RPGLE %TRIM, %TRIML and %TRIMR Reference

This page is a lookup for %TRIM, %TRIML and %TRIMR: what each one removes, what the optional character-list parameter changes, and the cases that are easy to get wrong, such as fixed-length padding and definition-specification restrictions. For the rest of the string functions, see the RPGLE String BIFs Reference. The complete list of BIFs is in the RPGLE Built-in Functions Reference.

All examples are free-form RPGLE.

Syntax

%trim(string {: characters {: *natural | *stdcharsize}})
%triml(string {: characters {: *natural | *stdcharsize}})
%trimr(string {: characters {: *natural | *stdcharsize}})

%trim removes matching characters from both ends. %triml removes them from the left end only. %trimr removes them from the right end only.

dcl-s cleaned varchar(20);

cleaned = %trim('  ABC  ');          // 'ABC'
cleaned = %triml('  ABC  ');         // 'ABC  '
cleaned = %trimr('  ABC  ');         // '  ABC'

The optional character list

The second parameter was added in OS/400 V5R3; before that release, %trim and its variants removed only blanks. With the parameter, the function removes any of the listed characters from the matching end, in any order, rather than blanks specifically.

dcl-s code varchar(10);

code = %trim('**ABC**' : '*');            // 'ABC'
code = %trim('00012340' : '0');           // '1234'
code = %triml('00012340' : '0');          // '12340' (leading zeros removed, trailing zero untouched)
code = %trimr('00012340' : '0');          // '00012340' trimmed only on the right: '0001234'

The order of characters inside the list does not matter; %trim(x : 'ab') and %trim(x : 'ba') remove the same characters. A character that appears in the list but not at an edge of the string is left alone; %trim never removes characters from the middle.

Return type

Every variant returns a varying-length result, because the trimmed length depends on the data. Assigning the result into a fixed-length field pads it with blanks again to that field’s declared length; assigning it into a varying field keeps the trimmed length.

dcl-s fixedOut char(10);
dcl-s varOut   varchar(10);

fixedOut = %trim('  Hi  ');   // 'Hi' padded with blanks to 10: 'Hi        '
varOut   = %trim('  Hi  ');   // 'Hi', current length 2

None of the three functions change the variable passed in. They return a new value, which is only kept if you assign it.

Definition-specification restriction

IBM’s reference notes a restriction that is easy to miss: the two-parameter form of %trim (or %triml/%trimr) is not supported as a value for a definition-specification keyword, such as a default value on a dcl-s. The single-parameter form is allowed there because the string must be a constant in that context.

// Allowed: one parameter, string is a constant
dcl-s a varchar(10) inz(%trim('  Hi  '));

// Not supported: two-parameter form in a definition keyword
// dcl-s b varchar(10) inz(%trim('**Hi**' : '*'));

Use the two-parameter form in calculations instead of in a declaration’s default value.

Trimming leading zeros

A common use is removing leading zeros from a numeric-looking character field before display or concatenation, which %triml does directly without a loop.

dcl-s invoiceNbr char(8) inz('00042017');
dcl-s shown varchar(8);

shown = %triml(invoiceNbr : '0');     // '42017'

If the field can be all zeros, trimming every character leaves an empty string, not a zero; test for that case before using the result where a non-blank value is expected.

Common mistakes

• Expecting %trim, %triml or %trimr to change the original variable. Assign the result to keep it.
• Passing a character list of a different type than string, which the compiler rejects.
• Using the two-parameter form inside a definition-specification keyword, such as an inz default built from a variable list; only the one-parameter, constant form is supported there.
• Assuming %triml with a character list also trims the right side, or the reverse for %trimr. Each variant trims one end only; use %trim for both.
• Forgetting that a field made entirely of the trimmed character becomes an empty string, which can turn a “no data” case into an unexpectedly blank result further down the program.

FAQ

What is the difference between %TRIM, %TRIML and %TRIMR?

%trim removes matching characters from both ends. %triml removes them from the left end only, and %trimr removes them from the right end only.

Can %TRIM remove characters other than blanks?

Yes, with the optional second parameter: %trim(string : characters) removes any character in the list, not only blanks.

Does %TRIM change the field I pass to it?

No. All three functions return a new value. The source variable is unchanged unless you assign the result back to it.

Related BIFs

• RPGLE String BIFs Reference: the full string family, including %scan, %subst and %replace.
• RPGLE %SCAN and %SCANRPL Reference: searching and replacing within a string.
• RPGLE Built-in Functions Reference: the full index by task.

Summary

• %trim trims both ends; %triml and %trimr trim one end each.
• Without a second parameter, all three remove blanks only; with one, they remove the listed characters instead.
• The two-parameter form is not supported as a definition-specification keyword value; use it in calculations.
• Every variant returns a new, varying-length value and leaves the source unchanged.