Let's look at the new %TRIM, %TRIML, and %TRIMR built-ins of CL.

Over the past year, IBM has continued to enhance CL in order to make our lives, as developers, easier. In the previous article, "New Support for CL Commands Lets You Know When a Command Ends," we saw how a PTF enables the system to call a program of your choosing when a given CL command completes processing. Likewise, in an earlier series of articles, starting with "Introducing the New Run SQL Command," we saw how, with a PTF, you can now run SQL statements directly out of your CL programs.

This month, we'll look at three new CL built-ins that IBM has provided by way of 7.1 PTF SE53451. The new built-ins, which are supported with both the OPM and ILE compilers, are %TRIM, %TRIML, and %TRIMR. Note that while this PTF is only available with 7.1, the PTF does provide the 7.1 CL compiler support so that you can (by way of the TGTRLS parameter of the CRTCLPGM, CRTCLMOD, and CRTBNDCL commands) generate code that will run on V5R4 and 6.1 systems within your network (in addition to obviously supporting systems running at 7.1).

The first built-in we'll look at, %TRIM, is defined with two parameters. The first parameter is required and is a CL variable, defined as Type(*Char), that you want trimmed in terms of removing certain leading and/or trailing characters. The second parameter is optional and can be a CL variable, defined as Type(*Char), or a character literal value. Using the second parameter, you can specify one or more characters that are to be trimmed from the value of the first parameter. The second parameter, when not specified, defaults to the single character of a blank.

The %TRIM built-in returns the value of the first parameter after performing any requested trimming. Suppose we have two CL variables defined as follows:

Dcl       Var(&Amount) Type(*Char) Len(20) +

             Value('     *******12.50***')

Dcl       Var(&Result) Type(*Char) Len(50)                          

The following CHGVAR command would set the value of &Result to '12.50', removing the leading blanks and asterisks of &Amount, along with the trailing asterisks.

ChgVar     Var(&Result) Value(%trim(&Amount ' *'))

Now, suppose the second parameter of the %TRIM built-in isn't specified, as shown below:

ChgVar     Var(&Result) Value(%trim(&Amount))

This would result in variable &Result being set to '*******12.50***' as, by default, only the leading blanks would be removed.

And now consider specifying a second parameter of only the asterisk:

ChgVar     Var(&Result) Value(%trim(&Amount '*'))

This would result in variable &Result being set to '     *******12.50' as only leading asterisks would be removed, and the leading characters in &Amount are blanks, not asterisks. The trailing asterisks are, however, gone.

The %TRIM built-in can be used anywhere that a character expression can be used. It can be used alone, as with the previous examples, or in a more complex expression such as this one:

Dcl      Var(&Text)   Type(*Char) Len(25) Value('Total Amount:')

Dcl       Var(&Amount) Type(*Char) Len(20) +                    

             Value('     *******12.50***')                      

Dcl       Var(&Result) Type(*Char) Len(50)                      

ChgVar     Var(&Result) Value(%trim(&Text) *Cat ' ' *Cat +      

                             %trim(&Amount ' *'))              

Here, the value of %Result would end up being 'Total Amount: 12.50'. In a similar fashion, the %TRIM built-in can be used in the COND parameter of an IF or WHEN command.

The %TRIML built-in supports the same parameters as the %TRIM built-in but trims only leading characters. The %TRIMR built-in supports the same parameters as the %TRIM built-in but trims only trailing characters. In the preceding example, where we concatenated &Text and &Amount, we could, rather than using %TRIM(&Text), have used %TRIMR as only trailing blanks exist in the value of variable &Text:

ChgVar     Var(&Result) Value(%trimr(&Text) *Cat ' ' *Cat +

                             %trim(&Amount ' *'))        

This change to using %TRIMR would result in no change in terms of the resulting value of the variable &Result. You could, of course, have also gotten the same answer using the *BCAT operator as in the following:

ChgVar     Var(&Result) Value(&Text *BCat %trim(&Amount ' *'))          

Before closing on the various %trim built-ins, let's look at one more example based on this new function. Let's say you have a CL program that has copied a report to a database file and is designed to summarize various dollar amounts, found in positions 85 through 97 of particular records, to the variable &Result. This seems easy enough. Assuming that positions 85 through 97 are mapped to the character variable &Amount and that &Result is initially set to a value of 0, simply add &Amount to &Result (for those records selected) after converting to a decimal variable, as shown:

Dcl       Var(&Interim) Type(*Dec) Len(12 2)

Dcl       Var(&Result) Type(*Dec) Len(12 2)

ChgVar     Var(&Interim) Value(&Amount)

ChgVar     Var(&Result) Value(&Result + &Interim)

You run into a little wrinkle, though. It turns out that there is also a floating dollar sign that is found within the field &Amount. Prior to the %trim built-in support, you would have had to scan for the dollar sign and ignore/bypass it (using a variety of possible approaches) when setting the intermediate variable &Interim. Not a difficult task, but certainly more work for you to squeeze into your schedule. With the new built-ins, you can simply trim the floating dollar sign as shown:

ChgVar     Var(&Interim) Value(%trim(&Amount ' $'))              

ChgVar     Var(&Result) Value(&Result + &Interim)

In some situations, the three new trim built-ins provide for much easier handling of character strings. They represent new capabilities that you should definitely consider adding to your development toolkit. I give a tip of the hat to the IBM CL development team for adding these new built-ins to the CL language.

More CL Questions?

Wondering how to accomplish a function in CL? Send your CL-related questions to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll try to answer your burning questions in future columns.

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale