STOP function
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.
While stopping objects, you should consider the TOPTOBOTTOM and BOTTOMTOTOP stop order parameters as the scope of the stop request. A stop request that specifies the TOPTOBOTTOM parameter intends to stop one object. Using the BOTTOMTOTOP parameter stops the selected object as well as its descendants.
By default, TOM stops objects by using the DEPENDENCY order. DEPENDENCY means the same as BOTTOMTOTOP. You can change that default behavior by specifying TOPTOBOTTOM in the STOP_ORDER parameter in the MAMINIxx parameter member.
TOPTOBOTTOM causes TOM to issue a stop command only for the selected object. Other objects may come down after a subsequent evaluation pass. Whether objects are stopped after evaluation depends upon the dependency entry of the object. If an object running in the system depends upon the object stopped by the TOPTOBOTTOM stop request being active, then TOM will automatically stop that object.
Objects stopped after the evaluation pass will not be stopped with the same parameters (BYPASSCNTL or BYPASSSTRENGTH) as those were used for the object that was stopped with the TOPTOBOTTOM parameter. These objects come down using either default parameter values or with attributes in the object’s definition.
A BOTTOMTOTOP or DEPENDENCY stop can have a much wider scope of objects affected by the command than TOPTOBOTTOM. TOM starts a BOTTOMTOTOP stop by determining the names of the objects in its dependency structure. The dependency structure is made up not only of the immediate children of the selected object but its grandchildren and great grandchildren. TOM keeps running down a relationship branch until it encounters an object that has no children.
After finding the last object in a relationship branch TOM begins by stopping that object. When that object has been successfully stopped, its parent will be stopped when all its other children have been stopped. This process continues until all the descendants of the selected object are stopped. TOM then stops the selected object.
If additional parameters such as BYPASSCNTL or BYPASSSTRENGTH have been specified in the BOTTOMTOTOP stop request, then TOM will apply those parameters when stopping the other objects in the dependency structure.
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 (if they specify @STATUS EQ ACTIVE for the dependency property), 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] | [BYPASSSTRENGTH=Yes|No] [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 if they specify @STATUS EQ ACTIVE for the dependency property. 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 START or RESET RESETOPT(RUNSTAT) to return the object to ACTIVE status without adversely affecting other objects. |
LOCKDEPS | For a dependency-order (BOTTOMTOTOP) stop, 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 NO to check the relationship strength of dependent objects during a dependency-order (BOTTOMTOTOP) stop to prevent stopping dependent or child objects that have a WEAK relationship to their dependencies or parents. You might want to specify this parameter when specifying the FORCE parameter because FORCE implies the BYPASSSTRENGTH or BYPASSSTRENGTH=YES option. See the definition for the FORCE parameter for more information. |
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 or set, specify the number of the command that TOM uses to stop the object or set. If the CMDNUMBER keyword is not specified, or if it is specified as 0, then TOM uses the default STOP command. |
CMDLABEL | Stops the object or set 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 or 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 that have a WEAK relationship strength. |
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 SUSPEND 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 also implies BYPASSSTRENGTH. Dependency strength checking will be bypassed. See the definition for the BYPASSSTRENGTH parameter for more information. 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.
This section contains the following topics: