ISGLCRT — Create a latch set

Call the Latch_Create service to create a set of latches. Your application should call Latch_Create during application initialization, and specify a number of latches that is sufficient to serialize all the resources that the application requires. Programs that run as part of the application can call the following related services:

ISGLOBT: Requests exclusive or shared ownership of a latch.
ISGLREL: Releases ownership of an owned latch or a pending request to obtain a latch.
ISGLPRG: Purges all granted and pending requests for a particular requestor within a specific latch set.

In the following description of Latch_Create, constants defined in the latch manager IDFs are followed by their numeric equivalents; you may specify either when coding calls to Latch_Create.

Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.

Assign values to the following parameters:

number_of_latches
latch_set_name
create_option

Latch_Create returns values in the following parameters:

latch_set_token
return_code

CALL statement	Parameters
CALL ISGLCRT	(number_of_latches ,latch_set_name ,create_option ,latch_set_token ,return_code)

The parameters are explained as follows:

number_of_latches

Specifies a fullword integer that indicates the number of latches to be created.

,latch_set_name

Specifies a 48-byte area that contains the name of the latch set. The latch set name must be unique within the current address space. The latch set name can be any value up to 48 characters, but the first character must not be binary zeros or an EBCDIC blank. If the latch set name is less than 48 characters, it must be padded on the right with blanks.

IBM® recommends that you use a standard naming convention for the latch set name. To avoid using a name that IBM uses, do not begin the latch set name with the character string SYS. It is a good idea to select a latch set name that is readable in output from the DISPLAY GRS command and interactive problem control system (IPCS). Avoid '@', '$', and '#' because those characters do not always display consistently.

,create_option

Specifies a fullword integer that must have one of the following values:

ISGLCRT_PRIVATE (or a value of 0)
ISGLCRT_PRIVATE + ISGLCRT_LOWSTGUSAGE (or a value of 2)
ISGLCRT_PRIVATE + ISGLCRT_DEADLOCKDET1 (or a value of 64)
ISGLCRT_PRIVATE + ISGLCRT_DEADLOCKDET2 (or a value of 128)
ISGLCRT_PRIVATE + ISGLCRT_DEADLOCKDET1 + ISGLCRT_LOWSTGUSAGE (or a value of 66)
ISGLCRT_PRIVATE + ISGLCRT_DEADLOCKDET2 + ISGLCRT_LOWSTGUSAGE (or a value of 130)

If the creating address space is constrained by private storage, use the ISGLCRT_LOWSTGUSAGE option. ISGLCRT_LOWSTGUSAGE reduces storage usage at the cost of performance. IBM suggests that this option is only used if there is a known or possible storage constraint issue. See "Specifying the Number of Latches in a Latch Set" in z/OS MVS Programming: Authorized Assembler Services Guide for a description of the amount of storage that can be consumed by a latch set.

If you want to have the latch obtain services detect some simple latch deadlock situations, consider using the ISGLCRT_DEADLOCKDET1 and ISGLCRT_DEADLOCKDET2 options. For performance reasons, latch deadlock detection is not exhaustive. It can detect some simple deadlock situations.

When ISGLCRT_PRIVATE + ISGLCRT_DEADLOCKDET1 is specified, it can detect the following deadlock situations:

The work unit requests exclusive ownership of a latch that the work unit already owns exclusively.
The work unit requests shared ownership of a latch that the work unit already owns exclusively.

When ISGLCRT_PRIVATE + ISGLCRT_DEADLOCKDET2 is specified, it can detect all the deadlock situations listed under ISGLCRT_PRIVATE + ISGLCRT_DEADLOCKDET1, and it can also detect if the work unit holding a SHARED latch requests exclusive use of the same latch.

Because ISGLCRT_DEADLOCKDET2 provides the best deadlock detection, IBM suggests that you use ISGLCRT_DEADLOCKDET1 in cases where it can be used and use ISGLCRT_DEADLOCKDET2 in all cases where there are not many SHARED latch holders.

Note:

The unit of work context of the requester is captured at latch obtain time. The system does not know if the application passes responsibility for releasing the latch to another unit of work. To prevent false detection, deadlock detection can not be used if latches are used in such a way that responsibility for releasing the latch is passed between the obtainer and the releaser.
Deadlock detection can be safely used by SRBs, if all the obtained latches are released by the SRB work unit before the unit of work completes. There is a possibility of false deadlock hits otherwise.
Deadlock detection is not performed if the latches are obtained conditionally using the ISGLOBT_ASYNC_ECB option in ISGLOBT.

,latch_set_token

Specifies an 8-byte area to contain the latch set token returned by the Latch_Create service. The latch set token uniquely identifies the latch set. Programs must specify this value on calls to the Latch_Obtain, Latch_Release, and Latch_Purge services.

,return_code

A fullword integer to contain the return code from the Latch_Create service.