ibm-information-center/dist/eclipse/plugins/i5OS.ic.cl_5.4.0.1/sndpgmmsg.htm

707 lines
36 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head><META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Send Program Message (SNDPGMMSG)</title>
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body bgcolor="white">
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<a name="SNDPGMMSG.Top_Of_Page"></a>
<h2>Send Program Message (SNDPGMMSG)</h2>
<table width="100%">
<tr>
<td valign="top" align="left"><b>Where allowed to run: </b>Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX)<br>
<b>Threadsafe: </b>Yes
</td>
<td valign="top" align="right">
<a href="#SNDPGMMSG.PARAMETERS.TABLE">Parameters</a><br>
<a href="#SNDPGMMSG.COMMAND.EXAMPLES">Examples</a><br>
<a href="#SNDPGMMSG.ERROR.MESSAGES">Error messages</a></td>
</tr>
</table>
<div> <a name="SNDPGMMSG"></a>
<p>The Send Program Message (SNDPGMMSG) command sends a message to a named message queue or to a call message queue. A call message queue can be the *EXT external message queue or a message queue associated with a call stack entry. Each time a program or procedure is called a new message queue is associated with its call stack entry. The message queue is identified by the name of its associated program or procedure.
</p>
<p>A program can send a message to its own message queue or to a message queue that is associated with a different call stack entry.
</p>
<p>This command can send both exception and non-exception messages.
</p>
<p><b>Restrictions:</b>
</p>
<ol>
<li>The SNDPGMMSG command allows a message of up to 512 characters to be sent. However, if the message is sent to the *EXT message queue of an interactive job, only 76 characters are shown on the Display Program Messages display. If the message is sent to a user's, work station's, or the system operator's message queue, the Display Message (DSPMSG) command allows all 512 characters to be displayed.
</li>
<li>This command can only send inquiry messages (specified by MSGTYPE(*INQ)) to one message queue or to two nonprogram message queues if one of the queues is *HSTLOG.
</li>
</ol>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div>
<h3><a name="SNDPGMMSG.PARAMETERS.TABLE">Parameters</a></h3>
<table border="1" cellpadding="4" cellspacing="0">
<!-- col1="10" col2="15" col3="30" col4="10" -->
<tr>
<th bgcolor="aqua" valign="bottom" align="left">Keyword</th>
<th bgcolor="aqua" valign="bottom" align="left">Description</th>
<th bgcolor="aqua" valign="bottom" align="left">Choices</th>
<th bgcolor="aqua" valign="bottom" align="left">Notes</th>
</tr>
<tr>
<td valign="top"><a href="#SNDPGMMSG.MSG"><b>MSG</b></a></td>
<td valign="top">Message text, or</td>
<td valign="top"><i>Character value</i></td>
<td valign="top">Optional, Positional 1</td>
</tr>
<tr>
<td valign="top"><a href="#SNDPGMMSG.MSGID"><b>MSGID</b></a></td>
<td valign="top">Message identifier</td>
<td valign="top"><i>Name</i></td>
<td valign="top">Optional, Positional 2</td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#SNDPGMMSG.MSGF"><b>MSGF</b></a></td>
<td valign="top">Message file</td>
<td valign="top"><i>Qualified object name</i></td>
<td valign="top" rowspan="3">Optional, Positional 3</td>
</tr>
<tr>
<td valign="top">Qualifier 1: Message file</td>
<td valign="top"><i>Name</i></td>
</tr><tr>
<td valign="top">Qualifier 2: Library</td>
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b>, *CURLIB</td>
</tr><tr>
<td valign="top"><a href="#SNDPGMMSG.MSGDTA"><b>MSGDTA</b></a></td>
<td valign="top">Message data field values</td>
<td valign="top"><i>Character value</i>, <b><u>*NONE</u></b></td>
<td valign="top">Optional, Positional 4</td>
</tr>
<tr>
<td valign="top" rowspan="6"><a href="#SNDPGMMSG.TOPGMQ"><b>TOPGMQ</b></a></td>
<td valign="top">Call stack entry message queue</td>
<td valign="top">Single values: *EXT<br>Other values: <i>Element list</i></td>
<td valign="top" rowspan="6">Optional</td>
</tr>
<tr>
<td valign="top">Element 1: Relationship</td>
<td valign="top">
<b><u>*PRV</u></b>, *SAME</td>
</tr>
<tr>
<td valign="top">Element 2: Call stack entry identifier</td>
<td valign="top">
<i>Element list</i></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 1: Call stack entry</td>
<td valign="top">
<i>Character value</i>, <b><u>*</u></b></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 2: Module</td>
<td valign="top">
<i>Name</i>, <b><u>*NONE</u></b></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 3: Bound program</td>
<td valign="top">
<i>Name</i>, <b><u>*NONE</u></b></td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#SNDPGMMSG.TOMSGQ"><b>TOMSGQ</b></a></td>
<td valign="top">Send to non-pgm message queue</td>
<td valign="top">Single values: <b><u>*TOPGMQ</u></b>, *SYSOPR<br>Other values (up to 50 repetitions): <i>Qualified object name</i></td>
<td valign="top" rowspan="3">Optional</td>
</tr>
<tr>
<td valign="top">Qualifier 1: Send to non-pgm message queue</td>
<td valign="top"><i>Name</i>, *HSTLOG</td>
</tr><tr>
<td valign="top">Qualifier 2: Library</td>
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b>, *CURLIB</td>
</tr><tr>
<td valign="top"><a href="#SNDPGMMSG.TOUSR"><b>TOUSR</b></a></td>
<td valign="top">To user profile</td>
<td valign="top"><i>Name</i>, *SYSOPR, *ALLACT, *REQUESTER</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#SNDPGMMSG.MSGTYPE"><b>MSGTYPE</b></a></td>
<td valign="top">Message type</td>
<td valign="top"><b><u>*INFO</u></b>, *INQ, *RQS, *COMP, *DIAG, *NOTIFY, *ESCAPE, *STATUS</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#SNDPGMMSG.RPYMSGQ"><b>RPYMSGQ</b></a></td>
<td valign="top">Message queue to get reply</td>
<td valign="top">Single values: <b><u>*PGMQ</u></b><br>Other values: <i>Qualified object name</i></td>
<td valign="top" rowspan="3">Optional</td>
</tr>
<tr>
<td valign="top">Qualifier 1: Message queue to get reply</td>
<td valign="top"><i>Name</i></td>
</tr><tr>
<td valign="top">Qualifier 2: Library</td>
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b>, *CURLIB</td>
</tr><tr>
<td valign="top"><a href="#SNDPGMMSG.KEYVAR"><b>KEYVAR</b></a></td>
<td valign="top">CL var for KEYVAR (4)</td>
<td valign="top"><i>Character value</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#SNDPGMMSG.CCSID"><b>CCSID</b></a></td>
<td valign="top">Coded character set ID</td>
<td valign="top">1-65535, *HEX, <b><u>*JOB</u></b></td>
<td valign="top">Optional</td>
</tr>
</table>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
</div>
<div> <a name="SNDPGMMSG.MSG"></a>
<h3>Message text, or (MSG)</h3>
<p>Specifies the message text that is to be sent. A maximum of 3000 characters can be specified or, if you are prompting for this command in an interactive job, a maximum of 512 characters can be specified. The string must be enclosed in apostrophes if special characters (including blanks) are used. If this parameter is specified, a value cannot be specified for the <b>Message identifier (MSGID)</b> parameter, and *ESCAPE, *NOTIFY, or *STATUS cannot be specified for the <b>Message type (MSGTYPE)</b> parameter. If this parameter is specified, a value cannot be specified for the <b>Message file (MSGF)</b> parameter or the <b>Message data field values (MSGDTA)</b> parameter, because these types require that a message identifier also be specified.
</p>
<p><b>Coded Character Set Identifier (CCSID) Considerations</b>
</p>
<p>The text supplied for the MSG parameter is assumed to be in the CCSID of the job running this command unless a coded character set identifier is supplied in the CCSID parameter. For more information about the message handler and its use of CCSIDs, see the Globalization topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDPGMMSG.MSGID"></a>
<h3>Message identifier (MSGID)</h3>
<p>Specifies the message identifier of a message description whose predefined message is being sent by the program to a message queue. If this parameter is specified, a value cannot be specified for the <b>Message text, or (MSG)</b> parameter.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDPGMMSG.MSGF"></a>
<h3>Message file (MSGF)</h3>
<p>Specifies the message file that contains the predefined message to be sent. This parameter is required if a value is specified for the <b>Message identifier (MSGID)</b> parameter.
</p>
<p><b>Qualifier 1: Message file</b>
</p>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the message file which contains the predefined message to be sent.
</dd>
</dl>
<p><b>Qualifier 2: Library</b>
</p>
<dl>
<dt><b><u>*LIBL</u></b></dt>
<dd>All libraries in the library list for the current thread are searched until the first match is found.
</dd>
</dl>
<dl>
<dt><b>*CURLIB</b></dt>
<dd>The current library for the job is used to locate the message file. If no current library entry exists in the library list, QGPL is used.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the library where the message file is located.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDPGMMSG.MSGDTA"></a>
<h3>Message data field values (MSGDTA)</h3>
<p>Specifies the character string, or a CL variable that contains a character string, containing one or more substitution values that are used as message data fields within the predefined message. The substitution values take the place of the substitution variables that were defined in the message text when the message was defined.
</p>
<dl>
<dt><b><u>*NONE</u></b></dt>
<dd>There are no program-supplied substitution values used in the specified message.
</dd>
<dt><b><i>character-string</i></b></dt>
<dd>Specify the character string that gives the substitution values in the specified predefined message that is sent by the program, or specify the name of the CL variable that contains the character string.
<p><b>Coded Character Set Identifier (CCSID) Considerations</b>
</p>
<p>The text supplied for the MSGDTA parameter that corresponds to the *CCHAR type field is assumed to be in the CCSID of the job running this command unless the coded character set identifier is supplied in the CCSID parameter. All other text supplied for the MSGDTA parameter is assumed to be 65535 and is not converted. For more information about the message handler and its use of CCSIDs, see the Globalization topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter. For more information about the *CCHAR type fields, see the Add Message Description (ADDMSGD) command.
</p>
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDPGMMSG.TOPGMQ"></a>
<h3>Call stack entry message queue (TOPGMQ)</h3>
<p>Specifies the call message queue to which the specified message is to be sent. The message queue can be the *EXT external queue or the call message queue associated with a call stack entry.
</p>
<p><b>Single values</b>
</p>
<dl>
<dt><b>*EXT</b></dt>
<dd>The message is sent to the external message queue of the job. The external message queue is used to communicate with the external requester of the job, such as a display station user. *INQ messages that are sent to *EXT wait for 24 hours before the default reply is sent.
<p>Messages sent to this queue can be 512 characters in length, but only 76 characters of text are shown on the Program Messages display.
</p>
</dd>
</dl>
<p><b>Element 1: Relationship</b>
</p>
<p>Two parameter elements are used to specify the call stack entry message queue from which a message is to be removed. The first element specifies whether the message queue is associated with the program or procedure identified by the second element, or if it is associated with the caller of the program or procedure.
</p>
<dl>
<dt><b><u>*PRV</u></b></dt>
<dd>The message is sent to the message queue of the call stack entry that is immediately previous to the one identified by the second element of this parameter. However, if the message queue immediately previous to the one identified by the second element is for an Integrated Language Environment (ILE) program entry procedure (PEP), the message is sent to the message queue that precedes the PEP message queue in the stack.
</dd>
<dt><b>*SAME</b></dt>
<dd>The message is sent to the message queue of the call stack entry identified by the second element of this parameter.
</dd>
</dl>
<p><b>Element 2: Call stack entry identifier</b>
</p>
<p>The second element of this parameter has three elements. Element 1 specifies an OPM program or ILE procedure name or a special value. Element 2 specifies an ILE module name which is used as a qualifier for the value specified in element 1. Element 3 can specify either an OPM program name or an ILE program name or a service program name, depending on what is specified in element 1. Element 3 is also used as a qualifier for what is specified in element 1.
</p>
<dl>
<dt><b></b></dt>
<dd>
<p><b>Element 1: Call stack entry</b>
</p>
<dl>
<dt><b><u>*</u></b></dt>
<dd>Specifies the OPM program or ILE procedure running this command.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the OPM program or ILE procedure used to identify the call stack entry.
<p>If this element identifies an OPM program, the name specified can be a maximum of 10 characters. If this element identifies an ILE procedure, the name specified can be a maximum of 256 characters.
</p>
<p>Nested procedure names can be specified by separating each procedure name with a colon (:). When specifying nested procedure names, the outermost procedure name is identified first, followed by its contained procedures. The innermost procedure name is identified last in the string.
</p>
<p>Partial names of programs or procedures can be specified by placing three less-than symbols (&lt;&lt;&lt;) at the beginning of the name or by placing three greater-than symbols (&gt;&gt;&gt;) at the end of the name. If both the greater-than symbols and the less-than symbols are used, the program or procedure name specified is limited to 250 characters.
</p>
<p>The system begins its search for the specified program or procedure name with the most recently called program or procedure.
</p>
<p>When searching for a partial program or procedure name:
</p>
<ul>
<li>The less-than symbols (&lt;&lt;&lt;) are truncated when specified only at the beginning of a program or procedure name and the remaining character string is right-justified. The remaining characters in the specified string are compared to the current program or procedure on the call stack, starting with the last position of the program or procedure name and comparing backward.
</li>
<li>The greater-than symbols (&gt;&gt;&gt;) are truncated when specified only at the end of a program or procedure name. The remaining characters in the specified string are compared to the current program or procedure on the call stack, starting with the first position of the program or procedure name.
</li>
<li>The less-than symbols (&lt;&lt;&lt;) and the greater-than symbols (&gt;&gt;&gt;) are truncated when both are specified for a program or procedure name. The remaining characters are used to scan and compare the entire length of the specified string with the current program or procedure on the call stack.
</li>
</ul>
</dd>
</dl>
</dd>
<dt><b></b></dt>
<dd>
<p><b>Element 2: Module</b>
</p>
<dl>
<dt><b><u>*NONE</u></b></dt>
<dd>No ILE module qualifier is provided.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the ILE module name to be used to identify the message queue.
</dd>
</dl>
</dd>
<dt><b></b></dt>
<dd>
<p><b>Element 3: Program</b>
</p>
<dl>
<dt><b><u>*NONE</u></b></dt>
<dd>No program qualifier is provided.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the program name to be used to identify the message queue.
</dd>
</dl>
</dd>
</dl>
<p>The procedure name alone may not identify the correct procedure. Several different procedures with the same name can run in a job. To further identify a procedure, the name specified can be qualified by a module name, or by both a module name and a bound program name. The following special values can be specified for the first qualifier of the second element of this parameter:
</p>
<dl>
<dt><b>*CTLBDY</b></dt>
<dd>Specifies the call stack entry that is at the most recent control boundary. This entry will be running in the same activation group as the CL program that is running the SNDPGMMSG command. Note that a control boundary will not exist if all programs on the call stack are OPM programs.
</dd>
<dt><b>*PGMBDY</b></dt>
<dd>Specifies the program boundary of either the program that is using the SNDPGMMSG command or the program whose name is specified for qualifier 3 of this parameter. If no name is specified for qualifier 3, it is assumed that the program is the one using the command.
<p>If it is an ILE program that is being specified, this special value identifies the call stack entry for the program entry procedure (PEP) of that program, if the program was called by a dynamic call. If the program was called by a procedure pointer, this special value identifies the call stack entry for the procedure that was pointed to. If it is an ILE service program that is being specified, this special value identifies the call stack entry for the first procedure that was called in that service program.
</p>
<p>If the program being specified is an OPM program, this special value has the same effect as specifying the special value * or a program name for item 1. A difference will occur if the OPM program has called itself recursively. In this case, this special value identifies the first recursion level rather than the current recursion level as would be the case if the special value * or a program name was used.
</p>
</dd>
<dt><b>*PGMNAME</b></dt>
<dd>Specifies that the call stack entry will be identified only by using a program name and optionally a module name. When this special value is used, qualifier 3 must specify an ILE program or service program name or OPM program name. Qualifier 2 may contain either the special value *NONE or an ILE module name.
<p>This special value is used to send a message to the most recently called procedure that is part of the specified ILE program or service program. When using this special value, it is not necessary to explicitly provide a procedure name. If a module name is also provided, then this special value is used to send a message to the most recently called procedure that is both part of the identified program and the identified module.
</p>
<p>This special value may also be used to send a message to an OPM program. In this case, using this special value and providing the OPM program name in item 3 has exactly the same effect as providing that program name here in item 1. Note that if this special value is being used to send to an OPM program then the module name must be specified as *NONE.
</p>
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDPGMMSG.TOMSGQ"></a>
<h3>Send to non-pgm message queue (TOMSGQ)</h3>
<p>Specifies up to 50 nonprogram message queues to which an informational message is sent. For an inquiry message, one message queue may be specified or two message queues may be specified if one of the queues is *HSTLOG. This parameter cannot be used if a value is specified for the <b>To user profile (TOUSR)</b> parameter.
</p>
<p><b>Single values</b>
</p>
<dl>
<dt><b><u>*TOPGMQ</u></b></dt>
<dd>The message is sent only to the call message queue specified for the <b>Call stack entry message queue (TOPGMQ)</b> parameter.
</dd>
<dt><b>*SYSOPR</b></dt>
<dd>The message is sent to the system operator message (message queue QSYSOPR in library QSYS). Any message sent to message queue QSYSOPR in library QSYS automatically has a copy of the message sent to the QHST (history log) message queue in library QSYS.
</dd>
</dl>
<p><b>Qualifier 1: Send to non-pgm message queue</b>
</p>
<dl>
<dt><b>*HSTLOG</b></dt>
<dd>The message is sent to the system history log (message queue QHST in library QSYS). If *HSTLOG is specified more than once, only one message will be sent to the system history log. If *HSTLOG is specified with message queue QSYSOPR, only one message is sent to the system history log.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the message queue to which the message is to be sent. A maximum of fifty message queues can be specified.
</dd>
</dl>
<p><b>Qualifier 2: Library</b>
</p>
<dl>
<dt><b><u>*LIBL</u></b></dt>
<dd>All libraries in the library list for the current thread are searched until the first match is found.
</dd>
</dl>
<dl>
<dt><b>*CURLIB</b></dt>
<dd>The current library for the job is used to locate the message queue. If no current library entry exists in the library list, QGPL is used.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the library where the message queue is located.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDPGMMSG.TOUSR"></a>
<h3>To user profile (TOUSR)</h3>
<p>Specifies that the message is to be sent to the message queue specified in the user profile for the user named on this parameter. This parameter cannot be used if a value is specified for the <b>Send to non-pgm message queue (TOMSGQ)</b> parameter or the <b>Call stack entry message queue (TOPGMQ)</b> parameter.
</p>
<dl>
<dt><b>*SYSOPR</b></dt>
<dd>The message is sent to the system operator (message queue QSYSOPR in library QSYS). Any message sent to message queue QSYSOPR in library QSYS automatically has a copy of the message sent to the QHST (history log) message queue in library QSYS.
</dd>
<dt><b>*REQUESTER</b></dt>
<dd>The message is sent to the user profile message queue for interactive jobs or to the system operator's message queue (QSYSOPR in library QSYS) for batch jobs.
</dd>
<dt><b>*ALLACT</b></dt>
<dd>A copy of the message is sent to the user profile message queue of each user profile with an interactive job currently running. *ALLACT cannot be specified with inquiry messages.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the user profile name of the user to whom the message is to be sent.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDPGMMSG.MSGTYPE"></a>
<h3>Message type (MSGTYPE)</h3>
<p>Specifies which message type is assigned to this message when it is sent by this program.
</p>
<p><b>Notes:</b>
</p>
<ol>
<li>Inquiry messages can be sent only to the external queue or to a named message queue specified for the TOUSR or TOMSGQ parameters. When sending an inquiry with the TOMSGQ parameter, a second queue can be specified if the value is *HSTLOG.
</li>
<li>Completion, diagnostic, escape, notify, and status messages can be sent only to a call message queue.
</li>
<li>Escape messages cannot be sent to the external message queue.
</li>
</ol>
<dl>
<dt><b><u>*INFO</u></b></dt>
<dd>The message is sent as an informational message.
</dd>
<dt><b>*INQ</b></dt>
<dd>The message is sent as an inquiry message.
</dd>
<dt><b>*COMP</b></dt>
<dd>A completion message is sent to a call message queue. A completion message indicates the status of the work that is successfully performed.
</dd>
<dt><b>*DIAG</b></dt>
<dd>A diagnostic message is sent to a call message queue. Diagnostic messages provide information about errors detected by this program. The errors are either in the input sent to it, or are those that occurred while it was running the requested function. An escape or notify message should also be sent to inform the receiving program or procedure of the diagnostic messages that are on its message queue.
</dd>
<dt><b>*NOTIFY</b></dt>
<dd>A notify exception message is sent to a call message queue. A notify message describes a condition for which corrective action must be taken before the sending program can continue. A reply message is sent back to the sending program. After corrective action is taken, the sending program can resume running and can receive the reply message from its message queue.
</dd>
<dt><b>*ESCAPE</b></dt>
<dd>An escape exception message is sent to a call message queue. An escape message describes an irrecoverable error condition. The sending program does not continue to run.
</dd>
<dt><b>*RQS</b></dt>
<dd>A request message is sent to a call message queue. A request message allows request data received from device files to pass from this program to another program or procedure. An immediate message, specified by the MSG parameter, must be used to send the request.
</dd>
<dt><b>*STATUS</b></dt>
<dd>A status exception message is sent to a call message queue. The status message describes the status of work performed by the sending program. The first 28 characters of message data in the MSGDTA parameter are used as the comparison data for message monitors (established by the Monitor Message (MONMSG) command). If the status exception message is not being monitored, control is returned to the sending program. If a status message is sent to the external message queue of an interactive job, the message is shown on line 24, processing continues, and no response is required.
<p>
<b>Note: </b>This value cannot be specified if the <b>Message text, or (MSG)</b> parameter, is specified.
</p>
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDPGMMSG.RPYMSGQ"></a>
<h3>Message queue to get reply (RPYMSGQ)</h3>
<p>Specifies, for inquiry and notify messages only, the call message queue or the non-program message queue to which the reply message is to be sent.
</p>
<p><b>Single values</b>
</p>
<dl>
<dt><b><u>*PGMQ</u></b></dt>
<dd>The reply to an inquiry or notify message is sent to the message queue associated with the call stack entry of the program or procedure using this command.
</dd>
</dl>
<p><b>Qualifier 1: Message queue to get reply</b>
</p>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the message queue to which the reply is sent.
</dd>
</dl>
<p><b>Qualifier 2: Library</b>
</p>
<dl>
<dt><b><u>*LIBL</u></b></dt>
<dd>All libraries in the library list for the current thread are searched until the first match is found.
</dd>
</dl>
<dl>
<dt><b>*CURLIB</b></dt>
<dd>The current library for the job is used to locate the message queue. If no current library entry exists in the library list, QGPL is used.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the library where the message queue is located.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDPGMMSG.KEYVAR"></a>
<h3>CL var for KEYVAR (4) (KEYVAR)</h3>
<p>Specifies the name of the CL character variable, if any, that contains the message reference key that identifies the message sent by the program containing this command. The message reference key is assigned by the system when the message is sent and is placed in the variable specified here.
</p>
<p>If a message is being sent to a message queue associated with a call stack entry, KEYVAR refers to that message queue (specified for the <b>Call stack entry message queue (TOPGMQ)</b> parameter). If *INQ or *NOTIFY is specified for the <b>Message type (MSGTYPE)</b> parameter, KEYVAR refers to the message queue specified for the <b>Message queue to get reply (RPYMSGQ)</b> parameter. In all other cases, KEYVAR refers to the message queue specified for the TOPGMQ parameter.
</p>
<p>Any type of message can be assigned a key when it is being sent to a program message queue. For messages sent to a nonprogram message queue, message reference keys are available for inquiry (*INQ) messages only. If another message type is sent to a nonprogram queue, no message key is available and blanks are returned for KEYVAR.
</p>
<p>The variable must be a character variable having a length of 4 characters. If KEYVAR is not specified and a reply is required, it can be received by the program in FIFO order.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDPGMMSG.CCSID"></a>
<h3>Coded character set ID (CCSID)</h3>
<p>Specifies the coded character set identifier (CCSID) that the supplied message or message data is in. If a message identifier is specified, the text supplied by the MSGDTA (message data) parameter that corresponds to the *CCHAR type field is assumed to be in the CCSID specified by the CCSID parameter. The data supplied that does not correspond to the *CCHAR type field is assumed to be 65535 and is not converted. For more information about the *CCHAR type field see the Add Message Description (ADDMSGD) command.
</p>
<p>If no message identifier is specified, the text supplied by the MSG (message) parameter is assumed to be in the CCSID supplied by the CCSID parameter. For more information about the message handler and its use of CCSIDs, see the Globalization topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
</p>
<dl>
<dt><b><u>*JOB</u></b></dt>
<dd>The message data or immediate text is assumed to be in the CCSID of the job running this command.
</dd>
<dt><b>*HEX</b></dt>
<dd>The message data or immediate text is not converted. CCSID 65535 is used.
</dd>
<dt><b><i>coded-character-set-identifier</i></b></dt>
<dd>Specify a valid CCSID in which you want your message or message data to be considered in. Valid values range from 1 through 65535. This command validates the CCSID. See the Globalization information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter for a list of valid CCSID values.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="SNDPGMMSG.COMMAND.EXAMPLES">Examples</a> </h3>
<p><b>Example 1: Specifying Substitution Values</b>
</p>
<p>
<pre>
SNDPGMMSG MSGID(UIN0023) MSGF(INV) MSGDTA('50 100')
TOPGMQ(*EXT)
</pre>
</p>
<p>This command sends the message identified as UIN0023, which is stored in message file INV, to the external message queue of the job (the Display Program Messages presents the message at a display station). The data, which contains two substitution values specified in the MSGDTA parameter, is sent with the message. This data can then be used as substitution values when the message is received, or it can be used as data to be dumped, depending on how the message UIN0023 is defined in the message file. Assuming that the variables &amp;1 and &amp;2 have been defined in the message file as character variables, each 3 characters long, and that the first-level message text of the message UIN0023 is: 'Requested item decreased by &amp;1; current balance &amp;2.' The message text sent is: 'Requested item decreased by 50; current balance 100.'
</p>
<p><b>Example 2: Sending an Inquiry Message</b>
</p>
<p>
<pre>
SNDPGMMSG MSG('Mount checks in printer before continuing')
MSGTYPE(*INQ) TOMSGQ(*SYSOPR)
</pre>
</p>
<p>This command sends an inquiry message to the system operator. The operator looks at the message that was sent by using the DSPMSG command and responds to the message directly on that display. A Receive Message (RCVMSG) command is used in the program to accept the operator's response.
</p>
<p><b>Example 3: Sending an Escape Message</b>
</p>
<p>
<pre>
SNDPGMMSG MSGID(USR0001) MSGF(USRMSGR) TOPGMQ(*PRV *)
MSGTYPE(*ESCAPE)
</pre>
</p>
<p>This command is an example of how a message could be sent to the caller of a program or procedure to cause an abnormal end. The message USR0001 could indicate that an invalid code was passed (such as a nonnumeric code when numeric is required). Because the message being sent is an escape message, the program or procedure that is sending the message cannot be resumed. The values *PRV and * did not have to be coded on this command because they are the default values on the TOPGMQ parameter.
</p>
<p><b>Example 4: Sending an Escape Message to an ILE Procedure</b>
</p>
<p>
<pre>
SNDPGMMSG MSGID(USR0001) MSGF(USRMSGR)
TOPGMQ(*SAME ACCOUNT_FINAL_TOTALS)
MSGTYPE(*ESCAPE)
</pre>
</p>
<p>This command sends a message to an ILE procedure. In this example, the call stack entry identifier is more than 10 characters. Since no qualifier is specified, the actual module name and bound program name associated with the procedure are not used in finding the procedure. The escape exception message is sent to the message queue associated with ACCOUNT_FINAL_TOTALS because *SAME is specified for Element 1.
</p>
<p><b>Example 5: Sending an Escape Message using Qualifiers</b>
</p>
<p>
<pre>
SNDPGMMSG MSGID(USR0001) MSGF(USRMSGR)
TOPGMQ(*PRV FIRST_QTR_SUMMARY SUMQTRS REPORTS)
MSGTYPE(*ESCAPE)
</pre>
</p>
<p>This command sends an escape exception message to the caller of the procedure FIRST_QTR_SYMMARY. The procedure is qualified by the module name SUMQTRS and the bound program name REPORTS. The escape exception message interrupts the sending program and the sending program is not resumed.
</p>
<p><b>Example 6: Sending a Completion Message using a Partial Procedure Name</b>
</p>
<p>
<pre>
SNDPGMMSG MSGID(USR0001) MSGF(USRMSGR)
TOPGMQ(*SAME 'MANAGE_SALES&gt;&gt;&gt;') MSGTYPE(*COMP)
</pre>
</p>
<p>This command sends a completion message to the most recent procedure whose name begins with MANAGE_SALES.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="SNDPGMMSG.ERROR.MESSAGES">Error messages</a> </h3>
<p><b><u>*ESCAPE Messages</u></b>
</p>
<dl>
<dt><b>CPF24CB</b></dt>
<dd>*PGMNAME requires a specified program name.
</dd>
<dt><b>CPF2409</b></dt>
<dd>Specified message type not valid with specified program message queue.
</dd>
<dt><b>CPF2428</b></dt>
<dd>Message queue parameter is not valid.
</dd>
<dt><b>CPF2453</b></dt>
<dd>Reply queue not sender's program message queue.
</dd>
<dt><b>CPF2469</b></dt>
<dd>Error occurred when sending message&amp;1.
</dd>
<dt><b>CPF247A</b></dt>
<dd>Call stack entry not found.
</dd>
<dt><b>CPF247E</b></dt>
<dd>CCSID &amp;1 is not valid.
</dd>
<dt><b>CPF2499</b></dt>
<dd>Message identifier &amp;1 not allowed.
</dd>
<dt><b>CPF2524</b></dt>
<dd>Exception handler not available because of reason code &amp;1.
</dd>
<dt><b>CPF2550</b></dt>
<dd>Exception message sent to a deleted program or procedure.
</dd>
<dt><b>CPF2702</b></dt>
<dd>Device description &amp;1 not found.
</dd>
<dt><b>CPF7C08</b></dt>
<dd>No support network connection.
</dd>
<dt><b>CPF8C0C</b></dt>
<dd>Content of problem record &amp;1 not valid.
</dd>
<dt><b>CPF8C0E</b></dt>
<dd>Library QGPL not found.
</dd>
<dt><b>CPF8C01</b></dt>
<dd>Cannot connect to IBM service system. One session allowed.
</dd>
<dt><b>CPF8C07</b></dt>
<dd>A parameter is not valid.
</dd>
<dt><b>CPF8C08</b></dt>
<dd>Cannot specify *SELECT for the control point name.
</dd>
<dt><b>CPF8C09</b></dt>
<dd>&amp;1 not defined as a service provider.
</dd>
<dt><b>CPF8C16</b></dt>
<dd>Error occurred while processing request.
</dd>
<dt><b>CPF8C17</b></dt>
<dd>Sign-on failed.
</dd>
<dt><b>CPF8C18</b></dt>
<dd>No support network connection.
</dd>
<dt><b>CPF8C19</b></dt>
<dd>Remote support application failed.
</dd>
<dt><b>CPF8C2A</b></dt>
<dd>Cannot connect to IBM service system.
</dd>
<dt><b>CPF8C24</b></dt>
<dd>Error occurred while processing request.
</dd>
<dt><b>CPF8C27</b></dt>
<dd>Alternate load device not found.
</dd>
<dt><b>CPF8C32</b></dt>
<dd>PTF order cannot be processed.
</dd>
<dt><b>CPF9830</b></dt>
<dd>Cannot assign library &amp;1.
</dd>
<dt><b>CPF9845</b></dt>
<dd>Error occurred while opening file &amp;1.
</dd>
<dt><b>CPF9846</b></dt>
<dd>Error while processing file &amp;1 in library &amp;2.
</dd>
<dt><b>CPF9847</b></dt>
<dd>Error occurred while closing file &amp;1 in library &amp;2.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDPGMMSG.Top_Of_Page">Top</a></td></tr>
</table>
</body>
</html>