Each FairCom DB function has two names: the full name and the abbreviated name. Full names are used throughout this manual, and describe the action the function performs. The abbreviated name is generally shorter and more cryptic. You will see it if you examine the FairCom DB source code. Prior versions of the c‑tree File Handler used the abbreviated names. If you have a program that worked with older versions of c‑tree, you will not have to change the function calls to the full names. Also included in the table is the function’s API group and a table of API groups.

Full Names

This table lists the functions alphabetically by the Full Name.

Abbreviated (short) Names

This table lists the functions alphabetically by the Abbreviated Name.

Function API Listing

This section lists the FairCom DB Function API broken into functional groupings: Initialization, Definition, Manipulation, and Utility. Each of these groupings has sub-groups as described in the topics that follow.

Initialization API

The initialization API prepares the environment for FairCom DB operation. Included are the ctThrd, Instance Control, ISAM Initialization, and Low-Level Initialization APIs.

ctThrd API

The FairCom DB ctThrd API is a very thin overlay over the native threading API for each operating systems. Only systems without native threading use a FairCom DB proprietary threading API.

Instance Control API

Similar to the thread API but used only with single-thread models, Instance Control allows and controls multiple FairCom DB instances within a single application.

ISAM Initialization API

Used to initialize the ISAM level operation of FairCom DB.

Low-Level Initialization API

Used to initialize the Low-Level FairCom DB environment.

Data Definition API

Used to create and define tables and indexes. Divided into ISAM and Low-Level APIs.

ISAM Data Definition API

Used to create and define files for ISAM level use.

Low-Level Data Definition API

Used to create and define files for Low-Level use.

Data Manipulation API

Data manipulation functions are used to alter the contents of data and index files. This sections is divided into ISAM and Low-Level functions.

ISAM Data Manipulation API

ISAM Manipulation functions are divided into general, Batch, Context, and Set APIs.

Batch API

Manipulate batches of records in a single call.

Context API

Maintain separate positions in a file.

Sets API

Work with a specified subset of a table’s records.

Low-Level Data Manipulation API

Manipulate data and index files at the low level.

Utility Functions

The following functions provide capabilities that do not fit into the categories above. In addition to general utility functions, Server administration and Transaction Processing control functions are included here.

Server Administration API

The following utility functions are specific to Client/Server operation.

Transaction Processing API

The following utility functions control transaction processing.

Common Entry Point Functions

FairCom DB offers two calling methods for each function: the traditional FairCom DB call by function name in which each operation is called by a separate function, and the common entry point in which all functions are accessed through the ctree function. For example, AddKey() can be called in either of these two ways:

AddKey(keyno,target,recbyt,typadd);
ctree(FN_ADDKEY,keyno,target,&recbyt,NULL,NULL,typadd);

Either approach produces the same results, but some developers find the common entry point approach better suits their approach to programming.

If you are using FairCom DB, the client side of FairCom DB uses the common entry point approach to send the function calls to FairCom DB. The traditional functions are remapped to common entry point functions. If you use the common entry point function in your application, without any traditional functions, your program will not have to link in the remapping code, saving program memory.

Forced Single Entry Point Capability

The ctFRCSNG define forces single entry point calls using the regular API. Enabling this define causes the standard FairCom DB API (i.e., GetRecord(), AddRecord(), . . .) to be routed through the FairCom DB single entry function ctree(). Forcing the single-entry point is used when developing an interface wrapper from another database. This forced single entry point feature is enabled by adding #define ctFRCSNG to ctoptn.h (see the Quick Start and Product Overview Guide for information on modifying ctoptn.h) and requires no modification on the part of the programmer.

Extended Feature Parameter Blocks

Most of the extended features, such as file security, are passed to ctree as part of a set of parameter blocks defined in ctparm.h. Any application using the single entry point function, ctree(), must include ctparm.h. ctparm.h also contains the function numbers (FN_ADDKEY, etc.) used in the ctree()fn parameter.

The definitions of the parameter blocks are below. They are referenced as parameters in the function definitions listed at the end of this appendix. Please note the values assigned to the various character array sizes for the parameter block definitions:

Logon Block

typedef struct logblk {
  COUNT     files;         /* number of files & indexes */  COUNT     userprof;      /* user profile mask         */
  COUNT     ibuffers;      /* # of index buffers        */
  COUNT     dbuffers;      /* # of data buffers         */
  COUNT     nsectors;      /* # of sectors per buffer   */
  COUNT     reservd1;      /* reserved                  */
  VRLEN     reservd2;      /* reserved                  */
  TEXT      userid[IDZ];   /* user id                   */
  TEXT      userword[PWZX]; /* user password             */
  TEXT      servname[FNZ]; /* optional server name      */
} LOGBLK;

The ibuffers, dbuffers, and nsectors members are ignored when connecting to a FairCom DB. The userid and userword members are ignored in non-server operation. The userprof member controls performance of automatic TransformKey() on targets sent to ISAM level search routines. Set userprof to USERPRF_NTKEY to disable the automatic TransformKey(). The servname member supports multiple FairCom DB environments.

ISAM Block

typedef struct isamblk {
  LOGBLK    isamlog;       /* login block                */
  LONG      permmask;      /* CreateISAM permission mask */
  TEXT      groupid[IDZ];  /* CreateISAM Group id        */
  TEXT      fileword[FILEPWZ]; /* file password              */
  TEXT      parmname[FNZ]; /* parameter file name        */
} ISAMBLK;

The isamlog member is simply a logon block interpreted as above. The optional permmask and groupid members are only used by CreateISAM() to set the file permission masks and passwords. The fileword member is used by CreateISAM() to set the password and by OpenISAM() to access the file. The parmname member holds the parameter file name.

IFIL Block

typedef struct ifilblk {
  LONG      permmask;      /* CreateIFile permission mask */
  TEXT      groupid[IDZ];  /* CreateIFile Group id        */
  TEXT      fileword[FILEPWZ]; /* file password               */
  TEXT      dataextn[EXZ]; /* data extension              */
  TEXT      indxextn[EXZ]; /* indx extension              */
  pIFIL     ptr_ifil;      /* IFIL pointer                */
} IFILBLK;

permmask and groupid hold the optional security information assigned at file creation. fileword holds the optional password assigned at creation or used by a file open. dataextn and indxextn hold optional file name extensions for the data and index files, respectively. If a file name extension member begins with a NULL byte, the default extension is used, .dat for data files and .idx for index files. To signify that no extension should be added, pass the member containing only blanks and a null terminator. Both file name extension members cannot be blank since the data file and index must have unique names. ptr_ifil points to a traditional IFIL structure.

Create File Block

typedef struct creblk {
  UCOUNT    length;        /* record / key length  */
  UCOUNT    extdsize;      /* file extent size     */
  COUNT     filemode;      /* file mode            */
  COUNT     keytyp;        /* index key type       */
  COUNT     keydup;        /* index duplicate flag */
  COUNT     member;        /* index member #       */
  LONG      permmask;      /* permission mask      */
  TEXT      groupid[IDZ];  /* group id             */
  TEXT      fileword[FILEPWZ]; /* file password        */
  TEXT      filename[FNZ]; /* file name            */
} CREBLK;

length specifies the record length for data files or the key length for index files. extdsize contains the file size extension parameter, and filemode contains the file mode. keytyp, keydup, and member are ignored for data files and represent the key type, key duplicate, and index member number, respectively, for index files. permmask, groupid, and fileword hold the optional file security information. Finally, filename contains the file name to be used at create.

Open File Block

typedef struct openblk {  COUNT     filemode;      /* file mode     */  TEXT      fileword[FILEPWZ]; /* file password */
  TEXT      filename[FNZ]; /* file name     */
} OPENBLK;

Key Estimate Block

typedef struct estmblk {
  TEXT      key1[MAXLEN]; /* 1st key */
  TEXT      key2[MAXLEN]; /* 2nd key */
} ESTMBLK;

The Key Estimate Block is used with the FN_ESTKEY() function, which estimates the number of key values occurring between key1 and key2.

Function Calls

The single entry point calling sequence is based on the following function prototype:

COUNT ctree(COUNT fn, COUNT filno, pVOID ptr1, pLONG plong,
            pVOID ptr2, pVRLEN psize, COUNT mode);

fn is the function number, filno is usually a file number, ptr1 and ptr2 point to various types of data or parameter blocks, plong points to a long integer, psize points to a long integer used to convey or return the size of an object, and mode is a short integer for various specifications.

Because of the manner in which C functions pass parameters, it is not necessary to supply all seven parameters all of the time. Generally, you need only supply enough parameters to satisfy the particular function, BUT you cannot skip parameters.

For example, GetKey() returns a long value corresponding to the record position containing the target key value. In the traditional FairCom DB approach, call:

recpos = GetKey(keyno,target);

With the ctree() form, call:

errcod = ctree(FN_EQLKEY,keyno,target,&recpos);

recpos is passed back as an output parameter of ctree(). In the following listing, retval denotes the parameter that contains the return value of the function. FairCom DB functions which return an error code do not use a retval parameter.

