Materialize Queue Messages (MATQMSG)

Operand 2: System pointer.

Operand 3: Character(16) scalar.

Built-in number for MATQMSG is 45.
MATQMSG (
         receiver                     : address
         queue                        : address of system pointer
         message_selection_template   : address
)

Description

Materialize selected messages on a queue. One or more messages on the queue specified by operand 2 are selected according to information provided in operand 3 and materialized into operand 1. The number of messages materialized and the amount of key and message text data materialized for each message is governed by the message selection template.

Note that the list of messages on a queue is a dynamic attribute and may be changing on a continual basis. The materialization of messages provided by this instruction is just a picture of the status of the queue at the point of interrogation by this instruction. As such, the actual status of the queue may differ from that described in the materialization when subsequent instructions use the information in the template as a basis for operations against the queue.

Operand 1 specifies a space that is to receive the materialized attribute values.

Operand 2 is a system pointer identifying the queue from which the messages are to be materialized.

Operand 3 is a character (16) scalar specifying which messages are to be materialized.

The operand 1 space pointer must address a 16-byte boundary. The materialization template has the following format:

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

The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver is greater than that required to contain the information requested, then the excess bytes are unchanged. No exceptions are signaled in the event that the receiver contains insufficient area for the materialization, other than the materialization length invalid  (hex 3803) exception described previously.

The count of messages available for materialization is the number of messages available to be materialized.

The count of messages on the queue is the current number of messages on the queue.

The maximum message size and key size are values specified when the queue was created. If the queue is not a keyed queue, the value materialized for the key size is zero.

The length of the message key and message text fields is determined by values supplied in operand 3, message selection data. If the length supplied in operand 3 exceeds the actual data length, the remaining space will be padded with binary zeros.

The message selection template identified by operand 3 must be at least 16 bytes and must be on a 16-byte boundary. The format of the message selection template is as follows:

The message selection type must not specify keyed if the queue was not created as a keyed queue.

Both of the fields specified under lengths must be zero or an integer multiple of 16. The maximum value allowed for the key length is 256. The maximum value allowed for the message text is 65,536.

The enqueue and dequeue mode field indicates whether or not MATQMSG blocks out all other activity to the queue during the materialize. If a value of binary 0 is specified, MATQMSG blocks out all other activity to the queue during the materialize. If a value of binary 1 is specified, MATQMSG allows concurrent enqueue (ENQ instruction) and dequeue (DEQ instruction) activity to the queue during the materialize.

In the following cases, the value specified for enqueue and dequeue mode is ignored and activity to the queue is blocked during the materialize:

• The queue type is last in first out (LIFO).

• The queue type is keyed and the key length is greater than 240 bytes.

Usage Note

On all current and foreseen implementations of the machine, concurrent mode includes overhead which may slow the materialize down. However, concurrent dequeues from the same queue by other threads during a long-running materialize could see a performance gain. Therefore, concurrent mode is recommended when it is necessary to maintain dequeue performance during potentially long running materialize operations.

Authorization Required

• Retrieve

  • Operand 2

• Execute

  • Contexts referenced for address resolution

Lock Enforcement

• Materialization

  • Operand 2

  • Contexts referenced for address resolution

Exceptions

06 Addressing

• 0601 Space Addressing Violation
• 0602 Boundary Alignment
• 0603 Range

08 Argument/Parameter

• 0801 Parameter Reference Violation

0A Authorization

• 0A01 Unauthorized for Operation

10 Damage Encountered

• 1004 System Object Damage State
• 1005 Authority Verification Terminated Due to Damaged Object
• 1044 Partial System Object Damage

1A Lock State

• 1A01 Invalid Lock State

20 Machine Support

• 2002 Machine Check
• 2003 Function Check

22 Object Access

• 2201 Object Not Found
• 2202 Object Destroyed
• 2205 Object Not Available to Process
• 2207 Authority Verification Terminated Due to Destroyed Object
• 2208 Object Compressed
• 220B Object Not Available

24 Pointer Specification

• 2401 Pointer Does Not Exist
• 2402 Pointer Type Invalid
• 2403 Pointer Addressing Invalid Object Type

2E Resource Control Limit

• 2E01 User Profile Storage Limit Exceeded

32 Scalar Specification

• 3201 Scalar Type Invalid
• 3202 Scalar Attributes Invalid
• 3203 Scalar Value Invalid

36 Space Management

• 3601 Space Extension/Truncation

38 Template Specification

• 3803 Materialization Length Invalid

44 Protection Violation

• 4401 Object Domain or Hardware Storage Protection Violation
• 4402 Literal Values Cannot Be Changed