Controlled starting of objects during IPL with IPLLEVEL

You can use IPL levels to perform a controlled, step-by-step IPL or system shutdown. You can accomplish this by defining the IPL levels, specifying a start or stop timeout for each level, and by associating objects with the desired IPL level.

By using IPL levels, you can start or stop a group of objects to perform validation or maintenance before starting the next group of objects. You can also partially bring your system up or down to perform maintenance or other processing that does not require the entire system.

Task 1: Creating IPL levels

You create and name IPL levels by using the IPLORDER= parameter in the MAMINIxx BBPARM member. The order in which you define them determines the order in which TOM starts and stops objects associated with them during an IPL or shutdown.

You can also specify a timeout start and stop time for each level. TOM monitors the objects at each level to ensure that they reach the required state within the specified timeout time. If there are objects that are not in the required state at the end of the timeout period, you receive messages listing the objects not yet in their required state.

If you don't specify a timeout start or stop time for a level, TOM calculates default times as follows:

Start time—Number of objects associated with that level for the local system multiplied by 5 seconds
Stop time—Number of objects associated with that level for the local system multiplied by 10 seconds

To create IPL levels

In the MAMINIxx BBPARM member, set the IPLORDER parameter in the following format:

IPLORDER=((level1,start1,stop1),(level2,start2,stop2),…)

The variables in this parameter are defined as follows:

level1—Name of the first IPL level
start1—(Optional) Start time of the timeout period for the first IPL level, specified as a number of minutes from 1–99
stop1—(Optional) Stop time of the timeout period for the first IPL level, specified as a number of minutes from 1–99
level2—Name of the second defined IPL level
start2—(Optional) Start time of the timeout period for the second IPL level, specified as a number of minutes from 1–99
stop2—(Optional) Stop time of the timeout period for the second IPL level, specified as a number of minutes from 1–99

Example

(BASIC,5,10)—The IPL level is named BASIC. Its timeout start time is 5 minutes. its timeout stop time is 10 minutes.
(NETWORK,5)—The IPL level is named NETWORK. Its timeout start time is 5 minutes. Its timeout stop time is the default stop time.
(ONLINE,,10)—The IPL level is named ONLINE. Its timeout start time is the default start time. Its timeout stop time is 10 minutes.
(DATABASE)—The IPL level is named DATABASE. Both the timeout start and stop times are the default times.

Task 2: Associating objects with IPL levels

You can associate objects with an IPL level by specifying the level name in the object’s IPL Level: attribute. By specifying this object attribute, you can group your objects by IPL level to control which objects start and stop at each level. Any objects for which you do not associate with an IPL level or any objects that specify an IPL level that is not defined in IPLORDER are automatically associated with <null> IPL level.

To specify the timeout start and stop times for the <null> level

In the MAMINIxx BBIPARM member, set the following parameters:

Start time—IPLTIME parameter
Stop time—SHUTTIME parameter

If you don't specify values in these parameters, TOM calculates the default times as described in Task 1: Creating IPL levels.

Task 3: Starting objects

Starting your TOM PAS with the IPLL=Y parameter activates IPL level processing. Alternatively, to dynamically activate IPL level processing, perform one of these steps:

Use the ACTivate console command.
Use the TOMEXEC API ACTivate function with the IPLLEVEL parameter.
On the TSYS view, use the ACTivate line command.

TOM sets the first IPL level as the current IPL level and starts only those objects in your active Definition Base that are associated with that IPL level. Other objects do not start, so you can perform maintenance or validation at each level.

You then use the START IPLLEVEL command to start the objects associated with the next IPL level. TOM sets that IPL level as the current one and starts objects that are associated with it.

You can issue from this command as follows:

As a console command.
As a TOMEXEC API request
On the TSYS view, by using the SIL (START IPLLEVEL) line command

Use the START IPLLEVEL command again to start subsequent IPL levels. It always sets the next IPL level as the current one and starts the objects in that level. You cannot start IPL levels in a different order from that in which you defined them in the IPLORDER parameter.

After you've started all the defined IPL levels, you can use START IPLLEVEL again to start the objects associated with the <null> IPL level (that is, those that you didn't associate with any defined IPL level, as well as any objects that specify an IPL level you didn’t define in IPLORDER). All objects are now started.

Example

You set IPLORDER=(MINIMAL,DATABASE,ONLINE) and associated some objects with those levels, but left some objects unassociated.
You start TOM with IPLL=Y.
TOM sets MINIMAL as the current IPL level and starts all objects in the active Definition Base for the local system that are associated with that IPL level. No other objects start.
You issue the START IPLLEVEL command.
TOM sets DATABASE as the current IPL level and starts all the objects that are associated with that level.
You issue the START IPLLEVEL command.
TOM sets ONLINE as the current IPL level and starts all the objects that are associated with that level. All the objects associated with the defined IPL Levels have now started.
You issue the START IPLLEVEL command again.
TOM sets <null> as the current IPL level and starts all objects that do not specify an IPL level, as well as any that specify an IPL level that is not defined in IPLORDER.

Task 4: Stopping objects

To bring objects down, either for system shutdown or to perform maintenance, use the STOP IPLLEVEL command. You can issue this command as follows:

As a console command
As a TOMEXEC API request
On the TSYS view, by using the PIL (STOP IPLLEVEL) line command

When you issue the STOP IPLLEVEL command, TOM stops all objects associated with the current IPL level and then sets the previously defined IPL level as the current one. For example, if the current IPL level is <null>, STOP IPLLEVEL will cause TOM to stop all objects associated with the <null> level and then set the current IPL Level to the previously defined IPL level, which was ONLINE. The next STOP IPLLEVEL command will stop all objects defined to the ONLINE IPL level and set the current IPL Level to DATABASE. At any time, you can issue the START IPLLEVEL command to start the objects in the next defined IPL level. If you want perform maintenance, you can issue START IPLLEVEL or STOP IPLLEVEL commands to bring the system to the needed level.

You cannot use the STOP IPLLEVEL command if the current IPL level is the first level defined in IPLORDER. Instead, use the SHUTSYS command to bring TOM down.

You can use the SHUTSYS command at any time to bring down all objects, regardless of their IPL level.
Any time a SHUTSYS is performed with IPL levels enabled and the first defined IPL level is not the current level, TOM calculates the shutdown timeout value by accumulating the timeout stop value for each active level.

You set

IPLORDER=(MINIMAL,DATABASE,ONLINE).

If the current IPL Level is DATABASE and you issue SHUTSYS, the timeout stop value is the timeout value for the DATABASE level plus the timeout value for the MINIMAL level.

Troubleshooting

When TOM starts an IPL Level, it first determines how many objects are associated with that level on the local system. It then evaluates each object to ensure it can start. The following issues can prevent an object from starting:

Schedules or dependencies that are not satisfied
An object that is blocked or locked at IPL
An object that is in a SUSPEND state.

After TOM identifies eligible objects, it begins to start them. The process of starting objects is a continuous process until all objects are started or a timeout occurs. TOM might make several passes and issue the same messages each pass to indicate how many eligible objects are starting. This might occur because of object dependencies. If there are dependencies on other objects within the IPL level, TOM must first start the parent object and then start the child object on the next pass.

Important

If an object associated with one IPL level is dependent on an object associated with another IPL level, TOM might be unable to complete starting the object with the dependency.

For examples of performing a TOM IPL and shutdown by using IPL levels, please see Examples: Using IPL levels.