Admin Alert: Getting into a i5/OS Restricted State
September 10, 2008 Joe Hertvik
There’s a special place for restricted state processing in the i5/OS or OS/400 world. In restricted state, administrators can apply upgrades, change core system parameters, backup the operating system and run special commands that affect partition configurations. This week, I’ll examine everything about restricted state processing, from why it exists, to how to enter and leave this core operating system function.
The Beauty of Restriction
Some i5/OS functions can’t be run while the system is active. That’s why IBM created restricted state processing, a feature that isn’t available in many other operating systems. Restricted state occurs when you end all the subsystems that perform user-submitted work (some Q subsystems that run the partition itself will remain active). The system console is the only device that remains active in restricted state. No other users and devices can connect to the system and no batch jobs can run. Restricted state provides an almost quiet system that allows you to perform work that cannot be done when the system is processing user-based work.
Restricted state functions include backing up the operating system through the Save System (SAVSYS) command and correcting damaged objects and user profiles through the Reclaim Storage (RCLSTG) command. You must also be in restricted state to upgrade your operating system and make certain system changes.
Entering Restricted State
The hardest thing about entering restricted state is stopping the work on your system. Most shops are running 24×7, and it can be a negotiation process getting users to give up the machine. Once everyone has signed off and all batch and server jobs have ended, it’s a simple matter to enter restricted state by performing one of the following three techniques:
Each technique has its own advantages and drawbacks. Here’s how they compare to each other.
ENDSBS: The Usual Way
Most people enter restricted state by running the End Subsystem command this way:
ENDSBS SBS(*ALL) OPTION(*IMMED)
With these parameters, ENDSBS will immediately end all non-essential active jobs and subsystems except for the partition’s controlling subsystem and system console. There will be no warning to the users and no chance to end things cleanly once ENDSBS starts. To end your system in a more controlled manner, you can run ENDSBS with these parameters.
ENDSBS SBS(*ALL) OPTION(*CNTRLD) DELAY(*NOLIMIT)
A controlled ending gives your jobs time to perform end of job processing before termination. Because this command specifies *NOLIMIT in the Controlled end delay time parameter (DELAY), the system will allow each job as much time as it needs to end cleanly. However, using *NOLIMIT can be a bad idea because if a job up is hung or can’t perform EOJ processing, the system will never go into restricted state. It’s better to run ENDSBS with these parameters for controlled endings.
ENDSBS SBS(*ALL) OPTION(*CNTRLD) DELAY(xxxxx)
The xxxxx equals the number of seconds ENDSBS should wait for each job before ending that job immediately. This setting allows as many jobs and subsystems as possible to end normally. When the delay time runs out, the system will forcibly end all jobs and subsystems that have not finished their processing.
ENDSYS: A Slightly Better Way to End Subsystems
The End System (ENDSYS) command is slightly more flexible than ENDSBS. Like running ENDSBS with the *ALL parameter, ENDSYS ends all subsystems and system jobs. Like ENDSBS, ENDSYS has a How To end and Controlled end delay time parameter for forcefully or gently bringing down system work. There are only two practical differences between running ENDSBS and running ENDSYS.
First, ENDSYS notifies all active subsystems that a shutdown process is beginning. This may give some of your users and applications time to terminate cleanly before the system ends. The second difference is that you can configure ENDSYS to confirm whether the system shutdown request should be started. You can force confirmation for ENDSYS by running the command this way:
With CONFIRM set to *YES, ENDSYS will request a user confirmation before taking down the system. This is handy in case one of your administrators unintentionally runs the ENDSYS command during the day or changes their mind after starting the command. As valuable as CONFIRM *YES is, please understand that *YES is not the default setting for CONFIRM. CONFIRM is set to *ENVVAR, by default. *ENVVAR specifies that the command will consult the value in the system’s QIBM_ENDSYS_CONFIRM environment variable to determine it should ask for a confirmation. The problem with using QIBM_ENDSYS_CONFIRM is that IBM provides little documentation on how to set the environment value. It’s also unclear what happens if the value is not set. If anyone has more information on displaying and setting QIBM_ENDSYS_CONFIRM, please email me using the IT JungleContact page and I may publish your comments in a future article.
Because QIBM_ENDSYS_CONFIRM is a little obscure, changing CONFIRM’s default value to *YES may be the best way to always receive a confirmation request when running ENDSYS. For more information on changing command default parameters, check out this article on using the Change Command Default command.
Configuring Your System To IPL Into Restricted State
The third way to enter restricted state is to set up the box to IPL into restricted state. This is easily done by setting the Start to restricted state parameter (STRRSTD) to *YES in the Change IPL Attributes (CHGIPLA) command. To do this, type in the CHGIPLA command on a 5250 green screen and press the F4 key to prompt for its parameters. When you change STRRSTD set to *YES, the next partition IPL will not start the controlling subsystem and your system will start up in restricted state.
The nice thing about STRRSTD is that it’s a one-time change. After the system IPLs into restricted state, i5/OS will reset STRRSTD back to *NO so that you can perform a normal IPL the next time.
Knowing When Your System Is In Restricted State
There are three ways to tell when a system is in restricted state.
1. Look at the Work with Active Jobs (WRKACTJOB) command on the system console green screen. For systems that are in restricted state, all subsystems will be down. The controlling subsystem (usually QBASE or QCTL) will be the only active subsystem and there will only be one active job in that subsystem, the system console. The controlling subsystem job status may be set to END, when using ENDSBS or ENDSYS commands to put the system in restricted state.
2. Run the Work with Subsystems (WRKSBS) command. WRKSBS shows all the active subsystems, the subsystem pools that are assigned to each subsystem, and the status of each subsystem. When your system is in restricted state, WRKSBS will only show one entry for the controlling subsystem. Press F11 on that entry to view the subsystem status. If the controlling subsystem’s status is RSTD, then your system is in restricted state.
3. Look in the System Operator message queue (QSYSOPR) or the System History Log. When an i5/OS system goes into restricted state, the operating system puts the following CPF0968 message into QSYSOPR and the system history log. Run the Display Messages (DSPMSG) command to look for the message in QSYSOPR:
To find this message in the System History log, run the following Display Log (DSPLOG) command:
The CPF0968 message will look like this:
CPF0968 - System ended to restricted condition.
4. Call the Retrieve System Status API (QWCRSSTS) with the SST0200 format. When called with this format, the program returns a Restricted State flag in position 31.
Getting Out of Restricted State
Once you finish restricted state processing, there are two ways to restart your subsystems and jobs.
1. Restart your controlling subsystem. In restricted state, the controlling subsystem is considered ended. Once you restart the controlling subsystem, it launches the system startup program listed in the Startup Program system value (QSTRUPPGM). To view QSTRUPPGM’s value, execute the following Display System Value (DSPSYSVAL) command:
I would caution you against restarting your system by calling the QSTRUPPGM program. Doing that will restart most of your subsystems but it will not restart the controlling subsystem. This can cause problems depending on whether you process work in that subsystem. It’s always cleanest to restart your i5/OS system by restarting the controlling subsystem. This can be done by running this Start Subsystem (STRSBS) command.
STRSBS SBSD(Controlling subsystem name)
You can find the name of the controlling subsystem in the Controlling Subsystem system value (QCTLSBSD):
2. IPL your system with the STRRSTD IPL attribute set to *NO. When the system restarts, it will automatically start the controlling subsystem and run the QSTRUPPGM program to restart your subsystems and applications.
Easy to Understand
There’s nothing mysterious about getting into and out of restricted state. Once you know the tricks, the rest is easy.
About Our Testing Environment
Configurations described in this article were tested on an i5 550 box running i5/OS V5R4. Many of the commands are also available in earlier versions of the operating system running on iSeries or AS/400 machines. If a command is present in earlier versions of the i5/OS or OS/400 operating systems, you may notice some variations in the pre-V5R4 copies of these commands. These differences may be due to command improvements that have occurred from release to release.