friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.cl_5.4.0.1/sndusrmsg.htm

460 lines
20 KiB
HTML
Raw Permalink 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">
<title>Send User Message (SNDUSRMSG)</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="SNDUSRMSG.Top_Of_Page"></a>
<h2>Send User Message (SNDUSRMSG)</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>No
</td>
<td valign="top" align="right">
<a href="#SNDUSRMSG.PARAMETERS.TABLE">Parameters</a><br>
<a href="#SNDUSRMSG.COMMAND.EXAMPLES">Examples</a><br>
<a href="#SNDUSRMSG.ERROR.MESSAGES">Error messages</a></td>
</tr>
</table>
<div> <a name="SNDUSRMSG"></a>
<p>The Send User Message (SNDUSRMSG) command is used by a program to send a message to a message queue and optionally receive a reply to that message. The message sent using this command can be either an impromptu or a predefined message and can be sent to a display station user in an interactive job or a specific message queue. For inquiry messages, a CL variable can be specified to receive the reply value, and the program using this command will wait for a response.
</p>
<p>This command uses a combination of parameters available on the Send Program Message (SNDPGMMSG) and Receive Message (RCVMSG) commands to allow a program to send and receive messages by using a single command. Also, the SNDUSRMSG command provides validity checking and uppercase translation for replies to inquiry messages.
</p>
<p><b>Restrictions:</b>
</p>
<ol>
<li>The SNDUSRMSG command allows a message of up to 512 characters of first-level message text to be sent. However, if the message is sent to an external message queue (*EXT) in 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 system operator's message queue, the Display Message (DSPMSG) command allows all 512 characters to be displayed.
</li>
</ol>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div>
<h3><a name="SNDUSRMSG.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="#SNDUSRMSG.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="#SNDUSRMSG.MSGID"><b>MSGID</b></a></td>
<td valign="top">Message identifier</td>
<td valign="top"><i>Name</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#SNDUSRMSG.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</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="#SNDUSRMSG.MSGDTA"><b>MSGDTA</b></a></td>
<td valign="top">Message data field values</td>
<td valign="top"><i>Character value</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#SNDUSRMSG.VALUES"><b>VALUES</b></a></td>
<td valign="top">Valid reply values</td>
<td valign="top">Values (up to 20 repetitions): <i>Character value</i>, <b><u>*NONE</u></b></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#SNDUSRMSG.DFT"><b>DFT</b></a></td>
<td valign="top">Default reply value</td>
<td valign="top"><i>Character value</i>, <b><u>*MSGDFT</u></b></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#SNDUSRMSG.MSGTYPE"><b>MSGTYPE</b></a></td>
<td valign="top">Message type</td>
<td valign="top"><b><u>*INQ</u></b>, *INFO</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#SNDUSRMSG.TOMSGQ"><b>TOMSGQ</b></a></td>
<td valign="top">To message queue</td>
<td valign="top">Single values: <b><u>*</u></b>, *EXT, *SYSOPR<br>Other values: <i>Qualified object name</i></td>
<td valign="top" rowspan="3">Optional</td>
</tr>
<tr>
<td valign="top">Qualifier 1: To message queue</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="#SNDUSRMSG.TOUSR"><b>TOUSR</b></a></td>
<td valign="top">To user profile</td>
<td valign="top"><i>Name</i>, *SYSOPR, *REQUESTER</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#SNDUSRMSG.MSGRPY"><b>MSGRPY</b></a></td>
<td valign="top">CL var for message reply</td>
<td valign="top"><i>Character value</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#SNDUSRMSG.TRNTBL"><b>TRNTBL</b></a></td>
<td valign="top">Translate table</td>
<td valign="top">Single values: *NONE<br>Other values: <i>Qualified object name</i></td>
<td valign="top" rowspan="3">Optional</td>
</tr>
<tr>
<td valign="top">Qualifier 1: Translate table</td>
<td valign="top"><i>Name</i>, <b><u>QSYSTRNTBL</u></b></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="#SNDUSRMSG.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="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
</div>
<div> <a name="SNDUSRMSG.MSG"></a>
<h3>Message text, or (MSG)</h3>
<p>Specifies the message text of an immediate message that is sent by the program. A maximum of 512 characters can be specified. The text string must be enclosed in apostrophes if special characters (including blanks) are used. If this parameter is specified, values cannot be specified for the <b>Message identifier (MSGID)</b> parameter, <b>Message file (MSGF)</b> parameter, or <b>Message data field values (MSGDTA)</b> parameter.
</p>
<dl>
<dt><b><i>'text'</i></b></dt>
<dd>Specify the text of the immediate message to be sent.
</dd>
</dl>
<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="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.MSGID"></a>
<h3>Message identifier (MSGID)</h3>
<p>Specifies the message identifier of a predefined message sent by the program to a message queue. If a value is specified for this parameter, a value must also be specified for the <b>Message file (MSGF)</b> parameter, and a value cannot be specified for the <b>Message text, or (MSG)</b> parameter.
</p>
<dl>
<dt><b><i>identifier</i></b></dt>
<dd>Specify the message identifier of the message to be sent.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.MSGF"></a>
<h3>Message file (MSGF)</h3>
<p>Specifies the message file that contains the predefined message to be sent. This parameter is valid only 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 in which the message file is located.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.MSGDTA"></a>
<h3>Message data field values (MSGDTA)</h3>
<p>Specifies the character string or the CL variable that contains a character string used as the message data in the predefined message. A character string that is specified contains one or more substitution values that are used in place of the substitution variables that were defined in the message's text when the message was defined.
</p>
<dl>
<dt><b><u>*NONE</u></b></dt>
<dd>No message data is specified for the predefined message.
</dd>
<dt><b><i>message-data</i></b></dt>
<dd>Specify the character string that gives the substitution values in the specified predefined message that is sent, or specify the name of the 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 a 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 field, see the Add Message Description (ADDMSGD) command.
</p>
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.VALUES"></a>
<h3>Valid reply values (VALUES)</h3>
<p>Specifies a list of valid replies to an inquiry message sent by this command. No more than 20 replies can be specified in the list. If the reply to the inquiry message does not match one of the specified values, an error message is sent to the reply's sender and the inquiry message is sent again.
</p>
<dl>
<dt><b><u>*NONE</u></b></dt>
<dd>No replies to inquiry messages are specified. Any reply to an inquiry message is valid.
</dd>
<dt><b><i>allowable-values</i></b></dt>
<dd>Specify no more than 20 values that are compared to replies received for inquiry messages sent by this command. The maximum length of each value is 32 characters. If this value is specified, the <b>CL var for message reply (MSGRPY)</b> parameter must also be specified.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.DFT"></a>
<h3>Default reply value (DFT)</h3>
<p>Specifies the value used as the reply to an inquiry message (sent by this command) if the inquiry message is sent to a message queue that is in default delivery mode, or for any other reason the default reply is sent.
</p>
<dl>
<dt><b><u>*MSGDFT</u></b></dt>
<dd>The default value defined in the message description of the message ID (specified for the MSGID parameter) is used. If no message ID is specified, the default value is *N.
</dd>
<dt><b><i>'default-reply-value'</i></b></dt>
<dd>Specify the reply (enclosed in apostrophes) used as the default reply. This value can only be specified if the <b>CL var for message reply (MSGRPY)</b> parameter is specified.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.MSGTYPE"></a>
<h3>Message type (MSGTYPE)</h3>
<p>Specifies the type of message to be sent.
</p>
<dl>
<dt><b><u>*INQ</u></b></dt>
<dd>An inquiry message is sent and the message queue receiving the message must reply to it.
</dd>
<dt><b>*INFO</b></dt>
<dd>An informational message is sent.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.TOMSGQ"></a>
<h3>To message queue (TOMSGQ)</h3>
<p>Specifies the name of the message queue to which the message is to be sent. 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>*</u></b></dt>
<dd>In an interactive job, the message is to be sent to the external message queue (*EXT). In a batch job, the message is to be sent to the system operator (message queue QSYSOPR in library QSYS).
</dd>
<dt><b>*SYSOPR</b></dt>
<dd>The message is to be sent to the system operator (message queue QSYSOPR in library QSYS).
</dd>
<dt><b>*EXT</b></dt>
<dd>The message is to be sent to the job's external message queue. For batch job inquiry messages, the default reply is always received.
</dd>
</dl>
<p><b>Qualifier 1: To message queue</b>
</p>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the message queue that is to receive the message being 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="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.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>To message queue (TOMSGQ)</b> parameter.
</p>
<dl>
<dt><b>*SYSOPR</b></dt>
<dd>The message is to be sent to the system operator user profile message queue, QSYS/QSYSOPR.
</dd>
<dt><b>*REQUESTER</b></dt>
<dd>The message is to be sent to the user profile message queue for interactive jobs or to the system operator's message queue (QSYS/QSYSOPR) for batch jobs.
</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="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.MSGRPY"></a>
<h3>CL var for message reply (MSGRPY)</h3>
<p>Specifies the CL character variable (of up to 132 characters) that contains the reply received in response to an inquiry message. This parameter is valid only if *INQ is specified for the <b>Message type (MSGTYPE)</b> parameter.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.TRNTBL"></a>
<h3>Translate table (TRNTBL)</h3>
<p>Specifies the name of the translation table that is used if the reply value is being translated.
</p>
<p><b>Qualifier 1: Translate table</b>
</p>
<dl>
<dt><b><u>QSYSTRNTBL</u></b></dt>
<dd>The translation table named QSYSTRNTBL is used to translate the reply value.
<p>The IBM-supplied translation table QSYSTRNTBL table translates, for the English language only, all lowercase characters in the range of X'81' to X'A9' to uppercase characters. All other characters are not translated.
</p>
<p>To use a different translation table, use the Create Table (CRTTBL) command and specify that particular table for this parameter.
</p>
</dd>
<dt><b>*NONE</b></dt>
<dd>The reply is not being translated.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the translation table that is used to translate the message reply.
</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 translation table. 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 translation table is located.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="SNDUSRMSG.CCSID"></a>
<h3>Coded character set ID (CCSID)</h3>
<p>Specifies the coded character set identifier (CCSID) that the message text supplied for the MSG (message) or MSGDTA (message data) parameters 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 supplied by this 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 this 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 text supplied by the MSGDTA (message data) or MSG (message) parameter is assumed to be in the CCSID of the job running this command.
</dd>
<dt><b>*HEX</b></dt>
<dd>The text supplied by the MSGDTA (message data) or MSG (message) parameter 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 text specified for the MSG (message) or MSGDTA (message data) parameter 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 CCSID values.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="SNDUSRMSG.COMMAND.EXAMPLES">Examples</a> </h3>
<p><b>Example 1: Message Requiring Specific Reply</b>
</p>
<p>
<pre>
SNDUSRMSG MSG('Data verified. Update master files (Y,N)?')
TOMSGQ(*) VALUES(Y N) DFT(N) MSGRPY(&amp;REPLY)
</pre>
</p>
<p>This command sends an inquiry message to the display station operator (if it is used in an interactive job) or to the system operator (if it is used in a batch job). The valid replies are Y and N, and any other reply is rejected. The reply is returned in the variable &amp;REPLY. The default translation table, QSYSTRNTBL, is used to translate the reply to uppercase characters.
</p>
<p><b>Example 2: Message Requiring Any Reply</b>
</p>
<p>
<pre>
SNDUSRMSG MSG('Enter any response when ready to continue.')
TOMSGQ(WS01)
</pre>
</p>
<p>This command sends an inquiry message to a specific message queue. Any reply is valid. Because the purpose of this example is simply to wait, no CL variable is provided to receive the reply.
</p>
<p><b>Example 3: Sending an Information Message</b>
</p>
<p>
<pre>
SNDUSRMSG MSGID(USR0150) TOUSR(FRED) MSGF(QGPL/USRMSGF)
MSGDTA(&amp;ACCTNO) MSGTYPE(*INFO)
</pre>
</p>
<p>This command sends a predefined message as an information message to the message queue specified in the user profile of the specified user (FRED). The message data provided is included in the message.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="SNDUSRMSG.ERROR.MESSAGES">Error messages</a> </h3>
<p><b><u>*ESCAPE Messages</u></b>
</p>
<dl>
<dt><b>CPF247E</b></dt>
<dd>CCSID &amp;1 is not valid.
</dd>
<dt><b>CPF2559</b></dt>
<dd>Error occurred in SNDUSRMSG command.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#SNDUSRMSG.Top_Of_Page">Top</a></td></tr>
</table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink