487 lines
15 KiB
HTML
487 lines
15 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>Change Exception Message (QMHCHGEM) 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 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>Change Exception Message (QMHCHGEM) API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<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">Modification option</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">Reply text</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">6</td>
|
||
|
|
<td align="left" valign="top">Reply text length</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">7</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 Change Exception Message (QMHCHGEM) API changes an exception message on
|
||
|
|
a call message queue. This API allows the current program to perform one of the
|
||
|
|
following actions on an exception message that was sent to its caller, a
|
||
|
|
previous caller, or itself:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Handle the escape, status, or notify message. If the exception is a notify
|
||
|
|
message that has not already received a reply, return the default reply.</li>
|
||
|
|
|
||
|
|
<li>If it is a notify message that has not been replied to, return a reply to
|
||
|
|
the call stack entry that sent this message. Handle the exception.</li>
|
||
|
|
|
||
|
|
<li>Handle the escape, status, or notify message and remove it from the job
|
||
|
|
log. If the exception is a notify message that has not been replied to, return
|
||
|
|
its default reply or another reply to the call stack entry that sent it.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<p>None.</p>
|
||
|
|
|
||
|
|
<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 to which the exception
|
||
|
|
message was sent. When using a value other than 0 for the call stack counter
|
||
|
|
parameter, the invocation pointer points to the call stack entry from which to
|
||
|
|
start counting in the call stack. This is the location of the call stack entry
|
||
|
|
that received the exception message that was sent. 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 QMHCHGEM API
|
||
|
|
is used.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Call stack counter</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>A number that identifies the location in the call stack of the call stack
|
||
|
|
entry that received the message you are changing. The number is relative to the
|
||
|
|
call stack entry specified in the invocation pointer parameter. The number
|
||
|
|
indicates how many calls earlier in 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="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top">Change a message in the message queue of 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">Change a message in the message queue of the call
|
||
|
|
stack entry that called the call stack entry specified in the invocation
|
||
|
|
pointer parameter.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>n</em></td>
|
||
|
|
<td align="left" valign="top">Change a message in the message queue of the nth
|
||
|
|
call stack entry earlier up the stack from the call stack entry specified in
|
||
|
|
the invocation pointer parameter.
|
||
|
|
|
||
|
|
<p>You can use any positive number that offsets 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 exception message being changed. This parameter is
|
||
|
|
ignored when *CHANGEALL or *CHANGELST is specified for the modification option
|
||
|
|
parameter.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Modification option</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(10)
|
||
|
|
|
||
|
|
<p>The type of change to be done to the exception message. Valid values
|
||
|
|
follow:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*HANDLE</em></td>
|
||
|
|
<td align="left" valign="top">Causes the exception to be handled. No error
|
||
|
|
message is returned if the exception is already handled.
|
||
|
|
|
||
|
|
<p>If the exception is a status message, it is immediately removed from the job
|
||
|
|
message queue and is no longer accessible. If the exception is an escape or
|
||
|
|
notify message and is still in the job log, it is still accessible through its
|
||
|
|
message key.</p>
|
||
|
|
|
||
|
|
<p>If the exception is a notify message, the default reply is sent. If the
|
||
|
|
notify message already received a reply but was not handled, the exception will
|
||
|
|
still be handled. If the notify message was already handled but had not
|
||
|
|
received a reply, the default reply will still be sent.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*CHANGE</em></td>
|
||
|
|
<td align="left" valign="top">Changes escape message to a diagnostic message
|
||
|
|
and handles it. If the escape message has already been handled, it is still
|
||
|
|
changed to a diagnostic message. If the exception is not an escape message, an
|
||
|
|
error is returned to the caller of this API and the exception is not handled or
|
||
|
|
changed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*CHANGEALL</em></td>
|
||
|
|
<td align="left" valign="top">Changes all escape messages that were sent to the
|
||
|
|
specified call stack entry. Each escape message is changed to a diagnostic
|
||
|
|
message and handled. If the escape message has already been handled, it is
|
||
|
|
still changed to a diagnostic message. If any messages are encountered that are
|
||
|
|
not escape messages, they are ignored. When *CHANGEALL is specified, the
|
||
|
|
message key parameter value is ignored.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*CHANGELST</em></td>
|
||
|
|
<td align="left" valign="top">Changes the last escape message that was sent to
|
||
|
|
the specified call stack entry. The escape message is changed to a diagnostic
|
||
|
|
message and handled. If the escape message has already been handled, it is
|
||
|
|
still changed to a diagnostic message. When *CHANGELST is specified, the
|
||
|
|
message key parameter value is ignored.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*REPLY</em></td>
|
||
|
|
<td align="left" valign="top">Replies to a notify message and handles it. The
|
||
|
|
default reply or the reply specified in the reply text parameter is returned to
|
||
|
|
the call stack entry that sent the notify message. If the reply text length
|
||
|
|
parameter value is 0, the default reply is sent. The notify message is handled
|
||
|
|
after its reply is sent.
|
||
|
|
|
||
|
|
<p>If the notify message has already been handled, the reply is still sent.</p>
|
||
|
|
|
||
|
|
<p>If the notify message has already been replied to, an error is returned to
|
||
|
|
the caller of this API, and the exception is not handled.</p>
|
||
|
|
|
||
|
|
<p>If the exception is not a notify message, an error is returned to the caller
|
||
|
|
of this API, and the exception is not handled.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*REMOVE</em></td>
|
||
|
|
<td align="left" valign="top">Handles the escape, notify, or status exception
|
||
|
|
and removes the message from the job log. If the exception is a notify message,
|
||
|
|
its default reply or the reply specified in the reply text parameter is
|
||
|
|
returned to the call stack entry that sent it. If the reply text length
|
||
|
|
parameter value is 0, the default reply is sent. No error message is returned
|
||
|
|
if the exception is already handled. The exception is immediately inaccessible
|
||
|
|
for any further operations.
|
||
|
|
|
||
|
|
<p>If the exception is a notify message that has already been replied to, it is
|
||
|
|
handled and removed from the job log. No error message is returned to the
|
||
|
|
caller of this API.</p>
|
||
|
|
|
||
|
|
<p>If the exception is not a notify message, the reply text length parameter
|
||
|
|
value must be 0. If the reply text length parameter value is not 0, an error is
|
||
|
|
returned to the caller of this API. The exception is not handled or removed
|
||
|
|
from the job log.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Reply text</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The data that is returned as the reply to a notify message when *REPLY or
|
||
|
|
*REMOVE is specified for the modification option parameter. This data must be
|
||
|
|
compatible with the reply type, reply length, and valid reply values stored in
|
||
|
|
the message description for the message. If it is not compatible, an error is
|
||
|
|
returned to the caller of this API.</p>
|
||
|
|
|
||
|
|
<p>This parameter is ignored if:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The message being changed is not a notify message.</li>
|
||
|
|
|
||
|
|
<li>The modification option is not *REPLY or *REMOVE.</li>
|
||
|
|
|
||
|
|
<li>The reply text length parameter is 0.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Reply text length</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The length, in bytes, of the data that is returned as the reply to a notify
|
||
|
|
message. This length must be compatible with the reply type and maximum reply
|
||
|
|
length stored in the message description for the message.</p>
|
||
|
|
|
||
|
|
<p>Valid values follow:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="10 90" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="8%"><em>0</em></td>
|
||
|
|
<td align="left" valign="top" width="92%">Return the notify message's default
|
||
|
|
reply.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1-132</em></td>
|
||
|
|
<td align="left" valign="top">Return the reply specified in the reply text
|
||
|
|
parameter. This is the number of bytes to return.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>If the message being changed is not a notify message, or the modification
|
||
|
|
option is not *REPLY or *REMOVE, this parameter is ignored.</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 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%">CPF24A3 E</td>
|
||
|
|
<td align="left" valign="top" width="85%">Value for call stack counter
|
||
|
|
parameter 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">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">CPF242D E</td>
|
||
|
|
<td align="left" valign="top">Modification option &1 not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF242E E</td>
|
||
|
|
<td align="left" valign="top">Tried to change message which is not an
|
||
|
|
exception.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF242F E</td>
|
||
|
|
<td align="left" valign="top">Message type must be ESCAPE for *CHANGE
|
||
|
|
modification option.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF2420 E</td>
|
||
|
|
<td align="left" valign="top">Reply already sent for inquiry or notify
|
||
|
|
message.</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">CPF243A E</td>
|
||
|
|
<td align="left" valign="top">Invocation pointer parameter not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF2432 E</td>
|
||
|
|
<td align="left" valign="top">Cannot send reply to message type other than *INQ
|
||
|
|
or *NOTIFY.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF2547 E</td>
|
||
|
|
<td align="left" valign="top">Damage to message file QCPFMSG.</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: V2R1
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|