Last modified: 22 August 2012
Name: H5Pset_type_conv_cb
Signature:
  herr_t `H5Pset_type_conv_cb`( hid_t `plist`, H5T_conv_except_func_t `func`, void *`op_data`)

Purpose:
  Sets user-defined datatype conversion callback function.

Description:
  `H5Pset_type_conv_cb` sets the user-defined datatype conversion callback function `func` in the dataset transfer property list `plist`.

  The parameter `op_data` is a pointer to user-defined input data for the callback function and will be passed through to the callback function.

  The callback function `func` defines the actions an application is to take when there is an exception during datatype conversion. The function prototype is as follows:

  `typedef` H5T_conv_ret_t (`H5T_conv_except_func_t`) ( H5T_conv_except_t `except_type`, hid_t `src_id`, hid_t `dst_id`, void *`src_buf`, void *`dst_buf`, void *`op_data`)

  where `except_type` indicates what kind of exception has happened, `src_id` and `dst_id` are the source and destination datatype identifiers, `src_buf` and `dst_buf` are the source and destination data buffer, and `op_data` is the required input data for this callback function.

  Valid values for `except_type` are as follows:

  `H5T_CONV_EXCEPT_RANGE_HI`
    Source value is positive and is too big to the destination. Overflow happens.
  `H5T_CONV_EXCEPT_RANGE_LOW`
    Source value is negative and its magnitude is too big to the destination. Overflow happens.
  `H5T_CONV_EXCEPT_TRUNCATE`
    Source is floating-point type and destination is integer. The floating-point number has fractional part.
  `H5T_CONV_EXCEPT_PRECISION`
    Source is integer and destination is floating-point type. The mantissa of floating-point type is not big enough to hold all the digits of the integer.
  `H5T_CONV_EXCEPT_PINF`
    Source is floating-point type and the value is positive infinity.
  `H5T_CONV_EXCEPT_NINF`
    Source is floating-point type and the value is negative infinity.
  `H5T_CONV_EXCEPT_NAN`
    Source is floating-point type and the value is NaN (not a number, including QNaN and SNaN).

  Valid callback function return values are `H5T_CONV_ABORT`, `H5T_CONV_UNHANDLED` and `H5T_CONV_HANDLED`.

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 `H5Pset_elink_cb` and `H5Pset_type_conv_cb` and functions such as `H5Tconvert` and `H5Ewalk2`.

  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.

Parameters:

  hid_t `plist` | IN: Dataset transfer property list identifier.
  H5T_conv_except_func_t `func` | IN: User-defined type conversion callback function.
  void *`op_data` | IN: User-defined input data for the callback function.

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

Fortran90 Interface:
  None.