Built In Functions

Midware Ltd.

Built-in-functions (BIF's) are probably the most exciting new feature in RPG IV - not just because of the functionality they provide, but because of the potential they promise.

Built in functions are actually procedures written by IBM that may be used in expressions (IF, EVAL, etc.) as if they are variables. Procedures are an ILE concept that we will cover in later sections. For now just think of a procedure as a kind of hybrid subroutine. In later sections, we'll show you how you can write your own functions. This is a little more advanced, and requires some knowledge of ILE concepts. There is nothing special you need to do to use built in functions however. If you are using RPG IV, you have full access to all BIF's.

All built in functions begin with a percent sign (%). Most built in functions accept parameters which can be coded in parenthesis. Multiple parameters should be separated by a colon (:). The syntax of built-in-functions is:

%name{(parm1{:parm2...})}

BIF's may be used in any freeform expressions and may be embedded in in other built in functions. For example:

eval @Index = %int(%abs(@Value))

The built in function %ABS returns the absolute value of a numeric parameter. %INT returns the integer portion a numeric parameter. The above example will execute from the innermost parenthesis first. Each BIF will execute a procedure call and return the result in place of the expressions. For example, lets assume that @Value is set to -3.14 at the time the EVAL statement is executed. The sequence the statement will be evaluated is as follows:

eval      @Index = %int(%abs(-3.14))
:
eval      @Index = %int(3.14)
:
eval      @Index = 3

A wide range of built in functions are available. New functions are added with each release of the operation system. At one point, IBM said that most of the near-term enhancements to RPG will be in the form of new BIF's. Check with IBM's online documentation for the BIF's available in your release or click here for a complete list of BIF's in V4R5.

Following is a rundown of some of the more useful built-in-functions.

%ABS(numeric expression)
Returns the absolute value (always positive) of a numeric expression.

%EDITC(numeric : editcode {: *ASTFILL | *CURSYM | currency-symbol})
%EDITW(numeric : editword)
Applies an edit code edit word or to a numeric expression. This is especially useful when building text strings as in:

eval      @Message = 'The current balance for ' +
             'Social Security Number +
             %editw(@SSN: '0   - -    ') +
             ' is ' + %editc(@Balance: 'J')

%EOF{(file_name)}
%EQUAL{(file_name)}
%FOUND{(file_name)}
One thing you may have noticed is that later versions of RPG IV do not require an indicator to be coded on READ and CHAIN operations (instead of manually spacing over to the indicator positions, I used to just press enter, and let the error condition automatically position the cursor). At first, I thought this was an oversight, until I learned of these functions.

%EOF, %EQUAL and %FOUND may be used to replace the status indicators on I/O operations. %EOF is used with read operations (READ, READE, etc.), %EQUAL may be used with the SETLL operation, and %FOUND may be used with the CHAIN, DELETE, SETLL and SETGT operations.

read      file1
read      file2
if        %eof(file1) or %eof(file2)
:

If the file parameter is omitted from the function, the status of the last file operation will be returned. For example:

read      file1
dow       not %eof
:
read      file1
enddo

The %EQUAL and %FOUND functions may be used also for some non-I/O operations as well. The LOOKUP operation code will set both %EQUAL and %FOUND. %FOUND may also be used with the CHECK, CHECKR, and SCAN operation codes in place of an indicator.

%INT(numeric expression)
Returns the integer value of a numeric expression.

eval      @Message = 'Your bill is for ' +
          %char(%int(@BillAmt)) + ' dollars and '
          %char((@BillAmt - %int(@BillAmt)) * 100)
          + ' cents')

Note the use of the %CHAR built in function to convert the numeric data to character format. Remember, you can not mix data types in a free-format expression (%CHAR can only be used to convert numeric data as of V4R4).

%LEN(expression)
Returns the length of an expression, or sets the length of a variable length field.

%SCAN(search argument : source string {: start})
Scans a text string left to right for a search argument. If a start position is not specified, the search begins at position 1. The expression returns the first position in which the search string was found. If zero is returned, the search string was not found.

%TRIM(string)
%TRIML(string)
%TRIMR(string)
Trims leading and trailing blanks from a text string. %TRIML will only trim leading blanks and %TRIMR will only trim trailing blanks.

eval      @Name = %trim(@FirstName) + ' ' +
             @MiddleInit + '. ' +
             %trim(@LastName)

Back to Date & Time

Next to ILE Concepts

Last Modified: August 18, 2000