|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |
The C Interfaces:
Alphabetical Listing
H5Pall_filters_avail(hid_t dcpl_id)
H5Pall_filters_avail verifies that all of the filters
set in the dataset creation property list dcpl_id are
currently available.
hid_t dcpl_id |
IN: Dataset creation property list identifier. |
TRUE if all filters are available
and FALSE if one or more is not currently available.FAIL, a negative value, on error.
H5Pclose(hid_t plist
)
H5Pclose terminates access to a property list.
All property lists should be closed when the application is
finished accessing them.
This frees resources used by the property list.
hid_t plist |
IN: Identifier of the property list to terminate access to. |
SUBROUTINE h5pclose_f(prp_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pclose_f
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 |
SUBROUTINE h5pclose_class_f(class, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: class ! Property list class identifier
! to close
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pclose_class_f
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 |
SUBROUTINE h5pclose_list_f(plist, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist ! Property list identifier to close
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pclose_list_f
H5Pcopy(hid_t plist
)
H5Pcopy copies an existing property list to create
a new property list.
The new property list has the same properties and values
as the original property list.
hid_t plist |
IN: Identifier of property list to duplicate. |
SUBROUTINE h5pcopy_f(prp_id, new_prp_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HID_T), INTENT(OUT) :: new_prp_id ! Identifier of property list
! copy
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pcopy_f
H5Pcopy_prop(
hid_t dst_id,
hid_t src_id,
const char *name
)
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).
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 |
SUBROUTINE h5pcopy_prop_f(dst_id, src_id, name, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: dst_id ! Destination property list
! identifier
INTEGER(HID_T), INTENT(IN) :: src_id ! Source property list identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Property name
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pcopy_prop_f
H5Pcreate(hid_t cls_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.
This property list must eventually be closed with
H5Pclose;
otherwise, errors are likely to occur.
hid_t cls_id |
IN: The class of the property list to create. |
plist) if successful;
otherwise Fail (-1).
SUBROUTINE h5pcreate_f(classtype, prp_id, hdferr)
IMPLICIT NONE
INTEGER, INTENT(IN) :: classtype ! The type of the property list
! to be created
! Possible values are:
! H5P_FILE_CREATE_F
! H5P_FILE_ACCESS_F
! H5P_DATASET_CREATE_F
! H5P_DATASET_XFER_F
! H5P_MOUNT_F
INTEGER(HID_T), INTENT(OUT) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pcreate_f
H5Pcreate_class(
hid_t class,
const char *name,
H5P_cls_create_func_t create,
H5P_cls_copy_func_t copy,
H5P_cls_close_func_t close
)
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 the property 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)(
hid_t prop_id,
void * close_data
);
hid_t prop_id |
IN: The identifier of the property list being closed |
void * close_data |
IN/OUT: User pointer to any class close information needed |
close routine is called before any registered
close function is called for each property value.
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 |
IN: Property list class to inherit from. |
const char *name |
IN: Name of property list class to register |
H5P_cls_create_func_t create |
IN: Callback routine called when a property list is created |
H5P_cls_copy_func_t copy |
IN: Callback routine called when a property list is copied |
H5P_cls_close_func_t close |
IN: Callback routine called when a property list is being closed |
SUBROUTINE h5pcreate_class_f(parent, name, class, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: parent ! Parent property list class
! identifier
! Possible values include:
! H5P_NO_CLASS_F
! H5P_FILE_CREATE_F
! H5P_FILE_ACCESS_F
! H5P_DATASET_CREATE_F
! H5P_DATASET_XFER_F
! H5P_MOUNT_F
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to create
INTEGER(HID_T), INTENT(OUT) :: class ! Property list class identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pcreate_class_f
H5Pcreate_list(
hid_t class)
H5Pcreate_list creates a new property list of a
given class. If a create callback exists for the
property list class, it is called before the property list
is passed back to the user.
If create callbacks exist for any individual properties
in the property list, they are called before the class
create callback.
hid_t class; |
IN: Class of property list to create. |
H5Premove_filter(hid_t plist,
H5Z_filter_t filter
)
H5Premove_filter removes the specified
filter from the filter pipeline in the
dataset creation property list plist.
The filter parameter specifies the filter to be removed.
Valid values for use in filter are as follows:
H5Z_FILTER_ALL
| Removes all filters from the permanent filter pipeline. |
H5Z_FILTER_DEFLATE
| Data compression filter, employing the gzip algorithm |
H5Z_FILTER_SHUFFLE
| Data shuffling filter |
H5Z_FILTER_FLETCHER32
| Error detection filter, employing the Fletcher32 checksum algorithm |
H5Z_FILTER_SZIP
| Data compression filter, employing the SZIP algorithm |
Additionally, user-defined filters can be removed with this routine by passing the filter identifier with which they were registered with the HDF5 Library.
Attempting to remove a filter that is not in the permanent filter pipeline is an error.
plist must be a dataset creation
property list.
plist_id
filter
SUBROUTINE h5premove_filter_f(prp_id, filter, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset creation property
! list identifier
INTEGER, INTENT(IN) :: filter ! Filter to be removed
! Valid values are:
! H5Z_FILTER_ALL_F
! H5Z_FILTER_DEFLATE_F
! H5Z_FILTER_SHUFFLE_F
! H5Z_FILTER_FLETCHER32_F
! H5Z_FILTER_SZIP_F
!
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success, -1 on failure
END SUBROUTINE h5premove_filter_f
H5Pequal(
hid_t id1,
hid_t id2
)
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.
hid_t id1 |
IN: First property object to be compared |
hid_t id2 |
IN: Second property object to be compared |
SUBROUTINE h5pequal_f(plist1_id, plist2_id, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist1_id ! Property list identifier
INTEGER(HID_T), INTENT(IN) :: plist2_id ! Property list identifier
LOGICAL, INTENET(OUT) :: flag ! Flag
! .TRUE. if lists are equal
! .FALSE. otherwise
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pequal_f
H5Pexist(
hid_t id;
const char *name
)
H5Pexist determines whether a property exists
within a property list or class.
hid_t id |
IN: Identifier for the property to query |
const char *name |
IN: Name of property to check for |
SUBROUTINE h5pexist_f(prp_id, name, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to modify
LOGICAL, INTENT(OUT) :: flag ! Logical flag
! .TRUE. if exists
! .FALSE. otherwise
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pexist_f
H5Pfill_value_defined(hid_t plist_id,
H5D_fill_value_t *status
)
H5Pfill_value_defined determines whether a fill value
is defined in the dataset creation property list plist_id.
Valid values returned 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.
hid_t plist_id |
IN: Dataset creation property list identifier. |
H5D_fill_value_t *status |
OUT: Status of fill value in property list. |
H5Pget(
hid_t plid,
const char *name,
void *value
)
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.
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: Identifier of the property list to query |
const char *name |
IN: Name of property to query |
void *value |
OUT: Pointer to a location to which to copy the value of of the property |
SUBROUTINE h5pget_f(plid, name, value, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plid ! Property list identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to get
TYPE, INTENT(OUT) :: value ! Property value
! Supported types are:
! INTEGER
! REAL
! DOUBLE PRECISION
! CHARACTER(LEN=*)
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_f
H5Pget_alignment(hid_t plist,
hsize_t *threshold,
hsize_t *alignment
)
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 plist |
IN: Identifier of a file access property list. |
hsize_t *threshold |
OUT: Pointer to location of return threshold value. |
hsize_t *alignment |
OUT: Pointer to location of return alignment value. |
SUBROUTINE h5pget_alignment_f(prp_id, threshold, alignment, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HSIZE_T), INTENT(OUT) :: threshold ! Threshold value
INTEGER(HSIZE_T), INTENT(OUT) :: alignment ! Alignment value
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_alignment_f
H5Pget_alloc_time(hid_t plist_id,
H5D_alloc_time_t *alloc_time
)
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 plist_id |
IN: Dataset creation property list identifier. |
H5D_alloc_time_t *alloc_time |
IN: When to allocate dataset storage space. |
SUBROUTINE h5pget_alloc_time_f(plist_id, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation
! property list identifier
INTEGER(HSIZE_T), INTENT(OUT) :: flag ! Allocation time flag
! Possible values are:
! H5D_ALLOC_TIME_ERROR_F
! H5D_ALLOC_TIME_DEFAULT_F
! H5D_ALLOC_TIME_EARLY_F
! H5D_ALLOC_TIME_LATE_F
! H5D_ALLOC_TIME_INCR_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_alloc_time_f
H5Pget_btree_ratios(hid_t plist,
double *left,
double *middle,
double *right
)
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 plist |
IN: The dataset transfer property list identifier. |
double left |
OUT: The B-tree split ratio for left-most nodes. |
double right |
OUT: The B-tree split ratio for right-most nodes and lone nodes. |
double middle |
OUT: The B-tree split ratio for all other nodes. |
SUBROUTINE h5pget_btree_ratios_f(prp_id, left, middle, right, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id
! Property list identifier
REAL, INTENT(OUT) :: left ! B-tree split ratio for left-most nodes
REAL, INTENT(OUT) :: middle ! B-tree split ratio for all other nodes
REAL, INTENT(OUT) :: right ! The B-tree split ratio for right-most
! nodes and lone nodes.
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_btree_ratios_f
H5Pget_buffer(hid_t plist,
void **tconv,
void **bkg
)
H5Pget_buffer reads values previously set
with H5Pset_buffer.
hid_t plist |
IN: Identifier for the dataset transfer property list. |
void **tconv |
OUT: Address of the pointer to application-allocated type conversion buffer. |
void **bkg |
OUT: Address of the pointer to application-allocated background buffer. |
SUBROUTINE h5pget_buffer_f(plist_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset transfer
! property list identifier
INTEGER(HSIZE_T), INTENT(OUT) :: size ! Conversion buffer size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_buffer_f
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.
hid_t plist_id |
IN: Identifier of the file access property list. |
int *mdc_nelmts |
IN/OUT: Number of elements (objects) in the meta data cache. |
int *rdcc_nelmts |
IN/OUT: Number of elements (objects) in the raw data chunk cache. |
size_t *rdcc_nbytes |
IN/OUT: Total size of the raw data chunk cache, in bytes. |
double *rdcc_w0 |
IN/OUT: Preemption policy. |
SUBROUTINE h5pget_cache_f(prp_id, mdc_nelmts, rdcc_nelmts, rdcc_nbytes,
rdcc_w0, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: mdc_nelmts ! Number of elements (objects)
! in the meta data cache
INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nelmts ! Number of elements (objects)
! in the meta data cache
INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nbytes ! Total size of the raw data
! chunk cache, in bytes
REAL, INTENT(OUT) :: rdcc_w0 ! Preemption policy
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_cache_f
H5Pget_chunk(hid_t plist,
int max_ndims,
hsize_t * dims
)
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 plist |
IN: Identifier of property list to query. |
int max_ndims |
IN: Size of the dims array. |
hsize_t * dims |
OUT: Array to store the chunk dimensions. |
SUBROUTINE h5pget_chunk_f(prp_id, ndims, dims, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: ndims ! Number of chunk dimensions
! to return
INTEGER(HSIZE_T), DIMENSION(ndims), INTENT(OUT) :: dims
! Array containing sizes of
! chunk dimensions
INTEGER, INTENT(OUT) :: hdferr ! Error code
! chunk rank on success
! and -1 on failure
END SUBROUTINE h5pget_chunk_f
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.
hid_t plist |
IN: Identifier of property list to query. |
SUBROUTINE h5pget_class_f(prp_id, classtype, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: classtype ! The type of the property list
! to be created
! Possible values are:
! H5P_NO_CLASS
! H5P_FILE_CREATE_F
! H5P_FILE_ACCESS_F
! H5PE_DATASET_CREATE_F
! H5P_DATASET_XFER_F
! H5P_MOUNT_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_class_f
H5Pget_class_name(
hid_t pcid
)
H5Pget_class_name retrieves the name of a
generic property list class. The pointer to the name
must be freed by the user after each successful call.
hid_t pcid |
IN: Identifier of the property class to query |
SUBROUTINE h5pget_class_name_f(prp_id, name, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier to
! query
CHARACTER(LEN=*), INTENT(INOUT) :: name ! Buffer to retrieve class name
INTEGER, INTENT(OUT) :: hdferr ! Error code, possible values:
! Success: Actual length of the
! class name
! If provided buffer "name" is
! smaller, than name will be
! truncated to fit into
! provided user buffer
! Failure: -1
END SUBROUTINE h5pget_class_name_f
H5Pget_class_parent(
hid_t pcid
)
H5Pget_class_parent retrieves an identifier for the
parent class of a property class.
hid_t pcid |
IN: Identifier of the property class to query |
SUBROUTINE h5pget_class_parent_f(prp_id, parent_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HID_T), INTENT(OUT) :: parent_id ! Parent class property list
! identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_class_parent_f
H5Pget_data_transform
(hid_t plist_id,
char *expression,
size_t size)
H5Pget_data_transform retrieves the data
transform expression previously set in the dataset transfer
property list plist_id by H5Pset_data_transform.
H5Pget_data_transform can be used to both
retrieve the transform expression and to query its size.
If expression is non-NULL, up to size
bytes of the data transform expression are written to the buffer.
If expression is NULL, size is ignored
and the function does not write anything to the buffer.
The function always returns the size of the data transform expression.
If 0 is returned for the size of the expression,
no data transform expression exists for the property list.
If an error occurs, the buffer pointed to by expression
is unchanged and the function returns a negative value.
hid_t plist_id |
IN: Identifier of the property list or class |
char *expression |
OUT: Pointer to memory where the transform expression will be copied |
size_t size |
IN: Number of bytes of the transform expression to copy to |
H5Pget_driver(
hid_t plist_id
)
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_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_id |
IN: File access or data transfer property list identifier. |
SUBROUTINE h5pget_driver_f(prp_id, driver, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: driver ! Low-level file driver identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_driver_f
H5Pget_dxpl_mpio(
hid_t dxpl_id,
H5FD_mpio_xfer_t *xfer_mode
)
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 dxpl_id |
IN: Data transfer property list identifier. |
H5FD_mpio_xfer_t *xfer_mode |
OUT: Data transfer mode. |
SUBROUTINE h5pget_dxpl_mpio_f(prp_id, data_xfer_mode, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: data_xfer_mode ! Data transfer mode
! Possible values are:
! H5FD_MPIO_INDEPENDENT_F
! H5FD_MPIO_COLLECTIVE_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_dxpl_mpio_f
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.
hid_t dxpl_id, |
IN: Data transfer property list identifier. |
const hid_t *memb_dxpl |
OUT: Array of data access property lists. |
H5Pget_edc_check(hid_t plist)
H5Pget_edc_check queries the dataset transfer property
list plist to determine whether error detection
is enabled for data read operations.
hid_t plist |
IN: Dataset transfer property list identifier. |
H5Z_ENABLE_EDC or H5Z_DISABLE_EDC
if successful;
otherwise returns a negative value.
SUBROUTINE h5pget_edc_check_f(prp_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset transfer property list
! identifier
INTEGER, INTENT(OUT) :: flag ! EDC flag; possible values
! H5Z_DISABLE_EDC_F
! H5Z_ENABLE_EDC_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_edc_check_f
H5Pget_external(hid_t plist,
unsigned idx,
size_t name_size,
char *name,
off_t *offset,
hsize_t *size
)
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 plist |
IN: Identifier of a dataset creation property list. |
unsigned idx |
IN: External file index. |
size_t name_size |
IN: Maximum length of name array. |
char *name |
OUT: Name of the external file. |
off_t *offset |
OUT: Pointer to a location to return an offset value. |
hsize_t *size |
OUT: Pointer to a location to return the size of the external file data. |
SUBROUTINE h5pget_external_f(prp_id, idx, name_size, name, offset,bytes, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: idx ! External file index.
INTEGER, INTENT(IN) :: name_size ! Maximum length of name array
CHARACTER(LEN=*), INTENT(OUT) :: name ! Name of an external file
INTEGER, INTENT(OUT) :: offset ! Offset, in bytes, from the
! beginning of the file to the
! location in the file where
! the data starts.
INTEGER(HSIZE_T), INTENT(OUT) :: bytes ! Number of bytes reserved in
! the file for the data
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_external_f
H5Pget_external_count(hid_t plist
)
H5Pget_external_count returns the number of external files
for the specified dataset.
hid_t plist |
IN: Identifier of a dataset creation property list. |
SUBROUTINE h5pget_external_count_f (prp_id, count, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: count ! Number of external files for
! the specified dataset
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_external_count_f
H5Pget_family_offset (
hid_t fapl_id,
hsize_t *offset
)
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 particular member
of a family of files. The file handle is retrieved with a separate call
to H5Fget_vfd_handle
(or, in special circumstances, to H5FDget_vfd_handle;
see Virtual File Layer and List of VFL Functions
in HDF5 Technical Notes).
The 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.
hid_t fapl_id |
IN: File access property list identifier. |
hsize_t *offset |
IN: Offset in bytes within the HDF5 file. |
H5Pget_fapl_core(
hid_t fapl_id,
size_t *increment,
hbool_t *backing_store
)
H5Pget_fapl_core queries the H5FD_CORE
driver properties as set by H5Pset_fapl_core.
hid_t fapl_id |
IN: File access property list identifier. |
size_t *increment |
OUT: Size, in bytes, of memory increments. |
hbool_t *backing_store |
OUT: Boolean flag indicating whether to write the file contents to disk when the file is closed. |
SUBROUTINE h5pget_fapl_core_f(prp_id, increment, backing_store, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(SIZE_T), INTENT(OUT) :: increment ! File block size in bytes
LOGICAL, INTENT(OUT) :: backing_store ! Flag to indicate that entire
! file contents are flushed to
! a file with the same name as
! this core file
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_fapl_core_f
H5Pget_fapl_family (
hid_t fapl_id,
hsize_t *memb_size,
hid_t *memb_fapl_id
)
H5Pget_fapl_family returns file access property list
for use with the family driver.
This information is returned through the output parameters.
hid_t fapl_id |
IN: File access property list identifier. |
hsize_t *memb_size |
OUT: Size in bytes of each file member. |
hid_t *memb_fapl_id |
OUT: Identifier of file access property list for each family member. |
SUBROUTINE h5pget_fapl_family_f(prp_id, imemb_size, memb_plist, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HSIZE_T), INTENT(OUT) :: memb_size ! Logical size, in bytes,
! of each family member
INTEGER(HID_T), INTENT(OUT) :: memb_plist ! Identifier of the file
! access property list to be
! used for each family member
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_fapl_family_f
H5Pget_fapl_gass(
hid_t fapl_id,
GASS_Info *info
)
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/.
hid_t fapl_id, |
IN: File access property list identifier. |
GASS_Info *info |
OUT: Pointer to the GASS information structure. |
H5Pget_fapl_mpio(
hid_t fapl_id,
MPI_Comm *comm,
MPI_Info *info
)
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.
hid_t fapl_id |
IN: File access property list identifier. |
MPI_Comm *comm |
OUT: MPI-2 communicator. |
MPI_Info *info |
OUT: MPI-2 info object. |
SUBROUTINE h5pget_fapl_mpio_f(prp_id, comm, info, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: comm ! Buffer to return communicator
INTEGER, INTENT(IN) :: info ! Buffer to return info object as
! defined in MPI_FILE_OPEN of MPI-2
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_fapl_mpio_f
H5Pget_fapl_mpiposix(
hid_t fapl_id,
MPI_Comm *comm
)
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.
hid_t fapl_id |
IN: File access property list identifier. |
MPI_Comm *comm |
OUT: MPI-2 communicator. |
SUBROUTINE h5pget_fapl_mpiposix_f(prp_id, comm, use_gpfs, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(OUT) :: comm ! Buffer to return communicator LOGICAL, INTENT(OUT) :: use_gpfs INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5pget_fapl_mpiposix_f
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_fapl_multi returns information about the
multi-file access property list.
hid_t fapl_id |
IN: File access property list identifier. |
const H5FD_mem_t *memb_map |
OUT: Maps memory usage types to other memory usage types. |
const hid_t *memb_fapl |
OUT: Property list for each memory usage type. |
const char **memb_name |
OUT: Name generator for names of member files. |
const haddr_t *memb_addr |
OUT: |
hbool_t *relax |
OUT: Allows read-only access to incomplete file sets
when TRUE. |
SUBROUTINE h5pget_fapl_multi_f(prp_id, memb_map, memb_fapl, memb_name,
memb_addr, relax, hdferr)
IMPLICIT NONE
INTEGER(HID_T),INTENT(IN) :: prp_id ! Property list identifier
INTEGER,DIMENSION(0:H5FD_MEM_NTYPES_F-1),INTENT(OUT) :: memb_map
INTEGER(HID_T),DIMENSION(0:H5FD_MEM_NTYPES_F-1),INTENT(OUT) :: memb_fapl
CHARACTER(LEN=*),DIMENSION(0:H5FD_MEM_NTYPES_F-1),INTENT(OUT) :: memb_name
REAL, DIMENSION(0:H5FD_MEM_NTYPES_F-1), INTENT(OUT) :: memb_addr
! Numbers in the interval [0,1) (e.g. 0.0 0.1 0.5 0.2 0.3 0.4)
! real address in the file will be calculated as X*HADDR_MAX
LOGICAL, INTENT(OUT) :: relax
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_fapl_multi_f
H5Pget_fapl_srb(
hid_t fapl_id,
SRB_Info *info
)
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/.
hid_t fapl_id |
IN: File access property list identifier. |
SRB_Info *info |
OUT: Pointer to the SRB information structure. |
H5Pget_fapl_stream(
hid_t fapl_id,
H5FD_stream_fapl_t *fapl
)
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.
hid_t fapl_id |
IN: File access property list identifier. |
H5FD_stream_fapl_t *fapl |
OUT: The streaming I/O file access property list. |
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.
hid_t fapl_id |
IN: File access property list identifier. |
H5F_close_degree_t *fc_degree |
OUT: Pointer to a location to which to return the file close degree
property, the value of fc_degree. |
SUBROUTINE h5pget_fclose_degree_f(fapl_id, degree, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier
INTEGER, INTENT(OUT) :: degree ! Info about file close behavior
! Possible values:
! H5F_CLOSE_DEFAULT_F
! H5F_CLOSE_WEAK_F
! H5F_CLOSE_SEMI_F
! H5F_CLOSE_STRONG_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_fclose_degree_f
H5Pget_fill_time(hid_t plist_id,
H5D_fill_time_t *fill_time
)
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.
hid_t plist_id |
IN: Dataset creation property list identifier. |
H5D_fill_time_t *fill_time |
OUT: Setting for the timing of writing fill values to the dataset. |
SUBROUTINE h5pget_fill_time_f(plist_id, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property
! list identifier
INTEGER(HSIZE_T), INTENT(OUT) :: flag ! Fill time flag
! Possible values are:
! H5D_FILL_TIME_ERROR_F
! H5D_FILL_TIME_ALLOC_F
! H5D_FILL_TIME_NEVER_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_fill_time_f
H5Pget_fill_value(hid_t plist_id,
hid_t type_id,
void *value
)
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.
hid_t plist_id |
IN: Dataset creation property list identifier. |
hid_t type_id, |
IN: Datatype identifier for the value passed
via value. |
void *value |
OUT: Pointer to buffer to contain the returned fill value. |
SUBROUTINE h5pget_fill_value_f(prp_id, type_id, fillvalue, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier of fill
! value datatype (in memory)
TYPE(VOID), INTENT(IN) :: fillvalue ! Fillvalue
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_fill_value_f
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_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.
hid_t plist |
IN: Property list identifier. |
int filter_number |
IN: Sequence number within the filter pipeline of the filter for which information is sought. |
unsigned int *flags |
OUT: Bit vector specifying certain general properties of the filter. |
size_t *cd_nelmts |
IN/OUT: Number of elements in cd_values. |
unsigned int *cd_values |
OUT: Auxiliary data for the filter. |
size_t namelen |
IN: Anticipated number of characters in name. |
char name[] |
OUT: Name of the filter. |
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 |
SUBROUTINE h5pget_filter_f(prp_id, filter_number, flags, cd_nelmts,
cd_values, namelen, name, filter_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: filter_number ! Sequence number within the filter
! pipeline of the filter for which
! information is sought
INTEGER, DIMENSION(*), INTENT(OUT) :: cd_values
! Auxiliary data for the filter
INTEGER, INTENT(OUT) :: flags ! Bit vector specifying certain
! general properties of the filter
INTEGER(SIZE_T), INTENT(INOUT) :: cd_nelmts
! Number of elements in cd_values
INTEGER(SIZE_T), INTENT(IN) :: namelen ! Anticipated number of characters
! in name
CHARACTER(LEN=*), INTENT(OUT) :: name ! Name of the filter
INTEGER, INTENT(OUT) :: filter_id ! Filter identification number
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_filter_f
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_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.
hid_t plist_id |
IN: Property list identifier. |
H5Z_filter_t filter |
IN: Filter identifier. |
unsigned int flags |
OUT: Bit vector specifying certain general properties of the filter. |
size_t cd_nelmts |
IN/OUT: Number of elements in cd_values. |
const unsigned int cd_values[] |
OUT: Auxiliary data for the filter. |
size_t namelen |
IN/OUT: Length of filter name and
number of elements in name[]. |
char *name[] |
OUT: Name of filter. |
SUBROUTINE h5pget_filter_by_id_f(prp_id, filter_id, flags, cd_nelmts,
cd_values, namelen, name, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: filter_id ! Filter identifier
INTEGER(SIZE_T), INTENT(INOUT) :: cd_nelmts
! Number of elements in cd_values
INTEGER, DIMENSION(*), INTENT(OUT) :: cd_values
! Auxiliary data for the filter
INTEGER, INTENT(OUT) :: flags ! Bit vector specifying certain
! general properties of the filter
INTEGER(SIZE_T), INTENT(IN) :: namelen ! Anticipated number of characters
! in name
CHARACTER(LEN=*), INTENT(OUT) :: name ! Name of the filter
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_filter_by_id_f
H5Pget_gc_references(hid_t plist,
unsigned *gc_ref
)
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.
hid_t plist |
IN: File access property list identifier. |
unsigned gc_ref |
OUT: Flag returning the state of reference garbage collection.
A returned value of 1 indicates that
garbage collection is on while
0 indicates that garbage collection is off. |
SUBROUTINE h5pget_gc_references_f (prp_id, gc_reference, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: gc_reference ! The flag for garbage collecting
! references for the file
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_gc_references_f
H5Pget_hyper_vector_size(hid_t dxpl_id,
size_t *vector_size
)
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.
hid_t dxpl_id |
IN: Dataset transfer property list identifier. |
size_t *vector_size |
OUT: Number of I/O vectors to accumulate in memory for I/O operations. |
SUBROUTINE h5pget_hyper_vector_size_f(plist_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset transfer property list
! identifier
INTEGER(SIZE_T), INTENT(OUT) :: size ! Vector size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_hyper_vector_size_f
H5Pget_istore_k(hid_t plist,
unsigned * ik
)
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.
hid_t plist |
IN: Identifier of property list to query. |
unsigned * ik |
OUT: Pointer to location to return the chunked storage B-tree 1/2 rank. |
SUBROUTINE h5pget_istore_k_f(prp_id, ik, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: ik ! 1/2 rank of chunked storage B-tree
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_istore_k_f
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.
Note that a compact storage layout may affect writing data to the dataset with parallel applications. See note in H5Dwrite documentation for details.
hid_t plist |
IN: Identifier for property list to query. |
Otherwise, returns a negative value indicating failure.
SUBROUTINE h5pget_layout_f (prp_id, layout, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: layout ! Type of storage layout for raw data
! possible values are:
! H5D_COMPACT_F
! H5D_CONTIGUOUS_F
! H5D_CHUNKED_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_layout_f
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.
hid_t fapl_id |
IN: File access property list identifier. |
hsize_t *size |
OUT: Minimum size, in bytes, of metadata block allocations. |
SUBROUTINE h5pget_meta_block_size_f(plist_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list
! identifier
INTEGER(HSIZE_T), INTENT(OUT) :: size ! Metadata block size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_meta_block_size_f
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 specify the type of data the
application wishes to access so that the application
can retrieve a file handle for low-level access to the particular member
of a set of MULTI files in which that type of data is stored.
The file handle is retrieved with a separate call
to H5Fget_vfd_handle
(or, in special circumstances, to H5FDget_vfd_handle;
see Virtual File Layer and List of VFL Functions
in HDF5 Technical Notes).
The type of data 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.
hid_t fapl_id |
IN: File access property list or data transfer property list identifier. |
H5FD_mem_t *type |
OUT: Type of data. |
H5Pget_nfilters(hid_t plist)
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.
hid_t plist |
IN: Property list identifier. |
SUBROUTINE h5pget_nfilters_f(prp_id, nfilters, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset creation property
! list identifier
INTEGER, INTENT(OUT) :: nfilters ! The number of filters in
! the pipeline
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_nfilters_f
H5Pget_nprops(
hid_t id,
size_t *nprops
)
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.
hid_t id |
IN: Identifier of property object to query |
size_t *nprops |
OUT: Number of properties in object |
SUBROUTINE h5pget_nprops_f(prp_id, nprops, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(SIZE_T), INTENT(OUT) :: nprops ! Number of properties
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_nprops_f
H5Pget_preserve(hid_t plist)
H5Pget_preserve checks the status of the
dataset transfer property list.
hid_t plist |
IN: Identifier for the dataset transfer property list. |
SUBROUTINE h5pget_preserve_f(prp_id, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset transfer property
! list identifier
LOGICAL, INTENT(OUT) :: flag ! Status of for the dataset
! transfer property list
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_preserve_f
H5Pget_sieve_buf_size(
hid_t fapl_id,
hsize_t *size
)
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.
hid_t fapl_id |
IN: File access property list identifier. |
hsize_t *size |
IN: Maximum size, in bytes, of data sieve buffer. |
SUBROUTINE h5pget_sieve_buf_size_f(plist_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list
! identifier
INTEGER(SIZE_T), INTENT(OUT) :: size ! Sieve buffer size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_sieve_buf_size_f
H5Pget_size(
hid_t id,
const char *name,
size_t *size
)
H5Pget_size retrieves the size of a
property's value in bytes. This function operates on both
property 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 |
SUBROUTINE h5pget_size_f(prp_id, name, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to query
INTEGER(SIZE_T), INTENT(OUT) :: size ! Size in bytes
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_size_f
H5Pget_sizes(hid_t plist,
size_t * sizeof_addr,
size_t * sizeof_size
)
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.
hid_t plist |
IN: Identifier of property list to query. |
size_t * size |
OUT: Pointer to location to return offset size in bytes. |
size_t * size |
OUT: Pointer to location to return length size in bytes. |
SUBROUTINE h5pget_sizes_f(prp_id, sizeof_addr, sizeof_size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(SIZE_T), DIMENSION(:), INTENT(OUT) :: sizeof_addr
! Size of an object address in bytes
INTEGER(SIZE_T), DIMENSION(:), INTENT(OUT) :: sizeof_size
! Size of an object in bytes
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_sizes_f
H5Pget_small_data_block_size(hid_t fapl_id,
hsize_t *size
)
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.
hid_t fapl_id |
IN: File access property list identifier. |
hsize_t *size |
OUT: Maximum size, in bytes, of the small data block. |
SUBROUTINE h5pget_small_data_block_size_f(plist_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list
! identifier
INTEGER(HSIZE_T), INTENT(OUT) :: size ! Small raw data block size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_small_data_block_size_f
H5Pget_sym_k(hid_t plist,
unsigned * ik,
unsigned * lk
)
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.
hid_t plist |
IN: Property list to query. |
unsigned * ik |
OUT: Pointer to location to return the symbol table's B-tree 1/2 rank. |
unsigned * size |
OUT: Pointer to location to return the symbol table's leaf node 1/2 size. |
SUBROUTINE h5pget_sym_k_f(prp_id, ik, lk, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: ik ! Symbol table tree rank
INTEGER, INTENT(OUT) :: lk ! Symbol table node size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_sym_k_f
H5Pget_userblock(hid_t plist,
hsize_t * size
)
H5Pget_userblock retrieves the size of a user block
in a file creation property list.
hid_t plist |
IN: Identifier for property list to query. |
hsize_t * size |
OUT: Pointer to location to return user-block size. |
SUBROUTINE h5pget_userblock_f(prp_id, block_size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HSIZE_T), DIMENSION(:), INTENT(OUT) :: block_size
! Size of the user-block in bytes
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_userblock_f
H5Pget_version(hid_t plist,
unsigned * super,
unsigned * freelist,
unsigned * stab,
unsigned * 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.
hid_t plist |
IN: Identifier of the file creation property list. |
unsigned * super |
OUT: Pointer to location to return super block version number. |
unsigned * freelist |
OUT: Pointer to location to return global freelist version number. |
unsigned * stab |
OUT: Pointer to location to return symbol table version number. |
unsigned * shhdr |
OUT: Pointer to location to return shared object header version number. |
SUBROUTINE h5pget_version_f(prp_id, boot, freelist, &
stab, shhdr, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, DIMENSION(:), INTENT(OUT) :: boot ! Array to put boot block
! version number
INTEGER, DIMENSION(:), INTENT(OUT) :: freelist
! Array to put global
! freelist version number
INTEGER, DIMENSION(:), INTENT(OUT) :: stab ! Array to put symbol table
! version number
INTEGER, DIMENSION(:), INTENT(OUT) :: shhdr ! Array to put shared object
! header version number
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_version_f
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.
H5Pget_vlen_mem_manager is the companion function to
H5Pset_vlen_mem_manager, returning the parameters
set by that function.
hid_t plist |
IN: Identifier for the dataset transfer property list. |
H5MM_allocate_t alloc |
OUT: User's allocate routine, or NULL
for system malloc. |
void *alloc_info |
OUT: Extra parameter for user's allocation routine.
Contents are ignored if preceding parameter is NULL. |
H5MM_free_t free |
OUT: User's free routine, or NULL for
system free. |
void *free_info |
OUT: Extra parameter for user's free routine.
Contents are ignored if preceding parameter is NULL. |
H5Pinsert(
hid_t plid,
const char *name,
size_t size,
void *value,
H5P_prp_set_func_t set,
H5P_prp_get_func_t get,
H5P_prp_delete_func_t delete,
H5P_prp_copy_func_t copy,
H5P_prp_compare_func_t compare,
H5P_prp_close_func_t close
)
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.
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.
Theset routine is called before a new value is copied
into the property.
The H5P_prp_set_func_t callback 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 transformation or translation of the
value set. The get callback would then
reverse the transformation or translation.
A single get or set callback
could handle multiple properties by
performing different actions based on the
property name or other properties in the property list.
The get routine is called when a value is retrieved
from a property value.
The H5P_prp_get_func_t callback function is defined
as follows:
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: 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.
The delete routine is called when a property is being
deleted from a property list.
The H5P_prp_delete_func_t callback function is defined
as follows:
typedef herr_t (*H5P_prp_delete_func_t)(
hid_t prop_id,
const char *name,
size_t size,
void *value);
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.
The compare routine is called when a property list with
this property is compared to another property list with the same property.
The H5P_prp_compare_func_t callback function is defined
as follows:
H5P_prp_compare_func_t)(
const void *value1,
const void *value2,
size_t size);
const void *value1 |
IN: The value of the first property to compare |
const void *value2 |
IN: The value of the second property to compare |
size_t size |
IN: The size of the property in bytes |
compare routine may not modify the values.
The compare routine should return a positive value if
value1 is greater than value2, a negative value
if value2 is greater than value1 and zero if
value1 and value2 are equal.
The close routine is called when a property list
with this property is being closed.
The H5P_prp_close_func_t callback function is defined
as follows:
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.
hid_t plid |
IN: Property list identifier to create temporary property within |
const char *name |
IN: Name of property to create |
size_t size |
IN: Size of property in bytes |
void *value |
IN: Initial value for the property |
H5P_prp_set_func_t set |
IN: Callback routine called before a new value is copied into the property's value |
H5P_prp_get_func_t get |
IN: Callback routine called when a property value is retrieved from the property |
H5P_prp_delete_func_t delete |
IN: Callback routine called when a property is deleted from a property list |
H5P_prp_copy_func_t copy |
IN: Callback routine called when a property is copied from an existing property list |
H5P_prp_compare_func_t compare |
IN: Callback routine called when a property is compared with another property list |
H5P_prp_close_func_t close |
IN: Callback routine called when a property list is being closed and the property value will be disposed of |
SUBROUTINE h5pinsert_f
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist ! Property list class identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to insert
INTEGER(SIZE_T), INTENT(IN) :: size ! Size of the property value
TYPE, INTENT(IN) :: value ! Property value
! Supported types are:
! INTEGER
! REAL
! DOUBLE PRECISION
! CHARACTER(LEN=*)
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pinsert_f
H5Pisa_class(
hid_t plist,
hid_t pclass
)
H5Pisa_class checks to determine whether a property list
is a member of the specified class.
hid_t plist |
IN: Identifier of the property list |
hid_t pclass |
IN: Identifier of the property class |
SUBROUTINE h5pisa_class_f(plist, pclass, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist ! Property list identifier
INTEGER(HID_T), INTENT(IN) :: pclass ! Class identifier
LOGICAL, INTENT(OUT) :: flag ! Logical flag
! .TRUE. if a member
! .FALSE. otherwise
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pisa_class_f
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
H5Pmodify_filter(hid_t plist,
H5Z_filter_t filter,
unsigned int flags,
size_t cd_nelmts,
const unsigned int cd_values[]
)
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.
hid_t plist_id |
IN: Property list identifier. |
H5Z_filter_t filter |
IN: Filter to be modified. |
unsigned int flags |
IN: Bit vector specifying certain general properties of the filter. |
size_t cd_nelmts |
IN: Number of elements in cd_values. |
const unsigned int cd_values[] |
IN: Auxiliary data for the filter. |
SUBROUTINE h5pmodify_filter_f(prp_id, filter, flags, cd_nelmts, &
cd_values, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: filter ! Filter to be modified
INTEGER, INTENT(IN) :: flags ! Bit vector specifying certain
! general properties of the filter
INTEGER(SIZE_T), INTENT(IN) :: cd_nelmts ! Number of elements in cd_values
INTEGER, DIMENSION(*), INTENT(IN) :: cd_values
! Auxiliary data for the filter
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pmodify_filter_f
H5Pregister(
hid_t class,
const char * name,
size_t size,
void * default,
H5P_prp_create_func_t create,
H5P_prp_set_func_t set,
H5P_prp_get_func_t get,
H5P_prp_delete_func_t delete,
H5P_prp_copy_func_t copy,
H5P_prp_compare_func_t compare,
H5P_prp_close_func_t close
)
H5Pregister registers a new property with a
property list class.
The property will exist in all property list objects of
class created after this routine finishes. The name
of the property must not already exist, or this routine will fail.
The default property value must be provided and all new property
lists created with this property will have the property value set
to the default value. Any of the callback routines may be set to
NULL if they are not needed.
Zero-sized properties are allowed and do not store any data in the
property list. These may be used as flags to indicate the presence
or absence of a particular piece of information. The default pointer
for a zero-sized property may be set to NULL.
The property create and close callbacks
are called for zero-sized properties, but the set and
get callbacks are never called.
The create routine is called when a new property list
with this property is being created.
The H5P_prp_create_func_t callback function is defined
as follows:
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 transformation or translation of the
value set. The get callback would then
reverse the
transformation or translation.
A single get or set callback
could handle multiple properties by
performing different actions based on the
property name or other properties in the property list.
The get routine is called when a value is retrieved
from a property value.
The H5P_prp_get_func_t callback function is defined
as follows:
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.
The compare routine is called when a property list with
this property is compared to another property list with the same property.
The H5P_prp_compare_func_t callback function is defined
as follows:
H5P_prp_compare_func_t)(
const void *value1,
const void *value2,
size_t size);
const void *value1 |
IN: The value of the first property to compare |
const void *value2 |
IN: The value of the second property to compare |
size_t size |
IN: The size of the property in bytes |
compare routine may not modify the values.
The compare routine should return a positive value if
value1 is greater than value2, a negative value
if value2 is greater than value1 and zero if
value1 and value2 are equal.
The close routine is called when a property list with
this property is being closed.
The H5P_prp_close_func_t callback function is defined
as follows:
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 |
IN: Property list class to register permanent property within |
const char * name |
IN: Name of property to register |
size_t size |
IN: Size of property in bytes |
void * default |
IN: Default value for property in newly created property lists |
H5P_prp_create_func_t create |
IN: Callback routine called when a property list is being created and the property value will be initialized |
H5P_prp_set_func_t set |
IN: Callback routine called before a new value is copied into the property's value |
H5P_prp_get_func_t get |
IN: Callback routine called when a property value is retrieved from the property |
H5P_prp_delete_func_t delete |
IN: Callback routine called when a property is deleted from a property list |
H5P_prp_copy_func_t copy |
IN: Callback routine called when a property is copied from a property list |
H5P_prp_compare_func_t compare |
IN: Callback routine called when a property is compared with another property list |
H5P_prp_close_func_t close |
IN: Callback routine called when a property list is being closed and the property value will be disposed of |
SUBROUTINE h5pregister_f
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: class ! Property list class identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to register
INTEGER(SIZE_T), INTENT(IN) :: size ! Size of the property value
TYPE, INTENT(IN) :: value ! Property value
! Supported types are:
! INTEGER
! REAL
! DOUBLE PRECISION
! CHARACTER(LEN=*)
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pregister_f
H5Premove(
hid_t plid;
const char *name
)
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.
hid_t plid |
IN: Identifier of the property list to modify |
const char *name |
IN: Name of property to remove |
SUBROUTINE h5premove_f(plid, name, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plid ! Property list identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to remove
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5premove_f
H5Pset(
hid_t plid,
const char *name,
void *value)
)
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 |
SUBROUTINE h5pset_f(plid, name, value, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plid ! Property list identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to set
TYPE, INTENT(IN) :: value ! Property value
! Supported types are:
! INTEGER
! REAL
! DOUBLE PRECISION
! CHARACTER(LEN=*)
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_f
H5Pset_alignment(hid_t plist,
hsize_t threshold,
hsize_t alignment
)
H5Pset_alignment sets the alignment properties
of a file access property list
so that any file object greater than or equal in size to
threshold bytes will be aligned on an address
which is a multiple of alignment. The addresses
are relative to the end of the user block; the alignment is
calculated by subtracting the user block size from the
absolute file address and then adjusting the address to be a
multiple of alignment.
Default values for threshold and
alignment are one, implying
no alignment. Generally the default values will result in
the best performance for single-process access to the file.
For MPI-IO and other parallel systems, choose an alignment
which is a multiple of the disk block size.
hid_t plist |
IN: Identifier for a file access property list. |
hsize_t threshold |
IN: Threshold value. Note that setting the threshold value to 0 (zero) has the effect of a special case, forcing everything to be aligned. |
hsize_t alignment |
IN: Alignment value. |
SUBROUTINE h5pset_alignment_f(prp_id, threshold, alignment, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HSIZE_T), INTENT(IN) :: threshold ! Threshold value
INTEGER(HSIZE_T), INTENT(IN) :: alignment ! Alignment value
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_alignment_f
H5Pset_alloc_time(hid_t plist_id,
H5D_alloc_time_t alloc_time
)
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.
hid_t plist_id |
IN: Dataset creation property list identifier. |
H5D_alloc_time_t alloc_time |
IN: When to allocate dataset storage space. |
SUBROUTINE h5pset_alloc_time_f(plist_id, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property
! list identifier
INTEGER(HSIZE_T), INTENT(IN) :: flag ! Allocation time flag
! Possible values are:
! H5D_ALLOC_TIME_ERROR_F
! H5D_ALLOC_TIME_DEFAULT_F
! H5D_ALLOC_TIME_EARLY_F
! H5D_ALLOC_TIME_LATE_F
! H5D_ALLOC_TIME_INCR_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_alloc_time_f
H5Pset_btree_ratios(hid_t plist,
double left,
double middle,
double right
)
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.
hid_t plist |
IN: The dataset transfer property list identifier. |
double left |
IN: The B-tree split ratio for left-most nodes. |
double right |
IN: The B-tree split ratio for right-most nodes and lone nodes. |
double middle |
IN: The B-tree split ratio for all other nodes. |
SUBROUTINE h5pset_btree_ratios_f(prp_id, left, middle, right, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id
! Property list identifier
REAL, INTENT(IN) :: left ! The B-tree split ratio for left-most nodes
REAL, INTENT(IN) :: middle ! The B-tree split ratio for all other nodes
REAL, INTENT(IN) :: right ! The B-tree split ratio for right-most
! nodes and lone nodes.
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_btree_ratios_f
H5Pset_buffer(hid_t plist,
hsize_t size,
void *tconv,
void *bkg
)
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.
hid_t plist |
IN: Identifier for the dataset transfer property list. |
hsize_t size |
IN: Size, in bytes, of the type conversion and background buffers. |
void tconv |
IN: Pointer to application-allocated type conversion buffer. |
void bkg |
IN: Pointer to application-allocated background buffer. |
SUBROUTINE h5pset_buffer_f(plist_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset transfer property
! list identifier
INTEGER(HSIZE_T), INTENT(IN) :: size ! Conversion buffer size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_buffer_f
H5Pset_cache(hid_t plist_id,
int mdc_nelmts,
int rdcc_nelmts,
size_t rdcc_nbytes,
double rdcc_w0
)
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 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.
Any (or all) of the H5Pget_cache pointer arguments
may be null pointers.
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.
hid_t plist_id |
IN: Identifier of the file access property list. |
int mdc_nelmts |
IN: Number of elements (objects) in the meta data cache. |
int rdcc_nelmts |
IN: Number of elements (objects) in the raw data chunk cache. |
size_t rdcc_nbytes |
IN: Total size of the raw data chunk cache, in bytes. |
double rdcc_w0 |
IN: Preemption policy. |
SUBROUTINE h5pset_cache_f(prp_id, mdc_nelmts,rdcc_nelmts, rdcc_nbytes, rdcc_w0, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: mdc_nelmts ! Number of elements (objects)
! in the meta data cache
INTEGER(SIZE_T), INTENT(IN) :: rdcc_nelmts ! Number of elements (objects)
! in the meta data cache
INTEGER(SIZE_T), INTENT(IN) :: rdcc_nbytes ! Total size of the raw data
! chunk cache, in bytes
REAL, INTENT(IN) :: rdcc_w0 ! Preemption policy
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_cache_f
H5Pset_chunk(hid_t plist,
int ndims,
const hsize_t * dim
)
H5Pset_chunk sets the size of the chunks used to
store a chunked layout dataset. This function is only valid
for dataset creation property lists.
The ndims parameter currently must be the same size
as the rank of the dataset.
The values of the dim
array define the size of the chunks to store the dataset's raw data.
The unit of measure for dim values is
dataset elements.
As a side-effect of this function, the layout of the dataset is
changed to H5D_CHUNKED, if it is not already so set.
(See H5Pset_layout.)
hid_t plist |
IN: Identifier for property list to query. |
int ndims |
IN: The number of dimensions of each chunk. |
const hsize_t * dim |
IN: An array defining the size, in dataset elements, of each chunk. |
SUBROUTINE h5pset_chunk_f(prp_id, ndims, dims, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: ndims ! Number of chunk dimensions
INTEGER(HSIZE_T), DIMENSION(ndims), INTENT(IN) :: dims
! Array containing sizes of
! chunk dimensions
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_chunk_f
H5Pset_data_transform
(hid_t plist_id,
const char *expression)
H5Pset_data_transform sets the data transform to
be used for reading and writing data.
This function operates on the dataset transfer property lists
plist_id.
The expression parameter is a string containing an algebraic
expression, such as (5/9.0)*(x-32)
or x*(x-5).
When a dataset is read or written with this property list,
the transform expression is applied with the x
being replaced by the values in the dataset.
When reading data, the values in the file are not changed
and the transformed data is returned to the user.
Data transforms can only be applied to integer or floating-point datasets. Order of operations is obeyed and the only supported operations are +, -, *, and /. Parentheses can be nested arbitrarily and can be used to change precedence.
When writing data back to the dataset, the transformed data is written to the file and there is no way to recover the original values to which the transform was applied.
hid_t plist_id |
IN: Identifier of the property list or class |
const char *expression |
IN: Pointer to the null-terminated data transform expression |
H5Pset_deflate(hid_t plist,
int level
)
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.
hid_t plist |
IN: Identifier for the dataset creation property list. |
int level |
IN: Compression level. |
SUBROUTINE h5pset_deflate_f(prp_id, level, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: level ! Compression level
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_deflate_f
H5Pset_dxpl_mpio(
hid_t dxpl_id,
H5FD_mpio_xfer_t xfer_mode
)
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
hid_t dxpl_id |
IN: Data transfer property list identifier. |
H5FD_mpio_xfer_t xfer_mode |
IN: Transfer mode. |
SUBROUTINE h5pset_dxpl_mpio_f(prp_id, data_xfer_mode, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: data_xfer_mode ! Data transfer mode
! Possible values are:
! H5FD_MPIO_INDEPENDENT_F
! H5FD_MPIO_COLLECTIVE_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_dxpl_mpio_f
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.
hid_t dxpl_id, |
IN: Data transfer property list identifier. |
const hid_t *memb_dxpl |
IN: Array of data access property lists. |
H5Pset_edc_check(hid_t plist,
H5Z_EDC_t check)
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.
hid_t plist |
IN: Dataset transfer property list identifier. |
H5Z_EDC_t check |
IN: Specifies whether error checking is enabled or disabled for dataset read operations. |
SUBROUTINE h5pset_edc_check_f(prp_id, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset transfer property
! list identifier
INTEGER, INTENT(IN) :: flag ! EDC flag; possible values
! H5Z_DISABLE_EDC_F
! H5Z_ENABLE_EDC_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_edc_check_f
H5Pset_external(hid_t plist,
const char *name,
off_t offset,
hsize_t size
)
H5Pset_external sets the
external storage property in the property list,
thus designating that the dataset will be stored in
one or more non-HDF5 file(s) external to the HDF5 file.
This call also adds the file name as the
first file in the list of external files.
Subsequent calls to the function add the named file as
the next file in the list.
If a dataset is split across multiple files, then the files
should be defined in order. The total size of the dataset is
the sum of the size arguments for all the external files.
If the total size is larger than the size of a dataset then the
dataset can be extended (provided the data space also allows
the extending).
The size argument specifies the number of bytes reserved
for data in the external file.
If size is set to H5F_UNLIMITED, the
external file can be of unlimited size and no more files can be added
to the external files list.
All of the external files for a given dataset must be
specified with H5Pset_external
before H5Dcreate is called to create
the dataset.
If one these files does not exist on the system when
H5Dwrite is called to write data to it,
the library will create the file.
hid_t plist |
IN: Identifier of a dataset creation property list. |
const char *name |
IN: Name of an external file. |
off_t offset |
IN: Offset, in bytes, from the beginning of the file to the location in the file where the data starts. |
hsize_t size |
IN: Number of bytes reserved in the file for the data. |
SUBROUTINE h5pset_external_f(prp_id, name, offset,bytes, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of an external file
INTEGER, INTENT(IN) :: offset ! Offset, in bytes, from the
! beginning of the file to the
! location in the file where
! the data starts
INTEGER(HSIZE_T), INTENT(IN) :: bytes ! Number of bytes reserved in
! the file for the data
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_external_f
H5Pset_family_offset (
hid_t fapl_id,
hsize_t offset
)
H5Pset_family_offset sets the offset property in the
file access property list fapl_id so that the user application
can retrieve a file handle for low-level access to a particular member
of a family of files. The file handle is retrieved with a separate call
to H5Fget_vfd_handle
(or, in special circumstances, to H5FDget_vfd_handle;
see Virtual File Layer and List of VFL Functions
in HDF5 Technical Notes).
The value of offset is an offset in bytes from the
beginning of the HDF5 file, identifying a user-determined location
within the HDF5 file. The file handle the user application is seeking
is for the specific member-file in the associated family of files
to which this offset is mapped.
Use of this function is only appropriate for an HDF5 file written as a
family of files with the FAMILY file driver.
hid_t fapl_id |
IN: File access property list identifier. |
hsize_t offset |
IN: Offset in bytes within the HDF5 file. |
SUBROUTINE h5pset_family_offset_f(prp_id, offset, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HSIZE_T), INTENT(IN) :: offset ! Offset in bytes
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_family_offset_f
H5Pset_fapl_core(
hid_t fapl_id,
size_t increment,
hbool_t backing_store
)
H5FD_CORE driver.
H5Pset_fapl_core modifies the file access property list
to use the H5FD_CORE driver.
The H5FD_CORE driver enables an application to work
with a file in memory, speeding reads and writes as no disk access
is made. File contents are stored only in memory until the file
is closed. The backing_store parameter determines
whether file contents are ever written to disk.
increment specifies the increment by which allocated
memory is to be increased each time more memory is required.
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.
hid_t fapl_id |
IN: File access property list identifier. |
size_t increment |
IN: Size, in bytes, of memory increments. |
hbool_t backing_store |
IN: Boolean flag indicating whether to write the file contents to disk when the file is closed. |
SUBROUTINE h5pset_fapl_core_f(prp_id, increment, backing_store, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(SIZE_T), INTENT(IN) :: increment ! File block size in bytes
LOGICAL, INTENT(IN) :: backing_store ! Flag to indicate that entire
! file contents are flushed to
! a file with the same name as
! this core file
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_core_f
H5Pset_fapl_family (
hid_t fapl_id,
hsize_t memb_size,
hid_t memb_fapl_id
)
H5Pset_fapl_family sets the file access property list
identifier, fapl_id, to use the family driver.
memb_size is the size in bytes of each file member. This size
will be saved in the file when the property list fapl_id is used
to create a new file. If fapl_id is used to open an existing
file, memb_size has to be equal to the original size saved in
the file. A failure with an errror message indicating the correct member
size will be returned if memb_size does not match the size saved.
If any user does not know the original size, H5F_FAMILY_DEFAULT
can be passed in. The library will retrieve the correct size saved in the file.
memb_fapl_id is the identifier of the
file access property list to be used for each family member.
hid_t fapl_id |
IN: File access property list identifier. |
hsize_t memb_size |
IN: Size in bytes of each file member. |
hid_t memb_fapl_id |
IN: Identifier of file access property list for each family member. |
SUBROUTINE h5pset_fapl_family_f(prp_id, imemb_size, memb_plist, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HSIZE_T), INTENT(IN) :: memb_size ! Logical size, in bytes,
! of each family member
INTEGER(HID_T), INTENT(IN) :: memb_plist ! Identifier of the file
! access property list to be
! used for each family member
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_family_f
H5Pset_fapl_gass(
hid_t fapl_id,
GASS_Info info
)
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/.
hid_t fapl_id, |
IN: File access property list identifier. |
GASS_Info info |
IN: Pointer to the GASS information structure. |
H5Pset_fapl_log(
hid_t fapl_id,
const char *logfile,
unsigned int flags,
size_t buf_size
)
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.
hid_t fapl_id |
IN: File access property list identifier. |
char *logfile |
IN: Name of the log file. |
unsigned int flags |
IN: Flags specifying the types of logging activity. |
size_t buf_size |
IN: The size of the logging buffer. |
H5Pset_fapl_mpio(
hid_t fapl_id,
MPI_Comm comm,
MPI_Info info
)
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.
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.
hid_t fapl_id |
IN: File access property list identifier. |
MPI_Comm comm |
IN: MPI-2 communicator. |
MPI_Info info |
IN: MPI-2 info object. |
SUBROUTINE h5pset_fapl_mpio_f(prp_id, comm, info, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: comm ! MPI communicator to be used for
! file open as defined in
! MPI_FILE_OPEN of MPI-2
INTEGER, INTENT(IN) :: info ! MPI info object to be used for
! file open as defined in
! MPI_FILE_OPEN of MPI-2
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_mpio_f
H5Pset_fapl_mpiposix(
hid_t fapl_id,
MPI_Comm comm
)
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.
hid_t fapl_id |
IN: File access property list identifier. |
MPI_Comm comm |
IN: MPI-2 communicator. |
SUBROUTINE h5pset_fapl_mpiposix_f(prp_id, comm, use_gpfs, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: comm ! MPI communicator to be used
! for file open as defined in
! MPI_FILE_OPEN of MPI-2
LOGICAL, INTENT(IN) :: use_gpfs
INTEGER, INTENT(OUT) :: hdferr ! Error code
END SUBROUTINE h5pset_fapl_mpiposix_f
H5Pset_fapl_multi(
hid_t fapl_id,
const H5FD_mem_t *memb_map,
const hid_t *memb_fapl,
const char * const *memb_name,
const haddr_t *memb_addr,
hbool_t relax
)
H5Pset_fapl_multi sets the file access property list
fapl_id to use the multi-file driver.
The multi-file driver enables different types of HDF5 data and metadata to be written to separate files. These files are viewed by the HDF5 library and the application as a single virtual HDF5 file with a single HDF5 file address space. The types of data that can be broken out into separate files include raw data, the superblock, B-tree data, global heap data, local heap data, and object headers. At the programmer's discretion, two or more types of data can be written to the same file while other types of data are written to separate files.
The array memb_map maps memory usage types to other
memory usage types and is the mechanism that allows the caller
to specify how many files are created.
The array contains H5FD_MEM_NTYPES entries,
which are either the value H5FD_MEM_DEFAULT
or a memory usage type.
The number of unique values determines the number of files
that are opened.
The array memb_fapl contains a property list
for each memory usage type that will be associated with a file.
The array memb_name should be a name generator
(a printf-style format with a %s which will be replaced with the
name passed to H5FDopen, usually from
H5Fcreate or H5Fopen).
The array memb_addr specifies the offsets within the
virtual address space, from 0 (zero) to
HADDR_MAX, at which each type of data storage begins.
If relax is set to TRUE (or 1),
then opening an existing file for read-only access will not fail
if some file members are missing.
This allows a file to be accessed in a limited sense if just the
meta data is available.
Default values for each of the optional arguments are as follows:
memb_map
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.
hid_t fapl_id |
IN: File access property list identifier. |
const H5FD_mem_t *memb_map |
IN: Maps memory usage types to other memory usage types. |
const hid_t *memb_fapl |
IN: Property list for each memory usage type. |
const char * const *memb_name |
IN: Name generator for names of member files. |
const haddr_t *memb_addr |
IN: The offsets within the virtual address space,
from 0 (zero) to HADDR_MAX,
at which each type of data storage begins. |
hbool_t relax |
IN: Allows read-only access to incomplete file sets
when TRUE. |
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);
SUBROUTINE h5pset_fapl_multi_f(prp_id, memb_map, memb_fapl, memb_name,
memb_addr, relax, hdferr)
IMPLICIT NONE
INTEGER(HID_T),INTENT(IN) :: prp_id ! Property list identifier
INTEGER,DIMENSION(0:H5FD_MEM_NTYPES_F-1),INTENT(IN) :: memb_map
INTEGER(HID_T),DIMENSION(0:H5FD_MEM_NTYPES_F-1),INTENT(IN) :: memb_fapl
CHARACTER(LEN=*),DIMENSION(0:H5FD_MEM_NTYPES_F-1),INTENT(IN) :: memb_name
REAL, DIMENSION(0:H5FD_MEM_NTYPES_F-1), INTENT(IN) :: memb_addr
! Numbers in the interval [0,1) (e.g. 0.0 0.1 0.5 0.2 0.3 0.4)
! real address in the file will be calculated as X*HADDR_MAX
LOGICAL, INTENT(IN) :: relax
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_multi_f
H5Pset_fapl_sec2(
hid_t fapl_id
)
H5Pset_fapl_sec2 modifies the file access property list
to use the H5FD_SEC2 driver.
hid_t fapl_id |
IN: File access property list identifier. |
SUBROUTINE h5pset_fapl_sec2_f(prp_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_sec2_f
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_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.
hid_t fapl_id, |
IN: File access property list identifier. |
const char *meta_ext, |
IN: Metadata filename extension. |
hid_t meta_plist_id, |
IN: File access property list identifier for the metadata file. |
const char *raw_ext, |
IN: Raw data filename extension. |
hid_t raw_plist_id |
IN: File access property list identifier for the raw data file. |
/* 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);
SUBROUTINE h5pset_fapl_split_f(prp_id, meta_ext, meta_plist, raw_ext, &
raw_plist, hdferr)
IMPLICIT NONE
INTEGER(HID_T),INTENT(IN) :: prp_id ! Property list identifier
CHARACTER(LEN=*),INTENT(IN) :: meta_ext ! Name of the extension for
! the metafile filename
INTEGER(HID_T),INTENT(IN) :: meta_plist ! Identifier of the meta file
! access property list
CHARACTER(LEN=*),INTENT(IN) :: raw_ext ! Name extension for the raw
! file filename
INTEGER(HID_T),INTENT(IN) :: raw_plist ! Identifier of the raw file
! access property list
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_split_f
H5Pset_fapl_srb(
hid_t fapl_id,
SRB_Info info
)
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/.
hid_t fapl_id |
IN: File access property list identifier. |
SRB_Info info |
IN: Pointer to the SRB information structure. |
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.
hid_t fapl_id |
IN: File access property list identifier. |
SUBROUTINE h5pset_fapl_stdio_f(prp_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fapl_stdio_f
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.
hid_t fapl_id |
IN: File access property list identifier. |
H5FD_stream_fapl_t *fapl |
IN: The streaming I/O file access property list. |
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 remaining in the file are closed then file is closed |
H5F_CLOSE_DEFAULT |
The VFL driver chooses the behavior. Currently,
all VFL drivers set this value to H5F_CLOSE_WEAK, except
for the MPI-I/O driver, which sets it to H5F_CLOSE_SEMI.
|
|
hid_t fapl_id |
IN: File access property list identifier. |
H5F_close_degree_t fc_degree |
IN: Pointer to a location containing the file close degree property,
the value of fc_degree. |
SUBROUTINE h5pset_fclose_degree_f(fapl_id, degree, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier
INTEGER, INTENT(IN) :: degree ! Info about file close behavior
! Possible values:
! H5F_CLOSE_DEFAULT_F
! H5F_CLOSE_WEAK_F
! H5F_CLOSE_SEMI_F
! H5F_CLOSE_STRONG_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fclose_degree_f
H5Pset_fill_time(hid_t plist_id,
H5D_fill_time_t fill_time
)
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.
hid_t plist_id |
IN: Dataset creation property list identifier. |
H5D_fill_time_t fill_time |
IN: When to write fill values to a dataset. |
SUBROUTINE h5pset_fill_time_f(plist_id, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property
! list identifier
INTEGER(HSIZE_T), INTENT(IN) :: flag ! File time flag
! Possible values are:
! H5D_FILL_TIME_ERROR_F
! H5D_FILL_TIME_ALLOC_F
! H5D_FILL_TIME_NEVER_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fill_time_f
H5Pset_fill_value(hid_t plist_id,
hid_t type_id,
const void *value
)
H5Pset_fill_value sets the fill value for
a dataset in the dataset creation property list.
value is interpreted as being of datatype
type_id. This datatype may differ from that of
the dataset, but the HDF5 library must be able to convert
value to the dataset datatype when the dataset
is created.
The default fill value is 0 (zero), which is
interpreted according to the actual dataset datatype.
Setting value to NULL indicates
that the fill value is to be undefined.
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.
hid_t plist_id |
IN: Dataset creation property list identifier. |
hid_t type_id, |
IN: Datatype of value. |
const void *value |
IN: Pointer to buffer containing value to use as fill value. |
SUBROUTINE h5pset_fill_value_f(prp_id, type_id, fillvalue, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HID_T), INTENT(IN) :: type_id ! Datatype identifier of fill
! value datatype (in memory)
TYPE(VOID), INTENT(IN) :: fillvalue ! Fillvalue
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fill_value_f
H5Pset_filter(hid_t plist,
H5Z_filter_t filter,
unsigned int flags,
size_t cd_nelmts,
const unsigned int cd_values[]
)
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 filter identifiers are as follows:
H5Z_FILTER_DEFLATE
| Data compression filter, employing the gzip algorithm |
H5Z_FILTER_SHUFFLE
| Data shuffling filter |
H5Z_FILTER_FLETCHER32
| Error detection filter, employing the Fletcher32 checksum algorithm |
H5Z_FILTER_SZIP
| Data compression filter, employing the SZIP algorithm |
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.
hid_t plist |
IN: Property list identifier. |
H5Z_filter_t filter |
IN: Filter identifier for the filter to be added to the pipeline. |
unsigned int flags |
IN: Bit vector specifying certain general properties of the filter. |
size_t cd_nelmts |
IN: Number of elements in cd_values. |
const unsigned int cd_values[] |
IN: Auxiliary data for the filter. |
SUBROUTINE h5pset_filter_f(prp_id, filter, flags, cd_nelmts, cd_values, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: filter ! Filter to be added to the pipeline
INTEGER, INTENT(IN) :: flags ! Bit vector specifying certain
! general properties of the filter
INTEGER(SIZE_T), INTENT(IN) :: cd_nelmts
! Number of elements in cd_values
INTEGER, DIMENSION(*), INTENT(IN) :: cd_values
! Auxiliary data for the filter
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_filter_f
H5Pset_filter_callback(hid_t plist,
H5Z_filter_func_t func,
void *op_data)
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.
hid_t plist |
IN: Dataset transfer property list identifier. |
H5Z_filter_func_t func |
IN: User-defined filter callback function. |
void *op_data |
IN: User-defined input data for the callback function. |
H5Pset_fletcher32(hid_t plist)
H5Pset_fletcher32 sets the Fletcher32 checksum filter
in the dataset creation property list plist.
hid_t plist |
IN: Dataset creation property list identifier. |
SUBROUTINE h5pset_fletcher32_f(prp_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset creation property list
! identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_fletcher32_f
H5Pset_gc_reference(hid_t plist,
unsigned gc_ref
)
H5Pset_gc_references sets the flag for
garbage collecting references for the file.
Dataset region references and other reference types use space in an HDF5 file's global heap. If garbage collection is on and the user passes in an uninitialized value in a reference structure, the heap might get corrupted. When garbage collection is off, however, and the user re-uses a reference, the previous heap block will be orphaned and not returned to the free heap space.
When garbage collection is on, the user must initialize the reference structures to 0 or risk heap corruption.
The default value for garbage collecting references is off.
hid_t plist |
IN: File access property list identifier. |
unsigned gc_ref |
IN: Flag setting reference garbage collection to
on (1) or off (0). |
SUBROUTINE h5pset_gc_references_f (prp_id, gc_reference, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: gc_reference ! Flag for garbage collecting
! references for the file
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_gc_references_f
H5Pset_hyper_vector_size(hid_t dxpl_id,
size_t vector_size
)
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.
hid_t dxpl_id |
IN: Dataset transfer property list identifier. |
size_t vector_size |
IN: Number of I/O vectors to accumulate in memory for I/O operations.
Must be greater than 1 (one). Default value: 1024. |
SUBROUTINE h5pset_hyper_vector_size_f(plist_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset transfer property list
! identifier
INTEGER(SIZE_T), INTENT(IN) :: size ! Vector size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_hyper_vector_size_f
H5Pset_istore_k(hid_t plist,
unsigned ik
)
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.
hid_t plist |
IN: Identifier of property list to query. |
unsigned ik |
IN: 1/2 rank of chunked storage B-tree. |
SUBROUTINE h5pset_istore_k_f (prp_id, ik, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: ik ! 1/2 rank of chunked storage B-tree
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_istore_k_f
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:
Note that a compact storage layout may affect writing data to the dataset with parallel applications. See note in H5Dwrite documentation for details.
hid_t plist |
IN: Identifier of property list to query. |
H5D_layout_t layout |
IN: Type of storage layout for raw data. |
SUBROUTINE h5pset_layout_f (prp_id, layout, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: layout ! Type of storage layout for raw data
! Possible values are:
! H5D_COMPACT_F
! H5D_CONTIGUOUS_F
! H5D_CHUNKED_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_layout_f
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.
hid_t fapl_id |
IN: File access property list identifier. |
hsize_t size |
IN: Minimum size, in bytes, of metadata block allocations. |
SUBROUTINE h5pset_meta_block_size_f(plist_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list
! identifier
INTEGER(HSIZE_T), INTENT(IN) :: size ! Metadata block size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_meta_block_size_f
H5Pset_multi_type (
hid_t fapl_id,
H5FD_mem_t type
)
MULTI driver.
H5Pset_multi_type sets the data type property in the
file access or data transfer property list fapl_id.
This enables a user application to specify the type of data the
application wishes to access so that the application
can retrieve a file handle for low-level access to the particular member
of a set of MULTI files in which that type of data is stored.
The file handle is retrieved with a separate call
to H5Fget_vfd_handle
(or, in special circumstances, to H5FDget_vfd_handle;
see Virtual File Layer and List of VFL Functions
in HDF5 Technical Notes).
The type of data specified in type may be one of the following:
H5FD_MEM_DEFAULT
| Need description.... | |
H5FD_MEM_SUPER
| Super block ... need description.... | |
H5FD_MEM_BTREE
| Btree ... need description.... | |
H5FD_MEM_DRAW
| Need description.... | |
H5FD_MEM_GHEAP
| Global heap ... need description.... | |
H5FD_MEM_LHEAP
| Local Heap ... need description.... | |
H5FD_MEM_OHDR
| Need description.... |
Use of this function is only appropriate for an HDF5 file written
as a set of files with the MULTI file driver.
hid_t fapl_id |
IN: File access property list or data transfer property list identifier. |
H5FD_mem_t type |
OUT: Type of data. |
H5Pset_preserve(hid_t plist,
hbool_t status
)
H5Pset_preserve sets the
dataset transfer property list status to TRUE or FALSE.
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.
hid_t plist |
IN: Identifier for the dataset transfer property list. |
hbool_t status |
IN: Status of for the dataset transfer property list (TRUE/FALSE). |
SUBROUTINE h5pset_preserve_f(prp_id, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset transfer property
! list identifier
LOGICAL, INTENT(IN) :: flag ! Status for the dataset
! transfer property list
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_preserve_f
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.
As implied above, the primary value of the shuffle filter lies in its coordinated use with a compression filter; it does not provide data compression when used alone. When the shuffle filter is applied to a dataset immediately prior to the use of a compression filter, the compression ratio achieved is often superior to that achieved by the use of a compression filter without the shuffle filter.
hid_t plist_id |
IN: Dataset creation property list identifier. |
SUBROUTINE h5pset_shuffle_f(prp_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_shuffle_f
H5Pset_sieve_buf_size(
hid_t fapl_id,
hsize_t size
)
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.
hid_t fapl_id |
IN: File access property list identifier. |
hsize_t size |
IN: Maximum size, in bytes, of data sieve buffer. |
SUBROUTINE h5pset_sieve_buf_size_f(plist_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list
! identifier
INTEGER(SIZE_T), INTENT(IN) :: size ! Sieve buffer size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_sieve_buf_size_f
H5Pset_sizes(hid_t plist,
size_t sizeof_addr,
size_t sizeof_size
)
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.
hid_t plist |
IN: Identifier of property list to modify. |
size_t sizeof_addr |
IN: Size of an object offset in bytes. |
size_t sizeof_size |
IN: Size of an object length in bytes. |
SUBROUTINE h5pset_sizes_f (prp_id, sizeof_addr, sizeof_size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(SIZE_T), INTENT(IN) :: sizeof_addr ! Size of an object offset
! in bytes
INTEGER(SIZE_T), INTENT(IN) :: sizeof_size ! Size of an object length
! in bytes
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_sizes_f
H5Pset_small_data_block_size(hid_t fapl_id,
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.
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.
hid_t fapl_id |
IN: File access property list identifier. |
hsize_t size |
IN: Maximum size, in bytes, of the small data block.
The default size is 2048. |
SUBROUTINE h5pset_small_data_block_size_f(plist_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id ! File access
! property list identifier
INTEGER(HSIZE_T), INTENT(IN) :: size ! Small raw data block size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_small_data_block_size_f
H5Pset_sym_k(hid_t plist,
unsigned ik,
unsigned lk
)
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.
hid_t plist |
IN: Identifier for property list to query. |
unsigned ik |
IN: Symbol table tree rank. |
unsigned lk |
IN: Symbol table node size. |
SUBROUTINE h5pset_sym_k_f (prp_id, ik, lk, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: ik ! Symbol table tree rank
INTEGER, INTENT(IN) :: lk ! Symbol table node size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_sym_k_f
H5Pset_szip(hid_t plist,
unsigned int options_mask,
unsigned int pixels_per_block)
H5Pset_szip sets an SZIP compression filter,
H5Z_FILTER_SZIP, for a dataset.
SZIP is a compression method designed for use with scientific data.
Before proceeding, be aware that there are factors that affect your rights and ability to use SZIP compression. See the documents at SZIP Compression in HDF5 for important information regarding terms of use and the SZIP copyright notice, for further discussion of SZIP compression in HDF5, and for a list of SZIP-related references.
In the text below, the term pixel refers to an HDF5 data element. This terminology derives from SZIP compression's use with image data, where pixel referred to an image pixel.
The SZIP bits_per_pixel value (see Notes, below)
is automatically set, based on the HDF5 datatype.
SZIP can be used with atomic datatypes that may have size
of 8, 16, 32, or 64 bits.
Specifically, a dataset with a datatype that is
8-, 16-, 32-, or 64-bit
signed or unsigned integer;
char; or
32- or 64-bit float
can be compressed with SZIP.
See Notes, below, for further discussion of the
the SZIP bits_per_pixel setting.
SZIP compression cannot be applied to
compound datatypes,
array datatypes,
variable-length datatypes,
enumerations, or
any other user-defined datatypes.
If an SZIP filter is set up for a dataset containing a non-allowed
datatype, H5Pset_szip will succeed but the subsequent call
to H5Dcreate
will fail;
the conflict is detected only when the property list is used.
SZIP options are passed in an options mask, options_mask,
as follows.
|
Option |
Description (Mutually exclusive; select one.) |
H5_SZIP_EC_OPTION_MASK
|
Selects entropy coding method. |
H5_SZIP_NN_OPTION_MASK
| Selects nearest neighbor coding method. |
|
|
|
H5_SZIP_EC_OPTION_MASK, is best suited for
data that has been processed.
The EC method works best for small numbers.
H5_SZIP_NN_OPTION_MASK,
preprocesses the data then the applies EC method as above.
SZIP compresses data block by block, with a user-tunable block size.
This block size is passed in the parameter
pixels_per_block and must be even and not greater than 32,
with typical values being 8, 10,
16, or 32.
This parameter affects compression ratio;
the more pixel values vary, the smaller this number should be to
achieve better performance.
In HDF5, compression can be applied only to chunked datasets.
If pixels_per_block is bigger than the total
number of elements in a dataset chunk,
H5Pset_szip will succeed but the subsequent call to
H5Dcreate
will fail; the conflict is detected only when the property list
is used.
To achieve optimal performance for SZIP compression,
it is recommended that a chunk's fastest-changing dimension
be equal to N times pixels_per_block
where N is the maximum number of blocks per scan line
allowed by the SZIP library.
In the current version of SZIP, N is set to 128.
H5Pset_szip will fail if SZIP encoding is
disabled in the available copy of the SZIP library.
H5Zget_filter_info can be employed
to avoid such a failure.
hid_t plist |
IN: Dataset creation property list identifier. |
unsigned int options_mask |
IN: A bit-mask conveying the desired SZIP options.
Valid values are H5_SZIP_EC_OPTION_MASK
and H5_SZIP_NN_OPTION_MASK. |
unsigned int pixels_per_block |
IN: The number of pixels or data elements in each data block. |
In non-HDF5 applications, SZIP typically requires that the user application supply additional parameters:
pixels_in_object,
the number of pixels in the object to be compressed
bits_per_pixel,
the number of bits per pixel
pixels_per_scanline,
the number of pixels per scan line
These values need not be independently supplied in the HDF5
environment as they are derived from the datatype and dataspace,
which are already known.
In particular, HDF5 sets
pixels_in_object to the number of elements in a chunk
and bits_per_pixel to the size of the element or
pixel datatype.
The following algorithm is used to set
pixels_per_scanline:
pixels_per_scanline to
128 times pixels_per_block.
pixels_per_block,
set pixels_per_scanline to the minimum of
size and 128 times pixels_per_block.
pixels_per_block
but greater than the number elements in the chunk,
set pixels_per_scanline to the minimum of
the number elements in the chunk and
128 times pixels_per_block.
The HDF5 datatype may have precision that is less than the
full size of the data element, e.g., an 11-bit integer can be
defined using
H5Tset_precision.
To a certain extent, SZIP can take advantage of the
precision of the datatype to improve compression:
H5Tset_offset
or H5Tget_offset),
the data is the in lowest N bits of the data element.
In this case, the SZIP bits_per_pixel
is set to the precision
of the HDF5 datatype.
bits_per_pixel
will be set to the number of bits in the full size of the data
element.
bits_per_pixel will be set to 32.
bits_per_pixel will be set to 64.
HDF5 always modifies the options mask provided by the user
to set up usage of RAW_OPTION_MASK,
ALLOW_K13_OPTION_MASK, and one of
LSB_OPTION_MASK or MSB_OPTION_MASK,
depending on endianness of the datatype.
SUBROUTINE h5pset_szip_f(prp_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id
! Dataset creation property list identifier
INTEGER, INTENT(IN) :: options_mask
! A bit-mask conveying the desired
! SZIP options
! Current valid values in Fortran are:
! H5_SZIP_EC_OM_F
! H5_SZIP_NN_OM_F
INTEGER, INTENT(IN) :: pixels_per_block
! The number of pixels or data elements
! in each data block
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_szip_f
H5Pset_userblock(hid_t plist,
hsize_t size
)
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.).
hid_t plist |
IN: Identifier of property list to modify. |
hsize_t size |
IN: Size of the user-block in bytes. |
SUBROUTINE h5pset_userblock_f (prp_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER(HSIZE_T), INTENT(IN) :: size ! Size of the user-block in bytes
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_userblock_f
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.
H5Pset_vlen_mem_manager sets the memory manager for
variable-length datatype allocation in H5Dread
and free in H5Dvlen_reclaim.
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.
hid_t plist |
IN: Identifier for the dataset transfer property list. |
H5MM_allocate_t alloc |
IN: User's allocate routine, or NULL
for system malloc. |
void *alloc_info |
IN: Extra parameter for user's allocation routine.
Contents are ignored if preceding parameter is NULL. |
H5MM_free_t free |
IN: User's free routine, or NULL
for system free. |
void *free_info |
IN: Extra parameter for user's free routine.
Contents are ignored if preceding parameter is NULL. |
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 |
SUBROUTINE h5punregister_f(class, name, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: class ! Property list class identifier
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to remove
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5punregister_f
|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |