Enqueue domain's specific gates

Table 74 summarizes the NQ domain's specific gate. It shows the level-1 trace point IDs of the modules providing the functions for the gate and the functions provided by the gate. The DFHNQEDX XPI macro provides ENQUEUE and DEQUEUE functions for the NQ domain.

Table 74. NQ domain’s specific gates
Gate Trace Function
NQNQ
NQ 0201
NQ 0202
CREATE_ENQUEUE_POOL
DEACTIVATE
REACQUIRE_ENQUEUE
SET_NQRNAME_LIST
DEQUEUE_TASK
NQED
NQ 0301
NQ 0302
ENQUEUE
DEQUEUE
NQIB
NQ 0401
NQ 0402
INQUIRE_ENQUEUE
START_BROWSE_ENQUEUE
GET_NEXT_ENQUEUE
END_BROWSE_ENQUEUE
NQRN
NQ 0601
NQ 0602
INQUIRE_NQRNAME
ADD_REPLACE_ENQMODEL
DISCARD_ENQMODEL
REMOVE_ENQMODEL
INQUIRE_ENQMODEL
START_BROWSE_ENQMODEL
GET_NEXT_ENQMODEL
END_BROWSE_ENQMODEL
SET_ENQMODEL
COMMIT_ENQMODEL
RESTORE_DIRECTORY
NQIE
NQ FF50
NQ FF51
INTERPRET_ENQUEUE

NQNQ gate, CREATE_ENQUEUE_POOL function

This function creates a separate enqueue pool for the caller. A token is returned which the caller specifies on all requests associated with that pool.

Input parameters:

POOL_NAME
The eight character name of the new enqueue pool.
EXPECTED_NAME_LENGTH
The expected length for enqueue names in the pool.

For pools with fixed length enqueue names this should be the length of the names that are going to be enqueued upon.

For pools that are to contain variable length enqueue names this should be a length that would satisfy 'most' of the requests to be made in the pool.

Note that is no maximum length for enqueue names. However, requests will only be handled inline if the length of the enqueue name is less than or equal to the EXPECTED_NAME_LENGTH. The inline macro only copes with names of less than or equal to 256 characters. For this reason an error will be diagnosed if a value of greater than 256 is specified for this parameter.

SHUNT_ACTION
Indicates the default action that is to be performed to UOW lifetime enqueues in this pool if their owning UOW is shunted. Note that most enqueue pools will require the same action to be performed for all enqueues in that pool. However, the ENQUEUE function allows this default to be overridden for particular enqueue requests.

The possible values are as follows:

RELEASE
The enqueue(s) will be released if the owning UOW is shunted.
RETAIN
The enqueue(s) will be retained if the owning UOW is shunted.
IGNORE
The shunt will be ignored. The enqueue(s) will remain in the same state as currently held in.

Transaction lifetime enqueues are automatically released when a shunt occurs.

ERROR_LEVEL
Indicates the severity of the error response that is to be returned for the following errors made while using this pool:

The possible values for ERROR_LEVEL are as follows:

EXCEPTION_RESPONSE
The above errors are to be returned with an exception response.
INVALID_RESPONSE
The above errors are to be returned with an invalid response. (i.e. FFDC is to be performed).
Note:
It is expected that only the EXEC and the KC enqueue pools will specify EXCEPTION_RESPONSE since the DFHKC service previously used by them allowed these sorts of error to go by undetected.
EXEC_INTERPRETER
Indicates how enqueues belonging to the enqueue pool are to be interpreted by the EXEC CICS® INQUIRE UOWENQ command.

The possible values are as follows:

NONE
No interpreter has been supplied so enqueues belonging to this pool will be ignored by the INQUIRE UOWENQ command.
DEFAULT
Enqueues are to be returned by the INQUIRE UOWENQ command. The default NQ domain interpreter will be called to perform the interpretation. This will map the outputs of the INQUIRE UOWENQ command as follows:
TYPE
Will be the CVDA corresponding to the ENQUEUE_TYPE parameter supplied on this call.
RESOURCE
Will be ENQUEUE_NAME1 as supplied on the NQED_ENQUEUE function.
QUALIFIER
Will be ENQUEUE_NAME2 if supplied on the NQED_ENQUEUE function. If not then no QUALIFIER data will be returned.
OWN
Enqueues are to be returned by the INQUIRE UOWENQ command. A routine provided by the pool owner will perform the interpretation. In this case the entry point of the routine must be passed in the INTERPRETER_ADDR parameter.
Note:
The routine will be called by a kernel subroutine call, not by a domain call. Consequently it will execute in the domain of the caller (i.e. AP domain).
OWN_INTERPRETER_ADDRESS
Entry point of interpreter routine for this pool. Should only be supplied for pools which specify a value of OWN for the EXEC_INTERPRETER parameter.
ENQUEUE_TYPE
The enqueue type that is to be returned by the default interpreter. Should only be supplied for pools which specify a value of DEFAULT for the EXEC_INTERPRETER parameter.

The possible values are as follows and these map onto the CVDA values for the TYPE field as detailed under the EXEC CICS INQUIRE UOWENQ command.

Output parameters:

POOL_TOKEN
Token returned which identifies the newly created enqueue pool.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
INVALID
INTERPRETER_ADDR_EXPECTED
ENQUEUE_TYPE_EXPECTED
DUPLICATE_POOL_NAME
INVALID_NAME_LENGTH

NQNQ gate, DEACTIVATE function

This function converts an active enqueue into retained state. The caller must already own the enqueue.

Input parameters:

POOL_TOKEN
Token representing enqueue pool from which the enqueue is to be deactivated.
ENQUEUE_TOKEN
Token representing the enqueue that is to be deactivated.

Slightly better performance is achieved for callers that use the token method for this function.

ENQUEUE_NAME1
A block (addr,len) identifying the name of the enqueue to be deactivated.

Or alternatively identifies the prefix of the enqueue name which when combined with the ENQUEUE_NAME2 parameter forms the name of the enqueue to be deactivated.

ENQUEUE_NAME2
A block (addr,len) identifying the second half of the enqueue name.

Output parameters:

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION
ENQUEUE_NOT_OWNED
ENQUEUE_NOT_ACTIVE
INVALID
ENQUEUE_NOT_OWNED
ENQUEUE_NOT_ACTIVE
TRANSACTION_ENQUEUE
INVALID_POOL_TOKEN

NQNQ gate, REACQUIRE_ENQUEUE function

NQ domain doesn't recover enqueues over a CICS restart. Instead resource owners use this function to reacquire enqueues that were held by inflight and indoubt UOWs.

The enqueue can be reacquired in either active or retained state. The calling UOW must currently be shunted.

No MAX_LIFETIME input is provided since such enqueues are only ever associated with a single UOW.

The same rules as documented for the mainline ENQUEUE function apply to the shunt action that will be associated with the reacquired enqueue.

Input parameters:

POOL_TOKEN
Token representing enqueue pool from which the enqueue is to be allocated from.
ENQUEUE_NAME1
A block (addr,len) identifying the name of the enqueue.

Or alternatively identifies the prefix of the enqueue name which when combined with the ENQUEUE_NAME2 parameter forms the name being enqueued on.

ENQUEUE_NAME2
A block (addr,len) identifying the second half of the enqueue name.
STATE
The state that the enqueue is to be reacquired in.

The possible states are as follows:

ACTIVE
The enqueue is to be reacquired in active state.
RETAINED
The enqueue is to be reacquired in retained state.
SHUNT_ACTION
Indicates the action that is to be performed if the UOW reacquiring the enqueue is shunted again. This parameter acts as an override, if not supplied then the default shunt action specified when the pool was created is assumed for this request.

The possible overrides are as follows:

RELEASE
The enqueue will be released if the UOW is shunted again.
RETAIN
The enqueue will be retained if the UOW is shunted again.
IGNORE
The shunt will be ignored. The enqueue will remain in the same state as it is currently held in.

Output parameters:

ENQUEUE_TOKEN
Token returned to represent the enqueue that has been successfully reacquired.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION
ENQUEUE_LOCKED
ENQUEUE_ACTIVE
INVALID
ENQUEUE_LOCKED
ENQUEUE_ACTIVE
CALLER_NOT_SHUNTED
INVALID_POOL_TOKEN

NQNQ gate, SET_NQRNAME_LIST function

This function is called from three places in dfhnqrn:

