SA_USERS

Perform user-related Server Administration.

Short Name

SA_USERS()

Type

System Administration

Declaration

NINT SA_USERS(COUNT action, saUSRINFO usrinfo)

Description

The SA_USERS() function performs user-related c-tree Server administration operations. SA_USERS() accepts action, indicating the operation to perform, and usrinfo, a pointer to a saUSRINFO structure whose fields contain the data used in the specified operation. The following action values are described in detail below:

Value	Symbolic Constant	Description
1	ctuNEW	Add User
2	ctuREMOVE	Remove User
3	ctuLIST	List Users
4	ctuWORD	Change User Password
5	ctuGROUP	Add User to Group
6	ctuDESC	Change User Description
7	ctuMEM	Change User Memory
8	ctuXINFO	Change User Extended Info
9	ctuGROUPRM	Remove User From Group
10	ctuSHOW	Retrieve User Settings

usrinfo points to the USER definition structure, saUSRINFO, defined below. Each action value uses specific values in the saUSRINFO structure. The other values are ignored.

typedef struct _saUSRI

  TEXT    usr_pass[PWZ];          // User Password

  TEXT    usr_group[MAX_NAME];    // User Group

  TEXT    usr_id[IDZ];            // User Id

  TEXT    usr_desc[DSZ];          // User Description

  TEXT    usr_memory[11];         // User Memory Limit

  TEXT    usr_memrule[2];         // User Memory Rule

  TEXT    usr_xbegdat[11];        // Begin validity period

  TEXT    usr_xenddat[11];        // End validity period

  TEXT    usr_xlgnlmt[11];        // Invalid logon limit

  TEXT    usr_xlgnrsm[11];        // Logon block time remaining

  TEXT    usr_xmstlgn[11];        // Must logon limit

  struct _saUSRI    *usr_list;    // Ptr to user list

} saUSRINFO;

The operations that SA_USERS() supports are described in detail below.

ADD USER

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

Example

COUNT     rc;

saUSRINFO usrinfo;


ctsfill(&usrinfo, 0, sizeof(saUSRINFO));

strcpy(usrinfo.usr_id,      "QATEST");

strcpy(usrinfo.usr_desc,    "QA test account");

strcpy(usrinfo.usr_pass,    "qat$145");

strcpy(usrinfo.usr_group,   "QA");

strcpy(usrinfo.usr_memory,  "100000");

strcpy(usrinfo.usr_memrule, "D");

strcpy(usrinfo.usr_xbegdat, "05/23/1999");

strcpy(usrinfo.usr_xenddat, "12/31/1999");

strcpy(usrinfo.usr_xlgnlmt, "3");


if ((rc = SA_USERS(ctuNEW, &usrinfo)) != 0)

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

else

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

REMOVE USER

To remove a user, declare a variable of type saUSRINFO and set the usr_id field to the user id to remove. Call SA_USERS() with the ctuREMOVE action and the address of your saUSRINFO structure.

Example

COUNT     rc;

saUSRINFO usrinfo;


ctsfill(&usrinfo, 0, sizeof(saUSRINFO));

strcpy(usrinfo.usr_id,      "QATEST");


if ((rc = SA_USERS(ctuREMOVE, &usrinfo)) != 0)

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

else

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

LIST USERS

To retrieve a list of all defined users, call SA_USERS() with the ctuLIST action and the address of your saUSRINFO structure. Upon successful completion, SA_USERS() sets the usr_list field of the saUSRINFO structure you passed to it to point to a linked list of saUSRINFO structures. You can traverse the list to retrieve information about each user.

Example

COUNT     rc;

saUSRINFO usrinfo;


ctsfill(&usrinfo, 0, sizeof(saUSRINFO));

if ((rc = SA_USERS(ctuLIST, &usrinfo)) != 0)

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

else

    saUSRINFO *pusr, *tp;

    pusr = usrinfo.usr_list;

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

           "User Description (Groups)","------------",

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

    while (pusr) {

        printf("\n%31s  %s", pusr->usr_id, pusr->usr_desc);

        if (pusr->usr_group[0]){

            if (pusr->usr_desc[0])

                printf(" ");

            printf("( %s )", pusr->usr_group);

        tp = pusr;

        pusr = pusr->usr_list;

        mbfree(tp);

    printf("\n");

CHANGE USER PASSWORD

To change the password for a user, declare a variable of type saUSRINFO, set the usr_id field to the user id whose password to change, and set the usr_pass field to the new password. Call SA_USERS() with the ctuWORD action and the address of your saUSRINFO structure.

Example

COUNT     rc;

saUSRINFO usrinfo;


ctsfill(&usrinfo, 0, sizeof(saUSRINFO));

strcpy(usrinfo.usr_id,      "QATEST");

strcpy(usrinfo.usr_pass,    "QATEST");


if ((rc = SA_USERS(ctuWORD, &usrinfo)) != 0)

    printf("Change user password failed. Error %d (%d).\n", rc, isam_err);

else

    printf("Successfully changed user password.\n");

ADD USER TO GROUP

To add a user to a group, declare a variable of type saUSRINFO, set the usr_id field to the desired user id, and set the usr_group field to the name of the group to which the user is to be added. Call SA_USERS() with the ctuGROUP action and the address of your saUSRINFO structure.

Example

COUNT     rc;

saUSRINFO usrinfo;


ctsfill(&usrinfo, 0, sizeof(saUSRINFO));

strcpy(usrinfo.usr_id,      "QATEST");

strcpy(usrinfo.usr_group,   "ADMIN");


if ((rc = SA_USERS(ctuGROUP, &usrinfo)) != 0)

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

else

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

CHANGE USER Description

To change the description for a user, declare a variable of type saUSRINFO, set the usr_id field to the desired user id, and set the usr_desc field to the new description. Call SA_USERS() with the ctuDESC action and the address of your saUSRINFO structure.

Example

COUNT     rc;

saUSRINFO usrinfo;


ctsfill(&usrinfo, 0, sizeof(saUSRINFO));

strcpy(usrinfo.usr_id,   "QATEST");

strcpy(usrinfo.usr_desc, "QA test account for SA_ADMIN");


if ((rc = SA_USERS(ctuDESC, &usrinfo)) != 0)

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

else

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

CHANGE USER MEMORY

To change the memory settings for a user, declare a variable of type saUSRINFO, set the usr_id field to the desired user id, set the usr_memory field to the new memory limit, and set the usr_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_USERS() with the ctuMEM action and the address of your saUSRINFO structure.

Example

COUNT     rc;

saUSRINFO usrinfo;


ctsfill(&usrinfo, 0, sizeof(saUSRINFO));

strcpy(usrinfo.usr_id,      "QATEST");

strcpy(usrinfo.usr_memory,  "300000");

strcpy(usrinfo.usr_memrule,  "A");


if ((rc = SA_USERS(ctuMEM, &usrinfo)) != 0)

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

else

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

CHANGE EXTENDED USER SETTINGS

To change the extended settings for a user, declare a variable of type saUSRINFO, set the usr_id field to the desired user id, set the usr_xbegdat field to the new start valid date, set the usr_xenddat field to the new end valid date, set the usr_xlgnlmt field to the new invalid logon limit, set the usr_xmstlgn field to the new must logon period (in minutes), and set the usr_xlgnrsm field to the new remaining logon timeout value (in minutes).

Use the format “mm/dd/yyyy” for the usr_xbegdat and usr_xenddat fields. You can specify a field as an empty string to use the current value for that option. Call SA_USERS() with the ctuXINFO action and the address of your saUSRINFO structure.

To use the system default for the invalid logon limit, set usr_xlgnlmt to 0. Set the usr_xlgnlmt and usr_xmsglgn fields to -1 to disable the “logon limit” and “must logon” checks, if desired.

Example

COUNT     rc;

saUSRINFO usrinfo;


ctsfill(&usrinfo, 0, sizeof(saUSRINFO));

strcpy(usrinfo.usr_id,      "QATEST");

strcpy(usrinfo.usr_xbegdat, "05/23/1999");

strcpy(usrinfo.usr_xenddat, "12/31/1999");

strcpy(usrinfo.usr_xlgnlmt, "3");

strcpy(usrinfo.usr_xmstlgn, "3600");

strcpy(usrinfo.usr_xlgnrsm, "0");


if ((rc = SA_USERS(ctuXINFO, &usrinfo)) != 0)

    printf("Change extended user settings failed: %d (%d).\n", rc, isam_err);

else

    printf("Successfully changed extended user settings.\n");

REMOVE USER FROM GROUP

To remove a user from a group, declare a variable of type saUSRINFO, set the usr_id field to the desired user id, and set the usr_group field to the name of the group from which the user is to be removed. Call SA_USERS() with the uctGROUPRM action and the address of your saUSRINFO structure.

Example

COUNT     rc;

saUSRINFO usrinfo;


ctsfill(&usrinfo, 0, sizeof(saUSRINFO));

strcpy(usrinfo.usr_id,      "QATEST");

strcpy(usrinfo.usr_group,   "ADMIN");


if ((rc = SA_USERS(ctuGROUPRM, &usrinfo)) != 0)

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

else

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

RETRIEVE USER SETTINGS

To retrieve the settings for a user, declare a variable of type saUSRINFO and set the usr_id field to the desired user id. Call SA_USERS() with the ctuSHOW action and the address of your saUSRINFO structure. Upon successful completion, SA_USERS() fills your saUSRINFO structure with the settings for the specified user.

Example

COUNT     rc;

saUSRINFO usrinfo;


ctsfill(&usrinfo, 0, sizeof(saUSRINFO));

strcpy(usrinfo.usr_id,      "QATEST");


if ((rc = SA_USERS(ctuSHOW, &usrinfo)) != 0)

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

else {

    ctrt_printf("\nUser Id:     %s", usrinfo.usr_id);

    ctrt_printf("\nDescription: %s", usrinfo.usr_desc);

    ctrt_printf("\nPassword:    *******");

    ctrt_printf("\nUser Memory: %s", usrinfo.usr_memory);

    ctrt_printf("\nMemory Rule: %s", usrinfo.usr_memrule);

    if (!usrinfo.usr_group[0])

        ctrt_printf("\nUser Groups: (None)");

    else

        ctrt_printf("\nUser Groups: %s", usrinfo.usr_group);

    printf("\n");

Return

All of the 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 c-tree Plus error value. See “c-tree Plus Error Codes” in the c-tree Plus Programmer’s Reference Guide for a complete listing of valid c-tree Plus error values.

Limitations

Requires SA_LOGON() call.