Easytrieve System Functions

Date and Time Functions

Current date function returns processing date—usually system date at job start unless date simulation PARM or special facility overrides for testing. Time function returns time of day for timestamp lines. Return may be packed numeric CCYYMMDD, character MM/DD/YYYY after format step, or binary seconds since epoch per manual—never assume without reading DEFINE compatibility. Assign RUN-DATE once in initialization PROC before JOB INPUT loop; TITLE references RUN-DATE on every page without re-invoking function. Payroll date-of-run versus pay-period-end date are different business concepts—do not substitute system date for period end stored in control file.

1
2
3
4
5
6
* Illustrative—verify names and formats on your system
RUN-DATE = $DATE
RUN-TIME = $TIME
RUN-DATE-EDIT = EDIT(RUN-DATE, 'MM/DD/YYYY')
 
TITLE 'PAYROLL REGISTER ' RUN-DATE-EDIT

Job and Step Metadata

Job name function returns JCL JOB card name—helps when same program runs under multiple job names in test and prod. Step name identifies which step within job—useful when proc contains multiple Easytrieve steps writing different reports. DISPLAY job and step on SYSPRINT at startup accelerates ops search in SDSF when user reports wrong output. Length of returned name must fit DEFINE A field—eight-character classic job names versus longer special characters on some systems.

User and Security Context

User ID function returns submitter or execution user per security product integration. Audit reports stamp CREATED-BY on output records for SOX trails. Do not log passwords or sensitive tokens—only documented user identifiers. RACF or Top Secret identity may differ from TSO userid displayed—document which identity function returns for your shop.

Formatting System Values

Raw system date into packed field may work for IF comparisons. Human TITLE needs EDIT or date format function second step. Chain: SYS-DATE = $DATE; SYS-DATE-CHAR = EDIT or format function. Mismatch when IF SYS-DATE-CHAR GT LITERAL compares strings not chronology—compare packed dates for date logic, edited strings for display only.

Testing and Simulation Overrides

Test regions simulate dates via control cards or PARM options so regression runs do not depend on calendar day. Document override in test JCL README. Production must use real system date unless business backdating explicitly authorized. Clock changes at midnight and DST transitions affect time function—schedule long jobs crossing midnight knowing RUN-DATE captured at start may differ from date at end.

System Functions Versus Input Control Records

Control file may carry processing date chosen by scheduler—system date function ignores that business date. When scheduler passes date in SYSIN, prefer parameter over $DATE for business as-of. System date suits when did this job run operationally. Both may appear on same report: period end from file, run date from system function.

Performance

Call once per job for invariant values. Per-record system time stamp on million-row output file adds CPU and widens record layout—use when audit mandates row-level timestamp; otherwise job-level header suffices.

Common System Function Mistakes

• DEFINE target too short for formatted date string.
• Using display date in numeric IF compare.
• Confusing system date with pay period date from input.
• Per-record $DATE call when value unchanged entire job.
• Assuming SQL CURRENT DATE equivalent without checking format.
• Hard-coding userid in test then forgetting prod uses function.

Explain It Like I'm Five

System functions ask the computer clock and name tag questions. What day is it today? What time is it? What is this job called? Who pressed start? The answers go on the cover of your homework so the teacher knows when and who turned it in—not inside each math problem unless every line needs its own timestamp.

Exercises

1. Write initialization assigning RUN-DATE before JOB loop.
2. Explain run date versus pay period date on same report.
3. List three system values useful on SYSPRINT startup line.
4. Describe formatting step between $DATE and TITLE display.
5. When would row-level timestamp beat job-level header?