Normally, GT.M orders data with numeric values first, followed by strings sequenced by ASCII values. To use an alternative collating sequence the following items must be provided at GT.M process intialization.

A shared library for an alternative collation sequence must contain the following four routines:

GT.M searches the shared library for the gtm_ac_xform_1 and gtm_ac_xback_1 before searching for the gtm_ac_xform and gtm_ac_xback routines. If the shared library contains gtm_ac_xform_1, GT.M ignores gtm_ac_xform even if it is present. If GT.M finds gtm_ac_xform_1 but does not find gtm_ac_xback_1, it reports a COLLATIONUNDEF error with an additional mismatch COLLFNMISSING warning.

If the application does not use strings longer than 32,767 bytes, the alternative collation library need not contain the gtm_ac_xform_1 and gtm_ac_xback_1 routines. On the other hand, if the application passes strings greater than 32,767 bytes (but less than the maximum support string length) and does not provide gtm_xc_xform_1 and gtm_xc_xback_1, GT.M issues the COLLARGLONG run-time error.

Note that database key sizes are much more restricted by GT.M than local key sizes, and may be restricted further by user configuration.

All subscripted local variables for a process must use the same collation sequence. The collation sequence used by local variables can be established as a default or in the current process. The local collation sequence can only be changed when a process has no subscripted local variables defined.

To establish a default local collation sequence provide a numeric value to the environment variable gtm_local_collate to select one of the collation tables, for example:

$ gtm_local_collate=n
$ export gtm_local_collate

where n is the number of a collation sequence that matches a valid collation number defined by an environment variable in the form gtm_collate_n.

An active process can use the %LCLCOL utility to define the collation sequence for subscripts of local variables.

For more information, refer to “%LCLCOL ”in the Utilities Chapter of this manual.

set^%LCLCOL(n)changes the local collation to the type specified by n.

Example:

IF '$$set^%LCLCOL(3) D
. Write "local collation sequence not changed",! Break

This piece of code illustrates $$set^LCLCOL used as an extrinsic. It would write an error message and BREAK if the local collation sequence was not set to 3.

set^%LCLCOL(n,ncol) determines the null collation type to be used with the collation type n.

  • If the truth value of ncol is FALSE(0), local variables use the GT.M standard null collation.

  • If the truth value of ncol is TRUE(1), local variables use the M standard null collation.

With set^%LCLCOL(,ncol), the null collation order can be changed while keeping the alternate collation order unchanged. If subscripted local variables exist, null collation order cannot be changed. In this case, GT.M issues the COLLDATAEXISTS error.

get^%LCLCOL returns the current local type.

Example:

GTM>Write $$get^%LCLCOL
0

This example uses $$get^%LCLCOL as an extrinsic that returns 0, indicating that the effective local collation sequence is the standard M collation sequence.

If set^%LCLCOL is not specified and gtm_local_collate is not defined, or is invalid, the process uses M standard collation. The following would be considered invalid values:

  • A value less than 0

  • A value greater than 255

  • A legal collation sequence that is inaccessible to the process

Inaccessibility could be caused by a missing environment variable, a missing image, or security denial of access.

loading table of contents...