TransformKey

Perform key segment translation to target key.

Short Name

TFRMKEY()

Type

ISAM function

Declaration

pTEXT TransformKey(COUNT keyno, pVOID target)

Description

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 Plus 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 Plus 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 Plus Programmer’s Reference Guide), or the extended functions CreateISAMXtd(), OpenISAMXtd(), or InitISAMXtd(), c-tree Plus 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 Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example

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

LONG      int_target;

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