Script Language Components

Script language is composed of "commands" and "values." Commands are words that have special meaning in script language. Values are pieces of data in the form of variables, strings, numbers, or file names. A "statement" is an instruction that performs an action; it has at least one command, and some statements have parameters. A "parameter" is the object of the statement and may be a keyword, a value, or a combination of keywords and values. You can sometimes think of statements as having verbs and objects. For example, in the statement GET _author, GET is the verb (command) and _author is the object (parameter).

The components and conventions used to describe the STN script language are:

• Commands and keywords are shown in uppercase letters, e.g., EXIT and SECONDS.
• Strings are shown in lowercase letters inside double quotation marks. For example, in the statement SEND "string", SEND is a command, and string is a string value. You may use a variable wherever you can use a string.
• Variables are shown in lowercase letters with a preceding underscore. For example, in GET _var1, GET is a command and _var1 represents the name of a variable.
• Operators are shown in uppercase letters, e.g., AND.
• Labels are preceded by an @ character and identify a location in a script so that other statements can refer to that location.
• Numbers are denoted by lowercase letters. For example, in the statement PAUSE n, n represents a number.
• Optional parameters are shown inside square brackets. For example, PAUSE n [SECONDS] means the PAUSE statement has a required parameter, n, and an optional keyword, SECONDS. Do not type the brackets when you type the parameter or keyword. Note: When there is a choice of parameters or values, the choices are enclosed in braces, and a vertical bar separates the choices. For example, in the statement CAPTURE {ON | OFF}, the keyword ON or the keyword OFF follows the CAPTURE command.
• File names are shown within angle brackets. For example, DELETE <file name>. You may use a variable whose value is a file name wherever you can use a file name.
• Comments are preceded by \* and continue through the ends of their lines. The script processor ignores comments.

Notes:

• Example scripts and statements are shown in a fixed-width font.
• Script output and results are shown in a bold font.
• A block is either a single statement or a group of statements enclosed by BEGIN and END.

See Script Syntax Requirements for additional information on organizing scripts and writing statements.

Script Character Strings

Textual data is enclosed in double quotes and can be a string up to 140 characters long. You may continue a string on a new line by typing a backslash, \, at the end of the line.

To use the value of a string variable, type the variable along with the text. Place double quotes around the entire string.

For example:

_s = "how to use"

ECHO "This is _s a variable in a string."

displays:

This is how to use a variable in a string.

Variables within strings are replaced by their values, converting integers to text. The # operator, along with a variable, is replaced by the number of answers in the answer set and is converted to text.

If you want a variable within a string to be immediately followed by non-blank text, separate the variable name and text with a period.

For example:

_variable = "con"

ECHO "This example string includes

_variable.concatenated text"

displays:

This example string includes concatenated text

Special characters and escape characters within strings are:

[CR]	Carriage return
[TAB]	Move to next tab position
[BS]	Backspace
[ESC]	Escape
[BELL]	STN file environment on entry to the script
[CRTL-A]...[CTRL-Z]	Unprintable control characters
[FF]	Formfeed

Note that many networks and STN use control characters in normal operations. As a result, indiscriminate use of control characters may result in lost data, locked sessions, or terminated processes.

The characters _, \, ", [, and # have special use within the script language and must be doubled if they are to be used within a string. In other words, to include a [ in a string, use two in a row:

ECHO "Here is a string with a left bracket (i.e., [[) in it."

displays:

