Built-in number for MATPRMSG is 127.
MATPRMSG (
          receiver_template    : address
          message_template     : address
          source_template      : address OR
                                 null operand
          selection_template   : address
)

It is recommended that you use selection types 8 and 9 for 8-byte invocation and activation group marks, respectively, rather than selection types 3 and 4. It is also recommended that you use the 8-byte invocation and activation group marks at the end of the materialization template. 4-byte marks can wrap and produce unexpected results.

Process queue space queue offset

This value indicates which queue in the queue space a message resides on. A value of -1 will be returned if the message is on the external queue, and zero if the message is on the message log. If the message resides on an invocation queue this field will be zero.

Time sent (local time)

The value of the system time-of-day clock when the message was originally sent (Signal Exception (SIGEXCP) or message originated as a result of an exception). See Standard Time Format for additional information on the time-of-day clock.

Time modified (local time)

This value is initially equal to the time sent value. See Standard Time Format for additional information on the time-of-day clock.

Interrupted invocation

An invocation pointer that addresses the invocation which currently has this message as its interrupt cause. This pointer will have a null pointer value if the message is not an exception message.

Target invocation

An invocation pointer or system pointer that identifies which queue contains the message. If the message resides on an invocation queue, this field contains an invocation pointer that addresses the invocation whose invocation message queue currently contains the message. If the message does not reside on an invocation queue, then a system pointer to the Queue Space is returned. The process queue space queue offset field indicates on which queue the message resides, the message log or the external queue.

Original target invocation

An invocation pointer that addresses the invocation which originally was sent the message. This pointer will have a null pointer value if the original target invocation no longer exists.

Source program location

A suspend pointer which identifies the program, module, procedure, and statement where the source invocation was suspended (due to a CALL or some form of interrupt).

Target program location

A suspend pointer which identifies the program, module, procedure, and statement where the target invocation was suspended (due to a CALL or some form of interrupt). If the message is no longer in an invocation message queue, then this pointer reflects the invocation of the last (most recent) invocation message queue in which the message resided. This pointer will have a null pointer value if the message has never resided in an invocation message queue.

Originating program location

A suspend pointer which identifies the program, module, procedure, and statement of the instruction that sent the message. For messages sent by the machine, this pointer area contains a machine-dependent representation of the source machine component.

Invocation mark

If the message has ever resided on an invocation, this field will be non-zero. It contains the mark of the invocation where the message was last queued. The value returned in the 4-byte invocation mark may have wrapped.

Activation group mark

If the message has ever resided on an invocation, this field will be non-zero. It contains the mark of the activation group which contains the invocation where the message was last queued. The value returned in the 4-byte activation group mark may have wrapped.

Thread ID

This is the thread ID of the thread that added the message to the process queue space.

Messages will contain a thread ID that is determined by the queue space to which the message is being sent. When sending to the current process queue space, the thread ID of the current thread will be used. When sending to a different process queue space, the thread ID of the initial thread for the owning process will be used. If the queue space is not associated with a process, the thread ID will be 0.

Note: When sending a reply, the message will contain the thread ID from the associated inquiry message.

Hex 00 = Informational message 0

Hex 01 = Informational message 1

Hex 04 = Exception message

Hex 06 = Return/Transfer Control message

Hex 07 = Return message

Hex 10 = Control Entry message

Hex 11 = Escape/return handler

All other values are reserved.

Message type

This value determines the type of the message. The type of message determines which message status values have meaning.

The following message status attributes are valid for all informational message types:.

• Log Message
• Reply
• Inquiry

The following message status attributes are valid for a message type of exception:.

• Log Message
• Retain
• Action pending
• Invoke PDEH
• Inquiry
• Reply

The following message status attributes are valid for a message type of return or return/transfer control.

• Action pending

The following describes each message type in detail.

• Informational 0 - There are no special requirements as to what message status contains or what the Target Invocation pointer actually identifies.

• Informational 1 - There are no special requirements as to what message status contains or what the Target Invocation pointer actually identifies.

• Exception - This type of message has an interrupt cause for the interrupted invocation.

• Return/transfer control - This message type indicates that a return handler is invoked when the target invocation is exited for any reason including XCTL. Additionally, messages of this type interpret the message format information field to identify a program or procedure to be invoked as the return handler.

• Return - This message type indicates that a return handler will be invoked if the target invocation is exited for any reason other than Transfer Control (XCTL). In the case of XCTL, the message is preserved and associated with the transferred to invocation. Additionally, messages of this type interpret the message format information field to identify a program or procedure to be invoked as the return handler.

• Control Entry - This message type is associated with an invocation. The control entry is used to keep data required for exception processing.

• Escape/Return Handler - This message type is associated with an invocation. The escape/return handler is used to keep data required for processing when control is returned to an invocation.

Message severity

