Builtin functions
Usable as an expression anywhere, e.g. &Username = USERID(). Most take zero arguments with a fixed return type; Val() is the exception (see its own entry).
| Function | Return | Description |
|---|---|---|
USERID() | char(10) | IBM i user profile running this program. No arguments. |
PGNAME() | char(10) | Object name of this same program — a compile-time constant, not a runtime lookup. No arguments. |
TODAY() | date | Current system date. No arguments. |
TIME() | char(8) | Current system time formatted "HH:MM:SS" (8 characters). No arguments. |
Val(&CharVariable) | same as the assignment’s destination | Parses a char value into a Number, using the destination of the assignment’s precision/scale — unlike other builtins, it has no fixed return type. Only valid directly as &NumberVariable = Val(&CharExpr); using it anywhere else (nested in another expression, as a Do/Call argument, etc.) is an error. |
CurrentInput() | char(30) | See @Source: Event and Screen. |
String(&NumberVariable, integerDigits[, decimalDigits]) | char(integerDigits [+ 1 + decimalDigits]) | Converts a Number to char, e.g. to concatenate it in a Message(...) (which only accepts text). integerDigits/decimalDigits must be integer literals (compile-time constants) — the return width depends on them. decimalDigits is optional (default 0, no decimal separator in the result). Fixed width, zero-padded (no leading-zero suppression); doesn’t handle negatives specially. |
SubString(&Variable, start, length) | char(length) | Trims a fixed-width chunk out of a char value (variable or literal) so it fits into a smaller variable — e.g. &Short40 = SubString(&Long120, 1, 40). Without this, directly assigning a wider char to a narrower one is a compile-time error. start/length must be integer literals. When the source size is known at compile time, start + length - 1 exceeding it is also a compile-time error. |
Trim(&Variable) | same as the argument (char/varchar) | Removes blanks from both left and right. A single argument. |
LTrim(&Variable) | same as the argument | Removes blanks from the left. A single argument. |
RTrim(&Variable) | same as the argument | Removes blanks from the right. A single argument. |
Length(&Variable) | number | Size of a char/varchar value: for varchar, the actual runtime content length; for char, its declared fixed length. A single argument. |
IndexOf(needle, &haystack) | number | Searches for needle inside haystack and returns the raw position found (1-based if found, 0 if not), with no conversion applied. Exactly two arguments (text to search for, text to search in). |
Date, time and timestamp
Year/Month/Days/Hour/Minute/Second are polymorphic: they accept date/time/timestamp as appropriate (Year/Month/Days with date or timestamp; Hour/Minute/Second with time or timestamp) — there’s no need for a different name per type.
format (where it applies) is always optional: if omitted, it falls back to the value configured in @GeneratorConfig (Date Format/Time Format/Timestamp Format); if there’s no configuration either, the system default format is used.
| Function | Return | Description |
|---|---|---|
Year(&Variable) | number(4) | Year of a date/timestamp. |
Month(&Variable) | number(2) | Month of a date/timestamp. |
Days(&Variable) | number(2) | Day of the month of a date/timestamp. |
Hour(&Variable) | number(2) | Hour of a time/timestamp. |
Minute(&Variable) | number(2) | Minute of a time/timestamp. |
Second(&Variable) | number(2) | Second of a time/timestamp. |
DateDiff(&Date1, &Date2, Unit) | number | Difference between two dates, in Days/Months/Years (bare word, not a string). Positive when Date1 is later than Date2, negative otherwise. |
TimeDiff(&Time1, &Time2, Unit) | number | Same as DateDiff, over time, with Hours/Minutes/Seconds. |
TimestampDiff(&Ts1, &Ts2, Unit) | number | Same as DateDiff, over timestamp, with all 6 units enabled: Seconds/Minutes/Hours/Days/Months/Years. |
DateAdd(&Date, amount, Unit) | date | Adds (or subtracts, if amount is negative) days/months/years to a date. amount can be any number expression (not just a literal). |
TimeAdd(&Time, amount, Unit) | time | Same as DateAdd, over time, with Hours/Minutes/Seconds. |
TimestampAdd(&Ts, amount, Unit) | timestamp | Same as DateAdd, over timestamp, with all 6 units. |
IsDate(value[, format]) | number(1) | Validates whether value (char/varchar/number) is a valid date in format (optional — one of Iso/Usa/Eur/Jis/Mdy/Dmy/Ymd/Jul). Returns 1/0 (WARP has no boolean type). Not a pure expression — that’s why, just like Val(), it’s only valid directly as &NumberVariable = IsDate(...). |
IsTime(value[, format]) | number(1) | Same as IsDate, over time (format one of Hms/Iso/Usa/Eur/Jis). |
IsTimestamp(value[, format]) | number(1) | Same as IsDate, over timestamp (format one of Iso/Usa/Eur/Jis). Iso is the recommended, most widely compatible format. |
StringToDate(string[, format]) | date | Converts char/varchar to date. |
NumberToDate(number[, format]) | date | Converts number to date — same format rules as StringToDate. |
StringToTime(string[, format]) | time | Converts char/varchar to time. |
StringToTimestamp(string[, format]) | timestamp | Converts char/varchar to timestamp. |
DateToString(&Date[, format]) | char(10) | Converts date to text — same format rules. |
TimeToString(&Time[, format]) | char(8) | Converts time to text. |
TimestampToString(&Ts[, format]) | char(26) | Converts timestamp to text (26 = ISO width with microseconds). |
Now() | timestamp | Current system timestamp. No arguments. |
Examples
&Username = USERID()
&Program = PGNAME()
&Today = TODAY()
&CurrentTime = TIME()
&Quantity = Val(&QuantityText)
Message("Total: " + String(&Total, 9, 2), Info)
&Short = SubString(&Long, 1, 40)
&Clean = Trim(&WithSpaces)
&Size = Length(&Description)
&Pos = IndexOf("@", &Email)
&DueDate = DateAdd(&Today, 30, Days)
&DaysUntilDue = DateDiff(&DueDate, &Today, Days)
&IsValidDate = IsDate(&DateText, Dmy)
&Now = Now()
&HoursElapsed = TimestampDiff(&Now, &Start, Hours)