FairCom DB Function Descriptions K-Z

LastInRange

Read the last data record in a range

Short Name

LSTRNG()

Type

ISAM function

Declaration

COUNT LastInRange(FILNO keyno, pVOID recptr)  

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

Read the last data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful LasttInRange() defines a current key value set, and subsequent calls to NextInRange() or PreviousInRange() will read the other records in the range.

If the data file has variable-length records, only the fixed-length portion of the record is actually read. You can use ReReadVRecord() to retrieve the whole record, including the variable-length portion. You can use LastInVRange() to read the whole variable-length record with one function call.

Return

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

See also

AllocateRange(), EstimateRange(), FirstInRange(), FirstInVRange(), FreeRange(), LastInVRange(), NextInRange(), NextInVRange(), PreviousInRange(), PreviousInVRange()

LastInSet

Read the last data record in the set defined by a target.

Short Name

LSTSET()

Type

ISAM function

Declaration

COUNT LastInSet(FILNO keyno, pVOID target, pVOID recptr, COUNT siglen)

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

LastInSet() reads the last data record in the set of data records whose keys match the target key in the first siglen bytes. If successful, this record becomes the current ISAM record for the associated data file. A successful LastInSet() defines a current key value set, and subsequent calls to NextInSet() and PreviousInSet() will read the other records in the set (i.e., those records whose keys also match the last siglen bytes of target). If an error occurs or no key value matches the target, the current ISAM record is not updated, and no key value set is defined.

If the data file has variable-length records, only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to LastInSet(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

The target buffer must be initialized to the full length of the key to avoid memory corruption when the target is transformed to match the key.

LastInSet() can be used to perform an equality search for duplicate keys. Set target to the key value of interest, and set siglen to the key length less the 4 bytes of the suffix.

Notice that you do not directly identify the data file number involved. The ISAM parameter file described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contains the correspondence between the index file number and the associated data file.

Return

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

Example

FILNO        keyfil;

TEXT         target[24], recbuf[320];

printf("\nEnter set value:");

scanf("%23s", target);

LastInSet(keyfil, TransformKey(keyfil,target), recbuf,

          strlen(target));

while (isam_err == NO_ERROR) {

   process_data();

   PreviousInSet(keyfil, recbuf);

}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

NextInSet(), PreviousInSet(), FirstInSet(), PositionSet(), ChangeSet(), CreateIFile(),
ReReadVRecord(), TransformKey()

LastInVRange

Read the last data record in a range

Short Name

LSTVRNG()

Type

ISAM function

Declaration

COUNT LastInRange(FILNO keyno, pVOID recptr, pVRLEN plen)  

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

Read the last data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful LasttInVRange() defines a current key value set, and subsequent calls to NextInVRange() or PreviousInVRange() will read the other records in the range.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Return

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

See also

AllocateRange(), EstimateRange(), FirstInRange(), FirstInVRange(), FreeRange(), LastInRange(), NextInRange(), NextInVRange(), PreviousInRange(), PreviousInVRange()

LastInVSet

Read the last variable-length data record in the set defined by target.

Short Name

LSTVSET()

Type

ISAM function

Declaration

COUNT LastInVSet(FILNO filno, pVOID target, pVOID recptr,

                 COUNT signlen, pVRLEN plen)

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

LastInVSet() is identical to it’s fixed-length counterpart, LastInSet(), except that it reads the last variable-length data record in the set defined by target and siglen. If successful, this record becomes the current ISAM record for the associated data file.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for LastInSet() for additional important information.

Return

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

See also

LastInSet(), NextInVSet(), PreviousInVSet(), TransformKey()

LastKey

Find the last entry in an index file.

Short Name

LSTKEY()

Type

Low-Level index file function

Declaration

LONG LastKey(FILNO keyno, pVOID idxval) 

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

LastKey() searches index file keyno for the last entry in the index. If successful, it copies the last index entry into the space pointed to by idxval.

Return

LastKey() returns the data record position associated with the last entry in the index file. If the index is empty or an error is detected, LastKey() returns zero. If LastKey() returns zero, check uerr_cod to see if an error occurred: if uerr_cod is also zero, then the index is empty; otherwise, an error condition was detected. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

TEXT     idxval[10];

FILNO    keyno;

if (LastKey(keyno,idxval))

   printf("\nLast index entry = %.10s", idxval);

else {

   printf("\nEither index is empty or an error occurred.");

   if (uerr_cod)

      printf("\Error = %d",uerr_cod);

   else

      printf("\Index is empty.);

}

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered. Use GetCtFileInfo() to determine the key length.

The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments. Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) in the c-tree Programmer’s Reference Guide contains suggestions for manipulating the key value.

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

GetCtFileInfo(), FirstKey(), NextKey()

LastRecord

Read the last data record.

Short Name

LSTREC()

Type

ISAM function

Declaration

COUNT LastRecord(FILNO filno, pVOID recptr)

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

LastRecord() retrieves the last data record found. If filno designates an index file, LastRecord() reads the last data record based on the key sequential order of entries in index file number filno. If filno designates a data file, LastRecord() reads the last active data record, in physical sequential order. If successful, the last record becomes the current ISAM record for the associated data file. If an error occurs or there are no entries, the current ISAM record is not updated.

If LastRecord() is called with an index number, the data file number involved is not directly described. The ISAM parameters described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contain the correspondence between the index number and the associated data file.

Return

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

Example

FILNO     keyfil,datfil;

TEXT      recbuf[320];

if (LastRecord(keyfil,recbuf))

    printf("\nError %d retrieving last record.", isam_err);

else if (ReReadVRecord(datfil,recbuf,320))

    printf("\nError %d retrieving variable portion.", isam_err);

else

    printf("\nSuccessful LastRecord.");

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

filno cannot be a data file number if any of the following are true:

• The data file is set up for variable-length records.
• The data file is a member of a Superfile.
• The data file has Resources enabled (the default state).

In any of the above cases, LastRecord() returns FMOD_ERR (48).

If filno is a key number whose associated data file has variable-length records, only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to LastRecord(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

See also

NextRecord(), PreviousRecord(), FirstRecord(), CreateIFile(), ReReadVRecord()

LastVRecord

Read the last variable-length data record.

Short Name

LSTVREC()

Type

ISAM function

Declaration

COUNT LastVRecord(FILNO filno, pVOID recptr, pVRLEN plen)

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

LastVRecord() is identical to it’s fixed-length counterpart, LastRecord(), except that it reads the last variable-length data record in the data file. If successful, this record becomes the current ISAM record for the associated data file.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for LastRecord() for additional important information.

Return

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

See also

LastRecord(), NextVRecord(), PreviousVRecord(), TransformKey()

LoadFilter

Called when FairCom DB loads a filter callback DLL. This function initializes resources that are used by the filter callback DLL.

Declaration

NINT LoadFilter(pTEXT libname, ppVOID plibhandle);

Where:

• libname is the filter callback DLL name that was passed to SetDataFilter().
• plibhandle is a pointer to an application-defined library handle.

Description

This function is defined in the ctuserx.c module used to build a filter callback function.

LoadFilter() can allocate memory for use by the filter callback function and can return its address in this parameter.

See also

ctfiltercbAddFilter(), EvaluateFilter(), ctfiltercbRemoveFilter(), UnloadFilter(), SetDataFilter()

LoadKey

Add key value to index file in presorted order.

Short Name

LOADKEY()

Type

Low-Level index file function

Declaration

COUNT LoadKey(FILNO keyno, pVOID target, LONG recbyt, COUNT typadd)

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

LoadKey() inserts the key value pointed to by target and the associated data record position recbyt into index file number keyno. Repeated calls to LoadKey() provide an exceptionally fast method to add key values which have already been sorted. The sorted keys must be added to an empty index or all of the sorted keys must be greater than the existing entries.

Calls to LoadKey() should not be intermixed for different indexes.

typadd signals the beginning, middle and end of the calls to LoadKey() as shown below:

LoadKey() is used by the RebuildIFile() to quickly build the indexes associated with a data file.

Return

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

Example

TEXT      target[11];

LONG      recbyt,trials;

FILNO     name_key;

COUNT     mode;

FILE      *fp;

trials = 0L;

mode   = FRSADD;

while (fscanf(fp,"%s %ld",target,&recbyt) == 2) {

    if (LoadKey(name_key,target,recbyt,mode))

        break;

    if (trials++)

        mode = NXTADD;

}

if (uerr_cod || LoadKey(name_key,NULL,0L,BLDADD))

    printf("\nerror during LoadKey (%d) on trial #%ld", uerr_cod,trials);

Limitations

LoadKey() does not pad key values. Therefore, if you pass a key value which is not completely specified to its full length, LoadKey() will effectively pad the value with whatever “garbage” follows the key value in memory.

Key values added to an index which supports duplicate keys (keydup = 1 in CreateIndexFile() or CreateIndexMember()) have their last 4 bytes overwritten by the associated data record position. In this way, identical key values become distinguishable.

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 Record Offsets Under Huge File Support.

See also

AddKey(), CreateIndexFile(), CreateIndexMember(), ctSETHGH(), ctGETHGH()

LockCtData

Lock / unlock data records or tables.

Short Name

LOKREC()

Type

Low-Level data file function

Declaration

COUNT LockCtData(FILNO datno, COUNT lokmod, LONG recbyt)

Description

LockCtData() provides Low-Level lock and unlock control over fixed- and variable-length data records. LockCtData() can also be used with ISAM files to relax the constraints of the “two-phase” protocol described in Multi-User Concepts of the c-tree Programmer’s Reference Guide. Because c-tree is based on write locks, a locked record can be read by other processes as long as they do not attempt their own write lock on the record.

lokmod specifies an action based on the following values:

Note: Many systems do not support read locks. If read locks are not supported, c-tree returns no error condition (i.e., the read lock is not attempted, but no error is reported). The FairCom Server supports both read and write locks.

recbyt specifies the beginning byte offset for the record lock/unlock operation. c-tree automatically provides the data file record length for the number of bytes to be locked. In the case of a variable-length file, c-tree only applies the lock to the minimum, fixed-length portion of the record. In any event, c-tree always asks for at least a 1-byte lock.

Return

In single-user applications, LockCtData() always returns successfully. In other modes, check uerr_cod for the values in the following table.

A LockCtData() call attempting to unlock a record that is part of transaction returns NO_ERROR (0), but sets sysiocod to UDLK-TRN (-3), indicating the lock will be held until the end of the transaction.

If LockCtData(datno,ctCHKLOK,recbyt) returns NO_ERROR then sysiocod holds the lock status. If sysiocod and uerr_cod are zero, then no lock is held by the calling user. If sysiocod is non-zero and uerr_cod is zero, interpret sysiocod as follows:

• The low-order byte contains the type of lock: ctENABLE (2) for a write lock, or ctREADREC (4) for a read lock.
• The high-order byte is composed of one or more of the following attributes bits (left shifted 8 bits):

The higher order byte may contain other attribute bits that may be found in ctport.h where ctISAMLOCK is defined.

For an example of ctCHKLOK, a call of the form LockCtData(datno, ctCHKLOK, recbyt) might return the following values:

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

Example

LONG      pntr;

FILNO     datno;

TEXT recbuf[147];

if ((pntr = NewData(datno)) == 0L ||

    fill_buffer(recbuf) != NO_ERROR ||

    WriteData(datno,pntr,recbuf) ||

    LockCtData(datno,ctFREE,pntr))

  printf("\nCould not write new record (%d)",uerr_cod);

/* NewData always acquires a lock on a new record */

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.

Locks on a specified record offset

ctCHKLOK_OTHER can be used to check if a lock is held on the specified offset of a data file by either another connection or by the same connection but with a different file number. The definition of "different file number" depends on the MULTIOPN mode that is in effect on the data file whose file number is specified:

• If using MULTIOPN_NODIFUSR or MULTIOPN_DIFUSR, then a lock that was acquired on the record offset by the calling connection using a different file number (known as a co-file) is treated as though the lock was acquired by another connection.
• If using MULTIOPN_SAMUSR_1 or MULTIOPN_SAMUSR_M, then a co-file lock is treated as though the lock was acquired by the calling connection.

To use this feature, call LOKREC() with the mode ctCHKLOK_OTHER. As with the ctCHKLOK mode, LOKREC() returns NO_ERROR to indicate success, or a non-zero error code to indicate failure. On success, c-tree's connection-level state variable sysiocod is set to indicate whether or not another connection or co-file has acquired a lock on the specified offset:

• A sysiocod value of 0 indicates no lock is held by another connection or co-file.
• A sysiocod value of 2 indicates a write lock is held by another connection or co-file.
• A sysiocod value of 4 indicates a read lock is held by another connection or co-file.

Table Locking

V11 and later of FairCom DB support file-level locking on c-tree data files, which is known as a "table lock." An application can request a file lock to prevent other connections from reading from and/or writing to the file. Table Locks can be invoked using SQL or using the LockCtData() function. For information, see the sections titled Table Lock Suppor (Table Lock Support, Table Lock)t.

LOKREC() modes to unlock all records in all files of the specified type that are open by the caller

In V11, LOKREC() function's ctFREE_FILE mode now supports options to free ALL locks in ALL specified types of files that a caller has open. To use this feature, call LOKREC() with mode of ctFREE_FILE, recbyt of zero (it is ignored), and set datno to one, or a combination of the following values:

• ctFREEALL_NOTRAN - free all non-transaction file locks
• ctFREEALL_NOIICT - free all transaction-controlled file locks without IICT enabled
• ctFREEALL_IICT - free all transaction-controlled file locks with IICT enabled
• ctFREEALL_TRAN - free all transaction-controlled file locks
• ctFREEALL_ALL - free all file locks

Example

Free all locks in all non-transaction files and all transaction-controlled files that are not using IICT that the caller has open.

rc = LOKREC( ctFREEALL_NOTRAN | ctFREEALL_NOIICT,ctFREE_FILE, 0 );

See also

LockISAM(), NewData(), NewVData()

LockDump

Dump the FairCom Server internal lock table.

Short Name

ctLOKDMP()

Type

Low-Level function

Declaration

COUNT LockDump(COUNT refno, pTEXT dumpname, COUNT mode)   

Description

LockDump() creates a diagnostic dump of the FairCom Server internal lock table. refno indicates whether locks for a particular file or user are to be dumped or whether all locks are to be dumped. mode indicates whether the dump is organized by file or by user number. dumpname is the name of a text file to which the contents of the dump will be appended.

The possible legal combinations of the mode and refno parameters are as follows:

In all but one case of the above combinations the caller of LockDump() does not have to have any files open, although it is no problem if the caller does have files open. In the case of ctLOKDMPfile/filno, the caller must have opened a file with file number filno. The userno referenced in the last combination is the thread ID assigned by the FairCom Server. This thread ID is listed when ctadmn is used to list users logged on to the FairCom Server. In addition to dumping the location of the lock and the type of lock, users waiting for a lock are also listed.

Lock Dump Contents

=================================================

All Files Lock Dump at Fri May 04 13:00:12 2007

----------------

----------------

SOMEFILE.FCS>>

        0000-013c9a16x T221 write/1: W060 W254 W740 W763 W758

        0000-002916abx T758 write/1: W774 W772 W771 W775 W773 W778 W779 W776 W071

cumulative lock attempts: 4002(616)  blocked: 21(0)  dead-lock: 0  denied: 0

Current file lock count: 0

----------------

cumulative I/O: read ops: 0 bytes: 0    write ops: 5 bytes: 16768

.

.

.

.

List of connected clients

-------------------------

User# 00002: (Node name not set)

User# 00012: (Node name not set)

=================================================

Description

In the example above, there are two records with locks held in SOMEFILE.FCS. Each record is listed with it’s locked file offset value, the thread ID of the user holding the lock, the type of lock, and a listing of thread IDs waiting for the record lock to be released. The waiting thread IDs are further delineated with a prefix indicating the type of lock they are waiting to obtain, write (W) or read (R) locks.

Types of Locks

There are several types of record locks that can be reported. The most common of these are:

• read - A read lock requested and held by a user thread.
• write/1 - A write lock requested and held by a user thread.
• write/2 - An internal lock very briefly held by the FairCom Server for files under transaction control. You may occasionally observe these in a system with a high transaction volume, and these can be safely ignored.
• forcei cmtlok - A very briefly held commit read lock enforced by the FairCom Server. These will only occur when the COMMIT_READ_LOCK option is enabled in the server configuration file. These may be occasionally observed in systems with high transaction volumes.

File Lock Info

• cumulative lock attempts xxx (yyy) - Total number of file and (header) lock attempts. The header locks are internal FairCom Server locks required for critical updates to the file header.
• blocked - Total number of locks and (header locks) that were blocked while another lock was held. In a high volume system, some blocked lock attempts are expected.
• dead-lock - Total of dead-lock conditions reported for this file. These are generally not expected, and error DEAD_ERR (86) is returned to the application caller when this condition is detected. DEAD_ERR is returned when waiting for a write lock would cause a deadlock condition.
• denied - Total number of locks denied to a caller with error DLOK_ERR (42). A lock is denied if the record is already locked. Note that blocking locks cause the thread to sleep until the lock is available, avoiding the DLOK_ERR.

Cumulative I/O

• read ops - Total cumulative read operations for this file.
• bytes - Total cumulative bytes read for this file.
• write ops - Total cumulative write operations for this file.
• bytes - Total cumulative bytes written for this file.

List of Connected Clients

A list of all connected clients is appended to the end of the lock dump output. This assists the correlation of known user threads at the application level to threads with potential blocked locks.

• User# - The thread ID of the user as identified by the FairCom Server
• Node Name - The node name of the thread as assigned by the application.

Note: On Windows, the list of connected clients includes the IP address in addition to the user name and node name.

Return

The common error code returns are:

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

Example

COUNT     retval;

TEXT      dumpname[20]="AllUserLocks.dmp"

retval = LockDump(ctLOKDMPallusers, dumpname, ctLOKDMPuser);

switch (retval) {

    case NO_ERROR:

        break;

    case NUSUP_ERR:

        terminate("LockDump not supported .");

    default:

        terminate("LockDump error.");

}

Limitations

Note: Dumping large quantities of locks in a very active system could affect performance.

Because of potential performance impact, a FairCom Server will ONLY support the LockDump() call if either of the following conditions is met:

• The configuration file, ctsrvr.cfg, contains DIAGNOSTICS LOCK_DUMP.
• The user calling LockDump() belongs to the ADMIN user group.

Related Topics

• The command-line utility ctstat -filelocks and -userlocks modes provide an alternate way to retrieve lock table information. That utility provides a more granular method of inspecting locks. See File and User Lock Example in the FairCom DB Server Administrator's Guide.
• LockDump Output

LockISAM

Enable, free, or suspend data record locks.

Short Name

LKISAM()

Type

ISAM function

Declaration

COUNT LockISAM(COUNT lokmod) 

Description

LockISAM() manages the data record locks during multiple-user ISAM file handling. The LockISAM() options, defined in ctport.h, are:

To ensure multi-user systems make consistent updates, each program should ctENABLE data record locks prior to updating data, and hold these locks until the operations associated with those data records are completed. At that time, a call to LockISAM() with the ctFREE mode cancels all outstanding ISAM locks. Locks created by LockCtData() will NOT be released. ctRESET is used when traversing the data in key sequential order when, after each update, the previous locks should be released and new locks enabled for the next transaction.

ctREADREC signals that the record is under review by one or more readers, and that no update should be performed. If records are read without read, or write, locks, another process may update the record while it is under review. Usually, this is acceptable.

Note: Many systems do not support read locks. If read locks are not supported, c-tree returns a NO_ERROR condition (i.e., the read lock is not attempted, but no error is reported). The FairCom Server DOES support both read and write locks.

Five LockISAM() modes toggle locking, avoiding unnecessary data record locks in the middle of a transaction. These modes are ctSUSPEND, ctRESTORE, ctRESTORE_BLK, ctRESTRED, and ctRESTRED_BLK. Use the ctSUSPEND mode to scan one or more data records which will NOT be updated, or for which READ LOCKS ARE NOT REQUIRED, in the middle of a transaction which has already enabled data record locks. After scanning these records and before returning to your update activities, either:

• Call LockISAM() with the ctRESTORE mode to restore ctENABLE.
• Call LockISAM() with the ctRESTORE_BLK mode to restore ctENABLE_BLK.
• Call LockISAM() with the ctRESTRED mode to restore ctREADREC.
• Call LockISAM() with the ctRESTRED_BLK mode to restore ctREADREC_BLK.

Return

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

In the example below, a program performing updates to customer invoices does updates involving price extension computations. To perform the computations, the program searches a separate ISAM file maintaining the prices. Since the program does not modify the price records, it calls LockISAM(ctSUSPEND) before searching the price records, and LockISAM(ctRESTORE) before continuing with the invoice updates.

Example

FILNO     inv_idx, inv_fil, price_idx, price_fil;

TEXT      target[9];

struct invd  {

    TEXT     delflg;

    TEXT     invn[8];

    TEXT     dscrp[60];

    TEXT     part[12];

    float    quant;

    float    price;

    float    exten;

} cur_info;

struct {

    TEXT     pdlflg;

    TEXT     ppart[12];

    float    pprice;

} price_rec;

main() {

    printf("\nEnter invoice number: ");

    scanf("%8s",target);

    if (LockISAM(ctENABLE) ||

       FirstInSet(inv_idx, target, &cur_info,8)) {

        printf("\n\nError starting SCAN with codes %d %d",

               isam_err,isam_fil);

        LockISAM(ctFREE);

        return;

    }

    while (!isam_err) {

        LockISAM(ctSUSPEND);      /* turn off lock acquisition */

        get_price_extension();

        LockISAM(ctRESTORE);      /* restore lock acquisition  */

        ReWriteRecord(inv_fil,&cur_info);

        ResetRecord(inv_fil,SWTCURI);

                                /* reset current ISAM record */

        LockISAM(ctRESET);

        NextInSet(inv_idx,&cur_info);

    }

    LockISAM(ctFREE);

}

void get_price_extension()

{

    if (GetRecord(price_idx,cur_info.part,&price_rec)) {

        printf("\nCould not find part# %s.",cur_info.part);

        return;

    }

    new_info.exten = (cur_info.price = price_rec.pprice) *

                     cur_info.quant;

}

Limitations

The FairCom Server supports both read and write locks on records. When not using the Server for multi-user applications, read locks may show success even if read locks are not implemented.

When using Transaction functions, refer to “Data Integrity” in the c-tree Programmer’s Reference Guide for information on how transaction processing interacts with LockISAM().

See also

LockCtDat()

LockList

Retrieve a list of users that own, and are waiting for, a data record lock at a specified byte offset of a data file.

Declaration

NINT LockList(FILNO datno, ctRECPT recbyt, NINT NbrUsers, pLOCKID userlist, pLONG pNbrLockers, pLONG pNbrWaiters);

Short Name

ctLOKLST

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

LockList() information is obtained with the following parameters

• datno is the file number of a data file opened by the calling program.
• recbyt is the byte offset of a data record. To set the high-order word of the record offset for huge files, call ctSETHGH() immediately before calling LockList().
• NbrUsers is the number of LOCKID structures in the array pointed to by userlist.
• userlist may be NULL, but then NbrUsers must be zero.
• pNbrLockers and pNbrWaiters cannot be NULL. In the event that NbrUsers is smaller than the sum of lockers and waiters, then the list returned in userlist is truncated after NbrUsers entries. LockList() returns NO_ERROR if successful.

LockList() returns the user identification information for lock owners and lock waiters in the userlist array. The lock owners are returned at the beginning of the array, and the lock waiters follow the lock owners in the array. The number of lock owners is returned in the 4-byte integer pointed to by pNbrLockers. For read locks there may be more than one lock owner. For write locks there can only be one lock owner unless strict serialization is in effect. The number of users waiting for the lock is returned in the 4-byte integer pointed to by pNbrWaiters. There are waiters for a lock only when a lock request includes the blocking attribute (e.g., ctENABLE_BLK).

Details

LOCKID is a structure defined in ctport.h that includes the internal thread ID, the login name and the node name:

typedef struct lockid {

    LONG ThrdID;        /* internal thread ID */

    TEXT UserID[32];    /* logon ID [IDZ] */

    TEXT NodeName[32];  /* optional network NodeName IDZ*/

} LOCKID, * pLOCKID;

Because an ISAM operation that fails with a lock denied error DLOK_ERR (42) does not permit the denied locker to determine the record location of the denied lock, LockList() has been enhanced to accept a pseudo datno that indicates the request is for the last denied data record lock by the caller. Use ctLastDeniedLock, defined in ctport.h, for datno and the recbyt will be ignored. Instead, the last denied record lock, across all of the data files opened by the user, if any, will be examined for current lockers and waiters.

The last denied data record lock is not cleared upon the next successful data record lock. So calling LockList(ctLastDeniedLock ...) may be referencing a denied lock from the “distant” past. If the user closes the data file which contains the last denied lock, then the last denied lock will be cleared.

Return

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

The following is an example to list all lock owner and “waiters” for a given record offset.

Example

NINT ListLockUsers(NINT datno, ctRECPT recbyt)

{

    NINT i;

    LOCKID list[128];

    LONG lockers, waiters;

    NINT eRet;

    ctSETHGH(0);

    eRet = (NINT)LockList((FILNO)datno, recbyt, 128, &list, &lockers, &waiters);

    if (eRet != NO_ERROR)

    {

        printf("LockList failed with error %d\n", eRet);

        return -1;

    }

    /* list lock owners */

    for (i = 0; i < (NINT)lockers; i++)

        printf("Lock owner %s\n", list[i].UserID);

    /* list lock waiters */

    for (i = (NINT)lockers; i < (NINT)waiters; i++)

        printf("Waiting for lock %s\n", list[i].UserID);

    return (NINT)(lockers + waiters);

}

See also

LockCtData(), LockDump(), LockISAM()

NbrOfKeyEntries

Number of entries in index file.

Short Name

IDXENT()

Type

Low-Level index file function

Declaration

LONG NbrOfKeyEntries(FILNO keyno)

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

NbrOfKeyEntries() returns the number of entries in index file number keyno.

Note: A huge file may return values greater than 4 GB. This function returns the low-order 4-byte word of the 8-byte number of keys. To get the high-order 4-byte word, call ctGETHGH(). A return of zero is not necessarily an error if there are exactly a multiple 4 GB worth of key values.

Return

If an error occurs or the index file is empty, NbrOfKeyEntries() returns zero. Otherwise, NbrOfKeyEntries() returns the number of entries in the index file. When NbrOfKeyEntries() returns a zero, check uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key values are in the index. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

FILNO     keyno;

scanf("%d",&keyno);

printf("\nThere are %ld entries in index #%d.",

       NbrOfKeyEntries(keyno),keyno);

Limitations

With Standalone Multi-user systems, or when updates are immediately forced to disk, the time to add or delete an index entry can be reduced if the number of index entries is not maintained. By default, c-tree maintains this information. To disable this feature, add #define NO_IDXENT to the bottom of ctoptn.h/ctree.mak. By adding this define, multi-user, non-server applications may experience a performance gain. Therefore, we suggest you only use this function if it is very important to quickly determine the number of index entries.

NbrOfKeysInRange

Return the number of active index entries found between two targets .

Short Name

RNGENT()

Type

Low-Level index file function

Declaration

LONG NbrOfKeysInRange(FILNO keyno, pVOID idxval1, pVOID idxval2)

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

NbrOfKeysInRange() returns the number of active index entries found between idxval1 and idxval2 for index file keyno. idxval1 and idxval2 must be properly formed keys, as is necessary with any c-tree function that retrieves data using indexes. This function is very helpful for controlling list boxes requiring “thumb operations”.

Note: A huge file may return values greater than 4 GB. This function returns the low-order 4-byte word of the 8-byte number of keys. To get the high-order 4-byte word, call ctGETHGH(). A return of zero is not necessarily an error if there are exactly a multiple 4 GB worth of key values.

Return

On success, NbrOfKeysInRange() returns the number of active index entries found between the given targets. If an error occurs or the index file is empty, NbrOfKeysInRange() returns zero. When NbrOfKeysInRange() returns zero, check uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key values are in the index. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

The following example uses a duplicate allowed index over customer name. The code prompts the user for a beginning name and an ending name for the range. ActiveRange() takes the number of active index entries between the two values entered by the user.

Example

#define maxbuf 40

TEXT      idxval1[maxbuf];             /* input buffer one */

TEXT      idxval2[maxbuf];             /* input buffer two */

LONG      ActiveRange;

memset(idxval1,' ',maxbuf);

printf("\n\tEnter first name for range:");

gets(idxval1);

TransformKey(2,idxval1);      /* properly form index value 1 */

memset(idxval2,' ',maxbuf);

printf("\n\tEnter last name for range:");

gets(idxval2);

TransformKey(2,idxval2);      /* properly form index value 2 */

ActiveRange = NbrOfKeysInRange(2,idxval1,idxval2);

printf("\nRNGENT for Parent Key is %ld uerr_cod = %d", ActiveRange,uerr_cod);

See also

GetORDKey(), NbrOfKeyEntries()

NbrOfRecords

Get the number of active records in fixed-length data file.

Short Name

DATENT()

Type

Low-Level fixed-length data file function

Declaration

LONG NbrOfRecords(FILNO datno)

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

NbrOfRecords() returns the number of active data records for the fixed length data file designated by datno.

Each time a new record is added to the file, the count of active records is incremented. Each time a record is deleted, the active count is decremented. A record is added by the Low-Level function NewData() or the ISAM function AddRecord(). A record is deleted by the Low-Level function ReleaseData() or the ISAM function DeleteRecord().

Note: A huge file may return values greater than 4 GB. This function returns the low-order 4-byte word of the 8-byte number of keys. To get the high-order 4-byte word, call ctGETHGH(). A return of zero is not necessarily an error if there are exactly a multiple 4 GB worth of key values.

Return

If an error occurs or if there are no active data records, NbrOfRecords() returns a value of zero. Otherwise, NbrOfRecords() returns the number of active fixed data records in the data file. After a call to NbrOfRecords() returns a zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no active records are in the file. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

FILNO   datno;

scanf("%d",&datno);

printf("\nThere are %ld active records in file #%d.",

NbrOfRecords(datno),datno);

See also

NewData(), AddRecord(), DeleteRecord(), ReleaseData()

NewData

Get next available fixed-length data record position.

Short Name

NEWREC()

Type

Low-Level data file function

Declaration

LONG NewData(FILNO datno)

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

NewData() determines the next available data record position for fixed-length data file datno. If records have been deleted via ReleaseData, they are reused by NewData() before the file size is extended.

Each call to NewData() increments the serial number associated with the file. The ISAM level key segment mode of three (SRLSEG) permits this serial number to be part of a key value to enable chronologically, or reverse chronologically, ordered key values. See ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide.

Note: In multi-user systems, NewData() automatically acquires a data record lock on the newly acquired record. This lock should be released using LockCtData() after writing the contents of the new record.

Return

NewData() returns the data record position of the next available record. If an error occurs, NewData() returns a zero and uerr_cod is set to a non-zero value.

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

Example

LONG      recd;

FILNO     dfil;

pTEXT     recptr;

if (recd = NewData(dfil))

    if (WriteData(dfil, recd, recptr) == 0)

        if (LockCtData(dfil, ctFREE, recd) == 0)

            printf("\nSuccessful addition of new record.");

        else

            printf("\nError %d unlocking record.", uerr_cod);

    else

        printf("\nError %d writing record.", uerr_cod);

else

    printf("\nError %d getting new record pointer.", uerr_cod);

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

ReleaseData(), LockCtData(), NewVData()

Data File Layout

NewVData

Get next available variable-length data record position.

Short Name

NEWVREC()

Type

Low-Level data file function

Declaration

LONG NewVData(FILNO datno, VRLEN varlen)

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

NewVData() determines the next available data record position for variable-length data file datno. If records have been deleted via ReleaseVData(), and if they are large enough, they are reused by NewVData() before the file size is extended.

Each call to NewVData() increments the serial number associated with the file. The ISAM level key segment mode of three (SRLSEG) permits this serial number to be part of a key value to enable chronologically, or reverse chronologically, ordered key values. See ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide.

Note: In multi-user systems, NewVData() automatically acquires a data record lock on the newly acquired record. This lock should be released using LockCtData() after writing the contents of the new record.

A 10-byte control block specifying the record length and the length used precedes each variable-length record whether the record is active or not.

Return

NewVData() returns the data record position of the next available record. If an error occurs, NewVData() returns a zero and uerr_cod is set to a non-zero value.

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

Example

LONG      recd;

FILNO     dfil;

VRLEN     varlen;

pTEXT     recptr;

varlen = strlen(recptr);

if (recd = NewVData(dfil, varlen))

    if (WriteVData(dfil, recd, recptr, varlen) == 0)

        if (LockCtData(dfil, ctFREE, recd) == 0)

            printf("\nSuccessful addition of new record.");

        else

            printf("\nError %d unlocking record.", uerr_cod);

    else

        printf("\nError %d writing record.", uerr_cod);

else

    printf("\nError %d getting new record pointer.", uerr_cod);

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

ctSETHGH(), ctGETHGH(), ReleaseVData(), LockCtData(), NewData()

NextCtree

Change to the next registered c-tree instance.

Short Name

NXTCTREE()

Type

Low-Level function

Declaration

pTEXT NextCtree() 

Description

NextCtree() cycles to the next available c-tree instance.

When multiple instances of c-tree are established with RegisterCtree(), control blocks are connected via a link list. The last control block points back to the first. Therefore, a NextCtree() call when the last instance is current results in the first instance becoming current.

Repeated calls to NextCtree() result in continually looping through all c-tree instances. In the example program ctlxmg, the reference name of the first instance is saved to determine the “end-of-instances”.

Return

A successful NextCtree() call returns the pointer to the instance reference name. Each instance reference name, up to 31 bytes and a NULL terminator in length, is originally registered with c-tree using RegisterCtree(). If there are no active instances, a NULL will be returned.

See also

SwitchCtree(), RegisterCtree(), WhichCtree(), GetCtreePointer(), UnRegisterCtree()

NextInRange

Read the next data record in a range

Short Name

NXTRNG()

Type

ISAM function

Declaration

COUNT NextInRange(FILNO keyval, pVOID recptr)  

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

Read the next data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful NextInRange() defines a current key value set, and subsequent calls to NextInRange() or PreviousInRange() will read the other records in the range.

If the data file has variable-length records, only the fixed-length portion of the record is actually read. You can use ReReadVRecord() to retrieve the whole record, including the variable-length portion. You can use NextInVRange() to read the whole variable-length record with one function call.

Return

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

See also

AllocateRange(), EstimateRange(), FirstInRange(), FirstInVRange(), FreeRange(), LastInRange(), LastInVRange(), NextInVRange(), PreviousInRange(), PreviousInVRange()

NextInSet

Read the next data record in the set defined by target.

Short Name

NXTSET()

Type

ISAM function

Declaration

COUNT NextInSet(FILNO keyno, pVOID recptr)  

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

NextInSet() reads the next data record in the set of data records whose keys match the set created by an earlier set function call. If successful, this record becomes the current ISAM record for the associated data file. If an error occurs or no key value matches the target, the current ISAM record is not updated, and no key value set is defined.

If the data file has variable-length records, only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to NextInSet(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

Notice that you do not directly identify the data file number involved. The ISAM parameter file described in c-tree Error Codes of the c-tree Programmer’s Reference Guide contains the correspondence between the index file number and the associated data file.

Return

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

Example

FILNO        keyfil;

TEXT         target[24],recbuf[320];

printf("\nEnter set value:");

scanf("%23s",target);

FirstInSet(keyfil,target,recbuf,strlen(target));

while (isam_err == NO_ERROR) {

   process_data();

   NextInSet(keyfil,recbuf);

}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

FirstInSet(), PreviousInSet(), LastInSet(), PositionSet(), ChangeSet(), CreateIFile(), ReReadVRecord(), TransformKey()

NextInVRange

Read the next data record in a range

Short Name

NXTVRNG()

Type

ISAM function

Declaration

COUNT NextInVRange(FILNO keyval, pVOID recptr, pVRLEN plen)  

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

Read the next data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful NextInVRange() defines a current key value set, and subsequent calls to NextInVRange() or PreviousInVRange() will read the other records in the range.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Return

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

See also

AllocateRange(), EstimateRange(), FirstInRange(), FirstInVRange(), FreeRange(), LastInRange(), LastInVRange(), NextInRange(), PreviousInRange(), PreviousInVRange()

NextInVSet

Read the next variable-length data record in the set defined by target.

Short Name

NXTVSET()

Type

ISAM function

Declaration

COUNT NextInVSet(FILNO filno, pVOID recptr,pVRLEN plen)

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

NextInVSet() is identical to it’s fixed-length counterpart, NextInSet(), except that it reads the next variable-length data record in the set defined by target and siglen. If successful, this record becomes the current ISAM record for the associated data file.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for NextInSet() for additional important information.

Return

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

See also

NextInSet(), FirstInVSet(), PreviousInVSet(), TransformKey()

NextKey

Find the next entry in an index file.

Short Name

NXTKEY()

Type

Low-Level index file function

Declaration

LONG NextKey(FILNO keyno, pVOID idxval) 

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

NextKey() searches index file keyno for the next entry in the index. If successful, it copies the index entry into the space pointed to by idxval. NextKey() fails if it is the first index search routine called after the index is opened, or if the entry found before the call to NextKey() is the last entry in the index. Repeated calls to NextKey() move through the index in ascending key value order.

Return

NextKey() returns the data record position associated with the next entry in the index file. If the index is empty or an error is detected, NextKey() returns zero. If NextKey() returns zero, check uerr_cod to see if an error occurred: if uerr_cod is also zero, then the index is empty; otherwise, an error condition was detected. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

LONG      recbyt;

TEXT      idxval[10];  /* 10 byte key, no duplicates */

FILNO     keyno;

recbyt = FirstKey(keyno,idxval);

while (recbyt) {

    printf("\nIndex Entry %.10s found in record #%ld",

            idxval,recbyt);

    recbyt = NextKey(keyno,idxval);

}

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered. Use GetCtFileInfo() to determine the key length.

The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments. Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) in the c-tree Programmer’s Reference Guide contains suggestions for manipulating the key value.

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

GetKey(), GetCtFileInfo(), LastKey(), PreviousKey()

NextRecord

Read the next data record.

Short Name

NXTREC()

Type

ISAM function

Declaration

COUNT NextRecord(FILNO filno, pVOID recptr)

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

NextRecord() retrieves the next data record found. If filno designates an index file, NextRecord() reads the next data record based on the key sequential order of entries in index file number filno. If filno designates a data file, NextRecord() reads the next active data record, in physical sequential order. If successful, the next record becomes the current ISAM record for the associated data file. If an error occurs or there are no entries, the current ISAM record is not updated.

If filno designates a data file that is a member of a Superfile, NextRecord() may not reliably return the next physical active data record, though it will retrieve a record.

If the data file has variable-length records, only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to NextRecord(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

If NextRecord() is called with an index number, the data file number involved is not directly described. The ISAM parameters described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contain the correspondence between the index number and the associated data file.

NextRecord() can move sequentially through a data file based on one index then switch to another index. For example, moving through an inventory file in part number order before switching to part name order by changing the keyno parameter in the NextRecord() call.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

Return

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

Example

FILNO     acct_idx, test;

TEXT      recbuf[320];

test = FirstRecord(acct_idx,recbuf);

while (test == NO_ERROR) {

    post_interest(recbuf);

    test = NextRecord(acct_idx,recbuf);

}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

FirstRecord(), PreviousRecord(), LastRecord(), CreateIFile(), ReReadVRecord()

NextVRecord

Read the next variable-length data record in the data file.

Short Name

NXTVREC()

Type

ISAM function

Declaration

COUNT NextVRecord(FILNO filno, pVOID recptr, pVRLEN plen)

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

NextVRecord() is identical to it’s fixed-length counterpart, NextRecord(), except that it reads the next variable-length data record. If successful, this record becomes the current ISAM record for the associated data file.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for NextRecord() for additional important information.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

Return

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

See also

NextRecord(), PreviousVRecord(), TransformKey()

OpenCtFile

Open a data file.

Short Name

OPNFIL()

Type

Low-Level file function

Declaration

COUNT OpenCtFile(FILNO filno, cpTEXT filnam, COUNT filmod)

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

OpenCtFile() opens the file with the name pointed to by filnam in the mode specified by filmod. Subsequent calls to other Low-Level data file functions use filno to reference this file. filno must be in the range 0 to fils - 1, where fils is the second parameter in the initialization routine InitCTree().

The name referenced by filnam must conform to the operating system environment, and usually can include directory path names and/or disk drive identifiers. The file name should be null terminated. If filnam references an index file with additional index members, OpenCtFile() opens all indexes included in the file. The indexes are assigned file numbers equal to filno in OpenCtFile() plus their member number.

Before a file can be opened, it must be created with either CreateDataFile() or CreateIndexFile().

filmod is limited to the values shown below. Modes not listed below are reserved for creating files, and cannot be changed for an existing file. For example, you need not specify ctFIXED or ctVLENGTH when opening the file, as that is set when the file is created.

ctPERMANENT ctVIRTUAL

ctEXCLUSIVE ctSHARED ctREADFIL

ctCHECKLOCK ctCHECKREAD

ctDUPCHANEL

ctWRITETHRU

ctOPENCRPT

ctCHECKREAD and ctDUPCHANEL are available only with the FairCom Server. See filmod in the index for additional information. Some values must be used exclusively. For instance, you cannot use both ctSHARED and ctEXCLUSIVE.

SUPERFILES: Superfiles and superfile members, discussed in the chapter titled “c-tree Features” of the c-tree Programmer’s Reference Guide, must be handled differently than standard files. Form the name of the member as follows:

<name of superfile>!<name of member>

Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.

Return

OpenCtFile() returns an error code from the table below. On a successful open when a differently named file matches the file ID of an open file, the error return will be NO_ERROR(0) but sysiocod will be set to MFID_COD (-586). If the files are detected to actually be different, then the file ID is changed as discussed above and sysiocod is not set to MFID_COD.

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

Example

FILNO     filno = 0;

COUNT     retval=0;

TEXT      filnam[15] = "sample.dat";

if (retval = InitCTree(100, 10, 64))

    printf("\nCould not initialize c-tree connection. Error %d.", retval);

else {

    if (retval = OpenCtFile(filno, filnam, (ctSHARED | ctFIXED)))

        printf("\nCould not open file. Error %d.", retval);

    else if (CloseCtFile(filno, 0))

        printf("\nCould not close file.");

    if (retval = StopUser())

        printf("\nCould not close c-tree connection. Error %d.", retval);

}

Limitations

In Standalone Multi-user implementations of c-tree, the locking routines depend on the operating system, and possibly the compiler. If your operating system or compiler does not support locks, you may have to code your own locking routines. The ctclib.c files provided in each sub-directory contain locking routines and shared file opening facilities for the popular multi-user and network systems.

See also

InitCTree(), CreateDataFile(), CreateIndexFile(), OpenCtFile(), OpenCtFileXtd()

OpenCtFileXtd

Extended data or index file open.

Short Name

OPNFILX()

Type

Extended Low-Level file function

Declaration

COUNT OpenCtFileXtd(FILNO filno, cpTEXT filnam, COUNT filmod, cpTEXT fileword)

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

OpenCtFileXtd() is a variation of OpenCtFile() that permits the use of the FairCom Server’s security system. This section expands on the description of OpenCtFile().

fileword is an optional file password. Set fileword to NULL if there is no password for this file. If a password is established, every user will need to use the password to be able to open the file. For more information on file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.

Return

The following error codes may be seen in addition to those for OpenCtFile():

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

See also

InitCTree(), CreateIndexFile(), OpenCtFile()

OpenFileWithResource

Incremental ISAM open, based on the IFIL Resource.

Short Name

OPNRFIL()

Type

ISAM function

Declaration

COUNT OpenFileWithResource(FILNO filno, cpTEXT filnam, COUNT filmod)  

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

OpenFileWithResource() opens the data file with the name pointed to by filnam and optional index files referenced by the IFIL resource information stored in that file. This resource was automatically added to the file when the file was created with CreateIFile() unless Resources have been disabled for this file. All subsequent references to the file are made via the filno value. filno must be less than fils - 1, where fils is the second parameter in the initialization routine InitISAM().

The name referenced by filnam must conform to the operating system environment, and usually can include directory path names and/or disk drive identifiers. If you are trying to open a file in a subdirectory of the data folder, your path must start with "." as in ./subdir/MyFile.dat.

If OpenFileWithResource() is called with a different path than the original IFIL definition holds, an attempt is made to automatically update alternative index names with the same path modification. The file name should be null terminated. If filnam references an index file with additional index members, OpenFileWithResource() opens all indexes included in the file.

Consecutive file numbers are assigned to the data file and any associated indexes. If filno is less than zero, c-tree finds the first available block of consecutive file numbers that can accommodate the data file and its indexes. If a block of numbers is found, the first number in the block is assigned to the data file and returned. If filno is greater than or equal to zero, filno is assigned to the data file and returned provided enough consecutive file numbers are available.

filmod is limited to the values shown below. Modes not listed are reserved for file creation and cannot change for an existing file. For example, ctFIXED or ctVLENGTH are not specified when opening the file, as they are set when the file is created.

ctPERMANENT ctVIRTUAL

ctEXCLUSIVE ctSHARED ctREADFIL

ctCHECKLOCK ctCHECKREAD

ctDUPCHANEL

ctWRITETHRU

ctOPENCRPT

ctCHECKREAD and ctDUPCHANEL are available only with the FairCom Server. See filmod in the index for additional information. Some values must be used exclusively. For instance, you cannot use both ctSHARED and ctEXCLUSIVE.

Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.

Return

OpenFileWithResource() returns the file number assigned to the data file. If an error occurs, the function returns a -1 and isam_err contains an error code. On a successful open when a differently named file matches the file ID of an open file, the error return will be NO_ERROR (0) but sysiocod will be set to MFID_COD (-586). If the files are detected to actually be different, then the file ID is changed as discussed above and sysiocod is not set to MFID_COD.

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

Example

FILNO     filno = 0;

COUNT     retval=0;

TEXT      filnam[15] = "sample.dat";

if (retval = InitISAM(6,7,4))

    printf("\nCould not initialize. Error %d.", retval);

else {

    if (OpenFileWithResource(filno, filnam, ctSHARED) < 0)

        printf("\nCould not open file (%d,%d).", isam_err, sysiocod);

    else if (CloseRFile(filno))

        printf("\nCould not close file (%d,%d).", isam_err, sysiocod);

    if (CloseISAM())

        printf("\nCould not close ISAM.");

}

Limitations

The data file must contain a resource record with the appropriate Incremental ISAM Structures (IFIL, etc.). CreateIFile() inserts a resource record and adds Incremental ISAM Structures. However, if the file was created without resource records, by either removing #define RESOURCE from ctoptn.h or by using ctDISABLERES as a file mode, resources can be enabled dynamically using EnableCtResource(). The Incremental ISAM Structures can be inserted by calling PutIFile().

See also

EnableCtResource(), PutIFile(), OpenIFile(), InitISAM(), CreateIFile(), CloseISAM(), OpenFileWithResourceXtd() and ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide describing the ISAM parameters.

OpenFileWithResourceXtd

Incremental ISAM open, based on the IFIL Resource (extended).

Short Name

OPNRFILX()

Type

Extended ISAM function

Declaration

COUNT OpenFileWithResourceXtd(FILNO filno, cpTEXT filnam,

                              COUNT filmod, cpTEXT fileword)

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

OpenFileWithResourceXtd() is a variation of OpenFileWithResource() that permits the use of the FairCom Server’s security system. This section expands on the description of OpenFileWithResource().

fileword is an optional file password. Set fileword to NULL if there is no password for this file. If a password is established, every user will need to use the password to be able to open the file. For more information on file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.

Return

OpenFileWithResourceXtd() returns the file number assigned to the data file. If an error occurs, the function returns a -1 and isam_err contains an error code. The following error codes may be seen in addition to those for OpenFileWithResource():

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

Return Relative File Number

In V11.5 and later, the OPNRFILX() function has been modified so that, when it is called with a negative data file number, if the open fails, isam_fil is returned as a relative file number:

isam_fil = 0 indicates the data file open failed.
isam_fil = 1 indicates the first index open failed, etc.

Note: This feature is a Compatibility Change.

Prior to this change, OPNRFILX() set isam_fil to the file number that was not possible to open. However, it did not return useful information when it was called with a negative data file number, such as OPNRFIL(-1).

See also

InitISAM(), CreateIFile(), OpenFileWithResource()

OpenIFile

Incremental ISAM open.

Short Name

OPNIFIL()

Type

ISAM function

Declaration

COUNT OpenIFile(pIFIL ifilptr) 

Description

OpenIFile() opens the data file and (optional) index file referenced by the IFIL structure pointed to by ifilptr. The file name pointed to by the IFIL structure, ifilptr->pfilnam, should NOT include an extension: .dat and .idx are automatically appended to the file name for the data file and index file, respectively. The extended version of this function, OpenIFileXtd(), can change the file extensions at run time.

If you desire the files to be opened in directories that are not specified until run-time, then ifilptr->pfilnam should not be finalized until run-time.

Consecutive file numbers are assigned to the data file and any (optional) indexes associated with the data file. The IFIL structure contains two file numbers: a permanent file number (dfilno), and a temporary file number (tfilno). If dfilno is less than zero, c-tree finds the first available block of sufficient consecutive file numbers. If such a block of numbers is found, then the first number in the block is assigned to the data file and to tfilno. If dfilno is greater than or equal to zero, then dfilno is assigned to the data file and to tfilno.

Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.

Return

Upon successful open, ifilptr->tfilno contains the file number assigned to the data file; and the associated indexes are assigned consecutive index numbers starting one (1) greater than the data file number.

On a successful open when a differently named file matches the file ID of an open file, the error return will be NO_ERROR (0) but sysiocod will be set to MFID_COD (-586). If the files are detected to actually be different, then the file ID is changed as discussed above and sysiocod is not set to MFID_COD.

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

Example

extern IFIL     myfile;

       COUNT    retval;

if (retval = InitISAM(6,7,4))

    printf("\nCould not close files. Error %d.", retval);

else {

    if (CreateIFile(&myfile))

        printf( "\nCould not create %s (%d,%d)\n", 

               myfile.pfilnam, isam_err, isam_fil );

    else if (CloseIFile(&myfile))

        printf("\nCould not close files.");

    if (OpenIFile(&myfile))

        printf("\nCould not open files.");

    else if (CloseIFile(&myfile))

        printf("\nCould not close files.");

    if (CloseISAM())

        printf("\nCould not close ISAM.");

}

Limitations

The index files will be numbered consecutively following the data file. See “File numbering” in the index for additional information.

See also

InitISAM(), CreateIFile(), CloseISAM(), OpenIFileXtd(), OpenFileWithResource(), GetIFile() and ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide, which describes the ISAM parameters.

OpenIFileXtd

Extended Incremental ISAM open.

Short Name

OPNIFILX()

Type

Extended ISAM function

Declaration

COUNT OpenIFileXtd(pIFIL ifilptr, cpTEXT dataextn,

                   cpTEXT indxextn, cpTEXT fileword)

Description

OpenIFileXtd() is a variation of OpenIFile() that permits the use of the FairCom Server’s security system. This section expands on the description of OpenIFile().

dataextn and indxextn point to buffers specifying the data and index file name extensions, respectively. The extensions are 8-byte ASCIIZ (NULL terminated ASCII) strings. If the pointers are NULL, the default extension will be used: .dat for data files and .idx for index files. For files with no extension, pass a pointer to a buffer that contains only blanks terminated by a NULL character.

fileword is an optional file password. If fileword is null then there will be no password for this file. If a password is established, every user will need to use the password to be able to open the file.

For more information on permission masks, group id’s, and file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.

Return

The following error codes may be seen in addition to those for OpenIFile():

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

See also

InitISAM(), OpenIFile(), CloseISAM()

OpenISAM

Open all the ISAM files.

Short Name

OPNISAM()

Type

ISAM function

Declaration

COUNT OpenISAM(pTEXT filnam) 

Description

OpenISAM() opens the parameter file, whose name is pointed to by filnam, and opens the data and index files specified in the parameter file. Application programs using the ISAM level functions must make a call to InitISAM() or OpenISAM() before any other c-tree functions are used. If any one of these three functions has been called, then CloseISAM() must be called before anyone of them can be invoked again. In part, this implies that no more than one ISAM parameter file may be active at one time. However, the incremental ISAM functions allow for more flexibility in file manipulations and are highly recommended.

Using virtual files, the parameter file may contain more files than available file descriptors. c-tree automatically manages the open and close of virtual files.

Although it is not recommended, it is possible to use incremental ISAM file opens and opens along with a parameter file. Increase the value of the second parameter in the parameter file, (idxs), by the total number of files used by the incremental routines. For example, if the incremental routines open two additional data files, each with five indexes, then the idxs parameter in the ISAM parameter file should be increased by 12.

Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.

Return

OpenISAM() returns an error code from the table below. On a successful open when a differently named file matches the file ID of an open file, the error return will be NO_ERROR (0) but sysiocod will be set to MFID_COD (-586). If the files are detected to actually be different, then the file ID is changed as discussed above and sysiocod is not set to MFID_COD.

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

Example

TEXT      isam_par[64];

printf("\nEnter ISAM parameter file name: ");

scanf("%63s",isam_par);

if (OpenISAM(isam_par))

    printf("\nCould not open ISAM.");

else   

    ProcessData()

if (CloseISAM())

    printf("\nCould not close ISAM.");

Limitations

It is not possible to open some of the files specified in the parameter file and create others. They must all be created by CreateISAM(). However, the incremental ISAM functions permit on the fly opening and closing of ISAM files. If you are adding a new index file to an established set of ISAM files, you should:

• Update the parameter file to include the new index.
• Use the rebuild utility to create and build the new index file. Respond no when asked to force rebuild.
• Call OpenISAM() to actually use the files.

See also

CloseISAM(), InitISAM(), CreateISAM(), CreateIFile(), OpenIFile(), OpenISAMXtd() and ISAM Parameters in the c-tree Programmer’s Reference Guide, which describes the parameter file contents.

OpenISAMContext

Opens (creates) an ISAM context.

Short Name

OPNICON()

Type

ISAM function

Declaration

COUNT OpenISAMContext(FILNO datno, FILNO keyno, COUNT contextid)

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

OpenISAMContext() returns a 2-byte integer (COUNT) which serves as the context ID. The context is maintained for the data file specified by datno. keyno is either a key for the data file or -1. If keyno is -1, then the context saves key images (values) for all the indexes associated with datno. If a specific key is specified with keyno, then the context only maintains the key value for the given index thereby conserving memory. Opening a context actually creates the context and then selects the context as the current context for the specified data file.

If contextid is passed in as “-1”, then the next available ID is assigned. If not passed as “-1”, then the value passed is taken as the desired context ID. Note that the context IDs do not have to be consecutive numbers, and both positive and negative values are allowed. However, -1 is not a legitimate value for a context ID. It is used to signify that c-tree should automatically assign the context number.

Note: FairCom DB has an internal hard limit of 65534 contexts.

To speed the location of contexts, a simple hashing scheme is used. The number of hash bins defaults to six (6) for each user. If a large number of contexts are to be maintained, then this default can be overridden as follows:

1. Server (non-BOUND) Applications: the configuration file can contain the keyword value pair:

   CONTEXT_HASH    <# of hash bins>

1. Bound Applications: Set the global unsigned integer ctconbins to a non-zero value before a call to initialize c-tree.

   UINT     ctconbins=12;

Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.

Return

If an error occurs, OpenISAMContext() returns -1 and isam_err is set; otherwise, OpenISAMContext() returns the context ID. If datno that does not correspond to an open data file, or keyno, (when not -1), does not correspond to an open index file associated with datno, isam_err is set to FMOD_ERR (48). If no IDs are available, or if the ID is already in use, isam_err is set to ECON_ERR (592).

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

Example

FILNO     datno1,datno2;              /* data file numbers   */

pVOID     bufptr1,bufptr2;            /* data buffer pointer */

COUNT     contextID_1,contextID_2,contextID_3,contextID_4; /* context ID's     */

OpenFileWithResource(datno1,"data1",ctSHARED);

OpenFileWithResource(datno2,"data2",ctSHARED);

FirstRecord(datno1 + 1,bufptr1);        /* move to first record for       *

                                         * datano1 using first key        */

contextID_1 = OpenISAMContext(datno1,-1,-1);

                    /* establish first context for datno1 at first record.  *

                     * keyno == -1 saves all key positions.                 */

FirstRecord(datno2 + 3,bufptr2);        /* move to first record for       *

                                         * datano2 using third key.       */

contextID_2 = OpenISAMContext(datno2, datno2 + 3,-1);

                        /* establish first context for datno2 at first record.  *

                         * keyno != -1 saves only key value for third key.      */

NextRecord(datno1 + 1,bufptr1);

NextRecord(datno1 + 1,bufptr1);          /* position datno1 at third       *

                                          * record by first key.           */

contextID_3 = OpenISAMContext(datno1,-1,-1);

       /* Third record by first key becomes the saved position for contextID_1 *

        * and contextID_3 becomes the active context for datno1.               */

NextRecord(datno1 + 2,bufptr1);  /* move from third record by first key,       *

                                  * to the  next record using the second key.  *

                                  * Call this record 4' (4 prime).             */

ChangeISAMContext(contextID_1); /* save record 4' as contextID_3. Make the     *

                                 * 3rd record the current position for datno1, *

                                 * and contextID_1 becomes the active  context *

                                 * for datno1. contextID_2 is still the active *

                                 * context for datno2.                         */

NextRecord(datno1 + 1,bufptr1); /* move to the 4th record by key 1 for datno1.*/

contextID_4 = OpenISAMContext(datno2,datno2 + 3,-1);

         /* saves 1st record by 3rd key as the contents of contextID_2 and     *

          * makes  contextID_4 the active context for datno2. Note that only   *

          * the third key image is stored for contextID_2 and contextID_4.     *

          * Therefore, when  selecting one of these contexts, it will not make *

          * sense to continue  traversing the file with a different key.       */  

See also

CloseISAMContext(), ChangeISAMContext()

OpenISAMXtd

Open all the ISAM files (extended version).

Short Name

OPNISAMX()

Type

Extended ISAM function

Declaration

COUNT OpenISAMXtd(pTEXT filnam, COUNT userprof, pTEXT userid,

                pTEXT userword, pTEXT servname, pTEXT fileword)

Description

OpenISAMXtd() is a variation of OpenISAM() that permits the use of the FairCom Server’s security system. This section expands on the description of OpenISAM().

• userprof is the user profile mask. It accepts the following values:
  • USERPRF_CLRCHK
  • USERPRF_LOCLIB
  • USERPRF_NDATA
  • USERPRF_NTKEY
  • USERPRF_PTHTMP
  • USERPRF_SAVENV
  • To use more than one value, OR the values together. Leave userprof set to zero to accept the defaults.
• userid is a pointer to a buffer containing the user ID. If userid is null, the user is assigned the ID of GUEST
• userword is a pointer to a buffer containing the user password.
• servname is a pointer to a Server name if you are going to use a Server name other than the default.
• fileword is an optional file password. If fileword is NULL then there will be no password for this file. If a password is established, every user will need to use the password to be able to open the file.

For more information on user id’s, user passwords, server names, and file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

Note: This function supports EXCLUSIVE file opens. For more information, please refer to Multi-user File Mode.

Return

The following error codes may be seen in addition to those for OpenISAM():

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

See also

InitISAM(), CreateISAM(), OpenISAM(), CloseISAM(), TransformKey(), GetCtTempFileName(), Begin()

PartitionAdmin

Partition file administration function.

Short Name

PTADMIN()

Type

Utility Function

Declaration

COUNT PartitionAdmin(FILNO datno, pVOID partdesc, LONG prawno, COUNT ptmode) 

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

PartitionAdmin() manages the partitions for datno, the file number for the host data file.

• partdesc may be either a pointer to a partition member data file name, a pointer to a key value (already transformed) representative of a partition member, or NULL.
• prawno may either be a “raw” partition number or its value is ignored.
• ptmode controls how to interpret partdesc and prawno as well as what action PartitionAdmin() should perform. ptmode is formed by OR-ing together the appropriate bit values from this list defined in ctport.h:

* The ptADMINnumber, ptADMINreuse, and ptADMINmulti options have NOT been implemented.

Note: All calls to PartitionAdmin() must specify exactly one way in which the partition will be identified (ptADMINname or ptADMINkey or ptADMINraw) and exactly one operation (for example., ptADMINpurge). If the ptmode parameter is not correctly formed, PTADMIN() will return BMOD_ERR (446, Bad mode: parameter out of range).

ptADMINstatus Option

If the ptADMINstatus option is used, then PartitionAdmin() returns either an error code (such as PLOW_ERR, 712, partition number is out of range - low) or NO_ERROR. If NO_ERROR is returned, then sysiocod contains the member status code from this list:

There is a subtlety here concerning a return of pmSTATUSnone in sysiocod, and some possible error codes returned by PTADMIN(). For example, a NO_ERROR return from PTADMIN(.........,ptADMINstatus) and sysiocod of pmSTATUSnone means that the partition number is in the current valid range, but that no such partition member has been created. A PLOW_ERR (712, out of range - low) return means that the partition number is out of the current valid range (whether or not such a partition was ever created).

A partition that is not in use or a partition that has been opened by the host (that is, not explicitly by the application), and which is not in use by another user, can be archived or purged.

Base Partition Number

The record add and update functions attempt to increase the base partition number of the partitioned file to the first current active partition number if one exists, or to the partition number that will hold the newly-added or updated record if no current active partition exists.

Return

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

Limitations

• A raw partition number must be 1 or greater.
• Encryption is not supported for partitioned files.
• To support transaction processing, a partitioned file must also support transaction-dependent file creation (TRANDEP).

Perform

Evaluate FairCom Server performance.

Short Name

PERFORM()

Type

Low-Level function

Declaration

COUNT Perform(COUNT status)  

Description

Perform() collects statistics on the number of times each c-tree function is called between PERFORM_ON and PERFORM_OFF. status is used to begin and end the evaluation process and to display the information collected. The values that can be used for status are:

Return

Always returns zero (NO_ERROR).

Example

Perform(PERFORM_ON);

GetRecord(...);

ReWriteRecord(...);

NextRecord(...);

/* additional c-tree functions */

Perform(PERFORM_OFF);

Perform(PERFORM_DUMP);

PermIIndex

Permanent Incremental Index creation.

Short Name

PRMIIDX()

Type

ISAM function

Declaration

COUNT PermIIndex(pIFIL ifilptr) 

Description

In a single call to PermIIndex(), your application program will:

• Add one or more additional indexes to an existing Incremental ISAM definition.
• Automatically load the indexes from the existing data (optional).
• Reference the new indexes with the standard ISAM level calls (e.g., the next AddRecord() call updates the new indexes along with the original indexes).
• If resources are enabled, automatically update the stored file definition to include the new indexes.

Note: This command requires an exclusive open of the file (see PRMIIDX82() for a shared mode version of this function). c-tree attempts to open the file in exclusive mode while allowing other connections read access. If the file is already open, c-tree flushes updates to disk and sets the update flag to zero to indicate that the file is in a clean, consistent state. If c-tree cannot open the file in exclusive mode, this operation fails.

When the Incremental file is closed via CloseIFile(), CloseISAM(), or CloseRFile(), the new indexes are automatically closed. The next Incremental open automatically includes the new indexes if OpenFileWithResource() is used, or if you have updated your Incremental structures and use OpenIFile().

The key values from the existing records will be added automatically. The additional indexes created and loaded by PermIIndex() reside in a separate index file, distinct from the index file(s) already in existence for the data file. There is no extended form of this function because the new indexes are automatically assigned the security information assigned to the existing indexes.

To disable the automatic load feature, set the dxtdsiz parameter of ifilptr to ctNO_IDX_BUILD. This creates the new index without loading key values into it. This feature allows PermIIndex() to be followed by UpdateConditionalIndex(), limiting the keys the index loads to those that meet the specified condition. Once the condition is in place, call RebuildIIndex() to fill the index. Do not close the files between PermIIndex() and RebuildIIndex().

ifilptr points to a new IFIL structure in which:

• dfilno contains the file number of the underlying Incremental data file.
• ix points to the new index definitions.
• tfilno is -1 if you wish the index file number to be assigned, or tfilno is set to the first desired index number.
• dnumidx is the number of index files to create.

Note: The underlying data file is not determined by the pfilnam member of the new IFIL structure. dfilno specifies the data file involved.

The IFIL file name and location enhancement automatically locates index files created by PermIIndex() or TempIIndexXtd() in the same directory as the associated data file. With PermIIndex() only, it also allows the IFIL entry for the index file to have the same directory as the associated data file, even if the data file is not in its original directory. To activate this feature, the index file name in the aidxnam parameter of ifilptr should be in the form:

+index_name   

By placing a plus sign,‘+’s the first character of the index name, the new index automatically “follows” the data file, i.e., it is created in the same directory as the data file. c-tree can open files via OpenFileWithResource() in a directory different from the directory in the file’s internal IFIL resource. When this happens, OpenFileWithResource() expects any index that had the same directory as the data file to be in the new directory.

The plus sign is not part of the actual file name used to create the index. Mirrored file name components use this option independently. Only the name components beginning with the plus sign invoke this feature. For example, the following would all be “legal” for aidxnam entries:

+primary_index|+mirror_index

+primary_index|mirror_index

 primary_index|+mirror_index

Adding an Index to an Existing File

FairCom has always supported adding an additional index to an existing file if the index is placed in a new physical file. If you need to add an additional index to an existing file and want to store the new index in the same physical file, PermIIndex() is the preferred method. This support is available starting in V11.2.

Return

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

Example

pIFIL     newindex;

FILNO     filno;

VRLEN     bufsiz;

filno = OpenFileWithResource(-1,"test", (ctEXCLUSIVE | ctPERMANENT));

if (filno < 0) {

    printf("\nOpen  failed");

    exit(1);

}

bufsiz = GetIFile(filno, 0, newindex);

newindex = (pIFIL) mballc(1, bufsiz);

GetIFile(filno, bufsiz, newindex);

newindex->dfilno = filno;

newindex->tfilno = -1;

newindex->dnumidx = 1;

newindex->aidxnam = "testnew";

if (PermIIndex(newindex))

    printf("\nAdding Index failed (%d %d)",isam_err,isam_fil);

Limitations

The Incremental ISAM files must be opened ctEXCLUSIVE.

See also

TempIIndexXtd(), DropIndex(), RebuildIIndex(), UpdateConditionalIndex(), AddRecord(), CloseIFile(), CloseISAM(), CloseRFile(), OpenFileWithResource(), OpenIFile(), PRMIIDX82()

PermIIndex8

Permanent 8-byte Incremental Index creation.

Short Name

PRMIIDX8()

Type

Extended 8-byte ISAM function

Declaration

COUNT PermIIndex8(pIFIL ifilptr, pXCREblk pxcreblk)

Description

PermIIndex()8 is a variation of PermIIndex() that permits the use of huge file support. This section expands on the description of PermIIndex().

pxcreblk points to an array of XCREblk structures, the extended creation block, one for each physical file in ifilptr. For more information, review Huge File Support in the c-tree Programmer’s Reference Guide.

Return

PermIIndex8() returns error codes similar to those for PermIIndex(). See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Limitations

PermIIndex8() and TempIIndexXtd8() support ctTRANDEP creates. Without ctTRANDEP creates, these routines cannot be called within a transaction. With ctTRANDEP creates, they MUST be called within a transaction.

See also

TempIIndexXtd(), RebuildIIndex(), PermIIndex(), UpdateConditionalIndex(), PRMIIDX82

PositionSet

Establish current ISAM record as current position in set.

Short Name

MIDSET()

Type

ISAM function

Declaration

COUNT PositionSet(FILNO keyno, pVOID recptr, COUNT siglen)

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

PositionSet extracts the key value for index keyno from the current ISAM record, and defines a set based on the first siglen bytes of this key value. This permits an application to “jump” into the middle of a set using the current ISAM record to define the set. A successful PositionSet() defines a current key value set, and subsequent calls to NextInSet() and PreviousInSet() will read the other records in the set (i.e., those records whose keys also match the first siglen bytes of keyno). If an error occurs or no key value matches the target, no key value set is defined.

Notice that you do not directly identify the data file number involved. The ISAM parameter file described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contains the correspondence between the index file number and the associated data file.

Return

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

Example

FILNO        keyfil;

TEXT         target[24],recbuf[320];

printf("\nEnter set value:");

scanf("%23s",target);

LockISAM(ctENABLE);

FirstInSet(keyfil,target,recbuf,strlen(target));

while (isam_err == NO_ERROR) {

    process_data();

    LockISAM(ctRESET);

    while (NextInSet(keyfil,recbuf) == DLOK_ERR) {

        LockISAM(ctSUSPEND);

        PositionSet(keyfil,recbuf,strlen(target));

        LockISAM(ctRESTORE);

    }

}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

NextInSet(), PreviousInSet(), LastInSet(), FirstInSet(), ChangeSet(), TransformKey()

PositionVSet

Establish current variable-length ISAM record as current position in set.

Short Name

MIDVSET()

Type

ISAM function

Declaration

COUNT PositionVSet(FILNO keyno, pVOID recptr, COUNT siglen, pVRLEN plen)

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

PositionVSet() is the same as its fixed-length counter-part, PositionSet(), except that one argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for PositionSet() for additional important information.

Return

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

See also

PositionSet(), NextInVSet(), PreviousInVSet(), LastInVSet(), FirstInVSet(), ChangeSet(), TransformKey()

PreviousInRange

Read the previous record in a range

Short Name

PRVRNG()

Type

ISAM function

Declaration

COUNT PreviousInRange(COUNT keyval, pVOID recptr)  

Description

Read the previous data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful PreviousInRange() defines a current key value set, and subsequent calls to NextInRange() or PreviousInRange() will read the other records in the range.

If the data file has variable-length records, only the fixed-length portion of the record is actually read. You can use ReReadVRecord() to retrieve the whole record, including the variable-length portion. You can use PreviousInVRange() to read the whole variable-length record with one function call.

Return

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

See also

AllocateRange(), EstimateRange(), FirstInRange(), FirstInVRange(), FreeRange(), LastInRange(), LastInVRange(), NextInRange(), NextInVRange(), PreviousInVRange()

PreviousInSet

Read the previous data record in the current key value set.

Short Name

PRVSET()

Type

ISAM function

Declaration

COUNT PreviousInSet(FILNO keyno, pVOID recptr)  

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

PreviousInSet() reads the previous data record in the set of data records whose keys match the set created by an earlier set function call. If successful, this record becomes the current ISAM record for the associated data file. If an error occurs or no previous record exists in the set, the current ISAM record is not updated, and the current key value set becomes undefined.

If the data file has variable-length records, only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to PreviousInSet(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

Notice that you do not directly identify the data file number involved. The ISAM parameter file described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contains the correspondence between the index file number and the associated data file.

Return

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

Example

FILNO        keyfil;

TEXT         target[24],recbuf[320];

printf("\nEnter set value:");

scanf("%23s",target);

LastInSet(keyfil,target,recbuf,strlen(target));

while (isam_err == NO_ERROR) {

   process_data();

   PreviousInSet(keyfil,recbuf);

}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

FirstInSet(), NextInSet(), LastInSet(), PositionSet(), ChangeSet(), CreateIFile(), ReReadVRecord(), TransformKey()

PreviousInVRange

Read the previous record in a range

Short Name

PRVVRNG()

Type

ISAM function

Declaration

COUNT PreviousInVRange(COUNT keyval, pVOID recptr, pVRLEN plen)  

Description

Read the previous data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful PreviousInVRange() defines a current key value set, and subsequent calls to NextInVRange() or PreviousInVRange() will read the other records in the range.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Return

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

See also

AllocateRange(), EstimateRange(), FirstInRange(), FirstInVRange(), FreeRange(), LastInRange(), LastInVRange(), NextInRange(), NextInVRange(), PreviousInRange()

PreviousInVSet

Read the previous variable-length data record in the set defined by target.

Short Name

PRVVSET()

Type

ISAM function

Declaration

COUNT PreviousInVSet(FILNO filno, pVOID recptr, pVRLEN plen)

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

PreviousInVSet() is identical to it’s fixed-length counterpart, PreviousInSet(), except that it reads the previous variable-length data record in the set defined by target and siglen. If successful, this record becomes the current ISAM record for the associated data file.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for PreviousInSet() for additional important information.

Return

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

See also

PreviousInSet(), FirstInVSet(), NextInVSet(), TransformKey()

PreviousKey

Find the previous entry in an index file.

Short Name

PRVKEY()

Type

Low-Level index file function

Declaration

LONG PreviousKey(FILNO keyno, pVOID idxval) 

Description

PreviousKey() searches index file keyno for the previous entry in the index. If successful, it copies the index entry into the space pointed to by idxval. PreviousKey() fails if it is the first index search routine called after the index is opened, or if the entry found before PreviousKey() is the first entry in the index. Repeated PreviousKey() calls move through the index in descending key value order.

Return

PreviousKey() returns the data record position associated with the previous entry in the index file. If the index is empty or an error is detected, PreviousKey() returns zero. When PreviousKey() returns zero, check uerr_cod: if uerr_cod is also zero, then the index is empty; otherwise, an error condition was detected. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

LONG      recbyt;

TEXT      idxval[10];  /* 10 byte key, no duplicates */

FILNO     keyno;

recbyt = LastKey(keyno,idxval);

while (recbyt) {

    printf("\nIndex Entry %.10s found in record #%ld", idxval,recbyt);

    recbyt = PreviousKey(keyno,idxval);

}

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered. Use GetCtFileInfo() to determine the key length.

The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments. Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) in the c-tree Programmer’s Reference Guide contains suggestions for manipulating the key value.

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

ctSETHGH(), ctGETHGH(), GetKey(), GetCtFileInfo(), FirstKey(), NextKey()

PreviousRecord

Read the preceding data record.

Short Name

PRVREC()

Type

ISAM function

Declaration

COUNT PreviousRecord(FILNO filno, pVOID recptr)

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

PreviousRecord() retrieves the previous data record found. If filno designates an index file, PreviousRecord() reads the previous active data record based on the key sequential order of entries in index file number filno. If filno designates a data file, PreviousRecord() reads the previous active data record, in physical sequential order. If successful, the previous record becomes the current ISAM record for the associated data file. If an error occurs or there are no entries, the current ISAM record is not updated.

Note: filno cannot be a data file number, and the error FMOD_ERR (48) will be returned, if any of the following are true:

• The data file is set up for variable-length records;
• The data file is a member of a Superfile;
• The data file has Resources enabled (the default state).

If the data file has variable-length records, only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to PreviousRecord(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

If PreviousRecord() is called with an index number, the data file number involved is not directly described. The ISAM parameters described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contain the correspondence between the index number and the associated data file.

PreviousRecord() can move sequentially through a data file based on one index then switch to another index. For example, moving through an inventory file in part number order before switching to part name order by changing the keyno parameter in the PreviousRecord() call.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

Return

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

Example

FILNO     acct_idx, test;

TEXT      recbuf[320];

test = LastRecord(acct_idx,recbuf);

while (test == NO_ERROR) {

    post_interest(recbuf);

    test = PreviousRecord(acct_idx,recbuf);

}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

FirstRecord(), NextRecord(), LastRecord(), CreateIFile(), ReReadVRecord().

PreviousVRecord

Read the previous variable-length data record in the data file.

Short Name

PRVVREC()

Type

ISAM function

Declaration

COUNT PreviousVRecord(FILNO filno, pVOID recptr, pVRLEN plen)

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

PreviousVRecord() is identical to it’s fixed-length counterpart, PreviousRecord(), except that it reads the previous variable-length data record. If successful, this record becomes the current ISAM record for the associated data file.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for PreviousRecord() for additional important information.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

Return

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

See also

PreviousRecord(), NextVRecord(), TransformKey()

PRMIIDX82

Create an index with the data file open in shared mode.

Declaration

CTERR PRMIIDX82(pIFIL ifilptr, pXCREblk pxcreblk, ULONG numberOfExtendedCreateBlocks, ctINDEX_ATTRIBUTES *pIndexAttributes);

Description

Beginning with V13, a condition can be added to the index when creating the index with the data file open in shared mode. Use this function to add a permanent index to a data file. The function accepts ifilptr and pxcreblk parameters that are identical in usage to PRMIIDX8(). The two additional parameters indicate the number of extended create blocks in the pxcreblk array and provide the desired index attributes:

The ctINDEX_ATTRIBUTES structure contains a version so that it can be modified in future versions to support passing additional index attributes. Version 1 of the structure is defined as follows:

/* index attributes for PRMIIDX82 */

typedef struct ctIndexAttributes_t {

ULONG structureVersion;

ULONG numberOfExtendedKeySegments;

ULONG numberOfIndexConditions;

pctKSEGDEF *extendedKeySegments;

cpTEXT *indexConditions;

} ctINDEX_ATTRIBUTES;

To use the index attributes structure, set structureVersion to ctINDEX_ATTRIBUTES_VERS_V01, set numberOfExtendedKeySegments to the number of extended key segments in the extendedKeySegments array (specify zero and NULL if no extended key segments are supplied), and set numberOfIndexConditions to the number of index conditions in the indexConditions array (specify zero and NULL if no index conditions are specified).

• extendedKeySegments is an array of pointers to key segment definitions, one for each key segment definition (ISEG structure element) specified in the array of IIDX structures specified in the ifilptr parameter. If a given key segment has no extended key segment definition, specify NULL for that array element.
• indexConditions is an array of pointers to index conditions, one for each index definition (IIDX structure element) specified in the ifilptr parameter. If a given index has no index condition, specify NULL for that array element.

Return Values

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

putcndxmem

Frees memory from expression parser tree.

Declaration

VOID putcndxmem( pVOID objptr );

Description

The macros getcndxmem() and putcndxmem(), used to get and put memory required to process and store conditional index expressions, allow the proper memory allocation routines to be used on the client and server sides. (These substitute for the internal mballc() and mbfree() calls.)

Example

/* Allocate a run-time stack for the expression analyzer (first time only). */

if (!ctcidxStk)  {

    ctcidxStk = (pVOID) getcndxmem(CNDX_MAX_STACK * ctSIZE(PLEAF));

    if (!ctcidxStk)  {

        printf("Unable to allocate memory for run-time stack.\n");

        ctrt_exit(1);

    }

}

if (ctcidxStk)

putcndxmem(ctcidxStk);

See also

cndxeval(), cndxfree(), cndxparse(), ctparsedoda(), cndxrun(), putcndxmem()

PutDODA

Store information from a record schema as a resource.

Short Name

PUTDODA()

Type

Low-Level data file resource function

Declaration

COUNT PUTDODA(FILNO datno, pDATOBJ doda, UCOUNT numfld)

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

PutDODA() assigns the contents of a data object definition array (DODA) to data file. The DODA is converted into a schema map and schema names as described in Record Schemas of the c-tree Programmer’s Reference Guide.

• datno is the data file number to assign the DODA to.
• doda points to the beginning of the DODA (i.e., the array of DATOBJ’s). The DATOBJ is discussed in Record Schemas of the c-tree Programmer’s Reference Guide.
• The numfld parameter indicates how many data fields (number of elements) are contained in the DODA.

Return

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

Limitations

The file must be opened in ctEXCLUSIVE mode.

Resources must be enabled for the data file.

See also

GetDODA()

PutIFile

Place an IFIL structure into a data file resource record.

Short Name

PUTIFIL()

Type

ISAM resource function

Declaration

VRLEN PutIFile(pIFIL ifilptr) 

Description

Place a new, or replace an existing file definition (consisting of IFIL, IIDX and ISEG structures) into the resource record of the data file pointed to by ifilptr.

Normally, the IFIL is placed in the file during CreateIFile(). PutIFile() allows this resource to be updated or a new IFIL structure to be placed in files created with other functions.

Return

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

Refer to the following sections for additional details regarding IFIL structures.

IFIL Structure

IIDX Structure

ISEG Structure

Example

IFIL vc_dat = {

. . . .

};   /* IFIL structure to be placed in resource record */

VRLEN ret=0;  /* function return work variable */

if (ret=PutIFile(&vc_dat))

    printf("\nError during PUTIFIL(), error = %d",ret);

else

    printf("\nSuccessful PUTIFIL()!");

Limitations

The file must be closed prior to calling this function. PutIFile() opens the file in ctEXCLUSIVE mode and closes the file upon return.

See also

OpenFileWithResource(), GetIFile(), CreateIFile(), PutIFileXtd()

PutIFileXtd

Place an IFIL structure into a data file resource record. (Extended version)

Short Name

PUTIFILX()

Type

Extended ISAM function

Declaration

COUNT PutIFileXtd(pIFIL ifilptr, cpTEXT dataextn,

                  cpTEXT indxextn, cpTEXT fileword)

Description

PutIFileXtd() is a variation of PutIFile() that permits the use of the FairCom Server’s security system. This section expands on the description of PutIFile().

fileword is an optional file password. If fileword is null then there will be no password for this file. If a password is established, every user will need to use the password to be able to open the file. For more information on file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

dataextn and indxextn are pointers to buffers specifying optional data and index file name extensions, respectively. The extensions can be 8-byte ASCIIZ (NULL terminated ASCII) strings. If they are NULL pointers, the default extension will be used: .dat for data files and .idx for index files. For files with no extension, pass a pointer to a buffer that contains only blanks terminated by a null character. Do not set both extensions to blanks, since the index and data file names must be distinct.

Return

The following error code may be seen in addition to those for PutIFile():

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

Limitations

The file must be closed prior to calling this function. PutIFile() opens the file in ctEXCLUSIVE mode and closes the file upon return.

See also

PutIFile()

PutIFileXtd8

Put an IFIL structure into a data file resource record. Extended 8-byte version.

Short Name

PUTIFILX8()

Type

Extended 8-byte ISAM Function

Declaration

COUNT PutIFileXtd8(pIFIL ifilptr, cpTEXT dataextn,

          cpTEXT indxextn, cpTEXT fileword, pXCREblk pxcreblk) 

Description

PutIFileXtd8() extends PutIFileXtd() in that it can be used on an open file. It accepts a pointer to an extended file creation block, pxcreblk, however, does not currently use that information and NULL should be passed in.

Return

The following three points will help users avoid any error when using this function:

• The file must be opened in exclusive mode.
• The tfilno member of the IFIL structure must be set to the current file number.
• The xcreblk structure must be allocated and its splval member must be set to ctFILEOPENED constant value.

See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

IFIL      vc_dat = {

. . . .

};   /* IFIL structure to be placed in resource record */

COUNT     ret=0;  /* function return work variable */

pTEXT     fileword;

getfileword(&fileword);

if (ret = PutIFileXtd8(&vc_dat, NULL, NULL, fileword, NULL))

    printf("\nError during PUTIFILX8, error = %d",ret);

else

    printf("\nSuccessful PUTIFILX8!");

See also

PutIFile(), PutIFileXtd()

PutXtdKeySegmentDef

Defines an extended key segment for a Server, an application, a data file, an index file, or a particular index segment.

Short Name

PUTKSEGDEF()

Type

ISAM Data Definition

Declaration

NINT  PutXtdKeySegmentDef(FILNO filno, NINT segno, pctKSEGDEF pkdef) 

Description

PutXtdKeySegmentDef() defines an extended key segment for a Server, an application, a data file, an index file, or a particular index segment. The pkdef parameter points to a definition to be created in a call to PutXtdKeySegmentDef(). The filno and segno parameters determine where the definition is to be stored, as follows:

Return

PutXtdKeySegmentDef() returns a handle for the definition if successful.

PutXtdKeySegmentDef() returns a negative value upon error, where the absolute value of the return value is the error code. The most common errors are shown below. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

See the API example in the chapter titled “Unicode Support”.

See also

AddRecord(), AddVRecord(), OpenIFile(), PutXtdKeySegmentDef(), GetXtdKeySegmentDef(), TransformXtdSegment()

QuietCtree

Temporarily suspends operation of the FairCom Server for specific files/actions.

Declaration

NINT QuietCtree( pTEXT filespec, LONG timeoutSEC, LONG action )

Short Name

ctQUIET()

Description

Overview

A connection can call ctQuiet() to start quiescing the database. It can set action code options to block some or all activities, such as new file opens, new logins, new transactions, and all APIs except ctQuiet(). It can call this function multiple times to unblock some or all of the previously blocked activities, such as allow new logins but not new transactions.

The typical flow is to call ctQuiet() to block all new activity. When ctQuiet() returns, the app calls it again to flush all files. When ctQuiet() returns, the app performs some action like taking a snapshot of all the files for a backup. Then lastly, the app calls ctQuiet() again to unblock everything, which returns the database back to normal.

ctQuiet() supports various types of actions related to pausing system activity. This allows, for example, a clean filesystem level copy of data and index files. External hardware snapshots are also possible when available. Placing the files in a "closed" and "clean" (that is, flushed) state allows quick recovery from these backups. Unflushed files can also be copied, and if the transaction logs are included, a server can bring the files to a current consistent state during automatic recovery.

When you quiesce the server, as long as the connection that quiesced the server remains connected, all other connections are blocked. Only if that connection goes away do we allow the ADMIN user to logon again and undo the quiesce.

When connecting to a quieted server with the intent to remove the quiet state when the original caller of ctQuiet() has disconnected, you must set the InitISAMXtd() user profile mask (userprof parameter) to USERPRF_ADMSPCL. Here is an example:

INTISAMX(bufs, file, 0,128,0,0,USERPRF_ADMSPCL,admnuser,admnword,srv_name)

Note the command-line utility ctquiet (ctquiet - Quiesce FairCom DB Utility, ctquiet Utility) sets the user profile mask (userprof parameter) to USERPRF_ADMSPCL when the -x switch is used, so this is another method for waking up the server when the quiescing client has been abandoned.

QuietCtree() returns NSUP_ERR (454) on those servers where this feature is not enabled.

• filespec is currently ignored (file-specific quiet operations are not currently supported).
• timeoutSEC specifies the time in seconds to wait before aborting transactions prior to blocking.
• action is either a block or unblock code from the following tables:

Block Action Codes

Unblock Action codes

Other options can be passed into ctQUIET() for additional control. These values are OR-ed into the action parameter.

ctQUIET() Options

The following actions and options are combinations of the above actions for convenience.

The action codes for ctQUIET() are defined in ctport.h.

Note: Except for ctQTblockLogFiles, all references to files imply c-tree data and/or index files.

When the blocks are set, callers that hit the blocks sleep until the block is released and then continue with their API request, except when the caller’s transaction was aborted by QuietCtree(). If the transaction was aborted, then when the caller's block is released, the current API request returns with a QTAB_ERR (817). If the transaction was aborted but the caller has not made an API call since the transaction was aborted, then the next API call will return immediately with the QTAB_ERR. QTAB_ERR is returned to alert the caller that its current transaction has been aborted. Transactions are aborted by QuietCtree() only if ctQTnoActiveTran is part of the QuietCtree() request.

QuietCtree() is designed to permit multiple calls to achieve the desired results. When the final blocking attribute is removed by a call to QuietCtree(), QuietCtree() is completed which gives ups its interlocks on other QuietCtree()/ctFILBLK() calls and dynamic dumps.

A call to ctQUIET() with mode ctQTblockALL | ctQTflushAllFiles can be used to suspend all activity within FairCom DB and flush all files so that they have all updates written to disk and the update flag in the header of the files is reset, so that they can then be copied by an external process. However, this option forces a "no active transaction" state. This means that any transactions that are active when ctQUIET() is called are aborted.

A call to ctQUIET() with mode ctQTblockAPI can be used to suspend all activity on the FairCom Server while files remain open, potentially having updated data and index cache pages that have not been written to disk. In this mode, active transactions are simply suspended and they are resumed when ctQUIET() is called with mode ctQTunblockAPI. If you use this ctQUIET() mode and then copy the data and index files and the active transaction log files, you can then run automatic recovery on the files and you will have a point in time consistent copy of the file (where the point of time is the time the ctQUIET() successfully blocked all API calls: transactions that are pending as of that time are not included in the files).

Note: QuietCtree() cannot be called with a mix of ctQTblock and ctQTunblock action codes.

Quiet vs. Blocking

There is a subtle distinction between QuietCtree() and ctFILBLK(). QuietCtree() does not "physically" close files. This has particular implications on the Windows filesystem, as files are not allowed to be removed in this case as there is an open OS file handle still maintained. Compare to ctFILBLK() where files can be deleted or otherwise replaced while in the blocked state as the OS file handle may be released. Unix systems do not impose this restriction on files, thus, care should be taken in these environments to not replace or otherwise delete a file while in a Quiet state. Always use the file block API to physically replace a file.

Timeout Notes

The quiesce mode can be set to abandon the ctQUIET() call if transactions are still active after timeout period.

The ctQUIET() option ctQTnoActiveTran causes ctQUIET() to wait for the specified timeout interval for all active transactions to complete. As soon as all active transactions have completed, ctQUIET() continues putting the server into a quiesced state. But if any transactions remain active after the specified timeout interval, c-tree Server terminates those transactions.

The ctQTfailAfterTimeout mode changes this behavior so that when the specified timeout interval has passed the ctQUIET() call fails if any transactions remain active. To use this option, OR in the ctQTfailAfterTimeout mode to the action parameter that you pass to ctQUIET(). When ctQUIET() fails because this option is used and transactions remain active after the timeout period, it returns error code QTFA_ERR (1031).

It is possible for ctQUIET() to get into an abandoned state if the calling application (or c-tree utility ctquiet or ctadmn option 8) are terminated before c-tree is taken out of the quiesce state. When in an abandoned state any new client connections that are attempted will receive the QABN_ERR (error 898). Any existing connections that were waiting before the abandoned state occurs will continue to wait.

Example:

 NINT rc;

 if (!(rc = ctQUIET(NULL, 2, ctQTblockALL | ctQTflushAllFiles | ctQTfailAfterTimeout))) {

  printf(""Successfully quiesced server.\n"");

 } else {

  printf(""Error: Failed to quiesce server: %d\n"", rc);

 }

Return Values

Possible sysiocod Returns

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

Example

NINT quiesce()

{

    if (!QuietCtree( NULL, 1000, ctQTblockALL | ctQTflushAllFiles )) {

printf("Successful Quiesce.\n\n");

printf("It is now safe to perform sytem administrator duties.\n");

printf("Press RETURN once the backup is completed to resume the c-tree Server\n");

getchar();

if (rc = ctQUIET( NULL, 1000, ctQTunblockALL )) {

printf("Could not resume. Error: %d\n", rc);

}

    } else {

   printf("Could not quiesce\n");

    }

return(0);

}

See also

ctFILBLK()

ReadData

Read fixed-length data record.

Short Name

REDREC()

Type

Low-Level data file function

Declaration

COUNT ReadData(FILNO datno, LONG recbyt, pVOID recptr)

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

ReadData() reads the data record at byte position recbyt for data file datno into the buffer area pointed to by recptr. If datno refers to a variable-length file, ReadData() reads only the fixed-length portion into the buffer. Use ReReadVRecord() to read an entire variable-length record.

Return

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

Example

FILNO     datno,keyno;

TEXT      recptr[1024];

LONG      part_number;

scanf("%ld",&part_number);

if (ReadData(datno, GetKey(keyno, &part_number), recptr))

    printf("\nCould not retrieve record for part #%ld", part_number);

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

ctSETHGH(), ctGETHGH(), ReReadVRecord(), ReadIsamData(), WriteData()

ReadIsamData

ISAM read data at record position.

Short Name

REDIREC()

Type

ISAM function

Declaration

COUNT ReadIsamData(FILNO datno, LONG recbyt, pVOID recptr)

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

ReadIsamData() is the ISAM equivalent to the Low-Level function ReadData(). ReadIsamData() reads the data at record position recbyt for data file datno into the buffer pointed to by recptr. The significance of this function is that it decreases network traffic by eliminating the need to call ReadData() and SetRecord() to update the ISAM record buffers.

Return

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

Example

FILNO     datno;

LONG      recbyt[16];

TEXT      recptr[1024];

/* fill in an array of record positions */

FillRecordByteArray(recbyt);

/* read the 10th record in the array */

if (ReadIsamData(datno,recbyt[9],recptr))

    printf("\nCould not read 10th record, error = %d",

           isam_err);

else

    printf("\nSuccessful record read at offset %ld",recbyt[9]);

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

ctSETHGH(), ctGETHGH(), ReadData(), SetRecord()

ReadIsamVData

ISAM read variable-length data at record position.

Short Name

REDIVREC()

Type

ISAM function

Declaration

COUNT ReadIsamVData(FILNO datno, LONG recbyt, pVOID recptr, pVRLEN plen)

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

ReadIsamVData() reads a variable-length ISAM record and is the variable-length analog to ReadIsamData(). ReadIsamVData() reads the data at record position recbyt for data file datno into the buffer pointed to by recptr for plen bytes.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

ReadIsamVData() decreases network traffic by eliminating the need to make two separate function calls as follows:

• Retrieve the fixed-length portion of the record with an ISAM search routine, such as FirstRecord(),
• Call ReReadVRecord() to retrieve the variable-length component.

As with the other variable-length ISAM functions, ReadIsamVData() can read all or a portion of the variable-length record, potentially further reducing network traffic.

Return

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

Example

FILNO   datno;

LONG    recbyt[16];

TEXT    recptr[1024];

VRLEN   varlen;

/* fill in an array of record positions */

FillRecordByteArray(recbyt);

varlen = 64;   /* set plen to 64 bytes */

/* read *plen bytes of the 10th record in the array */

if (ReadIsamVData(datno,recbyt[9],recptr,&varlen))

    printf("\nCould not read 10th record, error = %d", isam_err);

else

    printf("\nSuccessful record read at offset %ld", recbyt[10]);

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

ctSETHGH(), ctGETHGH(), FirstRecord(), ReReadVRecord(), ReadData(), ReadIsamData().

ReadVData

Read variable-length data record.

Short Name

RDVREC()

Type

Low-Level variable-length record function

Declaration

COUNT ReadVData(FILNO datno, LONG recbyt, pVOID recptr, VRLEN varlen)

Description

ReadVData() reads the variable-length data record at byte position recbyt for data file datno into the buffer area pointed to by recptr. If varlen, the size of the buffer pointed to by recptr, is not large enough for the variable-length record, ReadVData() returns an error.

To ensure varlen is large enough, call VDataLength() before calling ReadVData(). VDataLength() returns the actual length of the record. If the existing buffer is not large enough, a new, larger buffer must be allocated before calling ReadVData().

Note: No check is actually made to be sure that the region pointed to by recptr is in fact as large as varlen indicates. It is up to the application to ensure that varlen accurately specifies the size of the area pointed to by recptr.

Return

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

Example

FILNO     datno, keyno;

VRLEN     cur_bufsiz, varlen;

pTEXT     recptr, calloc();

LONG      part_number, pntr;

scanf("%ld",&part_number);

if ((pntr = GetKey(keyno,&part_number)) != DRNZERO) {

    varlen = VDataLength(datno,pntr);

    if (varlen > cur_bufsiz) {

        free(recptr);

        recptr = calloc(1,varlen));

        cur_bufsiz = varlen;

    }

    if (ReadVData(datno,pntr,recptr,varlen))

        printf>("\nError #%d reading at %ld", uerr_cod, pntr);

}

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

ctSETHGH(), ctGETHGH(), ReReadVRecord(), VDataLength(), WriteVData()

RebuildIFile

Incremental ISAM rebuild.

Short Name

RBLIFIL()

Type

ISAM function

Declaration

COUNT RebuildIFile(pIFIL ifilptr)  

Description

RebuildIFile() rebuilds the data file and index files referenced by the IFIL structure pointed to by ifilptr. The file(s) to be rebuilt MUST be closed. RebuildIFile() opens the file(s), performs the rebuild, and closes the files upon completion.

RebuildIFile() does the following:

1. Resets the update corrupt flag updflg in the header of the data file.
2. Rebuilds the internal delete stack chain in fixed-length files and rebuilds the internal delete management index in variable-length files.
3. Removes the existing index file and builds an index, optimized for both size and speed, over the existing data file.
4. If a SRLSEG exists, RebuildIFile() finds the highest serial number in use and updates the file header with that value.

The user data is not affected in any way.

If you desire the files to be rebuilt in directories that are not specified until run-time, then ifilptr->pfilnam should not be finalized until run-time.

If RESOURCES are defined, and if ifilptr->tfilno is set to updateIFIL, RebuildIFile() automatically places the current IFIL array into a resource record in the data file - even if the data file was created without resources. After writing the IFIL structure, RebuildIFile() checks to see if the IIDX or ISEG arrays have changed. If changes are detected, the new structures replace any existing structures in the data file or will be added if no structures were previously present.

Note: Do not use RebuildIFile() to add indexes to an existing index, since the member headers are all at the front of the physical file with the key values afterward, and there is no slack space to add new member headers without recreating the physical index file. Therefore, first delete the physical index file and then do the rebuild if additional index members are added. You may also use PermIIndex() or TempIIndexXtd().

Rebuild times can be optimized by increasing the number of temporary sort files used. Increase the #define MAX_HANDLES found in ctsort.h from its default of 50 to a larger number up to the maximum of 255. The value to use is a function of the size of the index to be rebuilt and the number of available file handles and is best determined by performing timing tests on the target system. The temporary files created during rebuild are c-tree files. After changing ctsort.h, recompile the entire c-tree library, including removing the object files and library, and the rebuild application.

The path and/or drive of the temporary sort files can be modified in non-server mode with minor changes to ctsort.h and ctsort.c as follows:

Change approximately line 32 of ctsort.h from:

   #define WORK_DRIVE_OR_PATH ""

to:

   pTEXT WORK_DRIVE_OR_PATH;

Now declare WORK_DRIVE_OR_PATH as an ‘extern’ in the rebuild application and assign the desired path. See also the GetCtTempFileName() function description.

A second method for decreasing rebuild times is to link the rebuild application with a single-user c-tree library so that index caching will be used. To increase the size of the index cache, increase the number of index buffers (i.e., bufs parameter to InitISAM() or the first number of the parameter file initialization record). The index cache uses a hashing algorithm, therefore the larger the index cache the faster the rebuild will be. The size of the index cache can be calculated as follows:

memory(in bytes) = bufs *(sect * 128 + MAXLEN + 128)

MAXLEN, the maximum key length defined in ctopt2.h, defaults to 1024 bytes.

Option to skip initial data file scan

Normally the rebuild function starts by scanning the data file, checking for valid record marks if it is a variable-length data file, and checking that the logical and physical end of file values are correct. If the data file is known to be in a good state, it can be beneficial to skip this scan. OR the skipdatascanIFILoption bit into the tfilno field of the IFIL structure that you pass to the rebuild function. When using this and other options, remember to negate the tfilno value after you OR in the options. For example:

myifil.tfilno = -(redosrlIFILoption | skipdatascanIFILoption);

RBLIFIL(&myifil);

Automatic Duplicate Purge Logic

Prior to c-tree V6.7, rebuilding a file with duplicate key values on an index for which duplicates were not allowed terminated the rebuild completely or left the indexes in an inconsistent state. The index not supporting duplicates would not have an entry for the record while the other indexes would have an entry for the record. For consistency, this is still the default behavior, but details concerning the duplicate keys are sent to a temporary text file instead of the console. The name of the temporary file is sent to the console and to CTSTATUS.FCS. This information is not subject to the RB_OUTPUT define. It happens automatically and may not be disabled.

Records containing the unwanted duplicates are marked deleted, and none of the indexes will have an entry for this record. A copy of each deleted duplicate record is stored in a temporary file, which notes the position, length, and content of the record. CTSTATUS.FCS contains entries indicating how many duplicate keys were rejected, the name of the data file, the name of the temporary file, and a message indicating successful completion of the duplicate purge.

To implement the automatic duplicate purge behavior, where records with duplicate keys are purged from the data file and copied into a temporary file, one of the following two approaches is used:

1. Incremental ISAM Structure Support (IFIL): Rebuilding files defined by an Incremental ISAM Structure is typically accomplished with RebuildIFile(). Setting ifilptr->tfilno to purgeIFIL, which is defined in ctport.h, instigates the new auto-purge logic. It is permissible to set ifilptr->tfilno to purgeIFIL + updateIFIL so both behaviors can be achieved.
2. Parameter Files: For parameter files rebuilt with ctrbld.c, add #define ctRBLD_AUTO_PURGE when compiling ctrbld.c. This causes the parameter file rebuild to attempt automatic record purge if duplicate keys are rejected.

Note: If the record is longer than the operating system maximum unsigned integer (MUI), only MUI bytes are stored in the temporary file for this record. Typically, this will only be an issue with 16-bit systems where MUI will be 64K bytes.

To re-instate a deleted record, open the temporary file using c-tree open calls, retrieve the desired record, and insert it back into the data file.

If purgeIFIL is used and a binary stream file can be opened, duplicate keys and bad serial numbers are automatically purged from the indexes and the data records are deleted from the file. RebuildIFile() returns DUPJ_ERR (650) and the temporary stream file contains the deleted data records. This is an informational, not fatal, error.

If purgeIFIL is NOT used and an ASCII stream file can be opened, the duplicate keys and bad serial numbers are not added to the indexes, but the data records remain in the file. RebuildIFile() returns DUPL_ERR (652), and lists the offending keys and data records in the stream file. Before V6.7, RebuildIFile() returned NO_ERROR (0) under this condition. DUPL_ERR is an informational, not fatal, error.

Option Values

Prior to FairCom DB V9.5, several option values were defined such as updateIFIL, purgeIFIL, and badpartIFIL, that can be specified. These values are specified by adding them together. For example: myifil.tfilno = updateIFIL + purgeIFIL. A new approach simplifies checking of these options. The following option values are now specified in ctport.h:

#define updateIFILoption     0x0002

#define purgeIFILoption      0x0004

#define badpartIFILoption    0x0008

#define redosrlIFILoption    0x0010

These values can now be OR-ed together and, using the setIFILoptions() macro, assigned to the tfilno field of the IFIL structure passed to the compact or rebuild function. For example, to indicate that you want to assign new serial numbers, do the following:

myifil.tfilno = setIFILoptions(redosrlIFILoption);

RBLIFIL(&myifil);

If you want to also use more than one option when compacting or rebuilding a file, OR them in to the value. For example:

/* assign new serial numbers and update IFIL resource. */

myifil.tfilno = setIFILoptions(redosrlIFILoption | updateIFILoption);

RBLIFIL(&myifil);

If a stream file cannot be opened, RebuildIFile() returns either KDUP_ERR (2) or KSRL_ERR (605) when duplicate keys and/or bad serial numbers are encountered. Further, no more indexes are processed. That is, the rebuild does not run to completion as it does in the above two cases.

To rebuild a mirrored file, ensure the mirror is specified in ifilptr. RebuildIFile() copies the primary file to the mirrored name on successful completion.

badpartIFILoption (badpartIFIL)

The rebuild should reference the partition host. If the partition host can be opened, we attempt to open each member and rebuild only the members that get an error on open. If the partition host itself fails to open, we rebuild the host and all members.

Online Rebuild - new for V13

An online index rebuild has been implemented. It requires the target file to have the ctTRNLOG file mode (full transaction control).

To invoke an online rebuild, use onlineIFILoption:

myifil.tfilno = setIFILoptions(onlineIFILoption);

RBLIFIL(&myifil);

The file must be closed by the calling user, as for a normal rebuild, but may be open by OTHER users for update. The IFIL resource embedded in the file is used, not the IFIL definition provided by the caller. Behavior is undefined if the IFIL resource embedded in the file doesn't match the definition used to create the indexes.

NOTES: Online rebuild uses the dynamic dump and immediate restore, so it requires the ctrdmp binary exists in the server working directory. Only one dynamic dump may occur at a time, so the online rebuild will wait to begin if backups or other online rebuilds are in process. When the new index is ready, access to the file will be suspended while the index is replaced. Any active transactions that have updated this file will be aborted at this point. If an error occurs after this point, the index will need to be rebuilt in exclusive mode. The online rebuild is not supported for memory files, partition files, segmented files, or superfiles. Files with deferred indexes are not currently supported.

Return

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

Example

extern IFIL    customer;

       COUNT   retval;

main() {

    if (retval = InitISAM(10,10,16))

        printf("\nInitISAM error = %d",retval);

    if (!(RebuildIFile(&customer)))

        printf("\nSuccessful rebuild");

    else

        printf("\nRebuildIFile isam_err = %d",isam_err);

    CloseISAM();

}

Limitations

RebuildIFile() can be called from applications linked with the Standalone Multi-user (FPUTFGET) mode. RebuildIFile() opens the files in ctEXCLUSIVE mode, so no processes may access the file during rebuild. For performance reasons, single-user rebuilds are recommended.

To rebuild superfiles, call SuperfilePrepassXtd() prior to RebuildIFile().

See also

• Preventing Possible Data Loss with Compact & Rebuild Operations
• PermIIndex()
• TempIIndexXtd()
• GetCtTempFileName()
• RebuildIFileXtd()
• InitISAM()
• CompactIFile()
• SuperfilePrepassXtd()
• ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide (describes the ISAM parameters)

RebuildIFileXtd

Extended Incremental ISAM rebuild.

Short Name

RBLIFILX()

Type

Extended ISAM function

Declaration

COUNT RebuildIFileXtd(pIFIL ifilptr, cpTEXT dataextn, cpTEXT indxextn,

                      LONG permmask, cpTEXT groupid, cpTEXT fileword)

Description

RebuildIFileXtd() is a variation of RebuildIFile() that permits the use of the FairCom Server’s security system. This section expands on the description of RebuildIFile().

• dataextn and indxextn point to buffers specifying optional data and index file name extensions, respectively. The extensions are 8-byte ASCIIZ strings. If the pointers are NULL, the default extension are used: .dat for data files and .idx for index files. To use no extensions, pass a pointer to a buffer containing only blanks terminated by NULL. Do not set both extensions to blanks. The data and index files must be distinct.
• permmask is the permission mask assigned to this data file. It is formed by OR-ing the appropriate permission constants.
• groupid is a pointer to a buffer that contains the group id that this file is to be assigned to. The group id must be valid for the user that is creating the file. If groupid is null, the file will be assigned to the default group for the user.
• fileword is an optional file password. If fileword is null then there will be no password for this file. If a password is established, every user will need to use the password to be able to open the file.

For more information on permission masks, group id’s, and file passwords, review Security and Encryption (File Security and Encryption, /doc/ctreeplus/FileSecurityandEncryption.htm) in the c-tree Programmer’s Reference Guide.

Return

The following error code may be seen in addition to those for RebuildIFile():

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

See also

• Preventing Possible Data Loss with Compact & Rebuild Operations
• InitISAM()
• RebuildIFile()
• CloseISAM()

RebuildIFileXtd8

Extended 8-byte Incremental ISAM rebuild.

Short Name

RBLIFILX8()

Type

Extended 8-byte ISAM function

Declaration

  COUNT RebuildIFileXtd8(pIFIL ifilptr, cpTEXT dataextn,

          cpTEXT indxextn, LONG permmask, cpTEXT groupid,

          cpTEXT fileword, pXCREblk pxcreblk)

Description

RebuildIFileXtd8() is a variation of RebuildIFile() that permits the use of huge file support. This section expands on the description of RebuildIFile() and RebuildIFileXtd().

pxcreblk points to an array of XCREblk structures, the extended creation block, one for each physical file in ifilptr. For more information, review Huge File Support in the c-tree Programmer’s Reference Guide.

Return

RebuildIFileXtd8() returns error codes similar to those for RebuildIFile() and RebuildIFileXtd().

See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

See also

• Preventing Possible Data Loss with Compact & Rebuild Operations
• InitISAM()
• RebuildIFile()
• CloseISAM()
• RebuildIFileXtd()

RebuildIIndex

Rebuilds a single index.

Short Name

RBLIIDX()

Type

ISAM function

Declaration

COUNT RebuildIIndex(pIFIL ifilptr)  

Description

RebuildIIndex() rebuilds the indexes specified by ifilptr, starting with the file number specified in ifilptr->tfilno, producing new optimized indexes.

InitISAM() or InitISAMXtd() must be called prior to calling RebuildIIndex() and the file pointed to by ifilptr->tfilno must be open at the time of the call to RebuildIIndex().

RebuildIIndex() was created for use with PermIIndex() and TempIIndexXtd(). By default, both functions create and fill index files in one action. The ability to separate the index creation from the index build permits UpdateConditionalIndex() to set conditional expressions for the new indexes. If PermIIndex() is involved, the data file has its conditional index resource updated. If TempIIndexXtd() is involved, no permanent storage of the conditional index expression is made. The proper steps are:

• PermIIndex() or TempIIndexXtd() with ifilptr->dxtdsiz == ctNO_IDX_BUILD.
• UpdateConditionalIndex() for each new index with a conditional expression.
• RebuildIIndex() for each new index.

Note: Between a call to PermIIndex() or TempIIndexXtd() and a call to RebuildIIndex(), the newly created indexes have remained opened, and have not been closed or closed and re-opened.

Note: The setting for SORT_MEMORY <n> in ctsrvr.cfg should be increased when rebuilding large indexes for performance. The closer SORT_MEMORY is set to the size of the index, the faster the sort phase of the rebuild will be, regardless of the index size. (There is no additional benefit in setting SORT_MEMORY larger than the size of the index.)

Return

A zero (0) return indicates successful operation. A non-zero return indicates an error, check isam_err. The error returns are similar OpenCtFile() and RebuildIFile(). See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

extern IFIL    customer;

COUNT          retval; 

FILNO          filno;

COUNT          conditional;

main() {

    if (retval = InitISAM(10,10,16))

        printf("\nInitISAM error = %d",retval);

    filno = OpenFileWithResource(-1,"test", (ctEXCLUSIVE | ctPERMANENT));

    if (filno < 0) {

        printf("\nOpen  failed");

        exit(1);

    }

    customer->dfilno = filno

    customer->tfilno = -1

    if (conditional)

        customer->dxtdsiz = ctNO_IDX_BUILD;

    if (permIIndex(&customer))

        printf("\nAdding Index failed (%d %d)", isam_err, isam_fil);

    if (conditional && !(RebuildIIndex(&customer)))

        printf("\nSuccessful compact");

    else

        printf("\nRebuildIIndex isam_err = %d",isam_err);

    CloseISAM();

}

Limitations

RebuildIIndex() does not support superfiles, see Superfiles in the c-tree Programmer’s Reference Guide.

RebuildIIndex() is not recommended for existing indexes. If one index becomes corrupt, FairCom recommend rebuilding all indexes associated with the data file.

See also

InitISAM(), InitISAMXtd(), UpdateConditionalIndex(), OpenCtFile(), PermIIndex(), RebuildIFile(), TempIIndexXtd()

RegisterCtree

Register (establish) a c-tree instance.

Short Name

REGCTREE()

Type

Low-Level function

Declaration

COUNT RegisterCtree(pTEXT regid)  

Description

RegisterCtree() accepts a unique registration reference name, pointed to by regid, and establishes a unique c-tree instance. Each call allocates a new control block for the c-tree global variables. The registration reference name can be up to 31 bytes and a NULL terminator in length.

Return

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

Example

TEXT     inpbuf[32];   /* input buffer */

ctrt_printf("\nEnter Instance Name\n");

gets(inpbuf);

if (RegisterCtree(inpbuf))

{

    ctrt_printf("\nCould not register {%s} data base",inpbuf);

    ctlxmg_exit(2);

}

Limitations

File handles are not shared between instances. Virtual logic cannot close files in other instances.

See also

NextCtree(), SwitchCtree(), WhichCtree(), GetCtreePointer(), UnRegisterCtree()

ReleaseData

Release fixed-length data record for reuse.

Short Name

RETREC()

Type

Low-Level data file function

Declaration

COUNT ReleaseData(FILNO datno, LONG recbyt)

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

ReleaseData() adds record position recbyt to the chain of deleted records for fixed-length file datno. ReleaseData() should be called when a data record is no longer needed so that the space can be reused. Records returned by ReleaseData() are reused by NewData() before the data file is extended. ReleaseData() is automatically called by DeleteRecord().

Return

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

Example

FILNO     keyno,datno;

LONG      recbyt;

pTEXT     target;

if (recbyt = GetKey(keyno,target))

    if (DeleteKey(keyno,target,recbyt) == NO_ERROR)

        if (ReleaseData(datno,recbyt) == NO_ERROR)

            printf("\nSUCCESS.");

Limitations

ReleaseData() writes an 0xff byte and a 4-byte data record position starting at the first byte of the returned data record. Therefore, even if you only write ASCII information into the data records, ReleaseData() will place binary information into the beginning of deleted records.

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 Record Offsets Under Huge File Support.

See also

ctSETHGH(), ctGETHGH(), DeleteRecord(), LockCtData(), NewData()

ReleaseVData

Release variable-length data record for reuse.

Short Name

RETVREC()

Type

Low-Level data file function

Declaration

COUNT ReleaseVData(FILNO datno, LONG recbyt)

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

ReleaseVData() adds record position recbyt to the pool of deleted records for variable-length file datno. ReleaseVData() should be called when a data record is no longer needed so that the space can be reused. Records returned by ReleaseVData() are reused by NewVData() before the data file is extended. ReleaseVData() is automatically called by DeleteVRecord().

Return

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

Example

FILNO     keyno,datno;

LONG      recbyt;

pTEXT     target;

if (recbyt = GetKey(keyno,target))

    if (DeleteKey(keyno,target,recbyt) == NO_ERROR)

        if (ReleaseVData(datno,recbyt) == NO_ERROR)

            printf("\nSUCCESS.");

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

ctSETHGH(), ctGETHGH(), DeleteVRecord(), LockCtData(), NewVData()

RemoveAutoSysTimeFields

Removes the automatic system time definition from datno.

Type

ISAM Function

Declaration

NINT RemoveAutoSysTimeFields(FILNO datno);

Description

• datno - the data file number. 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

Return

NO_ERROR on success

RenameFile

Rename a file.

Short Name

ctRENFIL()

Type

Low-Level function

Declaration

COUNT RenameFile(FILNO filno, cpTEXT newname)  

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

RenameFile() renames a file that has been opened exclusively, meaning no other processes have the file open. RenameFile() is particularly useful for allowing a client application to rename a file controlled by a FairCom Server.

A superfile host cannot have any members open when it is renamed. A superfile member must have a correct matching host name in the newname string. For example, if the file being renamed is myhost!oldname, the newname string must be of the form “myhost!newname”. A file opened as part of a mirrored pair cannot be renamed.

Note: filno corresponds to the file to rename, and which must have been open exclusively. When renaming transaction logged files, it would be wise to include SKIP_MISSING_FILES YES in the FairCom Server configuration file since the log may contain references to the old file, which will not appear present during recovery.

Return

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

RenameIFile

Atomically rename some or all of the files associated with the IFIL structure.

Short Name

RENIFIL()

Type

ISAM function

Declaration

COUNT RenameIFile(pIFIL ifilptr)

Description

RenameIFile() atomically renames some or all of the files associated with the IFIL structure ifilptr, and updates the internal IFIL resource. ifilptr must point to a complete IFIL structure corresponding to an exclusively opened IFIL, with the names replaced by the new names. If the “new” name is the same as the original name, no renaming takes place for that file. The tfilno member of ifilptr must contain the file number of the data file associated with the IFIL. The dataextn and indxextn parameters can be used to modify the file name suffixes of the data and/or index files.

The data file’s IFIL resource will be updated under the following conditions:

• Resources have been enabled.
• The ctDISABLERES bit of the dfilmod member of ifilptr is not on.

When the IFIL resource is updated, then the following protocol is used:

• If an existing IFIL resource is found, then only the name fields are updated to reflect the renaming operations.
• If no existing IFIL resource is found, then the IFIL information passed into RenameIFile() is used in its entirety.

The IFIL structure passed into RenameIFile() must agree with both the physical files and the existing IFIL resource (if any) on the following points:

• The number of indexes.
• The key length and duplicate key status of each index.
• The specification of which indexes serve as a host index, keeping in mind that the aidxnam member of IIDX can create host indexes in addition to the “base” index.

If any of these characteristics do not match, RenameIFile() returns IAIX_ERR (608).

The first index in the IFIL may derive its name either from the data file name, or through a non-NULL aidxnam parameter. The new IFIL may change whether or not the aidxnam parameter is used for the first index. It cannot change whether aidxnam is used for any of the other indexes.

Return

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

Example

ISEG inv_seg = {

2,25,2

};

IIDX inv_idx = {

25,            /* key length            /

0,             / key type              /

0,             / dup off               /

0,             / null off              /

32,            / empty char            /

1,             / number of key segments*/

&inv_seg,      /* pointer to segment array*/

"Itemidx",      /* pointer to symbolic index name (r-tree)/

"invent.idx"    / optional index name (if this field is omitted the

                       default index name will be used.  The default is the

                       name supplied in the IFIL pfilnam with an extension

                       of "idx".)*/

};

IFIL inv_dat = {

"invent",       /* data file name ("dat" is always assumed)/

INVENTDAT,      / data file number     /

sizeof(invent), / data record length   /

4096,           / data extension size  /

1,              / data file mode       /

1,              / number of indices    /

4096,           / index extension size /

1,              / index file mode      /

&inv_idx,       / pointer to index array*/

"Delflag",      /* pointer to first field name (r-tree)/

"Buffer"        / pointer to last field name (r-tree)*/

};

#ifdef PROTOTYPE

VOID RenameTable(void)

#else

VOID RenameIFile1()

#endif

{

if (CloseIFile(&inv_dat))  /* Close file - file must be opened in exclusive mode */

printf("\nCloseIFile error  %d",isam_err);

inv_dat.dfilmod = 0;  /* set data file mode to exclusive for RenameIFile /

inv_dat.ifilmod = 0;  / set index file mode to exclusive for RenameIFile */

if  (OpenIFile(&inv_dat)) /* Open file now that the data file AND the index are set to exclusive */

printf("\nOpenIFile error  %d",isam_err);

cpybuf(inv_dat.pfilnam,"invent2",sizeof("invent2"));  /* copy in the new file name for the data file /

cpybuf(inv_idx.aidxnam,"invent2",sizeof("invent2"));  / copy in the new file name for the index file */

if (RenameIFile(&inv_dat))

printf("\nRenameIFile error  %d",isam_err);

}

Limitations

Transaction Logging

If the data file supports transaction logging and it does NOT have the ctTRANDEP or ctRSTRDEL extended file attributes, two criteria must be satisfied:

• No transaction can be active when RenameIFile() is called.
• The files cannot be updated between the exclusive open and the renaming call.

If either of the criteria is violated, RenameIFile() returns TEXS_ERR (70) or FCRP_ERR (14), respectively.

The renaming and optional updating of the IFIL resource are performed atomically under the control of a transaction automatically managed by c-tree.

Note: Transaction dependent files that have the ctTRANDEP or ctRSTRDEL extended file attributes MUST be within an active transaction to be renamed (the exact opposite of those that do not have these attributes).

Other Limitations

The IFIL structure passed into RenameIFile() must agree with both the physical files and the existing IFIL resource (if any) on the following points:

• The number of indexes.
• The key length and duplicate key status of each index.
• The specification of which indexes serve as a host index, keeping in mind that the aidxnam member of IIDX can create host indexes in addition to the “base” index.

See also

RenameIFileXtd(), RenameFile()

RenameIFileXtd

Rename ISAM files, extended version.

Short Name

RENIFILX()

Type

Extended ISAM function

Declaration

COUNT RenameIFileXtd(pIFIL ifilptr, cpTEXT dataextn, cpTEXT indxextn)

Description

RenameIFileXtd() is a variation of RenameIFile() permitting the file extensions to be changed. This section expands on the description of RenameIFile().

dataextn and indxextn point to buffers specifying the data and index file name extensions, respectively. The extensions are 8-byte ASCIIZ (NULL terminated ASCII) strings. If the pointers are NULL, the default extension will be used: .dat for data files and .idx for index files. For files with no extension, pass a pointer to a buffer that contains only blanks terminated by a NULL character.

Return

As with RenameIFile(). See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

ReplaceSavePoint

Maintain a moving savepoint within a transaction.

Short Name

SPCLSAV()

Type

Low-Level data file function.

Declaration

LONG SPCLSAV(VOID)

LONG ReplaceSavePoint(VOID)

Description

Call ReplaceSavePoint() to establish a savepoint while at the same time clearing the previous savepoint. ReplaceSavePoint() can be used to maintain a single “moving” savepoint within a transaction, which is useful for applications that may need to undo the work since the last savepoint but that never need to restore back to a point prior to the most recent savepoint. ReplaceSavePoint() provides this ability in the form of a single savepoint rather than multiple savepoints. Because ReplaceSavePoint() clears the previous savepoint, only the most recently established savepoint can be restored to. To restore to this savepoint, call TRANRST(-1).

Return

ReplaceSavePoint() returns a non-zero value to indicate success and a value of zero to indicate failure. If the return value is zero, uerr_cod contains the c-tree error code. If a client supports ReplaceSavePoint() but the server does not, the message:

Bad raw function #. fn: 231

will be placed in CTSTATUS.FCS and the c-tree error SFUN_ERR (170) will be returned. A RestoreSavePoint() cannot go back beyond a special save point set with SPCLSAV(). Further, ClearSavePoint() cannot clear a special save point. Either of these situations returns a SPCL_ERR (753).

Example

An example of the use of SPCLSAV() is within the c-treeSQL Server engine that must be able to undo the last update, and may involve a very large number of updates within a single transaction.

See also

SetSavePoint(), RestoreSavePoint()

ReReadRecord

Reread current ISAM record.

Short Name

RRDREC()

Type

ISAM function

Declaration

COUNT ReReadRecord(FILNO datno, pVOID recptr)

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

ReReadRecord() provides a simple way to reread the current ISAM record for fixed-length data records belonging to data file number datno. The record is read into the record buffer pointed to by recptr. Use ReReadVRecord() to reread the current ISAM record for a variable-length data file, unless only the fixed-length portion of the variable-length record is needed.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

Return

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

Example

  FILNO     datno;

  TEXT      buffer[256];

if (LockISAM(ctENABLE) || ReReadRecord(datno,buffer)) {

    printf("\nCould not reread record (%d)",isam_err);

    LockISAM(ctFREE);

    return(-1);

}

See also

ReReadVRecord(), the LOCK discussion of multi-user updates in Multi-User Concepts of the c-tree Programmer’s Reference Guide and the source code of CTIXMG.C.

ReReadVRecord

Reread variable-length ISAM data record.

Short Name

REDVREC()

Type

ISAM variable-length record function

Declaration

COUNT ReReadVRecord(FILNO datno,pVOID  recptr, VRLEN varlen)

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

ReReadVRecord() reads the current variable-length ISAM record for data file datno into the buffer area pointed to by recptr. If varlen, the size of the buffer pointed to by recptr, is not large enough for the variable-length record, ReReadVRecord() returns an error. ReReadVRecord() is used to read the entire variable-length record after the fixed-length portion is read via one of the fixed-length ISAM search routines (e.g., FirstInSet() instead of FirstInVSet()).

To ensure varlen is large enough, call VRecordLength() before calling ReReadVRecord(). VRecordLength() returns the actual length of the record. If the existing buffer is not large enough, allocate a new, larger buffer before calling ReReadVRecord().

Note: No check is actually made to be sure that the region pointed to by recptr is in fact as large as varlen indicates. It is up to the application to ensure that varlen accurately specifies the size of the area pointed to by recptr.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

See also Record Offsets Under Huge File Support.

Return

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

Example

FILNO     datno, keyno;

VRLEN     cur_bufsiz = 128, varlen;

pTEXT     recptr;

LONG      part_number;

recptr = calloc(1, cur_bufsiz));

if (FirstRecord(keyno, recptr)) == NO_ERROR) {

    if ((varlen = VRecordLength(datno)) > cur_bufsiz) {

        free(recptr);

        recptr = calloc(1,varlen));

        cur_bufsiz = varlen;

    }

    if (ReReadVRecord(datno,recptr,varlen))

        printf>("\nCould not reread record (%d).", isam_err);

}

See also

ReadVData(), ReReadRecord(), VRecordLength(), WriteVData()

resetIDfield

Resets the IDENTITY value assigned to a DODA field.

Declaration

  NINT resetIDfield(FILNO datno, LONG8 nxtval)

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

resetIDfield() resets an IDfield (IDENTITY) auto-numbering value for a numeric field in a record to a new specified value.

Where:

• datno is the data file number
• nxtval is the next value to be assigned on record addition

IDfield requires a DAR resource (Direct Access Resource) embedded in the file. The DAR is a specialized high-speed resource.

Return

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

Example

retval = resetIDfield(fileno, 1000);

if (retval) {

printf("\tERROR: Failed to reset ID field with error %d\n", retval);

}

Override IDENTITY Values

PUTHDR() using the ctIDfieldOverRide mode can turn on and off the ability to override the automatic IDfield values. The override is on a per user, per file basis. A nonzero hdrval turns on the override, and a zero hdrval restores the standard operation. When the override is on for a data file that supports an IDfield, then an add record operation does not fill-in the IDfield value. Whatever is passed in the record buffer is used for the IDfield. And a rewrite permits the IDfield value to change instead of generating the IDFL_CHG error. When the override is enabled, add record operations do not consume IDfield values.

See also

addIDfield(), delIDfield(), getIDfield(), wchIDfield(), IDfields - Extended support

ResetRecord

Updates the current ISAM record image buffers.

Short Name

UPDCURI()

Type

ISAM function

Declaration

COUNT ResetRecord(FILNO datno, 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

ResetRecord() manipulates the internal image of the current ISAM record kept by c-tree. An image is kept of the current ISAM record’s key structure and the current ISAM record’s file address. Whenever an ISAM function changes the current ISAM record, such as an AddRecord() or ReWriteRecord(), the original current ISAM record information is copied over to a secondary buffer before the primary buffer is changed. ResetRecord() can be used to manage these two buffers.

• datno specifies the ISAM file that is to be affected.
• mode can be one of several values;

Return

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

Example

FILNO     invfil;
 

struct invd {

  TEXT      delflg[4];

  LONG      part_no;

  LONG      on_hand;

  TEXT      part_name[60];

 } recbuf;

scanf("%ld %59s %ld",&recbuf.part_no,recbuf.part_name, &recbuf.on_hand);

recbuf.delflg = '\0'; /* clear delete flag */

if (AddRecord(invfil,&recbuf) )

    printf("\nAddRecord error %d in file %d", isam_err, isam_fil);

/* after adding record, restore current ISAM to previous point */

if (ResetRecord(invfil,SWTCURI) )

    printf("\nCannot reset, error %d",isam_err);

See also

AddRecord(), ReWriteRecord(), SetRecord().

RestoreSavePoint

Undo transaction operations back to a savepoint.

Short Name

TRANRST()

Type

Low-Level data file function

Declaration

COUNT RestoreSavePoint(COUNT savpnt)

Description

RestoreSavePoint() rolls the current transaction back to a previously defined savepoint created with a call to SetSavePoint(). savpnt is the savepoint to roll back to, and is the value returned by the call to SetSavePoint(). This allows you to back up in a transaction to a particular point, without having to Abort() or Commit() the entire transaction. For a complete discussion of this process please see Data Integrity in the c-tree Programmer’s Reference Guide.

savpnt can also be specified as a small negative number. -1 means go back to the most current savepoint. -2 means go back one more, etc.

RestoreSavePoint() also clears errors that have occurred since the savepoint.

Return

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();     /* RestoreSavePoint if can't add master rec          */

        dodetail();      /* process detail records                            */

    }

    if ( Commit(ctFREE) )

        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(), SetSavePoint(), TRANRDY()

ReWritePartialRecord

Rewrites a partial fixed or variable-length record.

Declaration

COUNT ReWritePartialRecord (FILNO datno, pVOID recptr, VRLEN varlen);

Short Name

RWTPREC()

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

ReWritePartialRecord() permits a fixed or variable-length record to be updated (i.e., rewritten) without passing back an entire record image. It is only necessary to pass enough bytes to hold the fields that have been modified. As a matter of good practice, varlen should end on a field boundary. This routine is especially effective for files whose records start with status fields and end with potentially large variable-length fields. For example, for a record containing ID fields and status fields followed by a very large binary field, say a graphic image, and one desired to only change a status or ID field, it is not necessary to pass the entire record to ReWritePartialRecord() rather, only the first few bytes at the beginning of the record. This significantly reduces network traffic and improves performance.

There is a subtle difference between ReWriteVRecord() and ReWritePartialRecord() called with a varlen equal to the original record length: ReWritePartialRecord() assumes a well formed record and will permit a variable-length field to be truncated by the end of the record. ReWriteVRecord() assumes it must avoid field truncation, and would return error SDAT_ERR (445) under the same circumstance. Practically, ReWritePartialRecord() should not be used to perform a full rewrite and good practices would not permit a truncated record image for ReWriteVRecord().

ReWritePartialRecord() can only be used to rewrite with a partial record image that is less than or equal to the full record image length. An attempt to grow the existing record results in error VMAX_ERR (140). When updating records with ReWritePartialRecord() the partial record image must contain enough data to enable c-tree to construct all key segments for all indexes of the data file. ReWriteVRecord().should be used instead of ReWritePartialRecord() if any variable-length field of the record was resized, even if the resulting record length remains unchanged.

Return

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

Example

If a data file has a record structure that contains three fields: id (CT_INT4), status (CT_INT4) and description (CT_STRING), and the id field is never updated, but the status or the description field may be updated, the ReWritePartialRecord() or ReWriteVRecord() may be used, depending on which field was updated.

Example

typedef struct

{

    LONG    id;

    LONG    status;

    TEXT    description[MAX_DESCRIPTION];

} MYRECORD;

NINT UpdateMyRecord(FILNO datno, LONG id,  LONG status, pTEXT description)

{

    NINT eRet;

    NINT partial = YES;

    VRLENvarlen = sizeof(LONG)*2;

    MYRECORD recbuf;

    /* set the fixed portion of the record */

    recbuf.id = id;

    recbuf.status  = status;

    /* check if we need to set the description field */

    if (description)

    {

        strcpy(recbuf.description, description);

        partial = NO;

        varlen += strlen(description) + 1;

    }

    /*  update/rewrite the record */

    if (partial)

        eRet = ReWritePartialRecord(datno, &recbuf, varlen);

    else

        eRet = ReWriteVRecord(datno, &recbuf, varlen);

    return eRet;

}
 

Limitations

An issue remains for how to perform the rewrite, partial or full, if the prior read of the record was itself partial (only the fixed portion of a variable-length record was read) and did not permit all of the internal key buffers to be updated. This issue remains in a pending state and you are advised to not attempt this sequence of operations. In addition, support for row level call callbacks has not been enabled for partitioned files during full or partial rewrites.

