Summary of possible changes to Group API

• To: netcdf-hdf@xxxxxxxxxxxxxxxx
• Subject: Summary of possible changes to Group API
• From: Quincey Koziol <koziol@xxxxxxxxxxxxx>
• Date: Wed, 16 Feb 2005 15:48:41 -0600 (CST)

Hi all,
    We need to start thinking about what the new group API will look like.
Here's a quick draft of a high level view from the changes I can think of.
Please give me feedback about your ideas for this API.  I'm also going to
write up a draft for the API renaming proposal, which will affect the changes
to the group API, but shouldn't depend on it.

    Quincey

========================================================================

NOTE #1: These changes are mainly ramifications from the addition of an
    [optional] index that allows applications to access objects in a group
    according to the order they were created.

NOTE #2: We still need to decide on scheme for re-naming existing functions
    when their parameters change.

Existing API routine changes:
============================

Old Name:               Purpose:                Change:
=========               ========                ======
H5Gcreate               Create new group        Will need to drop 'size_hint'
                                                parameter and acquire "group
                                                creation" and "group access"
                                                property lists

H5Gopen                 Open an existing        Add "group access" property
                        group                   list

H5Gclose                Close a group ID        <none>

H5Gset_comment          Set a "comment" on a    <none> (deprecated)
                        group

H5Gget_comment          Get the "comment" on a  <none> (deprecated)
                        group

H5Glink/H5Glink2        Creates a link to an    <none>
                        object in another group
                        by name in the other
                        group

H5Gmode/H5Gmove2        Renames a link to an    <none>
                        object in current group
                        by name

H5Giterate              Iterate through objects Change to allow choice of which
                        in a group, with user   index to use (and direction?).
                        callback routine

H5Gget_objinfo          Retrieve information    Update H5G_stat_t with any new
                        about an object in a    information.  Possibly add
                        group                   H5Gget_objinfo_by_idx routine?
                                                Absorb H5Gget_<foo>_by_idx
                                                routines?

H5Gget_num_objs         Retrieve number of      <none>
                        objects in a group

H5Gget_objname_by_idx   Retrieve name of n'th   Needs a "type of index"
                        object in a group,      parameter, in order to choose
                        according to link name  index to use to compute the
                        order                   "n'th object" of.

H5Gget_objtype_by_idx   Retrieve type of n'th   Needs a "type of index"
                        object in a group,      parameter, in order to choose
                        according to link name  index to use to compute the
                        order                   "n'th object" of.

Added API routines:
==================

Name:                   Purpose:
=========               =======
H5Glink_order           Create a link to an object in another group by creation
                        order in the other group.

H5Gunlink_order         Remove the n'th object (by creation order) in a group.

H5Gchange_time          Change the creation time of an object in a group,
                        potentially changing its position in creation order.

H5Gget_linkval_by_idx   Retrieve the link information about a soft link, using
                        the order with an index.

H5Gopen_by_idx          Open the n'th object in a group, accordding to
                        the order with an index.

New property lists:
==================

Name:                   Purpose:
=====                   =======
"Group Creation"        Control various parameters of a group, like it's B-tree
                        properties and whether it has an index allowing it
                        track the order that objects are created.  Possibly
                        other parameters as well.

"Group Access"          Control various parameters of accessing a group, like
                        possibly the default index to use for various
                        operations, etc.