Function definitions

This section provides an overview of the argument type, function type, and value returned for each of the intrinsic functions.

For more information about the intrinsic functions, see Table 1.

Argument types and function types are abbreviated as follows:

Abbreviation Meaning
A Alphabetic
D DBCS
I Integer
K Keyword
N Numeric
O Other, as specified in the function definition (pointer, function-pointer, procedure-pointer, or object reference)
U National
X Alphanumeric
UT UTF-8

Each intrinsic function is described in detail in the topics that follow the table below.

Table 1. Table of functions
Function name Arguments Function type Value returned
ABS N1 I or N Absolute value of N1
ACOS N1 N Arccosine of N1
ANNUITY N1, I2 N Ratio of annuity paid for I2 periods at interest of N1 to initial investment of one
ASIN N1 N Arcsine of N1
ATAN N1 N Arctangent of N1
BIT-OF A1, D1, I1, N1, X1, U1, UT1, or O1 X Alphanumeric character string consisting of characters "1" and "0" that correspond to the binary value of each byte in the argument
BIT-TO-CHAR X1 X Character string consisting of bytes that correspond to the bit pattern indicated by the sequence of "0" and "1" characters in the argument
BYTE-LENGTH A1, D1, N1, X1, U1, UT1, or O1 I Integer that is equal to the length of the argument in bytes
CHAR I1 X Character in position I1 of program collating sequence
COMBINED-DATETIME I1, N2 N Numeric representation of combined integer date and standard numeric time
COS N1 N Cosine of N1
CURRENT-DATE None X Current date and time and difference from Greenwich mean time
DATE-OF-INTEGER I1 I Standard date equivalent (YYYYMMDD) of integer date
DATE-TO-YYYYMMDD I1, I2 I Standard date equivalent (YYYYMMDD) of I1 (standard date with a windowed year, YYMMDD), according to the 100-year interval whose ending year is specified by the sum of I2 and the year at execution time
DAY-OF-INTEGER I1 I Julian date equivalent (YYYYDDD) of integer date
DAY-TO-YYYYDDD I1, I2 I Julian date equivalent (YYYYDDD) of I1 (Julian date with a windowed year, YYDDD), according to the 100-year interval whose ending year is specified by the sum of I2 and the year at execution time
DISPLAY-OF
U1, UT1, I2
 X Each character in U1 or UT1 converted to a corresponding character representation using a code page identified by I2, if specified, or a default code page selected at compile time if I2 is unspecified
E None N Approximation of e, the base of natural logarithms
EXP N1 N Approximation of the value of e raised to the power of N1
EXP10 N1 N Approximation of the value of 10 raised to the power of N1
FACTORIAL I1 I Factorial of I1
FORMATTED-CURRENT-DATE U1, X1, or UT1 U, X, or UT Formatted date equivalent of current date and time in the format specified in argument-1
FORMATTED-DATE U1, X1, or UT1, I2 U, X, or UT Formatted date equivalent of integer date contained in argument-2 in the format specified in argument-1
FORMATTED-DATETIME U1, X1, or UT1, I2, N3, I4 U, X, or UT Formatted date (from integer date in argument-2) and time (from standard numeric time in argument-3) in the format specified by argument-1. Offset from UTC, if the format requires it, is supplied by argument-4
FORMATTED-TIME U1, X1, or UT1, N2, I3 U, X, or UT Formatted time equivalent of standard numeric time contained in argument-2 in the format specified in argument-1. Offset from UTC, if the format requires it, is supplied by argument-3
HEX-OF A1, D1, I1, N1, X1, U1, UT1, or O1 X Alphanumeric character string consisting of the bytes of the argument converted to a hexadecimal representation
HEX-TO-CHAR X1 X Character string consisting of bytes that correspond to the hexadecimal digit characters in the argument
INTEGER N1 I The greatest integer not greater than N1
INTEGER-OF-DATE I1 I Integer date equivalent of standard date (YYYYMMDD)
INTEGER-OF-DAY I1 I Integer date equivalent of Julian date (YYYYDDD)
INTEGER-OF-FORMATTED-DATE U1, UT1, or X1, U2, UT2, or X2 I Integer date equivalent of date contained in argument-2 whose format is described by argument-1
INTEGER-PART N1 I Integer part of N1
LENGTH A1, N1, O1, X1, U1, or UT1 I Length of argument in national character positions or in alphanumeric character positions or bytes, depending on the argument type
LOG N1 N Natural logarithm of N1
LOG10 N1 N Logarithm to base 10 of N1
LOWER-CASE A1 or X1 X All letters in the argument set to lowercase
U1 U All letters in the argument set to lowercase
UT1 UT All letters in the argument set to lowercase
MAX A1... X Value of maximum argument; note that the type of function depends on the arguments
I1... I Value of maximum argument; note that the type of function depends on the arguments
N1... N Value of maximum argument; note that the type of function depends on the arguments
X1... X Value of maximum argument; note that the type of function depends on the arguments
U1... U Value of maximum argument; note that the type of function depends on the arguments
MEAN N1... N Arithmetic mean of arguments
MEDIAN N1... N Median of arguments
MIDRANGE N1... N Mean of minimum and maximum arguments
MIN A1... X Value of minimum argument; note that the type of function depends on the arguments
I1... I Value of minimum argument; note that the type of function depends on the arguments
N1... N Value of minimum argument; note that the type of function depends on the arguments
X1... X Value of minimum argument; note that the type of function depends on the arguments
U1... U Value of minimum argument; note that the type of function depends on the arguments
MOD I1, I2 I I1 modulo I2
NATIONAL-OF A1, X1, D1, or UT1 U The characters in the argument converted to national characters, using the code page identified by I2, if specified, or a default code page selected at compile time if I2 is unspecified
A1, X1, D1, or UT1; I2 U The characters in the argument converted to national characters, using the code page identified by I2, if specified, or a default code page selected at compile time if I2 is unspecified
NUMVAL X1 or U1 N Numeric value of simple numeric string
NUMVAL-C
X1 or U1;
X1, X2;
U1, U2
 N Numeric value of numeric string with optional commas and currency sign