discard_enqmodel
IF nqrmodel delete is set THEN the specified nqrmodel is removed from nqrname_list.
Add_replace_enqmodel
IF nqrmodel add is set THEN the specified nqrmodel is added to nqrname_list.
set_nqrmodel
IF neither delete or add is set THEN the specified nqrmodel is set disabled.

Input parameters:

MODEL_TOKEN
The address of the nqrmodel to be set or added to nqrname_list.
POOL_TOKEN
The pool to be searched for matching enqueues
POOL_TWO
An optional second pool to be searched for matching enqueues

Output parameters:

FREE_TOKEN
Address of Model being removed.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION or PURGED. Possible values are:
NQRMODEL_NOT_FOUND
The nqrmodel could not be found in nqrname_list
FREE_NQRMODEL
A nqrmodel has been removed and must be freemained. Its address is in free_token.

NQED gate, ENQUEUE function

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

Input parameters:

POOL_TOKEN
Token representing enqueue pool from which the enqueue is to be allocated.
ENQUEUE_NAME1
A block (addr,len) identifying the name being enqueued on.

Or alternatively identifies the prefix of the enqueue name which when combined with the ENQUEUE_NAME2 parameter forms the name being enqueued on.

ENQUEUE_NAME2
A block (addr,len) identifying the second half of the enqueue name.
MAX_LIFETIME
Indicates the maximum duration that the enqueue is to be held for. The possible values are as follows:
UOW
The enqueue will be released if it is held when the current UOW commits. This is the default value when not supplied on the call.
TRANSACTION
The enqueue will be released if it is held when the last UOW in the current transaction commits.
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.
WAIT
Indicates whether the caller wishes to wait if the requested enqueue is currently held in the pool by a different UOW. The possible values are as follows:
YES
The caller will be suspended if the enqueue is busy. This is the default value when not supplied on the call.
NO
The ENQUEUE_BUSY exception is returned to the caller if the enqueue is busy.
Note that callers specifying WAIT(NO) should still expect to suspend for the NQ domain lock.
SHUNT_ACTION
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.

Output parameters:

ENQUEUE_TOKEN
Token returned to represent the enqueue that has been successfully returned.

The token can then be used on the corresponding DEQUEUE request.

DUPLICATE_REQUEST
When an OK is returned this indicates whether the caller already owned the enqueue or not:
YES
The caller already owned the enqueue.
NO
The caller didn't already own the enqueue.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, PURGED or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION
ENQUEUE_BUSY
ENQUEUE_LOCKED
ENQUEUE_DISABLED
LIMIT_EXCEEDED
SYSENQ_FAILURE
PURGED
TASK_CANCELLED
TIMED_OUT
INVALID
SHUNT_ACTION_NOT_EXPECTED
INVALID_POOL_TOKEN

NQED gate, DEQUEUE function

This functions releases an active enqueue owned by the current UOW from the specified enqueue pool.

Input parameters:

POOL_TOKEN
Token representing enqueue pool from which the enqueue is to be released.
ENQUEUE_TOKEN
Token representing the enqueue that is to be released.

Slightly better performance is achieved for callers that use the token method for releasing their enqueues.

ENQUEUE_NAME1
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
A block (addr,len) identifying the second half of the enqueue name.
MAX_LIFETIME
Indicates the maximum duration of the enqueue being released. The possible values are as follows:
UOW
The enqueue was acquired with a duration of the current UOW. This is the default value when not supplied on the call.
TRANSACTION
The enqueue was acquired with a duration of the last UOW of the current transaction.

Output parameters:

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION
ENQUEUE_NOT_OWNED
ENQUEUE_LOCKED
INVALID
ENQUEUE_NOT_OWNED
ENQUEUE_LOCKED
INVALID_POOL_TOKEN

NQIB gate, INQUIRE_ENQUEUE function

This functions returns information about a particular enqueue. Note that the pool containing the enqueue must be passed since it is a logical extension to the enqueue name.

For inquiries by token it is the caller's responsibility to ensure that the enqueue which the token represents is still held.

Input parameters:

POOL_TOKEN
The token identifying the pool from which the enqueue being inquired about belongs.
ENQUEUE_TOKEN
Token representing the enqueue that is being inquired upon.
ENQUEUE_NAME1
A block (addr,len) identifying the name of the enqueue be inquired upon.

