Attach an object registry scope

ss_file_registry is a function defined in ssfile.c.

Synopsis:

herr_t ss_file_registry(ss_file_t *file, ss_scope_t *registry)

Formal Arguments:

  • file: The file that is getting the new registry.
  • registry: The open scope to serve as the registry. This need not be a top-level scope though it usually is. It could even be some scope within file in an extreme case.

Description: A find operation searches a specific scope for objects that match some partially initialized key value. However, sometimes object definitions are in a separate object registry instead and should be “sucked into” the main file as necessary. An object registry is simply a stack of additional scopes to search when a find operation for the specified scope fails to locate any matching objects.

If a scope of file is searched during a find operation and results in no matches, then the registry scope is searched (registries are searched in the order defined with this function) and the object handle that gets returned is marked as coming from a registry. The current version of the library simply makes links to the registry scope, but a future version might copy the object from the registry into the specified file along with all prerequisites.

Registry lists are associated with the shared file information in the GFile array. That is, if two ss_file_t objects are opened and refer to the same underlying HDF5 file, then adding a registry to one of those ss_file_t links will cause the other link to also see the registry. This allows files that are opened implicitly to automatically use the same registry as their explicitly opened counterpart.

Note: The File, Scope, and Blob tables, which describe infrastructure, do not use object
registries during find operations. If the registry scope is closed then it is automatically removed from all the files for which it’s serving as a registry.

Return Value: Returns non-negative on success; negative on failure.

Parallel Notes: Independent, although it’s typically used in such a way that all tasks of the file communicator make identical calls to this function to define a common set of object registries.

Example: Here’s how this function might be used:

1
2
3
4
 ss_file_t file = ss_file_open("registry.saf",H5F_ACC_RDONLY,NULL);
 ss_scope_t registry = ss_file_topscope(file);
 ss_file_t myfile = ss_file_create("myfile.saf",H5F_ACC_RDWR,NULL);
 ss_file_registry(myfile,registry);

See Also:

  • Files: Introduction for current chapter