The logical structure of the HartRAO parser should meet the following design constraints (in rough order of importance):
The generalised format of the input file is defined to be:
SETUP
... "global" or "common" keywords applicable to all objects
CONF name1
... named block of keywords to be inserted at USECONF name1
ENDCONF
CONF name2
... named block of keywords to be inserted at USECONF name2
ENDCONF
CONF name3
... named block of keywords to be inserted at USECONF name3
ENDCONF
DEFCONF name1 name2 default configs to be used for an object where
no USECONF is specified
ENDSETUP end of global or common area
OBJECT name first object for observation
... no USECONF so uses DEFCONF
ENDOBJ optional end-of-object statement
OBJECT next object for observation
USECONF name3 only CONF name3 is used for this object
OBJECT next object for observation
RESTFREQ 1234e6 define scan specific to this object
USECONF no parameter so do not paste in DEFCONFs
...
This format is discussed in more detail below.
Keywords appearing before the first object are regarded as GLOBAL, i.e. to pasted in at the top of each scan definition. They must be enclosed by by SETUP... ENDSETUP, e.g.
SETUP OBSERVER A.N. Other OBSLOCAL justin PROJECT galactic plane map at 3.5cm PROPOSAL 1999.003 ... ENDSETUP
There is one and only one global SETUP per input file, and this appears at the start of the input file. Where multiple SETUPs appear to be needed, the possibility of error or ambiguity in parsing the commands is so great that another input file must be created.
All keywords are categorised in terms of whether thay may appear within the "SETUP" section or an "OBJECT" block or both. For example, the SETUP block therefore cannot validly contain RESTFREQ other than within a CONF... ENDCONF block.
Being globally defined, keywords in SETUP will be used for all scans unless they are replaced by the local definition of a keyword after OBJECT or RESTFREQ or from a pasted in CONF block.
Within the setup section, re-useable combinations of keywords may be explicitly defined in a "CONF name"... "ENDCONF" blocks. Each config block would consist of any combination of keywords from those applicable to an "OBJECT" block with one exception, namely that when a "RESTFREQ" keyword is included, it must be the first keyword in the block (such that all the other keywords will always be associated with the "RESTFREQ" when the "CONFIG" is used.)
These "CONFIG" blocks may be inserted into an "OBJECT" block at any point using the "USECONF" keyword such that the "OBJECT" block is only interpreted once all such substitutions have occurred.
A "DEFCONF" keyword with the names of one or more CONF blocks as parameters in the "SETUP" section defines which "CONFIG" blocks will be included automatically just before the (explicit or implicit) "ENDOBJ" when no explicit "USECONF" was given.
DEFCONF can only appear in the SETUP section.
"USECONF" with no argument is used to cancel the implicit inclusion of DEFCONF.
After encountering OBJECT, global keywords from SETUP are pasted in. Then if a catalog has been defined the parameters for the object in the catalog are pasted in. If USECONF NAME follows immediately after OBJECT, the SETUP keywords and keywords in a catalog (if the object is in the catalog and a catalog name has been given in the SETUP section) are pasted in before the CONF NAME keywords.
As in SETUP, all keywords common to the scans on the OBJECT must occur before a USECONF block or the RESTFREQ keyword (which may be standalone within an OBJECT but not standalone outside a CONF block within SETUP).
If no USECONF appears explicitly after OBJECT or via a pasted in CONF block, DEFCONF will be pasted in at the end of the keywords for the object.
If no RESTFREQ appears at all in the list of keywords for an object after pasting in SETUP and either named CONF or DEFCONF, no scans will be done.
After the SETUP keywords and the CONF NAME or DEFCONF keywords have been pasted in as text in the appropriate places after OBJECT, the sequence of keywords from OBJECT to the next OBJECT can be parsed to create scans for the scheduler and observing programs.
In parsing the sequence of keywords from OBJECT on, a new SCAN construct is started when RESTFREQ is encountered after OBJECT. Subsequent RESTFREQs after the same OBJECT imply consecutive SCANs to be created as structures and later executed. The keywords between each RESTFREQ are specific to each SCAN thus defined.
Keywords that are repeated within a SCAN constructed in this way are handled such that the parameters associated with the last instance of the repeated keyword replace the earlier parameters.
SETUP // global SETUP block
OBSERVER G.D. NICOLSON
PROJECT flux calibration
PROPOSAL 1999.001
CATALOG calibrators.cat
OUTFILE calibrator_data // data subdirectory name
// above are implicit at start of all OBJECTs
CONFIG 18NA // Start of explicit CONF block
RESTFREQ 1650E6 // ( must be first line of block )
INSTRUME NA
WEATHER Cloud
ENDCONF // end of explicit CONF block
CONFIG 13NA // Start of explicit CONF block
//RESTFREQ= 2300E6 // ( commented out - not available )
INSTRUME= NA
WEATHER = Cloud
ENDCONF // end of explicit CONF block
CONFIG 6D // Start of explicit CONF block
RESTFREQ 5000E6
INSTRUME DICKE
WEATHER Clear
ENDCONF // end of explicit CONF block
CONFIG= 3D // Start of explicit CONF block
RESTFREQ= 8400E6
INSTRUME= DICKE
WEATHER = Clear
ENDCONF // end of explicit CONF block
CONFIG STEP // Start of explicit CONF block
// - no restfreq in this block
SCANTYPE STEP // stepping type observation
STEPSEQ FNNCAL, HPN, ON, HPS, FNS, FNE, HPE, ON, HPW, FNW
ENDCONF // end of explicit CONF block
CONFIG SCAN // Start of explicit CONF block
// - no restfreq in this block
SCANTYPE SCANPNT // crossed scans type observation
ENDCONF // end of explicit CONF block
DEFCONF STEP 6D 3D 13NA 18NA // Default setup is stepping at 4 frequencies
// - though 13cm is temporarily unavailable
// implicit at the end of those OBJECTs where
// nothing was explicitly specified.
ENDSETUP // end of global SETUP
OBJECT 0915-11 // calibrator - get coords etc from catalog
// SETUP values implicitly pasted in here
HALIST 0H // start at meridian transit (HA = 0 hour)
// default CONF list pasted in here.
// expands to step scans at all 4 frequencies
ENDOBJ
OBJECT 1228+02 // start new object, also calibrator
// SETUP values implicitly pasted in here
HALIST = 1h // start at HA = 1 hour
USECONF = STEP // set default observation type to stepping
RESTFREQ= 12178E6 // Only this source is strong enough at 2.5cm
INSTRUME= TP
WEATHER = Clear
USECONF = SCAN // - use crossed scans as source is extended
USECONF = 3D SCAN // - use crossed scans at 3.5cm also
USECONF = 6D 13NA 18NA // but step scan at the other 3 frequencies
// default CONF list not applicable
ENDOBJ
OBJECT = 1648+05 // start new object, also calibrator
// SETUP values implicitly pasted in here
HALIST = -3h 3h // start scans at HA = -3 and +3 hours
USECONF = STEP 13NA 18NA // don't bother with 3.5 and 6cm
// default CONF list not applicable
ENDOBJ
The Parser is run with the following command line parameters:
Parser [input_file_name] [binary_out_file_name] [parsed_out_file_name]
If only the input file name is given, no binary- or parsed- output files will be produced.
The binary output file is the file required by the Scheduler. It has to be copied to directory /schedules/ to become accessible to the Scheduler.
The parsed output file is optional. It is a plain text file which indicates how the parser has responded to the input file, for diagnostic purposes.
An example of a parsed output file from a bug-free input file follows. Note that the parameter (0 or 1) that follows the first '=' sign is a flag set to 1 if the parameter was used in the input file or 0 if it was not used and a default value has been inserted. The values supplied or inserted by the parser are shown after the second '=' sign.
****SCHEDULER_TASK***** OBSERVER =1=M Gaylard OBSLOCAL =1=mikea PROJECT =1=1665 MHz hydroxyl maser test source PROPOSAL =1=2003.006 OUTFILE =1=G2852_1665 SCANTYPE =1=Spectra DURATION =1=300 START =1=52821.000000 END =1=52852.291667 INTERVAL =0=0.000000 SIDERIAL T =0=-1.000000 HOUR ANGLE T=1=-180.000000 HA LIMIT =0=90.000000 ELEV LIMIT =0=0.000000 SUN LIMIT =0=0.000000 MOON LIMIT =0=0.000000 REPEATS =1=1 LINKED =0=0 RESTART =0=0 LEVEL =1=INTERRUPT ORDER =0=OPTIMISE WEATHER =0=2 NIGHTIME =0=0 OBJECT =1=G285.26-0.05 SOURCE =0= COORDSYS =1=B1950 LONGITUDE =1=157.405000 LATITUDE =1=-57.779444 RESTFREQ =1=1665401840.000000 EPHSIZE =0=0 EPHPOINTER =0=(nil) OBSSIZE =1=60 OBSPOINTER =1=0x8060890 **** spectra ***** SPVLSR =1=8.000000 SPCHAN =1=1024 SPCONF =0= SPFS =1=500000.000000 SPPSLON =0=0.000000 SPPSLAT =0=0.000000 SPTIME =1=120.000000 SPPOINT =0=0 ****SCHEDULER_TASK***** OBSERVER =1=M Gaylard OBSLOCAL =1=mikea PROJECT =1=1665 MHz hydroxyl maser test source PROPOSAL =1=2003.006 OUTFILE =1=G2852_1665 SCANTYPE =1=Spectra DURATION =1=1140 START =1=52821.000000 END =1=52852.291667 INTERVAL =0=0.000000 SIDERIAL T =0=-1.000000 HOUR ANGLE T=1=-180.000000 HA LIMIT =0=90.000000 ELEV LIMIT =0=0.000000 SUN LIMIT =0=0.000000 MOON LIMIT =0=0.000000 REPEATS =0=1 LINKED =0=0 RESTART =0=0 LEVEL =1=INTERRUPT ORDER =0=OPTIMISE WEATHER =0=2 NIGHTIME =0=0 OBJECT =1=G285.26-0.05 SOURCE =0= COORDSYS =1=B1950 LONGITUDE =1=157.405000 LATITUDE =1=-57.779444 RESTFREQ =1=1665401840.000000 EPHSIZE =0=0 EPHPOINTER =0=(nil) OBSSIZE =1=60 OBSPOINTER =1=0x8061398 **** spectra ***** SPVLSR =1=8.000000 SPCHAN =1=1024 SPCONF =0= SPFS =1=500000.000000 SPPSLON =0=0.000000 SPPSLAT =0=0.000000 SPTIME =1=120.000000 SPPOINT =1=1