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