Shutdown UDC Documentation
As of: August 7, 2003
The SHUTDOWN command was enhanced in release 7.0 of MPE/iX. From the dark reaches of time, the SHUTDOWN command on MPE systems has always been supported through a console interrupt [CTRL-A]. The objective of the enhancement was to provide a SHUTDOWN mechanism with a reboot option at the command level similar to the HP-UX operating system.
Prior to using this UDC, read and become familiar with the changes to the command. The changes are documented in the 7.5 Communicator.
This UDC was created to:
Because the enhancement to the SHUTDOWN command was designed to mimic HP-UX functionality, the UDC was also designed to imitate how Unix systems conduct an orderly system shutdown.
Unix systems use "sequencer directories" to control system start-up and shutdown. Sequencer directories are number, typically from 1 to 5. During system start-up, items in the first sequencer directory are started, then items in the second and so on. The reverse happens during a normal shutdown. Items in the last directory (usually fifth) are halted first, with items in the fourth directory stopped next and so forth.
Many MPE shops have emulated the same process -- starting "important" things/jobs early during system start-up and similarly halting them late during shutdown (like the network) -- but without benefit of assistance from the operating system.
The SHUTDOWN UDC introduces the concept of a single location -- an MPE group -- holding the scripts to perform an orderly system shutdown. This mechanism provides a highly adaptable/customizable method to manage a shutdown.
The default shutdown group is SDCMD in the SYS account. Because some sites can't or won't create a group in the SYS account, the UDC supports an external CI variable SHUTDOWN_CMD_LOC. Use SETVAR to establish the group and optional account that holds your shutdown scripts. For example:
SETVAR SHUTDOWN_CMD_LOC ".MYSDCMD.MYACCOUNT"
If the default group is used, the recommended newgroup command is:
NEWGROUP SDCMD;ACCESS=(R,W,A,L,S:GU;X:AC)
The system operator needs to have execute access to this group. This group should not be the home group for anyone. If the group is not in the SYS account, extra steps need to be taken to assure the security/accessability of these files.
It is important to know that the "flow" of the shutdown process is entirely in system administrator's hands. If one process must be halted before another, the control mechanism must be constructed. There are no pauses in the UDC.
All scripts in this group are XEQ'd in alphabetical order. This allows the system manager to tailor the sequence of events according to their own needs. If the current shutdown process is encapsulated in one job stream, then only one XEQ file needs to be in the shutdown group and the script simply needs to stream the job. Of course, if the shutdown process is a series of job or a sequence of UDCs, then more XEQ files will be needed.
It is up to the system manager to decide of the overall shutdown process needs to be handled sequentially or if can be handled by parallel processes.
With a location established, the focus changes to the files in the group. As stated earlier, the files need to be valid MPE command files. Additionally, each file must do it's own error checking and pause control. For example, consider the following script:
stream stopsrvr.jcl.myaccount
What if --
It should be obvious that thought must be applied to the contents of the XEQ files prior to implemantation. The following is an example of an XEQ file that would work in many environments:
if finfo('stopsrvr.jcl.myaccount','exists')
errclear
continue
stream stopsrver.jcl.myaccount
if hpcierr = 0
pause job=!hplastjob
else
echo ERROR: Trouble streaming job 'stopsrvr.jcl.myaccount'
echo !hpcierrmsg
escape !hpcierr
endif
else
echo ERROR: stopsrvr.jcl.myaccount job could not be found
escape 99
endif
In the above script, much care is taken to be sure that the file exists, that it stream properly and the script also waits until the job completes ("pause job=!hplastjob"). Note the use of escape.
Obviously, much work needs to be done to implement this UDC. To aid this process, the UDC supports another external CI variable "SHUTDOWN_TESTING". Setting this variable to true will prevent the UDC from actually issuing the SHUTDOWN command. It is recommended that the variable also be incorporated into the shutdown XEQ scripts so that complete end-to-end testing can be conducted in safety.
The UDC is designed to be cataloged for both OPERATOR.SYS and MANAGER.SYS. Internal checks require session-use of the UDC to be done by either user on the physical console. If MANAGER.SYS includes any (valid) parameter(s) the normal shutdown process will be by-passed. This is because there will be times when the system administrator needs to shutdown the system in a hurry due to an emergency or is doing extra-ordinary system maintenance, like an operating system update.
Additionally, the UDC supports being called from a job. Because the SHUTDOWN command is a restricted, operator-only command, it must be allowed for use in a job.