The HDF Group

HDF Reference Manual


[H Interface][Top]


Hclose/hclose

intn Hclose(int32 file_id)

file_id
IN:
File identifier returned by Hopen

Purpose
Closes the access path to the file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The file identifier file_id is validated before the file is closed. If the identifier is valid, the function closes the access path to the file.
 
If there are still access identifiers attached to the file, the error DFE_OPENAID is placed on the error stack, FAIL (or -1) is returned, and the file remains open. This is a common error when developing new interfaces. Refer to the Reference Manual page on Hendaccess for a discussion of this problem.

FORTRAN
integer function hclose(file_id)
 
integer file_id

[H Interface][Top]


Hgetfileversion/hgfilver

intn Hgetfileversion(int32 file_id, uint32 *major_v, uint32 *minor_v, uint32 *release, char string[])

file_id
IN:
File identifier returned by Hopen
major_v
OUT:
Major version number
minor_v
OUT:
Minor version number
release
OUT:
Release number
string
OUT:
Version number text string

Purpose
Retrieves version information for an HDF file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
It is still an open question as to what exactly the version number of a file should mean, so we recommend that code not depend on this buffer. The string argument is limited to a length of LIBVSTR_LEN (or 80) characters as defined in hfile.h.

FORTRAN
integer function hgfilver(file_id, major_v, minor_v, release, string)
 
integer file_id, major_v, minor_v, release
 
character*(*) string

[H Interface][Top]


Hgetlibversion/hglibver

intn Hgetlibversion(uint32 *major_v, uint32 *minor_v, uint32 *release, char string[])

major_v
OUT:
Major version number
minor_v
OUT:
Minor version number
release
OUT:
Release number
string
OUT:
Version number text string

Purpose
Retrieves the version information of the current HDF library.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The version information is compiled into the HDF library, so it is not necessary to have any open files for this function to execute. The string buffer is limited to a length of LIBVSTR_LEN (or 80) characters as defined in hfile.h.

FORTRAN
integer function hglibver(major_v, minor_v, release, string)
 
integer major_v, minor_v, release
 
character*(*) string

[H Interface][Top]


Hishdf/hishdff

intn Hishdf(char *filename)

filename
IN:
Complete path and filename of the file to be checked.

Purpose
Determines if a file is an HDF file.
Return value
Returns TRUE (or 1) if the file is an HDF file and FALSE (or 0) otherwise.
Description
The first four bytes of a file identify it as an HDF file. It is possible that Hishdf will identify a file as an HDF file but Hopen will be unable to open the file; for example, if the data descriptor list is corrupted.

FORTRAN
integer function hishdff(filename)
 
character*(*) filename

[H Interface][Top]


Hopen/hopen

int32 Hopen(char *filename, intn access, int16 n_dds)

filename
IN:
Complete path and filename for the file to be opened
access
IN:
Access code definition (preceded by DFACC_)
n_dds
IN:
Number of data descriptors in a block if a new file is to be created

Purpose
Provides an access path to an HDF file by reading all the data descriptor blocks into memory.
Return value
Returns the file identifier if successful and FAIL (or -1) otherwise.
Description
If given a new file name, Hopen will create a new file using the specified access type and number of data descriptors. If given an existing file name, Hopen will open the file using the specified access type and ignore the n_dds argument.
 
The number of data descriptors in a block, n_dds, is a non-negative integer with a default value of DEF_NDDS (or 16) and a minimum value of MIN_NDDS (or 4). If the specified value of n_dds is less than MIN_NDDS, then it will be set to MIN_NDDS.
 
HDF provides several access code definitions:
 
      DFACC_CREATE If file exists, delete it, then open a new file for read/write.
      DFACC_READ Open for read only. If file does not exist, return an error.
      DFACC_WRITE Open for read/write. If file does not exist, create it.
 
If a file is opened and an attempt is made to reopen the file using DFACC_CREATE, HDF will issue the error code DFE_ALROPEN. If the file is opened with read-only access and an attempt is made to reopen the file for write access using DFACC_WRITE, HDF will attempt to reopen the file with read and write permissions.
 
Upon successful exit, the specified file is opened with the relevant permissions, the data descriptors are set up in memory, and the associated file_id is returned. For new files, the appropriate file headers are also set up.
 
Note that it has been reported that opening/closing file in loops is very slow; thus, it is not recommended to perform such operations too many times, particularly, when data is being added to the file between opening/closing.

FORTRAN
integer function hopen(filename, access, n_dds)
 
character*(*) filename
 
integer access, n_dds

[H Interface][Top]


HCget_config_info

intn HCget_config_info(comp_coder_t coder_type, uint32 *compression_config_info)

coder_type
IN:
Type of compression
compression_config_info
OUT:
Flags indicating status of compression method

Purpose
Retrieves information about the configuration of a compression method.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
HCget_config_info retrieves the configuration status of the compression type specified by coder_type, returning that status information as flags in compression_config_info.
 
Valid values of coder_type are as follows:
 
COMP_CODE_NONE no compression
COMP_CODE_RLE RLE run-length encoding
COMP_CODE_NBIT NBIT compression
COMP_CODE_SKPHUFF Skipping Huffman compression
COMP_CODE_DEFLATE GZIP compression
COMP_CODE_SZIP Szip compression
COMP_CODE_JPEG JPEG compression
 
The compression method, coder_type, used for a data set can be obtained as the returned value of the comp_type parameter in an SDgetcompinfo call.
 
The configuration flags returned in compression_config_info include the following:
      0 Compression method is not enabled.
      COMP_DECODER_ENABLED Decoding is enabled.
      COMP_ENCODER_ENABLED Encoding is enabled.
 
If the returned value is COMP_DECODER_ENABLED|COMP_ENCODER_ENABLED, the compression method is enabled for both encoding and decoding.
 
In the general case, any available compression type can be configured in any mode:
COMP_DECODER_ENABLED
COMP_ENCODER_ENABLED
COMP_DECODER_ENABLED |COMP_ENCODER_ENABLED
 
As of this writing (HDF4 Release 2.1, February 2005), only the Szip compression library is actually used with the HDF libraries in more than one configuration (see immediately below.) As a third-party product, it is distributed in both decode-only and encode/decode configurations. All other compression methods are currently distributed or used in an encode/decode configuration if they are available at all, and HCget_config_info returns either 0 or COMP_DECODER_ENABLED|COMP_ENCODER_ENABLED when they are used.
 
Due to licensing requirements, the Szip library is available in both decode-only and encode/decode configurations. Therefore, the full range of values can be returned for Szip compression.
      o If the Szip version available on a system is decode-only, HCget_config_info will return COMP_DECODER_ENABLED in compression_config_info.
      o If the available Szip library is configured as encode/decode, compression_config_info will contain the value COMP_DECODER_ENABLED|COMP_ENCODER_ENABLED upon return.
Note
Regarding Szip compression in HDF4:
Szip compression is available only through the SD interface and is documented in the SDsetcompress and SDgetcompinfo reference manual entries. Aside from the configuration discovery capability documented in HCget_config_info, Szip compression is not accessible through the HC interface.
See also
Regarding Szip usage and licensing:
See http://hdf.ncsa.uiuc.edu/doc_resource/SZIP/ for information regarding the use of Szip in HDF products and Szip licensing.
 
Regarding compression in HDF4:
See the SDsetcompress and SDgetcompinfo entries in this reference manual for a more general description of dataset compression information.

FORTRAN
currently unavailable
 
 
 
 

[H Interface][Top]


HDdont_atexit/hddontatexit

intn HDdont_atexit(void)

Purpose
Indicates to the library that an atexit() routine is _not_ to be installed.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
This routine indicates to the library that an atexit() cleanup routine should not be installed. The purpose for this is in situations where the library is dynamically linked into an application and is unlinked from the application before exit() gets called. In those situations, a routine installed with atexit() would jump to a routine which was no longer in memory, causing errors.
 
In order to be effective, this routine must be called before any other HDF function calls, and must be called each time the library is loaded/linked into the application (the first time and after it has been unloaded).
 
If this routine is used, certain memory buffers will not be deallocated, although in theory a user could call HPend on their own.

FORTRAN
integer hddontatexit( )

[H Interface][Top]


HEprint/heprntf/heprnt

VOID HEprint(FILE *stream, int32 level)

stream
IN:
Stream to print error message to
level
IN:
Level of error stack to print

Purpose
Prints information to the error stack.
Return value
None.
 
Fortran function returns 0 (zero) on success or -1 on failure.
Description
If level is 0, all of the errors currently on the error stack are printed. Output from this function is sent to the file pointed to by stream.
 
The following information is printed: the ASCII description of the error, the reporting routine, the reporting routine as source file name, and the line at which the error was reported. If the programmer has supplied extra information by means of HEreport, this information is printed as well.
 
The FORTRAN-77 routine heprnt uses one less parameter than the C routine because it doesn't allow the user to specify the print stream. Instead, it always prints to stdout.
 
The FORTRAN-77 routine heprntf is available on all platforms; heprnt is not supported on Microsoft Windows platforms.
 
The heprntf parameter filename is the name of the file to which error output is to be written. If the value of filename is an empty string (''), error output will be written to standard output, stdout.

FORTRAN
integer function heprntf(filename, level)
 
character*(*) filename
 
integer level
 
 
 
integer function heprnt(level)
 
integer level

[H Interface][Top]


HEstring/hestringf

const char *HEstring(hdf_err_code_t error_code)

error_code
IN:
HDF error code

Purpose
Returns the error message associated with specified error code.
Return value
Returns a pointer to a string associated with the error code, if successful.
Description
Returns a text description of the given error code. These strings are statically declared and should not be deallocated from memory (using the free routine) by the user. If a defined text description cannot be found a generic default message is returned.

FORTRAN
integer function hestringf(error_code, error_message)
 
integer error_code
 
character*(*) error_message

[H Interface][Top]


HXsetcreatedir/hxiscdir

intn HXsetcreatedir(char *dir)

dir
IN:
Target directory of the external file to be written

Purpose
Initializes the directory environment variable, identifying the location of the external file to be written.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The contents of dir is copied into the private memory of the HDF library. If dir is NULL, the directory variable is unset. If HXsetcreatedir encounters an error condition, the directory variable is not changed. When a new external element is created (via the routines HXcreate or SDsetexternal), the HDF library accesses the external file just like the open call by default. Refer to the Reference Manual page on HXcreate for a description of when a new or an old file should be opened.
 
Users may override the default action by calling HXsetcreatedir or by defining the environment variable $HDFEXTCREATEDIR. The HDF library will access the external file in the directory according to the environment variable setting. The precedence is HXsetcreatedir, then $HDXEXTDIR, in the manner of open.
 
Note that the above override does not apply to absolute pathnames - i.e., filenames starting with a forward slash. HDF will access the absolute pathname without change. Also note that HXsetcreatedir and $HDFEXTCREATEDIR are not symmetrical to HXsetdir and $HDFEXTDIR. The former pair permits only single directory values and is used to compose the filename for access. The later pair permits multiple directory values which are used for searching an existing file.
 
The dir_len parameter in the FORTRAN-77 routine specifies the length of the dir character string.

FORTRAN
integer function hxiscdir(dir, dir_len)
 
character*(*) dir
 
integer dir_len

[H Interface][Top]


HXsetdir/hxisdir

intn HXsetdir(char *dir)

dir
IN:
Target directory of the external file to be located

Purpose
Initializes the directory environment variable, identifying the location of the external file to be located.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
HXsetdir sets the directory variable for locating an external file according to dir which may contain multiple directories separated by vertical bars (e.g., "dir1|dir2"). The content of dir is copied into the private memory of the HDF library. If dir is NULL, the directory variable is unset.
 
If HXsetdir encounters any error, the directory variable is not changed. By default, the HDF library locates the external file just like the open call. It also searches for the external file in the directories specified by the user environment variable $HDFEXTDIR, if defined, and the directory variable set by HXsetdir. The searching precedence is directory variable, if set, then $HDXEXTDIR, then in the manner of open.
 
The searching differs if the external filename is an absolute pathname - i.e., starting with a forward slash. HDF will try open first. If open fails and if $HDFEXTDIR is defined or the directory variable is set via HXsetdir, HDF will remove all directory components of the absolute pathname (e.g., "/usr/groupA/projectB/Data001" becomes "Data001") and search for that filename with the strategy described in the previous paragraph.
 
The dir_len parameter in the FORTRAN-77 routine specifies the length of the dir character string.

FORTRAN
integer function hxisdir(dir, dir_len)
 
character*(*) dir
 
integer dir_len


HDF4.2r4 - February 2009
Copyright
The HDF Group
www.hdfgroup.org
The HDF Group