Skip to content

CSUTLDTC

Source: cbl/CSUTLDTC.cbl

Type: Batch program

CSUTLDTC — Date Validation Utility

Purpose

CSUTLDTC is a callable utility subprogram that validates whether a given date string is a legitimate calendar date according to a caller-specified format mask. It is a thin wrapper around IBM's Language Environment (LE) CEEDAYS API, translating the raw LE feedback code into a short human-readable result string and a numeric severity code. It's designed to be called from other COBOL programs that need date validation logic (e.g., screen/field edits) without each program having to interact with CEEDAYS directly.

How it works

  • The program is entered via PROCEDURE DIVISION USING LS-DATE, LS-DATE-FORMAT, LS-RESULT — it has no main-line file or terminal I/O; all interaction is through the linkage section parameters.
  • It initializes WS-MESSAGE (the result structure) and clears WS-DATE, then performs A000-MAIN through A000-MAIN-EXIT.
  • A000-MAIN:
  • Copies the caller-supplied LS-DATE into a varying-length "Vstring" structure (WS-DATE-TO-TEST), setting its length field to LENGTH OF LS-DATE (i.e., always 10, since LS-DATE is fixed at PIC X(10)).
  • Does the same for LS-DATE-FORMAT into WS-DATE-FORMAT.
  • Zeroes OUTPUT-LILLIAN (the Lillian-format date CEEDAYS would return).
  • Calls CEEDAYS passing the date, the format mask, the output Lillian date, and a FEEDBACK-CODE structure that CEEDAYS populates with severity/message-number/class/cause codes.
  • Copies the severity and message number out of FEEDBACK-CODE into WS-SEVERITY-N / WS-MSG-NO-N (both numeric redefinitions of alphanumeric fields).
  • Runs an EVALUATE TRUE against a set of 88-level condition names (FC-INVALID-DATE, FC-INSUFFICIENT-DATA, FC-BAD-DATE-VALUE, etc.) that match specific hex token values in FEEDBACK-TOKEN-VALUE, setting WS-RESULT to a corresponding short text message (e.g., "Date is valid", "Invalid month ", "Bad Pic String "). Any unmatched feedback code falls to WHEN OTHER → "Date is invalid".
  • A000-MAIN-EXIT is just an EXIT marker for the PERFORM ... THRU.
  • Back in the main paragraph (unnamed, before A000-MAIN), the assembled WS-MESSAGE (severity, message number, result text, original date, and format mask) is moved to LS-RESULT, the numeric severity is moved to RETURN-CODE, and the program ends with EXIT PROGRAM (not GOBACK — see below).

Inputs & outputs

This program has no files, copybooks, CICS commands, or SQL — all I/O is via the LINKAGE SECTION and one external call:

Item Direction Description
LS-DATE (PIC X(10)) Input The date string to validate.
LS-DATE-FORMAT (PIC X(10)) Input The picture/mask CEEDAYS should use to interpret LS-DATE (e.g., a date format pattern).
LS-RESULT (PIC X(80)) Output Receives the full WS-MESSAGE structure: severity, message code label, result text (15 chars), echoed input date, and echoed format mask.
RETURN-CODE Output Set to the numeric severity code returned by CEEDAYS (WS-SEVERITY-N).
CEEDAYS (external call) Call IBM LE runtime API that converts a date string in a given format into a Lillian-format integer date, or returns a feedback/error code if invalid.

There are no COBOL files, no CICS transactions, and no SQL tables involved — this is a pure computational subroutine.

Things to know

  • No GOBACK, uses EXIT PROGRAM: The commented-out GOBACK suggests this was possibly changed intentionally or during maintenance; EXIT PROGRAM behaves differently from GOBACK in some calling contexts (e.g., dynamic vs. static call semantics, and how control returns to CICS vs. batch callers) — worth confirming this is correct for all call sites.
  • Feedback code interpretation relies on hard-coded hex literals: The 88-level conditions (FC-INVALID-DATE, FC-INSUFFICIENT-DATA, etc.) are matched against specific hex byte patterns (e.g., X'000309CB59C3C5C5') representing LE message tokens. These are brittle — if IBM changes message IDs/severities in a different LE version, the matching could silently fail and fall through to WHEN OTHER ("Date is invalid"), masking the real error.
  • FC-INVALID-DATE label is misleading: It's tied to the all-zero feedback token (X'0000000000000000'), which in CEEDAYS actually signals success (no error). Its associated message text is "Date is valid" — so despite the 88-level name suggesting an error condition, this case represents the valid/success path. Anyone modifying this logic should not assume the label name matches its true meaning.
  • Output Lillian date is discarded: OUTPUT-LILLIAN is computed by CEEDAYS but never used, copied to the linkage section, or returned to the caller — only the feedback/severity/message info is surfaced. If a caller needs the actual converted date value, this program does not provide it.
  • Fixed-length assumptions: LS-DATE and LS-DATE-FORMAT are both hard-coded to 10 characters; LENGTH OF LS-DATE will always evaluate to 10 regardless of actual content, so variable-length dates/formats are not supported by this interface.
  • WS-RESULT text field is a fixed 15-character display string with hard-coded, sometimes inconsistently-padded literals (e.g., 'Invalid Era ' vs 'Datevalue error') — these are cosmetic/debugging aids embedded in LS-RESULT, not structured error codes, so downstream callers parsing this text should do so carefully (whitespace-sensitive).
  • No explicit error handling for the CALL "CEEDAYS" itself (e.g., if the call fails to resolve/load) — any such failure would likely abend rather than being caught here.
  • Comment references indicate this program is part of the CardDemo sample application (version tag CardDemo_v1.0-15-g27d6c6f-68), suggesting it's a demo/utility component rather than a customer-specific business function.

Calls

CEEDAYS

Paragraph flow

flowchart TD
    A000_MAIN["A000-MAIN"]
    A000_MAIN_EXIT["A000-MAIN-EXIT"]

Paragraphs

Paragraph Line Performs
A000-MAIN 103
A000-MAIN-EXIT 152