MATCHLIST

The MATCHLIST instruction matches or compares each variable in the source operand to the corresponding variable in the destination operand using a single instruction. The source and destination operands must be RECORD or VARLIST types. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

source

Required. A RECORD or VARLIST variable that serves as the source operand and contains the individual variables to be matched or compared.

sep

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

dest

Required. A RECORD or VARLIST variable that serves as the destination operand and contains the individual variables to be matched or compared.

Flags Affected: EOS, LESS, OVER, ZERO

Note the following:

1. The {source} and {dest} RECORDs or VARLISTs do not have to be identical when using MATCHLIST.

2. RECORD variables are processed recursively. All variables contained within nested RECORD definitions are included in the MATCHLIST processing operation.

3. Array elements contained within RECORDs or VARLISTs are processed individually as part of the variable list.

4. When the RECORD or VARLIST source variable is a DIM or NCHAR type and the corresponding destination variable is also a DIM or NCHAR type, these variables are matched as follows:

 

1.   If both the source and destination variables are NULL Strings, then the variables are equal.

2.   If both the source and destination variables are not NULL Strings, the variables are equal only when they have the same logical length and their data contents are equal. Otherwise, MATCHLIST quits with the ZERO flag cleared.

3.   DIM and NCHAR comparisons are case-sensitive.

4.   If one variable is a DIM or NCHAR type and the other variable is not a DIM or NCHAR type, the variables are not equal and MATCHLIST quits with the ZERO flag cleared.

 

5. When the RECORD or VARLIST source variable is a FORM or INTEGER type and the corresponding destination variable is also a FORM or INTEGER type, these numeric variables are compared as follows:

 

1.   If the actual content values of the source and destination variables are equal, MATCHLIST continues executing with the ZERO flag set TRUE. Otherwise, MATCHLIST quits with the ZERO flag cleared.

2.   If the source variable is a FORM or INTEGER type and the destination variable is not a FORM or INTEGER type, the variables are not equal and MATCHLIST quits with the ZERO flag cleared.

 

6. When the RECORD or VARLIST source variable is a GUI objec type and the corresponding destination variable is also a GUI object type, these variables are matched as follows:

 

1.   If both the source and destination variables are GUI objects and the object types are the same, MATCHLIST continues executing with the ZERO flag set TRUE. Otherwise, MATCHLIST quits with the ZERO flag cleared.

2.   GUI object created and not created states are not included in the MATCHLIST comparison operation.

3.   GUI object variables may exist in RECORD variables and LIST variables. However, GUI object variables are not allowed in VARLIST declarations.

 

7. If the number of variables is different in the source and destination operands, MATCHLIST processes the match and comparison operations until the smallest variable list is exhausted or until the ZERO flag is cleared.

8. The EOS and LESS flags are always cleared.

9. The OVER flag is set TRUE if an unknown variable type is encountered in the source or destination variable lists. Otherwise, the OVER flag is cleared.

10. The ZERO flag is set TRUE if all tested variables in the source and destination operands match or compare equal. Otherwise, MATCHLIST quits when a match or comparison operation results in a not equal condition and the ZERO flag is cleared.

11. The following example demonstrates MATCHLIST processing for RECORD, LIST, nested RECORD, GUI object, and unequal variable count comparisons:

LIST1 LIST

Rec1 RECORD (3)

A DIM 5

B BUTTON

Recx RECORD

X INIT "X"

             RECORDEND

             RECORDEND

             LISTEND

.

LIST2 LIST

Rec2 RECORD (3)

A1 DIM 10

B1 BUTTON

Recxx RECORD

X1 INIT "X"

             RECORDEND

             RECORDEND

             LISTEND

.

arr DIM 5(3)

.

ListX LIST

A INIT "A"

B INIT "B"

             LISTEND

.

ListX1 LIST

A1 INIT "A"

B1 INIT "B"

C1 INIT "C"

             LISTEND

.

*...............................................................

.

.....

    MOVE "XY", Rec1(1).A, Rec2(1).A1

.

    MATCHLIST Rec1(1), Rec2(1)

    IF EQUAL

      DISPLAY "EQUAL...: MATCHLIST Rec1(1), ":

                "Rec2(1) --> Expected"

    ELSE

      DISPLAY "NOT EQUAL...: MATCHLIST Rec1(1), "":

                "Rec2(1) --> NOT Expected"

    ENDIF

.....

    MATCHLIST List1, List2

    IF EQUAL

      DISPLAY "EQUAL...: MATCHLIST List1, List2 ":

                "--> Expected"

    ELSE

      DISPLAY "NOT EQUAL...: MATCHLIST List1, List2 ":

                "--> NOT Expected"

    ENDIF

.....

    MOVE "XYZ", Rec2(1).A1

.

    MATCHLIST Rec1(1), Rec2(1)

    IF EQUAL

      DISPLAY "EQUAL...: MATCHLIST Rec1(1), Rec2(1) ":

                "--> NOT Expected"

    ELSE

      DISPLAY "NOT EQUAL...: MATCHLIST Rec1(1), Rec2(1) ":

                "--> Expected"

    ENDIF

.....

    MATCHLIST ListX, ListX1

    IF EQUAL

      DISPLAY "EQUAL...: MATCHLIST ListX, ListX1 ":

                "--> Expected"

    ELSE

      DISPLAY "NOT EQUAL...: MATCHLIST ListX, ListX1 ":

                "--> NOT Expected"

    ENDIF

.....

    MATCHLIST ListX1, ListX

    IF EQUAL

      DISPLAY "EQUAL...: MATCHLIST ListX1, ListX ":

           "--> Expected"

    ELSE

      DISPLAY "NOT EQUAL...: MATCHLIST ListX1, ListX ":

                "--> NOT Expected"

    ENDIF

.....

    KEYIN "Hit enter to exit: ", S$CMDLIN

.

    STOP

See Also: MATCH, CMATCH, Character String Instructions