Enqueue domain XPI functions

There are two XPI enqueue domain functions. These are the DFHNQEDX macro calls ENQUEUE and DEQUEUE.

The ENQUEUE function

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

Start of changeAll enqueues created by XPI ENQUEUE commands are allocated to a specific enqueue pool called "DISPATCH" and are treated as internal to CICS. Thus 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 on the same string being obtained. Furthermore:

End of change
ENQUEUE

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

Start of changeThis command is threadsafe.End of change

DUPLICATE_REQUEST
indicates that the requesting dispatcher task already owns the resource being enqueued.
ENQUEUE_NAME1(address,length)
specifies the high-order part of name to be enqueued.
ENQUEUE_NAME2(address,length)
specifies the low-order part, if any, of 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.
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, as no recovery services are provided for abending global user exits, CICS® ensures that any outstanding XPI enqueues are dequeued automatically when the dispatcher task terminates. Note that if the dispatcher task is running a CICS transaction, the dispatcher task terminates when the CICS transaction terminates (whether normally or abnormally).

Normally 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 may be invoked under dispatcher tasks which 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  
PURGED
TASK_CANCELLED
TIMED_OUT     

The DEQUEUE function

The DEQUEUE function is provided on the DFHNQEDX macro call. It releases a resource previously enqueued by an ENQUEUE function call.

DEQUEUE

DFHNQEDX [CALL,]
      [CLEAR,]
      [IN,
      FUNCTION(DEQUEUE),
      {ENQUEUE_TOKEN(name4),|
      ENQUEUE_NAME1(address,length),[ENQUEUE_NAME2(address,length),]}
      MAX_LIFETIME(DISPATCHER_TASK),]
      [OUT,
      RESPONSE (name1 | *),
      REASON(name1 | *)]

Start of changeThis command is threadsafe.End of change

The ENQUEUE_TOKEN, ENQUEUE_NAME1, ENQUEUE_NAME2, and MAX_LIFETIME(DISPATCHER_TASK) parameters are the same as in the ENQUEUE function call.

RESPONSE and REASON values for DEQUEUE

RESPONSE REASON
OK None
EXCEPTION
ENQUEUE_NOT_OWNED
ENQUEUE_LOCKED   

Related concepts
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Making an XPI call
Writing global user exit programs
Writing a task-related user exit program
Related reference
The XPI functions
[[ Contents Previous Page | Next Page Index ]]