7 PROGRAMMER'S GUIDE

This chapter is intended to help programmers, who already have a working startup tool prototype and intend to complete its implementation by adding instrument specific features.

It is assumed here that the stoo module and the instrument software have already been properly installed and environment variables are properly defined. See chapter 9 for more information on this subject.

7.1 DEBUGGING FACILITIES

7.1.1 Log Levels

The startup/shutdown scripts log their actions to stdout or to a logging window. The logging window is used by default when no arguments are passed to the xxinsStart or xxinsStop scripts. If arguments are used, then logs are sent to stdout, unless the option -log is specified as the first script argument.

The log messages are more detailed if a higher log level is used. The log level of the startup/shutdown scripts is set as follows:

· Default log level: OCS.CON.LOGLEVEL value (0..5).

· Script option -loglevel <n>

7.1.2 TCL Errors

If xxinsStart and xxinsStop detect an error, an error message is reported. To report the complete TCL error information, use option -debug, e.g.

xxinsStart -debug

7.1.3 Internal Object List

The debug option -objList gives a quick overview of the instrument software as seen by the startup tool. The xxinsStart and xxinsStop scripts configure themselves according to the supplied instrument configuration. They build an internal tree of TCL objects that can be listed with option -objList:

xxinsStart -objList

E.g. the output in case of UVES is as follows:

-> INIT : Reading configuration from INS.cfg.

Repository STOOL

CONFIG INS

STARTUP INS

INSTRUMENT UVES

PANEL EXPMETERS

PANEL BOB

OS OS

PROCESS uvoOSMaster

PROCESS uvoExpCtrl_RED

PROCESS uvoExpCtrl_BLUE

PROCESS uvoSVCtrl_RED

PROCESS uvoSVCtrl_BLUE

PROCESS uvosvSVag

PANEL OS_CONTROL

PANEL OS_STATUS

TCS UT2

ICS ICS

PROCESS uviControl

PROCESS uviSimControl

PANEL ICS

DCS BLUE

PROCESS fcdconCI_ccdUvB

PROCESS fcditWs_ccdUvB

PANEL BLUE

PANEL BLUE_RTD

DCS RED

PROCESS fcdconCI_ccdUvR

PROCESS fcditWs_ccdUvR

PANEL RED

PANEL RED_RTD

DCS TCCD_BLUE

PROCESS ccdconCI_ccdUvSB

PROCESS ccditWs_ccdUvSB

PANEL TCCD_BLUE

PANEL TCCD_BLUE_RTD

DCS TCCD_RED

PROCESS ccdconCI_ccdUvSR

PROCESS ccditWs_ccdUvSR

PANEL TCCD_RED

PANEL TCCD_RED_RTD

PANEL ALARM

PANEL AUTOGUIDING

PANEL SENSORS

PANEL LOG

Object `CONFIG INS' allows to read the config. file, object `STARTUP INS' implements the main code to start/stop the instrument software. The rest of the objects describe the instrument software, in terms of applications (OS, TCS, ICS, DCS), processes and panels.

7.1.4 Internal Object Variables

When the startup tool is configured, some processes and panels may not start/stop as expected. The list of object variables of individual objects can be listed with the -objShow debug option. Please note that this option lists all public variables of an object and is supplied for detailed debugging. An understanding of all variables assumes having a deep understanding of the startup tool implementation and is beyond the scope of this manual.

E.g. the configuration of the UVES process uvoExpCtrl_BLUE is:

pl2 uves:~ 57 > uvinsStart -objShow PROCESS uvoExpCtrl_BLUE

-> INIT : Reading configuration from INS.cfg.

PROCESS uvoExpCtrl_BLUE {

-defaultPeriod = `100'

-defaultTimeout = `500'

-desc = `UVES OS blue exposure control'

-envName = `wuves'

-execCmd = `uvoExpCtrl blue'

-infoHeader = `UVES'

-loglevel = `0'

-msgTimeout = `10000'

-name = `uvoExpCtrl_BLUE'

-objId = `9'

-objParent = `::stooSTARTUP0.startup.instrument.os'

-objRepository = `::stooSTARTUP::rep'

-objType = `PROCESS'

-procName = `uvoExpCtrl_BLUE'

-startTimeout = `10000'

-useXterm = `0'

}