See also

ReWriteRecord(), ReWriteVRecord()

ReWriteRecord

Rewrite current fixed-length ISAM record.

Short Name

RWTREC()

Type

ISAM function

Declaration

COUNT ReWriteRecord(FILNO datno, pVOID recptr)

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

ReWriteRecord() allows changes to be made in the current ISAM record for fixed-length data records belonging to data file number datno. recptr should point to the updated version of the current ISAM record. ReWriteRecord() assumes that the current ISAM record is the original version. After successful completion of ReWriteRecord(), the updated version is now stored in the data file and all necessary changes to the key values associated with the updates are automatically made.

The typical ReWriteRecord() usage is:

• First, an ISAM retrieval function, (e.g., ReadISAMData(), GetRecord() or NextRecord()), reads the desired record, making it the current ISAM record.
• Updates are made to the record buffer.
• ReWriteRecord() rewrites the updated record, making the updated record the current ISAM record. If any of the key fields have been changed, the old key is removed from the appropriate indexes, and the new one is added.

Unlike c-tree version 4.3 and older, you do not have to be careful about making changes to the current record in your buffer. c-tree maintains its own copy of the current ISAM record key information and position.

Multi-user updates are more complex because of the possibility of either locking out the record for prolonged periods, or because of two users trying to update the same record at the same time. See Multi-User Concepts in the c-tree Programmer’s Reference Guide for a detailed discussion of multi-user updates.

