ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/QMHPRMM.htm

579 lines
16 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">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Promote Message (QMHPRMM) 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 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited Sept 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>Promote Message (QMHPRMM) 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%">Invocation pointer</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">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">Message identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(7)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Qualified message file name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Message data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Length of message data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Message type</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Message severity</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="left" valign="top">Log option</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="left" valign="top">Priority</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="left" valign="top">New message key</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(4)</td>
</tr>
<tr>
<td align="center" valign="top">13</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;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Promote Message (QMHPRMM) API promotes an escape or status message that
has been sent to a call stack entry. The API replaces the message with a new
escape or status message to the same call stack entry. An escape message may be
promoted to another escape message or to a status message. A status message may
be promoted to an escape message or to another status message. The stored
severity of the new message may be overridden. The new message may be added to
the job log, and the initial priority of the new message may be changed.</p>
<p>The message to be promoted must be an active escape message or status
message, existing on the message queue of the specified call stack entry. This
API causes the existing message to be handled. The source call stack entry of
the new message is the same as the source call stack entry of the promoted
message. The message key of the new message is returned to the caller of this
API. If the new message is not monitored by the target call stack entry, an
error may be returned to the caller of this API and the new message key may not
be returned.</p>
<p>In a multithreaded job only messages on a call message queue in the thread
that calls this API can be promoted. This API cannot promote messages on call
message queues in other threads.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Message File Authority</em></dt>
<dd>*USE</dd>
<dt><em>Message File Library Authority</em></dt>
<dd>*EXECUTE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Invocation pointer</strong></dt>
<dd>INPUT; POINTER
<p>The invocation pointer to the call stack entry receiving the escape message
or status message that is to be promoted. When the call stack counter parameter
is other than 0, the invocation pointer points to the call stack entry from
which to start counting earlier in the call stack. This locates the call stack
entry that received the escape message or status message being promoted. The
call stack entry you specify must be in the call stack. A null invocation
pointer may be specified. If this pointer is not set, the call stack entry that
called the QMHPRMM API is used.</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
receiving the escape or status message that is to be promoted. The number is
relative to the call stack entry specified in the invocation pointer parameter.
It indicates how many calls up the call stack the call stack entry is from the
one specified in the invocation pointer 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">Promotes the message that was sent to the call
stack entry specified in the invocation pointer parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Promotes the message sent to the call stack entry
that called the call stack entry specified in the invocation pointer
parameter.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>n (any positive number)</em></td>
<td align="left" valign="top">Promotes the message sent to the nth call stack
entry earlier in the stack from the call stack entry specified in the
invocation pointer parameter.
<p>You can use any positive number that points to an actual call stack entry in
the call stack.</p>
</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Message key</strong></dt>
<dd>INPUT; CHAR(4)
<p>The message key of the existing message that is to be promoted.</p>
</dd>
<dt><strong>Message identifier</strong></dt>
<dd>INPUT; CHAR(7)
<p>The identifying code for the new predefined message that replaces the
message being promoted.</p>
</dd>
<dt><strong>Qualified message file name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the message file and the library in which the new predefined
message resides. The first 10 characters specify the file name, and the second
10 characters specify the library. You must specify both the message file name
and the library name. You can use these special values for the library
name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Message data</strong></dt>
<dd>INPUT; CHAR(*)
<p>The data to insert in the predefined message's substitution variables.</p>
<p>If there is no data to insert, a value of 0 should be specified for the
length of message data parameter.</p>
<p>If this parameter contains pointer data, each pointer must start on a
16-byte boundary to keep the data accurate.</p>
</dd>
<dt><strong>Length of message data</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the message data, in bytes. Valid values are 0 through
32767.</p>
</dd>
<dt><strong>Message type</strong></dt>
<dd>INPUT; CHAR(10)
<p>The type of the new message.</p>
<p>You must specify one of these values:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*ESCAPE</em></td>
<td align="left" valign="top">Escape message</td>
</tr>
<tr>
<td align="left" valign="top"><em>*STATUS</em></td>
<td align="left" valign="top">Status message</td>
</tr>
</table>
<p>You may promote an escape message to another escape message or to a status
message. You may promote a status message to an escape message or to another
status message.</p>
</dd>
<dt><strong>Message severity</strong></dt>
<dd>INPUT; BINARY(4)
<p>A number identifying the message severity that overrides the severity that
is stored in the message description for the message. Valid values follow:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">The message severity is not to be
overridden.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>0-99</em></td>
<td align="left" valign="top">The severity for the new message that replaces
the message being promoted. For a list of the severity codes and their
meanings, see the <a href="../rbam6/clpro.htm">CL Programming</a> topic.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Log option</strong></dt>
<dd>INPUT; CHAR(1)
<p>A value that indicates whether the new message is to appear in the job log.
Valid values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The new message is not to appear in the job
log.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The new message is to appear in the job log.
However, if the exception monitor for the new message indicates that it is not
to be enqueued, it does not appear in the job log. This parameter value is only
valid when the message type parameter is *ESCAPE. If the message type parameter
is *STATUS, an error is returned to the caller of this API.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Priority</strong></dt>
<dd>INPUT; CHAR(10)
<p>The initial priority of the new message.</p>
<p>You must specify one of these values:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CONTINUE</em></td>
<td align="left" valign="top">Continue. The initial priority of the new message
is the same as the current priority of the message that is being promoted.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LERETRY</em></td>
<td align="left" valign="top">Retry. The initial priority of the new message is
135, so that the first condition handler that will get control is the ILE
condition manager.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LEDFT</em></td>
<td align="left" valign="top">LE/400 Default. The initial priority of the new
message is 225, which indicates LE default action. This causes the exception to
be moved up to the next call stack entry where processing continues at the
first handler condition.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>New message key</strong></dt>
<dd>OUTPUT;CHAR(4)
<p> The message key of the new message that replaces the promoted message.</p>
</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>Error Messages</h3>
<table cellpadding="5">
<!-- cols="15 85" -->
<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">CPF24A3 E</td>
<td align="left" valign="top">Value for call stack counter parameter not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B3 E</td>
<td align="left" valign="top">Message type &amp;1 not valid.</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">CPF24B6 E</td>
<td align="left" valign="top">Length of &amp;1, not valid for message text or
data.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2401 E</td>
<td align="left" valign="top">Not authorized to library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2407 E</td>
<td align="left" valign="top">Message file &amp;1 in &amp;2 not found.</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">CPF2411 E</td>
<td align="left" valign="top">Not authorized to message file &amp;1 in
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2419 E</td>
<td align="left" valign="top">Message identifier &amp;1 not found in message
file &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF243A E</td>
<td align="left" valign="top">Invocation pointer parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF243B E</td>
<td align="left" valign="top">Message severity &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF243C E</td>
<td align="left" valign="top">Log option &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF243D E</td>
<td align="left" valign="top">Priority &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF243E E</td>
<td align="left" valign="top">Message is not an active exception.</td>
</tr>
<tr>
<td align="left" valign="top">CPF243F E</td>
<td align="left" valign="top">Cannot promote message of type other than *ESCAPE
or *STATUS.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2499 E</td>
<td align="left" valign="top">Message identifier &amp;1 not allowed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2531 E</td>
<td align="left" valign="top">Message file &amp;1 in &amp;2 damaged for
&amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2548 E</td>
<td align="left" valign="top">Damage to message file &amp;1 in &amp;2.</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">CPF8100 E</td>
<td align="left" valign="top">All CPF81xx messages could be returned. xx is
from 01 to FF.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9830 E</td>
<td align="left" valign="top">Cannot assign library &amp;1.</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: V2R3
<hr>
<table align="center" 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>
</body>
</html>