Name

VMReadVariable

Description

($err, $value) = VMReadVariable($vmHandle,
                                $variableType,
                                $name,
                                $options);

This function reads variables from the virtual machine state. This includes the virtual machine configuration, environment variables in the guest, and VMware "Guest Variables".

Parameters

vmHandle

Identifies a virtual machine. Call VMOpen() to create a virtual machine handle.

variableType

The type of variable to read. The currently supported values are:

VIX_VM_GUEST_VARIABLE - A "Guest Variable". This is a runtime-only value; it is never stored persistently. This is the same guest variable that is exposed through the VMControl APIs, and is a simple way to pass runtime values in and out of the guest.
VIX_VM_CONFIG_RUNTIME_ONLY - The configuration state of the virtual machine. This is the .vmx file that is stored on the host. You can read this and it will return the persistent data. If you write to this, it will only be a runtime change, so changes will be lost when the VM powers off.
VIX_GUEST_ENVIRONMENT_VARIABLE - An environment variable in the guest of the VM. On a Windows NT series guest, writing these values is saved persistently so they are immediately visible to every process. On a Linux or Windows 9X guest, writing these values is not persistent so they are only visible to the VMware tools process.

name

The name of the variable.

options

must be 0.

Return Value

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

$value. The value of the variable.

Remarks

You must call VMLoginInGuest() before calling this function to read a VIX_GUEST_ENVIRONMENT_VARIABLE value. You do not have to call VMLoginInGuest() to use this function to read a VIX_VM_GUEST_VARIABLE or a VIX_VM_CONFIG_RUNTIME_ONLY value.

Side Effects

None.

Requirements

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

since Workstation 6.0

Example

This example writes and reads a variable you may define, called "myTestVariable".

my $err = VIX_OK;
my $hostHandle = VIX_INVALID_HANDLE;
my $vmHandle = VIX_INVALID_HANDLE;
my $readValue = NULL;

($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;
                       
$err = VMPowerOn($vmHandle,
                 0, # powerOnOptions
                 VIX_INVALID_HANDLE);  # propertyListHandle
die "VMPowerOn() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;


$err = VMWaitForToolsInGuest($vmHandle,
                             300); # timeoutInSeconds
die "VMWaitForToolsInGuest() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;

                               
$err = VMWriteVariable($vmHandle,
                       VIX_VM_GUEST_VARIABLE,
                       "myTestVariable",
                       "newValue",
                       0); # options
die "VMWriteVariable() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;
                              
$(err, $readValue) = VixVM_ReadVariable($vmHandle,
                                        VIX_VM_GUEST_VARIABLE,
                                        "myTestVariable",
                                        0); # options
die "VMReadVariable() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;

ReleaseHandle($vmHandle);
HostDisconnect($hostHandle);