Chapter 19: Intrinsic Functions Reference -- Key Takeaways

Chapter Summary

Intrinsic functions bring a library of built-in computational, string-manipulation, date-handling, and financial operations directly into the COBOL language, eliminating the need for hand-coded routines or external subroutine calls for many common tasks. This chapter provided a comprehensive reference to the intrinsic functions available in modern COBOL compilers, organized by category: numeric, string, date/time, and financial.

Every intrinsic function is invoked using the FUNCTION keyword followed by the function name and its arguments in parentheses. The result of a function call can be used anywhere a literal or identifier of the corresponding type would be valid, including in MOVE, COMPUTE, IF, DISPLAY, and STRING statements. Functions are evaluated at runtime and return a temporary value that is not stored unless explicitly assigned.

Numeric functions such as MAX, MIN, MEAN, MEDIAN, SUM, MOD, INTEGER, and REM provide arithmetic capabilities that would otherwise require multiple COMPUTE statements and temporary variables. String functions including LENGTH, REVERSE, TRIM, UPPER-CASE, LOWER-CASE, ORD, and CHAR simplify text processing that traditionally demanded elaborate INSPECT and UNSTRING logic. Date functions like CURRENT-DATE, INTEGER-OF-DATE, DATE-OF-INTEGER, and WHEN-COMPILED enable calendar arithmetic and timestamp retrieval without platform-specific system calls. Financial functions such as ANNUITY and PRESENT-VALUE support business calculations that are central to COBOL's traditional domain in banking, insurance, and accounting systems.

Key Concepts

• The FUNCTION keyword precedes every intrinsic function invocation; for example, FUNCTION UPPER-CASE(WS-NAME) converts WS-NAME to uppercase.
• Intrinsic functions return a temporary result that has no persistent storage; the result must be used immediately in an expression or assigned to a data item.
• FUNCTION LENGTH(item) returns the number of characters (or bytes) in an alphanumeric item or the number of digits in a numeric item.
• FUNCTION UPPER-CASE(item) and FUNCTION LOWER-CASE(item) return the alphabetic content converted to the respective case without altering the original data item.
• FUNCTION TRIM(item LEADING/TRAILING/BOTH) removes leading spaces, trailing spaces, or both from an alphanumeric item.
• FUNCTION REVERSE(item) returns the characters of an alphanumeric item in reverse order, which is useful for right-to-left string processing.
• FUNCTION ORD(character) returns the ordinal position of a character in the program's collating sequence; FUNCTION CHAR(integer) returns the character at that ordinal position.
• FUNCTION MAX and FUNCTION MIN accept one or more arguments and return the largest or smallest value, working with both numeric and alphanumeric arguments.
• FUNCTION MEAN, FUNCTION MEDIAN, and FUNCTION SUM perform statistical calculations across their argument lists without requiring explicit loop logic.
• FUNCTION MOD(dividend, divisor) returns the remainder of integer division; FUNCTION REM(dividend, divisor) returns the remainder with the same sign as the dividend.
• FUNCTION INTEGER(number) returns the greatest integer not exceeding the argument, effectively performing a floor operation; FUNCTION INTEGER-PART returns just the integer portion.
• FUNCTION CURRENT-DATE returns a 21-character alphanumeric value containing the date, time, and difference from Greenwich Mean Time in the format YYYYMMDDHHMMSSnnnnnnSHHMM.
• FUNCTION INTEGER-OF-DATE(YYYYMMDD) converts a standard date to an integer day count, and FUNCTION DATE-OF-INTEGER(integer) converts back, enabling calendar arithmetic by simple addition and subtraction.
• FUNCTION ANNUITY(interest-rate, periods) returns the ratio of annuity payment to present value; FUNCTION PRESENT-VALUE(rate, amounts...) computes the present value of a series of future cash flows.
• FUNCTION WHEN-COMPILED returns the date and time the program was compiled, useful for version identification in program output.

Common Pitfalls

• Omitting the FUNCTION keyword: Writing UPPER-CASE(WS-NAME) without FUNCTION causes a compilation error because the compiler interprets the name as an undefined identifier rather than an intrinsic function.
• Assuming functions modify the original item: Intrinsic functions return a new temporary value and never alter their arguments. To store the result, you must MOVE or COMPUTE it into a receiving field.
• Data type mismatches with function results: The result of a string function is alphanumeric and the result of a numeric function is numeric. Moving a numeric function result to an alphanumeric field or vice versa requires attention to the receiving field's PICTURE.
• Passing invalid dates to date functions: FUNCTION INTEGER-OF-DATE requires a valid Gregorian date in YYYYMMDD format. Passing an invalid date such as 20250230 produces undefined results or a runtime error.
• TRIM behavior with all-spaces fields: FUNCTION TRIM applied to a field containing only spaces returns a zero-length string, which can cause unexpected results in subsequent STRING or comparison operations.
• Using MEAN or MEDIAN with a single argument: While syntactically valid, calling MEAN or MEDIAN with one argument simply returns that value, which may indicate a logic error where a list of values was intended.
• Platform-specific function availability: Not all intrinsic functions are available on every compiler. GnuCOBOL supports most standard functions but some IBM-specific extensions may not be present, and vice versa.

Quick Reference

      * Numeric functions
           COMPUTE WS-RESULT = FUNCTION MAX(A B C)
           COMPUTE WS-RESULT = FUNCTION MIN(A B C)
           COMPUTE WS-TOTAL  = FUNCTION SUM(A B C D)
           COMPUTE WS-AVG    = FUNCTION MEAN(A B C D)
           COMPUTE WS-MID    = FUNCTION MEDIAN(A B C)
           COMPUTE WS-REMAIN = FUNCTION MOD(WS-NUM, 10)
           COMPUTE WS-REM    = FUNCTION REM(WS-NUM, 3)
           COMPUTE WS-FLOOR  = FUNCTION INTEGER(WS-DEC)

      * String functions
           MOVE FUNCTION UPPER-CASE(WS-NAME)
               TO WS-NAME-UPPER
           MOVE FUNCTION LOWER-CASE(WS-NAME)
               TO WS-NAME-LOWER
           MOVE FUNCTION TRIM(WS-FIELD BOTH)
               TO WS-TRIMMED
           MOVE FUNCTION REVERSE(WS-TEXT)
               TO WS-REVERSED
           COMPUTE WS-LEN = FUNCTION LENGTH(WS-NAME)
           COMPUTE WS-ORD = FUNCTION ORD("A")
           MOVE FUNCTION CHAR(65) TO WS-CHR

      * Date/time functions
           MOVE FUNCTION CURRENT-DATE TO WS-DATETIME
      *    WS-DATETIME is 21 chars: YYYYMMDDHHMMSSnnnnnnSHHMM
           COMPUTE WS-INT-DATE =
               FUNCTION INTEGER-OF-DATE(20250115)
           COMPUTE WS-NEW-DATE =
               FUNCTION DATE-OF-INTEGER(
                   WS-INT-DATE + 30)
           MOVE FUNCTION WHEN-COMPILED TO WS-COMP-DT

      * Financial functions
           COMPUTE WS-ANNUITY-FACTOR =
               FUNCTION ANNUITY(0.005, 360)
           COMPUTE WS-PAYMENT =
               WS-LOAN-AMOUNT * WS-ANNUITY-FACTOR
           COMPUTE WS-PV =
               FUNCTION PRESENT-VALUE(0.05, 1000 1000)

What's Next

Chapter 20 covers debugging techniques and tools for COBOL programs. You will learn how to use DISPLAY-based debugging, the USE FOR DEBUGGING declarative, compiler listing analysis, and platform-specific tools such as IBM Debug Tool and GnuCOBOL's cobcrun debugger. Many of the intrinsic functions introduced in this chapter, particularly CURRENT-DATE and LENGTH, become valuable aids in constructing informative debug output, and understanding function return types helps when diagnosing data-related abends.