Several FairCom DB functions are listed below with their traditional call by name form and the ctree(FN_...) form. The extended functions, those that have a suffix of Xtd, use the same single entry point call as the equivalent standard function. The function numbers are based on the short function name listed in Upgrade Previous Editions.

COUNT Abort()
ctree(FN_TRANABT)
COUNT AddKey(keyno,target,recbyt,typadd)
ctree(FN_ADDKEY,keyno,target,&recbyt,NULL,NULL,typadd)
COUNT AddRecord(datno,recptr)
ctree(FN_ADDREC,datno,recptr)
COUNT AddCtResource(datno,resptr,varlen)
ctree(FN_ADDRES,datno,resptr,NULL,NULL,&varlen)
COUNT AddVRecord(datno,recptr,varlen)
ctree(FN_ADDVREC,datno,recptr,NULL,NULL,&varlen)
COUNT AllocateSet(numset)
ctree(FN_ALCSET,numset)
COUNT AvailableFileNbr(numfils)
ctree(FN_AVLFILNUM,numfils,retval)
LONG Begin(mode)
ctree(FN_TRANBEG,mode,NULL,&retval)
COUNT ChangeSet(setnum)
ctree(FN_CHGSET,setnum)
COUNT ClearTranError()
ctree(FN_TRANCLR)
COUNT CloseFile(filno,filmod)
ctree(FN_CLSFIL,filno)
COUNT CloseIFile(ifilptr)
ctree(FN_CLIFIL,0,&ifilblk)
COUNT CloseISAM()
ctree(FN_CLISAM)
COUNT CloseRFile(datno)
ctree(FN_CLRFIL,datno)
COUNT Commit(mode)
ctree(FN_TRANEND,mode)
COUNT CreateDataFile(datno,filnam,datlen,xtdsiz,filmod)
COUNT CreateDataFileXtd(datno,filnam,datlen,xtdsiz,filmod,
                        permmask,groupid,fileword)
ctree(FN_CREDAT,datno,&createblk)
COUNT CreateIFile(ifilptr)
COUNT CreateIFileXtd(ifilptr,dataextn,indxextn,permmask,groupid,fileword)
ctree(FN_CREIFIL,0,&ifilblk)
COUNT CreateIndexFile(keyno,filnam,keylen,keytyp,keydup,
                      nomemb,xtdsiz,filmod)
COUNT CreateIndexFileXtd(keyno,filnam,keylen,keytyp,keydup,
                         nomemb,xtdsiz,filmod,permmask,groupid,fileword)
ctree(FN_CREIDX,keyno,&createblk)
COUNT CreateIndexMember(keyno,keylen,keytyp,keydup,membno)
ctree(FN_CREMEM,keyno,&createblk)
COUNT CreateISAM(filnam)
COUNT CreateISAMXtd(filnam,userprof,userid,userword,servname,
                    permmask,groupid,fileword)
