INT-IDS-3

IDS Server Detailed Design

Daniel Matthews

1.1, 28 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 coding and functions of the IDS server, as implemented in 1996 for the INT ICS, are described below for the benefit of engineers intending to test or modify the server. Information here refers entirely to internal details. Details of the external interfaces are contained in reference [1]. Reference [2] outines how to build install and configure the IDS server as part of the oberving system.

1.2 Scope and Overview

The IDS server is responsible for controlling the IDS, and maintaining status information for all the various mechanisms for displaying on the Mimic and sorting in the FITs header. The system is implemented as a set of Drama tasks.

Section 2 describes conventions and technologies used to build the system. Section 3 describes the INS facility, which acts as an umbrella under which the rest of the IDS server sits. The subtleties of the IDS server itself are outined in section 4. Section 5 described the operation of the clients and the mimic. Section 6 describes the source code components of the INS facility, section 7 those for the server itself, and section 8 those for the clients and mimic. A description of the serial port messages used to communicate with the IDS MMS are shown in Appendix A. An example of an SDS datafile used by the change command as part of the mountables database is given in appendix B.

1.3 References

[1] Interfaces to the IDS server ING/RGO document INT-IDS-2, by Daniel Matthews

[2] Transfer of DAS and ICS ING/RGO document

[3] DTCL Tcl interface to Drama AAO DRAMA software report 12

[4] srv Facility ING/RGO document , by Guy Rixon

2 Standards, Conventions and Procedures

2.1 Design standards

All C code is compileable by ANSI compilers. Where possible, library calls are limited to ANSI and POSIX functions. Any non-POSIX calls should be carefully documented.

The starlink coding standards were loosely followed. Modifcations should follow the ING C coding standard.

2.2 Documentation standards

Technical documentation is produced using the ESA standards as a guide. They are produced in Interleaf format, and are maintained in the general ING catalogue of documentation.

Manuals for use by the observer, should also be available, on-line, in HTML format.

2.3 Naming conventions

The following naming convention was used throughout:

Names of compiled servers are lower case

Variable and function names are mainly lowercase, with uppercase letters inserted where words are concatenated eg: idsUpdateSlitShut()

Names of data types have the suffixe "_t" unless they are structure type in which case they have the suffix "_T", eg insParameterType_t and insClientDef_T

Constants, notably those declared as macros, are named in uppercase.

Source file names are in mixed case with the subsystem name as a prefix, eg idsComm.c

Names of Drama actions and parameters are all in uppercase.

2.4 Developement tools

The compiler and debugger from SPARCworks Professional C was used for developement. The lint provided with this package was also used. Version control used sccs, part of the Solaris deistribution. The "bom" facility is used for maintaining releases. The tools provided with DRAMA were also used, particularly ditscmd, sdslist and cleanup.

2.5 Infrastructure requirements

These are outined in the reference [2].

3 INS Implementation

The INS facility provides a set of functions to host servers and clients. It does not in itself create an executable. The host server must provide the makefile.

3.1 Main

The INS facility provides a simple way of implementing a serial port base instrument control server. All that is required from the host application is an initialisation routine for the parameter system, DRAMA action table, and for the serial port, and a callback function that gets called whenever data arrives on the serial port. The main() function provides all the DRAMA initialisation as well as providing some of the library actions from the srv facility (see reference [4]). Finally main() enters the DitsAltInLoop which is the DRAMA alternative input (ie with input from a serial port as well as Drama messages) main loop.

Also provided is the logging facility which starts a log file. Interfaces to this are defined in reference [1]. The host application should call msgLog() with two arguments - the function name and the message string. These will be appended to the log.

It also provides a utility function call, insMatchCode, which can be used to fill in the filter name into the parameter system, when the position of a filter wheel changes. It looks up the given filter position, in the database for the given filter wheel. If the filter is found, the concatenation of the uniqueId, the waveband, and the photoSys elements is put into the named parameter. If the filter is not found, the word "NullName" is put into the parameter to indicate the filter wheel is in an undefined position.

3.2 Archive

This provides an easy way for a server to generate the FITs header packets required. It gets called when an ARCHIVE action is requested. The template file is read line at a time, and the FITs header packet generated accordingly. The details of the interface are described in reference [1].

3.3 Clients

The INS facility provides a way of implementing the simple clients, using a table and several static links. Each entry of the client table, provided by the host, consists of an entry containing the invocation name for the command and details of the parameters to be used, and the name of the action to be invoked in the target server. This table is defined in the interface specification reference [1].

4 IDS Implementation

4.1 Communications

The portInit function is called by the INS facility as part of the initialisation at the start of main(). This initialises the communications port to the IDS. It sets it to 9600 buad, 7 bit, parity enabled. More significantly it sets the port to canonical input, meaning, among other things, the server will only be notified of an arrived message when a line has arrived. That is line by line read, rather than character by character. This works because the IDS terminates it's lines with a carraige return line feed. The initialisation sets up a file pointer to the port which is then made available to the write function (idsMechInfo()) through the global portPtr.

The portInit function also starts the "requestStatus" cycle, which then becomes self maintaining. It does this by setting a Drama timeout, and arranging for itself to be called on the timeout. When the function is called, it sends a "global status request' to the IDS MMS, which replies with the status of every mechanism. These replies are handled by the portRead function.

The INS facility arranges to call the portRead function whenever an input line (since we are in canonical mode) arrives from the IDS MMS. These arrive as one line per mechanism, with a header indicating which mechanism. Appendix A. outines the messages. Each message is interpretted and the appropriate "update" function called to update the parameter database and notify any pending action.

4.2 Camera

The camera in use is defined by the Drama parameter CAMERAINUSE. This is set by the contents of the idsSettings file when the IDS_INIT action is invoked. It does not correspond to a physical mechanism. It meerly enables the interpretation of the grating angle as a central wavelength and the slit width as a slitwidth projected onto the detector. It is also used to decide which camera shutter to open or close with the IDS_SHUTTER action.

4.3 Dekker

The dekker has a movement of about 1053 encoder units, yet each slide only has 9 valid positions - 8 and the "clear" position. Each of the dekker slides available has the individual dekkers in different positions. This means for the slide currently in use there has to be a mechanism for linking the dekker number in the beam and the encoder position. This is done using the Mountables Database, outlined in reference [x].

The slide is considered a filter wheel, with 9 positions. The database contains a "filter" description for each of these positions. The description is actually just a brief description of the dekker - eg "Double 5.0, sep 42.0" implying that particular dekker is a double slit, each 5.0 arcseconds sparation, with 42 arcseconds between the centres of the two slits. The encoder position for any particular dekker is located in the "code" element of the filter description, while the dekker number is stored in the "invocation" part. Since the "invocation" element is actually character based, the required position has to printed to a string for testing against the invocation.

Definitions have been generated for each of the currently available dekkers. These files are stored in /ing/etc. The contents can be viewed using the "sdslist" function provided with Drama.

4.4 Access

The IDS server itself imposes no interlocks. The IDS MMS however does. When trying to unlatch the access ports, the IDS camera shutters must both be closed. This is a throw back from when IPCS was often used on the instrument. Unfortunately the controller does not complain when refusing to unlatch a port, it just returns with out error, but with the port still latched.

The other interlock is that the grating port cannot be opened if the grating shutter is not closed. Again, there is no status message returned to indicate this.

4.5 Grating and Slit

These two mechanisms have parameters derived from the raw encoder position. The slit width projected onto the detector is derived from both the slit width and the grating angle. This means that whenever the grating angle changes, both the derived grating parameters and the derived slit parameters are updated. When the slit width changes, there is only a need to update the derived slit parameters,

