The HDF Group

HDF Reference Manual


Section 1
Introduction to the HDF APIs

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

1.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 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 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 files dffunc.inc and hdf.inc into the user application. If the capability is available, the files can be included in the Fortran code. The files reside in the include/ 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 Definitions
Definition Name
Definition Value
Description
DFNT_CHAR8
4
8-bit character type
DFNT_CHAR
4
Same as DFNT_CHAR8
DFNT_UCHAR8
3
8-bit unsigned character type
DFNT_UCHAR
3
Same as DFNT_UCHAR8
DFNT_INT8
20
8-bit integer type
DFNT_UINT8
21
8-bit unsigned integer type
DFNT_INT16
22
16-bit integer type
DFNT_UINT16
23
16-bit unsigned integer type
DFNT_INT32
24
32-bit integer type
DFNT_UINT32
25
32-bit unsigned integer type
DFNT_FLOAT32
5
32-bit floating-point type
DFNT_FLOAT64
6
64-bit floating-point type
DFNT_NINT8
(DFNT_NATIVE | DFNT_INT8)
8-bit native integer type
DFNT_NUINT8
(DFNT_NATIVE | DFNT_UINT8)
8-bit native unsigned integer type
DFNT_NINT16
(DFNT_NATIVE | DFNT_INT16)
16-bit native integer type
DFNT_NUINT16
(DFNT_NATIVE | DFNT_UINT16)
16-bit native unsigned integer type
DFNT_NINT32
(DFNT_NATIVE | DFNT_INT32)
32-bit native integer type
DFNT_NUINT32
(DFNT_NATIVE | DFNT_UINT32)
32-bit native unsigned integer type
DFNT_NFLOAT32
(DFNT_NATIVE | DFNT_FLOAT32)
32-bit native floating-point type
DFNT_NFLOAT64
(DFNT_NATIVE | DFNT_FLOAT64)
64-bit native floating-point type

