FairCom ISAM for C

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:

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

CONTEXT_HASH <# of hash bins>

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).

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful open (creation).
48	FMOD_ERR	Operation incompatible with type of file.
83	IALC_ERR	No memory is available.
592	ECON_ERR	Context ID exists.

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. */