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
- ENQSCOPE
- Optional Parameter
- For sysplex scope enqueues, the 4-character scope name that qualifies all ENQUEUE requests issued by this CICS region.
- ENQUEUE_NAME1
- Optional Parameter
- The first part of a two-part enqueue name.
- LOCAL_UOWID
- Optional Parameter
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
- Optional Parameter
- 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
- REASON
- The values for the parameter are:
- NO_UOW_ENVIRONMENT
- BROWSE_TOKEN
- Token to be used by the caller on subsequent operations associated with this browse.
- RESPONSE
- Indicates whether the domain call was successful. For more information, see RESPONSE parameter on domain interfaces.