INS-DAS-8

Software Requirements
for the
Data-acquisition server

Issue 5.2; 21st May 1996

Royal Greenwich Observatory,
Madingley Road,
Cambridge CB3 0HJ

Telephone (01223) 374000
Fax (01223) 374700
Internet G.Rixon@ast.cam.ac.uk

1 Introduction

1.1 Purpose of this document

This document defines the behaviour and interfaces that the DA server guarantees to other systems and programs. If you need to modify, test or interface to the server you should read this document.

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

Issue 1 of this document was titled Interfaces to the Data-acquisition Server.

1.2 Scope of the software

The data-acquisition servers are a group of programs for the `Solaris' operating-environment that records observations on disk. The detailed design of the servers is described in INS-DAS-9. The original user-requirements driving the design of the server are listed in INT-PF-1 and INT-DAS-1; a technical analysis of INT-PF-1 is presented in INT-PF-4.

The behaviour of the servers is quite complex. Much of the detailed behaviour is described in INS-DAS-9 but these details are liable to change. The aspects of the behaviour that can be relied upon are described in section 2.

Image data is received by the server from CCDs on a dedicated fibre-optic link, described in section 3.

The images are written to disk in the Unix file-system of the computer RUNing the data-acquisition server. The images are stored in FITS format and the details of the FITS storage are discussed in section 5. Auxiliary information for the FITS headers is read from separate disk-files as described in section 4.

The servers run under the supervision of the general observing system. The interfaces by which a server talks to its parent system are described in sections 6 and 7.

1.3 References

[1] Implementation of the Data-acquisition Server
RGO/ING document INS-DAS-9 by Guy Rixon.

[2] User Requirements for the INT DAS
RGO/ING document INT-DAS-1 by Guy Rixon and Daniel Matthews.

[3] Controls for the INT PFC: User Requirements
RGO/ING document INT-PF-1 by Guy Rixon.

[4] Controls for the INT PFc: System Requirements
RGO/ING document INT-PF-4 by Guy Rixon.

[5] The Fibre-optic Multiplexor: a Technical Description
RGO/ING document INS-DAS-7 by Nick Hall.

[6] The Flexible Image Transport System
NASA document NOST-100b.

2 Behaviour of the data-acquisition servers

2.1 Operational concepts

This section describes how the DA server should be used.

A data-acquisition channel, as understood by the server, is an image-data path from a single CCD. Each server operates one channel and the data-acquisition hardware allows up to eight channels to run in parallel. Channels are independent of one another in normal operation, but some error conditions can only be cleared by resetting all channels at once.

A pixel headcode is a byte that prefixes all pixels for a particular channel as they are passed down from the CCDC and allows the data-acquisition hardware to separate a merged stream of pixels. When a channel is set up at the start of observing, the relationship between channel number and pixel headcode is written into the hardware in response the HEADCODE action.

A readout-format defines how the stream of pixels from a CCD is to be reconstructed into a rectangular image. The format states the size of the final image, the binning, the arrangement of readout windows and any reflections or rotations that must be applied to the incoming pixel-stream. To operate a data-acquisition channel, the server must be told the format for that channel using the FORMAT action. Once set, the format remains in force until explicitly altered by the FORMAT action. The server records on disk the format set for each channel and will remember it if reloaded or reinitialized.

Arming a channel, a service performed at the start of the READOUTn command, makes it ready to receive a readout. Any pixels received on a channel that is not armed are lost but otherwise cause no problems.

A run means, to a DA server, the acquisition of a single CCD readout and the accompanying FITS-header. A run starts when the server executes the command RUN and ends when the server has written the data to disk and disposed of the disk file. In the event that a run has not been saved or otherwise disposed of, starting a new run ends the old one and destroys its data.

A FITS-header packet is a disk-file containing part of the FITS header for an observation. By concatenating a set of packets, the server generates the full header required in each FITS file. The server requires its parent system to tell it the names of the packets; a separate list is required for each active channel. Once the list is set up, it applies to all subsequent observations until explicitly changed by a command to the server. The server records the packet lists on disk and remembers them if reloaded or reinitialized.

Saving a run implies making the corresponding disk-file accessible to the archiving system, as described in section 5. Note that the archiving operations - logging and writing to tape - are not performed by the data-acquisition servers. A run marked for saving is not actually passed for archiving until its file has both image and header.

Discarding a run implies destroying its file and losing the data. For operational reasons, a run marked for discarding is not deleted until its file has both header and data; the wasted work in completing the file is offset by simplification in the software.

Demoting a run implies converting it to a scratch file and thus hiding it from the archiving system. Promoting a scratch file reveals it to the archiving system and gives it a run number.

A glance file is the file created by a server to store an observation as it is acquired. The server creates a glance file for every observation. An archive file is a file for the observation that is visible to the archiving system. These files have the naming scheme described in section 5; the serever creates them by renaming the equivalent glance files. A scratch file is an arbitrary file for an observation. Scratch files are created by renaming glance files, but never by renaming archive files; that is, once an observation is archivable, it cannot be demoted.

Run numbers are counted from one in a single series and are never reused. Run numbers are only assigned to observations that will be archived. Demoted observations are not given run numbers until they are promoted.

In normal operation, a server establishes settings for the data directory, the pixel headcode, the readout format and the packet list when it initializes; the settings are read back from disk. Before observing, these settings may be changed, through the command interface, to tune the server for the current instrument-configuration; most commonly, the observers will set a new readout format.

2.2 Specific requirements

This section details the behaviour of the server that is required for successful operation and the behaviour that is guaranteed to other systems and programs. Where `facts' about the server are stated in the present tense, they should be interpreted as requirements for the detailed design.

The interfaces for the actions defined here are detailed in section 6. The parameters are detailed in section 7. The `settings' are a data structure containing the control settings that the server retains on disk between executions.

2.2.1 Invariant conditions

Req 1 The server provides eight channels on which observations may be acquired in parallel.

Req 1.1 Except on reset of the FOX, the channels operate independently.

Req 2 The server is robust, and cannot be made to fail (i.e. crash and cease operation) by external events, except in the case where the host computer fails.

Req 2.1 Exceptional conditions signalled by the FOX driver (section 3) are handled and reported

Req 2.2 Disk-write errors in storing observations are handled and reported.

Req 2.3 Invalid inputs in the DRAMA command-interface (section 6) are handled and reported.

Req 2.4 Any error can be recovered with the loss of no more than one observation per active channel.

Req 3 The server is self-sufficient at loading and will initialize itself as detailed below.

Req 3.1 The server records the control settings for each channel each time these settings change.

Req 3.2 When loaded, the server restores the saved settings on each channel. Where there are no valid saved settings,for a channel, that channel is held inoperable until valid settings are applied.

Req 3.3 No `initialize' action is required when the server is loaded: initialization is automatic. The RESET action is equivalent to killing and reloading the server.

Req 4 Pixel headcodes satify the following conditions:

Req 4.1 The headcodes to which channels are mapped Headcodes are integers in the range 0 to 232 - 1 inclusive (i.e. the FOX driver stores headcodes as an unsigned integer). Headcodes attached to CCD pixels are always in the range 00h to 7Fh (i.e. the CCDCs produce headcodes as a single byte in which the top bit is always unset).

Req 4.2 A headcode is valid if and only if it is in the range 00h to 7Fh inclusive.

Req 4.3 A valid headcode must never be mapped to more than one channel.

Req 4.4 If the correct headcode for a channel is unknown, that channel must be mapped to an invalid headcode.

Req 5 Data-directory names satisfy the following conditions:

Req 5.1 Directory names are character strings with the semantics of Unix file-names.

Req 5.2 A directory name is valid if and only if it is the full path-name of a writable directory visible to the DA server. That is, the server must be able to write to the file named by the directory-name datum.

Req 5.3 If the correct data-directory for a channel is not known, that channel must be assigned an invalid directory-name such as a blank string.

Req 6 FITS-packet lists satify the following conditions:

Req 6.1 Packet lists are character strings. They normally contain space-separated lists of file-names.

Req 6.2 A list is valid if it contains only characters that can appear in a filename. In practice, this means that any list is valid. In particular, lists which are zero-length strings and lists which contain only whitespace are valid.

Req 6.3 If the correct packet list for a channel is not known, that channel must be assigned an empty packet-list.

Req 7 Readout formats satisfy the following conditions:

Req 7.1 Formats are transported between tasks in SDS structures built to match the structure definition in sccd.h.

Req 7.2 A format is valid for input to the DAS if and only if it contains the data specified in sccd.h and if those data satisfy the following conditions:

Req 7.2.1 The CCD size has positive numbers for x and y.

Req 7.2.2 The binning factors are integers from 1 to 10 inclusive.

Req 7.2.3 The windows all fit within the bounds of the chip or the windows are disabled.

Req 7.2.4 No pixel is included in more than one readout window or the windows are disabled.

