2 Standards, Conventions and Procedures

2.1 Coding standards

All C code will be ANSI complient, and POSIX calls will be used whenever available.

2.2 Documentation standards

Technical documentation is produced using the ESA standards as a guide. They are produced in HTML format, and will be 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 will be 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: jagUpdateAutoCol().

Names of data types have the suffix "_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 jagComm.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 [3].

3 JAG Implementation

3.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 JAG. It sets it to 9600 baud, 7 bit, parity enabled. It also 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 JAG MMS 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 (jagMechInfo()) 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 JAG 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 JAG MMS. These arrive in the format described in Appendix A. The position and status of every mechanism is extracted from the return message and all the update functions are called to ensure the parameter system and outstanding actions get notified.

3.2 Filters

The filters in the main filter wheel can be changed, and there will be a GUI provided to edit the accompanying database and correspondance table.

There are two autoguider filter wheels. It is impossible to change these filters without striping down the JAG. Therefore there will be no pretty GUI editor for these filters. However, there will be an sds database for them. This means that if the filters are ever changed, the file can be updated using sdspoke without rebuilding the software, but the observers are unlikely to do anything silly.

Although the mountables database is used to maintain the filter names, the absolute filter wheel position should be given as the argument to the Drama action. All filters wheel ranges are set so that position 0 is clear.

The contents of each filter wheel is maintained in an SDS file. These are kept in ${OBSSYS]/../etc and can be read with sdslist.

3.3 TV Mirror

The run command should make sure that the TV mirror is out of the way before the exposure is taken.

4 Clients and Mimic Implementation

4.1 INS clients

All except the change command, mainfilt and the mimic (described below) are implemented using the INS client facility, described in reference 2. A table is used to define all the clients. When this is compiled with the INS facility, one executable is generated - JAG_CLIENT. When the install target of this is made ("make -f jagClients.mk install") this executable is moved to the observing system binary directory (pointed to by the environment variable OBSSYS). The soft links to this executable are generated also with in the $OBSSYS/bin directory. These soft links are named "autocol", "autoxy" etc, and are what the user executes. When the JAG_CLIENT starts executing it extracts the command name used to invoke it - this will be the name of the link - eg "autoxy". 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 JAG server to initiate.

4.2 Change_filt command

The change_filt command is implemented with the jagChange.tcl script. It is written using the Drama extention to Tcl. When it starts, it retrieves the current configuration from the jagSettings file, found in ${OBSSYS}/../etc. This is used to set the values for the various internal parameters.

There are three filter wheels; one main wheel in front of the science CCD and two in front of the autoguider. Datafiles are stored on disk defining the contents of each of the wheels. Once a wheel has been selected, the corresponding data file is loaded, and the contents of the wheel can be viewed by hitting the "View wheel contents". This shows the contents of the data file read from disk. For the main filter wheel only, all the fields shown can be modified. These fileds are: filter position, filter name, unique filter id, optical thickness, and corressponding autoguider colour and ND filters. When the "Change" button is clicked, the software will check whether the optical thickness of each filter matches the optical thickness of the combined autoguider filters assigned to it. Then the contents of the data file are 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 JAG server itself.

The two autoguider filter wheels (autocol and autond) wheels do not have alternative wheels to insert. The contents of the wheel can be viewed by clicking on the "View wheel contents" button. The contents cannot be modified.

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 jagSettings file in the ${OBSSYS}/../etc directory. The JAG server is then sent an JAG_INIT action which causes it to reload the jagSettings file. There is no other link between the change command and the server. This means that any changes become the default startup configuration.

4.3 autoXY command

The guide probes are under the control of the JAG server. With the non-array autoguider, the TCS must move the guide probes during the acquire stage to get the target guide star in the centre of the image to allow guiding. This is done by the TCS sending a movement request down the Inter Processor Link (IPL). These movement requests are only relative positions as the TCS does not know the position of the autoguider probe. The IPL is connected to the instrument control Sparc running the TCS Drama task. The TCS Drama task maintains a Drama parameter of the value of these requested values. When ever a new request from the TCS arrives, these values will be updated. A command can also be entered at the TCS to request an absolute XY position for the autoguider probe. This is also sent as a message down the IPL which is interpretted by the TCS Drama task which maintains them as parameters,

The autoXY.tcl script sets up a monitor on the parameters in the TCS server that hold the requested relative movements and the requested absolute XY positions. If any of these change, the local copies in the autoXY task get updated, and the JAG_AUTOXY action in the JAG server is invoked with the appropriate position. The autoXY task must also maintain a local copy of the current autoguider XY position to work out the desired position when the TCS sends relative positions.

4.4 Mimic

The mimic is implemented with the jagMimic.tcl script. It is written using the Drama extention to Tcl (DTCL). The mimic for the JKT covers both the science CCD and the A&G box. These are controlled by the CCD and JAG 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 that variable, the DRAMA fixed 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 mechanism. It also causes the mimic to be completely redrawn. This may seem excessive for just one mechanism moving, but it is simpler, and means the light path is up to date at all times. Indeed if any mechanism in the A&G moves, the JAG 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. In the JAG MMS, the status of the X and Y motors of the Autoguider probe are the same.

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 another observer 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:

jagMimic.tcl -b 100000 -n OBSMIMIC &

5 The Server Components

5.1 Component list

As well as the INS components listed in reference [2]. the JAG server has the following components

jagServerMain.c Provides the action map and parameter database

jag.h Provides interfaces to the JAG server that might be required by external clients.

jagInternal.h Provides definitions and macros that are required internally to the JAG server only.

jagComm.c Provides the portRead function to receive lines from the serial port, and jagMechInfo which is used to send movement requests down the serial port.

jagFilters.c Implements the JAG_MAINFILT, JAG_AUTOCOL and JAG_AUTOND actions, and the corresponding update functions to maintain the parameters for these mechanisms

jagInit.c Implements the JAG_INIT action, which causes the jagSettings file to be reloaded.

jagTVMirror.c Implements the JAG_TVMIRROR action for moving the TV mirror, and provides the update function for maintaining the related parameter.

jagAuto.c Implements the JAG_AUTOXY action and provides the corresponding update function for maintaining the related parameters

jagTVShutter.c Implements the JAG_TVSHUTTER action and provides the corresponding update functions for maintaining the related parameters

jag.mk Makefile for the JAG server - creating the "jag" executable.

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

5.2 Component relationships

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

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

5.3 jagServerMain.c

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

PURPOSE:
To provide facilities for the JAG server:
starting the parameter system.
defining the action handlers


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

startParamSys starts the parameter system, adds all the parameters required
for the JAG server, and initialises then

startActions defines the action handlers corresponding to the DITS
actions

The C entry function main is implemented in insMain.c

SUBORDINATES:
None

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:
"Interfaces to the JAG servers"
RGO/ING document JKT-JAG-2

5.4 jag.h

TYPE:
C source-code: include-file.

PURPOSE:
Defines values needed by external clients of the jag server, either for
limit checking for for interpretation of the JAG parameters.

FUNCTION:
Defined the following:
JAG_IN JAG_OUT JAG_BETWEEN - position of shutters and TV mirror

JAG_AUTOCOLMIN JAGAUTOCOLMAX - Autoguider colour filter wheel limits
JAG_AUTONDMIN JAG_AUTONDMAX - Autoguider ND filter wheel limits
JAG_MAINFMIN JAG_MAINFMAX - Main filter wheel limits

JAG_AUTOXMAX JAG_AUTOXMIN - Autoguider probe movement limit
JAG_AUTOYMAX JAG_AUTOYMIN

SUBORDINATES:
None.

DEPENDENCIES:
None.

5.5 jagInternal.h

TYPE:
C source-code: include-file.

PURPOSE:
Defines values used internally the jag server.

FUNCTION:
Enumerated type:
JAG_Mech_t - lists the mechanisms of the A&G Box

Definitions and macros:
JAGTO_AUTOCOL JAGTO_AUTOND - Mechanism timeouts in seconds
JAGTO_MAINFILT JAGTO_AUTOXY
JAGTO_TVMIRROR
JAGTO_TVSHUTTER

AGB_AGVZXU AGB_AGVZXO - Defines region of AG vignetting
AGB_AGVZYU AGB_AGVZYO

JAG_AGXCENTRE JAG_AGYCENTRE - Defines AG probe central position

JAG_AGXPARK1 JAG_AGYPARK1 - Defines AG probe's park 1 position
JAG_AGXPARK2 JAG_AGYPARK2 - Defines AG probe's park 2 position

JAG_AGTOL JAG_TVTOL - Tolerance in AG and TV probe positions

JAGTO_REQSTATUS - Time in milliseconds between status polls

SUBORDINATES:
None.

DEPENDENCIES:
Depends on some definitions from jag.h which should be included before this

5.6 jagComm.c

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

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

FUNCTION:
The portInit function initialises the named serial port device
for communication with the JAG micro. It also triggers the requestStatus_
function which reschedules itself every JAGTO_REQSTATUS milliseconds, and
sends a full status request message. This ensures that the 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 is interpretted, by decomposing to the status bytes.
The interpretation of each status byte is dependent
on the mechanism. The appropriate update function is then notified
of the new position and status of the mechanism.

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 jagInternal.h jag.h insErr.h

Called:
jagUpdateAutoCol jagUpdateAutoND jagUpdateMainFilt jagUpdateTVShutter jagUpdateAGXProbe jagUpdateAGYProbe
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(JAG_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 AGB server"
RGO/ING document INS-AGB-1

5.7 jagFilters.c

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

PURPOSE:
To provide facilities for the control and monitoring of the position and the status (stable, moving,failed) of the various filters in the A and G box, these are:

Main filter (MAINFILT)
Autoguider neutral density filter (AUTOND)
Autoguider colour filter (AUTOCOL)

FUNCTION:
This component of the IDS server implements the JAG_MAINFILT, JAG_AUTOCOL and JAG_AUTOND DRAMA actions and provides the facility for the position/state feedback to the parameter system for all these mechanisms

jagAutoCol jagAutoND jagMainFilt
These functions implement the correspoonding DRAMA tasks by sending off a request to the JAG MMS, reschedules awaiting the postion update. If this does not occur before the timeout, the action returns with a mechanism timeout error. If it does return before the timeout, then if the status shows it is still moving, the action reschedules, if the status shows a mechanism failure, the action returns a MECHFAIL error, otherwise, if the status shows the mechanism has stopped movement, and the mechanism is in the requested position, the action will return normally. If the mechanism has stopped moving but is not in the requested position, a mechanism failure is reported. If the action is kicked, the action will terminate with an ABORT error. This can be used to terminate actions before timeouts.
The JAG_MAINFILT action will use all these three functions to move all three filter wheels.

jagUpdateAutoCol jagUpdateAutoND jagUpdateMainF
These functions are called whenever the status or position of the corresponding mechanism arrives from the MMS. The position and state parameters for the mechanism will be updated and, if the corresponding DRAMA action (above) is running, it will be notified of the change. 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 jagInternal.h
Called:
msgLog jagMechInfo insMatchCode


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 jagUpdateAutoCol( long pos, long state, StstusType *status)
void jagUpdateAutoND( long pos, long state, StstusType *status)
void jagUpdateMainFilt( long pos, long state, StstusType *status)



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

5.8 jagInit.c

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

PURPOSE:
Provides facilities to initialise the JAG server

FUNCTION:
This component of the JAG server implements the JAG_INIT DRAMA action.

jagInit implements the DRAMA task, which installs the filter wheel contents
for all the filter wheels in the A&G box.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h jag.h mdb.h
Called:
msgLog


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

INTERFACES:

DITS action:

Invoke the JAG_INIT action, with no parameters

5.9 jagMirror.c

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

PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the
TV mirror in the A and G box

FUNCTION:
This component of the JAG server implements the JAG_TVM action. and provides the facility for the position/state feedback to the parameter system.
jagTVMirror implements the JAG_TVMIRROR DRAMA task, which sends off a request to move the TV mirror, 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.
JagUpdateTVMirror will be called whenever the position/status of the TV
mirror arrives from the JAG MMS. The position and state parameters in
the DRAMA parameter system are updated, and the JAG_TVMIRROR action (above) is
notified, if it was running.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h jagInternal.h jag.h
Called:
msgLog jagMechInfo


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 jagUpdateTVMirror( long pos, long state, StstusType *status)
Where `pos` == JAG_IN or JAG_OUT.
DITS action:

JAG_TVM action is invoked with the following parameter:
Name: "Argument1" Type: Integer,
Contents: JAG_IN (0) or JAG_OUT(1)

5.10 jagAutoXY.c

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

PURPOSE:
To provide facilities for the control and monitoring of the
position and the status (stable, moving,failed) of the
autoguider probe in the A and G box.

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

jagAutoXY implements the JAG_AUTOXY DRAMA task, which sends off
a request to move the autoguider probe, 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.

idsUpdateAutoXY will be called whenever the position/status of the autoguider
probe arrives from the JAG MMS. The position and state parameters in
the DRAMA parameter system are updated, and the JAG_AUTOXY action (above) is
notified, if it was running.

SUBORDINATES:
Included:
insInternal.h insErr.h ciaBoolean.h jagInternal.h
Called:
msgLog jagMechInfo


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 jagbUpdateAutoX( long pos, long state, StatusType *status)
void jagbUpdateAutoY( long pos, long state, StatusType *status)


DITS action:
JAG_AUTOXY action is invoked with the following parameters:
Name: "Argument1" Type: Integer, Contents: X position
Name: "Argument2" Type: Integer, Contents: Y position

5.11 jagTVShutter.c

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

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

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

jagTVShutter implements the DRAMA task, which sends off a request to move
the TV shutter 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.

jagUpdateTVShutter will be called whenever the position/status of the
TV shutter arrives from the JAG MMS. The position and state parameters
in the DRAMA parameter system are updated, and the JAG_TVS action (above)
is notified, if it was running.

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


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 jagUpdateTVShutter( long pos, long state, StstusType *status)
Where 'pos' in JAG_IN when the shutter is in position, ie
stopping light getting to the TV, and JAG_OUT when out.
(both these are defined in jag.h)


DITS action:

Invoke the JAG_TVS action, with the following parameters:
Name: "Argument1" Type: Integer,
Contents: 0 for Closed, 1 for Open

5.12 jag.mk

# TYPE:
# makefile
#
# PURPOSE:
# makes the jag server
#
# FUNCTION:
# The main targets are:
#
# build This builds the final executable, sccd
#
# 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.
#
# SUBORDINATES:
# jagServerMain.c
# jagFilters.c
# jagMirror.c
# jagTVShutter.c
# jagComm.c
# jagAutoXY.c
# jagInit.c
# srvArchive.c
# srvFindFile.c
# insArchive.c
# insMain.c
# srvPingExit.c
# mdbMount.c
# mdbMatch.c
# srvTalk.c
# insErr.msgt
# srvErr.msgt
# jagInternal.h
# ciaBoolean.h
# jag.h
# srv.h
# mdb.h
# ins.h
#
# DEPENDENCIES:
# dramastart should have been run to define the locations of the DRAMA
# elements - libraries and headers.

5.13 jag.bom

# Bill of materials to build server for the JAG at v1.0
#
#
# 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 ciaBoolean.h 1.1 sccs ${ING}/src
Component jag.h 1.7 sccs ${ING}/src
Component jagInternal.h 1.14 sccs ${ING}/src
Component jagComm.c 1.28 sccs ${ING}/src
Component jagFilters.c 1.8 sccs ${ING}/src
Component jagInit.c 1.3 sccs ${ING}/src
Component jagMirror.c 1.7 sccs ${ING}/src
Component jagAutoXY.c 1.10 sccs ${ING}/src
Component jagServerMain.c 1.8 sccs ${ING}/src
Component jagTVShutter.c 1.7 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 jag.mk 1.11 sccs ${ING}/src


Tag jag 1.3 TAG.c
Makefile jag.mk jag

6 The Client Components

6.1 Component list

As well as those components listed in reference. the JAG clients has the following components

jagClientTable.c Provides the table for generating the JAG clients with the INS client facility.

jagClients.mk Makefile for the JAG clients, produces the JAG_CLIENT executable and installs with all required links to produce the full range of clients.

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

jagChange.tcl Provides the change_jag client

autoXY.tcl Provides the mechanism for forwarding autoguider probe move requests from the TCS to the instrument.

6.2 Component relationships

The makefile jagClients.mk builds from jagClientTable.c and insClient.c, including assorted header files, creating the JAG_CLIENT executable.

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

The jagChange.tcl command needs the following datafiles in ${OBSSYS}/../etc:

jagSettings Persistance file containing current contents of mechanisms

MAIN Contents of main filter wheel

AUTOCOL Contents of autoguider colour filter wheel

AUTOND Contents of autoguider ND filter wheel

6.3 jagClientTable.c

TYPE:
C source-code file: produces a table for insClient.c

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

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

Variables declared:
serverName - name of server to connect to - "JAG"
cmdTable1 - Used to interpret required position of hartmann shutter
cmdTable2 - Used to interpret required position of other shutters
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)

6.4 jagClients.mk

# TYPE:
# makefile
#
# PURPOSE:
# To build the clients for use with the JAG system.
#
# FUNCTION:
# The main targets are:
#
# build This builds the final executable, JAG_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:
# jagClientTable.c Client table specific to the JAG 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.

6.5 jagClients.bom

# Bill of materials to build client programs for the JAG 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.
#

Assembly libcia 6.3 ${OBSSYS}/lib/libcia.a
Component insClient.c 1.2 sccs ${ING}/src
Component jagClientTable.c 1.5 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 jagClients.mk 1.5 sccs ${ING}/src


Tag JAG_CLIENT 1.2 JAG_CLIENT.TAG.c
Makefile jagClients.mk JAG_CLIENT

6.6 jagChange.tcl

TYPE:
Dtcl script (TCL with Drama extensions)

PURPOSE:
Provides a graphical method for seeing the contents of the echangeable optics installed in the INT A&G box, and of changing them.

FUNCTION:
The following functions are defined:

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 name of filter 1 in mainfilter wheel 1, changes the file MAINFILT-1. For this to be installed into the server, the "save changes" button must be clicked on the uppermost screen.

jagChange - 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 jagSettings, and the JAG server to be sent the JAG_INIT action to cause the file to be reloaded.

jagLoadStartup - 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 the various internal variables are initialised in this function.

jagInitDisplay - 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 jagLoadStartup and jagInitDisplay
SUBORDINATES:
The JAG server should be running if it is required to save any changes
The following files must be present in the directory indicated by fileSource:
MAIN AUTOCOL AUTOND

6.7 autoXY.tcl

# TYPE:
# tcl script
#
# PURPOSE:
# Forwards guide probe moves from TCS to JAG servers
#
# FUNCTION:
# Monitors the TCS parameters that are changed when a move
# is requested, and sends an obey message to theJAG server,
# requesting the guide probes to move. If the GD_X or GD_Y
# parameters on the TCS change, then the absolute positions
# of the guide probes are being requested. If however the
# GDOF_X or GDOF_Y parameters change, then this is a delta
# movement commend, typically issued when the TCS is trying
# to pull in the probes. This will have the current position
# added to the requested offset before being forwarded to the
# JAG server.
#
# USAGE:
# autoXY.tcl -n PROBES -b 50000
#
# SUBORDINATES:
# None.

7 The Mimic Components

7.1 Component list

jagMimic.tcl The source code for the Mimic.

jagMimic.mk Makefile for the JAG mimic, produces the JAG_MIMIC executable.

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

7.2 Component relationships

The makefile jagMimic.mk builds the JAG_MIMIC executable, using the jagMimic.bom.

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

7.3 jagMimic.mk

# TYPE:
# makefile
#
# PURPOSE:
# To build the mimic for the JAG system.
#
# FUNCTION:
# The main targets are:
#
# build This builds the final executable, JAG_MIMIC
#
# 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:
#
# DEPENDENCIES:
# dramastart should have been run to define the locations of the DRAMA
# elements - libraries and headers.
#
# The CIA library should have been built.

7.4 jagMimic.bom

Bill of materials to build the mimic program for the JAG 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 jagChange.tcl 2.2 SCCS ${ING}/src
Component jagMimic.tcl 2.2 SCCS ${ING}/src
Component jagMimic.mk 1.2 SCCS ${ING}/src
Component jag.icon 1.1 SCCS ${ING}/src

Tag jag_mimic 1.2 Tcl TAG.tcl
Makefile ics_mimic.mk all

7.5 jagMimic.tcl

PUERPOSE:
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 entire mimic is redrawn. This ensures the light path is correct.

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 running concurrently. The -b option specifies the buffer size.

SUBORDINATES:
The IDS and AGB servers should be running.

References:
See [4]

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 JAGTO_REQSTATUS microseconds. This is set in jagInternal.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 jag server.

Commands

ASCF @A00000a a = required position

ASND @B00000a a = required position

Comparison mirror @C00000a a = required position, 2 for in, 1 for out

TV Shutter @D00000a a = required position, 2 for in, 1 for out

AFARC @U00000a a = required position

BFARC @E00000a a = required position

Flip mirror @F00000a a = required position 2 for in, 1 for out

Auto filter @G00000a a = required position

TV filter @H00000a a = required position

Comp lamps @I00000a a = required position (Bit mapped)

TV X probe @K0a a = required position

TV Y probe @M0a a = required position

Autoguider X probe @O0a a = required position

Autoguider Y probe @Q0a a = required position

Status

This is returned in one long string with each mechanism allocated a position in this string. The string is of the form:

@aabbccddeeffgghhiijjkkkkllmmnnnnooppqqqqrrssttttuuvvww

Where:

aa corresponds to ASCF position

bb corresponds to ASND position

cc corresponds to comparison mirror position

dd corresponds to TV shutter position

ee corresponds to BFARC position

ff corresponds to flip mirror position

gg corresponds to guide filter position

hh corresponds to TV filter position

ii corresponds to comparison lamps

jj is unused (graticule illumination)

kkkk corresponds to TV X probe position

ll is unused

mm is unused

nnnnn corresponds to TV Y probe position

oo is unused

pp is unused

qqqq corresponds to Autoguider X probe position

rr is unused

ss is unused

tttt corresponds to Autoguider Y probe position

uu is unused

vv is unused

ww corresponds to AFARC position

Appendix B. Document History

Draft 2 Oct 1997 Draft release