RPG BiF to get leftmost or rightmost characters @ RPGPGM.COM

Within the latest Technology Refreshes, IBM i 7.5 TR3 and 7.4 TR9, are a couple of new RPG Built in Functions, BiF, that can make it easier to get the leftmost or rightmost characters from another variable.

The new BiF are:

%LEFT: gets the leftmost characters
%RIGHT: gets the rightmost characters

The syntax is the same for them both:

Result = %left(< string or variable > : < number of characters to get > :
                 < charcount constant >) ;

Result = %right(< string or variable > : < number of characters to get > : 
                 < charcount constant >) ;

The first two parameters are mandatory.

The third is optional. This is where I can use the CHARCOUNT values of *NATURAL or *STDCHARSIZE from variables that use double byte characters.

IMHO it is easier to understand what these BIF do if I show them in action. Here is the first part of my example RPG program, the definitions:

01  **free

02  dcl-s String1 char(30) ;
03  dcl-s String2 varchar(30) ;
04  dcl-s Result1 char(5) ;

05  dcl-c Letters 'abcdefghijklmnopqrstuvwxyz' ;

Line 1: You all know that if I am writing RPG it is modern, and totally free format.

Line 2 – 4: Definitions of the variables I will using in this part of my example.

Line 5: As I will be moving these characters into more than one variable I created a constant so that I can move it to the variables I need this in.

Now for the first example of these BiF in action:

06  String1 = Letters ;

07  Result1 = %left(String1 : 3) ;
08  dsply ('1. ' + Result1) ;

Line 6: I am moving the constant to the variable String1.

Line 7: I am using the %LEFT BiF to move the three leftmost characters into the result field, which is ten characters in length.

Line 8: Use the Display operation code, DSPLY, to show the result:

DSPLY  1. abc

The next example uses the %RIGHT BiF:

09  Result1 = %right(String1 : 3) ;
10  dsply ('2. ' + Result1) ;

Line 9: Here the three rightmost characters are moved into the result variable.

DSPLY  2.

The result is blank. This is not an error. As the variable String1 is 30 characters in length, and there are only 24 letters the rightmost six characters of the variable are blank.

How to resolve this? The next example show how I would do it:

11  Result1 = %right(%trimr(String1) : 3) ;
12  dsply ('3. ' + Result1) ;

I have use the Trim right BiF, %TRIMR, within the %RIGHT to remove the trailing blanks from the string within String1.

DSPLY  3. xyz

And the result displayed are the last three characters.

Another way is to define the variable as variable length character, rather than just character. I have defined String2 as VARCHAR on line 3. I replace the variable String1 with String2 in my example:

13  String2 = Letters ;

14  Result1 = %right(String2 : 3) ;
15  dsply ('4. ' + Result1) ;

Line 13: Move the value in the constant to the variable String2.

Line 14: Extract the rightmost three characters from String2.

DSPLY  4. xyz

I get the last three letters, as I wanted.

In these next examples I will be using double byte characters.

20  dcl-s String3 varchar(60) ccsid(*utf8) ;
21  dcl-s Result2 char(10) ccsid(*utf8) ;

22  dcl-c Letters2 'áâãåæçèéêëìíîïñòóôõøùúûý' ;

23  String3 = Letters2 ;

24  Result2 = %left(String3 : 3) ;
25  dsply ('5. ' + Result2) ;

Lines 20 and 21: As double byte characters occupy twice the space as single byte I have to define my variables to be twice the length I did before with the single byte characters. I have also defined them with the CCSID of UTF8.

Line 22: This constant contains the double byte characters.

Line 23: I move the contents of the variable into String3.

Line 24: I am using the %LEFT BiF as I did before extracting the three leftmost characters.

DSPLY  5. á

The result may have surprised you until you think about what happened. I extracted the three leftmost characters, and as the variable String3 contains double byte characters that is 1½ characters. The operating system can only display whole characters, which is why only one double byte character, which occupies two places in the variable, is extracted.

Next up is an example using the third parameter, the type of character count:

26  Result2 = %left(String3 : 3 : *stdcharsize) ;
27  dsply ('6. ' + Result2) ;

I am using the Standard Character Size value "telling" the %LEFT to extract based upon the standard way to count characters.

DSPLY  6. á

The result is the same as not giving a third parameter.

In the next example I use the other character count method, *NATURAL.

28  Result2 = %left(String3 : 3 : *natural) ;
29  dsply ('7. ' + Result2) ;

Line 28: The third parameter says that this time the natural method for character counting will be used.

DSPLY  7. áâã

The result is what I desired, the first three double bye characters.

The last example shows what happens with %RIGHT and the natural character counting method.

30  Result2 = %right(String3 : 3 : *natural) ;
31  dsply ('8. ' + Result2) ;

Line 30: Using the %RIGHT with the natural character counting method.

DSPLY  8. úûý

The results are the last three characters, which was what I wanted.

These are nice addition to the RPG language. I could have used a substring BiF to do the same, but I like how simple these both are so that others can easily see what is going on in my RPG code.

You can learn more about this from the IBM website:

This article was written for IBM i 7.5 TR3 and 7.4 TR9.