JKT-DAS-2

JKT DAS s2.2j Transfer Document

Issue 1.1; 19 June 1997

Isaac Newton Group,
Apartado de Correos 321,
38780 Santa Cruz de La Palma,
Spain
Telephone (int+) 34 22 425423
Fax (int+) 34 33 425401
Email rje@ing.iac.es
Internet http://www.ing.iac.es/~rje/mydoc.html

1 Introduction

The Data Acquisitions system (DAS) for the JKT consists of a number of software servers and clients as well as hardware elements that integrate into a complete observing system. This document descibes the requirements of the host computer and the recipe for building and installing the complete system. It is intended to be used by engineers carrying out a system release.

The document does not have detail about the operation and configuration of individual server. These can be found in the detailed design document for each server individually.

This document describes the first ever build of the observing system at the JKT on lpss10. The system was based on the INT observing system version s2.2 and has been called on the JKT version s2.2j.

1.2 Scope and Overview

This document records how the JKT observing system was set up and configured during March 1997. Where possible I have included information not strictly relevant to the observing system but which is necessary to create a working system such as operating system installation and modification. In addition I have added as appendicies information on installing the important additional packages and examples of login files. Hopefully after reading this document the reader will have all the pointers necessary to either re-create an observing system or maintain and modify it.

1.3 References

[1] Interfaces to the Science CCD Server
ING/RGO document INS-CCD-7 (was INS-CCD-5)

[2] Software Requirements for the Data Acquisition Server
ING/RGO document INS-DAS-8

[3] User Manual for the Sparc based Data Acquisition System
ING/RGO document INS-DAS-11

[4] Technical User's Guide to the Unix Based Data Acquisition System
ING/RGO document INS-DAS-13

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

[6] Congiguration Management Standards for ING Observing Systems
ING/RGO document SOF-STD-3

[7] Acceptance Test Plan for the Sparc based DAS
ING/RGO document INS-TEST-1

There are also many more detailed documents which can be found in the ING/RGO document library (mostly these documents are in interleaf format) or usually there are copies on the web.

2 System Configuration

The CCD connects to a phase 2 CCD controller which is connected via two serial RS232 links (network and engineering) to lpss10 the host sparc via a Sbus 8 serial channel expansion card (magma). The CCD data comes via a fibre link to a Fox rack which fifos the data and transfers it across a parrellel link (via a grey plastic box) to a datacell card which is an Sbus card that puts the CCD data (finally) into the host computer's memory. The host connects to the Perkin Elmer ICS via ethernet and collects fits header information via a socket based transfer program. There is no connection to the PE TCS as the telescope header information arrives via the IPL to the PE ICS.

The data reduction and other computational tasks (eg netscape) must be run on a second computer currently this is a SunOS Sun IPX (lpss6).

2.1 Host Sparc

Services: Operating system (solaris 2.5.1 or later), NTP,

Currently using a Sparc5 with 128MB memory (lpss10)

The observing system requires data directories and scratch directories for the observers to put in their original FITs files and reduced data. On lpss10 for example these should be at:

/obsdata/lpss10a

/obsdata/lpss10b ... etc

/scratch/lpss10a

/scratch/lpss10b ... etc

The obsdata partitions are exported and visiable on lpss6 as /obsdata/jkta and /obsdata/jktb. The sparc lpss10 nfs mounts the observing system source from lpss12 as /ing/src, it also gets its compilers and licences from lpss12 as /opt/SUNWspro.

In addition an observing account (observer) and guest and duty tech accounts are needed all in the same group. The telescope software development account is ing. Group privileges need to be set up.

The following software packages are necessary for observing:

X11R6

perl v5.001m

magma serial port driver (3.1.3)

datacell fox driver (4-7-96)

fits file utilities (from /ing/src/tools/SCCS/s.fits.bom)

The following software packages are handy to have (usually on the data reduction sparc):

starlink release

iraf and display tool

xemacs and emacs

ghostview

netscape

xview

The following software packages are necessary to build the software:

Tk v4.0

Tcl v7.4

drama 0.5

Sunpro C compiler (version 4.0 was used)

Sunpro F77 compiler (fits utilities only - any version)

Files that need modifying (or at least checking) on the host:

/etc/remote (to add in the CCD controller reference)

/etc/auto_master

/etc/auto_direct

/etc/auto_scratch

/etc/auto_home

/etc/system (for drama)

/etc/devlinks.tab (for magma and datacell)

