You copied the Doc URL to your clipboard.

usecase run command

The usecase run command runs the script from the specified entry point.

The basic syntax for running a use case script from the command-line is:

usecase run script_name [options]

The options that you can use are defined in the method with the $Options$ tag of the current use case within the script. You can get more information about them using the usecase help command.

The syntax for setting options on the command line is or value. If you do not specify a value for an option explicitly, the option takes the default value defined in the script.


The examples use options as the name of the top level group of options. However, you can give a different name to the top level group of options in the use case script.

When issuing the usecase run command, rather than specifying an absolute path to a script, specify a -p or -s flag before the script name. For example, issue usecase run -p script_name [options] to run a use case script for the current platform.

If there is more than one use case defined in a single script, the entry point or main method to use when running the script must be defined. For scripts with multiple use cases the syntax is usecase run script_name entry_point [options].

If the entry point to the use case accepts positional arguments, you must specify them on the command-line when the script is run. For example, if the main method in the use case script in the current working directory is defined as follows:

$Run$ main
def main(script, filename, value):
        print("Running the main method")

The syntax to run the script is:

usecase run [options] filename value

Example 7-16 Examples

usecase run --options.enableETM=True --options.enableETM.timestamping=True
        --options.traceCapture "DSTREAM"

Runs a use case script called in the current working directory, setting the options defined for this use case.

usecase run mainOne --options.traceCapture "ETR"

Runs a use case script called in the current working directory. The entry point to this use case script is mainOne. A single option is specified after the entry point.

usecase run -s mainTwo filename.txt 100

Runs a use case script in the /Scripts/usecase/ directory in the configuration database called in the current working directory. The entry point to this use case script is mainTwo which defines two positional arguments. No options are supplied to the script.

Saving options

On the command-line, providing a long list of options might be tedious to type in every time the script is run over different connections. A solution to this is to use the built-in functionality --save-options.

For example, you can run the script usecase run script_name --option1=..., --option2=... --save-options=/path/to/options.txt where options.txt is the file in which to save the options. This saves the options to this use case script, at runtime, to options.txt.

If you do not specify an option on the command-line, its default value is saved to the specified file.

Loading options

After saving options to a file, there is a similar mechanism for loading them back in. Issuing usecase run script_name --load-options=path/to/options.txt loads the options in from options.txt and, if successful, runs the script.

You can combine options by providing options on the command-line and loading them from a file. Options from the command-line override those from a file.


The options file options.txt for contains two option values:

  • options.a=10.
  • options.b=20.

Running usecase run --load-options=options.txt results in options.a having the value 10 and options.b having the value 20, loaded from the specified file. If an option is set on the command-line, for example usecase run --options.b=99 --load-options=options.txt, it overrides those options retrieved from the file. options.a takes the value 10, but options.b takes the new value 99 provided on the command-line and not the one stored in the file. This is useful for storing a standard set of options for a single use case and modifying only those necessary at runtime.

Showing options

When running a script, the user might want to see what options are being used, especially if the options are loaded from an external file. The built-in option --show-options displays the name and value of all options being used in the script when the script is run.

Example 7-17 Examples

usecase run script_name --show-options

Prints out a list of the default options for this script.

usecase run script_name --option1=x, --option2=y --show-options

Prints out a list of options for the script, with updated values for option1 and option2.

usecase run script_name --load-options=file --show-options

Prints out a list of options taking their values from the supplied file. If an option is not defined in the loaded file, its default value is printed.