Or alternatively identifies the prefix of the enqueue name which when combined with the ENQUEUE_NAME2 parameter forms the name of the enqueue being inquired upon.

ENQUEUE_NAME2
A block (addr,len) identifying the second half of the enqueue name.

Output parameters:

ENQUEUE_NAME_OUT
A buffer into which the enqueue name is returned. The caller specifies the address and maximum length of the data area into which the enqueue name will be returned. If the enqueue name is too big for the buffer then the data is truncated and an OK response is returned. The actual length of the name is returned in enqueue_name_out_n.

Typically this parameter will only be of interest to callers inquiring by enqueue token.

POOL_NAME
The name of the pool containing the enqueue.
STATE
The state that the enqueue is held in.
ACTIVE
The enqueue is held in active state.
RETAINED
The enqueue is held in retained state.
LOCAL_UOWID
The local UOWID of the UOW which owns the enqueue
UOW_LIFETIME
The number of times the enqueue is held with UOW lifetime.
TRANSACTION_LIFETIME
The number of times the enqueue is held with TRANSACTION lifetime.
NUM_WAITERS
The number of transactions waiting for this enqueue.
NUM_LOCKED_FAILURES
Returns the number of failed requests for this enqueue whilst it is held in retained state.
SHUNT_ACTION
The action that would be performed to this enqueue should its owning UOW be shunted.

The possible values are as follows:

RELEASE
The enqueue will be released.
RETAIN
The enqueue will be retained.
IGNORE
The shunt will be ignored and the enqueue will remain in the same state.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION ENQUEUE_NOT_FOUND
INVALID INVALID_POOL_TOKEN

NQIB gate, START_BROWSE_ENQUEUE function

This function initiates a browse of all enqueues currently in the system or currently associated with a given UOW.

The browse returns both enqueue owners and enqueue waiters. The RELATION output parameter on GET_NEXT_ENQUEUE indicates whether the data being returned is associated with the enqueue owner or a UOW waiting for that enqueue.

When a system wide browse is initiated the first enqueue in the system is returned with RELATION(OWNER). If the enqueue has any waiters then the same enqueue will be returned again for each of the waiters but this time with RELATION(WAITER). The data returned will be that associated with that particular waiter. After the last waiter has been returned the next owned enqueue will be returned.

If the browse is restricted to only a particular UOW then only the enqueues that UOW owns will be returned. If the UOW is waiting for an enqueue this will also be returned.

The order in which the enqueues are returned is undefined, however enqueue waiters are always returned consecutively after their enqueue owner

As with other types of CICS browses the state isn't locked for the duration of the browse. Thus for example, there is no guarantee that the owner returned on a previous GET_NEXT_ENQUEUE is still the owner by the time each of its waiters are returned.

Input parameters:

LOCAL_UOWID
Identifies the unit of work if the browse is to be restricted to only those enqueues owned and being waited for by a particular UOW.

If omitted then browse will return all enqueue owners and waiters in the system.

STABLE_ENQUEUES
Specifies that the caller will complete the browse without issuing any further ENQ or DEQ requests. Applies only if LOCAL_UOWID is also specified and names the caller's own UOWID.

Output parameters:

BROWSE_TOKEN
Token to be used by the caller on subsequent operations associated with this browse.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER or EXCEPTION. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION NO_UOW_ENVIRONMENT

NQIB gate, GET_NEXT_ENQUEUE function

This functions returns information about the next enqueue owner or waiter in a browse.

Input parameters:

BROWSE_TOKEN
The token for the current browse.

Output parameters:

ENQUEUE_NAME_OUT
A buffer into which the enqueue name is returned. The caller specifies the address and maximum length of the data area into which the enqueue name will be returned. If the enqueue name is too big for the buffer then the data is truncated and an OK response is returned. The actual length of the name is returned in enqueue_name_out_n.
RELATION
Indicates whether the data being returned is associated with owner or a UOW waiting for the enqueue.
OWNER
The data is associated with the owner of the returned enqueue.
WAITER
The data is associated with a waiter of the returned enqueue.
POOL_NAME
The name of the pool containing the enqueue.
STATE
The state that the enqueue is held in.
ACTIVE
The enqueue is held in active state.
RETAINED
The enqueue is held in retained state.
LOCAL_UOWID
The local UOWID of the UOW which owns or is waiting for the enqueue.
UOW_LIFETIME
For an enqueue returned with RELATION(OWNER) the number of times it is held with UOW lifetime.

