FairCom ISAM for C

BuildKey

BuildKey() assembles a key value from the supplied record buffer using the ISAM key segment definitions, then calls TransformKey().

Short Name

frmkey()

Type

ISAM-level index file function

Declaration

COUNT frmkey(FILNO keyno, pTEXT recptr, pTEXT txt, ctRECPT pntr, VRLEN datlen)

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

BuildKey() extracts a key value for index number keyno from the data record image of datlen bytes pointed to by recptr. The key value is assembled at the location pointed to by txt. If the index supports duplicate key values, then the 4-byte value given by pntr is appended to the end of the key value in most significant to least significant byte order. BuildKey() uses the information in the Incremental ISAM structure, or ISAM parameter file, to extract the key, concatenating key segments after they have been transformed according to the segment mode parameter.

BuildKey() may be called directly from an application program in a situation where a target key value can be created according to the ISAM specifications, but TransformKey() is not convenient. Consider the following example in which the key value is made up of two segments:

The first 6 bytes of the name field converted to upper case with a segment mode value of 2.
The 4 bytes of the id field.

In an 80X86 environment, the 4-byte id field will be automatically reversed using a segment mode value of 1 (INTSEG - unsigned integer).

The value of pntr is only used when an index supports duplicate entries. CurrentFileOffset() can be used to determine the current file offset. In most cases, pass a long zero (0L) for this parameter. Use 0xffffffff for pntr before a call to GetLTERecord() for an index supporting duplicates.

Return

BuildKey() returns the length of the key value assembled or a zero if the key is composed entirely of the empty character, as defined in the parameter file. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

A non-zero return code indicates success. Zero means either no key or an error occurred. When the function returns zero, check isam_err. If it is zero, the specified record image produced no key value (for example due to a condition on the index, or the null key check is enabled and the key consists entirely of the empty character). If it is non-zero, an error occurred.

Example

FILNO keyno;

COUNT i;

struct {

COUNT delflg[4];

TEXT name[24];

LONG id;

TEXT desc[128];

} cur_info, /* current ISAM buffer */

upd_info, /* rewrite update buffer */

tar_info; /* target key staging area */

TEXT target[10]; /* target key buffer */

printf("\n\nEnter name field ");

scanf("%24s",tar_info.name); /* load name field */

for (i = strlen(tar_info.name); i < 24; i++) /* pad name */

tar_info.name[i] = PADDING;

printf("\nEnter id field ");

scanf("%ld",&tar_info.id); /* load id */

/* now the raw elements of the target are ready */

frmkey(keyno, &tar_info,target,0L,sizeof(tar_info));

/* frmkey performs the necessary transformations on tar_info

and places the result in target. Now search isam files. */

GetRecord(keyno,target,&cur_info);

Limitations

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.