Change Exception Message (QMHCHGEM) API

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:

• 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.
• 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.
• 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.

Authorities and Locks

None.

Required Parameter Group

Invocation pointer

INPUT; POINTER

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.

Call stack counter

INPUT; BINARY(4)

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.

Message key

INPUT; CHAR(4)

The message key of the exception message being changed. This parameter is ignored when *CHANGEALL or *CHANGELST is specified for the modification option parameter.

Modification option

INPUT; CHAR(10)

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.

Reply text

INPUT; CHAR(*)

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 message being changed is not a notify message.
• The modification option is not *REPLY or *REMOVE.
• The reply text length parameter is 0.

Reply text length

INPUT; BINARY(4)

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.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Error Messages