Find collections

saf_find_collections is a function defined in coll.c.

Synopsis:

int saf_find_collections(SAF_ParMode pmode, SAF_Set *containing_set, SAF_Role *role, SAF_CellType cell_type, int topo_dim, SAF_DecompMode decomp_mode, int *num, SAF_Cat **found)

Formal Arguments:

  • pmode: The parallel mode.
  • containing_set: The containing set in which to search for collections. In SAF__ONE parallel mode, all processes except the process identified by the rank argument of the SAF__ONE macro are free to pass SAF__NULL_SET with the set’s database handle.
  • role: The role of the collection. Pass NULL if you do not wish to limit the search by this parameter.
  • cell_type: The cell-type of the members of the collection. Pass SAF__ANY_CELLTYPE if you do not wish to limit the search by this parameter.
  • topo_dim: The topological dimension of the collection. Pass SAF__ANY_TOPODIM if you do not wish to limit the search by this parameter.
  • decomp_mode: Whether the found collections must be a decomposition of the containing set. Pass SAF__DECOMP_TORF if it does not matter.
  • num: For this and the succeeding argument, (see *Returned Handles*).
  • found: For this and the preceding argument, (see *Returned Handles*).

Description: This function is used to search for collections on a given set. In addition, the client can limit the search to collections of a given role, with a given cell-type or those which are or are not a decomposition of the containing set.

Preconditions:

  • pmode must be valid. (low-cost)
  • containing_set must be a valid set handle for participating processes. (low-cost)
  • NUM_COLLS and CATS must be compatible for return value allocation. (low-cost)
  • role must be a valid role handle if supplied. (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.

Issues: The documentation for this function originally said it would return all collections in the whole database if the containing_set arg passed was ``SAF__UNIVERSE``(db). However, it is clear from the implementation that it cannot do that.

See Also: