Promote Message (QMHPRMM) API
Required Parameter Group:
| 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(*) |
Default Public Authority: *USE
Threadsafe: Yes
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.
Authorities and Locks
- Message File Authority
- *USE
- Message File Library Authority
- *EXECUTE
Required Parameter Group
- Invocation pointer
- INPUT; POINTER
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.
- Call stack counter
- INPUT; BINARY(4)
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.
- Message key
- INPUT; CHAR(4)
The message key of the existing message that is to be promoted.
- Message identifier
- INPUT; CHAR(7)
The identifying code for the new predefined message that replaces the message being promoted.
- Qualified message file name
- INPUT; CHAR(20)
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
- Message data
- INPUT; CHAR(*)
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.
- Length of message data
- INPUT; BINARY(4)
The length of the message data, in bytes. Valid values are 0 through 32767.
- Message type
- INPUT; CHAR(10)
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.
- Message severity
- INPUT; BINARY(4)
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.
- Log option
- INPUT; CHAR(1)
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.
- Priority
- INPUT; CHAR(10)
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.
- New message key
- OUTPUT;CHAR(4)
The message key of the new message that replaces the promoted message.
- 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
| 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. |
API introduced: V2R3