The <Instructions> node has the
following attributes:
[Instruction Type] - The
type that determines where the instruction will be executed.
Init - The parameter will be executed
when the configuration is read.
Update - The parameter will be executed when the project is updated.
[Plug-In Name] - The user-defined
name of the generic plug-in. This name must be unique throughout the
instruction file. It defines a way for the Workbench environment to
identify this instance of the generic plug-in, because it is possible
to have several instances (several third party applications or codes)
of the third party plug-in in the process sequence.
[Executable Path] - The location
of the executable file with which the third-party plug-in will interact.
This can be either the full path or the relative path of the executable
with respect to the Working Directory for the instruction file.
[Error File] - A file used to communicate that the execution of the
external application was not successful. The error file must be removed by
the external application upon completion. If it is still present, Workbench
sends an error message and stops the update. The content of the error
message can be specified through the attribute
CheckOnError (see below). A generic message is
displayed if CheckOnError is not specified.
[Error String] - If an error
file is specified, its content will be scanned for lines that contain
the specified error string. All lines that contain the string will
be displayed as error messages (with the error string stripped from
the message). An error string named file will
cause the whole content of the file to be displayed.
[Args] - The command line
arguments passed to the executable when run.
[Script] - The Python script
to be interpreted within the Workbench framework on execution of this
instruction if the ExePath is not defined.
The Python script has access to the following variables:
container - A string that
can be passed to any command or query that requires a data container
reference parameter.
configurationObject - The
configuration object can be used to access some of the information
specified in the configuration file (for example, Working Directory
or error file). The query GetEntityProperties(Entity=configurationObject) returns a dictionary that contains all the available configuration
information.
[Interrupt Script] - An optional
Python script that is invoked when the computation is interrupted.
In Workbench terminology, the Interrupt operation closes the external
application cleanly, allowing access to data. The Interrupt operation
is visible only if the Interrupt script is
provided.
[Stop Script] - An optional
Python script that is invoked when the computation is stopped. In
Workbench terminology, the Stop operation abruptly closes the external
application, possibly resulting in the loss of data. The Stop operation
is visible only if the Stop script is provided.
The same script can be used for Stop and Interrupt. Both scripts have
access to the same information (strings container and configurationObject) that is passed
to the update script.
[Node Name] - A name given
to the XML node that defines the parsing information for a single
parameter. This name does not have to be unique but must adhere to
the naming rules for XML nodes (for example, no spaces or special
characters).
[Parameter Name] - A unique
name that represents a single parameter in the Workbench environment.
This is the name that will be used to identify the parameter throughout
the user interface.
[Type] - The general type
of the parameter. It must be one of two possible values:
Input - The parameter will
be treated as an input parameter, exactly as input parameters are
handled in the Workbench environment.
Output - The parameter will
be treated as an output or response parameter in the Workbench environment.
When chaining generic plug-ins together, each instance of the generic
plug-in can contain input and output parameters.
[Rule Name] - A name given
to the XML node that represents a single parsing rule for the parameter
defined by the rule's parent node. This name does not have to be unique,
but must adhere to the naming rules for XML nodes (for example, no
spaces or special characters). Multiple rules can (and in most cases
must) be defined for each parameter. The only restriction is that
only one rule of each type (detailed below) can exist for each parameter.
[Rule Type] - The type of
the defined rule. This can be one of the following values:
File - The file rule defines
the text file that contains the parameter value. This file can be
the full path to the file, or the relative path to the file with respect
to the Working Directory. Files containing Input type parameters must exist when reading the
configuration file.
StartLine - The line number
in the text file that the code will begin parsing. For example, if
the first 500 lines of a file contain only comments, begin parsing
the file at line 501 to avoid wasting system resources. The start
line is 1 based; therefore, a value of 0 or 1 will be treated in the
same way.
PreString - The text that
immediately precedes the actual parameter value in the file. For example,
if the file defines a parameter as "Cf = 12.555" the PreString for the parameter would
be "Cf =". This text does not need to include
any white space immediately preceding the parameter value.
DataType - The type of data
that represents the parameter. The DataType must be one of the following values.
float - The value
of the parameter is a floating point (decimal) number. This is used
for continuous variables.
double - The value
of the parameter is a double.
quantity - The value
of the parameter is a quantity containing a numeric value with units
in the form value [unit] (for example, “20 [m s^-1]”).
SkipOccurrences - The number
of PreString occurrences to skip before parsing
begins.
[Value] - The value of the
rule. No quotes are needed to delimit this value, as per the XML parsing
rules. For example, a SkipOccurrences node
would look like
<Rule Type="SkipOccurrences">3 </Rule>
where "3" is the [Value] for the rule,
signifying that 3 lines should be skipped in the file before searching
for the parameter.