579 lines
16 KiB
HTML
579 lines
16 KiB
HTML
|
<!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>
|
||
|
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>
|
||
|
Default Public Authority: *USE<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
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 &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 &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 &1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2407 E</td>
|
||
|
<td align="left" valign="top">Message file &1 in &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
|
||
|
&1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2411 E</td>
|
||
|
<td align="left" valign="top">Not authorized to message file &1 in
|
||
|
&2.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2419 E</td>
|
||
|
<td align="left" valign="top">Message identifier &1 not found in message
|
||
|
file &2 in &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 &1 not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF243C E</td>
|
||
|
<td align="left" valign="top">Log option &1 not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF243D E</td>
|
||
|
<td align="left" valign="top">Priority &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 &1 not allowed.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2531 E</td>
|
||
|
<td align="left" valign="top">Message file &1 in &2 damaged for
|
||
|
&3.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2548 E</td>
|
||
|
<td align="left" valign="top">Damage to message file &1 in &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 &1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
<td align="left" valign="top">Program or service program &1 in library
|
||
|
&2 ended. Reason code &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>
|