Here is a string with a left bracket (i.e., [) in it.

A distinction between upper- and lowercase is made when the characters are within a string, and the number of spaces between words and letters is not ignored.

Script Variables

A variable is a name for a place to store information. Specifically, a variable can store a number, a string of characters, a file name, or the L-number result of a search. Use a variable when a specific value is unknown or will change within a script. For example, if you write a script that performs an author search, make the script flexible by using a variable for the author’s name instead of typing the author’s name in the script.

Variables are named with an underscore followed by 1 to 20 alphanumeric characters. They are considered "declared" after their first use. A variable cannot reference another variable, and there is no capacity for arrays.

Variable names are not case-sensitive. For example, the variable named _var is the same as the variable named _VAR.

Variables are always considered to be of type string (text), except for variables that represent search results (L-numbers). Variables are automatically converted to numbers (integers) when necessary for arithmetic operations or conditions. Attempts to perform arithmetic operations on non-numeric text result in errors when the script is run.

To give a variable a value, use an assignment statement or the \> operator, described at the => statement. See also the # operator, explained under the => statement.

Up to 1000 variables are permitted within a script. If there are more variables, this is noted when you run the script online rather than when you use Check Command File.

Variable values may not exceed 255 characters in length.

There are predefined logon setup variables and predefined STN variables.

Script Operators and Conditions

Operators and conditions are elements that manipulate and compare pieces of data.

Arithmetic Operators

Operators and conditions are components of statements. Arithmetic operators manipulate the values of numbers. "String operators" work on text strings. Conditional operators compare the values of strings and numbers in IF statements. Compound conditions are built with logical operators. Special operators are used in specific situations.

+	addition	add two numbers
-	subtraction	subtract one number from another
*	multiplication	multiply two numbers
/	division	divide one number by another

String Operators

Use the arithmetic operators in assignment statements to perform arithmetic on numbers. The arithmetic operators do not function inside strings or conditions.

+	concatenation	join two strings (not inside double quotation marks)
-	concatenation	denote the end of a variable name inside double quotes

Conditional Operators

To control execution of a statement or a set of statements based on the value of a variable, use an IF statement with a condition. A condition compares the values of two variables or a variable and a literal number or literal string.

All operators are binary, and the general syntax is A operator B.

If both A and B are integers, comparison is based on their numerical values. Otherwise, an alphabetic comparison is made.

All string comparisons are case-sensitive. That means "salt" is not equal to "SALT".

Numbers and Strings

=	equality	numbers or strings are equal
<>	inequality	numbers or strings are not equal

Numbers

>	greater than	A is greater than B
<	less than	A is less than B
>=	greater than or equal	A is greater than or equal to B
<=	less than or equal	A is less than or equal to B

Strings

INCL	includes	string A includes string B
NOTINCL	does not include	nstring A does not include string B

Example 1

_s = "string"
IF _s = "string"	\* True
IF _s = "string "	\* False
IF _s = "STRING"	\* False
IF _s INCL "ring"	\* True
IF _s INCL "Ring"	\* False
IF _s NOTINCL "cow"	\* True

Example 2

_var1 = 10
_var2 = 5 + 5
IF _var2 = _var1	\* True
IF _var2 <> _var1	\* False
IF _var1 > 0	\* True
IF _var2 < 4	\* False
IF _var1 >= 10	\* True
IF _var1 <= 10	\* True

Compound Conditions

Compound conditions may be formed from multiple conditions using logical operators. Use parentheses to group and nest conditions up to eight levels deep.

AND	logical and	both A and B
OR	logical or	either A or B or both
XOR	exclusive or	either A or B, but not both

Example

_answers = 42
_dformat = "bib"
IF ((_answers < 100) AND (_dformat = "bib"))	/* True
IF ((_answers < 100) AND (_dformat = "all"))	/* False
IF ((_answers < 100) OR (_dformat = "ide"))	/* True
IF ((_answers < 15) OR (_dformat = "ide"))	/* False
IF ((_answers < 100) XOR (_dformat = "bib"))	/* FALSE
IF ((_answers < 100) XOR (_dformat = "ide"))	/* True

Special Operators

\!	Edit	Edit a command before sending it to an online host (=> statement).
\>	L-number	Assign the L-number result of a command to a variable (=> statement).
#	answer count	Retrieve the number of answers from an L-number variable.
EXISTS	file existence	Determine whether a given file exists. EXISTS first checks the User Scripts folder and then Scripts folder. It sets _$filerror to zero if the file exists and to a nonzero value if the file does not exist.

Script Labels

A "label" or "statement label" identifies a line in a script so that other statements can refer to that line. Labels are named similarly to variables except that they begin with the @ character. The following are examples of valid labels:

@start

@error

Refer to the CONTINUE, GOTO, and GOSUB statements for examples of how to use labels.

Script Numbers

The Script Language supports integers; there are no decimals or fractions. Type whole numbers in an ordinary way. For example:

_var = 42
IF _var < 100 THEN

To use a negative number, subtract a positive number from zero:

_neg = -1\* not allowed
_neg = 0 - 1
IF _neg < 0 THEN

Script File Names

For transcript or data files on your PC, enclose file names within angle brackets, < >. All characters within the brackets are taken literally, but underscore characters are not allowed. File names may be stored in variables. For example:

CAPTURE ON <transcript> \* a literal file name

_var = <new script>     \* assign a file name

                        \* to a variable

EXEC _var        \* execute a script

                 \* whose name is in _var

CAPTURE OFF <>

Script Syntax Requirements

The STN script language has a few rules for organizing scripts and writing statements:

• More than one statement may appear on the same line, or each statement may be typed on its own line.
• Commands in the script language are not case-sensitive. For example, the EXIT statement may be written EXIT or exit.
• Uppercase and lowercase are significant in character strings. For example, "Yes" is different from "yes".
• Blank lines may appear anywhere.
• Blanks and space characters may appear anywhere. However, they are significant in strings (inside double quotes). For example, "sodiumnitrate" is different from "sodium nitrate."
• A single script statement can be 140 characters long. To continue a statement on the next line, put a backslash, \, at the end of each line that is continued on the next line.
• Enclose strings in double quotes.
• Comments are notes that describe or explain the script, and they are ignored by the script processor. Comments begin with \* and continue until the end of the line. Comments may appear on lines of their own, or they may appear at the end of any statement except the Prompt statement.
• STN commands can be up to 292 characters in length.