Matching Alternative Patterns

GT.M allows the definition of unique patterns for use with the pattern match operator, in place of, or in addition to, the standard C, N, U, L, and P. You can redefine existing pattern codes (patcodes), or add new ones. These codes are defined in a specification file. The format is described in the next section.

Pattern Code Definition

This section explains the requirements for specifying alternative pattern codes. These specifications are created as a table in a file which GT.M loads at run time.

Use the following keywords to construct your text file. Each keyword must:

  • Appear as the first non-whitespace entry on a line.

  • Be upper case.

The table names also must be uppercase. The patcodes are not case-sensitive.

PATSTART indicates the beginning of the definition text and must appear before the first table definition.

PATTABLE indicates the beginning of the table definition. The keyword PATTABLE is followed by whitespace, then the table name. The text file can contain multiple PATTABLEs.

PATCODE indicates the beginning of a patcode definition. The keyword PATCODE is followed by whitespace, then the patcode identifying character. On the next line enter a comma-delimited list of integer codes that satisfy the patcode. A PATCODE definition is always included in the most recently named PATTABLE. A PATTABLE can contain multiple PATCODEs.

PATEND indicates the end of the definition text; it must appear after the last table definition.

To continue the comma-delimited list on multiple lines, place a dash (-) at the end of each line that is not the last one in the sequence. To enter comments in the file, begin the line with a semi-colon (;).

The following example illustrates a possible patcode table called "NEWLANGUAGE," The example has definitions for patcodes "S," which would be a non-standard pattern character, and "L," which would substitute alternative definitions for the standard "L" (or lower case) pattern characters.

Example:

PATSTART
  PATTABLE NEWLANGUAGE
  PATCODE S
    144,145,146,147,148,149,150
  PATCODE L
    230,231,232,233,234,235,236,237,238,239,240,241-,242,243,244,245,246,247,248,249,250,251,252,253,254,255
PATEND

Be mindful of the following items as you define your patcode table.

  • GT.M loads a table name can only be loaded once during an invocation of a process. Changes a loaded table do not apply to running processes that have already reference that table.

  • The table name "M" is a reserved designation for standard M, which is included in the GT.M run-time library.

  • Standard patcodes A and E cannot be explicitly redefined. A is always the union of codes U and L; E always designates the set of all characters.

  • The C pattern code you define is used by GT.M to determine those characters which are to be treated as unprintable. All characters not defined as C are treated as printable.

  • In UTF-8 mode, M standard patcodes (A,C,L,U,N,P,E) work with Unicode® characters. Application developers can neither change their default classification nor define the non-standard patcodes ((B,D,F-K,M,O,Q-T,V-X) beyond the ASCII subset. This means that the pattern tables cannot contain characters with codes greater than the maximum ASCII code 127.

Pattern Code Selection

To establish a default patcode table for a database define the environment variable:

$ gtm_pattern_file=pathname
$ export gtm_pattern_file

where filename is the text file containing the patcode table definition, and

$ gtm_pattern_table=tablename
$ export gtm_pattern_table

where tablename is the name of the patcode table within the file pointed to by gtm_pattern_file.

[Caution] Warning

GT.M performs operations on literals at compile time and the pattern codes settings may have an impact on such operations. Therefore, it is safest to either always compile with the same pattern code settings as those used at runtime. If changes to pattern codes are required at run time, "hide" any patterns used on literal expressions from the compiler (which are uncommon) using XECUTE commands or indirection.

Within an active process, the patcode table is established using the M VIEW command and the %PATCODE utility. Before invoking the %PATCODE utility, you may use VIEW to load pattern definition files for GT.M. The required keyword and value are:

VIEW "PATLOAD":"pathname" 

This allows you to use the %PATCODE utility or the VIEW command to set current patcode table. The format of the VIEW command to set the patcode table is:

VIEW "PATCODE":"tablename"

This is equivalent to set ^%PATCODE explained below.

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

%PATCODE has the following extrinsic entry points:

set^%PATCODE(tn)

sets the current patcode table to the one having the name specified by tn, in the defined file specification.

Example:

GTM>Write $$set^%PATCODE("NEWLANGUAGE")
1

If there is no table with that name, the function returns a false (0) and does not modify the current patcode table.

get^%PATCODE

returns the current patcode table name.

Example:

GTM>Write $$get^%PATCODE
NEWLANGUAGE