CHANGE RECORD

ISSUE

DATE

SECTION/

PAGE

AFFECTED

REASON/INITIATION

DOCUMENTS/REMARKS

1.0 / prep 1

20/12/2000

All

NOVEMBER 2000 - First Version

Update for MAR2001 RELEASE
1.1	08/04/2001	20,22,23,49, 52,81	VLTSW20010019-18: OCS.SUBSYST setup keyw no longer supported
		20 (49)	VLTSW20010017: always use INS.MODE is compulsory in the first SETUP
		11,31,36,54,80	VLTSW20010014: STOP cmd is not supported
		15,18,83	VLTSW20010054 : OCS.OCS.* à OCS.OS.*
		26,27,28	VLTSW20010012: no alias tables
		30	VLTSW20010044: db classes for each subsystem interface
		18,26,79	Config kw not supported OCSi.OCS.ALIAS
		25,26,42,51,77	Configuration file xxoControl.cfg->xxmcfgINS.cfg
		36	Cancel inactive exposures using command END
		37	Added description to FORWARD
		41	Added new sections in chapter 9.8 in SOS
		52	New section 11.10 db point/structure (FAQ)
		38	New section – binary tables

Update for MAR 2002 RELEASE
ISSUE	DATE	SECTION	REASON/INITIATION/REMARKS
1.2	20/03/2002	4	VLTI module
		9.8.6.2	VLTSW20010618 : Multiple ICS headers
		9.4.5	VLTSW20010575 : Wait –first VLTSW20020051 : reply to wait command (9.4.5)
		9.5	VLTSW20010044:Life cycle (present in MAR2001 but not mentioned in doc)
		0 9.8.6	VLTSW20010691: Partial header files New section
		9.8, 9.8.5.3, 9.8.6.3, 9.8.4	SOS (new feature in MARCH2002) Sos interaction new section 9.8.4
		9.7.2	Exposure status
		9.7.4	VLTSW20010724: substates
		9.7.1	last expoId (updates)
		9.4.3.1,9.4.3.2, 9.4.3.5	VLTSW20010104 : SETUP (new sections) While exp running; repeate ; redeclare
		9.4.6	VLTSW20010535: END cmd
		9.4.7	VLTSW20010682: Forward
		10.1	VLTSW20010013 :default startup
		7.7	VLTSW20010494: default mode
		9.2,10.3	User specifed cfg keyword (AppConfigure argument)
		7 7.2 7.5, 7.3, 7.6	Configuration (VLTSW20010010/13, VLTSW20010448) DBROOT, DBIFROOT OCS.INSi.HDRCAT , default values for DCS/OS cfg kw.
		7.4	VLTSW20010448: TELESCOP fits kw (OCS.TEL.ID)
		13	Maintenance of boss
		11	FAQ added questions
		Reference	updated
		Appendix	updated

Update for APR2003 RELEASE
ISSUE	DATE	SECTION	REASON/INITIATION/REMARKS
3	30/03/2003	7.7	VLTSW20020342- max number of modes
		10.2	VLTSW20020180 added overload able function SetupPostProc
		10.7	VLTSW20010458/VLTSW20020360/ VLTSW20020583 Operation bypassing the OS/SOS (new section)
		9.4.3.4	VLTSW20020256 SETUP –noExposure (new subsection )
		9.4.5 9.7.5 11.16	VLTSW20010669: WAIT -header Synchronization (new section)
		11.6.2	VLTSW20020478 additional fits header keywords at SOS level (new section)
		9.6.1	VLTSW20020427: supplementary 'arf' files are removed
		7.3	VLTSW20020281: added optional detector configuration keyword: OCS.DETi.WIPING to set wiping
		7.3	VLTSW20020280: added optional detector configuration keyword: OCS.DETi.STOP to leave detector ONLINE
		9.6	VLTSW20020431: auto add cfg and setup kws to FITS header VLTSW20010669: each exposure starts with a new empty header
		9.7.4	Added new substates
		6.6 10.3	New section about dictionaries Updated with dictionary info
		11.17	FAQ special online action
		9.4.3.3	Default mode (1 mode) – new section
		Appendix	CDT,dict,cfg updated

Update for APR2004 RELEASE
ISSUE	DATE	SECTION	REASON/INITIATION/REMARKS
4	30/03/2004	7.1	VLTSW20030249 - added new cfg kw OCS.CON.LOGLEVEL
		8	VLTSW20020505 - new 'image file naming' scheme is applied as default : "Standard-Naming"
		9.4.5	VLTSW2003312 - added new parameter '-cond' to command WAIT
		9.4.5	VLTSW2003350 - added new parameter '-all' to command WAIT
		7.1	VLTSW20030387 – new configuration keyword OCS.ARC.TIMEOUT
		9.4.3.4	VLTSW20030119 - SETUP cmd without paremeter '-expoId' specified is considered as -noExposure
		10.2	VLTSW20030388 - Added overloadable empty functions ApplImageHandleProc()
		7.3	VLTSW20030149 - When cfg kw OCS.DETi.STOP is set, cmd ONLINE is only sent when state is not yet ONLINE.
		9.4.9	VLTSW20030250 New command ACCESS
		9.6.3	New section: archiver process
		Appendix	Manpage,CDT, dictionary update

TABLE OF CONTENTS

1 Scope.............................................................................................................................................................................................. 10

2 Documents and Acronyms.............................................................................................................................................. 10

2.1 Applicable Documents.............................................................................................................................................. 10

2.2 Reference Documents................................................................................................................................................ 10

2.3 Acronyms.......................................................................................................................................................................... 11

3 Introduction........................................................................................................................................................................... 12

4 Overview..................................................................................................................................................................................... 13

5 User’s Guide................................................................................................................................................................................ 14

6 Getting Started..................................................................................................................................................................... 14

6.1 The processes of the Observation Software............................................................................................. 14

6.2 Initializing....................................................................................................................................................................... 15

6.3 Server class..................................................................................................................................................................... 15

6.4 State handling.............................................................................................................................................................. 15

6.5 Configuration................................................................................................................................................................ 16

6.6 Dictionary........................................................................................................................................................................ 16

6.7 Command handling.................................................................................................................................................... 16

6.8 Database events.......................................................................................................................................................... 17

6.9 Interfaces......................................................................................................................................................................... 17

6.10 Exposures.......................................................................................................................................................................... 17

6.11 OS as Super OS.................................................................................................................................................................. 18

6.12 Logging................................................................................................................................................................................ 18

7 Configuration Guide........................................................................................................................................................... 20

7.1 General system configuration keywords................................................................................................. 21

7.2 Configuration of the subsystems..................................................................................................................... 22

7.3 Additional detector configuration keywords...................................................................................... 24

7.4 Additional TCS configuration keywords................................................................................................... 27

7.5 Additional ICS configuration keywords..................................................................................................... 27

7.6 OS Subsystem Configuration Keywords........................................................................................................ 27

7.7 Instrument modes....................................................................................................................................................... 28

8 Setup Guide................................................................................................................................................................................. 31

9 Programmer’s Guide............................................................................................................................................................ 33

9.1 Initialisation................................................................................................................................................................. 34

9.2 The Server class............................................................................................................................................................ 36

9.3 Interface classes........................................................................................................................................................ 39

9.4 Standard commands................................................................................................................................................ 40

9.4.1 STATE Command and related functions.................................................................................................................... 40

9.4.2 State changing commands............................................................................................................................................ 41

9.4.3 SETUP Command........................................................................................................................................................... 43

9.4.4 START Command............................................................................................................................................................ 47

9.4.5 WAIT Command............................................................................................................................................................... 48

9.4.6 Other exposure control commands.............................................................................................................................. 50

9.4.7 FORWARD command..................................................................................................................................................... 50

9.4.8 Commands operating on fits file.................................................................................................................................. 51

9.4.9 Other Commands............................................................................................................................................................ 51

9.5 Database and database events........................................................................................................................ 52

9.6 The final image.............................................................................................................................................................. 53

9.6.1 Partial header files......................................................................................................................................................... 53

9.6.2 Binary Tables.................................................................................................................................................................. 55

9.7 Exposure............................................................................................................................................................................. 56

9.7.1 The exposure table......................................................................................................................................................... 56

9.7.2 Exposure status............................................................................................................................................................... 57

9.7.3 Functions accessing the exposure table................................................................................................................... 58

9.7.4 Main steps of exposure.................................................................................................................................................. 58

9.7.5 Synchronization.............................................................................................................................................................. 59

9.8 Super Observation Software (SOS).................................................................................................................... 61

9.8.1 Configuration of OS subsystem.................................................................................................................................... 62

9.8.2 Hierarchical setup keywords....................................................................................................................................... 63

9.8.3 Dictionary for SOS......................................................................................................................................................... 63

9.8.4 SOS interaction............................................................................................................................................................... 63

9.8.5 Command handling........................................................................................................................................................ 67

9.8.6 Creating the finale image file by SOS......................................................................................................................... 68

9.8.7 Not-BOSS-based OS as a subsystem of SOS............................................................................................................... 71

10 Observation Software Based on BOSS................................................................................................................. 72

10.1 Default Startup........................................................................................................................................................... 73

10.2 List of overloadable functions........................................................................................................................ 74

10.3 Additional configuration keyword.............................................................................................................. 75

10.4 Additional setup keyword.................................................................................................................................... 76

10.5 Add new command...................................................................................................................................................... 79

10.5.1 Send a message.......................................................................................................................................................... 80

10.6 Modifying existing command callbacks..................................................................................................... 80

10.6.1 Declare mode, detector, subsystem, exposure status.......................................................................................... 80

10.7 Operation bypassing the OS/SOS.......................................................................................................................... 81

11 FAQ and Troubleshooting.............................................................................................................................................. 82

11.1 Manual start up of BOSS OS.................................................................................................................................. 82

11.2 Parameter ‘-expoId’ in the commands........................................................................................................... 82

11.3 Subsystem list or instrument mode is not declared in the setup............................................... 82

11.4 Usage of command STATUS.................................................................................................................................... 83

11.5 Usage of command ADDFITS................................................................................................................................... 84

11.6 Add additional keyword to the fits header............................................................................................ 84

11.6.1 Example-1: Add keyword to OS image.................................................................................................................. 84

11.6.2 Example-2: Add keyword to SOS image file......................................................................................................... 85

11.7 Dictionary for OS......................................................................................................................................................... 86

11.8 Parameter ‘-detId’ in command......................................................................................................................... 86

11.9 Place of pre-processing functions.................................................................................................................... 87

11.10 Instrument with no detector............................................................................................................................. 87

11.11 Data base point ‘NewData’................................................................................................................................... 88

11.12 Additional Action when Exposure fails, succeeds or aborted.................................................... 89

11.13 Interface for subsystem that does not fall into any of the given categories................ 90

11.14 What to do when OS subsystem of SOS is not based on BOSS.......................................................... 91

11.15 TCS in the SOS structure.......................................................................................................................................... 92

11.16 File merging...................................................................................................................................................................... 93

11.17 Add Special Online Action...................................................................................................................................... 94

12 Installation Guide............................................................................................................................................................... 95

13 Maintenance............................................................................................................................................................................. 95

14 Reference.................................................................................................................................................................................... 96

14.1 Manpage of the bossControl............................................................................................................................... 96

14.2 Manpage of the bossSERVER class..................................................................................................................... 97

14.3 Manpage of bossAbortCB, bossStartCB, bossPauseCB…................................................................... 105

14.4 Manpage of bossEXPOSURE class...................................................................................................................... 109

14.5 Manpage of bossINSMODE class........................................................................................................................ 113

14.6 Manpage of bossINTERFACE_DCS........................................................................................................................ 116

14.7 Manpage of bossINTERFACE_CCD........................................................................................................................ 118

14.8 Manpage of bossArchiver.................................................................................................................................... 120

This page has been left intentionally blank.

1 Scope

This document describes the BOSS package.

2 Documents and Acronyms

2.1 Applicable Documents

The following documents, of the exact issue shown, form a part of this document to the extent specified herein. In the event of conflict between the documents referenced herein and the contents of this document, the contents of this document shall be considered as a superseding requirement.

Reference	Document Number	Issue	Date	Title
[AD 01]	GEN-SPE-ESO-19400-0794	2.0	31/10/1997	DICB - Data Interface Control Document
[AD 02]	VLT-SPE-ESO-10000-0011	2.0	30/09/1992	VLT Software Requirements Specification
[AD 03]	VLT-PRO-ESO-10000-0228	1.0	10/03/1993	VLT Software Programming Standards
[AD 04]	VLT-PLA-ESO-10000-0441	1.0	01/05/1995	VLT Science Operation Plan
[AD 05]	VLT-MAN-ESO-17210-0667	1.0	03/12/1997	Guidelines for VLT applications.
[AD 06]	VLT-SPE-ESO-17212-0001	2.0	23/02/1995	INS Software Specification
[AD 07]	VLT-SPE-ESO-17240-0385	2.1	15/07/1996	INS Common Software Specification
[AD 08]	VLT-ICD-ESO-17240-19400	2.6	17/11/1997	ICD between VCS and Archive
[AD 09]	VLT-ICD-ESO-17240-19200	1.0	29/10/1996	ICD between VCS and OH

2.2 Reference Documents

The following documents contain additional information and are referenced in the text:

Reference	Document Number	Issue	Date	Title
[RD 01]	VLT-MAN-ESO-17240-1973	2.0	03/01/2001	Template Instrument User Manual
[RD 02]	VLT-SPE-ESO-15400-0886	2.0	18/12/1996	XXXX ICS
[RD 03]	VLT-MAN_ESO-17110-0771	1.7	30/09/1999	CCS-Event Tool Kit –EVH
[RD 04]	VLT-MAN_ESO-17240-0853	1.1	06/05/1996	Objective SLX-OSLX
[RD 05]				VLT SW Installation
[RD 06]	VLT-ICD-ESO-17240-19400	2.0	17/11/97	VLT Archive System
[RD 07]	VLT-MAN-ESO-17240-0672	1.6	25/09/98	CCD Detectors Control Software-User Manual
[RD 08]	VLT-MAN-ESO-13640-1388	1.1	22/11/99	FIERA CCD Controller –Software User Manual
[RD 09]	VLT-MAN-ESO-14100-1878	1.2	13/12/99	IRACE DCS User Manual
[RD-10]	VLT-MAN-ESO-17240-2325	1.0	10/10/2000	Configuration Tool User Manual
[RD-11]	VLT-MAN-ESO-17240- 2153	1.3		Startup Tool

2.3 Acronyms

This document employs several abbreviations and acronyms to refer concisely to an item, after it has been introduced. The following list is aimed to help the reader in recalling the extended meaning of each short expression:


OS	Observation Software
BOSS	Base Observation Software Stub
XXXX	Template instrument
XXXX ICS	Template instrument ICS
XXXX OS	Template instrument OS
OS	Observation Software
SOS	Super OS. An OS that also controls OS.
<CAT>	Category denoting detector, instrument, telescope or OS subsystem
single exposure	One exposure.
parallel exposure	Exposures started at the same time
semi-parallel exposure	Exposures running simultaneously. Started at different time.

3 Introduction

This version of the UM describes the behavior of the BOSS package APR2003 version.

The Observation software is responsible for taking care of one single exposure or simultaneous exposures. OS coordinates the communication between the subsystems of an instrument (ICS, DCS) and the telescope.

The BOSS software (BOSS is short for base observation software stub) is designed to incorporate the common features of all observation software, while the OS that is based on BOSS should incorporate the specialties characterizing the instrument.

The observation software of a specific instrument therefore consists of a

· an instrument independent part (BOSS), and

· an instrument specific part (OS).

Boss includes the implementation of all the standard commands [AD 07]. In special cases, the default process can be extended. The communication with the subsystems takes place through interfaces. The package includes suitable interfaces for the most commonly used subsystems. When an exposure is finished, the VOLAC system [RD 06] is informed about the event (through a database point) to archive the image.

During the development of an OS one must exploit the features and functionality of BOSS as much as possible. This would make sure that the OS-es have the least size, and therefore make the maintenance of the software easier.

The development of an OS is described through an example [RD 01].

The implementation of the most commonly used extra features (such as additional command or keyword) are described in Chapter 10.

Before going through the details of BOSS, it is recommended to first install and run the template instrument [RD 01]. This way one can gain better understanding what an OS is doing.

4 Overview

The BOSS software package consist of the following modules:

Module	Description
ibac	Instrument Basic Application Classes Includes handling of logs, bits, strings, list ..
ixac	Instrument Extended Application Classes This module contains classes to handle common VLT data types (e.g. Short Fits Keywords, Database,…)
boss	Base Observation Software Stub Incorporates the implementation of the common properties of OS
osb	Interface module including the dictionary and CDT of boss ( ESO-VLT-DIC.BOSS, bossSERVER.cdt)
bossvlti[1]	Necessary only for VLTI instruments This small module contains the interface for ISS.

Release versions numbers:

MAR2001: boss 1.35.1.3, osb 1.12, bossvlti 1.2, ixac 1.37, ibac 1.26

MAR2002: boss 1.81, osb 1.20, bossvlti 1.5, ixac 1.43, ibac 1.29

APR2003: boss 1.106, osb 1.24, bossvlti 1.5, ixac 1.45, ibac 1.29

APR2004: boss 1.129, osb 1.28, bossvlti 1.6, ixac 1.46, ibac 1.30

5 User’s Guide

The Template Instrument User Manual [RD 01] introduces an example observation software based on BOSS. Users are suggested to first install and run the example described in this manual and then try the various features described in this manual.

6 Getting Started

6.1 The processes of the Observation Software

The Observation Software of an instrument consists of two processes:

· ‘Main Control Process’

It is a multipurpose process the functionality of which is described in detail in this document.

The name of the process is ‘xxoControl’ where xx is the instrument ID.

· ‘Archiver Process’ [2]

The ‘File Handler Process’ is an auxiliary process that handles the post-processing of data, i.e. merging image file with header files. The process also takes care of informing VOLAC when the final image is ready. The name of this auxilary process is composed of the string ‘bossArchiver_’ and the instrument id, e.g.: ‘bossArchiver_xxo’

BOSS takes care of the communication between the ‘Main Control Process’ and the ‘Archiver Process’. During this action a supplementary file with extension ‘.arf’ is created, which is removed after the final image is ready. (Note that in case the process is started up in debug mode the supplementary files are not removed but renamed as ‘.arf_’ after successful handling. In this case they are removed only during the re-start of the Archiver process[3].)

These processes must be started at the same time[4].

6.2 Initializing

There is a support class (bossCtrlMain.C) included in BOSS to support initialising and exiting CCS, initialising the boss ‘Main Control Process’, and setting the verbose level according to the command line options (see Chapter 9.1). The developers are recommended to apply it following the pattern of the main function of the template instrument [RD 01].

6.3 Server class

The heart of the boss package is the bossSERVER class. The default functionalities of BOSS can be altered when necessary.

The bossSERVER class includes special (normally empty) functions. In these functions (i.e. in their overloads) the implementation of the additional properties of the instruments should be placed.

Note that overloading other functions is also possible (as most of the function of the bossSERVER are declared virtual)[5], however it is not recommended.

In some cases the default properties of BOSS fully satisfies the requirement of an instrument. In this case the instrument can be startup based on its configuration and database using the auto startup functionality (see section 10.1).

6.4 State handling

The bossSERVER takes care of handling the states and sub-states of the instrument.

The states of the subsystems are [AD 07]: OFF, LOADED, STANDBY, ONLINE.

The state of the instrument is normally associated with the state of its subsystems and it represents the minimum states of all the subsystems. Therefore when one of the subsystems is state OFF, the global state of the instrument is also OFF.

Note that the OS process has a state itself, which is different from the instrument state and not connected to the subsystem states at all. It simply shows whether OS process is alive, thus it is either ONLINE or OFF.

When the OS process is ONLINE it can have the following substates: SETUP, OBSERVING, PAUSED, IDLE.

6.5 Configuration

The instruments are configured via Application Configuration Files. These files (that should be placed in a separate module) contain information about the individual subsystems and the OS of the instrument and also startup options.

The configuration of the OS of an instrument (Section 7) consists of the declaration of its subsystems (Section 7.2, 7.3, 7.6) and the instrument modes (Section 7.7).

6.6 Dictionary

The configuration and setup keywords are declared in dictionaries, where the configuration keywords are checked during startup and the setup keywords are checked during runtime.

The common configuration and setup keywords regarding the OS are specified in dictionary

ESO-VLT-DIC.OSB.

Any additional instrument specific configuration and setup keywords must be specified by the user.

The additional configuration keywords should be included in the dictionary ESO-VLT-DIC.<INSNAME>_CFG.

Note that as the configuration file is handled by the configuration tool (ctoo) the dictionary (which contains the additional configuration keyword) must be also set as part of the instrument configuration [RD-10]. Section 10.3 explains how to add additional configuration keywords.

Additional setup keywords (see also 10.4) should be specified in the dictionary[6] named:

ESO-VLT-DIC.<INSNAME>_OS.

The following dictionaries are automatically loaded by BOSS:

ESO-VLT-DIC.OBS ESO-VLT-DIC.OSB

ESO-VLT-DIC.TPL ESO-VLT-DIC.<INSNAME>_OS

ESO-VLT-DIC.DPR

6.7 Command handling

BOSS supports the handling of the following commands:

ABORT, ADDFITS, COMMENT, CONT, END, EXIT, FORWARD, OFF, ONLINE, PAUSE, PING,

SETUP, STANDBY, START, STATE, STATUS, WAIT, VERSION

Normally the commands are declared in templates and sent to an OS by BOB. Nevertheless the commands can be also sent directly to the OS (using e.g. testscripts or GUI).

Handling these commands BOSS takes care of the necessary communication between its subsystem. It sends (synchronous and asynchronous) messages to the subsystems and synchronises their replies.

The state and substate of the OS is updated according to the actions of the given command.

The default implementation of the commands callbacks are placed in the class bossSERVER.

For more information about the details of the procedures see Chapter 9.4.

6.8 Database events

During the initialization BOSS attaches database events to some of the database points of the subsystems of the instrument. These database events are playing an important role in the synchronization process of BOSS.

The addresses of the relevant database points - status, state, newdata - are given in the configuration file.

For more details see Chapter 9.5.

6.9 Interfaces

BOSS includes several interface classes through which the communication between OS and the instrument’s subsystems can take place. These are:

bossINTERFACE, bossINTERFACE_ICS, bossINTERFACE_TCS,

bossINTERFACE_OCS, bossINTERFACE_DCS, bossINTERFACE_CCD,

bossINTERFACE_IRACE, bossINTERFACE_TCCD, bossINTERFACE_FIERA

The subsystems are declared in the configuration file however the interfaces for them have to be declared in SERVER class of the instrument (see Chapter 9.2). Each subsystem must be coupled to an interface. It is also essential to build the database according to the subsystems.

BOSS stores the declared interfaces on its internal subsystem list. The interfaces are identified by the name of their belonging subsystem. (The names of the subsystems are given in the configuration file.)

6.10 Exposures

The exposures that can be handled by BOSS fall into the following categories:

Single exposure: Single exposure.

The looping TCCD (without image is saved) belongs to also this category.

Parallel exposures[7]: Two or more exposures are handled simultaneously. Exposures are started at the same time, and have the same expoId. Only one single START command is used to start the exposures (see Figure 1).

Semi-Parallel exposure: Exposures are running simultaneously (see Figure 2), however they are handled independently from each other, and each exposure has its unique exposure id. The exposures are started separately.

Figure 1 Example for parallel exposure

Figure 2 Example for semi-parallel exposure

Each time an exposure is declared by the user (through the command SETUP) BOSS adds the exposure to its internal exposure table, that is also represented in the database. The exposure table is updated each time when the state, mode, filename, etc of an exposure is modified (see also Section 9.7.1, Table 9). In case of error it could be useful to check exposure table.

The exposures are identified by their exposure id-s. Before an exposure can be started the detector (or detectors) with which the exposure is taken must be uniquely identified. (See also declaration of mode, and parameter detId of the commands).

6.11 OS as Super OS

An OS become SOS (see Chapter 9.8) when one or more of its subsystem is an OS. The configuration of an SOS (Chapters 7.6, 9.8.1) is similar to the configuration of a normal OS.

To setup the parameters of the subsystems on lower levels hierarchical keywords are used (see section 9.8.2)

6.12 Logging

Logging can help detecting bugs or understanding the behavior of the code. The different type of logs are declared in the module ibac. There are five types of logs, which will appear according to command line or start up options. Developers are recommended to apply these logs in the OS application. Please see below the usage of these logs (for more information, see man pages of ibac and ibacLog):

Warning log:

Log data into the standard VLT log file and to the stdout (if verbose is specified). the level is put to 1. This procedure is called when there are errors or abnormal events for application

WarningLog ("A configuration file has to be specified");

WarningLog ("Could not read database attribute %s.",dbaddr);

Info log:

Log data into the standard VLT log file and to the stdout (if verbose is specified). the level is put to 2. This procedure is called when operational mode is modified.

InfoLog("Checking FITS header file '%s'", fitsHdrFile);

InfoLog("Getting TCS FITS header at start of exposure");

Action log:

Log data into the database attribute dependent on the level specified. Log data into the standard VLT log file and to the stdout.

ActionLog(1, "Cleaning up done.");

ActionLog(1, "%s command failed", msg.Command());

Test log:

Log data into the standard VLT log file and to the stdout (if verbose is specified). The level is put to 3.

TestLog(" expoId: %d ; detector :%s ",expoId, (char*)detId);

TestLog("Handling the DB event from attribute '%.80s'",dbaddr);

Debug log:

Log data into the standard VLT log file and to the stdout (if verbose is specified). The level is put to 5. This procedure is called when users want more detailed debugging information.

Recommended to add at the beginning of each function.

ExtDbgLog("bossSERVER::OnlineCB()");

ExtDbgLog("bossEXPOSURE::GetSubsystems(expoId :%d)",expoId);

7 Configuration Guide

The OS is configured via configuration file [AD 07].

In this configuration file the basic information about the instrument (name, prefix, database) and its subsystems (that are to be controlled by the OS) must be declared.

The subsystems that can be handled by BOSS fall into the following categories:

DET: detector subsystem

INS: instrument subsystem

OS: OS subsystem (in case of SOS)[8]

TEL: telescope

These categories are also referred as <CAT> below. If there are more than one subsystem belonging to the same category they must be indexed.

Some keywords must be declared for all type of subsystems (Chapter 7.2) while others only for certain type of subsystems. Many configuration parameters have default values. When the default value is applicable the keyword can be omitted from the configuration. The optional keywords are written by italic letters in the tables.

The instrument modes (see Chapter 7.7) must be also declared in the configuration file to make the SETUP simpler.

The configuration file is handled by the bossSERVER class. It configures the interface classes for the given subsystems, and stores the defined modes in its internal mode table, that is also represented in the database. (See classes bossINS_MODES and bossMODES_TABLE_ENTRY on figure Figure 3.)

For an example of a complete configuration of an instrument please take a look at the configuration of the template instrument OS [RD 01] in the Appendix 1.

Note that the configuration of the ICS [AD 06, AD 07,RD 02] itself is also placed togethere with the OS configuration but here only the keywords relationg to the OS are described.

7.1 General system configuration keywords

Here only the keywords that are relevant to the OS are described.

Table 7.1 Configuration of the subsystems

Configuration keyword	Short description
INS.CON.ID	Instrument identifier
INS.CON.PREFIX	Name prefix for modules and servers
OCS.CON.OSDBROOT	Database point of the intrument OS itself (optional).
OCS.CON.ORIGIN	Origin
OCS.CON.RELEASE	Release date
OCS.ARC.TIMEOUT	Archiver timeout (optional).
OCS.CON.LOGLEVEL	Log level (optional).

The name of the instrument and the two letter instrument code always have to be supplied in the configuration.

Name of the instrument:

INS.CON.ID "XXXX";

Two letter instrument code:

INS.CON.PREFIX "xx";

Database address of the OS of the instrument:

OCS.CON.OSDBROOT “<alias>xxo”;

The default value for OSDBROOT is: “:Appl_data:<INS.CON.ID>:OS”;

Archiver timeout:

OCS.ARC.TIMEOUT 60;

The support process of the OS -called the ‘archiver process’- takes care of the merging of the images. Via this keyword the time -as default 60 sec- allowed to handle one image can be altered.

Loglevel:

OCS.CON.LOGLEVEL 1;

This is an optional configuration keyword, which only taken into account if the logging level otherwise not specified as command line option (see section 11.1). Value of this keyword should be 1 to 5 which corresponds to the gradual increase of Acton/Log/Verbose level (see also 6.12). Default value is 0.

General information about origin, release date can be supplied by keywords

OCS.CON.ORIGIN and OCS.CON.RELEASE.

7.2 Configuration of the subsystems

Table 7.2 Configuration of the subsystems

Configuration keyword	Short description
OCS.<CAT>.NUM	Number of subsystem belonging to the given category.
OCS.<CAT>i.NAME	name of the subsystem
OCS.<CAT>i.ACCESS	access mode of the subsystem: NORMAL, IGNORE,FORBIDDEN
OCS.<CAT>i.DICTi	Dictionary of the subsystem : ESO-VLT-DIC.XXXX
OCS.<CAT>i.ENVNAME	Environment name where process of the subsystem is running
OCS.<CAT>i.PROCNAME	name of process of the subsystem
OCS.<CAT>i.KEYWFILT	Keywords that are forwarded to the subsystem
OCS.<CAT>i.TIMEOUT	timeout for OS process
OCS.<CAT>i.DBROOT	The database address of the subsystem (optional).
OCS.<CAT>i.DBSTATE	db address of ‘state’ (optional)
OCS.<CAT>i.DBIFROOT	The database address of the subsystem interface (optional).

Number of subsystems - OCS.<CAT>i.NUM

The number of the subsystems of the given category is a required information for the startup tool [RD-11] therefore should be placed in the configuration file[9].

Note that this keyword is not available for TCS subsystem, as there can be only one TCS.

E.g.: OCS.DET.NUM 2

denotes that there are two DCS subsystems , e.g. one FIERA and one TCCD.

Name of subsystem - OCS.<CAT>i.NAME

The individual subsystems can be referred to by their NAME-s. The names can be up to 32 character long, nevertheless it is recommended to use short names.

E.g.: OCS.DET1.NAME “TCCD”

Note that in case of Unit telescope (TEL) the name is restricted to have the following values:

“UT1”, “UT2”, “UT3”, “UT4”. (UT0 can be used when TCS is in simulation)

Access mode of subsystem- OCS.<CAT>i.ACCESS

As the examples below show, the ACCESS of a subsystem can have three values:

OCS.DET1.ACCESS "NORMAL"

OCS.DET2.ACCESS "FORBIDDEN"

OCS.TEL.ACCESS "IGNORE"

In normal operation mode the subsystem process must be properly installed and ready to be started up. In this case the ACCESS modes must be set to NORMAL.

When the subsystem is IGNORED all request (i.e. messages) to the subsystem will be ignored, i.e. considered as successfully finished. This option can be used during development when the process for the subsystem is not yet available, or just simply make the tests quicker. When a subsystem is ignored its state has no impact on the global state of the instrument.

When during operation one of the subsystem goes out of order its access mode should be switched to FORBIDDEN. This forbids the usage of this subsystem. In this case all request to the subsystem are rejected (error message is sent).

Dictionary of subsystem - OCS.<CAT>i.DICTi

Only the ‘tail’ of the dictionary of the subsystem must be given, i.e: XXXX for a dictionary ESO-VLT-DIC.XXXX.

More then one dictionary can be supplied using indexes.

E.g.: OCS.INS.DICT1 "ICS_AA"

OCS.INS.DICT2 "ICS_BB"

Environment name - OCS.<CAT>i.ENVNAME

e.g.: OCS.INS.ENVNAME "wxxxx"

Note that the environment where the process is running, should not be given by environment variable, eg,.: $RTAPENV.

On the contrary, the environment variables are set according to the configuration file.

Keyword filter- OCS.<CAT>i.KEYWFILT

The keywords in the setup that match the pattern will be forwarded to the subsystem.

When more the one filter id given, they must be separated by a comma.

E.g.: OCS.DET2.KEYWFILT "DET2.*.*.*.*.*.*,DET.*.*.*.*.*.*"

Timeout - OCS.<CAT>i.TIMEOUT

Must be given in seconds.

E.g.: OCS.DET2.TIMEOUT 600

Database address of subsystem - OCS.<CAT>i.DBROOT

Must be supplied when other then default, e.g.:

OCS.DET3.DBROOT "<alias>fiera";

Default values:

DCS: "<alias><INS.CON.ID>:DCS:<OCS.DETi.NAME>"

ICS: "<alias><INS.CON.ID>:<OCS.INSi.NAME>"

TCS: "<alias>TCS"

OS: "<alias><INS.CON.ID>:DCS:<OCS.OSi.NAME>"

Based on the value of DBROOT other default database addresses -of state, newdata(DCS) and status (DCS)- are specifed.

Database address of state - OCS.<CAT>i.DBSTATE

The state (i.e. ONLINE, STANDBY, OFF) of the subsystems are stored in a database point.

In order to declare the global state of the instrument it is required to supply the database addresses of these point in the configuration file when other then default.

E.g.:

OCS.OS2.DBSTATE "<alias>yyo:status.state";

OCS.TEL.DBSTATE "<alias>TCS:tcsState.tcsSubstate";

OCS.INS1.DBSTATE "<alias>XXXX:ICS:PROCESSES:WS:icsControl.state";

Default values:

DCS (TCCD/FIERA): " <DBROOT>.opState"

DCS (IRACE): "<DBROOT>.:irace.state"

ICS: "<DBROOT>:PROCESSES:WS:icsControl.state"

TCS: "<RTAPENV>:<alias>TCS:tcsState.tcsState"

OS: “<DBROOT>:status.state”

Database address of interface - OCS.<CAT>i.DBIFROOT

The keyword specifies the root database address of the interface of subsystem. When database is declared as specified in section 9.5, the default values are applicable, and keyword can be omitted from the configuration.

The keyword is used for declaring the db address of the interface of the subsystem where configuration and runtime information (e.g. lifecycle for DCS) about the subsystem is displayed by BOSS.

Defaults:

DCS : "<OSDBROOT >:subsystems:<OCS.DETi.NAME>" , e.g. : "<alias>xxo:subsystems:fiera"

ICS: “<OSDBROOT >:subsystems:<OCS.INSi.NAME>” , e.g.: "<alias>XXXX:OS:subsystems:ics"

TCS: “<OSDBROOT >:subsystems:<OCS.TEL.NAME>” , e.g.: "<alias>xxo:subsystems:tcs"

OS: “<OSDBROOT >:subsystems:<OCS.OSi.NAME>” , e.g.: "<alias>sos:subsystems:xxxx"

where the database root of the OS (<OSDBROOT>) is specified[10] by the configuration kewyords : OCS.CON. OSDBROOT.

7.3 Additional detector configuration keywords

According to the type of the detector boss supplies deafult values the database address of status, state, and new filename. When the detector is not TCCD, FIERA or IRACE or the data are different then the default the keywords in Table 7.3 must be supplied.

Table 7.3 Additional detector configuration keywords

Configuration keyword	Short description
OCS.DETi.TYPE	Type of the detector ACE,FIERA, IRACE
OCS.DETi DBSTATE	db address of ‘state’ (when other then default)
OCS.DETi.DBNEWDT	db address of ‘new data file’ (when other then default)
OCS.DETi.DBEXPSTS	db address of ‘exposure status’ (when other then default)
OCS.DETi.WIPING	Start/Stop wiping of detectors during online/standby
OCS.DETi.STOP	leave detector ONLINE when the system is set to STANDBY

Type - OCS.DETi.TYPE

The TYPE of the detector is FIERA, ACE or IRACE according to the available detector subsystem interfaces. Based on the type of the detector, the default data for the database address of state, status, and newdata are declared. Therefore the database addresses below only have to be supplied when other then default.

Database points:

The database points for state, newdata, exposure status, specified by keywords OCS.DETi.DBSTATE, OCS.DETi.DBNEWDT, OCS.DETi.DBEXPSTS generate events that are captured by BOSS. The procedures that are executed in the event of their change are described in Chapter 9.5.

These data must be supplied when other then default. The default values are:

Type:TCCD or FIERA

OCS.DETi.DBSTATE " <DBROOT>.opState"; # e.g.

OCS.DETi.DBNEWDT "<DBROOT>.:exposures:exposure_1:transfer.fileNameUnComp";

OCS.DETi.DBEXPSTS "<DBROOT>.:exposures:exposure_1.expStatus";

Type: IRACE

OCS.DETi.DBSTATE "<DBROOT>:irace.state";

OCS.DETi.DBNEWDT "<DBROOT>:exposure.newDataFileName"

OCS.DETi.DBEXPSTS "<DBROOT>:exposure.expStatus"

Where DBROOT is specified by the keyword OCS.DETi.DBROOT, when other then default ( see section 7.2).

