High Level Command Language (HLCL) Reference Manual

Transcription

1 High Level Command Language (HLCL) Reference Manual

2 Seite/Page: I von/of II DOCUMENT CHANGE RECORD ISSUE/REV. DATE Affected Paragraph/Page DESCRIPTION OF CHANGE 0 / all initial issue 1 / all Rids and comments from HLCL review ( ) incorporated 1 / A all COL ERNO DDR 0174 & HCI HCI HCI HCI all HCI all HCI HCI HCI HCI HCI picture updated HCI HCI HCI HCI HCI HCI HCI HCI HCI HCI HLCL HLCL HLCL HLCL all M. Danne Inputs from VICOS team all S. Lütt Inputs from the CSS team all COL MBER ZU1 TN / all COL RIBRE DDR 0563 changes required by COL RIBRE DDR 0587 which has not been formally approved but the contents are agreed. 2/A Ref. to applicable document updated , page 6 Delete Parameter lists must be enclosed in parentheses. 4.17, page 13 Change LIBRARIES to IMPORTS in type OB- JECTS.

3 Seite/Page: II von/of II

4 Seite/Page: 1 1 INTRODUCTION 1.1 Identification and Scope This is the Language Reference Manual for the Columbus High Level Command Language (HLCL), Document No.: COL RIBRE STD 0009 (previous Doc. No.: STD ). 1.2 Purpose This document provides the language definition for HLCL. It serves the purpose of establishing the formal requirements on the language, i.e. its syntax and semantics. It is particularly intended for the design and development of the HLCL interpreter. Chapter 3 gives an overview on the Columbus Language Concepts: UCL and HLCL and their relationship, as well as the basic conceptual ideas that led to the definition of HLCL. In chapter 4 the definition of the High Level Command Language is given.

5 Seite/Page: 2 2 APPLICABLE AND REFERENCE DOCUMENTS 2.1 Applicable Documents The following documents form a part of this specificaiton to the extent specified here. In case of conflict this specification shall be superseding. The exact actual status of the documents listed below is to be obtained from the contractual baseline status list User Control Language Reference Manual COL RIBRE STD 0010, Issue 4/, Reference Documents None identified.

6 Seite/Page: 3 3 LANGUAGE CONCEPTS 3.1 HLCL and UCL The High Level Command Language (HLCL) is the interactive counterpart of the User Control Language (UCL). UCL acts as a pure programming language: automated procedures and libraries are edited off line, compiled and kept in the database for later on line execution. HLCL is an interactive command language used in different environments in the Columbus Ground System: within interactive sessions, users type commands which are executed immediately by the HLCL command interpreter. UCL and HLCL are, in principle, lexically, syntactically and functionally identical. They are essentially the same language. There are, however, specific features, extensions and restrictions for both language domains. This document defines the HLCL specific differences between UCL and HLCL. It does not describe the basic language itself as given by the UCL Language Reference Manual. The UCL RM is considered part of this document. 3.2 General principles It should be noted as an obvious fact that the design principles for an interactive command language like HLCL are naturally different from those of a programming language like UCL: While programs in a programming language are typically written only once, but read a lot of times (even by different people), commands are typically typed repeatedly and never read again. So while, for a programming language, readability is a major requirement, and features that ease writing play a minor role (e.g. optional parameters) or should even be entirely forbidden (e.g. abbreviations), the contrary holds for command languages. Here easy input is a major topic. While the program logic of e.g. a UCL program must be completely defined before actual execution and allows no interactive modifications at run time, command language sessions have totally contrary characteristics: the session logic is interactively developed (possibly on an experimental or trial and error basis) during the session. Therefore flexibility and interactive assistance are major requirements. While in the case of UCL programs full checks on availability and compatibility of accessed resources must be performed at mission preparation time, these checks are naturally on line constituents of an HLCL session and role themselves as decision factors for the further session development. While run time efficiency is an important aspect for UCL programs, it is of less importance for HLCL sessions. These principles have driven the definition of the HLCL specifics as described in this manual.

7 Seite/Page: Usage HLCL may be used in a command window, i.e. where a user interactively types commands, or in any other environment where commands are generated by software, e.g. in the synoptic displays environment used for verification, integration, and checkout. When used in a command window, it is assumed that the command window software will provide for the usual support services like command history, command line editing, and command interrupt. This manual, however, defines only the language itself, not its use in any specific environment.

8 Seite/Page: 5 4 LANGUAGE DEFINITION 4.1 Sessions A session is the basic commanding and execution environment for interactive operation. It is, in a certain sense, the interactive counterpart of a UCL automated procedure (AP). Within a session the user types more or less the same commands in the same form that may appear in an AP in UCL. There are, however, some essential differences: There is no syntactic frame that encloses a session, like e.g. a session header, or the begin and end keywords. When logged in, the user is free to start typing commands. There is no required order or grouping of commands, e.g. declarations, import statements and any other commands may be mixed arbitrarily. Declared objects may even be deleted. The underlying application software may make its own specific language additions available, such as login and logout command sequences and application specific types, commands and functions. All additions will, however, conform to the basic language definition Debug mode The user may switch between normal mode and debug mode by setting the predefined variable DEBUG to false or true, respectively. In normal mode commands are executed immediately. In debug mode each command is first displayed in expanded and evaluated form, i.e. abbreviations are removed, expressions are evaluated, defaults are inserted and all parameters are given in named notation. The user is then asked for explicit confirmation before executing the command Command logging Interactively typed commands may be collected in a log file to automatically build a command sequence which may then be executed again. For this purpose the user can open and close command log files with the OPEN and CLOSE commands. Whenever a new file is opened, a new command sequence is built. The OPEN command allows for different logging options. Command logging mode can be controlled with the predefined variable KEEP. When keep is set to true (and a log file is open), all interactively entered commands are logged in the currently open log file, when set to false, commands are not logged. This may be used for selective command logging. Note that this command logging mode provided by the HLCL Interpreter itself is independent of any logging functionality that may be provided by the applications using the HLCL Interpreter.

9 Seite/Page: Command Sequences A command sequence is a series of single commands put in a file or in the database. They may be used to set up a certain working environment (define variables, constants, alias names etc.). Command sequences may have parameters, they are restricted to predefined types and open arrays of predefined types, but may be of any mode. A command sequence can be executed at any time like a single command by using its file name or path name as the command name, and specifying its parameters in the usual form, as for any other command. A command sequence acts as a non interactive session. It may contain any commands, in particular it may contain calls to other command sequences. The execution of command sequences thus forms an execution hierarchy whose upper level is the session. When a command sequence is started, execution at the current level is blocked until the called sequence has completed its execution. Execution is then resumed at the point of call. This implies that during execution of a command sequence no commands can be given from the keyboard. The execution can, however, be interrupted by pressing an interrupt key combination: the currently executed command is then cancelled, and control immediately returns to the session. The sequence is suspended but remains loaded and can be resumed at any time with the RESUME command Command sequence syntax The command sequence syntax resembles that of a procedure with the following differences: The keyword procedure is replaced by the keyword sequence. The name given after the keyword is implicitly declared as an alias for the pathname (for sequences kept in the database) or for the file name (for sequences kept in files). The begin keyword is omitted. A command sequence does not have a local scope: all declarations create global objects at the session level. But the sequence parameters, as well as the alias derived from the sequence name, are visible and accessible only within the command sequence. Within a command sequence, a grouping of commands is not required, i.e. import statements, declarations and other commands may be mixed arbitrarily. Within a command sequence the same rules apply as in a session, but some session specific relaxations and extensions are not valid: Abbreviations are not allowed. The end of a line is not a command terminator, i.e. commands must be terminated with a semicolon and may be formatted over several lines if desired. Only optional parameters may be omitted. Engineering units must not be omitted. (deleted) Echo mode When the predefined variable ECHO is set to true, commands executed from a command sequence are echoed on the screen. When ECHO is not set, only start and completion of command sequences are reported.

10 Seite/Page: Error handling in command sequences When an error occurs in a command sequence, the effect depends on the predefined TRAP variable. If error trapping is on, an error within a command in a command sequence interrupts the command sequence, as if the interrupt key combination had been pressed. Execution can then be resumed with the RESUME command Single step mode Command sequences may be executed in single step mode. This is controlled via the predefined variable STEP. When this variable is set to true, each command from a command sequence must be confirmed before execution. When it is set to false, commands are executed automatically without confirmation. 4.3 Command lines In UCL a statement is terminated with a semicolon, and the line structure is irrelevant. In HLCL the semicolon is a command terminator, as well. But the end of an input line acts as an additional command terminator. This means that practically the semicolon may be omitted when single commands are entered, each on a separate line. It must not be omitted, however, between two commands on the same line. single command on a line, no semicolon needed two commands on a line, separated by semico- Examples: PUT X X := Y + Z; PUT X lon

