H5P: Property List Interface

“Using HDF5 Virtual Datasets”

Supporting functions:

VDS functions:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 22 April 2016

Name: H5Pget_virtual_dsetname

Signature:

ssize_t H5Pget_virtual_dsetname(
        hid_t dcpl_id,
        size_t index,
        char *name,
        size_t size
        )

Purpose:

Gets the name of a source dataset used in the mapping.

Description:

H5Pget_virtual_dsetname takes the dataset creation property list for the virtual dataset, dcpl_id, the mapping index, index, the size of the dataset name for a source dataset, size, and retrieves the name of the source dataset used in the mapping.

Up to size characters of the dataset name are returned in name; additional characters, if any, are not returned to the user application.

If the length of the dataset name, which determines the required value of size, is unknown, a preliminary call to H5Pget_virtual_dsetname with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the dataset name. That value, plus 1 for a NULL terminator, must then be assigned to size for a second H5Pget_virtual_dsetname call, which will retrieve the actual dataset name.

Parameters:

`hid_t dcpl_id`		IN: The identifier of the virtual dataset creation property list.
`size_t index`		IN: Mapping index. The value of `index` is 0 (zero) or greater and less than `count` (`0 ≤ index < count`), where `count` is the number of mappings returned by `H5Pget_virtual_count`.
`char *name`		OUT: A buffer containing the name of the source dataset.
`size_t size`		IN: The size, in bytes, of the name buffer. Must be the size of the dataset name in bytes plus 1 for a `NULL` terminator.

Returns:

Returns the length of the dataset name if successful; otherwise returns a negative value.

Fortran Interface: h5pget_virtual_dsetname_f

Signature:

  SUBROUTINE h5pget_virtual_dsetname_f(dcpl_id, index, name, hdferr, name_len)
    INTEGER(HID_T)  , INTENT(IN)  :: dcpl_id
    INTEGER(SIZE_T) , INTENT(IN)  :: index
    CHARACTER(LEN=*), INTENT(OUT) :: name
    INTEGER, INTENT(OUT)          :: hdferr
    INTEGER(SIZE_T), OPTIONAL     :: name_len

Optional parameters:

  name_len - The size of name needed to hold the source dataset name. (OUT)

Inputs:

  dcpl_id - The identifier of the virtual dataset creation property list.
  index   - Mapping index.
            The value of index is 0 (zero) or greater and less than count 
            (0 ≤ index < count), where count is the number of mappings 
            returned by h5pget_virtual_count.

Outputs:

  name   - A buffer containing the name of the source dataset.
  hdferr - Returns 0 if successful and -1 if fails.

See Also:

“Using HDF5 Virtual Datasets”

Supporting functions:

VDS functions:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 22 April 2016

Name: H5Pget_virtual_filename

Signature:

ssize_t H5Pget_virtual_filename(
        hid_t dcpl_id,
        size_t index,
        char *name,
        size_t size
        )

Purpose:

Gets the filename of a source dataset used in the mapping.

Description:

H5Pget_virtual_filename takes the dataset creation property list for the virtual dataset, dcpl_id, the mapping index, index, the size of the filename for a source dataset, size, and retrieves the name of the file for a source dataset used in the mapping.

Up to size characters of the filename are returned in name; additional characters, if any, are not returned to the user application.

If the length of the filename, which determines the required value of size, is unknown, a preliminary call to H5Pget_virtual_filename with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the filename. That value, plus 1 for a NULL terminator, must then be assigned to size for a second H5Pget_virtual_filename call, which will retrieve the actual filename.

Parameters:

`hid_t dcpl_id`		IN: The identifier of the virtual dataset creation property list.
`size_t index`		IN: Mapping index. The value of `index` is 0 (zero) or greater and less than `count` (`0 ≤ index < count`), where `count` is the number of mappings returned by `H5Pget_virtual_count`.
`char *name`		OUT: A buffer containing the name of the file containing the source dataset.
`size_t size`		IN: The size, in bytes, of the name buffer. Must be the size of the filename in bytes plus 1 for a `NULL` terminator.

Returns:

Returns the length of the filename if successful; otherwise returns a negative value.

Fortran Interface: h5pget_virtual_filename_f

Signature:

  SUBROUTINE h5pget_virtual_filename_f(dcpl_id, index, name, hdferr, name_len)
    INTEGER(HID_T)  , INTENT(IN)  :: dcpl_id
    INTEGER(SIZE_T) , INTENT(IN)  :: index
    CHARACTER(LEN=*), INTENT(OUT) :: name
    INTEGER, INTENT(OUT)          :: hdferr
    INTEGER(SIZE_T), OPTIONAL     :: name_len

Optional parameters:

  name_len - The size of name needed to hold the filename. (OUT)

Inputs:

  dcpl_id - The identifier of the virtual dataset creation property list.
  index   - Mapping index.
            The value of index is 0 (zero) or greater and less than count 
            (0 ≤ index < count), where count is the number of mappings 
            returned by h5pget_virtual_count.

Outputs:

  name   - A buffer containing the name of the file containing the 
           source dataset.
  hdferr - Returns 0 if successful and -1 if fails.

See Also:

“Using HDF5 Virtual Datasets”

Supporting functions:

VDS functions:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 22 April 2016

Name: H5Pget_virtual_printf_gap

Signature:

herr_t H5Pget_virtual_printf_gap(
        hid_t dapl_id,
        hsize_t *gap_size
        )

Purpose:

Returns the maximum number of missing source files and/or datasets with the printf-style names when getting the extent for an unlimited virtual dataset.

Description:

H5Pget_virtual_printf_gap returns the maximum number of missing printf-style files and/or datasets for determining the extent of an unlimited virtual dataaset, gap_size, using the access property list for the virtual dataset, dapl_id.

The default library value for gap_size is 0 (zero).

Parameters:

`hid_t dapl_id`		IN: Dataset access property list identifier for the virtual dataset
`hsize_t *gap_size`		OUT: Maximum number of the files and/or datasets allowed to be missing for determining the extent of an unlimited virtual dataset with printf-style mappings. (Default: `0`)

Returns:

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

Fortran Interface: h5pget_virtual_printf_gap_f

Signature:

  SUBROUTINE h5pget_virtual_printf_gap_f(dapl_id, gap_size, hdferr)
    INTEGER(HID_T)  , INTENT(IN)  :: dapl_id
    INTEGER(HSIZE_T), INTENT(OUT) :: gap_size
    INTEGER         , INTENT(OUT) :: hdferr

Inputs:

  dapl_id    - Dataset access property list identifier for the virtual dataset

Outputs:

  gap_size - Maximum number of the files and/or datasets allowed to 
             be missing for determining the extent of an unlimited virtual 
             dataset with printf-style mappings. 
  hdferr   - Returns 0 if successful and -1 if fails

See Also:

“Using HDF5 Virtual Datasets”

Supporting functions:

VDS functions:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 22 April 2016

Name: H5Pget_virtual_srcspace

Signature:

hid_t H5Pget_virtual_srcspace(
        hid_t dcpl_id,
        size_t index
        )

Purpose:

Gets a dataspace identifier for the selection within the source dataset used in the mapping.

Description:

H5Pget_virtual_srcspace takes the dataset creation property list for the virtual dataset, dcpl_id, and the mapping index, index, and returns a dataspace identifier for the selection within the source dataset used in the mapping.

Parameters:

`hid_t dcpl_id`		IN: The identifier of the virtual dataset creation property list.
`size_t index`		IN: Mapping index. The value of `index` is 0 (zero) or greater and less than `count` (`0 ≤ index < count`), where `count` is the number of mappings returned by `H5Pget_virtual_count`.

Returns:

Returns a valid dataspace identifier if successful; otherwise returns a negative value.

Fortran Interface: h5pget_virtual_srcspace_f

Signature:

  SUBROUTINE h5pget_virtual_srcspace_f(dcpl_id, index, ds_id, hdferr)
    INTEGER(HID_T) , INTENT(IN)  :: dcpl_id
    INTEGER(SIZE_T), INTENT(IN)  :: index
    INTEGER(HID_T) , INTENT(OUT) :: ds_id
    INTEGER, INTENT(OUT)         :: hdferr

Inputs:

  dcpl_id - The identifier of the virtual dataset creation property list.
  index   - Mapping index.
            The value of index is 0 (zero) or greater and less than count 
            (0 ≤ index < count), where count is the number of mappings 
            returned by h5pget_virtual_count.

Outputs:

  ds_id  - dataspace identifier
  hdferr - Returns 0 if successful and -1 if fails.

See Also:

“Using HDF5 Virtual Datasets”

Supporting functions:

VDS functions:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 22 April 2016

Name: H5Pget_virtual_view

Signature:

herr_t H5Pget_virtual_view(
        hid_ dapl_id,
        H5D_vds_view_t *view
        )

Purpose:

Retrieves the view of a virtual dataset accessed with dapl_id.

Description:

H5Pget_virtual_view takes the virtual dataset access property list, dapl_id, and retrieves the flag, view, set by the H5Pset_virtual_view call.

Parameters:

`hid_t dapl_id`		IN: Dataset access property list identifier for the virtual dataset
`H5D_vds_view_t *view`		OUT: The flag specifying the view of the virtual dataset. Valid values are: `H5D_VDS_FIRST_MISSING` `H5D_VDS_LAST_AVAILABLE`

Returns:

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

Fortran Interface: h5pget_virtual_view_f

Signature:

  SUBROUTINE h5pget_virtual_view_f(dapl_id, view, hdferr)
    INTEGER(HID_T), INTENT(IN)  :: dapl_id
    INTEGER       , INTENT(INOUT) :: view
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  dapl_id - Dataset access property list identifier for the virtual dataset

Outputs:

  view - The flag specifying the view of the virtual dataset.
         Valid values are:
             H5D_VDS_FIRST_MISSING_F
             H5D_VDS_LAST_AVAILABLE_F
  hdferr - Returns 0 if successful and -1 if fails.

See Also:

“Using HDF5 Virtual Datasets”

Supporting functions:

VDS functions:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 22 April 2016

Name: H5Pget_virtual_vspace

Signature:

hid_t H5Pget_virtual_vspace(
        hid_t dcpl_id,
        size_t index
        )

Purpose:

Gets a dataspace identifier for the selection within the virtual dataset used in the mapping.

Description:

H5Pget_virtual_vspace takes the dataset creation property list for the virtual dataset, dcpl_id, and the mapping index, index, and returns a dataspace identifier for the selection within the virtual dataset used in the mapping.

Parameters:

`hid_t dcpl_id`		IN: The identifier of the virtual dataset creation property list.
`size_t index`		IN: Mapping index. The value of `index` is 0 (zero) or greater and less than `count` (`0 ≤ index < count`), where `count` is the number of mappings returned by `H5Pget_virtual_count`.

Returns:

Returns a valid dataspace identifier if successful; otherwise returns a negative value.

Fortran Interface: h5pget_virtual_vspace_f

Signature:

  SUBROUTINE h5pget_virtual_vspace_f(dcpl_id, index, ds_id, hdferr)
    INTEGER(HID_T) , INTENT(IN)  :: dcpl_id
    INTEGER(SIZE_T), INTENT(IN)  :: index
    INTEGER(HID_T) , INTENT(OUT) :: ds_id
    INTEGER, INTENT(OUT)         :: hdferr

Inputs:

  dcpl_id - The identifier of the virtual dataset creation property list.
  index   - Mapping index.
            The value of index is 0 (zero) or greater and less than count 
            (0 ≤ index < count), where count is the number of mappings 
            returned by h5pget_virtual_count.

Outputs:

  hdferr - Returns 0 if successful and -1 if fails.

See Also:

“Using HDF5 Virtual Datasets”

Supporting functions:

VDS functions:

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

History:

Release	Change
1.10.0	C function introduced with this release.

Name: H5Pget_userblock

Signature:

herr_t H5Pget_userblock(hid_t plist, hsize_t * size )

Purpose:

Retrieves the size of a user block.

Description:

H5Pget_userblock retrieves the size of a user block in a file creation property list.

Parameters:

hid_t plist IN: Identifier for property list to query.

hsize_t * size OUT: Pointer to location to return user-block size.

Returns:

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

Fortran90 Interface: h5pget_userblock_f

