SHUTDOWN-VM (Execute shutdown in a guest system and for VM2000)

/SHUTDOWN-VM is used to execute a shutdown (without a restart) in the selected guest systems.

The shutdown can be executed for the whole VM2000 system (all guest systems and the monitor system), for all guest systems or an individual guest system (with the exception of the monitor system).

The shutdown cannot be executed in a VM's guest system while the VM is being migrated (VM Migration).

Information on command execution is provided in section "Shutdown in the guest system and of VM2000".

VM2000 operation can also be terminated (analogously to coordinated shutdown) on the SU x86 via the SE Manager, see section "Terminating the monitor system and VM2000".

   

SHUTDOWN-VM

VM-IDENTIFICATION = *CURRENT / *VM2000(...) / *VM-GUESTS / <integer 1..99> / <name 1..8>
	*VM2000(...)
		|	WAITING-TIME = *UNLIMITED / <integer 1..60> minutes
,ACTION = *SHUTDOWN(...) / *ENTER-JOB
	*SHUTDOWN(...)
		|	QUIET-TIME = <integer 0..60> minutes

VM-IDENTIFICATION =
Identification of the virtual machine for whose guest system the shutdown is to be executed.

VM-IDENTIFICATION = *CURRENT
The VM identification assigned previously by means of /BEGIN-VM-DIALOG is used.

VM-IDENTIFICATION = *VM2000(...)
The shutdown is to be coordinated and executed for the overall VM2000 system (with all guest systems). The shutdown is initiated for all guest systems. The monitor system is the last system to be shut down. All VMs are also terminated.

The coordinated shutdown for the entire VM2000 system cannot be executed while a VM is being migrated (VM Migration).

WAITING-TIME =
Determines the maximum time which is to be waited (before the monitor system is terminated) for all virtual machines to have the state INIT-ONLY or DOWN. The wait time begins with the start of the enter jobs or when shutdown processing is initiated (MODE=*END) in the guest systems. In this period the monitor system continues to operate regularly. VM2000 commands can also still be entered, see "Shutdown in the guest system and of VM2000".

The maximum wait time selected should be greater than the longest SHUTCTL wait time in the guest systems, see system parameter SHUTCTL in the “Introduction to System Administration” [2]. The guest systems can consequently be shut down before the monitor system.

WAITING-TIME = *UNLIMITED
The monitor system waits for the other guest systems to shut down for an unlimited period before it shuts down itself.

This operand value is rejected if a VM is in the IN HOLD (WAIT) status.

WAITING-TIME = <integer 1..60> minutes
Time in minutes during which the guest system remains in QUIET state before it is shut down. All guest systems (with the exception of the monitor system) are explicitly shut down after the wait time has elapsed using /DELETE-VM CHECK-VM-STATE=*NO regardless of their status.

VM-IDENTIFICATION = *VM-GUESTS
The shutdown is to be executed for all guest systems, with the exception of the monitor system, and for guest systems on VMs for which a VM Migration is currently running.

VM-IDENTIFICATION = <integer 1..99> / <name 1..8>
Identifies the virtual machine by means of a VM index or VM name.

ACTION =
Defines the method for system shutdown of a guest system.

ACTION = *SHUTDOWN(...)
The system shutdown of a guest system is implemented by VM2000 by calling shutdown processing (analogously to the BS2000 command /SHUTDOWN). The operator on the guest system is informed of this by the message NRT1201.

QUIET-TIME =
Time in minutes during which the guest system remains in QUIET status before it is shut down.

On SU /390, the VM definitions are still processed by VM2000 when shutdown takes place. For this action BCAM must still be active in the monitor system. Consequently, when the combined shutdown of VM2000 takes place (/SHUTDOWN-VM VM-ID=*VM2000... ), the QUIET-TIME=0 operand should be selected.

QUIET-TIME = 0
System shutdown is initiated immediately.

QUIET-TIME = <integer 1..60> minutes
System shutdown is executed in two steps:

1) The system is initially placed in QUIET state:

• All interactive users of the system are informed of the impending system shutdown

• Job acceptance is terminated

• New users are no longer admitted

     The guest system remains in this status for the defined QUIET-TIME.
     The operator on the guest system is informed of the length of the QUIET-TIME.

2) After the QUIET-TIME has elapsed, the final system shutdown is initiated.

ACTION = *ENTER-JOB
The system shutdown of a guest system is to be implemented by an enter job. The command file is expected in the $TSOS.SYS.VM.SHUTDOWN file in the guest system. The last action of the customer specific preparations must be the BS2000 command /SHUTDOWN MODE=*NO/*END(RESTART=*NO). The privilege OPERATING is required for the execution of /SHUTDOWN (see "Privileges of the user task in the monitor system").

 

Command return codes

(SC2)   SC1	Main code	Meaning
0 1             0 2             0 64 64 64 64 64 64 64 64 64 64 64 128	CMD0001 CMD0001 VMS2104 VMS2055 VMS2056 VMS2057 VMS2058 VMS2070 VMS2101 VMS2102 VMS2103 VMS2105 VMS4000 VMS9005 VMS3042	Command successfully executed Shutdown successfully initiated No action required VM2000 is shut down; at least one VM is in state IN HOLD (WAIT) Shutdown of guest system not acknowledged Shutdown for guest system already in progress Shutdown for VM rejected; no suitable guest system is running Shutdown of guest system rejected or acknowledged with warnings VM in state IN HOLD (WAIT) VM2000 shutdown in progress Shutdown for VM2000 rejected; monitor system unsuitable Unlimited waiting for shutdown of an unsuitable guest system not permitted /ENTER-JOB cannot be executed in the guest system VM not yet created Command could not be processed or could only be partially processed (VM-ID=*VM-GUESTS) VM being migrated

Guaranteed messages

VMS2054, VMS2055, VMS2056, VMS2057, VMS2058, VMS2070, VMS2100, VMS2104, VMS3041

Example

/shutdown-vm vm-id=*vm2000(waiting-time=*unlimited),
                          action=*shutdown(quiet-time=0) ——————————————  (1)
VMS2054 SHUTDOWN OF GUEST SYSTEM ON VM (2,SYSTEM2) INITIATED
VMS2054 SHUTDOWN OF GUEST SYSTEM ON VM (3,SYSTEM3) INITIATED
VMS2100 VM2000 SHUTDOWN INITIATED

-----------------------------------------------------------------------------------------------------------------

(1)	The VM2000 administrator initiates the coordinated shutdown of VM2000. The monitor system would wait for an unlimited time for the guest systems to shut down.

-----------------------------------------------------------------------------------------------------------------

See also the detailed "Example of coordinated shutdown of VM2000".