|
|
|
TransformSegment
Low-Level key transformation.
Short Name
cttseg()
Type
Low-Level function
Declaration
NINT TransformSegment(COUNT spos, COUNT mod, COUNT slen,
pTEXT target, pCOUNT aq, pConvMap mp);
Description
TransformSegment() transforms keys for Low-Level functions in the same manner that TransformKey() transforms for ISAM functions.
mod is the segment mode as described in Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) in the c-tree Programmer’s Reference Guide. slen is the length of the segment to transform. tarptr points to the key value to be transformed. Note that you can do a transformation on a portion of a key. aq points to an optional alternative collating sequence. mp points to an optional record schema. aq and mp can be NULL.
spos is only used if the segment mode requires the record schema. In this case, spos specifies which field of the schema is used to define the key segment type.
Limitation: This function does not support a call with a schema-based key segment mode, such as SCHSEG, on a field that uses the CT_JSON data type. Such a call will fail with error FNUM_ERR (22). This is because, for a CT_JSON data type, the index file number and key segment number are required to transform or untransform the key segment, and this function does not accept these parameters.
Return
TransformSegment() returns zero if successful, or a Low-Level error code if not. 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 transforms the double float key value pointed to by kvp in place.
Example
NINT errc;
double *kvp;
errc = TransformSegment(0,FLTSEG,8,(pTEXT) kvp,NULL,NULL);
Limitations
It is very important to note that transformations are done in place. Move the values to a buffer or structure specifically assigned to index building, rather than transforming variables in a record buffer. Taking the example code above, a mode of FLTSEG changes the format of the information stored in the double float variable so that it can be used by c-tree as a key value. The information in that variable is no longer a valid double float value usable in C language calculations. If this variable was a part of a record structure, and it is written back to the data file, that portion of the data record is trashed.
