Qtran README File
Tony Allen
Imperial, London
a.allen@ic.ac.uk or csc-support-dl@imperial.ac.uk


 May 2016


This file accompanies the distribution of Qtran, a utility to translate
between flat ascii and Common Data Format (CDF) files. This utility is
based on import/export routines found within the QMW Science Analysis
System (QSAS). The resulting CDF files are ISTP and Cluster-compliant.

Version 1 cef files (Cluster Exchange Format) and version 2 cef files (Cluster Active Archive)
are independently supported, but cef 2 is the default (use -ie or -oe flags for
importing/exporting cef 1 files).

The distribution, after un-tarring, consists of:

doc/DataDic.pdf
doc/CU-QMW-TN-0011.pdf  (File Syntax for QSAS understood ascii files and helper files)
doc/DS-QMW-TN-0010.pdf  (Cluster Exchange Format syntax, cef files)
Qtran (executable, Mac OSX only)
SampleFiles (example data files)
src (self contained src tree)


Requirements
============

Building Qtran
--------------

Qtran is built against cdf version 3.1 and above for Themis compatibility.

On OSX the provided binary should work straight out of the box, but the source is provided so that Qtran can be built against the local cdf installation. It is standalone and does NOT require NASA cdf libraries to be installed.

On all other platforms, Qtran builds using gcc via the Makefile contained in the release. The
CDF library need to be installed, and the first entry in the Makefile
edited to point to its location.

Type "make" at a system prompt to build Qtran. 


Running Qtran
-------------

Users may need to add the cdf library to their LD_LIBRARY_PATH if the local 
build uses the dynamic (.so) cdf library ( <xxx> = local pathway ):

if ($?LD_LIBRARY_PATH) then
   setenv LD_LIBRARY_PATH </usr/local/cdf/lib>:$LD_LIBRARY_PATH
else
   setenv LD_LIBRARY_PATH </usr/local/cdf/lib>
endif                                # add location of libcdf.so to lib path


The default behaviour is to convert *.qft, *.cef or *.qfd files 
to *.cdf and to convert *.cdf to *.cef (CAA) format.

Typing "Qtran" with no arguments produces an abbreviated option summary:

Usage: Qtran  [-o{tdce}] [-i{tdce}] [-hName] [-nName] [-f] [-r] [-v] FileName
options are...
  -i{tdcea} for input type qft, qfd, cdf, cef, cef2(CAA) respectively
 -o{tdceax} to specify output type as  qft, qfd, cdf, cef, cef2(CAA), no file respectively
 -f forces overwrite, otherwise error returned if file exists
 -r turns on record numbering if output file is flat
 -v turns on  verbose messages
 -c turns on  cef 2 syntax compliance messages
 -hName specifies Name as that of a detached header
 -nName specifies Name as that of the output file stem
 -sxxx Records starting with xxx are to be read. First record number is 0. Ignored when reading CDF
 -exxx Records up to and including xxx are to be read. First record number is 0. Ignored when reading CDF

 Option flags MUST be space separated,
 File type option must IMMEDIATELY follow -i and -o flags
 Option -h is ignored for cdf type input file
 If the input file has no extension use -i flag to set input type


Windows users
-------------

On windows the command line executable Qtran.exe may be run in the same way as Linux
versions using a terminal application such as msys.


NOTE
====

Files from DOS platforms with carriage-return/line-feed end of line
markers may cause Qtran to fail to read the line properly on a UNIX
platform. Such files should be re-saved as UNIX files before translation.


Documentation
=============

CU-QMW-TN-0011.pdf.ps
-------------
describes the basic ASCII file formats understood by Qtran (and QSAS).
In particular, it describes the format of the metadata (attributes in CDF),
including how to handle time from foreign files. The FREE_TIME_FORMAT capability
allows Qtran to translate ascii files from most data archives. The directory
Sample_headers contains example files with sample headers. Headers may be
either attached to the file or detached.


ExchangeFormat.pdf
------------------
is the documentation for Cluster Active Archive standard format.


Warranty and License
====================

Qtran is supplied under the Gnu Public License and without any warranty against
loss of any kind, but with the hope that it will be useful.

End of README_QTRAN
