SHUTDOWN

Read syntax diagramSkip visual syntax diagram SHUTDOWN SYSTEM sysname1WITHINintervalBYtimeIMMEDiateREIPLrdevOptions23WAITcodeNOCKPTCANCEL
Options
Read syntax diagramSkip visual syntax diagramOFfsetnnnnnnnnEXtentnMDiskuseridvdevMOdulefilenameORiginhexlocIplparmstext?
Notes:
  • 1 The default interval for the entire z/VM system shutdown is calculated by adding the system-default shutdown-signal timeout interval to the CP shutdown interval.
  • 2 The Options can be specified in any order except for IPLPARMS, which must be the last option of the command.
  • 3 If MDISK, EXTENT, MODULE OFFSET, ORIGIN, or IPLPARMS are not specified, their values default to the same values that the system is currently using. Their values do not default to the values that were written to the rdev volume by the SALIPL utility.

Authorization

Privilege Class: A

Purpose

Use SHUTDOWN to complete the following tasks:
  • Systematically end all system function.
  • Checkpoint the system for an eventual warm start.

Optionally, SHUTDOWN does an automatic warm start of the current or specified CP module.

Operands

SYSTEM sysname
specifies the name of the system that is to be shut down. The sysname must be the name of the system on which the command is issued.

The SHUTDOWN command shuts down only the system on which the command is issued. Specifying the system name serves as a check to verify that the intended system is being shut down (you cannot shut down system B from system A.

The system configuration file can be defined to require the SYSTEM to be specified on the SHUTDOWN command (see the FEATURES Statement in z/VM®: CP Planning and Administration). This might be preferred in large data centers with multiple operator consoles to help prevent accidentally shutting down the wrong system.

WITHIN interval
specifies a time interval for the entire z/VM system shutdown.

The interval specifies a number of seconds in the range 1 - 65535.

If the interval is greater than the CP shutdown interval, CP immediately sends a shutdown signal to enabled guests and delays the start of the CP shutdown. The start of the CP shutdown is delayed until either of the following events occurs:
  • All signaled guests indicate that they shut down.
  • The shutdown-signal timeout interval elapses.

See usage notes 10, 11, and 12.

BY time
specifies a time-of-day target for the entire z/VM system shutdown.

The time can be specified as hh:mm or hh:mm:ss. The interval from the time of day that the command is entered until the specified time-of-day must be in the range 1 - 65535 seconds.

The start of the CP shutdown is delayed until one of the following events occurs:
  • All signaled guests indicate that they shut down.
  • The shutdown-signal timeout interval elapses.
  • The specified time of day (minus the amount of time that is reserved for a CP shutdown) is reached.

See usage notes 10, 11, and 12.

IMMEDiate
shuts down the entire z/VM system immediately without sending shutdown signals to enabled users, even if a previous SHUTDOWN command is pending. If a previous SHUTDOWN command is pending, its operands are not used and must be specified with IMMEDIATE on the new command if they are required. See usage note 10.
REIPL
specifies that the system is to be restarted immediately after the SHUTDOWN command completes.
rdev
identifies the real device to be IPLed when the system is restarted. If rdev is not specified, the system will REIPL from the rdev that was used for the last IPL or SHUTDOWN REIPL.
Note: If you specify rdev, you cannot specify MDISK.
WAIT code
causes a disabled wait state PSW to be loaded after shutdown. The code in the PSW is a hexadecimal number between 1 and FFFF.
NOCKPT
will suppress taking a checkpoint and load a disabled PSW of 9027 after the following message is displayed: 
HCP9027W  SYSTEM TERMINATION COMPLETE WITHOUT CHECKPOINT
CANCEL
causes a scheduled shutdown to be terminated. Any guests that received termination signals when the original SHUTDOWN command was issued continue to process those signals.

Options

MDisk userid vdev
specifies the owning user ID and virtual device number of the minidisk that contains the CP module.
EXtent n
specifies which minidisk extent on a CP-formatted volume contains the module to be loaded. The variable n is a single decimal number in the range 1 - 9. 1 refers to the first extent formatted as PARM, while 9 refers to the ninth such extent.
MOdule filename
specifies the file name of the module that SHUTDOWN is to load. The file type of the module must be MODULE.
OFfset nnnnnnnn
specifies the offset from the beginning of the disk (identified by rdev) at which the CMS-formatted minidisk that contains the module resides. You can specify up to 8 digits for OFFSET. For CKD and ECKD DASD, the offset is specified as the number of cylinders from the beginning of the disk. For FBA DASD, the offset is specified as the number of blocks from the beginning of the disk.
ORigin hexloc
specifies the address at which SHUTDOWN loads the module. This option is ignored by SHUTDOWN if the module that is being loaded was not generated with the RLDSAVE option. In this case, the module is loaded into storage at the location at which the module was generated.

When loading CP, the ORIGIN option is accepted, but CP relocates itself to location X'2000'.

Iplparms
specifies information that is to be passed to the loaded program by SHUTDOWN.
text/?
specifies information that is to be passed to the loaded program by SHUTDOWN. The information replaces all currently specified IPL parameters.
Note: When you enter text on the command line, IPLPARMS must be the last option that you specify. The format of the IPL parameters depends entirely on the options that are supported by the loaded program. For a list of IPL parameters supported by CP, see Passing IPL Parameters in z/VM: System Operation.
?
causes SHUTDOWN to prompt the operator for up to three lines of data to be read from the console. A null entry can be used to signify that all parameters are entered.

SHUTDOWN command processing accepts a "?" or a "? " (a "?" followed by a blank) as valid arguments to initiate the prompting sequence for the IPL parameters. All other arguments are assumed to be IPL parameters and do not initiate the prompting sequence.

Usage Notes

  1. Because SHUTDOWN stops all virtual machine operations, consider warning all users of an impending shutdown as early as possible so that they can quiesce their systems in an orderly manner.

    You can use the SET LOGMSG, MESSAGE, and WARNING commands to inform the affected users.

    Note: CMS file pool servers shut down automatically without operator intervention unless a server is explicitly disabled from receiving a shutdown signal from CP. For more information, see Startup Parameter Descriptions in z/VM: CMS File Pool Planning, Administration, and Operation.
  2. Specifying SHUTDOWN with no operands causes the system to come to an orderly termination. When the termination completes, CP enters a disabled wait state.
  3. SHUTDOWN terminates all outstanding Concurrent Copy (CONCOPY) sessions, and disbands the path groups of all DASD if CP is running in a native machine.
  4. If REIPL is specified but rdev is omitted, the current system residence device is re-IPLed.
  5. When REIPL is specified, CP attempts to do an automatic warm start. If the automatic warm start is to succeed:
    1. It must have its warm start cylinders and checkpoint cylinders defined in the same location that the current system does.
    2. The new CP module must contain the same versions of control blocks that are used by the checkpoint or warm start process, such as HCPCKIBK, HCPCKPBK, HCPPFXPG, HCPSYSCM, HCPRSPBK, HCPSPFBK, and HCPSPMBK.
    3. The new CP module must contain the same version of the checkpoint (HCPCKP or HCPCKS) and warm start (HCPWRM or HCPWRS) modules.
    4. Any CP system volumes that are shared between the old and the new system must have the same position in the CP_Owned statement in the system configuration file.

    Otherwise, the automatic warm start might fail and a hardware IPL with a FORCE start must be completed.

  6. When REIPL is specified, CP uses the parm disk location from the previous IPL. If the parm disk was moved by using CPFMTXA or ICKDSF, CP might fail to find the CPLOAD module and issue message HCP6739E. Or CP might find the old CPLOAD module on the previous parm disk. Use the EXTENT option of the SHUTDOWN command to force CP to find the parm disk at its new location, or use the OFFSET option to specify the new location of the parm disk. It is recommended to move the parm disk only shortly before a planned REIPL.
  7. When a SHUTDOWN is issued, the trace data for all active DEFERIO traces are not written.
  8. All IPL parameters that are used with the IPLPARMS option remain in effect until they are changed with a subsequent SHUTDOWN REIPL command that specifies the IPLPARMS parameter, or the CP nucleus is shut down, or a SET IPLPARMS is issued.
  9. If the REIPL option is used, some I/O subsystem features might not be available if the system that is brought up on the re-IPL supports a superset of the features that are supported by the system that was shut down. A full I/O reset is necessary to support all the features. A full I/O reset can be completed only by using the Load function on the processor's hardware console. For example, the Parallel Access Volumes feature of an IBM® DASD Subsystem might not be available on re-IPL if the system that was shut down did not support that feature.
  10. A user is enabled for signals only when a guest operating system is running in the virtual machine and is enabled to receive these signals.
  11. If the WITHIN, BY, or IMMEDIATE operand is not specified on the SHUTDOWN command, and the system-default shutdown-signal timeout interval is greater than 0, the following occurs:
    • CP sends a shutdown signal to enabled users.
    • The start of the CP shutdown is delayed. The delay gives guest systems an opportunity to do their own shutdown processing. The CP shutdown is delayed until the shutdown-signal timeout interval elapses or all signaled guests shut down, whichever occurs first.

    If the WITHIN, BY, or IMMEDIATE operand is not specified on the SHUTDOWN command and the system-default shutdown-signal timeout interval is 0, shutdown signals are suppressed and the CP shutdown begins immediately.

    Use caution when you specify the WITHIN, BY, or IMMEDIATE operand on the SHUTDOWN command. The resulting interval might not provide guests with enough time to complete an orderly shutdown.

    The WITHIN, BY, and IMMEDIATE operands specify the time interval for the entire z/VM system shutdown. The shutdown-signal timeout interval, which provides time for guests to shut down, is the difference between the entire z/VM system shutdown interval and the CP shutdown interval. When you specify the WITHIN or BY operand, the shutdown-signal timeout interval might not provide guests with enough time to complete an orderly shutdown. When you specify the IMMEDIATE operand, the shutdown-signal timeout interval does not provide guests with enough time to complete an orderly shutdown.

    If the interval that you specify with the WITHIN or BY operand is equal to the CP shutdown interval, shutdown signals are suppressed and the CP shutdown begins immediately.

    For examples of the interaction between the SHUTDOWN command timing operands, the CP shutdown interval, and the system-default shutdown-signal timeout interval, see Examples.

    Tip:
    • The system-default shutdown-signal timeout interval is specified by the SET SIGNAL SHUTDOWNTIME system configuration statement or command. For more information, see SET SIGNAL.
    • The CP shutdown interval is specified by the SET SHUTDOWNTIME system configuration statement or command. For more information, see SET SHUTDOWNTIME.
  12. A user might issue the SET SHUTSIGNAL OFF command to temporarily make shutdown signals unavailable. The QUERY SIGNALS command can be used to display the signal status of a specified user or all users.
  13. After the SHUTDOWN command is initiated successfully, this message is sent to the primary system operator: 
     
HCP2116I SHUTDOWN initiated at yyyy-mm-dd hh:mm:ss by userid
  14. After the SHUTDOWN CANCEL command is issued, this message is sent to the primary system operator: 
     
HCP2117I SHUTDOWN CANCEL issued at yyyy-mm-dd hh:mm:ss by userid
  15. Users who receive the shutdown signal and need more information about the system shutdown can issue QUERY SHUTDOWN STATUS to get information about the current shutdown.

Responses

Response 1: 
System shutdown may be delayed for up to interval seconds
is displayed when the command is accepted and some guests require time to shut down. If a user other than the primary system operator issues the SHUTDOWN command, this response is sent to both the command issuer and the primary system operator.
Response 2: 
SYSTEM SHUTDOWN STARTED
is displayed when the command is accepted and termination processing is in progress. If a Class A user other than the primary system operator issues the SHUTDOWN command, this response is sent to both the command issuer and the primary system operator.
Response 3: 
STARTING SYSTEM SHUTDOWN STEP name - description
is displayed for each step of the shutdown process as it proceeds. Each message identifies the name of the step and a description of its function. On a 3270 terminal, these messages are displayed on the first line of the screen, always showing the last step that was initiated. On the system console (SYSC) device, the messages are displayed one after another in line mode.

Examples

  1. In the following example, a guest is not provided their time to process signals because the duration is not long enough. 
    SET SHUTDOWNTIME 70
SET SIGNAL SHUTDOWNtime 30
SHUTDOWN WITHIN 90

    Guests get only 20 seconds to respond to shutdown signals because CP requires 70 of the 90 seconds for CP shutdown.

  2. In this example, assume that the time is exactly 11:58. The SHUTDOWN command's BY operand specifies a time of 12:00, which provides 120 seconds to process a shutdown. 
    SET SHUTDOWNTIME 70
SET SIGNAL SHUTDOWNtime 30
SHUTDOWN BY 12:00

    Guests get 50 seconds to respond to shutdown signals because CP needs only 70 of the 120 seconds for the CP shutdown.

Messages

  • HCP002E Invalid operand - operand
  • HCP005E Invalid hexdata - operand
  • HCP006E Invalid device type - rdev
  • HCP040E Device {rdev|vdev|ldev} does not exist
  • HCP046E DASD rdev offline
  • HCP052E Error in CP directory
  • HCP053E userid not in CP directory
  • HCP126E DASD rdev error reading volid
  • HCP128E DASD rdev error reading allocation record
  • HCP160E hexloc exceeds the storage size
  • HCP160E Hexloc hexloc exceed storage
  • HCP959I sysname SYSTEM TERMINATION IN PROGRESS ON yyyy-mm-dd
  • HCP961W SYSTEM SHUTDOWN COMPLETE FOR sysname ON yyyy-mm-dd
  • HCP962I VM SHUTDOWN COMPLETED IN duration SEC
  • HCP965E The IPLPARMS option is not allowed when this command is executed remotely with the AT command.
  • HCP2116I SHUTDOWN initiated at yyyy-mm-dd hh:mm:ss by userid
  • HCP2117I SHUTDOWN CANCEL issued at yyyy-mm-dd hh:mm:ss by userid
  • HCP6014I command cancelled at user request.
  • HCP6015E command cancelled because of console read error.
  • HCP6016E System shutdown is already in progress
  • HCP6017E System shutdown is not in progress
  • HCP6019E Guests may not have time to shut down because VM SHUTDOWN requires duration seconds
  • HCP6020E Guests do not have time to shut down because VM SHUTDOWN requires duration seconds
  • HCP6021E Required SYSTEM operand missing on SHUTDOWN command; command rejected
  • HCP6022E Incorrect value specified for SYSTEM - sysname
  • HCP6028E Scheduled system shutdown has already begun.
  • HCP6425I {CP TRACE TABLE RECORDING|TRACEID traceid} DEFERIO TRACE DATA WILL NOT BE WRITTEN.
  • HCP6704E Missing token at end of line
  • HCP6723E Requested parm disk not found in allocation map.
  • HCP6739E filename MODULE not found
  • HCP6881E userid vdev is not in CP directory.
  • HCP6882E userid vdev is not a minidisk.
  • HCP6883E userid vdev not accessible -- volume volid not mounted.
  • HCP6884E Unable to access re-IPL minidisk because no free access slot is available.
  • HCP6884E Unable to access re-IPL minidisk because of an I/O error.
  • HCP6884E Unable to access re-IPL minidisk because the disk is not CMS formatted.
  • HCP9015W SYSTEM TERMINATION FAILURE; MACHINE MALFUNCTION
  • HCP9022W SYSTEM LOAD FAILURE; FATAL I/O ERROR
  • HCP9023W SYSTEM TERMINATION FAILURE; MULTIPLE INCIDENTS
  • HCP9025W SYSTEM TERMINATION COMPLETE, ENTERING WAIT STATE
  • HCP9027W SYSTEM TERMINATION COMPLETE WITHOUT CHECKPOINT
  • HCP9035E LOAD ORIGIN address of hexloc is not valid.
  • HCP9275I SYSTEM TERMINATION IN PROGRESS; RESTART IGNORED
  • HCP9276W SYSTEM TERMINATION FAILURE; PROGRAM ERROR
  • HCP9277I SYSTEM TERMINATION COMPLETE, ATTEMPTING RESTARTyyyy-mm-dd SYSTEM sysname