From GridLAB-D Wiki
Jump to: navigation, search

 Proposed for review  Hassayampa (Version 3.0) --Dchassin 12:58, 27 September 2012 (UTC)


script - Directive to run external commands Template:NEW30

Synopsis

script command-line;
script on_create command-line;
script on_init command-line;
script on_sync command-line;
script on_term command-line;
script export global-name;

Remarks

The script directives cause external commands to be executed. The simulation will wait for the command to exit. If the exit code is non-zero, the simulation will immediately terminate with the exit code returned by the script. The recognized exit codes are listed in the exit codes page.

Loader scripts (those without event specifications) are loaded one at a time in the order in which they are encountered by the loader.

Event scripts may be run in parallel if the threadcount is greater than 1.

export

The variable listed is exported to the shell's environment before script are executed.

Note: The syntax for accessing a variable is dependent on the shell being used to interpret the script commands. For example, DOS uses the %name% syntax whereas bash uses the $name syntax.

on_create

The script is executed after all objects have been created and before the first object is initialized.

on_init

The script is executed after all objects have been initialized and before the first sync event.

on_sync

The script is executed after each clock synchronization pass has been completed.

on_term

The script is executed when the simulation terminates.

Caveat

Platform independence
In the current implementation, scripts are interpreted by the platform's native shell command processor (e.g., DOS for MS Windows, bash for linux and Mac). This means GLM files that use scripts are not normally portable from one platform to another.
On most platforms you can specify the shell to use by preceding the command with the name of the shell, e.g.
script python my_script.py
provided you include the shell command in the your PATH environment. If platform independent scripts are desired, care should be take to only use those shell features that are platform independent. See the shell's documentation for details.
Asynchronous calls
On MS Windows platform the DOS shell interprets the start command as a request for asynchronous execution of the script. On Linux/Mac platforms, a trailing & causes asynchronous execution of the script. If a script request is repeated before the previous copy if done (e.g., on_sync), this can result in many copies of the script running concurrently and the system becoming bogged down with multiple copies of the same process.
Variable expansion
Variable names are interpreted when the script command is parsed by the GLM rather than when it is executed. It is currently not possible to update the value of a variable when the script is executed. As a result, the following directive will not work as expected
script on_sync echo ${clock}
because the value of the clock is interpreted when the directive is encountered (when clock contains the start time) and not when the script is executed. You must use the export option to export variables to scripts. The correct syntax for the above example is
script export clock;
script on_sync echo $clock; // linux/mac variable expansion syntax
or
script export clock;
script on_sync echo %clock%; // windows variable expansion syntax

See also