Name

Description

HRESULT
ReadVariable([in] LONG variableType,
             [in] BSTR name,
             [in] LONG options,
             [in] ICallback* jobDoneCallback,
             [out,retval] IJob** readJob);

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

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.

jobDoneCallback

An ICallback instance that will be called when the operation is complete.

readJob

Returns an IJob object that describes the state of this asynchronous operation.

Return Value

Remarks

• You must call VM::LoginInGuest() before calling this function to read a VIX_GUEST_ENVIRONMENT_VARIABLE value. You do not have to call VM::LoginInGuest() to use this function to read a VIX_VM_GUEST_VARIABLE or a VIX_VM_CONFIG_RUNTIME_ONLY value.
• The result of the call is in the property VIX_PROPERTY_JOB_RESULT_VM_VARIABLE_STRING on the returning jobHandle.

Side Effects

Requirements

Example

Dim lib
Dim host
Dim job
Dim vm
Dim results

Set lib = CreateObject("VixCOM.VixLib")

Set job = lib.Connect(VixCOM.Constants.VIX_API_VERSION, VixCOM.Constants.VIX_SERVICEPROVIDER_VMWARE_WORKSTATION, Empty, 0, Empty, Empty, 0, Nothing, Nothing)

' results needs to be initialized before it's used, even if it's just going to be overwritten.
Set results = Nothing

err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE), results)
If lib.ErrorIndicatesFailure(err) Then
   WScript.Echo("Error: " & lib.GetErrorText(err, empty))
   WScript.Quit
End If

Set host = results(0)

Set job = host.OpenVM("c:\Virtual Machines\vm1\win2000.vmx", Nothing)
err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE), results)
If lib.ErrorIndicatesFailure(err) Then
   WScript.Echo("Error: " & lib.GetErrorText(err, empty))
   WScript.Quit
End If

Set vm = results(0)

Set job = vm.PowerOn(VixCOM.Constants.VIX_VMPOWEROP_LAUNCH_GUI, Nothing, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
   WScript.Echo("Error: " & lib.GetErrorText(err, empty))
   WScript.Quit
End If

' Wait until VMware Tools are running within the guest, with a 300 second timeout.
Set job = vm.WaitForToolsInGuest(300, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
   ' Handle the error...
End If

Set job = vm.WriteVariable(VixCOM.Constants.VIX_VM_GUEST_VARIABLE, "myTestVariable", "newValue", 0, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
   ' Handle the error...
End If

Dim variableVal

Set job = vm.ReadVariable(VixCOM.Constants.VIX_VM_GUEST_VARIABLE, "myTestVariable", 0, Nothing)
err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_VM_VARIABLE_STRING), results)
If lib.ErrorIndicatesFailure(err) Then
   ' Handle the error...
End If
variableVal = results(0)

host.Disconnect()