E.g.:

OCS.DET2.DBSTATE "<alias>tccd.opState"

OCS.DET2.DBNEWDT "<alias>tccd:exposures:exposure_1:transfer.fileNameUnComp"

OCS.DET2.DBEXPSTS "<alias>tccd:exposures:exposure_1.expStatus"

In Appendix 1 example for setting the database points for FIERA and IR DCS can be also found.

(Note that as default values are used the settings are commented out.)

Set Wiping- OCS.DETi.WIPING (optional):

When the keyword OCS.DETi.WIPING is set to true (i.e. ‘T’) it starts wiping the detectors during online and stops the wiping during standby. The OS sends the corresponding commands STARTWP, STOPWP to the CCD during the execution of commands ONLINE and STANDBY respectively. The default value of the keyword is ‘F’. (If the state is already in the desired value these commands will not be resent).

Leave detector ONLINE - OCS.DETi.STOP (optional):

When keyword CS.DETi.STOP is set to false (i.e. ‘F’) the OS leaves the detector ONLINE when the system is set to STANDBY. The default value of the keyword is ‘T’.

When the OS receives a normal STANDBY or OFF command (without the parameter ‘–subSystem’ specified), then these commands are not forwarded to the detectors that have their corresponding configuration keyword set to false:

OCS.DETi.STOP=F;

However, if the OS receives a STANDBY or OFF command to place a specific detector in the STANDBY or OFF state e.g. :

STANDBY -subSystem FIERA

the command is forwarded to the subsystem regardless whether or not keyword OCS.DETi.STOP is specified.

7.4 Additional TCS configuration keywords

Table 7.4 Additional TCS configuration keywords

Configuration keyword	Short description
OCS.TEL.ID	Sets TELESCOP kw in the fitshdr when TCS is ignored

The TELESCOP keyword that is placed in the final fits header is normally specified by the TCS subsystem. When the TCS subsystem is ignored but given on the subsystemlist of a selected mode (7.7), the TELESCOPE keyword still has to be included in the fitsheader. In this case its value is set as given by

the OCS.TEL.ID keyword in the configuration.

The OCS.TEL.ID must correspond to the given Telescope as declared in DICD. E.g.: For Unit Telescope i the value must be set to: 'ESO-VLT-Ui'.

Boss gives a log when keyword is not specified in the configuration. (The OCS.TEL.ID is checked when the acces of TCS is normal.)

7.5 Additional ICS configuration keywords

Table 7.5 Additional ICS configuration keywords

Configuration keyword	Short description
OCS.INSi.HDRCAT	Category of the ICS keywords in the final fits header (optional).

Keyword should be used when more then one ICS headers are merged together with the final imagefile. As the result of this keyword, the category of the keywords (INS.*.*) in the header file created by the subsystem will be replaced by the specifed category. Typically an index is added, (e.g. "INS3") but other specifications (e.g. "XXX INS") are also possible. The newly created keywords must be included in the dictionaries of the subsytem.

See chapter 9.6.1, 9.8.6.2 for more details.

7.6 OS Subsystem Configuration Keywords

An OS can also be a subsystem in case of SOS. The OS as a subsystem is configured by the same keywords as other subsystems. See Table 7.2.

Table 7.6 Additional OS configuration keywords (required only when OS subsystem is not based on BOSS)

Configuration keyword	Short description
OCS.OSi.DBSTATE	db address of ‘state’ (when other then default)
OCS.OSi.DBNEWDT	db address of ‘new data file’ (when other then default)
OCS.OSi.DBEXPSTS	Exposure status database attribute (when other then default)
OCS OSi PREFIX	Keyword prefix for SOS Setup keywords (optional)

The configuration keywords OCS.OSi.DBSTATE, OCS.OSi.DBNEWDT, OCS.OSi.DBEXPSTS specifying the database address of the state, newdata and exposure status respectively are only necessary when the subsytem OS is not based on BOSS. The default values are:

OCS.OSi.DBSTATE <DBROOT>:status.state;

OCS.OSi.DBNEWDT <DBROOT>.osNewData;

OCS.OSi.DBEXPSTS <DBROOT>:exposure.expStatus;

Where DBROOT is specified by the keyword OCS.DETi.DBROOT, when other then default (see section 7.2).

The setup keywords sent to SOS and intended to reach sub OS-es must be prefixed. The default prefix is OCSi (where i correspons to the category index). It is possible but not recommended to specify other prefix by the keyword OCS. OSi.PREFIX. (For more infirmation on SOS setup keyword see section 9.8.2)

For more information about super OS see Chapter 9.8.

7.7 Instrument modes

The modes of the instrument - that is declared as a series of SETUP parameters - can include SETUP values for the ICS, DCS, OS subsystems and also for the telescope as well. When an instrument mode is specified, the subsystems that are involved in the given mode must be also declared.

Setting up/or starting subsystems that are not on the subsystem-list are not allowed to. (A warning log appears on the logmonitor if setup includes a subsystem that is not on the subsystemlist.) Single exposures can be executed simultaneously only if they have the same instrument mode. Currently no proper check is included for these points in BOSS, so satisfying the above conditions are the user’s responsibility.

Note that the modes are always specific properties of the instrument. Declaring them makes the setup of the exposures simpler. [AD 07]

The selected mode always has to be specified in the first setup of an exposure. The setup of a mode can be only omitted when there is only one mode specified in the configuration (see section 9.4.3.3) or when previous exposure is repeated (see section 9.4.3.2).

The maximum number of modes is limited to 40.

Table 7.7 Configuration of instrument modes

Configuration keyword	Short description
OCS.MODEi.NAME	Name of the mode.
OCS.MODEi.SETUP	List of setup keywords together with their values.
OCS.MODEi.SUBSYST	List of the name of the subsystems involved in the mode.
OCS.MODEi.PATH	The instrument path that is connected to the mode.

To configure an instrument mode the keyword in Table 7.7 are used, as the following examples show:

# Instrument modes

# mode 1

OCS.MODE1.NAME "IR_IMAGING"

OCS.MODE1.SETUP "-function DET1.DIT 10 DET1.NDIT 1"

OCS.MODE1.SUBSYST "IRDCS ICS UT0"

OCS.MODE1.PATH "BLUE"

# mode 2

OCS.MODE2.NAME "GUIDING"

OCS.MODE2.SETUP "-file ccd.ref"

OCS.MODE2.SUBSYST "TCCD ICS"

OCS.MODE2.PATH "RED"

During the declaration of the OCS.MODE2.SETUP, the parameters ‘–function’ and ‘–file’ are used (similarly to the SETUP command).

Please note that the length of the NAME, PATH, and subsyst is limited to 64, 64, 256 characters respectively. The length of the SETUP declaration is limited to 256 characters. In case this is not enough (as normally) declare the setup values in a file and use the ‘–file’ parameter as shown in the second example (GUIDING mode).

The keyword OCS.MODEi.SUBSYST declares the subsystems that are involved in the given mode.

The instrument mode always has to be declared in the first SETUP of an exposure unless there is only one mode specified in the configuration file (see also Chapter 8). The mode has to be set by the keyword INS.MODE as the following example shows:

SETUP –expoid 0 –function INS.MODE IR_IMAGING

The INS.MODE setup keyword is also forwarded to the ICS subsystem together with the other INS*.*.* keywords (pattern declared in the configuration file by the keyword KEYWFILT) in the setup.

Please note that in the case one of the setup keywords, that is also included into the specified mode is repeated in the same setup, the value given in the mode will be set[11]. E.g. in case of

SETUP –expoid 0 –function INS.MODE IR_IMAGING DET1.DIT 5

the value of DET1.DIT will be set to 10.

When someone needs to overwrite a value declared in the specified mode, a subsequent SETUP command has to be sent (without specifying the mode). E.g.:

SETUP –expoid 0 –function INS.MODE IR_IMAGING

SETUP –expoid <id> –function DET1.DIT 5

In the above case the value of DET1.DIT is set to 5, and also the name of the mode is changed to ‘Undeclared’. Note that this will only effect the value of database point where the mode is stored (see also Table 9). However, the ICS will NOT get a new setup command with ‘INS.MODE Undefined’. Note that modification is only valid for the given exposure, the actual parameters of the mode can not be changed during SETUP. Therefore a subsequent command with ‘INS.MODE IR_IMAGING’ is sent the keyword DET1.DIT is set to 10 again.

In general when one of the mode setup keywords are redefined with different values the given mode cannot be identified any longer.

Nevertheless changing the path (using keyword OCS.PATH) is allowed and will not effect the name of the mode. I.e. in the following example the mode stored by OS remains ‘IR_IMAGING’.

SETUP –expoid 0 –function INS.MODE IR_IMAGING

SETUP –expoid <id> –function OCS.PATH “RED”

The detector(s) with which the exposure is taken must be present on the subsystemlist (that is specified by the given mode). BOSS automatically detects the detectors on the subsystem list and stores their names. See also exposure table (Table 9) in Section 9.7.1.

For example the following setup

SETUP –expoid <id> –function INS.MODE IR_IMAGING

declares the detector unambiguously. In the above case the exposure is taken by IRDCS.

If there are more then one detectors are on the subsystem list (declared by a given mode), the exposures can be started with any or all of the declared detectors on the subsystem.

When the exposure has to be started only by one detector only (and there are more detectors are specified on the subsystem list) the required detector has to be specified during the START command using the –detId parameter. E.g.:

START –expoId 1–detId IRDCS

When detId is not specified parallel[12] exposure will be started. I.e. START command is sent to all the detectors on the subsystem list simultaneously.

8 Setup Guide

Any SETUP keywords that are in the dictionaries of the subsystems can be given in the setup. One must make sure that the keywords are indexed according to the declaration in configuration file (see filter).

The keywords declared in the SETUP command are forwarded to the subsystems by BOSS. The command is successful when all subsystems set up the corresponding data successfully. (See tests of the XXXX Instrument [RD 01]).

There are special keywords for declaring the image name and for selecting an instrument mode. It is also possible to modify the elements of a selected instrument mode. These keywords are declared in the BOSS dictionary.

Do not include subsystem and mode configuration keywords in the setup!!

Also do not include setup keyword in the configuration!!

Table 8.1 Setup keywords

Setup keyword	Short description
INS.MODE	declare instrument mode (optional)
OCS.PATH	set the path (optional)
[13]OCS.DETi.IMGNAME	declare the image filename (required when image is to be saved)
OCS.DETi.NAMING	Set filenaming type (optional, default is standard naming)

Setting the image name by keyword OCS.DETi.IMGNAME:

The name of the image file is declared by the keyword OCS.DET.IMGNAME[14] in the SETUP. When this keyword is specified, BOSS first stores the name (for its internal use), and later (when an exposure is ready to be started) it takes care that the filename is set correctly according to the naming type. As default OS is using standard naming. This means that the given filename is automatically extended by a number indicating the day of the year, and a serial number.

OS takes care of setting the image filename for the detector (in charge) by sending a SETUP to the detector with the appropriate DCS setup keyword.

When the image filename is set as an empty string, i.e. : OCS.DET.IMGNAME “”, it is interpreted to take an exposure without saving the image. Not all the detectors support this. E.g. IRACE detector software returns an error when image filename is not set at the start of the exposure. BOSS DCS interfaces therefore include a check for this.

See examples for usage of SETUP keywords below:

SETUP "-expoId 0 -function INS.MODE IR_SPECTROSCOPY INS.DROT.POSANG 10.0 DET2.WIN1.UIT1 15.0 DET2.EXP.NREP 1 OCS.DET.IMGNAME testImage.fits"

SETUP "-expoId 1 -function OCS.PATH red"

Setting the Image naming with OCS.DETi.NAMING

The naming type can have the following values:

“Standard-Naming”

“Sequence-Naming”

“Request-Naming”

As default “Standard-Naming” is applied. According to this scheme the filename has the following format:

<imgname><doy>_<seq>_<imgext>.fits

where:

<imgname> : base filename without extention

<seq> : sequential number between 0001-9999

(see more detailed description at “Sequence-Naming”)

<doy> : day of the year 001-256

<imgext> : extention as specified by the setup keyword OCS.DETi.IMGEXT

When “Sequence-Naming” is applied, the filename is supplemented with 4 digits. When files with the given base name (specified by OCS.DET.IMGNAME) already exist this digit is increased automatically.

The first file will be named as:

<basename>_0001.fits

(Regardless whether or not file with name <basename>.fits exists already.)

Then all the following files are named as:

<basename>_0002.fits, <basename>_0003.fits, ….,<basename>_xxxx.fits,

When “Request -Naming” is selected, file with specified name should not exist already. During the start of the exposure an error is returned when file with the given filename already exists.

Once a particular detector’s naming type is setup it will remain until the user changes it again.

If the naming is not declared “Sequence-Naming” is applied as default.

Note1: When the TCCD is in simulation mode, always “Request-Naming” is set. As in this case TCCD accepts only special filenames (e.g. ccdImageLcuSim.fits).

Note2: When no index is given all the detectors naming type will be set, i.e.

OCS.DET.NAMING Request-Naming

sets the naming type of all detectors to “Request-Naming”.

Mode:

For more information on keywords INS.MODE, OCS.PATH see Chapter 7.7.

More information about the functionalities of SETUP command is found in 9.4.3

9 Programmer’s Guide

The main classes that construct the BOSS software can be seen in Figure 3. In this chapter, the roles of these classes are introduced in detail. It is important for the developers to understand the functionality of the relevant classes.

Figure 3 Class design of the module boss

9.1 Initialisation

The ‘main’ function of an instrument OS is supported by the bossCtrlMain class of the BOSS package.

The ‘main’ function of an instrument OS therefore should follow the example bellow:

static char *rcsId="@(#) $Id: xxoControl.C,v 1.14+ 2000/08/04 19:20:06 vltsccm Exp $";

static void *use_rcsId = ((void)&use_rcsId,(void *) &rcsId);

#include "bossCtrlMain.h"

int main(int argc, char *argv[])

{

bossCtrlMain mainHandler("xx",rcsId);

mainHandler.CreateServer( new xxoSERVER( "XXXX");

// Startup: Register to CCS, set defaults, parse runstring, create SERVER object

mainHandler.Init(argc, argv);

//Enter the main loop

evhHandler->MainLoop();

//Terminate : Deregister from CCS

mainHandler.Exit(EXIT_SUCCESS);

}

On the command line one can set the required verbose level[15], e.g. for debugging purpose set the highest logging level as:

xxoControl –v 5 –l 2 -noDate

The command line parameters are:

-l <level> set standard log level

-v <level> set verbose log level

-a <level> set action log level

-t <level> set timer log level

-h print this help

-version print the version number of the software

-noDate turn off the display of date in verbose log messages (written to stdout)

-noFileLine turn off the display of file name and line number in verbose log

messages (written to stdout)

-noExit when applicable, avoid that application exits in case of a problem

when starting it up.

-c <file> specify application configuration file

The instrument ID and the version of the module (typically the rcsId) must be given as arguments of the constructor function of bossCtrlMain[16]. The instrument ID (i.e. ‘xx’ in the above example) is used for identification of the processes. (The instrument ID must correspond to configuration keyword INS.CON.PREFIX. See also section 7.1)

When the instrument ID is ‘xx’ the processes of the instrument OS are named as follows:

xxoControl : ‘Main Control Process’

bossArchiver_xxo : ‘File Handler Process[17]’ :

The CreateServer function of bossCtrlMain as its names implies creates a new instance of the instrument’s OS SERVER class. Note that the OS SERVER class of the instrument has to be a child class of the bossSERVER class !

The developer of an instrument OS must supply the following data:

database address of the root point of the OS (e.g.: "<alias>xxo")
Name of the instrument (e.g.: "XXXX") (which has to correspond to INS.CON.ID

Specified in the configuration module, e.g. in xxmcfg/config/xxmcfgINS.cfg [RD-10]

dictionary ("XXXX_OS" for ESO-VLT-DIC.XXXX_OS) of the instrument (if there is )

These parameters must be given as arguments[18] [19] of the constructor function of the SERVER class.

The Init() function of the class bossCtrlMain regiters to CCS and also initialize and configure the instrument server by calling the Init() function of the SERVER class. See details of SERVER class including the steps of functions Init() and Configure() in the next chapter.

9.2 The Server class

The bossSERVER -as shown in Figure 4a - is an evh [RD 03] application. Figure Figure 4b shows the protected variables of this class, that can be accessed by the child classes.

Figure 4 a) The inheritance chain of the bossSERVER class.

b) Protected variables of the bossSERVER class

When a server class is created it carries out the following action as default:

bossSERVER::bossSERVER(char * InsName)

:bossDB_TASK(dbPoint)

{

// set the name of configfile, dictionary

// Saves the name of the root database point

// Resets error handling

// Create instance of : dictionary

// Check if exposure db root point exists

// Reset list of pending WAIT commands

// Sets state alignment

}

Additional processes can be added when necessary in the overloads. The bossSERVER has several protected variables (Figure 4) that are therefore accessible for the instrument servers (i.e. the child classes of the bossSERVER).

The Init() function of the class bossCtrlMain regiters to CCS and also initialize and configure the instrument server by calling the Init() function of the bossSERVER instance. See details of functions Init() and Configure() below.

ccsCOMPL_STAT bossSERVER::Init()

{

// Sets filter for application keywords

// Define the instrument mode keyword (INS.MODE)

// Add triggers in the setup

// Set action log database point

// Set db point for handling sub-systems

// optional: Set interfaces of the subsystems

SubsystemInterfaces()

// Initialise subsystems (DCS)

// Clear database

// Load dictionary, configfile

// Configure the system

Configure(char *configFile)

// Add callbacks

// optional user declaration: Application specific initialization post process

InitPostProc()[20]

// Initialise archiver interface

// Sets interface for the ‘file handler[21]’ process

// Configure archiver process interface

// Sets the expoId of the DCS-es to be undefined

}

The steps of the function Configure are shown below:

ccsCOMPL_STAT bossSERVER::Configure(char *configFile)

{

// If no config file is specified retrieve previously loaded file

// Clear 'appConfig' object.

// Load the configuration file

// Load extra-dictionaries if specified in the configuration file

// Configure the sub-system interfaces

// Load sub-system dictionaries

// Configure instrument modes

// optional user declaration: configuration through additional keywords

AppConfig()

// Dispatches application configuration keywords to keyword event handler

// Sets state of the Instrument

}

Some of the above steps are highlighted and marked as optional. These are the functions that can be or overloaded in the SERVER class of an instrument OS.

The function ‘SubsystemInterfaces’ has a default implementation in BOSS to generate the interfaces automatically based on the configuration file (During auto startup the default function is used (see section 10.1). When there are subsystems that do not fall into the predeclared categories (ICS, DCS, TCS, OS) the function ‘SubsystemInterfaces’ has to be overloaded specifying all the subsystem interfaces (see also section 9.3). Below you find an example how to declare an interface of a subsystem:

ccsCOMPL_STAT xxoSERVER::SubsystemInterfaces()

{

//#= Define a subsystem of an instrument

// bossINTERFACE_IRACE irdcsPtr_; // declared in header file

irdcsPtr_ = new bossINTERFACE_IRACE (“<alias>iracq”, “DET1”);

AddSubSystem (irdcsPtr_);

…

return SUCCESS;

}

To have a direct access to the interfaces declare them as protected variable in the header file of the class. In order to couple the interface to the subsystem (declared in the configfile) the database point of the subsystem and category together with its index must be given as an argument.

Always add the subsystem interface to the subsystemList (see next chapter) using the function:

ccsCOMPL_STAT bossSERVER::AddSubSystem(bossINTERFACE *subSystemPtr)

For an example please see the implementation of template instrument OS [RD 01].

Note that missing keywords in the configuration can be source of various errors. Make sure that the second argument of the interface corresponds to the category of the keywords in the configuration exactly.

In case additional configuration keywords are necessary to configure the system, these keywords have to be placed into the dictionary of the instrument OS, and the belonging implementation should go into the function:

ccsCOMPL_STAT bossSERVER::AppConfigure(ctooCONFIG *)

Note that functions InitPostProc() and AppConfigure () are just empty functions in BOSS. The function InitPostProc and AppConfigure are typically used during the declaration of setup and configuration keywords. See Chapters 10.3, 10.4 for more information how to declare additional keywords.

9.3 Interface classes

There are several interface classes available in the BOSS library that should satisfy most needs. The available interfaces are shown in Figure 5.

In special cases you might wish to overload some of these interface classes. (Refer to man pages of the interface classes). When new interface class is to be developed it must always inherit from the base class bossINTERFACE.C or from any of its child class.

Figure 5 Available interface classes in BOSS

The interfaces should be selected according to the type of the subsystem. Each interface class has its own database class, with the same name. It is essential to include the corresponding database classes of the interfaces into the database of the instrument.

For more information how to declare the connection between given subsystem, its interface, and its database, see the function SubsystemInterfaces of the bossSERVER class (Section 9.2). Example is given in the template instrument document [RD 01].

BOSS stores the declared interfaces on its internal subsystem list (see class bossINTERFACE_LIST on Figure 3.). The interfaces are identified by the name of their belonging subsystem. (The names of the subsystems are given in the configuration file.)

9.4 Standard commands

The bossSERVER class contains the implementation of all callbacks that are called whenever a standard command is sent to the OS process. The list of the standard commands [AD 07] can be found in the appendix.

As the there are all the commands callbacks are implemented in one bossSERVER class, ( and it is therefore consists of numerous functions) for maintenance reason it is shared among several files:

bossSERVER.C bossSetModeCB.C bossWaitCB.C

bossStateCtrl.C bossExitCB.C bossAddFitsCB.C

bossExpoCtrl.C bossStateCB.C bossCommentCB.C

bossStatusCB.C bossStateAlign.C

bossSetupCB.C bossForwardCB.C

Note: most of the commands supported by bossSERVER class have a <subSystem> parameter, which is used to forward the command towards software (i.e sub-systems) implicated in the control of the instrument.

The behavior of the standard commands can be changed. See following sections.

9.4.1 STATE Command and related functions

STATE ==>-state <STRING>

Returns the state and substate of the instrument in the format of:

ONLINE/BUSY

STANDBY/IDLE

Note the state and sub-state of the instrument are saved in the database under points ... . When the command STATE is received the function StateCB is executed, which reads these dbpoints :

evhCB_COMPL_STAT bossSERVER::StateCB(msgMESSAGE &msg, void *)

{

// Gets current value of the state form the db point ...

// Gets current value of the sub-state from the db point...

// Compose complete state i.e. STATE/SUBSTATE

// Sends reply

// Handles error when necessary

}

The instrument state is associated with the state of the subsystem. It shows the minimum state of its subsystems (or the state of the OS[22]).

Event is attached to the ‘state’ database attribute of each subsystems. (See also configuration in Table 7.2.) . When ‘ aligned state’ is true (i.e. ‘T’) every time when a subsystem’s state is altered the function evhCB_COMPL_STAT bossSERVER::StateEvtCB(evtEVENT_MSG& event , void *)

is called that checks and sets the overall state of the instrument.

9.4.2 State changing commands

OFF -subSystem <STRING> ==> -done <STRING>

ONLINE -subSystem <STRING> ==> -done <STRING>

STANDBY -subSystem <STRING> ==> -done <STRING>

The handling of these commands is carried out by the OnlineCB, StandbyCB, OffCB. These functions are reasonably simple and they are also similar to each other. The procedure of the online callback is shown below:

evhCB_COMPL_STAT bossSERVER::OnlineCB(msgMESSAGE &msg, void *userData)

{

// Check if execution of command is allowed in the current state

// Log action

// Gets current sub-state

// Set sub-state

// optional user declaration: Call pre-processing function

// Re-configure server according to the configuration file

// Handles command

// calls function StateCtrlCmdProc which executes the following:

//Parse message parameters

// If parameter '-subsystem' is specified

// send message to specified sub-system

// Else

// send command to all available sub-systems (except TCS).

// Wait sub-system reply(ies)

// Synchronize sub-system replies

}

A successful reply (i.e. ‘OK’) for these commands is given only when all the -not ignored- subsystems (see Table 7.7) has successfully carried out the given command. The state of the instrument is updated through database events (see chapter 9.4.1).

The developer of an OS can optionally include an additional step into the callback process by overloading the functions:

ccsCOMPL_STAT bossSERVER::OffPreProc(msgMESSAGE &, void *)

ccsCOMPL_STAT bossSERVER::StandbyPreProc(msgMESSAGE &, void *)

ccsCOMPL_STAT bossSERVER::OnlinePreProc(msgMESSAGE &, void *)

that are originally empty (returning SUCCESS immediately).

9.4.3 SETUP Command

SETUP -expoId <INTEGER> -detId <STRING> -file <STRING>

-function <STRING> -noMove <LOGICAL> -check <LOGICAL> -noExposure <LOGICAL>

==> -expoId <INTEGER>

evhCB_COMPL_STAT bossSERVER::SetupCB(msgMESSAGE &msg, void *)

{

// Check condition for execution of command

// Log action

// Sets the start time marker of the command

// Sets sub-state to 'SETUP'

// Handle setup command: parses command parameter

// If there is no setup keyword Return error

// Get/Check expoId specified in command

// Extracts application configuration keywords

// If application configuration keywords found

// Configure list of the sub-system interfaces

// Configure instrument modes.

// Handles instrument modes (if specified): adds setup keywords corresponding to the instrument mode

// Update database (add new exposure)

// Check if exposure is declared in the db

// Check instrument modes : check whether setup keywords influence the current instrument mode

// Calls keyword trigger dispatcher

// Extract OBS.* TPL*,DPR.* keywords to be placed in FITS header

// optional user declaration: call preprocessing function

// Forwards setup command to sub-system(s)

// Wait for sub-system reply(ies)

// Synchronizes sub-system replies

// Set the global exposure status inactive

// Sets sub-state to IDLE

}

In case of error happens during the SETUP, the exposure is cancelled. That means that it no longer exists and cannot be started. Should the setup sent to a running exposure fail, the exposure remains active of course- see 9.4.3.1.

When SETUP includes setup keyword of subsystem which is not included in the given mode BOSS logs the case on the logmonitor, but no error is returned.

Note that the parameters specified in the SETUP command refers to the OS exposures. BOSS modifies the setup parameters before forwarding it to the subsystems if necessary.

9.4.3.1 Allow SETUP while exposure is running

As default BOSS allows SETUP while exposure is running.

The situation is represented by the substate OBSERVING|SETUP which can be monitored by the databasepoint: : <alias>xxo:status.substateui. (see 9.7.2)

Users can restrict this option (when applicable) calling the function:

AllowSetupWhileExpRunning(ccsFALSE);

e.g. in the constructor of the overloaded bossSERVER class.

Note: Sending SETUP to a finished/failed/aborted/cancelled exposure is not allowed.

When the SETUP sent to a running exposure (e.g. altering the integration time) fails the users are informed by an error message, but the exposure is not affected by boss.

9.4.3.2 Repeat exposures

When same or similar exposures has to be carried out many times, it is worth to use the ‘the repeate exposure’ functionality to avoid superfluous setup imposed by e.g. the INS.MODE keyword.

Repeating exposure of course only makes sense when exposure has been previously set up successfully (otherwise error is returned). It is allowed to alter the setup of the repeated exposure by consequence SETUP commands.

To repeate an exposure omit the parameters ‘–function’ and ‘–file’ for the new exposure:

msgSend "" xxoControl SETUP "-expoId 0"

During the above setup no setup keyword is sent to the subsystems, but a new expoId is generated.

Note that as the new setup starts with an empty header TPL,OBS,DPR,OCS keywords must be sent again in order to place them in the fits header in a consecutive setup.

During START the previous exposure is repeated.

Examples of repeating exposure:

A) Typical case

SETUP –expoId 0 –function INS.MODE GUIDING …

START -expoId 1

WAIT -expoId 1

SETUP –expoId 0

SETUP –expoid 0 –function TPL*,OBS* ..

START -expoId 2

WAIT -expoId 1

B) Pre declaration of exposures

SETUP –expoId 0 –function ….

SETUP –expoId 0

START -expoId 1

START -expoId 2

START -expoId 3

Caution: Pre declared repeated exposures have to be started in order.

C) Special case

In a special case when one sets up a new exposure while an other is running, the expoId and/or detId should be always specified for the other commands sent to the exposures.

E.g.:

SETUP –expoId 0 –function INS.MODE OPT_IMAGING …

START –expoId 1

SETUP –expoId 0 - function INS.MODE OPT_IMAGING …

START –expoId 2

WAIT expoId 1 // wait for the exposure 1

In case the user forgets the specify the expoId (or optionally the detId) for the command

WAIT, the default expoId (i.e. for the last exposure is 2) takes places.

9.4.3.3 Default mode

The setup of a mode (INS.MODE) can be omitted when there is only one mode specified in the configuration.

When default mode is applied (i.e. the mode is not specified in the setup) the setup parameters of the mode are included in the setup until the first successful setup.

In the following setups the INS.MODE setup parameters will be only included if INS.MODE has been included in the setup or the global state of the instrument has been changed before.

In the special case of ‘one mode’ setup without parameter -functions is accepted for first setup:

E.g.: SETUP -expoId 0.

9.4.3.4 Setup bypassing exposures

As default boss automatically sets up a new exposure, or request an existing exposure for the SETUP.

In special cases the SETUP may not correspond to any exposures (e.g. there is no detector connected to the OS). In this case the parameter ‘–noExposure’ is applicable (for both OS and SOS) as the example below shows:

SETUP -noExposure -function INS.LAMPi.ST F

Functionality must be used with extreme caution not to interrupt running exposures!!

The case when neither the parameter -expoId nor the parameter –noExposure is supplied for the SETUP is extremely discouraged (nevertheless as default this would be understood as –noExposure).

Instrument mode:

When parameter 'noExposure' is given it is NOT compulsory to declare the instrument mode in the setup. However when INS.MODE keyword is found amongst the setup keywords, it is treated the same way regardless the parameter -noExposure is given or not in the setup. I.e.: The setup keywords belonging to the instrument mode as declared in the configuration file are sent.

Pre and Post processing functions:

The SetupPreProc() and SetupPostProc() functions are also executed during the setup which bypassing the exposures just like in case of a 'normal' setup. When these functions are dependent on the type of the setup, use the variable 'noExposure' as shown below:

ccsCOMPL_STAT xxoSERVER::SetupPreProc(msgMESSAGE &, vltINT32 expoId,void *)

{

if (noExposure) {..}

else {..}

return SUCCESS;

}

For existing instruments it is suggested to reconsider the content of SetupPre/PostProc() functions before applying the functionality of 'noexposure setup'.

9.4.3.5 Re-declaring exposure on CCD/FIERA

TCCD and FIERA detector software can handle only two exposures at a time: one that is running and one is to be prepare to be started. In order to avoid conflicts when a user tries to setup new exposures on BOSS without starting them, (i.e. sending consecutive SETUP commands with expoId 0) including keywords for a CCD, e.g.:

SETUP –expoId 0 –function INS.MODE OPT_IMAGING DET3.WIN.UIT1 10

after the execution of the second SETUP command the first exposure becomes INVALID. This means that it cannot be started. I.e.

START –expoId 4 will result in error.

This functionality was developed to make sure that templates can be always restarted, regardless the number of inactive exposures hanging around as a result of a failed or aborted template.

9.4.4 START Command

START -expoId <INTEGER> -detId <STRING> -at<STRING> Þ -done <STRING>

evhCB_COMPL_STAT bossSERVER::StartCB(msgMESSAGE &msg, void *userData)

{

// Check conditions of command

// If sub-state is IDLE Set sub-state to BUSY

// Get/Check expoId specified in command (as a parameter)

// Get filename

// Get/Check detId specified in command (as parameter)

// Preparation for the exposure:

// Get the detector declared by -detId parameter

// (otherwise detector(s) on the detector list[23])

// Check current exposure status of the given detector

// if exposure filename is not given display a warning log

// if exposure filename is given

// Check if there is enough disc place

// create file

// Set the image filename (by sending a SETUP to dcs)

// Set the status file name for the next exposure

// activate the databasepoint status

// Call pre-processing function

StartPreProcMain()

{ if (isImagefile) StartPreProc();else StartPreProcSpecial();}

// Send command to DCS/OS

// optional user declaration: Call post-processing function

StartPostProc()

// Send subsystem replies

// Short exposure action

}

When an exposure is started the db events attached to the status db attribute of the detector (or detectors) are activated.

(The status db attribute of the detectors is set in the configuration file (See Chapter 7.3). These db events have impact on the observation status, as well as on the releasing the pending wait commands.

In most callbacks the preprocessing and post-processing functions are empty functions. The StartPreProc is an exception, it calls tcsExpStart (during which the tifGetFitsStart process is executed) and the icsExpStart (which sends the EXPSTRT –path <inspath> command to ICS) as show below.

ccsCOMPL_STAT bossSERVER::StartPreProc(msgMESSAGE &, vltINT32 expoId,void *)

{

// send expstart to tcs

if (tcsExpStart(expoId)!=SUCCESS)

{

ErrAdd (bossMODULE_ID, bossERR_START_PREPROC, __FILE_LINE__ );

return FAILURE;

}

// send expstart to ics (to all of them if there are more then one declared)

if ( icsExpStart(expoId)!=SUCCESS)

{

ErrAdd (bossMODULE_ID, bossERR_START_PREPROC, __FILE_LINE__ );

return FAILURE;

}

return SUCCESS;

}

When the user wish to alter the START command overloading the StartPreProc and/or StartPostProc functions he must take into consideration the original functionality of the StartPreProc !

Note that StartPreProc is only called when image name is given for the exposure (i.e. image is created by the exposure. When image is not created the function StartPreProcSpecial (empty as default) is called. Both functions are called by the function StartPreProcMain which calles StartPreProc or StartPreProcSpecial according to the condition. All of these functions can be overloaded when reqired:

virtual ccsCOMPL_STAT StartPreProcMain(msgMESSAGE &msg, vltINT32 expoId,void *userData);

virtual ccsCOMPL_STAT StartPreProc(msgMESSAGE &msg, vltINT32 expoId, void *userData);

virtual ccsCOMPL_STAT StartPreProcSpecial(msgMESSAGE &msg, vltINT32 expoId, void *userData);

9.4.5 WAIT Command

WAIT -expoId <INTEGER> -detId <STRING> -first <LOGICAL> -all -cond <STRING> Þ -expStatus <INTEGER>

WAIT –detId IRDCS

WAIT –expoId 2

BOSS is able to handle more then one WAIT commands simultaneously.

The number of replies to wait command depends on the exposure status.

Only one reply is sent when the exposure is already FINISHED, FAILED or ABORTED.

Two replies are sent when exposure is running when WAIT command is received. The first reply is sent to acknowledge that WAIT command has been received and informs about the status, and last reply is sent when exposure is FINISHED, FAILED or ABORTED or specified condition is fulfilled.

Error reply is sent when exposure has not yet been started or the parameter ‘-expoId’ or ‘-detId’ is invalid. Error reply is sent also when exposure fails or it is aborted by the user.

When the parameter –all is specified the WAIT command refers to all running exposures, and return when all exposures has been finished failed or aborted or satisfy a specified condition.

It is possible to specify a condition to alter the timing of the final reply sent to the WAIT command. The values of this parameter can have the following values:

CanSetupNextObs [24] – Condition when new exposure can be setup without interrupting the currently running exposure. This condition is fulfilled when all the partial headers are collected from the subsystems and the telescope, i.e. when READING_OUT state has been reached on FIERA. (This option is only relevant for FIERA detectors. Regarding other detectors, the headers are collected when SUCCESS event is reached, therefore there is no difference between condition CanSetupNextObs and CanStartNextObs. )

CanStartNextObs [25] – Condition when next exposure can be started. I.e. the currently running observation has been successfully finished, headers from other subsystems has been collected and merging process has been informed to archive the image.

ObsEnd [26] – Default condition denoting the exposure is completed and the image file has been merged with headers and archived.

With the help of parameters ‘–cond’ and ‘–all’ the execution of the observations can be optimized for speed.

SETUP –expoId 0 –file <>,

START –expoId 1

WAIT –expoId 1 –cond CanStartNextObs

SETUP –expoId 0 –function <>

START –expoId 2

WAIT –expoId 2 –cond CanStartNextObs

…

WAIT –all

Also in an urgent situation (unforeseen event, e.g. exploding supernova) these options give way to the setup and start of a new exposure while safely ending a running exposure as fast as possible.

SETUP –expoId 0 –file <>,

START –expoId 1

END –expoId 1

WAIT –expoId 1 –cond CanSetupNextObs

SETUP –expoId 0 –function <>

WAIT - expoId 1 –cond CanStartNextObs

START -expoId 2

WAIT –all

9.4.6 Other exposure control commands

PAUSE -expoId <INTEGER> -detId <STRING> -at <STRING> Þ -done <STRING>

Pause the current exposure at a given optional time.

CONT -expoId <INTEGER> -detId <STRING> -at <STRING> Þ -done <STRING>

Continue a paused exposure at a given optional time.

END -expoId <INTEGER> -detId <STRING> Þ -done <STRING>

End the current exposure as soon as possible and read out the data. Image file is saved.

When this command is sent when the exposure status is still inactive (i.e. after setting up an exposure but before starting it) the exposure will be cancelled.

When command END sent to TCCD/FIERA that is looping, the OS (which receives the command) will send a STOP command to the DCS (rather then END command).

ABORT -expoId <INTEGER> -detId <STRING> Þ -done <STRING>

The command ABORT terminates all the currently running actions. The exposures are terminated immediately (no image is saved). The abort command replies when reply from the subsystem arrives. As the reply does not mean that the exposure has been already stopped it is recommended to send a WAIT command after ABORT before a new exposure is set up.

STATUS -expoId <INTEGER> -function <STRING> -global<LOGICAL>

Þ -status <STRING>

Get the status of the functions in the list of arguments.

See also the documents on DCS Software for more information about the ABORT, END commands [RD 07], [RD 08], [RD 09].

9.4.7 FORWARD command

FORWARD -subSystem <STRING> -command <STRING> -arguments <STRING>

Þ -reply <STRING>

This command forwards the specified command with a specified arguments to the specified sub-system. It returns the reply of the sub-system command as a string. When the specified subsystem is set to be ignored the command has no effect.

E.g.:

msgSend "" xxoControl FORWARD "-subSystem IRDCS -command SETUP -arguments \",,DET.DIT 20,,,\" "

Note that max length of parameter ‘–arguments’ is: 256bytes

9.4.8 Commands operating on fits file

ADDFITS -expoId <INTEGER> -detId <STRING> -info <STRING> ==> -done <STRING>

Add information to the FITS header.

9.4.9 ACCESS command

ACCESS -subSystem <STRING> -mode <STRING> [-info <LOGICAL > ]

Þ -reply <STRING>

The ACCESS command changes the ACCESS mode of the subsystems, i.e. IGNORE or NORMAL. The parameter -subSystem specifies the name of the subsystem the access mode of which is to be changed. Name should be given according to the configuration file. When set to 'ALL' the mode of all subsystems is changed to the specified mode. (Default value ALL.)

The parameter -mode specifies the mode, its value can be set to IGNORE or NORMAL.

If mode of a subsystem is set to be ignored, all commands that are sent to it are ignored.

(Default value NORMAL.)

If the parameter –info is specified the command returns information about the ACCESS mode of all subsystems. This parameter should not be used together with the other parameters.

E.g.:

Set all the subsystems mode to NORMAL:

msgSend "" xxoControl ACCESS ""

Returns information about all the subsystems:

msgSend "" xxoControl ACCESS "-info"

Set the access mode of the TCS to be ignored:

msgSend "" xxoControl ACCESS "-subSystem UT0 -mode IGNORE"

9.4.10 Other Commands

VERSION Þ-version <STRING>

Returns the version of the boss module and if there is the version of the toplevel instrument OS module.

VERBOSE -status <STRING> Þ -reply <STRING>

9.5 Database and database events

State handling

For each declared subsystem the database point where its state is stored must be know for the OS.

OS attaches database events to the databbase points of the subsystems (the access mode of which is normal). These events have impact on the global state of the instrument.

Exposure handling

In case of DCS subsystems OS attaches database events also to the database points ‘exposure status’ and the ‘newdata’(see Section 7.3). These events invoke the processes that must be carried out after the images have been created. E.g. the image must be merged with the header files produced by other subsystems.

Connection to VOLAC

The ready image files are archived by the VOLAC system. The VOLAC system is informed about new files through the database point: <alias>newData.newDataFileName.

Based on the application-supplied information OS_ROOT, this database point is created automatically.

To achieve this the application’s database (xxo.db) must include the osbEnv.db file (which includes boss.db). It is ensured that the database point ‘<alias>newData’ is only created once, regardless the number of OS-es in the system.

See Template instrument example Chapter 10 (xxo.db)., and Chapter 11.10 (FAQ) for more details.

Life Cycle

The status of the detectors are displayed under the databasepoint:

‘<alias>xxo:subsystems:<subsyst>:lifecycle’ as specified in VLT-SPE-ESO-17240-0385.

Where <subsyst> must be set to the lower case version of the subsystem name,

i.e. in xxoSERVER.class the database point for the ‘IRDCS’ sybsystem is set to ‘irdcs’.

CLASS bossINTERFACE_LIST xxodbSUB_SYSTEMS

BEGIN

ATTRIBUTE bossINTERFACE_IRACE irdcs

END

9.6 The final image

When the image file has been created by the detector, boss merges it together with header files (containing information about the other subsystems e.g. ICS, TCS or the DCS itself).

Each exposure starts with a new empty header, i.e. keywords that are retrieved from the setup are not reserved for the following exposures.

There are several keywords that are placed automatically in the fits header by BOSS retrieving the values from the configuration file or from the setup.

These fits header keywords based on the configuration are:

INSTRUME (according to INS.CON.ID)

ORIGIN (according to OCS.CON.ORIGIN)

INS.DATE (according to OCS.CON.RELEASE)

TELESCOP (according to OCS.TEL.ID)

These fits header keywords based on setup keywords are:

OBJECT (according to DPR.CATG,OBS.TARG.NAME , DPR.TYPE)

if (DPR.CATG=="SCIENCE") then OBJECT = OBS.TARG.NAME)

otherwise OBJECT = DPR.TYPE ( OBJECT is set to "" when keyword is missing)

OBSERVER (according to OBS.OBSERVER)

PI-COI (according to OBS.PI-COI.NAME)

Note that setup keywords starting by OCS.*.* , OBS.*.*, TPL.*.* or DPR.*.* are also automatically placed into the header.

Normally the users do not have to worry about the header merging process nevertheless during the development it is useful to know what temporary files are created (9.6.1 ).

It is also possible to specify additional binary tables (9.6.2).

9.6.1 Partial header files

Given the image filename (by a setup keyword OCS.DETi.IMGNAME) BOSS creates the final image file by merging the image file created by the DCS together with the header files gained from various subsystems. The partial header files are removed after successful merging.

Supposing that the filename is given as ‘myfile.fits’ the following files are created:

I) header file created by TCS or VLTI :

TCSHDR_<detId> _<expoId>.tcs or

TCSHDR_<detId> _<expoId>.iss

Where detId is the name of the detector that creates the ‘myfile.fits’ image and expoId is the serial number of the exposure. This file is created during EXPSTRT process and finished during EXPEND process.

II) header files created by ICS-es:

myfile_<subsName>_hdr.fits

Where subsName is the name of the ICS subsystem that creates the header.

This file is created during EXPEND. (STATUS command is sent to ICS to retrieve the header.)

III) header files created by FIERA or TCCD :

myfile.fits.det

Created when imagefile is ready.

IV) header file created by BOSS:

myfile_hdr.fits

This file contains the TPL/DPR/OBS keywords which has been included into the SETUP command. It also contains any additional keywords that are added during runtime by the commands COMMENT and ADDFITS.

(Data saved into this file at the end of the exosure.)

The extension of the header files created by the subsystems is declared by the subsystem itself. The boss interfaces adopt this information. See function bossINTERFACE:: GetStatusFits() for more details.

For the archiver process an auxiliary file is created with name: ‘myfile.arf', which is removed[27] after successful handling. This auxiliary file contains the name of the files to be merged, deleted.

Note that when requested (by the configuration keyword OCS.INS.HDRCAT) the archiver process changes the category in the header file as well.

All these files are collected under directory $INS_ROOT/SYSTEM/DETDATA/.

When SOS controls the exposure additional header files might be created.(See section 9.8.6 for more information.)

9.6.2 Binary Tables

In many cases there are additional information in form of binary tables that have to be included into the final FITS file.

Boss has a functionality to append binary tables to the image file automatically, when the following conditions are satisfied:

1) The file containing the binary table must be ready by the time the image file is ready

2) It is saved under $INS_ROOT/$INS_USER /DETDATA

3) It has the same name as the imagefile but extention ‘_btbl.fits’.

4) The file containing the binary table is a proper fitsfile, i.e. contains the binary tables as extentions.

The best is to create the binary tables using module oslx. See manpage of oslxFITS_EXT.

e.g. : myfile.fits will be merged with myfile_btbl.fits

Note that in case of VLTI instruments binary tables (names as: ‘<imgname> .bin<subsystem>’) created by ISS are automatically merged together with the image file.

9.6.3 Archiver process

The archiver process handles the supplementary files (*.arf) generated by the main process containing information about which files are to be merged together.

These files are stored under INS_ROOT and removed after their successful handling, unless the process has been started up in a debug mode.

The files to be merged, deleted or archived are appear as a list of files after specific keywords, e.g.: APPENDEXT, APPENDBIN, MERGE, APPEND, ARCHIVE, DELETE.

The communication between the main process and archiver, the format of the supplementary file, and the image handling is kept private. In case more files are necessary to be merged together with the image files the user are advised to apply the naming scheme and overload functions

CreateBtblFile(), GetSosUserFiles() (see also 9.8.6, 9.6.1, 9.6.2).

For experienced users it is also possible to work directly with the arf file pointer (See also 10.2 function ApplImageHandleProc()), however it is advisable to contact the BOSS developer before doing so.

In an unlucky event of the archiver process is killed (due to e.g. computer crash) there might be unhandled (and un-archived) image files left under INS_ROOT. In this case it is possible to restore these files after restarting the process. For each *.arf file under INS_ROOT/SYSTEM/DETDATA, running the following command:

msgSend “” bossArchiver_xxo ARCHIVE “-file imageFilename_00XY.arf”

See also section 6.1, 9.1, 10.1 on the archiver process.

9.7 Exposure

The bossSERVER class has a pointer to one instance of the bossEXPOSURE class (See Figure 3).

The bossSERVER class as well as the bossEXPOSURE class have access to the list of subsystems (see Figure 3).

The bossEXPOSURE class is responsible to keep track of the current and past exposures. Boss keeps track of up to 20 exposures. The ‘old’ exposures are removed from the table.

9.7.1 The exposure table

The bossEXPOSURE class keeps track of the current and previous exposures[28]. The exposures are collected in table at the following databasepoint:

<alias>xxo:exposure.currExposureTbl

where xx is the two-letters instrument code.

Table 9 Exposure table

expoId	Mode	Subsystems	Inspath	Detector	filename	State	expstrt
expo-1	Undefined	TCCD ICS TCS	BLUE	TCCD	myTCCD1.fits	COMPLETED	done
expo-2	GUIDING	TCCD ICS TCS	BLUE	TCCD	myTCCD2.fits	ABORTED
expo-3	IR_IMAGING	IRDCS ICS TCS	RED	IRDCS	myIR.fits	INTEGRATING	tcs,ics

The exposure table shows the main properties characterizing the exposures that are identified by the expoId.

The last property in the table is the expstart flag that is used by BOSS internally. This flag indicates whether there are processes running that must be finished before the final image can be created. (These processes are typically the EXPSTRT processes that prepare additional information that must be placed in the header.) The expstart flag is emptied when there are no such processes left, and switched to ‘done’ when the final image is created.

The id of the last exposure, the last inactive exposure, and the last invalid exposure are also represented under the database points:

<alias>info.lastExposure - last exposure (with the highest expoId)

<alias>info.lastInacivExp - last exposure that has been set up but has not yet been started

(Set to –9999 when there is no inactive exposure to be started)

<alias>info.invalidExp - exposure that has been automatically set to invalid,

because of a consequent setup of a new exposure

(e.g. trying to setup 2 exposures on the same CCD simultaneusly without starting any)

Initially (at startup) all these values are set to –9999.

The expoId of the last exposure and last inactive exposure are updated during setup and start command sent to the OS.

When there is no more inactive exposures left the lastInacivExp is set to –9999

9.7.2 Exposure status

The expostatus values are collected in the table below for reference:

*Exposure status*	*Value*
*inscEXP_UNDEFINED*	0
*inscEXP_INACTIVE*	1
*inscEXP_PENDING*	2
*inscEXP_INTEGRATING*	4
*inscEXP_PAUSED*	8
*inscEXP_READING_OUT*	16
*inscEXP_PROCESSING*	32
*inscEXP_TRANSFERRING*	64
*inscEXP_COMPL_SUCCESS*	128
*inscEXP_COMPL_FAILURE*	256
*inscEXP_COMPL_ABORTED*	512

