The HDF Library: Software and Hardware
What is the HDF library and how can it be used?
Obtaining and installing the HDF library
Computer platforms supporting the HDF library
Programming languages supporting the HDF library
What is the HDF library and how can it be used?
The HDF library is a collection of software routines that provides two types of interfaces which allow the user to work with HDF files. A brief capsule describing these interfaces is provided below:
Application Programming Interfaces (APIs)
Components of the HDF library include the base library, the multi-file library, the jpeg library, and the gzip library. The most recent versions of HDF also contain a Java Products, which includes a Java HDF Interface (JHI) and a Java-based HDF viewer.
The HDF library also provides a set of command-line utilities that allow the user to work with HDF files outside of the interfaces and within the command level (such as UNIX) of a terminal session. Outside of the HDF library, there is also a large number of browsing and visualization software packages (both free and commercial) that allow the user to look at all types of HDF files. These two methods will be discussed later in the tutorial.
Obtaining and installing the HDF library
The HDF library and utilities are public domain software and are freely available, along with documentation, from the NCSA anonymous ftp server. The source code of the latest release of the HDF library can be downloaded via ftp from the NCSA Current HDF release. Associated documentation and reference material can also be obtained from NCSA Current HDF Documentation. The source code of the HDF library, as well as utilities and iclude files, are available for each platform with each "release" of HDF and can be downloaded free of charge from this ftp site. These pre-compiled binaries for all supported platforms for the HDF4.1r3 Library may also be obtained from the GSFC DAAC.
Unfortunately, the HDF library may not be accessed by every computer platform. The following sections list the platforms and operating systems on which the latest release of HDF has been tested.
NCSA provides a binary distribution for those platforms supported by HDF. For platforms that are not specifically supported, the HDF source code is provided.
How do you install HDF on your computer system? Detailed directions for configuring and installing the latest version of HDF can be found in the README and INSTALL files located in the HDF_Current unpacked subdirectory of the NCSA HDF ftp server. The INSTALL file also includes information specific to various platforms, including Windows 95/NT.
In order to use the HDF library through C and FORTRAN programs, the user's computer must have either a C or FORTRAN library linked with the HDF library.
For those users who wish to work with HDF using Java, Version 2.5 of the HDF Java Products has been released as part of the latest release of the HDF library. Included in these products is the Java HDF Interface (JHI) for the HDF library. The JHI provides an interface to all the functions of the HDF library and may be used by any Java application to work with HDF files. The necessary Java source code can be downloaded from ftp.ncsa.uiuc.edu/HDF/HDF/HDF_Current/java.
These are the only languages which can call HDF routines (more detailed information in "Programming languages supporting the HDF library").
Computer platforms supporting the HDF library
The latest version of the HDF library as of summer 2000 is HDF 4.1 Release 3. As of the latest release, the HDF library has been tested and is currently beiung supported on the following computer platforms and operating systems:
Earlier versions or releases of the HDF library can still be used but may not be compatible with the platforms listed above.
Programming languages supporting the HDF library
As of the current release of HDF (HDF 4.1r3), the only programming languages which are supported by the HDF library are C and FORTRAN. Although the HDF library code is only written in C, the library provides both a FORTRAN and Java Interface which converts the code to C and allows the user to call the HDF 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 function. In addition, to use and compile HDF 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").
One of the features of the HDF library is that it creates free format FORTRAN include files during the "make" process on UNIX platforms. This allows FORTRAN 90 programs to use HDF include files. The FORTRAN 90 files are designated by the ".f90" file extension.
Another recent update to the HDF library is the inclusion of the Java HDF Interface (JHI) as part of HDF version 4.1r3. The JHI provides an interface to all HDF functions and must be obtained and installed in order to use Java to work with HDF files. Please see Obtaining and installing the HDF library for further details.
As of July 1999 and the latest release of the HDF library (4.1r3), the only platforms that support the JHI are:
The following examples (for UNIX platforms) illustrate the general method of compiling the HDF library using both C and FORTRAN programs. It should be noted that, for C programs, the line "include mfhdf.h" must be included if using the mfhdf library OR the line "include hdf.h" if it is not being used. Also worth noting is that, as indicated below, the following libraries must be specified in the following order- libmfhdf.a, libdf.a, libjpeg.a, and libz.a.
C programs
cc -o <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
FORTRAN programs
f77 -o <your program> <your program>.f -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
Specific examples for various platforms are provided below. If the platform you use is not listed, the general instructions should be followed.
The latest platform related information can be found on the NCSA anonymous ftp server at HDF4.1r3/release_notes/compile.txt.
INSTRUCTIONS FOR SPECIFIC PLATFORMS
Cray C90 or YMP:
C:
cc -O -s -o <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
FORTRAN:
cf77 -O 1 -s -o <your program> <your program>.f -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
Dec Alpha/Digital Unix:
C:
cc -Olimit 2048 -std1 -o <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
FORTRAN:
f77 -o <your program> <your program>.f -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
Exemplar:
C:
cc -ext -nv -no <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
FORTRAN:
fc -sfc -72 -o <your program> <your program>.f -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
HP - UX:
C:
cc -Ae -O -o <your program> <your program>. -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
FORTRAN:
f77 -O -o <your program> <your program>.f -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
IRIX 5.3:
C:
cc -ansi -O -s -o <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
FORTRAN:
f77 -O -s -o <your program> <your program>.f -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
IRIX 6.x with 64-bit mode:
C:
cc -ansi -64 -mips4 -O -s -o <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
FORTRAN:
f77 -64 -mips4 -O -s -o <your program> <your program>.f -I<path for hdf include directory>\ -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
Linux A.OUT And ELF:
C:
gcc -ansi -o <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
FORTRAN (a.out only):
f77 -o <your program> <your program>.f -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
Solaris:
The -lnsl is necessary in order to include the xdr library.
C:
cc -Xc -xO2 -o <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz -L/usr/lib -lnsl
FORTRAN:
f77 -O -o <your program> <your program>.f -I<path for hdf include directory>-L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz -L/usr/lib -lnsl
Solaris_x86 (C only):
The -lnsl is necessary in order to include the xdr library.
gcc -ansi -O -o <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz -L/usr/lib -lnsl
SP2 (AIX):
C:
xlc -qlanglvl=ansi -O -o <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
FORTRAN:
f77 -O -o <your program> <your program>.f -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
SunOS:
C:
gcc -ansi -o <your program> <your program>.c -I<path for hdf include directory> -L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
FORTRAN:
f77 -f -o <your program> <your program>.f -I<path for hdf include directory>-L<path for hdf libraries> -lmfhdf -ldf -ljpeg -lz
VAX OpenVMS:
To compile your programs, prog.c and prog1.for, with the HDF library, mfhdf.olb, df.olb, and libz.olb are required. The libjpeg.olb library is optional.
cc/DECC/STANDARD=VAXC/opt/nodebug/define=(HDF,VMS)/nolist/include=-<dir for include> prog.c
fort prog1.for
link/nodebug/notraceback/exec=prog.exe prog.obj, prog1.obj, -<dir for lib>mfhdf/lib -<dir for lib>df/lib, <dir for lib>libjpeg/lib, -<dir for lib>libz/lib, sys$library:deccrtl/lib
NOTE: The order of the libraries is important: mfhdf.olb first,followed by df.olb then libjpeg.olb and libz.olb.
Windows NT / 95:
Using Microsoft Visual C++ version 4.x:
C:\MSDEV\INCLUDE
C:\MSDEV\MFC\INCLUDE
C:<path to HDF includes>\INCLUDE
C:\MSDEV\LIB
C:\MSDEV\MFC\LIB
C:<path to HDF libs>\LIB
libsrc.lib src.lib jpeg.lib zlib.lib xdr.lib getopt.lib
kernel32.lib user32.lib gdi32.lib winspool.lib comdig32.lib advapi32lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib
The so-called low-level interface provides software that enables the user to work with such file features as memory, error handling, and storage. However, these features and the software are more of interest to the experienced programmer and software developer not the HDF novice or beginner interested in learning to read and write HDF files.
Information on the low-level interface can be found in the documentation listed in Section 2 Where can I get additional and detailed information on HDF?
Application Programming Interfaces (APIs)
Of more use to the average HDF user are the high-level or Application Programming Interfaces (APIs). These APIs are sets of routines that can be called in the user's FORTRAN or C program and which will allow the user to access, read, and write HDF files. There are APIs specifically created for each of the different data types supported by HDF which allow the user to work with HDF files.
Further detail is provided in Section 4 - Methods of Working with HDF Files.
On UNIX, VMS, and Windows NT/95, the binary distribution includes the pre-compiled libraries, utilities, include files, man pages, and release notes. The binary distribution on the Macintosh does not include the utilities.
The binaries are located in the following directories on the NCSA ftp server (ftp.ncsa.uiuc.edu):
If you uncompressed the binaries for a supported platform, you would (in general) find the following directories:
../bin - pre-compiled utilities
../include - include files
../lib - libraries
../man - man pages
../release_notes - release notes
The compressed source code can be found on the ftp server in /HDF/HDF_Current/tar. An uncompressed version of the source code can be found in /HDF/HDF_Current/unpacked.
To compile and install the HDF libraries from the source code, please read through the READ and INSTALL files in the top directory of the source code. In general, these are the steps you would take to compile and install HDF:
./configure -v
make >& comp.out
make test >& test.out
make install