ENQ

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

  or

  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.