A Bevy of BIFs: %SCAN and %CHECK
February 25, 2009 Jon Paris
|
From recent questions on Internet lists, and from one-on-one discussions with RPG programmers, it seems that many are confused about the usage and operation of a number of built-in functions (BIFs). In particular the BIFs %XLATE, %REPLACE, %SCAN, and %CHECK seem to cause a lot of confusion. In this tip, I focus on %CHECK and %SCAN. I’ll look at the other misunderstood pair, XLATE and REPLACE, in a future tip. The %SCAN BIF has been with us since V3R7, when it was introduced along with %EDITC and %EDITW, to improve string handling. %CHECK, on the other hand, is a relative newcomer, having been introduced in V5R1 to support the functionality of the old CHECK op-code in /Free form coding. As with all BIFs, one of the major advantages compared with the old op-code version is that the BIF can be used directly in a conditional expression–no need to create a temporary work variable and test that. Here’s the syntax definition for our two BIFs:
%CHECK( comparator : base {: startpos})
%SCAN( search argument : source {: startpos})
As you can see the parameters are at first glance very much alike, particularly if like me you tend to mentally convert terms such as “comparator” to “search string”. Perhaps this accounts in part for the confusion. But there are two very big differences between these two BIFs. The first is that with %CHECK, the compare string is treated as a list of individual characters, whereas %SCAN operates on it as a single string. The second is that %SCAN tries to locate an occurrence of the characters in the compare string, whereas %CHECK tries to identify any characters that are not present in the compare string. %CHECK Let’s review the operation of %CHECK first. This BIF steps through the input a character at a time, comparing each one with the list in the compare string. If it encounters a character that does not exist in the compare set, it returns the position of that character in the input string. In other words, you can think of the compare string as being a list of the characters that are valid in the input field. For example, a compare string that validates the individual characters in a phone number field might look like this: '0123456789-( )' Since %CHECK is a function, it can be used directly in tests such as this one:
If %Check( ' 0123456789-()': character) <> 0;
// Bad character in phone #
EndIf;
This is useful where the actual position of the “bad” character in the string is not important. In practice I would have coded the string of valid characters as a constant, but I coded the literal in this example for ease of explanation. %CHECK has a companion BIF, %CHECKR, which works exactly like %CHECK, but backward. In other words, it begins its scan at the right-hand end of the input field. At one time this feature was very useful when dealing with fields that were padded with characters other than spaces. However, the %TRIMx family of BIFs has been updated to allow any specified character to be trimmed, so %CHECKR has less utility than it once did. %SCAN Like many RPGers, I used to have problems remembering whether the first parameter to %SCAN was the string I was searching, or the string I was searching for. For me this was resolved by an example from former RPG compiler team member, Hans Boldt. His version of the syntax was:
%SCAN( needle : haystack {: startpos})
I’ve never had a problem remembering the sequence since! As we noted earlier, %SCAN is looking for a specific character string. That string can be a single character, or a group of characters. If it finds the requested string in the input (or should I say “haystack”), it returns the position of the first matching character. If it fails to find a match, it returns zero. When using %SCAN, don’t forget that you may need to take spaces into account. For example, when searching for the word “is”, you may need to specify it with both a leading and trailing space. If you don’t, then words such as “This” and “issue” will also give a positive response–and that may not be what you want. One last point on %SCAN: If you want to make your scan code as generic as possible, consider using a variable length field (keyword VARYING) for the compare string. That way you won’t have to worry about trailing spaces in the string messing up the comparison. The following brief sample demonstrates this:
D targetFix s 10a
D targetVar s 10a Varying
D source s 30a
D position s 5i 0
/Free
source = 'this is the test input string';
targetFix = 'is';
position = %Scan( targetFix: source);
// position value is zero due to trailing spaces
dsply ('Position of ' + targetFix + ' is ' + %Char(position));
targetVar = 'is';
position = %Scan( targetVar: source);
// position value is 3
dsply ('Position of ' + targetVar + ' is ' + %Char(position));
Before I close, I should just touch on the one parameter we haven’t mentioned, the start position, which is common to both of these BIFs and works in the same way. It determines the point at which the comparison is to begin. By default the start position is 1, except for %CHECKR, of course, where it is the last character in the input field. This parameter is most commonly used when calling the BIF in a loop, where you need to skip past any instances of the search string that have already been handled. I can’t recall ever using it with %CHECK, but I use it often with %SCAN and we will look at an example of such usage when we review the %REPLACE BIF. BIFs are a vastly underutilized resource in RPG programming. Hopefully this series will help you gain a greater understanding of their utility and help clear up some common misunderstandings. 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 Summitconference. Send your questions or comments for Jon to Ted Holt via the IT Jungle Contact page. RELATED STORIES A Bevy of BIFs: Look Up to %LookUp A Bevy of BIFs: Getting a Date is Easy with %Date
|
