Property List API Functions

H5Pset_sieve_buf_size @@ -271,6 +271,7 @@ See further notes in the description of each function. -

H5Pall_filters_avail
H5Pclose
H5Pclose_class @@ -294,7 +295,7 @@ See further notes in the description of each function.
H5Pget_class_name
H5Pget_class_parent
H5Pget_driver -
H5Pget_driver_info +
H5Pget_dxpl_mpio ||
H5Pget_dxpl_multi
H5Pget_edc_check @@ -311,11 +312,13 @@ See further notes in the description of each function.
H5Pget_fapl_stream
H5Pget_fclose_degree
H5Pget_fill_time +

H5Pget_fill_value
H5Pget_filter
H5Pget_filter_by_id @@ -355,11 +358,13 @@ See further notes in the description of each function.
H5Pset_dxpl_multi
H5Pset_edc_check
H5Pset_external +

H5Pset_family_offset
H5Pset_fapl_core
H5Pset_fapl_family @@ -395,26 +400,27 @@ See further notes in the description of each function.
H5Pset_userblock
H5Pset_vlen_mem_manager
H5Punregister +

- || Available only in the parallel HDF5 library. + || Available only in the parallel HDF5 library.

+
The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task -as the corresponding C function. The links below go to the C function +as the corresponding C function. The links below (electronic versions only) go to the C function descriptions, which serve as general descriptions for both. A button, under Non-C API(s) at the end of the C function description, opens an external browser window displaying the FORTRAN90-specific information. You will probably want to adjust the size and location of this external window so that both browser windows are visible and to facilitate moving easily between them. - +

@@ -589,66 +595,39 @@ facilitate moving easily between them.

+ +

Name: H5Pcreate +

Name: H5Pall_filters_avail

Signature: -

hid_t H5Pcreate(H5P_class_t type - ) +

htri_t H5Pall_filters_avail(hid_t dcpl_id)

Purpose: -

Creates a new property as an instance of a property list class. +

Verifies that all required filters are available.

Description: -

H5Pcreate creates a new property as an instance of some - property list class. The new property list is initialized - with default values for the specified class. The classes are: -

H5P_FILE_CREATE -: Properties for file creation. - See Files - in the HDF User's Guide - for details about the file creation properties. -
H5P_FILE_ACCESS -: Properties for file access. - See Files - in the HDF User's Guide - for details about the file creation properties. -
H5P_DATASET_CREATE -: Properties for dataset creation. - See Datasets - in the HDF User's Guide - for details about dataset creation properties. -
H5P_DATASET_XFER -: Properties for raw data transfer. - See Datasets - in the HDF User's Guide - for details about raw data transfer properties. -
H5P_MOUNT -: Properties for file mounting. - With this parameter, H5Pcreate - creates and returns a new mount property list - initialized with default values. -

- This property list must eventually be closed with - H5Pclose; - otherwise, errors are likely to occur. +

H5Pall_filters_avail verifies that all of the filters + set in the dataset creation property list dcpl_id are + currently available.

Parameters:
-
H5P_class_t type -
IN: The type of property list to create. +
hid_t dcpl_id +
IN: Dataset creation property list identifier.

Returns: -

Returns a property list identifier (plist) if successful; - otherwise Fail (-1). -

Non-C API(s): -

Returns TRUE if all filters are available + and FALSE if one or more is not currently available.
+ Returns FAIL, a negative value, on error. +

+ +

Name: H5Pclose @@ -679,38 +658,93 @@ facilitate moving easily between them. -->

- + +

Name: H5Pget_class +
Name: H5Pclose_class +
Signature: -: H5P_class_t H5Pget_class(hid_t plist - ) +; herr_t H5Pclose_class( + hid_t class + ) +
Purpose: -: Returns the property list class for a property list. +; Closes an existing property list class. +
Description: -: H5Pget_class returns the property list class for the - property list identified by the plist parameter. - Valid property list classes are defined in the description of - H5Pcreate. +; Removes a property list class from the library. + +
+ Existing property lists of this class will continue to exist, + but new ones are not able to be created. +
Parameters: -
-
hid_t plist -
IN: Identifier of property list to query. -
+
+ + + +
hid_t class IN: Property list class to close
+
Returns: -: Returns a property list class if successful. - Otherwise returns H5P_NO_CLASS (-1). -
Non-C API(s): -: - +; Success: a non-negative value +; Failure: a negative value + +
Non-C APIs: +: +

+ + +

Name: H5Pclose_list + +
Signature: +: herr_t H5Pclose_list( + hid_t plist + ) + +
Purpose: +: Closes a property list. + +
Description: +: H5Pclose_list closes a property list. + +
+ If a close callback exists for the property list class, + it is called before the property list is destroyed. + If close callbacks exist for any individual properties + in the property list, they are called after the class + close callback. + +
Parameters: +
+ + +
hid_t plist + IN: Property list to close
+ +
Returns: +: Success: a non-negative value +; Failure: a negative value + +
Non-C APIs: +: + +

+ +

Name: H5Pcopy @@ -741,84 +775,215 @@ facilitate moving easily between them. -->

- + +

Name: H5Pcreate_class +

Name: H5Pcopy_prop

Signature: -

hid_t H5Pcreate_class( - hid_t class, - const char *name, - H5P_cls_create_func_t create, - H5P_cls_copy_func_t copy, - H5P_cls_close_func_t close - ) +

herr_t H5Pcopy_prop( + hid_t dst_id, + hid_t src_id, + const char *name + )

Purpose: -

Creates a new property list class. +

Copies a property from one list or class to another.

Description: -

H5Pcreate_class registers a new property list class - with the library. - The new property list class can inherit from an existing property - list class or may be derived from the default "empty" class. - New classes with inherited properties from existing classes - may not remove those existing properties, only add or remove - their own class properties. -

H5Pcopy_prop copies a property from one property + list or class to another. + +

+ If a property is copied from one class to another, all the property + information will be first deleted from the destination class and + then the property information will be copied from the source class + into the destination class. - The create routine is called when a new property list - of this class is being created. - The H5P_cls_create_func_t callback function is defined - as follows: -

typedef herr_t

H5P_cls_create_func_t

hid_t

prop_id

void *

create_data

- The parameters to this callback function are defined as follows: -

hid_t `prop_id`	IN: The identifier of the property list being created
void * `create_data`	IN/OUT: User pointer to any class creation information needed

- The create routine is called after any registered - create function is called for each property value. - If the create routine returns a negative value, - the new list is not returned to the user and the - property list creation routine returns an error value. -

+ If a property is copied from one list to another, the property + will be first deleted from the destination list (generating a call + to the close callback for the property, if one exists) + and then the property is copied from the source list to the + destination list (generating a call to the copy + callback for the property, if one exists). - The copy routine is called when an existing property list - of this class is copied. - The H5P_cls_copy_func_t callback function - is defined as follows: -

typedef herr_t

H5P_cls_copy_func_t

hid_t

prop_id

void *

copy_data

- The parameters to this callback function are defined as follows: -

hid_t `prop_id`	IN: The identifier of the property list created by copying
void * `copy_data`	IN/OUT: User pointer to any class copy information needed

- The copy routine is called after any registered - copy function is called for each property value. - If the copy routine returns a negative value, the new list - is not returned to the user and thenproperty list copy routine returns - an error value. -

+ If the property does not exist in the class or list, this call is + equivalent to calling H5Pregister or H5Pinsert + (for a class or list, as appropriate) and the create + callback will be called in the case of the property being + copied into a list (if such a callback exists for the property). - The close routine is called when a property list of this +

Parameters: +
+ + + + + + + + + +
hid_t dst_id IN: Identifier of the destination property list or + class
hid_t src_id IN: Identifier of the source property list or class
const char *name IN: Name of the property to copy
+ +

Returns: +

Success: a non-negative value +

Failure: a negative value + +

Non-C APIs: +

+ +

+ + + +

Name: H5Pcreate +

Signature: +

hid_t H5Pcreate(H5P_class_t type + ) +

Purpose: +

Creates a new property as an instance of a property list class. +

Description: +

H5Pcreate creates a new property as an instance of some + property list class. The new property list is initialized + with default values for the specified class. The classes are: +

H5P_FILE_CREATE +: Properties for file creation. + See Files + in the HDF User's Guide + for details about the file creation properties. +
H5P_FILE_ACCESS +: Properties for file access. + See Files + in the HDF User's Guide + for details about the file creation properties. +
H5P_DATASET_CREATE +: Properties for dataset creation. + See Datasets + in the HDF User's Guide + for details about dataset creation properties. +
H5P_DATASET_XFER +: Properties for raw data transfer. + See Datasets + in the HDF User's Guide + for details about raw data transfer properties. +
H5P_MOUNT +: Properties for file mounting. + With this parameter, H5Pcreate + creates and returns a new mount property list + initialized with default values. +

+ This property list must eventually be closed with + H5Pclose; + otherwise, errors are likely to occur. +

Parameters: +
+
H5P_class_t type +
IN: The type of property list to create. +
+

Returns: +

Returns a property list identifier (plist) if successful; + otherwise Fail (-1). +

Non-C API(s): +

+ +

+ + + +

Name: H5Pcreate_class + +

Signature: +

hid_t H5Pcreate_class( + hid_t class, + const char *name, + H5P_cls_create_func_t create, + H5P_cls_copy_func_t copy, + H5P_cls_close_func_t close + ) + +

Purpose: +

Creates a new property list class. + +

Description: +

H5Pcreate_class registers a new property list class + with the library. + The new property list class can inherit from an existing property + list class or may be derived from the default "empty" class. + New classes with inherited properties from existing classes + may not remove those existing properties, only add or remove + their own class properties. +

+ + The create routine is called when a new property list + of this class is being created. + The H5P_cls_create_func_t callback function is defined + as follows: +

typedef herr_t

H5P_cls_create_func_t

hid_t

prop_id

void *

create_data

+ The parameters to this callback function are defined as follows: +

hid_t `prop_id`	IN: The identifier of the property list being created
void * `create_data`	IN/OUT: User pointer to any class creation information needed

+ The create routine is called after any registered + create function is called for each property value. + If the create routine returns a negative value, + the new list is not returned to the user and the + property list creation routine returns an error value. +

+ + The copy routine is called when an existing property list + of this class is copied. + The H5P_cls_copy_func_t callback function + is defined as follows: +

typedef herr_t

H5P_cls_copy_func_t

hid_t

prop_id

void *

copy_data

+ The parameters to this callback function are defined as follows: +

hid_t `prop_id`	IN: The identifier of the property list created by copying
void * `copy_data`	IN/OUT: User pointer to any class copy information needed

+ The copy routine is called after any registered + copy function is called for each property value. + If the copy routine returns a negative value, the new list + is not returned to the user and thenproperty list copy routine returns + an error value. +

+ + The close routine is called when a property list of this class is being closed. The H5P_cls_close_func_t callback function is defined @@ -876,7 +1041,8 @@ facilitate moving easily between them. -->

- + +

Name: H5Pcreate_list @@ -919,287 +1085,90 @@ facilitate moving easily between them. -->

- + +

Name: H5Pregister +

Name: H5Pequal

Signature: -

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

htri_t H5Pequal( + hid_t id1, + hid_t id2 + ) +

Purpose: -

Registers a permanent property with a property list class. - -

Description: -

H5Pregister 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. +

Compares two property lists or classes for equality. -

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

Description: +

H5Pequal compares two property lists or classes + to determine whether they are equal to one another. - 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: +

+ Either both id1 and id2 must be + property lists or both must be classes; comparing a list to a + class is an error. + +

Parameters:
- - - - - + + - - + +

const char *name IN: The name of the property being modified
size_t size IN: The size of the property in bytes
hid_t id1 IN: First property object to be compared

void *initial_value IN/OUT: The default value for the property being created, - which will be passed to H5Pregister
hid_t id2 IN: Second property object to be compared

