1
Introduction to the HDF APIs
1.1 Overview of the HDF Interfaces
The HDF library structure consists of three interface layers built upon a physical file format. (See Figure 1a.) The first layer, or the low-level interface, is generally reserved for software developers because it provides support for low-level details such as file I/O, error handling, and memory management. The second layer, containing the single and multifile application interfaces, consists of a set of interfaces designed to simplify the process of storing and accessing data. The single file interfaces are operate on one file at a time, whereas the multifile interfaces can operate on several simultaneously. The highest HDF layer includes a collection of command-line utilities that operate on HDF files or the data objects they contain.
FIGURE 1a The Three Levels of Interaction with the HDF File Format
1.2 The Low-Level Interface 1.2.1 The H Interface
The low-level H interface provides a collection of routines, whose names begin with the letter H, for managing HDF files. 1.2.2 The HDF Interface
The names of these routines are prefaced by 'HDF'. As HDF begins expanding its interfaces to include mult-file support for each data model, it is anticipated that the some H routines will evolve into an HDF interface. There are only two such routines, HDFopen and HDFclose. HDFopen and HDFclose currently operate as macros for Hopen and Hclose respectively. 1.2.3 The HE Interface
The HDF library incorporates an error stack via the HE interface. In addition to other functions, the HE routines add information onto the error stack, print information from the stack, and clear the stack. 1.3.1 8-bit Raster Image Sets: The DFR8 Interface
The HDF 8-bit raster interface provides a collection of routines for managing 8-bit raster image sets. Any 8-bit raster image accompanied by its dimension record is recognized as an 8-bit raster image set. Raster image sets may also include a palette. 1.3.2 Palettes: The DFP Interface
The HDF palette interface provides a collection of routines for managing palette data. This interface is most often used for working with multiple palettes stored in a single file or palettes not specifically assigned to a raster image. 1.3.3 24-bit Raster Image Sets: The DF24 Interface
The HDF 24-bit raster interface provides a collection of routines for managing 24-bit raster image sets. Any 24-bit raster image array accompanied by its dimension record is recognized as a 24-bit raster image set. 1.3.4 Scientific Data Sets: The Single File DFSD Interface
There are two HDF interfaces that support multi-dimensional arrays: the single-file DFSD interface described here, which permits access to only one file at a time, and the newer multifile SD interface, which permits simultaneous access to more than one file. 1.3.5 Annotations: The DFAN Interface
The single-file annotation interface provides a collection of routines for reading and writing text strings assigned to HDF data objects or files. Annotations consist of labels and descriptions. A label is a null-terminated sequence of characters. 1.4.1 Scientific Data Sets: The SD Interface
The scientific data set interface provides a collection of routines for reading and writing arrays of arbitrary dimension and number type. Multidimensional arrays accompanied by a record of their dimension and number type are called scientific data sets. Under the multifile interface, scientific data sets may include predefined or user defined attribute records. Each attribute record is optional and describes a particular facet of the environment from which the scientific data was taken. 1.4.2 Multifile Annotations: The AN Interface
The purpose of the AN multifile annotation interface is to permit concurrent operations on a set of annotations that exist in more than one file. The design of the AN interface is similar to the multifile interfaces for raster image (GR) and scientific data set objects (SD). 1.4.3 General Raster Images: The GR Interface
The routines in the GR interface provide for multifile operations on general raster (GR) image data sets. 1.4.4 Scientific Data Sets: The netCDF Interface
The SD interface is designed to be as interoperable as possible with netCDF, an interface developed by the Unidata Program Center. Consequently, the SD interface can read files written by the netCDF interface, and the netCDF interface (as implemented in HDF) can read both netCDF files and HDF files that contain scientific data sets. 1.4.5 Vdata: The VS Interface
The VS interface provides a collection of routines for reading and writing customized tables. Each table is comprised of a series of vdata records whose values are stored in fixed length fields. In addition to its records, a vdata may contain three kinds of identifying information: a vdata name, vdata class, and several vdata field names. 1.4.6 Vdata Query: The VSQ Interface
The VSQ interface provides a collection of routines for inquiring about existing Vdata. These routines provide information such as the number of records in a Vdata, its field names, number types, and name. All routines in the VSQ interface are prefaced by 'VSQ'. 1.4.7 Vdata Fields: The VF Interface
The VF interface provides a collection of routines for inquiring about the fields in an existing Vdata. These routines provide information such as the field name, size, order, and number type. 1.4.8 Vgroups: The V Interface
The vgroup interface provides a collection of routines for reading and writing customized data sets. Each vgroup may contain one or more vdatas, vgroups, or data objects stored via other HDF data models. In addition to its members, a vgroup may also be given a vgroup name and a vgroup class. 1.4.9 High-Level Vdata/Vgroups: The VH Interface
The high-level VH interface provides a collection of routines for creating simple vdatas and vgroups with a single function call. All routines in this interface are prefaced by 'VH'. 1.4.10 Vgroup Inquiry: The VQuery Interface
The high-level VQ interface provides one routine that returns tag information from a specified vgroup, and one routine that returns reference number information from a specified vgroup. All C routine names in this interface are prefaced by 'VQuery'. 1.5.1 Fortran-77-to-C Translation
Nearly all of the HDF library code is written in C. The Fortran-77 HDF API routines translate all parameter data types to C data types, then call the C routine that performs the main function. For example, d8aimg is the Fortran-77 equivalent for DFR8addimage. Calls to either routine execute the same C code that adds an 8-bit raster image to an HDF file - see the following figure.FIGURE 2b Use of a Function Call Converter to Route Fortran-77 HDF Calls to the C Library
1.5.2 Case Sensitivity
Fortran-77 identifiers generally are not case sensitive, whereas C identifiers are. Although all of the Fortran-77 routines shown in this manual are written in lower case, Fortran-77 programs can generally call them using either upper- or lower-case letters without loss of meaning. 1.5.3 Name Length
Because some Fortran-77 compilers only interpret identifier names with seven or fewer characters, the first seven characters of the Fortran-77 HDF routine names are unique. 1.5.4 Header Files
The inclusion of header files is not generally permitted by Fortran-77 compilers. However, it is sometimes available as an option. On UNIX systems, for example, the macro processors m4 and cpp let your compiler include and preprocess header files. If this capability is not available, you may have to copy whatever declarations, definitions, or values you need from the "constants.f" file into your program code. If it is, include the header file named "hdf.inc" in your Fortran-77 code. The "constants.f" file is included in the "hdf.inc" header file. 1.5.5 Data Type Specifications
When mixing machines, compilers, and languages, it is difficult to maintain consistent data type definitions. For instance, on some machines an integer is a 32-bit quantity and on others, a 16-bit quantity. In addition, the differences between Fortran-77 and C lead to difficulties in describing the data types found in the argument lists of HDF routines. To maintain portability, the HDF library expects assigned names for all data types used in HDF routines. (See TABLE 2A)
TABLE 2A Data Type Definitions
As Fortran-90 is a superset of Fortran-77, HDF programs should compile and run correctly when using a Fortran-90 compiler.
1.6 Error Codes
The error codes defined in the HDF library are defined in the following table.