Document ID: TC-IEG-050

$Revision: 1.8 $
$Date: 2001/03/04 16:22:35 $

0.0 Contents

1. Introduction
2. Types
3. Variables
4. Statements
5. Expressions
6. Commands
7. Operator
8. Procedures
9. Reference
10. Related Information

1.0 Introduction

1.1 Background

The IEGSE STOL implementation is based on the description of CSTOL given in OASIS-CC CSTOL Reference Manual (v02.05.12). This document attempts to mirror the structure of the OASIS-CC CSTOL reference to minimise any possible confusion.

The major differences between the IEGSE STOL and CSTOL are associated with the commanding of both the instrument under test and the internal IEGSE functions. OASIS-CC took the approach of using parsed English language like commands. The IEGSE implementation takes the simpler method of using command nmemonics which take a fixed number of parameters.

The major omissions from the IEGSE STOL implementation are the statements associated with management of the OASIS-CC databases. The approach taken in the IEGSE is somewhat simpler since it was not designed to scale to much larger systems. Also missing are CSTOL statements which control displays. The IEGSE uses separate components to provide similar functionality.

The CSTOL macro system has been included in the IEGSE implementation, but it's use is deprecated and not documented here.

The aim of the IEGSE STOL implementation has been to keep as strictly as possible to the CSTOL specification, except in clearly identified areas. Extensions are explicitly noted in this document.

1.2 Basics

The STOL system provides the only interface to command the HIRDLS instrument. All command and microprocessor must be sent via the STOL. The STOL system consists of three components :

1. An operator task : This takes STOL instructions input from the IEGSE console keyboard. This is implemented as an always visible window running a STOL interpreter. There can only be one operator task.
2. Procedures : These are sequences of STOL instructions stored in a text file. This allow testing to be done in repeatable and/or automatic manner. The STOL procedure is "compiled" into a intermediate form to allow syntax/error checking and to improve execution efficiency. When a procedure is executed it runs as standalone process in it's own window on the IEGSE console. Only one procedure can actually be executing instructions at a particular time. Other procedures might be loaded but be in paused state. Procedures can start other procedures. The parent waits for the child to finish before continuing execution.
3. A manager task : This organises the procedures and transfers control instructions from the operator to the running procedure or between parent and child procedures.

The CSTOL language has the following basic properties :

• It is case insensitive, except within string typed variables and constants.
• ASCII spaces are used to delimit identifiers (statement directives, variables. constants), i.e. spaces cannot be used within variable names, constants etc.
• The specification implies that there is an asynchronous control available to a running CSTOL procedure. This is provided in the IEGSE STOL implementation by the operator task. The operator task can be used to start procedures and manipulate their execution in a more restricted manner than that allowed under OASIS-CC CSTOL. This is discussed in detail in the later sections describing the STOL operator and procedures.

2.0 Types

There are effectively eight different data types defined by CSTOL. The following sections describe them.

2.1 Integer numbers

The CSTOL integer type is a signed 32-bit entity, i.e. has a valid range of -2147483647 to 21474836476. Integer constants can be expressed in a non-decimal radix as shown in the table.

Radix	Prefix	Example(s)
Decimal	D# or none	156 -67 D#156
Binary	B#	B#10011100
Octal	O#	O#234
Hexadecimal	X#	X#9C

2.2 Real numbers

Floating point numbers are stored internally has 64-bit entities. However the floating point representation of any imported data (e.g. after conversion to engineering units) is limited to single precision values (32-bit) i.e approximately -1.0e+38 to 1.0e+38. A real constant can be expressed using exponentiation. Examples are :

1.673
-9908.06
4.5e9

2.3 Strings

