# Name

VixVM_RunScriptInGuest

# Description

    VixHandle
    VixVM_RunScriptInGuest(VixHandle vmHandle,
                           const char *interpreter,
                           const char *scriptText,
                           VixRunProgramOptions options,
                           VixHandle propertyListHandle,
                           VixEventProc *callbackProc,
                           void *clientData);

This function runs a script in the guest operating system.

# Parameters

vmHandle
  Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.
interpreter
  The path to the script interpreter, or NULL to use cmd.exe as the interpreter on Windows.
scriptText
  The text of the script.
options
  Run options for the program. See the remarks below.
propertyListHandle
  Must be VIX_INVALID_HANDLE.
callbackProc
  A callback function that will be invoked when the operation is complete.
clientData
  A parameter that will be passed to the callbackProc function.

# Return Value

VixHandle. A job handle that describes the state of this asynchronous operation.

# Remarks

- This function runs the script in the guest operating system.
- The current working directory for the script executed in the guest is not defined. Absolute paths should be used for files in the guest, including the path to the interpreter, and any files referenced in the script text.
- You must call VixVM_LoginInGuest() before calling this function.
- If the options parameter is 0, this function will report completion to the job handle when the program exits in the guest operating system. Alternatively, you can pass VIX_RUNPROGRAM_RETURN_IMMEDIATELY as the value of the options parameter, and this function reports completion to the job handle as soon as the program starts in the guest.
- When the job is signaled, the following properties will be available on the returned job handle:
  - VIX_PROPERTY_JOB_RESULT_PROCESS_ID: the process id; however, if the guest has an older version of Tools (those released with Workstation 6 and earlier) and the VIX_RUNPROGRAM_RETURN_IMMEDIATELY flag is used, then the process ID will not be returned from the guest and this property will not be set on the job handle, so attempting to access this property will result in VIX_E_UNRECOGNIZED_PROPERTY being returned;
  - VIX_PROPERTY_JOB_RESULT_GUEST_PROGRAM_ELAPSED_TIME: the process elapsed time;
  - VIX_PROPERTY_JOB_RESULT_GUEST_PROGRAM_EXIT_CODE: the process exit code.
  If the option parameter is VIX_RUNPROGRAM_RETURN_IMMEDIATELY, the latter two will both be 0.
- Depending on the behavior of the guest operating system, there may be a short delay after the job completes before the process is visible in the guest operating system.
- If the total size of the specified interpreter and the script text is larger than 60536 bytes, then the error VIX_E_ARGUMENT_TOO_BIG is returned.

# Side Effects

None.

# Requirements

vix.h, since VMware Workstation 6.0
Minimum Supported Guest OS: Microsoft Windows NT Series, Linux

# Example

    VixError err = VIX_OK;
    VixHandle hostHandle = VIX_INVALID_HANDLE;
    VixHandle jobHandle = VIX_INVALID_HANDLE;
    VixHandle vmHandle = VIX_INVALID_HANDLE;

    jobHandle = VixHost_Connect(VIX_API_VERSION,
                                VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
                                NULL, // hostName
                                0, // hostPort
                                NULL, // userName
                                NULL, // password
                                0, // options
                                VIX_INVALID_HANDLE, // propertyListHandle
                                NULL, // callbackProc
                                NULL); // clientData

    err = VixJob_Wait(jobHandle,
                      VIX_PROPERTY_JOB_RESULT_HANDLE,
                      &hostHandle,
                      VIX_PROPERTY_NONE);

    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }
    Vix_ReleaseHandle(jobHandle);
    jobHandle = VixVM_Open(hostHandle,
                           "c:\\Virtual Machines\\vm1\\win2000.vmx",
                           NULL, // callbackProc
                           NULL); // clientData
    err = VixJob_Wait(jobHandle,
                      VIX_PROPERTY_JOB_RESULT_HANDLE,
                      &vmHandle,
                      VIX_PROPERTY_NONE);
    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    Vix_ReleaseHandle(jobHandle);

    jobHandle = VixVM_PowerOn(vmHandle,
                              0, // powerOnOptions
                              VIX_INVALID_HANDLE, // propertyListHandle
                              NULL, // callbackProc
                              NULL); // clientData

    err = VixJob_Wait(jobHandle,VIX_PROPERTY_NONE);
    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    Vix_ReleaseHandle(jobHandle);

    // Wait until guest is completely booted.
    jobHandle = VixVM_WaitForToolsInGuest(vmHandle,
                                          300, // timeoutInSeconds
                                          NULL, // callbackProc
                                          NULL); // clientData

    err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    Vix_ReleaseHandle(jobHandle);

    // Authenticate for guest operations.
    jobHandle = VixVM_LoginInGuest(vmHandle,
                                   "vixuser", // userName
                                   "secret", // password
                                   0, // options
                                   NULL, // callbackProc
                                   NULL); // clientData

    err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    Vix_ReleaseHandle(jobHandle);

    /*
     * Perl script to reverse the lines in a file.
     * The const declaration here, instead of at the top, makes this a cpp program.
     */
    const char *scripttext =
    "if (!open IN, \"<\", \"in.txt\") { die \"failed to open input file\"};\n"
    "if (!open OUT, \">\", \"out.txt\") { die \"failed to open output file\"};\n"
    "@input = <IN>;\n"
    "@reverse = reverse @input;\n"
    "print OUT @reverse;\n" ;
    /*
     * With alternate script, use NULL interpreter.
     */
    const char *altscript =
    "cmd.exe /k \"C:\\Program Files\\Microsoft Visual Studio\\VC\\vcvarsall.bat\" x86";

    // Run the target program.
    jobHandle = VixVM_RunScriptInGuest(vmHandle,
                                       "c:\\perl\\perl.exe",
                                       scripttext,
                                       0, // options,
                                       VIX_INVALID_HANDLE, // propertyListHandle,
                                       NULL, // callbackProc,
                                       NULL); // clientData

    err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);

    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    abort:
    Vix_ReleaseHandle(jobHandle);
    Vix_ReleaseHandle(vmHandle);
    VixHost_Disconnect(hostHandle);

Copyright (C) 2007-2018 VMware, Inc. All rights reserved.