ENQ
Schedule use of a resource by a task (enqueue).
Description
ENQ causes further execution of the task 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–255 bytes, established by in-house standards, to protect against conflicting actions between tasks, or to cause single threading within a program.
If a task enqueues on a resource but does not dequeue from it, CICS® automatically releases the resource during syncpoint processing (including DL/I, PCB, and TERM calls), or when the task is terminated. Option UOW forces the dequeue at the end of a unit of work (UOW). Option TASK forces the dequeue at the end of a task. If there are several units of work in a task, the enqueue carries over the UOWs.
If more than one ENQ command is issued for the same resource by a given task, the resource remains owned by that task until the task issues a matching number of DEQ commands.
The resource 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 matters, not its contents.
- Specifying a data area that contains a unique argument (for example, an employee name) that represents the resource. It is the contents of the data value that matters, not its location. LENGTH is required; the presence of the LENGTH option tells CICS to enqueue on the contents of the data value.
When an EXEC CICS ENQ (or DEQ) command is issued for a resource whose name matches that of an installed ENQMODEL resource definition, CICS checks the value of the ENQSCOPE attribute to determine whether the scope is local or sysplex-wide. If the ENQSCOPE is non-blank, CICS treats the ENQ or DEQ as sysplex-wide, and passes a queue name and the resource name to z/OS® global resource serialization to manage the enqueue. If the ENQSCOPE attribute is left blank (the default value), CICS treats the ENQ as local to the issuing CICS region. If no ENQMODEL matches the resource name, the scope of the ENQ command is local. For more information on ENQMODEL resources, see ENQMODEL resources.
Resource unavailability
If a resource is not available when ENQ is issued, the application program is suspended until it becomes available. However, if the NOSUSPEND option has been specified and the resource is unavailable, the ENQBUSY condition is raised, as it is also raised if you have an active HANDLE condition. This allows the application program to handle the case of resource unavailability (by HANDLE CONDITION ENQBUSY) without waiting for the resource to become available.
Options
- LENGTH(data-value)
- specifies as a halfword binary value the length of the resource to be enqueued on. The value must 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 when using the method that specifies a data value containing a unique argument, but not for the method that specifies a data area as the resource. It is the presence or absence of LENGTH that tells CICS which method you are using.
- MAXLIFETIME(cvda)
- specifies
the duration of the ENQ to be automatically released by CICS. CVDA values are:
- UOW
- The
duration of the ENQ is a unit of work. Examples are a syncpoint rollback
or syncpoint, if the application does not issue a DEQ before the unit
of work ends. This is the default value. Note: For compatibility, a CVDA value of LUW is also supported.
- TASK
- The duration of the ENQ is a task. The enqueue carries over the units of work within the task. Use MAXLIFETIME(TASK) with great care because other tasks issuing ENQ commands on the same resource could be suspended until the end of this task.
There are two ways to code this option.- You can assign a CVDA value with the translator routine DFHVALUE.
This allows you to change a CVDA value in the program. For example:
MOVE DFHVALUE(UOW) TO AREA-A EXEC CICS ENQ RESOURCE(RESNAME) MAXLIFETIME(AREA-A)
- If the required action is always the same, you can declare the
value directly. For example:
EXEC CICS ENQ RESOURCE(RESNAME) UOW
EXEC CICS ENQ RESOURCE(RESNAME) TASK
- NOSUSPEND
- specifies
that the application program is not to be suspended if the resource
on the ENQ command is unavailable, but the ENQBUSY condition occurs.
Note, however, that if a HANDLE CONDITION for ENQBUSY is active when the command is executed, action, control is passed to the user label supplied in the HANDLE CONDITION. This takes precedence over the NOSUSPEND option but is, of course, negated by either NOHANDLE or RESP.
- RESOURCE(data-area)
- identifies
the resource to be enqueued on by:
- Specifying an area whose address represents the resource.
- Specifying a variable that contains the resource (an employee name, for example). In this case, you must use the LENGTH option.
Conditions
- 55 ENQBUSY
- occurs
when an ENQ command specifies a resource that is unavailable and the
NOSUSPEND option is specified, or there is an active HANDLE CONDITION
ENQBUSY.
If the NOSUSPEND option is not specified, and the ENQ command specifies a resource that is unavailable, the application program is suspended and the ENQBUSY condition is not raised.
Default action: ignore the condition.
- 16 INVREQ
- RESP2
values: CVDA values are:
- 2
- The MAXLIFETIME option is set with an incorrect CVDA.
Default action: terminate the task abnormally.
- 22 LENGERR
- RESP2
values:
- 1
- The value specified for the LENGTH option is outside the range 1 through 255.
Default action: terminate the task abnormally.
Examples
EXEC CICS ENQ
RESOURCE(RESNAME)
EXEC CICS ENQ
RESOURCE(SOCSECNO)
LENGTH(9)
The two methods cannot be combined. If one task uses the LENGTH option, and the other task does not, CICS regards the enqueues with and without the LENGTH option as different types of enqueues, and the tasks are not serialized.