Guru Classic: A Bevy Of BIFs – %ScanRpl (Scan And Replace)

January 8, 2020 Jon Paris

This gem of a BIF was introduced with the V7.1 release and so was not available some five years ago when I wrote my original Bevy series of tips. Now that most active development shops are running V7.1 and later it seems a good candidate for a “Classic” to remind readers of its capabilities. The intervening years have not dimmed its utility and it remains one of my all-time favorite BIFs.

Simply put, %ScanRpl will search a target string for a given character sequence and replace it with another. Not only that but it will then continue to search through the target string and perform the replacement as many additional times as needed. Prior to the arrival of this new BIF, performing this kind of “mail merge” operation required you to manually code a loop comprising a %Scan and a %Replace operation.

The basic syntax for the BIF is:

%SCANRPL(scan string : replacement : source { : scan start { : scan length } )

Most of the time you will only need to use the first three parameters to do the job. But as you can see you can also optionally control the search start position and length of the string to be scanned if desired.

For example, the following code will replace all instances of &Name in the string baseText with the content of the custName variable. The resulting string is placed in the variable outputText.

outputText = %ScanRpl( '&Name' : custName : baseText );

This example assumes that custName is a variable length field with no trailing spaces. But if it were a fixed length field we could deal with that by simply trimming the field when passing it, like so:

outputText = %ScanRpl( '&Name': %TrimR( custName ): baseText );

It is important to note that just as with its predecessor, the %Replace BIF, %ScanRpl can replace a short string with a longer one, or vice versa. In fact it can even be used to remove unwanted characters completely from a string by replacing them with a null string. In the example below all commas in baseText are removed (i.e. they are replaced by a null string).

outputText = %ScanRpl( ',' : '' : baseText );

An “Interesting” Example

At first glance, you might think that %SCANRPL could be used to replace a sequence of consecutive spaces by a single space. Certainly that will work if you want to replace two spaces by one, like this:

// First parm is 2 spaces, second parm is a single space
outputText = %ScanRpl( '  ' : ' ' : baseText );

But typically you won’t know in advance exactly how many spaces you’ll need to replace. Using this method, if there were three or more spaces – you would still end up with more spaces than you want. Why? Because a single space will replace each pair of spaces in the original string. So three or four consecutive spaces would still result in two spaces in the output. You could put the statement above in a loop and implement some method to determine when to stop looping, but that would be even less efficient than other techniques such as simply using %Scan followed by %Replace in a loop.

The following code, while almost certainly not the most efficient way to do it, will achieve the task. Sometimes I just like to explore different coding techniques and when I first came upon this approach I thought it would make an interesting example of how %ScanRpl could be used, so here it is.

The task is to replace all instances of two or more spaces in a string leaving only single spaces between “words.” Here’s the %SCANRPL code to achieve this:

     dcl-s baseString char(38)   Inz('3 spc   4 spc    5 spc     End');   
     dcl-s result varChar(38);
(a)  result = %ScanRpl( ' ': '<>': baseString ); // 1st parm is 1 space
     dsply ('Contents: ' + result );
(b)  result = %ScanRpl( '><': '': result );  // 2nd parm is null string
     dsply ('Contents: ' + result );
(c)  result = %ScanRpl( '<>': ' ': result );
     dsply ('Contents: ' + result ); 
     dsply ('Length of result is ' + %Char(%Len(result)));

As you can see, I have interspersed dsply operations so that when you run the code you can see the effect of each stage. At the first step (a) every single space is replaced by the characters ‘<>’. Next (b) we remove all occurrences of ‘><‘ and replace them with nothing (i.e. a null string). At this point, no matter how many spaces we had to start with, we will be left with the string ‘<>’ in their place. So at (c) we replace that string with a single space. That’s all there is to it.

Jon Paris is one of the world’s foremost experts on programming on the IBM i platform. A frequent author, forum contributor, and speaker at User Groups and technical conferences around the world, he is also an IBM Champion and a partner at Partner400 and System i Developer. He hosts the RPG & DB2 Summit twice per year with partners Susan Gantner and Paul Tuohy.

RELATED STORY

A Bevy Of BIFs: %ScanRpl (Scan And Replace)