Dequeue (DEQ)

Operand 2: Space pointer.

Operand 3: System pointer or space pointer data object.

Operand 4-5:

• Branch Form-Branch point, instruction pointer, relative instruction number, or absolute instruction number.

• Indicator Form-Numeric variable scalar or character variable scalar.

Built-in number for DEQ is 41.
DEQ (
     message_prefix   : address
     message_text     : address
     queue            : address of system pointer OR
                        address of space pointer(16)
) :   signed binary(4) /* return_code */

 
  -- OR --
 
Built-in number for DEQWAIT is 42.
DEQWAIT (
         message_prefix   : address
         message_text     : address
         queue            : address of system pointer OR
                            address of space pointer(16)
)

Description

Retrieves a queue message based on the queue type (FIFO, LIFO, or keyed) specified during the queue's creation. If the queue was created with the keyed option, messages can be retrieved by any of the following relationships between an enqueued message key and a selection key specified in operand 1 of the Dequeue instruction: =, <>, >, <, <=, and >=. If the queue was created with either the LIFO or FIFO attribute, then only the next message can be retrieved from the queue.

If a message is not found that satisfies the dequeue selection criterion and the branch or indicator options are not specified, the thread waits until a message arrives to satisfy the dequeue or until the dequeue wait time-out expires. If branch or indicator options are specified, the thread is not placed in the dequeue wait state and either the control flow is altered according to the branch options, or indicator values are set based on the presence or absence of a message to be dequeued.

If operand 3 is a system pointer, the message is dequeued from the queue specified by operand 3. If operand 3 is a space pointer, the message is dequeued from the queue which is specified in the template pointed to by the space pointer. The format of this template is given later in this section. The criteria for message selection are given in the message prefix specified by operand 1. The message text is returned in the space specified by operand 2, and the message prefix is returned in the scalar specified by operand 1. If an exception is signaled, the message text and message prefix may be changed, but do not contain valid data. Improper alignment results in an exception being signaled. The format of the message prefix is as follows:

A nonzero dequeue wait time-out value overrides any dequeue wait time-out value specified as the current process attribute. A zero dequeue wait time-out value causes the wait time-out value to be taken from the current process attribute. If all wait time-out values are 0 (from the Dequeue instruction and the current process attribute), a dequeue time-out  (hex 3A01) exception is signaled. See Standard Time Format for additional information on the format of the dequeue wait time-out. The maximum dequeue wait time-out interval allowed is a value equal to (2⁴⁸ - 1) microseconds. Any value that indicates more time than the maximum wait time-out causes the maximum wait time-out to be used.

The size of message dequeued is returned in the message prefix. The size of message dequeued can be less than or equal to the maximum size of message specified when the queue was created. When dequeuing from a keyed queue, the length of the search key field and the length of the message key field (in the message key prefix specified in operand 1) are determined implicitly by the attributes of the queue being accessed. If the message text on the queue contains pointers, the message text operand must be 16-byte aligned.

The access state of the process access group is modified when a Dequeue instruction results in a wait and the following conditions exist:

• The process' instruction wait initiation access state control attribute specifies allow access state modification

• The dequeue access state modification option specifies modify access state

• The multiprogramming level option specifies leave MPL set during wait.

• The process is not multi-threaded (i.e. the waiting thread is the only thread in the process)

The thread will remain in the current MPL set for an implementation-defined period which will not exceed 2 seconds, if the multiprogramming level option specifies remain in current MPL set at Dequeue wait. If the wait has not been satisfied at the end of this period, the thread will automatically be removed from the current MPL set. The automatic removal does not change or affect the total wait time specified for the thread by the dequeue wait time-out value.

Operand 3 can be a system pointer or a space pointer. If it is a system pointer, this pointer will be addressing the queue from which the message is to be dequeued. If it is a space pointer, this pointer will be addressing a template which will contain the system pointer to the queue as well as the dequeue template extension. The queue template is 32 bytes in length and must be aligned on a 16-byte boundary with the format as follows:

The modify thread event mask option controls the state of the event mask in the thread executing this instruction. If the modify thread event mask option field specifies to modify thread event mask, the thread event mask will be changed as specified by the new thread event mask field. When the thread event mask is changed, the current thread event mask will be returned in the previous thread event mask field. The previous thread event mask is only returned when the modify thread event mask option is set to 1.

If the system security level machine attribute is hex 40 or greater and the thread is running in user state, a template value invalid  (hex 3801) exception is signalled if the modify thread event mask option is set to modify thread event mask.

If the thread event mask is in the masked state, the machine does not schedule signaled event monitors in the thread. The event monitors continue to be signaled by the machine or other threads. When the thread is modified to the unmasked state, event handlers are scheduled to handle those events that occurred while the thread was masked and those events occurring while in the unmasked state. The number of signals retained while the thread is masked is specified by the attributes of the event monitor associated with the process or thread.

The thread is automatically masked by the machine when event handlers are invoked. If the thread is unmasked in the event handler, other events can be handled if another enabled event monitor within that thread is signaled. If the thread is masked when it exits from the event handler, the machine explicitly unmasks the thread.

Valid masking values are:

Other values are reserved and must not be specified. If any other values are specified, a template value invalid  (hex 3801) exception is signaled.

Whether masking or unmasking the current thread, the new mask takes effect upon completion of a satisfied dequeue.

The asynchronous signals processing option controls the action to be taken if an asynchronous signal is pending or received while in a Dequeue wait. If an asynchronous signal that is not blocked or ignored is generated for the process and the asynchronous signals processing option indicates allow asynchronous signal processing during Dequeue wait, the Dequeue wait will be terminated and an asynchronous signal terminated MI wait  (hex 4C01) exception is signaled. Otherwise, when the asynchronous signals processing option indicates do not allow asynchronous signal processing during Dequeue wait, the process remains in the wait until a message arrives to satisfy the dequeue or until the dequeue wait time-out value expires.

Resultant Conditions

• Equal - message dequeued

• Not equal - message not dequeued

Authorization Required

• Retrieve

  • Operand 3

• Execute

  • Contexts referenced for address resolution

Lock Enforcement

• Materialize

  • Contexts referenced for address resolution

• Modify

  • Operand 3

    • When the locking attribute of the queue is set to enforce queue object locks then this instruction will attempt to get a shared update lock on the queue before performing the dequeue. If it fails to get the lock an object not available to process  (hex 2205) exception will be signaled and the instruction may be tried again. The MATQAT instruction can be used to materialize the locking attribute of the queue.

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

1C Machine-Dependent

• 1C03 Machine Storage Limit Exceeded
• 1C0E IASP Resources Exceeded
• 1C11 Independent ASP Varied Off

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

30 Journal

• 3002 Entry Not Journaled

32 Scalar Specification

• 3203 Scalar Value Invalid

38 Template Specification

• 3801 Template Value Invalid

3A Wait Time-Out

• 3A01 Dequeue Time-Out

44 Protection Violation

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

4C Signals Management

• 4C01 Asynchronous Signal Terminated MI Wait