FairCom ISAM for C

TransformKey

TransformKey() transforms the supplied, already-assembled key value according to the ISAM key segment mode in effect for each of the key segments comprising the assembled key value.

Short Name

TFRMKEY()

Type

ISAM function

Declaration

pTEXT TransformKey(FILNO keyno, pVOID target)

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

The ISAM parameters for your application can specify that key segments are to be translated (e.g., converted to upper case) before being concatenated and added to index files. However, c-tree does not automatically translate your target keys in the same way. TransformKey() converts a target key, pointed to by target, according to the ISAM definition for index number keyno. For example, if you have reversed the bytes of a key segment (see segment mode equal to one in ISAM Functions of the c-tree Programmer’s Reference Guide), then passing a target key to TransformKey() causes the appropriate segment of the target key to be reversed.

Since TransformKey() constructs the translated key in place, ensure the key area pointed to by target is at least as large as the key length, including suffix, defined for index number keyno. TransformKey() expects that you have concatenated all necessary segments into a target key pointed to by the target parameter. This implies all data types should be in the same contiguous buffer. See the example and notice how the LONG field int_target is copied into the TEXT buffer key_buffer.

Note: When using single entry point function calls, (see Common Entry Point Functions in the c-tree Programmer’s Reference Guide), or the extended functions CreateISAMXtd(), OpenISAMXtd(), or InitISAMXtd(), c-tree automatically invokes TransformKey() for you unless you disable this feature.

Return

TransformKey() returns a pointer to the translated target key. Since the translation is performed in place, the return value is always equal to the target parameter, unless there is an error. If an index accepts duplicate key values, TransformKey() sets the suffix to zero in the target key. A NULL value is returned if there is an error, and the value of isam_err will be:

Value	Symbolic Constant	Explanation
80	BKEY_ERR	target is null or keyno is out of range.
199	NSCH_ERR	Segment mode requires a schema map.
433	SSCH_ERR	File referenced by schema-based segment is not defined.

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

TEXT alph_target[5],key_buffer[13],rec_buffer[750];

LONG int_target;

FILNO keyno;

/* target is comprised of a long integer, a five byte alphanumeric, and a 4 byte duplicate key suffix. cpybuf copies n bytes (without regard to null bytes). */

cpybuf(key_buffer, (pTEXT) &int_target,4);

cpybuf(key_buffer + 4, alph_target,5);

if (FirstInSet(keyno, TransformKey(keyno,key_buffer), rec_buffer, 9))

printf("\nUnsuccessful FirstInSet (%d)\n", isam_err);

Limitations

TransformKey() automatically sets the suffix of the target key to all NULL bytes if duplicates are enabled for index number keyno. To control the suffix, change it after TransformKey() is called.

If the target area pointed to by target is not at least the key length, TransformKey() clobbers the memory area following the target key.