A value indicating the severity of the message.

Reply/Inquiry message reference key

If the message materialized is an inquiry message that has been answered, this is the message reference key of its reply message.

If the message materialized is a reply message, this is the message reference key of its inquiry message.

This value only has meaning for exception and informational messages.

Message status mask

A bit-significant value indicating the original status of the message.

• Log message status. If this bit is 1, the message is queued to the Process Message Log until it is explicitly removed.

• Inquiry status. If this bit is 1, this message will accept a reply message.

• Reply status. If this value is 1, this message is a reply to an inquiry message. The reply message reference key is used to identify the message for which the message was replied.

• Answered status. If this value is 1, the message is a inquiry message for which a reply has been sent. The reply message reference key is used to identify the reply message.

• Retain status. If this bit is 1, the message is kept even if the invocation message queue after the following message status bits are zero: log, message being processed, and action pending.

• Action pending status. If this bit is 1, this message represents an exception which is the current interrupt cause for the specified Source Invocation or else it is a return or return/transfer control message which has not yet been processed.

• Invoke Process Default Exception Handler. This status only has meaning for exception messages.

Interrupt class mask

A bit-significant value indicating the cause of the interrupt. The MI user is allowed to use the machine-defined classes since machine-generated errors may be re-sent by the MI user.

This value only has meaning for exception messages.

The Java thrown class interrupt class indicates that the message corresponds to a thrown class in the Java language.

Initial handler priority

An unsigned eight-bit binary number which selects the initial interrupt handler priority. This value is within the range of 64 - 255.

This value only has meaning for exception messages.

Exception ID

A two-byte field that identifies the exception being defined by this message.

This value only has meaning for exception messages.

PDEH reason code

A value defined by the user which indicates the type of processing to be attempted by the Process Default Exception Handler.

This value only has meaning for exception messages.

Signal class

A value defined by the user which is used to select exception monitors.

This value only has meaning for exception messages.

Compare data length

A value indicating the number of bytes provided as compare data.

This value only has meaning for exception messages.

Message ID

Specifies the message identifier of a message description whose predefined message is being sent.

Maximum message data length

Input to the instruction that specifies the number of bytes supplied for the message data. The maximum value allowed is 65,504.

Message data length

A value indicating the number of bytes of message data for this process message.

Maximum extension data length

Input to the instruction that specifies the number of bytes supplied for the message data extension. The maximum value allowed is 65,504.

Message extension data length

A value indicating the number of bytes of message data extension for this process message.

Message data pointer

A pointer to the area to receive the message data. This field is ignored if the maximum message data length field is zero.

Message data extension pointer

A pointer to the area to receive the message data extension. This field is ignored if the maximum extension data length field is zero.

Message format information

A 32 byte field that contains either compare data or two 16 byte fields which contain information related to a return type message.

• If message type is not a return or return/transfer control message, this field is defined as compare data used to determine which exception handler is given control. Up to 32 bytes may be specified.

• If message type is a return or return/transfer control message, then the first 16 bytes of this field are defined as a system pointer to a program object, or else a procedure pointer to a bound program procedure. The last 16 bytes of the field are reserved for future use.

This value is ignored if the message does not represent an exception, return or return/transfer control message.

Source invocation offset

A signed numerical value indicating an invocation relative to the invocation located by the source invocation pointer. A value of zero denotes the invocation addressed by the source invocation pointer, with increasingly positive numbers denoting increasingly later invocations in the stack, and increasingly negative numbers denoting increasingly earlier invocations in the stack. If a process queue space is specified as the message source, then the only valid values for this field are 0, -1 and -2. A value of -1 indicates to materialize from the external queue of the process queue space. A zero value indicates to materialize from the message log of the process queue space. A value of -2 indicates to attempt to locate the message using the message reference index supplied in operand 4 without regard to the queue space queue that the message resides on. Only unanswered inquiry messages, return messages, and return/transfer control messages can be materialized in this fashion. Other values result in a scalar value invalid  (hex 3203) exception being signaled.

If the invocation identified by this offset does not exist in the stack, a scalar value invalid  (hex 3203) exception will be signaled.

Originating invocation offset

Specifies a displacement from the invocation executing this instruction and must be zero (which indicates the current invocation) or negative (which indicates an older invocation). The invocation identified is used as the source for all authorization checks (environment authority to an invocation or authority to a process queue space). If the originating invocation offset is non-zero, then the invocation executing this instruction must be authorized to the originating invocation identified.

If the invocation identified by this offset does not exist in the stack or the value is greater than zero, a scalar value invalid  (hex 3203) exception will be signaled.

Invocation range

A signed numerical value indicating the number of invocations in the range in addition to the invocation identified by the source invocation pointer. If a process queue space pointer is provided, this value must be zero.

