Äîêóìåíò âçÿò èç êýøà ïîèñêîâîé ìàøèíû. Àäðåñ îðèãèíàëüíîãî äîêóìåíòà : http://curl.sai.msu.ru/mass/download/doc/sv_ug.pdf Äàòà èçìåíåíèÿ: Mon Mar 22 12:27:50 2004 Äàòà èíäåêñèðîâàíèÿ: Mon Oct 1 20:13:13 2012 Êîäèðîâêà: Ïîèñêîâûå ñëîâà: ï ï ï ï ï ï ï ï ï ð ï ð ï

SUPERVISOR program User Guide SV version 0.24
Kornilov V., Shatsky N., Voziakova O. March 22, 2004

1


Contents
1 Basic principles 2 Comp onent programs 3 Writing the scenaria 4 Editing the SV configuration file 5 Starting the system A Command list for the communication of the system Sup ervisor A.1 Commands acknowledgment . . . . . . . . . . . . . . A.2 General purp ose commands . . . . . . . . . . . . . . A.3 TLSP: Telescop e driving commands . . . . . . . . . A.4 MASS/DIMM: Detector commands . . . . . . . . . . A.5 CENT: Centering unit commands . . . . . . . . . . . A.6 CORR: Position correcting unit commands . . . . . A.7 OBJM: Ob ject manager commands . . . . . . . . . . A.8 DOME: Dome driver program commands . . . . . . A.9 METE: Meteorology service program commands . . B Inter-program communication proto col C Description of the observations scenario obs massdimm.tcl C.1 Algorithm functioning . . . . . . . . . . . . . . . . . . . . . . C.2 The list of control variables of algorithm . . . . . . . . . . . . C.3 Pro cedures of algorithm . . . . . . . . . . . . . . . . . . . . . C.4 Algorithm usage . . . . . . . . . . . . . . . . . . . . . . . . . C.5 Parameters of configuration file which tune the scenario work D Visualization utilities for scenaria debugging E Sup E.1 E.2 E.3 E.4 E.5 ervisor programming issues (development engineer Intro duction . . . . . . . . . . . . . . . . . . . . . . . . . Op erating system requirements and p ortability . . . . . Structure of the SV program . . . . . . . . . . . . . . . Starting and stopping the observations and circumstance Possible errors/failures o ccurring in Sup ervisor . . . . . guide) ..... ..... ..... monitor ..... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . comp onent programs and . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 15 16 19 20 21 21 21 22 22 23 25 27 27 28 29 29 30 31 31 31 32 35 38 3 4 5 9 11

2


List of Figures
1 2 3 4 5 6 7 SV graphic window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . States of the comp onent program and transitions b etween them . . . . . . . . . Blo ck-scheme of the algorithm of observations with MASS/DIMM . . . . . . . XMGRACE output pro duced by the viewlog.sh utility . . . . . . . . . . . . . . XMGRACE output pro duced by the viewhaz.sh utility . . . . . . . . . . . . . Startup of SV algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Control variables in starting and stopping the scenaria. Dashed arrows denote errors (emerging in scenaria during use of deleted aliased commands or attempt to call a command in deleted interpreter) which cause catch-construct to work and thus stop scenario evaluation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 17 26 30 31 33

.

37

Intro duction
In this do cument we consider the use of Sup ervisor program for automation of the observations sequence with a numb er of comp onent programs which are running the observational equipment (telescop e, detectors etc). The basic principles and the system tuning and running is describ ed b elow, whereas the MASS/DIMM scenario description, communication proto col accepted in MASS/DIMM and programming topics are lo cated in app endices. Below we briefly rep eat the general ideas of the SV-driven system explained in also in the Rep ort I. on the "Combined MASS/DIMM instrument" do cument (Kornilov et al, 2003).

1

Basic principles

The observational system from the software p oint of view consists of a numb er of driver-programs running on a single or several machines in a lo cal network. Each driver-program is called "comp onent" and allows to manipulate with a single hardware comp onent of the system ­ namely telescop e, some detector, stand-alone meteo-service or anything else. The comp onent normally has two interfaces: lo cal (console or graphic) user interface which allows to work manually with the device, and the command interface for communication with the program via a so cketconnection. The latter is used by the Sup ervisor program, which runs the sp ecially user-written system-tuned scripts. These scripts consist of a numb er of commands sent to the comp onents when some particular action or result is needed from them. Comp onents start the requested action or reply immediately with the ready result to the requesting agent (Sup ervisor). The proto col according to which they should act and accept commands is describ ed in app endix. The main content of latter do cument sp ecifies the demands to the MASS/DIMM system sp ecially. Normally, the observational set is a continuous p erio d of time (say, a night, week or a year) during which Sup ervisor must solve two tasks: 1. Tracing the conditions ­ whether they are go o d or not for starting observations; 2. Start observations when conditions are go o d and stop them (promptly!) when they b ecome bad. The scientific results collection is not the primary task of Sup ervisor, it only provides the extensive logging of own actions and commands exchange. The listed tasks are almost indep endent from each other, b oth in a sense of used comp onents and in a timing. They normally are run asynchronously and in parallel. In other words, SV provides the to ols for sequencing the commands to the comp onents in order to provide the non-excessive and efficient monitoring of observational conditions ­ this is

3


the scenario of the "Circumstance monitor" ­ and logical and optimal chain of commands to detectors, telescop e etc for conducting the observations ­ this is the "Observations" scenario. Both scenaria are written as Tcl scripts, but run not in a pure Tcl interpreter, but from the interpreters started by SV. User must provide the names of these script files (say, circmon.tcl for a monitor and obs.tcl for observations scenario) together with the comp onent parameters in the configuration file of SV ­ this is the sv.cfg file. Latter file may contain some parameters which tune the p erformance of the scenaria themselves ­ in order to easily mo dify their characteristics without edition of scenaria with a dully search for hard-co ded numb ers. Once provided such a go o d configuration file, user may start the comp onents, ensure that they are in a go o d shap e, start SV, and ensure that its start-up sequence has passed well and all comp onents were successfully connected to SV. That's all. In ideal situation, the User may come back home and wait for the e-mails from SV sent in case of o ccurrence of some error situations during observations (sending a mail is a usual option for the emergency sys script in CFG).

2

Comp onent programs

The current release of SV (or, more precisely, the provided scenaria of circumstance monitor and observations) op erates with following comp onent programs: a) OBJM ­ Ob ject Manager (Tcl script objm.tcl). The to ol for selection of the b estviewed star according to the user-provided selection criteria and the star catalogue. Includes the functionality of CIRC. b) CIRC ­ Circumstance Monitor (Tcl script circ.tcl). The computer of astronomical circumstances ­ the Sun and Mo on equatorial co ordinates and altitudes ab ove horizon, stellar and Universal time etc. Included into OBJM since it supp orts all the astronomical calculations needed for ob jects selection. c) METEO ­ Meteo service simulator (Tcl script meteo.tcl). To b e replaced with a real meteo-gathering program or upgraded to make the real conditions requests. Currently conditions are simulated using the random numb er generator. d) TLSP ­ Telescop e driver simulator (Tcl script tlsp.tcl). To b e replaced with a real driver program, or upgraded to send the commands to the mounting when it is needed. Currently, the telescop e activity is simulated by some waiting p erio ds. e) DIMM ­ the Differential Image Motion Monitor program simulator (Tcl script dimm.tcl). To b e replaced by a real DIMM program, e.g Robodimm for Windows or whatso ever app ears. In case of Rob o dimm, it will run on a separated Windows machine. Current simulator supp orts all the needed SV commands to DIMM replacing the real work for measurements with waiting p erio ds of 60 to 120 sec length (random). The simulator also supp orts the centering device functionality rep orting the star shifts in arcseconds on request. Shifts are random numb ers for b oth co ordinates which range increases from (-1,1) to (-100,100) arcsec when the time since the last request increases from 1 to 100 seconds and further. The CENT-functions run indep endently from DIMM functions in current simulator. f ) MASS ­ the Multi-Ap erture Scintillation Sensor program simulator (Tcl script mass.tcl). To b e replaced with a current release of Turbina program (version 2.04 or later) running on the same machine as SV or on the other Linux machine. Simulator provided serves thus only for purp oses of SV testing waiting for 60 sec up on RUN command for main measurements and for 5 sec up on RUN SCEN1 command for background measurement. The requests for data with GET-commands are supp orted (see MASS User Guide, Version 2.04). These comp onents (mostly simulators) may b e started together using the provided start dummies.sh script and killed by the stop dummies.sh script which is created by start dummies.sh.

4


When one wants to replace the simulators with real comp onent programs, the sv.cfg file must b e mo dified resp ectively to change the port, host and ident parameters of them. Then, to use other non-replaced comp onents, the line set comps "mass dimm meteo objm tlsp" in start dummies.sh must b e edited by removal of the names of replaced comp onents.

3

Writing the scenaria

Circumstance monitor and Observations scenaria are normally relatively simple scripts. They do not pay attention to errors which might o ccur in comp onents during execution ­ this is the comp etence of Sup ervisor (see also the end of this section). Also they must not care ab out the connection issues of the comp onents ­ they only know the new Tcl commands cmd, is cmd, wait cmd, wait sec, initialize, stop park and comp1, comp2... compn for communication with them (where comp1... are the comp onent program names listed in the configuration ­ the commands suited to return their configuration and requested parameter values). Both observations and circumstance monitor scenaria MUST take care ab out the initialization or parking of the comp onents b efore and after working with them, resp ectively. Note that this is a demand of SV versions starting with 0.20; earlier versions initialized and parked comp onents automatically. For doing so, the commands (actually, macros) initialize and stop park are provided ­ the scenario may use them as well as their own scripting. Initialization should b e done b efore scenario starts execution of measurements ­ i.e. b efore sending any commands implying the non-parked status of comp onents. Parking while stopping the scenario is more complex: the scenario has no idea when it may happ en. If some actions must b e undertaken while shutting down the observations (parking normally, also some p ossible after-scripts cancellation etc), the pro cedure with the reserved name end (without parameters) must b e written in the scenario. In case the scenario is stopp ed, SV searches for such a pro cedure and, if found, executes it b efore deletion of the scenario interpreter. First thing which this pro cedure must do is to prevent any other pro cedure from sending the commands to comp onents (organized, for example, with help of after-constructs), and then to call stop park "comp.list" if this is needed. Summarizing, the scenaria scripts do have b eginning, but not finalization which is provided by an isolated pro cedure end. Finally, Observations scenario has no idea ab out existence of Circumstance monitor scenario, and the latter knows only the commands start obs, is observations now and stop obs to manipulate the former. Below we sketch out the approximate sequence of actions which the scenaria should p erform in order to make observations: Circumstance monitor: 1. initialize monitoring comp onents (e.g. initialize "CIRC METEO") 2. set the needed parameters in them (optional; e.g.: cmd CIRC set longitude=..) 3. organize p erio dical requests of weather and sun-height conditions and, according to results and current state of observations (run or not), start or stop observations. Observations: 1. ask the new ob ject parameters 5