/var/spool/cron/crontabs/* (to check for midnight jobs - which are not a good idea)

Partitions:

/opt all the usual stuff here (mainly Sun)

/soft third party (non Sun) software

/ing ING software collection

In the directory /soft/audio_sounds all the audioplayer sound files have been placed. A script which beeps the monitor called beep is placed in /ing/tools/bin.

The disk sizes and mounts and extracts from some of the control files above are given in Appendix C.

2.2 DataCell interface card

The DataCell card provides an interface between the Sparc (SBus) and the Fox rack. This interface is 24 bit parellel with hardware handshaking. Coming out of the DataCell card is a double ribbon cable. This plugs into an interface box (labelled "TCubed") and a single ribbon cable goes from this box to the Fox rack.

To insert the card, power down the Sparc, leaving the mains lead connected. Open the Sparc, and attatch an anti-static wrist strap onto the power suppy casing. Remove one of the external SBus slot covers, and insert the card. Ensure the card is pushed down well onto the SBus connector. If necessary screw the front panel of the DataCell card to the Sparc chassis.

To add the driver execute the following instructions

1) Create a directory and tar the [floppy] disk [on which the driver was delivered to RGO] into the directory /soft/fox-datacell. It is best to request the latest version from RGO.

2) Switch to SuperUser.

3) Edit the devlink.tab file which is found in the /etc directory and insert the following two lines to the end of the file:

type=ddi_pseudo;name=sbusbib<tab>snapper\N0
type=ddi_pseudo;name=rgofox<tab>\M0

4) Run the install script which came off the disk. (/soft/fox-datacell/install)

5) Reboot the machine.

The release notes are in appendix A.

With the current release of driver, if the system needs to be rebooted, it must first be powered down. This seems to cause the DataCell card to get reset correctly.

2.3 Magma serial port card

This SBus card can be used to provide 8 extra local serial ports (RS232) to the Sparc. These appear as RJ45 connectors in a box at the back of the Sparc. Connectors are available to convert between RJ45 type and stanard 25 pin D-type. This route should be used if it is preferred to use a physical link, that bypasses the ethernet.

The card fits into a single slot on the Sparc motherboard. Follow the installation instructions that come with the board. Remember to use static protection. Once the system is re-assembled, the connection box should be attatched to allow access to the serial ports.

Follow the manufacturers instructions for installing the driver required to operate the card (See the manual but basically a good old pkgadd -d). This will install some links into /dev/term that link to the ports on the card. They will be numbers 0 to 7. It also modifies the /etc/devlinks.tab file which forces you to do a boot -r to rebuild the device links table.

Currently the installed version is 3.1.3 and has been installed into /opt/MAGMA_Sp. However this does not support solaris 2.5.1! So an updated version is available on Andromeda in /opt/MAGMA_Sp_4.1.1 . Magma technical support is at http://www.magma.com/support.htm.

2.4 Installing Drama

Drama is relatively painless to install once you have the correct tar file. The installation notes are given in appendix B. The tar file is lpss10:/soft/drama/drama-v0.5-lpss12.tar.Z (the lpss12 reference means that the original source was that installed on lpss12 not got from RGO or AAO). Drama requires the following additions to the /etc/system file:

set semsys:seminfo_semmni=50
set semsys:seminfo_semmns=200
set shmsys:shminfo_shmmni=200
set shmsys:shminfo_shmseg=50

There is a drama mail exploder which can be subscribed to by emailing mptalk-request@aaoepp.aao.gov.au with the line subscribe in the message. To unsubscribe email majordomo@aaossz.aao.gov.au with the line unsubscribe imptalk your_e_name@your.fully.qualified.address in the message.

Drama is only necessary at build time any components required during operation are copied into the observing system's bin directory, which ensures that the drama components in use are the ones that the observing system was built with.

2.5 Installing the fits Utilities

The fits utilities are a collection of programs that are used to read and write fits files to tape on the ING sparcs. The programs are:

fitsinit - used to initialise a new tape before writing to it. Creates a tape header which is an empty fits header. Also defines the tape as a D-tape or a C-tape.

fitsout - used to write fits files from the observing directory to tape.

fitsin - used to read the files off tape.

fitsenviron - used to set up the environment variables for using the fits utilities, needs to be localised for the sparc and is usually sourced by the login files.

fitsnc - fits name change - converted new style names (eg r123.fit) to old style names (eg r000123.fit) - now redundant

The fits utilities are atored in sccs and the library is in lpss12:/ing/src/tools/SCCS. It has a bill of materials file fits.bom. The version currently in use is 1.4, however there is not any linkage between the version of the observing system and the fits utilities version.

To build the fits utilities login as your favourite user and:

> setenv PROJECTDIR /ing/src/tools
> setenv ING /ing
> sccs get -r1.4 fits.bom
> bom fits.bom
> make -f fits.mk install

2.6 Auto Boot

The sparcs should be configured to autoboot on power up - to query to value type

> eeprom auto-boot\?

> eeprom auto-boot\?=true

For building the software there is a general account called ing which owns the /ing tree. If you want your personnal account to be used for building you must be in the same group as user ing. ing must be set up with read write access to lpss12:/ing and requires the same group and uid to do this. (NB the solaris cluster name is intsm for this account, and will be jktsm for the jkt)

For general use there are three accounts:

observer For running the observing system

jkt_guest In case the data reduction sparc goes down this account can be used

jkt_dt Duty tech account for data reduction

These files are populated with a set of generic login and startup files which are stored in /ing/tools/account_files. These files should be generic and capable of use without modification for any of the above accounts. A .tcshrc.observer file is provided for observers own changes. Note that to prevent mis-understandings only the observer account when logged into the console can start the observing system. (When the solaris ORM cluster arrives at the JKT the observer account will be jktobs) Copies of some of these files are in Appendix D.

Finally you need to set up iraf for the accounts which is done by logging in, going to the home directory and typing mkiraf. The questions are fairly obvious, but ensure you select xgterm.

2.8 On Line Help

There are two sources of on line help; namely a web based help facility and a startup message at the begining of the observing system startup. The startup message is held in /ing/etc/motd and the web pages are found at http://www.ing.iac.es/Onhelp/JKThelp.html.

In addition it is often left to the observing system installer to maintain the log on message of the day in /etc/motd.

2.9 Phase 1 CCD Controller Software Support

For the operation of the phase 1 CCD controller using ADAM on the ICS for CCD control there is a socket based program to transfer the fits files to lpss10 called peserver which is in /ing/tools/bin. The source files are in /ing/tools/bin/perkin.

Hopefully this will never be needed.

3 Observing System Overview

3.1 /ing

Beneath /ing we have the following directories:

src Contains the SCCS directory containing the masters for the sccs history files for all files required in building the observing system. This is exported from lpss12. The sources apply to all telescopes and instruments.

src/SCCS Histroy files for sccs.

tools/bin Contains useful executables for the use of the observing system, that are not part of a release. This includes the fits routines, some drama utilities, and some others.

src/tools/SCCS SCCS history files for any of the above tools that require building.

src/ccd_profiles/SCCS SCCS history files for the CCD definition files

etc Location of all the nightly logs files. Location of the JKT.run file showing the last used run number. Also used as a store for local settings files and the temporary files for header collection.

bin Location of obssys-3.csh (and derivatives). Nothing else is stored here.

ccd_profiles Data files describing the characteristics of each of the CCDs in use.

hdr_templates Contains the header templates used with the header collection facility. The source files are held in /ing/src/SCCS.

p'n' The patch directories, containing

bin with the executables

etc with plain text file "patch.description" describing the effect of the patch.

s'n.n' The release directories, outlined below.

3.2 Contents of release directory

A release directory should consist of a dirctory name s`n.n' where `n.n' is the release number, with the following subdirectories (and no others):

bin Contains all the system executables and links

etc Used as a store for the DAS settings files, and the FITs header packets during a run.

inc Can be used to store system wide header files

lib Used to store system wide libraries. Currently only the libcia.

All except etc should have the unix privileges 775. However since the user will be writing the FITs headers temporarily into the etc sub-directory, this should be world read-writeable (777).

3.3 Other Files

The profile files that describe the characteristics of all the CCDs are stored in the /ing/ccd_profiles directory. This is pointed to by the SCCD_PROFILES environment variable. The ccd profiles are listed in reference [1]. Note that the CCD profiles contain the latest noise and gain figures as placed in the FITS headers and that this information should be updated reqularly (although there is no formal method for this). CCD profiles are stored in sccs.

The header templates used with the header collection facility are located in /ing/hdr_templates, pointed to by the environment variable HDR_TEMPLATES.

The local settings files in /ing/etc are created by the applications as required. The run number file JKT.run holds a string containing the last run number used. This file is used by all versions of the operating system and should not be reset at any time. If it is corrupted or lost it can be recreated by editing the file and placing the last used run number in it.

The bom utility must be extracted from the sccs library /ing/src/SCCS and placed in /ing/tools/bin.

3.4 Reconfiguring Observing System

To modify the serial port that any server operates on, the parameter provided to it when it starts up needs to be changed. This is found in the startobssys script which entails releasing a new patch.

The DAS channel that any CCD should use is defined in the CCD profile file. If this is changed the whole observing system should be re-started. More commonly the CCD controller headcode or network name (eg CCD7) does not match that found in the CCD profile. In general it is best to have the CCD controller changed as those found in the CCD profile are usually the defaults established over time.

The DITs name that some servers and scripts register with can be set. This should be modified in the startobssys script to be permenent (another patch level).

3.5 Differences From the INT System s2.2

The base line for this system was the INT observing system version s2.2 with patches 1 and 3. However a number of modifications where made to accomodate the JKT. These are usually noticable as they are sccs branches eg have versions such as 1.9.2.1.

The file jkt_pe.hdr_template is new and provides the filter list for the header items from the JKT ICS Perkin Elmer computer.

The sccd_clients package is at version 1.9.2.1. Essentially 1.9 was used by INT s2.2 (PE ICS) and 1.10 was used by the INT s2.1 which included the unix IDS/AGB ICS. The two files that are for the unix ICS only are clientRunCCD.c and clientSetup.c. Version 1.9.1.1 of the package was an attempt to use libcia 7.3 and drama 0.6 which is now redundant.

Version 1.9.2.1 of sccd_clients is based on v1.9 with patch 3 changes (as used in v1.10) that are not unix ICS specific (ie clientRunKickCCD.c and clientSettings.c) plus some specific JKT changes to clientRunCCD.c (at version 1.30.2.2) so it collects the headers from jktpe.

The log facility is at version 1.6.1.1 and basically has the changes for the log display column headings in it.

The other JKT specific file is startobssys at v1.11.1.6 which required a number of changes from the original v1.11 used on the INT.

3.6 RBS

The observing system is basically set up for the JAG, however the RBS can be used. The RBS does not have any FITS headers associated with it and the image fits file will contain blank JAG header items. Apart from that the CCD controller needs to be set up for a compur shutter (an electronics problem).

4 Observing System Installation

It is assumed that the sparc has been set up as in section 2 with the correct interfaces, drivers, drama and support software, etc. The ing source sccs library nedds to have been automounted to appear at /ing/src/SCCS.

The following tools then need to be extracted from the library and placed in /ing/tools/bin:

bom
cmd
make-release-dirs.csh
make-patch-dirs.csh

4.2 Installation

To set up the system ready to start the build:

1. Log in as user "ing" and clean out or create an empty working directory and ensure /ing/tools/bin is in your path.

Create a shell script for starting up the system called defsys2.2 which contains:

setenv ING /ing

setenv OBSSYS /ing/s2.2j

setenv PROJECTDIR /ing/src

/soft/drama/v0.5/dramastart

and place it ~ing/bin and make it executable. (This is not necessary but handy for preventing mistakes)

2. Create a new release directory structure. eg for s2.2j:

mkdir /ing/s2.2j

mkdir /ing/s2.2j/bin /ing/s2.2j/etc

mkdir /ing/s2.2j/lib /ing/s2.2j/inc

This point and the one below can be done quickly by the command:

make-release-dirs s2.2j

3. Change permissions of these dirctories to bin:775 etc:777 inc:775 lib:775

4. Run the script ~ing/bin/defsys2.2 which starts drama.

For each of the components with BOM scripts:

5. Indicate to SCCS where to get the BOM from:

setenv PROJECTDIR /ing/src

6. Extract the BOM script: eg for v2.5 sccd.bom:

sccs get -r2.5 sccd.bom

7. Unset the PROJECTDIR environment variable to ensure source files are extracted with bom.

unsetenv PROJECTDIR

8. Make the executable, using bom. eg for sccd server:

bom sccd.bom

9. Install the executable, eg for sccd server:

make -f sccd.mk install

Note that the make file name is not always the same as the bom file name. Also not all the make files have the install target - if not simply copy the created executables to /ing/s2.2j/bin.

10. Cleanup the working driectory, eg for sccd server:

make -f sccd.mk clean

Not all the make files have the clean target - use rm -f * instead.

After this cycle is complete, the working directory should be empty. If it is not, remove all remaining files.

The following components have bom files at the stated release. They should be made in the order listed:

libcia.bom 6.3

sccd.bom 1.13

sccd_clients.bom 1.9.2.1 (ignore errors on install)

mon.bom 1.2

das.bom 3.2

talker.bom 4.4

log.bom 1.6.1.1

hdrPE 1.4

The rt program once copied to /ing/s2.2j/bin has to have its ownership changed. su yourself to the root user (stay in /ing/s2.2j/bin) and then:

chown root rt
chmod u+s rt

startobssys 1.11.1.6

shutdownobssys 1.5

obssys_check.csh 1.5 and chmod 555

ics.icon 1.1

The following file will need to be extracted from the main sccs library /ing/src/SCCS and moved to /ing/bin:

obssys-3.csh 1.2

The following file will need to be extracted from the main sccs library /ing/src/SCCS and moved to ~observer/.obsstation.csh :

obsstation.csh 1.2

You must populate /ing/ccd_profiles by extracting the latest versions of all the files in the library /ing/src/ccd_profiles/SCCS.

The following files will need to be extracted from the main sccs library /ing/src/SCCS and moved to /ing/hdr_templates:

jkt_pe.hdr_template 1.2

sccdHdr.BEGIN 1.1

sccdHdr.END 1.1

The following files will need to be copied from /soft/drama/v0.5/release/imp/r1_0/sun4_solaris to /ing/s2.2j/bin:

reciever

master

transmitter

The following file will need to be softlinked from /soft/drama/v0.5/release/imp/r1_0/sun4_solaris to /ing/tools/bin:

cleanup

Other files that can be softlinked from drama v0.5 to /ing/tools/bin are:

impdump impprobe sdslist sdsc

4.3 Before Using the Computer as an Observing System

These things only have to be done once per computer (unless something really corrupts it!).

Create the motd file eg

touch /ing/etc/motd

alias obssys source /ing/bin/obssys-3.csh

cat - > /ing/etc/JKT.run
0
^c
chmod 777 /ing/etc/JKT.run

Then start the observing system up (well partly) to configure the DAS for the detector, this needs to be done on each new observing system (or patch to the DAS I expect). Fuller details are given in reference [4].

Log in as observer and type :

obssys
setenv SCCD_PROFILE /ing/ccd_profiles
master &
dasm JKT &
daschoose 1
cmd DAS1 PACKETS "observation given 1 5" "sccd SCCDa 1 50" "ics given 
1 50"	[...this is all one line]
mkdir /obsdata/lpss10a/970326
chmod 777 /obsdata/lpss10a/970326
dasformat -c 1242:1152 1

4.5 Checks

First make certain you can ping the jktpe and lpss6. Check you can tip to the CCD controller (command is tip CCD).

Log in as observer and start the observing system as normal, setup the CCD and take a run (eg "run 7"). This checks a lot of the installation problems that have occurred in the past. Follow the instructions given in reference [3].

A full confidence test should include checking the headers in the FITs files, checking the data using iraf on lpss6 and making various runs, biases, etc including the use of abort, multrun and killmultrun. Check the CCD controller can be set to the various windows and clear/readout speeds.

A full test specification is given in reference [7].

5 Installation of a Patch

First you need an observing system to patch. Once you have that it is possible to generate patches using your own account and then test them with either user ing or observer.

One 'nasty' with the patch system is that currently the patch numbers refer to all system versions on a telescope, so it is NOT possible to have s2.2j patch 1 and s3.0j patch 1 (well it is but it will be the same patch and not very useful).

Once a patch has been fully tested and released it should be included in the start up options in /ing/bin/obssys-3.csh. This file is under sccs control and is generic to both the INT and JKT. Always include a startup option to fall back to the previous release without the new patch.

5.2 Installation

The make-patch-directories.csh utility does this:

mkdir /ing/xx
mkdir /ing/xx/etc
mkdir /ing/xx/bin
chmod 777 /ing/xx/etc

These notes are based on reference [6]. It is assumed that the observing system conforms to the guidelines in this document.

1. Complete the patch and its testing by ensuring that the bom is up to date and that all source files are checked back into the SCCS library.

2. Create a new patch directory in the observing system, imediately below $ING. Patch directories are called p# where # is the patch number. This can be achieved with the make-patch-directories.csh utility located in /ing/tools/bin. Example:

          >cd $ING
          >make-patch-directories.csh p7

          $ING/p7
          $ING/p7/bin
          $ING/p7/etc

4. Then build the module or modules (where x.y is the module version number required) - some of this will have been defined in ~ing/bin/defsys2.2 which can be sourced instead of the first 3 lines:

     >setenv $ING /ing
     >setenv PROJECTDIR $ING/src
     >/soft/drama/v0.z/dramastart
     >sccs get -rx.y module.bom
     >unsetenv PROJECTDIR
     >bom module.bom

     >setenv $OBSSYS /ing/p#
     >make -f module.mk install

7. If the patch is major and requires more complete documentation create a release note for it and place a copy in $ING/p#/etc and with the ING document manager (GTR).

8. If the patch will effect the observers add a note to the observing system message of the day file located at $ING/etc/motd. This file is displayed to obervers on starting up the system.

9. If it is a major patch or needs to involve the observer before starting the observing system get the system manager to modify the computers login message file located in /etc/motd.

10. Modify the observing system startup options file located in /ing/bin/obssys-3.csh. Note that this file is under SCCS control in $ING/src. Create a new start option for the patch number and leave the old start option for the system available - however identify the old startup as a fallback . eg before:

if( $TELESCOPE == 'INT') echo "8: WFC (s4.2 with no patches)"

if( $TELESCOPE == 'INT') echo "9: WFC (s4.2 with patch 7)"
if( $TELESCOPE == 'INT') echo "8: Previous WFC (s4.2 with no 
patches)"

11. Test it.

12. Advise the support astronomers, telescope operators and telescope software manager of the changes.

13. If the change will effect the way the system is maintained then inform the Duty Engineers and electronics groups.

14. Change the whiteboard in the control room to show the startup option number for tonight's system and the fallback option.

15. If there is new documentation ensure a copy is available in papaer form in the control room and available from the online web pages
http://www.ing.iac.es/Onhelp/INThelp.html. In the future this is where patches will be announced.

Appendix A. DataCell Card Fox Driver Installation Notes

Readme.txt file for rgofox driver, 4.7.96
-----------------------------------------

The driver has been altered so that it can now correctly acquire
any number if 16 bit pixels; the number of pixels acquired no
longer has to be a multiple of 1024 (i.e. 2048 bytes).

The acquiring of pixels is a real-time task. Therefore, the
driver must be run by the kernel with real-time scheduling, so that
there are no undue delays before the driver is able to respond
to the arrival of new pixels. When the rgofox driver is run, it is
scheduled by the kernel according to the scheduling parameters of
the user thread that called the driver. Thus, for the driver to
run at a high scheduling priority, the user thread must also
be run at a high scheduling priority. In order to change the
scheduling class of a thread from the normal time-sharing class to
the real-time class, the thread must be running with superuser
privileges. The example program foxread changes the scheduling
priority of the acquisition thread to be real-time, and so it
must be run with superuser privileges.

The foxread program also locks into memory the user's buffer.
This is done to help to reduce any delays when transferring pixel
data from the driver's buffer into the user's buffer. In order
to do this, once again the program must be run with superuser
privileges. However, it is not essential to lock the user's
buffer into memory.

The foxread program has various options that can be selected
on the command line, and also some compile time options. The
compile options control whether a second thread or process is
created in order to report the progress of the acquistion, as
well as how the data is displayed after acquistion - either all
the data can be displayed, or just any detected errors. It is
suggested that the program be run with the current compile
time options so that only errors are displayed, and a second
thread is used to report progress. If you wish to recompile
the program, the following command line is required:

cc -o foxread foxread.c -D_REENTRANT -lthread

If the program is run with the "-n" option for "no copy", then
the second thread will not only report the acquisition's
progress, but it will also copy the data from the driver's buffer
into the user's buffer whilest the acqusition is in progress.
This is done every time 1Mbyte of data has been acquired, and thus
the program could easily be altered to analsyse the data during
the acquistion. The current version of this example program
examines all the data at the end of the acquistion.
The second thread runs at the standard time-sharing scheduling
priority so that it does not interfere with the main real-time
thread that is controlling the acqusition.

The foxread program has been used to test the rgofox driver. Using
this program, it is possible to have two acquisitions going on
at the same time without interfering with eachother. These tests
have been done on a SPARC 2 machine, using the RGOFOX test equipment.
The tests were run as follows:

In one user shell,
Become superuser
foxread -n 3000000
Select commmand 1, and the default size to lock down driver memory
for the acquisition
Select command 2 in order to start the acquisition
Turn on the pixel generator

In a second user shell,
Become superuser
foxread -n -f /dev/rgofox01 3000000
Select commmand 1, and the default size to lock down driver memory
for the acquisition
Select command 2 in order to start the acquisition
Turn on the pixel generator

The above two acquistions of 3000000 bytes can be run at the same time.
No errors are reported on our system, acquiring pixels on both channels
0 and 1 at 4.5 microseconds per pixel. The acquisitions can be started
and stopped whilest another acquisition is in progress, with no adverse
effects.

Appendix B. Drama Installation Instructions

How to install DRAMA

====================

Installing a DRAMA version to support an observing system is a lengthy and cumbersome process with great potential for mistakes. The chance of guessing the install-and-build process from the supplied files is vanishingly small and AAO's documentation, while helpful, does not explain all the customizations needed to fit DRAMA for use at ING.On the positive side, no particularly arcane knowledge is needed and the list of thinks that have to be set up appears to be well understood. I believe the instructions below to be all you need to know.These sections show the necessary procedure:

1. Acquire supporting software.

2. Acquire the DRAMA release.

3. Install the source.

4. Set the local configuration for the Solaris build.

5. Build for solaris.

6. Set the local configuration for the VxWorks build.

7. Build for VxWorks.

1. Acquire supporting software

------------------------------

To build enough of DRAMA for ING purposes, you need the following packages. - SunSoft C compilation tools (v4 or later) or GCC for Solaris. The SunSoft product is preferred, because it is used in tests systems at RGO. On the other hand, DRAMA is routinely compiled with GCC at AAO. - VxWorks 5.1.1. (Other variants may be compatible but have not been tested.) This should be in /soft/vw/vw5.1 - GNU cross-compilation tools for VxWorks on MC68k. These must be in /soft/vw/gnu/solaris.68k. - Tcl v7.4 and Tk v4.0. No other versions will do: earlier versions don't have the required features and later versions aren't compatible with DRAMA (as of DRAMA 0.6). The Tcl/Tck libraries should be installed as libtcl7.4.a and libtk4.0.a in /usr/local/lib. The include files tcl.h and tk.h should go in /usr/local/include. (If you absolutely must install these packages elsewhere then DRAMA can be adapted to cope, but remember look out for inconsistencies when configuring the Solaris build.)Extra features are enabled if you also have these: -

SunSoft FORTRAN-77 compilation tools (v4 or later). - The Starlink software collection. This should be installed as /star. (Again, if you want to put it somewhere else you can but the DRAMA configuration must be changed to match.)There is no need for any of these: - EPICS. - SCCS, RCS or CVS. - PERL. - X11R6. - Motif.(No need, that is, when you build DRAMA. Applications within the observing system still need X11R6 and PERL.)

2. Acquire the DRAMA release

----------------------------

The current formal release of DRAMA may be copied by FTP from ftp://aaoepp.aao.gov.au/drama.dir/which is the AAO's base in Epping, on the outskirts of Sydney. Network linksto NSW are highly variable in performance since the Internet packets arerouted though North America. Downloading DRAMA while the USA is asleep is feasible; at other times the download will usually time out. An easier way to get DRAMA is to copy the relevant version from RGO; this also ensures that any patches found necessary in tests at RGO are already in place. Contact Guy Rixon at RGO to find out the current state of the installation. The RGO version of DRAMA can be tar'd up from Garkbit:/data/drama/vx.ywhere `x.y' is the version number. (Taking the entire /data/drama partition is unsafe; unpacking such a tar file at ING may overwrite existing versions of DRAMA needed for operation versions of the observing system.)

3. Install the source

---------------------

The DRAMA release should be installed at /soft/drama/vx.yThe DRAMA tree includes two main branches. The drama_source branch contains the supplied source-code divided into a number of sub-systems with their own directories. This branch is where the building takes place. The release branch contains directories for the same set of sub-systems as the source branch and these directories conatin files copied from the source/build directories as each sub-system is built. The sub-systems in the release branch each have a common directory holding include-files and, below that, a sub-directory for the libraries and executable files for each supported architecture. After DRAMA is build, all use of the software is through the release branch.If you have taken DRAMA from RGO then it probably includes the remnants of old builds. There are instructions for removing these in later sections. The version taken from RGO may also contain runnable builds of DRAMA in /soft/drama/release, but these are likely to be crippled by the different installation-pattern of supporting software. You really do need to rebuild DRAMA before any serious use of it.

4. Configure the Solaris build

------------------------------

DRAMA uses imake and a system of `dmakefiles' to allow it to be built for different architectures and different configurations of each architecture. You must adapt the build to suit your computer by editing the file /soft/drama/drama_source/config/sun_solaris.cfwhich uses the #define command of the C proe-processor to set various symbols.Ensure that you have to following definitions:

#define OSName SunOS 5.5

#define OSMajorVersion 5

#define OSMinorVersion 5

#define HasGcc NO

#define HasFortran YES

#define HasStarlink YES

#define HasMotif NO

#define HasTcl YES

#define HasTk YES

#define HasCPlusPlus NO(If you say you have GCC, then the DRAMA build will use it.

Saying you don't have it, even if it's actually installed, switches the build to use SunSoft C. Motif is not needed for the build and is best left out of the configuration.)

#define FortranLibs -L/opt/SUNWspro/SC4.0/lib -lF77 -lsunmath -lm

#define StarlinkDir /star

#define TclLib -L/usr/local/lib -R/usr/local/lib -ltcl -lm

#define TkLib -L/usr/openwin/lib -R/usr/openwin/lib -L/usr/local/lib -R/usr/local/lib -ltk4.0 -ltcl7.4 -lX11 -lm

#define TclTkIncl -I/usr/local/include -I/usr/openwin/include(Change these paths if you want to put Tcl/Tk somewhere non-standard.

The -R flag codes into the binarys that use Tcl/Tk the path for finding the libraries at run-time; this avoid the need to set LD_LIBRARY_PATH. Note that DRAMA is built with OpenWindows libraries, not with X11R6. Some of the definitions are split across lines here for legibility, but they must not be split in the configuration file.)

5. Build DRAMA for Solaris

--------------------------

Go to the directory /soft/drama/vx.y. If there is a chance that the DRAMA tree contains the residue of old builds, clean up with a `clean-only' build: drama_make -coNow build the release: drama_make -c This builds the various packages within DRAMA in the source directories under /soft/drama/vx.y/drama_source and copies the output into /soft/drama/vx.y/release. The -c flag causes the build to remove residues from the source directories after building, leaving the tree in the same state that it was in after the `clean-only' build.The build should take about five minutes on an unloaded SPARCstation 20, will produce vast amounts of output to the terminal and should end with the message `successful build of DRAMA'.

6. Configure the VxWorks build

------------------------------

This configuration is similar to that for Solaris except that there is more to set up.Edit the file /soft/drama/vx.y/drama_source/config/vw68k.cfand ensure that the following are set:#define Version_5_1

#if !defined(Version_020) && !defined(Version_030) && !defined(Version_040)

#define Version_030#define OSName VxWorks 5.1.1

#define OSMajorVersion 5

#define OSMinorVersion 1

#define HasStarlink NO

#define HasFortran NO

#define HasGcc YES

#define HasMotif NO

#define HasTcl NO

#define HasTk NO

#define HasCPlusPlus NO (You have to use GCC to build this DRAMA because SunSoft C doesn't include cross-compilation tools for the M68k processors.)

#define VxWorksBase /soft/vw/vw5.1

#define Host sun4_solaris

#define Xdev /soft/vw/gnu/solaris.68k

#define Vw /soft/vw/vw5.1

#define GccPrefix -B$(VWLIBPATH)/gcc-lib/

#define DefaultCCOptions -pipe -fvolatile -fstrength-reduce GccMOpt()

#define VwVer 5_1

7. Build DRAMA for VxWorks

--------------------------

Go to the directory /soft/drama/vx.y. If there is a chance that the DRAMA tree contains the residue of old builds, clean up with a `clean-only' build: drama_make -coNow build the release: drama_make -c -t vw68k(-t is for target). The build should take about five minutes on an unloaded SPARCstation 20, will produce vast amounts of output to the terminal and should end with the message `successful build of DRAMA'.

8. Elementary tests

-------------------

The DRAMA release includes some test programs which can be run very simply.Give the commands /soft/drama/vx.y/dramastart source $DRAMA/drama.cshto set up the developer's environment (I assume here that you are using the Unix C-shell).Run the server program ticker and the client program tocker:

ticker &

tocker

and you should see output like this:

TOCKER:connected to task TICKER

TOCKER:Total time for 100 ticks is 0.11s, Ave Time = 1.0780ms

TICKER:Total time for 100 ticks is 0.05s, Ave Time = 0.4890ms

which demonstates that the DRAMA message-net is working on the local host. It also exercises some parts of SDS.Give the command `cleanup' to remove the tasks: this shows that the IMP tools are runnable.Run tocker again without ticker: this should generate an error message (saying that rocker can't find ticker) which shows that ERS, the error-reporting system, is functioning.Run the DRAMA-enabled windowing shell, dtk. This should display a square blank window on your X server, showing that DRAMA and Tcl/Tk are properly integrated. (The window is blank because no ionstructions have been given to dtk to draw any widgets.) Kill this window with Cntrl-C at the terminal.

Appendix C. Extracts from Control Files on lpss10

This is the output from df -k:

Filesystem            kbytes    used   avail capacity  Mounted on
/dev/dsk/c0t3d0s0     104983   36507   57986    39%    /
/dev/dsk/c0t3d0s6     250303  183618   41655    82%    /usr
/proc                      0       0       0     0%    /proc
fd                         0       0       0     0%    /dev/fd
swap                  208016     372  207644     1%    /tmp
/dev/dsk/c0t1d0s7     981588  503796  379642    58%    /export/home/lpss10
/dev/dsk/c0t1d0s6     981588  793708   89730    90%    /export/scratch/lpss10a
/dev/dsk/c0t2d0s6    1963991  895156  872445    51%    /export/scratch/lpss10b
/dev/dsk/c0t4d0s0    4046399 3351787  289982    93%    /export/obsdata1
/dev/dsk/c0t4d0s6    4269773 3248708  594095    85%    /export/obsdata2
/dev/dsk/c0t0d0s0    1349387  982122  232335    81%    /star
/dev/dsk/c0t0d0s3    3853640 1231251 2237029    36%    /soft
/dev/dsk/c0t0d0s5    2016967  365213 1450064    21%    /export/install
/dev/dsk/c0t0d0s7     963869  173520  693969    21%    /opt
lpss12:/opt/old_SUNWspro  840408  507872  248496    68%    /opt/SUNWspro
/export/obsdata2     4269773 3248708  594095    85%    /obsdata/lpss10b
/export/obsdata1     4046399 3351787  289982    93%    /obsdata/lpss10a

# Master map for automounter
#
# auto_master map for INT Solaris `cluster';  master copy on lpss12
# v1.1 PSB 1997-01-15
#
+auto_master
/net		-hosts		-nosuid
/home		auto_home
/scratch	auto_scratch
/-		auto_direct
/xfn		-xfn

# auto_direct map for INT Solaris `cluster' 
# PSB 1996 Jan 15;   master copy on lpss12
# RJE 1997 Mar 5; removed most links to lpss12 ready for JKT move
#
/obsdata/lpss10a lpss10:/export/obsdata1
/obsdata/lpss10b lpss10:/export/obsdata2
/soft/ing/src	lpss12:/export/ing/src
/opt/SUNWspro	lpss12:/opt/old_SUNWspro

# Home directory map for automounter
#
+auto_home
#
# home entries for the INT Solaris `cluster';  PSB 1997-01-15:
psb		lpss12:/export/home/lpss12/&
mike		lpss12:/export/home/lpss12/&
jrl             lpss12:/export/home/lpss12/&

# auto_scratch map for INT Solaris `cluster'
# v1.1 PSB 1997-01-15  master copy on lpss12
# v1.2 RJE 1997-03-05  removed lpss12 clustering for move to JKT
#
lpss10a		lpss10:/export/scratch/&
lpss10b		lpss10:/export/scratch/&
#lpss12a		lpss12:/export/scratch/&
#lpss12b		lpss12:/export/scratch/&
#lpss13a		lpss13:/export/scratch/&

t0:\
        :dv=/dev/term/0:tc=hardwire:
t1:\
        :dv=/dev/term/1:tc=hardwire:
t2:\
        :dv=/dev/term/2:tc=hardwire:
t3:\
        :dv=/dev/term/3:tc=hardwire:
t4:\
        :dv=/dev/term/4:tc=hardwire:
t5:\
        :dv=/dev/term/5:tc=hardwire:
t6:\
        :dv=/dev/term/6:tc=hardwire:
t7:\
        :dv=/dev/term/7:tc=hardwire:CCDutil:\
        :dv=/dev/term/2:pa=none:tc=hardwire:
CCD:\
        :dv=/dev/term/3:pa=none:tc=hardwire:
meng:\
        :dv=/dev/term/3:pa=none:br#9600:tc=hardwire:

.login file:

# @(#)local.login 1.3     93/09/15 SMI
# Modified for INT observing-account 1996-01-09 by GTR.
# Modified for general use at the JKT by RJE 12/05/97

stty -istrip 
#setenv TERM `tset -Q -`

#
# Since this account is for observing, work out which
# observing station is in use (i.e. setenv TELESCOPE and OBSSTATION).
#
if ( "`/usr/ucb/whoami`" == "observer") then
	source .obsstation.csh
endif
set me = `/usr/ucb/whoami`
setenv LOGINNAME `/usr/bin/cat /etc/passwd | /usr/bin/grep ${me} | 
/usr/bin/awk -F: '{print $5}'`
unset me
setenv OW_WINDOW_MANAGER /export/home/lpss10/observer/bin/olvwm
#
# Set search paths.  These are absolute paths which should be set only 
once,
# at login, and not reset each time a shell is started (the latter 
course would
# stop the observing system from working).
set     sys_path =      (/usr/{bin,ucb,ccs/bin,sbin})
setenv  SYS_MAN         "/usr/man"

set     x11_path =      (/usr/openwin/bin)
setenv  X11_MAN         "/usr/openwin/man"

setenv  SFT_MAN        "/usr/local/man"
set     sft_path =     (/usr/local/bin)

set	tex_path =	()

setenv  COM_MAN         "/opt/SUNWspro/man"
set     com_path  =     (/opt/SUNWspro/bin)

#set     my_path =      (. /ing/bin /ing/tools/bin /star/local/bin 
/star/bin)
set     my_path =       (. /ing/bin /ing/tools/bin /star/local/bin)
setenv  MY_MAN          "/soft/drama/v0.5/man"

set 	path =  ($my_path $com_path $sys_path $x11_path 
$sft_path $tex_path)

setenv  MANPATH "${SYS_MAN}:${X11_MAN}:${SFT_MAN}:${COM_MAN}:${MY_MAN}"

setenv  LD_LIBRARY_PATH 
"/usr/lib:/usr/ucblib:/usr/local/lib:/usr/openwin/lib:/soft/X11R6/lib"
#setenv  LD_LIBRARY_PATH 
"/usr/lib:/usr/ucblib:/usr/local/lib:/usr/openwin/lib:/star/lib:/soft/X1
1R6/lib"

#
# set the location of the audio player sound files
#
setenv AUDIOPATH /soft/audio_sounds

#
# Determine where the X graphics should go.
#
source /star/etc/xdisplay

#
# If possible, start the windows system.  Give user a chance to bail out
#
if ( `tty` == "/dev/console" ) then

	if ( $TERM == "sun" || $TERM == "AT386" ) then

		if ( ${?OPENWINHOME} == 0 ) then	 
			setenv OPENWINHOME /usr/openwin
		endif   

		echo ""
		echo -n "Starting OpenWindows in 2 seconds (type 
Control-C to interrupt)"
		sleep 2
		echo ""
		$OPENWINHOME/bin/openwin
		clear	# get rid of annoying cursor rectangle
		logout	# logout after leaving windows system

	endif

endif

#
# Set the default file protections
#
umask 22
#
# Specify zero-size core dumps
#
limit coredumpsize 0

#
# Put the account name and host into the prompt.
#
set prompt = "`/usr/ucb/whoami`@%m%# "

#
# Some handy aliases to help life along
#
alias emacs xemacs
alias netscape echo "Please run netscape on lpss1 or lpss6 as running 
it on the observing system will corrupt your images\!"
#alias cl echo "Please run iraf on lpss13 \(either telnet or login to 
console\)"
alias starlink "source /star/etc/login; source /star/etc/cshrc"

#
#  Setup so that obssys command works
#
if ( "`/usr/ucb/whoami`" == "observer") then
	alias obssys source /ing/bin/obssys-3.csh
else
	alias obssys echo "You can only run the observing 
system from the observer account"
endif

#
# and fits read / write utilites
#
if ( -e /ing/tools/bin/fitsenviron ) then
	source /ing/tools/bin/fitsenviron
endif

#
# observers own startup script
#
if ( -e ~/.tcshrc.observer ) then
	source ~/.tcshrc.observer
endif

"Programs"	TITLE PIN
"xterm..."	DEFAULT exec xterm -sb -sl 750
"XGterm..."	exec xgterm -sb -sl 512 -bg LightSteelBlue1 -fn 7x14
"XImtool..."	exec ximtool
"iraf..."	exec xgterm -fn 10x20 -fg wheat -bg black -sb -sl 750 
-title IRAF
"SAOImage..."	exec saoimage
"File Manager..."	exec $OPENWINHOME/bin/filemgr
"Text Editor..."	exec $OPENWINHOME/bin/textedit
"Mail Tool..."	exec $OPENWINHOME/bin/mailtool
"Calendar Manager..."	exec $OPENWINHOME/bin/cm
	SEPARATOR
"lpss1"		exec xterm -title lpss1 -sb -sl 750 -e 
telnet lpss1
"lpss6"		exec xterm -title lpss6 -sb -sl 750 -e 
telnet lpss6
"lpss10"	exec xterm -title lpss10 -sb -sl 750 -e telnet lpss10
"lpss12"	exec xterm -title lpss12 -sb -sl 750 -e telnet lpss12
"lpss13"	exec xterm -title lpss13 -sb -sl 750 -e telnet lpss13
"lpss14"	exec xterm -title lpss14 -sb -sl 750 -e telnet lpss14
"lpss20"	exec xterm -title lpss20 -sb -sl 750 -e telnet lpss20
"Fault database lpvs3"	exec xterm -title "Fault database" -sb 
-sl 750 -e telnet lpvs3
"Command Tool..."	exec $OPENWINHOME/bin/cmdtool
"Shell Tool..."	exec $OPENWINHOME/bin/shelltool
	SEPARATOR
"Clock..."	exec $OPENWINHOME/bin/clock
"Calculator..."	exec $OPENWINHOME/bin/calctool
"Performance Meter..."	exec $OPENWINHOME/bin/perfmeter
"Print Tool..."	exec $OPENWINHOME/bin/printtool
"Audio Tool..."	exec $OPENWINHOME/bin/audiotool
"Tape Tool..."	exec $OPENWINHOME/bin/tapetool
	SEPARATOR
"Image Tool..."	exec $OPENWINHOME/bin/imagetool
"Snapshot..."	exec $OPENWINHOME/bin/snapshot
"Icon Editor..."	exec $OPENWINHOME/bin/iconedit
"Binder..."	exec $OPENWINHOME/bin/binder
"AnswerBook..."	exec $OPENWINHOME/bin/answerbook
	SEPARATOR
"Demos..."	exec $OPENWINHOME/bin/filemgr -d $OPENWINHOME/demo/add
	SEPARATOR

.xinitrc file:

# Make sure the BackSpace key produces the BackSpace keysym.
# Programs in the observing system need this.
   xmodmap -e "keysym BackSpace = Delete" -display ${DISPLAY}

# Have a command tool as a console window, started in the iconic state.
  cmdtool -C -Wi -sb -bg cadetblue2 -title Console -icon_label Console &
 
# Have an ordinary xterminal for general observing.
   xterm -sb -bg mistyrose -title "${LOGINNAME}" -name Obssys -sl 750 &

# Now run the standard window manager.
   olwm

Issue 1.1 1997-06-19 First Formal release.