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 failure 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).
    Save return code in parameter Saves the return code as a new or existing parameter. Enter or select a parameter if you want the exit code saved. If the parameter does not already exist, creates it. This parameter type can be an integer, real, or string. The default is string. If this field is left empty, which is the default for simulation processes, the exit code is not saved. Simulation processes created in Isight show retval as the parameter name. This ensures that existing models have the same previous behavior.
    Find file or string

    Have wait for a file to appear after the OS command ends before moving to the next step in the process. If selected, enter a file name in the File field. The file name can contain variable substitutions, such as “{var xx},” similar to file parameters.

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

    Specify the Delay after file or string is found (s) to specify 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.
    Output found in 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.
    Output found in 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 Logs 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 stream

    Logs any messages from the standard error stream 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 stream

    Logs any messages from the standard output stream 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.
    Number of lines to log

    Limits the amount of text that is written to the job log. 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; 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 Execution Environment area, specify the following options to control some aspects of how the program runs:
    OptionDescription
    End all jobs or processes created by the command after the command executes (recommended)

    Places the command 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 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.
    X-Windows Display on UNIX

    To enable this option, enter a host name in the corresponding field. The host name can be either a domain name or an IP address.

    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.

    File name substitutions are allowed, such as {localhost} to obtain the host name of the machine from which the job was submitted.
    Execute command locally

    Executes the command using local system resources. Disable for the local system to be free to perform other work while waiting for the remote command. 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.
  6. Click Ok to save your changes and to close the OS Command Editor.