%SCANRPL(scan string : replacement : source { : scan start { : scan length } )%SCANRPL returns the string produced by replacing all occurrences of the scan string in the source string with the replacement string. The search for the scan string starts at the scan start position and continues for the scan length. The parts of the source string that are outside the range specified by the scan start position and the scan length are included in the result.
The first, second and third parameters must be of type character, graphic, or UCS-2. They can be in either fixed-length or variable-length format. These parameters must all be of the same type and CCSID.
The fourth parameter represents the starting position, measured in characters, where the search for the scan string should begin. If it is not specified, the starting position defaults to one. The value may range from one to the current length of the source string.
The fifth parameter represents the number of characters in the source string to be scanned. If the parameter is not specified, the length defaults to remainder of the source string starting from the start position. The value must be greater than or equal to zero, and less than or equal to the remaining length of the source string starting at the start position.
The starting position and length may be any numeric value or numeric expression with no decimal positions.
The returned value may be larger, equal to or smaller than the source string. The resulting length depends on the lengths of the scan string and the replacement string, and also on the number of times the replacement is performed. For example, assume the scan string is 'a' and the replacement string is 'bc'. If the source string is 'ada', the returned value has a length of five ('bcdbc'). If the source string is 'ddd', the returned value has a length of three ('ddd').
The returned value is varying length if the source string and replacement string have different lengths, or if any of the strings are varying length. Otherwise, the returned value is fixed length. The returned value has the same type as the source string.
Each position in the source string is scanned only once. For example, if the scan string is 'aa', and the source string is 'baaaaac', then the first match is in positions 2 and 3. The next scan begins at position 4, and finds a match in positions 4 and 5. The next scan begins at position 6, and does not find any further matches. If the replacement string is 'xy', then the returned value is 'bxyxyac'.
Tip: %SCANRPL can be used to completely remove occurrences of the scan string from the source string by specifying an empty replacement string.
For more information, see String Operations or Built-in Functions.
// ....+....1....+....2....+....3....+...
string1 = 'See NAME. See NAME run. Run NAME run.';
// 1. All occurrences of "NAME" are replaced by the
// replacement value. In the first case,
// the resulting string is shorter than the source
// string, since the replacment string is shorter
// than the scan string. In the second case, the
// resulting string is longer.
string2 = %ScanRpl('NAME' : 'Tom' : string1);
// string2 = 'See Tom. See Tom run. Run Tom run.'
string2 = %ScanRpl('NAME' : 'Jenny' : string1);
// string2 = 'See Jenny. See Jenny run. Run Jenny run.'
// 2. All occurrences of ** are removed from the string.
// The replacement string, '', has zero length.
string3 = '*Hello**There**Everyone*';
string2 = %ScanRpl('**' : '' : string3);
// string2 = '*HelloThereEveryone*'
// 3. All occurrences of "NAME" are replaced by "Tom"
// starting at position 6. Since the first "N" of
// the first "NAME" in the string is not part of the
// source string that is scanned, the first "NAME"
// is not considered replaceable.
string2 = %ScanRpl('NAME' : 'Tom' : string1 : 6);
// string2 = 'See NAME. See Tom run. Run Tom run.'
// 4. All occurrences of "NAME" are replaced by "Tom"
// up to length 31. Since the final "E" of
// the last "NAME" in the string is not part of the
// source string that is scanned, , the final "NAME"
// is not considered replaceable.
string2 = %ScanRpl('NAME' : 'Tom' : string1 : 1 : 31);
// string2 = 'See Tom. See Tom run. Run NAME run.'
// 5. All occurrences of "NAME" are replaced by "Tom"
// from position 10 for length 10. Only the second
// "NAME" value falls in that range.
string2 = %ScanRpl('NAME' : 'Tom' : string1 : 10 : 10);
// string2 = 'See NAME. See Tom run. Run NAME run.'