It's time to have a little fun! Let's build MS Excel-like LEFT and RIGHT functions using BIFs.

My guess is that you, dear reader, use MS Excel (or some sort of spreadsheet similar to it) to some extent. Even if you don't use it every day, it's possible that you've come across the LEFT, MID, and RIGHT functions. If you haven't, this article provides a nice overview. These are simple yet powerful text-handling functions. LEFT and RIGHT don't have a parallel in RPG. However, the MID function does: it's the %SUBST BIF that I presented two TechTips ago.

Our Own LEFT RPG Function

Let's build our own LEFT RPG function. If you haven't already, this would be a good time to stop and read the two TechTips is this series that explain how to build and use your own functions. Now think a bit about what the LEFT function does: returns the leftmost n characters of a string. In other words, it returns the first n characters of a string. Well, that's something easily achieved with %SUBST; just indicate 1 in the BIF's second parameter (start position) and n in the third (length to extract), like this: %SUBST(<string> : 1 : n)

With that, we can start to build our function. But first, allow me a moment to discuss what a procedure or function should be. In order to build a proper procedure or function, a programmer should, in my opinion, perform three distinct tasks:

1. Check the input parameters, if they exist, especially if they have keywords like VARYING or OPTIONS. Validate the parameters the best you can and return an error if an unrecoverable situation occurs. This can be anything—from missing parameters to unknown values—so be careful here and think it through before starting to write code.
2. Retrieve all the necessary information from files, data areas, calculations over variables, and so on so that the next task on this list can be as isolated from the rest of the code as possible. This is important for the readability and future maintainability of the code. However, in simple functions, like our LEFT function, this task might not be necessary.
3. Finally, perform whatever operation the procedure or function is supposed to, documenting it properly so that your train of thought can be followed by whoever reads that code in the future.

Enough talk. Let's code! Just like its MS Excel counterpart, our LEFT function has two parameters:

*------------------------------------------------------------------------*

*   Left (return the leftmost n characters of a string)                 *

*------------------------------------------------------------------------*

P Left           B                   Export                              

D Left           PI         32767A   VARYING                            

* Input parameters                                                      

D P_String                 32767A   OPTIONS(*VARSIZE)                  

D                                     CONST                              

D P_NbrChars                   5P 0 CONST                              

We're going to need some work variables, so let's declare and initialize them:

* Work variables                                        

D W_String       S         32767A   VARYING INZ(*Blanks)

D W_Return       S         32767A   VARYING INZ(*Blanks)

Then comes first task, checking the input parameters, which looks like this:

* Check input parms                                              

* P_String                                                      

C                   IF       P_String = ''                      

C                   RETURN   P_String                            

C                   ENDIF  

* "Clean" P_String because of OPTIONS(*VARSIZE)

C                   EVAL     W_String = %SUBST(P_String : 1 :

C                                              %LEN(%TRIM(P_String)))

* P_NbrChars                                                    

C                   IF       P_NbrChars <= *Zeros                

C                             Or P_NbrChars > %LEN(%TRIM(P_String))

C                   RETURN   P_String                            

C                   ENDIF                                        

In the P_String check, the only thing to do is confirm that a string was actually passed. If it wasn't, then there's nothing for the function to do, so it returns control to the calling program. Otherwise, the content of P_String is moved (not by using MOVE, because we no longer use that) to a work variable, thus "cleaning" the input parm's value of any unwanted content. The second parameter validation is slightly more complex: we need to make sure that a valid number of characters was passed: it needs to be a positive number, smaller than the length of the string. Also, because P_String has the OPTIONS(*VARSIZE) keyword, we're only interested in the length of the string that actually contains data, hence the %LEN(%TRIM(P_String)), has explained here. Again, if something went wrong, control is passed back to the calling program, returning the input string untouched.

Because this function doesn't require additional data, the second task, retrieve all the necessary information, is not required. The third task can be executed next:

* If the input parms are ok, process

* Perform the LEFT operation                                            

C                   EVAL     W_Return = %SUBST(W_String : 1 : P_NbrChars)

C                   RETURN   W_Return                                  

P Left           E

There you have it: your own LEFT function!

RIGHT Is Next…

RIGHT is a bit more complex, because we don't know beforehand how long the input string is going to be. Because %SUBST extracts characters from left to right, you could either reverse the string and use LEFT (not so simple, but possible) or do a little calculation to determine where to start extracting characters. Think about it; I'll get back to that in a bit. The RIGHT function will have the same parameters as LEFT, so they are very similar right down to the end of the first task:

*------------------------------------------------------------------------*

*   Right /return the rightmost n characters of a string)               *

*------------------------------------------------------------------------*

P Right           B                   Export                              

D Right           PI         32767A   VARYING                            

* Input parameters                                                        

D P_String                 32767A   OPTIONS(*VARSIZE)                  

D                                     CONST                              

D P_NbrChars                   5P 0 CONST                                

* Work variables                                                        

D W_String       S         32767A   VARYING INZ(*Blanks)                

D W_Return       S         32767A   VARYING INZ(*Blanks)

D W_StartPos     S              5P 0 INZ(*Zeros)        

* Check input parms                                    

* P_String                                              

C                   IF       P_String = ''              

C                   RETURN   P_String                  

C                   ENDIF                                

* P_NbrChars                                            

C                   IF       P_NbrChars <= *Zeros      

C                  RETURN   P_String                              

C                   ENDIF                                            

* "Clean" P_String because of OPTIONS(*VARSIZE)                    

C                   EVAL     W_String = %SUBST(P_String : 1 :      

C                                               %LEN(%TRIM(P_String)))

* P_NbrChars                                                        

C                   IF       P_NbrChars <= *Zeros                  

C                            Or P_NbrChars > %LEN(%TRIM(P_String))  

C                   RETURN   P_String                              

C                   ENDIF                                            

You probably noticed an additional work variable in the code above: W_StartPos. While the second task (retrieve all the necessary information) was not required in the LEFT function, now we need to determine where our %SUBST is going to start. What we need is to know how long our input string is so that the program can extract the last n characters. Here's RIGHT's task 2:

* Determine the start position                                

C                   EVAL     W_StartPos = %LEN(%TRIM(P_String))

C                                           - P_NbrChars + 1  

Let me give you an example to illustrate the code above. If P_String has 10 characters and we want the last three (the eighth, ninth, and tenth characters), W_StartPos will contain 8 (10 – 3 + 1). Finally, the third and last task can be performed:

* Perform the RIGHT operation                                        

C                   EVAL     W_Return = %SUBST(W_String : W_StartPos)

C                   RETURN   W_Return                                

P Right           E                                                  

Note that the %SUBST is not using the third parameter. It can be omitted because this BIF will automatically determine the length of the string and W_StartPos contains the correct start position. By the way, you could skip W_StartPos and simply perform its operation directly in the %SUBST, like this:

C                   EVAL     W_Return = %SUBST(W_String :

C                                               %LEN(%TRIM(P_String))

C                                                 - P_NbrChars + 1)  

Not so clear, right? I've shown before that you can perform operations in a BIF's parameter. I chose not to do it for two reasons: to keep the code simple, clear, and maintainable (it can get hard to decipher operations within operations) and to keep the three tasks of a procedure/function as isolated from each other as possible.

That's all for now! The next TechTip of the RPG Academy series will introduce a new BIF and use it to create a few other MS Excel-like functions in RPG. Until then, comment on this TechTip, improve on it, and share your thoughts and doubts in the Comments section below or in the usual LinkedIn groups.