| |
|
|
|
2 USER'S GUIDE
2.1 OVERVIEW
BOB is the high-level interface towards the VLT Control Software. It operates on Observation Block Descriptions (OBDs), which it either reads from a disk file or receives from the Scheduling tool (OH/OT). These OBDs contain (or refer to) all the information needed by VCS as a whole to execute individual exposures. It is BOB's task to break these OBDs down, ending up with "units" of individual exposures, sending sequences of commands which are understood by its VCS lower level partner, i.e. OS. At the same time, BOB's GUI keeps the user informed of the contents of Observation Blocks plus Templates, and their status of execution, as high-level units.
If the OBDs have been received from the Scheduler, the status of execution of the individual Templates etc. is fed back to the Scheduler as these events occur. This allows the Scheduler to take internal decisions, and also to inform its fellow processes on the OH side about relevant events.
2.2 STARTING BOB UP
BOB requires communication with the OH-scheduler and with the OS of the instrument it is controlling. For this communication it uses the CCS message system. Therefore, BOB needs to be started from a shell running on a WS equipped with CCS and running environments.
As the messages exchanged between BOB and the OH-scheduler do not include the contents of template scripts nor template signature files, but rather only a reference to their names, these files need to be present on the system where BOB runs. BOB will look for these files under specific paths, including $INS_ROOT/SYSTEM/COMMON/SEQUENCES1. So it is vital to have the INS_ROOT environment variable set before starting BOB.
$ bob ?-display <hostName>? -- ?-configFile <fileName>? \
The options before the double dash are the same ones as the options permitted for the standard wish (see the manpage of Tcl). The ones after the double dash are the name of the configuration file under the home-directory (defaulting to .bobrc - see also below), the password to switch to the engineering interface (see section2.10), the name under which to register BOB with CCS, and a flag to pass to OH if it is not expected to get any events.
BOB will at start-up automatically configure itself, reading in the last saved configuration file (see below). When BOB starts up successfully, a main panel will appear on the screen (see Figure 4)
, and BOB will start executing <scriptFile> (if specified; see also section 2.11). The various constituent parts of this GUI are:
· a window title bar, which contains a.o. the name with which this instance of bob is registered with CCS, and the environment under which it is running. If the ccsInit failed, this part within brackets will simply contain bob@<hostname>
· a vertical toolbar on the left side with buttons which have icons in them. These buttons have balloon-help, and are typically the only buttons to press for a successful execution of Observation Blocks. Inactive buttons appear shady.
· a short-help line (white background) at the bottom, with the heartbeat indicator. Depending on where the mouse cursor is, this line will show a single line of text, showing what the effect will be if a mouse button (typically the left button) gets pressed.
· below the short-help line, an action area, with labelled buttons. Inactive buttons are shaded out.
Although the main panel by itself is not resizable, the relative distribution of the area occupied by the two latter panes can be modified by dragging the squared sash at the right side on the horizontal separation line between the two panes. Also, these panes are equipped with vertical and horizontal scrollbars, which can be used to see information which is off-screen.
The messages which appear in the Template Log-area are also automatically stored on disk. OB-activity will be written into $VLTDATA/tmp/bob_<procNameOS>.log, when an OB terminates or when it is aborted. If <procNameOS> is changed (see 2.3 below), the log-file is changed correspondingly. If the logfile $VLTDATA/tmp/bob_<procNameOS>.log already exists, bob will move it to $VLTDATA/tmp/bob_<procNameOS>.log.old, before opening the former one.
Apart from these template logs, bob will also generate FITS ops-logs, which are archived. See also section 2.6.
2.3 CONFIGURING BOB
To be able to communicate with OS and the OH-scheduler, BOB needs to have some information which reflects its environment. Although BOB at start-up configures itself to the configuration which was last saved, it is of course necessary to set these configuration parameters when the environment (process names, etc.) change, or initially when BOB is run for the first time.
The configuration panel (see Figure 2) is invoked by either hitting the "tools" button (toolbar, ninth button from top) or by clicking on the Configure menu, then going to Environment....
This panel contains a.o. the environment name and process name of the OH-scheduler2, which are obviously essential if communication with OH is needed, i.e. when the OBDs will not be retrieved from a disk file. The environment name / process name for OS also need to be filled out. Remark that Tcl-variables can also be referenced in these latter entry fields (and further down, in the Call-backs and Print command entry fields as well). This is particularly useful for environment variables, e.g. $env(RTAPENV) stands for the value of the environment variable RTAPENV.
The fields for the process names can contain a second list-element, in which case this element will be used as process-identifier part of the label for the OB-canvas (see Figure 1). If for OS there is no such label given, bob will try to find out the instrument-id by interrogating the OS process: first it will send a "STATUS -function INS.ID" command, and if this fails, a "FORWARD -subSystem ICS -command STATUS -arguments 1,INS.ID" command. If and only if both these commands do not return any useful information, the OS process-name itself will be used in this label for the OB-canvas. Remark that new entries in all these comboboxes can be saved in their respective listbox (showing up when the arrow is pressed) by pressing the <Enter> key. An entry can be removed from a listbox by selecting it (so it appears in the entry field), preceding it with a minus sign and then pressing <Enter>.
It should be noted that the label of the OB-canvas reflects the status of the currently displayed OB. I.e. changing the OH process name via the configuration panel will not be reflected by this label until a new OB is fetched from OH. On the other hand, changing the OS process name will be shown immediately, as this does affect the currently displayed OB. Remark that the short help-text for the vertical toolbar top button (to fetch an OB) contains the information where the OB will be fetched from, and the fourth button (to start an OB) will say where it sends the template commands to.
The action corresponding to the top button on the toolbar is influenced by the settings for OH: if either the environment name or process name is left blank, BOB will assume you want to retrieve files from disk, instead of retrieving them from OH.
Part of the configuration can be set directly via the Configuration menu of BOB's main panel, i.e. without pressing Environment... and invoking the configuration panel. All of the following configuration menu options can be selected directly:
· Run all OBs: if more than one OB has been downloaded, this option will make sure that they are all executed one after the other, unless there is some error or operator intervention.
· Auto-request OBs: when set, this will cause BOB to request automatically for the next OB when the current one is finished. Remark that if an OBD is loaded from a file, while the OH procname is blank and the auto-request option is set, then BOB will reset the OBs when the last one has been executed, and start all over again (in other words, BOB will loop infinitely).
· Auto-unfold: when set, the information shown on the canvas about the OB and its templates will automatically unfold as they are executed, and fold-back when finished - unless the OB/
templates were explicitly unfolded before the start (in which case they remain as they were).
· Create all TPLs: this will create and check (to some extent) all the templates of all OBs. This is likely to be a "waste of energy", as a normal operation of BOB plus scheduler foresees to use only the first of the OBs received, and then after execution to request the next.
· Verbose TPL communication: this will log in the "Template Messages" text-box all commands + parameters sent by the template script to OS, plus corresponding replies. Commands are logged in blue, OK replies in green, error messages and error replies in red. Messages logged explicitly by the template-script itself and the "starting exposure ..." message remain in black (the standard foreground colour), and are always underlined.
· Simulate TPL communication: this will short-circuit the communication between BOB and OS. This means that commands sent by the template script to OS will always return successfully, with some configurable delay. Remark that this type of simulation is without the intervention of any external simulation process: all short-cuts are taken by BOB itself.
All these configuration menu options appear also on the Configuration panel (see Figure 4). Configuration items which are in the configuration panel, but not under the Configure menu of BOB's main panel are:
· The Environment and Process names of both OH and OS (see above). These are the names under which they run in the CCS environment.
· The Behaviour of bob; this includes the User proficiency (beginner or advanced), which allows bob to decide how verbose and technical some messages need to be. This section includes also the first four checkbuttons as available under the Configure menu (see above).
· The Communication with OH: contains the Status events checkbutton. When this button is activated (which it is by default), all template- and OB-status messages as defined in [1] will be sent to OH. Otherwise, none of the automatically generated status events will be transmitted, and OH will be told it should not expect any of these events either. Remark that the PAFReady event, which is not generated by BOB itself but rather by an explicit call within a template script (see section 2.7.2) is always transmitted to OH.
· The Communication with OS: contains the Simulate, Verbose and Internals checkbuttons, and two sliders for simulation delays, allowing to set how many ms a reply should artificially be delayed when in simulation mode. The top one is for specific commands which are listed in the entry field close to this slide bar. The bottom one is similar, but for all commands which are not listed in the entry field of the "specific" OS commands. The Internals checkbutton is for obtaining additional information about keyword use - i.e. additional info/warnings, logged in the TPL-messages text-box (see section 2.7.1).
Finally, this section has an entry field to list all OS-commands which should be skipped after the Abort flag has been set (by pressing the Abort button). This can speed up considerably the response time to the Abort button (see 2.7.3). The character * can be entered as a wildcard for all commands, while commands preceded by a dash indicate an exclusion from this skip-list.
· Call-backs: the scripts to execute at termination of an OB, template, or when a configuration parameter is modified. The definition of the template call-back can be overridden programmatically in e.g. the template script itself via a call to the setCallBack convenience procedure (see section 2.7.2). For the OB call-back on the other hand there is no similar convenience procedure.
These OB/template call-backs will be executed independent from the exit-status of their OB resp. template, i.e. even when the OB/template fails, the call-back will be evaluated.
Remark that these call-backs should not be seen as an extension of the template's functionality (e.g. to prepare/start exposures). Instead, they should be considered as internal housekeeping functions. Their typical use is to log the template's or OB's termination or to put the instrument in a safe state. They will be executed after the template's resp. OB's termination status has been communicated to the Scheduler (OH/OT). The template call-backs will not skip any commands after the ABORT key has been pressed, independent of the configuration setting explained in the section above on Communication with OS. This allows to put the instrument into a safe state, independent of the termination status of the template/OB.
The call-back for the modification of a configuration parameter is executed at global level, and gets at invocation automatically four more arguments than what is declared in the corresponding entry field:
b. a boolean indicating if this call-back is executed during the initialization phase (value 1) or during normal operation (value 0)
E.g. if in the configuration panel the entry field for this call-back is set to `myCfgCB a b', the command myCfgCB could be defined in a library as
proc myCfgCB {fixed1 fixed2 configParam initFlag oldValue newValue} {
# here we process the input params
...
}
· Template libraries: a space-separated list of names of VLT/Tcl-libraries which contain declarations of auxiliary procedures used by some templates. Remark that these names do not include the "lib" prefix nor the ".tcl" suffix of the directory they are stored in, so in the example of Figure 4 BOB would look for procedures under directories called lib/libmySeqLib.tcl and lib/libmyTclLib.tcl. The search path for these directories will be:
This scheme coincides with what is common practice for the VLT Common Software, and is supported by a.o. vltMakefile.
· Print command: command into which logs will be piped when printing is requested. As this is actually the trailing part of a Tcl exec-command, Tcl-variables can be used
· Load Tcl Plugin: to import a Tcl script (e.g. a VLT panel), within the same interpreter as BOB. This means such a Tcl script can have access to e.g. variables set by the template script. If the at start-up checkbutton is ticked, this script will be executed during start-up, immediately after bob is initialized. Otherwise this script can be activated via the Configure menu.
The configuration settings can be saved by pressing the Save or Save as ... action buttons in the Configuration Panel. In the former case (Save button) these settings will be stored in the file as indicated in the Configuration Panel title bar, i.e. the currently loaded configuration file. In the latter case (Save as ... button), a file selection panel will pop up to enter a filename. After saving the configuration file, the window title showing the name of the configuration file will be updated. Remark that the default name for the configuration file is .bobrc, and this can be overridden at BOB's start-up with the -configFile option. If this is a relative pathname, it will be interpreted as relative to the home-directory. If this file exists, it will be read by BOB at start-up, i.e. BOB will start-up with the configuration that was last saved into that file. Otherwise, BOB will try to give some "reasonable" default values to these parameters.
A similar scheme is applied for the Preferences. The Preferences panel can be triggered via the Configuration menu or the "palette" button on the toolbar. The purpose and contents of the Preferences panel is explained in section 2.4.
2.4 BOB'S PREFERENCES
There are several settings of BOB which do not require any adjustment in order to have BOB operating and behaving correctly. These have been grouped in a Preferences panel, which will pop-up when the toolbar-button below Configure is pressed. The panel which will then be displayed is shown in Figure 3
.
There are currently 3 sections in this panel: font definitions, sound related settings and log-texts for the OS WAIT command. In the former, one can set the fonts for the labels of the OB canvas and TPL-messages text-box, the text within the OB canvas (the upper part of BOB's main panel), the text within the template log area (the lower part of BOB's main panel), the dialog boxes showing warning or error messages, and finally the editor panels used during editing of OBs/templates (within engineering mode - see section 2.10).
In the middle part of the preferences panel, one can select the audio-server, indicate whether its proper functioning should be tested at start-up or not, set the audio-volume and determine at what occasion this volume should be applied. Remember though that it is necessary to press the "Apply" or "Save" button to enforce these settings - e.g. merely moving the volume slider will have no effect on the volume until either of these latter buttons has been pressed. In this part of the panel one can also point to the sound files to be played when particular events occur. Remark that this requires the sound to be enabled. This can be done via either the "Enabled" checkbutton at the top of this section, or the BOB toolbar-button below Preferences. Of course that on its turn requires that the audio-server pointed to (by default or via the corresponding entry field) is properly functioning; for details on audio see [5]. The filenames of the sound-files need to have their extension included in these entry-fields. Current supported file formats are WAV, MP3, AU, SND, AIFF, SMP, and RAW binary; as BOB relies on the audio module for playing sounds, this list of formats is actually determined by the audio module.
The bottom section of this preferences panel allows to configure the messages to log when a reply is received on a WAIT command sent to OS, according to the option that is passed along with this WAIT command. The options are specified in the left column, while the text is entered in the right column. The resulting log-text for a matching option will be "exposure <exposureNr> of <nrOfExposures> <text> (<timeStamp>)" whereby <text> is as defined in the right column. If a WAIT command is issued for which there is no match as far as its accompanying options are concerned, the log-text upon receiving a reply will be "ended exposure <exposureNr> of <nrOfExposures> (<timeStamp>)". Remark that the option-matching is done using regular expressions, so in order to match any amount of whitespace one should specify "\s+". See also the manpage of BobPanedComboBox.n in section 4.2, in particular for the key-bindings, and re_syntax.n for the syntax of regular expressions.
The different action buttons for this preferences panel are standard: OK will apply the values and remove the panel, Apply will force BOB to immediately take the shown values into account while leaving the preferences panel displayed, Save will apply the values and save them in the configuration file, leaving the panel on the display, while Cancel will pull out of this preferences setting, keeping the values as they were when applied last.
2.5 LOADING AND SAVING OB-DESCRIPTIONS
OBs can be loaded via the File menu - Load OBs. A sub-menu will allow to either request OBs from the OH-scheduler, or to load them from a file (penultimate menu option). In the latter case a file-selection box will appear.
If a set of OBs was loaded via a file, it can afterwards also be reloaded via the Reload file menu option under Load OBs. This is useful e.g. if one has edited some parameters via the Engineering interface, and wants to discard the changes. This button can normally also be activated during execution of an OB. Although this may look like a graceful recovery for a hanging script, there is presently for technical reasons no complete clean-up of internal tables and stacks associated with this action. I.e. if a reply was pending when a file was re-loaded, this reply will still be pending and can actually disturb BOB if it would still come in at a later time. So care has to be taken with the use of this menu option.
The next OB can also be solicited via the top button of the toolbar. This will then lead to a request of a single OB to OH. If in the Configuration panel the environment name or process name of the OH partner is left blank, BOB will assume you want to retrieve a file from disk, instead of retrieving an OB from OH.
The OBs which are received from OH can also be saved locally, either by the Save command under the File menu, or via the third button of the toolbar. In either case a file-selection box will appear to get a filename. If the filename given does not have a .obd extension, BOB will append one to the filename.
When the OBD is loaded, BOB will show its contents, and allows you to perform several actions on it, like:
· fold/unfold the information; an arrow pointing to the right indicates there is more information hidden underneath, and clicking on it will unfold to the next level.
· flag that a particular OB or template should be skipped3, or that BOB must pause when it gets to that point.
· select a particular OB or template to display its log; logs are empty at the beginning and get filled as execution proceeds.
An example of this is shown in
Figure 4.
Remark that the label of an OB and its templates contains information which is taken from the OBD and the template signature files. This includes the ID of OBs and templates.
2.6 RUNNING AN OB
Press the "Start" action button, or the telescope button in the toolbar (fourth from top). An icon will appear next to the OB and template, showing its state ("running"). In general, an OB inherits the state of the currently executing template. If this template returns an error, or is aborted, its OB will get the same status.
OBs and templates can be paused or aborted while running. The "pause" action button will only pause in between 2 templates. An "abort" will pass the proper flags on to the executing template, but the template only looks at these flags on particular moments, so an "abort" is usually not immediate. Anyway, BOB itself does not issue an abort-command towards OS, it merely sets a flag which can be picked up by the template. It is up to the template to decide to issue an abort command. BOB will not permit to send specific commands to OS for this particular template (see section 2.3).
OBs and templates can also get a "breakpoint" as long as they are idle (i.e. not running nor finished). This is achieved by clicking with mouse-button-3 on the label of the particular OB/template on the canvas. This clicking works as a toggle, i.e. the breakpoint is removed by clicking again. Putting a breakpoint on an OB means it will enter into "pause" before any of its templates starts. Putting a breakpoint on a template means it will enter into pause before the template script is started.
Pressing again mouse-button-3 on an OB or template with a breakpoint will change this breakpoint into a "skip"-flag. I.e. if during execution such a flag is seen, the OB resp. template will be skipped. A third mouse-button-3 press on such an item will put it back into its "normal" idle state.
When a template is executing, it can write some log messages to the template text-box (lower part of panel). It should at least indicate what the important actions are. The start of an exposure is automatically intercepted by BOB and a corresponding log-message is displayed. Every template keeps record of its own text, and this can be displayed by clicking with mouse-button-1 on the template label.
If during the execution of the template script an error occurs within this script, a message dialog box will pop up indicating this. If the user-level is set to "advanced", this message will also contain an error stack trace.
Foldable items (i.e. items which contain more viewable information) are indicated on the canvas with a small triangle, which at the same time indicates the status of folding. The (un)folding is simply performed by clicking with the mouse-button-1 on this triangle (see Figure 4).
OBs and templates can be marked with:
· a skull: the OB/template was aborted. Remark that aborting a template leads immediately to the abortion of its OB.
· a red flag: some error was returned by one of the templates. This is usually because OS returned an error. When this happens, an error dialogue box will pop up signalling this problem.
Once an OB is finished (either successfully or with error), it cannot be executed again. For the time being, there is a "Reset status" action button, which will reset the status of all OBs and templates on the canvas, so they can be re-executed, while maintaining the flow control settings (breakpoints and skip flags). To start an OB fully afresh, i.e. without flow control flags as set before, one should instead re-load the OB.
If there are more than 1 OBs loaded, and when BOB is idle, the next OB to execute can be selected by clicking mouse-button-1 on its label.
There can be several FITS ops-logs during the running of an OB, e.g. when it starts and stops, and also when a new OB gets loaded. Remark that this requires the OBS and TPL dictionaries to be loaded into logManager - this is not done by bob itself. On top of the ops-logs generated automatically by bob at particular occasions, template scripts themselves may also create ops-logs - see section 2.7.2.
2.7 RULES, TIPS AND TRICKS FOR TEMPLATE SCRIPTS
As all the other files and formats involved in the execution of OBs, template scripts need to comply with a certain set of rules which are outlined in documents [1] and [4]. Based on these assumptions, the search for a template script that gets called for a certain template takes place as follows:
1. The keyword TPL.ID in the OBD allows to determine the name of the template signature file. The latter needs to have a .tsf extension. This template signature file is then searched for in a number of directories under $INS_ROOT. Remark that the setting of the keyword TPL.MODE in the OBD can influence this search - see [4].
2. The template signature file must contain the keyword TPL.PRESEQ. This keyword contains the filename of the template script, excluding the pathname, and with or without the .seq extension. Remark that the template script needs to be stored in a file which has a .seq extension. Although most of the times the basename contained in TPL.PRESEQ will be the same as the one from TPL.ID, this is not mandatory. The label of the template shown on BOB's canvas will contain both if they are different.
3. The script file is located searching a set of directories based on the environment variable INS_ROOT. Again, the value of TPL.MODE has an impact on the paths searched.
4. This script file is sourced in before a template starts its execution; the basename of that file is assumed to be identical to the procedure-name contained in it.
2.7.1 Template calling procedure / access to variables
Templates must be written as Tcl-procedures. There are no arguments passed to them4; BOB takes care that these procedures have automatically access to the keyword-variables as local arrays, as explained below.
The information contained in the Observation Block Description in so-called Parameter File Format is parsed by BOB, and put into arrays for easy access. E.g. the OBD-line
DET.WIN1.BINX "1";
will result in a variable DET(WIN1.BINX) with value 1.
These arrays are automatically made accessible to the template script5 (but not its library procedures it uses - see below). Remark that only the arrays for which keywords are within this OB defined for the current template are made accessible, plus the DPR array. The TPL array contains the TPL parameters set by the Observation Block Description plus the ones defined in the signature file (e.g. TPL(REFSUP) for the instrument reference setup file).The following rules/guidelines should be observed when accessing these arrays:
1. While template scripts have automatic access to these arrays, library procedures must use the convenience procedure seeBobVars (see section 2.7.2 item 10.) before dealing with these arrays as local variables.
2. Keywords specified in the OBD (as received from OH or as read from a disk-file) and/or the template signature file should be considered strictly read-only, i.e. the template script should not write into the corresponding keyword elements, nor should it unset any of these keyword elements.
BOB sets traces on all these category-arrays when in engineering mode (see 2.10). This permits to check if all keywords declared in the OBD and/or TSF are effectively used by the template script, and do not get overwritten or unset. Remark that the category-arrays created by BOB are only guaranteed to exist during template execution, i.e. one cannot keep a reference to such an array after the template script finishes, in particular indirect references created via upvar commands.
By means of the mentioned tracing mechanism, BOB will report within the Template-log window the following "infractions" against the above rules:
3. Keyword-arrays that have been made accessible via an own, internal upvar scheme (i.e. not using seeBobVars), whereby the original category array-names were linked to variables of a different name.
When the tplInternals flag is set (see sections 2.3 and 2.11), there will be additionally the following messages, if applicable:
1. Warning that keywords are linked from a different namespace. Although not forbidden, this requires imperatively that these links are removed before the template finishes - otherwise there will be persistent links to variables of deleted objects.
Although BOB can in principle ensure that keywords are read-only, it will not enforce this (for backward compatibility reasons); apart from logging messages as described above, BOB will continue as normal.
It is mandatory for every template script that contains some hardcoded exposures (i.e. the amount of which is unknown to BOB), to set the total number of exposures in the variable TPL(NEXP), before starting the first one, and to adjust it during the execution as this value gets affected by runtime conditions. E.g. for a template which loops SEQ(NEXPO) times over an exposure setup and execution, and has three more hardcoded exposures, we need
set TPL(NEXP) [expr $SEQ(NEXPO)+ 3]
This is for BOB the only way to know how many exposures there will be in total. BOB uses this value to show it in the message next to the OB-identifier ("(exposure X of nnn)") and in the Template Log when it starts executing an exposure ("Starting exposure X of nnn"). By default, BOB assumes there is only one exposure in a template script.2.7.2 Communication and logging
There are basically 10 convenience-procedures available from BOB:
This has to be used for whatever communication with OS. A direct call via seq_msgSendCommand is not allowed. Remark that BOB tries to filter out three particular command-names, as they require and receive a special treatment:
a. START
When BOB sees this command, it will - before forwarding this START to OS - insert a SETUP command to pass on all OBS and TPL keywords that should be written into the FITS header of each exposure. One of these keywords is TPL.EXPNO, i.e. the sequential number of this exposure within the template (with the counter starting from 1).
b. START_NO_OS
If for particular applications (like engineering) the above mentioned insertion of an additional SETUP command would be disturbing, the START_NO_OS command should be used instead of START.
A typical scenario for this is when BOB is used in engineering mode straight with DCS. Of course DCS does not have the OBS and TPL keywords in its dictionary, and consequently would complain if it receives them. Using the START_NO_OS instead, there is no such problem. One could actually say that BOB together with the proper OBs and templates behave in this case (to some extent) as a replacement for OS.
c. WAIT
This command is simply filtered to detect when to display messages in BOB that the current exposure was finished (i.e. after the final reply to WAIT came in).
This allows to log some messages in the template text-box at the lower part of the BOB GUI. Remark that this will also be recorded into the automatic log (stored in $VLTDATA/tmp/bob_<procNameOS>.log), like all other messages that end up in the Template Log-area.
A procedure to check if BOB's ABORT button was pressed. It will automatically generate an "ACK ABORT" error message if the abort flag was set, otherwise it returns with an empty string
A procedure which allows to set a variable to a certain value, so that it can be picked up by another template in the same OB, using the companion procedure getResult (see below). Remark that all such variables are erased when the first template of an OB starts it execution. In other words, with this procedure result-passing from one template to another is only possible within a single OB.
To set the script to be evaluated upon termination of the current template, thereby overriding - for this template only - the setting in the configuration panel of the default template call-back script.
To send the OBS and DPR keywords, plus some TPL keywords, to OS. This is normally done automatically by bob when a "START" command is given within the template; however, there are cases where data can be produced without starting an exposure, i.e. without a START command. The "sendObsKeys" procedure provides for these cases a means to still have the proper OBS-, DPR- and TPL-keywords recorded into the FITS header. This proc should only be called once per data file, and only if there is no START command involved.
To indicate that the entire OB should be finished immediately after the current template terminates, i.e. that the remaining templates should be skipped. Optionally, the OB termination status sent to OH (default: TERMINATED) can be indicated as an argument to this procedure. Of course, this needs to be consistent with what OH can expect for this instrument, i.e. with what is written in the instrument summary file.
To send an event to OH, signalling the readiness of some PAF-files. OH can after receiving this event decide to retrieve these files at a later point in time. Remark that this event will always be sent to OH, independent from BOB's configuration setting for the sending of the automatically generated OB/TPL status events.
This makes a series of variables, created/owned by BOB, accessible as local variables to the invoking template library procedure. Currently, the only variables are the category arrays, as described in section 2.7.1. Remark that these variables are made automatically accessible at the level of the template script itself, so calling seeBobVars at the level of the template script itself will lead to errors, complaining about already existing variables.
This procedure can also take the optional argument "-localcopy <categories>", in which case the list of <categories> will appear as local arrays.
This procedure can be called from any namespace, thereby making these BOB-vars available in that namespace; however, if called in a different namespace, the template script will have to ensure that these links do not exist beyond the execution of the template script (to avoid the existence of references to variables of deleted objects), e.g. by deleting this namespace; this problem does not exist if using local variables within a procedure, as these are non-persistent.
The technical details about these ten procedures and how to use them (i.e. the number and meaning of their argument(s)) are given in the bobTPL manpage (see chapter 4, under the heading CLASS PROCEDURES.
If a parameter-value to be sent to OS is a string containing quotes, it has to be passed on to sendCmd with the quotes well protected, by either surrounding them with braces or escaping them with backslashes. Examples:
sendCmd $timeout SETUP -expoId $id -function CAT.PAR {"my value"}
or sendCmd $timeout SETUP -expoId $id -function CAT.PAR \"my value\"
The above list of procedures does not consider "basic" Sequencer commands or library procedures which are available to any Sequencer script, and which may be very useful for logging purposes (e.g. seq_logFitsAction(n) - see [2]).
2.7.3 Aborting a running template script
As BOB is not fully aware about the detailed status of the execution of a template and its exposures, BOB cannot decide when to abort an exposure after the "Abort" button has been pressed. For this purpose, a variable is accessible within the template, flagging the pressing of this abort button. This variable is accessible only after issuing the following command in the template script:
The template script should then at appropriate times test this localAbortFlag (0 means no abort, 1 is abort pending), and take appropriate action if necessary. When it has finally take action, it should also return an error as follows:
Alternatively template script can use the checkAbortFlag convenience procedure to deal with the abort-flag (see item 3. in section 2.7.2). As this method is for template developers far easier to use and less error prone, it is clear that this is the preferred way to test the abort-flag. The above mentioned direct use of the abort-flag is still supported, but only for backward-compatibility reasons.
Remark that BOB allows to configure the set of commands that should no longer be sent to OS once the abort flag has been raised. This can indeed speed-up the abortion of the template script. At the same time, it allows to still send some critical commands that always should be sent to guarantee a graceful termination (leaving the instrument/telescope in a safe state).
2.7.4 Return values
Template scripts should return the following way, with proper values:
· return "<RA> <Dec>": for successfully terminated acquisition templates, with <RA> and <Dec> the coordinates of the acquired object (both in degrees, as a float number, identical to how the primary FITS keywords RA and DEC are written)
· return {}: if all went OK, for normal templates; acquisition templates should return a non-empty string, containing the coordinates of the acquired object.
· error "message": if there is some error within the template, or an error returned from the OS-level (e.g. ABORT). The setting of the ABORT-flag within BOB should be acknowledged by an error "ACK ABORT" message at the first opportunity.
If a template returns an error, BOB will try to pop-up the CCS error display, to allow error-stack browsing, provided the user-level is configured to "advanced". The error display can under any circumstance be forced to pop-up, via the Errors menu item.
2.7.5 Library scripts
Application/instrument specific Tcl libraries can be declared via the configuration panel (see 2.3), provided they have been built according to the VLT software standards, i.e. using vltMake. This means template scripts can be kept relatively simply, putting the more complicated and frequently used sections into library procedures by default unknown to BOB.
Remark however that these library procedures will of course be called from bob's template class namespace (i.e. ::BobTPL), while the template script is executed; to avoid namespaces problems, in particular when these procedures try to call on their turn public template class procedures like sendCmd, it is best to declare them within the ::BobTPL namespace. Example:
2.7.6 Search paths
BOB needs to access a series of auxiliary files, most notably the template scripts and signature files. The locations where BOB scans through to find them, are listed in this section.
2.7.6.1 Template signature files
An OBD can include for every template the TPL.MODE keyword, which is in fact extracted from the template signature file at the time an OBD is constructed. If it does, i.e. if the instrument mode is defined, the search path will be:
In case the environment variable INS_USER was not set, $INS_USER will be replaced by SYSTEM. Paths 2. and 4. are there for backward compatibility purposes only: users are encouraged to put their template signature files in either path 1. or 3.
2.7.6.2 Template scripts
A template signature file can contain the filename of the associated template script in the variable TPL.PRESEQ. If this field is blank, the name of the sequencer script will be derived from the TPL.ID. Also, the signature file should include the TPL.MODE keyword, describing what the instrument mode for this template is. The search path for the template script will be:
In case the environment variable INS_USER was not set, $INS_USER will be replaced by SYSTEM. Paths 2. and 4. are there for backward compatibility purposes only: users are encouraged to put their template script files in either path 1. or 3.
2.7.6.3 Sound files
2.7.6.4 Template library scripts
These are directories named as lib<name>.tcl, which contain a set of Tcl-procedures and a corresponding tclIndex file, as generated by the VLT Makefile (see sections 2.3 and 2.7.5). A list of such libraries can be specified via BOB's configuration panel. Remark however that in this entry field only <name> must be given, excluding the lib-prefix and .tcl-extension. In this case, the corresponding Tcl-library directory lib<name>.tcl will be searched for in:
2.8 SIMULATION
For the purposes of the implementation of template scripts, it is useful to have some simulation, resulting on the one hand in BOB being independent from the other hard- and software, and on the other hand in a predictable, prompt reaction when a command is sent. There are actually two levels of simulation provided by BOB, as described below.
2.8.1 Internal simulation
This level is set by setting the "Simulating TPL communication" to true (see Configuration - section 2.3). In this case the template will no longer communicate with OS. Instead, BOB will short-circuit this communication in the sendCmd procedure, and normally return after a certain delay with a reply equal to "OK SIM".
This delay is also configurable: a first group of commands can have a certain delay, and all the other commands get a different delay. Typically the commands that reflect the execution of an exposure would have a somewhat longer delay (set in first group), and most other commands can get a much shorter one. See also section 2.3.
If any of these delays is set to a value larger than the time-out value the template passes on to sendCmd, a time-out error will occur. In this case the error reply will contain "simulated reply timeout".
2.8.2 External simulation
This involves two external processes: simOS and simOH. This level of simulation is intended for development purposes of BOB itself, and is normally not needed by template developers. See [3] for more details.
2.9 STATUS RETURNED
If in the configuration panel both the process name and environment name of the OH-partner are filled in, BOB will return information to this partner, telling in what state the Observation Block and/or Template are. The following events are fed back:
2.9.1 Observation Block Events
<OBSid> yyyy-mm-ddThh:mm:ss <status> <add_params>
where <OBSid> is the observation block identifier; <status> is one of the following:
· ABORTED; if the abortion is due to a user-intervention via BOB's GUI, <add_params> is a string containing a description of the motive, as entered in the abort dialogue-box. If the abortion is due to an error returned by the template script, <add_params> will contain "template error: <errorText>".
· MUSTREPEAT followed by a message why the OB needs to be repeated (BOB's Repeat button was pressed).
2.9.2 Template Events
<OBSid> <TPLid> yyyy-mm-ddThh:mm:ss <status> <add_params>
where <OBSid> and <TPLid> are the observation block resp. template identifier; <status> is one of the following:
· ABORTED; if the abortion is due to a user-intervention via BOB's GUI, <add_params> is a string containing a description of the motive, as entered in the abort dialogue-box. If the abortion is due to an error returned by the template script, <add_params> will contain "template error: <errorText>".
· TERMINATED; for acquisition templates this is followed by the coordinates (right ascension and declination, in that order) of the acquired object, (both in degrees, as a float number, identical to how the primary FITS keywords RA and DEC are written).
2.10 ENGINEERING INTERFACE
BOB's menubar contains an item to change the interface from Observation (default) to Engineering. In the latter mode, one still has access to the normal buttons, but there is more functionality available: one can edit the OB and the template parameters, partially in a graphical cut-and-paste way (see
Figure 5). The function to execute is selected by clicking one of the small buttons below the menubar. The OB, template or section of parameters on which this action will be performed is selected with the middle mouse button, and this area is marked by a shaded rectangle.
If parameter-editing is on, clicking this middle mouse button on a single parameter will allow to edit the value straight on the canvas, via a standard entry widget with the usual key-bindings. Pressing the <Enter> key is required to accept the value, while <Esc> will cancel this editing. If on the other hand the middle mouse button is clicked over an OB or template label, or on a keyword-category such as TEL, a new mega-widget will pop up allowing to modify the entire set of corresponding values (see Figure 6)
. When the edited values are accepted, this section of the OBD will again be verified using the same procedures as for a newly read-in OBD, labels on the canvas will get updated, etc.
The selection of this Engineering interface will be password protected once the Trusted mode option has been disabled. This is to provide some basic level of security against accidental modification of OB parameters by people who are not (yet) very comfortable with this engineering interface; such parameter modification, in particular for science OBs at the telescope, can invalidate the entire data-flow process for this OB. On the other hand, engineers building templates and exercising their software and instrument may find the engineering interface a useful tool, providing a convenient and direct means to edit an OB.
The password can also be given on the commandline when BOB is started up (see 2.2). This password is requested every time a switch is made from Observing mode to Engineering mode, once the "Trusted mode" under the Interface menu has been disabled (it is enabled by default). A newly installed BOB will have an empty password, which should after installation be modified to a proper value, using the "Change passwd.." menu-item.
Under this interface, the template log can contain error messages about some keywords which have not been touched by the template script, although they are defined in the Observation Block Description and/or the Template Signature File, so they should be sent to OS. This is of course to be seen as an error in the template script.
More explanation about this Engineering interface can be found in [3].
2.11 PROGRAMMATIC ACCCESS
The initial implementation of BOB considered its interactive use as a GUI only. It became quickly clear however that there is a definite interest in programmatic access to BOB's functionality, be it by sending it CCS messages, or alternatively by starting it up as a shell passing it a script to execute, or even running it interactively in prompt-mode. Consequently, there was first a (somewhat limited) shell implementation of BOB, called bobWish, followed by enabling the sending of commands (e.g. to start an OB) via CCS to the standard BOB, and the addition of the <scriptFile> run-string parameter (see also section 2.2).
This means that alternatively to using the standard BOB GUI, commands can be given in a typed, interactive form or grouped together in a script, using a set of specific bob(Wish)-commands. This enables the creation of different applications with a BOB-like behaviour (based on these bob(Wish)-commands), or even to execute OBs via modem connections without having to deal with the X-traffic generated by BOB's GUI - as explained below. A useful and typical application of bob(Wish) is a bob(Wish)-script dealing with the automatic execution of one or more OBs as part of a non-interactive maintenance procedure.
In the following section a list of publicly available commands are listed, giving access to most of BOB's settings. This is the only supported API for retrieving or modifying these settings.
2.11.1 Commands
The following list contains the commands available at script level from bob and bobWish; calling these procedures has the same effect as interactively executing the corresponding GUI-function (like e.g. pressing the "Start OB" button or calling the configuration panel):
bobProcNameOH, bobProcNameOHlist, bobEnvNameOS, bobEnvNameOSlist, bobEnvNameOH, bobEnvNameOHlist, bobProcNameOS, bobProcNameOSlist, bobUserLevel, bobRunAll, bobAutoUnfold, bobGetNext, bobAutoCreateTpl, tplEvents, tplSim, tplVerbose, tplInternals, tplSimList, tplSpeDelay, tplDefDelay, tplSkipList, tplCallBack, bobCallBack, bobCfgCallback, tplLibList, bobCfgFile, bobPrintCmd, bobPlugin, bobPluginFlag, bobTitleFont, bobCanvasFont, bobLogFont, bobDialogFont, bobEditorFont, bobSoundOn, bobSoundVolume, bobSoundHeadphones, bobSoundSpeaker, bobSoundLineOut, bobErrorSound, bobWarningSound, bobBreakpointSound, bobTplSound, bobObSound, bobWaitOptions
These commands correspond with the fields in BOB's configuration and preferences panel (see 2.3 resp. 2.4). When given without arguments, they return the current setting. They can also be given a single argument, in which case this value will be set into the corresponding configuration variable.
Remark that modifying a configuration setting can trigger a call-back (see section 2.3). The name of the configuration variable that will be passed to this call-back corresponds to the commandname used to retrieve or set this parameter, e.g. using `bobProcNameOH myScheduler' to modify the OH process name will trigger the configuration call-back with additional argument `bobProcNameOH'.
bobStart, bobPause, bobContinue, bobAbort, bobRepeat, bobReset, bobNextObsBlocks, bobSave, bobSaveAs, bobSoundOn, bobPrint, bobSnapshot, bobInfo, bobSaveConfig, bobSaveConfigAs
Most of these commands correspond to GUI buttons, and do not require any arguments. There are three notorious exceptions to the latter rule. First the bobNextObsBlocks command, which can have as arguments either an integer number (for the number of OBs to download from OH) or the word "file" optionally followed by a filename (to avoid the file-selection box to pop-up). Second resp. third exception are the bobSaveAs and bobSaveConfigAs commands, which can have a filename as argument (also to avoid that a file-selection window pops up).
- bobVersion: version number of bob. Remark that this is not necessarily a decimal number, as it is the version number manipulated by the cmm-tool (i.e. when dealing with a branched off version, it will be of the form i.j.k.l)
- interface: enumerator, showing the type of selected interface; 0 = Observation mode, 1 = Engineering mode
- interpreter: gives the Tcl-interpreter name, ie. bob or bobWish; this permits scripts to distinguish between a graphical and non-graphical interface
- obdFile: filename (absolute path) of the loaded technical OB, or empty if the OB was retrieved from OH.
These commands are all declared in the namespace ::bob. To have them available in the global namespace, one should call the procedure bobMakeUifProcsGlobal. Remark however that this is not recommended: to avoid name-clashes and avoid pollution of namespaces (in particular the global one), it is better to use the fully qualified commandnames, with the ::bob:: prefix.
2.11.2 bobWish
All runstring parameters which can be passed to BOB (see section 2.2) are also accepted by bobWish; bobWish retrieves its configuration the same way as BOB does (i.e. the file ~/.bobrc, or the file specified with the -configFile option), and these settings can also be modified via commands. An overview of the special bobWish-commands are given at the start-up of an interactive run (try bobWish at your terminal to see, or have a look at the bobWish manpage in section 4.2).
The command bobSetup within bobWish shows the list of modifiable parameters (listed with the command name to change them). Remark that bobWish does not provide an engineering mode, nor any command related to this mode: as the purpose is exactly to avoid the use of GUIs and their associated X-traffic, this is considered beyond the scope of bobWish.
Using the bob(Wish)-commands listed in section 2.11.1, one can easily write a script to load and execute an OB. These scripts should be terminated with an exit command.
One important caveat: although during normal execution you will not see GUIs on any screen, the use of bobWish requires the definition of the environment variable DISPLAY to a sensible value, i.e. to an X-server for which you have authorization to connect (typically your X-terminal is OK, if you are already logged into it). Remark that for some error messages a dialog window will still pop-up, and some commands, depending on the options given, may require input widgets, like a file selection box.
Once the DISPLAY environment variable is set, proceed as follows for a programmatic background session from a remote site:
· theFileNameForOutput is the file to send messages to that would normally appear on the screen during an interactive session
· & is needed to make the thing run in the background and not having it abort when logging off before the script is finished.
Remark that by default the bobStart and bobContinue commands will make an OB run in the background. In other words, control is returned to your terminal or script immediately after this command has been accepted, and actually before the OB is running. This of course permits full asynchronous control of the OB's execution (e.g. it permits to give the bobAbort command before the OB finishes its execution), but on the other hand requires a mechanism to check and verify the state of execution, e.g. within a script. WIthout such synchronization one may give a subsequent command too early, particularly when running non-interactively, via a script. One of these mechanisms is the OB-termination call-back (see section 2.3). For non-interactive use however, this asynchronous behaviour is normally not required. For that reason, the bobStart and bobContinue have a -foreground option. If this option is given, these commands will only return control as the OB finishes.
2.12 MOBS AND GENERIC TEMPLATES
2.12.1 What MOBS and Generic Templates are
MOBS (Multiple Observations Software) has been defined as a common part of the VLT INS software (see [4]). Its was initially presented as a separate software module, interacting with the OS of each instrument. While the task of OS is to coordinate and supervise the execution of a single exposure, MOBS's task was to offer an "easy" way to define, modify and execute a sequence of such exposures. The flexibility and "intelligence" offered by relatively complicated templates is many times not required at all, in particular if the goal is to execute unconditionally a set of exposures, simply one after the other, changing a couple of parameters in between. In ESO's pre-VLT software this feature was offered in the form of so-called sequence tables, where each row in the table contained the definition of a single exposure, and the columns contained the values for specific parameters. The usefulness and appreciation of this feature was translated into a requirement towards the VLT software to offer something similarly simple and powerful.
Templates on the other hand are of course very powerful tools to deal with a certain predefined sequence of commands required to execute one or more exposures. But their scope is limited in the sense that they are designed for very specific modes of observation. To overcome this limitation, the ICD between VCS and OH (see [1]) mentions so-called generic templates. This sort of templates has been inspired by the specification of MOBS: it must be possible to specify/modify any parameter within a given mode of observation. [1] refers to MOBS as the tool to achieve this, by means of a table editor as described above. Remark however that the use of generic templates imposes certain restrictions on the Data Flow: as for a generic template any instrument/telescope parameter can be specified, it is in practice impossible to classify a priori such exposures and to apply e.g. a pre-defined reduction recipe on the resulting images.
In the implementation of MOBS within BOB there is of course a clear mapping between the MOBS-table and the generic templates: a MOBS Observation Block corresponds to a MOBS table, and each line of the table corresponds with a generic template. Through this mapping the features already implemented in BOB can be exported to the execution of a MOBS-table (alias a set of generic templates), e.g.:
Of course the availability of these and other features has been one of the prime driving factors to integrate the MOBS concepts into BOB.
2.12.2 The MOBS Engineering Interface Editor
The engineering interface editor for a MOBS-table differs substantially from the one for "normal" templates (see section 2.10). This is because a MOBS Observation Block can (largely) be presented by a table, and a table-widget is much more compact and surveyable than a set of pages in notebook.
BOB will pop up this MOBS Editor
(see Figure 7) instead of the standard one if the following conditions are met:
By extension of the concept of generic templates, we will call further on such an OB a generic OB or a MOBS-OB. Such an OB is dealt with by BOB in a generic fashion, independent of the instrument.
The MOBS-OB editor contains 2 distinct parts, and the top one is already familiar: it is the tab-notebook style widget as used for editing "normal" templates (see section 2.10). The parameter which can be edited in this part are:
Below this is a table widget, with at as many lines as the MOBS-OB contains generic templates, complemented with a few empty (available) lines. The table has a minimum of 6 columns, in fixed positions on the left of the table. These columns are, from left to right:
· A loop counter. It tells the generic template script how many times the exposure defined on this line needs to be repeated, and its default value is 1. Remark that the full SETUP command, including reference to the various setup-files, is normally sent only once, before the first exposure starts. Subsequent exposures will be preceded by a SETUP command without any arguments, in order to retrieve an exposure-id. This standard behaviour can be modified by using a negative value for the loop counter; in this case, the full SETUP command will be repeated for every exposure.
· The timeout value in seconds for the setup command to OS which the generic template script will construct from the collection of all parameters on this line. If for a line this field is left blank, the timeout value taken by the generic template script will be the one previously defined within the same OB (possibly also in the acquisition template - see section 2.12.4 for an example). If no such parameter has been defined, a default of 30 seconds is applied.
· The name of the reference setup file for this observation. This will determine the list of parameters which can appear as additional columns (see further).
The existence of any other columns beyond these six, and their meaning, depends on the contents of the Observation Block Description. The MOBS-OB editor will show every keyword it has found in this description as a separate column. It is possible to add new columns, or remove some already defined by pressing the Columns action button, and selecting the set of additional keywords to display. When the OK button is pressed, only the keywords and values of the columns displayed are saved, i.e. not the ones of the columns which were removed.
2.12.3 The Generic Template Script
The execution of a MOBS-OB is based on the generic template script. This script is not instrument specific, and is therefore picked up form a central place rather than from a directory under $INS_ROOT. It is supplied and installed together with its template signature file as part of the bob software module. Once bob was installed, the generic template script is accessible.
The tasks executed by the generic template script are as follows (in the order as listed):
· determine the name of the reference setup file. If for this generic template no reference setup file was given, use the one defined before within the same OB.
· construct a SETUP command, including the name of the reference and partial setup files, and the other keyword-value pairs which are part of the observation block description for this template.
· send this SETUP command to OS. For this purpose the sendCmd is used (see section 2.7.2), with a timeout as calculated before. OS will return an exposure-Id.
· Use this expoId to WAIT for the exposure to finish - this time with a sufficiently large timeout, and return
2.12.4 An example acquisition template script for MOBS
The first template of a MOBS-OB can be either an acquisition template or a generic template. One possibility is to define within such acquisition template a mode of observation, i.e. a reference setup file, and not worry about it any further for the rest of the OB. On top of that, we could at that stage already define a default value for the timeout of the SETUP command.
The contents of a template which does nothing more than that is given below. This template, called MMS, has 2 parameters of category SEQ, namely SEQ.SETUP.FILE and SEQ.SETUP.TIMEOUT. The corresponding template signature file and script are both installed under $VLTROOT/templates/forBOB/mobs/ as part of the installation of the bob software module.
# Example acquisition template script
setResult refSetupFile $SEQ(SETUP.FILE)
setResult timeout $SEQ(SETUP.TIMEOUT)
2.13 TECHNICAL TEMPLATES
Up to this point we have considered the use of BOB as a tool to execute "real" OBs (imported from the Data Flow world). OBs contain templates, and each of these templates contain instructions for the OS process of the instrument it is controlling. This communication with OS is taken care of by BOB.
BOB is actually not interested in knowing whether the OS-process it is talking to is really an OS, or any other process that responds properly to the commands it receives. This means we can have templates designed e.g. to talk to ICS, combine them together and declare their arguments in an OBD, and have them executed by BOB. Of course the rules imposed by BOB for use of templates, and template signature files, for dealing with hierarchical keywords, return values etc. must be respected (see also section 2.7). As long as this is the case, one can benefit from the features offered by BOB also for tasks which in reality have very little to do with Data Flow and "real" OBs. For that reason, this type of templates is qualified as technical templates.
As an example, let's assume we want to send a single SETVAL command to a process. The parameter of this command is supposedly a single integer, in the range 100-1000, and we want to pass this parameter to the template as an argument. We can easily create a template signature file6 for that purpose:
PAF.HDR.START ; # Marks start of header
# The next set of keywords (up to TPL.RESOURCES) are mandatory.
# The assigned values need to be adjusted for each signature file.
TPL.INSTRUM "TEST"; # This is a template for WORKSHOP
TPL.MODE ""; # Not applicable for WORKSHOP
TPL.VERSION "0.1 alpha"; # (any string)
TPL.REFSUP ""; # Reference setup file
TPL.PRESEQ "waTemplate.seq"; # Sequencer script
TPL.TYPE "test"; # science, calib, ...
TPL.EXECTIME "computed"; # can be "computed" or a number
# Here starts the description of the various arguments of the
# template script. In this particular case, we have only one
# parameter. We need to give its type, range and default value.
The above signature file shows there is a unique argument for the script, and it is defined with the name VALUE in the SEQ category. On top of that, it will make BOB look for a corresponding template script called waTemplate.seq (see value assigned to the keyword TPL.PRESEQ). So to keep things simple, the template signature file can be named waTemplate.tsf (the template script and signature files share the same basename). The template script waTemplate.seq could look as follows:
# Example Technical Template script
checkAbortFlag; # Check if bob's ABORT button has been pressed
# Make it look like we're talking about real OBs, so we don't
# get any complaints from bob (in engineering mode) about
set TPL(REFSUP); set TPL(EXPNO) 1
# Timeout value (ms) for replies on commands to partner process
tplLog "About to send SETVAL command ..."
set reply [sendCmd $timeout "SETVAL $SEQ(VALUE)"]
We can put this technical template into an OBD. In fact, the example below calls this template twice, with different arguments:
# Standard parameter file header
PAF.HDR.START ; # Marks start of header
PAF.TYPE "OB Description"; # Type of parfile
PAF.CRTE.NAME "BOB"; # Broker for OBs
PAF.CRTE.DAYTIM "1999-04-20T11:54:34"; # Date+time of creation
PAF.LCHG.DAYTIM "1999-04-20T11:54:34"; # Date+time of last change
PAF.CHCK.CHECKSUM ""; # Unused
PAF.HDR.END ; # Marks end of header
# Observation Block description follows; first come the keywords
# belonging to the OB itself (up to OBS.PROG.ID).
TPL.NAME "Workshop demo template"
TPL.NAME "Workshop demo template"
The only remaining task now is to configure BOB properly with its partner data: the name under which this partner process registered itself with CCS, and its environment name need to be inserted into BOB's configuration panel, in the entry fields that corresponds to a "normal" OS (see section 2.3). After this has been done, we can activate the usual features of BOB:
· modify the value assigned to SEQ.VALUE within the Engineering Interface (see section 2.10); in other words, this permits to edit the parameter of the SETVAL command.
2.14 PARAMFILE KEYWORDS
There has been a special keyword-type defined, called paramfile. This allows keywords to absorb the contents of a PAF-file. I.e. the value of such keyword will be ASCII text, taken from a disk file. When bob gets such a parameter as part of an OB, it will store this text in a file with name as given by the text itself: the basename is taken from the included PAF.NAME keyword, while the path is taken from the mandatory TPL.FILE.DIRNAME keyword. If the latter is an empty string, the path $INS_ROOT/INS_USER/MISC will be used. For security reasons, storage of these PAF-files will only happen if the resulting path points to a directory under $INS_ROOT.
Remark that after storing this file to disk, bob will put the absolute pathname of this stored PAF-file into the keyword, so it becomes a relatively short string to display. This filename, rather than the complete text, can then be edited via the engineering interface. When the OBD is saved, the file pointed to will be read-in, and the complete ASCII text will be saved into the .obd file.
Bob will by default remove files stored by this mechanism, when the corresponding template gets deleted (e.g. when a new OB is loaded). In order to override this behaviour, one needs to set the boolean keyword TPL.FILE.KEEP in the paramfile-text.
Detailed explanation about the paramfile keyword-type can be found in [1].
2.15 SNAPSHOTS
The bottom toolbar button in the main panel of BOB allows to store a snapshot of the information involving BOB. When this button is pressed the following sequence of actions takes place:
· Make a copy of /vltdata/tmp/logFile and place it in the above directory; same for the most recent previous logFile (if any).
· Create a text file (name: bobSnapshot) containing info about the currently executing OB/template/exposure, and the template logs of the current OB.
· Add to this file the current Tcl error message stack, the complete CCS error stack, the Tcl errorInfo contents at the last template script problem.
This function can also be activated via the ::bob::bobSnapshot command (see section 2.11).
1The search path also include paths which depend on the setting of the INS_USER and the instrument mode, combined with INS_ROOT. The file search algorithm used by BOB is fully compliant with the INS Common Software Specification.
3This is an engineering mode, which is not to be used as a standard observation practise, as it actually renders the OB useless for further dataflow-pipeline processing. For that reason, this feature may not be globally available in future releases of BOB.
4BOB-versions up to 1.108 required 2 arguments, namely first the list of category-names and second a reserved argument. It also required that each template script takes care itself of making these category-arrays (which are passed by reference) locally accessible, by means of upvar instructions. Newer versions of BOB still honour this scheme, for backward-compatibility reasons, although its use is no longer recommended.
6see document [1] for more detailed info on the syntax, structure and content of template signature files.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|
