Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

GetORDKey

Return the record offset (recbyt) to the nth offset past the given target.

Short Name

ORDKEY()

Type

Low-Level index file function

Declaration

ctRECPT GetORDKey(FILNO keyno, pVOID target, LONG offset, 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

GetORDKey() returns the record offset, recbyt, for the nth active index entry, offset, past the given target for index number keyno. The target must be properly formed as is necessary with any c-tree function that retrieves data using indexes. This function is intended to aid developers programming “list boxes” in a GUI environment.

In V11.8 and later, the GetORDKey() function is supported for partitioned files.

Return

GetORDKey(), if successful, returns the record offset, recbyt, for the nth active index entry, offset, past the given target and the idxval argument contains the index value found at the index location target + offset.

If an error occurs or no active entries are found, GetORDKey() returns zero. When GetORDKey() returns zero, if uerr_cod is non-zero, an error condition was detected; otherwise no active key values were detected. 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 contains a duplicate allowed index over customer name. The code prompts the user for a beginning name and the number of active key values to skip. The value recbyt returned by GetORDKey() is the record offset in the data file for the key value found.

Example

FILNO keyno=4;

LONG maxbuf=40;


LONG ret_long, recbyt;

TEXT target[maxbuf]; /* target value to start search with */

TEXT idxval1[maxbuf]; /* input buffer for RNGENT function */

TEXT idxval2[maxbuf]; /* input buffer for RNGENT function */


printf("\n\tEnter name for GetORDKey:");

memset(target,' ',maxbuf);

gets(target);


TransformKey(4,target); /* properly form search target */

printf("\n\tEnter offset to find with ORDKEY:");

memset(idxval1,0x0,maxbuf);

gets(idxval1);

ret_long = atol(idxval1);


if (!(recbyt = GetORDKey(keyno,target,ret_long,idxval2)))

printf("\nError on GetORDKey, error = %d",uerr_cod);

else

printf("\nSuccessful GetORDKey, recbyt =%ld, idxval2 = %s",recbyt, idxval2);

Limitations

The value of offset must be positive.

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

NbrOfKeysInRange(), NbrOfKeyEntries()

TOCIndex