ctree(FN_CREISAM,0,&isamblk)
pTEXT CurrentISAMKey(keyno,idxval,plen)
ctree(FN_GETCURK,keyno,idxval,NULL,plen)
LONG CurrentFileOffset(datno)
ctree(FN_GETCURP,datno,NULL,&retval)
COUNT DeleteCtFile(filno)
ctree(FN_DELFIL,filno)
COUNT DeleteKey(keyno,target,recbyt)
ctree(FN_DELCHK,keyno,target,&recbyt)
LONG DeleteKeyBlind(keyno,target)
ctree(FN_DELBLD,keyno,target,&retval)
COUNT DeleteRecord(datno)
ctree(FN_DELREC,datno)
COUNT DeleteCtResource(datno,resptr)
ctree(FN_DELRES,datno,resptr)
COUNT DeleteVRecord(datno)
ctree(FN_DELVREC,datno)
COUNT DoBatch(filno,request,bufptr,bufsiz,mode)
ctree(FN_BATSET,filno,request,NULL,bufptr,&bufsiz,mode)
COUNT EnableCtResource(datno)
ctree(FN_ENARES,datno)
LONG EstimateKeySpan(keyno,idxval1,idxval2)
ctree(FN_ESTKEY,keyno,&estm,&retval)
COUNT FirstInSet(keyno,target,recptr,siglen)
ctree(FN_FRSSET,keyno,target,NULL,recptr,NULL,siglen)
LONG FirstKey(keyno,idxval)
ctree(FN_FRSKEY,keyno,idxval,&retval)
COUNT FirstRecord(filno,recptr)
ctree(FN_FRSREC,filno,recptr)
COUNT FreeSet()
ctree(FN_FRESET)
COUNT GetAlternateSequence(keyno,altseq)
ctree(FN_GETALTSEQ,keyno,altseq)
VRLEN GetDODA(datno,bufsiz,bufptr,mode)
ctree(FN_GETDODA,datno,bufptr,&bufsiz,NULL,&retval,mode)
LONG GetFileInfo(filno,mode)
ctree(FN_GETFIL,filno,NULL,&retval,NULL,NULL,mode)
LONG GetGTEKey(keyno,target,idxval)
ctree(FN_GTEKEY,keyno,target,&retval,idxval)
COUNT GetGTERecord(keyno,target,recptr)
ctree(FN_GTEREC,keyno,target,NULL,recptr)
LONG GetGTKey(keyno,target,idxval)
ctree(FN_GTKEY,keyno,target,&retval,idxval)
VRLEN GetIFile(datno,bufsiz,bufptr)
ctree(FN_GETIFIL,datno,bufptr,&bufsiz,NULL,&retval)
LONG GetKey(keyno,target)
ctree(FN_EQLKEY,keyno,target,&retval)
LONG GetLTEKey(keyno,target,idxval)
ctree(FN_LTEKEY,keyno,target,&retval,idxval)
COUNT GetLTERecord(keyno,target,recptr)
ctree(FN_LTEREC,keyno,target,NULL,recptr)
LONG GetLTKey(keyno,target,idxval)
ctree(FN_LTKEY,keyno,target,&retval,idxval)
COUNT GetRecord(keyno,target,recptr)
ctree(FN_EQLREC,keyno,target,NULL,recptr)
LONG GetCtResource(datno,resptr,bufptr,bufsiz,resmode)
ctree(FN_GETRES,datno,resptr,&retval,bufptr,&bufsiz,resmode)
LONG GetSerialNbr(datno)
ctree(FN_SERIALNUM,datno,NULL,&retval)
COUNT GetSymbolicNames(filno,nambuf,buflen,mode)
ctree(FN_GETNAM,filno,nambuf,NULL,NULL,&buflen,mode)
COUNT GetTempCtFileName(bufptr,bufsiz)
ctree(FN_TMPNAME,0,bufptr,NULL,NULL,&bufsiz)
COUNT InitISAM(bufs,fils,sect)
COUNT InitISAMXtd(bufs,fils,sect,dbufs,userprof,userid,userword,servname)
ctree(FN_INTISAM,0,&logonblk)
COUNT InitCTree(bufs,fils,sect)
COUNT InitCTreeXtd(bufs,fils,sect,dbufs,userprof,userid,userword,servname)
ctree(FN_INTREE,0,&logonblk)

logonblk is defined above under the discussion of the Logon Block found in CTPARM.H.

LONG KeyAtPercentile(keyno,idxval,fractal)
ctree(FN_FRCKEY,keyno,idxval,&retval,NULL,NULL,fractal)
COUNT LastInSet(keyno,target,recptr,siglen)
ctree(FN_LSTSET,keyno,target,NULL,recptr,NULL,siglen)
LONG LastKey(keyno,idxval)
ctree(FN_LSTKEY,keyno,idxval,&retval)
COUNT LastRecord(filno,recptr)
ctree(FN_LSTREC,filno,recptr)
COUNT LoadKey(keyno,target,recbyt,typadd)
ctree(FN_LOADKEY,keyno,target,&recbyt,NULL,NULL,typadd)
COUNT LockISAM(lokmod)
ctree(FN_LKISAM,lokmod)
COUNT LockCtData(datno,lokmod,recbyt)
ctree(FN_LOKREC,datno,NULL,&recbyt,NULL,NULL,lokmod)
LONG NbrOfKeyEntries(keyno)
ctree(FN_IDXENT,keyno,NULL,&retval)
LONG NbrOfRecords(datno)
ctree(FN_DATENT,datno,NULL,&retval)
LONG NewData(datno)
ctree(FN_NEWREC,datno,NULL,&retval)
LONG NewVData(datno,varlen)
ctree(FN_NEWVREC,datno,NULL,&retval,NULL,&varlen)
COUNT NextInSet(keyno,recptr)
ctree(FN_NXTSET,keyno,recptr)
LONG NextKey(keyno,idxval)
ctree(FN_NXTKEY,keyno,idxval,&retval)
COUNT NextRecord(filno,recptr)
ctree(FN_NXTREC,filno,recptr)
COUNT OpenCtFile(filno,filnam,filmod)
COUNT OpenCtFileXtd(filno,filnam,filmod,fileword)
ctree(FN_OPNFIL,filno,&openblk)
COUNT OpenFileWithResource(filno,filnam,filmod)
COUNT OpenFileWithResourceXtd(filno,filnam,filmod,fileword)
ctree(FN_OPNRFIL,filno,&openblk,&retval)

