INT-IDS-2

Interfaces to the
IDS server

Daniel Matthews

1.1, 20 November 1996







Isaac Newton Group, RGO,
Aptdo 368,
Santa Cruz de La Palma, TF38780 Spain

Telephone (int+) 34 22 405500
Fax (int+) 34 33 405646
Internet drm@ing.iac.es

1 Introduction

1.1 Context

The IDS server is a program for the `Solaris' operating-environment that controls the intermediate dispersion spectrograph on the INT. The detailed design of the server is described in INT-IDS-3, reference [2]. This document defines the architecture of the server and the interfaces by which other systems and programs can use the server.

This is a specification of the server. It is valid for software writers to claim conformity with a specific issue of this document. If the implementation of the IDS server does not match this document, then the software is at fault.

1.2 Overview of interfaces

Much of the detailed behaviour is described in INT-IDS-3 but these details are liable to change. The aspects of the behaviour that can be relied upon are described in sections 5 and 6.

Communication with the IDS MMS controller is via an RS232 serial link, operating a protocol as described in [1]. The specific messages used when communicating with a controller are described in reference [2] .

The server runs under the supervision of the general observing system. The interfaces by which the server talks to its parent system are described in sections 5 and 6.

The server requires certain environment variables to find files, and homes for generated files. These are described in section 7.2.

1.3 References

[1] IDS local controller RGO document ER022, LP Technical Manual 24

[2] IDS server detailed design ING/RGO document INT-IDS-3 by Daniel Matthews

[3] Exchangeable optics Interface ING/RGO document *** by Guy Rixon

[4] Dialogues with the user: General Principles ING/RGO document OBS-TALK-1 by Guy Rixon

[5] Remote Procedure Calls for DRAMA clients ING/RGO document OBS-RPC-1, by Guy Rixon

[6] Server services ING/RGO document ?????, by Guy Rixon

[7] Interfaces to the DAS server

[8] Transfer Document ING/RGO document INS-TF-1, by Daniel Matthews

2 Architecture

2.1 System context

Figure 1. is the context diagram for the IDS server. The primary data and control source is the IDS MMS itself. It is this that controls the position of all the mechanisms (except the slit shutter), and reports the position and status of all mechanisms.



The system is responsive to all kinds of DRAMA transactions which come from the clients and the Mimic. The interface for incoming transactions are defined in section 5. The interface to the talker (Talker_transaction) is defined in reference [4].

The DRAMA parameter database (IDS_parameters) is described in section 6. The archive action causes a FITs packet file to be written to disk. This is described in section 3.3. The environment variables and command line arguments provided by the parent process are outlined in sections 3.1 and 7. The low level communications messages between the server and the IDS controller (MMS)are described in the Detailed Design, reference [2]. When the server starts up and when the IDS_INIT action is invoked, the contents of the IDS_Settings file are reloaded - the structure of this file is outlined in section 7.2.

2.2 Communications

The communication to and from the IDS MMS is via one entry point.



For each mechanism there is an update (Update-N) and Action (Action-N) task. When a low level message arrives from the MMS (as a result of the periodic full status request) the message is interpreted and the mechanism status and position is forwarded to the appropriate Update task. This updates the Parameter system and sends a DRAMA Signal (Signal-transaction) to the task. If the task is not active, this message will be ignored.

2.3 Actions

The IDS server has initialisation code, and 15 actions. The detail of the actions is described in section 5. Most of the actions correspond to the movement of one mechanism. The exceptions are the PING and EXIT actions, provided by the srv facility (reference [6]), the ARCHIVE action, described in section 3.3, and the IDS_INIT action. The IDS_INIT action causes the mountables database (reference [3]) to be reloaded.

Most of the initialisation code is provided by the INS facility, described in section 3.

Two actions are provided for moving the grating, IDS_GRATANG and IDS_CENWAVE. They both call the same function. The action IDS_CENWAVE is used if the central wavelength is provided, but IDS_GRATANG should be provided when the actual demand angle is provided. If IDS_CENWAVE is used, the grating lines per mm (GRATLINES) and the camera currently selected (CAMERAINUSE) must have been initialised.

2.4 Clients

Most clients are provided by the INS facility, described in section 3, with a table defining the implementation in the IDS. A series of soft links are used to provide the different commands for the user.

Only the change_ids client is not implemented as above. This command allows the user to modify the idsSettings persistence file, and then prompts the IDS server to reload it, by sending it an IDS_INIT action.

2.5 Mimic

The mimic can be treated as another client, but due to it's substantially different architecture, it will be described separately. When started the mimic attaches to the IDS and AGB servers with Drama Get and Monitor actions (Get_transaction and Monitor_transaction). This causes the parameters in both servers to become available to the mimic. When any of them change the mimic will be notified causing the appropriate change in the display.



3 INS facility

The suite of functions provided by the instrument (INS) facility is aimed at making it easier to implement the DRAMA tasks serving instruments, with a serial port interfaces. It provides a structure to hang the specifics of an instrument, and also series of tools commonly needed in creating a DRAMA based instrument server. This includes a way of creating simple clients using a table to define their function.

3.1 Command line interface

From the parent process the INS facility requires the following environment variables to be defined:

LOGS defines the destination directory required for the log generated by the server. The file produced will be NNN_yymmdd.log, where NNN is either the capitalised name of the executable used to start the server, or the name provided as the second command argument (see below). If this is not defined, the file will be deposited in the directory current when the server started.

LOGDATE defines the date used as the suffix for the log file name, ie the "yymmdd" in NNN_yymmdd.log (see above). If it is not defined, the word "NULL" will be used.

HDR_TEMPLATES defines the location of the header template, see section 3.3 below.

OBSSYS defines the root of the current observing system.

The command line arguments for a server using the INS facility should be:

arg(0) (required) is the name of the executable itself. If no arg(2) is provided, this name, capitalised, will be used when registering with DITs.

arg(1) (required) defines the serial port to use in the form "/dev/term/xxx" where xxx corresponds to the particular port the instrument under control is attached.

arg(2) (optional) defines the name to be used when registering with DITs.

For example:

ids /dev/term/a002 &
Will start the IDS server, communicating to the instrument down port /dev/term/a002, and use the name IDS when registering with DITs, and run in the background. However:

sccd /dev/term/a SCCDa &
Will start the SCCD server, on port /dev/term/a, but will register with DITs and SCCDa.

3.2 Function call interface

The INS facility requires the server to provide the following functions:

void portInit ( char *portName, FILE *portPtr, StatusType *status)

portName (read only) is that provided as arg(1) of the command line

portPtr (modified) returns the file pointer

status (modified) is the inherited status.

This is called by the INS facility during initialisation.

void portRead( int *portPtr, StatusType *status)

portPtr (read only) is that returned by portInit above

status (modified) is the inherited status

This is used as the call back function to DitsAltInAdd. This function will get called whenever a message arrives down the nominated serial port. The raw data will be available to the user at the first "read" in this function.

void startParamSys( StatusType *status)

status (modified) is the inherited status

This is called during initialisation. The server should ensure that the parameter system is started in this function. It is usually worth ensuring that the parameters created are also initialised.

void startActions( StatusType *status)

status (modified) is the inherited status

This is also called during initialisation. This is where the server should add the actions it requires. Note the PING, EXIT and ARCHIVE actions are provided by the INS facility and should not be added by the host server.

The INS facility provides the following functions for use by the host server:

void msgLog( const char *source, const char *str )

source (read only) is the name of the function requesting the log entry

str (read only) is the message to be added

This causes one line to be added to the log. The entry will consist of the time the entry is added, the source of the entry, and the message itself.

void insMatchCode(const char *wheel, long code,const char *sdpName, StatusType *status)

wheel (read only) is the name of the mechanism in use

code (read only) is the position of the mechanism

sdpName (read only) is the name of the parameter holding the description

status (modified) is the inherited status

This is used to look up the name of a particular filter, and update the corresponding parameter. The parameter must be a ARG_STRING type. The string added assembled by adding the following entries in the "mountables database" for that filter: uniqueId, waveband, photoSys. This can be used at the description that will end up in the FITs header.

3.3 Archive action

When the shutter first opens on an exposure, the DAS server initiates an ARCHIVE action on all servers it has been told about. When the shutter closes at the end of an exposure, the DAS server sends a kick to all the ARCHIVE actions it had initiated (see reference [7]). The srv facility provides the action to catch these requests, and forwards them to the function insArchive() provided by the INS facility.

The INS facility requires two template files to be available, in the directory pointed to by the HDR_TEMPLATES environment variable. The names of these files must be nnnHdr.BEGIN and nnnHdr.END, where nnn is the command name of the server. For example idsHdr.BEGIN and idsHdr.END for the IDS server. These template files should be world readable. The template file should have lines of the following format:

[FITSdescriptor](! ParamDataType ParamName([:PrintFormat]||[:{TranslationTable}]))

Where:

FITSdescriptor is exactly 80 characters consisting of:

8 uppercase characters including spaces, of FITs descriptor name

An `=' character

22 characters - spaces if to be filled in by a parameter value.

A `/' separator, to separate the value from the comment

48 characters of comment usefully describing the item

ParamDataType - defines the data type of the parameter, only the first character is used. Valid values are:

FLOAT (floating point type)

INTEGER (signed long integer)

UNSIGNED (unsigned long integer)

SHORT (unsigned short integer)

CHARACTER (character string)

BOOLEAN (unsigned short int, with !0 meaning TRUE)

TIME (unsigned long integer, of form hhmmss)

ParamName is the name as defined when created in the parameter system. This can be the element of a structure, using `.' to descend the structure definition. Elements of arrays can be accessed using the standard `[n]' notation. `n' corresponds to the C type index, so starts at zero. A combination of these can be used, for example:

FORMAT.WIN[2].WIN_SIZE.X

PrintFormat defines how the value should be inserted into the parameter field of the FITS descriptor. It is only used with FLOAT and INTEGER type, and is ignored with other data types. If this is left blank, the standard format for the data type will be used - that is "%20e" for FLOATs and "%20hi" for INTEGERS.

TranslationTable is an array of strings, that the parameter will index. It is the indexed string that is inserted into the FITS descriptor. This is only used if the data type is INTEGER, otherwise the table is ignored. The table is defined as follows:

{str1,str2,str3,..,strn}

Where the strings are not bounded by any quotes. For example:

{STANDARD,QUICK,TURBO,NONASTRO,SLOW,INVALID}

If the first character on any line in the template file is not an upper case, alphabetic character, the whole line will be ignored, and assumed to be a comment.

If there is no `!` character in the 81st character position, then it is assumed that the whole line is to be inserted verbatum into the header, without the insertion of a parameter value. This can be used to adding invarient descriptors such as INSTRUME (the instrument in use).

3.4 Compile time

At compile time the INS server facility requires the following header files to be available:

ciaBoolean.h

insErr.h

srv.h

mdb.h

It requires the following source files to be compiled and linked:

insMain.c

insArchive.c

srvPingExit.c

srvFindFile.c

mdbMount.c

mdbMatch.c

srvTalk.c

3.5 Client facility

The INS suite provides a simple was of creating simple clients for a server. A structure type, insClientDef_T, is defined in ins.h. An array of these should be provided with one entry for each required client. The entry for a client consists on the command name, the DRAMA action to be invoked by the client, the name of an interlock, and then a description of the parameters expected on the command line when the client is invoked, that is the number of arguments and their type. Finally a string describing the usage should be provided. This will be given to the user if the wrong number or type of arguments are provided. The final client description should have the action name as 'NULL' to indicate the end of the table.

The type of the command line arguments can be any of the following:

INS_INT implying an integer

INS_FLOAT implying a floating point number

INS_STRING implying a character string

INS_TABLE1 implying an element from cmdTable1

INS_TABLE2 implying an element from cmdTable2

The command line arguments are converted to the appropriate type, if possible, and inserted into a DRAMA SDS argument to the corresponding DRAMA obey action. The names of the arguments are `Argument1', `Argument2' etc.

The command tables cmdTable1 and cmdTable2 must be provided but may be empty if not used. An example of when you might use them is when moving a shutter. The DRAMA action may require one argument, type integer, that specifies whether to open or close the shutter, with 0 signifying close and 1, open. In such a case it is more convenient for a user to enter the string `open' or `close' when invoking the client. In such a case, cmdTable1 might be defined as:

char *cmdTable1[] = {
"CLOSE",
"OPEN",
"NULL" };

The argument the user enters will be converted to uppercase before comparison with the elements of the command table.

Finally the name of the server must be provided. This is defined as the character pointer serverName.

The individual client names, as defined in the table, should be created by linking to the umbrella client generated by the compilation of the specific client table with the INS client facility.

4 Behaviour of the IDS server

This section defines those aspects of the server's behaviour that affect the interfacing. It describes the more complex actions in more detail.

Some of the actions that can be started can take some time to complete - notably grating and collimator movements. If these actions are obviously going to fail and the user no longer wishes to wait for them to complete, they can be kicked (DRAMA Kick message sent to the action), with no arguments to cause them to terminate. This will not affect the IDS controller, which may continue to move focus, or change filter without any action from the server. Therefore it is recommended that this feature be used sparingly and with caution.

Although the IDS can be put into "monitor mode", this has been found to be unreliable. Therefore the full state of all mechanisms is requested every IDSTO_REQSTATUS microseconds (defined in idsInternal.h as 1000000, ie 1 second).

