Name

Description

HRESULT
RunScriptInGuest([in] BSTR interpreter,
                 [in] BSTR scriptText,
                 [in] LONG options,
                 [in] IVixHandle* propertyList,
                 [in] ICallback* jobDoneCallback,
                 [out,retval] IJob** runJob);

This function runs a script in the guest operating system.

Parameters

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 NULL (C++), null (C#), or Nothing (VB).

jobDoneCallback

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

runJob

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

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 VM::LoginInGuest() before calling this function.
• If the options parameter is 0, this function will report completion to the IJob object when the program exits in the guest operating system. Alternatively, you can pass VixCOM.Constants.VIX_RUNPROGRAM_RETURN_IMMEDIATELY as the value of the options parameter, and this function reports completion to the IJob object as soon as the program starts in the guest.
• When the job is signaled, the following properties will be available on the returned IJob object:
  • 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 VixCOM.Constants.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 in seconds;
  • VIX_PROPERTY_JOB_RESULT_GUEST_PROGRAM_EXIT_CODE: the process exit code.
  If the option parameter is VixCOM.Constants.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

VBScript:
Dim lib
Dim host
Dim job
Dim vm
Dim result

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
   ' Handle the error...
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
   ' Handle the error...
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
   ' Handle the error...
End If

Set job = vm.WaitForToolsInGuest(300, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
   ' Handle the error...
End If

Set job = vm.LoginInGuest("vixuser", "secret", 0, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
   ' Handle the error...
End If

Dim scriptText

scriptText = "if (!open IN, ""<"", ""in.txt"") { die ""failed to open input file""};\n"
scriptText = scriptText & "if (!open OUT, "">"", ""out.txt"") { die ""failed to open output file""};\n"
scriptText = scriptText & "@input = <IN>;\n"
scriptText = scriptText & "@reverse = reverse @input;\n"
scriptText = scriptText & "print OUT @reverse;\n"

Set job = vm.RunScriptInGuest("c:\perl\perl.exe", scriptText, 0, Nothing, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
   ' Handle the error...
End If

Set results = Nothing
Set job = Nothing
Set vm = Nothing

host.Disconnect()

C#:
class Program
{

   static void Main(string[] args)  
   {
      VixCOM.VixLibClass lib = new VixCOM.VixLibClass();
      UInt64 err;
      object results = null;

      VixCOM.IJob job = lib.Connect(VixCOM.Constants.VIX_API_VERSION,
                                    VixCOM.Constants.VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
                                    null,
                                    0,
                                    null,
                                    null,
                                    0,
                                    null,
                                    null);
      err = job.Wait(new int[] { VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE },
                     ref results);
      if (lib.ErrorIndicatesFailure(err)) {
         // Handle the error... 
      }     

      VixCOM.IHost host = (VixCOM.IHost)((object[])results)[0];
      CloseVixObject(job);

      job = host.OpenVM("c:\\Virtual Machines\\vm1\\win2000.vmx", null);

      err = job.Wait(new int[] { VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE }, 
                     ref results);
      if (lib.ErrorIndicatesFailure(err)) {
         // Handle the error... 
      }     

      VixCOM.IVM2 vm = (VixCOM.IVM2)((object[])results)[0];
      CloseVixObject(job);

      job = vm.PowerOn(VixCOM.Constants.VIX_VMPOWEROP_LAUNCH_GUI, null, null);
      job.WaitWithoutResults();
      if (lib.ErrorIndicatesFailure(err))
      {
         // Handle the error... 
      }
      CloseVixObject(job);

      // Wait up to 300 seconds for tools to start
      job = vm.WaitForToolsInGuest(300, null);
      err = job.WaitWithoutResults();
      if (lib.ErrorIndicatesFailure(err))
      {
         // Handle the error... 
      }
      CloseVixObject(job);

      job = vm.LoginInGuest("vixuser", "secret", 0, null);
      err = job.WaitWithoutResults();
      if (lib.ErrorIndicatesFailure(err))
      {
         // Handle the error...
      }
      CloseVixObject(job);


      string perlScript = "";

      // Fill perlScript with desired perl script text

      job = vm.RunScriptInGuest("c:\\perl\\perl.exe", perlScript, 0, null, null);
      err = job.WaitWithoutResults();
      if (lib.ErrorIndicatesFailure(err))
      {
         // Handle the error...
      }
      CloseVixObject(job);

      CloseVixObject(vm);
     
      host.Disconnect();
   }

   static void CloseVixObject(Object vixObject)
   {
      try
      {
         ((IVixHandle2)vixObject).Close();
      }
      catch(Exception)
      {
         //Close is not supported in this version of Vix COM - Ignore
      }
   }
}



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