======================================================================
Installation and Usage of ESOC/FD orbit and attitude 
file access S/W (version 1.0)
======================================================================
This text provides information on how to install and use the
ESOC/FD orbit and attitude file access S/W (version 1.0).


Contact
======================================================================
In case of problems, questions or recommendations please contact
Mathias.Lauer@esa.int


Version of 'readme' file
======================================================================
1.5	27/08/2003	M. Lauer


Contents of Package
======================================================================
The package consists of

1) orbit and attitude file access S/W:
subroutine		version
dj2000.f 		 1.3
drsort.f 		 1.3
getun.f 		 1.4
hermde.f 		 1.5
jd2000.f 		 1.3
lagrde.f 		 1.2
qdrate.f 		 1.1
quanrm.f 		 1.1
rafcl.f 		 1.2
rafop.f 		 1.4
rafrr.f 		 1.8
rbinfo.f 		 1.5
rdgotb.f 		 1.6
rgblhe.f 		 1.5
rgetbl.f 		 1.6
rgethe.f 		 1.6
rgetre.f 		 1.4
rghead.f 		 1.5
rgotob.f 		 1.7
rifcl.f 		 1.6
rifop.f 		 1.13
rinfo.f 		 1.6
riorec.f 		 1.5
rnextb.f 		 1.6
rofcl.f 		 1.7
rofop.f 		 1.16
rofrr.f 		 1.12
rrered.f 		 1.10
rtcrbt.f 		 1.4
rtfndb.f 		 1.3
rtfndg.f 		 1.3
taiutc.f 		 1.9
tdbtdt.f 		 1.1
tdbutc.f 		 1.1
tdtutc.f 		 1.1
wafcl.f 		 1.2
wafnb.f 		 1.4
wafnr.f 		 1.3
wafop.f 		 1.3
wblhea.f 		 1.4
wgblhe.f 		 1.4
wghead.f 		 1.4
whead.f 		 1.4
wifcl.f 		 1.5
wifop.f 		 1.8
wiorec.f 		 1.4
wmodbl.f 		 1.2
wmodhe.f 		 1.4
wnwblk.f 		 1.6
wnwrec.f 		 1.10
wofcl.f 		 1.6
wofnb.f 		 1.8
wofnr.f 		 1.7
wofop.f 		 1.12

2) conversion routine
as2bin.f 		 1.11
to convert orbit and attitude files from ASCII format 1.0 into binary format

3) sample main programs
readaf.f 		 1.3
to test attitude file access
readof.f 		 1.4
to test orbit file access


Changes w.r.t. version 0.1
======================================================================
1) The official interface to the library, i.e. subroutines
- rofop, rofrr, rofcl for orbit file access and
- rafop, rafrr, rafcl for attitude file access
has not(!) changed. There is therefore no code change required
for application programs to link the new software version.

2) The formats of orbit and attitude files, compatible with the
software, have not(!) changed, i.e. files converted with 'as2bin'
from version 0.1 can be read with the software 1.0 and vice versa.

3) Some deficiencies and bugs have been removed. The main ones are:
- The number of blocks allowed in an orbit or attitude file has
been increased.
- A wrong calling sequence in as2bin has been corrected. The old
version did not cause a wrong result, but the code did not compile
with a LAHEY FORTRAN compiler on WINDOWS 98.
- Under special circumstances, retrievals from data files were
dependent on the order of the time key in which the data were
accessed.

4) For a detailed description of changes, see also the source code 
of the updated routines.


Description
======================================================================
Each source code contains a header describing the functionality
and the calling sequence of each subroutine. Additional comments
are given within the code.


Compilation and Linkage
======================================================================
All subroutines are written in Standard FORTRAN77 with the following
exceptions:
- usage of data types REAL*8 and INTEGER*4
- usage of non standard intrinsic function 'dfloat'
No special compiler options or preprocessing (e.g. include
files) are required for compilation.
Main programs (e.g. a user application, the conversion routine
as2bin and the sample routines readof, readaf) have to be
linked with the subroutines.


Usage
======================================================================
1) Conversion of orbit and attitude files:
To convert an orbit or attitude file from ASCII format to binary format,
the
program as2bin has to be executed. The user is prompted to give
the name of the input file (orbit or attitude), which has to be in ASCII
format,
and to give the name of the output file (orbit or attitude),
which will be in
binary format.
The following ASCII formats are supported:
ESOC_TOS_GFI_ORBIT_FILE_VERSION    = 1.0
ESOC_TOS_GFI_ATTITUDE_FILE_VERSION = 1.0


3) Retrieving states from orbit file:
A user application has to be coded which calls:
1.) once subroutine rofop.f to open the data file before the
    retrieval of a state
2.) rofrr.f to access the data every time a state referring to a 
    specific epoch is required
3.) once rofcl.f to close the file after retrieval of all required
    states
The data file has to be an orbit file in binary format. For
conversion into the binary format use the program as2bin.
The main program readof.f gives an example of how to use the
access software and can be used for testing purposes.


4) Retrieving data from attitude file:
A user application has to be coded which calls:
1.) once subroutine rafop.f to open the data file before the
    retrieval of data
2.) rafrr.f to access the data every time the attitude referring 
    to a specific epoch is required
3.) once rafcl.f to close the file after retrieval of all required
    attitude data
The data file has to be an attitude file in binary format. For
conversion into the binary format use the program as2bin.
The main program readaf.f gives an example of how to use the
access software and can be used for testing purposes.


Orbital information
======================================================================
The time scale is barycentric dynamical time (TDB). The time
format of the epoch is MJD2000, i.e. the number of days since
January 1, 2000, 0 hours.
The states retrieved from the orbit file consist of position
(km) and velocity (km/s) and refer to the mean Earth equator
frame of equinox J2000.0 (= 2000 January 1, 12 hours =
JD 2451545.0 = 0.5 MJD2000 (all TDB)).
The centre of the coordinate system is either the barycentre of
the solar system, the Sun, a planet or the Moon. Their ephemerides
are taken from the latest version DE405 of the JPL export
ephemeris files. Depending on the actual orbit file the centre may
vary with the epoch (e.g. Sun during cruise, planet during 
flyby). The information on the centre is returned as output
together with the state from the subroutine rofrr.f (see header of
the source code).


Attitude information
======================================================================
The time scale is barycentric dynamical time (TDB). The time
format of the epoch is MJD2000, i.e. the number of days since
January 1, 2000, 0 hours.
The states retrieved from the attitude file consist of attitude
quaternion and angular rate (rad/s). The scalar part of the quaternion
is the 4th element of the array. The quaternion refers to the attitude
of the spacecraft mechanical frame with respect to the mean Earth 
equator frame of equinox J2000.0 (= 2000 January 1, 12 hours =
JD 2451545.0 = 0.5 MJD2000 (all TDB)). The angular rate is given in
rad/s and is resolved along spacecraft axes.