![]() |
![]() |
![]() |
![]() |
The Script Control Language (SCL) is used to write scripts. Scripts define and control the test cases and input that are to be used to test the target system.
Script files consist of up to three sections which must appear in the following order if present:
The first section is the mandatory Environment section. This section defines the global attributes of the script, i.e. the script description, script mode and wait command units. It is introduced by the ENVIRONMENT command, and continues until a DEFINITIONS or CODE command is encountered.
The second section is the optional Definitions section. This section contains the variable, constant, timer and file definitions for the script. It starts with the DEFINITIONS command, and continues until the CODE command.
The last section is the mandatory Code section, which contains the main script commands. The start of this section is marked by the CODE command; it continues until the end of the script file.
Tabs, spaces and form-feeds may be incorporated into the code to align keywords and generally aid legibility; they have no other effect on compilation.
Character Representation
The text within an SCL source file falls into three broad categories:
2 Arguments to SCL commands - variable names, integer values or quoted character strings, for example.
Within character string arguments, SCL supports the use of any character with an ASCII value in the range HEX 00 to FF inclusive. However, direct specification of these characters is not always possible, for two reasons:
1 Characters with values in the ranges HEX 00 to 20 and HEX 7F to A0, and the value HEX FF, are `non-printing' characters, and cannot easily be specified in an SCL source file.
2 Two characters are reserved for use by SCL - one as a command character and the other as a control character. The characters used for these purposes cannot be used as literal characters in a character string. The default values are "~" for the command character and "^" for the control character; these values are used throughout these instructions. They can, however, be changed within the script.
To resolve these problems, SCL provides a set of `character commands', as described in Representing the Command Character and Representing the Control Character. In addition, to ensure there is no ambiguity within the source file, characters are rejected which have values in the ranges HEX 00 to 20, or HEX 7F to A0, or the value HEX FF, except as described in Characters Ignored by the Compiler.
Character commands are recognized within all SCL character strings (except for a small number of exceptions that are explicitly stated). Thus, for example, the character string "~<07>" always represents a single character (namely the character with a hexadecimal value of 7), not five characters.
Note: Single quotes may be included in character strings by using double quotes for the string delimiters, and vice versa.
Character Command Using Hexadecimal ASCII Code
All characters can be represented by hexadecimal ASCII code, character command. The command format is:
"~" is the currently defined command character and "hh" is the hexadecimal ASCII code of the required character. This form of character command is primarily intended to represent characters that cannot be represented by any of the other forms of character command.
For example, the ASCII horizontal tabulation character is represented by "~<09>" and the null character by "~<00>".
Character Command Using ASCII Mnemonic
SCL provides a number of character commands which give an easily identifiable representation of common control characters. These use the ASCII mnemonic of the control character in question. The following commands are available:
~<BEL> Bell ~<BS> Backspace ~<CR> Carriage return ~<DEL> Delete ~<ESC> Escape ~<FF> Form feed ~<HT> Horizontal tab ~<LF> Line feed ~<VT> Vertical tabControl Command
All 7-bit control characters, i.e. characters with ASCII codes in the range HEX 00 to 1F inclusive, may be represented using a control command. The control command has the following format:
"^" is the default control character and "c" is the control character specifier. The control character specifier is an ASCII graphics character with an ASCII code in the range HEX 40 (ASCII "@") to 5F (ASCII "_"). The compiler will apply the bottom 6 bits only, to generate an ASCII code in the range HEX 00 to 1F.
For example, the ASCII bell character (ASCII code HEX 07), is represented by "^G".
Representing the Command Character
The command character always introduces a command and therefore cannot be used to represent the command character itself. The command character is instead represented by a command of the following format:
"~" is the defined command character.
Representing the Control Character
The control character is always used to represent the Ctrl key, in combination with the character following it. It therefore cannot be used to represent the control character itself. The control character is instead represented by a command of the following format:
"~" is the defined command character and "^" is the defined control character.
Continuation Lines
It is not always possible to fit a script statement or command onto one line, so SCL allows you to use `continuation lines'.
An SCL statement or command may be split over two or more lines by terminating all but the last line of the statement with an ampersand or hyphen character ("&" or "-"). To avoid possible confusion with the minus character, it is recommended that the ampersand be used, and that it be separated from the preceding characters on the line by at least one space.
The only things that may follow a continuation character are space characters, tab characters and comments (see the next section).
A quoted character string is continued onto another line by closing it at the end of the line and reopening it on the next. Opening and closing quotes must match on any one line, as shown in the following example:
Note: A line that ends with an SCL command or statement terminated by "&" or "-" implies that the next line encountered will be regarded as a continuation of the original command or statement.
Comments
Scripts may incorporate comments, either on lines by themselves or embedded in statements or commands. In both cases, the comment is identified by the comment command ("!"), and terminated by the end of the line. For example:
OpenSTA Datanames
The names of many items within scripts must be defined as a OpenSTA Dataname. For example labels, variable names and subroutine names must all be OpenSTA Datanames.
A OpenSTA Dataname comprises between 1 and 16 alphanumeric, underscore or hyphen characters. The first character must be alphabetic; spaces are not allowed; two adjacent underscores or hyphens are not allowed; and neither is a trailing underscore or hyphen.
Maximum Values in Scripts
The SCL compiler and system resources impose limitations at run-time on the maximum value (number, size, level etc.) allowed for a number of items which may be specified in an SCL source file.
Including Text from Other Source Files
The INCLUDE command allows you to combine several source files into a single source file at compilation time. These included files may contain commands from any of the script sections and may span these sections. Scripts may be nested up to a depth of 10, including the main script. Care should be taken to avoid duplicating any of the script section commands (for example, ENVIRONMENT).
This command can appear at any point within the script, including before the ENVIRONMENT command.
A quoted character string which defines the name of the source file to be included. The location of the file will default to the current default directory.
Conditional Compilation of Source Code
SCL provides a number of commands to allow you to define that a section of code should be compiled only under certain circumstances. Conditional sections of code are marked with `variants'.
Variants are specified on the `-V' option, on the SCL compiler command line when you compile the source file.
Conditional compilation commands may appear at any point within the Environment, Definitions and Code sections, including before the ENTRY command and between subroutines. They cannot appear part way through a command or statement. They may be nested to a depth of 10.
A conditional compilation command which starts or ends a section of code. This may be one of the following:
The #IFDEF, #IFNDEF and #ELIF commands require the "variant" parameter, to specify the condition under which the following section of code will be compiled. The #ELSE and #ENDIF commands relate to the most recently specified variant.
A OpenSTA Dataname which identifies a section of code that is only compiled under certain conditions. The compiler processes this variant in conjunction with the `-V' option on the SCL command line.
The ENVIRONMENT Section
The Environment section of the SCL source code is introduced by the mandatory ENVIRONMENT command. It defines the global attributes of the script, i.e. the script description, the script mode and wait command units.
The Environment section must be the first section of the script, preceding the Definitions section (if present) and Code section. It may, however, be preceded by an INCLUDE statement. For further information, see Including Text from Other Source Files.
DESCRIPTION Statement
This mandatory statement assigns a descriptive character string to a script.
A quoted character string, between 1 and 50 characters in length, used as the description.
MODE HTTP Statement
This optional statement defines the script as an HTTP mode script. These scripts are used to issue HTTP requests to an HTTP server.
This statement must be specified in order for the HTTP-specific commands to be available to a script.
WAIT UNIT Statement
This optional statement defines the unit of the wait period specified in WAIT commands within a script. This does NOT apply to the wait period in the WAIT FOR SEMAPHORE command - the wait period in this command is always specified in seconds.
If this statement is omitted, the wait unit is seconds.
The DEFINITIONS Section
The Definitions section of the SCL source code defines the variables and constants used by the script. It can also contain declarations of timers and files. It is optional and introduced by the DEFINITIONS command.
Only one Definitions section may appear in a script; if it is present, it must follow the Environment section and precede the Code section.
CHARACTER Statement
This statement defines a character string variable consisting of ASCII characters, including control characters. SCL supports character variables of between 1 and 65535 bytes in length.
Arrays of character variables can be defined, with a maximum of three dimensions. For further information about arrays, see Variable Arrays.
An asterisk may be used instead of a colon to delimit the size.
An unsigned integer value in the range 1-65535, representing the size of the variable in bytes. The default is 1.
The name of the variable. This must be a valid OpenSTA Dataname.
The dimensions of the array to be allocated for this variable. Up to three dimensions can be specified, separated by commas, each comprising one or two numbers.
If a dimension has only one number, the elements in that dimension range from 1 to the number specified. If two numbers are specified, they must be separated by a colon (":"); the elements in this dimension range from the first number to the second.
Note that if "dimensions" is specified, "values" may not be.
A list of character values to be associated with the variable. Note that if "values" is specified, "dimensions" may not be. See Variable Values for further information on variable values.
A list of variable options. See Variable Options for further information on variable options.
CONSTANT Statement
This statement defines a variable which has a static value in a script. They may thus be translated at compilation time, and not consume memory at run-time.
The value of a constant may be an integer value or a quoted character string.
Constants can be used in any situation where a literal of the same type (i.e. character or integer) can be used, for example in a value list. The only constraint is that the constant must have been defined before it is used.
The name of the constant. This must be a valid OpenSTA Dataname.
A quoted character string or an integer value.
FILE Statement
This statement declares an identifier (ID) for any external files that are accessed by this script. The FILE statement is mandatory for any files that are being passed as a parameter to the script, and optional otherwise. It is good practice, however, to formally declare all file IDs in this way before use.
A OpenSTA Dataname used to identify a file that is passed as a parameter to the script.
INTEGER Statement
This statement defines a variable with a positive or negative integral value. In SCL, integers are defined as being 4 bytes long, giving a range of -2147483648 to +2147483647.
Arrays of integer variables can be defined, with a maximum of three dimensions. For further information about arrays, see Variable Arrays.
The name of the variable. This must be a valid OpenSTA Dataname.
The dimensions of the array to be allocated for this variable. Up to three dimensions can be specified, separated by commas, each comprising one or two numbers.
If a dimension has only one number, the elements in that dimension range from 1 to the number specified. If two numbers are specified, they must be separated by a colon (":"); the elements in this dimension range from the first number to the second. Note that if "dimensions" is specified, "values" may not be.
A list or range of integer values to be associated with the variable.
Note that if "values" is specified, "dimensions" may not be. For further information on variable values, see Variable Values.
A list of variable options. For further information on variable options, see Variable Options.
TIMER Statement
The TIMER statement declares the name of a stopwatch timer. These timers may be used in conjunction with the START TIMER and END TIMER statements in the Code section of the script.
Up to 1020 timers may be declared and used in a script.
The name of the timer. This must be a valid OpenSTA Dataname.
Variable Arrays
Character and integer variables declared within the Definitions section of a script may be defined as arrays. SCL supports arrays of up to three dimensions. There is no defined limit to the number of elements which may be declared in an array dimension.
If an array of two or three dimensions is specified, each dimension must be separated from the following dimension by a comma. When an array is referenced, array subscripts must be specified for each of its dimensions.
The numbering of the array elements is dependent on how the array was declared. SCL supports both start and end array subscript values within the array declaration itself. For example:
Both of these variable declarations declare an array of character variables each with 12 elements. The elements in the array are both numbered 1 to 12. Compare them with the following example:
This example also declares an array of 12 elements, but the array elements are numbered from 0 to 11.
Only positive values can be specified for the start and end array subscript values, and the start value must be less than or equal to the end value. If the start value is omitted, it defaults to 1.
When you want to retrieve a value from an array variable, you can use numeric literals, integer variables or complex arithmetic expressions to specify the element(s). For example:
Variable Values
A set of values may be associated with a variable, using a value clause in the variable definition. They are used by the GENERATE and NEXT commands, which allow the variable to be assigned a value from the list or range, either randomly (using GENERATE) or sequentially (using NEXT). Values may be specified as a list (integer and character variables) or as a range (integers only). Note: Lists may contain only individual values, and not ranges.
Variables which have been declared as an array may not have an associated value list or range. A value list has the following format:
The values must be of the same data type as the variable, i.e. integer values for integer variables and character values for character variables. They may be literals or constants which have previously been defined.
Note: In the case of character variables, the maximum size of a character constant or literal string is 65535 characters.
Ranges provide a shorthand method for defining a list of adjacent integer values and have the following format:
If the start value is less than the end value, the variable is incremented by 1 on each execution of the NEXT command, until the end value is reached. If the start value is greater than the end value, the variable is decremented by 1 on each execution of the NEXT command, until the end value is reached.
If the variable is set to the end value when the NEXT command is executed, the variable will be reset to the start value. You can also reset the variable explicitly, by using the RESET command.
In the following list of example variable definitions including values, the first two definitions are equivalent:
Variable Options
Additional attributes may be assigned to a variable using option clauses. Variable options follow the value definitions (if present), and are introduced by a comma. There are three types of option clause available: the first defines the scope of the variable; the second is used with variables with associated values, to define how random values are to be generated, if required; the third is used with variables that are defined as a parameter for the script.
The following sections describe the types of variable option clause.
Variable Scope Options
The variable scope options define how widely accessible the variable is; they are mutually exclusive. The variable scope options are:
These options are described below:
Local variables are only accessible to the thread running the script in which they are defined. They cannot be accessed by any other threads or scripts (including scripts referenced by the main script). Similarly, a script cannot access any of the local variables defined within any of the scripts it calls.
Space for local variables defined within a script is allocated when the script is activated and deallocated when script execution completes.
This is the default if no scope option is specified in the variable definition.
Script variables are accessible to any thread running the script in which they are defined.
Space for the script variables defined within a script is allocated when the script is activated and there are no threads currently running the script. If one or more threads are already running the script, the existing script variable data is used.
The space for script variables is normally deallocated when the execution of a script terminates, and no other threads are running the script. In some cases, however, it may be desirable to retain the contents of script variables even if there is no thread accessing the script. This can be achieved by using the ",KEEPALIVE" clause on the EXIT command. The space allocated to script variables is only deleted when a thread is both the last thread accessing the script and has not specified the ",KEEPALIVE" clause. A particular use of this clause is where the script is being called by a number of threads, but there is no guarantee that there will be at least one thread accessing the script at all times.
Thread variables are accessible from any script executed by the thread which declares an instance of them.
The space for thread variables is deallocated when the thread completes.
Thread variables cannot have associated value lists or ranges.
Global variables are accessible to any thread running any script under the same Test Manager.
The space for global variables is deallocated when the Test Manager in question is closed down.
Global variables cannot have associated value lists or ranges.
Random Variable Options
The random options are only valid for variables which have an associated set of values; they are mutually exclusive. The two random options are:
These options function as follows:
This option indicates that a value is to be selected randomly from a list or range, when the variable is used in conjunction with the GENERATE command. The values will be selected in a different order each time they are generated; this is achieved by generating a different seed value for the variable each time the variable is initialized. Local variables are initialized when script execution begins. Script variables are initialized by the first thread to execute the script.
This option is particularly useful when load testing a system.
This is the default if no random option is specified.
This option indicates that a value is to be selected randomly from a list or range, when the variable is used in conjunction with the GENERATE command, but in the same order each time the script is run. This is achieved by using the same seed value for the variable each time the variable is initialized.
This option is particularly useful in regression testing when reproducible input is required.
This option can be used in conjunction with the REPEATABLE RANDOM option, to specify the seed value that is to be used when generating the random sequence of numbers . This makes it possible to use a different sequence of random values for each repeatable random variable. "n" is a numeric literal in the range -2147483648 to +2147483647.
File Option
The variable file option associates an ASCII text file of values - one per line - with a variable:
where "filename" is a quoted character string which defines the name of the ASCII text file, excluding the path name and file extension. The file must reside in the data directory of the Repository and have the file extension .FVR.
The file is used by the NEXT command, which allows the variable to be assigned a value from the file sequentially.
Values are held in the file with one value per line. The values must be of the same data type as the variable, i.e. integer values for integer variables and character values for character variables. For example, a file for an integer variable could contain the values:
A file for a character variable could contain the values:
Note: SCL character commands are not recognized within the file variable files - the file should contain raw ASCII characters only.
Values are retrieved from the file associated with a variable using the NEXT command. This command retrieves the next sequential value from the file. When the NEXT command is first executed, it will retrieve the first value from the file. If the variable is set to the last value in the file when the NEXT command is executed, the variable will be reset to the first value in the file. You can also reset the variable explicitly, by using the RESET command.
The file option is NOT valid for variables which:
Example Variable Definitions
This section shows a number of example variable definitions:
The CODE Section
The mandatory Code section of the SCL source file contains all the commands that define the script's behavior.
A script file must contain a (single) Code section as the last section in the file. It is introduced by the mandatory CODE command.
Code Section Structure
The Code section of an SCL source file is composed of:
SCL provides a wide range of commands that control the behavior of the script.
A command is normally terminated by the end of the source line, but may be continued on a subsequent line by specifying the continuation character as the last character on a line - apart for any line comment. Either an ampersand or a hyphen ("&" or "-") may be used as the continuation character; this is described in Continuation Lines.
Spaces and tabs are treated as separators within a command, although spaces are significant when they appear in character string arguments.
The script compiler allows any character with an ASCII value in the range HEX 00 to 20 or HEX 81 to 8F inclusive to appear at the start of a line or the end of a line. It ignores these characters, allowing tabs and form-feeds, for example, to be used to aid legibility.
If any ASCII control character appears elsewhere, the script compiler will generate a compilation error.
Command Types
SCL offers a large number of commands to support the creation of powerful and flexible scripts. These fall into a number of distinct categories:
Script Processing
When a script is executed, the first command in the script is selected and executed.
Commands are processed sequentially, unless a command that alters the flow of control is executed, in which case processing continues at the defined point in the script.
A script terminates when the end of the script is reached, when an EXIT, or DETACH {THREAD} command is executed, or when an error is detected and error trapping is not enabled for the script.
Variables
All variables accessed by a script must be predefined in the Definitions section of the script. If an undefined variable is accessed from within an SCL source file, an error will be reported.
All integer variables are initially set to zero, and character variables are empty
Labels
Labels may be used to identify SCL statements. A label consists of label name followed by a colon. For example:
A label name must be a valid OpenSTA Dataname.
Any defined subroutines may not reference labels defined in other sections of the code, since labels are local to the module within which they are defined.
Symbols
During compilation, the compiler maintains symbol tables of all the symbols it has encountered, so that it may resolve references to them. There are separate symbol tables for variables, timers and labels.
All symbols within a symbol table must be unique. However, the use of separate symbol tables allows, for instance, the same name to be used for a label as for a variable.
Furthermore, because labels are not propagated into subroutines or vice versa, labels within a subroutine may duplicate labels within other subroutines, or within the main body of the code.
LOAD RESPONSE_INFO BODY Identifiers
The LOAD RESPONSE_INFO BODY command loads a character variable with all or part of the data from an HTTP response message body for a specified TCP connection. For a response body containing an HTML document, the "WITH" clause may be used to load a character variable with an element or part of an element from the document.
The "WITH" clause has the following format:
Note: identifier is a character variable, quoted character string or character expression identifying the data to be retrieved from the HTML document in the response message body. The following sections describe the format of this identifier.
An element within an HTML document is identified by an element address string.
tag(tagnum){/tag(tagnum)}:element_type:{attribute}(element_num)
A number identifying the tag relative to its parent tag or the document root.
0 = First child tag
1 = Second child tag
n = nth child tagThe HTML element type. This must be one of the following:
For element_type ATTRIBUTE, specifies the name of the HTML attribute.
A number identifying the element. For element type ATTRIBUTE, the number identifies the attribute relative to its associated tag.
A complete HTML element string may be retrieved from an HTML document using an identifier containing only an HTML element address. However, a substring may be selected from it using a variety of qualifiers. These qualifiers immediately follow the HTML element address and are described below.
An HTML element substring may be selected using an identifier specifying the offset of the substring and its length.
where "[" and "]" are literal characters and part of the required syntax.
The HTML element address in the format described above.
The offset of the first character of the substring from the start of the element string.
The number of characters in the substring.
· If the length is zero, or is invalid, all characters from the start offset to the end of the element string are returned.
HTML(0)/HEAD(0)/META(1):ATTRIBUTE:CONTENT(1)[2,5]
An HTML element substring may be selected by specifying an identifier containing two string delimiters. The substring returned contains all the characters between the first occurrence of the first delimiter and the first occurrence of the second. The string will also include both delimiter strings.
element_addr[delimiter1,delimiter2]
where "[" and "]" are literal characters and part of the required syntax.
The HTML element address in the format described above.
A string - enclosed in single quotes - identifying the characters at the beginning of the substring.
A string - enclosed in single quotes - identifying the characters at the end of the
· If delimiter2 cannot be found, all characters from and including delimiter1 to the end of the element string are returned.
HTML(0)/HEAD(0)/META(1):ATTRIBUTE:CONTENT(1)['document.cookie=',';']
The above two methods of substring selection can be combined, allowing an HTML element substring to be identified by a start string and a length or an offset and a termination string.
element_addr[delimiter1,length]
element_addr[offset,delimeter2]
where "[" and "]" are literal characters and part of the required syntax.
The HTML element address in the format described above.
A string - enclosed in single quotes - identifying the characters at the beginning of the substring.
The number of characters in the substring.
The offset of the first character of the substring from the start of the element string.
A string - enclosed in single quotes - identifying the characters at the end of the
· If delimiter2 cannot be found, all characters after, and including, delimiter1 to the end of the element string are returned.
· If the length is zero, or is invalid, all characters from the specified offset to the end of the element string are returned.
With the syntax described above, any delimiter strings specified are included in the returned substring. Either or both delimiters may be excluded from the returned substring by inverting the square bracket nearest to the delimiter, i.e. using an opening square bracket in place of a closing square bracket and vice versa.
This method can also be used with offset parameters. Instead of identifying the offset of the first character of the substring to be selected, using this alternative syntax, the offset becomes the offset of the character immediately before the first character to be selected.
The following examples illustrate how a substring may be selected from the CONTENT attribute string of an HTML META tag.
Selects the substring that starts at offset 3 from the beginning of the attribute string and that is terminated by - and includes - the next semicolon in the string.
Selects the substring that starts at offset 2 from the beginning of the attribute string and that is terminated by - but does not include - the next semicolon in
Selects the substring that starts at offset 3 from the beginning of the attribute string and that is terminated by - but does not include - the next semicolon in the string.
There are occasions when it is useful to use the above facilities starting from some point within the element string, rather than at the beginning of the string. This can be achieved by resetting the selection base. This can be done by specifying the selection base as an offset from the beginning of the element string, or by specifying a substring that identifies the characters at the beginning of the substring to be examined. The offset or substring is preceded by one of two operators ">" or ">=":
The offset is that of the character immediately before the substring to be examined.
The substring identifies the characters at the end of the string to be ignored. The substring starts with the first character after the substring.
The offset is that of the first character in the substring to be examined.
The substring identifies the characters at the beginning of the substring to be examined.
If the offset or substring cannot be found, an empty string is returned.
The following examples illustrate how the selection base is reset for a selection from the CONTENT attribute string of an HTML META tag.
The selection base offset is set to the offset of the first character after the first occurrence of the string "// Cookie" in the element string. The selected substring starts with the character after "document.cookie=" and ends with - and includes - the next semicolon.
Same as above, except that the selection base offset is now the first character of "// Cookie".
Same as above, except that selection base offset is now 50 characters from the start of the element string.
All string comparisons specified by LOAD RESPONSE_INFO BODY identifiers are by default case sensitive. The case of characters can be ignored in comparisons by prefixing the search string or delimiter string by "I".
The selection base is reset by searching the element string for "// Cookie"; the case of characters is ignored in the search.
Quoted character strings within SCL are delimited, either by single quotes or by double quotes. Since the syntax of a LOAD RESPONSE_INFO BODY identifier includes single quotes, it is recommended that double quotes are used to delimit a quoted character string containing such an identifier.
A literal single quote character can be included within an identifier string by preceding it with a backslash. For example:
This selects a substring terminated by a single quote.
A literal double quote character can be specified within an identifier string, using the SCL character command, ~<22>. For example,
This selects a substring terminated by a double quote.
Code Section Commands
This section describes the commands that can be included in the Code section of a script file.
The Code section can also contain labels and comments. Further information on these items is given in Overview of Script Control Language Syntax.
Refer to the HTTP Commands section for information relating to the commands that can be used with HTTP.
HTTP Commands
The HTTP commands provide facilities for issuing HTTP requests for resources, examining/ interrogating the response messages and synchronizing requests. These commands are only available in scripts which contain the MODE HTTP statement in their Environment section.
The HTTP commands are as follows:
Input Stream Entry Commands
Input stream entry commands control how the script feeds input to the system under test.
GENERATE Command
This command loads a random value from a set of values into a variable.
The variable must have a list or range of values associated with it in the Definitions section. If it is defined as "REPEATABLE RANDOM", values will be retrieved in the same random order on every run. If it is defined as "RANDOM", values will be retrieved in different random sequences each run.
The name of the variable into which the generated value is to be loaded. The variable must have a set of values associated with it in the Definitions section.
GET Command
This command issues an HTTP GET request for a specified resource. It is only valid within a script that has been defined as MODE HTTP.
The optional PRIMARY keyword denotes primary HTTP requests such as those referred to by the "referer" header in secondary requests. For example:
A request pulling back an HTML page from a Web server can be followed by requests pulling back some GIF images whose URLs are contained in the specified page.
The request header fields are obtained from the HEADER clause. These can be modified using the WITH and WITHOUT clauses.
The HTTP GET request is asynchronous. Immediately after the request is issued, the next command in the script is processed - it does not wait for a response message to be received.
A client certificate may be specified in a request either by file or by name using the "CERTIFICATE FILE" and "CERTIFICATE NAME" clauses.
There is an optional "RESPONSE TIMER" clause, which can be used to specify that a pair of response timer records are to be written to the statistics log. The first record is written when the request message is sent, and the second is written on receipt of the response request message from the server.
The response code in the response message can be retrieved by using the optional "RETURNING CODE response_code " clause to specify the integer variable to hold the response code. The variable is loaded when the response message is received from the server. In addition, the optional "RETURNING STATUS response_status" clause can be used to specify the integer variable to hold one of two values indicating whether the request succeeded or failed. There is an SCL include file "response_codes.inc" supplied with OpenSTA, which defines SCL integer constants for both the response code and response status values.
The TCP connection used for the request depends upon whether a connection has already been established for the specified Connection ID using the CONNECT command. If it has, the request uses that connection. If it has not, a TCP connection will be established to the host identified by the uri-httpversion, on port 80.
By default, if an error occurs while establishing the TCP connection or issuing the request, an error message will be written to the audit log and the thread will be aborted. However, if error trapping is enabled, control will be transferred to the error-handling code.
A character variable, quoted character string or character expression, containing the URI (Uniform Resource Identifier) of the resource upon which to apply the request, and the HTTP Version, separated by a single space character. The HTTP Version indicates the format of the message and the sender's capacity for understanding further HTTP communication.
An integer variable, integer value or integer expression identifying the Connection ID of the TCP connection on which to issue the request.
A character variable, quoted character string, character expression or character value list containing the request header fields.
A character variable, quoted character string, character expression or character value list containing zero or more request header fields. These request-header fields are added to those specified in "http_header". If a request-header field appears in both "http_header" and "header_value", the field specified here overrides that specified in "http_header".
A character variable, quoted character string, character expression or character value list containing the request header field names of fields to be excluded from the request.
A character variable, quoted character string, character expression, containing the name of a file. The file contains a client certificate.
A character variable, quoted character string, character expression, containing a client certificate name.
The name of a timer declared in the Definitions section of the script.
An integer variable into which the response status of the HTTP response message is loaded when the HTTP response message is received.
An integer variable into which the response code of the HTTP response message is loaded when the HTTP response message is received.
HEAD Command
This command issues an HTTP HEAD request for a specified resource. It is only valid within a script that has been defined as MODE HTTP.
The optional PRIMARY keyword denotes primary HTTP requests such as those referred to by the "referer" header in secondary requests. For example:
A request pulling back an HTML page from a Web server can be followed by requests pulling back some GIF images whose URLs are contained in the specified page.
The request header fields are obtained from the HEADER clause. These can be modified using the WITH and WITHOUT clauses.
The HTTP HEAD request is asynchronous. Immediately after the request is issued, the next command in the script is processed - it does not wait for a response message to be received.
A client certificate may be specified in a request either by file or by name using the "CERTIFICATE FILE" and "CERTIFICATE NAME" clauses.
There is an optional "RESPONSE TIMER" clause, which can be used to specify that a pair of response timer records are to be written to the statistics log. The first record is written when the request message is sent, and the second is written on receipt of the response request message from the server.
The response code in the response message can be retrieved by using the optional "RETURNING CODE response_code " clause to specify the integer variable to hold the response code. The variable is loaded when the response message is received from the server. In addition, the optional "RETURNING STATUS response_status" clause can be used to specify the integer variable to hold one of two values indicating whether the request succeeded or failed. There is an SCL include file "response_codes.inc" supplied with OpenSTA, which defines SCL integer constants for both the response code and response status values.
The TCP connection used for the request depends upon whether a connection has already been established for the specified Connection ID using the CONNECT command. If it has, the request uses that connection. If it has not, a TCP connection will be established to the host identified by the uri-httpversion, on port 80.
By default, if an error occurs while establishing the TCP connection or issuing the request, an error message will be written to the audit log and the thread will be aborted. However, if error trapping is enabled, control will be transferred to the error-handling code.
A character variable, quoted character string or character expression, containing the URI (Uniform Resource Identifier) of the resource upon which to apply the request, and the HTTP Version, separated by a single space character. The HTTP Version indicates the format of the message and the sender's capacity for understanding further HTTP communication.
An integer variable, integer value or integer expression identifying the Connection ID of the TCP connection on which to issue the request.
A character variable, quoted character string, character expression or character value list containing the request-header fields.
A character variable, quoted character string, character expression or character value list containing zero or more request-header fields. These request header fields are added to those specified in "http_header". If a request header field appears in both "http_header" and "http_value", the field specified here overrides that specified in "http_header".
A character variable, quoted character string, character expression or character value list containing the request header field names of fields to be excluded from the request.
A character variable, quoted character string, character expression, containing the name of a file. The file contains a client certificate.
A character variable, quoted character string, character expression, containing a client certificate name.
The name of a timer declared in the Definitions section of the script.
An integer variable into which the response status of the HTTP response message is loaded when the HTTP response message is received.
An integer variable into which the response code of the HTTP response message is loaded when the HTTP response message is received.
NEXT Command
This command loads a variable with the next sequential value from a set of values. This could be either a list or a range associated with that variable, or from a file associated with the variable.
When the NEXT command is first executed, it will retrieve the first value. The set is treated as cyclic: when the last value has been retrieved, the next value retrieved will be the first in the set.
This command may be used to reset the value pointer associated with a variable so that the first NEXT command to be executed after the RESET retrieves the first value in the set.
The variable must have a set of values or a file associated with it in the Definitions section.
The name of a variable into which the next value from the set is loaded. The variable must have a set of values or a file associated with it in the Definitions section.
POST Command
This command issues an HTTP POST request for a specified resource. It is only valid within a script which has been defined as MODE HTTP.
The optional PRIMARY keyword denotes primary HTTP requests such as those referred to by the "referer" header in secondary requests. For example:
A request pulling back an HTML page from a Web server can be followed by requests pulling back some GIF images whose URLs are contained in the specified page.
The request field headers to be used in the request are obtained from the HEADER clause, appropriately modified by the WITH and WITHOUT clauses, if specified.
The HTTP POST request is asynchronous. Immediately after the request is issued, the next command in the script is processed - it does not wait for a response message to be received.
A client certificate may be specified in a request either by file or by name using the "CERTIFICATE FILE" and "CERTIFICATE NAME" clauses.
There is an optional "RESPONSE TIMER" clause, which can be used to specify that a pair of response timer records are to be written to the statistics log. The first record will be written when the request message is sent, and the second written on receipt of the response request message from the server.
The status code in the response message may be retrieved by using the optional "RETURNING CODE response_code" clause to specify the integer variable to hold the response code. The variable is loaded when the response message is received from the server. In addition, the optional "RETURNING STATUS response_status" clause may be used to return one of two values indicating whether the request succeeded or failed. There is an SCL include file "response_codes.inc" supplied with OpenSTA, that defines SCL integer constants for both the response code and response status values.
The TCP connection used for the request depends upon whether a connection has already been established for the specified Connection ID using the CONNECT command. If it has, the request uses that connection. If it has not, a TCP connection will be established to the host identified by the uri-httpversion, on port 80.
By default, if an error occurs while establishing the TCP connection or issuing the request, an error message is written in the audit log and the thread is aborted. However, if error trapping is enabled, control will be transferred to the error-handling code.
A character variable, quoted character string or character expression, containing the URI (Uniform Resource Identifier) of the resource upon which to apply the request, and the HTTP Version, separated by a single space character. The HTTP Version indicates the format of the message and the sender's capacity for understanding further HTTP communication.
An integer variable, integer value or integer expression identifying the connection ID of the TCP connection on which to issue the request.
A character variable, quoted character string, character expression or character value list containing the request header fields.
A character variable, quoted character string or character expression containing the request body.
A character variable, quoted character string, character expression or character value list containing zero or more request header fields. These request header fields are added to those specified in "http_header". If a request header field appears in both "http_header" and "http_value", the field specified here overrides that specified in "http_header".
A character variable, quoted character string, character expression or character value list containing the request header field names of fields to be excluded from the request.
A character variable, quoted character string, character expression, containing the name of a file. The file contains a client certificate.
A character variable, quoted character string, character expression, containing a client certificate name.
The name of a timer declared in the Definitions section of the script.
An integer variable into which the response status of the HTTP response message is loaded when the HTTP response message is received.
An integer variable into which the response code of the HTTP response message is loaded when the HTTP response message is received.
RESET Command
This command resets the value pointer for a variable to the first value in the associated value set. This could be either a list or a range associated with that variable, or from a file associated with the variable. In the case of a repeatable random variable, the variable's seed may be reset to a specified or defaulted value.
The RESET command does not alter the contents of the variable. The value to which the variable has been reset is only retrieved on execution of the first NEXT command after the RESET command.
The name of the variable whose value pointer is to be reset. The variable must have a set or a file associated with it in the Definitions section.
An integer numeric literal in the range -2147483648 to +2147483647. If the "SEED" clause is omitted from the RESET command, the seed variable will be reset to the value specified when the variable was defined, or to the value specified by a previous RESET command.
SET Command
This command allows a value to be assigned to an integer or character variable. The values may be any integer or character values or a function reference, but their data types must match that of the variable. The values may be derived as a result of arithmetical operations.
If the variable is an integer variable, the assignment expression may be another integer variable or a numeric literal, or a complex arithmetic expression consisting of two or more integer values or variables, each separated by an operator. The following operators are supported:
+ for addition - for subtraction * for multiplication / for division | for moduloThe value resulting from a division operation will be an integer, i.e. the remainder will be ignored. The modulo calculation is the converse of this operation, i.e. the variable will be set to the value of the remainder. For example:
If B = 13 and C = 2, then A will be set to 6 and D to 1.
Parentheses may be specified to determine the order of precedence. If parentheses are not specified, then the expression is evaluated from left to right with no other order of precedence applied.
Care should be taken when using arithmetic expressions, since there is no check for integer overflow at run-time. If an integer overflow occurs a script error will be reported.
If the variable is a character variable, the assignment expression may consist of one or more character variables or literals. Operands are separated by the addition operator if the operands are to be added together; if the second operand is to be subtracted from the first, they are separated by the subtraction operator.
The character function ~EXTRACT may be referenced within a SET command to extract a substring from a character variable or quoted character string into a character variable.
The integer function ~LOCATE may be referenced within a SET command to load the offset of a substring within a character variable or quoted character string into an integer variable.
The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error. An error could occur if, for example, an ~EXTRACT function is specified with an invalid offset, or an attempt is made to divide by zero.
The name of an integer or character variable into which the result of the operation is to be placed.
The value from which the initial operation result will be taken. For a character SET command, the operand may be a character variable, quoted character string or character function reference. For integer SET commands, the operand may be an integer function reference, literal or variable.
The operation which is to be performed upon the previous and following operands. For character SET commands, it may be "+" to add the first operand to the second, or "-" to subtract the second operand from the first. For integer SET commands, all operators are valid.
The variable or value which is used to modify the current value for "variable". For a character SET command, the operand may be a character variable, quoted character string or character function reference. For integer SET commands, the operand may be an integer literal or variable.
A label defined within the current scope of the script, to which control branches if an error occurs.
Output Stream Handling Commands
Output stream handling commands control how scripts examine and manipulate output from the system, either within the script itself or by saving the data for later comparison.
CONVERT Command
This command allows the value in an integer variable to be converted to an ASCII string, or vice versa. The default radix for the conversion is 10, but this may be overridden by including a "RADIX" clause in the command.
For integer-to-character conversions, format options may be specified. These options can cause the ASCII string to be left- or right-justified within the output buffer, or to have leading zeros or spaces, or cause the conversion to be signed or unsigned.
In the format description below, the "|" characters indicate mutually exclusive options.
The default options are SIGNED and LEFT JUSTIFY. If RIGHT JUSTIFY is in operation, the default filling is LEADING ZEROS.
if the output buffer is too small to hold the output string, it will be filled with asterisk ("*") characters.
For character-to-integer conversions, leading and trailing spaces are removed form the ASCII string before the conversion. Specification of a non-numeric ASCII string, or of an ASCII string which is converted to a numeric outside the range of an interger*4, will cause a message to be logged to the audit file indicating an invalid character string to convert. The thread will be aborted.
The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error.
A variable containing the variable to be converted.
A variable into which the converted variable is to be placed.
An integer variable or literal in the range 2 to 36.
A label defined within the current scope of the script, to which control branches if an error occurs.
~EXTRACT Command
This command is a function and can only be referenced within a SET command. It returns the portion of the source string identified by the specified offset and length.
If the string identified by the offset and length overlaps the end of the source string, only the characters up to the end of the source string will be returned.
If the offset does not lie within the bounds of the source string when the script is executed, a message will be written to the audit log, indicating that a bad parameter value has been specified. Script execution will then be aborted, or the specified action taken if error trapping is enabled via the ON ERROR command.
The character substring extracted from the source string.
An integer variable or value defining the offset in the source string of the first character that is to be extracted. The first character of the source string is at offset zero.
An integer variable or value defining the number of characters to extract to form the substring.
The character value or character variable from which the substring is to be extracted.
FORMAT Command
This command translates characters from one format into another. This makes it easier to manipulate character strings that have been output from the system under test, or which are to be input into that system.
In all translations, the command requires three elements:
The target variable that will receive the translated value. This may be either a character variable or an integer variable.
A format string defining the type of translation required. For an integer target variable, the format string must only contain a single format identifier; for a character variable, the format string may contain multiple identifiers and/or ordinary characters that are to be copied unchanged to the target variable.
One or more values to be translated; these may be specified as variables or as literal text. A single value must be specified for each of the format identifiers in the format string; the data type of each must agree with the associated format identifier and the data type of the target variable, as discussed below. Note that any discrepancies in this respect are detected at run-time and are not picked up by the compiler.
The following types of translation are supported:
%U - Translate each alphabetic character in the input string into its uppercase equivalent. Both source and target variables must be character variables. The source string if necessary is truncated to fit the target variable.
%L - Translate each alphabetic character in the input string into its lowercase equivalent. Both source and target variables must be character variables. The source string if necessary is truncated to fit the target variable.
%D - Convert a character string date value into numeric format (representing the number of days since the Smithsonian base date of 17-Nov-1858). The target variable must be an integer variable, and the source variable a character string containing a valid date; this can be either in the default style for the platform on which the script is running or in the fixed format "DD-MMM-CCYY" (where "CC" is optional).
This format identifier may also be used to convert a numeric date value (representing the number of days since the Smithsonian base date of 17-Nov-1858) into a character string in the fixed format "DD-MMM-CCYY". The source variable must be an integer variable and the target variable a character string, which will be truncated if necessary.
%T - Convert a character string time value into a numeric format (representing the number of 10 milli-second `ticks' since midnight). The target variable must be an integer variable, and the source variable a character string containing a valid time; this can be either in the default style for the platform on which the script is running or in the form "HH:MM:SS.MMM" (where ".MMM" is optional).
This format identifier may also be used to convert a numeric time value (representing the number of 10 milli-second ticks since midnight) into a character string in the fixed format "HH:MM:SS.MMM". The source variable must be an integer variable and the target variable a character string, which will be truncated as required.
The name of an integer or character variable into which the result of the operation is placed.
A quoted character string containing the string to be formatted and containing a number of format identifiers. The format identifiers must be compatible with the data types of the variables that follow.
One or more integer or character variables or literals to be translated. The number of variables must correspond with the number of format identifiers in the format string. The data type of each variable must match the corresponding format identifier and the target variable.
A label defined within the current scope of the script, to which control branches if an error occurs.
LOAD RESPONSE_INFO BODY Command
This command loads a character variable with all or part of the data from an HTTP response message body for a specified TCP connection. It is used after a GET, HEAD or POST command.
OpenSTA will automatically wait until any request on the specified connection ID is complete before executing this command. It is not necessary for the script to do this explicitly.
If the data string is too long to fit into the target variable, it will be truncated. For a response message body containing an HTML document, the "WITH" clause may be used to load a character variable with an element or part of an element from the document.
An integer variable, integer value or integer expression identifying the Connection ID of the TCP connection on which the HTTP response message will be received.
The name of a character variable into which the HTTP response message body, or the selected part of it, are loaded.
A character variable, quoted character string or character expression identifying the data to be retrieved from the response message body. For a definition of the identifier format see LOAD RESPONSE_INFO BODY Identifiers.
LOAD RESPONSE_INFO HEADER Command
This command loads a character variable with all or some of the HTTP response message header fields for a specified TCP connection.
OpenSTA will automatically wait until any request on the specified Connection ID is complete before executing this command. It is not necessary for the script to do this explicitly.
If the data string is too long to fit into the target variable, it will be truncated.
The "WITH" clause can be used to specify the names of a header field whose value is to be retrieved from the HTTP response message. If this clause is omitted, all the response message header fields are retrieved.
An integer variable, integer value or integer expression identifying the connection ID of the TCP connection on which the HTTP response message will be received.
The name of a character variable into which the HTTP response message headers, or the selected headers, are loaded.
A character variable, quoted character string or character expression containing the name of the response message header field to be retrieved.
~LOCATE Command
This command is a function and can only be referenced within a SET command. It returns an integer value, corresponding to the offset of the specified substring in the source string. The offset of the first character in the source string is zero. If the substring is not found, the function returns a value of -1.
By default, the matching is case sensitive. The strings "London" and "LONDON", for example, would not produce a match, because the case of the characters is not the same. This can be overridden by specifying the ", CASE_BLIND" clause.
The source string is scanned from left to right. If the substring appears more than once in the source string, the function will always return the offset of the first occurrence.
The offset of the substring in the source string. If the substring was not found, then a value of -1 is returned.
The character value defining the substring to be located in the source string. This may be a character variable or quoted character string.
The character value to be searched for the specified substring. This may be a character variable or quoted character string.
Flow Control Commands
Flow control commands determine which sections of a script are processed, and in what order.
CALL Command
This command calls a subroutine from within a script. Subroutines must follow the main code section and must not be embedded within it. They share the variable definitions of the main module.
It is not possible to branch into or out of a subroutine, because a label cannot be referenced outside of the main module or subroutine in which it occurs. This does mean, however, that each subroutine enables a script to define up to 255 labels in addition to those used in the main code.
A maximum of eight parameters may be passed from the calling code to the called subroutine. The parameters passed may be character or integer variables, literals or quoted character strings. The calling code must pass exactly the same number of parameters to the called subroutine as the called subroutine has defined in its SUBROUTINE statement. The names of the variables in the call need not be the same as in the subroutine parameter list, but the data types of each of the parameters must match. Failure to comply with these conditions will result in a script error being generated.
The values of the variables defined as parameters in the subroutine definition are not copied back to the variables in the call, on return from the subroutine. However, if the same variable names are used in the call and the subroutine parameter list, the value of the variable in the call will be changed by a change in the subroutine; this is because the calling code and the called subroutine share the same data definitions. Conversely, if different variable names are used, any changes made to variables within the subroutine will not affect the variables in the call.
The name of the called subroutine. The name must be a valid OpenSTA Dataname.
A character variable, integer variable, integer value or a quoted character string. Up to 8 parameters may be declared in the CALL command. There must be the same number of parameters in this list as are in the subroutine's definition, and the data types of the parameters must match.
CALL SCRIPT Command
This command calls a script from another script. When the command is executed, control is transferred to the called script; when the called script exits, control is returned to the calling script, optionally returning a status from the called script. There is no limit on the number of scripts that may be referenced by any one script.
In general, a called script is considered as an extension to the calling script, and any changes made in the called script are propagated back to the calling script on exit. However, certain changes (e.g. further ON ERROR handlers) only remain in force for the duration of the called script (or scripts called by it); the original condition is reestablished when control is returned to the calling script.
For scripts, a maximum of eight parameters may be passed from the calling script to the called script. An omitted parameter is specified by two consecutive commas ",,". The calling script must pass exactly the same number of parameters to the called script as the called script has defined in its ENTRY statement (accounting for any omitted parameters). In addition, the data types of each of the parameters must match. Failure to comply with these conditions will result in a script error being generated.
The values of the parameters are passed from the caller into the variables defined within the ENTRY statement of the called script. Any modifications to the values of the variables are copied back to the caller on return from the called script.
An optional status value can be returned from the called script by using the "RETURNING" clause to specify the integer variable which is to hold the return status value.
By default, if an error occurs in a called script, an error message is written to the audit log and the thread aborts; control is not returned to the calling script. However, if error trapping is enabled in the calling script and the error was a script error, then control will be returned to the calling script's error handling code.
The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error while attempting to call the script.
A character variable or quoted character string defining the name of the script to be called. The name must be a valid OpenSTA Dataname.
A character variable, integer variable, quoted character string, integer value or file ID to be passed to the called script. A maximum of 8 parameters may be passed between scripts.
An integer variable to receive the returned status from the called script. If no status is returned from the called script, then this variable will contain the last status returned from any called script.
A label defined within the current scope of the script, to which control branches if an error occurs.
CANCEL ON Command
This command terminates the automatic trapping of script errors, which is enabled with the ON ERROR command. Any script errors encountered will cause the thread to be aborted.
This command will only affect automatic trapping of script errors within the current script or scripts called by it. On exit from this script, any ON ERROR handler established by a calling script will be re-established.
DETACH Command
This command causes the current thread to exit. The program exits from any scripts or subroutines that have been called (including nested calls) until control returns to the primary script. The thread is then detached from the Test Executer.
DO Command
The DO and ENDDO commands allow a set of commands to be repeated a fixed number of times. The section of a script to be repeated is terminated by an ENDDO command.
The name of the control or index variable that is adjusted each time the loop executes. The adjustment is determined by the value of the step variable. This must be an integer variable.
The starting value of the control variable. This must be either an integer variable or an integer value.
The terminating value of the control variable. This must be an integer variable or value, and may be either higher or lower than value1. When the control variable contains a value that is greater than this value (or lower if the step is negative), the loop will be terminated.
An integer variable or value determining the value by which the control variable or index variable is incremented each time the loop executes. If value2 is less than value1, then the step value must be negative. If a step variable is not specified, then the step value will default to 1.
END SUBROUTINE Command
This command terminates a subroutine. It must follow all other executable commands within the subroutine. The only statements that may follow an END SUBROUTINE command are a comment, a new SUBROUTINE command or an INCLUDE command; the included script must contain more subroutine definitions.
A subroutine is initiated by the SUBROUTINE command.
ENTRY Command
This command, if specified, must be the first item in the Code section of the script, excluding format characters and comments. It identifies which variables are to receive values passed as parameters from a calling script
It is advisable that variables declared in the ENTRY command do not have an associated value list or range or file. Values passed in this way will be overwritten when script initialization takes place following the ENTRY command.
A character variable (of up to 50 characters in length), integer variable or file ID declared in the Definitions section of the script. Up to 8 parameters may be declared in the ENTRY command. There must be the same number of parameters in this list as are passed to the script (including omitted parameters), and the data types of corresponding parameters must match.
EXIT Command
This command causes execution of the current script to terminate immediately. No further input will be provided from the script file and no commands executed.
An optional status value can be returned when the script in question has been called from another script. This is achieved by using the status variable to place a value into the return status variable specified on the call to this script. If no status is specified, but the caller is expecting one, then the status returned will be that returned by the last script which exited with a status. This allows a status to be retrieved from a deeply nested script where no explicit status returning has been employed.
At run-time, a script is automatically terminated when the end of the script is reached. It is not necessary to include an EXIT command as the last command in a script, to terminate script execution.
If the script has been called, using the CALL SCRIPT command, execution of the calling script will resume at the command immediately following the CALL SCRIPT command.
When an EXIT command is processed and there are no other threads executing the script, the script data is discarded. However, if the ",KEEPALIVE" option is specified on the EXIT command, then the script data that will not be deleted even if there are no other threads executing it. This allows subsequent threads to execute the script and access any script data set up by a previous thread.
An integer variable or integer value to be returned as the status from this script to the caller. The status will be returned into the integer variable specified on the CALL command.
GOTO Command
This command transfers control to a specified script label. The transfer of control is immediate and unconditional.
Conditional branches may be made using the IF command.
A label defined within the current scope of the script.
IF Command
This command performs tests on the values of variables against other variables or literals, and transfers control to a specified label depending upon the outcome of the tests.
Alternatively, structured IF commands may be used to perform one or more commands depending upon the success or failure of the tests.
By default, the matching is case sensitive. The strings "London" and "LONDON", for example, would not produce a match, because the case of the characters is not the same. This can be overridden by specifying the ", CASE_BLIND" clause.
A condition of the following format:
{NOT}(operand1 operator operand2 {, CASE_BLIND}) &
{AND/OR condition ...}The two operands may each be a variable, a quoted character string or an integer value.
The option "CASE_BLIND" may be specified for "operand2", to request a case-insensitive comparison of the operands.
"NOT" inverts the result of the bracketed condition that it precedes.
All conditions are evaluated from left to right.
A label defined in the current scope of the script.
Any number of script commands - including further IF or DO commands, provided that the maximum nesting level of 100 is not exceeded.
ON ERROR Command
This command allows script errors - which would normally cause the thread being executed to abort - to be captured, and script execution to be resumed at a predefined label. The ON ERROR handler is global to all sections of the script; it is propagated into all called subroutines and scripts.
The ON ERROR command captures any errors which occur either in the script within which it was declared or within any lower level scripts called by it. All script errors, such as a bad parameter error on the ~EXTRACT command, or an attempt to call a nonexistent script, may be intercepted and dealt with by this command.
If a script error is encountered, then a message will be written to the audit log, identifying and locating where the error occurred. If the error has occurred in a script at a lower level than that within which the ON ERROR command was declared, then all scripts will be aborted until the required script is found.
An ON ERROR handler may be overridden by the "ON ERROR GOTO" or "ON TIMEOUT GOTO" clause for the duration of a single command. It may also be overridden by the ON ERROR command within a called script or subroutine; such a modification will affect only those scripts and subroutines at that nesting level or lower. On exit from the script or subroutine, the previously defined ON ERROR handler will be re-established.
When ON ERROR checking is established, it can be disabled by using the CANCEL command, as follows:
The name of the label within the current scope of the script, to which control branches if a script error is encountered.
RETURN Command
This command returns control from a called subroutine to the instruction following the call to that subroutine.
SUBROUTINE Command
This command defines the start of a discrete section of code which is bounded by the SUBROUTINE and END SUBROUTINE commands.
Subroutines are called from the main code with a command of the format "CALL name". They return control to the main code by use of the RETURN command. A maximum of 255 subroutines may be defined within a script.
Subroutines share the same variable definitions as the main code but have their own labels. A label may not be referenced outside the main module or outside the subroutine in which it occurs. This has the effect of disabling branching into and out of subroutines, and also means that each subroutine may use a further 255 labels in addition to those used in the main code.
The name of the subroutine. This must be a valid OpenSTA Dataname, and must be unique within the script.
A character variable or integer variable declared in the Definitions section of the script. Up to 8 parameters can be declared in the SUBROUTINE command. There must be the same number of parameters in this list as there are in the subroutine call, and the data types of the parameters must match.
File Handling Commands
File handling commands help scripts and external data files exchange data.
CLOSE Command
This command closes an external data file. The file must have already been opened by the OPEN command.
The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error.
The name associated with the file when it was opened.
A label defined within the current scope of the script, to which control branches if an error occurs.
OPEN Command
This command opens an external data file (or creates a new one) and associates a OpenSTA Dataname with it, for future reference.
The data file can be opened for INPUT, OUTPUT or APPEND access. While the file is open for OUTPUT or APPEND access, it may not be opened by any other threads, unless the ",SHARED" clause is specified. This clause allows multiple threads to open an external file concurrently; they use the same `stream', so that reads from or writes to that file by the threads are interleaved. A shared file may be open for INPUT access by one group of threads and for OUTPUT or APPEND access by another group at the same time. Note that more than one thread may open a file for INPUT access, even if the ",SHARED" clause is not specified; in this case, reads from the file are totally independent for each thread.
If the ",COMMA-SEPARATED" clause is specified, the file will be opened as a comma-separated data file. This means that comma characters within the record are treated as being significant; they are used to break the record up into its constituent fields. This clause can be used when opening SCL data files for input or output. External data files that are created from an OPEN command using the ",COMMA-SEPARATED" clause, contain records that are all ASCII text - including integer fields. Integer fields are automatically converted back into their binary representation by the READ command. Conversely, integers are converted into ASCII when written to the file using the WRITE command.
If the ",BINARY" clause is specified, then the file will be opened as a binary file rather than a text file. Binary files differ from text files in that there is no delimiting of individual records. The data is organized as a continuous stream and is written to and read from the file as such.
For a text file, a newline character will be added to the end of each record written to the file to act as a record delimiter. When reading records from a text file, data will be read up to but not including the newline character. The newline character will be skipped over to position the file at the start of the next record to be read.
The record read will be truncated as required to fill the specified variable.
Attempting to write to a data file opened for INPUT access will cause a script error. In the same way, a data file opened for OUTPUT or APPEND access cannot be read from.
If "OUTPUT" access is specified, then under normal circumstances, a new file is created. However, if the ",SHARED" clause is also specified, a new file will only be created by the thread which first executes the command. All other threads will write to this file.
A maximum of 10 external data files may be open for each thread at any one time. Attempting to open more than this number will result in a script error being reported.
The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error. This must be the last clause in the statement.
A character variable or quoted character string containing the filename of the file to open.
A OpenSTA Dataname associated with the file when it is opened; it is used to identify the file in future references. The "fileid" must be declared in a FILE statement in the Definitions section of the script.
The type of access which is to be allowed to the file. This can be "INPUT" (the default), "OUTPUT" or "APPEND".
Can be set to "SHARED" or "NOSHARED", and defaults to "NOSHARED".
A label defined within the current scope of the script, to which control branches if an error occurs.
READ Command
This command reads a single record from an external file that is currently open for input, into a variable. If the file record is longer than the variable, the record data is truncated.
If the external data file was opened using the "COMMA-SEPARATED" clause on the OPEN command, the compiler checks that data is read as comma-separated records; it reports an error if data is not read into a record variable.
If the file was opened with the "BINARY" option specified, then a record consists of sufficient data to fill the specified variable.
If the "BINARY" option was not specified when the file was opened, then the record read will be delimited by a newline character in the file. This newline character is used purely as a record delimiter and does not form part of the record.
By default, the file will be rewound when an "End-of-File" status is returned by the READ command. This action may be modified by use of the "AT END GOTO label" clause.
The file is read sequentially.
A character variable into which the next record from the file is read.
The dataname associated with the file when it was opened.
A label within the current scope of the script, to which script execution will branch if the "End-of-File" status is encountered.
A label within the current scope of the script, to which script execution will branch if an error occurs.
REWIND Command
This command causes an external data file to be rewound. The file must already have been opened by the OPEN command. If the file is open for APPEND or OUTPUT access, it will be re-initialized when the first Write operation following the REWIND command is made - providing the file has not been closed and reopened in the interim.
The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error.
The name associated with the file when it was opened.
A label defined within the current scope of the script, to which control branches if an error occurs.
WRITE Command
This command writes the specified variable, as a record, to the specified file.
The WRITE command may only be used on external data files which have been opened for APPEND or OUTPUT access. Attempting to write to an external data file which has not been opened for either of these access types will cause a script error to be reported.
If the external data file was opened using the "COMMA-SEPARATED" clause on the OPEN command, the compiler checks that data is written as comma-separated records; it reports an error if the data to be written is not a record variable.
If the file has been opened as a text file (i.e. the "BINARY" option was not specified on the OPEN command), then a newline character will be appended to the record before it is written to the file, to act as a record delimiter. For this reason, records written to text files should not themselves contain newline characters, because they will be treated as delimiters when the record is read again.
The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error.
The name of a character variable, or a quoted character string, which is to be written to the specified file.
The name associated with the file when it was opened.
A label defined within the current scope of the script, to which control branches if an error occurs.
Formal Test Control Commands
Formal test control commands provide formal support for tracking the results of each test, so that it is possible to see easily how well the testing is going.
END TEST-CASE Command
The END TEST-CASE command terminates a section of the script that starts with a START TEST-CASE command, to create an individual test case.
If the END TEST-CASE command is reached during execution of the script, the test case is considered to have succeeded, and the message specified in the test definition is sent to the report log.
Test cases cannot be nested. However, there is no restriction on calling another script that contains test cases, from within a test case section.
FAIL TEST-CASE Command
This command indicates that the current test case has failed. The test case failure message is sent to the report log, and the test case anomaly count is incremented.
Script execution is resumed at the first instruction following the end of the test case section (i.e. the END TEST-CASE command). If a "GOTO" clause is specified, script execution is resumed at the point identified by the clause label. If a valid command immediately follows the FAIL TEST-CASE command that would not be executed because of the jump in script execution, the script compiler outputs a warning message when the script is compiled, but still produces an object file (assuming there are no errors).
This command is only valid within a test case section of a script. It can be repeated as often as required within an individual test case.
A label defined within the current scope of the script, to which control branches.
HISTORY Command
History logs contain a history of the executions of a test. Therefore, the program always attempts to open an existing history log each time the test is executed.
The HISTORY command allows you to specify a message to be logged in this file. Each message will have a date, time and thread name associated with it in the history log.
A history message may consist of any number of individual values separated by commas. Any nonprintable ASCII characters in character values are replaced with periods (".") Integer values are written as signed values, using only as many characters as necessary.
The value or variable to be written to the history log. This may be a variable or quoted character string.
PASS TEST-CASE Command
This command indicates that the current test case has succeeded. The test case success message is sent to the report log.
If no GOTO clause is specified, script execution is resumed at the first command following the end of the test case section (i.e. the END TEST-CASE command). If a GOTO clause is specified, script execution is resumed at the point identified by the clause label. If a valid command immediately follows the PASS TEST-CASE command that would not be executed because of the jump in script execution, the compiler outputs a warning message when the script is compiled, but still produces an object file (assuming there are no errors).
This command is only valid within a test case section of a script. It can be repeated as often as required within a test case.
If the END TEST-CASE command is reached during execution of the script, the test case is automatically considered to have succeeded, and the success message is sent to the report log.
A label defined within the current scope of the script, to which control branches.
REPORT Command
Report logs contain transient information relating to the execution of a test.
The REPORT command allows the user to specify a message to be logged in this file. Each message will have a date, time and thread name associated with it in the report log.
A report message may consist of any number of individual values separated by commas.
Any nonprintable ASCII characters in character values are replaced with periods ("."). Integer values are written as signed values, and use only as many characters as are necessary.
The value or variable to be written to the report log. This may be a variable or quoted character string.
START TEST-CASE Command
The START TEST-CASE command introduces a section of code that is grouped together into a test case. The section is terminated by an END TEST-CASE command.
The START TEST-CASE command must include a description of the test case. The test case description and test case status are written to the report log when the test case is executed.
Test cases cannot be nested, so a test case must be terminated with an END TEST-CASE command before a new test case section can be started. However, there is no restriction on calling another script that contains test cases, from within a test case section.
A character variable or quoted literal string containing text that describes the test case.
Synchronization Commands
These commands address events that scripts may have to wait for before continuing their execution.
ACQUIRE MUTEX Command
This command acquires exclusive access to a shared resource, known as a mutex. The mutex is identified by its name and scope (which must be either "LOCAL" or "TEST-WIDE"). A test-wide mutex is one that is shared by all scripts running as part of a distributed test; a local mutex is only shared between scripts running on the local node.
By default, if an attempt is made to acquire a mutex that has already been acquired by another script (within the same scope), then the thread will be suspended until the mutex is released. However, if a time-out period is specified, this represents the maximum number of seconds that OpenSTA will wait for the mutex to be released before timing out the request. A period of zero indicates that the request should be timed out immediately if the mutex has been acquired by another script.
The "ON TIMEOUT GOTO tmo_label" clause can be specified to define a label to which control should be transferred if the request times out. In addition, the "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error, or if the request times out and there was no "ON TIMEOUT GOTO tmo_label" clause.
The scope of the mutex to be acquired. This must be either "LOCAL" or "TEST-WIDE", and defaults to "LOCAL".
A character variable, or quoted character string, containing the name of the mutex which is to be acquired. "mutex-name" must be a valid OpenSTA Dataname.
An integer variable or value, defining the number of seconds to wait before an unsatisfied request is timed out. The valid range is 0-2147483647.
A label defined within the current scope of the script, to which control branches if a time-out occurs.
A label defined within the current scope of the script, to which control branches if an error occurs, or the command times out and "tmo_label" is not specified.
CLEAR SEMAPHORE Command
This command resets a named semaphore to its "Clear" state. The semaphore is identified by its name and scope (which must be either "LOCAL" or "TEST-WIDE"). A test-wide semaphore is one that is shared by all scripts running as part of a distributed test; a local semaphore is only shared between scripts running on the local node.
The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error.
The scope of the semaphore to clear. This must be either "LOCAL" or "TEST-WIDE", and defaults to "LOCAL".
A character variable, or quoted character string, containing the name of the semaphore to clear.
A label defined within the current scope of the script, to which control branches if an error occurs.
RELEASE MUTEX Command
This command releases a named mutex. The mutex to be released is identified by its name and scope, which must correspond to the values specified on the corresponding ACQUIRE MUTEX command.
The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error. Note that an error always occurs if the script that issues the RELEASE MUTEX request has not previously acquired it.
The scope of the mutex to release. This must be either "LOCAL" or "TEST-WIDE", and defaults to "LOCAL".
A character variable, or quoted character string, containing the name of the mutex to release.
A label defined within the current scope of the script, to which control branches if an error occurs.
SET SEMAPHORE Command
This command sets a named semaphore to its "Set" state. The semaphore is identified by name and scope (which must be either "LOCAL" or "TEST-WIDE"). A test-wide semaphore is one that is shared by all scripts running as part of a distributed test; a local semaphore is only shared between scripts running on the local node.
The "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error.
The scope of the semaphore to be set. This must be either "LOCAL" or "TEST-WIDE", and defaults to "LOCAL".
A character variable, or quoted character string, containing the name of the semaphore to be set.
A label defined within the current scope of the script, to which control branches if an error occurs.
SYNCHRONIZE REQUESTS Command
HTTP requests are issued asynchronously. Immediately after an HTTP request has been issued, the next command in the script is processed. OpenSTA does not wait for a response to be received for an HTTP request.
This command causes the thread currently executing to be suspended immediately, until responses have been received for all the requests that have been issued by the thread. It is only valid within a script that has been defined as MODE HTTP.
The `ON TIMEOUT GOTO tmo_label' clause can be specified to define the label to which control will be transferred if the request times out.
An integer variable, integer value or integer expression defining the number of seconds to wait before the command is timed out. The valid range is 0 - 32767.
A label defined within the current scope of the script, to which control branches if a time-out occurs.
Input Stream Entry Commands
Input stream entry commands control how the script feeds input to the system under test.
WAIT Command
This command suspends the script execution for the specified number of seconds. The unit is either seconds or milliseconds depending upon the value of the Environment statement WAIT UNIT.
An integer variable or value defining the number of seconds for which script execution is to be suspended. The valid range is 0-2147483647.
WAIT FOR SEMAPHORE Command
This command halts the script until the specified semaphore is in its "Set" state. The semaphore is identified by its name and scope (which must be either "LOCAL" or "TEST-WIDE"). A test-wide semaphore is one that is shared by all scripts running as part of a distributed test; a local semaphore is only shared between scripts running on the local node.
By default, if the semaphore is in its "Clear" state when the WAIT FOR SEMAPHORE command is issued, the thread will be suspended until it is set into its "Set" state. However, if a time-out period is specified, this represents the maximum number of seconds that OpenSTA will wait for the semaphore to be set before timing out the request. A period of zero indicates that the request should be timed out immediately if the semaphore is not set.
The "ON TIMEOUT GOTO tmo_label" clause can be specified to define a label to which control should be transferred if the request times out. In addition, the "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error, or if the request times out and there was no "ON TIMEOUT GOTO tmo_label" clause.
An integer variable or value defining the number of seconds to wait. The valid range is 0-2147483647.
The scope of the semaphore to wait for. This must be either "LOCAL" or "TEST-WIDE", and defaults to "LOCAL".
A character variable, or quoted character string, containing the name of the semaphore to wait for.
A label defined within the current scope of the script, to which control branches if a time-out occurs.
A label defined within the current scope of the script, to which control branches if an error occurs, or the command times out and "tmo_label" is not specified.
Statistical Data Logging Commands
Diagnostic commands help you to analyze scripts in order to diagnose an anomaly.
END TIMER Command
This command switches off the named stop-watch timer and writes an `end timer' record to the statistics log, even if the timer is already switched off.
A stop-watch timer is switched on by the START TIMER command.
The timer name. The timer must be declared in a TIMER statement in the Definitions section of the script.
START TIMER Command
This command switches on the named stop-watch timer and writes a `start timer' record to the statistics log.
There is no limit to the number of stop-watch timers that can be switched on at the same time. However, if a timer is switched on twice without being stopped in the interim, the first timer is effectively cancelled and thrown away when it is restarted.
A stop-watch timer is switched off by the END TIMER command.
The timer name. The timer must be declared in a TIMER statement in the Definitions section of the script.
Diagnostic Commands
During test development, there is occasionally a need to find out more about what a script is doing in order to diagnose an anomaly. The diagnostic commands assist in this process.
LOG Command
OpenSTA maintains an audit trail of its activity and related events. The LOG command allows the user to specify a message to be written to the audit log. Each message in this file will have a date, time and thread name associated with it.
A log message may consist of any number of individual values separated by commas.
Any nonprintable ASCII characters in character values are replaced with periods ("."). Integer values are written as signed values, using only as many characters as are necessary.
The value or variable to be logged. This may be a variable or quoted character string.
NOTE Command
This command associates a list of variables or quoted character strings with the current thread. The current value can be viewed in the Monitoring tab of the Active Test Pane in Commander.
The value or variable to be logged. This may be a variable or quoted character string.
TRACE Command
This command writes user-definable messages to the script tracing log.
The value or variable to be written to the trace log. This may be a variable or quoted character string.
Miscellaneous Commands
Miscellaneous commands provide other functionality that has been found to be useful when creating scripts.
CONNECT Command
This command may be used to establish a TCP connection to a nominated host. It is only valid within a script that has been defined as MODE HTTP.
This command specifies an ID for the TCP connection. This may be used in subsequent GET, HEAD, POST and LOAD RESPONSE_INFO commands to use this TCP connection. The TCP connection may be closed using the DISCONNECT command. It will also be terminated when the thread exits the script.
The connection ID specified must not correspond to a TCP connection already established previously using the CONNECT command. Otherwise a script error will be reported.
A character variable, quoted character string or character expression, containing the host name or IP address of the resource to connect to and, optionally, the port number on which the connection is to be made. If a port is specified, it must be separated from the host field by a colon (":"). If the port number field is empty or not specified, the port defaults to TCP 80.
An integer variable, integer value or integer expression defining the connection ID. This is used in all subsequent operations on this connection.
DISCONNECT Command
This command closes one or all of the TCP connections established using the CONNECT command. It is only valid within a script that has been defined as MODE HTTP.
If the "FROM conid" clause is specified, the TCP connection identified by that Connection ID will be closed. If the "ALL" keyword is used, all TCP connections established by the current thread will be closed.
By default, the DISCONNECT command will wait until any requests on the connection(s) to be closed are complete before closing them. If the WITH CANCEL clause is specified, the connection(s) will be closed immediately.
The Connection ID specified must correspond to a TCP connection established using the CONNECT command, otherwise a script error will be reported.
An integer variable, integer value or integer expression identifying the Connection ID of the TCP connection to be closed.
LOAD ACTIVE_THREADS Command
This command allows the number of threads which are currently active on the current Test Manager to be loaded into an integer variable for later use.
The count of active threads includes all threads which are executing either their primary script or a secondary script. It does not include threads which are processing a start-up delay or which are currently suspended.
An integer variable into which the count of active threads is loaded.
LOAD DATE Command
This command loads an integer variable with the number of days since the system base date, or a character variable with the system date.
For character variables, the system date will be loaded in the system default format (for example, "DD-MMM-CCYY"); the date will be truncated as required to fit into the target variable.
The name of a character or integer variable into which the date is loaded.
LOAD NODENAME Command
This command loads the current node name into a variable.
A character variable into which the node name is loaded. The node name will be truncated as required, to fit into the target variable.
LOAD SCRIPT Command
This command loads the name of the script being executed, into a character variable.
A character variable into which the script name is loaded. The script name will be truncated as required, to fill the target variable.
LOAD TEST Command
This command loads the name of the test of which the script is a part, into a variable. The test name will be truncated as required to fit into the target variable. The maximum size of the string returned by this command is 64 characters.
A character variable into which the name of the test is loaded.
LOAD THREAD Command
This command loads the name of the thread on which the script is currently executing, into a character variable.
Declare the character variable at 32 bytes long, using the CHARACTER*32 command. 32 bytes should be long enough to handle most thread names.
The thread name will be truncated as required to fill the target variable if you do not declare a value large enough to cope with the thread names.
A character variable into which the thread name is loaded.
LOAD TIME Command
This command loads a variable with either the number of 10ms `ticks' since midnight (if the variable is an integer variable), or the system time (if the variable is a character variable).
For character variables, the system time will be loaded in the system default format, truncated if the variable is not long enough to hold it.
The name of a character or integer variable into which the time is loaded.
LOAD TIMER Command
This command loads an integer variable with the current value - as a number of 10ms ticks - of the specified timer. The current value of a timer is calculated by taking the time for the latest stop timer and subtracting from it the time for the preceding start timer. If no start timer / stop timer commands have been executed for the specified timer by the current thread an error will occur. This will either abort script execution, or take the specified action if error trapping is enabled via the ON ERROR command.
The timer name. The timer must be declared in a TIMER statement in the Definitions section of the script.
The name of an integer variable into which the timer value - in 10ms ticks - is loaded.
CYRANO Customer Support: France +33 (0) 1 56 33 40 00 USA +1 (978) 462-0737 UK +44 (0) 1274 761024 support-fr@cyrano.com support-us@cyrano.com support-uk@cyrano.com |
![]() |
![]() |
![]() |
![]() |