The IDS MMS is mounted on the cassegrain of the telescope. It communicated via an RS 232 port, using the protocol outlined in reference [1]. This serial port can either be plugged directly into the serial port of the System computer, or into a terminal server under control of the system computer. The latter is recommended to reduce the length of cable down which the RS232 protocol is expected to function.

Under the new Data Acquisition System, the slit shutter is no longer controlled by the IDS, but by the CCD controller. The IDS MMS is however still aware of the state of the shutter, so this is maintained as a parameter, even though there is no action in the server to move the shutter.

The exchangeable optics database protocol is used to maintain persistent information of the contents of the filter wheels and the type of grating and collimator sources. A file containing SDS structures defining the contents of each mechanism is maintained, but should only accessed through the interface described in reference [3]. When the server first starts up, the file is loaded. If any element of the file is changed, the command IDS_INIT should be issued to cause it to be re-loaded. The contents of the persistence file is outlined in section 7.2.

The server is required to provide a FITs packet describing the state of all the mechanisms. This is provided by the Archive Collection Facility, described in detail in section 3.3

The dekker has it's position encoded with a range upto approximately 1053. The 9 valid positions simply correspond to an encoder position, as each dekker slide has the 9 valid dekker positions in different places. The positioning of the dekker slide is however not acturate to one encoder unit, and even once in position the encoder reading shows some 'noise'. For this reason some tolerance of the dekker position is permitted in the interpretting of a valid position. If the encoder reading is 2 units either side of a valid position, it is counted as at the valid position.

5 Command interface

The IDS server is a DRAMA task and its commands are implemented as DRAMA actions, invoked through OBEY messages in the normal way. These actions can be used by DRAMA tasks running on the IDS, instrument control computer or on computers elsewhere on the Internet. Only one IDS server can run on the instrument control computer at any one time.

The IDS server registers with the DRAMA message-system as `IDS'. Note also that case is significant when invoking this program by name. If the host computers for the INT is, say, lpss12, then the IDS server can be addressed as IDS@lpss12.ing.iac.es: this is the fully-qualified task name that would be passed to functions of the DRAMA libraries when connecting to the servers.

The server's actions send one status message when they end and do not send `trigger' messages. Each completion message reports the final status of the action to which it applies but does not describe the state of the sub-system; e.g., a completion message might say that a filter move failed, but it would not say which filter was current at the end of the action. The sub-system state is reported by DRAMA parameters, as described in section 4. Action names are all in upper case: this make it possible to access the actions from an ADAM system. The argument names listed, including the mixed case, should be reproduced exactly in the argument structure passed with the action.

All of the actions that result in mechanisms moving can be kicked during execution. This will cause the action to terminate immediately with an error.

IDS_ACCESS is used to control the state of the following ports: grating port - for changing the grating; collimator port - for changing the collimator; observers port - for access to the slit area including below slit filters and dekker slide; and the grating shutter - for protecting the shutter during a change. The IDS controller will not unlatch any port unless the camera shutters are closed. It will not unlatch the grating port unless the grating shutter is closed. This action has two required parameters:

Argument1 (integer) specifies the port to be modified, using the IDS_Mech_t enumerated type, as defined in ids.h. The following values are valid:

IDS_GRATPORT 0

IDS_COLLPORT 1

IDS_OBSPORT 2

IDS_GRATSHUT 3

Argument2 (integer) specifies the position requested for the above port, with the values interpreted by the following definitions in ids.h (note: Close actually latches the port, and Open unlatches):.

IDS_CLOSE 0

IDS_OPEN 1

IDS_HART sets the position of the the two hartmann shutters. It has two required parameters:

Argument1 (integer) specifies the requested position of the hartmann A, using the values interpreted by the following definitions in ids.h:

IDS_CLOSE 0

IDS_OPEN 1

Argument2 (integer) specifies the requested position of the hartmann B, as above.

IDS_SHUTTER changes the state of the IDS shutter. The camera shutter moved depends on the value of the parameter CAMERAINUSE, which is set up by IDS_INIT, to be either IDS_235INUSE or IDS_500INUSE. This action requires one parameter to describe the position of the shutter requested:

Argument1 (integer) specifies the requested position of the shutter of the camera in use, using the values interpreted by the following definitions in ids.h:

IDS_CLOSE 0

IDS_OPEN 1

IDS_GRATSHUT changes the state of the grating shutter. If the shutter is to be closed the IDS MMS will first move the grating to the change position. This action requires one parameter to describe the position of the shutter requested:

Argument1 (integer) specifies the requested position of the shutter, using the values interpreted by the following definitions in ids.h:

IDS_CLOSE 0

IDS_OPEN 1

IDS_DEKKER sets the position of the dekker slide. Position zero is used to indicate "out of beam". There is one required parameter:

Argument1 (integer) specifies the filter number requested, it should be in the range, defined in ids.h:

IDS_DEKMIN 0

IDS_DEKMAX 8

IDS_BSCF changes the below slit colour filter. Position zero is out of the beam. This action has one required parameter:

Argument1 (integer) specifies the filter number requested, it should be in the range, defined in ids.h:

IDS_BSCFMIN 0

IDS_BSCFMAX 2

IDS_BSND changes the below slit neutral density filter. Position zero is out of the beam. This action has one required parameter:

Argument1 (integer) specifies the filter number requested, it should be in the range, defined in ids.h:

IDS_BSNDMIN 0

IDS_BSNDMAX 2

IDS_GRATANG changes the angle of the grating. This sets the absolute grating angle irrespective of the grating and camera in use. This action has one required parameter:

Argument1 (integer) specifies the required grating angle

IDS_CENWAVE changes the angle of the grating. The CAMERAINUSE and GRATLINES is used to calculate the grating angle required for the requested central wavelength, so these should have been defined before this action is executed. This action has one required parameter:

Argument1 (integer) specifies the required central wavelength.

IDS_COLLIMATOR sets the collimator position, and hence the spectrograph focus. This action has one required parameter:

Argument1 (integer) specifies the required position of the collimator.

IDS_SLITWIDTH sets the width of the slit. This action requires one parameter:

Argument1 (integer) specifies the slit width in microns.

IDS_INIT initialises the server. This causes all the files defining the contents of the filter trays, dekkers, collimator and grating type and camera in use to be re-loaded. This should be called after any of these have been changed. See section 2 for further details.

EXIT causes the server to exit cleanly. It is recommended that this be the only method of terminating the server. This is the standard action from the srv package

