Functions
H5_DLL herr_t	H5Pfill_value_defined (hid_t plist, H5D_fill_value_t *status)
	Determines whether fill value is defined. More...

H5_DLL herr_t	H5Pget_alloc_time (hid_t plist_id, H5D_alloc_time_t *alloc_time)
	Retrieves the timing for storage space allocation. More...

H5_DLL int	H5Pget_chunk (hid_t plist_id, int max_ndims, hsize_t dim[])
	Retrieves the size of chunks for the raw data of a chunked layout dataset. More...

H5_DLL herr_t	H5Pget_chunk_opts (hid_t plist_id, unsigned *opts)
	Retrieves the edge chunk option setting from a dataset creation property list. More...

H5_DLL herr_t	H5Pget_dset_no_attrs_hint (hid_t dcpl_id, hbool_t *minimize)
	Retrieves the setting for whether or not to create minimized dataset object headers. More...

H5_DLL herr_t	H5Pget_external (hid_t plist_id, unsigned idx, size_t name_size, char name, off_t offset, hsize_t *size)
	Returns information about an external file. More...

H5_DLL int	H5Pget_external_count (hid_t plist_id)
	Returns the number of external files for a dataset. More...

H5_DLL herr_t	H5Pget_fill_time (hid_t plist_id, H5D_fill_time_t *fill_time)
	Retrieves the time when fill values are written to a dataset. More...

H5_DLL herr_t	H5Pget_fill_value (hid_t plist_id, hid_t type_id, void *value)
	Retrieves a dataset fill value. More...

H5_DLL H5D_layout_t	H5Pget_layout (hid_t plist_id)
	Returns the layout of the raw data for a dataset. More...

H5_DLL herr_t	H5Pget_virtual_count (hid_t dcpl_id, size_t *count)
	Gets the number of mappings for the virtual dataset. More...

H5_DLL ssize_t	H5Pget_virtual_dsetname (hid_t dcpl_id, size_t index, char *name, size_t size)
	Gets the name of a source dataset used in the mapping. More...

H5_DLL ssize_t	H5Pget_virtual_filename (hid_t dcpl_id, size_t index, char *name, size_t size)
	Gets the filename of a source dataset used in the mapping. More...

H5_DLL hid_t	H5Pget_virtual_srcspace (hid_t dcpl_id, size_t index)
	Gets a dataspace identifier for the selection within the source dataset used in the mapping. More...

H5_DLL hid_t	H5Pget_virtual_vspace (hid_t dcpl_id, size_t index)
	Gets a dataspace identifier for the selection within the virtual dataset used in the mapping. More...

H5_DLL herr_t	H5Pset_alloc_time (hid_t plist_id, H5D_alloc_time_t alloc_time)
	Sets the timing for storage space allocation. More...

H5_DLL herr_t	H5Pset_chunk (hid_t plist_id, int ndims, const hsize_t dim[])
	Sets the size of the chunks used to store a chunked layout dataset. More...

H5_DLL herr_t	H5Pset_layout (hid_t plist_id, H5D_layout_t layout)
	Sets the type of storage used to store the raw data for a dataset. More...

H5_DLL herr_t	H5Pset_szip (hid_t plist_id, unsigned options_mask, unsigned pixels_per_block)
	Sets up use of the SZIP compression filter. More...

herr_t	H5Pset_chunk_opts (hid_t plist_id, unsigned opts)
	Sets the edge chunk option in a dataset creation property list. More...

herr_t	H5Pset_dset_no_attrs_hint (hid_t dcpl_id, hbool_t minimize)
	Sets the flag to create minimized dataset object headers. More...

herr_t	H5Pset_external (hid_t plist_id, const char *name, off_t offset, hsize_t size)
	Adds an external file to the list of external files. More...

herr_t	H5Pset_fill_time (hid_t plist_id, H5D_fill_time_t fill_time)
	Sets the time when fill values are written to a dataset. More...

