Generic Properties Overview and Justification

It would also be useful to give users the ability to create and set properties which are temporary in nature and do not need to be stored longer than the application is active. These would allow users to set application specific properties which can be set and queried during the application's execution.

Generic Properties Implementation

The existing property list classes would be modified so that the existing properties are generic properties which are registered when the library starts up. The existing property list API functions would become wrappers around the new "generic" get/set functions. This would allow the library to become more modular, with each driver or API registering it's own properties without hard- wiring new fields in the property list class.

The library will provide a default or "empty" property list class with no property values defined for property lists of that class. A mechanism for deriving a new property list class will be defined by inheriting from an existing property list class. The existing property list classes defined by the library (file access, dataset creation, etc) will be created during library initialization and will have global constants available for applications to use. (This is similar to the way the library-defined datatypes are created at run-time)

Users may derive new property list classes from any existing property list class, including the completely new classes derived from the default "empty" property list class, or other user-derived property list classes. User-derived property list classes which are derived from the library-defined classes may be passed to API functions which expect library-defined property lists and the API functions will traverse the inherited classes to find the correct class to retrieve information.

The new generic property list API functions allow properties to be registered for each property list class (library or user defined) to create a set of initial properties for newly created property lists of that class. These registered properties can have default values for each new property list created for that class.

Temporary generic properties can also be attached to any existing property list without affecting new property lists of that class.

Property names beginning with "H5" are reserved for library use and should not be used by third-party applications or libraries.

The names and sizes of property values for each property are local to each property list and changing them in a property list class do not affect existing property lists.

API Changes for Implementing Generic Properties

H5Pcreate_class	-	Create a new property list class.
H5Pcreate_list	-	Create a new property list of a given class.
H5Pregister	-	Register a permanent property with a class.
H5Pinsert	-	Create a temporary property for a property list.
H5Pset	-	Set an existing property (permanent or temporary) to a value.
H5Pexist	-	Query whether a property exists in a property list or class.
H5Pget_size	-	Query size of property value in bytes.
H5Pget_nprops	-	Query number of properties in list or class
H5Pget_class_name	-	Retrieve the name of a class object
H5Pget_class_parent	-	Retrieve a property class's parent class
H5Pisa_class	-	Checks if a property list is a member of a property class
H5Pget	-	Retrieve property value.
H5Pequal	-	Compares two property lists or classes for equality
H5Piterate	-	Iterates over properties in a property class or list
H5Pcopy_prop	-	Copies a property from one list to another
H5Premove	-	Removes a property from a property list.
H5Punregister	-	Un-register a permanent property from a class.
H5Pclose_list	-	Close a property list.
H5Pclose_class	-	Remove a property list class.

H5Pcreate and H5Pclose are replaced with H5Pcreate_list and H5Pclose_list.

All the existing H5Pget/set routines would need to be changed to use the new generic register/unregister and get/set routines for the properties they manage, but that shouldn't be a user-visible change. Also, H5Pget_class will change from returning a H5P_class_t to the ID of a generic property class.

New API Function Definitions

NAME

H5Pcreate_class

PURPOSE

Create a new property list class

USAGE

hid_t H5Pcreate_class(class, name, create, copy, close)

hid_t class;	IN: Property list class to inherit from.
const char *name;	IN: Name of property list class to register.
H5P_cls_create_func_t create;	IN: Callback routine called when a property list is created.
H5P_cls_copy_func_t copy;	IN: Callback routine called when a property list is copied.
H5P_cls_close_func_t close;	IN: Callback routine called when a property list is being closed.

RETURNS

Success: Valid property list class ID

Failure: negative value

DESCRIPTION

Registers a new property list class with the library. The new property list class can inherit from an existing property list class or may be derived from the default "empty" class. New classes with inherited properties from existing classes may not remove those existing properties, only add or remove their own class properties.

The create routine is called when a new property list of this class is being created. The H5P_cls_create_func_t is defined as:

typedef herr_t (*H5P_cls_create_func_t)( hid_t prop_id, void * create_data );

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list being created.
void * create_data;	IN/OUT: User pointer to any class creation information needed

The create routine is called after any registered create function is called for each property value. If the create routine returns a negative value, the new list is not returned to the user and the property list creation routine returns an error value.

The copy routine is called when an existing property list of this class is copied. The H5P_cls_copy_func_t is defined as:

typedef herr_t (*H5P_cls_copy_func_t)( hid_t prop_id, void * copy_data );

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list created by copying.
void * copy_data;	IN/OUT: User pointer to any class copy information needed

The copy routine is called after any registered copy function is called for each property value. If the copy routine returns a negative value, the new list is not returned to the user and the property list copy routine returns an error value.

The close routine is called when a property list of this class is being closed. The H5P_cls_close_func_t is defined as:

typedef herr_t (*H5P_cls_close_func_t)( hid_t prop_id, void * close_data );

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list being closed.
void * close_data;	IN/OUT: User pointer to any class close information needed

The close routine is called before any registered close function is called for each property value. If the close routine returns a negative value, the property list close routine returns an error value but the property list is still closed.

COMMENTS, BUGS, ASSUMPTIONS

I would like to say "the property list is not closed" when a _close_ routine fails, but I don't think that's possible due to other properties in the list being successfully closed & removed from the property list. I suppose that it would be possible to just remove the properties which have successful _close_ callbacks, but I'm not happy with the ramifications of a mangled, un-closable property list hanging around... Any comments?

NAME

H5Pcreate_list

PURPOSE

Create a new property list class of a given class

USAGE

hid_t H5Pcreate_list(class)

hid_t class;

IN: Class of property list to create.

RETURNS

Success: Valid property list ID

Failure: negative value

DESCRIPTION

Creates a property list of a given class. If a create callback exists for the property list class, it is called before the property list is passed back to the user. If create callbacks exist for any individual properties in the property list, they are called before the class create callback.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pregister

PURPOSE

Register a permanent property with a property list class

USAGE

herr_t H5Pregister(class, name, size, default, create, set, get, close)

hid_t class;	IN: Property list class to register permanent property within.
const char * name;	IN: Name of property to register.
size_t size;	IN: Size of property in bytes.
void * default;	IN: Default value for property in newly created property lists.
H5P_prp_create_func_t create;	IN: Callback routine called when a property list is being created and the property value will be initialized.
H5P_prp_set_func_t set;	IN: Callback routine called before a new value is copied into the property's value.
H5P_prp_get_func_t get;	IN: Callback routine called when a property value is retrieved from the property.
H5P_prp_delete_func_t delete;	IN: Callback routine called when a property is deleted from a property list.
H5P_prp_copy_func_t copy;	IN: Callback routine called when a property is copied from in a property list.
H5P_prp_close_func_t close;	IN: Callback routine called when a property list is being closed and the property value will be disposed of.

RETURNS

Success: non-negative value

Failure: negative value

DESCRIPTION

Registers a new property with a property list class. The property will exist in all property list objects of class created after this routine finishes. The name of the property must not already exist, or this routine will fail. The default property value must be provided and all new property lists created with this property will have the property value set to the default value. Any of the callback routines may be set to NULL if they are not needed.

Zero-sized properties are allowed and do not store any data in the property list. These may be used as flags to indicate the presence or absence of a particular piece of information. The 'default' pointer for a zero-sized property may be set to NULL. The property 'create' & 'close' callbacks are called for zero-sized properties, but the 'set' and 'get' callbacks are never called.

The create routine is called when a new property list with this property is being created. H5P_prp_create_func_t is defined as:

typedef herr_t (*H5P_prp_create_func_t)( const char *name, size_t size, void *initial_value);

where the parameters to the callback function are:

const char * name;	IN: The name of the property being modified.
size_t size;	IN: The size of the property in bytes.
void * initial_value;	IN/OUT: The default value for the property being created. (The default value passed to H5Pregister)

The create routine may modify the value to be set and those changes will be stored as the initial value of the property. If the create routine returns a negative value, the new property value is not copied into the property and the create routine returns an error value.

The set routine is called before a new value is copied into the property. H5P_prp_set_func_t is defined as:

typedef herr_t (*H5P_prp_set_func_t)( hid_t prop_id, const char *name, size_t size, void *new_value);

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list being modified.
const char * name;	IN: The name of the property being modified.
size_t size;	IN: The size of the property in bytes.
void ** new_value;	IN/OUT: Pointer to new value pointer for the property being modified.

The set routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the set routine returns a negative value, the new property value is not copied into the property and the set routine returns an error value. The set routine will not be called for the initial value, only the create routine will be called.

The get routine is called when a value is retrieved from a property value. H5P_prp_get_func_t is defined as:

