Visual RPG Language Reference  

Functions

Visual RPG built-in functions are similar to RPG operation codes in that they provide an action that returns a result.  However, built-in functions can be used in expressions). (eg, x = %XFOOT( MyArray )).  Built-in functions always start with a percent sign (%).

Usage

function-name{(argument{:argument...})}
- or -
function-name{(argument{,argument...})}

As defined by IBM, built-in functions use a colon (:) to delimit arguments being passed to a function.  For example, the formal IBM syntax for using the %EDITC function is:

    x = %EDITC( NumVal : '3' )

where the colon delimits the functions arguments.

Visual RPG offers an optional, more intuitive syntax, that uses the comma (,) to separate function arguments.  For example, 

    x = %EDITC( NumVal, '3' )

is also valid with Visual RPG code.

You can use whichever syntax you prefer.

Arguments for the function may be variables, constants, expressions, a prototyped procedure, or other built-in functions.  An expression argument can include a built-in function.

See the individual built-in function descriptions for details on what arguments are allowed.

Note – In syntax samples and elsewhere, optional arguments are surrounded by curly braces ({}).  These braces are not used in actual code, they only serve as a visual indicator that an argument is optional.


Built-In Function Argument(s) Value Returned

%ABS

numeric expression

Absolute value of the numeric expression.

%BOOL

boolean expression

True of False value.

%CHAR

numeric, date, time or timestamp expression

Value in character format.

%CHECK

comparator, base {,start}

The first position of base (start, then left to right) that contains a character that does NOT appear in comparator: otherwise 0.  start default is 1.

%CHECKR

comparator, base {,start}

The last position of base (start, then right to left) that contains a character that does NOT appear in comparator: otherwise 0.  start default is the length of the string.

%DATE

(character, numeric, or timestamp expression {,*ISO *JUL | *USA | *EUR | *JIS | *MDY | *DMY | *YMD})

Value of expression converted to type date or the current system date in *ISO date format.

%DAYS

number

The result is a date or timestamp value with the appropriate number of days added or subtracted.

%DEC

numeric expression { ,digits ,decpos }

Value in packed numeric format.

%DECH

numeric expression,digits, decpos

Half-adjusted value in packed numeric format.

%DECPOS

numeric expression

Number of decimal digits.

%DIFF

op1, op2, {*MSECONDS | *SECONDS | *MINUTES | *HOURS | *DAYS | *MONTHS | *YEARS}

The difference (duration) between two date, time, or timestamp values.

%DIGITS

Numeric,start{,length}

Value in integer format.

%DIV

dividend , divisor

The quotient from the division of two arguments; packed numeric if either operand is a packed, zoned, or binary numeric value, or integer if either operand is an integer numeric value.

%EDITC

non-float numeric expression , edit code {, *ASTFill | *CURSYM | currency-symbol})

Value in string format representing the edited value.

%EDITFLT

numeric expression

Character external display representation of float.

%EDITW

non-float numeric expression , edit word

Value in string format representing the edited value.

%ELEM

array, table, or multiple occurrence data structure name

Number of elements or occurrences.

%EOF

{file name}

'1' if the most recent read operation or write to a subfile ended in an end of file or beginning of file condition; otherwise, it returns '0'.

%EQUAL

{file name}

'1' if the most recent relevant operation found an exact match; otherwise, it returns '0'.

%ERROR

'1' if the most recent operation with extender 'E' specified resulted in an error condition. '0' and remains unchanged following the operation if no error occurs.

%FLOAT

numeric expression

Value in float format.

%FOUND

{file name}

'1' if the most recent relevant file operation found a record (CHAIN, DELETE, SETGT, SETLL), an element (LOOKUP), or a match (CHECK, CHECKR, SCAN).  Otherwise, this function returns '0'.

%HOURS

number

The result is a time or timestamp value with the appropriate number of hours added or subtracted.

%INT

numeric expression

Value in integer format.

%INTH

numeric expression

Half-adjusted value in integer format.

%KDS

dsn name {,number-keys}

The data structure reference as indicated by setting the Key parameter in the CHAIN, DELETE,  READE,  READPE, SETGT, or SETLL using this function.

%LEN

expression

The length of a program defined variable or database variable defined as variable length, or also the current length of such fields.

%LOOKUP

argument, array {,start-index {,num-elements}}

Returns the array index of the item in array that matches the argument; otherwise, zero if no match is found.

%MINUTES

number

The result is a time or timestamp value with the appropriate number of minutes added or subtracted.

%MONTHS

number

The result is a date or timestamp value with the appropriate number of months added or subtracted.

%MSECONDS

number

The result is a time or timestamp value with the appropriate number of microseconds added or subtracted.

%NULLIND

fieldname

 The name of the field to query or set the null indicator for null-capable fields.

%OCCUR

dsn name

Returns an unsigned numeric value of the current occurrence number of the dsn name (data structure).  Also can be used to set the occurrence number.

%OMITTED

%OMITTED is only valid inside of BegProc routines for ILE procedures, and is only valid on Parameters that have the *OMIT option; i.e.

DCLSRPARM CustName Options (*OMIT)

  if not %OMITTED(CustName)

       // we have a name

  EndIf

%OPEN

file name

'1' if the specified file is open.
'0' if the specified file is closed.

%PARMS

number

%Parms is only valid inside of BegProc routines for ILE procedures.

DCLSRPARM CustName Options(*OMIT)
DCLSRPARM CustAddress
DCLSRPARM CustPhone Options(*Omit, *NoPass) 

   If (%Parms = 3)

      // if we are here, it means that CustPone was passed, but it may be omitted

      If not %OMITTED(CustPhone)

         // we have a valid phone number

      EndIf

   EndIf

%REM

, dividend, divisor

The remainder from the division of the two arguments.

%REPLACE

Replacement string , source string {,start position{,source length to Replace}}

String produced by inserting Replacement string into source string, starting at start position and replacing the specified number of characters.

%SCAN

Search argument, string to be searched {,start position]

First position of search argument in string, or zero if not found.

%SECONDS

number

The result is a time or timestamp value with the appropriate number of seconds added or subtracted.

%SQRT

numeric expression

The square root of the numeric expression.

%SUBARR

array ,start-index {,num-elements}

Returns a section of the specified Array starting at Start-index.  The number of elements returned is specified by num-elements. or the remainder of the array if num-elements is not specified. 

%SUBDT

date, time, or timestamp value, {*MSECONDS | *SECONDS | *MINUTES | *HOURS | *DAYS | *MONTHS | *YEARS}

An unsigned numeric value with the extracted portion of a date, time, or timestamp value.

%SUBST

String,start{,length}

Substring.

%TIME

(character, numeric, or timestamp expression {, *ISO | *HMS | *USA | *EUR | *JIS})

Value of expression converted to type time or the current system time in *ISO format.

%TIMESTAMP

(character, numeric, or timestamp expression {, *ISO | *ISO0})

Value of expression converted to type timestamp or the current system timestamp in *ISO format.

%TLOOKUP

argument, search-table {, alternate_table}

Sets the current table element to the element that satisfies the condition and returns the value *ON, otherwise, *OFF if no match is found.

%TRIM

string

String with left and right blanks trimmed.

%TRIML

string

String with left blanks trimmed.

%TRIMR

string

String with right blanks trimmed.

%XFOOT

array expression

Sum of the elements.

%XLATE

from, to, string {,start position}

Value translated from String, with any From character values replaced with the corresponding To character values.

%YEARS

number

The result is a date or timestamp value with the appropriate number of years added or subtracted.

Related Sections

Visual RPG Language Reference
  Provides a reference of the Visual RPG language.