LOCK function

The LOCK function corresponds to the LOCK line command, which you can issue for objects from the TOBJOR view or sets from the TSETO view.

LOCK makes the object (or objects in the set) unavailable for scheduling until the next system IPL or until you manually reset the status. The status of the object is set to LOCKED on the selected system. If the object status is ACTIVE on the selected system, TOM stops the object.

You can issue the LOCK function against objects in inactive Definition Bases. A system IPL resets the LOCKED status.

Related topic

Using-the-TOM-programming-interface

LOCK ignores dependencies on the object being locked. After the object is locked, object evaluation occurs and any objects (children) with strong dependencies on the LOCKED object are set to an evaluated status of INACTIVE, and then stopped. If the object being locked has children with STRONG dependencies, we recommend that you use STOP instead of LOCK so that TOM can determine which children, if any, need to also be stopped. A dependency order stop (BOTTOMTOTOP) stops the children first and then the parent.

If you specify the RESNEXTIPL parameter on the STOP command, the object is locked. If you do not specify RESNEXTIPL, the object is blocked.     

Important

When you use the BLOCK or LOCK function, TOM always schedules any pre- or post-stop commands that are defined for the object. In contrast, the STOP function allows you to choose whether the pre- and post-stop commands are scheduled.

Restarting objects with LOCKED status

When you perform an initial program load (IPL) on a system, TOM unlocks any objects in a LOCKED status on that system, allowing TOM to start the objects when TOM determines that their schedule and dependency criteria are satisfied.

To allow TOM to start an object in LOCKED status on a specific system before its IPL, you must perform one of the following actions (from the UI, in an EXEC, or from the operator console):

  • Issue the START command.
  • Specify the UNLOCK command with the system name in the HOST parameter.
  • Issue the RESET RESETOPT(STATUS) command.
  • Issue the RESET RESETOPT(ALL) command.

If the object has multiple systems in its VSL and is not ACTIVE on one of those systems, TOM starts the object if you issue one of the following functions:

  • UNLOCK (or START) function (or command) for that system 
  • RESET RESETOPT(STATUS) or RESET RESETOPT(ALL) function (or command) for the object

The following table shows the command and parameters:

Command

Parameters

TOMEXEC FUNCTION(LOCK)

OBJECT(name)|SET(name)

[HOST(hostName)]

DEFBASE(name)

SYSPLEX(name)

[CMDNUMBER(nnn)]

[NOTE('xxx')]

[TOMID(tom ID) | TOMPLEX(tomplexName)]

IPL(nn)

The following table describes the parameters:

Parameter

Function

OBJECT

Specify the object name to be locked (mutually exclusive with the SET parameter).

For information about specifying the object name, see Object-and-set-naming-restrictions.

SET

Specify the set name to be locked (mutually exclusive with the OBJECT parameter).

For information about specifying the set name, see Object-and-set-naming-restrictions.

HOST

(Optional) Specify the name of a MVS system that is specified in the object definition’s valid systems list. TOM issues the function on the primary system in the VSL.

If you do not specify HOST, TOM issues the function on the ACTIVE system.

DEFBASE

Specify the object Definition Base where the object or set is stored in the Registry.

This value is associated with the sysplex keyword value. If you do not specify DEFBASE, the currently active object base is used.

SYSPLEX

Specify the sysplex associated with the Definition Base named by the DEFBASE parameter where the object is stored in the Registry.

CMDNUMBER

When multiple Stop commands are defined for the object, specify the number of the command that the LOCK command will use.

If you do not specify the CMDNUMBER keyword, TOM uses the STOP command that is defined by the object's Default Stop Command attribute.

NOTE

Specify a reason for the action taken.

By default, this parameter is optional, but it is required if you specify OPER_NOTE_REQUIRED=YES in BBPARM member MAMINIxx.

If NOTE('xxx') is required but is not specified, the request is rejected with RC147 and error message MAMOD2035E is written to the log.

TOMID

Specify the ID of the TOM PAS on which you want the command issued.

TOMPLEX

Specify the name of the TOMPLEX where you want to issue the function.

For usage information, see Specifying-the-TOMID-and-TOMPLEX-parameters.

IPL

Specify the IPL parameter to indicate that, this object should be locked starting with the next IPL of the system specified by the HOST() parameter. If you want it processed for all systems in the Valid System List (VSL), then you can specify HOST(*). HOST(*) is valid only when IPL() is specified.

When this parameter is specified, the object is not immediately stopped and is not locked until the next IPL. Valid values are: 

  • IPL(0)–Reset Lock for next nn IPLs for the system specified by the HOST( ) parameter. The object is no longer locked at IPL for the system. No action (start/stop) is taken for the object. This resets only the LOCK-at-next-IPL setting.
  • IPL(nn)–nn is a number from 1 through 99 that indicates how many IPLs of the system specified by the HOST( ) parameter after which the object is locked.
  • IPL(ALL)–When you specify ALL, the object is locked at every IPL of the system specified by the HOST( ) parameter until LOCK IPL(0) is requested.

This section contains the following topics:

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*