ISGLOBT — Obtain a latch

The requirements for the caller are:

If you specify an obtain_option of ISGLOBT_ASYNC_ECB (as described in Parameters), initialize the ECB pointed to by the value on the ECB_address parameter to zero before calling Latch_Obtain.

*
* Latch Obtain Option Equate Symbols
*
ISGLOBT_SYNC                  EQU   0
ISGLOBT_COND                  EQU   1
ISGLOBT_ASYNC_ECB             EQU   2
*
*   Latch Obtain Access Equate Symbols
*
ISGLOBT_EXCLUSIVE             EQU   0
ISGLOBT_SHARED                EQU   1
*
*   Latch Obtain Equate Symbols
*
ISGLOBT_SUCCESS               EQU   0
ISGLOBT_CONTENTION            EQU   4
*

1. The caller of Latch_Obtain must have a PSW key that allows access to the latch set storage.
2. The ECB specified on the ECB_address parameter must reside in storage with a storage key that matches the latch set storage key.
3. You must call Latch_Obtain from the same primary address space from which the Latch_Create service was called.

See the information about obtaining latches in z/OS MVS Programming: Authorized Assembler Services Guide for performance implications related to the Latch_Obtain service.

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

All input to callable services is in the form of RX-type addresses.

The parameters are explained as follows:

latch_set_token

Specifies an 8-byte area that contains the latch_set_token that the Latch_Create service returned earlier when it created the latch set.

,latch_number

Specifies a fullword integer that contains the number of the latch to be obtained. The latch_number must be in the range from 0 to the total number of latches in the associated latch set minus one.

,requestor_ID

Specifies an 8-byte area that contains a value that identifies the caller of the Latch_Obtain service. The requestor_ID can be any value except all binary zeros.

Recovery routines can purge all granted and pending requests for a particular requestor (identified by a requestor_id) within a specific latch set. When specifying the requestor_ID on Latch_Obtain, consider which latches would be purged if the Latch_Purge service were to be called with the specified requestor_ID. For more information about the Latch_Purge service, see ISGLPRG — Purge a requestor from a latch set.

,obtain_option

A fullword integer that specifies how the system is to handle the Latch_Obtain request if the latch manager cannot immediately grant ownership of the latch to the requestor:

ISGLOBT_SYNC (value of 0)

The system processes the request synchronously. The system suspends the requestor. When the latch manager eventually grants ownership of the latch to the requestor, the system returns control to the requestor.

ISGLOBT_COND (value of 1)

The system processes the request conditionally. The system returns control to the requestor with a return code of ISGLOBT_CONTENTION (value of 4). The latch manager does not queue the request to obtain the latch.

ISGLOBT_ASYNC_ECB (value of 2)

The system processes the request asynchronously. The system returns control to the requestor with a return code of ISGLOBT_CONTENTION (value of 4). When the latch manager eventually grants ownership of the latch to the requestor, the system posts the ECB pointed to by the value specified on the ECB_address parameter.

When you specify this option, the ECB_address parameter must contain the address of an initialized ECB that is addressable from the home address space (HASN).

,access_option

A fullword or character string that specifies the access required:

• ISGLOBT_EXCLUSIVE (value of 0) - Exclusive (write) access
• ISGLOBT_SHARED (value of 1) - Shared (read) access

,ECB_address

Specifies a fullword that contains the address of an ECB. If you specify an obtain_option of ISGLOBT_SYNC (value of 0) or ISGLOBT_COND (value of 1) on the call to Latch_Obtain, the ECB_address field must be valid (though its contents are ignored). IBM® recommends that an address of 0 be used when no ECB is to be processed.

If you specify an obtain_option of ISGLOBT_ASYNC_ECB (value of 2) and the system returns a return code of ISGLOBT_CONTENTION (value of 4) to the caller, the system posts the ECB pointed to by the value specified on the ECB_address parameter when the latch manager grants ownership of the latch to the requestor.

,latch_token

Specifies an 8-byte area to contain the latch token returned by the Latch_Obtain service. You must provide this value as a parameter on a call to the Latch_Release service to release the latch.

,work_area

Specifies a 256-byte work area that provides temporary storage for the Latch_Obtain service. The work area should begin on a doubleword boundary to optimize performance. The work area must be in the same storage key as the caller of Latch_Obtain.

,return_code

Specifies a fullword integer that is to contain the return code from the Latch_Obtain service.

The caller might encounter abend code X'9C6' for certain errors. See z/OS MVS System Codes for explanations and responses for these codes.

When the Latch_Obtain service returns control to your program, return_code contains a hexadecimal return code. The following table identifies return codes in hexadecimal and decimal (in parentheses), the equate symbol associated with each return code, the meaning of each return code, and a recommended action:

See LATCHX31 - How to call AMODE 31 latch devices for an example of how to call Latch_Obtain in assembler language.