Workbench 0.18 User Guide

Guest Tools

Tool Usage Profile Arguments

To integrate tools in the Toolbox with data from the Object Explorer, Workbench needs to supply parameters when a tool is executed.  Currently, Workbench relies on the use of command line parameters, and provides a range of argument variable types.  An argument variable is defined by a percent sign (%) followed by a number, e.g. %1, %2, %3, etc.  At execution time, Workbench replaces these variables with those that are defined in the Variables fields.

Screenshot of tool profile argument dropdown

If you drop a tool onto a single file data object on the workpad, Workbench will typically pass the specification of that file (path and name) to the tool. If a tool is dropped onto a data set, Workbench must pass the list of files in the data set to the tool.

Similarly, a tool may need an output file specification, and this needs to be passed to the tool at execution time.

Tools differ in their requirements. For example, a tool to merge multiple trace files may expect the list of input files to be separated by spaces, whereas another tool may expect a list delimited with commas.

Workbench supports a wide variety of arguments.

Dynamic Argument

A dynamic argument is a value that the user will supply when the Tool profile is executed. Workbench will display a form that allows you to specify the dynamic argument values when you execute the Tool profile. The values you supply will be injected into the profile command.

Dynamic Output File:

A dynamic output file argument is a value that the user will supply when the tool profile is executed. Workbench will display a form that allows you to specify the dynamic output file argument value when you execute the tool profile. The value you supply will be used as the output file specification (path and name) for the tool operation (if your tool creates output).

Input File

Input file is the most common tool profile argument and is simply the specification (path and name) of the file onto which you have dropped a tool.

Screenshot showing a quoted variable

It's a good idea to enclose an input file variable in double quotes, as above.  This ensures that a file specification that include space characters is correctly passed to the tool.

Input File List

The input file lists are used when you want to pass a list of files as a parameter to your Tool profile command. For example, if you use this argument in your Tool profile and then drop the tool onto a data set or directory set tile, Workbench will construct a list of all the files in the set and pass that list to the tool.  If the set of files includes files types that are not supported by the tool, Workbench will exclude those files from the list.

The character used to separate each entry of the list is set using the Delimiter dropdown.  A comma delimited list would look like this:

fileA,fileB,fileC,fileD

Input File Encapsulated List

An input file encapsulated list works in the same way as the input file list with a single difference.  The entries in an encapsulated list are surrounded by quotes:

“fileA”,”fileB”,”fileC”,”fileD”

This is an important option because a list of files may include space characters in the file specification of each file, and programs (tools) will usually need these to be surrounded by quotes.

Static Output File

The static output file argument is used to allow Workbench to automatically handle your output files. When you specify a static output file (you will need to populate the Static Output Extension field on the profile form) Workbench will take care of naming and placing the output file for you. If you have the ‘Auto position operation results in Object Explorer’ option enabled, Workbench will add the output of the operation to the Object Explorer for you.

To enable the automatic insertion of output files into the Object Explorer tree, go to Tools -> Options -> Environment and check the entry Auto position operation results in Object Explorer.