%REPLACE (Replace Character String)

%REPLACE(replacement string: source string{:start position {:source
length to replace { : *NATURAL | *STDCHARSIZE}}})

%REPLACE returns the character string produced by inserting a replacement string into the source string, starting at the start position and replacing the specified number of characters.

The first and second parameter must be of type character, graphic, or UCS-2 and can be in either fixed- or variable-length format. The second parameter must be the same type as the first.

The third parameter represents the starting position, measured in characters, for the replacement string. If it is not specified, the starting position is at the beginning of the source string. The value may range from one to the current length of the source string plus one. It may be any numeric value or numeric expression with no decimal positions.

The fourth parameter represents the number of characters in the source string to be replaced. If zero is specified, then the replacement string is inserted before the specified starting position. If the parameter is not specified, the number of characters replaced is the same as the length of the replacement string. The value must be greater than or equal to zero, and less than or equal to the current length of the source string. It may be any numeric value or numeric expression with no decimal positions.

The third, fourth, or fifth parameter can be *NATURAL or *STDCHARSIZE to override the current CHARCOUNT mode for the statement. If this parameter is specified, it must be the last parameter.

Specify *NATURAL to indicate that %REPLACE operates in CHARCOUNT NATURAL mode. The start position and length value are measured in characters rather than bytes or double bytes. For example, if the source string is a UTF-8 string with the value 'ábç12', with CHARCOUNT NATURAL mode, a start position of 3 refers to 'ç' because that is the third character in the string.
Specify *STDCHARSIZE to indicate that %REPLACE operates in CHARCOUNT STDCHARSIZE mode. In the previous example, with CHARCOUNT STDCHARSIZE mode, a start position of 3 refers to 'b' because it is the third byte in the string. Characters 'á' and 'ç' are 2-byte characters.

See Processing string data by the natural size of each character and Character Data Type.

Note: %REPLACE can also operate in CHARCOUNT NATURAL mode due to the /CHARCOUNT compiler directive or the CHARCOUNT Control keyword.

The returned value is varying length if the source string or replacement string are varying length, or if the start position or source length to replace are variables, or if CHARCOUNT NATURAL mode is in effect. Otherwise, the result is fixed length.

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

Figure 1. %REPLACE Example

 *..1....+....2....+....3....+....4....+....5....+....6....+....7...+....
D*Name++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++
D var1            S             30A   INZ('Windsor') VARYING
D var2            S             30A   INZ('Ontario') VARYING
D var3            S             30A   INZ('Canada') VARYING
D fixed1          S             15A   INZ('California')
D date            S               D   INZ(D'1997-02-03')
D result          S            100A   VARYING

 /FREE
     result = var1 + ', ' + 'ON';
  // result = 'Windsor, ON'
 
  // %REPLACE with 2 parameters to replace text at begining of string:
     result = %replace ('Toronto': result);
  // result = 'Toronto, ON'
 
  // %REPLACE with 3 parameters to replace text at specified position:
     result = %replace (var3: result: %scan(',': result) + 2);
  // result = 'Toronto, Canada'
 
  // %REPLACE with 4 parameters to insert text:
     result = %replace (', ' + var2: result: %scan (',': result): 0);
  // result = 'Toronto, Ontario, Canada'
 
  // %REPLACE with 4 parameters to replace strings with different length
     result = %replace ('Scarborough': result:
    1: %scan (',': result) - 1);
  // result = 'Scarborough, Ontario, Canada'
 
  // %REPLACE with 4 parameters to delete text:
     result = %replace ('': result: 1: %scan (',': result) + 1);
  // result = 'Ontario, Canada'
 
  // %REPLACE with 4 parameters to add text to the end of the string:
     result = %replace (', ' + %char(date): result:
   %len (result) + 1: 0);
  // result = 'Ontario, Canada, 1997-02-03'
 
  // %REPLACE with 3 parameters to replace fixed-length text at
  // specified position:  (fixed1 has fixed-length of 15 chars)
     result = %replace (fixed1: result: %scan (',': result) + 2);
  // result = 'Ontario, California     -03'
 
  // %REPLACE with 4 parameters to prefix text at beginning:
     result = %replace ('Somewhere else: ': result: 1: 0);
  // result = 'Somewhere else: Ontario, California     -03'
 /END-FREE