- 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 (*H5P_prp_set_func_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. -
- Note: - The set callback function may be useful - to range check the value being set for the property - or may perform some tranformation 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 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. -
+

Returns: +

Success: TRUE (positive) if equal; FALSE (zero) if unequal +

Failure: a negative 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 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. -

Non-C APIs: +

+ +

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

+ + +

Name: H5Pexist - 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: +
Signature: +: htri_t H5Pexist( + hid_t id; + const char *name + ) + +
Purpose: +: Queries whether a property name exists in a property list + or class. + +
Description: +: H5Pexist determines whether a property exists + within a property list or class. + +
Parameters:
- - + + - - - - - - - +

hid_t prop_id IN: The identifier of the property list being - closed
hid_t id IN: Identifier for the property to query

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
IN: Name of property to check for

- 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. - -
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 +
Returns: +: Success: a positive value if the property exists in the + property object; zero if the property does not exist; Failure: a negative value
Non-C APIs: -

- + +

Name: H5Pinsert - +

Name: H5Pfill_value_defined

Signature: -

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

herr_t H5Pfill_value_defined(hid_t plist_id, + H5D_fill_value_t *status + )

Purpose: -

Registers a temporary property with a property list. - +

Determines whether fill value is defined.

Description: -

H5Pinsert 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. +

H5Pfill_value_defined determines whether a fill value + is defined in the dataset creation property list plist_id. +

+ Valid values returnrd in status are as follows: + +
+ H5D_FILL_VALUE_UNDEFINED + + Fill value is undefined. +
+ H5D_FILL_VALUE_DEFAULT + + Fill value is the library default. +
+ H5D_FILL_VALUE_USER_DEFINED + + Fill value is defined by the application. +
+

Note: +

H5Pfill_value_defined is designed for use in + concert with the dataset fill value properties functions + H5Pget_fill_value and H5Pget_fill_time. +

+ See H5Dcreate for + further cross-references. +

Parameters: +
+
hid_t plist_id +
IN: Dataset creation property list identifier. +
H5D_fill_value_t *status +
OUT: Status of fill value in property list. +
+

Returns: +

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

Non-C API(s): +

+ +

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

+ + +

Name: H5Pget - The set routine is called before a new value is copied - into the property. - The H5P_prp_set_func_t calback 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 tranformation 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. +

Signature: +

herr_t H5Pget( + hid_t plid, + const char *name, + void *value + ) -

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

typedef herr_t

H5P_prp_get_func_t

hid_t

prop_id

const char *

name

size_t

size

void *

value

- where the parameters to the callback function are: -

hid_t `prop_id`	IN: The identifier of the property list being queried
const char *	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. -

Purpose: +

Queries the value of a property. - 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

- where the parameters to the 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. -

Description: +

H5Pget retrieves a copy of the value for a property + in a property list. If there is a get callback routine + registered for this property, the copy of the value of the property + will first be passed to that routine and any changes to the copy of + the value will be used when returning the property value from this + routine. - 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 collback function is defined - as follows: -

typedef herr_t

H5P_prp_copy_func_t

const char *

name

size_t

size

void *

value

- where the parameters to the 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 ID 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. + This routine may be called for zero-sized properties with the + value set to NULL. The get routine + will be called with a NULL value if the callback exists. + +

+ The property name must exist or this routine will fail. + +

+ If the get callback routine returns an error, + value will not be modified.

Parameters:
- - + + - - - - + - - - - - - - - - - - - - - - - +

hid_t plid IN: Property list identifier to create temporary property - within
hid_t plid IN: Identifier of the property list to query

const char *name IN: Name of property to create
size_t size IN: Size of property in bytes
IN: Name of property to query

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
OUT: Pointer to a location to which to copy the value of + of the property

Returns: @@ -1467,7 +1287,7 @@ facilitate moving easily between them.

Failure: a negative value

Non-C APIs: -

- + +

Name: H5Pset - +

Name: H5Pget_alignment

Signature: -

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

herr_t H5Pget_alignment(hid_t plist, + hsize_t *threshold, + hsize_t *alignment + )

Purpose: -

Sets a property list value. - +

Retrieves the current settings for alignment properties from a + file access property list.

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

H5Pget_alignment retrieves the current settings for + alignment properties from a file access property list. + The threshold and/or alignment pointers + may be null pointers (NULL).

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

Non-C APIs: -

- +

hid_t plist +: IN: Identifier of a file access property list. +
hsize_t *threshold +: OUT: Pointer to location of return threshold value. +
hsize_t *alignment +: OUT: Pointer to location of return alignment value. +

Returns: +

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

Non-C API(s): +

- + +

Name: H5Pexist - +

Name: H5Pget_alloc_time

Signature: -

htri_t H5Pexist( - hid_t id; - const char *name - ) - +

herr_t H5Pget_alloc_time(hid_t plist_id, + H5D_alloc_time_t *alloc_time + )

Purpose: -

Queries whether a property name exists in a property list - or class. - +

Retrieves the timing for storage space allocation.

Description: -

H5Pexist determines whether a property exists - within a property list or class. - +

H5Pget_alloc_time retrieves the timing for allocating + storage space for a dataset's raw data. + This property is set in the dataset creation property list + plist_id. +

+ The timing setting is returned in fill_time as one of the + following values: + +
+ H5D_ALLOC_TIME_DEFAULT + + Uses the default allocation time, based on the dataset storage method.
+ See the fill_time description in + H5Pset_alloc_time for + default allocation times for various storage methods. +
+ H5D_ALLOC_TIME_EARLY + + All space is allocated when the dataset is created. +
+ H5D_ALLOC_TIME_INCR + + Space is allocated incrementally as data is written to the dataset. +
+ H5D_ALLOC_TIME_LATE + + All space is allocated when data is first written to the dataset. +
+

Note: +

H5Pget_alloc_time is designed to work in concert + with the dataset fill value and fill value write time properties, + set with the functions + H5Pget_fill_value and H5Pget_fill_time. +

Parameters: -
- - - - - - -
hid_t id IN: Identifier for the property to query
const char *name IN: Name of property to check for
- +
+
hid_t plist_id +
IN: Dataset creation property list identifier. +
H5D_alloc_time_t *alloc_time +
IN: When to allocate dataset storage space. +

Returns: -

Success: a positive value if the property exists in the - property object; zero if the property does not exist -

Failure: a negative value - -

Non-C APIs: -

- +

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

Non-C API(s): +

- + +

Name: H5Pget_size - +
Name: H5Pget_btree_ratios
Signature: -: int H5Pget_size( - hid_t id, - const char *name, - size_t *size - ) - +; herr_t H5Pget_btree_ratios(hid_t plist, + double *left, + double *middle, + double *right + )
Purpose: -: Queries the size of a property value in bytes. - +; Gets B-tree split ratios for a dataset transfer property list.
Description: -: H5Pget_size retrieves the size of a - property's value in bytes. This function operates on both - poperty lists and property classes - -
- Zero-sized properties are allowed and return 0. - - +; H5Pget_btree_ratios returns the B-tree split ratios + for a dataset transfer property list. +
+ The B-tree split ratios are returned through the non-NULL + arguments left, middle, and right, + as set by the H5Pset_btree_ratios function.
Parameters: -
- - - - - - - - - -
hid_t id IN: Identifier of property object to query
const char *name IN: Name of property to query
size_t *size OUT: Size of property in bytes
- +
+
hid_t plist +
IN: The dataset transfer property list identifier. +
double left +
OUT: The B-tree split ratio for left-most nodes. +
double right +
OUT: The B-tree split ratio for right-most nodes and lone nodes. +
double middle +
OUT: The B-tree split ratio for all other nodes. +
Returns: -: Success: a non-negative value -; Failure: a negative value - -
Non-C APIs: -: - +; Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +: +

- + +

Name: H5Pget_nprops +
Name: H5Pget_buffer +
Signature: +: hsize_t H5Pget_buffer(hid_t plist, + void **tconv, + void **bkg + ) +
Purpose: +: Reads buffer settings. +
Description: +: H5Pget_buffer reads values previously set + with H5Pset_buffer. +
Parameters: +
+
hid_t plist +
IN: Identifier for the dataset transfer property list. +
void **tconv +
OUT: Address of the pointer to application-allocated + type conversion buffer. +
void **bkg +
OUT: Address of the pointer to application-allocated + background buffer. +
+
Returns: +: Returns buffer size, in bytes, if successful; + otherwise 0 on failure. +
Non-C API(s): +: + +

+ + +

Name: H5Pget_cache
Signature: -: int H5Pget_nprops( - hid_t id, - size_t *nprops - ) +; herr_t H5Pget_cache(hid_t plist_id, + int *mdc_nelmts, + int *rdcc_nelmts, + size_t *rdcc_nbytes, + double *rdcc_w0 + ) +
Purpose: +: Queries the meta data cache and raw data chunk cache parameters. +
Description: +: H5Pget_cache retrieves the maximum possible + number of elements in the meta + data cache and raw data chunk cache, the maximum possible number of + bytes in the raw data chunk cache, and the preemption policy value. +
+ Any (or all) arguments may be null pointers, in which case the + corresponding datum is not returned. +
Parameters: +
+
hid_t plist_id +
IN: Identifier of the file access property list. +
int *mdc_nelmts +
IN/OUT: Number of elements (objects) in the meta data cache. +
int *rdcc_nelmts +
IN/OUT: Number of elements (objects) in the raw data chunk cache. +
size_t *rdcc_nbytes +
IN/OUT: Total size of the raw data chunk cache, in bytes. +
double *rdcc_w0 +
IN/OUT: Preemption policy. +
+
Returns: +: Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +: + +

+ + +

Name: H5Pget_chunk +
Signature: +: int H5Pget_chunk(hid_t plist, + int max_ndims, + hsize_t * dims + )
Purpose: -: Queries number of properties in property list or class. +; Retrieves the size of chunks for the raw data of a chunked layout dataset.
Description: -: H5Pget_nprops retrieves the number of properties in a - property list or class. - If a property class identifier is given, the number of registered - properties in the class is returned in nprops. - If a property list identifier is given, the current number of - properties in the list is returned in nprops. - +; H5Pget_chunk retrieves the size of chunks for the + raw data of a chunked layout dataset. + This function is only valid for dataset creation property lists. + At most, max_ndims elements of dims + will be initialized.
Parameters: -
- - - - - - -
hid_t id IN: Identifier of property object to query
size_t *nprops OUT: Number of properties in object
- +
+
hid_t plist +
IN: Identifier of property list to query. +
int max_ndims +
IN: Size of the dims array. +
hsize_t * dims +
OUT: Array to store the chunk dimensions. +
Returns: -: Success: a non-negative value -; Failure: a negative value - -
Non-C APIs: -: - +; Returns chunk dimensionality successful; + otherwise returns a negative value. +
Non-C API(s): +: +

+ + +

Name: H5Pget_class +
Signature: +: H5P_class_t H5Pget_class(hid_t plist + ) +
Purpose: +: Returns the property list class for a property list. +
Description: +: H5Pget_class returns the property list class for the + property list identified by the plist parameter. + Valid property list classes are defined in the description of + H5Pcreate. +
Parameters: +
+
hid_t plist +
IN: Identifier of property list to query. +
+
Returns: +: Returns a property list class if successful. + Otherwise returns H5P_NO_CLASS (-1). +
Non-C API(s): +: + +

+ +

Name: H5Pget_class_name @@ -1714,7 +1638,8 @@ facilitate moving easily between them. -->

- + +

Name: H5Pget_class_parent @@ -1751,591 +1676,381 @@ facilitate moving easily between them. -->

- + +

Name: H5Pisa_class - +

Name: H5Pget_driver

Signature: -

htri_t H5Pisa_class( - hid_t plist, - hid_t pclass - ) - +

hid_t H5Pget_driver( + hid_t plist_id + )

Purpose: -

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

Returns low-lever driver identifier.

Description: -

H5Pisa_class checks to determine whether a property list - is a member of the specified class. - +

H5Pget_driver returns the identifier of the + low-level file driver associated with the file access property list + or data transfer property list plist_id. +

+ Valid driver identifiers with the standard HDF5 library distribution + include the following: +

+           H5FD_CORE
+           H5FD_DPSS
+           H5FD_FAMILY
+           H5FD_GASS
+           H5FD_LOG
+           H5FD_MPIO
+           H5FD_MULTI
+           H5FD_SEC2
+           H5FD_STDIO
+           H5FD_STREAM

+ If a user defines and registers custom drivers or + if additional drivers are defined in an HDF5 distribution, + this list will be longer. +

+ The returned driver identifier is only valid as long as the + file driver remains registered.

Parameters: -
- - - - - - -
hid_t plist IN: Identifier of the property list
hid_t pclass IN: Identifier of the property class
- +
+
hid_t plist_id +
IN: File access or data transfer property list identifier. +

Returns: -

Success: TRUE (positive) if equal; FALSE (zero) if unequal -

Failure: a negative value - -

Non-C APIs: -

- -

Returns a valid low-level driver identifier if successful. + Otherwise returns a negative value. +

Non-C API(s): +

+ + + +

Returns a pointer to the struct containing + low-level driver information. + Otherwise returns NULL. +

+ NULL is also returned if no driver-specific properties + have been registered. + No error is pushed on the stack in this case. +

Non-C API(s): +

+--> + +

Name: H5Pequal - +

Name: H5Pget_dxpl_mpio

Signature: -

htri_t H5Pequal( - hid_t id1, - hid_t id2 - ) - +

herr_t H5Pget_dxpl_mpio( + hid_t dxpl_id, + H5FD_mpio_xfer_t *xfer_mode + )

Purpose: -

Compares two property lists or classes for equality. - +

Returns the data transfer mode.

Description: -

H5Pequal compares two property lists or classes - to determine whether they are equal to one another. - -

- Either both id1 and id2 must be - property lists or both must be classes; comparing a list to a - class is an error. - +

H5Pget_dxpl_mpio queries the data transfer mode + currently set in the data transfer property list dxpl_id. +

+ Upon return, xfer_mode contains the data transfer mode, + if it is non-null. +

+ H5Pget_dxpl_mpio is not a collective function.

Parameters: -
- - - - - - -
hid_t id1 IN: First property object to be compared
hid_t id2 IN: Second property object to be compared
- +
+
hid_t dxpl_id +
IN: Data transfer property list identifier. +
H5FD_mpio_xfer_t *xfer_mode +
OUT: Data transfer mode. +

Returns: -

Success: TRUE (positive) if equal; FALSE (zero) if unequal -

Failure: a negative value - -

Non-C APIs: -

- +

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

Non-C API(s): +

- + +

Name: H5Piterate - +
Name: H5Pget_dxpl_multi +
Signature: +: herr_t H5Pget_dxpl_multi( + hid_t dxpl_id, + const hid_t *memb_dxpl + ) +
+
Purpose: -: Iterates over properties in a property class or list. +; Returns multi-file data transfer property list information. +
Description: +: H5Pget_dxpl_multi returns the data transfer property list + information for the multi-file driver. +
Parameters: +
+
hid_t dxpl_id, +
IN: Data transfer property list identifier. +
const hid_t *memb_dxpl +
OUT: Array of data access property lists. +
+
Returns: +: Returns a non-negative value if successful. + Otherwise returns a negative value. + + +

+ + +

Name: H5Pget_edc_check
Signature: -: int H5Piterate( - hid_t id, - int * idx, - H5P_iterate_t iter_func, - void * iter_data - ) - +; H5Z_EDC_t H5Pget_edc_check(hid_t plist) +
Purpose: +: Determines whether error-detection is enabled for dataset reads.
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. - - (NOTE: iter_func was changed to - H5P_iterate_t in the preceding sentence. - Is this correct?) - -
- 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. - -
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 - - - - -

- +

H5Pget_edc_check queries the dataset transfer property + list plist to determine whether error detection + is enabled for data read operations. +

Parameters: +

hid_t plist +: IN: Dataset transfer property list identifier. +

Returns: +

Returns H5P_ENABLE_EDC or H5P_DISABLE_EDC + if successful; + otherwise returns a negative value. +

Non-C API(s): +

+ + + +

Name: H5Pcopy_prop - +

Name: H5Pget_external

Signature: -

herr_t H5Pcopy_prop( - hid_t dst_id, - hid_t src_id, - const char *name - ) - +

herr_t H5Pget_external(hid_t plist, + int idx, + size_t name_size, + char *name, + off_t *offset, + hsize_t *size + )

Purpose: -

Copies a property from one list or class to another. - +

Returns information about an external file.

Description: -

H5Pcopy_prop copies a property from one property - list or class to another. - -

- If a property is copied from one class to another, all the property - information will be first deleted from the destination class and - then the property information will be copied from the source class - into the destination class. - -

- If a property is copied from one list to another, the property - will be first deleted from the destination list (generating a call - to the close callback for the property, if one exists) - and then the property is copied from the source list to the - destination list (generating a call to the copy - callback for the property, if one exists). - -

- If the property does not exist in the class or list, this call is - equivalent to calling H5Pregister or H5Pinsert - (for a class or list, as appropriate) and the create - callback will be called in the case of the property being - copied into a list (if such a callback exists for the property). - +

H5Pget_external returns information about an external + file. The external file is specified by its index, idx, + which is a number from zero to N-1, where N is the value + returned by H5Pget_external_count. + At most name_size characters are copied into the + name array. If the external file name is + longer than name_size with the null terminator, the + return value is not null terminated (similar to strncpy()). +

+ If name_size is zero or name is the + null pointer, the external file name is not returned. + If offset or size are null pointers + then the corresponding information is not returned.

Parameters: -
- - - - - - - - - -
hid_t dst_id IN: Identifier of the destination property list or - class
hid_t src_id IN: Identifier of the source property list or class
const char *name IN: Name of the property to copy
- +
+
hid_t plist +
IN: Identifier of a dataset creation property list. +
int idx +
IN: External file index. +
size_t name_size +
IN: Maximum length of name array. +
char *name +
OUT: Name of the external file. +
off_t *offset +
OUT: Pointer to a location to return an offset value. +
hsize_t *size +
OUT: Pointer to a location to return the size of the + external file data. +

Returns: -

Success: a non-negative value -

Failure: a negative value - -

Non-C APIs: -

- +

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

Non-C API(s): +

- + +

Name: H5Premove - +

Name: H5Pget_external_count

Signature: -

herr_t H5Premove(plid, name) - hid_t plid; - const char *name - ) - +

int H5Pget_external_count(hid_t plist + )

Purpose: -

Removes a property from a property list. - +

Returns the number of external files for a dataset.

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 H5Pinsert) 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. - +

H5Pget_external_count returns the number of external files + for the specified dataset.

Parameters: -
- - - - - - -
hid_t plid IN: Identifier of the property list to modify
const char *name IN: Name of property to remove
- +
+
hid_t plist +
IN: Identifier of a dataset creation property list. +

Returns: -

Success: a non-negative value -

Failure: a negative value - -

Non-C APIs: -

- +

Returns the number of external files if successful; + otherwise returns a negative value. +

Non-C API(s): +

- + +

Name: H5Punregister - +
Name: H5Pget_family_offset
Signature: -: herr_t H5Punregister( - H5P_class_t class, - const char *name - ) - +; herr_t H5Pget_family_offset ( + hid_t fapl_id, + hsize_t *offset + )
Purpose: -: Removes a property from a property list class. - +; Retrieves a data offset from the file access property list.
Description: -: H5Punregister removes a property from a - property list class. - -
- Future property lists created of that class will not contain - this property; - existing property lists containing this property are not affected. - -
Parameters: -
- - - - - - -
H5P_class_t class IN: Property list class from which to remove - permanent property
const char *name IN: Name of property to remove
- -
Returns: -: Success: a non-negative value -; Failure: a negative value - -
Non-C APIs: -: - -

- - -

Name: H5Pclose_list - -
Signature: -: herr_t H5Pclose_list( - hid_t plist - ) - -
Purpose: -: Closes a property list. - -
Description: -: H5Pclose_list closes a property list. - -
- If a close callback exists for the property list class, - it is called before the property list is destroyed. - If close callbacks exist for any individual properties - in the property list, they are called after the class - close callback. - -
Parameters: -
- - -
hid_t plist - IN: Property list to close
- -
Returns: -: Success: a non-negative value -; Failure: a negative value - -
Non-C APIs: -: - -

- - -

Name: H5Pclose_class - -
Signature: -: herr_t H5Pclose_class( - hid_t class - ) - -
Purpose: -: Closes an existing property list class. - -
Description: -: Removes a property list class from the library. - -
- Existing property lists of this class will continue to exist, - but new ones are not able to be created. - -
Parameters: -
- - - -
hid_t class IN: Property list class to close
- -
Returns: -: Success: a non-negative value -; Failure: a negative value - -
Non-C APIs: -: - -

- - -

Name: H5Pget_version -

Signature: -

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

Purpose: -

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

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

H5Pget_family_offset retrieves the value of offset + from the file access property list fapl_id + so that the user application + can retrieve a file handle for low-level access to a particluar 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 data offset returned in offset is the offset + of the data in the HDF5 file that is stored on disk in the selected + member file in a family of files. +

+ 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 plist -
IN: Identifier of the file creation property list. -
int * super -
OUT: Pointer to location to return super block version number. -
int * freelist -
OUT: Pointer to location to return global freelist version number. -
int * stab -
OUT: Pointer to location to return symbol table version number. -
int * shhdr -
OUT: Pointer to location to return shared object header version number. +
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. +

- + +

Name: H5Pset_userblock +
Name: H5Pget_fapl_core
Signature: -: herr_t H5Pset_userblock(hid_t plist, - hsize_t size - ) +; herr_t H5Pget_fapl_core( + hid_t fapl_id, + size_t *increment, + hbool_t *backing_store + )
Purpose: -: Sets user block size. +; Queries core file driver properties.
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.). +; H5Pget_fapl_core queries the H5FD_CORE + driver properties as set by H5Pset_fapl_core.
Parameters:
-
hid_t plist -
IN: Identifier of property list to modify. -
hsize_t size -
IN: Size of the user-block in bytes. +
hid_t fapl_id +
IN: File access property list identifier. +
size_t *increment +
OUT: Size, in bytes, of memory increments. +
hbool_t *backing_store +
OUT: 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. +; Returns a non-negative value if successful. + Otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Pget_userblock +
Name: H5Pget_fapl_family
Signature: -: herr_t H5Pget_userblock(hid_t plist, - hsize_t * size - ) +; herr_t H5Pget_fapl_family ( + hid_t fapl_id, + hsize_t *memb_size, + hid_t *memb_fapl_id + )
Purpose: -: Retrieves the size of a user block. +; Returns file access property list information.
Description: -: H5Pget_userblock retrieves the size of a user block - in a file creation property list. +; H5Pget_fapl_family returns file access property list + for use with the family driver. + This information is returned through the output parameters.
Parameters:
-
hid_t plist -
IN: Identifier for property list to query. -
hsize_t * size -
OUT: Pointer to location to return user-block size. +
hid_t fapl_id +
IN: File access property list identifier. +
hsize_t *memb_size +
OUT: Size in bytes of each file member. +
hid_t *memb_fapl_id +
OUT: Identifier of file access property list for each + family member.
Returns:: Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Pset_sizes +
Name: H5Pget_fapl_gass
Signature: -: herr_t H5Pset_sizes(hid_t plist, - size_t sizeof_addr, - size_t sizeof_size - ) +; herr_t H5Pget_fapl_gass( + hid_t fapl_id, + GASS_Info *info + )
Purpose: -: Sets the byte size of the offsets and lengths used to address objects - in an HDF5 file. +; Retrieves GASS information.
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 same as sizeof(hsize_t) in the library - (normally 8 bytes). Valid values currently are 2, 4, - 8 and 16. +; If the file access property list fapl_id is set + for use of the H5FD_GASS driver, + H5Pget_fapl_gass returns the GASS_Info + object through the info pointer. +
+ The GASS_Info information is copied, so it is valid + only until the file access property list is modified or closed. +
Note: +: H5Pget_fapl_gass is an experimental function. + It is designed for use only when accessing files via the + GASS facility of the Globus environment. + For further information, see + http//www.globus.org/.
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. +
hid_t fapl_id, +
IN: File access property list identifier. +
GASS_Info *info +
OUT: Pointer to the GASS information structure.
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. +; Returns a non-negative value if successful. + Otherwise returns a negative value. +

