compareStr()

The system function StrLib.compareStr compares two substrings in accordance with their ASCII or EBCDIC order at run time.

  StrLib.compareStr(
    target a character type in,
    targetSubstringIndex INT in,
    targetSubstringLength INT in,
    source a character type in,
    sourceSubstringIndex INT in,
    sourceSubstringLength INT in  )
  returns (result INT)
result
Numeric field that receives one of the following values (defined as type INT or the equivalent: type BIN with length 9 and no decimal places) returned by the function:
-1
The substring based on target is less than the substring based on source
0
The substring based on target is equal to the substring based on source
1
The substring based on target is greater than the substring based on source
target
String from which a target substring is derived. Can be a field or a literal.
targetSubStringIndex
Identifies the starting byte of the substring in target, given that the first byte in target has the index value 1. This index can be an integer literal. Alternatively, this index can be a field defined as type INT or the following equivalent: type BIN with length 9 and no decimal places.
targetSubStringLength
Identifies the number of bytes in the substring that is derived from target. The length can be an integer literal. Alternatively, this index can be a field defined as type INT or the following equivalent: type BIN with length 9 and no decimal places.
source
String from which a source substring is derived. Can be a field or a literal.
sourceSubStringIndex
Identifies the starting byte of the substring in source, given that the first byte in source has the index value of 1. This index can be an integer literal. Alternatively, this index can be a field defined as type INT or the following equivalent: type BIN with length 9 and no decimal places.
sourceSubStringLength
Identifies the number of bytes in the substring that is derived from source. The length can be an integer literal. Alternatively, this index can be a field defined as type INT or the following equivalent: type BIN with length 9 and no decimal places.

A byte-to-byte binary comparison of the substring values is performed. If the substrings are not the same length, the shorter substring is padded with spaces before the comparison.

Definition considerations

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

Example

  target = "123456";
  source = "34";
  result = 
    StrLib.compareStr(target,3,2,source,1,2);
  // result = 0
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.