PING does nothing, simply terminates immediately. It can be used as a method of verifying the server is alive. This is the standard action from the srv package

ARCHIVE writes the FITs header packet relating to the IDS to the named fits file. This is the standard action from the srv package, with the INS archive facility.

6 Parameter interface

The position and state of all the mechanisms of the IDS are all reported through DRAMA parameters. These parameters are updated and accessed independently of actions on the IDS server. All mechanisms have one parameter to define it's position and one to define the status of the mechanism. Some other parameters are derived from the absolute position, such as central wavelength being derived from the grating angle, lines per mm, and the camera in use.

The parameters may be monitored or polled by any DRAMA task that wishes to watch events in the server; monitoring is preferred to polling as it involves fewer messages and gives a more timely notification of changes. A task that monitors a parameter will not be told the parameter's value at the time that monitoring begins: the task should do one explicit GET of the parameter when monitoring starts.

Normally parameters should not be modified by external tasks, as this could leave the server in an undefined state.

CAMERAINUSE (unsigned short integer) defines which of the two beams in the IDS spectrograph is currently in use. The value is set by IDS_INIT action. The value can be interpreted from the two definitions in ids.h:

IDS_235INUSE 1

IDS_500INUSE 0

GRATPORTPOS (unsigned short integer) defines the position of the IDS grating port. This value is set by the movement of the mechanism. The value can be interpreted using the the definitions in ids.h:

IDS_OPEN 1

IDS_CLOSE 0

GRATPORTSTATE (signed short integer) defines the state of the grating port access door. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

COLLPORTPOS (unsigned short integer) defines the position of the collimator access port. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ids.h:

IDS_OPEN 1

IDS_CLOSE 0

COLLPORTSTATE (signed short integer) defines the state of the collimator access port. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

OBSPORTPOS (unsigned short integer) defines the position of the observer access port. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ids.h:

IDS_OPEN 1

IDS_CLOSE 0

OBSPORTSTATE (signed short integer) defines the state of the observation access door. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

HARTAPOS (unsigned short integer) defines the position of hartmann shutter A. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ids.h:

IDS_OPEN 1

IDS_CLOSE 0

HARTBPOS (unsigned short integer) defines the position of hartmann shutter B. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ids.h:

IDS_OPEN 1

IDS_CLOSE 0

HARTSSTATE (signed short integer) defines the state of hartmann shutters. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

GRATSHUTPOS (unsigned short integer) defines the position of the grating shutter. This value is set by the movement of the mechanism. The value can be interpreted with the definitions in ids.h:

IDS_OPEN 1

IDS_CLOSE 0

GRATSHUTSTATE (signed short integer) defines the state of the grating shutter. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

SHUT235POS (unsigned short integer) defines the position of the 235mm camera shutter. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ids.h:

IDS_OPEN 1

IDS_CLOSE 0

SHUT500POS (unsigned short integer) defines the position of the 500mm camera shutter. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ids.h:

IDS_OPEN 1

IDS_CLOSE 0

IDSSHUTSSTATE (signed short integer) defines the state of the IDS camera shutters. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

DEKKERRAW (unsigned integer) defines the dekker position in encoder units. This value is set by the movement of the mechanism.

DEKKERPOS (unsigned short integer) defines the dekker number in the beam. This value is derived from the DEKKERRAW parameter. The position 0 (zero) indicates the dekker is out of the beam.

DEKKERSTATE (signed short integer) This value is set by the movement of the mechanism.

STABLE 0

MOVING 1

FAILURE -1

DEKKERNAME (character string) is a string that usefully describes the dekker mask currently in use. This might be "Single 2.0" indicating a single slit, 2.0 arcseconds wide.

DEKSLIDENAME (character string) is a string that usefully describes the dekker slide currently in use - note unlike other mechanisms this does not describe the particular dekker in the beam, but the name of the whole slide. For example it may be "FOS" but will not be "2arcec single slit".

BSCFPOS (unsigned short integer) defines the position of the below slit colour filter. This value is set by the movement of the mechanism.

BSCFSTATE (signed short integer) defines the state of the below slit colour filter slide. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

BSCFNAME (character string) is a string that usefully describes the below slit colour filter currently in the beam - that is not just the name of the complete slide, but the particular filter in the beam.

BSNDPOS (unsigned short integer) defines the position of the below slit neutral density filter. This value is set by the movement of the mechanism

BSNDSTATE (signed short integer) defines the state of the below slit neutral density filter slide. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

BSNDNAME (character string) is a string that usefully describes the below slit neutral density filter currently in the beam - that is not just the name of the complete slide, but the particular one in use.

GRATANGRAW (unsigned integer) defines the current position of the grating, in encoder units. This value is set by the movement of the mechanism.

GRATANGDEG (float) defines the current position of the grating, in degrees. This value is derived from the raw encoder reading by dividing it by 100.

GRATCENWAVE (float) is a value, in Angstroms, of the current central wavelength. This is derived from the grating encoder position and the lines per millimetre of the grating as follows:

GRATCENWAVE = cameraFactor *(sin(gZAngle) +sin(camAngle + gZAngle)) 			                linesPerMM
Where;

gZAngle is the zero corrected grating angle (GRATANGDEG - 89.75)

cameraFactor is -1E7 for the 235 camera and 1E7 for the 500 camera

camAngle as defined in idsInternal.h, is 35.56 for 235 and -25.36 for 500 camera

linesPerMM is dependent on the grating and taken from GRATLINES below

GRATANGSTATE (signed short integer) defines the state of the grating angle. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

GRATNAME (character string) is a string that usefully, and uniquely, describes which grating is in use. This is set when a change of grating has been carried out, and when the IDS server first starts.

GRATZERO (float) This is the zero position of the grating and is initialised to the value in idsInternal.h (89.75 degrees). If the encoder of the grating is changed, this parameter must be changed.

GRATLINES (unsigned integer) This is the number of lines per mm in the grating. It is modified when the grating is changed, and initialised when the server first starts.

GRATBLAZE (float) This is the blaze in angstroms of the grating in use. This is modified when the change command finishes, and in initialised to the last values used when the server starts up.

COLLPOS (unsigned integer) This value is the reading of the collimator encoder, and is set by the movement of the mechanism.

COLLSTATE (signed short integer) defines the state of the collimator. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

COLLNAME (character string) is a string which usefully, and uniquely, describes the collimator in use. This is set when a change of collimator has been carried out, and when the IDS server first starts.

SLITWRAW (unsigned integer) is the width of the slit in encoder units This value is set by the movement of the mechanism.

SLITWMM (float) is the width of the slit in millimetres. It is derived from the raw encoder reading, above as follows:

SLITWMM = (SLITWRAW - slitZeroPos) * 0.005
Where the slitZeroPos is the encoder reading when the slit is 0mm width, and is initialised to 137 units in ids.h, the value is stored in SLITZERO below

SLITWM (float) is the width of the slit in metres. It is derived from SLITWMM above.

SLITWPROJECT (float) is the projected slit width in millimetres. It is derived from the slit width, and the grating angle using the equation:

SLITWPROJECT = SLITWMM / reductionFactor 
Where

reductionFactor = cos(gZAngle + cameraAngle) * CollFLength     			     cos(gZAngle) * cameraFLength
Where

gZAngle is (GRATANGDEG - GRATZERO) above

cameraAngle is as defined in idsInternal.h: 35.56 deg for 235, and -25.36 for 500 camera

collFLength is the focal length of the collimator, as defined in ids.h (and is 1275 mm)

cameraFLength is the focal length of the camera in use (235mm or 500mm)

SLITWARCSEC (float) is the slitwidth projected onto the sky in arcseconds. This is derived from the slit width using the equation:

SLITWARCSEC = SLITWMM * IDS_SLITSCALE
Where

IDS_SLITSCALE is defined in idsInternal as 5.41 arcseconds per millimetre.

SLITWSTATE (signed short integer) defines the state of the slit width mechanism. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

