ENQ

Syntax:

ENQ(qname,rname[,control][,scope][,reqtype])

Arguments:

qname

(also referred to as the "major name") is the 1 to 8 character name that identifies the first level of qualification for the resource you want to process. If you code fewer than 8 characters the name is blank padded on the right out to a length of 8. The qname can be any arbitrary set of characters. The only requirement is that all users of a resource use the same qname (and rname) to represent the same resource.

Note: Certain qnames are reserved for authorized programs only. You should especially avoid using qnames that begin with 'SYS' since some of these are reserved for the control program. SYSDSN, for example, cannot be used because it is reserved by the access methods.

rname

(also referred to as the "minor name") is the 1 to 255 character name that identifies the second level of qualification for the resource you want to process. Note that the rname (unlike the qname) is not blank padded. The rname can be any arbitrary set of characters. The only requirement is that all users of a resource use the same rname (and qname) to represent the same resource.

control

Specifies the type of control you are trying to acquire:

'E'

You want exclusive control of the resource. While your program holds exclusive control, other programs' attempts to gain either exclusive or shared control will fail. This option is usually reserved for occasions when you are planning to modify the resource.

'S'

You want shared control of the resource. While your program holds shared control, other programs' attempts to gain shared control will succeed, but attempts to gain exclusive control will fail.

The default value is 'E'.

scope

indicates scope of control for the resource. The valid values are:

'STEP'

The resource is only used on one address space.

'SYSTEM'

The resource is used on one system.

'SYSTEMS'

The resource is used on several systems. Note that 'SYSTEMS' will only work if global resource serialization (GRS) is active.

The default value is 'STEP'.

reqtype

This argument is used to indicate the type of ENQ request. The valid values are:

'CHNG'

The enqueue is to be "upgraded" to exclusive from shared control.

'HAVE'

The request for acquiring control of a resource is conditional. If the resource is already held by the current task, a return code is issued.

'TEST'

Only the availability of the resource is to be tested. If the resource is held by another user, a return code is issued.

'USE'

The request for acquiring control of a resource is conditional. If the resource is not immediately available, a return code is issued and the current task is not placed in a wait state.

'NONE'

The request for acquiring control of a resource is unconditional. If the resource is already held by the current task, an error occurs.

The default value is 'NONE'.

Module Name:

Service Description:

For most forms of ENQ, the caller will be placed in a wait state until the request can be satisfied. However, if you specify a reqtype of 'USE', control will be returned to your program immediately, regardless of the availability of the resource.

Returned Information:

The following ENQ return code values are possible:

0

reqtype	Meaning
'TEST'	The resource is available.
'USE'	The current task has control of the resource.
'HAVE'	The current task has control of the resource.
'CHNG'	The resource is now held exclusively.

4

reqtype	Meaning
'TEST'	The resource is not available.
'USE'	The resource is not available.
'CHNG'	The resource is not available for exclusive use.

8

reqtype	Meaning
'TEST'	The resource already held.
'USE'	The resource already held.
'HAVE'	The resource already held.
'CHNG'	The resource was not previously held shared.

20

A previous request for the resource has been made and this task does not control the resource.

24

reqtype	Meaning
'USE'	No more concurrent resource requests can be made. Request rejected.
'HAVE'	No more concurrent resource requests can be made. Request rejected.

Other

The abend code in REXX decimal (use the REXX D2X function to convert to hexadecimal).

Note: Abend code X'138' (the resource is already owned by the current task) is ignored and the return code is set to zero.

Examples:

1. Call the ENQ function to gain exclusive control of a data set:

   call enq 'OURDSN', 'USER1.EXEC', 'e', 'system'
   

2. Call the ENQ function to gain shared control of an arbitrary resource:

   call enq 'THEQNAME', 'THERNAME', 's', 'system'