Easytrieve Built-in Functions Overview

Functions Versus Statements

Statements drive program flow—JOB INPUT, IF, PRINT, FILE. Functions compute values within expressions. NET = GROSS - TAX uses arithmetic operators only. HEADER-DATE = DATE-FUNC() uses a function call on the right side—exact function name and parentheses syntax depend on your release documentation. You cannot typically place a bare function call as its own top-level statement line unless grammar defines it as a callable form. Think of functions as vocabulary inside formulas, not as standalone job steps.

1
2
3
4
5
6
7
* Assignment using a function result (names vary by release)
WS-TODAY = $DATE
WS-ABS-AMT = ABS(VARIANCE)
 
IF ABS(DELTA) GT TOLERANCE
   PRINT EXCEPTION-RPT
END-IF

General Invocation Pattern

Most built-ins follow function-name open-paren argument-list close-paren. Some vendors prefix function names with dollar sign or other sigils in Plus documentation—verify literal spelling in your manual; do not guess from other languages. Arguments may be fields, literals, or nested expressions. Return type must fit the receiving field on assignment— assigning a long formatted string into A 8 truncates or errors per rules. Nested calls ABS(MAX(A,B)) are valid when inner return type satisfies outer parameter requirements.

Function Categories

Broadcom and legacy CA manuals group built-ins by purpose. This tutorial section mirrors those families with dedicated index pages and eventual per-function depth. Use the category index when you know the task—format a date, test numeric sign, pad a string—not the function name yet.

String Functions

String functions manipulate alphabetic and alphanumeric fields—extract segments, find delimiters, measure length, or pad for output. Availability varies: classic Report Generator code often uses INDEX with OCCURS 1 A and overlay fields instead of a SUBSTR function. Easytrieve Plus adds richer string builtins documented in Application Reference. When a function exists, prefer it for readability over ten-line INDEX loops. When it does not, procedural string handling remains the portable pattern. Watch fixed-length padding: functions may not trim trailing spaces unless documented—compare results against business rules on A fields.

Date and Time Functions

Date functions return current system date, extract components, or convert between internal packed layouts and display formats. Payroll and billing jobs use them for cycle headers, age calculations, and cutoff comparisons when DATE fields align formats before relational operators apply. Time functions complement batch timestamps in audit trails. Always match internal representation—CCYYMMDD character, packed Julian, or numeric month-day-year—between function output and Library DEFINE types. Mixing formats causes silent wrong comparisons in IF EFF-DATE GT CUTOFF even when function output looks correct on PRINT.

1
2
3
4
5
* Illustrative date header pattern (function names per your manual)
RPT-DATE = $DATE
RPT-TIME = $TIME
 
TITLE 'PAYROLL REGISTER AS OF ' RPT-DATE

Numeric and Math Functions

ABS returns absolute value—common for variance checks IF ABS(ACTUAL - BUDGET) GT LIMIT. MIN and MAX select extremes across arguments or field pairs. Sign tests complement relational operators on negative amounts. Math functions—square root, logarithm—appear in statistical or scientific batch jobs less often than payroll, but documentation lists them for Plus installations. Implied decimal scales propagate: ABS on P 2 currency stays monetary scale. Assign function results into fields with matching precision to avoid truncation.

Conversion and Formatting Functions

Conversion functions translate between data types—packed to zoned, binary to display, character digits to numeric—without manual PROC nibble logic. Formatting functions apply edit masks similar to COBOL PIC clauses for human-readable SYSPRINT or report columns. EDIT and mask parameters vary by release; copy examples from your manual rather than from other sites. Conversion errors surface at compile time when argument types mismatch; runtime errors appear when source data contains non-numeric characters in supposedly numeric fields.

Testing and Validation Functions

Testing functions classify field content—is numeric, is alphabetic, is blank—before MOVE or arithmetic. Validation jobs gate processing: IF NOT NUMERIC-FUNC(INPUT-FLD) skip bad records to exception file. Combine with NE and EQ filters for data quality pipelines feeding downstream systems. Do not assume every site documents the same test function names—grep your Application Reference index for NUMERIC, ALPHA, or BLANK entries.

File, System, and Report Functions

File functions expose runtime file status or metadata—useful in error PROCs after READ failures. System functions return job name, step information, or environment values for audit headers. Report functions supply page numbers, line counts, or report writer state inside TITLE or LINE expressions. These tie Easytrieve batch output to operational context without hard-coding literals that change every run.

When No Built-in Exists

Easytrieve predates modern string libraries. Portable fallback patterns include: overlay fields in Library for substring views; INDEX with OCCURS for byte walks; DO WHILE loops for delimiter parsing; arithmetic for date math when date functions unavailable; EDIT masks for display without separate format function. Document fallback in comments when function availability differs between dev and prod releases. Consider EZT Plus upgrade when maintainers spend more time reimplementing builtins than writing business logic.

Performance Considerations

Function call cost is usually small versus file I/O. Calling functions inside tight loops on millions of records still adds up—hoist invariant calls outside loops when possible. WS-TODAY = DATE-FUNC once per job beats per-record date retrieval for headers. Nested string functions on long fields cost more than simple numeric ABS—profile hot paths if runtime exceeds batch window. Correctness beats micro-optimization: wrong format function wastes more operator time than a few extra CPU microseconds.

Version and Installation Checks

1. Locate Application Reference function index for your product level.
2. Compile one-line test program calling the function before production use.
3. Verify return type fits target DEFINE field length and type.
4. Compare function output against known manual examples.
5. Document function name and release in program header comment.

Common Built-in Function Mistakes

• Assuming COBOL or SQL function names exist in Easytrieve unchanged.
• Wrong argument count or type per manual—compile errors or garbage results.
• Assigning formatted date string into numeric date field without conversion.
• Calling per record when once-per-job suffices.
• Ignoring trailing spaces on alphabetic function results.
• Using Plus-only functions on Report Generator-only compile site.

Explain It Like I'm Five

Built-in functions are tools the language already knows how to use. You ask for today's date and it hands you the answer instead of you counting calendars on your fingers. You ask how long a word is and it tells you the length instead of you spelling it on blocks one by one. Not every toolbox has every tool—your school might have crayons but not glitter glue. Check which tools your Easytrieve has in its manual before you plan a craft project.

Exercises

1. List three function categories and one task each handles.
2. Write pseudocode assigning a date function result to a header field.
3. Explain difference between a function and a MOVE statement.
4. Describe fallback when SUBSTR function is unavailable on your site.
5. Identify one function you would call once per job versus per record and why.