VIX API Version 1.1.1 (for Workstation 6.0.1) Release Notes

Released 16-August-2007

The VIX API allows users to write scripts and programs to automate virtual machine operations. The API is high-level, easy to use, and practical for both script writers and application programmers.

The VIX API includes:

  • C API—This release of the API is available in the C language. API functions allow you to register, power on or off virtual machines, and run programs in the guest operating systems.
  • Perl API—This release also includes a simplified API available in the Perl language.
  • COM API—This release includes a COM binding for the VIX API. Developers can now use C#, Visual Basic, and VBScript clients.
  • Command-line Utility— Included with the installation is the vmrun command-line utility, based on the VIX API.

This document contains the following information:

New Features

  • VIX API error strings have been localized into Japanese. The error text returned from Vix_GetErrorText() is provided either in English or Japanese, depending on the default locale for the system on which the VIX API client is running. This change is effective only when running the VIX client against Workstation 6.0.1 or later.

Resolved Issues

  • Ten-folder limit on VixVM_AddSharedFolder() function. The VixVM_AddSharedFolder() function was limited to 10 shared folders. This problem has been corrected.

  • Wrapper library problem on Linux. When using the VIX API on Linux, the wrapper library had problems with missing symbols, which prevented clients from linking with it. This problem has been corrected.

  • Problem linking VixAllProducts.lib to a debug version of the C runtime on Windows. The VixAllProducts.lib library for Microsoft Windows did not function correctly when linked with a debug version of the C runtime libraries. This problem has been corrected.

  • VixVM_PowerOn() failed when multiple VMware products installed. The VixVM_PowerOn() function previously relied on the VMINSTALL environment variable to locate installed VMware executables. If you first installed a VMware product that supports the VIX API, then you later installed a VMware product that does not support the VIX API, VMINSTALL would point to the later installation. This problem has been corrected for the Workstation 6.0.1 release.

Known Issues

  • The FindRunningVMs() function does not return appropriately on failure. When the VIX API Perl function FindRunningVMs() succeeds, it returns VIX_OK and a host handle. However, when this function fails, it returns an empty list rather than an appropriate error message.

  • The VixVM_EnableSharedFolders() function behaves differently, depending on the power state. If you call VixVM_EnableSharedFolders() when the virtual machine is powered on, shared folders are enabled only until the next power-off or suspend operation. If you call VixVM_EnableSharedFolders() when the virtual machine is powered off, the enabled setting persists until you change it again.

  • VixHost_FindItems() does not consistently report all running virtual machines. Calling VixHost_FindItems() with the VIX_FIND_RUNNING_VMS option does not always detect all running virtual machines. The same is true for the Perl function FindRunningVMs(). To work around this issue, add a five-second delay after powering on a virtual machine.

  • RunScriptInGuest does not work with DOS batch commands (.bat or .cmd files). Instead, use RunProgramInGuest to run cmd.exe with the /c option, as shown in this example:

    vmrun -gu administrator -gp AdminPassword runProgramInGuest C:\VMs\w2k\w2k.vmx c:\windows\System32\cmd.exe "/c c:\Workarea\script.bat"

  • Unsupported shared folder functions fail silently. Microsoft Windows 95, Windows 98, and Windows ME guest operating systems do not support shared folder functions. Calls to such functions for these guests fail without returning an error code.

  • The VixVM_LoginInGuest() function fails when given an empty string as a password. This is a security feature in Windows XP guest operating systems. For more information, visit:

    To workaround this issue, create a new user account with a non-empty password, or change the password for the user account you use to authenticate for guest operating system functions.

  • Timeout range is limited to 2048 seconds. The timeoutInSeconds parameter of VixVM_WaitForTools() is limited to 2048 seconds. Larger values produce unpredictable results.

  • VixVM_ListDirectoryInGuest() failure for outdated Tools. If VMware Tools in the guest operating system is not current, VixVM_ListDirectoryInGuest() may fail with the error code E_INVALID_ARG. To correct the problem, use VixVM_InstallTools() to upgrade to the current version of VMware Tools.

  • Invoking VixVM_RunScriptInGuest() with DOS batch files. The function VixVM_RunScriptInGuest() fails when the user attempts to use cmd.exe to run a Windows batch file. This problem is seen when the interpreter parameter points to cmd.exe and the scriptText parameter points to the name of a batch file. The problem is also seen when using vmrun to execute a batch file in the guest (from a command shell on the host). For example, the following command causes vmrun to hang: vmrun runProgramInGuest C:\MyVMs\w2k\w2k.vmx C:\windows\System32\cmd.exe C:\Workarea\script.bat To execute a batch script in the guest operating system, use the /c option with cmd.exe. The /c option should precede the name of the batch file. For example: vmrun runProgramInGuest C:\MyVMs\w2k\w2k.vmx C:\windows\System32\cmd.exe "/c C:\Workarea\script.bat"

  • Issue with vmrun, virtual machine power-on, and snapshot. The vmrun utility does not power on a virtual machine if you revert to a snapshot that was taken while the virtual machine was powered on. Instead, the virtual machine reverts to the snapshot state but remains suspended.

  • Issue with background resume feature. If the background resume feature is enabled for a virtual machine, Vix might report too early that the resume operation is complete. To work around this problem, disable the background resume feature (assuming it has been enabled—by default, background resume is disabled).

  • The vmrun utility can’t distinguish between snapshots with the same name. The Vix libraries identify snapshots with unique handles, but vmrun identifies snapshots by user-visible name, which need not be unique. If you give the same name to two snapshots, there is no way to identify them uniquely to vmrun.

  • Inconsistency in Folder and File Characters. The shared folder and file copy functions in the VIX API are inconsistent in the set of characters they allow in folder names. As a result, you can create a shared folder that you subsequently can’t use in a file copy function such as VixVM_CopyFileFromHostToGuest(). To work around this problem, avoid using non-alphanumeric characters in shared folder names.

  • Vix shared folder status subject to delay in Linux guests. The HGFS (host-guest file system) driver for a Linux guest caches information related to shared folders. The default caching duration is five seconds. As a consequence, Vix functions that check the status of a shared folder in the HGFS file system will see stale information for five seconds after the state of the shared folder changes. For instance, if you call VixVM_RemoveSharedFolder() to remove a shared folder, then if you immediately call VixVM_FileExistsInGuest() to test for a file in the shared folder, the file system reports that the file still exists in a subdirectory of /mnt/hgfs. To work around this issue, a client should sleep for five seconds before assuming the shared folder status is correct.

  • Microsoft Windows 95 guest operations not supported. Most guest operations, including guest file operations, getting and setting of environment variables, and running programs in the guest, will not work properly for Microsoft Windows 95 guests.

  • Wait before calling VixVM_InstallTools(). The function VixVM_InstallTools() sometimes fails to work correctly if you call it immediately after powering on a virtual machine. VixVM_InstallTools() mounts an ISO image containing the VMware Tools installer, but the guest operating system can fail to recognize the mounted image or to execute the autorun file if the guest operating system has not completed its startup process.
    To work around this problem, you should wait until the guest operating system is fully operational before calling VixVM_InstallTools().

  • VIX API CopyFileFromHostToGuest() and CopyFileFromGuestToHost() reset permission bits (KB 2318633)

  • VIX API returns undefined error code in some situations (KB 3460454)

  • VIX API does not always report failure of VixVM_CopyFileFromGuestToHost() (KB 3656116)

  • VIX API might crash if client uses an invalid host handle (KB 2416845)

Last updated: 19-April-2007 5:00 pm