[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
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
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
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
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
[Top] [Prev] [Next] [Bottom]
hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF
Development Group.