The HDF Group

HDF Reference Manual

Version 4.2.12


[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]


Hgetntinfo

intn Hgetntinfo(const int32 n_type, hdf_ntinfo_t *nt_info)

n_type
IN:
HDF4 number type
nt_info
OUT:
Number type's information

Purpose
Retrieves some information of the given number type.
Return value
Returns SUCCEED (0) if successful, and FAIL (-1) otherwise.
Description
Hgetntinfo retrieves the name and byte order of the given number type, n_type. These values are in character arrays and are encapsulated in the structure hdf_ntinfo_t, which is defined in hdf.h as:
typedef struct hdf_ntinfo_t
{
    char type_name[9]; /* nt name, e.g. "int8" or "float32" */
    char byte_order[13]; /* nt byte order, e.g. "littleEndian" or "bigEndian" */
}
hdf_ntinfo_t;
Hgetntinfo returns FAIL (-1) when n_type does not match one of the types listed in the tables in Section 2.5.2, "HDF Definitions" of the HDF User's Guide.

FORTRAN
Currently unavailable
 
 

[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 - Create a new file. If file exists, replace its contents.
    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 - for no compression
    COMP_CODE_RLE - for RLE run-length encoding
    COMP_CODE_NBIT - for NBIT compression
    COMP_CODE_SKPHUFF - for Skipping Huffman compression
    COMP_CODE_DEFLATE - for GZIP compression
    COMP_CODE_SZIP - for Szip compression
    COMP_CODE_JPEG - for 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 https://support.hdfgroup.org/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]


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


HDF 4.2.12 - June 2016
Copyright
The HDF Group
www.hdfgroup.org
The HDF Group