Generic Properties Overview and Justification

It is useful to allow "drivers" (VFL, VDL, datatype conversion, etc.) to create properties for controlling features they wish to add to the library. Allowing a driver to create properties when installed at run-time will enable new features to be easily created and controlled while localizing the changes to just the section of code being modified or added. This should allow easier maintainence and evolution of the library's properties in future versions of the library code.

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

New Functions: Removed Functions:
H5Pcreate and H5Pclose are replaced with H5Pcreate_list and H5Pclose_list.
Changes to Existing Functions:
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)

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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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)

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)

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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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)

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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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:

where the parameters to the callback function are: 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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

RETURNS

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:

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:

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)

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)

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)

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)

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)

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:

Example #1: Register a new property for future dataset creation property lists. This property uses a "set" callback to range check the values for the property. This set of features would likely be used with Virtual File or Dataset drivers. This example also shows how get/set API functions for the property registered might work.
/* 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");
}


QAK:9/10/01