Script Basics

USE scripts, which are ASCII files you can create with any editor, are stored in <basedir>/system/config/use. Both UNIX and Microsoft 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 a 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 new line 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) you must use double quotes, ", or an escape, \, 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 summarizes the behavior:

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:

  • 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

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 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.

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 called 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.


How did we do?