SLITZERO (unsigned integer) defines the encoder reading for a slitwidth of zero. This is the encoder offset (in encoder units). It is initialised to IDS_SLITZERO as defined in ids.h (137). This should be changed when the system starts up if this default position is no longer correct.

SLITSHUTPOS (unsigned short integer) defines the position of the slit shutter The value can be interpreted using the definitions in ids.h:

IDS_OPEN 1

IDS_CLOSE 0

SLITSHUTSTATE (signed short integer) defines the status of the slit shutter. This value is set by the movement of the mechanism. The value can be interpreted using the definitions in ins.h:

STABLE 0

MOVING 1

FAILURE -1

IDSSTATUS (signed short integer) reports any other IDS faults. The value is a copy of the most recent value returned for the %K status message. This should be interpreted by referring to reference [1].

7 System Interface

7.1 Parent process

The IDS server requires the executable ids to be in the search path (environment variable PATH). It is started by executing the command ids with one argument defining the serial port to be used for this server. The name used to register with DRAMA can be given as a second parameter, but it is not thought this will be used. If executed on the command line or in a shell script, the server will probably want to run in the background. For example typing:

ids /dev/term/1 &

will start the server, using serial port /dev/term/1, and operate in the background. The server will register with DRAMA as "IDS".

The following environment variables are used by the IDS server:

LOGS defines the location for the log file produced by this server, IDS_log. If it is undefined, the files will be deposited in the current directory.

LOGDATE defines the date to be used for the log file suffix produced by this server, IDS_yymmdd.log. If it is undefined, the log file will be called IDS_NULL.log

HDR_TEMPLATES defined the location of the FITs header template files. These are named idsHdr.BEGIN and idsHdr.END

OBSSYS defines the root of the current observing system in use. This is used for storage of the archive packets and the location of the persistence files containing the exchangeable optics databases.

7.2 Data files

The following files are required by the IDS server:

idsHdr.BEGIN defines the header packets to be collected at the start of an observation. See section 3.3 for details of the format. This file should be stored in the location indicated by HDR_TEMPLATES above.

idsHdr.END defines the header packets to be collected at the end of an observation. See section 3.3 for details of the format. This file should be stored in the location indicated by HDR_TEMPLATES above.

idsSettings is used to provide persistent information above the exchangeable optics in use in the instrument. It is only read by the IDS server - it's contents being modified by the change_ids command. It should be available in the /ing/etc directory and be world read-writable. The format of the file is defined by reference [3] and should have the following elements:

DEKKER describes the currently loaded dekker

COLLNAME Textual name of the collimator

GRATNAME Textual name of the grating

GRATLINES Lines per mm on the grating

GRATBLAZE Blaze angle of the grating

CAMERAINUSE Which camera is in use - same form as the parameter of the same name in section 6.

I/IDS/BSCF describes the contents of the below slit colour filter wheel

I/IDS/BSND describes the contents of the below slit neutral density filter wheel

I/IDS/DEK describes the contents of the dekker slide.

The change command requires details of the contents of all the available slides, collimators and gratings. These are provided via the following files that should be available in /ing/etc. The ".dat" files are text, while the others are SDS files, the contents of which can be shown with sdslist. An example output from sdslist can be seen in reference [8]

collimator.dat List of available collimators

grating.dat List of available dekkers with details

D-CORO D-ENG Definition of each available dekker slide

D-FOS D-IPCS

D-MISC D-OUT

D-P22 D-P43 D-SING

BSND-n (n=0 to 3) Details of each available below slide ND slide

BSCF-n (n=0 to 3) Details of each available below slit colour slide

8 Compile-time interfaces

The IDS server sub-system provides some include files defining IDS-specific constants and data types for the use of other software.

ids.h defines data types used in the parameter and command interfaces.

insErr_msg.h Error messages corresponding to error numbers produced in the server

insErr.h Error numbers returned by actions in this server.

Appendix A. Document History

Issue 1.1 1996-11-16 Informally released as INS-IDS-1.

Issue 1.1 1997-02-05 Formally released as INT-IDS-2.