typedef herr_t (*H5P_prp_get_func_t)( hid_t prop_id, const char *name, size_t size, void *value);

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list being queried.
const char * name;	IN: The name of the property being queried.
size_t size;	IN: The size of the property in bytes.
void * value;	IN/OUT: The value of the property being returned.

The get routine may modify the value to be returned from the query and those changes will be returned to the calling routine. If the set routine returns a negative value, the query routine returns an error value.

The delete routine is called when a property is being deleted from a property list. H5P_prp_delete_func_t is defined as:

typedef herr_t (*H5P_prp_delete_func_t)( hid_t prop_id, const char *name, size_t size, void *value);

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list the property is being deleted from.
const char * name;	IN: The name of the property in the list.
size_t size;	IN: The size of the property in bytes.
void * value;	IN: The value for the property being deleted.

The delete routine may modify the value passed in, but the value is not used by the library when the delete routine returns. If the delete routine returns a negative value, the property list delete routine returns an error value but the property is still deleted.

The copy routine is called when a new property list with this property is being created through a copy operation. H5P_prp_copy_func_t is defined as:

typedef herr_t (*H5P_prp_copy_func_t)( const char *name, size_t size, void *value);

where the parameters to the callback function are:

const char * name;	IN: The name of the property being copied.
size_t size;	IN: The size of the property in bytes.
void * value;	IN/OUT: The value for the property being copied.

The copy routine may modify the value to be set and those changes will be stored as the new value of the property. If the copy routine returns a negative value, the new property value is not copied into the property and the copy routine returns an error value.

The close routine is called when a property list with this property is being closed. H5P_prp_close_func_t is defined as:

typedef herr_t (*H5P_prp_close_func_t)( hid_t prop_id, const char *name, size_t size, void *value);

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list being closed.
const char * name;	IN: The name of the property in the list.
size_t size;	IN: The size of the property in bytes.
void * value;	IN: The value for the property being closed.

The close routine may modify the value passed in, but the value is not used by the library when the close routine returns. If the close routine returns a negative value, the property list close routine returns an error value but the property list is still closed.

COMMENTS, BUGS, ASSUMPTIONS

The set callback function may be useful to range check the value being set for the property or may perform some tranformation/translation of the value set. The get callback would then [probably] reverse the transformation, etc. A single get or set callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.

I would like to say "the property list is not closed" when a close routine fails, but I don't think that's possible due to other properties in the list being successfully closed & removed from the property list. I suppose that it would be possible to just remove the properties which have successful close callbacks, but I'm not happy with the ramifications of a mangled, un-closable property list hanging around... Any comments?

NAME

H5Pinsert

PURPOSE

Register a temporary property with a property list

USAGE

herr_t H5Pinsert(plid, name, size, value, set, get, close)

hid_t plid;	IN: Property list id to create temporary property within.
const char *name;	IN: Name of property to create.
size_t size;	IN: Size of property in bytes.
void *value;	IN: Initial value for the property.
H5P_prp_set_func_t set;	IN: Callback routine called before a new value is copied into the property's value.
H5P_prp_get_func_t get;	IN: Callback routine called when a property value is retrieved from the property.
H5P_prp_delete_func_t delete;	IN: Callback routine called when a property is deleted from a property list.
H5P_prp_copy_func_t copy;	IN: Callback routine called when a property is copied from an existing property list.
H5P_prp_close_func_t close;	IN: Callback routine called when a property list is being closed and the property value will be disposed of.

RETURNS

Success: non-negative value

Failure: negative value

DESCRIPTION

Create a new property in a property list. The property will exist only in this property list and copies made from it. The name of the property must not already exist in this list, or this routine will fail. The initial property value must be provided and the property value will be set to it. The set and get callback routines may be set to NULL if they are not needed.

Zero-sized properties are allowed and do not store any data in the property list. The default value of a zero-size property may be set to NULL. They may be used to indicate the presence or absence of a particular piece of information.

The set routine is called before a new value is copied into the property. The H5P_prp_set_func_t is defined as:

typedef herr_t (*H5P_prp_set_func_t)( hid_t prop_id, const char *name, size_t size, void *new_value);

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list being modified.
const char *name;	IN: The name of the property being modified.
size_t size;	IN: The size of the property in bytes.
void **new_value;	IN: Pointer to new value pointer for the property being modified.

The set routine may modify the value pointer to be set and those changes will be used when setting the property's value. If the set routine returns a negative value, the new property value is not copied into the property and the set routine returns an error value. The set routine will be called for the initial value.

The get routine is called when a value is retrieved from a property value. The H5P_prp_get_func_t is defined as:

typedef herr_t (*H5P_prp_get_func_t)( hid_t prop_id, const char *name, size_t size, void *value);

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list being queried.
const char *name;	IN: The name of the property being queried.
size_t size;	IN: The size of the property in bytes.
void *value;	IN: The value of the property being returned.

The get routine may modify the value to be returned from the query and those changes will be preserved. If the get routine returns a negative value, the query routine returns an error value.

The delete routine is called when a property is being deleted from a property list. H5P_prp_delete_func_t is defined as:

typedef herr_t (*H5P_prp_delete_func_t)( hid_t prop_id, const char *name, size_t size, void *value);

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list the property is being deleted from.
const char * name;	IN: The name of the property in the list.
size_t size;	IN: The size of the property in bytes.
void * value;	IN: The value for the property being deleted.

The delete routine may modify the value passed in, but the value is not used by the library when the delete routine returns. If the delete routine returns a negative value, the property list delete routine returns an error value but the property is still deleted.

The copy routine is called when a new property list with this property is being created through a copy operation. H5P_prp_copy_func_t is defined as:

typedef herr_t (*H5P_prp_copy_func_t)( const char *name, size_t size, void *value);

where the parameters to the callback function are:

const char * name;	IN: The name of the property being copied.
size_t size;	IN: The size of the property in bytes.
void * value;	IN/OUT: The value for the property being copied.

The copy routine may modify the value to be set and those changes will be stored as the new value of the property. If the copy routine returns a negative value, the new property value is not copied into the property and the copy routine returns an error value.

The close routine is called when a property list with this property is being closed. The H5P_prp_close_func_t is defined as:

typedef herr_t (*H5P_prp_close_func_t)( hid_t prop_id, const char *name, size_t size, void *value);

where the parameters to the callback function are:

hid_t prop_id;	IN: The ID of the property list being closed.
const char *name;	IN: The name of the property in the list.
size_t size;	IN: The size of the property in bytes.
void *value;	IN: The value for the property being closed.

The close routine may modify the value passed in, the value is not used by the library when the close routine returns. If the close routine returns a negative value, the property list close routine returns an error value but the property list is still closed.

COMMENTS, BUGS, ASSUMPTIONS

The set callback function may be useful to range check the value being set for the property or may perform some tranformation/translation of the value set. The get callback would then [probably] reverse the transformation, etc. A single get or set callback could handle multiple properties by performing different actions based on the property name or other properties in the property list.

There is no create callback routine for temporary property list objects, the initial value is assumed to have any necessary setup already performed on it.

I would like to say "the property list is not closed" when a close routine fails, but I don't think that's possible due to other properties in the list being successfully closed & removed from the property list. I suppose that it would be possible to just remove the properties which have successful close callbacks, but I'm not happy with the ramifications of a mangled, un-closable property list hanging around... Any comments?

NAME

H5Pset

PURPOSE

Set a property list value

USAGE

herr_t H5Pset(plid, name, value)

hid_t plid;	IN: Property list id to modify
const char *name;	IN: Name of property to modify.
void *value;	IN: Pointer to value to set the property to.

RETURNS

Success: non-negative value

Failure: negative value

DESCRIPTION

Sets a new value for a property in a property list. The property name must exist or this routine will fail. If there is a set callback routine registered for this property, the value will be passed to that routine and any changes to the value will be used when setting the property value. The information pointed at by the value pointer (possibly modified by the set callback) is copied into the property list value and may be changed by the application making the H5Pset call without affecting the property value.

If the set callback routine returns an error, the property value will not be modified. This routine may not be called for zero-sized properties and will return an error in that case.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pexist

PURPOSE

Query if a property name exists in a property list or class

USAGE

htri_t H5Pexist(id, name)

hid_t id;	IN: Property ID to query
const char *name;	IN: Name of property to check for.

RETURNS

Success: Positive if the property exists in the property object, zero if the property does not exist.

Failure: negative value

DESCRIPTION

This routine checks if a property exists within a property list or class.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pget_size

PURPOSE

Query size of property value in bytes

USAGE

int H5Pget_size(id, name, size)

hid_t id;	IN: ID of property object to query
const char *name;	IN: Name of property to query
size_t *size;	OUT: Size of property in bytes

RETURNS

Success: non-negative value

Failure: negative value

DESCRIPTION

This routine retrieves the size of a property's value in bytes. Zero- sized properties are allowed and return 0. This function operates on both poperty lists and property classes

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pget_nprops

PURPOSE

Query number of properties in property list or class

USAGE

int H5Pget_nprops(id, nprops)

hid_t id;	IN: ID of property object to query
size_t *nprops;	OUT: Number of properties in object

RETURNS

Success: non-negative value

Failure: negative value

DESCRIPTION

This routine retrieves the number of properties in a property list or class. If a property class ID is given, the number of registered properties in the class is returned in nprops. If a property list ID is given, the current number of properties in the list is returned in nprops.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pget_class_name

PURPOSE

Retrieve the name of a class

USAGE

char * H5Pget_class_name(pcid)

hid_t pcid;

IN: Property class id to query

RETURNS

Success: Pointer to a malloc'ed string containing the class name

Failure: NULL

DESCRIPTION

This routine retrieves the name of a generic property list class. The pointer to the name must be free'd by the user for successful calls.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pget_class_parent

PURPOSE

Retrieve the parent class of a property class

USAGE

hid_t H5Pget_class_parent(pcid)

hid_t pcid;

IN: Property class ID to query

RETURNS

Success: ID of parent class object

Failure: negative

DESCRIPTION

This routine retrieves an ID for the parent class of a property class.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pisa_class

PURPOSE

Check if a property list is a member of a class

USAGE

htri_t H5Pisa_class(plist, pclass)

hid_t plist;	IN: ID of property list to compare
hid_t pclass;	IN: ID of property class to compare against

RETURNS

Success: TRUE (positive) if equal, FALSE (zero) if unequal

Failure: negative value

DESCRIPTION

This routine checks if a property list is a member of a class.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pget

PURPOSE

Query value of property

USAGE

herr_t H5Pget(plid, name, value)

hid_t plid;	IN: Property list id to query
const char *name;	IN: Name of property to query
void *value;	OUT: Pointer to location to copy value of property retrieved into.

RETURNS

Success: non-negative value.

Failure: negative value

DESCRIPTION

Retrieves a copy of the value for a property in a property list. The property name must exist or this routine will fail. If there is a get callback routine registered for this property, the copy of the value of the property will first be passed to that routine and any changes to the copy of the value will be used when returning the property value from this routine. If the get callback routine returns an error, value will not be modified. This routine may be called for zero-sized properties with the value set to NULL and the get routine will be called with a NULL value if the callback exists.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pequal

PURPOSE

Compare two property lists or classes for equality

USAGE

htri_t H5Pequal(id1, id2)

hid_t id1;	IN: First property object to compare
hid_t id2;	IN: Second property object to compare

RETURNS

Success: TRUE (positive) if equal, FALSE (zero) if unequal

Failure: negative value

DESCRIPTION

This routine determines whether two property lists or classes are equal to one another. Both id1 and id2 must be either property lists or classes, comparing a list to a class is an error.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Piterate

PURPOSE

Iterates over properties in a property class or list

USAGE

int H5Piterate(idass_id, idx, iter_func, iter_data)

hid_t id;	IN: ID of property object to iterate over
int * idx;	IN/OUT: Index of the property to begin with
H5P_iterate_t iter_func;	IN: Function pointer to function to be called with each property iterated over.
void * iter_data;	IN/OUT: Pointer to iteration data from user

RETURNS

Success:	Returns the return value of the last call to iter_func if it was non-zero, or zero if all properties have been processed.
Failure:	negative value

DESCRIPTION

This routine iterates over the properties in the property object specified with ID. The properties in both property lists and classes may be iterated over with this function. For each property in the object, the iter_func and some additional information, specified below, are passed to the iter_func function. The iteration begins with the idx property in the object and the next element to be processed by the operator is returned in idx. If idx is NULL, then the iterator starts at the first property; since no stopping point is returned in this case, the iterator cannot be restarted if one of the calls to its operator returns non-zero.

The prototype for H5P_iterate_t is:

typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data)

The operation receives the property list or class identifier for the object being iterated over, ID, the name of the current property within the object, name, and the pointer to the operator data passed in to H5Piterate, iter_data.

The return values from an operator are:

Zero:	Causes the iterator to continue, returning zero when all properties have been processed.
Positive:	Causes the iterator to immediately return that positive value, indicating short-circuit success. The iterator can be restarted at the index of the next property.
Negative:	Causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the index of the next property.

H5Piterate assumes that the properties in the object identified by ID remains unchanged through the iteration. If the membership changes during the iteration, the function's behavior is undefined.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pcopy_prop

PURPOSE

Copies a property from one list or class to another

USAGE

herr_t H5Pcopy_prop(dst_id, src_id, name)

hid_t dst_id;	IN: ID of destination property list or class
hid_t src_id;	IN: ID of source property list or class
const char *name;	IN: Name of property to copy

RETURNS

Success: non-negative value.

Failure: negative value

DESCRIPTION

Copies a property from one property list or class to another.

If a property is copied from one class to another, all the property information will be first deleted from the destination class and then the property information will be copied from the source class into the destination class.

If a property is copied from one list to another, the property will be first deleted from the destination list (generating a call to the close callback for the property, if one exists) and then the property is copied from the source list to the destination list (generating a call to the copy callback for the property, if one exists).

If the property does not exist in the class or list, this call is equivalent to calling H5Pregister or H5Pinsert (for a class or list, as appropriate) and the create callback will be called in the case of the property being copied into a list (if such a callback exists for the property).

COMMENTS, BUGS, ASSUMPTIONS

NAME

H5Premove

PURPOSE

Removes a property from a property list

USAGE

herr_t H5Premove(plid, name)

hid_t plid;	IN: Property list id to modify
const char *name;	IN: Name of property to remove

RETURNS

Success: non-negative value.

Failure: negative value

DESCRIPTION

Removes a property from a property list. Both properties which were in existance when the property list was created (i.e. properties registered with H5Pregister) and properties added to the list after it was created (i.e. added with H5Pinsert) may be removed from a property list. Properties do not need to be removed a property list before the list itself is closed, they will be released automatically when H5Pclose is called. The close callback for this property is called before the property is release, if the callback exists.

COMMENTS, BUGS, ASSUMPTIONS

NAME

H5Punregister

PURPOSE

Removes a property from a property list class

USAGE

herr_t H5Punregister(class, name)

H5P_class_t class;	IN: Property list class to remove permanent property from.
const char *name;	IN: Name of property to remove

RETURNS

Success: non-negative value.

Failure: negative value

DESCRIPTION

Removes 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.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pclose_list

PURPOSE

Close a property list

USAGE

herr_t H5Pclose_list(plist)

hid_t plist;

IN: Property list to close.

RETURNS

Success: non-negative value

Failure: negative value

DESCRIPTION

Closes a property list. If a close callback exists for the property list class, it is called before the property list is destroyed. If close callbacks exist for any individual properties in the property list, they are called after the class close callback.

COMMENTS, BUGS, ASSUMPTIONS

[?]

NAME

H5Pclose_class

PURPOSE

Closes an existing property list class

USAGE

herr_t H5Pclose_class(class)

hid_t class;

IN: Property list class to close.

RETURNS

Success: non-negative value

Failure: negative value

DESCRIPTION

Removes a property list class from the library. Existing property lists of this class will continue to exist, but new ones are not able to be created.

COMMENTS, BUGS, ASSUMPTIONS

[?]

Examples:

/* Property "set" callback */
herr_t driver_set_check(hid_t prop, const char *name, void *_value)
{
    int *value=(int *)_value;

    /* Check that this routine is called for proper property name */
    if(strcmp(name,"property1"))
        return(-1);

    /* Range check property value */
    if(*value<0 || *value>SOME_LIMIT)
        return(-1);

    /* Name and value are OK */
    return(0);
}

/* An API routine that sets the property for this driver */
herr_t H5Pset_driver_property1(hid_t prop, int value)
{
    /*
     *  Call the generic H5Pset routine and let the "set" callback do the
     *  range checking, etc.
     */
    return(H5Pset(prop, "property1", &value));
}

/* An API routine that gets the property for this driver */
herr_t H5Pget_driver_property1(hid_t prop, int *value)
{
    /* Call the generic H5Pget routine to retrieve the value */
    return(H5Pget(prop, "property1", value));
}

int setup_driver()
{
    int prop1_default=12;       /* Default value for "property1" */

    [Set up other driver information]

    /* Register new property with Dataset Creation property list class */
    /* Provide a "set" callback, but no "get" callback for this property */
    H5Pregister(H5P_DATASET_CREATE, "property1", sizeof(int), &prop1_default,
        driver_set_check, NULL);

}

int shutdown_driver()
{
    [Shut down other driver information]

    /* Unregister property from Dataset Creation property list class */
    H5Punregister(H5P_DATASET_CREATE, "property1");
}