These utilities are an integral part of the GT.M functionality that permits you to customize your applications for use with other languages. For a description of these utilities, refer to Chapter 12: “Internationalization”.
The internationalization utilities are:
The %GBLDEF utility manipulates the collation sequence assigned to a global other than the default M collation that is based on code value (ASCII for the codes 0 to 127) ordering except for numeric values, which order most negative to most positive before string values. As described in the Internationalization Chapter, alternative collation definition requires supplying routines that transform codes into desired collation order. All subscripted variables for a global must use the same collation sequence. A global collation sequence can only be changed when a global has no subscripted variables defined.
get^%GBLDEF(gname[,reg])
get: returns a value associated with the current global variable collation in the form nct,act,ver, where:
- if nct is FALSE (0), it indicates the current global variable collation follows the M standard of collating numeric values before all non-empty strings, and if TRUE (1), the global uses only code order with no special treatment of numeric values
- act is an integer from zero (0) to 255, where zero indicates M standard collation, and other integers indicate alternative collation definitions that tie to environment variables of the form gtm_collate_act
- ver is an integer indicating the version of the act collation sequence definition
A "0" return from $$get^%GBLDEF(gname[,reg]) indicates that the global has no special characteristics and uses the region default collation, while a "0,0,0" return indicates that the global is explicitly defined to M collation.
kill^%GBLDEF(gname)
kill: returns a TRUE (1) if the current global variable collation now uses M standard collation that is based on code value (ASCII for the codes 0 to 127) ordering except for numeric values, which order most negative to most positive before string values;It returns FALSE (0) if:
- The global has an access method other than BG or MM - typically this means the global is remote and accessed using GT.CM - if so, maintain it on the system that holds it
- The global contains data with collation other than M; use this to function after removing all content
- The global's subscripts span multiple regions; use the global directory (GBLNAME object in GDE) to set collation characteristics for a global whose subscripts span multiple regions
- $TLEVEL is non-zero; always execute this function outside of a TSTART/TCOMMIT fence
set^%GBLDEF(gname[,nct][,act])
set: if possible, esablishes a global variable collation; returns a TRUE (1) if the current successful in establishing or matching global variable collation characteristics;returns FALSE (0) if:
- The global has an access method other than BG or MM - typically this means the global is remote and accessed using GT.CM - if so, maintain it on the system that holds it
- The global contains data with collation other than that specified; use this to function after removing all content
- The global's subscripts span multiple regions; use the global directory (GBLNAME object in GDE) to set collation characteristics for a global whose subscripts span multiple regions
- $TLEVEL is non-zero; always execute this function outside of a TSTART/TCOMMIT fence
Of the following input arguments only the second and third are valid for set, while the first is required for all three functions:
- first argument: name of the global; must be a legal M variable name, including the leading caret (^); if the global name appears as a literal, it must be enclosed in quotation marks (" ")
- Optional second argument: truth value where a FALSE (0) indicates numeric values collate before non-numeric values and a TRUE (1) value indicates all keys collate in code order.
- Optional third argument: integer value of a collation definition, where zero (0) selects the standard collation, which requires no special definition and other numbers n up to 255 select collations that tie to environment variables of the form gtm_collate_n
- Optional second argument for get: region name; the funtion determines the region name if you don't supply it
For more information and usage examples, refer to “Using the %GBLDEF Utility” in the Internationalization Chapter of this manual.
The %LCLCOL utility deals with the adoption and reporting of a local variable collation other than the default M collation that is based on code value (ASCII for the codes 0 to 127) ordering except for numeric values, which order most negative to most positive before string values. As described in the Internationalization Chapter, alternative collation definition requires supplying routines that transform codes into desired collation order. 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 by this utility within 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 prior to invoking a GT.M process, provide a numeric value to the environment variable gtm_local_collate to select one of the collation tables.
get^%LCLCOL[()]
get: returns an integer value associated with the current local variable collation.
getncol^%LCLCOL[()]
getncol: returns a FALSE (0) if the current local variable collation uses the original GT.M collation of an empty string ("NULL) value between numeric values and strings, and a TRUE (1) value indicates the proces is using the M standard collation where the empty string collates before all other values.
getnct^%LCLCOL[()]
getnct: returns a FALSE (0) if the current local variable collation follows the M standard of collating numeric values before all non-empty strings and a TRUE (1) if it uses only code order with no special treatment of numeric values.
set^%LCLCOL([colid][,ncol][,nct])
set: if possible, esablishes a local variable collation.
If the set invocation supplies no argument, there is no environment variable defined corresponding to the first argument, or the specification requests a change when subscripted local variables already exist, the extrinsic function returns a FALSE (0). If the function successly modifies the local variable collation, or the specification matches the current settings, the function returns a TRUE (1).
The following input arguments are valid only for set:
- Optional first argument: integer value of a collation definition, where zero (0) selects the standard collation, which requires no special definition and other numbers n up to 255 select collations that tie to environment variables of the form gtm_collate_n
- Optional second argument: truth value where a FALSE (0) indicates numeric values collate before non-numeric values and a TRUE (1) value indicates all keys collate in code order.
- Optional third argument: truth value where a FALSE (0) indicates original GT.M collation of an empty string ("NULL) value between numeric values and strings and a TRUE (1) value indicates M standard collation where the empty string collates before all other values. Empty string use as a subscript in local variables is also subject to the VIEW and $VIEW() "LVNULLSUBS" keyword and its "NO" and "NEVER" variations.
For more information and usage examples, refer to “Establishing A Local Collation Sequence”in the Internationalization Chapter of this manual.
The %PATCODE utility is a wrapper for pattern code related VIEW "PATCODE":code" and $VIEW("PATCODE"), and has the following extrinsic entry points:
get^%PATCODE[()]
get: returns the name of the process current pattern table; for example the default table is "M"
set^%PATCODE(tablename)
set: updates the current process pattern table to the named table
If the set invocation finds the character set is UTF-8, it returns FALSE (0) if the argument is missing or does not correspond to an existing file, the function returns the empty string; it successfuly changes the pattern table or matches the current table, the function returns TRUE (1).
