Name
VMPowerOff
Description
$err = VMPowerOff($vmHandle,
$powerOffOptions);
This function powers off a virtual machine.
Parameters
- vmHandle
-
Identifies a virtual machine. Call VMOpen() to create a virtual machine handle.
- powerOffOptions
-
Must be VIX_VMPOWEROP_NORMAL or VIX_VMPOWEROP_FROM_GUEST.
Return Value
$err. The error code returned by the operation. For returned values, see Topics > Error Codes.
Remarks
- This function powers off a virtual machine. It is an asynchronous operation,
and the job will be signalled when the operation completes.
- If you call this function while the virtual machine is powered off, the
operation returns a VIX_E_VM_NOT_RUNNING error. You can safely ignore this
error.
- If you call this function while the virtual machine is suspended, the
operation returns a VIX_E_VM_NOT_RUNNING error. The virtual machine is
not powered off and remains suspended.
- The VIX_VMPOWEROP_FROM_GUEST flag will cause the function to try to power off
the guest OS. This will ensure a clean shutdown of the guest. This option
requires that the VMware Tools be installed and running in the guest.
- If VIX_VMPOWEROP_NORMAL is passed as the 'powerOffOptions' parameter, then the
virtual machine will be powered off at the hardware level. Any state of the
guest that has not been committed to disk will be lost.
Side Effects
None.
Requirements
use VMware::Vix::Simple;
use VMware::Vix::API::Constants;
since VMware Server 1.0
Example
my $err = VIX_OK;
my $hostHandle = VIX_INVALID_HANDLE;
my $vmHandle = VIX_INVALID_HANDLE;
($err, $hostHandle) = HostConnect(VIX_API_VERSION,
VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
undef, # hostName
0, # hostPort
undef, # userName
undef, # password
0, # options
VIX_INVALID_HANDLE); # propertyListHandle
die "HostConnect() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;
($err, $vmHandle) = VMOpen($hostHandle,
"c:\\Virtual Machines\\vm1\\win2000.vmx");
die "VMOpen() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;
# Assume this virtual machine is already running
$err = VMPowerOff($vmHandle,
VIX_VMPOWEROP_FROM_GUEST); # powerOnOptions
die "VMPowerOff() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;