herr_t	H5Pset_fill_value (hid_t plist_id, hid_t type_id, const void *value)
	Sets the fill value for a dataset. More...

herr_t	H5Pset_shuffle (hid_t plist_id)
	Sets up use of the shuffle filter. More...

Detailed Description

Function Documentation

◆ H5Pfill_value_defined()

herr_t H5Pfill_value_defined	(	hid_t	plist,
		H5D_fill_value_t *	status
	)

Determines whether fill value is defined.

Parameters

[in]	plist	Dataset creation property list identifier
[out]	status	Status of fill value in property list

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pfill_value_defined() determines whether a fill value is defined in the dataset creation property list plist. Valid values returned in status are as follows:

H5D_FILL_VALUE_UNDEFINED	Fill value is undefined.
H5D_FILL_VALUE_DEFAULT	Fill value is the library default.
H5D_FILL_VALUE_USER_DEFINED	Fill value is defined by the application.

Since: 1.6.0

◆ H5Pget_alloc_time()

herr_t H5Pget_alloc_time	(	hid_t	plist_id,
		H5D_alloc_time_t *	alloc_time
	)

Retrieves the timing for storage space allocation.

Parameters

[in]	plist_id	Dataset creation property list identifier
[out]	alloc_time	The timing setting for allocating dataset storage space

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pget_alloc_time() retrieves the timing for allocating storage space for a dataset's raw data. This property is set in the dataset creation property list plist_id. The timing setting is returned in alloc_time as one of the following values:

H5D_ALLOC_TIME_DEFAULT	Uses the default allocation time, based on the dataset storage method. See the `alloc_time` description in H5Pset_alloc_time() for default allocation times for various storage methods.
H5D_ALLOC_TIME_EARLY	All space is allocated when the dataset is created.
H5D_ALLOC_TIME_INCR	Space is allocated incrementally as data is written to the dataset.
H5D_ALLOC_TIME_LATE	All space is allocated when data is first written to the dataset.

Note: H5Pget_alloc_time() is designed to work in concert with the dataset fill value and fill value write time properties, set with the functions H5Pget_fill_value() and H5Pget_fill_time().

Since: 1.6.0

◆ H5Pget_chunk()

int H5Pget_chunk	(	hid_t	plist_id,
		int	max_ndims,
		hsize_t	dim[]
	)

Retrieves the size of chunks for the raw data of a chunked layout dataset.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	max_ndims	Size of the `dims` array
[out]	dim	Array to store the chunk dimensions

Returns: Returns chunk dimensionality if successful; otherwise returns a negative value.

H5Pget_chunk() retrieves the size of chunks for the raw data of a chunked layout dataset. This function is only valid for dataset creation property lists. At most, max_ndims elements of dim will be initialized.

Since: 1.0.0

◆ H5Pget_chunk_opts()

herr_t H5Pget_chunk_opts	(	hid_t	plist_id,
		unsigned *	opts
	)

Retrieves the edge chunk option setting from a dataset creation property list.

Parameters

[in]	plist_id	Dataset creation property list identifier
[out]	opts	Edge chunk option flag. Valid values are described in H5Pset_chunk_opts(). The option status can be retrieved using the bitwise AND operator ( & ). For example, the expression (opts&H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS) will evaluate to H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS if that option has been enabled. Otherwise, it will evaluate to 0 (zero).

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pget_chunk_opts() retrieves the edge chunk option setting stored in the dataset creation property list plist_id.

Since: 1.10.0

◆ H5Pget_dset_no_attrs_hint()

herr_t H5Pget_dset_no_attrs_hint	(	hid_t	dcpl_id,
		hbool_t *	minimize
	)

Retrieves the setting for whether or not to create minimized dataset object headers.

Parameters

[in]	dcpl_id	Dataset creation property list identifier
[out]	minimize	Flag indicating whether the library will or will not create minimized dataset object headers

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pget_dset_no_attrs_hint() retrieves the no dataset attributes hint setting for the dataset creation property list dcpl_id. This setting is used to inform the library to create minimized dataset object headers when TRUE. The setting value is returned in the boolean pointer minimize.

Since: 1.10.5

◆ H5Pget_external()

herr_t H5Pget_external	(	hid_t	plist_id,
		unsigned	idx,
		size_t	name_size,
		char *	name,
		off_t *	offset,
		hsize_t *	size
	)

Returns information about an external file.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	idx	External file index
[in]	name_size	Maximum length of `name` array
[out]	name	Name of the external file
[out]	offset	Pointer to a location to return an offset value
[out]	size	Pointer to a location to return the size of the external file data

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

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.

Version: 1.6.4 idx parameter type changed to unsigned.

Since: 1.0.0

◆ H5Pget_external_count()

int H5Pget_external_count ( hid_t plist_id )

Returns the number of external files for a dataset.

Parameters

[in] plist_id Dataset creation property list identifier

Returns: Returns the number of external files if successful; otherwise returns a negative value.

H5Pget_external_count() returns the number of external files for the specified dataset.

Since: 1.0.0

◆ H5Pget_fill_time()

herr_t H5Pget_fill_time	(	hid_t	plist_id,
		H5D_fill_time_t *	fill_time
	)

Retrieves the time when fill values are written to a dataset.

Parameters

[in]	plist_id	Dataset creation property list identifier
[out]	fill_time	Setting for the timing of writing fill values to the dataset

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pget_fill_time() examines the dataset creation property list plist_id to determine when fill values are to be written to a dataset. Valid values returned in fill_time are as follows:

H5D_FILL_TIME_IFSET	Fill values are written to the dataset when storage space is allocated only if there is a user-defined fill value, i.e., one set with H5Pset_fill_value(). (Default)
H5D_FILL_TIME_ALLOC	Fill values are written to the dataset when storage space is allocated.
H5D_FILL_TIME_NEVER	Fill values are never written to the dataset.

Note: H5Pget_fill_time() is designed to work in coordination with the dataset fill value and dataset storage allocation time properties, retrieved with the functions H5Pget_fill_value() and H5Pget_alloc_time().

Since: 1.6.0

◆ H5Pget_fill_value()

herr_t H5Pget_fill_value	(	hid_t	plist_id,
		hid_t	type_id,
		void *	value
	)

Retrieves a dataset fill value.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	type_id	Datatype identifier for the value passed via `value`
[out]	value	Pointer to buffer to contain the returned fill value

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pget_fill_value() returns the dataset fill value defined in the dataset creation property list plist_id. The fill value is returned through the value pointer and will be converted to the datatype specified by type_id. This datatype may differ from the fill value datatype in the property list, but the HDF5 library must be able to convert between the two datatypes.

If the fill value is undefined, i.e., set to NULL in the property list, H5Pget_fill_value() will return an error. H5Pfill_value_defined() should be used to check for this condition before H5Pget_fill_value() is called.

Memory must be allocated by the calling application.

Note: H5Pget_fill_value() is designed to coordinate with the dataset storage allocation time and fill value write time properties, which can be retrieved with the functions H5Pget_alloc_time() and H5Pget_fill_time(), respectively.

Since: 1.0.0

◆ H5Pget_layout()

H5D_layout_t H5Pget_layout ( hid_t plist_id )

Returns the layout of the raw data for a dataset.

Parameters

[in] plist_id Dataset creation property list identifier

Returns

Returns the layout type (a non-negative value) of a dataset creation property list if successful. Valid return values are:

H5D_COMPACT: Raw data is stored in the object header in the file.
H5D_CONTIGUOUS: Raw data is stored separately from the object header in one contiguous chunk in the file.
H5D_CHUNKED: Raw data is stored separately from the object header in chunks in separate locations in the file.
H5D_VIRTUAL: Raw data is drawn from multiple datasets in different files.