2. p oint the telescop e to new ob ject. Check that it is found with help of centering comp onent (co ordinate difference is not reserved +999 for the case of NOSTAR-error) If found 3. 4. 5. . 6. . . else 7. . . . try to find an ob ject around the exp ected p osition with telescop e and centering device. If found ­ check that it's likely the searched star, go to p.3. else ­ wait for some time and go to p.1 center the ob ject in field of view with help of centering comp. run a measurement command sequence if it is a time to check background or make some calibration ­ do it with help of telescop e and/or detectors trace whether it is enough with current ob ject. If yes ­ go to p.1, else ­ continue with p.4

As we see, observations scenario is much more complicated as it is. Writing the correct scenario is a key-p oint of successful usage of SV in automated observations. To write a scenario, the user should have at least general knowledge of the Tcl language, but study of the sample circmon.tcl and obs massdimm.tcl scripts may help to do the job without one since Tcl is very simple. Basic p oints are: · each line is a command with command name b eing the first word · command is ended by ";"-character or newline. The command may b e continued on a second line with help of trailing "¨ haracter. -c · a command in brackets [command args] represents the command substitution: e.q. [OBJM port] results in "1234" if sv.cfg has a line "p ort 1234" in "comp onent OBJM" section. This substitution may stand as an argument to another command: e.g. cmd OBJM set longitude="[CIRC longitude]" Here double-quotes are part of the command, since the result of CIRC-command may contain (and contains!) the spaces. · braces "{...}" are used to group the arguments. The content of braces may b e placed on several lines without trailing backslashes. Most common use of this is conditional commands if {condition} then {what then} else {what else}. · variables may b e declared on place of initialization where they b ecome needed. Do not forget that assignment may b e done only as: set a 1; set fi [CIRC latitude] and NOT as a = 1; fi=[CIRC latitude] - THIS IS WRONG. 6


· comments (#-started lines) are also commands - they are interpreted but only not executed. DO NOT PUT non-paired braces or brackets in comments! Avoid comments in switch-commands! The list of commands which user may use in scenaria is given in sections "SAFE INTERPRETERS" of the manual page to Tcl interp command (see man n interp). That's the starting p oint for a b eginner. All commands listed there may b e studied using their own manual pages (section "n"): e.g. man n after. The syntax of SV sp ecial commands is given b elow: cmd - to issue the command to the comp onent. Returns the command identifier. May b e started in background form with trailing "&" as a last parameter. The result of cmd when it rejects the request (e.g. comp onent is disconnected) is -1. NOTE this circumstance, since some scripts may b e based on issuing the command once previous is over! Since "-1"-result do es not cause an error situation in SV (no scenario script interruption is done), this may initiate an infinite lo op of cmd-calls (the SV console will b e full of messages "Attempt to send a command to disconnected comp onent"). Also, do not forget to enclose the string-typ e parameters in double-quotes: e.g.: cmd CIRC get longitude latitude set l [CIRC longitude] cmd TLSP set longitude="$l" latitude="[CIRC latitude]" is cmd comid - check that the command with the identifier comid (returned by cmd call) is still under execution (concerns evidently the cmd started with "&". Others return when execution is over.) Example: set mass_comid [cmd MASS RUN &] ... if {[is_cmd $mass_comid]} then { ... } else { ... } wait cmd comid [comid [... ]] - waits until any of the command(s) with given identifier(s) are over. When one of provided commands finishes - return its comid. wait cmd -1 returns immediately as well (see cmd). Example: set mc [cmd MASS RUN &]; set dc [cmd DIMM run &] ... wait_cmd $mc $dc if {![is_cmd $mc]} {} if {![is_cmd $dc]} {} # Note that at least one of above two conditioned lines will execute! wait sec delay [addlog ] ­ to delay execution of the scenario by the sec seconds. This do es not freeze the SV application up dating it once a second. The optional b o olean parameter addlog may b e set 0, if one wishes to skip the addition of the log-record (e.g. if delay is frequent and short). 7


component parameter - returns the value of the parameter (CFG or returned by the GETcommand) of the comp onent. In other words, there is such a command for all comp onents which are mentioned in CFG. Request of non-existent parameter causes the scenario interruption on error. Example: see cmd-examples. add log record ­ add the record in the log. initialize "components list" ­ a macro of INIT-commands where them are given the all comp onents altogether (INIT &) and then the macro waits for completion of initialization of all comp onents b efore return of control. For a single comp onent, the command is equivalent to cmd COMP INIT. Note that some comp onents may b e initialized with parameters (i.e. like INIT param=value param2=value..., see circ.tcl) ­ they cannot b e thus initialized with initialize. stop park "components list" ­ a macro of STOP NOW and PARK & commands where them are given to all comp onents and then the control is given back to caller when all comp onents get status PARKED. Monitor of circumstances also "knows" start obs - start observations scenario (when "go o d"). E.g.: cmd CIRC get hsun if {[CIRC hsun]<-12} { # Navigation twilight already: start_obs } stop obs - stop observations. E.g.: cmd METEO get cond if {[METEO cond]!="GOOD"} stop_obs is observations now - is the observations scenario under execution now. Example: if {[METEO cond]=="GOOD" && [CIRC hsun]<-12 && ![is_observations_now]}{ start_obs } An example of the observations scenario ­ obs massdimm.tcl ­ is do cumented in the app endix. Handing errors. As it was stated ab ove, SV takes care of handling the errors which o ccur while running the scenaria or rep orted by comp onents in their replies. A normal reaction for fatal errors happ ening with comp onents (such as a loss of connection, fatal error status etc., see Section E.5) is shutting the comp onent down (parking, if p ossible, and disconnecting), then ­ terminate SV or continue, dep ending on the optional parameter of this comp onent. Meanwhile, sometimes it is more vise to try to handle the situation more flexibly in order to make the system p erformance more stable. For this, the scenario (monitor or observations) must provide the pro cedure: 8


proc error_handler {code comp} { # parsing code and comp-onent parameters... ... # if handled successfully: return 1 # else -- unfortunately: return 0 } Such a pro cedure must return 1 ONLY if the error of a king code from the comp onent comp is indeed exp ected ­ for example, due to imp erfections of its co de implementation. See the co des in Section E.5. It is evident that there is no sense to return 1 in some cases: e.g. when the connection is lost (i.e. co de==ECMDLOS, ECMDLOW, ECMPDSC), b ecause the next error will o ccur immediately. Normally, successfully handled are only the ECMPFAT errors, although it is useful sometimes (at developing stage) to rep ort the errors only and to return 1 in any case.

4

Editing the SV configuration file

The SV configuration file name sv.cfg (the file resides in the same directory as sv.tcl!) is the only hard-co ded value of SV. All other settings are made by assignment of resp ective parameters in this file. Sometimes, sv.cfg is a link to the currently active SV setting file. SV comp osition is describ ed b elow and in sv.cfg sample as well in the comment lines (starting with #-character). The parameters of configuration stand in SV as either parameters of SV itself (in this case they are referenced in SV source text as SV(param) and in scenaria as [SV param]) or parameters of a comp onent - e.g. [CIRC latitude] in a scenario or cmp(port) in sv.tcl. This division is made with help of so called sections in SV configuration file. Beginning of a first section is the b eginning of the file. This is the section of SV parameters. They (tmout, oscen etc) last till the first declaration of a next sections: "component name" on a separate line. This declaration starts the section of the comp onent "name" and simultaneously declares that the comp onent program "name" exists in the system and must b e connected on start-up using the parameters sp ecified b elow. A numb er of parameters MUST reside within sv.cfg in order SV to work correctly. These are the parameters oscen and cscen of SV and the parameters port and ident for each comp onent. Their existence is checked during SV startup and error o ccurs if any is missing. A numb er of other parameters are also needed but defaulted within SV if not found in sv.cfg: these are tmout, revive time, interactive, start monitor and emergency sys in SV section , and parameters host and optional in each comp onent sections. Since version 0.20, the parameter obs comp list is obsolete (due to explicit initialization/parking of comp onents in scenaria, see b elow). Finally, a to ol for manipulating the observations scenario (only) interactively is provided in a form of a separate GUI: a window with the arbitrary numb er of buttons. This window app ears when Observations scenario is started and disapp ears when it is stopp ed. The button action is sp ecified in SV configuration file as a line: button1 command in scenario context; there may b e any numb er of lines like this: button2 command2, button3 command3... Normally, these commands are simple: assignment of some control variable or calling of a scenario script pro cedure. Complex commands are not recommended. Usually, such a GUI control is used while developing the system and related observations scenario; when the system is run finally as non-assisted, the resp ective button parameters are removed from sv.cfg. 9


Below we give a short explanation of a use of SV parameters: SV parameters: cscen ­ file name of a Circumstance monitor scenario script. oscen ­ file name of an Observations scenario. tmout ­ the time in seconds to wait for a reaction of a comp onent on a newly given command. Default is 10 sec. revive time ­ time in seconds after which the SV is self-restarting after shutting down up on a fatal error o ccurred with a comp onent while running scenario. This is made in a (mayb e fictious) hop e that after some time the problem may disapp ear itself. Defaulted to 0, i.e. do not restart. emergency sys ­ the system command or the name of a system script which is executed up on o ccurrence of a fatal error b efore termination of SV. Normally it is shaping out and sending the problem rep ort by e-mail. Defaulted to simply typing "SV termination!" on a lo cal console. interactive ­ logical (0/1) variable sp ecifying the way some error situations are treated. If 0 (non-interactive), SV shuts down up on any unhandable fatal situation calling emergency sys b efore; if 1 (interactive), the message is output in a graphic window allowing some bypassing actions to b e undertaken which is used while debugging the system b ehavior lo cally (i.e. in assisted mo de). Defaulted to 0 (i.e. non-assisted). start monitor ­ logical (0/1) variable sp ecifying whether to start or not the Circumstance monitor immediately up on startup (i.e. as shown in Fig. 6). Defaulted to 1. buttoni command ­ sp ecification of a command to b e invoked in Observations scenario when it is running. Comp onent parameters: ident ­ comp onent program identifier (string), returned up on the request GET IDENT (see b elow). p ort ­ so cket p ort numb er of a comp onent. host ­ name of the machine (IP or DNS name) where comp onent is running. Defaulted to 127.0.0.1 (i.e. lo cal host). optional ­ role of a comp onent in a system. If sp ecified as 1, the comp onent is parked and disconnected up on o ccurrence the fatal error with it and the system pro ceeds running. If not sp ecified or given as 0 ­ o ccurrence of a fatal error with the comp onent causes the system to shut down. It is fully due to the scenaria writer to decide which comp onent is optional and which is the mandatory, i.e. the one without which the system p erformance is not p ossible at all. Defaulted to 0 (i.e. mandatory). All the rest parameters are suited for the scenaria needs only and ignored by the SV co de itself. Note that there is NO principal difference where to put these parameters ­ in a section of SV or of some comp onent; it's a matter of taste and free logics. A go o d habit is to put the p ersonal parameters of comp onents (which control their usage or which are set in them with 10


SET command) in the section of resp ective comp onent. Note that similar comp onent parameters may have the same name for different comp onents. In principle, the user is free to hard-co de all the parameters in scenaria scripts and to leave only the obligatory parameters in sv.cfg. Example of usage of SV configuration parameters in Circumstance monitor scenario is given in sample circmon.tcl.

5

Starting the system

The SV package should b e unpacked in some directory, normally it is /usr/src. No ro ot privileges are demanded for SV running. So, its useful to change the p ermissions for the user going to start SV (e.g. mass) to b e able to write in the SV directory. Also, the log-files *.log and temp orary files (tmp.*,.tmp), if present, and SV configuration files *.cfg must b e writable or owned by this user. sv.tcl and the comp onent scripts such as meteo.tcl, circ.tcl, objm.tcl etc. must have execution p ermissions. The comp onent programs apart from those residing in SV directory must b e installed separately and must b e accessible via network. Their IP addresses (127.0.0.1 for the same machine as SV runs on) and p ort numb ers must b e written in SV configuration file sv.cfg. Note, that p ort numb ers on the same machine cannot b e shared! All comp onent programs should b e started BEFORE SV starts and continue to b e on-line all the time the system works. Once the connection is lost, SV stops working and disconnects the comp onent. If the parameter "optional 1" is not set in the resp ective comp onent section of SV, the SV terminates (or gives the resp ective message if run in interactive mo de). You may use client.tcl port [host] script for connecting to the particular comp onent program to check how it works and how it is seen to SV through network. The commands there are enumerated automatically, so the first input word from the console should b e the command keyword (INIT, RUN etc). Finally, shap e out the emergency sys parameter in sv.cfg to have the prop er error handling command ready. Try to initiate the error situation (disconnect or shut down one of comp onents) and see what will happ en: someb o dy should receive an e-mail in reserved address with the fragment of SV log file if your emergency sys is set to running of the provided sv error.sh script. Then start Sup ervisor from the current directory: $ ./sv.tcl The window like shown in Fig. 1 app ears in the screen. The history of commands exchange app ears on the console and (somehow shortened, command-reply pasted) - in the SV window panel. Log-file is created with the name YYMMDDsv.log, where YYMMDD is the evening lo cal date of the night (it is given by the moment 12 hours b efore). The circumstance monitor scenario will b e started automatically and may b e stopp ed by the [Stop monitor] button. When monitor (or you ­ via [Start observations] button) commands to start observations, the observation scenario script with related communication with comp onents will start. To stop observations or monitor ­ press the resp ective Stop-button. When finished completely ­ press [Terminate]. Exp eriment with a trial starts of SV using the manual Start observations (from GUI button). Check that system starts initialization and everything go es Ok. GUI control buttons

11


Figure 1: SV graphic window

12


Comp onent names : these are in practice the buttons which p op up the menu with following items: Command : op ens the dialog for command exchange with the comp onent. Connect : connects the comp onent if it was disconnected. Practical for the manual commands exchange only when no scenario (monitor or observations) using a comp onent is active Disconnect : closes the so cket channel of the comp onent. All the commands sent after this to comp onent are ignored resulting in a resp ective log message only Start Observations : calls the pro cedure start obs of SV. If the observations starting was disabled, enables it first (that's a difference with the starting of observations from the scenario) Stop Observations : calls the pro cedure stop obs of SV and disables starting of observations by the circumstance monitor. Allow Observations : resets the observations starting protection set by Stop Observations button. Observations MAY then b e started by the circumstance monitor Pause/Resume communication with comp onents: delays the comp onents until the rep etitive pressing of the button. scenaria are executed until the control reaches the next is pressed, the delayed command(s) is sent as normally. communication and Terminate button are not blo cked in sending of the commands to the After pressing the button, the cmd call. When Resume button Comp onent Commands dialog the paused state.

Start monitor : starts the circumstance monitor scenario (which is started automatically up on SV startup pro cedure) Stop monitor : stops the execution of the circumstance monitor scenario until next its start by the button Terminate : stops observations parking all the comp onents, disconnect all comp onents, remove GUI and exit the program. The same as a small cross-button of the SV's window (upp erright side normally).

13


Appendices
A Command list for the communication of the system comp onent programs and Sup ervisor
Intro duction
This do cument concerns the further development of the software for the pro ject at the upp er logical level. Here we consider the requirements for the comp onent programs (like MASS, DIMM and Telescop e driving programs and other secondary services) which should b e fulfilled for their successful op eration under the management of the Sup ervisor program. The communication proto col was fixed in the previous rep ort (see Appx."Inter-program communication proto col") while here we sp ecify what in particular is needed to b e supp orted (commands and all parameters which may accompany them) in the device programs within the current pro ject. Currently, the following comp onent programs are exp ected to take part in the scenario of Sup ervisor: TLSP ­ telescop e driving program: p ointing and corrections MASS ­ detector 1 program DIMM ­ detector 2 program CENT ­ guiding unit giving the current star offset from the center CORR ­ p osition correcting unit (normally unified with TLSP) DOME ­ dome controlling program (may b e unified with TLSP) OBJM ­ ob ject manager program and astronomical circumstance computer: sun height, Luna co ords.. METE ­ meteo service program Changes of the philosophy of the Sup ervisor, compared to the previous Rep ort, are reflected in the separate do cument "The construction of the sup ervisor program for automated observations" (Shatsky, 2-7 July 2003). Considering the proto col itself, three issues should b e stressed with resp ect to the distributed proto col given in the Rep ort 1 (Appx. C): 1. The message strings are terminated with newline character. This is intro duced in order to resolve two messages arrived one after other b efore the program is able to read the so cket buffer 2. Command identifier (the first field in the message) is no longer the arbitrary unique word, but (in the current MASS/DIMM pro ject) the unsigned integer numb er varying cyclically as 0, 1, 2,..., 65535, 0, 1 etc. This space of allowed values should b e enough for any feasible set of commands active in the system for a given moment. 3. Parameters use in commands and replies is made more determined. For example, the parameter cannot b e replied without request (except for system-sp ecific sp ecial parameters like STATUS, see b elow) and cannot b e requested and assigned simultaneously (intermixture of SET and GET commands is avoided). 14


The up-to-date version of the proto col is given in the app endix to the current do cument. Management of the Sup ervisor from external is not p ossible. The only way for intervention in SV work is a ssh login to its machine and sending it a signal (TERM) to terminate correctly. This will cause ab ortion of observations, parking all comp onents and termination of SV program. Then some changes may b e intro duced in the configuration of SV and its algorithms and SV may then b e restarted again. The current state of SV will b e visualized to external by supp orting the sp ecial part of SV which will monitor the state of comp onents (their status and data rep ort requested by GET DATA command, see b elow), current ob ject and co ordinates including. The resp ective htmlpage will b e generated automatically from these data up on request from external client for which the separate (server-typ e) so cket will b e created by SV. In brief, the system state and some data results will b e seen to external world, but no way to affect the system p erformance will b e provided except for sp ecially p ermitted login to the SV machine for maintenance. Other issues of the system configuration (comp onents distribution in different machines, time synchronization etc) will b e considered elsewhere and are not the sub ject of the current commands-definition do cument.

A.1

Commands acknowledgment

Being fed with a new command, the comp onent must distinguish the commands with purely logical actions (value setting or getting) and the ones which demand some practical job to b e completed. Formers normally take a little time to execute since neither extensive calculations nor intensive physical movement or long data accumulation are requested. These commands are executed immediately and the acknowledgment "OK" with some optional supplied parametervalue pairs is sent back to SV. The latter (intensive) commands ­ RUN, INIT and PARK ­ normally take a significant time for execution; their reception and execution b eginning is usually acknowledged as "OK STATUS=BUSY WAIT=twait" where twait is a maximized estimation of the execution time of the command. If the comp onent receives the command "GET STATUS" in b etween the command reception and the command completion, its status is again returned as "OK STATUS=BUSY". When the command is completed, the final acknowledgment is sent together with the status of execution (see statuses list in sect. A.2). In case the command arrives which requests the state-switching action while the comp onent is in the incompatible state (reflected by status), the error is replied: ERROR STATUS=status. Examples are any commands except for STOP NOW and GET STATUS arrived b efore a previous command was not completed (reply is ERROR STATUS=BUSY); RUN, STOP in the parked state (reply is ERROR STATUS=PARKED). The commands STOP NOW and GET STATUS are accepted in any state, the former causes no effect if there is no job to stop (status is not BUSY). The maximal time which is needed for any comp onent to react to logical ("short-term") commands should b e estimated for any system, maximized by some factor (say, 3) and set as a timeout duration in the sup ervisor needed to detect the abnormal states of the comp onents when they ignore the commands. It should b e stressed again that since the sup ervisor needs to know the state of the comp onent after completion of each long-term or state-switching command, the comp onents are obliged to rep ort their status while sending the final completion acknowledgment for state-switching commands, namely ­ RUN, STOP, INIT, PARK, FREE rep orted as

15


OK STATUS=BUSY|READY|PARKED|LOCAL [WAIT={\it Twait}] and any other (GET/SET including) which caused the error-state of the comp onent replied as ERROR STATUS=ERFAT|ERSYN|ERANG Example of communication log-file (each line b eing the direction of a message, recipient name and a command):
->1000 <-1000 ... ->1020 <-1020 ... <-1000 MASS RUN OK STATUS=BUSY WAIT=61 MASS GET STATUS OK STATUS=BUSY OK STATUS=READY

In the sections b elow we list the commands which should b e supp orted by the comp onents. The exp ected reply is given for each command for the case of success. In case of the fatal error o ccurred during the command execution, the answer will b e "ERROR STATUS=ERFAT"; for errors of the command interpretation replies are either "ERROR STATUS=ERSYN" (for unrecognized command syntax, parameter names etc, including the full character mess) or "ERROR STATUS=ERANG" for the case of the command parameter value out of allowed range (e.g. TLSP p ointing to inaccessible direction on the sky or ob ject identifier not found in the detector comp onent catalogue). Note: for the state-switching commands INIT, FREE and PARK the command rep etition is not prohibited. If the comp onent is already in the needed state, it replies immediately as OK STATUS=state. E.g.:
->1030 <-1030 ... <-1030 ->1033 <-1033 TLSP PARK OK WAIT=100 OK STATUS=PARKED TLSP PARK OK STATUS=PARKED

The scheme of states and transitions for comp onent programs is shown in Fig. 2. These general rules should b e ob eyed by any program which conforms to the proto col.

A.2

General purp ose commands

Here we give a set of commands with parameters which should b e supp orted by each of the program comp onents interacting with Sup ervisor. GET IDENT - return the comp onent identification. This value must coincide with the comp onent parameter IDENT in the configuration file. Since multiple devices are planned to b e used at different sites, the safe identification is seemed to consist of the program name, program version and the hardware device ID. E.g.: MASS(IDENT)="turbina v2.01 unit01"). This identification is also exp ected to b e present in the output data files of detector comp onents. Reply: OK IDENT="ident"

16


get READY (NOSTAR)

set

tlsp: itself, run set ERANG any incorrect command ERSYN get status

stop now

free any command LOCAL

BUSY

init park

run

run, park, itself ERFAT init

get status PARKED

park

Figure 2: States (statuses) of the comp onent program and transitions b etween them. Along transition arrows the commands are shown which cause such a comp onent transition.

17


INIT - self initialize to bring the device in the working (online) state after PARKed state. For TLSP this means that only the command RUN RA=... DEC=... is needed to start observations, i.e. sidereal tracking will b e switched on after p ointing (it do es not matter to SV whether it is on or off in b etween INIT and RUN commands). Replies: OK WAIT=Tinit, then OK STATUS=READY RESET - clear the message queue in the program (no acknowledgment!). This command is reserved as a p ossible future mechanism of problem resolution using a sp ecial mo de of so cket connection. Not realized in a first implementation of a system. Reply: no GET STATUS - return the status of the program. The statuses may b e following: PARKED - comp onent in the parked (hardware off ) state LOCAL - comp onent is under the lo cal console control READY - ready to p erform next command (normal state after acknowledging of the previous command with OK). BUSY - command is under execution ERSYN - error of syntax parsing: unrecognized command ERANG - supplied parameter is out of allowed range of values. For telescop e, this is also the state when telescop e has tracked to the limit of p osition and stopp ed waiting for the next p ointing ERFAT - unrecoverable error o ccurred making imp ossible further work of the comp onent. Details are in lo cal program log file. There is also a sp ecial status for detecting comp onents like CENT or scientific detectors (MASS, DIMM): NOSTAR - ob ject is not found or sensed within field of view; no valid measurement results may b e or are obtained Reply: OK STATUS=status GET DATA - return the unformatted string with latest obtained output data. This command concerns only the data-pro ducing comp onents, e.g. detectors, centering unit (star offset data) and meteoservice. These data are supplied to the sp ecial part of the Sup ervisor which provides the monitoring of the system via the WWW interface. Reply: OK DATA="data record up to 1024 symbols" FREE (obsolete) - lo cal control (standby state) activation (if there is one) until a next command comes. Reply: OK STATUS=LOCAL Note, GET some will b that this status may b e returned only by the STATUS would bring the comp onent back action started lo cally in the moment of this e returned, until the action is completed or 18 command FREE, since any after-going online. If the comp onent was running next GET STATUS, the status BUSY STOP NOW command comes. In any


case, no further lo cal action requests is pro cessed. This command is obsolete, since in practice the lo cal controls allow to activate themselves even if SV is connected. So, after such an activation the control should rest lo cal until SV requests the next action. PARK - shut down own services, switch off the high voltage, close the do ors or whatso ever to prepare for sleeping and go asleep. Reply: OK WAIT=Tpark, then OK STATUS=PARKED QUIT - implies PARKing (if not PARKED status) with a reply as stated ab ove, and termination (with closing the so cket connection) after at least 1 second. This command is added later and is essential for some rob otic systems which do not work in day-time. In following sections we consider the commands sp ecific to each of the comp onents by their parameters and/or actions required.

A.3

TLSP: Telescop e driving commands

The comp onent TLSP must accept the following sp ecific commands. Note, that the co ordinates involved in the communication are the real astronomical co ordinates, not the instrumental ones! In this resp ect, maintaining the correct time reference system in Sup ervisor and TLSP comp onent is the crucial part of the correct system p erformance. Telescop e comp onent commands would b e rather more concise if there was no need for SV to check the visibility conditions for a given ob ject, taking into account two p ossible orientations of the tub e relative to the mounting in many telescop e mountings. Thus, some commands were intro duced to allow the SV to see, how long the selected star may b e tracked by the mounting in a given (current or changed) orientation. So, some intellect is required to b e supp orted by TLSP comp onent program to provide these simple but mounting-sp ecific up-to-date measures. However, if there is no way to implement this functionality in the TLSP program, it should resp ond ERROR STATUS=ERSYN to such requests. Thus, the SV observation scenario should b e adapted corresp ondingly. SET RA="hh mm ss" DEC="±dd mm ss" - set the co ordinates for future p ointing. This is used to check the accessibility conditions in different orientation of the tub e with help of GET TVIS TVIS2 command. No status is changed. Reply: OK Note: no checking of the accessibility is p erformed. After-going RUN without parameters may result in ERROR STATUS=ERANG if preset co ordinates were unavailable. GET TVIS TVIS2 - get the time of visibility in seconds for currently preset co ordinates (by previous SET RA... DEC... command) or for actual co ordinates if no co ordinates were preset after the last p ointing. Here TVIS is the visibility duration in current orientation of the tub e, TVIS2 - in opp osite orientation of tub e. Reply: OK TVIS=tvis TVIS2=tvis2. Note: if the ob ject is not accessible in one of orientations (or b oth) or no co ordinates were p ointed or preset b efore, resp ective TVIS or TVIS2 is/are returned zero. RUN [OVER ] - p oint to the co ordinates preset by foregoing SET RA=... DEC=.. command. If no SET-command was given, ERROR STATUS=ERANG is returned. Optional parameter OVER means changing the orientation of the tub e to the opp osite while p ointing to the preset co ordinates (see command GET TVIS TVIS2). 19


Replies: OK WAIT=Tpoint, then OK STATUS=READY or: ERROR STATUS=ERANG if the requested co ordinates are currently inaccessible in the given orientation (no OVER) or in the changed one (if OVER switch is supplied). RUN RA="hh mm ss" DEC="±dd mm ss" [OVER ] - p oint to the given co ordinates. Optional parameter OVER means changing the orientation of the tub e to the opp osite while p ointing to the given co ordinates (see command GET TVIS TVIS2). Replies: OK WAIT=Tpoint, then OK STATUS=READY or: ERROR STATUS=ERANG if the requested co ordinates are (currently) inaccessible. Note, that for german-typ e and some other typ es of mountings, there are some limitations for tracking regarding the orientation of the tub e relative to the mounting and ob ject height ab ove horizon. If a limit of tracking is reached, the telescop e stops and replies to the next GET STATUS with ERROR STATUS=ERANG. This is the only way for SV to know ab out this state. TLSP must start rep orting ERROR STATUS=ERANG to GET STATUS at least one munute in advance to actual stopping of the tracking motor. GET RA DEC - get the current actual (not preset by SET RA=... DEC=...!) p osition of the telescop e. Reply: OK RA="hh mm ss" DEC="±dd mm ss". RUN DRA=dh DDEC=dd - apply the correction in right ascension and declination directions. Both dh and dd are measured in seconds of arc in the sky plane, i.e. the actual change of a hour angle is sec(D E C ) · dh/15. The sp eed of correction is selected by the telescop e software, probably dep ending on the value of the correction. Reply: OK WAIT=Tcor, then OK STATUS=READY or: ERROR STATUS=ERANG (in case of to o large corrections or ERANG (stopp ed) state of the telescop e).

A.4

MASS/DIMM: Detector commands

The following list is supp orted by any detector device program disregarding its sp ecialization. Both MASS and DIMM devices supp ort the same command set. SET OBJECT="nnnn" - informs the program that the telescop e is p ointed to the ob ject identified in the program's target catalogue with a key nnnn (in MASS and DIMM nnnn is accepted as a Bright Stars catalogue star numb er). Reply: OK or: ERROR STATUS=ERANG (misidentification of the ob ject) RUN - start a lo op of accumulation of one output data piece (accumulation time measurements). Once obtained a data p oint, stop. Replies: OK WAIT=Tmeas STATUS=BUSY, then OK STATUS=READY; or ERROR STATUS=NOSTAR if no data may b e obtained due to absence of the ob ject in the field of view. RUN SCEN1 - measure and save the background level for prop er reduction of data in the RUN commands (if applicable). SCEN1 is a name of a scenario where the mo de (or a sequence of mo des) is sp ecified to make the background measurements. Replies: OK STATUS=BUSY WAIT=Tbkgr, then OK STATUS=READY. 20


The comp onent which do es not need the background resp onds with immediate OK STATUS=READY instead. No check for the clearness of the field is required. RUN SCEN2 - start measurements of the stellar flux (MASS only). SCEN2 is a scenario where flux measurement (single or continuous ­ made until STOP NOW comes) is written. Replies: OK STATUS=BUSY WAIT=Tflux, then OK STATUS=READY. This command is intro duced to allow the remote checking of the fluxes in the several ap ertures of MASS device. STOP NOW - ab ort the current accumulation and stop immediately. Current data piece is lost. This is used in rain-drop emergency, or elsewhere. Usually this command is followed by PARK. Reply: OK STATUS=READY GET DATA ­ return the last-obtained results of measurements. Here "DATA" are replaced with one of SCIND, FLUX, BKGR, X/LPROFILE, INTEGRAL ­ see Mass User Guide what is provided.

A.5

CENT: Centering unit commands

RUN DRA DDEC - measure and return the measured offset of a guiding (target) star from the center of the field of view in arcseconds. If grabbing of frames is continuously ongoing, return the last obtained offset. Reply: OK STATUS=READY DRA=dh DDEC=dd or OK STATUS=READY DRA=+999 DDEC=+999 if there is no star found. Note: in some systems, this might b e the check for sky clearness for background measurements (see RUN BKGR command in Sect. A.4).

A.6

CORR: Position correcting unit commands

Normally this function b elongs to the telescop e. RUN DRA=dh DDEC=dd - see the description of TLSP RUN DRA DDEC command. In most systems the CORR comp onent is an alias of TLSP program, and the algorithms may refer to CORR for the sake of generality.

A.7

OBJM: Ob ject manager commands

GET T1 T2 T3 T4 - compute and return the following moments for the night expressed in UT. T1 is b eginning of evening twilight when (restricted mo de) measurements may b e started, T2 and T3 - b egin and end of the "deep" night (say, sun height is -18), T4 - end of morning twilight. The rule is that T4 is always the nearest moment in the future. The parameters may (in principle) b e acquired separately, but this rule ab out T4 should b e fulfilled disregarding which parameter is mentioned. If the evening twilight is continued by morning one ("white night"), then the result ob eys the convention: T2=T3=(T1+T4)/2. The p olar day request to the parameters considers the first "white night" in the future. Time is given in UT in the following format: "YYYY-mm-dd HH:MM:SS". Reply: OK T1="t1" T2="t2" T3="t3" T4="t4".

21


GET HSUN - return the current apparent (corrected for refraction) Sun height in degrees (negative in the twilight/night time). Reply: OK HSUN=hsun (e.g. "OK HSUN=-4.6") RUN OBJECT RA DEC TVIS - return the parameters of the star for p ointing now which is the "b est" according to the OBJM's opinion. Note that the request to either of OBJECT, RA, DEC or TVIS always initiates the search for a b est star, so separate requests of these parameters are dangerous and meaningless. Mo on p osition, twilight (hence minimal brightness) are taken into account prop erly. Here OBJECT is the catalogue numb er which is identified by the detector catalogues (HR for MASS and DIMM), RA and DEC are transmitted to the telescop e for p ointing, and TVIS is a time of visibility in seconds during which this star will remain the b est choice for observations. Reply: OK WAIT=tsort, then OK STATUS=READY OBJECT="id" RA="hh mm ss" DEC="±dd mm ss" TVIS=tvis, or OK STATUS=NOSTAR if no p otential target is visible. SET OBJECT="nnnn" STATE="ssss" - inform Ob ject Manager, that the current ob ject "nnnn" is either successfully observed ("ssss" is "DONE") and needs no p ointing for a while, or was rejected by some comp onent ("ssss" is "REJECT", e.g. by TLSP p ointing restrictions). This causes OBJM to remove this ob ject from sorting by conditions (at least for some p erio d of time). Reply: OK, or ERROR STATUS=ERANG

A.8

DOME: Dome driver program commands
Reply: OK WAIT=topen, then OK STATUS=READY

RUN DOME=OPEN - op en the dome.

RUN DOME=CLOSE - close the dome. Reply: OK WAIT=tclose, then OK STATUS=READY GET DOME - ask the state of the dome (op ened/closed) Reply: OK DOME=OPENED, or OK DOME=CLOSED or OK DOME=BUSY (op ening or closing). Note that the azimuth of dome (for rotating enclosures) is not considered, since the issues of the equipment saving in day- or rain-time are only considered. If dome is a rotating enclosure with a narrow slit, the synchronization of its azimuth is p erformed by the telescop e program and the DOME comp onent will naturally b e the alias of TLSP.

A.9

METE: Meteorology service program commands

This comp onent is meant as some interface to the lo cal observatory meteostation service, which requests the needed subset of parameters from the common access place (http or NFS file). Thus, the interpretation of some parameters may not b e straightforward. For example, the T (temp erature) for SV may b e assigned the value of some measurement at, say, 5m ab ove ground. GET DATA - get the current meteo information in unformatted string, where following designations are recommended: 22


T - temp erature in degrees of Celsius at the height of instrument H - relative humidity in p ercent R - rain flag: 0 - no rain, 1 - rain detected W - wind sp eed in meters p er second WD - wind direction counted from north to east in degrees P - pressure in millibar. Reply: OK DATA="T=t H=h R=0/1 W=w WD=az P=p" Note that this reply format is an example, since SV do es not parse DATA replies. GET COND - get the lo cal conditions in terms "GOOD" for observations and "BAD" for immediate closing the dome based on the own evaluation of criteria for T, H, R, W, and P (see ab ove). This command will evidently b e p olled much more frequently than GET DATA. Reply: OK COND=GOOD, or OK COND=BAD.

B

Inter-program communication proto col

Here we quote up to date version of the communication proto col which sp ecifies the syntax of the commands sent of the network b etween the SV and comp onent programs. Each message transfered via so cket connection is a command to p erform some action (make something or return some value) or reply to the command. Message is an ASCI I string terminated by the newline character. The string has the following structure: COMID KEYWORD [ PARAM1[=VALUE1] [ PARAM2[=VALUE2] [ ... ] ] First word in a string is a command identifier which is aimed to resolve the p ossible cases of confusion b etween asynchronous replies to different commands. It consists of either decimal digits or (case insensitive) alphab etic letters. The proto col do es not sp ecify the meaning of this identifier; its only prop erty is that it is unique, at least over a long enough time scop e of the communication. In MASS/DIMM application, an agreement to use as an identifier the unsigned integer changing as 0,1,..65535,0,1... etc is accepted (this will b e a single global command numb er variable incremented by the command-sending routine). Second word in a string (all words are delimited by spaces) is a command key word which sp ecifies the typ e of action which is requested. Keywords list is minimal and their meaning is as general as p ossible. Details are sp ecified in parameters. The case of letters is not significant. Keywords consist of up to 8 symb ols and may include alphab etic letters and decimal digits 0-9 only. Parameters PARAM1...PARAMn also b elong to a reserved list which is more flexible and easily expandable than the keywords list. Optional values (words after a '=' sign) are either decimal floating p oint numb ers or strings. No b o olean logic typ es is supp orted. If there is no parameter value given, the parameter is a called b elow "parameter-switch". There must b e no space b etween the parameter name and the '=' symb ol and b etween '=' and the value. String values which contain spaces must b e enclosed in double-quote symb ols. Example: 12 SET OBJECT="Alpha Leo" SPCL=B7V CIBV=-0.11

23


The proto col demands that receiving of every command except for RESET and acknowledgment commands (replies) must b e confirmed. This is done by sending an answering acknowledgment command with the SAME command identifier and one of two keywords "OK" or "ERROR" with optional parameter(s). "OK" is reserved for cases when the command parsing was successful and the demanded action has completed without a problem. "ERROR" is for problematic cases: command misundersto o d, invalid parameter names, some parameter is our of allowed range or, finally, the fatal error has o ccurred during the command execution. Which of the problem has resulted in this error, is sp ecified by the STATUS parameter value, which may b e app ended to the reply. The command confirmation (acknowledgment) is waited for at most TIMEOUT seconds (TIMEOUT is a parameter sp ecified in the SV configuration file which is somehow maximized reaction time of all the programs). When the confirmation OK is supplied with a parameter "WAIT=", this means that the requesting agent (normally SV) should wait for the completion of the requested action another seconds during which the final confirmation "OK" or another "OK WAIT=" should arrive with the same command identifier. If neither comes, this is a communication failure case. If the command is exp ected to return some value of a parameter (other but some general one like STATUS), this parameter name must b e mentioned in the command: E.g. GET DATA or RUN DATA cannot result in OK ONE=1 TWO=2, but only in OK DATA="data". Backward is not true, since some parameter-value pairs and parameter-switches may b e supplied with no need to return any value of the switch (which may b e meaningless). For example, RUN BKGR may result b oth in simple OK and in OK BKGR=bkgr, dep ending on the system implementation. Failure case handling. When no answer comes within timeout interval (communication failure) the comp onent state is considered as abnormal, since the information loss on the so cket communication level is hardly p ossible. The fatal error o ccurred while executing the command is also the abnormal state of the comp onent. These two cases present the emergency situation which is sp ecially handled by the system manager (SV). When the reply is an ERROR message, this is mostly due to incompatibility of the command set implemented in a comp onent and utilized by the SV algorithms. This case also causes the emergency situation which needs to b e resolved by the system programmers. It is p ossible to intro duce the command rep eated sending in cases of the command loss (timeout situation), but it hardly currently seems to b e promising in troublesho oting. Meanwhile, this option may b e activated in future after getting some exp erience with working SV-driven systems. Command Keywords list. INIT - initiate the program service (bring online) to b e able to execute the commands from SV. If needed - p erform self-test which is sp ecified in the pro cess configuration file. Set the default settings in the system for working with SV. RESET - clear the message queue in the program. This command is of the highest priority and serves to resolve conflicts in communication. No reply is sent by the program once received this command. The program service (or device) is not reset or re-initialized PARK - shut down own services of a program and b e prepared to b e terminated. Optional parameter QUIT means PARKing and termination of the program. FREE - give the program control to the lo cal user console. This state continues until the next command from SV 24


GET - return the value of some parameter. Demands a parameter , which is a name of requested parameter. Exp ected reply is "OK =". Parameter-value pairs are NOT allowed, only the (not empty) list of requested parameter names is accepted. SET - set the new parameter(s) in the program. Most usual is setting the new ob ject. In this case, parameters are likely OBJECT=... RA=... DEC=... SPCL=... MAGV=... CIBV=... MODE=... etc, the exact list dep ends on the program to which this message is sent (E.g., the TLSP program demands normally the RA and DEC parameters only). Switches are NOT allowed, i.e. each parameter name MUST b e followed by the parameter value. RUN - start action. For telescop e - p oint to ob ject (normally, followed by "OK WAIT=..." and then "OK", for detector - start observation. Telescop e may p oint after a single RUN RA=... DEC=... command, i.e. without preceding SET RA=... DEC=... command. STOP - stop observation after end of current measurement (for TLSP - stop movement immediately). Optional parameter NOW demands to ab ort the measurement instead of completion.

C

Description of the observations scenario obs massdimm.tcl

The observations scenario, written in obs massdimm.tcl file, is a sp ecial Tcl-script and should b e run by means of Sup ervisor program only (version 0.12 or later). The aim of the scenario is to provide the joint work of the observational system comp onents - ob ject manager OBJM, telescop e TLSP, centering device CENT (which is part of DIMM or TLSP), corrector CORR (normally a function of TLSP) and two indep endent detectors MASS and DIMM - for astro climat simultaneous measurements. The mo de of observations the continuous monitoring of the most appropriate ob ject during the time of its go o d visibility. The guiding (p erio dic correction of the telescop e attitude) is p erformed simultaneously with measurements; the background level registration is made from time to time by MASS device after the shift of the telescop e by some distance and after temp orary canceling of the measurements and guiding. The algorithm is presented in a blo ck-scheme Fig. 3. The structure is expressed by separation of part of co de in several pro cedures (rectangles on a chart with three sections in each one), from which the general algorithm is constructed. The pro cedure name is given in the middle of rectangle, the upp er section list the names of control variables of algorithm (in capitals) and parameters of comp onents (capitals with parameter name in parentheses) from which the pro cedure p erformance dep ends; the b ottom section shows the variables affected by the pro cedure. The control variables drive the conditional transitions in the algorithm. Besides the pro cedures, the control variable assignments and usage of supplementary small functions (lower-case named) are also shown in blo ck-scheme. Finally, the dashed arrows p oint to the commands "after " using which the background delayed execution of some pro cedures or commands is realized. For example, the BACKGROUND pro cedure sets the BG NEED flag for own restart after a certain p erio d, while GUIDER restarts itself using after-command with another p erio dicity. The pro cedures themselves, depicted by rectangles, implement in turn the algorithms of more lo cal meaning with different degree of complexity. Their blo ck-schemes are not considered (b eing quite simple in most of cases) but the principles of work and some details are given b elow for them.

25


OBS_MASSDIMM

GETOBJECT
OBJM(RA,DEC), OVER, TEND

WTIME=getwtime(TEND) Y N wait() WTIME > 0 Y OBJM(RA,DEC), OVER BG_NEED?

BACKGROUND
MEASURING, BG_NEED=0 MEASURING = 1 MEASURING

after B_TIME:
BG_NEED = 1

N

SLEWTEL

GUIDER
CENT(STATUS), CENTERED

after G_TIME

CENTERED, BG_NEED

SEARCH
CENTERED

MAINMETER

WTIME=getwtime(TEND)

WTIME=getwtime(TEND)

N

CENTERED & WTIME>0?

Y

N MEASURING = 0 stop()

CENTERED & WTIME>0?

Y

Figure 3: Blo ck-scheme of the algorithm of observations with MASS/DIMM

26


C.1

Algorithm functioning

The work with any new star is started, obviously, with a selection of an ob ject (i.e. the star itself ) - this is GETOBJECT pro cedure. The accessibility of the star, which is the b est according to e OBJM, by the telescop e is checked as well, using the current or changed telescop e tub e orientation relative to the mounting. Normally for fork-typ e mountings the accessibility is always go o d. As a result, the needed orientation is selection (normally - the current one) and the limiting clo ck value TEND till which the star should b e tracked is derived (in seconds after 0h of 1 January 1970, i.e. in Unix-seconds). Using TEND the observations time WTIME is computed. If this is zero (no appropriate star is accessible, ... p ossible in principle), then the selection of a star is rep eated after some time (10 min). In the end of pro cedure, the ob ject is set in the comp onent programs MASS and DIMM by the command SET OBJECT=. The telescop e is p ointed to the selected star (SLEWTEL pro cedure) and the algorithm of the star search by the square-cornered spiral-like tub e movement around the exp ected p osition is started (SEARCH) until the star is found or the limiting radius of the spiral is reached. The found star is centered by GUIDER pro cedure. In case the star is either not centered (wind, or correcting problems) or not found (clouds?) - these two reasons are expressed by a single flag CENTERED - or the centering has consumed all the available observations time (p ossible as well) - the waiting pro cedure is again called and algorithm is restarted. When the star is successfully centered, the measurements b egin. First of all the background registration pro cedure BACKGROUND is called: it shifts the telescop e off from the star, sends the MASS the command RUN BKGR and shifts the TLSP back comp ensating for the p ossible backlash. After making these p erturbations, the setting of the BG NEED flag again in 1 is scheduled using the after-command. The time after which the flag will b e set is determined by the circumstances - the Sun and Mo on altitudes. After return from BACKGROUND the algorithm allows the star measurements setting the flag MEASURING to unity. The GUIDER started afterwards is executed only in case the MEASURING flag is set. It requests the current star displacement from the centering device and, with a negated sign and some alpha-regularization, this displacement is translated to the telescop e (correcting device). This is rep eated at most 3 times. After this the next restart of pro cedure is planned after some short time and the pro cedure exits leaving the flag of success determined - CENTERED. Note that GUIDER is also used by SEARCH. Finally, after centering, the MAINMETER is started which p erforms the cycle of the main measurements. It waits until one of detectors finishes measurements and, up on this reads the data string from this detector. Finally, it restarts the accumulation time measurements if the centering is not violated or BG NEED flag is still reset. Next, if the time is still left and the centering is Ok, the BACKGROUND, GUIDER and MAINMETER are called in case BG NEED is already set, or MAINMETER solely is restarted if not. The call to BACKGROUND resets the MEASURING flag which stops the self-starts of GUIDER. Background work is made, MEASURING is set back, GUIDER is revived and measurements are again p erformed - until the time is over (WTIME==0) or centering is violated due to clouds or wind (CENTERED==0). If one of two o ccurs, guiding and measurements are stopp ed and the algorithm of observations is restarted.

C.2

The list of control variables of algorithm

BG NEED : flag of necessity of background measurements. Set by background command execution scheduled in BACKGROUND. It is the condition to start BACKGROUND explicitly, the latter is not the self-restarted! BG NEED is reset by BACKGROUND. 27


CENTERED : flag of success of centering: star is found and is put within the working zone. TEND : limiting system clo ck value (in seconds after 1969) till which the ob ject measurements may b e continued (see OVER). MEASURING : flag of ongoing measurements - in practice it's a flag of telescop e centered on the star when the guiding and measurements are p ossible. Reset in BACKGROUND and after the end of ob ject observations time. Set explicitly after return from BACKGROUND. OVER : flag of necessity to change the telescop e orientation while slewing to ob ject. Set in GETOBJECT in case when the time of accessibility of ob ject in current orientation of telescop e is less than the time of ob ject visibility according to OBJM (i.e OBJM(tvis)¿TLSP(tvis)), but the opp osite orientation results in longer measurements series (i.e. TLSP(tvis2)¿TLSP(tvis)). WTIME : time left till the end of observations in seconds. Determined by getwtime() call from the current time and TEND.

C.3

Pro cedures of algorithm

Below we give the list of pro cedures of algorithm with the brief explanation of each one. The control variables used and/or determined are not listed b eing shown in Fig. 3 and explained ab ove. GETOBJECT - requests the ob ject manager the ob ject (numb er) with co ordinates and time of visibility. Determines the necessity of orientation change of telescop e. The latter implies that the solution ab out change is due to the mounting user (i.e. SV); if the orientation is selected automatically by TLSP, the pro cedure should b e simplified SLEWTEL - p oints the telescop e to the selected ob ject SEARCH - centering of the slewed telescop e on the star just as the star app ears in the field of view of centering device (e.g. DIMM). If the star is not found from the first shot, the spiral movement around the central p osition is made until the star is not found or maximal distance to the center p osition is reached. In principle, the identification of the found star is p ossible based on the stellar brightness check, but this is not currently implemented. Centering of the found star is made by GUIDER call (which is not self-restarting in this case since MEASURING flag is not set). BACKGROUND - stop the guiding and deviate the telescop e by some distance. Then register the background level using MASS. After this - move the telescop e backward by double distance and again forward to comp ensate for back-lashes. The time after which the background registration is again desired is determined by get bkgr p erio d() call. After measurement of background the BG NEED is reset and its setting is scheduled by the background command (after in Tcl) after the determined p erio d. GUIDER - iterative (at most 3 attempts) correction of the star p osition in the field of view by reading its shift from CENT and sending it negated to the corrector CORR. Explicit call is distinguished from the self-restart by the argument (default or not). In background (self )restart while the MEASURING flag is not set, neither iterative correction nor self-restart is not p erformed. The result - star found or not (CENT-result is co ded as +999 if not found) and centered (put within "working" zone) or not is expressed by the value of the single control variable CENTERED. MAINMETER - the main pro cedure of scientific measurements. Op erates with the identifiers of RUN-commands sent to MASS and DIMM detectors by which it waits for end of MASS or DIMM measurements. If one (or b oth) detector finish its own accumulation time, it reads its data. According to the values of CENTERED and BG NEED flags, either restarts the ready 28


detector or doing nothing. No explicit iterations or restarts is made - this is done on the global (algorithm) level. Thus, the current version of MAINMETER makes the measurements with two detectors ASYNCHRONOUSLY, with a maximal usage of the observational time. In future versions the mo dification is p ossible to implement the simultaneous start of b oth detectors after waiting for the one which finishes later. STOP - stops b oth detector measurements, disregarding their status. Resets the scheduled setting of BG NEED or start of GUIDER. Used in algorithm itself and in the BACKGROUND pro cedure. getwtime() - computes the time left till the end of observations of the current star as (TEND - seconds) or 0 if the result is negative. get bkgr p erio d() - determines the time span b etween the current moment and next background measurement using following condition: If Sun altitude is more than -20 degree, or Mo on altitude is p ositive but less than 15 degree, then this is 10 min Otherwise this is 20 min. This simple condition sp ecifying the p erio ds of the fast background level changes may b e replaced by some more sophisticated functional or, on contrary, by a simple constant.

C.4

Algorithm usage

The variables-parameters of algorithm (such as the p erio dicity of the guiding cycles etc.) should b e written in configuration file of SV (sv.cfg). Also, the name of this scenario obs massdimm.tcl must b e set in the parameter oscen in the first section (SV section, see main do cument). Afterwards, the comp onents participating in scenario are configured (MASS, DIMM, TLSP, OBJM and CENT and CORR which are the aliases of DIMM and TLSP, resp ectively). After this one may star Sup ervisor and observe the work of scenario by means of communication logging. For the debugging and control of the scenario p erformance the sp ecial utility viewlog.sh is useful.

C.5

Parameters of configuration file which tune the scenario work

Below we list the parameters put in sv.cfg for tuning the scenario p erformance without touching its file. The parameter name is given in parentheses after the name of section of the configuration file. SV(wait time) - time of waiting for "b etter times" in seconds CENT(n try) - numb er of attempts in GUIDER made to put the star in the central zone CENT(cent zone) - the size of circle within which the star shifts are neglected CENT(work zone) - work zone is a much larger circle compared to cent zone, where the measurements are valid CENT(alpha) - the regularization parameter for corrections (0.9 normally). CENT(p erio d) - the p erio dicity of calls of GUIDER in seconds TLSP(shift step) - step of the telescop e displacement by the hour angle or by declination while moving it along a squared spiral searching for the star TLSP(shift max) - the maximal displacement of telescop e from the center of a spiral by either of co ordinate while searching for the ob ject TLSP(bkgr shift ra) - displacement by right ascension for background registration TLSP(bkgr shift dec) - displacement by declination for background registration

29


SV communication log for 2003-10-23

OBJM GET MASS RUN MASS GET DIMM RUN DIMM GET CORR RUN TLSP RUN OBJM RUN

18.55

18.6 UT hours

18.65

18.7

Figure 4: XMGRACE output pro duced by the viewlog.sh utility

D

Visualization utilities for scenaria debugging

The utility viewlog.sh is aimed for the visualization of the comp onents communication during the execution of the SV scenaria with help of XMGRACE graphic utility. It draws the horizontal bars of different colors which reflect the busy-times of the resp ective comp onents; the color and ordinate of the bar designates the pair of comp onent name and the command keyword which viewlog.sh extracts from the log. The abscissa is the UT hours deciphered from the time stamps of the log. The b eginning of the bar denotes the moment when the command was issued; the tail of the bar denotes the rep ort ab out the command execution finished. In order to configure the utility, one must edit the viewlog.typ file and write a line there for each kind of a command which one wants to see on the graph. The first word is the ordinate of the series (in range, say, [1,10]), the second is the comp onent name (real or alias) and the third is the command keyword. Note, that the commands to the same comp onent which differ in parameters only cannot b e distinguished in a graph. The color is selected automatically. Then, the viewlog.sh must b e started with the name of the SV log-file, e.g.: $ ./viewlog.sh 031023sv.log It will first show the sets for drawing on the console and then start the XMGRACE program (version 5 or later) using the sp ecial parameter file viewlog.par. Use the menu Plot--Axis prop erties--x-axis for magnifying some time-span of the interest and adjust the x-axis tick marks corresp ondingly. Then you will see the picture like shown in Fig. 4

30


Zenith distance for 031019sv.log
40 35 30 25 20 21 21.5 22 22.5 23 23.5 24

Hour angle
-1 -1.5 -2 -2.5 -3 21

21.5

22

22.5

23

23.5

24

Figure 5: XMGRACE output pro duced by the viewhaz.sh utility Apart from viewlog.sh, there is another XMGRACE-based visualization utility ­ viewhaz.sh. It helps to see what's a change of the ob jects hour angle and zenith distance throughout the night. Its only parameter is the name of the SV log file. When started with log-file name, it extracts the "hour=..." and "zen=..." expressions from the log and plots the change of these parameters against the UT hours as shown in Fig. 5. As with viewlog.sh, you can tune the X-axis limits to magnify the p erio d of interest.

E
E.1

Sup ervisor programming issues (development engineer guide)
Intro duction

In current do cument we consider the ideas and principles on which the Sup ervisor programming is based. The general ideas of creation of a Sup ervisor program and organization of observations with help of SV and asso ciated comp onent programs are expressed elsewhere (see sup ervisor.txt and Combined MASS/DIMM instrument...Rep ort I., Kornilov et al, 2003).

E.2

Op erating system requirements and p ortability

SV is written in Tcl/Tk interpreted language and can b e run in any Linux system with Xwindows which has a Tcl/Tk package installed, together with additional freeware package extentions - namely Extended Tcl (TclX) and extended Tk (Tix). Latter packages improve SV functionality but are not obligatory since version 0.21. Since some op erating system dep endent 31


commands are executed by SV and its asso ciated comp onents (see for example, the current implementation of the Ob ject Manager, OBJM in ob jm.tcl), the p ortability of SV to other op erating systems where Tcl/Tk also runs is questionable but not imp ossible. Once a serious reason emerges to do it, the p ort will b e done, since ma jority of the SV co de is a pure Tcl which is platform-indep endent language.

E.3

Structure of the SV program

SV is considered as an extention of the standard Tcl commands which helps to easily organize the sequencing of the op erations with certain comp onents of the observational system with help of the commands exchange in a certain proto col describ ed in commands.tex (*.ps). To make the sequencing life even more easy, three basic pro cesses are completely separated from each other - the monitoring of the conditions, the preparations/cancellation of observations (when the conditions b ecome go o d or bad, resp ectively) and the observation actions chain itself. The first and third sequences (scenaria) run in different Tcl scripts and interpreters and have a very thin connecting thread with help of a reserved SV commands like start obs, stop obs and is observations now. In some resp ects SV mimics the idea of the VLT Sequencer but uses the own proto col of the commands communication b etween comp onents and SV and the own strategy of errors handling. The latter is completely separated from the monitoring and observational scripts. SV text is considered to b e completely indep endent from the task which it is aimed to decide. The application of SV to the particular observational system is made by editing the SV configuration file, from which it knows the list of comp onent programs and some few other parameters which help to communicate with them. All the other information in configuration file serves to the scenaria scripts only. These scenaria are the scripts which describ e the desired b ehavior of the system in details. In some resp ect, the observations and circumstance monitor scenaria represent the "sup ervisor" notion, and the SV program itself is only the background supp ort for this. Of course, in order to have the system working as we want it, the comp onent programs must supp ort the proto col of commands (see commands.tex) and p erform the related tasks correctly. The SV consists of a set of pro cedures which are glued with each other by the scenaria scripts and by the start-up pro cedure of SV - main{}. It runs on the event-handling base, i.e. once created the graphic interface, it executes the commands from the separate scenaria interpreters, from the GUI elements (buttons) and pro cesses the information got from the comp onents via op en so ckets. SV terminates with help of a sp ecial pro cedure terminate{}, which closes the comp onents correctly and removes the SV GUI window thus causing the main{} pro cedure (see b elow) to return and exit the program. The SV pro cedures b elong to the following classes: the start-up pro cedures called in main{}: reading the SV configuration file read cfg{}, creation of the SV GUI (Tk interface) create window{}, some validation of the scenaria scripts check scen{}. main{} also calls the multiple-access pro cedures connect{} and start monitor{} (see Fig. 6) the so cket-connection service: connect{} with comp onent identification checking, disconnect{}; the command service: the cmd{} utility to send a command to the comp onent, get reply{} so cket channel reading handler to pro cess the reply from the comp onent when it arrives; the helpful scenaria-oriented functions is cmd{} and wait cmd{} for checking the status 32


BEGIN

open_log

Init logging to file and to colsole

read_cfg
CFG file reading into global SV and comp-s param-s

create_window

Creation of GUI
connect

Connect components listed in CFG
check_scen

Check obs-s and monitor scenaria Trap SIGTERM to call terminate
start_monitor

Start the Circumstance Monitor scenario

Wait for GUI closing

END
Figure 6: Startup of SV algorithm

33


of the comp onent command execution and the runtime-created functions named the same way as comp onents to read the SV and comp onent parameters obtained from configuration file or requested from comp onents themselves; the batch-like pro cedures (macros) start obs{} and stop obs{} available to the circumstance monitor scenario to start/cancel observations; start monitor{} and stop monitor{} for engineer access (GUI control only) to activate/disactivate the circumstance monitor. The separate pro cedure terminate{} makes all actions in order to park and disconnect the comp onents correctly and cause SV to exit normally. The synchronization of calls to these batches is considered in a section I I I b elow; the batches start..., stop... and terminate use the lower-level utilities: for starting/stopping a scenario: start scen{} and stop scen{} which structure is very imp ortant for SV p erformance; macros initialize{}, stop park{} for sending the INIT and STOP, PARK commands to comp onents when it is needed. They trace execution of these commands and exit only when they are over; GUI pro cedures, including those called automatically by Tk "trace variable" commands up date buttons{}, cmd dialog{}, cmd issue{}, up date cmd array{}. The call to them is organized with help of Tk means in create window{} startup pro cedure; logging facility: op en log{}, add log{}, close log{}, time stamp{}; error-handling pro cedure problem{} (see section E.5 b elow). The start-up sequence is shown in Fig. 6. A numb er of utilities is called sequentially preparing SV to the normal functioning. Then, b efore starting the monitor, the signal trapping is made for the usual SIGTERM signal, which is sent by kill program as a default signal to the pro cess. Once trapping this signal, the terminate{} pro cedure will b e called. The same consequence is configured in GUI for the cross-button in the upp er-right corner of the window and for the "Terminate" button. Finally, terminate{} is called from problem{} in case some unmanageable errors is encountered. Trapping the signal is the only feature of the extended Tcl (TclX) package which is used in SV. That is why the conditional b o dy is put in main{} for trapping signal only in case the TclX package is activated correctly. This means that SV will work without TclX as well, but it will b e imp ossible to stop SV correctly from another machine. Most of other pro cedures in SV are self-explanatory, b oth by the name, content and by the comments emb edded in the pro cedure texts as well. Pro cedures are preceded by the comment headers shap ed in doxygen style (although no DOXYGEN version still exists for do cumenting of Tcl pro jects, unfortunately). Finally, the SV pro cedures are all emb edded in the single namespace "sv" with help of "namespace eval" command. Since a numb er of pro cedures is called from external scenaria scripts, they are exp orted to the global namespace with help of "namespace exp ort/imp ort" commands. These global names are aliased in turn by "slave alias" command in start obs{} and start monitor{} batches. In these pro cedures, the other pro cedure calls are made with sv:: namespace qualifier. The sv-namespace variables (global to pro cedures) are referenced in pro cedures as namespace-qualified. The idea of sv namespace refers to the earliest version of SV when no clear mechanism of the SV internal protection from the other untrusted scripts (scenaria) was intro duced. Currently it seems to b e excessive, since the interpreter which runs SV co de do not run any other scenaria or scripts. Namespace sv will b e p ossibly dropp ed in future development of SV.

34


E.4

Starting and stopping the observations and circumstance monitor

Both scenaria are considered to b e non-parts of the Sup ervisor, i.e. treated as (non-trusted) user-written co de. User here is a p erson who is familiar with current observational system structure (comp onent programs usage) and implementation of algorithms Tcl scripts. Since the co de of scenario is user-written, it is considered as a p otential source of errors or danger to the system integrity. That's why the scenaria are started in a standalone SAFE interpreters and not in the interpreter which runs the SV co de itself. The interface which is provided to the comp onent programs consists of a few "command"handling utilities (issuing the command to the comp onent - cmd - and tracing its completeness - is cmd and wait cmd) and, for the monitor scenario, also the commands to start and stop the observation scenario (start obs, stop obs) and to trace the flag of the observations status (is observations now command which returns the fact whether the observations interpreter is running now). Other functions are describ ed in Sec. 3. In addition, b oth scenaria have a reading access to the parameters of the comp onents and SV which are read from the SV configuration file or retrieved from the comp onents with help of GET or RUN commands with resp ective arguments. These commands have the same names as comp onents or "SV" and written in upp er-case. An argument to these commands is a name of the parameter in interest (lowercase). Since the starting and stopping of scenaria are not atomic pro cedures (they have certain and significant duration in time) there is a need to synchronize their calls from different "threads" of the SV p erformance (observation and circumstance monitor scenaria, GUI, remote program termination). For example, the starting of the scenario by the circumstance monitor may b e interfered by another start or stop from the other source, for example - from the button hit on the SV window. Other example is termination of observations: it involves normally the continued parking pro cess of the comp onents and it would b e strange to allow to reenter this parking from the other source (e.g. the monitor scenario stopping of observations and the remote SV termination). Starting of a scenario is made with help of the pro cedure start scen{} which creates an interpreter, aliases to commands within it and invokes the (hidden) source command with a needed scenario script file. Stopping the scenario is more tricky: it should cancel the evaluation of the scenario not violating the rest functionality of SV and the op erated system which demands dep ends on the particular task. That's why the reserved-name pro cedure end{} is searched for among the known scenario interpreter pro cedures. If found - it is started hoping that it will stop the observations sequence correctly which is the comp etence of the scenario-writer. Then the aliases are removed and interpreter is deleted and its variable is assigned zero. NOTE, that removal of aliases is formally excessive (since deletion of interpreter deletes aliases as well), but some machines running Tcl version 8.4 b ehave strangely: during ab out 1 sec they continue to execute the scenario commands AFTER the interpreter was deleted! This might b e the consequence of some bufferization made inside Tcl co de. What saves situation is a still immediate removal of aliases: the running script b ecomes blind and handless and cannot affect the system comp onents any more. A numb er of SV global variables are resp onsible for controlling the access to these pro cedures. They are used as flags or semaphores which allow or prohibit the execution of the b o dy of resp ective pro cedures. Here b elow we consider these variables: is_observations_now (1/0): fact that the observation interpreter runs the obs.scenario ->1 in start_obs\{\} just before starting sourcing obs.scen ->0 in stop_obs\{\} just after obs.interpreter is deleted 35


disable\_start\_obs (1/0): fact that starting of obs-s is not allowed ->1 in start_obs\{\} after beginning ->0 in start_obs\{\} before end ->1 in stop_obs\{\} called from the SV window button and terminate\{\} tclobs ("interp?"/0): obs.interpreter identifier ->[interp create -safe] in start_scen\{\} beginning ->0 in stop_scen\{\} after deletion (in the end) tclmon ("interp?"/0): circ. monitor interpreter identifier ->[interp create -safe] in start_scen\{\} beginning -\>0 in stop_scen\{\} after deletion (in the end) Pro cedures which are involved in pro cess of starting/stopping the scenaria are listed b elow. "Conditions" sp ecify the ones which should b e fulfilled to call the pro cedure. start scen{} : create interpreter for a given scenario assigning the given variable with the interpreter name, creates aliases, sources scenario catching its errors (which stop sourcing thus) Conditions: no stop scen{} : calls the end{} pro cedure in the scenario (if found), deletes aliases and interpreter itself, assigns its variable zero. Conditions: interp!=0 && no interp in stopping list start obs{} : start the obs.scenario with help of start scen{} Conditions: !disable start obs && tclobs==0 stop obs{} : delete obs.interpreter with stop scen{} Conditions: [tclobs exists] start monitor{} : start the circ.mon.scenario using start scen{} Conditions: tclmon==0 stop monitor{} : delete circ.mon.interpreter with stop scen{}. Parking of monitoring comp onents is made in terminate{}, so monitor normally do es not contain end{} pro cedure. Conditions: [tclmon exists] terminate{} : call stop monitor{}, stop obs{} if under way, stop park{} for all comp onents Conditions: non-reenterable (vwait-blo ck of is set to avoid rep etitive stop park{}-ing) GUI : buttons to call start/stop obs/mon{} and terminate{}, Conditions: switching of their active-state is made according to the value of the ab ovepresented global variables The mentioned conditions are verified in pro cedures themselves and used to activate/disable the resp ective buttons in GUI. Latter switching is only made to inform the op erator ab out the true state of the program, b ecause the pro cedures protect themselves from non-contemp orary calls. 36


end end disable_start_obs=0

Stop_obs

disable_start_obs=1 (if GUI) after 10 ms create command aliases tclobs = [interp create -safe] delete tclobs, tclobs = 0 disable_start_obs=1 is_observations_now=0 Start_obs catch {source obs.scen.} Play end{} if exists is_observations_now=1 delete aliases

end

Figure 7: Control variables in starting and stopping the scenaria. Dashed arrows denote errors (emerging in scenaria during use of deleted aliased commands or attempt to call a command in deleted interpreter) which cause catch-construct to work and thus stop scenario evaluation. When starting observations from the circumstance scenario, the is observations now{} function is used. It returns zero if the obs. scenario is not executed. The switching of the control variables describ ed ab ove is sketched in Fig. 7 on the example of starting/stopping observations. Actions p erformed b oth in start obs{}, stop obs{} and start scen{}, stop scen{} are presented. Checking listed in "Conditions" to resp ective pro cedures ab ove are not shown. In brief, the values of tclobs and tclmon are assigned to interpinitializers from the very b eginning and indicate that start *{} pro cedures are under way. When the pro cess is finished and the resp ective script commands started execution, the final flag is set ­ is observations now-¿1 in start obs{}. Start monitor{} do es not need such a final flag, since no such strong restrictions on its start apply. While stopping the scenaria, the scenario pro cedure end{} is called first, if provided. As any other, such a call is done within the catch-construction, to protect SV against the errors in untrusted scenario scripts. Then, the resp ective interpreter is deleted. Note, that the delayed execution may cause an attempt to execute the next scenario command on a background in an interpreter which do es not exist any more. This error is sp ecially caught by the catchconstruction in after-scripts started from start scen{} and has a sp ecial errorCo de IDELETE in Tcl which helps to differ it from other errors which may emerge from (erroneous and buggy) scenaria scripts. Such an error is a normal consequence of complicated time-diagrams of scenaria involving after-commands and is ignored when caught. The signal that stopping of the scenario and, p ossibly, parking of involved comp onents is over is assignment of the interpreter variable (tclobs or tclmon) to zero. This indicates to other parts of SV the p otential to start the scenario again. 37


E.5

Possible errors/failures o ccurring in Sup ervisor
error type

Startup errors: ErrName Proc Error

ENOCFG read_cfg no cfg sv.cfg found cfg EBADCFG read_cfg Single word in cfg FILE, not a comment cfg ENOPCFG read_cfg No obligatory parameter PAR found in CFG cfg ENOCMP connect Cannot connect to COMP connect ENMCMP connect COMP ident IDENT does not match IDENT from cfg cfg EBADSCE check_scen Scenario file not readable cfg

Execution errors: ECMDDSC cmd Attempt to send a command to disconnected COMP connection ECMPNEX cmd A command to non-existent component COMP cfg ECMDLOS cmd Timeout waiting for COMP reply comp.fatal ECMPDSC get_reply Lost connection to COMP connection ECMDID get_reply Unexpected reply: no command COMID sent to COMP comp.prog ECMDPAR get_reply Parsing reply: no param. value in REPLY comp.prog ECMDLOW get_reply Timeout waiting for COMP reply (after wait) comp.fatal ECMPFAT get_reply ERROR reply: fatal error in COMP comp.fatal ECMPSTA get_reply ERROR reply: cmd cannot be executed: STATUS scen ECMDKWD get_reply Unknown keyword: REPLY from COMP comp.prog ENOPAR Access to non-existent component parameter cfg ECMPNST stop_park COMP is busy after STOP NOW comp.prog ECMDSCE start_scen scen Actions due to errors: Startup errors: exit with error message (the op erator controls troublesho oting and SV restart)

Execution errors: o ccur after everything started up correctly ECMDDSC: ignore without messages (optional comp. may b e closed due to problems) ECMDID, ECMPNST, ECMDPAR, ECMDKWD (dangerous: unpredictable software b ehavior): so far - b ehavior the same as for ECMDLOS etc....... ECMDLOS, ECMDLOW, ECMPDSC, ECMPFAT: if some scenario pro cedure error handler {code comp} is found ­ execute it. If returned value is 1 or (in interactive==1 mo de) user selects to skip this error ­ return. Othervise: disconnect comp, issue error message (emergency sys), if comp(optional) exists (whatever value!) - return; else ­ stop obs, stop park, stop monitor, wait for SV(revive time) (if p ositive) and restart SV script. ECMPSTA: if status is BUSY - retry after status changes; if ERANG/ERSYN ­ ignore in case error is comp onent-dialog-caused or treate as ECMPFAT; otherwise ­ ignore with error message Unknown error co de: causes error in SV and call of emergency sys. Error handling Error handling strategy is based on usage of the common error handler which may either return or exit dep ending on situation and after making some trouble-sho oting actions. This handling of errors is concentrated in a single pro cedure problem {message code [comp] 38


[cmd]} in namespace sv, which is called in case some error state o ccurs. The call is made with following parameters: message error message (human-readable) co de error co de to classify an error and select actions to p erform in each particular case comp (optional): comp onent with which an error is asso ciated cmd (optional): command sent to the comp onent which caused an error state One or b oth last two parameters are empty defaults for errors which do not deal directly with comp onents. problem{} has a switch-b o dy where, for groups of errors listed ab ove, the actions describ ed there are p erformed. In case the normal functioning of SV should b e canceled, the terminate{} pro cedure is called and then SV exits. In some cases, after SV(revive time) seconds, SV will restart again. Note, that this should b e used with caution since the bug-caused restarts may blo ck the system filling it up with non-terminating SV instances. Before starting the switch-b o dy describ ed ab ove, the checking is done whether SV is currently terminating its work. This is done to avoid the infinite recursion of problem{} pro cedure due to secondary errors o ccuring while terminating. The only exception is the loss of connection: the lost comp onent is immediately disconnected to stop the events flow from its channel caused by the EOF state. Since intro duction of the (optional) interactive parameter, SV b ehaves here in two ways: if interactive ­ the choice for an op erator is given to by-pass the error situation somehow, i.e. not simply terminate, which is the only action made up on the serious error in interactive==0 mo de.

39