On FIERA and TCCD there are additional expostatus values defined as shown in the table below:

*Exposure status FIERA/TCCD*	*Value*
*ccdEXP_LOOP_FINITE*	1024
*ccdEXP_LOOP_INFINITE*	2048
*ccdEXP_DONE*	ccdEXP_COMPLETED \| ccdEXP_FAILED \| ccdEXP_ABORTED
*ccdEXP_RUNNING*	ccdEXP_PENDING \| ccdEXP_INTEGRATING \| ccdEXP_PAUSED \| ccdEXP_READING \| ccdEXP_PROCESSING \| ccdEXP_TRANSFERING
*ccdEXP_LOOP*	ccdEXP_LOOP_FINITE \| ccdEXP_LOOP_INFINITE

BOSS interprets the exposure status values as described in the table below. In addition, boss also has some additional expostatus values:

*Exposure status boss*	*Value*
*UNDEFINED*	0	At the beginning when OS started up, no exposure has been defined. Or when status of DCS is undefined.
*INACTIVE*	1	Exposure has been setup but has not yet been started
*FAILURE*	256	Exposure failed. (Can be caused by many reasons, e.g. archiver process does not exists, expend process failed, exposure on dcs failed)
*ABORTED*	512	Exposure is aborted by the user. (considered as error)
*bossEXP_RUNNING*	1024	From the moment exposure is started till the end of the expend processes Until archiver process is informed that exposure is finished
*bossEXP_FINISHED*	2048	Exposure has been finished successfully, header data for merging has been collected.
*ossEXP_CANCELLED*	4096	An exposure that has been set up, but has not yet been started is cancelled by the user (sending command END). Global status is set to ABORTED.

Note: When boss BOSS encounters a complex exposure status (e.g. ccdEXP_RUNNING) it is interpreted as follows:

If it includes a FAILED member -> FAILED, if it includes a ABORT member -> ABORT

If it includes a PAUSED member -> PAUSED, otherwise RUNNING.

When more then one exposure is running (semi-parallel or parallel) the global exposure status is calculated.

9.7.3 Functions accessing the exposure table

The bossEXPOSURE class includes functions that operate on the exposures, and exposure tables. These are used internally. Below the functions, which retrieve useful information about an exposure, are listed.

ccsCOMPL_STAT GetLastExpoId(vltINT32 *expoId);

vltUINT32 GetGlobalExpoStatus();

char * ExpoStatus2Str(vltUINT32 expoStatus);

ccsCOMPL_STAT GetExposure(int expoId, char *mode, char *subsystems, char *inspath,

char *detector, char *filename, char *state, char *expstrt);

vltLOGICAL IsDefined (int expoId);

vltINT32 NoExposures();

ccsCOMPL_STAT GetSubsystems(vltINT32 expoId,char *subsystems)

ccsCOMPL_STAT GetDetector(vltINT32 expoId,char* detector)

ccsCOMPL_STAT GetFileName(vltINT32 expoId,char *filename)

ccsCOMPL_STAT GetInsPath(vltINT32 expoId,char *inspath)

ccsCOMPL_STAT GetExpstartFlag(vltINT32 expoId,char *expstrt)

vltLOGICAL CheckDetector( vltINT32 expoId, char *detId);

vltLOGICAL IsDetectorOnDetectorList( vltINT32 expoId, char *detId);

vltINT32 GetNumberOfDetectors(vltINT32 expoId);

For more information on other functions, see manpage of bossEXPOSURE.

9.7.4 Main steps of exposure

An exposure consists of the following main steps:

a) Setup of an exposure

Each exposure is identified by a unique number (expoId) during the setup.

b) Start of an exposure

- Preparation for starting the image

(e.g. setting the image file name)

- ‘expstart action’: Exposure start action during which ICS and TCS (on the subsystem list) are informed that an exposure is about to start.

c) Observation

- boss monitors the events (e.g. exposure status) generated by the subsystems.

d) End of exposure process

- ‘expend action’: ICS and TCS (on the subsystem list) are informed that exposure has been finished. (Note that when exposure is aborted, STOP command is sent to ICS, otherwise EXPEND command is sent).

- ‘merge action’: Preparation for merging the header files together

with the image file (informing the archiver process which files to merge)

- ‘image handling action’: handling and archiving the imagefile (done by a separate process,

but synchronsed with the main process)

- Reply is sent to pending wait commands

The steps of the exposures re also reflected by the substate of OS. (see also 6.4).

The substate of the OS is monitored through the database point: '<alias>xxo:state.substateui' :

The substate values are[29]:

*Substates of BOSS*	*Value*
*UNKNOWN*	0
*NOT_RUNNING*	1
*LOADED*	2
*IDLE*	4
*BUSY*	8
*SETUP*	16
*OBSERVING*	32
*PAUSED*	64
*OBSERV/BUSY*	40
*OBSERV/SETUP*	48
*OBSERV/PAU*	98
*OBS/PAU/SET*	114
*OBS/EXPSTRT*	160
*OBS/EXPEND*	288
*OBS/MERGE*	544

Complex sub-state values are formed from OBSERVING|SETUP to represent the situation when setup is sent during a running exposure. Sub-states OBS/EXPSTRT, OBS/EXPEND and OBS/MERGE represents the situation when OS executes an action while the exposure is running. (Note that often expend and merge action are still running after DCS has been finished the exposure. In this cases the sub-state indicates that the OS is still carries out actions concerning the exposure).

The complex sub-state OBSERV/BUSY denotes the case when OS handling a command while observation is running.

The complex sub-state OBSERV/PAU happens during semi-parallel exposures when one of the exposure is running and the other is paused. If a setup command is sent at this time the sub-state should change to OBS/PAU/SET.

9.7.5 Synchronization

The various actions (expstart, expend, merge, explained in the previous section 9.7.4) during the exposure must be handled with care as they are dependent on each other, on the exposure status and new data event. BOSS keeps track of the status of these steps and events via an internal synchronization class, which can be enquired for information at any time.

This internal class checks also the conditions whether an action regarding to an event is executable or not. The following conditions apply to the various steps:

Expstart action: The expstart action is executed before (as default) or after START command is sent to the DCS. It can be executed when DCS is idle, i.e. when previous exposure if any has been already finished, failed or aborted. If this condition does not apply error is returned.

Expend action: This action is executed when expstart action has been carried out successfully and READING_OUT status has been reached or passed. Error is returned if expstart action has previously failed. (Internal error is reported should the merge action occur before this step.)

Merge action: This action is executed after expend is done and the exposure finished successfully and new image file has been created. This synchronization is necessary to make sure that when exposure has finished successfully the new image file is ready. This can happen when integration time is very short.)

When a subsystem status changes or it creates a new image file the event is captured by the OS and checks whether the prerequisites of the corresponding actions are satisfied. If yes it executes the action otherwise sets a flag to mark that the action must be executed later. At the end of the start procedure a special check is included to handle short exposures (i.e. when due to short integration time the exposure is already finished).

The synchronization makes sure that the actions are only carried out once.

9.8 Super Observation Software (SOS)

SOS is an OS which controls other OS-es.

The example in Figure 6 shows an SOS which controls two instruments XXXX and YYYY (i.e. two OS-es) besides its own ICS and the Telescope.

Figure 6 Example for SOS

Start up of SOS

First start up the subsystems and finally the SOS.

Structure of SOS

It is not recommended to design an SOS with a direct connection to DCS[30].

It is the user’s responsibility to ensure that there is only one TCS/VLTI (with access mode normal) in the whole SOS structure.

It is suggested to place the TCS at top level, but other arrengments are also possible. For test purpose or standalone operation of the sub OS-es, it is allowed to include TCS in the configuration of more then one OS-es, however their access mode have to be set to ‘ignored’ when SOS is in charge of the controlling the system.

SOS exposures

It is allowed to take test exposures with the sub-OS-es before SOS has been started up. Exposures should not be taken directly by the sub-OS–es while SOS is ONLINE.

Should you wish to test a sub-OS without its Super OS, set the SOS to STANDBY or shut it down. SOS cleans up its sub-OS-es when its state is set to ONLINE.

Parallel exposures[31] are not supported at SOS level. This means that when parallel exposures are required they has to be specified as semi-parallel exposures.

9.8.1 Configuration of OS subsystem

The configuration of an OS subsystem follows the pattern of the configuration of other subsystems (Chapter 7.). See example below:

# Configure the XXXX instrument

OCS.OS1.NAME "XXXX" # name of the OS subsystem

OCS.OS1.ACCESS "NORMAL" # access mode of the OS subsystem

OCS.OS1.ENVNAME "wbos" # environment where proc. is running

OCS.OS1.PROCNAME "xxoControl" # name of the OS process

OCS.OS1.KEYWFILT "OCS1.*.*.*.*.*.*" # keywords to be forwarded to subsyst

OCS.OS1.TIMEOUT 6000 # timeout for the process

OCS.OS1.DBSTATE "<alias>xxo:status.state" # db address of 'state'

# Configure the YYYY instrument

OCS.OS2.NAME "YYYY" # name of the IRACE detector

OCS.OS2.ACCESS "NORMAL" # access mode of the IRACE detector

OCS.OS2.ENVNAME "wbos" # environment where proc. is running

OCS.OS2.PROCNAME "yyoControl" # name of the IRACE detector process

OCS.OS2.KEYWFILT "OCS2.*.*.*.*.*.*" # keywords to be forwarded to subsyst

OCS.OS2.TIMEOUT 6000 # timeout for the process

OCS.OS2.DBSTATE "<alias>yyo:status.state" # db address of 'state'

# Configure the Instrument modes

OCS.MODE1.NAME "SOS_TEST" # name of the instrmode

OCS.MODE1.SETUP "-function OCS1.INS.MODE IR_IMAGING" # setup the mode

OCS.MODE1.SUBSYST "XXXX" # subsystems involved in the given mode

OCS.MODE1.PATH "" # instrument path

OCS.MODE2.NAME "TWO_OS" # name of the instrmode

OCS.MODE2.SETUP "-function OCS1.INS.MODE IR_IMAGING OCS2.INS.MODE YY_TEST" # setup the mode

OCS.MODE2.SUBSYST "XXXX YYYY" # subsystems involved in the given mode

OCS.MODE2.PATH "" # instrument path

9.8.2 Hierarchical setup keywords

In the SETUP command (which are sent to the SOS) the keywords must be given hierarchically. All keywords that are intended to setup a parameter of a subsystem of a subsystem must have a prefix: OCSi[32].

The index of this prefix must correspond to the index of the category of the given OS as declared in the configuration file!

For example when the instrument XXXX is assigned by the OS1 category in the configfile, i.e.

OCS.OS1.NAME "XXXX" ,

then to set up the integration time of the DET1 subsystem of the XXXX instrument the keyword

OCS1.DET1.DIT

must be used in the setup command.

In principle to set up an SOS parallel exposure, one can send the following setup command to the SOS process (note that this is not yet supported):

SETUP -expoId 0 -function INS.MODE TWO_OS OCS1.OCS.DET.IMGNAME xxxx.fits OCS1.DET1.DIT 2 OCS2.OCS.DET.IMGNAME yyyy.fits OCS2.DET1.WIN1.UIT1 10.0

The SOS (or more precisely the interfaces of the XXXX and YYYY instruments) then will cut off the prefixes and send to XXXX:

SETUP –expoId <id> -function OCS.DET.IMGNAME xxxx.fits DET1.DIT 2 INS.MODE IR_IMAGING

and to YYYY:

SETUP –expoId <id> -function OCS.DET.IMGNAME yyyy.fits DET1.WIN1.UIT1 10.0 INS.MODE YY_TEST

9.8.3 Dictionary for SOS

As long as only the hierarchical keywords and the standard configuration keywords are used, there is no need to supply additional dictionary at SOS level.

9.8.4 SOS interaction

The exposure controlled by an SOS has the same main steps (9.7.4) as a normal OS, however because of the hierarchical structure the interactions are more complex.

Figure 8 shows the interaction diagram of command START, when SOS controls three OS-es, one ICS and the TCS and in the given mode all subsystems are on the subsystem list. Two of the OS subsystems (OS1 and OS2) have one detector and an ICS connected to them, while OS3 controls only an ICS. (Figure 7 shows the structure of the SOS.)

Figure 9 shows the image data ready event for the same instrument as shown in …., however in a different mode. In the mode depicted OS2 is not on the subsystem list, therefore it does not take role.

The image taking OS is OS2, and data is collected from OS3.