LOCK (Lock a Resource) Macro
The macro queues the task for accessing the named resource.
Format
Requirements for the caller
- AMODE:
- 24 or 31
- RMODE:
- 24 or ANY
- ASC Mode:
- Primary
Parameters
- name | (S,name) | (r)
- Specifies the DTL address.
- FAIL=RETURN | WAITC | WAIT | WAITECB
- Defines the system action in case the resource cannot be obtained:
- FAIL=RETURN
- Causes the system to return control back to the requesting program in any case. The requesting program must check the return code in register 15 to find out whether the request was successful.
- FAIL=WAITC
- Causes the system to place the requesting task in the wait state if the requested resource is found to be locked by another task. In all other cases, control returns to the requesting program. The requesting program must check the return code in register 15 to find out whether the request was successful, or whether an error occurred.
- FAIL=WAIT
- Requests the system to return control to the requesting task when the resource can be obtained. If the resource is locked by another task, the requesting task is set into the wait state until the resource is freed. In case of an error condition with a return code of 12 or higher, the requesting task is canceled.
- FAIL=WAITECB
- Causes the system to place the requesting task in the request queue if the requested resource is found to be locked by another task. In all cases, control returns to the requesting program. The requesting program must check the return code in register 15 to find out whether the request was successful, or whether an error occurred, or whether the task 's request is put in the request queue (return code = 4). If the request was put in the request queue, the requesting task should issue a WAIT macro on this ECB.
WAIT, WAITC or WAITECB cannot be specified, if the resource is defined with OWNER=PARTITION.
Table 1 summarizes how the system controls access to a resource, depending on the specification of the CONTROL and LOCKOPT operands in the DTL (Define the Lock) Macro or GENDTL (Generate the DTL Block) Macro macro. The illustration assumes that a task issues a LOCK request for a resource, which is already locked.
| Incoming LOCK Request | Current Lock Status of Resource | |||||
|---|---|---|---|---|---|---|
| LOCKOPT=1 | LOCKOPT=2 | LOCKOPT=4 | ||||
| CONTROL= | CONTROL= | CONTROL= | ||||
| E | S | E | S | E | S | |
| LOCKOPT=1 CONTROL=E | W | W | W | W | W | W |
| CONTROL=S | W | G | I | I | I | I |
| LOCKOPT=2 CONTROL=E | W | I | W | G | I | I |
| CONTROL=S | W | I | G | G | I | I |
| LOCKOPT=4 CONTROL=E | W | I | I | I | G/W | G |
| CONTROL=S | W | I | I | I | G | G |
- Abbreviations
- E =
- Exclusive.
- S =
- Shared.
- G =
- Access is granted (return code 0).
- I =
- Access is not granted. The incoming LOCK request is inconsistent with the current LOCK status (return code 12).
- W =
- Access to the resource cannot be granted (return code 4 or 16).
- G/W =
- Access is granted if the resource is already exclusively owned by the requesting system. Access is denied (return code 4) if the resource is exclusively held by the other system.
A task or partition can lock a resource more than once. The system maintains a lock request count for the resource.
When a resource is defined with LOCKOPT=1, a task can issue up to 255 LOCK requests with CONTROL=S. When a resource is defined with LOCKOPT=2, up to 255 LOCK requests with CONTROL=S and (if no other task locks the resource exclusively) one LOCK request with CONTROL=E are allowed.
When a resource is locked more than once by a task, this task must issue at least as many UNLOCK requests as it issued LOCK requests before it gives up the resource completely. If the resource is defined with OWNER=PARTITION, the unlocking can be done by any task in the partition.
Return Codes in Register 15
Table 2 gives a summary of system actions by return codes, depending on the specification of the FAIL operand. A list of possible return codes together with a summary of their meanings follows Table 2. If FAIL=WAITECB is specified, the return code is also presented in byte 1 of the ECB.
| Return Code | System Action if | ||||
|---|---|---|---|---|---|
| HEX | Dec. | FAIL=RETURN | FAIL=WAITC | FAIL=WAIT | FAIL=WAITCB |
| 00 | 0 | Return | Return | Return | Return |
| 04 | 4 | Return | Wait | Wait | Queue + Return |
| 08 | 8 | Return | Return | Wait | Return |
| 0C | 12 | Return | Return | Cancel | Return |
| 10 | 16 | Return | Return | Cancel | Return |
| 14 | 20 | Return | Return | Cancel | Return |
| 18 | 24 | Return | Return | Cancel | Return |
| 1C | 28 | Return | Return | Wait | Return |
| 20 | 32 | Return | Return | Cancel | Return |
| 24 | 36 | Return | Return | Cancel | Return |
- Return Code
- 0
- Successful request: the resource is locked for the task (or for the partition if the resource is defined with partition ownership).
- 4
- Resource not available: the resource is already locked with a locking status that allows no concurrent access.
- 8
- The lock table space is exhausted.
- 12
- The lock request is inconsistent with previous lock requests (by the same or other tasks).
- 16
- The request would have resulted in a deadlock condition within the system (deadlocks across systems are not affected).
- 20
- DTL format error.
- 24
- The issuing task tried to lock a resource, which it owns already exclusively. The locking status must not be the same as the one specified in the DTL macro with the CONTROL and LOCKOPT options.
- 28
- The lock request resulted in a lock file overflow condition. Use the DLF command to specify a larger size for the lock file.
- 32
- A lock request was issued for a shared DASD file, but the corresponding volume is not online.
- 36
- An unrecoverable I/O error occurred on the lock file. This probably means that the system must be restarted and the lock file redefined. This must be done on all sharing systems.