Script Syntax

The quickest and simplest method of checking script syntax is to make use of the script execution graph in which syntax error in scripts are identified by an <ERROR> condition. What follows here should provide sufficient information to identify and resolve such problems. Careful adherence to the conventions and suggestions proposed in the Script Style Guide also helps to avoid most common script errors.

CommentsLines in scripts and templates which commence with the string "// " (ASCII 47 ASCII 47) are interpreted as comments by Mailtraq. Comments may appear anywhere within a script or template but must be on separate lines and must appear in column one, i.e. at the start of a new line:-

// This comment is legalSetHeader("From", // This comment is not legal AddressOf("postmaster");// This comment is not legal//This comment is legal //This comment is not legal

FunctionsTo be recognised as valid by Mailtraq, every function must have opening and closing brackets "( )" (ASCII 40 ASCII 41) and the function name must be followed immediately (no white space) by the opening bracket.

//Recognised as a functionMyFunction(arguments)//Not recognised as a functionMyFunction ( arguments )

The syntax of a function used in the Command Reference is, generally, shown as:-

FunctionName( arg1 , arg2 [, arg3 ])This example shows that FunctionName() requires two arguments, arg1 and arg2. The use of square brackets "[ ]"(ASCII 91 ASCII 93) around arg3 indicates that it is an optional argument. That is, it may be used if needed (without the square brackets when used, of course) but is not required for the function to operate.

Function ArgumentsThe arguments to a function must be separated by commas and must be quoted in the order specified by the Command Reference. Arguments generally consist of strings but can always also accept functions which themselves evaluate to strings. The SetHeader() function, for example, requires two arguments, "field" and "value" and the following two expressions are functionally identical:-

VariablesVariable names must begin with an alphabetic character and must not contain spaces (ASCII 32) nor the symbols used for operators nor the symbols used to delimit functions (left and right brackets and commas) nor the semicolon ";" (ASCII 59) which is used to delimit expressions.

Any string of valid characters which precedes an assignment operator, ":=", in a script is treated as a variable by Mailtraq. Such variables can simply be regarded as general purpose containers and do not have to be declared or typed before use. Mailtraq types the contents of variables as it evaluates them using the context of the function being evaluated as a guide. If, for example, a variable named my_var contains the string "10", Mailtraq treats that as a string when evaluating strings and as a number when evaluating numbers:-

If Mailtraq cannot evaluate the contents of a variable it returns a null value in most cases.

OperatorsMailtraq scripts use all the normal mathematical operators "+" for addition, "/" for division, etc., in scripts. The following example adds ten to two hundred in one calculation, subtracts one from three in another calculation, then divides the first result by the second result:-

calc_result := (10 + 200) / (3 - 1)

Script ExpressionsAn expression is simply something which Mailtraq can evaluate to a result, anything from a simple assignment, or an argument within a function, to a complex multiple argument function in which other functions are embedded. Script expressions are separated by a semicolon ";" (ASCII 59) which is required as a continuation character between expressions. If the semicolon is missing between two expressions, Mailtraq halts execution of the script at that point on the assumption that there are no more expressions to evaluate. The corollary is, therefore, that the last expression in a script must not have a continuation character appended otherwise Mailtraq assumes that one or more expressions are missing and generates an error. This example shows three expressions linked together by continuation characters to form a script:-

ListsA list in the Mailtraq script language consists of any number of comma separated elements. Optionally, each element may also be enclosed in quotes. If there are no commas in a string, Mailtraq defaults to using <space> (ASCII 32) and <CRLF> (ASCII 13 ASCII 10) as separators.

The function GetMailboxes(), for example, returns a list which consists of the names of all the mailboxes configured in the console. That list might look something like this:-

"postmaster, sales, marketing, john, ellen, webmaster, william"

The following expression, however, returns a <CRLF> separated list, i.e. each element of the list is placed on a new line:-

host_names := GetSystemVar(“HostAliases”) ++ “\n” ++ LOCALHOST

Mailtraq provides a number of string functions to manipulate these lists in addition to the For() loop which can be used to loop through them quickly and efficiently however care must be taken not to assume that long strings containing <space> and <CRLF> will only be indexed by their comma separators.