STOP function
The STOP function corresponds to the STOp line command, which can be issued for objects from the TOBJOR view or sets from the TSETO view.
Use STOP to stop an object and make its status LOCKED or BLOCKED on all of the systems in its VSL.
When this function is used to stop objects defined within a set and the TOPTOBOTTOM parameter is specified, the objects in the set might be stopped immediately, without first stopping the objects that depend upon the members of the selected set.
Using the STOP function is a recommended method of manually stopping an object because you have the most control over the stopping process such as controlling the dependency stop order.
The following lists additional considerations for using the STOP function and parameters:
- When you specify the STOP function with the RESNEXTIPL parameter, the stopped object has a status of LOCKED on all of the systems in its VSL.
- When you specify the STOP function without the RESNEXTIPL parameter, the stopped object has a status of BLOCKED on all of the systems in its VSL.
To stop the selected object without affecting its children, specify the HOLD parameter.
The selected object will be stopped and placed in the status of ACTIVE-HOLD.
- To schedule the object’s pre-stop or post-stop commands during the stopping process, specify the FULLAUTO parameter.
To stop the object and its dependent objects that have a WEAK relationship to the object, specify the BYPASSSTRENGTH parameter.
If the strength of the dependency relationship between an object and its dependent objects is weak, and you do not specify the BYPASSSTRENGTH parameter, TOM does not stop the dependent objects.
- To stop an object that is in SUSPEND control mode, specify the BYPASSCNTL parameter.
TOM processing stops the selected object's dependents in dependency order and changes their status to STOPPED on the system where they were previously ACTIVE. When all of the selected object's dependents have stopped, the selected object is stopped and TOM sets its status to BLOCKED on all of the systems in its VSL (or LOCKED if the RESNEXTIPL parameter is specified).
The following table shows the command and parameters:
Command | Parameters |
|---|---|
TOMEXEC FUNCTION(STOP) | OBJECT(name)|SET( name) IPLLEVEL [HOST(hostname)] [HOLD] [LOCKDEPS] [FULLAUTO] [RESNEXTIPL] [BYPASSSTRENGTH] [BYPASSCNTL] RESOMODE [CMDNUMBER(nnn)] [CMDLABEL(label_name)] [ BOTTOMTOTOP | TOPTOBOTTOM] [NOTE('xxx')] [FORCE] [TOMID(tom ID) | TOMPLEX(tomplex name)] |
The following table describes the parameters:
Parameter | Function |
|---|---|
OBJECT | Specify the object name to be stopped. For information about specifying the object name, see Object-and-set-naming-restrictions. |
SET | Specify the set name to be stopped. For information about specifying the set name, see Object-and-set-naming-restrictions. |
IPLLEVEL | Stop the current level group of objects. When you specify the IPLLEVEL parameter, the only other parameters you can specify are the HOST and NOTE parameters. |
HOST | Specify the name of a MVS system in the object definition’s valid systems list where the object is ACTIVE. The HOST parameter is optional. If you do not specify HOST, TOM issues the function on the ACTIVE system. |
HOLD | Specify this parameter to prevent TOM from issuing STOP commands for the dependents of the named object or set. The object is set to ACTIVE-HOLD status unless an error is encountered; in which case, a FAILURE- status is set. To restart an object that has been placed into ACTIVE-HOLD issue RESET RESETOPT(RUNSTAT) to return the object to ACTIVE status without adversely affecting other objects. |
LOCKDEPS | Specifies that a BOTTOMTOTOP (dependency order) stop take place. The status of the children of the object will be set to LOCKED instead of STOPPED. Objects that are not ACTIVE are not affected by this stop. LOCKDEPS prevents the children objects from being automatically started by TOM after the dependency order STOP completes in case a complex dependency formula might be satisfied by a different parent of the child. |
FULLAUTO | Specify to indicate that TOM will schedule all of the object's pre-stop and post-stop commands during the STOP process. When this parameter is not specified, these commands are not scheduled. |
RESNEXTIPL | Specify to cause the object's status to be LOCKED after it stops; otherwise, the status is BLOCKED and the object will not start at the next system IPL. |
BYPASSSTRENGTH | Specify to bypass (or skip) dependency strength check during a dependency order STOP. |
BYPASSCNTL | Specify not to check the object's control mode for SUSPEND; this allows the object to be stopped when its control mode is SUSPEND. |
RESOMODE | Resets the operating mode (OMODE) of the object. When you specify this parameter, the OMODE is reset for an object and TOM might start or stop any objects that use the @OMODE dependency attribute that depend on the object being RESET. This command resets only the OMODE setting for the Valid System List (VSL) entry where TOM is stopping the object. |
CMDNUMBER | When multiple Stop commands are defined for the object, specify the number of the command that TOM uses to stop to object. If you do not specify the CMDNUMBER keyword, TOM uses the STOP command that is defined by the object's Default Stop Command attribute. |
CMDLABEL | Stops the object with the stop-sequence commands (pre-stop, stop, post-stop, or retry-stop) that match the label specified with this parameter value. If there are pre-stop, stop, post-stop, or retry-stop commands that are not labeled, they are also used. |
TOPTOBOTTOM | Stops the selected object first. If the selected object has children defined, TOM then stops the children objects. |
BOTTOMTOTOP | Stop the selected object after TOM stops any defined children objects. TOM stops the children objects in dependency order. |
FORCE | Stop the selected object, regardless of its status. The FORCE option also mean that while stopping the object, TOM does not check the object's control mode for SUSPEND and stops objects in SYSPEND mode (similar to specifying the BYPASSCNTL parameter). When you specify FORCE, the BYPASSCNTL parameter is implied and the FORCE command stops objects that have a Status of SUSPEND and ignores the object's Verify stop confirmation attributes. FORCE does not stop objects with the following transitional statuses:
In addition, for objects that have a Status of FAILURE-PRESTOP, if you specify FORCE with the FULLAUTO keyword, the object is not stopped and TOM returns the following warning message: MAMOD2357W Use STOP FORCE without FULLAUTO for objectName |
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 will be rejected with RC147. 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. See Specifying-the-TOMID-and-TOMPLEX-parameters for usage information. |
How the TOMEXEC FUNCTION STOP IPLLEVEL command stops objects
When you specify the IPLLEVEL parameter with the TOMEXEC FUNCTION STOP command, TOM stops the current IPL level of objects. Successive TOMEXEC FUNCTION STOP IPLLEVEL commands stop additional levels of objects, one level at a time. When there is only one active IPL level remaining, TOM rejects the TOMEXEC FUNCTION STOP IPLLEVEL command and issues the following message:
At this point, you must use the SHUTSYS command to stop the remaining active objects in the definition base.
Using the IPLLEVEL attribute when defining objects is optional. If you want to define objects for TOM to start in groups after an IPL, you can have one or more IPLLEVEL groups defined in an object definition base.
To create levels of objects, you must specify IPLL=Y on the EXEC PARM statement of the TOM start procedure and specify a value (or multiple values) with the IPLORDER parameter in MAMINIxx. Then, to match the objects to the levels, specify the values to object definition with the IPLLEVEL attribute. If IPLL=N is specified then IPL levels will not be active during the life of the IPL.
For more information and an example about how IPLLEVEL works, see Controlled-starting-of-objects-during-IPL-with-IPLLEVEL.