MATCH

ANSI, NCHAR

The MATCH instruction compares two character strings or two RECORDS. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

source

Required. A previously defined Character String Variable, National Character String Variable, Literal, National Character String Literal, or RECORD that is compared to the {dest} operand.

sep

Required. A comma or one of the following prepositions: BY, TO, OF, FROM, USING, WITH, IN, or INTO.

dest

Required. A previously defined Character String Variable, National Character String Variable, Literal, National Character String Literal, or RECORD that is compared to the {source} operand.

wildcard

Required. A previously defined Character String Variable, National Character String Variable, or constant character indicating source variable wildcard characters.

Flags Affected: EOS, LESS, ZERO

Note the following:

1. Only the Logical String contents of the {source} and {dest} strings are compared.

2. None of the operands, nor their Form Pointers or Length Pointers change.

3. If either operand is a Null String, the LESS and EQUAL Condition Flags are not set (both FALSE) and the EOS Condition Flag is set.

4. The operand length is defined as:
   
   LENGTH = Length Pointer - Form Pointer + 1
    

5. If all characters matched are equal, the EQUAL (or ZERO) Condition Flag is set. The instruction then makes the following calculation:
   
   X = DESTINATION LOGICAL LENGTH - SOURCE LOGICAL LENGTH
   
   If X is negative, the LESS Condition Flag is set.
    

6. If all characters compared are not equal, the instruction makes the following calculation based on the hexadecimal value of the first non-matching character:
   
   X = DESTINATION HEX VALUE - SOURCE HEX VALUE
   
   If X is negative, the LESS Condition Flag is set.
    

7. The optional third parameter ({wildcard}) specifies a character that is treated as a don't care or wildcard character. If the specified character exists in the {source} operand, it matches any character in the destination operand that occupies the same relative position. If {wildcard} is a character string variable, the Form Pointed character is used.

8. If the operands are RECORDs, the corresponding members of each record are matched. The MATCH operation is an absolute comparison of each byte in {source} to the corresponding byte in {dest}. The comparison is not being performed on a per member basis and therefore the {wildcard} parameter is not allowed. Specification of the {wildcard} parameter will produce a warning message by the compiler. The MATCH instruction does not support record pointers.

See Also: Example Code, CMATCH, Character String Instructions