$GETLOK – Acquire the MVS CMS, LOCAL, or JES2 job lock

$GETLOK – Acquire the MVS CMS, LOCAL, or JES2 job lock

z/OS JES2 Macros
SA32-0996-00

Use $GETLOK to acquire the MVS™ CMS, LOCAL, or JES2 job lock depending on the type of lock requested and the environment from which it is requested.

Use $GETLOK to obtain the cross-memory services (CMS) lock to serialize the JES2 main task with routines that are executing for tasks in other address spaces. The CMS lock is required when modifying certain operating system control blocks and in some cases when interfacing with JES2 code that is running in support of the subsystem interface and access method interface in other address spaces. After obtaining the CMS lock, the user should not execute any code that allows the execution of any SVC instructions until after first freeing the lock through $FRELOK macro instruction.

Obtaining the local lock (LOCAL) serializes the use of resources such as queues and control blocks among several tasks running within the same address space. The functional subsystem interface (FSI) service routines running in the functional subsystem address space require the local lock for serialization of queues, buffer pools, and control blocks so many separate functional subsystem application (FSA) tasks can use these resources.

Obtaining the JES2 job lock (JOB) prevents job queue elements (JQEs) from being changed by any code except the issuer of the job lock.

Note: The reason for executing the $GETLOK macro instruction should be fully documented in your code.

Format description


>>-+--------+--$GETLOK------------------------------------------>
   '-symbol-'            

>--+-------------------------------------------+---------------->
   |          .-CMS--------------------------. |   
   '-TYPE--=--+-LOCAL------------------------+-'   
              '-(--JOB--,--JQE--=--relexp--)-'     

>--+------------------+----------------------------------------><
   |          .-YES-. |   
   '-WAIT--=--+-NO--+-'

TYPE=

Specifies the lock to be obtained. Modules assembled for the JES2 environment can specify CMS or JOB only. Modules assembled for the FSS environment can specify CMS or LOCAL only.

CMS (default): The cross-memory lock is to be obtained. All other operands are ignored.
LOCAL: The MVS local lock is to be obtained. All other operands are ignored.
JOB: The JES2 job lock is to be obtained. In this case a job queue element address (JQE=) must be specified.

JQE=

Specifies the address of a fullword containing the address of the specified JQE in its three right-most bytes. JQE= must be specified for TYPE=JOB.

WAIT=

Specifies whether to $WAIT for the JOB lock to be obtained. This keyword only applies to a TYPE=JOB request; otherwise, it is ignored. WAIT=YES is the default.

On return from the $GETLOK routine, register 15 will contain a return code as follows:

Return Code: Meaning
0: Lock obtained
4: Wait required
8: JQE was freed while waiting for the lock.

Environment

Main task and functional subsystem (HASPFSSM).
$WAIT can occur (if you specify WAIT=YES on the macro).