Built In Functions

Built-In Functions

String Functions

DCL-S s VARCHAR(50);

s = '  Hello World  ';
DSPLY %TRIM(s);         // 'Hello World'
DSPLY %LEN(s);          // 15
DSPLY %SUBST(s:3:5);    // 'Hello'
DSPLY %SCAN('World':s); // 9
DSPLY %REPLACE('RPG':'Hello World':1:5);  // 'RPG World'
DSPLY %LOWER('HELLO');  // 'hello'
DSPLY %UPPER('hello');  // 'HELLO'

Numeric Functions

DSPLY %CHAR(%ABS(-42));     // 42
DSPLY %CHAR(%INT(3.7));     // 3
DSPLY %CHAR(%DEC(3.7:5:2)); // 3.70
DSPLY %CHAR(%REM(17:5));    // 2
DSPLY %CHAR(%SQRT(144));    // 12

Date/Time Functions

// INZ(*SYS): the date/time the program starts. An initial value is fixed
// at compile time, so INZ(%DATE) is not allowed (IBM: RNF0314).
DCL-S today DATE INZ(*SYS);
DCL-S now TIME INZ(*SYS);
DCL-S ts TIMESTAMP INZ(*SYS);
DCL-S future DATE;

future = today + %DAYS(30);
DSPLY %CHAR(future);

DCL-S daysBetween INT(10);
daysBetween = %DIFF(future : today : *DAYS);
DSPLY %CHAR(daysBetween);  // 30

%DATE, %TIME and %TIMESTAMP convert a character or numeric value read in a format: *ISO (the default, whatever the program's DATFMT), *USA, *EUR, *JIS, *MDY, *DMY, *YMD, *JUL, *LONGJUL, *CYMD, *CMDY, *CDMY, and for times *HMS. A separator can follow the format (*MDY-), or 0 for none (*ISO0); numbers never have separators. A value that is not a valid date or time is status 112. A *ISO time is written hh.mm.ss.

DCL-S due DATE;
DCL-S start TIME;
due = %DATE('01/15/24' : *MDY);
due = %DATE(20240115 : *ISO);
start = %TIME('14.30.00');
due = %DATE(ts);                  // the date part of a timestamp

Typed literals are written with their type letter: D'2024-01-15', T'14.30.00', Z'2024-01-15-14.30.00.000000', all in *ISO format.

IF due > D'2024-01-01';
  DSPLY 'After New Year';
ENDIF;

TEST — Check a Date or Time

TEST(E) checks the value of a date, time or timestamp field; TEST(DE), TEST(TE) and TEST(ZE) check a character or numeric field as one, in the format given or the program's DATFMT (else *ISO). %ERROR is on when the value is not valid. In free form the E is required (IBM: RNF5056), and D, T and Z apply only to character and numeric fields (RNF7523).

DCL-S entered CHAR(10) INZ('02/30/2024');
TEST(DE) *USA entered;
IF %ERROR;
  DSPLY 'Not a date';
ENDIF;