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

421 lines
18 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">
<title>Retrieve Message (RTVMSG)</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="RTVMSG.Top_Of_Page"></a>
<h2>Retrieve Message (RTVMSG)</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="#RTVMSG.PARAMETERS.TABLE">Parameters</a><br>
<a href="#RTVMSG.COMMAND.EXAMPLES">Examples</a><br>
<a href="#RTVMSG.ERROR.MESSAGES">Error messages</a></td>
</tr>
</table>
<div> <a name="RTVMSG"></a>
<p>The Retrieve Message (RTVMSG) command is used in a CL program or REXX procedure to retrieve a specified predefined message from a message file and to copy it into CL variables. Substitution values can be specified in the MSGDTA parameter (as a single character string containing one or more concatenated message data fields) to replace the substitution variables in the predefined message text. The program can later write the message to an output device file to be printed, for example.
</p>
<p>The CL prompt for this command lists the minimum length for retrieved variables next to the parameters that have a minimum length. For character variables, a single number is shown. For decimal variables, two numbers are shown. The first number indicates the minimum variable length and the second number indicates the minimum number of decimal positions.
</p>
<p><b>Restrictions:</b> The user of this command must have use (*USE) authority for the message file and *USE authority for the library in which the message file is located.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div>
<h3><a name="RTVMSG.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="#RTVMSG.MSGID"><b>MSGID</b></a></td>
<td valign="top">Message identifier</td>
<td valign="top"><i>Name</i></td>
<td valign="top">Required, Positional 1</td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#RTVMSG.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">Required, Positional 2</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="#RTVMSG.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="#RTVMSG.MSG"><b>MSG</b></a></td>
<td valign="top">CL var for 1st level text</td>
<td valign="top"><i>Character value</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RTVMSG.MSGLEN"><b>MSGLEN</b></a></td>
<td valign="top">CL var for MSGLEN (5 0)</td>
<td valign="top"><i>Decimal number</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RTVMSG.SECLVL"><b>SECLVL</b></a></td>
<td valign="top">CL var for 2nd level text</td>
<td valign="top"><i>Character value</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RTVMSG.SECLVLLEN"><b>SECLVLLEN</b></a></td>
<td valign="top">CL var for SECLVLLEN (5 0)</td>
<td valign="top"><i>Decimal number</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RTVMSG.SEV"><b>SEV</b></a></td>
<td valign="top">CL var for SEV (2 0)</td>
<td valign="top"><i>Decimal number</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RTVMSG.ALROPT"><b>ALROPT</b></a></td>
<td valign="top">CL var for ALROPT (9)</td>
<td valign="top"><i>Character value</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RTVMSG.LOGPRB"><b>LOGPRB</b></a></td>
<td valign="top">CL var for LOGPRB (1)</td>
<td valign="top"><i>Character value</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RTVMSG.CCSID"><b>CCSID</b></a></td>
<td valign="top">Convert to CCSID</td>
<td valign="top">1-65535, *HEX, <b><u>*JOB</u></b></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RTVMSG.MDTACCSID"><b>MDTACCSID</b></a></td>
<td valign="top">Message data CCSID</td>
<td valign="top">1-65535, *HEX, <b><u>*JOB</u></b></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RTVMSG.TXTCCSID"><b>TXTCCSID</b></a></td>
<td valign="top">CL var for text CCSID (5 0)</td>
<td valign="top"><i>Decimal number</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RTVMSG.DTACCSID"><b>DTACCSID</b></a></td>
<td valign="top">CL var for data CCSID (5 0)</td>
<td valign="top"><i>Decimal number</i></td>
<td valign="top">Optional</td>
</tr>
</table>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
</div>
<div> <a name="RTVMSG.MSGID"></a>
<h3>Message identifier (MSGID)</h3>
<p>Specifies the message identifier of the predefined message that is being retrieved from the specified message file.
</p>
<p>This is a required parameter.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.MSGF"></a>
<h3>Message file (MSGF)</h3>
<p>Specifies the message file that contains the predefined message to be retrieved.
</p>
<p>This is a required 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 containing the message to be retrieved.
</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="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.MSGDTA"></a>
<h3>Message data field values (MSGDTA)</h3>
<p>Specifies the substitution values that are used in the retrieved message if the predefined message contains substitution variables. Either a character string or a CL variable containing the character string can be specified.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.MSG"></a>
<h3>CL var for 1st level text (MSG)</h3>
<p>Specifies the name of the CL character variable in the program into which the text of the retrieved message is copied. If a CL variable name is not specified, the message text is not copied into the program. This is a variable length field, but most messages are designed to be less than 132 characters long.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.MSGLEN"></a>
<h3>CL var for MSGLEN (5 0) (MSGLEN)</h3>
<p>Specifies the name of the CL decimal variable in the program into which the total length of the message text available to be retrieved is copied.
</p>
<p>The specified variable must be a decimal variable that has a length of five digits.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.SECLVL"></a>
<h3>CL var for 2nd level text (SECLVL)</h3>
<p>Specifies the name of the CL character variable in the program into which the second level message, or message help, of the retrieved message is copied. If a variable name is not specified, the message help is not copied into the program. This is a variable length field, but most message help is designed to be less than 3000 characters long.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.SECLVLLEN"></a>
<h3>CL var for SECLVLLEN (5 0) (SECLVLLEN)</h3>
<p>Specifies the name of the CL decimal variable in the program into which the total length of the message help being retrieved is copied.
</p>
<p>The specified variable must be a decimal variable that has a length of five positions.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.SEV"></a>
<h3>CL var for SEV (2 0) (SEV)</h3>
<p>Specifies the name of the CL decimal variable into which the severity code of the retrieved message is copied. The specified variable must be a decimal variable that has a length of two positions. If a variable name is not specified, the severity code of the retrieved message is not copied into the program.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.ALROPT"></a>
<h3>CL var for ALROPT (9) (ALROPT)</h3>
<p>Specifies the name of the CL variable into which the alert option of the retrieved message is copied. The variable must be a character variable nine positions long. If a character variable is not specified, the alert option of the retrieved message is not copied into the program.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.LOGPRB"></a>
<h3>CL var for LOGPRB (1) (LOGPRB)</h3>
<p>Specifies whether the message will be logged in the problem log. The variable must be a character variable one position long.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.CCSID"></a>
<h3>Convert to CCSID (CCSID)</h3>
<p>Specifies the coded character set identifier (CCSID) in which you want your message text returned. This applies only to text returned in the MSG and SECLVL parameters. When replacement data is substituted into the text returned in the MSG or SECLVL parameters, only the part of the replacement data that is defined as a character that can be converted (*CCHAR) is converted. The rest of the replacement data will not be converted. For more information about the *CCHAR field, see the Add Message Description (ADDMSGD) command.
</p>
<dl>
<dt><b><u>*JOB</u></b></dt>
<dd>The retrieved message description is converted to the CCSID of the job before being returned.
</dd>
<dt><b>*HEX</b></dt>
<dd>The retrieved message description is not converted before being returned.
</dd>
<dt><b><i>coded-character-set-identifier</i></b></dt>
<dd>Specify the CCSID that you want your message description converted to before it is returned.
<p>
<b>Note: </b>The valid values range from 1 through 65535. See the Globalization information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter for a list of valid CCSID values. Only CCSIDs that you can change your job to are accepted.
</p>
<p>For more information on 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>
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.MDTACCSID"></a>
<h3>Message data CCSID (MDTACCSID)</h3>
<p>Specifies the CCSID that the supplied message data is assumed to be in. This only applies to the parts of the replacement data that are defined as *CCHAR. The rest of the replacement data will never be converted and is assumed to have a CCSID of 65535.
</p>
<dl>
<dt><b><u>*JOB</u></b></dt>
<dd>The message data supplied is assumed to be in the CCSID of the job running this command.
</dd>
<dt><b>*HEX</b></dt>
<dd>The message data supplied is assumed to be 65535 and is never converted.
</dd>
<dt><b><i>coded-character-set-identifier</i></b></dt>
<dd>The message data supplied is assumed to be in the CCSID specified. Valid values range from 1 through 65535. 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="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.TXTCCSID"></a>
<h3>CL var for text CCSID (5 0) (TXTCCSID)</h3>
<p>Specifies the name of the CL variable, if any, used to return the coded character set identifier (CCSID) associated with the text returned by the MSG and SECLVL parameters. The CCSID that the message description is stored in is returned if the one of the following occurs:
</p>
<ul>
<li>If a conversion error occurs.
</li>
<li>If the job has a CCSID of 65535 and you did not specify the CCSID parameter.
</li>
<li>If you specify *JOB for the CCSID parameter.
</li>
<li>If the CCSID you requested the text to be converted to is 65535.
</li>
</ul>
<p>Otherwise, the CCSID you wanted the text converted to is returned. If you do not want the text converted before it is returned to you but you do want to know the CCSID that the message description is stored in, specify 65535 for the CCSID parameter. The CCSID that the message description is stored in is returned in the TXTCCSID parameter. You can also check for a conversion error by comparing the CCSID you passed in against the TXTCCSID returned. If they are not equal and they are not 65535, a conversion error occurred.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RTVMSG.DTACCSID"></a>
<h3>CL var for data CCSID (5 0) (DTACCSID)</h3>
<p>Specifies the name of the CL variable, if any, used to return the coded character set identifier (CCSID) associated with the replacement data defined as *CCHAR. All other replacement data is not converted before it is returned. The CCSID specified for the MDTACCSID parameter is returned if the one of the following occurs:
</p>
<ul>
<li>If a conversion error occurs.
</li>
<li>If the job has a CCSID of 65535 and you did not specify the CCSID parameter.
</li>
<li>If you specify *JOB for the CCSID parameter.
</li>
<li>If the CCSID you requested the text to be converted to is 65535.
</li>
</ul>
<p>Otherwise the CCSID you wanted the text converted to is returned. When there is no *CCHAR replacement data in the text, 65535 is returned. You can check for a conversion error by comparing the CCSID you passed in against the DTACCSID returned. If they are not equal and they are not 65535, a conversion error occurred.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="RTVMSG.COMMAND.EXAMPLES">Examples</a> </h3>
<p><b>Example 1: Replacing Substitution Variables</b>
</p>
<p>
<pre>
RTVMSG MSGID(UIN0145) MSGF(INVN) MSG(&amp;WORK)
MSGDTA('any old time')
</pre>
</p>
<p>This command retrieves the message text of the message UIN0145 stored in the INVN message file. The retrieved text is copied into the CL variable &amp;WORK after the substitution variables are replaced with the values <i>any</i>, <i>old</i>, and <i>time</i>. This example assumes that the substitution variables &amp;1, &amp;2, and &amp;3 have been defined in the message as character variables, each 4 characters long.
</p>
<p><b>Example 2: Retrieving First-Level and Second-Level Message Text</b>
</p>
<p>
<pre>
RTVMSG MSGID(UIN0150) MSGF(INV) MSG(&amp;MSG)
SECLVL(&amp;SECLVL)
</pre>
</p>
<p>This command retrieves the first-level message text and second-level message text of the message UIN0150, which is stored in message file INV, and moves it into the CL variables &amp;MSG and &amp;SECLVL.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="RTVMSG.ERROR.MESSAGES">Error messages</a> </h3>
<p><b><u>*ESCAPE Messages</u></b>
</p>
<dl>
<dt><b>CPF2401</b></dt>
<dd>Not authorized to library &amp;1.
</dd>
<dt><b>CPF2407</b></dt>
<dd>Message file &amp;1 in &amp;2 not found.
</dd>
<dt><b>CPF2411</b></dt>
<dd>Not authorized to message file &amp;1 in &amp;2.
</dd>
<dt><b>CPF247E</b></dt>
<dd>CCSID &amp;1 is not valid.
</dd>
<dt><b>CPF2471</b></dt>
<dd>Length of field not valid.
</dd>
<dt><b>CPF2499</b></dt>
<dd>Message identifier &amp;1 not allowed.
</dd>
<dt><b>CPF2531</b></dt>
<dd>Message file &amp;1 in &amp;2 damaged for &amp;3.
</dd>
<dt><b>CPF2547</b></dt>
<dd>Damage to message file QCPFMSG.
</dd>
<dt><b>CPF2548</b></dt>
<dd>Damage to message file &amp;1 in &amp;2.
</dd>
<dt><b>CPF8126</b></dt>
<dd>Message file &amp;4 in &amp;9 damaged.
</dd>
<dt><b>CPF9830</b></dt>
<dd>Cannot assign library &amp;1.
</dd>
</dl>
<p><b><u>*STATUS Messages</u></b>
</p>
<dl>
<dt><b>CPF2419</b></dt>
<dd>Message identifier &amp;1 not found in message file &amp;2 in &amp;3.
</dd>
</dl>
<p><b><u>*NOTIFY Messages</u></b>
</p>
<dl>
<dt><b>CPF2465</b></dt>
<dd>Replacement text of message &amp;1 in &amp;2 in &amp;3 not valid for format specified.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#RTVMSG.Top_Of_Page">Top</a></td></tr>
</table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink