                       FFEXTRACT: Users' Guide
                       =======================

FFEXTRACT is a command-line utility that gives the user the ability
to convert UCLA/IGPP Flatfiles from the native SUN binary format
(MSB/IEEE) to any of the following formats:

      ibm    -  IBM 370 binary format
      vax    -  VAX/VMS binary format
      pc     -  Intel PC using IEEE binary format
      sun    -  SUN binary format (MSB/IEEE) -- no conversion
      ascii  -  ASCII format (text file)

  Note: In the near future the following two formats will also be supported.

      hp    -  HP 1000 binary format
      mbf   -  Intel PC using Microsoft Binary Format


SYNTAX:
-------

%  ffextract <Input Flatfile> [time=<TimeStyle>]

Here, the input Flatfile is converted to ASCII format (text) and printed
to the terminal screen.  This is a good way of quickly viewing the structure
and contents of a Flatfile.  The descriptor information (the fields making
up the data) is first displayed on the terminal screen, and then the user
can advance through the data a page at a time.  One can look at all the
fields by using the 'l' and 'r' keys followed by an <Enter> command.  More
specific help is available by pressing 'h' during the listing.  The optional
"time=<TimeStyle>" argument specifies the time style to use for the TIME
fields in the flatfile.  The default time style is PDS_STYLE, and the possible
time styles are: AMERDATE, EURODATE, ABBRAMER, ABBREURO, LONGAMER, LONGEURO,
NUMERICAL, DAYNUMBER, JAPANDATE, NIPPONDATE, HIGHLOW, ISEEDATE, DFS_STYLE,
ABBRDFS_STYLE, PDS_STYLE, ISO, BINARY, and GLL_SCLK.
A second usage form is:

%  ffextract <Format> <Input Flatfile> <Outfile> [time=<TimeStyle>]

In this case, the input Flatfile is converted from the native SUN binary
format to the format specified by <Format>.  The <Format> argument can
be any one of the formats specified above.  If the format is ASCII then
the output is stored in the file <Outfile>.ASC with an accompanying
descriptor file <Outfile>.DES.  If the <Format> argument is one of
the other binary formats, then the output is stored in a Flatfile with 
the basename <Outfile>.  If the <Outfile> argument is missing, then the
output will be directed to the terminal screen in ASCII format.  Here, the
"time=<TimeStyle>" argument is only effective when the Format is ASCII.
Its usage is as described above.

NOTE:  All Flatfile names should be given as only the basename of the
       Flatfile.  In other words, there should be no extension specified.
       More information about UCLA/IGPP Flatfiles is provided in the
       next section.


UCLA/IGPP Flatfiles
-------------------

A UCLA/IGPP Flatfile is made up of four components, three text files
and a binary data file.  All four of the files share the same basename
(prefix), and all four should always be present together in the same
directory.  For example, a Flatfile with the basename "ORBIT_1" would
be made up of the following four files:

      ORBIT_1.ABS
      ORBIT_1.DAT
      ORBIT_1.DES
      ORBIT_1.HED

ORBIT_1.ABS is the abstract component of the Flatfile; it contains an
optional short summary about the Flatfile.  ORBIT_1.DES is the descriptor
file which tells the software the structure of the binary data file.
ORBIT_1.HED is a header file which provides information about the creation
of the Flatfile.  And lastly, ORBIT_1.DAT is the actual raw data file
which is in SUN binary format (MSB/IEEE).

Note: An older version of the UCLA/IGPP Flatfile exists and is called a
      "lower flatfile".  It is composed of two files, a header file (.FFH)
      and a data file (.FFD).  FFEXTRACT is capable of working with these
      lower flatfiles, but only as the <Input Flatfile>; it is not possible
      to get a "lower flatfile" as the output of FFEXTRACT.  The syntax of
      the command is exactly the same as given above.  Note that just like
      with regular Flatfiles, when a "lower flatfile" is given as the input
      to FFEXTRACT, only the basename should be specified.


Example 1:
----------
Let's assume that we have a Flatfile called T890822 and we would like
to see its contents.  In order to view the contents of this file in ASCII
format on the screen, we issue the following command:

%  ffextract T890822


Example 2:
----------
Now let's assume that we want to extract the contents of this same file
in VAX binary format and we want to call the output "VAX_OUT".  We issue
the following command:

