Materialize Process Message (MATPRMSG)

Instruction Syntax

Op Code (Hex)	Operand 1	Operand 2	Operand 3	Operand 4
039C	Materialization template	Message template	Source template	Selection template

Operand 1: Space pointer.

Operand 2: Space pointer.

Operand 3: Space pointer or null.

Operand 4: Space pointer.

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

Warning

The following information is subject to change from release to release. Use it with caution and be prepared to adjust for changes with each new release.

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

Description:

A message is materialized from a queue space according to the options specified. The message is located on a queue space queue specified by operand 3. The message is selected by the operand 4 criteria. Operands 1 and 2 contain the materialized information from the process message.

The template identified by operand 1 must be 16-byte aligned. Following is the format of the materialization template:

Offset
Dec	Hex	Field Name	Data Type and Length
0	0	Template size specification	Char(8)
0	0	Number of bytes provided for materialization	Bin(4)
4	4	Number of bytes available for materialization	Bin(4)
8	8	Process queue space queue offset	Bin(4)
12	C	Reserved (binary 0)	Char(4)
16	10	Time sent	Char(8)
24	18	Time modified	Char(8)
32	20	Interrupted invocation	Invocation pointer
48	30	Target invocation	Invocation pointer or System pointer
64	40	Original target invocation	Invocation pointer
80	50	Source program location	Suspend pointer
96	60	Target program location	Suspend pointer
112	70	Originating program location	Suspend pointer
128	80	Invocation mark	UBin(4)
132	84	Activation group mark	UBin(4)
136	88	Thread ID	Char(8)
144	90	Invocation mark For Non-Bound programs, the following datatype should be used:	UBin(8)
144	90	Invocation mark (Non-Bound program)	Char(8)
152	98	Activation group mark For Non-Bound programs, the following datatype should be used:	UBin(8)
152	98	Activation group mark (Non-Bound program)	Char(8)
160	A0	--- End ---

The first 4 bytes of the materialization template identify the total number of bytes provided for use by the instruction. This number is supplied as input to the instruction and is not modified by the instruction. If the value is zero for this field, then the operand 1 template is not returned. A number less than 128 (but not 0) causes the materialization length invalid (hex 3803) exception.

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: 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). The time will be returned in UTC if time format is set in operand 4. By default the time will be returned as local system time. The local system time returned is derived from a conversion of the UTC time, so the current system time zone may not reflect the system time zone of when the message was originally sent. Messages will contain microsecond granularity. The time-of-day used is not unique and all the uniqueness bits are set to 0. See Standard Time Format for additional information on the time-of-day clock.
Time modifed: This value is initially equal to the time sent value. The time will be returned in UTC if time format is set in operand 4. By default the time will be returned as local system time. The local system time returned is derived from a conversion of the UTC time, so the current system time zone may not reflect the system time zone of when the message was originally modifed. The not unique time-of-day is used. 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.

The template identified by operand 2 is used to contain the materialized message. It must be 16-byte aligned with the following format.

Offset
Dec	Hex	Field Name	Data Type and Length
0	0	Template size	Char(8)
0	0	Number of bytes provided for materialization	Bin(4)
4	4	Number of bytes available for materialization	Bin(4)
8	8	Message type 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.	Char(1)
9	9	Reserved (binary 0)	Char(1)
10	A	Message severity	Bin(2)
12	C	Reply/Inquiry message reference key	Char(4)
16	10	Message status mask	Char(8)
16	10	Log message 0 = The message is not queued to the Process Message Log. 1 = The message is queued to the Process Message Log.	Bit 0
16	10	Inquiry 0 = Message will not accept a reply. 1 = Message will accept a reply.	Bit 1
16	10	Reply 0 = Message does not represent a reply message. 1 = Message represents a reply message.	Bit 2
16	10	Answered 0 = For messages with a status of inquiry, this indicates that a reply message has not been received. 1 = For messages with a status of inquiry, this indicates that a reply message has been received.	Bit 3
16	10	Message being processed 0 = This value of the flag has no particular meaning. 1 = For a message type of exception, this indicates that the interrupt is currently being handled.	Bit 4
16	10	Retain 0 = Message will be dequeued and its contents discarded when the following message status bits are zero: log, message being processed, and action pending. 1 = Keeps the message from being dequeued after all other message status bits are zero.	Bit 5
16	10	Action pending 0 = Indicates no actions are pending based on this message. 1 = Indicates that the message is either an interrupt cause or is a return, return/transfer control message.	Bit 6
16	10	Invoke Process Default Exception Handler (PDEH) 0 = Do not invoke PDEH. 1 = Invoke PDEH, only valid if message type is exception.	Bit 7
16	10	Error 0 = No error has occurred in the sending of this message. 1 = An error has occurred in the sending of this message.	Bit 8
16	10	PDEH previously invoked 0 = PDEH has not previously been invoked for this message. 1 = PDEH has previously been invoked for this message.	Bit 9
16	10	Reserved (binary 0)	Bits 10-31
16	10	User defined status	Bits 32-63
24	18	Interrupt class mask Note: All fields in the interrupt class mask that are marked as 'Reserved' have a value of binary zero.	Char(8)
24	18	Binary overflow or divide by zero	Bit 0
24	18	Decimal overflow or divide by zero	Bit 1
24	18	Decimal data error	Bit 2
24	18	Floating-point overflow or divide by zero	Bit 3
24	18	Floating-point underflow or inexact result	Bit 4
24	18	Floating-point invalid operand or conversion error	Bit 5
24	18	Other data error (edit mask, etc)	Bit 6
24	18	Specification (operand alignment) error	Bit 7
24	18	Pointer not set/pointer type invalid	Bit 8
24	18	Object not found	Bit 9
24	18	Object destroyed	Bit 10
24	18	Address computation underflow/overflow	Bit 11
24	18	Space not allocated as specified offset	Bit 12
24	18	Domain/State protection violation	Bit 13
24	18	Authorization violation	Bit 14
24	18	Java thrown class	Bit 15
24	18	Reserved	Bits 16-28
24	18	Other MI generated exception (not function check)	Bit 29
24	18	MI generated function check/machine check	Bit 30
24	18	Message generated by Signal Exception instruction	Bit 31
24	18	Reserved	Bits 32-39
24	18	User defined	Bits 40-63

32	20	Initial handler priority	Char(1)
33	21	Current handler priority	Char(1)
34	22	Exception ID	UBin(2)
36	24	PDEH reason code	Char(1)
37	25	Signal class	Char(1)
38	26	Compare data length	Bin(2)
40	28	Message ID	Char(7)
47	2F	Reserved (binary 0)	Char(1)
48	30	Maximum message data length Input to the instruction	Bin(4)
52	34	Message data length	Bin(4)
56	38	Maximum length of message extension data Input to the instruction	Bin(4)
60	3C	Message extension data length	Bin(4)
64	40	Message data pointer Input to the instruction	Space pointer
80	50	Message data extension pointer Input to the instruction	Space pointer
96	60	Message format information	Char(32)
		If the message is not a return or return/transfer control message.
96	60	Compare data If the message is a return or return/transfer control message.	Char(32)
96	60	Return handler identifier	System pointer or Procedure pointer
112	70	Reserved	Char(16)
128	80	Reserved (binary 0)	Char(48)
176	B0	--- End ---

The first 4 bytes of the message template identify the total number of bytes provided for use by the instruction. This number is supplied as input to the instruction and is not modified by the instruction. A number less than 160 causes the materialization length invalid (hex 3803) exception.

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.