857 lines
30 KiB
HTML
857 lines
30 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
<html>
|
||
|
<head>
|
||
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
<title>Resend Escape Message (QMHRSNEM) API</title>
|
||
|
<!-- Begin Header Records ========================================== -->
|
||
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
<!-- US Government Users Restricted Rights -->
|
||
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
<!-- MH1TEMP SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
||
|
<!-- RCHVMW2 on 26 Jan 1999 at 10:37:34 -->
|
||
|
<!-- Change History: -->
|
||
|
<!-- YYMMDD USERID Change description -->
|
||
|
<!--File Edited Sept 2001 by v2cdijab -->
|
||
|
<!--End Header Records -->
|
||
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
</head>
|
||
|
<body>
|
||
|
<a name="Top_Of_Page"></a>
|
||
|
<!-- Java sync-link -->
|
||
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
||
|
</script>
|
||
|
|
||
|
<h2>Resend Escape Message (QMHRSNEM) API</h2>
|
||
|
|
||
|
<div class="box" style="width: 75%;">
|
||
|
<br>
|
||
|
Required Parameter Group:<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
<table width="100%">
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">1</td>
|
||
|
<td align="left" valign="top" width="50%">Message key</td>
|
||
|
<td align="left" valign="top" width="15%">Input</td>
|
||
|
<td align="left" valign="top" width="25%">Char(4)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">2</td>
|
||
|
<td align="left" valign="top">Error code</td>
|
||
|
<td align="left" valign="top">I/O</td>
|
||
|
<td align="left" valign="top">Char(*)</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
Optional Parameter Group:<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
<table width="100%">
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">3</td>
|
||
|
<td align="left" valign="top" width="50%">To call stack entry</td>
|
||
|
<td align="left" valign="top" width="15%">Input</td>
|
||
|
<td align="left" valign="top" width="25%">CHAR(*)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">4</td>
|
||
|
<td align="left" valign="top">To call stack entry length</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">5</td>
|
||
|
<td align="left" valign="top">Format of to call stack entry parameter</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">Char(8)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">6</td>
|
||
|
<td align="left" valign="top">From call stack entry address</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">CHAR(16) or Pointer</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">7</td>
|
||
|
<td align="left" valign="top">From call stack counter</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
Default Public Authority: *USE<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
Threadsafe: Yes<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
</div>
|
||
|
|
||
|
<p>The Resend Escape Message (QMHRSNEM) API resends an escape message from the
|
||
|
current call stack entry to the previous call stack entry in the call stack or
|
||
|
to any call stack entry that is earlier if the optional parameters are used.
|
||
|
This API can also be used to resend an escape message from a call stack entry
|
||
|
other than the current one.</p>
|
||
|
|
||
|
<p>You can use this API along with the Move Program Messages (QMHMOVPM) API to
|
||
|
streamline exception message handling. If a call stack entry is sent diagnostic
|
||
|
messages and an escape message but cannot handle the error itself, you can use
|
||
|
the QMHMOVPM API to move the diagnostic messages. You can use the QMHRSNEM API
|
||
|
to forward the escape message to the previous call stack entry in the call
|
||
|
stack. The call stack entry does not need to send an escape message of its own.
|
||
|
For details about the QMHMOVPM API, see <a href="qmhmovpm.htm">Move Program
|
||
|
Messages</a> (QMHMOVPM) API.</p>
|
||
|
|
||
|
<p>In a multithreaded job messages can be resent only from one call message
|
||
|
queue to another call message queue within the thread that calls this API.
|
||
|
Messages cannot be resent to a call stack entry in another thread.</p>
|
||
|
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3>Authorities and Locks</h3>
|
||
|
|
||
|
<p>None.</p>
|
||
|
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3>Required Parameter Group</h3>
|
||
|
|
||
|
<dl>
|
||
|
<dt><strong>Message key</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(4)
|
||
|
|
||
|
<p>The key to the escape message being resent. The key is assigned by the
|
||
|
command or API that first sends the message.</p>
|
||
|
|
||
|
<p>To resend the last new escape message, use blanks for this parameter.</p>
|
||
|
|
||
|
<p>A message is new until it is received. It then becomes an old message. You
|
||
|
can resend an old message only if you specify the message key.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Error code</strong></dt>
|
||
|
|
||
|
<dd>I/O; CHAR(*)
|
||
|
|
||
|
<p>The structure in which to return error information. For the format of the
|
||
|
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
|
||
|
</dd>
|
||
|
</dl>
|
||
|
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3>Optional Parameter Group</h3>
|
||
|
|
||
|
<p>Use these optional parameters if the call stack entry, to which the message
|
||
|
is to be resent, is not just previous to the one that is using this API. Use
|
||
|
these optional parameters also when the message to resend is not on the current
|
||
|
call stack entry's message queue.</p>
|
||
|
|
||
|
<dl>
|
||
|
<dt><strong>To call stack entry</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(*)
|
||
|
|
||
|
<p>A structure that contains the information that this API will use to
|
||
|
determine the call stack entry to resend the message to. The structure can be
|
||
|
in one of two formats; RSNM0100 or RSNM0200.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>To call stack entry length</strong></dt>
|
||
|
|
||
|
<dd>INPUT; BINARY(4)
|
||
|
|
||
|
<p>The length of the To call stack entry parameter. The length specified here
|
||
|
must be at least large enough to hold the specified format of the To call stack
|
||
|
entry parameter. It may be larger. In case it is larger, the structure must be
|
||
|
left justified in the area. If the length specified by this parameter is not
|
||
|
adequate for the format being used, error CPF24C7 is sent to the caller of this
|
||
|
API.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Format of to call stack entry parameter</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(8)
|
||
|
|
||
|
<p>The format of the to call stack entry parameter. Use one of the following
|
||
|
format names:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>RSNM0100</em></td>
|
||
|
<td align="left" valign="top">The To call stack entry parameter is in the
|
||
|
RSNM0100 format. This format is used when the to call stack entry is identified
|
||
|
by name or by special value.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>RSNM0200</em></td>
|
||
|
<td align="left" valign="top">The To call stack entry parameter is in the
|
||
|
RSNM0200 format. This format is used when the call stack entry is identified by
|
||
|
a pointer.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>From call stack entry address</strong></dt>
|
||
|
|
||
|
<dd>INPUT; Pointer or CHAR(16)
|
||
|
|
||
|
<p>A pointer to the call stack entry where the escape message to resend exists
|
||
|
or the call stack entry to start counting from if the From call stack counter
|
||
|
is not 0.</p>
|
||
|
|
||
|
<p>The pointer that is specified must be an invocation pointer that addresses a
|
||
|
valid call stack entry or must be set to Null.</p>
|
||
|
|
||
|
<p>For programming languages that do not support pointers, a Null pointer can
|
||
|
be represented by a 16 byte variable in which the first byte is set to the
|
||
|
special value '*' and the remaining 15 bytes are set to blanks.</p>
|
||
|
|
||
|
<p>If the pointer provided is set to Null, this indicates the current call
|
||
|
stack entry.</p>
|
||
|
|
||
|
<p>If the pointer is not Null or it does not address a valid call stack entry,
|
||
|
the error message CPF24C5 is sent to the user of the API.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>From call stack counter</strong></dt>
|
||
|
|
||
|
<dd>INPUT; BINARY(4)
|
||
|
|
||
|
<p>A number identifying the location in the call stack of the call stack entry
|
||
|
from where the message is to be resent. The number is relative to the from call
|
||
|
stack entry that is addressed by the pointer. It indicates how many calls
|
||
|
earlier in the call stack the entry is from the one that is addressed by the
|
||
|
pointer. Valid values follow:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">The message to resend exists at the call stack
|
||
|
entry that is addressed by the pointer.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
<td align="left" valign="top">The message to resend exists at the call stack
|
||
|
entry that is one earlier in the call stack than the one addressed by the
|
||
|
pointer.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>n (any positive number)</em></td>
|
||
|
<td align="left" valign="top">The message to resend exists at the nth call
|
||
|
stack entry earlier in the stack from the one addressed by the pointer.
|
||
|
|
||
|
<p>You can use any positive number that does not exceed the actual number of
|
||
|
call stack entries in the call stack. Do not include the external message queue
|
||
|
in your count.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
</dd>
|
||
|
</dl>
|
||
|
|
||
|
<h3>RSNM0100 Format</h3>
|
||
|
|
||
|
<p>The following table shows the structure of the To call stack entry parameter
|
||
|
when the RSNM0100 format is used. This format is used when the to call stack
|
||
|
entry is identified by name or by special value.</p>
|
||
|
|
||
|
<p>The information passed in the RSNM0100 format is described in <a href=
|
||
|
"#HDRFDD">Field Descriptions</a>.</p>
|
||
|
|
||
|
<table border width="80%">
|
||
|
<tr>
|
||
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<th align="center" valign="bottom">Dec</th>
|
||
|
<th align="center" valign="bottom">Hex</th>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
<td align="left" valign="top" width="60%">To call stack counter</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">4</td>
|
||
|
<td align="center" valign="top">4</td>
|
||
|
<td align="left" valign="top">CHAR(20)</td>
|
||
|
<td align="left" valign="top">To call stack entry qualification</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">24</td>
|
||
|
<td align="center" valign="top">18</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Length of to call stack entry identifier</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">28</td>
|
||
|
<td align="center" valign="top">1C</td>
|
||
|
<td align="left" valign="top">CHAR(*)</td>
|
||
|
<td align="left" valign="top">To call stack entry identifier</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3>RSNM0200 Format</h3>
|
||
|
|
||
|
<p>The following table shows the structure of the To call stack entry parameter
|
||
|
when the RSNM0200 format is used. This format is used when the to call stack
|
||
|
entry is identified by a pointer.</p>
|
||
|
|
||
|
<p>The information passed in the RSNM0200 format is described in <a href=
|
||
|
"#HDRFDD">Field Descriptions</a>.</p>
|
||
|
|
||
|
<table border width="80%">
|
||
|
<tr>
|
||
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<th align="center" valign="bottom">Dec</th>
|
||
|
<th align="center" valign="bottom">Hex</th>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
<td align="left" valign="top" width="20%">Pointer</td>
|
||
|
<td align="left" valign="top" width="60%">To call stack entry address</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">16</td>
|
||
|
<td align="center" valign="top">10</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">To call stack counter</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">20</td>
|
||
|
<td align="center" valign="top">14</td>
|
||
|
<td align="left" valign="top">CHAR(10)</td>
|
||
|
<td align="left" valign="top">Pointer qualifier</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3><a name="HDRFDD">Field Descriptions</a></h3>
|
||
|
|
||
|
<p><strong>Length of the to call stack entry identifier.</strong> The length of
|
||
|
the To call stack entry identifier. Valid values for this parameter are as
|
||
|
follows:</p>
|
||
|
|
||
|
<ul>
|
||
|
<li>1 to and including 4096 if partial name indicators are not used.</li>
|
||
|
|
||
|
<li>1 to and including 4102 is partial name indicators are used.</li>
|
||
|
</ul>
|
||
|
|
||
|
<p><strong>Note:</strong> The actual length of the call stack entry name cannot
|
||
|
exceed 4096.</p>
|
||
|
|
||
|
<p><strong>Pointer qualifier.</strong></p>
|
||
|
|
||
|
<p>Specify one of the following special values:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*NONE</em></td>
|
||
|
<td align="left" valign="top">Specify this special value if the call stack
|
||
|
entry addressed by the pointer is the one to which the message is to be resent
|
||
|
or the one to start counting from when using a value other than 0 for the To
|
||
|
call stack counter parameter.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*PGMBDY</em></td>
|
||
|
<td align="left" valign="top">Specify this special value if call stack entry to
|
||
|
resend the message to or to start counting from is an ILE program boundary. The
|
||
|
ILE program is the one which contains the procedure that is running in the call
|
||
|
stack entry addressed by the pointer.
|
||
|
|
||
|
<p>If the ILE program was called using a dynamic call, using this special value
|
||
|
with a pointer will identify the call stack entry for the PEP of that program.
|
||
|
If a call was made using a procedure pointer, it will identify the call stack
|
||
|
entry for the procedure that was pointed to.</p>
|
||
|
|
||
|
<p>If the pointer addresses a call stack entry that is running a procedure from
|
||
|
an ILE service program, this option can be used to identify the call stack
|
||
|
entry for the first procedure that was called in that service program.</p>
|
||
|
|
||
|
<p>If the call stack entry addressed by the pointer is running an OPM program,
|
||
|
using the special value *PGMBDY here will have the same effect as using *NONE
|
||
|
in most cases. A difference will occur if the OPM program called itself
|
||
|
recursively. In this case using *PGMBDY identifies the first recursion level
|
||
|
while *NONE identifies the current recursion level.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>To call stack counter.</strong> A number identifying the location in
|
||
|
the call stack of the call stack entry to which the message is to be resent.
|
||
|
The number is relative to the call stack entry identified by the To call stack
|
||
|
entry identifier field. It indicates how many calls up the call stack the
|
||
|
target entry is from the one specified in the To call stack entry identifier
|
||
|
field. Valid values follow:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">Resend the message to the message queue of call
|
||
|
stack entry specified by the To call stack entry identifier field. You cannot
|
||
|
use 0 when the To call stack identifier field specifies * to designate the
|
||
|
current call stack entry.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
<td align="left" valign="top">Resend the message to the message queue of the
|
||
|
call stack entry that is one earlier in the call stack than the one identified
|
||
|
by the To call stack entry identifier field.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>n (any positive number)</em></td>
|
||
|
<td align="left" valign="top">Resend the message to the queue of the nth call
|
||
|
stack entry earlier in the stack from the one specified in the to call stack
|
||
|
entry field.
|
||
|
|
||
|
<p>You can use any positive number that does not exceed the actual number of
|
||
|
call stack entries in the call stack. Do not include the external message queue
|
||
|
in your count.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p>The From call stack entry cannot be the same as the To call stack entry.
|
||
|
Additionally, the To call stack entry must be earlier on the call stack than
|
||
|
the From call stack entry.</p>
|
||
|
|
||
|
<p><strong>To call stack entry address.</strong> A pointer to the call stack
|
||
|
entry to resend the messages to, or the call stack entry to start counting from
|
||
|
when using a value other than 0 for the To call stack counter parameter.</p>
|
||
|
|
||
|
<p>The pointer that is specified must be an invocation pointer that addresses a
|
||
|
valid call stack entry or must be set to Null.</p>
|
||
|
|
||
|
<p>If the pointer provided is Null, this indicates the current call stack
|
||
|
entry. If a Null pointer is provided, the To call stack counter parameter must
|
||
|
be specified as a non-zero value.</p>
|
||
|
|
||
|
<p>If the pointer provided is not Null and does not address a valid call stack
|
||
|
entry, the error message CPF24C5 is sent to the user of the API.</p>
|
||
|
|
||
|
<p><strong>To call stack entry identifier.</strong> An identification of the
|
||
|
call stack entry to resend the message to or the call stack entry to start
|
||
|
counting from when using a value other than 0 for the To call stack counter
|
||
|
parameter. The call stack entry identified by this field must be in the call
|
||
|
stack, and you cannot specify the external message queue.</p>
|
||
|
|
||
|
<p>You can identify the To call stack entry by providing the name of the OPM
|
||
|
program or ILE procedure running in the entry or by using one of the following
|
||
|
special values:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*</em></td>
|
||
|
<td align="left" valign="top">The call stack entry of the program or procedure
|
||
|
using the API.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*PGMBDY</em></td>
|
||
|
<td align="left" valign="top">The call stack entry is for the boundary of the
|
||
|
specified program object. The program object is specified explicitly by
|
||
|
providing a program name in the To call stack entry qualification field. The
|
||
|
program object can be implicitly specified by specifying the program name
|
||
|
qualification as *NONE. In this case, the program object is assumed to be the
|
||
|
program that is using the API.
|
||
|
|
||
|
<p>This option essentially identifies the oldest call stack entry which began a
|
||
|
sequence of calls, where each call in this sequence involved the same program
|
||
|
object. The call sequence could involve recursive calls to the same program or,
|
||
|
in the case of ILE, calls to different procedures of the same ILE program or
|
||
|
ILE service program.</p>
|
||
|
|
||
|
<p>For OPM programs, in most cases using *PGMBDY produces the same result as
|
||
|
using * or an OPM program name directly in this field. A difference will appear
|
||
|
when an OPM program calls itself recursively. In this case, using * or an OPM
|
||
|
program name identifies the current recursion level. In contrast, using *PGMBDY
|
||
|
identifies the first recursion level.</p>
|
||
|
|
||
|
<p>For an ILE program, this option can be used to identify the first procedure
|
||
|
of the ILE program that was called in the current sequence. If the ILE program
|
||
|
was called using a dynamic call, this is the PEP (program entry procedure) of
|
||
|
the ILE program. If sequence was started by calling using a procedure pointer,
|
||
|
this is the call stack entry for the procedure that was pointed to.</p>
|
||
|
|
||
|
<p>For ILE service programs, this special value can be used to specify the call
|
||
|
stack entry for the first procedure called in the identified service
|
||
|
program.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*CTLBDY</em></td>
|
||
|
<td align="left" valign="top">The call stack entry at the most recent control
|
||
|
boundary. This call stack entry is in the same activation group as the one that
|
||
|
is using the API.
|
||
|
|
||
|
<p>If this key word value is used and there is no control boundary in the
|
||
|
current call stack, the error CPF24C8 is returned to the user of this API. This
|
||
|
would happen if the only entries on the call stack are for OPM programs.</p>
|
||
|
|
||
|
<p>Note that in some cases, *PGMBDY and *CTLBDY will identify the same call
|
||
|
stack entry but not in all cases. The option *CTLBDY does not care if all call
|
||
|
stack entries in a call sequence involve the same program object. It cares only
|
||
|
that a sequence started at a control boundary. Conversely, the start of a call
|
||
|
sequence identified by *PGMBDY may not fall on a control boundary.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td valign="top"><em>*PGMNAME</em></td>
|
||
|
<td valign="top">The call stack entry is identified entirely by the program
|
||
|
name and optionally module name that is provided in the To call stack entry
|
||
|
qualification field.
|
||
|
|
||
|
<p>For OPM programs, specifying this special value here and the program name in
|
||
|
the To call stack entry qualification field produces the same results as if the
|
||
|
program name had been specified directly here.</p>
|
||
|
|
||
|
<p>For ILE programs or service programs, this special value is used to indicate
|
||
|
that a procedure name is not being specified. Rather the call stack entry is
|
||
|
identified by providing only the ILE program name or ILE service program name
|
||
|
and optionally the ILE module name. This means that the call stack entry will
|
||
|
be the most recently called procedure that is part of the specified ILE program
|
||
|
(and part of the ILE module if module name is also specified). The name of this
|
||
|
most recently called procedure is not important in determining the correct call
|
||
|
stack entry.</p>
|
||
|
|
||
|
<p>If this key value is specified with a program name only, then the call stack
|
||
|
entry is the most recently called OPM program that has the specified program
|
||
|
name or the most recently called ILE procedure that is part of an ILE program
|
||
|
or service program of the specified name, whichever is the most recent on the
|
||
|
call stack. If the module name is also specified, then the call stack entry is
|
||
|
the most recently called ILE procedure that is part of specified ILE program or
|
||
|
service program and module. If module name is given then the call stack entry
|
||
|
cannot be an OPM program.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p>The call stack entry can be a nested procedure name from 1 through 4096
|
||
|
characters in length. When specifying nested procedures, each procedure name
|
||
|
must be separated by a colon, and the outermost procedure is identified first
|
||
|
followed by the procedures it contains. The innermost procedure is the last
|
||
|
procedure identified in the string.</p>
|
||
|
|
||
|
<p>The call stack entry can be a partial name. To specify a partial name, place
|
||
|
three less-than signs (<<<) at the beginning of the call stack entry
|
||
|
identifier, or place three greater-than signs (>>>) at the end of the
|
||
|
call stack entry identifier, or place both the less-than signs and the
|
||
|
greater-than signs at their respective ends of the call stack entry identifier.
|
||
|
The value for the call stack entry excluding the less-than signs and the
|
||
|
greater-than signs is used to search backward through the stack for the
|
||
|
requested call stack entry name.</p>
|
||
|
|
||
|
<p>When searching for a partial call stack entry name:</p>
|
||
|
|
||
|
<ul>
|
||
|
<li>If the less-than signs (<<<) are specified only at the beginning
|
||
|
of the call stack entry name, the less-than signs are truncated and the
|
||
|
remaining character string is right-justified. The remaining string is then
|
||
|
compared to the current call stack entry on the call stack. The comparison
|
||
|
starts at the end of the call stack entry name and backwardly compares the
|
||
|
number of characters in the specified string.<br>
|
||
|
<br>
|
||
|
</li>
|
||
|
|
||
|
<li>If the greater-than signs (>>>) are specified only at the end of
|
||
|
the call stack entry name, the greater-than signs are truncated. The remaining
|
||
|
character string is compared to the current call stack entry on the call stack.
|
||
|
The comparison starts at position 1 of the call stack entry name and compares
|
||
|
the number of characters in the specified string.<br>
|
||
|
<br>
|
||
|
</li>
|
||
|
|
||
|
<li>If the less-than signs (<<<) are specified at the beginning of the
|
||
|
call stack entry name and the greater-than signs (>>>) are specified
|
||
|
at the end of the call stack entry name, both the less-than signs and the
|
||
|
greater-than signs are truncated. The remaining characters are used to scan and
|
||
|
to compare the entire length of the specified string and the current call stack
|
||
|
entry on the call stack.</li>
|
||
|
</ul>
|
||
|
|
||
|
<p><strong>To call stack entry qualification.</strong> This field is used when
|
||
|
it is necessary to further identify the To call stack entry. The parameter
|
||
|
consists of two 10 character parts. The first part is the module name qualifier
|
||
|
and the second part is the program name qualifier. The values provided in this
|
||
|
field are used as a qualifier for the value provided in the To call stack entry
|
||
|
identifier field. The values that can be specified here depend upon the value
|
||
|
provided as the To call stack entry identifier.</p>
|
||
|
|
||
|
<p>The following special value may be used to indicate that the module name
|
||
|
qualifier or program name qualifier is not being specified:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="10 90" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*NONE</em></td>
|
||
|
<td align="left" valign="top">This value can be used for the value of the
|
||
|
module name qualifier, program name qualifier, or both to indicate that no
|
||
|
qualifier is being specified.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p>If the To call stack entry identifier field contains an ILE procedure name
|
||
|
then this field can contain the name of the module and program that the
|
||
|
procedure was compiled and bound into. The module and program name qualifiers
|
||
|
are used to distinguish the correct call stack entry in the case where
|
||
|
different procedures of the same name are on the call stack at the same time.
|
||
|
The first 10 characters specify the module name, and the second 10 characters
|
||
|
specify the ILE program name or ILE Service program name. If *NONE is specified
|
||
|
for both the module and program name qualifiers, only the specified procedure
|
||
|
name is used to determine the call stack entry.</p>
|
||
|
|
||
|
<p>If the To call stack entry identifier field contains the special value
|
||
|
*PGMNAME than the program name qualifier must contain either an OPM program
|
||
|
name or an ILE program or Service program name. For ILE, the module name
|
||
|
qualifier may contain a module name; otherwise it must contain *NONE.</p>
|
||
|
|
||
|
<p>When the To call stack entry identifier field contains the special value *
|
||
|
or *CTLBDY, both the module name qualifier and program name qualifier must be
|
||
|
specified as *NONE.</p>
|
||
|
|
||
|
<p>When the To call stack entry identifier field contains an OPM program name,
|
||
|
both the module name and program name qualifiers should be specified as *NONE.
|
||
|
If a module name or program name is specified here, the name specified as the
|
||
|
To call stack entry identifier is interpreted as an ILE procedure name rather
|
||
|
than an OPM program name. Either the entry would not be found or an incorrect
|
||
|
entry would be found.</p>
|
||
|
|
||
|
<p>When the To call stack entry identifier field contains the special value
|
||
|
*PGMBDY, the module name qualifier must be specified as *NONE. For the program
|
||
|
name qualifier, an OPM, ILE program, or ILE Service program name may be
|
||
|
specified or *NONE may be used.</p>
|
||
|
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3>Error Messages</h3>
|
||
|
|
||
|
<table width="100%" cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<th align="left" valign="top">Message ID</th>
|
||
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top" width="15%">CPF24A3 E</td>
|
||
|
<td align="left" valign="top" width="85%">Value for call stack counter
|
||
|
parameter not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24B4 E</td>
|
||
|
<td align="left" valign="top">Severe error while addressing parameter
|
||
|
list.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24B7 E</td>
|
||
|
<td align="left" valign="top">Value &1 for call stack entry name length not
|
||
|
valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24B9 E</td>
|
||
|
<td align="left" valign="top">When call stack entry name is '*' or '*CTLBDY',
|
||
|
module name and program name must be '*NONE'.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24BC E</td>
|
||
|
<td align="left" valign="top">No escape message to resend.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24C5 E</td>
|
||
|
<td align="left" valign="top">Pointer to call stack entry not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24C7 E</td>
|
||
|
<td align="left" valign="top">The length &1 is not valid when the specified
|
||
|
format is &2.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24C8 E</td>
|
||
|
<td align="left" valign="top">Control boundary not found on call stack.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24C9 E</td>
|
||
|
<td align="left" valign="top">Program boundary not found on call stack.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24CA E</td>
|
||
|
<td align="left" valign="top">Call stack entry is not valid to resend
|
||
|
message.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24CB E</td>
|
||
|
<td align="left" valign="top">*PGMNAME requires a specified program name.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24CC E</td>
|
||
|
<td align="left" valign="top">Call stack entry &2 for *PGMNAME not
|
||
|
found.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24CD E</td>
|
||
|
<td align="left" valign="top">Module name cannot be specified when *PGMBDY is
|
||
|
used.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24CE E</td>
|
||
|
<td align="left" valign="top">Qualifier &1 incorrect for use with
|
||
|
pointer.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24CF E</td>
|
||
|
<td align="left" valign="top">Pointer qualifier &1 incorrect for use with
|
||
|
pointer.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2410 E</td>
|
||
|
<td align="left" valign="top">Message key not found in message queue
|
||
|
&1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF246A E</td>
|
||
|
<td align="left" valign="top">Destination call stack entry not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF247A E</td>
|
||
|
<td align="left" valign="top">Call stack entry not found.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2479 E</td>
|
||
|
<td align="left" valign="top">Call stack entry not found.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2524 E</td>
|
||
|
<td align="left" valign="top">Exception handler not available because of reason
|
||
|
code &1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2550 E</td>
|
||
|
<td align="left" valign="top">Exception message sent to a deleted program or
|
||
|
procedure.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF3CF1 E</td>
|
||
|
<td align="left" valign="top">Error code parameter not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF3C21 E</td>
|
||
|
<td align="left" valign="top">Format name &1 is not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF3C36 E</td>
|
||
|
<td align="left" valign="top">Number of parameters, &1, entered for this
|
||
|
API was not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF3C90 E</td>
|
||
|
<td align="left" valign="top">Literal value cannot be changed.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
<td align="left" valign="top">Program or service program &1 in library
|
||
|
&2 ended. Reason code &3.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<hr>
|
||
|
API introduced: V2R1.1
|
||
|
|
||
|
<hr>
|
||
|
<center>
|
||
|
<table cellpadding="2" cellspacing="2">
|
||
|
<tr align="center">
|
||
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
"mh1.htm">Message Handling APIs</a> | <a href="aplist.htm">APIs by
|
||
|
category</a></td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
</center>
|
||
|
</body>
|
||
|
</html>
|
||
|
|