*** NOTE:
VAX-VMS users can find available software from
UCLASP::DISK$SCRATCH:[PDSUSER.SOFTWARE].
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.