Anatomy of a Program Logic Manual

s01 · Program Narrative

Daily Transaction Report

What the program does, in source-grounded prose.

CBTRN03C is a batch COBOL report program in the CardDemo application that produces a Daily Transaction Report L5, L179. It reads a sequential transaction file pre-sorted and pre-filtered by a JCL SORT step, enriches each transaction with card-to-account cross-reference data, transaction type descriptions, and transaction category descriptions via three indexed lookup files, then writes a formatted report containing page headers, detail lines, page totals, account-level subtotals (triggered by card-number control breaks), and a grand total.

The program's function is stated in its header comment as "Print the transaction detail report" L5. PROGRAM-ID is CBTRN03C L23, AUTHOR is AWS L24.

s01 · I/O Summary

Every file the program touches

Direction, organization, access mode, key, and status variable — for all six files.

Direction	File	DD Name	Org.	Access	Key	Status Var.
Input	TRANSACT-FILE	TRANFILE	Sequential	Sequential	—	TRANFILE-STATUS L116
Input	XREF-FILE	CARDXREF	Indexed	Random	FD-XREF-CARD-NUM L36	CARDXREF-STATUS L133
Input	TRANTYPE-FILE	TRANTYPE	Indexed	Random	FD-TRAN-TYPE L42	TRANTYPE-STATUS L149
Input	TRANCATG-FILE	TRANCATG	Indexed	Random	FD-TRAN-CAT-KEY L48	TRANCATG-STATUS L167
Input	DATE-PARMS-FILE	DATEPARM	Sequential	Sequential	—	DATEPARM-STATUS L250
Output	REPORT-FILE	TRANREPT	Sequential	Sequential	—	TRANREPT-STATUS L246

s04 · Hierarchical Structure Map

The program's control flow at a glance

An auto-generated structure chart showing every PERFORM path, including the loop body and EOF flush.

PROCEDURE DIVISION (L291–L349)
├── DISPLAY 'START OF EXECUTION OF PROGRAM CBTRN03C' (L292)
├── PERFORM 0000-TRANFILE-OPEN  (L293)
├── PERFORM 0100-REPTFILE-OPEN  (L294)
├── PERFORM 0200-CARDXREF-OPEN  (L295)
├── PERFORM 0300-TRANTYPE-OPEN  (L296)
├── PERFORM 0400-TRANCATG-OPEN  (L297)
├── PERFORM 0500-DATEPARM-OPEN  (L298)
├── PERFORM 0550-DATEPARM-READ  (L300)
│     └── 9910-DISPLAY-IO-STATUS / 9999-ABEND-PROGRAM (on error)
├── PERFORM UNTIL END-OF-FILE = 'Y' (L302–L338)
│   ├── PERFORM 1000-TRANFILE-GET-NEXT  (L304)
│   ├── [date range filter — NEXT SENTENCE exits loop if out-of-range] (L305–L310)
│   ├── [card-number control break] (L313–L320)
│   │     ├── PERFORM 1120-WRITE-ACCOUNT-TOTALS (L315)
│   │     └── PERFORM 1500-A-LOOKUP-XREF        (L319)
│   ├── PERFORM 1500-B-LOOKUP-TRANTYPE          (L322)
│   ├── PERFORM 1500-C-LOOKUP-TRANCATG          (L327)
│   └── PERFORM 1100-WRITE-TRANSACTION-REPORT   (L328)
│         ├── PERFORM 1120-WRITE-HEADERS        (first time / page break)
│         ├── PERFORM 1110-WRITE-PAGE-TOTALS    (on page break)
│         └── PERFORM 1120-WRITE-DETAIL         (L421)
├── PERFORM 9000-TRANFILE-CLOSE  (L340)
├── PERFORM 9100-REPTFILE-CLOSE  (L341)
├── …  (close paragraphs L342–L345)
└── GOBACK (L349)

Excerpt — the full PLM also documents every called paragraph in its own table with line range, line count, and purpose (26 paragraphs total).

s08 · Error and Exception Handling

Every status check, every failure path

Compliance teams ask "what does this program do when something goes wrong?" Brevidy answers in a table.

File	Status Variable	Check	Success	Failure
TRANSACT-FILE	TRANFILE-STATUS	IF = '00' L511	APPL-RESULT=0	DISPLAY → 9910 → 9999 (abend)
REPORT-FILE	TRANREPT-STATUS	IF = '00' L529	APPL-RESULT=0	DISPLAY → 9910 → 9999
XREF-FILE	CARDXREF-STATUS	IF = '00' L547	APPL-RESULT=0	DISPLAY → 9910 → 9999
TRANTYPE-FILE	TRANTYPE-STATUS	IF = '00' L565	APPL-RESULT=0	DISPLAY → 9910 → 9999
TRANCATG-FILE	TRANCATG-STATUS	IF = '00' L583	APPL-RESULT=0	DISPLAY → 9910 → 9999
DATE-PARMS-FILE	DATEPARM-STATUS	IF = '00' L601	APPL-RESULT=0	DISPLAY → 9910 → 9999

Abend codes

The program uses a single user-abend code — 999 — for all I/O failures, raised via CALL 'CEE3ABD' from 9999-ABEND-PROGRAM L758. TIMING=0 means the abend is immediate.

Literal error message text

The full PLM includes a 19-row table listing every literal DISPLAY message the program emits on failure — by paragraph and source line. Operations teams use it as a message-to-paragraph lookup for SOC runbooks. Examples:

Line	Paragraph	Literal text
L519	0000-TRANFILE-OPEN	'ERROR OPENING TRANFILE'
L619	1500-A-LOOKUP-XREF	'INVALID CARD NUMBER : ' + FD-XREF-CARD-NUM
L759	9999-ABEND-PROGRAM	'ABENDING PROGRAM'
— 16 more rows in the full PLM, grounded in notable_constructs.display_statements[] —

s01 · Negative Assertions

What this program does not do

Brevidy is one of the few documentation systems that explicitly states absence. For each search we ran, we report the result — found or not found — so reviewers don't have to take silence as proof.

• absent No embedded SQL (EXEC SQL) detected in expanded source
• absent No CICS commands (EXEC CICS) detected
• absent No IMS DL/I calls detected
• absent No SORT / MERGE in COBOL (sorting is done by the JCL SORT step)
• absent No application CALLs (sole CALL is to LE service CEE3ABD)
• absent No LINKAGE SECTION (not a called subprogram)
• absent No REWRITE or DELETE operations (read-only inputs)
• absent No STRING, UNSTRING, or INSPECT
• absent No COMPUTE (arithmetic via ADD / SUBTRACT)
• absent No ACCEPT or STOP RUN statements
• absent No GO TO statements

Each item verified by a deterministic STB scan (notable_constructs.absence_facts[]) — not by an LLM "remembering" what wasn't there.

s18 · Copybook Inventory

Copybooks, and who else uses them

Every copybook resolved during expansion is listed with the records it defines and the other programs in your corpus that consume it.

Copybook	Lines	Defines	Shared with (corpus-wide)
CVTRA05Y	L93–L115	TRAN-RECORD (350 B)	8 others — CBACT04C, CBTRN01C, CBTRN02C, COBIL00C, CORPT00C, COTRN00C, COTRN01C, COTRN02C
CVACT03Y	L120–L132	CARD-XREF-RECORD (50 B)	11 others — CBACT03C, CBACT04C, CBSTM03A, CBTRN01C, CBTRN02C, COACTUPC, COACTVWC, COBIL00C, COPAUA0C, COPAUS0C, COTRN02C
CVTRA03Y	L137–L148	TRAN-TYPE-RECORD (60 B)	Unique to CBTRN03C
CVTRA04Y	L153–L166	TRAN-CAT-RECORD (60 B)	Unique to CBTRN03C
CVTRA07Y	L171–L245	Report layout records	Unique to CBTRN03C

Sharing data is read from the corpus-wide post-pass cross_corpus.copybook_consumers[] — each consumer is verified by source COPY resolution, never by inference.

s02 · System-Level Context

How this program runs in production

Brevidy connects the COBOL to its JCL — the same documentation answers "what does the program do" and "how is it invoked."

Pipeline step sequence

From jcl_facts.tier2_enhanced.step_sequence — the full pipeline that feeds this program:

#	Step	Program	What it does
1	STEP05R.PRC001	IDCAMS	Backup copy of the transaction VSAM KSDS to a sequential GDG (housekeeping) JCL L23–33
2	STEP05R	SORT	Filters by date range ('2022-01-01' to '2022-07-06') and sorts by TRAN-CARD-NUM ascending; SORT key at byte offset 263, length 16 JCL L37–55
3	STEP10R	CBTRN03C	This program — produces the formatted Daily Transaction Report JCL L59

DD statements for STEP10R

DD Name	DSN	DISP	Notes
TRANFILE	AWS.M2.CARDDEMO.TRANSACT.DALY(+1)	SHR	Input · daily sorted transactions (GDG)
CARDXREF	AWS.M2.CARDDEMO.CARDXREF.VSAM.KSDS	SHR	Input · VSAM KSDS
TRANTYPE	AWS.M2.CARDDEMO.TRANTYPE.VSAM.KSDS	SHR	Input · VSAM KSDS
TRANCATG	AWS.M2.CARDDEMO.TRANCATG.VSAM.KSDS	SHR	Input · VSAM KSDS
DATEPARM	AWS.M2.CARDDEMO.DATEPARM	SHR	Input · date-range parameter file
TRANREPT	AWS.M2.CARDDEMO.TRANREPT(+1)	(NEW,CATLG,DELETE)	Output · LRECL=133, RECFM=FB, GDG