cstol

Copyright 1986, 1992By the Regents of the University of Colorado

OASIS-CCOperations and Science Instrument Support

Command and Control

CSTOL Reference Manual

For OASIS-CC V02.05.12and subsequent versions

November 1994

Copyright 1986, 1992By the Regents of the University of Colorado

OASIS-CCOperations and Science Instrument Support

Command and Control

CSTOL Reference Manual

Permission is granted to make and distribute verbatim copies of this manual provided that thecopyright notice and these paragraphs are preserved on all copies. The software and anyaccompanying written materials are provided “as is” without warranty of any kind. The Universityof Colorado disclaims all warranties of any kind, either expressed or implied, including but notlimited to implied warranties of merchantability and fitness for a particular purpose.

Mention of any commercial company or product in this document does not constitute anendorsement by the University of Colorado.

OASIS-CC CSTOL Reference Manual Table of Contents

i

Laboratory for Atmospheric and Space Physics University of Colorado at Boulder

Table of Contents

1. Introduction .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1About CSTOL ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1Using CSTOL... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2About This Manual.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Manual Conventions.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-32. Building Blocks .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

CSTOL Character Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Identifiers.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3Constants .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Literals .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3States .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Integers .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Data Numbers .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Real Numbers .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6Engineering Units.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Clock Times .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Delta Times.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8Strings .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8

Variables.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8Global Variables .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8Local Variables.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10Special Variables.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10Global Special Variables.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10CLP Special Variables .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14Procedure Special Variables.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17Other Special Variables .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17

3. Building CSTOL Statements .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Labels .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Directives.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Table of Contents OASIS-CC CSTOL Reference Manual

ii

University of Colorado at Boulder Laboratory for Atmospheric and Space Physics

Qualifiers .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Arguments .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Clauses .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Argument Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Range Specifications.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Input Lines.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4Comments.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

4. Summary of CSTOL Statements.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Expressions.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Control Structures .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Procedures.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Macros .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3Commands .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3Communications.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4User Input/Output .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4Database Management.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5Program Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

5. Expressions .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1Operators .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Arithmetic Operators .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2String Operators.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Relational Operators.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Logical Operators.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Order of Evaluation .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5Data Types in Expressions .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6Functions .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

Trigonometric Functions.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7Inverse Trigonometric Functions .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7Hyperbolic Functions.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8Miscellaneous Functions.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8

Using Expressions.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9Assignment .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9IF-blocks .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10Indefinite Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10Timed Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10Conditional/Timed Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11Command Execution Verification Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11Positional Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11


iii


Input to CSTOL... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12Output to the User .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

6. Control Sequences .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1IF-Blocks .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1Loops.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

7. Procedures.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1The Form of a CSTOL Procedure.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

Declarative Section .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2Executable Section.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3

Preparing a Procedure .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3Installing a Procedure.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3Compiling a Procedure .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4Starting a CSTOL Procedure .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5Controlling a CSTOL Procedure .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6

Suspending Procedure Execution.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6Setting Breakpoints in a Procedure.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7Resuming Execution of a Suspended Procedure.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7Terminating a Procedure.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7Procedures and Special Variables .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7Determining the Status of CSTOL Procedures .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10

8. Macros.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1The Form of a CSTOL Macro .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1Preparing a Macro.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2Installing a Macro .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2Macro Definition .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3Invoking a Macro.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3Determining Macro Status .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3Example Macro.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4

9. Commands .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1Basic Commands .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1Qualifying and Quantifying Commands .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

Clauses .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2Qualifying Keywords.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3

Unchecked Bit pattern and ASCII Commands .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4Timed Commands.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5Priority Commands.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5Command Messages .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6Microprocessor Loads .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6


iv


10. Description of CSTOL Statements.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1ASK ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2BEGIN... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3CANCEL ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4CHECKPOINT ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5CLEAR ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7CHECK... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8Commands .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10

Basic Command Syntax.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10Clauses and Keywords .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11Timed Commands .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12Priority Commands .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12

COMMIT... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14COMPILE... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-15CSTOL OFF ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16DECLARE ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17DECOMPILE... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19DEFINE ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20DELETE... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21DISPLAY ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-22ELSE... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24ELSE IF.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25END... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26

END IF ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26END LOOP... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26END MACRO.... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26END PROC... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-27

ESCAPE... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28FLUSH... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29GO... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30GO TO ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31IF ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32INITIALIZE ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33INSERT... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34LET... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-35LOAD.... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-37LOCK... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38LOOP ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-39


v


MACRO .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-40MAKE ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-41MESSAGE ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-42POLL... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-43PROC ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-44RECORD.... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-45REPORT... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-47RESTORE... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-48RETRIEVE... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-49RETRY ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-51RETURN ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-52ROUTE ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-53RUN... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-54SAMPLE ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-56SEND ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-57SHOW .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-58SNAP ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-59START... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-60STOP POLLING BUS... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-61STOP RECORDING... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-62STOP RETRIEVING ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-63STOP ROUTING... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-64STOP SAMPLING... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-65SWITCH... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-66SWITCH RECORDING ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-67UNDEFINE ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-68UNLOCK.... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-69UPDATE ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-70WAIT ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-71WAIT AT... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-73WAIT FOR... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-74WRITE... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-76

Appendix A. Control Language Processors .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Automatic CLPs.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Automatic and User CLP Differences .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2

Sub-CLPs ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

Initiation of Sub-CLPs ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3


vi


User Control of the Sub-CLPs ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

Appendix B. Operator-Operand Compatibility .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Appendix C. Adding Command Verbs to the Parser.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

OASIS-CC CSTOL Reference Manual 1. IntroductionRev 0 – 11/94

1-1


1 . Introduction

The Operations and Science Instrument Support Command and Control (OASIS-CC)teleoperations package uses the CSTOL system control language. CSTOL is not aprogramming language. Instead, it resembles the command languages one encounterswhen signing onto a system. These general-purpose command languages include DCL forVAX/VMS, C-Shell and Bourne Shell for Unix and the MS/DOS command language.While these languages perform operations like listing files in a directory and displaying thecontents of text files, CSTOL provides functions to monitor and control spacecraft, spaceinstruments and their ground support equipment.

About CSTOLCSTOL is an enhanced version of the System Test and Operations Language (STOL).STOL, an important part of several spacecraft test and operations systems, originated atNASA's Goddard Space Flight Center. CSTOL retains the advantages of STOL —particularly its simplicity — but is easier to use. Improvements include:

• A distinctly English-like syntax;

• The ability to access database tables using a query language;

• A mechanism for expanding the language through macros.

CSTOL users may perform the following functions:

• Evaluate expressions with data item variables from the spacecraft or instrument;

• Make decisions based on information returned by the spacecraft or instrument;

• Initiate and control procedures written in CSTOL;

• Initiate OASIS-CC and system utility programs;

• Maintain the OASIS-CC database;

1. Introduction OASIS-CC CSTOL Reference ManualRev 0 – 11/94

1-2


• Call and terminate displays;

• Make and break communications links;

• Send commands to the spacecraft or instrument.

Using CSTOLUsers communicate with the OASIS-CC teleoperations package through CSTOL. Whenusers enter OASIS-CC, a window for entering CSTOL statements appears on the screen.Text entered here is sent to a Control Language Processor (CLP). OASIS-CC has oneCLP for each user to accept and perform the actions specified within CSTOL statements.The CLP performs the action or calls the appropriate OASIS-CC task. For example, theCLP may evaluate arithmetic expressions and initiate and control procedures while tasksmay issue commands, control data acquisition and call displays.

Users may create CSTOL procedures and macros — sequences of CSTOL statementsstored in a file and executed repeatedly (see Chapters 7 and 8).

CSTOL may also be used indirectly. For example, OASIS-CC is indifferent to selectionsmade from the TAE+ interface or the keyboard. When the user selects an OASIS-CCTAE+ action item, the selection is translated to a CSTOL statement and passed to the CLP.

CSTOL may insert CSTOL statements into certain database tables. The records in thesetables define conditions that require quick responses. When a condition occurs, theassociated CSTOL statement is automatically executed. System managers usually enterCSTOL statements into database tables. See the OASIS-CC System Manager's Guide.

OASIS-CC may execute procedures using background CLPs (sub-CLPs). Appendix Adescribes the variety of CLPs within OASIS-CC.

About This ManualThis manual describes the CSTOL language as implemented within OASIS-CC and may beused as both a tutorial for new users and a reference guide. Chapters 2 through 9 beginwith basic language components — how to form words and statements in CSTOL — andprogress to more advanced topics such as expressions, procedures, macros andcommands. Chapter 10 describes each type of CSTOL statement in detail.

OASIS-CC CSTOL Reference Manual 1. IntroductionRev 0 – 11/94

1-3


Manual Conventions

CSTOL format specifications, particularly for the different types of statements, occurthroughout this manual. The following typographic conventions are used:

• Words and phrases within CSTOL statements appear in capital letters. Thisconvention is used mainly for directive names (ENABLE and STOP SAMPLING)and words that introduce qualifying clauses (TO and WHERE). All sample CSTOLstatements appear in upper case type.

• Italicized type distinguishes terms that represent a class of item. For example,integer-constant means to insert an integer constant here. A format specificationexplains what to substitute for each italicized term.

• Square brackets denote optional components.

The following example uses all conventions:

DECLARE VARIABLE name = default-value [value-range]

DECLARE VARIABLE must appear as shown, while the variable name is represented byname. A data value from an optional value range replaces default-value. The [value-range]is optional.

1. Introduction OASIS-CC CSTOL Reference ManualRev 0 – 11/94

1-4


This page is intentionally blank.

OASIS-CC CSTOL Reference Manual 2. Building BlocksRev 1 – 11/94

2-1


2 . Building Blocks

This chapter explains the formation of different word and number classes, the basiccomponents of CSTOL statements.

CSTOL Character SetPrintable ASCII characters compose words and statements in CSTOL. Use the followingcharacters to construct CSTOL statements:

• Alphabetic characters, the letters A to Z in upper or lowercase. CSTOL is caseinsensitive, treating upper and lowercase characters identically. The followingstatements are equivalent in CSTOL:

TURN OFF HEATER_1

TURN OFF heater_1

turn off heater_1

Turn Off Heater_1

• The decimal digits 0 - 9.

• Special characters to act as mathematical operators in expressions or stringdelimiters:

Blanks separate CSTOL statement components. Blanks may not appear withinidentifiers or numbers.

Tabs may appear blanks do. Do not use tabs if possible. Their expansion istypically computer and display-device dependent.

Underscores, _, connect words to form meaningful identifiers likeHIGH_VOLTAGE.

2. Building Blocks OASIS-CC CSTOL Reference ManualRev 1 – 11/94

2-2


The dollar sign, $, denotes local and special variables. Local variable names useone dollar sign — $TEST_VOLTAGE — while special variable names use two —$$COMMAND_MODE.

Double quotation marks, "", delimit text strings.

Parentheses, ( and ), set off parts of an expression.

The left angle bracket, <, expresses 'less than' within relational expressions.

The right angle bracket, >, expresses 'greater than' within relational expressions.

The plus sign, +, expresses addition within arithmetic expressions as well as stringconcatenation.

The dash or minus sign, -, expresses subtraction and negation within arithmeticexpressions. It also separates the date from the time in clock time constants.

The asterisk, *, expresses multiplication within arithmetic expressions.

The slash, /, expresses division within arithmetic expressions and part of 'not equalto' within relational expressions. It also separates the year from the day in clocktime constants.

The equals sign, =, expresses assignment within LET statements and "equal to"within relational expressions.

The pound sign, #, is the radix indicator in non-decimal integer constants.

The ampersand, &, is the continuation marker, indicating when to continue astatement on another line.

The colon marks the end of statement labels and separates the low and high valuesin range specifications and the hours, minutes and seconds in clock time and deltatime constants.

The semicolon is the comment indicator, marking the start of a comment on a line ofinput.

The comma separates arguments within argument lists.


2-3


IdentifiersIdentifiers are alphanumeric names. Identifiers have the following uses:

• Literal constants

• State constants

• Units in engineering unit numbers

• Variable names

• Labels

• Directive names

Identifiers consist of one to 16 characters. The first character must be a letter. anycombination of letters, digits and underscores may follow the first character. For example:

ENABLE

STEPPER_MOTOR

PLUS7_VOLTS

ConstantsConstants are character strings that supply values. CSTOL contains eight constant types.Two types — literals and states — are identifiers. The others are numeric constants —integers, data numbers, reals, engineering units, delta times and clock times plus one thatrepresents general text strings. Each of these constant types is described below.

Literals

Literals are constructed from identifiers and used as qualifying arguments in statements.They indicate the option being selected. For example, the CLEAR ALL statement, usesthis format:

CLEAR ALL window-type

The window-type argument is replaced by one of these literals: DISPLAYS, MESSAGES,COMMANDS or REPORTS.


2-4


States

Like literals, states are identifiers that indicate the option being selected. Unlike literals,states describe values that state variables can assume. The OASIS-CC State_Conversionsdatabase table defines state values allowed for a global variable. Use the DECLAREstatement to define the state values allowed for a local variable. For example:

LET $INST_STATE = OFF

SET FAN SPEED TO LOW

The first example presents OFF, a state constant assigned to the local variable$INST_STATE. LOW, in the second example, is a state variable that specifies the fanspeed.

Integers

Integer constants are whole numbers in the range, -231 to +231-1. Integers are usuallyexpressed using standard decimal notation. For example:

0

+123

-145789232

Decimal integers may be preceded by a plus or minus sign. Blanks, commas andmagnitudes greater than 231 are not allowed. The following decimal integers are not legal:

12 34 — No blanks allowed.

123,456,789 — No commas allowed.

99999999999 — Magnitude greater than 231 not allowed.

Integer numbers may be alternately expressed in binary, octal, decimal and hexadecimalradix notation. radix notation uses this general format:

radix# value

In this notation, radix equals a radix character while value equals a string of digits in theappropriate range for the radix:


2-5


• B = Binary: valid digits are 0 and 1

• O = Octal: valid digits are 0 - 7

• D = Decimal: valid digits are 0 - 9

• X = Hexadecimal: valid digits are 0 - 9 and A - F. Interpreted as an unsignedinteger

• H = Hexadecimal: valid digits are 0 - 9 and A - F – used in raw binary SENDcommands

Although decimal integers are usually written using the default decimal syntax, they may beexpressed using the D radix.

The following examples present integer numbers equivalent to the decimal value 45 in radixnotation:

B#101101

O#55

X#2D

Data Numbers

Data numbers are integer constants that represent raw, uncalibrated values like thosereturned by spacecraft equipment sensors. Data numbers have this format:

integer-number DN

Within this format, integer-number is expressed in the standard decimal or radix notation.For example:

123 DN

B#11010010 DN

The OASIS-CC package permits signed or unsigned data numbers from 1 to 64 bits inlength. However CSTOL only manipulates these numbers up to 32 bits in length.


2-6


Real Numbers

Real numbers represent whole and fractional values. They have the range and precision ofdouble precision words on the host computer running OASIS-CC. (NOTE: The exceptionto this rule is that the floating point data stored in the Latest_Data table are single precision.)Real numbers use a scaled or unscaled format. Unscaled real number are expressed usingthese formats:

[ sign ] integer . [fraction]

[sign] . fraction

If present, the optional sign must be plus (+) or minus (-). If a sign is not given, a positivevalue is assumed. Integer is a string of one or more decimal digits, while fraction is astring of zero or more decimal numbers following the decimal sign. If the integer ismissing, one or more digits in the fraction part must be supplied . See the followingexamples of unscaled real numbers:

3.14159

.645

-2453

Scaled real numbers are a computer version of scientific notation — real numbers withexponent specified. They have this format:

unscaled-real-number E nninteger-number E nn

Within this format, nn is a decimal integer exponent that indicates a power of ten used toscale the number. Positive values multiply the number while negative exponent valuesdivide the number by the specified power of 10. The following examples represent thevalue of π:

314.159E-2

.00314159E3

3.14159E0


2-7


Engineering Units

Engineering units are scaled or unscaled real numbers with units of measurement explicitlystated. They usually represent the calibrated value of a sensor measurement. engineeringunit constants use this format:

real-number units

The unit of measurement is a one, two or three letter abbreviation for the measurement.The EU_UNIT_CATEGORIES in Appendix A of the OASIS-CC Database Guide lists allunit abbreviations recognized by CSTOL. See the following examples of engineering unitconstants:

27.948 V — Value in volts

7.13E-1 MA — Value in milliamperes

90.00DEG — Value in degrees of arc

As shown in the last example, the space between the number and the units is optional.

Clock Times

Clock time constants specify a date and time of day. Clock time constants use this format:

[year] / [day-of-year] - [hour] : [minute] : second

Year is specified as a two- or four-digit number. If two, a value of 1900 is added tocalculate a twentieth century date. If omitted, Year defaults to the current year.

Day-of-year occurs in the range 1 - 365 (366 for a leap year). If omitted, Day-of-yeardefaults to the current day number.

Hour and minute represent the hour of day and minute of hour. Hour occurs in the range 0- 23, while minute occurs in the range 0 - 59. If unspecified, both values default to zero.Second, specified as an integer or a real number, is required. See the following examples:

1987/360-12:30:45.5

1989/073-1:0:0

/-18:00:00 — 1800 hours today


2-8


The system clock of the computer running OASIS-CC determines the time zone for clocktimes. Spacecraft operations clocks are typically set to Coordinated Universal Time (UTC)or Greenwich Mean Time (GMT).

Delta Times

Delta time constants specify a time interval. They use this format:

[hours] : [minutes] : seconds

The components of this format have the same definitions and rules as for clock times. Forexample:

01:30:00.0 — Specifies an interval of 90 minutes

::22.2 — Specifies an interval of 22.2 seconds

Strings

Strings are constants that represent arbitrary text. Text strings are enclosed in doublequotes:

"text-string"

Text strings include blanks, tabs and any printing ASCII character except the doublequotation mark reserved for the string delimiter. The text string length is limited by themaximum length of a CSTOL statement, 800 characters. Lowercase letters in text stringsare not converted to uppercase, unless the string is contained in a query directive, such asUPDATE or INSERT. In performing comparisons of text strings, "abc" does not equal"ABC".

VariablesVariables contain data values. CSTOL variables are global, local and special.

Global Variables

Global variables store the individual measurements to be processed that are stripped fromthe data stream when data are received by the OASIS-CC system. The Latest_Data tablecontains one global variable for each measurement. Global variables also store status datacreated by the OASIS-CC package. These variables are updated automatically when newdata become available, usually when a new frame or packet of telemetry data is processed.By examining global variables, CSTOL may determine the current state of OASIS-CC andthe systems it monitors, and to analyze a system's state. For example, a CSTOL procedure


2-9


may send a particular command only when a specific state occurs in the spacecraft.CSTOL examines global variables containing status data from the spacecraft to determine ifthe spacecraft is in the desired state. Each global variable has a two-part name, each part anidentifier:

element item

Within this format, item names the particular measurement the variable holds, whileelement names the component the measurement pertains to — for example, OASIS-CC, aninstrument, or a spacecraft. See these examples:

CAMERA APERTURE

LIGHT_SENSOR READING

PLATFORM TEMPERATURE

Global variables often contain multiple values. If the value comes from a sensor as a datanumber (DN) value, the global variable stores the value. OASIS-CC typically converts adata number to an engineering unit number or a state value, making the value moremeaningful to users. The raw DN value and the engineering unit (EU) or staterepresentation, if any, are available for manipulation. If the global variable name isspecified, its engineering unit or state value is used. To manipulate the DN value, precedethe variable name with the RAW. For example:

WRITE PLATFORM TEMPERATURE

prints a value in engineering units, like degrees Centigrade, while

WRITE RAW PLATFORM TEMPERATURE

prints the DN value. Global values may be automatically smoothed by OASIS-CC as thedata arrive using a running average technique. If averaging is enabled, the smoothed valueis included with DN and EU values. The smoothed value is manipulated by preceding thevariable name with SMOOTHED or AVERAGED. For example:

WRITE AVERAGED PLATFORM TEMPERATURE

WRITE SMOOTHED PLATFORM TEMPERATURE

Either word prints the current running average value of the platform temperature.


2-10


Global variables are created with the database generation process. See the OASIS-CCSystem Manager's Guide.

Local Variables

Local Variables are created using the DECLARE statement. These variables hold calculatedvalues within procedures. Local variables are named with an identifier preceded by a dollarsign. For example:

$MODE

$MAXIMUM_TEMP

OASIS-CC interprets names lacking the $ as state constants.

Within the DECLARE statement, each local variable is assigned a specific data type,restricting its storage to values of that type. Local variables hold all types but literal.

Special Variables

OASIS-CC predefines special variables. Some special variables are read-only, allowingCSTOL to read, but not change, their values. Other special variables act like local variables— their value can be read and changed through CSTOL. Special variable names consist ofan identifier preceded by two dollar signs. The OASIS-CC special variables are presentedbelow. The visibility of the special variables differs. Some of the variables are visible toall users and procedures on all control language processors (CLPs). Some of the variablesare visible at the CLP level (meaning each CLP has it's own copy), while other variablesare visible at the procedure level (each procedure has its own copy).

Global Special Variables

These variables are visible system-wide.

$$GBL_COMMAND_MODE

The value of this variable determines if commands entered in CSTOL are transmitted byOASIS-CC. This variable is visible to all OASIS-CC CLPs. It has one of these statevalues:

• ISSUE — Enables the transmission of commands to be defined by each sub-CLP'svalue of $$COMMAND_MODE;

• NOISSUE — Disables transmission of all OASIS-CC commands.


2-11


The default value for $$GBL_COMMAND_MODE is ISSUE. This variable has acorresponding Latest_Data element, $$GLOBAL $$COMMAND_MODE that reflects itsvalue. This correspondence allows the setting to be displayed.

$$COMMAND_ECHO

The value of this variable determines if hexadecimal representations of command contentsare logged in the message queue. This variable is visible to all OASIS-CC CLPs. It hasone of these state values:

• OFF — Inhibits the logging of all command headers, contents and trailers in themessage queue;

• CMD — Enables the logging of command contents (without message headers ortrailers) in the message queue;

• MSG — Enables the logging of command headers and trailers (without commandcontents) in the message queue;

• BOTH — Enables the logging of all command data (including headers and trailers)in the message queue.

The default value for $$COMMAND_ECHO is OFF. This variable has a correspondingLatest_Data element, $$GLOBAL $$COMMAND_ECHO that reflects its value. Thiscorrespondence allows the setting to be displayed.

$$CURRENT_TIME

This read-only clock time variable, expressed in clock time format, contains the currenttime defined by the computer system clock.

$$LIMITS_WAIT

This system-wide variable determines whether CSTOL procedures executing on the user orsub-CLPs are halted at the time a red limit or state alarm condition is entered.

• ON — Procedures on the user CLP and sub-CLPs are halted when a red limitscondition is entered from either a green or yellow condition, or if a state enters aBAD desirability from a GOOD desirability (procedures executing on the equation,trigger and command CLPs are unaffected by this flag). A GO statement isrequired to resume execution on each CLP that was halted.


2-12


OASIS-CC is unable to affect a limits wait for any CLP that has an ASK windowactive at the time the red limit or state alarm was issued. The result is thatprocedures will resume execution when the ASK is answered.

• OFF — Procedures are unaffected when red limit or state alarm conditions areentered.

The default value for $$LIMITS_WAIT is OFF. This variable has a correspondingLatest_Data element, $$GLOBAL $$LIMITS_WAIT that reflects the value. Thiscorrespondence allows the setting to be displayed.

$$LIMITS_MODE

This system-wide variable controls which database-defined limits checks will beperformed.

• BOTH — HILO and DELTA checks are performed as defined in Latest_Data andLimits.

• HILO — HILO checks are performed as defined in Latest_Data and Limits.

• DELTA — DELTA checks are performed as defined in Latest_Data and Limits.

• OFF — No limits checks defined in Latest_Data and Limits are performed.

The default value for $$LIMITS_MODE is BOTH. This variable has a correspondingLatest_Data element, $$GLOBAL $$LIMITS_MODE that reflects the value. Thiscorrespondence allows the setting to be displayed.

$$STATES_MODE

This system-wide variable controls which database-defined states checks will beperformed.

• BOTH — DESIRABILITY and CHANGE checks are performed as defined inLatest_Data and State_Conversions.

• DESIRABILITY — DESIRABILITY checks are performed as defined inLatest_Data and State_Conversions.

• CHANGE — CHANGE checks are performed as defined in Latest_Data andState_Conversions.


2-13


• OFF — No states checks defined in Latest_Data and State_Conversions areperformed.

The default value for $$STATES_MODE is BOTH. This variable has a correspondingLatest_Data element, $$GLOBAL $$STATES_MODE that reflects the value. Thiscorrespondence allows the setting to be displayed.

$$CEV_MODE

This system-wide variable acts as a switch that controls Command Execution Verification(CEV) for commands with this function is enabled in the database (see Chapter 5 of theOASIS-CC System Manager's Guide). It has one of these state values:

• ON — Engages CEV for commands with CEV enabled in the database.Commands not enabled for CEV in the database aren't affected by this variable;

• OFF — Disengages CEV for commands with CEV enabled in the database. Whilesetting this variable to OFF inhibits CEV, it does not alter the database. Setting thevariable to ON will reinstate CEV for commands with CEV enabled.

The default value for $$CEV_MODE is ON. This variable has a correspondingLatest_Data element, $$GLOBAL $$CEV_MODE that reflects its value. Thiscorrespondence allows the setting to be displayed.

$$UED_MODE

This system-wide variable acts as a switch that controls Unexpected Event Detection (UED)for telemetry items with this function enabled (see Chapter 4 of the OASIS-CC SystemManager's Guide). It has one of these state values:

• ON — Engages UED for enabled telemetry items in the database;

• OFF — Disengages UED for all telemetry items without altering their databasesettings.

The default value for $$UED_MODE is ON. This variable has a correspondingLatest_Data element, $$GLOBAL $$UED_MODE that reflects its value. Thiscorrespondence allows the setting to be displayed.


2-14


$$PRECHECK_MODE

This system-wide variable acts as a switch that controls the activation of PRECHECKprocedures for commands with PRECHECKs defined. (see Chapter 5 of the OASIS-CCSystem Manager's Guide). It has one of these state values:

• ON — Engages PRECHECK execution for commands with PRECHECKs defined;

• OFF — Disengages PRECHECK execution for commands with PRECHECKswithout altering the database.

The default value for $$PRECHECK_MODE is ON. This variable has a correspondingLatest_Data element, $$GLOBAL $$PRECHECK_MODE that reflects its value. Thiscorrespondence allows the setting to be displayed.

$$POSTCHECK_MODE

This system-wide variable acts as a switch that controls the activation of POSTCHECKprocedures for commands with POSTCHECKs defined. (see Chapter 5 of the OASIS-CCSystem Manager's Guide). It has one of these state values:

• ON — Engages POSTCHECK execution for commands with POSTCHECKsdefined;

• OFF — Disengages POSTCHECK execution for commands with POSTCHECKswithout altering the database.

The default value for $$POSTCHECK_MODE is ON. This variable has a correspondingLatest_Data element, $$GLOBAL $$POSTCHECK_MODE that reflects its value. Thiscorrespondence allows the setting to be displayed.

CLP Special Variables

These variables are local to each CLP. Each CLP has its own copy.

$$ERROR

This variable holds the exit status of a combined conditional/timed wait. It has one of thesestate values:

• NO_ERROR — Indicates the relational expression tested TRUE;


2-15


• TIME_OUT — Indicates the relational expression did not test TRUE within thespecified delta or clock time..

$$COMPILER_OUTPUT

This state variable determines the route of listings generated during procedure compilation.Choices are:

• WINDOW —Compiler output is directed to the display screen;

• FILE — Compiler output is written to a disk file;

• BOTH — Both window and file output are desired;

• NEITHER — Neither window nor file output is desired.

The default value for $$COMPILER_OUTPUT is NEITHER.

$$CHECK_INTERVAL

This variable determines the rate at which conditional WAIT statements are evaluated. It isexpressed as a delta time such as:

• 00:00:01— Conditional WAIT will be evaluated about once per second;

• ::00.5— Conditional WAIT will be evaluated about two times per second.

The default value for $$CHECK_INTERVAL is 00:00:01

$$COMMAND_MODE

The value of this variable determines if commands entered in CSTOL are transmitted byOASIS-CC. The user CLP has its own copy of this variable, as does each user sub-CLP.Modifying the value of the variable on one CLP does not affect the values for the otherCLPs. It has one of these state values:

• ISSUE — Enables the transmission of commands;

• NOISSUE — Disables transmission of commands.

The default value for $$COMMAND_MODE is ISSUE


2-16


$$CLP_LOG_INPUT

This variable is identical to $$LOG_INPUT (see Procedure Special Variables below),however each CLP has its own copy. When a procedure is started, it inherits and operateswith the value of $$CLP_LOG_INPUT until it encounters a setting for $$LOG_INPUT, ifone exists, within the procedure. Changing the value of $$CLP_LOG_INPUT will notaffect execution of active procedures, since the variable is only used at the time a procedureis started. Table 2.1 presents the default value for this variable.

$$CLP_STP_INTERVAL

This variable is identical to $$STEP_INTERVAL (see Procedure Special Variables below),however each CLP has its own copy. When a procedure is started, it inherits and operateswith the value of $$CLP_STP_INTERVAL until it encounters a setting for$$STEP_INTERVAL, if one exists, within the procedure. Changing the value of$$CLP_STP_INTERVAL will not affect execution of active procedures, since the variableis only used at the time a procedure is started. Table 2.1 presents the default value for thisvariable.

$$CLP_STEP_MODE

This variable is identical to $$STEP_MODE (see Procedure Special Variables below),however each CLP has its own copy. When a procedure is started, it inherits and operateswith the value of $$CLP_STEP_MODE until it encounters a setting for $$STEP_MODE, ifone exists, within the procedure. Changing the value of $$CLP_STEP_MODE will notaffect execution of active procedures, since the variable is only used at the time a procedureis started. Table 2.1 presents the default value for this variable.

Table 2.1 $$CLP_STEP_MODE, $$CLP_STP_INTERVAL and$$CLP_LOG_INPUT defaults

CLP $$CLP_LOG_INPUT $$CLP_STP_INTERVAL $$CLP_STEP_MODE

User YES ::0.0 GO

Equation NO ::0.0 GO

Command NO ::0.0 GO

Trigger YES ::0.0 GO

Sub YES ::0.0 GO


2-17


Procedure Special Variables

These variables exist only within the domain of the active procedure, and must be setwithin the body of the procedure.

$$LOG_INPUT

This state variable determines if procedure output is logged to the message log. Legalvalues are YES to log the statement or NO to not log it. The default value is YES.

$$STEP_INTERVAL

This variable specifies the delay between execution of CSTOL statements within aprocedure. The variable has delta time values:

• 00:00:02 — Procedure statements are executed every two seconds (when$$STEP_MODE is PAUSE).

The default value is 00:00:01.

$$STEP_MODE

This state variable determines the events following statement execution. It has one of thesevalues:

• GO — Procedure statements are executed as quickly as the CLP can process them;

• PAUSE — Procedure statements are executed once the $$STEP_INTERVAL timeinterval elapses;

• WAIT — Procedure statements wait until the user enters a GO directive to execute .This process equals a single step mode.

The default for $$STEP_MODE is GO.

Other Special Variables

$$LOOP_COUNT

This read-only integer variable counts the number of times the current loop is executed.The first time through a loop the count equals one. The variable is defined within a looponly.


2-18



OASIS-CC CSTOL Reference Manual 3. Building CSTOL StatementsRev 1 – 11/94

3-1


3 . Building CSTOL Statements

CSTOL statements are sentences in CSTOL recognized and acted upon by the CLP. MostCSTOL statements have the following format, whether a user enters CSTOL input from aterminal, invokes a macro, starts a procedure, or inserts CSTOL statements into theOASIS-CC database:

[label:] directive qualifiers.

For example:

TURN OFF HEATER_1

DIAGNOSTICS: START LEAK_TEST

LET TANK PRESSURE = 28.5 PSI

LabelsLabels, identifiers that mark statements within procedures, usually transfer control to themarked statement. Labels end with a colon with no intervening blanks. For example:

A:

XYZ_1A:

POWER_UP:

Check_Status:

While these examples are legal, meaningful labels like POWER_UP are more meaningfulthan nondescript labels like XYZ. These are illegal labels:

3. Building CSTOL Statements OASIS-CC CSTOL Reference ManualRev 1 – 11/94

3-2


1A: — A letter always begins a label.

A1$: — Only alphanumeric characters and underscores are allowed.

Check_Transponder: — Labels must be 16 characters or less.

DirectivesDirectives are identifiers naming the CSTOL action to occur. Most directives are singlecommon English words, but may be compound, consisting of two words. For example,LET and IF are one-word directives, END IF and TURN OFF, compound directives.

QualifiersQualifiers are arguments, argument lists, range specifications and clauses that qualify thedirective action. Some directives — like ELSE, GO and RETURN — require noqualifying arguments or clauses while other directives require at least one. Certainmandatory qualifiers must be specified while others are optional, included only for valuesdiffering from the default.

Arguments

Arguments are single constant values or variable names that hold such values. Valuesqualify the directive action. For example:

DISPLAY POWER_STATUS

LOOP 3

The literal constant argument, POWER_STATUS, names the display page to show in thefirst example. In the second, the integer constant argument, value 3, specifies the numberof loop executions. Given statements allow certain value types for particular arguments.

Clauses

If CSTOL statements consisted only of directives and arguments, many statements wouldbe difficult to remember or read. For example, this directive is difficult to comprehend:

DISPLAY POWER_STATUS 7 0:0:10

To simplify such statements, most arguments are encased within clauses. This exampledemonstrates the same statement with clauses:

OASIS-CC CSTOL Reference Manual 3. Building CSTOL StatementsRev 1 – 11/94

3-3


DISPLAY POWER_STATUS ON 7 EVERY 0:0:10

Here the ON clause identifies the terminal to display the window while EVERY specifiesthe update interval.

The following list presents CSTOL clauses and the type of argument they contain:

• AT — A location;

• BEGINNING — Starting clock time;

• BY — Quantity of increase or decrease;

• EVERY — Repeat time interval;

• FROM — A source;

• ON — A location;

• TO — A destination;

• UNTIL — Stopping clock time;

• WITH — One or more parameter name/value pairs;

• WHERE — Condition specifying a contingent action.

Argument ListsDirectives may demand or allow multiple values for a particular argument. CSTOL allowsargument lists — groups of arguments with individual values separated by commas. Forexample, the COMPILE directive may accepts an argument list of procedure names tocompile, if compiling multiple procedures:

COMPILE PROC_A, PROC_B, PROC_C

Range SpecificationsRange specifications, pairs of numbers separated by a colon, specify the lowest and highestvalues allowed on a declared numeric value. Appearing in the DECLARE statement, rangespecifications are legal for integers, data numbers, reals and engineering unit numbers, butillegal for delta or clock times. For example:

3. Building CSTOL Statements OASIS-CC CSTOL Reference ManualRev 1 – 11/94

3-4


-10 : +10 — Range of integer values

24.5 : 30.6 — Range of real values

0.DEG : 90.DEG — Range of engineering units values

Input Lines

CSTOL statements are entered into OASIS-CC as text lines, each line containing 80characters or less. While most statements fit onto a single line, some are longer than 80characters. To compensate, CSTOL provides continuation lines. To continue to the nextline, use the ampersand (&) as the last character in the line. The ampersand is unneeded ifentering a text string spanning more than one line. The text string automatically continuesto new lines until the closing double-quote text string delimiter is encountered.

When continuing a statement to another line, a special prompt , -> , tells the user that theCLP expects a continuation line. Statement labels begin lines and statements but cannotappear on continuation lines. CSTOL statements are limited to 800 characters.

Comments

Comments may be appended to end a line. Comments are text appearing after theexecutable part of a CSTOL statement on an input line. Any input line may be commentedand may consist of a comment only. Comments begin with a semicolon. The semicolonseparates the comment, which extends to the end of its line, from executable CSTOL code.The CLP ignores comments, and they do not affect processing. Comments often provideadditional information about macros or procedures, making it advisable to use commentsliberally there. This example shows the use of comments when annotating a procedure:

;; Commands to power the instrument;TURN ON INSTRUMENT

IF $NIGHT_TIME = YESTURN ON HEATER ; Heater must be on when S/C is in darkEND IF

OASIS-CC CSTOL Reference Manual 4. Summary of CSTOL StatementsRev 1 – 11/94

4-1


4 . Summary of CSTOL Statements

This chapter summarizes all CSTOL statements. Each statement description includes thedirective, the part of the statement specifying the action. Statements are arranged by thesefunction areas:

• Expressions *

• Control Structures *

• Procedures *

• Macros *

• Commands *

• Communications

• User Input/Output

• Database Management

• Program Control

Functional areas marked with asterisks are explored further in subsequent chapters.Chapter 10 describes each CSTOL statement individually.

ExpressionsThe following statements define variables and evaluate expressions.

• DECLARE defines procedure parameters, local variables and constants.

• LET evaluates an arithmetic or logical expression.

4. Summary of CSTOL Statements OASIS-CC CSTOL Reference ManualRev 1 – 11/94

4-2


Control StructuresThe following statements compose CSTOL's two major control structures: IF-blocks andloops.

• ELSE marks the block of statements executed if the IF and all ELSE IF clauses donot execute.

• ELSE IF marks the beginning of the set of statements executed if the ELSE IFrelational expression is TRUE, assuming no previous IF or ELSE IF clause withinthe IF-block is TRUE.

• END IF marks the end of an IF-block.

• END LOOP marks the end of a loop.

• ESCAPE breaks a loop, transferring control to the first statement after END LOOP.

• IF marks the beginning of a set of statements executed if the IF relationalexpression is TRUE.

• LOOP marks the beginning of a loop, specifying the number of times it executes.

ProceduresThe following statements define and control CSTOL procedures.

• BEGIN marks where declarations end and normal statement execution beginswithin a procedure.

• COMPILE compiles one or more procedures.

• DECOMPILE releases the memory space of the compiled code of one or moreprocedures.

• END PROC marks the end of a procedure.

• GO resumes procedure execution.

• GO TO redirects procedure execution.

• PROC marks the procedure start and names its expected parameters.

• RETURN terminates procedure execution.


4-3


• START initiates procedure execution, supplying the arguments passed to it.

• WAIT suspends procedure execution.

• WAIT AT sets an automatic breakpoint within a procedure.

MacrosThe following statements define CSTOL macros.

• DEFINE preprocesses a macro, making it available for use.

• END MACRO marks the macro end.

• MACRO marks the macro beginning.

• UNDEFINE releases the memory space of one or more macros.

CommandsThe following statements are used to command external elements. Besides the followingdirectives, CSTOL provides a large set of predefined directives used to express commands.See Chapter 9 for a list of command directives.

• FLUSH clears the Command Execution Verification (CEV) buffers.

• CANCEL deletes command messages before transmission.

• LOAD transfers disk file contents to an external element.

• MESSAGE marks the command message start.

• RETRY retransmits a command message.

• SEND transmits a command message or a raw binary or ASCII command.


4-4


CommunicationsThe following statements control data reception from and transmission to external elements.

• INITIALIZE initializes an IEEE-488 bus controller.

• MAKE sets a bus device to a specific communications state.

• POLL initiates acquisition of IEEE devices' status bytes.

• RECORD initiates and terminates logging of incoming and outgoing data to diskfiles.

• RETRIEVE retrieves data recorded in a disk file and replays it through OASIS-CClike a data line.

• ROUTE sends part of a return stream to a forward stream or a sub-CLP.

• SAMPLE initiates sampling of devices on an IEEE-488 bus.

• STOP POLLING terminates automated polling on an IEEE-488 bus.

• STOP SAMPLING terminates sampling of devices on an IEEE-488 bus.

• SWITCH activates or deactivates a data stream.

User Input/OutputThe following statements control the display of data and messages and allow CSTOL tosend output to and receive input from users.

• ASK asks the user questions and receives the answers.

• CHECK writes data values and text, and optionally compares them to user-suppliedranges.

• SHOW displays a variety of statuses for the CSTOL Control Language Processors(CLPs) and Command Execution Verification (CEV) processor.

• SHOW displays the CSTOL Control Language Processor status, includingprocedure and macro names known to the CLP.

• SNAP saves the contents of display or message windows in a disk file.


4-5


• WRITE writes data values and text to the OASIS-CC message log.

Database ManagementThe following statements allow storage, retrieval and updating of information in theOASIS-CC database.

• COMMIT and CHECKPOINT save memory-resident contents of database tables todisk files.

• DELETE removes records from a database table.

• INSERT creates a new database table record and specifies the values for data fieldsin that record.

• LOCK reserves a database table for exclusive access by the issuing user.

• REPORT produces a list of database table records meeting user-specified criteria.

• RESTORE copies a database table from disk to memory for access by OASIS-CCsoftware.

• UNLOCK releases a lock on a database table, allowing access by all users.

• UPDATE modifies fields within selected database table records.

Program ControlThe following statements control access to OASIS-CC and run application and systemprograms.

• CSTOL OFF logs out users from OASIS-CC software.

• RUN initiates routines outside of OASIS-CC.


4-6



OASIS-CC CSTOL Reference Manual 5. ExpressionsRev 0 – 11/94

5-1


5 . Expressions

Expressions are mathematical equations consisting of variables, constants, functions, andoperators combined following the rules of expression construction outlined in this chapter.Expressions appear in several CSTOL contexts, described below.

Constants and variables are operands — the data acted upon — within expressions.Operators are special symbols specifying an arithmetic, relational or logical operationapplied to one or two operands. Once an operation is performed, the operator returns asingle value.

Functions extend operators. Identified by name rather than special symbol, they too act onone or more operands and return a single value. Each operand has an associated data type(see Chapter 2). This data type is key since most operators and functions only act on a fewdata types. Also, the value type returned by operators or functions depends upon the datatypes acted upon. Appendix B presents the valid data types for each operator.

Rules for expression formation are simple. CSTOL expressions resemble expressions inprogramming languages like BASIC and FORTRAN. Expressions may take these forms:

• operand — Expressions may be simple constants or variables. This expressionvalue equals the operand value. For example:

3.14159 — A real constant.

PLATFORM POSITION — A global variable.

$X — A local variable.

• function (operand) — Functions applied to operands form expressions. Thisexpression value equals the returned function value. For example:

5. Expressions OASIS-CC CSTOL Reference ManualRev 0 – 11/94

5-2


LOG(3.14159) — Natural logarithm of π.

SIN(PLATFORM POSITION) — Sine of a global variable.

SQRT($X) — Square root of a local variable.

• expression operator expression — more elaborate expressions may be formedusing operators. For example:

3.14159 + $X — An arithmetic expression.

0.95*$X**2 - 12.37*$X + 201.06 — Another arithmetic expression.

PLATFORM POSITION < 152.3 DEG — A relational expression.

• (expression) — Expressions may be enclosed within parentheses to isolate part ofa complicated expression (see Order of Evaluation, below). The value of theexpression is unchanged. For example:

($X + 3.14159)

2*(PLATFORM POSITION - 123.7 DEG)

The expression output is always a single value.

OperatorsOperators hold expressions together, specifying the arithmetic, relational or logicaloperation performed on operands and subexpressions. Except for the arithmetic negation (-) and logical negation (not) operators, all CSTOL operators are binary, requiring twooperands. Operators return a single value of the data type determined by the operands.

Arithmetic Operators

Arithmetic operators take numeric — integer, real, data number, engineering unit, clocktime or delta time — values as operands and perform an arithmetic operation to yield anumeric result. The CSTOL arithmetic operators are:


5-3


• + for addition;

• - for subtraction or negation;

• * for multiplication;

• / for division;

• ** for exponentiation;

• mod for modulo.

The negation operator acts on a single operand to return the negative value of the operand.For example, if local variable $X contains the value 3.14, then -$X returns the value -3.14.

The exponentiation operator raises the first operand to the power specified by the secondoperand. For example, 3**2 produces the value 9. CSTOL recognizes only integralexponents; for example, 3**2.5 is not allowed.

The modulo operator returns the remainder after integer division of the first operand by thesecond. For example, 10 mod 3 returns 1, the remainder after dividing 10 by 3.

Arithmetic expressions use only arithmetic operators and numeric operands. For example:

PLATFORM POSITION mod 5

($TEST - 123.0 DEG)*2

00:01:20 + 00:00:25 — Results in a value of 00:01:45

String Operators

CSTOL provides a single operator, concatenation, for manipulating character strings. Theplus sign (+) represents concatenation, a binary operator that joins the characters of twooperand strings. For example:

"data" + "base" — Results in the string "database"

"To be"+ " or " +"not to be" — Results in "To be or not to be"

Relational Operators

Relational operators compare two numeric operands or two string operands and yield aboolean result. If the comparison holds, the logical value TRUE is returned, if not,FALSE is returned. The CSTOL's relational operators are:


5-4


• = for equal;

• /= for not equal;

• > for greater than;

• >= for greater than or equal;

• < for less than;

• <= for less than or equal.

Relational expressions contain relational operators. For example:

$X > 5

INSTRUMENT POWER /= ON

3 = 1 + 2

"first" /="second"

Text strings equal if they match character for character, including blanks. Lowercase lettersdo not equal uppercase letters; for example, "AB" is not equal to "ab".

Logical Operators

Logical operators have two distinct purposes in CSTOL. They may connect relationalexpressions into a larger relational expressions or specify bit-wise operations on integeroperands to yield an integer result. The logical operators are:

• and for the logical and

• or for the logical or

• xor for the logical exclusive or

• not for the logical not

The not operator is a unary operator that reverses the logical state of its operand. Forexample, TRUE operands are reversed to FALSE . Other logical operators are binary,acting as connectors of relational expressions to produce values in the following ways:


5-5


• The and operator result is TRUE if both relational expressions are TRUE;

• The or operator result is TRUE if one or both relational expressions are TRUE;

• The xor operator result is TRUE if only one relational expression is TRUE.

For bit-wise manipulation of integer numbers, the not operator reverses the sense of eachbit of its operand. For example, 1 bits become 0. The binary logical operators also actupon each bit of their integer operands independently; the least-significant bits arecompared, then the next-least significant bits, up to the most-significant bits. These bitcomparisons results are generated as follows:

• For and operations, the resultant bit is 1 if both corresponding bits in the operandsare 1;

• For or operations, the resultant bit is 1 if either corresponding bit in the operands is1;

• For xor operations, the resultant bit is a 1 if one (but not both) of the operand bitsare 1.

Order of EvaluationExpressions in CSTOL are normally evaluated from left to right. However, every operatorhas an assigned precedence that may override this evaluation. The user may explicitlyoverride the evaluation by encasing subexpressions in parentheses. The rules forexpression evaluation are summarized from the strongest to the weakest rule as follows:

• Subexpressions within parentheses are evaluated first. If nested, evaluation beginsinside the innermost parentheses and moves outward;

• Operators with higher precedence are evaluated before those with lower precedence;

• Operators of equal precedence are evaluated from left to right.


5-6


The following list presents the CSTOL operator precedence from highest to lowest:

• Unary minus and logical not

• Exponentiation

• Multiplication and division

• Addition and subtraction

• String concatenation

• Relational operators

• Logical and, or and exclusive-or

For operators of equal precedence, the expression 3 - 5 - 2 results in -4 (and not 0) sincethe subexpression 3 - 5 is evaluated first, yielding -2, then -2 is subtracted, yielding -4.Parentheses may alter the order of evaluation as follows: 3 - (5 - 2) results in 0 sinceparentheses force the subexpression 5-2 to be evaluated first.

For operators of unequal precedence, the expression 1 + 3 * 4 produces a value of 13because multiplication has a higher precedence than addition. The subexpression 3*4 isevaluated, then 1 is added to yield 13. Again parentheses may alter the evaluation: (1 + 3)* 4 produces the value 16.

The order of evaluation for exponentiation differs from other operators when multipleexponentiation operations are performed in series. The expression 2**3**2 evaluates as2**(3**2) (equaling 512) rather than (2**3)**2 (equaling 64).

Data Types in ExpressionsOperators act on specific types of operands. For example, two integer or delta-time valuesmay be added, but an integer may not be added to a delta-time value because they haveincompatible data types. At times the data types of two operands resemble enough that onemay be converted into a compatible data type, a process called coercion. When an operatoris applied to one or two operands one of the following happens:


5-7


• If the operands are compatible with the operator, the operation is performed;

• If operands are nearly compatible, one is coerced into compatibility with the otherand the operation performed;

• If the operands are incompatible, the operation is aborted and an error messageissued.

Coercion is typically encountered when one operand is an integer and the other a real value.Here the integer value is coerced into a real value.

Appendix B presents compatible data types and defines those coercable for each CSTOLoperator.

FunctionsCSTOL provides several predefined functions: trigonometric, inverse trigonometric,hyperbolic, and miscellaneous functions.

Trigonometric Functions

Trigonometric functions take a single argument, an angle represented by an engineeringunit number in degrees or radians. Its result is a real number.

• SIN represents the sine of an angle. Result range equals -1.0 to + 1.0.

• COS represents the cosine of an angle. Result range equals -1.0 to + 1.0.

• TAN represents the tangent of an angle.

For example:

SIN(45. DEG) — Results in the value .7071

COS(PLATFORM POSITION)

Inverse Trigonometric Functions

Inverse trigonometric functions take a single real argument interpreted as the sine, cosine ortangent of an angle and return an engineering unit value with the angle in radians.


5-8


• ASIN represents Arcsine. Its result ranges from -1.57080 radians to +1.57080radians.

• ACOS represents Arcosine. Its result ranges from 0.0 radians to 3.14159 radians.

• ATAN represents Arctangent. Its result ranges from -1.57080 radians to +1.57080radians.

For example:

ASIN(1.0) — results in the value 1.57080 RAD

ACOS(1.0) — results in the value 0.0 RAD

Hyperbolic Functions

These functions resemble trigonometric functions, but compute the hyperbolic sine, cosineand tangent. The argument must be an engineering unit number in radians. The result is areal number.

• SINH represents the hyperbolic sine of an angle.

• COSH represents the hyperbolic cosine of an angle.

• TANH represents the hyperbolic tangent of an angle.

See the following example:

SINH(1.57080 RAD) —Results in the value .7071

Miscellaneous Functions

The following functions take integer or real number arguments and return a real number.Logarithm and square-root routines require an argument greater than zero.

• EXP computes the natural exponential of its value (e raised to the power of theargument).

• LOG represents the natural logarithm (to the base e).

• LOG2 represents the logarithm to the base 2.

• LOG10 represents the logarithm to the base 10.

• SQRT represents the square root.


5-9


For example:

EXP(1.) — Results in the value 2.71828

SQRT(4) — Results in the value 2.0000

Using ExpressionsCSTOL expressions appear in six different contexts:

• On the right side of the assignment operator in the CSTOL LET statement;

• In IF and ELSE IF statements within an IF-block;

• As the time specifier in a timed WAIT statement;

• As the condition specifier in a conditional WAIT statement;

• As a response to an input statement in an ASK statement;

• As the output value in a WRITE statement;

Assignment

Expression results are assigned to variables through the LET statement. The LETstatement has this format: LET variable = expression.

Here variable is a local, special or global variable that stores the expression value. Forexample:

LET $X = $Y

LET EXTENDER POSITION = EXTENDER POSITION + 14.5 DEG

LET $X = 1.0 + SIN(123.4 DEG)*($Y-3.0)

If the expression and variable data types do not match, CSTOL attempts to coerce theexpression value to the variable's data type. Appendix B presents coercion rules.


5-10


IF-blocks

CSTOL IF-blocks control the conditional execution of sections of code. IF-blocks use thisformat:

IF expressionStatement(s)

ELSE IF expressionStatement(s)

ELSEStatement(s)

END IF

IF the logical or relational expression in the IF statement evaluates TRUE, the statementsimmediately following it are executed . If FALSE, all ELSE IF statement expressions areevaluated in order of appearance. The first to evaluate TRUE is executed while other ELSEIF or ELSE statements are ignored. If none evaluate TRUE, the statements after the ELSEstatement are executed.

Indefinite Wait

The indefinite wait statement suspends the current procedure until either a GO is issued, ora subsequent non-indefinite wait statement completes. It uses this format:

WAIT

If a procedure is halted by a wait, and, for example, a subsequent timed wait is issued fromthe keyboard, the procedure will automatically resume execution when the timed waitcompletes. The same hold true if a conditional wait were issued from the keyboard and thecondition tests TRUE .

Timed Wait

The timed wait statement temporarily suspends the current procedure. It uses this format:

WAIT time-expression

Here time-expression evaluates to a clock or delta time value. A clock time suspends theprocedure until a specified time, while a delta time suspends the procedure for a specifiedlength of time. Sample timed waits are shown below. In the second example, the localvariable is assumed to be declared as a clock time, however the directive would also workif it was a delta time:


5-11


WAIT 00:00:30 suspends a procedure for 30 seconds

WAIT $AOS suspends a procedure until the time specified in $AOS

Conditional/Timed Wait

Conditional/Timed waits suspend a procedure until a specified condition has occurred, or,optionally, until a clock time or delta time has passed. The wait uses this format:

WAIT relational-expression [OR FOR delta time | OR UNTIL clock time]

The procedure remains suspended until the relational-expression is TRUE, or if supplied,the delta or clock time has passed. The special variable $$ERROR returns NO_ERRORwhen the condition is met, or TIME_OUT if a supplied delta or clock time has passed. Therelational-expression is evaluated at the frequency stored in the special variable$$CHECK_INTERVAL. For example:

WAIT INSTRUMENT POWER = ON

WAIT INSTRUMENT POWER = OFF OR FOR 00:01:00

WAIT PLATFORM POSITION > 123. DEG OR UNTIL 1993/359-00:00:02

Command Execution Verification Wait

Command Execution Verification (CEV) waits suspend procedure execution depending onthe outcome of CEV processing (see Chapter 5 of the OASIS-CC System Manager's Guidefor a description of Command Execution Verification).

The CEV wait uses this format:

WAIT FOR cev_group_name

WAIT FOR ALL

WAIT FOR LAST

ALL, LAST and cev_group_name all qualifiers that dictate which commands must passCEV before allowing the procedure to resume execution.

Positional Wait

Positional waits suspend procedure execution at a specified line or label.


5-12


The positional wait uses this format:

WAIT AT line number | label [always]

Procedures are suspended at the specified line or label. Once procedure execution isresumed, the positional wait will not halt at the line or label again, unless the option alwayswas used.

Input to CSTOL

The ASK statement gets input for a CSTOL procedure from a user. It has this format:

ASK reply-variable ask-string.

The ASK statement causes a window to appear on the display screen with the ask-stringmessage. The user enters any CSTOL expression. The expression is evaluated and theresult placed into the local variable specified by reply-variable. If the data types of theexpression and the reply variable do not match, CSTOL attempts to coerce the expressionvalue to fit that of the variable and reports an error if that attempt fails.

Output to the User

The WRITE statement evaluates a list of expressions and writes their values to the messagelog. The WRITE statement has this format:

WRITE write-list.

Here write-list is a list of one or more expressions to be evaluated. For example:

WRITE "Current platform position is ", PLATFORM POSITION

WRITE 413 mod 360

The first example writes out the string expression, the first argument in the output list (theconstant string value is the string itself), then the global variable value of PLATFORMPOSITION. The second example evaluates the expression, 413 mod 360, and outputs theanswer – 53.

OASIS-CC CSTOL Reference Manual 6. Control SequencesRev 0 – 11/94

6-1


6 . Control Sequences

CSTOL provides two mechanisms, IF-blocks and loops, to conditionally execute a groupof statements. These mechanisms appear only within procedures. See the followingexplanations:

• IF-blocks allow procedures to make decisions and conditionally execute statementsbased on those decisions.

• Loops allow the cyclical execution of a set of statements. This cycle may repeatinfinitely.

IF-BlocksGroups of CSTOL statements may be executed conditionally with IF-blocks. A completeIF-block has this format:

IF relational-expressionStatement(s) controlled by the IF

ELSE IF expressionStatement(s) controlled by the ELSE IF

ELSEStatement(s) controlled by the ELSE

END IF

IF-blocks have four main parts: the IF clause, the ELSE IF clause, the ELSE clause, andthe END IF statement. The IF clause, an IF statement followed by a set of CSTOLstatements, appear firsts. If the relational expression of the IF statement is false,theCSTOL statements are skipped and execution resumes with the next ELSE IF, ELSE orEND IF statement. If true,the statements are executed. When all statements are processed,control passes to the END IF statement.

6. Control Sequences OASIS-CC CSTOL Reference ManualRev 0 – 11/94

6-2


ELSE IF clauses resemble IF clauses. They provide a relational expression and containstatements executed if that expression is true. ELSE IF clauses are optional, however; anIF-block may have zero, one or multiple ELSE IF clauses. Multiple ELSE IF statementsare evaluated in order of appearance.

ELSE IF clauses are processed exactly like IF clauses: if the relational expression is true,its statements are executed. When all statements are processed, control passes to the ENDIF statement. If the expression is false, the statements are skipped and execution continueswith the next ELSE IF, ELSE or END IF statement.

ELSE clauses specify a group of statements executed when the relational expressions onthe IF statement and all preceding ELSE IF statements evaluate false. If so, all statementsfrom ELSE to END IF are executed. The optional ELSE clause appears once only.

The END IF statement signifies the end of an IF-block. An IF-block contains only oneEND IF statement.

An IF-blocks may be nested, appearing within an IF, ELSE IF, or ELSE clause. CSTOLdoes not limit the depth of this nesting, but the OASIS program office discourages nestingmore than two levels deep (an IF-block within an IF-block) due to user difficulty inunderstanding deeply nested constructs.

LoopsA sequence of CSTOL statements may execute repeatedly with the loop control structure,which takes this form:

LOOP [loop-count]

Statements to be executed repeatedly

END LOOP

The loop count is an integer constant or local variable with an integer value that determinesthe number of times the loop is executed. If unspecified, the loop continues indefinitelyuntil it encounters an ESCAPE statement. The loop count value is evaluated when the loopis entered.

Any CSTOL statement within the executable portion of a procedure may appear in a loop.Loops may also be imbedded within other loops. Loops may be nested, but like IF-blocks,the OASIS program office discourages nesting more than two levels deep (a loop within aloop) due to user difficulty in understanding deeply nested constructs.

OASIS-CC CSTOL Reference Manual 6. Control SequencesRev 0 – 11/94

6-3


Loop execution is terminated with the ESCAPE statement. When executed, ESCAPEtransfers control to the first statement following the END LOOP statement.

The special variable, $$LOOP_COUNT, occurs within a loop. This variable counts thenumber of times the loop executes. The count starts at 1 and increases with each ENDLOOP statement. $$LOOP_COUNT counts the executions of the innermost loop withinnested loops. $$LOOP_COUNT is undefined outside of a loop.

6. Control Sequences OASIS-CC CSTOL Reference ManualRev 0 – 11/94

6-4



OASIS-CC CSTOL Reference Manual 7. ProceduresRev 1 – 11/94

7-1


7 . Procedures

Procedures are sequences of CSTOL statements executed by the CLP. Contained in a textfile, procedures allow the development and checking of complex test and operationsequences prior to execution. Procedures also eliminate the inconvenience of reenteringstatements from the keyboard. CSTOL procedures resemble FORTRAN and otherprogramming language subprograms, but differ as follows:

• Users have substantial control over procedure execution. Users may suspend andresume execution and redirect or terminate the flow of processing.

• Procedure lines may be displayed during execution, allowing the user to monitor it.

• The user controls the rate of procedure execution. The user may run a procedure atfull speed, slow it using a time delay between statements, or move through theprocedure one statement at a time.

• Procedures may be executed despite syntax errors detected during compilation. Theprocedure stops at any statement where an error is detected or if an error is detectedat run time (dividing by zero, for example).

• Values of procedure variables may be queried and changed by the user duringprocedure execution. Special variables may control many facets of processing.

7. Procedures OASIS-CC CSTOL Reference ManualRev 1 – 11/94

7-2


The Form of a CSTOL ProcedureCSTOL procedures use this form:

PROC procedure-name [parameter-list]

Declarative section

BEGIN

Statement(s)

END PROC

Here procedure-name, an identifier, specifies the procedure name to CSTOL, whileparameter-list provides the procedure an optional set of formal parameters. Passingparameters allows the procedure to be called with different input data. Each formalparameter in the PROC statement is positionally matched with an argument in the STARTstatement initiating the procedure. For example, the value of the first argument is assignedto the first formal parameter, the second value to the second parameter.

CSTOL allows input parameters only; values are passed to the procedure but not returned.Argument are constants or variables. The argument of a data type must agree with that ofthe formal parameter. Global variables may be passed as arguments but are usuallyaccessed directly. Use the LET statement to assign a new value to a global variable. Theassigned value remains after termination.

Declarative Section

The declarative section declares input parameters, local variables, and symbolic constantswithin the procedure. Only DECLARE statements are allowed here, with one DECLAREstatement for every input parameter listed in the PROC statement. Declarations of formalparameters have this format:

DECLARE INPUT name = value [value-range]

Here name is the formal parameter name in the PROC statement. It has the format of alocal variable, an identifier preceded by a dollar sign (for example, $INST_TEMP). Thevalue determines the type of argument value supplied for the parameter. Integer values, ifgiven, require that an integer constant or variable is supplied when the procedure is called.A value range may be specified. The supplied value is checked for its occurrence withinthis value range when the procedure is called.


7-3


A local variable declaration has this format: DECLARE VARIABLE name = value [value-range].

Here the meanings of name, value, and value-range are the same as input parameters.These values set the initial variable value on procedure execution, although the value maybe changed by the procedure or the user with the LET statement.

A symbolic constant is a constant value referred to by an identifier. For example, themathematical quantity π is referred to by $PI, rather than repeatedly entering 3.14159. Aconstant declaration has this format: DECLARE CONSTANT name = value.

A constant value cannot be changed with LET, so value ranges are unnecessary.

Executable Section

Unless a RETURN statement is encountered, interactive procedure execution begins withthe first statement after BEGIN and continues to END PROC.

All CSTOL statements are allowed with the executable section except a second PROC, aMACRO, or an END MACRO statement. Because procedures end with END PROC, onlyone END PROC statement may occur. END PROC terminates procedure processing andreturns control to the user or calling procedure. Procedure execution may be terminatedbefore END PROC with a RETURN entered from the keyboard.

Preparing a ProcedureProcedures are text files prepared with a text editor. The standard file extension forprocedure files is .PRC. Each line of file text equals the corresponding line of theprocedure. The first executable CSTOL statement is PROC, but blank lines or lines withcomments may precede the PROC statement. The last executable CSTOL statement is ENDPROC. Blank lines are allowed between statements.

Installing a ProcedureThe user must install a new CSTOL procedure before its use. Installation informs CSTOLof the procedure, telling its location and the method to compile and start it.

To install a procedure, transfer the procedure file to the directory indicated byOASIS_PROCS. Next, place an entry in the OASIS-CC Procedures database table to tellOASIS-CC the file name containing the procedure. This entry is typically made throughCSTOL using a statement like this:


7-4


INSERT PROCEDURES Procedure_Name = proc-name, &Filename = file-name

Here proc-name is the procedure name in the PROC statement while file-name names thefile containing the procedure. Other fields in the Procedures table may be optionally filledfor procedure configuration management. See the OASIS-CC Database Manual.

Compiling a ProcedureCompilation transforms CSTOL procedures into object code executed by a CLP.Procedures are compiled with the COMPILE statement: COMPILE proc-name-list.

Here proc-name-list contains a list of procedure names to compile. Once compiled aprocedure stays compiled and available for use for the remainder of the session. However,the object version is kept in memory and discarded at termination.

During compilation, the procedure is checked for syntactic error which are reported to theuser. The special variable, $$COMPILER_OUTPUT determines message routing.Messages may be sent to WINDOW, FILE, BOTH, or NEITHER with the LET statement.For example, LET $$COMPILER_OUTPUT = FILE, writes a file to list errors detectedduring compilation. Compiler output may be sent to a WINDOW, FILE, BOTH, orNEITHER.

If WINDOW is selected, output is directed to the display screen. Messages, includingerror messages, are sent to the message log when compilation begins and ends.

If FILE is selected, a complete listing of the procedure source is written to a disk file withmessages of syntax errors. The file, named like the procedure file plus an .LIS fileextension, is placed into the directory pointed to by OASIS_PROCS. For each source linethe listing contains:

• A line number. All lines — even non-CSTOL code — is assigned a line numberstarting at 1. These line numbers may be used in GO TO statements to specifycontrol redirection and WAIT AT statements to set breakpoints.

• The current level of IF-block nesting. The count begins at 0 and increases for eachnested level.

• The source line from the procedure file.

Errors are reported before the source line of occurrence. Error messages start at the left ofthe listing for easy identification. The expansion of macros also appears in the listing;


7-5


expanded macro lines are preceded by an (M) and shown as they occur after parametersubstitution.

If BOTH is selected, output is sent to the event message log and a listing file on disk via theWINDOW and FILE options.

If NEITHER is selected, error messages are not logged nor is a listing file created.Messages for the beginning and completion of compilation are sent to the message queue.The completion message contains the number of detected errors. These errors are notcounted in the total, however, but in these other compiler options:

• Procedures missing the PROC statement;

• Procedures missing the END PROC statement;

• Procedures with a continuing last line.

Starting a CSTOL ProcedureProcedure execution begins with a START statement of this format:

START procedure-name [argument-list].

Here procedure-name names the CSTOL procedure while argument-list lists the parameterssupplied to the procedure. Each formal parameter needs one corresponding argument of amatching data type.

START may be entered from the keyboard to start a procedure or from a procedure to startanother procedure. These events occur once a procedure is started:

1. A list of compiled procedures is searched for the named procedure. If found,execution begins immediately.

2. If the procedure is not compiled, CSTOL calls the procedure file from disk andcompiles it. If free of syntax errors, execution is initiated.

3. The call arguments are evaluated and the resulting values passed to the procedure.

4. The currently running procedures are suspended until the started procedure iscomplete, then resumed at the point of suspension. Execution is suspended ifanother procedure is called from within or from the keyboard.

Recursive procedure calling — calling a running procedure — is not allowed in CSTOL.


7-6


Controlling a CSTOL ProcedureThe user has substantial control over the execution of CSTOL procedures. The followingCSTOL statements are available to control procedures. They may be entered from thekeyboard or — except for GO — occur within the procedure:

• WAIT suspends execution;

• WAIT AT establishes a breakpoint;

• GO resumes execution;

• GO TO transfers control to a particular line;

• RETURN terminates execution of the current procedure;

• RETURN ALL terminates execution of all active procedures.

Suspending Procedure Execution

Procedure execution is suspended with the WAIT statement. If entered from the keyboard,WAIT allows the current statement to complete, then suspends the procedure beforeprocessing the next statement . WAIT statements occur in the following types:

• An unconditional WAIT is not modified with relational or time expressions. Itcauses procedure execution to stop until GO is entered from the keyboard.

• A timed WAIT is modified with a time expression (WAIT time-expression). If thetime expression is a clock time, the procedure is suspended until that time; if deltatime, the procedure is suspended for the specified duration.

• A conditional/timed WAIT is modified with a relational expression (WAITrelational-expression) and an optional time expression (WAIT relational-expressionOR FOR delta time | OR UNTIL clock time). It stops procedure execution until therelational expression evaluates to true. If the optional delta time or clock time expirebefore the relational expression evaluates to true, the procedure resumes executionafter setting $$ERROR to TIME_OUT. It the relational-expression is true, then$$ERROR is set to NO_ERROR. The rate at which a conditional expression is re-evaluated is governed by the special variable $$CHECK_INTERVAL.

User-initiated procedures are suspended automatically whenever a red limit or state alarmcondition is entered if the special variable $$LIMITS_WAIT is set to ON. See the sectionProcedures and Special Variables below. Chapter 2 has more information on this and other


7-7


special variables. Refer to Chapter 4 of the OASIS-CC System Manager's Guide for moreinformation on limits and states checking.

Setting Breakpoints in a Procedure

The WAIT AT statement specifies a line, by line number or label, where procedureexecution is suspended. When reached, this specification, called a breakpoint, causes theprocedure to automatically enter an unconditional wait state before that line is executed.Breakpoints normally occur when the line is first encountered, although they may be set forevery time.

Another type of breakpoint halts procedure execution depending on Command ExecutionVerification (CEV) results (see Chapter 5 of the OASIS-CC System Manager's Guide).WAIT FOR cev_group halts the procedure until all of the commands named by thecev_group have passed CEV successfully. Cev_group can be a specific group name, orALL, or LAST.

Resuming Execution of a Suspended Procedure

The GO statement resumes procedure execution with the next line in sequence. GOprimarily resumes procedures in unconditional wait states (via WAIT statements,breakpoints or errors), but may also resume procedures in conditional states prior to thesatisfaction of the condition or timed waits prior to the elapse.

The GO TO statement resembles GO, but redirects execution to another line beforeresuming it.

Terminating a Procedure

The RETURN statement terminates a procedure. If started from another procedure,execution of the calling procedure resumes where the terminated procedure ends.

The RETURN ALL statement terminates all active procedures. If procedure X startsprocedure Y and RETURN ALL is encountered, from within or the keyboard, Y isterminated followed by X, continuing until no procedures are running.

Procedures and Special Variables

Some of the special variables available in CSTOL are for status and control of procedureexecution. See Chapter 2 for complete descriptions of all of the special variables.


7-8


$$LOOP_COUNT:

This integer read-only variable contains the number of times the current loop has executed.It is defined within a loop.

$$LIMITS_WAIT

This flag determines whether OASIS-CC automatically halts procedure execution on theuser and sub-CLPs at the time a red limit or state alarm is issued. $$LIMITS_WAIT iseither ON or OFF (default). The special CLPs (command, equation and trigger) areunaffected by $$LIMITS_WAIT. If an ASK statement is active when a red limit or statealarm is issued, responding to the ask will resume execution of the procedure. The variableis defined system wide.

$$CURRENT_TIME:

This clock time read-only variable contains the current system time defined by thecomputer's system clock.

$$STEP_MODE

This state variable contains a value that indicates what occurs after statement execution.The value GO means execute the next statement immediately while WAIT triggers anunconditional wait state. PAUSE means wait a specified amount of time before executingthe next statement. $$STEP_INTERVAL contains the waiting period. It is defined withina procedure.

$$CLP_STEP_MODE

This variable is identical to $$STEP_MODE, however each CLP has its own copy. Whena procedure is started, it inherits and operates with the value of $$CLP_STEP_MODE untilit encounters a setting for $$STEP_MODE, if one exists, within the procedure. Changingthe value of $$CLP_STEP_MODE will not affect execution of active procedures, since thevariable is only used at the time a procedure is started.

$$STEP_INTERVAL

This delta-time variable indicates the time the CSTOL interpreter waits when$$STEP_MODE is set to PAUSE. OASIS-CC maintains $$STEP_MODE and$$STEP_INTERVAL values for every active procedure. Once a procedure begins,OASIS-CC assigns $$STEP_MODE the value GO and $$STEP_INTERVAL the value


7-9


00:00:01. For the desired execution rate, modify these variables with the CSTOL LETdirective from within the procedure or the keyboard while the procedure is running. Whenone procedure terminates and a calling procedure resumes, $$STEP_MODE and$$STEP_INTERVAL revert to the values of the calling procedure.

$$CLP_STP_INTERVAL

This variable is identical to $$STEP_INTERVAL, however each CLP has its own copy.When a procedure is started, it inherits and operates with the value of$$CLP_STP_INTERVAL until it encounters a setting for $$STEP_INTERVAL, if oneexists, within the procedure. Changing the value of $$CLP_STP_INTERVAL will notaffect execution of active procedures, since the variable is only used at the time a procedureis started.

$$LOG_INPUT

This state variable determines if procedure lines are logged to the event message log. IfYES, all procedure lines are logged, if NO, they are not logged. It is defined within eachprocedure.

$$CLP_LOG_INPUT

This variable is identical to $$LOG_INPUT, however each CLP has its own copy. Whena procedure is started, it inherits and operates with the value of $$CLP_LOG_INPUT untilit encounters a setting for $$LOG_INPUT, if one exists, within the procedure. Changingthe value of $$CLP_LOG_INPUT will not affect execution of active procedures, since thevariable is only used at the time a procedure is started.

$$COMPILER_OUTPUT

This variable contains a value to indicate the destination of compiler output. Each CLP hasits own copy of this variable.

$$CHECK_INTERVAL

This variable determines how often a conditional wait statement is re-evaluated. Each CLPhas its own copy of this variable.


7-10


$$ERROR

This STATE variable stores the exit status of a conditional/timed wait. The valueNO_ERROR means the relational expression tested true. TIME_OUT indicates that therelational expression did not test rue before the delta or clock time expired.

Determining the Status of CSTOL Procedures

Information about procedures, compiled or active, is obtained with the SHOW statement.For compiled procedures, use the SHOW COMPILED PROCEDURES statement. Thenames and number of lines for each compiled procedure will appear.

For active procedures, use the SHOW ACTIVE PROCEDURES statement. The names ofthe active procedures, the current line of execution, and the total number of lines in theprocedure will appear.

OASIS-CC CSTOL Reference Manual 8. MacrosRev 0 – 11/94

8-1


8 . Macros

Macros are the principal mechanism for extending CSTOL. They allow users to create newCSTOL statements by combining existing CSTOL statements into a sequence to executerepeatedly, but they execute like single CSTOL statements. Macros resemble procedures inthat they both execute a series of CSTOL statements, but differ as follows:

• Macros execute as a single entity and their execution cannot be suspended orredirected.

• Where a procedure receives the argument value, macros substitute the actualargument text for the associated formal parameter.

• Macros may contain statements entered from the keyboard. IF-blocks and loops arenot allowed.

• The macro source code is not visible to the user during execution. If a macroappears in a procedure, the line containing the macro invocation appears in themessage log, while its CSTOL statements do not.

The Form of a CSTOL MacroMacros have this format:

MACRO macro-name parameter-list

Statement(s)

END MACRO

Here macro-name, an identifier, specifies the macro name as known to CSTOL whileargument-list lists the expected formal parameters. Macro parameters have the form $n,where n is a decimal digit 1 - 9. The first parameter must be $1, the second $2, up to $9.Most macros have one or two arguments.

8. Macros OASIS-CC CSTOL Reference ManualRev 0 – 11/94

8-2


Most CSTOL statements can appear within a macro, including LET, database statementsand commands. However, macros cannot contain statements restricted to procedures, inparticular, IF-blocks and loops as well as MACRO, PROC and END PROC statements.Each macro ends with one END MACRO statement.

Macros always execute to completion — they cannot be suspended, resumed or redirected.Each statement is executed in order of appearance. Statements that control procedures —WAIT, WAIT AT, GO, GO TO, RETURN and RETURN ALL — appear in macros butcontrol only the active procedure, not the macro itself. As a result, execution of a macrowith a WAIT statement causes the suspension of the active procedure.

Preparing a MacroLike procedures, macros are text files prepared with a text editor. The standard fileextension for macro files is .MAC. Each text line in a macro file becomes thecorresponding macro line. The first executable CSTOL statement in a macro file is aMACRO statement, the last, END MACRO. Blank lines or lines with comments mayappear before MACRO, after END MACRO, or between any two statements within.

Installing a MacroThe user must install a new macro file before its use. Installation makes the location of themacro file known to CSTOL for retrieval during definition and execution.

To install a macro, first transfer the macro file to the directory pointed to byOASIS_MACROS. Second, place an entry in the Macros database table to tell OASIS-CCthe appropriate file name. Typically this entry is made through CSTOL using a statementlike this:

INSERT MACROS Macro_Name = macro-name, &Filename = file-name

Her macro-name names the macro in the MACRO statement while file-name names the filewith the macro. Other fields in the Macros table may be filled for macro configurationmanagement. See the OASIS-CC Database Manual.

OASIS-CC CSTOL Reference Manual 8. MacrosRev 0 – 11/94

8-3


Macro DefinitionMacros must be defined before execution. During definition, the macro file is read andportions of its syntax are checked for correctness (macros are affected by run-time textsubstitution, so a complete syntax check cannot be performed until invocation). Macros aredefined using the DEFINE statement in CSTOL: DEFINE macro-name-list.

Here macro-name-list lists the macros to define.

The object code for macros is kept in virtual memory. If many macros are defined, virtualspace may run short. Use the UNDEFINE statement to eliminate macro object code.

Invoking a MacroA macro is invoked when its name appears in place of a CSTOL directive. A macroinvocation uses this format:

macro-name arguments

Macro arguments are separated by blank or tab characters. When examining CSTOLstatement syntax, a CLP first looks for a standard CSTOL directive within the statement. Ifnone appear, the CLP presumes that a macro will be invoked and does the following:

1. The list of defined macros is searched for the macro named in the macro invocation.

2. If found, the macro is processed immediately. If not, the file is read in, defined,and processed.

3. The argument text supplied in the invocation is substituted for the actual macroparameters.

4. The expanded macro is changed to object code. If the macro was entered from thekeyboard, the object code is executed immediately. If included in a procedure, theobject code is copied for later use.

Determining Macro StatusUsers may access information on defined macros with the SHOW DEFINED MACROSstatement. This statement generates a list of currently defined macros in the message log.

8. Macros OASIS-CC CSTOL Reference ManualRev 0 – 11/94

8-4


Example MacroThis example presents a macro that reinitializes a database table. The database table name issupplied as the single macro argument. The table is locked before the restore to preventinconsistencies that might arise if accessed during it.

MACRO REINIT $1

LOCK $1RESTORE $1UNLOCK $1

END MACRO

The macro invocation is:

REINIT Latest_Data

When invoked, the argument (Latest_Data) is substituted for all formal parameter $1.Substitution results in this code:

LOCK LATEST_DATARESTORE LATEST_DATAUNLOCK LATEST_DATA

Expanded statements are then parsed and converted to object code. If entered from thekeyboard, the object code is executed immediately. If within a procedure, the object codeis added to the procedure and saved for later execution.

OASIS-CC CSTOL Reference Manual 9. CommandsRev 0 – 11/94

9-1


9 . Commands

The OASIS-CC teleoperations package allows users to control external elements —spacecraft, science instruments and test equipment. To exercise this control, users sendexternal elements instructions using commands. Two problems generally arise withcommands in space systems. One, the commands are often encoded in a binary formatunderstood by electronic systems but not people. Two, the command formats differ greatlybetween external elements. To compensate, CSTOL provides a natural, English-like wayof command expression with a consistent syntax for all external elements. When a userenters a CSTOL command statement, the following occurs:

1. The Control Language Processor checks the command statement syntax;

2. A parsed version of the command statement is passed to the command processingsoftware within OASIS-CC. This software translates the statement into a commandformat understood by the external element;

3. The command processing software places the translated command into a commandmessage;

4. The command message is transmitted automatically or upon user request.

OASIS-CC usually performs all steps rapidly, making them seem like a single action to theuser. However, users may open a message and buffer multiple commands within it. Oncebuffered, the message is transmitted only with a SEND MESSAGE statement.

This chapter describes the syntax of CSTOL command statements and the procedure usedto control the generation and transmission of command messages. For further informationon commands and command messages, see the OASIS-CC System Manager's Guide.

Basic CommandsEvery CSTOL command statement has two mandatory components, a command directiveand an element name. The command directive specifies the action while an element namespecifies the external element to perform the action. For example:

9. Commands OASIS-CC CSTOL Reference ManualRev 0 – 11/94

9-2


TURN ON INSTRUMENT

CLOSE VALVE_1

The first example presents the command directive TURN ON and the element nameINSTRUMENT. The second presents the command directive CLOSE and the elementname VALVE_1.

A third component — a specific attribute of the external element affected — may be addedas needed. For example:

RESET OVEN TEMPERATURE

Here TEMPERATURE names the oven attribute affected by the command. CSTOLprovides a set of predefined command directives:

ACTIVATE, ARM, BOOT, CHANGE, CLOSE, DISABLE,DISARM, DRIVE, DUMP, ENABLE, FIRE, FLYBACK,FORCE OFF , FORCE ON, GET, HALT, IGNORE,INITIATE, MOVE, OPEN, PASS, PERFORM, RESET,SELECT, SET, SLEW, STEP, TEST, TOGGLE, TURNOFF, TURN ON, USE

Appendix C describes how command verbs can be added or subtracted from the above list.CSTOL is indifferent to command directive meanings; instead, the receiving elementdetermines the meaning based upon its context. For example, the OPEN command allowsflow through a valve but stops the flow of current through an electrical switch. CSTOLcannot detect this ambiguity; the switch and valve determine the meaning of the OPENcommand.

Qualifying and Quantifying CommandsBasic commands are imperative, telling an external element to take an action. If the actionrequires qualification or quantification, OASIS-CC provides clauses and keywords toattach to the command.

Clauses

CSTOL provides four clauses for use in commands. These clauses are introduced withTO, WITH, BY or FROM. A command statement may contain one clause only.

The TO clause sets the command the external element or attribute to a specified value. Forexample:


9-3


SET PUMP SPEED TO 1200. RPM

TURN ON HEATER TO LOW

The WITH clause resembles TO, but assigns values to one or more attributes. Eachattribute is paired with the assigned value. If multiple pairs occur in the clause, subsequentpairs are separated by a comma or the keyword AND. For example:

TEST COMPUTER_1 WITH INTERRUPTS DISABLED

TURN ON TELESCOPE WITH AUTO_FOCUS ENABLED, &AZIMUTH_DRIVE ON AND ELEVATION_DRIVE ON

The first example specifies a value for a single attribute while the second assigns values tothree attributes (AUTO_FOCUS, AZIMUTH_DRIVE and ELEVATION_DRIVE), acomma and the keyword AND separating these pairs. Commas and AND areinterchangeable and the pairs may appear in any order. These WITH clauses equal theabove:

WITH AUTO_FOCUS ENABLED, AZIMUTH_DRIVE ON, &ELEVATION_DRIVE ON

WITH ELEVATION_DRIVE ON AND AZIMUTH_DRIVE ON &AND AUTO_FOCUS ENABLED

The BY clause can be used to indicate a change by a specified amount. For example:

CHANGE OVEN TEMPERATURE BY 10. C

MOVE MANIPULATOR BY -1.4 CM

While the TO and WITH specify absolute values, BY can specify relative change.

The FROM clause can be used to indicate the source of something the command operatesupon. For example:

BOOT COMPUTER_1 FROM DISK_A

Qualifying Keywords

Command statements may contain certain keywords that act as adverbs modifying the verbsused as command directives. Keywords specify the speed or direction of occurrence andare categorized by these specifications. A command may include only one keyword fromeach category. Qualifying keywords appear after clauses, if present.


9-4


These keywords specify speed:

• FAST

• MEDIUM

• SLOW

These specify direction:

• BACKWARD

• FORWARD

• UP

• DOWN

• LEFT

• RIGHT

• IN

• OUT

• CW (clockwise)

• CCW (counterclockwise)

The following command moves a manipulator arm left by 1.4 centimeters:

MOVE MANIPULATOR BY 1.4 CM LEFT

Like other commands, CSTOL does not attach particular meanings to keywords. Forexample, CSTOL is indifferent to speed when FAST is specified. Instead, the receivingelement determines the speed.

Unchecked Bit pattern and ASCII CommandsWhile CSTOL allows command expression in plain English, sometimes commands aremore directly expressed in a format the external element understands quickly. As a result,CSTOL allows users to specify bit strings and ASCII strings as commands. These


9-5


commands — represented as hexadecimal digits, or strings— may be entered with theSEND statement and the external element name. For example:

SEND H#103E2501A78 TO INSTRUMENT_A

This command uses the radix designator H for hexadecimal command strings todifferentiate bit-pattern commands from normal integer constants that use the radixdesignator X for hexadecimal numbers. Similarly:

SEND "This is a test message" TO LISTENER_B

This command results in the transmission of the text enclosed within the double quotes. Ifa quotation mark is to be part of the transmitted test, represent it as a single quote - OASIS-CC will automatically replace it with the ASCII code for a double quote. Chapter 5 of theOASIS-CC System Manager's Guide discusses these as raw commands.

Timed CommandsBecause many spacecraft systems utilize command storage to buffer commands for laterexecution, CSTOL provides a method for specifying timed commands. To specify timedcommand execution, place the word HOLD before the command. The time to release thecommand for execution and the memory location within the command store are specified inclauses that follow the command. For example:

HOLD SLEW INSTRUMENT TO 10.3 DEG &AT X#011C8 UNTIL /-12:30:05

This statement places the command that corresponds to this CSTOL statement

SLEW INSTRUMENT TO 10.3 DEG

into memory location 11C8 (hex). The command will be executed at 12:30:05 today.

Priority CommandsThe keyword NOW indicates the execution of the command at priority level. A prioritycommands will not become part of a command message; instead, message processing issuspended while the priority command is processed and transmitted. For example:

NOW TURN OFF VACUUM_PUMP


9-6


Command MessagesCSTOL allows users to construct command messages with multiple commands and tocontrol message transmission. Command messages are initiated with the MESSAGEstatement to specify the message type. Commands entered after MESSAGE — exceptpriority commands — are processed and placed into the message. The commands arebuffered until transmission or deletion, then sent with the SEND MESSAGE statement.This example shows the construction and transmission of a command message:

MESSAGE TYPE_A;TURN ON INSTRUMENTCLOSE PURGE_VALVESET DETECTOR VOLTAGE TO 12. V;SEND MESSAGE

If transmission fails, the message may be sent again with the RETRY statement. TheCLEAR statement deletes messages.

Microprocessor LoadsMost modern space instruments are controlled by built-in microprocessors. Theprogramming of most microprocessors is altered by transmitting a block of code or data tothe instrument. The LOAD statement initiates this transfer. LOAD specifies the externalelement receiving the load, the starting memory location where the load is placed, and thefilename to take the load from. For example:

LOAD INSTRUMENT_A AT X#125E FROM MP_FILE_123A

See the OASIS-CC System Manager's Guide for the proper microprocessor load fileformat.

OASIS-CC CSTOL Reference Manual 10. Description of CSTOL StatementsRev 1 – 11/94

10-1


10. Description of CSTOL Statements

This chapter describes all CSTOL statements, each type discussed in an alphabeticallyarranged section. Particularly complicated types are decomposed into smaller sections tocover all variations. Each section contains the following information:

• A general statement description;

• The statement syntax;

• A description of each statement component;

• Notes on the proper statement usage.

The component description identifies user expectations and, for arguments, the appropriatedata types. The argument description indicates if an argument is a constant or variableonly. If not indicated, use the constant or variable of the appropriate data type.

10. Description of CSTOL Statements OASIS-CC CSTOL Reference ManualRev 1 – 11/94

10-2


ASKASK asks a question displayed in a dialogue window and receives an answer from theuser. The user enters the answer into the dialogue window and its value is placed into thespecified local variable. The dialogue window disappears and the reply value is used,typically in an IF statement, to direct the flow of processing.

Format

ASK reply-variable question

Arguments

reply-variable (local variable): The name of the local variable storing the result. Its datatype must be compatible with that of the user-entered value.

question (string constant): A text string containing the text within in the ASK window.

Notes

1. Most questions in an ASK statement are simple and require simple replies. Forexample, many questions require YES or NO answers. More complex replies mayinclude CSTOL expressions. When the user hits [return] to terminate the reply, theexpression is evaluated and its value deposited into the local variable.

2. Local variables must be previously defined with a DECLARE statement. The valueobtained from the evaluation of the user-entered expression must match the valueexpected for the local variable. For example, state variables require ON and OFFvalues. If not entered, an error message is issued, the dialogue window disappearsfrom the screen, and the local variable remains unchanged.

3. Expressions entered as replies to ASK statements are limited to 256 characters.Explicit continuation characters are not available for ASK responses — once theend of the line is reached, it scrolls to allow typing on the next line.

4. The ASK statement does not supply default values for local variables. Pressing[return] results in an error message. Local variables will remain unchanged.

5. Upper and lowercase letters are indistinct. Input is converted to uppercase unlessenclosed by double quotation marks.


10-3


BEGINBEGIN divides procedures into two sections:

• All statements between the procedure start and BEGIN, a section usually used forDECLARE statements, are executed at the outset. This. DECLARE insures theproper declaration of all variables when the procedure executes. BEGIN may alsoset special variables to control procedure execution, like $$LOG_INPUT and$$STEP_INTERVAL. The user cannot place the procedure into a WAIT state orredirect procedure execution with a GO TO statement until BEGIN is reached.

• After BEGIN, the procedure may be suspended or redirected at any statement usingWAITs, GO TOs, or keyboard entries. Most statements appear after BEGIN, toallow the user maximum control over the procedure.

Format

BEGIN

Notes

1. statements occurring before and after BEGIN are currently indistinct to OASIS-CC.In reality, BEGIN has no real effect on procedure execution. However, a futureversion will enforce these rules, so users should follow them.

2. When execution occurs by an autonomous (non-interactive) Control LanguageProcessor as a trigger response, automatic equation, or command pre- or post-check, BEGIN is ignored. The procedure acts like those occurring before BEGIN,where control cannot be interrupted or altered. Use interactive mode to create suchprocedures by omitting BEGIN.


10-4


CANCELCANCEL deletes the current command message, stopping transmission in the process.Once sent, command messages cannot be canceled.

Format

CANCEL


10-5


CHECKPOINTCHECKPOINT creates database-format disk images for database tables records.

Format

CHECKPOINT ALL TO name

CHECKPOINT table-name WHERE selection-expression

Arguments

name (): translates to an upper case environment variable ($NAME) that identifies thedirectory to which a complete database checkpoint is written.

table-name (identifier): The database table containing the records to checkpoint.

selection-expression (): A relational expression with sub expressions of the form field-name=value where field-name is a field and value is a constant value the field iscompared against. Multiple sub expressions are connected by the logical connectiveAND. Records where every field has the specified value are candidates forcheckpointing.

Notes

1. The first form, (CHECKPOINT ALL TO name) creates a complete image of theOASIS-CC database from which a future OASIS-CC session may be started.Database files are stored in the directory defined by the environment variable$NAME (must be upper case). The files are named by the table with a ".dat"appended (e.g. analog_conversions.dat).

All primary streams must be switched off and retrieved off, all telemetry displaysmust be cleared, and all bridge files must have recording stopped prior to attemptingthis form. If these conditions are not met, OASIS-CC will issue an error messageand abort the request.

2. The second form (CHECKPOINT table-name WHERE selection-expression) createsimages of the selected table to be made for book-keeping purposes. OASIS-CC doesnot care about the status of the table in this form. Care should be taken not to startOASIS-CC from one of the files created by this form of checkpoint. If, for example,OASIS-CC was activated with a checkpointed Streams table where the field


10-6


stream_is_on = true, the user could never activate the stream - OASIS-CC will reply"The stream is already on" when the switch is attempted. Checkpoint files are placed inthe directory pointed to by the environment variable $OASIS_CHECKPOINT, and arenamed fyy_mon_doy_hh_mm_ss.table_name (e.g. limits.f94_dec_25_12_34_45).

3. CHECKPOINT in either form is intended as a tool to save database information thathas accumulated during an OASIS-CC run. A similar directive, COMMIT is intendedas a tool to create disk copies of database tables during application development.


10-7


CLEARCLEAR stops display processing for an output window, then removes the window fromthe screen. CLEAR ALL removes all windows of a specified type.

Format

CLEAR page_name [FROM terminal_nickname]

CLEAR ALL page_type [FROM terminal_nickname]

Arguments

page_name (identifier): The window name to remove.

page_type (identifier): The window type to remove. Use one of these keywords:

DISPLAYS Clear data display windowsMESSAGES Clear event message windowsCOMMANDS Clear windows that show command messagesREPORTS Clear database report windows

terminal_nickname (identifier): A name identifying a remote terminal to remove thewindow from. If unspecified, terminal_nickname defaults to the terminal where thestatement is entered. If specified, the terminal_nickname provides a key into theLinks table, which stores the full host and terminal ID.

Notes

1. See Chapter 9 of the OASIS-CC System Manager's Guide for more information onremote displays.


10-8


CHECKCHECK compares a data value against a value or range of values supplied by the user, andsends the results to the message queue.

Format

CHECK parameter-list

Arguments

parameter-list: One or more of the following elements, separated by a comma (,)

Character string (text between double quotes(")

Local variable [check-list]

Global variable [check-list]

check-list: VS value_1 : value_2

Notes

1. Character strings are output without change.

2. When a global or a local variable is specified, its named is output, followed by itsvalue.

3. All local variable types are supported, except delta times and clock times. All globalvariable types are supported - including raw values.

4. When a single value is supplied in the optional check-list, the value of the local orglobal variable is checked for equality. If not equal, the portion of the messageassociated with the check is red, and flagged as ne (not equals).

5. When two values appear in the optional check-list (value_1 and value_2), OASIS-CC checks if the value of the local or global variable is within the range of value_1and value_2 (inclusive). If not within the range, the portion of the messageassociated with the check is red, and flagged with either lt or gt (less than or greaterthan).

6. Check-lists must always include a colon (:), even if a single value is used.


10-9


7. Values in a check-list can be valid CSTOL numeric expressions.


10-10


CommandsCommands specify actions performed by external systems controlled by OASIS-CC.When executed, OASIS-CC software translates the command into a string of ASCIIcharacters or bits understood by the external system. OASIS-CC also attaches commandmessage and ground network protocols necessary to route the command to the externalelement. See Chapter 9 for a more complete discussion of CSTOL command statements.See the OASIS-CC System Manager's Guide for further information on the conversion ofCSTOL command statements into external element commands.

Basic Command Syntax

Every command has two components. A command directive specifies an action while anelement name specifies the external element receiving the command. A third component, aspecific attribute of the external element, may appear as needed.

Format

command-directive element-name [attribute-name ]

Arguments

command-directive (identifier): A word or two-word phrase that specifies the action ofthe command.

external-element (identifier) The external element that receives the command.

attribute-name (identifier): An optional attribute of the external element. If omitted, thecommand specifies no attribute.

Notes

1. CSTOL contains a standard set of command directives (See Chapter 9). Newcommand directives are added through modification of the CSTOL parser tables asdescribed in Appendix C.

2. The OASIS-CC internal database design limits the length of attribute names beyondthe normal rules for identifiers. See the OASIS-CC System Manager's Guide.


10-11


Clauses and Keywords

Basic commands are imperative, telling an external element to take an action. However,some actions require qualification. OASIS-CC provides certain qualifying clauses,including TO, WITH, BY and FROM, to attach to commands.

The TO clause causes the command to act by setting the external element or attribute to aspecified value. The WITH clause resembles TO except that one or more attribute valuesmay be specified. The BY clause causes the command to act by changing the externalelement or attribute by a specified amount. The FROM clause indicates a source thecommand must act upon.

A command may also contain keywords to qualify the speed or direction of change.

Format

basic-command TO value [speed-qualifier] [direction-qualifier]

basic-command BY amount [speed-qualifier] [direction-qualifier]

basic-command FROM source [speed-qualifier] [direction-qualifier]

basic-command WITH attribute value [speed-qualifier] [direction-qualifier]

Arguments

attribute (identifier): An attribute of the external element to set to the associated value.

value (integer, state, delta time, engineering unit): The value to set the external elementor attribute to.

amount (integer, state, delta time, engineering unit): The amount to change an externalelement or attribute.

source (integer, state, delta time, engineering unit): The place name something isretrieved from.

speed-qualifier (identifier): A keyword specifying the speed of action. The choices areFAST, MEDIUM, and SLOW.

direction-qualifier (identifier): A keyword specifying the direction of change. Thechoices are BACKWARD, FORWARD, UP, DOWN , LEFT, RIGHT, IN, OUT,CW (clockwise), and CCW (counterclockwise).


10-12


Notes

1. A command may contain one clause, one speed qualifier and one direction qualifieronly. Qualifying keywords occur after clauses. Speed or direction qualifiers mayappear in either order.

2. Multiple attribute/value pairs may appear in a WITH clause. Separate each pair witha comma or the AND keyword.

Timed Commands

The HOLD keyword indicates that a timed command is placed into intermediate commandstorage at the receiving element rather than executed immediately. Timed commandscontain not only the command pattern, but also the memory location and the desired time ofexecution.

Format

HOLD command [AT location] [UNTIL time]

Arguments

location (integer constant): The memory location of the command in storage.

time (clock time constant): The release time for execution.

Notes

1. See the OASIS-CC System Manager's Guide to set up timed commands.

2. An AT or UNTIL clause may appear first.

3. The external element must provide intermediate command storage.

Priority Commands

The NOW keyword indicates the execution of the command at priority level. For example:NOW TURN OFF VACUUM_PUMP.

Format

NOW command


10-13


Notes

1. See the OASIS-CC System Manager's Guide to set up priority commands.

2. Priority commands are transmitted even if the special variable,$$COMMAND_MODE, is set to NO_ISSUE.

3. Priority commands are not placed in buffered command messages. Instead,message processing is suspended while the priority command is processed andsent.


10-14


COMMITCOMMIT saves the current contents of the named database table to disk, establishing thestate the table is set to when OASIS-CC is started or a RESTORE statement is executed.

Format

COMMIT table-name

Arguments

table-name (identifier): The name of the table to commit to disk.

Notes

1. The table must be locked and restored before COMMIT is used. Only the userissuing the lock may commit the table.


10-15


COMPILECOMPILE precompiles CSTOL procedures. Compilation consists of parsing and saving aprocedure (object code) for later execution. Compilation has two advantages:

• Syntax errors are detected during compilation before one uses the procedure.

• Procedures that are parsed and ready to run begin execution more quickly.

Format

COMPILE procedure-list

Arguments

procedure-list (identifier): The list of procedures to precompile. If multiple proceduresare specified, separate them with commas.

Notes

1. All procedures to compile must appear in the Procedures database table. This entrytells the CLP the filename containing the procedure source code. The file is locatedin the directory indicated by OASIS_PROCS.

2. See DECOMPILE for removal of CSTOL procedures from the system.

3. Undefined macros within the procedure are defined during compilation.

4. A procedure list with compilation errors is available in CSTOL. See the Proceduressection for further information.


10-16


CSTOL OFFCSTOL OFF terminates an OASIS-CC session. OASIS-CC terminates all activeprocedures and streams and clears all display windows from the screen.

Format

CSTOL OFF

Notes

1. Logging out of OASIS-CC terminates the reception and recording of active streams.

2. In general, if OASIS-CC fails to exit properly, press CONTROL-Y and enter aSTOP directive at the DCL prompt. Issue CONTROL-C for Unix.


10-17


DECLAREDECLARE defines the parameters passed to and the constants and variables used locallywithin a procedure.

Format

DECLARE mode variable-name = default-value [range value-list]

Arguments

mode (identifier): A keyword specifying the data type of the declared item. The valuesare:

The INPUT declaration supplies additional information about an input parameter,its data type established by the default value. The argument value passed to theprocedure must have the same data type. The actual value of an input variable is thevalue of this argument.

The VARIABLE declares a local variable. The local variable receives the data typeand value of the default value. The value can change if the variable appears on theleft side of a LET statement, but the data type cannot be changed, remaining thesame as when initially declared.

The CONSTANT declaration creates a local constant. The constant receives theunchangeable default value from the statement. Constants cannot appear on the leftside of a LET statement, while the range or value specification is ignored.

variable-name (local variable): The name of the declared variable. This name uses thecorrect format for a local variable name — an identifier preceded by a $.

default-value (any constant): A default value of any constant type must be supplied. Itsdata type determines the local variable type. The variable only accepts values of thespecified type. If an engineering unit value, the local variable has the same type ofunits specified for the default value.

range (numeric constant): An optional range of legal values for numeric constantsspecified in the form lowest-allowed-value : highest-allowed-value. The data typesof values supplied in a range clause must equal those of the default value.


10-18


value-list (literal): A list of valid values for a state variable. The list must include everypossible state the variable can accept.

Notes

1. A variable or constant may be declared once within a procedure. Attempts toredefine a variable or constant result in compilation errors. The ability to reset thevalue of variables using the LET statement is not limited.

2. To assure execution, DECLARE appears before the BEGIN statement. Otherwise,a necessary variable or constant may not be declared before its reference in anotherstatement, causing the procedure to halt with an error.

3. No range specification or value list is allowed for clock and delta times, hex bitstrings and character strings.

4. Although allowed by the language, a range specification or value list are useless forconstants; they use the value assigned in the declaration.


10-19


DECOMPILEDECOMPILE removes compiled procedures from the CLP list. This statement has twoadvantages:

• To remove a changed procedure, creating room for a new version. STARTstatements always use precompiled versions. To enter a new version into the CLP,recompile the procedure using the COMPILE statement or DECOMPILE so the nextSTART statement may recompile the new version.

• To free up memory space holding the procedure object code. If compiledprocedures are no longer needed, these procedures may be decompiled to freevirtual memory space.

Format

DECOMPILE procedure-list

DECOMPILE ALL PROCEDURES

Arguments

procedure-list (identifiers): The names of procedures to decompile. If multipleprocedures are specified, separate them with commas.

Notes

1. DECOMPILE ALL PROCEDURES decompiles only inactive procedures.


10-20


DEFINEDEFINE preprocesses a CSTOL macro. Like the compilation of procedures, macrosspecified in the statement are read into the CLP and placed on a list. Unlike compilation,macros are not converted to object code when defined, but when invoked from thekeyboard or within a procedure.

Format

DEFINE macro-name-list

Arguments

macro-name-list (identifier): A list of macro names to define.

Notes

1. All macros to be defined must have an entry in the Macros database table. Thisentry tells the CLP the filename containing the macro source code. The file must belocated in the directory pointed to by OASIS_MACROS.


10-21


DELETEDELETE removes all records meeting the selection criteria from the named database table.

Format

DELETE table-name WHERE selection-criteria

Arguments

table-name (identifier): The database table containing records to be deleted.

selection-criteria (expression): A relational expression in the form field-name = value[AND field-name = value...], where field-name is the name of a field contained inthe database table and value is a constant that field is compared to. Only recordswhere the entire expression evaluates to TRUE — where every named field has thespecified value — are deleted.

Notes

1. The only relational operator currently allowed in the selection criteria expression isthe equality (=) test. Only the AND connective may be used.

2. Any value other than an integer number, real number, or identifier (an alphacharacter followed by a sequence of alphanumeric characters) must be enclosed inquotes.


10-22


DISPLAYDISPLAY causes the named page or panel to appear on a monitor. If unspecified, thedestination monitor defaults to the terminal where the statement is entered.

Format

DISPLAY page-name [AT column row]

DISPLAY page-name [TO remote-terminal-nickname]

Arguments

page-name (identifier): The page name to display. OASIS-CC looks to see if the pagename corresponds to a page_name field in Display_Descriptions. If so, OASIS-CCuses the associated tae_panel_name for the name of the TAE+ panel to display. If aDisplay_Descriptions record doesn't exist, or the tae_panel_name field is blank,OASIS-CC assumes the TAE panel name is the supplied page name. The pagename can also be one of the windows not created by TAE+, such as the page fordisplaying CSTOL procedures.

remote-terminal-nickname (identifier): An name identifying a record in the Links tablethat contains an Internet address and terminal identifier for the host system forwhich the remote display is intended. Only TAE+ displays and OASIS-CCmessage windows can be displayed remotely. For example, if the TAE+ panelnamed master was desired on a workstation with the given nickname monitor_3,the display statement would be:

display master to monitor_3

and the Links database table record with the link_name monitor_3 would have anassociated data_line field would contain "128.138.138.19:0.0". See Chapter 9 ofthe OASIS-CC System Manager's Guide for more information on remote displays.

column (integer constant): The screen character column holding the lower left corner ofthe window. If unspecified, the default page position in the Display_Descriptionsdatabase table is used. The AT clause is only applicable to the pages generated byOASIS-CC – not TAE+ panels (see Chapters 8 and 9 of the OASIS-CC SystemManager's Guide).


10-23


row (integer constant): The screen character row holding the lower left corner of thewindow. If unspecified, the default page position in the page definition databasetable is used. The AT clause is only applicable to the pages generated by OASIS-CC – not TAE+ panels (see Chapters 8 and 9 of the OASIS-CC System Manager'sGuide).

Notes

1. The TO qualifier is used to display the page on a remote X-based workstation orterminal. Prior to issuing remote displays, the X-server must be active on theremote workstation the remote workstation must be authorized to accept X requestsfrom workstation running OASIS-CC. See Chapter 9 of the OASIS-CC SystemManager's Guide for more information on remote displays.


10-24


ELSEThe optional ELSE introduces the default part of an IF-block. If the relational expressionin the IF statement and all ELSE IF expressions evaluate FALSE, the statements followingELSE are executed. If the IF or ELSE IF evaluates TRUE , the ELSE is skipped. Only oneELSE may occur in an IF-block.

Format

ELSE


10-25


ELSE IFELSE IF marks the beginning of a set of statements within an IF-block that are executed ifboth of these conditions are met:

• The expression in the IF statement and preceding ELSE IFs evaluate FALSE;

• The expression in the particular ELSE IF evaluates TRUE .

When the expression in an ELSE IF evaluates TRUE , the statements following it areexecuted in sequence until an END IF, ELSE IF or ELSE occurs. Further ELSE IF orELSE parts of the block are skipped regardless of how they evaluate. Execution continuesfrom the END IF.

Format

ELSE IF controlling-expression

Arguments

controlling-expression (relational expression): The relational expression evaluated.This expression governs the execution of statements in the ELSE IF.

Notes

1. The controlling expression must evaluate TRUE or FALSE. Other values result inan error.


10-26


ENDEND marks the end of a block of statements. END is always paired with a statementbeginning of the block. END uses these block types:

Procedures PROC and END PROCMacros MACRO and END MACROLoops LOOP and END LOOPIF Blocks IF and END IF

Because blocks occur only within procedures or macros, END statements are entered fromthe keyboard.

END IF

END IF terminates an IF-block. Every IF-block must have an associated END IF.

Format

END IF

END LOOP

END LOOP marks the end of a block of statements that execute repeatedly. When ENDLOOP occurs, execution cycles return to the first statement following the LOOP statement.One END LOOP occurs for each LOOP statement.

Format

END LOOP

END MACRO

END MACRO the end of a CSTOL macro. END MACRO causes the CLP to stop readinginput from a macro source file. Statements after END MACRO cause errors.

Format

END MACRO


10-27


END PROC

END PROC marks the end of a procedure.

END PROC statement stops the CLP from reading procedure input and terminatescompilation for the procedure file. Any statements after END PROC are ignored. Aprocedure will compile without END PROC, but OASIS-CC returns a system error oncethe procedure begins.

Format

END PROC


10-28


ESCAPEESCAPE breaks a counted or indefinite loop. Procedure execution resumes with thestatement following END LOOP.

Format

ESCAPE

Notes

1. ESCAPE is valid only within a LOOP.

2. ESCAPE is most useful when used with an IF statement to determine whetherconditions warrant breaking the loop.


10-29


FLUSHFLUSH resets the Command Execution Verification (CEV) function. See Chapter 5 of theOASIS-CC System Manager's Guide for details on CEV.

Format

FLUSH command-group-name

FLUSH ALL

Arguments

command-group-name (identifier): name of the command group to be reinitialized.

Notes

1. All commands belonging to the command-group-name are removed from thepending CEV queue, and the counters of the failed commands in the command-group-name are reset to zero.

2. FLUSH ALL is identical to FLUSH command-group-name, except that allcommands are removed and all failed command counters are reset to zero.

3. FLUSH in either form generates messages indicating which commands wereremoved, and which counters were reset. The format of these messages followsthe format of messages generated by the SHOW PENDING CEV statement.


10-30


GOGO resumes procedure execution at the next statement in sequence.

Format

GO

Notes

1. GO cannot appear within a procedure; the procedure would be running before thestatement is executed.


10-31


GO TOGO TO repositions the procedure to a specified label or line number and resumes executionfrom there.

Format

GO TO label

GO TO line

Arguments

label (identifier): The label name where execution is redirected.

line (positive integer constant): The line number where execution is redirected.

Notes

1. Line numbers appear only in GO TOs issued from a terminal. References to linenumbers are not allowed within procedures or macros to prevent the addition ordeletion of lines from a procedure, accidentally causing execution to go to anunintended line.

2. Errors occur if no procedures are active, the specified label does not currently exist,or the reference to a line number beyond the last procedure line. Repositioningdoes not occur with an error. The procedure instead waits for corrective actionfrom the user at the GO TO.

3. The blank between GO and TO is optional.

4. If a procedure is in WAIT when GO TO is issued, the procedure is repositioned tothe specified line, remaining in WAIT until GO is entered or WAIT conditions aremet.


10-32


IFThe basic mechanism for decision-making is the IF-block. All IF-blocks start with an IFstatement. The specified relational expression is evaluated and, if TRUE , CSTOLstatements following the IF are executed to an END IF, ELSE IF or ELSE. IF cannot beentered from the keyboard, but may appear within procedures and macros.

Format

IF controlling-expression

Arguments

controlling-expression (relational expression): An expression with a TRUE or FALSEresult value.

Notes

1. IF must be paired with an END IF to mark the end of statements it controls.

2. GO TO statement may be used to enter or exit an IF-block, although such actionsmay yield unpredictable results.

3. See Chapter 6 for more information on IF-blocks.


10-33


INITIALIZEThis statement initializes an IEEE-488 bus controller.

Format

INITIALIZE data-stream

Arguments

data-stream (identifier): The stream name for the appropriate IEEE-488 controller.

Notes

1. This statement puts the IEEE-488 controller into the Controller in Charge state.


10-34


INSERTINSERT creates a new record in a database table, filling the record fields with values fromthe value list. The value list must use named notation.

Format

INSERT table-name value-list

Arguments

table-name (identifier): The database table to store the new record.

value-list (): An item list where each item uses the format, field-name = value, field-name is the a field in the database table, and value is a constant that provides thevalue to place into the field. If multiple items are specified, separate the names withcommas. The value may be:

• An integer or real number;

• A state or other literal;

• A text string.

The value and field types must agree.

Notes

1. All key fields must be included; unspecified non-key fields receive the defaultvalues.



10-35


LETLET evaluates an expression and stores the result into the specified variable. Resultsinclude a global variable, a local variable or a special variable (some special variables areunable to store). The result and variable data types must agree. The result value mustoccur within the range of the result variable.

Format

LET variable = expression

Arguments

variable (global, local or special variable): The variable storing the result. If a globalvariable results, the value is placed in the Latest_Data table.

expression (arithmetic or logical expression): The expression to evaluate.

Notes

1. The expression and variable data types must agree. Compatibility exists betweenthe expression result and the destination variable if any of these factors are true:

• They have the same data type. State values require that the expression resultstate is a legal value associated with the variable.

• The expression result is an integer value and the variable is real; the value isconverted to real.

• The expression result is a real value and the variable is an integer; the result isconverted an integer through truncation.

• The expression result occurs in engineering units that may be converted intothe variable units. For example, if the expression result occurs in microvoltsand the variable in volts, the result is converted to volts.

• The expression evaluates to a real number and the result variable occurs inengineering units, or vice versa.

• The expression evaluates to an integer number and the result variable occursin Data Numbers, or vice versa.


10-36


Other combinations result in an error.

2. Certain special variables cannot appear as the LET destination variable. They are:

$$CURRENT_TIME contains the current time of the system clock and cannot bereset by CSTOL.

$$LOOP_COUNT contains the current number of loop iterations, incrementingwith each time loop. The $$LOOP_COUNT special variable is undefined beyondits loop. If occurring within an expression beyond the loop, an error occurs.


10-37


LOADThis statement sends the contents of a file to an external element.

Format

LOAD external-element-name AT location FROM file-name

Arguments

external-element-name (identifier): The external element where the load is directed.

location (integer constant): The address where the load is inserted.

file-name (long identifier): The file holding data to send.

Notes

1. This application dependent statement mainly sends microprocessor loads.

2. The AT location phrase may be ignored for some applications.

3. The file must be located in the logical directory OASIS_LOAD.

4. The filename extension is .LOAD.

5. The file has a specific format described in the System Manager's Guide.


10-38


LOCKLOCK reserves the named database table exclusively for the user issuing the statement.Required when a table is permanently modified, LOCK prevents other users frommodifying the table while the permanent updates are made.

Format

LOCK table-name

Arguments

table-name (identifier): The database table to lock.

Notes

1. If a user attempts to access or lock a already-locked table, an error message is sentto that user denying the request. If a user issues a lock request for a table that userhas locked, no change occurs.

2. A significant risk occurs when locking a database table during real-time operations.Consequently, when a lock granted, OASIS-CC issues a warning to the user notingwhen a particular table was last used.


10-39


LOOPLOOP marks the beginning of a loop block, a block of statements that execute repeatedly.

Format

LOOP [repeat-count]

Arguments

repeat-count (integer): The number of times the loop is repeated. If unspecified, theloop repeats endlessly unless a GO TO or ESCAPE stops it. The repeat-count mustbe an integer constant or a local variable with an integer value.


10-40


MACROMACRO marks the beginning of a CSTOL macro.

Format

MACRO macro-name [macro-parameters]

Arguments

macro-name (identifier): The name of the macro.

macro-parameters (): Consists of parameter specifiers $1 ... $9 separated by spaces.Parameter specifiers must appear in ascending numeric order starting from $1.When the macro expands, text associated with the macro invocation is substitutedfor the parameter.

Notes

1. The entry in the Macros database table must name a file residing in the logicaldirectory OASIS_MACROS.

2. When a macro is used from the keyboard or in a procedure, the current macrodefinition is used. To reflect a new macro definition in a procedure, the macro mustbe defined with DEFINE and the procedure recompiled to use of this latestdefinition.


10-41


MAKEMAKE sets bus devices or instruments to a defined state.

Format

MAKE DEVICE/INSTRUMENT device-name-list BE/DO state

MAKE ALL DEVICES ON stream-name-list BE global-state

Arguments

device-name-list (identifier): The affected IEEE-488 devices.

state (identifier): The communications class for devices — REMOTE, LOCAL_LOCK,RESET, LOCAL, or TRIGGER

global-state (identifier): The communications class for devices — REMOTE,LOCAL_LOCK, RESET, or LOCAL

stream-name-list (identifier): The streams containing affected devices.

Notes

1. The devices specified in MAKE may not reside on the same IEEE bus.

2. The word INSTRUMENT is interchangeable with DEVICE while BE interchangewith DO to allow for improved readability.


10-42


MESSAGEMESSAGE marks the beginning of a command message. Commands entered after thisstatement — except priority commands — are placed into the message until full, transmittedwith a SEND MESSAGE statement, or deleted with a CANCEL statement.

Format

MESSAGE external-element-name[HOLD AT location] [UNTIL release-time]

Arguments

external-element-name (identifier): The external element receiving the message.

location (integer constant): The location of the message within a command store.

release-time (clock time constant): The release time for execution.

Notes

1. A MESSAGE statement may have one AT and one UNTIL clause only. If both arepresent, they may occur in either order (AT or UNTIL first).

2. OASIS-CC does not provide command store. It must reside in some externalelement (usually a spacecraft or ground support system).


10-43


POLLThis statement instructs OASIS-CC to get the status byte of IEEE-488 devices.

Format

POLL DEVICE device-name-list

POLL BUS stream-name-list

Arguments

device-name-list (identifier): The names of the devices to be polled, separated bycommas.

stream-name-list (identifier): The name of the stream on which all devices are to bepolled, separated by commas.

Notes

1. The POLL DEVICE statement causes OASIS-CC to get the status byte of the listeddevices.

2. The POLL BUS statement causes OASIS-CC to wait for the SRQ line to beasserted on one of the listed streams. When SRQ is asserted, OASIS-CC gets thestatus byte from the device(s) that requested service. This functionality is enableduntil a STOP POLLING BUS statement is issued.


10-44


PROCPROC marks the beginning of a CSTOL procedure by specifying the procedure name andproviding the parameter names it accepts.

Format

PROC proc-name [formal-parameter-list]

Arguments

proc-name (identifier): The procedure name. This name matches the name in theProcedures database table.

formal-parameter-list (local variable): Local variable names of the parameters within theprocedure.

Notes

1. If not compiled with a COMPILE or START statement, the procedure is compiledand executed when START is issued. If previously compiled, execution beginsimmediately.

2. The formal parameter names must be unique. A name may appear once only in theformal parameter list. Each formal parameter should appear in a DECLAREstatement that supplies additional information about it.


10-45


RECORDRECORD enables the logging event messages, incoming data streams, and bridge streams.Chapter 10 of the OASIS-CC System Manager's Guide has more information on theformats of certain files recorded by OASIS-CC.

Format

RECORD record-mode [title]

Arguments

record-mode (identifier): The data type logging is enabled for. If the record-mode isMESSAGES, logging of event messages is affected. Other record-modes includeincoming data streams or bridge streams.

title (string): Text placed in a header file to identify the recorded stream.

Notes

1. Incoming data streams are recorded in files in OASIS_RECORD. Filenamesgenerated for data streams have the form F yy_mm_dd_hh_mm_ss, specifying theyear, month, day, hour, minute, and seconds the data stream is opened. Two fileswith the same name but different extensions are produced for a data stream:

.stream_name The data stream itself.stream_name_HEADER The title

2. Bridge stream files are placed into OASIS_BRIDGE. The filenames for bridgestreams use the same format as incoming data streams. A bridge stream has threefiles with the same name but different extensions:

.stream_name_DATA The bridge stream itself

.stream_name_HEADER The title

.stream_name_IDENTA description of the data file

3. Message files are placed in OASIS_MSG_LOGGING. The filenames for messagelogs follow the same conventions as data and bridge streams. A message log hastwo files with the same name but different extensions:


10-46


.EVENT_MESSAGES The message log itself

.EVENT_MESSAGES_HEADER The title

4. For compatibility with previous OASIS-CC versions, the formats RECORD ONrecord-mode [title], RECORD OFF record-mode, and RECORD OFF ALL aresyntactically correct.


10-47


REPORTREPORT produces a listing of fields for all records of the table where the selection clauseholds. The listing goes to the appropriate terminal (output goes to a special report window)or a disk file. The default device is the terminal where the request was issued.

Format

REPORT table-name [field-list][WHERE selection-expression] [TO device]

Arguments

table-name (identifier): The database table receiving the records.

field-list (long identifier): A list of fields to report.

selection-expression (relational expression): A conditional expression where eachsubexpression has the format field-name = value where field-name is a record fieldand value is a constant the field is compared against. Multiple subexpressions areconnected by the logical connective AND. Only records where all named fieldshave the specified value are reported.

device (identifier): The device where output is directed. This device is WINDOW,FILE, or BOTH.

Notes

1. If no device is specified at the request, the report is written to the report window, ifpresent. Otherwise, the report is written to a disk file described below.

2. Report files are placed in the logical directory OASIS_REPORTS. The filename isthe described database table while the file extension is .REPORT.



10-48


RESTOREThis directive restores the contents of the named database table to the last committed state.

Format

RESTORE table-name

Arguments

table-name (identifier): The database table to restore.

Notes

1. The table must be locked before RESTORE is issued. Only the user who locks thetable may restore it.

2. Under certain conditions, OASIS-CC will not restore certain tables. If telemetrydisplays are present or if data are bridged, the Latest_Data table cannot be restored.Likewise, Streams cannot be restored if streams are active. These restrictionsprevent potentially dangerous resetting of certain fields within these tables.


10-49


RETRIEVERETRIEVE gets stored data blocks from disk and reads them into OASIS-CC as if datawere entering from a data line.

Format

RETRIEVE data-stream FROM file-name[BEGINNING start-time] [UNTIL stop-time] [EVERY retrieval-rate]

Arguments

data-stream (identifier): The data stream attached to incoming information.

file-name (long identifier): The file containing the data to retrieve.

start-time (clock constant): Records in the file are time indexed. This argumentspecifies the first record to retrieve.

stop-time (clock constant): This argument specifies the last record to retrieve (see start-time).

retrieval-rate (delta time constant): The rate of retrieval specified in frames per second.

Notes

1. The file for the retrieved data must appear in the logical directory OASIS_RECORDwith a filename of this format: filename.data-stream.

2. At the end of stream retrieval, STOP RETRIEVING must be issued to access thestream again.

3. For compatibility with previous OASIS-CC versions, the formats RETRIEVE ONdata-stream, RETRIEVE OFF data-stream, and RETRIEVE OFF ALL aresyntactically correct.

4. If the stream's record in the Streams table has a secondary offset that is not 0,OASIS-CC will build the decomposition tree for this stream when it is retrieved.This may take several minutes for complex data streams. If the secondary offset forthe primary stream is 0, OASIS-CC will look for a pre-saved copy of the stream'sdecomposition tree instead – a much faster operation. See Chapter 6 of the OASIS-


10-50


CC System Manager's Guide for details on how to generate disk copies ofdecomposition trees.


10-51


RETRYRETRY sends a command message or a single command again, working only if themessage is previously transmitted.

Format

RETRY


10-52


RETURNRETURN terminates the current procedure and returns to the previous one. RETURNALL terminates all active procedures associated with the CLP.

Format

RETURN

RETURN ALL

Notes

1. RETURN ALL is usually entered from the keyboard, but may appear in aprocedure.


10-53


ROUTEROUTE sends part of a return stream to a forward stream or to a Sub-CLP.

Format

ROUTE secondary-stream TO forward-stream

ROUTE secondary-stream TO Sub-CLP ID

Arguments

secondary-stream (identifier): The secondary data stream from the Streams table.

forward-stream (identifier): The forward data stream.

Sub-CLP ID (identifier): Legal values are clp_1, clp_2...clp_20.

Notes

1. A secondary stream may be routed to many forward streams.

2. ROUTE returns an error if the return primary stream parent of the routed secondaryis not ON (not switched on or not retrieved) or the forward stream is not ON(unlike RECORD/STOP RECORDING or SWITCH ON/OFF of a non-primarystream, the route status of a secondary stream is not memorized in the Streamstable). ROUTE also will return an error when data is sent to a non-active Sub-CLP.

3. Routing may be implicitly stopped by OASIS-CC. Consider these events:

SWITCH ON return_aSWITCH ON forward_aROUTE part_of_return_a TO forward_aSWITCH OFF forward_aSWITCH ON forward_a

The SWITCH OFF forward_a causes an implicit STOP ROUTINGpart_of_return_a TO forward_a. No routing occurs when forward_a is switchedon again.


10-54


RUNRUN activates a user-supplied utility program. The program name is used as a key into theUtility_Tasks database table, which provides the filename for the program.

Format

RUN program-name [parameter-list]

Arguments

program-name (identifier): The utility program to start. The name must appear in theUtility_Tasks database table. See Chapter 12 of the OASIS-CC System Manager'sGuide for more information on utility tasks. All values of local and global variablesare converted to string data.

parameter-list: Optional values to pass to the utility program. The list can containcharacter strings, local variables and/or global variables separated by commas

Notes

1. The utility program runs with the same attributes and scheduling class as OASIS-CC.

2. If a parameter is character string, the string is passed to the utility program. Singlequotes within a string (') are replaced with double quotes (").

3. If a parameter is either and EU or a REAL (see Chapter 2), the ASCII image of thefloat value is passed to the utility program. The units associated with EUs aredropped.

4. If a parameter is either DN or INTEGER, the ASCII image of the integer value ispassed to the utility program. The "DN" specifier associated with DN types isdropped.

5. If a parameter is a STATE, the ASCII image of the state is passed to the utilityprogram.

6. If a parameter is a delta time, the ASCII image of the float value in seconds ispassed to the utility program.


10-55


7. If a parameter is a clock time, the ASCII image of the time is passed to the utilityprogram.

8. The effective maximum number of parameters is 23. The effective maximum isdefined as the number of spaces contained in the translated parameter list, plus one.For example, if the parameter list is:

"This 'Is a' new TEST",$realwhere $real is 15.0, the effective parameter list passed to the program is:

This "IS a" new TEST 1.5000000000e+1which has 6 effective parameters. The maximum length of an effective parameterlist is 256 characters (including the name of program to be started), and anindividual string parameter cannot exceed 128 characters.


10-56


SAMPLESAMPLE initiates sampling on an IEEE-488 bus.

Format

SAMPLE device-name-list [EVERY sample-rate]

Arguments

device-name-list (identifier): The devices to sample, separated by commas.

sample-rate (delta-time constant): The rate of sampling.

Notes

1. Different IEEE buses may contain the devices.

2. If the sample rate is not supplied, devices are sampled once.


10-57


SENDSEND sends a command message, a command expressed as a bit pattern, or a commandexpressed as a string of ASCII characters.

Format

SEND MESSAGE

SEND bit-pattern-command TO external-element-name

SEND quoted-character-string TO external-element-name

SEND local-variable-name TO external-element-name

SEND global-variable-name TO external-element-name

Arguments

bit-pattern-command (H#hex-integer-constant): The hexadecimal representation of thecommand.

quoted-character-string (string): The string data must be enclosed within double quotes

local-variable-name : The name of a local variable containing a character string

global-variable-name: The name of a global variable (i.e. an External_Element andItem_Name in the Latest_Data table) containing a character string/

external-element-name (identifier): The external element receiving the command.

Notes

1. Single quotes within the string data are translated into double quotes prior to issuingthe ASCII command.

2. The local and global variables named must contain string data.

3. Strings sent by the SEND string TO external-element-name can be fixed or variablelength. See Chapter 5 of the OASIS-CC System Manager's Guide.


10-58


SHOWSHOW displays certain CLP and command information.

Format

SHOW attribute item

Arguments

attribute (identifier): Qualifies the information type to show.

item (identifier): Identifies the information type to show.

At present, SHOW may be followed by any of these pairs of attribute-item combinations.

ACTIVE PROCEDURESCOMPILED PROCEDURESDEFINED MACROSPENDING CEV

Notes

1. PENDING CEV refers to the queue of commands that are pending CommandExecution Verification. Chapter 5 of the OASIS-CC System Manager's Guidedescribes Command Execution Verification.


10-59


SNAPSNAP saves the current contents of the named display page.

Format

SNAP page-name

SNAP page-name RESOURCE

Arguments

page-name (identifier): The display page to snap.

Notes

1. SNAP page-name creates a printable approximate image of the page. This form ofthe directive does not require that the page be displayed in order to be snapped. Itcreates a file named fyy_mon_dd_hh_mm_ss.page-name in the $OASIS_SNAPdirectory.

2. SNAP page-name RESOURCE saves a graphical image of the page in TAE+resource file format. The Action Workbench (awb) can then be used to display thesnapped file offline. This form of SNAP only works when the page is alreadydisplayed. It creates a file named fyy_mon_dd_hh_mm_ss.page-name.res in the$OASIS_SNAP directory.

3. SNAP page-name RESOURCE corrensponds to the directive SNAP page-name inreleases prior to v020512.


10-60


STARTSTART initiates procedure execution and optionally passes the actual value for parametersto it. If the procedure has been compiled, procedure execution begins immediately. If not,the procedure is compiled before execution.

Format

START proc-name [argument-list]

Arguments

proc-name (identifier): The procedure to start.

argument-list : The values passed to the procedure. Multiple arguments are separated bycommas. If a procedure expects arguments, the correct number must be passed andin the same order as the formal parameters specified in the PROC statement.Procedure arguments may be variables or numeric, state or text string constants.All parameters are input only; they cannot currently be returned from a procedure.

Notes

1. The procedure must have an entry in the Procedures database table and be located inthe directory referenced by the logical name OASIS_PROCS.


10-61


STOP POLLING BUSSTOP POLLING BUS instructs OASIS-CC to terminate the automatic polling of IEEE-488streams initiated with the POLL BUS statement.

Format

STOP POLLING BUS stream-name-list

Arguments

stream-name-list (identifier): The names of the primary streams on which automaticpolling should be stopped. The stream names are separated by commas.


10-62


STOP RECORDINGSTOP RECORDING turns off the logging of event messages, incoming data streams,outgoing command streams, or bridge streams.

Format

STOP RECORDING record-mode

STOP RECORDING ALL

Arguments

record-mode (identifier): The type of data logging is stopped for. If the record-mode isMESSAGES, logging of event messages is terminated. Other record-modes areinterpreted as incoming data, an outgoing command, or bridge streams.

Notes

1. STOP RECORDING ALL terminates recording of all messages and streams. ALLshould not be used as a stream name.

2. For compatibility with previous OASIS-CC versions, the formats RECORD OFFrecord-mode and RECORD OFF ALL are syntactically acceptable.


10-63


STOP RETRIEVINGSTOP RETRIEVING terminates data retrieval from disk.

Format

STOP RETRIEVING data-stream

STOP RETRIEVING ALL

Arguments

data-stream (identifier): The data stream retrieval is terminated for.

Notes

1. STOP RETRIEVING ALL terminates all streams being retrieved. ALL should notbe used as a stream name.

2. For compatibility with earlier OASIS-CC versions, RETRIEVE OFF data-stream,and RETRIEVE OFF ALL are syntactically correct.


10-64


STOP ROUTINGSTOP ROUTING terminates routing of a return stream to a forward stream or a Sub-CLP.

Format

STOP ROUTING secondary-stream TO forward-stream

STOP ROUTING secondary-stream TO Sub-CLP ID

Arguments

secondary-stream (identifier): The secondary data stream from the Streams table.

forward-stream (identifier): The forward data stream.

Sub-CLP ID (identifier): Legal values are clp_1, clp_2...clp_20.

Notes

1. STOP ROUTING secondary-stream terminates all routing of that stream (secondarystreams may be routed to many forward streams).

2. Routing may be implicitly stopped by OASIS-CC. Consider these events:

SWITCH ON return_aSWITCH ON forward_aROUTE part_of_return_a TO forward_aSWITCH OFF forward_aSWITCH ON forward_a

The SWITCH OFF forward_a causes an implicit STOP ROUTINGpart_of_return_a TO forward_a. No routing occurs when forward_a is switchedon again.


10-65


STOP SAMPLINGSTOP SAMPLING stops sampling of a device or stream associated with the IEEE bus.

Format

STOP SAMPLING device-name-list

STOP SAMPLING ON stream-name-list

Arguments

device-name-list (identifier): The devices sampling is stopped for, separated bycommas.

stream-name-list (identifier): The streams sampling is stopped for, separated bycommas.

Notes

1. Devices do not have to appear on the same bus, streams do.


10-66


SWITCHSWITCH activates and deactivates data streams. Streams may be assigned to a specificdata line to override the default.

Format

SWITCH ON data-stream [data-line]

SWITCH OFF data-stream

SWITCH OFF ALL

Arguments

data-stream (identifier): The data stream to activate or deactivate.

data-line (identifier): The logical name of the communications device.

Notes

1. If the stream's record in the Streams table has a secondary offset that is not 0,OASIS-CC will build the decomposition tree for this stream when it is switched on.This may take several minutes for complex data streams. If the secondary offset forthe primary stream is 0, OASIS-CC will look for a pre-saved copy of the stream'sdecomposition tree instead – a much faster operation. See Chapter 6 of the OASIS-CC System Manager's Guide for details on how to generate disk copies ofdecomposition trees.

2. SWITCH OFF ALL terminates all active data streams. Do not use ALL as a streamname.


10-67


SWITCH RECORDINGSWITCH RECORDING enables the reopening of event message log files, incoming datastreams record files, outgoing command stream record files and bridge stream record files,without loss of any data.

Format

SWITCH RECORDING OF data-stream-name

SWITCH RECORDING MESSAGES

SWITCH RECORDING OF ALL

Arguments

data-stream-name (identifier): The stream name the statement is applied to.

Notes

1. SWITCH RECORDING OF data-stream-name forces the closing and reopeningwithout data loss of the record file of the indicated stream.

2. SWITCH RECORDING MESSAGES forces the closing and reopening withoutmessage loss of the event message log file.

3. SWITCH RECORDING OF ALL forces the closing and reopening withoutmessage or data loss of all opened record files.

4. An error will result if SWITCH RECORDING is specified for a file that is notcurrently open.


10-68


UNDEFINEUNDEFINE undefines CSTOL macros.

Format

UNDEFINE macro-list

UNDEFINE ALL MACROS

Arguments

macro-list (identifier): A list containing the macros to undefine.


10-69


UNLOCKUNLOCK releases the lock on a database table, making the table accessible to all users.

Format

UNLOCK table-name

Arguments

table-name (identifier): The database table to unlock.


10-70


UPDATEUPDATE modifies fields for all database table records where the selection clause holds.

Format

UPDATE table-name value-list WHERE selection-expression

Arguments

table-name (identifier): The database table containing the records to modify.

value-list (): A list of items of the format field-name = value where field-name is the afield in the record and value is a constant placed in the field for each record meetingthe selection criteria. Multiple items are separated by commas.

selection-expression (): A relational expression with subexpressions of the format field-name = value where field-name is a field and value is a constant value the field iscompared against. Multiple subexpressions are connected by the logical connectiveAND . Records where every named field has the specified value are candidates forupdating.

Notes

1. Users may only update fields where they have access privilege. Key fields cannotbe updated.



10-71


WAITWAIT suspends a procedure. These suspension types may occur with WAIT:

• Indefinite suspends the procedure until a GO statement is entered from thekeyboard.

• Temporary suspends the procedure for a specified length or clock time.

• Conditional suspends the procedure until certain conditions are met.

• Conditional/timed suspends the procedure until certain conditions are met or until aspecified delta or clock time has expired.

Format

WAIT

WAIT delta-time

WAIT clock-time

WAIT conditional-expression [OR FOR delta time| OR UNTIL clock time]

Arguments

delta-time (delta time expression): The length of time to wait before terminating the wait

clock time (delta time expression): The clock time to wait for before terminating the wait

conditional-expression (conditional expression): An expression that determines thecondition to terminate a conditional wait.

Notes

1. If no expression is given, the procedure is placed in an indefinite wait. To resumeexecution, issue GO from the keyboard.

2. To avoid deadlocks, an indefinite wait statement in a procedure executing within anautomatic CLP causes the procedure to terminate as if RETURN ALL isencountered.


10-72


3. If an conditional expression appears in WAIT, the expression must produce alogical result (TRUE or FALSE) Other results cause an error.

4. If the time in a wait is a clock time, procedure execution is suspended until thattime. When the time is reached, the procedure automatically resumes execution.

5 If the specified clock time is in the past, no wait occurs.

6 If the result of a conditional wait is TRUE, no wait occurs. If the expression has alogical FALSE value, the procedure enters a wait state until it re-evaluates TRUE,or until an optional delta or clock time expired. The rate of re-evaluation isgoverned by the delta time stored in $$CHECK_INTERVAL.

7. A conditional wait returns the state value NO_ERROR in the $$ERROR variablewhen the condition is TRUE. $$ERROR returns TIME_OUT if either the optionaldelta or clock time expires, depending on which was supplied.

8. If a user starts a procedure from the keyboard while another procedure sits inconditional or timed wait, the preempted procedure enters an unconditional waitstate.

9. Care must be taken not to 'stack' waits from the keyboard. For example, if aprocedure has entered a wait condition, and the user enters WAIT 00:00:05 fromthe keyboard, the procedure will resume execution in 5 seconds, regardless of thetype of wait that originally halted the procedure.


10-73


WAIT ATWAIT AT sets a breakpoint at a specified label or line number. When the breakpoint isreached, the procedure enters an unconditional wait. The break may occur each time or thefirst time the label or line is encountered.

Format

WAIT AT label / line [ALWAYS]

Arguments

label (identifier): The label where execution is suspended.

line (positive integer constant): The line number where execution is suspended.

Notes

1. A line number may only be specified in a WAIT AT issued from the terminal.

2. WAIT AT is canceled once used unless the ALWAYS option is to keep thebreakpoint in effect. All breakpoints are canceled when the procedure terminates.


10-74


WAIT FORWAIT FOR is designed to use in conjunction with Command Execution Verification(CEV). See Chapter 5 of the OASIS-CC System Managers Guide for CEV details.

Format

WAIT FOR command-group-name

WAIT FOR ALL

WAIT FOR LAST

Arguments

command-group-name (identifier): The name of the command group the wait applies to.

Notes

1. WAIT FOR command-group-name temporarily blocks a procedure while there arecommands pending CEV for the command-group-name.

2. WAIT FOR command-group-name issues an error and indefinitely blocks aprocedure if, once the pending CEV queue is empty of command-group-namecommands, the number of command-group-name commands that have failed CEVis greater than 0.

3. WAIT FOR command-group-name resets the count of failed command-group-namecommands to zero once the CEV queue is emptied of command-group-namecommands.

4. WAIT FOR ALL acts identically to WAIT FOR command-group-name, except thatall commands in the pending CEV queue are considered, not just commandsbelonging to a single group.

5. WAIT FOR LAST acts identically to WAIT FOR command-group-name, exceptthat the LAST command transmitted in the pending CEV queue is considered. TheLAST command is defined as the last one sent on the CLP from which the WAITFOR LAST was issued.

6. Command-group-names cannot be named ALL or LAST.


10-75


7. WAIT FOR generates messages showing the status of the pending CEV queue afterthe WAIT FOR is complete. The messages are similar to those generated by thestatement SHOW PENDING CEV.


10-76


WRITEWRITE inserts a message into the event message log. The message can combine text withvariable values. See the description for CHECK, a statement similar to WRITE.

Format

WRITE write-list

Arguments

write-list (expression): A list of expressions determining the output. Multipleexpressions are separated by commas.

Notes

1. Each item in a write list may be a valid CSTOL expression. The expression isevaluated and the result output. However, most items fall into two categories:

• Specifying a string constant like "Starting power-up process" results in theoutput of that text;

• Specifying a global, local or special variable results in the output of that value.

2. Users can direct WRITE output to customized message windows by supplyingcustom message ID codes. If the first character of a string supplied in a WRITE isan asterisk ("@"), the next 32 characters (or up to the first space character) areinterpreted as message identification codes. The event message is duplicated foreach of the message ID codes, in addition to the regular LIxx code. Chapter 8 ofthe OASIS-CC System Managers Guide describes message ID codes and how tocreate custom message windows.

• Validity checks on the user-supplied ID codes are not performed. Users cansupply any characters, however the event message processor understandsalphabetical characters only;

• ID codes are 2 characters wide, except for the '..xx' codes starting with L,CM, or CD, which are 4 characters wide.

For example, WRITE "ABCD This is a test" will result in 3 instances of themessage "This is a test". One instance carries the custom message ID AB. The


10-77


second carries the ID CD. The third carries the inherent LIxx code OASIS-CCautomatically associates with all WRITE output.

Text output by WRITE is limited to one line in the message log. The text from each itemis appended to existing text from the statement.

3. The current version of CSTOL has no output format control.

4. Color and attribute control information may appear within a message. For examplethe text string.'<R>This is a critical message" results in the display of screen outputin red (on color terminals). The red remains in effect for that line unless anothercolor code is supplied. Similarly, <Y> and <G> specify yellow and greenmessages.


10-78



OASIS-CC CSTOL Reference Manual Appendix A. Control Language ProcessorsRev 0 – 11/94

A-1


Appendix A. Control LanguageProcessors

The control language processor (CLP) allows the user to communicate with the OASIS-CCsystem. Using the CLP, the user issues commands, requests displays, and runsprocedures.

OASIS-CC contains different types of CLPs. Automatic CLPs are used by subsystemswith needs similar to the user. For example, the Command Subsystem may run aprocedure to check for appropriate system configuration before and to verify that thedesired effect has occurred after a command is sent. To facilitate this interaction, CLPs areavailable to subsystems needing them. In particular, one CLP has been provided forCommand, two for Data Handling.

Sub-CLPs assist with closed loop control performance. Sub-CLPs execute procedures in abackground mode without interfering with user CLP activities.

This appendix describes the automatic and Sub-CLPs within OASIS-CC. Implementationof automatic CLPs is described further in the OASIS-CC System Manager's Guide.

Automatic CLPs

The equation, trigger, and command CLPs are automatic CLPs.

Equation CLP:

The Data Handling subsystem manipulates data arriving in a telemetry stream and derivesother data values by sending LET statements or procedures with LET statements to theEquation CLP. For example, if a telemetry stream provides measurements of batteryvoltage from three sensors, Data Handling may send a LET statement to the Equation CLPto derive the average voltage.

Appendix A. Control Language Processors OASIS-CC CSTOL Reference ManualRev 0 – 11/94

A-2


Trigger CLP:

If Data Handling detects an out of limits analog measurement or a discrete measurement notin the correct state, it may send statements or procedures to the Trigger CLP to initiate anautomatic response to the specific condition. These responses include notifying the user ofthe problem, performing diagnostics, and taking corrective action.

Command CLP:

Command uses this CLP to execute CSTOL statements and procedures ensuring that allcommand prerequisites are met prior to transmission and to determine proper execution.

Automatic and User CLP Differences

Automatic CLPs execute most CSTOL statements. Because automatic CLPs perform theirduties without human oversight or intervention, however, CSTOL statements requiringuser interaction are not allowed within these CLPs. User and automatic CLPs have thesedifferences:

1. Automatic CLPs are autonomous, each with its own set of compiled procedures andmacros. All automatic CLP input comes from its subsystem, allowing users noexplicit control over it. For example, compilation or recompilation of a procedurefrom a user CLP does not make the code available to an automatic CLP. For aprocedure to be recompiled, the user must terminate and restart the OASIS-CCsession or force recompilation via input through the automatic CLP subsystem.

2. Procedure lines within an automatic CLP are not displayed to the CSTOL procedureline window. WRITE statements within procedures running in automatic CLPsmay alert the user to when the procedures runs and what it does. However,WRITE the execution speed of automatic procedures.

3. Error messages are not reported via the CSTOL error message window. Errorsduring automatic CLP processing appear in the message log and event messagewindows on the screen.

OASIS-CC CSTOL Reference Manual Appendix A. Control Language ProcessorsRev 0 – 11/94

A-3


4. Procedures in automatic CLPs may not enter an indefinite wait state. Theseprocedures are terminated if the procedure encounters:

• An unconditional WAIT statement;

• An ASK statement;

• Any run-time error.

Sub-CLPs

Sub-CLPs execute procedures, providing a closed loop control capability within OASIS-CC while freeing user CLPs to initiate activities more executive in nature. They havenearly the capabilities as a user CLP, executing any CSTOL directive embodied within aprocedure. Sub-CLPs may execute directives outside a procedure that are associated withits control.

Initiation of Sub-CLPs

The OASIS-CC system manager decides if an application requires Sub-CLPs. Theirnumber must be defined in a Latest_Data table global variable (SUB_CLP NUMBER).When started, OASIS-CC reads this variable and creates the appropriate number of Sub-CLPs. If SUB_CLP NUMBER does not exist at startup, or its value is zero or less, noSub-CLPs are available during that session. Additional global variables must be defined toallow the user to monitor the execution status of each Sub-CLP. See Appendix C of theOASIS-CC System Managers Guide for further information on Latest_Data entries.

CSTOL statements received from external sources can be routed to Sub-CLPs. TheUser_Privileges table is used to define whether a given Sub-CLP has authority to executecommands, run procedures or access External Communications. This table is read once atstartup, therefore any modifications to it during run time are ignored. See Chapter 6 of theOASIS-CC System Managers Guide for more details on ROUTING data to Sub-CLPs.

User Control of the Sub-CLPs

To start proc_xyz on sub-CLP number 3, the operator enters:

3 START PROC_XYZ

This causes START PROC_XYZ to be passed to sub-CLP 3, which then compiles andexecutes the procedure. Sub-CLPs are designed to be restricted to running and controllingCSTOL procedures. Procedures that run on sub-CLPs can use any of the CSTOLdirectives available, however the list of directives that can be passsed to a sub-CLP from

Appendix A. Control Language Processors OASIS-CC CSTOL Reference ManualRev 0 – 11/94

A-4


the user-CLP (by prefacing the user-CLP directive with a sub-CLP number) is limited tothe following set:

GO, GO TO, WAIT, RETURN, SHOW, DEFINE, UNDEFINE, COMPILE,DECOMPILE, START and CLEAR.

Chapter 10 provides complete descriptions of the directives listed above. In general, user-CLP initiation of the allowable directives on any Sub-CLP takes this form:

Format

Sub-CLP-number Directive

Arguments

Sub-CLP-number (identifier): An integer value or a local variable declared as an integerwith a value from 1 to 20.

Directive (identifier): The legal values are GO, GO TO, WAIT, RETURN, SHOW,DEFINE, UNDEFINE, COMPILE, DECOMPILE, START, and CLEAR. Chapter10 provides their formats.

Notes

1. Statements routed to a sub-CLP from the External Communications subsystem canbe any CSTOL directive – they are not limited to the list above.

OASIS-CC CSTOL Reference Manual Appendix B. Operator-Operand CompatibilityRev 0 – 11/94

B-1


Appendix B. Operator-OperandCompatibility

The following tables show the operands allowed with operators appearing in CSTOLexpressions. Rows represent the possible values of operands appearing to the left ofoperators while columns represent the possible values of operands appearing to their right.For each legal combination of operands, the corresponding table cell is filled with the resultdata type. If no entry appears in a table cell, the operation is not allowed.

Assignment (=)Integer Real Clock Delta State Text Dn Eu

Integer Allowed Rounded Allowed

Real Allowed Allowed Allowed

Clock Allowed

Delta Allowed

State Allowed

Text Allowed

Dn Allowed Allowed

Eu Allowed Allowed

Appendix B. Operator-Operand Compatibility OASIS-CC CSTOL Reference ManualRev 0 – 11/94

B-2


Addition (+)Integer Real Clock Delta State Text Dn Eu

Integer Integer Real

Real Real Real

Clock Clock

Delta Clock Delta

State

Text Text

Dn Dn

Eu Eu

Subtraction (-)Integer Real Clock Delta State Text Dn Eu


Real Real Real

Clock Delta Clock

Delta Delta

State

Text

Dn Dn

Eu Eu

Multiplication (*)Integer Real Clock Delta State Text Dn Eu

Integer Integer Real Delta Eu

Real Real Real Eu

Clock

Delta Delta

State

Text

Dn

Eu Eu Eu


B-3


Division (/)Integer Real Clock Delta State Text Dn Eu


Real Real Real

Clock

Delta Delta

State

Text

Dn

Eu Eu Eu

Modulo (mod)Integer Real Clock Delta State Text Dn Eu

Integer Integer

Real

Clock

Delta

State

Text

Dn

Eu

Exponentiation (**)Integer Real Clock Delta State Text Dn Eu

Integer Integer

Real Real

Clock

Delta

State

Text

Dn

Eu


B-4


(and), (not), (or), (xor)Integer Real Clock Delta State Text Dn Eu

Integer Integer

Real

Clock

Delta

State

Text

Dn

Eu

Equals (=), Not Equals (/=)Integer Real Clock Delta State Text Dn Eu

Integer Boolean Boolean

Real Boolean Boolean

Clock Boolean

Delta Boolean

State Boolean

Text Boolean

Dn Boolean

Eu Boolean

Greater than (>), Greater than or Equal (>=)Less than (<), Less than or Equal (<=)

Integer Real Clock Delta State Text Dn Eu

Integer Boolean Boolean

Real Boolean Boolean

Clock Boolean

Delta Boolean

State

Text

Dn Boolean

Eu Boolean


B-5


Negation (-)Integer Real Clock Delta State Text Dn Eu

Integer Integer

Real Real

Clock

Delta Delta

State

Text

Dn Dn

Eu Eu


B-6



OASIS-CC CSTOL Reference Manual Appendix C. Adding Command Verbs to the ParserRev 1 – 11/94

C-1


Appendix C. Adding Command Verbsto the Parser

OASIS-CC application developers can add to or delete from the list of CSTOL commandverbs. The command verbs delivered with OASIS-CC are in Table C.1. Adding anddeleting command verbs should be used with care – changes should be coordinatedbetween members of the same project to make sure that no incompatibilities are created.

Table C.1 OASIS-CC Command Verbs

ACTIVATE ARM BOOT CHANGE

CLOSE DISABLE DISARM DRIVE

DUMP ENABLE FIRE FLYBACK

FORCE OFF FORCE ON GET HALT

IGNORE INITIATE MOVE OPEN

PASS PERFORM RESET SELECT

SET SLEW STEP TEST

TOGGLE TURN OFF TURN ON USE

To update the command sub-language verb list, four steps are necessary:

1) Edit parser.dat file. This file (in the directory pointed to by $OASIS_PARSER)contains the ASCII representation of the parsing rules.

2) Find the comment "THIS PORTION OF PARSER.DAT FILE CAN BEMODIFIED"

; THIS PORTION OF PARSER.DAT FILE CAN BE MODIFIED TO ADD OR REMOVE CMD VERBSSTATETRAN 'NOW' ,CMD_HOLD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'HOLD' ,CMD_NAME_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMAND

Appendix C. Adding Command Verbs to the Parser OASIS-CC CSTOL Reference ManualRev 1 – 11/94

C-2


TRAN 'ENABLE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'CHANGE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'CLOSE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'DISABLE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'HALT' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'MOVE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'OPEN' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'SET' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'TOGGLE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'TURN' ,TURN_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'BOOT' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'SELECT',NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'DUMP' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'IGNORE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'USE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'PASS' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'DRIVE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'FORCE' ,TURN_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'FLYBACK' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN !RESET ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN !STEP ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN !TEST ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN !PERFORM ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN !SLEW ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMAND

; END OF THE PORTION OF PARSER.DAT THAT CAN BE MODIFIED TO ADD OR REMOVE; CMD VERBS

3) Remove the lines that correspond to the verbs you want to remove and/or add thelines that correspond to the verbs you want to add. For example, add arm, disarm,fire, initiate, activate and get to the list of command keywords:

; THIS PORTION OF PARSER.DAT FILE CAN BE MODIFIED TO ADD OR REMOVE CMD VERBSSTATETRAN 'NOW' ,CMD_HOLD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'HOLD' ,CMD_NAME_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'ENABLE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'CHANGE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'CLOSE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'DISABLE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'HALT' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'MOVE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'OPEN' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'SET' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'TOGGLE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'TURN' ,TURN_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'BOOT' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'SELECT',NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'DUMP' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'IGNORE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'USE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'PASS' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'DRIVE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'FORCE' ,TURN_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'FLYBACK' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN !RESET ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN !STEP ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN !TEST ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMAND

OASIS-CC CSTOL Reference Manual Appendix C. Adding Command Verbs to the ParserRev 1 – 11/94

C-3


TRAN !PERFORM ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN !SLEW ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMAND; Additional sub language verbs added 10/93 per crn 330TRAN 'ARM' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'DISARM' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'FIRE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'INITIATE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'ACTIVATE' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMANDTRAN 'GET' ,NORMAL_CMD_STATE,EXTENDED_DIRECTIVE_TOKEN,COMMAND

; END OF THE PORTION OF PARSER.DAT THAT CAN BE MODIFIED TO ADD OR REMOVE; CMD VERBS

4) Convert the ASCII file into a binary file understandable by OASIS-CC by entering$ODIST/bin/convert_table. This creates a file called parser_int.dat in$OASIS_PARSER. This is the file from which OASIS-CC loads the languagerules at run-time.

Appendix C. Adding Command Verbs to the Parser OASIS-CC CSTOL Reference ManualRev 1 – 11/94

C-4



Date post:	29-Mar-2015
Category:	Documents
Upload:	kenneth-shelton
View:	29 times
Download:	1 times

cstol

Documents