friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
0332907f0f
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/QMHSNDPM.htm

1287 lines
44 KiB
HTML
Raw Blame History

<!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>Send Program Message (QMHSNDPM) 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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- MH1TEMP SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
<!-- RCHVMW2 on 26 Jan 1999 at 10:37:34 -->
<!--File Edited Oct 2001 by v2cdijab -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>Send Program Message (QMHSNDPM) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Required Parameters 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 identifier</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="25%">Char(7)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Qualified message file name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Message data or immediate text</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Length of message data or immediate text</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">Message type</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">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">7</td>
<td align="left" valign="top">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">8</td>
<td align="left" valign="top">Message key</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(4)</td>
</tr>
<tr>
<td align="center" valign="top">9</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>
&nbsp;&nbsp;Optional Parameter Group 1:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">10</td>
<td align="left" valign="top" width="50%">Length of 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">11</td>
<td align="left" valign="top">Call stack entry qualification</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="left" valign="top">Display program messages screen wait time</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group 2:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">13</td>
<td align="left" valign="top" width="50%">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">14</td>
<td align="left" valign="top">Coded character set identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Send Program Message (QMHSNDPM) API sends a message to a call message
queue or the external message queue. (The external message queue is the part of
the job message queue that handles messages between an interactive job and the
work station user. It is not associated with a specific call stack entry.) This
API allows the current call stack entry to send a message to its caller, a
previous caller, or itself.</p>
<p>In a multithreaded job, messages can be sent only to call message queues in
the thread in which this API is called or to the external message queue.
Messages cannot be sent to call message queues in other threads.</p>
<p>To send a message to a nonprogram message queue, see <a href="QMHSNDM.htm">
Send Nonprogram Message</a> (QMHSNDM) API.</p>
<p>Before coding your call to the QMHSNDPM API, see <a href="#HDRALLPAR">
Dependencies among Parameters</a>.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Message File Authority</em></dt>
<dd>*USE</dd>
<dt><em>Message File Library Authority</em></dt>
<dd>*EXECUTE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Message identifier</strong></dt>
<dd>INPUT; CHAR(7)
<p>The identifying code for the predefined message being sent, or blanks for an
immediate message.</p>
<p>When sending an escape, notify, or status message, you must specify a
message identifier. When sending a request
<img src="v5r4adelta.gif" alt="Start of change">or command
<img src="v5r4adeltaend.gif" alt="End of change">
message, you must use blanks. When
sending other types of messages, you can use either a message identifier or
blanks.</p>
<p>If you specify a message identifier, you must specify a qualified message
file name. If you do not specify a message identifier, the API ignores the
qualified message file name parameter.</p>
</dd>
<dt><strong>Qualified message file name</strong></dt>
<dd>INPUT; CHAR(20)
<p>For a predefined message, the name of the message file and the library in
which it resides. The first 10 characters specify the file name, and the second
10 characters specify the library. You can use these special values for the
library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<p>For an immediate message, use blanks for this parameter. If you specify a
name, the API ignores it and does not return an error.</p>
</dd>
<dt><strong>Replacement data or impromptu message text</strong></dt>
<dd>INPUT; CHAR(*)
<p>If a message identifier is specified, this parameter specifies the data to
insert in the predefined message's substitution variables. If blanks are used
for the message identifier, this parameter specifies the complete text of an
immediate message.</p>
<p>If this parameter contains pointer data, each pointer must start on a
16-byte boundary to keep the data accurate.</p>
</dd>
<dt><strong>Length of replacement data or impromptu message text</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the replacement data or impromptu message text, in bytes.
Valid values for each are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>Message data</em></td>
<td align="left" valign="top">0-32767</td>
</tr>
<tr>
<td align="left" valign="top"><em>Immediate text</em></td>
<td align="left" valign="top">1-6000</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Message type</strong></dt>
<dd>INPUT;CHAR(10)
<p>The type of the message. You must specify one of these values:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em><img src="v5r4adelta.gif" alt="Start of change">*CMD</em></td>
<td align="left" valign="top">Command<img src="v5r4adeltaend.gif" alt="End of change"></td>
</tr>
<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</td>
</tr>
<tr>
<td align="left" valign="top"><em>*INFO</em></td>
<td align="left" valign="top">Informational</td>
</tr>
<tr>
<td align="left" valign="top"><em>*INQ</em></td>
<td align="left" valign="top">Inquiry. You can send inquiry messages only to the
external message queue.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NOTIFY</em></td>
<td align="left" valign="top">Notify</td>
</tr>
<tr>
<td align="left" valign="top"><em>*RQS</em></td>
<td align="left" valign="top">Request</td>
</tr>
<tr>
<td align="left" valign="top"><em>*STATUS</em></td>
<td align="left" valign="top">Status</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Call stack entry</strong></dt>
<dd>INPUT; CHAR(*) or Pointer
<p>The call stack entry to send the message to, or the call stack entry to
start counting from when using a value other than 0 for the Call stack counter
parameter. The call stack entry you specify must be in the call stack. You can
also specify the external message queue.</p>
<p>You can specify a call stack entry by providing the name of the OPM program
or ILE procedure running in the entry, by providing a pointer to the call stack
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 current call stack entry (that is, the one in
which the program or procedure is using this API is running).</td>
</tr>
<tr>
<td align="left" valign="top"><em>*PGMBDY</em></td>
<td align="left" valign="top">The call stack is for the boundary of the
specified program object. The program object is identified explicitly by
providing a program name in the optional Call stack entry qualification
parameter. The program object can be specified by either not using the call
stack entry qualification 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 this API.
<p>This option essentially identifies the oldest call stack entry that began a
sequence of calls, and 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 results as
using * or an OPM program name. 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, *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 by means of 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 identify the
call stack entry for the first procedure called in the specified 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>In some cases, *PGMBDY and *CTLBDY will 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 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 align="left" valign="top"><em>*PGMNAME</em></td>
<td align="left" valign="top">The call stack entry is identified entirely by
the program name and optionally module name that is provided by the optional
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 directly in this required
parameter.</p>
<p>For ILE programs or ILE service programs, this special key 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 or 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
or 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 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 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 the 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>
<tr>
<td align="left" valign="top"><em>*EXT</em></td>
<td align="left" valign="top">The external message queue. The Call stack
counter parameter is ignored. You cannot send escape
<img src="v5r4adelta.gif" alt="Start of change">or command
<img src="v5r4adeltaend.gif" alt="End of change">
messages to this message
queue. If you are sending an inquiry message, you must specify this message
queue.</td>
</tr>
</table>
<p>If the call stack entry is to be identified by pointer, the pointer that is
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 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>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 (&lt;&lt;&lt;) at the beginning of the call stack entry
identifier, or place three greater-than signs (&gt;&gt;&gt;) 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 (&lt;&lt;&lt;) 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.</li>
<li>If the greater-than signs (&gt;&gt;&gt;) 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.</li>
<li>If the less-than signs (&lt;&lt;&lt;) are specified at the beginning of the
call stack entry name and the greater-than signs (&gt;&gt;&gt;) 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>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 message is to be sent. The number is relative to the
call stack entry identified by the Call stack entry parameter. It indicates how
many calls up the call stack the target entry is from the one identified by the
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">Send the messages to the message queue of the
entry specified by the Call stack entry parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Send the messages to the message queue of the
call stack entry one earlier on the stack than the one identified by the Call
stack entry parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>n (any positive number)</em></td>
<td align="left" valign="top">Send the messages to the queue of the nth call
stack entry earlier in the stack from the one identified by the 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>
<br>
</dd>
<dt><strong>Message key</strong></dt>
<dd>OUTPUT; CHAR(4)
<p>The key to the message being sent. This API assigns the key when it sends a
message of any type except status. For a status message, no key is returned and
this parameter is not changed.</p>
<p>For inquiry and notify messages, this is the key to the sender's copy of the
message in the sending program's message queue.</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>
<p><strong>Note:</strong> The API does not return an error code for the message
type of *STATUS if the qualified message file name parameter is specified
incorrectly, unless the call stack entry parameter is the special value
*EXT.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 1</h3>
<dl>
<dt><strong>Length of call stack entry</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the value for the Call stack entry parameter. Valid values for
this parameter are as follows:</p>
<ul>
<li>1 through 4096 if partial name indicators are not used.</li>
<li>16 if the call stack entry parameter is a pointer.</li>
<li>1 through 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>Call stack entry qualification</strong></dt>
<dd>INPUT; CHAR(20)
<p>This parameter is used when it is necessary to further identify the 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 Call stack entry parameter. The values that can be specified
here depend upon the value provided in the Call stack entry parameter.</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="15 85" -->
<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>
<br>
<p>If the Call stack entry parameter contains an ILE procedure name then this
parameter 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 or 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 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 or service program name. For ILE, the module name qualifier may contain
a module name; otherwise it must contain *NONE.</p>
<p>When the Call stack entry parameter specifies the special value * or
*CTLBDY, both the module name qualifier and program name qualifier must be
specified as *NONE.</p>
<p>When the Call stack entry parameter specifies 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 in the Call
stack entry parameter 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 Call stack entry parameter specifies 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>
<p>If the 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
set to *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 sent or the one to start counting from
when using a value other than 0 for the Call stack counter parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*PGMBDY</em></td>
<td align="left" valign="top">The call stack entry to send the message to or to
start counting from is an ILE program or Service program boundary. The ILE
program or Service 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 the 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>
<br>
</dd>
<dt><strong>Display program messages screen wait time</strong></dt>
<dd>INPUT; BINARY(4)
<p>The amount of time in seconds to wait on the display program messages screen
for any user action when a message is sent to an external message queue. If
there is no user action within the specified time, the control returns to the
statement following the call of this API. Valid values follow:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">Wait on the display program messages screen for
the maximum length of time allowed by the system (24 hours). If this parameter
is not specified, this is the default.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Send the message, but do not show the display
program messages screen.</td>
</tr>
<tr>
<td align="left" valign="top"><em>&gt;0</em></td>
<td align="left" valign="top">The amount of time to wait in seconds for user
action. If there is no user action within the time, then control returns. If
the display file currently being displayed is defined with the restore display
attribute of *NO, the Display Program Messages screen wait time parameter is
ignored.</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 2</h3>
<dl>
<dt><strong>Call stack entry data type</strong></dt>
<dd>INPUT; CHAR(10)
<p>The value of the 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 Call stack entry parameter is a character string.</p>
</dd>
<dt><strong>Coded character set identifier</strong></dt>
<dd>INPUT; BINARY(4)
<p>The coded character set identifier (CCSID) that the supplied replacement
data or impromptu message text is in. If a message identifier is specified, the
data supplied by the replacement data or impromptu message text parameter that
corresponds to *CCHAR type fields is assumed to be in the CCSID supplied by
this parameter. The data supplied that does not correspond to a *CCHAR field is
65535 and will not be converted. For more information about *CCHAR type fields
see the Add Message Description (ADDMSGD) command.</p>
<p>If no message identifier is specified, the text supplied by the message data
or immediate text parameter will all be assumed to be in the CCSID supplied by
this parameter. For more information about message handler and its use of
CCSIDs, see <a href="../nls/rbagsccsidmsgsup2.htm">CCSIDs: Message Support</a>
in the Globalization topic. The following values are allowed:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The message data or immediate text is assumed in
the CCSID of the job running this API. This is the default value if this
parameter is not specified.</td>
</tr>
<tr>
<td align="left" valign="top"><em>65535</em></td>
<td align="left" valign="top">The message data or immediate text will not be
converted.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CCSID</em></td>
<td align="left" valign="top">Specify a valid CCSID that your message data or
immediate text is in. Valid values are between 1 and 65535. This API will
validate the CCSID.</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3><a name="HDRALLPAR">Dependencies among Parameters</a></h3>
<p>You can use many different combinations of parameters when calling the
QMHSNDPM API. The values you specify for the message identifier and message
type parameters determine which other input parameters you must specify and
which you must code as blanks. They also determine whether the system returns
the message key in the message key output parameter.</p>
<br>
<h3><a name="HDRADDITI">Additional Information about Message Types</a></h3>
<p>The following sections discuss additional considerations in using the
different types of messages that you can specify when calling the QMHSNDPM
API.</p>
<p><strong>Completion and Diagnostic Messages:</strong>&nbsp;&nbsp;You can send completion and diagnostic
messages as immediate messages or with message identifiers to call message
queues or to the external message queue.</p>
<p><strong>Escape Messages:</strong>&nbsp;&nbsp; You
can send escape messages only with a message identifier and only to a call
message queue. You cannot send them to the external message queue.</p>
<p>An escape message sent to a previous caller's call message queue ends the
current call stack entry. Sending the escape message causes all the call stack
entries up to but not including the call stack entry receiving the escape
message to end. For example, if three call stack entries are active and the
third call stack entry sends an escape message to the first, then the second
and third call stack entries are ended.</p>
<p><strong><a name="HDRINFO">Informational Messages:</a></strong>&nbsp;&nbsp;
You can send informational messages as immediate messages or with message
identifiers to call message queues or to the external message queue.</p>
<p>When you send an informational or inquiry message to the external message
queue and the job is interactive, the message is displayed on the work station
of the current job. The user sees the Display Program Messages display. Sending
messages of these types to the external message queue is the only way to make
the Display Program Messages display appear.</p>
<p><strong>Inquiry Messages:</strong>&nbsp;&nbsp; You
can send inquiry messages only to the external message queue. You cannot send
them to call message queues. The sending call stack entry would have to end
before the receiving call stack entry could receive the message and send a
reply. At that point, the sending call stack entry is no longer active, so it
cannot receive a reply.</p>
<p>When you send an inquiry message, it is displayed at the work station as
described in <a href="#HDRINFO">Informational Messages</a>. In addition, a copy
of the message is placed in the reply message queue, which is always the
sending call stack entry's call message queue. Sending an inquiry message lets
your call stack entry receive the reply to the message by using the message key
returned by this API.</p>
<p>An inquiry message sent to the external message queue requires either the
default reply or a reply from an interactive user. Call stack entries cannot
reply to inquiry messages sent to the external message queue. In batch mode,
the default reply is automatically sent as the reply.</p>
<p>The QMHSNDPM API returns the message key to the copy of the inquiry message
in the reply message queue. You can receive the reply to the inquiry message by
using the Receive Program Message (QMHRCVPM) API specifying this key and the
message type reply. You can receive the copy of the original inquiry message by
specifying this key and the message type of *COPY. You cannot use this key to
receive the original message.</p>
<p><strong>>Notify Messages</strong> You can send
notify messages only with a message identifier. You can send them to a call
message queue or to the external message queue.</p>
<p>The reply message queue is always the sending call stack entry's call
message queue (*PGMQ). This API returns the message key to the copy of the
message in the reply message queue. To receive the reply, use the Receive
Program Message (QMHRCVPM) API specifying this key and a message type of reply
(*RPY).</p>
<p>When a notify message is sent to a call message queue, the action taken
depends on two things:</p>
<ul>
<li>Whether the receiving call stack entry monitors for the message.</li>
<li>Whether the receiving call stack entry has specified an external exception
handler to handle the message.</li>
</ul>
<p>When a notify message is sent to the external message queue, the action
taken is the same as if an inquiry message were sent, with this exception.
Notify messages are not responded to by the system reply list.</p>
<table border>
<tr>
<th align="left" valign="bottom" colspan="4"><em><a name="TBLNOTIFY">NOTIFY
Message Results</a></em></th>
</tr>
<tr>
<th align="left" valign="bottom">Receiving Call Stack Entry</th>
<th align="left" valign="bottom">Sending Call Stack Entry</th>
<th align="left" valign="bottom">Default Reply</th>
<th align="left" valign="bottom">Action Taken after Notify Message Is Sent</th>
</tr>
<tr>
<td align="left" valign="top">Monitor defined with external handler</td>
<td align="left" valign="top">Does not end</td>
<td align="left" valign="top">Not sent</td>
<td align="left" valign="top">External handler is called</td>
</tr>
<tr>
<td align="left" valign="top">Monitor defined and no external handler</td>
<td align="left" valign="top">Ends</td>
<td align="left" valign="top">Not sent</td>
<td align="left" valign="top">Control is returned to receiving call stack
entry</td>
</tr>
<tr>
<td align="left" valign="top">No monitor defined</td>
<td align="left" valign="top">Does not end</td>
<td align="left" valign="top">Sent</td>
<td align="left" valign="top">Control is returned to sending call stack
entry</td>
</tr>
</table>
<p>In an interactive job where a notify message is sent to *EXT, the user must
take action to send any reply, including the default reply. In a batch job, the
default reply is automatically sent because programs cannot reply to notify
messages sent to the external message queue.</p>
<p><strong>Request Messages:</strong>&nbsp;&nbsp; You
can send a request message only as an immediate message. You can send it to a
call message queue or to the external message queue.</p>
<p>Request messages sent to the external message queue are never displayed on
the Display Program Messages display. The system program QCMD receives them.
Before the Command Entry display appears, the QCMD program attempts to perform
the commands contained in the request messages. The QCMD program performs this
function only with request messages on the external message queue; it does not
work with request messages on other queues.</p>
<p><strong>Status Messages:</strong>&nbsp;&nbsp; You
must send status messages with a message identifier. You can send them to a
call message queue or the external message queue.</p>
<p>When you send status messages to the external message queue, the system
displays them at the bottom of the current job's display station. This shows
the status of running programs. You can use this to reassure users that long
programs are still running.</p>
<p>Status messages appear only on the display. Because they are never put in
message queues and they do not have message keys, you cannot receive them.</p>
<p>Status messages are predefined messages. However, you can send the user what
appears to be an immediate status message by using a message type of status and
message CPF9898. CPF9898 is in message file QCPFMSG in library QSYS. This
message consists only of a substitution variable; thus, it uses the message
data that you supply as the full message text. To use it, specify CPF9898 in
the message identifier parameter and the text you want to send in the
replacement data or impromptu text parameter. To clear the message from the
bottom of the display, you can send CPI9801, which only contains a blank line
as the message.</p>
<p><img src="v5r4adelta.gif" alt="Start of change"><strong>Command Messages:</strong>&nbsp;&nbsp; You
can send command messages only as immediate messages, and
only to a call message queue. You cannot send them to the
external message queue.</p>
<p>Command messages are intended for IBM use for logging commands to the
job log when a CL program runs.
<img src="v5r4adeltaend.gif" alt="End of change"></p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="3">
<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%">
<img src="v5r4adelta.gif" alt="Start of change">CPF24C4 E</td>
<td align="left" valign="top" width="85%">Not allowed to send stored command
message.
<img src="v5r4adeltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top" width="15%">CPF24C5 E</td>
<td align="left" valign="top" width="85%">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 &amp;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 &amp;1 incorrect for use with
pointer.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24AC E</td>
<td align="left" valign="top">Either message identifier or message text must be
specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24AD E</td>
<td align="left" valign="top">Messages to remove must be *ALL if program
message queue is *ALLINACT.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24A3 E</td>
<td align="left" valign="top">Value for call stack counter parameter 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 &amp;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">CPF24B6 E</td>
<td align="left" valign="top">Length of &amp;1, not valid for message text or
data.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B7 E</td>
<td align="left" valign="top">Value &amp;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">CPF24C2 E</td>
<td align="left" valign="top">Value &amp;1 for display wait time not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2401 E</td>
<td align="left" valign="top">Not authorized to library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2407 E</td>
<td align="left" valign="top">Message file &amp;1 in &amp;2 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2409 E</td>
<td align="left" valign="top">Specified message type not valid with specified
program message queue.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2411 E</td>
<td align="left" valign="top">Not authorized to message file &amp;1 in
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2435 E</td>
<td align="left" valign="top">System reply list not found.</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">CPF2467 E</td>
<td align="left" valign="top">&amp;3 message queue &amp;1 in library &amp;2
logically damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2469 E</td>
<td align="left" valign="top">Error occurred when sending message&amp;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">CPF2479 E</td>
<td align="left" valign="top">Call stack entry not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF247E E</td>
<td align="left" valign="top">CCSID &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2489 E</td>
<td align="left" valign="top">Message identifier required for *NOTIFY, *ESCAPE,
or *STATUS message types.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2493 E</td>
<td align="left" valign="top">Message identifier not allowed with message type
*RQS.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2499 E</td>
<td align="left" valign="top">Message identifier &amp;1 not allowed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2524 E</td>
<td align="left" valign="top">Exception handler not available because of reason
code &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2531 E</td>
<td align="left" valign="top">Message file &amp;1 in &amp;2 damaged for
&amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2547 E</td>
<td align="left" valign="top">Damage to message file QCPFMSG.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2548 E</td>
<td align="left" valign="top">Damage to message file &amp;1 in &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2557 E</td>
<td align="left" valign="top">System reply list damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2558 E</td>
<td align="left" valign="top">System reply list currently in use.</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">CPF8100 E</td>
<td align="left" valign="top">All CPF81xx messages could be returned. xx is
from 01 to FF.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9830 E</td>
<td align="left" valign="top">Cannot assign library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9845 E</td>
<td align="left" valign="top">Error occurred while opening file &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9846 E</td>
<td align="left" valign="top">Error while processing file &amp;1 in library
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9847 E</td>
<td align="left" valign="top">Error occurred while closing file &amp;1 in
library &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;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>
Reference in New Issue View Git Blame Copy Permalink