There are two XPI enqueue domain functions. These are the DFHNQEDX macro calls ENQUEUE and DEQUEUE.
The ENQUEUE function is provided on the DFHNQEDX macro call. It allows you to enqueue on a named resource.
All 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:
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 | *)]
This command is threadsafe.
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.
RESPONSE | REASON |
---|---|
OK | None |
EXCEPTION |
ENQUEUE_BUSY ENQUEUE_LOCKED ENQUEUE_DISABLED LIMIT_EXCEEDED SYSENQ_FAILURE |
PURGED |
TASK_CANCELLED TIMED_OUT |
The DEQUEUE function is provided on the DFHNQEDX macro call. It releases a resource previously enqueued by an ENQUEUE function call.
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 | *)]
This command is threadsafe.
The ENQUEUE_TOKEN, ENQUEUE_NAME1, ENQUEUE_NAME2, and MAX_LIFETIME(DISPATCHER_TASK) parameters are the same as in the ENQUEUE function call.
RESPONSE | REASON |
---|---|
OK | None |
EXCEPTION |
ENQUEUE_NOT_OWNED ENQUEUE_LOCKED |