When 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:

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
Error Code
Code Definition
DFE_NONE
No error.
DFE_FNF
File not found.
DFE_DENIED
Access to file denied.
DFE_ALROPEN
File already open.
DFE_TOOMANY
Too many AID's or files open.
DFE_BADNAME
Bad file name on open.
DFE_BADACC
Bad file access mode.
DFE_BADOPEN
Miscellaneous open error.
DFE_NOTOPEN
File can't be closed because it hasn't been opened.
DFE_CANTCLOSE
fclose error
DFE_READERROR
Read error.
DFE_WRITEERROR
Write error.
DFE_SEEKERROR
Seek error.
DFE_RDONLY
File is read only.
DFE_BADSEEK
Attempt to seek past end of element.
DFE_PUTELEM
Hputelement error.
DFE_GETELEM
Hgetelement error.
DFE_CANTLINK
Cannot initialize link information.
DFE_CANTSYNC
Cannot synchronize memory with file.
DFE_BADGROUP
Error from DFdiread in opening a group.
DFE_GROUPSETUP
Error from DFdisetup in opening a group.
DFE_PUTGROUP
Error on putting a tag/reference number pair into a group.
DFE_GROUPWRITE
Error when writing group contents.
DFE_DFNULL
Data file reference is a null pointer.
DFE_ILLTYPE
Data file contains an illegal type: internal error.
DFE_BADDDLIST
The DD list is non-existent: internal error.
DFE_NOTDFFILE
The current file is not an HDF file and it is not zero length.
DFE_SEEDTWICE
The DD list already seeded: internal error.
DFE_NOSUCHTAG
No such tag in the file: search failed.
DFE_NOFREEDD
There are no free DD's left: internal error.
DFE_BADTAG
Illegal WILDCARD tag.
DFE_BADREF
Illegal WILDCARD reference number.
DFE_NOMATCH
No DDs (or no more DDs) that match the specified tag/reference number pair.
DFE_NOTINSET
Warning: Set contained unknown tag. Ignored.
DFE_BADOFFSET
Illegal offset specified.
DFE_CORRUPT
File is corrupted.
DFE_NOREF
No more reference numbers are available.
DFE_DUPDD
The new tag/reference number pair has been allocated.
DFE_CANTMOD
Old element doesn't exist. Cannot modify.
DFE_DIFFFILES
Attempt to merge objects in different files.
DFE_BADAID
An invalid AID was received.
DFE_OPENAID
Active AIDs still exist.
DFE_CANTFLUSH
Cannot flush DD back to file.
DFE_CANTUPDATE
Cannot update the DD block.
DFE_CANTHASH
Cannot add a DD to the hash table.
DFE_CANTDELDD
Cannot delete a DD in the file.
DFE_CANTDELHASH
Cannot delete a DD from the hash table.
DFE_CANTACCESS
Cannot access specified tag/reference number pair.
DFE_CANTENDACCESS
Cannot end access to data element.
DFE_TABLEFULL
Access table is full.
DFE_NOTINTABLE
Cannot find element in table.
DFE_UNSUPPORTED
Feature not currently supported.
DFE_NOSPACE
malloc failed.
DFE_BADCALL
Routine calls were in the wrong order.
DFE_BADPTR
NULL pointer argument was specified.
DFE_BADLEN
Invalid length was specified.
DFE_NOTENOUGH
Not enough space for the data.
DFE_NOVALS
Values were not available.
DFE_ARGS
Invalid arguments passed to the routine.
DFE_INTERNAL
Serious internal error.
DFE_NORESET
Too late to modify this value.
DFE_GENAPP
Generic application level error.
DFE_UNINIT
Interface was not initialized correctly.
DFE_CANTINIT
Cannot initialize the interface the operation requires.
DFE_CANTSHUTDOWN
Cannot shut down the interface the operation requires.
DFE_BADDIM
Negative number of dimensions, or zero dimensions, was specified.
DFE_BADFP
File contained an illegal floating point number.
DFE_BADDATATYPE
Unknown or unavailable data type was specified.
DFE_BADMCTYPE
Unknown or unavailable machine type was specified.
DFE_BADNUMTYPE
Unknown or unavailable number type was specified.
DFE_BADORDER
Unknown or illegal array order was specified.
DFE_RANGE
Improper range for attempted access.
DFE_BADCONV
Invalid data type conversion was specified.
DFE_BADTYPE
Incompatible types were specified.
DFE_BADSCHEME
Unknown compression scheme was specified.
DFE_BADMODEL
Invalid compression model was specified.
DFE_BADCODER
Invalid compression encoder was specified.
DFE_MODEL
Error in the modeling layer of the compression operation.
DFE_CODER
Error in the encoding layer of the compression operation.
DFE_CINIT
Error in encoding initialization.
DFE_CDECODE
Error in decoding compressed data.
DFE_CENCODE
Error in encoding compressed data.
DFE_CTERM
Error in encoding termination.
DFE_CSEEK
Error seeking in an encoded dataset.
DFE_MINIT
Error in modeling initialization.
DFE_COMPINFO
Invalid compression header.
DFE_CANTCOMP
Cannot compress an object.
DFE_CANTDECOMP
Cannot decompress an object.
DFE_NOENCODER
Encoder not available.
DFE_NOSZLIB
SZIP library not available.
DFE_COMPVERSION
Version error from zlib
Note: when Z_VERSION_ERROR (-6) returned from zlib.
DFE_READCOMP
Error in reading compressed data.
Note: when one of the following error codes returned from zlib:
Z_ERRNO (-1)
Z_STREAM_ERROR (-2)
Z_DATA_ERROR (-3)
Z_MEM_ERROR (-4)
Z_BUF_ERROR (-5)
DFE_NODIM
A dimension record was not associated with the image.
DFE_BADRIG
Error processing a RIG.
DFE_RINOTFOUND
Cannot find raster image.
DFE_BADATTR
Invalid attribute.
DFE_BADTABLE
The nsdg table has incorrect information.
DFE_BADSDG
Error in processing an SDG.
DFE_BADNDG
Error in processing an NDG.
DFE_VGSIZE
Too many elements in the vgroup.
DFE_VTAB
Element not in vtab[].
DFE_CANTADDELEM
Cannot add the tag/reference number pair to the vgroup.
DFE_BADVGNAME
Cannot set the vgroup name.
DFE_BADVGCLASS
Cannot set the vgroup class.
DFE_BADFIELDS
Invalid fields string passed to vset routine.
DFE_NOVS
Cannot find the vset in the file.
DFE_SYMSIZE
Too many symbols in the users table.
DFE_BADATTACH
Cannot write to a previously attached vdata.
DFE_BADVSNAME
Cannot set the vdata name.
DFE_BADVSCLASS
Cannot set the vdata class.
DFE_VSWRITE
Error writing to the vdata.
DFE_VSREAD
Error reading from the vdata.
DFE_BADVH
Error in the vdata header.
DFE_VSCANTCREATE
Cannot create the vdata.
DFE_VGCANTCREATE
Cannot create the vgroup.
DFE_CANTATTACH
Cannot attach to a vdata or vset.
DFE_CANTDETACH
Cannot detach a vdata or vset with write access.
DFE_BITREAD
A bit read error occurred.
DFE_BITWRITE
A bit write error occurred.
DFE_BITSEEK
A bit seek error occurred.
DFE_TBBTINS
Failed to insert the element into tree.
DFE_BVNEW
Failed to create a bit vector.
DFE_BVSET
Failed when setting a bit in a bit vector.
DFE_BVGET
Failed when getting a bit in a bit vector.
DFE_BVFIND
Failed when finding a bit in a bit vector.

HDF 4.2.6 - June 2011
Copyright
The HDF Group
www.hdfgroup.org
The HDF Group