Otherwise, returns a negative value indicating failure.

H5Pget_layout() returns the layout of the raw data for a dataset. This function is only valid for dataset creation property lists.

Note that a compact storage layout may affect writing data to the dataset with parallel applications. See the H5Dwrite() documentation for details.

Version: 1.10.0 H5D_VIRTUAL added in this release.

Since: 1.0.0

◆ H5Pget_virtual_count()

herr_t H5Pget_virtual_count	(	hid_t	dcpl_id,
		size_t *	count
	)

Gets the number of mappings for the virtual dataset.

Parameters

[in]	dcpl_id	Dataset creation property list identifier
[out]	count	The number of mappings

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pget_virtual_count() gets the number of mappings for a virtual dataset that has the creation property list specified by dcpl_id.

See also

Supporting Functions:

VDS Functions:

Since: 1.10.0

◆ H5Pget_virtual_dsetname()

ssize_t H5Pget_virtual_dsetname	(	hid_t	dcpl_id,
		size_t	index,
		char *	name,
		size_t	size
	)

Gets the name of a source dataset used in the mapping.

Parameters

[in]	dcpl_id	Dataset creation property list identifier
[in]	index	Mapping index. The value of `index` is 0 (zero) or greater and less than `count` (0 ≤ `index` < `count`), where `count` is the number of mappings returned by H5Pget_virtual_count().
[out]	name	A buffer containing the name of the source dataset
[in]	size	The size, in bytes, of the name buffer. Must be the size of the dataset name in bytes plus 1 for a NULL terminator

Returns: Returns the length of the dataset name if successful; otherwise returns a negative value.

H5Pget_virtual_dsetname() takes the dataset creation property list for the virtual dataset, dcpl_id, the mapping index, index, the size of the dataset name for a source dataset, size, and retrieves the name of the source dataset used in the mapping.

Up to size characters of the dataset name are returned in name; additional characters, if any, are not returned to the user application.

If the length of the dataset name, which determines the required value of size, is unknown, a preliminary call to H5Pget_virtual_dsetname() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the dataset name. That value, plus 1 for a NULL terminator, must then be assigned to size for a second H5Pget_virtual_dsetname() call, which will retrieve the actual dataset name.

See also

Supporting Functions:

VDS Functions:

Since: 1.10.0

◆ H5Pget_virtual_filename()

ssize_t H5Pget_virtual_filename	(	hid_t	dcpl_id,
		size_t	index,
		char *	name,
		size_t	size
	)

Gets the filename of a source dataset used in the mapping.

Parameters

[in]	dcpl_id	Dataset creation property list identifier
[in]	index	Mapping index. The value of `index` is 0 (zero) or greater and less than `count` (0 ≤ `index` < `count`), where `count` is the number of mappings returned by H5Pget_virtual_count().
[out]	name	A buffer containing the name of the file containing the source dataset
[in]	size	The size, in bytes, of the name buffer. Must be the size of the filename in bytes plus 1 for a NULL terminator

Returns: Returns the length of the filename if successful; otherwise returns a negative value.

H5Pget_virtual_filename() takes the dataset creation property list for the virtual dataset, dcpl_id, the mapping index, index, the size of the filename for a source dataset, size, and retrieves the name of the file for a source dataset used in the mapping.

Up to size characters of the filename are returned in name; additional characters, if any, are not returned to the user application.

If the length of the filename, which determines the required value of size, is unknown, a preliminary call to H5Pget_virtual_filename() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the filename. That value, plus 1 for a NULL terminator, must then be assigned to size for a second H5Pget_virtual_filename() call, which will retrieve the actual filename.

See also

Supporting Functions:

VDS Functions:

Since: 1.10.0

◆ H5Pget_virtual_srcspace()

hid_t H5Pget_virtual_srcspace	(	hid_t	dcpl_id,
		size_t	index
	)

