This procedure compares two strings using the ordering information returned by VSNORDERING_INFO. A starting position can be given for each piece of text, along with the compare relationship to be checked. One of the following methods of comparison can be chosen:

Example

This example compares two strings using the CanadaEBCDIC ccsversion. The compare relation is CS_CMPEQLV(=) to determine if one string is equal to another, using a logical comparison. The ORDER_ARY is obtained by calling the VSNORDERING_INFO procedure. This call obtains the ORDER_ARY for the CanadaEBCDIC ccsversion. The MultiLingual System Administration, Operations, and Programming Guide can be used to determine that the ccsversion number for CanadaEBCDIC is 74. This number can also be retrieved by calling VALIDATE_NAME_RETURN_NUM with the name CanadaEBCDIC.

BEGIN

 $ INCLUDE INTL="SYMBOL/INTL/ALGOL/PROPERTIES." 10000000 - 49999999

  FILE OUT(KIND=DISK,UNITS=CHARACTERS,FILEUSE=IO,FILETYPE=0,NEWFILE,
           MAXRECSIZE=80,TITLE="OUT/ALGOL/COMP_TEXT_ORD_INF.");
  EBCDIC ARRAY TEXT1[0:4]
             ,TEXT2[0:4];
  REAL ARRAY ORDER_ARY[0:255];
  POINTER P_TEXT1
        ,P_TEXT2;
  INTEGER COMPARE_LEN
        ,VSN_NUM
        ,RESULT;

  VSN_NUM:= 74;                                   % Canada EBCDIC
  RESULT := VSNORDERING_INFO(VSN_NUM, ORDER_ARY);
  IF RESULT EQL CS_DATAOKV THEN
     BEGIN
     COMPARE_LEN := MIN(SIZE(TEXT1), SIZE(TEXT2));
     P_TEXT1 := TEXT1[0];
     P_TEXT2 := TEXT2[0];
     REPLACE TEXT1 BY "hotel";
     REPLACE TEXT2 BY "hôtel";

RESULT := COMPARE_TEXT_USING_ORDER_INFO(P_TEXT1, P_TEXT2,
               COMPARE_LEN, CS_CMPEQLV, CS_LOGICALV, ORDER_ARY);
     WRITE(OUT,<"RESULT = ",J4>,RESULT);
     END;
  CLOSE(OUT,LOCK);
END.

Output

RESULT = 0                  % The strings are not equal

In this call, the parameters have the following meanings:

P_TEXT1 is a POINTER array passed to the procedure. It contains the first string to be compared.

P_TEXT2 is a POINTER array passed to the procedure. It contains the other string to be compared.

COMPARE_LEN is an integer passed to the procedure. It designates the number of characters to be compared. If COMPARE_LEN is larger than the number of characters in the strings, then the procedure might be comparing invalid data. The value of COMPARE_LEN should not exceed the bounds of either the PTEXT1 array or the PTEXT2 array. The strings should be of equal size or padded with blanks up to COMPARE_LEN. If all pairs of characters compare equally through the last pair, the strings are considered equal. The first pair of unequal characters to be encountered is compared to determine their relative ordering. The string that contains the character with the higher ordering (higher OSV and PSV) is considered to be the greater string. If, because of substitution, the strings become of unequal size, the comparison proceeds as if the shorter string had been expanded by blanks on the right to make it equal in size to the longer string.

CS_CMPEQLV represents an integer that compares TEXT1 to TEXT2. This is one of 6 compare relation options:

CS_LOGICALV represents an integer that specifies a logical comparison. It is one of two options:

ORDER_ARY is a REAL array passed to the procedure. It contains the ordering information to be used to compare the strings. Ordering information can be obtained using the VSNORDERING_INFO procedure. It is recommended that the size of this array be 256 words. The layout of ORDER_ARY can be found in the VSNORDERING_INFO procedure later in this section.

RESULT is an integer returned by the procedure. It indicates whether or not an error occurred during the execution of the procedure. An explanation of the error result values and messages can be found at the end of this section.

The values returned by this procedure include: