ENQ

Standard Format

See also List Format and Execute Format.

Notes:

• ¹ The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.

Purpose

Use the ENQ macro to request control of a serially reusable resource.

A serially reusable resource (SRR) is a data resource, local to a virtual machine, that some tasks may want to update and that others may want merely to examine. Use of these SRRs should be coordinated carefully. Two programs may seek to update the resource simultaneously, leading to incorrect results. Meanwhile, another program may be looking at the same data, causing more confusion.

Use the ENQ macro to request control of a serially reusable resource and to define the control sought by your task.

Parameters

qname_address

Specifies the address in virtual storage where the QNAME for the resource in question can be found.

The QNAME is the first of a pair of names that identifies the resource, and must be eight characters long. Your installation has defined the QNAMEs of each serially reusable resource available to you. Each programmer is required to use the proper QNAME to identify an SRR.

You can write this parameter as an assembler program label or as register (2) through (12).

rname_address

Specifies the address in virtual storage where the RNAME of the resource can be found.

The RNAME is the second of a pair of names that identifies the resource. Again, your installation has defined these and they must be used consistently. The name can be qualified and be from 1 to 255 characters long.

You can write this parameter as an assembler program label or as register (2) through (12).

E

Indicates that you want your task to have exclusive control over the serially reusable resource. That is, while your task has control over the resource, no other task can use it.

You must request exclusive control if your task is to modify the serially reusable resource in any way.

S

Indicates that your task can share control of the resource with other tasks that are also willing to share.

If two or more tasks are sharing a serially reusable resource, then none is permitted to change the contents of that resource.

rname_length

Specifies the length of the RNAME, in bytes.

If you omit this parameter, then the RNAME is considered by default to be the assembled length. If you wish, you may override its assembled length with another within the range 1 through 255. If you specify 0 as the length, then the ENQ macro assumes that the first byte at the address specified for the RNAME ADDRESS contains the RNAME's correct length.

You must specify this parameter if there is no length associated with the RNAME itself. For example, you may specify the RNAME by using a register or by using a name appearing in an EQU assembler instruction to specify the RNAME.

You can write this parameter as a number from 0 to 255.

RET

Indicates the condition under which your request for control of the resource will be honored. If you omit this parameter, then the request is considered unconditional.

TEST

Tests the availability of the resource specified. It does not turn control of the resource over to your task.

CHNG

Indicates that the shared control your task now has over the resource is to change to exclusive control.

This request will be honored if no other tasks are sharing the same resource with your task.

HAVE

Indicates that your task wants control of the resource only if it has not requested control of it before.

NONE

Indicates that your task requests control of the resource unconditionally.

Your task will not regain control until it obtains control of the resource.

USE

Indicates that your task wants immediate control over the resource. If control of the resource is not immediately available, then your task foregoes control and does not wait.

RELATED

Specifies documentation data that you are using to relate this macro to a DEQ macro.

The value you assign to this parameter has nothing to do with the execution of the macro itself. It merely relates one macro (ENQ) to a macro that provides an opposite, though related, service (DEQ).

The format and content of this parameter are at your discretion and may be any valid coding values.

Usage

1. Control of a resource is surrendered under when:
   • A program within the task with control issues the DEQ macro. Review the entry titled DEQ.
   • The task with control ends. The task terminates abnormally, because it did not release the resource itself.
2. After it issues the ENQ macro, your task may be placed in the WAIT state when requesting:
   • Exclusive unconditional control of a resource that is under exclusive or shared control of another task.
   • Control of a resource that is under the exclusive control of another task.
   • Shared control but there is a request for exclusive control ahead of it.
3. The ENQ macro affects only the tasks within the virtual machine which issued it. Tasks in other virtual machines are not constrained from using the serially reusable resource to which the instruction refers. The programmers involved should take steps to assure that this does not create problems.
4. If you choose the TEST parameter, then your task is not given control of the task but merely receives a return code. The same may be true if you choose the HAVE or USE parameter. Return codes are defined in Return Codes and ABEND Codes.

Return Codes and ABEND Codes

A return code is passed to your task only if you choose the TEST, USE, CHNG, or HAVE conditions for the RET parameter.

If register 15 contains 0, then the return code for the resource in question is 0. If register 15 does not contain 0, then it contains the address of the input parameter list of the macro. The ENQ macro places all nonzero return codes in byte-3 of the input parameter list.

For all 08 return codes (except when RET=CHNG), you must examine the fourth bit in byte-0 of the input parameter list. If this bit is reset to 0, then the return code means that the task has obtained exclusive control of the resource. If this bit is set to 1, then the return code means that the task has obtained shared control.

The return codes and abend codes are described as follows, according to the condition specified in the RET parameter. When RET=CHNG:

When RET=HAVE:

When RET=TEST:

When RET=USE:

List Format

Notes:

• ¹ The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.

Purpose (List Format)

This format of the macro generates an in-line parameter list based on the parameter values that you specify. However, this format generates no executable code. Remember that you cannot specify any of the parameters using register notation.

Added Parameter

MF=L

Specifies the list format of this macro.

Execute Format

Notes:

• ¹ The following parameters are optional and may be specified in any order. For any parameter not specified, the default value, if applicable, is used.

Purpose (Execute Format)

This format of the macro generates code that executes the function, using a parameter list whose address you specify.

Added Parameter (Execute Format)

MF=(E,address)

address specifies the address of the parameter list to be used by the macro.

You can add or modify values in this parameter list by specifying them in this macro.