Gets a dataspace identifier for the selection within the source dataset used in the mapping.

Parameters

[in]	dcpl_id	Dataset creation property list identifier
[in]	index	Mapping index. The value of `index` is 0 (zero) or greater and less than `count` (0 ≤ `index` < `count`), where `count` is the number of mappings returned by H5Pget_virtual_count().

Returns: Returns a valid dataspace identifier identifier if successful; otherwise returns H5I_INVALID_HID.

H5Pget_virtual_srcspace() takes the dataset creation property list for the virtual dataset, dcpl_id, and the mapping index, index, and returns a dataspace identifier for the selection within the source dataset used in the mapping.

See also

Supporting Functions:

VDS Functions:

Since: 1.10.0

◆ H5Pget_virtual_vspace()

hid_t H5Pget_virtual_vspace	(	hid_t	dcpl_id,
		size_t	index
	)

Gets a dataspace identifier for the selection within the virtual dataset used in the mapping.

Parameters

[in]	dcpl_id	Dataset creation property list identifier
[in]	index	Mapping index. The value of `index` is 0 (zero) or greater and less than `count` (0 ≤ `index` < `count`), where `count` is the number of mappings returned by H5Pget_virtual_count()

Returns: Returns a valid dataspace identifier identifier if successful; otherwise returns H5I_INVALID_HID.

H5Pget_virtual_vspace() takes the dataset creation property list for the virtual dataset, dcpl_id, and the mapping index, index, and returns a dataspace identifier for the selection within the virtual dataset used in the mapping.

See also

Supporting Functions:

VDS Functions:

Since: 1.10.0

◆ H5Pset_alloc_time()

herr_t H5Pset_alloc_time	(	hid_t	plist_id,
		H5D_alloc_time_t	alloc_time
	)

Sets the timing for storage space allocation.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	alloc_time	When to allocate dataset storage space

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pset_alloc_time() sets up the timing for the allocation of storage space for a dataset's raw data. This property is set in the dataset creation property list plist_id. Timing is specified in alloc_time with one of the following values:

H5D_ALLOC_TIME_DEFAULT	Allocate dataset storage space at the default time (Defaults differ by storage method.)
H5D_ALLOC_TIME_EARLY	Allocate all space when the dataset is created (Default for compact datasets.)
H5D_ALLOC_TIME_INCR	Allocate space incrementally, as data is written to the dataset (Default for chunked storage datasets.) Chunked datasets: Storage space allocation for each chunk is deferred until data is written to the chunk. Contiguous datasets: Incremental storage space allocation for contiguous data is treated as late allocation. Compact datasets: Incremental allocation is not allowed with compact datasets; H5Pset_alloc_time() will return an error.
H5D_ALLOC_TIME_LATE	Allocate all space when data is first written to the dataset (Default for contiguous datasets.)

Note: H5Pset_alloc_time() is designed to work in concert with the dataset fill value and fill value write time properties, set with the functions H5Pset_fill_value() and H5Pset_fill_time().; See H5Dcreate() for further cross-references.

Since: 1.6.0

◆ H5Pset_chunk()

herr_t H5Pset_chunk	(	hid_t	plist_id,
		int	ndims,
		const hsize_t	dim[]
	)

Sets the size of the chunks used to store a chunked layout dataset.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	ndims	The number of dimensions of each chunk
[in]	dim	An array defining the size, in dataset elements, of each chunk

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pset_chunk() sets the size of the chunks used to store a chunked layout dataset. This function is only valid for dataset creation property lists.

The ndims parameter currently must be the same size as the rank of the dataset.

The values of the dim array define the size of the chunks to store the dataset's raw data. The unit of measure for dim values is dataset elements.

As a side-effect of this function, the layout of the dataset is changed to H5D_CHUNKED, if it is not already so set.

