 |
|
The Script Node embeds a script that you want to have executed. This can be a shell script that you use to wrap an external application, or a script in one of the supported scripting languages. Data, both files and values, can be passed to, and extracted from, the script.
To configure a Script node you need to provide the following parameters:
Name: the name for the shell script. If you are using a shell script to wrap and application, and the application will run under a Windows platform, the name should have a .bat extension, unless you have installed CygWin on your machine. For all other cases, any name is allowed.
Description: the node description will appear as tooltip when the mouse stop over the node in the Work Flow canvas.
Script Language: you need to specify the language to be used to interpret the script. The languages supported are:
UNIX Shell
DOS Batch Shell
Jython
Bean Shell (i.e., Java, not to be confused with JavaScript)
Microsoft VBScript
Microsoft JScript
With the exception of the Jython scripting language, all others are actually interpreted in a separated process invoked by means of the host operating system. Therefore with the use of the UNIX Shell or DOS Batch Shell you can virtually use any external application.
Finally, you need to actually type in the script. To do this you need to click on the button to open the Script Editor.
If everything works correctly, the application exit value will be the one returned by the script upon exit. However, if something goes wrong, one of the following reserved exit values could be returned:
| 910 | A failure occurred while retrieving the output data |
| 912 | The job has been killed before it could terminate |
| 920 | The job was set-up incorrectly, and it was not possible to start it |
| 921 | The output files and data could not be retrieved |
Additional exit values can be returned depending on the script language used. For UNIX Shell and DOS Batch Shell, possible exit codes are:
| 1001 | It was not possible to retrieve the current environment |
| 1002 | The external process failed unexpectedly |
A Jython Script can instead return one of the following exit values:
| 2001 | The Jython interpreter was not found |
| 2002 | It was not possible to assign a design variable value to a Jython variable |
| 2003 | The script could not be found |
| 2004 | It was not possible to assign to the CWD variable the full path of the script working directory |
| 2005 | The script failed to run (consult ErrLog for additional information on the cause) |
| 2006 | It was not possible to extract one or more variables from the Jython environment |
A Bean Shell Script can return one of the following exit values:
| 3001 | The Bean Shell interpreter was not found |
| 3002 | It was not possible to assign a design variable value to a Bean Shell variable |
| 3003 | The script could not be found |
| 3004 | It was not possible to assign to the CWD variable the full path of the script working directory |
| 3005 | The script failed to run (consult ErrLog for additional information on the cause) |
| 3006 | It was not possible to extract one or more variables from the Bean Shell environment |
A VBScript can return one of the following exit values:
| 4001 | The script could not be found |
| 4002 | The wrapping script could not be written to disk |
A JScript can return one of the following exit values:
| 5001 | The script could not be found |
| 5002 | The wrapping script could not be written to disk |
The Script node input can be connected to one or more nodes. The connectable nodes are different for each connector. The process input connector can only be connected to the process output connector of nodes that belong to one of the following types:
The data input connector can be connected only to nodes that belong to one of the following types:
For each node belonging to one of the last five node types (i.e., for each variable) that you connect, you must also indicate the name of the script environment variable to which you want to assign the value.The Script node output can be connected to one or more nodes, different for each connector. The process output connector can only be connected to the process input connector of nodes that belong to one of the following types:
Note
The conditions must be mutually exclusive (i.e., there can be no exit value for which two or more conditions hold true).
The data output connector can be connected only to nodes that belong to one of the following types:
For each output file, you also need to specify for which values of the exit value you want the file to be processed (see Section 4.2.7, "Conditional Expression Legal Syntax"). Only those output branches for which the exit value matches the corresponding condition will be transversed.For each output variable and buffer variable node connected, you must also indicate the name of the script environment variable from which you want to extract the value.
The following error messages can be associated with an script node:
| 102 | INVALID EXIT CONDITION(S) | The conditions for the output nodes that support the Process Flow routing are not mutually exclusive |
| 103 | MISSING SCRIPT FILE | No script has been defined |
| 126 | SCRIPT NODE NOT REACHEABLE | The Process Flow cannot be routed through the script node because an appropriate input connection is missing |
| 127 | NO EXIT PATH FOR SCRIPT NODE | The Process Flow cannot be routed past the script node because an appropriate output connection is missing |
| 134 | MISSING NAME FOR I/O VARIABLE | A name has not been assigned to one or more variables passed to, or extracted from, the script |
The Script Editor allows you to type a script to be executed. The script is responsible for correctly using the input variables and files, and for producing the required variables and files. Also, the script must exit with an exit value that is descriptive of any problem encountered (this is the value that will be used inside modeFRONTIER to determine whether output variables should be extracted from output files, transfer files should be transferred, and how the process should be routed).
Caution
For script languages other than UNIX Shell and DOS Batch Shell, the exit value must be passed back to modeFRONTIER by assigning a value to the EXIT_VALUE variable before the end of the script. If such variable is not set, the exit value is assumed to be zero. For UNIX Shell scripts the exit command must be used, whereas for DOS Batch Shell scripts the ERRORLEVEL environment variable must be set.
If a shell script is used to wrap an external application, the script must perform all the operations necessary to correctly set up the application, and must feed it the necessary input file(s) (set up within modeFRONTIER by connecting Input File nodes to the Script node).
Before executing the script, a working directory is set up for it, and all the input, support, and transfer files required (specified within modeFRONTIER by connecting Input File, Support File, and Transfer File nodes to the Script node) are copied in that directory.
If a UNIX Shell or a DOS Batch Shell is used, the script will be executed in the working directory for the script. Also, the system environment under which the script will be executed will be identical to the environment under which the Launcher has been started. In addition, the value of each variable provided as an input to the Script node will be assigned to an environment variable, having the name specified in the Script properties dialog. Furthermore, some environment variables that are design-specific will also be set. These include:
APPL_NAME: the full path name for the script being executed
APPL_OUT_ENV: the name of the file where the environment must be saved before exiting the script (see below).
APPL_PWD: the absolute path of the working directory for the script
DESIGN_ID: the ID for the design being evaluated
PROJECT_NAME: The name of the modeFRONTIER project within which the script is being run
APPL_STDOUT: The name for the file where the standard output will be redirected
APPL_STDERR: The name for the file where the standard error will be redirected
APPL_PRIORITY: The priority with which the script will be executed
ESTECO_USER: The username of the user that requested the execution. This is not necessarily the user that owns the script, because, for example, the script could be run by the Launcher on behalf of a remote user.
Warning
The environment variable names has been carefully choosen to prevent accidental shadow of user defined variables. User must take on the responsability to avoid variable name collisions.
When any other scripting language is used, the full path of the working directory for the script will be assigned to a variable in the script workspace named CWD (Current Working Directory). The script will need to use this variable to locate any input file it might need, or to create files to be used by subsequent nodes. Also, the value of each variable provided as an input to the Script node will be assigned to a variable in the script workspace, using the name specified in the Script properties dialog. Furthermore, the variables DESIGN_ID, PROJECT_NAME and ESTECO_USER will also be assigned the same values described above for a shell script.
After the script has been executed, the exit value, and possibly the value of some output variables, must be retrieved. For UNIX Shell scripts the exit value is the one passed to the exit command. For DOS Batch Shell scripts the exit value is equal to the ERRORLEVEL environment variable. When any other scripting language is used, the value of the EXIT_VALUE variable is used. If such variable is not set, the exit value is assumed to be zero.
The values for output and buffer variables connected as outputs to the Script node are extracted from workspace variables (shell enviroment variables for Shell Scripts) having the names specified in the Script properties dialog.
Caution
For UNIX Shell and DOS Batch Shell scripts, the environment is cleaned upon script termination. Thus, to enable modeFRONTIER to retrieve the environment variables set within the script, the user MUST save the content of the environment into the file indicated in the environment variable APPL_OUT_ENV before exiting the script (i.e., the shell command
env > ${APPL_OUT_ENV} [UNIX Shell]
or
set > %APPL_OUT_ENV% [DOS Batch Shell]
should precede any exit command).
The Script Editor is a simple text editor, and, through the menu and the toolbar at the top of the dialog, it allows you to perform the classic editing operations. More precisely, the menu allows you to carry out the following operations:
-> (Ctrl-N): Clears the current content of the script editor, and lets you start over.
-> (Ctrl-O): Loads a file from the file system into the script editor.
-> (Ctrl-S): Saves the current content of the script editor into an external file.
The menu instead enables you to do the following:
-> (Ctrl-X): Removes the text currently selected, putting it on the system clipboard.
-> (Ctrl-C): Copies into the system clipboard the text currently selected.
-> (Ctrl-V): Copies into the text, after the current location of the cursor, the current content of the system clipboard.
-> (Ctrl-F): Locates a string within the text.
-> (F3): Repeats the search for the last string used in a find command.
-> (Ctrl-G): Jumps to a specific line number within the text.
-> (Ctrl-Z): Cancels the last operation performed.
-> (Ctrl-Y): Re-applies the last operation that was undone.
Some of these operations can also be invoked using the buttons in the toolbar.
In the toolbar there is also an encoding selector, which allows you to change the encoding to be used to save the script. This can become useful if you introduce in the script characters that are not supported by the original encoding (e.g., accented letters or Far East characters). Of course, you must be sure that the scripting engine will be able to automatically recognize such encoding.
In addition, you can specify the convention to be used to terminate each line in the script. Here you can select either the DOS format, or the UNIX format. In the former case, each line is terminated by a CR - LF pair (carriage return - line feed); if the UNIX format is select, only a LF is indicate a line termination. Specifying the correct line termination is especially important for DOS operation, because UNIX-terminated text files could be interpreted incorrectly.
