IBM Support

New built-in functions have been added to both OPM CL and ILE CL that make string handling easier and faster

News


Abstract

New built-in functions have been added to both OPM CL and ILE CL that make string handling easier and faster

Content

You are in: IBM i Technology Updates > General IBM i Operating System > New built-in functions have been added to both OPM CL and ILE CL that make string handling easier and faster

Three new control language (CL) compiler built-in functions (%CHECK, %CHECKR, and %SCAN) were added by PTF SI49061 for IBM i 7.1.

Support for three new trim built-in functions (%TRIM, %TRIML, and %TRIMR) was added for IBM i 7.1 by PTF SI48166 in October 2012, and SI49061 supersedes SI48166.

New built-in functions have been added to both OPM CL and ILE CL that make string handling easier and faster:

  • %CHECK - Check Characters
  • %CHECKR - Check Reverse
  • %SCAN - Scan for Characters
  • %TRIM - Trim Characters at Edges
  • %TRIML - Trim Leading Characters
  • %TRIMR - Trim Trailing Characters

If you want to use these new CL built-in functions on a 7.1 system, PTF SI49061 must be loaded and applied. Support will not be PTF'ed to 6.1 or 5.4 releases, but you can compile CL code that uses these new functions on your 7.1 system and specify TGTRLS(V6R1M0) or TGTRLS(V5R4M0) and then save the CL objects off your 7.1 system and restore them on an IBM i system running the 5.4 or 6.1 release of IBM i.

All of the above built-in functions will have almost the same behavior as the RPG built-in functions by the same name.

Descriptions of each new built-in function:

%CHECK built-in function
The check built-in function (%CHECK) returns the first position of a base string that contains a character that does not appear in the comparator string. If all of the characters in the base string also appear in the comparator string, the function returns 0. This function can only be used within a CL program or procedure.

The %CHECK built-in function can be used anywhere that CL supports an arithmetic expression. %CHECK can be used alone or as part of a more complex arithmetic expression. For example, %CHECK could be used to compare to a numeric CL variable in the COND parameter of an IF or WHEN command. %CHECK can also be used to set the value of a CL command parameter, if the associated command object defines the parameter with EXPR(*YES) and TYPE of *DEC, *INT2, *INT4, *UINT2, or *UINT4.

The format of the check built-in function is shown in this example:

%CHECK(comparator-string base-string [starting-position])

The comparator string must be either a CL character variable or a character literal. The base string can be a CL character variable or *LDA. When *LDA is specified, the check function is performed on the contents of the local data area for the job. The starting position is optional and defaults to 1. Checking begins at the starting position and continues to the right until a character that is not contained in the comparator string is found. The result is always the position relative to the start of the source string even if the starting position is specified. The starting position, if specified, must be either a CL integer variable or a CL decimal variable with zero decimal positions or a numeric literal with zero decimal positions. The starting position cannot be 0 or negative. If the starting position is greater than the length of the entire base variable or the local data area, an error occurs. The length of the local data area is 1024.

%CHECKR built-in function
The reverse check built-in function (%CHECKR) returns the last position of a base string that contains a character that does not appear in the comparator string. If all of the characters in the base string also appear in the comparator string, the function returns 0. This function can only be used within a CL program or procedure.

The %CHECKR built-in function can be used anywhere that CL supports an arithmetic expression. %CHECKR can be used alone or as part of a more complex arithmetic expression. For example, %CHECKR could be used to compare to a numeric CL variable in the COND parameter of an IF or WHEN command. %CHECKR can also be used to set the value of a CL command parameter, if the associated command object defines the parameter with EXPR(*YES) and TYPE of *DEC, *INT2, *INT4, *UINT2, or *UINT4.

The format of the reverse check built-in function is shown in this example:

%CHECKR(comparator-string base-string [starting-position])

The comparator string must be either a CL character variable or a character literal. The base string can be a CL character variable or *LDA. When *LDA is specified, the reverse check function is performed on the contents of the local data area for the job. The starting position is optional and defaults to the end of the string. Checking begins at the starting position and continues to the left until a character that is not contained in the comparator string is found. The result is always the position relative to the start of the source string even if the starting position is specified. The starting position, if specified, must be either a CL integer variable or a CL decimal variable with zero decimal positions or a numeric literal with zero decimal positions. The starting position cannot be 0 or negative. If the starting position is greater than the length of the entire base variable or the local data area, an error occurs. The length of the local data area is 1024.

%SCAN built-in function
The scan built-in function (%SCAN) returns the first position of a search argument in another string (the source string), or 0 if it was not found. This function can only be used within a CL program or procedure.

The %SCAN built-in function can be used anywhere that CL supports an arithmetic expression. %SCAN can be used alone or as part of a more complex arithmetic expression. For example, %SCAN could be used to compare to a numeric CL variable in the COND parameter of an IF or WHEN command. %SCAN can also be used to set the value of a CL command parameter, if the associated command object defines the parameter with EXPR(*YES) and TYPE of *DEC, *INT2, *INT4, *UINT2, or *UINT4.

The format of the scan built-in function is shown in this example:

%SCAN(search-argument source-string [starting-position])

The search-argument must be either a CL character variable or a character literal. The source-string can be a CL character variable or *LDA. When *LDA is specified, the scan function is performed on the contents of the local data area for the job. The starting position is optional and defaults to 1. Searching begins at the starting position. The result is always the position relative to the start of the source string even if the starting position is specified. The starting position, if specified, must be either a CL integer variable or a CL decimal variable with zero decimal positions or a numeric literal with zero decimal positions. And the starting position can’t be 0 or negative. If the starting position is greater than the length of the entire source-string variable or the local data area, an error occurs. The length of the local data area is 1024.

%TRIM built-in function
The trim built-in function (%TRIM) with one parameter produces a character string with any leading and trailing blanks removed. The trim built-in function (%TRIM) with two parameters produces a character string with any leading and trailing characters that are in the characters to trim parameter removed. This function can only be used within a CL program or procedure.

The %TRIM built-in function can be used anywhere that CL supports a character expression. %TRIM can be used alone or as part of a more complex character expression. For example, %TRIM could be used to compare to a character CL variable in the COND parameter of an IF or WHEN command. %TRIM can also be used to set the value of a CL command parameter, if the associated command object defines the parameter with EXPR(*YES) and TYPE of *CHAR, *NAME, *SNAME, *CNAME, *PNAME, *GENERIC, *DATE, *TIME, or *X.

The format of the trim built-in function is shown in this example:

%TRIM(character-variable-name [characters-to-trim])

The trim function produces a substring from the contents of the specified CL character variable. If the characters to trim parameter is specified, it must be either a CL character variable or a character literal. If after trimming, no characters are left, the trim function produces a string of blanks with corresponding length.

%TRIML built-in function
The trim left built-in function (%TRIML) with one parameter produces a character string with any leading blanks removed. The trim left built-in function (%TRIML) with two parameters produces a character string with any leading characters that are in the characters to trim parameter removed. This function can only be used within a CL program or procedure.

The %TRIML built-in function can be used anywhere that CL supports a character expression. %TRIML can be used alone or as part of a more complex character expression. For example, %TRIML could be used to compare to a character CL variable in the COND parameter of an IF or WHEN command. %TRIML can also be used to set the value of a CL command parameter, if the associated command object defines the parameter with EXPR(*YES) and TYPE of *CHAR, *NAME, *SNAME, *CNAME, *PNAME, *GENERIC, *DATE, *TIME, or *X.

The format of the trim left built-in function is shown in this example:

%TRIML(character-variable-name [characters-to-trim])

The trim left function produces a substring from the contents of the specified CL character variable. If the characters to trim parameter is specified, it must be either a CL character variable or a character literal. If after trimming, no characters are left, the trim left function produces a string of blanks with corresponding length.

%TRIMR built-in function
The trim right built-in function (%TRIMR) with one parameter produces a character string with any trailing blanks removed. The trim right built-in function (%TRIMR) with two parameters produces a character string with any trailing characters that are in the characters to trim parameter removed. This function can only be used within a CL program or procedure.

The %TRIMR built-in function can be used anywhere that CL supports a character expression. %TRIMR can be used alone or as part of a more complex character expression. For example, %TRIMR could be used to compare to a character CL variable in the COND parameter of an IF or WHEN command. %TRIMR can also be used to set the value of a CL command parameter, if the associated command object defines the parameter with EXPR(*YES) and TYPE of *CHAR, *NAME, *SNAME, *CNAME, *PNAME, *GENERIC, *DATE, *TIME, or *X.

The format of the trim right built-in function is shown in this example:
%TRIMR(character-variable-name [characters-to-trim])

The trim right function produces a substring from the contents of the specified CL character variable. If the characters to trim parameter is specified, it must be either a CL character variable or a character literal. If after trimming, no characters are left, the trim right function produces a string of blanks with corresponding length.

Examples:
1. Check for any characters that are not digits (0-9):

PGM PARM(&SN)
DCL VAR(&SN) TYPE(*CHAR) LEN(10)
IF COND(%CHECK('0123456789' &SN) *NE 0) +
THEN(SNDPGMMSG ('INVALID CHARACTER FOUND!'))

2. Figure out the length of a string which is padded at the end with some characters:

DCL VAR(&LEN) TYPE(*INT)
DCL VAR(&STRING) TYPE(*CHAR) LEN(20) VALUE('JOHN SMITH*****')
DCL VAR(&PADCHARS) TYPE(*CHAR) LEN(2) VALUE(' *')
CHGVAR VAR(&LEN) VALUE(%CHECKR(&PADCHARS &STRING))
/* &LEN will have the value 10 */

3. Search characters from the local data area (*LDA):

DCL VAR(&POS) TYPE(*UINT) LEN(2)
CHGVAR VAR(&POS) VALUE(%SCAN('Escape' *LDA))

4. Trimming blanks:

DCL VAR(&FIRSTNAME) TYPE(*CHAR) VALUE(' JOHN ')
DCL VAR(&LASTNAME) TYPE(*CHAR) VALUE(' SMITH ')
DCL VAR(&NAME) TYPE(*CHAR) LEN(10)
/* &NAME will have the value 'JOHN SMITH' */
CHGVAR VAR(&NAME) VALUE(%TRIM(&FIRSTNAME) *BCAT %TRIM(&LASTNAME))

5. Trimming leading characters specified in a literal string:

DCL VAR(&PRICE) TYPE(*CHAR) VALUE(' $5.27')
DCL VAR(&TRIMMED) TYPE(*CHAR) LEN(5)
DCL VAR(&DEC) TYPE(*DEC) LEN(3 2)
/* &TRIMMED will have the value '5.27 ' */
CHGVAR VAR(&TRIMMED) VALUE(%TRIML(&PRICE '$ '))
/* &DEC will have the value 5.27 */
CHGVAR VAR(&DEC) VALUE(&TRIMMED)

6. Trimming trailing characters specified in a CL variable:

DCL VAR(&NAME) TYPE(*CHAR) LEN(10) VALUE('12345*** ')
DCL VAR(&TCHAR) TYPE(*CHAR) LEN(2) VALUE('* ')
IF COND(%TRIMR(&NAME &TCHAR) *EQ '12345') +
THEN(SNDPGMMSG ('EQUAL!'))

[{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"Component":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB08","label":"Cognitive Systems"}}]

Document Information

Modified date:
09 January 2020

UID

ibm11127691