![]() |
HDF Reference Manual |
Section 1Introduction to the HDF APIs1.1 Overview of the HDF Interfaces
The HDF library structure consists of two interface layers and one application layer 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 operate on one file at a time, whereas the multifile interfaces can operate on several files simultaneously. The highest HDF layer includes various NCSA and commercial applications and a collection of command-line utilities that operate on HDF files or the data objects they contain.
FIGURE 1a Three Levels of Interaction with the HDF File1.2 Low-Level Interface
This is the layer of HDF reserved for software developers and provides routines for error handling, file I/O, memory management, and physical storage. These routines are prefaced with 'H'. For a more detailed discussion of the low-level interface, consult the HDF Specifications and Developer's Guide from the HDF WWW home page at http://www.hdfgroup.org.
The low-level interface provides a collection of routines that are prefaced with either 'H', 'HE', or 'HX'. The H routines are for managing HDF files. The HE routines provide error handlings. The HX routines are for managing HDF external files.
Prior to HDF version 3.2, all low-level routines began with the prefix 'DF'. As of HDF version 3.3, the DF interface was no longer recommended for use. It is only supported to maintain backward compatibility with programs and files created under earlier versions of the HDF library.
1.3 Multifile Application Interfaces
The HDF multifile interfaces are designed to allow operations on more than one file and more than one data object at the same time. The multifile interfaces provided are AN, GR, SD, VS, VSQ, VF, V, and VH. The AN interface is the multifile version of the DFAN annotation interface. The GR interface is the multifile version of the 8- and 24-bit raster image interfaces. The SD interface is the multifile version of the scientific data set interface. The VS, VSQ, and VF interfaces support the vdata model. The V and VH interfaces provide support for the vgroup data model.
Like the single-file interfaces, the multifile interfaces are built upon the low-level H routines. Unlike single-file operations, operations performed via a multifile interface are not implicitly preceded by Hopen and followed by Hclose. Instead, each series of operations on a file must be preceded by an explicit call to open and close the file. Once the file is opened, it remains open until an explicit call is made to close it. This process allows operations on more than one file at a time.
1.3.1 Scientific Data Sets: SD Interface
The scientific data set interface provides a collection of routines for reading and writing arrays of data. 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 can be used to note or describe about the data being stored in scientific data sets.
The SD interface is designed to be as compatible as possible with netCDF, an interface developed by the Unidata Program Center and used to store and manipulate scientific data sets. Consequently, the SD interface can read files written by the netCDF interface, and the netCDF interface version 2.3.2 (as implemented in HDF) can read both netCDF files and HDF files that contain scientific data sets.
Further information regarding the netCDF interface routines and their equivalents in the HDF netCDF interface can be found in the HDF User's Guide, Section 3.15, "netCDF." Additional information on the netCDF interface can be found in the netCDF User's Guide available at http://www.unidata.ucar.edu/software/netcdf/docs/.
The names of the routines in the multifile scientific data set interface are prefaced by 'SD'. The equivalent FORTRAN-77 routine names are prefaced by 'sf'.
1.3.2 Annotations: 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. Annotations consist of labels and descriptions.
The C routine names of the multifile annotation interface are prefaced by the string 'AN' and the FORTRAN-77 routine names are prefaced by 'af'.
1.3.3 General Raster Images: GR Interface
The routines in the GR interface provide multifile operations on general raster image data sets.
The C routine names in the general raster interface have the prefix 'GR' and the equivalent FORTRAN-77 routine names are prefaced by 'mg'.
1.3.4 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 records whose values are stored in fixed length fields. In addition to its records, a vdata may contain four kinds of identifying information: a name, class, data type and a number of field names.
Routines in the VS interface are prefaced by 'VS'. The equivalent FORTRAN-77 routine names are prefaced by 'vsf'.
1.3.5 Vdata Query: 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'. The equivalent FORTRAN-77 routine names are prefaced by 'vsq'.
1.3.6 Vdata Fields: 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.
All routines in the VF interface are prefaced by 'VF'. There are no equivalent FORTRAN-77 functions.
1.3.7 Vgroups: V Interface
The vgroup interface provides a collection of routines for grouping and manipulating HDF data objects in the file. Each vgroup may contain one or more vdatas, vgroups, or other HDF data objects. In addition to its members, a vgroup may also be given a name and a class.
Every routine name in the vgroup interface are prefaced by 'V'. The equivalent FORTRAN-77 routine names are prefaced by 'vf'.
1.3.8 Vdata/Vgroups: 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'. The equivalent FORTRAN-77 routine names are prefaced by 'vh'.
1.3.9 Vgroup Inquiry: VQ 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 'VQ'. The equivalent Fortran-77 routine names are prefaced by 'vq'.
1.4 Single-File Application Interfaces
The HDF single-file application interfaces include several independent modules each is designed to simplify the process of storing and accessing a specific type of data. These interfaces support the 8-bit raster image(DFR8), 24-bit raster image (DF24), palette (DFP), scientific data (DFSD), and annotation (DFAN) models. All single-file interfaces are built upon the H routines - unless otherwise specified, all the low-level details can be ignored.
1.4.1 24-bit Raster Image Sets: DF24 Interface
The HDF 24-bit raster interface provides a collection of routines for managing 24-bit raster image sets. A 24-bit raster image set is comprised of a 24-bit raster image array and its accompanied dimension record. Raster image sets may also include a palette.
The names of the routines in the 24-bit raster interface are prefaced by 'DF24'. The equivalent FORTRAN-77 routine names are prefaced by 'd2'.
1.4.2 8-bit Raster Image Sets: DFR8 Interface
The HDF 8-bit raster interface provides a collection of routines for managing 8-bit raster image sets. An 8-bit raster image set is comprised of an 8-bit raster image array and its accompanied dimension record. Raster image sets may also include a palette.
Every function in the 8-bit raster interface begins with the prefix 'DFR8'. The equivalent FORTRAN-77 functions use the prefix 'd8'.
1.4.3 Palettes: 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.
The names of the routines in the palette interface are prefaced by 'DFP'. The equivalent FORTRAN-77 routine names are prefaced by 'dp'.
1.4.4 Scientific Data Sets: DFSD Interface
There are two HDF interfaces that support multidimensional 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. The existence of the single-file scientific data set interface is simply to support backward compatibility for previously created files and applications. It is recommended that the multifile scientific data set interface is to be used where possible.
The single-file scientific data set interface provides a collection of routines for reading and writing arrays of data. A scientific data set is comprised of a scientific data array and its accompanied rank, name and number type. Scientific data sets may also include predefined attribute records.
The names of the routines in the single-file scientific data set interface are prefaced by 'DFSD'. The equivalent FORTRAN-77 routine names are prefaced by 'ds'.
1.4.5 Annotations: 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.
The names of the routines in the single-file annotation interface are prefaced by 'DFAN'. The equivalent FORTRAN-77 routine names are prefaced by 'da'.
1.5 FORTRAN-77 and C Language Issues
In order to make the FORTRAN-77 and C versions of each routine as similar as possible, some compromises have been made in the process of simplifying the interface for both programming languages.
1.5.1 FORTRAN-77-to-C Translation
Nearly all of the HDF library code is written in C. The Fortran 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 1b Use of a Function Call Converter to Route FORTRAN-77 HDF Calls to the C Library1.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
andcpp
let the compiler include and preprocess header files. If this capability is not available, the user may have to copy the declarations, definitions, and values needed from the filesdffunc.inc
andhdf.inc
into the user application. If the capability is available, the files can be included in the Fortran code. The files reside in theinclude/
subdirectory of the directory where the HDF library is installed on the user's system.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 number types used in HDF routines. (See Table 1A.)
TABLE 1A Number Type DefinitionsWhen using a FORTRAN-77 data type that is not supported, the general practice is to use another data type of the same size. For example, an 8-bit signed integer can be used to store an 8-bit unsigned integer variable unless the code relies on a sign-specific operation.
1.5.6 String and Array Specifications
In the declarations contained in the headers of FORTRAN-77 functions, the following conventions are followed:
- character*(*) x means that x refers to a string of an indefinite number of characters. It is the responsibility of the calling program to allocate enough space to hold the data to be stored in the string.
- real x(*) means that x refers to an array of reals of indefinite size and of indefinite rank. It is the responsibility of the calling program to allocate an actual array with the correct number of dimensions and dimension sizes.
- <valid numeric data type > x means that x may have one of the numeric data types listed in the Description column of Table 1A on page 5.
- <valid data type > x means that x may have any of the data types listed in the Description column of Table 1A on page 5.
1.5.7 FORTRAN-77, ANSI C and K&R C
As much as possible, we have conformed the HDF API routines to those implementations of Fortran and C that are in most common use today, namely FORTRAN-77, ANSI C and K&R C. Due to the increasing availability of ANSI C, future versions of HDF will no longer support K&R C.
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 listed in the following table.
TABLE 1B HDF Error Codes
HDF 4.2.6 - June 2011 Copyright |
The HDF Group www.hdfgroup.org ![]() |