E.g, variable -execCmd specifies how the process is started: `uvoExpCtrl blue'.

Note that the usage of the variables depends of the implementation, in particular:

· DCS applications are started with the startup scripts supplied by the DCS software. The process objects are only used to verify if the processes are running after the startup, therefore e.g. variable -execCmd is not used.

· Instrument specific implementations may not use these variables.

7.2 INSTRUMENT SPECIFIC STARTUP CODE

If the startup tool customization done with the configuration files is not sufficient, then the startup and shutdown procedures of the individual applications can be modified replacing the corresponding standard classes with instrument specific code. It is recommended to place this code in a TCL script called xxinsStoo. Please see files stoo/test/stooTclfileExample.tcl and stoo/test/stooTestSpecialICSs.tcl for examples. The latter file describes how to use supplied code for STRAP and RTC.

Note that modification of startup and shutdown procedures should be avoided and only used as the last option.

7.2.1 Registering File xxinsStoo

The main source for script xxinsStoo is usually file xxinsStoo.tcl, i.e. add to the xxins Makefile the following lines:

TCL_SCRIPTS = xxinsStoo

xxinsStoo_OBJECTS = xxinsStoo

xxinsStoo_TCLSH = seqSh

xxinsStoo_LIBS =

Script xxinsStoo has to be registered in the xxmcfgINS.cfg file. This is done, adding the following keyword:

START.CON.TCLFILE "xxinsStoo"

7.2.2 The Global Array stooType

The startup tool implementation uses a global array to register all TCL classes that may be overloaded (or replaced). The array contains the following entries:

Array Index	Description	Default Value
STARTUP	Startup object that reads the config. files and starts/stops the applications and panels. This class has to be overloaded, if you wish to make adjustments to the internal instrument representation (see section 7.2.3).	stooINS
INSTRUMENT	Container of the internal instrument representation. This class normally does not need to be modified.	stooINSTRUMENT
OS	OS Application. Overload this class, if you have an instrument specific OS (see section 7.5.1).	stooOS
TCS	TCS Application. This class does not start/stop TCS. It only verifies that the TCS env. variables are properly set. This class normally does not need to be modified.	stooINS_TCS
ICS, ICS2, ...	ICS Applications. Overload one or more of these classes if you have an instrument specific ICS(s), e.g. STRAP or RTC. (see section 7.5.1).	stooICS
DCS_<type>	DCS Application. Register this class, if you have a detector of type <type> not supported by the startup tool (see section 7.5.1).	stooDCS_ACE stooDCS_FIERA stooDCS_IRACE
MIDAS	MIDAS Application. This class starts pco and inmidas. The standard configuration creates a MIDAS object. If your instrument does not use MIDAS, then this object can be deleted (see section 7.3.4).	stooMIDAS
BOB	BOB panel. This class normally does not need to be modified.	stooBOB
ALARM	ALARM panel. This class starts the RtapASDisplay panel. Replace this class, if you have an instrument specific alarm panel (see section 7.4.2).	stooALARM
UIF_CLASS	User defined uifClass for startup panel. See stooTestUSERCLASS.cfg , stooTclfileExample.tcl and stooTestStartup_uifClass.tcl for examples	No default

7.2.3 Example: Overloading Class STARTUP

To e.g. overload the STARTUP class, register the instrument specific class in the stooType array and supply the corresponding implementation. Add the following lines to the xxinsStoo.tcl file:

#########################################

# 1. register class xxinsSTARTUP

#

global stooType

set stooType(STARTUP) xxinsSTARTUP

#########################################

# 2. xxinsSTARTUP implementation

#

class xxinsSTARTUP {

inherit stooINS

public method Config { cfg } {

# run normal config.

stooINS::Config $cfg

# add own code

...

}

}

Note that the new class should normally inherit from the class registered as default value in the stooType array (see table above, i.e. in case of the STARTUP class, from stooINS). OS, ICS and DCS classes may inherit from class stooAPPLICATION.

7.2.4 Example: Using Specific startup code for STRAP and RTC

STRAP and RTC packages provide their own specific startup code in modules strapiws and macrtcws respectively that should be used. See file stoo/test/stooTestSpecialICSs.tcl for information how to incorporate this code into your application.

7.3 ADJUSTING THE INSTRUMENT CONFIGURATION

The standard startup procedure may need small adjustments, that are not available via the configuration keywords, but that may be applied changing the internal instrument description. This section describes some typical situations.

7.3.1 Adding a Single Process

To add a single process to a standard ICS or OS, proceed as follows:

1. Create class xxinsICS (resp. xxinsOS, similar as described in section 7.2.3 above) and inherit from the standard class stooICS (resp. stooOS).

2. Add the following lines to method xxinsICS::Config:

#*# start process xxiMyProcess

set procname "xxiMyProcess"

set obj [stooPROCESS $this.$procname \

-name $procname \

-execCmd "xxiMyProcess [<options>]" \

-envName $envName \

-desc "[Desc] MyProcess Description"]

AddObj $obj

A stooPROCESS object is created (see the stooPROCESS man page for details) [lines 1-6] and added to the application [line 7].

7.3.2 Setting an Option of an Application, Panel or Process

If an instrument needs to set a specific option (or variable) not available via the configuration file, then this option can be set as follows (e.g. to pass an argument to the xxiControl process):

1. Create class xxinsSTARTUP (see section 7.2.3 above).

2. Add the following lines to method xxinsSTARTUP::Config:

#*# pass <arguments> to the xxiControl process

set obj [LookupName xxiControl stooPROCESS $maxDepth]

$obj configure -execCmd "xxiControl <arguments>"

The xxiControl object is searched with the LookupName method inside the complete object tree [line 1]. The option -execCmd is set [line 2].

7.3.3 Changing the Startup Order of an Application or Panel

Script xxinsStart starts all applications bottom-up, i.e. starting with the last application displayed with debug option -objList (see section 7.1.3). This makes sure that applications needed by upper layers of the software are already running, when they are started (e.g. ICS, DCSs are started before OS). Panels are started from top to bottom, i.e. the first panel started is usually BOB. Instrument specific panels (created with e.g. START.PANELi.*) are normally appended at the bottom of the tree. If a particular instrument needs to start an application or panel in a different order, then the application or panel has to be moved within the internal instrument description.

For example, to have panel `START.PANEL1.NAME SENSORS' be started first, proceed as follows:

1. Create class xxinsSTARTUP (see section 7.2.3 above).

2. Add the following lines to method xxinsSTARTUP::Config:

#*# start first the SENSORS panel

set obj [LookupName SENSORS stooPANEL $maxDepth]

set parent [$obj Parent]

$parent MoveObj $obj 0

The panel is searched with the LookupName method inside the complete object tree [line 1]. The panel's parent is retrieved [line 2]. The parent is told to move the panel to the beginning (index 0) of it's object list [line 3].

7.3.4 Removing a Process or Panel

If a specific process or panel is not available and does not need to be started/stopped, then it can be removed from the internal instrument description.

For example, to remove panel xxopanStatus, proceed as follows:

1. Create class xxinsSTARTUP (see section 7.2.3 above).

2. Add the following lines to method xxinsSTARTUP::Config:

set obj [LookupName xxopanStatus stooPANEL $maxDepth]

set parent [$obj Parent]

$parent DeleteObj $obj

delete object $obj

The xxopanStatus object is searched with the LookupName method inside the complete object tree [line 1]. The parent of the panel is retrieved [line 2]. The panel is removed from the parent's list [line 3] and deleted [line 4].

7.4 INSTRUMENT SPECIFIC PANELS

The standard startup tool assumes that the instrument has a certain list of panels (see section 2.3.3). These panels can either be replaced or new panels can be added as described below.

7.4.1 Adding New Panels

Additional panels can be registered with the START.PANELi.* keywords (see section 6.14).

For example, to register a new panel SENSORS, register the following keywords in the configuration file:

START.PANEL1.NAME "SENSORS"; # Panel name

START.PANEL1.EXECMD "xxipanSensors"; # Command to start the panel

START.PANEL1.DESC "XXXX Sensors"

START.PANEL1.DEFAULT F;

7.4.2 Modifying/Replacing an Existing Panel

To replace an existing panel with an instrument specific one, make sure to register the corresponding name in keyword START.PANELi.NAME. The startup tool will remove the standard panel and replace it with the new one.

For example, to replace the ALARM panel with an instrument specific one, add the following keywords to the configuration file:

START.PANEL2.NAME "ALARM"; # Panel name

