PATTERN MATCH

Used to test a field value against a pattern of characters.

Syntax

MATCH pattern ["message"]

Parameters

pattern: A pattern of characters which indicate which type of character in which position is acceptable input for this field.
message: Specifies a custom error message.

Discussion

The pattern match allows you to check field values against a general pattern. It can be used to check the actual value, but actual values are more easily checked in the Single Value, Table, or Range tests. This test is generally used to test the type of character entered in a particular position. Before data is checked against a pattern, any leading and trailing blanks are stripped.




	NOTE: Native Language Support does not support pattern matching with native language characters. `MATCH` uses USASCII (NATIVE-3000) rules. For more information on Native Language Support, see Section 8.

Special Pattern Characters

The pattern consists of a series of special characters that indicate the type of USASCII data that can be entered in that position. These characters are:

a: upper or lowercase alphabetic character (A-Z, a-z)
u: uppercase alphabetic character (A-Z)
l: lowercase alphabetic character (a-z)
b: blank
d: digit (0-9)
?: any character

The beginning of the pattern is defined by the first nonblank character after MATCH and, in the simplest case, is terminated by the first blank encountered. A pattern beginning or ending with the special character b will interpret the b as the alphabetic character and not the special character indicating a blank. Leading and trailing blanks should be indicated as spaces within a grouping as described on the next page.

A pattern may contain embedded blanks only if it is enclosed within braces {}. Also, a pattern can span more than one line if it is enclosed within braces {}. If a pattern is within braces, it is terminated by the first blank outside the braces.

The match pattern can include specific characters in addition to the types listed above. To illustrate:

MATCH Aaa-ddd

This pattern means that the value must start with the letter A, be followed by any two upper or lowercase letters of the alphabet, followed by a hyphen and then three digits. For example, the value Acs-123 or AAA-999 are acceptable, but the values Bcs-999 or A12-345 are not.

Transparency

A special operator can be used to indicate that a pattern character is to be used as an actual value. For example, suppose you want the lowercase letter a to be an exact value in the pattern. You can do this by preceding it, or any of the other special pattern characters, with an exclamation point (!). For example:

MATCH !addd           \Value must start with the letter "a"
                      \followed by any three digits.

The exclamation point (called the transparency user) is also used to allow inclusion of any of the pattern operators listed below, and described in Table 4-2 “Local Edit Terminal Menu Selection”

!: (tranparency)
,: (choice)
:: (range)
{}: (grouping)
[]: (optional)
+: (repetition — 1 or more)
*: (repetition — 0 or more)

Choice

You can indicate a selection of acceptable patterns as part of the MATCH pattern. Each possible choice is separated by a comma (,). For example:

MATCH A,AB,BCD,ddd            \The characters "A", "AB", "BCD",
                              \or any three digits are acceptable.

Range

A range of acceptable characters for a single character position can be indicated with the colon (:). All characters within the range are acceptable. This acts as a shorthand for listing a series of single characters in USASCII sequence. For example:

MATCH C:J: This is equivalent to the pattern specified by MATCH C,D,E,F,G,H,I,J.
MATCH 1:7: Any of the digits 1,2,3,4,5,6, or 7 is accepted by this pattern.
MATCH !a:f: Since the letter a is a pattern character, it is preceded by an exclamation point. Other such characters within the range are implicitly preceded by this operator. Thus, the range is equivalent to specifying MATCH !a,!b,c,!d,e,f.

It is important to differentiate between a pattern range which is a range of single characters, and the range check described earlier. In a pattern check, MATCH 10:90 means the value must be a 1 followed by a digit between 0 and 9, followed a 0. In a range check, IN 10:90 means the value must be in the range 10 through 90.

Grouping and Optional

You can group pattern specifications by enclosing the pattern in braces {}. Brackets [] make the enclosed pattern optional. Braces indicate data must correspond to at least one item in the group; brackets indicate any item in the group is optional. For example:

MATCH {A,AB,BCD}) ddd: One of the choices within braces must be matched. For example: A123 or AB999 or BCD562, among others, are acceptable matches for this pattern.
MATCH [A,AB,BCD] ddd: All choices within brackets can be omitted, or one may be matched. For example: AB345, BCD567, A441, or 123 are all acceptable matches.
MATCH [u,d]!+ [1:5]: Some acceptable values are A+ or 5+3 or +5 or simply +.
MATCH [B,dd]dd[%,d]: Accepts such values as B12 or 12345 or 50% or 10, among others.

Since blanks may be included within braces, you can put blanks in a pattern to enhance its clarity by enclosing the entire pattern within braces. For example,

MATCH {[B,dd] dd[%,d]}: Identical to preceding pattern except that it is enclosed within braces so that blanks can be included.

Enclosing a pattern within braces also allows the pattern to span lines. For example:

MATCH {[B,dd] dd [%,d]}: Identical to the example above, except that each pattern component is listed on a separate line.

Repetition

Repetition of any character or sets of characters can be indicated by an asterisk (*) or by a plus sign (+) following any pattern character or pattern group within braces. Plus (+) means that at least one occurrence of the pattern is required for the match; the asterisk (*) means that zero or more occurrences can be matched. These repetition indicators cannot follow items enclosed within brackets. Some examples:

MATCH d+

The plus sign indicates repetition of the digit, with at least one occurrence required for the match. Leaving the field blank is not acceptable unless the field type is 0 for optional, in which case a blank is accepted because processing specifications are ignored.

For example, 2 or 7654321 or 55 are acceptable.

MATCH Xd+

This pattern accepts the letter X followed by one or more digits.

For example, X1 or X2345, and so forth are acceptable, but not X.

MATCH M{A,C,d}+

A plus sign after a pair of braces indicates repetition of any item within the braces, in any order.

Some acceptable values are MA, MCCC, or M12333CAA9.

MATCH d*

The asterisk indicates optional repetition that allows zero or more occurrences of the pattern. Thus, the digit can be omitted, or repeated any number of times.

For example, nothing, or 3, or 123456, and so forth are acceptable matches.

MATCH [d+]

This pattern is another way of expressing the pattern shown above as d*.

MATCH a*

Accepts any alphabetic or empty string.

MATCH Xu*

This pattern accepts X alone, or followed by any number of uppercase letters.

For example, XABC or XX or X are all acceptable.

MATCH M{A,C,d}*

Any of the enclosed characters can be repeated in any order, or can be omitted.

Thus, M is acceptable, as are MAA, MCCAC12, MA63CCA5, and so forth.

Operator Hierarchy

Table 4-5 “Pattern Match Operators” summarizes the operators allowed in a MATCH pattern. The pattern operators are evaluated in the following order, where x and y are any patterns:

 Highest               !x          Transparency
    |                  x:y         Range
    |                  x+ or x*    Repetition
    v                  xy          Concatenation
 Lowest                x,y         Choice

Table 4-5 Pattern Match Operators

Operator	Function	Example
Exclamation point !	Transparency operator that allows use of any special MATCH characters as an element in the pattern.	`MATCH !u,!d,!,,` accepts any of the values `u, d,,, or !`.
Comma ,	Choice of subpatterns, any one of which satisfies the match.	`MATCH A,B, dd` accepts values such as `A,B, and 22`.
Colon:	Range of single characters in ascending collating order, any one of which satisfies the match.	`MATCH 2:6` accepts only the values `2,3,4,5, or 6`.
Braces {}	Required grouping that specifies at least one occurrence of any pattern within braces.	`MATCH {A,B}dd{%,d}` accepts `A223, B34%,A795`, and so forth.
Brackets [ ]	Optional grouping that allows zero or one occurrence of any item in pattern within brackets.	`MATCH [A,B]dd[%,d]` accepts `24,A99, 10%,123`, and so forth.
Plus +	Required repetition that specifies at least one or more occurrences of a preceding item, or a pattern within braces.	`MATCH Xd+` accepts values such as `X1,X22`, `X3334789`, and so forth, but not `X`. `MATCH {d,a} +` accepts values such as `11,A23,acb`, or `33ABC9`.
Asterisk *	Optional repetition that allows zero or more occurrences of a preceding item or a pattern within braces.	`MATCH Xd` accepts values such as `X,X1, X22`, and `X3334789`. `MATCH {d,a}` accepts a null value, or such values as `11,A23,acb`, or `33ABC9`.

Example

Some further examples of the MATCH statement are:

MATCH 1dddd: Accepts an integer between 10000 and 19999. Could also be expressed as: IN 10000:19999.
MATCH [d]d!:dd [AM,PM]: Accepts a time such as 3:00 PM or 12:00.
MATCH {1:9,1(0:2}}!: {0:5}db*[{A,P} [M]]: Accepts 12-hour clock time, such as 12:15 PM or 01:30 AM.
MATCH {1:7}{0:7} *: Accepts an octal number greater than zero with at least one digit and no leading zeros, such as 2047, or 1 or 24.
MATCH ddd-dd-dddd: Accepts any United States Social Security number, such as 044-24-0474.
MATCH [(ddd)]b*ddd- dddd: Accepts a United States phone number with an optional area code.