RPG/400 Help

SCAN (Scan Character String)

*---------*---------------*-----------------*----------------*---------------*
|   CODE  |    FACTOR 1   |     FACTOR 2    |     RESULT     |  INDICATORS   |
|         |               |                 |      FIELD     |               |
*---------*---------------*-----------------*----------------*---------------*
| SCAN    | Comparator    | Base            | Left-          |   _ ER FD     |
|         | string:length | string:start    | most           |               |
|         |               |                 | position       |               |
*---------*---------------*-----------------*----------------*---------------*

The SCAN operation scans a character string (base string) contained in factor 2 for a substring (compare string) contained in factor 1. The scan begins at a specified location contained in factor 2 and continues for the length of the compare string which is specified in factor 1.

Factor 1 must contain either the compare string or the compare string, followed by a colon, followed by the length. The compare string portion of factor 1 must be character, and can contain one of: a field name, array element, named constant, data structure name, literal, or table name. The length portion must be numeric with no decimal positions and can contain one of: a named constant, array element, field name, literal, or table name. If no length is specified, it is that of the compare string.

Factor 2 must contain either the base string or the base string, followed by a colon, followed by the start location of the SCAN. The base string portion of factor 2 must be character, and can contain one of: a field name, array element, named constant, data structure name, literal, or table name. The start location portion of factor 2 must be numeric with no decimal positions and can be a named constant, array element, field name, literal, or table name. If no start location is specified, a value of 1 is used.

The result field contains the numeric value of the leftmost position of the compare string in the base string, if found. It must be numeric with no decimal positions and can contain one of: a field name, array element, array name, or table name. If no result field is specified, a resulting indicator in positions 58 and 59 must be specified. The result field is set to 0 if the string is not found. If the result field contains an array, each occurrence of the compare string is placed in the array with the leftmost occurrence in element 1. The array elements following the element containing the rightmost occurrence are all zero. The result array should be as large as the character field length of the base string specified in factor 2.

Note:
The strings are indexed from position 1. If the start position is greater than 1, the result field contains the position of the compare string relative to the beginning of the source string, not relative to the start position. Figurative constants cannot be used in the factor 1, factor 2, or result fields. No overlapping within data structures is allowed for factor 1 and the result field or factor 2 and the result field.

A resulting indicator in positions 58 and 59 can be specified to be set on if the string being scanned for is found. A resulting indicator in positions 56 and 57 can be specified to be set on if there is an error during the SCAN operation. An error occurs if the start position is greater than the length of factor 2 or if the value of factor 1 is too large. If no error indicator is specified and an error condition occurs, *PSSR, the error/exception handling subroutine runs (if it is specified in the program). If it is not specified, an error message is issued.

The SCAN begins at the leftmost character of factor 2 (as specified by the start location) and continues character by character, from left to right, comparing the characters in factor 2 to those in factor 1. If the result field is not an array, the SCAN operation will locate only the first occurrence of the compare string. To continue scanning beyond the first occurrence, use the result field from the previous SCAN operation to calculate the starting position of the next SCAN. If the result field is a numeric array, as many occurrences as there are elements in the array are noted. If no occurrences are found, the result field is set to zero; if the result field is an array, all its elements are set to zero.

Leading, trailing, or embedded blanks specified in the compare string are included in the SCAN operation.

The SCAN operation is case-sensitive. A compare string specified in lowercase will not be found in a base string specified in uppercase.

Figure "SCAN Operation" shows examples of the SCAN operation.

SCAN Examples

Figure 50. SCAN Operation

*...1....+....2....+....3....+....4....+....5....+....6....+....7...
CL0N01N02N03Factor1+++OpcdeFactor2+++ResultLenDHHiLoEqComments++++++
C*
C* The SCAN operation finds the substring 'ABC' starting in
C* position 3 in factor 2;  3 is placed in the result field.
C* Indicator 90 is set on because the string is found.  Because
C* no starting position is specified, the default of 1 is used.
C           'ABC'     SCAN 'XCABCD'  RESULT         90
C*
C* This SCAN operation scans the string in factor 2 for an
C* occurrence of the string in factor 1 starting at position 3.
C* The operation places the values 5 and 6 in the first and
C* second elements of the array.  Indicator 90 is set on.
C                     MOVE 'ARRAYY'  FIELD1   6
C                     MOVE 'Y'       FIELD2   1
C           FIELD2    SCAN FIELD1:3  ARRAY          90
C*
C* This SCAN operation scans the string in factor 2, starting
C* at position 2, for an occurrence of the string in factor 1
C* for a length of 4.  Because 'TOOL' is not found in FIELD1,
C* INT is set to zero and indicator 90 is set off.
C                     MOVE 'TESTING' FIELD1   7
C                     Z-ADD2         X        10
C                     MOVEL'TOOL'    FIELD2   5
C           FIELD2:4  SCAN FIELD1:X  INT      20    90
C*


[ Top of Page | Previous Page | Next Page | Table of Contents ]