Text constants are expressed as a string of characters enclosed within double quote (") marks. The value of string is the only part of CSTOL with is case-sensitive. The enclosed text may contain spaces. Examples are :

"ABC"
"table.1"
"Solution is : "

2.4 Clock times

These are used to specify date and time of day. This format is also referred within the IEGSE documentation as a datestring. The format is

year/day_of_year-hour:min:sec

The year and/or day_of_year may be omitted. In this case the current year and current day of the year are used. Examples :

1999/104-20:00:00
/-10:0:0           ; 10 am today
1999/102-6:32:8.9  ; fractional seconds allowed

IEGSE implementation notes:

1. The year, if given, must be the full value not a two digit shorthand i.e. 1999 not 99 (OASIS-CC CSTOL would accept two digit years).
2. Within other parts of the IEGSE software the datestring /-:: is used to identify the current time. This will not work in CSTOL, use the CSTOL special variable $$current_time instead (see section 3).

2.5 Delta times

Delta times specify time intervals. The format is

hour:min:sec

Either or both of hour and min may be omitted. Negative delta times are allowed. Examples

0:10:0      ; 10 minutes
-1:0:0      ; one hour before
::1.25      ; 1.25 seconds

2.6 States

A state constant is represented by a string of characters not enclosed in double quote marks ("). Data items in the IEGSE input_data databases can have a value represented as a state and this data type can be used in CSTOL to test the current state. Examples

OFF
YELLOW_LOW

IEGSE implementation note: There is a potential ambiguity between state values and names of data items in the IEGSE input_data databases. The IEGSE STOL compiler always checks an unenclosed string against the input_data database names before assuming it is a state value.

2.7 Data numbers

This type is used represent raw integer data values imported or acquired into the system. There value range is the same as for integers (see above). Hence the raw value associated with a IEGSE input_data database has this type. A data number constant is distinguished from a integer by adding the suffix DN (can be separated by space from value). Examples :

5 DN
5DN

2.8 Engineering Data

This type consists of a real value and a alpha_numeric string of characters which define the units in which the value is measured. This type is used for the engineering units values of items in the IEGSE input_data databases. Examples

9.1 A     ; 9.1 amps
2.0 V     ; 2 volts
-2.V     ; -2 volts

IEGSE implementation note:

1. The file containing the list of recognised engineering units is identified by the IEGSE configuration variable [stol]:units_file.
2. The value part must contain a decimal point, e.g. attempting to describe nine amps using 9A will fail.

2.9 Unsigned integer numbers [IEGSE extension]

The IEGSE version of CSTOL has implemented an unsigned 32-bit entity, i.e. has a valid range of 0 to 4294967295. Unsigned integer constants are differentiated from signed integer constants by placing a 'U' in front the radix identifier. The following table shows examples/

Radix	Prefix	Example(s)
Decimal	UD#	UD#156
Binary	UB#	UB#10011100
Octal	UO#	UO#234
Hexadecimal	UX#	UX#9C

3.0 Variables

3.1 Global variables

The IEGSE software gathers items from the data streams and places their current/last recorded value in the input_data databases. The name of a input_data database item can be used as a IEGSE STOL global variable. The type taken by a global variable is either data number (raw), state or engineering unit. Some data items value can be represented by more than one type. The type used by default by STOL is given by the database entry for the item. If a valid engineering or state conversion exists for the item that becomes the type of the STOL global variable, otherwise the variable is considered to be a data number. IEGSE STOL extension directiveiegse_force_raw can be used to solve some problems associated with this.

Global variable names have the following properties

• Must start with a letter and be less than 20 characters long
• Consist only of letters, digits and the underscore character (_)

Some typical uses are shown below

write SVA_STATUS     ; prints value of SVA_STATUS
let $i = SCCMDS_RCVCT   ; assigns current value of SCCMDS_RCVCT to a local variable

3.2 Local variables

STOL local variables are used within procedures. Their type is ascertained from the value given in STOL declarestatement used to create them. Local variables are used as working data storage within the procedure and as containers for arguments passed to the procedure (declare reference page for details). Local variable names have the following properties

• Must start with a dollar sign ($)
• Rest of name consists only of letters, digits and the underscore character (_)

3.3 Special variables

Special variables are denoted by having names which begin with two dollar signs ($$). The following table lists the special variables defined by IEGSE STOL.

Name	Type	Readonly	Description
$$current_time	clock time	yes	Contains the current time.
$$loop_count	integer time	yes	Only defined whilst procedure is in loop construction. Contains a count of the number of times the loop has been completed.
$$step_interval	delta time	no	If $$step_mode is set to PAUSE, this variable determines thelength of the pause. Set on a per procedure basis. Default is 0:0:1 (1 second).
$$step_mode	state	no	Controls how the statements in a procedure are executed. Set on a per procedure basis. Valid state values are GO Statements are executed as quickly as possible. This is the default behaviour. PAUSE After each statement execution is paused for a time given by the $$step_interval special variable. WAIT After each statement execution is suspended until a STOL go instruction is issued from the the operator prompt.

4.0 Statements

Like most procedural based programming languages CSTOL consists of statements which control execution flow, allow expressions to be evaluated etc. These statements are described in detail with examples in the reference section. The following subsections give a brief overview.

4.1 Labels

Labels are composed of letters, digits and the underscore character, _. They must start with a letter and end with a colon, :. They can be used to identify points in the procedure and to be the target of GOTO statements.

4.2 Continuation lines

OASIS CSTOL imposes a limit of 80 characters per line. Statements longer than this require the use of the ampersand (&) character to continue the statement on the next line. In the IEGSE STOL implementation the 80 character limit is not imposed.

4.3 Comments

Comments lines are denoted by the semi-colon character (;). All text after a ";" up to the next newline is ignored by the parser.

4.4 Assignment

• DECLARE : assigns local variable
• LET : assigns local or special variable

4.5 Control Flow

4.5.1 Conditional

• IF : starts if clause
• ELSE end if clause
• END IF : ends if structure

4.5.2 Jump

• GOTO : unconditional jump to another part of procedure

4.5.3 Iteration

• LOOP : starts loop
• END LOOP : ends loops
• ESCAPE : loop breakout

4.5.4 User input

• ASK : Requests input from user

4.6 Control and Definition of Procedures

• PROC : Indicates start of procedure code and expected arguments
• END PROC : End of procedure code marker
• COMPILE : Parse procedure and convert to object code which can be run.
• START : Start a procedure
• RETURN/RETURNALL : Leave or stop a procedure
• WAIT : Cause procedure to wait for operator intervention, time to expire, or condition to be met
• GO : Restart procedure after WAIT or other operator interventation request.

4.7 Output

• WRITE : Prints values of expressions and variables to standard output

4.8 IEGSE extensions

These statements are not part of the OASIS-CC defined CSTOL.

• IEGSE_DB_SOURCE
• IEGSE_ENG_DATA
• IEGSE_FORCE_RAW
• IEGSE_HIRCMD_LIMITS
• IEGSE_LOGFILE
• IEGSE_LOGGING
• IEGSE_OUTHEX
• IEGSE_OUTDN_ID
• IEGSE_STALE

5.0 Expressions

CSTOL expressions are constructed in a form which will be familiar to anyone who has experience of almost any procedural programming language, e.g. Fortran, Pascal, Basic.

5.1 Expression Types

Simple Operand

• 2 ; constant
• $LAST_VALUE ; local variable
• SSH_STATUS ; global variable

Function(Operand)

• cos($angle) ; cosine of local variable $angle
• log(2.0) ; natural log of 2

Expression Operator Expression

• $x + 10 ; Simple addition
• IFCBB_TMP1 > 310.0 K ; relational expression
• cos($angle) * $length ; trigonometry

( Expression )

Parentheses used to isolate sub-expression.

• ($x + 10) ** 2 ; Square a sum
• (($my_temp - 273.0) + 32) * 9) / 5.0 ; Convert to "proper" units

5.2 Arithmetic Operators

5.3 Relational Operators

5.4 Logical Operators

These operators are applied to expressions and can also be applied to integer operands to perform bit-wise manipulations.

Operator	Description
not	logical not
and	logical and
or	logical or
xor	logical exclusive or

5.5 CSTOL Predefined Functions

Function	Return Type	Argument Type	Description
ACOS	Engineering units (RAD)	Real	Arccosine
ASIN	Engineering units (RAD)	Real	Arcsine
ATAN	Engineering units (RAD)	Real	Arctangent
COS	Real	Engineering units (RAD or DEG)	Cosine
COSH	Real	Engineering units (RAD)	Hyberbolic Cosine
EXP	Real	Real	Natural exponential (e raised to the power of the argument)
LOG	Real	Real	Logarithm to base e
LOG2	Real	Real	Logarithm base 2
LOG10	Real	Real	Logarithm base 10
SIN	Real	Engineering units (RAD or DEG)	Sine
SINH	Real	Engineering units (RAD)	Hyperbolic Sine
SQRT	Real	Real	Square Root
TAN	Real	Engineering units (RAD or DEG)	Tangent
TANH	Real	Engineering units (RAD)	Hyperbolic Tangent

5.5 Evaluation precedence

The order of evaluation of expressions is as follows

• Sub expressions within parentheses, including functions, inner most first.
• Operator with highest precedence first.
• Operators of equal precedence evaluated left to right.

5.6 Operator precedence

• Unary minus and logical not
• Exponentiation
• Multiplication and division
• Addition and Subtraction
• Relational operators
• Logical operators except not

6.0 Commands

The major difference between OASIS-CC CSTOL and IEGSE STOL concerns the sending of commands. All of this section refers only to the IEGSE STOL implementation. IEGSE users should not expect anything in the CSTOL reference manual to be applicable in this area.

6.1 Command categories

Commands are grouped into three categories, there is an IEGSE database for each category. Each command has a unique nmemonic which identifies the record where the command properties are specified.

Command Category	Nmemonic prefix	Command Parameter Restrictions	Restricted Command Classes
HIRDLS instrument	HIR	Unsigned integer only	CRITICAL
Internal IEGSE subsystems	GSE	None	CRITICAL OPERATOR_ONLY
External test equipment	TEQ	None	CRITICAL OPERATOR_ONLY

The database defines command properties on per category basis. By default all commands can be sent from either the operator window or from within procedures except where specified to be class OPERATOR_ONLY. All class CRITICAL commands require a confirmation to be given via the operator window before the comamnd is dispatched.

6.2 Command statement format

All categories of commands are sent using the following statement format. The statement identifier is the "at" (@) character.

6.3 Upload of commands from files

Some HIRDLS commands have arguments which cannot be expressed as 32 bit integer values formatted into strings of digits, e.g. memory loads. To send these commands an upload file has to be prepared using the uplink_p utility. The file can then be sent to the instrument using the LOAD statement.

7.0 STOL Operator Task

The whole of this section should be considered to be an IEGSE implementation note.

7.1 Operator window

The STOL operator task runs in it's own X window on the IEGSE central node console. The window is always visible (non-minimisable and "sticky"). It's realisation is shown below.

The user types directives at the CSTOL prompt. The task supports a subset of EMACS style command-line editing and command history manipulation provided by the GNU readline library. On start up the operator task loads the command history saved in the file identified by the [stol]:operator_hsty file. This file contains the last 100 commands entered prior to the operator task being killed.

A few of the most useful character sequences are listed here.

• Up/Down Arrow : Move forward/back through command history.
• Right/Left Arrow : Move input cursor one character to right/left.
• ESC d : Delete word.
• CTRL-A : Start of current input.
• CTRL-E : End of current input.
• CTRL-U : Delete current input.
• DEL : Delete last character

7.2 Operator STOL directives

The following are the list of directives which may be executed from by the STOL operator. There are reference pages for each directive and some of them are described in the procedures section below.

• COMPILE : Parse procedure and convert to object code which can be run.
• @ : Dispatch an instrument, test equipment or IEGSE command.
• GO : Restart procedure after WAIT or other operator interventation request.
• LOAD : Send a upload file containing one or more instrument commands
• START : Start a procedure
• RETURN : Kill the currently executing procedure.
• RETURNALL : Kill the currently executing procedure and the rest of it's chain (i.e. all it's ancestors).
• WAIT : Pause the currently executing procedure.