Req 7.2.5 The string defining geometric transformations contains only the characters `+', `-', `x' and `y'.

Req 8 A format is valid after processing by the FORMAT action of the DAS if it satisfies the following conditions:

Req 8.1 The format remains valid for re-input to the DAS.

Req 8.2 The size of the output image has positive numbers for x and y.

Req 8.3 The processed windows fit within the output image.

2.2.2 When the DAS is loaded

Preconditions:

FOX powered up and available.

No activity on FOX.

No tasks DASM or DASn loaded.

Action:

Req 9 Start DRAMA task DASM.

Req 10 Enable actions on DASM as defined in section 6.

Req 11 Reset FOX.

Req 12 Allocate buffer memory.

Req 13 For each channel n indicated in command-line options:

Req 13.1 Start DRAMA task DASn.

Req 13.2 Recover control-settings from disk.

Req 13.3 Validate settings; calculate derived data for the readout format.

Req 13.4 Set the headcode in the FOX.

Req 13.5 Update settings on disk.

Req 13.6 Create the parameters defined in section 7 and set their initial values.

Req 13.7 Enable the actions on DASn defined in section 6.

Req 13.8 If any part of the above cannot be performed, exit with bad status. (This clause does not apply when settings are processed correctly but found to be invalid.)

Postconditions:

Req 14 FOX idle on all channels.

Req 15 Parameter RUN set as follows:

Req 15.1 RUN.RUN set to zero.

Req 15.2 RUN.SCRATCH set to zero.

Req 15.3 RUN.READOUT set to zero.

Req 15.4 RUN.HEADER set to zero.

Req 16 Parameters READY, OBSDATA, HEADCODE, FORMAT and PACKETS reflect the values read from the stored control settings. (See the invariants section for the corresponding actions.)

2.2.3 OBSDATA action

Preconditions:

DASn loaded and running

Action:

Req 17 Get the name of the directory in which runs are to be stored from the action's argument list.

Req 18 Validate the directory: it's valid if it exists and is readable, writeable and executable by the DAS.

Req 19 If the directory is valid:

Req 19.1 Record the directory name in the settings.

Req 19.2 Derive the name of the glance file for this channel and record it in the settings.

Postconditions:

Req 20 If the directory was valid:

Req 20.1 The specified directory-name and the name of the glance file are recorded in the settings.

Req 20.2 The action ends with good status.

Req 21 If the directory was not valid:

Req 21.1 The settings are not changed.

Req 21.2 The action end with bad status.

Invariants

Req 22 Parameter OBSDATA contains the directory name currently stored in the control settings, whether or not this has been updated in the current action.

Req 23 Parameter READY.OBSDATA is set to 1 (true) while the directory named by OBSDATA is valid and to 0 (false) otherwise.

2.2.4 HEADCODE action

Preconditions:

DASn loaded and running

FOX powered up and available.

Action:

Req 24 Get the headcode from the action's argument list.

Req 25 Validate the headcode: it's valid if it is an integer in the range 00h to 7Fh inclusive.

Req 26 If the headcode is valid:

Req 26.1 Set up the headcode in the FOX.

Req 26.2 Record the headcode in the settings.

Postconditions:

Req 27 If the headcode was valid:

Req 27.1 The specified headcode is set up in the FOX.

Req 27.2 The headcode directory is recorded in the settings.

Req 27.3 The action ends with good status.

Req 28 If the headcode was not valid:

Req 28.1 The headcode map in the FOX has not changed.

Req 28.2 The settings are not changed.

Req 28.3 The action end with bad status.

Invariants

Req 29 Parameter HEADCODE contains the headcode currently stored in the control settings, whether or not this has been updated in the current action.

Req 30 Parameter READY.HEADCODE is set to 1 (true) while the headcode in HEADCODE is valid and to 0 (false) otherwise.

2.2.5 FORMAT action

Preconditions:

DASn loaded and running

Actions:

Req 31 Get the format structure from the action's argument list.

Req 32 Validate the format.

Req 33 If the format is valid:

Req 33.1 Process the format to internal form; account for windowing, binning, reflection and rotation.

Req 33.2 Record the processed format in the settings.

Postconditions:

Req 34 If the format was valid:

Req 34.1 The format is recorded in the settings, including all data needed for RUN to reconstruct an image.

Req 34.2 The action ends with good status.

Req 35 If the headcode was not valid:

Req 35.1 The settings are not changed.

Req 35.2 The action end with bad status.

Invariants

Req 36 Parameter FORMAT contains the format currently stored in the control settings, whether or not this has been updated in the current action.

Req 37 Parameter READY.FORMAT is set to 1 (true) while the format in FORMAT is valid and to 0 (false) otherwise.

2.2.6 PACKETS action

Preconditions:

DASn loaded and running.

Action:

Req 38 Get from the action's argument list (a) the list of header packets to be collected; (b) the number of FITS descriptors exepected, totalled over all header packets.

Req 39 Validate the packet list and descriptor count: the packet list can be any string up to 255 characters in length and the descriptor count can be any integer that is not negative or greater than 100,000.

Req 40 If the packet list and descriptor count are valid:

Req 40.1 Record the packet list in the settings.

Req 40.2 Calculate the total size of the FITS header and record this in the settings.

Req 40.3 Update PACKETS and READY.PACKETS.

Postconditions:

Req 41 If the packet list and descriptor count were valid:

Req 41.1 The packet list is recorded in the settings.

Req 41.2 The size of the FITS header is recorded in the settings.

Req 41.3 The action ends with good status.

Req 42 If the headcode was not valid:

Req 42.1 The settings are not changed.

Req 42.2 The action end with bad status.

Invariants

Req 43 Parameter PACKETS contains the packet list currently stored in the control settings, whether or not this has been updated in the current action.

Req 44 Parameter READY.PACKETS is set to 1 (true) while the list in PACKETS is valid and to 0 (false) otherwise.

2.2.7 RUN action

Preconditions:

DASn loaded and running

Valid settings are available for data directory, headcode, format and packet list.

Action:

Req 45 Get a disposal option from the action's argument list.

Req 46 Validate the disposal option: its must be Archive, Scratch or Glance. For Scratch, the name of the scratch file must also be given. Abort the action if the arguments are invalid.

Req 47 Create a FITS file large enough to hold the header size and readout format recorded in the settings; create the file in the data directory recorded in the setting.

Req 48 If the disposal option is Archive:

Req 48.1 Allocate a run number for the run.

Req 48.2 Allocate a name for the archiveable file according to the rules of section 5.

Req 48.3 The name of the current scratch file is blank.

Req 49 If the disposal option is Scratch:

Req 49.1 Set the run number to zero.

Req 49.2 Record the name of the current scratch file.

Req 50 If the disposal option is Glance:

Req 50.1 Set the run number to zero.

Req 50.2 The name of the current scratch file is blank.

Req 51 Set the parameter RUN to show no progress in the readout:

Req 51.1 Set RUN.RUN to the run number.

Req 51.2 RUN.SCRATCH to the name of the current scratch file.

Req 51.3 Set RUN.READOUT to zero.

Req 51.4 Set RUN.HEADER to zero.

Req 52 Write the FITS header and image to the FITS file in parallel:

Req 52.1 Construct the header from packets:

Req 52.1.1 Write the mandatory FITS descriptors (see section 5) to the FITS file.

Req 52.1.2 For each packet named in the packet list of the settings:

Req 52.1.2.1 Wait for the packet to become readable.

Req 52.1.2.2 Copy the packet into the FITS file.

Req 52.1.3 Write the END descriptor into the FITS file.

Req 52.1.4 Pad the FITS header with blanks to bring it up to the size recorded in the settings.

Req 52.2 Reconstruct the image from incoming pixels in accordance with the formatting instructions recorded in the settings:

Req 52.2.1 Start the image at the first byte in the FITS file after the FITS header.

Req 52.2.2 For each pixel of this image:

Req 52.2.2.1 Wait for the pixel to be come available from the FOX.

Req 52.2.2.2 Acquire the pixel.

Req 52.2.2.3 Use the formatting instructions to calculate the pixel's address relative to the start of the output image.

Req 52.2.2.4 Convert the pixel from unsigned 16-bit format to signed 16-bit such that an input of 0 maps to -32K and an input of +64K maps to +32K..

Req 52.2.2.5 Copy the converted value into the FITS file.

Req 53 While data are arriving, update the parameters RUN.READOUT and RUN.HEADER to show percentage completion. Acceptable update rates are between 1 Hz and 0.05 Hz.

Req 54 When the FITS header and image are complete, close the FITS file and dispose of it according to the disposal recorded in the settings:

Req 54.1 For a disposal option of Archive, rename the glance file to be the archiveable file.

Req 54.2 For a disposal option of Scratch, rename the glance file to be the scratch file.

Req 54.3 For a disposal option of glance do not rename the file.

2.2.8 PROMOTE action

Normal preconditions:

Valid file-name and data directory indicated in argument list

Scratch file of that name exists.

Intended actions:

Req 55 A run number is allocated to the scratch file.

Req 56 Scratch file is renamed to be an archivable file.

Req 57 Scratch file is made visible to archiving system.

Postconditions:

Req 58 If preconditions met:

Req 58.1 Scratch file no longer exists.

Req 58.2 Run file equivalent to scratch file exists and is named in the prescribed convention.

Req 58.3 Run file is visible from archiving computer.

Req 58.4 Action returns good status.

Req 59 If preconditions not met:

Req 59.1 Archiving system sees no `new' files.

Req 59.2 Action returns bad status.

2.2.9 RESET action

Normal preconditions:

FOX is powered on and available.

Intended actions:

Req 60 Reset FOX.

Req 61 Update parameters RUN, READYn to show all runs aborted.

Req 62 End all other actions with bad status.

Postconditions:

Req 63 As for initialization.

Req 64 Action returns good status.

3 Interface to the CCDs

Image data is produced by one or more CCD controllers and written to a fibre-optic link; each CCD controller drives one fibre, and where a controller commands more than one CCD chip the pixels from the chips are interleaved on the same fibre. The outputs of the fibres are brought together in a multiplexor or `FOX rack', as described in INS-DAS-7. The FOX rack forwards the image-data as electrical signals to an interface card (an S330A card with a custom `snapper', as supplied by Data Cell Ltd.) mounted in the S-bus of the computer RUNing the data-acquisition server. The interface card writes each image to a memory-buffer in the address space of the data-acquisition server. The interface card and its driver are specific to Solaris 2 and the DA Server cannot run with any other operating system.

The formal interface to the DA servers is the API of the Solaris device-driver for the S330A. That is, the servers are conceptually interfaced to the FOX rack but actually interacts with a part of the SunOS-5 kernel via Unix system calls. The following description of the API is transcribed from notes provided by Data Cell; some details have been added. The general syntax of the calls is standard for Unix and is described in the Solaris manual-pages.

3.1 open()

This call opens one channel or `minor device' of the interface.

fileDescriptor = open( deviceName, flags, 0 );

If open() fails, it returns -1 and sets errno to an error code. The following error-codes have special meaning for the FOX interface:

ENXIO The fox-interface is not properly initialized. This is a failure of the hardware or of the operating system and should not occur in service.

EINVAL The FOX rack is not properly initialized.

ENODEV The minor-device number is not recognized. Either the calling program gave an incorrect number or the device driver is not properly installed in /dev.

EBUSY This minor device (0 to 7) is already open.

3.2 read()

This call accepts a readout from the FOX and completes when a specified number of bytes have arrived.

nBytesRead = read( fileDescriptor, buffer, nBytesToRead );

Minor devices 0 to 7 may each have one read() active in parallel, but there may not be more than one read() on any minor device. It is not possible to read from minor device 128.

If a readout ends before the required number of pixels have arrived, the corresponding read() is eventually terminated by a timer. The timeout value is set by ioctl() with the RGOFOXIO_SET_TIMEOUT option. The timer starts when the first pixel of the readout arrives at the FOX. If a read times out, the read() call returns a number of bytes read which is less than the number expected.

If an error other than a short read occurs, an error code is returned in place of nBytesRead. The following error codes have special meanings.

EBUSY There is already a read() in progress on this minor device.

ENODEV You cannot read pixels from minor device 128.

EINVAL The pixel buffer is not aligned on a 16-byte boundary.

3.3 write()

It is not possible to write pixels into the FOX. A write() call on any minor device always returns EINVAL.

3.4 ioctl()

This call allows a program to query events in the interface electronics and the FOX and to impose settings on the FOX and the device driver.

status = ioctl( fileDescriptor, opCode, dataAddress );

3.4.1 RGOFOXIO_GETPROGRESS

This option yields the number of bytes yet to arrive in the current read() call on the current channel; the data buffer is a long integer. While the read is in progress, the number of residual bytes is an overestimate, as it does not take account of the progress of the current

DMA operation.

3.4.2 RGOFOXIO_ABORTREAD

This option aborts the current read on the channel. If pixels are still arriving, subsequent pixels are discarded The abort does not affect operations on other channels.

3.4.3 RGOFOXIO_RESET

This option resets the FOX, the interface electronics and the device driver. Any reads in progress are lost and the device returns to its default settings, which are useless for normal operation. After a reset, no channels are armed to receive pixels and any pixels arriving are discarded.

3.4.4 RGOFOXIO_MAP_CHANNEL and RGOFOXIO_GET_MAP

These options query and set the mapping of pixel headcode to minor-device number for one channel. It is necessary to set this mapping for each channel before that channel can be read; the default mappings are useless for astronomy.

The MAP_CHANNEL code takes as an argument an rgofox_map_t (defined in rgofox.h). In this structure, the element .snap_channel is the DAS channel-number (0..7) and the element .fox_unit is the desired headcode. Headcodes in the range 00h to 7Fh will be rejected if they are already set on another channel. Headcodes 80h and higher can be set on any number of channels.

The GET_MAP option reads back the headcodes set on all channels. It takes as an argument a 256-element

array of short in which element i contains the headcode set on channel i.

3.4.5 RGOFOXIO_GET_TIMEOUT and RGOFOXIO_SET_TIMEOUT

These options query and set the timeout value which terminates a read when insufficient pixels arrive; the data buffer is a long integer representing the timeout in milliseconds.

3.4.6 RGOFOXIO_GET_STATUS

This option gets the status on all channels, regardless of which minor device is indicated in the ioctl() call; the data buffer is an array, of size 0 to RGOFOX_UNITS, of rgofox_status_t.

3.4.7 Other ioctl() options

Data Cell provide in the driver several other options for ioctl(). These are mainly low-level accesses to the interface hardware and are not used by the DA server.

3.5 close()

This call closes down a minor device, thereby allowing it to be opened again elsewhere in the system.

status = close( fileDescriptor );

The operation-codes for ioctl(), the constant RGOFOX_UNITS and the structured types used in ioctl() are defined in the include-file rgofox.h. The DA server includes this file in several of its components.

4 Fits-header collection

The data-acquisition server constructs a FITS header for each FITS file by concatenating the contents of FITS-header packets from disk files. Any number of packets may be specified for a data-acquisition channel and it is valid to specify no packets at all.

In enabling a data-acquisition channel, the system using the data-acquisition server must specify a list of packet names using the PACKETS command described in section 6. By default, when the server is loaded or initialized, the list contains no packets. Each entry in the list must be a single word and the entries must be separated by one or more blanks. The server converts the entries into names of files by adding the suffix .nnn where nnn is the run number; the server expects to be able to find and read these files during the run. For example, if the list of packets is set to

observation telescope pfc ccd

observation.666, telescope.666, pfc.666, ccd.666

observation.667, telescope.667, pfc.667, ccd.667

The data-acquisition server does not write to the packet files and does not delete them once it has read them. Once the server has finished with the run

to which the packets apply, it does not look at them again and the parent system can delete them.

Each packet must contain FITS descriptors in the format defined by NOST-100b. The packet files must contain only the bytes of the descriptors; i.e. the file length should be an exact multiple of 80 bytes and there should be no padding or new-line characters between descriptors.

The final header preserves the ordering of descriptors within packets and the order of packets within the header. The agency that writes the packets must order the descriptors to satisfy the user requirements.

The header packets should not include any of the following keywords, for which descriptors are supplied by the DAS server: SIMPLE, BITPIX, NAXIS, NAXIS1, NAXIS2, BZERO, BSCALE, BLANK, RUN.

Once a run begins, the data-acquisition server will attempt to read the header-packet files as soon as they appear. If the files are locked against reading the server will wait and try again later. The programs that write the files must ensure: (a) that the data-acquisition server never sees a packet that is both incomplete and unlocked; (b) that the packet files are unlocked once they are complete so that the data-acquisition server is not delayed.

5 Passing files for archiving

For any given night, the DA server writes each observation to a FITS file in the same disk directory. The files in this directory are visible to the data-handling system (DHS), which is expected to poll the directory for new observations.

The FITS files are given a path name of the form

obsdata/rn.fit

/int/obsdata1/r101800.fit

The FITS file for an observation is created approximately at the start of the exposure. The DHS should not attempt to process the file until the observation is complete and the DAS has recorded it. To enforce this, the DAS does not give the file its final name until the file is complete.

Once a file is is given its final name, it is available to the DHS and the DAS does not touch it again.

Observations demoted to scratch files are, by default stored in the same directory as the archivable observations, but the user can choose to have them written to another directory in the same file-system. There is no prescribed naming convention for scratch files. Scratch files are ignored by the DHS.

When a scratch file is promoted to a run file, it is given a new run number. To the DHS, a promoted file appears to be newly created and the DHS processes it accordingly.

6 Command interface

Data acquisition servers are DRAMA tasks and use the action/parameter interface defined for DITS. This section describes how the DA servers should be started and how they are addressed by other tasks.

6.1 Initialization

The DAS is started by executing the program `dasm' which is the DAS master task. Dasm starts a seperate server task for each active channel.

