GENDTL (Generate the DTL Block) Macro

The macro generates a control block, which is used by the LOCK/UNLOCK macros to enqueue/dequeue a resource access request.

The control block, commonly called 'DTL' (Define The Lock), is generated at the time of program execution. Space for the DTL is either provided by the program, or it is to be acquired by the system.

Format

Read syntax diagramSkip visual syntax diagramnameGENDTLADDR=name1(S, name1)( r1),CONTROL=E,CONTROL=S,KEEP=NO,KEEP=YES,LENGTH=NO,LENGTH=YES,LOCKOPT=1,LOCKOPT=24,NAME=name2(S, name2)( r2),OWNER=TASK,OWNER=PARTITION,SCOPE=INT,SCOPE=EXT,VOLID=name3(S, name3)( r3)

Requirements for the caller

AMODE:
24 or 31
RMODE:
24
ASC Mode:
Primary

Parameters

ADDR=name1 | (S,name1) | (r1)
Specifies the address of the area where the DTL is to be built. If this operand is omitted, storage is allocated in the partition 's GETVIS area by an implicit GETVIS request. After a successful GETVIS, the system places the DTL 's address in register 1. Register 15 contains the return code set by the implicit GETVIS request.
CONTROL=E | S
Defines how the named resource can be shared while your program owns it, which is determined by this specification and your specification for the operand LOCKOPT. A specification of E means that the resource is enqueued for exclusive use; a specification of S means that the resource is enqueued as shareable.
KEEP=NO | YES
This operand can be used to lock the named resource beyond job step boundaries. Only a main task should use this operand. KEEP=NO indicates that the named resource once locked, is to be released automatically at the end of the particular job step. With KEEP=YES, a named resource that is locked remains locked across job steps; it is automatically released at end of job.

If a job terminates abnormally, all resources with KEEP=YES are unlocked by the end-of-task (termination) routine.

LENGTH=NO | YES
If LENGTH=YES is specified, the GENDTL macro returns the length of the DTL in register 0. With LENGTH=NO, register 0 remains unchanged.
LOCKOPT=1 | 2 | 4
Together with the CONTROL operand, this operand determines how the system controls shared access in response to a LOCK request:
LOCKOPT=1 and CONTROL=E
No other task is allowed to use the resource concurrently.
LOCKOPT=1 and CONTROL=S
Other 'S' users are allowed concurrent access, but no concurrent 'E' user is allowed.
LOCKOPT=2 and CONTROL=E
No other 'E' user gets concurrent access; however, other 'S' users can have access to the resource.
LOCKOPT=2 and CONTROL=S
Other 'S' users can have concurrent access and, in addition, one 'E' user is allowed.
LOCKOPT=4 and CONTROL=E
No 'E' user from another system is allowed concurrent access. An 'S' user from another system can use the resource concurrently. Within your own system, you always have access to the resource.
LOCKOPT=4 and CONTROL=S
'S' users can have concurrent access and, in addition, one 'E' user from another system is allowed.
Note: If the DASDSHR support is not generated in the supervisor, the LOCK request for the resource is always granted.

All users of a particular resource must use the same LOCKOPT specification when they lock the resource. Exception: if LOCKOPT=1 and CONTROL=E, the lock status can be modified.

NAME=name2 | (S,name2) | (r2)
Specifies the address of the area where a 12-byte long resource name is stored. If the name is shorter than 12 bytes, it must be padded with blanks. It is by this name that z/VSE controls shared access of the resource as requested by active tasks via the LOCK macro. These tasks can all be active in one partition, or they can be distributed over several partitions; the resource-share control extends across partitions.

The name must not begin with any of the characters A through I or V because these characters are reserved for IBM® usage.

OWNER=TASK | PARTITION
Defines whether the named resource, once locked, can be unlocked only by the task, which issued the corresponding LOCK request (OWNER=TASK), or whether it can be unlocked by any task within the partition (OWNER=PARTITION).

When OWNER is defined as PARTITION, a LOCK request for the resource must not specify FAIL=WAIT, FAIL=WAITC, or FAIL=WAITECB, because deadlock prevention (return code 16) is not supported by OWNER=PARTITION.

SCOPE=INT | EXT
This operand can be used for locking resources across systems. SCOPE=EXT specifies that the lock is used across systems. You can omit the operand if you want to lock your resources only on one system since the default is SCOPE=INT (that is, the locking applies to one system only).
VOLID=name3 | (S,name3) | (r3)
Specifies the address of a 6-byte identifier of a DASD volume which (at the time of the LOCK request) is to be checked whether it is mounted on an I/O device that is defined as being shared across systems. If the device is a shared DASD, the LOCK request is treated as being defined with SCOPE=EXT (that is, the SCOPE operand is ignored); otherwise, SCOPE=INT is assumed.