SA_ERRMSG

Returns an SA ADMIN associated error message.

Declaration

pTEXT SA_ERRMSG(COUNT errcode)

Description

errcode is an SA ADMIN API error code.

Return

SA_ERRMSG() returns the error message associated with an SA ADMIN API error code.

Example psuedocode

SA_LOGON("ADMIN", "ADMIN", NULL, "FAIRCOMS");
...
if ((rc = SA_FILES(...) !=0) {
/* some error occured */
ctrt_printf("SA_FILES encountered the following error code(%n):\n, %s\n",
rc, SA_ERRMSG(rc));
}
...
SA_LOGOFF();

SA_FILES

Performs FairCom DB file administration operations.

Short Name

SA_FILES()

Type

System Administration

Declaration

NINT SA_FILES(COUNT action, saFILINFO * filinfo)

Description

The SA_FILES() function performs FairCom DB file administration operations. SA_FILES() accepts action, indicating the operation to perform, and filinfo, a pointer to an saFILINFO structure containing the data used in carrying out the specified operation.

The following action values are described in detail below:

filinfo points to the FILE definition structure, saFILINFO, defined below. Each action value uses specific values in the saFILINFO structure. The other values are ignored.

typedef struct
{
  TEXT    fil_pass[FILEPWZ];       // File Password
  TEXT    fil_group[IDZ];      // File Group
  TEXT    fil_name[MAX_NAME];  // File name
  TEXT    fil_mask[16];        // File Permission mask
  TEXT    fil_owner[IDZ];      // File Owner
} saFILINFO;

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

CHANGE FILE PASSWORD

To change the password for a file, declare a variable of type saFILINFO, set the fil_name field to the name of the file, and set the fil_pass field to the new password. Call SA_FILES() with the fPASS action and the address of your saFILINFO structure.

Example

COUNT     rc;
saFILINFO filinfo;

ctsfill(&filinfo, 0, sizeof(saFILINFO));
strcpy(filinfo.fil_name,    "data\\custmast.dat");
strcpy(filinfo.fil_pass,    "p%9ffL2x");

if ((rc = SA_FILES(ctfPASS, &filinfo)) != 0)
    printf("Change file password failed with error %d (%d).\n",
           rc, isam_err);
else
    printf("Successfully changed file password.\n");

CHANGE FILE PERMISSIONS

To change the security permissions for a file, declare a variable of type saFILINFO, set the fil_name field to the name of the file, and set the fil_mask field to the new permission mask. The fil_mask field is interpreted as a 15-byte permission mask containing owner, group, and world permissions:

 (offset)
 0   1   2   3   4   5   6   7   8   9  10  11  12  13  14
 ------OWNER------   ------GROUP------   ------WORLD------
 r   w   f   d   p   r   w   f   d   p   r   w   f   d   p

r = Read  w = Write  f = define  d = Delete  p = noPass

To set a permission, set the byte at the corresponding offset of fil_mask to a value of ‘+’; to reset a specified permission, set the corresponding byte to ‘-’. In the example below, the specified mask sets all OWNER and WORLD permissions, and resets all GROUP permissions.

Call SA_FILES() with the fPERM action and the address of your saFILINFO structure.

Example

COUNT     rc;
saFILINFO filinfo;

ctsfill(&filinfo, 0, sizeof(saFILINFO));
strcpy(filinfo.fil_name,    "data\\custmast.dat");
strcpy(filinfo.fil_mask,    "+++++-----+++++");

if ((rc = SA_FILES(ctfPERM, &filinfo)) != 0)
    printf("Change file permission mask failed: Error %d (%d).\n", rc,
           isam_err);
else
    printf("Successfully changed file permission mask.\n");

CHANGE FILE GROUP

To change the group to which a file belongs, declare a variable of type saFILINFO, set the fil_name field to the name of the file, and set the fil_group field to the new group. Call SA_FILES() with the fGROUP action and the address of your saFILINFO structure.

Example

COUNT     rc;
saFILINFO filinfo;

ctsfill(&filinfo, 0, sizeof(saFILINFO));
strcpy(filinfo.fil_name,    "data\\custmast.dat");
strcpy(filinfo.fil_group,   "SUPPORT");

if ((rc = SA_FILES(ctfGROUP, &filinfo)) != 0)
    printf("Change file group failed with error %d (%d).\n", rc, isam_err);
else
    printf("Successfully changed file group.\n");

CHANGE FILE OWNER

To change the owner for a file, declare a variable of type saFILINFO, set the fil_name field to the name of the file, and set the fil_owner field to the new owner. Call SA_FILES() with the fOWNER action and the address of your saFILINFO structure.

Example

COUNT     rc;
saFILINFO filinfo;

ctsfill(&filinfo, 0, sizeof(saFILINFO));
strcpy(filinfo.fil_name,    "data\\custmast.dat");
strcpy(filinfo.fil_owner,   "ADMIN");

if ((rc = SA_FILES(ctfOWNER, &filinfo)) != 0)
    printf("Change file owner failed with error %d (%d).\n", rc, isam_err);
else
    printf("Successfully changed file owner.\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 Programmer’s Reference Guide for a complete listing of error values.

Limitations

Requires SA_LOGON() call.

See also

SA_GROUP(), SA_USERSX(), SA_LOGON(), SA_LOGOF()

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:

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.

See also

SA_USERSX(), SA_FILES(), SA_LOGON(), SA_LOGOF()

SA_LOGOF

Close administration files and disconnect from FairCom DB.

Short Name

SA_LOGOF()

Type

System Administration

Declaration

NINT SA_LOGOF(); 

Description

The SA_LOGOF() function closes FairCom DB administration files and disconnects from FairCom DB.

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 Programmer’s Reference Guide for a complete listing of error values.

Example

NINT      rc;
TEXT      auid[IDZ], apwd[PWX], fpwd[FILEPWZ], svrname[25];

if ((rc = SA_LOGON(auid, apwd, fpwd, svrname)) != 0)
    printf("\nSA_LOGON error = %d", rc);
else {
    DoAdmin();
    SA_LOGOF();
}

Limitations

Requires SA_LOGON() call.

See also

SA_GROUP(), SA_FILES(), SA_LOGON(), SA_USERSX()

SA_LOGON

Connects to FairCom DB in preparation for administration.

Short Name

SA_LOGON()

Type

System Administration

Declaration

NINT SA_LOGON(cpTEXT admnuid, cpTEXT admnpwd, cpTEXT filepwd, cpTEXT servername) 

Description

The SA_LOGON() function is used to connect to FairCom DB and open the server’s administrative files. To use the SA_USERS(), SA_GROUP(), and SA_FILES() functions, a program must first call SA_LOGON().

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 Programmer’s Reference Guide for a complete listing of error values.

Example

NINT      rc;
TEXT      auid[IDZ], apwd[PWZX], fpwd[FILEPWZ], svrname[25];

if ((rc = SA_LOGON(auid, apwd, fpwd, svrname)) != 0)
    printf("\nSA_LOGON error = %d", rc);
else {
    DoAdmin();
    SA_LOGOF();
}

See also

SA_GROUP(), SA_FILES(), SA_USERSX(), SA_LOGOF()

SA_USERS

Perform user-related Server Administration. For versions 13.1 and beyond, you can use SA_USERSX for an equivalent function that is more fully featured. 

Short Name

SA_USERS()

Type

System Administration

Declaration

NINT SA_USERS(COUNT action, saUSRINFO * userinfo) 

Description

The SA_USERS() function performs user-related FairCom 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:

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[PWZX];          // 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 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 Programmer’s Reference Guide for a complete listing of error values.

Limitations

Requires SA_LOGON() call.

See also

SA_USERSX, SA_GROUP(), SA_FILES(), SA_LOGON(), SA_LOGOF()

SA_USERSX

Perform user-related Server Administration.

Short Name

SA_USERSX()

Type

System Administration

Declaration

NINT SA_USERSX(COUNT action, saUSRINFOX * userinfo, size_t infosize)

Description

The SA_USERSX() function performs user-related FairCom Server administration operations. SA_USERSX() accepts the following parameters: 

action

The action parameter indicates the operation that will be performed. It accepts the following values:  

usrinfo

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

typedef struct _saUSRX1
{
 TEXT    usr_pass[PWZX];          // 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 _saUSRX1    *usr_list;    // Ptr to user list
 UTEXT   version;                 // structure version
 TEXT    lastPasswordChange[11]   // Date of last password change
} saUSRINFOX;

infosize

The infosize parameter indicates the size of the structure (in bytes) pointed to by usrinfo. 

Operations supported by SA_USERSX(): 

ADD USER

To add a user, declare a variable of type saUSRINFOX and set the fields as desired. The version and 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_USERSX() with the ctuNEW action and the address of your saUSRINFOX structure.

Example

COUNT     rc;
saUSRINFOX usrinfo;

memset(&usrinfo, 0, sizeof(saUSRINFOX));
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");
usrinfo.version = saUSRINFOX_CURRENT_VERSION;

if ((rc = SA_USERSX(ctuNEW, &usrinfo,sizeof(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 saUSRINFOX and set the version and usr_id field to the user id to remove. Call SA_USERSX() with the ctuREMOVE action and the address of your saUSRINFO structure.

Example

COUNT     rc;
saUSRINFOX usrinfo;

memset(&usrinfo, 0, sizeof(saUSRINFOX));
strcpy(usrinfo.usr_id,      "QATEST");
usrinfo.version = saUSRINFOX_CURRENT_VERSION;

if ((rc = SA_USERSX(ctuREMOVE, &usrinfo, sizeof(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_USERSX() with the ctuLIST action and the address of your saUSRINFOX structure. Upon successful completion, SA_USERSX() sets the usr_list field of the saUSRINFOX 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. Each returned usr_list element must be freed with mbfree().

Example

COUNT     rc;
saUSRINFOX usrinfo;

memset(&usrinfo, 0, sizeof(saUSRINFOX));
usrinfo.version = saUSRINFOX_CURRENT_VERSION;
if ((rc = SA_USERSX(ctuLIST, &usrinfo, sizeof(usrinfo))) != 0)
   printf("List users failed with error %d (%d)\n", rc, isam_err);
else
{
   saUSRINFOX *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 saUSRINFOX, set the version and usr_id field to the user id whose password to change, and set the usr_pass field to the new password. Call SA_USERSX() with the ctuWORD action and the address of your saUSRINFOX structure.

Example

COUNT     rc;

saUSRINFOX usrinfo;

memset(&usrinfo, 0, sizeof(saUSRINFOX));

usrinfo.version = saUSRINFOX_CURRENT_VERSION;

strcpy(usrinfo.usr_id,      "QATEST");

strcpy(usrinfo.usr_pass,    "QATEST");

if ((rc = SA_USERSX(ctuWORD, &usrinfo, sizeof(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 saUSRINFOX, set the version and 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_USERSX() with the ctuGROUP action and the address of your saUSRINFOX structure.

Example

COUNT     rc;
saUSRINFOX usrinfo;

memset(&usrinfo, 0, sizeof(saUSRINFOX));
usrinfo.version = saUSRINFOX_CURRENT_VERSION;
strcpy(usrinfo.usr_id,      "QATEST");
strcpy(usrinfo.usr_group,   "ADMIN");

if ((rc = SA_USERSX(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 saUSRINFOX, set the version and usr_id field to the desired user id, and set the usr_desc field to the new description. Call SA_USERSX() with the ctuDESC action and the address of your saUSRINFOX structure.

Example

COUNT     rc;
saUSRINFOX usrinfo;

memset(&usrinfo, 0, sizeof(saUSRINFOX));
usrinfo.version = saUSRINFOX_CURRENT_VERSION;
strcpy(usrinfo.usr_id,   "QATEST");
strcpy(usrinfo.usr_desc, "QA test account for SA_ADMIN");

if ((rc = SA_USERSX(ctuDESC, &usrinfo, sizeof(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 saUSRINFOX, set the version, 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_USERSX() with the ctuMEM action and the address of your saUSRINFOX structure.

Example

COUNT     rc;
saUSRINFOX usrinfo;

memset(&usrinfo, 0, sizeof(saUSRINFOX));
usrinfo.version = saUSRINFOX_CURRENT_VERSION;
strcpy(usrinfo.usr_id,      "QATEST");
strcpy(usrinfo.usr_memory,  "300000");
strcpy(usrinfo.usr_memrule,  "A");

if ((rc = SA_USERSX(ctuMEM, &usrinfo, sizeof(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 saUSRINFOX, set the version,  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_USERSX() with the ctuXINFO action and the address of your saUSRINFOX 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;
saUSRINFOX usrinfo;

memset(&usrinfo, 0, sizeof(saUSRINFOX));
usrinfo.version = saUSRINFOX_CURRENT_VERSION;
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_USERSX(ctuXINFO, &usrinfo, sizeof(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 saUSRINFOX, set the version, 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_USERSX() with the uctGROUPRM action and the address of your saUSRINFOX structure.

Example

COUNT     rc;
saUSRINFOX usrinfo;

memset(&usrinfo, 0, sizeof(saUSRINFOX));
usrinfo.version = saUSRINFOX_CURRENT_VERSION;
strcpy(usrinfo.usr_id,      "QATEST");
strcpy(usrinfo.usr_group,   "ADMIN");

if ((rc = SA_USERSX(ctuGROUPRM, &usrinfo, sizeof(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 saUSRINFOX and set the version, set the usr_id field to the desired user id. Call SA_USERSX() with the ctuSHOW action and the address of your saUSRINFOX structure. Upon successful completion, SA_USERSX() fills your saUSRINFOX structure with the settings for the specified user.

Example

COUNT     rc;
saUSRINFOX usrinfo;
time_t     utctime;

memset(&usrinfo, 0, sizeof(saUSRINFOX));
usrinfo.version = saUSRINFOX_CURRENT_VERSION;
strcpy(usrinfo.usr_id,      "QATEST");

if ((rc = SA_USERSX(ctuSHOW, &usrinfo, sizeof(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);

   if (!usrinfo.usr_group[0])
       ctrt_printf("\nUser Groups: (None)");
   else
       ctrt_printf("\nUser Groups: %s", usrinfo.usr_group);
   utctime = (time_t)atoi(usrinfo.lastPasswordChange);
   ctrt_printf("\nLast password change: %s",myformat_UTC(utctime));
   printf("\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 Programmer’s Reference Guide for a complete listing of error values.

Limitations

Requires SA_LOGON() call.

See also

SA_GROUP(), SA_FILES(), SA_LOGON(), SA_LOGOF()

SA_WILDCARD

SA ADMIN function to find a file using a wildcard specification.

Declaration

NINT SA_WILDCARD(pTEXT infilnam, NINT mode, pTEXT outfilnam, NINT outfillen)

Description

• infilnam is the wildcard filename
• opcode is one of the following:

• outfilnam is the buffer to hold the found filename
• poutfillen points to the output buffer size

Note: The wildcard logic finds all files matching the wildcard specification — there is no check that the file is a c-tree data or index file. The wildcard logic also finds memory files whose names match the specified filename.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example SA ADMIN API pseudocode

#define MAX_SIZE 1024 /* 1K buffer size */
pText pFilelist;
int ListLength = MAX_SIZE

pFileList = (pText) malloc (sizeOf(pText) * MAX_SIZE);
memset(pFileList, 0, MAX_SIZE);

SA_LOGON("ADMIN", "ADMIN", NULL, "FAIRCOMS");
...
if ((rc = SA_WILDCARD("jrnl*.dat", ctFILWDfindfirst, pFilelist, ListLength)) !=0 ) {
ctrt_printf("SA_WILDCARD encountered the following error code(%n):\n", rc);
}
...

SA_LOGOFF();

SECURITY (function)

Modifies a file’s security settings, including password, group ID, and permission mask.

Short Name

SECURITY()

Type

Server only - FairCom DB File and User Security are available only when using the client/server operational model.

Declaration

COUNT Security(FILNO filno, pVOID bufptr, VRLEN bufsiz, COUNT mode) 

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

Security() permits the owner of a file to change a file’s security information, including the file’s password, Group ID, and permission mask. Security() permits members of the ADMIN group to change the default number of allowed consecutive logon failures or the default time to deny logon attempts after the failure limit is reached.

For file security changes to file number filno: bufptr points to the buffer containing the updated security information and bufsiz specifies the length of the buffer. The contents of the buffer will differ based on the mode. See the section below for a description of what to pass in the buffer. See the section below for a description on what to pass in the buffer.

The buffer should contain the old password, NULL terminated, immediately followed by the new information, also NULL terminated, which can be the new file password, new file group ID, new owner user ID, or the new permission mask. If you are changing the permission mask, the value following the NULL terminated old password must be a long integer containing the appropriate OR-ed permission values. To remove a password, simply pass a NULL byte for the new password. If you change the file owner, you will not be able to make additional calls to Security, only the new owner will be able to do so.

Note: FAIRCOM.FCS can be opened only by a member of the ADMIN group. ADMIN group members can read data from FAIRCOM.FCS using low-level or ISAM function calls but cannot update FAIRCOM.FCS, other than through calls through the SECURITY() API function.

mode defines the type of request. The values for mode are:

filno is ignored when mode is SEC_FAIL_LIMIT or SEC_FAIL_TIME.

Buffer Contents

SEC_ADD_USER

2-byte extended user settings file number (FAIRCOM.FCS!UVAL.dat)

2-byte group file number (FAIRCOM.FCS!GROUP.dat)

2-byte user group file number (FAIRCOM.FCS!USER.dat)

2-byte FC_USER length

FC_USER data

2-byte FC_UVAL length

FC_UVAL data

1-byte number of groups

group 0 name, group 1 name, ... (NULL terminated strings)

SEC_REMOVE_USER

2-byte extended user settings file number (FAIRCOM.FCS!UVAL.dat)

2-byte user group file number (FAIRCOM.FCS!USER.dat)

null-terminated user name

SEC_CHANGE_USER_PASSWD

null-terminated user name

null-terminated user password

SEC_CHANGE_USER_GROUPS

2-byte group file number

2-byte user group file number

null-terminated user ID

1-byte number of groups

group 0 name, group 1 name, ... (NULL terminated strings)

SEC_CHANGE_USER_DESC

null-terminated user name

null-terminated user description

SEC_CHANGE_USER_MEMORY

null-terminated user name

4-byte user memory

4-byte user memory attribute

SEC_CHANGE_USER_XINFO

2-byte extended user settings file number

2-byte user group file number

2-byte FC_UVAL length

FC_UVAL data

SEC_CHANGE_USER_LOGLMT

null-terminated user name

4-byte user logon limit

SEC_ADD_GROUP

2-byte FC_GROUP length

FC_GROUP Data

SEC_CHANGE_GROUP_DESC

null-terminated group name

null-terminated group description

SEC_CHANGE_GROUP_MEMORY

null-terminated group name

4-byte group memory

4-byte group memory attribute

SEC_CHANGE_GROUP_LOGLMT

null-terminated group name

4-byte group logon limit

SEC_FILEWORD

null-terminated password

SEC_FILEMASK

1-byte set to 0

filemask

SEC_FILEGRUP

null-terminated group name

SEC_FILEOWNR

null-terminated owner name

SEC_CHECK_ADVENC_PASSWD

Check if the specified master encryption password matches FairCom Server's current master encryption password. This feature is only supported in client/server mode and can only be done by a user account that is a member of the ADMIN group. To use this feature, call the SECURITY() function as described below:

• FILNO filno - Set to -1.
• pVOID bufptr - Pass the advanced encryption password as a null-terminated string.
• VRLEN bufsiz -Set to the length of the advanced encryption password in bytes including the null terminator.
• COUNT mode - Set to SEC_CHECK_ADVENC_PASSWD.

If called by a user account that is not a member of the ADMIN group, the function returns error LADM_ERR (589).

If advanced encryption is not enabled, the function call returns error NSUP_ERR (454).

If the specified master password does not match the master password that FairCom Server is currently using, the function returns error BMPW_ERR (932).

One-Time Password

To establish a one-time password that another client can use, along with the user ID matching the caller that set the password, set bufptr to a special, (0x01 in first byte), one-time password and plen to the length of the password. filno is ignored. The password is available until it is used by the subsequent client with a matching user ID or the caller of Security logs off. The password set by the original caller MUST begin with a byte of value 0x01, otherwise it will be ignored.

To change the Logon Fail Limit in real time regardless of setting file or configuration file entries, point bufptr to a LONG holding the new LOGON_FAIL_LIMIT value. The value is stored in FAIRCOM.FCS and can only be changed by a subsequent call to Security or by replacing FAIRCOM.FCS. filno is ignored.

To change the time interval regardless of setting file or configuration file entries, point bufptr to a LONG holding the new LOGON_FAIL_TIME value in minutes. The value is stored in FAIRCOM.FCS and can only be changed by a subsequent call to Security or by replacing FAIRCOM.FCS. filno is ignored.

FC_UVAL Structure

The FC_UVAL structure holds settings used by the SECURITY() function. Some of the mode settings require setting values in this structure.

typedef struct {
  TEXT  userid[32];
  ULONG begstamp;      /* beginning date for valid user logon     */
  ULONG endstamp;      /* last valid date for user logon          */
  LONG  lgonover;      /* limit on consecutive logon failures     */
  LONG  reserved;
  ULONG rsmstamp;      /* temporary logon block                   */
  LONG  lgonfail;      /* current number of failed login attempts */
  ULONG lgonany;       /* last logon attempt date                 */
  ULONG lgonok;        /* last successful login date              */
  ULONG lgonbad;       /* last failed login date                  */
  LONG  lgonoknum;     /* Total number of successful logins(ever) */
  LONG  lgonbadnum;    /* Total number of failed logins(ever)     */
  ULONG disstamp;      /* when logon was disabled                 */
  LONG  lgonmust;      /* user must login within this period      */
  ULONG lastpasschg;   /* time of last change to password         */
  ULONG passvaliddays; /* number of days that password is valid   */
  TEXT  resrv[92];
} FC_UVAL;

When calling SECURITY() with mode of SEC_FAIL_LIMIT to set the logon failure limit, set the maximum limit in lgonover.

When calling SECURITY() with mode of SEC_FAIL_TIME to set the logon failure time, set the maximum time (in seconds) in lgonmust.

When calling SECURITY() with mode of SEC_CHANGE_USER_XINFO to set an expiration date on a user account password, set the passvaliddays field of the FC_UVAL structure to the password validity period in days. A value of zero sets no password expiration. When a user account's password has expired, attempting to log on to the user account fails with error 1116 (PWDEXP_ERR). This feature is also available in the ctadmn and sa_admin utilities.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

API Call to Verify Server Master Password

The SECURITY() function now supports the ability to check if the specified master encryption password matches the FairCom Server's current master encryption password. It provides the ability to check that the user is able to connect as ADMIN.

This feature is only supported in client/server mode and can only be accessed by a user account that is a member of the ADMIN group. To use this feature, call the SECURITY() function as described below:

SECURITY() parameters:

• COUNT filno: Set to -1.
• pVOID bufptr: Pass the advanced encryption password as a null-terminated string.
• VRLEN bufsiz: Set to the length of the advanced encryption password in bytes including the null terminator.
• COUNT mode: Set to SEC_CHECK_ADVENC_PASSWD.

Function return values for this mode:

• The function returns NO_ERROR(0) on success.
• If called by a user account that is not a member of the ADMIN group, the function returns error LADM_ERR (589).
• If advanced encryption is not enabled, the function call returns error NSUP_ERR (454).
• If the specified master password does not match the master password that c-tree Server is currently using, the function returns error BMPW_ERR (932).

Changing the Master Password

To change the master password using the SECURITY() function:

1. Call the SECURITY() function with the SEC_CHANGE_ADVENC_PASSWD mode.
2. Specify filno of -1.
3. Set bufptr to point to a buffer that holds the master password change information and set bufsiz to the size of the buffer.
   
   The buffer must conform to the ctENCMOD structure definition shown below:
   
   typedef struct ctencmod
{ LONG options; LONG numfiles; TEXT varinf[4]; }
ctENCMOD, *pctENCMOD;
    
4. Set options to ctENCMODlowl
5. Set numfiles to the number of files whose names are specified in the varinf field (do not include the current and new master passwords in this count even though those values are also specified as the first two strings in the varinf field).
6. In the varinf field, store the following values as null-terminated strings:
   • the current master password
   • the new master password
   • the first c-tree file name
   • the second c-tree file name
   • ...
   • the Nth c-tree file name (where N equals numfiles)

When using the FairCom Server master password change interface, FairCom Server attempts to change the master password for the specified files and for all active, inactive, and template transaction logs that it knows about. If any of the files cannot be changed, the entire operation is undone. When the entire operation is successful, the ctsrvr.pvf file is also updated using the new master password.

If an error happens on the transaction logs but the FairCom Server terminates before it can undo the changes, some files may be left using the new master password but the master password is still set to the old value. In this case, the ctencrypt standalone utility (see Changing the master password using the ctencrypt standalone utility) can be used to change the master password for those c-tree data, index, or transaction log files that need to be changed.

Error Codes

Two error codes have been added:

See c-tree Error Codes for a complete listing of valid c-tree error values.

This also requires that the ALLOW_MASTER_KEY_CHANGE configuration option is enabled, as explained in the FairCom DB Server Administrator's Guide.

See also

See Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide for more information.

Ability to Validate against Advanced Encryption Master Password

FairCom Server now supports the ability to check if a client-provided master encryption password matches FairCom Server's current master encryption password. The use case for this feature is an elevated level of access beyond ADMIN authentication. Knowing the master encryption password implies the calling user has elevated privileges.

The server is assumed already started with a valid master key. A new SECURITY() (SECURITY (function), Security) API mode makes this check against the current master key.

SetAlternateSequence

Establishes an alternative collating sequence for an index file.

Short Name

SETALTSEQ()

Type

Low-Level index file resource function

Declaration

COUNT SetAlternateSequence(FILNO keyno, pCOUNT altseq)  

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

SetAlternateSequence() assigns an alternative collating sequence to index keyno, which has just been created and not yet closed, or has been opened exclusively. Resources must be enabled for the index file in order to complete this function successfully.

altseq points to an array of 256 short integers representing the new collating sequence. The zero’th and 255th entries in the array must be zero and 255, respectively. All other entries must be between zero and 255, inclusively. The value in the array determines where the underlying byte value will be mapped: a high value implies toward the end of the sequence.

Although this is a low level function, it ordinarily only applies to ISAM level key operations in which segment mode 32 (ALTSEG) is used to specify the use of an alternative collating sequence. See alternate collating sequence in the index for additional information.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

/* The start of a full alpha sort: A, a, B, b, etc. */

  COUNT altseq[256];

    altseq['A'] = 65;
    altseq['a'] = 66;
    altseq['B'] = 67;
    altseq['b'] = 68;
/* Fill in ALL values in the array. */

See also

GetAlternateSequence()

SetCallbackOnRebuild

Sets up a callback function that file reconstruction functions call as progress is made during an operation.

Short Name

SETCBRBL()

Type

Low-Level function

Declaration

COUNT SetCallbackOnRebuild( pVOID funcptr, UCOUNT step ) 

Description

SetCallbackOnRebuild() sets a pointer to a callback function that is periodically called by the file reconstruction functions RebuildIFile(), RebuildIFileXtd(), CompactIFile(), and CompactIFileXtd(). The callback function can be used for progress notification and to implement a custom user interface for rebuild utility programs.

When the rebuild callback support is activated, an internal counter is incremented every time a record or key is processed during the reconstruction process. The callback function is called each time the internal counter reaches a value that is a multiple of step. If step is set to 1, the callback function is called once per record/key. The ability of setting the callback frequency, gives the user the ability to balance between speed and accuracy.

The funcptr must be a pointer to a callback function of type RBLCBFNC that accepts three parameters. The function prototype is shown below.

void (*pRBLCBFNC)(ULONG counter, TEXT event, pTEXT message);

• Counter is the current value of the internal counter.
• event identifies the type of event that triggered the callback. event options are listed in the following table:

• message is a text string to be returned.

Return

Always returns NO_ERROR (0).

Example CTRBLEX.C in the ctree\samples directory

IFIL my_ifil = {...};

void CallbackProc( ULONG counter, TEXT event, TEXT* message )
{
   switch(event)
   {
      case RBLCB_DAT:
         putchar('d');
         break;
      case RBLCB_IDX:
         putchar('i');
         break;
      case RBLCB_MSG:
         printf("\n%s", message);
         break;
      case RBLDB_CNT:
         printf("\n%s", counter);
         break;
      case RBLCB_LOG:
         printf("\n%s", message);
         break;
      case RBLDB_MCT:
         printf("\n%s", (double) counter / 10);
   }
}

void main()
{
   SetCallbackOnRebuild( CallbackProc, 1 );
   RebuildIFile( &my_ifil );
}

See also

RebuildIFile()

RebuildIFileXtd()

CompactIFile()

CompactIFileXtd()

GETCBRBLST

SetDataFilter

Specify a data filter for a given data file.

Short Name

SETFLTR()

Type

Low-Level Data Manipulation

Declaration

COUNT SetDataFilter(FILNO datno, pTEXT condexpr)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

SetDataFilter() specifies that the data filter condexpr should be used for reads from data file datno until a new filter is set or the file is closed. To “turn off” a filter without closing the file, simply call SetDataFilter() with an empty string ("") for the conditional expression.

A Low-Level data record read returns FFLT_ERR (739) if the data record exists but does not satisfy the filter. ISAM level record requests, including sets and batches, skip over records failing the filter transparently to the user. In client/server, this may substantially reduce network traffic.

For partitioned files, call SetDataFilter() for the host data file and the filter automatically applies to each partition member file.

The condexpr string is similar to those used for conditional index support: it may be a logical expression involving field names from the record schema or a callback designator (e.g., “@mycallback”). See FairCom DB EXPRESSION PARSER AND GRAMMAR.

Row Level Permanent Callback Filters

Introduction

The c-tree API function SetDataFilter() can be used to establish a temporary, user-specific, filter for data record access (please see the section “Data Filters and Conditional Indexes” in the c-tree Plus Programmer’s Reference Guide). SetDataFilter() now supports establishing a new type of permanent system-wide filter.

Consider the case of requiring a customized security audit trail. Individual record reads and writes can be monitored and logged with these permanent filters in place. An application could also use this feature to restrict a user’s ability to read and/or write records based on the row from the table of interest. thereby enabling a row level security mechanism. The username, table, and operation attempted, including the record image, are all data available to your application.

System Level Callback Functions

If the conditional expression in the call to SetDataFilter() begins with either “@@?” or “@@!” then a permanent, system-wide (i.e., applies to all users) read or write filter, respectively, will be added to the file. Calling SetDataFilter() with a conditional expression that exactly matches “@@?” or “@@!” will cause the permanent read or write filter, respectively, to be deleted from the file.

To add or delete one of these filters, the file must be opened exclusively, and the calling user must have file definition permissions.

These filters are call-back filters. This is ensured with the leading ‘@’ character. A file may have at most one read and one write permanent filter.

• ctfiltercb_rowl() is a new callback function located in module ctclbk.c where the actual callback evaluation takes place.

Two existing callback functions are also called during filter initialization and de-initialization:

• ctfiltercb_init() - called each time a new filter is established or when a table with a permanent system wide filter is opened.
• ctfiltercb_uninit() - called each time a new filter is deleted, or when a table with a permanent system wide filter is closed.

c-tree stores these callback expressions in a c-tree file resource. It is important that the developer take care to restrict the ability to delete or otherwise modify these important file resources. Please see the features available regarding File Definition Resource (FCRES) Security in FILEDEF_SECURITY_LEVEL in the FairCom DB Administrator's Guide.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

See also

Data Filters and Conditional Indexes

ctfiltercbAddFilter(), EvaluateFilter(), LoadFilter(), ctfiltercbRemoveFilter(), UnloadFilter()

ctfiltercb_rowl(), ctfiltercb_init(), ctfiltercb_uninit()

SETFLTRN (SETFLTRN, /doc/ctreeplus/setfltrn.htm)

SetEncryption

Enable or disable encryption and set or reset encryption key.

Short Name

ctSETENCRYPT()

Declaration

COUNT SetEncryption(pTEXT mod, pTEXT key, VRLEN keylen)

Description

To encode index and data files without a parameter file, use SetEncryption() before the create file calls.

• mod - use one of the symbolic constants listed below for Advanced File Encryption
• keylen indicates the length of the key. keylen of 0 disables encryption for any files created after that point.

To stop encrypting new files, call SetEncryption() with keylen set to zero. See ctSETENCRYPT - Passing a NULL to disable encryption.

Remember: Although key is ignored when using an Advanced Encryption cipher, keylen is used to enable or disable encryption as described above.

Available Ciphers

Ciphers available prior to V13

SetEncryption() only affects file creation operations. All files created after a given call to SetEncryption(), with a keylen greater than zero will be encrypted with the same key. Therefore, at the ISAM level, a data file and its associated indexes will be created with the same encryption key. Turning encryption on and off through calls to SetEncryption() only affects whether or not a new file is encrypted. Once a file is set for encryption, it is always encrypted.

SetEncryption Examples

The following pseudo-code encrypts the first ISAM data file and its indexes using Advanced Encryption ciphers, and does not encrypt the second ISAM data file and its indexes:

InitISAM(...)

SetEncryption (ctAES32, NULL, 1)
CreateIFile(..1..)

SetEncryption (NULL, NULL, 0)
CreateIFile(..2..)

Sample Calls to Enable or Disable Encryption

Either of these calls will enable AES encryption (if a key is specified, it is ignored):

ctSETENCRYPT(ctAES32, "mykey", 5);
ctSETENCRYPT(ctAES32, NULL, 5);

Any of these calls will disable encryption:

ctSETENCRYPT(ctENCR, NULL, 0);
ctSETENCRYPT(NULL, NULL, 0);
ctSETENCRYPT(NULL, NULL, -99);
ctSETENCRYPT(ctAES32, NULL, 0);
ctSETENCRYPT(ctAES32, NULL, -10);

Note: SetEncryption() does not enable transaction log file encryption. Use the LOG_ENCRYPT configuration option to encrypt transaction log data.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

See Also

• Encryption (Advanced File Encryption, Advanced Encryption)
• ctSETENCRYPT - Passing a NULL to disable encryption

SetFileSegments

Segmented file support configuration function.

Short Name

ctSETSEG()

Type

Low-Level function

Declaration

COUNT SetFileSegments(FILNO filno, NINT aseg, NINT tseg, pSEGMDEF pseg)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

SetFileSegments() configures the segments for file filno. aseg specifies the number of active segments, i.e., the segments created immediately. aseg must be at least one and less than or equal to tseg. tseg specifies the total number of segments pointed to by pseg. pseg points to an array of SEGMDEF structures.

If the first segment definition pointed to by pseg has a sgname pointing to the empty string, i.e., *sgname == ‘\0’, not sgname == NULL, the sgsize member of the structure becomes the host segment size limit. Only the last segment can have a size limit of zero, which is interpreted as no limit.

Additional segments automatically become active as needed, up to the maximum set in tseg. The segments are used in the order defined by the array of SEGMDEF structures pointed to by pseg.

The file referenced by filno must be opened in ctEXCLUSIVE mode the first time SetFileSegments() is called. Note that a file which has been created and not yet closed is always in ctEXCLUSIVE mode, regardless of the file mode specified as part of the create call.

Modifying Segment Definitions

After the segment definitions have been established by the first call to SetFileSegments(), it is possible to call SetFileSegments() to modify the segment definitions even while the file is being updated. However, it is not possible to change a segment size so that the new size is smaller than the actual physical size of the segment, nor can SetFileSegments() rename a segment that is in use. A segment is in use if data beyond the segment header information has been written to the segment. An active segment is not in use just because it is on disk; data must have been written to it. Therefore, a call to SetFileSegments() can, in real time, change where segments will reside (provided the segment is not already in use) and/or how large they are (provided the new size is not smaller than the current physical size nor is the segmented already completely full).

Changing the Number of Segments

SetFileSegments() can be used to change the number of segments for a file that uses the automatic segment feature (ctSEGAUTO). Call SetFileSegments() as follows:

• Set aseg to zero
• Set tseg to the new maximum number of automatic segments
• Set pseg to point to a single SEGMDEF structure in which the sgname field is ignored and the sgsize field specifies the size of all the segments, including the host file.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

SEGMDEF segdef[2] = {
  {"d:\\data\\dataseg.2",1024}, /* 1024MB = 1GB size limit   */
  {"e:\\data\\dataseg.3",0}     /* no limit on segment size  */
};

IFIL fil = {...}

/* create files        */
if (CreateIFileXtd8( &fil, NULL, NULL, 0L, NULL, NULL,
          &creblk))  /* pointer to array of XCREblks         */
    printf("Could not create %s (%d,%d)\n", fil.pfilnam, isam_err, isam_fil);
 
/* specify definitions for the two other segments            */
if (SetFileSegments(
   fil.tfilno,  /* data file number                          */
            1,  /* one active segment (the host segment)     */
            2,  /* two segment definitions to be passed      */
      segdef))  /* pointer to the segment definitions        */
    printf("Could not set file segments (%d,%d)\n", isam_err, isam_fil);

Limitations

The fxtsiz member of the XCREblk structure cannot be set higher than the size of the first (host) segment during a file create. This results in SEGM_ERR (674) signifying the need for more segments, which do not exist yet because SetFileSegments() has not yet been called.

The file referenced by filno must be opened in ctEXCLUSIVE mode the first time SetFileSegments() is called.

See also

GetXtdCreateBlock()

SETFLTRN

Sets a filter having the specified filter number. Multiple filters allows advanced data filtering capability.

Type

Low-Level function

Declaration

COUNT SETFLTRN(FILNO datno, UCOUNT fltnum, UCOUNT fltopts, pTEXT expression);

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

The function prototype for SETFLTRN() is very similar to SetDataFilter(). SETFLTRN() includes two additional parameters:

• fltnum specifies the filter number
• fltopts specifies filter options.

The filter number determines the order in which a filter is evaluated: filters are evaluated in ascending order by filter number. Two filters cannot have the same filter number. A call to SETFLTRN() for filter number N replaces an existing filter that has that filter number.

A call to SETFLTRN() may specify a filter number in the range 0 through 16383. The upper two bits of the filter number value are reserved for internal use. A call to SETFLTRN() with a filter number larger than 16383 fails with error PBAD_ERR (749, bad parameter value).

Currently, the only supported filter option is ctDATFLT_OPTION_CURCTX, which indicates that the data filter applies only to the ISAM context in which it was created. When this filter option is not specified (that is, if the caller specifies zero for fltops), the filter applies to all ISAM contexts, and is how the current SetDataFilter() function behaves.

FairCom DB API layers use SETFLTRN() with the ctDATFLT_OPTION_CURCTX option for data filters as FairCom DB API expects a data filter to apply only to a particular context.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

rc = NXTVREC(CUSTDAT, recbuf, &reclen);
if (rc != INOT_ERR) {
ctrt_printf("Error: Failed to read record: %d\n", rc);
goto err_ret;
}

/* Set filter to read record 'b' only. */
if ((rc = SETFLTRN(CUSTDAT, 1, 0, "!strncmp(ZipCode, \"b\", 1)"))) {
ctrt_printf("Error: Failed to set data filter: %d\n", rc);
goto err_ret;
}

/* Read the record. */
reclen = bufsiz;
if ((rc = FRSVREC(CUSTDAT, recbuf, &reclen))) {
ctrt_printf("Error: Failed to read record: %d\n", rc);
goto err_ret;
}

if (recbuf[4] != 'b') {
ctrt_printf("Error: First record value (%c) does not match expected value (b)\n",
recbuf[4]);
rc = 1;
goto err_ret;
} 
 
rc = NXTVREC(CUSTDAT, recbuf, &reclen);
if (rc != INOT_ERR) {
ctrt_printf("Error: Failed to read record: %d\n", rc);
goto err_ret;
}
ctrt_printf("Successfully read record b with filter.\n");

/* Set filter to read record 'a' only. */
if ((rc = SETFLTRN(CUSTDAT, 1, 0, "!strncmp(ZipCode, \"a\", 1)"))) {
ctrt_printf("Error: Failed to set data filter: %d\n", rc);
goto err_ret;
}

/* Read the record. */
reclen = bufsiz;
if ((rc = FRSVREC(CUSTDAT, recbuf, &reclen))) {
ctrt_printf("Error: Failed to read record: %d\n", rc);
goto err_ret;
}

if (recbuf[4] != 'a') {
ctrt_printf("Error: First record value (%c) does not match expected value (a)\n",
recbuf[4]);
rc = 1;
goto err_ret;
}

rc = NXTVREC(CUSTDAT, recbuf, &reclen);
if (rc != INOT_ERR) {
ctrt_printf("Error: Failed to read record: %d\n", rc);
goto err_ret;
}
rc = NO_ERROR;
ctrt_printf("Successfully read record a with filter.\n");

/* Set filter to read record 'a' and 'b' only. */
if ((rc = SETFLTRN(CUSTDAT, 2, 0, "!strncmp(ZipCode, \"b\", 1)"))) {
ctrt_printf("Error: Failed to set data filter: %d\n", rc);
goto err_ret;
}

/* Read the record. */
reclen = bufsiz;
rc = FRSVREC(CUSTDAT, recbuf, &reclen);

if (rc != INOT_ERR) {
ctrt_printf("Error: Expected record read to fail with INOT_ERR but return code is : %d\n",
rc);
if (!rc)
rc = 1;
goto err_ret;
}

See also

SetDataFilter()

SETLOGPATH

Set transaction processing control file paths for single-user applications.

Short Name

SETLOGPATH()

Type

Low-Level function

Declaration

COUNT SETLOGPATH(pTEXT path, NINT mode)  

Description

SETLOGPATH() sets the path for the transaction processing log files, start files and temporary support files for single-user transaction processing applications.

SETLOGPATH() must be called BEFORE the initialization of c-tree (i.e., before InitCTree(), InitISAM(), etc.). Therefore, it does not set uerr_cod. It returns the error code or zero if successful. If c-tree is shutdown and restarted within an application, SETLOGPATH() must be repeated just prior to each c-tree initialization.

If ctNOGLOBALS is used with instance control functions, the instance must be registered by calling RegisterCtree() before SETLOGPATH() is called. Each SETLOGPATH() call applies to only one instance of c-tree.

• path is a pointer to the string with the path to be used. It should end with a path or device separator, and it is best if the path is absolute.
• mode takes one of the following values:

These modes apply only to the optional mirrored log files and start files:

• ctlogALL_MIRROR
• ctlogSTART_MIRROR
• ctlogLOG_ODD_MIRROR
• ctlogSTART_ODD_MIRROR
• ctlogLOG_MIRROR
• ctlogLOG_EVEN_MIRROR
• ctlogSTART_EVEN_MIRROR

The simplest approach is to call SETLOGPATH() with the mode ctlogALL. Unless mirrored logs are desired, this is the only call required. If mirror files are desired then a second call with mode ctlogALL_MIRROR will handle all the mirrored files. The other modes are provided for unusual situations in which individual files must be placed in different locations.

If the ctlogALL mode is not used, typically more than one call to SETLOGPATH() is required.

A call made by a FairCom Server client to SETLOGPATH() returns zero, but has no effect. The FairCom Server configuration file specifies the modified names for the log and related files. However, a LOCLIB call to SETLOGPATH() sets the names for the local log files.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

NINT rc;

if (rc = SETLOGPATH("/usr/logarea/",ctlogALL))
    printf("Could not setup log file names (%d)\n",rc);

SetNodeName

Sets a client side node name.

Short Name

SETNODE()

Type

Server only

Declaration

COUNT SetNodeName(pTEXT nodename) 

Description

SetNodeName() specifies a client side node name. The specified name appears in the ctadmn utility under the option for ‘list clients’.

The alternative method is to define the global variable ctnodnam. This variable is a null terminated, 32-byte, ASCII string hold the desired value. To set the ctnodnam to the string “Development Sun Sparc” do the following:

strcpy(ctnodnam,"Development Sun Sparc");

Note: SetNodeName() must be called after c-tree has been initialized, typically with InitISAMXtd().

Return

Always returns NO_ERROR (0).

Example

pTEXT     nodename = "Development Sun Sparc";

SetNodeName(nodename);

Limitations

Available only with the FairCom Server. A call to SetNodeName() on a non-server system results in NO_ERROR (0) error return.

See also

InitISAMXtd()

SetOperationState

Set operation modes for special performance-related functionality and test operational states for critical events.

Short Name

SETOPS()

Type

Low-Level function

Declaration

LONG SetOperationState( LONG status_word, VRLEN operation_code ) 

Description

SetOperationState() allows an application to set or return a 4-byte status word. The bits of the status word change default operation modes. status_word options options are listed in the following table and detailed below:

operation_code options are:

OPS_READLOCK - The set operations function, SETOPS(), enables automatic, low level, blocking read locks on each record access that does not already have a lock. The locks are released automatically as soon as the record is read. Blocking locks permit a c-tree application to be coded the same whether or not the automatic locks have been requested. But this means a read will block until the read lock is available. The locking code is in the REDREC(), iRDVREC(), and REDVREC() routines.

SETOPS(OPS_READLOCK,opcode)

will turn on or off the read lock state.

If ctBEHAV_READLOCK is not enabled, the SETOPS() call will not return an error, and no automatic locking will take place. The state variable returned by SETOPS() will not have the OPS_READLOCK bit set.

OPS_UNLOCK_ADD - If on, causes automatic record unlocks on calls to AddRecord() or AddVRecord(). A loop of the form:

   while (. . .) {
    LockISAM(ctENABLE);
    AddRecord(. . .);
    LockISAM(ctFREE);
}
could be replaced with:
SetOperationState(OPS_UNLOCK_ADD,OPS_STATE_ON);
while(. . .) {
    AddRecord(. . .);
}

OPS_UNLOCK_RWT - Causes automatic record unlock on calls to ReWriteRecord() or ReWriteVRecord(). Similar to the OPS_UNLOCK_ADD, this mode eliminates the need to call LockISAM(ctFREE). If the rewrite fails, the record remains locked.

OPS_LOCKON_GET - Unlike the previous two modes, this status word mode must be set before each use. However, the OPS_STATE_ON call for OPS_LOCKON_GET is not sent to the c-tree Server, so repeated calls do not cause network overhead. OPS_LOCKON_GET should not be OR-ed with any other status_word constants.

OPS_LOCKON_GET and OPS_UNLOCK_RWT can significantly reduce the number of calls needed to lock, read, update and unlock a record. A loop of the form:

while(. . .) {
    LockISAM(ctENABLE);
    GetRecord(. . .);
    ReWriteRecord(. . .);
    LockISAM(ctFREE);
}

which requires four calls to the c-tree Server for each loop, can be replaced with:

SetOperationState(OPS_UNLOCK_RWT, OPS_STATE_ON);
while(. . .) {
    SetOperationState(OPS_LOCKON_GET, OPS_STATE_ON);
    GetRecord(. . .);
    ReWriteRecord(. . .);
}

where only two calls go to the c-tree Server for each loop.

Note: The OPS_LOCKON_GET state is cleared on the subsequent read operation, whether or not the read operation succeeds. Thus, there is no need to call OPS_STATE_OFF for this mode. In fact, doing so results in additional network calls to the server defeating any benefits gained. If the read operation fails, the lock is freed automatically on return from the read operation. Use OPS_LOCKON_GET prior to any low level or ISAM level retrieval function, such as FirstRecord() or ReadData().

OPS_LOCKON_BLK - Behaves as OPS_LOCKON_GET except the lock request is a blocking lock. If the lock is denied, the client is placed in a wait list for the lock, which is granted on a FIFO (First In First Out) basis. The application does not see the lock denial, does not have to issue retries, and waits forever for the lock. However, while waiting in the wait list, if the requesting client would cause a deadlock, the retrieval operation fails with DEAD_ERR (86). Support for this option is only guaranteed by the c-tree Server. Many non-server, multi-user systems do not support blocking locks, and OPS_LOCKON_BLK functions as a non-blocking lock.

SetOperationState(OPS_LOCKON_BLK,OPS_STATE_ON);    /* enable */
SetOperationState(OPS_LOCKON_BLK,OPS_STATE_OFF);  /* disable */

OPS_FUNCTION_MON - Toggles the c-tree Server function monitor.

OPS_MIRROR_NOSWITCH - Changes how errors related to mirrored files are handled. The default protocol is to try to continue operation with either the primary or the mirror file if the other fails. If the primary fails, all I/O continues on the mirror. If the mirror fails, all I/O continues on the primary. When operation continues with the remaining good file, either primary or mirror, the c-tree Plus function returns successfully. However, this situation causes an event to be reported via SystemMonitor(), and the OPS_MIRROR_TRM bit is set in the status_word.

Calling SetOperationState(OPS_MIRROR_NOSWITCH, OPS_STATE_ON), changes the application protocol. If either the primary or the mirror fails, the entire operation fails and returns an appropriate error code. Use SystemMonitor() to monitor for primary/mirror errors under either protocol.

OPS_AUTOISAM_TRN - Implements automatic transaction begins, commits, or aborts for the six ISAM update routines: AddRecord(), DeleteRecord(), ReWriteRecord(), AddVRecord(), DeleteVRecord(), ReWriteVRecord(). Automatic transactions reduce the network traffic for single ISAM updates. These automatic transactions can be used for both Server and single user implementations. The calls:

SetOperationState(OPS_AUTOISAM_TRN,OPS_STATE_ON);
SetOperationState(OPS_AUTOISAM_TRN,OPS_STATE_OFF);

turn on and off, respectively, automatic transaction begins, commits or aborts for the six ISAM update routines listed above. When turned on, automatic transactions start a transaction at the beginning of each of these six ISAM update routines if, and only if, no transaction is already active. Upon successful conclusion of these ISAM updates, the transaction is committed. If an error occurs, the transaction is aborted. Of course, these automatic commits or aborts are only invoked if an automatic transaction was started at the beginning of the ISAM update routine.

Assuming SetOperationState(OPS_AUTOISAM_TRN, OPS_STATE_ON) has been called and that an update on a transaction processed file is to be performed without an explicit call to Begin, then the system behavior is as follows:

1. An automatic transaction will not free locks acquired outside the automatic transaction, unless the lock is on an item updated or locked in the transaction. This is similar to ctKEEP_OUT behavior as explained in the Begin function description.
2. An aborted automatic transaction, which occurs when the update returns an error, always releases locks acquired in the transaction.
3. If the LockISAM() state is ctENABLE or ctENABLE_BLK, or these states have been restored via LockISAM(ctRESTORE), or ctRESTORE_BLK, respectively, an automatic transaction will not free any locks on commit, similar to Commit(ctKEEP) or Abort(ctKEEP_OUT).

If OPS_UNLOCK_UPD is on, both commits and aborts on automatic transactions behave according to ctKEEP_OUT, regardless of the LockISAM() state.

OPS_TRACK_MON - Causes the net count of memory allocation requests to be output upon each calling of SetOperationState().

SetOperationState(OPS_TRACK_MON,OPS_STATE_ON);
SetOperationState(OPS_TRACK_MON,OPS_STATE_OFF);

Turning on the tracking via SetOperationState() uses a default threshold value of 250. Each such call to SetOperationState(), in addition to each time the threshold value is encountered, increasing or decreasing, produces a debug line of output to STDOUT, typically the c-tree Server console screen, detailing the current net allocation count. Override the threshold value by placing the keyword MEMORY_TRACK in the c-tree Server configuration file. This feature is intended for dynamically tracking the c-tree Server memory consumption.

OPS_LOCK_MON - Enables the lock monitor whether or not the configuration file contains LOCK_MONITOR. If there is no configuration entry, the threshold value is set to 100. SetOperationState(OPS_LOCK_MON, OPS_STATE_OFF) turns off the lock monitor. When SetOperationState() is called to turn the monitor on or off, and each time the threshold value is encountered, increasing or decreasing, a message specifying the current number of excess locks is sent to the c-tree Server console. The net lock count is always maintained. Therefore, if a monitor is subsequently turned on by SetOperationState(), the current lock count will be correct. There is almost no overhead to maintain this value: only a simple increment or decrement on each lock or unlock. This function is useful for assuring proper locking operation.

OPS_MIRROR_TRM - When the mirror error handling protocol is not changed via OPS_MIRROR_NOSWITCH, if a primary or mirror fails, causing the c-tree Server to go on using only one file, the OPS_MIRROR_TRM bit is set in status_word. It can be tested as follows:

if (SetOperationState((LONG)0,OPS_STATE_RET) & OPS_MIRROR_TRM)
 printf("System continuing with a primary or mirror failure.");

OPS_SERIAL_UPD - When turned on causes GetSerialNbr() to return a unique serial number. This mode allows manual serialization of the data by the application. GetSerialNbr() normally returns the current value of the file’s serial number.

Note: FairCom does not recommend this option. Corrupt files may contain an improper last-used-value in the header after a rebuild operation. When serial numbers are included in records via the serial number key segment mode, rebuild determines the highest used serial number and resets the value in the header.

For transaction controlled files, a transaction must be active to call GetSerialNbr() when OPS_SERIAL_UPD has been turned on.

OPS_DEFER_CLOSE - Defers a file closes or deletes requested during transactions. By default, a file close or delete request during a transaction returns CPND_ERR (588). Turning on the defer option allows the function to return NO_ERROR (0) and continue, while the actual close or delete is deferred until the end of the transaction.

OPS_CONV_STRING - For a data record containing CT_STRING field data in the fixed length portion of the record buffer, if the CT_STRING data is padded with null (0x0) bytes, and if a c-tree client reads the data from a c-tree Server whose system’s byte order differs from the client system’s byte ordering, the values of fields that follow the CT_STRING fields may be incorrectly reversed.

In heterogeneous environments, the c-tree client code reverses binary fields in the record buffer when reading data records. A CT_STRING field is considered to end when the first null byte is encountered. If an application pads a CT_STRING field with multiple null bytes, the c-tree client’s scanning logic stops scanning the field at the first null byte and considers the next field to begin with the second null byte. The client logic will then reverse the wrong bytes in the data record buffer.Enables the client logic to scan a c-tree data file’s field definitions when the client code reads the DODA from the data file. When enabled, the client logic will change all CT_STRING fields having a non-zero field length in the fixed length portion of the record buffer to CT_STRING fields.

OPS_DISK_IO - Uses sysiocod to indicate if the previous function call to the Server generated any read and/or write activity for data and/or index files. sysiocod is only set if the previous call did not itself cause a sysiocod return value.

A sysiocod between -1015 and -1000 indicates that the feature is on, and no other sysiocod value occurred. There are sixteen possible return values, defined as:

A return of -1000 means no data or index disk activity, though there still may have been activity in transaction logs and other Server files. A return of -1015 means there were read AND writes on both data and index files.

This statement prints a message as shown:

if (sysiocod <= -ctDISKIObase && (((-sysiocod) - ctDISKIObase)& ctDISKIO_DATW))
    printf(“One or more data file writes to disk\n”);
else
    printf(“No data file write to disk\n”);

OPS_AUTOISAM_TRN - Permits individual ISAM updates to be performed within an automatically initiated transaction. The purpose of this option is to avoid the network overhead of the TRANBEG and TRANEND calls. (If a transaction has already been initiated by the application, then no automatic transaction is attempted.)

Prior to the introduction of this option, the automatic commit would free any lock involved in the transaction unless LKISAM(ENABLE) or LKISAM(ENABLE_BLK) was already in effect and OPS_UNLOCK_ADD or OPS_UNLOCK_RWT were not in effect. If an application desired to hold the lock after the automatic commit, LKISAM(ENABLE) would have to be called first; but this caused the same network overhead as the TRANBEG.

The SETOPS option, OPS_KEEPLOK_TRN, causes the locks involved in automatic transactions for adds and rewrites to be kept after the automatic commit. Delete operations still have the locks freed.

OPS_LOCLON_ADD_BLK When a table lock is in effect, a record add call by a connection that is not holding the table lock fails with error DLOK_ERR and sysiocod of DLKT_COD if that connection has not enabled the ISAM blocking write lock mode. Calling LKISAM(ctENABLE_BLK) before adding the record avoids the error, but it requires an additional call to the server, plus another call after the record add call in order to restore the original lock mode. The c-tree client library and c-tree Server now support a new SETOPS() mode that can be used to enable the blocking write lock mode during the record add call and then restore the original lock mode, all in a single call to the server.

To use this feature, call SETOPS(OPS_LOCKON_ADD_BLK, OPS_STATE_ON) before calling the record add function [ADDREC() or ADDVREC()]. The SETOPS() call sets a bit on the client side and returns to the caller without making a call to the server. This bit is passed to the server on the next record add call. The server and client library turn off this mode when the record add call completes, so it applies only to the first record add call that is made after turning on this option. For this reason, it's recommended to enable this mode right before the call to add the record to which you want this mode to apply.

The record read functions that check and turn off the OPS_LOCKON_GET and OPS_LOCKON_BLK modes ignore this new mode. And the record add functions that check and turn off the OPS_LOCKON_ADD_BLK mode ignore the OPS_LOCKON_GET and OPS_LOCKON_BLK modes.

Return

SetOperationState() returns the present state of the operation status word. On return, uerr_cod is set to one of the following

See c-tree Error Codes for a complete listing of valid c-tree error values.

See also

GetSerialNbr(), AddRecord(), AddVRecord(), DeleteRecord(), DeleteVRecord(), ReWriteRecord(), ReWriteVRecord(), LockISAM(), FirstRecord(), ReadData(), SystemMonitor(), Abort(), Commit(), Begin()

SetRecord

Resets the current ISAM record.

Short Name

SETCURI()

Type

ISAM function

Declaration

COUNT SetRecord(FILNO datno, LONG recbyt, pVOID recptr, VRLEN datlen); 

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

c-tree maintains the record number of the current ISAM record for each data file, as well as an image of the key buffer. There may be times when you want to reset the current ISAM record. For instance, if you want to return to a particular point in the file and index in order to continue a sequential scan of the file. By calling SetRecord(), you can set the current record offset of file datno to the value in recbyt.

recptr points to a record image. If datlen is zero, recptr should point to a complete fixed-length record, or the fixed portion of a variable-length record. Otherwise, datlen indicates the size of the information pointed to by recptr.

If recptr is NULL, only the record position is updated. This is useful when SetRecord() is used to prepare for ReReadRecord(), or ReReadVRecord(), to reread the current ISAM record.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

FILNO     datno, keyno;
LONG      custno, recpos;
TEXT      savbuf[128], buffer[128];

printf("\nEnter customer number: ");
scanf("%ld",&custno);
if (FirstInSet(keyno, &custno, savbuf, 4))
    printf("\nCould not read customer record");
else{
    recpos = CurrentFileOffset(datno);
    process_more_records_in(buffer);
 
    /* restore original record as current ISAM */
    SetRecord(datno,recpos,savbuf,128L);
}

Limitations

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

ReReadRecord(), ReReadVRecord(), ctSETHGH(), ctGETHGH(), CurrentISAMKey(), TransformKey()

SetSavePoint

Establish a savepoint.

Short Name

TRANSAV()

Type

Low-Level data file function

Declaration

  COUNT SetSavePoint() 

Description

SetSavePoint() creates a savepoint in the current transaction. When processing a complex transaction, you will find times when you want to back up just part way in that transaction. You do not want to use Commit(), as that commits, and ends, the entire transaction. You do not want to use Abort(), as that aborts the entire transaction.

To be able to reverse just a portion of a transaction, call SetSavePoint() to set a savepoint. There can be any number of savepoints within a transaction. SetSavePoint() returns a COUNT value that is the numerical representation of that save point. To roll back the transaction to a particular save point, issue a call to RestoreSavePoint(), passing the specific save point value as the parameter.

Return

SetSavePoint() returns the numerical representation of the save point. Use this value in a subsequent RestoreSavePoint() to reset the transaction to this save point. If an error occurs, SetSavePoint() returns zero. Check uerr_cod for the error value.

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

COUNT     savepoint;

void domaster() {
    Begin(ctENABLE|ctTRNLOG);   /* start transaction with locks  */
    while(another()); {         /* get next record to add        */
        savepoint = SetSavePoint();
                        /* get save point at beginning of each master record */
        if (add_master() < 0)
            Abort();            /* Abort if can't add master rec */
        dodetail();             /* process detail records        */
    }
    if (Commit(ctFREE)0)
        printf("\nError %d in transaction",uerr_cod);
    return;
}

void dodetail() {
    while(moredetail()); {                /*get next detail record to add */
        if (add_detail()<0) {             /* add details, if possible */
            RestoreSavePoint(savepoint)   /* with error, return to savept */
            return;
        }
    }
}

See also

Abort(), AbortXtd(), Begin(), ClearSavePoint(), Commit(), RestoreSavePoint(), TRANRDY()

SetSystemConfigurationOption

SetSystemConfigurationOption() dynamically changes server configuration settings at runtime.

Declaration

NINT SetSystemConfigurationOption(NINT option, const TEXT * value);

Short Name

ctSETCFG()

Description

SetSystemConfigurationOption() allows a FairCom Server configuration to be changed at run time. This means you do not have to restart the server to operate with these specified configuration changes. This allows utilities and other diagnostic monitoring tools to directly call the server to activate or inactivate various server configuration options.

setcfgCONFIG_OPTION

setcfgCONFIG_OPTION is a general-purpose option used to set values for settings by passing a string value identical to a line in the server configuration file. Note that this option also supports the other existing options, making it possible to call ctSETCFG(setcfgCONFIG_OPTION, "CHECKPOINT_MONITOR YES").

Dynamic Adjustment Support

The following keywords support dynamic adjustment using setcfgCONFIG_OPTION. See the FairCom DB Configuration Options for keyword specific documentation.

• FUNCTION_MONITOR
• CHECKPOINT_MONITOR
• MEMORY_MONITOR
• REQUEST_TIME_MONITOR
• DYNAMIC_DUMP_DEFER
• DYNAMIC_DUMP_DEFER_INTERVAL
• VSS_WRITER
• VSS_WRITER_QUIESCE_TIMEOUT
• SQL_TRACE_CTREE_ERROR
• MAX_FILE_WAIT_SECS
• MAX_DFRIDX_LOGS
• MAX_REPL_LOGS
• DELSTK_COMMIT_SEC
• CHECKLOCK_FILE
• AUTOTRAN_ON_CREATE
• UNCSEG_KEYCOMPRESS
• FILESYS_COMPRESS_UNCSEG
• SHMEM_MAX_SPINNERS
• SYNC_COMMIT_MAX_SPINNERS
• READONLY_SERVER
• LOCAL_CONNECTION_ONLY
• REPL_NODEID
• LEAF_NODE_READ_LOCK
• OPEN_FILES_ALERT_THRESHOLD
• DYNAMIC_DUMP_SYNC_INTERVAL
• NONTRAN_FILESYS_FLUSH_OFF
• SQL_SERVER_LOG_SIZE
• FILE_CLOSE_FLUSH
• PENDING_FILE_OPEN_RETRY_LIMIT
• OPTIMIZE_FILE_OPEN
• SYSTEM_FILE_ID_LIST
• CLEANUP_ABLIST_ON_ABORT
• STACK_DUMP
• CHECK_FILENAME_VALIDITY
• SYNC_COMMIT_TIMEOUT
• REPL_USE_LAST_LOGPOS
• ABANDONED_QUIET_SUSPEND_LOGON
• MULTILINE_STATUS_LOG_MESSAGE
• REPLICATE_ALTER_TABLE
• BLOCKING_OPEN_RETRY_LIMIT
• BLOCKING_OPEN_RETRY_DEFER
• SYSCLOSE_REOPEN_CHECK_DIFF
• SET_CACHE_OPTIONS
• SHMEM_CONNECT_TIMEOUT
• FLEXREC_OPTIMIZE
• QUIET_MAX_WAIT
• SORT_MEMORY
• MAX_HANDLES
• MAX_REBUILD_QUEUE

Partial Dynamic Adjustment Support

The following keywords have some sub-options that may be changed, see below for additional details.

• DIAGNOSTICS
• COMPATIBILITY
• SUBSYSTEM

Disabling Binary Sub-Options

Use a tilda (~) character as a prefix to negate the sub-option to turn it off. This applies to the following keywords

• SQL_DEBUG
• DIAGNOSTICS
• CTSTATUS_MASK
• COMPATIBILITY

DIAGNOSTICS Sub-Options

Not all sub-options are changeable at runtime. Prefix the sub-option with a tilde (~) to turn it off.

The following suboptions are supported.

• LOWL_FILE_IO
• VSS_WRITER
• PTADMIN
• REPLICATE
• FULL_DUMP
• BACKGROUND_FLUSH
• BACKGROUND_FLUSH_BUCKETS
• MAX_ACTIVE_CONNECTIONS
• DFRIDX
• READ_ERR
• UNOD_ERR
• CMTLOK
• TR_RDIF_ERR
• TR_TRAN_ERR
• CHECKLOCK
• LOG_PURGE
• LDAP
• CHECK_KEY_MARKS
• FALG_ERR
• DMAP_ERR
• POPN_ERR
• RRED_ERR
• RESIZE_CACHE
• INIX_ERR
• SYSTEM_FILE_ID_LIST
• RECYCLE_BIN
• SYNCREPL
• FILE_BLOCK

COMPATIBILITY Sub-Options

Not all sub-options are changeable at runtime. Prefix the sub-option with a tilda (~) to turn it off.

The following sub-options are supported.

• SQLIMPORT_ADMIN_PASSWORD
• COPY_FILE_OPEN_SHARED

SUBSYSTEM details and supported Sub-Options

Keywords belonging to a SUBSYSTEM may support changes at runtime. To do so requires specific formatting like that required in the server configuration file. Multiple sub-options may be changed at once.

The following are SUBSYSTEM values with at least one supported sub-option.

• SUBSYSTEM SQL LATTE
• SUBSYSTEM TRNLOG AUTO_RESTORE_POINT
• SUBSYSTEM EVENT DISK_FULL_ACTION
• SUBSYSTEM SECURITY PASSWORD
• SUBSYSTEM EXTERNAL_KEY_STORE AWS
• SUBSYSTEM AUDIT LOG
• SUBSYSTEM CTFILE RECYCLE_BIN
• SUBSYSTEM CACHE PRIME_CACHE_AT_STARTUP

Specifying any other option value than those shown above causes ctSETCFG() to return error PBAD_ERR (749).

Options besides setcfgCONFIG_OPTION

Option may be one of the following FairCom Server configuration supported values (the new setting value specified as a string).

Details

An attempt to change an option that is specified in a FairCom Server encrypted settings file (ctsrvr.set) will fail with a "SETO_ERR (804) error, cannot override option specified in settings file." ctSETCFG() can only be called by a member of the ADMIN group; otherwise it will fail with error LADM_ERR (589).

The function monitor file output now also includes a time stamp.

Return Values

See c-tree Error Codes for a complete listing of valid c-tree error values.

Examples

/* Enable function monitor logging to a file. */
ctSETCFG(setcfgFUNCTION_MONITOR, "fncmon.log");

/* Dynamically set the Dynamic Dump defer time */
ctSETCFG(setcfgDYNAMIC_DUMP_DEFER, "25");

/* Dynamically turn on masking of Dynamic Dump messages */
ctSETCFG(setcfgCONFIG_OPTION, "CTSTATUS_MASK DYNAMIC_DUMP_FILES");

/* Dynamically disable masking of Dynamic Dump messages */
ctSETCFG(setcfgCONFIG_OPTION "CTSTATUS_MASK ~DYNAMIC_DUMP_FILES");

/* Dynamically set stack generation option to FULL_DUMP */
ctSETCFG(setcfgCONFIG_OPTION "STACK_DUMP FULL_DUMP");

/* Change the SUBSYSTEM SQL LATTE MAX_STORE option to 11 GB  */
ctSETCFG(setcfgCONFIG_OPTION,
"SUBSYSTEM SQL LATTE {\nMAX_STORE 11 GB\n}");

/* Change multiple SUBSYSTEM SECURITY PASSWORD options  */
const char * newconfig = "SUBSYSTEM SECURITY PASSWORD {\n" \
                      "MINIMUM_LENGTH 16\n" \
                      "REQUIRED_CLASSES 2\n" \
                      "EXPIRE_IN_DAYS 365\n}";
   
ctSETCFG(setcfgCONFIG_OPTION,newconfig);

History

V11.6 and later adds SQL_DEBUG configurable options.

SetVariableBytes

Change the values used for key padding and as a field delimiter in key construction.

Short Name

SETVARBYTS()

Type

Low-Level file resource function

Declaration

LONG SetVariableBytes(FILNO filno, pUTEXT resptr) 

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

When called for a data file, SetVariableBytes() changes the value used to pad varying length key segments as well as the byte value used to delimit varying length string fields that are not length count delimited. When called for an index file, SetVariableBytes() changes the padding byte used during trailing padding key compression. The default values are blanks for padding and NULL for the field delimiter.

filno must be opened with an ctEXCLUSIVE file mode for it to be successful. resptr points to a 2-byte array containing the values for padding (first byte) and the field delimiter (second byte). This information will be stored in the file as a resource, therefore resources must be enabled for the file.

For a related set of data and index files, SetVariableBytes() should be called for the data and index files immediately after successful creation.

Note: When using ISAM functions, be sure to specify appropriate value in the pvbyte element of the IIDX structure in addition to calling this function.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

FILNO     filnum;
UTEXT     thebytes[2];

if (OpenDataFile(filnum,"test.dat", ctEXCLUSIVE | ctPERMANENT))
    printf("\nCannot open file (%d)",uerr_cod);
else {
    thebytes[0] = 00;  /*set padding byte */
    thebytes[1] = 32;  /*set delimiter byte */
    if (SetVariableBytes(filnum,thebytes)
        printf("\nByte error %d",uerr_cod);
}

SetXtdFileOpenMode

Pass additional file open modes to FairCom Server.

Declaration

NINT SetXtdFileOpenMode (LONG mode)

Description

Additional file open modes can be passed to FairCom DB using this function. SetXtdFileOpenMode() sets a file open mode that is used by the OPNIFIL, OPNIFILX, OPNRFIL, and OPNRFILX functions.

Note: c-tree passes the extended file open mode value to the c-tree Server on the next call to OPNIFIL, OPNIFILX, OPNRFIL, or OPNRFILX that is made after calling SetXtdFileOpenMode(). These ISAM-level file open functions always reset the extended file mode, even in case of error, so that the extended file mode only applies to the first ISAM-level file open call that is made after the call to SetXtdFileOpenMode().

Extended file open modes set by SetXtdFileOpenMode()

Example

The following example shows a call to SetXtdFileOpenMode(ctXOPN_RETRYOPNFCNF) followed by opening a file:

FILNO filno = 0;
TEXT  filnam[15] = "sample.dat";

SetXtdFileOpenMode(ctXOPN_RETRYOPNFCNF);
if (OpenFileWithResource(filno, filnam, ctSHARED) < 0)
   printf("\nCould not open file (%d,%d).", isam_err, sysiocod);

Opening a data file if its record update callback resource DLL cannot be loaded

A c-tree data file that requires a record-update callback DLL would fail to open with error code 981 if the callback DLL could not be loaded. In some cases, it might be desirable to allow the data file to be opened in this situation. This is now permitted.

An extended file open mode has been added. It can be used to permit the data file to be opened for read-only access if its record-update callback DLL cannot be loaded. The new extended file mode is ctXOPN_NORUCB_OK. To use this mode when opening the file, call SetXtdFileOpenMode(ctXOPN_NORUCB_OK) before opening the file.

Note that the extended file mode set by SetXtdFileOpenMode() overwrites any previous extended file mode that was set for the connection. Upon return from the file open call, the extended file mode is reset to zero. This implies the normal usage of this function is to call it right before opening the file.

Note: Although the file open succeeds in this situation, the file open function sets sysiocod to RUCBDLL_NOT_LOADED_COD, and a message such as the following one is logged to CTSTATUS.FCS indicating the failed DLL load:

CTDLL_LOAD: Failed to load module ctuser.dll: The specified module could not be found.

SnapShot

Declaration

NINT SnapShot(NINT opcode, pTEXT rqstdesc, pVOID snapbufr, VRLEN buflen);

Parameters:

• opcode specifies the action to be taken by the snapshot function.
• rqstdesc points to an ASCII string containing the input information.
• snapbufr points to an output buffer of length buflen.

Different opcodes require different combinations of input and output parameters ranging from using neither of them to both of them.

Description

FairCom DB tracks and reports a wealth of performance-oriented statistics. FairCom DB's Snapshot capability enables the capture of performance monitoring data using a combination of configuration file options and the SnapShot API function. The performance data can be captured automatically at specified intervals or on demand in the following ways:

• The ctstat utility provides a command-line interface to the SNAPSHOT API function, supporting output of FairCom DB statistics at the core database engine, user, file, and function levels.
• Configuration file options support automatic performance snapshots by specifying the interval between automatic snapshots and the contents of the snapshots. The performance data captured by automatic snapshots are written to the FairCom DB system event log (SYSLOG) files.
• Use DIAGNOSTICS options to capture the automatic system snapshot data to the human-readable SNAPSHOT.FCS file.
• The SnapShot() API function can control automatic snapshots, overriding configuration options (if any), and can capture on-demand performance data:
  • to either the SYSLOG files or to the human-readable SNAPSHOT.FCS file, or
  • as a return to the calling program.

For tips about monitoring system performance using this function, see Performance Monitoring Using the SnapShot API.

Snapshot Contents

Each snapshot is composed of a structure (ctGSMS for system info, ctGUMS for user info, and ctGFMS for file info) followed optionally by a variable region. Each of the three snapshot structures contains information about the size of the structure and the amount of variable information, if any, following the structure. Further, if the output buffer is too small to hold all the variable information, the contents member of the main structure will have the ctSNAPSHOTtruncated bit turned on if information had to be truncated.

Note: These structure definitions may vary depending on the version of the FairCom DB and FairCom DB client versions you are using. Please consult the c-tree headers for the actual structure definition that is in use. Differences in definitions between a given ctstat client and FairCom DB may make ctstat incompatible with that server, in which case the ctstat utility displays an error message indicating structure incompatibility.

The only variable information consists of an array of function timing results for the overall system or for a user. The array is composed of ctWRKSTT structures. Function timings are described below, but these timings are only for direct calls from c-tree clients.

^ High-Resolution Timers - Most of the elapsed times accumulated in the snapshots are based on high-resolution timers that report in numbers of ticks and are stored in eight-byte integers. The description following each structure member contains a ‘^’ to indicate results based on high-resolution timers. To convert such times to seconds, divide by the ticks per second, a system dependent value stored in the scthrbastim member of each snapshot structure.

Snapshot Structures

System Snapshot Structure

File Snapshot Structure

User Snapshot Structure

SQL Snapshot Structure

Replication Snapshot Structure

Transaction Snapshot Structure

File List Snapshot Structure

CHECKLOCK List Snapshot Structure

Memory Snapshot

#define ctGMMSvern 1 /* ctGMMS (memory snapshot) version # */
#define TOTMEMLIST (24 /* NUMCTLIST */ + 1)

typedef struct ctgmms {
ULONG client_ver; /* client version of structure */
ULONG server_ver; /* server version of structure */
LONG8 snapshottm; /* snapshot time stamp: seconds since 70 */

TEXT memdsc[TOTMEMLIST][8]; /* Suballocator list description */
LONG8 memalc[TOTMEMLIST]; /* Allocated suballocator memory */
LONG8 memuse[TOTMEMLIST]; /* Used suballocator memory */

} ctGMMS, ctMEM * pctGMMS;

Snapshot Actions and Options

System Snapshot Support

The SnapShot API function supports logging FairCom DB system statistics. For a listing of the system statistics FairCom DB collects, refer to the ctGSMS structure in the Snapshot Contents section below. The supported operations include:

File Snapshot Support

The SnapShot API function supports logging FairCom DB file statistics. For a listing of the file statistics the FairCom DB collects, refer to the ctGFMS structure in the Snapshot Contents section. The supported operations include:

User Snapshot Support

The SnapShot API function supports logging FairCom DB user statistics. For a listing of the user statistics FairCom DB collects, refer to the ctGUMS structure in the Snapshot Contents section below. The supported operations include:

Automatic Snapshot Support

The SnapShot API function supports starting, stopping, and resuming automatic snapshots. The following table shows the parameters to pass to SnapShot to perform these operations.

Combined Snapshot Support

The SnapShot API function supports logging combined snapshots containing FairCom Server system statistics and user and file statistics for the specified activated users and files. This ability is supported by the following operation:

Function Timing Snapshot Support

The SnapShot API function supports profiling of FairCom DB API function calls (function timing) and timing of user-defined operations. The supported operations include:

• Starting and stopping the collection of FairCom DB API function timing statistics.
• Resetting the function timing statistics.
• Accumulating timings in user-defined timing baskets. Users may define up to 8 different timing baskets. A begin mark call establishes a high resolution starting time for the specified basket. An end mark call causes the specified basket counter to be incremented, and the elapsed time is added to the timing basket. The baskets are numbered from 0 to 7.

Note: Function timings require a significant number of calls to the high-resolution timer, and are more consistent with diagnostic or testing modes of operation.

The following table shows the parameters to pass to SnapShot() to perform these operations.

SQL Snapshot Support

The SnapShot API function has a mode for retrieving FairCom DB SQL specific statistics.

File List Snapshot Support

CHECKLOCK List Snapshot Support

Memory Snapshot Support

Replication Snapshot Support

The SnapShot API function supports logging information about the FairCom Server replication state. For a listing of the transaction statistics the FairCom Server collects, refer to the ctPSSreplread structure in the Snapshot Contents section below. The supported operations include:

Transaction Snapshot Support

The SnapShot API function supports logging FairCom Server transaction statistics. For a listing of the transaction statistics the FairCom Server collects, refer to the ctPSStransaction structure in the Snapshot Contents section. The supported operations include:

Snapshot support for FairCom Server compiled without transaction control

In V11 and later, support has been added for using the SnapShot feature when FairCom DB Server is compiled without transaction control (UNIFRMAT server, for example). (ctSNAPSHOT API and utilities such as ctstat and FairCom DB Monitor use this feature.)

Prior to this modification, FairCom DB Monitor had limited functionality on a server that did not support transaction processing: the Files Stats, System Snapshot, User Snapshot, Snapshot Favorites, and Function Timing tabs could not be used (typical error = 454, not supported).

Note: Although the snapshot API is now supported by a server, some functions (such as replication and transaction information) are not supported.

Return Values

SnapShot returns NO_ERROR (0) on success, or an error code on failure.

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

   ...

   ctGSMS* my_sysSnap;
   NINT rc = 0;

   my_sysSnap = (ctGSMS*) malloc(sizeof(ctGSMS));
   memset(my_sysSnap, 0, sizeof(ctGSMS));

   rc = InitISAMXtd(10, 10, 8192/128, 10, 0, "ADMIN", "ADMIN", "FAIRCOMS");
   if (rc) {
      printf("InitISAMXtd Error: %d\n", rc);
      return (rc);
   }
 
   /* Take a System SnapShot */
   rc = SnapShot(ctPSSsystem, NULL, my_sysSnap, sizeof(ctGSMS));
   if (rc) {
      printf("SnapShot Error: %d\n", rc);
      return (rc);
   }

   rc = CloseISAM();
   if (rc)
      printf("CloseISAM Error: %d\n", rc);

   /* Print Memory statistics */
   printf("High Mem: %d\n", my_sysSnap->sctmemhgh);
   printf("Current Mem: %d\n", my_sysSnap->sctmemsum);
    

   /* Print Disk I/O statistics */
   printf("Read ops: %d\n", my_sysSnap->sct_rdops);
   printf("Read bytes: %d\n", my_sysSnap->sct_rdbyt);
   printf("Write ops: %d\n", my_sysSnap->sct_wrops);
   printf("Write bytes: %d\n", my_sysSnap->sct_wrbyt);

   /* Print Platform Specific Server information */
   printf("Server flavor: %d\n", my_sysSnap->sflvr);
   printf("Alignment: %d\n", my_sysSnap->salgn);
   printf("Pointer size: %d\n", my_sysSnap->spntr);

   free(my_sysSnap);

   ...

See also

• Performance Monitoring Using the SnapShot API

StopServer

Stop operation of the FairCom Server.

Short Name

STPSRV()

Type

Server-only function

Declaration

COUNT StopServer(pTEXT usrword, pTEXT servname, COUNT delay)

Description

StopServer() stops operation of the FairCom Server from inside an application. usrword must point to the password of the system administrator, ADMIN. servname can point to an optional FairCom Server name, or may be NULL when using the default FairCom Server name.

The application should NOT be connected to the FairCom Server when StopServer() is called. Call RegisterCtree() before and UnRegisterCtree() after the call to StopServer().

A non-zero delay specifies the number of seconds the FairCom Server should delay before beginning the shut down process. The delay allows transactions in process to complete. When a non-zero delay is specified, the FairCom Server does not accept any new users or new transactions while waiting to shut down. Logons and transactions fail with SHUT_ERR (150). After the delay expires, the FairCom Server immediately shuts down. Any users currently logged in are logged off and any incomplete transactions are aborted.

Note: If the Replication Agent is running on a server, replication should be stopped before trying to stop the server. If replication is running when you attempt to stop the server, you will see error 792 (External server shutdown disabled).

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

TEXT      usrword[10];
TEXT      servname[256];
COUNT     delay=10;

RegisterCtree(MYREGID);
printf("\nEnter the password: ");
scanf("%10s",usrword);
printf("\nEnter the server name:");
scanf("%255s",servname);

if (StopServer(usrword,servname,delay)
    printf("\nError on StopServer() error = %d",uerr_cod);

UnRegisterCtree(MYREGID);

See also

RegisterCtree(), UnRegisterCtree()

StopServerXtd

Stop operation of the FairCom Server, Extended Version

Short Name

STPSRVX()

Type

Server-only function

Declaration

COUNT StopServerXtd(pTEXT admnuser, pTEXT usrword,
                      pTEXT servname, COUNT delay)

Description

StopServerXtd() stops operation of the FairCom Server from inside an application. usrword must point to the password of the system administrator, admnuser. servname can point to an optional FairCom Server name, or may be NULL when using the default FairCom Server name.

The application should NOT be connected to the FairCom Server when StopServer() is called. Call RegisterCtree() before and UnRegisterCtree() after the call to StopServer().

A non-zero delay specifies the number of seconds the FairCom Server should delay before beginning the shut down process. The delay allows transactions in process to complete. When a non-zero delay is specified, the FairCom Server does not accept any new users or new transactions while waiting to shut down. Logons and transactions fail with SHUT_ERR (150). After the delay expires, the FairCom Server immediately shuts down. Any users currently logged in are logged off and any incomplete transactions are aborted.

Note: If the Replication Agent is running on a server, replication should be stopped before trying to stop the server. If replication is running when you attempt to stop the server, you will see error 792 (External server shutdown disabled).

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

TEXT      admnuser[10],usrword[10],servname[256];
COUNT     delay=10;

RegisterCtree(MYREGID);
printf("\nEnter the Admin ID: ");
scanf("%10s",admnuser);
printf("\nEnter the password: ");
scanf("%10s",usrword);
printf("\nEnter the server name:");
scanf("%255s",servname);

if (StopServerXtd(admnuser,usrword,servname,delay)
    printf("\nError on StopServerXtd() error = %d",uerr_cod);

UnRegisterCtree(MYREGID);

See also

RegisterCtree(), UnRegisterCtree()

StopUser

Log application off the FairCom Server.

Short Name

STPUSR()

Type

Server-only function

Declaration

COUNT StopUser() 

Description

StopUser() logs an application off a FairCom Server. It causes all the files not yet closed by the application to be closed and frees a slot on the Server for another user. StopUser() is automatically invoked by CloseISAM(). Therefore, StopUser() is only required in Low-Level applications, or in ISAM applications when a program can exit without calling CloseISAM().

Note: A c-tree application is automatically logged on to a FairCom Server whenever InitCTree(), InitISAM(), OpenISAM(), or CreateISAM() is called. There is no separate call for logging-on to the FairCom Server.

Return

StopUser() returns an error if it could not communicate with the FairCom Server. This might happen if the FairCom Server has been shut down or if the communications link has been disturbed.

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

pTEXT     pfname;

if (OpenISAM(pfname)) {
    printf("\nCould not OpenISAM. Error %d. File %d.", isam_err,isam_fil);
    StopUser();
    exit(2);
}

See also

CloseISAM(), InitCTree(), InitISAM(), OpenISAM(), CreateISAM()

StopUserAsync

Short Name

STPUSRA()

Type

Server-only function

Declaration

COUNT StopUserAsync(COUNT mode)

Description

StopUserAsync() is the same as StopUser() except that it returns immediately when called by a client without waiting for the server to complete the STPUSR() processing.

StopUserAsync() accepts a mode parameter to convey special user shutdown options. The only mode implemented affects flush operations: if a file is on the NO_SHUTDOWN_FLUSH list (see the NO_SHUTDOWN_FLUSH FairCom Server configuration keyword), and if StopUserAsync() is called with ctNOFLUSH OR-ed into mode, the file buffers will not be flushed if the StopUserAsync() causes the file closure, and the file will be marked corrupt.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

COUNT     retval=0, buf = dbuf = 10, fil = sect = 32;
pTEXT     uid = "ADMIN", pass = "ADMIN", srv = "FAIRCOMS";

if (retval = InitISAMXtd(buf, fil, sect, dbuf, NULL, uid, pass, srv))
{
    printf("\nCould not initialize c-tree: %hd", retval);
    StopUserAsync(ctNOFLUSH);
    exit(2);
}

See also

StopUser()

SuperfilePrepassXtd

Preprocess superfiles to allow rebuilds.

Short Name

CTSBLDX()

Type

Low-Level function

Declaration

COUNT SuperfilePrepassXtd(pTEXT filnam, pTEXT fileword)

Description

SuperfilePrepassXtd() processes the superfile in place. Because a superfile holds numerous c-tree files in one physical file, there are complex inter-file relationships that SuperfilePrepassXtd() function cleans up.

SuperfilePrepassXtd() empties the index files. Each file in the superfile must now be processed by RebuildIFile() before it is usable.

As is the case with RebuildIFile(), the superfile must be closed prior to calling SuperfilePrepassXtd(). Both SuperfilePrepassXtd() and RebuildIFile() open and close the superfile and members.

In single user environments, the fileword parameter, file password, is ignored; i.e., you should pass both parameters, but the second one is ignored.

This operation is available as both a function and stand-alone utility. The function call can be used in single-user and client/server applications. The stand-alone implementation, ctsbld, is available only as a single-user utility.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

TEXT     filnam[64];

printf("\nEnter superfile host name: ");
scanf("%63s",filnam);
if (SuperfilePrepassXtd(filnam, NULL))
    printf("\nError on superfile pre-pass, error = %d on file
           %d", isam_err, isam_fil);

See also

Functions RebuildIFile(), RebuildIFileXtd(), and the ctsbld utility.

SwitchCtree

Switch to a specific c-tree instance.

Short Name

SWTCTREE()

Type

Low-Level function

Declaration

COUNT SwitchCtree(pTEXT regid)  

Description

SwitchCtree() makes the instance identified by the supplied registration reference name regid active.

Note: regid is case sensitive and must be exactly the same value previously passed to RegisterCtree.

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

TEXT     inpbuf[128] = "myInstance"; /* input buffer */

if (SwitchCtree(inpbuf)) {
    ctrt_printf("\nCould not SWITCH to {%s} instance.",inpbuf);
    ctrt_exit(2);
}

See also

NextCtree(), RegisterCtree(), WhichCtree(), GetCtreePointer(), UnRegisterCtree()

SystemConfiguration

Describes the configuration of the c-tree system.

Short Name

SYSCFG()

Type

Low-level function

Declaration

COUNT SystemConfiguration(pVOID bufptr)  

Description

SystemConfiguration returns an array of LONGs describing the c-tree system configuration, as well as some of the important dynamic aspects of the system, such as the memory usage and the number of files in use. The number of elements in the array is given by ctCFGLMT, which defaults to 256.

To determine if a particular system configuration option is active, check to see if its corresponding array element is non-zero. For example, to determine if TRANPROC was turned on during system compilation, check element cfgTRANPROC of the configuration array to determine if it is non-zero.

Dynamic System Resources

The following configuration array subscripts correspond to dynamic system resources and are interpreted as noted:

Server Implementations

The following array subscripts only apply to server implementations:

Static Compile-Time Values

The following array subscripts are static compile-time values:

Client and Server Versions ("app" suffix)

The subscripts displayed in this section and the pre-initialization resources section below have client and FairCom Server versions, except for the following three subscripts:

Subscripts ending with ‘app’ are specific to the client side of a client/server application. To check the same system setting for the FairCom Server, use the same subscript without the app extension. For example, to determine if Conditional Index support is active on the FairCom Server, use cfgCONDIDX as the subscript and cfgCONDIDXapp for the client side. On the client side, it is assumed the argument to SystemConfiguration is an array of properly aligned LONGs.

If SystemConfiguration is called for a non-client library, use the ‘app’ versions, i.e., cfgCONDIDXapp.

The pre-initialization resource subscripts below may be specified prior to a c-tree initialization call, i.e., InitISAM, InitCTree, in addition to having both a client and FairCom Server version, as discussed above.

Pascal Length Byte

c-tree supports two different methods for specifying the length byte in a Pascal data type. The original and non-traditional approach does not include the length byte in the byte count. For example, with a 1-byte data type, CT_FPSTRING, the smallest valid length byte would be 0. The new method follows the more traditional Pascal convention of including the length byte in the byte count. For example, with the traditional approach, the smallest valid length for a 1-byte data type would be 1. Therefore, if cfgPASCALstapp or cfgPASCAL24app return a non-zero value, the new traditional approach is active.

To receive a valid return value from cfgPATH_SEPARATOR, ctPATH_SEP must be defined. The default definition found in ctopt2.h is:

#define ctPATH_SEP   '?'

This definition specifies that the system default path separator will be used. To use the same separator for all platforms, you might want to choose one of the following:

#define ctPATH_SEP   '\\'
/* define for Windows */
#define ctPATH_SEP   '/' 
/* define for most Unix systems */
#define ctPATH_SEP   ':' 
/* define for Mac OSX */

Configuration Bitmaps

The following configuration bitmaps are used with the cfgCFGCHK element of the SystemConfiguration output array. When the bit is on, the corresponding configuration is in effect. The current configuration bit mask definition is:

cfgCFGCHK

The SYSCFG() function's cfgCFGCHK element is a 32-bit value that contains bits to indicate if particular features are enabled or disabled at runtime.

In V11.5 and later, a bit has been added to indicate if the advanced encryption feature is enabled:

#define cfgCFGCHKadvenc ((LONG)0x00000008) /* advanced encryption enabled */

The cfgCFGCHK element also indicates if REPL_MAPPINGS is in effect for FairCom Server.

Feature Bitmaps

The following feature bitmaps are used with the cfgFEACHK element of the SystemConfiguration output array. When the bit is on, the corresponding feature is available. This is useful for client applications where the availability of a feature is not known at compile/link time. The current feature bit mask definitions are:

cfgFEACHK

cfgFEACHK2

Note: An initial c-tree call (InitCTree, InitCtreeXtd, InitISAM, etc.) must be made before SystemConfiguration can check on the cfgFEACHK element. The cfgINIT_CTREEapp element can be evaluated to determine the status of the c-tree initialization.

For example:

  LONG       ca[ctCFGLMT];

SystemConfiguration(ca);

if (ca[cfgINIT_CTREEapp] == YES)
    printf("c-tree Initialized");
else
    printf("c-tree Uninitialized: %ld",
           ca(cfgINIT_CTREEapp));

/* where the Uninitialized value is NINT_ERR for a client or FINT_ERR for a bound application */

System-wide Cache and Buffer Statistics

SystemConfiguration returns nine values referenced with the following constants used as subscripts in the output array of LONG values an application can use to capture system-wide cache and buffer statistics, (cache pages hold data record images and buffers hold index nodes), allowing an application to track the use of these resources.

Note: The dedicated cache pages are a subset of the regular cache pages.

Please see the following example for the use of this feature.

  LONG      ctcfg[ctCFGLMT];
SystemConfiguration(ctcfg);
printf("\nAvailable Dedicated Cache Pages - %ld",
       ctcfg[cfgCACHE_PAGES_DED]);

Version Information

These values allow a client to display the same server version and build date that the FairCom Server displays.

The ctdbGetProductVersion() function is a good way to get these values in a form that is more readable than these binary values.

Additional Array Elements

The following array subscripts are also returned:

Return

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

LONG      ctcfg[ctCFGLMT];       /* array of 256 longs */

SystemConfiguration(ctcfg);

printf("\nMemory Use is %ld\n", ctcfg[cfgMEMORY_USAGE]);
printf("Memory Highest is %ld\n", ctcfg[cfgMEMORY_HIGH]);
printf("Net allocation is %ld\n", ctcfg[cfgNET_ALLOCS]);
printf("Open Files level is %ld\n", ctcfg[cfgOPEN_FILES]);
printf("Physical Files is %ld\n", ctcfg[cfgPHYSICAL_FILES]);
printf("Open FCB's is %ld\n", ctcfg[cfgOPEN_FCBS]);
printf("ctLOGIDX support is %ld\n", ctcfg[cfgLOGIDX]);

See also

Functions InitISAM(), InitCTree(), InitCtreeXtd(), and ctport.h utility.

SystemLog

Manipulate a log of system events in a c-tree format file.

Short Name

SYSLOG()

Type

Low-Level function

Declaration

COUNT SystemLog(COUNT evclass, LONG event, pTEXT buffer, VRLEN buflen) 

Description

Use SystemLog() to add your own entries to the log. evclass must be ctSYSLOGapi or higher. buflen should not exceed SYSLOGvar, 8100 bytes. The contents pointed to by buffer do NOT need to be actual text. No assumptions are made about the contents of buffer.

Each entry in the system log, SYSLOGDT.FCS, is a variable-length record using the SYSLOGrec structure defined in ctport.h. Typically, the SYSLOGrec structure overlays a buffer capable of holding an entire record. A buffer of SYSLOGmax bytes will hold any entry in the system log. A DODA with the record layout below is added to SYSLOGDT.FCS when it is created:

typedef struct ctslog {
 LONG   evclass;           /* overall type of entry                    */
 LONG   event;             /* the particular event code                */
 LONG   date;              /* date measured in days: r-tree compatible */
 LONG   time;              /* seconds past midnight                    */
 LONG   rsvrd;             /* for future use                           */
 LONG   seqnm;             /* sequence number                          */
 LONG   error;             /* uerr_cod at time of entry                */
 TEXT   userid[SYSLOGidz]; /* logon user ID                            */
 TEXT   nodnam[SYSLOGidz]; /* logon node name                          */
 UCOUNT vlen;              /* length of variable region                */
 TEXT   vfld[2];           /* beginning of variable region             */
} SYSLOGrec, ctMEM * pSYSLOGrec;

The FairCom-defined evclass codes are:

It is anticipated that additional evclass codes will be defined, with appropriate event codes, as additional types of FairCom Server operations are added to the system log facility.

The user logon info event codes are:

On the ADDUSER, CHGUSER, and DELUSER entries, the variable buffer portion of the entry contains the user ID and a brief description of the type of activity. The actual details of the user profile information are not in the log.

The dynamic dump event codes are:

The TRAN, CLEAN, and DIRTY log entries contain the name of the file dumped in the variable buffer portion of the log record.

There are no event codes for CTSTATUS entries. They are all event zero.

The file delete event codes are:

The abort node list event codes are:

The snapshot event codes are:

The restore point info event codes are:

The SQL info event codes are:

The developer of the calling application assigns the user-defined event codes.

The maximum length for the variable-length portion of the log entry is given by the constant SYSLOGvar, which defaults to 8100. The fixed length user ID and node name fields are SYSLOGidz bytes, which defaults to 32.

Purging entries from the log uses a special form of the SystemLog() call: evclass is set as ctSYSLOGpurge, and event is set to zero to purge all classes, or to a particular evclass code to only purge entries from that class. The number of days of entries to keep is specified by placing the number of days to keep in an integer and passing the address of the integer in buffer and the length of the integer in buflen.

Return

SystemLog() returns an error code, NO_ERROR (0) on success.

Note: The actual writing of the log is performed by a dedicated FairCom Server thread which reads a queue fed by SystemLog() calls and internal server calls. The successful return of the SystemLog() call does not guarantee that the entry has been made in the log.

See c-tree Error Codes for a complete listing of valid c-tree error values.

This example shows how to keep the last seven days of user logon information, as well as all other entries regardless of date.

Example

NINT      days_to_keep = 7, retval;

retval = SystemLog(ctSYSLOGpurge,(LONG) ctSYSLOGuser,
                   (pTEXT) &days_to_keep,
                   (VRLEN) sizeof(NINT));

Limitations

Server configuration entries control which users, if any, can call SystemLog(). Review the FairCom Server Administrator’s Guide for complete details on server configuration and operation.

SystemMonitor

Monitor certain critical FairCom Server events.

Short Name

SYSMON()

Type

Server-only function

Declaration

COUNT SystemMonitor(COUNT mode, LONG timeout, pTEXT buffer, VRLEN buflen) 

Description

SystemMonitor() provides the ability for a client to monitor certain critical FairCom Server events. Each event causes a message to be written to an internal queue. Each call to SystemMonitor() reads a message from this queue. If no message is available, it waits for a message or times out.

mode can take on two values:

• SYSMON_MAIN monitors the beginning and end of dynamic dumps and the occurrence of file mirroring events.
• SYSMON_OFF turns off the monitoring.

timeout specifies the time in seconds for a forced return of SystemMonitor() in the event that no event occurs. A value of -1L indicates an unlimited wait: SystemMonitor returns only when an event occurs or the Server stops. Note that the monitor is still in effect after a timeout return. For another process to start monitoring, the client currently monitoring must disconnect from the Server or call SystemMonitor() with the SYSMON_OFF mode.

buffer points to the buffer which receives a descriptive Server monitor message.

buflen is the length of the buffer.

Return

SystemMonitor() returns one of the following values. More events may be added in future releases.

When coding the “switch” or other constructs to handle the SystemMonitor() return codes, be sure to provide a default to handle return codes which may be added in future implementations. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

VRLEN     buflen=128;
TEXT      buffer[128];   /* input buffer */
LONG      timeout = 10;

while(SystemMonitor(SYSMON_MAIN,timeout,buffer,buflen)) {
    switch(uerr_cod){
        case NSUP_ERR:
            printf("No monitor support\n");
            StopUser();
            exit(0);
        case NTIM_ERR:
            break;
        case PREA_ERR:
        case PWRT_ERR:
        case PSAV_ERR:
            printf("Primary file not operational (%d)\n%s\n", uerr_cod,buffer);
            break;
        case CWRT_ERR:
        case CSAV_ERR:
            printf("Mirror file not operational (%d)\n%s\n", uerr_cod,buffer);
            break;
        default:
            printf("other monitor event(%d)\n%s\n", uerr_cod, buffer);
            break;
    }    /* end of switch */
}    /* end of while */

/* if server has terminated */
StopUser();
exit(0);

Limitations

Available only with the FairCom Server. A call to SystemMonitor() on a non-server system results in error return NSUP_ERR (454).

Only one application connected to each Server may have SystemMonitor() active.