The sign of the invocation range determines the direction of the additional invocations. A positive number specifies a range encompassing newer invocations, while a negative number specifies a range encompassing older invocations.

It is not an error if this value specifies a range greater than the number of existing invocations in the specified direction. The materialization will stop after the last invocation is encountered.

Source invocation pointer

An invocation pointer to an invocation. If a null pointer value, then the current invocation is indicated.

If the invocation identified does not exist in the stack or is invalid for this operation, an invalid invocation address  (hex 1603) exception will be signaled.

Process queue space pointer

A system pointer to a process queue space object.

Hex 00 = Select based on message status

Hex 01 = Select based on message ID

Hex 02 = Select based on interrupt class

Hex 03 = Select based on invocation mark

Hex 04 = Select based on activation group mark

Hex 07 = Select based on thread ID

Hex 08 = Select based on 8-byte invocation mark

Hex 09 = Select based on 8-byte activation group mark

Starting and ending message reference index

Messages in the specified range of index values are examined either until one of the selection criteria has been satisfied or all queues specified have been searched. The direction of search is determined by the relative values of starting message reference index and ending message reference index. If the former value is smaller, then the search direction is in numerically (and chronologically) increasing order, while if the latter value is smaller the search direction is in the opposite direction.

Messages are examined starting with the message identified by starting message reference index, or if no such message exists in the queue, starting with the closest existing message in the direction of the search.

For the current process, queue space messages will only be selected for the current thread. To select messages for another thread, a thread selection criteria must be used.

For a different process queue space, all messages for all threads will be selected.

If operand 3 specifies a system pointer to a queue space and a source invocation offset of -2, then the starting and ending message reference indices must be equal, otherwise a scalar value invalid  (hex 3203) exception will be issued.

Number of selection criteria

A numerical value that specifies how many selection criteria fields are supplied. If number of selection criteria has a value of zero, then the first message in the index range will be materialized.

Selected message reference index

This value returns the message reference index of the message materialized. Zero is returned if no message satisfies the criteria.

Selected message count

This value indicates the number of messages selected: zero for no messages found, one if a message was found.

Selection criterion

This field contains the data used to select messages from a queue space. There is a variable number of criteria present in the template (the number present is in the number of selection criteria field). Each selection criterion may select a message, reject it, or take no action. Successive selection criteria are applied to each message until it is selected or rejected, or until selection criteria have been exhausted (in which case selection is the default).

Selection type

This field indicates the format of the selection criterion and what field in the message is compared.

Selection action

A bit-significant value indicating what actions to perform during the selection criteria processing.

• Reject criterion - If this bit is 1, a message is rejected if the selection criterion is satisfied. If this bit is 0, a message is selected when the selection criterion is satisfied.

• Reject message - If this bit is 1, a message is rejected if the selection criteria is not satisfied. If this bit is 0, no action is taken when the selection criteria is not satisfied. Processing continues with the next selection criterion.

• Reject satisfaction - If this bit is 0, the satisfaction of the criterion is accepted. If this bit is 1, a satisfied criterion will become not satisfied and a not satisfied criterion will become satisfied.

The following figure illustrates how messages are selected based on the selection action criterion.

Message type mask

A bit-significant value indicating types of messages that should be
examined during selection criteria processing. The first 31 bits
correspond to message types hex 00 through hex 1E respectively. The
32nd bit (bit 31) corresponds to all message types greater than hex 1E.

Message status mask and message status complement

These are bit-significant values indicating the message status
attributes that will allow a message to be selected. These values are
used to test a message as follows:

The message status complement is bit-wise exclusive-ORed with
the message status value of a message. The result of this is then
bit-wise ANDed with the message status mask. If the result is
all 0 bits, the message does not satisfy this selection criterion. If
the result is not all 0 bits, the message satisfies the selection
criterion.

Message ID

A character value that is compared to the message ID of a message. If
the values are equal the selection is satisfied.

Interrupt class mask and interrupt class complement

These are bit-significant values indicating the interrupt class
attributes that will allow a message to be selected. These values are
used to test a message as follows:

The interrupt class complement is bit-wise exclusive-ORed with
the interrupt class value of a message. The result of this is then
bit-wise ANDed with the interrupt class mask. If the result is
all 0 bits, the message does not satisfy this selection criterion. If
the result is not all 0 bits, the message satisfies the selection
criterion.

Invocation mark

A binary number that is compared to the invocation mark of a message.
If the values are equal the selection is satisfied.
The value returned in the 4-byte invocation mark may have wrapped.

Activation group mark

A binary number that is compared to the activation group mark of a
message. If the values are equal the selection is satisfied.
The value returned in the 4-byte activation group mark may have wrapped.

Thread ID

A binary number that is compared to the thread ID of a message. If the
values are equal, the selection is satisfied.

Note: 0 is not a valid thread ID and can be used to select all
messages.