870 lines
29 KiB
HTML
870 lines
29 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>Move Program Messages (QMHMOVPM) 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 cleanup completed 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>Move Program Messages (QMHMOVPM) API</h2>
|
|
|
|
<div class="box" style="width: 80%;">
|
|
<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">Message types</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Array of Char(10)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Number of message types</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">To call stack entry</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(*) or Pointer</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="left" valign="top">To call stack counter</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">6</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 1:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">7</td>
|
|
<td align="left" valign="top" width="50%">Length of to call stack entry</td>
|
|
<td align="left" valign="top" width="15%">Input</td>
|
|
<td align="left" valign="top" width="25%">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">To call stack entry qualification</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(20)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Optional Parameter Group 2:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">9</td>
|
|
<td align="left" valign="top" width="50%">To call stack entry data type</td>
|
|
<td align="left" valign="top" width="15%">Input</td>
|
|
<td align="left" valign="top" width="25%">Char(10)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">10</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">11</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 Move Program Message (QMHMOVPM) API moves messages from a call message
|
|
queue in the call stack to the call message queue of an earlier call stack
|
|
entry. Moving a message does not change the sender information stored with the
|
|
message. However, moving an escape message automatically changes it to a
|
|
diagnostic message.</p>
|
|
|
|
<p>You can use the QMHMOVPM API to pass messages up the call stack,
|
|
transferring important information to a previous program. When messages are
|
|
sent to a call stack entry and the program running in that entry ends without
|
|
moving its messages up the stack, the programs left in the stack cannot receive
|
|
those messages unless:</p>
|
|
|
|
<ul>
|
|
<li>They use the message key of those messages.</li>
|
|
|
|
<li>They use the List Job Log (QMHLJOBL) API.</li>
|
|
</ul>
|
|
|
|
<p>For example, assume a program is sent several diagnostic messages and one
|
|
escape message in response to an error. Another program earlier in the stack
|
|
can handle the error. If the first program uses the QMHMOVPM API to move all
|
|
the diagnostic messages to the program earlier in the stack, it then uses <a
|
|
href="QMHRSNEM.htm">Resend Escape Message</a> (QMHRSNEM) API to send the escape
|
|
message to the calling program.</p>
|
|
|
|
<p>In a multithreaded job, messages can be moved only from one call message
|
|
queue to another call message queue within the thread that calls this API.
|
|
Messages cannot be moved 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>When moving a single, specific message, use the key to that message for this
|
|
parameter. The key is assigned by the command or API that sends the
|
|
message.</p>
|
|
|
|
<p>When using the message types parameter to move a group of messages, use
|
|
blanks for this parameter.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Message types</strong></dt>
|
|
|
|
<dd>INPUT; ARRAY of CHAR(10)
|
|
|
|
<p>The type or types of the messages being moved.</p>
|
|
|
|
<p>When moving a group of messages, specify a list of one through four message
|
|
types. You can use these values in the list to move all messages of one or more
|
|
types:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*COMP</em></td>
|
|
<td align="left" valign="top">Completion</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DIAG</em></td>
|
|
<td align="left" valign="top">Diagnostic</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*ESCAPE</em></td>
|
|
<td align="left" valign="top">Escape. After an escape message is moved, its
|
|
message type changes to diagnostic.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*INFO</em></td>
|
|
<td align="left" valign="top">Informational</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>For descriptions of the message types, see <a href="term.htm#HDRMSGTYPE">
|
|
Message Types</a>.</p>
|
|
|
|
<p>If there are no messages of a type you specify, the QMHMOVPM API does not
|
|
return an error. It simply returns control to the calling program.</p>
|
|
|
|
<p>If the number of message types parameter specifies 0, this parameter is
|
|
ignored.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Number of message types</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>The number of message types specified in the message types parameter.</p>
|
|
|
|
<p>When moving a single message by specifying the message key in the message
|
|
key parameter, use 0 for the number of message types parameter.</p>
|
|
|
|
<p>If you use blanks for the message key parameter and specify one or more
|
|
message types, the value must be 1 through 4.</p>
|
|
</dd>
|
|
|
|
<dt><strong>To call stack entry</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*) OR POINTER
|
|
|
|
<p>The call stack entry to move 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. The call stack entry specified must be in the call stack;
|
|
you cannot specify the external message queue.</p>
|
|
|
|
<p>You can specify a call stack entry by:</p>
|
|
|
|
<ul>
|
|
<li>Providing the name of the OPM program or ILE procedure running in the
|
|
entry.</li>
|
|
|
|
<li>Providing a pointer to the call stack entry, or</li>
|
|
|
|
<li>Using one of the following special values:<br>
|
|
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*</em></td>
|
|
<td align="left" valign="top">The current call stack entry (that is, the one in
|
|
which the program or procedure using the API is running).<br>
|
|
<br>
|
|
</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 by providing a
|
|
program name in the optional To call stack entry qualification parameter. The
|
|
program object can be also be provided by not using the optional parameter or
|
|
by specifying *NONE for the program name. 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 using an OPM program name in this parameter. 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 of the program. 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).</p>
|
|
|
|
<p>For ILE service programs, this option can be used to identify the call stack
|
|
entry for the first procedure that was 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
|
|
using the API.
|
|
|
|
<p>If this keyword value is used and there is no control boundary in the
|
|
current call stack entry, the error CPF24C8 is returned to the user of this
|
|
API. This happens if the only entries on the call stack are for OPM
|
|
programs.</p>
|
|
|
|
<p>In some cases, *PGMBDY and *CTLBDY identify the same call stack entry. The
|
|
option *CTLBDY does not care if all call stack entries in a call sequence
|
|
involve the same program object. It only cares 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 align="left" valign="top"><em>*PGMNAME</em></td>
|
|
<td align="left" valign="top">The to call stack entry is identified by the
|
|
program name and, optionally, module name that is provided by the optional To
|
|
call stack entry qualification parameter.
|
|
|
|
<p>For OPM programs, specifying this special value and the optional parameter
|
|
is the same as specifying the OPM program name in this parameter.</p>
|
|
|
|
<p>For ILE programs or ILE service programs this special key value indicates
|
|
that a procedure name is not being specified. Rather the call stack entry is
|
|
identified by providing only the ILE program or service program name and
|
|
optionally the ILE module name. This means that the call stack entry is the
|
|
most recently called procedure that is part of the specified ILE program or ILE
|
|
service 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 special 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 ILE service program of the specified name, whichever occurs most
|
|
recently 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
|
|
the ILE program or service program and module. If a module name is given, the
|
|
call stack entry cannot be an OPM program.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>If the call stack entry is identified by pointer, the pointer specified must
|
|
address a valid call stack entry within the same job as the one the API is used
|
|
in. Alternatively, the pointer can be set to Null. The Optional Parameter Group
|
|
1 must be used and the Length of To call stack entry parameter must be set to
|
|
16. In addition, the Optional Parameter Group 2 must also be used and the Call
|
|
stack entry format parameter must be set to *PTR.</p>
|
|
|
|
<p>If the pointer provided is set to Null, this indicates that the call stack
|
|
entry is the one in which the API is being used.</p>
|
|
|
|
<p>If the pointer does not address a valid call stack entry or is not a Null
|
|
pointer, the error message CPF24C5 is sent to the user of the API.</p>
|
|
|
|
<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>Note:</strong> If the optional parameters Length of to call stack
|
|
entry and To call stack entry data type are not specified, this parameter is
|
|
assumed to be CHAR(10).</p>
|
|
</dd>
|
|
|
|
<dt><strong>To call stack counter</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>A number identifying the location in the call stack of the call stack entry
|
|
to whose message queue the messages are to be moved. The number is relative to
|
|
the call stack entry identified by the To call stack entry parameter. It
|
|
indicates how many calls up the call stack the target entry is from the one
|
|
identified by the To call stack entry parameter. 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">Move the messages to the message queue of the
|
|
entry specified by the to call stack entry parameter. You cannot use 0 when the
|
|
to call stack entry parameter specifies *, a Null pointer, or a pointer that
|
|
points to the user of the API. This combination means that you want to move the
|
|
message from yourself to yourself which is not a valid operation.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Move the messages to the message queue of the
|
|
call stack entry one earlier on the stack than the one identified by the To
|
|
call stack entry parameter.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>n (any positive<br>
|
|
number)</em></td>
|
|
<td align="left" valign="top">Move the messages to the queue of the nth call
|
|
stack entry earlier in the stack from the one identified by the To call stack
|
|
entry parameter.
|
|
|
|
<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>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Optional Parameter Group 1</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Length of to call stack entry</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>The length of the value for the to call stack entry parameter.</p>
|
|
|
|
<p>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>16 if the call stack entry parameter is a pointer.</li>
|
|
|
|
<li>1 to and including 4102 if partial name indicators are used.</li>
|
|
</ul>
|
|
|
|
<p><strong>Note:</strong> The actual length of the call stack entry name cannot
|
|
exceed 4096 characters. If this parameter is not used, the value for the call
|
|
stack entry parameter is assumed to be 10 characters in length.</p>
|
|
</dd>
|
|
|
|
<dt><strong>To call stack entry qualification</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(20)
|
|
|
|
<p>Further identifies 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 parameter are
|
|
used as a qualifier for the value provided in the To call stack entry
|
|
parameter. The values that can be specified here depend upon the value provided
|
|
in the To call stack entry parameter.</p>
|
|
|
|
<p>The special values discussed with this parameter can be used to indicate
|
|
that the module name qualifier or program name qualifier is not being
|
|
specified:</p>
|
|
|
|
<p>If the To call stack entry parameter contains an ILE procedure name then
|
|
this parameter can contain the name of the module and the ILE program to
|
|
further qualify the procedure name. The first 10 characters specify the module
|
|
name, and the second 10 characters specify the ILE program name. If this
|
|
parameter is not used or if *NONE is specified for both qualifiers, only the
|
|
specified procedure name is used to determine the call stack entry.</p>
|
|
|
|
<p>If the required To call stack entry parameter contains the key value
|
|
*PGMNAME, then the program name qualifier must contain either an OPM program
|
|
name or an ILE 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 parameter contains the special value * or
|
|
*CTLBDY, the Optional Parameter Group 1 should either not be used or both the
|
|
module name and program name qualifiers must be specified as *NONE.</p>
|
|
|
|
<p>When the To call stack entry parameter contains an OPM program name, the
|
|
Optional Parameter Group 1 should also either not be used or 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 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 special value *PGMBDY is used, the Optional Parameter Group 1 may
|
|
be used. In this case, the module name qualifier must be specified as *NONE.
|
|
For the program name qualifier, an OPM or ILE program name may be specified or
|
|
*NONE may be used.</p>
|
|
|
|
<p>If the To call stack entry is identified by pointer, this parameter must
|
|
still be passed to the API. The value specified for the module name qualifier
|
|
must be specified as *NONE. The program name qualifier serves as a qualifier
|
|
for the pointer and must be specified as 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">The call stack entry addressed by the pointer is
|
|
the one to which the message is to be moved or the one to start counting from
|
|
when using a value other than 0 for the To call stack counter parameter.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>*PGMBDY</em></td>
|
|
<td valign="top">The call stack entry to move 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
|
|
than 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>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Optional Parameter Group 2</h3>
|
|
|
|
<p>Use these optional parameters when:</p>
|
|
|
|
<ul>
|
|
<li>The call stack entry to which the messages are to be moved is identified by
|
|
a pointer.</li>
|
|
|
|
<li>The messages to be moved are not on the current call stack entry's message
|
|
queue.</li>
|
|
</ul>
|
|
|
|
<dl>
|
|
<dt><strong>To call stack entry data type</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(10)
|
|
|
|
<p>Whether the value of the To call stack entry parameter is a character string
|
|
(a name or special value) or a pointer.</p>
|
|
|
|
<p>Use one of the following special values;</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*CHAR</em></td>
|
|
<td align="left" valign="top">Value of the parameter is a character string
|
|
(name or special value)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*PTR</em></td>
|
|
<td align="left" valign="top">Value of the parameter is a pointer.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If the above optional parameter is not specified, it is assumed that the
|
|
value of the To call stack entry parameter is a character string.</p>
|
|
</dd>
|
|
|
|
<dt><strong>From call stack entry address</strong></dt>
|
|
|
|
<dd>INPUT CHAR(16) OR POINTER
|
|
|
|
<p>A pointer to the call stack entry where the messages to be moved exist 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 program languages that do not support pointers, a Null pointer can be
|
|
presented by using a 16 byte variable. The first byte of the variable is set to
|
|
the special value * and the remaining 15 bytes set to blanks.</p>
|
|
|
|
<p>If the pointer provided is set to Null, this indicates the current call
|
|
stack entry (the one using the API).</p>
|
|
|
|
<p>If the pointer is not a valid pointer or if it is a valid pointer but is not
|
|
Null nor does it 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
|
|
where the messages to be moved exist. The number is relative to the To call
|
|
stack entry that is addressed by the From call stack entry address pointer. It
|
|
indicates how many calls up 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 move exists at the call stack
|
|
entry that is addressed by the pointer.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">The message to move exists at the call stack
|
|
entry that is one earlier in the call stack than the one addressed by the
|
|
pointer.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>n (any positive number)</em></td>
|
|
<td align="left" valign="top">The message to move 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>
|
|
|
|
<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>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Messages</h3>
|
|
|
|
<table width="100%" cellpadding="5">
|
|
<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">CPF24A5 E</td>
|
|
<td align="left" valign="top">Value of &1, for number of message types, not
|
|
valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24BF E</td>
|
|
<td align="left" valign="top">Module or bound-program name is blank.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24B3 E</td>
|
|
<td align="left" valign="top">Message type &1 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">CPF24B5 E</td>
|
|
<td align="left" valign="top">Not able to move message.</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">CPF24C5 E</td>
|
|
<td align="left" valign="top">Pointer to call stack entry not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24C6 E</td>
|
|
<td align="left" valign="top">Value of To call stack entry data type parameter
|
|
not valid.</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">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">CPF241B E</td>
|
|
<td align="left" valign="top">Message type &1 in system program is not
|
|
valid.</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">CPF247A E</td>
|
|
<td align="left" valign="top">Call stack entry not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF2471 E</td>
|
|
<td align="left" valign="top">Length of field not valid.</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">CPF2508 E</td>
|
|
<td align="left" valign="top">Cannot move messages to same or later call stack
|
|
entry.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF2509 E</td>
|
|
<td align="left" valign="top">Message key &2 refers to a message that is
|
|
not on the mover's call stack entry.</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">CPF3CF1 E</td>
|
|
<td align="left" valign="top">Error code parameter 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">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>
|
|
|