11 Seite/Page: Command and function classes HLCL provides most of the basic language material of UCL, as well as HLCL specific extensions. In HLCL, statements and other syntactic entities are usually referred to as commands. The basic UCL statements constitute the primary command set of HLCL. An essential characteristic of HLCL is that it does not restrict itself to a predefined set of commands, but that it is able to incorporate ( inherit ) all executable objects in the Columbus database and make them transparently available as commands or functions, respectively. The following command and function classes can be distinguished: Import statements As defined in the UCL Reference Manual. Declarations As defined in the UCL Reference Manual, but HLCL does not support the declaration of procedures and functions. Assignments As defined in the UCL Reference Manual. Standard UCL procedures and functions ( intrinsics ) As defined in the UCL Reference Manual. Simple commands and functions These are predefined commands and functions. A basic set of primary commands and functions is described in this paper, but within a given application environment (EGSE, simulator, on board) the relevant application may add application specific commands and functions. Thus the primary command set is made up of basic commands and functions predefined in HLCL application specific commands and functions added by an application. Inherited commands and functions All executable objects in the Columbus database are accessible as quasi HLCL commands or functions. They are activated in the same syntax as primary commands and functions. Inherited commands and functions comprise automated procedures (APs, are commands) UCL library routines (are commands and functions, respectively). Command sequences Command sequences kept in the database or in files may be called like single commands (see 4.2). A help facility.

12 Seite/Page: Import The import statement is identical to that in UCL. 4.6 Declarations and deletions The UCL declarations are fully available in HLCL. HLCL extends the alias declaration: an alias may also be assigned to a string constant. When used, the string alias must designate the name of a file that contains a command sequence. The intended effect is to be able to call a command sequence contained in a file by a simple name. Example: alias SHUTDOWN = /usr/columbus/users20/vicos/shutdown.hlcl 4.7 Assignment Assignments are identical to UCL assignments. 4.8 Standard procedures & functions All the procedures and functions defined in the UCL Reference Manual may be called from HLCL, procedures becoming commands. HLCL predefines additional standard procedures. HLCL allows to delete (undeclare) a user declared object (constant, variable, type,...) with the standard procedure DELETE. Predefined objects and objects imported from libraries cannot be deleted. DELETE DELETE [km] HLCL predefines an additional standard procedure TRIGGER to trigger objects of type PULSE and BURST_PULSE. It has two forms: TRIGGER TRIGGER PULSE BURST_PULSE BURST_PULSE

13 Seite/Page: Simple commands A simple command is essentially identical to a UCL procedure call, i.e. it is invoked with its name, followed by its parameter list, if any. HLCL relaxes the UCL syntax rules to support easy typing: Parameter lists are given without the enclosing parentheses. All parameters (except open array and open string out parameters) may be omitted, an appropriate default action is then taken: For optional parameters the defined default value is taken. Mandatory in and in out parameters are prompted for. For pure out parameters the returned value is displayed. A few simple commands are predefined. This basic command set may be extended by various applications with application specific command sets Return command The return command (without a value) is only allowed in command sequences. It terminates execution of the command sequence and returns control to the caller Structured commands The HLCL structured commands identically correspond to the UCL control structures (if, case, loop, while, for, repeat). They are only allowed in command sequences Expressions Expressions are identical to UCL expressions Path names HLCL extends the path name syntax. Path names may start with \\ instead of just \. Such path names are implicitly understood to be a subpath of the default path defined in the varible DEFAULT_PATH, i.e. they are implicitly prefixed with the current value of DEFAULT_PATH Type conversions HLCL defines new type conversions (see 4.17): PULSE > BOOLEAN BURST_PULSE > UNSIGNED_INTEGER. HLCL allows type conversions from any type to string types. In the case of named string types this follows the usual conversion syntax. A general conversion to string may also be written as string (expression)

14 Seite/Page: Type overloading HLCL relaxes the rule that a parameter is bound to exactly one type: parameters of primary commands (basic as well as application specific) may be of more than one type. Such parameters are said to be (type) overloaded. An overloaded parameter accepts values of any of its types. If it is an open array parameter, the list of values may contain a mixture of values of any of the allowed types Units of measure The HLCL unit of measure concept is identical to the corresponding UCL concept. The strict conformance rules of UCL are, however, relaxed: A unitized variable may be assigned a unitless value. The value is then implicitly unitized with the same unit as the variable. A unitless variable may be assigned a unitized value. The unit is then ignored. A unitless in parameter may be passed a unitized value. The unit is then ignored. A unitized in parameter may be passed a unitless value. The value is then implicitly unitized with the same unit as the parameter. A unitized (in) out parameter may be passed a unitless variable. Within the procedure or function, the value of the variable is then assumed to be of the same unit as the parameter. A unitless (in) out parameter may be passed a unitized variable. The unit of the variable is then ignored within the procedure or function Abbreviations All identifiers may be abbreviated arbitrarily, as long as they remain unique, simply by cutting off word tails. In compound identifiers (i.e. names composed of name parts separated by underscores) the name parts can be abbreviated separately like simple identifiers, as long as the whole name remains unique. Examples: Identifier VOLTAGE ASSIGN_PICTURE SEND_TM_MESSAGE Possible abbreviations VOLTAG, VOLTA, VOLT, VOL ASS_PIC, ASS_P, A_P, ASS SEND_TM, S_TM_MES, S_T_M In general, UCL reserved words (keywords) cannot be abbreviated. But, for convenience, if the first word of a command is a keyword, e.g. in declarations (constant, type, variable, alias, unit) or in the import command, then it may be abbreviated. Within a command sequence, abbreviations are not allowed.

15 Seite/Page: Help facility HLCL provides a help facility that allows the user to obtain a short description on an object given by its name, an engineering unit, or on the value of an expression. Syntax: Help ::=? [ Item ] Item ::= Object [... ] [ Constraint ] Expression Unit Object ::= Qualified_Identifier Name Constraint ::= ( Identifier {, Identifier } ) A single question mark displays a list of all (predefined or declared) identifiers. The effect of a question mark applied to a (qualified) identifier depends on the identifier. If it is ambiguous, then it is assumed to be an abbreviation and a one line information is displayed for all objects whose name matches the abbreviation. This line contains the value of the object, if any. If the identifier is unique, a more detailed information for that object is displayed: For a command or function name a short command/function information is displayed, comprising the parameter list, and for each parameter the type(s), parameter mode and default value, if any. A library procedure/function is treated as a simple command/function. For an alias, in addition to the value of the alias an information on the designated object is displayed, depending on the type of object. For all other objects a short identification of the object is displayed, together with its value, if any. A question mark applied to an expression displays the expression with all abbreviations expanded, together with its value. For a unit, its definition in terms of the seven basic SI units is displayed. The effect of a question mark applied to a database path name depends on the type of item: For a virtual item (non end item) a one line information for each of its children is displayed. An AP path name is treated like a simple command. For a library path name a list of the library contents is displayed. A path name may be constrained to a subset of item types by giving a list of possibly abbreviated item types in parentheses. The recursive indicator (... ) requests information to be displayed recursively: For a unique (qualified) identifier an information line is displayed for the identifier itself and for all identifiers referenced in its definition. This process is repeated recursively until all identifiers have been resolved. For a virtual database item not only its children are displayed, but also the children of the (virtual) children, and so on recursively down to end item level. Examples:? Display list of all identifiers? ASS_PIC Display details of command ASSIGN_PICTURE? ASS_PIC... Display details of ASSIGN_PICTURE recursively? MIN (INTEGER) Display value of an expression? (X + y) * Z Display value of an expression? [km/h] Display [km/h] in terms of [m/s]? \APM\GROUND\VICOS... Display database subtree recursively? \APM\GROUND... (UCL,HLCL) Display all UCL and HLCL items in database subtree

