Find collection categories

saf_find_categories is a function defined in cat.c.

Synopsis:

int saf_find_categories(SAF_ParMode pmode, SAF_Db *db, SAF_Set *containing_set, const char *name, SAF_Role *role, int tdim, int *num, SAF_Cat **found)

Formal Arguments:

  • db: Database on which to restrict the search.
  • containing_set: The set upon which to restrict the search. The special macro ``SAF__UNIVERSE``(db) (which takes a database handle as an argument) allows the search to span all categories of the specified database.
  • name: The name of the categories upon which to restrict the search. The constant SAF__ANY_NAME allows the search to span categories with any name.
  • role: The role of the categories upon which to restrict the search. A null pointer allows the search to span categories with any role (see *Collection Roles*).
  • tdim: The topological dimension of the categories upon which to restrict the search. The constant SAF__ANY_TOPODIM allows the search to span categories with any topological dimension.
  • num: For this and the succeeding argument [see Returned Handles].
  • found: For this and the preceding argument [see Returned Handles].

Description: This function will find collection categories matching the specified name, role and tdim. It searches collection categories defined on the containing_set, which can be set to ``SAF__UNIVERSE``(db), implying that all collection categories in the entire database should be searched. Since the number of collection categories is relatively small, and global, such a search should not take much time.

Preconditions:

  • pmode must be valid. (low-cost)
  • db must be a valid database. (low-cost)
  • num and found must be compatible for return value allocation. (low-cost)
  • role must be a valid role handle or NULL. (low-cost)
  • containing_set must be a valid set handle or NULL. (low-cost)

Return Value: The constant SAF__SUCCESS is returned when this function is successful. Otherwise this function either returns an error number or throws an exception, depending on the value of the library’s error handling property.

Parallel Notes: This function must be called collectively across the database communicator of the containing_set.

See Also: