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

441 lines
18 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>Remove Message (RMVMSG)</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="RMVMSG.Top_Of_Page"></a>
<h2>Remove Message (RMVMSG)</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="#RMVMSG.PARAMETERS.TABLE">Parameters</a><br>
<a href="#RMVMSG.COMMAND.EXAMPLES">Examples</a><br>
<a href="#RMVMSG.ERROR.MESSAGES">Error messages</a></td>
</tr>
</table>
<div> <a name="RMVMSG"></a>
<p>The Remove Message (RMVMSG) command is used by a program to remove the specified message, or a group of messages, from the specified message queue. If an unanswered inquiry message is removed, the default reply is sent before it is removed. If the specified message queue is not allocated to the job in which this command is issued and no other job has the message queue allocated, it is implicitly allocated by this command for the duration of the command.
</p>
<p><b>Restrictions:</b>
</p>
<ol>
<li>To remove a message from the message queue, you must have change (*CHANGE) authority for the queue and use (*USE) authority for the library in which the queue is located.
</li>
</ol>
</div>
<table width="100%">
<tr><td align="right"><a href="#RMVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div>
<h3><a name="RMVMSG.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" rowspan="6"><a href="#RMVMSG.PGMQ"><b>PGMQ</b></a></td>
<td valign="top">Call stack entry message queue</td>
<td valign="top">Single values: *ALLINACT, *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>*SAME</u></b>, *PRV</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="#RMVMSG.MSGQ"><b>MSGQ</b></a></td>
<td valign="top">Message queue</td>
<td valign="top">Single values: *PGMQ<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</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="#RMVMSG.MSGKEY"><b>MSGKEY</b></a></td>
<td valign="top">Message key</td>
<td valign="top"><i>Character value</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RMVMSG.CLEAR"><b>CLEAR</b></a></td>
<td valign="top">Clear</td>
<td valign="top"><b><u>*BYKEY</u></b>, *ALL, *KEEPUNANS, *OLD, *NEW</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RMVMSG.RMVEXCP"><b>RMVEXCP</b></a></td>
<td valign="top">Remove unhandled exception</td>
<td valign="top"><b><u>*YES</u></b>, *NO</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#RMVMSG.RJTDFTRPY"><b>RJTDFTRPY</b></a></td>
<td valign="top">Reject default reply</td>
<td valign="top"><b><u>*NOALWRJT</u></b>, *ALWRJT</td>
<td valign="top">Optional</td>
</tr>
</table>
<table width="100%">
<tr><td align="right"><a href="#RMVMSG.Top_Of_Page">Top</a></td></tr>
</table>
</div>
<div> <a name="RMVMSG.PGMQ"></a>
<h3>Call stack entry message queue (PGMQ)</h3>
<p>Specifies the call message queue from which the messages are to be removed. Messages can be removed from the external queue (*EXT) or from a message queue associated with a call stack entry.
</p>
<p><b>Notes:</b>
</p>
<ol>
<li>If CLEAR(*BYKEY) is specified, the PGMQ parameter is ignored.
</li>
<li>If values are specified for this parameter, values cannot be specified for the <b>Message queue (MSGQ)</b> parameter.
</li>
</ol>
<p><b>Single values</b>
</p>
<dl>
<dt><b>*ALLINACT</b></dt>
<dd>All messages for inactive call stack entries are to be removed from the user's job message queue. If this value is specified, *ALL must be specified for the <b>Clear (CLEAR)</b> parameter.
</dd>
<dt><b>*EXT</b></dt>
<dd>The message is to be removed from the external message queue of the job.
</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>*SAME</u></b></dt>
<dd>The message is to be removed from the message queue of the program or procedure identified by the second element of this parameter.
</dd>
<dt><b>*PRV</b></dt>
<dd>The message is to be removed from the message queue of the program or procedure that called the program or procedure identified by the second element of this parameter.
<p>
<b>Note: </b>If the message queue previous to the one identified by the second value is for an ILE program entry procedure (PEP), the message will be removed from the message queue immediately previous to the PEP message queue; effectively this would be two message queues previous to the one identified by the program or qualified procedure.
</p>
</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>
</div>
<table width="100%">
<tr><td align="right"><a href="#RMVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RMVMSG.MSGQ"></a>
<h3>Message queue (MSGQ)</h3>
<p>Specifies the message queue from which one or more messages are to be removed. If this parameter is specified, the <b>Call stack entry message queue (PGMQ)</b> parameter cannot be specified.
</p>
<p><b>Single values</b>
</p>
<dl>
<dt><b>*PGMQ</b></dt>
<dd>The call message queue specified for the <b>Call stack entry message queue (PGMQ)</b> parameter is the only queue from which the messages are to be removed. If CLEAR(*KEEPUNANS) is specified, MSGQ(*PGMQ) cannot be specified.
</dd>
</dl>
<p><b>Qualifier 1: Message queue</b>
</p>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the message queue from which one or more messages are to be removed.
</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 library is specified as the current library for the job, 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="#RMVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RMVMSG.MSGKEY"></a>
<h3>Message key (MSGKEY)</h3>
<p>Specifies the name of the control language (CL) variable that contains the message reference key of the message to be removed. This parameter can be specified only if CLEAR(*BYKEY) is specified.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RMVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RMVMSG.CLEAR"></a>
<h3>Clear (CLEAR)</h3>
<p>Specifies whether one or more messages are to be removed from the queue.
</p>
<dl>
<dt><b><u>*BYKEY</u></b></dt>
<dd>The message identified by the control language (CL) variable named in the <b>Message key (MSGKEY)</b> parameter is to be removed from the message queue.
</dd>
<dt><b>*ALL</b></dt>
<dd>All messages are to be removed from the specified message queue.
</dd>
<dt><b>*KEEPUNANS</b></dt>
<dd>All messages except unanswered inquiry messages are to be removed from the specified message queue. If this value is specified, MSGQ(*PGMQ) cannot be specified, a message queue name must be specified.
</dd>
<dt><b>*OLD</b></dt>
<dd>All old messages in the specified message queue are to be removed from the queue.
</dd>
<dt><b>*NEW</b></dt>
<dd>All new messages in the specified message queue are to be removed from the queue.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#RMVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RMVMSG.RMVEXCP"></a>
<h3>Remove unhandled exception (RMVEXCP)</h3>
<p>Specifies the action to be taken when an unhandled exception message is found. An unhandled exception message is an escape, notify, or status message that has been sent to an ILE procedure. When this command is run, the ILE procedure has not yet taken action to tell the system that the exception is handled. One action that the ILE procedure can take is to call a CL program that will remove the exception message. More information on actions that an ILE procedure can take to handle an exception is in the ILE Concepts book, SC41-5606.
</p>
<p>This parameter is valid only when working with a message queue that is associated with a call stack entry for an ILE procedure. This parameter is ignored when working with a message queue associated with a call stack entry for an OPM (original program model) program.
</p>
<dl>
<dt><b><u>*YES</u></b></dt>
<dd>The unhandled exception message on the specified message queue is removed. As a result, the exception is handled.
</dd>
<dt><b>*NO</b></dt>
<dd>The unhandled exception message on the specified message queue is not removed. The message remains on the queue as an unhandled exception message.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#RMVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="RMVMSG.RJTDFTRPY"></a>
<h3>Reject default reply (RJTDFTRPY)</h3>
<p>Removing an unanswered inquiry message causes the default reply to be sent to the inquiry message. This value indicates whether a reply handling exit program will be allowed to reject a default reply that is sent as a result of using this command. A reply handling exit program can be registered via the system registration facility for exit point QIBM_QMH_REPLY_INQ.
</p>
<dl>
<dt><b><u>*NOALWRJT</u></b></dt>
<dd>A reply handling exit program will not be allowed to reject a default reply.
</dd>
<dt><b>*ALWRJT</b></dt>
<dd>A reply handling exit program will be allowed to reject a default reply. If an exit program rejects the reply, message CPD2476 (Reply rejected by a reply handling exit program) will be sent as a diagnostic message to the program using this command. The CPD2476 will be followed by a CPF2422 (Reply not valid) escape message that the program using this command should monitor for to handle and recover from error situations.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#RMVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="RMVMSG.COMMAND.EXAMPLES">Examples</a> </h3>
<p><b>Example 1: Removing a Message</b>
</p>
<p>
<pre>
RMVMSG MSGQ(SMITH) MSGKEY(&amp;KEY)
</pre>
</p>
<p>This command removes the message with the reference key specified in the CL variable &amp;KEY from the message queue named SMITH.
</p>
<p><b>Example 2: Keeping Unanswered Messages</b>
</p>
<p>
<pre>
RMVMSG MSGQ(SMITH) CLEAR(*KEEPUNANS)
</pre>
</p>
<p>This command removes all messages except the unanswered inquiry messages from the message queue named SMITH.
</p>
<p><b>Example 3: Removing Messages Using a Partial Procedure Name</b>
</p>
<p>
<pre>
RMVMSG PGMQ(*SAME 'PROCESS_ORDER&gt;&gt;&gt;') CLEAR(*ALL)
</pre>
</p>
<p>This command removes all messages from the most recent procedure whose name begins with PROCESS_ORDER.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#RMVMSG.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="RMVMSG.ERROR.MESSAGES">Error messages</a> </h3>
<p><b><u>*ESCAPE Messages</u></b>
</p>
<dl>
<dt><b>CPF24A6</b></dt>
<dd>Value for messages to remove not valid.
</dd>
<dt><b>CPF24AD</b></dt>
<dd>Messages to remove must be *ALL if program message queue is *ALLINACT.
</dd>
<dt><b>CPF2401</b></dt>
<dd>Not authorized to library &amp;1.
</dd>
<dt><b>CPF2403</b></dt>
<dd>Message queue &amp;1 in &amp;2 not found.
</dd>
<dt><b>CPF2407</b></dt>
<dd>Message file &amp;1 in &amp;2 not found.
</dd>
<dt><b>CPF2408</b></dt>
<dd>Not authorized to message queue &amp;1.
</dd>
<dt><b>CPF241A</b></dt>
<dd>Clear option &amp;1 in system program is not valid.
</dd>
<dt><b>CPF2410</b></dt>
<dd>Message key not found in message queue &amp;1.
</dd>
<dt><b>CPF2411</b></dt>
<dd>Not authorized to message file &amp;1 in &amp;2.
</dd>
<dt><b>CPF2419</b></dt>
<dd>Message identifier &amp;1 not found in message file &amp;2 in &amp;3.
</dd>
<dt><b>CPF2422</b></dt>
<dd>Reply not valid.
</dd>
<dt><b>CPF2450</b></dt>
<dd>Work station message queue &amp;1 not allocated to job.
</dd>
<dt><b>CPF2451</b></dt>
<dd>Message queue &amp;1 is allocated to another job.
</dd>
<dt><b>CPF247A</b></dt>
<dd>Call stack entry not found.
</dd>
<dt><b>CPF2477</b></dt>
<dd>Message queue &amp;1 currently in use.
</dd>
<dt><b>CPF2479</b></dt>
<dd>Call stack entry not found.
</dd>
<dt><b>CPF2483</b></dt>
<dd>Message file currently in use.
</dd>
<dt><b>CPF2499</b></dt>
<dd>Message identifier &amp;1 not allowed.
</dd>
<dt><b>CPF8127</b></dt>
<dd>&amp;8 damage on message queue &amp;4 in &amp;9. VLIC log-&amp;7.
</dd>
<dt><b>CPF8176</b></dt>
<dd>Message queue for device description &amp;4 damaged.
</dd>
<dt><b>CPF9830</b></dt>
<dd>Cannot assign library &amp;1.
</dd>
<dt><b>CPF9838</b></dt>
<dd>User profile storage limit exceeded.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#RMVMSG.Top_Of_Page">Top</a></td></tr>
</table>
</body>
</html>