Last modified: 23 August 2012
Name: H5Pinsert2
Signature:
  herr_t `H5Pinsert2`( hid_t `plid`, const char *`name`, size_t `size`, void *`value`, H5P_prp_set_func_t `set`, H5P_prp_get_func_t `get`, H5P_prp_delete_func_t `delete`, H5P_prp_copy_func_t `copy`, H5P_prp_compare_func_t `compare`, H5P_prp_close_func_t `close` )

Purpose:
  Registers a temporary property with a property list.

Description:
  `H5Pinsert2` create a new property in a property list. The property will exist only in this property list and copies made from it.

  The initial property value must be provided in `value` and the property value will be set accordingly.

  The name of the property must not already exist in this list, or this routine will fail.

  The `set` and `get` callback routines may be set to NULL if they are not needed.

  Zero-sized properties are allowed and do not store any data in the property list. The default value of a zero-size property may be set to NULL. They may be used to indicate the presence or absence of a particular piece of information.

  The `set` routine is called before a new value is copied into the property. The `H5P_prp_set_func_t` callback function is defined as follows:
  typedef herr_t (*`H5P_prp_set_func_t`)( hid_t `prop_id`, const char *`name`, size_t `size`, void *`new_value`);
  The parameters to the callback function are defined as follows:

  hid_t `prop_id` | IN: The identifier of the property list being modified
  const char *`name` | IN: The name of the property being modified
  size_t `size` | IN: The size of the property in bytes
  void **`new_value` | IN: Pointer to new value pointer for the property being modified

  The `set` routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the `set` routine returns a negative value, the new property value is not copied into the property and the set routine returns an error value. The `set` routine will be called for the initial value.

  Note: The `set` callback function may be useful to range check the value being set for the property or may perform some transformation or translation of the value set. The `get` callback would then reverse the transformation or translation. A single `get` or `set` callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.

  The `get` routine is called when a value is retrieved from a property value. The `H5P_prp_get_func_t` callback function is defined as follows:

  typedef herr_t (*`H5P_prp_get_func_t`)( hid_t `prop_id`, const char *`name`, size_t `size`, void *`value`);

  The parameters to the above callback function are:

  hid_t `prop_id` | IN: The identifier of the property list being queried
  const char *`name` | IN: The name of the property being queried
  size_t `size` | IN: The size of the property in bytes
  void *`value` | IN: The value of the property being returned

  The `get` routine may modify the value to be returned from the query and those changes will be preserved. If the `get` routine returns a negative value, the query routine returns an error value.

  The `delete` routine is called when a property is being deleted from a property list. The `H5P_prp_delete_func_t` callback function is defined as follows:

  `typedef herr_t` (*`H5P_prp_delete_func_t`)( hid_t `prop_id`, const char *`name`, size_t `size`, void *`value`);

  The parameters to the above callback function are:

  hid_t `prop_id` | IN: The identifier of the property list the property is being deleted from
  const char * `name` | IN: The name of the property in the list
  size_t `size` | IN: The size of the property in bytes
  void * `value` | IN: The value for the property being deleted

  The `delete` routine may modify the value passed in, but the value is not used by the library when the `delete` routine returns. If the `delete` routine returns a negative value, the property list delete routine returns an error value but the property is still deleted.

  The `copy` routine is called when a new property list with this property is being created through a copy operation. The `H5P_prp_copy_func_t` callback function is defined as follows:

  typedef herr_t (*`H5P_prp_copy_func_t`)( const char *`name`, size_t `size`, void *`value`);

  The parameters to the above callback function are:

  const char *`name` | IN: The name of the property being copied
  size_t `size` | IN: The size of the property in bytes
  void * `value` | IN/OUT: The value for the property being copied

  The `copy` routine may modify the value to be set and those changes will be stored as the new value of the property. If the `copy` routine returns a negative value, the new property value is not copied into the property and the copy routine returns an error value.

  The `compare` routine is called when a property list with this property is compared to another property list with the same property. The `H5P_prp_compare_func_t` callback function is defined as follows:

  typedef int (*`H5P_prp_compare_func_t`)( const void *`value1`, const void *`value2`, size_t `size`);
  The parameters to the callback function are defined as follows:

  const void *`value1` | IN: The value of the first property to compare
  const void *`value2` | IN: The value of the second property to compare
  size_t `size` | IN: The size of the property in bytes

  The `compare` routine may not modify the values. The `compare` routine should return a positive value if `value1` is greater than `value2`, a negative value if `value2` is greater than `value1` and zero if `value1` and `value2` are equal.

  The `close` routine is called when a property list with this property is being closed. The `H5P_prp_close_func_t` callback function is defined as follows:

  typedef herr_t (*`H5P_prp_close_func_t`)( hid_t `prop_id`, const char *`name`, size_t `size`, void *`value`);
  The parameters to the callback function are defined as follows:

  hid_t `prop_id` | IN: The identifier of the property list being closed
  `const char *`name | IN: The name of the property in the list
  `size_t` size | IN: The size of the property in bytes
  `void *`value | IN: The value for the property being closed

  The `close` routine may modify the value passed in, the value is not used by the library when the `close` routine returns. If the `close` routine returns a negative value, the property list close routine returns an error value but the property list is still closed.

  Note: There is no `create` callback routine for temporary property list objects; the initial value is assumed to have any necessary setup already performed on it.

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 `plid` | IN: Property list identifier to create temporary property within
const char *`name` | IN: Name of property to create
size_t `size` | IN: Size of property in bytes
void *`value` | IN: Initial value for the property
H5P_prp_set_func_t `set` | IN: Callback routine called before a new value is copied into the property's value
H5P_prp_get_func_t `get` | IN: Callback routine called when a property value is retrieved from the property
H5P_prp_delete_func_t `delete` | IN: Callback routine called when a property is deleted from a property list
H5P_prp_copy_func_t `copy` | IN: Callback routine called when a property is copied from an existing property list
H5P_prp_compare_func_t `compare` | IN: Callback routine called when a property is compared with another property list
H5P_prp_close_func_t `close` | IN: Callback routine called when a property list is being closed and the property value will be disposed of

Returns:
  Success: a non-negative value
  Failure: a negative value

Fortran90 Interface:
  None.

History:

  Release | C
  1.8.0 | Function introduced in this release.