For an enqueue returned with RELATION(WAITER) a count of one indicates that the enqueue was requested with UOW lifetime.

TRANSACTION_LIFETIME
For an enqueue returned with RELATION(OWNER) the number of times it is held with TRANSACTION lifetime.

For an enqueue returned with RELATION(WAITER) a count of one indicates that the enqueue was requested with TRANSACTION lifetime.

NUM_WAITERS
The number of transactions waiting for this enqueue.
NUM_LOCKED_FAILURES
Returns the number of failed requests for this enqueue whilst it is held in retained state.
SHUNT_ACTION
The action that would be performed to this enqueue should its owning UOW be shunted.

The possible values are as follows:

RELEASE
The enqueue will be released.
RETAIN
The enqueue will be retained.
IGNORE
The shunt will be ignored and the enqueue will remain in the same state.
INTERPRETER_ADDRESS
The address of a routine which should be called with the INTERPRET_ENQUEUE function in order to interpret the enqueue for the EXEC CICS INQUIRE UOWENQ command.

If a zero address is returned then the enqueue isn't to be returned by the INQUIRE UOWENQ command.

POOL_TOKEN
Token which identifies the pool which the enqueue owner or waiter belongs.
ENQUEUE_NAME2_LENGTH
The length of the second part of the enqueue name if the enqueue was originally specified in two parts (i.e. ENQUEUE_NAME1 and ENQUEUE_NAME2).

If the ENQUEUE_NAME2 parameter wasn't originally specified for this enqueue then zero will be returned.

ENQUEUE_TOKEN
Token returned only when the enqueue is owned by the caller. Parameter is set to zero for all other enqueues returned on the browse.
RESOURCE_FILTER
The resource filter as specified in the RESOURCE option on the ENQUIRE UOWENQ command.
RESOURCE_FILTER_LEN
The length of the RESOURCE_FILTER parameter.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
EXCEPTION BROWSE_END
INVALID INVALID_BROWSE_TOKEN

NQIB gate, END_BROWSE_ENQUEUE function

This functions terminates a browse of the enqueues.

Input parameters:

BROWSE_TOKEN
The token for the browse that is to be terminated.

Output parameters:

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
INVALID INVALID_BROWSE_TOKEN

NQRN gate, ENQUEUE function

This function calls INQ_NQRNAME to see if an enqueue name entry exists in NQRNAME_LIST.

If the name is either an exact or generic match, INQUIRE_NQRNAME returns the 4-character SCOPE name, enqmodel STATE and ann OK RESPONSE. Otherwise it returns an EXCEPTION REASON(NQRNAME_NOT_FOUND).

Input parameters:

NQRNAME
A buffer giving a 1 to 255 char name and length of the resource to be located.
MSG0105
YES|NO, indicating whether message DFHNQ0105 is to be issued if the matching enqmodel is disabled or in the waiting state.

Output parameters:

SCOPE
The 4-character scope identifier for the resource. Four blanks indicates that the enqueue has local scope.
STATE
ENABLED
Matching ENQ/DEQ requests should be processed.
DISABLED
Matching ENQ/DEQ requests should be rejected, and the issuing task abended abcode ENQ_DISABLED.
WAITING
Matching ENQ/DEQ requests should be rejected, and the issuing task abended abcode ENQ_DISABLED. There are INSTALL, CREATE, or DISCARD requests waiting to be processed.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, PURGED or INVALID. Possible values are:
NQRNAME_NOT_FOUND
The name does not exist in the table.
ACQUIRE_LOCK_FAILED
Attempt to acquire a shared NQRNAME lock failed.
RELEASE_LOCK_FAILED
Attempt to release a shared NQRNAME lock failed.

NQRN gate, ADD_REPLACE_ENQMODEL function

