Enqueue (ENQ)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2 Operand 3
036B Queue Message prefix Message text
Operand 1: System pointer.

Operand 2: Character scalar.

Operand 3: Space pointer.

Bound Program Access 
Built-in number for ENQ is 43.
ENQ (
     queue            : address of system pointer
     message_prefix   : address
     message_text     : address
)

Description:

A message is enqueued according to the queue type attribute specified during the queue's creation.

If keyed sequence is specified, enqueued messages are sequenced in ascending binary collating order according to the key value. If a message to be enqueued has a key value equal to an existing enqueued key value, the message being added is enqueued following the existing message.

If the queue was defined with either last in, first out (LIFO) or first in, first out (FIFO) sequencing, then enqueued messages are ordered chronologically with the latest enqueued message being either first on the queue or last on the queue, respectively. A key can be provided and associated with messages enqueued in a LIFO or FIFO queue; however, the key does not establish a message's position in the queue. The key can contain pointers, but the pointers are not considered to be pointers when they are placed on the queue by an Enqueue instruction.

Operand 1 specifies the queue to which a message is to be enqueued. Operand 2 specifies the message prefix, and operand 3 specifies the message text.

The format of the message prefix is as follows:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Size of message to be enqueued Bin(4)
4 4 Enqueue key value (ignored for FIFO/LIFO queues with key lengths equal to 0) Char(key length)

*

*

--- End ---

 

The size of message to be enqueued is supplied to inform the machine of the number of bytes in the space that are to be considered message text. The size of the message is then considered the lesser of the size of message to be enqueued attribute and the maximum message size specified on queue creation. The message text can contain pointers. When pointers are in message text, the operand 3 space pointer must be 16-byte aligned. Improper alignment will result in an exception being signaled.

If the enqueued message causes the number of messages to exceed the maximum number of messages attribute of the queue, one of the following occurs:

  • If the queue is not extendable, or if the maximum number of extends specified by the user at queue creation has been reached, then the queue full (hex 2602) exception is signaled. The message is not enqueued.
  • If the queue is extendable, the queue is implicitly extended by the extension value attribute. The message is enqueued. No exception is signaled.

Limitations (Subject to Change)

The maximum allowable queue size, including all messages currently enqueued and the machine overhead, is 2 gigabytes.

Authorization Required

  • Insert
    • Operand 1
  • Execute
    • Contexts referenced for address resolution

Lock Enforcement

  • Materialize
    • Contexts referenced for address resolution
  • Modify
    • Operand 1
      • 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 enqueue. 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
    • 1C04 Object 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
  • 26 Process Management
    • 2602 Queue Full
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 30 Journal
    • 3002 Entry Not Journaled
  • 36 Space Management
    • 3601 Space Extension/Truncation
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed
Parent topic: Queue Management