Built-in Function

%CHAR

The %CHAR built-in function in CL is used to convert logical, decimal, integer, or unsigned integer data into character format.

SYNTAX:

• Convert-argument: The convert-argumentis a CL variable with the type of *LGL, *DEC, *INT, or *UINT.

EXAMPLE:

• %CHAR built-in function converted the &NUM1, &LEN, &SIZE, and & LGLVAR variable, to character type, which has type *DEC, *UINT, *INT, and *LGL respectively.
• The &RESULT variable having *CHAR type will store the result in character format.

%DEC

 %DEC built-in function is used to convert character, logical, decimal, integer, or unsigned integer data into packed decimal format.

SYNTAX:

• Convert-argument: The convert-argument is a CL variable with the type of *CHAR, *LGL, *DEC, *INT, or *UINT.
• Total-digits & decimal-places: total-digits and decimal-places parameters are optional. They will take default values, Based on data type.

EXAMPLE:

• %DEC built-in function converted the &STR1, &LGLVAR, &NUM1, and &NUM2 variable , to decimal type, which has type *CHAR, *LGL, *INT, and *UINT respectively.
• The &RESULT variable having *DEC type will store the result in packed decimal format.

%INT

%INT built-in function is used to convert character, logical, decimal, or unsigned integer data to integer format.

SYNTAX:

• Convert-argument: The convert-argument is a CL variable with the type of *CHAR, *LGL, *DEC or *UINT.

EXAMPLE:

• %INT built-in function converted the &STR1, &LGLVAR, &NUM1, and &NUM2 variable, to integer type, which has type *CHAR, *LGL, *DEC, and *UINT respectively.
• The &RESULT variable having *INT type will store the result in integer format.

%LEN 

%LEN built-in function is used to return the length of the numeric or character variable.

SYNTAX:

• Variable-argument: The variable-argument is a CL variable with the type of *CHAR, *DEC, *INT, or *UINT.
• If length is not defined for the numeric and character variable it will return the default length.

EXAMPLE:

• The length of variables &STR1, &STR2, &NUM1, &NUM2, &NUM3, and &NUM4 will be 32, 30, 16, 6, 10, and 5 respectively stored in &LEN variable.
• The value 5 will be returned for a 2-byte *INT or *UINT variable. And value 10 will be returned for a 4-byte *INT or *UINT.

%LOWER 

%LOWER built-in function returns a character string of the same length as the argument passed in, but with every uppercase letter changed to its corresponding lowercase letter.

SYNTAX:

• input-string:  input-string is a CL variable with the type of *CHAR.
• The CCSID parameter is optional and defaults to the job CCSID.

EXAMPLE:

&STR1 variable contains the value “HI THERE” in uppercase letters. %LOWER built-in function will return the value “hi there” in lowercase letters.

%UPPER 

%UPPER built-in function returns a character string of the same length as the argument passed in, but with every lowercase letter changed to its corresponding uppercase letter.

SYNTAX:

• input-string: input-string is a CL variable with the type of *CHAR.
• The CCSID parameter is optional and defaults to the job CCSID.

EXAMPLE:

&STR1 variable contains the value “hi there” in lowercase letters. %UPPER built-in function will return the value “HI THERE” in uppercase letters.

%PARMS

%PARMS built-in function is used to return the number of parameters that were passed to the program in which %PARMS is used.

SYNTAX:

EXAMPLE:

The following is the source for EMPDATA.

• Three parameters were passed to the program which was called by a program call.
• %PARMS built-in function will return the 3 parameters and “3 parms were passed” will be the result of program.

%CHECK:

%CHECK is used to find the first position of base string where a specific character is not available in the test string from left to right. A 0 is returned when all characters match. It is supported in arithmetic expressions and conditional statements.

SYNTAX:

• Comparator-String: it must be either a cl character variable or a character literal. The comparator string specifies the characters to search for in the base string.
• Base-String: It can be a cl character variable or *LDA. Base string refers to the string against which the comparison is made.
• Starting-position: It is optional and defaults to 1 and specifies where checking begins.

EXAMPLE:

• Look for the first character that isn’t an asterisk(*) or a dollar sign($). From left to right, the characters in the variable &AMOUNT are examined.
• The CHGVAR command assigns the value 8 to the cl variable &POS since the eighth character is the first one that is neither an asterisk nor a dollar sign.