%  ffextract vax T890822 VAX_OUT

After a few seconds the program will complete and we will have the
following files in the directory:

    VAX_OUT.ABS
    VAX_OUT.DAT
    VAX_OUT.DES
    VAX_OUT.HED

This is of course a Flatfile just like T890822, except the data file is
in VAX binary format instead of SUN/IEEE format.  If the program complains
that it is unable to open the output file, it is possible that you
have no write access to the current directory.  In that case you can
specify a different path for the output file, such as:

%  ffextract vax T890822 /tmp/VAX_OUT 

on UNIX, or,

%  ffextract vax T890822 [TMPDIR]VAX_OUT

on VMS, etc.


Example 3:
----------
In this example, let's assume that we would like to extract the contents
of a lower flatfile "orb0180" as ASCII.  We want the time field(s) in the
flatfile to be output in AMERDATE style.  The command for this would be:

%  ffextract ascii orb0180 output time=AMERDATE

After the command is completed, we will obtain two files, "output.ASC"
which contains the actual ASCII data, and "output.DES" that contains
the descriptor information.  




                     FFEXTRACT: Installation Guide
                     =============================
The source code of FFEXTRACT comes in the following three files:

        Makefile
        ffextract.c
        ffextract.h

To install FFEXTRACT you must have the following libraries on your system:

        binary  -  Binary Conversion library
        ffio    -  Flatfile I/O library
        parserc -  Command parser library
        miscc   -  Miscellaneous library
        timec   -  Time library

If you receive this software in a zipfile, then you must extract the above
files using the "unzip" command.  There are numerous versions of Zip/Unzip
utilities. If you have one installed already, refer to its documentation in
order to unzip these files. In the case that there is no Zip utility
installed, or it does not unzip correctly, there is a version of InfoZip on
this CD located at /SOFTWARE/SOURCE/ZIP_WARE.

It should also be noted that all of these files (source code and executables
for FFEXTRACT and InfoZip's Unzip) can be found at the PPI
node at http://www.igpp.ucla.edu.

A listing of the files that should be created through the unzipping of
FFEXTRAC.ZIP can be found in the file FFEXTRACT/INSTALL.TXT.

                     *** INSTALLATION ****

If you are using a Sparc Station running SOLARIS then you can use
the executable SOFTWARE/SOLARIS/FFEXTRACT already supplied.

If you are using a Sparc Station running SunOS 4.x then you can use
the executable SOFTWARE/SUNOS/FFEXTRACT already supplied.

If you are using a PC running DOS then you can use
the executable SOFTWARE/PC/FFEXTRACT.EXE already supplied.

Other users:
1)  Copy the appropriate MAKE_CONF.??? and MAKE_LIBS.??? files to Make.conf
and Make.libs, respectively.

    Your System           Use                                  Copy to
   ==========================================================================
     PC                   MAKE_CONF.PC  & MAKE_LIBS.PC     \
     HPUX                 MAKE_CONF.HPUX & MAKE_LIBS.HPUX   \  Make.conf &
     SUN4.X               MAKE_CONF.SUN4X & MAKE_LIBS.SUN4X  / Make.libs
     SUN/SOLARIS 2        MAKE_CONF.SOL2 & MAKE_LIBS.SOL2   /

2) Make any changes to the Make.conf and Make.libs files if necessary
   (i.e. the type of C compiler you are using (cc, gcc, etc), where you want
   the executable to go, etc.)

3) set the DFSHOME environment variable to the path leading to and including
   the directory FFEXTRACT (created as the base of the tar extraction)
   ex. prompt>> setenv DFSHOME /usr/software/tools/FFEXTRACT

4) issue command "make".
   ex. prompt>> make


NOTE:  Depending on your compiler, warnings make appear when compiling the
       program. These can be ignored.

-----------------------------------------------------------------------
      Copyright(c) 1993 Regents of the University of California
      All rights reserved.

   Redistribution and use in source and binary forms are permitted
   provided that the above copyright notice and this paragraph are
   duplicated in all such forms and that any documentation,
   advertising materials, and other materials related to such
   distribution and use acknowledge that the software was developed
   by the University of California, Los Angeles.  The name of the
   University may not be used to endorse or promote products derived
   from this software without specific prior written permission.
   THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
   IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
-----------------------------------------------------------------------
