Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

Multiple ISAM Contexts (Positions)

To permit an application to maintain more than one current ISAM position in a single instance of an open file, the following three routines are used: OpenISAMContext(), ChangeISAMContext(), and CloseISAMContext().

These functions make it possible to save multiple positions in the same file. For example, it is possible to do the following with an index defined over city name:

  • Open an ISAM context. Retrieve the city “Columbia”.
  • Open a second ISAM context over the same index. Retrieve the city “Denver”.
  • Change to the first ISAM context. Read the next record to retrieve “Columbus”.

The following code demonstrates these concepts.

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

Multiple ISAM Context Example

#define namebuf 32


struct { /* data record format */

TEXT name[namebuf]; /* customer name */

LONG num; /* customer number */

} parentimage;


FILNO datno, keyno;

COUNT contextID1, contextID2;

TEXT target[namebuf];


if ((contextID1=OpenISAMContext(datno,keyno,-1)) == -1)

printf("\n\tOpenISAMContext1 error - %d", isam_err);


memset(target,' ',namebuf);

cpybuf(target,"Columbia",strlen("Columbia"));


if (error =

GetRecord(keyno,TransformKey(keyno,target),&parentimage))

printf("\n\tGetRecord error - isam_err = %d",isam_err);


if ((contextID2=OpenISAMContext(datno,keyno,-1))==-1 )

printf("\n\tOpenISAMContext2 error - %d",isam_err);


memset(target,' ',namebuf);

cpybuf(target,"Denver",strlen("Denver"));


if (error =

GetRecord(keyno,TransformKey(keyno,target),&parentimage))

printf("\n\tGetRecord error - isam_err = %d",isam_err);


if (ChangeISAMContext(contextID1))

printf("\n\tError on CHGICON 1 = %d",isam_err);


if (!(error=NextRecord(keyno,&parentimage)))

printf("\n\tSuccessful NXTREC for context1-city name: %s.",

parentimage.name);

These routines permit a similar form of control as the multiple SET and BATCH routines, with the following essential differences:

  • An ISAM Context is tied to one and only one data file. Each data file has a current ISAM context. A set or batch can be used with any key file for any associated data file.
  • When a file is closed, its associated contexts are closed. Closing an individual file does not affect the existence of the multiple SET (or BATCH) buffers.
  • CloseISAMContext() removes the context buffers for one particular ISAM context. FreeSet() and FreeBatch() remove the buffers for all the multiple sets and batches.
  • Neither sets nor batches permit FairCom DB to automatically assign set or batch numbers. OpenISAMContext() allows FairCom DB to automatically assign the context ID if it is passed in as negative one (-1).
  • Calling AllocateSet() or AllocateBatch() is not necessary. Calling OpenISAMContext() is necessary.

TOCIndex