Find and Replace Text

FindReplace

The FindReplace procedure scans a text string for a pattern and replaces the pattern in the text string with replacement text.

The FindReplace procedure can be used to replace or delete/remove text from an existing character field. The original data is not modified by the procedure. The new value is returned to the caller as the return value for the procedure and may be assigned (copied to) another field or the same field.

varying-length-char-value FindReplace(
  szFindWhat        4096A   Const Varying :
  szReplaceWith     4096A   Const Varying :
  szSearchedText   65535A   Const Varying :
  bOptions             1A   Const Options(*NOPASS : *OMIT) :
  nCount              10I 0 Options(*NOPASS) 
)

Parameters

szFindWhat

[input VChar(*) const]  A varying or fixed-length character value that contains the find text for the search. The text in this parameter is searched for in the szSearchText parameter. By default upper/lower case letters are ignored. You can override this setting by specifying FR_MATCHCASE on the bOptions parameter. Remember when specifying this value that trailing blanks are included. It is recommended to either insert the find text into a character field that also contains the VARYING keyword or pass the value using the %TRIMR built-in function.

szReplaceWith

[input VChar(*) const]  A varying or fixed-length character value that contains the replacement text for the search. The text in this parameter is inserted into the szSearchText in the same location as the original Find Text. By default upper/lower case letters are ignored. To override this setting specify FR_MATCHCASE on the bOptions parameter. Remember when specifying this value that trailing blanks are included. It is recommended to either insert the replacement text into a character field that also contains the VARYING keyword or pass the value using the %TRIMR built-in function.

szSearchedText

[input VChar(*) const]  A varying or fixed-length character value that contains the text to be search.

 

bOptions [optional] DFT(ignore case and find/replace all instances)

[input Char(1) bit mask] A bit field that identifies any variations in the kind of search and replace to be performed. The valid options are as follows:

 

Symbolic Named Constant	Value	Description
FR_FINDFIRST	X'01'	Causes the search to end after one match is detected and replaced.
FR_MATCHCASE	X'02'	Causes the search to use the upper/lower case letters to match the find text.
FR_CHAR	X'04'	Causes the search to be performed individually for each character of the szFind parameter. That is each character in the szFind parameter is located and individually replaced with the szReplace text.

The default for bOptions is not FR_FINDFIRST it means find-all-matches and if it is not FR_MATCHCASE it means ignore upper lower case while searching but respect it when inserting the replacement text. To use this parameter, a bit mask must be created. In RPG IV under OS/400 V5R2 and later use the %BITOR built-in function, under earlier releases, use the BITON operation code as follows:

.....DName+++++++++++EUDS.......Length+TDc.Functions++++++++++++++++++++++++++++

     D bOptions        S              1A   Inz(X'00')

.....CSRn01..............OpCode(ex)Extended-factor2+++++++++++++++++++++++++++++

     C/IF DEFINED(*V5R2M0)                   

     C                   Eval      bOptions = %BITOR(bOptions : FR_FINDFIRST)    

     C/ELSE                   

     C                   BitOn     FR_FINDFIRST  bOptions

     C/ENDIF

nCount [optional]

[output int(4)]  This optional parameter allows you to specify a 10i0 field (Int4)  that receives a count of the number of find/replace actions that occurred.

Return Value

If the function succeeds, the return value is the a varying length text string that contains the modified szSearchText value with the szFindWhat text replaced with the szReplaceWith text. 

If the function fails, the return value is empty.

Remarks

This procedure updates the following exported fields.

• FR_OVERFLOW - Indy: *ON if the result is longer than the original szSearchText field's lengths.
• FR_RESULTLEN - Int(4): Contains the length of the new text with the replacement text inserted. Check this field to determine if your result field was large enough to accommodate the entire replacement string.
• FR_REPLACECNT - Int(4): Indicates the number of times the find/replace action was performed. Use this field or pass the nCount parameter to receive this value.