Declare an Alternative Index Specification

saf_declare_alternate_indexspec is a function defined in altindx.c.

Synopsis:

SAF_AltIndexSpec * saf_declare_alternate_indexspec(SAF_ParMode pmode, SAF_Db *db, SAF_Set *containing_set, SAF_Cat *cat, const char *name, hid_t data_type, hbool_t is_explicit, SAF_IndexSpec implicit_ispec, hbool_t is_compact, hbool_t is_sorted, SAF_AltIndexSpec *aspec)

Formal Arguments:

  • pmode: The parallel mode
  • db: Database to contain the new index spec.
  • containing_set: The containing set of the collection.
  • cat: The collection category.
  • name: The name you wish to assign to this alt index spec
  • data_type: The data type used to identify members of the collection
  • is_explicit: Whether the indexing specification is explicit or implicit
  • implicit_ispec: The alternate indexing scheme of the collection. Ignored for explicit specs. Pass SAF__NA_INDEXSPEC for explicit alternative index specs.
  • is_compact: Whether the indexing specification is compact or not. Ignored for implicit specs.
  • is_sorted: Whether the indexing specification is sorted or not. Ignored for implicit specs.
  • aspec: [OUT] The optional returned alternate index spec handle. If the null pointer is passed for this argument then new memory is allocated and returned, otherwise this argument serves as the successful return value.

Description: There is already a default SAF__IndexSpec associated with the collection defined by containing_set and cat. This call registers another, alternate index specification. The default index spec associated with the collection is something that allows you to describe the collection IDs very easily by specifying the start index and how many you have (typically the start index is 0). If you have some other, arbitrary way to identify the members of the collection, then you need to write out a problem sized array describing the names you give to the members of that collection. This is an explicit alternate indexing scheme, since you need to explicitly list the id’s for each member of the collection. An implicit index spec is something that can be captured by stating the start index and how many you have, so you don’t need to explicitly list the collection ids.

Preconditions:

  • pmode must be valid. (low-cost)
  • containing_set must be a valid set handle. (low-cost)
  • cat must be a valid cat handle. (low-cost)

Return Value: On success, returns either the aspec argument or a newly allocated index specification. Returns the null pointer on failure.

Issues: The data_type is just stored as the HDF5 data_type member of the SAF__AltIndexSpec. This is transient, in memory data, it is not written to the saf database until the saf_write_alternate_indexspec call. This means that if you do something like: saf_declare_alternate_indexspec, then saf_find_alternate_index_spec, then saf_describe_alternate_indexspec, (with no write call yet) you won’t be able to recover the data_type.

See Also: