ArborX

trun

Longname: t run   Open the Documentation Legend
Released: not available 
Created: not available 
See also: tgsel run
3B2 Scripting

Summary
 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 Arbortext APP in two different ways: as a normal Arbortext APP text stream contained in a document or as a string from one of Arbortext APP's strings files.
Example (n/a)
 No example is available for this feature.

Syntax (SVNNA)
trun  tag_name:t?  string number:n?  exit_code:n?  suspend_code:n?  suspend_parameter:b?  parameter:b?
tag_name:t

The name of a Arbortext APP text stream in the current document, usually a .sc type tag. You would start the script in the text stream Script with:

 trun "Script"
string_number:

A script is started which takes commands from a numbered Arbortext APP string contained, usually, 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 no.350 with this macro:

 trun 350
exit_code:n
0  The script backs up all levels leaving no script at all running; this is therefore a way of exiting all scripts immediately.
–10..–1  If the first parameter is a number less than 0 then 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:n

This is an integer code identifying which condition to wait for:

+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 is not '0' 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 re-started manually with a 'trun +0' command.
+2  Same as '+1', except that the keycode is passed through the current keyboard map first. Arbortext APP 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  Suspended scripts until the system is genuinely idle. Arbortext APP 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,^(v21022+5)^
suspend_parameter:b

This is used to specify more information for the condition (defaulting to 0), or when terminating a suspension (suspend_code is 0), it is used to 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:b

The second parameter of trun, if present, is a string enclosed in double quotes:

 trun 932,"I"

A script can issue its own trun macro to start another script which can then start its own script. In previous versions of 3B2 nesting of scripts was limited to up to 10 levels. There is now no limit to the number of scripts that can be nested. Scripts do not run concurrently, but 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 1
 @hello %s 2

When this script is run with the trun macro 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" 1
 addstr 999,"Width }^width%-10000..10000;3i\\\%\n" 2
 addstr 999,"Height }^height%-10000..10000;3i\\\%\n-\n" 3
 addstr 999,"|%2..1e[OK] [Cancel]" 4
 wdb 999 5
 . 6
 . 7
 . 8
 tgnsplit (^width%),(^height%)^ 9

Once it has been modified to take a parameter, this script would look like this:
 defstr 999,"|Scale Object\n-\n" 1
 addstr 999,"Width }^width%%-10000..10000;3i\\\%%\n" 2
 addstr 999,"Height }^height%%-10000..10000;3i\\\%%\n-\n" 3
 addstr 999,"|%%2..1e[OK] [Cancel]" 4
 wdb 999 5
 . 6
 . 7
 . 8
 tgnsplit (^width%%),(^height%%)^ 9

This script must now always be called with a parameter. Illustrated below are dialogue boxes when called with a parameter (left) without a parameter (right). The dialogue box on the right is also more-or-less what you would get if you call a script with a parameter, but without having converted % to %%.

Scripts are executed one line at a time during Arbortext APP's idle loop. Every time Arbortext APP issues an internal idle macro (when nothing else is happening Arbortext APP does this periodically), one macro line is executed from the current script. This means that the rest of Arbortext APP 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.

Document created on 08-Feb-2003 (revision 1)