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}])
The expression specifies the string to transform.
The intexpr specifies the ID of the alternative transform to use.
The optional third argument specifies:
zero (0): the transform is to normalized form
one (1): the reverse transform from the normalized to the native form
two (2): the character which collates immediately after the first character of the first argument, or the empty string if no character does.
minus two (-2): character which collates immediately before the first character of the first argument, or the empty string if no character does.
The optional fourth argument specifes whether to use standard M collation of numbers before strings, the default or zero (0), or to sort all values as strings (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)”.
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.