%SCAN(search argument : source string {: start})
%SCAN returns the first position of the search argument in the source string, or 0 if it was not found. If the start position is specified, the search begins at the starting position. The result is always the position in the source string even if the starting position is specified. The starting position defaults to 1.
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 parameter, 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 unsigned integer. This built-in function can be used anywhere that an unsigned integer 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.
*..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
/FREE
pos = %scan ('oo' : source);
// After the EVAL, pos = 6 because 'oo' begins at position 6 in
// 'Dr. Doolittle'.
pos = %scan ('D' : source : 2);
// After the EVAL, pos = 5 because the first 'D' found starting from
// position 2 is in position 5.
pos = %scan ('abc' : source);
// After the EVAL, pos = 0 because 'abc' is not found in
// 'Dr. Doolittle'.
pos = %scan ('Dr.' : source : 2);
// After the EVAL, pos = 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 EVAL, pos = 0 because srchFld is a 10-byte field, so
// the search argument is 'Dr.' followed by seven blanks. However,
// posTrim and posVar are both 1, since the %TRIMR and srchFldVar
// scans both use a 3-byte search argument 'Dr.', no trailing blanks.
/END-FREE