START.PANEL2.EXECMD "xxopanAlarm"; # Command to start the panel

START.PANEL2.DESC "XXXX Alarm"

START.PANEL2.DEFAULT F;

7.5 INSTRUMENT SPECIFIC APPLICATIONS

The standard behavior provided for OS, DCS and ICS are tailored to start/stop the software provided by the VLT Common Software: BOSS, ACE DCS, FIERA DCS and Base ICS. If an instrument does not use these software packages, then they probably have to supply their own startup classes to start/stop their applications. The XXXX Template Instrument supplies class samples for an instrument specific OS and ICS. Other application types can be implemented in a similar fashion.

7.5.1 Starting/Stopping an Instrument Specific OS or ICS

The startup tool gives the possibility of incorporating multiple ICSs in a single instrument. This includes ICSs based on STRAP and RTC. Each of them can be different and can have its own code supplied in the common tcl file specified with the keyword START.CON.TCLFILE. For back compatibility reasons the corresponding global array stooType has the element stooType(ICS) that corresponds to the first ICS (note no index in ICS) and then stooType(ICSi) for corresponding ICSi (i>1). Important note: If the startup class of the first ICS (i.e. stooType(ICS)) is overloaded with a specific code, all other ICSs with the default behavior (i.e. the ones without their own specific code) will be overloaded with the same class. Therefore, if stooType(ICS) is overloaded and you want e.g. ICS2 still to use the class stooICS, stooType(ICS2) must be explicitly defined, i.e. "set stooType(ICS2) stooICS", in the supplied tcl file.

File stoo/test/stooTclfileExample.tcl contains two sample classes: one for OS, another for ICS. These samples may be copied to file nninsStoo.tcl (if not already there) renaming all `xx' to `nn'. Make these classes known to the startup tool adding the following lines to the beginning of the nninsStoo.tcl file (see section 7.2.2):

global stooType

set stooType(OS) nninsOS

set stooType(ICS) nninsICS # or, e.g. "set stooType(ICS2) ..." for ICS2

These instrument specific classes may either inherit from their direct parent (stooOS, resp. stooICS) or from class stooAPPLICATION, according to what standard behavior you wish to maintain. The classes should overload one or more of the methods provided by an stooAPPLICATION: Config, Start, Stop, IsActive, IsStopped and Standby (see 10.3.1 for details).

1. Class xxinsOS

The OS class shows the typical way an instrument specific application startup might be implemented:

· Method Config consists of two parts:

The first loads the keywords from the configuration file needed to start the application (if any). The second part registers the processes and panels owned by the application. OS should have at least a main process (xxoControl) and panels OS_CONTROL and OS_STATUS. See the ctooPROCESS and ctooPANEL man pages for details of how to configure these objects.

· The default behaviour of method Start is to start all processes owned by the application (registered with method Config). The method can be overloaded if additional tasks need to be done, like e.g. sending a DEBUG command to OS to set it's logging level.

· The default behaviour of method Stop is to stop all processes owned by the application.

· Method Standby should set OS in state Standby. The method supplied by stooOS sends a STANDBY command to the first process owned by the application (i.e. the first process registered in method Config), the Standby method supplied by stooAPPLICATION does nothing.

As stooAPPLICATION inherits from classes stooBASE and stooLOG, the methods provided by these classes to e.g. read/write the OLDB and provide logs can be used by the instrument specific class. Class stooPROCESS provides methods to send messages to the process.

When script xxinsStart starts OS, it will first call the OS methods Config, then Start (to start OS) and finally method Standby (to place OS in state Standby). Script xxinsStop calls method Config, Standby and Stop. The panels are started/stopped by default, if their default variable is set.

2. Class xxinsICS

The ICS class shows an alternative way to start an application: If the instrument specific application already supplies a startup script, then this script can be called from xxinsICS::Start. This method is shown in the xxinsICS example (method Config anyway registers the ICS processes, to use the standard Stop method to stop the ICS processes).

7.6 INTERFACES

7.6.1 Human Interfaces

The human interface is mainly described in the User's Guide (chapter 4). It consists of the standard startup panel and scripts xxinsStart and xxinsStop. It is suggested to provide several desktop root menu entries as described in section 4.1.

7.6.2 Hardware Interfaces

None.

7.6.3 Software Interfaces

See previous chapters.

Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com