8.0 Procedures

As briefly described in the introduction procedures are sequences of STOL instructions which are stored as a text file and hence can be executed in a repeatable manner. Therefore they are key component when developing a structured and controlled instrument test platform.

8.1 Procedure Structure

A CSTOL procedure has the following structure.

PROC proc_name [ parameter_list ] 
; Declaration section start
   
	
    
; Declaration section end
BEGIN
; Executable statements start

; End of procedure
END PROC

IEGSE implementation note:

The name of the file containing the procedure must be of the form name.pro, where name is proc_namewith letter characters converted to lowercase.

8.1.1 Declaration Section

All local variables and input parameters must contain an entry in this section. See the DECLARE reference page for full details.

8.1.2 Executable Section

The BEGIN statement identifies the boundary between the declaration section and the executable section. The statements in this section are executed until either a RETURN statement or the END PROC is reached.

8.2 Procedure Compilation

The procedure must be compiled into an interpretable object format before it can be executed. This process allows syntax and other error checks to be performed on the procedure before it is run. The STOL directive COMPILE is provided for this purpose.

IEGSE implementation note:

Procedure source files can be stored in a number of different path locations in the IEGSE central node filesystem. The search order is given by the configuration parameter [stol]:srcdir. If a file name name.pro is not found in a directory specified by [stol]:srcdir the users own directory $HOME/stol is then searched.

