3 RULES FOR TEMPLATES
In the rest of this chapter, we use yy as prefix for module/file names for a generic instrument.
3.1 MODULES
The general rule for all instrumentation cmm modules is defined in [6].
All files dealing with templates for an instrument must be distributed over four modules, described in the following sub-sections.
These modules must be installed, as any other instrument module, as part of the general installation procedure, based on the pkgin tool (see [17]) and on the contents of the installation module yyins.
3.1.1 Observation Template Signature Files
The module yyotsf contains Template Signature Files of observation templates, supplied to astronomers for observing runs. The product of this module is mainly the instrument package as defined in [9], i.e. a zipped file containing the instrument summary file and the template signature files. Such a file is created in ../config after make all and copied in $INTROOT/config after make install
This module contains the public interface towards P2PP and is normally only updated in agreement with ESO Data Flow responsible.
3.1.2 Observation Template Scripts
The module yyoseq contains the Sequencer scripts, implementing the behavior of the observation templates, whose Signature files are contained in module yyotsf. Having the *.tsf files in a separate module assures that execution details can be changed at any time during development/maintenance, while the public interface towards P2PP (the Instrument package, consisting of Template Signature Files and the Instrument Summary File) is kept unchanged.
3.1.3 Maintenance Template Signature Files
The module yymtsf contains Template Signature Files of maintenance templates, used only by operations personnel at Paranal. The product is a maintenance instrument package that contains all template signature files for the instrument: observation and maintenance templates.
3.1.4 Maintenance Template Scripts
The module yymseq contains the Sequencer scripts, implementing the behavior of the maintenance templates, whose Signature files are contained in module yymtsf
3.2 TEMPLATES
3.2.1 Template Signature Files
It is strongly recommended to use the oslx utility oslxCompileTsf to build tsf files: by using a OO approach, consistency and reliability are enhanced.
The name of Template Signature Files (TSF) must follow the scheme below:
description = optional string (up to 16 letters) identifying the purpose of the template (see Table 1 for standard values)
Table 2 defines the set of mandatory Template Signature Files, which have to be provided by all instruments, if applicable.
The keyword TPL.VERSION should contain the CMM reserved string pattern $Revision$, which is then automatically updated (including cmm version number) whenever a new cmmArchive operation is done on the module:
Every Template Signature File must specify and use a Reference Setup File (RSF).
A RSF should contain the setting of all keywords needed to perform the observation(s) foreseen by that template.
The only keywords appearing in the TSF itself should be:
2. Keywords, whose value is fixed for that template, but is going to be used/checked within the associated Template Script File.
3. Keywords, whose value is fixed for that template, but cannot be put in the RSF, e.g. because such a file is shared among different templates.
The name of Reference Setup Files must follow the scheme below:
Whenever a RSF is used only by one TSF, the name has to be the same.
Whenever a RSF is used by more than one TSF, the name has to remove the parts, which are not in common.
The order in which keywords must be defined and appear in a TSF is the following:
For those templates handling two or more sub-systems, i.e. the light is split and reaches different detectors, after following different paths (e.g. UVES dichroic templates, whereby sub-systems are the red and the blue arm), the order must be:
INS (devices on the DET1 light path only, e.g. UVES red arm)
INS (devices on the DETn light path only, e.g. UVES blue arm)
INS (devices common to all sub-systems, e.g. UVES pre-slit devices)
It is recommended to use the VLT sw tool tpltooTsfKeySort (see 6.8) to perform the requested ordering (e.g. by calling it within the Makefile, see example in module xxotsf).
1. While it is clear that all templates of type tec belong to the Maintenance category, and must therefore be placed in the module yymtsf (see 3.1.3), templates of other types (acq, obs, cal) may belong either to Observation, if they are supposed to be made available to observers, or to Maintenance, if they are supposed to be used only by operations staff; in the former case, they have to be placed in the module yyotsf (see 3.1.1), in the latter case in yymtsf.
2. In general, setting the Instrument Mode, through the keyword INS.MODE, means setting a few keywords to certain values. The translation from INS.MODE <value> to a set of pairs <keyword> <value> is outside the scope of TSFs and RSFs: it is normally done by OS (see [18] and configuration keywords OCS.MODEi.SETUP). TSFs and/or RSFs should therefore not contain the values of keywords already implicitly defined by INS.MODE. On the other hand, OS is responsible for the translation, through the keyword OCS.MODEi.SETUP, only of those keywords, whose value is fixed for that mode, independently from the operations/observations one intends to do. Keywords, whose value is not fixed, but may change, depending on the type of observation within a specific Instrument Mode, have to be specified in TSFs or RSFs.
If an Instrument has a Mode called RED, and in this mode the device INS.MIRR1 has always to be placed in position RED and the lamp INS.LAMP1 has always to be on, then the OS configuration file should contain the following definition:
The TSF (or RSF) should contain INS.MODE RED, but not the values for INS.MIRR1.NAME and INS.LAMP1.ST (implicitly done by INS.MODE).
3. The same principle applied to the INS.MODE keyword at point 2. above should be extended to all assemblies defined within ICS (see [19]).
In all TSFs and RSFs where INS.LAMP OFF appears, the values for INS.OPTI1, INS.LAMP1 and INS.SHUT1 should not be defined (implicitly done by INS.LAMP).
3.2.2 Template Script Files
Templates are supposed to send commands only to the instrument OS front-end process. They are not allowed to send commands directly to TCS or ICS or DCS nor to use a mechanism different from that defined in the BOB User Manual (see procedure SendCmd in [16]).
Whenever an exposure, within a template, terminates with a result other than SUCCESS (including therefore any error or abort from the operator), the template must terminate with error and the whole OB be aborted.
The name of Template Script Files must follow the scheme below:
Whenever a Template Script File is used only by one Template Signature File, the name has to be the same.
Whenever a Template Script File is used by more than one Template Signature File, the name has to remove the parts, which are not in common.
The name of the FITS file, where the result of an observation will be stored, must follow the scheme below (see VLTSW20020505):
The value of the keywords OCS.DETi.IMGNAME and, optionally, OCS.DETi.IMGEXT must be set within the Template Script.
The value of OCS.DETi.IMGNAME must follow the scheme below:
The rule above is embedded in the class tplOBS, method ImgName (see 4.1), called e.g. by method Expose.
Some Maintenance Templates may produce files in the format specified and used by the CCS sampling tool (e.g. to analyze a motor current curve). Such files should be archived. Their standard directory location is defined in [7].
In order to optimize observing time, files produced by Infrared detectors, and in general files containing large amount of data, should be archived in background, i.e. the next observation can start while the results of the previous one are being archived. The Template Instrument provides examples of how this can be achieved with the standard tools. See e.g. the template script xxoseq/src/XXXX_irimg_obs_exp.seq.
Whenever the instrument must be brought to a safe state at the end of a template, no matter how the template completes, the tplTry procedure should be used, whereby the corresponding commands/actions are placed in the block <finally> (see tplTry manual page). The Template Instrument provides examples: see e.g. xxoseq/src/XXXX_optimg_cal_calunitflat.seq. In order to achieve the same purpose, the usage of callbacks or try_eval or catch instructions within the template script itself is not recommended.
3.3 OBSERVATION BLOCKS
3.3.1 Simple Observation Block Description files
In order to be able to test each individual template directly from BOB on the Instrument Workstation (no need to be connected to the OH/P2PP WS), there must be one Observation Block Description file for every Template Signature File implemented.
The name of such OBDs must be the same as the name of the corresponding TSF, but with extension .obd
It is recommended to use the VLT sw tool tpltooObdBuild (see 6.9) to create such OBDs (e.g. by calling it within the Makefile, see example in module xxotsf).
3.3.2 Complex Observation Block Description files
In addition to the OBDs associated to single TSFs, there must be one, which runs sequentially all existing templates, whenever possible and it makes sense. The purpose is purely technical, to perform an automatic regressive test, whenever new versions of the VLT or instrument Software are installed.
Since such an OB can take very long, in some case it might be more convenient to split it into two or more files, which then should be named
It is recommended to use the VLT sw tool tpltooObdBuild (see 6.9) to create such OBD (e.g. by calling it within the Makefile, see example in module xxotsf).
Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |