INS-CCD-x
1.1, 9th December 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
The coding and functions of the science CCD (SCCD) server, as implemented in 1996 for the INT DAS, 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] outlines how to build install and configure the SCCD server as part of the observing system.
1.2 Scope and Overview
The SCCD server is responsible for controlling the CCD controller, and maintaining status information for displaying on the Mimic and storing 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 Utility Network facility, which the server uses to communicate with the CCD controller. The subtleties of the SCCD server itself are outlined in section 4. Section 5 described the operation of the clients and the mimic. Section 6 describes the source code components of the Utility Network facility, section 7 those for the server itself, and section 8 those for the clients and mimic.
1.3 References
[1] Interfaces to the SCCD server ING/RGO document INS-CCD-5, by Daniel Matthews
[2] Transfer of DAS and ICS ING/RGO document
[3] Interfaces to the IDS server ING/RGO document INS-IDS-1, by Daniel Matthews
[4] srv Facility ING/RGO document , by Guy Rixon
[5]
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. Modifications 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: sccdPkgRunUpdate()
Names of data types have the suffixes "_t" unless they are structure type in which case they have the suffix "_T", eg SCCD_cmdtype_t and SCCD_format_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 sccdServerMain.c
Names of Drama actions and parameters are all in uppercase.
2.4 Development tools
The compiler and debugger from SPARCworks Professional C was used for development. The lint provided with this package was also used. Version control used sccs, part of the Solaris distribution. 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 outlined in the reference [2].
3.1 Communications
The nominated serial port, is configured as noncanonical, since the protocol does not use CR or LF as message terminators. The port is initialised to 7 bit, 9600 baud, even parity.
3.2 Transmit
Every UNET_XTRANSMIT_TO microseconds (.5 seconds) an X-ON character is sent, as required by the protocol. This is instigated by calling unetXServer() from the portInit function when the serial port is first set up. It is maintained by setting the DITs timeout in the unetXServer() function, causing unetXServer to be rescheduled each .5 seconds.
The unetTxRetrasmit_() function goes through the transmit table until it finds an unsent message. If the message is due for transmission, that is it either has not been already sent, or it was sent over a second ago, the message is sent. If however the message has been re-sent too often already, the message is removed from the transmit table, and the RESENT Drama parameter incremented.
When the server requires a utility network message to be sent, it will call unetTransmit(). This causes the new message to be added to the transmit table. If the table was previously empty, it will also cause the unetTxRetransmit_() function to be called. This ensures that a new message will not get written immediately if there is already one pending.
If an acknowledgement for a utility network message arrives, the original message is removed from the transmit table, and unetTxRetransmit_() function is called. This ensures that if a queue has formed in the transmit table, the next message will get sent when the previous one has been acknowledged.
The XON/OFF server unetXServer(), which is rescheduled every half second, also calls unetTxRetransmit_(). This ensures that if an acknowledgement is not received for a message, the message will get resent.
3.3 Receive
The INS facility ensures that when characters from the remote 4MS system arrive down the nominated serial port, the portRead() function will get called. This will get called multiple times for any one message, since the port is set non-canonical. The portRead() function provided by the UNET facility, assembles the characters into full utility network messages. When a complete message has arrived, it is forwarded to unetReceive_(), and the message assembly process restarted.
When the complete message is forwarded to unetReceive_(), it is logged to the log file. This ensures that all received messages appear in the log. The message is then checked for validity, and the various parts extracted. If it was an acknowledgement, the transmit side is notified so that the message can be removed from the transmit table. Otherwise, it is acknowledged (there is no need to acknowledge receipt of and acknowledge message). If the message is not a duplicate it is added to the receive table (used to check for duplicate messages) and forwarded to the host server for processing (via the unetProcessMsg() function call).
4.1 Communications
The SCCD server communicates with the CCD controller using the Utility Network Protocol. The particular messages used are interpreted in the sccdUnet.c module, and forwarded to the appropriate function. Before any messages can be sent to the CCD controller, it's network name must be known. This is only known once the SCCD_INIT action has been invoked.
The sccdUnet.c module is the interface between the utility network protocol and the SCCD application. In this module all received messages are interpreted as from a CCD controller, and forwarded to the appropriate "update" function. Any not recognised as CCD controller messages are rejected. Any that are not recognised as coming from the expected CCD controller are also rejected, as are any not destined for this server. However the TIM and UTC messages are forwarded to the time service software (sccdServiceTime) irrespective of the source and destination.
4.2 Initialisation
The details of the detector in use are defined in a profile file. The SCCD_INIT action causes this file to be loaded, and all the static parameters to be initialised accordingly. These include the full frame readout size, the gain and readout noise, the head code, and the network name.
Other parameters, such as readout speed, readout format (windowed/binned etc) are initialised either to their default state, or that requested in the profile file.
4.3 Time synchronisation
The CCD controller can either instigate the synchronisation of it's real time clock automatically, every 24 hours, or this can be started by sending a network message to the controller requesting it to carry out the synchronisation. In either case, the controller attempts to set up a dialogue with the time distribution system (TDS). This is a 4MS system that sits on the utility network in the WHT. It has a network name TIM. Since there is no longer a utility network as such, the system computer must take the place of the TDS. This means that any TIM out RTC messages are routed to the time synchronisation module (sccdServiceTime).
The dialogue required to synchronise the CCD controller is outlined in reference [], and is implemented by the sccdTime.c module.
4.4 Resetting CCD controller
The RES network message causes the CCD controller to reset. This can take several seconds to complete, and there is no positive feedback from the CCD that the reset has complete. It will also cause all the settings to revert to the saved settings, which may not be known by the SCCD server. For this reason, when the RES message has been sent to the CCD controller, the initialised flag is cleared to force the user to do another "setup_ccd". This sets all the settings to known values and stops the CCD controller and the server getting out of sync. Also the SCCD_DORESET action will complete before the CCD controller has finished. However a setup will not succeed until the reset has been completed.
4.5 Format
The full frame image size is read from the CCD profile file when the SCCD_DOINIT action is invoked. This is used to initialise the FORMAT structure. This is an SDS version of the C structure type SCCD_format_T. It contains the full frame image size, and all defined windows, and the binning parameters. This is kept in step with the windows defined on the CCD controller through the sccdUpdateSettings() function. This is copied by the SETTINGS client to the DASn which uses the structure to calculate the number of pixels to expect when a run is carried out.
The action SCCD_SETFORMAT is invoked with the required FORMAT SDS structure passed as a parameter. This parameter is read into a local variable. Any undefined or invalid parts of the structure are ignored, and any that are set or copied into the required_format global variable. Thus if only the binning factors are to be changed, all the WIN[n].VALID and WINDOWS_ENABLED elements on the structure should be set to NOT_DEFINED.
Once the required_format has been set, the sccdTrackSettings() function is called. This compares the current readout format with that requested, and sends the appropriate utility network messages to cause them to converge.
When messages arrive from the CCD controller that cause the current settings to be updated, the action SCCD_SETFORMAT action is signalled. If the settings are still not those requested (tested with sccdSettingsDrift_() function), the action will be rescheduled until it times out.
4.6 Settings
The other settings set is the same manner as the format described above are: clear speed; readout speed; preflash time and exposure time.
4.7 Run
The run is implemented in the SCCD server using the PIC network message to the CCD controller. This invokes a "packaged run", which carries out the clear, preflash if necessary, exposure and readout autonomously. The position in this sequence is returned to the system computer as status messaged, but no more messages from the SCCD server are required. When the status message arrives, the RUNSTAT parameter is updated. This is an SDS item of the same SCCD_runstat_T C type. It can be monitored by clients to determine the status of the run.
5.1 Setup
The SETUP client, implements the SCCD_INIT action on the SCCD server. This loads the configuration file for the nominated CCD, and initialises both the CCD controller and the SCCD server accordingly.
Once this action is complete, this client extracts the now initialised DASCHANNEL, HEADCODE and FORMAT from the SCCD server. A RESET action is invoked on the DASM server, with the DAS channel as an argument - this causes the DASn server to be started. The DASn server is then configured with the FORMAT and HEADCODE from the SCCD server, and the PACKETS action configured with the header packet names to expect. This will change with the configuration of the instrument control as a whole. The OBSDATA directory is also set up (to that defined in the OBSDATA_DIR environment variable) on the DASn server, to configure the destination directory for the science data.
5.2 Settings
The SETTINGS client implements the WINDOW, BIN, READOUT_SPEED, CLEAR_SPEED, DISABLE_WIN, ENABLE_WIN and EXPTIME user commands. The multiple command names are merely softlinks to the executeable SETTINGS. By examining argv[0] the command name used can be seen.
The current format is initially retrieved from the SCCD server. If one of the commands requesting a change to the readout format is invoked (WINDOW, BIN, DISABLE_WIN or ENABLE_WIN), the format structure will be modified accordingly. If the modified format is deemed a invalid format, the command will fail with an error indicating this. If however the modified format is valid, it is sent on to the SCCD server, by invoking the SCCD_SETFORMAT action, and the DASn server, by invoking the FORMAT action. The DAS_CHANNEL parameter must be read from the SCCD server to determine which DASn is to be notified.
However with the READOUT_SPEED, CLEAR_SPEED and EXPTIME commands, the corresponding action (SCCD_DORSPEED, SCCD_SETCSPEED and SCCD_SETEXPTIME) is invoked only on the SCCD server.
5.3 Run
The RUN client implements the ARC, BIAS, DARK, FLASH, FLAT, RUN, SKY, GLANCE and SCRATCH user commands. The multiple command names are merely softlinks to the executeable RUN. By examining argv[0] the command name used can be seen. The command name is used as the observation type. If a comment is given as a trailing argument, this is used as the OBJECT name in the fits header - otherwise the command name is used.
A monitor is initiated on the RUNSTAT parameter of the SCCD server. This provides the state of the run, to allow the collection of the headers to start at the appropriate time.
The exposure time is either assumed (to be zero in the case of a bias) or extracted from the second argument. The SCCD server SCCD_SETEXPTIME action is invoked to set the exposure time to that requested.
The RUN action is invoked on the DASn server. This prepares the DAS server for the receipt of the pixels. It also causes the run number to be generated. this is then retrieved from the DASn server and printed on the command line to the user.
The SCCD_DORUN action is finally invoked, and executed in parallel with the RUN action on the DASn server and the monitor on the SCCD server. The SCCD_DORUN action sends the PIC message to the CCD controller to start a packaged run.
During the run, as the RUNSTAT parameter on the SCCD server changes, the monitor will return to the run client. Each time it returns, the runStartHeaders_() action is called. Once the shutter shutter is shown as having opened, the ARCHIVE action is invoked on the DASn server, and executed in parallel with the rest of the pending actions. When the shutter closes the ARCHIVE action on the DASn server is kicked, to cause it to finish. This ensures that all the header packets to be generated at the start and end of the run are collected at the correct times.
When all the pixels have arrived (the RUN action completes on the DASn server), and the CCD controller indicates it has completed the SCCD_DORUN action, the monitor is cancelled, and the client terminates.
If the status of the run returned in the RUNSTAT parameter ever indicates the run is aborting, the abortRun_() function is called, which causes a dummy observation packet to be written, allowing the ARCHIVE action to terminate.
5.4 Run modifications
If the user wished to alter the sequence of an already initiated run, the RUN action on the SCCD server can be kicked. The RUNKICK client does this. The user commands ABORT, PAUSE, CONTINUE and FINISH are softlinks to this client.
With the PAUSE, CONTINUE and FINISH commands, the appropriate arguments to a kick to the SCCD RUN action are assembled and the kick invoked.
However with the ABORT command, a kick is also sent to the RUIN action on the DASn server.
5.5 Shutter
The client to move the shutter simply interprets the movement request in the command line argument and invokes an SCCD_DOSHUTTER action in the SCCD server.
5.6 RTC synchronisation
The RTC synchronisation client initiated the synchronisation protocol as outlined in reference [], by sending the SCCD_DOSYNC to the SCCD controller. This can take up to 70 seconds to complete.
5.7 Reset
The RESET client, invokes the SCCD_DORESET action in the SCCD server - which sends the RESET utility network message to the CCD controller. The action, and hence the client will terminate once this message has been sent, and not necessarily when the CCD controller has finished the reset - which can take several seconds. The reset client pops up a confirmation window before the action is invoked in the SCCD server, to ensure the user does wish to reset the CCD controller.
5.8 Promote
If a scratch run number is provided as a command line option, the command invokes the PROMOTE action on the DASn server, which causes the numbered scratch file to be promoted to a run. If no number is given, the KEEP action is invoked on the DASn server, to promote a glance file to a run file.
5.9 Mimic
A simple mimic has been provided This is based on a curses screen that just displays the various parameters of note in the SCCD server, by setting up monitors on these parameters. Multiple copies of the monitor programme can by invoked as the name used when registering with DITs is dependent on the process number.
The utility network facility consists of the following components:
unetServerMain.c Contains the initialisation of the UNET facility - including the portInit function required by the INS facility.
unet.h Provides access to types and definitions required to interface to the UNET facility
unetInternal.h Provides access to types and definitions required internally to the UNET facility
unetTransmit.c Provides facility for sending utility network messages to the remote 4MS system
unetRecieve.c Provides facility for receiving utility network messages from the remote 4MS system
6.2 Component relationships
The modules unetTransmit.c and unetReceive.c provide the two directions for the implementation of the utility network protocol. While the module unetServerMain.c installs the parameters required for the facility, and initialises the serial port.
The UNET facility must be compiled with a host server, which will provide the missing functions. See section 7.
6.3 unetServerMain.c
TYPE:
C source-code file: one public functions, one private.
PURPOSE:
To provide facilities for initialising the Utility Network facility in
a host server.
FUNCTION:
portInit should be called by the host server to initialise the utility
network facility. The serial port is opened, and configured. The
unet parameters are added to the parameter system of the host server.
The transmit side is initialised. The XON/OFF server is kicked off
unetStartParamSys_ adds all the parameters used in the utility network
facility to the parameter system of the host server. These parameters
are used to report faults. All are initialised to zero
SUBORDINATES:
Included:
Called: unetTxInit unetXServer
DEPENDENCIES:
The host parameter system must have been started before portInit is
called.
INTERFACES:
Call from C:
void portInit(char *portName_, int *portPtr, StatusType *status )
Private calls from C:
static void unetStartParamSys_( StatusType *status )
RESOURCES:
3 DITS parameters are created (all SDS_USHORT):
SHORTMSG - is incremented when an invalid UNET message arrives (too short)
LONGMSG - is incremented when an invalid UNET message arrives (too long)
RESEND - is incremented when the retry limit is reached for a message
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
"ER412 Utilitynet protocol"
RGO document
"Utility Network Facility"
RGO/ING document INS-UNET-1
6.4 unet.h
TYPE:
C source code: include file
PURPOSE:
Define functions, types and constants for the UNET facility. This should
be included when interface to the UNET server or any of it's
internal types. Prmarily a definition of the UNET_mechmsg_T
FUNCTION:
Strcuture type definitions:
UNET_mechmsg_T - A utility network message
Enumerated type definitions:
UNET_mechmsg_type_t - type of Unet message - command/status request etc
Definitions and Macros:
UNET_NAME_LEN - Length of a utilitynetwork name (10)
MAX_UNET_STRING_LEN - Max length of a valid string
UNET_MECHSTR_LEN - Length of mechstr element of UNET msg
SUBORDINATES:
None.
REFERENCES:
"Interfaces to the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
6.5 unetInternal.h
TYPE:
C source code: include file
PURPOSE:
Define types and constants for use by the UNET service, that are
not required externally to the host server.
FUNCTION:
Structure types defined:
UNET_tx_tbl_T - entry in the transmit table
Definitions, constants and macros:
UNET_TX_TBL_SIZE - size of the TX table
UNET_RX_TBL_SIZE - size of the RX table
UNET_XTRANSMIT_TO - time period of XON/XOFF transmits (0.5sec)
MIN_UNET_STRING_LEN - min length of valid message string
Character definitions from Utility network
UNET_CMD_CHAR
UNET_STAT_CHAR
UNET_DATA_CHAR
UNET_ACK_CHAR
UNET_NACK_CHAR
UNET_BROADCAST_CHAR
X_ON
X_OFF
EOT
SYN
SUBORDINATES:
srv.h Must have been included before this to make bool_t available
REFERENCES:
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
"ER412 Utilitynet protocol"
RGO document
6.6 unetTransmit.c
TYPE:
C source-code file: five public functions, four private.
PURPOSE:
To transmit utility network messages down a serial port.
FUNCTION:
This modules provides facilities for transmitting utility network messages down
a serial port. The port must be initialised and the tansmit table cleared out
before any messages are sent. Also the XON/XOFF server should have started.
This is a function that sends an XON every 0.5 seconds. It also checks for
messages to be resent. The function portInit in unetServerMain.c carries
out the initialisation required.
The server can then supply a utility network message, of type UNET_mechmsg_T
(as defined in ids.h) to the function unetTransmit. This message will then get
added to the transmit table. The poll of the transmit table will then cause
the new message to get sent. To stop the target machine getting overloaded
by new messages, only one message is sent at a time, anyothers are left in
the TX table pending. When an ACK arrives for the first one, the next
will be sent. This ensures that all messages get sent eventually, but
the receive table in the target doesn't get overfull.
The unetXserver() function gets rescheduled every half second. When it runs,
it transmits the XON character and polls the transmit table. The next
message that has not been acknowledged, but was first sent more than a
second ago will get (re)sent. A count of the number of resends of
each message is kept in the transmit table. If this gets above
acceptible levels, the message is removed from the table and no more
resends are attempted. The RESEND parameter will also get incremented.
When the receive side receives a message, it acknowledges it to the instrument
by calling unetTxAck which sends the ack message.
When the receive side receives an ACK for a message, it will call
unetTxAckReceived. This removes the message from the TX table. The
unetTxReTransmit function is called to enable the nexted queued message
to be sent.
When sending the message, a type of UNET_CMDREQ_M will cause the command to be
sent along with the request for immeadiate and delayed status ie command types
101 200 and 201. The first number in the mesg part is assumed to be the head
number and is used as the argument to the 200 and 201 messages. eg for a
readout speed change of a CCD controller, the messages sent may be:
RSP101(1,3) RSP200(1) RSP201(1)
A type of UNET_CMDREQ_NOHDNO_M is similar, except no parameter is provided
with the 200 and 201 messages, for example:
RGA101(102000) RGA200 RGA201
SUBORDINATES:
Included: srv.h unet.h unetInternal.h
Called: msgLog( )
INTERFACES:
Call from host server:
void unetTransmit(UNET_mechmsg_T *umsg,StatusType *status )
- add msg to table and TX
Call from somewhere else in Utility Net Facility:
void unetTxInit( StatusType *status ) - clears the TX table
void unetTxAck(int msg_no,char *dest,char *src) - send ACK
void unetTxAckReceived(int msg_no) - remove msg from TX table
void unetXServer (StatusType *status ) - handle send of XON/XOFF
AND transmit pending messages
Private:
static void unetTxRetransmit_( StatusType * status ) poll tx table & TX any
static boolean_t unetTxTableEmpty( void ) - returns TRUE if table is empty
static void unetTxTblMsg_( UNET_tx_tbl_T *msg ) - transmit a TX table entry
static void unetTxTableAdd_(UNET_mechmsg_T *msg) - add msg to tx table
static void unetTxMsgStr_( char * msg ) - sends string to port
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
"ER412 Utilitynet protocol"
RGO document
"Utility Network Facility"
RGO/ING document INS-UNET-1
DATA:
The transmit table (UNET_tx_tbl_T) txTable[UNET_TX_TBL_SIZE]) is used to
store the message to be sent, so that they can be resent if no
acknowledgement is received with a certain time.
unetMsgNo_ is the number of the next utility network message. this gets
initialised to a pseudo random number ((100 * (uint)pid) % 0xFFFF) in
unetTxInit. The instrument attatched would ignore messages that arrive
with a message number that has previously been used, so this number should
be changed significantly each time the host server starts up.
6.7 unetReceive.c
TYPE:
C source-code file: one public functions, four private.
PURPOSE:
To receive characters from the serial port, combine them up to a utility
network message, which is then forwarded to the host server.
FUNCTION:
The host server should register portRead as the alternative input
call-back function and then call the alternative input main loop.
When a character, or string of characters arrives at the serial port,
the DITs main loop will call portRead. Any characters in the buffer
of the port are read and processed in turn. If a (SYN) character arrives
indicating the start of a utility network message, subsequent characters
are combined into a message until the next character (EOT) arrives to
indicate the end of a message. The message is then passed onto
unetReceive_ where it is parsed. All characters between the last EOT
and next SYN are ignored. If a message arrives that is shorter than
MIN_UNET_STRING_LEN characters long, the message is ignored and the
SHORTMSG parameter incremented. If a message longer than MAX_UNET_STRING_LEN
arrives, it is ignored and the parameter LONGMSG is incremented.
Once the message is forwarded to unetReceive_ it's various sections are
separated and validated (source, destination, number,
type and the messages themselves). Received ACK messages are forwarded to
unetTxAck, NACKS and broadcast messages are ignored, but the command and
status messages are acknowledged and forwarded, one at a time, to the
application side, if the message has not already been seen. That is each
mechanism message is sent on separately - via a call to the function
unetProcessMsg that is in the host server.
The receive table is used to verify that the a message has not already been
received, and is maintained by the two private functions unetRxMsgDuplicate_
and unetRxMsgLog_.
SUBORDINATES:
Included: srv.h unet.h unetInternal.h
Called: unetTxAckReceived() unetTxAck() msgLog() unetProcessMsg()
DEPENDENCIES:
The parameter system must have been started up before portRead is
called,
INTERFACES:
Call from C:
void portRead( int *portPtr, StatusType *status)
Private calls from C:
static void unetRxXchar_( char c )
static bool_t unetRxMsgDuplicate_(int message_no)
static void unetRxMsgLog_(int message_no)
static void unetReceive_(char *msg, StatusType *status )
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
"ER412 Utilitynet protocol"
RGO document
"Utility Network Facility"
RGO/ING document INS-UNET-1
DATA:
The following item are delared statically to provide the receive table:
static int rxTable_[UNET_RX_TBL_SIZE]
static int rxTablePtr_
As well as the INS components listed in reference []. the AGB server has the following components
sccdServerMain.c Provides the action map and parameter database
sccd.h Provides interfaces to the SCCD server that might be required by external clients
sccdInternal.h Provides definitions and macros that are required by the SCCD server
sccdClear.c Implements the SCCD_DOCLEAR action, causing the CCD controller to carry out a clear of the detector.
sccdInit.c Impelements the SCCD_INIT action, initialising both the server and the CCD controller
sccdPkgRun.c Implements the SCCD_DORUN action, which causes a packaged run to be taken.
sccdReadout.c Implements the SCCD_DOREADOUT action, which promptsthe CCD controller to read the CCD out.
sccdReset.c Implements the SCCD_DORESET action, which resets the CCD controller.
sccdSds.c Implements the sccdFormatSds() and sccdRstatSds() functions to generate the Sds structures corresponding to the SCCD_format_T and SCCD_runstat_T 'C' structures.
sccdSettings.c Implements the SCCD_SETFORMAT, SCCD_SETRSPEED, SCCD_SETCSPEED, SCCD_SETPFLASH and SCCD_SETEXPTIME actions
sccdShutter.c Implements the SCCD_DOSHUTTER action to move the shutter.
sccdTime.c Which implements the SCCD_DOSYNC action, which synchronised the CCD controller with the time on the system computer.
sccdUnet.c Provides the interface to the Utility network facility above, and interprets arrived messages.
sccd.mk Make file to produce the sccd executable
sccd.bom Bom file used to create a formal server release.
7.2 Component relationships
The makefile sccd.mk makes the SCCD server by compiling all the above C files, as well as those in the INS facility, the srv facility and the utility network facility, and linking into the "sccd" executable.
A release is defined by the version numbers of all the components listed in sccd.bom. A release can be made by giving this list to the "bom" utility, as described in reference [2].
7.3 sccdServerMain.c
TYPE:
C source-code file: two public functions.
PURPOSE:
To provide facilities for starting up the server, installing the DRAMA
actions and starting the parameter system.
FUNCTION:
This component installs the actions and the parameter system of the
SCCD server.
startActions installs all the actions. Elsewhere the EXIT, PING and
ARCHIVE actions should be unstalled.
startParamSys starts the parameter system and adds all the parameters
needed. It is worth remembering that although the parameters have been
added, they will not be initialised until SCCD_INIT action has completed.
This is indicated with the value of the INIT parameter.
SUBORDINATES:
Included: unet.h sccd.h sccdInternal.h
Called: sccdFormatSds() sccdRstatSds()
DEPENDENCIES:
None
INTERFACES:
Call from C:
void startParamSys( StatusType *status )
void startActions( StatusType *status )
RESOURCES:
The 'required settings' parameters are declared as globals so that they
are available to the various modules that require them - principly sccdInit
and sccdSettings.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
7.4 sccd.h
TYPE:
C source code: include file
PURPOSE:
Define functions, types and constants for the SCCD server
FUNCTION:
This should be included when interface to the SCCD server or any of it's
internal types. Prmarily a definition of the SCCD_format_T and
SCCD_runstat_T structure types
SUBORDINATES:
None.
REFERENCES:
"Interfaces to the science CCD server"
RGO/ING document INS-CCD-5
7.5 sccdInternal.h
TYPE:
C source code: include file
PURPOSE:
Define functions, types and constants for modules internal to the SCCD
server.
FUNCTION:
This should be used when modules of the sccd server require. definitions
are provided for:
SCCD_mechcode_t
All failure timeout periods
All bit mapped error messages from the utilitynet
SUBORDINATES:
None.
REFERENCES:
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
"Interfaces to the science CCD server"
RGO/ING document INS-CCD-5
"ER412 Utilitynet protocol"
RGO document
7.6 sccdClear.c
TYPE:
C source-code file: two public functions
PURPOSE:
To start and monitor a clear of the detector.
FUNCTION:
This component implements the SCCD_DOCLEAR action descibed in INS-CCD-5.
sccdClear() starts off the clear action by checking that the server has
been initalised since the last controller reset, by checking the INIT
paramter, if this is false, the action fails with an error indicating this.
Otherwise, the action continues by sending the CLR mechanism
message to the UNET server, and reschedules. If nothing happens by
SCCD_STARTACTION_FAIL seconds, the action will terminate with a timeout.
If the action is kicked at all, it is taken as a user abort and terminates.
Alternatively, if it gets signalled (by sccdClearUpdate below), with the
mechanism error code as an argument, it will reschedule if the mechanism is
busy. If the mechanism error code implies the action has complete
successfull the action will terminate without an error, otherwise the it
terminates with a status error
sccdClearUpdate() updates the parameter system in the light of a
received CLR mechanism status message. It will also signal the
SCCD_DOCLAEAR action (above) if it was in progress.
SUBORDINATES:
Included: sccd.h sccdInternal.h sccdErr.h insErr.h
Called: msgLog() sccdUnetSendCmd()
DEPENDENCIES:
The parameter system must have been started up before sccdClearUpdate and
sccdClear are called.
INTERFACES:
Call from C:
(void) = sccdUpdateClear( ulong MechError, StatusType *status )
The action is invoked with SCCD_DOCLEAR, without an argument. Sending
a kick to the action will abort it.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
7.7 sccdInit.c
TYPE:
C source-code file: two public functions, one private
PURPOSE:
To initialise both the server and the CCD controller.
FUNCTION:
This component implements the SCCD_DOINIT action described in INS-CCD-5
sccdInit is called when the SCCD_DOINIT action is requested. It takes one
argument, the name of the CCD (for example EEV9). This function will load
the profile file with the filename of the CCD with a suffix of '.dat',
(EEV9.dat) for example. This contains the initial setup required for the
chip, and some of the info needed for the FITs header. It sets all the
parameters in the parameter system, and causes network messages to be sent
to the controller to ensure it is setup to this default configuration.
Monitor mode is also setup on the CCD controller to ensure this server is
notified all changes in the controller state. This action rechedules, and
waits for the controller to confirm all its parameters are set to those
requested. The action will timeout if nothing occurs in a set time, but
will end normally otherwise. If the profile file is valid, the INIT flag is
set to FALSE indicating thatthe server/controller is in an uninitialised
state.
sccdUpdateInit is called when a utility network message implying the
controller has been reset (INS message). This causes the INIT parameter
to be set to 0. It is also called when a monitor mode status message (MON
message) arrives, and notifies the action routine of its arrive. The
following actions are also kicked, which, if they are in operation, will be
terminated:
SCCD_DOCLEAR, SCCD_DOREADOUT, SCCD_DORUN, SCCD_DOSHUTTER,
SCCD_DOSYNC,
SCCD_SETEXPTIME.
A Kick with no parameters is generally used by action to indicate an abort
request.
sccdGetParams_ is the internal function that reads the profile file for
the detector requested. The following parameters MUST be declared in
this profile file:
SCCD_SIZE Full frame size of image including under/overscans
UNET_REMOTE
GAIN
NOISE
DAS_CHANNEL
HEADNO
HEADCODE
PIXXSIZE
PIXYSIZE
XUNDER
YUNDER
XSILSIZE
YSILSIZE
CCDTYPE
CCDNAME
This is because they are either needed by this or other servers, or
must appear in the headers, and so must be initialised to something
sensible. The follwoing parameters MAY be set, but otherwise
initialise to the state shown:
Initialise to:
TRANSFORM string defining the transforms required to make the
chip orientation consistent (depends on readout corner)
BSCALE (scaling factor of data) 1.0
BZERO (zero point of data) 32767
BITPIX (number of bits used for each pixel) 16
WIN (windows) no windows valid, windows disabled
BIN (binning) no binning, ie binning by 1x1
PFLASH (preflash time) no preflash, ie set to 0.0
RSPEED (readout speed) STANDARD
CSPEED (clear speed) QUICK
DETCOUNT (number of detectors) initailsed to 1
SUBORDINATES:
Included: unet.h sccd.h sccdInternal.h sccdErr.h insErr.h
Called: msgLog() sccdUnetSendCmd()
DEPENDENCIES:
The parameter system must be started before SCCD_DOINIT action is called
INTERFACES:
Call from C:
(void) = sccdUpdateInit( UNET_mechmsg_T *umsg, StatusType *status )
(void) = sccdGetParams_( char *ccd_name, StatusType *status)
The action (sccdInit) is invoked with SCCD_DOINIT, with one string argument,
which is the name of the CCD as defined in INS-CCD-5
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
7.8 sccdPkgRun.c
TYPE:
C source-code file: three public functions
PURPOSE:
To carry out a packaged run, that is one with clear, preflash, expose
and readout.
FUNCTION:
This component implements the SCCD_DORUN action descibed in INS-CCD-5.
The exposure time should already have been set up with an SCCD_SETEXPTIME
action.
sccdPkgRun() starts off the action by confirming that the server has been
initialised - terminating with an error if it hasn't. Otherwise it will
contine by sending the the PIC/DAR message,
and the controller then carries out the packaged run autonomously, sending
occasional update messages. The action will terminate if a received status
message implies a serious error or the packaged run completes. If the
action is kicked sccdKickPkgRun is called. When a run is first requested,
the start time is logged, and when subsequent messages arrive from the
controller (into sccdUpdatePkgRun) the ELAPSED_TIME element of the
run_status parameter is updated. It is worth noting that while reading out
the controller does not send any messages, so the elapsed time will not be
updated until the end of the run - ie when the PIC/DAR complete message
arrives.
sccdKickPkgRun() is called when the SCCD_DORUN action is sent a kick message.
This is used to request the following changes to a packaged run: ABORT,
PAUSE/CONTINUE and FINISH. If the run is in the correct state,
the appropriate message is sent to the controller. The kick will terminate
immeadiately, with the action handler (sccdPkgRun) handling the status
messages arising from the kick. If no argument is provided with the kick,
it is interpreted as a terminate request, and the action will complete.
sccdUpdatePkgRun() updates the SCCD_runstat_T structure type parameter
(RUNSTAT) in the parameter system, in response to received status messages
from the controller, regarding the mechanisms involved in a packaged run
and its various possible kicks. The elapsed time is calculated when the
shutter closes and the readout starts, as the time since the exposing
started, and includes the times for pauses and the like.
SUBORDINATES:
Included: unet.h sccd.h sccdInternal.h sccdErr.h insErr.h
Called: msgLog() sccdUnetSendCmd() unetUnetSds()
DEPENDENCIES:
If SCCD_INIT hasn't been called before SCCD_DORUN is attempted,
the action will return an error indicating this.
INTERFACES:
Call from C:
(void) = sccdUpdatePkgRun( UNET_mechmsg_T *umsg, StatusType *status )
The action (sccdPkgRun) is invoked with with SCCD_DORUN, and has 1 argument.
"Argument1" is the type of packaged run (SCCD_pkgrun_t) SCCD_RUN_PIC or
SCCD_RUN_DAR.
The action SCCD_DORUN can be kicked, with one optional argument. If the
argument is present, its value comes from SCCD_pkgrun_kick_t.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
DATA:
Two static boolean flags, sccdRunSent_l and sccdRunDark_l, are local to
sccdPkgRun. Their values can be preserved and used un subsequent
reschedules of the action.
7.9 sccdReadout.c
TYPE:
C source-code file: two public functions
PURPOSE:
To start and monitor an unpackages readout of the detector.
FUNCTION:
This component implements the SCCD_DOREADOUT action descibed in INS-CCD-5.
sccdReadout() starts off the readout action by sending the RED mechanism
message to the UNET server, and reschedules. If nothing happens by
SCCD_STARTACTION_FAIL seconds, the action will terminate with a timeout.
If the action is kicked at all, it is taken as a user abort and terminates.
Alternatively, if it gets signalled (by sccdReadoutUpdate below), with the
mechanism error code as an argument, it will reschedule if the mechanism is
busy. If the mechanism error code implies the action has complete
successfull the action will terminate without an error, otherwise the it
terminates with a status error
sccdReadoutUpdate() updates the parameter system structure RUNSTAT in the
light of a received RED mechanism status message. It will also signal the
SCCD_DOREADOUT action (above) if it was in progress.
SUBORDINATES:
Included: sccd.h sccdInternal.h sccdErr.h insErr.h
Called: msgLog() sccdUnetSendCmd()
DEPENDENCIES:
If SCCD_DOINIT hasn't been called before SCCD_DOREADOUT is attempted,
the action will fail with an error indicating this.
The parameter system must have been started up before sccdReadoutUpdate
is called.
INTERFACES:
Call from C:
(void) = sccdReadoutUpdate( ulong MechError, StatusType *status )
The action is invoked with SCCD_DOREADOUT, without an argument. Sending
a kick to the action will abort it.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
7.10 sccdReset.c
TYPE:
C source-code file: one public functions
PURPOSE:
To reset the ccd controller.
FUNCTION:
This component implements the SCCD_DORESET action descibed in INS-CCD-5.
sccdReset() send the RES message to the controller and terminates. There
are no reschedules, and the action cannot be kicked. When the controller
receives the RES message, it should reset, sending out an INS message,
which in turn will inform the server that a the controller is in an
unitialised state.
SUBORDINATES:
Included: No project specific headers.
Called: msgLog() sccdUnetSendCmd()
DEPENDENCIES:
The parameter system must have been started before the action is called.
If SCCD_DOINIT hasn't been called before SCCD_DORESET is attempted,
the action will fail with an error indicating this.
INTERFACES:
The action is invoked with SCCD_DORESET, without an argument. It doesn't
accept kicks, and terminates immeadiately.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
7.11 sccdSds.c
TYPE:
C source-code file: two public functions
PURPOSE:
To generate the SCCD_format_T and SCCD_runstat_T structures in SDS.
FUNCTION:
This component can be used in any application to provide functions for
generating the two complex structures in an SDS format for passing between
processes using DRAMA.
SUBORDINATES:
Included: sccd.h
DEPENDENCIES:
None.
INTERFACES:
Call from C:
(SdsIdType) = sccdFormatSds( StatusType *status );
(SdsIdType) = sccdRstatSds ( StatusType *status );
RESOURCES:
Allocates one SdsId per call. These should be removed when finished with.
REFERENCES:
"Interfaces of to the science CCD server"
RGO/ING document INS-CCD-5
7.12 sccdSettings.c
TYPE:
C source-code file: three public functions, one private.
PURPOSE:
To monitor and change the settings - that is readout speed, clear speed,
preflash time and the readout format.
FUNCTION:
This component implements the SCCD_SETRSPEED, SCCD_SETCSPEED,
SCCD_SETPFLASH
SCCD_SETEXPTIME and SCCD_SETFORMAT actions described in INS-CCD-5. It also
keeps the parameter system informaed of changes in the settings.
sccdSettings starts off the SCCD_SETx action. If the server has not been
"SETUP" since the last CCD controller reset, or since the server starting
up (ie INIT is FALSE), the action terminates with an error indicating this.
The setting to be modified
is then determined, and the required setting updated accordingly. With the
FORMAT structure, only BINning WINDOWS_ENABLED and the various WINdows can
be changed, and the values of these will be ignored if they are not valid.
For example, if changing the windowing, the two BINning factors should be set
to 0.
The conformance of the actual settings to those required is then checked
(using sccdSettingsDrift_). If they is no drift, then the required setting
is already set and the action returns with the "ALREADYTHERE" error.
Otherwise, commands required to get to the required settings, from the
current settings, are sent to the controller (by sccdTrackSettings). The
action will then reschedule after a delay period. If there has not been
notification of the actual parameter changing after a time period, the
action will fail with the timeout error. If however a setting is changed,
this action will be notified. If the settings are all now set to those
required, the action will terminate without error. If however, the
settings are still not OK, the action will reschedule and wait for further
updates or will timeout. The action does not accept Kicks.
When a network message arrives that implies the status of one of the
settings, sccdUpdateSettings is called and processes the utility net
message - updating the parameter system copy of the current values. It
then attempts to trigger the SCCD_SETx action (above) to inform it that a
parameter may have changed. If the message implied that an error occurred
while setting the parameter, then we must ensure that the erroneous
required_setting is removed (ie the current setting copied in). This will
ensure that there are not further attempts to set this setting when
unrealated settings are modified.
SUBORDINATES:
Included: sccd.h sccdInternal.h sccdErr.h unet.h ciaBoolean.h insErr.h
Called: msgLog() sccdUnetSendCmd()
DEPENDENCIES:
If SCCD_DOINIT hasn't been called before SCCD_SETx is attempted,
the action will timeout, as the server will not yet know the utilnet
address of the CCD controller, so cannot communicate.
INTERFACES:
Call from C:
( void ) = sccdTrackSettings( StatusType *status )
( void ) = sccdSettings ( StatusType *status )
( void ) = sccdUpdateSetting
(SCCD_mechcode_t mech, UNET_mechmsg_T *umsg , StatusType *status )
Internal C function:
( bool_t ) = sccdSettingsDrift_( StatusType *status )
The function sccdSettings() is invoked with SCCD_SETx DRAMA action
The global variables required_cspeed, required_rspeed, required_pflash,
required_exptime and required_format are all read and modified by this
module.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
7.13 sccdShutter.c
TYPE:
C source code
PURPOSE:
To allow the shutter to be controlled and for the position and status
to be available
FUNCTION:
This component implements the SCCD_DOSHUTTER action descibed in INS-CCD-5.
sccdShutter() carries out the requested move, with the only argument
(Arument1) being the requested move - open, close or unjam. This action
sends the appropriate utility network message and reschedules. If nothing
happens, it will time out SCCD_SHUTTER_FAIL seconds later. It cannot be
kicked. When a SSH status message arrives, the sccdShutterUpdate (below)
forwards the mechanism message in a signal message to this action. If an
error has occured, the action will terminating indicating this. Otherwise,
it will terminate without error.
sccdShutterUpdate() updates the parameter system variable SHUTTERPOS and
SHUTTEROK in the light of a received shutter (SSH) status message. It will
also signal the SCCD_DOSHUTTER action (sccdShutter() above), if it was in
progress, and forward the error status of the received status message .
SUBORDINATES:
Included: unet.h sccd.h sccdInternal.h sccdErr.h insErr.h
Called: msgLog() sccdUnetSendCmd()
DEPENDENCIES:
If SCCD_DOINIT hasn't been called before SCCD_DOSHUTTER is attempted,
the action will fail with an error indicating this.
The parameter system must have been started up before sccdShutterUpdate
is called.
INTERFACES:
Call from C:
(void) = sccdShutterUpdate( UNET_mechmsg_T *umsg, StatusType *status )
The action is invoked with SCCD_DOSHUTTER, with one argument ("Aurgument1"),
the shutter movement required. It cannot be kicked. It will respond to a
Signal with one arugument ("MechError") being the status of the received
utility mechanism status message.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
7.14 sccdTime.c
TYPE:
C source-code file: three public functions
PURPOSE:
To mimic the time service in synchronising the controller, and to allow
the user to instigate a synchronisation.
FUNCTION:
This component implements the SCCD_DOSYNC action descibed in INS-CCD-5.
It also mimics the operation of the time service, as descibed in WHT-TDS-3.
sccdSync() starts of the synchronise action, by sending a SYN mechanism
message to the ccd controller. If nothing has happened by SCCD_SYNC_FAIL
seconds, the action will terminate with a timeout error. If the action is
kicked, it is assumed this is a user abort, and the action is terminated,
although the automatic element of the synchronisation process will continue.
If the action is signalled (by sccdUpdateTime() below), with one argument
("MechError") it will either reschedule if the mechanism is busy, or
terminate with a status error is the mechanism showed an error.
sccdUpdateSync() updates the SYNC paramter in the parameter system in the
light of a reveived SYN status message. It will attempt to signal the
SCCD_DOSYNC action (above) if it is in progress.
sccdServiceTime() impliments the Time Distribution Service network protocol
as defined in WHT-TDS-3. Basically responds to TIM and UTC messages that
arrive from the controller. It has to use a different utilitynet source
address, as the CCD controller is expecting to be talking to the TDS. It is
purely responsive, maintianing no state information.
SUBORDINATES:
Included: unet.h sccd.h sccdInternal.h sccdErr.h insErr.h
Called: msgLog() sccdUnetSendCmd() unetTransmit()
DEPENDENCIES:
If SCCD_DOINIT hasn't been called before SCCD_DOSYNC is attempted,
the action will fail with an error indicating this.
The parameter system must have been started up before sccdClearUpdate
is called.
INTERFACES:
Call from C:
void sccdUpdateSync(UNET_mechmsg_T *umsg, StatusType *status)
void sccdServiceTime ( UNET_mechmsg_T *umsg, StatusType *status )
The action routine (sccdSync) is activated with SCCD_DOSYNC, without and
argument. Sending a kick to the action will abort it.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
"The 4.2M WHT Time Distribution Service Network Protocol"
RGO/ING document WHT-TDS-3
7.15 sccdUnet.c
TYPE:
C source-code file: five public functions, one private
PURPOSE:
To provide the server with an interface to the utility net server.
FUNCTION:
Two utility functions are defined here to allow th easy sending of
utilitynet messages. These are sccdUnetSendMsg() which sends the
utilitynet work message to the utility network facility, which in turn will
send it to the controller and a higher level function sccdUnetSendCmd()
which composes a utility network message from the mechanism name and
parameter string. It adds the standard source and destination addresses
and mechanism message type of UNET_CMDREQ_M. The message is forwarded to
the unet facility via sccdUnetSendMsg above.
SUBORDINATES:
Included: unet.h sccd.h sccdInternal.h sccdErr.h
Called :
msgLog() sccdServiceTime() sccdUpdateReadout() sccdUpdateShutt()
sccdUpdateSync() sccdUpdateClear() sccdUpdateInit() sccdUpdatePkgRun()
sccdUpdateSetting()
DEPENDENCIES:
The master task must be running to allow DitsLoad to work.
INTERFACES:
Call From C:
void sccdUnetSendCmd(char *cmdName, char *cmdParam, StatusType *status)
void unetProcessMsg(UNET_mechmsg_T *umsgPtr, StatusType *status)
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"CCD network messages Issue 8.3"
RGO/ING document WHT-CCD-1
7.16 sccd.mk
# TYPE:
# makefile
#
# PURPOSE:
# To build the sccd 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 of 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:
# sccdServerMain.c Define sccd server to INS facility
# sccdSettings.c For maintaining the setting of the CCD controller
# sccdUnet.c For connection to the Utility Network layer
# sccdInit.c For initialisation - loading defaults
# sccdShutter.c Controls the shutter
# sccdClear.c Clearing the detector
# sccdPkgRun.c Carrying out a packaged run (using PIC)
# sccdReadout.c Reading out the detector in non-packaged mode
# sccdTime.c For synchronising the RTC of the controller
# sccdReset.c For resetting the controller
# sccdSds.c For maintaining the SDS definitions of FORMAT and RUNSTAT
# insArchive.c INS facility - archive collection
# insMain.c INS facility - main() definition and logging
# srvPingExit.c SRV facility - defines PING and EXIT actions
# srvFindFile.c SRC facility - descend OBSSYS
# srvArchive.c SRV facility - defines ARCHIVE action
# srvTalk.c SRV facility - link to TALKER
# unetServerMain.c Utility network facility, initialisation
# unetReceive.c Utility network facility, recieving msgs from
remote instrument
# unetTransmit.c Utliity network facility, transmitting msgs to
remote inst
# mdbMatch.c MDB facility - match codes/name
# mdbMount.c MDB facility - mount wheel
# sccdErr.msgt Messages from SCCD
# insErr.msgt Messages from INS
# srvErr.msgt Messages from SRV
# sccdInternal.h Definitions internal to SCCD
# unetInternal.h Definitions internal to utility network facility
# ciaBoolean.h For TRUE/FALSE and boolean_t
# sccd.h Define SCCD wide structures
# srv.h SRV header
# mdb.h MDB header
#
# DEPENDENCIES:
# dramastart should have been run to define the locations of the DRAMA
# elements - libraries and headers.
7.17 sccd.bom
# Bill-of-materials for the release v1.12 of sccd
#
# 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 sccd.bom 1.12 /ing/src/SCCS/s.sccd.bom 96/11/19 14:58:08
Component ciaBoolean.h 1.1 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 mdb.h 1.1 sccs ${ING}/src
Component sccd.h 1.4 sccs ${ING}/src
Component sccdClear.c 1.4 sccs ${ING}/src
Component sccdInit.c 1.23 sccs ${ING}/src
Component sccdInternal.h 1.2 sccs ${ING}/src
Component sccdPkgRun.c 1.14 sccs ${ING}/src
Component sccdReadout.c 1.4 sccs ${ING}/src
Component sccdReset.c 1.3 sccs ${ING}/src
Component sccdSds.c 1.4 sccs ${ING}/src
Component sccdServerMain.c 1.12 sccs ${ING}/src
Component sccdSettings.c 1.12 sccs ${ING}/src
Component sccdShutter.c 1.5 sccs ${ING}/src
Component sccdTime.c 1.4 sccs ${ING}/src
Component sccdUnet.c 1.8 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 unet.h 1.5 sccs ${ING}/src
Component unetInternal.h 1.3 sccs ${ING}/src
Component unetReceive.c 1.7 sccs ${ING}/src
Component unetServerMain.c 1.9 sccs ${ING}/src
Component unetTransmit.c 1.7 sccs ${ING}/src
Component sccd.mk 1.20 sccs ${ING}/src
Component sccdErr.msg 1.7 sccs ${ING}/src
Component insErr.msg 1.3 sccs ${ING}/src
Component srvErr.msg 1.1 sccs ${ING}/src
Tag sccd 1.12 C
Makefile sccd.mk sccd
Assembly sccd 1.12
The following components are used to build the clients for the SCCD server:
clientGetServerName.c Linked in all the clients. This extracts the -C command line option for selecting the SCCD server name. Defaults this to SCCDa if none is given
clientPromote.c Invokes the PROMOTE actions in the DAS server
clientReset.c Invokes the SCCD_DORESET action in the SCCD server, which causes the CCD controller to reset
clientRunCCD.c Coordinates all the actions required on the DAS and SCCD servers to create a run
clientRunKickCCD.c Modifies the sequence of a normal packaged ron, either a pause/continue, an abort, a finish or a newtime
clientSetup.c For initialising the SCCD server and SCCD controller.
clientShutter.c For moving or unjamming the shutter
clientSyncRtc.c For synchronising the CCD controller time to that of the host Sparc
MULTRUN Script implementing the various multiple exposure clients
sccdClients.mk Makefile for the SCCD clients.
sccd_clients.bom Bill of materials for a release of the SCCD clients.
mon.c Creates a curses type display of the state of the SCCD server
mon.mk Makes the mon executable and installs.
mon.bom Bill of materials for the relase of the mon client.
8.2 Component relationships
The makefile sccdClients.mk makes all the action clients for the SCCD server (ie not the mon client). A release of the sccd clients is defined by the version numbers of the the components listed in sccd_clients.bom. A release can be generated by by giving this list to the "bom" utility, as described in reference [2]. The clients should always be installed into the obsering system by executing "make -f sccdClients.mk install" as several soft links are required to complete the implementation of the clients.
The makefile mon.mk makes the monitor clients for displaying the server status to the user. A release of the mon client is defined by a version of mon.bom.
8.3 clientGetServerName.c
TYPE:
C source-code: one public function.
PURPOSE:
Scans the input arguments for the SCCD server name.
FUNCTION:
Looks for the "-C" option, then scans it for a string of the format
"nnnn/xxxxx", where nnnn is ignored (as the CCD name), and xxxxx is the
name the SCCD server used when registering with Drama. If this isn't
given, it will default to SCCDa
SUBORDINATES:
None
DEPENDENCIES:
None
INTERFACES:
Call from C:
void=GetServer( int *nArgs, char *argv[],char *SName, StatusType *status )
where argv[] is the argument list from the calling program's command line
and *argc is the number of elements used in argv[], and SName is the
returned SCCD server name ( which will default to SCCDa if no -C option is
found)
8.4 clientPromote.c
TYPE:
C source-code file: producing executable task
PURPOSE:
Send the PROMOTE or KEEP action to the DAS server, after checking for locks.
If no run argument is given, it KEEPs the glance file, otherwise PROMOTEs
a scratch file.
FUNCTION:
Requests the RUN lock, if this was successful, it sends the
PROMOTE action request off to the DAS server.
SUBORDINATES:
called:
ciaRedirectErs ciaPingInit ciaExitInit ciaRpcInit ciaTalkInit
ciaLockInit ciaLockReq ciaObeyRpc ciaExecuteRpc
DEPENDENCIES:
The talker program should be running.
INTERFACES:
Call from command line:
name [-C NN/PORTX] [runNumber]
Has two optional arguments. "runNumber" is the number of the scratch
run to be promoted. Where no "runNumber" is given it is assumed that
the use is asking for the promotion of the glance file, ie a KEEP.
The other optional argument "-C NNN\PORTX " where NNN is unused,
is the port name that the SCCD server serves.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"Remote Procedure Calls for Drama clients"
RGO/ING document OBS-RPC-1
8.5 clientReset.c
TYPE:
C source-code file: producing executable task
PURPOSE:
Send the SCCD_DORESET action to the SCCD server, after checking for locks.
Also resets the DAS server.
FUNCTION:
Requests RESET lock. If this was successful, the SCCD_DORESET action
request is sent off to the requested server.
SUBORDINATES:
called:
ciaRedirectErs ciaPingInit ciaExitInit ciaRpcInit ciaTalkInit
ciaLockInit ciaLockReq ciaObeyRpc ciaExecuteRpc
GetServerName
DEPENDENCIES:
The talker program should be running.
INTERFACES:
Call from C:
Accepts one optional argument "-C NNN\PORTX " where NNN is unused, and
is the port name that the SCCD server serves.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"Remote Procedure Calls for Drama clients"
RGO/ING document OBS-RPC-1
8.6 clientRunCCD.c
TYPE:
C source-code file: with main, produces executable task
PURPOSE:
Requests that the SCCD server carries out a packaged run, after checking for
locks. It also sets up the DAS server so that it is ready for the run, and
cleans it up afterwards.
SUBORDINATES:
called:
ciaRedirectErs ciaPingInit ciaExitInit ciaRpcInit ciaTalkInit
ciaLockInit ciaLockReq ciaObeyRpc ciaExecuteRpc
GetServerName
DEPENDENCIES:
The talker program should be running.
INTERFACES:
Call from command line:
name [-C NN/PORTX] N.N ["T"]
all actions (RUN DARK BIAS and SCRATCH) accept one optional argument
"-C NNN\PORTX " where NNN is unused, and X is the port name that the SCCD
server serves.
RUN, DARK, GLANCE and SCRATCH also have one required parameter N.N the
exposure time, and one optional parameter T the title for the observation.
BIAS has one optional parameter T the title for the observation.
In all cases, if T is not provided, the observation title defaults to
the actionname, that is SCRATCH, BIAS, RUN, DARK or GLANCE.
The RUN, DARK and BIAS commands causes a run to start, and all the headers
to be collected, and finally the file written to a numbered run file.
By aliasing the command RUN, the following commands become available:
ARC FLAT SKY and FLASH
The SCRATCH command causes a run to be carried out, all the headers
collected but the run gets saved in the scratch file number given. This
will get overwritten with the next scratch file for that number.
The GLANCE command causes a run to be carried out, and all the fast
headers collected (ie don't bother with the PE ones). The file is not
copied to any other file at the end of the run, and is available in the
observation directory as DASn.fit, where 'n' is the DAS_CHANNEL used.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
8.7 clientRunKickCCD.c
TYPE:
C source-code file: producing executable task
PURPOSE:
Send a kick to the SCCD_DORUN action to the SCCD server, after checking for
locks. Implements the following clients:
ABORT FINISH PAUSE CONTINUE
FUNCTION:
Requests the RUNKICK lock, if this was successful, it sends a kick to the
SCCD_DORUN action on either the requested server, or "SCCDa" by default.
The kick PRC is built up firstly, using the name of the command (argv[0])
to decide the contents of the arguments to the RPC. This kick is
then sent to the action.
If and ABORT was requested, a kick is also sent to the RUN action on
the DASn server (n being retrieved from the DASCHANNEL parameter on the
SCCD server).
SUBORDINATES:
called:
ciaRedirectErs ciaPingInit ciaExitInit ciaRpcInit ciaTalkInit
ciaLockInit ciaLockReq ciaObeyRpc ciaExecuteRpc
GetServerName
DEPENDENCIES:
The talker program should be running.
INTERFACES:
Call from command line:
Accepts one optional argument "-C NNN\PORTX " where NNN is unused, and X
is the port name that the SCCD server serves.
No other parameters are expected.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"Remote Procedure Calls for Drama clients"
RGO/ING document OBS-RPC-1
8.8 clientSetup.c
TYPE:
C source-code file: producing executable task
PURPOSE:
Send the SCCD_INIT action to the SCCD server, after checking for locks.
Also sets up the DAS server.
FUNCTION:
Registers with Dits and the various cia utilities are started. The
arguemnt, which is the CCD name, is converted to upper case.
Requests SETUP lock. If this was successful, the SCCD_INIT action
request is sent off to the requested server, with the CCD name as the
only argument.
Finally, the HEADCODE, FORMAT and DASCHANNEL parameters are read from the
SCCD server, and used to call the FORMAT PACKETS and HEADCODE actions
on the DAS server.
SUBORDINATES:
called:
ciaPingInit ciaExitInit ciaRpcInit ciaTalkInit
ciaLockInit ciaLockReq ciaObeyRpc ciaExecuteRpc
GetServerName ciaGetPath
(as well as the DRAMA routines)
DEPENDENCIES:
The talker program should be running.
OBSDATA_DIR environment variable should be defined
INTERFACES:
Call from C:
Accepts one optional argument "-C NNN\PORTX " where NNN is unused, and
is the port name that the SCCD server serves.
Requires the environment variable OBSDATA_DIR for setting up the data
directory.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"Remote Procedure Calls for Drama clients"
RGO/ING document OBS-RPC-1
8.9 clientShutter.c
TYPE:
C source-code file: producing executable task
PURPOSE:
Send the SCCD_DOSHUTTER action to the SCCD server, after checking for locks.
FUNCTION:
Requests the SHUTTER lock, if this was successful, it sends the
SCCD_DOSHUTTER action request off to either the requested server, or
"SCCDa" by default. The command line argument defines what action
is required, either open, close or unjam (not case sensitive)
SUBORDINATES:
called:
ciaPingInit ciaExitInit ciaRpcInit ciaTalkInit
ciaLockInit ciaLockReq ciaObeyRpc ciaExecuteRpc
GetServerName
DEPENDENCIES:
The talker program should be running.
INTERFACES:
Call from command line:
Accepts one optional argument "-C NNN\PORTX " where NNN is unused, and
is the port name that the SCCD server serves.
One required parameter - the required action. None case sensitive.
One of "open","close" or "unjam"
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"Remote Procedure Calls for Drama clients"
RGO/ING document OBS-RPC-1
8.10 clientSyncRtc.c
TYPE:
C source-code file: producing executable task
PURPOSE:
Send the SCCD_DOSYNC action to the SCCD server, after checking for locks.
FUNCTION:
Requests the RTCSYNC lock, if this was successful, it sends the SCCD_DOSYNC
action request off to either the requested server, or "SCCDa" by default.
SUBORDINATES:
called:
ciaRedirectErs ciaPingInit ciaExitInit ciaRpcInit ciaTalkInit
ciaLockInit ciaLockReq ciaObeyRpc ciaExecuteRpc
GetServerName
DEPENDENCIES:
The talker program should be running.
INTERFACES:
Call from command line:
Accepts one optional argument "-C NNN\PORTX " where NNN is unused, and
is the port name that the SCCD server serves.
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"Remote Procedure Calls for Drama clients"
RGO/ING document OBS-RPC-1
8.11 sccdClients.mk
# TYPE:
# makefile
#
# PURPOSE:
# To build the clients for use in the Science CCD server and DAS server.
#
# FUNCTION:
# The main targets are:
#
# build This builds the final executables:
# SHUTTER SETTINGS SETUP SYNC_RTC RUN
# RUNKICK RESET PROMOTE MULTRUN
#
# install If the execuatables haven't been built, they are 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
#
#
# 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 targets 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:
# sccdErr.msg
# dasErr.msg
# ciaErr.msg
# insErr.msg
# srvErr.msg
# clientShutter.c
# clientGetServerName.c
# clientSettings.c
# clientSetup.c
# clientSyncRtc.c
# clientRunCCD.c
# clientRunKickCCD.c
# clientReset.c
# clientPromote.c
# ciaRpc.h
# ciaTalk.h
# ciaBoolean.h
# sccd.h
# ciaActions.h
#
# DEPENDENCIES:
# dramastart should have been run to define the locations of the DRAMA
# elements - libraries and headers.
#
# The CIA library should have been built.
8.12 sccd_clients.bom
# Bill of materials to build client programs for the SCCD at v1.10:
# 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 sccd_clients.bom 1.10 /ing/src/SCCS/s.sccd_clients.bom 96/11/19 15:07:48
Assembly libcia 6.3 ${OBSSYS}/lib/libcia.a
Component ciaActions.h 1.1 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 clientGetServerName.c 1.6 sccs ${ING}/src
Component clientPromote.c 1.5 sccs ${ING}/src
Component clientReset.c 1.6 sccs ${ING}/src
Component clientRunCCD.c 1.31 sccs ${ING}/src
Component clientRunKickCCD.c 1.8 sccs ${ING}/src
Component clientSettings.c 1.16 sccs ${ING}/src
Component clientSetup.c 1.17 sccs ${ING}/src
Component clientShutter.c 1.8 sccs ${ING}/src
Component clientSyncRtc.c 1.4 sccs ${ING}/src
Component sccd.h 1.4 sccs ${ING}/src
Component sccdSds.c 1.4 sccs ${ING}/src
Component sccdErr.msg 1.7 sccs ${ING}/src
Component dasErr.msg 4.2 sccs ${ING}/src
Component ciaErr.msg 2.2 sccs ${ING}/src
Component insErr.msg 1.3 sccs ${ING}/src
Component srvErr.msg 1.1 sccs ${ING}/src
Component MULTRUN 1.5 sccs ${ING}/src
Component sccdClients.mk 1.1 sccs ${ING}/src
Tag RESET 1.10 C RESET.TAG.c
Makefile sccdClients.mk RESET
Tag SETTINGS 1.10 C SETTINGS.TAG.c
Makefile sccdClients.mk SETTINGS
Tag SETUP 1.10 C SETUP.TAG.c
Makefile sccdClients.mk SETUP
Tag SHUTTER 1.10 C SHUTTER.TAG.c
Makefile sccdClients.mk SHUTTER
Tag SYNC_RTC 1.10 C SYNC_RTC.TAG.c
Makefile sccdClients.mk SYNC_RTC
Tag PROMOTE 1.10 C PROMOTE.TAG.c
Makefile sccdClients.mk PROMOTE
Tag RUN 1.10 C RUN.TAG.c
Makefile sccdClients.mk RUN
Tag RUNKICK 1.10 C RUNKICK.TAG.c
Makefile sccdClients.mk RUNKICK
Tag MULTRUN 1.10 C MULTRUN.TAG.c
Makefile sccdClients.mk MULTRUN
8.13 mon.c
TYPE:
C source-code file: ten functions.
PURPOSE:
Provides simple, curses, mimic to the sccd server.
FUNCTION:
When started, the name of the SCCD server to attatch must be provided as
a character argument. This allows the monitor task to attatch to the
server, using the SCCDc name described in INS-CCD-5. The curses screen is
initialised (using SetupScreen). The task then registers with DITS using
the name SCCDMONxxxx where xxxx is the process id. The process then sets
up the RPC system, and sends a monitor request and a get parameter request
to the SCCD server for each parameter needed. The main loop is then entered.
During this, any messages that arrive are forwarded to ProcessMonitor.
Monitor message forwarded to ProcessMonitor, where the parameter name
allows the parameter value to be extracted. This is then forwarded to
UpdateMimic which will place the new value on the screen.
Messages can be sent to the message half screen using LogMsg.
DEPENDENCIES:
The sccd server should have started before this task is started.
INTERFACES:
Call from C:
int main(int argc, char *argv[])
void LogMsg( char *str )
void RefreshScreen( void )
void SetupScreen ( void )
void ProcessMonitor( StatusType *status )
void UpdateMimic( Param_t param, void * data , StatusType * status)
DITS actions implemented:
EXIT calls void EXIT (StatusType *status ) with no parameters. This
terminated immediately, and will cause the event loop to terminate.
PING calls void PING (StatusType *status ) with no parameters. This
terminated immediately.
Command line:
mon <SCCDservername>,
for example to attatch to SCCDa execute "mon SCCDa"
REFERENCES:
"Interfacing with the science CCD server"
RGO/ING document INS-CCD-5
"Remote Procedure Calls for DRAMA clients"
RGO/ING document OBS-RPC-1
8.14 mon.mk
# TYPE:
# makefile
#
# PURPOSE:
# Build the CCD controller status window (curses).
#
# FUNCTION:
# The main targets are:
#
# build This builds the final executable, mon
#
# 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 by 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:
# ciaRpc.h
# ciaTalk.h
# ciaActions.h
# sccd.h
# unet.h
# sccdErr.msgt
# mon.c
#
# DEPENDENCIES:
# dramastart should have been run to define the locations of the DRAMA
# elements - libraries and headers.
8.15 mon.bom
# Bill of materials to build mon - the CCD status display at v1.2:
#
#
# 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 mon.bom 1.2
Assembly libcia 5.2 ${OBSSYS}/lib/libcia.a
Component mon.mk 1.4 sccs ${ING}/src
Component ciaActions.h 1.1 sccs ${ING}/src
Component ciaBoolean.h 1.1 sccs ${ING}/src
Component ciaTalk.h 1.4 sccs ${ING}/src
Component ciaRpc.h 2.1 sccs ${ING}/src
Component mon.c 1.9 sccs ${ING}/src
Component sccd.h 1.4 sccs ${ING}/src
Component unet.h 1.4 sccs ${ING}/src
Component sccdErr.msg 1.7 sccs ${ING}/src
Tag mon 1.2 C TAG.c
Makefile mon.mk mon
Appendix A. Document History
Issue 1.1 9.12.96 First released