- + +

Name: H5Pget_sizes +
Name: H5Pget_fapl_mpio
Signature: -: herr_t H5Pget_sizes(hid_t plist, - size_t * sizeof_addr, - size_t * sizeof_size - ) +; herr_t H5Pget_fapl_mpio( + hid_t fapl_id, + MPI_Comm *comm, + MPI_Info *info + )
Purpose: -: Retrieves the size of the offsets and lengths used in an HDF5 file. +; Returns MPI communicator information.
Description: -: H5Pget_sizes retrieves the size of the offsets - and lengths used in an HDF5 file. - This function is only valid for file creation property lists. +; If the file access property list is set to the H5FD_MPIO + driver, H5Pget_fapl_mpio returns the MPI communicator and + information through the comm and info + pointers, if those values are non-null. +
+ Neither comm nor info is copied, + so they are valid only until the file access property list + is either modified or closed.
Parameters:
-
hid_t plist -
IN: Identifier of property list to query. -
size_t * size -
OUT: Pointer to location to return offset size in bytes. -
size_t * size -
OUT: Pointer to location to return length size in bytes. +
hid_t fapl_id +
IN: File access property list identifier. +
MPI_Comm *comm +
OUT: MPI-2 communicator. +
MPI_Info *info +
OUT: MPI-2 info object.
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. +; Returns a non-negative value if successful. + Otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Pset_sym_k +

Name: H5Pget_fapl_mpiposix

Signature: -

herr_t H5Pset_sym_k(hid_t plist, - int ik, - int lk - ) +

herr_t H5Pget_fapl_mpiposix( + hid_t fapl_id, + MPI_Comm *comm + )

Purpose: -

Sets the size of parameters used to control the symbol table nodes. +

Returns MPI communicator information.

Description: -

H5Pset_sym_k sets the size of parameters used to - control the symbol table nodes. This function is only valid - for file creation property lists. Passing in a value of 0 for - one of the parameters retains the current value. -

- ik is one half the rank of a 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. -

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

If the file access property list is set to the H5FD_MPIO + driver, H5Pget_fapl_mpiposix returns + the MPI communicator through the comm + pointer, if those values are non-null. +

+ comm is not copied, so it is valid only + until the file access property list is either modified or closed.

Parameters:
-
hid_t plist -
IN: Identifier for property list to query. -
int ik -
IN: Symbol table tree rank. -
int lk -
IN: Symbol table node size. +
hid_t fapl_id +
IN: File access property list identifier. +
MPI_Comm *comm +
OUT: MPI-2 communicator.

Returns: -

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

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

- + +

Name: H5Pget_sym_k +
Name: H5Pget_fapl_multi
Signature: -: herr_t H5Pget_sym_k(hid_t plist, - int * ik, - int * lk - ) +; herr_t H5Pget_fapl_multi( + hid_t fapl_id, + const H5FD_mem_t *memb_map, + const hid_t *memb_fapl, + const char **memb_name, + const haddr_t *memb_addr, + hbool_t *relax + )
Purpose: -: Retrieves the size of the symbol table B-tree 1/2 rank - and the symbol table leaf node 1/2 size. +; Returns information about the multi-file access property list.
Description: -: H5Pget_sym_k retrieves the size of the - symbol table B-tree 1/2 rank and the symbol table leaf - node 1/2 size. This function is only valid for file creation - property lists. If a parameter valued is set to NULL, that - parameter is not retrieved. See the description for - H5Pset_sym_k for more - information. +; H5Pget_fapl_multi returns information about the + multi-file access property list.
Parameters:
-
hid_t plist -
IN: Property list to query. -
int * ik -
OUT: Pointer to location to return the symbol table's B-tree 1/2 rank. -
int * size -
OUT: Pointer to location to return the symbol table's leaf node 1/2 size. +
hid_t fapl_id +
IN: File access property list identifier. +
const H5FD_mem_t *memb_map +
OUT: Maps memory usage types to other memory usage types. +
const hid_t *memb_fapl +
OUT: Property list for each memory usage type. +
const char **memb_name +
OUT: Name generator for names of member files. +
const haddr_t *memb_addr +
OUT: +
hbool_t *relax +
OUT: Allows read-only access to incomplete file sets + when TRUE.
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. +; Returns a non-negative value if successful. + Otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Pset_istore_k +
Name: H5Pget_fapl_srb
Signature: -: herr_t H5Pset_istore_k(hid_t plist, - int ik - ) +; herr_t H5Pget_fapl_srb( + hid_t fapl_id, + SRB_Info *info + )
Purpose: -: Sets the size of the parameter used to control the - B-trees for indexing chunked datasets. +; Retrieves SRB information.
Description: -: H5Pset_istore_k sets the size of the parameter - used to control the B-trees for indexing chunked datasets. - This function is only valid 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. +; If the file access property list fapl_id is set + for use of the H5FD_SRB driver, + H5Pget_fapl_srb returns the SRB_Info + object through the info pointer. +
+ The SRB_Info information is copied, so it is valid + only until the file access property list is modified or closed. +
Note: +: H5Pset_fapl_gass is an experimental function. + It is designed for use only when accessing files via the + Storage Resource Broker (SRB). For further information, see + http//www.npaci.edu/Research/DI/srb/.
Parameters:
-
hid_t plist -
IN: Identifier of property list to query. -
int ik -
IN: 1/2 rank of chunked storage B-tree. +
hid_t fapl_id +
IN: File access property list identifier. +
SRB_Info *info +
OUT: Pointer to the SRB information structure.
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. +; Returns a non-negative value if successful. + Otherwise returns a negative value. +

- + +

Name: H5Pget_istore_k +
Name: H5Pget_fapl_stream
Signature: -: herr_t H5Pget_istore_k(hid_t plist, - int * ik - ) +; herr_t H5Pget_fapl_stream( + hid_t fapl_id, + H5FD_stream_fapl_t *fapl + )
Purpose: -: Queries the 1/2 rank of an indexed storage B-tree. +; Returns the streaming I/O driver settings.
Description: -: H5Pget_istore_k queries the 1/2 rank of - an indexed storage B-tree. - The argument ik may be the null pointer (NULL). - This function is only valid for file creation property lists. -
- See H5Pset_istore_k for details. +; H5Pget_fapl_stream returns the file access properties + set for the use of the streaming I/O driver. +
+ H5Pset_fapl_stream and H5Pget_fapl_stream + are not intended for use in a parallel environment.
Parameters:
-
hid_t plist -
IN: Identifier of property list to query. -
int * ik -
OUT: Pointer to location to return the chunked storage B-tree 1/2 rank. +
hid_t fapl_id +
IN: File access property list identifier. +
H5FD_stream_fapl_t *fapl +
OUT: The streaming I/O file access property list.
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. +; Returns a non-negative value if successful. + Otherwise returns a negative value. +

- -

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 very small amounts of raw - data. - The current limit is approximately 64K (HDF5 Release 1.6). -
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. -

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

Non-C API(s): -

- -

- - + +

Name: H5Pget_layout -

Signature: -

H5D_layout_t H5Pget_layout(hid_t plist) -

Purpose: -

Returns the layout of the raw data for a dataset. -

Description: -

H5Pget_layout returns the layout of the raw data for - a dataset. This function is only valid for dataset creation - property lists. - -

Parameters: +

Name: H5Pget_fclose_degree +

Signature: +

herr_t H5Pget_fclose_degree(hid_t fapl_id, + H5F_close_degree_t fc_degree) +

Purpose: +

Returns the file close degree. +

Description: +

H5Pget_fclose_degree returns the current setting of the file + close degree property fc_degree in the file access property list + fapl_id.� +

The value of fc_degree determines how aggressively H5Fclose + deals with objects within a file that remain open when H5Fclose + is called to close that file.� fc_degree can have any one of + four valid values as described above in H5Pset_fclose_degree. +

Parameters:
-
hid_t plist -
IN: Identifier for property list to query. +
hid_t fapl_id +
IN: File access property list identifier. +
H5F_close_degree_t fc_degree +
OUT: Pointer to a location to which to return the file close degree + property, the value of fc_degree.
-

Returns: -

Returns the layout type (a non-negative value) - of a dataset creation property list if successful. - Valid return values are: -

H5D_COMPACT -: Raw data is stored in the object header in the file. -
H5D_CONTIGUOUS -: Raw data is stored separately from the object header in - one contiguous chunk in the file. -
H5D_CHUNKED -: Raw data is stored separately from the object header in - chunks in separate locations in the file. -

- Otherwise, returns a negative value indicating faliure. +

Returns: +

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

Non-C API(s): -

- + +

Name: H5Pset_chunk +

Name: H5Pget_fill_time

Signature: -

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

herr_t H5Pget_fill_time(hid_t plist_id, + H5D_fill_time_t *fill_time )

Purpose: -

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

Retrieves the time when fill value are written to a 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. - As a side-effect, the layout of the dataset is changed to - H5D_CHUNKED, if it is not already. +

H5Pget_fill_time examines the dataset creation + property list plist_id to determine when fill values + are to be written to a dataset. +

+ Valid values returned in fill_time are as follows: + +
+ H5D_FILL_TIME_IFSET + + Fill values are written 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 + + Fill values are written to the dataset when storage space is allocated. +
+ H5D_FILL_TIME_NEVER + + Fill values are never written to the dataset. +
+

Note: +

H5Pget_fill_time is designed to work in coordination + with the dataset fill value and + dataset storage allocation time properties, retrieved with the functions + H5Pget_fill_value and H5Pget_alloc_time. +

Parameters:
-
hid_t plist -
IN: Identifier for property list to query. -
int ndims -
IN: The number of dimensions of each chunk. -
const hsize_t * dim -
IN: An array containing the size of each chunk. +
hid_t plist_id +
IN: Dataset creation property list identifier. +
H5D_fill_time_t *fill_time +
OUT: Setting for the timing of writing fill values to the dataset.
-

Returns: +

Returns:

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

Non-C API(s): -

- + +

Name: H5Pget_chunk +

Name: H5Pget_fill_value

Signature: -

int H5Pget_chunk(hid_t plist, - int max_ndims, - hsize_t * dims - ) +

herr_t H5Pget_fill_value(hid_t plist_id, + hid_t type_id, + void *value + )

Purpose: -

Retrieves the size of chunks for the raw data of a chunked layout dataset. - +

Retrieves a dataset fill value.

Description: -

H5Pget_chunk retrieves the size of chunks for the - raw data of a chunked layout dataset. - This function is only valid for dataset creation property lists. - At most, max_ndims elements of dims - will be initialized. +

H5Pget_fill_value returns the dataset + fill value defined in the dataset creation property list + plist_id. +

+ The fill value is returned through the value + pointer and will be converted to the datatype specified + by type_id. + This datatype may differ from the + fill value datatype in the property list, + but the HDF5 library must be able to convert between the + two datatypes. +

+ If the fill value is undefined, + i.e., set to NULL in the property list, + H5Pget_fill_value will return an error. + H5Pfill_value_defined should be used to + check for this condition before + H5Pget_fill_value is called. +

+ Memory must be allocated by the calling application. +

Note: +

H5Pget_fill_value is designed to coordinate + with the dataset storage allocation time and + fill value write time properties, which can be retrieved + with the functions H5Pget_alloc_time + and H5Pget_fill_time, respectively. +

Parameters:
-
hid_t plist -
IN: Identifier of property list to query. -
int max_ndims -
IN: Size of the dims array. -
hsize_t * dims -
OUT: Array to store the chunk dimensions. +
hid_t plist_id +
IN: Dataset creation property list identifier. +
hid_t type_id, +
IN: Datatype identifier for the value passed + via value. +
void *value +
OUT: Pointer to buffer to contain the returned fill value.

Returns: -

Returns chunk dimensionality successful; +

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

Non-C API(s): -

- + +

Name: H5Pset_alignment +

Name: H5Pget_filter

Signature: -

herr_t H5Pset_alignment(hid_t plist, - hsize_t threshold, - hsize_t alignment +

H5Z_filter_t H5Pget_filter(hid_t plist, + int filter_number, + unsigned int *flags, + size_t *cd_nelmts, + unsigned int *cd_values, + size_t namelen, + char name[] )

Purpose: -

Sets alignment properties of a file access property list. +

Returns information about a filter in a pipeline.

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

H5Pget_filter returns information about a + filter, specified by its filter number, in a filter pipeline, + specified by the property list with which it is associated.

- 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 plist is a dataset creation property list, + the pipeline is a permanent filter pipeline; + if plist is a dataset transfer property list, + the pipeline is a transient filter pipeline. +

+ On input, cd_nelmts indicates the number of entries + in the cd_values array, as allocated by the caller; + on return,cd_nelmts contains the number of values + defined by the filter. +

+ filter_number is a value between zero and + N-1, as described in + H5Pget_nfilters. + The function will return a negative value if the filter number + is out of range. +

+ If name is a pointer to an array of at least + namelen bytes, the filter name will be copied + into that array. The name will be null terminated if + namelen is large enough. The filter name returned + will be the name appearing in the file, the name registered + for the filter, or an empty string. +

+ The structure of the flags argument is discussed + in H5Pset_filter. +

Note: +

This function currently supports only the permanent filter + pipeline; plist must be a dataset creation property + list.

Parameters:

hid_t plist -
IN: Identifier for a file access property list. -
hsize_t threshold -
IN: Threshold value. - Must be non-negative. - 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. - Must be a positive value. +
IN: Property list identifier. +
int filter_number +
IN: Sequence number within the filter pipeline of + the filter for which information is sought. +
unsigned int *flags +
OUT: Bit vector specifying certain general properties + of the filter. +
size_t *cd_nelmts +
IN/OUT: Number of elements in cd_values. +
unsigned int *cd_values +
OUT: Auxiliary data for the filter. +
size_t namelen +
IN: Anticipated number of characters in name. +
char name[] +
OUT: Name of the filter.

Returns: -

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

Returns the filter identifier if successful: + + + + + + +

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

+ + Otherwise returns a negative value.

Non-C API(s): -

- + +

Name: H5Pget_alignment +

Name: H5Pget_filter_by_id

Signature: -

herr_t H5Pget_alignment(hid_t plist, - hsize_t *threshold, - hsize_t *alignment - ) +

herr_t H5Pget_filter_by_id( + hid_t plist_id, + H5Z_filter_t filter, + unsigned int *flags, + size_t *cd_nelmts, + unsigned int cd_values[], + size_t namelen, + char name[] + )

Purpose: -

Retrieves the current settings for alignment properties from a - file access property list. +

Returns information about the specified filter.

Description: -

H5Pget_alignment retrieves the current settings for - alignment properties from a file access property list. - The threshold and/or alignment pointers - may be null pointers (NULL). -

Parameters: +

H5Pget_filter_by_id returns information about the + filter specified in filter, a filter identifier. +

+ plist_id must identify a dataset creation property list + and filter will be in a permanent filter pipeline. +

+ The filter and flags parameters are used + in the same manner as described in the discussion of + H5Pset_filter. +

+ Aside from the fact that they are used for output, the + parameters cd_nelmts and cd_values[] are + used in the same manner as described in the discussion + of H5Pset_filter. + On input, the cd_nelmts parameter indicates the + number of entries in the cd_values[] array + allocated by the calling program; on exit it contains the + number of values defined by the filter. +

+ On input, the name_len parameter indicates the + number of characters allocated for the filter name + by the calling program in the array name[]. + On exit it contains the length in characters of name of the filter. + On exit name[] contains the name of the filter + with one character of the name in each element of the array. +

+ If the filter specified in filter is not + set for the property list, an error will be returned + and H5Pget_filter_by_id will fail. +

Parameters:
-
hid_t plist -
IN: Identifier of a file access property list. -
hsize_t *threshold -
OUT: Pointer to location of return threshold value. -
hsize_t *alignment -
OUT: Pointer to location of return alignment value. +
hid_t plist_id +
IN: Property list identifier. +
H5Z_filter_t filter +
IN: Filter identifier. +
unsigned int flags +
OUT: Bit vector specifying certain general properties + of the filter. +
size_t cd_nelmts +
IN/OUT: Number of elements in cd_values. +
const unsigned int cd_values[] +
OUT: Auxiliary data for the filter. +
size_t namelen +
IN/OUT: Length of filter name and + number of elements in name[]. +
char *name[] +
OUT: Name of filter.
-

Returns: +

Returns:

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

Non-C API(s): -

Non-C API(s): +

- + +

Name: H5Pset_external +

Name: H5Pget_gc_references

Signature: -

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

herr_t H5Pget_gc_references(hid_t plist, + unsigned *gc_ref )

Purpose: -

Adds an external file to the list of external files. +

Returns garbage collecting references setting.

Description: -

H5Pset_external adds an external file to the - list of external files. -

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

H5Pget_gc_references returns the current setting + for the garbage collection references property from + the specified file access property list. + The garbage collection references property is set + by H5Pset_gc_references.

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. +
IN: File access property list identifier. +
unsigned gc_ref +
OUT: Flag returning the state of reference garbage collection. + A returned value of 1 indicates that + garbage collection is on while + 0 indicates that garbage collection is off.

Returns:

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

Non-C API(s): -

- + +

Name: H5Pget_external_count +
Name: H5Pget_istore_k
Signature: -: int H5Pget_external_count(hid_t plist - ) +; herr_t H5Pget_istore_k(hid_t plist, + int * ik + )
Purpose: -: Returns the number of external files for a dataset. +; Queries the 1/2 rank of an indexed storage B-tree.
Description: -: H5Pget_external_count returns the number of external files - for the specified dataset. +; H5Pget_istore_k queries the 1/2 rank of + an indexed storage B-tree. + The argument ik may be the null pointer (NULL). + This function is only valid for file creation property lists. +
+ See H5Pset_istore_k for details.
Parameters:

hid_t plist -
IN: Identifier of a dataset creation property list. +
IN: Identifier of property list to query. +
int * ik +
OUT: Pointer to location to return the chunked storage B-tree 1/2 rank.
Returns: -: Returns the number of external files if successful; +; Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -

- + +

Name: H5Pget_external +

Name: H5Pget_layout

Signature: -

herr_t H5Pget_external(hid_t plist, - int idx, - size_t name_size, - char *name, - off_t *offset, - hsize_t *size - ) +

H5D_layout_t H5Pget_layout(hid_t plist)

Purpose: -

Returns information about an external file. +

Returns the layout of the raw data for a dataset.

Description: -

H5Pget_external returns information about an external - file. The external file is specified by its index, idx, - which is a number from zero to N-1, where N is the value - returned by H5Pget_external_count. - At most name_size characters are copied into the - name array. If the external file name is - longer than name_size with the null terminator, the - return value is not null terminated (similar to strncpy()). +

H5Pget_layout returns the layout of the raw data for + a dataset. This function is only valid for dataset creation + property lists.

- If name_size is zero or name is the - null pointer, the external file name is not returned. - If offset or size are null pointers - then the corresponding information is not returned. + 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 a dataset creation property list. -
int idx -
IN: External file index. -
size_t name_size -
IN: Maximum length of name array. -
char *name -
OUT: Name of the external file. -
off_t *offset -
OUT: Pointer to a location to return an offset value. -
hsize_t *size -
OUT: Pointer to a location to return the size of the - external file data. +
IN: Identifier for property list to query.

Returns: -

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

Returns the layout type (a non-negative value) + of a dataset creation property list if successful. + Valid return values are: +

H5D_COMPACT +: Raw data is stored in the object header in the file. +
H5D_CONTIGUOUS +: Raw data is stored separately from the object header in + one contiguous chunk in the file. +
H5D_CHUNKED +: Raw data is stored separately from the object header in + chunks in separate locations in the file. +

+ Otherwise, returns a negative value indicating faliure.

Non-C API(s): -

+ +

Name: H5Pset_fill_value +

Name: H5Pget_meta_block_size

Signature: -

herr_t H5Pset_fill_value(hid_t plist_id, - hid_t type_id, - const void *value +

herr_t H5Pget_meta_block_size( + hid_t fapl_id, + hsize_t *size )

Purpose: -

Sets the fill value for a dataset. +

Returns the current metadata block size setting.

Description: -

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

H5Pget_meta_block_size returns the current + minimum size, in bytes, of new metadata block allocations. + This setting is retrieved from the file access property list + fapl_id.

- 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. + This value is set by + H5Pset_meta_block_size + and is retrieved from the file access property list + fapl_id.

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. +
hid_t fapl_id +
IN: File access property list identifier. +
hsize_t *size +
OUT: Minimum size, in bytes, of metadata block allocations.

Returns: -

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

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

Non-C API(s): -

- + +

Name: H5Pget_fill_value +

Name: H5Pget_multi_type

Signature: -

herr_t H5Pget_fill_value(hid_t plist_id, - hid_t type_id, - void *value +

herr_t H5Pset_multi_type ( + hid_t fapl_id, + H5FD_mem_t *type )

Purpose: -

Retrieves a dataset fill value. +

Retrieves data type property for MULTI driver.

Description: -

H5Pget_fill_value returns the dataset - fill value defined in the dataset creation property list - plist_id. -

- The fill value is returned through the value - pointer and will be converted to the datatype specified - by type_id. - This datatype may differ from the - fill value datatype in the property list, - but the HDF5 library must be able to convert between the - two datatypes. -

- If the fill value is undefined, - i.e., set to NULL in the property list, - H5Pget_fill_value will return an error. - H5Pfill_value_defined should be used to - check for this condition before - H5Pget_fill_value is called. -

- Memory must be allocated by the calling application. -

Note: -

H5Pget_fill_value is designed to coordinate - with the dataset storage allocation time and - fill value write time properties, which can be retrieved - with the functions H5Pget_alloc_time - and H5Pget_fill_time, respectively. +

H5Pget_multi_type retrieves the data type setting from the + file access or data transfer property list fapl_id. + This enables a user application to specifiy 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 returned in type will be one of those + listed in the discussion of the type parameter in the the + description of the function + H5Pset_multi_type.

+ Use of this function is only appropriate for an HDF5 file written + as a set of files with the MULTI file driver.

Parameters:
-
hid_t plist_id -
IN: Dataset creation property list identifier. -
hid_t type_id, -
IN: Datatype identifier for the value passed - via value. -
void *value -
OUT: Pointer to buffer to contain the returned fill value. +
hid_t fapl_id +
IN: File access property list or data transfer property list identifier. +
H5FD_mem_t *type +
OUT: Type of data.

Returns:

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

- - - - - + +

Name: H5Pfill_value_defined +

Name: H5Pget_nfilters

Signature: -

herr_t H5Pfill_value_defined(hid_t plist_id, - H5D_fill_value_t *status - ) +

int H5Pget_nfilters(hid_t plist)

Purpose: -

Determines whether fill value is defined. +

Returns the number of filters in the pipeline.

Description: -

H5Pfill_value_defined determines whether a fill value - is defined in the dataset creation property list plist_id. +

H5Pget_nfilters returns the number of filters + defined in the filter pipeline associated with the property list + plist.

- Valid values returnrd in status are as follows: - -
- H5D_FILL_VALUE_UNDEFINED - - Fill value is undefined. -
- H5D_FILL_VALUE_DEFAULT - - Fill value is the library default. -
- H5D_FILL_VALUE_USER_DEFINED - - Fill value is defined by the application. -
+ In each pipeline, the filters are numbered from + 0 through N-1, where N is the value returned + by this function. During output to the file, the filters are + applied in increasing order; during input from the file, they + are applied in decreasing order. +

+ H5Pget_nfilters returns the number of filters + in the pipeline, including zero (0) if there + are none.

Note: -

H5Pfill_value_defined is designed for use in - concert with the dataset fill value properties functions - H5Pget_fill_value and H5Pget_fill_time. -

- See H5Dcreate for - further cross-references. +

This function currently supports only the permanent filter + pipeline; plist_id must be a dataset creation + property list.

Parameters:
-
hid_t plist_id -
IN: Dataset creation property list identifier. -
H5D_fill_value_t *status -
OUT: Status of fill value in property list. +
hid_t plist +
IN: Property list identifier.

Returns: -

Returns a non-negative value if successful; +

Returns the number of filters in the pipeline if successful; otherwise returns a negative value.

Non-C API(s): -

- + +

Name: H5Pset_fill_time +

Name: H5Pget_nprops +

Signature: -

herr_t H5Pset_fill_time(hid_t plist_id, - H5D_fill_time_t fill_time - ) +

int H5Pget_nprops( + hid_t id, + size_t *nprops + ) +

Purpose: -

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

Queries number of properties in property list or class. +

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

H5Pget_nprops retrieves the number of properties in a + property list or class. + If a property class identifier is given, the number of registered + properties in the class is returned in nprops. + If a property list identifier is given, the current number of + properties in the list is returned in nprops. +

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. -
+
+ + + + + + +
hid_t id IN: Identifier of property object to query
size_t *nprops OUT: Number of properties in object
+

Returns: -

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

Non-C API(s): -

- -

Success: a non-negative value +

Failure: a negative value +

Non-C APIs: +

+ + + +

Name: H5Pget_fill_time +

Name: H5Pget_preserve

Signature: -

herr_t H5Pget_fill_time(hid_t plist_id, - H5D_fill_time_t *fill_time - ) +

int H5Pget_preserve(hid_t plist)

Purpose: -

Retrieves the time when fill value are written to a dataset. +

Checks status of the dataset transfer property list.

Description: -

H5Pget_fill_time examines the dataset creation - property list plist_id to determine when fill values - are to be written to a dataset. -

- Valid values returned in fill_time are as follows: - -
- H5D_FILL_TIME_IFSET - - Fill values are written 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 - - Fill values are written to the dataset when storage space is allocated. -
- H5D_FILL_TIME_NEVER - - Fill values are never written to the dataset. -
-

Note: -

H5Pget_fill_time is designed to work in coordination - with the dataset fill value and - dataset storage allocation time properties, retrieved with the functions - H5Pget_fill_value and H5Pget_alloc_time. -

H5Pget_preserve checks the status of the + dataset transfer property list.

Parameters:
-
hid_t plist_id -
IN: Dataset creation property list identifier. -
H5D_fill_time_t *fill_time -
OUT: Setting for the timing of writing fill values to the dataset. +
hid_t plist +
IN: Identifier for the dataset transfer property list.

Returns: -

Returns a non-negative value if successful; +

Returns TRUE or FALSE if successful; otherwise returns a negative value.

Non-C API(s): -

- + +

Name: H5Pset_alloc_time +

Name: H5Pget_sieve_buf_size

Signature: -

herr_t H5Pset_alloc_time(hid_t plist_id, - H5D_alloc_time_t alloc_time - ) +

herr_t H5Pget_sieve_buf_size( + hid_t fapl_id, + hsize_t *size + ) +
+

Purpose: -

Sets the timing for storage space allocation. +

Returns maximum data sieve buffer size.

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

H5Pget_sieve_buf_size retrieves, size, + the current maximum size of the data sieve buffer.

- Timing is specified in fill_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. + This value is set by + H5Pset_sieve_buf_size + and is retrieved from the file access property list + fapl_id.

Parameters:
-
hid_t plist_id -
IN: Dataset creation property list identifier. -
H5D_alloc_time_t alloc_time -
IN: When to allocate dataset storage space. +
hid_t fapl_id +
IN: File access property list identifier. +
hsize_t *size +
IN: Maximum size, in bytes, of data sieve buffer.

Returns: -

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

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

Non-C API(s): -

- + +

Name: H5Pget_alloc_time +

Name: H5Pget_size +

Signature: -

herr_t H5Pget_alloc_time(hid_t plist_id, - H5D_alloc_time_t *alloc_time - ) +

int H5Pget_size( + hid_t id, + const char *name, + size_t *size + ) +

Purpose: -

Retrieves the timing for storage space allocation. +

Queries the size of a property value in bytes. +

Description: -

H5Pget_alloc_time retrieves the timing for allocating - storage space for a dataset's raw data. - This property is set in the dataset creation property list - plist_id. -

- The timing setting is returned in fill_time as one of the - following values: - -
- H5D_ALLOC_TIME_DEFAULT - - Uses the default allocation time, based on the dataset storage method.
- See the fill_time description in - H5Pset_alloc_time for - default allocation times for various storage methods. -
- H5D_ALLOC_TIME_EARLY - - All space is allocated when the dataset is created. -
- H5D_ALLOC_TIME_INCR - - Space is allocated incrementally as data is written to the dataset. -
- H5D_ALLOC_TIME_LATE - - All space is allocated when data is first written to the dataset. -
-

Note: -

H5Pget_alloc_time is designed to work in concert - with the dataset fill value and fill value write time properties, - set with the functions - H5Pget_fill_value and H5Pget_fill_time. -

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

Non-C API(s): -

- -

- - - +

H5Pget_size retrieves the size of a + property's value in bytes. This function operates on both + poperty lists and property classes + +

+ Zero-sized properties are allowed and return 0. + +

Parameters: +

hid_t `id`	IN: Identifier of property object to query
const char *`name`	IN: Name of property to query
size_t *`size`	OUT: Size of property in bytes

Returns: +

Success: a non-negative value +

Failure: a negative value +

Non-C APIs: +

+ + + +

Name: H5Pset_filter +

Name: H5Pget_sizes

Signature: -

herr_t H5Pset_filter(hid_t plist, - H5Z_filter_t filter, - unsigned int flags, - size_t cd_nelmts, - const unsigned int cd_values[] - ) +

herr_t H5Pget_sizes(hid_t plist, + size_t * sizeof_addr, + size_t * sizeof_size + )

Purpose: -

Adds a filter to the filter pipeline. +

Retrieves the size of the offsets and lengths used in an HDF5 file.

Description: -

H5Pset_filter adds the specified - filter and corresponding properties to the - end of an output filter pipeline. - If plist is a dataset creation property list, - the filter is added to the permanent filter pipeline; - if plist is a dataset transfer property list, - the filter is added to the transient filter pipeline. -

- 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. If this bit is - clear and a filter fails, then H5Dwrite - or H5Dread also fails. -

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

- -

- The filter parameter specifies the filter to be set. - Valid values 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 -

- -

- Also see H5Pset_edc_check and - H5Pset_filter_callback. - -

Notes: -

This function currently supports only the permanent filter - pipeline; plist must be a dataset creation - property list. -

- If multiple filters are set for a property list, they will be - applied to each chunk in the order in which they were set. +

H5Pget_sizes retrieves the size of the offsets + and lengths used in an HDF5 file. + This function is only valid for file creation property lists.

Parameters:

hid_t plist -
IN: Property list identifier. -
H5Z_filter_t filter -
IN: 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. +
IN: Identifier of property list to query. +
size_t * size +
OUT: Pointer to location to return offset size in bytes. +
size_t * size +
OUT: Pointer to location to return length size in bytes.

Returns:

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

Non-C API(s): -

- + +

Name: H5Pall_filters_avail +
Name: H5Pget_small_data_block_size
Signature: -: htri_t H5Pall_filters_avail(hid_t dcpl_id) +; herr_t H5Pget_small_data_block_size(hid_t fapl_id, + hsize_t *size + )
Purpose: -: Verifies that all required filters are available. +; Retrieves the current small data block size setting.
Description: -: H5Pall_filters_avail verifies that all of the filters - set in the dataset creation property list dcpl_id are - currently available. +; H5Pget_small_data_block_size retrieves the + current setting for the size of the small data block. +
+ If the returned value is zero (0), the small data + block mechanism has been disabled for the file.
Parameters:
-
hid_t dcpl_id -
IN: Dataset creation property list identifier. +
hid_t fapl_id +
IN: File access property list identifier . +
hsize_t *size +
OUT: Maximum size, in bytes, of the small data block.
Returns: -: Returns TRUE if all filters are available - and FALSE if one or more is not currently available.
- Returns FAIL, a negative value, on error. -

- + +

Name: H5Pget_nfilters +

Name: H5Pget_sym_k

Signature: -

int H5Pget_nfilters(hid_t plist) +

herr_t H5Pget_sym_k(hid_t plist, + int * ik, + int * lk + )

Purpose: -

Returns the number of filters in the pipeline. +

Retrieves the size of the symbol table B-tree 1/2 rank + and the symbol table leaf node 1/2 size.

Description: -

H5Pget_nfilters returns the number of filters - defined in the filter pipeline associated with the property list - plist. -

- In each pipeline, the filters are numbered from - 0 through N-1, where N is the value returned - by this function. During output to the file, the filters are - applied in increasing order; during input from the file, they - are applied in decreasing order. -

- H5Pget_nfilters returns the number of filters - in the pipeline, including zero (0) if there - are none. -

Note: -

This function currently supports only the permanent filter - pipeline; plist_id must be a dataset creation - property list. +

H5Pget_sym_k retrieves the size of the + symbol table B-tree 1/2 rank and the symbol table leaf + node 1/2 size. This function is only valid for file creation + property lists. If a parameter valued is set to NULL, that + parameter is not retrieved. See the description for + H5Pset_sym_k for more + information.

Parameters:

hid_t plist -
IN: Property list identifier. +
IN: Property list to query. +
int * ik +
OUT: Pointer to location to return the symbol table's B-tree 1/2 rank. +
int * size +
OUT: Pointer to location to return the symbol table's leaf node 1/2 size.

Returns: -

Returns the number of filters in the pipeline if successful; +

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

Non-C API(s): -

- + +

Name: H5Pget_filter +

Name: H5Pget_userblock

Signature: -

H5Z_filter_t H5Pget_filter(hid_t plist, - int filter_number, - unsigned int *flags, - size_t *cd_nelmts, - unsigned int *cd_values, - size_t namelen, - char name[] - ) +

herr_t H5Pget_userblock(hid_t plist, + hsize_t * size + )

Purpose: -

Returns information about a filter in a pipeline. +

Retrieves the size of a user block.

Description: -

H5Pget_filter returns information about a - filter, specified by its filter number, in a filter pipeline, - specified by the property list with which it is associated. -

- If plist is a dataset creation property list, - the pipeline is a permanent filter pipeline; - if plist is a dataset transfer property list, - the pipeline is a transient filter pipeline. -

- On input, cd_nelmts indicates the number of entries - in the cd_values array, as allocated by the caller; - on return,cd_nelmts contains the number of values - defined by the filter. -

- filter_number is a value between zero and - N-1, as described in - H5Pget_nfilters. - The function will return a negative value if the filter number - is out of range. -

- If name is a pointer to an array of at least - namelen bytes, the filter name will be copied - into that array. The name will be null terminated if - namelen is large enough. The filter name returned - will be the name appearing in the file, the name registered - for the filter, or an empty string. -

- The structure of the flags argument is discussed - in H5Pset_filter. -

Note: -

This function currently supports only the permanent filter - pipeline; plist must be a dataset creation property - list. +

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

Parameters:

hid_t plist -
IN: Property list identifier. -
int filter_number -
IN: Sequence number within the filter pipeline of - the filter for which information is sought. -
unsigned int *flags -
OUT: Bit vector specifying certain general properties - of the filter. -
size_t *cd_nelmts -
IN/OUT: Number of elements in cd_values. -
unsigned int *cd_values -
OUT: Auxiliary data for the filter. -
size_t namelen -
IN: Anticipated number of characters in name. -
char name[] -
OUT: Name of the filter. +
IN: Identifier for property list to query. +
hsize_t * size +
OUT: Pointer to location to return user-block size.

Returns: -

Returns the filter identifier if successful: - - - - - - -

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

- - Otherwise returns a negative value. +

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

Non-C API(s): -

- + +

Name: H5Pget_filter_by_id +

Name: H5Pget_version

Signature: -

herr_t H5Pget_filter_by_id( - hid_t plist_id, - H5Z_filter_t filter, - unsigned int *flags, - size_t *cd_nelmts, - unsigned int cd_values[], - size_t namelen, - char name[] - ) +

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

Purpose: -

Returns information about the specified filter. +

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

Description: -

H5Pget_filter_by_id returns information about the - filter specified in filter, a filter identifier. -

- plist_id must identify a dataset creation property list - and filter will be in a permanent filter pipeline. -

- The filter and flags parameters are used - in the same manner as described in the discussion of - H5Pset_filter. -

- Aside from the fact that they are used for output, the - parameters cd_nelmts and cd_values[] are - used in the same manner as described in the discussion - of H5Pset_filter. - On input, the cd_nelmts parameter indicates the - number of entries in the cd_values[] array - allocated by the calling program; on exit it contains the - number of values defined by the filter. -

- On input, the name_len parameter indicates the - number of characters allocated for the filter name - by the calling program in the array name[]. - On exit it contains the length in characters of name of the filter. - On exit name[] contains the name of the filter - with one character of the name in each element of the array. -

- If the filter specified in filter is not - set for the property list, an error will be returned - and H5Pget_filter_by_id will fail. -

Parameters: +

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_id -
IN: Property list identifier. -
H5Z_filter_t filter -
IN: Filter identifier. -
unsigned int flags -
OUT: Bit vector specifying certain general properties - of the filter. -
size_t cd_nelmts -
IN/OUT: Number of elements in cd_values. -
const unsigned int cd_values[] -
OUT: Auxiliary data for the filter. -
size_t namelen -
IN/OUT: Length of filter name and - number of elements in name[]. -
char *name[] -
OUT: Name of filter. +
hid_t plist +
IN: Identifier of the file creation property list. +
int * super +
OUT: Pointer to location to return super block version number. +
int * freelist +
OUT: Pointer to location to return global freelist version number. +
int * stab +
OUT: Pointer to location to return symbol table version number. +
int * shhdr +
OUT: Pointer to location to return shared object header version number.
-

Returns: +

Returns:

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

Non-C API(s): -

Non-C API(s): +

- + +

Name: H5Pmodify_filter +
Name: H5Pget_vlen_mem_manager
Signature: -: herr_t H5Pmodify_filter(hid_t plist, - H5Z_filter_t filter, - unsigned int flags, - size_t cd_nelmts, - const unsigned int cd_values[] +; herr_t H5Pget_vlen_mem_manager(hid_t plist, + H5MM_allocate_t *alloc, + void **alloc_info, + H5MM_free_t *free, + void **free_info )
Purpose: -: Modifies a filter in the filter pipeline. +; Gets the memory manager for variable-length datatype allocation in + H5Dread and H5Dvlen_reclaim.
Description: -: H5Pmodify_filter modifies the specified - filter in the filter pipeline. - plist must be a dataset creation property list - and the modified filter will be in a permanent filter pipeline. -
- The filter, 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. -
Note: -: This function currently supports only the permanent filter - pipeline; plist_id must be a dataset creation - property list. +; H5Pget_vlen_mem_manager is the companion function to + H5Pset_vlen_mem_manager, returning the parameters + set by that function.
Parameters:
-
hid_t plist_id -
IN: Property list identifier. -
H5Z_filter_t filter -
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. +
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. - - dt>Non-C API(s): -; Non-C API(s): +; -

- - - - - - - + +

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

- This filter is designed to be used in combination with - a compression 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. -

Non-C API(s): -

- -

- +

Name: H5Pinsert -

Name: H5Pset_fletcher32
Signature: -: herr_t H5Pset_fletcher32(hid_t plist) -
Purpose: -: Sets up use of the Fletcher32 checksum filter. -
Description: -: H5Pset_fletcher32 sets the Fletcher32 checksum filter - in the dataset creation property list plist. � -
Note: -: The initial error detection implementation supports - error detection for chunked datasets only. -
Parameters: -
-
hid_t plist -
IN: Dataset creation property list identifier. -
-
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -: - -

- +

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

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

Registers a temporary property with a property list. +

Description: -

H5Pset_szip sets a filter for the dataset - to SZIP compression, H5Z_FILTER_SZIP, - a compression method designed for use with scientific data. -

- SZIP options are passed in an options mask, options_mask, - as follows. -

- - +

H5Pinsert 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 routine is called before a new value is copied + into the property. + The H5P_prp_set_func_t calback 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: +

- - Option -	- - Description - - (Paired options are mutually exclusive.) -
- - `H5_SZIP_CHIP_OPTION_MASK` -	- - Compresses exactly as in hardware. -
- `H5_SZIP_ALLOW_K13_OPTION_MASK` -	- Allows k split = 13 compression mode. (Default) -
- - `H5_SZIP_EC_OPTION_MASK` -	- - Selects entropy coding method. (Default) -
- `H5_SZIP_NN_OPTION_MASK` -	- Selects nearest neighbor coding method. -

+ + + + + + + + + + + + +

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

- -

- - - - Some typical usages are as follows: -

One of the compression methods, - H5_SZIP_EC_OPTION_MASK or - H5_SZIP_NN_OPTION_MASK, is specified. -
The H5_SZIP_ALLOW_K13_OPTION_MASK is used. -

- Options are combined to create the options mask by means of - a logical OR operation. For example, the - option mask can be set as follows: -

- options_mask = H5_SZIP_NN_OPTION_MASK | H5_SZIP_ALLOW_K13_OPTION_MASK; - -

- 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, - with typical values being 8, 10, - 16, and 32. - The more pixel values vary, the smaller this number should be. - For optimal performance, the number of pixels per scan line - (i.e., the size of the fastest-changing dimension in the chunk) - should be an even multiple of the number of pixels per block. -

Notes: -

SZIP works only with datasets with 1 through 24 bits/pixel, - 32 pits/pixel, or 64 bits/pixel. -

- SZIP typically requires that the user application also supply - the number of pixels in the object to be compressed, - the number of bits per pixel, and 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. -

- Also see - SZIP Compression in HDF5 - for further discussion of SZIP compression in HDF5, - for important information regarding terms of use and - the SZIP copyright notice, - and for a list of SZIP-related references. - -

Parameters: -
-
hid_t plist -
IN: Dataset creation or dataset transfer property list - identifier. -
unsigned int options_mask -
IN: A bit-mask conveying the desired SZIP options. -
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. -

Non-C API(s): -

- - - +

Non-C APIs: +

- + +

Name: H5Pset_edc_check +

Name: H5Pisa_class +

Signature: -

herr_t H5Pset_edc_check(hid_t plist, - H5Z_EDC_t check) +

htri_t H5Pisa_class( + hid_t plist, + hid_t pclass + ) +

Purpose: -

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

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

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

H5Pisa_class checks to determine whether a property list + is a member of the specified class. +

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. -
+
+ + + + + + +
hid_t plist IN: Identifier of the property list
hid_t pclass IN: Identifier of the property class
+

Returns: -

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

Non-C API(s): -

- +

Success: TRUE (positive) if equal; FALSE (zero) if unequal +

Failure: a negative value + +

Non-C APIs: +

+ + +

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. + + (NOTE: iter_func was changed to + H5P_iterate_t in the preceding sentence. + Is this correct?) + +
+ 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. + +
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 + + + + +

+ +

Name: H5Pget_edc_check +
Name: H5Pmodify_filter
Signature: -: H5Z_EDC_t H5Pget_edc_check(hid_t plist) +; herr_t H5Pmodify_filter(hid_t plist, + H5Z_filter_t filter, + unsigned int flags, + size_t cd_nelmts, + const unsigned int cd_values[] + )
Purpose: -: Determines whether error-detection is enabled for dataset reads. +; Modifies a filter in the filter pipeline.
Description: -: H5Pget_edc_check queries the dataset transfer property - list plist to determine whether error detection - is enabled for data read operations. +; H5Pmodify_filter modifies the specified + filter in the filter pipeline. + plist must be a dataset creation property list + and the modified filter will be in a permanent filter pipeline. +
+ The filter, 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. +
Note: +: This function currently supports only the permanent filter + pipeline; plist_id must be a dataset creation + property list.
Parameters:
-
hid_t plist -
IN: Dataset transfer property list identifier. +
hid_t plist_id +
IN: Property list identifier. +
H5Z_filter_t filter +
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 H5P_ENABLE_EDC or H5P_DISABLE_EDC - if successful; +; Returns a non-negative value if successful; otherwise returns a negative value. -
Non-C API(s): -: Non-C API(s): +; -->

- + +

Name: H5Pset_filter_callback +

Name: H5Pregister +

Signature: -

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

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

Purpose: -

Sets user-defined filter callback function. +

Registers a permanent property with a property list class. +

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, - void *buf, - size_t buf_size, - void *op_data) - -

- where filter 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. - -

- - - - - - - - +

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

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

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

Non-C API(s): -

- -

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

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 -

Name: H5Pget_meta_block_size -
Signature: -: herr_t H5Pget_meta_block_size( - hid_t fapl_id, - hsize_t *size - ) -
Purpose: -: Returns the current metadata block size setting. -
Description: -: H5Pget_meta_block_size returns the current - minimum size, in bytes, of new metadata block allocations. - This setting is retrieved from the file access property list - fapl_id. -
- This value is set by - H5Pset_meta_block_size - and is retrieved from the file access property list - fapl_id. -
Parameters: -
-
hid_t fapl_id -
IN: File access property list identifier. -
hsize_t *size -
OUT: Minimum size, in bytes, of metadata block allocations. -
-
Returns: -: Returns a non-negative value if successful. - Otherwise returns a negative value. -
Non-C API(s): -: - +
Non-C APIs: +: +

- + +

Name: H5Pset_sieve_buf_size +

Name: H5Premove +

Signature: -

herr_t H5Pset_sieve_buf_size( - hid_t fapl_id, - hsize_t size - ) +

herr_t H5Premove(plid, name) + hid_t plid; + const char *name + ) +

Purpose: -

Sets the maximum size of the data sieve buffer. +

Removes a property from a property list. +

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

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 H5Pinsert) 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 fapl_id -
IN: File access property list identifier. -
hsize_t size -
IN: Maximum size, in bytes, of data sieve buffer. -
+
+ + + + + + +
hid_t plid IN: Identifier of the property list to modify
const char *name IN: Name of property to remove
+

Returns: -

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

Non-C API(s): -

- -

Success: a non-negative value +

Failure: a negative value +

Non-C APIs: +

+ + + +

Name: H5Pget_sieve_buf_size +
Name: H5Pset +
Signature: -: herr_t H5Pget_sieve_buf_size( - hid_t fapl_id, - hsize_t *size - ) -
-
+; herr_t H5Pset( + hid_t plid, + const char *name, + void *value) + ) +
Purpose: -: Returns maximum data sieve buffer size. +; Sets a property list value. +
Description: -: H5Pget_sieve_buf_size retrieves, size, - the current maximum size of the data sieve buffer. -
- This value is set by - H5Pset_sieve_buf_size - and is retrieved from the file access property list - fapl_id. -
Parameters: -
-
hid_t fapl_id -
IN: File access property list identifier. -
hsize_t *size -
IN: Maximum size, in bytes, of data sieve buffer. -
-
Returns: -: Returns a non-negative value if successful. - Otherwise returns a negative value. -
Non-C API(s): -: - -

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 +

Non-C APIs: +

+ + + +

Name: H5Pset_gc_references +

Name: H5Pset_alignment

Signature: -

herr_t H5Pset_gc_reference(hid_t plist, - unsigned gc_ref +

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

Purpose: -

Sets garbage collecting references flag. +

Sets alignment properties of a file access property list.

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

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.

- The default value for garbage collecting references is off. + 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.

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). +
IN: Identifier for a file access property list. +
hsize_t threshold +
IN: Threshold value. + Must be non-negative. + 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. + Must be a positive value.

Returns:

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

Non-C API(s): -

-->

+ +

Name: H5Pget_gc_references +

Name: H5Pset_alloc_time

Signature: -

herr_t H5Pget_gc_references(hid_t plist, - unsigned *gc_ref - ) +

herr_t H5Pset_alloc_time(hid_t plist_id, + H5D_alloc_time_t alloc_time + )

Purpose: -

Returns garbage collecting references setting. +

Sets the timing for storage space allocation.

Description: -

H5Pget_gc_references returns the current setting - for the garbage collection references property from - the specified file access property list. - The garbage collection references property is set - by H5Pset_gc_references. +

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 fill_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 -
IN: File access property list identifier. -
unsigned gc_ref -
OUT: Flag returning the state of reference garbage collection. - A returned value of 1 indicates that - garbage collection is on while - 0 indicates that garbage collection is off. +
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.

Non-C API(s): -

-->

- + +

Name: H5Pset_cache +

Name: H5Pset_btree_ratios

Signature: -

herr_t H5Pset_cache(hid_t plist_id, - int mdc_nelmts, - int rdcc_nelmts, - size_t rdcc_nbytes, - double rdcc_w0 +

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

Purpose: -

Sets the meta data cache and raw data chunk cache parameters. +

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

Description: -

H5Pset_cache sets - the number of elements (objects) in the meta data cache and - the number of elements, the total number of bytes, and - the preemption policy value in the raw data chunk cache. +

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 plist_id is a file access property list. - The number of elements (objects) in the meta data cache - and the raw data chunk cache are mdc_nelmts and - rdcc_nelmts, respectively. - The total size of the raw data chunk cache and the preemption policy - are rdcc_nbytes and rdcc_w0. + 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.

- Any (or all) of the H5Pget_cache pointer arguments - may be null pointers. + A node which is the only node at its level in the tree uses + the ratio right when it splits.

- The rdcc_w0 value should be between 0 and 1 inclusive and - indicates how much chunks that have been fully read are - favored for preemption. A value of zero means fully read - chunks are treated no differently than other chunks (the - preemption is strictly LRU) while a value of one means fully - read chunks are always preempted before other chunks. + All ratios are real numbers between 0 and 1, inclusive.

Parameters:
-
hid_t plist_id -
IN: Identifier of the file access property list. -
int mdc_nelmts -
IN: Number of elements (objects) in the meta data cache. -
int rdcc_nelmts -
IN: Number of elements (objects) in the raw data chunk cache. -
size_t rdcc_nbytes -
IN: Total size of the raw data chunk cache, in bytes. -
double rdcc_w0 -
IN: Preemption policy. +
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.

Non-C API(s): -

-->

- + +

Name: H5Pget_cache +

Name: H5Pset_buffer

Signature: -

herr_t H5Pget_cache(hid_t plist_id, - int *mdc_nelmts, - int *rdcc_nelmts, - size_t *rdcc_nbytes, - double *rdcc_w0 - ) +

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

Purpose: -

Queries the meta data cache and raw data chunk cache parameters. +

Sets type conversion and background buffers.

Description: -

H5Pget_cache retrieves the maximum possible - number of elements in the meta - data cache and raw data chunk cache, the maximum possible number of - bytes in the raw data chunk cache, and the preemption policy value. -

- Any (or all) arguments may be null pointers, in which case the - corresponding datum is not returned. +

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_id -
IN: Identifier of the file access property list. -
int *mdc_nelmts -
IN/OUT: Number of elements (objects) in the meta data cache. -
int *rdcc_nelmts -
IN/OUT: Number of elements (objects) in the raw data chunk cache. -
size_t *rdcc_nbytes -
IN/OUT: Total size of the raw data chunk cache, in bytes. -
double *rdcc_w0 -
IN/OUT: Preemption policy. +
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.

Non-C API(s): -

-->

- + +

Name: H5Pset_hyper_vector_size +

Name: H5Pset_cache

Signature: -

herr_t H5Pset_hyper_vector_size(hid_t dxpl_id, - size_t vector_size +

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

Purpose: -

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

Sets the meta data cache and raw data chunk cache parameters.

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

H5Pset_cache sets + the number of elements (objects) in the meta data cache and + the number of elements, the total number of bytes, and + the preemption policy value in the raw data chunk cache.

- The I/O vectors are hyperslab offset and length pairs - and are generated during hyperslab I/O. + The plist_id is a file access property list. + The number of elements (objects) in the meta data cache + and the raw data chunk cache are mdc_nelmts and + rdcc_nelmts, respectively. + The total size of the raw data chunk cache and the preemption policy + are rdcc_nbytes and rdcc_w0.

- 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). + Any (or all) of the H5Pget_cache pointer arguments + may be null pointers.

- 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. + The rdcc_w0 value should be between 0 and 1 inclusive and + indicates how much chunks that have been fully read are + favored for preemption. A value of zero means fully read + chunks are treated no differently than other chunks (the + preemption is strictly LRU) while a value of one means fully + read chunks are always preempted before other chunks.

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. +
hid_t plist_id +
IN: Identifier of the file access property list. +
int mdc_nelmts +
IN: Number of elements (objects) in the meta data cache. +
int rdcc_nelmts +
IN: Number of elements (objects) in the raw data chunk cache. +
size_t rdcc_nbytes +
IN: Total size of the raw data chunk cache, in bytes. +
double rdcc_w0 +
IN: Preemption policy.

Returns:

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

Non-C API(s): -

-->

- + +

Name: H5Pget_hyper_vector_size +
Name: H5Pset_chunk
Signature: -: herr_t H5Pget_hyper_vector_size(hid_t dxpl_id, - size_t *vector_size - ) +; herr_t H5Pset_chunk(hid_t plist, + int ndims, + const hsize_t * dim + )
Purpose: -: Retrieves number of I/O vectors to be read/written in hyperslab I/O. +; Sets the size of the chunks used to store a chunked layout dataset.
Description: -: H5Pset_hyper_vector_size retrieves 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 number of I/O vectors set in the dataset transfer property list - dxpl_id is returned in vector_size. - Unless the default value is in use, vector_size - was previously set with a call to - H5Pset_hyper_vector_size. +; 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. + As a side-effect, the layout of the dataset is changed to + H5D_CHUNKED, if it is not already.
Parameters:
-
hid_t dxpl_id -
IN: Dataset transfer property list identifier. -
size_t *vector_size -
OUT: Number of I/O vectors to accumulate in memory for I/O operations. +
hid_t plist +
IN: Identifier for property list to query. +
int ndims +
IN: The number of dimensions of each chunk. +
const hsize_t * dim +
IN: An array containing the size of each chunk.
-
Returns: +
Returns:: Returns a non-negative value if successful; otherwise returns a negative value. - -
Non-C API(s): -: -->

- - - - - + +

Name: H5Pset_btree_ratios +

Name: H5Pset_deflate

Signature: -

herr_t H5Pset_btree_ratios(hid_t plist, - double left, - double middle, - double right +

herr_t H5Pset_deflate(hid_t plist, + int level )

Purpose: -

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

Sets compression method and compression level.

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

H5Pset_deflate sets the compression method for a + dataset creation property list to H5D_COMPRESS_DEFLATE + and the compression level to level, which should + be a value from zero to nine, inclusive. + Lower compression levels are faster but result in less compression. + This is the same algorithm as used by the GNU gzip program.

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. +
IN: Identifier for the dataset creation property list. +
int level +
IN: Compression level.

Returns:

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

Non-C API(s): -

-->

+ +--> + +

Name: H5Pset_buffer +

Name: H5Pset_dxpl_mpio

Signature: -

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

herr_t H5Pset_dxpl_mpio( + hid_t dxpl_id, + H5FD_mpio_xfer_t xfer_mode + )

Purpose: -

Sets type conversion and background buffers. +

Sets data transfer mode.

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

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

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

Non-C API(s): -

-->

+ + +

Name: H5Pset_dxpl_multi +
Signature: +: herr_t H5Pset_dxpl_multi( + hid_t dxpl_id, + const hid_t *memb_dxpl + ) +
Purpose: +: Sets the data transfer property list for the multi-file driver. +
Description: +: H5Pset_dxpl_multi sets the data transfer property list + dxpl_id to use the multi-file driver for each + memory usage type memb_dxpl[]. +
+ H5Pset_dxpl_multi can only be used after + the member map has been set with H5Pset_fapl_multi. +
Parameters: +
+
hid_t dxpl_id, +
IN: Data transfer property list identifier. +
const hid_t *memb_dxpl +
IN: Array of data access property lists. +
+
Returns: +: Returns a non-negative value if successful. + Otherwise returns a negative value. + + +

+ +

Name: H5Pget_buffer +

Name: H5Pset_edc_check

Signature: -

hsize_t H5Pget_buffer(hid_t plist, - void **tconv, - void **bkg - ) +

herr_t H5Pset_edc_check(hid_t plist, + H5Z_EDC_t check)

Purpose: -

Reads buffer settings. +

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

Description: -

H5Pget_buffer reads values previously set - with H5Pset_buffer. +

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.

Parameters:

hid_t plist -
IN: Identifier for the dataset transfer property list. -
void **tconv -
OUT: Address of the pointer to application-allocated - type conversion buffer. -
void **bkg -
OUT: Address of the pointer to application-allocated - background buffer. +
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 buffer size, in bytes, if successful; - otherwise 0 on failure. +

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

Non-C API(s): -

-->

- + +

Name: H5Pset_small_data_block_size +

Name: H5Pset_external

Signature: -

herr_t H5Pset_small_data_block_size(hid_t fapl_id, +

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

Purpose: -

Sets the size of a contiguous block reserved for small data. +

Adds an external file to the list of external files.

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 IO 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 - IO 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. +

H5Pset_external adds an external file to the + list of external files.

- The small data block size is set as an allocation property in the - file access property list identified by fapl_id. + 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).

- Setting size to zero (0) disables the - small data block mechanism. + The size argument specifies 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.

Parameters:
-
hid_t fapl_id -
IN: File access property list identifier . +
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: Maximum size, in bytes, of the small data block. -
- The default size is 2048. +
IN: Number of bytes reserved in the file for the data.

Returns:

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

Non-C API(s): -

-->

- + +

Name: H5Pget_small_data_block_size +

Name: H5Pset_family_offset

Signature: -

herr_t H5Pget_small_data_block_size(hid_t fapl_id, - hsize_t *size - ) +

herr_t H5Pset_family_offset ( + hid_t fapl_id, + hsize_t offset + )

Purpose: -

Retrieves the current small data block size setting. +

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

Description: -

H5Pget_small_data_block_size retrieves the - current setting for the size of the small data block. -

- If the returned value is zero (0), the small data - block mechanism has been disabled for the file. +

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 particluar 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 *size -
OUT: Maximum size, in bytes, of the small data block. +
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 a negative value. + otherwise returns a negative value.

Non-C API(s): -

-->

- + +

Name: H5Pset_preserve +
Name: H5Pset_fapl_core
Signature: -: herr_t H5Pset_preserve(hid_t plist, - hbool_t status - ) +; herr_t H5Pset_fapl_core( + hid_t fapl_id, + size_t increment, + hbool_t backing_store + )
Purpose: -: Sets the dataset transfer property list status to TRUE or FALSE. +; Modifies the file access property list to use the + H5FD_CORE driver.
Description: -: H5Pset_preserve sets the - dataset transfer property list status to TRUE or FALSE. +; H5Pset_fapl_core modifies the file access property list + to use the H5FD_CORE driver.
- When reading or writing compound data types 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. -
Non-C API(s): -: - -

- - -

Name: H5Pget_preserve -

Signature: -

int H5Pget_preserve(hid_t plist) -

Purpose: -

Checks status of the dataset transfer property list. -

Description: -

H5Pget_preserve checks the status of the - dataset transfer property list. + 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. +

+ If 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. +

Note: +

There is currently no means for reading a file from disk then + using the H5FD_CORE driver to manipulate the file.

Parameters:
-
hid_t plist -
IN: Identifier for the dataset transfer property list. +
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 TRUE or FALSE if successful; - otherwise returns a negative value. +

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

Non-C API(s): -

-->

- - +

Name: H5Pset_compression +

Name: H5Pset_fapl_family

Signature: -

herr_t H5Pset_compression(hid_t plist, - H5Z_method_t method, - unsigned int flags, - size_t cd_size, - const void *client_data +

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

Purpose: -

Sets compression method. +

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

Description: -

H5Pset_compression sets the compression method - in a dataset creation property list. This is a catch-all - function for defining compression methods - and is intended to be called from a wrapper such as - H5Pset_deflate. The dataset creation property - list plist is adjusted to use the specified - compression method. The flags is an 8-bit vector - which is stored in the file as part of the compression message - and passed to the compress and uncompress functions. The - client_data is a byte array of length - cd_size which is copied to the file and passed to the - compress and uncompress methods. +

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

- The FLAGS, CD_SIZE, and CLIENT_DATA are copied to the - property list and eventually to the file and passed to the - compression functions. + memb_size is the size in bytes of each file member + and is used only when creating a new file.

- See The Dataset Interface (H5D) - in the HDF5 User's Guide for further information - regarding data compression. + memb_fapl_id is the identifier of the + file access property list to be used for each family member.

Parameters:
-
hid_t plist -
IN: Identifier for the dataset creation property list. -
H5Z_method_t method -
IN: Compression method, an integer from 16 to 225. -
unsigned int flags -
IN: Compression flags. -
size_t cd_size -
IN: Size of the byte array client_data. -
const void *client_data -
IN: Client data byte array passed to the compression method. +
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.

Non-C API(s): -

- ---> - - - ---> - - + +

Name: H5Pset_deflate +

Name: H5Pset_fapl_gass

Signature: -

herr_t H5Pset_deflate(hid_t plist, - int level +

herr_t H5Pset_fapl_gass( + hid_t fapl_id, + GASS_Info info )

Purpose: -

Sets compression method and compression level. +

Stores user-supplied GASS information.

Description: -

H5Pset_deflate sets the compression method for a - dataset creation property list to H5D_COMPRESS_DEFLATE - and the compression level to level, which should - be a value from zero to nine, inclusive. - Lower compression levels are faster but result in less compression. - This is the same algorithm as used by the GNU gzip program. +

H5Pset_fapl_gass stores user-supplied GASS information, + the GASS_Info struct data as passed in info, + to the file access property list fapl_id. + fapl_id can then be used to create and/or open the file. +

+ The GASS_Info object, info, is used for + file open operations when using GASS in the Globus environment. +

+ Any modification to info after this function call + returns may have undetermined effect to the access property list. + Users must call H5Pset_fapl_gass again to setup + the property list. +

Note: +

H5Pset_fapl_gass is an experimental function. + It is designed for use only when accessing files via the + GASS facility of the Globus environment. + For further information, see + http//www.globus.org/.

Parameters:
-
hid_t plist -
IN: Identifier for the dataset creation property list. -
int level -
IN: Compression level. +
hid_t fapl_id, +
IN: File access property list identifier. +
GASS_Info info +
IN: Pointer to the GASS information structure.

Returns: -

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

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

- - +

Name: H5Pget_deflate +

Name: H5Pset_fapl_log

Signature: -

int H5Pget_deflate(hid_t plist +

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

Purpose: -

Returns the deflate compression level from a dataset creation - property list. +

Sets up the use of the logging driver.

Description: -

H5Pget_deflate returns the deflate compression level - from a dataset creation property list that uses that method. +

H5Pset_fapl_log modifies the + file access property list to use the logging driver + H5FD_LOG. +

+ 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 an logical OR contained + in parentheses. For example, logging read and write locations would + be specified as (H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE). + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ + 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` + +
+ `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, or seek operations that occur. +
+ `H5FD_LOG_NUM_WRITE` + +
+ `H5FD_LOG_NUM_SEEK` + +
+ `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_TIME_OPEN` + +	+ + Track the time spent in open, read, write, seek, or close operations. + + + Not implemented in this release: open and read + + Partially implemented: write and seek + + Fully implemented: close + +
+ `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_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., meta data, raw data; using H5FD_LOG_FLAVOR). + This information is tracked in a buffer of size buf_size, + which must be at least the size in bytes of the file to be logged. +

Parameters:
-
hid_t plist -
IN: Identifier for the dataset creation property list. +
hid_t fapl_id +
IN: File access property list identifier. +
char *logfile +
IN: Name of the log file. +
unsigned int flags +
IN: Flags specifying the types of logging activity. +
size_t buf_size +
IN: The size of the logging buffer.

Returns: -

Returns compression level, a value between 0 and 9, if successful. - Otherwise returns a negative value. +

Returns non-negative if successful. + Otherwise returns negative. + +

---> - - + +

Name: H5Pset_vlen_mem_manager +

Name: H5Pset_fapl_mpio

Signature: -

herr_t H5Pset_vlen_mem_manager(hid_t plist, - H5MM_allocate_t alloc, - void *alloc_info, - H5MM_free_t free, - void *free_info +

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

Purpose: -

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

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

Description: -

H5Pset_vlen_mem_manager sets the memory manager for - variable-length datatype allocation in H5Dread - and free in H5Dvlen_reclaim. +

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 the file.

- The alloc and free parameters - identify the memory management routines to be used. - If the user has defined custom memory management routines, - alloc and/or free should be set to make - those routine calls (i.e., the name of the routine is used as - the value of the parameter); - if the user prefers to use the system's malloc - and/or free, the alloc and - free parameters, respectively, should be set to - NULL + H5Pset_fapl_mpio is available only in the + parallel HDF5 library and is not a collective function.

- The prototypes for these user-defined functions would appear as follows: -
- typedef void *(*H5MM_allocate_t)(size_t size, - void *alloc_info) ; - -
- typedef void (*H5MM_free_t)(void *mem, - void *free_info) ; -
- The alloc_info and free_info parameters - can be used to pass along any required information to - the user's memory management routines. + 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 access property list. + Users should not modify the communicator while it is defined + in a property list.

- In summary, if the user has defined custom memory management - routines, the name(s) of the routines are passed in the - alloc and free parameters and the - custom routines' parameters are passed in the - alloc_info and free_info parameters. - If the user wishes to use the system malloc and - free functions, the alloc and/or - free parameters are set to NULL - and the alloc_info and free_info - parameters are ignored. + info is the MPI info object to be used for + file open as defined in MPI_FILE_OPEN of MPI-2. + This function does not create a duplicated info object. + Any modification to the info object after this function call + returns may have an undetermined effect on the access property list. + Users should not modify the info while it is defined + in a property list.

Parameters:
-
hid_t plist -
IN: Identifier for the dataset transfer property list. -
H5MM_allocate_t alloc -
IN: User's allocate routine, or NULL - for system malloc. -
void *alloc_info -
IN: Extra parameter for user's allocation routine. -
- Contents are ignored if preceding parameter is - NULL. -
H5MM_free_t free -
IN: User's free routine, or NULL - for system free. -
void *free_info -
IN: Extra parameter for user's free routine. -
- Contents are ignored if preceding parameter is - NULL. +
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. -

+ +

Name: H5Pget_vlen_mem_manager +

Name: H5Pset_fapl_mpiposix

Signature: -

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

herr_t H5Pset_fapl_mpiposix( + hid_t fapl_id, + MPI_Comm comm )

Purpose: -

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

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

Description: -

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

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 access property list. + Users should not modify the communicator while it is defined + in a property list.

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. +
hid_t fapl_id +
IN: File access property list identifier. +
MPI_Comm comm +
IN: MPI-2 communicator.

Returns: -

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

- - - - - + +

Name: H5Pset_fapl_family +

Name: H5Pset_fapl_multi

Signature: -

herr_t H5Pset_fapl_family ( - hid_t fapl_id, - hsize_t memb_size, - hid_t memb_fapl_id +

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

Purpose: -

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

Sets up use of the multi-file driver.

Description: -

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

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

- memb_size is the size in bytes of each file member - and is used only when creating a new file. + 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.

- memb_fapl_id is the identifier of the - file access property list to be used for each family member. + 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 value is HADDR_UNDEF for each element. +

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. +
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 **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. +

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);
+

Non-C API(s): -

-->

- + +

Name: H5Pget_fapl_family +
Name: H5Pset_fapl_sec2
Signature: -: herr_t H5Pget_fapl_family ( - hid_t fapl_id, - hsize_t *memb_size, - hid_t *memb_fapl_id +; herr_t H5Pset_fapl_sec2( + hid_t fapl_id )
Purpose: -: Returns file access property list information. +; Sets the sec2 driver.
Description: -: H5Pget_fapl_family returns file access property list - for use with the family driver. - This information is returned through the output parameters. +; 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. -
hsize_t *memb_size -
OUT: Size in bytes of each file member. -
hid_t *memb_fapl_id -
OUT: Identifier of file access property list for each - family member.
Returns: -: Returns a non-negative value if successful; - otherwise returns a negative value. +; Returns a non-negative value if successful. + Otherwise returns a negative value.
Non-C API(s): -: -->

- - - - - + +

Name: H5Pset_family_offset +

Name: H5Pset_fapl_split

Signature: -

herr_t H5Pset_family_offset ( - hid_t fapl_id, - hsize_t offset +

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

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

Emulates the old split file driver.

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 particluar 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. +

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 +
+
hid_t fapl_id,
IN: File access property list identifier. -
hsize_t offset -
IN: Offset in bytes within the HDF5 file. +
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. +

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);
+

Non-C API(s): -

-->

- + +

Name: H5Pget_family_offset +

Name: H5Pset_fapl_srb

Signature: -

herr_t H5Pget_family_offset ( - hid_t fapl_id, - hsize_t *offset +

herr_t H5Pset_fapl_srb( + hid_t fapl_id, + SRB_Info info )

Purpose: -

Retrieves a data offset from the file access property list. +

Saves SRB connection handler and sets SRB settings.

Description: -

H5Pget_family_offset retrieves the value of offset - from the file access property list fapl_id - so that the user application - can retrieve a file handle for low-level access to a particluar 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 data offset returned in offset is the offset - of the data in the HDF5 file that is stored on disk in the selected - member file in a family of files. -

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

H5Pset_fapl_srb stores the SRB client-to-server + connection handler SRB_CONN after the connection + is established and other user-supplied SRB information. +

+ The user-supplied SRB information is contained in the + SRB_Info struct pointed to by info + and is stored in the file access property list fapl_id. + This information can then be used to create or open a file. +

Note: +

H5Pset_fapl_gass is an experimental function. + It is designed for use only when accessing files via the + Storage Resource Broker (SRB). For further information, see + http//www.npaci.edu/Research/DI/srb/.

Parameters:

hid_t fapl_id
IN: File access property list identifier. -
hsize_t *offset -
IN: Offset in bytes within the HDF5 file. +
SRB_Info info +
IN: Pointer to the SRB information structure.

Returns: -

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

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

- + +

Name: H5Pset_fapl_log +

Name: H5Pset_fapl_stdio

Signature: -

herr_t H5Pset_fapl_log( - hid_t fapl_id, - const char *logfile, - unsigned int flags, - size_t buf_size +

herr_t H5Pset_fapl_stdio( + hid_t fapl_id )

Purpose: -

Sets up the use of the logging driver. +

Sets the standard I/O driver.

Description: -

H5Pset_fapl_log modifies the - file access property list to use the logging driver - H5FD_LOG. -

- 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 an logical OR contained - in parentheses. For example, logging read and write locations would - be specified as (H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE). - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - 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` - -
- `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, or seek operations that occur. -
- `H5FD_LOG_NUM_WRITE` - -
- `H5FD_LOG_NUM_SEEK` - -
- `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_TIME_OPEN` - -	- - Track the time spent in open, read, write, seek, or close operations. - - - Not implemented in this release: open and read - - Partially implemented: write and seek - - Fully implemented: close - -
- `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_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)` -
- -	- -

- +

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

Non-C API(s): +

+ +

- 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., meta data, raw data; using H5FD_LOG_FLAVOR). - This information is tracked in a buffer of size buf_size, - which must be at least the size in bytes of the file to be logged. - + + +

Name: H5Pset_fapl_stream +

Signature: +

herr_t H5Pset_fapl_stream( + hid_t fapl_id, + H5FD_stream_fapl_t *fapl + ) +

Purpose: +

Sets up the use of the streaming I/O driver. +

Description: +

H5Pset_fapl_stream sets up the use of the + streaming I/O driver. +

+ fapl_id is the identifier for the + file access property list currently in use. +

+ fapl is the file access property list. +

+ The H5FD_stream_fapl_t struct contains the following + elements: +

+ + + + + + + + + + + + + + + + + + + +

size_t	`increment`
H5FD_STREAM_SOCKET_TYPE	`socket`
hbool_t	`do_socket_io`
unsigned int	`backlog`
H5FD_stream_broadcast_t	`broadcast_fn`
void *	`broadcast_arg`

increment specifies how much memory to allocate + each time additional memory is required. +
socket is an external socket descriptor; + if a valid socket argument is provided, that socket will be used. +
do_socket_io is a boolean value specifying whether + to perform I/O on socket. +
backlog is the argument for the + listen call. +
broadcast_fn is the broadcast callback function. +
broadcast_arg is the user argument to + the broadcast callback function. +

+ +

+ H5Pset_fapl_stream and H5Pget_fapl_stream + are not intended for use in a parallel environment.

Parameters:

hid_t fapl_id
IN: File access property list identifier. -
char *logfile -
IN: Name of the log file. -
unsigned int flags -
IN: Flags specifying the types of logging activity. -
size_t buf_size -
IN: The size of the logging buffer. +
H5FD_stream_fapl_t *fapl +
IN: The streaming I/O file access property list.

Returns: -

Returns non-negative if successful. - Otherwise returns negative. +

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

+ + +

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 ramaining 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`. +

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

Non-C API(s): +

+ +

Name: H5Pset_fapl_mpio +

Name: H5Pset_fill_time

Signature: -

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

herr_t H5Pset_fill_time(hid_t plist_id, + H5D_fill_time_t fill_time + )

Purpose: -

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

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

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 the 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 does not create a duplicated communicator. - Modifications to comm after this function call - returns may have an undetermined effect on the access property list. - Users should not modify the communicator while it is defined - in a property list. +

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.

- info is the MPI info object to be used for - file open as defined in MPI_FILE_OPEN of MPI-2. - This function does not create a duplicated info object. - Any modification to the info object after this function call - returns may have an undetermined effect on the access property list. - Users should not modify the info while it is defined - in a property list. + 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 fapl_id -
IN: File access property list identifier. -
MPI_Comm comm -
IN: MPI-2 communicator. -
MPI_Info info -
IN: MPI-2 info object. +
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. +

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

Non-C API(s): -

-->

- + +

Name: H5Pget_fapl_mpio +

Name: H5Pset_fill_value

Signature: -

herr_t H5Pget_fapl_mpio( - hid_t fapl_id, - MPI_Comm *comm, - MPI_Info *info +

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

Purpose: -

Returns MPI communicator information. +

Sets the fill value for a dataset.

Description: -

If the file access property list is set to the H5FD_MPIO - driver, H5Pget_fapl_mpio returns the MPI communicator and - information through the comm and info - pointers, if those values are non-null. +

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

- Neither comm nor info is copied, - so they are valid only until the file access property list - is either modified or closed. + 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 fapl_id -
IN: File access property list identifier. -
MPI_Comm *comm -
OUT: MPI-2 communicator. -
MPI_Info *info -
OUT: MPI-2 info object. +
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. +

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

Non-C API(s): -

-->

- - - + +

Name: H5Pset_fapl_mpiposix +

Name: H5Pset_filter

Signature: -

herr_t H5Pset_fapl_mpiposix( - hid_t fapl_id, - MPI_Comm comm +

herr_t H5Pset_filter(hid_t plist, + H5Z_filter_t filter, + unsigned int flags, + size_t cd_nelmts, + const unsigned int cd_values[] )

Purpose: -

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

Adds a filter to the filter pipeline.

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_filter adds the specified + filter and corresponding properties to the + end of an output filter pipeline. + If plist is a dataset creation property list, + the filter is added to the permanent filter pipeline; + if plist is a dataset transfer property list, + the filter is added to the transient filter pipeline.

- H5Pset_fapl_mpiposix is available only in the - parallel HDF5 library and is not a collective function. + 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.

+ + + + + +

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. If this bit is + clear and a filter fails, then H5Dwrite + or H5Dread also fails. +

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

+ +

+ The filter parameter specifies the filter to be set. + Valid values 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 +

+ +

+ Also see H5Pset_edc_check and + H5Pset_filter_callback. + +

Notes: +

This function currently supports only the permanent filter + pipeline; plist must be a dataset creation + property list. +

+ If multiple filters are set for a property list, they will be + applied to each chunk in the order in which they were set.

Parameters:
-
hid_t fapl_id -
IN: File access property list identifier. -
MPI_Comm comm -
IN: MPI-2 communicator. +
hid_t plist +
IN: Property list identifier. +
H5Z_filter_t filter +
IN: 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. -

- + +

Name: H5Pget_fapl_mpiposix +

Name: H5Pset_filter_callback

Signature: -

herr_t H5Pget_fapl_mpiposix( - hid_t fapl_id, - MPI_Comm *comm - ) +

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

Purpose: -

Returns MPI communicator information. +

Sets user-defined filter callback function.

Description: -

If the file access property list is set to the H5FD_MPIO - driver, H5Pget_fapl_mpiposix returns - the MPI communicator through the comm - pointer, if those values are non-null. -

- comm is not copied, so it is valid only - until the file access property list is either modified or closed. +

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, + void *buf, + size_t buf_size, + void *op_data) + +

+ where filter 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 fapl_id -
IN: File access property list identifier. -
MPI_Comm *comm -
OUT: MPI-2 communicator. +
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. +

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

- - - - - + +

Name: H5Pset_dxpl_mpio +

Name: H5Pset_fletcher32

Signature: -

herr_t H5Pset_dxpl_mpio( - hid_t dxpl_id, - H5FD_mpio_xfer_t xfer_mode - ) +

herr_t H5Pset_fletcher32(hid_t plist)

Purpose: -

Sets data transfer mode. +

Sets up use of the Fletcher32 checksum filter.

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

- +

H5Pset_fletcher32 sets the Fletcher32 checksum filter + in the dataset creation property list plist. � +

Note: +

The initial error detection implementation supports + error detection for chunked datasets only.

Parameters:
-
hid_t dxpl_id -
IN: Data transfer property list identifier. -
H5FD_mpio_xfer_t xfer_mode -
IN: Transfer mode. +
hid_t plist +
IN: Dataset creation property list identifier.

Returns: -

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

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

Non-C API(s): -

-->

- + +

Name: H5Pget_dxpl_mpio +

Name: H5Pset_gc_references

Signature: -

herr_t H5Pget_dxpl_mpio( - hid_t dxpl_id, - H5FD_mpio_xfer_t *xfer_mode +

herr_t H5Pset_gc_reference(hid_t plist, + unsigned gc_ref )

Purpose: -

Returns the data transfer mode. +

Sets garbage collecting references flag.

Description: -

H5Pget_dxpl_mpio queries the data transfer mode - currently set in the data transfer property list dxpl_id. +

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

- Upon return, xfer_mode contains the data transfer mode, - if it is non-null. + 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.

- H5Pget_dxpl_mpio is not a collective function. + 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 dxpl_id -
IN: Data transfer property list identifier. -
H5FD_mpio_xfer_t *xfer_mode -
OUT: Data transfer mode. +
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. +

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

Non-C API(s): -

-->

- + +

Name: H5Pset_fapl_multi +

Name: H5Pset_hyper_cache

Signature: -

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

herr_t H5Pset_hyper_cache(hid_t plist, + unsigned cache, + unsigned limit )

Purpose: -

Sets up use of the multi-file driver. +

Indicates whether to cache hyperslab blocks during I/O.

Description: -

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

[NOTE: + + This function is deprecated in HDF5 Release 1.6 + and will eventually be removed from the HDF5 distribution. + It is provided in this release only to enable backward compatibility + with HDF5 Releases 1.4.x + and is enabled only if the HDF5 library is configured + with the flag H5_WANT_H5_V1_4_COMPAT; + the function is not enabled in the binaries distributed by NCSA. + ]

- 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). + Given a dataset transfer property list, H5Pset_hyper_cache + indicates whether to cache hyperslab blocks during I/O, + a process which can significantly increase I/O speeds.

- 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. + When working with hyperslab selections, it is possible to + significantly speed up I/O operations by retrieving an + entire hyperslab from the file in one operation and + caching it in memory. + The cache parameter specifies whether to turn + caching on for hyperslab I/O operations. + If cache is set to 1, + caching is turned on; + if set to 0, caching is turned off.

- 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. + The parameter limit sets the maximum size of the + hyperslab block to cache. If a block is smaller than that limit, + it may still not be cached if no memory is available. + Setting limit to 0 (zero) indicates + no limitation on the size of block to attempt to cache.

- 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 value is HADDR_UNDEF for each element. -

- + The default is to cache blocks with no limit on block size + for serial I/O and to not cache blocks for parallel I/O.

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 **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. +
hid_t plist +
IN: Dataset transfer property list identifier. +
unsigned cache +
IN: A flag indicating whether caching is to be + set to on (1) or off (0). +
unsigned limit +
IN: Maximum size of the hyperslab block to cache. + 0 (zero) indicates no limit.

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

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

Non-C API(s): -

-->

- + +

Name: H5Pget_fapl_multi +

Name: H5Pset_hyper_vector_size

Signature: -

herr_t H5Pget_fapl_multi( - hid_t fapl_id, - const H5FD_mem_t *memb_map, - const hid_t *memb_fapl, - const char **memb_name, - const haddr_t *memb_addr, - hbool_t *relax +

herr_t H5Pset_hyper_vector_size(hid_t dxpl_id, + size_t vector_size )

Purpose: -

Returns information about the multi-file access property list. +

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

Description: -

H5Pget_fapl_multi returns information about the - multi-file access property list. +

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 fapl_id -
IN: File access property list identifier. -
const H5FD_mem_t *memb_map -
OUT: Maps memory usage types to other memory usage types. -
const hid_t *memb_fapl -
OUT: Property list for each memory usage type. -
const char **memb_name -
OUT: Name generator for names of member files. -
const haddr_t *memb_addr -
OUT: -
hbool_t *relax -
OUT: Allows read-only access to incomplete file sets - when TRUE. +
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. +

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

Non-C API(s): -

-->

- + +

Name: H5Pset_dxpl_multi +
Name: H5Pset_istore_k
Signature: -: herr_t H5Pset_dxpl_multi( - hid_t dxpl_id, - const hid_t *memb_dxpl - ) +; herr_t H5Pset_istore_k(hid_t plist, + int ik + )
Purpose: -: Sets the data transfer property list for the multi-file driver. +; Sets the size of the parameter used to control the + B-trees for indexing chunked datasets.
Description: -: H5Pset_dxpl_multi sets the data transfer property list - dxpl_id to use the multi-file driver for each - memory usage type memb_dxpl[]. -
- H5Pset_dxpl_multi can only be used after - the member map has been set with H5Pset_fapl_multi. +; H5Pset_istore_k sets the size of the parameter + used to control the B-trees for indexing chunked datasets. + This function is only valid 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.
Parameters:
-
hid_t dxpl_id, -
IN: Data transfer property list identifier. -
const hid_t *memb_dxpl -
IN: Array of data access property lists. +
hid_t plist +
IN: Identifier of property list to query. +
int ik +
IN: 1/2 rank of chunked storage B-tree.
Returns: -: Returns a non-negative value if successful. - Otherwise returns a negative value. -

- + +

Name: H5Pget_dxpl_multi -

Signature: -

herr_t H5Pget_dxpl_multi( - hid_t dxpl_id, - const hid_t *memb_dxpl - ) -
-
+

Name: H5Pset_layout +

Signature: +

herr_t H5Pset_layout(hid_t plist, + H5D_layout_t layout + )

Purpose: -

Returns multi-file data transfer property list information. +

Sets the type of storage used to store the raw data for a dataset.

Description: -

H5Pget_dxpl_multi returns the data transfer property list - information for the multi-file driver. +

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 very small amounts of raw + data. + The current limit is approximately 64K (HDF5 Release 1.6). +
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. +

+ 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 dxpl_id, -
IN: Data transfer property list identifier. -
const hid_t *memb_dxpl -
OUT: Array of data access property lists. +
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. -

- + +

Name: H5Pset_fapl_split +

Name: H5Pset_meta_block_size

Signature: -

herr_t H5Pset_fapl_split( +

herr_t H5Pset_meta_block_size( hid_t fapl_id, - const char *meta_ext, - hid_t meta_plist_id, - const char *raw_ext, - hid_t raw_plist_id + hsize_t size )

Purpose: -

Emulates the old split file driver. +

Sets the minimum metadata block size.

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

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.

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

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

Non-C API(s): -

- + +

Name: H5Pset_multi_type @@ -6639,336 +6713,180 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
Non-C API(s):: - --> - -

- - -

Name: H5Pget_multi_type -

Signature: -

herr_t H5Pset_multi_type ( - hid_t fapl_id, - H5FD_mem_t *type - ) -

Purpose: -

Retrieves data type property for MULTI driver. -

Description: -

H5Pget_multi_type retrieves the data type setting from the - file access or data transfer property list fapl_id. - This enables a user application to specifiy 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 returned in type will be one of those - listed in the discussion of the type parameter in the the - description of the function - H5Pset_multi_type. -

- Use of this function is only appropriate for an HDF5 file written - as a set of files with the MULTI file driver. -

Parameters: -
-
hid_t fapl_id -
IN: File access property list or data transfer property list identifier. -
H5FD_mem_t *type -
OUT: Type of data. -
-

Returns: -

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

- - -

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. -
Non-C API(s): -: - -

- - -

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. -
Non-C API(s): -: + -->

- + +

Name: H5Pset_fapl_stream +

Name: H5Pset_preserve

Signature: -

herr_t H5Pset_fapl_stream( - hid_t fapl_id, - H5FD_stream_fapl_t *fapl - ) +

herr_t H5Pset_preserve(hid_t plist, + hbool_t status + )

Purpose: -

Sets up the use of the streaming I/O driver. +

Sets the dataset transfer property list status to TRUE or FALSE.

Description: -

H5Pset_fapl_stream sets up the use of the - streaming I/O driver. -

- fapl_id is the identifier for the - file access property list currently in use. -

- fapl is the file access property list. -

- The H5FD_stream_fapl_t struct contains the following - elements: -

- - - - - - - - - - - - - - - - - - - -

size_t	`increment`
H5FD_STREAM_SOCKET_TYPE	`socket`
hbool_t	`do_socket_io`
unsigned int	`backlog`
H5FD_stream_broadcast_t	`broadcast_fn`
void *	`broadcast_arg`

increment specifies how much memory to allocate - each time additional memory is required. -
socket is an external socket descriptor; - if a valid socket argument is provided, that socket will be used. -
do_socket_io is a boolean value specifying whether - to perform I/O on socket. -
backlog is the argument for the - listen call. -
broadcast_fn is the broadcast callback function. -
broadcast_arg is the user argument to - the broadcast callback function. -

- +

H5Pset_preserve sets the + dataset transfer property list status to TRUE or FALSE.

- H5Pset_fapl_stream and H5Pget_fapl_stream - are not intended for use in a parallel environment. + When reading or writing compound data types 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 fapl_id -
IN: File access property list identifier. -
H5FD_stream_fapl_t *fapl -
IN: The streaming I/O file access property list. +
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. -

- + +

Name: H5Pget_fapl_stream +

Name: H5Pset_shuffle

Signature: -

herr_t H5Pget_fapl_stream( - hid_t fapl_id, - H5FD_stream_fapl_t *fapl - ) +

herr_t H5Pset_shuffle(hid_t plist_id)

Purpose: -

Returns the streaming I/O driver settings. +

Sets up use of the shuffle filter.

Description: -

H5Pget_fapl_stream returns the file access properties - set for the use of the streaming I/O driver. -

- H5Pset_fapl_stream and H5Pget_fapl_stream - are not intended for use in a parallel environment. +

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

+ This filter is designed to be used in combination with + a compression filter.

Parameters:
-
hid_t fapl_id -
IN: File access property list identifier. -
H5FD_stream_fapl_t *fapl -
OUT: The streaming I/O file access property list. +
hid_t plist_id +
IN: Dataset creation property list identifier.

Returns: -

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

- - +

Name: H5Pset_driver +

Name: H5Pset_sieve_buf_size

Signature: -

herr_t H5Pset_driver( - hid_t plist_id, - hid_t driver_id, - const void * driver_info +

herr_t H5Pset_sieve_buf_size( + hid_t fapl_id, + hsize_t size )

Purpose: -

Sets the file driver. +

Sets the maximum size of the data sieve buffer.

Description: -

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

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.

- Need driver_info struct definition. + 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 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. + 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.

Parameters:
-
hid_t plist_id -
IN: File access or data transfer property list identifier. -
hid_t driver_id -
IN: Driver identifier. -
const void * driver_info -
IN: Optional struct containing driver properties. +
hid_t fapl_id +
IN: File access property list identifier. +
hsize_t size +
IN: Maximum size, in bytes, of data sieve buffer.

Returns:

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

Non-C API(s): -

---> - - + +

Name: H5Pget_driver +

Name: H5Pset_sizes

Signature: -

hid_t H5Pget_driver( - hid_t plist_id - ) +

herr_t H5Pset_sizes(hid_t plist, + size_t sizeof_addr, + size_t sizeof_size + )

Purpose: -

Returns low-lever driver identifier. +

Sets the byte size of the offsets and lengths used to address objects + in an HDF5 file.

Description: -

H5Pget_driver returns the identifier of the - low-level file driver associated with the file access property list - or data transfer property list plist_id. -

- Valid driver identifiers with the standard HDF5 library distribution - include the following: -

-           H5FD_CORE
-           H5FD_DPSS
-           H5FD_FAMILY
-           H5FD_GASS
-           H5FD_LOG
-           H5FD_MPIO
-           H5FD_MULTI
-           H5FD_SEC2
-           H5FD_STDIO
-           H5FD_STREAM

- If a user defines and registers custom drivers or - if additional drivers are defined in an HDF5 distribution, - this list will be longer. -

- The returned driver identifier is only valid as long as the - file driver remains registered. +

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_id -
IN: File access or data transfer property list identifier. +
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 valid low-level driver identifier if successful. - Otherwise returns a negative value. +

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

Non-C API(s): -

- - +

Name: H5Pget_driver_info +

Name: H5Pset_small_data_block_size

Signature: -

void *H5Pget_driver_info( - hid_t plist_id - ) +

herr_t H5Pset_small_data_block_size(hid_t fapl_id, + hsize_t size + )

Purpose: -

Returns a pointer to file driver information. +

Sets the size of a contiguous block reserved for small data.

Description: -

H5Pget_driver_info returns a pointer to - file driver-specific information for the low-level driver - associated with the file access or data transfer property list - plist_id. - +

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 IO performance.

- Need more on "a pointer" or on what - is "pointed to." Might this be the driver_info - struct definition in H5Pset_driver? - + 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.

- If no driver-specific properties have been registered, - H5Pget_driver_info returns NULL. + The HDF5 library employs an algorithm that determines whether + IO 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 plist_id -
IN: File access or data transfer property list identifier. +
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 pointer to the struct containing - low-level driver information. - Otherwise returns NULL. -

- NULL is also returned if no driver-specific properties - have been registered. - No error is pushed on the stack in this case. +

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

Non-C API(s): -

---> - - + +

Name: H5Pset_fapl_gass +

Name: H5Pset_sym_k

Signature: -

herr_t H5Pset_fapl_gass( - hid_t fapl_id, - GASS_Info info - ) +

herr_t H5Pset_sym_k(hid_t plist, + int ik, + int lk + )

Purpose: -

Stores user-supplied GASS information. +

Sets the size of parameters used to control the symbol table nodes.

Description: -

H5Pset_fapl_gass stores user-supplied GASS information, - the GASS_Info struct data as passed in info, - to the file access property list fapl_id. - fapl_id can then be used to create and/or open the file. -

- The GASS_Info object, info, is used for - file open operations when using GASS in the Globus environment. -

- Any modification to info after this function call - returns may have undetermined effect to the access property list. - Users must call H5Pset_fapl_gass again to setup - the property list. -

Note: -

H5Pset_fapl_gass is an experimental function. - It is designed for use only when accessing files via the - GASS facility of the Globus environment. - For further information, see - http//www.globus.org/. +

H5Pset_sym_k sets the size of parameters used to + control the symbol table nodes. This function is only valid + for file creation property lists. Passing in a value of 0 for + one of the parameters retains the current value. +

+ ik is one half the rank of a 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. +

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

Parameters:
-
hid_t fapl_id, -
IN: File access property list identifier. -
GASS_Info info -
IN: Pointer to the GASS information structure. +
hid_t plist +
IN: Identifier for property list to query. +
int ik +
IN: Symbol table tree rank. +
int lk +
IN: Symbol table node size.

Returns: -

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

- + +

Name: H5Pget_fapl_gass +

Name: H5Pset_szip

Signature: -

herr_t H5Pget_fapl_gass( - hid_t fapl_id, - GASS_Info *info - ) +

herr_t H5Pset_szip(hid_t plist, + unsigned int options_mask, + unsigned int pixels_per_block)

Purpose: -

Retrieves GASS information. +

Sets up use of the SZIP compression filter.

Description: -

If the file access property list fapl_id is set - for use of the H5FD_GASS driver, - H5Pget_fapl_gass returns the GASS_Info - object through the info pointer. -

- The GASS_Info information is copied, so it is valid - only until the file access property list is modified or closed. -

Note: -

H5Pget_fapl_gass is an experimental function. - It is designed for use only when accessing files via the - GASS facility of the Globus environment. - For further information, see - http//www.globus.org/. +

H5Pset_szip sets a filter for the dataset + to SZIP compression, H5Z_FILTER_SZIP, + a compression method designed for use with scientific data. +

+ SZIP options are passed in an options mask, options_mask, + as follows. +

+ + + + + + + + + + + + +

+ + Option +	+ + Description + + (Paired options are mutually exclusive.) +
+ + `H5_SZIP_CHIP_OPTION_MASK` +	+ + Compresses exactly as in hardware. +
+ `H5_SZIP_ALLOW_K13_OPTION_MASK` +	+ Allows k split = 13 compression mode. (Default) +
+ + `H5_SZIP_EC_OPTION_MASK` +	+ + Selects entropy coding method. (Default) +
+ `H5_SZIP_NN_OPTION_MASK` +	+ Selects nearest neighbor coding method. +
+ +	+ +

+ + Some typical usages are as follows: +

One of the compression methods, + H5_SZIP_EC_OPTION_MASK or + H5_SZIP_NN_OPTION_MASK, is specified. +
The H5_SZIP_ALLOW_K13_OPTION_MASK is used. +

+ Options are combined to create the options mask by means of + a logical OR operation. For example, the + option mask can be set as follows: +

+ options_mask = H5_SZIP_NN_OPTION_MASK | H5_SZIP_ALLOW_K13_OPTION_MASK; + +

+ 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, + with typical values being 8, 10, + 16, and 32. + The more pixel values vary, the smaller this number should be. + For optimal performance, the number of pixels per scan line + (i.e., the size of the fastest-changing dimension in the chunk) + should be an even multiple of the number of pixels per block. +

Notes: +

SZIP works only with datasets with 1 through 24 bits/pixel, + 32 pits/pixel, or 64 bits/pixel. +

+ SZIP typically requires that the user application also supply + the number of pixels in the object to be compressed, + the number of bits per pixel, and 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. +

+ Also see + SZIP Compression in HDF5 + for further discussion of SZIP compression in HDF5, + for important information regarding terms of use and + the SZIP copyright notice, + and for a list of SZIP-related references. +

Parameters:
-
hid_t fapl_id, -
IN: File access property list identifier. -
GASS_Info *info -
OUT: Pointer to the GASS information structure. +
hid_t plist +
IN: Dataset creation or dataset transfer property list + identifier. +
unsigned int options_mask +
IN: A bit-mask conveying the desired SZIP options. +
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. - -

+ + + +

Name: H5Pset_fapl_srb +
Name: H5Pset_userblock
Signature: -: herr_t H5Pset_fapl_srb( - hid_t fapl_id, - SRB_Info info - ) +; herr_t H5Pset_userblock(hid_t plist, + hsize_t size + )
Purpose: -: Saves SRB connection handler and sets SRB settings. +; Sets user block size.
Description: -: H5Pset_fapl_srb stores the SRB client-to-server - connection handler SRB_CONN after the connection - is established and other user-supplied SRB information. -
- The user-supplied SRB information is contained in the - SRB_Info struct pointed to by info - and is stored in the file access property list fapl_id. - This information can then be used to create or open a file. -
Note: -: H5Pset_fapl_gass is an experimental function. - It is designed for use only when accessing files via the - Storage Resource Broker (SRB). For further information, see - http//www.npaci.edu/Research/DI/srb/. +; 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 fapl_id -
IN: File access property list identifier. -
SRB_Info info -
IN: Pointer to the SRB information structure. +
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. -

- - - + +

Name: H5Pget_fapl_srb +

Name: H5Pset_vlen_mem_manager

Signature: -

herr_t H5Pget_fapl_srb( - hid_t fapl_id, - SRB_Info *info +

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

Purpose: -

Retrieves SRB information. +

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

Description: -

If the file access property list fapl_id is set - for use of the H5FD_SRB driver, - H5Pget_fapl_srb returns the SRB_Info - object through the info pointer. +

H5Pset_vlen_mem_manager sets the memory manager for + variable-length datatype allocation in H5Dread + and free in H5Dvlen_reclaim.

- The SRB_Info information is copied, so it is valid - only until the file access property list is modified or closed. -

Note: -

H5Pset_fapl_gass is an experimental function. - It is designed for use only when accessing files via the - Storage Resource Broker (SRB). For further information, see - http//www.npaci.edu/Research/DI/srb/. + The alloc and free parameters + identify the memory management routines to be used. + If the user has defined custom memory management routines, + alloc and/or free should be set to make + those routine calls (i.e., the name of the routine is used as + the value of the parameter); + if the user prefers to use the system's malloc + and/or free, the alloc and + free parameters, respectively, should be set to + NULL +

+ The prototypes for these user-defined functions would appear as follows: +
+ typedef void *(*H5MM_allocate_t)(size_t size, + void *alloc_info) ; + +
+ typedef void (*H5MM_free_t)(void *mem, + void *free_info) ; +
+ The alloc_info and free_info parameters + can be used to pass along any required information to + the user's memory management routines. +

+ In summary, if the user has defined custom memory management + routines, the name(s) of the routines are passed in the + alloc and free parameters and the + custom routines' parameters are passed in the + alloc_info and free_info parameters. + If the user wishes to use the system malloc and + free functions, the alloc and/or + free parameters are set to NULL + and the alloc_info and free_info + parameters are ignored.

Parameters:
-
hid_t fapl_id -
IN: File access property list identifier. -
SRB_Info *info -
OUT: Pointer to the SRB information structure. +
hid_t plist +
IN: Identifier for the dataset transfer property list. +
H5MM_allocate_t alloc +
IN: User's allocate routine, or NULL + for system malloc. +
void *alloc_info +
IN: Extra parameter for user's allocation routine. +
+ Contents are ignored if preceding parameter is + NULL. +
H5MM_free_t free +
IN: User's free routine, or NULL + for system free. +
void *free_info +
IN: 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. +

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

+ + +

Name: H5Punregister + +
Signature: +: herr_t H5Punregister( + H5P_class_t class, + const char *name + ) + +
Purpose: +: Removes a property from a property list class. + +
Description: +: H5Punregister removes a property from a + property list class. + +
+ Future property lists created of that class will not contain + this property; + existing property lists containing this property are not affected. + +
Parameters: +
+ + + + + + +
H5P_class_t class IN: Property list class from which to remove + permanent property
const char *name IN: Name of property to remove
+ +
Returns: +: Success: a non-negative value +; Failure: a negative value + +
Non-C APIs: +: + +

+ + + +--> + + + - -

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

The value of fc_degree determines how aggressively H5Fclose - deals with objects within a file that remain open when H5Fclose - is called to close that file.� fc_degree can have any one of - four valid values: -

- - - - - - - - - - - - - - - - - - - - - - - - - -

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 ramaining 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`. -

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

Non-C API(s): -

- -

+--> + +--> +

HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003 -

- -Last modified: 3 July 2003 +

-- cgit v0.12

hid_t `dst_id`	IN: Identifier of the destination property list or + class
hid_t `src_id`	IN: Identifier of the source property list or class
const char *`name`	IN: Name of the property to copy

	+ `H5D_FILL_VALUE_UNDEFINED` +	+ Fill value is undefined. +
	+ `H5D_FILL_VALUE_DEFAULT` +	+ Fill value is the library default. +
	+ `H5D_FILL_VALUE_USER_DEFINED` +	+ Fill value is defined by the application. +

`hid_t` `plid`	IN: Property list identifier to create temporary property - within
hid_t `plid`	IN: Identifier of the property list to query
const char *`name`	IN: Name of property to create
size_t `size`	IN: Size of property in bytes
IN: Name of property to query
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
OUT: Pointer to a location to which to copy the value of + of the property

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

	+ `H5D_ALLOC_TIME_DEFAULT` +	+ Uses the default allocation time, based on the dataset storage method. + See the `fill_time` description in + H5Pset_alloc_time for + default allocation times for various storage methods. +
	+ `H5D_ALLOC_TIME_EARLY` +	+ All space is allocated when the dataset is created. +
	+ `H5D_ALLOC_TIME_INCR` +	+ Space is allocated incrementally as data is written to the dataset. +
	+ `H5D_ALLOC_TIME_LATE` +	+ All space is allocated when data is first written to the dataset. +

hid_t `id`	IN: Identifier for the property to query
const char *`name`	IN: Name of property to check for

hid_t `id`	IN: Identifier of property object to query
size_t *`nprops`	OUT: Number of properties in object

hid_t `plist`	IN: Identifier of the property list
`hid_t` pclass	IN: Identifier of the property class

hid_t `id1`	IN: First property object to be compared
hid_t `id2`	IN: Second property object to be compared

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

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

hid_t `plid`	IN: Identifier of the property list to modify
const char *`name`	IN: Name of property to remove

H5P_class_t `class`	IN: Property list class from which to remove - permanent property
const char *`name`	IN: Name of property to remove

	+ `H5D_FILL_TIME_IFSET` +	+ Fill values are written 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` +	+ Fill values are written to the dataset when storage space is allocated. +
	+ `H5D_FILL_TIME_NEVER` +	+ Fill values are never written to the dataset. +

	- `H5D_FILL_VALUE_UNDEFINED` -	- Fill value is undefined. -
	- `H5D_FILL_VALUE_DEFAULT` -	- Fill value is the library default. -
	- `H5D_FILL_VALUE_USER_DEFINED` -	- Fill value is defined by the application. -

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

	- `H5D_FILL_TIME_IFSET` -	- Fill values are written 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` -	- Fill values are written to the dataset when storage space is allocated. -
	- `H5D_FILL_TIME_NEVER` -	- Fill values are never written to the dataset. -

	- `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.) -

	- `H5D_ALLOC_TIME_DEFAULT` -	- Uses the default allocation time, based on the dataset storage method. - See the `fill_time` description in - H5Pset_alloc_time for - default allocation times for various storage methods. -
	- `H5D_ALLOC_TIME_EARLY` -	- All space is allocated when the dataset is created. -
	- `H5D_ALLOC_TIME_INCR` -	- Space is allocated incrementally as data is written to the dataset. -
	- `H5D_ALLOC_TIME_LATE` -	- All space is allocated when data is first written to the dataset. -

	+ `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.) +

H5P: Property List Interface

Property List API Functions

	+ `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. +