START function
The START function corresponds to the STArt line command, which can be issued for objects from the TOBJOR view or sets from the TSETO view or to advance to the next IPLLEVEL after IPL.
Use the START function to un-lock, un-block, or reset the status of an object and allow TOM to start it according to its dependencies and schedules.
Use the START command with the FORCE option to make an object ACTIVE regardless of its dependencies and schedules.
FORCE parameter
After TOM initiates the START function, TOM sets an indicator that shows that the object was started using the START function. The indicator is displayed in the Force Start column on the TOBJOR view or in the LINE.STATE REXX variable returned by the TOMEXEC FUNC(GET) request. This column can have one of the following two values:
IPL indicates that the START function was issued with the RESNEXTIPL parameter
When the next IPL occurs, TOM resets the indicator to NO and TOM initiates the start process defined for the object according to its dependency and schedule criteria are met.
FORCED indicates the START function did not include the RESNEXTIPL parameter
At each subsequent system IPL, TOM starts the object without considering its dependency and schedule criteria. This force-starting can be changed only by using the RESET RESETOPT(FORCED), RESET RESETOPT(OPER), or RESET RESETOPT(ALL) function. TOM issues the start command for the object without evaluating its dependencies or its schedule.
BYPASSCMDCT parameter with the FORCE parameter
TOM uses a start command counter to keep a count of the number of start commands that TOM issues for an object.
This prevents TOM from repeatedly attempting to start an object. You can specify a value for the Max Start Count attribute to define the maximum number of times that TOM attempts to start an object before a possible error is detected. If too many start commands are issued for an object and the Max Start Count value is exceeded, TOM changes the object status to FAILURE-CMDCOUNT.
You can clear the value in the start command counter with one of the following actions:
- Use the RESET RESETOPT(STARTCMDCT), RESET RESETOPT(OPER), or RESET RESETOPT(ALL) function
- Specify a value in the Reset start count at term attribute, which resets the start count when the object stops
- Specify a value in the Reset start count after attribute, which resets the start count after a user-specified period of time passes.
By default, TOM does not clear the start command counter. When the value in the counter exceeds the value set in the Max Start Count attribute, TOM does not attempt to start the object and sets the object status to FAILURE-CMDCOUNT.
When you specify the BYPASSCMDCT parameter with the START function, TOM does not check the value in the start command counter and attempts to start the objects, without clearing the start command counter and without placing the object into FAILURE-CMDCOUNT status.
The following table shows the command and parameters:
Command | Parameters |
---|---|
TOMEXEC FUNCTION(START) | OBJECT(name)|SET(name) | IPLLEVEL HOST(hostname) [FULLAUTO] [UNLOCKDEPS] [ RESNEXTIPL|NORESNEXTIPL] [BYPASSCMDCT] [CMDNUMBER(nnn)] [CMDLABEL(label_name)] [OMODE(label_name)] [NOTE('xxx')] [ FORCE | NOFORCE] [TOMID(tom ID) | TOMPLEX(tomplex name)] |
The following table describes the parameters:
Parameter | Function |
---|---|
OBJECT | Specify the object name to be started. For information about specifying the object name, see Object-and-set-naming-restrictions. |
SET | Specify the set name to be started. For information about specifying the set name, see Object-and-set-naming-restrictions. |
IPLLEVEL | Start the next 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 from the object definition’s valid systems list on which to start the object. The HOST parameter is optional. If you do not specify HOST, TOM issues the function on the ACTIVE system. |
FULLAUTO | (This parameter is valid only when you specify it with the FORCE parameter. Just as it is for RESNEXTIPL, BYPASSCMDCT and NORESNEXTIPL. Specify to indicate that TOM will schedule all of the object's pre-start and post-start, commands during the START process. When this parameter is not specified, these commands are not scheduled. |
UNLOCKDEPS | Specifies that all LOCKED valid system list entries will be changed to STOPPED on each descendant of the object being started. UNLOCKDEPS is useful when the object being started was stopped using the LOCKDeps option. |
RESNEXTIPL | This parameter is valid only when you specify it with the FORCE parameter. Specify this parameter to remove the object from Forced status after the next IPL and resume control based on the object’s defined schedule and other object attributes. When this parameter is not specified, the object remains in this Forced status through subsequent system IPLs. |
NORESNEXTIPL | This parameter is valid only when you specify it with the FORCE parameter. Specify this parameter to force the object to start during subsequent IPLs of the system, without regarding the object's dependencies and schedules. |
BYPASSCMDCT | This parameter is valid only when you specify it with the FORCE parameter. Specify to start object without checking whether the command count specified in the object's definition has been exceeded (on the Maximum Start Count field of the object ADD or EDIT dialog). |
CMDNUMBER | If multiple start commands are defined for the object, specify the number of the command in the list that the START command uses. If you do not specify the CMDNUMBER keyword, TOM uses the start command that is defined by the object's Default Start Command attribute. |
CMDLABEL | Starts the object with the start-sequence commands (pre-start, start, post-start, or retry-start) that match the label specified with this parameter value. If there are pre-start, start, post-start, or retry-start commands that are not labeled, they are also used. If the object does not have a START command labeled with the CMDLABEL parameter, the MAMOD2209E message is issued and the object is not started. |
OMODE | Starts the object in a specific operating mode (OMODE) with the start-sequence commands (pre-start, start, post-start, or retry-start) that match the label specified with this parameter value. If there are pre-start, start, post-start, or retry-start commands that are not labeled, they are also used. In addition, you must specify the OMODE parameter in BBPARM member MAMINIxx. If you do not ,TOM issues the MAMOD2212E message and does not start the object. When TOM successfully starts an object using OMODE, TOM retains the OMODE for that object until one of the following events happens:
|
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. |
FORCE | Specify to override the setting START_FORCE=NO in BBPARM member MAMINIxx or, specify that the object is started to make it ACTIVE without following the object's schedules and dependencies. |
NOFORCE | NOFORCE is the default unless START_FORCE=YES is specified in the MAMINIxx BBPARM member. Specify NOFORCE to override the START_FORCE=YES setting in BBPARM member MAMINIxx or to specify that the object status is UNLOCKED, UNBLOCKED, or RESET. This allows TOM to start the object according to it's schedules and dependencies. |
TOMID | Specify the ID of the system 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 START IPLLEVEL command starts objects
When you specify the IPLLEVEL parameter with the TOMEXEC FUNCTION START command, TOM starts the next level of objects after an IPL. Successive TOMEXEC FUNCTION START IPLLEVEL commands then start additional levels of objects, one level at a time. When TOM completes starting all of the IPL levels, the next TOMEXEC FUNCTION START IPLLEVEL command starts all of the objects that are not defined as part of an IPLLEVEL group.
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 use the IPLLEVEL feature, you must specify IPLL=Y on the EXEC PARM statement of the TOM start procedure and specify a value (or multiple values) for the IPLORDER parameter in MAMINIxx. You then associate objects with IPL levels by specifying the level name with the object's IPLLEVEL attribute. When IPL and the TOM PAS completes initialization, TOM automatically starts the objects that have the IPLLEVEL attribute value matching the first (or possibly only) value listed with the IPLORDER parameter.
To disable the IPLLEVEL feature, specify IPLL=N parameter in the TOM start procedure. This will cause TOM to start all of the objects as though there are no values specified with the IPLORDER parameter in BBPARM member MAMINIxx.
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:
Related topic