H5L Interface Changes

James Laird and Quincey Koziol 11/9/05

The H5L Interface

The H5L Interface itself will have the following APIs:

herr_t H5Lcreate(hid_t new_loc_id, const char *new_name, hid_t object_id, hid_t lcpl)

The new link creation call. Takes the location ID, the ID of the object to be linked in, the name of the new object, and a Link Creation Property List. The LCPL controls the link type (hard or soft) and the character encoding.

H5Lcreate can only create hard links, since an object is being specified by id.

Formerly, links were created with H5Glink and H5Glink2, which took the link type as a parameter rather than as part of a link creation property list. H5Glink2 also identifies the object to be linked by name rather than by id; this functionality is supported in H5Llink2 below.

herr_t H5Llink( hid_t curr_loc_id, const char *current_name, hid_t new_loc_id, const char *new_name, hid_t lcpl )

Links to an object by name. Very similar to the current H5Glink2, but takes a link creation property list.

An H5Llink function which uses only one location should be created as a high-level API, since it does not add any functionality. This function is H5Llink_simple and is discussed below. It does not use

It might also be appropriate to create high-level functions that would have exactly the same signatures as H5Glink and H5Glink2 so that casual users would not have to construct link creation property lists.

herr_t H5Lmove( hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name )

The new move function's signature is the same as the old H5Gmove2. It will preserve creation time and the creation property list of a link while renaming the link and possibly moving it to a new group.

I propose that the simpler H5Gmove (which assumed that the link's old location and new location were the same) be implemented as a high-level function, rather than as a library function, since it is just a special case of the call above.

herr_t H5Lmove( hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t lcpl )

herr_t H5Lrename( hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t lcpl )

To emphasize that groups are "bins" for holding links, the functionality of H5Gmove has been split into two functions, H5Lmove and H5Lrename. H5Lmove will move links between groups without altering the links, and H5Lrename will change links' names without relocating the links. Another option would be to combine these into a single more powerful function, or to try to implement such a function as a high-level API.

H5Lmove needs the lcpl because of the "create intermediate groups" option. H5Lrename needs it to set the character encoding of the link's new name.

High-level functions might be implemented that used only one location and no property lists.

herr_t H5Lunlink(hid_t loc_id, const char *name )

The new unlinking function would be identical to the old function, H5Gunlink. Unlinking requires no parameters, and links are still specified by location/name.

hid_t H5Lget_create_plist(hid_t loc, char *name)

Links have LCPLs that store their character encoding and whether they are hard or soft links. This function allows the user to retrieve these lists.

There is probably little demand for a 'touch' function to update a link's creation time, and less for a function allowing users to manually set a link's creation time. These functions could be added later, but will not be part of the API now.

Changes to H5P Interface

A new link creation property list class needs to be created. Its properties are the link's character encoding (ASCII or UTF-8) and the link's type (hard or soft link). It also contains the "create intermediate groups" property which is currently part of the object creation property list. This property will no longer be part of all creation lists, only the link creation list.

herr_t H5Pset_encoding(hid_t plist_id, H5T_cset_t encoding)

herr_t H5Pget_encoding(hid_t plist_id, H5T_cset_t *encoding)

herr_t H5Pset_link_type(hid_t plist_id, H5G_link_t link_type)

herr_t H5Pget_link_type(hid_t plist_id, H5G_link_t *link_type)

herr_t H5Pset_create_intermediate_group(hid_t plist_id, unsigned crt_intmd_group)

Attributes will be able to accept UTF-8 names as well. The encoding of an attribute's name will be specified in the same way as a link's, using the H5Pset_encoding and H5Pget_encoding functions.

After the H5L interface has been created, a second series of changes will allow files to set a file-wide default character encoding. This will be set through the file creation property list, and can be overridden using the link creation property list.

Other Changes

H5Dcreate_extend, H5Gcreate_extend, and H5Tcommit_extend (names being tentative) will not create a link to the created object, letting the user do so manually. H5Dcreate, H5Gcreate, and H5Tcommit will continue to create links with default settings.

To support files eventually having default character encodings, the file format will be changed to store the default character encoding in the superblock. Until this feature is supported, all files will default to the ASCII encoding.

Other Languages

These changes would need to be made in Fortran and C++, as well. The Fortran changes would be the same as in C.

The C++ interface has its own organization. It would need to recognize and be able to set properties in Link Creation Property Lists, but it would not necessarily need to change to reflect the reorganization in the C interface.

I suggest we get the input of our C++ guru before redesigning the C++ classes.

High-level Wrappers

There are a number of link-related function calls that users may want to use for convenience, but which are essentially simplifications or combinations of other HDF5 API calls.

The current object creation calls are the best example of this. The current H5Gmove is another, essentially combining link creation and deletion into one step. Users may also want to query properties of objects (link character encoding, e.g.) without going to the trouble of extracting the object's property list.

I propose a high-level "utility" library that would hold such commonly-used calls. H5Dcreate, H5Gcreate, and H5Tcommit could be part of this high-level library rather than duplicating the effects of other library functions. The "utility" library functions could be mentioned in the main HDF5 reference manual.

For the 1.8 release, time permitting, we create the new function H5Dcreate_extend. We continue to support the H5Dcreate function, but consider it depreciated. We also create a high-level library with H5Dcreate_simple, which has the same (or less!) functionality as H5Dcreate, and encourage users to migrate to either H5Dcreate_extend or H5Dcreate, depending on whether or not they need the additional features of H5Dcreate_extend.

The high-level API functions to be written for this change include:

H5Dcreate_simple

H5Gcreate_simple

H5Tcommit_simple

These functions have the same functionality as the current H5Dcreate, H5Gcreate, and H5Tcommit (which will be duplicated functionality while those functions are present but depreciated).

If the H5L interface is something we want to shield users from as much as possible, it might also be worthwhile to have a high-level creation command like the library's H5Dcreate_extend, but that also created a link as part of dataset creation.

H5Llink_simple

H5Llink_simple creates a link like the current H5Glink call. It creates a link with default properties so that high-level users don't need to worry about property lists.

H5Lmove_simple

H5Lrename_simple

H5Lmove_and_rename

These functions move and rename with default properties and using only one location id.

H5Lmove_and_rename both moves and renames a link in a single function call.