Configuring Execution Options

You can define options for error reporting, reattempting execution, return codes, and the execution environment.

  1. From the Utilities section of the action bar, click OS Command and drop it on the process diagram.
  2. Click OS Command , and from the context menu, click .
    The OS Command Editor appears with the Execution Options tab selected.
  3. In the Consider Execution Failed If area, determine the conditions that will indicate that the program failed.

    If you do not select any of the options, the program will be considered to succeed no matter how it exits. However, if the program cannot be found, the adapter will always fail.

    OptionDescription
    Return codes for success

    If you want to define the return codes for successful completion of the execution, you can enter multiple return codes separated by commas (for example, “1,2,5” means consider return codes of 1, 2, or 5 as success) or a range of numbers separated by a colon (for example, “0:9” means any return code from 0 to 9 inclusive indicates success.) You can combine the codes to specify multiple ranges (for example, “0:9, 21:30”). You can also use negative return codes (though few programs return them).
    There is output to the Standard Error stream

    Indicates that if the command produces any output to standard output, the run is considered a failure, and the simulation process flow is ended. This option is rarely used and is independent of whether standard output has been redirected or not. It is also independent of whether standard output is also logged.
    There is output to the Standard Output stream

    Indicates that if the command produces any output to the standard error stream, the run is considered a failure and the rest of the simulation process flow is ended. This option is typically selected for UNIX programs.
  4. In the Log Output area, specify what will be shown in the log (these options are in addition to whether standard error is redirected to a file and whether output to standard error is considered a sign that the program failed):
    OptionDescription
    Log Standard Error

    If selected, any messages the program writes to standard error will also be logged to the job log. By default, this option is selected. This option is useful in determining why the program did not run as expected.

    Log Standard Output

    If selected, any messages to standard output are also sent to the job log. Selecting this option is not recommended because many programs can produce a lot of output, and log messages are relatively expensive.
    Log at most

    If selected, the amount of text that is written to the job log can be limited. This prevents a program that writes a lot of messages to standard output or standard error from flooding the job log. Only the number of lines specified by this option are logged. If more lines are produced, only the first and last few lines are logged and all lines in the middle are discarded. The number of lines taken from the start and end of the file are each half of the value specified here, so the total number of lines logged is the given value.

    Enter a value of -1 to log all lines of text written to the job log.

    Note: Lines are logged as they are produced by the program. This option can be useful if the program writes a couple of lines and then executes for a long time. You can see the status messages in the job log before the program finishes.
  5. In the Wait for File area, use the following options to run a program that submits a job to an external system and then waits for that job to finish by looking for an output file the job writes:
    OptionDescription
    Wait for file after program finishes

    Have Automation Process Composer wait for a file to appear after the program finishes. If selected, you must enter a file name in the File field. You can enter the path name or click Browse to locate the file. The file name can contain variable substitutions, such as “{var xx},” similar to file parameters.

    Find this string in the file (optional)

    Enter the string in the file for which the program should wait. If no string is specified, the command terminates when the file is created.

    Delay after file or string is found (seconds)

    Enter the number of seconds the program will wait if the file or string is found before continuing. This allows the process to finish writing the file.
  6. In the Execution Environment area, specify the following options to control some aspects of how the program runs:
    OptionDescription
    Run command/script as Windows job or UNIX Process group (recommended)

    Specify special processing when the OSCommand times out or the job is stopped. When this option is selected, the command is placed into a Windows Job object or a UNIX process group. When the OS Command times out or is stopped, the whole Job or Process group is terminated. This is the default and recommended setting.

    If this option is not selected, the command is run as a child process of the Automation Process Composer or the 3DOrchestrate station. If the OS Command times out or stops, Java tries to end the command; but any other processes the command created are NOT stopped. This can cause a problem when running the command using Windows Batch or when using one of the UNIX shells, where all the actual programs are children of the shell, and continue to run after the OS Command adapter stops. Certain Windows programs will not run if they are inside a Windows job object. To run such a program, do not select this option.

    Note: When this option is selected, a helper program called makejob is run by the OS Command. You will see this program if you examine the list of processes running on your computer.
    Save exit code in parameter

    Enter a parameter name in the text box if you want the exit code saved. If the parameter does not already exist, Automation Process Composer creates it. This parameter type can be an integer, real, or string. The default is string. If this text box is left empty, which is the default for simulation processes, the exit code is not saved.

    Note: Simulation processes created in Isight show retval as the parameter name. This ensures that existing models have the same previous behavior.
    Set X-Windows Display on UNIX

    Select this option for UNIX X-Windows programs that fail to run because an X-Windows display is not available. The specified display must be available at run time.

    If you select this option, enter a Host Name in the corresponding text box. The host name can be either a domain name or an IP address.

    File name substitutions are allowed, such as {localhost} to obtain the host name of the machine from which the job was submitted.
    Command uses no local system resources

    Select if the OS command does not use local system resources during execution. For example, the command may remotely execute a command on another compute node and wait for the command to complete, using minimal resources on the local system while waiting. If this option is selected, the local system will be free to perform other work while waiting for the remote command.

  7. Click Ok to save your changes and to close the OS Command Editor.