Bind a blob to a dataset

ss_blob_bind_f is a function defined in ssblob.c.

Synopsis:

herr_t ss_blob_bind_f(ss_blob_t *blob, hid_t dset, hid_t dspace, unsigned flags)

Formal Arguments:

  • blob: The blob to which a dataset is associated.
  • dset: The dataset to associate with the blob. The handle is duplicated by SSlib, allowing the caller to close its handle at any time.
  • dspace: A selection that describes which elements of dset are owned by the blob. If non-positive then the entire dataset is owned by the blob.
  • flags: Various bit flags affecting the operation of this function.

Description: If a dataset already exists and a new blob is being created then an existing dataset can be bound to the blob. In effect, this causes the blob to own part of the dataset. Multiple blobs can point into a common dataset and those blobs can own overlapping regions of the dataset. This function duplicates the dataset handle so the caller can close its handle without affecting SSlib.

This function is only applicable when initializing or modifying a blob since all blobs that are read from a file are automatically bound to the same dataset and region as previously specified. That is, information about the dataset and region are stored as part of the blob object in the file.

A blob can be disassociated from a dataset by providing a non-positive handle for the dset argument, in which case the remaining arguments are ignored.

The multi-dimensional size of the blob is deteremined from the selection defined on dspace. The dimensionality of the blob is determined by removing all the dimensions that have unit size in the blob. Thus a blob’s dimensionality may be less than the dimensionality of the dataset on which it is defined. This allows, for instance, one dimensional blobs to be stored as rows of a two dimensional dataset. See ss_blob_space for additional information.

A blob’s size can be changed simply by rebinding it to a dataset using a new data space. If the the SS_BLOB_EXTEND bit is turned on in the flags argument then the underlying dataset is extended if necessary in order for the blob to fit within the dataset. All calling tasks (even those that don’t have a blob) must pass the same value for the SS_BLOB_EXTEND bit.

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

Parallel Notes: Conceptually collective across the blob’s scope communicator, however in practice the file communicator must be used. This is due to the fact that SSlib might need to make file-collective calls to HDF5. The restriction isn’t so bad though because the caller would have had to file-collectively create the dataset anyway.

All tasks should pass the same blob and dataset, but any “extra” task that’s part of the blob’s file communicator but not the blob’s scope communicator should pass the top scope for the blob’s file instead of the blob. The dspace argument is ignored on the “extra” tasks but should be consistent across the blob’s tasks.

Issues: Currently only very simple selections are allowed: a contiguous multi-dimensional rectangular region of an extent specified by arrays of offsets and lengths, one per dimension.

See Also: