SAF_Cat *
saf_declare_category(SAF_ParMode pmode,
SAF_Db *db, /* The database handle. */
const char *name, /* The collection category name. */
SAF_Role *role, /* Role of collections of this category (see Collection Roles). */
int tdim, /* The maximum topological dimension of the members of collections of this category. */
SAF_Cat *cat /* [OUT] The returned collection category handle. */
)
{
SAF_ENTER(saf_declare_category, NULL);
ss_scope_t scope;
SAF_REQUIRE(_saf_valid_pmode(pmode), SAF_LOW_CHK_COST, NULL,
_saf_errmsg("PMODE must be valid"));
if (!_saf_is_participating_proc(pmode)) SAF_RETURN(NULL);
SAF_REQUIRE(ss_file_isopen(db, NULL)>0, SAF_LOW_CHK_COST, NULL,
_saf_errmsg("DB must be a valid database"));
SAF_REQUIRE(ss_file_iswritable(db)>0, SAF_NO_CHK_COST, NULL,
_saf_errmsg("the database must not be open for read-only access"));
SAF_REQUIRE(name != NULL, SAF_LOW_CHK_COST, NULL,
_saf_errmsg("a NAME must be supplied for the category"));
SAF_REQUIRE(SS_ROLE(role), SAF_LOW_CHK_COST, NULL,
_saf_errmsg("ROLE must be a valid collection role"));
SAF_REQUIRE(tdim >= 0, SAF_LOW_CHK_COST, NULL,
_saf_errmsg("topological dimension, TDIM, must be positive"));
ss_file_topscope(db, &scope);
cat = (ss_cat_t*)ss_pers_new(&scope, SS_MAGIC(ss_cat_t), NULL, SAF_ALL==pmode?SS_ALLSAME:0U, (ss_pers_t*)cat, NULL);
if (SAF_EACH==pmode) SS_PERS_UNIQUE(cat);
ss_string_set(SS_CAT_P(cat,name), name);
SS_CAT(cat)->role = *role;
SS_CAT(cat)->tdim = tdim;
SAF_LEAVE(cat);
}