| |
|
|
|
4 REFERENCE
4.1 ERROR MESSAGES
During the operation of bob, while it analyses or tries to execute an OB and its templates, there are of course plenty of things which can go wrong: illegal syntax, values out of range, referenced files not found, etc. In the following sections you will find a list of error messages which can pop up in the form of dialogue boxes or logs; they are grouped according to the activity that is going on. Within each activity, the order is alphabetical (case insensitive).
4.1.1 OB/Template creation
Remark that some of these messages can also appear after the OB/template is edited via bob's engineering mode editor, as some of the "creation checks" are then passed through again.
As the message says. Either the file pointed to by TPL.PRESEQ was not found, or TPL.PRESEQ was not defined and <tplId>.seq could not be found
the template signature file is searched for, based on the <tplId> name (i.e. <tplId>.tsf), eventually taking the INS.MODE into account as defined in the OB. Apparently this file is not found. It is searched for under $INS_ROOT/<insMode>/TEMPLATES/TSF and $INS_ROOT/COMMON/TEMPLATES/TSF.
As the message says. A search for <tplId>.seq will be undertaken, although in principle TPL.PRESEQ should be defined.
Correct the OB and/or TSF, reload the OB, or edit this <key> via bob's engineering interface editor.
As the message says. Remark that this is for a <key> which has a NODEFAULT value for the DEFAULT entry in its template signature file.
Correct the OB and/or TSF, reload the OB, or edit this <key> via bob's engineering interface editor.
As the message says. Remark that this is for a <key> which has a NODEFAULT value for the DEFAULT entry in its template signature file.
As the message says. This is for a <key> of type "filename", which should match any of the the patterns defined in the .RANGE entry of the tsf.
There seems to be an inconsistency between what the OBD and <tsf> files contain with respect to <key>.
This message is only shown during a first pass, i.e. it will not show up if such a <key> is edited via bob's engineering mode editor.
This is for a keyword which has a default value defined in the <tsf>. This will warn beginners about this "automatic" assignment of values. Normally OBs should include this keyword, as the .DEFAULT entry in the <tsf> serves for P2PP to pick up the value and put it in the OB. This message is only shown during a first pass, i.e. it will not show up if such a <key> is edited via bob's engineering mode editor.
This is about a key with a .NODEFAULT entry in <tsf>. Such keys should have a proper definition in the OB. This is done properly by P2PP. So we're dealing here with a local .OBD file. This message is only shown during a first pass, i.e. it will not show up if such a <key> is edited via bob's engineering mode editor.
the <tplId> is passed as part of the OB. It should be in the format of <context>/<name>/<version>, or <name> (see ESO-VLT-DIC.TPL).
during population of the template tree, there were some problems with keywords of a particular <category>
4.1.2 OB/Template editing
Remark that several messages which are listed in 4.1.1 can also appear after OB/Template editing, as most of the verification steps (and corresponding code) are identical.
This message is not shown during a first pass, i.e. it will show up only if such a <key> is edited via bob's engineering mode editor.
4.1.3 OB execution
Apparently the "abort" button got pressed while no OB was running/paused. This should in principle not be possible.
Apparently the "continue" button got pressed while no OB was paused. This should in principle not be possible.
Apparently the "pause" button got pressed while no OB was running. This should in principle not be possible.
The OB has been aborted, due to the fact that OS has reported back an error or abort during the execution of <tplId>.
The OB has been aborted, due an error in the template script. This is most likely a bug in the template script (as it should normally be designed to trap error conditions itself, and either recover from these errors, or pass specific error conditions back to the OB).
The OB has been aborted, due to the error indicated in the message. Actually, that this sequencer script was missing should have been signalled already when the OB was loaded.
The OB has been aborted, due to the error indicated in the message. Actually, that this template signature file was missing should have been signalled already when the OB was loaded.
This is when bob has truncated a value on the canvas (appending trailing dots to where it truncated), because this value contained too many characters. It is error-prone to try to edit such strings directly on the canvas.
This is when the "start" button gets pressed before an OB has been loaded, i.e. just after bob was started.
This is when the "start" button gets pressed before an OB has been selected, i.e. with multiple OBs loaded.
Within non-interactive use (bobWish-script), there was an attempt to abort the OB while it was not in a state to be aborted.
4.1.4 Selecting/Loading of OBs or .obd files
Occurs during an attempt to retrieve an OB from OH. The command requesting an OB was successfully sent, but the replies did not (all) come in.
Occurs during an attempt to retrieve an OB from OH. The command requesting an OB was successfully sent, but OH replied with an error.
Occurs during an attempt to retrieve an OB from OH. The command requesting an OB was successfully sent, but OH replied with an empty OB.
Occurs during the selection of an OBD file. As the message says: this <file> seems to be a link pointing (ultimately) to itself.
4.1.5 Various
Apparently the "print" button got pressed while no OB was selected, i.e. there are several OBs loaded.
The "repeat" action button was pressed, while several OBs are loaded, and none of them has been selected first.
4.2 MANPAGES
bobAbort(n), bobContinue(n), bobPause(n), bobPrint(n), bobRepeat(n), bobStart(n), bobNextObsBlocks(n), bobReset(n), bobSaveConfig(n), bobSnapshot(n)
bobAbort, bobContinue, bobPause, bobPrint, bobRepeat, bobStart,
bobNextObsBlocks, bobReset, bobSaveConfig, bobSnapshot
- several procedures used from GUI level to control bob
bobAbort
bobContinue
bobPause
bobPrint
bobRepeat
bobStart ?<contFlag>?
bobNextObsBlocks <nr> ?<file>?
bobReset
bobSaveConfig
bobSaveConfigAs ?<file>?
bobSnapshot
bobAbort: abort execution of running OB
bobContinue: equivalent to bobStart <1>
bobPause: pause execution of running OB
bobPrint: print logs of currently selected OB
bobRepeat: request a MUSTREPEAT for selected object
bobStart ?<contFlag>?: start execution of selected/paused OB; if
<contFlag> is true, then continue after pause instead of start.
Default for <contFlag> is false.
bobNextObsBlocks <nr> ?<fileName>?: request <nr> OBs from scheduler process.
if <nr> is set to the word 'file', then either pop up a file-selection
panel (if <fileName> is not set), or try to load <fileName>.
bobReset: reset objects and interface
bobSaveConfig : save the current config parameters
bobSaveConfigAs : save the current config parameters into <file>. If <file>
is not specified, bring up a file-selection box first.
bobSnapshot : dump bob-related info and logfiles to a timestamped directory.
The name of this latter directory is the return value.
These procs will retrieve the OBD of the selected OB, and prepend a proper
header to it before writing it to an .obd file. There are two forms of
basically the same function:
bobSave
saves the current OBD into a file. If the OBD was originally loaded
from a local file, it will be saved into that same file; otherwise
a file-selection window will pop up to ask for a filename.
bobSaveAs ?<file>?
saves the current OBD into <file>. Remark that if <file> is given but
does not contain an absolute path, the saving will be done with
respect to the current working directory, which can be manipulated
by any template.
If <file> is not specified, bobSaveAs will pop up a file-selection
window to select a filename.
BobPanedComboBox creates an iTk-style mega-widget, designed especially
for the needs of bob. The widget consists of the following elements:
- a listbox (top left) to show typically the names of variables
- a listbox (top right) to show typically the values of variables.
There is be a 1-to-1 correspondence between the lines of both
listboxes, i.e. the name of a variable and its value are displayed
in the same vertical position, and any positioning action in one
listbox will be followed by the same action in the other.
- an entry field (bottom left), showing e.g. the name of the variable
currently being edited
- an entry field (bottom right), showing the current value of the variable
being edited
- optionally a scrollbar (see -scrollbar option below); moving this
scrollbar will move both listboxes
These elements are organized in 2 paned windows, with a vertical
separation bar in the middle, and a sash between the two columns,
allowing to redistribute the available space between the name part (left)
and value part (right).
fraction <left> <right>: redistribute the space of the panes as indicated
by the numbers <left> and <right>. These 2 numbers must add up to
100.
getEntries : returns a list with 2 sublists, namely the list of entries
in the left resp. right listbox.
insert {<leftList> <rightList>} : append items to the end of the left and
right listboxes; the single argument consists of 2 sublists, one
for each listbox. Both sublists must have the same size
The normal class bindings for listboxes resp. entry fields apply, with the
following exceptions or modifications:
<Button1>: for listboxes and entry field
get focus, select item (for listbox and entry field)
<Button1-Motion>: for listboxes and scrollbar
drag & select
<Key-Prior> (= PageUp): for listboxes/entry fields
show previous page in listboxes
<Key-Next> (= PageDown): for listboxes/entry fields
show next page
<Key-Up> (= Arrow up): for listboxes/entry fields
select previous element in listboxes
<Key-Down> (= Arrow down): for listbox/entry field
select next element in listboxes
<Key-Home>: for listboxes/entry fields
show top of listbox resp. beginning of line
<Key-End>: for listboxes/entry fields
show end of listbox resp. end of line
<Key-Enter>: for entry fields
accept entry-field value
<Key-Escape>: for entry fields
restore entry as selected in listbox into the entry fields
<Key-Delete>: for listboxes/entry fields
delete selection
<Key-Insert>: for listboxes/entry fields
insert new element into the listboxes resp. paste copy buffer into
entry field
cursor font height width
borderWidth relief selectBackground selectForeground
See the options(n) manual entry for details on the standard options.
WIDGET-SPECIFIC OPTIONS
-helpvariable (name: helpVariable, class: Variable)
The name of the global Tcl-variable which is used to display help text
i.e. this widget will change the contents of this variable according
to the position of the cursor over its constituent widgets.
-leftlabel (name: leftLabel, class: Label)
label to display on top of the left listbox; default: empty (no label)
-leftlisthelp (name: leftListHelp, class: Help)
The short help text for the left listbox; default: empty (no help)
-leftentryhelp (name: leftEntryHelp, class: Help)
The short help text for the left entry-field; default: empty (no help)
-leftentrystate (name: leftEntryState, class: State)
Specifies the state for the left entry field. Can be "normal" (i.e.
editable), "disabled" or "readonly". Default: readonly
-listvariable (name: listVariable, class: Variable)
The name of the global Tcl-variable which contains the contents of
the 2 listboxes, if a format as returned by the getEntries method.
If the value of this variable changes, the widget will automatically
update itself to reflect the new values. Attempts to assign a
variable with an invalid list of sublists to -listvariable will cause
an error. Attempts to unset a variable in use as a -listvariable will
fail but will not generate an error.
-rightlabel (name: rightLabel, class: Label)
label to display on top of the right listbox; default: empty (no label)
-rightlisthelp (name: rightListHelp, class: Help)
The short help text for the right listbox; default: empty (no help)
-rightentryhelp (name: rightEntryHelp, class: Help)
The short help text for the right entry-field; default: empty (no help)
-rightentrystate (name: rightEntryState, class: State)
Specifies the state for the right entry field. Can be "normal" (i.e.
editable), "disabled" or "readonly". Default: normal
-scrollbar (name: scrollbar, class: Scrollbar)
Controls the presence of a vertical scrollbar to the right of the
entry-listbox. It can take the value "on", "off" or "auto". In the
latter case, the scrollbar will appear only if the listboxes contain
more elements than fit in a single view. Default: auto.
When -scrollbar is set to "auto", the need for a scrollbar is evaluated
when data are inserted in the listboxed. For the listbox sizes returned
by Tk to be correct, it is needed that this widget is being displayed.
This may not be the case if it is e.g. part of a tabnotebook page. In
this case, one should either make sure this page is displayed, or opt
for the "on" or "off" value instead of "auto".
BobTPL <obj_name>|#auto \
<rawData> <obdSource> <canvas> <scrolledText> \
<initialObsInfo> <tplNr> <args>
constructor: contruct the BobBaseObject, and do the store in array (always
done at creation time for templates). Do also a first check on
the parameters value;see [incr Tcl]
destructor: delete any saved paramfiles and proceed with base object
destruction;
configure: see [incr Tcl]
abort: request an abort of the template's execution. This will set a
variable called "abort", which can be upvar-ed by the template.
ackabort: acknowledge the abort (sendStatus)
unmark: extend 'unmark' to also clear the log of this template
editRawData ?<cats>? ?<pars>?: pops up the TPL editor. The set of parameters
to be edited depends on the 2 arguments:
<cats> : name of a single keyword-category to be edited, or the word
"all" to include all categories. Default: all
<pars> : name of specific keywords to edit (assuming <cats> is not set
to a "all"). Default: all
execute <OBSinfo> <seqNr> <statVarName>: execute the template, whereby
its sequential number in its parent OB is <seqNr>;
<OBSinfo> contains relevant info passed to the template for execution.
This method returns potentially messages and the exec-status in a
variable whose name is given in <statVarName>. Possible values for
exec-status:
-3 : MustRepeat
-2 : Paused
-1 : Aborted; returns also the string "ACK ABORT".
0 : OK - normal completion; return value will be empty
>0 : error - the return value of the method itself will contain an
error message
1: Could not find the template signature file
2: Could not find the sequencer script
3: TPL ID has illegal format
10: Error returned by the template
11: Template was aborted at OS-level
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 {} or return without value: if all went OK, for all but
acquisition templates
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 causes the template to skip
SETUP and START commands. When the template sees the abort-
flag (see above), it should return an "ACK ABORT".
getEditedData: returns the edited data in the form of "raw" template data
getExpNr: returns a list with the current exposure number and the number of
exposures (TPL(EXPNO) resp. TPL(NEXP)).
getTplId: returns TPL(ID); used to make nice tabs label wile editing an OB
getTplType: returns TPL(TYPE)
init_editRawData <pathName> ?<cats>? ?<pars>?: initializes the TPL-editor
widget <pathName> with the data as indicated by the two optional args:
<cats> : name of a single keyword-category to be edited, or the word
"all" to include all categories. Default: all
<pars> : name of specific keywords to edit (assuming <cats> is not set
to a "all"). Default: all
mark: 'select' this Tpl and display its in the corresponding text widget
mustRepeat: request a MUSTREPEAT of the template's execution; this implies
an abort (see above).
paste <object> <where> : paste <object> <where> relative to this
pause: pause the template
populate: create all BobVisualTree child associated with this template
printLog: prints the log
showExpNr: shows current exposure number in canvas area display
updateRawData: builds a TPL raw-data string starting from the keyword
arrays.
checkAbortFlag: convenience 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
finishOB ?-status <status>?: tell the OB that when this template finishes,
it should skip the remaining templates and return the termination
status <status> (default: TERMINATED) to OH.
getResult <name> : retrieve the value for the previously stored <name>
variable. Remark that all variables are erased when the first TPL of
an OB starts it execution. In other words, result-passing from one
template to another is only possible within a single OB.
Bob itself stores the execution status (0 = OK, 1 = error) of the
last template in the variable "tplExitStatus". This variable can
then be used by the call-back script to decide on proper actions.
pafReady <pathName> ?<keep>? : send an event to OH signalling that the
PAF-file <pathName> is ready for download. This file will be deleted by
bob after OH fetched it, unless the boolean variable <keep> is set to
true (or 1). Unlike other events, this one will be sent to OH even if
the template executing this command is part of an OB which was not
downloaded from OH.
If <pathName> is a directory, there will be an event generated to OH
for every single file on that directory.
seeBobVars ?-localcopy <listOfCats>?: in the absence of the -localcopy
option, issues the proper set of "upvar" instructions, within the
context of the calling procedure, to make the various category-arrays
created/owned by BOB accessible as local arrays with the same name.
This procedure returns a list with as first element the list of
category names which are then locally accessible.
If the "-localcopy" option is specified, <listOfCats> must be a list of
keyword category-arrays, for which there will be then a *copy* created
in the context of the calling procedure (i.e. these arrays are *not*
linked to the ones owned and accessed by BOB). The category OBS can
be included within <listOfCats>.
sendCmd <timeout> <cmd> ?<param1>? ?<param2>? ...: convenience procedure to
send commands to OS. This is the one and only way template-scripts are
allowed to use for communication with OS.
<timeout>: timeout value (in ms) for reply; 0 means return immediately
with the commandId - do not wait for replies; this argument
is not taken into account if the template-simulation mode
is on.
<cmd> : command; this is either a commandname alone (in which case
pararameters can be given in <paramX>) or it includes some
parameters (more parameters can be given as <paramX>).
Typical examples of commandnames are SETUP and START, of
parameters are "-file <fileName>" and
"-function <function1> <value1> [<function2> <value2> .....]"
<paramX> : parameter for <cmd>, if not already included as part of
<cmd>.
This procedure returns:
- reply on command if waiting for last reply (<timeout> # 0). Remark
that this reply is the new expoId value when the first SETUP command
for a new exposure is given (with an expoId-argument equal to 0).
Only the last reply on the command is returned.
- cmdId if command was sent OK and <timeout> is set to 0; this can
then be used by the caller to e.g. attach an event (see seq_evtAttach)
to incoming replies on this command.
- error (with message) if any error occurs or if ABORT flag is
acknowledged
There are a number of messages logged automatically logged by this
procedure into BOB's template log window; the commands sent will be
shown in green if operating in verbose mode (see configuration panel),
while in this case normal or error replies will be shown in green resp.
red. If <cmd> is WAIT, there will also be a message logged indicating
the termination of the exposure, when the final reply comes in.
Remark that sendCmd will not send any of a list of commands once the
abort flag has been set. This list can be defined/edited via the
configuration panel. The skipping of such commands is indicated in BOB's
template log window.
sendObsKeys ?<timeout>? ?-array <listOfCats>?: convenience procedure 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. The default timeout for OS to reply is 2000 ms.
Remark that a call to sendObsKeys will automatically increase the
exposure number (TPL EXPNO), so this proc should only be called once
per data file, and only if there is no START command involved.
The "-array <listOfCats>" optional pair is only legal in case OS is
not defined (i.e. BOB is used for particular engineering purposes).
<listOfCats> is now limited to OBS only. By using this optional
argument, the array OBS will become available at the level that this
procedure is called. Remark that during normal operation (with OS)
there is no need to access the OBS keywords passed in the OB.
(This "-array <listOfCats>" option is actually deprecated: please use
"seeBobVars -localcopy <listOfCats>" instead).
setCallBack <script>: set the script to be evaluated upon termination of
this template to <script>, thereby overriding - for this template
only - the setting in the configuration panel of the default template
call-back script.
<script> will be invoked whether or not the template returned an error.
It can find out the termination status of the template script via a
"getResult tplExitStatus" command (0 = OK, 1 = error). It
is up to the call-back to decide if and to what extent it should
continue if the template script returned with an error.
If the call-back script needs to get access to values the template
script has set, the "setResult" and "getResult" mechanism can be used.
Remark that these call-backs should not be seen as an extension of the
template's functionality (e.g. to prepare/start exposures). Instead,
their typical use is to log the template's termination or to put the
instrument in a safe state. For that reason. this call-back's return-
status does NOT influence the overall return-status of the template.
setResult <name> <value>: set the <value> for the variable <name>; this
value can then be retrieved by another template in the same OB -
see "getResult".
tplLog <text> ?<colour> ?<underline>??
append <text> to the current log-text, in colour <colour> (default is
standard default for text), and underlined if the boolean <underline>
is set. <text> is allowed to contain newline characters.
Remark that when "verbose communication" is on, the messages sent to
OS are logged in blue, and OK-replies are logged in SpringGreen4.
Errors come logged in red. The messages which are always added
automatically by "sendCmd" (e.g. "starting exposure n of m...") are
underlined. These colour-schemes of bob should be respected, in order
to avoid confusion.
This is a shell implementation of bob. The start-up parameters are similar
as for bob, i.e. you can specify the <name> under which this process will
register itself with the CCS environment, and pick up configuration
parameters from a different <file> than the default ~/.bobrc. If you do
not wish to run bobWish interactively, or need to run some script before
you enter into interactive mode, you can also pass the name of a
<scriptFile>.
BobWish contains dummy objects for all widget related operations. The
actions accessible via buttons or menus in bob are here activated through
the following set of commands :
bobAbort <reason>
abort the currently executing OB
bobContinue ?-foreground?
continue the currently paused OB
bobDisplayLog
display the log of the current OB-object
bobHelp
display a help text
bobInfo
give info about the loaded OBs and their state
bobNextObsBlocks ?<nr>|file? ?<filename>?
load <nr> OBs from the scheduler process, or an OBD from a file.
In the latter case, if <filename> is not given, a file-selection
widget will pop-up.
bobPause
stop the currently executing OB
bobPrint
print the log of the current OB
bobRepeat <reason>
tell the scheduler process to repeat this OB at a later stage,
giving also a textual <reason>. This implies an abort.
bobReset
mark all currently loaded OBs as freshly loaded
bobSaveConfig
save the configuration parameters in the configuration file.
bobSaveConfigAs ?<file>?
save the configuration parameters into <file>, or if <file> is
not specified, bring up a file selection box first.
bobSetup
display a help text, listing all the configuration commands.
bobSnapshot
dump bob-related info and logfiles to a timestamped directory.
bobStart ?-foreground?
start the OB
If the -foreground (of -fg) flag is given (valid for the bobStart and
bobContinue commands), control will be passed back to the shell *after*
the OB has terminated, instead of running it in the background and
returning control immediately.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|