16 Seite/Page: Predefined types The HLCL data types are identical to the UCL types. HLCL predefines the following additional types, an application may add its own application specific types. type OBJECTS This is an enumeration type that defines the objects that may be listed with the LIST command. type OBJECTS Objects to be listed (see LIST command): = (CONSTANTS, all constants (including enumeration literals) LITERALS, all enumeration literals (subset of CONSTANTS) VARIABLES, all variables TYPES, all types ALIASES, all alias names PARAMETERS, all parameters of the currently running sequence UNITS, all measurement units COMMANDS, all commands (including intrinsic and other procedures) FUNCTIONS, all functions (including intrinsic functions) INTRINSICS, all standard ( intrinsic ) procedures and functions IMPORTS, all imported UCL libraries SUBTREES, the set of database subtrees authorized for the user ITEM_TYPES, the set of database item types authorized for the user CALL_STACK) the stack of loaded command sequences type PULSE A pulse is a binary event used by a simulator (CSS) function block to trigger the execution of another function block. A function block receiving a triggered parameter of type PULSE is automatically activated within the next time frame. Objects of type PULSE are only defined in the database. They cannot be declared, have no operations and cannot be assigned. They are initially cleared and may be triggered with the standard procedure TRIGGER. Triggering a PULSE object changes its value. The value of a PULSE object may be obtained by converting it to BOOLEAN. The conversion yields true for triggered objects, otherwise false. type BURST_PULSE A burst pulse is a counting event used by a simulator (CSS) function block to trigger the execution of another function block, like a pulse. A function block receiving a triggered parameter of type BURST_PULSE is automatically activated within the next time frame. When triggered, it does not just become set but, rather, increments its value. Objects of type BURST_PULSE are only defined in the database. They cannot be declared, have no operations and cannot be assigned. They are initially cleared (i.e. they have value 0) and may be triggered with the standard procedure TRIGGER to increment thair value. The default increment is 1, greater increments may be requested as a second parameter to TRIGGER. The value of a PULSE object may be obtained by converting it to UNSIGNED_INTEGER. The conversion yields a value > 0 for triggered objects, otherwise 0.

17 Seite/Page: Predefined variables HLCL predefines some variables with a special meaning. These variables have an initial default value that may be changed by the user with an assignment. variable DEFAULT_PATH: pathname := application defined Wherever a path name is prefixed with \\, the prefix is expanded with the current value of the variable DEFAULT_PATH. This variable has an initial value defined by the underlying application. variable DEFAULT_NODE: pathname := application defined The default node used to start APs and call library routines. This variable has an initial value defined by the underlying application. variable ECHO: BOOLEAN := FALSE This variable defines whether commands executed from command sequences are echoed on the screen. If set to false, only start and stop of command sequences are reported. This variable is initially set to false. variable TRAP: BOOLEAN := FALSE This variable determines the error handling mechanism within command sequences. When set to true, an error in a command sequence interrupts execution of the sequence and returns control to the session. The sequence remains loaded and may be resumed with the RESUME command. When set to false, errors in a command sequence do not interrupt execution of the sequence. variable STEP: BOOLEAN := FALSE This variable selects single step execution of command sequences. When set to true, each command from a command sequence must be confirmed before execution. variable DEBUG: BOOLEAN := FALSE This variable selects debug mode. In debug mode all commands are displayed in expanded form (abbrevations resolved, defaults inserted etc.), and confirmation is requested before execution. variable KEEP: BOOLEAN := TRUE This variable controls command logging mode. When set to true (and a log file is open), all interactively typed commands are logged in expanded form in a command log file (see the OPEN and CLOSE commands). When set to false, nothing is logged, even if a log file is open.

18 Seite/Page: Predefined commands A set of primary commands is built in to HLCL on a fixed basis. This basis comprises the different command forms: declarations, assignments, simple commands, structured commands, and the help command. This section lists only the simple commands that are specific to HLCL and therefore not covered by the UCL LRM. Only the basic commands are listed here; for the different target environments, additional environment specific commands may be added. Each primary command is described in this section, giving its name, a short description and its parameter list. For each parameter, its mode, name, type(s) and default value, if any, are given. Parameters with a default value are optional Display commands LIST Display list of objects Display a list of all objects of a certain class. The list may be restricted to a specific scope. Parameters: in CLASS: OBJECTS the class of objects to be displayed. It is given as a value of the predefined enumeration type OBJECTS. in SCOPE: pathname := \\ This parameter allows to restrict the list to objects of a specific library scope determined by the path name of a library: only objects declared in that library are then listed. If no scope is given (\\), all scopes (i.e. the session and all imported libraries) are listed.

