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
|
|
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:
- DEQUEUE
- Enqueue_not_owned
- Enqueue_locked
- REACQUIRE_ENQUEUE
- Enqueue_locked
- Enqueue_active
- DEACTIVATE
- Enqueue_not_owned
- Enqueue_not_active
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.
- DATASET
- EXECENQ
- EXECENQADDR
- EXECENQPLEX
- FILE
- TDQUEUE
- TSQUEUE
- DISPATCHER
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
|
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
|
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
|
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.
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
|
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
|
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 |
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 |
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 |
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 |
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.
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.
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.
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.
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.
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
- not have an interpreter and consequently not have its enqueues
returned by the INQUIRE UOWENQ command
- rely upon a default interpreter supplied by NQ domain, (DFHNQIE)
- supply its own interpreter routine.
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.
- DATASET
- EXECENQ
- EXECENQADDR
- FILE
- TDQUEUE
- TSQUEUE
- 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 ]]