|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5DS H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5L H5O H5P H5R H5S H5T H5Z Tools Datatypes Fortran Compatibility Macros Collective Calls in Parallel (Printable PDF of this Reference Manual) |
The C Interfaces:
Alphabetical Listing
Filter Behavior in HDF5:
Filters can be inserted into the HDF5 pipeline to perform functions
such as compression and conversion. As such, they are a very flexible
aspect of HDF5; for example, a user-defined filter could provide
encryption for an HDF5 dataset.
A filter can be declared as either required or optional. Required is the default status; optional status must be explicitly declared.
A required filter that fails or is not defined causes an entire output operation to fail; if it was applied when the data was written, such a filter will cause an input operation to fail.
The following table summarizes required filter behavior.
| Required FILTER_X not available | FILTER_X available | |
H5Pset_<FILTER_X> |
Will fail. |
Will succeed. |
H5Dwritewith FILTER_X set |
Will fail. | Will succeed; FILTER_X will be applied to the data. |
H5Dreadwith FILTER_X set |
Will fail. | Will succeed. |
An optional filter can be set for an HDF5 dataset even when the filter is not available. Such a filter can then be applied to the dataset when it becomes available on the original system or when the file containing the dataset is processed on a system on which it is available.
A filter can be declared as optional through the use of
the H5Z_FLAG_OPTIONAL flag
with H5Pset_filter.
Consider a situation where one is creating files that will normally be used only on systems where the optional (and fictional) filter FILTER_Z is routinely available. One can create those files on system A, which lacks FILTER_Z, create chunked datasets in the files with FILTER_Z defined in the dataset creation property list, and even write data to those datasets. The dataset object header will indicate that FILTER_Z has been associated with this dataset. But since system A does not have FILTER_Z, dataset chunks will be written without it being applied.
HDF5 has a mechanism for determining whether chunks are actually written with the filters specified in the object header, so while the filter remains unavailable, system A will be able to read the data. Once the file is moved to system B, where FILTER_Z is available, HDF5 will apply FILTER_Z to any data rewritten or new data written in these datasets. Dataset chunks that have been written on system B will then be unreadable on system A; chunks that have not been re-written since being written on system A will remain readable on system A. All chunks will be readable on system B.
The following table summarizes optional filter behavior.
not available | FILTER_Z available with encode and decode | FILTER_Z available decode only | |
H5Pset_<FILTER_Z> |
Will succeed. |
Will succeed. | Will succeed. |
H5Dwritewith FILTER_Z set |
Will succeed; FILTER_Z will not be applied to the data. |
Will succeed; FILTER_Z will be applied to the data. |
Will succeed; FILTER_Z will not be applied to the data. |
H5Dreadwith FILTER_Z set |
Will succeed if FILTER_Z has not actually been applied to data. | Will succeed. | Will succeed. |
The above principles apply generally in the use of
HDF5 optional filters insofar as HDF5 does as much as possible
to complete an operation when an optional filter is unavailable.
(The SZIP filter is an exception to this rule; see
H5Pset_szip for details.)
Notes:
Filters can be applied only to chunked datasets;
they cannot be used with other dataset storage methods,
such as contiguous, compact, or external datasets.
Dataset elements of variable-length and dataset region reference datatypes are stored in separate structures in the file called heaps. Filters cannot currently be applied to these heaps.
H5Pall_filters_avail(
hid_t plist_id
)
H5Pall_filters_avail verifies that all of the filters
set in the dataset or group creation property list plist_id
are currently available.
hid_t plist_id |
IN: Dataset or group 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.
| Release | Change |
| 1.6.0 | Function introduced in this release. |
| 1.8.5 | Function extended to work with group creation property lists. |
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
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 as
follows; see the function index at
the top of this page for a list of functions related to each class:
H5P_OBJECT_CREATE
H5P_FILE_CREATE
H5P_FILE_ACCESS
H5P_DATASET_CREATE
H5P_DATASET_ACCESS
H5P_DATASET_XFER
H5P_FILE_MOUNT
H5P_GROUP_CREATE
H5P_GROUP_ACCESS
H5P_DATATYPE_CREATE
H5P_DATATYPE_ACCESS
H5P_STRING_CREATE
H5P_ATTRIBUTE_CREATE
H5P_OBJECT_COPY
H5P_LINK_CREATE
H5P_LINK_ACCESS
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 parent_class,
const char *name,
H5P_cls_create_func_t create,
void *create_data,
H5P_cls_copy_func_t copy,
void *copy_data,
H5P_cls_close_func_t close,
void *close_data
)
H5Pcreate_class registers a new property list class
with the library.
The new property list class can inherit from an existing property
list class, parent_class, or may be derived from the
default “empty” class, NULL.
New classes with inherited properties from existing classes
may not remove those existing properties, only add or remove
their own class properties.
Property list classes defined and supported in the HDF5 Library
distribution are listed and briefly described in
H5Pcreate.
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: User pointer to any class creation data required |
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: User pointer to any class copy data required |
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 callback function is defined
as follows:
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: User pointer to any class close data required |
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 parent_class |
IN: Property list class to inherit from or NULL |
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 |
void *create_data |
IN: Pointer to user-defined class create data, to be passed along to class create callback |
H5P_cls_copy_func_t copy |
IN: Callback routine called when a property list is copied |
void *copy_data |
IN: Pointer to user-defined class copy data, to be passed along to class copy callback |
H5P_cls_close_func_t close |
IN: Callback routine called when a property list is being closed |
void *close_data |
IN: Pointer to user-defined class close data, to be passed along to class close callback |
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
SUBROUTINE h5pcreate_class_f(parent, name, class, hdferr, create, &
create_data, copy, copy_data, close, close_data)
INTEGER(HID_T) , INTENT(IN) :: parent
CHARACTER(LEN=*), INTENT(IN) :: name
INTEGER(HID_T) , INTENT(OUT) :: class
INTEGER , INTENT(OUT) :: hdferr
TYPE(C_PTR) , OPTIONAL :: create_data, copy_data, close_data
TYPE(C_FUNPTR) , OPTIONAL :: create, copy, close
Inputs:
parent - Parent property list class identifier
Possible values include:
H5P_ROOT_F
H5P_FILE_CREATE_F
H5P_FILE_ACCESS_F
H5P_DATASET_CREATE_F
H5P_DATASET_XFER_F
H5P_FILE_MOUNT_F
name - Name of property to create
Outputs:
class - Property list class identifier hdferr - Returns 0 if successful and -1 if fails
Optional parameters:
H5P_cls_create_func_t (create) - Callback routine called when a
property list is created
create_data - User pointer to any class creation
information needed
H5P_cls_copy_func_t (copy) - Callback routine called when a property
list is copied
copy_data - User pointer to any class copy
information needed
H5P_cls_close_func_t (close) - Callback routine called when a property
list is being closed
close_data - User pointer to any class close
information needed
| Release | Change |
| 1.8.8 | Fortran updated to Fortran2003. |
H5Premove_filter(
hid_t plist_id,
H5Z_filter_t filter
)
H5Premove_filter removes the specified
filter from the filter pipeline in the
dataset or group creation property list plist_id.
The filter parameter specifies the filter to be removed.
Valid values for use in filter are as follows:
H5Z_FILTER_ALL
| Removes all filters from the filter pipeline. |
H5Z_FILTER_DEFLATE
| Data compression filter, employing the gzip algorithm |
H5Z_FILTER_SHUFFLE
| Data shuffling filter |
H5Z_FILTER_FLETCHER32
| Error detection filter, employing the Fletcher32 checksum algorithm |
H5Z_FILTER_SZIP
| Data compression filter, employing the SZIP algorithm |
H5Z_FILTER_NBIT
| Data compression filter, employing the N-Bit algorithm |
H5Z_FILTER_SCALEOFFSET
| Data compression filter, employing the scale-offset algorithm |
Additionally, user-defined filters can be removed with this routine by passing the filter identifier with which they were registered with the HDF5 Library.
Attempting to remove a filter that is not in the filter pipeline is an error.
plist_id
filter
SUBROUTINE h5premove_filter_f(prp_id, filter, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier
INTEGER, INTENT(IN) :: filter ! Filter to be removed
! Valid values are:
! H5Z_FILTER_ALL_F
! H5Z_FILTER_DEFLATE_F
! H5Z_FILTER_SHUFFLE_F
! H5Z_FILTER_FLETCHER32_F
! H5Z_FILTER_SZIP_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success, -1 on failure
END SUBROUTINE h5premove_filter_f
| Release | Changes |
| 1.6.3 |
Function introduced in this release. Fortran subroutine introduced in this release. |
| 1.8.5 | Function extended to work with group creation property lists. |
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. |
| Release | C |
| 1.6.0 | Function introduced in this release. |
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)
INTEGER(HID_T) , INTENT(IN) :: plid
CHARACTER(LEN=*), INTENT(IN) :: name
TYPE , INTENT(OUT) :: value
INTEGER , INTENT(OUT) :: hdferr
Inputs:
prp_id - Property list identifier to modify
name - Name of property to get
value - Property value, supported types are:
INTEGER
REAL
DOUBLE PRECISION
CHARACTER(LEN=*)
Outputs:
hdferr - Returns 0 if successful and -1 if fails
SUBROUTINE h5pget_f(plid, name, value, hdferr)
INTEGER(HID_T) , INTENT(IN) :: plid
CHARACTER(LEN=*), INTENT(IN) :: name
TYPE(C_PTR) , INTENT(OUT) :: value
INTEGER , INTENT(OUT) :: hdferr
Inputs:
prp_id - Property list identifier to modify
name - Name of property to get
value - Pointer to a location to which to copy the value of
the property
Outputs:
hdferr - Returns 0 if successful and -1 if fails
| Release | Change |
| 1.8.8 | Fortran updated to Fortran2003. |
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 alloc_time as one of the
following values:
H5D_ALLOC_TIME_DEFAULT
|
Uses the default allocation time, based on the dataset storage method. See the alloc_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
| Release | C |
| 1.6.0 | Function introduced in this release. |
H5Pget_attr_creation_order(
hid_t ocpl_id,
unsigned *crt_order_flags
)
H5Pget_attr_creation_order retrieves the settings for
tracking and indexing attribute creation order on an object.
ocpl_id is a dataset or group creation property list
identifier. The term ocpl, for object creation property
list, is used when different types of objects may be involved.
crt_order_flags returns flags with the
following meanings:
|
H5P_CRT_ORDER_TRACKED
| Attribute creation order is tracked but not necessarily indexed. |
|
H5P_CRT_ORDER_INDEXED
|
Attribute creation order is indexed
(requires H5P_CRT_ORDER_TRACKED).
|
crt_order_flags is returned with a value of
0 (zero), attribute creation order is neither tracked
nor indexed.
hid_t ocpl_id
|
IN: Object (group or dataset) creation property list identifier |
unsigned *crt_order_flags
|
OUT: Flags specifying whether to track and index attribute creation order |
SUBROUTINE h5pget_attr_creation_order_f(ocpl_id, crt_order_flags, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: ocpl_id ! Object (group or dataset) creation
! property list identifier
INTEGER, INTENT(OUT) :: crt_order_flags ! Flags specifying whether to track
! and index attribute creation order
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_attr_creation_order_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Pget_attr_phase_change(
hid_t ocpl_id,
unsigned *max_compact,
unsigned *min_dense
)
H5Pget_attr_phase_change retrieves threshold values
for attribute storage on an object.
These thresholds determine the point at which attribute storage
changes from compact storage (i.e., storage in the object header)
to dense storage (i.e., storage in a heap and indexed with a B-tree).
In the general case, attributes are initially kept in compact storage.
When the number of attributes exceeds max_compact,
attribute storage switches to dense storage.
If the number of attributes subsequently falls below
min_dense, the attributes are returned to compact storage.
If max_compact is set to 0 (zero),
dense storage always used.
ocpl_id is a dataset or group creation property list
identifier. The term ocpl, for object creation property
list, is used when different types of objects may be involved.
hid_t ocpl_id
|
IN: Object (dataset or group) creation property list identifier |
unsigned *max_compact
|
OUT: Maximum number of attributes to be stored
in compact storage
(Default: 8) |
unsigned *min_dense
|
OUT: Minimum number of attributes to be stored
in dense storage
(Default: 6) |
SUBROUTINE h5pget_attr_phase_change_f(ocpl_id, max_compact, min_dense, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: ocpl_id
! Object (dataset or group) creation property list identifier
INTEGER, INTENT(OUT) :: max_compact
! Maximum number of attributes to be stored in compact storage
! (Default: 8)
INTEGER, INTENT(OUT) :: min_dense
! Minimum number of attributes to be stored in dense storage
! (Default: 6)
INTEGER, INTENT(OUT) :: hdferr
! Error code:
! 0 on success and -1 on failure
END SUBROUTINE h5pget_attr_phase_change_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
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
| Release | C |
| 1.6.0 | The return type changed from hsize_t to size_t. |
| 1.4.0 | The return type changed to hsize_t. |
H5Pget_cache(hid_t plist_id,
int *mdc_nelmts,
size_t *rdcc_nelmts,
size_t *rdcc_nbytes,
double *rdcc_w0
)
H5Pget_cache retrieves
the maximum possible number of elements in the 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.
Note that the *mdc_nelmts parameter is not longer used.
hid_t plist_id |
IN: Identifier of the file access property list. |
int *mdc_nelmts |
IN/OUT: No longer used. |
size_t *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
| Release | C |
| 1.8.0 |
Use of the mdc_nelmts parameter discontinued.
Metadata cache configuration is managed with H5Pset_mdc_config and H5Pget_mdc_config. |
| 1.6.0 |
The rdcc_nbytes and rdcc_nelmts
parameters changed from
type int to size_t. |
H5Pget_char_encoding(
hid_t plist_id,
H5T_cset_t encoding
)
H5Pget_char_encoding retrieves the character encoding
used to encode strings or object names that are created with the
property list plist_id.
Valid values for encoding are defined in
H5Tpublic.h and include the following:
H5T_CSET_ASCII
| US ASCII | |
H5T_CSET_UTF8
| UTF-8 Unicode encoding |
hid_t plist_id |
IN: Property list identifier |
H5T_cset_t encoding |
OUT: String encoding character set |
SUBROUTINE h5pget_char_encoding_f(plist_id, encoding, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id
! Property list identifier
INTEGER, INTENT(OUT) :: encoding ! Valid values for encoding are:
! H5T_CSET_ASCII_F -> US ASCII
! H5T_CSET_UTF8_F -> UTF-8 Unicode encoding
INTEGER, INTENT(OUT) :: hdferr ! Error code:
! 0 on success and -1 on failure
END SUBROUTINE h5pget_char_encoding_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
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_chunk_cache(
hid_t dapl_id,
size_t *rdcc_nslots,
size_t *rdcc_nbytes,
double *rdcc_w0
)
H5Pget_chunk_cache
retrieves the number of chunk slots in the raw data chunk cache hash table
, the maximum possible number of bytes in the raw data chunk cache, and
the preemption policy value.
These values are retrieved from a dataset access property list. If the values have not been set on the property list, then values returned will be the corresponding values from a default file access property list.
Any (or all) pointer arguments may be null pointers, in which case the corresponding datua is not returned.
hid_t plist_id
| IN: Dataset access property list identifier. | |
size_t *rdcc_nslots
| OUT: Number of chunk slots in the raw data chunk cache hash table. | |
size_t *rdcc_nbytes
| OUT: Total size of the raw data chunk cache, in bytes. | |
double *rdcc_w0
| OUT: Preemption policy. |
dapl_id into local variables:
size_t nslots, nbytes; double w0; status = H5Pget_chunk_cache(dapl_id, &nslots, &nbytes, &w0);
SUBROUTINE h5pget_chunk_cache_f(dapl_id, rdcc_nslots, rdcc_nbytes, rdcc_w0, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: dapl_id ! Dataset access property list identifier.
INTEGER(SIZE_T), INTENT(OUT) :: rdcc_nslots ! Number of chunk slots in the raw data chunk
! cache hash table.
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_chunk_cache_f
H5Pset_chunk_cache
| Release | Change |
| 1.8.3 | C function introduced in this release. |
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_copy_object(
hid_t ocp_plist_id,
unsigned *copy_options
)
H5Pget_copy_object retrieves the properties currently
specified in the object copy property list ocp_plist_id,
which will be invoked when a new copy is made of an existing object.
copy_options is a bit map indicating the flags,
or properties, governing object copying that are set in the
property list ocp_plist_id.
The available flags are described in
H5Pset_copy_object.
hid_t ocp_plist_id
|
IN: Object copy property list identifier |
unsigned *copy_options
|
OUT: Copy option(s) set in the object copy property list |
SUBROUTINE h5pget_copy_object_f(ocp_plist_id, copy_options, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: ocp_plist_id
! Object copy property list identifier
INTEGER, INTENT(OUT) :: copy_options ! Valid copy options returned are:
! H5O_COPY_SHALLOW_HIERARCHY_F
! H5O_COPY_EXPAND_SOFT_LINK_F
! H5O_COPY_EXPAND_EXT_LINK_F
! H5O_COPY_EXPAND_REFERENCE_F
! H5O_COPY_WITHOUT_ATTR_FLAG_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
| Release | C |
| 1.8.0 | Function introduced in this release. |
| 1.8.3 | Fortran subroutine introduced in this release. |
H5Pget_create_intermediate_group(
hid_t lcpl_id,
unsigned *crt_intermed_group
)
H5Pget_create_intermediate_group determines whether
the link creation property list lcpl_id is set
to allow functions that create objects in groups different from the
current working group to create intermediate groups that may be
missing in the path of a new or moved object.
Functions that create objects in or move objects to a group
other than the current working group make use of this property.
H5Gcreate_anon and H5Lmove are
examples of such functions.
If crt_intermed_group is true,
missing intermediate groups will be created;
if crt_intermed_group is false,
missing intermediate groups will not be created.
hid_t lcpl_id
|
IN: Link creation property list identifier |
unsigned *crt_intermed_group
|
OUT: Flag specifying whether to create intermediate groups upon creation of an object |
| Release | C |
| 1.8.0 | Function introduced in this release. |
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 |
SUBROUTINE h5pget_data_transform_f(plist_id, expression, hdferr, size)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id
! Identifier of the property list or class
CHARACTER(LEN=*), INTENT(OUT) :: expression
! Buffer to hold transform expression
INTEGER(SIZE_T), INTENT(OUT), OPTIONAL :: size
! Registered size for transform expression
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_data_transform_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
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 distributed with HDF5 are listed and described in the following table.
| Supported file drivers in HDF5 | ||||||
|
Driver Name |
Driver Identifier |
Description | Related API | |||
| POSIX | H5FD_SEC2 |
This driver uses POSIX file-system functions like read and write to perform I/O to a single, permanent file on local disk with no system buffering. This driver is POSIX-compliant and is the default file driver for all systems. | H5Pset_fapl_sec2 | |||
| Direct | H5FD_DIRECT |
This is the H5FD_SEC2 driver except data is
written to or read from the file synchronously without being
cached by the system. |
H5Pset_fapl_direct | |||
| Log | H5FD_LOG |
This is the H5FD_SEC2 driver with logging
capabilities. |
H5Pset_fapl_log | |||
| Windows | H5FD_WINDOWS |
This driver was modified in HDF5-1.8.8 to be a wrapper of the POSIX driver, H5FD_SEC2. This change should not affect user applications. | H5Pset_fapl_windows | |||
| STDIO | H5FD_STDIO |
This driver uses functions from the standard C
stdio.h to perform I/O to a single, permanent file
on local disk with additional system buffering. |
H5Pset_fapl_stdio | |||
| Memory | H5FD_CORE |
With this driver, an application can work with a file in memory for faster reads and writes. File contents are kept in memory until the file is closed. At closing, the memory version of the file can be written back to disk or abandoned. | H5Pset_fapl_core | |||
| Family | H5FD_FAMILY |
With this driver, the HDF5 file’s address space is partitioned into pieces and sent to separate storage files using an underlying driver of the user’s choice. This driver is for systems that do not support files larger than 2 gigabytes. | H5Pset_fapl_family | |||
| Multi | H5FD_MULTI |
With this driver, data can be stored in multiple files according to the type of the data. I/O might work better if data is stored in separate files based on the type of data. The Split driver is a special case of this driver. | H5Pset_fapl_multi | |||
| Split | H5FD_SPLIT |
This file driver splits a file into two parts. One part stores metadata, and the other part stores raw data. This splitting a file into two parts is a limited case of the Multi driver. | H5Pset_fapl_split | |||
| Parallel | H5FD_MPIO |
This is the standard HDF5 file driver for parallel file systems. This driver uses the MPI standard for both communication and file I/O. | H5Pset_fapl_mpio | |||
| Parallel POSIX | H5FD_MPIPOSIX |
This parallel file system driver uses MPI for communication and POSIX file-system calls for file I/O. | H5Pset_fapl_mpiposix | |||
| Stream | H5FD_STREAM |
This driver is no longer available. | ||||
This list does not include custom drivers that might be defined and registered by a user.
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
| Release | C |
| 1.4.0 | Function introduced in this release. |
H5Pget_driver_info(
hid_t plist_id
)
H5Pget_driver_info returns a pointer to
file driver-specific information for the low-level driver
associated with the file access or data transfer property list
plist_id.
The pointer returned by this function points to an
“uncopied” struct.
Driver-specific versions of that struct are defined for each
low-level driver in the relevant source code file
H5FD*.c.
For example, the struct used for the MULTI driver
is H5FD_multi_fapl_t defined in H5FDmulti.c.
If no driver-specific properties have been registered,
H5Pget_driver_info returns NULL.
H5Pget_driver_info and H5Pset_driver
are used only when creating a virtual file driver (VFD)
in the virtual file layer (VFL). For further information, see
“Virtual File Layer”
and “List of VFL
Functions” in the
HDF5 Technical Notes.
plist_id
NULL.
NULL is also returned if no driver-specific properties
have been registered.
No error is pushed on the stack in this case.
| Release | C |
| 1.8.2 | Function publicized in this release; previous releases described this function only in the virtual file driver documentation. |
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
| Release | C |
| 1.4.0 | Function introduced in this release. |
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. |
| Release | C |
| 1.4.0 | Function introduced in this release. |
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
| Release | C |
| 1.6.0 | Function introduced in this release. |
H5Pget_elink_acc_flags(
hid_t lapl_id,
unsigned *flags
)
H5Pget_elink_acc_flags
retrieves the file access flag used to open an external link target file
from the specified link access property list.
The value returned, if it is not H5F_ACC_DEFAULT will
override the default access flag, which is the access flag used to open
the parent file.
hid_t lapl_id
| IN: Link access property list identifier | |||||||||||||
unsigned *flags
| OUT: File access flag for link traversal.
Valid values include:
|
lapl_id into a local
variable:
unsigned acc_flags; status = H5Pget_elink_acc_flags(lapl_id, &acc_flags);
H5Pset_elink_acc_flags
| Release | Change |
| 1.8.3 | C function introduced in this release. |
H5Pget_elink_cb(
hid_t lapl_id,
H5L_elink_traverse_t *func,
void **op_data
)
H5Pget_elink_cb
retrieves the user-defined external link traversal callback function
defined in the specified link access property list.
The callback function may adjust the file access property list and file access flag to use when opening a file through an external link. The callback will be executed by the HDF5 Library immediately before opening the target file.
hid_t lapl_id
| IN: Link access property list identifier. | |
H5L_elink_traverse_t *func
| OUT: User-defined external link traversal callback function. | |
void **op_data
| OUT: User-defined input data for the callback function. |
H5Pget_elink_cb will fail if the link access
property list identifier, lapl_id, is invalid.
An invalid function pointer or data pointer,
func or op_data respectively,
may cause a segmentation fault or an invalid memory access.
lapl_id into local variables:
H5L_elink_traverse_t elink_callback_func; void *elink_callback_udata; status = H5Pget_elink_cb(lapl_id, &elink_callback_func, &elink_callback_udata);
H5Pset_elink_cb
H5Pset_elink_fapl,
H5Pset_elink_acc_flags,
H5Lcreate_external
H5Fopen for discussion of
H5F_ACC_RDWR and H5F_ACC_RDONLY
file access flags
| Release | Change |
| 1.8.3 | C function introduced in this release. |
H5Pget_elink_fapl(
hid_t lapl_id
)
H5Pget_elink_fapl retrieves the
file access property list identifier that is set for the
link access property list identifier, lapl_id.
The library uses this file access property list identifier to open
the target file for the external link access.
When no such identifier is set, this routine returns
H5P_DEFAULT.
See also H5Pset_elink_fapl and H5Lcreate_external.
hid_t lapl_id |
IN: Link access property list identifier. |
| Release | C |
| 1.8.2 | Function introduced in this release. |
H5Pget_elink_file_cache_size(
hid_t fapl_id,
unsigned *efc_size
)
H5Pget_elink_file_cache_size
retrieves the number of files that can be held open in an
external link open file cache.
hid_t fapl_id
| IN: File access property list identifier | |
unsigned *efc_size
| OUT: External link open file cache size in number of files. |
efc_size:
status = H5Pget_elink_file_cache_size(fapl_id, &efc_size);
H5Pset_elink_file_cache_size
H5Fclear_elink_file_cache
| Release | Change |
| 1.8.7 | C function introduced in this release. |
H5Pget_elink_prefix(
hid_t lapl_id,
char *prefix,
size_t size
)
H5Pget_elink_prefix retrieves the prefix applied
to the path of any external links traversed.
When an external link is traversed, the prefix is retrieved
from the link access property list lapl_id,
returned in the user-allocated buffer pointed to by
prefix, and
prepended to the filename stored in the external link.
The size in bytes of the prefix, including the NULL
terminator, is specified in size.
If size is unknown,
a preliminary H5Pget_elink_prefix call
with the pointer prefix set to NULL
will return the size of the prefix
without the NULL terminator.
hid_t lapl_id |
IN: Link access property list identifier |
char *prefix |
OUT: Prefix applied to external link paths |
size_t size |
IN: Size of prefix, including null terminator |
NULL terminator;
otherwise returns a negative value.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Pget_est_link_info(
hid_t gcpl_id,
unsigned *est_num_entries,
unsigned *est_name_len
)
H5Pget_est_link_info queries
a group creation property list, gcpl_id, for its
“estimated number of links” and
“estimated average name length” settings.
The estimated number of links anticipated to be inserted into
a group created with this property list is returned in
est_num_entries.
The estimated average length of the anticipated link names
is returned in est_name_len.
The values for these two settings are multiplied to compute the initial local heap size (for old-style groups, if the local heap size hint is not set) or the initial object header size for (new-style compact groups; see “Group implementations in HDF5”). Accurately setting these parameters will help reduce wasted file space.
A value of 0 (zero) in est_num_entries
will prevent a group from being created in the compact format.
See “Group implementations in HDF5” in the H5G API introduction for a discussion of the available types of HDF5 group structures.
hid_t gcpl_id |
IN: Group creation property list identifier |
unsigned *est_num_entries |
OUT: Estimated number of links to be inserted into group |
unsigned *est_name_len |
OUT: Estimated average length of link names |
SUBROUTINE h5pget_est_link_info_f(gcpl_id,est_num_entries, est_name_len,hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list id
INTEGER, INTENT(OUT) :: est_num_entries ! Estimated number of links to be
! inserted into group
INTEGER, INTENT(OUT) :: est_name_len ! Estimated average length of link
! names
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_est_link_info_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
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(SIZE_T), 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
| Release | C |
| 1.6.4 |
idx parameter type changed to
unsigned. |
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 |
OUT: Offset in bytes within the HDF5 file. |
| Release | C |
| 1.6.0 | Function introduced in this release. |
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
| Release | C | Fortran90 | |
| 1.6.0 |
The backing_store parameter type
changed from INTEGER to LOGICAL
to better match the C API | ||
| 1.4.0 | Function introduced in this release. |
H5Pget_fapl_direct(
hid_t fapl_id,
size_t *alignment,
size_t *block_size,
size_t *cbuf_size
)
H5Pget_fapl_direct retrieves the
required memory alignment (alignment),
file system block size (block_size), and
copy buffer size (cbuf_size) settings
for the direct I/O driver, H5FD_DIRECT,
from the file access property list fapl_id.
See
H5Pset_fapl_direct
for discussion of these values, requirements, and
important considerations.
hid_t fapl_id
|
IN: File access property list identifier |
size_t *alignment
|
OUT: Required memory alignment boundary |
size_t *block_size
|
OUT: File system block size |
size_t *cbuf_size
|
OUT: Copy buffer size |
SUBROUTINE H5Pget_fapl_direct_f(fapl_id, alignment, block_size, cbuf_size, &
hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier
INTEGER(SIZE_T), INTENT(OUT) :: alignment
! Required memory alignment boundary!
INTEGER(SIZE_T), INTENT(OUT) :: block_size
! File system block size
INTEGER(SIZE_T), INTENT(OUT) :: cbuf_size
! Copy buffer size
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE H5Pget_fapl_direct_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
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
| Release | C |
| 1.4.0 | Function introduced in this release. |
H5Pget_fapl_mpio(
hid_t fapl_id,
MPI_Comm *comm,
MPI_Info *info
)
H5FD_MPIO
driver, H5Pget_fapl_mpio returns duplicates of
the stored MPI communicator and Info object through the
comm and info
pointers, if those values are non-null.
Since the MPI communicator and Info object are duplicates of the stored information, future modifications to the access property list will not affect them. It is the responsibility of the application to free these objects.
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
| Release | Change |
| 1.4.5 | Handling of the MPI Communicator and Info object changed at this release. A duplicate of each of these objects is now returned instead of pointers to each object. |
| 1.4.0 | C function introduced in this release. |
H5Pget_fapl_mpiposix(
hid_t fapl_id,
MPI_Comm *comm,
hbool_t *use_gpfs_hints
)
H5FD_MPIPOSIX
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.
use_gpfs_hints specifies whether to attempt to use
GPFS hints when accessing this file.
A value of TRUE (or 1) indicates that
the hints are being used, where possible.
A value of FALSE (or 0) indicates that
the hints are not being used.
hid_t fapl_id |
IN: File access property list identifier. |
MPI_Comm *comm |
OUT: MPI-2 communicator. |
hbool_t *use_gpfs_hints |
OUT: Use of GPFS hints. |
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
| Release | Change |
| 1.6.1 | Fortran subroutine introduced. |
| 1.6.0 | use_gpfs_hints parameter added. |
| 1.6.0 | C function introduced in this release. |
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: The offsets within the virtual address space,
from 0 (zero) to HADDR_MAX,
at which each type of data storage begins. |
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
| Release | C |
| 1.4.0 | Function introduced in this release. |
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 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
| Release | C |
| 1.6.0 | Function introduced in this release. |
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
| Release | C |
| 1.6.0 | Function introduced in this release. |
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)
INTEGER(HID_T), INTENT(IN) :: prp_id
INTEGER(HID_T), INTENT(IN) :: type_id
TYPE(VOID) , INTENT(OUT) :: fillvalue
INTEGER , INTENT(OUT) :: hdferr
Inputs:
prp_id - Property list identifier type_id - Datatype identifier of fill value datatype (in memory)
Outputs:
fillvalue - Fillvalue hdferr - Returns 0 if successful and -1 if fails
SUBROUTINE h5pget_fill_value_f(prp_id, type_id, fillvalue, hdferr)
INTEGER(HID_T), INTENT(IN) :: prp_id
INTEGER(HID_T), INTENT(IN) :: type_id
TYPE(C_PTR) , INTENT(OUT) :: fillvalue
INTEGER , INTENT(OUT) :: hdferr
Inputs:
prp_id - Property list identifier type_id - Datatype identifier of fill value datatype (in memory)
Outputs:
fillvalue - Fillvalue hdferr - Returns 0 if successful and -1 if fails
| Release | Change |
| 1.8.8 | Fortran updated to Fortran2003. |
H5Pget_filter is a macro that is mapped to either
H5Pget_filter1 or
H5Pget_filter2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. For example:
H5Pget_filter macro
will be mapped to H5Pget_filter1 and
will use the H5Pget_filter1 syntax
(first signature above)
if an application is coded for HDF5 Release 1.6.x.
H5Pget_filter macro
mapped to H5Pget_filter2 and
will use the H5Pget_filter2 syntax
(second signature above)
if an application is coded for HDF5 Release 1.8.x.
Macro use and mappings are fully described in “API Compatibility Macros in HDF5” we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Pget_filter is mapped to the most recent version of
the function, currently
H5Pget_filter2.
If the library and/or application is compiled for Release 1.6
emulation, H5Pget_filter will be mapped to
H5Pget_filter1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Pget_filter mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Pget_filter2 |
| Enable deprecated symbols | H5Pget_filter2 |
| Disable deprecated symbols | H5Pget_filter2 |
Emulate Release 1.6 interface |
H5Pget_filter1 |
Function-level macros |
|
H5Pget_filter_vers = 2 |
H5Pget_filter2 |
H5Pget_filter_vers = 1 |
H5Pget_filter1 |
H5Pget_filter interface
and the only interface available prior to HDF5 Release 1.8.0.
This signature and the corresponding function are now deprecated
but will remain directly callable as
H5Pget_filter1.
Signature [2] above was introduced with HDF5 Release 1.8.0
and is the recommended and default interface.
It is directly callable as
H5Pget_filter2.
See “API Compatibility Macros in HDF5” for circumstances under which either of these functions might not be available in an installed instance of the HDF5 Library.
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
| Release | C |
| 1.8.0 | The function
H5Pget_filter renamed to H5Pget_filter1
and deprecated in this release.
The macro H5Pget_filter
and the function H5Pget_filter2
introduced in this release. |
H5Pget_filter1(
hid_t plist_id,
unsigned int idx,
unsigned int *flags,
size_t *cd_nelmts,
unsigned int *cd_values,
size_t namelen,
char name[]
)
H5Pget_filter and
deprecated in favor of the function
H5Pget_filter2
or the new macro
H5Pget_filter.
H5Pget_filter1 returns information about a
filter, specified by its filter number, in a filter pipeline,
specified by the property list with which it is associated.
plist_id must be a dataset or group creation property list.
idx 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.
The structure of the flags argument is discussed
in H5Pset_filter.
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.
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.
hid_t plist_id |
IN: Dataset or group creation property list identifier. |
int idx |
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 |
H5Z_FILTER_NBIT
| Data compression filter, employing the N-bit algorithm |
H5Z_FILTER_SCALEOFFSET
| Data compression filter, employing the scale-offset 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
| Release | Change |
| 1.6.4 |
filter parameter type changed to
unsigned. |
| 1.8.0 | N-bit and scale-offset filters added. |
| 1.8.0 |
Function H5Pget_filter renamed to
H5Pget_filter1 and deprecated
in this release. |
| 1.8.5 | Function extended to work with group creation property lists. |
H5Pget_filter2(
hid_t plist_id,
unsigned idx,
unsigned int *flags,
size_t *cd_nelmts,
unsigned cd_values[],
size_t namelen,
char name[],
unsigned *filter_config
)
H5Pget_filter2 returns information about a
filter, specified by its filter number, in a filter pipeline,
specified by the property list with which it is associated.
plist_id must be a dataset or group creation property list.
idx 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.
The structure of the flags argument is discussed
in H5Pset_filter.
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.
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.
filter_config is the bit field described in
H5Zget_filter_info.
hid_t plist_id |
IN: Dataset or group creation property list identifier. |
int idx |
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. |
unsigned int *filter_config |
OUT: Bit field, as described in
H5Zget_filter_info. |
H5Z_FILTER_DEFLATE
| Data compression filter, employing the gzip algorithm |
H5Z_FILTER_SHUFFLE
| Data shuffling filter |
H5Z_FILTER_FLETCHER32
| Error detection filter, employing the Fletcher32 checksum algorithm |
H5Z_FILTER_SZIP
| Data compression filter, employing the SZIP algorithm |
H5Z_FILTER_NBIT
| Data compression filter, employing the N-bit algorithm |
H5Z_FILTER_SCALEOFFSET
| Data compression filter, employing the scale-offset algorithm |
| Release | Change |
| 1.8.0 | Function introduced in this release. |
| 1.8.5 | Function extended to work with group creation property lists. |
H5Pget_filter_by_id is a macro that is mapped to either
H5Pget_filter_by_id1 or
H5Pget_filter_by_id2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. For example:
H5Pget_filter_by_id macro
will be mapped to H5Pget_filter_by_id1 and
will use the H5Pget_filter_by_id1 syntax
(first signature above)
if an application is coded for HDF5 Release 1.6.x.
H5Pget_filter_by_id macro
mapped to H5Pget_filter_by_id2 and
will use the H5Pget_filter_by_id2 syntax
(second signature above)
if an application is coded for HDF5 Release 1.8.x.
Macro use and mappings are fully described in “API Compatibility Macros in HDF5” we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Pget_filter_by_id is mapped to the most recent version of
the function, currently
H5Pget_filter_by_id2.
If the library and/or application is compiled for Release 1.6
emulation, H5Pget_filter_by_id will be mapped to
H5Pget_filter_by_id1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Pget_filter_by_id mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Pget_filter_by_id2 |
| Enable deprecated symbols | H5Pget_filter_by_id2 |
| Disable deprecated symbols | H5Pget_filter_by_id2 |
| Emulate Release 1.6 interface | H5Pget_filter_by_id1 |
Function-level macros |
|
H5Pget_filter_by_id_vers = 2 |
H5Pget_filter_by_id2 |
H5Pget_filter_by_id_vers = 1 |
H5Pget_filter_by_id1 |
H5Pget_filter_by_id interface
and the only interface available prior to HDF5 Release 1.8.0.
This signature and the corresponding function are now deprecated
but will remain directly callable as
H5Pget_filter_by_id1.
Signature [2] above was introduced with HDF5 Release 1.8.0
and is the recommended and default interface.
It is directly callable as
H5Pget_filter_by_id2.
See “API Compatibility Macros in HDF5” for circumstances under which either of these functions might not be available in an installed instance of the HDF5 Library.
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
| Release | C |
| 1.8.0 | The function
H5Pget_filter_by_id renamed to
H5Pget_filter_by_id1
and deprecated in this release.
The macro H5Pget_filter_by_id
and the function H5Pget_filter_by_id2
introduced in this release. |
H5Pget_filter_by_id1(
hid_t plist_id,
H5Z_filter_t filter_id,
unsigned int *flags,
size_t *cd_nelmts,
unsigned int cd_values[],
size_t namelen,
char name[]
)
H5Pget_filter_by_id and
deprecated in favor of the function
H5Pget_filter_by_id2
or the new macro
H5Pget_filter_by_id.
H5Pget_filter_by_id1 returns information about the
filter specified in filter_id, a filter identifier.
plist_id must be a dataset or group creation property list
and filter_id must be in the associated filter pipeline.
The filter_id 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 namelen parameter indicates the
number of characters allocated for the filter name
by the calling program in the array name[].
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_id is not
set for the property list, an error will be returned
and H5Pget_filter_by_id1 will fail.
hid_t plist_id |
IN: Dataset or group creation property list identifier. |
H5Z_filter_t filter_id |
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. |
unsigned int *cd_values |
OUT: Auxiliary data for the filter. |
size_t namelen |
IN: Length of filter name and
number of elements in name[]. |
char name[] |
OUT: Name of filter. |
H5Pget_filter_by_id
macro description.
| Release | Change |
| 1.6.0 | Function introduced in this release. |
| 1.8.0 |
Function H5Tget_filter_by_id renamed to
H5Tget_filter_by_id1 and deprecated
in this release. |
| 1.8.5 | Function extended to work with group creation property lists. |
H5Pget_filter_by_id2(
hid_t plist_id,
H5Z_filter_t filter_id,
unsigned int *flags,
size_t *cd_nelmts,
unsigned int cd_values[],
size_t namelen,
char name[],
unsigned int *filter_config
)
H5Pget_filter_by_id2 returns information about the
filter specified in filter_id, a filter identifier.
plist_id must be a dataset or group creation property list
and filter_id must be in the associated filter pipeline.
The filter_id 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 namelen parameter indicates the
number of characters allocated for the filter name
by the calling program in the array name[].
On exit name[] contains the name of the filter
with one character of the name in each element of the array.
filter_config is the bit field described in
H5Zget_filter_info.
If the filter specified in filter_id is not
set for the property list, an error will be returned
and H5Pget_filter_by_id2 will fail.
hid_t plist_id |
IN: Dataset or group creation property list identifier. |
H5Z_filter_t filter_id |
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. |
unsigned int *cd_values |
OUT: Auxiliary data for the filter. |
size_t namelen |
IN: Length of filter name and
number of elements in name[]. |
char name[] |
OUT: Name of filter. |
unsigned int *filter_config |
OUT: Bit field, as described in
H5Zget_filter_info. |
H5Pget_filter_by_id
macro description.
| Release | Change |
| 1.8.0 | Function introduced in this release. |
| 1.8.5 | Function extended to work with group creation property lists. |
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
| Release | C |
| 1.6.0 | Function introduced in this release. |
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
| Release | C |
| 1.6.4 |
ik parameter type changed to
unsigned. |
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_libver_bounds(
hid_t fapl_id,
H5F_libver_t *libver_low,
H5F_libver_t *libver_high
)
H5Pget_libver_bounds retrieves the lower and upper bounds
on the HDF5 Library versions that indirectly determine the object
formats versions used when creating objects in the file.
This property is retrieved from the file access property list specified
by fapl_id.
hid_t fapl_id
|
IN: File access property list identifier | ||||||
H5F_libver_t *libver_low
|
OUT: The earliest version of the library that will
be used for writing objects. The library version indirectly
specifies the earliest object format version that can be used
when creating objects in the file.
Valid values of
| ||||||
H5F_libver_t *libver_high
|
OUT: The latest version of the library that
will be used for writing objects.
The library version indirectly specifies the latest object
format version that can be used when creating objects in the file.
Valid values of
|
| Release | C |
| 1.8.0 | Function introduced in this release. |
| 1.8.6 |
H5F_LIBVER_18 version boundary setting added
in this release. |
H5Pget_link_creation_order(
hid_t gcpl_id,
unsigned *crt_order_flags
)
H5Pget_link_creation_order queries the group creation
property list, gcpl_id, and returns a flag indicating
whether link creation order is tracked and/or indexed in a group.
See
H5Pset_link_creation_order for a list of valid
creation order flags, as passed in crt_order_flags,
and their meanings.
hid_t gcpl_id |
IN: Group creation property list identifier |
unsigned *crt_order_flags |
OUT: Creation order flag(s) |
SUBROUTINE h5pget_link_creation_order_f(gcpl_id, crt_order_flags, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list id
INTEGER, INTENT(OUT) :: crt_order_flags ! Creation order flag(s)
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_link_creation_order_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Pget_link_phase_change(
hid_t gcpl_id,
unsigned *max_compact,
unsigned *min_dense
)
H5Pget_link_phase_change queries the
maximum number of entries for a compact group and the
minimum number links to require before converting a group
to a dense form.
In the compact format, links are stored as messages in the group’s header. In the dense format, links are stored in a fractal heap and indexed with a version 2 B-tree.
max_compact is the maximum number of links
to store as header messages in the group header before
converting the group to the dense format.
Groups that are in the compact format and exceed this number of links
are automatically converted to the dense format.
min_dense is the minimum number of links to
store in the dense format. Groups which are in dense format
and in which the number of links falls below this number are
automatically converted back to the compact format.
In the compact format, links are stored as messages in the group’s header. In the dense format, links are stored in a fractal heap and indexed with a version 2 B-tree.
See H5Pset_link_phase_change
for a discussion of traditional, compact, and dense group storage.
hid_t gcpl_id |
IN: Group creation property list identifier |
unsigned *max_compact |
OUT: Maximum number of links for compact storage |
unsigned *min_dense |
OUT: Minimum number of links for dense storage |
SUBROUTINE h5pset_link_phase_change_f(gcpl_id, max_compact, min_dense, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: gcpl_id
! Group creation property list identifier
INTEGER, INTENT(IN) :: max_compact
! Maximum number of attributes to be stored
! in compact storage
INTEGER, INTENT(IN) :: min_dense
! Minimum number of attributes to be stored
! in dense storage
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_link_phase_change_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Pget_local_heap_size_hint(
hid_t gcpl_id,
size_t *size_hint
)
H5Pget_local_heap_size_hint queries the
group creation property list, gcpl_id, for the
anticipated size of the local heap, size_hint,
for original-style groups,
i.e., for groups of the style used prior to HDF5 Release 1.8.0.
See
H5Pset_local_heap_size_hint
for further discussion.
hid_t gcpl_id |
IN: Group creation property list identifier |
size_t *size_hint |
OUT: Anticipated size of local heap |
SUBROUTINE h5pget_local_heap_size_hint_f(gcpl_id, size_hint, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: gcpl_id
! Group creation property list identifier
INTEGER(SIZE_T), INTENT(OUT) :: size_hint
! Hint for size of local heap
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_local_heap_size_hint_f
| Release | Change |
| 1.8.0 | Function introduced in this release. |
H5Pget_mdc_config(hid_t
plist_id, H5AC_cache_config_t *config_ptr)
H5Pget_mdc_config gets the initial metadata cache
configuration contained in a file access property list and loads it
into the instance of H5AC_cache_config_t pointed to by
the config_ptr parameter.
This configuration is used when the file is opened.
Note that the version field of *config_ptr must be
initialized; this allows the library to support old versions of the
H5AC_cache_config_t structure.
See the overview of the metadata cache in the special topics section of the user guide for details on the configuration data returned. If you haven't read and understood that documentation, the results of this call will not make much sense.
hid_t plist_id
|
IN: Identifier of the file access property list. |
H5AC_cache_config_t *config_ptr
|
IN/OUT: Pointer to the instance of H5AC_cache_config_t in which the current metadata cache configuration is to be reported. The fields of this structure are discussed below: |
| General configuration section: | |
int version |
IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This field should be set to H5AC__CURR_CACHE_CONFIG_VERSION (defined in H5ACpublic.h). |
hbool_t rpt_fcn_enabled
|
OUT: Boolean flag indicating whether the adaptive
cache resize report function is enabled. This field should almost
always be set to FALSE. Since resize algorithm activity is reported
via stdout, it MUST be set to FALSE on Windows machines.
The report function is not supported code, and can be expected to change between versions of the library. Use it at your own risk. |
hbool_t open_trace_file
|
OUT: Boolean field indicating whether
the trace_file_name field should be
used to open a trace file for the
cache. This field will always be
set to FALSE in this context.
|
hbool_t close_trace_file
|
OUT: Boolean field indicating whether
the current trace file (if any) should
be closed. This field will always
be set to FALSE in this context.
|
char *trace_file_name
|
OUT: Full path name of the trace file
to be opened if the open_trace_file
field is TRUE. This field will always
be set to the empty string in this context.
|
hbool_t evictions_enabled
|
OUT: Boolean flag indicating whether metadata cache entry evictions will be enabled when the file is opened / created. |
hbool_t set_initial_size
|
OUT: Boolean flag indicating whether the cache should be created with a user specified initial maximum size. |
size_t initial_size
|
OUT: Initial maximum size of the cache in bytes, if applicable. |
double min_clean_fraction
|
OUT: Float value specifing the minimum fraction of the cache that must be kept either clean or empty when possible. |
size_t max_size
|
OUT: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select as the maximum cache size. |
size_t min_size
|
OUT: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select as the maximum cache size. |
int epoch_length
|
OUT: Number of cache accesses between runs of the adaptive cache resize code. |
| Increment configuration section: | |
enum H5C_cache_incr_mode incr_mode |
OUT: Enumerated value indicating the operational mode of
the automatic cache size increase code. At present, only the following
values are legal:
H5C_incr__off: Automatic cache size increase is disabled. H5C_incr__threshold: Automatic cache size increase is enabled using the hit rate threshold algorithm. |
double lower_hr_threshold
|
OUT: Hit rate threshold used in the hit rate threshold cache size increase algorithm. |
double increment
|
OUT: The factor by which the current maximum cache size is multiplied to obtain an initial new maximum cache size if a size increase is triggered in the hit rate threshold cache size increase algorithm. |
hbool_t apply_max_increment
|
OUT: Boolean flag indicating whether an upper limit will be applied to the size of cache size increases. |
size_t max_increment
|
OUT: The maximum number of bytes by which the maximum cache size can be increased in a single step -- if applicable. |
enum H5C_cache_flash_incr_mode
flash_incr_mode |
OUT: Enumerated value indicating the operational mode of
the flash cache size increase code. At present, only the following
values are legal:
H5C_flash_incr__off: Flash cache size increase is disabled. H5C_flash_incr__add_space: Flash cache size increase is enabled using the add space algorithm. |
double flash_threshold
|
OUT: The factor by which the current maximum cache size is multiplied to obtain the minimum size entry / entry size increase which may trigger a flash cache size increase. |
double flash_multiple
|
OUT: The factor by which the size of the triggering
entry / entry size increase is multiplied to obtain
the initial cache size increment. This increment
may be reduced to reflect existing free space in
the cache and the max_size field
above. |
| Decrement configuration section: | |
enum H5C_cache_decr_mode decr_mode |
OUT: Enumerated value indicating the operational mode
of the automatic cache size decrease code. At present, the following
values are legal:
H5C_decr__off: Automatic cache size decrease is disabled, and the remaining decrement fields are ignored. H5C_decr__threshold: Automatic cache size decrease is enabled using the hit rate threshold algorithm. H5C_decr__age_out: Automatic cache size decrease is enabled using the ageout algorithm. H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the ageout with hit rate threshold algorithm |
double upper_hr_threshold
|
OUT: Upper hit rate threshold. This value is only used if the decr_mode is either H5C_decr__threshold or H5C_decr__age_out_with_threshold. |
double decrement
|
OUT: Factor by which the current max cache size is multiplied to obtain an initial value for the new cache size when cache size reduction is triggered in the hit rate threshold cache size reduction algorithm. |
hbool_t apply_max_decrement
|
OUT: Boolean flag indicating whether an upper limit should be applied to the size of cache size decreases. |
size_t max_decrement
|
OUT: The maximum number of bytes by which cache size can be decreased if any single step, if applicable. |
int epochs_before_eviction
|
OUT: The minimum number of epochs that an entry must reside unaccessed in cache before being evicted under either of the ageout cache size reduction algorithms. |
hbool_t apply_empty_reserve
|
OUT: Boolean flag indicating whether an empty reserve should be maintained under either of the ageout cache size reduction algorithms. |
double empty_reserve
|
OUT: Empty reserve for use with the ageout cache size reduction algorithms, if applicable. |
| Parallel configuration section: | |
int dirty_bytes_threshold
|
OUT: Threshold number of bytes of dirty metadata
generation for triggering synchronizations of the metadata caches
serving the target file in the parallel case.
Synchronization occurs whenever the number of bytes of dirty metadata created since the last synchronization exceeds this limit. |
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
| Release | C |
| 1.4.0 | Function introduced in this release. |
H5Pget_mpio_actual_chunk_opt_mode(
hid_t dxpl_id,
H5D_mpio_actual_chunk_opt_mode_t *
actual_chunk_opt_mode)
H5Pset_dxpl_mpio. The operation can be optimized in
several different ways, some of which also can be requested by the
user. However, HDF5 may not be able to satisfy requests for
specific optimizations and may choose a different
optimization scheme. This property allows the user to track which
optimization was actually used. Used in conjunction with
H5Pget_mpio_actual_io_mode, this property allows the
user to determine exactly what HDF5 did when attempting collective
chunked I/O.
H5Pget_mpio_actual_chunk_opt_mode
retrieves the type of chunk optimization performed when collective
I/O was requested. This property is set before I/O takes place, and
will be set even if I/O fails.
Valid values returned in actual_chunk_opt_mode:
H5D_MPIO_NO_CHUNK_OPTIMIZATION
|
No chunk optimization was performed. Either no collective I/O
was attempted or the dataset wasn't chunked.
(Default) | ||
H5D_MPIO_MULTI_CHUNK
|
Each chunk was individually assigned collective or independent I/O
based on what fraction of processes access the chunk. If the fraction
is greater than the multi chunk ratio threshold, collective I/O is
performed on that chunk. The multi chunk ratio threshold can be set
using H5Pset_dxpl_mpio_chunk_opt_ratio. The default
value is 60%.
| ||
H5D_MPIO_MULTI_CHUNK_NO_OPT
|
Each chunk is assigned collective or independent I/O based on how many chunks were accessed before it. Collective I/O is performed on the the first chunk in each selection, then the second, and so on until one process finishes, then the remaining processes perform independent I/O on the rest of their selections. | ||
H5D_MPIO_LINK_CHUNK
|
Collective I/O is performed on all chunks simultaneously. |
hid_t dxpl_id
| IN: Dataset transfer property list identifier | |
H5D_mpio_actual_chunk_opt_mode_t *
actual_chunk_opt_mode
| OUT: The type of chunk optimization performed by HDF5. |
H5Pget_mpio_actual_io_mode
is a sister function that reports the type of I/O HDF5 performed.
The following functions request optimizations or change values
that HDF5 uses to choose an optimization scheme:
H5Pset_dxpl_mpio_chunk_opt
H5Pset_dxpl_mpio_chunk_opt_num
H5Pset_dxpl_mpio_chunk_opt_ratio
H5Pset_dxpl_mpio_collective_opt
| Release | Change |
| 1.8.8 | C function introduced in this release. |
H5Pget_mpio_actual_io_mode(
hid_t dxpl_id,
H5D_mpio_actual_io_mode_t *
actual_io_mode)
H5Pset_dxpl_mpio. However,
HDF5 will sometimes ignore this request and perform independent I/O
instead. This property allows the user to see what kind of I/O HDF5
actually performed. Used in conjunction with
H5Pget_mpio_actual_chunk_opt_mode, this property allows
the user to determine exactly HDF5 did when attempting collective I/O.
H5Pget_mpio_actual_io_mode
retrieves the type of I/O performed on the selection of the current
process. This property is set after all I/O is completed; if I/O
fails, it will not be set.
Valid values returned in actual_io_mode:
H5D_MPIO_NO_COLLECTIVE_IO
|
No collective I/O was performed. Collective I/O was not requested
or collective I/O isn't possible on this dataset.
(Default) | ||
H5D_MPIO_CHUNK_INDEPENDENT
|
HDF5 performed one the chunk collective optimization schemes and each chunk was accessed independently. | ||
H5D_MPIO_CHUNK_COLLECTIVE
|
HDF5 performed one the chunk collective optimization schemes and each chunk was accessed collectively. | ||
H5D_MPIO_CHUNK_MIXED
|
HDF5 performed one the chunk collective optimization schemes and some chunks were accessed independently, some collectively. | ||
H5D_MPIO_CONTIGUOUS_COLLECTIVE
|
Collective I/O was performed on a contiguous dataset. |
H5D_MPIO_CHUNK_COLLECTIVE while the second will report
H5D_MPIO_CHUNK_INDEPENDENT.
hid_t dxpl_id |
IN: Dataset transfer property list identifier | |
H5D_mpio_actual_io_mode_t *
actual_io_mode
|
OUT: The type of I/O performed by this process. |
H5Pget_mpio_actual_chunk_opt_mode
is a sister function that reports the type of optimization HDF5 attempted.
| Release | Change |
| 1.8.8 | C function introduced in this release. |
H5Pget_multi_type (
hid_t fapl_id,
H5FD_mem_t *type
)
MULTI driver.
H5Pget_multi_type retrieves the type of data 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. |
| Release | C |
| 1.6.0 | Function introduced in this release. |
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_nlinks(
hid_t lapl_id,
size_t *nlinks
)
H5Pget_nlinks retrieves the maximum number of soft or
user-defined link traversals allowed, nlinks,
before the library assumes
it has found a cycle and aborts the traversal.
This value is retrieved from the link access property list
lapl_id.
The limit on the number soft or user-defined link traversals is designed to terminate link traversal if one or more links form a cycle. User control is provided because some files may have legitimate paths formed of large numbers of soft or user-defined links. This property can be used to allow traversal of as many links as desired.
hid_t fapl_id |
IN: File access property list identifier |
size_t *nlinks |
OUT: Maximum number of links to traverse |
SUBROUTINE h5pget_nlinks_f(lapl_id, nlinks, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: lapl_id
! File access property list identifier
INTEGER(SIZE_T), INTENT(OUT) :: nlinks
! Maximum number of links to traverse
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_nlinks_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
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
| Release | Fortran90 |
| 1.6.0 |
The flag parameter was changed from
INTEGER to LOGICAL to better
match the C API. |
H5Pget_obj_track_times(
hid_t ocpl_id,
hbool_t *track_times
)
H5get_obj_track_times queries the
object creation property list, ocpl_id,
to determine whether object times are being recorded.
If track_times is returned as TRUE,
times are being recorded;
if track_times is returned as FALSE,
times are not being recorded.
Time data can be retrieved with
H5Oget_info,
which will return it in the H5O_info_t struct.
If times are not tracked, they will be reported as follows
when queried:
12:00 AM UDT, Jan. 1, 1970
See
H5Pset_obj_track_times
for further discussion.
hid_t ocpl_id |
IN: Object creation property list identifier |
hbool_t *track_times |
OUT: Boolean value,
TRUE or FALSE,
specifying whether object times are being recorded |
SUBROUTINE h5pget_obj_track_times_f(plist_id, flag, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id
! Dataset creation property
! list identifier
LOGICAL, INTENT(OUT) :: flag ! Object timestamp setting
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pget_obj_track_times_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Pget_shared_mesg_index(
hid_t fcpl_id,
unsigned index_num,
unsigned *mesg_type_flags,
unsigned *min_mesg_size
)
H5Pget_shared_mesg_index retrieves
the message type and minimum message size settings
from the file creation property list fcpl_id
for the shared object header message index specified by
index_num.
index_num specifies the index.
index_num is zero-indexed, so in a file with
three indexes, they will be numbered 0,
1, and 2.
mesg_type_flags and min_mesg_size
will contain, respectively, the types of messages and
the minimum size, in bytes, of messages that can be stored
in this index.
Valid message types are described in
H5Pset_shared_mesg_index.
hid_t fcpl_id |
IN: File creation property list identifier. |
unsigned index_num |
IN: Index being configured. |
unsigned *mesg_type_flags |
OUT: Types of messages that may be stored in this index. |
unsigned *min_mesg_size |
OUT: Minimum message size. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Pget_shared_mesg_nindexes(
hid_t fcpl_id,
unsigned *nindexes
)
H5Pget_shared_mesg_nindexes retrieves the
number of shared object header message indexes
in the specified file creation property list fcpl_id.
If the value of nindexes is 0 (zero),
shared object header messages are disabled in files created
with this property list.
hid_t fcpl_id
|
IN: File creation property list |
unsigned *nindexes
|
OUT: Number of shared object header message indexes available in files created with this property list |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Pget_shared_mesg_phase_change(
hid_t fcpl_id,
unsigned *max_list,
unsigned *min_btree
)
H5Pget_shared_mesg_phase_change retrieves the
threshold values for storage of shared object header message
indexes in a file. These phase change thresholds determine the
point at which the index storage mechanism changes
from a more compact list format
to a more performance-oriented B-tree format, and vice-versa.
By default, a shared object header message index is initially
stored as a compact list.
When the number of messages in an index exceeds the specified
max_list threshold, storage switches to a B-tree
format for impoved performance.
If the number of messages subsequently falls below the
min_btree threshold, the index will revert to the
list format.
If max_compact is set to 0 (zero),
shared object header message indexes in the file will always
be stored as B-trees.
fcpl_id specifies the file creation property list.
hid_t fcpl_id
|
IN: File creation property list identifier |
unsigned *max_compact
|
OUT: Threshold above which storage of a shared object header message index shifts from list to B-tree |
unsigned *min_btree
|
OUT: Threshold below which storage of a shared object header message index reverts to list format |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Pget_sieve_buf_size(
hid_t fapl_id,
size_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. |
size_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
| Release | C |
| 1.6.0 | The size
parameter has changed from type hsize_t
to size_t. |
| 1.4.0 | Function introduced in this release. |
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
| Release | C |
| 1.4.4 | Function introduced in this release. |
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
| Release | C |
| 1.6.4 |
ik parameter type changed to
unsigned |
| 1.6.0 |
The ik parameter has changed
from type int to unsigned |
H5Pget_type_conv_cb(hid_t plist,
H5T_conv_except_func_t *func,
void **op_data)
H5Pget_type_conv_cb gets the user-defined
datatype conversion callback function func
in the dataset transfer property list plist.
The parameter op_data is a pointer to
user-defined input data for the callback function.
The callback function func defines the
actions an application is to take when there is an
exception during datatype conversion.
Please refer to the function H5Pset_type_conv_cb
for more details.
hid_t plist |
IN: Dataset transfer property list identifier. |
H5T_conv_except_func_t *func |
OUT: User-defined type conversion callback function. |
void **op_data |
OUT: User-defined input data for the callback function. |
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
| Release | C |
| 1.6.4 |
boot, freelist,
stab, shhdr
parameter types changed to
unsigned. |
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 is a macro that is mapped to either
H5Pinsert1 or
H5Pinsert2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. For example:
H5Pinsert macro
will be mapped to H5Pinsert1 and
will use the H5Pinsert1 syntax
(first signature above)
if an application is coded for HDF5 Release 1.6.x.
H5Pinsert macro
mapped to H5Pinsert2 and
will use the H5Pinsert2 syntax
(second signature above)
if an application is coded for HDF5 Release 1.8.x.
Macro use and mappings are fully described in “API Compatibility Macros in HDF5” we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Pinsert is mapped to the most recent version of
the function, currently
H5Pinsert2.
If the library and/or application is compiled for Release 1.6
emulation, H5Pinsert will be mapped to
H5Pinsert1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Pinsert mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Pinsert2 |
| Enable deprecated symbols | H5Pinsert2 |
| Disable deprecated symbols | H5Pinsert2 |
| Emulate Release 1.6 interface | H5Pinsert1 |
Function-level macros |
|
H5Pinsert_vers = 2 |
H5Pinsert2 |
H5Pinsert_vers = 1 |
H5Pinsert1 |
H5Pinsert interface
and the only interface available prior to HDF5 Release 1.8.0.
This signature and the corresponding function are now deprecated
but will remain directly callable as
H5Pinsert1.
Signature [2] above was introduced with HDF5 Release 1.8.0
and is the recommended and default interface.
It is directly callable as
H5Pinsert2.
See “API Compatibility Macros in HDF5” for circumstances under which either of these functions might not be available in an installed instance of the HDF5 Library.
SUBROUTINE h5pinsert_f
INTEGER(HID_T) , INTENT(IN) :: plist
CHARACTER(LEN=*), INTENT(IN) :: name
INTEGER(SIZE_T) , INTENT(IN) :: size
TYPE , INTENT(IN) :: value
INTEGER , INTENT(OUT) :: hdferr
Inputs:
plist - Property list class identifier
name - Name of property to insert
size - Size of the property value
value - Property value, supported types are:
INTEGER
REAL
DOUBLE PRECISION
CHARACTER(LEN=*)
Outputs:
hdferr - Returns 0 if successful and -1 if fails
SUBROUTINE h5pinsert_f
INTEGER(HID_T) , INTENT(IN) :: plist
CHARACTER(LEN=*), INTENT(IN) :: name
INTEGER(SIZE_T) , INTENT(IN) :: size
TYPE(C_PTR) , INTENT(IN) :: value
INTEGER , INTENT(OUT) :: hdferr
Inputs:
plist - Property list class identifier name - Name of property to insert size - Size of the property value value - Pointer to new value pointer for the property being modified
Outputs:
hdferr - Returns 0 if successful and -1 if fails
| Release | Change |
| 1.8.8 | Fortran updated to Fortran2003. |
| 1.8.0 | The function
C function H5Pinsert renamed to
H5Pinsert1
and deprecated in this release.
C macro H5Pinsert
and the C function H5Pinsert2
introduced in this release. |
H5Pinsert1(
hid_t plid,
const char *name,
size_t size,
void *value,
H5P_prp_set_func_t set,
H5P_prp_get_func_t get,
H5P_prp_delete_func_t delete,
H5P_prp_copy_func_t copy,
H5P_prp_close_func_t close
)
H5Pinsert and
deprecated in favor of the function
H5Pinsert2
or the new macro
H5Pinsert.
H5Pinsert1 create a new property in a property list.
The property will exist only in this property list and copies made
from it.
The initial property value must be provided in
value and the property value will be set accordingly.
The name of the property must not already exist in this list, or this routine will fail.
The set and get callback routines may
be set to NULL if they are not needed.
Zero-sized properties are allowed and do not store any data in the property list. The default value of a zero-size property may be set to NULL. They may be used to indicate the presence or absence of a particular piece of information.
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);
The parameters to the above callback function are:
hid_t prop_id |
IN: The identifier of the property list being queried |
const char *name |
IN: The name of the property being queried |
size_t size |
IN: The size of the property in bytes |
void *value |
IN: The value of the property being returned |
get routine may modify the value to be returned from
the query and those changes will be preserved.
If the get routine returns a negative value, the query
routine returns an error value.
The delete routine is called when a property is being
deleted from a property list.
The H5P_prp_delete_func_t callback function is defined
as follows:
typedef herr_t (*H5P_prp_delete_func_t)(
hid_t prop_id,
const char *name,
size_t size,
void *value);
The parameters to the above callback function are:
hid_t prop_id |
IN: The identifier of the property list the property is being deleted from |