Dasm requires eight command-line arguments each defining how much image-buffer memory is required for a channel in units of 1,000,000 bytes. A value of zero for any channel tells dasm not to load that channel. For example,

% dasm 0 2.5 3.4 0 1.2 0 0 0

6.2 DRAMA names and addresses

The DAS master task logs into the DRAMA message-net as DASM. The channel servers log on as DASn where n is the number of the channel they serve. Case is significant when invoking these programs by name. If the data-acquisition computers for the INT and JKT are, say, lpss10 and lpss12 respectively, then the data-acquisition servers for channel 0 at those telescopes can be addressed as DAS0@lpss10.ing.iac.es and DAS0@lpss12.ing.iac.es: these are the fully-qualified task names that would be passed to functions of the DRAMA libraries when connecting to the servers.

6.3 Actions on DASM

RESET resets the master server and the servers for all channels. The channel servers abort any outstanding runs and exit. The master server then reloads the necessary channel servers. This action can be used to clear problems, to change the set of active channels or to vary the amount of buffer memory allocated to the channels. RESET requires arguments as follows.

Argument1 (floating point) is the amount of buffer memory for channel 0.

Argument2 (floating point) is the amount of buffer memory for channel 1.

Argument3 (floating point) is the amount of buffer memory for channel 2.

Argument4 (floating point) is the amount of buffer memory for channel 3.

Argument5 (floating point) is the amount of buffer memory for channel 4.

Argument6 (floating point) is the amount of buffer memory for channel 5.

Argument7 (floating point) is the amount of buffer memory for channel 6.

Argument8 (floating point) is the amount of buffer memory for channel 7.

The arguments are in units of 1,000,000 bytes.

The standard actions PING and EXIT are also provided. EXIT causes the channel servers to shut down as well as the master server; all outstanding runs are terminated.

6.4 Actions on DASn

OBSDATA sets the name of the file partition (or of a directory therein) in which observations are stored. An absolute path-name is required. OBSDATA may be given at any time and has no effect on runs already set up by the RUN command below. OBSDATA requires one parameter as follows:

Argument1 (character string) is the path name for the data directory.

HEADCODE sets up the relationship between the headcode of pixels and channel number for one channel; the action completes immediately. HEADCODE requires one parameter as follows:

Argument1 (integer, decimal) is the pixel headcode.

FORMAT sets the readout format for one data-acquisition channel and completes immediately. Any invocations of READOUTn started after FORMAT take the new format; any READOUTn already in progress are not effected. FORMAT may be given at any time. FORMAT requires one parameter as follows:

Argument1 (structure) is a structure describing the format; the argument is formed by exporting (using SdsPut()) a C structure of type SCCD_format_T.

PACKETS sets the list of FITS-header packets for one data-acquisition channel and completes immediately. Subsequent invocations of RUN use the new packet list; any runs already in progress are not affected. PACKETS may be given at any time. PACKETS requires arguments as follows:

Argument1 (string) is the list of packets as described in section 4.

Argument2 (integer) is the total number

of FITS descriptors in the packets listed by Argument1.

RUN acquires an observation, recording image and FITS header on disk. The acquisition always creates a glance file and may also create an archive or scratch file; see section 2.1 for a definition of these terms. RUN requires arguments as follows:

Argument1 (character string) enables reading pixels from the FOX; it must be set to Fox or Nofox.

Argument2 (character string) controls reconstructing the image from the readout. It must be set to Image or Noimage.

Argument3 (character string) controls collection of header packets. It must be set to Packets or Nopackets. If no packets are collected, the header contains the mandatory descriptorrs and a lot of blank space.

Argument4 (character string) determines the file to which the data are ultimately written. It must be set to Archive, Glance, or ``Scratch=file" where file is the name of a scratch file to be created in the current data-directory. Note that a temporary glance file is used for the archive and scratch options.

Sending a Kick message to RUN aborts the observation and end the action. The Kick need no arguments.

KEEP saves the observation in the glance file for channel n. KEEP can only succeed if it follows RUN with the Glance option; otherwise, there is no glance file to keep.

KEEP takes a single argument, Argument1, which is identical to RUN's Argument4.

PROMOTE converts an existing scratch file into an archivable run. It cannot operate on a scratch file which is still being processed by RUN. PROMOTE requires arguments as follows:

Argument1 (character string) is the name of the file on which the action is to operate. This must be an absolute path-name.

Argument2 (character string) specifies the data directory in which the scratch file is kept. It must be an absolute path-name. Argument2 is optional: if omitted, PROMOTE looks for the scratch file in the directory most recently defined by OBSDATA.

There is no RESET action for DASn. A channel is reset by killing and reloading its server; this is normally done by RESET on DASM. The standard actions PING and EXIT are provided.

7 Parameter interface

The state of the data-acquisition channels, and of the runs active upon those channels, is reported through DRAMA parameters. These parameters are updated and accessed independently of actions on the data-acquisition server.

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

OBSDATA (string) is the directory in which observations are saved.

HEADCODE (unsigned integer) is the pixel headcode to which the channel is mapped.

FORMAT (`format' structure) is the readout format currently set on data-acquisition channel n. FORMAT is updated when a the FORMAT action is executed.

PACKETS (string) is the list of FITS-header packets currently set on data-acquisition channel n. PACKETS is updated when the PACKETS action is executed.

RUN (`run' structure) describes the run on data-acquisition channel n.

READY (`ready' structure) indicates the readyness of the server to acquire data on each channel.

The `format' structure used for FORMAT may be read by SdsGet() into a C structure of type SCCD_format_T as defined in sccd.h. This is the same type used as an argument of the action FORMAT.

ALARM (`dialogue' structure) reports and alarm condition. See OBS-TALK-1 for details.

The `run' structure used in RUN may be read by SdsGet() into a C structure of type dasRun_t as defined in das.h. The SDS elements of this structure are as follows.

RUN (unsigned long integer) is the run number.

READOUT (unsigned short integer) is the percentage completeness of the readout. This is updated once at the start of the readout, once at the end and at intervals of 5% completeness in between.

HEADER (unsigned short integer) is the percentage completeness of the header collection. This is updated once at the start of header collection, once at the end and approximately once per packet in between.

DISPOSAL (string) is the intended disposal at the end of the run: Archive, Scratch or Delete (exact case will be as given here).

The `ready' structures may be read into C structures of type dasReady_t as defined in das.h. The SDS elements of this structure are as follows; each filed is a Boolean integer.

OBSDATA (integer) is non-zero when the data-directory has been set.

HEADCODE (integer) is non-zero when the pixel headcode has been set.

FORMAT (integer) is non-zero when the readout format has been set.

PACKETS (integer) is non-zero when the FITS-packet list has been set.

RUN (integer) is non-zero when a FITS file is ready to receive data.

8 Compile-time interfaces

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

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

rgofox.h defines data types and constants for programs intending to access the FOX directly.

dasErr.h defines condition codes that are specific to the DAS.

dasErr_msgt.h defines a DRAMA message-translation table for use with the codes in dasErr.h

The DA server includes the file sccd.h from the SCCD sub-system.

Appendix A. Document History

Issue 1.1 10/03/95 First formal issue (as Interfaces to the DA server). Section 5 is new in this draft. The command interface in section 6 is substantially different from that in the second informal draft.

Issue 1.2 10/04/95 Amendments to command interface found necessary while coding the DA server. PACKETS now has an extra parameter (the length of the FITS header). The restriction on using HEADCODE during READOUTn is lifted.

Issue 2.1 22/05/95 Renamed Software Requirements for the DA server. The behaviour section was expanded to include detailed requirements. The READYn parameter were recast from character strings to structures containing boolean flags.

Issue 2.2 09/08/95 The requirements for initialization, and for the actions OBSDATA, HEADCODE, FORMAT, PACKETS were rephrased and made more exact. Requirments on the state of the settings file (which is a design feature and not part of the requirements) were recast in terms of what happens when the DA server is restarted. The numbering of the requirements has changed.

Issue 2.3 10/08/95 Invariant conditions for control settings are stated. The parameters HEADCODE are redefined to be unsigned integers. The numbering of requirements has changed.

Issue 3.1 17/08/95 The actions DISPOSEn were replaced by ARCHIVEn, DEMOTEn and DELETEn. The definition of the action PRMOTE was altered. Tne naming of FOX devices was altered to Data Cell's final scheme.

Issue 4.1 21/08/95 The actions RUN, READOUTn, HEADERn and the disposal actions are combined into new RUN.

Issue 5.1 14/12/95 The single task DAS is split into DASM and DASn. Sections 6 and 7 have changed. In particular, beware of new semantics for RESET and PROMOTE.

Issue 5.2 21/05/96 The semantics of PROMOTE and RUN were simplified.