This procedure compares two strings, TEXT1 and TEXT2, using a binary, equivalent or logical comparison, specified in ORD_TYPE. The starting position for the comparison is specified for each record, along with the compare relationship to be checked.

A binary comparison is based on the hexadecimal code values of the characters. An equivalent comparison is based on the ordering sequence values (OSVs) of the characters. A logical comparison is based on the OSVs plus the priority sequence values (PSVs). These OSVs and PSVs are retrieved from the SYSTEM/CCSFILE based on the ccsversion.

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 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

  DEFINE TEXT1_START = 0 #
       ,TEXT2_START = 0 #;

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

  VSN_NUM := 74;
  COMPARE_LEN := MIN(SIZE(TEXT1), SIZE(TEXT2));
  REPLACE TEXT1 BY "hotel";
  REPLACE TEXT2 BY "hôtel";
  RESULT := VSNCOMPARE_TEXT(VSN_NUM, TEXT1, TEXT1_START, TEXT2,
            TEXT2_START, COMPARE_LEN, CS_CMPEQLV, CS_LOGICALV);
  WRITE(OUT,<"RESULT = ",J4>,RESULT);
  CLOSE(OUT,LOCK);
END.

Output

RESULT = 0

In this call, the parameters have the following meanings:

VSN_NUM is an integer passed to the procedure. It contains the number of the ccsversion that is used to compare TEXT1 and TEXT2. The number can be obtained by referring to the MultiLingual System Administration, Operations, and Programming Guide. The following shows the valid values:

TEXT1 is an EBCDIC array passed to the procedure. It contains the first text to be compared.

TEXT1_START is an integer passed to the procedure. It contains the byte offset (0 relative) of TEXT1 where the comparison starts.

TEXT2 is a record passed to the procedure. It contains the last text to be compared.

TEXT2_START is an integer passed to the procedure. It contains the byte offset (0 relative) of TEXT2 where the comparison starts.

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 TEXT1 array or the TEXT2 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 indicates that TEXT1 is equal to TEXT2. It is one of six comparison options:

CS_LOGICALV represents an integer that indicates that a logical comparison is to be done. It is one of two options.

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: