# vim: set ts=2 sw=2 et tw=72:
= tsc-status README
This is a package of a library libtscstatus and a user interface
dump-tsc-log to extract telescope status data on TWS4 or from the log
files in SOSS.

The package is tested on Linux 2.6.x on ix86 and Solaris 2.8 on Sparc.

test-shm-interface currently fails on Solaris 2.8 on Sparc.

== Overview
tsc-status is a package of libraries to aim to offer an easy way to
access telescope status on TWS4 and other machines. The author assumes
two main ways looking into the status data:

* as log files extracted from STARS on your machine, using dump-tsc-log
  command, and
* as real time staus on TWS4 through POSIX shared memories, this
  library, and your program in C or Python.

The following diagram is a rough sketch of flows of status data.

  [TSC]-+-rpc---[TWS4:rpc daemon-->shm---libtscstatus:your program]
        |
        +-rpc---[OBS]---STARS:status log files---[your machine]:dump-tsc-log

== Usage
Please refer man pages in doc/.

A Japanese description to be used inside Subaru Telescope Network can
also be found in usage-in-stn.ja.txt.

== Performance
On test-shm-interface, it is confirmed that the size of the process in
the memory (reading /proc/self/statm) remains the same after 10000
reading from shared memory and converting it into a double. Also, a read
and conversion to double can be done 20 nsec on onversions are done in
about 0.2 sec on a 32bit 2.8GHz Xeon. Moreover, it takes about 10 msec
to scan a sample data file and deploy them to the shared memories.

== Installation
Please note that A RATHER LARGE MEMORY (> 480MB) IS NEEDED!

It takes a night to compile the package on a Cerelon 300MHz machine with
128MB physical memory + 512MB swap space. Physical memory of more than 480MB
greatly reduces the time required to compile.

=== Configuration, compilation and installation 
Usually, you just have to do the following to compile.
  $ ./confiugre
  $ make
Compiling status-hash.o requires a rather large memory space (about 480MB
with gcc on ix86).

You might also have to do:
  $ CC=`which gcc` ./configure

You can also
  $ make check
to check if everything (hopefully) is working good. If you suspect a
memory leak, try:
  $ export MALLOC_COUNT_SHOW=1
  $ make check
malloc(2) and free(2) in the library and the test programs (not
including those in python/ directory) will be displayed to the stderr.

If everything goes good, install the programs as the root:
  # make install

You might want to install the package not as root. Do something like:
  $ ./configure --prefix=$HOME/local
  $ make
  $ make check
  $ make install
In this case, you have to do either
  sh$ export LD_LIBRARY_PATH=$HOME/local/lib:$LD_LIBRARY_PATH
  csh$ setenv LD_LIBRARY_PATH $HOME/local/lib:$LD_LIBRARY_PATH
for the linker to find the library needed.

If ./configure does not work, follow these steps before doing above:
  $ aclocal
  $ autoconf
  $ autoheader
  $ automake
or
  $ autoreconf

If the commands complains that "file `version.m4' does not exist", you will
have to do
  $ ./update-version-m4
on a working copy. If you are not on a working copy, you can make a file
version.m4 like follows:

  m4_define([VERSION_NUMBER], [0.8.1])

This file defines the of the package.

== Update of the status signals
The package uses the CSV files in melco-csv/. It currently has the September
2004 version of status entries. Please edit or replace the files to follow
updates on the telescope. Edit mitsubishi.py for changes or addtions of
* instrument IDs
* length of monitor data message for each instrument
* correction of typos
and  edit makekeywords.py for
* name space collisions

Keywords defined so far are listed in the file predefiened-keywords.txt with
each line has ID and keyword, except for IDs listed in
NameSpace.no_predefine inmakekeywords.py. This prevents keywords to be
changed in the future when a new collision is found. The file should be
updated automatically by makekeywords.py with executing
  make stamp-makekeywords  
when a new keyword is found.

gperf >= 3.0 and python are needed.

You should be able to build the package at first cleaning the gperf created
files:

  $ make maintainer-clean

than configure and make again:

  $ aclocal
  $ autoconf
  $ autoheader
  $ automake
  $ ./configure
  $ make 

If the build process fails in compiling status-hash.c. In that case,
please scroll back to the very beginning of the huge number of warnings.
The compiler should complain about an unknown type like this:

  status-hash.c:6700: error: `BINARY1_1' undeclared here (not in a function)

In the case, you have to define:

* new union types in melco/status-types.h
* new `reader' functions to convert the value into double, long long, 
  char*, or struct timeval in status-type.c and melco/status-types.h, and
* edit makekeywords.py and an entry to no_reader_function in it to suppress
  some reader functions (e.g. we can not convert a real number into a time).

== RPC interface
Files in test-rpc/ are used to test RPC interface in this library. The
real implementation to be used in TWS4 is included in rpc/.

== Copyright

Copyright (C) 2005 and 2007 Daigo Tomono <tomono at subaru.naoj.org>

Permission is granted copying, modification, distribution, and distribution
of modified versions of this work under the terms of GPL version 2 or later.

Read the COPYING file for more details.
