H5Pset_char_encoding(
hid_t plist_id,
H5T_cset_t encoding
)
H5Pset_char_encoding sets the character encoding
used for the names of links
(which provide the names by which objects are referenced)
or attributes created with the property list plist_id.
Valid values for encoding include the following:
H5T_CSET_ASCII
| US ASCII | |
H5T_CSET_UTF8
| UTF-8 Unicode |
For example, if the character set for the property list
plist_id is set to
H5T_CSET_UTF8,
link names pointing to objects created with the
link creation property list plist_id
will be encoded using the UTF-8 character set.
Similarly, names of attributes created with the
attribute creation property list plist_id
will be encoded as UTF-8.
ASCII and UTF-8 Unicode are the only currently supported character encodings. Extended ASCII encodings (for example, ISO 8859) are not supported. This encoding policy is not enforced by the HDF5 Library. Using encodings other than ASCII and UTF-8 can lead to compatibility and usability problems.
Note that H5Pset_char_encoding
sets the character set used for an HDF5 link or attribute name while
H5Tset_cset
sets the character set used in a character or string datatype.
hid_t plist_id |
IN: Link creation or attribute creation property list identifier |
H5T_cset_t encoding |
IN: String encoding character set |
SUBROUTINE h5pset_char_encoding_f(plist_id, encoding, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: plist_id
! Property list identifier
INTEGER, INTENT(IN) :: encoding ! String encoding character set:
! H5T_CSET_ASCII_F -> US ASCII
! H5T_CSET_UTF8_F -> UTF-8 Unicode encoding
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5pset_char_encoding_f
| Release | C |
| 1.8.0 | Function introduced in this release. |
- Last modified: 16 September 2015
- Name: H5Pset_chunk
- Signature:
- herr_t
H5Pset_chunk(hid_tplist, intndims, const hsize_t *dim) - Purpose:
- Sets the size of the chunks used to store a chunked layout dataset.
- Description:
-
H5Pset_chunksets the size of the chunks used to store a chunked layout dataset. This function is only valid for dataset creation property lists.The
ndimsparameter currently must be the same size as the rank of the dataset.The values of the
dimarray define the size of the chunks to store the dataset's raw data. The unit of measure fordimvalues is dataset elements.As a side-effect of this function, the layout of the dataset is changed to
H5D_CHUNKED, if it is not already so set. (SeeH5Pset_layout.) - Notes:
- Chunk size cannot exceed the size of a fixed-size dataset. For example, a dataset consisting of a 5x4 fixed-size array cannot be defined with 10x10 chunks.
- Chunk maximums
- The maximum number of elements in a chunk is
232-1 which is equal to 4,294,967,295. If the
number of elements in a chunk is set via
H5Pset_chunkto a value greater than 232-1, thenH5Pset_chunkwill fail. - The maximum size for any chunk is 4GB. If a chunk that
is larger than 4GB attempts to be written with
H5Dwrite, thenH5Dwritewill fail. - Parameters:
- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_chunk_f
-
SUBROUTINE h5pset_chunk_f(prp_id, ndims, dims, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(IN) :: ndims ! Number of chunk dimensions INTEGER(HSIZE_T), DIMENSION(ndims), INTENT(IN) :: dims ! Array containing sizes of ! chunk dimensions INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_chunk_f - History:
-
Release Change 1.8.16 Added chunk size limit note to Description.
hid_t plist |
IN: Dataset creation property list identifier. |
int ndims |
IN: The number of dimensions of each chunk. |
const hsize_t * dim |
IN: An array defining the size, in dataset elements, of each chunk. |
- Last modified: 4 November 2014
- Name: H5Pset_chunk_cache
- Signature:
- Name: H5Pset_chunk_cache
- herr_t
H5Pset_chunk_cache( hid_tdapl_id, size_trdcc_nslots, size_trdcc_nbytes, doublerdcc_w0) - Purpose:
- Sets the raw data chunk cache parameters.
- Motivation:
H5Pset_chunk_cacheis used to adjust the chunk cache parameters on a per-dataset basis, as opposed to a global setting for the file usingH5Pset_cache. The optimum chunk cache parameters may vary widely with different data layout and access patterns, so for optimal performance they must be set individually for each dataset. It may also be beneficial to reduce the size of the chunk cache for datasets whose performance is not important in order to save memory space.- Description:
H5Pset_chunk_cachesets the number of elements, the total number of bytes, and the preemption policy value in the raw data chunk cache on a dataset access property list. After calling this function, the values set in the property list will override the values in the file's file access property list.The raw data chunk cache inserts chunks into the cache by first computing a hash value using the address of a chunk, then using that hash value as the chunk's index into the table of cached chunks. The size of this hash table, i.e., and the number of possible hash values, is determined by the
rdcc_nslotsparameter. If a different chunk in the cache has the same hash value, this causes a collision, which reduces efficiency. If inserting the chunk into cache would cause the cache to be too big, then the cache is pruned according to therdcc_w0parameter.- Parameters:
-
hid_t dapl_idIN: Dataset access property list identifier. size_t rdcc_nslotsIN:The number of chunk slots in the raw data chunk cache for this dataset. Increasing this value reduces the number of cache collisions, but slightly increases the memory used. Due to the hashing strategy, this value should ideally be a prime number. As a rule of thumb, this value should be at least 10 times the number of chunks that can fit in rdcc_nbytesbytes. For maximum performance, this value should be set approximately 100 times that number of chunks.The default value is
521. If the value passed isH5D_CHUNK_CACHE_NSLOTS_DEFAULT, then the property will not be set ondapl_idand the parameter will come from the file access property list used to open the file.size_t rdcc_nbytesIN: The total size of the raw data chunk cache for this dataset. In most cases increasing this number will improve performance, as long as you have enough free memory. The default size is 1 MB. If the value passed is
H5D_CHUNK_CACHE_NBYTES_DEFAULT, then the property will not be set ondapl_idand the parameter will come from the file access property list.double rdcc_w0IN: The chunk preemption policy for this dataset. This must be between 0and1inclusive and indicates the weighting according to which chunks which have been fully read or written are penalized when determining which chunks to flush from cache. A value of0means fully read or written chunks are treated no differently than other chunks (the preemption is strictly LRU) while a value of1means fully read or written chunks are always preempted before other chunks. If your application only reads or writes data once, this can be safely set to1. Otherwise, this should be set lower, depending on how often you re-read or re-write the same data.The default value is
0.75. If the value passed isH5D_CHUNK_CACHE_W0_DEFAULT, then the property will not be set ondapl_idand the parameter will come from the file access property list.
- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Example Usage:
- The following code sets the chunk cache to use a hash table with 12421
elements and a maximum size of 16 MB, while using the preemption policy
specified for the entire file:
H5Pset_chunk_cache(dapl_id, 12421, 16*1024*1024, H5D_CHUNK_CACHE_W0_DEFAULT); - Usage Notes:
- The chunk cache size is a property for accessing a dataset and
is not stored with a dataset or a file. To guarantee
the same chunk cache settings each time
H5Dopenis called, callH5Dopenwith a dataset access property list (H5Dopen(hid_t loc_id, const char *name, hid_t dapl_id))where the chunk cache size is set by callingH5Pset_chunk_cachefor that property list. The property list can be used for multiple accesses in the same application.
For files where the same chunk cache size will be appropriate for all or most datasets,H5Pset_cachecan be called with a file access property list to set the chunk cache size for accessing all datasets in the file.
Both methods can be used in combination, in which case the chunk cache size set byH5Pset_cachewill apply except for specific datasets whereH5Dopenis called with dataset property list with the chunk cache size set byH5Pset_chunk_cache.
In the absence of any cache settings,H5Dopenwill by default create a 1 MB chunk cache for the opened dataset. If this size happens to be appropriate, no call will be needed to either function to set the chunk cache size.
It is also possible that a change in access pattern for later access to a dataset will change the appropriate chunk cache size. For more detailed information on chunks, chunk caching, and performance pitfalls, see “Chunking in HDF5”. - Fortran90 Interface: h5pset_chunk_cache_f
-
SUBROUTINE h5pset_chunk_cache_f(dapl_id, rdcc_nslots, rdcc_nbytes, rdcc_w0, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: dapl_id ! Dataset access property list ! identifier. INTEGER(SIZE_T), INTENT(IN) :: rdcc_nslots ! The number of chunk slots in the ! raw data chunk cache for this ! dataset. INTEGER(SIZE_T), INTENT(IN) :: rdcc_nbytes ! The total size of the raw data ! chunk cache for this dataset. REAL, INTENT(IN) :: rdcc_w0 ! The chunk preemption policy for ! this dataset. INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_chunk_cache_f - See Also:
-
H5Pget_chunk_cache
H5Pset_cache
“Chunking in HDF5” - History:
Release Change 1.8.3 C function introduced in this release.
- Last modified: 3 July 2013
- Name: H5Pset_copy_object
- Signature:
- Name: H5Pset_copy_object
- herr_t
H5Pset_copy_object( hid_tocpypl_id, unsignedcopy_options) - Purpose:
- Sets properties to be used when an object is copied.
- Description:
H5Pset_copy_objectsets properties in the object copy property listocpypl_id. When an existing object is copied, that property list will determine how the new copy is created.The following flags are available for use in an object copy property list:
- A committed datatype in the source will be copied to the destination as a committed datatype.
- If a dataset in the source uses a committed datatype or an object in the source has an attribute of a committed datatype, that committed datatype will be written to the destination as an anonymous committed datatype.
- If copied in a single
H5Ocopyoperation, objects that share a committed datatype in the source will share an anonymous committed dataype in the destination copy. SubsequentH5Ocopyoperations, however, will be unaware of prior anonymous committed dataypes and will create new ones.
H5O_COPY_SHALLOW_HIERARCHY_FLAGCopy only immediate members of a group.
Default behavior, without flag: Recursively copy all objects in and below the group.H5O_COPY_EXPAND_SOFT_LINK_FLAGExpand soft links into new objects.
Default behavior, without flag: Copy soft links as they are.H5O_COPY_EXPAND_EXT_LINK_FLAGExpand external link into new objects.
Default behavior, without flag: Copy external links as they are.H5O_COPY_EXPAND_REFERENCE_FLAGCopy objects that are pointed to by references and update reference values in destination file.
Default behavior, without flag: Set reference values in destination file to zero (0).H5O_COPY_WITHOUT_ATTR_FLAGCopy object without copying attributes.
Default behavior, without flag: Copy object with all its attributes.H5O_COPY_MERGE_COMMITTED_DTYPE_FLAGUse a matching committed datatype in the destination file when copying a committed datatype, a dataset with a committed datatype, or an object with an attribute of committed datatype.
Default behavior without flag:See the “See Also” section immediately below for functions related to the use of this flag.
- Parameters:
hid_t ocpypl_idIN: Object copy property list identifier unsigned copy_optionsIN: Copy option(s) to be set - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- See Also:
H5Ocopy
Copying Committed Datatypes
withH5Ocopy
A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5
H5Padd_merge_committed_dtype_path
H5Pfree_merge_committed_dtype_paths
H5Pset_mcdt_search_cb
H5Pget_mcdt_search_cb
H5O_mcdt_search_cb_t
Functions and a callback function used to tune committed datatype copying behavior- Fortran90 Interface: h5pset_copy_object_f
SUBROUTINE h5pset_copy_object_f(ocpypl_id, copy_options, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: ocpypl_id ! Object copy property list identifier INTEGER, INTENT(IN) :: copy_options ! Copy option(s) to be set, valid options are: ! H5O_COPY_SHALLOW_HIERARCHY_F ! H5O_COPY_EXPAND_SOFT_LINK_F ! H5O_COPY_EXPAND_EXT_LINK_F ! H5O_COPY_EXPAND_REFERENCE_F ! H5O_COPY_WITHOUT_ATTR_FLAG_F ! H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG_FINTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_copy_object_f- History:
Release C 1.8.0 Function introduced in this release. 1.8.9 H5O_COPY_MERGE_COMMITTED_DTYPE_FLAGadded in this release.
- Last modified: 13 August 2014
- Name: H5Pset_core_write_tracking
- Signature:
herr_t H5Pset_core_write_tracking( hid_t fapl_id, hbool_t is_enabled, size_t page_size )- Purpose:
- Sets write tracking information for core driver,
H5FD_CORE. - Description:
-
When a file is created or opened for writing using the
core virtual file driver (VFD) with the backing store option turned on,
the core driver can be configured to track changes to the file
and write out only the modified bytes.
This write tracking feature is enabled and disabled with
is_enabled. The default setting is that write tracking is disabled, or off.To avoid a large number of small writes, changes can be aggregated into pages of a user-specified size,
page_size.Setting
page_sizeto1enables tracking with no page aggregation.The backing store option is set via the function
H5Pset_fapl_core. - Notes:
-
This function is only for use with the core VFD and must be used
after the call to
H5Pset_fapl_core. It is an error to use this function with any other VFD.It is an error to use this function when the backing store flag has not been set using
H5Pset_fapl_core.This function only applies to the backing store write operation which typically occurs when the file is flushed or closed. This function has no relationship to the
incrementparameter passed toH5Pset_fapl_core.For optimum performance, the
page_sizeparameter should be a power of two.It is an error to set the page size to 0.
- Parameters:
-
hid_t fapl_idIN: File access property list identifier. hbool_t is_enabledIN: Boolean value specifying whether feature is enabled. size_t page_sizeIN: Positive integer specifying size, in bytes, of write aggregation pages.
Value of1(one) enables tracking with no paging. - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Fortran Interface:
- None
- See Also:
-
H5Pget_core_write_tracking - History:
Release Change 1.8.13 C function introduced with this release. 1.8.14 C function modified in this release to return error if page_sizeis set to0(zero).
- Last modified: 11 May 2011
- Name: H5Pset_create_intermediate_group
- Signature:
- Name: H5Pset_create_intermediate_group
- herr_t
H5Pset_create_intermediate_group( hid_tlcpl_id, unsignedcrt_intermed_group) - Purpose:
- Specifies in property list whether to create missing intermediate
groups.
- Description:
H5Pset_create_intermediate_groupspecifies whether to set the link creation property listlcpl_idso that calls to functions that create objects in groups different from the current working group will create intermediate groups that may be missing in the path of a new or moved object.Functions that create objects in or move objects to a group other than the current working group make use of this property.
H5Gcreate_anonandH5Lmoveare examples of such functions.If
crt_intermed_groupis positive, theH5G_CRT_INTMD_GROUPwill be added tolcpl_id(if it is not already there). Missing intermediate groups will be created upon calls to functions such as those listed above that uselcpl_id.If
crt_intermed_groupis non-positive, theH5G_CRT_INTMD_GROUP, if present, will be removed fromlcpl_id. Missing intermediate groups will not be created upon calls to functions such as those listed above that uselcpl_id.- Parameters:
hid_t lcpl_idIN: Link creation property list identifier unsigned crt_intermed_groupIN: Flag specifying whether to create intermediate groups upon the creation of an object - Returns:
- Returns a non-negative valule if successful;
otherwise returns a negative value.
- Example:
- The following call sets the link creation property list
lcpl_idsuch that a call toH5Gcreate_anonor other function usinglcpl_idwill create any missing groups in the path to the new object:herr_t ret_value = H5Pset_create_intermediate_group(lcpl_id, 1) - Fortran90 Interface:
h5pset_create_inter_group_f -
SUBROUTINE h5pset_create_inter_group_f(lcpl_id, crt_intermed_group, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: lcpl_id ! Link creation property list identifier INTEGER, INTENT(IN) :: crt_intermed_group ! Specifying whether to create intermediate groups ! upon the creation of an object INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_create_inter_group_f - History:
Release C 1.8.0 Function introduced in this release.
- Name: H5Pset_data_transform
- Signature:
- herr_t
H5Pset_data_transform(hid_tplist_id, const char *expression) - Purpose:
- Sets a data transform expression.
- Description:
H5Pset_data_transformsets the data transform to be used for reading and writing data. This function operates on the dataset transfer property lists plist_id.The expression parameter is a string containing an algebraic expression, such as
(5/9.0)*(x-32)orx*(x-5). When a dataset is read or written with this property list, the transform expression is applied with thexbeing replaced by the values in the dataset. When reading data, the values in the file are not changed and the transformed data is returned to the user.Data transforms can only be applied to integer or floating-point datasets. Order of operations is obeyed and the only supported operations are +, -, *, and /. Parentheses can be nested arbitrarily and can be used to change precedence.
When writing data back to the dataset, the transformed data is written to the file and there is no way to recover the original values to which the transform was applied.
- Parameters:
hid_t plist_idIN: Identifier of the property list or class const char * expressionIN: Pointer to the null-terminated data transform expression - Returns:
- Success: a non-negative value
- Failure: a negative value
- Fortran90 Interface: SUBROUTINE h5pset_data_transform_f
SUBROUTINE h5pset_data_transform_f(plist_id, expression, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plist_id ! Identifier of the property list or class CHARACTER(LEN=*), INTENT(IN) :: expression ! Buffer to hold transform expression INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_data_transform_f- History:
Release C 1.8.0 Function introduced in this release.
- Last modified: 20 June 2013
- Name: H5Pset_deflate
- Signature:
- Name: H5Pset_deflate
- herr_t
H5Pset_deflate( hid_tplist_id, uintlevel) - Purpose:
- Sets deflate (GNU gzip) compression method and compression level.
- Description:
H5Pset_deflatesets the deflate compression method and the compression level,levelfor a dataset or group creation property list,plist_id.The filter identifier set in the propertly list is
H5Z_FILTER_DEFLATE.The compression level,
level, is a value from zero to nine, inclusive. A compression level of0(zero) indicates no compression; compression improves but speed slows progressively from levels 1 through 9:Compression level Gzip action 0No compression 1Best compression speed; least compression 2through8Compression improves; speed degrades 9Best compression ratio; slowest speed Note that setting the compression level to
0(zero) does not turn off use of the gzip filter; it simply sets the filter to perform no compression as it processes the data.HDF5 relies on GNU gzip for this compression (see
zlib).- Parameters:
hid_t plist_idIN: Dataset or group creation property list identifier. uint levelIN: Compression level. - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_deflate_f
SUBROUTINE h5pset_deflate_f(prp_id, level, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(IN) :: level ! Compression level INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_deflate_f- History:
Release Change 1.8.5 Function extended to work with group creation property lists.
- Name: H5Pset_driver
- Signature:
- herr_t
H5Pset_driver( hid_tplist_id, hid_tnew_driver_id, const void *new_driver_info) - Purpose:
- Sets a file driver.
- Description:
H5Pset_driversets the file driver,new_driver_id, for a file access or data transfer property list,plist_id, and supplies an optional struct containing the driver-specific properties,new_driver_info.The driver properties will be copied into the property list and the reference count on the driver will be incremented, allowing the caller to close the driver identifier but still use the property list.
- Note:
H5Pset_driverandH5Pget_driver_infoare used only when creating a virtual file driver (VFD) in the virtual file layer (VFL). For further information, see “Virtual File Layer” and “List of VFL Functions” in the HDF5 Technical Notes.- Parameters:
- hid_t
plist_id - IN: File access or data transfer property list identifier.
- hid_t
new_driver_id - IN: Driver identifier.
- const void *
new_driver_info - IN: Optional struct containing driver properties.
- hid_t
- Returns:
- Returns a non-negative value if successful.
Otherwise returns a negative value.
- Fortran90 Interface:
- None.
- History:
Release C 1.8.2 Function publicized in this release; previous releases described this function only in the virtual file driver documentation.
- Name: H5Pset_dxpl_mpio
- Signature:
- herr_t
H5Pset_dxpl_mpio( hid_tdxpl_id, H5FD_mpio_xfer_txfer_mode) - Purpose:
- Sets data transfer mode.
- Description:
H5Pset_dxpl_mpiosets the data transfer property listdxpl_idto use transfer modexfer_mode. The property list can then be used to control the I/O transfer mode during data I/O operations.Valid transfer modes are as follows:
H5FD_MPIO_INDEPENDENT- Use independent I/O access (default).
H5FD_MPIO_COLLECTIVE- Use collective I/O access.
- Parameters:
hid_t dxpl_idIN: Data transfer property list identifier. H5FD_mpio_xfer_t xfer_modeIN: Transfer mode. - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Fortran90 Interface:
-
SUBROUTINE h5pset_dxpl_mpio_f(prp_id, data_xfer_mode, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(IN) :: data_xfer_mode ! Data transfer mode ! Possible values are: ! H5FD_MPIO_INDEPENDENT_F ! H5FD_MPIO_COLLECTIVE_F INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_dxpl_mpio_f - History:
Release C 1.4.0 Function introduced in this release.
- Name:
H5Pset_dxpl_mpio_chunk_opt
- Signature:
- herr_t
H5Pset_dxpl_mpio_chunk_opt(hid_tdxpl_id, H5FD_mpio_chunk_opt_topt_mode) - Purpose:
- Sets a flag specifying linked-chunk I/O or multi-chunk I/O.
- Description:
H5Pset_dxpl_mpio_chunk_optspecifies whether I/O is to be performed as linked-chunk I/O or as multi-chunk I/O. This function overrides the HDF5 Library's internal algorithm for determining which mechanism to use.When an application uses collective I/O with chunked storage, the HDF5 Library normally uses an internal algorithm to determine whether that I/O activity should be conducted as one linked-chunk I/O or as multi-chunk I/O.
H5Pset_dxpl_mpio_chunk_optis provided so that an application can override the library's alogorithm in circumstances where the library might lack the information needed to make an optimal desision.H5Pset_dxpl_mpio_chunk_optworks by setting one of the following flags in the parameteropt_mode:H5FD_MPIO_CHUNK_ONE_IODo one link chunked I/O. H5FD_MPIO_CHUNK_MULTI_IODo multi-chunked I/O. dxpl_id.The library perform I/O in the specified manner unless it determines that the low-level MPI IO package does not support the requested behavior; in such cases, the HDF5 Library will internally use independent I/O.
Use of this function is optional.
- Parameters:
hid_t dxpl_idIN: Data transfer property list identifier H5FD_mpio_chunk_opt_t opt_modeIN: Optimization flag specifying linked-chunk I/O or multi-chunk I/O - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Name:
H5Pset_dxpl_mpio_chunk_opt_num
- Signature:
- herr_t
H5Pset_dxpl_mpio_chunk_opt_num(hid_tdxpl_id, unsignednum_chunk_per_proc) - Purpose:
- Sets a numeric threshold for linked-chunk I/O.
- Description:
H5Pset_dxpl_mpio_chunk_opt_numsets a numeric threshold for the use of linked-chunk I/O.The library will calculate the average number of chunks selected by each process when doing collective access with chunked storage. If the number is greater than the threshold set in
num_chunk_per_proc, the library will use linked-chunk I/O; otherwise, a separate I/O process will be invoked for each chunk (multi-chunk I/O).- Parameters:
hid_t dxpl_idIN: Data transfer property list identifier unsigned num_proc_per_chunkIN: Numeric threshold for performing linked-chunk I/O - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Name:
H5Pset_dxpl_mpio_chunk_opt_ratio
- Signature:
- herr_t
H5Pset_dxpl_mpio_chunk_opt_ratio(hid_tdxpl_id, unsignedpercent_proc_per_chunk) - Purpose:
- Sets a ratio threshold for collective I/O.
- Description:
H5Pset_dxpl_mpio_chunk_opt_ratiosets a threshold for the use of collective I/O based on the ratio of processes with collective access to a dataset with chunked storage. The decision whether to use collective I/O is made on a per-chunk basis.The library will calculate the percentage of the total number of processes, the ratio, that hold selections in each chunk. If that percentage is greater than the threshold set in
percent_proc_per_chunk, the library will do collective I/O for this chunk; otherwise, independent I/O will be done for the chunk.- Parameters:
hid_t dxpl_idIN: Data transfer property list identifier unsigned percent_proc_per_chunkIN: Percent threshold, on the number of processes holding selections per chunk, for performing linked-chunk I/O - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Name:
H5Pset_dxpl_mpio_collective_opt
- Signature:
- herr_t
H5Pset_dxpl_mpio_collective_opt(hid_tdxpl_id, H5FD_mpio_collective_opt_topt_mode) - Purpose:
- Sets a flag governing the use of independent versus collective I/O.
- Description:
H5Pset_dxpl_mpio_collective_optenables an application to specify that the HDF5 Library will use independent I/O internally when the dataset transfer property listdxpl_idis set for collective I/O, i.e., withH5FD_MPIO_COLLECTIVEspecified. This allows the application greater control over low-level I/O while maintaining the collective interface at the application level.H5Pset_dxpl_mpio_collective_optworks by setting one of the following flags in the parameteropt_mode:H5FD_MPIO_COLLECTIVE_IOUse collective I/O. (Default) H5FD_MPIO_INDIVIDUAL_IOUse independent I/O. This function should be used only when
H5FD_MPIO_COLLECTIVEhas been set throughH5Pset_dxpl_mpio. In such situations, normal behavior would be to use low-level collective I/O functions, but the library will use low-level MPI independent I/O functions whenH5FD_MPIO_INDIVIDUAL_IOis set.Use of this function is optional.
- Parameters:
hid_t dxpl_idIN: Data transfer property list identifier H5FD_mpio_collective_opt_t opt_modeIN: Optimization flag specifying the use of independent or collective I/O - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Last modified: 20 May 2010
- Name: H5Pset_edc_check
- Signature:
- Name: H5Pset_edc_check
- herr_t
H5Pset_edc_check( hid_tplist, H5Z_EDC_tcheck) - Purpose:
- Sets whether to enable error-detection when reading a dataset.
- Description:
H5Pset_edc_checksets the dataset transfer property listplistto enable or disable error detection when reading data.Whether error detection is enabled or disabled is specified in the
checkparameter. Valid values are as follows:H5Z_ENABLE_EDC(default)
H5Z_DISABLE_EDCThe error detection algorithm used is the algorithm previously specified in the corresponding dataset creation property list.
This function does not affect the use of error detection when writing data.
- Note:
- The initial error detection implementation, Fletcher32 checksum,
supports error detection for chunked datasets only.
- Note:
- The Fletcher32 EDC checksum filter, set with
H5Pset_fletcher32, was added in HDF5 Release 1.6.0. In the original implementation, however, the checksum value was calculated incorrectly on little-endian systems. The error was fixed in HDF5 Release 1.6.3.As a result of this fix, an HDF5 Library of Release 1.6.0 through Release 1.6.2 cannot read a dataset created or written with Release 1.6.3 or later if the dataset was created with the checksum filter and the filter is enabled in the reading library. (Libraries of Release 1.6.3 and later understand the earlier error and comensate appropriately.)
Work-around: An HDF5 Library of Release 1.6.2 or earlier will be able to read a dataset created or written with the checksum filter by an HDF5 Library of Release 1.6.3 or later if the checksum filter is disabled for the read operation. This can be accomplished via an
H5Pset_edc_checkcall with the valueH5Z_DISABLE_EDCin the second parameter. This has the obvious drawback that the application will be unable to verify the checksum, but the data does remain accessible. - Parameters:
hid_t plistIN: Dataset transfer property list identifier. H5Z_EDC_t checkIN: Specifies whether error checking is enabled or disabled for dataset read operations. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_edc_check_f
-
SUBROUTINE h5pset_edc_check_f(prp_id, flag, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset transfer property ! list identifier INTEGER, INTENT(IN) :: flag ! EDC flag; possible values ! H5Z_DISABLE_EDC_F ! H5Z_ENABLE_EDC_F INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_edc_check_f - History:
Release Change 1.6.0 Function introduced in this release. 1.6.3 Error in checksum calculation on little-endian systems corrected in this release.
- Last modified: 26 April 2016
- Name: H5Pset_efile_prefix
- Signature:
herr_t H5Pset_efile_prefix( hid_t dapl_id, const char *prefix )- Purpose:
- Sets the external dataset storage file prefix in the dataset access property list.
- Description:
H5Pset_efile_prefixsets the prefix used to locate raw data files for a dataset that uses external storage. This prefix can provide either an absolute path or a relative path to the external files.H5Pset_efile_prefixis used in conjunction withH5Pset_externalto control the behavior of the HDF5 Library when searching for the raw data files associated with a dataset that uses external storage:- The default behavior of the library is to search for the dataset’s external storage raw data files in the same directory as the HDF5 file which contains the dataset.
- If the prefix is set to an absolute path, the target directory will be searched for the dataset’s external storage raw data files.
- If the prefix is set to a relative path, the target directory, relative to the current working directory, will be searched for the dataset’s external storage raw data files.
- If the prefix is set to a relative path that begins with
the special token
${ORIGIN}, that directory, relative to the HDF5 file containing the dataset, will be searched for the dataset’s external storage raw data files.
The
HDF5_EXTFILE_PREFIXenvironment variable can be used to override the above behavior (the environment variable supersedes the API call). Setting the variable to a path string and callingH5DcreateorH5Dopenis the equivalent of callingH5Pset_efile_prefixand calling the same create or open function. The environment variable is checked at the time of the create or open action and copied so it can be safely changed after theH5DcreateorH5Dopencall.Calling
H5Pset_efile_prefixwithprefixset toNULLor the empty string returns the search path to the default. The result would be the same as ifH5Pset_efile_prefixhad never been called.- Notes:
- If the external file prefix is not an absolute path and the
HDF5 file is moved, the external storage files will also need to
be moved so they can be accessed at the new location.
As stated above, the use of the
HDF5_EXTFILE_PREFIXenvironment variable overrides any property list setting.H5Pset_efile_prefixandH5Pget_efile_prefix, being property functions, set and retrieve only the property list setting; they are unaware of the environment variable.On Windows, the prefix must be an ASCII string since the Windows standard C library’s I/O functions cannot handle UTF-8 file names.
- Parameters:
hid_t dapl_idIN: Dataset access property list identifier const char *prefixIN: Dataset external storage prefix in UTF-8 or ASCII
(Path and filename must be ASCII on Windows systems.)- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran Interface:
- None
- See Also:
- History:
-
Release Change 1.10.0 and 1.8.17 C function introduced in these releases.
- Last modified: 8 May 2009
- Name: H5Pset_elink_acc_flags
- Signature:
- Name: H5Pset_elink_acc_flags
- herr_t
H5Pset_elink_acc_flags( hid_tlapl_id, unsignedflags) - Purpose:
- Sets the external link traversal file access flag in a link access
property list.
- Motivation:
H5Pset_elink_acc_flagsis used to adjust the file access flag used to open files reached through external links. This may be useful to, for example, prevent modifying files accessed through an external link. Otherwise, the target file is opened with whatever flag was used to open the parent.- Description:
H5Pset_elink_acc_flagsspecifies the file access flag to use to open the target file of an external link. This allows read-only access of files reached through an external link in a file opened with write access, or vice-versa.The library will normally use the file access flag used to open the parent file as the file access flag for the target file. This function provides a way to override that behaviour. The external link traversal callback function set by
H5Pset_elink_cbcan override the setting fromH5Pset_elink_acc_flags.- Parameters:
-
hid_t lapl_idIN: Link access property list identifier unsigned flagsIN: The access flag for external link traversal. Valid values include:
H5F_ACC_RDWRCauses files opened through external links to be opened with write access. H5F_ACC_RDONLYCauses files opened through external links to be opened with read-only access. H5F_ACC_DEFAULTRemoves any external link file access flag setting from lapl_id, causing the file access flag setting to be taken from the parent file. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Example Usage:
- The following code sets the link access property list
lapl_idto open external link target files with read-only access:status = H5Pset_elink_acc_flags(lapl_id, H5F_ACC_RDONLY);
- See Also:
-
H5Pget_elink_acc_flags,H5Pset_elink_cb,H5Fopen,H5Lcreate_external - History:
Release Change 1.8.3 C function introduced in this release.
- Last modified: 18 June 2013
- Name: H5Pset_elink_cb
- Signature:
- Name: H5Pset_elink_cb
- herr_t
H5Pset_elink_cb( hid_tlapl_id, H5L_elink_traverse_tfunc, void *op_data) - Purpose:
- Sets the external link traversal callback function in a
link access property list.
- Motivation:
H5Pset_elink_cbis used to specify a callback function that is executed by the HDF5 Library when traversing an external link. This provides a mechanism to set specific access permissions, modify the file access property list, modify the parent or target file, or take any other user-defined action. This callback function is used in situations where the HDF5 Library's default behavior is not suitable.- Description:
H5Pset_elink_cbsets a user-defined external link traversal callback function in the link access property listlapl_id. The callback functionfuncmust conform to the prototype specified inH5L_elink_traverse_t.The callback function may adjust the file access property list and file access flags to use when opening a file through an external link. The callback will be executed by the HDF5 Library immediately before opening the target file.
The callback will be made after the file access property list set by
H5Pset_elink_fapland the file access flag set byH5Pset_elink_acc_flagsare applied, so changes made by this callback function will take precedence.- Programming Note for C++ Developers Using C Functions:
-
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cbandH5Pset_type_conv_cband functions such asH5TconvertandH5Ewalk2.Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
- Note:
- A file close degree property setting
(
H5Pset_fclose_degree) in this callback function or an associated property list will be ignored. A file opened by means of traversing an external link is always opened with the weak file close degree property setting,H5F_CLOSE_WEAK. - Parameters:
-
hid_t lapl_idIN: Link access property list identifier. H5L_elink_traverse_t funcIN: User-defined external link traversal callback function. void * op_dataIN: User-defined input data for the callback function. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Failure Modes:
H5Pset_elink_cbwill fail if the link access property list identifier,lapl_id, is invalid or if the function pointer,func, isNULL.An invalid function pointer,
func, will cause a segmentation fault or other failure when an attempt is subsequently made to traverse an external link.- Example Usage:
- This example defines a callback function that prints the name of the
target file every time an external link is followed, and sets this
callback function on
lapl_idherr_t elink_callback(const char *parent_file_name, const char *parent_group_name, const char *child_file_name, const char *child_object_name, unsigned *acc_flags, hid_t fapl_id, void *op_data) { puts(child_file_name); return 0; } int main(void) { hid_t lapl_id = H5Pcreate(H5P_LINK_ACCESS); H5Pset_elink_cb(lapl_id, elink_callback, NULL); ... } - See Also:
-
H5Pget_elink_cbH5Pset_elink_fapl,H5Pset_elink_acc_flags,H5Lcreate_externalH5Fopenfor discussion ofH5F_ACC_RDWRandH5F_ACC_RDONLYfile access flags - History:
Release Change 1.8.3 C function introduced in this release.
- Last modified: 18 June 2013
- Name: H5Pset_elink_fapl
- Signature:
- Name: H5Pset_elink_fapl
- herr_t
H5Pset_elink_fapl( hid_tlapl_id, hid_tfapl_id) - Purpose:
- Sets a file access property list for use in accessing a file pointed
to by an external link.
- Description:
H5Pset_elink_faplsets the file access property list,fapl_id, to be used when accessing the target file of an external link associated withlapl_id.- Note:
- A file close degree property setting
(
H5Pset_fclose_degree) in this property list will be ignored. A file opened by means of traversing an external link is always opened with the weak file close degree property setting,H5F_CLOSE_WEAK. - Parameters:
-
hid_t lapl_idIN: Link access property list identifier hid_t fapl_idIN: File access property list identifier - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- See Also:
H5Pget_elink_fapl
H5Lcreate_external- Fortran90 Interface:
-
None.
- History:
Release Change 1.9.0 C function introduced in this release.
- Last modified: 11 May 2011
- Name: H5Pset_elink_file_cache_size
- Signature:
- Name: H5Pset_elink_file_cache_size
- herr_t
H5Pset_elink_file_cache_size( hid_tfapl_id, unsignedefc_size) - Purpose:
- Sets the number of files that can be held open in an
external link open file cache.
- Motivation:
- The external link open file cache holds files open after
they have been accessed via an external link.
This cache reduces the number of times such files are opened
when external links are accessed repeatedly and can siginificantly
improves performance in certain heavy-use situations and
when low-level file opens or closes are expensive.
H5Pset_elink_file_cache_sizesets the number of files that will be held open in an external link open file cache;H5Pget_elink_file_cache_sizeretrieves the size of an existing cache; andH5Fclear_elink_file_cacheclears an existing cache without closing it. - Description:
H5Pset_elink_file_cache_sizespecifies the number of files that will be held open in an external link open file cache.The default external link open file cache size is 0 (zero), meaning that files accessed via an external link are not held open. Setting the cache size to a positive integer turns on the cache; setting the size back to zero turns it off.
With this property set, files are placed in the external link open file cache cache when they are opened via an external link. Files are then held open until either they are evicted from the cache or the parent file is closed. This property setting can improve performance when external links are repeatedly accessed.
When the cache is full, files will be evicted using a least recently used (LRU) scheme; the file which has gone the longest time without being accessed through the parent file will be evicted and closed if nothing else is holding that file open.
Files opened through external links inherit the parent file’s file access property list by default, and therefore inherit the parent file’s external link open file cache setting.
When child files contain external links of their own, the caches can form a graph of cached external files. Closing the last external reference to such a graph will recursively close all files in the graph, even if cycles are present.
- Parameters:
-
hid_t fapl_idIN: File access property list identifier unsigned efc_sizeIN: External link open file cache size in number of files.
Default setting is0(zero). - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Example Usage:
- The following code sets up an external link open file cache that
will hold open up to 8 files reached through external links:
status = H5Pset_elink_file_cache_size(fapl_id, 8); - See Also:
-
H5Pget_elink_file_cache_size
H5Fclear_elink_file_cacheH5Lcreate_external
H5Pset_elink_fapl - History:
Release Change 1.8.7 C function introduced in this release.
- Name: H5Pset_elink_prefix
- Signature:
- herr_t
H5Pset_elink_prefix( hid_tlapl_id, const char *prefix) - Purpose:
- Sets prefix to be applied to external link paths.
- Description:
H5Pset_elink_prefixsets the prefix to be applied to the path of any external links traversed. The prefix is prepended to the filename stored in the external link.The prefix is specified in the user-allocated buffer
prefixand set in the link access property listlapl_id. The buffer should not be freed until the property list has been closed.- Parameters:
hid_t lapl_idIN: Link access property list identifier const char * prefixIN: Prefix to be applied to external link paths - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface:
- None.
- History:
Release C 1.8.0 Function introduced in this release.
- Name: H5Pset_est_link_info
- Signature:
- herr_t
H5Pset_est_link_info( hid_tgcpl_id, unsignedest_num_entries, unsignedest_name_len) - Purpose:
- Sets estimated number of links and length of link names in a group.
- Description:
H5Pset_est_link_infoinserts two settings into the group creation property listgcpl_id: the estimated number of links that are expected to be inserted into a group created with the property list and the estimated average length of those link names.The estimated number of links is passed in
est_num_entries.The estimated average length of the anticipated link names is passed in
est_name_len.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.
If a group is expected to have many links and to be stored in dense format, set
est_num_entriesto0(zero) for maximum efficiency. This will prevent the group from being created in the compact format.See “Group implementations in HDF5” in the H5G API introduction for a discussion of the available types of HDF5 group structures.
- Parameters:
hid_t gcpl_idIN: Group creation property list identifier unsigned est_num_entriesIN: Estimated number of links to be inserted into group unsigned est_name_lenIN: Estimated average length of link names - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface:
SUBROUTINE H5Pset_est_link_info_f(gcpl_id, est_num_entries, est_name_len, & hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list identifier INTEGER, INTENT(IN) :: est_num_entries ! Estimated number of links to be ! inserted into group INTEGER, INTENT(IN) :: est_name_len ! Estimated average length of link names INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE H5Pset_est_link_info_f- History:
Release C 1.8.0 Function introduced in this release.
- Last modified: 22 April 2011
- Name: H5Pset_external
- Signature:
- Name: H5Pset_external
- herr_t
H5Pset_external(hid_tplist, const char*name, off_toffset, hsize_tsize) - Purpose:
- Adds an external file to the list of external files.
- Description:
- The first call to
H5Pset_externalsets the external storage property in the property list, thus designating that the dataset will be stored in one or more non-HDF5 file(s) external to the HDF5 file. This call also adds the filenameas the first file in the list of external files. Subsequent calls to the function add the named file as the next file in the list.If a dataset is split across multiple files, then the files should be defined in order. The total size of the dataset is the sum of the
sizearguments for all the external files. If the total size is larger than the size of a dataset then the dataset can be extended (provided the data space also allows the extending).The
sizeargument specifies the number of bytes reserved for data in the external file. Ifsizeis set toH5F_UNLIMITED, the external file can be of unlimited size and no more files can be added to the external files list. Ifsizeis set to0(zero), no external file will actually be created.All of the external files for a given dataset must be specified with
H5Pset_externalbeforeH5Dcreateis called to create the dataset. If one these files does not exist on the system whenH5Dwriteis called to write data to it, the library will create the file. - Parameters:
hid_t plistIN: Identifier of a dataset creation property list. const char *nameIN: Name of an external file. off_t offsetIN: Offset, in bytes, from the beginning of the file to the location in the file where the data starts. hsize_t sizeIN: Number of bytes reserved in the file for the data. - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_external_f
-
SUBROUTINE h5pset_external_f(prp_id, name, offset,bytes, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier CHARACTER(LEN=*), INTENT(IN) :: name ! Name of an external file INTEGER, INTENT(IN) :: offset ! Offset, in bytes, from the ! beginning of the file to the ! location in the file where ! the data starts INTEGER(HSIZE_T), INTENT(IN) :: bytes ! Number of bytes reserved in ! the file for the data INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_external_f
- Name: H5Pset_family_offset
- Signature:
- herr_t
H5Pset_family_offset( hid_tfapl_id, hsize_toffset) - Purpose:
- Sets offset property for low-level access to a file in a family of files.
- Description:
H5Pset_family_offsetsets the offset property in the file access property listfapl_idso 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 toH5Fget_vfd_handle(or, in special circumstances, toH5FDget_vfd_handle; see Virtual File Layer and List of VFL Functions in HDF5 Technical Notes).The value of
offsetis an offset in bytes from the beginning of the HDF5 file, identifying a user-determined location within the HDF5 file. The file handle the user application is seeking is for the specific member-file in the associated family of files to which this offset is mapped.Use of this function is only appropriate for an HDF5 file written as a family of files with the
FAMILYfile driver.- Parameters:
hid_t fapl_idIN: File access property list identifier. hsize_t offsetIN: Offset in bytes within the HDF5 file. - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_family_offset_f
-
SUBROUTINE h5pset_family_offset_f(prp_id, offset, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER(HSIZE_T), INTENT(IN) :: offset ! Offset in bytes INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_family_offset_f - History:
Release C 1.6.0 Function introduced in this release.
- Name: H5Pset_fapl_core
- Signature:
- herr_t
H5Pset_fapl_core( hid_tfapl_id, size_tincrement, hbool_tbacking_store) - Purpose:
- Modifies the file access property list to use the
H5FD_COREdriver. - Description:
H5Pset_fapl_coremodifies the file access property list to use theH5FD_COREdriver.The
H5FD_COREdriver enables an application to work with a file in memory, speeding reads and writes as no disk access is made. File contents are stored only in memory until the file is closed. Thebacking_storeparameter determines whether file contents are ever written to disk.incrementspecifies the increment by which allocated memory is to be increased each time more memory is required.While using
H5Fcreateto create a core file, if thebacking_storeis set to1(TRUE), the file contents are flushed to a file with the same name as this core file when the file is closed or access to the file is terminated in memory.The application is allowed to open an existing file with
H5FD_COREdriver. While usingH5Fopento open an existing file, if thebacking_storeis set to1and theflagsforH5Fopenis set toH5F_ACC_RDWR, any change to the file contents are saved to the file when the file is closed. Ifbacking_storeis set to0and theflagsforH5Fopenis set toH5F_ACC_RDWR, any change to the file contents will be lost when the file is closed. If theflagsforH5Fopenis set toH5F_ACC_RDONLY, no change to the file is allowed either in memory or on file.- Note:
- Currently this driver cannot create or open family or multi files.
- Parameters:
hid_t fapl_idIN: File access property list identifier. size_t incrementIN: Size, in bytes, of memory increments. hbool_t backing_storeIN: Boolean flag indicating whether to write the file contents to disk when the file is closed. - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Fortran90 Interface: h5pset_fapl_core_f
-
SUBROUTINE h5pset_fapl_core_f(prp_id, increment, backing_store, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER(SIZE_T), INTENT(IN) :: increment ! File block size in bytes LOGICAL, INTENT(IN) :: backing_store ! Flag to indicate that entire ! file contents are flushed to ! a file with the same name as ! this core file INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_fapl_core_f - History:
Release C Fortran90 1.6.0 The backing_storeparameter has changed from INTEGER to LOGICAL to better match the C API.1.4.0 Function introduced in this release.
- Name: H5Pset_fapl_direct
- Signature:
- herr_t
H5Pset_fapl_direct( hid_tfapl_id, size_talignment, size_tblock_size, size_tcbuf_size) - Purpose:
- Sets up use of the direct I/O driver.
- Description:
H5Pset_fapl_directsets the file access property list,fapl_id, to use the direct I/O driver,H5FD_DIRECT. With this driver, data is written to or read from the file synchronously without being cached by the system.File systems usually require the data address in memory, the file address, and the size of the data to be aligned. The HDF5 Library’s direct I/O driver is able to handle unaligned data, though that will consume some additional memory resources and may slow performance. To get better performance, use the system function
posix_memalignto align the data buffer in memory and the HDF5 functionH5Pset_alignmentto align the data in the file. Be aware, however, that aligned data I/O may cause the HDF5 file to be bigger than the actual data size would otherwise require because the alignment may leave some holes in the file.alignmentspecifies the required alignment boundary in memory.block_sizespecifies the file system block size. A value of0(zero) means to use HDF5 Library’s default value of 4KB.cbuf_sizespecifies the copy buffer size.- Note:
- On an SGI Altix Linux 2.6 system, the memory alignment must be
a multiple of 512 bytes, and the file system block size is 4KB.
The maximum size for the copy buffer has to be a multiple of
the file system block size. The HDF5 Library’s
default maximum copy buffer size is 16MB. This copy buffer
is used by the library’s internal algorithm to copy data
in fragments between an application’s unaligned buffer
and the file. The buffer’s size may affect I/O performance.
- Parameters:
hid_t fapl_idIN: File access property list identifier size_t alignmentIN: Required memory alignment boundary size_t block_sizeIN: File system block size size_t cbuf_sizeIN: Copy buffer size - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_fapl_direct_f
SUBROUTINE h5pset_fapl_direct_f(fapl_id, alignment, block_size, cbuf_size, & hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier INTEGER(SIZE_T), INTENT(IN) :: alignment ! Required memory alignment boundary INTEGER(SIZE_T), INTENT(IN) :: block_size ! File system block sizeINTEGER(SIZE_T), INTENT(IN) :: cbuf_size ! Copy buffer size INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE H5Pset_fapl_direct_f- History:
Release C 1.8.0 Function introduced in this release.
- Name: H5Pset_fapl_family
- Signature:
- herr_t
H5Pset_fapl_family( hid_tfapl_id, hsize_tmemb_size, hid_tmemb_fapl_id) - Purpose:
- Sets the file access property list to use the family driver.
- Description:
H5Pset_fapl_familysets the file access property list identifier,fapl_id, to use the family driver.memb_sizeis the size in bytes of each file member. This size will be saved in file when the property listfapl_idis used to create a new file. Iffapl_idis used to open an existing file,memb_sizehas to be equal to the original size saved in file. A failure with an error message indicating the correct member size will be returned ifmemb_sizedoes not match the size saved. If any user does not know the original size,H5F_FAMILY_DEFAULTcan be passed in. The library will retrieve the saved size.memb_fapl_idis the identifier of the file access property list to be used for each family member.- Parameters:
hid_t fapl_idIN: File access property list identifier. hsize_t memb_sizeIN: Size in bytes of each file member. hid_t memb_fapl_idIN: Identifier of file access property list for each family member. - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_fapl_family_f
-
SUBROUTINE h5pset_fapl_family_f(prp_id, imemb_size, memb_plist, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER(HSIZE_T), INTENT(IN) :: memb_size ! Logical size, in bytes, ! of each family member INTEGER(HID_T), INTENT(IN) :: memb_plist ! Identifier of the file ! access property list to be ! used for each family member INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_fapl_family_f - History:
Release C 1.4.0 Function introduced in this release. 1.8.0 Behavior of the memb_sizeparameter was changed.
- Last modified: 12 May 2011
- Name: H5Pset_fapl_log
- Signature:
- Name: H5Pset_fapl_log
- herr_t
H5Pset_fapl_log( hid_tfapl_id, const char *logfile, unsigned long longflags, size_tbuf_size) - Purpose:
- Sets up the logging virtual file driver (
H5FD_LOG) for use. - Description:
H5Pset_fapl_logmodifies the file access property list to use the logging driver,H5FD_LOG. The logging virtual file driver (VFD) is a clone of the standard SEC2 (H5FD_SEC2) driver with additional facilities for logging VFD metrics and activity to a file.logfileis the name of the file in which the logging entries are to be recorded.The actions to be logged are specified in the parameter
flagsusing the pre-defined constants described in the following table. Multiple flags can be set through the use of a logical OR contained in parentheses. For example, logging read and write locations would be specified as(H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE).
Table 1: Logging flags
Flag Description H5FD_LOG_LOC_READTrack the location and length of every read, write, or seek operation. H5FD_LOG_LOC_WRITEH5FD_LOG_LOC_SEEKH5FD_LOG_LOC_IOTrack all I/O locations and lengths. The logical equivalent of the following: (H5FD_LOG_LOC_READ | H5FD_LOG_LOC_WRITE | H5FD_LOG_LOC_SEEK)H5FD_LOG_FILE_READTrack the number of times each byte is read or written. H5FD_LOG_FILE_WRITEH5FD_LOG_FILE_IOTrack the number of times each byte is read and written. The logical equivalent of the following: (H5FD_LOG_FILE_READ | H5FD_LOG_FILE_WRITE)H5FD_LOG_FLAVORTrack the type, or flavor, of information stored at each byte. H5FD_LOG_NUM_READTrack the total number of read, write, seek, or truncate operations that occur. H5FD_LOG_NUM_WRITEH5FD_LOG_NUM_SEEKH5FD_LOG_NUM_TRUNCATEH5FD_LOG_NUM_IOTrack the total number of all types of I/O operations. The logical equivalent of the following: (H5FD_LOG_NUM_READ | H5FD_LOG_NUM_WRITE | H5FD_LOG_NUM_SEEK | H5FD_LOG_NUM_TRUNCATE)H5FD_LOG_TIME_OPENTrack the time spent in open, stat, read, write, seek, or close operations. H5FD_LOG_TIME_STATH5FD_LOG_TIME_READH5FD_LOG_TIME_WRITEH5FD_LOG_TIME_SEEKH5FD_LOG_TIME_CLOSEH5FD_LOG_TIME_IOTrack the time spent in each of the above operations. The logical equivalent of the following: (H5FD_LOG_TIME_OPEN | H5FD_LOG_TIME_STAT | H5FD_LOG_TIME_READ | H5FD_LOG_TIME_WRITE | H5FD_LOG_TIME_SEEK | H5FD_LOG_TIME_CLOSE)H5FD_LOG_ALLOCTrack the allocation of space in the file. H5FD_LOG_ALLTrack everything. The logical equivalent of the following: (H5FD_LOG_ALLOC | H5FD_LOG_TIME_IO | H5FD_LOG_NUM_IO | H5FD_LOG_FLAVOR | H5FD_LOG_FILE_IO | H5FD_LOG_LOC_IO)The logging driver can track the number of times each byte in the file is read from or written to (using
H5FD_LOG_FILE_READandH5FD_LOG_FILE_WRITE) and what kind of data is at that location (e.g., metadata, raw data; usingH5FD_LOG_FLAVOR). This information is tracked in internal buffers of sizebuf_size, which must be at least the maximum size in bytes of the file to be logged while the log driver is in use.One buffer of size
buf_sizewill be created for each ofH5FD_LOG_FILE_READ,H5FD_LOG_FILE_WRITEandH5FD_LOG_FLAVORwhen those flags are set; these buffers will not grow as the file increases in size.- Parameters:
hid_t fapl_idIN: File access property list identifier. char * logfileIN: Name of the log file. unsigned long long flagsIN: Flags specifying the types of logging activity. size_t buf_sizeIN: The size of the logging buffers, in bytes (see description). - Output:
- This section describes the logging driver (LOG VFD) output.
The table, immediately below, describes output of the various logging driver flags and function calls; error output is in red italic. A list of valid flavor values, describing the type of data stored, follows the table.
Table 2: Logging output
Flag (H5FD_LOG_) VFD Call Output and Comments LOC_READRead()%10a-%10a (%10Zu bytes) (%s) ReadStart position
End position
Number of bytes
Flavor of readAdds
(%f s)and seek time ifTIME_SEEKis also set.LOC_READRead() ErrorError! Reading: %10a-%10a (%10Zu bytes)Same parameters as non-error entry.
LOC_WRITEWrite()%10a-%10a (%10Zu bytes) (%s) WrittenStart position
End position
Number of bytes
Flavor of writeAdds
(%f s)and seek time ifTIME_SEEKis also set.LOC_WRITEWrite() ErrorError! Writing: %10a-%10a (%10Zu bytes)Same parameters as non-error entry.
LOC_SEEKRead()
Write()Seek: From %10a-%10aStart position
End positionAdds
(%f s)and seek time ifTIME_SEEKis also set.FILE_READClose()Begins with:
Dumping read I/O informationThen, for each range of identical values, there is this line:
\tAddr %10-%10 (%10lu bytes) read from %3d timesStart address
End address
Number of bytes
Number of times readNote: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
FILE_WRITEClose()Begins with:
Dumping write I/O informationThen, for each range of identical values, there is this line:
\tAddr %10-%10 (%10lu bytes) written to %3d timesStart address
End address
Number of bytes
Number of times writtenNote: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
FLAVORClose()Begins with:
Dumping I/O flavor informationThen, for each range of identical values, there is this line:
\tAddr %10-%10 (%10lu bytes) flavor is %sStart address
End address
Number of bytes
FlavorNote: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
NUM_READClose()Total number of read operations: %11uNUM_WRITEClose()Total number of write operations: %11uNUM_SEEKClose()Total number of seek operations: %11uNUM_TRUNCATEClose()Total number of truncate operations: %11uTIME_OPENOpen()Open took: (%f s)TIME_READClose()
Read()Total time in read operations: %f sSee also:
LOC_READTIME_WRITEClose()
Write()Total time in write operations: %f sSee also:
LOC_WRITETIME_SEEKClose()
Read()
Write()Total time in seek operations: %f sSee also:
LOC_SEEKorLOC_WRITETIME_CLOSEClose()Close took: (%f s)TIME_STATOpen()Stat took: (%f s)ALLOCAlloc()%10-%10 (%10Hu bytes) (%s) AllocatedStart of address space
End of address space
Total size of allocation
Flavor of allocation
Flavors:
The flavor describes the type of stored information. The following table lists the flavors that appear in log output and briefly describes each. These terms are provided here to aid in the construction of log message parsers; a full description is beyond the scope of this document.
Table 3: Flavors of logged data
Flavor Description H5FD_MEM_NOLISTError value H5FD_MEM_DEFAULTValue not yet set.
May also be a datatype set in a larger allocation that will be suballocated by the library.H5FD_MEM_SUPERSuperblock data H5FD_MEM_BTREEB-tree data H5FD_MEM_DRAWRaw data (for example, contents of a dataset) H5FD_MEM_GHEAPGlobal heap data H5FD_MEM_LHEAPLocal heap data H5FD_MEM_OHDRObject header data - Returns:
- Returns non-negative if successful. Otherwise returns negative.
- Fortran90 Interface:
- None.
- History:
Release C 1.8.7 The flagsparameter has been changed from unsigned int to unsigned long long.
The implementation of theH5FD_LOG_TIME_OPEN,H5FD_LOG_TIME_READ,H5FD_LOG_TIME_WRITE, andH5FD_LOG_TIME_SEEKflags has been finished.
New flags were added:H5FD_LOG_NUM_TRUNCATEandH5FD_LOG_TIME_STAT.
1.6.0 The verbosityparameter has been removed.
Two new parameters have been added:flagsof type unsigned andbuf_sizeof type size_t.1.4.0 Function introduced in this release.
- Last modified: 15 May 2009
- Name: H5Pset_fapl_mpio
- Signature:
- Name: H5Pset_fapl_mpio
- herr_t
H5Pset_fapl_mpio( hid_tfapl_id, MPI_Commcomm, MPI_Infoinfo) - Purpose:
- Stores MPI IO communicator information to the file access property list.
- Description:
H5Pset_fapl_mpiostores the user-supplied MPI IO parameterscomm, for communicator, andinfo, for information, in the file access property listfapl_id. That property list can then be used to create and/or open a file.H5Pset_fapl_mpiois available only in the parallel HDF5 library and is not a collective function.commis the MPI communicator to be used for file open, as defined inMPI_FILE_OPENof MPI-2. This function makes a duplicate of the communicator, so modifications tocommafter this function call returns have no effect on the file access property list.infois the MPI Info object to be used for file open, as defined inMPI_FILE_OPENof MPI-2. This function makes a duplicate copy of the Info object, so modifications to the Info object after this function call returns will have no effect on the file access property list.If the file access property list already contains previously-set communicator and Info values, those values will be replaced and the old communicator and Info object will be freed.
- Note:
- Raw dataset chunk caching is not currently supported when using
this file driver in read/write mode.
All calls to
H5DreadandH5Dwritewill access the disk directly, andH5Pset_cacheandH5Pset_chunk_cachewill have no effect on performance.Raw dataset chunk caching is supported when this driver is used in read-only mode.
- Parameters:
hid_t fapl_idIN: File access property list identifier MPI_Comm commIN: MPI-2 communicator MPI_Info infoIN: MPI-2 info object - Returns:
- Returns a non-negative value if successful.
Otherwise returns a negative value.
- Fortran90 Interface: h5pset_fapl_mpio_f
-
SUBROUTINE h5pset_fapl_mpio_f(prp_id, comm, info, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(IN) :: comm ! MPI communicator to be used for ! file open as defined in ! MPI_FILE_OPEN of MPI-2 INTEGER, INTENT(IN) :: info ! MPI info object to be used for ! file open as defined in ! MPI_FILE_OPEN of MPI-2 INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_fapl_mpio_f - History:
Release Change 1.4.5 Handling of the MPI Communicator and Info object changed at this release. A duplicate of each of these is now stored in the property list instead of pointers to each. 1.4.0 C function introduced in this release.
- Last modified: 2 May 2013
- Name: H5Pset_fapl_mpiposix
- Signature:
- Name: H5Pset_fapl_mpiposix
- herr_t
H5Pset_fapl_mpiposix( hid_tfapl_id, MPI_Commcomm, hbool_tuse_gpfs_hints) - Purpose:
- Stores MPI IO communicator information to a file access property list.
- Function Removed:
-
The C functions H5Pset_fapl_mpiposixandH5Pget_fapl_mpiposixand the corresponding Fortran subroutines have been removed from the HDF5 Library at Release 1.8.13. They remain available in earlier releases, through HDF5 Release 1.8.12.
All applications used with HDF5 Release 1.8.13 or later and that use MPI I/O should use the functionsH5Pset_fapl_mpioandH5Pget_fapl_mpioor the corresponding Fortran subroutines.
While HDF5’s MPI-POSIX driver (H5Pset_fapl_mpiposixandH5Pget_fapl_mpiposix) once provided performance benefits on some systems, that is no longer the case. HDF5’s MPIO driver (H5Pset_fapl_mpioandH5Pget_fapl_mpio) now provides as good or better performance on all modern systems. - Description:
H5Pset_fapl_mpiposixstores the user-supplied MPI IO parametercomm, for communicator, in the file access property listfapl_id. That property list can then be used to create and/or open the file.H5Pset_fapl_mpiposixis available only in the parallel HDF5 library and is not a collective function.commis the MPI communicator to be used for file open, as defined inMPI_FILE_OPENof MPI-2. This function does not create a duplicated communicator. Modifications tocommafter this function call returns may have an undetermined effect on the file access property list. Users should not modify the communicator while it is defined in a property list.use_gpfs_hintsspecifies whether to attempt to use GPFS hints when accessing this file. A value ofTRUE(or1) indicates that the hints should be used, if possible. A value ofFALSE(or0) indicates that the hints should not be used.Available GPFS hints are known to the HFD5 Library and are not user configurable. They may be used only with GPFS file systems and may improve file access for some applications; the user of a GPFS system is encouraged to experiment by running an application with and without this parameter set.
- Note:
- Raw dataset chunk caching is not currently supported when using
this file driver in read/write mode.
All calls to
H5DreadandH5Dwritewill access the disk directly, andH5Pset_cacheandH5Pset_chunk_cachewill have no effect on performance.Raw dataset chunk caching is supported when this driver is used in read-only mode.
- Parameters:
hid_t fapl_idIN: File access property list identifier. MPI_Comm commIN: MPI-2 communicator. hbool_t use_gpfs_hintsIN: Use of GPFS hints. - Returns:
- Returns a non-negative value if successful.
Otherwise returns a negative value.
- Fortran90 Interface: h5pset_fapl_mpiposix_f
-
SUBROUTINE h5pset_fapl_mpiposix_f(prp_id, comm, use_gpfs, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(IN) :: comm ! MPI communicator to be used ! for file open as defined in ! MPI_FILE_OPEN of MPI-2 LOGICAL, INTENT(IN) :: use_gpfs INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5pset_fapl_mpiposix_f - History:
Release Change 1.8.13 C function and Fortran subroutine removed from HDF5 at this release. 1.6.1 Fortran subroutine introduced in this release. 1.6.0 use_gpfs_hintsparameter added.1.6.0 C function introduced in this release.
- Last modified: 14 October 2014
- Name: H5Pset_fapl_multi
- Signature:
- herr_t
H5Pset_fapl_multi( hid_tfapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl, const char * const *memb_name, const haddr_t *memb_addr, hbool_trelax) - Purpose:
- Sets up use of the multi-file driver.
- Description:
H5Pset_fapl_multisets the file access property listfapl_idto use the multi-file driver.The multi-file driver enables different types of HDF5 data and metadata to be written to separate files. These files are viewed by the HDF5 library and the application as a single virtual HDF5 file with a single HDF5 file address space. The types of data that can be broken out into separate files include raw data, the superblock, B-tree data, global heap data, local heap data, and object headers. At the programmer's discretion, two or more types of data can be written to the same file while other types of data are written to separate files.
The array
memb_mapmaps memory usage types to other memory usage types and is the mechanism that allows the caller to specify how many files are created. The array containsH5FD_MEM_NTYPESentries, which are either the valueH5FD_MEM_DEFAULTor a memory usage type. The number of unique values determines the number of files that are opened.The array
memb_faplcontains a property list for each memory usage type that will be associated with a file.The array
memb_nameshould be a name generator (a printf-style format with a %s which will be replaced with the name passed toH5FDopen, usually fromH5FcreateorH5Fopen).The array
memb_addrspecifies the offsets within the virtual address space, from0(zero) toHADDR_MAX, at which each type of data storage begins.If
relaxis set toTRUE(or1), then opening an existing file for read-only access will not fail if some file members are missing. This allows a file to be accessed in a limited sense if just the meta data is available.Default values for each of the optional arguments are as follows:
memb_map- The default member map contains the value
H5FD_MEM_DEFAULTfor each element. memb_fapl- The default value is
H5P_DEFAULTfor each element. memb_name- The default string is
%s-X.h5whereXis one of the following letters:sforH5FD_MEM_SUPER
bforH5FD_MEM_BTREE
rforH5FD_MEM_DRAW
gforH5FD_MEM_GHEAP
lforH5FD_MEM_LHEAP
oforH5FD_MEM_OHDR memb_addr- The default setting is that the address space is equally
divided among all of the elements:
H5FD_MEM_SUPER -> 0 * (HADDR_MAX/6) H5FD_MEM_BTREE -> 1 * (HADDR_MAX/6) H5FD_MEM_DRAW -> 2 * (HADDR_MAX/6) H5FD_MEM_GHEAP -> 3 * (HADDR_MAX/6) H5FD_MEM_LHEAP -> 4 * (HADDR_MAX/6) H5FD_MEM_OHDR -> 5 * (HADDR_MAX/6)
- Parameters:
hid_t fapl_idIN: File access property list identifier. const H5FD_mem_t * memb_mapIN: Maps memory usage types to other memory usage types. const hid_t * memb_faplIN: Property list for each memory usage type. const char * const * memb_nameIN: Name generator for names of member files. const haddr_t * memb_addrIN: The offsets within the virtual address space, from 0(zero) toHADDR_MAX, at which each type of data storage begins.hbool_t relaxIN: Allows read-only access to incomplete file sets when TRUE.- Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Example:
- The following code sample sets up a multi-file access property list
that partitions data into meta and raw files, each being
one-half of the address:
H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES]; hid_t memb_fapl[H5FD_MEM_NTYPES]; const char *memb[H5FD_MEM_NTYPES]; haddr_t memb_addr[H5FD_MEM_NTYPES]; // The mapping... for (mt=0; mt<H5FD_MEM_NTYPES; mt++) { memb_map[mt] = H5FD_MEM_SUPER; } memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW; // Member information memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT; memb_name[H5FD_MEM_SUPER] = "%s.meta"; memb_addr[H5FD_MEM_SUPER] = 0; memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT; memb_name[H5FD_MEM_DRAW] = "%s.raw"; memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2; hid_t fapl = H5Pcreate(H5P_FILE_ACCESS); H5Pset_fapl_multi(fapl, memb_map, memb_fapl, memb_name, memb_addr, TRUE); - Fortran90 Interface: h5pset_fapl_multi_f
-
SUBROUTINE h5pset_fapl_multi_f(prp_id, memb_map, memb_fapl, memb_name, memb_addr, relax, hdferr) IMPLICIT NONE INTEGER(HID_T),INTENT(IN) :: prp_id ! Property list identifier INTEGER,DIMENSION(H5FD_MEM_NTYPES_F),INTENT(IN) :: memb_map INTEGER(HID_T),DIMENSION(H5FD_MEM_NTYPES_F),INTENT(IN) :: memb_fapl CHARACTER(LEN=*),DIMENSION(H5FD_MEM_NTYPES_F),INTENT(IN) :: memb_name REAL, DIMENSION(H5FD_MEM_NTYPES_F), INTENT(IN) :: memb_addr ! Numbers in the interval [0,1) (e.g. 0.0 0.1 0.5 0.2 0.3 0.4) ! real address in the file will be calculated as X*HADDR_MAXLOGICAL, INTENT(IN) :: relax INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_fapl_multi_f - History:
Release C 1.6.3 memb_nameparameter type changed to const char* const*.1.4.0 Function introduced in this release.
- Name: H5Pset_fapl_sec2
- Signature:
- herr_t
H5Pset_fapl_sec2( hid_tfapl_id) - Purpose:
- Sets the sec2 driver.
- Description:
H5Pset_fapl_sec2modifies the file access property list to use theH5FD_SEC2driver.- Parameters:
hid_t fapl_idIN: File access property list identifier. - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Fortran90 Interface: h5pset_fapl_sec2_f
-
SUBROUTINE h5pset_fapl_sec2_f(prp_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_fapl_sec2_f - History:
Release C 1.4.0 Function introduced in this release.
- Name: H5Pset_fapl_split
- Signature:
- herr_t
H5Pset_fapl_split( hid_tfapl_id, const char *meta_ext, hid_tmeta_plist_id, const char *raw_ext, hid_traw_plist_id) - Purpose:
- Emulates the old split file driver.
- Description:
H5Pset_fapl_splitis a compatibility function that enables the multi-file driver to emulate the split driver from HDF5 Releases 1.0 and 1.2. The split file driver stored metadata and raw data in separate files but provided no mechanism for separating types of metadata.fapl_idis a file access property list identifier.meta_extis the filename extension for the metadata file. The extension is appended to the name passed toH5FDopen, usually fromH5FcreateorH5Fopen, to form the name of the metadata file. If the string %s is used in the extension, it works like the name generator as inH5Pset_fapl_multi.meta_plist_idis the file access property list identifier for the metadata file.raw_extis the filename extension for the raw data file. The extension is appended to the name passed toH5FDopen, usually fromH5FcreateorH5Fopen, to form the name of the rawdata file. If the string %s is used in the extension, it works like the name generator as inH5Pset_fapl_multi.raw_plist_idis the file access property list identifier for the raw data file.If a user wishes to check to see whether this driver is in use, the user must call
H5Pget_driverand compare the returned value to the stringH5FD_MULTI. A positive match will confirm that the multi driver is in use; HDF5 provides no mechanism to determine whether it was called as the special case invoked byH5Pset_fapl_split.- Parameters:
hid_t fapl_id,IN: File access property list identifier. const char * meta_ext,IN: Metadata filename extension. hid_t meta_plist_id,IN: File access property list identifier for the metadata file. const char * raw_ext,IN: Raw data filename extension. hid_t raw_plist_idIN: File access property list identifier for the raw data file. - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Example:
-
/* Example 1: Both metadata and rawdata files are in the same */ /* directory. Use Station1-m.h5 and Station1-r.h5 as */ /* the metadata and rawdata files. */ hid_t fapl, fid; fapl = H5Pcreate(H5P_FILE_ACCESS); H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "-r.h5", H5P_DEFAULT); fid=H5Fcreate("Station1",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); /* Example 2: metadata and rawdata files are in different */ /* directories. Use PointA-m.h5 and /pfs/PointA-r.h5 as */ /* the metadata and rawdata files. */ hid_t fapl, fid; fapl = H5Pcreate(H5P_FILE_ACCESS); H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT); fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); - Fortran90 Interface: h5pset_fapl_split_f
-
SUBROUTINE h5pset_fapl_split_f(prp_id, meta_ext, meta_plist, raw_ext, & raw_plist, hdferr) IMPLICIT NONE INTEGER(HID_T),INTENT(IN) :: prp_id ! Property list identifier CHARACTER(LEN=*),INTENT(IN) :: meta_ext ! Name of the extension for ! the metafile filename INTEGER(HID_T),INTENT(IN) :: meta_plist ! Identifier of the meta file ! access property list CHARACTER(LEN=*),INTENT(IN) :: raw_ext ! Name extension for the raw ! file filename INTEGER(HID_T),INTENT(IN) :: raw_plist ! Identifier of the raw file ! access property list INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_fapl_split_f - History:
Release C 1.4.0 Function introduced in this release.
- Name: H5Pset_fapl_stdio
- Signature:
- herr_t
H5Pset_fapl_stdio( hid_tfapl_id) - Purpose:
- Sets the standard I/O driver.
- Description:
H5Pset_fapl_stdiomodifies the file access property list to use the standard I/O driver,H5FD_STDIO.- Parameters:
hid_t fapl_idIN: File access property list identifier. - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Fortran90 Interface: h5pset_fapl_stdio_f
-
SUBROUTINE h5pset_fapl_stdio_f(prp_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_fapl_stdio_f - History:
Release C 1.4.0 Function introduced in this release.
- Name: H5Pset_fapl_windows
- Signature:
- herr_t
H5Pset_fapl_windows( hid_tfapl_id) - Purpose:
- Sets the Windows I/O driver.
- Description:
H5Pset_fapl_windowssets the default HDF5 Windows I/O driver on Windows systems.Since the HDF5 Library uses this driver,
H5FD_WINDOWS, by default on Windows systems, it is not normally necessary for a user application to callH5Pset_fapl_windows. While it is not recommended, there may be times when a user chooses to set a different HDF5 driver, such as the standard I/O driver (H5FD_STDIO) or the sec2 driver (H5FD_SEC2), in a Windows application.H5Pset_fapl_windowsis provided so that the application can return to the Windows I/O driver when the time comes.Only the Windows driver is tested on Windows systems; other drivers are used at the application’s and the user’s risk.
Furthermore, the Windows driver is tested and available only on Windows systems; it is not available on non-Windows systems.
- Parameters:
hid_t fapl_idIN: File access property list identifier - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface:
- None.
- History:
Release C 1.8.0 Function introduced in this release.
- Last modified: 18 June 2013
- Name: H5Pset_fclose_degree
- Signature:
- Name: H5Pset_fclose_degree
- herr_t
H5Pset_fclose_degree( hid_tfapl_id, H5F_close_degree_tfc_degree) - Purpose:
- Sets the file close degree.
- Description:
H5Pset_fclose_degreesets the file close degree propertyfc_degreein the file access property listfapl_id.The value of
fc_degreedetermines how aggressivelyH5Fclosedeals with objects within a file that remain open whenH5Fcloseis called to close that file.fc_degreecan have any one of four valid values:Degree name H5Fclosebehavior with no open object in fileH5Fclosebehavior with open object(s) in fileH5F_CLOSE_WEAKActual file is closed. Access to file identifier is terminated; actual file close is delayed until all objects in file are closed H5F_CLOSE_SEMIActual file is closed. Function returns FAILURE H5F_CLOSE_STRONGActual file is closed. All open objects remaining in the file are closed then file is closed H5F_CLOSE_DEFAULTThe VFL driver chooses the behavior. Currently, all VFL drivers set this value to H5F_CLOSE_WEAK, except for the MPI-I/O driver, which sets it toH5F_CLOSE_SEMI.Note that if a file is opened multiple times without being closed, each open operation must use the same file close degree setting. For example, if a file is already open with
H5F_CLOSE_WEAK, anH5Fopencall withH5F_CLOSE_STRONGwill fail.- Parameters:
hid_t fapl_idIN: File access property list identifier. H5F_close_degree_t fc_degreeIN: Pointer to a location containing the file close degree property, the value of fc_degree.- Returns:
- Returns a non-negative value if successful. Otherwise returns a negative
value.
- Fortran90 Interface: h5pset_fclose_degree_f
-
SUBROUTINE h5pset_fclose_degree_f(fapl_id, degree, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier INTEGER, INTENT(IN) :: degree ! Info about file close behavior ! Possible values: ! H5F_CLOSE_DEFAULT_F ! H5F_CLOSE_WEAK_F ! H5F_CLOSE_SEMI_F ! H5F_CLOSE_STRONG_F INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_fclose_degree_f - History:
Release C 1.6.0 Function introduced in this release.
- Last modified: 2 May 2014
- Name: H5Pset_file_image
- Signature:
- Name: H5Pset_file_image
- herr_t
H5Pset_file_image( hid_tfapl_id, void *buf_ptr, size_tbuf_len) - Purpose:
- Sets an initial file image in a memory buffer.
- Motivation:
H5Pset_file_imageand other elements of HDF5 are used to load an image of an HDF5 file into system memory and open that image as a regular HDF5 file. An application can then use the file without the overhead of disk I/O.- Recommended Reading:
- This function is part of the file image operations feature set.
It is highly recommended to study the guide
“HDF5 File Image Operations” before using this feature set.
See the “See Also” section below for links to other elements of HDF5 file image operations.
- Description:
H5Pset_file_imageallows an application to provide a file image to be used as the initial contents of a file. CallingH5Pset_file_imagemakes a copy of the buffer specified inbuf_ptrof sizebuf_len.- Parameters:
-
hid_t fapl_idIN: File access property list identifier void * buf_ptrIN: Pointer to the initial file image, or NULLif no initial file image is desiredsize_t buf_lenIN: Size of the supplied buffer, or 0(zero) if no initial image is desired - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran2003 Interface: h5pset_file_image_f
-
Signature:
SUBROUTINE h5pset_file_image_f(fapl_id, buf_ptr, buf_len, hdferr) USE iso_c_binding IMPLICIT NONE INTEGER(HID_T) , INTENT(IN) :: fapl_id TYPE(C_PTR) , INTENT(IN) :: buf_ptr INTEGER(SIZE_T), INTENT(IN) :: buf_len INTEGER , INTENT(OUT) :: hdferrInputs:
fapl_id - File access property list identifier buf_ptr - Pointer to the initial file image, or C_NULL_PTR if no initial file image is desired buf_len - Size of the supplied buffer, or 0 (zero) if no initial image is desiredOutputs:
hdferr - Returns 0 if successful and -1 if fails
- See Also:
H5LTopen_file_image
H5Fget_file_image
H5Pget_file_image
H5Pset_file_image_callbacks
H5Pget_file_image_callbacks“HDF5 File Image Operations”
WithinH5Pset_file_image_callbacks:
Callback structH5_file_image_callbacks_t
Callback ENUMH5_file_image_op_t- History:
Release Change 1.8.13 Fortran subroutine added in this release. 1.8.9 C function introduced in this release.
- Last modified: 13 April 2012
- Name: H5Pset_file_image_callbacks
- Signature:
- Name: H5Pset_file_image_callbacks
- herr_t
H5Pset_file_image_callbacks( hid_tfapl_id, H5_file_image_callbacks_t *callbacks_ptr) - Purpose:
- Sets the callbacks for working with file images.
- Motivation:
H5Pset_file_image_callbacksand other elements of HDF5 are used to load an image of an HDF5 file into system memory and open that image as a regular HDF5 file. An application can then use the file without the overhead of disk I/O.- Recommended Reading:
- This function is part of the file image operations feature set.
It is highly recommended to study the guide
“HDF5 File Image Operations” before using this feature set.
See the “See Also” section below for links to other elements of HDF5 file image operations.
- Description:
H5Pset_file_image_callbackssets callback functions for working with file images in memory.H5Pset_file_image_callbacksallows an application to control the management of file image buffers through user defined callbacks. These callbacks can be used in the management of file image buffers in property lists and with certain file drivers.H5Pset_file_image_callbacksmust be used before any file image has been set in the file access property list. Once a file image has been set, the function will fail.The callback routines set up by
H5Pset_file_image_callbacksare invoked when a new file image buffer is allocated, when an existing file image buffer is copied or resized, or when a file image buffer is released from use.Some file drivers allow the use of user-defined callback functions for allocating, freeing, and copying the driver’s internal buffer, potentially allowing optimizations such as avoiding large
mallocandmemcpyoperations, or to perform detailed logging.From the perspective of the HDF5 Library, the operations of the
image_malloc,image_memcpy,image_realloc, andimage_freecallbacks must be identical to those of the corresponding C standard library calls (malloc,memcpy,realloc, andfree). While the operations must be identical, the file image callbacks have more parameters. The return values ofimage_mallocandimage_reallocare identical to the return values ofmallocandrealloc. The return values ofimage_memcpyandimage_freediffer from the return values ofmemcpyandfreein that the return values ofimage_memcpyandimage_freecan also indicate failure.The callbacks and their parameters, along with a struct and an ENUM required for their use, are described below.
Callback struct and ENUM:
The callback functions set up byH5Pset_file_image_callbacksuse a struct and an ENUM that are defined as followsThe struct
H5_file_image_callbacks_tserves as a container for the callback functions and a pointer to user-supplied data. The struct is defined as follows:typedef struct { void *(*image_malloc)(size_t size, H5_file_image_op_t file_image_op, void *udata); void *(*image_memcpy)(void *dest, const void *src, size_t size, H5_file_image_op_t file_image_op, void *udata); void *(*image_realloc)(void *ptr, size_t size, H5_file_image_op_t file_image_op, void *udata); herr_t (*image_free)(void *ptr, H5_file_image_op_t file_image_op, void *udata); void *(*udata_copy)(void *udata); herr_t (*udata_free)(void *udata); void *udata; } H5_file_image_callbacks_t;
Elements of the ENUMH5_file_image_op_tare used by the callbacks to invoke certain operations on file images. The ENUM is defined as follows:typedef enum { H5_FILE_IMAGE_OP_PROPERTY_LIST_SET, H5_FILE_IMAGE_OP_PROPERTY_LIST_COPY, H5_FILE_IMAGE_OP_PROPERTY_LIST_GET, H5_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE, H5_FILE_IMAGE_OP_FILE_OPEN, H5_FILE_IMAGE_OP_FILE_RESIZE, H5_FILE_IMAGE_OP_FILE_CLOSE } H5_file_image_op_t;The elements of the
H5_file_image_op_tENUM are used in the callbacks for the following purposes:H5_FILE_IMAGE_OP_PROPERTY_LIST_SETPassed to the image_mallocandimage_memcpycallbacks when a file image buffer is to be copied while being set in a file access property list (FAPL).H5_FILE_IMAGE_OP_PROPERTY_LIST_COPYPassed to the image_mallocandimage_memcpycallbacks when a file image buffer is to be copied when a FAPL is copied.H5_FILE_IMAGE_OP_PROPERTY_LIST_GETPassed to the image_mallocandimage_memcpycallbacks when a file image buffer is to be copied while being retrieved from a FAPL.H5_FILE_IMAGE_OP_PROPERTY_LIST_CLOSEPassed to the image_freecallback when a file image buffer is to be released during a FAPL close operation.H5_FILE_IMAGE_OP_FILE_OPENPassed to the image_mallocandimage_memcpycallbacks when a file image buffer is to be copied during a file open operation. While the file image being opened will typically be copied from a FAPL, this need not always be the case. For example, the core file driver, also known as the memory file driver, takes its initial image from a file.H5_FILE_IMAGE_OP_FILE_RESIZEPassed to the image_realloccallback when a file driver needs to resize an image buffer.H5_FILE_IMAGE_OP_FILE_CLOSEPassed to the image_freecallback when an image buffer is to be released during a file close operation.
Callback functions
Theimage_malloccallback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C librarymalloc()call.- Signature in
H5_file_image_callbacks_t: - void
*(*image_malloc) (size_tsize, H5_file_image_op_t *file_image_op, void *udata) - Parameters:
size_t sizeIN: Size in bytes of the file image buffer to allocate H5_file_image_op_t * file_image_opIN: A value from H5_file_image_op_tindicating the operation being performed on the file image when this callback is invokedvoid * udataIN: Value passed in in the H5Pset_file_image_callbacksparameterudata
Theimage_memcpycallback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C librarymemcopy()call, except that it returns aNULLon failure. (ThememcpyC Library routine is defined to return thedestparameter in all cases.)Setting
image_memcpytoNULLindicates that HDF5 should invoke the standard C librarymemcpy()routine when copying buffers.- Signature in
H5_file_image_callbacks_t: - void
*(*image_memcpy) (void *dest, const void *src, size_tsize, H5_file_image_op_t *file_image_op, void *udata) - Parameters:
void * destIN: Address of the destination buffer const void * srcIN: Address of the source buffer size_t sizeIN: Size in bytes of the file image buffer to copy H5_file_image_op_t * file_image_opIN: A value from H5_file_image_op_tindicating the operation being performed on the file image when this callback is invokedvoid * udataIN: Value passed in in the H5Pset_file_image_callbacksparameterudata
Theimage_realloccallback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C libraryrealloc()call.Setting
image_realloctoNULLindicates that HDF5 should invoke the standard C libraryrealloc()routine when resizing file image buffers.- Signature in
H5_file_image_callbacks_t: - void
*(*image_realloc) (void *ptr, size_tsize, H5_file_image_op_t *file_image_op, void *udata) - Parameters:
void * ptrIN: Pointer to the buffer being reallocated size_t sizeIN: Desired size in bytes of the file image buffer after reallocation H5_file_image_op_t * file_image_opIN: A value from H5_file_image_op_tindicating the operation being performed on the file image when this callback is invokedvoid * udataIN: Value passed in in the H5Pset_file_image_callbacksparameterudata
Theimage_freecallback contains a pointer to a function that must appear to HDF5 to have functionality identical to that of the standard C libraryfree()call, except that it will return0(SUCCEED) on success and-1(FAIL) on failure.Setting
image_freetoNULLindicates that HDF5 should invoke the standard C libraryfree()routine when releasing file image buffers.- Signature in
H5_file_image_callbacks_t: - herr_t
(*image_free) (void *ptr, H5_file_image_op_t *file_image_op, void *udata) - Parameters:
void * ptrIN: Pointer to the buffer being released H5_file_image_op_t * file_image_opIN: A value from H5_file_image_op_tindicating the operation being performed on the file image when this callback is invokedvoid * udataIN: Value passed in in the H5Pset_file_image_callbacksparameterudata
Theudata_copycallback contains a pointer to a function that, from the perspective of HDF5, allocates a buffer of suitable size, copies the contents of the suppliedudatainto the new buffer, and returns the address of the new buffer. The function returnsNULL on failure. This function is necessary if a non-NULL udataparameter is supplied, so that property lists containing the image callbacks can be copied. If theudataparameter below isNULL, then this parameter should beNULLas well.- Signature in
H5_file_image_callbacks_t: - void
*(*udata_copy) (void *udata) - Parameters:
void * udataIN: Value passed in in the H5Pset_file_image_callbacksparameterudata
Theudata_freecallback contains a pointer to a function that, from the perspective of HDF5, frees a user data block. This function is necessary if a non-NULLudataparameter is supplied so that property lists containing image callbacks can be discarded without a memory leak. If theudataparameter below isNULL, this parameter should beNULLas well.- Signature in
H5_file_image_callbacks_t: - herr_t
(*udata_free) (void *udata) - Parameters:
void * udataIN: Value passed in in the H5Pset_file_image_callbacksparameterudata
udata, the final field in theH5_file_image_callbacks_tstruct, provides a pointer to user-defined data. This pointer will be passed to theimage_malloc,image_memcpy,image_realloc, andimage_freecallbacks. DefineudataasNULLif no user-defined data is provided.- Parameters:
hid_t fapl_idIN: File access property list identifier H5_file_image_callbacks_t * callbacks_ptrIN/OUT: Pointer to an instance of the H5_file_image_callbacks_tstructure- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Failure Modes:
- Due to interactions between this function and
H5Pset_file_imageandH5Pget_file_image,H5Pset_file_image_callbackswill fail if a file image has already been set in the target file access property list,fapl_id.- See Also:
H5LTopen_file_image
H5Fget_file_image
H5Pset_file_image
H5Pget_file_image
H5Pget_file_image_callbacks“HDF5 File Image Operations”
WithinH5Pset_file_image_callbacks:
Callback structH5_file_image_callbacks_t
Callback ENUMH5_file_image_op_t- History:
Release Change 1.8.9 C function introduced in this release. - Signature in
- Name: H5Pset_fill_time
- Signature:
- herr_t
H5Pset_fill_time(hid_tplist_id, H5D_fill_time_tfill_time) - Purpose:
- Sets the time when fill values are written to a dataset.
- Description:
H5Pset_fill_timesets up the timing for writing fill values to a dataset. This property is set in the dataset creation property listplist_id.Timing is specified in
fill_timewith one of the following values:H5D_FILL_TIME_IFSETWrite fill values to the dataset when storage space is allocated only if there is a user-defined fill value, i.e., one set with H5Pset_fill_value. (Default) H5D_FILL_TIME_ALLOCWrite fill values to the dataset when storage space is allocated. H5D_FILL_TIME_NEVERNever write fill values to the dataset. - Note:
H5Pset_fill_timeis designed for coordination with the dataset fill value and dataset storage allocation time properties, set with the functionsH5Pset_fill_valueandH5Pset_alloc_time.See H5Dcreate for further cross-references.
- Parameters:
hid_t plist_idIN: Dataset creation property list identifier. H5D_fill_time_t fill_timeIN: When to write fill values to a dataset. - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_fill_time_f
-
SUBROUTINE h5pset_fill_time_f(plist_id, flag, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property ! list identifier INTEGER(HSIZE_T), INTENT(IN) :: flag ! File time flag ! Possible values are: ! H5D_FILL_TIME_ERROR_F ! H5D_FILL_TIME_ALLOC_F ! H5D_FILL_TIME_NEVER_F INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_fill_time_f - History:
Release C 1.6.0 Function introduced in this release.
- Last modified: 29 September 2011
- Name: H5Pset_fill_value
- Signature:
- Name: H5Pset_fill_value
- herr_t
H5Pset_fill_value( hid_tplist_id, hid_ttype_id, const void *value) - Purpose:
- Sets the fill value for a dataset.
- Description:
H5Pset_fill_valuesets the fill value for a dataset in the dataset creation property list.valueis interpreted as being of datatypetype_id. This datatype may differ from that of the dataset, but the HDF5 library must be able to convertvalueto the dataset datatype when the dataset is created.The default fill value is
0(zero), which is interpreted according to the actual dataset datatype.Setting
valuetoNULLindicates that the fill value is to be undefined.- Notes:
- Applications sometimes write data only to portions of
an allocated dataset. It is often useful in such cases
to fill the unused space with a known
fill value.
This function allows the user application to set that fill value;
the functions
H5DfillandH5Pset_fill_time, respectively, provide the ability to apply the fill value on demand or to set up its automatic application.A fill value should be defined so that it is appropriate for the application. While the HDF5 default fill value is
0(zero), it is often appropriate to use another value. It might be useful, for example, to use a value that is known to be impossible for the application to legitimately generate.H5Pset_fill_valueis designed to work in concert withH5Pset_alloc_timeandH5Pset_fill_time.H5Pset_alloc_timeandH5Pset_fill_timegovern the timing of dataset storage allocation and fill value write operations and can be important in tuning application performance.See
H5Dcreatefor further cross-references. - Parameters:
hid_t plist_idIN: Dataset creation property list identifier. hid_t type_id,IN: Datatype of value.const void * valueIN: Pointer to buffer containing value to use as fill value. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_fill_value_f
-
Signature:
SUBROUTINE h5pset_fill_value_f(prp_id, type_id, fillvalue, hdferr) INTEGER(HID_T), INTENT(IN) :: prp_id INTEGER(HID_T), INTENT(IN) :: type_id TYPE(VOID) , INTENT(IN) :: fillvalue INTEGER , INTENT(OUT) :: hdferrInputs:
prp_id - Property list identifier type_id - Datatype identifier of fill value datatype (in memory) fillvalue - Fillvalue
Outputs:
hdferr - Returns 0 if successful and -1 if fails
- Fortran2003 Interface: h5pset_fill_value_f
-
Signature:
SUBROUTINE h5pset_fill_value_f(prp_id, type_id, fillvalue, hdferr) INTEGER(HID_T), INTENT(IN) :: prp_id INTEGER(HID_T), INTENT(IN) :: type_id TYPE(C_PTR) , INTENT(IN) :: fillvalue INTEGER , INTENT(OUT) :: hdferrInputs:
prp_id - Property list identifier type_id - Datatype identifier of fill value datatype (in memory) fillvalue - Fillvalue
Outputs:
hdferr - Returns 0 if successful and -1 if fails
- History:
Release Change 1.8.8 Fortran updated to Fortran2003.
- Last modified: 30 April 2014
- Name: H5Pset_filter
- Signature:
- Name: H5Pset_filter
- herr_t
H5Pset_filter(hid_tplist_id, H5Z_filter_tfilter_id, unsigned intflags, size_tcd_nelmts, const unsigned intcd_values[]) - Purpose:
- Adds a filter to the filter pipeline.
- Description:
H5Pset_filteradds the specifiedfilter_idand corresponding properties to the end of an output filter pipeline.plist_id must be either a dataset creation property list or group creation property list identifier. If
plist_idis a dataset creation property list identifier, the filter is added to the raw data filter pipeline.If
plist_idis a group creation property list identifier, the filter is added to the link filter pipeline, which filters the fractal heap used to store the most of link metadata in certain types of groups. The only predefined filters that can be set in a group creation property list are the gzip filter (H5Z_FILTER_DEFLATE) and the Fletcher32 error detection filter (H5Z_FILTER_FLETCHER32).The array
cd_valuescontainscd_nelmtsintegers which are auxiliary data for the filter. The integer values will be stored in the dataset object header as part of the filter information.The
flagsargument is a bit vector with the following fields specifying certain general properties of the filter:H5Z_FLAG_OPTIONALIf this bit is set then the filter is optional. If the filter fails (see below) during an H5Dwriteoperation then the filter is just excluded from the pipeline for the chunk for which it failed; the filter will not participate in the pipeline during anH5Dreadof the chunk. This is commonly used for compression filters: if the filter result would be larger than the input, then the compression filter returns failure and the uncompressed data is stored in the file.This flag should not be set for the Fletcher32 checksum filter as it will bypass the checksum filter without reporting checksum errors to an application.
H5Z_FLAG_MANDATORYIf the filter is required, that is, set to mandatory, and the filter fails, the library’s behavior depends on whether the chunk cache is in use: - If the chunk cache is enabled, data chunks will be
flushed to the file during
H5Dcloseand the library will return the failure inH5Dclose. - When the chunk cache is disabled or not big enough,
or the chunk is being evicted from the cache,
the failure will happen during
H5Dwrite.
For example, assume that an application creates a dataset of four chunks, the chunk cache is enabled and is big enough to hold all four chunks, and the filter fails when it tries to write the fourth chunk. The actual flush of the chunks will happen during
H5Dclose, notH5Dwrite. By the timeH5Dclosefails, the first three chunks will have been written to the file. Even thoughH5Dclosefails, all the resources will be released and the file can be closed properly.If, however, the filter fails on the second chunk, only the first chunk will be written to the file as nothing further can be written once the filter fails.
The
filter_idparameter specifies the filter to be set. Valid pre-defined filter identifiers are as follows:H5Z_FILTER_DEFLATEData compression filter, employing the gzip algorithm H5Z_FILTER_SHUFFLEData shuffling filter H5Z_FILTER_FLETCHER32Error detection filter, employing the Fletcher32 checksum algorithm H5Z_FILTER_SZIPData compression filter, employing the SZIP algorithm H5Z_FILTER_NBITData compression filter, employing the N-Bit algorithm H5Z_FILTER_SCALEOFFSETData compression filter, employing the scale-offset algorithm Also see
H5Pset_edc_checkandH5Pset_filter_callback.- If the chunk cache is enabled, data chunks will be
flushed to the file during
- Notes:
- When a non-empty filter pipeline is used with a group creation property
list, the group will be created with the new group file format (see
“Group Implementations
in HDF5”). The filters will come into play only when dense
storage is used (see
H5Pset_link_phase_change) and will be applied to the group’s fractal heap. The fractal heap will contain most of the the group’s link metadata, including link names.When working with group creation property lists, if you are adding a filter that is not in HDF5’s set of predefined filters, i.e., a user-defined or third-party filter, you must first determine that the filter will work for a group. See the discussion of the set local and can apply callback functions in
H5Zregister.If multiple filters are set for a property list, they will be applied to each chunk of raw data for datasets or each block of the fractal heap for groups in the order in which they were set.
Filters can be applied only to chunked datasets; they cannot be used with other dataset storage methods, such as contiguous, compact, or external datasets.
Dataset elements of variable-length and dataset region reference datatypes are stored in separate structures in the file called heaps. Filters cannot currently be applied to these heaps.
Filter Behavior in HDF5:
Filters can be inserted into the HDF5 pipeline to perform functions such as compression and conversion. As such, they are a very flexible aspect of HDF5; for example, a user-defined filter could provide encryption for an HDF5 dataset.A filter can be declared as either required or optional. Required is the default status; optional status must be explicitly declared.
A required filter that fails or is not defined causes an entire output operation to fail; if it was applied when the data was written, such a filter will cause an input operation to fail.
The following table summarizes required filter behavior.
Required FILTER_X
not availableFILTER_X available H5Pset_<FILTER_X>Will fail.
Will succeed. H5Dwrite
with FILTER_X setWill fail. Will succeed; FILTER_X will be applied to the data. H5Dread
with FILTER_X setWill 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_OPTIONALflag withH5Pset_filter.Consider a situation where one is creating files that will normally be used only on systems where the optional (and fictional) filter FILTER_Z is routinely available. One can create those files on system A, which lacks FILTER_Z, create chunked datasets in the files with FILTER_Z defined in the dataset creation property list, and even write data to those datasets. The dataset object header will indicate that FILTER_Z has been associated with this dataset. But since system A does not have FILTER_Z, dataset chunks will be written without it being applied.
HDF5 has a mechanism for determining whether chunks are actually written with the filters specified in the object header, so while the filter remains unavailable, system A will be able to read the data. Once the file is moved to system B, where FILTER_Z is available, HDF5 will apply FILTER_Z to any data rewritten or new data written in these datasets. Dataset chunks that have been written on system B will then be unreadable on system A; chunks that have not been re-written since being written on system A will remain readable on system A. All chunks will be readable on system B.
The following table summarizes optional filter behavior.
FILTER_Z
not availableFILTER_Z available
with encode and decodeFILTER_Z available
decode onlyH5Pset_<FILTER_Z>Will succeed.
Will succeed. Will succeed. H5Dwrite
with FILTER_Z setWill succeed;
FILTER_Z will not be applied to the data.Will succeed;
FILTER_Z will be applied to the data.Will succeed;
FILTER_Z will not be applied to the data.H5Dread
with FILTER_Z setWill 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_szipfor details.) - See Also:
-
For a discussion of the chunk cache, see
H5Pset_cache.For a discussion of the various types of HDF5 groups, see “Group Implementations in HDF5.”
Related functions:
H5Pset_link_phase_change,H5Pset_edc_check,H5Pset_filter_callback,H5Pset_deflate,H5Pset_shuffle,H5Pset_fletcher32,H5Pset_szip,H5Pset_nbit,H5Pset_scaleoffset - Parameters:
hid_t plist_idIN: Dataset or group creation property list identifier. H5Z_filter_t filter_idIN: Filter identifier for the filter to be added to the pipeline. unsigned int flagsIN: Bit vector specifying certain general properties of the filter. size_t cd_nelmtsIN: Number of elements in cd_values.const unsigned int cd_values[]IN: Auxiliary data for the filter. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_filter_f
-
SUBROUTINE h5pset_filter_f(prp_id, filter, flags, cd_nelmts, cd_values, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Gropu or dataset creation property ! list identifier INTEGER, INTENT(IN) :: filter ! Filter to be added to the pipeline INTEGER, INTENT(IN) :: flags ! Bit vector specifying certain ! general properties of the filter INTEGER(SIZE_T), INTENT(IN) :: cd_nelmts ! Number of elements in cd_values INTEGER, DIMENSION(*), INTENT(IN) :: cd_values ! Auxiliary data for the filter INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_filter_f - History:
Release Change 1.6.0 Function introduced in this release. 1.8.5 Function applied to group creation property lists.
- Name: H5Pset_filter_callback
- Signature:
- herr_t
H5Pset_filter_callback(hid_tplist, H5Z_filter_func_tfunc, void *op_data) - Purpose:
- Sets user-defined filter callback function.
- Description:
H5Pset_filter_callbacksets the user-defined filter callback functionfuncin the dataset transfer property listplist.The parameter
op_datais a pointer to user-defined input data for the callback function and will be passed through to the callback function.The callback function
funcdefines the actions an application is to take when a filter fails. The function prototype is as follows:typedefH5Z_cb_return_t (H5Z_filter_func_t) (H5Z_filter_tfilter_id, void *buf, size_tbuf_size, void *op_data)where
filter_idindicates which filter has failed,bufandbuf_sizeare used to pass in the failed data, andop_datais the required input data for this callback function.Valid callback function return values are
H5Z_CB_FAILandH5Z_CB_CONT.- Parameters:
hid_t plistIN: Dataset transfer property list identifier. H5Z_filter_func_t funcIN: User-defined filter callback function. void * op_dataIN: User-defined input data for the callback function. - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface:
- None.
- History:
Release C 1.6.0 Function introduced in this release.
- Last modified: 14 June 2010
- Name: H5Pset_fletcher32
- Signature:
- Name: H5Pset_fletcher32
- herr_t
H5Pset_fletcher32( hid_tplist_id) - Purpose:
- Sets up use of the Fletcher32 checksum filter.
- Description:
H5Pset_fletcher32sets the Fletcher32 checksum filter in the dataset or group creation property listplist_id.- Note:
- The Fletcher32 EDC checksum filter was added in HDF5 Release 1.6.0.
In the original implementation, however, the checksum value was
calculated incorrectly on little-endian systems.
The error was fixed in HDF5 Release 1.6.3.
As a result of this fix, an HDF5 Library of Release 1.6.0 through Release 1.6.2 cannot read a dataset created or written with Release 1.6.3 or later if the dataset was created with the checksum filter and the filter is enabled in the reading library. (Libraries of Release 1.6.3 and later understand the earlier error and comensate appropriately.)
Work-around: An HDF5 Library of Release 1.6.2 or earlier will be able to read a dataset created or written with the checksum filter by an HDF5 Library of Release 1.6.3 or later if the checksum filter is disabled for the read operation. This can be accomplished via a call to
H5Pset_edc_checkwith the valueH5Z_DISABLE_EDCin the second parameter. This has the obvious drawback that the application will be unable to verify the checksum, but the data does remain accessible. - Parameters:
hid_t plist_idIN: Dataset or group creation property list identifier. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_fletcher32_f
-
SUBROUTINE h5pset_fletcher32_f(prp_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_fletcher32_f - History:
Release Change 1.6.0 Function introduced in this release. 1.6.3 Error in checksum calculation on little-endian systems corrected in this release. 1.8.5 Function extended to work with group creation property lists.
- Name: H5Pset_gc_references
- Signature:
- herr_t
H5Pset_gc_reference(hid_tplist, unsignedgc_ref) - Purpose:
- Sets garbage collecting references flag.
- Description:
H5Pset_gc_referencessets the flag for garbage collecting references for the file.Dataset region references and other reference types use space in an HDF5 file's global heap. If garbage collection is on and the user passes in an uninitialized value in a reference structure, the heap might get corrupted. When garbage collection is off, however, and the user re-uses a reference, the previous heap block will be orphaned and not returned to the free heap space.
When garbage collection is on, the user must initialize the reference structures to 0 or risk heap corruption.
The default value for garbage collecting references is off.
- Parameters:
hid_t plistIN: File access property list identifier. unsigned gc_refIN: Flag setting reference garbage collection to on ( 1) or off (0).- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_gc_references_f
-
SUBROUTINE h5pset_gc_references_f (prp_id, gc_reference, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(IN) :: gc_reference ! Flag for garbage collecting ! references for the file INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_gc_references_f
- Name: H5Pset_hyper_vector_size
- Signature:
- herr_t
H5Pset_hyper_vector_size(hid_tdxpl_id, size_tvector_size) - Purpose:
- Sets number of I/O vectors to be read/written in hyperslab I/O.
- Description:
H5Pset_hyper_vector_sizesets the number of I/O vectors to be accumulated in memory before being issued to the lower levels of the HDF5 library for reading or writing the actual data.The I/O vectors are hyperslab offset and length pairs and are generated during hyperslab I/O.
The number of I/O vectors is passed in
vector_sizeto be set in the dataset transfer property listdxpl_id.vector_sizemust be greater than1(one).H5Pset_hyper_vector_sizeis an I/O optimization function; increasingvector_sizeshould provide better performance, but the library will use more memory during hyperslab I/O. The default value ofvector_sizeis1024.- Parameters:
hid_t dxpl_idIN: Dataset transfer property list identifier. size_t vector_sizeIN: Number of I/O vectors to accumulate in memory for I/O operations. Must be greater than 1(one). Default value:1024.- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_hyper_vector_size_f
-
SUBROUTINE h5pset_hyper_vector_size_f(plist_id, size, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset transfer property list ! identifier INTEGER(SIZE_T), INTENT(IN) :: size ! Vector size INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_hyper_vector_size_f - History:
Release C 1.6.0 Function introduced in this release.
- Last modified: 7 March 2013
- Name: H5Pset_istore_k
- Signature:
- Name: H5Pset_istore_k
- herr_t
H5Pset_istore_k( hid_tfcpl_id, unsignedik) - Purpose:
- Sets the size of the parameter used to control the
B-trees for indexing chunked datasets.
- Description:
H5Pset_istore_ksets the size of the parameter used to control the B-trees for indexing chunked datasets. This function is valid only for file creation property lists.ikis one half the rank of a tree that stores chunked raw data. On average, such a tree will be 75% full, or have an average rank of 1.5 times the value ofik.The HDF5 library uses
(ik*2)as the maximum # of entries before splitting a B-tree node. Since only 2 bytes are used in storing # of entries for a B-tree node in an HDF5 file,(ik*2)cannot exceed65536. The default value forikis32.- Parameters:
hid_t fcpl_idIN: File creation property list identifier unsigned ikIN: 1/2 rank of chunked storage B-tree - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_istore_k_f
-
SUBROUTINE h5pset_istore_k_f (prp_id, ik, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(IN) :: ik ! 1/2 rank of chunked storage B-tree INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_istore_k_f - History:
Release C 1.6.4 ikparameter type changed to unsigned.
- Last modified: 11 May 2011
- Name: H5Pset_layout
- Signature:
- Name: H5Pset_layout
- herr_t
H5Pset_layout( hid_tplist, H5D_layout_tlayout) - Purpose:
- Sets the type of storage used to store the raw data for a dataset.
- Description:
H5Pset_layoutsets the type of storage used to store the raw data for a dataset. This function is only valid for dataset creation property lists.Valid values for
layoutare:- H5D_COMPACT
- Store raw data in the dataset object header in file. This should only be used for datasets with small amounts of raw data. The raw data size limit is 64K (65520 bytes). Attempting to create a dataset with raw data larger than this limit will cause the H5Dcreate call to fail.
- H5D_CONTIGUOUS
- Store raw data separately from the object header in one large chunk in the file.
- H5D_CHUNKED
- Store raw data separately from the object header as chunks of data in separate locations in the file.
Note that a compact storage layout may affect writing data to the dataset with parallel applications. See note in H5Dwrite documentation for details.
- Parameters:
hid_t plistIN: Identifier of property list to query. H5D_layout_t layoutIN: Type of storage layout for raw data. - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_layout_f
-
SUBROUTINE h5pset_layout_f (prp_id, layout, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(IN) :: layout ! Type of storage layout for raw data ! Possible values are: ! H5D_COMPACT_F ! H5D_CONTIGUOUS_F ! H5D_CHUNKED_F INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_layout_f
- Last modified: 7 January 2011
- Name: H5Pset_libver_bounds
- Signature:
- Name: H5Pset_libver_bounds
- herr_t
H5Pset_libver_bounds( hid_tfapl_id, H5F_libver_tlibver_low, H5F_libver_tlibver_high) - Purpose:
- Sets bounds on library versions, and indirectly format versions,
to be used when creating objects.
- Description:
H5Pset_libver_boundscontrols the versions of the object formats that will be used when creating objects in a file. The object format versions are determined indirectly from the HDF5 Library versions specified in the call.This property is set in the file access property list specified by
fapl_id.When bounds have been set through an
H5Pset_libver_boundscall, a function that creates an object will fail if the object cannot be created within the boundaries set inlibver_lowandlibver_high.- Parameters:
hid_t fapl_idIN: File access property list identifier H5F_libver_t libver_lowIN: The earliest version of the library that will be used for writing objects, indirectly specifying the earliest object format version that can be used when creating objects in the file. Valid values of
libver_loware as follows:H5F_LIBVER_EARLIEST(Default)H5F_LIBVER_18H5F_LIBVER_LATESTSetting
libver_lowtoH5F_LIBVER_EARLIESTwill result in objects being created using the earliest possible format for each object. Note that earliest possible is different from earliest, as some features introduced in library versions later than 1.0.0 resulted in updates to object formats. Withlibver_low=H5F_LIBVER_EARLIEST, if the application creates an object that requires a feature introduced in library versions later than 1.0.0, the earliest possible version that supports the requested feature will be used.Setting
libver_lowtoH5F_LIBVER_LATESTwill result in objects being created using the latest available format for each object. This setting means that objects will be created with the latest format versions available (within the range of library versions specified in the call), and can take advantage of the latest features and performance enhancements. Objects written with theH5F_LIBVER_LATESTsetting forlibver_lowmay be accessible to a smaller range of library versions than would be the case if theH5F_LIBVER_EARLIESTvalue had been used.Setting
libver_lowto the intermediate valueH5F_LIBVER_18specifies that created or modifed objects must be readable by the HDF5 Release 1.8 series but do not need to be readable by earlier versions.H5F_libver_t libver_highIN: The latest version of the library that will be used for writing objects, indirectly specifying the latest object format version that can be used when creating objects in the file. Valid values of
libver_highare as follows:H5F_LIBVER_18H5F_LIBVER_LATEST(Default)H5F_LIBVER_18specifies that objects may be created in a format used by releases up to and including the HDF5 Release 1.8 series. Object formats introduced in later releases may not be used.H5F_LIBVER_LATESTspecifies that objects may be created in the latest format available; there is no requirement that earlier versions of the HDF5 library be able to read all objects in the file.- Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_libver_bounds_f
SUBROUTINE h5pset_libver_bounds_f(fapl_id, low, high, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: fapl_id ! File access property list identifier INTEGER, INTENT(IN) :: low ! The earliest version of the library that ! will be used for writing objects. ! Currently, low must be either: ! H5F_LIBVER_EARLIEST_F ! H5F_LIBVER_LATEST_F INTEGER, INTENT(IN) :: high ! The latest version of the library that will be ! used for writing objects. ! Currently, high must set to: ! H5F_LIBVER_LATEST_F INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_libver_bounds_f- History:
Release C 1.8.0 Function introduced in this release. 1.8.6 H5F_LIBVER_18version boundary setting added in this release.
- Last modified: 22 March 2012
- Name: H5Pset_link_creation_order
- Signature:
- Name: H5Pset_link_creation_order
- herr_t
H5Pset_link_creation_order( hid_tgcpl_id, unsignedcrt_order_flags) - Purpose:
- Sets creation order tracking and indexing for links in a group.
- Description:
H5Pset_link_creation_ordersets flags for tracking and indexing links on creation order in groups created with the group creation property listgcpl_id.crt_order_flagscontains flags with the following meanings:
Default behavior is that link creation order is neither tracked nor indexed.H5P_CRT_ORDER_TRACKEDLink creation order is tracked but not necessarily indexed. H5P_CRT_ORDER_INDEXEDLink creation order is indexed (requires H5P_CRT_ORDER_TRACKED).H5Pset_link_creation_ordercan be used to set link creation order tracking, or to set link creation order tracking and indexing.Note that if a creation order index is to be built, it must be specified in the group creation property list. HDF5 currently provides no mechanism to turn on link creation order tracking at group creation time and to build the index later.
- Parameters:
hid_t gcpl_idIN: Group creation property list identifier unsigned crt_order_flagsIN: Creation order flag(s) - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_link_creation_order_f
SUBROUTINE h5pset_link_creation_order_f(gcpl_id, crt_order_flags, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: gcpl_id ! File access property list identifier INTEGER, INTENT(IN) :: crt_order_flags ! Creation order flag(s): ! H5P_CRT_ORDER_TRACKED_F ! H5P_CRT_ORDER_INDEXED_F INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_link_creation_order_f- History:
Release C 1.8.0 Function introduced in this release.
- Name: H5Pset_link_phase_change
- Signature:
- herr_t
H5Pset_link_phase_change( hid_tgcpl_id, unsignedmax_compact, unsignedmin_dense) - Purpose:
- Sets the parameters for conversion between compact and dense groups.
- Description:
H5Pset_link_phase_changesets the maximum number of entries for a compact group and the minimum number of links to allow before converting a dense group to back to the compact format.max_compactis the maximum number of links to store as header messages in the group header as before converting the group to the dense format. Groups that are in compact format and in which the exceed this number of links rises above this threshold are automatically converted to dense format.min_denseis the minimum number of links to store in the dense format. Groups which are in dense format and in which the number of links falls below this theshold are automatically converted to compact format.See “Group implementations in HDF5” in the H5G API introduction for a discussion of the available types of HDF5 group structures.
- Parameters:
hid_t gcpl_idIN: Group creation property list identifier unsigned max_compactIN: Maximum number of links for compact storage
(Default: 8)unsigned min_denseIN: Minimum number of links for dense storage
(Default: 6)- Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_link_phase_change_f
SUBROUTINE h5pset_link_phase_change_f(gcpl_id, max_compact, min_dense, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list id INTEGER, INTENT(IN) :: max_compact ! Maximum number of attributes to be ! stored in compact storage INTEGER, INTENT(IN) :: min_dense ! Minimum number of attributes to be ! stored in dense storage INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_link_phase_change_f- History:
Release C 1.8.0 Function introduced in this release.
- Name: H5Pset_local_heap_size_hint
- Signature:
- herr_t
H5Pset_local_heap_size_hint( hid_tgcpl_id, size_tsize_hint) - Purpose:
- Specifies the anticipated maximum size of a local heap.
- Description:
H5Pset_local_heap_size_hintis used with original-style HDF5 groups (see “Motivation” below) to specify the anticipated maximum local heap size,size_hint, for groups created with the group creation property listgcpl_id. The HDF5 Library then usessize_hintto allocate contiguous local heap space in the file for each group created withgcpl_id.For groups with many members or very few members, an appropriate initial value of
size_hintwould be the anticipated number of group members times the average length of group member names, plus a small margin:size_hint = max_number_of_group_members * (average_length_of_group_member_link_names + 2)If it is known that there will be groups with zero members, the use of a group creation property list with
size_hintset to to1(one) will guarantee the smallest possible local heap for each of those groups.Setting
size_hintto zero (0) causes the library to make a reasonable estimate for the default local heap size.- Motivation:
- In situations where backward-compatibility is required, specifically,
when libraries prior to HDF5 Release 1.8.0 may be used to read the file,
groups must be created and maintained in the original style.
This is HDF5’s default behavior.
If backward compatibility with pre-1.8.0 libraries is not a concern,
greater efficiencies can be obtained with the new-format compact and
indexed groups.
See “Group
implementations in HDF5” in the H5G API introduction.
H5Pset_local_heap_size_hintis useful for tuning file size when files contain original-style groups with either zero members or very large numbers of members.The original style of HDF5 groups, the only style available prior to HDF5 Release 1.8.0, was well-suited for moderate-sized groups but was not optimized for either very small or very large groups. This original style remains the default, but two new group implementations were introduced in HDF5 Release 1.8.0: compact groups to accomodate zero to small numbers of members and indexed groups for thousands or tens of thousands of members ... or millions, if that's what your application requires.
The local heap size hint,
size_hint, is a performance tuning parameter for original-style groups. As indicated above, an HDF5 group may have zero, a handful, or tens of thousands of members. Since the original style of HDF5 groups stores the metadata for all of these group members in a uniform format in a local heap, the size of that metadata (and hence, the size of the local heap) can vary wildly from group to group. To intelligently allocate space and to avoid unnecessary fragmentation of the local heap, it can be valuable to provide the library with a hint as to the local heap’s likely eventual size. This can be particularly valuable when it is known that a group will eventually have a great many members. It can also be useful in conserving space in a file when it is known that certain groups will never have any members. - Parameters:
hid_t gcpl_idIN: Group creation property list identifier size_t size_hintIN: Anticipated maximum size in bytes of local heap - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_local_heap_size_hint_f
-
SUBROUTINE h5pset_local_heap_size_hint_f(gcpl_id, size_hint, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: gcpl_id ! Group creation property list id INTEGER(SIZE_T), INTENT(IN) :: size_hint ! Hint for size of local heap INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_local_heap_size_hint_f - History:
Release Change 1.8.0 Function introduced in this release.
- Last modified: 22 August 2012
- Name: H5Pset_mcdt_search_cb
- Signature:
- Name: H5Pset_mcdt_search_cb
- herr_t
H5Pset_mcdt_search_cb( hid_tocpypl_id, H5O_mcdt_search_cb_tfunc, void *op_data) - Purpose:
- Sets the callback function that
H5Ocopywill invoke before searching the entire destination file for a matching committed datatype. - Motivation:
H5Pset_mcdt_search_cbprovides the means to define a callback function. An application can then use that callback to take an additional action before the default search of all committed datatypes in the destination file or to take an action that replaces the default search. This mechanism is intended to improve performance when the global search might take a long time.- Description:
H5Pset_mcdt_search_cballows an application to set a callback function,func, that will be invoked before searching the destination file for a matching committed datatype. The default, global search process is described inH5Padd_merge_committed_dtype_path.The callback function must conform to the
H5O_mcdt_search_cb_tprototype and will return an instruction for one of the following actions:- Continue the search for a matching committed datatype in the destination file.
- Discontinue the search for a matching committed datatype.
H5Ocopywill then apply the default behavior of creating an anonymous committed datatype. - Abort the copy operation and exit
H5Ocopy.
- Warning:
- If the callback function return value causes
H5Ocopyto abort, the destination file may be left in an inconsistent or corrupted state. - Programming Note for C++ Developers Using C Functions:
-
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cbandH5Pset_type_conv_cband functions such asH5TconvertandH5Ewalk2.Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
- Parameters:
hid_t ocpypl_idIN: Object copy property list identifier H5O_mcdt_search_cb_t funcIN: User-defined callback function void * op_dataIN: User-defined input data for the callback function - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Failure Modes:
H5Pset_mcdt_search_cbwill fail if the object copy property list is invalid.- Example Usage:
- This example defines a callback function in the object copy property list.
/* The user-defined callback function */ static H5O_mcdt_search_ret_t mcdt_search_cb(void *_udata) { H5O_mcdt_search_ret_t action = *((H5O_mcdt_search_ret_t *)_udata); return(action); } int main(void) { hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY); /* Enable the merging committed datatype feature. */ H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG); /* Add a path to search for a matching committed datatype. */ H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA"); /* * Set the callback function to discontinue the global search * if H5Ocopy cannot find a matching committed datatype from the * above suggested path. */ action = H5O_MCDT_SEARCH_STOP; H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action); H5Ocopy(...ocpypl_id...); ... ... } - See Also:
H5Ocopy
H5Pset_copy_objectH5Padd_merge_committed_dtype_path
H5Pget_mcdt_search_cb
H5O_mcdt_search_cb_t
Copying Committed Datatypes
withH5Ocopy
A comprehensive discussion of copying committed datatypes (PDF) in Advanced Topics in HDF5- History:
Release Change 1.8.9 C function introduced in this release.
- Last modified: 18 May 2009
- Name: H5Pset_mdc_config
- Signature:
- Name: H5Pset_mdc_config
- herr_t
H5Pset_mdc_config(hid_tplist_id, H5AC_cache_config_t *config_ptr) - Purpose:
- Set the initial metadata cache configuration in the indicated File Access Property List to the supplied value.
- Description:
- H5Pset_mdc_config attempts to set the initial metadata cache configuration
to the supplied value. It will fail if an invalid configuration is detected.
This configuration is used when the file is opened.
See the overview of the metadata cache in the special topics section of the user manual for details on what is being configured. If you haven't read and understood that documentation, you really shouldn't be using this API call.
- Parameters:
hid_t plist_idIN: Identifier of the file access property list. H5AC_cache_config_t * config_ptrIN: Pointer to the instance of H5AC_cache_config_t containing the desired configuration. The fields of this structure are discussed below: General configuration section: int versionIN: 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_enabledIN: 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_fileIN: Boolean field indicating whether the trace_file_namefield should be used to open a trace file for the cache.The trace file is a debuging feature that allows the capture of top level metadata cache requests for purposes of debugging and/or optimization. This field should normally be set to
FALSE, as trace file collection imposes considerable overhead.This field should only be set to
TRUEwhen thetrace_file_namecontains the full path of the desired trace file, and either there is no open trace file on the cache, or theclose_trace_filefield is alsoTRUE.The trace file feature is unsupported unless used at the direction of THG. It is intended to allow THG to collect a trace of cache activity in cases of occult failures and/or poor performance seen in the field, so as to aid in reproduction in the lab. If you use it absent the direction of THG, you are on your own.
hbool_t close_trace_fileIN: Boolean field indicating whether the current trace file (if any) should be closed. See the above comments on the
open_trace_filefield. This field should be set toFALSEunless there is an open trace file on the cache that you wish to close.The trace file feature is unsupported unless used at the direction of THG. It is intended to allow THG to collect a trace of cache activity in cases of occult failures and/or poor performance seen in the field, so as to aid in reproduction in the lab. If you use it absent the direction of THG, you are on your own.
char trace_file_name[]IN: Full path of the trace file to be opened if the open_trace_filefield isTRUE.In the parallel case, an ascii representation of the MPI rank of the process will be appended to the file name to yield a unique trace file name for each process.
The length of the path must not exceed
H5AC__MAX_TRACE_FILE_NAME_LENcharacters.The trace file feature is unsupported unless used at the direction of THG. It is intended to allow THG to collect a trace of cache activity in cases of occult failures and/or poor performance seen in the field, so as to aid in reproduction in the lab. If you use it absent the direction of THG, you are on your own.
hbool_t evictions_enabledIN: A boolean flag indicating whether evictions from the metadata cache are enabled. This flag is initially set to TRUE.In rare circumstances, the raw data throughput requirements may be so high that the user wishes to postpone metadata writes so as to reserve I/O throughput for raw data. The
evictions_enabledfield exists to allow this. However, this is an extreme step, and you have no business doing it unless you have read the User Guide section on metadata caching, and have considered all other options carefully.The
evictions_enabledfield may not be set toFALSEunless all adaptive cache resizing code is disabled via theincr_mode,flash_incr_mode, anddecr_modefields.When this flag is set to
FALSE, the metadata cache will not attempt to evict entries to make space for new entries, and thus will grow without bound.Evictions will be re-enabled when this field is set back to
TRUE. This should be done as soon as possible.hbool_t set_initial_sizeIN: Boolean flag indicating whether the cache should be created with a user specified initial size. size_t initial_sizeIN: If set_initial_size is TRUE, initial_size must contains the desired initial size in bytes. This value must lie in the closed interval [min_size, max_size]. (see below) double min_clean_fractionIN: This field specifies the minimum fraction of the cache that must be kept either clean or empty. The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to start in the serial case. In the parallel case, a larger value is needed -- see the overview of the metadata cache in the “ Metadata Caching in HDF5” section of the HDF5 User’s Guide for details.
size_t max_sizeIN: 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_sizeIN: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select as the maximum cache size. long int epoch_lengthIN: Number of cache accesses between runs of the adaptive cache resize code. 50,000 is a good starting number. Increment configuration section: enum H5C_cache_incr_mode incr_mode
IN: Enumerated value indicating the operational mode of the automatic cache size increase code. At present, only two values are legal:H5C_incr__off: Automatic cache size increase is disabled, and the remaining increment fields are ignored.
H5C_incr__threshold: Automatic cache size increase is enabled using the hit rate threshold algorithm.
double lower_hr_thresholdIN: Hit rate threshold used by the hit rate threshold cache size increment algorithm. When the hit rate over an epoch is below this threshold and the cache is full, the maximum size of the cache is multiplied by increment (below), and then clipped as necessary to stay within max_size, and possibly max_increment.
This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good place to start.
double incrementIN: Factor by which the hit rate threshold cache size increment algorithm multiplies the current cache max size to obtain a tentative new cache size. The actual cache size increase will be clipped to satisfy the max_size specified in the general configuration, and possibly max_increment below.
The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable value.
If you set it to 1.0, you will effectively disable cache size increases.
hbool_t apply_max_incrementIN: Boolean flag indicating whether an upper limit should be applied to the size of cache size increases. size_t max_incrementIN: Maximum number of bytes by which cache size can be increased in a single step -- if applicable. enum H5C_cache_flash_incr_mode flash_incr_modeIN: 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_thresholdIN: The factor by which the current maximum cache size is multiplied to obtain the minimum size entry / entry size increase which may trigger a flash cache size increase. At present, this value must lie in the range [0.1, 1.0].
double flash_multipleIN: 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_sizefield above.At present, this field must lie in the range [0.1, 10.0].
Decrement configuration section: enum H5C_cache_decr_mode decr_modeIN: Enumerated value indicating the operational mode of the automatic cache size decrease code. At present, the following values are legal: H5C_decr__off: Automatic cache size decrease is disabled.
H5C_decr__threshold: Automatic cache size decrease is enabled using the hit rate threshold algorithm.
H5C_decr__age_out: Automatic cache size decrease is enabled using the ageout algorithm.
H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the ageout with hit rate threshold algorithm
double upper_hr_thresholdIN: Hit rate threshold for the hit rate threshold and ageout with hit rate threshold cache size decrement algorithms. When decr_mode is H5C_decr__threshold, and the hit rate over a given epoch exceeds the supplied threshold, the current maximum cache size is multiplied by decrement to obtain a tentative new (and smaller) maximum cache size.
When decr_mode is H5C_decr__age_out_with_threshold, there is no attempt to find and evict aged out entries unless the hit rate in the previous epoch exceeded the supplied threshold.
This field must lie in the interval [0.0, 1.0].
For H5C_incr__threshold, .9995 or .99995 is a good place to start.
For H5C_decr__age_out_with_threshold, .999 might be more useful.
double decrementIN: In the hit rate threshold cache size decrease algorithm, this parameter contains the factor by which the current max cache size is multiplied to produce a tentative new cache size. The actual cache size decrease will be clipped to satisfy the min_size specified in the general configuration, and possibly max_decrement below.
The parameter must be be in the interval [0.0, 1.0].
If you set it to 1.0, you will effectively disable cache size decreases. 0.9 is a reasonable starting point.
hbool_t apply_max_decrementIN: Boolean flag indicating whether an upper limit should be applied to the size of cache size decreases. size_t max_decrementIN: Maximum number of bytes by which the maximum cache size can be decreased in any single step -- if applicable. int epochs_before_evictionIN: In the ageout based cache size reduction algorithms, this field contains the minimum number of epochs an entry must remain unaccessed in cache before the cache size reduction algorithm tries to evict it. 3 is a reasonable value. hbool_t apply_empty_reserveIN: Boolean flag indicating whether the ageout based decrement algorithms will maintain a empty reserve when decreasing cache size. double empty_reserveIN: Empty reserve as a fraction of maximum cache size if applicable. When so directed, the ageout based algorithms will not decrease the maximum cache size unless the empty reserve can be met.
The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to start.
Parallel configuration section: int dirty_bytes_thresholdIN: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the metadata caches serving the target file in the parallel case. Synchronization occurs whenever the number of bytes of dirty metadata created since the last synchronization exceeds this limit.
This field only applies to the parallel case. While it is ignored elsewhere, it can still draw a value out of bounds error.
It must be consistant across all caches on any given file.
By default, this field is set to 256 KB. It shouldn't be more than half the current max cache size times the min clean fraction.
- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Name: H5Pset_meta_block_size
- Signature:
- herr_t
H5Pset_meta_block_size( hid_tfapl_id, hsize_tsize) - Purpose:
- Sets the minimum metadata block size.
- Description:
H5Pset_meta_block_sizesets the minimum size, in bytes, of metadata block allocations whenH5FD_FEAT_AGGREGATE_METADATAis set by a VFL driver.Each raw metadata block is initially allocated to be of the given size. Specific metadata objects (e.g., object headers, local heaps, B-trees) are then sub-allocated from this block.
The default setting is 2048 bytes, meaning that the library will attempt to aggregate metadata in at least 2K blocks in the file. Setting the value to
0(zero) with this function will turn off metadata aggregation, even if the VFL driver attempts to use the metadata aggregation strategy.Metadata aggregation reduces the number of small data objects in the file that would otherwise be required for metadata. The aggregated block of metadata is usually written in a single write action and always in a contiguous block, potentially significantly improving library and application performance.
- Parameters:
hid_t fapl_idIN: File access property list identifier. hsize_t sizeIN: Minimum size, in bytes, of metadata block allocations. - Returns:
- Returns a non-negative value if successful. Otherwise returns a negative value.
- Fortran90 Interface: h5pset_meta_block_size_f
-
SUBROUTINE h5pset_meta_block_size_f(plist_id, size, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list ! identifier INTEGER(HSIZE_T), INTENT(IN) :: size ! Metadata block size INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_meta_block_size_f - History:
Release C 1.4.0 Function introduced in this release.
- Name: H5Pset_multi_type
- Signature:
- herr_t
H5Pset_multi_type( hid_tfapl_id, H5FD_mem_ttype) - Purpose:
- Specifies type of data to be accessed via the
MULTIdriver, enabling more direct access. - Description:
H5Pset_multi_typesets the type of data property in the file access property listfapl_id.This setting enables a user application to specify the type of data the application wishes to access so that the application can retrieve a file handle for low-level access to the particular member of a set of
MULTIfiles in which that type of data is stored. The file handle is retrieved with a separate call toH5Fget_vfd_handle(or, in special circumstances, toH5FDget_vfd_handle; see Virtual File Layer and List of VFL Functions in HDF5 Technical Notes).The type of data specified in
typemay be one of the following:H5FD_MEM_SUPERSuper block data H5FD_MEM_BTREEB-tree data H5FD_MEM_DRAWDataset raw data H5FD_MEM_GHEAPGlobal heap data H5FD_MEM_LHEAPLocal Heap data H5FD_MEM_OHDRObject header data This function is for use only when accessing an HDF5 file written as a set of files with the
MULTIfile driver.- Parameters:
hid_t fapl_idIN: File access property list identifier. H5FD_mem_t typeIN: Type of data to be accessed. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface:
- None.
- History:
Release Change 1.6.0 C function introduced in this release.
- Last modified: 26 October 2011
- Name: H5Pset_nbit
- Signature:
- Name: H5Pset_nbit
- herr_t
H5Pset_nbit( hid_tplist_id) - Purpose:
- Sets up the use of the N-Bit filter.
- Description:
H5Pset_nbitsets the N-Bit filter,H5Z_FILTER_NBIT, in the dataset creation property listplist_id.The HDF5 user can create an N-Bit datatype by writing codes like:
- hid_t nbit_datatype = H5Tcopy(H5T_STD_I32LE);
H5Tset_precision(nbit_datatype, 16);
H5Tset_offset(nbit_datatype, 4);
In memory, one value of the N-Bit datatype in the above example will be stored on a little-endian machine like this:
-
byte 3 byte 2 byte 1 byte 0 ???????? ????SPPP PPPPPPPP PPPP????
Note: S - sign bit, P - significant bit, ? - padding bit; For signed integer, the sign bit is included in the precision.
When data of the above datatype are stored on disk using N-bit filter, all padding bits are chopped off and only significant bits are stored. So, the values on disk will be something like:
-
1st value 2nd value SPPPPPPPPPPPPPPP SPPPPPPPPPPPPPPP ...
The N-Bit filter is used effectively for compressing data of an N-Bit datatype as well as a compound and an array datatype with N-Bit fields. However, the datatype classes of the N-Bit datatype or the N-Bit field of the compound datatype or the array datatype are limited to integer or floating-point.
The N-Bit filter supports complex situations where a compound datatype contains member(s) of compound datatype or an array datatype that has compound datatype as the base type. However, it does not support the situation where an array datatype has variable-length or variable-length string as its base datatype. But the filter does support the situation where variable-length or variable-length string is a member of a compound datatype.
For all other HDF5 datatypes such as time, string, bitfield, opaque, reference, enum, and variable length, the N-Bit filter allows them to pass through like an no-op.
Like other I/O filters supported by the HDF5 library, application using the N-Bit filter must store data with chunked storage.
By nature, the N-Bit filter should not be used together with other I/O filters.
- hid_t nbit_datatype = H5Tcopy(H5T_STD_I32LE);
- Parameters:
hid_t plist_idIN: Dataset creation property list identifier. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_nbit_f
-
Signature:
SUBROUTINE h5pset_nbit_f(plist_id, hdferr) INTEGER(HID_T), INTENT(IN) :: plist_id INTEGER , INTENT(OUT) :: hdferrInputs:
plist_id - Dataset creation property list identifier.
Outputs:
hdferr - Returns 0 if successful and -1 if fails
- History:
Release Change 1.8.0 C function introduced in this release. 1.8.8 Fortran subroutine introduced in this release.
- Name: H5Pset_nlinks
- Signature:
- herr_t
H5Pset_nlinks( hid_tlapl_id, size_tnlinks) - Purpose:
- Sets maximum number of soft or user-defined link traversals.
- Description:
H5Pset_nlinkssets the maximum number of soft or user-defined link traversals allowed,nlinks, before the library assumes it has found a cycle and aborts the traversal. This value is set in the link access property listlapl_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.
- Parameters:
hid_t lapl_idIN: File access property list identifier size_t nlinksIN: Maximum number of links to traverse - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_nlinks_f
SUBROUTINE h5pset_nlinks_f(lapl_id, nlinks, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: lapl_id ! File access property list identifier INTEGER(SIZE_T), INTENT(IN) :: nlinks ! Maximum number of links to traverse INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_nlinks_f- History:
Release C 1.8.0 Function introduced in this release.
- Name: H5Pset_preserve
- Signature:
- herr_t
H5Pset_preserve(hid_tplist, hbool_tstatus) - Purpose:
- Sets the dataset transfer property list
statusto1(TRUE) or0(FALSE). - Notice:
- This function is deprecated as it no longer has any effect;
compound datatype field preservation is now core functionality
in the HDF5 Library.
- Description:
H5Pset_preservesets the dataset transfer property liststatusto1(TRUE) or0(FALSE).When reading or writing compound datatypes and the destination is partially initialized and the read/write is intended to initialize the other members, one must set this property to TRUE. Otherwise the I/O pipeline treats the destination datapoints as completely uninitialized.
- Parameters:
hid_t plistIN: Identifier for the dataset transfer property list. hbool_t statusIN: Status of for the dataset transfer property list (TRUE/FALSE). - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_preserve_f
-
SUBROUTINE h5pset_preserve_f(prp_id, flag, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset transfer property ! list identifier LOGICAL, INTENT(IN) :: flag ! Status for the dataset ! transfer property list INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_preserve_f - History:
Release Fortran90 1.6.0 The flagparameter has changed from INTEGER to LOGICAL to better match the C API.
- Name: H5Pset_obj_track_times
- Signature:
- herr_t
H5Pset_obj_track_times( hid_tocpl_id, hbool_ttrack_times) - Purpose:
- Sets the recording of times associated with an object.
- Description:
H5Pset_obj_track_timessets a property in the object creation property list,ocpl_id, that governs the recording of times associated with an object.If
track_timesisTRUE, time data will be recorded. Iftrack_timesisFALSE, time data will not be recorded.Time data can be retrieved with
H5Oget_info, which will return it in theH5O_info_tstruct.If times are not tracked, they will be reported as follows when queried:
12:00 AM UDT, Jan. 1, 1970
That date and time are commonly used to represent the beginning of the UNIX epoch.- Parameters:
hid_t ocpl_idIN: Object creation property list identifier hbool_t track_timesIN: Boolean value, TRUEorFALSE, specifying whether object times are to be tracked- Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_obj_track_times_f
SUBROUTINE h5pset_obj_track_times_f(plist_id, flag, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plist_id ! Dataset creation property ! list identifier LOGICAL, INTENT(IN) :: flag ! Object timestamp setting INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_obj_track_times_f- History:
Release C 1.8.0 Function introduced in this release.
- Last modified: 26 October 2011
- Name: H5Pset_scaleoffset
- Signature:
- Name: H5Pset_scaleoffset
- herr_t
H5Pset_scaleoffset( hid_tplist_id, H5Z_SO_scale_type_tscale_type, intscale_factor) - Purpose:
- Sets up the use of the scale-offset filter.
- Description:
H5Pset_scaleoffsetsets the scale-offset filter,H5Z_FILTER_SCALEOFFSET, for a dataset.Generally speaking, scale-offset compression performs a scale and/or offset operation on each data value and truncates the resulting value to a minimum number of bits (MinBits) before storing it. The current scale-offset filter supports integer and floating-point datatypes.
For an integer datatype, the parameter
scale_typeshould be set toH5Z_SO_INT (2). The parameterscale_factordenotes MinBits. If the user sets it toH5Z_SO_INT_MINBITS_DEFAULT (0), the filter will calculate MinBits. Ifscale_factoris set to a positive integer, the filter does not do any calculation and just uses the number as MinBits. However, if the user gives a MinBits that is less than what would be generated by the filter, the compression will be lossy. Also, the MinBits supplied by the user cannot exceed the number of bits to store one value of the dataset datatype.For a floating-point datatype, the filter adopts the GRiB data packing mechanism, which offers two alternate methods: E-scaling and D-scaling. Both methods are lossy compression. If the parameter
scale_typeis set toH5Z_SO_FLOAT_DSCALE (0), the filter will use the D-scaling method; if it is set toH5Z_SO_FLOAT_ESCALE (1), the filter will use the E-scaling method. Since only the D-scaling method is implemented,scale_typeshould be set toH5Z_SO_FLOAT_DSCALEor 0.When the D-scaling method is used, the original data is "D" scaled — multiplied by 10 to the power of
scale_factor, and the "significant" part of the value is moved to the left of the decimal point. Care should be taken in setting the decimalscale_factorso that the integer part will have enough precision to contain the appropriate informationof the data value. For example, ifscale_factoris set to 2, the number 104.561 will be 10456.1 after "D" scaling. The last digit 1 is not "significant" and is thrown off in the process of rounding. The user should make sure that after "D" scaling and rounding, the data values are within the range that can be represented by the integer (same size as the floating-point type).Valid values for
scale_typeare as follows:H5Z_SO_FLOAT_DSCALE (0)Floating-point type, using variable MinBits method H5Z_SO_FLOAT_ESCALE (1)Floating-point type, using fixed MinBits method H5Z_SO_INT (2)Integer type The meaning of
scale_factorvaries according to the value assigned toscale_type:scale_typevaluescale_factordescriptionH5Z_SO_FLOAT_DSCALEDenotes the decimal scale factor for D-scaling and can be positive, negative or zero. This is the current implementation of the library. H5Z_SO_FLOAT_ESCALEDenotes MinBits for E-scaling and must be a positive integer. This is not currently implemented by the library. H5Z_SO_INTDenotes MinBits and it should be a positive integer or H5Z_SO_INT_MINBITS_DEFAULT (0).If it is less than 0, the library will reset it to 0 since it is not implemented.Like other I/O filters supported by the HDF5 library, an application using the scale-offset filter must store data with chunked storage.
- Parameters:
hid_t plist_idIN: Dataset creation property list identifier. H5Z_SO_scale_type_t scale_typeIN: Flag indicating compression method. int scale_factorIN: Parameter related to scale. Must be non-negative. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_scaleoffset_f
-
Signature:
SUBROUTINE h5pset_scaleoffset_f(plist_id, scale_type, scale_factor, hdferr) INTEGER(HID_T), INTENT(IN) :: plist_id INTEGER , INTENT(IN) :: scale_type INTEGER , INTENT(IN) :: scale_factor INTEGER , INTENT(OUT) :: hdferrInputs:
plist_id - Dataset creation property list identifier. scale_type - Flag indicating compression method. Valid values: H5Z_SO_FLOAT_DSCALE_F H5Z_SO_FLOAT_ESCALE_F H5Z_SO_INT_F scale_factor - Parameter related to scale.Outputs:
hdferr - Returns 0 if successful and -1 if fails
- History:
Release Change 1.8.0 C function introduced in this release. 1.8.8 Fortran90 subroutine introduced in this release.
- Name: H5Pset_shared_mesg_index
- Signature:
- herr_t
H5Pset_shared_mesg_index( hid_tfcpl_id, unsignedindex_num, unsignedmesg_type_flags, unsignedmin_mesg_size) - Purpose:
- Configures the specified shared object header message index.
- Description:
H5Pset_shared_mesg_indexis used to configure the specified shared object header message index, setting the types of messages that may be stored in the index and the minimum size of each message.fcpl_idspecifies the file creation property list.index_numspecifies the index to be configured.index_numis zero-indexed, so in a file with three indexes, they will be numbered0,1, and2.mesg_type_flagsandmin_mesg_sizespecify, respectively, the types and minimum size of messages that can be stored in this index.Valid message types are as follows:
H5O_SHMESG_NONE_FLAGNo shared messages H5O_SHMESG_SDSPACE_FLAGSimple dataspace message H5O_SHMESG_DTYPE_FLAGDatatype message H5O_SHMESG_FILL_FLAGFill value message H5O_SHMESG_PLINE_FLAGFilter pipeline message H5O_SHMESG_ATTR_FLAGAttribute message H5O_SHMESG_ALL_FLAGAll message types; i.e., equivalent to the following:
(H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | H5O_SHMESG_ATTR_FLAG)- Parameters:
hid_t fcpl_idIN: File creation property list identifier. unsigned index_numIN: Index being configured. unsigned mesg_type_flagsIN: Types of messages that should be stored in this index. unsigned min_mesg_sizeIN: Minimum message size. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_shared_mesg_index_f
-
SUBROUTINE h5pset_shared_mesg_index_f(fcpl_id, index_num, mesg_type_flags, & min_mesg_size, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: fcpl_id ! File creation property list INTEGER, INTENT(IN) :: index_num ! Index being configured. INTEGER, INTENT(IN) :: mesg_type_flags ! Types of messages that should be ! stored in this index. INTEGER, INTENT(IN) :: min_mesg_size ! Minimum message size. INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_shared_mesg_index_f - History:
Release C 1.8.0 Function introduced in this release.
- Name: H5Pset_shared_mesg_nindexes
- Signature:
- herr_t
H5Pset_shared_mesg_nindexes( hid_tplist_id, unsignednindexes) - Purpose:
- Sets number of shared object header message indexes.
- Description:
H5Pset_shared_mesg_nindexessets the number of shared object header message indexes in the specified file creation property list.This setting determines the number of shared object header message indexes that will be available in files created with this property list. These indexes can then be configured with
H5Pset_shared_mesg_index.If
nindexesis set to0(zero), shared object header messages are disabled in files created with this property list.- Parameters:
hid_t plist_idIN: File creation property list unsigned nindexesIN: Number of shared object header message indexes to be available in files created with this property list - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_shared_mesg_nindexes_f
-
SUBROUTINE h5pset_shared_mesg_nindexes_f( plist_id, nindexes, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plist_id ! File creation property list INTEGER, INTENT(IN) :: nindexes ! Number of shared object header message ! indexes available in files created ! WITH this property list INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_shared_mesg_nindexes_f - History:
Release C 1.8.0 Function introduced in this release.
- Last modified: 11 March 2013
- Name: H5Pset_shared_mesg_phase_change
- Signature:
- Name: H5Pset_shared_mesg_phase_change
- herr_t
H5Pset_shared_mesg_phase_change( hid_tfcpl_id, unsignedmax_list, unsignedmin_btree) - Purpose:
- Sets shared object header message storage phase change thresholds.
- Description:
H5Pset_shared_mesg_phase_changesets threshold values for storage of shared object header message indexes in a file. These phase change thresholds determine the point at which the index storage mechanism changes from a more compact list format to a more performance-oriented B-tree format, and vice-versa.By default, a shared object header message index is initially stored as a compact list. When the number of messages in an index exceeds the threshold value of
max_list, storage switches to a B-tree for improved performance. If the number of messages subsequently falls below themin_btreethreshold, the index will revert to the list format.If
max_listis set to0(zero), shared object header message indexes in the file will be created as B-trees and will never revert to lists.fcpl_idspecifies the file creation property list.- Parameters:
hid_t fcpl_idIN: File creation property list identifier unsigned max_listIN: Threshold above which storage of a shared object header message index shifts from list to B-tree unsigned min_btreeIN: Threshold below which storage of a shared object header message index reverts to list format - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface:
- None.
- History:
Release C 1.8.0 Function introduced in this release.
- Name: H5Pset_shuffle
- Signature:
- herr_t
H5Pset_shuffle(hid_tplist_id) - Purpose:
- Sets up use of the shuffle filter.
- Description:
H5Pset_shufflesets the shuffle filter,H5Z_FILTER_SHUFFLE, in the dataset creation property listplist_id.The shuffle filter de-interlaces a block of data by reordering the bytes. All the bytes from one consistent byte position of each data element are placed together in one block; all bytes from a second consistent byte position of each data element are placed together a second block; etc. For example, given three data elements of a 4-byte datatype stored as
012301230123, shuffling will re-order data as000111222333. This can be a valuable step in an effective compression algorithm because the bytes in each byte position are often closely related to each other and putting them together can increase the compression ratio.As implied above, the primary value of the shuffle filter lies in its coordinated use with a compression filter; it does not provide data compression when used alone. When the shuffle filter is applied to a dataset immediately prior to the use of a compression filter, the compression ratio achieved is often superior to that achieved by the use of a compression filter without the shuffle filter.
- Parameters:
hid_t plist_idIN: Dataset creation property list identifier. - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_shuffle_f
-
SUBROUTINE h5pset_shuffle_f(prp_id, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_shuffle_f - History:
Release C 1.6.0 Function introduced in this release.
- Last modified: 14 April 2010
- Name: H5Pset_sieve_buf_size
- Signature:
- Name: H5Pset_sieve_buf_size
- herr_t
H5Pset_sieve_buf_size( hid_tfapl_id, size_tsize) - Purpose:
- Sets the maximum size of the data sieve buffer.
- Description:
H5Pset_sieve_buf_sizesetssize, the maximum size in bytes of the data sieve buffer, which is used by file drivers that are capable of using data sieving.The data sieve buffer is used when performing I/O on datasets in the file. Using a buffer which is large enough to hold several pieces of the dataset being read in for hyperslab selections boosts performance by quite a bit.
The default value is set to 64KB, indicating that file I/O for raw data reads and writes will occur in at least 64KB blocks. Setting the value to 0 with this API function will turn off the data sieving, even if the VFL driver attempts to use that strategy.
Internally, the library checks the storage sizes of the datasets in the file. It picks the smaller one between the size from the file access property and the size of the dataset to allocate the sieve buffer for the dataset in order to save memory usage.
- Parameters:
hid_t fapl_idIN: File access property list identifier. size_t sizeIN: Maximum size, in bytes, of data sieve buffer. - Returns:
- Returns a non-negative value if successful.
Otherwise returns a negative value.
- Fortran90 Interface: h5pset_sieve_buf_size_f
SUBROUTINE h5pset_sieve_buf_size_f(plist_id, size, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plist_id ! File access property list ! identifier INTEGER(SIZE_T), INTENT(IN) :: size ! Sieve buffer size INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_sieve_buf_size_f- History:
Release C 1.6.0 The sizeparameter has changed from type hsize_t to size_t.1.4.0 Function introduced in this release.
- Name: H5Pset_sizes
- Signature:
- herr_t
H5Pset_sizes(hid_tplist, size_tsizeof_addr, size_tsizeof_size) - Purpose:
- Sets the byte size of the offsets and lengths used to address objects in an HDF5 file.
- Description:
H5Pset_sizessets the byte size of the offsets and lengths used to address objects in an HDF5 file. This function is only valid for file creation property lists. Passing in a value of 0 for one of thesizeof_...parameters retains the current value. The default value for both values is the same assizeof(hsize_t)in the library (normally 8 bytes). Valid values currently are 2, 4, 8 and 16.- Parameters:
hid_t plistIN: Identifier of property list to modify. size_t sizeof_addrIN: Size of an object offset in bytes. size_t sizeof_sizeIN: Size of an object length in bytes. - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_sizes_f
-
SUBROUTINE h5pset_sizes_f (prp_id, sizeof_addr, sizeof_size, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER(SIZE_T), INTENT(IN) :: sizeof_addr ! Size of an object offset ! in bytes INTEGER(SIZE_T), INTENT(IN) :: sizeof_size ! Size of an object length ! in bytes INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_sizes_f
- Name: H5Pset_small_data_block_size
- Signature:
- herr_t
H5Pset_small_data_block_size(hid_tfapl_id, hsize_tsize) - Purpose:
- Sets the size of a contiguous block reserved for small data.
- Description:
H5Pset_small_data_block_sizereserves blocks ofsizebytes for the contiguous storage of the raw data portion of small datasets. The HDF5 library then writes the raw data from small datasets to this reserved space, thus reducing unnecessary discontinuities within blocks of meta data and improving I/O performance.A small data block is actually allocated the first time a qualifying small dataset is written to the file. Space for the raw data portion of this small dataset is suballocated within the small data block. The raw data from each subsequent small dataset is also written to the small data block until it is filled; additional small data blocks are allocated as required.
The HDF5 library employs an algorithm that determines whether I/O performance is likely to benefit from the use of this mechanism with each dataset as storage space is allocated in the file. A larger
sizewill result in this mechanism being employed with larger datasets.The small data block size is set as an allocation property in the file access property list identified by
fapl_id.Setting
sizeto zero (0) disables the small data block mechanism.- Parameters:
hid_t fapl_idIN: File access property list identifier. hsize_t sizeIN: Maximum size, in bytes, of the small data block.
The default size is2048.- Returns:
- Returns a non-negative value if successful; otherwise a negative value.
- Fortran90 Interface: h5pset_small_data_block_size_f
-
SUBROUTINE h5pset_small_data_block_size_f(plist_id, size, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: plist_id ! File access ! property list identifier INTEGER(HSIZE_T), INTENT(IN) :: size ! Small raw data block size INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_small_data_block_size_f - History:
Release C 1.4.4 Function introduced in this release.
- Last modified: 7 March 2013
- Name: H5Pset_sym_k
- Signature:
- Name: H5Pset_sym_k
- herr_t
H5Pset_sym_k( hid_tfcpl_id, unsignedik, unsignedlk) - Purpose:
- Sets the size of parameters used to control the symbol table nodes.
- Description:
H5Pset_sym_ksets the size of parameters used to control the symbol table nodes.This function is valid only for file creation property lists. Passing in a value of zero (
0) for one of the parameters retains the current value.ikis one half the rank of a B-tree that stores a symbol table for a group. Internal nodes of the symbol table are on average 75% full. That is, the average rank of the tree is 1.5 times the value ofik. The HDF5 library uses(ik*2)as the maximum # of entries before splitting a B-tree node. Since only 2 bytes are used in storing # of entries for a B-tree node in an HDF5 file,(ik*2)cannot exceed65536. The default value forikis16.lkis one half of the number of symbols that can be stored in a symbol table node. A symbol table node is the leaf of a symbol table tree which is used to store a group. When symbols are inserted randomly into a group, the group's symbol table nodes are 75% full on average. That is, they contain 1.5 times the number of symbols specified bylk. The default value forlkis4.- Parameters:
hid_t fcpl_idIN: File creation property list identifier unsigned ikIN: Symbol table tree rank unsigned lkIN: Symbol table node size - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface: h5pset_sym_k_f
-
SUBROUTINE h5pset_sym_k_f (prp_id, ik, lk, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER, INTENT(IN) :: ik ! Symbol table tree rank INTEGER, INTENT(IN) :: lk ! Symbol table node size INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_sym_k_f - History:
Release C 1.6.4 ikparameter type changed to unsigned.1.6.0 The ikparameter has changed from type int to unsigned.
- Last modified: 16 July 2013
- Name: H5Pset_szip
- Signature:
- Name: H5Pset_szip
- herr_t
H5Pset_szip(hid_tplist, unsigned intoptions_mask, unsigned intpixels_per_block) - Purpose:
- Sets up use of the SZIP compression filter.
- Description:
H5Pset_szipsets an SZIP compression filter,H5Z_FILTER_SZIP, for a dataset. SZIP is a compression method designed for use with scientific data.Before proceeding, all users should review the “Limitations” section below.
Users familiar with SZIP outrside the HDF5 context may benefit from reviewing “Notes for Users Familiar with SZIP in Other Contexts” below.
In the text below, the term pixel refers to an HDF5 data element. This terminology derives from SZIP compression's use with image data, where pixel referred to an image pixel.
The SZIP
bits_per_pixelvalue (see Notes, below) is automatically set, based on the HDF5 datatype. SZIP can be used with atomic datatypes that may have size of 8, 16, 32, or 64 bits. Specifically, a dataset with a datatype that is 8-, 16-, 32-, or 64-bit signed or unsigned integer; char; or 32- or 64-bit float can be compressed with SZIP. See Notes, below, for further discussion of the the SZIPbits_per_pixelsetting.SZIP options are passed in an options mask,
options_mask, as follows.
Option
Description
(Mutually exclusive; select one.)
H5_SZIP_EC_OPTION_MASK
Selects entropy coding method.H5_SZIP_NN_OPTION_MASKSelects nearest neighbor coding method.
- The entropy coding method, the EC option specified by
H5_SZIP_EC_OPTION_MASK, is best suited for data that has been processed. The EC method works best for small numbers. - The nearest neighbor coding method, the NN option
specified by
H5_SZIP_NN_OPTION_MASK, preprocesses the data then the applies EC method as above.
SZIP compresses data block by block, with a user-tunable block size. This block size is passed in the parameter
pixels_per_blockand must be even and not greater than 32, with typical values being8,10,16, or32. This parameter affects compression ratio; the more pixel values vary, the smaller this number should be to achieve better performance.In HDF5, compression can be applied only to chunked datasets. If
pixels_per_blockis bigger than the total number of elements in a dataset chunk,H5Pset_szipwill succeed but the subsequent call toH5Dcreatewill fail; the conflict can be detected only when the property list is used.To achieve optimal performance for SZIP compression, it is recommended that a chunk's fastest-changing dimension be equal to N times
pixels_per_blockwhere N is the maximum number of blocks per scan line allowed by the SZIP library. In the current version of SZIP, N is set to 128.- The entropy coding method, the EC option specified by
- Limitations:
-
- SZIP compression cannot be applied to
If an SZIP filter is set in a dataset creation property list used to create a dataset containing a non-allowed datatype, the call toH5Dcreatewill fail; the conflict can be detected only when the property list is used. - Users should be aware that there are factors that affect one’s rights and ability to use SZIP compression. See the documents at SZIP Compression in HDF5 for important information regarding terms of use and the SZIP copyright notice, for further discussion of SZIP compression in HDF5, and for a list of SZIP-related references.
- SZIP compression cannot be applied to
- Parameters:
hid_t plistIN: Dataset creation property list identifier. unsigned int options_maskIN: A bit-mask conveying the desired SZIP options. Valid values are H5_SZIP_EC_OPTION_MASKandH5_SZIP_NN_OPTION_MASK.unsigned int pixels_per_blockIN: The number of pixels or data elements in each data block. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Notes for Users Familiar with SZIP in Other Contexts:
- The following notes are of interest primarily to those who have
used SZIP compression outside of the HDF5 context.
In non-HDF5 applications, SZIP typically requires that the user application supply additional parameters:
pixels_in_object, the number of pixels in the object to be compressedbits_per_pixel, the number of bits per pixelpixels_per_scanline, the number of pixels per scan line
These values need not be independently supplied in the HDF5 environment as they are derived from the datatype and dataspace, which are already known. In particular, HDF5 sets
pixels_in_objectto the number of elements in a chunk andbits_per_pixelto the size of the element or pixel datatype. The following algorithm is used to setpixels_per_scanline:- If the size of a chunk's fastest-changing dimension,
size, is greater than 4K,
set
pixels_per_scanlineto 128 timespixels_per_block. - If size is less than 4K
but greater than
pixels_per_block, setpixels_per_scanlineto the minimum of size and 128 timespixels_per_block. - If size is less than
pixels_per_blockbut greater than the number elements in the chunk, setpixels_per_scanlineto the minimum of the number elements in the chunk and 128 timespixels_per_block.
The HDF5 datatype may have precision that is less than the full size of the data element, e.g., an 11-bit integer can be defined using
H5Tset_precision. To a certain extent, SZIP can take advantage of the precision of the datatype to improve compression:- If the HDF5 datatype size is 24-bit or less and
the offset of the bits in the HDF5 datatype is zero (see
H5Tset_offsetorH5Tget_offset), the data is the in lowest N bits of the data element. In this case, the SZIPbits_per_pixelis set to the precision of the HDF5 datatype. - If the offset is not zero, the SZIP
bits_per_pixelwill be set to the number of bits in the full size of the data element. - If the HDF5 datatype precision is 25-bit to 32-bit,
the SZIP
bits_per_pixelwill be set to 32. - If the HDF5 datatype precision is 33-bit to 64-bit,
the SZIP
bits_per_pixelwill be set to 64.
HDF5 always modifies the options mask provided by the user to set up usage of
RAW_OPTION_MASK,ALLOW_K13_OPTION_MASK, and one ofLSB_OPTION_MASKorMSB_OPTION_MASK, depending on endianness of the datatype. - Fortran90 Interface: h5pset_szip_f
-
SUBROUTINE h5pset_szip_f(prp_id, options_mask, pixels_per_block, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Dataset creation property list identifier INTEGER, INTENT(IN) :: options_mask ! A bit-mask conveying the desired ! SZIP options ! Current valid values in Fortran are: ! H5_SZIP_EC_OM_F ! H5_SZIP_NN_OM_F INTEGER, INTENT(IN) :: pixels_per_block ! The number of pixels or data elements ! in each data block INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_szip_f - History:
Release C 1.6.0 Function introduced in this release.
- Last modified: 22 August 2012
- Name: H5Pset_type_conv_cb
- Signature:
- Name: H5Pset_type_conv_cb
- herr_t
H5Pset_type_conv_cb( hid_tplist, H5T_conv_except_func_tfunc, void *op_data) - Purpose:
- Sets user-defined datatype conversion callback function.
- Description:
H5Pset_type_conv_cbsets the user-defined datatype conversion callback functionfuncin the dataset transfer property listplist.The parameter
op_datais a pointer to user-defined input data for the callback function and will be passed through to the callback function.The callback function
funcdefines the actions an application is to take when there is an exception during datatype conversion. The function prototype is as follows:typedefH5T_conv_ret_t (H5T_conv_except_func_t) ( H5T_conv_except_texcept_type, hid_tsrc_id, hid_tdst_id, void *src_buf, void *dst_buf, void *op_data)
where
except_typeindicates what kind of exception has happened,src_idanddst_idare the source and destination datatype identifiers,src_bufanddst_bufare the source and destination data buffer, andop_datais the required input data for this callback function.Valid values for
except_typeare as follows:H5T_CONV_EXCEPT_RANGE_HI- Source value is positive and is too big to the destination. Overflow happens.
H5T_CONV_EXCEPT_RANGE_LOW- Source value is negative and its magnitude is too big to the destination. Overflow happens.
H5T_CONV_EXCEPT_TRUNCATE- Source is floating-point type and destination is integer. The floating-point number has fractional part.
H5T_CONV_EXCEPT_PRECISION- Source is integer and destination is floating-point type. The mantissa of floating-point type is not big enough to hold all the digits of the integer.
H5T_CONV_EXCEPT_PINF- Source is floating-point type and the value is positive infinity.
H5T_CONV_EXCEPT_NINF- Source is floating-point type and the value is negative infinity.
H5T_CONV_EXCEPT_NAN- Source is floating-point type and the value is NaN (not a number, including QNaN and SNaN).
Valid callback function return values are
H5T_CONV_ABORT,H5T_CONV_UNHANDLEDandH5T_CONV_HANDLED.- Programming Note for C++ Developers Using C Functions:
-
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cbandH5Pset_type_conv_cband functions such asH5TconvertandH5Ewalk2.Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
- Parameters:
hid_t plistIN: Dataset transfer property list identifier. H5T_conv_except_func_t funcIN: User-defined type conversion callback function. void * op_dataIN: User-defined input data for the callback function. - Returns:
- Returns a non-negative value if successful;
otherwise returns a negative value.
- Fortran90 Interface:
- None.
- Name: H5Pset_userblock
- Signature:
- herr_t
H5Pset_userblock(hid_tplist, hsize_tsize) - Purpose:
- Sets user block size.
- Description:
H5Pset_userblocksets the user block size of a file creation property list. The default user block size is 0; it may be set to any power of 2 equal to 512 or greater (512, 1024, 2048, etc.).- Parameters:
hid_t plistIN: Identifier of property list to modify. hsize_t sizeIN: Size of the user-block in bytes. - Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface: h5pset_userblock_f
-
SUBROUTINE h5pset_userblock_f (prp_id, size, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: prp_id ! Property list identifier INTEGER(HSIZE_T), INTENT(IN) :: size ! Size of the user-block in bytes INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5pset_userblock_f
- Name: H5Pset_vlen_mem_manager
- Signature:
- herr_t
H5Pset_vlen_mem_manager(hid_tplist, H5MM_allocate_talloc, void *alloc_info, H5MM_free_tfree, void *free_info) - Purpose:
- Sets the memory manager for variable-length datatype allocation in
H5DreadandH5Dvlen_reclaim. - Description:
H5Pset_vlen_mem_managersets the memory manager for variable-length datatype allocation inH5Dreadand free inH5Dvlen_reclaim.The
allocandfreeparameters identify the memory management routines to be used. If the user has defined custom memory management routines,allocand/orfreeshould be set to make those routine calls (i.e., the name of the routine is used as the value of the parameter); if the user prefers to use the system'smallocand/orfree, theallocandfreeparameters, respectively, should be set toNULLThe prototypes for these user-defined functions would appear as follows:
typedef void *(*H5MM_allocate_t)(size_tsize, void *alloc_info) ;
typedef void (*H5MM_free_t)(void *mem, void *free_info) ;
Thealloc_infoandfree_infoparameters can be used to pass along any required information to the user's memory management routines.In summary, if the user has defined custom memory management routines, the name(s) of the routines are passed in the
allocandfreeparameters and the custom routines' parameters are passed in thealloc_infoandfree_infoparameters. If the user wishes to use the systemmallocandfreefunctions, theallocand/orfreeparameters are set toNULLand thealloc_infoandfree_infoparameters are ignored.- Parameters:
hid_t plistIN: Identifier for the dataset transfer property list. H5MM_allocate_t allocIN: User's allocate routine, or NULLfor systemmalloc.void * alloc_infoIN: Extra parameter for user's allocation routine.
Contents are ignored if preceding parameter isNULL.H5MM_free_t freeIN: User's free routine, or NULLfor systemfree.void * free_infoIN: Extra parameter for user's free routine.
Contents are ignored if preceding parameter isNULL.- Returns:
- Returns a non-negative value if successful; otherwise returns a negative value.
- Fortran90 Interface:
- None.
- Name: H5Punregister
- Signature:
- herr_t
H5Punregister( H5P_class_tclass, const char *name) - Purpose:
- Removes a property from a property list class.
- Description:
H5Punregisterremoves a property from a property list class.Future property lists created of that class will not contain this property; existing property lists containing this property are not affected.
- Parameters:
H5P_class_t classIN: Property list class from which to remove permanent property const char * nameIN: Name of property to remove - Returns:
- Success: a non-negative value
- Failure: a negative value
- Fortran90 Interface: h5punregister_f
-
SUBROUTINE h5punregister_f(class, name, hdferr) IMPLICIT NONE INTEGER(HID_T), INTENT(IN) :: class ! Property list class identifier CHARACTER(LEN=*), INTENT(IN) :: name ! Name of property to remove INTEGER, INTENT(OUT) :: hdferr ! Error code ! 0 on success and -1 on failure END SUBROUTINE h5punregister_f
The HDF Group Help Desk: 
Describes HDF5 Release 1.8.18, November 2016. |
Copyright by
The HDF Group
and the Board of Trustees of the University of Illinois |