<@SCRIPT>
Syntax
<@SCRIPT [SCOPE=scope]>script
here</@SCRIPT>
or
<@SCRIPT EXPR=expr [SCOPE=scope]>
Description
Used for server-side execution of scripts written in JavaScript.
The tag syntax can take one of two forms, and which one you use depends on how much script you have. Functionally, the two forms are equivalent and the result of evaluating the tag is the output from the script; so, for example, <@SCRIPT EXPR="2+2"> evaluates to "4".
Usage One: <@SCRIPT [SCOPE=scopeSpec]> your script here</@SCRIPT>
This is the long form of the tag. You can use this syntax for large chunks of script where it makes sense for the script to be blocked out by begin/end tags. The script can contain other Tango tags; those tags are substituted prior to script execution. In order for the script to be able to interact with the Tango environment, there are predefined object/methods that can be called from the script. They are explained on the following page.
The optional SCOPE attribute defines the lifetime of the objects and functions declared in the script, and is similar to the scope of variables. Only two scopes are supported: LOCAL and IMMED. The default scope is LOCAL, so anything defined in one script can be referenced in another script in the same file execution. The second scope, IMMED, specifies that the execution context for the script is completely deleted immediately after running the script, and is used to ensure no name/space clashes occur between the script and other longer-lived objects.
Nesting of <@SCRIPT> blocks is not supported.
Usage Two: <@SCRIPT EXPR="your script here" [SCOPE=SCOPESPEC]>
This is a shorthand form of the tag for small script snippets. As with the long form of this tag, the script snippet can contain other Tango tags that are substituted prior to script execution.
Note:
If the script expression
attribute is supplied, then it is syntactically invalid to include the
closing </@SCRIPT> tag, and the closing tag is left
unsubstituted. Also note that all attributes to <@SCRIPT>
must be named.
Predefined Objects
The following predefined objects and methods exist in the JavaScript environment of Tango Server to allow scripts to interact with Tango in a controlled and meaningful way:
- server: object representing Tango Server.
- getVariable(name): gets Tango a variable. Using default scoping rules, returns variable value.
- getVariable(name, scope): as in the previous paragraph, but defined with scope.
- setVariable(name, value): sets a Tango variable, using default scoping rules, returns nothing.
- setVariable(name, value, scope): as in the previous paragraph, but with defined scope.
Note:
Tango variables are accessed
by value, not by reference. You must therefore use setVariable
to update Tango with any changes you make to variable values. Also,
because they are passed by value, getting large Tango arrays can
consume a lot of memory because the entire array is duplicated inside
of JavaScript.
Because Tango supports only two-dimensional arrays, it is an error to try to put a JavaScript array of more than two dimensions into a Tango variable.
For more information on the JavaScript capabilities of Tango, see the online help for JavaScript that is distributed with Tango (in the Help directory under the Tango root directory).
Examples
This example returns a value of "24".
<@SCRIPT EXPR="server.setVariable ('foo', 'bar');">
This example sets the Tango variable "foo" to the value "bar", so that a subsequent <@VAR NAME="foo"> returns "bar".
<@SCRIPT EXPR="server.getVariable('foo');">
This example is equivalent to <@VAR NAME="foo">.