In the following description of 64-bit Latch_Create, equate symbols defined in the ISGLMASM macro are followed by their numeric equivalents; you may specify either when coding calls to Latch_Create.
The requirements for the caller are:
| Environmental factor | Requirement |
|---|---|
| Minimum authorization: | Supervisor state or PSW allowing key 0-7 |
| Dispatchable unit mode: | Task or SRB |
| Cross memory mode: | Any PASN, any HASN, any SASN |
| AMODE: | 64-bit |
| ASC mode: | Primary |
| Interrupt status: | Enabled for I/O and external interrupts |
| Locks: | No locks held |
| Control parameters: | Control parameters must be accessible from the primary address space. |
* Latch Create Option Equate Symbols
*
ISGLCRT_PRIVATE EQU 0
*
* Latch Create Return Codes
*
ISGLCRT_SUCCESS EQU 0
ISGLCRT_DUPLICATE_NAME EQU 4
ISGLCRT_NO_STORAGE EQU 16
*You cannot create a latch set in the master scheduler address space if the master scheduler address space is not also the home address space.
None.
Write the call as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.
| Syntax | Description |
|---|---|
CALL ISGLCR64 |
|
All input to callable services is in the form of RX-type addresses.
The parameters are explained as follows:
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.
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_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. It also catches multiple Share requests by same unit of work when there is exclusive Waiter in between -> Shared (UW1) - Exclusive (UW2) - Shared (UW1).
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.
The caller might encounter abend code X'9C6' for certain errors. See z/OS MVS System Codes for explanations and responses.
When the Latch_Create 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:
| Return code and Equate symbol | Meaning and Action |
|---|---|
00 |
Meaning: The Latch_Create service completed
successfully. Action: None required. |
04 |
Meaning: The specified latch_set_name already
exists, and is associated with a latch set that was created by a program
running in the current primary address space. The latch manager does
not create a new latch set. Action: To create a new latch set, specify a unique name on the latch_set_name parameter, then call the Latch_Create service again. Otherwise, continue processing with the returned latch set token. |
10 |
Meaning: Environmental error. Not enough
storage was available to contain the requested number of latches.
The latch manager does not create a new latch set. Action: Specify a smaller value on the number_of_latches parameter. |
TITLE 'LATCHX64 - How to call AMODE 64 Latch Services'
*** START OF SPECIFICATIONS *******************************************
*
*01* MODULE-NAME = LATCHX64
*
*02* DESCRIPTIVE-NAME = SAMPLE PROGRAM WHICH CONTAINS CALLS
* TO EACH LATCH SERVICE.
*
*01*PROPRIETARY STATEMENT =
*
* LICENSED MATERIALS - PROPERTY OF IBM
* THIS MACRO IS "RESTRICTED MATERIALS OF IBM"
*
*01*STATUS = HBB7760
*
*01* FUNCTION:
*
* This module provides samples of how to call the following AMODE 64
* services: ISGLCR64 (Latch Create), ISGLID64 (Latch Id), ISGLOB64
* (Latch Obtain), ISGLRE64 (Latch Release), ISGLPR64 (Latch Purge),
* and ISGLPB64 (Latch Purge By Address Space).
*
***********************************************************************
*
*02* RECOVERY-OPERATIONS: None.
*
***********************************************************************
*
*01* NOTES =
*
* (1) Also shows sample of how to allocate an ISGYLID_ENTRY block
* to change the Latch ID field of a latch in the latchset.
*
*02* DEPENDENCIES: None
*
*
*02* RESTRICTIONS: None
*
*
*02* REGISTER-CONVENTIONS:
*
*03* REGISTERS SAVED: R0-R15
*
*03* REGISTERS RESTORED: R2-R14
*
*03* CODE REGISTER: R12
*
*03* DATA REGISTER: R13
*
*02* PATCH-LABEL: None
*
*01* MODULE-TYPE: Procedure
*
*02* PROCESSOR: HLASM
*
*02* MODULE-SIZE: See External Symbol Dictionary
*
*02* ATTRIBUTES:
*
*03* LOCATION: User specified
*03* LOAD MODULE: LATCHX64
*03* TYPE: Non-Reentrant
*03* RMODE: Any
*03* SYSGEN: None
*
***********************************************************************
*
*01* ENTRY-POINT: LATCHX64
*
*02* PURPOSE: See FUNCTION section for this module.
*
*03* OPERATION: See FUNCTION section for this module.
*
*03* ENTRY
*
*04* MODE: Enabled
*04* STATE: Problem
*04* KEY: 8
*04* AMODE: 64
*04* LOCKS HELD: None
*04* ASCMODE: Primary
*04* MEMORY MODE: Non-XMEM
*04* DISPATCH MODE: Task
*04* RECOVERY TYPE: None
*04* ADDRESS SPACE: Caller's
*
*03* EXECUTION
*
*04* MODE: Enabled
*04* STATE: Supervisor
*04* KEY: 0
*04* AMODE: 64
*04* LOCKS OBTAINED: None
*04* ASCMODE: Primary
*04* MEMORY MODE: Non-XMEM
*04* ADDRESS SPACE: Caller's
*
*02* LINKAGE: Branched to.
*
*03* CALLERS:
*
* Any
*
*02* INPUT:
*
*03* ENTRY-REGISTERS:
*
* R0 - R12,R15 - Irrelevant
* AR0-AR15 - Irrelevant
*
*02* OUTPUT:
*
*02* EXIT-NORMAL: RETURN TO CALLER
*
*03* CONDITIONS: successful completion
*
*03* EXIT-REGISTERS:
*
* R0 -R14 - Unchanged
* R15 - Return code (always 0)
* AR0-AR15 - Irrelevant
*
*03* RETURN-CODES: None
*
* Return code Reason code Interpretation
* ----------- ----------- --------------
* '0'x N/A Success
*
*02* EXIT-ERROR: None
*
***********************************************************************
*
*01* TERMINATION-CONSIDERATIONS: None
*
***********************************************************************
*
*01* EXTERNAL-REFERENCES :
*
*
*02* ROUTINES: Latch Services.
*
*02* DATA-AREAS: None
*
*02* CONTROL-BLOCKS:
*
* Name Use Mapping Description
* ------- ---- -------- ----------
* ISGYLID CW ISGLMASM Latch Identity Entry
*
* Legend: C=Create, R=Read, W=Write, D=Delete
*
*01* TABLES: TRTABLE
*
*01* MACROS-EXECUTABLE:
*
* None
*
*01* SERIALIZATION:
*
* None
*
*01* MESSAGES:
*
* None
*
*01* POST-CODES:
*
* None
*
*01* ABEND-CODES:
*
* None
*
*01* WAIT-STATE-CODES:
*
* None
*
*01* CHANGE-ACTIVITY:
*
* None
*
**** END OF SPECIFICATIONS ********************************************
LATCHX64 CSECT
LATCHX64 AMODE 64
LATCHX64 RMODE ANY
SYSSTATE AMODE64=YES Indicate AMODE 64
BAKR R14,R0 Save gprs 2-14 and PSW
SAC 0 Ensure primary mode
BRAS R12,PSTART Establish addressability
PSTART EQU *
USING PSTART,12
MODESET MODE=SUP Get into supervisor state
STORAGE OBTAIN,LENGTH=DYNALEN Get savearea and dynamic area
LGR R13,R1 Place savearea address into reg13
USING DYNASTORE,R13
MVC 4(4,R13),=C'F4SA' Set the Save area ID (64 bit)
*
**********************************************************************
* Create latch set
**********************************************************************
*
CALL ISGLCR64,(NUM_LATCH,LS_NAME,PRIVATE,LS_TOKEN,RETCD), X
MF=(E,CREATE_DPL)
*
**********************************************************************
*
* Initialize Storage for initial LID Entry Block.
* Note that in this example the DYNASTOR section is not freed and
* non-pertinent data is placed in the DYNASTOR section for simplicity.
*
* The default subpool associated with the STORAGE OBTAIN macro has a
* lifetime of the address space, so the DYNASTOR * section will exist
* for the life of the address space as well.
*
* However, IBM recommends using a separate storage request
* for the LIDPointerArray and ISGYLID_Entry blocks so that only
* necessary data will continue to exist beyond the life of the calling
* module.
*
* Also, it is not necessary to initialize all latch IDs in the set
* to point to a default ISGYLID_ENTRY block. NULL values in the
* Latch ID Pointer Array are acceptable.
*
**********************************************************************
*
XC INIT_STOR,INIT_STOR
XC ENTIRELIDARRAY,ENTIRELIDARRAY
LA R3,INIT_STOR Base ISGYLID_ENTRY block X
at address of allocated storage
USING ISGYLID_ENTRY,R3
LA R4,INITLIDSTR
STG R4,LIDPRINTABLESTRING@
LHI R4,L'INITLIDSTR Put length of INITLIDSTR into X
entry block
STH R4,LIDPRINTABLESTRINGLENGTH
L R4,ONEMINUTE Set hold threshold value to X
one minute
ST R4,LIDHOLDTHRESHOLD
L R4,THIRTYSECONDS Set contention threshold value to X
thirty seconds
ST R4,LIDCONTTHRESHOLD
*
**********************************************************************
*
* Set Latch ID array entries all to address of Initial Lid Entry ---
* indicating all entries are currently unused.
*
* Latch ID Pointer Array must be in the primary address space.
*
**********************************************************************
*
LGHI R6,0
L R4,NUM_LATCH
LOOP1 EQU *
STG R3,LIDPTRARRAY(R6)
A R6,LIDPTRARRAYLEN
BCT R4,LOOP1
DROP R3
*
**********************************************************************
*
* Attach Latch IDs to Latch Set
*
**********************************************************************
*
CALL ISGLID64,(LS_TOKEN,LIDPTRARRAY,LIDVERSION, X
RETCD),MF=(E,LID_DPL)
*
**********************************************************************
*
* Change Latch ID Entry for latch #3
*
* Note:
* Once the Latch Identity Pointer Array has been attached to the
* latch set, it cannot be deleted. However it can be replaced by
* calling the service again and specifying a new array. To change
* the Latch Identity for a particular latch, allocate a new latch
* identity block, fill it out, and update the corresponding array
* entry. Then the program is free to delete the previous latch
* identity block.
*
**********************************************************************
*
MVC NEW_STOR,INIT_STOR Copy LID Entry to new storage
USING ISGYLID_ENTRY,R3 Use R3 as base for LID Entry Block
LA R3,NEW_STOR
LA R4,NEWLIDSTR
STG R4,LIDPRINTABLESTRING@ Store address and length of new X
string in ISGYLID_ENTRY block
LHI R5,L'NEWLIDSTR
STH R5,LIDPRINTABLESTRINGLENGTH
L R4,LATCH_NUM Point to new ISGLID_ENTRY block
SLL R4,3 Multiply by 8 (size of LIDPTRARRAY)
STG R3,LIDPTRARRAY(R4)
DROP R3
*
**********************************************************************
* Obtain latch #3
**********************************************************************
*
MVC REQ_IDH,PSAAOLD-PSA Use ASCB address as high half
MVC REQ_IDL,PSATOLD-PSA Use TCB address as low half
CALL ISGLOB64,(LS_TOKEN,LATCH_NUM,REQ_ID,SUSPEND,EXCLUSIVE, X
ECB_ADDR,LATCH_TOKEN1,WORK_AREA,RETCD), X
MF=(E,OBTAIN_DPL)
*
**********************************************************************
* Release latch #3
**********************************************************************
*
CALL ISGLRE64,(LS_TOKEN,LATCH_TOKEN1, X
UNCOND,WORK_AREA,RETCD),MF=(E,RELEASE_DPL)
*
**********************************************************************
*
* Purge requestor from latch set.
*
* Normally reserved for recovery situations.
*
**********************************************************************
*
XC REQ_IDL,REQ_IDL Clear the low half of requestor ID
CALL ISGLPR64,(LS_TOKEN,REQ_ID,RETCD),MF=(E,PURGE_DPL)
*
**********************************************************************
*
* Purge all granted and pending requests for a group of requestors for
* a group of latch sets in the current address space.
*
* Normally reserved for recovery situations.
*
**********************************************************************
*
CALL ISGLPB64,(=AD(0),REQ_ID,REQ_MASK,LS_NAME,LS_MASK,RETCD), X
MF=(E,PURGEBA_DPL)
*
**********************************************************************
* Exit
*
* Restore caller's regs and return. Also restores caller's PSW key and
* State without a MODESET MODE=PROB.
*
**********************************************************************
*
LGHI R15,0 Set return code to zero
PR ,
*
**********************************************************************
* Equates
**********************************************************************
*
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
*
*
**********************************************************************
* Constants
**********************************************************************
*
NUM_LATCH DC F'16' Number of latches to create - input
* to create
LS_NAME DC CL48'EXAMPLE.ONE_LATCH_SET' latch set name - input to
* create
LS_MASK DC 48XL1'FF' Latch set name mask to match all
* names - input to purge group
REQ_MASK DC 4XL1'FF'
DC 4XL1'00' Requestor ID mask to match all
* requestors with the same first
* half (ascb@) and any second half
INITLIDSTR DC C'Latch not used' Initial LID string and length
*
LIDVERSION DC AL1(ISGYLID_VERSION1) Set latch version to default
*
LIDPTRARRAYLEN DC F'8'
*
THIRTYSECONDS DC F'30'
*
ONEMINUTE DC F'60'
*
NEWLIDSTR DC C'Serializing Abstract Resource' New string and length
*
PRIVATE DC A(ISGLCRT_PRIVATE) Create option - input to create -
* (defined in IDF)
LATCH_NUM DC F'3' Number of latch to be obtained -
* input to obtain
SUSPEND DC A(ISGLOBT_SYNC) Obtain option - input to obtain -
* (defined in IDF)
EXCLUSIVE DC A(ISGLOBT_EXCLUSIVE) access option - input to obtain -
* (defined in IDF)
UNCOND DC A(ISGLREL_UNCOND) Release option - input to release -
* (defined in IDF)
**********************************************************************
* Dynamic area for save area, parmlists, and variables
**********************************************************************
*
DYNASTORE DSECT
*
SAVEAREA DS 18D 144-byte register save area
*
ENTIRELIDARRAY DS 0XL128
*
LIDPTRARRAY DS 16AD LIDPtrArray
*
CREATE_DPL DS 0F
CALL ,(NUM_LATCH,LS_NAME,PRIVATE,LS_TOKEN,RETCD),MF=L
*
OBTAIN_DPL DS 0F
CALL ,(LS_TOKEN,LATCH_NUM,REQ_ID,SUSPEND,EXCLUSIVE, X
ECB_ADDR,LATCH_TOKEN1,WORK_AREA,RETCD),MF=L
*
LID_DPL DS 0F
CALL ,(LS_TOKEN,LIDPTRARRAY,LIDVERSION, X
RETCD),MF=L
*
RELEASE_DPL DS 0F
CALL ,(LS_TOKEN,LATCH_TOKEN1,UNCOND,WORK_AREA,RETCD),MF=L
*
PURGE_DPL DS 0F
CALL ,(LS_TOKEN,REQ_ID,RETCD),MF=L
*
PURGEBA_DPL DS 0F
CALL ,(0,REQ_ID,REQ_MASK,LS_NAME,LS_MASK,RETCD),MF=L
*
ECB DS F ECB (used only when the obtain
* option is ISGLOBT_ASYNC_ECB)
ECB_ADDR DS A Address of ECB - input to obtain -
* (required for the interface, but
* only used when obtain option is
* ISGLOBT_ASYNC_ECB)
LS_TOKEN DS 2F Latch set token - output from create
* and input to obtain, latch identity,
* release, purge, and purge group
LATCH_TOKEN1 DS 2F Latch token - output from obtain
* and input to release
REQ_ID DS 0D Double word requestor ID - input to
* obtain, purge, and purge group
REQ_IDH DS F First half of requestor ID (ascb@)
*
REQ_IDL DS F Second half of requestor ID (tcb@)
*
WORK_AREA DS 64D 512-byte work area
*
RETCD DS F Return code - output from services
*
INIT_STOR DS XL(ISGYLID_ENTRY_LEN) Isgylid_entry block storage
*
NEW_STOR DS XL(ISGYLID_ENTRY_LEN)
*
DYNALEN EQU *-DYNASTORE
*
IHAPSA , Needed for ascb@ and tcb@ req ID
ISGLMASM , Needed for latch constants
END LATCHX64