%SCAN (Scan for Characters)

%SCAN(search argument : source string {: start position {: length}})

%SCAN returns the first position of the search argument in the source string, or 0 if it was not found.

The start position and length specify the substring of the source string to be searched. The start position defaults to 1 and the length defaults to the remainder of the source string. The result is always the position in the source string even if the starting position is specified.

The first parameter must be of type character, graphic, or UCS-2. The second parameter must be the same type as the first parameter. The third and fourth parameters, if specified, must be numeric with zero decimal positions.

When any parameter is variable in length, the values of the other parameters are checked against the current length, not the maximum length.

The type of the return value is numeric. This built-in function can be used anywhere that a numeric expression is valid.

If the search argument contains trailing blanks, the scan will include those trailing blanks. For example if 'b' represents a blank, %SCAN('12b':'12312b') would return 4. If trailing blanks should not be considered in the scan, use %TRIMR on the search argument. For example %SCAN(%TRIMR('12b'):'12312b') would return 1.

For more information, see String Operations or Built-in Functions.

Note: Unlike the SCAN operation code, %SCAN cannot return an array containing all occurrences of the search string and its results cannot be tested using the %FOUND built-in function.

%SCAN Example

Consider the following definitions

 *..1....+....2....+....3....+....4....+....5....+....6....+....7...+....
D*Name++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++
D source          S             15A   inz ('Dr. Doolittle')
D pos             S              5U 0
D posTrim         S              5U 0
D posVar          S              5U 0
D srchFld         S             10A
D srchFldVar      S             10A   varying


     pos = %scan ('oo' : source);

After the previous assignment, the value of pos is 6 because 'oo' begins at position 6 in 'Dr. Doolittle'.


     pos = %scan ('D' : source : 2);

After the previous assignment, the value of pos is 5 because the first 'D' found, starting from position 2, is in position 5.


     pos = %scan ('D' : source : 2 : 3);

After the previous assignment, the value of pos is 0 because no 'D' is found starting at position 2 for a length of 3.


     pos = %scan ('D' : source : 2 : 4);

After the previous assignment, the value of pos is 5 because the 'D' is found when the search starts at position 2 for a length of 4.


     pos = %scan ('abc' : source);

After the previous assignment, the value of pos is 0 because 'abc' is not found in 'Dr. Doolittle'.


     pos = %scan ('Dr.' : source : 2);

After the previous assignment, the value of pos is 0 because 'Dr.' is not found in 'Dr. Doolittle', if the search starts at position 2.


     srchFld = 'Dr.';
     srchFldVar = 'Dr.';
     pos = %scan (srchFld : source);
     posTrim = %scan (%trimr(srchFld) : source);
     posVar = %scan (srchFldVar : source);

After the previous statements, the value of pos is 0 because srchFld is a 10-byte field, so the search argument is 'Dr.' followed by seven blanks. However, the values of posTrim and posVar are both 1, since the %TRIMR and srchFldVar scans both use a 3-byte search argument 'Dr.', with no trailing blanks.

For an example comparing %SCAN and %SCANR, see Example using %SCAN and %SCANR together.