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

ENQUEUE()

This function serializes 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])

Parameters

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. Check the return code to find if you have gained control or if the ownership of another IMOD 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 the request would have succeeded.

EXCL

Requests an exclusive enqueue. No other users can hold an enqueue of any type for the resource.

CONT

Requests an enqueue for control of the resource. Only one CONT requestor can hold a resource, but multiple SHR users can hold an enqueue simultaneously with the single CONT user.

SHR

Requests a shared enqueue. Any number of requestors can hold an SHR enqueue simultaneously.

qname

A one to eight character name (case-sensitive), which is used to group requests. Do not begin qnames (except as assigned by CA) with a dollar sign ($).

rname

A 1 through 256 character name (case-sensitive), which is used to define fully a resource within a qname group. Do not begin Rnames (except as assigned by CA) with a dollar sign ($).

shrcount

For shared enqueues, the maximum number of users that can hold the enqueue simultaneously. The limit for one user is not enforced on another user. Therefore, all requestors of a specific enqueue specify the same value for shrcount.

Default: 0 (no limit)

Usage Notes

• The action that is taken for each type of request, which is based on the current ownership status for the resource.

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

• Resource names are arbitrary. The only afforded protection 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, with all waiting SHR requestors. This assignment is made only if no EXCL or CONT requestors 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 succeeds 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.  */