F.11 BuildKey

---

Perform key segment translation from record buffer to target key.

SHORT NAME

frmkey

TYPE

Low level index file function

DECLARATION

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

DESCRIPTION

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 Appendix A "c-tree Plus Error Codes" of the c-tree Plus Programmer's Reference Guide for a complete listing of valid c-tree Plus error values.

EXAMPLE

COUNT keyno,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.

SEE ALSO

TransformKey