INS-DAS-13

Technical User's Guide
to the Unix-based
Data Acquisition System

Issue 3.2; 1997-07-10

Royal Greenwich Observatory,
Madingley Road,
Cambridge CB3 0HJ

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

Document history

Issue 1.1 1996-02-08 Original document.

Issue 2.1 1996-10-16 Revised to suit das v3.1.

Issue 3.1 1997-02-17 Revised to reflect the introduction of dasprofile and daspackets.

Issue 3.2 1997-07-10 Updated to reflect observing system s4.2.

1 Introduction

1.1 Purpose of this document

This manual is provided as a guide to ING staff in installing, maintaining and configuring the Unix-based Data-Acquisition sub-System (DAsS). It is most definitely not an instruction to visiting observers on how to drive the system during normal observing; misuse of the techniques described below can subvert the integrity of the system and lose observations.

1.2 Scope of the software

The Data Acquisition System (DAS) is the collection of software and hardware that manages runs, drives CCDs and records observations on disk. The Data Acquisition sub-System (DAsS) is the part of the DAS that just records the observations.

The detailed, technical requirements for the DAsS are listed in [1] and the design of the software is described in [2]. Image data are input to the DAsS via fibre-optic links from the CCD controllers (CCDCs) and textual data describing each observation are read from files on disk. The DAsS outputs disk-FITS files each of which contain one run with an explanatory FITS header.

The DAsS is a of DRAMA server-programs. It is normally released as a package including a collection of DRAMA client-programs for engineering use, the latter being logically part of the Central Intelligence. This manual describes both the servers and the clients.

1.3 Glossary

Archive run: a science observation destined for the log, FITS tapes and La Palma archive.

bill of materials: a script in the language BOM (see [4]) defining the components that make up a program or group of programs.

CCDC: CCD controller.

channel: the data path to the DAS from one CCD. Channels have numbers 0 to 7.

client program: a program that uses a service provided by dasm or dasn.

cmd: a client program for general engineering commands.

csh> : represents a C-shell prompt in examples of commands. You do not type these characters when issuing the command.

DAS: the overall Data Acquisition System.

DAsS: the specific Data Acquisition sub-System.

daschoose: a client program that selects DAS channels.

dascontact: a client program to make contact with a newly-loaded DAsS.

dasformat: a client program that sets the DAS' readout format.

dasload: a script to load the DAsS on a remote computer.

dasm, DASM: the DAS' master server; dasm is the executable file and DASM is its name in the DRAMA message-net.

dasn, DASn: the server for one DAS channel.

dasreset: a client program that resets or reconfigures the entire DAS.

glance run: a run that persists on disk only until the next acquisition and is then over-written. All runs are glance runs if they aren't archive or scratch runs.

headcode: the byte attached to a pixel which identifies the CCDC that produced it.

header packet: a disk-file containing a contiguous fragment of the FITS header for a run.

libcia: a library of support subroutines needed to build the DAS client-programs.

obsdata: the client program that changes data directories.

run: the quantum of recorded observation. Each run is stored in a separate FITS file.

run number: runs are numbered, counting from one, and the number sequence for a given telescope is continuous for the entire lifetime of the telescope.

scratch run: a run preserved on disk for examination but not archived.

`the package': the data acquisition sub-system and the clients released with it.

1.4 References

[1] Software Requirements for the Data Acquisition Servers
ING/RGO document INS-DAS-8.

[2] Implementation of the Data Acquisition Server
ING/RGO document INS-DAS-9

[3] DAS: user manual
ING document INS-DAS-11

[4] BOM: a Configuration-Control Language
ING/RGO document SOF-BOM-1

[5] FITS headers for INT observations
ING/RGO document INT-DAS-2

[6] Dialogues with the user: general principles
ING/RGO document OBS-TALK-1.

[7] Interfaces to the science-CCD server
ING document INS-CCD-7 by Daniel Matthews.

2 Installing the package

These notes on installation are generally true for all versions of the package. The release notes for a particular version may over-rule some of the advice given here.

2.1 Environment

The build process uses two environment variables: OBSSYS and ING. ING should be set to show the root of the source tree from which components can be retrieved: e.g. /ing or /lpss10/ingsw. OBSSYS should name the root of the observing system into which the DAS will be built: e.g. /ing/21.1 or /ing/p1. ING and OBSSYS must always be absolute path-names and may not include shell constructs (wild-cards; references to environment variables; the tilde character).

To build the clients, the major assembly libcia must first be built and installed. Check the release notes for compatible versions of libcia. The DAsS requires source components from the srv series that are not part of the package. All these source components are drawn from the library ${ING}/src/SCCS.

Many of the configuration techniques require the command tool cmd.

The DAsS can be built (but cannot run) on a computer that does not have the FOX interface described in [1].

2.2 Installation of components and building of assemblies

The DAS source-components must be installed in the SCCS library ${ING}/src/SCCS. This is not an option: the bills of materials for the DAS will not operate correctly if the sub-system is installed elsewhere.

There are four bills of materials: dasn.bom, dasm.bom dasp.bom and das_clients.bom; the file das.bom is obsolete. Hence, the DAsS has no overall version number and four version numbers for sub-assemblies. These bills can be run as described in reference 4.

After building the sub-system there should be eight executable programs:

dasn is the server for one DAS channel; one copy of it is run per active channel;

rt is a utility program used by dasn to get real-time scheduling;

dasm is the DAsS' master server which manages start-up and shut-down;

dasp is the header-packet-collecting server;

obsdata is a client that changes data directories;

dasformat is a client that sets and reports the readout format;

dasreset is a client that resets and reconfigures the DAsS;

daschoose is a client that selects and activate DAsS channels;

dasprofile is a client that matches a channel to a particular CCD controller;

daspackets is a client (with a built-in GUI) that selects FITS-header packets for a channel;

dasload is a script to load dasn, dasm and the DRAMA network agents in a remote computer;

dascontact is a client that establishes DRAMA communications with DASn and DASM when they are newly loaded in a remote computer.

2.3 Installing the programs in the observing system

The command

csh> make -f das.mk install

copies the assemblies of the package into the observing system. The executable programs go into ${OBSSYS}/bin and a set of include-files (which may be required by clients outside the package) go into ${OBSSYS}/inc.

The program rt must be set up as a set-UID program owned by root. This is not done by the install command because the installation is not usually run from the root account and does not have the necessary privilege.

The command

csh> make -f das.mk clean

removes most of the waste files in the build directory.

The programs dasn and dasm will not run unless a `Data-Cell' image-capture interface is present in the host computer and the device driver for that interface is loaded; the driver is not a part of the DAsS package. The driver is supplied separately as the executable program rgofox and a shell-script called install. Running install copies rgofox to the appropriate system directory and makes it part of the Unix kernel; install also creates a set of files representing the minor devices of the interface. The DAsS expects to see the device files /dev/rgofox0128 and /dev/rgofox0n where n = 0..7 and these must be manually created as soft-links to the files that install generates. Only root can run install successfully.

2.4 Supporting software

The DAsS is designed to be run in conjunction with a Talker program (see reference 6) such that messages to the user and alarms are handled correctly. The DAsS servers connect to a default Talker when they are started: this is the task named by the environment variable TALKER in the job from which DASM is started. Other talkers can connect to the DAsS later and certain messages will be broadcast to all connected Talkers. The DAsS will operate satisfactorily with no Talkers attached; in this case any `broadcast' messages are written to the shell from which the DAsS was started.

Operation on a SPARCstation that is not the system computer requires the IMP network-agents master, receiver and transmitter to be present in the observing-systems binaries directory; master is also required by dasm for local operation on the system computer. This requirement is satisfied if the utility package is built. daspackets requires the generic client-program cmd, also from the utility package.

Logging of observations and archiving of data on FITS tapes are done by separate facilities. At the time of writing, these programs interact with the DAS only by reading the disk-FITS files. Thus, each time a data directory is changed in the DAS, an equivalent change should be made in the logging and archiving programs.

2.5 Checklist for installation

S Install the utility package to make cmd available.

S Install the talker package to make talker available.

S Install the libcia package to make the DAsS clients buildable.

S Execute dasn.bom.

S Execute dasm.bom (same build-directory as above).

S Execute dasp.bom (same build-directory as above).

S Execute das_clients.bom (same build-directory as above).

S Execute make -f das.mk deinstall ; make -f das,mk install.

S Change rt to be setuid root.

3 Configuration by ING staff

The DAsS has a large number of control settings that must match choices elsewhere in the observing system if data are to be collected correctly. The greater part of this configuration, as described below, should be set up by ING technical staff when a new DAsS version is installed, or when changing instruments or detectors.

To make the DAsS usable, it must be told the next run number to use, told the correct set of channels to use, matched to the CCD(s) in use and told the set of FITS-header packets to store with each run; the data directory. Once the sub-system has accepted these settings, it will remember and re-apply them whenever it is started. Setting the run number must be done before starting the sub-system. All the other configuration can only be done after the sub-system is started.

3.1 Locating the observing system

Before starting the DAsS, the environment variable OBSSYS must define the location of the system on disk, e.g. /ing/s2.1. The directory ${OBSSYS}/bin must be in your path.

3.2 Setting the run number

A contiguous series of run numbers is used for each of the three telescopes: the numbers do not start from one for each new group of observers and are not set back to one when a new version of the DAsS is brought into use. The record of the last run-number used at each telescope is therefore recorded outside any observing system. It is absolutely vital that these files contain the correct numbers when observing starts; if the numbers are wrong then observations may be mis-filed and lost.

There are three files, INT.run, JKT.run and WHT.run, recording the last run-number to be allocated at the respective telescopes. They are kept in a directory etc that is in the same directory tree as the observing systems but not a part of any system. For example, if the observing systems /ing/s1.1 and /ing/s2.4 are on disk, the run-number files would be in /ing/etc. This arrangement is critical to the DAsS: its programs look for the run-number files in ${OBSSYS}/../etc when they start up. The files must be writeable by the program dasn. This generally means that the files must be writeable by any user.

Each file is one line of ASCII code containing the number followed by a new-line character. If the run-number file is lost for any reason, it can be recreated using a text editor. The last-used number can be recovered from the observation logs.

3.3 The set of tasks that must run

The DAsS can be run either on the system computer - local configuration - or in its own SPARCstation - remote configuration.

These programs must be continuously resident in the host for operation in local configuration:

S dasm, communicating as the task DASM;

S For each channel n in use, dasn, communicating as the task DASn;

S dasp, communicating as the task DASP;

S master.

For the remote configuration, dasm and dasn run on the remote machine and dasp and the clients run on the system computer. On each computer, there must also be the network agents:

S master;

S receiver;

S transmitter

3.4 Starting up: local configuration

The tasks can be run directly from the command line, or from a shell script:

master &
talker -n $TALKER
dasm $TELESCOPE &
dasp $TELESCOPE channel &

dasn $TELESCOPE channel &

The remote part of the sub-system is launched by the command dasload; the tasks on the system computer are run from the command line or from a script:

master &
talker -n TALKER-SYS
dasp $TELESCOPE channel &
dasload address

3.6 Choosing the channel

The DAsS is configured by channels where a channel is the data path to one CCD. The DAsS can operate up to eight channels, numbered 0 to 7, in parallel.

If you are have just started up a new version of the DAS for the first time, or if you are changing detectors, the system will probably have activated the wrong channel for the CCD you are using. You must select the right channel before going on. Give the command

daschoose c1 [c2 c3...]

where c1, c2 etc are channel numbers. You need one channel per CCD readout-point. Thus, `normal' single-CCD cameras use one channel each, CCDs that read out from two corners use two each and the INT mosaic camera uses four channels (one per CCD).

The daschoose command causes the DAS to be completely reset: all the instances of dasn are killed and a new set loaded. Hence, this command must not be used while any readout is active on the telescope. Not only will the data be lost, but if the system comes up part-way through a readout then the image-acquisition hardware may be swamped by the pixel stream before the software can get going.

Once the channels are chosen, all the remaining adjustments must be repeated for each chosen channel.

3.7 Matching to a CCD

A DAS channel is set up to match a particular CCD by setting the pixel headcode; setting the size and shape of the full-frame readout; defining where the bias and illuminated regions of the CCD are; defining the rotations and reflections to be made in recording the image.

The pixel headcode is an 8-bit integer prefixing each pixel value that identifies the CCD that produced the pixel. It is defined in the CCD controller by a combination of jumper settings and software settings.

The bias and illuminated regions are defined by

S the size of the basic CCD frame;

S the width of the x-underscan;

S the height of the y-underscan;

which together define a central illuminated rectangle surrounded by four bias rectangles (some of the possible bias-rectangles may end up with no pixels; e.g. the y-underscan in a TEK frame).

The rotations and reflections are applied to bring the output image into the most-convenient orientation. For spectrographs this will give wavelength increasing to the right; for multiple-chip imagers like the WFC it will bring all the images into the same orientation. The transformation string is the only line in the profile that is likely to change if a detector is moved between foci (it's more a feature of the instrument than of the CCD).

All the necessary settings are listed in the CCD's profile file as described in reference 7. They can be downloaded to the DAsS by running the dasprofile client for the CCD in question. The client requires you to set the environment variable SCCD_PROFILE to show the path to the directory where the profiles are kept. For example, to set up for using TEK3:

setenv SCCD_PROFILE /ing/ccd_profiles

dasprofile TEK3

(The name of the CCD is case-sensitive because it is expanded to the name of a file in the profiles directory.)

The same settings can be made without a profile file by invoking the HEADCODE and FORMAT actions on the appropriate DAsS server; parameters of the same name show the current settings. See reference 1 for details.

3.8 Setting the packet list

The DAsS must be told which packets of FITS header-data to collect and where to get them from: this information usually needs to be reset at each instrument or detector change. The command daspackets runs a graphical program that guides the selection of packets.

daspackets instrument

To enable collection of a packet, press the selector button at the left-hand end of the row describing the packet. All packets are selected in daspackets by default. Please note that if a packet is selected in the graphics display, this does not necessarily mean that the system knows to collect that packet: daspackets does not read back the set of packets known to dasp and dasn when creating the display.

The details of each packet are shown in text-entry fields. You should check these fields for each selected packet and correct as necessary. It is an error to leave any of the fields blank: this will prevent the DAsS from completing any runs.

The names in the Packet: field can be changed, but you only need to do this if you are experimenting with new packets.

The For: field indicates which task will be asked to incorporate the packet in its FITS header. The entry here must all be DASn where n is the number of the channel you are setting up.

The From: field shows the name of the task that will be asked, by dasp to generate the packet. When the field is set to given, it means that the packet is generated internally by the DAsS. When the field is set to copy (for WFC and other multi-channel instruments), it means that the packet will copied from one collected for another channel; there should be exactly one channel in the set collecting packets and the rest should be copying them. Where this field contains an actual task-name, the name should include the network address. If the task name does not match a task in the observing system (or if the network address is wrong) then the packet will not be present in the FITS headers. This does not stop the DAsS from completing runs but does slow it down slightly.

The Lines: field shows the number of FITS descriptors expected in the packet. The number of descriptors is specified in reference 5. It is a fatal error for the sum of the Lines: fields for all packets to be less than the total size of the packets collected: this causes the FITS files to be corrupted. It is not damaging to specify too many lines in daspackets, but it does waste space in the FITS headers.

The Channel: field has two uses. For packets collected from tasks, it is passed to those tasks in the packet request. For copied packets, the number indicates which channel the packets should be copied from. If you are configuring one channel, set the Channel: field to that number. If you are configuring for a multi-channel instrument, set all the Channel: field to the lowest channel-number in the set and make sure that the designated channel is collecting packets and not copying them.

Pushing the Apply button downloads the packet-list to the DAsS servers. If you notice a mistake in the selection after downloading, you can correct it and download a new list without restarting daspackets. Pushing the Exit button terminates the program without downloading a list.

After using daspackets, the DAsS must be restarted to force it to pick up the new packet list. In particular, if DASP is not restarted, different parts of the sub-system will be using different lists and runs will probably hang. The restart must occur before the first run is attempted but need not be done before the rest of the configuration.

The packet list can also be set by invoking the action PACKETS on the appropriate DAsS server; a parameter of the same name shows the current list. See reference 1 for details.

3.9 Setting the data-directory

Each DAS channel must be told where to record data; it is possible to route the data from each channel to a different directory but more normal to feed all the active channels to one directory. Any directory may be used for which the observer will have read, write and execute permissions.

When told a directory to work in, the DAsS server creates in that directory a sub-directory named for the date (and changes this directory to the new day's date at noon UT). All observation files are created in the sub-directory.

To set the directory, use the command

obsdata d

where d is the full path-name of the directory excluding the date-specific part. The directory name may not contain any wild-card characters or references to environment or shell variables. This command sets the directory for all active channels.

The data directory may also be set by invoking the action OBSDATA on the appropriate DASn server; the parameter of the same name list the current directory including the date-specific part of the path. See reference 1 for details.

3.10 Setting the readout format

This section, which was an essential part of the set-up procedure in previous versions, is retained only for completeness. The operations here still work but the setting up of the initial format is now normally done by dasprofile.

The readout format describes how the DAS should reconstruct the image on a channel, taking account of CCD size, windows and binning. The format also allows for rotation and reflection of the image relative to the geometry of the CCD.

In general, observers will set the format by running client programs that are outside the scope of the DAsS package: it is necessary to set equivalent formats in the DAsS and the CCDC. Engineers can set the DAsS format independently using the dasformat command:

dasformat [-c ccd-size -b binning -w enabled -1 window -2 window -3 window -4 window -t transformation -p -r -d] channel

where channel is the channel number. If none of the options are invoked the effect is to set the format to default values:

CCD size defaults to 100:100;

binning factors default to 1:1;

windowing defaults to disabled;

transformation defaults to no transformation;

the windows default to 0:0:0:0.

The -p (`read parameter') option avoids the defaults and initializes the new format to the values currently set on the DAS channel.

Most of the options alter an aspect of the format:

-c sets a new CCD size. The size of the un-windowed, un-binned image is given in pixels in the format x:y, e.g 1180:1280.

-b sets binning factors. The x and y factors are given in the format x:y, e.g. 2:4.

-w enables or disables windowing. Its argument is 1 to enable windowing and 0 to disable.

-1 sets window 1. The argument is in the format x-size:y-size:x-origin:y-origin, e.g. 100:1280:500:0 and the sizes and origins are measured in unbinned pixels. The leftmost column and bottom row are numbered 0: in the example above, the window spans the full height of the CCD.

-2 sets window 2 with the same syntax as -1.

-3 sets window 3 with the same syntax as -1.

-4 sets window 4 with the same syntax as -1.

-t sets the geometric transformation. The argument is a quoted string in which each character specifies a transformation: `x' is a reflection in the x axis, `y' a reflection in the y axis, `+' a rotation by +90 degrees (i.e. anti-clockwise) and `-' a rotation by -90 degrees (i.e. clockwise). The transformations are applied in order from left to right.

The -r option causes dasformat to read back and report to the terminal the format that it has set. Using -p and -r with no other options reprocesses and reports the format that was set at the start of the command.

The -d option instructs the DAS to dump to the terminal its array of `readout strips'; see [2]. This array is an internal representation of the format and can be inspected to check the format processing. It is no use whatsoever during observing.

It is important to remember that the dasformat command does not change the readout format in the CCDC.

The current format can also be listed to the terminal using the command

csh> cmd -g DASn FORMAT

which will show the positions of the windows in the output image as well as their position on the original CCD frame (dasformat -r doesn't show this). It is not possible to set a format using cmd.

3.11 Resetting

It is only necessary to reset the DAS to clear errors. The commands described above take effect from the next readout on the channel(s) concerned and do not need a reset to become effective.

To reset all channels at once, and also to reset the image-acquisition hardware, use the command dasreset. This should take around five seconds per active channel. As with daschoose, this command must not be used when any readout is active on the telescope for which the data must be saved. It is reasonable to use dasreset to end a failed readout (it does not actually stop the CCDC reading out; no software can do that), but it may be necessary to repeat dasreset once the pixel-stream has stopped. You can tell if pixels are still arriving by watching the green data-indicators on the FOX rack.

The sub-system can also be reset by running dasload as described above. For the remote configuration, this is a more complete reset; it takes longer than dasreset and is noisier but it may be more reliable.

dascontact establishes or checks DRAMA communications with the remote sub-system. It is run by dasload, and you can run it explicitly to check that remote tasks are still on-line. dascontact tries to talk to all eight possible DASn, including the ones not configured by daschoose, so it will usually show some tasks not responding.

3.12 Closing down

To close down the DAS, tell the main server-program to exit:

cmd DASM EXIT

Then shut down DASP explicitly:

cmd DASP EXIT

This works for both remote and local configurations.

3.13 Checklist for configuration

S Define OBSSYS.

S Check the run-number file.

S Start the sub-system

S Run daschoose.

S Run dasprofile.

S Run daspackets.

S Run obsdata.

S Restart to pick up the new packet list.

4 Control settings: their persistence and validity

The DAS has control settings which it remembers from night to night: the settings are recorded in the files DASn.settings (n = 0..7) and DASM.settings. The former files specify the data directory, pixel headcode, header-packet list and readout format for channels 0..7; the latter lists the set of active channels. The settings files live in ${OBSSYS}/etc.

When a version of the DAS is installed, it has no settings files.

; the system creates default files as it starts up. The default DASM.settings records no channels as active. The other settings files have a validity flag for each item which is set false when the files are created.

The validity flags may be read from the DAS' parameter set; to check validity on channel n use:

csh> cmd -g DASn READY

which returns a boolean flag (1 = true, 0 = false) for the validity of each control setting. The flag READY.run does not refer to a control setting but indicates whether the channel is armed to receive image data from the CCDC. If any ready flags, except READY.run, are false, the channel is not able to record observations. Making a valid control-setting, as described above, changes the associated flag to true.

The settings files are binary. DASM.settings is in SDS format and can be read by the utility sdslist from the directory $SDS_LIB. DASn.settings cannot be read except by dasn. It is sometimes possible for observers to preserve their settings files between observing runs: this allows them to recreate formats exactly. However, the settings files are not necessarily compatible between versions of the DAS. Using an incompatible version of a settings file may cause very odd failures.

The settings files must be writable by the programs dasn and dasm. This generally means that the files must be writeable by any user.

5 What may observers change?

In general, visiting observers should be encouraged not to change the DAsS configuration. At the time that the telescope is first handed over to the observers, the configuration should be complete and consistent with the rest of the observing system. Any of the run-like commands in reference 3 should function as listed.

Observers will typically want to adjust windows and binning factors. The observing commands for this are listed in reference 3. Observers should not use the dasformat command.

The obsdata command (see section 3.9) is appropriate if observers need to change to another data directory.

If the DAsS breaks down for any reason, the observers should be encouraged to use dasreset in preference to restarting the entire observing system. Restarting just the DAsS is much quicker than a global restart.

6 Monitoring acquisitions

6.1 Watching the progress of a run

The parameter RUN in DASn reports the progress of a run and is updated as data are acquired. You can get the current value of this parameter with the command

csh> cmd -g DASn RUN

or monitor the progress continually with

csh> cmd -p DASn START RUN &

(the latter command is a poor man's mimic-system). Here is a typical view of the parameter:

ArgStructure         Struct
  RUN                  Struct
    run                  Uint   2030
    readout              Ushort 12
    header               Ushort 100
    validFits            Int    1
    fileReleased         Int    0
    imageStart           Uint   8640
    fileName             Char   [256] "/obsdata1/DAS0.fit..."
    disposal             Char   [16] "Archive"
    foxThread            Int    5
    imgThread            Int    6
    hdrThread            Int    0
    foxStatus            Uint   0
    imgStatus            Uint   0
    hdrStatus            Uint   0

Watching the parameter READY in DASn indicates when the channel is ready to receive pixels: pixels will be recorded while READY.run shows true and will be thrown away at all other times.

6.2 Archive, scratch and glance runs

The DAS distinguishes three classes of acquisitions. Archive runs are destined for the FITS tapes, observation log and, ultimately, the La Palma archive. Scratch runs are temporary data, recorded to allow off-line checks of the observing system. Glance runs are temporary data that survive only long enough to be examined in the image display.

All runs start off as glance runs; the DAsS saves all incoming data to disk in the files DASn.fit (n = 0..7). At the end of archive runs, DASn.fit is renamed to rn.fit where n is the run number. At the end of scratch runs, the file is renamed to sn.fit where n is some number specified by the user. At the end of glance runs there is no renaming; the next run over-writes the previous glance.

6.3 Checking disk-space

The DAsS server check disk-space before starting each run. If there is space for 15 or fewer frames at the current frame-size then an alarm is raised but the run goes ahead. If the isn't space for one frame then the run is aborted.

You can check the space yourself using the command

csh> cmd -g DASn OBSDATA

to extract the name of the directory and

csh> df -k directory

to report the available space in kilobytes. Note that this report refers to the disk partition holding the directory. It is quite possible to run the DAS with eight different data-directories depleting space from one partition. In the general case it is not possible to predict accurately the number of runs that can safely be made on a particular channel.

7 Potential problems

This section lists a selection of problems that may occur in service, concentrating on the more subtle failures.

`IMP master task is not running' - message received while starting or resetting the DAS. Because the master task isn't running, DASM can't load DASn. See section 3.4.

`Cannot register DAS0: task name already in use' - message while loading or resetting the DAS. (This message can refer to any DASn or to DASM.) Another program has allocated the name by which your program wants to log into the DRAMA message net: the names are exclusive. Either the DAS was already running or one of the programs failed to close down last time it was stopped. You can usually kill the rogue program with

csh> cmd program EXIT

where program is the name that you need to reuse in the message net. If this doesn't work the rogue program may be hung; get its process number from ps and kill it as you would any other Unix command. (NB: don't use kill -9 for this; the program must be given a chance to run its exit handlers or it won't log out of the message net.) If the program isn't running you can clear its mortal remains with the command cleanup. Be warned: this command will remove every DRAMA task in the observing system.

`I can't open /dev/rgofoxnn: device busy' - message received while starting or resetting the DAS. This file is the Unix access-point to the image-acquisition device; the nn in the file-name is the channel number affected. These devices only allow one program to use them at a time and someone else got there first. Presumably, the interfering program isn't an instance of DASn or you'd have seen the `can't register; name already in use message' (see above) instead. Someone is running an engineering program on your channel; take a blunt instrument and go reason with them. Running dasreset may clear the problem.

`Failed to connect to task TALKER' (message from DASM or DASn). This means that the server in question cannot see a talker program to display its textual messages. Instead, any messages will be written to the terminal from which DASM was started. This situation can occur either because the talker program isn't running or because the environment variable TALKER wasn't set to the name of the talker when the DAS was started. Once you've fixed this, you need to shut down the DAS entirely and then restart it; dasreset isn't enough as it doesn't restart DASM.

`Window n will not fit on the CCD' - message from dasformat or other format-setting command. Well, should it fit? Remember that there is a row zero and a column zero. A window set to 50:1124:100:1 on a 1124-square CCD would start at the second row and would extend one row beyond the top of the CCD. Window origins equal to one are usually mistakes.

CCDC completes its readout but the run doesn't finish; 0% < RUN.header < 100%. The channel is probably waiting for a header packet to become available: this can happen because the packet list is corrupt or possibly because the DRAMA message-net has been disrupted at a critical point. In general, unless the channel is hung on a packet whose associated task is set to given or copy, the hang is only temporary; the system should recover within 15 seconds. If the channel is still hung this way after a minute, consider abandoning the run and restarting the DAS with dasreset. Check also to see if all the tasks named in the packet list are still responding.

Readout completes but DASn is hung; RUN.readout does not go to 100%. A pixel may have been lost in the FOX rack or Data-Cell interface. Wait to see if the run times out and reports lost data. If it doesn't time out within 30 seconds, assume that there is a software defect in DASn and run dasreset.

CCDC reads out but RUN.readout remains at zero. Check that the data light comes on on the FOX receiver board. If so, the pixels have arrived but have been ignored; your observation is lost. Check the parameter READY.run; if it's false the pixel-stream was sent when the DAsS wasn't ready, which is some kind of fault in the client program executing the run. Otherwise, go to the computer in which the FOX interface is mounted and check for messages on its console window. If you see `Unexpected data on unmapped channel x' you can assume that someone has set the wrong headcode for the channel. See section 3.7 for the solution.

Data in the output images do not not match the known orientation of the CCD. Check the transformation in your image format (see section 3.10). Particular care is needed with reflections in spectroscopic images. Perhaps you should take and check an arc frame at hand-over time?