Name

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

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

Requirements

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);