GBT Command Line Proposal

This is a proposal for a command line interface for the GBT real-time control system.

DRAFT
by F.Ghigo, T.Minter, K.ONeil, R.Maddalena
May 10, 2003

Contents

1.0 Introduction.
1.1 Why command-line interface.
1.2 General Features.
1.3 Help facility.
1.4 Remarks on Implementation.
2.0 Users Manual A: Language features and syntax.
3.0 Users Manual B: Dictionary of keywords.
3.0 Users Manual C: Dictionary of commands.

1.0 Introduction

Discussions among astronomers regarding improvements to the ease of use of the GBT led to the recommendation that a command line interface should be developed. This does not preclude GUI interfaces of course, but the suggestion is to build GUI interfaces on top of a command line language. This has multiple advantages, including making the GUI more transparent, allowing observers to implement strategies not yet accounted for in the GUI, and acting as a back-up system for GUI failures.

1.1 Reasons why a command-line interface is important

An astronomer doing a series of experiments can save the command file used in the first session and use it again at a later date to assure that the system is set up just as it was before.
Experiments can be set up and run in batch mode -- switching from one experiment to the next just requires loading the right batch file.
An astronomer can develop his own library of observing setups and procedures.
A command-line interface is readily adapted to remote observing and dynamic scheduling.
Considerable flexibility in setup and observing is allowed: "cutting edge" observations can be set up without requiring software modifications.

One should note that it is important that the command-line system remain stable, or at least backward compatible, for decades: -- If an astronomer returns after an absence of several years, he should expect that his many-year-old batch file will still work.

It should also be noted that the presently existing Cleo save/restore facility does not provide the needed capability because it is too thorough and too close to the hardware. Specifics of M&C managers may change from time to time. If one saves the system state with Cleo and then tries to restore it after a small manager change has happened, the restore may fail. This problem can be avoided by using configuration commands based on general keyword values. The command interpreter uses the high level keywords to command the M&C devices. Any changes in the hardware or the M&C managers must be dealt with by changes in the command interpreter, but the commands and keywords stay the same.

1.2 General Features

The system should provide commands for configuring the many GBT devices. There should be commands for setting parameters in individual devices as well as a general configuration command. Commands for all the standard observing procedures should be provided. The system should include the capabilities presently available in GO Tables.

There should be a capability for easily writing subroutines, or procedures, composed of any pre-exising commands or subroutines. The user should be able to create text files of commands and subroutines which can be loaded and executed. Any text file should be able to include other text files.

A user should be able to easily create new observing procedures in this language (to add to standard ones such as "track", "onoff", etc). Loading a text file with these procedure definitions will add these procedures temporarily to the repertoire. Optionally, the name of the new observing procedure and its parameters will be recorded in the GO FITS file when the procedure is run.

1.3 Help Facility

A help facility should be built into the command language. Although web-based documentation is useful, there should be some information available within the context of the command language where it will be immediately available.

For example, typing "help commandname" should briefly list all the parameters needed by that command. Some meta-help should also be available, such as "help procs" to list all the observing procedures, "help devs" to list the commands that set up devices, and so forth.

1.4 Remarks on Implementation

We do not suggest any specific implementation, but leave this to the software department. The command-line language needs to be an interpreted language, and it can be built out of some existing and well-known language, such as C++ or Python. Commands should be easily writable in the underlying language.

The capability of the existing GO Table system, allowing observing schedules in columnar form, should be retained.

The observer's GUI built on top of the command-line language should be able to save and restore the current configuration to and from a text file consisting of commands of the command-line language. One should be able to load any text file of commands and procedures, and have any new observing procedures appear in the GUI.

2.0 Users Manual A: Language and Syntax.

2.1 Statements and delimiters.

Delimiters will be blanks, commas, or semicolons. Blanks can also be used to space out statements for readability.

For example, the following two statments mean the same:
param1=17
param1 = 17

One may put several statements on the same line:
param1=17 param2 = 'Fred' param3='weevils'
param1=17, param2 = 'Fred', param3='weevils'

New-line, or end-of line is ignored within a statement, so one may write:
param1 =
14.2

Characters that are used as parts of numbers, such as period, decimal point, plus and minus signs, cannot be used as delimiters.

Any value that contains alphabetics is taken to be a string, for example, "param1=A0045" means the same as "param1='A0045'"

Comments begin with a hash mark ( # ). Anything from the hash mark to the end of the line is ignored. These may be imbedded within statements, for example the following will work:
param1 = # comment 1
14.2 # comment 2

2.2 Variables.

Assignment of a value to a variable is done with the equals ( = ) sign. Variables may be assigned a value which is a list or array. For example:
param1=12
param2= [2, 4, 6, 9 ]

There are global variables corresponding to the configuration keywords. For example, the receiver keyword is set as follows:
receiver = 'Rcvr1_2'

Variables associated with specific commands or procedures may be set with the syntax "command.variable=", for example:
lo1.tolerance= 10
proc.rarate = 40

The user can create a new variable simply by mentioning it. For example, the user can create a new variable "A" and assign it a value of "1" by the statment:
A=1

In other words, any assignment to a variable that is not already known to the system creates a new variable of that name.

If a new variable is created outside a function definition, it is global. If it is created within a function definition, it is local to that function.

2.3 Tables.

Observing tables will work just as they do now in the GO Table system. For example, the following:

header \
source             ra           dec             velocity procedure
I00070+6503        00:09:43.67    +65:20:09.3    -36.3    OffOn
I00117+6412        00:14:27.72    +64:28:46.2    -51.2    OffOn
I00420+5530        00:44:57.62    +55:47:18.1    -30.0    OffOn

is equivalent to:

source=I00070+6503  ra=00:09:43.67  dec=+65:20:09.3 velocity= -36.3  OffOn
source=I00117+6412  ra=00:14:27.72  dec=+64:28:46.2 velocity= -51.2  OffOn
source=I00420+5530  ra=00:44:57.62  dec=+55:47:18.1 velocity= -30.0  OffOn

Note here that "OffOn" is a command name which is executed simply by invoking it.

   func newfunction( parameterlist )
   begin
	....
	....
	....
   end

Parameters in the call may be matched with parameters in the function either by order or by name.

2.7 includes

A text file of any valid statements and function definitions may be executed by using the include command:

   include 'textfilename'

TCL aficionados will want to use "source" instead of "include". We can satisfy everyone by making these aliases of each other.

2.8 Executing lower level code

Code written in the underlying language (e.g. Python??) can be included. Perhaps "include" can be used for this, or maybe we need a different command, such as "loadcode 'filename' ".

2.9 Command definitions.

By "commands", we mean both configuration and setup commands, and observing procedures. These commands have certain built-in features making them somewhat more sophisticated than ordinary functions.

A command uses a certain set of parameters which are keyword values either global or local to that command. It is possible to set all the parameters needed for a particular command prior to invoking the command. In that case one simply invokes the name of the command without any parameter list. For example, using the command "setReceiver" :

  
   receiver='Rcvr1_2'
   pol='circ'
   cal='lo-ext'
   setReceiver

The parameters may be given as in a traditional function call with the same effect:

  
   setReceiver(receiver='Rcvr1_2', pol='circ', cal='lo-ext')

A command knows the state of its parameters; in particular, it can determine which of its parameters have changed since the last invocation. Different types of invokation are possible:

  commandname

Performs only those actions required by any changes of parameters that have happened since the last invocation.

  commandname.init

Performs all operations to implement all its parameters, regardless of whether any parameters have changed or not.

  commandname.verify

This simply reports whether any of its parameters have changed since the last invocation.

Other options can be implemented if necessary. In particular, all commands should have a "help" option, invoked as:

 
     commandname.help
	or
     commandname(help)
	or
     help(commandname)