trun
Description
The trun macro controls the running of scripts. It can be used to start and stop both stream and string scripts, either manually by the user or automatically from within a script. Scripts can be presented to PTC ALD in two different ways: as a normal PTC ALD text stream contained in a document or as a string from one of PTC ALD strings files.
Syntax
trun tag_name:t? string number:n? exit_code:n? suspend_code:n? suspend_parameter:b? parameter:b?
|
tag_name
|
The name of a text stream in the current document, usually a .sc type tag. For example, you would start the script in the text stream Script with:
trun "Script"
|
|
string_number
|
A numbered string, usually either contained in a strings file such as stuk.3ad, suser.3ad or shuk.3ad, or defined from within a script using defstr and addstr. For example, you would start a script in string number 350 with:
trun 350
|
|
exit_code
|
Backup / exit options:
|
0
|
All levels: the script backs up all levels leaving no script at all running; this is therefore a way of exiting all scripts immediately.
|
|
–10..–1
|
Number of levels: If the first parameter is a number less than 0 the script backs up the given number of nesting levels. With a script already running, you would exit the current script and return to any previous script with this macro.
|
|
|
suspend_code
|
Wait condition:
|
+0
|
Continue with any suspended scripts. trun +0 could be assigned onto a key to restart a script without waiting for any other conditions.
|
|
+1
|
Suspend scripts until any raw keycode is received from the keyboard. If suspend_parameter has a non-zero value then wait for that specific keycode. The actual keycode received can be obtained in the script using getvar code 01156. Other than passing the result back to the script, the keypress is effectively discarded. If a suspend_parameter code is specified which can not be generated by the keyboard then the script will be suspended until it is restarted manually with a trun +0 command.
|
|
+2
|
Same as +1 except that the keycode is passed through the current keyboard map first. PTC ALD will normally pass all received keys through this map as soon as they are received. For example, to suspend the script until the Enter key is pressed use the following syntax: trun +2,13
|
|
+10
|
Suspend scripts until the system is genuinely idle. PTC ALD has an idle loop in which a running script is the first to receive attention. There may be other activities waiting that would not normally be serviced until all scripts have ended. Using this code will suspend a script until all waiting activities have been processed. This can help to ensure that all screen redraws, page re-formats, autosave etc. are complete.
|
|
+1000 >
|
Any code above 999 is considered to be a getvar code. The script will be suspended until the value of the getvar is greater than or equal to suspend_parameter. If the getvar code would normally return a string of characters (the first digit of the 5 digit code is 1 or 3) then the length of the string will be the value of the getvar. The example below would suspend a script for 5 seconds:
trun +21022,^(V210222+5)^
|
|
|
suspend_ parameter
|
Additional information for the condition (defaulting to 0), or when terminating a suspension (suspend_code is 0): return a result to the suspended script.
If a new script is started when another is suspended then the suspension will temporarily be lifted while the new nested script is running. As soon as the new script terminates, the suspended script will again be current, but still suspended.
|
|
parameter
|
The second parameter of trun, if present, is a string enclosed in double quotes:
trun 932,"I"
|
Additional Information
A script can issue its own trun macro to start another script which can then start its own script. There is no limit to the number of scripts that can be nested. Scripts do not run concurrently, but rather work like subroutines in that any script can return to the one that started it. Scripts should generally be terminated with a trun-1, allowing them to be run from within other scripts; trun 0 is best reserved for error conditions. Scripts can also be suspended until certain condition(s) are met.
Each line in a script can refer to the parameter by including the sequence %b or %s. When the script is processed %b will be replaced by the parameter itself, and %s will be replaced by both the parameter and the double quotes which surround it. Each line of a script can have no more than one replacement item. The sample script shown below takes two variable parameters:
@hello %b @hello %s
When this script is run with the trun macro (as shown below) it will execute two macros: @hello dave and @hello "dave".
trun "script","dave"
This can be a powerful feature, particularly if you have written a large number of scripts and have started running out of user-definable strings. In this case, you can often concatenate related scripts and access them by giving each one an 'option number'.
Any script which is being passed a parameter (whether it uses the parameter or not) must have each non-parameter % symbol duplicated. For example, here is a portion of script which does not take a parameter:
defstr 999,"|Scale Object\n-\n"
addstr 999,"Width }^width%-10000..10000;3i\\\%\n"
addstr 999,"Height }^height%-10000..10000;3i\\\%\n-\n"
addstr 999,"|%2..1e[OK][Cancel]"
wdb 999
.
.
.
tgnsplit (^width%),(^height%)^
Once it has been modified to take a parameter, this script would look like this:
defstr 999,"|Scale Object\n-\n"
addstr 999,"Width }^width%%-10000..10000;3i\\\%%\n"
addstr 999,"Height }^height%%-10000..10000;3i\\\%%\n-\n"
addstr 999,"|%%2..1e[OK] [Cancel]"
wdb 999
.
.
.
tgnsplit (^width%%),(^height%%)^
This script must now always be called with a parameter.
Scripts are executed one line at a time during PTC ALD idle loop. Every time PTC ALD issues an internal idle macro (when nothing else is happening PTC ALD does this periodically), one macro line is executed from the current script. This means that the rest of PTC ALD is still active between script lines. This allows scripts to be stopped at any time by pressing the escape key on your keyboard to display the macro bar on screen and then using the trun 0 macro.
Related Links