From c1afffec458a21b98072930d06ece03e7ba1954c Mon Sep 17 00:00:00 2001
From: Frank Baker
+
- This property list must eventually be closed with
-
+ Existing property lists of this class will continue to exist,
+ but new ones are not able to be created.
+
+ If a
@@ -60,8 +61,7 @@ And in this document, the
-
-H5P: Property List Interface
Property List API Functions
@@ -154,7 +154,7 @@ which require many different parameters to be easily manipulated.
-
+
-
+
+
+
- || 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.
-
+
+
H5Pcreate
(H5P_class_t type
- )
+ H5Pall_filters_avail
(hid_t dcpl_id
)
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
- H5P_FILE_ACCESS
- H5P_DATASET_CREATE
- H5P_DATASET_XFER
- H5P_MOUNT
- H5Pcreate
- creates and returns a new mount property list
- initialized with default values.
- 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.
-
type
- dcpl_id
+ plist
) if successful;
- otherwise Fail (-1).
- TRUE
if all filters are available
+ and FALSE
if one or more is not currently available.
+ Returns FAIL
, a negative value, on error.
+
-
+
+
-
+
+
+H5Pget_class
(hid_t plist
- )
+ H5Pclose_class
(
+ hid_t class
+ )
+
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
.
+
-
+ plist
-
+
+
+
+ hid_t
+ class
IN: Property list class to close
-
+
+
+
+
+
+
H5Pclose_list
(
+ hid_t plist
+ )
+
+ H5Pclose_list
closes a property list.
+
+ 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.
+
+
+
+
+
+
+ hid_t plist
+ IN: Property list to close
+
+
-
+
+
-
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 H5Pcopy_prop
(
+ hid_t dst_id
,
+ hid_t src_id
,
+ const char *name
+ )
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:
-
H5P_cls_create_func_t
)(
- hid_t prop_id
,
- void * create_data
- );
- 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 |
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:
-
H5P_cls_copy_func_t
)(
- hid_t prop_id
,
- void * copy_data
- );
- 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 |
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
+
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 |
H5Pcreate
(H5P_class_t type
+ )
+ 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
+ H5P_FILE_ACCESS
+ H5P_DATASET_CREATE
+ H5P_DATASET_XFER
+ H5P_MOUNT
+ 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.
+
type
+ plist
) if successful;
+ otherwise Fail (-1).
+ 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 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:
+ H5P_cls_create_func_t
)(
+ hid_t prop_id
,
+ void * create_data
+ );
+ 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 |
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:
+ H5P_cls_copy_func_t
)(
+ hid_t prop_id
,
+ void * copy_data
+ );
+ 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 |
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.
-->
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
- )
-
+ H5Pequal
(
+ hid_t id1,
+ hid_t id2
+ )
+
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.
-
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:
- H5P_prp_create_func_t
)(
- const char *name
,
- size_t size
,
- void *initial_value
);
-
+ Either both id1
and id2
must be
+ property lists or both must be classes; comparing a list to a
+ class is an error.
+
+
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 |
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:
- prop_id
,
- const char *name
,
- size_t size
,
- void *new_value
);
- 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 |
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:
-
H5P_prp_get_func_t
)(
- hid_t prop_id
,
- const char *name
,
- size_t size
,
- void *value
);
- 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 |
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.
-
+ 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:
- H5P_prp_delete_func_t
)(
- hid_t prop_id
,
- const char *name
,
- size_t size
,
- void *value
);
- 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 |
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.
-
+ 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:
- H5P_prp_copy_func_t
)(
- const char *name
,
- size_t size
,
- void *value
);
- 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 |
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.
-
+
+
+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:
- H5P_prp_close_func_t
)(
- hid_t prop_id
,
- const char *name
,
- size_t size
,
- void *value
);
- H5Pexist
(
+ hid_t id
;
+ const char *name
+ )
+
+ H5Pexist
determines whether a property exists
+ within a property list or class.
+
+ 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 |
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.
-
-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
- 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
- )
-
+ H5Pfill_value_defined
(hid_t plist_id
,
+ H5D_fill_value_t *status
+ )
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. + |
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. +
plist_id
+ status
+ - 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. -
+ + +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:
- H5P_prp_set_func_t
)(
- hid_t prop_id
,
- const char *name
,
- size_t size
,
- void *new_value
);
- 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 |
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.
+
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:
-
H5P_prp_get_func_t
)(
- hid_t prop_id
,
- const char *name
,
- size_t size
,
- void *value
);
- 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 |
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.
-
+ 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
);
- 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 |
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.
-
+ 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:
- H5P_prp_copy_func_t
)(
- const char *name
,
- size_t size
,
- void *value
);
- 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 |
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:
-
H5P_prp_close_func_t
)(
- hid_t prop_id
,
- const char *name
,
- size_t size
,
- void *value
);
- hid_t |
- 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 |
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.
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 |
H5Pset
(
- hid_t plid
,
- const char *name
,
- void *value
)
- )
-
+ H5Pget_alignment
(hid_t plist
,
+ hsize_t *threshold
,
+ hsize_t *alignment
+ )
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).
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 |
plist
+ *threshold
+ *alignment
+ H5Pexist
(
- hid_t id
;
- const char *name
- )
-
+ H5Pget_alloc_time
(hid_t plist_id
,
+ H5D_alloc_time_t *alloc_time
+ )
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. + |
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
.
+
hid_t id |
- IN: Identifier for the property to query |
const char *name |
- IN: Name of property to check for |
plist_id
+ alloc_time
+ H5Pget_size
(
- hid_t id
,
- const char *name
,
- size_t *size
- )
-
+ H5Pget_btree_ratios
(hid_t plist
,
+ double *left
,
+ double *middle
,
+ double *right
+ )
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.
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 |
plist
+ left
+ right
+ middle
+ H5Pget_buffer
(hid_t plist
,
+ void **tconv
,
+ void **bkg
+ )
+ H5Pget_buffer
reads values previously set
+ with H5Pset_buffer.
+ plist
+ **tconv
+ **bkg
+ H5Pget_nprops
(
- hid_t id
,
- size_t *nprops
- )
+ H5Pget_cache
(hid_t plist_id
,
+ int *mdc_nelmts
,
+ int *rdcc_nelmts
,
+ size_t *rdcc_nbytes
,
+ double *rdcc_w0
+ )
+ 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. +
plist_id
+ *mdc_nelmts
+ *rdcc_nelmts
+ *rdcc_nbytes
+ *rdcc_w0
+ H5Pget_chunk
(hid_t plist
,
+ int max_ndims
,
+ hsize_t * dims
+ )
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.
hid_t id |
- IN: Identifier of property object to query |
size_t *nprops |
- OUT: Number of properties in object |
plist
+ max_ndims
+ dims
array.
+ dims
+ H5Pget_class
(hid_t plist
+ )
+ 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
.
+ plist
+ H5Pisa_class
(
- hid_t plist
,
- hid_t pclass
- )
-
+ H5Pget_driver
(
+ hid_t plist_id
+ )
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.
hid_t plist |
- IN: Identifier of the property list |
hid_t pclass |
- IN: Identifier of the property class |
plist_id
+ NULL
.
+
+ NULL
is also returned if no driver-specific properties
+ have been registered.
+ No error is pushed on the stack in this case.
+
H5Pequal
(
- hid_t id1,
- hid_t id2
- )
-
+ H5Pget_dxpl_mpio
(
+ hid_t dxpl_id
,
+ H5FD_mpio_xfer_t *xfer_mode
+ )
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.
hid_t id1 |
- IN: First property object to be compared |
hid_t id2 |
- IN: Second property object to be compared |
dxpl_id
+ xfer_mode
+ H5Pget_dxpl_multi
(
+ hid_t dxpl_id
,
+ const hid_t *memb_dxpl
+ )
+H5Pget_dxpl_multi
returns the data transfer property list
+ information for the multi-file driver.
+ dxpl_id
,
+ memb_dxpl
+ H5Piterate
(
- hid_t id
,
- int * idx
,
- H5P_iterate_t iter_func
,
- void * iter_data
- )
-
+ H5Pget_edc_check
(hid_t plist
)
+ 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.
-
H5P_iterate_t
operator is
- as follows:
- H5P_iterate_t
)(
- hid_t id
,
- const char *>name
,
- void *iter_data
- )
- 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.
-
-
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 |
iter_func
if it was non-zero;
- zero if all properties have been processed
- H5Pget_edc_check
queries the dataset transfer property
+ list plist
to determine whether error detection
+ is enabled for data read operations.
+ plist
+ H5P_ENABLE_EDC
or H5P_DISABLE_EDC
+ if successful;
+ otherwise returns a negative value.
+ H5Pcopy_prop
(
- hid_t dst_id
,
- hid_t src_id
,
- const char *name
- )
-
+ H5Pget_external
(hid_t plist
,
+ int idx
,
+ size_t name_size
,
+ char *name
,
+ off_t *offset
,
+ hsize_t *size
+ )
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.
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 |
plist
+ idx
+ name_size
+ name
array.
+ *name
+ *offset
+ *size
+ H5Premove
(plid, name
)
- hid_t plid
;
- const char *name
- )
-
+ H5Pget_external_count
(hid_t plist
+ )
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.
hid_t plid |
- IN: Identifier of the property list to modify |
const char *name |
- IN: Name of property to remove |
plist
+ H5Punregister
(
- H5P_class_t class
,
- const char *name
- )
-
+ H5Pget_family_offset
(
+ hid_t fapl_id
,
+ hsize_t *offset
+ )
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. - -
H5P_class_t class |
- IN: Property list class from which to remove - permanent property |
const char *name |
- IN: Name of property to remove |
H5Pclose_list
(
- hid_t plist
- )
-
- 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.
-
-
hid_t plist | - | IN: Property list to close |
H5Pclose_class
(
- hid_t class
- )
-
- - Existing property lists of this class will continue to exist, - but new ones are not able to be created. - -
hid_t class |
- IN: Property list class to close |
H5Pget_version
(hid_t plist
,
- int * super
,
- int * freelist
,
- int * stab
,
- int * shhdr
- )
- 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.
plist
- super
- freelist
- stab
- shhdr
- fapl_id
+ offset
+ H5Pset_userblock
(hid_t plist
,
- hsize_t size
- )
+ H5Pget_fapl_core
(
+ hid_t fapl_id
,
+ size_t *increment
,
+ hbool_t *backing_store
+ )
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
.
plist
- size
- fapl_id
+ increment
+ backing_store
+ H5Pget_userblock
(hid_t plist
,
- hsize_t * size
- )
+ H5Pget_fapl_family
(
+ hid_t fapl_id
,
+ hsize_t *memb_size
,
+ hid_t *memb_fapl_id
+ )
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.
plist
- size
- fapl_id
+ memb_size
+ memb_fapl_id
+ H5Pset_sizes
(hid_t plist
,
- size_t sizeof_addr
,
- size_t sizeof_size
- )
+ H5Pget_fapl_gass
(
+ hid_t fapl_id
,
+ GASS_Info *info
+ )
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.
+ 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. +
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/.
plist
- sizeof_addr
- sizeof_size
- fapl_id
,
+ info
+ H5Pget_sizes
(hid_t plist
,
- size_t * sizeof_addr
,
- size_t * sizeof_size
- )
+ H5Pget_fapl_mpio
(
+ hid_t fapl_id
,
+ MPI_Comm *comm
,
+ MPI_Info *info
+ )
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.
+ 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.
plist
- size
- size
- fapl_id
+ comm
+ info
+ H5Pset_sym_k
(hid_t plist
,
- int ik
,
- int lk
- )
+ H5Pget_fapl_mpiposix
(
+ hid_t fapl_id
,
+ MPI_Comm *comm
+ )
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
.
+
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.
plist
- ik
- lk
- fapl_id
+ comm
+ H5Pget_sym_k
(hid_t plist
,
- int * ik
,
- int * lk
- )
+ 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
+ )
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.
plist
- ik
- size
- fapl_id
+ memb_map
+ memb_fapl
+ memb_name
+ memb_addr
+ relax
+ TRUE
.
H5Pset_istore_k
(hid_t plist
,
- int ik
- )
+ H5Pget_fapl_srb
(
+ hid_t fapl_id
,
+ SRB_Info *info
+ )
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
.
+
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. +
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/.
plist
- ik
- fapl_id
+ info
+ H5Pget_istore_k
(hid_t plist
,
- int * ik
- )
+ H5Pget_fapl_stream
(
+ hid_t fapl_id
,
+ H5FD_stream_fapl_t *fapl
+ )
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.
plist
- ik
- fapl_id
+ fapl
+ H5Pset_layout
(hid_t plist
,
- H5D_layout_t layout
- )
- 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:
-
plist
- layout
- H5Pget_layout
(hid_t plist
)
- H5Pget_layout
returns the layout of the raw data for
- a dataset. This function is only valid for dataset creation
- property lists.
-
- H5Pget_fclose_degree
(hid_t fapl_id
,
+ H5F_close_degree_t fc_degree
)
+ 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
.
+
plist
- fapl_id
+ fc_degree
+ fc_degree
.
- Otherwise, returns a negative value indicating faliure. +
H5Pset_chunk
(hid_t plist
,
- int ndims
,
- const hsize_t * dim
+ H5Pget_fill_time
(hid_t plist_id
,
+ H5D_fill_time_t *fill_time
)
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. + |
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
.
+
plist
- ndims
- dim
- plist_id
+ fill_time
+ H5Pget_chunk
(hid_t plist
,
- int max_ndims
,
- hsize_t * dims
- )
+ H5Pget_fill_value
(hid_t plist_id
,
+ hid_t type_id
,
+ void *value
+ )
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. +
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.
+
plist
- max_ndims
- dims
array.
- dims
- plist_id
+ type_id
,
+ value
.
+ value
+ H5Pset_alignment
(hid_t plist
,
- hsize_t threshold
,
- hsize_t alignment
+ H5Pget_filter
(hid_t plist
,
+ int filter_number
,
+ unsigned int *flags
,
+ size_t *cd_nelmts
,
+ unsigned int *cd_values
,
+ size_t namelen
,
+ char name[]
)
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
.
+
plist
must be a dataset creation property
+ list.
plist
- threshold
- alignment
- filter_number
+ flags
+ cd_nelmts
+ cd_values
.
+ cd_values
+ namelen
+ name
.
+ name[]
+
+ 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 + |
H5Pget_alignment
(hid_t plist
,
- hsize_t *threshold
,
- hsize_t *alignment
- )
+ 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[]
+ )
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).
- 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.
+
plist
- *threshold
- *alignment
- plist_id
+ filter
+ flags
+ cd_nelmts
+ cd_values
.
+ cd_values[]
+ namelen
+ name[]
.
+ name[]
+ H5Pset_external
(hid_t plist
,
- const char *name
,
- off_t offset
,
- hsize_t size
+ H5Pget_gc_references
(hid_t plist
,
+ unsigned *gc_ref
)
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.
plist
- *name
- offset
- size
- gc_ref
+ 1
indicates that
+ garbage collection is on while
+ 0
indicates that garbage collection is off.
H5Pget_external_count
(hid_t plist
- )
+ H5Pget_istore_k
(hid_t plist
,
+ int * ik
+ )
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.
plist
- ik
+ H5Pget_external
(hid_t plist
,
- int idx
,
- size_t name_size
,
- char *name
,
- off_t *offset
,
- hsize_t *size
- )
+ H5Pget_layout
(hid_t plist
)
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.
+
plist
- idx
- name_size
- name
array.
- *name
- *offset
- *size
- + Otherwise, returns a negative value indicating faliure.
H5Pset_fill_value
(hid_t plist_id
,
- hid_t type_id
,
- const void *value
+ H5Pget_meta_block_size
(
+ hid_t fapl_id
,
+ hsize_t *size
)
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.
-
- 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
.
plist_id
- type_id
,
- value
.
- value
- fapl_id
+ size
+ H5Pget_fill_value
(hid_t plist_id
,
- hid_t type_id
,
- void *value
+ H5Pset_multi_type
(
+ hid_t fapl_id
,
+ H5FD_mem_t *type
)
MULTI
driver.
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. -
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.
plist_id
- type_id
,
- value
.
- value
- fapl_id
+ type
+ H5Pfill_value_defined
(hid_t plist_id
,
- H5D_fill_value_t *status
- )
+ H5Pget_nfilters
(hid_t plist
)
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. - |
+ H5Pget_nfilters
returns the number of filters
+ in the pipeline, including zero (0
) if there
+ are none.
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. +
plist_id
must be a dataset creation
+ property list.
plist_id
- status
- plist
+ H5Pset_fill_time
(hid_t plist_id
,
- H5D_fill_time_t fill_time
- )
+ H5Pget_nprops
(
+ hid_t id
,
+ size_t *nprops
+ )
+
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. - |
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
.
+
plist_id
- fill_time
- hid_t id |
+ IN: Identifier of property object to query |
size_t *nprops |
+ OUT: Number of properties in object |
H5Pget_fill_time
(hid_t plist_id
,
- H5D_fill_time_t *fill_time
- )
+ H5Pget_preserve
(hid_t plist
)
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. - |
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.
plist_id
- fill_time
- plist
+ H5Pset_alloc_time
(hid_t plist_id
,
- H5D_alloc_time_t alloc_time
- )
+ H5Pget_sieve_buf_size
(
+ hid_t fapl_id
,
+ hsize_t *size
+ )
+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.) - 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.) - |
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
.
plist_id
- alloc_time
- fapl_id
+ size
+ H5Pget_alloc_time
(hid_t plist_id
,
- H5D_alloc_time_t *alloc_time
- )
+ H5Pget_size
(
+ hid_t id
,
+ const char *name
,
+ size_t *size
+ )
+
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. - |
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
.
- -
plist_id
- alloc_time
- 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
.
+
+
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 |
H5Pset_filter
(hid_t plist
,
- H5Z_filter_t filter
,
- unsigned int flags
,
- size_t cd_nelmts
,
- const unsigned int cd_values[]
- )
+ H5Pget_sizes
(hid_t plist
,
+ size_t * sizeof_addr
,
+ size_t * sizeof_size
+ )
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. - -
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.
plist
- filter
- flags
- cd_nelmts
- cd_values
.
- cd_values[]
- size
+ size
+ H5Pall_filters_avail
(hid_t dcpl_id
)
+ H5Pget_small_data_block_size
(hid_t fapl_id
,
+ hsize_t *size
+ )
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.
dcpl_id
- fapl_id
+ size
+ TRUE
if all filters are available
- and FALSE
if one or more is not currently available.FAIL
, a negative value, on error.
-
H5Pget_nfilters
(hid_t plist
)
+ H5Pget_sym_k
(hid_t plist
,
+ int * ik
,
+ int * lk
+ )
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.
-
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.
plist
- ik
+ size
+ H5Pget_filter
(hid_t plist
,
- int filter_number
,
- unsigned int *flags
,
- size_t *cd_nelmts
,
- unsigned int *cd_values
,
- size_t namelen
,
- char name[]
- )
+ H5Pget_userblock
(hid_t plist
,
+ hsize_t * size
+ )
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
.
-
plist
must be a dataset creation property
- list.
+ H5Pget_userblock
retrieves the size of a user block
+ in a file creation property list.
plist
- filter_number
- flags
- cd_nelmts
- cd_values
.
- cd_values
- namelen
- name
.
- name[]
- size
+
- 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 - |
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[]
- )
+ H5Pget_version
(hid_t plist
,
+ int * super
,
+ int * freelist
,
+ int * stab
,
+ int * shhdr
+ )
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.
-
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.
+ plist_id
- filter
- flags
- cd_nelmts
- cd_values
.
- cd_values[]
- namelen
- name[]
.
- name[]
- plist
+ super
+ freelist
+ stab
+ shhdr
+ H5Pmodify_filter
(hid_t plist
,
- H5Z_filter_t filter
,
- unsigned int flags
,
- size_t cd_nelmts
,
- const unsigned int cd_values[]
+ H5Pget_vlen_mem_manager
(hid_t plist
,
+ H5MM_allocate_t *alloc
,
+ void **alloc_info
,
+ H5MM_free_t *free
,
+ void **free_info
)
H5Dread
and H5Dvlen_reclaim
.
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.
-
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.
plist_id
- filter
- flags
- cd_nelmts
- cd_values
.
- cd_values[]
- plist
+ alloc
+ NULL
+ for system malloc
.
+ alloc_info
+ NULL
.
+ free
+ NULL
for
+ system free
.
+ free_info
+ NULL
.
H5Pset_shuffle
(hid_t plist_id
)
- 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. -
plist_id
- H5Pset_fletcher32
(hid_t plist
)
- H5Pset_fletcher32
sets the Fletcher32 checksum filter
- in the dataset creation property list plist
.
- plist
- 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
+ )
-H5Pset_szip
(hid_t plist
,
- unsigned int options_mask
,
- unsigned int pixels_per_block
)
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. - |
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 |
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.
-
H5_SZIP_EC_OPTION_MASK
or
- H5_SZIP_NN_OPTION_MASK
, is specified.
- 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.
-
-
- 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. - -
plist
- options_mask
- pixels_per_block
- H5Pset_edc_check
(hid_t plist
,
- H5Z_EDC_t check
)
+ H5Pisa_class
(
+ hid_t plist
,
+ hid_t pclass
+ )
+
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. -
H5Pisa_class
checks to determine whether a property list
+ is a member of the specified class.
+
plist
- check
- hid_t plist |
+ IN: Identifier of the property list |
hid_t pclass |
+ IN: Identifier of the property class |
H5Piterate
(
+ hid_t id
,
+ int * idx
,
+ H5P_iterate_t iter_func
,
+ void * iter_data
+ )
+
+ 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.
+
H5P_iterate_t
operator is
+ as follows:
+ H5P_iterate_t
)(
+ hid_t id
,
+ const char *>name
,
+ void *iter_data
+ )
+ 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.
+
+
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 |
iter_func
if it was non-zero;
+ zero if all properties have been processed
+ H5Pget_edc_check
(hid_t plist
)
+ H5Pmodify_filter
(hid_t plist
,
+ H5Z_filter_t filter
,
+ unsigned int flags
,
+ size_t cd_nelmts
,
+ const unsigned int cd_values[]
+ )
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.
+
plist_id
must be a dataset creation
+ property list.
plist
- plist_id
+ filter
+ flags
+ cd_nelmts
+ cd_values
.
+ cd_values[]
+ H5P_ENABLE_EDC
or H5P_DISABLE_EDC
- if successful;
+ H5Pset_filter_callback
(hid_t plist
,
- H5Z_filter_func_t func
,
- void *op_data
)
+ 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
+ )
+
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
.
-
plist
- func
- op_data
- 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.
+
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:
+ H5P_prp_create_func_t
)(
+ const char *name
,
+ size_t size
,
+ void *initial_value
);
+ 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 |
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:
+ prop_id
,
+ const char *name
,
+ size_t size
,
+ void *new_value
);
+ 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 |
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:
+
H5P_prp_get_func_t
)(
+ hid_t prop_id
,
+ const char *name
,
+ size_t size
,
+ void *value
);
+ 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 |
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:
+ H5P_prp_delete_func_t
)(
+ hid_t prop_id
,
+ const char *name
,
+ size_t size
,
+ void *value
);
+ 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 |
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:
+ H5P_prp_copy_func_t
)(
+ const char *name
,
+ size_t size
,
+ void *value
);
+ 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 |
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.
+
-H5Pset_meta_block_size
(
- hid_t fapl_id
,
- hsize_t size
- )
- 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. -
fapl_id
- size
- 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:
+ H5P_prp_close_func_t
)(
+ hid_t prop_id
,
+ const char *name
,
+ size_t size
,
+ void *value
);
+ 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 |
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.
+
+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
+ H5Pget_meta_block_size
(
- hid_t fapl_id
,
- hsize_t *size
- )
- 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
.
-
fapl_id
- size
- H5Pset_sieve_buf_size
(
- hid_t fapl_id
,
- hsize_t size
- )
+ H5Premove
(plid, name
)
+ hid_t plid
;
+ const char *name
+ )
+
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.
+
fapl_id
- size
- hid_t plid |
+ IN: Identifier of the property list to modify |
const char *name |
+ IN: Name of property to remove |
H5Pget_sieve_buf_size
(
- hid_t fapl_id
,
- hsize_t *size
- )
-H5Pset
(
+ hid_t plid
,
+ const char *name
,
+ void *value
)
+ )
+
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
.
-
fapl_id
- size
- 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. + +
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 |
H5Pset_gc_reference
(hid_t plist
,
- unsigned gc_ref
+ H5Pset_alignment
(hid_t plist
,
+ hsize_t threshold
,
+ hsize_t alignment
)
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.
plist
- gc_ref
- 1
) or off (0
).
+ threshold
+ alignment
+ H5Pget_gc_references
(hid_t plist
,
- unsigned *gc_ref
- )
+ H5Pset_alloc_time
(hid_t plist_id
,
+ H5D_alloc_time_t alloc_time
+ )
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.) + 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.) + |
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.
plist
- gc_ref
- 1
indicates that
- garbage collection is on while
- 0
indicates that garbage collection is off.
+ plist_id
+ alloc_time
+ H5Pset_cache
(hid_t plist_id
,
- int mdc_nelmts
,
- int rdcc_nelmts
,
- size_t rdcc_nbytes
,
- double rdcc_w0
+ H5Pset_btree_ratios
(hid_t plist
,
+ double left
,
+ double middle
,
+ double right
)
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.
plist_id
- mdc_nelmts
- rdcc_nelmts
- rdcc_nbytes
- rdcc_w0
- plist
+ left
+ right
+ middle
+ H5Pget_cache
(hid_t plist_id
,
- int *mdc_nelmts
,
- int *rdcc_nelmts
,
- size_t *rdcc_nbytes
,
- double *rdcc_w0
- )
+ H5Pset_buffer
(hid_t plist
,
+ hsize_t size
,
+ void *tconv
,
+ void *bkg
+ )
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. +
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.
plist_id
- *mdc_nelmts
- *rdcc_nelmts
- *rdcc_nbytes
- *rdcc_w0
- plist
+ size
+ tconv
+ bkg
+ H5Pset_hyper_vector_size
(hid_t dxpl_id
,
- size_t vector_size
+ H5Pset_cache
(hid_t plist_id
,
+ int mdc_nelmts
,
+ int rdcc_nelmts
,
+ size_t rdcc_nbytes
,
+ double rdcc_w0
)
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.
dxpl_id
- vector_size
- 1
(one).
- Default value: 1024
.
+ plist_id
+ mdc_nelmts
+ rdcc_nelmts
+ rdcc_nbytes
+ rdcc_w0
+ H5Pget_hyper_vector_size
(hid_t dxpl_id
,
- size_t *vector_size
- )
+ H5Pset_chunk
(hid_t plist
,
+ int ndims
,
+ const hsize_t * dim
+ )
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.
dxpl_id
- vector_size
- plist
+ ndims
+ dim
+ H5Pset_btree_ratios
(hid_t plist
,
- double left
,
- double middle
,
- double right
+ H5Pset_deflate
(hid_t plist
,
+ int level
)
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.
plist
- left
- right
- middle
- level
+ H5Pset_buffer
(hid_t plist
,
- hsize_t size
,
- void *tconv
,
- void *bkg
- )
+ H5Pset_dxpl_mpio
(
+ hid_t dxpl_id
,
+ H5FD_mpio_xfer_t xfer_mode
+ )
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
+ H5FD_MPIO_COLLECTIVE
+ plist
- size
- tconv
- bkg
- dxpl_id
+ xfer_mode
+ H5Pset_dxpl_multi
(
+ hid_t dxpl_id
,
+ const hid_t *memb_dxpl
+ )
+ 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
.
+
dxpl_id
,
+ memb_dxpl
+ H5Pget_buffer
(hid_t plist
,
- void **tconv
,
- void **bkg
- )
+ H5Pset_edc_check
(hid_t plist
,
+ H5Z_EDC_t check
)
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. +
plist
- **tconv
- **bkg
- check
+ H5Pset_small_data_block_size
(hid_t fapl_id
,
+ H5Pset_external
(hid_t plist
,
+ const char *name
,
+ off_t offset
,
hsize_t size
- )
+ )
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.
fapl_id
- plist
+ *name
+ offset
+ size
- 2048
.
+ H5Pget_small_data_block_size
(hid_t fapl_id
,
- hsize_t *size
- )
+ H5Pset_family_offset
(
+ hid_t fapl_id
,
+ hsize_t offset
+ )
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.
fapl_id
- size
- offset
+ H5Pset_preserve
(hid_t plist
,
- hbool_t status
- )
+ H5Pset_fapl_core
(
+ hid_t fapl_id
,
+ size_t increment
,
+ hbool_t backing_store
+ )
H5FD_CORE
driver.
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. -
plist
- status
- H5Pget_preserve
(hid_t plist
)
- 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.
+
H5FD_CORE
driver to manipulate the file.
plist
- fapl_id
+ increment
+ backing_store
+ H5Pset_compression
(hid_t plist
,
- H5Z_method_t method
,
- unsigned int flags
,
- size_t cd_size
,
- const void *client_data
+ H5Pset_fapl_family
(
+ hid_t fapl_id
,
+ hsize_t memb_size
,
+ hid_t memb_fapl_id
)
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.
plist
- method
- flags
- cd_size
- client_data
.
- *client_data
- fapl_id
+ memb_size
+ memb_fapl_id
+ H5Pset_deflate
(hid_t plist
,
- int level
+ H5Pset_fapl_gass
(
+ hid_t fapl_id
,
+ GASS_Info info
)
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.
+
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/.
plist
- level
- fapl_id
,
+ info
+ H5Pget_deflate
(hid_t plist
+ H5Pset_fapl_log
(
+ hid_t fapl_id
,
+ const char *logfile
,
+ unsigned int flags
,
+ size_t buf_size
)
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. + + 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.
+
plist
- fapl_id
+ logfile
+ flags
+ buf_size
+ H5Pset_vlen_mem_manager
(hid_t plist
,
- H5MM_allocate_t alloc
,
- void *alloc_info
,
- H5MM_free_t free
,
- void *free_info
+ H5Pset_fapl_mpio
(
+ hid_t fapl_id
,
+ MPI_Comm comm
,
+ MPI_Info info
)
H5Dread
and H5Dvlen_reclaim
.
+ 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.
plist
- alloc
- NULL
- for system malloc
.
- alloc_info
- NULL
.
- free
- NULL
- for system free
.
- free_info
- NULL
.
+ fapl_id
+ comm
+ info
+ H5Pget_vlen_mem_manager
(hid_t plist
,
- H5MM_allocate_t *alloc
,
- void **alloc_info
,
- H5MM_free_t *free
,
- void **free_info
+ H5Pset_fapl_mpiposix
(
+ hid_t fapl_id
,
+ MPI_Comm comm
)
H5Dread
and H5Dvlen_reclaim
.
+ 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.
plist
- alloc
- NULL
- for system malloc
.
- alloc_info
- NULL
.
- free
- NULL
for
- system free
.
- free_info
- NULL
.
+ fapl_id
+ comm
+ H5Pset_fapl_family
(
- hid_t fapl_id
,
- hsize_t memb_size
,
- hid_t memb_fapl_id
+ 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
)
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
+ H5FD_MEM_DEFAULT
for each element.
+ memb_fapl
+ H5P_DEFAULT
for each element.
+ memb_name
+ %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
+ HADDR_UNDEF
for each element.
+ fapl_id
memb_size
- memb_fapl_id
- memb_map
+ memb_fapl
+ memb_name
+ memb_addr
+ 0
(zero) to HADDR_MAX
,
+ at which each type of data storage begins.
+ relax
+ TRUE
.
+ 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); +
H5Pget_fapl_family
(
- hid_t fapl_id
,
- hsize_t *memb_size
,
- hid_t *memb_fapl_id
+ H5Pset_fapl_sec2
(
+ hid_t fapl_id
)
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.
fapl_id
memb_size
- memb_fapl_id
- H5Pset_family_offset
(
- hid_t fapl_id
,
- hsize_t offset
+ 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
)
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
.
fapl_id
+ fapl_id
,
offset
- meta_ext
,
+ meta_plist_id
,
+ raw_ext
,
+ raw_plist_id
+ +/* 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); +
H5Pget_family_offset
(
- hid_t fapl_id
,
- hsize_t *offset
+ H5Pset_fapl_srb
(
+ hid_t fapl_id
,
+ SRB_Info info
)
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.
+
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/.
fapl_id
offset
- info
+ H5Pset_fapl_log
(
- hid_t fapl_id
,
- const char *logfile
,
- unsigned int flags
,
- size_t buf_size
+ H5Pset_fapl_stdio
(
+ hid_t fapl_id
)
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. - - 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
.
+ fapl_id
+
- 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.
-
+
+
+
H5Pset_fapl_stream
(
+ hid_t fapl_id
,
+ H5FD_stream_fapl_t *fapl
+ )
+ 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.
fapl_id
logfile
- flags
- buf_size
- fapl
+ H5Pset_fclose_degree
(hid_t fapl_id
,
+ H5F_close_degree_t fc_degree
)
+ 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 .
+ |
+
fapl_id
+ fc_degree
+ fc_degree
.
+ H5Pset_fapl_mpio
(
- hid_t fapl_id
,
- MPI_Comm comm
,
- MPI_Info info
- )
+ H5Pset_fill_time
(hid_t plist_id
,
+ H5D_fill_time_t fill_time
+ )
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. + |
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.
fapl_id
- comm
- info
- plist_id
+ fill_time
+ H5Pget_fapl_mpio
(
- hid_t fapl_id
,
- MPI_Comm *comm
,
- MPI_Info *info
+ H5Pset_fill_value
(hid_t plist_id
,
+ hid_t type_id
,
+ const void *value
)
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.
+
+ 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.
fapl_id
- comm
- info
- plist_id
+ type_id
,
+ value
.
+ value
+ H5Pset_fapl_mpiposix
(
- hid_t fapl_id
,
- MPI_Comm comm
+ H5Pset_filter
(hid_t plist
,
+ H5Z_filter_t filter
,
+ unsigned int flags
,
+ size_t cd_nelmts
,
+ const unsigned int cd_values[]
)
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.
- 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.
+ 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. + +
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.
fapl_id
- comm
- plist
+ filter
+ flags
+ cd_nelmts
+ cd_values
.
+ cd_values[]
+ H5Pget_fapl_mpiposix
(
- hid_t fapl_id
,
- MPI_Comm *comm
- )
+ H5Pset_filter_callback
(hid_t plist
,
+ H5Z_filter_func_t func
,
+ void *op_data
)
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
.
fapl_id
- comm
- plist
+ func
+ op_data
+ H5Pset_dxpl_mpio
(
- hid_t dxpl_id
,
- H5FD_mpio_xfer_t xfer_mode
- )
+ H5Pset_fletcher32
(hid_t plist
)
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
- H5FD_MPIO_COLLECTIVE
- H5Pset_fletcher32
sets the Fletcher32 checksum filter
+ in the dataset creation property list plist
.
+ dxpl_id
- xfer_mode
- plist
+ H5Pget_dxpl_mpio
(
- hid_t dxpl_id
,
- H5FD_mpio_xfer_t *xfer_mode
+ H5Pset_gc_reference
(hid_t plist
,
+ unsigned gc_ref
)
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.
dxpl_id
- xfer_mode
- plist
+ gc_ref
+ 1
) or off (0
).
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
+ H5Pset_hyper_cache
(hid_t plist
,
+ unsigned cache
,
+ unsigned limit
)
H5Pset_fapl_multi
sets the file access property list
- fapl_id
to use the multi-file driver.
+ 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
- H5FD_MEM_DEFAULT
for each element.
- memb_fapl
- H5P_DEFAULT
for each element.
- memb_name
- %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
- HADDR_UNDEF
for each element.
- fapl_id
- memb_map
- memb_fapl
- memb_name
- memb_addr
- 0
(zero) to HADDR_MAX
,
- at which each type of data storage begins.
- relax
- TRUE
.
+ plist
+ cache
+ 1
) or off (0
).
+ limit
+ 0
(zero) indicates no limit.
- 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); -+
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
+ H5Pset_hyper_vector_size
(hid_t dxpl_id
,
+ size_t vector_size
)
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
.
fapl_id
- memb_map
- memb_fapl
- memb_name
- memb_addr
- relax
- TRUE
.
+ dxpl_id
+ vector_size
+ 1
(one).
+ Default value: 1024
.
H5Pset_dxpl_multi
(
- hid_t dxpl_id
,
- const hid_t *memb_dxpl
- )
+ H5Pset_istore_k
(hid_t plist
,
+ int ik
+ )
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
.
dxpl_id
,
- memb_dxpl
- plist
+ ik
+ H5Pget_dxpl_multi
(
- hid_t dxpl_id
,
- const hid_t *memb_dxpl
- )
-H5Pset_layout
(hid_t plist
,
+ H5D_layout_t layout
+ )
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:
+
+ Note that a compact storage layout may affect writing data to + the dataset with parallel applications. See note in + H5Dwrite + documentation for details.
dxpl_id
,
- memb_dxpl
- plist
+ layout
+ H5Pset_fapl_split
(
+ 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
)
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.
fapl_id
,
+ fapl_id
meta_ext
,
- meta_plist_id
,
- raw_ext
,
- raw_plist_id
- size
+ -/* 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); -
H5Pset_multi_type
(
- hid_t fapl_id
,
- H5FD_mem_t *type
- )
- MULTI
driver.
- 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.
-
fapl_id
- type
- H5Pset_fapl_sec2
(
- hid_t fapl_id
- )
- H5Pset_fapl_sec2
modifies the file access property list
- to use the H5FD_SEC2
driver.
- fapl_id
- H5Pset_fapl_stdio
(
- hid_t fapl_id
- )
- H5Pset_fapl_stdio
modifies the file access property list
- to use the standard I/O driver, H5FD_STDIO
.
- fapl_id
- H5Pset_fapl_stream
(
- hid_t fapl_id
,
- H5FD_stream_fapl_t *fapl
- )
+ H5Pset_preserve
(hid_t plist
,
+ hbool_t status
+ )
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.
fapl_id
- fapl
- plist
+ status
+ H5Pget_fapl_stream
(
- hid_t fapl_id
,
- H5FD_stream_fapl_t *fapl
- )
+ H5Pset_shuffle
(hid_t plist_id
)
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.
fapl_id
- fapl
- plist_id
+ H5Pset_driver
(
- hid_t plist_id
,
- hid_t driver_id
,
- const void * driver_info
+ H5Pset_sieve_buf_size
(
+ hid_t fapl_id
,
+ hsize_t size
)
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.
plist_id
- driver_id
- driver_info
- fapl_id
+ size
+ H5Pget_driver
(
- hid_t plist_id
- )
+ H5Pset_sizes
(hid_t plist
,
+ size_t sizeof_addr
,
+ size_t sizeof_size
+ )
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.
plist_id
- plist
+ sizeof_addr
+ sizeof_size
+ H5Pget_driver_info
(
- hid_t plist_id
- )
+ H5Pset_small_data_block_size
(hid_t fapl_id
,
+ hsize_t size
+ )
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.
plist_id
- fapl_id
+ size
+ 2048
.
NULL
.
-
- NULL
is also returned if no driver-specific properties
- have been registered.
- No error is pushed on the stack in this case.
+
H5Pset_fapl_gass
(
- hid_t fapl_id
,
- GASS_Info info
- )
+ H5Pset_sym_k
(hid_t plist
,
+ int ik
,
+ int lk
+ )
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.
-
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
.
fapl_id
,
- info
- plist
+ ik
+ lk
+ H5Pget_fapl_gass
(
- hid_t fapl_id
,
- GASS_Info *info
- )
+ H5Pset_szip
(hid_t plist
,
+ unsigned int options_mask
,
+ unsigned int pixels_per_block
)
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. -
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. + |
+ + |
+ + |
H5_SZIP_EC_OPTION_MASK
or
+ H5_SZIP_NN_OPTION_MASK
, is specified.
+ 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.
+
+
+ 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. +
fapl_id
,
- info
- plist
+ options_mask
+ pixels_per_block
+ H5Pset_fapl_srb
(
- hid_t fapl_id
,
- SRB_Info info
- )
+ H5Pset_userblock
(hid_t plist
,
+ hsize_t size
+ )
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.
-
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.).
fapl_id
- info
- plist
+ size
+ H5Pget_fapl_srb
(
- hid_t fapl_id
,
- SRB_Info *info
+ H5Pset_vlen_mem_manager
(hid_t plist
,
+ H5MM_allocate_t alloc
,
+ void *alloc_info
,
+ H5MM_free_t free
,
+ void *free_info
)
H5Dread
and H5Dvlen_reclaim
.
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. -
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.
fapl_id
- info
- plist
+ alloc
+ NULL
+ for system malloc
.
+ alloc_info
+ NULL
.
+ free
+ NULL
+ for system free
.
+ free_info
+ NULL
.
H5Punregister
(
+ H5P_class_t class
,
+ const char *name
+ )
+
+ 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. + +
H5P_class_t class |
+ IN: Property list class from which to remove + permanent property |
const char *name |
+ IN: Name of property to remove |
H5Pset_fclose_degree
(hid_t fapl_id
,
- H5F_close_degree_t fc_degree
)
- 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 .
- |
-
fapl_id
- fc_degree
- fc_degree
.
-