|
General Property List Operations
File Creation Properties | File Access Properties |
Dataset Creation Properties
Dataset Memory and Transfer Properties | ||
|
|| Available only in the parallel HDF5 library. | ||||
H5Pcreate(H5P_class_t type
)
H5Pcreate creates a new property as an instance of some
property list class. The new property list is initialized
with default values for the specified class. The classes are:
H5P_FILE_CREATE
H5P_FILE_ACCESS
H5P_DATASET_CREATE
H5P_DATASET_XFER
type
plist) if successful;
otherwise Fail (-1).
H5Pclose(hid_t plist
)
H5Pclose terminates access to a property list.
All property lists should be closed when the application is
finished accessing them.
This frees resources used by the property list.
plist
H5Pget_class(hid_t plist
)
H5Pget_class returns the property list class for the
property list identied by the plist parameter.
Valid property list classes are defined in the description of
H5Pcreate().
plist
H5Pcopy(hid_t plist
)
H5Pcopy copies an existing property list to create
a new property list.
The new property list has the same properties and values
as the original property list.
plist
H5Pget_version(hid_t plist,
int * boot,
int * freelist,
int * stab,
int * shhdr
)
H5Pget_version retrieves the version information of various objects
for a file creation property list. Any pointer parameters which are
passed as NULL are not queried.
plist
boot
freelist
stab
shhdr
H5Pset_userblock(hid_t plist,
hsize_t size
)
H5Pset_userblock sets the user block size of a
file creation property list.
The default user block size is 0; it may be set to any
power of 2 equal to 512 or greater (512, 1024, 2048, etc.).
plist
size
H5Pget_userblock(hid_t plist,
hsize_t * size
)
H5Pget_userblock retrieves the size of a user block
in a file creation property list.
plist
size
H5Pset_sizes(hid_t plist,
size_t sizeof_addr,
size_t sizeof_size
)
H5Pset_sizes sets the byte size of the offsets and lengths used to
address objects in an HDF5 file. This function is only valid for
file creation property lists. Passing in a value of 0 for one of the
sizeof parameters retains the current value. The default value
for both values is 4 bytes. Valid values currenly are 2, 4, 8 and
16.
plist
sizeof_addr
sizeof_size
H5Pget_sizes(hid_t plist,
size_t * sizeof_addr,
size_t * sizeof_size
)
H5Pget_sizes retrieves the size of the offsets
and lengths used in an HDF5 file.
This function is only valid for file creation property lists.
plist
size
size
H5Pset_mpi(hid_t plist,
MPI_Comm comm,
MPI_Info info
)
H5Pset_mpi stores the access mode for MPIO call and the user supplied
communicator and info in the access property list, which can then
be used to open file. This function is available only in the
parallel HDF5 library and is not a collective function.
plist
comm
comm. Any modification to comm after
this function call returns may have undetermined effect
to the access property list. Users should call this function
again to setup the property list.
info
info. Any modification to info after
this function call returns may have undetermined effect
to the access property list. Users should call this function
again to setup the property list.
H5Pget_mpi(hid_t plist,
MPI_Comm *comm,
MPI_Info *info
)
H5Pget_mpi retrieves the communicator and info object
that have been set by H5Pset_mpi.
This function is available only in the parallel HDF5 library
and is not a collective function.
plist
comm
info
H5Pset_xfer(hid_t plist,
H5D_transfer_t data_xfer_mode
)
H5Pset_xfer sets the transfer mode of the dataset transfer property list.
The list can then be used to control the I/O transfer mode
during dataset accesses. This function is available only
in the parallel HDF5 library and is not a collective function.
Valid data transfer modes are:
plist
data_xfer_mode
H5Pget_xfer(hid_t plist,
H5D_transfer_t * data_xfer_mode
)
H5Pget_xfer retrieves the transfer mode from the
dataset transfer property list.
This function is available only in the parallel HDF5 library
and is not a collective function.
plist
data_xfer_mode
H5Pset_sym_k(hid_t plist,
int ik,
int lk
)
H5Pset_sym_k sets the size of parameters used to
control the symbol table nodes. This function is only valid
for file creation property lists. Passing in a value of 0 for
one of the parameters retains the current value.
ik is one half the rank of a tree that stores a symbol
table for a group. Internal nodes of the symbol table are on
average 75% full. That is, the average rank of the tree is
1.5 times the value of ik.
lk is one half of the number of symbols that can
be stored in a symbol table node. A symbol table node is the
leaf of a symbol table tree which is used to store a group.
When symbols are inserted randomly into a group, the group's
symbol table nodes are 75% full on average. That is, they
contain 1.5 times the number of symbols specified by
lk.
plist
ik
lk
H5Pget_sym_k(hid_t plist,
int * ik,
int * lk
)
H5Pget_sym_k retrieves the size of the
symbol table B-tree 1/2 rank and the symbol table leaf
node 1/2 size. This function is only valid for file creation
property lists. If a parameter valued is set to NULL, that
parameter is not retrieved. See the description for
H5Pset_sym_k for more
information.
plist
ik
size
H5Pset_istore_k(hid_t plist,
int ik
)
H5Pset_istore_k sets the size of the parameter
used to control the B-trees for indexing chunked datasets.
This function is only valid for file creation property lists.
Passing in a value of 0 for one of the parameters retains
the current value.
ik is one half the rank of a tree that stores
chunked raw data. On average, such a tree will be 75% full,
or have an average rank of 1.5 times the value of
ik.
plist
ik
H5Pget_istore_k(hid_t plist,
int * ik
)
H5Pget_istore_k queries the 1/2 rank of
an indexed storage B-tree.
The argument ik may be the null pointer (NULL).
This function is only valid for file creation property lists.
See H5Pset_istore_k for details.
plist
ik
H5Pset_layout(hid_t plist,
H5D_layout_t layout
)
H5Pset_layout sets the type of storage used store the
raw data for a dataset.
This function is only valid for dataset creation property lists.
Valid parameters for layout are:
plist
layout
H5Pget_layout(hid_t plist)
H5Pget_layout returns the layout of the raw data for
a dataset. This function is only valid for dataset creation
property lists. Valid types for layout are:
plist
H5Pset_chunk(hid_t plist,
int ndims,
const hsize_t * dim
)
H5Pset_chunk sets the size of the chunks used to
store a chunked layout dataset. This function is only valid
for dataset creation property lists.
The ndims parameter currently must be the same size
as the rank of the dataset. The values of the dim
array define the size of the chunks to store the dataset's raw data.
As a side-effect, the layout of the dataset is changed to
H5D_CHUNKED, if it is not already.
plist
ndims
dim
H5Pget_chunk(hid_t plist,
int max_ndims,
hsize_t * dims
)
H5Pget_chunk retrieves the size of chunks for the
raw data of a chunked layout dataset.
This function is only valid for dataset creation property lists.
At most, max_ndims elements of dims
will be initialized.
plist
max_ndims
dims array.
dims
H5Pset_alignment(hid_t plist,
hsize_t threshold,
hsize_t alignment
)
H5Pset_alignment sets the alignment properties
of a file access property list
so that any file object >= THRESHOLD bytes will be aligned on
an address which is a multiple of ALIGNMENT. The addresses
are relative to the end of the user block; the alignment is
calculated by subtracting the user block size from the
absolute file address and then adjusting the address to be a
multiple of ALIGNMENT.
Default values for THRESHOLD and ALIGNMENT are one, implying no alignment. Generally the default values will result in the best performance for single-process access to the file. For MPI-IO and other parallel systems, choose an alignment which is a multiple of the disk block size.
plist
threshold
alignment
H5Pget_alignment(hid_t plist,
hsize_t *threshold,
hsize_t *alignment
)
H5Pget_alignment retrieves the current settings for
alignment properties from a file access property list.
The threshold and/or alignment pointers
may be null pointers (NULL).
plist
*threshold
*alignment
H5Pset_external(hid_t plist,
const char *name,
off_t offset,
hsize_t size
)
H5Pset_external adds an external file to the
list of external files.
If a dataset is split across multiple files then the files should be defined in order. The total size of the dataset is the sum of the SIZE arguments for all the external files. If the total size is larger than the size of a dataset then the dataset can be extended (provided the data space also allows the extending).
plist
*name
offset
size
H5Pget_external_count(hid_t plist,
)
H5Pget_external_count returns the number of external files
for the specified dataset.
plist
H5Pget_external(hid_t plist,
int idx,
size_t name_size,
char *name,
off_t *offset,
hsize_t *size
)
H5Pget_external returns information about an external
file. The external file is specified by its index, idx,
which is a number from zero to N-1, where N is the value
returned by H5Pget_external_count().
At most name_size characters are copied into the
name array. If the external file name is
longer than name_size with the null terminator, the
return value is not null terminated (similar to strncpy()).
If name_size is zero or name is the
null pointer, the external file name is not returned.
If offset or size are null pointers
then the corresponding information is not returned.
plist
idx
name_size
name array.
*name
*offset
*size
H5Pset_filter(hid_t plist,
H5Z_filter_t filter,
unsigned int flags,
size_t cd_nelmts,
const unsigned int cd_values[]
)
H5Pset_filter adds the specified
filter and corresponding properties to the
end of an output filter pipeline.
If plist is a dataset creation property list,
the filter is added to the permanent filter pipeline;
if plist is a dataset transfer property list,
the filter is added to the transient filter pipeline.
The array cd_values contains
cd_nelmts integers which are auxiliary data
for the filter. The integer values will be stored in the
dataset object header as part of the filter information.
The flags argument is a bit vector with
the following fields specifying certain general properties
of the filter:
H5Z_FLAG_OPTIONAL |
If this bit is set then the filter is
optional. If the filter fails (see below) during an
H5Dwrite() operation then the filter is
just excluded from the pipeline for the chunk for which
it failed; the filter will not participate in the
pipeline during an H5Dread() of the chunk.
This is commonly used for compression filters: if the
compression result would be larger than the input then
the compression filter returns failure and the
uncompressed data is stored in the file. If this bit is
clear and a filter fails then H5Dwrite()
or H5Dread() also fails. |
plist_id must be a dataset creation
property list.
plist
filter
flags
cd_nelmts
cd_values
cd_values[]
H5Pget_nfilters(hid_t plist)
H5Pget_nfilters returns the number of filters
defined in the filter pipeline associated with the property list
plist.
In each pipeline, the filters are numbered from 0 through N-1, where N is the value returned by this function. During output to the file, the filters are applied in increasing order; during input from the file, they are applied in decreasing order.
H5Pget_nfilters returns the number of filters
in the pipeline, including zero (0) if there
are none.
plist_id must be a dataset creation
property list.
plist
H5Pget_filter(hid_t plist,
int filter_number,
unsigned int *flags,
size_t *cd_nelmts,
unsigned int *cd_values,
size_t namelen,
char name[]
)
H5Pget_filter returns information about a
filter, specified by its filter number, in a filter pipeline,
specified by the property list with which it is associated.
If plist is a dataset creation property list,
the pipeline is a permanent filter pipeline;
if plist is a dataset transfer property list,
the pipeline is a transient filter pipeline.
On input, cd_nelmts indicates the number of entries
in the cd_values array, as allocated by the caller;
on return,cd_nelmts contains the number of values
defined by the filter.
filter_number is a value between zero and
N-1, as described in
H5Pget_nfilters().
The function will return FAIL (-1) if the filter number is out
of range.
If name is a pointer to an array of at least
namelen bytes, the filter name will be copied
into that array. The name will be null terminated if
namelen is large enough. The filter name returned
will be the name appearing in the file, the name registered
for the filter, or an empty string.
The structure of the flags argument is discussed
in H5Pset_filter().
plist must be a dataset creation property
list.
plist
filter_number
flags
cd_nelmts
cd_values
cd_values
namelen
name.
name[]
H5Pget_driver(hid_t plist,
)
H5Pget_driver returns the identifier of the
low-level file driver. Valid identifiers are:
plist
H5Pset_stdio(hid_t plist)
H5Pset_stdio sets the low level file driver to use
the functions declared in the stdio.h file: fopen(), fseek()
or fseek64(), fread(), fwrite(), and fclose().
plist
H5Pget_stdio(hid_t plist)
H5Pget_stdio checks to determine whether the
file access property list is set to the stdio driver.
In the future, additional arguments may be added to this
function to match those added to H5Pset_stdio().
plist
H5Pset_sec2(hid_t plist,
)
H5Pset_sec2 sets the low-level file driver to use
the functions declared
in the unistd.h file: open(), lseek() or lseek64(), read(),
write(), and close().
plist
H5Pget_sec2(hid_t plist)
H5Pget_sec2 checks to determine whether the
file access property list is set to the sec2 driver.
In the future, additional arguments may be
added to this function to match those added to H5Pset_sec2().
plist
H5Pset_core(hid_t plist,
size_t increment
)
H5Pset_core sets the low-level file driver to use
malloc() and free().
This driver is restricted to temporary files which are not
larger than the amount of virtual memory available.
The increment argument determines the file block size
and memory will be allocated in multiples of INCREMENT bytes.
A liberal increment results in fewer calls to
realloc() and probably less memory fragmentation.
plist
increment
H5Pget_core(hid_t plist,
size_t *increment
)
H5Pget_core checks to determine whether the
file access property list is set to the core driver.
On success, the block size is returned through the
increment if it is not the null pointer.
In the future, additional arguments may be added to this
function to match those added to H5Pset_core().
plist
*increment
H5Pset_split(hid_t plist,
const char *meta_ext,
hid_t meta_plist,
const char *raw_ext,
hid_t raw_plist
)
H5Pset_split sets the low-level driver to
split meta data from raw data, storing meta data in one file and
raw data in another file. The meta file will have a name
which is formed by adding meta_extension (recommended
default value: .meta) to the end of the base name
and will be accessed according to the meta_properties.
The raw file will have a name which is formed by appending
raw_extension (recommended default value:
.raw) to the base name and will be accessed according
to the raw_properties.
Additional parameters may be added to this function in the future.
plist
*meta_ext
.meta.
meta_plist
*raw_ext
.raw.
raw_plist
H5Pget_split(hid_t plist,
size_t meta_ext_size,
char *meta_ext,
hid_t *meta_properties,
size_t raw_ext_size,
char *raw_ext,
hid_t *raw_properties
)
H5Pget_split checks to determine whether the file
access property list is set to the split driver.
On successful return,
meta_properties and raw_properties will
point to copies of the meta and raw access property lists
which should be closed by calling H5Pclose() when
the application is finished with them, but if the meta and/or
raw file has no property list then a negative value is
returned for that property list identifier. Also, if
meta_extension and/or raw_extension are
non-null pointers, at most meta_ext_size or
raw_ext_size characters of the meta or raw file name
extension will be copied to the specified buffer. If the
actual name is longer than what was requested then the result
will not be null terminated (similar to
strncpy()). In the future, additional arguments
may be added to this function to match those added to
H5Pset_split().
plist
meta_ext_size
meta_ext buffer.
*meta_ext
*meta_properties
raw_ext_size
raw_ext buffer.
*raw_ext
*raw_properties
H5Pset_family(hid_t plist,
hsize_t memb_size,
hid_t memb_plist
)
H5Pset_family sets the file access properties
to use the family
driver; any previously defined driver properties are erased
from the property list. Each member of the file family will
use member_properties as its file access property
list. The memb_size argument gives the logical size
in bytes of each family member but the actual size could be
smaller depending on whether the file contains holes. The
member size is only used when creating a new file or
truncating an existing file; otherwise the member size comes
from the size of the first member of the family being
opened. Note: if the size of the off_t type is
four bytes then the maximum family member size is usually
2^31-1 because the byte at offset 2,147,483,647 is generally
inaccessable. Additional parameters may be added to this
function in the future.
plist
memb_size
memb_plist
H5Pset_family(hid_t plist,
hsize_t memb_size,
hid_t memb_plist
)
family
driver.
H5Pset_family sets the file access properties
to use the family driver; any previously defined
driver properties are erased from the property list.
See File Families
in the HDF5 User's Guide for a discussion
of file families.
Each member of the file family will use memb_plist
as its file access property list.
The memb_size argument gives the logical size
in bytes of each family member; the actual size could be
smaller depending on whether the file contains holes.
The member size is only used when creating a new file or
truncating an existing file; otherwise the member size comes
from the size of the first member of the family being
opened.
Note: If the size of the off_t type is
four bytes, then the maximum family member size is usually
2^31-1 because the byte at offset 2,147,483,647 is generally
inaccessable.
Additional parameters may be added to this function in the future.
plist
memb_size
memb_plist
H5Pget_family(hid_t tid,
hsize_t *memb_size,
hid_t *memb_plist
)
H5Pget_family checks to determine whether the
file access property list is set to the family driver.
On successful return,
access_properties will point to a copy of the member
access property list which should be closed by calling
H5Pclose() when the application is finished with
it. If memb_size is non-null then it will contain
the logical size in bytes of each family member. In the
future, additional arguments may be added to this function to
match those added to H5Pset_family().
plist
*memb_size
*memb_plist
H5Pset_cache(hid_t plist,
int mdc_nelmts,
size_t rdcc_nbytes,
double rdcc_w0
)
H5Pset_cache sets the number of elements (objects)
in the meta data cache and the total number of bytes in the
raw data chunk cache.
Sets or queries the meta data cache and raw data chunk cache
parameters. The plist is a file access property
list. The number of elements (objects) in the meta data cache
is mdc_nelmts. The total size of the raw data chunk
cache and the preemption policy is rdcc_nbytes and
w0. For H5Pget_cache() any (or all) of
the pointer arguments may be null pointers.
The RDCC_W0 value should be between 0 and 1 inclusive and indicates how much chunks that have been fully read are favored for preemption. A value of zero means fully read chunks are treated no differently than other chunks (the preemption is strictly LRU) while a value of one means fully read chunks are always preempted before other chunks.
plist
mdc_nelmts
rdcc_nbytes
rdcc_w0
H5Pget_cache(hid_t plist,
int *mdc_nelmts,
size_t *rdcc_nbytes,
double *rdcc_w0
)
plist
*mdc_nelmts
*rdcc_nbytes
*rdcc_w0
H5Pset_buffer(hid_t plist,
size_t size,
void *tconv,
void *bkg
)
H5Pset_buffer
sets the maximum size
for the type conversion buffer and background buffer and
optionally supply pointers to application-allocated buffers.
If the buffer size is smaller than the entire amount of data
being transfered between application and file, and a type
conversion buffer or background buffer is required then
strip mining will be used. However, certain restrictions
apply for the size of buffer which can be used for strip
mining. For instance, when strip mining a 100x200x300
hyperslab of a simple data space the buffer must be large
enough to hold a 1x200x300 slab.
If tconv and/or bkg are null pointers,
then buffers will be allocated and freed during the data transfer.
The default value for the maximum buffer is 1 Mb.
plist
size
tconv
bkg
H5Pget_buffer(hid_t plist,
void **tconv,
void **bkg
)
H5Pget_buffer reads values previously set
with H5Pset_buffer().
plist
**tconv
**bkg
H5Pset_preserve(hid_t plist,
hbool_t status
)
H5Pset_preserve sets the
dataset transfer property list status to TRUE or FALSE.
When reading or writing compound data types and the destination is partially initialized and the read/write is intended to initialize the other members, one must set this property to TRUE. Otherwise the I/O pipeline treats the destination datapoints as completely uninitialized.
plist
status
H5Pget_preserve(hid_t plist)
H5Pget_preserve checks the status of the
dataset transfer property list.
plist
H5Pset_deflate(hid_t plist,
int level
)
H5Pset_deflate sets the compression method for a
dataset creation property list to H5D_COMPRESS_DEFLATE
and the compression level to level<>/code>, which should
be a value from zero to nine, inclusive.
Lower compression levels are faster but result in less compression.
This is the same algorithm as used by the GNU gzip program.
- Parameters:
- hid_t
plist
- IN: Identifier for the dataset creation property list.
- int
level
- IN: Compression level.
- Returns:
- Returns SUCCEED (0) if successful;
otherwise FAIL (-1).