All software and relevant documentation resides on a central common fileserver in order that offline development on any suitable machine and routine online system operation may occur simultaneously. Currently this is implemented on "apus.hartrao.ac.za" in the /home2/local/src directory, routinely mounted as /usr/local/src on all HartRAO Linux machines.
Documentation is written in SGML and converted to HTML, Latex and other formats using SGML-Tools, see SGML-Tools User's Guide, html version 0.99.0
An index to all currently available documentation in WWW browse-able format is available in the NCCS index at /usr/local/src/nccs/doc/index.html.
The NCCS fileserver area is divided into two separate directories, namely the TACO and system home directory (referred to as $DSHOME and where the operational system is stored) and the local HartRAO NCCS development directory where the average NCCS developer would work.
The $DSHOME directory contains all of the TACO control system software, including the API source code plus operational copies of all the NCCS executables, their associated header files and libraries as follows:
/usr/local/src/dserver
** /bin - Multi-platform NCCS executable collection
** /linux - for Linux Operating System
** ## /x86 - on Intel 80x86
[/m68k] - on Motorola 68000
[/sun4] - for SunOS on sun4 architecture
/classgen - Class Generator distribution
/bin
/classes
/doc
/examples
/system
/uncustomize
** /dbase - Resource Database / DBAPI distribution
** @@ /dbm - Actual DBM database files
** @@ /backup - backup copies
/include - C header files for DBAPI
** @@ /res - Resource files
** @@ /CLASS - device class resources
** @@ /CMDS - device command names
** @@ /ERROR - device error names
** @@ /HARTRAO - NCCS resource database
** @@ /SEC - device security setup
** @@ /SYPARM - NCCS SYPARM database
** /scripts - Database Tool invocation scripts
/scripts.dist (as originally distributed)
/server - Database Server distribution
/include - C header files
/src - Source code
/src - Source code for DBAPI
/tools - Database Tools distribution
/include - C header files
/src - Source code
/doc - Collated TACO documentation
/system - DBN, DSM, DSN, manpages etc.
/dserver - TACO Base, System & DSAPI/DSXDR distribution
/classes - Device Classes for C
/main - basic DevServer class
/include - C header files
/src - Source code
/test_class - test Inst_Verify class
/include - C header files
/res - Resource examples
/src - Source code
/ug - LaTeX userguide
/test_class - test Inst_Verify class
/classes++ - Device Classes for C++
/device - basic Device class
/include - C++ header files
/oic - C++ OIC wrapper
/include
/src
/src - Source code
/system - System (including DSAPI/DSXDR)
/api - Main distribution
/admin - Aministrator
/include
/apilib - DSAPI library
/doc
/include
/src
/cmds_err - Command/Error Names
/include
/res
/src
/dataport - Dataport distribution
/include - C header files
/src - Source code
/test - Test software
/src
/dc - Data Collector interface
/include - C header files
/dev_ping - dev_ping utility
/manager - Device Server Manager
/include - C header files
/src - Source code
/msg - Message Server
/include - C header files
/src - Source code
/xdr - DSXDR libraries
/include - C header files
/src - Source code
** ## /etc - NCCS/TACO startup/shutdown scripts
/gmake
/include - C header file collection
/private - private C header files
/include++ - C++ header file collection
/lib - Multi-platform NCCS/TACO library collection
/linux - for Linux Operating System
/x86 - on Intel 80x86
** @@ /system - TACO system executable collection
** @@ /bin - Multi-platform executables
** @@ /linux - for Linux OS
** @@ /x86 - on Intel 80x86
where:
Note: Dynamically loaded libraries are installed on all NCCS development machines by making symbolic links in /usr/local/lib (mounted from the fileserver at apus:/home2/local/lib/linux) which point to the current versions in the directory structure above (ie. to $DSHOME/lib/linux/x86.)
On NCCS operational machines a local version of each appropriate library must be physically copied to a locally mounted /usr/local/lib directory so that execution can continue undisturbed if the server should fail for any reason (see RUNTIME ENVIRONMENT below.)
This is the main NCCS development area, roughly subdivided as follows (with symbolic links suppressed for clarity):
/usr/local/src/nccs
/antenna - Antenna Control System development area
/doc - Linux Steer documentation.
/hardware - External cage device driver
/steer - Steer device server
/steer_dbg - Steer errorlog debugger
/steer_sub - Antenna control sub-process
/correlator - AT Multibeam Correlator development area
/atdc - AT Distributed Clock computer
/atsoft140199 - AT software release of 1999/01/14
/atsoft240399 - AT software release of 1999/03/24
/docs - correlator docs
/emails - emails relating to correlator
/mbcc - Block Control Computer
/doc - NCCS Documentation Project area
/design - NCCS Design Document
/developer - NCCS Developer's Guide
/inputfiles - Input files Definition
/dserver/local - Local Device Server Program. Guide
/meetings - NCCS Progress Meeting minutes
/motivations - Motivations etc.
/obsolete - Outdated/Obsolete documents
/outputfiles - Output files Definition
/pulsars - pulsar timing docs
/require - NCCS Requirements & Specifications
/scheduler - Proposed NCCS Scheduler Design
/sgmltools - SGML-Tools docs
/spectroscopy - spectroscopy docs
/tasklist - Tasklist etc.
/timeline - Timelines etc.
/text - Assorted plain text documents
/userif - Proposed NCCS GUI Design
/dservers - NCCS Device Server development area
/develop - Development/obsolete versions
/dummy - A generic dummy device server
/logger - Log/alarm/watchdog device server
/sdio - SDIO device server cluster
/ndiode - Noise Diode/Dicke switch
/ndmux - low-level ND multiplexor
/sdio - low-level SDIO I/O port
/selector - Multi-position selector
/toggle - Simple toggle switch
/libhart - HartRAO Station Library development area
/obsolete - Old/Obsolete software versions
/tcl (stub) - HartRAO Observer Shell development area
/userif (stub) - HartRAO Observer GUI development area
Most directories contain README files detailing the contents of files and/or sub-directories. All directories should be owned by the "dserver" group, be group writeable and have the setgid bit set ie.
host:~$ chown dserver <directory-name>
host:~$ chmod g+ws <directory-name>
and all source files etc. should be under RCS control and left checked in when not actively being worked upon. This will ensure that multiple programmers can collaborate on developing and maintaining all relevant software.
Each NCCS machine must have the archetypal device server userid "dserver" (uid=300, gid=300) defined in /etc/passwd with home directory pointing to the appropriate $DSHOME directory ie. to
/usr/local/src/dserver on NCCS development machines and to
/home/dserver on NCCS operational machines,
with the password and home directory fields only filled in on operational machines.
Similarly each NCCS machine must have the "dserver" groupid (gid=300) defined in /etc/group, with the developer's own userid listed as an additional member of the group.
Each developer's personal login profile ( /.bash_profile) should contain the following environment definitions:
# # NCCS programming support # export DSHOME=~dserver export PATH=$PATH:$DSHOME/bin/linux/x86 export NETHOST=nccs1
where
With the appropriate dserver userid and groupid set and with the environment variables as defined above, the developer should then be able to use his own personal login to develop, maintain and test the various NCCS software components described below.
All of the NCCS operational Linux machines (currently nccs1, nccs2 and steer) are partially decoupled from the central server archive as follows:
/home/dserver
/bin - Multi-platform executable collection
/linux - for Linux Operating System
/x86 - on Intel 80x86
/etc - NCCS startup/shutdown scripts
All NCCS executables and scripts can be refreshed with the latest
versions by running the script /etc/nccs.reload while logged in
as dserver on the $NETHOST.
Each of these machines is thus able to run any of the NCCS executables (in particular device servers) independently of the central fileserver using offline (perhaps obsolete) copies of executables and libraries.
One specific NCCS operational machine is designated to be the $NETHOST (usually nccs1), the only fixed point in the TACO control system. The dserver home directory copy of $DSHOME on the $NETHOST must also contain the following additional directories:
/home/dserver
/dbase - Resource Database
/scripts - Tool invocation scripts
/dbm - Actual DBM database files
/backup - backup copies
/res - Resource files
/CLASS - class resources
/CMDS - command names
/ERROR - error names
/HARTRAO - NCCS resources
/SEC - security setup
/SYPARM - NCCS SYPARM
/system - TACO system binary collection
/bin - Multi-platform executables
/linux - for Linux OS
/x86 - on i80x86
These contain the files implementing the Device Manager and the Resource Database which controls and configures the NCCS TACO control system. The resource files in the /dbase/res sub-directory comprise the primary reference for all of the NCCS structure, being loaded into the NDBM database (in /dbase/dbm) for easy access by the Database Server which in turn supplies them to all NCCS processes on request. Any of the resource directories directories which may exist in any other $DSHOME implementation should at best be considered as a backup copy. The copy on the fileserver for example usually reflects a standard default setup.
The /dbase/scripts and /system/bin/linux/x86 directories contain local copies of the TACO system scripts and binaries to allow stand-alone operation as with the NCCS scripts and binaries above. Note that these would need to be refreshed manually should the primary versions on the central fileserver be changed for any reason. The /etc/nccs.reload script does NOT operate on these directories.
Although devices will be served by device servers running as dserver on any one of the machines in the NCCS operational network, all of these processes are usually started (or stopped) by remote shell from a single central startup (or shutdown) script run on the $NETHOST. Device servers can also be individually shutdown and restarted on the relevant host if necessary.