| 1 | Invocation pointer | Input | Pointer |
| 2 | Call stack counter | Input | Binary(4) |
| 3 | Message key | Input | Char(4) |
| 4 | Message identifier | Input | Char(7) |
| 5 | Qualified message file name | Input | Char(20) |
| 6 | Message data | Input | Char(*) |
| 7 | Length of message data | Input | Binary(4) |
| 8 | Message type | Input | Char(10) |
| 9 | Message severity | Input | Binary(4) |
| 10 | Log option | Input | Char(1) |
| 11 | Priority | Input | Char(10) |
| 12 | New message key | Output | Char(4) |
| 13 | Error code | I/O | Char(*) |
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.
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.
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.
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.
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:
| 0 | Promotes the message that was sent to the call stack entry specified in the invocation pointer parameter. |
| 1 | Promotes the message sent to the call stack entry that called the call stack entry specified in the invocation pointer parameter. |
| n (any positive number) | 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.
You can use any positive number that points to an actual call stack entry in the call stack. |
The message key of the existing message that is to be promoted.
The identifying code for the new predefined message that replaces the message being promoted.
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:
| *CURLIB | The job's current library |
| *LIBL | The library list |
The data to insert in the predefined message's substitution variables.
If there is no data to insert, a value of 0 should be specified for the length of message data parameter.
If this parameter contains pointer data, each pointer must start on a 16-byte boundary to keep the data accurate.
The length of the message data, in bytes. Valid values are 0 through 32767.
The type of the new message.
You must specify one of these values:
| *ESCAPE | Escape message |
| *STATUS | Status message |
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.
A number identifying the message severity that overrides the severity that is stored in the message description for the message. Valid values follow:
| -1 | The message severity is not to be overridden. |
| 0-99 | The severity for the new message that replaces the message being promoted. For a list of the severity codes and their meanings, see the CL programming topic. |
A value that indicates whether the new message is to appear in the job log. Valid values follow:
| 0 | The new message is not to appear in the job log. |
| 1 | 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. |
The initial priority of the new message.
You must specify one of these values:
| *CONTINUE | Continue. The initial priority of the new message is the same as the current priority of the message that is being promoted. |
| *LERETRY | 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. |
| *LEDFT | 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. |
The message key of the new message that replaces the promoted message.
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. |
| CPF24B3 E | Message type &1 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. |
| CPF2407 E | Message file &1 in &2 not found. |
| CPF2410 E | Message key not found in message queue &1. |
| CPF2411 E | Not authorized to message file &1 in &2. |
| CPF2419 E | Message identifier &1 not found in message file &2 in &3. |
| CPF243A E | Invocation pointer parameter not valid. |
| CPF243B E | Message severity &1 not valid. |
| CPF243C E | Log option &1 not valid. |
| CPF243D E | Priority &1 not valid. |
| CPF243E E | Message is not an active exception. |
| CPF243F E | Cannot promote message of type other than *ESCAPE or *STATUS. |
| CPF2499 E | Message identifier &1 not allowed. |
| CPF2531 E | Message file &1 in &2 damaged for &3. |
| 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. |