Script basics

USE scripts are stored in <basedir>/system/config/use, and are ASCII files that can be created with any editor. Both UNIX and Windows end-of-line formats are supported but in certain circumstances, they may be automatically converted to UNIX end-of-line format.

Statements

Each statement in a USE script must be contained on a single line. Statements consist of a keyword followed by zero or more parameters separated by whitespace. The USE Reference Guide contains documentation for each statement.

Quotes and escapes

By default, a space, tab or newline will mark the end of a word in a USE script. To include whitespace in a word (for example to create a variable with a space in it) then double quotes - " - or an escape - \ - must be used to prevent the parser from interpreting the space as an end of word marker. Unless within double quotes, to specify a literal tab or space character it must be escaped by preceding it with a backslash character - \.

Examples:

"This quoted string is treated as a single word"  
var myname = "Eddy Deegan"  
This\ is\ treated\ as\ a\ single\ word
"The character \" is used for quoting"

The following table summarises the behaviour:

Characters	Meaning
" ... "	Anything inside the quotes, except for a newline, is treated as literal text
\"	Whether within quotes or not, this is expanded to a double quote - " - character
\t	When used outside quotes, this is expanded to a TAB character
\	When used outside quotes, a space following the \ is treated as a literal character
\\	When used outside quotes, this is expanded to a backslash - \ - character

Comments

Comments in a USE script start with a # character that is either of

• the first character of a line

• the first character in a word

Comments always end at the end of the line they were started on

# This is a comment
set http_header "Content-Type: application/x-www-form-urlencoded"     # This is a comment
var usage#1 = Usage1   # The '#' in 'usage#1' does not start a comment

Currently, comments should not be used on the same line as the encrypt statement as it will consider the comment as part of the value to encrypt

Variables

Overview

USE scripts often make use of variables. Variables have a name and a value. When a variable name is encountered on any given line during the execution of the script, the name is replaced with the value before the line is executed.

To reference a variable, the name should be preceded with ${ and followed by }. For example, to access the value of a variable called username, it should be written as ${username}.

The length (in characters) of a variable can be determined by appending LENGTH to the variable name when referencing it. Thus if a variable called result has a value of success then ${result.LENGTH} will be replaced with 7.

Creation

Variables may be explicitly declared using the var statement, or may be automatically created as a consequence of actions performed in the script. Additionally, a number of variables are automatically created before a script is executed.

For a list of variables created automatically please consult the article on the var statement

Encryption

It may be desirable to conceal the value of some variables (such as passwords) rather than have them represented as plain text in a USE script. This can be accomplished via the encrypt statement.

Publishing to the user interface

Variables may be exposed in the GUI by prefixing their declaration with the word public as follows:

public var username = username
public encrypt var password = something_secret

Any variable so marked may be edited using a form in the GUI before the script is executed. If a public variable is followed by a comment on the same line, then the GUI will display that comment for reference. If there is no comment on the same line, then the line before the variable declaration is checked, and if it starts with a comment then this is used. Both variants are shown in the example below:

public var username = login_user  # Set this to your username
# Set this to your password
public var password = "<please fill this in>"

If a variable declaration has both kinds of comment associated with it then the comment on the same line as the variable declaration will be used

Named buffers

A named buffer (also termed a response buffer) contains data retrieved from an external source, such as an HTTP or ODBC request. Buffers are created with the buffer statement.

Once created, a buffer can be referenced by enclosing its name in { and } as follows:

# Example of buffer creation
buffer token = http POST "https://login.windows.net/acme/oauth2/token"

# Examples of referencing a buffer
save {token} as "extracted\token.data"
discard {token}

• Buffer names may be up to 31 characters in length

• Up to 128 buffers may exist simultaneously

• Up to 2Gb of data can be stored in any given buffer (memory permitting)

Extracting data with Parslets

Parslets are used to extract data from from the contents of a named buffer.

Please refer to the full article on parslets for more information on parslets and their use.