$ZATRansform

Returns the transformed representation of the first argument expr in a normalized form using the alternative transform specified by the second argument intexpr; the transformed representation can be used as an operand to the follows (]) or sorts-after (]]) operator such that, if both operands are in the normalized form, the result is independent of alternative collation. The format for the $ZATRANSFORM() function is:

$ZATRANSFORM(expr,intexpr[,{0|1|2|-2}][,{0|1}])

Please see “$ZCOLlate()” for a similar alternative.

The 2 and -2 work in M mode for the 'M' collation (collation 0), or any user defined collation which supplies the necessary plugin functionality. In UTF-8 mode, these argument values produce a ZATRANSCOL error. If the plugin for the specified collation does not support this "next character" functionality, the function produces a COLLATIONUNDEF error in response to an an attempt to invoke it. If an external collation library is used and encounters a gtm_ac_xutil failure, ZATRANSFORM produces an ERR_ZATRANSCOL. If an external collation library is used and does not supply a gtm_ac_xutil function, ZATRANSFORM produces an ERR_COLLATIONUNDEF when operations -2 or 2 are specified. To use these operations with external collation libraries, the libraries must supply a function called 'gtm_ac_xutil'. For more information on the following signature and characteristics of the gtm_ac_xutil function, refer to “Transform Utility Routine (gtm_ac_xutil).

Examples of $ZATRANSFORM()

Example:

GTM>write $zatransform("John Smythe",1)]$zatransform("Jane Smith",2)
0
GTM>

This example uses $ZATRANSFORM() and two (here unspecified) collation definitions to compare the ordering of two (literal) expressions as GT.M would collate them if there was a way to collate them together. The result indicates that the first would collate before the second.