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

September 24, 2014 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 more people have V7.1 in their shops, I decided it was time to revisit the series and add it to the collection. It is probably my all-time favorite BIF . . . at least so far.

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.

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

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

This example assumes that custName is a variable length field, but if that were not the case we would simply need to trim the parameter 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. For example, you could easily remove a CRLF sequence at the end of a text line.

An “Interesting” Example

I’m not suggesting that the following code is necessarily the best way to achieve the task, but sometimes I like to explore different ways of doing things. When I first saw this technique I thought it would make an interesting example of how %ScanRpl could be used, so here it is.

Here’s the task. Replace all instances of two or more spaces in a string leaving only single spaces between “words”. The following code will achieve this:

    dcl-s baseString char(38)  
          Inz('4 spc    5 spc     6 spc      2 more  ');
  
    dcl-s result     varChar(38);

(a) result = %ScanRpl( ' ': '<>': baseString ); 

    dsply ('Contents: ' + result );

(b) result = %ScanRpl( '><': '': result ); 

    dsply ('Contents: ' + result );

(c) result = %ScanRpl( '<>': ' ': result ); 

    dsply ('Contents: ' + result );

    dsply ('Length of result is ' + %Char(%Len(result)));

    *InLr = *On;

As you can see, I have interspersed dsply operations so that when you run the code you can see what happens at each stage. At the first step (a) every single space is replaced by the characters ‘<>’. Next (b) we remove all occurrences of ‘><‘ by replacing them with 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 most knowledgeable experts on programming on the System i platform. Paris cut his teeth on the System/38 way back when, and in 1987 he joined IBM’s Toronto software lab to work on the COBOL compilers for the System/38 and System/36. He also worked on the creation of the COBOL/400 compilers for the original AS/400s back in 1988, and was one of the key developers behind RPG IV and the CODE/400 development tool. In 1998, he left IBM to start his own education and training firm, a job he does to this day with his wife, Susan Gantner–also an expert in System i programming. Paris and Gantner, along with Paul Tuohy and Skip Marchesani, are co-founders of System i Developer, which hosts the new RPG & DB2 Summit conference. Send your questions or comments for Jon to Ted Holt via the IT Jungle Contact page.