|
|
|
|
|
This section provides rules that must be followed when writing scripts. They include the syntax, argument structure and types, and address mode and format for script instructions.
Script syntax
The syntax used for a script instruction is an instruction mnemonic followed by any required and optional arguments enclosed in parentheses. There is a convention that appears only in this book and is not part of an actual script. Brackets ([ ]) indicate an optional argument for an instruction.
The following table lists the characters used in the script syntax.
Character |
Meaning |
Example |
parentheses ( ) |
Encloses arguments in an instruction |
|
comma , |
Optional character that separates the arguments of an instruction. You may also use spaces to separate arguments, but the use of commas is strongly encouraged. |
|
period . |
Required syntax character that separates an argument type and argument value |
r.1 – argument type is a register, register number is 1 |
asterisk * or |
Preceding a type, signifies that the value is the number of a script register containing the user space address. Type without an asterisk or ampersand signifies that the value is an address. |
*ch.1 – character string at address in register 1 ch.1024 – character string at address 1024 |
Destination and source arguments
The address modes are represented in the following table.
Address |
Modes |
type.dst |
All types except immediate and time |
type.src |
All types |
ctype.dst |
Only types char and *char |
ctype.src |
Only types char and *char |
Arguments to script instructions
The following is an example of an argument format, where type is one of the argument types listed in the following table, and # is a numerical value or a define statement or an enum symbol:
type.#
You may write numerical values in decimal (256) or hexadecimal (0x100) notation.
Address modes
The data types are summarized in the following table. The values associated with character, short, and integer types represent user space addresses defined in the script or in header files.
Most of the script instructions do not check data typing. Thus, in most instances, the outcome of using character, short, or integer typing has no effect on the outcome of the instruction. The instructions are sensitive, however, to the contents of the specified user space locations. If characters are required, a null-terminated ASCII string must start at the specified address. Similarly, a short integer (2 bytes) or long integer (4 bytes) must start at the specified address if the instruction requires an integer value.
The subsequent instruction descriptions indicate when character values result in or are required by the ctype.dest or ctype.src descriptions. The type.dest or type.src descriptions require short or long integer values. Only the atoi and itoa instructions convert characters to integers and integers to characters.
Although most instructions allow character typing for integer values and integer typing for character values, this practice should be avoided. Integer types must be assigned to even user space byte addresses while character strings may begin at even or odd locations. The integer types are assigned values ranging from -32768 to 32767 (short) and -2147483648 to 2147483647 (int).
In general, an integer variable type (int or short) may be used anywhere that an integer constant (immed) is used. Integer variables allow more flexibility with instruction arguments, but TSM requires more time to retrieve the integer variable values.
Argument Type |
Field Width (bytes) |
Meaning |
Example |
immed1 |
-- |
Actual value, for example, a number, string, or string address |
4, "xyz", 64,"ABC" |
time |
4 |
Operating system time value. A value following (.) is ignored. |
t.0 |
reg |
4 |
Contents of script register |
r.1 |
char |
1 |
Character address in user memory |
ch.VARIABLE |
short |
2 |
Short address in user memory |
sh.SHORT |
int |
4 |
Integer address in user memory |
int.NUMBER |
event |
4 |
Address in event memory |
ev.1 |
*char |
1 |
Register containing address of a character in user memory |
*ch.1 |
*short |
2 |
Register containing address of a short in user memory |
*sh.1 |
*int |
4 |
Register containing address of an integer in user memory |
*int.1 |
*event |
4 |
Register containing address in event memory |
*ev.1 |
&char |
1 |
Register containing address of a character in parent script user memory |
&ch.1 |
&short |
2 |
Register containing address of a short in parent script user memory |
&sh.1 |
&int |
4 |
Register containing address of an integer in parent script user memory |
&int.1 |
script |
- |
Name of script (string). A value following (.) is ignored. |
script.o |
&script |
- |
Name of nearest parent script (string). Null string if there is no parent script. A value following (.) is ignored. |
&script.o |
X |
- |
Data passed using the exec instruction. A value following (.) is ignored. See the exec instruction. |
X.0 |
Chan |
4 |
The channel number on which the script is running. A value following (.) is ignored. |
Ch.0 |
Numbers following the dot (.) in argument specifications may also be expressed as simple arithmetic expressions involving addition and subtraction of integer constants. For example, the argument char.VARIABLE+12 refers to the character string starting at the user memory offset 12 bytes after the offset defined by the VARIABLE symbol. You can also use C-preprocessor # define symbols, positive and negative numbers, and parenthetical expressions.
