| |
|
|
|
11 REFERENCE
11.1 Scripts
11.1.1 icbConfigGet
icbConfigGet retrieves the value of an instrument
configuration parameter.
insid: Instrument identifier (INS.CON.ID).
parameter: Normally this is the name of a configuration
parameter. In this case, the corresponding
value is returned.
The special names listed below are recognized
to return the DBL_FLAGS needed during the
build of the OLDBs.
DBL_FLAGS_WS : returns the flags needed
to build the WS OLDB.
DBL_FLAGS_LCU1: flags for LCU1.
DBL_FLAGS_LCU2: flags for LCU2.
DBL_FLAGS_LCU3: flags for LCU3.
Retrieve the name of the WS environment (INS.CON.WSENV):
icbConfigGet XXXX INS.CON.WSENV
Define in the WS OLDB Makefile the variables needed by
icbEnv.db during the OLDB build:
DBL_FLAGS = -v0 `icbConfigGet XXXX DBL_FLAGS_WS`
11.1.2 icbConfigSet
icbConfigSet writes the LCU configuration file
according to the current instrument configuration.
<insid> - instrument identifier (INS.CON.ID).
<lcuenv> - LCU environment
$INS_ROOT/SYSTEM/COMMON/CONFIGFILES/<name>.dic
$INTROOT/config/<name>.dic
$VLTROOT/config/<name>.dic
File containing the list of config. dictionaries.
$INS_ROOT/SYSTEM/COMMON/CONFIGFILES/<name>.cfg
$INTROOT/config/<name>.cfg
$VLTROOT/config/<name>.cfg
Main configuration file.
$VLTDATA/config/<env>.dbcfg
Created LCU configuration file.
INS_ROOT resp. INTROOT must be defined to be able to read
a configuration stored in the corresponding location.
11.1.3 icbInstallHook
icbInstallHook is a script that has to be called by
pkginInstall during the installation of the instrument
software. This is accomplished by registering the
following hook in the pkgin configuration file:
INSTALL.HOOK1.NAME "AFTER_INS_INSTALL";
INSTALL.HOOK1.PLUGIN "icbInstallHook <insid>";
11.2 Programs
11.2.1 ic0Control
The ic0Control process is the frontend of ICS in the WS.
The process initialises itself directly from the
instrument configuration stored in the $INS_ROOT area.
$INS_ROOT/SYSTEM/COMMON/CONFIGFILES/INS.dic
File containing the list of INS config. dictionaries.
$INS_ROOT/SYSTEM/COMMON/CONFIGFILES/INS.cfg
Main instrument configuration file.
11.2.2 ic0SimControl
The ic0SimControl process is a generic ICS simulator process.
The process initialises itself directly from the instrument
configuration stored in the $INS_ROOT area.
$INS_ROOT/SYSTEM/COMMON/CONFIGFILES/INS.dic
File containing the list of INS config. dictionaries.
$INS_ROOT/SYSTEM/COMMON/CONFIGFILES/INS.cfg
Main instrument configuration file.
11.2.3 ic0devServer
ic0devServer() initializes the ic0devServer process by starting
the command interpreter.
Called by the boot script userScript.
The ic0devServer is a generic ICS device manager that
initialises itself from the OLDB. The OLDB must have
been made with file ic0insEnv.db.
The server reads the following two attributes:
:Appl_data:insId
:Appl_data:insLcuId
and then uses the following point to store its own data:
<alias>$insId:PROCESSES:LCU$insLcuId:icsDevServer
The devices to be managed are retrieved from the point:
<alias>$insId:DEVICES
The following attributes are retrieved during initialisation:
<alias>$insId:DEVICES:<deviceN>.lcuId
<alias>$insId:DEVICES:<deviceN>.devType
Only devices with their $lcuId equal to the $insLcuId and
device types beginning with the string "ic0" are managed
by ic0devServer.
11.2.4 ic0lcuServer
ic0lcuServer() initializes the ic0lcuServer process by starting
the command interpreter.
Called by the boot script userScript.
The ic0lcuServer is a generic ICS LCU frontend that
initialises itself from the OLDB. The OLDB must have
been made with file ic0insEnv.db.
The server reads the following two attributes:
:Appl_data:insId
:Appl_data:insLcuId
and then uses the following point to store its own data:
<alias>$insId:PROCESSES:LCU$insLcuId:icsServer
The devices to be managed are retrieved from the point:
<alias>$insId:DEVICES
The following attribute (a.o) is retrieved during initialisation:
<alias>$insId:DEVICES:<deviceN>.lcuId
Only devices with their $lcuId equal to the $insLcuId
are considered when the ic0lcuServer OLDB tables are
initialised.
11.2.5 ic0SelfTest
It performs a complete self-test of the <insid> instrument ICS based on ic0.
It particular:
1) It makes sure that the environment is running
2) It makes sure that ICS is online
3) It tests the state transitions:
ONLINE --> OFF --> STANDBY --> ONLINE
4) It repeats till all possible device positions have been tested:
SETUP + STATUS
5) It brings the system to STANDBY (for safety reasons)
<device list> is a string containing the alias name for the devices.
Examples:
"all" to test all devices
"TSH CALS" to test Tel. shutter and Calibration slide
Default: "all"
<nrep> specifies the number of times the test has to be repeated
Default: 1
ic0SelfTest XXXX
Test all ICS devices for instrument XXXX
ic0SelfTest XXXX "TSH CALS"
Devices TSH and CALS are tested once
ic0SelfTest XXXX "all" 20
All devices are tested 20 times
11.3 WS classes
11.3.1 ic0SERVER
#include "ic0SERVER.h"
ic0SERVER myServer("<alias>myPoint","myIcsSimServer",
1,&lcuServer,"myDictionary","myAliasFile");
The ic0SERVER is the basic application framework class which is used to
build an ICS command frontend server.
This class handles all incomming 'standard' commands which are passed to
the server process. Additional commands might be added from sub-classes.
Commands requiring parameter check i.e commands specifying ICS keywords
are check against the ICS dictionary. Keyword aliases are converted if
applicable.
In normal operation commands received by ic0SERVER class are forwarded to
the ICS LCU (or LCU's) specified (se constructor method below).
If the operation mode, indicated by opMode, is set to simulation then
the commands which normally are forwarde to the ICS LCU are sent to the
ICS simulation process instead, specified by simServerName.
All class functions are virtual so their behaviour can be modified by
overloading of the sub-classes in order for this class to adapt to
specific needs. This is especially usefull for functions called from
withing the command handling functions.
Callback functions called when a corresponding command is received.
All callback functions on command that need to bee forwarded to the
LCU subsystem are handled asynchroniously, i.e. "dynamic" callbacks
are installed to handle the receive of the reply, error reply or a
timeout. The asynchronious behaviour ensures that ic0SERVER class
is capable of handling multiple simulatious commands.
The state commands are synchronous commands i.e. while a state
transition commands is executed e.g. STANDBY no other commands can be
processed. The INIT command is also a synchronous command.
Commands requesting more detailed post processing install there
specific handling routine. Currently this is only the case for the
SETUP and STATUS command, e.g. SetupErrorCB().
ic0SERVER(const dbSYMADDRESS dbRef,
ccsPROCNAME chkServiceName,
ccsPROCNAME simServerName,
vltINT32 lcuNum,
ic0lcuSERVER *lcuServers,
char *dictionary,
char *alias,
ic0chkType chkInterfaceGhost = ic0chkINTERFACE_CLASS,
ic0simType simInterfaceGhost = ic0simINTERFACE_CLASS,
ic0lcuType lcuInterfaceGhost = ic0lcuINTERFACE_CLASS);
The ic0SERVER constructor establishes the contact to the dedicated
server processes and subsystems, which are: simulation
server and the ICS LCU.
Additionally the constructor registers the callbacks of the commands
defined in the command section.
The constructor allows the user to use other interface classes then
the default ic0xxxINTERFACE classes. This allows the user to
sub-class ic0xxxINTERFACE classes and still be able to call them
from within an unchanged ic0SERVER class.
~ic0SERVER();
Destructor.
virtual evhCB_COMPL_STAT InitServers(ccsPROCNAME simServerName,
vltINT32 lcuNum,
ic0lcuSERVER *lcuServers);
Initialize communication with the subsystem servers for:
lcu server(s) and simulation server.
virtual evhCB_COMPL_STAT OnlineCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT OffCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT StandByCB(msgMESSAGE &msg, void *udata);
State commands callbacks handling the state commands: STANDBY,
ONLINE, OFF. The command OPERATE is maped to ONLINE and
PDOWN mapped to OFF.
virtual ccsCOMPL_STAT Loaded2Standby(void *udata);
virtual ccsCOMPL_STAT Standby2Online(void *udata);
virtual ccsCOMPL_STAT Online2Standby(void *udata);
virtual ccsCOMPL_STAT Standby2Loaded(void *udata);
virtual ccsCOMPL_STAT Online2Loaded(void *udata);
State transition functions called Whenever a state transition is
performed - when the respective state commands is processed. All
state transition functions in ic0SERVER are only placeholders in
order to be overridden by sub-classes. Data udata passed to functions
are taken from the installation of the state command callback.
virtual ccsCOMPL_STAT CheckSubState(const char *command);
virtual ccsCOMPL_STAT ResetSubState(const char *command);
virtual char *SubStateName();
Handling of sub-states. The implementation of sub-state in these
methods are only limmited. The intention is to leave this up to the
sub-classes as the interpretation of sub-states might vary among
instruments. The sample implementation raises the busy sub-state
while a command is processed.
The sub-state is reset to idle by the ResetSubState() which is
called after a reply (or error reply) is received from the
sub-system.
virtual ccsCOMPL_STAT LcuState();
This methods sends a STATE command request to the LCU when the
operation is in NORMAL mode. The STATE command returns the global
state of the LCU and the WS process is aligned to this state.
virtual evhCB_COMPL_STAT SetupCB(msgMESSAGE &msg, void *udata);
Callback handling the SETUP command. If files are given as
arguments these are individually sent to the chkService for
loading and merging them into the setup buffer in the chkService.
If functions are specified these are equally loaded and merged
together with the others. The complete keyword list is retrieved
and placed into a keyword list. This list is passed to the keyword
handling functions described below.
If the keyword handling fails e.g. checking ranges the SETUP command
returns immidiately with an error reply. If it succeeds a new
parameter structure is set up in order to forward the command to the
sub-system. Un-supported parameter fields are removed from the
parameter structure.
virtual ccsCOMPL_STAT KeywordRangeCheck(msgCMD cmd,
ic0KEYWORD_LIST *keyword);
virtual ccsCOMPL_STAT KeywordPreProcessing(msgCMD cmd,
ic0KEYWORD_LIST *keyword);
virtual ccsCOMPL_STAT KeywordPostProcessing(msgCMD cmd,
ic0KEYWORD_LIST *keyword);
Keyword handling methods. The SETUP function is the most complex
function of ICS and does for some systems require special
preprocessing of the collected keywords, before sending the SETUP
request to the ICS LCU. For this purpose the above methods are
provided:
KeywordRangeCheck() is passed all merged setup keyword in an
ic0KEYWORD_LIST object and performs a range check on the keywords.
KeywordPreProcessing() is passed all merged and checked setup
keywords in an ic0KEYWORD_LIST object. In the pre-processing an
instrument model can be notified (see also ic0INS_MODEL(3)). In this
function the list of keywords might be extended or modified e.g.
when inserting keyword on a specific instrument 'mode' selection. For
this reason a pointer to the ic0KEYWORD_LIST is returned.
KeywordPostProcessing() is similar to pre-processing except that the
method is called with the keywords returned from the sub-systems.
Implementation of all methods are dummies to be overloaded by an
ic0SERVER subclass.
virtual evhCB_COMPL_STAT InitReplyCB(msgMESSAGE &msg, void *udata);
This method is called upon successfull reply of the subsystems.
The state of the system is set to LOADED after successfull
initialization.
virtual evhCB_COMPL_STAT SetupReplyCB(msgMESSAGE &msg, void *udata);
This method is called upon successfull reply of the subsystems.
The KeywordPostProcessing is called in order to notify the server
process of this event - this could be used to notify a instrument
model e.g. to clear setup flags.
virtual evhCB_COMPL_STAT SetupErrorCB(msgMESSAGE &msg, void *udata);
Error callback called when a SETUP error is returned from the sub-
systems.
virtual evhCB_COMPL_STAT StatusCB(msgMESSAGE &msg, void *udata);
Callback handling the STATUS command. If functions are passed as
arguments these are checked for validity.
virtual evhCB_COMPL_STAT StatusReplyCB(msgMESSAGE &msg, void *udata);
This method is called when the status reply is received from the
subsystems. If a "-dumpFITS" arguments is received then the key
words returned from the sub-system are passed into a FITS object
which actually writes the INS keywords into a FITS file.
virtual evhCB_COMPL_STAT CommentCB(msgMESSAGE &msg, void *udata);
Callback to handle the COMMENT command. Comment strings are placed
in the status buffer of the check server. In this way they are
inserted in the FITS header that can be produced by the STATUS
command. Command is _not_ forwarded to LCU.
virtual evhCB_COMPL_STAT DebugCB(msgMESSAGE &msg, void *udata);
Callback to handle the DEBUG command. The debug objects (see
ic0DEBUG(3)) used in the server are updated according the flags
specified as command parameters.
evhCB_COMPL_STAT GeneralCmdCB(msgMESSAGE &msg, void *udata);
Generic callback used to handle commands:
ENABLE/DISABLE/LOCK/UNLOCK
virtual evhCB_COMPL_STAT MaintenanceCB(msgMESSAGE &msg, void *udata);
Generic callback used to handle commands:
SETVAL/GETVAL/CFGELEM/MOVE/MOVEREL.
When the function is passed it is checked for validity.
Forwarded directly to sub-systems.
virtual evhCB_COMPL_STAT InitCB(msgMESSAGE &msg, void *udata);
Callback used to handle INIT command. If functions are
passed as arguments these are checked for validity.
Forwarded directly to sub-systems.
virtual evhCB_COMPL_STAT SetModeCB(msgMESSAGE &msg, void *udata);
Callback used to handle SETMODE command. The modes supported
are currently operational modes: NORMAL, LCU_SIMULATION and
maintenance mode: ON, OFF. If the operational mode is changed
then the forwarding sheme is changed. In normal operation the
ICS Lcu recieves the commands in LCU_SIMULATION mode. This command
is not forwarded to the sub-systems.
virtual evhCB_COMPL_STAT SimCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT SimulatCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT StopCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT StopSimCB(msgMESSAGE &msg, void *udata);
Callback used to handle SIM/SIMULAT/STOPSIM/SIMSTOP command.
The redundency is due to different specifications this system
applies to (see INS Common SW spec. 2.0 and Guidelines for VLT
applications). In case a SIM with all functions is specified this is
treated the same as setting the system in LCU_SIMULATION mode.
virtual evhCB_COMPL_STAT ReplyCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT ErrorCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT TimeoutCB(msgMESSAGE &msg, void *udata);
The following callbacks are used to deal with default replies and
error replies. If a more advance sheme is requested they can be
overloaded by subclasses.
ic0DEBUG *Debug();
Returns debug object.
virtual ccsCOMPL_STAT AttachDbEvents();
PROCTECTED DATA MEMBERS:
ic0chkINTERFACE *chkService; // Interface to parameter check server
ic0simINTERFACE *simServer; // Interface to command simulation server
ic0lcuINTERFACE *lcuServer; // Interface to ICS lcu server
ic0genINTERFACE *lcuCmd; // Virtual interface pointer
cmdPARAM_LIST paramList; // Command parameter list
ic0STATUS *status; // STATUS object
ic0DEBUG debug; // DEBUG object
// database values
eccsDB_INT32 substate; // substate (usage reserved for sub-classes)
eccsDB_INT32 opMode; // ics operational mode
eccsDB_INT32 error; // error indication (usage reserved for
// sub-classes)
eccsDB_INT32 timeout; // timeout for forwarding messages
eccsDB_LOGICAL simulation; // flag for simulation mode
eccsDB_LOGICAL maintMode; // flag for maintenance mode
PRIVATE DATA MEMBERS:
PRIVATE METHODS:
evhCB_COMPL_STAT ErrorReply(msgMESSAGE *msg);
evhCB_COMPL_STAT OkReply(msgMESSAGE *msg);
ErrorReply() send error message back to originator of a command
request.
OkReply() send OK reply to originator of a command request.
Following ICS standard commands are handled by this class:
CFGELEM, COMMENT, DISABLE, ENABLE, GETVAL, INIT, MOVE, MOVEREL, PDOWN,
SELFTST, SETMODE, SETVAL, SETUP, SIM, STATUS, STOP, STOPSIM.
11.4 Database
11.4.1 icb.class
This file contains all public Base ICS classes that can
be used from the instrument specific software modules.
The following classes are available:
Lamp and shutters:
icbLAMP calibration lamp
icbSHUTTER shutter
Motorized functions:
icbMOT_ADC ADC
icbMOT_DPOR depolarizer
icbMOT_DROT derotator
icbMOT_FILTER filter wheel
icbMOT_GRATING2 grating function (two gratings back to back).
icbMOT_MIRROR mirror wheel or linear function.
icbMOT_OPTI optical function
icbMOT_POS continuous position function
icbMOT_SLIT2_LEN length slit (two motors)
icbMOT_SLIT2_WID width slit (two motors)
icbMOT_SLITS slit wheel
icbMOT_TILT tilt
Sensors:
icbSEN_ADAM ADAM analog sensors.
icbSEN_BAROMETER Barometer sensor.
icbSEN_CN76000 OMEGA CN76000 temperature controller.
icbSEN_COOLING ESO cabinet cooling controller.
icbSEN_DIGITAL digital sensors.
icbSEN_HUMIDITY Humidity sensor.
icbSEN_QUAT10 HERAEUS QUAT10 temperature sensors.
Base for special devices:
icbDEVICE_BASE Base for special devices.
11.4.2 icbOLDB
The instrumentation OLDBs needed in the instrument workstation
and in the instrument LCUs are all built from a main instrument
specific branch file xxinsEnv.db. This file has to be included
by the dbl/DATABASE.db file located in each environment directory.
In addition, the corresponding dbl/Makefile files have to define
DBL_FLAGS as follows:
Workstation environment:
DBL_FLAGS = -v0 -I$(INTROOT)/vw/dbl -I$(INTROOT)/vw/include \
-I$(VLTROOT)/vw/dbl -I$(VLTROOT)/vw/include \
`icbConfigGet <XXXX> DBL_FLAGS_WS`
1. instrument LCU:
DBL_FLAGS = -v0 `icbConfigGet <XXXX> DBL_FLAGS_LCU1`
2. instrument LCU:
DBL_FLAGS = -v0 `icbConfigGet <XXXX> DBL_FLAGS_LCU2`
3. instrument LCU:
DBL_FLAGS = -v0 `icbConfigGet <XXXX> DBL_FLAGS_LCU3`
File xxinsEnv.db must include file icbEnv.db to create the
instrument OLDB structure. Then, it has to define all device
points needed by the instrument. The device points have to be
placed under the ICS DEVICE point:
:Appl_data:<XXXX>:ICS:DEVICE:<device_name>
where:
<XXXX> is the value of the config. parameter INS.CON.ID.
<device_name> is the device name of the device (e.g. config.
parameter INS.FILT1.DEVNAME).
The following classes are available:
Lamp and shutters:
icbLAMP calibration lamp
icbSHUTTER shutter
Motorized functions:
icbMOT_DPOR depolarizer
icbMOT_DROT derotator
icbMOT_FILTER filter wheel
icbMOT_GRATING2 grating function
(two gratings back to back).
icbMOT_MIRROR mirror wheel or linear function.
icbMOT_OPTI optical function
icbMOT_SLIT2_LEN length slit (two motors)
icbMOT_SLIT2_WID width slit (two motors)
icbMOT_SLITS slit wheel
icbMOT_TILT tilt
Sensors:
icbSEN_ADAM ADAM analog sensors.
icbSEN_CN76000 OMEGA CN76000 temperature controller.
icbSEN_COOLING ESO cabinet cooling controller.
icbSEN_DIGITAL digital sensors.
icbSEN_QUAT10 HERAEUS QUAT10 temperature sensors.
Motorized functions have to add a MOTOR point to the OLDB directly
under their device point. Functions with two motors have to add
one point for each motor: RIGHT and LEFT.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|