FairCom ISAM for C

SA_GROUP

Performs operations on FairCom DB Groups.

Short Name

SA_GROUP()

Type

System Administration

Declaration

NINT SA_GROUP(COUNT action,saGRPINFO * grpinfo)

Description

The SA_GROUP() function performs FairCom DB group operations. SA_GROUP() accepts action, indicating the operation to perform, and grpinfo, a pointer to an saGRPINFO structure containing the data used in carrying out the specified operation.

The following action values are described in detail below:

Value	Symbolic Constant	Description
1	ctgNEW	Add a group.
2	ctgREMOVE	Remove a group.
3	ctgLIST	List all groups.
4	ctgMEMBAD	Add a user to a group.
5	ctgDESC	Change a group description.
6	ctgMEM	Change group memory setting.
7	ctgSHOW	Retrieve group settings.
8	ctgMEMBRM	Remove a user from a group.

grpinfo points to the GROUP definition structure, saGRPINFO, defined below. Each action value uses specific values in the saGRPINFO structure. The other values are ignored.

typedef struct _saGRPI

{

TEXT grp_id[IDZ]; // Group Id

TEXT grp_desc[DSZ]; // Group Description

TEXT grp_memory[32]; // Group Memory Limit

TEXT grp_memrule[2]; // Group Memory Rule

TEXT grp_user[IDZ+1]; // User id to add or remove

struct _saGRPI *grp_list; // Ptr to group list

} saGRPINFO;

The operations that SA_GROUP() supports are described in detail below:

ADD GROUP

To add a group, declare a variable of type saGRPINFO and set the fields as desired. The only required field is grp_id. Specify any of the other fields as an empty string to use the default value for that option. Call SA_GROUP() with the gNEW action and the address of your saGRPINFO structure.

Example

COUNT rc;

saGRPINFO grpinfo;

ctsfill(&grpinfo, 0, sizeof(saGRPINFO));

strcpy(grpinfo.grp_id, "SUPPORT");

strcpy(grpinfo.grp_desc, "Technical support");

strcpy(grpinfo.grp_memory, "100000");

strcpy(grpinfo.grp_memrule, "D");

if ((rc = SA_GROUP(ctgNEW, &grpinfo)) != 0)

printf("Add group failed with error %d (%d).\n", rc, isam_err);

else

printf("Successfully added group.\n");

REMOVE GROUP

To remove a group, declare a variable of type saGRPINFO and set the grp_id field to the group id you wish to remove. Call SA_GROUP() with the gREMOVE action and the address of your saGRPINFO structure.

Example

COUNT rc;

saGRPINFO grpinfo;

ctsfill(&grpinfo, 0, sizeof(saGRPINFO));

strcpy(grpinfo.grp_id, "SUPPORT");

if ((rc = SA_GROUP(ctgREMOVE, &grpinfo)) != 0)

printf("Remove group failed with error %d (%d).\n", rc, isam_err);

else

printf("Successfully removed group.\n");

LIST GROUPS

To retrieve a list of all defined groups, call SA_GROUP() with the gLIST action and the address of your saGRPINFO structure. Upon successful completion, SA_GROUP() sets the grp_list field of the saGRPINFO structure you passed to it to point to a linked list of saGRPINFO structures. You can traverse the list to retrieve information about each group.

Example

COUNT rc;

saGRPINFO grpinfo;

if ((rc = SA_GROUP(ctgLIST, &grpinfo)) != 0)

printf("List groups failed with error %d (%d)\n", rc, isam_err);

else {

saGRPINFO *pgrp, *tp;

pgrp = grpinfo.grp_list;

printf("\n\n%31s %s\n%31s %s", "Group Id",

"Group Description", "------------",

"------------------------------------");

while (pgrp) {

printf("\n%31s %s",pgrp->grp_id,pgrp->grp_desc);

tp = pgrp;

pgrp = pgrp->grp_list;

mbfree(tp);

}

printf("\n");

}

ADD USER TO GROUP

To add a user to a group, declare a variable of type saGRPINFO, set the grp_id field to the desired group id, and set the grp_user field to the user id you wish to add to the specified group. Call SA_GROUP() with the gMEMBAD action and the address of your saGRPINFO structure.

Example

COUNT rc;

saGRPINFO grpinfo;

ctsfill(&grpinfo, 0, sizeof(saGRPINFO));

strcpy(grpinfo.grp_id, "SUPPORT");

strcpy(grpinfo.grp_user, "ADMIN");

if ((rc = SA_GROUP(ctgMEMBAD, &grpinfo)) != 0)

printf("Add user to group failed with error %d (%d)\n", rc, isam_err);

else

printf("Successfully added user to group.\n");

CHANGE GROUP Description

To change the description for a group, declare a variable of type saGRPINFO, set the grp_id field to the desired group id, and set the grp_desc field to the new description. Call SA_GROUP() with the gDESC action and the address of your saGRPINFO structure.

Example

COUNT rc;

saGRPINFO grpinfo;

ctsfill(&grpinfo, 0, sizeof(saGRPINFO));

strcpy(grpinfo.grp_id, "SUPPORT");

strcpy(grpinfo.grp_desc, "Product support group");

if ((rc = SA_GROUP(ctgDESC, &grpinfo)) != 0)

printf("Change group description failed: Error %d (%d)\n", rc, isam_err);

else

printf("Successfully changed group description.\n");

CHANGE GROUP MEMORY

To change the memory settings for a group, declare a variable of type saGRPINFO, set the grp_id field to the desired group, set the grp_memory field to the new memory limit, and set the grp_memrule field to the new memory rule. You can specify a field as an empty string to use the current value for that option. Call SA_GROUP() with the gMEM action and the address of your saGRPINFO structure.

Example

COUNT rc;

saGRPINFO grpinfo;

ctsfill(&grpinfo, 0, sizeof(saGRPINFO));

strcpy(grpinfo.grp_id, "SUPPORT");

strcpy(grpinfo.grp_memory, "300000");

strcpy(grpinfo.grp_memrule, "A");

if ((rc = SA_GROUP(ctgMEM, &grpinfo)) != 0)

printf("Change group memory failed with error %d (%d).\n", rc, isam_err);

else

printf("Successfully changed group memory.\n");

RETRIEVE GROUP SETTINGS

To retrieve the settings for a group, declare a variable of type saGRPINFO and set the grp_id field to the desired group id. Call SA_GROUP() with the gSHOW action and the address of your saGRPINFO structure. Upon successful completion, SA_GROUP() fills your saGRPINFO structure with the settings for the specified group.

Example

COUNT rc;

saUSRINFO grpinfo;

ctsfill(&grpinfo, 0, sizeof(saGRPINFO));

strcpy(grpinfo.grp_id, "SUPPORT");

if ((rc = SA_GROUP(ctgSHOW, &grpinfo)) != 0)

printf("Retrieve group settings failed: Error %d (%d)\n", rc, isam_err);

else

{

printf("\nGroup Id: %s", grpinfo.grp_id);

printf("\nDescription: %s", grpinfo.grp_desc);

printf("\nUser Memory: %s", grpinfo.grp_memory);

printf("\nMemory Rule: %s", grpinfo.grp_memrule);

printf("\n");

}

REMOVE USER FROM GROUP

To remove a user from a group, declare a variable of type saGRPINFO, set the grp_id field to the desired group id, and set the grp_user field to the user id to wish to remove from the specified group. Call SA_GROUP() with the gMEMBRM action and the address of your saGRPINFO structure.

Example

COUNT rc;

saGRPINFO grpinfo;

ctsfill(&grpinfo, 0, sizeof(saGRPINFO));

strcpy(grpinfo.grp_id, "SUPPORT");

strcpy(grpinfo.grp_user, "ADMIN");

if ((rc = SA_GROUP(ctgMEMBRM, &grpinfo)) != 0)

printf("Remove user from group failed: Error %d (%d)\n", rc, isam_err);

else

printf("Successfully removed user from group.\n");

Return

All server administration functions return a zero value to indicate success and a non-zero value (defined in cthelp.h) to indicate failure. In the case of failure, the global variable isam_err will be set to the FairCom DB error value. See c-tree Error Codes in the FairCom DB Reference Guide for a complete listing of error values.

Limitations

Requires SA_LOGON() call.