General Property List Operations

Detailed Description

Use the functions in this module to manage HDF5 property lists.

Create	Read
{ __label__ fail_dcpl; hid_t dcpl; // every property list is created as an instance of a suitable // property list class if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_dcpl; } // ... H5Pclose(dcpl); fail_dcpl:; }	{ __label__ fail_dcpl, fail_plist_cls_id; hid_t dcpl, plist_cls_id; if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_dcpl; } // to perform introspection on any kind of property list, // we need to determine its property list class by obtaining a handle if ((plist_cls_id = H5Pget_class(dcpl)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_plist_cls_id; } // Compare the handle to the handles of built-in or user-defined // property list classes assert(H5Pequal(plist_cls_id, H5P_DATASET_CREATE) > 0); fail_plist_cls_id: H5Pclose(dcpl); fail_dcpl:; }
Update	Delete
{ __label__ fail_dcpl, fail_prop; hid_t dcpl; if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_dcpl; } // a property list is updated by adding (or removing) properties if (H5Pset_fill_time(dcpl, H5D_FILL_TIME_NEVER) < 0) { ret_val = EXIT_FAILURE; goto fail_prop; } fail_prop: H5Pclose(dcpl); fail_dcpl:; }	{ __label__ fail_dcpl; hid_t dcpl; if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; goto fail_dcpl; } // a property list is "deleted" by closing it H5Pclose(dcpl); fail_dcpl:; }

Functions
herr_t	H5Pclose (hid_t plist_id)
	Terminates access to a property list. More...
hid_t	H5Pcopy (hid_t plist_id)
	Copies an existing property list to create a new property list. More...
hid_t	H5Pcreate (hid_t cls_id)
	Creates a new property list as an instance of a property list class. More...
hid_t	H5Pget_class (hid_t plist_id)
	Returns the property list class identifier for a property list. More...

Function Documentation

H5Pclose()

herr_t H5Pclose

(

hid_t

plist_id

)

Terminates access to a property list.

Parameters

[in]

plist_id

Property list identifier

Returns

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

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.

Since

1.0.0

H5Pcopy()

hid_t H5Pcopy

(

hid_t

plist_id

)

Copies an existing property list to create a new property list.

Parameters

[in]

plist_id

Property list identifier

Returns

Returns a property list identifier if successful; otherwise returns H5I_INVALID_HID.

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.

Since

1.0.0

H5Pcreate()

hid_t H5Pcreate

(

hid_t

cls_id

)

Creates a new property list as an instance of a property list class.

Parameters

[in]

cls_id

Property list class identifier

Returns

Returns a property list identifier if successful; otherwise returns H5I_INVALID_HID.

H5Pcreate() creates a new property list as an instance of some property list class. The new property list is initialized with default values for the specified class. The classes are as follows:

Class Identifier	Class Name	Comments
H5P_ATTRIBUTE_CREATE	attribute create	Properties for attribute creation
H5P_DATASET_ACCESS	dataset access	Properties for dataset access
H5P_DATASET_CREATE	dataset create	Properties for dataset creation
H5P_DATASET_XFER	data transfer	Properties for raw data transfer
H5P_DATATYPE_ACCESS	datatype access	Properties for datatype access
H5P_DATATYPE_CREATE	datatype create	Properties for datatype creation
H5P_FILE_ACCESS	file access	Properties for file access
H5P_FILE_CREATE	file create	Properties for file creation
H5P_FILE_MOUNT	file mount	Properties for file mounting
H5P_GROUP_ACCESS	group access	Properties for group access
H5P_GROUP_CREATE	group create	Properties for group creation
H5P_LINK_ACCESS	link access	Properties governing link traversal when accessing objects
H5P_LINK_CREATE	link create	Properties governing link creation
H5P_OBJECT_COPY	object copy	Properties governing the object copying process
H5P_OBJECT_CREATE	object create	Properties for object creation
H5P_STRING_CREATE	string create	Properties for character encoding when encoding strings or object names

This property list must eventually be closed with H5Pclose(); otherwise, errors are likely to occur.

Version

1.8.15 For each class, the class name returned by H5Pget_class_name() was added. The list of possible Fortran values was updated.

1.8.0 The following property list classes were added at this release: H5P_DATASET_ACCESS, H5P_GROUP_CREATE, H5P_GROUP_ACCESS, H5P_DATATYPE_CREATE, H5P_DATATYPE_ACCESS, H5P_ATTRIBUTE_CREATE

Since

1.0.0

H5Pget_class()

hid_t H5Pget_class

(

hid_t

plist_id

)

Returns the property list class identifier for a property list.

Parameters

[in]

plist_id

Property list identifier

Returns

Returns a property list class identifier if successful; otherwise returns H5I_INVALID_HID.

H5Pget_class() returns the property list class identifier for the property list identified by the plist_id parameter.

Note that H5Pget_class() returns a value of hid_t type, an internal HDF5 identifier, rather than directly returning a property list class. That identifier can then be used with either H5Pequal() or H5Pget_class_name() to determine which predefined HDF5 property list class H5Pget_class() has returned.

A full list of valid predefined property list classes appears in the description of H5Pcreate().

Determining the HDF5 property list class name with H5Pequal() requires a series of H5Pequal() calls in an if-else sequence. An iterative sequence of H5Pequal() calls can compare the identifier returned by H5Pget_class() to members of the list of valid property list class names. A pseudo-code snippet might read as follows:

plist_class_id = H5Pget_class (dsetA_plist);
 
if H5Pequal (plist_class_id, H5P_OBJECT_CREATE) = TRUE;
    [ H5P_OBJECT_CREATE is the property list class    ]
    [ returned by H5Pget_class.                        ]
 
else if H5Pequal (plist_class_id, H5P_DATASET_CREATE) = TRUE;
    [ H5P_DATASET_CREATE is the property list class.  ]
 
else if H5Pequal (plist_class_id, H5P_DATASET_XFER) = TRUE;
    [ H5P_DATASET_XFER is the property list class.    ]
 
.
.   [ Continuing the iteration until a match is found. ]
.

H5Pget_class_name() returns the property list class name directly as a string:

plist_class_id = H5Pget_class (dsetA_plist);
plist_class_name = H5Pget_class_name (plist_class_id)

Note that frequent use of H5Pget_class_name() can become a performance problem in a high-performance environment. The H5Pequal() approach is generally much faster.

Version

1.6.0 Return type changed in this release.

Since

1.0.0