Ps-i 2.4 - Embedded scripts

General description

This chapter documents the ability to embed Tcl/Tk scripts into model specification files.

Embedding scripts

Tcl/Tk scripts are embedded into model specification files in snapshots by specifying values for special keys in the strings section.

Example:

strings
	key 'Tcl at start'  'tk_dialog .a  "Tcl at start" "Tcl at start" "" -1 OK'
	key 'Tcl each step'  'tk_dialog .a  "Tcl each step" "Tcl each step" "" -1 OK'
	key 'Tcl at end'  'tk_dialog .a  "Tcl at end" "Tcl at end" "" -1 OK'
end

During model load Ps-i will ask the user whether to allow embedded Tcl/Tk scripts to execute as executing scripts from unknown sources presents a security risk. Right after then it will execute "Tcl at start" script (which presents a message box in the example above). Next, each time the model is stepped, either through step command or when running continuously or until a set time, Ps-i will execute the scripts give by "Tcl each step" keyword. The script specified as "Tcl at end" is executed during cleanup just before loading a new model specification file or a snapshot. This is useful to cleanup any modifications to user interface performed by "Tcl at start" script which are no longer relevant.

Since the values of keys are enclosed in apostrophes one must escape any apostrophes with a backslash character. Also all backslashes must be escaped as well - in addition to any escaping that is part of your Tcl/Tk script. The values will continue from the first apostrophe to the last unescaped one so the scripts can be written on multiple lines.

Example:

strings
	key 'Tcl at start'   '
			set name \'hello\'
			set name2 "\\[hi\\]"
			'
end

The string value in the example above translates to the following Tcl/Tk script:

			set name 'hello'
			set name2 "[hi]"

After execution of embedded scripts Ps-i does not update its windows automatically as it does after execution of scripts loaded manually or via load_file command. This is done to improve perfomance for "Tcl each step" scripts. Hence, the author of the script must take care to refresh any windows that might be affected by the changes.

The following commands can be used to refresh Ps-i views:

reset_parameters_view

This command refresh parameters list in the main Ps-i window by retrieving current settings from Ps-i execution engine.

global time_m

This variable is monitored by field views, agent viewer and statistics viewer, When it is set, these windows will update automatically.

Related

See also About Ps-i 2.4.