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

713 lines
22 KiB
HTML
Raw Normal View History

Add readme and dist folders
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">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Remove Program Messages (QMHRMVPM) API</title>
<!-- Begin Header Records ========================================== -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- MH1TEMP SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
<!-- RCHVMW2 on 26 Jan 1999 at 10:37:34 -->
<!--File Edited Oct 2001 by v2cdijab -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Remove Program Messages (QMHRMVPM) API</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Call stack entry</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="25%">Char(*) or Pointer</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Call stack counter</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Message key</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Messages to remove</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group 1:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">6</td>
<td align="left" valign="top" width="50%">Length of call stack entry</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="25%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Call stack entry qualification</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Remove unhandled exceptions</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group 2:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">9</td>
<td align="left" valign="top" width="50%">Call stack entry data type</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="25%">Char(10)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group 3:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">10</td>
<td align="left" valign="top" width="50%">Allow default
reply rejection</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="25%">Char(10)
</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Remove Program Messages (QMHRMVPM) API removes messages from call
message queues and the external message queue. The removed instances of the
messages are no longer available for you to work with. However, other instances
of the messages might still exist in other message queues, and the definitions
of predefined messages are still in the message files.</p>
<p>To remove messages from nonprogram message queues, see <a href=
"QMHRMVM.htm">Remove Nonprogram Messages</a> (QMHRMVM) API.</p>
<p>You can use the QMHRMVPM API to streamline program message handling. Assume
that a program receives several diagnostic messages and an escape message from
a called program. The program handles the escape message without receiving the
diagnostic messages. The program could then use the QMHRMVPM API to remove all
the new messages it has not received, including the unneeded diagnostic
messages. This can prevent confusion if the program gets another escape message
and must receive the diagnostic messages associated with the new escape to
analyze the error.</p>
<p>In a multithreaded job messages can be removed from call message queues
within the thread that calls this API, and messages sent from within the same
thread can be removed from the external message queue. Messages on call message
queues in other threads or sent to the external message queue from other
threads cannot be removed.</p>
<br>
<h3>Authorities and Locks</h3>
<p>None.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Call stack entry</strong></dt>
<dd>INPUT; CHAR(*) or Pointer
<p>The call stack entry from whose message queue the message are to be removed,
or the call stack entry to start counting from when using the call stack
counter parameter. The call stack entry you specify must be in the call stack
or you can specify the external message queue instead of a call stack
entry.</p>
<p>You can specify a call stack entry by providing the name of the OPM program
or ILE procedure running in the entry, by providing a pointer to the call stack
entry, or by using one of the following special values:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*</em></td>
<td align="left" valign="top">The message queue of the current call stack entry
(that is, the call stack entry removing the messages).</td>
</tr>
<tr>
<td align="left" valign="top"><em>*ALLINACT</em></td>
<td align="left" valign="top">All message queues for inactive call stack
entries. The messages to remove parameter must specify *ALL. The call stack
counter parameter is ignored.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*EXT</em></td>
<td align="left" valign="top">The external message queue. The call stack
counter parameter is ignored.</td>
</tr>
</table>
<p>If you specify a message key and the messages to remove parameter specifies
*BYKEY, this parameter is ignored.</p>
<p>If the call stack entry is to be identified by pointer, the pointer that is
specified must address a valid call stack entry within the same job as the one
the API is used in. Alternatively, the pointer can be set to Null. The Optional
Parameter Group 1 must be used and the Length of Call stack entry parameter
must be set to 16. In addition, the Optional Parameter Group 2 must also be
used and the Call stack entry format parameter must be set to *PTR.</p>
<p>If the pointer provided is set to Null, this indicates that the call stack
entry is the one in which the API is being used.</p>
<p>If the pointer does not address a valid call stack entry or is not a Null
pointer, the error message CPF24C5 is sent to the user of the API.</p>
<p>The call stack entry can be a nested procedure name from 1 through 4096
characters in length. When specifying nested procedures, each procedure name
must be separated by a colon, and the outermost procedure is identified first
followed by the procedures it contains. The innermost procedure is the last
procedure identified in the string.</p>
<p>The call stack entry can be a partial name. To specify a partial name, place
three less-than signs (&lt;&lt;&lt;) at the beginning of the call stack entry
identifier, or place three greater-than signs (&gt;&gt;&gt;) at the end of the
call stack entry identifier, or place both the less-than signs and the
greater-than signs at their respective ends of the call stack entry identifier.
The value for the call stack entry excluding the less-than signs and the
greater-than signs is used to search backward through the stack for the
requested call stack entry name.</p>
<p>When searching for a partial call stack entry name:</p>
<ul>
<li>If the less-than signs (&lt;&lt;&lt;) are specified only at the beginning
of the call stack entry name, the less-than signs are truncated and the
remaining character string is right-justified. The remaining string is then
compared to the current call stack entry on the call stack. The comparison
starts at the end of the call stack entry name and backwardly compares the
number of characters in the specified string.</li>
<li>If the greater-than signs (&gt;&gt;&gt;) are specified only at the end of
the call stack entry name, the greater-than signs are truncated. The remaining
character string is compared to the current call stack entry on the call stack.
The comparison starts at position 1 of the call stack entry name and compares
the number of characters in the specified string.</li>
<li>If the less-than signs (&lt;&lt;&lt;) are specified at the beginning of the
call stack entry name and the greater-than signs (&gt;&gt;&gt;) are specified
at the end of the call stack entry name, both the less-than signs and the
greater-than signs are truncated. The remaining characters are used to scan and
to compare the entire length of the specified string and the current call stack
entry on the call stack.</li>
</ul>
<p><strong>Note:</strong> If the optional parameters Length of to call stack
entry and To call stack entry data type are not specified, this parameter is
assumed to be CHAR(10).</p>
</dd>
<dt><strong>Call stack counter</strong></dt>
<dd>INPUT; BINARY(4)
<p>A number identifying the location in the call stack of the call stack entry
from whose message queue the messages are to be removed. The number is relative
to the call stack entry identified by the Call stack entry parameter. It
indicates how many calls up the call stack the target entry is from the one
identified by the Call stack entry parameter.Valid values follow:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Remove the messages from the message queue of the
call stack entry specified in the Call stack entry parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Remove the messages from the message queue of the
call stack entry that is one earlier than the entry identified by the Call
stack entry parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>n (any positive number)</em></td>
<td align="left" valign="top">Remove the messages from the message queue of the
nth call stack entry up the stack from the call stack entry specified in the
Call stack entry parameter.
<p>You can use any positive number that does not exceed the actual number of
call stack entries in the call stack, excluding the external message queue.</p>
</td>
</tr>
</table>
<p>This parameter is ignored in these cases:</p>
<ul>
<li>When the program message queue parameter specifies all queues for inactive
call stack entries (*ALLINACT) or the external message queue (*EXT).</li>
<li>When you specify a message key and the messages to remove parameter
specifies *BYKEY.</li>
</ul>
<br>
</dd>
<dt><strong>Message key</strong></dt>
<dd>INPUT; CHAR(4)
<p>If the messages to remove parameter specifies *BYKEY or *SCOPE, the key to
the single message being removed. (The key is assigned by the command or API
that sends the message.) The call stack entry and call stack counter
parameters are ignored when the message to remove parameter specifies *BYKEY.
</p>
<p>If the messages to remove parameter does not specify *BYKEY or *SCOPE, you
must use blanks for this parameter.</p>
<p>When the messages to remove parameter specifies *BYKEY, the call stack entry
parameter and the call stack counter parameters are ignored, and the message
will be removed without regard to the call message queue that contains the
message.
This is useful if the message was sent to a call stack entry that is no longer
in the call stack.</p>
<p>When the messages to remove parameter specifies *SCOPE, the call stack
entry and call stack counter parameters must specify the call message queue
that contains the scope message.</p>
</dd>
<dt><strong>Messages to remove</strong></dt>
<dd>INPUT; CHAR(10)
<p>The message or group of messages being removed. Valid values follow:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*ALL</em></td>
<td align="left" valign="top">All messages in the call message queue.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*BYKEY</em></td>
<td align="left" valign="top">The single message specified in the message key
parameter. If the message to be removed is a *SCOPE message, the *SCOPE value
must be used instead of *BYKEY.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*KEEPRQS</em></td>
<td align="left" valign="top">All messages in the call message queue except
requests.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NEW</em></td>
<td align="left" valign="top">All new messages in the call message queue. New
messages are those that have not been received.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*OLD</em></td>
<td align="left" valign="top">All old messages in the call message queue. Old
messages are those that have already been received. The *SCOPE type message
identified by the message key specified in the Message key parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*SCOPE</em></td>
<td align="left" valign="top">The scope message specified in the message key
parameter.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 1</h3>
<dl>
<dt><strong>Length of call stack entry</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the value for the call stack entry parameter. Valid values for
this parameter are as follows:</p>
<ul>
<li>1 through 4096 if partial name indicators are not used.</li>
<li>16 if the call stack entry parameter is a pointer.</li>
<li>1 through 4102 if partial name indicators are used.</li>
</ul>
<p><strong>Note:</strong> The actual length of the call stack entry name cannot
exceed 4096 characters. If this parameter is not used, the value for the call
stack entry parameter is assumed to be 10 characters in length.</p>
</dd>
<dt><strong>Call stack entry qualification</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the module and the ILE program or service program to further
qualify the procedure name specified by the Call stack entry parameter. The
first 10 characters specify the module name, and the second 10 characters
specify the ILE program name or service program name. If this parameter is not
used, only the Call stack entry parameter is used to determine the call stack
entry. The following special value may be used:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*NONE</em></td>
<td align="left" valign="top">This value is used for the module or ILE program
name or service program name, or both. When *NONE is specified for one of the
names, then that name is not used when searching for the call stack entry. If
*NONE is specified for both names, only the Call stack entry parameter is used
to identify the call stack entry.</td>
</tr>
</table>
<p>If the call stack entry is to be identified by pointer, this parameter must
still be passed to the API but both the module and program qualifiers must be
specified as *NONE. When a pointer is used, the module and program name
qualification is not applicable.</p>
<p>The module name and bound program name should be used only when identifying
the call stack entry for an ILE procedure. When identifying the entry for an
OPM program, the Optional Parameter Group 1 should either not be used or the
module and program qualifiers should be specified as *NONE.</p>
</dd>
<dt><strong>Remove unhandled exceptions</strong></dt>
<dd>INPUT; CHAR(10)
<p>Whether to remove unhandled exceptions in the identified call message queue.
The exception handling support for some languages allows exceptions to not be
handled. Valid values follow:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*YES</em></td>
<td align="left" valign="top">Remove any unhandled exceptions in the identified
call message queue. This is the default when this parameter is not used.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NO</em></td>
<td align="left" valign="top">Do not remove any unhandled exceptions in the
identified call message queue.</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 2</h3>
<p>This parameter group is used when the Call stack entry parameter is
specified as a pointer.</p>
<dl>
<dt><strong>Call stack entry data type</strong></dt>
<dd>INPUT; CHAR(10)
<p>Whether the value of the call stack entry parameter is a character string (a
name or special value) or a pointer. Use one of the following special
values;</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*CHAR</em></td>
<td align="left" valign="top">Value of the parameter is a character string
(name or special value)</td>
</tr>
<tr>
<td align="left" valign="top"><em>*PTR</em></td>
<td align="left" valign="top">Value of the parameter is a pointer.</td>
</tr>
</table>
<p>If the above optional parameter is not specified, it is assumed that the
value of the call stack entry parameter is a character string.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 3</h3>
<dl>
<dt><strong>Allow default reply rejection</strong></dt>
<dd>INPUT; CHAR(10)
<p>Removing an unanswered inquiry 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
function. A reply handling exit program can be registered via
the system registration facility for exit point
QIBM_QMH_REPLY_INQ. If the parameter is not specified, a value
of *NO is used. Valid values are: </p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*NO</em></td>
<td align="left" valign="top">A reply handling exit program will
not be allowed to reject a default reply.
</td>
</tr>
<tr>
<td align="left" valign="top"><em>*YES</em></td>
<td align="left" valign="top">A reply handling exit program will
be allowed to reject a default reply. If an exit program rejects
the reply, a CPD2476 (Reply rejected by a reply handling exit
program) will be sent as a diagnostic message to the program
using this function. The CPD2476 will be followed by a
CPF2422 (Reply not valid) escape message that the program using
this function should monitor for to handle and recover from
error situations.<br>
</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top" width="15%">CPF24AD E</td>
<td align="left" valign="top" width="85%">Messages to remove must be *ALL if
program message queue is *ALLINACT.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24AE E</td>
<td align="left" valign="top">Message key and messages to remove are mutually
dependent.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24A3 E</td>
<td align="left" valign="top">Value for call stack counter parameter not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24A6 E</td>
<td align="left" valign="top">Value for messages to remove not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24BF E</td>
<td align="left" valign="top">Module or bound-program name is blank.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B7 E</td>
<td align="left" valign="top">Value &amp;1 for call stack entry name length not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B8 E</td>
<td align="left" valign="top">Value &amp;1 for remove unhandled exceptions not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24C5 E</td>
<td align="left" valign="top">Pointer to call stack entry not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24C6 E</td>
<td align="left" valign="top">Value of To call stack entry data type parameter
not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF241A E</td>
<td align="left" valign="top">Clear option &amp;1 in system program is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2410 E</td>
<td align="left" valign="top">Message key not found in message queue
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2422 E</td>
<td align="left" valign="top">Reply not valid.
</td>
</tr>
<tr>
<td align="left" valign="top">CPF247A E</td>
<td align="left" valign="top">Call stack entry not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2479 E</td>
<td align="left" valign="top">Call stack entry not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C3A E</td>
<td align="left" valign="top">Value for parameter &amp;2 for API &amp;1 not valid.
</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C36 E</td>
<td align="left" valign="top">Number of parameters, &amp;1, entered for this
API was not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R1.1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"mh1.htm">Message Handling APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue Copy Permalink