$ZCOnvert()

Returns its first argument as a string converted to a different encoding. The two argument form changes the encoding for case within a character set. The three argument form changes the encoding scheme.

The format for the $ZCONVERT() function is:

$ZCO[NVERT](expr1, expr2,[expr3])
[Note] Note

When UTF-8 mode is enabled, GT.M uses the ICU Library to perform case conversion. As mentioned in the Theory of Operation section, the case conversion of the strings occurs according to Unicode code-point values. This may not be the linguistically or culturally correct case conversion, for example, of the names in the telephone directories. Therefore, application developers must ensure that the actual case conversion is linguistically and culturally correct for their specific needs. The two-argument form of the $ZCONVERT() function in M mode does not use the ICU Library to perform operation related to the case conversion of the strings.

Examples of $ZCONVERT()

Example:

GTM>write $zconvert("Happy New Year","U")
HAPPY NEW YEAR

Example:

GTM>write $ZCHSET
M
GTM>Write $zconvert("HAPPY NEW YEAR","T")
%GTM-E-BADCASECODE, T is not a valid case conversion code

Example:

GTM>Set T8="主要雨在西班牙停留在平原"
GTM>Write $Length(T8)
12
GTM>Set T16=$zconvert(T8,"UTF-8","UTF-16LE")

GTM>Write $length(T16)
%GTM-E-BADCHAR, $ZCHAR(129,137,232,150) is not a valid character in the UTF-8 encoding form
GTM>Set T16=$ZCOnvert(T16,"UTF-16LE","UTF-8")

GTM>Write $length(T16)
9

In the above example, $LENGTH() function triggers an error because it takes only UTF-8 encoding strings as the argument.