Name

VMClone

Description

($err, $cloneHandle) = VMClone($vmHandle,
                               $snapshotHandle,
                               $cloneType,
                               $destConfigPathName,
                               $options,
                               $propertyListHandle);

Creates a copy of the virtual machine specified by the 'vmHandle' parameter.

Parameters

vmHandle

Identifies a virtual machine, which is referred to as the clone's parent. Call VMOpen() to create a virtual machine handle.

snapshotHandle

Optional. A snapshot belonging to the virtual machine specified by the 'vmHandle' parameter. If you pass VIX_INVALID_HANDLE, the clone will be based off the current state of the virtual machine. If you pass a valid snapshot handle, the clone will be a copy of the state of the virtual machine at the time the snapshot was taken.

cloneType

Must be either VIX_CLONETYPE_FULL or VIX_CLONETYPE_LINKED.

VIX_CLONETYPE_FULL - Creates a full, independent clone of the virtual machine.
VIX_CLONETYPE_LINKED - Creates a linked clone, which is a copy of a virtual machine that shares virtual disks with the parent virtual machine in an ongoing manner. This conserves disk space as long as the parent and clone do not change too much from their original state.

destConfigPathName

The path name of the virtual machine configuration file that will be created for the virtual machine clone produced by this operation. This should be a full absolute path name, with directory names delineated according to host system convention: \ for Windows and / for Linux.

options

Must be 0.

propertyListHandle

Must be VIX_INVALID_HANDLE.

Return Value

$err. The error code returned by the operation. For returned values, see Topics > Error Codes.

$cloneHandle. A handle to the new cloned virtual machine.

Remarks

This function is asynchronous, and uses a job object to report when the operation is complete. The function returns a handle to the job object immediately. When the job is signaled, the virtual machine handle of the resulting clone is stored as the VIX_PROPERTY_JOB_RESULT_HANDLE property of the job object.
It is not possible to create a full clone of a powered on virtual machine. You must power off or suspend a virtual machine before creating a full clone of that machine.
With a suspended virtual machine, requesting a linked clone results in error 3007 VIX_E_VM_IS_RUNNING. Suspended virtual machines retain memory state, so proceeding with a linked clone could cause loss of data.
A linked clone must be based on a virtual machine's snapshot. If a clone of this type is requested and VIX_INVALID_HANDLE is passed as the 'snapshotHandle' parameter, a new snapshot will be created by the function. This snapshot will reflect the current state of the virtual machine and will be used as a basis for the linked clone.
A linked clone must have access to the parent's virtual disks. Without such access, you cannot use a linked clone at all because its file system will likely be incomplete or corrupt.
Deleting a virtual machine that is the parent of a linked clone renders the linked clone useless.
Because a full clone does not share virtual disks with the parent virtual machine, full clones generally perform better than linked clones. However, full clones take longer to create than linked clones. Creating a full clone can take several minutes if the files involved are large.
This function is not supported when using the VIX_SERVICEPROVIDER_VMWARE_PLAYER host type.

Side Effects

If the 'cloneType' parameter is VIX_CLONETYPE_LINKED and the 'snapshotHandle' parameter is VIX_INVALID_HANDLE, then the function will create a snapshot of the current virtual machine state and use that to created the linked clone.

Requirements

use VMware::Vix::Simple;
use VMware::Vix::API::Constants;

since VMware Workstation 6.5 (not supported on VMware Server)

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\\WinXP\\WinXP.vmx");

die "VMOpen() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;

($err, $cloneHandle) = VMClone($vmHandle,
                               VIX_INVALID_HANDLE,
                               VIX_CLONETYPE_FULL,
                               "C:\\Virtual Machines\\WinXP2\\WinXP2.vmx",
                               0, # options
                               VIX_INVALID_HANDLE); # propertyListHandle

die "VMClone() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;

HostDisconnect($hostHandle);