ReWriteRecord() does not change the automatic serial number key segments, if any. If you want the serial number updated, delete the old record and add the updated record.

To make the old record the current ISAM record, so that NextRecord() will be performed relative to the position before the update, make the following call after successfully completing the record rewrite:

ResetRecord(datno,SWTCURI);

Return

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

Example

FILNO datno,keyno;

LONG  cust_no;

TEXT  buffer[128];

printf("\nEnter customer number: ");

scanf("%ld",&cust_no);

if (GetRecord(keyno,cust_no,buffer))  /* read current record */

    printf("\nCould not read customer record.");

else {

    update(buffer);           /* make your changes to buffer */

    if (ReWriteRecord(datno,buffer))

        printf("\nCould not rewrite customer record.");

    else

        printf("\nSuccessful update of customer record.");

}

Limitations

After a call to ReWriteRecord(), the current ISAM record is set to the new record. This may create a situation that you don’t expect when ReWriteRecord() is used inside a loop that steps over the data in key sequential order. If the key value is changed during the update, the current ISAM record position will skip to the new position, which may be before or after the original position. To avoid this situation, reset the current ISAM record after ReWriteRecord() using ResetRecord().

See also

ReadISAMData(), GetRecord(), NextRecord(), ResetRecord()

ReWriteVRecord

Rewrite current variable-length ISAM record.

Short Name

RWTVREC()

Type

ISAM function

Declaration

COUNT ReWriteVRecord(FILNO datno, pVOID recptr, VRLEN varlen)

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

ReWriteVRecord() allows changes to be made in the current variable-length ISAM record for data file number datno. recptr should point to the updated version of the current ISAM record, and varlen specifies the length of the updated version. ReWriteVRecord() assumes that the current ISAM record is the original version. After successful completion of ReWriteVRecord(), the updated version is now stored in the data file and all necessary changes to the key values associated with the updates are automatically made. If the updated version does not fit into the space available for the current record, it is moved to another location in the data file. All associated indexes are updated appropriately.

The typical ReWriteVRecord() usage is:

• First, an ISAM retrieval function, (e.g., GetRecord() or NextRecord()), reads the fixed portion of desired record, making it the current ISAM record.
• ReReadVRecord() reads the entire record into the buffer. This buffer now contains the entire current ISAM record.

Note: Variable-length retrieval functions, such as ReadISAMVData(), GetVRecord(), and NextVRecord(), accomplish these two steps in one function call.

• Updates are made to the record buffer.
• ReWriteVRecord() rewrites the updated record, making the updated record the current ISAM record. If any of the key fields have been changed, the old key is removed from the appropriate indexes, and the new one is added.

Multi-user updates are more complex because of the possibility of either locking out the record for prolonged periods, or because of two users trying to update the same record at the same time. See Multi-User Concepts in the c-tree Programmer’s Reference Guide for a detailed discussion of multi-user updates.

ReWriteVRecord() does not change the automatic serial number key segments, if any. To update the serial number, delete the old record and add the updated record.

To make the old record the current ISAM record, so that NextRecord() will be performed relative to the position before the update, make the following call after successfully completing the record rewrite:

ResetRecord(datno,SWTCURI);

Return

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

Example

FILNO     datno, keyno;

VRLEN     newlen, varlen;

LONG      cust_no;

TEXT      buffer[512];

printf("\nEnter customer number: ");

scanf("%ld",&cust_no);

if (GetRecord(keyno,cust_no,buffer)  /* read current record */

    || ReReadVRecord(datno,buffer,512))        

    printf("\nCould not read customer record.");

else {

    newlen = update(buffer);  /* make your changes to buffer */

    if (ReWriteVRecord(datno,buffer,newlen))

        printf("\nCould not rewrite customer record.");

    else

        printf("\nSuccessful update of customer record.");

}

Limitations

After a call to ReWriteVRecord(), the current ISAM record is set to the new record. This may create a situation that you don’t expect when ReWriteVRecord() is used inside a loop that steps over the data in key sequential order. If the key value is changed during the update, the current ISAM record position will skip to the new position, which may be before or after the original position. To avoid this situation, reset the current ISAM record after ReWriteVRecord() using ResetRecord().

See also

GetRecord(), NextRecord(), ReReadVRecord(), ReadISAMVData(), GetVRecord(),
NextVRecord(), ResetRecord()

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

GETCBRBLST

Returns the current rebuild callback state.

Declaration

ctCONV pctRBCBST ctDECL GETCBRBLST (VOID)

Description

Specific rebuild callback information can be passed back to the calling client via this structure. This is a useful feature that allows canceling a rebuild from the rebuild callback function. A call to this function returns a pointer to the rebuild callback state structure ctrbcbst.

typedef struct ctrbcbst {

LONG rcblen; /* number of data bytes in structure */

LONG rcbhw; /* counter high word value */

COUNT rcbrc; /* rebuild callback return code */

} ctRBCBST, ctMEM * pctRBCBST;

/* Size of rebuild callback state structure, version 1 */

#define ctRCBLEN_V01 10

Return Values

Returns a pointer to the ctrcbst state structure.

Example

To enable a clean rebuild cancel from within a callback, consider the following.

void myRebuildCallback( LONG counter, TEXT event, pTEXT message ) {
 

    pctRBCBST state;

    extern int cancel;