compareStr()

The vgLib.compareStr() system function compares two substrings according to their ASCII or EBCDIC order at run time.

vgLib.compareStr() is one of a number of functions maintained for compatibility with earlier versions. New code can use standard EGL operators for these purposes.

EGL performs a byte-to-byte comparison of the values. If the values are not the same length, EGL pads the shorter value with blanks, even that if value is numeric.

Syntax

  vgLib.compareStr(
    var1 CharType in,
    var1SubstrIndex INT in,
    var1SubstrLength INT in,
    var2 CharType in,
    var2SubstrIndex INT in,
    var2SubstrLength INT in  )
  returns (result INT)

var1

Value from which the first comparison substring is derived. Can be a variable or a literal.

var1SubstrIndex

Identifies the starting byte of the substring in var1, given that the index value of the first byte is 1. This index can be an integer literal or variable (INT or BIN(9)).

var1SubstrLength

Identifies the number of bytes in the substring that is derived from var1. The length can be an integer literal or variable (INT or BIN(9)).

var2

Value from which the second comparison substring is derived. Can be a variable or a literal.

var2SubstrIndex

Identifies the starting byte of the substring in var2, given that the first byte in source has the index value of 1. This index can be an integer literal or variable (INT or BIN(9)).

var2SubstrLength

Identifies the number of bytes in the substring that is derived from var2. The length can be an integer literal or variable (INT or BIN(9)).

result

One of the following integer values (INT or BIN(9)) returned by the function:

-1: The substring based on var1 is less than the substring based on var2
0: The substring based on var1 is equal to the substring based on var2
1: The substring based on var1 is greater than the substring based on var2

Error considerations

If you use V6 exception compatibility (see Using V6 exception compatibility), the following values are returned in sysVar.errorCode:

8: Index less than 1 or greater than string length.
12: Length less than 1.
20: Index for a DBCHAR or UNICODE string points to middle of double-byte character
24: Length in bytes for a DBCHAR or UNICODE string is odd (double-byte lengths must always be even).

Example

The following example illustrates the use of the vgLib.compareStr() function.

target, source CHAR (6);
result INT;
target = "123456";
source = "34";
result = vgLib.compareStr(target,3,2,source,1,2); // result = 0

Compatibility

Table 1. Compatibility considerations for vgLib.compareStr()
Platform	Issue
COBOL generation	NUM is a legal type for the source or target variable