RPGLE Built-in Functions Reference

A built-in function (BIF) is a function the RPG compiler provides. It starts with a percent sign, such as %trim or %scan, and you use it inside an expression.

This page is an index. Find the function you need by task or by name, read its one-line syntax, and follow the link to the page that explains it in full.

Everything here is written for free-form RPGLE, where BIFs are used directly in expressions. The fixed-format opcodes that BIFs replaced are named only where that helps you recognise old code. If you are new to the language, start with RPGLE for Beginners and come back here as a lookup.

How to use this page

Find your task in the first table.
Read the syntax line to confirm it is the function you want.
Open the family page for parameters, return values and edge cases.

Syntax notation: parameters in braces { } are optional, and a colon separates parameters.

Find a BIF by task

Task	BIF	Syntax	Family
Take part of a string	`%subst`	`%subst(string : start {: length})`	String
Find text inside a string	`%scan`	`%scan(search : source {: start {: length}})`	String
Remove blanks from both ends	`%trim`	`%trim(string {: chars})`	String
Replace or insert text	`%replace`	`%replace(replacement : source {: start {: length}})`	String
Check characters against an allowed list	`%check`	`%check(comparator : base {: start})`	String
Get the length of a value	`%len`	`%len(expression)`	String
Turn a number or date into text	`%char`	`%char(expression {: format})`	String
Convert text to a whole number	`%int`	`%int(expression)`	Numeric
Convert to packed or zoned decimal	`%dec`	`%dec(expression : digits : decimals)`	Numeric
Round while converting	`%inth`, `%dech`	`%dech(expression : digits : decimals)`	Numeric
Format a number for display	`%editc`	`%editc(number : edit-code)`	Numeric
Build a date	`%date`	`%date({value {: format}})`	Date and time
Add or subtract a duration	`%days`, `%months`, `%years`	`date + %months(1)`	Date and time
Count the time between two values	`%diff`	`%diff(value1 : value2 : unit)`	Date and time
Extract a year, month or day	`%subdt`	`%subdt(value : unit)`	Date and time
Test whether a record was found	`%found`	`%found({file})`	File and error handling
Test for end of file	`%eof`	`%eof({file})`	File and error handling
Test whether an operation failed	`%error`	`%error`	File and error handling
Count array elements	`%elem`	`%elem(array)`	Array and list

For %char, the optional second parameter is a format for dates and times, and a CCSID for character data. The syntax lines are summaries. Confirm exact parameter rules in the family page, and in IBM’s ILE RPG reference for your release, before relying on an edge case.

Alphabetical index

Every BIF named on this page, with what it does and the family page that covers it.

BIF	What it does	Family page
`%abs`	Absolute value	Numeric
`%char`	Convert to character data	String
`%check`, `%checkr`	Position of the first character not on an allowed list	String
`%date`	Build or convert a date	Date and time
`%days`, `%months`, `%years`	Date durations	Date and time
`%dec`, `%dech`	Convert to packed decimal, truncating or rounding	Numeric
`%diff`	Time between two values	Date and time
`%div`, `%rem`	Integer quotient and remainder	Numeric
`%editc`	Format a number with an edit code	Numeric
`%elem`	Number of array elements	Array and list
`%eof`, `%found`, `%equal`	Result of the last file operation	File and error
`%error`, `%status`	Error state after an operation with the `(e)` extender	File and error
`%int`, `%inth`	Convert to a whole number, truncating or rounding	Numeric
`%len`	Length of a value	String
`%lookup`	Search an array	Array and list
`%replace`	Replace or insert text	String
`%scan`	Position of text inside a string	String
`%size`	Size of a variable in bytes	Array and list
`%subdt`	One part of a date, time or timestamp	Date and time
`%subst`	Part of a string	String
`%time`, `%timestamp`	Build or convert a time or timestamp	Date and time
`%trim`, `%triml`, `%trimr`	Remove blanks	String
`%xlate`	Translate characters	String

BIF families

String BIFs: search, slice, trim, replace and convert text. See the RPGLE String BIFs Reference; the teaching version is ILE RPG String Handling. Two functions have their own pages: the RPGLE %SCAN and %SCANRPL Reference and the RPGLE %SUBST Reference.
Numeric and conversion BIFs: convert between data types and control rounding. See the RPGLE Numeric and Conversion BIFs Reference. For storage and precision, read RPGLE Data Types, Lengths and Precision.
Date and time BIFs: build dates, do duration arithmetic and measure differences. See the RPGLE Date and Time BIFs Reference; the teaching version is ILE RPG Date, Time and Timestamp Handling.
Array and list BIFs: %elem, %lookup and friends. See the RPGLE Array and List BIFs Reference; the teaching version is RPGLE Arrays and Tables.
File and error BIFs: %found, %eof and %error replace the indicators that older code uses to test the result of a file operation. See the RPGLE File and Error BIFs Reference.

Choosing between similar BIFs

%subst or %replace: %subst reads part of a string, %replace returns a changed copy.
%scan or %check: %scan finds a known piece of text, %check finds the first character that is not on an allowed list.
%int or %dec: %int gives a whole number, %dec lets you choose digits and decimals. %inth and %dech round, where %int and %dec truncate.
%diff or date arithmetic: use %diff to count the time between two values, and + or - with %days, %months or %years to move a date.
%found or %eof: %found tells you whether a keyed read or chain found a record, %eof whether a sequential read hit the end of the file.

Related lessons

RPGLE Fixed, Free and Fully Free Specifications explains why BIFs belong to the free-form style.
RPGLE Arrays and Tables teaches the array BIFs in context.

FAQ

What is a built-in function in RPGLE?

A function the compiler provides, written with a leading percent sign and used inside an expression. You do not declare or import it.

Can I use BIFs in fixed-format calculation specifications?

BIFs are expression functions. In fixed-format code you can use them inside an EVAL operation or another expression-based opcode, but not as a standalone factor in a classic opcode such as ADD.

Where do the old opcodes fit?

Many BIFs replaced an opcode: %subst replaced SUBST, %scan replaced SCAN, and %found replaced a result indicator. The opcodes still compile; new code should use the BIF. The RPGLE Opcode Reference lists the opcodes and the BIFs that replace them.

Summary

Start with the family that matches your task: string, numeric and conversion, date and time, array and list, or file and error. For old fixed-format code, use the RPGLE Opcode Reference.