19 Seite/Page: Command sequence related commands CHECK Check a command sequence Check a command sequence for syntactical correctness. Note that problems resulting from execution of the command sequence in different session environments and from possibly violated semantical conditions between actual parameters and between commands themselves cannot be checked. Parameter: in SEQUENCE: pathname string Name of the command sequence (path name if in the database, string if in a file). SUSPEND Suspend execution of a command sequence Suspend command sequence execution and return to interactive input. The sequence may later be resumed at the suspension point. This command can only be used within a command sequence. RESUME Resume a suspended command sequence Resume command sequence execution which was suspended by the SUSPEND command, by error or user interrupt. CANCEL Cancel the command sequence call stack Remove the command sequence call stack, i.e all currently loaded (and suspended) command sequences. This command can only be used interactively when no command sequence is active. RESUME is then no longer possible.

20 Seite/Page: Input/output commands These commands are intended for interaction with the user from within a command sequence. GET Read input value from keyboard Read a value from the keyboard, optionally write a prompt before reading. The type of the value is determined by the actual parameter. Invalid input will be reported as an error, and reading will be repeated until a correct value has been read. Parameters: in PROMPT: string := The prompt to be written. out ITEM: any type The item to be read. PUT Display the value of an item Display the value of the parameter as an output line on the screen. The parameter may be an expression of any type. (Several items may be combined into a line by converting them to string and concatenating them with the + operator.) Parameter: in ITEM: any type The item to be displayed.

21 Seite/Page: Command logging commands These commands are used to control command logging. OPEN Open a command log file Open a new command log file and generate a command sequence in it. The syntactical form of the commands in the command sequence to be generated may be specified by several parameters. This command is only allowed when no log file is currently open. Parameters: in FILE: string Name of the log file to be created. in SEQUENCE: string Name of the command sequence to be created in the log file. in EXCLUDE: string := List of commands to be excluded from logging. Command names are separated by comma or blank. Assignment is given as :=, the help facility as?, the different declaration statements as the respective keyword. in NAMED: BOOLEAN := TRUE Specifies whether command parameters are to be generated in named notation. in EVALUATED: BOOLEAN := FALSE Specifies whether parameters are to be evaluated and given as values, or expressions are to be kept. in FORMATTED: BOOLEAN := FALSE Specifies whether commands are to be formatted with each parameter on a separate line, or unformatted with the whole command in one line. CLOSE Close the command log file The currently open command log file is closed, the generated command sequence is syntactically completed first. This command is only allowed when a log file is currently open.

22 Seite/Page: Predefined functions There are no predefined HLCL functions other than the standard functions described in the UCL Reference Manual. For the different target environments (such as ground testing and checkout, simulation) additional environment specific functions may be added to the basic ones Inherited commands and functions The commands and functions described in previous chapters make up the basis of HLCL. A more interesting aspect of HLCL is its capability of dynamically extending its primary command and function set by inheriting new commands and functions from the Columbus databases. Since an HLCL command can be seen as a parameterised procedure (more generally: an executable object with a parameter list), any objects in the Columbus databases that have this same property can theoretically be addressed as HLCL commands, similarly for functions. The objects conforming to these conditions are automated procedures (APs), UCL library procedures and functions and command sequences. The following sections describe how these database objects are mapped onto HLCL commands and functions Automated procedures (APs) Automated procedures are parameterised main programs written in UCL and compiled into an intermediate code (I Code) which is interpreted by I Code interpreters residing in different nodes in the network. The APs have a path name which reflects their position in the database name tree, and a parameter list. An AP can therefore be mapped on an HLCL command, the path name acting as the command name, and the parameter list obeying the HLCL parameter conventions. Activation of an AP can thus be expressed as an inherited quasi HLCL command, e.g. : \PAYLOAD\EQUIPMENT\UNIT_A\COMMAND MODE: 3 APs are executed on different nodes in a network. Several APs may be active concurrently, on different nodes or on the same node. The node name is obtained from the predefined variable DEFAULT_NODE UCL library procedures and functions UCL library procedures and functions are called like in UCL. The target node in the network is obtained from the predefined variable DEFAULT_NODE Command sequences Command sequences stored in the database can be called in the same form as an AP. They are immediately executed in the local workstation. For a description of command sequences see chapter 4.2.