5 Clients and Mimic Implementation

5.1 INS clients

All except the change command and the mimic (described below) are implemented using the INS client facility, described in section 3.3. A table is used to define all the clients. When this is compiled with the INS facility, one executable is generated - IDS_CLIENT. When the install target of this is made ("make -f idsClients.mk install") this executable is moved to the observing system binary directory (pointed to by the environment variable OBSSYS /bin). The soft links to this executable are generated also with in the OBSSYS directory. These soft links are named "bscf", "hart" etc, and are what the user executes. When the IDS_CLIENT starts executing it extracts the command name used to invoke it - this will be the name of the link - eg "bscf". It then matches this name with one in the table to retrieve the appropriate information - how many arguments to expect and of which type and the action within the IDS server to initiate.

5.2 Change command

The change_ids command is implemented with the idsChange.tcl script. It is written using the Drama extention to Tcl. When it starts, it retrieves the current configuration from the idsSettings file, found in /ing/etc. This is used to set the values for the various internal parameters.

With the camera, the two options are 235 or 500. Selecting one of these will set the internal variable cameraInUse to the value 0 or 1 , using the encoding in ids.h.

With the two below slit filter slides, the user is offered the choice of 4 possible slides. This is because there are a selection of filled slides available to insert into the mechanism. Datafiles are stored on disk defining the contents of each of the slides. Once a slide has been selected, the corresponding data file is loaded, and the contents of the slide can be viewed by hitting the "View slide conents". This shows the contents of the data file read from disk. All the fields can be modified. When the "Change" button is clicked, the conents of the data file describing this particular slide is re-written with the modified contents. The FITs descriptor written into the header is the concatenation of Id, WaveBand and PhotSys - although this is handled from within the IDS server itself.

To generate a new slide description file, the "dtcl" command line interface could be used. This enables you to create and define the Sds structure and write it to a file, using SdsWrite. A small executable could also be made to create the file. If this file is to be available as an option to the change command, it will have to be added in the change script.

The dekker gives the user the option of selecting one of a number of dekker slide, much like with the below slit filters. The names of these are again hard coded into the script, and the selection of data files corresponding to each of the slides is stored in the /ing/etc directory. The user can also view the contents of the dekker slide by clicking on the "View slide conents" button, but it is recommended that the contents of the dekker definition files NOT be modified. The user should not change any individual dekker in a slide.

The collimator and grating selections are different. Each of these take the list of available choices from a data file - collimator.dat and grating.dat - in the /ing/etc directory. These files are simple plain ASCII text and are pretty self explainatory. Each option offered to the user corresponds to one line in these data files. Options can be added or removed by changing these data files.

When the user clicks on the "Save changes" button at the top of the window, the internal variables are converted to an SDS structure and written to the idsSettings file in the /ing/etc directory. The IDS server is then sent an IDS_INIT action which causes it to reload the idsSettings file. There is no other link between the change command and the server. This means that any changes become the default startup configuration.

5.3 Mimic

The mimic is implemented with the icsMimic.tcl script. It is written using the Drama extention to Tcl (DTCL). The mimic for the INT Cass instrumentation covers both the IDS and the A&G box. These two instruments are controlled by the IDS and AGB servers respectively. The mimic retains variables corresponding the the position and status of all mechanisms in both instruments. Monitor messages, with the appropriate call-back function, ensure that these variables represent the true positions of all the mechanisms at all times. If the position of any mechanism changes, the appropriate server will update it's drama parameter representing the mechanism position. Since there is a monitor active on taht variable, the DRAMA foxed part will notify the mimic of the change. This causes the call-back function to be called, which in turn updates the internal variable representing the position of the variable. It also causes the mimic for the appropriate instrument to be completely redrawn. This may seem excessive for just one mechanism moving, but it is simpler, and means the light path is upto date at all times. Indeed if any mechanism in the A&G moves, the IDS is completely re-drawn also again to ensure the light path is correct.

The colours of the mechanisms represent the status returned by the MMS for that mechanism. Some stati returned by the MMS correspond to more than one mechanism. For example, the all access ports are covered by just one status. this is also true for both hartmanns, both IDS shutters. In the A&G box MMS, the status of the X and Y slides in the Autoguider probe are the same, as with the TV probe.

The mimic has to be registered with DRAMA in order to initiate monitor and get transactions. the name is defined by the -n command like option - as specified in reference [3]. If the telescope operator wants to run another Mimic, a different name has to be chosen. The sizes of the buffers must also be set with a command line option. A recommended command to start up the mimic is:

icsMimic.tcl -b 100000 -n OBSMIMIC &

6 The INS Components

6.1 Component list

insArchive.c Generates FITS packets from lines in a template file

insMain.c Contains main() for host servers. Sets up parameter system and action map, starts logging and initialises serial port.

ins.h Provides access to the structures used in the INS facility for both the INS facility itself and users of the facility

insErr.msg Defines condition codes genereated by the INS facility. Compiles to insErr.h and insErr_msgt.h, both needed by external and host programs.

insClient.c Contains main() for clients. Requires the client table definition to customize to a set of clients.

6.2 Component relationships

The insMain.c requires a function insArchive defined, which is passed to the srv Archive function (see reference [4] for details of the srv facilities). This can be provided by a host server, but the insArchive.c module contains an insArchive that implements the INS archive facility. So if this facility is required, the insArchive.c module should be compiled and linked with the host server.

The INS facility must be compiled with a host server, which will provide the missing functions. See section 7.

Similarly the insClient.c module must be compiled with the host servers client table in order to create an executable. See section 8.

6.3 insArchive.c

TYPE:
C source-code file - 1 public function, 2 private.

PURPOSE:
To generate a FITS header file, given a template, by getting the
appropriate parameters from the current DRAMA task.

FUNCTION:
The insArchive function should be provided to the srvArchive as the call-back
function. This opens the template file defined as the server command name
appended by either Hdr.BEGIN or Hdr.END, and calls archive collect to actually
collect the header.

The function archiveCollect_ is called with the template file and output file
descirptors passed as arguments, this allows the output file to be appended
for example.

Each line of the template file is read, and passed to hdrPrintValue_
along with another string buffer to insert the result in. archiveCollect
copies the output line from the hdrPrintValue_ to the output file.

hdrPrintValue_ copies the FITSdesciptor part of the input line to the
output, this will remain unchanged if there is an error in collecting
the data item. It then reads the type and parameter name. If the
parameter is 'simple' - ie not a structure nor an array element, the
parameter is extracted, and the value passed on to the print format section.
If the parameter is not simple, a loop is entered and the parameter
tree is descended until the final part is found and extracted. This
is then passed on to the format section.

The format section of hdrPrintValue_ extracts any print format info or
translation table info - see below, and then prints the parameter value
to the output string.


SUBORDINATES:
Called:
msgLog

INTERFACES:

Called from C:
void archiveCollect
( FILE *hdrTemplate, FILE *hdrOutput, StatusType *status )

Where the two file descriptors hdrTemplate and hdrOutput point to the files
implied by their names.

The format of the template file is a file containing '\n' terminated lines,
with each line like this:

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

Where FITSdescriptor is exactly 80 characters long and is what is required
in the final fits file, with the parameter field blank.

ParamDataType is the type of the parameter described in ParamName and must
be one of the following - with the default format shown in brackets:

FLOAT - floating point %20e starting at 11th column
SHORT - unsigned short integer %20hu starting at 11th column
INTEGER - signed long integer %20li starting at 11th column
UNSIGNED - unsigned long integer %20lu starting at 11th column
CHARACTER - character array, ie string %-18.18 enclosed in single '
BOOLEAN - unsigned short integer F for 0, T for 1 in column 30
TIME - unsigned long integer, decimal form hhmmss

Although only the first character is used to confirm which type is used.

ParamName is the name used by the parameter system on the current task. If
the parameter corresponds to a structure element, use '.' to descend the
structure definition to the element required. If an array must be indexed,
use the standard "[n]" notation, remembering that "n", the index, 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

Means get he FORMAT structre, select cell 3 of the WIN structure, and so on.

PrintFormat defines how the value should be inserted into the parameter
field of the FITS desciptor. 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
will be the index string that is inserted into the FITS descriptor. This is
only used ifthe 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}

Only one of PrintFormat or TranslationTable can be used at a time. If no
DataType or ParameterName are given, the descriptor will be written to the
FITS file exactly how it appears in the FITSdescriptor.

Any lines that do not start with a capital letter will be ignored and not
passed no to the output file. These could be used for comments.

REFERENCES:
"Fits Headers for INT observations"
RGO/ING Doc number INT-DAS-2

"Archive Collection Facility"
RGO/ING Doc INS-ARC-1

6.4 insMain.c

TYPE:
C source-code file: two public functions, one private.

PURPOSE:
To provide facilities for starting up a task server, initiating the DRAMA
interface and starting the parameter system, and providing a message
logging facility. It also provides the archive facility and an interface to
the mountables database.

FUNCTION:
This component provides a shell for the definition of a DRAMA task.
It provides the entry point (main()) for the server, DITS is started up,
the application specific functions to set up the parameters systems (startParamSys)
and drama action tables (startActions) are called, the serial port is set up
(posrtInit) and finally the drama alternative
input main loop is called, so that while normal drama actions are handled
OK, any input for the serial port is sent to the application specific
serial port routine (portRead).

The archive action is implemented using the srvArchive function. The
packet name used in the command name, arg[0]. So for example if the
command name is "sccd", the archive packet for a run using DAS channel
0 will be sccd.0 in the $OBSSYS/etc directory

These 4 functions allow the task to be configured for a particular server.

logInit_ starts up the message logging file - which is stored in the directory
indicated by the LOGS environment name - or the current directory if this isn't
defined, and will be called SSSS_dddd.log where
SSSS is the server name, either as supplied as command line argument 2 or the
capitalised executable name (arg0), and dddd is the date as retrieved from the
environment variable LOGDATE - or "NULL" if this isn't defined. If the file
already exists, the new log will merely append - the header written can be used
to indicate a restarting of the server.

msgLog appends a message to the message log file setup with logInit_

The function insMatchCode can be used to create the FITs descriptor for a
particular filter in the mountables database. This is then poked into
a parameter to be retrieved when the next exposure is taken. It is a utility
function to make it easier for servers to use the mountables database. If the
filter cannot be found, the word NullName is inserted into the parameter given.

main is the 'c' entry point


SUBORDINATES:
included: insErr.h

Library functions called: talkParamsInit srvPingExitInit insArchive
Application functions called: startParaSys startActions portInit portRead


DEPENDANCIES:
Only one server can be run with any name

INTERFACES:
Call from C (internal to module):
void initLog_( char* serverName, StatusType *status )
initialise the message log file

Call from C:
void msgLog( const char *source, const char *str )
append a message to the log file, with suffix "source"
void main(int argc, char *argv[])
'C' entry point, with the serial port name as a character
string argument, and an optional second argument specifying the
name to be used to register with DITs.
void insMatchCode
(const char *wheel, long code,const char *sdpName, StatusType *status)
Creates the string that is to be used as the FITs descriptor of the filter
in a particular location in the filter wheel, presumable the one in the beam.

DITS actions:
EXIT and PING as defined by INS-RPC-1
ARCHIVE as defined in the srvArchive.c manual.
The name used when registering with DITs with be that provided by the
second command line argument, if provided, or the capitalised command
name if not.

Environment variables:
LOGS is used to define the directory to put the log file
LOGDATE is used to define the suffix for the log name (use 0822)

6.5 ins.h

TYPE:
C source-code: include-file.

PURPOSE:
Defines values and structures that are used in the "ins" system. These
are used across different server applications, and are not specific to any
in particular.

FUNCTION:
Defines the following structure type:
insClientDef_T - Element in a client definition table

Defines the following enumerated type:
insParameterType_t - Permitted parameter types for client table

Defines the following macros and definitions:
STABLE MOVING FAILURE - Mechanism status

SUBORDINATES:
None.

DEPENDENCIES:
None.

6.6 insErr.msg

TYPE:
This is a message source file, as required for the Drama messaging
system.

PURPOSE:
This provided status messages and values that can be returned to signify
errors or warnings to the invoking task.

INTERFACES:
This must be compiled to produce insErr.h, giving access to the
constant values. the routine 'messgen' should be used for compilation.

RESOURCES:

REFERENCES:
A portable message code system
AAO DRAMA software report 4

6.7 insClient.c

TYPE:
C source-code file: producing executable task

PURPOSE:
Provides the generic structure for generating simple clients. A
table must be provided by the host to specify the various commands
and their format, as well as the name of the target server. This
then in linked to produce one executable that is soft linked
to the command names listed in the table to produce all the
user commands.

FUNCTION:
This provides the main() for the client. The executable name is
defined by the makefile, different for each target server. The
individual commands are soft linked to this one executable to produce
the user commands. The softlinks mean that the actual command name
used is available as argv[0]. This is appended with the process
ID and used as the name to register with DITs.

The INS and CIA message facilities are loaded.

The command table provided externally to this file is searched for
the command name used to invoke this executable (argv[0]). If it
is not found then the command dies with an invalidArg error - implying
an invalid command has been entered.

The command table has entries of the form (as defined in ins.h):

typedef struct {
char *cmdName;
char *actionName;
char *interlockName;
int parameterCount;
insParameterType_t parameterType;
char *usage;
} insClientDef_T ;

Where the valid parameter types are defined as (as defined in ins.h):

typedef enum {
INS_INT,
INS_STRING,
INS_FLOAT,
INS_TABLE1,
INS_TABLE2
} insParameterType_t;

Once the command has been found in the command table, the required
lock is requested. If this request fails the command will fail
indicating why.

The parameters are then verified. If the number of arguments is
incorrect or they cannot be interpreted in the type specified in
the command table - the command will terminate with the invalidArg
error. These parameters are added to the argument list for the
Drama action, with argument names Argument1, Argument2 etc.

If the parameter type is defined as TABLE1 or TABLE2, the appropriate
string table is searched. If the string provided is found, the index
number of that string in the table is passed to the DRAMA action as
an integer, not the string itself.

Any error messages from the invoked action are reported to the
user when the invoked action terminates.

If the INVALIDARG error is present, either returned from the invoked
action or from one of the checks earlier in this function - the
usage string is given to the user to help explain correct usage of
the command.

SUBORDINATES:
called:
ciaPingInit ciaExitInit ciaRpcInit ciaTalkInit
ciaLockInit ciaLockReq ciaObeyRpc ciaExecuteRpc

included:
ciaRpc.h ciaTalk.h ciaErr_msgt.h insErr_msgt.h
insErr.h ins.h

External variables - read - provided by host application:
extern char serverName[];
extern insClientDef_T insCommand[];
extern char *cmdTable1[];
extern char *cmdTable2[];

DEPENDENCIES:
The talker program should be running.

INTERFACES:
Call from command line:
Executable name and argument number depend on host application
and command table.

REFERENCES:

"Remote Procedure Calls for Drama clients"
RGO/ING document OBS-RPC-1

7 The Server Components

7.1 Component list

As well as those components listed in section 6. the IDS server has the following components

idsServerMain.c Provides the action map and parameter databes

ids.h Provides interfaces to the IDS that might be required by external clients.

idsInternal.h Provides definitions and macros required in the AGB server

idsComm.c Provides the prtRead function to receive characters from the serial port, and the idsMechInfo function for moving mechanisms. Also starts self maintaining periodic request for status.

idsAccess.c Implements the IDS_ACCESS action to open the access ports and the update function for maintaining the related parameters

idsCollimator.c Implements the IDS_COLLIMATOR action for moving the collimator, and the update function for maintaining the related parameters

idsDekker.c Implements the IDS_DEKKER action for moving the dekker slide, and the update function for maintaining the related parameters

idsFilters.c Implements the IDS_BSCF and IDS_BSND actions for moving the filter slides, and the update functions for maintaining the related parameters

idsGrating.c Implements the IDS_GRATANG and IDS_CENWAVE action for moving the grating, and the update function for maintaining the related parameters

idsHart.c Implements the IDS_HART action for moving the hartmann shutters, and the update function for maintaining the related parameters

idsInit.c Implements the IDS_INIT action for moving the initialising the mountables database - loads the idsSettings file

idsShutters.c Implements the IDS_GRATSHUT and IDS_SHUTTER action for moving the grating and IDS camera shutters, and the update function for maintaining the related parameters - inccluding the slit shutter state.

idsSlit.c Implements the IDS_SLITWIDTH action for moving the slit width, and the update function for maintaining the related parameters

