An observing table is the primary method for writing an observing program for the GBT. The basic command language for the GBT is the same 'glish' used by AIPS++, but you do not need to learn glish unless you want to write a detailed procedure that is not already available in the system. For most GBT observations an observing table and the interactive features of the "GBT Observe" graphical user interface (GUI) will be enough.
This document describes the observing table and command shorthand. To learn how to write observing procedures in glish and how tables and procedures work together see the document Writing GBT Procedures in Glish.
The observing table reader and executor is an integral part of the GBT Observe. The table window allows you to do things like load and verify a table, select a line or line range to be executed, and interactively enter commands as a supplement to the table. This document is concerned mainly with the table's syntax.
alias bw sp.bandwidth
alias proc procedure
block newbwinteg
sp.bandwidth = 10
sp.integration = 60
end
sp.config = 4x512
sp.integration = 120
header \
ra dec bw proc
05:32:49.0 -05:25:00 2.5 declatmap
newbwinteg
ramap
05:33:49.0 -05:27:30 2.5 declatmap
05:34:49.0 -05:30:00 5 declatmap
query "Enter integration time:" sp.integration
sp.config = 2x1024
header \
ra dec bw velocity proc
05:35:49.0 -05:22:30 2.5 356.9 declatmap
repeat 3
05:33:49.0 -05:27:30 2.5 356.9 declatmap
05:34:49.0 -05:30:00 5 356.9 declatmap
end
Because the table syntax is intentionally limited, the line type can be inferred from its content, and types can be mixed in almost any order. The basic rules are:
Alias, header, block, repeat, end, and query lines are recognized by their leading word. Assignments are flagged by the equal sign following a legal keyword. A procedure or block execution line is recognized by a legal procedure or block name standing alone on the line. All other lines are assumed to be table entries. An end-of-line character terminates a line, but a line may be continued with a backslash. DOS and UNIX use different end-of-line characters, but this will be evident when you look at the file in the other operating system. At the GBT we mean UNIX end-of-line characters.
A header line defines the fields in all subsequent table entry lines until another header line is encountered. All of the fields in the header line itself must be legal keywords or aliases. The header plus table entry combination is just a shorthand way of doing repeated assignments and procedure calls. For example, the lines
header \
ra dec bw proc
05:32:49.0 -05:25:00 2.5 declatmap
expand to
ra = 05:32:49.0
dec = -05:25:00
sp.bandwidth = 2.5
declatmap
There can be more than one procedure column heading, and two or more
columns can have the same keyword or alias name. A header line must
contain at least two fields, i.e., there must be at least two columns.
The assignments and procedure invocations are executed from left to right
in the table line. If one or more partameter values on a table line
remain unchanged from the previous line, they may be omitted by placing
asterisks in those columns. A procedure may be omitted from a line by
entering the 'null' procedure in this column.
A table entry line must contain the same number of fields as the nearest preceding header line in the table. The fields are separated by white spaces, and each field must contain a legal constant or procedure name that can be assigned to its column heading keyword.
An alias is just a convenient shorthand for a longer keyword. Keywords may be abbreviated to their shortest, unambiguous length, but the alias gives you the option create a more readable name. An alias must not be the same as an existing keyword, but it can be the same as an abbreviated keyword in which case the alias takes precedence. An alias can be redefined, but this generates a warning.
An assignment is simply the transfer of a constant to the value of a keyword. Keyword values are either strings, e.g. 2x1024, or have intrinsic units (MHz, seconds, etc.).
At least two special constant formats, sexagesimal hours and degrees, will be supported, and their interpretation will be implied by the keyword. Arithmetic expressions are not supported since this is generally required only in writing a procedure where the full algebraic capability of glish is available.
A query line is a way of pausing execution of the table to ask for input from the telescope operator or simply to wait for a response to continue after the operator has taken some required action. The first query field is a string prompt and the second (optional) field is a keyword or alias name. Execution of the query statement will flash the command line entry field on the operator's workstation and sound an audio alert.
A procedure call is the invocation of a built-in or user-defined observing procedure. All built-in procedures use keyword values that must be assigned ahead of time or accepted with their current values. In the table example above the 'declatmap' procedure uses the ra and dec keyword values for the map center and assumes defaulted values for the number and length of the raster sweeps, sweep spacing, scan rate, etc. The main GBT Observe panel shows the parameters required for each procedure, or they can be found in the help documentation.
Any number of table lines may be enclosed in a repeat/end loop. Any valid table line, except alias lines and block definitions, may be contained within a loop. The repeated lines are executed as if they had been entered directly into the table as many times as specified by the repeat loop.
The repeat loop syntax is
repeat (repeat count)
valid table lines
end
The 'repeat' and 'end' statements must appear on lines by themselves, except for the repeat count, of course. Repeat loops may not be nested. When selecting lines to be executed in the table be sure to include either all or none of the repeat loop.
Any number of table lines may be assigned to a named block. Normally this would be used to group a set of assignment statements for later use in the table, but any valid table line may be contained within a block. The block lines are executed as if they had been entered directly into the table. A block is called the same way as a procedure, except that, if it is called in a multi-field table line, it must appear in a column whose header keyword is 'block'.
The block definition syntax is
block (block name)
valid table lines
end
The 'block' and 'end' statements must appear on lines by themselves, except for the block name, of course. Block definitions may not be nested. A block name must not conflict with a procedure name or an existing block name. It is probably a good rule never to put alias or header lines in a block because this can make a table hard to read and prone to strange errors.
All block definitions made since the beginning of the current GBT Observe session will remain unless overwritten by a new block definition of the same name. Blocks are defined when a table is loaded so they do not need to be "run," but it doesn't hurt if they are. However, you must be careful not to run a sequence of lines that includes only the beginning or end of a block. A sequence of lines fully within a block (not including the 'block' and 'end' statements) may be run as if they were in the main table.
Every setup and built-in procedure parameter in the GBT system has a predefined keyword. When a value is assigned to a keyword in the table the corresponding parameter(s) are set in hardware or the value is retained for use when a procedure is called. Most keywords have unique names in the system, but some, like bandwidth, are repeated in different devices (spectral processor, autocorrelator, etc.). Hence, every keyword is assigned to a group which is designated by a keyword prefix. For example, sp.bandwidth is the bandwidth of the spectral processor. If a keyword applies to only one device, the prefix may be omitted, but the safest thing is to use it. The prefixes assigned so far are listed below.
Keywords may be written in their shortest, unambiguous form, e.g. sp.band, but for table readability it is usually a good idea to use the full name or assign a good alias. The shortened form is better left to interactive assignment on the command line of the command line window where conflicts are caught immediately and help is available on the possible choices.
The GBT requires a lot of keywords so there are two help facilities, help label buttons in GBT Observe and on-line documentation readable by a web browser. All keywords are reasonably defaulted, and most can be safely ignored, but it will be difficult for a new observer to write an observing table without guidance from the control panels or written documentation to show which parameters are important and required. The observing table should be thought of as part of a larger context. Lots of examples and templates will also help. Observers will want to plan their observing runs at their home institution so all of the help features built into the GBT Observe must be available to an observer at home.
Many keywords have a limited number of possible assignment values. For example, sp.config can be only 2x1024, 4x512, 4x256, or 8x256. The selection list is in the keyword documentation, but it will also appear in the command line message window when assigning the keyword interactively. The list will also appear in an error message generated by the table verifier, if an illegal value is assigned.
Keywords are associated with specific hardware devices or with the procedure set. A few keywords naturally have the same name on different devices so every keyword has a prefix to designate its device group, e.g. dcr.integrationtime. The prefixes assigned so far are
ac. = autocorrelator (GBT spectrometer)
ant. = antenna
dcr. = digital continuum receiver
fe. = front-ends
ifr. = IF signal router
lo1. = local oscillator #1
proc. = procedure parameter
sc. = scan coordinator
sp. = spectral processor
Some keywords are actually arrays. For example, there are up to eight IF center frequencies that can be set in the spectral processor, one for each IF channel. As in glish, keyword arrays are subscripted with square brackets, and ranges may be specified. Some possibilities are
Set the second IF channel center frequency to 256.8 MHz.
sp.iffrequency[2] = 256.8
Set IF channels 1 through 4 to separate center frequencies.
sp.iffrequency[1:4] = [245.0, 255.0, 245.0, 255.0]
Set IF channels 1, 3, and 5 to separate center frequencies.
sp.iffrequency[1,3,5] = [245.0, 255.0, 245.0]
Set all IF center frequencies to 250.0 MHz.
sp.iffrequency = 250
If there is a mismatch between the number of indices in the keyword index array and the number of values to the right of the equal sign, you will get a warning, but the assignment will be executed anyway. Extra values will be ignored. If there are too few values, the last value will be assigned to all remaining keyword array members specified. More complex glish index syntax, such as [1,2,4:6], or wild cards are not recognized by the table parser. If the keyword is not an array, the index will be ignored.
Presently, sexagesimal formats for time, R.A., and Dec. constants are HH:MM:SS.S and sDD:MM:SS.S. Other formats can be added as options if preferred. The only requirement is that the format be unambiguously interpretable on assignment lines and in table fields. For example, space-separated hours, minutes, seconds fields would be particularly difficult to parse where whitespace is already used as a separator.
An observing table is executed from within GBT Observe using the "Observing Table" panel which is opened by selecting it in the "Other Panels" button menu at the lower left corner of the GBT Observe Main Screen. The observing table panel looks like Figure 1.
When you initiate the observing table panel it will automatically load the last table that you were using unless you have started GBT Observe in a new directory. The state of your previous table session is saved in the binary file 'go_table_state'. A new table may be loaded by typing its file name in the entry box and clicking the "Load" button. Loading a table causes the table parser to check for syntax errors and save any block definitions. Parsing error messages are displayed in the window at the bottom of the GBT Observing Table panel. If the table contains an error, edit the file with your text editor and reload it.
Tables can be split between files as long as each file is syntactically complete. In other words, you cannot split lines, blocks, or repeat loops between files. Loading two or more files in succession is the same as loading the same files concatenated into one file. Block definitions are remembered from one table load to the next within one GBT Observe session so you can have separate files for block definitions and tables that execute procedures, for example. However, blocks are not remembered from one GBT Observe session to the next. Of course, you can only execute lines from the currently loaded table file.
To execute the observing program described by the observing table currently loaded, first select the lines to be executed and then click the "Run" button. Lines may be selected by entering start and stop line numbers in the fields near the Run button or by dragging the cursor over the lines in the text window. The lines selected must be syntactically complete in the sense that they must not include a block or repeat loop end without a beginning or vice-versa. Block definitions and header lines need not be executed since they take effect when the table is loaded, but it doesn't hurt to re-execute them. Lines within a block or repeat loop may be selected and executed as if they were outside the block or loop as long as you do not select the beginning or end of the block or loop.
Clicking the Run button will cause it to turn into a "Stop" button. Clicking Stop will abort table execution after which you must make a new line range selection (if needed) and press Run. To simply pause execution after completion of the currently executing line click the "Pause" button. This button will turn into a "Resume" button which you may press to continue execution on the next table line. The one-line text field to the right of the Pause/Resume button tells the current status of table execution, such as the current line being executed.
When the table executor is in idle status commands may be executed by typing them into the "Command" line and pressing Return. The syntax for a Command line is the same as for a line in a table, but the Command line offers a few help features. If you type an ambiguous keyword, the possible matches will be displayed in the message window. If you enter an assignment statement without a value, the acceptable value selections will be displayed.
The "Keyword" button will bring up a panel to show the selection of legal keywords by category, but for the moment this button is not active.
The "Log File" entry lets you specify a file name into which all executed table lines and error messages will be written as a record of your observing session. This is a different file from the "Glish Log File" entered on the main GBT Observe panel.
The "c Close" button closes the GBT Observing Table panel. If a table is being executed when you close the panel, the execution will continue. If you reopen this panel, the current status of execution will be displayed in the same manner that it would if the panel not been closed.
This document last updated March 7, 2000