ENQUEUE()

CA-GSS Statements and Commands › GSS Extended Functions › IO Functions › Number, String, and Variable Functions › System Information Functions › ENQUEUE()

ENQUEUE()

Use the ENQUEUE() function to serialize the use of resource names among multiple IMOD tasks.

Syntax

The ENQUEUE() function has this syntax:

ENQUEUE({ENQ|DEQ},,{COND|UNCOND|TEST},{EXCL|CONT|SHR},qname,rname,[shrcount])

Arguments

The ENQUEUE() function takes these arguments:

ENQ	Reserves control of a resource.
DEQ	Releases control of a resource.
COND	Indicates a conditional request. Returns control to the IMOD immediately. You must check the return code to find if you have gained control or if another IMOD's ownership of the resource has prevented it.
UNCOND	Indicates an unconditional request. If the requested resource is not immediately available, your IMOD is placed in a wait state until the resource becomes available. When return is made, you have control of the resource (or an error condition was detected).
TEST	Tests the specified request. Returns control immediately, and the results indicate whether or not the request would have succeeded.
EXCL	Requests an exclusive enqueue. No other users may hold an enqueue of any type for the resource.
CONT	Requests an enqueue for control of the resource. Only one CONT requestor may hold a resource, but multiple SHR users may hold an enqueue simultaneously with the single CONT user.
SHR	Requests a shared enqueue. Any number of requestors may hold a SHR enqueue simultaneously.
qname	1- to 8-character name (case-sensitive), which is used to group requests. Qnames (except as assigned by CA) should not begin with a dollar sign ($).
rname	1- to 256-character name (case-sensitive), which is used to fully define a resource within a qname group. Rnames (except as assigned by CA) should not begin with a dollar sign ($).
shrcount	For shared enqueues, the maximum number of users that can hold the enqueue simultaneously. There is no enforcement of one user's limit on another user. Therefore, all requestors of a specific enqueue should specify the same value for shrcount. Default: 0 (no limit)

Usage Notes

The following indicates what action will be taken for each type of request, based upon the resource's current ownership status.

Request	Current "Owners"	Enqueue Assigned?
SHR	none SHR* CONTROL CONTROL,SHR EXCL	Yes Yes Yes Yes No
CONTROL	none SHR CONTROL CONTROL,SHR EXCL	Yes Yes No No No
EXCL	none SHR CONTROL CONTROL,SHR EXCL	Yes No No No No

* Multiple SHR owners can always be regarded as a single entity.

Resource names are arbitrary. The only protection afforded by ENQUEUE() is management of the names. Just because you assign a name and enqueue on it does not ensure protection of a resource. Any IMOD is free to ignore an enqueue scheme. To be successful, all IMODs must accept and abide by the same naming and access conventions.
When an owned resource is released and IMODs are waiting, ownership is assigned in the following order:
1. The EXCL requestor who has waited longest. This assignment is made only if no other IMOD has ownership.
2. The CONT requestor who has waited longest, along with all waiting SHR requestors. This assignment is made only if no EXCL or CONT requestors already own the resource.
3. All SHR requestors, provided there are no existing EXCL or CONT owners.
When an IMOD task ends, all enqueues assigned to it are automatically released.

Return Codes

The ENQUEUE() function produces these return codes.

0	If ENQ or DEQ and option is TEST: null (indicates request will succeed immediately) REQUEST FOR ALREADY OWNED RESOURCE RESOURCE NOT AVAILABLE RESOURCE NOT OWNED If ENQ and option is NOT TEST: null (indicates resource now owned) If DEQ and option is NOT TEST: null (indicates owned resource successfully released)
101 - 106	ARG n MISSING OR INVALID
122	REQUEST FOR ALREADY OWNED RESOURCE
123	RESOURCE NOT AVAILABLE
124	RESOURCE NOT OWNED
125	ENQUEUE REQUEST CANCELED (Although you requested an unconditional enqueue, your wait was terminated without you being assigned ownership.)

Example

/* Protect a pool of global (&) variables against multiple user
   updates. The qname of GLOBAL and rname of IMSGROUP are
   arbitrary, but are understood by all IMODs that will access 
   the variables in question. */

   x = enqueue('enq',,'uncond','excl','GLOBAL','IMSGROUP')
   if rc ^= 0 then signal error1
   &ims_count = &ims_count + 1

/* Following additional processing, the enqueue will be
   automatically released when the IMOD task ends.  */

Tell Technical Publications how we can improve this information