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

Qtran VERSION 3.6.1

 October 2011

3.6.1 handles Epoch16 data types as used in Cluster WBD data files.


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/DataExchangeMan.ps
doc/FileSyntax.ps
doc/ExchangeFormat_V1.pdf
doc/ExchangeFormat.pdf
Qtran (executable, Linux and Mac OSX only)
Qtran.exe (executable, Windows only)
Qtran.bat (script, Windows only)
README_QTRAN
SampleFiles
src/Makefile
src/Qtran.c
src/qie.h
src/qie_cdf.c
src/qie_flat.c
src/qie_ft.h
src/qie_local.h
src/qie_meta.c

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

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

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. 

Qtran should compile on most platforms with a standard gnu C compiler.
We are grateful to Pat Daly for providing WIN32 and VMS compliant
modifications which have been incorporated into Qtran version 3 and above.

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.

Alternatively, a Windows batch file is provided.
This may be edited to select the flags required and target files,
then run by double clicking the icon.

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
=============

FileSyntax.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.

DataExchangeMan.ps
------------------
is a programmer's manual, aimed at those who would like to
extend Qtran's capabilities. Qtran works by reading data into an internal
data structure, and then writing it out in the desired format. Thus by writing
a single set of read and write routines, the programmer can provide translation
into and out of all other formats understood by Qtran. The Qtran team would be
pleased to hear of any new read/write routines which might be incorporated
into future releases of Qtran.

ExchangeFormat_V1.pdf
------------------
is the documentation for CSDS archive task group data exchange standard format.

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
