ENQ

Schedules use of a resource by a task (enqueue).

Syntax


ENQ

>>-ENQ--RESOURCE(data-area)--+--------------------+------------->
                             '-LENGTH(data-value)-'   

>--+-----------+-----------------------------------------------><
   '-NOSUSPEND-'

Conditions: ENQBUSY, LENGERR

Description

ENQ causes further execution of the task that is issuing the ENQ command to be synchronized with the availability of the specified resource; control is returned to the task when the resource is available.

A resource in the context of this command is any string of 1 through 255 bytes, established by in-house standards to protect against conflicting actions between tasks.

ENQs are not recoverable. This is demonstrated in the following, where the transaction ONE is used to change the records of a file OMEGA, and the transaction TWO summarizes the file data. For TWO to see consistent data, the activities for each transaction are:

ONE                       TWO
EXEC CICS ENQ OMEGA       EXEC CICS ENQ OMEGA
EXEC CICS WRITE record1   EXEC CICS STARTBR
EXEC CICS WRITE record2   EXEC CICS READNEXT
EXEC CICS WRITE record3   EXEC CICS READNEXT
 ...                       ...
EXEC CICS SYNCPOINT       EXEC CICS ENDBR

The ENQ of OMEGA serializes the access to the file. In the absence of an explicit DEQ, this action occurs at the commit/rollback phase in the SYNCPOINT. If the ONE transaction has been successfully prepared, and a systems failure occurs, the records are again prepared. However, after the system restart, no logged ENQ information is available to draw on, and a fresh ENQ is not obtained. The transaction TWO obtains the ENQ on the original data and starts to do its summary; the READNEXTs will be successful because CICS® allows locked records to be read. If the ONE transaction resolution says ABORT, TWO might have used some of the new values that are about to be erased, giving an incorrect summary.

The ENQBUSY condition allows a conditional ENQ to be used. If a resource is not available when enqueued, the ENQBUSY condition occurs.

For COBOL programs only, the execution of a HANDLE CONDITION ENQBUSY command returns control to the task at the ENQBUSY label, without waiting for the resource to become available.

If a task enqueues on a resource but does not dequeue from it, CICS automatically releases the resource during syncpoint processing or when the task is terminated.

The resource that is to be enqueued on must be identified by one of the following methods:

Specifying a data area that is the resource. It is the location (address) of the data area in storage that is important, not its contents. Two tasks, enqueuing on the same resource and using this method, must refer to the same location in storage. They could both, for example, refer to the same location in the Common Work Area (CWA).
```
EXEC CICS ENQ
          RESOURCE(RESNAME)
```
Specifying a data area that contains a unique character string argument (for example, an employee name) that represents the resource. It is the contents of the data area that is important, not its location. Two tasks, enqueuing on the same resource and using this method, can refer to the same location or different locations, but the contents of the locations must be the same. The length must be supplied in the LENGTH option and can be up to 255 bytes long.
```
EXEC CICS ENQ
          RESOURCE(SOCSECNO)
          LENGTH(8)
```

Options

LENGTH(data-value): Specifies, as a 16-bit binary value, the length in bytes of the resource that is to be enqueued on. The value should be in the range 1 through 255; otherwise, the LENGERR condition occurs. If the LENGTH option is specified in an ENQ command, it must also be specified in the DEQ command for that resource, and the values of these options must be the same. You must specify LENGTH only when using the method that specifies a data area containing a unique argument that represents the resource that is to be enqueued on. It is the presence or absence of LENGTH that tells CICS which method you are using. For more information about using this option, see LENGTH.
NOSUSPEND: Specifies that the application program is not to be suspended if the ENQBUSY condition occurs.
RESOURCE(data-area): Identifies the resource that is to be enqueued on, by specifying either a data area whose address represents the resource or a data area containing a unique character string that represents the resource (for example, an employee name). For the second method only, you must use the LENGTH option.

Conditions

ENQBUSY: Occurs if an ENQ command specifies a resource that is not available.
Default action: Wait for the resource to become available. (This default action can be overridden by the NOSUSPEND option.)
LENGERR: Occurs if the LENGTH value is out of range.
Default action: Terminates the task abnormally.