openblk is defined above under the discussion of the Open Block found in CTPARM.H.

COUNT OpenIFile(ifilptr)
COUNT OpenIFileXtd(ifilptr,dataextn,indxextn,fileword)
ctree(FN_OPNIFIL,0,&ifilblk)
COUNT OpenISAM(filnam)
COUNT OpenISAMXtd(filnam,userprof,userid,userword,servname,
                  fileword)
ctree(FN_OPNISAM,0,&isamblk)
COUNT PermIIndex(ifilptr)
ctree(FN_PRMIIDX,0,&ifilblk)
COUNT PositionSet(keyno,recptr,siglen)
ctree(FN_MIDSET,keyno,recptr,NULL,NULL,NULL,siglen)
LONG PreviousKey(keyno,idxval)
ctree(FN_PRVKEY,keyno,idxval,&retval)
COUNT PreviousInSet(keyno,recptr)
ctree(FN_PRVSET,keyno,recptr)
COUNT PreviousRecord(filno,recptr)
ctree(FN_PRVREC,filno,recptr)
COUNT PutDODA(datno,doda,numfld)
ctree(FN_PUTDODA,datno,doda,NULL,NULL,NULL,numfld)
COUNT ReadData(datno,recbyt,recptr)
ctree(FN_REDREC,datno,recptr,&recbyt)
COUNT ReadVData(datno,recbyt,recptr,bufsiz)
ctree(FN_RDVREC,datno,recptr,&recbyt,NULL,&bufsiz)
COUNT RebuildIFile(ifilptr)
COUNT RebuildIFileXtd(ifilptr)
ctree(FN_RBLIFIL,0,&ifilblk)
COUNT ReleaseData(datno,recbyt)
ctree(FN_RETREC,datno,NULL,&recbyt)
COUNT ReleaseVData(datno,recbyt)
ctree(FN_RETVREC,datno,NULL,&recbyt)
COUNT ReReadRecord(datno,recptr)
ctree(FN_RRDREC,datno,recptr)
COUNT ReReadVRecord(datno,recptr,bufsiz)
ctree(FN_REDVREC,datno,recptr,NULL,NULL,&bufsiz)
COUNT ResetRecord(datno,mode)
ctree(FN_UPDCURI,datno,NULL,NULL,NULL,NULL,mode)
COUNT RestoreSavePoingTRANRST(savpnt)
ctree(FN_TRANRST,savpnt)
COUNT ReWriteRecord(datno,recptr)
ctree(FN_RWTREC,datno,recptr)
COUNT ReWriteVRecord(datno,recptr,varlen)
ctree(FN_RWTVREC,datno,recptr,NULL,NULL,&varlen)
COUNT SetAlternateSequence(keyno,altseq)
ctree(FN_SETALTSEQ,keyno,altseq)
COUNT SetRecord(datno,recbyt,recptr,datlen)
ctree(FN_SETCURI,datno,recptr,&recbyt,NULL,&datlen)
COUNT SetSavePoint()
ctree(FN_TRANSAV,0,&retval2)

retval2 is a short integer in which the save point number is returned.

COUNT SetVariableBytes(filno,pvbyte)
ctree(FN_SETVARBYTS,filno,pvbyte)
COUNT StopUser()
ctree(FN_STPUSR)
COUNT TempIIndex(ifilptr)
ctree(FN_TMPIIDX,0,&ifilblk)
pTEXT TransformKey(keyno,tarptr)
ctree(FN_TFRMKEY,keyno,tarptr)
COUNT UpdateFileMode(filno,filmod)
ctree(FN_PUTFIL,filno,NULL,NULL,NULL,NULL,filmod)
COUNT UpdateCtResource(datno,resptr,varlen)
ctree(FN_UPDRES,datno,resptr,NULL,NULL,&varlen)
VRLEN VDataLength(datno,recbyt)
ctree(FN_GTVLEN,datno,NULL,&recbyt,NULL,&retval)
VRLEN VRecordLength(datno)
ctree(FN_GETVLEN,datno,NULL,NULL,NULL,&retval)
COUNT WriteData(datno,recbyt,recptr)
ctree(FN_WRTREC,datno,recptr,&recbyt)
COUNT WriteVData(datno,recbyt,recptr,varlen)
ctree(FN_WRTVREC,datno,recptr,&recbyt,NULL,&varlen)