Enqueue (ENQ)

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