NQED gate, ENQUEUE function

This functions obtains an enqueue from the specified enqueue pool in active state.

Input Parameters

ENQUEUE_NAME1
Optional Parameter
A block (addr,len) identifying the name of the enqueue being released. Or alternatively identifies the prefix of the enqueue name which when combined with the ENQUEUE_NAME2 parameter forms the name of the enqueue being released.
ENQUEUE_NAME2
Optional Parameter
A block (addr,len) identifying the second half of the enqueue name.
MAX_LIFETIME
Optional Parameter
Indicates the maximum duration of the enqueue.
DISPATCHER_TASK
The enqueue will be released if it is held when a DEQUEUE_ALL request is issued by the owning dispatcher task. This is the only value permitted when POOL_TOKEN is not supplied on the call.
TRANSACTION
The enqueue will be acquired with a duration of the last UOW of the current transaction.
UOW
The enqueue will be acquired with a duration of the current UOW. This is the default value when not supplied on the call.
Values for the parameter are:
  • DISPATCHER_TASK
  • TRANSACTION
  • UOW
POOL_TOKEN
Optional Parameter
Token representing enqueue pool from which the enqueue is to be allocated.
PURGEABLE
Optional Parameter
Indicates if the task is purgeable.
Values for the parameter are:
  • NO
  • YES
SHUNT_ACTION
Optional Parameter

Indicates the action that is to be performed if this UOW is shunted whilst it owns the enqueue. This parameter acts as an override, if not supplied then the default shunt action specified when the pool was created is assumed for this enqueue request.

The shunt action is only applicable to UOW lifetime enqueues. An error is diagnosed if this parameter is supplied on a request for a transaction lifetime enqueue. The possible overrides are as follows:
RELEASE
The enqueue will be released if the UOW is shunted.
RETAIN
The enqueue will be retained if the UOW is shunted.
IGNORE
The shunt will be ignored. The enqueue will remain in the same state as it is currently held in.
Values for the parameter are:
  • IGNORE
  • RELEASE
  • RETAIN
WAIT
Optional Parameter
Indicates whether the caller wants to wait if the requested enqueue is currently held in the pool by a different UOW. The possible values are as follows:
NO
The ENQUEUE_BUSY exception is returned to the caller if the enqueue is busy.
YES
The caller will be suspended if the enqueue is busy. This is the default value when not supplied on the call.
Note that callers specifying WAIT(NO) should still expect to suspend for the NQ domain lock.
Values for the parameter are:
  • NO
  • YES

Output Parameters

REASON
The values for the parameter are:
  • ENQUEUE_BUSY
  • ENQUEUE_DISABLED
  • ENQUEUE_LOCKED
  • INVALID_PHASE
  • INVALID_POOL_TOKEN
  • LIMIT_EXCEEDED
  • SHUNT_ACTION_NOT_EXPECTED
  • SYSENQ_FAILURE
  • TASK_CANCELLED
  • TIMED_OUT
RESPONSE
Indicates whether the domain call was successful. For more information, see RESPONSE parameter on domain interfaces.
DUPLICATE_REQUEST
Optional Parameter
When RESPONSE(OK) is returned, indicates whether the caller already owned the enqueue or not:
Values for the parameter are:
  • NO
  • YES
ENQUEUE_TOKEN
Optional Parameter
A token returned to represent the enqueue that has been successfully returned. The token can then be used on the corresponding DEQUEUE request.


dfhs3_NQEDenqueue.html | Timestamp icon Last updated: Monday, 5 June 2017