The HDF-EOS Library: Software and Hardware
What is the HDF-EOS library and how can it be used?
Obtaining, installing, and compiling the HDF-EOS library
Computer platforms supporting the HDF-EOS library
Programming languages supporting the HDF-EOS library
What is the HDF-EOS library and how can it be used?
The HDF-EOS library is a collection of software routines or code in the form of three new Application Programming Interfaces (APIs) called the Point API, the Swath API, and the Grid API. These APIs, unlike the individual APIs in the base HDF library, will enable the user to work with data and associated geolocation or temporal information typical of the data sets (field campaign, satellite swath) anticipated from the EOS missions.
The HDF-EOS library is an extension or add-on to the base HDF library that is available from the ECS Project. As such, the HDF-EOS library requires the compiling and linking of the HDF library (as outlined in Section 4 The HDF Library: Software and Hardware) to be run succesfully. The APIs of the HDF-EOS library are structured and employed in a similar fashion to the HDF APIs.
It should also be noted that, although many EOS instrument teams and Data Centers will use the HDF-EOS library in tandem with other software (such as the SDP Toolkit) to work with and create EOS data, it is intended that working with the HDF and HDF-EOS library itself will be sufficient to enable the user to work succesfully with HDF-EOS data. This will be discussed further in later sections.
Obtaining, installing, and compiling the HDF-EOS library
The HDF-EOS library source code, along with the previously mentioned documentation, is availabale from several locations. The user may download the latest release of the HDF-EOS library and installment instructions from the GSFC HDF-EOS Information Resources page. Under the "Original HDF-EOS" button, the user will find the library itself for downlaoding, as well as installation directions (readme file) and Test_Driver files and programs to see if everything is done correct. Not only is HDF-EOS Library source code for various Unix platforms and binaries (for Macs) avaialble with this download, but so are a wide array of C and FORTRAN programs that can be used to perform operations on grid, point and swath data sets. The user can follow the detailed installation directions in the readme file, but a more updated set of installation directions can be found in Appendix A of the HDF-EOS Library User's Guide for the ECS Project, Volume 1: Overview and Examples which was mentioned in earlier sections.
When downloading the HDF-EOS library source code, the user should make sure that the recieving directory has at least 3-400 MB of space available to hold the files that will be downloaded. These files will be in compressed format, with the "uncompress" and "tar" commands necessary to get the actual files. After uncompressing the source code file and using the tar command (tar -xvf HDFEOSv2.6.tar), the user will have the HDF-EOS library files on his/her system. The user must then run an interactive installation script by typing in:
bin/INSTALL-HDFEOS [install options]
where [install options] can be -sgi, -sgi32, or -sgi64 depending on the system architecture.
As mentioned previously, the HDF-EOS library is an extension of and built upon the base HDF library. The HDF-EOS library needs the HDF library to be previously installed (see Section 4 The HDF Library: Software and Hardware). During the interactive routine, the user must then define the computer environment variables needed to compile nad run code with HDF-EOS. The environmental varaible $BRAND is defined depending on the type of platform where the library is being installed and is assigned "dec", "hp", "ibm", "sgi", or "sun5" for, respectively, DEC Alpha, HP 9000, IBM RS-6000, SGI Power Challenge, and Sun. The set up also depends on the type of login shell being used (C shell (csh), K shell (ksh), or Bourne (sh)). Once again, please see Appendix A of the HDF-EOS Library User's Guide for the ECS Project, Volume 1: Overview and Examples for the necessary information.
As stated in the above documentation, the HDF-EOS include and library files must be accessed in order to compile and link the program. The following can be done within the user's makefiles:
INCLUDE = -I. -I$(HDFEOS_INC) -I$(HDFINC) LIBRARY = -L. -L(HDFEOS_LIB) -L$(HDFLIB) LDFLAGS = -lhdfeos -1Gctp -lmfhdf -ldf -ljpeg -lnsl -lz -lm (For Sun Systems) LDFLAGS = -lhdfeos -1Gctp -lmfhdf -ldf -ljpeg -lz -lm (Others)
To compile a C or FORTRAN program (as an example, readswath.c) that utilizes the HDF-EOS library, the user may also use the following:
cc -DHDFSYS -o readswath.o -I$HDFINC -I$HDFEOS INC -c readswath.c cc -DHDFSYS -o readswath readswath.o -L$HDFLIB -L$HDFEOS LIB/ -lhdfeos -lGctp -lmfhdf -ldf -ljpeg -lz -lnsl -lm
Just as with the HDF library, the order of the libraries is important and should not be switched. Please note that both the HDF and HDF-EOS libraries are being linked, with the HDF-EOS library coming first. The "-lGctp" is for the map projections for gridded HDF-EOS data.
In addition, the latest version of the HDF-EOS library, along with the ECS Science Data Production (SDP) Toolkit and associated documentation may be obtained via the SDP Toolkit Home Page. However, since the SDP Toolkit was developed under a NASA contract for EOS instrument teams, this site is password protected and the password may be obtained by sending email to pgstlkit@eos.hitc.com. Once connected to the server, the user needs to change to the "/hdfeos" directory.
Computer platforms supporting the HDF-EOS library
The latest version of the HDF-EOS library is HDF-EOS2.6. Although the list of machines supported increases with every incremental version or release, it is still not possible to work with HDF or HDF-EOS files on every single platform or operating system. As of the current release in the summer of 2000, the HDF-EOS library is currently supporting the following computer platforms and operating systems:
Programming languages supporting the HDF-EOS library
As of the current release of HDF-EOS (HDF-EOS2.6), the only programming languages which are supported by the HDF library are C (C and C++) and FORTRAN (F77 and F90). Although the HDF and HDF-EOS library code is only written in C, the library provides a FORTRAN interface which converts the code to C and allows the user to call the HDF-EOS routines. This conversion will automatically take place and requires no action by the user.
Other then the obvious differences between the programming languages, the main difference between using the different languages is the naming convention, or names used for each HDF-EOS function. These differences will be pointed out in later sections. In addition, to use and compile HDF-EOS application routines through C programs, an HDF header file (hdf.h) containing standard HDF data type and file access code (i.e. read, write) definitions, declarations and prototypes for the API routines must be called or included (#include "hdf.h") at the beginning of the program. These header files are not permitted in all FORTRAN versions and the needed information must be written into the FORTRAN code (taken from the HDF library file "constants.f" within "hdf.h").