[Top] [Prev] [Next] [Bottom]

2.6 Basic Operations on HDF Files

The HDF programming model specifies that a data file be first explicitly opened by an application, then manipulated, then explicitly closed by the application code at the end of its execution. To use the routines designed to open and close data files, the user must first know about the file identifiers used by the HDF API routines.

2.6.1 File Identifiers

HDF data files are uniquely identified by either a filename or a file identification number, or file id. The filename is the name of the file as represented in the native filesystem, and is created along with the file itself through the HDF file creation routine. The file id is the numeric identifier given to the file by the HDF library, also at the time of creation, and is generally only used by the HDF library routines; the HDF user need not keep track of them.

As every file is assigned its own identifier, the order in which files are accessed is very flexible. For example, it is perfectly valid to open a file and obtain an identifier for it, then open a second file without closing the first file or disposing of the first file identifier. The only requirement made by HDF is that all file ids be individually discarded before the termination of the calling program.

File identifiers created by any HDF API routine cannot be used by the routines of any other interface - they are not interchangeable.

2.6.2 Opening HDF Files: Hopen

The Hopen routine opens or creates an HDF data file, depending on the access mode specified, and returns the file id the HDF library has assigned it. The parameter names and data types are listed in Table 2E below. Refer also to the HDF Reference Manual for additional information on Hopen and to Section 2.5 on page 11 for information regarding file access codes.

TABLE 2E Hopen Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Hopen

(hopen)

filename

char *

character8 (*)

File identifier.

access

intn

integer

Access mode definition.

n_dds

int16

integer*2

Number of data descriptors in a block if a new file is to be created.

2.6.3 Closing HDF Files: Hclose

The Hclose routine closes the file designated by the file id passed in as the file_id parameter. The parameter names and data types are listed in Table 2F below. Refer also to the HDF Reference Manual for additional information regarding Hclose.

TABLE 2F Hclose Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Hclose

(hclose)

file_id

int32

integer*4

File identifier.

2.6.4 Determining the Number of Objects with a Specified Tag: Hnumber

Hnumber determines how many objects with the specified tag exist within a file. To count the total number of objects in a file, set the tag argument to DFTAG_WILDCARD. Note that a return value of 0 is not a error condition. The parameter names and data types are listed in Table 2G below. Refer also to the HDF Reference Manual for additional information regarding Hnumber.

TABLE 2G Hnumber Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

Hnumber

(hnumber)

file_id

int32

integer*4

File identifier.

tag

int32

uint16

Tag to be counted.

2.6.5 Getting the HDF Library Version Used to Create a File: Hgetlibversion

Hgetlibversion returns the version of the HDF library currently being used, as well as additional textual information regarding the library. The parameter names and data types are listed in Table 2H below. Refer also to the HDF Reference Manual for additional information regarding Hgetlibversion.

TABLE 2H Hgetlibversion Parameter List
Function Name

(Fortran-77)

Parameter

Data Type

Description

C

Hgetfileversion

major_v

uint32 *

Major version number.

minor_v

uint32 *

Minor version number.

release

uint32 *

Complete library version number.

string

char [80]

Additional information about the library version.

2.6.6 Locate an Object by its Tag/Reference Number Pair: Hfind

Hfind, like all H functions, must be preceded by a call to Hopen and followed at some point by a call to Hclose.

Although Hfind is capable of executing many kinds of search operations, it is particularly useful for determining the valid reference numbers for any specified tag. When supplied with a recognized HDF tag, a wildcarded reference number and a search direction, Hfind will search sequentially through the objects stored in an HDF file until the first data object with the specified tag is encountered. Once the data object is discovered, Hfind will return its reference number. By using Hfind in a conditional loop the reference number for any or all data objects in an HDF file can be retrieved. For more about Hfind consult the HDF Reference Guide.

TABLE 2I Hfind Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Hfind

major_v

uint32 *

Major version number.

minor_v

uint32 *

Minor version number.

release

uint32 *

Complete library version number.

string

char [80]

Additional information about the library version.



[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.