SUBROUTINE h5pget_userblock_f(prp_id, block_size, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id   ! Property list identifier
  INTEGER(HSIZE_T), DIMENSION(:), INTENT(OUT) ::  block_size 
                                         ! Size of the user-block in bytes
  INTEGER, INTENT(OUT) :: hdferr         ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pget_userblock_f

Name: H5Pget_version

Signature:

herr_t H5Pget_version(hid_t plist, unsigned * super, unsigned * freelist, unsigned * stab, unsigned * shhdr )

Purpose:

Retrieves the version information of various objects for a file creation property list.

Notice:

This function is deprecated in favor of the function H5Fget_info.

Description:

H5Pget_version retrieves the version information of various objects for a file creation property list. Any pointer parameters which are passed as NULL are not queried.

Parameters:

hid_t plist IN: Identifier of the file creation property list.

unsigned * super OUT: Pointer to location to return super block version number.

unsigned * freelist OUT: Pointer to location to return global freelist version number.

unsigned * stab OUT: Pointer to location to return symbol table version number.

unsigned * shhdr OUT: Pointer to location to return shared object header version number.

Returns:

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

Fortran90 Interface: h5pget_version_f

SUBROUTINE h5pget_version_f(prp_id, boot, freelist, & 
                            stab, shhdr, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id         ! Property list identifier
  INTEGER, DIMENSION(:), INTENT(OUT) :: boot   ! Array to put boot block 
                                               ! version number
  INTEGER, DIMENSION(:), INTENT(OUT) :: freelist  
                                               ! Array to put global
                                               ! freelist version number
  INTEGER, DIMENSION(:), INTENT(OUT) :: stab   ! Array to put symbol table
                                               ! version number
  INTEGER, DIMENSION(:), INTENT(OUT) :: shhdr  ! Array to put shared object 
                                               ! header version number
  INTEGER, INTENT(OUT) :: hdferr               ! Error code
                                               ! 0 on success and -1 on failure
END SUBROUTINE h5pget_version_f

History:

Release C

1.6.4 boot, freelist, stab, shhdr parameter types changed to unsigned.

Last modified: 8 April 2014

Name: H5Pget_vlen_mem_manager

Signature:

herr_t H5Pget_vlen_mem_manager(hid_t plist,
        H5MM_allocate_t *alloc,
        void **alloc_info,
        H5MM_free_t *free,
        void **free_info)

Purpose:

Gets the memory manager for variable-length datatype allocation in H5Dread and H5Dvlen_reclaim.

Description:

H5Pget_vlen_mem_manager is the companion function to H5Pset_vlen_mem_manager, returning the parameters set by that function.

Parameters:

`hid_t plist`	IN: Identifier for the dataset transfer property list.
`H5MM_allocate_t *alloc`	OUT: User’s allocate routine, or `NULL` for system `malloc`.
`void **alloc_info`	OUT: Extra parameter for user’s allocation routine. Contents are ignored if preceding parameter is `NULL`.
`H5MM_free_t *free`	OUT: User’s free routine, or `NULL` for system `free`.
`void **free_info`	OUT: Extra parameter for user’s free routine. Contents are ignored if preceding parameter is `NULL`.

Returns:

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

Fortran90 Interface:

None.

Last modified: 23 August 2012

Name: H5Pinsert

Signatures:

herr_t `H5Pinsert`( 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_close_func_t `close` )	[1]
herr_t `H5Pinsert`( 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` )	[2]

Purpose:

Registers a temporary property with a property list.

Description:

H5Pinsert is a macro that is mapped to either H5Pinsert1 or H5Pinsert2, depending on the needs of the application.

Such macros are provided to facilitate application compatibility. For example:

The H5Pinsert macro will be mapped to H5Pinsert1 and will use the H5Pinsert1 syntax (first signature above) if an application is coded for HDF5 Release 1.6.x.
The H5Pinsert macro mapped to H5Pinsert2 and will use the H5Pinsert2 syntax (second signature above) if an application is coded for HDF5 Release 1.8.x.

When both the HDF5 Library and the application are built and installed with no specific compatibility flags, H5Pinsert is mapped to the most recent version of the function, currently H5Pinsert2. If the library and/or application is compiled for Release 1.6 emulation, H5Pinsert will be mapped to H5Pinsert1. Function-specific flags are available to override these settings on a function-by-function basis when the application is compiled.

Specific compile-time compatibility flags and the resulting mappings are as follows:

Compatibility setting	`H5Pinsert` mapping
Global settings
No compatibility flag	`H5Pinsert2`
Enable deprecated symbols	`H5Pinsert2`
Disable deprecated symbols	`H5Pinsert2`
Emulate Release 1.6 interface	`H5Pinsert1`
Function-level macros
`H5Pinsert_vers = 2`	`H5Pinsert2`
`H5Pinsert_vers = 1`	`H5Pinsert1`

For more information on macro use and mappings, see the “API Compatibility Macros in HDF5” document.

Interface history: Signature [1] above is the original H5Pinsert interface and the only interface available prior to HDF5 Release 1.8.0. This signature and the corresponding function are now deprecated but will remain directly callable as H5Pinsert1.

Signature [2] above was introduced with HDF5 Release 1.8.0 and is the recommended and default interface. It is directly callable as H5Pinsert2.

See “API Compatibility Macros in HDF5” for circumstances under which either of these functions might not be available in an installed instance of the HDF5 Library.

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.

Fortran90 Interface: h5pinsert_f

Signature:

  SUBROUTINE h5pinsert_f
    INTEGER(HID_T)  , INTENT(IN)  :: plist
    CHARACTER(LEN=*), INTENT(IN)  :: name
    INTEGER(SIZE_T) , INTENT(IN)  :: size
    TYPE            , INTENT(IN)  :: value
    INTEGER         , INTENT(OUT) :: hdferr

Inputs:

  plist  - Property list class identifier
  name   - Name of property to insert
  size   - Size of the property value
  value  - Property value, supported types are:
             INTEGER
             REAL
             DOUBLE PRECISION
             CHARACTER(LEN=*)

Outputs:

  hdferr - Returns 0 if successful and -1 if fails

Fortran2003 Interface: h5pinsert_f

Signature:

  SUBROUTINE h5pinsert_f
    INTEGER(HID_T)  , INTENT(IN)  :: plist
    CHARACTER(LEN=*), INTENT(IN)  :: name
    INTEGER(SIZE_T) , INTENT(IN)  :: size
    TYPE(C_PTR)     , INTENT(IN)  :: value
    INTEGER         , INTENT(OUT) :: hdferr

Inputs:

  plist  - Property list class identifier
  name   - Name of property to insert
  size   - Size of the property value
  value  - Pointer to new value pointer for the property being modified

Outputs:

  hdferr - Returns 0 if successful and -1 if fails

History:

Release	Change
1.8.8	Fortran updated to Fortran2003.
1.8.0	The function C function `H5Pinsert` renamed to `H5Pinsert1` and deprecated in this release. C macro `H5Pinsert` and the C function `H5Pinsert2` introduced in this release.

Last modified: 23 August 2012

Name: H5Pinsert1

Signature:

herr_t H5Pinsert1( 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_close_func_t close )

Purpose:

Registers a temporary property with a property list.

Notice:

This function is renamed from H5Pinsert and deprecated in favor of the function H5Pinsert2 or the new macro H5Pinsert.

Description:

H5Pinsert1 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 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.

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_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: h5pinsert_f

SUBROUTINE h5pinsert_f
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist   ! Property list class identifier 
  CHARACTER(LEN=*), INTENT(IN) :: name  ! Name of property to insert
  INTEGER(SIZE_T), INTENT(IN) :: size   ! Size of the property value	
  TYPE,   INTENT(IN) :: value           ! Property value
                                        ! Supported types are:
                                        !    INTEGER
                                        !    REAL
                                        !    DOUBLE PRECISION
                                        !    CHARACTER(LEN=*)
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pinsert_f

History:

Release C

1.8.0 Function H5Pinsert renamed to H5Pinsert1 and deprecated in this release.

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.

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

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.

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.

Last modified: 10 December 2015

Name: H5Pisa_class

Signature:

htri_t H5Pisa_class( hid_t plist, hid_t pclass )

Purpose:

Determines whether a property list is a member of a class.

Description:

H5Pisa_class checks to determine whether the property list plist is a member of the property list class pclass.

Parameters:

hid_t `plist`	IN: Property list identifier
`hid_t` pclass	IN: Property list class identifier

Returns:

Returns a positive value if the specified property list is a member of the specified class.
Returns 0 if the specified property list is not a member of the specified class.
Returns a negative value when the function fails.

See Also:

H5Pcreate

Fortran90 Interface: h5pisa_class_f

SUBROUTINE h5pisa_class_f(plist, pclass, flag, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist     ! Property list identifier 
  INTEGER(HID_T), INTENT(IN) :: pclass    ! Class identifier
  LOGICAL, INTENT(OUT) :: flag            ! Logical flag
                                          !    .TRUE. if a member
                                          !    .FALSE. otherwise
  INTEGER, INTENT(OUT) :: hdferr          ! Error code
                                          ! 0 on success and -1 on failure
END SUBROUTINE h5pisa_class_f

Last modified: 23 August 2012

Name: H5Piterate

Purpose:

Iterates over properties in a property class or list.

Signature:

int H5Piterate( hid_t id, int * idx, H5P_iterate_t iter_func, void * iter_data )

Description:

H5Piterate iterates over the properties in the property object specified in id, which may be either a property list or a property class, performing a specified operation on each property in turn.

For each property in the object, iter_func and the additional information specified below are passed to the H5P_iterate_t operator function.

The iteration begins with the idx-th property in the object; the next element to be processed by the operator is returned in idx. If idx is NULL, the iterator starts at the first property; since no stopping point is returned in this case, the iterator cannot be restarted if one of the calls to its operator returns non-zero.

The prototype for the H5P_iterate_t operator is as follows:

typedef herr_t (*H5P_iterate_t)( hid_t id, const char *name, void *iter_data )

The operation receives the property list or class identifier for the object being iterated over, id, the name of the current property within the object, name, and the pointer to the operator data passed in to H5Piterate, iter_data.

The valid return values from an operator are as follows:

Zero	Causes the iterator to continue, returning zero when all properties have been processed
Positive	Causes the iterator to immediately return that positive value, indicating short-circuit success. The iterator can be restarted at the index of the next property
Negative	Causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the index of the next property

H5Piterate assumes that the properties in the object identified by id remain unchanged through the iteration. If the membership changes during the iteration, the function's behavior is undefined.

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.

Parameters:

hid_t id IN: Identifier of property object to iterate over

int * idx IN/OUT: Index of the property to begin with

H5P_iterate_t iter_func IN: Function pointer to function to be called with each property iterated over

void * iter_data IN/OUT: Pointer to iteration data from user

Returns:

Success: the return value of the last call to iter_func if it was non-zero; zero if all properties have been processed

Failure: a negative value

Fortran90 Interface:

None.

Last modified: 10 June 2010

Name: H5Pmodify_filter

Signature:

herr_t H5Pmodify_filter( hid_t plist_id, H5Z_filter_t filter_id, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] )

Purpose:

Modifies a filter in the filter pipeline.

Description:

H5Pmodify_filter modifies the specified filter_id in the filter pipeline. plist_id must be a dataset or group creation property list.

The filter_id, flags cd_nelmts[], and cd_values parameters are used in the same manner and accept the same values as described in the discussion of H5Pset_filter.

Parameters:

hid_t plist_id IN: Dataset or group creation property list identifier.

H5Z_filter_t filter_id IN: Filter to be modified.

unsigned int flags IN: Bit vector specifying certain general properties of the filter.

size_t cd_nelmts IN: Number of elements in cd_values.

const unsigned int cd_values[] IN: Auxiliary data for the filter.

Returns:

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

Fortran90 Interface: h5pmodify_filter_f

SUBROUTINE h5pmodify_filter_f(prp_id, filter, flags, cd_nelmts, & 
                              cd_values, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id      ! Property list identifier
  INTEGER, INTENT(IN)        :: filter      ! Filter to be modified
  INTEGER, INTENT(IN)        :: flags       ! Bit vector specifying certain 
                                            ! general properties of the filter
  INTEGER(SIZE_T), INTENT(IN) :: cd_nelmts  ! Number of elements in cd_values
  INTEGER, DIMENSION(*), INTENT(IN) :: cd_values  
                                            ! Auxiliary data for the filter
  INTEGER, INTENT(OUT)       :: hdferr      ! Error code
                                            ! 0 on success and -1 on failure
END SUBROUTINE h5pmodify_filter_f

History:

Release Change

1.6.0 Function introduced in this release.

1.8.5 Function extended to work with group creation property lists.

Last modified: 26 March 2014

Name: H5Pregister

Signatures:

herr_t `H5Pregister`( hid_t `class`, const char * `name`, size_t `size`, void * `default`, H5P_prp_create_func_t `create`, 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_close_func_t `close` )	[1]
herr_t `H5Pregister`( hid_t `class`, const char * `name`, size_t `size`, void * `default`, H5P_prp_create_func_t `create`, 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` )	[2]

Purpose:

Registers a permanent property with a property list class.

Description:

H5Pregister is a macro that is mapped to either H5Pregister1 or H5Pregister2, depending on the needs of the application.

Such macros are provided to facilitate application compatibility. For example:

The H5Pregister macro will be mapped to H5Pregister1 and will use the H5Pregister1 syntax (first signature above) if an application is coded for HDF5 Release 1.6.x.
The H5Pregister macro mapped to H5Pregister2 and will use the H5Pregister2 syntax (second signature above) if an application is coded for HDF5 Release 1.8.x.

When both the HDF5 Library and the application are built and installed with no specific compatibility flags, H5Pregister is mapped to the most recent version of the function, currently H5Pregister2. If the library and/or application is compiled for Release 1.6 emulation, H5Pregister will be mapped to H5Pregister1. Function-specific flags are available to override these settings on a function-by-function basis when the application is compiled.

Specific compile-time compatibility flags and the resulting mappings are as follows:

Compatibility setting	`H5Pregister` mapping
Global settings
No compatibility flag	`H5Pregister2`
Enable deprecated symbols	`H5Pregister2`
Disable deprecated symbols	`H5Pregister2`
Emulate Release 1.6 interface	`H5Pregister1`
Function-level macros
`H5Pregister_vers = 2`	`H5Pregister2`
`H5Pregister_vers = 1`	`H5Pregister1`

For more information on macro use and mappings, see the “API Compatibility Macros in HDF5” document.

Interface history: Signature [1] above is the original H5Pregister interface and the only interface available prior to HDF5 Release 1.8.0. This signature and the corresponding function are now deprecated but will remain directly callable as H5Pregister1.

Signature [2] above was introduced with HDF5 Release 1.8.0 and is the recommended and default interface. It is directly callable as H5Pregister2.

See “API Compatibility Macros in HDF5” for circumstances under which either of these functions might not be available in an installed instance of the HDF5 Library.

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.

Fortran90 Interface: h5pregister_f

Signature:

  SUBROUTINE h5pregister_f(class, name, size, value, hdferr)
    INTEGER(HID_T)  , INTENT(IN)  :: class
    CHARACTER(LEN=*), INTENT(IN)  :: name
    INTEGER(SIZE_T) , INTENT(IN)  :: size
    TYPE            , INTENT(IN)  :: value
    INTEGER         , INTENT(OUT) :: hdferr

Inputs:

  class  - Property list class identifier
  name   - Name of property to register
  size   - Size of the property value
  value  - Property value, supported types are:
             INTEGER
             REAL
             DOUBLE PRECISION
             CHARACTER(LEN=*)

Outputs:

  hdferr - Returns 0 if successful and -1 if fails

Fortran2003 Interface: h5pregister_f

Signature:

  SUBROUTINE h5pregister_f(class, name, size, value, hdferr)
    INTEGER(HID_T)  , INTENT(IN)  :: class
    CHARACTER(LEN=*), INTENT(IN)  :: name
    INTEGER(SIZE_T) , INTENT(IN)  :: size
    TYPE(C_PTR)     , INTENT(IN)  :: value
    INTEGER         , INTENT(OUT) :: hdferr

Inputs:

  class  - Property list class identifier
  name   - Name of property to register
  size   - Size of the property value
  value  - Pointer to value to set the property to

Outputs:

  hdferr - Returns 0 if successful and -1 if fails

History:

Release	C
1.8.8	Fortran updated to Fortran2003.
1.8.0	The function C function `H5Pregister` renamed to `H5Pregister1` and deprecated in this release. C macro `H5Pregister` and C function `H5Pregister2` introduced in this release.

Last modified: 23 August 2012

Name: H5Pregister1

Signature:

herr_t H5Pregister1( hid_t class, const char * name, size_t size, void * default, H5P_prp_create_func_t create, 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_close_func_t close )

Purpose:

Registers a permanent property with a property list class.

Notice:

This function is renamed from H5Pregister and deprecated in favor of the function H5Pregister2 and or the new macro H5Pregister.

Description:

H5Pregister1 registers a new property with a property list class. The property will exist in all property list objects of class created after this routine finishes. The name of the property must not already exist, or this routine will fail. The default property value must be provided and all new property lists created with this property will have the property value set to the default value. Any of the 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. These may be used as flags to indicate the presence or absence of a particular piece of information. The default pointer for a zero-sized property may be set to NULL. The property create and close callbacks are called for zero-sized properties, but the set and get callbacks are never called.

The create routine is called when a new property list with this property is being created. The H5P_prp_create_func_t callback function is defined as follows:

typedef herr_t

H5P_prp_create_func_t

const char *

name

size_t

size

void *

initial_value

The parameters to this callback function are defined as follows:

const char *`name`	IN: The name of the property being modified
size_t `size`	IN: The size of the property in bytes
void *`initial_value`	IN/OUT: The default value for the property being created, which will be passed to `H5Pregister1`

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

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

hid_t

prop_id

const char *

name

size_t

size

void *

new_value

The parameters to this 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/OUT: 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 not be called for the initial value, only the create routine will be called.

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 callback function are defined as follows:

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/OUT: 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 returned to the calling routine. If the set 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 callback function are defined as follows:

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 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 callback function are defined as follows:

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 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, but 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.

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.

Parameters:

hid_t class IN: Property list class to register permanent property within

const char * name IN: Name of property to register

size_t size IN: Size of property in bytes

void * default IN: Default value for property in newly created property lists

H5P_prp_create_func_t create IN: Callback routine called when a property list is being created and the property value will be initialized

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 a 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: h5pregister_f

SUBROUTINE h5pregister_f
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: class   ! Property list class identifier 
  CHARACTER(LEN=*), INTENT(IN) :: name  ! Name of property to register
  INTEGER(SIZE_T), INTENT(IN) :: size   ! Size of the property value	
  TYPE,   INTENT(IN) :: value           ! Property value
                                        ! Supported types are:
                                        !    INTEGER
                                        !    REAL
                                        !    DOUBLE PRECISION
                                        !    CHARACTER(LEN=*)
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pregister_f

History:

Release	C
1.8.0	Function `H5Pregister` renamed to `H5Pregister1` and deprecated in this release.

Last modified: 23 August 2012

Name: H5Pregister2

Signature:

herr_t H5Pregister2( hid_t class, const char * name, size_t size, void * default, H5P_prp_create_func_t create, 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 permanent property with a property list class.

Description:

H5Pregister2 registers a new property with a property list class. The property will exist in all property list objects of class created after this routine finishes. The name of the property must not already exist, or this routine will fail. The default property value must be provided and all new property lists created with this property will have the property value set to the default value. Any of the callback routines may be set to NULL if they are not needed.

The create routine is called when a new property list with this property is being created. The H5P_prp_create_func_t callback function is defined as follows:

typedef herr_t

H5P_prp_create_func_t

const char *

name

size_t

size

void *

initial_value

The parameters to this callback function are defined as follows:

const char *`name`	IN: The name of the property being modified
size_t `size`	IN: The size of the property in bytes
void *`initial_value`	IN/OUT: The default value for the property being created, which will be passed to `H5Pregister2`

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

hid_t

prop_id

const char *

name

size_t

size

void *

new_value

The parameters to this 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/OUT: 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 not be called for the initial value, only the create routine will be called.

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 callback function are defined as follows:

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/OUT: The value of the property being returned

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 callback function are defined as follows:

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 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 callback function are defined as follows:

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

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

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.

Parameters:

hid_t class IN: Property list class to register permanent property within

const char * name IN: Name of property to register

size_t size IN: Size of property in bytes

void * default IN: Default value for property in newly created property lists

H5P_prp_create_func_t create IN: Callback routine called when a property list is being created and the property value will be initialized

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 a 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.

Name: H5Premove

Signature:

herr_t H5Premove( hid_t plid; const char *name )

Purpose:

Removes a property from a property list.

Description:

H5Premove removes a property from a property list.

Both properties which were in existence when the property list was created (i.e. properties registered with H5Pregister) and properties added to the list after it was created (i.e. added with H5Pinsert1) may be removed from a property list. Properties do not need to be removed from a property list before the list itself is closed; they will be released automatically when H5Pclose is called.

If a close callback exists for the removed property, it will be called before the property is released.

Parameters:

hid_t plid IN: Identifier of the property list to modify

const char *name IN: Name of property to remove

Returns:

Success: a non-negative value

Failure: a negative value

Fortran90 Interface: h5premove_f

SUBROUTINE h5premove_f(plid, name, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plid   ! Property list identifier
  CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to remove
  INTEGER, INTENT(OUT) :: hdferr       ! Error code
                                       ! 0 on success and -1 on failure
END SUBROUTINE h5premove_f

Last modified: 10 June 2010

Name: H5Premove_filter

Signature:

herr_t H5Premove_filter( hid_t plist_id, H5Z_filter_t filter )

Purpose:

Delete one or more filters in the filter pipeline.

Description:

H5Premove_filter removes the specified filter from the filter pipeline in the dataset or group creation property list plist_id.

The filter parameter specifies the filter to be removed. Valid values for use in filter are as follows:

`H5Z_FILTER_ALL`	Removes all filters from the filter pipeline.
`H5Z_FILTER_DEFLATE`	Data compression filter, employing the gzip algorithm
`H5Z_FILTER_SHUFFLE`	Data shuffling filter
`H5Z_FILTER_FLETCHER32`	Error detection filter, employing the Fletcher32 checksum algorithm
`H5Z_FILTER_SZIP`	Data compression filter, employing the SZIP algorithm
`H5Z_FILTER_NBIT`	Data compression filter, employing the N-Bit algorithm
`H5Z_FILTER_SCALEOFFSET`	Data compression filter, employing the scale-offset algorithm

Additionally, user-defined filters can be removed with this routine by passing the filter identifier with which they were registered with the HDF5 Library.

Attempting to remove a filter that is not in the filter pipeline is an error.

Parameters:

hid_t plist_id: IN: Dataset or group creation property list identifier.
H5Z_filter_t filter: IN: Filter to be deleted.

Returns:

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

Fortran90 Interface: h5premove_filter_f

SUBROUTINE h5premove_filter_f(prp_id, filter, hdferr) 

  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
  INTEGER, INTENT(IN) :: filter        ! Filter to be removed
                                       ! Valid values are:
                                       !     H5Z_FILTER_ALL_F
                                       !     H5Z_FILTER_DEFLATE_F
                                       !     H5Z_FILTER_SHUFFLE_F
                                       !     H5Z_FILTER_FLETCHER32_F
                                       !     H5Z_FILTER_SZIP_F
  INTEGER, INTENT(OUT) :: hdferr       ! Error code
                                       ! 0 on success, -1 on failure
END SUBROUTINE h5premove_filter_f

History:

Release	Changes
1.6.3	Function introduced in this release. Fortran subroutine introduced in this release.
1.8.5	Function extended to work with group creation property lists.

Last modified: 29 September 2011

Name: H5Pset

Signature:

herr_t H5Pset( hid_t plid, const char *name, void *value) )

Purpose:

Sets a property list value.

Description:

H5Pset sets a new value for a property in a property list. If there is a set callback routine registered for this property, the value will be passed to that routine and any changes to the value will be used when setting the property value. The information pointed to by the value pointer (possibly modified by the set callback) is copied into the property list value and may be changed by the application making the H5Pset call without affecting the property value.

The property name must exist or this routine will fail.

If the set callback routine returns an error, the property value will not be modified.

This routine may not be called for zero-sized properties and will return an error in that case.

Parameters:

hid_t `plid`;	IN: Property list identifier to modify
const char *`name;`	IN: Name of property to modify
void *`value`;	IN: Pointer to value to set the property to

Returns:

Success: a non-negative value

Failure: a negative value

Fortran90 Interface: h5pset_f

Signature:

  SUBROUTINE h5pset_f(plid, name, value, hdferr)
    INTEGER(HID_T)  , INTENT(IN)  :: plid
    CHARACTER(LEN=*), INTENT(IN)  :: name
    TYPE            , INTENT(IN)  :: value
    INTEGER         , INTENT(OUT) :: hdferr

Inputs:

  prp_id  - Property list identifier to modify
  name    - Name of property to modify
  value   - Property value, supported types are:
             INTEGER
             REAL
             DOUBLE PRECISION
             CHARACTER(LEN=*)

Outputs:

  hdferr  - Returns 0 if successful and -1 if fails

Fortran2003 Interface: h5pset_f

Signature:

  SUBROUTINE h5pset_f(plid, name, value, hdferr)
    INTEGER(HID_T)  , INTENT(IN)  :: plid
    CHARACTER(LEN=*), INTENT(IN)  :: name
    TYPE(C_PTR)     , INTENT(IN)  :: value
    INTEGER         , INTENT(OUT) :: hdferr

Inputs:

  prp_id  - Property list identifier to modify
  name    - Name of property to modify
  value   - Pointer to value to set the property to

Outputs:

  hdferr  - Returns 0 if successful and -1 if fails

History:

Release	Change
1.8.8	Fortran updated to Fortran2003.

Name: H5Pset_alignment

Signature:

herr_t H5Pset_alignment(hid_t plist, hsize_t threshold, hsize_t alignment )

Purpose:

Sets alignment properties of a file access property list.

Description:

H5Pset_alignment sets the alignment properties of a file access property list so that any file object greater than or equal in size to threshold bytes will be aligned on an address which is a multiple of alignment. The addresses are relative to the end of the user block; the alignment is calculated by subtracting the user block size from the absolute file address and then adjusting the address to be a multiple of alignment.

Default values for threshold and alignment are one, implying no alignment. Generally the default values will result in the best performance for single-process access to the file. For MPI IO and other parallel systems, choose an alignment which is a multiple of the disk block size.

If the file space handling strategy is set to H5F_FSPACE_STRATEGY_PAGE, then the alignment set via this routine is ignored. The file space handling strategy is set by H5Pset_file_space_strategy.

Parameters:

hid_t plist IN: Identifier for a file access property list.

hsize_t threshold IN: Threshold value. Note that setting the threshold value to 0 (zero) has the effect of a special case, forcing everything to be aligned.

hsize_t alignment IN: Alignment value.

Returns:

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

Fortran90 Interface: h5pset_alignment_f

SUBROUTINE h5pset_alignment_f(prp_id, threshold,  alignment, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id       ! Property list identifier
  INTEGER(HSIZE_T), INTENT(IN) :: threshold  ! Threshold value
  INTEGER(HSIZE_T), INTENT(IN) :: alignment  ! Alignment value
  INTEGER, INTENT(OUT) :: hdferr             ! Error code
                                             ! 0 on success and -1 on failure
END SUBROUTINE h5pset_alignment_f

Last modified: 6 April 2016

Name: H5Pset_all_coll_metadata_ops

Signature:

herr_t H5Pset_all_coll_metadata_ops(
              hid_t accpl_id,
              hbool_t is_collective
        )

Purpose:

Sets metadata I/O mode for read operations to collective or independent (default).

Description:

H5Pset_all_coll_metadata_ops sets the metadata I/O mode for read operations in the access property list accpl.

When engaging in parallel I/O, all metadata write operations must be collective. If is_collective is TRUE, this property specifies that the HDF5 Library will perform all metadata read operations collectively; if is_collective is FALSE, such operations may be performed independently.

Users must be aware that several HDF5 operations can potentially issue metadata reads. These include opening a dataset, datatype, or group; reading an attribute; or issuing a get info call such as getting information for a group with H5Gget_info. Collective I/O requirements must be kept in mind when issuing such calls in the context of parallel I/O.

If this property is set to true on a file access property list that is used in creating or opening a file, then the HDF5 Library will assume that all metadata read operations issued on that file identifier will be issued collectively from all ranks irrespective of the individual setting of a particular operation. If this assumption is not adhered to, corruption will be introduced in the metadata cache and HDF5’s behavior will be undefined.

Alternatively, a user may wish to avoid setting this property globally on the file access property list, and individually set it on particular object access property lists (dataset, group, link, datatype, attribute access property lists) for certain operations. This will indicate that only the operations issued with such an access property list will be called collectively and other operations may potentially be called independently. There are, however, several HDF5 operations that can issue metadata reads but have no property list in their function signatures to allow passing the collective requirement property. For those operations, the only option is to set the global collective requirement property on the file access property list; otherwise the metadata reads that can be triggered from those operations will be done independently by each process.

Functions that do not accommodate an access property list but that might issue metadata reads are listed in “Functions with No Access Property List Parameter that May Generate Metadata Reads.”

Warning:

As noted above, corruption will be introduced into the metadata cache and HDF5 Library behavior will be undefined when both of the following conditions exist:

A file is created or opened with a file access property list in which the collective metadata I/O property is set to TRUE.
Any function is called that triggers an independent metadata read while the file remains open with that file access property list.

An approach that avoids this corruption risk is described above.

Parameters:

`hid_t accpl_id`		IN: File, group, dataset, datatype, link, or attribute access property list identifier
`hbool_t is_collective`		IN: Boolean value indicating whether metadata reads are collective (`TRUE`) or independent (`FALSE`) Default mode: Independent (`FALSE`)

Returns:

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

Fortran Interface: h5pset_all_coll_metadata_ops_f

Signature:

  SUBROUTINE h5pset_all_coll_metadata_ops_f(plist_id, is_collective, hdferr)
    INTEGER(HID_T)  , INTENT(IN)  :: plist_id
    LOGICAL, INTENT(IN)           :: is_collective
    INTEGER, INTENT(OUT)          :: hdferr

Inputs:

  plist_id       - File access property list identifier.
  is_collective  - Indicates if metadata writes are collective or not.

Outputs:

  hdferr         - Returns 0 if successful and -1 if fails.

See Also:

H5Pset_coll_metadata_write H5Pget_coll_metadata_write	H5Pget_all_coll_metadata_ops
“Functions with No Access Property List Parameter that May Generate Metadata Reads”

History:

Release	Change
1.10.0	C function and Fortran wrapper introduced with this release.

Name: H5Pset_alloc_time

Signature:

herr_t H5Pset_alloc_time(hid_t plist_id, H5D_alloc_time_t alloc_time )

Purpose:

Sets the timing for storage space allocation.

Description:

H5Pset_alloc_time sets up the timing for the allocation of storage space for a dataset's raw data. This property is set in the dataset creation property list plist_id.

Timing is specified in alloc_time with one of the following values:

H5D_ALLOC_TIME_DEFAULT Allocate dataset storage space at the default time.
(Defaults differ by storage method.)
H5D_ALLOC_TIME_EARLY Allocate all space when the dataset is created.
(Default for compact datasets.)
H5D_ALLOC_TIME_INCR Allocate space incrementally, as data is written to the dataset.
(Default for chunked storage datasets.)

Chunked datasets: Storage space allocation for each chunk is deferred until data is written to the chunk.
Contiguous datasets: Incremental storage space allocation for contiguous data is treated as late allocation.
Compact datasets: Incremental allocation is not allowed with compact datasets; H5Pset_alloc_time will return an error.

H5D_ALLOC_TIME_LATE Allocate all space when data is first written to the dataset.
(Default for contiguous datasets.)

Note:

H5Pset_alloc_time is designed to work in concert with the dataset fill value and fill value write time properties, set with the functions H5Pset_fill_value and H5Pset_fill_time.

See H5Dcreate for further cross-references.

Parameters:

hid_t plist_id IN: Dataset creation property list identifier.

H5D_alloc_time_t alloc_time IN: When to allocate dataset storage space.

Returns:

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

Fortran90 Interface: h5pset_alloc_time_f

SUBROUTINE h5pset_alloc_time_f(plist_id, flag, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist_id  ! Dataset creation property
                                          ! list identifier
  INTEGER(HSIZE_T), INTENT(IN) :: flag    ! Allocation time flag
                                          ! Possible values are:
                                          !    H5D_ALLOC_TIME_ERROR_F
                                          !    H5D_ALLOC_TIME_DEFAULT_F
                                          !    H5D_ALLOC_TIME_EARLY_F
                                          !    H5D_ALLOC_TIME_LATE_F
                                          !    H5D_ALLOC_TIME_INCR_F
  INTEGER, INTENT(OUT)       :: hdferr    ! Error code
                                          ! 0 on success and -1 on failure
END SUBROUTINE h5pset_alloc_time_f

History:

Release C

1.6.0 Function introduced in this release.

Last modified: 27 May 2016

Name: H5Pset_append_flush

Signature:

herr_t H5Pset_append_flush (
              hid_t dapl_id, 
              int ndims, 
              const hsize_t boundary[], 
              H5D_append_cb_t  func, 
              void *user_data
        )

Purpose:

Sets two actions to perform when the size of a dataset’s dimension being appended reaches a specified boundary.

Description:

H5Pset_append_flush sets the following two actions to perform for a dataset associated with the dataset access property list dapl_id:

Call the callback function func set in the property list
Flush the dataset associated with the dataset access property list

When a user is appending data to a dataset via H5DOappend and the dataset’s newly extended dimension size hits a specified boundary, the library will first perform action #1 listed above. Upon return from the callback function, the library will then perform the above action #2 and return to the user. If no boundary is hit or set, the two actions above are not invoked.

The specified boundary is indicated by the parameter boundary. It is a 1-dimensional array with ndims elements, which should be the same as the rank of the dataset’s dataspace. While appending to a dataset along a particular dimension index via H5DOappend, the library determines a boundary is reached when the resulting dimension size is divisible by boundary[index]. A zero value for boundary[index] indicates no boundary is set for that dimension index.

The setting of this property will apply only for a chunked dataset with an extendible dataspace. A dataspace is extendible when it is defined with either one of the following:

A dataspace with fixed current and maximum dimension sizes
A dataspace with at least one unlimited dimension for its maximum dimension size

When creating or opening a chunked dataset, the library will check whether the boundary as specified in the access property list is set up properly. The library will fail the dataset create or open if the following conditions are true:

ndims, the number of elements for boundary, is not the same as the rank of the dataset’s dataspace.
A non-zero boundary value is specified for a non-extendible dimension.

The callback function func must conform to the following prototype:

typedef herr_t (H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *user_data)

The parameters of the callback function, per the above prototype, are defined as follows:

dataset_id is the dataset identifier.
cur_dims is the dataset’s current dimension sizes when a boundary is hit.
user_data is the user-defined input data.

Parameters:

`hid_t dapl_id`	IN: Dataset access property list identifier.
`int ndims`	IN: The number of elements for boundary.
`hsize_t *boundary`	IN: The dimension sizes used to determine the boundary.
`H5D_append_cb_t func`	IN: The user-defined callback function.
`void *user_data`	IN: The user-defined input data.

Returns:

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

Example Usage:

The example below illustrates the usage of this public routine to manage flush behavior while appending to a dataset. Note also the use of H5DOappend.

hsize_t dims[2] = {0, 100};
hsize_t max_dims[2] = {H5S_UNLIMITED, 100};
hsize_t boundary_dims[2] = {5, 0};
unsigned counter;
void *buf;
hid_t file_id;
hid_t dataset_id, dapl_id, type;

/* Open the file */
file_id = H5Fopen(FILE, H5F_ACC_RDWR|H5F_ACC_SWMR_WRITE, H5P_DEFAULT);

/* Create a copy of the dataset access property list */
dapl_id = H5Pcreate(H5P_DATASET_ACCESS);

/* Set up the append property values */
/* boundary_dims[0]=5: to invoke callback and flush every 5 lines */
/* boundary_dims[1]=0: no boundary is set for the non-extendible dimension */
/* append_cb: callback function to invoke when hitting boundary (see below) */
/* counter: user data to pass along to the callback function */
H5Pset_append_flush(dapl_id, 2, boundary_dims, append_cb, &counter);

/* DATASET is a 2-dimensional chunked dataset with dataspace: 
   dims[] and max_dims[] */
dataset_id = H5Dopen2(file_id, �dataset�, dapl_id);

/* Get the dataset�s datatype */
type = H5Dget_type(dataset_id);

/* Append 50 lines along the unlimited dimension (index = 0) to the dataset */
for(n = 0; n < 50; n++) {

    /* Append 1 line to the dataset */  
    /* Whenever hitting the specified boundary i.e., every 5 lines, 
       the library will invoke append_cb() and then flush the dataset. */ 
    H5DOappend(dataset_id, H5P_DEFAULT, 0, 1, type, buf);
}
:
:
:
/* counter will be equal to 10 */
:
:
:

/* The callback function */
static herr_t
append_cb(hid_t dset_id, hsize_t *cur_dims, void *_udata)
{
    unsigned *count = (unsigned *)_udata;
    ++(*count++);
    return 0;
} /* append_cb() */

Fortran Interface:

None

See Also:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 20 March 2012

Name: H5Pset_attr_creation_order

Signature:

herr_t H5Pset_attr_creation_order( hid_t ocpl_id, unsigned crt_order_flags )

Purpose:

Sets tracking and indexing of attribute creation order.

Description:

H5Pset_attr_creation_order sets flags for tracking and indexing attribute creation order on an object.

ocpl_id is a dataset or group creation property list identifier. The term ocpl, for object creation property list, is used when more than one type of object may be involved.

crt_order_flags contains flags with the following meanings:

H5P_CRT_ORDER_TRACKED Attribute creation order is tracked but not necessarily indexed.
H5P_CRT_ORDER_INDEXED Attribute creation order is indexed (requires H5P_CRT_ORDER_TRACKED).

Default behavior is that attribute creation order is neither tracked nor indexed.

H5Pset_attr_creation_order can be used to set attribute creation order tracking, or to set attribute creation order tracking and indexing.

Note that if a creation order index is to be built, it must be specified in the object creation property list. HDF5 currently provides no mechanism to turn on attribute creation order tracking at object creation time and to build the index later.

Parameters:

hid_t `ocpl_id`	IN: Object creation property list identifier
unsigned `crt_order_flags`	IN: Flags specifying whether to track and index attribute creation order Default: No flag set; attribute creation order is neither tracked not indexed.

Returns:

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

Fortran90 Interface: h5pset_attr_creation_order_f

SUBROUTINE h5pset_attr_creation_order_f(ocpl_id, crt_order_flags , hdferr)
  IMPLICIT NONE 
  INTEGER(HID_T), INTENT(IN) :: ocpl_id   ! Object (dataset or group) creation 
                                          ! property list identifier
  INTEGER, INTENT(IN) :: crt_order_flags  ! Flags specifying whether to track 
                                          ! and index attribute creation order
  INTEGER, INTENT(OUT) :: hdferr          ! Error code 
                                          ! 0 on success and -1 on failure
END SUBROUTINE h5pset_attr_creation_order_f

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Pset_attr_phase_change

Signature:

herr_t H5Pset_attr_phase_change( hid_t ocpl_id, unsigned max_compact, unsigned min_dense )

Purpose:

Sets attribute storage phase change thresholds.

Description:

H5Pset_attr_phase_change sets threshold values for attribute storage on an object. These thresholds determine the point at which attribute storage changes from compact storage (i.e., storage in the object header) to dense storage (i.e., storage in a heap and indexed with a B-tree).

If max_compact is set to 0 (zero), dense storage always used.

ocpl_id is a dataset or group creation property list identifier. The term ocpl, for object creation property list, is used when different types of objects may be involved.

Parameters:

hid_t `ocpl_id`	IN: Object (group or dataset) creation property list identifier
unsigned `max_compact`	IN: Maximum number of attributes to be stored in compact storage (Default: 8)
unsigned `min_dense`	IN: Minimum number of attributes to be stored in dense storage (Default: 6)

Returns:

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

Fortran90 Interface: h5pset_attr_phase_change_f

SUBROUTINE h5pset_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: ocpl_id 
                              ! Object (dataset or group) creation property 
                              ! list identifier
  INTEGER, INTENT(IN) :: max_compact  
                              ! Maximum number of attributes to be stored in 
                              ! compact storage (Default: 8)
  INTEGER, INTENT(IN) :: min_dense  
                              ! Minimum number of attributes to be stored in 
                              ! dense storage (Default: 6)
  INTEGER, INTENT(OUT) :: hdferr 
                              ! Error code
                              ! 0 on success and -1 on failure
END SUBROUTINE h5pset_attr_phase_change_f

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Pset_btree_ratios

Signature:

herr_t H5Pset_btree_ratios(hid_t plist, double left, double middle, double right )

Purpose:

Sets B-tree split ratios for a dataset transfer property list.

Description:

H5Pset_btree_ratios sets the B-tree split ratios for a dataset transfer property list. The split ratios determine what percent of children go in the first node when a node splits.

The ratio left is used when the splitting node is the left-most node at its level in the tree; the ratio right is used when the splitting node is the right-most node at its level; and the ratio middle is used for all other cases.

A node which is the only node at its level in the tree uses the ratio right when it splits.

All ratios are real numbers between 0 and 1, inclusive.

Parameters:

hid_t plist IN: The dataset transfer property list identifier.

double left IN: The B-tree split ratio for left-most nodes.

double right IN: The B-tree split ratio for right-most nodes and lone nodes.

double middle IN: The B-tree split ratio for all other nodes.

Returns:

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

Fortran90 Interface: h5pset_btree_ratios_f

SUBROUTINE h5pset_btree_ratios_f(prp_id, left, middle, right, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id   
                                  ! Property list identifier
  REAL, INTENT(IN) :: left        ! The B-tree split ratio for left-most nodes
  REAL, INTENT(IN) :: middle      ! The B-tree split ratio for all other nodes
  REAL, INTENT(IN) :: right       ! The B-tree split ratio for right-most
                                  ! nodes and lone nodes.
  INTEGER, INTENT(OUT) :: hdferr  ! Error code
                                  ! 0 on success and -1 on failure
END SUBROUTINE h5pset_btree_ratios_f

Name: H5Pset_buffer

Signature:

herr_t H5Pset_buffer(hid_t plist, hsize_t size, void *tconv, void *bkg )

Purpose:

Sets type conversion and background buffers.

Description:

Given a dataset transfer property list, H5Pset_buffer sets the maximum size for the type conversion buffer and background buffer and optionally supplies pointers to application-allocated buffers. If the buffer size is smaller than the entire amount of data being transferred between the application and the file, and a type conversion buffer or background buffer is required, then strip mining will be used.

Note that there are minimum size requirements for the buffer. Strip mining can only break the data up along the first dimension, so the buffer must be large enough to accommodate a complete slice that encompasses all of the remaining dimensions. For example, when strip mining a 100x200x300 hyperslab of a simple data space, the buffer must be large enough to hold 1x200x300 data elements. When strip mining a 100x200x300x150 hyperslab of a simple data space, the buffer must be large enough to hold 1x200x300x150 data elements.

If tconv and/or bkg are null pointers, then buffers will be allocated and freed during the data transfer.

The default value for the maximum buffer is 1 Mb.

Parameters:

hid_t plist IN: Identifier for the dataset transfer property list.

hsize_t size IN: Size, in bytes, of the type conversion and background buffers.

void tconv IN: Pointer to application-allocated type conversion buffer.

void bkg IN: Pointer to application-allocated background buffer.

Returns:

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

Fortran90 Interface: h5pset_buffer_f

SUBROUTINE h5pset_buffer_f(plist_id, size, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN)   :: plist_id ! Dataset transfer property 
                                           ! list identifier
  INTEGER(HSIZE_T), INTENT(IN) :: size     ! Conversion buffer size
  INTEGER, INTENT(OUT)         :: hdferr   ! Error code
                                           ! 0 on success and -1 on failure
END SUBROUTINE h5pset_buffer_f

History:

Release C

1.6.0 The size parameter has changed from type hsize_t to size_t.

1.4.0 The size parameter has changed to type hsize_t.

Last modified: 22 July 2014

Name: H5Pset_cache

Signature:

herr_t H5Pset_cache(hid_t plist_id,
        int mdc_nelmts,
        size_t rdcc_nslots,
        size_t rdcc_nbytes,
        double rdcc_w0)

Purpose:

Sets the raw data chunk cache parameters.

Motivation:

Setting raw data chunk cache parameters can be done with H5Pset_cache, H5Pset_chunk_cache, or a combination of both. H5Pset_cache is used to adjust the chunk cache parameters for all datasets via a global setting for the file, and H5Pset_chunk_cache is used to adjust the chunk cache parameters for individual datasets. When both are used, parameters set with H5Pset_chunk_cache will override any parameters set with H5Pset_cache.

Optimum chunk cache parameters may vary widely depending on different data layout and access patterns. For datasets with low performance requirements for example, changing the cache settings can save memory.

Description:

H5Pset_cache sets the number of elements, the total number of bytes, and the preemption policy value for all datasets in a file on the file’s file access property list.

The raw data chunk cache inserts chunks into the cache by first computing a hash value using the address of a chunk and then by using that hash value as the chunk’s index into the table of cached chunks. In other words, the size of this hash table and the number of possible hash values is determined by the rdcc_nslots parameter. If a different chunk in the cache has the same hash value, a collision will occur, which will reduce efficiency. If inserting the chunk into the cache would cause the cache to be too big, then the cache will be pruned according to the rdcc_w0 parameter.

The mdc_nelmts parameter is no longer used; any value passed in that parameter will be ignored.

Note:

Raw dataset chunk caching is not currently supported when using the MPI I/O and MPI POSIX file drivers in read/write mode; see H5Pset_fapl_mpio and H5Pset_fapl_mpiposix, respectively. When using one of these file drivers, all calls to H5Dread and H5Dwrite will access the disk directly, and H5Pset_cache will have no effect on performance.

Raw dataset chunk caching is supported when these drivers are used in read-only mode.

Parameters:

`hid_t plist_id`	IN: File access property list identifier.
`int mdc_nelmts`	IN: No longer used; any value passed is ignored.
`size_t rdcc_nslots`	IN: The number of chunk slots in the raw data chunk cache for this dataset. Increasing this value reduces the number of cache collisions, but slightly increases the memory used. Due to the hashing strategy, this value should ideally be a prime number. As a rule of thumb, this value should be at least 10 times the number of chunks that can fit in `rdcc_nbytes` bytes. For maximum performance, this value should be set approximately 100 times that number of chunks. The default value is 521.
`size_t rdcc_nbytes`	IN: Total size of the raw data chunk cache in bytes. The default size is 1 MB per dataset.
`double rdcc_w0`	IN: The chunk preemption policy for all datasets. This must be between 0 and 1 inclusive and indicates the weighting according to which chunks which have been fully read or written are penalized when determining which chunks to flush from cache. A value of 0 means fully read or written chunks are treated no differently than other chunks (the preemption is strictly LRU) while a value of 1 means fully read or written chunks are always preempted before other chunks. If your application only reads or writes data once, this can be safely set to 1. Otherwise, this should be set lower depending on how often you re-read or re-write the same data. The default value is 0.75. If the value passed is `H5D_CHUNK_CACHE_W0_DEFAULT`, then the property will not be set on `dapl_id`, and the parameter will come from the file access property list.

Returns:

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

Fortran90 Interface: h5pset_cache_f

SUBROUTINE h5pset_cache_f(prp_id, mdc_nelmts, rdcc_nslots, rdcc_nbytes, rdcc_w0, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id        ! Property list identifier
  INTEGER, INTENT(IN) :: mdc_nelmts           ! No longer used; any value passed
                                              ! is ignored.
  INTEGER(SIZE_T), INTENT(IN) :: rdcc_nslots  ! The number of chunk slots
                                              ! in the raw data chunk cache.
  INTEGER(SIZE_T), INTENT(IN) :: rdcc_nbytes  ! Total size of the raw data
                                              ! chunk cache in bytes.
  REAL, INTENT(IN) :: rdcc_w0                 ! Preemption policy
  INTEGER, INTENT(OUT) :: hdferr              ! Error code
                                              ! 0 on success and -1 on failure
END SUBROUTINE h5pset_cache_f

See Also:

H5Pget_cache
H5Pset_chunk_cache
“Chunking in HDF5”

History:

Release	Change
1.8.0	In C, use of the `mdc_nelmts` parameter discontinued. Metadata cache configuration is managed with `H5Pset_mdc_config` and `H5Pget_mdc_config`.
1.6.1	Fortran `rdcc_nbytes` parameter type changed to `INTEGER(SIZE_T)`.
1.6.0	In C, the `rdcc_nbytes` and `rdcc_nelmts` parameters changed from type int to size_t.

Last modified: 24 September 2014

Name: H5Pset_char_encoding

Signature:

herr_t H5Pset_char_encoding( hid_t plist_id, H5T_cset_t encoding )

Purpose:

Sets the character encoding used to encode link and attribute names.

Description:

H5Pset_char_encoding sets the character encoding used for the names of links (which provide the names by which objects are referenced) or attributes created with the property list plist_id.

Valid values for encoding include the following:

H5T_CSET_ASCII US ASCII
H5T_CSET_UTF8 UTF-8 Unicode

For example, if the character set for the property list plist_id is set to H5T_CSET_UTF8, link names pointing to objects created with the link creation property list plist_id will be encoded using the UTF-8 character set. Similarly, names of attributes created with the attribute creation property list plist_id will be encoded as UTF-8.

ASCII and UTF-8 Unicode are the only currently supported character encodings. Extended ASCII encodings (for example, ISO 8859) are not supported. This encoding policy is not enforced by the HDF5 Library. Using encodings other than ASCII and UTF-8 can lead to compatibility and usability problems.

Note that H5Pset_char_encoding sets the character set used for an HDF5 link or attribute name while H5Tset_cset sets the character set used in a character or string datatype.

Parameters:

hid_t `plist_id`	IN: Link creation or attribute creation property list identifier
H5T_cset_t `encoding`	IN: String encoding character set

Returns:

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

Fortran90 Interface: h5set_char_encoding_f

SUBROUTINE h5pset_char_encoding_f(plist_id, encoding, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist_id
                                  ! Property list identifier
  INTEGER, INTENT(IN) :: encoding ! String encoding character set:
                                  !   H5T_CSET_ASCII_F -> US ASCII
                                  !   H5T_CSET_UTF8_F -> UTF-8 Unicode encoding
  INTEGER, INTENT(OUT) :: hdferr  ! Error code
                                  ! 0 on success and -1 on failure
END SUBROUTINE h5pset_char_encoding_f

History:

Release	C
1.8.0	Function introduced in this release.

Last modified: 16 September 2015

Name: H5Pset_chunk

Signature:

herr_t H5Pset_chunk(hid_t plist, int ndims, const hsize_t * dim )

Purpose:

Sets the size of the chunks used to store a chunked layout dataset.

Description:

H5Pset_chunk sets the size of the chunks used to store a chunked layout dataset. This function is only valid for dataset creation property lists.

The ndims parameter currently must be the same size as the rank of the dataset.

The values of the dim array define the size of the chunks to store the dataset's raw data. The unit of measure for dim values is dataset elements.

As a side-effect of this function, the layout of the dataset is changed to H5D_CHUNKED, if it is not already so set. (See H5Pset_layout.)

Notes:

Chunk size cannot exceed the size of a fixed-size dataset. For example, a dataset consisting of a 5x4 fixed-size array cannot be defined with 10x10 chunks.
Chunk maximums

The maximum number of elements in a chunk is 2³²-1 which is equal to 4,294,967,295. If the number of elements in a chunk is set via H5Pset_chunk to a value greater than 2³²-1, then H5Pset_chunk will fail.
The maximum size for any chunk is 4GB. If a chunk that is larger than 4GB attempts to be written with H5Dwrite, then H5Dwrite will fail.

Parameters:

hid_t `plist`	IN: Dataset creation property list identifier.
int `ndims`	IN: The number of dimensions of each chunk.
const hsize_t * `dim`	IN: An array defining the size, in dataset elements, of each chunk.

Returns:

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

Fortran90 Interface: h5pset_chunk_f

SUBROUTINE h5pset_chunk_f(prp_id, ndims, dims, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id  ! Property list identifier 
  INTEGER, INTENT(IN) :: ndims          ! Number of chunk dimensions
  INTEGER(HSIZE_T), DIMENSION(ndims), INTENT(IN) :: dims    
                                        ! Array containing sizes of
                                        ! chunk dimensions
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pset_chunk_f

History:

Release	Change
1.8.16	Added chunk size limit note to Description.

Last modified: 4 November 2014

Name: H5Pset_chunk_cache

Signature:

herr_t H5Pset_chunk_cache( hid_t dapl_id, size_t rdcc_nslots, size_t rdcc_nbytes, double rdcc_w0 )

Purpose:

Sets the raw data chunk cache parameters.

Motivation:

H5Pset_chunk_cache is used to adjust the chunk cache parameters on a per-dataset basis, as opposed to a global setting for the file using H5Pset_cache. The optimum chunk cache parameters may vary widely with different data layout and access patterns, so for optimal performance they must be set individually for each dataset. It may also be beneficial to reduce the size of the chunk cache for datasets whose performance is not important in order to save memory space.

Description:

H5Pset_chunk_cache sets the number of elements, the total number of bytes, and the preemption policy value in the raw data chunk cache on a dataset access property list. After calling this function, the values set in the property list will override the values in the file's file access property list.

The raw data chunk cache inserts chunks into the cache by first computing a hash value using the address of a chunk, then using that hash value as the chunk's index into the table of cached chunks. The size of this hash table, i.e., and the number of possible hash values, is determined by the rdcc_nslots parameter. If a different chunk in the cache has the same hash value, this causes a collision, which reduces efficiency. If inserting the chunk into cache would cause the cache to be too big, then the cache is pruned according to the rdcc_w0 parameter.

Parameters:

hid_t `dapl_id`		IN: Dataset access property list identifier.
size_t `rdcc_nslots`		IN:The number of chunk slots in the raw data chunk cache for this dataset. Increasing this value reduces the number of cache collisions, but slightly increases the memory used. Due to the hashing strategy, this value should ideally be a prime number. As a rule of thumb, this value should be at least 10 times the number of chunks that can fit in `rdcc_nbytes` bytes. For maximum performance, this value should be set approximately 100 times that number of chunks. The default value is `521`. If the value passed is `H5D_CHUNK_CACHE_NSLOTS_DEFAULT`, then the property will not be set on `dapl_id` and the parameter will come from the file access property list used to open the file.
size_t `rdcc_nbytes`		IN: The total size of the raw data chunk cache for this dataset. In most cases increasing this number will improve performance, as long as you have enough free memory. The default size is 1 MB. If the value passed is `H5D_CHUNK_CACHE_NBYTES_DEFAULT`, then the property will not be set on `dapl_id` and the parameter will come from the file access property list.
double `rdcc_w0`		IN: The chunk preemption policy for this dataset. This must be between `0` and `1` inclusive and indicates the weighting according to which chunks which have been fully read or written are penalized when determining which chunks to flush from cache. A value of `0` means fully read or written chunks are treated no differently than other chunks (the preemption is strictly LRU) while a value of `1` means fully read or written chunks are always preempted before other chunks. If your application only reads or writes data once, this can be safely set to `1`. Otherwise, this should be set lower, depending on how often you re-read or re-write the same data. The default value is `0.75`. If the value passed is `H5D_CHUNK_CACHE_W0_DEFAULT`, then the property will not be set on `dapl_id` and the parameter will come from the file access property list.

Returns:

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

Example Usage:

The following code sets the chunk cache to use a hash table with 12421 elements and a maximum size of 16 MB, while using the preemption policy specified for the entire file:

H5Pset_chunk_cache(dapl_id, 12421, 16*1024*1024, H5D_CHUNK_CACHE_W0_DEFAULT);

Usage Notes:

The chunk cache size is a property for accessing a dataset and is not stored with a dataset or a file. To guarantee the same chunk cache settings each time H5Dopen is called, call H5Dopen with a dataset access property list (

H5Dopen(hid_t loc_id, 
    const char *name, hid_t dapl_id))

where the chunk cache size is set by calling H5Pset_chunk_cache for that property list. The property list can be used for multiple accesses in the same application.

For files where the same chunk cache size will be appropriate for all or most datasets, H5Pset_cache can be called with a file access property list to set the chunk cache size for accessing all datasets in the file.

Both methods can be used in combination, in which case the chunk cache size set by H5Pset_cache will apply except for specific datasets where H5Dopen is called with dataset property list with the chunk cache size set by H5Pset_chunk_cache.

In the absence of any cache settings, H5Dopen will by default create a 1 MB chunk cache for the opened dataset. If this size happens to be appropriate, no call will be needed to either function to set the chunk cache size.

It is also possible that a change in access pattern for later access to a dataset will change the appropriate chunk cache size. For more detailed information on chunks, chunk caching, and performance pitfalls, see “Chunking in HDF5”.

Fortran90 Interface: h5pset_chunk_cache_f

SUBROUTINE h5pset_chunk_cache_f(dapl_id, rdcc_nslots, rdcc_nbytes, rdcc_w0, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: dapl_id      ! Dataset access property list 
                                             ! identifier.
  INTEGER(SIZE_T), INTENT(IN) :: rdcc_nslots ! The number of chunk slots in the 
                                             ! raw data chunk cache for this 
                                             ! dataset.
  INTEGER(SIZE_T), INTENT(IN) :: rdcc_nbytes ! The total size of the raw data 
                                             ! chunk cache for this dataset.
  REAL, INTENT(IN) :: rdcc_w0                ! The chunk preemption policy for 
                                             ! this dataset.
  INTEGER, INTENT(OUT) :: hdferr             ! Error code
                                             ! 0 on success and -1 on failure
END SUBROUTINE h5pset_chunk_cache_f

See Also:

H5Pget_chunk_cache
H5Pset_cache
“Chunking in HDF5”

History:

Release	Change
1.8.3	C function introduced in this release.

Last modified: 6 June 2016

Name: H5Pset_chunk_opts

Signature:

herr_t H5Pset_chunk_opts(
        hid_t dcpl_id,
        unsigned opts
        )

Purpose:

Sets the edge chunk option in a dataset creation property list.

Motivation:

H5Pset_chunk_opts is used to specify storage options for chunks on the edge of a dataset’s dataspace. This capability allows the user to tune performance in cases where the dataset size may not be a multiple of the chunk size and the handling of partial edge chunks can impact performance.

Description:

H5Pset_chunk_opts sets the edge chunk option in the dataset creation property list dcpl_id.

The available option is detailed in the parameters section below. Only chunks that are not completely filled by the dataset’s dataspace are affected by this option. Such chunks are referred to as partial edge chunks.

Parameters:

hid_t dcpl_id IN: Dataset creation property list identifier

unsigned opts

IN: Edge chunk option flag. Valid values are:

`H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS`
	When enabled, filters are not applied to partial edge chunks. When disabled, partial edge chunks are filtered. Enabling this option will improve performance when appending to the dataset and, when compression filters are used, prevent reallocation of these chunks. Datasets created with this option enabled will be inaccessible with HDF5 Library versions before Release 1.10. Default: Disabled
`0` (zero)
	Disables option; partial edge chunks will be compressed.

Returns:

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

Fortran Interface:

None

See Also:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 6 April 2016

Name: H5Pset_coll_metadata_write

Signature:

herr_t H5Pset_coll_metadata_write(
              hid_t fapl_id,
              hbool_t is_collective
        )

Purpose:

Sets metadata write mode to collective or independent (default).

Description:

H5Pset_coll_metadata_write tells the HDF5 Library whether to perform metadata writes collectively (TRUE) or independently (FALSE).

If collective access is selected, then on a flush of the metadata cache, all processes will divide the metadata cache entries to be flushed evenly among themselves and issue a single MPI-IO collective write operation. This is the preferred method when the size of the metadata created by the application is large.

If independent access is selected, the library uses the default method for doing metadata I/O either from process zero or independently from each process.

Parameters:

`hid_t fapl_id`		IN: File access propery list identifier
`hbool_t is_collective`		IN: Boolean value indicating whether metadata writes are collective (`TRUE`) or independent (`FALSE`) Default mode: Independent (`FALSE`)

Returns:

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

Fortran Interface: h5pset_coll_metadata_write_f

Signature:

  SUBROUTINE h5pset_coll_metadata_write_f(plist_id, is_collective, hdferr)
    INTEGER(HID_T)  , INTENT(IN)  :: plist_id
    LOGICAL, INTENT(IN)           :: is_collective
    INTEGER, INTENT(OUT)          :: hdferr

Inputs:

  fapl_id        - File access property list identifier.
  is_collective  - Indicates if metadata writes are collective or not.

Outputs:

  hdferr         - Returns 0 if successful and -1 if fails.

See Also:

H5Pget_coll_metadata_write

History:

Release	Change
1.10.0	C function and Fortran wrapper introduced with this release.

Last modified: 3 July 2013

Name: H5Pset_copy_object

Signature:

herr_t H5Pset_copy_object( hid_t ocpypl_id, unsigned copy_options )

Purpose:

Sets properties to be used when an object is copied.

Description:

H5Pset_copy_object sets properties in the object copy property list ocpypl_id. When an existing object is copied, that property list will determine how the new copy is created.

The following flags are available for use in an object copy property list:

`H5O_COPY_SHALLOW_HIERARCHY_FLAG`	Copy only immediate members of a group. Default behavior, without flag: Recursively copy all objects in and below the group.
`H5O_COPY_EXPAND_SOFT_LINK_FLAG`	Expand soft links into new objects. Default behavior, without flag: Copy soft links as they are.
`H5O_COPY_EXPAND_EXT_LINK_FLAG`	Expand external link into new objects. Default behavior, without flag: Copy external links as they are.
`H5O_COPY_EXPAND_REFERENCE_FLAG`	Copy objects that are pointed to by references and update reference values in destination file. Default behavior, without flag: Set reference values in destination file to zero (`0`).
`H5O_COPY_WITHOUT_ATTR_FLAG`	Copy object without copying attributes. Default behavior, without flag: Copy object with all its attributes.
`H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG`	Use a matching committed datatype in the destination file when copying a committed datatype, a dataset with a committed datatype, or an object with an attribute of committed datatype. Default behavior without flag: A committed datatype in the source will be copied to the destination as a committed datatype. If a dataset in the source uses a committed datatype or an object in the source has an attribute of a committed datatype, that committed datatype will be written to the destination as an anonymous committed datatype. If copied in a single `H5Ocopy` operation, objects that share a committed datatype in the source will share an anonymous committed dataype in the destination copy. Subsequent `H5Ocopy` operations, however, will be unaware of prior anonymous committed dataypes and will create new ones. See the “See Also” section immediately below for functions related to the use of this flag.

Parameters:

hid_t `ocpypl_id`	IN: Object copy property list identifier
unsigned `copy_options`	IN: Copy option(s) to be set

Returns:

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

See Also:

`H5Ocopy`
Copying Committed Datatypes with `H5Ocopy`		A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5
`H5Padd_merge_committed_dtype_path` `H5Pfree_merge_committed_dtype_paths` `H5Pset_mcdt_search_cb` `H5Pget_mcdt_search_cb` `H5O_mcdt_search_cb_t`		Functions and a callback function used to tune committed datatype copying behavior

Fortran90 Interface: h5pset_copy_object_f

SUBROUTINE h5pset_copy_object_f(ocpypl_id, copy_options, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: ocpypl_id 
                              ! Object copy property list identifier
  INTEGER, INTENT(IN) :: copy_options 
                              ! Copy option(s) to be set, valid options are:
                              !   H5O_COPY_SHALLOW_HIERARCHY_F
                              !   H5O_COPY_EXPAND_SOFT_LINK_F 
                              !   H5O_COPY_EXPAND_EXT_LINK_F
                              !   H5O_COPY_EXPAND_REFERENCE_F
                              !   H5O_COPY_WITHOUT_ATTR_FLAG_F
                              !   H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG_F

  INTEGER, INTENT(OUT) :: hdferr      
                              ! Error code
                              ! 0 on success and -1 on failure
END SUBROUTINE h5pset_copy_object_f

History:

Release	C
1.8.0	Function introduced in this release.
1.8.9	`H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG` added in this release.

Last modified: 13 August 2014

Name: H5Pset_core_write_tracking

Signature:

herr_t H5Pset_core_write_tracking(
              hid_t fapl_id, 
              hbool_t is_enabled, 
              size_t page_size
         )

Purpose:

Sets write tracking information for core driver, H5FD_CORE.

Description:

When a file is created or opened for writing using the core virtual file driver (VFD) with the backing store option turned on, the core driver can be configured to track changes to the file and write out only the modified bytes.

This write tracking feature is enabled and disabled with is_enabled. The default setting is that write tracking is disabled, or off.

To avoid a large number of small writes, changes can be aggregated into pages of a user-specified size, page_size.

Setting page_size to 1 enables tracking with no page aggregation.

The backing store option is set via the function H5Pset_fapl_core.

Notes:

This function is only for use with the core VFD and must be used after the call to H5Pset_fapl_core. It is an error to use this function with any other VFD.

It is an error to use this function when the backing store flag has not been set using H5Pset_fapl_core.

This function only applies to the backing store write operation which typically occurs when the file is flushed or closed. This function has no relationship to the increment parameter passed to H5Pset_fapl_core.

For optimum performance, the page_size parameter should be a power of two.

It is an error to set the page size to 0.

Parameters:

`hid_t fapl_id`	IN: File access property list identifier.
`hbool_t is_enabled`	IN: Boolean value specifying whether feature is enabled.
`size_t page_size`	IN: Positive integer specifying size, in bytes, of write aggregation pages. Value of `1` (one) enables tracking with no paging.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran Interface:

None

See Also:


    H5Pget_core_write_tracking

History:

Release	Change
1.8.13	C function introduced with this release.
1.8.14	C function modified in this release to return error if `page_size` is set to `0` (zero).

Last modified: 11 May 2011

Name: H5Pset_create_intermediate_group

Signature:

herr_t H5Pset_create_intermediate_group( hid_t lcpl_id, unsigned crt_intermed_group )

Purpose:

Specifies in property list whether to create missing intermediate groups.

Description:

H5Pset_create_intermediate_group specifies whether to set the link creation property list lcpl_id so that calls to functions that create objects in groups different from the current working group will create intermediate groups that may be missing in the path of a new or moved object.

Functions that create objects in or move objects to a group other than the current working group make use of this property. H5Gcreate_anon and H5Lmove are examples of such functions.

If crt_intermed_group is positive, the H5G_CRT_INTMD_GROUP will be added to lcpl_id (if it is not already there). Missing intermediate groups will be created upon calls to functions such as those listed above that use lcpl_id.

If crt_intermed_group is non-positive, the H5G_CRT_INTMD_GROUP, if present, will be removed from lcpl_id. Missing intermediate groups will not be created upon calls to functions such as those listed above that use lcpl_id.

Parameters:

hid_t `lcpl_id`	IN: Link creation property list identifier
unsigned `crt_intermed_group`	IN: Flag specifying whether to create intermediate groups upon the creation of an object

Returns:

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

Example:

The following call sets the link creation property list lcpl_id such that a call to H5Gcreate_anon or other function using lcpl_id will create any missing groups in the path to the new object:

    herr_t ret_value = H5Pset_create_intermediate_group(lcpl_id, 1)

Fortran90 Interface: h5pset_create_inter_group_f

SUBROUTINE h5pset_create_inter_group_f(lcpl_id, crt_intermed_group, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: lcpl_id 
                           ! Link creation property list identifier
  INTEGER, INTENT(IN) :: crt_intermed_group  
                           ! Specifying whether to create intermediate groups 
                           ! upon the creation of an object
  INTEGER, INTENT(OUT) :: hdferr 
                           ! Error code
                           ! 0 on success and -1 on failure
END SUBROUTINE h5pset_create_inter_group_f

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Pset_data_transform

Signature:

herr_t H5Pset_data_transform (hid_t plist_id, const char *expression)

Purpose:

Sets a data transform expression.

Description:

H5Pset_data_transform sets the data transform to be used for reading and writing data. This function operates on the dataset transfer property lists plist_id.

The expression parameter is a string containing an algebraic expression, such as (5/9.0)*(x-32) or x*(x-5). When a dataset is read or written with this property list, the transform expression is applied with the x being replaced by the values in the dataset. When reading data, the values in the file are not changed and the transformed data is returned to the user.

Data transforms can only be applied to integer or floating-point datasets. Order of operations is obeyed and the only supported operations are +, -, *, and /. Parentheses can be nested arbitrarily and can be used to change precedence.

When writing data back to the dataset, the transformed data is written to the file and there is no way to recover the original values to which the transform was applied.

Parameters:

hid_t plist_id IN: Identifier of the property list or class

const char *expression IN: Pointer to the null-terminated data transform expression

Returns:

Success: a non-negative value

Failure: a negative value

Fortran90 Interface: h5pset_data_transform_f

SUBROUTINE h5pset_data_transform_f(plist_id, expression, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist_id 
                                    ! Identifier of the property list or class
  CHARACTER(LEN=*), INTENT(IN) :: expression  
                                    ! Buffer to hold transform expression
  INTEGER, INTENT(OUT) :: hdferr    ! Error code
                                    ! 0 on success and -1 on failure
END SUBROUTINE h5pset_data_transform_f

History:

Release	C
1.8.0	Function introduced in this release.

Last modified: 20 June 2013

Name: H5Pset_deflate

Signature:

herr_t H5Pset_deflate( hid_t plist_id, uint level )

Purpose:

Sets deflate (GNU gzip) compression method and compression level.

Description:

H5Pset_deflate sets the deflate compression method and the compression level, level for a dataset or group creation property list, plist_id.

The filter identifier set in the propertly list is H5Z_FILTER_DEFLATE.

The compression level, level, is a value from zero to nine, inclusive. A compression level of 0 (zero) indicates no compression; compression improves but speed slows progressively from levels 1 through 9:

Compression level Gzip action

0 No compression

1 Best compression speed; least compression

2 through 8 Compression improves; speed degrades

9 Best compression ratio; slowest speed

Note that setting the compression level to 0 (zero) does not turn off use of the gzip filter; it simply sets the filter to perform no compression as it processes the data.

HDF5 relies on GNU gzip for this compression (see zlib).

Parameters:

hid_t `plist_id`	IN: Dataset or group creation property list identifier.
uint `level`	IN: Compression level.

Returns:

Fortran90 Interface: h5pset_deflate_f

SUBROUTINE h5pset_deflate_f(prp_id, level, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier 
  INTEGER, INTENT(IN)        :: level  ! Compression level 
  INTEGER, INTENT(OUT)       :: hdferr ! Error code
                                       ! 0 on success and -1 on failure
END SUBROUTINE h5pset_deflate_f

History:

Release	Change
1.8.5	Function extended to work with group creation property lists.

Name: H5Pset_driver

Signature:

herr_t H5Pset_driver( hid_t plist_id, hid_t new_driver_id, const void *new_driver_info )

Purpose:

Sets a file driver.

Description:

H5Pset_driver sets the file driver, new_driver_id, for a file access or data transfer property list, plist_id, and supplies an optional struct containing the driver-specific properties, new_driver_info.

The driver properties will be copied into the property list and the reference count on the driver will be incremented, allowing the caller to close the driver identifier but still use the property list.

Note:

H5Pset_driver and H5Pget_driver_info are used only when creating a virtual file driver (VFD) in the virtual file layer (VFL). For further information, see “Virtual File Layer” and “List of VFL Functions” in the HDF5 Technical Notes.

Parameters:

hid_t plist_id: IN: File access or data transfer property list identifier.
hid_t new_driver_id: IN: Driver identifier.
const void * new_driver_info: IN: Optional struct containing driver properties.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran90 Interface:

None.

History:

Release C

1.8.2 Function publicized in this release; previous releases described this function only in the virtual file driver documentation.

Name: H5Pset_dxpl_mpio

Signature:

herr_t H5Pset_dxpl_mpio( hid_t dxpl_id, H5FD_mpio_xfer_t xfer_mode )

Purpose:

Sets data transfer mode.

Description:

H5Pset_dxpl_mpio sets the data transfer property list dxpl_id to use transfer mode xfer_mode. The property list can then be used to control the I/O transfer mode during data I/O operations.

Valid transfer modes are as follows:

H5FD_MPIO_INDEPENDENT: Use independent I/O access (default).
H5FD_MPIO_COLLECTIVE: Use collective I/O access.

Parameters:

hid_t dxpl_id IN: Data transfer property list identifier.

H5FD_mpio_xfer_t xfer_mode IN: Transfer mode.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran90 Interface:

SUBROUTINE h5pset_dxpl_mpio_f(prp_id, data_xfer_mode, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id  ! Property list identifier
  INTEGER, INTENT(IN) :: data_xfer_mode ! Data transfer mode 
                                        ! Possible values are:
                                        !    H5FD_MPIO_INDEPENDENT_F
                                        !    H5FD_MPIO_COLLECTIVE_F
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pset_dxpl_mpio_f

History:

Release C

1.4.0 Function introduced in this release.

Name: H5Pset_dxpl_mpio_chunk_opt

Signature:

herr_t H5Pset_dxpl_mpio_chunk_opt (hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode)

Purpose:

Sets a flag specifying linked-chunk I/O or multi-chunk I/O.

Description:

H5Pset_dxpl_mpio_chunk_opt specifies whether I/O is to be performed as linked-chunk I/O or as multi-chunk I/O. This function overrides the HDF5 Library's internal algorithm for determining which mechanism to use.

When an application uses collective I/O with chunked storage, the HDF5 Library normally uses an internal algorithm to determine whether that I/O activity should be conducted as one linked-chunk I/O or as multi-chunk I/O. H5Pset_dxpl_mpio_chunk_opt is provided so that an application can override the library's alogorithm in circumstances where the library might lack the information needed to make an optimal desision.

H5Pset_dxpl_mpio_chunk_opt works by setting one of the following flags in the parameter opt_mode:

`H5FD_MPIO_CHUNK_ONE_IO`	Do one link chunked I/O.
`H5FD_MPIO_CHUNK_MULTI_IO`	Do multi-chunked I/O.

This function works by setting a corresponding property in the dataset transfer property list dxpl_id.

The library perform I/O in the specified manner unless it determines that the low-level MPI IO package does not support the requested behavior; in such cases, the HDF5 Library will internally use independent I/O.

Use of this function is optional.

Parameters:

hid_t dxpl_id IN: Data transfer property list identifier

H5FD_mpio_chunk_opt_t opt_mode IN: Optimization flag specifying linked-chunk I/O or multi-chunk I/O

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Name: H5Pset_dxpl_mpio_chunk_opt_num
Signature:: herr_t H5Pset_dxpl_mpio_chunk_opt_num (hid_t dxpl_id, unsigned num_chunk_per_proc)
Purpose:: Sets a numeric threshold for linked-chunk I/O.
Description:: H5Pset_dxpl_mpio_chunk_opt_num sets a numeric threshold for the use of linked-chunk I/O.
The library will calculate the average number of chunks selected by each process when doing collective access with chunked storage. If the number is greater than the threshold set in num_chunk_per_proc, the library will use linked-chunk I/O; otherwise, a separate I/O process will be invoked for each chunk (multi-chunk I/O).
Parameters:

hid_t dxpl_id IN: Data transfer property list identifier

unsigned num_proc_per_chunk IN: Numeric threshold for performing linked-chunk I/O
Returns:: Returns a non-negative value if successful. Otherwise returns a negative value.

Name: H5Pset_dxpl_mpio_chunk_opt_ratio
Signature:: herr_t H5Pset_dxpl_mpio_chunk_opt_ratio (hid_t dxpl_id, unsigned percent_proc_per_chunk)
Purpose:: Sets a ratio threshold for collective I/O.
Description:: H5Pset_dxpl_mpio_chunk_opt_ratio sets a threshold for the use of collective I/O based on the ratio of processes with collective access to a dataset with chunked storage. The decision whether to use collective I/O is made on a per-chunk basis.
The library will calculate the percentage of the total number of processes, the ratio, that hold selections in each chunk. If that percentage is greater than the threshold set in percent_proc_per_chunk, the library will do collective I/O for this chunk; otherwise, independent I/O will be done for the chunk.
Parameters:

hid_t dxpl_id IN: Data transfer property list identifier

unsigned percent_proc_per_chunk IN: Percent threshold, on the number of processes holding selections per chunk, for performing linked-chunk I/O
Returns:: Returns a non-negative value if successful. Otherwise returns a negative value.

Name: H5Pset_dxpl_mpio_collective_opt

Signature:

herr_t H5Pset_dxpl_mpio_collective_opt (hid_t dxpl_id, H5FD_mpio_collective_opt_t opt_mode)

Purpose:

Sets a flag governing the use of independent versus collective I/O.

Description:

H5Pset_dxpl_mpio_collective_opt enables an application to specify that the HDF5 Library will use independent I/O internally when the dataset transfer property list dxpl_id is set for collective I/O, i.e., with H5FD_MPIO_COLLECTIVE specified. This allows the application greater control over low-level I/O while maintaining the collective interface at the application level.

H5Pset_dxpl_mpio_collective_opt works by setting one of the following flags in the parameter opt_mode:

`H5FD_MPIO_COLLECTIVE_IO`	Use collective I/O. (Default)
`H5FD_MPIO_INDIVIDUAL_IO`	Use independent I/O.

This function should be used only when H5FD_MPIO_COLLECTIVE has been set through H5Pset_dxpl_mpio. In such situations, normal behavior would be to use low-level collective I/O functions, but the library will use low-level MPI independent I/O functions when H5FD_MPIO_INDIVIDUAL_IO is set.

Use of this function is optional.

Parameters:

hid_t dxpl_id IN: Data transfer property list identifier

H5FD_mpio_collective_opt_t opt_mode IN: Optimization flag specifying the use of independent or collective I/O

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Last modified: 20 May 2010

Name: H5Pset_edc_check

Signature:

herr_t H5Pset_edc_check( hid_t plist, H5Z_EDC_t check )

Purpose:

Sets whether to enable error-detection when reading a dataset.

Description:

H5Pset_edc_check sets the dataset transfer property list plist to enable or disable error detection when reading data.

Whether error detection is enabled or disabled is specified in the check parameter. Valid values are as follows:

H5Z_ENABLE_EDC (default)
H5Z_DISABLE_EDC

The error detection algorithm used is the algorithm previously specified in the corresponding dataset creation property list. �

This function does not affect the use of error detection when writing data. �

Note:

The initial error detection implementation, Fletcher32 checksum, supports error detection for chunked datasets only.

Note:

The Fletcher32 EDC checksum filter, set with H5Pset_fletcher32, was added in HDF5 Release 1.6.0. In the original implementation, however, the checksum value was calculated incorrectly on little-endian systems. The error was fixed in HDF5 Release 1.6.3.

As a result of this fix, an HDF5 Library of Release 1.6.0 through Release 1.6.2 cannot read a dataset created or written with Release 1.6.3 or later if the dataset was created with the checksum filter and the filter is enabled in the reading library. (Libraries of Release 1.6.3 and later understand the earlier error and comensate appropriately.)

Work-around: An HDF5 Library of Release 1.6.2 or earlier will be able to read a dataset created or written with the checksum filter by an HDF5 Library of Release 1.6.3 or later if the checksum filter is disabled for the read operation. This can be accomplished via an H5Pset_edc_check call with the value H5Z_DISABLE_EDC in the second parameter. This has the obvious drawback that the application will be unable to verify the checksum, but the data does remain accessible.

Parameters:

hid_t plist IN: Dataset transfer property list identifier.

H5Z_EDC_t check IN: Specifies whether error checking is enabled or disabled for dataset read operations.

Returns:

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

Fortran90 Interface: h5pset_edc_check_f

SUBROUTINE h5pset_edc_check_f(prp_id, flag, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id   ! Dataset transfer property 
                                         ! list identifier 
  INTEGER, INTENT(IN)        :: flag     ! EDC flag; possible values
                                         !    H5Z_DISABLE_EDC_F 
                                         !    H5Z_ENABLE_EDC_F 
  INTEGER, INTENT(OUT)       :: hdferr   ! Error code
                                         ! 0 on success and -1 on failure
 
END SUBROUTINE h5pset_edc_check_f

History:

Release Change

1.6.0 Function introduced in this release.

1.6.3 Error in checksum calculation on little-endian systems corrected in this release.

Last modified: 26 April 2016

Name: H5Pset_efile_prefix

Signature:

herr_t H5Pset_efile_prefix(
        hid_t dapl_id,
        const char *prefix
        )

Purpose:

Sets the external dataset storage file prefix in the dataset access property list.

Description:

H5Pset_efile_prefix sets the prefix used to locate raw data files for a dataset that uses external storage. This prefix can provide either an absolute path or a relative path to the external files.

H5Pset_efile_prefix is used in conjunction with H5Pset_external to control the behavior of the HDF5 Library when searching for the raw data files associated with a dataset that uses external storage:

The default behavior of the library is to search for the dataset’s external storage raw data files in the same directory as the HDF5 file which contains the dataset.
If the prefix is set to an absolute path, the target directory will be searched for the dataset’s external storage raw data files.
If the prefix is set to a relative path, the target directory, relative to the current working directory, will be searched for the dataset’s external storage raw data files.
If the prefix is set to a relative path that begins with the special token ${ORIGIN}, that directory, relative to the HDF5 file containing the dataset, will be searched for the dataset’s external storage raw data files.

The HDF5_EXTFILE_PREFIX environment variable can be used to override the above behavior (the environment variable supersedes the API call). Setting the variable to a path string and calling H5Dcreate or H5Dopen is the equivalent of calling H5Pset_efile_prefix and calling the same create or open function. The environment variable is checked at the time of the create or open action and copied so it can be safely changed after the H5Dcreate or H5Dopen call.

Calling H5Pset_efile_prefix with prefix set to NULL or the empty string returns the search path to the default. The result would be the same as if H5Pset_efile_prefix had never been called.

Notes:

If the external file prefix is not an absolute path and the HDF5 file is moved, the external storage files will also need to be moved so they can be accessed at the new location.

As stated above, the use of the HDF5_EXTFILE_PREFIX environment variable overrides any property list setting. H5Pset_efile_prefix and H5Pget_efile_prefix, being property functions, set and retrieve only the property list setting; they are unaware of the environment variable.

On Windows, the prefix must be an ASCII string since the Windows standard C library’s I/O functions cannot handle UTF-8 file names.

Parameters:

`hid_t dapl_id`		IN: Dataset access property list identifier
`const char *prefix`		IN: Dataset external storage prefix in UTF-8 or ASCII (Path and filename must be ASCII on Windows systems.)

Returns:

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

Fortran Interface:

None

See Also:

History:

Release	Change
1.10.0 and 1.8.17	C function introduced in these releases.

Last modified: 8 May 2009

Name: H5Pset_elink_acc_flags

Signature:

herr_t H5Pset_elink_acc_flags( hid_t lapl_id, unsigned flags )

Purpose:

Sets the external link traversal file access flag in a link access property list.

Motivation:

H5Pset_elink_acc_flags is used to adjust the file access flag used to open files reached through external links. This may be useful to, for example, prevent modifying files accessed through an external link. Otherwise, the target file is opened with whatever flag was used to open the parent.

Description:

H5Pset_elink_acc_flags specifies the file access flag to use to open the target file of an external link. This allows read-only access of files reached through an external link in a file opened with write access, or vice-versa.

The library will normally use the file access flag used to open the parent file as the file access flag for the target file. This function provides a way to override that behaviour. The external link traversal callback function set by H5Pset_elink_cb can override the setting from H5Pset_elink_acc_flags.

Parameters:

hid_t lapl_id IN: Link access property list identifier

unsigned flags

IN: The access flag for external link traversal.

Valid values include:

H5F_ACC_RDWR Causes files opened through external links to be opened with write access.

H5F_ACC_RDONLY Causes files opened through external links to be opened with read-only access.

H5F_ACC_DEFAULT Removes any external link file access flag setting from lapl_id, causing the file access flag setting to be taken from the parent file.

Returns:

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

Example Usage:

The following code sets the link access property list lapl_id to open external link target files with read-only access:

status = H5Pset_elink_acc_flags(lapl_id, H5F_ACC_RDONLY);

See Also:

H5Pget_elink_acc_flags, H5Pset_elink_cb, H5Fopen, H5Lcreate_external

History:

Release	Change
1.8.3	C function introduced in this release.

Last modified: 18 June 2013

Name: H5Pset_elink_cb

Signature:

herr_t H5Pset_elink_cb( hid_t lapl_id, H5L_elink_traverse_t func, void *op_data )

Purpose:

Sets the external link traversal callback function in a link access property list.

Motivation:

H5Pset_elink_cb is used to specify a callback function that is executed by the HDF5 Library when traversing an external link. This provides a mechanism to set specific access permissions, modify the file access property list, modify the parent or target file, or take any other user-defined action. This callback function is used in situations where the HDF5 Library's default behavior is not suitable.

Description:

H5Pset_elink_cb sets a user-defined external link traversal callback function in the link access property list lapl_id. The callback function func must conform to the prototype specified in H5L_elink_traverse_t.

The callback function may adjust the file access property list and file access flags to use when opening a file through an external link. The callback will be executed by the HDF5 Library immediately before opening the target file.

The callback will be made after the file access property list set by H5Pset_elink_fapl and the file access flag set by H5Pset_elink_acc_flags are applied, so changes made by this callback function will take precedence.

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.

Note:

A file close degree property setting (H5Pset_fclose_degree) in this callback function or an associated property list will be ignored. A file opened by means of traversing an external link is always opened with the weak file close degree property setting, H5F_CLOSE_WEAK.

Parameters:

hid_t `lapl_id`		IN: Link access property list identifier.
H5L_elink_traverse_t `func`		IN: User-defined external link traversal 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.

Failure Modes:

H5Pset_elink_cb will fail if the link access property list identifier, lapl_id, is invalid or if the function pointer, func, is NULL.

An invalid function pointer, func, will cause a segmentation fault or other failure when an attempt is subsequently made to traverse an external link.

Example Usage:

This example defines a callback function that prints the name of the target file every time an external link is followed, and sets this callback function on lapl_id

herr_t elink_callback(const char *parent_file_name, const char
        *parent_group_name, const char *child_file_name, const char
        *child_object_name, unsigned *acc_flags, hid_t fapl_id, void *op_data) {
    puts(child_file_name);
    return 0;
}

int main(void) {
    hid_t lapl_id = H5Pcreate(H5P_LINK_ACCESS);
    H5Pset_elink_cb(lapl_id, elink_callback, NULL);
    ...
}

See Also:

H5Pget_elink_cb

H5Pset_elink_fapl, H5Pset_elink_acc_flags, H5Lcreate_external

H5Fopen for discussion of H5F_ACC_RDWR and H5F_ACC_RDONLY file access flags

H5L_elink_traverse_t

History:

Release	Change
1.8.3	C function introduced in this release.

Last modified: 18 June 2013

Name: H5Pset_elink_fapl

Signature:

herr_t H5Pset_elink_fapl( hid_t lapl_id, hid_t fapl_id )

Purpose:

Sets a file access property list for use in accessing a file pointed to by an external link.

Description:

H5Pset_elink_fapl sets the file access property list, fapl_id, to be used when accessing the target file of an external link associated with lapl_id.

Note:

A file close degree property setting (H5Pset_fclose_degree) in this property list will be ignored. A file opened by means of traversing an external link is always opened with the weak file close degree property setting, H5F_CLOSE_WEAK.

Parameters:

hid_t `lapl_id`	IN: Link access property list identifier
hid_t `fapl_id`	IN: File access property list identifier

Returns:

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

See Also:

H5Pget_elink_fapl
H5Lcreate_external

Fortran90 Interface:

None.

History:

Release	Change
1.9.0	C function introduced in this release.

Last modified: 11 May 2011

Name: H5Pset_elink_file_cache_size

Signature:

herr_t H5Pset_elink_file_cache_size( hid_t fapl_id, unsigned efc_size )

Purpose:

Sets the number of files that can be held open in an external link open file cache.

Motivation:

The external link open file cache holds files open after they have been accessed via an external link. This cache reduces the number of times such files are opened when external links are accessed repeatedly and can siginificantly improves performance in certain heavy-use situations and when low-level file opens or closes are expensive.

H5Pset_elink_file_cache_size sets the number of files that will be held open in an external link open file cache; H5Pget_elink_file_cache_size retrieves the size of an existing cache; and H5Fclear_elink_file_cache clears an existing cache without closing it.

Description:

H5Pset_elink_file_cache_size specifies the number of files that will be held open in an external link open file cache.

The default external link open file cache size is 0 (zero), meaning that files accessed via an external link are not held open. Setting the cache size to a positive integer turns on the cache; setting the size back to zero turns it off.

With this property set, files are placed in the external link open file cache cache when they are opened via an external link. Files are then held open until either they are evicted from the cache or the parent file is closed. This property setting can improve performance when external links are repeatedly accessed.

When the cache is full, files will be evicted using a least recently used (LRU) scheme; the file which has gone the longest time without being accessed through the parent file will be evicted and closed if nothing else is holding that file open.

Files opened through external links inherit the parent file’s file access property list by default, and therefore inherit the parent file’s external link open file cache setting.

When child files contain external links of their own, the caches can form a graph of cached external files. Closing the last external reference to such a graph will recursively close all files in the graph, even if cycles are present.

Parameters:

hid_t `fapl_id`		IN: File access property list identifier
unsigned `efc_size`		IN: External link open file cache size in number of files. Default setting is `0` (zero).

Returns:

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

Example Usage:

The following code sets up an external link open file cache that will hold open up to 8 files reached through external links:

    status = H5Pset_elink_file_cache_size(fapl_id, 8);

See Also:

H5Pget_elink_file_cache_size
H5Fclear_elink_file_cache

H5Lcreate_external
H5Pset_elink_fapl

History:

Release	Change
1.8.7	C function introduced in this release.

Name: H5Pset_elink_prefix

Signature:

herr_t H5Pset_elink_prefix( hid_t lapl_id, const char *prefix )

Purpose:

Sets prefix to be applied to external link paths.

Description:

H5Pset_elink_prefix sets the prefix to be applied to the path of any external links traversed. The prefix is prepended to the filename stored in the external link.

The prefix is specified in the user-allocated buffer prefix and set in the link access property list lapl_id. The buffer should not be freed until the property list has been closed.

Parameters:

hid_t `lapl_id`	IN: Link access property list identifier
const char *`prefix`	IN: Prefix to be applied to external link paths

Returns:

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

Fortran90 Interface:

None.

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Pset_est_link_info

Signature:

herr_t H5Pset_est_link_info( hid_t gcpl_id, unsigned est_num_entries, unsigned est_name_len )

Purpose:

Sets estimated number of links and length of link names in a group.

Description:

H5Pset_est_link_info inserts two settings into the group creation property list gcpl_id: the estimated number of links that are expected to be inserted into a group created with the property list and the estimated average length of those link names.

The estimated number of links is passed in est_num_entries.

The estimated average length of the anticipated link names is passed in est_name_len.

If a group is expected to have many links and to be stored in dense format, set est_num_entries to 0 (zero) for maximum efficiency. This will prevent the group from being created in the compact format.

See “Group implementations in HDF5” in the H5G API introduction for a discussion of the available types of HDF5 group structures.

Parameters:

hid_t `gcpl_id`	IN: Group creation property list identifier
unsigned `est_num_entries`	IN: Estimated number of links to be inserted into group
unsigned `est_name_len`	IN: Estimated average length of link names

Returns:

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

Fortran90 Interface: h5pset_est_link_info_f

SUBROUTINE h5pset_est_link_info_f(gcpl_id, est_num_entries, est_name_len, &
                                  hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: gcpl_id 
                                    ! Group creation property list identifier
  INTEGER, INTENT(IN) :: est_num_entries 
                                    ! Estimated number of links to be  
                                    ! inserted into group
  INTEGER, INTENT(IN) :: est_name_len    
                                    ! Estimated average length of link names
  INTEGER, INTENT(OUT) :: hdferr    ! Error code
                                    ! 0 on success and -1 on failure
END SUBROUTINE H5Pset_est_link_info_f

History:

Release	C
1.8.0	Function introduced in this release.

Last modified: 22 April 2011

Name: H5Pset_external

Signature:

herr_t H5Pset_external(hid_t plist, const char *name, off_t offset, hsize_t size )

Purpose:

Adds an external file to the list of external files.

Description:

The first call to H5Pset_external sets the external storage property in the property list, thus designating that the dataset will be stored in one or more non-HDF5 file(s) external to the HDF5 file. This call also adds the file name as the first file in the list of external files. Subsequent calls to the function add the named file as the next file in the list.

If a dataset is split across multiple files, then the files should be defined in order. The total size of the dataset is the sum of the size arguments for all the external files. If the total size is larger than the size of a dataset then the dataset can be extended (provided the data space also allows the extending).

The size argument specifies the number of bytes reserved for data in the external file. If size is set to H5F_UNLIMITED, the external file can be of unlimited size and no more files can be added to the external files list. If size is set to 0 (zero), no external file will actually be created.

All of the external files for a given dataset must be specified with H5Pset_external before H5Dcreate is called to create the dataset. If one these files does not exist on the system when H5Dwrite is called to write data to it, the library will create the file.

Parameters:

hid_t `plist`	IN: Identifier of a dataset creation property list.
const char `*name`	IN: Name of an external file.
off_t `offset`	IN: Offset, in bytes, from the beginning of the file to the location in the file where the data starts.
hsize_t `size`	IN: Number of bytes reserved in the file for the data.

Returns:

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

Fortran90 Interface: h5pset_external_f

SUBROUTINE h5pset_external_f(prp_id, name, offset,bytes, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id  ! Property list identifier
  CHARACTER(LEN=*), INTENT(IN) :: name  ! Name of an external file
  INTEGER, INTENT(IN) :: offset         ! Offset, in bytes, from the 
                                        ! beginning of the file to the 
                                        ! location in the file where 
                                        ! the data starts
  INTEGER(HSIZE_T), INTENT(IN) :: bytes ! Number of bytes reserved in 
                                        ! the file for the data
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pset_external_f

Last modified: 2016

Name: H5Pset_evict_on_close

Signature:


     herr_t H5Pset_evict_on_close(
       hid_t fapl_id, 
       hbool_t evict_on_close)

Purpose:

Controls the library's behavior of evicting metadata associated with a closed object

Description:

The library's metadata cache is fairly conservative about holding on to HDF5 object metadata (object headers, chunk index structures, etc.), which can cause the cache size to grow, resulting in memory pressure on an application or system. When enabled, the "evict on close" property will cause all metadata for an object to be evicted from the cache as long as metadata is not referenced by any other open object.

This function only applies to file access property lists.

The default library behavior is to not evict on object or file close.

When applied to a file access property list, any subsequently opened object will inherit the "evict on close" property and will have its metadata evicted when the object is closed.

Limitations:

H5Pset_evict_on_close cannot be used in parallel applications.

Parameters:

`hid_t fapl_id`		IN: File access property list
`hbool_t evict_on_close`		IN: Whether the HDF5 object should be evicted on close.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran Interface:

None

History:

Release	Change
1.10.1	C function introduced with this release.

Name: H5Pset_family_offset

Signature:

herr_t H5Pset_family_offset ( hid_t fapl_id, hsize_t offset )

Purpose:

Sets offset property for low-level access to a file in a family of files.

Description:

H5Pset_family_offset sets the offset property in the file access property list fapl_id so that the user application can retrieve a file handle for low-level access to a particular member of a family of files. The file handle is retrieved with a separate call to H5Fget_vfd_handle (or, in special circumstances, to H5FDget_vfd_handle; see Virtual File Layer and List of VFL Functions in HDF5 Technical Notes).

The value of offset is an offset in bytes from the beginning of the HDF5 file, identifying a user-determined location within the HDF5 file. The file handle the user application is seeking is for the specific member-file in the associated family of files to which this offset is mapped.

Use of this function is only appropriate for an HDF5 file written as a family of files with the FAMILY file driver.

Parameters:

hid_t fapl_id IN: File access property list identifier.

hsize_t offset IN: Offset in bytes within the HDF5 file.

Returns:

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

Fortran90 Interface: h5pset_family_offset_f

SUBROUTINE h5pset_family_offset_f(prp_id, offset, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN)   :: prp_id   ! Property list identifier
  INTEGER(HSIZE_T), INTENT(IN) :: offset   ! Offset in bytes
  INTEGER, INTENT(OUT)         :: hdferr   ! Error code
                                           ! 0 on success and -1 on failure
 
END SUBROUTINE h5pset_family_offset_f

History:

Release C

1.6.0 Function introduced in this release.

Name: H5Pset_fapl_core

Signature:

herr_t H5Pset_fapl_core( hid_t fapl_id, size_t increment, hbool_t backing_store )

Purpose:

Modifies the file access property list to use the H5FD_CORE driver.

Description:

H5Pset_fapl_core modifies the file access property list to use the H5FD_CORE driver.

The H5FD_CORE driver enables an application to work with a file in memory, speeding reads and writes as no disk access is made. File contents are stored only in memory until the file is closed. The backing_store parameter determines whether file contents are ever written to disk.

increment specifies the increment by which allocated memory is to be increased each time more memory is required.

While using H5Fcreate to create a core file, if the backing_store is set to 1 (TRUE), the file contents are flushed to a file with the same name as this core file when the file is closed or access to the file is terminated in memory.

The application is allowed to open an existing file with H5FD_CORE driver. While using H5Fopen to open an existing file, if the backing_store is set to 1 and the flags for H5Fopen is set to H5F_ACC_RDWR, any change to the file contents are saved to the file when the file is closed. If backing_store is set to 0 and the flags for H5Fopen is set to H5F_ACC_RDWR, any change to the file contents will be lost when the file is closed. If the flags for H5Fopen is set to H5F_ACC_RDONLY, no change to the file is allowed either in memory or on file.

Note:

Currently this driver cannot create or open family or multi files.

Parameters:

hid_t fapl_id IN: File access property list identifier.

size_t increment IN: Size, in bytes, of memory increments.

hbool_t backing_store IN: Boolean flag indicating whether to write the file contents to disk when the file is closed.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran90 Interface: h5pset_fapl_core_f

SUBROUTINE h5pset_fapl_core_f(prp_id, increment, backing_store, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN)  :: prp_id    ! Property list identifier
  INTEGER(SIZE_T), INTENT(IN) :: increment ! File block size in bytes
  LOGICAL, INTENT(IN) :: backing_store     ! Flag to indicate that entire 
                                           ! file contents are flushed to 
                                           ! a file with the same name as 
                                           ! this core file
  INTEGER, INTENT(OUT) :: hdferr           ! Error code
                                           ! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_core_f

History:

Release C Fortran90

1.6.0 The backing_store parameter has changed from INTEGER to LOGICAL to better match the C API.

1.4.0 Function introduced in this release.

Name: H5Pset_fapl_direct

Signature:

herr_t H5Pset_fapl_direct( hid_t fapl_id, size_t alignment, size_t block_size, size_t cbuf_size )

Purpose:

Sets up use of the direct I/O driver.

Description:

H5Pset_fapl_direct sets the file access property list, fapl_id, to use the direct I/O driver, H5FD_DIRECT. With this driver, data is written to or read from the file synchronously without being cached by the system.

File systems usually require the data address in memory, the file address, and the size of the data to be aligned. The HDF5 Library’s direct I/O driver is able to handle unaligned data, though that will consume some additional memory resources and may slow performance. To get better performance, use the system function posix_memalign to align the data buffer in memory and the HDF5 function H5Pset_alignment to align the data in the file. Be aware, however, that aligned data I/O may cause the HDF5 file to be bigger than the actual data size would otherwise require because the alignment may leave some holes in the file.

alignment specifies the required alignment boundary in memory.

block_size specifies the file system block size. A value of 0 (zero) means to use HDF5 Library’s default value of 4KB.

cbuf_size specifies the copy buffer size.

Note:

On an SGI Altix Linux 2.6 system, the memory alignment must be a multiple of 512 bytes, and the file system block size is 4KB. The maximum size for the copy buffer has to be a multiple of the file system block size. The HDF5 Library’s default maximum copy buffer size is 16MB. This copy buffer is used by the library’s internal algorithm to copy data in fragments between an application’s unaligned buffer and the file. The buffer’s size may affect I/O performance.

Parameters:

hid_t `fapl_id`	IN: File access property list identifier
size_t `alignment`	IN: Required memory alignment boundary
size_t `block_size`	IN: File system block size
size_t `cbuf_size`	IN: Copy buffer size

Returns:

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

Fortran90 Interface: h5pset_fapl_direct_f

SUBROUTINE h5pset_fapl_direct_f(fapl_id, alignment, block_size, cbuf_size, &
                                hdferr)
  IMPLICIT NONE  
  INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier
  INTEGER(SIZE_T), INTENT(IN) :: alignment    
                                        ! Required memory alignment boundary
  INTEGER(SIZE_T), INTENT(IN) :: block_size    
                                        ! File system block size

  INTEGER(SIZE_T), INTENT(IN) :: cbuf_size
                                        ! Copy buffer size
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE H5Pset_fapl_direct_f

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Pset_fapl_family

Signature:

herr_t H5Pset_fapl_family ( hid_t fapl_id, hsize_t memb_size, hid_t memb_fapl_id )

Purpose:

Sets the file access property list to use the family driver.

Description:

H5Pset_fapl_family sets the file access property list identifier, fapl_id, to use the family driver.

memb_size is the size in bytes of each file member. This size will be saved in file when the property list fapl_id is used to create a new file. If fapl_id is used to open an existing file, memb_size has to be equal to the original size saved in file. A failure with an error message indicating the correct member size will be returned if memb_size does not match the size saved. If any user does not know the original size, H5F_FAMILY_DEFAULT can be passed in. The library will retrieve the saved size.

memb_fapl_id is the identifier of the file access property list to be used for each family member.

Parameters:

hid_t fapl_id IN: File access property list identifier.

hsize_t memb_size IN: Size in bytes of each file member.

hid_t memb_fapl_id IN: Identifier of file access property list for each family member.

Returns:

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

Fortran90 Interface: h5pset_fapl_family_f

SUBROUTINE h5pset_fapl_family_f(prp_id, imemb_size, memb_plist, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN)   :: prp_id    ! Property list identifier
  INTEGER(HSIZE_T), INTENT(IN) :: memb_size ! Logical size, in bytes,
                                            ! of each family member
  INTEGER(HID_T), INTENT(IN) :: memb_plist  ! Identifier of the file 
                                            ! access property list to be
                                            ! used for each family member
  INTEGER, INTENT(OUT) :: hdferr            ! Error code
                                            ! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_family_f

History:

Release C

1.4.0 Function introduced in this release.

1.8.0 Behavior of the memb_size parameter was changed.

Last modified: 12 May 2011

Name: H5Pset_fapl_log

Signature:

herr_t H5Pset_fapl_log( hid_t fapl_id, const char *logfile, unsigned long long flags, size_t buf_size )

Purpose:

Sets up the logging virtual file driver (H5FD_LOG) for use.

Description:

H5Pset_fapl_log modifies the file access property list to use the logging driver, H5FD_LOG. The logging virtual file driver (VFD) is a clone of the standard SEC2 (H5FD_SEC2) driver with additional facilities for logging VFD metrics and activity to a file.

logfile is the name of the file in which the logging entries are to be recorded.

The actions to be logged are specified in the parameter flags using the pre-defined constants described in the following table. Multiple flags can be set through the use of a logical OR contained in parentheses. For example, logging read and write locations would be specified as (H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE).

Table 1: Logging flags
Flag	Description
`H5FD_LOG_LOC_READ`	Track the location and length of every read, write, or seek operation.
`H5FD_LOG_LOC_WRITE`
`H5FD_LOG_LOC_SEEK`
`H5FD_LOG_LOC_IO`	Track all I/O locations and lengths. The logical equivalent of the following:
	`(H5FD_LOG_LOC_READ \| H5FD_LOG_LOC_WRITE \| H5FD_LOG_LOC_SEEK)`
`H5FD_LOG_FILE_READ`	Track the number of times each byte is read or written.
`H5FD_LOG_FILE_WRITE`	Track the number of times each byte is read or written.
`H5FD_LOG_FILE_IO`	Track the number of times each byte is read and written. The logical equivalent of the following:
	`(H5FD_LOG_FILE_READ \| H5FD_LOG_FILE_WRITE)`
`H5FD_LOG_FLAVOR`	Track the type, or flavor, of information stored at each byte.
`H5FD_LOG_NUM_READ`	Track the total number of read, write, seek, or truncate operations that occur.
`H5FD_LOG_NUM_WRITE`
`H5FD_LOG_NUM_SEEK`
`H5FD_LOG_NUM_TRUNCATE`
`H5FD_LOG_NUM_IO`	Track the total number of all types of I/O operations. The logical equivalent of the following:
	`(H5FD_LOG_NUM_READ \| H5FD_LOG_NUM_WRITE \| H5FD_LOG_NUM_SEEK \| H5FD_LOG_NUM_TRUNCATE)`
`H5FD_LOG_TIME_OPEN`	Track the time spent in open, stat, read, write, seek, or close operations.
`H5FD_LOG_TIME_STAT`
`H5FD_LOG_TIME_READ`
`H5FD_LOG_TIME_WRITE`
`H5FD_LOG_TIME_SEEK`
`H5FD_LOG_TIME_CLOSE`
`H5FD_LOG_TIME_IO`	Track the time spent in each of the above operations. The logical equivalent of the following:
	`(H5FD_LOG_TIME_OPEN \| H5FD_LOG_TIME_STAT \| H5FD_LOG_TIME_READ \| H5FD_LOG_TIME_WRITE \| H5FD_LOG_TIME_SEEK \| H5FD_LOG_TIME_CLOSE)`
`H5FD_LOG_ALLOC`	Track the allocation of space in the file.
`H5FD_LOG_ALL`	Track everything. The logical equivalent of the following:
	`(H5FD_LOG_ALLOC \| H5FD_LOG_TIME_IO \| H5FD_LOG_NUM_IO \| H5FD_LOG_FLAVOR \| H5FD_LOG_FILE_IO \| H5FD_LOG_LOC_IO)`

The logging driver can track the number of times each byte in the file is read from or written to (using H5FD_LOG_FILE_READ and H5FD_LOG_FILE_WRITE) and what kind of data is at that location (e.g., metadata, raw data; using H5FD_LOG_FLAVOR). This information is tracked in internal buffers of size buf_size, which must be at least the maximum size in bytes of the file to be logged while the log driver is in use.

One buffer of size buf_size will be created for each of H5FD_LOG_FILE_READ, H5FD_LOG_FILE_WRITE and H5FD_LOG_FLAVOR when those flags are set; these buffers will not grow as the file increases in size.

Parameters:

hid_t `fapl_id`	IN: File access property list identifier.
char *`logfile`	IN: Name of the log file.
unsigned long long `flags`	IN: Flags specifying the types of logging activity.
size_t `buf_size`	IN: The size of the logging buffers, in bytes (see description).

Output:

This section describes the logging driver (LOG VFD) output.

The table, immediately below, describes output of the various logging driver flags and function calls; error output is in red italic. A list of valid flavor values, describing the type of data stored, follows the table.

Table 2: Logging output
Flag (H5FD_LOG_)	VFD Call	Output and Comments
`LOC_READ`	`Read()`	`%10a-%10a (%10Zu bytes) (%s) Read` Start position End position Number of bytes Flavor of read Adds `(%f s)` and seek time if `TIME_SEEK` is also set.
`LOC_READ`	`Read() Error`	`Error! Reading: %10a-%10a (%10Zu bytes)` Same parameters as non-error entry.
`LOC_WRITE`	`Write()`	`%10a-%10a (%10Zu bytes) (%s) Written` Start position End position Number of bytes Flavor of write Adds `(%f s)` and seek time if `TIME_SEEK` is also set.
`LOC_WRITE`	`Write() Error`	`Error! Writing: %10a-%10a (%10Zu bytes)` Same parameters as non-error entry.
`LOC_SEEK`	`Read() Write()`	`Seek: From %10a-%10a` Start position End position Adds `(%f s)` and seek time if `TIME_SEEK` is also set.
`FILE_READ`	`Close()`	Begins with: `Dumping read I/O information` Then, for each range of identical values, there is this line: `\tAddr %10-%10 (%10lu bytes) read from %3d times` Start address End address Number of bytes Number of times read Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
`FILE_WRITE`	`Close()`	Begins with: `Dumping write I/O information` Then, for each range of identical values, there is this line: `\tAddr %10-%10 (%10lu bytes) written to %3d times` Start address End address Number of bytes Number of times written Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
`FLAVOR`	`Close()`	Begins with: `Dumping I/O flavor information` Then, for each range of identical values, there is this line: `\tAddr %10-%10 (%10lu bytes) flavor is %s` Start address End address Number of bytes Flavor Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
`NUM_READ`	`Close()`	`Total number of read operations: %11u`
`NUM_WRITE`	`Close()`	`Total number of write operations: %11u`
`NUM_SEEK`	`Close()`	`Total number of seek operations: %11u`
`NUM_TRUNCATE`	`Close()`	`Total number of truncate operations: %11u`
`TIME_OPEN`	`Open()`	`Open took: (%f s)`
`TIME_READ`	`Close() Read()`	`Total time in read operations: %f s` See also: `LOC_READ`
`TIME_WRITE`	`Close() Write()`	`Total time in write operations: %f s` See also: `LOC_WRITE`
`TIME_SEEK`	`Close() Read() Write()`	`Total time in seek operations: %f s` See also: `LOC_SEEK` or `LOC_WRITE`
`TIME_CLOSE`	`Close()`	`Close took: (%f s)`
`TIME_STAT`	`Open()`	`Stat took: (%f s)`
`ALLOC`	`Alloc()`	`%10-%10 (%10Hu bytes) (%s) Allocated` Start of address space End of address space Total size of allocation Flavor of allocation

Flavors:
The flavor describes the type of stored information. The following table lists the flavors that appear in log output and briefly describes each. These terms are provided here to aid in the construction of log message parsers; a full description is beyond the scope of this document.

Table 3: Flavors of logged data
Flavor	Description
`H5FD_MEM_NOLIST`	Error value
`H5FD_MEM_DEFAULT`	Value not yet set. May also be a datatype set in a larger allocation that will be suballocated by the library.
`H5FD_MEM_SUPER`	Superblock data
`H5FD_MEM_BTREE`	B-tree data
`H5FD_MEM_DRAW`	Raw data (for example, contents of a dataset)
`H5FD_MEM_GHEAP`	Global heap data
`H5FD_MEM_LHEAP`	Local heap data
`H5FD_MEM_OHDR`	Object header data

Returns:

Returns non-negative if successful. Otherwise returns negative.

Fortran90 Interface:

None.

History:

Release C

1.8.7 The flags parameter has been changed from unsigned int to unsigned long long.
The implementation of the H5FD_LOG_TIME_OPEN, H5FD_LOG_TIME_READ, H5FD_LOG_TIME_WRITE, and H5FD_LOG_TIME_SEEK flags has been finished.
New flags were added: H5FD_LOG_NUM_TRUNCATE and H5FD_LOG_TIME_STAT.

1.6.0 The verbosity parameter has been removed.
Two new parameters have been added: flags of type unsigned and buf_size of type size_t.

1.4.0 Function introduced in this release.

Last modified: 15 May 2009

Name: H5Pset_fapl_mpio

Signature:

herr_t H5Pset_fapl_mpio( hid_t fapl_id, MPI_Comm comm, MPI_Info info )

Purpose:

Stores MPI IO communicator information to the file access property list.

Description:

H5Pset_fapl_mpio stores the user-supplied MPI IO parameters comm, for communicator, and info, for information, in the file access property list fapl_id. That property list can then be used to create and/or open a file.

H5Pset_fapl_mpio is available only in the parallel HDF5 library and is not a collective function.

comm is the MPI communicator to be used for file open, as defined in MPI_FILE_OPEN of MPI-2. This function makes a duplicate of the communicator, so modifications to comm after this function call returns have no effect on the file access property list.

info is the MPI Info object to be used for file open, as defined in MPI_FILE_OPEN of MPI-2. This function makes a duplicate copy of the Info object, so modifications to the Info object after this function call returns will have no effect on the file access property list.

If the file access property list already contains previously-set communicator and Info values, those values will be replaced and the old communicator and Info object will be freed.

Note:

Raw dataset chunk caching is not currently supported when using this file driver in read/write mode. All calls to H5Dread and H5Dwrite will access the disk directly, and H5Pset_cache and H5Pset_chunk_cache will have no effect on performance.

Raw dataset chunk caching is supported when this driver is used in read-only mode.

Parameters:

hid_t `fapl_id`	IN: File access property list identifier
MPI_Comm `comm`	IN: MPI-2 communicator
MPI_Info `info`	IN: MPI-2 info object

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran90 Interface: h5pset_fapl_mpio_f

SUBROUTINE h5pset_fapl_mpio_f(prp_id, comm, info, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id  ! Property list identifier
  INTEGER, INTENT(IN) :: comm           ! MPI communicator to be used for 
                                        ! file open as defined in 
                                        ! MPI_FILE_OPEN of MPI-2
  INTEGER, INTENT(IN) :: info           ! MPI info object to be used for 
                                        ! file open as defined in 
                                        ! MPI_FILE_OPEN of MPI-2
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_mpio_f

History:

Release Change

1.4.5 Handling of the MPI Communicator and Info object changed at this release. A duplicate of each of these is now stored in the property list instead of pointers to each.

1.4.0 C function introduced in this release.

Last modified: 2 May 2013

Name: H5Pset_fapl_mpiposix

Signature:

herr_t H5Pset_fapl_mpiposix( hid_t fapl_id, MPI_Comm comm, hbool_t use_gpfs_hints )

Purpose:

Stores MPI IO communicator information to a file access property list.

Function Removed:

The C functions H5Pset_fapl_mpiposix and H5Pget_fapl_mpiposix and the corresponding Fortran subroutines have been removed from the HDF5 Library at Release 1.8.13. They remain available in earlier releases, through HDF5 Release 1.8.12.

All applications used with HDF5 Release 1.8.13 or later and that use MPI I/O should use the functions H5Pset_fapl_mpio and H5Pget_fapl_mpio or the corresponding Fortran subroutines.

Description:

H5Pset_fapl_mpiposix stores the user-supplied MPI IO parameter comm, for communicator, in the file access property list fapl_id. That property list can then be used to create and/or open the file.

H5Pset_fapl_mpiposix is available only in the parallel HDF5 library and is not a collective function.

comm is the MPI communicator to be used for file open, as defined in MPI_FILE_OPEN of MPI-2. This function does not create a duplicated communicator. Modifications to comm after this function call returns may have an undetermined effect on the file access property list. Users should not modify the communicator while it is defined in a property list.

use_gpfs_hints specifies whether to attempt to use GPFS hints when accessing this file. A value of TRUE (or 1) indicates that the hints should be used, if possible. A value of FALSE (or 0) indicates that the hints should not be used.

Available GPFS hints are known to the HFD5 Library and are not user configurable. They may be used only with GPFS file systems and may improve file access for some applications; the user of a GPFS system is encouraged to experiment by running an application with and without this parameter set.

Note:

Raw dataset chunk caching is supported when this driver is used in read-only mode.

Parameters:

hid_t `fapl_id`	IN: File access property list identifier.
MPI_Comm `comm`	IN: MPI-2 communicator.
hbool_t `use_gpfs_hints`	IN: Use of GPFS hints.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran90 Interface: h5pset_fapl_mpiposix_f

SUBROUTINE h5pset_fapl_mpiposix_f(prp_id, comm, use_gpfs, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id  ! Property list identifier
  INTEGER, INTENT(IN) :: comm           ! MPI communicator to be used 
                                        ! for file open as defined in 
                                        ! MPI_FILE_OPEN of MPI-2
  LOGICAL, INTENT(IN) :: use_gpfs
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
END SUBROUTINE h5pset_fapl_mpiposix_f

History:

Release Change
1.8.13 C function and Fortran subroutine removed from HDF5 at this release.

1.6.1 Fortran subroutine introduced in this release.

1.6.0 use_gpfs_hints parameter added.

1.6.0 C function introduced in this release.

Last modified: 14 October 2014

Name: H5Pset_fapl_multi

Signature:

herr_t H5Pset_fapl_multi( hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl, const char * const *memb_name, const haddr_t *memb_addr, hbool_t relax )

Purpose:

Sets up use of the multi-file driver.

Description:

H5Pset_fapl_multi sets the file access property list fapl_id to use the multi-file driver.

The multi-file driver enables different types of HDF5 data and metadata to be written to separate files. These files are viewed by the HDF5 library and the application as a single virtual HDF5 file with a single HDF5 file address space. The types of data that can be broken out into separate files include raw data, the superblock, B-tree data, global heap data, local heap data, and object headers. At the programmer's discretion, two or more types of data can be written to the same file while other types of data are written to separate files.

The array memb_map maps memory usage types to other memory usage types and is the mechanism that allows the caller to specify how many files are created. The array contains H5FD_MEM_NTYPES entries, which are either the value H5FD_MEM_DEFAULT or a memory usage type. The number of unique values determines the number of files that are opened.

The array memb_fapl contains a property list for each memory usage type that will be associated with a file.

The array memb_name should be a name generator (a printf-style format with a %s which will be replaced with the name passed to H5FDopen, usually from H5Fcreate or H5Fopen).

The array memb_addr specifies the offsets within the virtual address space, from 0 (zero) to HADDR_MAX, at which each type of data storage begins.

If relax is set to TRUE (or 1), then opening an existing file for read-only access will not fail if some file members are missing. This allows a file to be accessed in a limited sense if just the meta data is available.

Default values for each of the optional arguments are as follows:

memb_map

The default member map contains the value H5FD_MEM_DEFAULT for each element.

memb_fapl

The default value is H5P_DEFAULT for each element.

memb_name

The default string is %s-X.h5 where X is one of the following letters: s    for H5FD_MEM_SUPER
b    for H5FD_MEM_BTREE
r    for H5FD_MEM_DRAW
g    for H5FD_MEM_GHEAP
l    for H5FD_MEM_LHEAP
o    for H5FD_MEM_OHDR

memb_addr

The default setting is that the address space is equally divided among all of the elements:

H5FD_MEM_SUPER -> 0 * (HADDR_MAX/6)
H5FD_MEM_BTREE -> 1 * (HADDR_MAX/6)
H5FD_MEM_DRAW -> 2 * (HADDR_MAX/6)
H5FD_MEM_GHEAP -> 3 * (HADDR_MAX/6)
H5FD_MEM_LHEAP -> 4 * (HADDR_MAX/6)
H5FD_MEM_OHDR -> 5 * (HADDR_MAX/6)

Parameters:

hid_t fapl_id IN: File access property list identifier.

const H5FD_mem_t *memb_map IN: Maps memory usage types to other memory usage types.

const hid_t *memb_fapl IN: Property list for each memory usage type.

const char * const *memb_name IN: Name generator for names of member files.

const haddr_t *memb_addr IN: The offsets within the virtual address space, from 0 (zero) to HADDR_MAX, at which each type of data storage begins.

hbool_t relax IN: Allows read-only access to incomplete file sets when TRUE.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Example:

The following code sample sets up a multi-file access property list that partitions data into meta and raw files, each being one-half of the address:

                  H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES];
                  hid_t memb_fapl[H5FD_MEM_NTYPES];
                  const char *memb[H5FD_MEM_NTYPES];
                  haddr_t memb_addr[H5FD_MEM_NTYPES];
 
                  // The mapping...
                  for (mt=0; mt<H5FD_MEM_NTYPES; mt++) {
                     memb_map[mt] = H5FD_MEM_SUPER;
                  }
                  memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW;
 
                  // Member information
                  memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT;
                  memb_name[H5FD_MEM_SUPER] = "%s.meta";
                  memb_addr[H5FD_MEM_SUPER] = 0;
 
                  memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT;
                  memb_name[H5FD_MEM_DRAW] = "%s.raw";
                  memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2;
 
                  hid_t fapl = H5Pcreate(H5P_FILE_ACCESS);
                  H5Pset_fapl_multi(fapl, memb_map, memb_fapl,
                                  memb_name, memb_addr, TRUE);

Fortran90 Interface: h5pset_fapl_multi_f

SUBROUTINE h5pset_fapl_multi_f(prp_id, memb_map, memb_fapl, memb_name,
                               memb_addr, relax, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T),INTENT(IN)  :: prp_id     ! Property list identifier

  INTEGER,DIMENSION(H5FD_MEM_NTYPES_F),INTENT(IN)          :: memb_map
  INTEGER(HID_T),DIMENSION(H5FD_MEM_NTYPES_F),INTENT(IN)   :: memb_fapl
  CHARACTER(LEN=*),DIMENSION(H5FD_MEM_NTYPES_F),INTENT(IN) :: memb_name
  REAL, DIMENSION(H5FD_MEM_NTYPES_F), INTENT(IN)           :: memb_addr
              ! Numbers in the interval [0,1) (e.g. 0.0 0.1 0.5 0.2 0.3 0.4)
              ! real address in the file will be calculated as X*HADDR_MAX

  LOGICAL, INTENT(IN)  :: relax
  INTEGER, INTENT(OUT) :: hdferr           ! Error code
                                           ! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_multi_f

History:

Release C

1.6.3 memb_name parameter type changed to const char* const*.

1.4.0 Function introduced in this release.

Name: H5Pset_fapl_sec2

Signature:

herr_t H5Pset_fapl_sec2( hid_t fapl_id )

Purpose:

Sets the sec2 driver.

Description:

H5Pset_fapl_sec2 modifies the file access property list to use the H5FD_SEC2 driver.

Parameters:

hid_t fapl_id IN: File access property list identifier.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran90 Interface: h5pset_fapl_sec2_f

SUBROUTINE h5pset_fapl_sec2_f(prp_id, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN)    :: prp_id  ! Property list identifier
  INTEGER, INTENT(OUT)          :: hdferr  ! Error code
                                           ! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_sec2_f

History:

Release C

1.4.0 Function introduced in this release.

Name: H5Pset_fapl_split

Signature:

herr_t H5Pset_fapl_split( hid_t fapl_id, const char *meta_ext, hid_t meta_plist_id, const char *raw_ext, hid_t raw_plist_id )

Purpose:

Emulates the old split file driver.

Description:

H5Pset_fapl_split is a compatibility function that enables the multi-file driver to emulate the split driver from HDF5 Releases 1.0 and 1.2. The split file driver stored metadata and raw data in separate files but provided no mechanism for separating types of metadata.

fapl_id is a file access property list identifier.

meta_ext is the filename extension for the metadata file. The extension is appended to the name passed to H5FDopen, usually from H5Fcreate or H5Fopen, to form the name of the metadata file. If the string %s is used in the extension, it works like the name generator as in H5Pset_fapl_multi.

meta_plist_id is the file access property list identifier for the metadata file.

raw_ext is the filename extension for the raw data file. The extension is appended to the name passed to H5FDopen, usually from H5Fcreate or H5Fopen, to form the name of the rawdata file. If the string %s is used in the extension, it works like the name generator as in H5Pset_fapl_multi.

raw_plist_id is the file access property list identifier for the raw data file.

If a user wishes to check to see whether this driver is in use, the user must call H5Pget_driver and compare the returned value to the string H5FD_MULTI. A positive match will confirm that the multi driver is in use; HDF5 provides no mechanism to determine whether it was called as the special case invoked by H5Pset_fapl_split.

Parameters:

hid_t fapl_id, IN: File access property list identifier.

const char *meta_ext, IN: Metadata filename extension.

hid_t meta_plist_id, IN: File access property list identifier for the metadata file.

const char *raw_ext, IN: Raw data filename extension.

hid_t raw_plist_id IN: File access property list identifier for the raw data file.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Example:

/* Example 1: Both metadata and rawdata files are in the same  */
/*    directory.   Use Station1-m.h5 and Station1-r.h5 as      */
/*    the metadata and rawdata files.                          */
hid_t fapl, fid;
fapl = H5Pcreate(H5P_FILE_ACCESS);
H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "-r.h5", H5P_DEFAULT);
fid=H5Fcreate("Station1",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);

/* Example 2: metadata and rawdata files are in different      */
/*    directories.  Use PointA-m.h5 and /pfs/PointA-r.h5 as    */
/*    the metadata and rawdata files.                          */
hid_t fapl, fid;
fapl = H5Pcreate(H5P_FILE_ACCESS);
H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT);
fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);

Fortran90 Interface: h5pset_fapl_split_f

SUBROUTINE h5pset_fapl_split_f(prp_id, meta_ext, meta_plist, raw_ext, &
                               raw_plist, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T),INTENT(IN)   :: prp_id     ! Property list identifier
  CHARACTER(LEN=*),INTENT(IN) :: meta_ext   ! Name of the extension for
                                            ! the metafile filename
  INTEGER(HID_T),INTENT(IN)   :: meta_plist ! Identifier of the meta file
                                            ! access property list
  CHARACTER(LEN=*),INTENT(IN) :: raw_ext    ! Name extension for the raw 
                                            ! file filename
  INTEGER(HID_T),INTENT(IN)   :: raw_plist  ! Identifier of the raw file
                                            ! access property list
  INTEGER, INTENT(OUT) :: hdferr            ! Error code
                                            ! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_split_f

History:

Release C

1.4.0 Function introduced in this release.

Name: H5Pset_fapl_stdio

Signature:

herr_t H5Pset_fapl_stdio( hid_t fapl_id )

Purpose:

Sets the standard I/O driver.

Description:

H5Pset_fapl_stdio modifies the file access property list to use the standard I/O driver, H5FD_STDIO.

Parameters:

hid_t fapl_id IN: File access property list identifier.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran90 Interface: h5pset_fapl_stdio_f

SUBROUTINE h5pset_fapl_stdio_f(prp_id, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN)    :: prp_id  ! Property list identifier
  INTEGER, INTENT(OUT)          :: hdferr  ! Error code
                                           ! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_stdio_f

History:

Release C

1.4.0 Function introduced in this release.

Name: H5Pset_fapl_windows

Signature:

herr_t H5Pset_fapl_windows( hid_t fapl_id )

Purpose:

Sets the Windows I/O driver.

Description:

H5Pset_fapl_windows sets the default HDF5 Windows I/O driver on Windows systems.

Since the HDF5 Library uses this driver, H5FD_WINDOWS, by default on Windows systems, it is not normally necessary for a user application to call H5Pset_fapl_windows. While it is not recommended, there may be times when a user chooses to set a different HDF5 driver, such as the standard I/O driver (H5FD_STDIO) or the sec2 driver (H5FD_SEC2), in a Windows application. H5Pset_fapl_windows is provided so that the application can return to the Windows I/O driver when the time comes.

Only the Windows driver is tested on Windows systems; other drivers are used at the application’s and the user’s risk.

Furthermore, the Windows driver is tested and available only on Windows systems; it is not available on non-Windows systems.

Parameters:

hid_t fapl_id IN: File access property list identifier

Returns:

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

Fortran90 Interface:

None.

History:

Release	C
1.8.0	Function introduced in this release.

Last modified: 18 June 2013

Name: H5Pset_fclose_degree

Signature:

herr_t H5Pset_fclose_degree( hid_t fapl_id, H5F_close_degree_t fc_degree )

Purpose:

Sets the file close degree.

Description:

H5Pset_fclose_degree sets the file close degree property fc_degree in the file access property list fapl_id.

Degree name	`H5Fclose` behavior with no open object in file	`H5Fclose` behavior with open object(s) in file
`H5F_CLOSE_WEAK`	Actual file is closed.	Access to file identifier is terminated; actual file close is delayed until all objects in file are closed
`H5F_CLOSE_SEMI`	Actual file is closed.	Function returns FAILURE
`H5F_CLOSE_STRONG`	Actual file is closed.	All open objects remaining in the file are closed then file is closed
`H5F_CLOSE_DEFAULT`	The VFL driver chooses the behavior. Currently, all VFL drivers set this value to `H5F_CLOSE_WEAK`, except for the MPI-I/O driver, which sets it to `H5F_CLOSE_SEMI`.

Note that if a file is opened multiple times without being closed, each open operation must use the same file close degree setting. For example, if a file is already open with H5F_CLOSE_WEAK, an H5Fopen call with H5F_CLOSE_STRONG will fail.

Parameters:

hid_t `fapl_id`	IN: File access property list identifier.
H5F_close_degree_t `fc_degree`	IN: Pointer to a location containing the file close degree property, the value of `fc_degree`.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran90 Interface: h5pset_fclose_degree_f

SUBROUTINE h5pset_fclose_degree_f(fapl_id, degree, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: fapl_id  ! File access property list identifier
  INTEGER, INTENT(IN) :: degree          ! Info about file close behavior 
                                         ! Possible values:
                                         !    H5F_CLOSE_DEFAULT_F
                                         !    H5F_CLOSE_WEAK_F
                                         !    H5F_CLOSE_SEMI_F
                                         !    H5F_CLOSE_STRONG_F
  INTEGER, INTENT(OUT) :: hdferr         ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pset_fclose_degree_f

History:

Release	C
1.6.0	Function introduced in this release.

Last modified: 2 May 2014

Name: H5Pset_file_image

Signature:

herr_t H5Pset_file_image( hid_t fapl_id, void *buf_ptr, size_t buf_len )

Purpose:

Sets an initial file image in a memory buffer.

Motivation:

H5Pset_file_image and other elements of HDF5 are used to load an image of an HDF5 file into system memory and open that image as a regular HDF5 file. An application can then use the file without the overhead of disk I/O.

Recommended Reading:

This function is part of the file image operations feature set. It is highly recommended to study the guide “HDF5 File Image Operations” before using this feature set.

See the “See Also” section below for links to other elements of HDF5 file image operations.

Description:

H5Pset_file_image allows an application to provide a file image to be used as the initial contents of a file. Calling H5Pset_file_image makes a copy of the buffer specified in buf_ptr of size buf_len.

Parameters:

hid_t `fapl_id`		IN: File access property list identifier
void *`buf_ptr`		IN: Pointer to the initial file image, or `NULL` if no initial file image is desired
size_t `buf_len`		IN: Size of the supplied buffer, or `0` (zero) if no initial image is desired

Returns:

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

Fortran2003 Interface: h5pset_file_image_f

Signature:

  SUBROUTINE h5pset_file_image_f(fapl_id, buf_ptr, buf_len, hdferr)
    USE iso_c_binding
    IMPLICIT NONE
    INTEGER(HID_T) , INTENT(IN)  :: fapl_id
    TYPE(C_PTR)    , INTENT(IN)  :: buf_ptr
    INTEGER(SIZE_T), INTENT(IN)  :: buf_len
    INTEGER        , INTENT(OUT) :: hdferr

Inputs:

  fapl_id - File access property list identifier
  buf_ptr - Pointer to the initial file image, 
            or C_NULL_PTR if no initial file image is desired
  buf_len - Size of the supplied buffer, or 0 (zero) if no initial image is desired

Outputs:

  hdferr  - Returns 0 if successful and -1 if fails

See Also:

H5LTopen_file_image

H5Fget_file_image

H5Pget_file_image

H5Pset_file_image_callbacks
H5Pget_file_image_callbacks “HDF5 File Image Operations”
in Advanced Topics in HDF5

Within H5Pset_file_image_callbacks:
Callback struct H5_file_image_callbacks_t
Callback ENUM H5_file_image_op_t

History:

Release	Change
1.8.13	Fortran subroutine added in this release.
1.8.9	C function introduced in this release.

Last modified: 13 April 2012

Name: H5Pset_file_image_callbacks

Signature:

herr_t H5Pset_file_image_callbacks( hid_t fapl_id, H5_file_image_callbacks_t *callbacks_ptr )

Purpose:

Sets the callbacks for working with file images.

Motivation:

H5Pset_file_image_callbacks and other elements of HDF5 are used to load an image of an HDF5 file into system memory and open that image as a regular HDF5 file. An application can then use the file without the overhead of disk I/O.

Recommended Reading:

This function is part of the file image operations feature set. It is highly recommended to study the guide “HDF5 File Image Operations” before using this feature set.

See the “See Also” section below for links to other elements of HDF5 file image operations.

Description:

H5Pset_file_image_callbacks sets callback functions for working with file images in memory.

H5Pset_file_image_callbacks allows an application to control the management of file image buffers through user defined callbacks. These callbacks can be used in the management of file image buffers in property lists and with certain file drivers.

H5Pset_file_image_callbacks must be used before any file image has been set in the file access property list. Once a file image has been set, the function will fail.

The callback routines set up by H5Pset_file_image_callbacks are invoked when a new file image buffer is allocated, when an existing file image buffer is copied or resized, or when a file image buffer is released from use.

Some file drivers allow the use of user-defined callback functions for allocating, freeing, and copying the driver’s internal buffer, potentially allowing optimizations such as avoiding large malloc and memcpy operations, or to perform detailed logging.

From the perspective of the HDF5 Library, the operations of the image_malloc, image_memcpy, image_realloc, and image_free callbacks must be identical to those of the corresponding C standard library calls (malloc, memcpy, realloc, and free). While the operations must be identical, the file image callbacks have more parameters. The return values of image_malloc and image_realloc are identical to the return values of malloc and realloc. The return values of image_memcpy and image_free differ from the return values of memcpy and free in that the return values of image_memcpy and image_free can also indicate failure.

The callbacks and their parameters, along with a struct and an ENUM required for their use, are described below.

Callback struct and ENUM:
The callback functions set up by H5Pset_file_image_callbacks use a struct and an ENUM that are defined as follows

The struct H5_file_image_callbacks_t serves as a container for the callback functions and a pointer to user-supplied data. The struct is defined as follows:

    typedef struct
    {
        void *(*image_malloc)(size_t size, H5_file_image_op_t file_image_op,
                        void *udata);
        void *(*image_memcpy)(void *dest, const void *src, size_t size,
                        H5_file_image_op_t file_image_op, void *udata);
        void *(*image_realloc)(void *ptr, size_t size,
                        H5_file_image_op_t file_image_op, void *udata);
        herr_t (*image_free)(void *ptr, H5_file_image_op_t file_image_op,
                        void *udata);
        void *(*udata_copy)(void *udata); 
        herr_t (*udata_free)(void *udata); 
        void *udata;
    } H5_file_image_callbacks_t;

Elements of the ENUM H5_file_image_op_t are used by the callbacks to invoke certain operations on file images. The ENUM is defined as follows:

    typedef enum
    {
        H5_FILE_IMAGE_OP_PROPERTY_LIST_SET, 
        H5_FILE_IMAGE_OP_PROPERTY_LIST_COPY, 
        H5_FILE_IMAGE_OP_PROPERTY_LIST_GET, 
        H5_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE, 
        H5_FILE_IMAGE_OP_FILE_OPEN, 
        H5_FILE_IMAGE_OP_FILE_RESIZE, 
        H5_FILE_IMAGE_OP_FILE_CLOSE
    } H5_file_image_op_t;

The elements of the H5_file_image_op_t ENUM are used in the callbacks for the following purposes:

H5_FILE_IMAGE_OP_PROPERTY_LIST_SET

Passed to the image_malloc and image_memcpy callbacks when a file image buffer is to be copied while being set in a file access property list (FAPL).
H5_FILE_IMAGE_OP_PROPERTY_LIST_COPY

Passed to the image_malloc and image_memcpy callbacks when a file image buffer is to be copied when a FAPL is copied.
H5_FILE_IMAGE_OP_PROPERTY_LIST_GET

Passed to the image_malloc and image_memcpy callbacks when a file image buffer is to be copied while being retrieved from a FAPL.
H5_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE

Passed to the image_free callback when a file image buffer is to be released during a FAPL close operation.
H5_FILE_IMAGE_OP_FILE_OPEN

Passed to the image_malloc and image_memcpy callbacks when a file image buffer is to be copied during a file open operation. While the file image being opened will typically be copied from a FAPL, this need not always be the case. For example, the core file driver, also known as the memory file driver, takes its initial image from a file.
H5_FILE_IMAGE_OP_FILE_RESIZE

Passed to the image_realloc callback when a file driver needs to resize an image buffer.
H5_FILE_IMAGE_OP_FILE_CLOSE

Passed to the image_free callback when an image buffer is to be released during a file close operation.

Callback functions
The image_malloc callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library malloc() call.

Signature in H5_file_image_callbacks_t:

void *(*image_malloc) ( size_t size, H5_file_image_op_t *file_image_op, void *udata )

Parameters:

size_t `size`		IN: Size in bytes of the file image buffer to allocate
H5_file_image_op_t *`file_image_op`
		IN: A value from `H5_file_image_op_t` indicating the operation being performed on the file image when this callback is invoked
void *`udata`		IN: Value passed in in the `H5Pset_file_image_callbacks` parameter `udata`

The image_memcpy callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library memcopy() call, except that it returns a NULL on failure. (The memcpy C Library routine is defined to return the dest parameter in all cases.)

Setting image_memcpy to NULL indicates that HDF5 should invoke the standard C library memcpy() routine when copying buffers.

Signature in H5_file_image_callbacks_t:

void *(*image_memcpy) ( void *dest, const void *src, size_t size, H5_file_image_op_t *file_image_op, void *udata )

Parameters:

void *`dest`		IN: Address of the destination buffer
const void *`src`		IN: Address of the source buffer
size_t `size`		IN: Size in bytes of the file image buffer to copy
H5_file_image_op_t *`file_image_op`
		IN: A value from `H5_file_image_op_t` indicating the operation being performed on the file image when this callback is invoked
void *`udata`		IN: Value passed in in the `H5Pset_file_image_callbacks` parameter `udata`

The image_realloc callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library realloc() call.

Setting image_realloc to NULL indicates that HDF5 should invoke the standard C library realloc() routine when resizing file image buffers.

Signature in H5_file_image_callbacks_t:

void *(*image_realloc) ( void *ptr, size_t size, H5_file_image_op_t *file_image_op, void *udata )

Parameters:

void *`ptr`		IN: Pointer to the buffer being reallocated
size_t `size`		IN: Desired size in bytes of the file image buffer after reallocation
H5_file_image_op_t *`file_image_op`
		IN: A value from `H5_file_image_op_t` indicating the operation being performed on the file image when this callback is invoked
void *`udata`		IN: Value passed in in the `H5Pset_file_image_callbacks` parameter `udata`

The image_free callback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C library free() call, except that it will return 0 (SUCCEED) on success and -1 (FAIL) on failure.

Setting image_free to NULL indicates that HDF5 should invoke the standard C library free() routine when releasing file image buffers.

Signature in H5_file_image_callbacks_t:

herr_t (*image_free) ( void *ptr, H5_file_image_op_t *file_image_op, void *udata )

Parameters:

void *`ptr`		IN: Pointer to the buffer being released
H5_file_image_op_t *`file_image_op`
		IN: A value from `H5_file_image_op_t` indicating the operation being performed on the file image when this callback is invoked
void *`udata`		IN: Value passed in in the `H5Pset_file_image_callbacks` parameter `udata`

The udata_copy callback contains a pointer to a function that, from the perspective of HDF5, allocates a buffer of suitable size, copies the contents of the supplied udata into the new buffer, and returns the address of the new buffer. The function returns NULL on failure. This function is necessary if a non-NULL udata parameter is supplied, so that property lists containing the image callbacks can be copied. If the udata parameter below is NULL, then this parameter should be NULL as well.

Signature in H5_file_image_callbacks_t:

void *(*udata_copy) ( void *udata )

Parameters:

void *udata IN: Value passed in in the H5Pset_file_image_callbacks parameter udata

The udata_free callback contains a pointer to a function that, from the perspective of HDF5, frees a user data block. This function is necessary if a non-NULL udata parameter is supplied so that property lists containing image callbacks can be discarded without a memory leak. If the udata parameter below is NULL, this parameter should be NULL as well.

Signature in H5_file_image_callbacks_t:

herr_t (*udata_free) ( void *udata )

Parameters:

void *udata IN: Value passed in in the H5Pset_file_image_callbacks parameter udata

udata, the final field in the H5_file_image_callbacks_t struct, provides a pointer to user-defined data. This pointer will be passed to the image_malloc, image_memcpy, image_realloc, and image_free callbacks. Define udata as NULL if no user-defined data is provided.

Parameters:

hid_t `fapl_id`		IN: File access property list identifier
H5_file_image_callbacks_t *`callbacks_ptr`
		IN/OUT: Pointer to an instance of the `H5_file_image_callbacks_t` structure

Returns:

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

Failure Modes:

Due to interactions between this function and H5Pset_file_image and H5Pget_file_image, H5Pset_file_image_callbacks will fail if a file image has already been set in the target file access property list, fapl_id.

See Also:

H5LTopen_file_image

H5Fget_file_image

H5Pset_file_image
H5Pget_file_image

H5Pget_file_image_callbacks “HDF5 File Image Operations”
in Advanced Topics in HDF5

Within H5Pset_file_image_callbacks:
Callback struct H5_file_image_callbacks_t
Callback ENUM H5_file_image_op_t

History:

Release	Change
1.8.9	C function introduced in this release.

Last modified: 2016

Name: H5Pset_file_space_page_size

Signature:

herr_t H5Pset_file_space_page_size(hid_t fcpl, hsize_t fsp_size)

Purpose:

Sets the file space page size for a file creation property list.

Description:

H5Pset_file_space_page_size sets the file space page size fsp_size used in paged aggregation and paged buffering.

fsp_size has a minimum size of 512. Setting a value less than 512 will return an error. The library default size for the file space page size when not set is 4096.

The size set via this routine may not be changed for the life of the file.

Parameters:

`hid_t fcpl`		IN: File creation property list identifier
`hsize_t fsp_size`		IN: File space page size

Returns:

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

Fortran Interface:

None

See Also:

History:

Release	Change
1.10.1	C function introduced with this release.

Last modified: 2016

Name: H5Pset_file_space_strategy

Signature:

herr_t H5Pset_file_space_strategy(
        hid_t fcpl, 
        H5F_fspace_strategy_t strategy, 
        hbool_t persist, 
        hsize_t threshold);

Purpose:

Sets the file space handling strategy and persisting free-space values for a file creation property list.

Description:

H5Pset_file_space_strategy sets the file space handling strategy, specifies persisting free-space or not (persist), and sets the free-space section size threshold in the file creation property list fcpl.

This setting cannot be changed for the life of the file.

As the H5F_FSPACE_STRATEGY_AGGR and H5F_FSPACE_STRATEGY_NONE strategies do not use the free-space managers, the persist and threshold settings will be ignored for those strategies.

Limitations:

The H5F_FSPACE_STRATEGY_PAGE (Page Buffering) strategy is turned off in parallel. You will receive an error if attempting to enable it in a parallel build.
The H5F_FSPACE_STRATEGY_AGGR (Paged Aggregation) strategy is not available with either the split or multi-file drivers.

Parameters:

`hid_t fcpl`		IN: The file creation property list identifier used to create a new file
`H5F_fspace_strategy_t strategy`		IN: The file space handling strategy to be used. `H5F_fspace_strategy_t` is defined as: typedef enum H5F_fspace_strategy_t { H5F_FSPACE_STRATEGY_FSM_AGGR = 0, /* FSM, Aggregators, VFD / H5F_FSPACE_STRATEGY_PAGE = 1 / Paged FSM, VFD / H5F_FSPACE_STRATEGY_AGGR = 2 / Aggregators, VFD / H5F_FSPACE_STRATEGY_NONE = 3, / VFD */ H5F_FSPACE_STRATEGY_NTYPES } H5F_fspace_strategy_t;
`hbool_t persist`		IN: A boolean value to indicate whether free space should be persistent or not.
`hsize_t threshold`		IN: The smallest free-space section size that the free space manager will track.

Returns:

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

Fortran Interface:

None

See Also:

History:

Release	Change
1.10.1	C function introduced with this release.

Name: H5Pset_fill_time

Signature:

herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time )

Purpose:

Sets the time when fill values are written to a dataset.

Description:

H5Pset_fill_time sets up the timing for writing fill values to a dataset. This property is set in the dataset creation property list plist_id.

Timing is specified in fill_time with one of the following values:

H5D_FILL_TIME_IFSET Write fill values to the dataset when storage space is allocated only if there is a user-defined fill value, i.e., one set with H5Pset_fill_value. (Default)
H5D_FILL_TIME_ALLOC Write fill values to the dataset when storage space is allocated.
H5D_FILL_TIME_NEVER Never write fill values to the dataset.

Note:

H5Pset_fill_time is designed for coordination with the dataset fill value and dataset storage allocation time properties, set with the functions H5Pset_fill_value and H5Pset_alloc_time.

See H5Dcreate for further cross-references.

Parameters:

hid_t plist_id IN: Dataset creation property list identifier.

H5D_fill_time_t fill_time IN: When to write fill values to a dataset.

Returns:

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

Fortran90 Interface: h5pset_fill_time_f

SUBROUTINE h5pset_fill_time_f(plist_id, flag, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property
                                         ! list identifier
  INTEGER(HSIZE_T), INTENT(IN) :: flag   ! File time flag
                                         ! Possible values are:
                                         !    H5D_FILL_TIME_ERROR_F
                                         !    H5D_FILL_TIME_ALLOC_F
                                         !    H5D_FILL_TIME_NEVER_F
  INTEGER, INTENT(OUT)       :: hdferr   ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pset_fill_time_f

History:

Release C

1.6.0 Function introduced in this release.

Last modified: 29 September 2011

Name: H5Pset_fill_value

Signature:

herr_t H5Pset_fill_value( hid_t plist_id, hid_t type_id, const void *value )

Purpose:

Sets the fill value for a dataset.

Description:

H5Pset_fill_value sets the fill value for a dataset in the dataset creation property list.

value is interpreted as being of datatype type_id. This datatype may differ from that of the dataset, but the HDF5 library must be able to convert value to the dataset datatype when the dataset is created.

The default fill value is 0 (zero), which is interpreted according to the actual dataset datatype.

Setting value to NULL indicates that the fill value is to be undefined.

Notes:

Applications sometimes write data only to portions of an allocated dataset. It is often useful in such cases to fill the unused space with a known fill value. This function allows the user application to set that fill value; the functions H5Dfill and H5Pset_fill_time, respectively, provide the ability to apply the fill value on demand or to set up its automatic application.

A fill value should be defined so that it is appropriate for the application. While the HDF5 default fill value is 0 (zero), it is often appropriate to use another value. It might be useful, for example, to use a value that is known to be impossible for the application to legitimately generate.

H5Pset_fill_value is designed to work in concert with H5Pset_alloc_time and H5Pset_fill_time. H5Pset_alloc_time and H5Pset_fill_time govern the timing of dataset storage allocation and fill value write operations and can be important in tuning application performance.

See H5Dcreate for further cross-references.

Parameters:

hid_t `plist_id`	IN: Dataset creation property list identifier.
hid_t `type_id`,	IN: Datatype of `value`.
const void *`value`	IN: Pointer to buffer containing value to use as fill value.

Returns:

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

Fortran90 Interface: h5pset_fill_value_f

Signature:

  SUBROUTINE h5pset_fill_value_f(prp_id, type_id, fillvalue, hdferr) 
    INTEGER(HID_T), INTENT(IN)  :: prp_id
    INTEGER(HID_T), INTENT(IN)  :: type_id
    TYPE(VOID)    , INTENT(IN)  :: fillvalue
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  prp_id    - Property list identifier
  type_id   - Datatype identifier of fill value datatype (in memory)
  fillvalue - Fillvalue

Outputs:

  hdferr    - Returns 0 if successful and -1 if fails

Fortran2003 Interface: h5pset_fill_value_f

Signature:

  SUBROUTINE h5pset_fill_value_f(prp_id, type_id, fillvalue, hdferr)
    INTEGER(HID_T), INTENT(IN)  :: prp_id 
    INTEGER(HID_T), INTENT(IN)  :: type_id
    TYPE(C_PTR)   , INTENT(IN)  :: fillvalue
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  prp_id    - Property list identifier
  type_id   - Datatype identifier of fill value datatype (in memory)
  fillvalue - Fillvalue

Outputs:

  hdferr    - Returns 0 if successful and -1 if fails

History:

Release	Change
1.8.8	Fortran updated to Fortran2003.

Last modified: 30 April 2014

Name: H5Pset_filter

Signature:

herr_t H5Pset_filter(hid_t plist_id, H5Z_filter_t filter_id, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] )

Purpose:

Adds a filter to the filter pipeline.

Description:

H5Pset_filter adds the specified filter_id and corresponding properties to the end of an output filter pipeline.

plist_id must be either a dataset creation property list or group creation property list identifier. If plist_id is a dataset creation property list identifier, the filter is added to the raw data filter pipeline.

If plist_id is a group creation property list identifier, the filter is added to the link filter pipeline, which filters the fractal heap used to store the most of link metadata in certain types of groups. The only predefined filters that can be set in a group creation property list are the gzip filter (H5Z_FILTER_DEFLATE) and the Fletcher32 error detection filter (H5Z_FILTER_FLETCHER32).

The array cd_values contains cd_nelmts integers which are auxiliary data for the filter. The integer values will be stored in the dataset object header as part of the filter information.

The flags argument is a bit vector with the following fields specifying certain general properties of the filter:

H5Z_FLAG_OPTIONAL

If this bit is set then the filter is optional. If the filter fails (see below) during an H5Dwrite operation then the filter is just excluded from the pipeline for the chunk for which it failed; the filter will not participate in the pipeline during an H5Dread of the chunk. This is commonly used for compression filters: if the filter result would be larger than the input, then the compression filter returns failure and the uncompressed data is stored in the file.

This flag should not be set for the Fletcher32 checksum filter as it will bypass the checksum filter without reporting checksum errors to an application.

H5Z_FLAG_MANDATORY

If the filter is required, that is, set to mandatory, and the filter fails, the library’s behavior depends on whether the chunk cache is in use:

If the chunk cache is enabled, data chunks will be flushed to the file during H5Dclose and the library will return the failure in H5Dclose.
When the chunk cache is disabled or not big enough, or the chunk is being evicted from the cache, the failure will happen during H5Dwrite.

In each case, the library will still write to the file all data chunks that were processed by the filter before the failure occured.

For example, assume that an application creates a dataset of four chunks, the chunk cache is enabled and is big enough to hold all four chunks, and the filter fails when it tries to write the fourth chunk. The actual flush of the chunks will happen during H5Dclose, not H5Dwrite. By the time H5Dclose fails, the first three chunks will have been written to the file. Even though H5Dclose fails, all the resources will be released and the file can be closed properly.

If, however, the filter fails on the second chunk, only the first chunk will be written to the file as nothing further can be written once the filter fails.

The filter_id parameter specifies the filter to be set. Valid pre-defined filter identifiers are as follows:

`H5Z_FILTER_DEFLATE`	Data compression filter, employing the gzip algorithm
`H5Z_FILTER_SHUFFLE`	Data shuffling filter
`H5Z_FILTER_FLETCHER32`	Error detection filter, employing the Fletcher32 checksum algorithm
`H5Z_FILTER_SZIP`	Data compression filter, employing the SZIP algorithm
`H5Z_FILTER_NBIT`	Data compression filter, employing the N-Bit algorithm
`H5Z_FILTER_SCALEOFFSET`	Data compression filter, employing the scale-offset algorithm

Also see H5Pset_edc_check and H5Pset_filter_callback.

Notes:

When a non-empty filter pipeline is used with a group creation property list, the group will be created with the new group file format (see “Group Implementations in HDF5”). The filters will come into play only when dense storage is used (see H5Pset_link_phase_change) and will be applied to the group’s fractal heap. The fractal heap will contain most of the the group’s link metadata, including link names.

When working with group creation property lists, if you are adding a filter that is not in HDF5’s set of predefined filters, i.e., a user-defined or third-party filter, you must first determine that the filter will work for a group. See the discussion of the set local and can apply callback functions in H5Zregister.

If multiple filters are set for a property list, they will be applied to each chunk of raw data for datasets or each block of the fractal heap for groups in the order in which they were set.

Filters can be applied only to chunked datasets; they cannot be used with other dataset storage methods, such as contiguous, compact, or external datasets.

Dataset elements of variable-length and dataset region reference datatypes are stored in separate structures in the file called heaps. Filters cannot currently be applied to these heaps.

Filter Behavior in HDF5:
Filters can be inserted into the HDF5 pipeline to perform functions such as compression and conversion. As such, they are a very flexible aspect of HDF5; for example, a user-defined filter could provide encryption for an HDF5 dataset.

A filter can be declared as either required or optional. Required is the default status; optional status must be explicitly declared.

A required filter that fails or is not defined causes an entire output operation to fail; if it was applied when the data was written, such a filter will cause an input operation to fail.

The following table summarizes required filter behavior.

	Required FILTER_X not available	FILTER_X available
`H5Pset_<FILTER_X>`	Will fail.	Will succeed.
`H5Dwrite` with FILTER_X set	Will fail.	Will succeed; FILTER_X will be applied to the data.
`H5Dread` with FILTER_X set	Will fail.	Will succeed.

An optional filter can be set for an HDF5 dataset even when the filter is not available. Such a filter can then be applied to the dataset when it becomes available on the original system or when the file containing the dataset is processed on a system on which it is available.

A filter can be declared as optional through the use of the H5Z_FLAG_OPTIONAL flag with H5Pset_filter.

Consider a situation where one is creating files that will normally be used only on systems where the optional (and fictional) filter FILTER_Z is routinely available. One can create those files on system A, which lacks FILTER_Z, create chunked datasets in the files with FILTER_Z defined in the dataset creation property list, and even write data to those datasets. The dataset object header will indicate that FILTER_Z has been associated with this dataset. But since system A does not have FILTER_Z, dataset chunks will be written without it being applied.

HDF5 has a mechanism for determining whether chunks are actually written with the filters specified in the object header, so while the filter remains unavailable, system A will be able to read the data. Once the file is moved to system B, where FILTER_Z is available, HDF5 will apply FILTER_Z to any data rewritten or new data written in these datasets. Dataset chunks that have been written on system B will then be unreadable on system A; chunks that have not been re-written since being written on system A will remain readable on system A. All chunks will be readable on system B.

The following table summarizes optional filter behavior.

	FILTER_Z not available	FILTER_Z available with encode and decode	FILTER_Z available decode only
`H5Pset_<FILTER_Z>`	Will succeed.	Will succeed.	Will succeed.
`H5Dwrite` with FILTER_Z set	Will succeed; FILTER_Z will not be applied to the data.	Will succeed; FILTER_Z will be applied to the data.	Will succeed; FILTER_Z will not be applied to the data.
`H5Dread` with FILTER_Z set	Will succeed if FILTER_Z has not actually been applied to data.	Will succeed.	Will succeed.

The above principles apply generally in the use of HDF5 optional filters insofar as HDF5 does as much as possible to complete an operation when an optional filter is unavailable. (The SZIP filter is an exception to this rule; see H5Pset_szip for details.)

See Also:

For a discussion of the chunk cache, see H5Pset_cache.

For a discussion of the various types of HDF5 groups, see “Group Implementations in HDF5.”

Parameters:

hid_t `plist_id`	IN: Dataset or group creation property list identifier.
H5Z_filter_t `filter_id`	IN: Filter identifier for the filter to be added to the pipeline.
unsigned int `flags`	IN: Bit vector specifying certain general properties of the filter.
size_t `cd_nelmts`	IN: Number of elements in `cd_values`.
const unsigned int `cd_values[]`	IN: Auxiliary data for the filter.

Returns:

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

Fortran90 Interface: h5pset_filter_f

SUBROUTINE h5pset_filter_f(prp_id, filter, flags, cd_nelmts, cd_values,  hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id  ! Gropu or dataset creation property 
                                        ! list identifier
  INTEGER, INTENT(IN) :: filter         ! Filter to be added to the pipeline
  INTEGER, INTENT(IN) :: flags          ! Bit vector specifying certain 
                                        ! general properties of the filter
  INTEGER(SIZE_T), INTENT(IN) :: cd_nelmts        
                                        ! Number of elements in cd_values
  INTEGER, DIMENSION(*), INTENT(IN) :: cd_values  
                                        ! Auxiliary data for the filter
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pset_filter_f

History:

Release Change

1.6.0 Function introduced in this release.

1.8.5 Function applied to group creation property lists.

Name: H5Pset_filter_callback

Signature:

herr_t H5Pset_filter_callback(hid_t plist, H5Z_filter_func_t func, void *op_data)

Purpose:

Sets user-defined filter callback function.

Description:

H5Pset_filter_callback sets the user-defined filter 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 a filter fails. The function prototype is as follows:

typedef H5Z_cb_return_t (H5Z_filter_func_t) (H5Z_filter_t filter_id, void *buf, size_t buf_size, void *op_data)

where filter_id indicates which filter has failed, buf and buf_size are used to pass in the failed data, and op_data is the required input data for this callback function.

Valid callback function return values are H5Z_CB_FAIL and H5Z_CB_CONT. �

Parameters:

hid_t plist IN: Dataset transfer property list identifier.

H5Z_filter_func_t func IN: User-defined filter 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.

History:

Release C

1.6.0 Function introduced in this release.

Last modified: 14 June 2010

Name: H5Pset_fletcher32

Signature:

herr_t H5Pset_fletcher32( hid_t plist_id )

Purpose:

Sets up use of the Fletcher32 checksum filter.

Description:

H5Pset_fletcher32 sets the Fletcher32 checksum filter in the dataset or group creation property list plist_id.

Note:

The Fletcher32 EDC checksum filter was added in HDF5 Release 1.6.0. In the original implementation, however, the checksum value was calculated incorrectly on little-endian systems. The error was fixed in HDF5 Release 1.6.3.

Work-around: An HDF5 Library of Release 1.6.2 or earlier will be able to read a dataset created or written with the checksum filter by an HDF5 Library of Release 1.6.3 or later if the checksum filter is disabled for the read operation. This can be accomplished via a call to H5Pset_edc_check with the value H5Z_DISABLE_EDC in the second parameter. This has the obvious drawback that the application will be unable to verify the checksum, but the data does remain accessible.

Parameters:

hid_t plist_id IN: Dataset or group creation property list identifier.

Returns:

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

Fortran90 Interface: h5pset_fletcher32_f

SUBROUTINE h5pset_fletcher32_f(prp_id, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id  ! Property list identifier 
  INTEGER, INTENT(OUT)       :: hdferr  ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pset_fletcher32_f

History:

Release	Change
1.6.0	Function introduced in this release.
1.6.3	Error in checksum calculation on little-endian systems corrected in this release.
1.8.5	Function extended to work with group creation property lists.

Name: H5Pset_gc_references

Signature:

herr_t H5Pset_gc_reference(hid_t plist, unsigned gc_ref )

Purpose:

Sets garbage collecting references flag.

Description:

H5Pset_gc_references sets the flag for garbage collecting references for the file.

Dataset region references and other reference types use space in an HDF5 file's global heap. If garbage collection is on and the user passes in an uninitialized value in a reference structure, the heap might get corrupted. When garbage collection is off, however, and the user re-uses a reference, the previous heap block will be orphaned and not returned to the free heap space.

When garbage collection is on, the user must initialize the reference structures to 0 or risk heap corruption.

The default value for garbage collecting references is off.

Parameters:

hid_t plist IN: File access property list identifier.

unsigned gc_ref IN: Flag setting reference garbage collection to on (1) or off (0).

Returns:

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

Fortran90 Interface: h5pset_gc_references_f

SUBROUTINE h5pset_gc_references_f (prp_id, gc_reference, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
  INTEGER, INTENT(IN) :: gc_reference  ! Flag for garbage collecting
                                       ! references for the file
  INTEGER, INTENT(OUT) :: hdferr       ! Error code
                                       ! 0 on success and -1 on failure
END SUBROUTINE h5pset_gc_references_f

Name: H5Pset_hyper_vector_size

Signature:

herr_t H5Pset_hyper_vector_size(hid_t dxpl_id, size_t vector_size )

Purpose:

Sets number of I/O vectors to be read/written in hyperslab I/O.

Description:

H5Pset_hyper_vector_size sets the number of I/O vectors to be accumulated in memory before being issued to the lower levels of the HDF5 library for reading or writing the actual data.

The I/O vectors are hyperslab offset and length pairs and are generated during hyperslab I/O.

The number of I/O vectors is passed in vector_size to be set in the dataset transfer property list dxpl_id. vector_size must be greater than 1 (one).

H5Pset_hyper_vector_size is an I/O optimization function; increasing vector_size should provide better performance, but the library will use more memory during hyperslab I/O. The default value of vector_size is 1024.

Parameters:

hid_t dxpl_id IN: Dataset transfer property list identifier.

size_t vector_size IN: Number of I/O vectors to accumulate in memory for I/O operations. Must be greater than 1 (one). Default value: 1024.

Returns:

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

Fortran90 Interface: h5pset_hyper_vector_size_f

SUBROUTINE h5pset_hyper_vector_size_f(plist_id, size, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset transfer property list 
                                         ! identifier
  INTEGER(SIZE_T), INTENT(IN) :: size    ! Vector size 
  INTEGER, INTENT(OUT)       :: hdferr   ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pset_hyper_vector_size_f

History:

Release C

1.6.0 Function introduced in this release.

Last modified: 7 March 2013

Name: H5Pset_istore_k

Signature:

herr_t H5Pset_istore_k( hid_t fcpl_id, unsigned ik )

Purpose:

Sets the size of the parameter used to control the B-trees for indexing chunked datasets.

Description:

H5Pset_istore_k sets the size of the parameter used to control the B-trees for indexing chunked datasets. This function is valid only for file creation property lists.

ik is one half the rank of a tree that stores chunked raw data. On average, such a tree will be 75% full, or have an average rank of 1.5 times the value of ik.

The HDF5 library uses (ik*2) as the maximum # of entries before splitting a B-tree node. Since only 2 bytes are used in storing # of entries for a B-tree node in an HDF5 file, (ik*2) cannot exceed 65536. The default value for ik is 32.

Parameters:

hid_t `fcpl_id`	IN: File creation property list identifier
unsigned `ik`	IN: 1/2 rank of chunked storage B-tree

Returns:

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

Fortran90 Interface: h5pset_istore_k_f

SUBROUTINE h5pset_istore_k_f (prp_id, ik, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
  INTEGER, INTENT(IN) :: ik            ! 1/2 rank of chunked storage B-tree
  INTEGER, INTENT(OUT) :: hdferr       ! Error code
                                       ! 0 on success and -1 on failure
END SUBROUTINE h5pset_istore_k_f

History:

Release	C
1.6.4	`ik` parameter type changed to unsigned.

Last modified: 21 April 2016

Name: H5Pset_layout

Signature:

herr_t H5Pset_layout( hid_t plist, H5D_layout_t layout )

Purpose:

Sets the type of storage used to store the raw data for a dataset.

Description:

H5Pset_layout sets the type of storage used to store the raw data for a dataset. This function is only valid for dataset creation property lists.

Valid values for layout are:

H5D_COMPACT: Store raw data in the dataset object header in file. This should only be used for datasets with small amounts of raw data. The raw data size limit is 64K (65520 bytes). Attempting to create a dataset with raw data larger than this limit will cause the H5Dcreate call to fail.
H5D_CONTIGUOUS: Store raw data separately from the object header in one large chunk in the file.
H5D_CHUNKED: Store raw data separately from the object header as chunks of data in separate locations in the file.
H5D_VIRTUAL: Draw raw data from multiple datasets in different files.

Note that a compact storage layout may affect writing data to the dataset with parallel applications. See note in H5Dwrite documentation for details.

Parameters:

hid_t `plist`	IN: Identifier of property list to query.
H5D_layout_t `layout`	IN: Type of storage layout for raw data.

Returns:

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

Fortran90 Interface: h5pset_layout_f

SUBROUTINE h5pset_layout_f (prp_id, layout, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
  INTEGER, INTENT(IN) :: layout        ! Type of storage layout for raw data
                                       ! Possible values are:
                                       !    H5D_COMPACT_F
                                       !    H5D_CONTIGUOUS_F
                                       !    H5D_CHUNKED_F
                                       !    H5D_VIRTUAL_F
  INTEGER, INTENT(OUT) :: hdferr       ! Error code
                                       ! 0 on success and -1 on failure
END SUBROUTINE h5pset_layout_f

See Also:

Virtual datasets: H5Pset_virtual

History:

Release	Change
1.10.0	`H5D_VIRTUAL` added in this release.

Name: H5Pset_libver_bounds

Signature:

herr_t H5Pset_libver_bounds( hid_t fapl_id, H5F_libver_t low, H5F_libver_t high )

Purpose:

Sets bounds on library versions, and indirectly format versions, to be used when creating objects.

Description:

H5Pset_libver_bounds controls the versions of the object formats that will be used when creating objects in a file. The object format versions are determined indirectly from the HDF5 Library versions specified in the call.

This property is set in the file access property list specified by fapl_id.

Parameters:

hid_t fapl_id IN: File access property list identifier

H5F_libver_t low

IN: The earliest version of the library that will be used for writing objects. The library version indirectly specifies the earliest object format version that can be used when creating objects in the file.

Currently, low must be one of two pre-defined values:

Setting low to H5F_LIBVER_EARLIEST will result in objects being created using the earliest possible format for each object. Note that earliest possible is different from earliest, as some features introduced in library versions later than 1.0.0 resulted in updates to object formats. With low=H5F_LIBVER_EARLIEST, if the application creates an object that requires a feature introduced in library versions later than 1.0.0, the earliest possible version that supports the requested feature will be used.

The upper bound on the range of possible library versions used to create the object is controlled by the high parameter.

This is the default behavior of the library if H5Pset_libver_bounds is not called.

Setting low to H5F_LIBVER_LATEST will result in objects being created using the latest available format for each object. This setting means that objects will be created with the latest format versions available (within the range of library versions specified in the call), and can take advantage of the latest features and performance enhancements. Objects written with the H5F_LIBVER_LATEST setting for low may be accessible to a smaller range of library versions than would be the case if the H5F_LIBVER_EARLIEST value had been used.

The upper bound on the range of possible library versions used to create the object is controlled by the high parameter.

H5F_libver_t high

IN: The latest version of the library that will be used for writing objects. The library version indirectly specifies the latest object format version that can be used when creating objects in the file.

Currently, high must be set to the pre-defined value H5F_LIBVER_LATEST. H5F_LIBVER_LATEST corresponds to the version of the HDF5 Library in use.

Returns:

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

Fortran90 Interface: h5pset_libver_bounds_f

SUBROUTINE h5pset_libver_bounds_f(fapl_id, low, high, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: fapl_id 
                             ! File access property list identifier
  INTEGER, INTENT(IN) :: low ! The earliest version of the library that 
                             ! will be used for writing objects.
                             ! Currently, low must be either:
                             !        H5F_LIBVER_EARLIEST_F
                             !        H5F_LIBVER_LATEST_F
    INTEGER, INTENT(IN) :: high 
                             ! The latest version of the library that will be 
                             ! used for writing objects.
                             ! Currently, high must set to:
                             !            H5F_LIBVER_LATEST_F
    INTEGER, INTENT(OUT) :: hdferr
                             ! Error code
                             ! 0 on success and -1 on failure
END SUBROUTINE h5pset_libver_bounds_f

History:

Release	C
1.8.0	Function introduced in this release.

Last modified: 22 March 2012

Name: H5Pset_link_creation_order

Signature:

herr_t H5Pset_link_creation_order( hid_t gcpl_id, unsigned crt_order_flags )

Purpose:

Sets creation order tracking and indexing for links in a group.

Description:

H5Pset_link_creation_order sets flags for tracking and indexing links on creation order in groups created with the group creation property list gcpl_id.

crt_order_flags contains flags with the following meanings:

H5P_CRT_ORDER_TRACKED Link creation order is tracked but not necessarily indexed.
H5P_CRT_ORDER_INDEXED Link creation order is indexed (requires H5P_CRT_ORDER_TRACKED).

Default behavior is that link creation order is neither tracked nor indexed.

H5Pset_link_creation_order can be used to set link creation order tracking, or to set link creation order tracking and indexing.

Note that if a creation order index is to be built, it must be specified in the group creation property list. HDF5 currently provides no mechanism to turn on link creation order tracking at group creation time and to build the index later.

Parameters:

hid_t `gcpl_id`	IN: Group creation property list identifier
unsigned `crt_order_flags`	IN: Creation order flag(s)

Returns:

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

Fortran90 Interface: h5pset_link_creation_order_f

SUBROUTINE h5pset_link_creation_order_f(gcpl_id, crt_order_flags, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: gcpl_id  ! File access property list identifier
  INTEGER, INTENT(IN) :: crt_order_flags ! Creation order flag(s):
                                         !   H5P_CRT_ORDER_TRACKED_F
                                         !   H5P_CRT_ORDER_INDEXED_F
  INTEGER, INTENT(OUT) :: hdferr         ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pset_link_creation_order_f

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Pset_link_phase_change

Signature:

herr_t H5Pset_link_phase_change( hid_t gcpl_id, unsigned max_compact, unsigned min_dense )

Purpose:

Sets the parameters for conversion between compact and dense groups.

Description:

H5Pset_link_phase_change sets the maximum number of entries for a compact group and the minimum number of links to allow before converting a dense group to back to the compact format.

max_compact is the maximum number of links to store as header messages in the group header as before converting the group to the dense format. Groups that are in compact format and in which the exceed this number of links rises above this threshold are automatically converted to dense format.

min_dense is the minimum number of links to store in the dense format. Groups which are in dense format and in which the number of links falls below this theshold are automatically converted to compact format.

See “Group implementations in HDF5” in the H5G API introduction for a discussion of the available types of HDF5 group structures.

Parameters:

hid_t `gcpl_id`	IN: Group creation property list identifier
unsigned `max_compact`	IN: Maximum number of links for compact storage (Default: 8)
unsigned `min_dense`	IN: Minimum number of links for dense storage (Default: 6)

Returns:

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

Fortran90 Interface: h5pset_link_phase_change_f

SUBROUTINE h5pset_link_phase_change_f(gcpl_id, max_compact, min_dense, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list id
  INTEGER, INTENT(IN) :: max_compact    ! Maximum number of attributes to be  
                                        ! stored in compact storage
  INTEGER, INTENT(IN) :: min_dense      ! Minimum number of attributes to be  
                                        ! stored in dense storage
  INTEGER, INTENT(OUT) :: hdferr        ! Error code 
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pset_link_phase_change_f

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Pset_local_heap_size_hint

Signature:

herr_t H5Pset_local_heap_size_hint( hid_t gcpl_id, size_t size_hint )

Purpose:

Specifies the anticipated maximum size of a local heap.

Description:

H5Pset_local_heap_size_hint is used with original-style HDF5 groups (see “Motivation” below) to specify the anticipated maximum local heap size, size_hint, for groups created with the group creation property list gcpl_id. The HDF5 Library then uses size_hint to allocate contiguous local heap space in the file for each group created with gcpl_id.

For groups with many members or very few members, an appropriate initial value of size_hint would be the anticipated number of group members times the average length of group member names, plus a small margin:

          size_hint = max_number_of_group_members  * 
                      (average_length_of_group_member_link_names + 2)

If it is known that there will be groups with zero members, the use of a group creation property list with size_hint set to to 1 (one) will guarantee the smallest possible local heap for each of those groups.

Setting size_hint to zero (0) causes the library to make a reasonable estimate for the default local heap size.

Motivation:

In situations where backward-compatibility is required, specifically, when libraries prior to HDF5 Release 1.8.0 may be used to read the file, groups must be created and maintained in the original style. This is HDF5’s default behavior. If backward compatibility with pre-1.8.0 libraries is not a concern, greater efficiencies can be obtained with the new-format compact and indexed groups. See “Group implementations in HDF5” in the H5G API introduction.

H5Pset_local_heap_size_hint is useful for tuning file size when files contain original-style groups with either zero members or very large numbers of members.

The original style of HDF5 groups, the only style available prior to HDF5 Release 1.8.0, was well-suited for moderate-sized groups but was not optimized for either very small or very large groups. This original style remains the default, but two new group implementations were introduced in HDF5 Release 1.8.0: compact groups to accomodate zero to small numbers of members and indexed groups for thousands or tens of thousands of members ... or millions, if that's what your application requires.

The local heap size hint, size_hint, is a performance tuning parameter for original-style groups. As indicated above, an HDF5 group may have zero, a handful, or tens of thousands of members. Since the original style of HDF5 groups stores the metadata for all of these group members in a uniform format in a local heap, the size of that metadata (and hence, the size of the local heap) can vary wildly from group to group. To intelligently allocate space and to avoid unnecessary fragmentation of the local heap, it can be valuable to provide the library with a hint as to the local heap’s likely eventual size. This can be particularly valuable when it is known that a group will eventually have a great many members. It can also be useful in conserving space in a file when it is known that certain groups will never have any members.

Parameters:

hid_t `gcpl_id`	IN: Group creation property list identifier
size_t `size_hint`	IN: Anticipated maximum size in bytes of local heap

Returns:

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

Fortran90 Interface:

None.

History:

Release	Change
1.8.0	Function introduced in this release.

Last modified: 22 August 2012

Name: H5Pset_mcdt_search_cb

Signature:

herr_t H5Pset_mcdt_search_cb( hid_t ocpypl_id, H5O_mcdt_search_cb_t func, void *op_data )

Purpose:

Sets the callback function that H5Ocopy will invoke before searching the entire destination file for a matching committed datatype.

Motivation:

H5Pset_mcdt_search_cb provides the means to define a callback function. An application can then use that callback to take an additional action before the default search of all committed datatypes in the destination file or to take an action that replaces the default search. This mechanism is intended to improve performance when the global search might take a long time.

Description:

H5Pset_mcdt_search_cb allows an application to set a callback function, func, that will be invoked before searching the destination file for a matching committed datatype. The default, global search process is described in H5Padd_merge_committed_dtype_path.

The callback function must conform to the H5O_mcdt_search_cb_t prototype and will return an instruction for one of the following actions:

Continue the search for a matching committed datatype in the destination file.
Discontinue the search for a matching committed datatype. H5Ocopy will then apply the default behavior of creating an anonymous committed datatype.
Abort the copy operation and exit H5Ocopy.

Warning:

If the callback function return value causes H5Ocopy to abort, the destination file may be left in an inconsistent or corrupted state.

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.

Parameters:

hid_t `ocpypl_id`		IN: Object copy property list identifier
H5O_mcdt_search_cb_t `func`		IN: User-defined 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.

Failure Modes:

H5Pset_mcdt_search_cb will fail if the object copy property list is invalid.

Example Usage:

This example defines a callback function in the object copy property list.

/* The user-defined callback function */
static H5O_mcdt_search_ret_t
mcdt_search_cb(void *_udata)
{
    H5O_mcdt_search_ret_t action = *((H5O_mcdt_search_ret_t *)_udata);

    return(action);
}

int main(void) {
    hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);

    /* Enable the merging committed datatype feature. */
    H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);

    /* Add a path to search for a matching committed datatype. */
    H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

    /* 
     * Set the callback function to discontinue the global search
     * if H5Ocopy cannot find a matching committed datatype from the 
     * above suggested path.
     */
    action = H5O_MCDT_SEARCH_STOP;
    H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);
    H5Ocopy(...ocpypl_id...);
    ...
    ...
}

See Also:

H5Ocopy
H5Pset_copy_object

H5Padd_merge_committed_dtype_path
H5Pget_mcdt_search_cb
H5O_mcdt_search_cb_t

Copying Committed Datatypes
with H5Ocopy A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5

History:

Release	Change
1.8.9	C function introduced in this release.

Last modified: 18 May 2009
Name: H5Pset_mdc_config
Signature:: herr_t H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr)
Purpose:: Set the initial metadata cache configuration in the indicated File Access Property List to the supplied value.
Description:: H5Pset_mdc_config attempts to set the initial metadata cache configuration to the supplied value. It will fail if an invalid configuration is detected. This configuration is used when the file is opened.
See the overview of the metadata cache in the special topics section of the user manual for details on what is being configured. If you haven't read and understood that documentation, you really shouldn't be using this API call.
Parameters:

hid_t plist_id     IN: Identifier of the file access property list.

H5AC_cache_config_t *config_ptr      IN: Pointer to the instance of H5AC_cache_config_t containing the desired configuration. The fields of this structure are discussed below:

General configuration section:

int version IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This field should be set to H5AC__CURR_CACHE_CONFIG_VERSION (defined in H5ACpublic.h).

hbool_t rpt_fcn_enabled      IN: Boolean flag indicating whether the adaptive cache resize report function is enabled. This field should almost always be set to FALSE. Since resize algorithm activity is reported via stdout, it MUST be set to FALSE on Windows machines.
The report function is not supported code, and can be expected to change between versions of the library. Use it at your own risk.

hbool_t open_trace_file      IN: Boolean field indicating whether the trace_file_name field should be used to open a trace file for the cache.
The trace file is a debuging feature that allows the capture of top level metadata cache requests for purposes of debugging and/or optimization. This field should normally be set to FALSE, as trace file collection imposes considerable overhead.
This field should only be set to TRUE when the trace_file_name contains the full path of the desired trace file, and either there is no open trace file on the cache, or the close_trace_file field is also TRUE.
The trace file feature is unsupported unless used at the direction of THG. It is intended to allow THG to collect a trace of cache activity in cases of occult failures and/or poor performance seen in the field, so as to aid in reproduction in the lab. If you use it absent the direction of THG, you are on your own.

hbool_t close_trace_file      IN: Boolean field indicating whether the current trace file (if any) should be closed.
See the above comments on the open_trace_file field. This field should be set to FALSE unless there is an open trace file on the cache that you wish to close.
The trace file feature is unsupported unless used at the direction of THG. It is intended to allow THG to collect a trace of cache activity in cases of occult failures and/or poor performance seen in the field, so as to aid in reproduction in the lab. If you use it absent the direction of THG, you are on your own.

char trace_file_name[]      IN: Full path of the trace file to be opened if the open_trace_file field is TRUE.
In the parallel case, an ascii representation of the MPI rank of the process will be appended to the file name to yield a unique trace file name for each process.
The length of the path must not exceed H5AC__MAX_TRACE_FILE_NAME_LEN characters.
The trace file feature is unsupported unless used at the direction of THG. It is intended to allow THG to collect a trace of cache activity in cases of occult failures and/or poor performance seen in the field, so as to aid in reproduction in the lab. If you use it absent the direction of THG, you are on your own.

hbool_t evictions_enabled      IN: A boolean flag indicating whether evictions from the metadata cache are enabled. This flag is initially set to TRUE.
In rare circumstances, the raw data throughput requirements may be so high that the user wishes to postpone metadata writes so as to reserve I/O throughput for raw data. The evictions_enabled field exists to allow this. However, this is an extreme step, and you have no business doing it unless you have read the User Guide section on metadata caching, and have considered all other options carefully.
The evictions_enabled field may not be set to FALSE unless all adaptive cache resizing code is disabled via the incr_mode, flash_incr_mode, and decr_mode fields.
When this flag is set to FALSE, the metadata cache will not attempt to evict entries to make space for new entries, and thus will grow without bound.
Evictions will be re-enabled when this field is set back to TRUE. This should be done as soon as possible.

hbool_t set_initial_size      IN: Boolean flag indicating whether the cache should be created with a user specified initial size.

size_t initial_size      IN: If set_initial_size is TRUE, initial_size must contains the desired initial size in bytes. This value must lie in the closed interval [min_size, max_size]. (see below)

double min_clean_fraction      IN: This field specifies the minimum fraction of the cache that must be kept either clean or empty.
The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to start in the serial case. In the parallel case, a larger value is needed -- see the overview of the metadata cache in the “ Metadata Caching in HDF5” section of the HDF5 User’s Guide for details.

size_t max_size      IN: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select as the maximum cache size.

size_t min_size     IN: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select as the maximum cache size.

long int epoch_length      IN: Number of cache accesses between runs of the adaptive cache resize code. 50,000 is a good starting number.

Increment configuration section:

enum H5C_cache_incr_mode incr_mode
IN: Enumerated value indicating the operational mode of the automatic cache size increase code. At present, only two values are legal:
H5C_incr__off: Automatic cache size increase is disabled, and the remaining increment fields are ignored.
H5C_incr__threshold: Automatic cache size increase is enabled using the hit rate threshold algorithm.

double lower_hr_threshold      IN: Hit rate threshold used by the hit rate threshold cache size increment algorithm.
When the hit rate over an epoch is below this threshold and the cache is full, the maximum size of the cache is multiplied by increment (below), and then clipped as necessary to stay within max_size, and possibly max_increment.
This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good place to start.

double increment      IN: Factor by which the hit rate threshold cache size increment algorithm multiplies the current cache max size to obtain a tentative new cache size.
The actual cache size increase will be clipped to satisfy the max_size specified in the general configuration, and possibly max_increment below.
The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable value.
If you set it to 1.0, you will effectively disable cache size increases.

hbool_t apply_max_increment      IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size increases.

size_t max_increment      IN: Maximum number of bytes by which cache size can be increased in a single step -- if applicable.

enum H5C_cache_flash_incr_mode flash_incr_mode     IN: Enumerated value indicating the operational mode of the flash cache size increase code. At present, only the following values are legal:
H5C_flash_incr__off: Flash cache size increase is disabled.
H5C_flash_incr__add_space: Flash cache size increase is enabled using the add space algorithm.

double flash_threshold      IN: The factor by which the current maximum cache size is multiplied to obtain the minimum size entry / entry size increase which may trigger a flash cache size increase.
At present, this value must lie in the range [0.1, 1.0].

double flash_multiple      IN: The factor by which the size of the triggering entry / entry size increase is multiplied to obtain the initial cache size increment. This increment may be reduced to reflect existing free space in the cache and the max_size field above.
At present, this field must lie in the range [0.1, 10.0].

Decrement configuration section:

enum H5C_cache_decr_mode decr_mode      IN: Enumerated value indicating the operational mode of the automatic cache size decrease code. At present, the following values are legal:
H5C_decr__off: Automatic cache size decrease is disabled.
H5C_decr__threshold: Automatic cache size decrease is enabled using the hit rate threshold algorithm.
H5C_decr__age_out: Automatic cache size decrease is enabled using the ageout algorithm.
H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the ageout with hit rate threshold algorithm

double upper_hr_threshold      IN: Hit rate threshold for the hit rate threshold and ageout with hit rate threshold cache size decrement algorithms.
When decr_mode is H5C_decr__threshold, and the hit rate over a given epoch exceeds the supplied threshold, the current maximum cache size is multiplied by decrement to obtain a tentative new (and smaller) maximum cache size.
When decr_mode is H5C_decr__age_out_with_threshold, there is no attempt to find and evict aged out entries unless the hit rate in the previous epoch exceeded the supplied threshold.
This field must lie in the interval [0.0, 1.0].
For H5C_incr__threshold, .9995 or .99995 is a good place to start.
For H5C_decr__age_out_with_threshold, .999 might be more useful.

double decrement      IN: In the hit rate threshold cache size decrease algorithm, this parameter contains the factor by which the current max cache size is multiplied to produce a tentative new cache size.
The actual cache size decrease will be clipped to satisfy the min_size specified in the general configuration, and possibly max_decrement below.
The parameter must be be in the interval [0.0, 1.0].
If you set it to 1.0, you will effectively disable cache size decreases. 0.9 is a reasonable starting point.

hbool_t apply_max_decrement      IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size decreases.

size_t max_decrement      IN: Maximum number of bytes by which the maximum cache size can be decreased in any single step -- if applicable.

int epochs_before_eviction      IN: In the ageout based cache size reduction algorithms, this field contains the minimum number of epochs an entry must remain unaccessed in cache before the cache size reduction algorithm tries to evict it. 3 is a reasonable value.

hbool_t apply_empty_reserve      IN: Boolean flag indicating whether the ageout based decrement algorithms will maintain a empty reserve when decreasing cache size.

double empty_reserve      IN: Empty reserve as a fraction of maximum cache size if applicable.
When so directed, the ageout based algorithms will not decrease the maximum cache size unless the empty reserve can be met.
The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to start.

Parallel configuration section:

int dirty_bytes_threshold IN: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the metadata caches serving the target file in the parallel case.
Synchronization occurs whenever the number of bytes of dirty metadata created since the last synchronization exceeds this limit.
This field only applies to the parallel case. While it is ignored elsewhere, it can still draw a value out of bounds error.
It must be consistant across all caches on any given file.
By default, this field is set to 256 KB. It shouldn't be more than half the current max cache size times the min clean fraction.

int metadata_write_strategy IN: Desired metadata write strategy. The valid values for this field are:
H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies that only process zero is allowed to write dirty metadata to disk.
H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED: Specifies that process zero still makes the decisions as to what entries should be flushed, but the actual flushes are distributed across the processes in the computation to the extent possible.
The src/H5ACpublic.h include file in the HDF5 library has detailed information on each strategy.
Returns:: Returns a non-negative value if successful; otherwise returns a negative value.

Last modified: 2017

Name: H5Pset_mdc_image_config

Signature:

herr_t H5Pset_mdc_image_config(
        hid_t plist_id,
        H5AC_cache_image_config_t * config_ptr);

Purpose:

Sets the metadata cache image option for a file access property list.

Description:

H5Pset_mdc_image_config sets the metadata cache image option with configuration values specified by config_ptr for the file access property list specified in plist_id.

H5AC_cache_image_config_t is defined as follows:

        typedef struct H5AC_cache_image_config_t {
          int32_t         version;
          hbool_t         generate_image;
          hbool_t         save_resize_status;
          int32_t         entry_ageout;
        } H5AC_cache_image_config_t;

Where the fields of H5AC_cache_image_config_t should be initialized as follows:

`version`:		Must be set to `H5AC__CURR_CACHE_IMAGE_CONFIG_VERSION`.
`generate_image`:		Set to either `TRUE` or `FALSE` depending on whether a cache image is desired.
`save_resize_status`:		Set to either `TRUE` or `FALSE` depending on whether the user wishes the metadata cache image resize configuration to be stored in the cache image and restored on file open. Note: this field is ignored at present.
`entry_ageout`:		This field allows the user to specify the number of times a cache entry can appear in subsequent cache images (created in subsequent file closes) without being accessed. The default value is `-1`, which indicates that the entry may appear in an indefinitely long sequence of cache images. The maximum value is `100`. Note: This field is ignored at present.

Limitations:

While it is an obvious error to request a cache image when opening the file read only, it is not in general possible to test for this error in the H5Pset_mdc_image_config() call. Rather than fail the subsequent file open, the library silently ignores the file image request in this case.

It is also an error to request a cache image on a file that does not support superblock extension messages (i.e. a superblock version less than 2). As above, it is not always possible to detect this error in the H5Pset_mdc_image_config() call, and thus the request for a cache image will fail silently in this case as well.

Creation of cache images is currently disabled in parallel -- as above, any request for a cache image in this context will fail silently.

Files with cache images may be read in parallel applications, but note that the load of the cache image is a collective operation triggered by the first operation that accesses metadata after file open (or, if persistent free space managers are enabled, on the first allocation or deallocation of file space, or read of file space manager status, whichever comes first). Thus the parallel process may deadlock if any process does not participate in this access.

In long sequences of file closes and opens, infrequently accessed metadata can accumulate in the cache image to the point where the cost of storing and restoring this metadata exceeds the benefit of retaining frequently used metadata in the cache image. When implemented, the entry_ageout should address this problem. In the interim, not requesting a cache image every n file close/open cycles may be an acceptable work around. The choice of n will be driven by application behavior, but n = 10 seems a good starting point.

Parameters:

hid_t plist_id IN: File access property list identifier

H5AC_cache_image_config_t * config_ptr

IN: Pointer to metadata cache image configuration values

Returns:

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

Fortran Interface:

None

See Also:

H5Pget_mdc_image_config

History:

Release	Change
1.10.1	C function introduced with this release.

Last modified: 7 December 2015

Name: H5Pset_mdc_log_options

Signature:

herr_t H5Pset_mdc_log_options(
              hid_t fapl_id, 
              hbool_t is_enabled, 
              char *location, 
              hbool_t start_on_access
        )

Purpose:

Sets metadata cache logging options.

Description:

The log format is described in the Metadata Cache Logging document.

Notes:

Logging is disabled by default.

When enabled and currently logging, the overhead of the logging feature will almost certainly be significant.

The log file is currently manipulated using the C standard library’s buffered I/O calls (for example, fprintf) regardless of the virtual file driver (VFD) used. Log events are flushed immediately after the write call.

On Windows, the location parameter must be an ASCII string since the Windows standard C library’s I/O functions cannot handle UTF-8 file names.

The log file will be created when the HDF5 file is opened or created regardless of the value of the start_on_access parameter. The log file will stay open as long as the HDF5 file is open.

Parameters:

`hid_t fapl_id`	IN: File access property list identifier.
`hbool_t is_enabled`	IN: Whether logging is enabled.
`char *location`	IN: Location of log in UTF-8/ASCII (file path/name) (On Windows, this must be ASCII).
`hbool_t start_on_access`	IN: Whether the logging will begin as soon as the file is opened or created.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran Interface:

None

See Also:

History:

Release	Change
1.10.0	C function introduced with this release.

Name: H5Pset_meta_block_size

Signature:

herr_t H5Pset_meta_block_size( hid_t fapl_id, hsize_t size )

Purpose:

Sets the minimum metadata block size.

Description:

H5Pset_meta_block_size sets the minimum size, in bytes, of metadata block allocations when H5FD_FEAT_AGGREGATE_METADATA is set by a VFL driver.

Each raw metadata block is initially allocated to be of the given size. Specific metadata objects (e.g., object headers, local heaps, B-trees) are then sub-allocated from this block.

The default setting is 2048 bytes, meaning that the library will attempt to aggregate metadata in at least 2K blocks in the file. Setting the value to 0 (zero) with this function will turn off metadata aggregation, even if the VFL driver attempts to use the metadata aggregation strategy.

Metadata aggregation reduces the number of small data objects in the file that would otherwise be required for metadata. The aggregated block of metadata is usually written in a single write action and always in a contiguous block, potentially significantly improving library and application performance.

Parameters:

hid_t fapl_id IN: File access property list identifier.

hsize_t size IN: Minimum size, in bytes, of metadata block allocations.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran90 Interface: h5pset_meta_block_size_f

SUBROUTINE h5pset_meta_block_size_f(plist_id, size, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list 
                                         ! identifier
  INTEGER(HSIZE_T), INTENT(IN) :: size   ! Metadata block size
  INTEGER, INTENT(OUT)       :: hdferr   ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pset_meta_block_size_f

History:

Release C

1.4.0 Function introduced in this release.

Last modified: 8 December 2015

Name:H5Pset_metadata_read_attempts

Signature:

herr_t H5Pset_metadata_read_attempts(
        hid_t plist_id, 
        unsigned attempts
        )

Purpose:

Sets the number of read attempts in a file access property list.

Motivation:

On a system that is not atomic, the library might possibly read inconsistent metadata with checksum when performing single-writer/multiple-reader (SWMR) operations for an HDF5 file. Upon encountering such situations, the library will try reading the metadata again to obtain consistent data. This routine provides the means to set the number of read attempts other than the library default.

Description:

H5Pset_metadata_read_attempts sets the number of reads that the library will try when reading checksummed metadata in an HDF5 file opened with SWMR access. When reading such metadata, the library will compare the checksum computed for the metadata just read with the checksum stored within the piece of checksum. When performing SWMR operations on a file, the checksum check might fail when the library reads data on a system that is not atomic. To remedy such situations, the library will repeatedly read the piece of metadata until the check passes or finally fails the read when the allowed number of attempts is reached.

The number of read attempts used by the library will depend on how the file is opened and whether the user sets the number of read attempts via this routine:

For a file opened with SWMR access:
- If the user sets the number of attempts to N, the library will use N.
- If the user does not set the number of attempts, the library will use the default for SWMR access (100).
For a file opened with non-SWMR access, the library will always use the default for non-SWMR access (1). The value set via this routine does not have any effect during non-SWMR access.

Parameters:

`hid_t plist_id`	IN: Identifier for a file access property list.
`unsigned attempts`	IN: The number of read attempts. Must be a value greater than 0.

Returns:

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

Failure Modes:

When the user sets the number of read attempts to 0.

When the input property list is not a file access property list.

When the library is unable to set the number of read attempts in the file access property list.

Example Usage:

The first example illustrates the case in setting the number of read attempts for a file opened with SWMR access.

    /* Create a copy of file access property list */
    fapl = H5Pcreate(H5P_FILE_ACCESS);

    /* Set the # of read attempts */
    H5Pset_metadata_read_attempts(fapl, 20);

    /* Open the file with SWMR access and the non-default file access property list */
    fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), fapl);

    /* Get the file's file access roperty list */
    file_fapl = H5Fget_access_plist(fid);

    /* Retrieve the # of read attempts from the file's file access property list */
    H5Pget_metadata_read_attempts(file_fapl, &attempts);

    /* 
     *	The value returned in "attempts" will be 20.
     *  The library will use 20 as the number of read attempts
     *  when reading checksummed metadata in the file 
     */

    /* Close the property list */
    H5Pclose(fapl);
    H5Pclose(file_fapl);

    /* Close the file */
    H5Fclose(fid);

The second example illustrates the case in setting the number of read attempts for a file opened with non-SWMR access. The value set in the file access property list does not have any effect.

    /* Create a copy of file access property list */
    fapl = H5Pcreate(H5P_FILE_ACCESS);

    /* Set the # of read attempts */
    H5Pset_metadata_read_attempts(fapl, 20);

    /* Open the file with SWMR access and the non-default file access property list */
    fid = H5Fopen(FILE, H5F_ACC_RDONLY, fapl);

    /* Get the file's file access roperty list */
    file_fapl = H5Fget_access_plist(fid);

    /* Retrieve the # of read attempts from the file's file access property list */
    H5Pget_metadata_read_attempts(file_fapl, &attempts);

    /* 
     *	The value returned in "attempts" will be 1 (default for non-SWMR access).
     *  The library will use 1 as the number of read attempts
     *  when reading checksummed metadata in the file 
     */

    /* Close the property lists */
    H5Pclose(fapl);
    H5Pclose(file_fapl);

    /* Close the file */
    H5Fclose(fid);

Fortran Interface:

None

See Also:

H5Pget_metadata_read_attempts

H5Fget_metadata_read_retries_info

History:

Release	Change
1.10.0	C function introduced with this release.

Name: H5Pset_multi_type

Signature:

herr_t H5Pset_multi_type ( hid_t fapl_id, H5FD_mem_t type )

Purpose:

Specifies type of data to be accessed via the MULTI driver, enabling more direct access.

Description:

H5Pset_multi_type sets the type of data property in the file access property list fapl_id.

This setting enables a user application to specify the type of data the application wishes to access so that the application can retrieve a file handle for low-level access to the particular member of a set of MULTI files in which that type of data is stored. The file handle is retrieved with a separate call to H5Fget_vfd_handle (or, in special circumstances, to H5FDget_vfd_handle; see Virtual File Layer and List of VFL Functions in HDF5 Technical Notes).

The type of data specified in type may be one of the following:

H5FD_MEM_SUPER Super block data

H5FD_MEM_BTREE B-tree data

H5FD_MEM_DRAW Dataset raw data

H5FD_MEM_GHEAP Global heap data

H5FD_MEM_LHEAP Local Heap data

H5FD_MEM_OHDR Object header data

This function is for use only when accessing an HDF5 file written as a set of files with the MULTI file driver.

Parameters:

hid_t fapl_id IN: File access property list identifier.

H5FD_mem_t type IN: Type of data to be accessed.

Returns:

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

Fortran90 Interface:

None.

History:

Release Change

1.6.0 C function introduced in this release.

Last modified: 26 October 2011

Name: H5Pset_nbit

Signature:

herr_t H5Pset_nbit( hid_t plist_id )

Purpose:

Sets up the use of the N-Bit filter.

Description:

H5Pset_nbit sets the N-Bit filter, H5Z_FILTER_NBIT, in the dataset creation property list plist_id.

The HDF5 user can create an N-Bit datatype by writing codes like:

hid_t nbit_datatype = H5Tcopy(H5T_STD_I32LE); H5Tset_precision(nbit_datatype, 16); H5Tset_offset(nbit_datatype, 4);

In memory, one value of the N-Bit datatype in the above example will be stored on a little-endian machine like this:

byte 3 byte 2 byte 1 byte 0 ???????? ????SPPP PPPPPPPP PPPP???? Note: S - sign bit, P - significant bit, ? - padding bit; For signed integer, the sign bit is included in the precision.

When data of the above datatype are stored on disk using N-bit filter, all padding bits are chopped off and only significant bits are stored. So, the values on disk will be something like:

1st value 2nd value SPPPPPPPPPPPPPPP SPPPPPPPPPPPPPPP ...

The N-Bit filter is used effectively for compressing data of an N-Bit datatype as well as a compound and an array datatype with N-Bit fields. However, the datatype classes of the N-Bit datatype or the N-Bit field of the compound datatype or the array datatype are limited to integer or floating-point.

The N-Bit filter supports complex situations where a compound datatype contains member(s) of compound datatype or an array datatype that has compound datatype as the base type. However, it does not support the situation where an array datatype has variable-length or variable-length string as its base datatype. But the filter does support the situation where variable-length or variable-length string is a member of a compound datatype.

For all other HDF5 datatypes such as time, string, bitfield, opaque, reference, enum, and variable length, the N-Bit filter allows them to pass through like an no-op.

Like other I/O filters supported by the HDF5 library, application using the N-Bit filter must store data with chunked storage.

By nature, the N-Bit filter should not be used together with other I/O filters.

Parameters:

hid_t plist_id IN: Dataset creation property list identifier.

Returns:

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

Fortran90 Interface: h5pset_nbit_f

Signature:

  SUBROUTINE h5pset_nbit_f(plist_id, hdferr)
    INTEGER(HID_T), INTENT(IN)  :: plist_id
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  plist_id - Dataset creation property list identifier.

Outputs:

  hdferr   - Returns 0 if successful and -1 if fails

History:

Release	Change
1.8.0	C function introduced in this release.
1.8.8	Fortran subroutine introduced in this release.

Name: H5Pset_nlinks

Signature:

herr_t H5Pset_nlinks( hid_t lapl_id, size_t nlinks )

Purpose:

Sets maximum number of soft or user-defined link traversals.

Description:

H5Pset_nlinks sets the maximum number of soft or user-defined link traversals allowed, nlinks, before the library assumes it has found a cycle and aborts the traversal. This value is set in the link access property list lapl_id.

Parameters:

hid_t `lapl_id`	IN: File access property list identifier
size_t `nlinks`	IN: Maximum number of links to traverse

Returns:

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

Fortran90 Interface: h5pset_nlinks_f

SUBROUTINE h5pset_nlinks_f(lapl_id, nlinks, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: lapl_id ! File access property list identifier
  INTEGER(SIZE_T), INTENT(IN) :: nlinks ! Maximum number of links to traverse
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pset_nlinks_f

History:

Release	C
1.8.0	Function introduced in this release.

Last modified: 2016

Name: H5Pset_page_buffer_size

Signature:


   herr_t H5Pset_page_buffer_size( 
     hid_t fapl_id, 
     size_t buf_size, 
     unsigned min_meta_perc, 
     unsigned min_raw_perc )

Purpose:

Sets the maximum size for the page buffer and the minimum percentage for metadata and raw data pages.

Description:

H5Pset_page_buffer_size sets buf_size, the maximum size in bytes of the page buffer. The default value is zero, meaning that page buffering is disabled. When a non-zero page buffer size is set, the library will enable page buffering if that size is larger or equal than a single page size if a paged file space strategy is enabled using the functions H5Pset_file_space_strategy() and H5Pset_file_space_page_size().

The page buffer layer captures all I/O requests before they are issued to the VFD and "caches" them in fixed sized pages. Once the total number of pages exceeds the page buffer size, the library evicts pages from the page buffer by writing them to the VFD. At file close, the page buffer is flushed writing all the pages to the file.

If a non-zero page buffer size is set, and the file space strategy is not set to paged or the page size for the file space strategy is larger than the page buffer size, the subsequent call to H5Fcreate() or H5Fopen() using the fapl_id will fail.

The function also allows setting the minimum percentage of pages for metadata and raw data to prevent a certain type of data to evict hot data of the other type.

Parameters:

`hid_t fapl_id`		IN: File access property list identifier
`size_t buf_size`		IN: Maximum size, in bytes, of the page buffer
`unsigned min_meta_perc`		IN: Minimum metadata percentage to keep in the page buffer before allowing pages containing metadata to be evicted (Default is 0)
`unsigned min_raw_perc`		IN: Minimum raw data percentage to keep in the page buffer before allowing pages containing raw data to be evicted (Default is 0)

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran Interface:

None

See Also:

History:

Release	Change
1.10.1	C function introduced with this release.

Name: H5Pset_preserve

Signature:

herr_t H5Pset_preserve(hid_t plist, hbool_t status )

Purpose:

Sets the dataset transfer property list status to 1 (TRUE) or 0 (FALSE).

Notice:

This function is deprecated as it no longer has any effect; compound datatype field preservation is now core functionality in the HDF5 Library.

Description:

H5Pset_preserve sets the dataset transfer property list status to 1 (TRUE) or 0 (FALSE).

When reading or writing compound datatypes and the destination is partially initialized and the read/write is intended to initialize the other members, one must set this property to TRUE. Otherwise the I/O pipeline treats the destination datapoints as completely uninitialized.

Parameters:

hid_t plist IN: Identifier for the dataset transfer property list.

hbool_t status IN: Status of for the dataset transfer property list (TRUE/FALSE).

Returns:

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

Fortran90 Interface: h5pset_preserve_f

SUBROUTINE h5pset_preserve_f(prp_id, flag, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id   ! Dataset transfer property 
                                         ! list identifier 
  LOGICAL, INTENT(IN)        :: flag     ! Status for the dataset 
                                         ! transfer property list 
  INTEGER, INTENT(OUT)       :: hdferr   ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pset_preserve_f

History:

Release Fortran90

1.6.0 The flag parameter has changed from INTEGER to LOGICAL to better match the C API.

Name: H5Pset_obj_track_times

Signature:

herr_t H5Pset_obj_track_times( hid_t ocpl_id, hbool_t track_times )

Purpose:

Sets the recording of times associated with an object.

Description:

H5Pset_obj_track_times sets a property in the object creation property list, ocpl_id, that governs the recording of times associated with an object.

If track_times is TRUE, time data will be recorded. If track_times is FALSE, time data will not be recorded.

Time data can be retrieved with H5Oget_info, which will return it in the H5O_info_t struct.

If times are not tracked, they will be reported as follows when queried:
12:00 AM UDT, Jan. 1, 1970
That date and time are commonly used to represent the beginning of the UNIX epoch.

Parameters:

hid_t ocpl_id IN: Object creation property list identifier

hbool_t track_times IN: Boolean value, TRUE or FALSE, specifying whether object times are to be tracked

Returns:

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

Fortran90 Interface: h5pset_obj_track_times_f

SUBROUTINE h5pset_obj_track_times_f(plist_id, flag, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist_id 
                                 ! Dataset creation property 
                                 ! list identifier 
  LOGICAL, INTENT(IN) :: flag    ! Object timestamp setting
  INTEGER, INTENT(OUT) :: hdferr ! Error code
                                 ! 0 on success and -1 on failure
END SUBROUTINE h5pset_obj_track_times_f

History:

Release	C
1.8.0	Function introduced in this release.

Last modified: 27 May 2016

Name: H5Pset_object_flush_cb

Signature:

herr_t H5Pset_object_flush_cb (
              hid_t fapl_id,  
              H5F_flush_cb_t func, 
              void *user_data
        )

Purpose:

Sets a callback function to invoke when an object flush occurs in the file.

Description:

H5Pset_object_flush_cb sets the callback function to invoke in the file access property list fapl_id whenever an object flush occurs in the file. Library objects are group, dataset, and committed datatype.

The callback function func must conform to the prototype defined below:

typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *user_data)

The parameters of the callback function, per the above prototyps, are defined as follows:

object_id is the identifier of the object which has just been flushed.
user_data is the user-defined input data for the callback function.

Parameters:

`hid_t fapl_id`	IN: Identifier for a file access property list.
`H5F_flush_cb_t func`	IN: The user-defined callback function.
`void *user_data`	IN: The user-defined input data for the callback function.

Returns:

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

Example Usage:

The example below illustrates the usage of this routine to set the callback function to invoke when an object flush occurs.

hid_t file_id, fapl_id;
hid_t dataset_id, dapl_id;
unsigned counter;

/* Create a copy of the file access property list *
fapl_id = H5Pcreate(H5P_FILE_ACCESS);

/* Set up the object flush property values */
/* flush_cb: callback function to invoke when an object flushes (see below) */
/* counter: user data to pass along to the callback function */
H5Pset_object_flush_cb(fapl_id, flush_cb, &counter);

/* Open the file */
file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);

/* Create a group */
gid = H5Gcreate2(fid, �group�, H5P_DEFAULT, H5P_DEFAULT_H5P_DEFAULT);

/* Open a dataset */ 
dataset_id = H5Dopen2(file_id, DATASET, H5P_DEFAULT);

/* The flush will invoke flush_cb() with counter */
H5Dflush(dataset_id);
/* counter will be equal to 1 */
:
:
:
/* The flush will invoke flush_cb() with counter */
H5Gflush(gid);
/* counter will be equal to 2 */
:
:
:

/* The callback function for object flush property */
static herr_t
flush_cb(hid_t obj_id, void *_udata)
{
    unsigned *flush_ct = (unsigned*)_udata;
    ++(*flush_ct);
    return 0;
}

Fortran Interface:

None

See Also:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 26 October 2011

Name: H5Pset_scaleoffset

Signature:

herr_t H5Pset_scaleoffset( hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor )

Purpose:

Sets up the use of the scale-offset filter.

Description:

H5Pset_scaleoffset sets the scale-offset filter, H5Z_FILTER_SCALEOFFSET, for a dataset.

Generally speaking, scale-offset compression performs a scale and/or offset operation on each data value and truncates the resulting value to a minimum number of bits (MinBits) before storing it. The current scale-offset filter supports integer and floating-point datatypes.

For an integer datatype, the parameter scale_type should be set to H5Z_SO_INT (2). The parameter scale_factor denotes MinBits. If the user sets it to H5Z_SO_INT_MINBITS_DEFAULT (0), the filter will calculate MinBits. If scale_factor is set to a positive integer, the filter does not do any calculation and just uses the number as MinBits. However, if the user gives a MinBits that is less than what would be generated by the filter, the compression will be lossy. Also, the MinBits supplied by the user cannot exceed the number of bits to store one value of the dataset datatype.

For a floating-point datatype, the filter adopts the GRiB data packing mechanism, which offers two alternate methods: E-scaling and D-scaling. Both methods are lossy compression. If the parameter scale_type is set to H5Z_SO_FLOAT_DSCALE (0), the filter will use the D-scaling method; if it is set to H5Z_SO_FLOAT_ESCALE (1), the filter will use the E-scaling method. Since only the D-scaling method is implemented, scale_type should be set to H5Z_SO_FLOAT_DSCALE or 0.

When the D-scaling method is used, the original data is "D" scaled — multiplied by 10 to the power of scale_factor, and the "significant" part of the value is moved to the left of the decimal point. Care should be taken in setting the decimal scale_factor so that the integer part will have enough precision to contain the appropriate informationof the data value. For example, if scale_factor is set to 2, the number 104.561 will be 10456.1 after "D" scaling. The last digit 1 is not "significant" and is thrown off in the process of rounding. The user should make sure that after "D" scaling and rounding, the data values are within the range that can be represented by the integer (same size as the floating-point type).

Valid values for scale_type are as follows:

H5Z_SO_FLOAT_DSCALE (0) Floating-point type, using variable MinBits method

H5Z_SO_FLOAT_ESCALE (1) Floating-point type, using fixed MinBits method

H5Z_SO_INT (2) Integer type

The meaning of scale_factor varies according to the value assigned to scale_type:

scale_type value scale_factor description

H5Z_SO_FLOAT_DSCALE Denotes the decimal scale factor for D-scaling and can be positive, negative or zero. This is the current implementation of the library.

H5Z_SO_FLOAT_ESCALE Denotes MinBits for E-scaling and must be a positive integer. This is not currently implemented by the library.

H5Z_SO_INT Denotes MinBits and it should be a positive integer or H5Z_SO_INT_MINBITS_DEFAULT (0). If it is less than 0, the library will reset it to 0 since it is not implemented.

Like other I/O filters supported by the HDF5 library, an application using the scale-offset filter must store data with chunked storage.

Parameters:

hid_t `plist_id`	IN: Dataset creation property list identifier.
H5Z_SO_scale_type_t `scale_type`	IN: Flag indicating compression method.
int `scale_factor`	IN: Parameter related to scale. Must be non-negative.

Returns:

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

Fortran90 Interface: h5pset_scaleoffset_f

Signature:

  SUBROUTINE h5pset_scaleoffset_f(plist_id, scale_type, scale_factor, hdferr)
    INTEGER(HID_T), INTENT(IN)  :: plist_id
    INTEGER       , INTENT(IN)  :: scale_type
    INTEGER       , INTENT(IN)  :: scale_factor
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  plist_id     - Dataset creation property list identifier.
  scale_type   - Flag indicating compression method. Valid values:
                    H5Z_SO_FLOAT_DSCALE_F
                    H5Z_SO_FLOAT_ESCALE_F
                    H5Z_SO_INT_F

  scale_factor - Parameter related to scale.

Outputs:

  hdferr       - Returns 0 if successful and -1 if fails

History:

Release	Change
1.8.0	C function introduced in this release.
1.8.8	Fortran90 subroutine introduced in this release.

Name: H5Pset_shared_mesg_index

Signature:

herr_t H5Pset_shared_mesg_index( hid_t fcpl_id, unsigned index_num, unsigned mesg_type_flags, unsigned min_mesg_size )

Purpose:

Configures the specified shared object header message index.

Description:

H5Pset_shared_mesg_index is used to configure the specified shared object header message index, setting the types of messages that may be stored in the index and the minimum size of each message.

fcpl_id specifies the file creation property list.

index_num specifies the index to be configured. index_num is zero-indexed, so in a file with three indexes, they will be numbered 0, 1, and 2.

mesg_type_flags and min_mesg_size specify, respectively, the types and minimum size of messages that can be stored in this index.

Valid message types are as follows:

     H5O_SHMESG_NONE_FLAG No shared messages
     H5O_SHMESG_SDSPACE_FLAG     Simple dataspace message
     H5O_SHMESG_DTYPE_FLAG Datatype message
     H5O_SHMESG_FILL_FLAG Fill value message
     H5O_SHMESG_PLINE_FLAG Filter pipeline message
     H5O_SHMESG_ATTR_FLAG Attribute message
     H5O_SHMESG_ALL_FLAG All message types; i.e., equivalent to the following:
(H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | H5O_SHMESG_ATTR_FLAG)

Parameters:

hid_t `fcpl_id`	IN: File creation property list identifier.
unsigned `index_num`	IN: Index being configured.
unsigned `mesg_type_flags`	IN: Types of messages that should be stored in this index.
unsigned `min_mesg_size`	IN: Minimum message size.

Returns:

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

Fortran90 Interface: h5pset_shared_mesg_index_f

SUBROUTINE h5pset_shared_mesg_index_f(fcpl_id, index_num, mesg_type_flags,    &
           min_mesg_size, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: fcpl_id  ! File creation property list
  INTEGER, INTENT(IN) :: index_num       ! Index being configured.
  INTEGER, INTENT(IN) :: mesg_type_flags ! Types of messages that should be 
                                         ! stored in this index.
  INTEGER, INTENT(IN) :: min_mesg_size   ! Minimum message size.
  INTEGER, INTENT(OUT) :: hdferr         ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pset_shared_mesg_index_f

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Pset_shared_mesg_nindexes

Signature:

herr_t H5Pset_shared_mesg_nindexes( hid_t plist_id, unsigned nindexes )

Purpose:

Sets number of shared object header message indexes.

Description:

H5Pset_shared_mesg_nindexes sets the number of shared object header message indexes in the specified file creation property list.

This setting determines the number of shared object header message indexes that will be available in files created with this property list. These indexes can then be configured with H5Pset_shared_mesg_index.

If nindexes is set to 0 (zero), shared object header messages are disabled in files created with this property list.

Parameters:

hid_t `plist_id`	IN: File creation property list
unsigned `nindexes`	IN: Number of shared object header message indexes to be available in files created with this property list

Returns:

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

Fortran90 Interface: h5pset_shared_mesg_nindexes_f

SUBROUTINE h5pset_shared_mesg_nindexes_f( plist_id, nindexes, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist_id ! File creation property list
  INTEGER, INTENT(IN) :: nindexes        ! Number of shared object header message
                                         ! indexes available in files created 
                                         ! WITH this property list
  INTEGER, INTENT(OUT) :: hdferr         ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pset_shared_mesg_nindexes_f

History:

Release	C
1.8.0	Function introduced in this release.

Last modified: 11 March 2013

Name: H5Pset_shared_mesg_phase_change

Signature:

herr_t H5Pset_shared_mesg_phase_change( hid_t fcpl_id, unsigned max_list, unsigned min_btree )

Purpose:

Sets shared object header message storage phase change thresholds.

Description:

H5Pset_shared_mesg_phase_change sets threshold values for storage of shared object header message indexes in a file. These phase change thresholds determine the point at which the index storage mechanism changes from a more compact list format to a more performance-oriented B-tree format, and vice-versa.

By default, a shared object header message index is initially stored as a compact list. When the number of messages in an index exceeds the threshold value of max_list, storage switches to a B-tree for improved performance. If the number of messages subsequently falls below the min_btree threshold, the index will revert to the list format.

If max_list is set to 0 (zero), shared object header message indexes in the file will be created as B-trees and will never revert to lists.

fcpl_id specifies the file creation property list.

Parameters:

hid_t `fcpl_id`	IN: File creation property list identifier
unsigned `max_list`	IN: Threshold above which storage of a shared object header message index shifts from list to B-tree
unsigned `min_btree`	IN: Threshold below which storage of a shared object header message index reverts to list format

Returns:

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

Fortran90 Interface:

None.

History:

Release	C
1.8.0	Function introduced in this release.

Name: H5Pset_shuffle

Signature:

herr_t H5Pset_shuffle(hid_t plist_id)

Purpose:

Sets up use of the shuffle filter.

Description:

H5Pset_shuffle sets the shuffle filter, H5Z_FILTER_SHUFFLE, in the dataset creation property list plist_id. �

The shuffle filter de-interlaces a block of data by reordering the bytes. All the bytes from one consistent byte position of each data element are placed together in one block; all bytes from a second consistent byte position of each data element are placed together a second block; etc. For example, given three data elements of a 4-byte datatype stored as 012301230123, shuffling will re-order data as 000111222333. This can be a valuable step in an effective compression algorithm because the bytes in each byte position are often closely related to each other and putting them together can increase the compression ratio.

As implied above, the primary value of the shuffle filter lies in its coordinated use with a compression filter; it does not provide data compression when used alone. When the shuffle filter is applied to a dataset immediately prior to the use of a compression filter, the compression ratio achieved is often superior to that achieved by the use of a compression filter without the shuffle filter.

Parameters:

hid_t plist_id IN: Dataset creation property list identifier.

Returns:

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

Fortran90 Interface: h5pset_shuffle_f

SUBROUTINE h5pset_shuffle_f(prp_id, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id      ! Property list identifier 
  INTEGER, INTENT(OUT)       :: hdferr      ! Error code
                                            ! 0 on success and -1 on failure
END SUBROUTINE h5pset_shuffle_f

History:

Release C

1.6.0 Function introduced in this release.

Last modified: 14 April 2010

Name: H5Pset_sieve_buf_size

Signature:

herr_t H5Pset_sieve_buf_size( hid_t fapl_id, size_t size )

Purpose:

Sets the maximum size of the data sieve buffer.

Description:

H5Pset_sieve_buf_size sets size, the maximum size in bytes of the data sieve buffer, which is used by file drivers that are capable of using data sieving.

The data sieve buffer is used when performing I/O on datasets in the file. Using a buffer which is large enough to hold several pieces of the dataset being read in for hyperslab selections boosts performance by quite a bit.

The default value is set to 64KB, indicating that file I/O for raw data reads and writes will occur in at least 64KB blocks. Setting the value to 0 with this API function will turn off the data sieving, even if the VFL driver attempts to use that strategy.

Internally, the library checks the storage sizes of the datasets in the file. It picks the smaller one between the size from the file access property and the size of the dataset to allocate the sieve buffer for the dataset in order to save memory usage.

Parameters:

hid_t fapl_id IN: File access property list identifier.

size_t size IN: Maximum size, in bytes, of data sieve buffer.

Returns:

Returns a non-negative value if successful. Otherwise returns a negative value.

Fortran90 Interface: h5pset_sieve_buf_size_f

SUBROUTINE h5pset_sieve_buf_size_f(plist_id, size, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list 
                                         ! identifier
  INTEGER(SIZE_T), INTENT(IN) :: size    ! Sieve buffer size 
  INTEGER, INTENT(OUT)       :: hdferr   ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pset_sieve_buf_size_f

History:

Release C

1.6.0 The size parameter has changed from type hsize_t to size_t.

1.4.0 Function introduced in this release.

Name: H5Pset_sizes

Signature:

herr_t H5Pset_sizes(hid_t plist, size_t sizeof_addr, size_t sizeof_size )

Purpose:

Sets the byte size of the offsets and lengths used to address objects in an HDF5 file.

Description:

H5Pset_sizes sets the byte size of the offsets and lengths used to address objects in an HDF5 file. This function is only valid for file creation property lists. Passing in a value of 0 for one of the sizeof_... parameters retains the current value. The default value for both values is the same as sizeof(hsize_t) in the library (normally 8 bytes). Valid values currently are 2, 4, 8 and 16.

Parameters:

hid_t plist IN: Identifier of property list to modify.

size_t sizeof_addr IN: Size of an object offset in bytes.

size_t sizeof_size IN: Size of an object length in bytes.

Returns:

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

Fortran90 Interface: h5pset_sizes_f

SUBROUTINE h5pset_sizes_f (prp_id, sizeof_addr, sizeof_size, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id       ! Property list identifier
  INTEGER(SIZE_T), INTENT(IN) :: sizeof_addr ! Size of an object offset 
                                             ! in bytes
  INTEGER(SIZE_T), INTENT(IN) :: sizeof_size ! Size of an object length 
                                             ! in bytes
  INTEGER, INTENT(OUT) :: hdferr             ! Error code
                                             ! 0 on success and -1 on failure
END SUBROUTINE h5pset_sizes_f

Name: H5Pset_small_data_block_size

Signature:

herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size )

Purpose:

Sets the size of a contiguous block reserved for small data.

Description:

H5Pset_small_data_block_size reserves blocks of size bytes for the contiguous storage of the raw data portion of small datasets. The HDF5 library then writes the raw data from small datasets to this reserved space, thus reducing unnecessary discontinuities within blocks of meta data and improving I/O performance.

A small data block is actually allocated the first time a qualifying small dataset is written to the file. Space for the raw data portion of this small dataset is suballocated within the small data block. The raw data from each subsequent small dataset is also written to the small data block until it is filled; additional small data blocks are allocated as required.

The HDF5 library employs an algorithm that determines whether I/O performance is likely to benefit from the use of this mechanism with each dataset as storage space is allocated in the file. A larger size will result in this mechanism being employed with larger datasets.

The small data block size is set as an allocation property in the file access property list identified by fapl_id.

Setting size to zero (0) disables the small data block mechanism.

Parameters:

hid_t fapl_id IN: File access property list identifier.

hsize_t size IN: Maximum size, in bytes, of the small data block.
The default size is 2048.

Returns:

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

Fortran90 Interface: h5pset_small_data_block_size_f

SUBROUTINE h5pset_small_data_block_size_f(plist_id, size, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: plist_id ! File access
                                         ! property list identifier
  INTEGER(HSIZE_T), INTENT(IN) :: size   ! Small raw data block size
  INTEGER, INTENT(OUT)       :: hdferr   ! Error code
                                         ! 0 on success and -1 on failure
END SUBROUTINE h5pset_small_data_block_size_f

History:

Release C

1.4.4 Function introduced in this release.

Last modified: 7 March 2013

Name: H5Pset_sym_k

Signature:

herr_t H5Pset_sym_k( hid_t fcpl_id, unsigned ik, unsigned lk )

Purpose:

Sets the size of parameters used to control the symbol table nodes.

Description:

H5Pset_sym_k sets the size of parameters used to control the symbol table nodes.

This function is valid only for file creation property lists. Passing in a value of zero (0) for one of the parameters retains the current value.

ik is one half the rank of a B-tree that stores a symbol table for a group. Internal nodes of the symbol table are on average 75% full. That is, the average rank of the tree is 1.5 times the value of ik. The HDF5 library uses (ik*2) as the maximum # of entries before splitting a B-tree node. Since only 2 bytes are used in storing # of entries for a B-tree node in an HDF5 file, (ik*2) cannot exceed 65536. The default value for ik is 16.

lk is one half of the number of symbols that can be stored in a symbol table node. A symbol table node is the leaf of a symbol table tree which is used to store a group. When symbols are inserted randomly into a group, the group's symbol table nodes are 75% full on average. That is, they contain 1.5 times the number of symbols specified by lk. The default value for lk is 4.

Parameters:

hid_t `fcpl_id`	IN: File creation property list identifier
unsigned `ik`	IN: Symbol table tree rank
unsigned `lk`	IN: Symbol table node size

Returns:

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

Fortran90 Interface: h5pset_sym_k_f

SUBROUTINE h5pset_sym_k_f (prp_id, ik, lk, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
  INTEGER, INTENT(IN) :: ik            ! Symbol table tree rank
  INTEGER, INTENT(IN) :: lk            ! Symbol table node size
  INTEGER, INTENT(OUT) :: hdferr       ! Error code
                                       ! 0 on success and -1 on failure
END SUBROUTINE h5pset_sym_k_f

History:

Release	C
1.6.4	`ik` parameter type changed to unsigned.
1.6.0	The `ik` parameter has changed from type int to unsigned.

Last modified: 16 July 2013

Name: H5Pset_szip

Signature:

herr_t H5Pset_szip(hid_t plist, unsigned int options_mask, unsigned int pixels_per_block)

Purpose:

Sets up use of the SZIP compression filter.

Description:

H5Pset_szip sets an SZIP compression filter, H5Z_FILTER_SZIP, for a dataset. SZIP is a compression method designed for use with scientific data.

Before proceeding, all users should review the “Limitations” section below.

Users familiar with SZIP outrside the HDF5 context may benefit from reviewing “Notes for Users Familiar with SZIP in Other Contexts” below.

In the text below, the term pixel refers to an HDF5 data element. This terminology derives from SZIP compression's use with image data, where pixel referred to an image pixel.

The SZIP bits_per_pixel value (see Notes, below) is automatically set, based on the HDF5 datatype. SZIP can be used with atomic datatypes that may have size of 8, 16, 32, or 64 bits. Specifically, a dataset with a datatype that is 8-, 16-, 32-, or 64-bit signed or unsigned integer; char; or 32- or 64-bit float can be compressed with SZIP. See Notes, below, for further discussion of the the SZIP bits_per_pixel setting.

SZIP options are passed in an options mask, options_mask, as follows.

Option	Description (Mutually exclusive; select one.)
`H5_SZIP_EC_OPTION_MASK`	Selects entropy coding method.
`H5_SZIP_NN_OPTION_MASK`	Selects nearest neighbor coding method.

The following guidelines can be used in determining which option to select:

The entropy coding method, the EC option specified by H5_SZIP_EC_OPTION_MASK, is best suited for data that has been processed. The EC method works best for small numbers.
The nearest neighbor coding method, the NN option specified by H5_SZIP_NN_OPTION_MASK, preprocesses the data then the applies EC method as above.

Other factors may affect results, but the above criteria provides a good starting point for optimizing data compression.

SZIP compresses data block by block, with a user-tunable block size. This block size is passed in the parameter pixels_per_block and must be even and not greater than 32, with typical values being 8, 10, 16, or 32. This parameter affects compression ratio; the more pixel values vary, the smaller this number should be to achieve better performance.

In HDF5, compression can be applied only to chunked datasets. If pixels_per_block is bigger than the total number of elements in a dataset chunk, H5Pset_szip will succeed but the subsequent call to H5Dcreate will fail; the conflict can be detected only when the property list is used.

To achieve optimal performance for SZIP compression, it is recommended that a chunk's fastest-changing dimension be equal to N times pixels_per_block where N is the maximum number of blocks per scan line allowed by the SZIP library. In the current version of SZIP, N is set to 128.

SZIP compression is an optional HDF5 filter.

Limitations:

SZIP compression cannot be applied to
     compound datatypes,
     array datatypes,
     variable-length datatypes,
     enumerations,
     or any other user-defined datatypes.
If an SZIP filter is set in a dataset creation property list used to create a dataset containing a non-allowed datatype, the call to H5Dcreate will fail; the conflict can be detected only when the property list is used.
Users should be aware that there are factors that affect one’s rights and ability to use SZIP compression. See the documents at SZIP Compression in HDF5 for important information regarding terms of use and the SZIP copyright notice, for further discussion of SZIP compression in HDF5, and for a list of SZIP-related references.

Parameters:

hid_t `plist`	IN: Dataset creation property list identifier.
unsigned int `options_mask`	IN: A bit-mask conveying the desired SZIP options. Valid values are `H5_SZIP_EC_OPTION_MASK` and `H5_SZIP_NN_OPTION_MASK`.
unsigned int `pixels_per_block`	IN: The number of pixels or data elements in each data block.

Returns:

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

Notes for Users Familiar with SZIP in Other Contexts:

The following notes are of interest primarily to those who have used SZIP compression outside of the HDF5 context.

In non-HDF5 applications, SZIP typically requires that the user application supply additional parameters:

pixels_in_object, the number of pixels in the object to be compressed
bits_per_pixel, the number of bits per pixel
pixels_per_scanline, the number of pixels per scan line

These values need not be independently supplied in the HDF5 environment as they are derived from the datatype and dataspace, which are already known. In particular, HDF5 sets pixels_in_object to the number of elements in a chunk and bits_per_pixel to the size of the element or pixel datatype. The following algorithm is used to set pixels_per_scanline:

If the size of a chunk's fastest-changing dimension, size, is greater than 4K, set pixels_per_scanline to 128 times pixels_per_block.
If size is less than 4K but greater than pixels_per_block, set pixels_per_scanline to the minimum of size and 128 times pixels_per_block.
If size is less than pixels_per_block but greater than the number elements in the chunk, set pixels_per_scanline to the minimum of the number elements in the chunk and 128 times pixels_per_block.

The HDF5 datatype may have precision that is less than the full size of the data element, e.g., an 11-bit integer can be defined using H5Tset_precision. To a certain extent, SZIP can take advantage of the precision of the datatype to improve compression:

If the HDF5 datatype size is 24-bit or less and the offset of the bits in the HDF5 datatype is zero (see H5Tset_offset or H5Tget_offset), the data is the in lowest N bits of the data element. In this case, the SZIP bits_per_pixel is set to the precision of the HDF5 datatype.
If the offset is not zero, the SZIP bits_per_pixel will be set to the number of bits in the full size of the data element.
If the HDF5 datatype precision is 25-bit to 32-bit, the SZIP bits_per_pixel will be set to 32.
If the HDF5 datatype precision is 33-bit to 64-bit, the SZIP bits_per_pixel will be set to 64.

HDF5 always modifies the options mask provided by the user to set up usage of RAW_OPTION_MASK, ALLOW_K13_OPTION_MASK, and one of LSB_OPTION_MASK or MSB_OPTION_MASK, depending on endianness of the datatype.

Fortran90 Interface: h5pset_szip_f

SUBROUTINE h5pset_szip_f(prp_id, options_mask, pixels_per_block, hdferr) 
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id     
                                   ! Dataset creation property list identifier 
  INTEGER, INTENT(IN) :: options_mask      
                                   ! A bit-mask conveying the desired
                                   ! SZIP options
                                   ! Current valid values in Fortran are:
                                   !    H5_SZIP_EC_OM_F
                                   !    H5_SZIP_NN_OM_F
  INTEGER, INTENT(IN) :: pixels_per_block  
                                   ! The number of pixels or data elements 
                                   ! in each data block
  INTEGER, INTENT(OUT)  :: hdferr  ! Error code
                                   ! 0 on success and -1 on failure
END SUBROUTINE h5pset_szip_f

History:

Release C

1.6.0 Function introduced in this release.

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.

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.

Name: H5Pset_userblock

Signature:

herr_t H5Pset_userblock(hid_t plist, hsize_t size )

Purpose:

Sets user block size.

Description:

H5Pset_userblock sets the user block size of a file creation property list. The default user block size is 0; it may be set to any power of 2 equal to 512 or greater (512, 1024, 2048, etc.).

Parameters:

hid_t plist IN: Identifier of property list to modify.

hsize_t size IN: Size of the user-block in bytes.

Returns:

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

Fortran90 Interface: h5pset_userblock_f

SUBROUTINE h5pset_userblock_f (prp_id, size, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: prp_id  ! Property list identifier
  INTEGER(HSIZE_T), INTENT(IN) :: size  ! Size of the user-block in bytes
  INTEGER, INTENT(OUT) :: hdferr        ! Error code
                                        ! 0 on success and -1 on failure
END SUBROUTINE h5pset_userblock_f

Last modified: 22 April 2016

Name: H5Pset_virtual

Signature:

herr_t H5Pset_virtual(
        hid_t dcpl_id,
        hid_t vspace_id,
        const char *src_file_name,
        const char *src_dset_name,
        hid_t src_space_id
        )

Purpose:

Sets the mapping between virtual and source datasets.

Description:

H5Pset_virtual maps elements of the virtual dataset (VDS) described by the virtual dataspace identifier vspace_id to the elements of the source dataset described by the source dataset dataspace identifier src_space_id. The source dataset is identified by the name of the file where it is located, src_file_name, and the name of the dataset, src_dset_name.

Parameters:

`hid_t dcpl_id`		IN: The identifier of the dataset creation property list that will be used when creating the virtual dataset.
`hid_t vspace_id`		IN: The dataspace identifier with the selection within the virtual dataset applied, possibly an unlimited selection.
`const char *src_file_name`		IN: The name of the HDF5 file where the source dataset is located. The file might not exist yet. The name can be specified using a C-style `printf` statement as described below.
`const char *src_dset_name`		IN: The path to the HDF5 dataset in the file specified by `src_file_name`. The dataset might not exist yet. The dataset name can be specified using a C-style `printf` statement as described below.
`hid_t src_space_id`		IN: The source dataset’s dataspace identifier with a selection applied, possibly an unlimited selection

C-style printf Formatting Statements:

C-style printf formatting allows a pattern to be specified in the name of a source file or dataset. Strings for the file and dataset names are treated as literals except for the following substitutions:

`"%%"`		Replaced with a single `"%"` (percent) character.
`"%<d>b"`		Where `"<d>` is the virtual dataset dimension axis (0-based) and "`b`" indicates that the block count of the selection in that dimension should be used. The full expression (for example, "`%0b`") is replaced with a single numeric value when the mapping is evaluated at VDS access time. Example code for many source and virtual dataset mappings is available in the “Examples of Source to Virtual Dataset Mapping” chapter in “RFC: HDF5 Virtual Dataset” (see [1]).

If the printf form is used for the source file or dataset names, the selection in the source dataset’s dataspace must be fixed-size; for more information see [1].

Returns:

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

Fortran Interface: h5pset_virtual_f

Signature:

  SUBROUTINE h5pset_virtual_f(dcpl_id, vspace_id, src_file_name, 
                              src_dset_name, src_space_id, hdferr)
    INTEGER(HID_T), INTENT(IN)   :: dcpl_id
    INTEGER(HID_T), INTENT(IN)   :: vspace_id
    CHARACTER(LEN=*), INTENT(IN) :: src_file_name
    CHARACTER(LEN=*), INTENT(IN) :: src_dset_name
    INTEGER(HID_T), INTENT(IN)   :: src_space_id
    INTEGER, INTENT(OUT)         :: hdferr

Inputs:

  dcpl_id       - The identifier of the dataset creation property list that 
                  will be used when creating the virtual dataset.
  vspace_id     - The dataspace identifier with the selection within the virtual 
                  dataset applied, possibly an unlimited selection.
  src_file_name - The name of the HDF5 file where the source dataset is located.
  src_dset_name - The path to the HDF5 dataset in the file specified by 
                  src_file_name.
  src_space_id  - The source dataset's dataspace identifier with a selection 
                  applied, possibly an unlimited selection

Outputs:

  hdferr  - Returns 0 if successful and -1 if fails

See Also:

“Using HDF5 Virtual Datasets”

Supporting functions:

VDS functions:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 22 April 2016

Name: H5Pset_virtual_printf_gap

Signature:

herr_t H5Pset_virtual_printf_gap(
        hid_t dapl_id,
        hsize_t gap_size
        )

Purpose:

Sets the maximum number of missing source files and/or datasets with the printf-style names when getting the extent of an unlimited virtual dataset.

Description:

H5Pset_virtual_printf_gap sets the access property list for the virtual dataset, dapl_id, to instruct the library to stop looking for the mapped data stored in the files and/or datasets with the printf-style names after not finding gap_size files and/or datasets. The found source files and datasets will determine the extent of the unlimited virtual dataset with the printf-style mappings.

Consider the following examples where the regularly spaced blocks of a virtual dataset are mapped to datasets with the names d-1, d-2, d-3, ..., d-N, ... :

If the dataset d-2 is missing and gap_size is set to 0, then the virtual dataset will contain only data found in d-1.
If d-2 and d-3 are missing and gap_size is set to 2, then the virtual dataset will contain the data from d-1, d-3, ..., d-N, ... . The blocks that are mapped to d-2 and d-3 will be filled according to the virtual dataset’s fill value setting.

Parameters:

`hid_t dapl_id`		IN: Dataset access property list identifier for the virtual dataset
`hsize_t gap_size`		IN: Maximum number of files and/or datasets allowed to be missing for determining the extent of an unlimited virtual dataset with printf-style mappings (Default value: `0`)

Returns:

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

Fortran Interface: h5pset_virtual_printf_gap_f

Signature:

  SUBROUTINE h5pset_virtual_printf_gap_f(dapl_id, gap_size, hdferr)
    INTEGER(HID_T)  , INTENT(IN)  :: dapl_id
    INTEGER(HSIZE_T), INTENT(IN)  :: gap_size
    INTEGER         , INTENT(OUT) :: hdferr

Inputs:

  dapl_id  - Dataset access property list identifier for the virtual dataset.
  gap_size - Maximum number of files and/or datasets allowed to be missing 
             for determining the extent of an unlimited virtual dataset 
             with printf-style mappings.

Outputs:

  hdferr   - Returns 0 if successful and -1 if fails.

See Also:

“Using HDF5 Virtual Datasets”

Supporting functions:

VDS functions:

History:

Release	Change
1.10.0	C function introduced with this release.

Last modified: 22 April 2016

Name: H5Pset_virtual_view

Signature:

herr_t H5Pset_virtual_view(
        hid_t dapl_id,
        H5D_vds_view_t view
        )

Purpose:

Sets the view of the virtual dataset (VDS) to include or exclude missing mapped elements.

Description:

H5Pset_virtual_view takes the access property list for the virtual dataset, dapl_id, and the flag, view, and sets the VDS view according to the flag value.

If view is set to H5D_VDS_FIRST_MISSING, the view includes all data before the first missing mapped data. This setting provides a view containing only the continuous data starting with the dataset’s first data element. Any break in continuity terminates the view.

If view is set to H5D_VDS_LAST_AVAILABLE, the view includes all available mapped data.

Missing mapped data is filled with the fill value set in the VDS creation property list.

Parameters:

hid_t dapl_id IN: Identifier of the virtual dataset access property list.

H5D_vds_view_t view

IN: Flag specifying the extent of the data to be included in the view.
Valid values are:

`H5D_VDS_FIRST_MISSING`
	View includes all data before the first missing mapped data.
`H5D_VDS_LAST_AVAILABLE`
	View includes all available mapped data.

Returns:

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

Fortran Interface: h5pset_virtual_view_f

Signature:

  SUBROUTINE h5pset_virtual_view_f(dapl_id, view, hdferr)
    INTEGER(HID_T), INTENT(IN)  :: dapl_id
    INTEGER       , INTENT(IN)  :: view
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  dapl_id - Identifier of the virtual dataset access property list.
  view    - Flag specifying the extent of the data to be included in the view.
            Valid values are:
               H5D_VDS_FIRST_MISSING_F
               H5D_VDS_LAST_AVAILABLE_F

Outputs:

  hdferr   - Returns 0 if successful and -1 if fails.

See Also:

“Using HDF5 Virtual Datasets”

Supporting functions:

VDS functions: