Materialize Queue Messages (MATQMSG)

Edit online

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2 Operand 3
033B Receiver Queue Message selection template
Operand 1: Space pointer.

Operand 2: System pointer.

Operand 3: Character(16) scalar.

Bound Program Access 
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:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Materialization 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 Materialization data Char(4)
8 8
  • Count of messages available for materialization
  • Bin(4)
12 C Queue data Char(12)
12 C
  • Count of messages on the queue
  • Bin(4)
16 10
  • Maximum message size
  • Bin(4)
20 14
  • Key size
  • Bin(4)
24 18 Reserved Char(8)
32
20
Message data
(repeated for each message)
[*] Char(*)
32 20
  • Message attributes
  • Char(16)
32 20
    • Message enqueue time
    • Char(8)
40 28
    • Message length
    • Bin(4)
44 2C
    • Reserved
    • Char(4)
48 30
  • Message key
  • Char(*)
* *
  • Message text
  • Char(*)
*
*
--- End ---
 

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 message enqueue time is the value of the system time-of-day clock (local time) when the message was enqueued by the Enqueue (ENQ) instruction. The time-of-day used is not unique (all the uniqueness bits are set to zero). See Standard Time Format for additional information on the format of the message enqueue time field.

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:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Message selection Char(2)
0
0
  • Type
    0001 =
    All messages
    0010 =
    First
    0100 =
    Last
    1000 =
    Keyed

    All other values are reserved
  • Bits 0-3
0
0
  • Key relationship (if needed)
    0010 =
    Greater than
    0100 =
    Less than
    0110 =
    Not equal
    1000 =
    Equal
    1010 =
    Greater than or equal
    1100 =
    Less than or equal

    All other values are reserved
  • Bits 4-7
0 0
  • Reserved
  • Bits 8-15
2 2 Lengths Char(8)
2 2
  • Number of key bytes to materialize
  • Bin(4)
6 6
  • Number of message text bytes to materialize
  • Bin(4)
10 A Materialize options Char(1)
10
A
  • Enqueue and dequeue mode
    0 =
    Blocked mode
    1 =
    Concurrent mode
  • Bit 0
10 A
  • Reserved
  • Bits 1-7
11 B Reserved Char(5)
16 10 Key (if needed) Char(*)
*
*
--- End ---
 

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 Notes

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