ids.mk Makefile for the IDS server, produces the executable `ids'

ids.bom Bill of Materials for a release of the ids server. Used by the bom utility to make a release.

7.2 Component relationships

The makefile ids.mk makes the IDS server by compiling all the above C files, as well as those in the INS facility and the srv facility, and linking into the "ids" executable.

A release is defined by the version numbers of all the components listed in ids.bom. A release can be made by giving this list to the "bom" utility, as described in reference [2].

7.3 idsServerMain.c

TYPE:
C source-code file: two public functions.

PURPOSE:
To provide facilities for the server controlling the INT IDS spectrograph:
starting the parameter system.
defining the action handlers


FUNCTION:
This component defines the IDS server parameter system and action table.

startParamSys starts the parameter system, adds all the parameters required
for the IDS server, and initialises them, with either NULL values for mechanism
positions, or default values for more invariant parameters, like SLITZERO. Finally
the settings are read off disk and loaded using idsLoadSetup

startActions defines the action handlers corresponding to the DITS
actions

SUBORDINATES:
Included:

Called:

DEPENDENCIES:
DitsInit should have been called before the startActions function
is called.

INTERFACES:
Call from C:

void startParamSys( StatusType *status)
void startActions( StatusType *status)

REFERENCES:
"Interfacing with the IDS server"
RGO/ING document INS-IDS-1

7.4 ids.h

TYPE:
C source-code: include-file.

PURPOSE:
Defines values used to send commands to and interpret return values from
the ids server.

FUNCTION:
Enumerated type defined:
IDS_Mech_t - list of mechanisms available in the IDS

Definitions and macros:
IDS_500INUSE IDS_235INUSE - For interpretting CAMERAINUSE
IDS_CLOSE IDS_CLOSED - For shutter position and movement
IDS_IN IDS_OPEN
IDS_OUT IDS_BETWEEN

IDS_DEKMIN IDS_DEKMAX - Range of permitted DEKKER positions
IDS_BSCFMIN IDS_BSCFMAX - Range of permitted BSCF positions
IDS_BSNDMIN IDS_BSNDMAX - Range of permitted BSND positions
IDS_SLITMIN IDS_SLITMAX - Range of permitted SLIT widths in microns
IDS_COLLMIN IDS_COLLMAX - Range of permitted collimator positions
IDS_GRATMIN IDS_GRATMAX - Range of permitted grating angles (100th degree)

SUBORDINATES:
None.

DEPENDENCIES:
None.

7.5 idsInternal.h

TYPE:
C source-code: include-file.

PURPOSE:
Defines constants used internal to the IDS server.

FUNCTION:
Enumerated type defined:
IDS_harts_t - position of both hartmanns

Constants, definitions and macros:
IDSTO_SHUTTER IDSTO_HART IDSTO_DEKKER - Mechanism timeouts
IDSTO_BSND IDSTO_BSCF IDSTO_GRATANG
IDSTO_COLLIMATOR IDSTO_SLITWIDTH
IDSTO_GRATSHUT IDSTO_ACCESS

IDSTO_REQSTATUS - Poll time for status requests

IDS_235CAMANGLE - Camera angle for 235 Camera
IDS_500CAMANGLE - Camera angle for 500 Camera
IDS_235CAMFACT - Camera Factor for 235 camera
IDS_500CAMFACT - Camera Factor for 500 camera
IDS_GRATZERO - Zero offset for grating angle
IDS_SLITZERO - Zero offset for slit width
IDS_SLITSCALE - Scale of slit in arcsecs per mm
IDS_COLLFLEN - Focal length of collimator
IDS_COLLRANGE - Tolerance permitted on collimator position
IDS_SLITRANGE - Tolerance permitted of slit width
IDS_DEKRANGE - Tolerance permitted in encoder units of dekker pos
IDS_GRATRANGE - Tolerance permitted in encoder units on grating angle

SUBORDINATES:
None.

DEPENDENCIES:
None.

7.6 idsComm.c

TYPE:
C source-code file: three public functions, one private

PURPOSE:
Interprets messages arriving from the IDS MMS, and compiles
messages to send to the server.

NOTE: SCCS expands some of the search strings - the option
-k should be used when getting this source file.

FUNCTION:
The portInit function initialises the named serial port device
for communication with the IDS MMS. It also triggers the requestStatus_
function which reschedules itself every IDSTO_REQSTATUS milliseconds, and
sends a full status request message. This ensures that he server
has up-to-date status information regarding the mechanisms. Polling
may be slightly more time consuming, but relying on "monitor-mode"
messages has apparently been found to be unreliable.

When a message arrives - presumably as a result of the requestStatus_
it's mechanism is interpretted, by looking at the first two characters.
The interpretation of the rest of the message string is dependent
on the mechanism. The appropriate update function is then notified
of the new position and status of the mechanism. It is worth noting
that after a request status, the mechanism messages come in one by one.

When the server requests a mechanism move, the idsMechInfo function
is called with the mechanism name and the required position. The
format of the message sent to the controller (MMS) is dependent on
the mechanism.

SUBORDINATES:
Included:
ciaBoolean.h ins.h idsInternal.h ids.h insErr.h

Called:
idsUpdateSlitWidth idsUpdateShutter idsUpdateSlitShut
idsUpdateGratShut idsUpdateHart idsUpdateGratAng
idsUpdateBSND idsUpdateBSCF idsUpdateDekPos
idsUpdateCollPos idsUpdateCollPort
idsUpdateObsPort idsUpdateGratPort
msgLog

Global data accessed:
extern int portPtr - File descriptor of the serial port

DEPENDENCIES:
portInit should have been called, and the global portPtr should have
been initialised before idsMechInfo is called.

INTERFACES:
Call from C:
void portRead( int *portFD , StatusType *status)
Where portFD is the file descriptor for the serial port stream
status is the inherited status

void portInit(char *port_, int *portFD, StatusType *status)
Where port_ is the name of the port, eg "/dev/term/a"
portFD is the return file descriptor
status is the inherited status

void idsMechInfo(IDS_Mech_t Mechs, ulong Pos, StatusType* status)
Where Mechs is the mechanism the move is requested for
Pos is the position requested
status is the inherited status

INS facility:
portRead should be the call back function when data arrives down the
serial port.

REFERENCES:
"Interfacing with the IDS server"
RGO/ING document INS-IDS-1

7.7 idsAccess.c

TYPE:
C source-code file: four public functions, none private.

PURPOSE:
To provide facilities for the control and monitoring of the
state (open/closed) and the status (stable, moving,failed) of the three
access ports.


FUNCTION:
This component of the IDS server implements the IDS_ACCESS DRAMA action
and provides the facility for the position/state feedback to the
parameter system.

idsAccess is the DRAMA task. The port lock to be moved, and the state
(locked or unlocked) to move it to, are passed to the action as arguments.
A requested to move this shutter/port mechanism is sent to the MMS, and
the action reschedules awaiting the position update. If this occurs
within the alotted time, the action will timeout with an error,
otherwise it will terminate quietly.

There is an interlock for all access prots with the IDS shutters - which
must be closed - the grating shutter must be closed to open the
grating port.

idsUpdateCollPort idsUpdateObsPort idsUpdateGratPort
will be called whenever the state of one of the access
ports arrives from the IDS MMS. The position and state parameters in the
DRAMA parameter system are updated, and the IDS_ACCESS action (above) is
notified, if it was running.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h ids.h
Called:
msgLog idsMechInfo

DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.

INTERFACES:
Call from C:
void idsUpdateCollPort( long portPos, long portState, StatusType *status)
void idsUpdateObsPort( long portPos, long portState, StatusType *status)
void idsUpdateGratPort( long portPos, long portState, StatusType *status)


DITS action:

Invoke the IDS_ACCESS action, with the following parameters:
Name: "Argument1" Type: Integer
Contents: IDS_GRATPORT (0), IDS_COLLPORT (1), IDS_OBSPORT (2)

Name: "Argument2" Type: Integer
Contents: IDS_OPEN (1) - unlatch, IDS_CLOSE (0) - latch.

7.8 idsCollimator.c

TYPE:
C source-code file: two public functions

PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the
collimator position in the IDS.

FUNCTION:
This component of the IDS server implements the IDS_COLLIMATOR DRAMA action
and provides the facility for the position/state feedback to the
parameter system.

idsCollimator implements the DRAMA task, which sends off a request to move the
collimator position, and reschedules awaiting the position update.
If this occurs within the alotted time, the action will timeout with an
error, otherwise it will terminate quietly.

idsUpdateCollPos will be called whenever the position/status of the
collimator arrives from the IDS MMS. The position and state parameters
in the DRAMA parameter system are updated, and the IDS_COLLIMATOR
action (above) is notified, if it was running.

The parameter COLLNAME is set in IDS_INIT and read with the ARCHIVE
action only - it is neither used nor set in this module.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h ids.h
Called:
msgLog portWrite


DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.

INTERFACES:
Call from C:
void idsUpdateCollPos(long collPos,long collState,StatusType *status)

DITS action:
Invoke the IDS_COLLIMATOR action, with the following parameters:
Name: "Argument1" Type: Integer, Contents: Required position

7.9 idsDekker.c

TYPE:
C source-code file: two public functions

PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the
dekker slide in the IDS.

FUNCTION:
This component of the IDS server implements the IDS_DEKKER DRAMA action
and provides the facility for the position/state feedback to the
parameter system.

idsDekker is the DRAMA task, which sends off a request to move the
dekker mechanism, and reschedules awaiting the position update.
If this occurs within the alotted time, the action will timeout with an
error, otherwise it will terminate quietly.

idsUpdateDekker will be called whenever the state of the dekker slide
arrives from the IDS MMS. The position and state parameters in the DRAMA
parameter system are updated, and the IDS_DEKKER action (above) is
notified, if it was running.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h
Called:
msgLog portWrite

DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.

INTERFACES:
Call from C:
void idsUpdateDekPos( ushort dekState, ushort dekPos, StatusType *status)

DITS action:

Invoke the IDS_DEKKER action, with the following parameters:
Name: "Argument1" Type: Integer 0-8, Contents: Required position

7.10 idsFilters.c

TYPE:
C source-code file: 4 public functions

PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the two
below slit filters (colour and ND) in the IDS.

FUNCTION:
This component of the IDS server implements the IDS_BSFC and
IDS_BSND DRAMA actions and provides the facilities for the
position/state feedback to the parameter system.

idsBSCF implements the IDS_BSCF DRAMA task, which sends off a request
to move the below slit colour filter, and reschedules awaiting the
position update. If this occurs within the alotted time, the action
will timeout with an error, otherwise it will terminate quietly.

idsUpdateBSCF will be called whenever the state (position or status) of
the below slit colour filter arrives from the IDS MMS. The position
and state parameters in the DRAMA parameter system are updated, and
the IDS_BSCF action (above) is notified, if it was running.
The textual name of the filter
in the beam is extracted from the mountables database using
the insMatchCode utility. The FITS descriptor is put into
the appropriate NAME parameter for extraction with the
ARCHIVE drama action.

idsBSND implements the IDS_BSND DRAMA task, which sends off a request
to move the below slit ND filter, and reschedules awaiting the
position update. If this occurs within the alotted time, the action
will timeout with an error, otherwise it will terminate quietly.

idsUpdateBSND will be called whenever the state (position or status) of
the below slit ND filter arrives from the IDS MMS. The position
and state parameters in the DRAMA parameter system are updated, and
the IDS_BSND action (above) is notified, if it was running.
The textual name of the filter
in the beam is extracted from the mountables database using
the insMatchCode utility. The FITS descriptor is put into
the appropriate NAME parameter for extraction with the
ARCHIVE drama action.


SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h ids.h
Called:
msgLog portWrite insMatchCode idsMechInfo

DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.

INTERFACES:
Call from C:
void idsUpdateBSCF( ushort filterState, ushort filterPos,
StatusType *status)
void idsUpdateBSCF( ushort filterState, ushort filterPos,
StatusType *status)

Call from DRAMA:

Invoke the IDS_BSCF action, with the following parameters:
Name: "Argument1" Type: Integer Contents: requested filter posn

Invoke the IDS_BSND action, with the following parameters:
Name: "Argument1" Type: Integer Contents: requested filter posn

7.11 idsGrating.c

TYPE:
C source-code file: two public functions, two private

PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the
grating angle in the IDS.

FUNCTION:
This component of the IDS server implements the IDS_GRATANG, and
IDS_CENWAVE DRAMA actions
and provides the facility for the position/state feedback to the
parameter system.

idsGratAng is the DRAMA task, which sends off a request to move the
grating angle, and reschedules awaiting the position update.
If this occurs within the alotted time, the action will timeout with an
error, otherwise it will terminate quietly.

idsUpdateGratAng will be called whenever the position/status of the grating
arrives from the IDS MMS. The position and state parameters in the DRAMA
parameter system are updated, and the IDS_GRATANG action (above) is
notified, if it was running. The derived slit parameters are updated if the
grating angle changes as the projected slit width may change.

The central wavelength (lambda) is calculated from the given grating angle
(theta) using the formula:

lambda = CameraFactor * (sin(theta - grat0) + sin(theta -grat0 +cameraAng)
/linesPermm

The required grating angle is requested from the given central wavelength
using the following formula:

theta = gratZero - (0.5 * camerAngle) +
arcsin( lambda * linesPermm / (2 * CameraFact * cos(.5*cameraAng)))

The values for cameraAngle and camerFact are given in idsInternal.h,
gratZero is initialised to the value in idsInternal.h but is stored
as a DRAMA parameter so may be modified if the encoder zero position
changes. linesPermm is dependant on the grating in use. lambda
corresponds to the central wavelength, in Angstroms, and theta
the grating angle in degrees. Degrees are used throughout the
equations, as are single precision floats.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h ids.h
Called:
msgLog idsMechInfo idsSlitUpdateDerived

DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.

INTERFACES:
Call from C:
void idsUpdateGratAng(long gratAngRawlong gratState,StatusType *status)

Call from C of private functions:
float calcGratpos_( float cenWave, StatusType *status);
float calcCenwave_( float gratAng, StatusType *status);

DITS action:
Invoke the IDS_GRATANG action, with the following parameters:
Name: "Argument1" Type: Int
Contents: (int) required encoder position of grating

Invoke the IDS_CENWAVE action, with the following parameters:
Name: "Argument1" Type: float
Contents: (float) central wavelength in angstroms

7.12 idsHart.c

TYPE:
C source-code file: two public functions

PURPOSE:
To provide facilities for the control and monitoring of the
state (open/closed) and the status (stable, moving,failed) of the two
hartmann shutters in the IDS.

FUNCTION:
This component of the IDS server implements the IDS_HART DRAMA action
and provides the facility for the position/state feedback to the
parameter system.

idsHart is the DRAMA task, which sends off a request to move the hartmann
mechanism, and reschedules awaiting the position update, and for the
mechanism to stabilize. If this occur within the alotted time, the
action will timeout with an error, otherwise it will terminate quietly.

In this function, the value of the arguments, indication the desired
positions of the two hartmanns are INVERTED - this is because it is
more normal for 1 to imply IN for a hartman and 0 out. But the
mechanism positions in the server generally have 1 as OUT. Hence the
invertion to make them consistent with the rest of the server.

idsUpdateHart will be called whenever the state of the hartman shutters
arrives from the IDS MMS. The position and state parameters in the DRAMA
parameter system are updated, and the IDS_HART (above) is notified, if it
was running.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h
Called:
msgLog protWrite

DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.

INTERFACES:
Call from C:
void idsUpdateHart (
long hartaPos, long hartbPos, long hartsStatus,
StatusType *status)

DITS action:

Invoke the IDS_HART action, with the following parameters:
Name: "Argument1" Type: Integer Contents:
'1' for Close hartmann A, '0' for Open Hartmann A
Name: "Argument2" Type: Integer Contents:
'1' for Close hartmann B, '0' for Open Hartmann B

7.13 idsInit.c

TYPE:
C source-code file: 1 public function, 1 private

PURPOSE:
Provides facilities to initialise the IDS server

FUNCTION:
This component of the IDS server implements the IDS_INIT DRAMA action.

idsInit implements the DRAMA task. It just calls idsLoadSetup (below)
and then ensures that any raw positions are set to invalid parameters
so that when the next status message arrives, and the position of the
mechanism is updated, the name will also be updated.

idsLoadSetup - reads the persistance file that contains the contents
of all the filter wheels (and dekker), definitions of the grating,
collimator and the camera in use. This gets called during startup
and with the idsInit/IDS_INIT action above.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h
Called:
mdbMount


DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.

INTERFACES:
Call from C:
void idsLoadSetup( StatusType *status)
With status the inherited status.

DITS action:
Invoke the IDS_INIT action, with no parameters

7.14 idsShutters.c

TYPE:
C source-code file: four public functions

PURPOSE:
To provide facilities for the control and monitoring of the
state (open/closed) and the status (stable, moving,failed) of the two
(235 and 500) camera shutters in the IDS and the grating shutter

FUNCTION:
This component of the IDS server implements the IDS_SHUTTER and IDS_GRATSHUT
DRAMA actions and provides the facility for the position/state feedback to the
parameter system.

idsShutter is the DRAMA task. The shutter to be moved is defined by the
CAMERAINUSE parameter, which is set up by the IDS_INIT DRAMA action. A
requested to move this shutter mechanism is sent to the MMS, and the action
reschedules awaiting the position update. If this occurs within the alotted time,
the action will timeout with an error, otherwise it will terminate quietly.

idsUpdateShutter will be called whenever the state of the IDS camera shutters
arrives from the IDS MMS. The position and state parameters in the DRAMA
parameter system are updated, and the IDS_SHUTTER action (above) is
notified, if it was running.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h
Called:
msgLog idsMechInfo

DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.

INTERFACES:
Call from C:
void idsUpdateShutter( long shutPos, long shutState, StatusType *status)
void idsUpdateGratShut( long shutPos, long shutState, StatusType *status)


DITS action:

Invoke the IDS_SHUTTER action, with the following parameters:
Name: "Argument1" Type: Integer Contents: '0' for Close, '1' for Open
Invoke the IDS_GRATSHUT action, with the following parameters:
Name: "Argument1" Type: Integer Contents: '0' for Close, '1' for Open

7.15 idsSlit.c

TYPE:
C source-code file: three public functions

PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the
slit position in the IDS.

FUNCTION:
This component of the IDS server implements the IDS_SLITWIDTH DRAMA action
and provides the facility for the position/state feedback to the
parameter system.

idsSlitWidth implements the DRAMA task, which sends off a request to move the
slit width, and reschedules awaiting the position update.
If this occurs within the alotted time, the action will timeout with an
error, otherwise it will terminate quietly.

idsUpdateSlitWidth will be called whenever the slit/status of the slit
arrives from the IDS MMS. The position and state parameters in the DRAMA
parameter system are updated, and the IDS_SLITWIDTH action (above) is
notified, if it was running.

idsSlitUpdateDerived should be called when ever anything that can effect the
derived slit parameters changes - this included the raw slit width, the
grating angle and the camera in use.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h idsInternal.h ids.h
Called:
msgLog idsMechInfo


DEPENDENCIES:
Dits should be running for the DRAMA action to be started, the
message log started, and the parameter system running.

INTERFACES:
Call from C:
void idsUpdateSlitWidth( long slitPos,long slitState,StatusType *status)
void idsSlitUpdateDerived(StatusType *status);

DITS action:

Invoke the IDS_SLITWIDTH action, with the following parameters:
Name: "Argument1" Type: Float, Contents: Required slitwidth in micrometers

7.16 ids.mk

# TYPE:
# makefile
#
# PURPOSE:
# Build the IDS server
#
# FUNCTION:
# The main targets are:
#
# build This builds the final executable, ids
#
# install If the execuatable hasn't been built, it is first build
# and then copied into the bin subdirectory os the
# dirctory indicated by the OBSSYS environment variable
#
# clean This removes the intermeadiate files generated byy a build
# and also all the source modules - should leave the
# working dirctory clear
#
# lint Lints the target instead of building.
#
# If no target is given - 'build' is assumed.
#
# If the environment variable PROJECT_DIR has been defined, the
# source code modules will be extracted from the SCCS directory
# before each is compiled. This should not be done for a release
# - as BOM should be used to extract.
#
# The module idsComm.c has strings for tests that get expanded by
# SCCS, so the file should be extracted using:
#
# sccd get -k idsComm.c
#
# This inhibits the keyword expasion, but leave the code unaffected.
# It does however mean the version number will not be found with 'what'
#
# SUBORDINATES:
# None.
#
# DEPENDENCIES:
# dramastart should have been run to define the locations of the DRAMA
# elements - libraries and headers.

7.17 ids.bom

# Bill of materials to build server for the IDS at v1.3:
#
#
# Set ${ING} to indicate the root of the source tree before building.
# You must have libcia installed to build this package.
# ${OBSSYS} must be correctly defined for the build to work.
#
# idsComm.c should be taken out with the -k option to stop keyword
# expansion.
#
# @(#) Component ids.bom 1.3 /ing/src/SCCS/s.ids.bom 96/11/19 15:21:08


Component ciaBoolean.h 1.1 sccs ${ING}/src
Component ids.h 1.9 sccs ${ING}/src
Component idsInternal.h 1.15 sccs ${ING}/src
Component idsAccess.c 1.7 sccs ${ING}/src
Component idsCollimator.c 1.7 sccs ${ING}/src
Component idsComm.c 1.17 sccs ${ING}/src
Component idsDekker.c 1.10 sccs ${ING}/src
Component idsFilters.c 1.8 sccs ${ING}/src
Component idsGrating.c 1.11 sccs ${ING}/src
Component idsHart.c 1.12 sccs ${ING}/src
Component idsInit.c 1.8 sccs ${ING}/src
Component idsServerMain.c 1.8 sccs ${ING}/src
Component idsShutters.c 1.7 sccs ${ING}/src
Component idsSlit.c 1.10 sccs ${ING}/src
Component ins.h 1.4 sccs ${ING}/src
Component insArchive.c 1.10 sccs ${ING}/src
Component insMain.c 1.9 sccs ${ING}/src
Component mdbMatch.c 1.3 sccs ${ING}/src
Component mdbMount.c 1.2 sccs ${ING}/src
Component srv.h 1.8 sccs ${ING}/src
Component srvArchive.c 2.2 sccs ${ING}/src
Component srvFindFile.c 1.1 sccs ${ING}/src
Component srvPingExit.c 1.2 sccs ${ING}/src
Component srvTalk.c 2.4 sccs ${ING}/src
Component insErr.msg 1.3 sccs ${ING}/src
Component srvErr.msg 1.1 sccs ${ING}/src
Component ciaActions.h 1.1 sccs ${ING}/src
Component mdb.h 1.1 sccs ${ING}/src

Component ids.mk 1.12 sccs ${ING}/src


Tag ids 1.3 TAG.c
Makefile ids.mk ids

8 The Client Components

8.1 Component list

idsClientTable.c Provides the table for generating the IDS clients with the INS client facility.

idsClients.mk Makefile for the IDS clients, produces the IDS_CLIENT executable and installs with all required links to produce the full range of clients.

idsClients.bom Bill of materials for a release of the IDS_CLIENT. Can be used by the "bom" facility to generate the executable.

idsChange.tcl Provides the change_ids client

icsMimic.tcl Provides the mimic for the IDS and AGB

8.2 Component relationships

The makefile idsClients.mk builds from idsClientTable.c and insClient.c, including assorted header files, creating the IDS_CLIENT executable.

The bill of materials idsClients.bom defines a release of the IDS_CLIENT executable. This can be given to the "bom" utility to generate the a released version.

The idsChange.tcl command needs the following datafiles in /ing/etc:

idsSettings Persistance file containing current contents of mechanisms

BSCF-0 Contents for below slit colour filter slide number 0

BSCF-1 Contents for below slit colour filter slide number 1

BSCF-2 Contents for below slit colour filter slide number 2

BSCF-3 Contents for below slit colour filter slide number 3

BSND-0 Contents for below slit ND filter slide number 0

BSND-1 Contents for below slit ND filter slide number 1

BSND-2 Contents for below slit ND filter slide number 2

BSND-3 Contents for below slit ND filter slide number 3

D-ENG Definition of the Engineering Dekker slide

D-FOS Definition of the FOS Dekker slide

D-IPCS Definition of the IPCS Dekker slide

D-OUT Definition Dekker with no slide in

D-P22 Definition of the 22arcsec Pairs Dekker slide

D-P43 Definition of the 43arcsec Pairs Dekker slide

D-SING Definition of the Single slit Dekker slide

collimator.dat Definitions of the different collimators available

grating.dat Definitions of the different gratings available.

An example of one of the SDS datafiles (filenames in capitals) is shown in appendix B. The other two data files, collimator.dat and grating.dat are textfiles. idsSettings is an SDS file showing the current contents of the exchangeable optics in the IDS.

8.3 idsClientTable.c

TYPE:
C source-code file: Table of action definitions

PURPOSE:
Lists the actions, arguments and lock for the simple IDS actions/clients

FUNCTION:
Defines the arrays and variables required when using the
INS client facility.

Variables declared:
serverName - name of server to connect to - "IDS"
cmdTable1 - Used to interpret required position of shutter
cmdTable2 - Declared as empty
insCommand - The command table describing each command available

SUBORDINATES:
None

DEPENDENCIES:
None

INTERFACES:
See reference [1]

REFERENCES:
INS-IDS-2 Interfaces to the IDS server (includes desciption of INS)

8.4 idsClients.mk

# TYPE:
# makefile
#
# PURPOSE:
# To build the cleints for use with the IDS CCD system.
#
# FUNCTION:
# The main targets are:
#
# build This builds the final executable, IDS_CLIENT
#
# install If the execuatable hasn't been built, it is first build
# and then copied into the bin subdirectory of the
# dirctory indicated by the OBSSYS environment variable,
# Finally all the softlinks are generated in the OBSSYS/bin
# that the user actually types
#
# clean This removes the intermeadiate files generated byy a build
# and also all the source modules - should leave the
# working dirctory clear
#
# lint Lints the target instead of building.
#
# If no target is given - 'build' is assumed.
#
# If the environment variable PROJECT_DIR has been defined, the
# source code modules will be extracted from the SCCS directory
# before each is compiled. This should not be done for a release
# - as BOM should be used to extract.
#
# SUBORDINATES:
# idsClientTable.c Client table specific to the IDS clients
# insClient.c INS facility for clients
# ciaErr.msg CIA messages
# insErr.msg INS messaged
# ciaRpc.h CIA RPC header
# ciaTalk.h CIA talker interface
# ciaBoolean.h CIA header for boolean_t and TRUE/FALSE
# ins.h INS interface header
#
# DEPENDENCIES:
# dramastart should have been run to define the locations of the DRAMA
# elements - libraries and headers.
#
# The CIA library should have been built before these clients

8.5 idsClients.bom

# Bill of materials to build client programs for the AGB at v1.2:
# several are built.
#
# Set ${ING} to indicate the root of the source tree before building.
# You must have libcia installed to build this package.
# ${OBSSYS} must be correctly defined for the build to work.
#
# @(#) Component idsClients.bom 1.2 /ing/src/SCCS/s.idsClients.bom 96/11/19 15:27:47

Assembly libcia 6.3 ${OBSSYS}/lib/libcia.a
Component insClient.c 1.2 sccs ${ING}/src
Component idsClientTable.c 1.4 sccs ${ING}/src
Component ciaBoolean.h 1.1 sccs ${ING}/src
Component ciaRpc.h 2.1 sccs ${ING}/src
Component ciaTalk.h 1.4 sccs ${ING}/src
Component ins.h 1.4 sccs ${ING}/src
Component ciaErr.msg 2.2 sccs ${ING}/src
Component insErr.msg 1.3 sccs ${ING}/src

Component idsClients.mk 1.4 sccs ${ING}/src


Tag IDS_CLIENT 1.2 IDS_CLIENT.TAG.c
Makefile idsClients.mk IDS_CLIENT

8.6 idsChange.tcl

# TYPE:
# Dtcl script (TCL with Drama extensions)
#
# PURPOSE:
# Provides a graphical method for seeing the contents of the
# exchangeable optics installed in the INT IDS, and of changing
# them.
#
# FUNCTION:
# The following functions are defined:
#
# accessPorts - sends the IDS_ACCESS action to request the
# unlatching of one of the ports. Since there is an interlock
# on the IDS shutter, this is closed first. With the grating
# port, the grating shutter must also be closed. Since this
# this moves the garting to the change position, the user must
# first confirm that they want this done. Once the requested
# port has been opened, the user is given a pop up window
# to indicate when they want the port latched again. The port
# can be accessed whenever this pop up window is shown.
#
# showConents - displays the contents of a filter wheel in a
# table that allows all the aspects of a 'filter' to be displayed
# and modified. This is also used for the dekker.
#
#
# changeFilterDefn - this is called when the 'change' button on
# the table produced by showContents is clicked. This verifies
# the user wishes to change the file on disk, if this is confirmed
# the file is re-written with any changes. It should be remembered
# this is not the persistence file that the server loads of startup
# but the definition file for that particular slide. For example
# changing the position of dekker 3 in the IPCS slide, changes the
# file D-IPCS. For this to be installed into the server, the
# "save changes" button must be clicked on the uppermost screen.
#
# idsChange - is called when the 'save changes' button is clicked on
# the top level screen. This causes the displayed filters etc to
# be started into the persistence file idsSettings, and the IDS
# server to be sent the IDS_INIT action to cause the file to be
# reloaded.
#
# idsLoadStartup - this is called when this script first starts. It
# reads the persistence file that the server used to initialise, and
# so ensures that the displayed contents of the filters is correct, or
# at least the same as the server thinks. All th various internal
# variables are initialised in this function.
#
# idsInitDisplay - draws the various boxes and buttons that makes up
# the display - including making the list of options when the
# buttons are pressed
#
# Initialisation code:
# The other code starts up the main window, adding the exit and
# save buttons along the top, provides names for the icon and a title
# then calls idsLoadStartup and idsInitDisplay
#
# SUBORDINATES:
# The IDS server should be running.
#
# The following files must be present in the directory indicated by
# fileSource:
# BSCF-0 BSCF-1 BSCF-2 BSCF-3
# BSND-0 BSND-1 BSND-2 BSND-3
# D-OUT D_ENG D-IPCS D_MISC D-CORO D-P42 D-P22 D-SING D-FOS
# grating.dat collimator.dat
# idsSettings

8.7 icsMimic.tcl

# TYPE:
# Dtcl script (TCL with Drama extensions)
#
# PURPOSE:
# Provides the mimic for the INT cass instrumentation, ie the A&G and IDS
#
# FUNCTION:
# When this script starts, all unmoving elements are drawn in black.
# These will not be effected by the moving parts of the mimic.
#
# Internal variables are created that represent the positions and
# stati of all the mechanisms. Drama Get and Monitor transactions
# are then kicked off that ensure these internal variables hold
# the same values as those in the servers themselves. If a parameter
# value in the server changes, the monitor call back function in this
# script will be called - ensuring the local variable gets updated.
#
# Whenever the callback function is called, implying a parameter in
# one of the servers has changed the appropriate mimic is redrawn. If
# the AGB section gets redrawn, the IDS section will also be redrawn
# to ensure the light path is current, even if no mechanisms in the IDS
# have changed.
#
# When a lightpath colour is set to 0 it will not be printed, this avoids
# writing over things with background colours
#
# Usage:
# icsMimic.tcl -n MIMIC -b 100000
# The name "MIMIC" should be different for each mimic runnin
# concurrently. The -b option specifies the buffer size.
#
# SUBORDINATES:
# The IDS and AGB servers should be running.

Appendix A. Low Level Communications

The MMS communicates via an RS232 connection. The protocol used is briefly described below. A global status request is made every IDSTO_REQSTATUS microseconds. This is set in idsInternal.h to 1 second (1000000 usecs). These commands are defined in reference [1], but there have been a few modifications to mechanism, and this briefly describes the commands used by the IDS server.

Commands

Dekker slide &A100xxx xxx is required pon in units of 0.1mm (Hex)

Slit Jaw &B100xxx xxx is required posn in units of 0.005mm (Hex)

Below slit colour filter &C40000x x is position required (1,2 or 3)

Below slit ND &C50000x x is position required (1,2,or 3)

Slit Shutter Now under control of CCD controller

Collimator &E100xxx xxx is required position in units of 0.05mm (Hex)

Hartmanns &F1000nm n is position of hartmann A (1 closed, 2 open) m is position of hartmann B (1 closed 2 open)

Grating angle &G1xxxxx xxxxx is position required (0-359.99 BCD)

Observers port access &H40000n n is 1 to allow access and close camera shutters 2 to release latch

Collimator port access &H50000n n as above

Grating port access &H60000n n as above

IDS 235 shutter &I10000n n = 1 to open shutter, 2 to close

IDS 500 shutter &I20000n n as above

Global status request &K200000 Requests A-L &K300000 Requests A-P &K400000 Enter monitor mode &K500000 Exit monitor mode

Status

The number is brackets defined the bit used in the nibble specified.

Dekker slide %Afu0xxx f(3) 1 = not in commanded position u - limits and clamps status xxx encoder reading (Hex)

Slit Jaw %Bfu0xxx f as above u jaw 1 and 2 status? xxx encoder reading (Hex)

Filters %Cf0abmn f as above a and b, valves 1,2,3,4,5 and 6, and optos? m(0) 1 = Slide A (Colour) position 1 m(1) 1 = Slide A position 2 m(2) 1 = Slide A position 3 m(3) 1 = Slide A detented n(0) 1 = Slide B (ND) position 1 n(1) 1 = Slide B position 2 n(2) 1 = Slide B position 3 n(3) 1 = Slide B detented

Slit shutter %Df000ab f as above a(0) 1 = Slit shutter closed a(1) 1 = Slit shutter open

Collimator %Eab0xxx a(3) 1 = Not in command position b ignored xxx Encoder reading in HEX

Hartmann %Ff0ab0d f as above a & b ignored d(0) 1 = Vane A Closed d(1) 1 = Vane A Open d(2) 1 = Vane B Closed d(3) 1 = Vane B Open

Grating %Guxxxxx u(0) 1 = Low limit reached u(1) 1 = High limit reached u(2) 1 = Change position u(3) 1 = Not in command position xxxxxx Encoder position

Ports %Hfxyzab f as above x Observer's port y Collimator port z Grating port port(0) 1 = Port open port(1) 1 = Latch operated a & b not used ( grating and slit illumination)

IDS shutters %If0b0a0 f as above a(0) = 235 shutter Closed a(1) = 235 shutter Open a(2) = 500 shutter Closed a(3) = 500 shutter Open

Common (faults) %K00cdef See reference [1]

Appendix B. MDB data file

This shows an example listing of one of the files used to maintain the mountables database. This listing is obtained with the command: sdslist BSCF-1

I/IDS/BSCF Struct
1 Struct
mechanism Char [7] "BSCF-1"
code Int 0
invocation Char [2] "0"
filter Struct
uniqueId Char [3] "F0"
waveband Char [6] "Clear"
photoSys Char [1] ""
focusOffset Float 0
2 Struct
mechanism Char [7] "BSCF-1"
code Int 1
invocation Char [2] "1"
filter Struct
uniqueId Char [3] "F1"
waveband Char [7] "BG 1.1"
photoSys Char [1] ""
focusOffset Float 0
3 Struct
mechanism Char [7] "BSCF-1"
code Int 2
invocation Char [2] "2"
filter Struct
uniqueId Char [3] "F2"
waveband Char [7] "BG 1.2"
photoSys Char [1] ""
focusOffset Float 0

Appendix C. Document History

Issue 1.1 1997-11-03 Informally released as INS-IDS-1.

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