Call Executable Step

TestStand 2019 Help

Edition Date: May 2019

Part Number: 370052AA-01

»View Product Info
Download Help (Windows Only)

The Call Executable step launches an application or runs a system command. You can also use a Call Executable step to call scripting languages from TestStand.

Configuring the Step

Use the Call Executable edit tabs in the TestStand Sequence Editor and the Configure Call Executable dialog box in a TestStand User Interface to specify the executable path, arguments, and options for the Call Executable step.

When you specify the name of a non-executable file, the step launches the file using the default application associated with the extension of the file. For example, you can execute a Python or Perl script file or open a text file by specifying the non-executable file directly.

You can use expressions to specify the path to the executable and to configure the working directory. You can use an absolute path to the working directory, use the executable directory, use the sequence file directory, or use the current working directory of the TestStand application.

You can configure whether the step waits for the call to exit or waits for a specified amount of time. When a step waits for the call, you can configure the standard input passed to the call and where to store the standard output and error the call generates.

You can configure the step to stream a file as input or evaluate a string or an expression as input. You can store the output and error information in a file on the local computer or on the remote computer when you call the executable on a remote computer. TestStand overwrites the file if it already exists. Alternatively, you can use expressions to store the output and error information in TestStand variables or properties. When you store the information in a variable or property, you can use Additional Results to include the information in the report TestStand generates.

Final Status of a Call Executable Step

The final status of a Call Executable step can depend on whether the step waits for the executable to exit, as described in the following table.

Scenario Step Status
The step does not wait for the executable to exit. Done
The step waits for the executable to exit and a timeout does not occur. Done, Passed, or Failed, depending on the status action you specify in the Exit Code Status Action ring control on the Call Executable edit tab for the step.

When you set the Exit Code Status Action ring control to No Action, the step always sets the step status to Done. Otherwise, you can choose to set the step status to Failed based on the value of the exit code—less than zero, greater than zero, equal to zero, or not equal to zero. You can also choose to ignore or set the step status to Error or Failed when the executable you call returns standard error information.
The step waits for the executable to exit but a timeout occurs. Error

Step Properties

Note Note  Calling remote executables more frequently than 10 times per second can result in a timeout error.

In addition to the common custom properties, the Call Executable step type defines the following step properties:

  • Step.Result.ExitCode—The exit code the executable returns.
  • Step.Executable—The pathname of the executable to launch.
  • Step.ExecutableExpr—The expression for the pathname of the executable to launch.
  • Step.SpecifyExeByExpr—Specifies whether the step uses the Step.Executable property or the Step.ExecutableExpr property to determine the executable to launch.
  • Step.ExecutableCalled—The executable the step called.
  • Step.Arguments—The expression for the argument string the step passes to the executable.
  • Step.WaitCondition—Specifies how the step waits for the executable to exit before completing.
  • Step.TimeToWait—The number of seconds to wait for the executable to exit.
  • Step.InitialWindowState—Specifies if the executable is initially active, not active, hidden, normal, minimized, or maximized.
  • Step.TerminateOnAbort—Specifies whether to terminate the executable process when the execution terminates or aborts while waiting for the executable.
  • Step.StoreProcessHandle—When this property is True, the step stores the Microsoft Windows process handle in a variable or property.
  • Step.ProcessHandleExpr—The expression that determines the variable or property in which the step stores the Windows process handle for the executable.
  • Step.ProcessHandle—A number property in which to store the Windows process handle for the executable. Only 32-bit TestStand can use this property, which is available only to support backward compatibility. For new instances of this step type, use the Step.ProcessHandlePtr property instead because it supports 32-bit TestStand and 64-bit TestStand.
  • Step.ProcessHandlePtr&8212; Default value for the Step.ProcessHandleExpr property to store the Windows process handle for the executable.
  • Step.ExitCodeStatusAction—The condition the step evaluates for the exit code the executable returns to set the step status to Failed.
  • Step.ExitCodeErrorAction—Specifies the condition the step evaluates for the exit code the executable returns to set the step status to Error.
  • Step.RemoteSettings—Contains the following settings for calling the executable on a remote computer:
    • Enabled—TestStand calls the executable on a remote computer.
    • Host—The computer name or IP address of the remote computer. The Step.RemoteSettings.HostByExpr property specifies whether the step interprets this property value as an expression or as a string.
    • HostByExpr—When this setting is True, the step interprets the Step.RemoteSettings.Host property value as an expression. When this setting is False, the step interprets the value as a string.
    • Port—The port number the remote host server application uses.
    • Password—The password configured on the remote host server application. The Step.RemoteSettings.PasswordByExpr property specifies whether the step interprets this property value as an expression or as a string.
    • PasswordByExpr—When this setting is True, the step interprets the Step.RemoteSettings.Password property value as an expression. When this setting is False, the step interprets the value as a string.
  • Step.StdInput—Contains the following standard input settings:
    • Type—A value that specifies the method for passing standard input to the call. The valid values are 0 = No Input, 1 = String, 2 = Expression, 3 = File on Local Machine, and 4 = File on Remote Machine.
    • Source—The standard input string, expression, or file pathname. The Step.StdInput.IsExpr property specifies whether the step interprets a file pathname value in this property as an expression or as a string.
    • IsExpr—When this setting is True, the step interprets a file pathname value in the SourceStep.StdInput.Source property as an expression. When this setting is False, the step interprets the value as a string.
  • Step.StdOutput—Contains the following standard output settings:
    • Dest—A value that specifies the method for retrieving standard output from the call. The valid values are 0 = Ignore, 1 = Store in Variable/Property, 2 = Save to Local File, and 3 = Save to Remote File.
    • Expr—The standard output variable/property or file pathname. The Step.StdOutput.IsExpr property specifies whether the step interprets a file pathname value in this property as an expression or as a string.
    • IsExpr—When this setting is True, the step interprets a file pathname value in the SourceStep.StdOutput.Source property as an expression. When this setting is False, the step interprets the value as a string.
    • Text—Default property for the value of the Step.StdOutput.Expr property when the Step.StdOutput.Dest property specifies to store the standard output to a variable or property.
  • Step.WorkingDir—Contains the following working directory settings:
    • Source—A value that specifies the method to determine the working directory. The valid values are 0 = Use Current Working Directory, 1 = Use Executable Directory, 2 = Use Sequence File Directory, and 3 = Specific Directory.
    • Expr—A specific working directory. The Step.WorkingDir.IsExpr property specifies whether the step interprets this property value as an expression or as a string.
    • IsExpr—When this setting is True, the step interprets the working directory path in the SourceStep.WorkingDir.Expr property as an expression. When this setting is False, the step interprets the path as a string.
  • Step.StdError—Contains the following standard error settings:
    • Dest—A value that specifies the method for retrieving standard error from the call. The valid values are 0 = Ignore, 1 = Store in Variable/Property, 2 = Save to Local File, and 3 = Save to Remote File.
    • Expr—The standard error variable/property or file pathname. The Step.StdError.IsExpr property specifies whether the step interprets a file pathname value in this property as an expression or as a string.
    • IsExpr—When this setting is True, the step interprets a file pathname value in the SourceStep.StdError.Expr property as an expression. When this setting is False, the step interprets the value as a string.
    • Text—Default property for value of the Step.StdError.Expr property when the Step.StdError.Dest property specifies to store the standard error in a variable or property.
  • Step.Action—Specifies how TestStand responds when the standard error is not empty. The valid values are 0 = No Action, 1 = Set Step Status to Failed, 2 = Set Step Status to Error.

See Also

Built-In Step Types

Call Executable Step Type Support for 64-bit TestStand

Calling Scripting Languages from TestStand

WAS THIS ARTICLE HELPFUL?

Not Helpful