COBOL Intrinsic Functions

COBOL intrinsic functions are built-in operations you invoke with FUNCTION function-name(arguments). They return a value you can use in MOVE, COMPUTE, IF, or other statements. This page covers the main categories: string functions (LENGTH, UPPER-CASE, NUMVAL), numeric functions (MAX, MIN, MOD, ABS), and date/time (CURRENT-DATE). Exact availability depends on your compiler and standard (e.g. COBOL 2002, 2014; IBM Enterprise COBOL).

Explain Like I'm Five: What Are Intrinsic Functions?

Intrinsic functions are ready-made tools that come with COBOL. Instead of writing a loop to find the longest of three numbers, you say FUNCTION MAX(a, b, c) and get the answer. Instead of counting characters yourself, you say FUNCTION LENGTH(name) and get how long the field is. You give the function an input (or several) and it gives you back one result. You use that result in your calculations or comparisons. They are called "intrinsic" because they are built into the language, not written by you.

How to Use FUNCTION

You write FUNCTION followed by the function name and then the arguments in parentheses. For example: FUNCTION LENGTH(WS-FIELD), FUNCTION MAX(WS-A, WS-B), FUNCTION UPPER-CASE(WS-NAME). The result is a temporary value; you typically MOVE it to a variable or use it in a condition. Arguments can be identifiers (data names), literals, or expressions, depending on the function. Some functions take no arguments (e.g. CURRENT-DATE, WHEN-COMPILED). The returned value has a type (numeric, alphanumeric, integer) that must match how you use it: e.g. LENGTH returns numeric, so you move it to a numeric field or use it in a numeric comparison.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
       01 WS-NAME   PIC X(30).
       01 WS-LEN   PIC 9(2).
       01 WS-A     PIC 9(3) VALUE 100.
       01 WS-B     PIC 9(3) VALUE 250.
       01 WS-BIG   PIC 9(3).
 
       MOVE FUNCTION LENGTH(WS-NAME) TO WS-LEN
       *> WS-LEN is 30
 
       MOVE FUNCTION MAX(WS-A, WS-B) TO WS-BIG
       *> WS-BIG is 250
 
       IF FUNCTION UPPER-CASE(WS-INPUT) = 'YES'
           PERFORM CONFIRM
       END-IF

String and Character Functions

String intrinsic functions operate on alphanumeric (or national) data. LENGTH returns the declared length of the argument in characters. UPPER-CASE and LOWER-CASE return a copy of the string with letters converted to uppercase or lowercase; other characters are unchanged. REVERSE returns the string with character order reversed. NUMVAL, NUMVAL-C, and NUMVAL-F take an alphanumeric item that contains a number (possibly with sign, decimal, or currency symbol) and return the numeric value; use them to convert user input or edited fields to numeric for arithmetic. The result of NUMVAL is numeric; the others above return alphanumeric except NUMVAL family. See the String Functions tutorial for more detail and examples.

Numeric Functions

MAX and MIN take two or more arguments of the same type (all numeric or all alphanumeric) and return the maximum or minimum. For numeric arguments the comparison is numeric; for alphanumeric it is character (collating sequence). MOD and REM take two numeric arguments and return the remainder of dividing the first by the second; use MOD for modulo arithmetic (e.g. even/odd, wrap-around). ABS takes one numeric argument and returns its absolute value. INTEGER (when available) returns the integer part of a numeric value (truncation toward zero). These functions return numeric values; you can use them in COMPUTE or MOVE to a numeric field.

1
2
3
4
5
6
7
8
9
10
11
       01 WS-NUM   PIC 9(4).
       01 WS-REM   PIC 9(2).
 
       COMPUTE WS-REM = FUNCTION MOD(17, 5)
       *> WS-REM is 2 (remainder of 17/5)
 
       MOVE FUNCTION MAX(100, 200, 50) TO WS-NUM
       *> WS-NUM is 200
 
       MOVE FUNCTION ABS(WS-SIGNED) TO WS-NUM
       *> WS-NUM is positive value

Date and Time Functions

CURRENT-DATE (or equivalent, depending on compiler) returns a 21-character value with the current date and time: typically YYYYMMDD for date, then hhmmss for time, then fractional seconds and optional timezone. You can reference-modify the result to get just the date (e.g. (1:8)) or just the time. Use it for timestamps, aging, or date comparisons. WHEN-COMPILED returns a value that represents when the program was compiled; useful for version or build identification in dumps or logs. Exact format and names vary by compiler; check your manual.

1
2
3
4
5
6
7
8
       01 WS-DATE-TIME PIC X(21).
       01 WS-DATE-ONLY  PIC X(8).
       01 WS-TIME-ONLY  PIC X(6).
 
       MOVE FUNCTION CURRENT-DATE TO WS-DATE-TIME
       MOVE WS-DATE-TIME(1:8) TO WS-DATE-ONLY
       MOVE WS-DATE-TIME(9:6) TO WS-TIME-ONLY
       *> WS-DATE-ONLY = YYYYMMDD, WS-TIME-ONLY = hhmmss

NUMVAL, NUMVAL-C, and NUMVAL-F in Detail

NUMVAL converts an alphanumeric (or national) item that contains a valid numeric representation (digits, optional sign, decimal point) to a numeric value. Leading and trailing spaces are allowed. If the content is not valid (e.g. letters where digits are expected), the behavior is implementation-defined (exception or invalid value). NUMVAL-C is for strings that may include a currency symbol (e.g. $ or €); the compiler knows the symbol and strips it. NUMVAL-F is for formatted numeric strings (e.g. with commas or a specific picture). Use these when you read numeric data as character (e.g. from a file or screen) and need to do arithmetic. The result is numeric; move it to a numeric field or use it in COMPUTE.

Argument Types and Return Types

Each function expects arguments of a certain class: numeric, alphanumeric, national, or integer. Passing the wrong type can cause a compile error or runtime error. The return type is also fixed: LENGTH returns integer/numeric; UPPER-CASE returns alphanumeric; MAX returns the same type as its arguments. When you MOVE the result to a variable, the receiving field must be compatible (same or convertible type and size). For example, moving FUNCTION LENGTH(WS-X) to a PIC 9(4) is fine; moving it to a PIC X(4) is wrong. Check your compiler documentation for the exact argument and return types of each function.

Step-by-Step: Using MAX and MIN

1. Ensure the arguments are the same type (all numeric or all alphanumeric). For numeric, they can be literals or identifiers.
2. Write FUNCTION MAX(arg1, arg2, ...) or FUNCTION MIN(arg1, arg2, ...). You can pass more than two arguments where the compiler supports it.
3. Use the result: MOVE to a variable of the same type and size, or use in IF/EVALUATE or COMPUTE. For example: MOVE FUNCTION MAX(WS-A, WS-B) TO WS-MAX.

Step-by-Step: Converting Display Data with NUMVAL

1. Have the alphanumeric field that contains the number (e.g. user input or file field). It should look like a number: digits, optional sign, optional decimal point. Trim or validate if needed.
2. Use FUNCTION NUMVAL(ws-field) or NUMVAL-C (if currency) or NUMVAL-F (if formatted). The result is numeric.
3. MOVE the result to a numeric data item or use it in COMPUTE. Handle any exception if the content is invalid (check your compiler for ON EXCEPTION or equivalent).

Best Practices

• Use intrinsic functions instead of hand-written loops for length, max, min, and case conversion when available; they are clear and often optimized.
• Match argument and return types: move numeric results to numeric fields, alphanumeric results to alphanumeric fields of sufficient length.
• For NUMVAL, ensure the source data is valid numeric text; invalid data may cause exceptions or wrong values.
• When using CURRENT-DATE, document the format (YYYYMMDD etc.) and use reference modification consistently so you do not mix up date and time positions.
• Check your compiler and standard level for which functions are available; IBM Enterprise COBOL and other vendors may add functions beyond the base standard.

Test Your Knowledge