[Top] [Prev] [Next]

2.3 Basic Operations on HDF Files Using the Multifile Interfaces

This section describes the basic file operations, some of which are required in working with HDF files using the multifile interfaces. Except for the SD interface, all applications using other multifile interfaces must explicitly use the routines Hopen and Hclose to control accesses to the HDF files. In an application using the HDF file format, the file is accessed via its identifier, referred to as file identifier. The following subsections describe the file identifier and the basic file operations common to most multifile interfaces.

2.3.1 File Identifiers

The HDF programming model specifies that a data file is first explicitly created or opened by an application, manipulated, then explicitly closed by the application. A file identifier is a unique number that the HDF library assigns to an HDF file when creating or opening the file. The HDF library creates the file identifier for an HDF file when given its file name, as represented in the native file system. Interface routines use only the file identifier to access and manipulate the file. When all operations on the file are complete, the file identifier must be discarded by explicitly closing the file before terminating the application.

As every file is assigned its own identifier, the order in which files are accessed is very flexible. For example, it is 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 identifiers be individually discarded before the termination of the calling program.

File identifiers created by the routine of one HDF interface can be used by the routines of any other interfaces, except SD's.

2.3.2 Opening HDF Files: Hopen

The routine Hopen creates or opens an HDF data file, depending on the access mode specified, and returns the file identifier that the HDF library has assigned to the file. The Hopen syntax is as follows:

C:		file_id = Hopen(filename, access_mode, num_dds_block);
FORTRAN:	file_id = hopen(filename, access_mode, num_dds_block)
The Hopen parameters are defined in Table 2A and the following discussion.

TABLE 2A - Hopen Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
Hopen

[int32]

(hopen)
filename
char *
character*(*)
File name

access_mode
intn
integer
File access mode

num_dds_block
int16
integer
Number of data descriptors in a data descriptor block

The parameter filename is a character string representing the name of the HDF file to be accessed.

The parameter access_mode specifies how the file should be accessed. All the access modes are listed in Table 2B. If the access mode is DFACC_CREATE and the file already exists, the file will be replaced by the new one. If the access mode is DFACC_READ and the file does not exist, Hopen will return FAIL (or -1). If the access mode is DFACC_WRITE and the file does not exist, a new file will be created.

The parameter num_dds_block specifies the number of data descriptors in a block when the access mode specified is create. If the access mode is not create, the value of num_dds_block is ignored. The default number of data descriptors in a block is 16 (defined as DEF_NDDS) data descriptors. The user may specify 0 to keep the default or any non-negative integer to reset this limit when creating the HDF file.

Note that, in the SD interface, SDstart is used to open files instead of Hopen. (Refer to Chapter 3, Scientific Data Sets (SD API), of this document for more information on SDstart.)

TABLE 2B - File Access Code Flags

File Access Flag
Flag Value
Description
DFACC_READ
1
Read access

DFACC_WRITE
2
Read and write access

DFACC_CREATE
4
Create with read and write access

2.3.3 Closing HDF Files: Hclose

The Hclose routine closes the file designated by the file identifier specified by the parameter file_id. The Hclose syntax is as follows:

C:		status = Hclose(file_id);
FORTRAN:	status = hclose(file_id)
Hclose returns a value of SUCCEED (or 0) if successful or FAIL (or -1) otherwise. The parameter name and type are listed in Table 2C. Refer also to the HDF Reference Manual for additional information regarding Hclose.

Note that Hclose is not used to close files in the SD interface. SDend is used for this purpose. (Refer to Chapter 3, Scientific Data Sets (SD API), of this document for more information on SDend.)

TABLE 2C - Hclose Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
Hclose

[intn] (hclose)

file_id
int32
integer
File identifier

2.3.4 Getting the HDF Library and File Versions: Hgetlibversion and Hgetfileversion

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 2D. Refer also to the HDF Reference Manual for additional information regarding Hgetlibversion.

Hgetfileversion returns the version information of the HDF file specified by the parameter file_id, as well as additional textual information regarding the nature of the file. The parameter names and data types are listed in Table 2D. Refer also to the HDF Reference Manual for additional information regarding Hgetfileversion.

The syntax of these routines is as follows:

C:		status = Hgetlibversion(&major_v, &minor_v, &release, string);
		status = Hgetfileversion(file_id, &major_v, &minor_v, &release, string);
FORTRAN:	status = hglibver(major_v, minor_v, release, string)
		status = hgfilver(file_id, major_v, minor_v, release, string)
Both routines return a value of SUCCEED (or 0) if successful or FAIL (or -1) otherwise.

TABLE 2D - Hgetlibversion and Hgetfileversion Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
Hgetlibversion

[intn]

(hglibver)
major_v
uint32*
integer
Major version number

minor_v
uint32*
integer
Minor version number

release
uint32*
integer
Complete library version number

string
char*
character*(*)
Additional information about the library version

Hgetfileversion

[intn]

(hgfilver)
file_id
int32
integer
File identifier

major_v
uint32*
integer
Major version number

minor_v
uint32*
integer
Minor version number

release
uint32*
integer
Complete library version number

string
char*
character*(*)
Additional information about the library version



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.