The ENQUEUE function

The ENQUEUE function is provided on the DFHNQEDX macro call. It allows you to enqueue on a named resource.

By default, all enqueues created by XPI ENQUEUE commands are allocated to a specific enqueue pool called DISPATCH and are treated as internal to CICS. XPI enqueues do not conflict with enqueues created by EXEC CICS ENQ commands, which are added to different enqueue pools, depending on the enqueue model specified. For example, an active EXEC CICS ENQ on a string does not prevent an XPI ENQUEUE command on the same string being obtained.

Note:

XPI enqueues cannot be browsed using the CICS SPI.
XPI enqueues cannot be controlled by the use of ENQMODELs.

When you use the optional ENQUEUE_TYPE parameter, the XPI ENQUEUE command can enqueue on the same resource being enqueued on by EXEC CICS ENQ or vice versa. Applications can synchronize processes using EXEC CICS and EXEC XPI commands.

ENQUEUE

DFHNQEDX [CALL,]
      [CLEAR,]
      [IN,
      FUNCTION(ENQUEUE),
      ENQUEUE_NAME1(address,length),
      [ENQUEUE_NAME2(address,length),]
      MAX_LIFETIME(DISPATCHER_TASK),
     [ENQUEUE_TYPE (XPI | EXECSTRN | EXECADDR),] 
      [WAIT(YES|NO),]
      [PURGEABLE(YES|NO),]]
      [OUT,
      [ENQUEUE_TOKEN(name4),]
      [DUPLICATE_REQUEST,]
      RESPONSE (name1 | *),
      REASON(name1 | *)]

This command is threadsafe.

DUPLICATE_REQUEST

Indicates that the requesting dispatcher task already owns the resource being enqueued.

ENQUEUE_NAME1(address,length)

Specifies the high-order part of the name to be enqueued.

ENQUEUE_NAME2(address,length)

Specifies the low-order part, if any, of the name to be enqueued.

ENQUEUE_TOKEN(name4)

Enables a subsequent DEQUEUE request to identify the resource by a token rather than enqueue name, allowing the NQ domain to locate the enqueue control block directly, and hence more efficiently.

ENQUEUE_TYPE (XPI | EXECSTRN | EXECADDR)

Specifies the type of resource being enqueued on. The XPI option specifies the typical DFHNQEDX behavior. The resource pool used is exclusive to XPI and cannot be accessed by the CICS API. Use EXECSTRN or EXECADDR to indicate that ENQUEUE_NAME1 specifies an enqueue resource, located in the same namespace as the one being used by EXEC CICS ENQ. For more information about EXECSTRN and EXECADDR, see The resources on which CICS system tasks can wait.

MAX_LIFETIME(DISPATCHER_TASK)

MAX_LIFETIME(DISPATCHER_TASK) is required and specifies that all XPI enqueues are owned by the requesting dispatcher task.

If you use the ENQUEUE XPI call to ensure that your global user exit programs are threadsafe, you are recommended to free (dequeue) resources during the invocation of the global user exit program in which they were enqueued. However, because no recovery services are provided for stopping global user exits, CICS® ensures that any outstanding XPI enqueues are dequeued automatically when the dispatcher task ends. If the dispatcher task is running a CICS transaction, the dispatcher task ends when the CICS transaction ends, whether normally or abnormally.

Usually, enqueues are owned by the requesting transaction, which contains units of work (UOWs), and these are used to anchor the enqueue control blocks. The XPI, however, does not require a transaction environment, and global user exits can be called under dispatcher tasks that have no transactions or UOWs.

PURGEABLE(YES|NO)

Specifies whether a purge (or timeout) request against the task is to be honored if the requesting dispatcher task has to wait for the enqueue.

WAIT(YES|NO)

Specifies whether the dispatcher task is to wait if the resource is currently enqueued to another dispatcher task.

RESPONSE and REASON values for ENQUEUE

RESPONSE	REASON
OK	None
EXCEPTION	ENQUEUE_BUSY ENQUEUE_LOCKED ENQUEUE_DISABLED LIMIT_EXCEEDED SYSENQ_FAILURE INVALID_PHASE
PURGED	TASK_CANCELLED TIMED_OUT