H5T_REGISTER

Registers a conversion function

Procedure:

H5T_REGISTER (type, name, src_id, dst_id, func)

Signature:

herr_t H5Tregister( H5T_pers_t type, const char * name, hid_t src_id, hid_t dst_id, H5T_conv_t func )

Parameters:

H5T_pers_t `type`	IN: Conversion function type: `H5T_PERS_HARD` for hard conversion functions `H5T_PERS_SOFT` for soft conversion functions
const char * `name`	IN: Name displayed in diagnostic output
hid_t `src_id`	IN: Identifier of source datatype
hid_t `dst_id`	IN: Identifier of destination datatype
H5T_conv_t `func`	IN: Function to convert between source and destination datatypes

Description:

H5T_REGISTER registers a hard or soft conversion function for a datatype conversion path.

The parameter type indicates whether a conversion function is hard (H5T_PERS_HARD) or soft (H5T_PERS_SOFT). User-defined functions employing compiler casting are designated as hard; other user-defined conversion functions registered with the HDF5 library (with H5T_REGISTER ) are designated as soft. The HDF5 library also has its own hard and soft conversion functions.

A conversion path can have only one hard function. When type is H5T_PERS_HARD, func replaces any previous hard function.

When type is H5T_PERS_SOFT, H5T_REGISTER adds the function to the end of the master soft list and replaces the soft function in all applicable existing conversion paths. Soft functions are used when determining which conversion function is appropriate for this path.

The name is used only for debugging and should be a short identifier for the function.

The path is specified by the source and destination datatypes src_id and dst_id. For soft conversion functions, only the class of these types is important.

The type of the conversion function pointer is declared as:

typedef herr_t (*H5T_conv_t) (hid_t src_id, 
                              hid_t dst_id, 
                              H5T_cdata_t *cdata,
                              size_t nelmts, 
                              size_t buf_stride, 
                              size_t bkg_stride, 
                              void *buf, 
                              void *bkg,
                              hid_t dset_xfer_plist)

The H5T_cdata_t struct is declared as:

typedef struct *H5T_cdata_t (H5T_cmd_t command, 
                             H5T_bkg_t need_bkg, 
                             hbool_t *recalc,
                             void *priv)

Programming Note for C++ Developers Using C Functions:

If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

Examples of this kind of routine include callbacks such as H5P_SET_ELINK_CB and H5P_SET_TYPE_CONV_CB and functions such as H5T_CONVERT and H5E_WALK2.

Exiting the routine in its normal fashion allows the HDF5 C library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Example:

Coming Soon!

History:

Release	Change
1.6.3	The following change occurred in the `H5Tconv_t` function: `nelmts` parameter type changed to size_t.

--- Last Modified: May 23, 2019 | 03:24 PM

Page tree

H5T_REGISTER

Procedure:

Signature:

Parameters:

Description:

Returns:

Example:

History:

The HDF Group

Site

Resources

Connect