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