Materialize Queue Attributes (MATQAT)

Operand 2: System pointer.

Built-in number for MATQAT is 44.
MATQAT (
        receiver   : address
        queue      : address of system pointer
)

Description

The attributes of the queue specified by operand 2 are materialized into the receiver specified by operand 1. The receiver must be aligned on a 16-byte multiple. The format of the materialized queue attributes is as follows:

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.

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 (other than the materialization length invalid  (hex 3803) exception described previously) are signaled when the receiver contains insufficient area for the materialization.

The following fields in the template are returned. No queue attributes are modified by the MATQAT instruction.

The object identification specifies the symbolic name that identifies the queue within the machine. An object type of hex 0A is implicitly supplied by the machine. The object identification is used to identify the object on materialize instructions as well as to locate the object in a context that addresses the object.

If the created object is permanent, it is owned by the user profile governing thread execution when the queue was created. The owning user profile is implicitly assigned all private authority states for the object. The storage occupied by the created object is charged to this owning user profile. If the created object is temporary, no owning user profile exists, and all authority states are assigned as public. Storage occupied by the created object is charged to the creating process.

The existence attribute specifies whether the queue is to be created as temporary or permanent. A temporary queue, if not explicitly destroyed by the user, is implicitly destroyed by the machine when machine processing is terminated.

If a space is associated with the queue, the space may be fixed or variable in size, as specified by the space attribute. The current allocation is as specified in the size of space field. The machine allocates a space of at least the size specified at queue creation; the actual size allocated depends on an algorithm defined by a specific implementation.

If the initial context attribute field indicates that addressability is inserted in a context, the context field contains a system pointer that identifies the context where addressability to the queue is placed.

If the access group creation attribute field indicates member of access group, the access group field contains a system pointer that identifies the access group in which the object was created. Only temporary queues may be created in an access group.

The initialize space creation option controls whether or not the space is to be initialized. When initialize is specified, each byte of the space is initialized to the value specified by the initial value of space field. Additionally, when the space is extended in size, this byte value is also used to initialize the new allocation. When do not initialize is specified, the initial value of space field is ignored and the initial value of the bytes of the space are unpredictable.

When do not initialize is specified for a space, internal machine algorithms do ensure that any storage resources last used for allocations to another object which are reused to satisfy allocations for the space are reset to a machine default value to avoid possible access of data which may have been stored in the other object. To the contrary, reuse of storage areas previously used by the space object are not reset, thereby exposing subsequent reallocations of those storage areas within the space to access of the data which was previously stored within them.

The message content attribute specifies whether the messages to be enqueued will contain pointers and scalar data, or scalar data only. If the messages are to contain pointers, the message text operand on Enqueue and Dequeue instructions must be aligned on 16-byte boundaries.

The queue type attribute establishes the basic sequence in which messages are dequeued from the queue.

The current number of messages enqueued field contains the number of messages currently enqueued on the queue.

The queue overflow action field establishes the machine action when the number of messages resident on the queue (enqueued and not yet dequeued) exceeds the current maximum capacity of the queue. This value is initially established by the value specified in the maximum number of messages field. The queue full  (hex 2602) exception is signalled when the number of resident messages exceeds this field unless the extend queue option is specified. When the extend queue option is specified for the queue overflow action field, the value of the current maximum number of messages field is increased by the amount specified by the extension value field each time the number of enqueued messages exceeds the value of the current maximum number of messages field. When the extend queue option is specified for the queue overflow action field, the extension value field contains a value greater than 0. If the signal exception option is specified, the extension value field is ignored and the current maximum number of messages field contains a value greater than zero.

The choose maximum number of extends field allows the user to overide the value for the maximum number of extends to the queue which would otherwise be chosen by the machine. If this field specifies machine chooses maximum number of extends, then the number of extends will be chosen such that the maximum number of messages for the queue will never be greater than what can be completely materialized into 16MB or require overall object size greater than 32MB. The overall object size depends upon the amount of storage needed for queue definition plus entries enqueued to queue and excludes the size of the associated space, if any. If this field specifies user specifies maximum number of extends, the queue will be extended by the number of messages specified by the extension value field until the number of extends reaches the value returned by the maximum number of extends field is reached. The current number of extends field specifies the number of times the queue has currently been extended.

The reclaim storage field specifies whether storage reclaim will be attempted when the number of currently enqueued messages on the queue reaches zero. If this field specifies reclaim storage when messages enqueued is zero then the size of the queue will be reduced to the number of messages specified by the initial number of messages field when the queue was created. The current number of extends field is reset to zero after the queue is reclaimed. If this field specifies do not reclaim queue storage then no reclaim action is taken.

The locking attribute field specifies whether the queue will enforce locks. If this field specifies enforce queue object locks then operations to the queue will obtain locks before proceeding. If this field specifies do not enforce queue object locks then no locking action is taken.

The key length field establishes the size of the queue's key. The key can contain pointers, but the pointers are considered to be scalar data when they are placed on the queue by an Enqueue instruction. If the queue type field specifies LIFO or FIFO, the key length can be equal to or greater than 0; however, the queue is not treated as a keyed queue.

The size of all messages to be enqueued is established by the maximum size of messages to be enqueued field. The Enqueue instruction may specify a size (in the message prefix) that is greater than this value, but the message is truncated to this length. The maximum size of messages to be enqueued field has a value of 0 or greater, up to a maximum value of 64 K bytes. The maximum size of a queue, excluding its associated space, cannot exceed 2 gigabytes. This value includes machine overhead associated with the queue.

The timestamp of last queue storage reclaim field contains the time of the last storage reclaim for this queue if the reclaim queue storage field is set to queue storage will be reclaimed when queue is empty. If the reclaim queue storage field is set to queue storage will not be reclaimed when queue is empty then the timestamp of last queue storage reclaim will be hex zeros. See Standard Time Format for additional information on the format of a timestamp.

Limitations (Subject to Change)

The following are limits that apply to the functions performed by this instruction. These limits may change on different implementations of the machine.

The size of the object specific portion of this object is limited to a maximum of 2 gigabytes. This size is dependent upon the amount of storage needed for the queue definition plus entries enqueued to queue and excludes the size of the associated space, if any.

The size of the associated space for this object is limited to a maximum of 16MB-32 bytes if the machine does not choose the space alignment and 0 is specified for the space alignment field. The size of the associated space for this object is limited to a maximum of 16MB-512 bytes if the machine does not choose the space alignment and 1 is specified for the space alignment field. The maximum size of an associated space for this object if the machine choose the space alignment is returned by option Hex 0003 of MATMDATA.

Authorization Required

• Operational

  • Operand 2

• Execute

  • Contexts referenced for address resolution

Lock Enforcement

• Materialize

  • 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

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