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