2 Architecture

2.1 System Context

Figure 1. is the context diagram for the JAG server. The primary data and control source is the JAG MMS itself. It is this that controls the position of all the mechanisms and reports the position and status of all mechanisms.

The system is responsive to all kinds of DRAMA transactions. The interface for incoming transactions are defined in section 4. The interface to the talker is defined in reference [7].

The DRAMA parameter database (JAG_parameters) is described in section 5. The archive action causes a FITs packet file to be written to disk. This is described in reference [4]. The environment variables and command line arguments provided by the parent process are outlined in reference [4] and section 6. The low level communications messages between the server and the JAG controller (MMS) are described in the Detailed Design, reference [2]. When the server starts up and when the JAG_INIT action is invoked, the contents of the JAG_Settings file are reloaded - the structure of this file is outlined in section 6.2.

2.2 Communications

The communication to and from the JAG 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 JAG server has initialisation code, and 8 actions. The detail of the actions is described in section 4. Most of the actions correspond to the movement of a mechanism. The exceptions are the PING and EXIT actions, provided by the srv facility (referecnce [6]), the ARCHIVE action, described in reference [4], and the JAG_INIT action. The JAG_INIT action causes the mountables database (reference [3]) to be reloaded.

Most of the initialisation code is provided by the INS facility, described in reference [4].

2.4 Clients

All except the edit_table and edit_main and autoXY clients are provided by the INS client facility, described in reference [4], with a table defining the implementation in the JAG. A series of soft links are used to provide the different commands for the user.

The edit_main client is provided by a DTCL script. If the filters in the main filter wheel are changed, this command provides a graphic way to edit the filter database. Once the change is made, the new filter wheel contents are stored in the settings file and the JAG server executes the JAG_INIT action. Next time the server starts up this settings file will be re-loaded, thus ensuring the server always has an up-to-date database of all the filter wheel contents. This is described in more detail in reference [2]. A similar system is provided for the correspondance table by the edit_table client.

The autoXY client is used to provide a link between the TCS and the A&G box servers. This is required only when the Autoguider is NOT an array type detector. This is because the guide probes need to move to get the guide star dead centre of the image disecting tube, during the acquire cycle. This task monitors the parameters in the TCS drama task that represent movement requests sent down the inter processor link from the TCS. When these parameters change, the movement is forwarded to the JAG server.

2.5 Mimic

The mimic is defined in reference [4] and described in detail in reference [5]. This is a joint ICS/JAG mimic.

3 Behaviour of the JAG server

Some of the actions that can be started can take some time to complete. 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 JAG controller, which may continue to move a mirror, or change filter without any action from the server. Therefore it is recommended that this feature be used sparingly and with caution.

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

The JAG 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 correspondance table is used to keep the autoguider in focus. For each filter in the main wheel, one or more filters of the same optical thickness are selected for the autoguider. This means that when the telescope is focused for the science CCD, the autoguider is also in focus.

There is also a database for the contents of the main filter wheel. This will need to be edited when the user changes filters.

Both these databases will be written as SDS structures, and accessed via an editor. After editing, the command jag_init must be issued to load the new data.

The server is required to provide a FITS packet describing the state of all the mechanisms. This is provided by the Archive Collection utility, part of the INS facility, described in detail in reference [4].

The TV and autoguider probes movements do not seem to have the status handled correctly by the MMS. So when testing for action/movement completetion, the actual position should be compared to the required position. Some tolerence of the position values should be permitted.

4 Command interface

The JAG server registers with the DRAMA message-system as `JAG'. Note also that case is significant when invoking this program by name. If the host computer for the JKT is, say, lpss6, then the JAG server can be addressed as JAG@lpss6.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 5. Action names are all in upper case: this makes 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.

JAG_TVM changes the position of the TV mirror.
One parameter
Argument1 (integer) Requested position of the TV mirror. The value can be interpreted using the following definitions in jag.h: JAG_IN 0, JAG_OUT 1

JAG_TVS changes the position of the TV shutter.
One parameter:
Argument1 (integer) specifies the requested position of the TV shutter. The value can be interpreted using the following definitions is jag.h: JAG_IN 0, JAG_OUT 1

JAG_MAINFILT changes the main filter.
One parameter:
Argument1 (integer) specifies the filter number requested, it should be in the range, defined in jag.h: JAG_MAINFMIN 0, JAG_MAINFMAX 7

JAG_AUTOCOL changes the autoguider colour filter.
One parameter:
Argument1 (integer) specifies the filter number requested, it should be in the range, defined in jag.h: JAG_AUTOCOLMIN 0, JAG_AUTOCOLMAX 7

JAG_AUTOND changes the autoguider neutral density filter.
One parameter:
Argument1 (integer) specifies the filter number requested, it should be in the range, defined in jag.h: JAG_AUTONDMIN 0, JAG_AUTONDMAX 7

JAG_AUTOXY moves the autoguider acquisition probe to the specified position. Two parameters:
Argument1 (integer) specifies the required X position in encoder units. (405000 - 595000) Argument2 (integer) specifies the required Y position in encoder units. (405000 - 595000)

JAG_INIT initialises the server. This causes all the files defining the contents of the filter trays, and calibration lamps 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 JAG to the named fits file. This is the standard action from the srv package, with the INS archive facility.

5 Parameter interface

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.

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

TVMIRROR (unsigned short integer) defines the position of TV mirror. This value is set by the movement of the mechanism, and can be interpreted using the following definitions in jag.h:
JAG_TVMIN 0
JAG_TVMOUT 1

TVMSTATE (signed short integer) defines the state of the flip mirror 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

TVSHUTTER (unsigned short integer) defines the position of the TV shutter. This value is set by the movement of the mechanism, and can be interpreted using the following definitions in jag.h:
JAG_IN 0
JAG_OUT 1

TVSHUTSTATE (signed short integer) defines the state of the TV shutter 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

MAINFPOS (unsigned short integer) defines the position of the main filter. This value is set by the movement of the mechanism

MAINFSTATE (signed short integer) defines the state of the above 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

MAINFNAME (character string) is a string that usefully describes the main filter currently in the beam - that is not the name of the complete slide, but the particular one in use.

AUTOCOLPOS (unsigned short integer) defines the position of the autoguider colourfilter. This value is set by the movement of the mechanism

AUTOCOLSTATE (signed short integer) defines the state of the autoguider colour filter wheel. 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

AUTOCOLNAME (character string) is a string that usefully describes the autoguider colour filter currently in position - that is not the name of the complete wheel, but the particular filter in use.

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

AUTONDSTATE (signed short integer) defines the state of the autoguider neutral density filter wheel. 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

AUTONDNAME (character string) is a string that usefully describes the autoguider neutral density filter currently in position - that is not the name of the complete wheel, but the particular filter in use.

AUTOXPOS (unsigned short integer) defines the X position of the autoguider.. This value is set by the movement of the mechanism

AUTOXSTATE (signed short integer) defines the state of the autoguider Xmotor. 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

AUTOYPOS (unsigned short integer) defines the Y position of the autoguider motor.. This value is set by the movement of the mechanism

AUTOYSTATE (signed short integer) defines the state of the autoguider Y motor.. 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

AGVIGNETTE (unsigned short integer) defines the state of the autoguider probe with regard to vignetting the beam. TRUE (!0) implies the beam is vignetted by the autoguider probe.

SHUTTERPOS (unsigned short integer) is the current position of the shutter. The value can be taken from the enumerated type SCCD_shutter_posn_t as defined in sccd.h. It can take the following values:
SHUTTER_OPENED 0
SHUTTER_CLOSED 1

SHUTTEROK (unsigned short integer) indicates the shutter status, and takes the value 0, or FALSE if the shutter is jammed, and !0 or TRUE otherwise.

HARTMANPOS (unsigned short integer) is the current position of the Hartmann shutter. The shutter is obsolete, and should not move. This is set on full status returns from the JAG micro, and can take the following values, as defined in sccd.h:
SHUTTER_OPENED 0
SHUTTER_CLOSED 1

GRISMPOS LGRISMPOS (unsigned short integer) is the current position of the left grism. The Grisms are obsolete, and should not move. However their position will be monitored using status returns from the JAG micro.

RGRISMPOS (unsigned short integer) is the current position of the right grism. The Grisms are obsolete, and should not move. However their position will be monitored using status returns from the JAG micro.

DRIFTPOS (unsigned short integer) is the current position of the drift table. The drift table is obsolete, and should not move. However its position will be monitored using status returns from the JAG micro.

6 System interface

6.1 Parent process

The JAG server requires the executable jag to be in the search path (environment variable PATH). It is started by executing the command JAG with one argument indicating 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:

jag /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 "JAG".

The following environment variables are used by the JAG server:

LOGS defines the location for the log file produced by this server, JAG_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, JAG_yymmdd.log. If it is undefined, the log file will be called JAG_NULL.log

HDR_TEMPLATES defined the location of the FITS header template files. These are named jagHdr.BEGIN and jagHdr.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.

6.2 Data files

The following files are required by the JAG server:

jagHdr.BEGIN defines the header packets to be collected at the start of an observation. See reference [5] for details of the format. This file should be stored in the location indicated by HDR_TEMPLATES above.

jagHdr.END defines the header packets to be collected at the end of an observation. See reference [5] for details of the format. This file should be stored in the location indicated by HDR_TEMPLATES above.

jagSettings is used to provide persistent information above the exchangeable optics in use in the instrument. It should be available in the OBSSYS directory tree. The format of the file is defined by reference [5] and should have the following elements:

I/JAG/MAINF describes the contents of the main filter tray

I/JAG/AUTOND describes the contents of the autoguider neutral density filter tray

I/JAG/AUTOCOL describes the contents of the autoguider colour filterwheel

The change command needs to have access to the conents of all the filter wheels and slides, even those that are not currently in use. These are available in data files created with sdsWrite, the contents of which can be viewed with the change command or the sdslist command. An example output from the INT version of sdslist can be seen in reference [8]. The following files should be available in the /ing/etc dirctory.

AUTOCOL Contents of the autoguider colourfilter wheel

AUTOND Contents of the autoguider neutral densityfilter wheel

MAINFILT Contents of the main filter wheel

7 Compile-time interfaces

jag.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

On September 1997 a draft version of this document was released.

Sheila Crosby