Note

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 2³²-1 which is equal to 4,294,967,295. If the number of elements in a chunk is set via H5Pset_chunk() to a value greater than 2³²-1, then H5Pset_chunk() will fail.
The maximum size for any chunk is 4GB. If a chunk that is larger than 4GB attempts to be written with H5Dwrite(), then H5Dwrite() will fail.

See also: H5Pset_layout(), H5Dwrite()

Since: 1.0.0

◆ H5Pset_chunk_opts()

herr_t H5Pset_chunk_opts	(	hid_t	plist_id,
		unsigned	opts
	)

Sets the edge chunk option in a dataset creation property list.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	opts	Edge chunk option flag. Valid values are: H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS When enabled, filters are not applied to partial edge chunks. When disabled, partial edge chunks are filtered. Enabling this option will improve performance when appending to the dataset and, when compression filters are used, prevent reallocation of these chunks. Datasets created with this option enabled will be inaccessible with HDF5 library versions before Release 1.10. Default: Disabled 0 (zero) Disables option; partial edge chunks will be compressed.

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pset_chunk_opts() sets the edge chunk option in the dataset creation property list dcpl_id.

The available option is detailed in the parameters section. Only chunks that are not completely filled by the dataset’s dataspace are affected by this option. Such chunks are referred to as partial edge chunks.

Note: Motivation: H5Pset_chunk_opts() is used to specify storage options for chunks on the edge of a dataset’s dataspace. This capability allows the user to tune performance in cases where the dataset size may not be a multiple of the chunk size and the handling of partial edge chunks can impact performance.

Since: 1.10.0

◆ H5Pset_dset_no_attrs_hint()

herr_t H5Pset_dset_no_attrs_hint	(	hid_t	dcpl_id,
		hbool_t	minimize
	)

Sets the flag to create minimized dataset object headers.

Parameters

[in]	dcpl_id	Dataset creation property list identifier
[in]	minimize	Flag for indicating whether or not a dataset's object header will be minimized

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pset_dset_no_attrs_hint() sets the no dataset attributes hint setting for the dataset creation property list dcpl_id. Datasets created with the dataset creation property list dcpl_id will have their object headers minimized if the boolean flag minimize is set to TRUE. By setting minimize to TRUE, the library expects that no attributes will be added to the dataset. Attributes can be added, but they are appended with a continuation message, which can reduce performance.

This setting interacts with H5Fset_dset_no_attrs_hint(): if either is set to TRUE, then the created dataset's object header will be minimized.

Since: 1.10.5

◆ H5Pset_external()

herr_t H5Pset_external	(	hid_t	plist_id,
		const char *	name,
		off_t	offset,
		hsize_t	size
	)

Adds an external file to the list of external files.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	name	Name of an external file
[in]	offset	Offset, in bytes, from the beginning of the file to the location in the file where the data starts
[in]	size	Number of bytes reserved in the file for the data

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

The first call to H5Pset_external() sets the external storage property in the property list, thus designating that the dataset will be stored in one or more non-HDF5 file(s) external to the HDF5 file. This call also adds the file name as the first file in the list of external files. Subsequent calls to the function add the named file as the next file in the list.

If a dataset is split across multiple files, then the files should be defined in order. The total size of the dataset is the sum of the size arguments for all the external files. If the total size is larger than the size of a dataset then the dataset can be extended (provided the data space also allows the extending).

The size argument specifies the number of bytes reserved for data in the external file. If size is set to H5F_UNLIMITED, the external file can be of unlimited size and no more files can be added to the external files list. If size is set to 0 (zero), no external file will actually be created.

All of the external files for a given dataset must be specified with H5Pset_external() before H5Dcreate() is called to create the dataset. If one these files does not exist on the system when H5Dwrite() is called to write data to it, the library will create the file.

Since: 1.0.0

◆ H5Pset_fill_time()

herr_t H5Pset_fill_time	(	hid_t	plist_id,
		H5D_fill_time_t	fill_time
	)

Sets the time when fill values are written to a dataset.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	fill_time	When to write fill values to a dataset

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pset_fill_time() sets up the timing for writing fill values to a dataset. This property is set in the dataset creation property list plist_id. Timing is specified in fill_time with one of the following values:

H5D_FILL_TIME_IFSET	Write fill values to the dataset when storage space is allocated only if there is a user-defined fill value, i.e.,one set with H5Pset_fill_value(). (Default)
H5D_FILL_TIME_ALLOC	Write fill values to the dataset when storage space is allocated.
H5D_FILL_TIME_NEVER	Never write fill values to the dataset.

Note: H5Pset_fill_time() is designed for coordination with the dataset fill value and dataset storage allocation time properties, set with the functions H5Pset_fill_value() and H5Pset_alloc_time(). See H5Dcreate() for further cross-references.

Since: 1.6.0

◆ H5Pset_fill_value()

herr_t H5Pset_fill_value	(	hid_t	plist_id,
		hid_t	type_id,
		const void *	value
	)

Sets the fill value for a dataset.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	type_id	Datatype of `value`
[in]	value	Pointer to buffer containing value to use as fill value

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pset_fill_value() sets the fill value for a dataset in the dataset creation property list. value is interpreted as being of datatype type_id. This datatype may differ from that of the dataset, but the HDF5 library must be able to convert value to the dataset datatype when the dataset is created.

The default fill value is 0 (zero), which is interpreted according to the actual dataset datatype.

Setting value to NULL indicates that the fill value is to be undefined.

Note: 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 H5Dfill() and H5Pset_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_value() is designed to work in concert with H5Pset_alloc_time() and H5Pset_fill_time(). H5Pset_alloc_time() and H5Pset_fill_time() govern the timing of dataset storage allocation and fill value write operations and can be important in tuning application performance.; See H5Dcreate() for further cross-references.

Since: 1.0.0

◆ H5Pset_layout()

herr_t H5Pset_layout	(	hid_t	plist_id,
		H5D_layout_t	layout
	)

Sets the type of storage used to store the raw data for a dataset.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	layout	Type of storage layout for raw data

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pset_layout() sets the type of storage used to store the raw data for a dataset. This function is only valid for dataset creation property lists.

Valid values for layout are:

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.
H5D_VIRTUAL: Draw raw data from multiple datasets in different files.

Note that a compact storage layout may affect writing data to the dataset with parallel applications. See the note in H5Dwrite() documentation for details.

Version: 1.10.0 H5D_VIRTUAL added in this release.

Since: 1.0.0

◆ H5Pset_shuffle()

herr_t H5Pset_shuffle ( hid_t plist_id )

Sets up use of the shuffle filter.

Parameters

[in] plist_id Dataset creation property list identifier

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pset_shuffle() sets the shuffle filter, H5Z_FILTER_SHUFFLE, in the dataset creation property list plist_id. The shuffle filter de-interlaces a block of data by reordering the bytes. All the bytes from one consistent byte position of each data element are placed together in one block; all bytes from a second consistent byte position of each data element are placed together a second block; etc. For example, given three data elements of a 4-byte datatype stored as 012301230123, shuffling will re-order data as 000111222333. This can be a valuable step in an effective compression algorithm because the bytes in each byte position are often closely related to each other and putting them together can increase the compression ratio.

As implied above, the primary value of the shuffle filter lies in its coordinated use with a compression filter; it does not provide data compression when used alone. When the shuffle filter is applied to a dataset immediately prior to the use of a compression filter, the compression ratio achieved is often superior to that achieved by the use of a compression filter without the shuffle filter.

Since: 1.6.0

◆ H5Pset_szip()

herr_t H5Pset_szip	(	hid_t	plist_id,
		unsigned	options_mask,
		unsigned	pixels_per_block
	)

Sets up use of the SZIP compression filter.

Parameters

[in]	plist_id	Dataset creation property list identifier
[in]	options_mask	A bit-mask conveying the desired SZIP options; Valid values are H5_SZIP_EC_OPTION_MASK and H5_SZIP_NN_OPTION_MASK.
[in]	pixels_per_block	The number of pixels or data elements in each data block

Returns: Returns a non-negative value if successful; otherwise returns a negative value.

H5Pset_szip() sets an SZIP compression filter, H5Z_FILTER_SZIP, for a dataset. SZIP is a compression method designed for use with scientific data.

Before proceeding, all users should review the “Limitations” section below.

Users familiar with SZIP outside the HDF5 context may benefit from reviewing the Note “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_pixel value (see Note, 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 Note, below, for further discussion of the the SZIP bits_per_pixel setting.

SZIP options are passed in an options mask, options_mask, as follows.

Option	Description (Mutually exclusive; select one.)
H5_SZIP_EC_OPTION_MASK	Selects entropy coding method
H5_SZIP_NN_OPTION_MASK	Selects nearest neighbor coding method

The following guidelines can be used in determining which option to select:

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.

Other factors may affect results, but the above criteria provides a good starting point for optimizing data compression.

SZIP compresses data block by block, with a user-tunable block size. This block size is passed in the parameter pixels_per_block and must be even and not greater than 32, with typical values being 8, 10, 16, or 32. This parameter affects compression ratio; the more pixel values vary, the smaller this number should be to achieve better performance.

In HDF5, compression can be applied only to chunked datasets. If pixels_per_block is bigger than the total number of elements in a dataset chunk, H5Pset_szip() will succeed but the subsequent call to H5Dcreate() will fail; the conflict 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_block where N is the maximum number of blocks per scan line allowed by the SZIP library. In the current version of SZIP, N is set to 128.

SZIP compression is an optional HDF5 filter.

Limitations:

SZIP compression cannot be applied to compound, array, variable-length, enumeration, or any other user-defined datatypes. If an SZIP filter is set in a dataset creation property list used to create a dataset containing a non-allowed datatype, the call to H5Dcreate() will 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 by reviewing the SZIP copyright notice.

Note

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 compressed
bits_per_pixel, the number of bits per pixel
pixels_per_scanline, the number of pixels per scan line

These values need not be independently supplied in the HDF5 environment as they are derived from the datatype and dataspace, which are already known. In particular, HDF5 sets pixels_in_object to the number of elements in a chunk and bits_per_pixel to the size of the element or pixel datatype.

The following algorithm is used to set pixels_per_scanline:

If the size of a chunk's fastest-changing dimension, size, is greater than 4K, set pixels_per_scanline to 128 times pixels_per_block.
If size is less than 4K but greater than pixels_per_block, set pixels_per_scanline to the minimum of size and 128 times pixels_per_block.
If size is less than pixels_per_block but greater than the number elements in the chunk, set pixels_per_scanline to the minimum of the number elements in the chunk and 128 times pixels_per_block.

The HDF5 datatype may have precision that is less than the full size of the data element, e.g., an 11-bit integer can be defined using H5Tset_precision(). To a certain extent, SZIP can take advantage of the precision of the datatype to improve compression:

If the HDF5 datatype size is 24-bit or less and the offset of the bits in the HDF5 datatype is zero (see H5Tset_offset() or H5Tget_offset()), the data is the in lowest N bits of the data element. In this case, the SZIP bits_per_pixel is set to the precision of the HDF5 datatype.
If the offset is not zero, the SZIP bits_per_pixel will 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_pixel will be set to 32.
If the HDF5 datatype precision is 33-bit to 64-bit, the SZIP bits_per_pixel will be set to 64.

HDF5 always modifies the options mask provided by the user to set up usage of RAW_OPTION_MASK, ALLOW_K13_OPTION_MASK, and one of LSB_OPTION_MASK or MSB_OPTION_MASK, depending on endianness of the datatype.

Since: 1.6.0