%CHECKR:

%CHECKR is used to find the first position of base string where a specific character is not available in the test string from right to left.  0 is returned when all characters match. It is supported in arithmetic expressions and conditional statements.

SYNTAX:

EXAMPLE:

• &COM contains the comparator string (‘$* ‘).
• &AMT contains the base string (‘$***5.27 ‘).
• &SPOST stores the leftmost position where a character not in the comparator string appears.
• &EPOST stores the rightmost position where a character not in the comparator string appears.
• &LENT calculates the number of characters between these two positions.
• &DECS Extracts The Relevant Substring And Converts It To A Decimal Cl Variable.

%SCAN:

The %scan built-in function in cl is a powerful tool for string manipulation.
%scan gives back a search argument’s initial position in the source string.
The function returns 0 if the search argument cannot be found.
%scan can be used anywhere an arithmetic expression is supported by CL.

SYNTAX:

• Search Argument: a literal character or a CL character variable. It is the substring that you want to search for within a larger string.
• Source-String: *LDA or a CL character variable. The contents of the local data area for the job are scanned by the scan function when *LDA.
• It refers to the string that is searched for occurrences of a specified substring.
• Starting Position (Optional): this is the first location in the source string where the search starts by default.

EXAMPLE:

• A message is issued if the string “jonny” cannot be located in the variable &firstname.
• Because the scan is case sensitive, if &firstname contains the value “jonny,” a search for “Jonny” will not yield a positive result.

%SUBSTRING OR %SST:

You can work with character strings using CLLE’S built-in %substring (or %sst) function.
A character string generated by the %substring function is a subset of an already-existing character string.

SYNTAX:

Alternatively, it can be written as:

We can also use %SST with the special value *LDA to indicate that the substring function operates on the contents of the local data area.

• Character-variable-name: The name of the CL character variable or the special value *LDA. Character variable name refers to the name of the variable containing the string from which you want to extract a substring.
• Starting position: The position (which can be a variable name) where the substring begins (cannot be 0 or negative). Specifies the position within the source string from which the substring extraction begins.
• Length: The length (which can also be a variable name) of the substring (cannot be 0 or negative).

The program CUS210 is invoked if the initial two positions of &VAR1 and &VAR2 match.

%TRIM:

Leading and trailing characters can be omitted from character strings using the %trim. The %trim function serves two purposes:

Trim Leading and Trailing Blanks: This function removes leading and trailing blank spaces from a character string when it is used with a single parameter.
Custom Trim: This function removes expected leading and trailing characters specified in the second parameter when it is used with two parameters.

SYNTAX:

• Character-variable-name: Refers variable name that we want to trim.
• Character-to-trim: Refers characters that we want to trim.
• 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 function produces a string of blank characters.

EXAMPLE:

• Eliminate leading and trailing whitespace characters.
• After trimming the leading and trailing blanks from the CL variables &FNAME and &LNAME, the remaining strings are concatenated with the *BCAT operator, leaving a single blank between the two values.
• Next, the concatenated string is allocated to the cl variable &sname

%TRIML:

The built-in function %triml is used to manipulate strings by eliminating only the leading characters.

SYNTAX:

• Character-variable-name: Refers variable name that we want to trim.
• Character-to-trim: Refers characters that we want to trim.
• If the characters-to-trim parameter is specified, it must be either a cl character variable or a character literal.
• If, after leading, no characters are left, the function produces a string of blank characters.

EXAMPLE:

• The letters that remain (6.37) are allocated to cl variable &TRIMMEDAMT, while all dollar signs and blanks are removed from the beginning of cl variable &AMT.
• Decimal variable &decvar receives the numeric value supplied to the character variable &TRIMMEDAMT.

%TRIMR:

The %trimr function removes any trailing characters (usually blank spaces) from a character string.

SYNTAX:

• Character-variable-name: Refers variable name that we want to trim.
• Character-to-trim: Refers characters that we want to trim.
• If the characters-to-trim parameter is specified, it must be either a cL character variable or a character literal.
• If, after trailing, no characters are left, the function produces a string of blank characters.

EXAMPLE:

• The CL variables &FNAME and &LNAME have their following blank characters removed, and the resulting strings are concatenated using the *cat operator.
• Next, the concatenated string is allocated to the CL variable &sname.