8.3 Procedure Execution

8.3.1 Starting a procedure

Procedures are started using the START directive.

IEGSE implementation notes:

• Procedure object files are stored in a number of different path locations in the IEGSE central node filesystem. The search order is given by the configuration parameter [stol]:objdir. If a file name name.obj is not found in a directory specified by [stol]:objdir, the search for the file continues in directories given by [stol]:srcdir and then finally in the users own directory $HOME/stol.
• There can be up to 24 procedures started at any time. However, only one can be executing instructions. Each procedure started from the STOL operator task heads a procedure chain. If a procedure is executing when the operator starts a new procedure the running procedure goes into an unconditional wait state. The new procedure is then the head of the current chain. Once the new chain completes the previous chain adain becomes the current chain, but since it is in a unconditional wait state it requires a GO to be sent by the operator before it restarts execution.
• A procedure may start other procedures which in turn can also start procedures. A measure of the length of the current chain is the nesting level (the first procedure started from the operator has nesting level 1). The IEGSE STOL implementation will develop problems (associated with the X-windows environment) when the nesting level is greater than 4. There is no compile time mechanism to detect this problem, hence users must make it their responsibility not to breach this limit.

8.3.2 Procedure execution environment

The whole of this section should be considered to be an IEGSE implementation note. Each procedure is a standalone POSIX (Unix) process. It runs within it's xterm window on the IEGSE central node console. The realisation on the screen is shown below. The window is non-minimisable, cannot be resized and does not have a scrollbar.

8.3.2.1 Procedure window layout

The procedure window is split into three areas.

INFORMATION LINE

The top line of text is in inverse video and contains the following information, reading from left to right

• Parent procedure name : CONSOLE means started directly by operator.
• Nesting level : In this 1 shows that this procedure is head of chain, i.e. started directly by operator.
• Current execution line
• Current execution state : in this case in a timed wait (see table).

PROCEDURE CODE

Two thirds of the window is allocated to showing the executing code. The currently executing line is shown in inverse video.

I/O WINDOW

The remainder of the window contains the output of STOL WRITE, the input and output associated with ASK statements and any internally generated information or error messages.

When the procedure exits, either by reaching a RETURN or an END PROC statement, receiving a RETURN from the operator or exiting due to error, the procedure indicates this by changing the window title and foreground and background colours as shown below.

8.3.2.2 Moving around the procedure window

When the procedure has exited or is in an wait state it is possible to use scroll through either the procedure code or the I/O windows by using the following instructions :

1. The procedure window must be made the input focus of the window manager. Unless the default window manager setup has been changed this is achieved by clicking the left mouse button in the procedure window.
2. Type CTRL-Z. An asterisk (*) character should appear in the top left corner of the window on the information line.
3. The up and down arrow keys can be used to move around the procedure code section of the window.
4. The o and p keys can be used to change between the I/O and procedure code sections respectively.
5. Typing CTRL-Z returns the window and the cursors to their original states.

8.3.2.3 Removing the procedure window

The procedure window can be removed once the procedure is in the EXITED state by following the instructions below.

1. The procedure window must be made the input focus of the window manager. Unless the default window manager setup has been changed this is achieved by clicking the left mouse button in the procedure window.
2. Type CTRL-C. The window will now disappear.

All procedure windows are removed automatically when the IEGSE software is stopped using the iegse_stop utility.

8.3.3 Procedure execution states

The following table describes the allowed procedure execution states. The execution state is displayed in the top right corner of the procedure window.

Execution State	Description
ASK	Procedure is awaiting input in response to a STOL ASK statement.
EXITED	Procedure has completed execution.
LOADING	Procedure is loading object code and initialising internal structures.
RUNNING	Procedure executing instructions.
WAIT_COMM	Procedure is awaiting confirmation to send a critical command. Requires a GO command from the operator to continue execution.
WAIT_COND	Procedure is waiting for a condition to become TRUE before continuing.
WAIT_OPER	Procedure is in unconditional wait. Requires operator to send GO to continue execution.
WAIT_TIME	Procedure is in a timed wait.

9.0 Reference

This is now a separate page : IEGSE STOL Reference Guide. The index of statements gives direct links to the appropriate section of the reference guide.

@	ASK	BEGIN	COMPILE	DECLARE
ELSE	END IF	END LOOP	END PROC	ESCAPE
GO	GOTO	IF	IEGSE_DB_SOURCE	IEGSE_ENG_DATA	IEGSE_FORCE_RAW	IEGSE_HIRCMD_LIMITS
IEGSE_LOGFILE	IEGSE_LOGGING	IEGSE_OUTHEX	IEGSE_OUTDN_ID	IEGSE_STALE
LET	LOAD	LOOP	PROC	RETURN
START	WAIT	WRITE

10.0 Related Information

• gse_data_if
• HIRDLS command list
• IEGSE command list
• IEGSE STOL Reference Guide
• STOL configuration component
• Test equipment command list
• uplink_p

Return to IEGSE Home

Document ID: TC-IEG-050

Modified --> $Revision: 1.8 $ $Date: 2001/03/04 16:22:35 $