This function adds an enqmodel definition to both the NQRN directory (keyed by enqmodel name, and to the NQRNAME_LIST (keyed by the variable length NQRNAME).

If the enqmodel already exists the entry is replaced. The replace is a discard then add operation.

If an attempt is made to create a deep enqmodel nesting, or if another enqmodel with the same nqrname is already installed, then msg NQ0106 is issued and a 'DUPLICATE_NQRNAME' exception is returned.

Input parameters:

CALLER
COLDINST, RDOINST or RESTART indicating A cold start, An online install or The input is in the MODEL_TOKEN respectively.
CATALOG
YES or NO indicating whether the record should be cataloged.
ENQMODEL
The 8-character identifier of the resource to be added.
MODEL_TOKEN
The address of the record obtained from the catalogue to be restored.
SCOPE
The 4-character scope identifier for the resource. If ommitted or specified as blanks, matching ENQs will have LOCAL scope.
STATE
ENABLED|DISABLED is the state in which to install the enqmodel. If ommitted, ENABLED is assumed.
NQRNAME
A buffer giving the 1 to 255 character name and length of the ENQ name or stem* to be added.

Output parameters:

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|PURGED
[REASON]
is returned when RESPONSE is DISASTER, EXCEPTION, PURGED or INVALID. Possible values are:
INVALID_PARAMETERS
One of the input parameters is invalid
DUPLICATE_NQRNAME
An attempt has been made to create a deep enqmodel nesting, or another enqmodel with the same nqrname is already installed.
DUPLICATE_ENABLED
An attempt to create an enabled enqmodel failed, because a less specific enqmodel is enabled.
CATALOG_WRITE_FAILED
COMMIT was specified but the record was not written to the catalogue.
GETMAIN_FAILED
The getmain for the NQRN storage failed.
DIRECTORY_ADD_FAILED
The DFHDDDIM ADD_ENTRY failed to add the ENQMODEL entry.
DIRECTORY_DELETE_FAILED
The DFHDDDIM DELETE_ENTRY failed to delete the ENQMODEL entry.
ACQUIRE_LOCK_FAILED
Attempt to acquire an exclusive NQRNAME lock failed.
RELEASE_LOCK_FAILED
Attempt to release an exclusive NQRNAME lock failed.

NQRN gate, DISCARD_ENQMODEL function

Remove an enqmodel definition from both the NQRN directory and from the NQRNAME_LIST.

If the enqmodel is not installed, an 'ENQMODEL_NOT_FOUND' exception is returned.

The ENQMODEL is put into the WAITING state until there are no enqueues in the local system which match the ENQNAME pattern. It is then removed from the local system.

Input parameters:

ENQMODEL
The 8-character identifier of the resource to be DELETED.

Output parameters:

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER
[REASON]
is returned when RESPONSE is DISASTER or EXCEPTION. Possible values are:
ENQMODEL_NOT_FOUND
The name is not in the NQRN directory.
CATALOG_DELETE_FAILED
An attempt to delete the ENQMODEL ENTRY from the GCD failed.
ACQUIRE_LOCK_FAILED
Attempt to acquire an exclusive NQRNAME lock failed.
RELEASE_LOCK_FAILED
Attempt to release an exclusive NQRNAME lock failed.

NQRN gate, INQUIRE_ENQMODEL function

Uses directory DDLO_LOCATE to retrieve information about a specified enqmodel definition in the NQRN directory.

If found, it returns the 1 to 255 character NQRNAME, the 4-character SCOPE name, the enqmodel STATE and ann OK RESPONSE. Otherwise it returns an EXCEPTION REASON(ENQMODEL_NOT_FOUND).

Input parameters:

ENQMODEL
The 8-character identifier of the entry to be returned.

Output parameters:

NQRNAME
A buffer returning the 1 to 255 character name and length of the ENQ name or generic stem*
SCOPE
Returns the 4-character scope identifier for the resource. Four blanks indicates that the enqueue has local scope.
STATE
ENABLED
Matching ENQ/DEQ requests should be processed.
DISABLED
Matching ENQ/DEQ requests should be rejected, and the issuing task abended abcode ENQ_DISABLED.
WAITING
Matching ENQ/DEQ requests should be rejected, and the issuing task abended abcode ENQ_DISABLED. There are INSTALL, CREATE, or DISCARD requests waiting to be processed.
RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER
[REASON]
is returned when RESPONSE is DISASTER or EXCEPTION. Possible values are:
ENQMODEL_NOT_FOUND
The name does not exist in the directory.
DIRECTORY_LOCATE_FAILED
Directory DDLO_LOCATE failed with something other than NOT_FOUND.
ACQUIRE_LOCK_FAILED
Attempt to acquire a shared NQRNAME lock failed.
RELEASE_LOCK_FAILED
Attempt to release a shared NQRNAME lock failed.

NQRN gate, SET_ENQMODEL function

This function uses directory DDLO_LOCATE to see if an enqmodel entry exists in the NQRN directory. If found, it calls SET_ENQMODEL to enable or disable the entry. Otherwise it returns an EXCEPTION REASON(ENQMODEL_NOT_FOUND).

Enqmodels forming nested generic nqrnames must be enabled in order, from the most to the least specific. I.e. A more specific enqmodel may not be enabled if a less specific enqmodel is enabled. If attempted, msg NQ0107 is issued and EXCEPTION 'DUPLICATE_ENABLED' is returned to the caller.

You cannot enable/disable an enqmodel which is in the waiting state. If attempted, EXCEPTION 'ENQMODEL_WAITING' is returned to the caller.

Input parameters:

ENQMODEL
The 8-character identifier of the entry to be enabled/disabled.
STATE
ENABLED
The enqmodel is to be enabled.
DISABLED
The enqmodel is to be disabled.

Output parameters:

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER
[REASON]
is returned when RESPONSE is DISASTER or EXCEPTION. Possible values are:
ENQMODEL_NOT_FOUND
The name does not exist in the directory.
ENQMODEL_WAITING
The enqmodel is in the WAITING state.
DUPLICATE_ENABLED
Attempt to enable/disable an enqmodel failed, because a less specific enqmodel is enabled.
DIRECTORY_LOCATE_FAILED
A DDLO_LOCATE failed with something other than NOT_FOUND.
CATALOG_UPDATE_FAILED
Attempt to update the enqmodel on the global catalog failed.
ACQUIRE_LOCK_FAILED
Attempt to acquire an exclusive NQRNAME lock failed.
RELEASE_LOCK_FAILED
Attempt to release an exclusive NQRNAME lock failed.

NQIE gate, INTERPRET_ENQUEUE function

This function interprets the passed enqueue prior to it being returned by the EXEC CICS INQUIRE UOWENQ command. The function takes the enqueue to be interpreted as input and returns ENQUEUE_TYPE, RESOURCE and QUALIFIER to the caller (EXEC layer).

Each enqueue pool can either

This is specified when the pool is created.

Input parameters:

POOL_NAME
Name of the pool containing the enqueue to be interpreted.

Note that an interpreter may interpret enqueues from more than one pool.

POOL_TOKEN
Token corresponding to the pool containing the enqueue to be interpreted
ENQUEUE_NAME
A block (addr,len) identifying the full name of the enqueue to be interpreted.
ENQUEUE_NAME2_LENGTH
The length of the second part of the enqueue name if the enqueue was originally specified in two parts (i.e. ENQUEUE_NAME1 and ENQUEUE_NAME2).

If the ENQUEUE_NAME2 parameter wasn't originally specified for this enqueue then this will contain zero.

Output parameters:

RESOURCE_BUFFER
A buffer into which the data for the RESOURCE field is returned. The caller specifies the address and maximum length of the data area into which the RESOURCE data will be returned. If the data is too big for the buffer then the data is truncated and an OK response is returned. The actual length of the name is returned in resource_buffer_n.
QUALIFIER_BUFFER
A buffer into which the data for the QUALIFIER field is returned. The caller specifies the address and maximum length of the data area into which the QUALIFIER data will be returned. If the data is too big for the buffer then the data is truncated and an OK response is returned. The actual length of the name is returned in qualifer_buffer_n.

If there is no QUALIFIER data then no data should be returned and the length of the data (qualifier_buffer_n) be returned as zero.

ENQUEUE_TYPE
The TYPE of the enqueue being returned.

The possible values are as follows and these map onto the CVDA values for the TYPE field as detailed under the EXEC CICS INQUIRE UOWENQ command.

RESPONSE
is the domain’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER or INVALID. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LOOP
INVALID INVALID_ENQUEUE
[[ Contents Previous Page | Next Page Index ]]