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 [time=]
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 command. More
specific help is available by pressing 'h' during the listing. The optional
"time=" 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 [time=]
In this case, the input Flatfile is converted from the native SUN binary
format to the format specified by . The argument can
be any one of the formats specified above. If the format is ASCII then
the output is stored in the file .ASC with an accompanying
descriptor file .DES. If the argument is one of
the other binary formats, then the output is stored in a Flatfile with
the basename . If the argument is missing, then the
output will be directed to the terminal screen in ASCII format. Here, the
"time=" 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 ; 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 FFEXTRAC.LBL.
*** 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.
-----------------------------------------------------------------------