NUMVAL-F
X1 or U1
 N Numeric value or approximation of the numeric value represented by the alphanumeric character string or national character string specified as the argument
ORD A1 or X1 I Ordinal position of the argument in collating sequence
ORD-MAX A1..., N1..., X1..., or U1... I Ordinal position of maximum argument
ORD-MIN A1..., N1..., X1..., or U1... I Ordinal position of minimum argument
PI None N Value that is an approximation of pi, the ratio of the circumference of a circle to its diameter.
PRESENT-VALUE N1, N2... N Present value of a series of future period-end amounts, N2, at a discount rate of N1
RANDOM I1, none N Random number
RANGE I1... I Value of maximum argument minus value of minimum argument; note that the type of function depends on the arguments.
N1... N Value of maximum argument minus value of minimum argument; note that the type of function depends on the arguments.
REM N1, N2 N Remainder of N1/N2
REVERSE A1 or X1 X Reverse order of the characters of the argument
U1 U Reverse order of the characters of the argument
SECONDS-FROM-FORMATTED-TIME U1, UT1, or X1, U2, UT2, or X2 N Standard numeric time equivalent of the data contained in argument-2 as described by the format specified in argument-1
SECONDS-PAST-MIDNIGHT   N Seconds past midnight as provided by the system
SIGN N1 I +1, 0, or -1 depending on the sign of the argument
SIN N1 N Sine of N1
SQRT N1 N Square root of N1
STANDARD-DEVIATION N1... N Standard deviation of arguments
SUM I1... I Sum of arguments; note that the type of function depends on the arguments.
N1... N Sum of arguments; note that the type of function depends on the arguments.
TAN N1 N Tangent of N1
TEST-DATE-YYYYMMDD I1 I 0 if argument-1 is a valid standard date; otherwise identifies the sub-field in error
TEST-DAY-YYYYDDD I1 I 0 if argument-1 is a valid Julian date; otherwise identifies the sub-field in error
TEST-FORMATTED-DATETIME U1, UT1, or X1, U2, UT2, or X2 I 0 if argument-2 conforms in form to the format specified in argument-1 and represents a valid date, time or combined representation according to that description; otherwise, identifies the character in error
TEST-NUMVAL X1 or U1 I
  • If the content of argument-1 conforms to the argument rules for the NUMVAL function, the returned value is 0.
  • If one or more characters are in error, the returned value is the position of the first character in error.
  • Otherwise, the returned value is (FUNCTION LENGTH (argument-1) + 1).
TEST-NUMVAL-C
X1 or U1;
X1, X2;
U1, U2
 I
  • If the content of argument-1 conforms to the argument rules for the NUMVAL-C function, the returned value is 0.
  • If one or more characters are in error, the returned value is the position of the first character in error.
  • Otherwise, the returned value is (FUNCTION LENGTH (argument-1) + 1).
TEST-NUMVAL-F
X1 or U1
 I
  • If the content of argument-1 conforms to the argument rules for the NUMVAL-F function, the returned value is 0.
  • If one or more characters are in error, the returned value is the position of the first character in error.
  • Otherwise, the returned value is (FUNCTION LENGTH (argument-1) + 1).
TRIM A1, X1, U1, or UT1; K1 X, U, or UT Character string that contains the characters in A1, X1, or U1 with leading spaces or trailing spaces deleted (if K1 is specified)
A1, X1, U1, or UT1 X, U, or UT Character string that contains the characters in A1, X1, or U1 with both leading spaces and trailing spaces deleted (if K1 is unspecified)
ULENGTH A1, X1, U1, or UT1 I Length of A1, X1, U1, or UT1 in UTF-8 or UTF-16 characters
UPOS A1, X1, U1, or UT1, I2 I Index of the I2th UTF-8 or UTF-16 character of A1, X1, U1, or UT1
UPPER-CASE A1 or X1 X All letters in the argument set to uppercase
U1 U All letters in the argument set to uppercase
UT1 UT All letters in the argument set to uppercase
USUBSTR A1, X1, U1, or UT1, I2, I3 X, U, or UT Alphanumeric character string that contains the I3 UTF-8 or UTF-16 characters of A1, X1, U1, or UT1, starting at the I2th character position
USUPPLEMENTARY A1, X1, U1, or UT1 I Index of the first Unicode supplementary character of A1, X1, U1, or UT1
UUID4 None X 36-character alphanumeric string that is a version 4 universally unique identifier (UUID)
UVALID A1, X1, U1, or UT1 I 0 if A1, X1, U1, or UT1 contains valid Unicode UTF-8 or UTF-16 data, or the index of the first invalid element of A1, X1, U1, or UT1
UWIDTH A1, X1, U1, or UT1, I2 I Width in bytes of the I2th UTF-8 or UTF-16 character of A1, X1, U1, or UT1
VARIANCE N1... N Variance of arguments
WHEN-COMPILED None X Date and time when program was compiled
YEAR-TO-YYYY I1, I2 I Expanded year equivalent (YYYY) of I1 (windowed year, YY), according to the 100-year interval whose ending year is specified by the sum of I2 and the year at execution time