ARAP scripts execute sequentially line by line from the start to end of a script file except as controlled by the script flow control commands listed below. A script ends automatically when it reaches the end the script file or a return or end command is executed.  

script

Syntax: script filename.dtl <parameter1> <parameter2>
Syntax: filename <parameter1> <parameter2>

This command runs a "child" script named "filename.dtl". The script file must be either in the current directory (the directory where ARAP is installed) or in the directory specified in the General Settings. Up to 50 parameters can be passed to a "child" script - see the Parameter Variables. When the "child" script finishes, the "parent" script continues running on the next line. If the script file is not found a fatal error is generated and the script aborts. Note that an easier way to run a script is to reference it by name as the first parameter of a line without the ".dtl" part. For example, "script test.dtl" just becomes "test".

Script names are not case-sensitive, however the preferred convention is that script names are in lower case. Up to 20 nested scripts can be active at any given time, so the calling script and up to 19 sub-scripts. Note that a script can run a copy of itself (recursion) - care must be taken not to create a recursion loop.

pause

Syntax: pause

This command causes the execution of a script to be paused. A dialog box is presented to the user with the option to either continue (Continue button) or abort (Abort button) the script (even if executed within a sub-script).

end

Syntax: end

This command causes the execution of a script to be stopped (even if it is executed from within a sub-script). If the last line of a script is run without an end command, execution stops unless the current script was run from a parent script in which case execution continues at the next line of the parent.

return

Syntax: return

This command causes the execution of a sub-script to be stopped, but execution continues in the parent script at the next line. If a sub-script executes the last line without an end command, it acts as if this command was run.

label

Syntax: label linelabel
Syntax: linelabel:

This command "labels" the current line as "linelabel". Labels are used by the "jump" command or one of the several "if" type commands. Note that an easier way to set a label is to reference it by name as the first parameter of a line followed by a ":" character. For example, "label label5" just becomes "label5:". Each script can contain up to 200 labels. Two labels in the same script with the same name cause a fatal error to occur. Label names are local to the current script and are not case-sensitive.

jump

Syntax: jump label

This command causes the script execution to jump to a new point ("label") in the script as set by the label command. If the label is not found a fatal error is generated and the script aborts. The location of the next line in the script is saved in case a jumpback command is later used.

if

Syntax: if $variable1 = $variable2 jump label

Syntax: if $variable1 <> $variable2 jump label

Syntax: if $variable1 > $variable2 jump label

Syntax: if $variable1 < $variable2 jump label

Syntax: if $variable1 <= $variable2 jump label

Syntax: if $variable1 >= $variable2 jump label

This command causes the script execution to jump to a new point ("label") in the script, as set by the label command, if the numerical test of the two specified values is "true". If the label is not found a fatal error is generated and the script aborts. The location of the next line in the script is saved in case a jumpback command is later used.

iftrue

Syntax: iftrue $variable jump label

This command causes the script execution to jump to a new point ("label") in the script, as set by the label command, if the specified "variable" is "true". Note that valid "true" values include "true", "yes" and "on" (not case-sensitive). If the label is not found a fatal error is generated and the script aborts. The location of the next line in the script is saved in case a jumpback command is later used.

iffalse

Syntax: iffalse $variable jump label

This command causes the script execution to jump to a new point ("label") in the script, as set by the label command, if the specified "variable" is false. Note that valid "false" values include "false", "no" and "off" (not case-sensitive). If the label is not found a fatal error is generated and the script aborts. The location of the next line in the script is saved in case a jumpback command is later used.

ifeq

Syntax: ifeq $variable1 $variable2 jump label

This command causes the script execution to jump to a new point ("label") in the script, as set by the label command, if the two specified variables are equal (by comparing the strings). The string comparison is not case-sensitive. If the label is not found a fatal error is generated and the script aborts. The location of the next line in the script is saved in case a jumpback command is later used.

ifnoteq

Syntax: ifnoteq $variable1 $variable2 jump label

This command causes the script execution to jump to a new point ("label") in the script, as set by the label command, if the two specified variables are not equal (by comparing the strings). The string comparison is not case-sensitive. If the label is not found a fatal error is generated and the script aborts. The location of the next line in the script is saved in case a jumpback command is later used.

jumpback

Syntax: jumpback

This command, in concert with a previous "jump" or "if" command (which saves the location just after a jump), creates a subroutine within a single script. Script execution jumps back to just after the most recent "jump" (within the same script), or to the location set by the savejumpback command. Note that there is only a single save jump back location (not a stack), so to implement multiple subroutines within the same script, use the savejumpback and restorejumpback commands. If the jump back location is invalid a fatal error is generated and the script aborts.

savejumpback

Syntax: savejumpback variable

This command saves the current jump back line number to the variable "variable". It is used with the restorejumpback command to allow for more than one subroutine to be active at a time within the same script. An example usage is shown below:

jump SUBROUTINE

... subroutine returns here ...

SUBROUTINE:

       savejumpback JB

       ... subroutine lines ...

       restorejumpback $JB

       jumpback

restorejumpback

Syntax: restorejumpback jumpbackline

This command restores the jump back line number to "jumpbackline". It must be used after an earlier savejumpback command and before a jumpback command. See example above.