| 1 | Invocation pointer | Input | Pointer |
| 2 | Call stack counter | Input | Binary(4) |
| 3 | Message key | Input | Char(4) |
| 4 | Modification option | Input | Char(10) |
| 5 | Reply text | Input | Char(*) |
| 6 | Reply text length | Input | Binary(4) |
| 7 | Error code | I/O | Char(*) |
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:
None.
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.
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:
| 0 | Change a message in the message queue of the call stack entry specified in the invocation pointer parameter. |
| 1 | Change a message in the message queue of the call stack entry that called the call stack entry specified in the invocation pointer parameter. |
| n | 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.
You can use any positive number that offsets to an actual call stack entry in the call stack. |
The message key of the exception message being changed. This parameter is ignored when *CHANGEALL or *CHANGELST is specified for the modification option parameter.
The type of change to be done to the exception message. Valid values follow:
| *HANDLE | Causes the exception to be handled. No error
message is returned if the exception is already handled.
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. 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. |
| *CHANGE | 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. |
| *CHANGEALL | 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. |
| *CHANGELST | 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. |
| *REPLY | 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.
If the notify message has already been handled, the reply is still sent. 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. If the exception is not a notify message, an error is returned to the caller of this API, and the exception is not handled. |
| *REMOVE | 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.
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. 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. |
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.
This parameter is ignored if:
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.
Valid values follow:
| 0 | Return the notify message's default reply. |
| 1-132 | Return the reply specified in the reply text parameter. This is the number of bytes to return. |
If the message being changed is not a notify message, or the modification option is not *REPLY or *REMOVE, this parameter is ignored.
The structure in which to return error information. For the format of the structure, see Error code parameter.
| Message ID | Error Message Text |
|---|---|
| CPF24A3 E | Value for call stack counter parameter not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF24B6 E | Length of &1, not valid for message text or data. |
| CPF2401 E | Not authorized to library &1. |
| CPF2410 E | Message key not found in message queue &1. |
| CPF2411 E | Not authorized to message file &1 in &2. |
| CPF242D E | Modification option &1 not valid. |
| CPF242E E | Tried to change message which is not an exception. |
| CPF242F E | Message type must be ESCAPE for *CHANGE modification option. |
| CPF2420 E | Reply already sent for inquiry or notify message. |
| CPF2422 E | Reply not valid. |
| CPF243A E | Invocation pointer parameter not valid. |
| CPF2432 E | Cannot send reply to message type other than *INQ or *NOTIFY. |
| CPF2547 E | Damage to message file QCPFMSG. |
| CPF2548 E | Damage to message file &1 in &2. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
[ Back to top | Message Handling APIs | APIs by category ]