AQUILA/i — Utilities Billing Core

AQUILA/i is a combined electric / water / gas utilities billing core: customer and service-point/meter masters, monthly meter reads, tiered/stepped-rate billing with a printed bill, cash receipts, delinquency & disconnect processing with a matching reconnect arc, late-fee and interest accrual, and a balanced GL posting feed. It is a native AS/400 estate — DDS physical and logical files, RPG (fixed-form and free-form) and ILE COBOL programs, one DB2 SQL table, CL for build and night batch, 5250 display files (including a subfile), a printer file, journaling and an object-authority restriction. This manual is the reference for the operator who runs the online screens and the night-batch chain, and for the developer maintaining the application. It is grounded entirely in the committed source (utilities-app/src/sources.mjs in library AQUILA, src/seed.mjs, and the test/aquila_*.mjs drivers).

A. Overview & Architecture ↑ top

A.1 What it does

AQUILA/i runs the monthly cycle of a combined-service (electric / water / gas) utility:

• Master maintenance — maintain customers (UTCUST) and physical meters (UTMETER) through one callable create/change/inquire program (UTMNT), against a service-point master (UTSVCPT) that links a customer to a utility type, rate class, meter and running balance.
• Metered, tiered billing — one pass over the month's meter reads (UTREAD) applies the stepped rate plan (UTRATE): each read is billed tier-by-tier (a fixed base charge plus per-tier unit prices), writing a bill header (UTBILL), one detail line per tier (UTBLIN), and an audit row (UTLEDG).
• Bill print — a printer-file (UTBILLP) spool of each bill: header, tier detail lines, total, due date.
• Cash application — receipts (UTCASH) are applied to the oldest open bill for a service point, partial or full, updating the bill and service-point balances and journaling a payment.
• Delinquency, disconnect & reconnect — overdue open bills flag the bill, the service point (disconnected) and the customer delinquent; once a disconnected service point is paid up it is reconnected and the customer restored.
• Late fees & interest — a flat late fee plus monthly interest on the outstanding balance is assessed per delinquent bill (packed-decimal math), added to the balances and journaled.
• Balanced GL feed — the night's billing, cash and fee totals are posted as balanced DR/CR rows into a DB2 table (UTGLF) under commitment control, committed only if debits equal credits, with an ILE COBOL cross-check report (UTGLRPT).

A.2 Native-AS/400 architecture

Unlike a two-layer SQL-PL application, AQUILA/i is a classic native IBM i estate: the business logic lives in the RPG and COBOL programs themselves, operating directly on DDS record-level files through keyed and arrival I/O (CHAIN, SETLL/READ, WRITE/UPDATE). Only two paths use embedded SQL — the GL posting program UTGLPST (DB2 INSERT/SUM under commitment control) and the COBOL report UTGLRPT (a cross-check SUM). Everything else is record-level RPG/COBOL.

• DDS data layer. 8 physical files, 2 logical files and 1 DB2 table hold the data; keys and arrival order are chosen deliberately (see D and F.3) so writes append durably and re-reads are safe.
• RPG/COBOL logic layer. 13 RPG programs plus 1 ILE COBOL program implement every rule. Packed-decimal arithmetic (widths from 7P4 unit prices to 15P4 interest accumulators) is exercised throughout the billing and fee math.
• CL orchestration. UTSETUP builds every object, wires journaling and an authority restriction, and seeds the rate plan; UTNIGHT documents the night chain. In practice each night-batch step is submitted as a separate SBMJOB so each program closes its output files fully before the next opens them.

Everything runs in library AQUILA (data root utilities-app/ibmidata-aquila*). The tested jobs run with LIBL = QSYS QGPL AQUILA QTEMP and CURLIB = AQUILA as QSECOFR.

A.3 Component & flow

  MAINTENANCE          ONLINE (5250)          BATCH (night chain, SBMJOB *JOBQ)
  -----------          -------------          --------------------------------
  UTMNT (CC/MC/CI/MI)  UTMENU                  UTBLGEN  --> UTBILL + UTBLIN + UTLEDG'B'
  UTRATLD (rate plan)    1 -> UTACCTIQ         UTCSHPST --> pay oldest bill, UTLEDG'P'
                         2 -> UTBILLIQ (SFL)   UTDELINQ --> flag D, disconnect, UTLEDG'A'
                                               UTFEECAL --> late fee+interest, UTLEDG'F'
                                               UTGLPST  --> balanced DR/CR into UTGLF (DB2)
                                               UTBILLPR --> bill spool (UTBILLP)
     reference: UTRATE (RATECD+TIERNO)         UTRECON  --> reconnect paid-up SP, UTLEDG'R'
            |                                  UTAGE    --> aged-AR buckets (report)
            v                                  UTGLRPT  --> COBOL cross-check (IN/OUT OF BALANCE)
  UTREAD (meter reads, journaled)  --UTBLGEN--> UTBILL --UTAGELF(by DUEDT)--> UTDELINQ/UTFEECAL/UTAGE
            |                                          \
            +--> every posting program APPENDS a keyed row to UTLEDG (journaled A/R audit trail)

A single billing event flows: meter reads land in UTREAD (journaled) → UTBLGEN walks each read against the UTRATE tiers, computes the whole bill in working storage, then writes UTBLIN detail lines, the UTBILL header, rolls up UTSVCPT.SPBAL, and appends a UTLEDG 'B' audit row. Downstream programs read bills through the aging logical file UTAGELF (keyed by DUEDT).

A.4 Object inventory

The catalogue is 8 PFs + 2 LFs + 1 DB2 table, 3 DSPFs + 1 PRTF, 13 RPG programs + 1 ILE COBOL + 2 CL, plus a journal/receiver pair. Sections D and F expand each.

B. Online Transactions & Screens ↑ top

B.1 The command/entry line

AQUILA/i has no CICS transaction identifiers and no menu-driven transid switch. On IBM i each program is reached by name from a 5250 command-entry line (or a JOBQ/scheduler for the batch jobs). The operator equivalent of "type a transid and Enter" is "type a CALL command and Enter". Before invoking anything, the job's library list must include AQUILA — the tested jobs run with LIBL = QSYS QGPL AQUILA QTEMP and CURLIB = AQUILA.

UTMNT is the one online program that is parameter-driven rather than screen-driven: it is called with a dcl-pi entry list so a driver or the day-cycle can maintain masters without a green screen. Its first parameter pAction selects the operation:

UTMNT reports its result in pOutFound ('Y'/'N') and a 30-char pOutMsg (e.g. CUSTOMER CREATED, METER CHANGED, CUSTOMER NOT FOUND, BAD ACTION), and also DSPLYs one line so a batch driver can assert on it without a screen. For a change it re-CHAINs the full key immediately before the UPDATE so it never double-updates a stale read.

B.2 Menu & inquiry screens (UTMENU / UTACCTIQ / UTBILLIQ)

The interactive front end is three WORKSTN programs over three display files. UTMENU (format MENUFMT) offers two options and dynamically CALLs the matching inquiry program; an invalid option shows Invalid option and neither program is called; F3 ends the menu.

Account inquiry — UTACCTIQ (format ACCTINQ)

A plain (non-subfile) screen. Key a service point in ISPNO, Enter: UTACCTIQ CHAINs UTSVCPT, then UTCUST for the name, and shows the customer, utility type, rate class, meter number, status and balance. A blank key prompts Enter a service point.; an unknown one shows Service point not found: <spno>.

Bill inquiry — UTBILLIQ (formats BSFL / BCTL)

The application's one subfile screen. Key a bill number in IBILLNO, Enter: UTBILLIQ CHAINs UTBILL for the header (service point, cycle, usage, status, total charge), then loads the bill's tier lines from UTBLINL (the LF over UTBLIN keyed by BILLNO) into the BSFL subfile via SETLL/READE, and displays them under control record BCTL (SFLPAG(10), SFLSIZ(20)). Indicators drive the subfile: 41=SFLDSP, 42=SFLDSPCTL, 43=SFLCLR, 44=SFLEND(*MORE). A blank key prompts Enter a bill number.; an unknown one shows Bill not found: <billno> and the subfile is cleared.

Subfile columns (BSFL)

B.3 Controls & audit workflow (honest model)

Honest statement: AQUILA/i does not model a four-eyes maker–checker / separate-authorization workflow. There is no "one clerk posts, a second approves" step; a cash receipt is applied immediately by UTCSHPST, and delinquency/disconnect/reconnect happen automatically in the night batch. The control model the application does have is:

• Immutable A/R audit trail (UTLEDG). Every money event appends a keyed row to the ledger: B bill (UTBLGEN), P payment (UTCSHPST), A delinquency/disconnect adjustment (UTDELINQ), F late fee/interest (UTFEECAL), R reconnect (UTRECON). Each posting program draws LEDGSEQ from a disjoint numeric band (see F.3) so keys never collide and the ledger accumulates across the whole night into one durable trail. A full lifecycle reads B → P → A → R.
• Journaling. UTREAD and UTLEDG are journaled (STRJRNPF … IMAGES(*BOTH) to UTJRN/UTRCV), so meter reads and every ledger write/update produce before/after journal images inspectable with DSPJRN/WRKJRNA.
• Object-authority restriction on the ledger. UTSETUP revokes *PUBLIC *ALL on UTLEDG and grants only *CHANGE — a deliberate authority restriction scoped to exactly what the batch posting path needs (read + add + update), exercising RVKOBJAUT/GRTOBJAUT.
• State gating. Business rules gate what can happen by status: cash applies only to a bill BSTAT IN ('O','D') with a positive balance; delinquency flags only open bills with a positive balance; reconnect refuses a service point that still owes (SPBAL > 0); fee assessment runs only for BSTAT='D' bills.
• Balanced GL control total. UTGLPST commits its DB2 posting only if debits equal credits, otherwise ROLLBACK; UTGLRPT (COBOL) independently re-sums and reports IN BALANCE / OUT OF BALANCE.

In sum, the control posture is immutable audit + journaling + object authority + state gating + a balanced control total, all in the data/logic layer, rather than a segregation-of-duties approval workflow.

C. Batch Jobs & the Periodic Cycle ↑ top

AQUILA/i's billing cycle runs as a night-batch chain: bill generation, cash posting, delinquency/disconnect, fee assessment, GL posting and bill print, with reconnect and the aged-AR report as adjuncts. None of the batch programs take CALL parameters — each opens the DDS files it needs, makes one pass, and closes them. Because rows written to an output-opened file may not be visible to a called subprogram until the writer closes it, the chain is not one CL calling several programs in-process; each step is a separate SBMJOB on a *JOBQ, so each program fully closes its output before the next opens it.

-- create the night-batch job queue, then submit the steps in order
CRTJOBQ JOBQ(AQUILA/NITEQ) TEXT('AQUILA night batch queue')
SBMJOB CMD(CALL AQUILA/UTBLGEN)  JOB(AQBLGEN) JOBQ(AQUILA/NITEQ) HOLD(*NO)
SBMJOB CMD(CALL AQUILA/UTCSHPST) JOB(AQCASH)  JOBQ(AQUILA/NITEQ) HOLD(*NO)
SBMJOB CMD(CALL AQUILA/UTDELINQ) JOB(AQDLQ)   JOBQ(AQUILA/NITEQ) HOLD(*NO)
SBMJOB CMD(CALL AQUILA/UTFEECAL) JOB(AQFEE)   JOBQ(AQUILA/NITEQ) HOLD(*NO)
SBMJOB CMD(CALL AQUILA/UTGLPST)  JOB(AQGLP)   JOBQ(AQUILA/NITEQ) HOLD(*NO)
SBMJOB CMD(CALL AQUILA/UTBILLPR) JOB(AQPRT)   JOBQ(AQUILA/NITEQ) HOLD(*NO)

The CL member UTNIGHT documents the same sequence as a single entry point (BILLGEN → CASH POST → DELINQUENCY → FEE → GL POST → bill print); the tested harness drives them as the separate SBMJOBs above.

C.1 Full batch program set

C.2 The night-batch chain, step by step

1. Billing — UTBLGEN

One pass over UTREAD (arrival). For each read it derives a deterministic BILLNO = 'B' + last 7 digits of (READID + 10000000) (so READID 1001 → B0001001, READID 701 → B0000701); a CHAIN(EN) on the header skips an already-billed read (idempotent). It computes the whole bill in wide (11P2) working storage first — walking UTRATE tiers in TIERNO order, each tier billing MIN(remaining, band) × UNITPRC with the sentinel-topped last tier absorbing the rest, plus BASECHG on tier 1 — then, only if the computed charge fits the persistable 9P2 capacity, re-walks the tiers to write the UTBLIN lines, the UTBILL header (BSTAT='O', DUEDT = CYCLE×100 + 20), rolls up SPBAL, and appends the ledger 'B' row. An oversized read is a clean data-quality reject with nothing written (no torn write).

Tiered-billing worked example (from the day-cycle test):
  ELE 1200 kWh:  9.50 base + 500*.12 + 500*.15 + 200*.20 = 9.50 + 60 + 75 + 40 = 184.50
  WAT  400 CCF:  6.00 base + 300*.05 + 100*.08           = 6.00 + 15 + 8       =  29.00
  GAS  250 thm:  7.25 base + 200*.40 +  50*.55           = 7.25 + 80 + 27.50   = 114.75
  DSPLY: UTBLGEN GENERATED=3 SKIPPED=0 REJECTED=0

2. Cash posting — UTCSHPST

One pass over UTCASH (arrival). Each receipt is applied to the single oldest open bill for its service point — a forward READ over UTBILL selecting the first BSTAT IN ('O','D') row for that SPNO with a positive balance. A payment short of the balance is a partial (BSTAT='D', balance reduced); a full/over payment closes it (BSTAT='P', balance 0). SPBAL is reduced by the amount applied and a ledger 'P' row written. A receipt with no matching open bill increments NOBILL.

Example: ACME ELE 184.50, pay 100.00 (partial); RIVERSIDE GAS 114.75, pay 114.75 (full)
  ELE  -> BSTAT=D, BILLBAL=84.50, SPBAL 184.50 -> 84.50
  GAS  -> BSTAT=P, BILLBAL=0.00,  SPBAL 114.75 -> 0.00
  DSPLY: UTCSHPST FULL=1 PART=1 NOBILL=0

3. Delinquency / disconnect — UTDELINQ

One forward pass over the aging LF UTAGELF (keyed by DUEDT). Any bill BSTAT IN ('O','D') with a positive balance is delinquent: the bill is set 'D', its service point SPSTAT='D' (disconnected) and its customer CSTAT='D', and a ledger 'A' row is written.

4. Late fee + interest — UTFEECAL

One pass over UTAGELF. For every BSTAT='D' bill still carrying a positive balance it assesses a flat $5.00 late fee plus monthly interest at 1.50% of the balance, computed in wide packed storage (15P4) then rounded half-up to cents. The fee is added to BILLBAL and SPBAL, and a ledger 'F' row is written. A per-bill idempotency guard scans UTLEDG for an existing 'F' row tagged with this bill's memo, so a bill is fee-assessed at most once per pass.

Example: bill 184.50 delinquent
  fee = 5.00 flat + round(184.50 * 0.0150 = 2.7675 -> 2.77) = 7.77
  BILLBAL 184.50 -> 192.27,  SPBAL grows by the same 7.77
  DSPLY: UTFEECAL ASSESSED=1 TOTFEE=7.77

5. GL posting — UTGLPST

Embedded SQL under commitment control (ctl-opt commit(*yes)). It sums total billed charges (SUM(CHARGE) over UTBILL), cash applied (ledger 'P') and fees (ledger 'F'), then inserts three balanced DR/CR pairs into UTGLF: billing DR A/R (120000) / CR Revenue (400000); cash DR Cash (100000) / CR A/R (120000); fee DR A/R (120000) / CR Fee Revenue (410000). It re-sums the batch just posted and COMMITs only if SUM(DR)=SUM(CR), else ROLLBACK.

6. Bill print — UTBILLPR

One pass over UTBILL; for each bill it writes the PRTF (UTBILLP) header, then the tier detail lines from UTBLINL (READE by BILLNO), the total charge and the due line, producing a UTBILLP spooled file. The spool shows the bill title, the total (e.g. 184.50) and per-tier prices (e.g. 0.1200).

Adjuncts — UTRECON, UTAGE, UTGLRPT

UTRECON closes the disconnect loop: pass 1 reconnects every disconnected service point whose balance is cleared (SPSTAT 'D' → 'A', ledger 'R'); pass 2 restores a customer to CSTAT='A' only if it has no other still-disconnected service point. It refuses to reconnect a service point that still owes. UTAGE buckets open vs delinquent balances for a report. UTGLRPT (ILE COBOL) totals UTBILL.CHARGE through a COMP-3 FD, adds ledger fees, and compares against the UTGLF A/R debit, printing IN BALANCE / OUT OF BALANCE.

C.3 Ordering, idempotency & dependencies

• BILLGEN first. Cash, delinquency, fees, GL and print all read bills; nothing downstream works until UTBLGEN has produced them.
• CASH before DELINQUENCY. A paid-off bill (balance 0) is not flagged delinquent; posting cash first prevents disconnecting a service point that has actually paid.
• DELINQUENCY before FEE. UTFEECAL only fees BSTAT='D' bills, which only UTDELINQ creates.
• GL POST last (once). Run UTGLPST after billing, cash and fees are final, and exactly once per close (see the idempotency note above).
• Idempotent steps. UTBLGEN (deterministic BILLNO + CHAIN(EN) skip) and UTFEECAL (per-bill 'F'-row guard) are safe to re-run within a pass; each posting program's disjoint LEDGSEQ band with a high-water-mark scan (F.3) prevents duplicate-key collisions on a second run in the same business day. UTGLPST is not re-run safe.

D. Data Files (data dictionary) ↑ top

All files are in library AQUILA, grounded in the DDS/SQL in src/sources.mjs. Type codes: nA = character, nS d = zoned decimal (n digits, d after point), nP d = packed decimal. Dates are stored as zoned integers in YYYYMMDD (or YYYYMM for a billing cycle). Unless noted, files are UNIQUE-keyed PFs.

UTCUST — Customer master (key CUSTNO)

UTSVCPT — Service-point master (key SPNO)

UTMETER — Physical meter master (key METERNO)

UTRATE — Tiered rate plan (key RATECD + TIERNO)

Seeded plan (UTRATLD): ELE 1→ub500/0.1200/base9.50, 2→ub1000/0.1500, 3→sentinel/0.2000; WAT 1→ub300/0.0500/base6.00, 2→sentinel/0.0800; GAS 1→ub200/0.4000/base7.25, 2→sentinel/0.5500. (7 tiers: ELE=3, WAT=2, GAS=2.)

UTREAD — Meter reads (key READID; journaled)

UTBILL — Bill header (key BILLNO)

UTBLIN — Bill tier lines (key BILLNO + LINENO)

UTCASH — Cash receipts (key RCPTNO)

UTLEDG — A/R ledger / audit trail (key LEDGSEQ; journaled)

Authority: *PUBLIC is restricted to *CHANGE on UTLEDG (RVKOBJAUT *ALL then GRTOBJAUT *CHANGE) so the batch can add/update but not delete.

UTBLINL / UTAGELF — Logical files

UTBLINL is an LF over UTBLIN keyed by BILLNO — the subfile source for UTBILLIQ and the detail source for UTBILLPR. UTAGELF is an LF over UTBILL keyed by DUEDT (record UTAGER, exposing BILLNO/SPNO/DUEDT/CHARGE/BSTAT/BILLBAL) — the aging pass read by UTDELINQ, UTFEECAL and UTAGE via SETLL *LOVAL / forward READ.

UTGLF — GL posting feed (DB2 table)

Relationships

• UTCUST 1—N UTSVCPT (UTSVCPT.CUSTNO → UTCUST.CUSTNO).
• UTSVCPT 1—N UTREAD / UTBILL / UTCASH / UTLEDG (all carry SPNO); UTSVCPT.METERNO → UTMETER.
• UTBILL 1—N UTBLIN (BILLNO); UTBLINL and UTAGELF are LF views of UTBLIN / UTBILL.
• UTSVCPT.RATECD → UTRATE (N tiers per class, keyed RATECD+TIERNO).
• UTGLF is an aggregate GL feed (no per-row FK; grouped by BATCHID/ACCT/DRCR).

E. Operations Runbook ↑ top

E.1 Day-in-the-life

1. Confirm the build is in place (one-time, or after a rebuild): CALL AQUILA/UTSETUP creates every object, wires journaling and the ledger authority, and seeds the rate plan (DSPLY AQUILA setup complete. Rate plan loaded.).
2. Maintain masters as needed through UTMNT (customers CC/CI, meters MC/MI).
3. Load the day's meter reads into UTREAD (journaled) — in the test harness a small RPG loader writes them; in production this is the meter-read import.
4. Run the night-batch chain (C.2) as sequenced SBMJOBs on AQUILA/NITEQ: BILLGEN → CASH POST → DELINQUENCY → FEE → GL POST → bill print.
5. Handle online inquiries through CALL AQUILA/UTMENU as they arrive.
6. When disconnected accounts pay up, run UTRECON to reconnect them.

Pre-checks: confirm the library list includes AQUILA; confirm the rate plan is present (UTRATE has 7 tiers); confirm each SBMJOB reached status = OUTQ before starting the next.

Post-checks per step (each program DSPLYs a one-line result):

• UTBLGEN GENERATED=n SKIPPED=n REJECTED=n — generated matches the new reads; SKIPPED counts already-billed/missing-SP reads; REJECTED counts oversized-charge data-quality rejects (should be 0 for clean data).
• UTCSHPST FULL=n PART=n NOBILL=n — NOBILL counts receipts with no matching open bill; investigate any non-zero NOBILL.
• UTDELINQ FLAGGED=n and UTFEECAL ASSESSED=n TOTFEE=n reconcile to the set of unpaid open bills.
• UTGLPST IN BALANCE … COMMITTED — a ROLLBACK line means the batch did not balance and nothing posted.
• UTBILLPR PRINTED=n equals the number of bills; the UTBILLP spool shows each bill title, total and tier prices.

E.2 The billing run & close

1. Ensure the day's reads are loaded and BILLGEN/CASH/DELINQUENCY/FEE have all run to OUTQ.
2. Run UTGLPST exactly once for the close. Confirm the joblog shows IN BALANCE … COMMITTED.
3. Run the COBOL cross-check: CALL AQUILA/UTGLRPT. Confirm CROSS-CHECK: IN BALANCE.
4. Review the GL feed and the aged-AR report.

-- GL control total (should balance and be non-zero)
SELECT COALESCE(SUM(CASE WHEN DRCR='D' THEN AMT ELSE 0 END),0),
       COALESCE(SUM(CASE WHEN DRCR='C' THEN AMT ELSE 0 END),0) FROM AQUILA.UTGLF;
-- A/R debit = billed charges + fees
SELECT COALESCE(SUM(AMT),0) FROM AQUILA.UTGLF WHERE ACCT='120000' AND DRCR='D';

Reconciling figures (the same ones the focused suites check):

• Billed charges — e.g. ELE 184.50 + WAT 29.00 + GAS 114.75 = 328.25; this is the Revenue credit (400000) and the billing A/R debit (120000).
• Fees — late fee + interest per delinquent bill (e.g. 7.77 + 5.32 = 13.09) is the Fee Revenue credit (410000) and adds to the A/R debit.
• A/R debit = billed charges + fees (e.g. 205.50 + 13.09 = 218.59) — the UTGLRPT cross-check target.
• Balance — SUM(DR) = SUM(CR) across the batch, or UTGLPST rolls back.

Aged-AR: CALL AQUILA/UTAGE DSPLYs UTAGE BILLS=n TOTBAL=n OPEN=n DLQ=n for a quick open-vs-delinquent split.

E.3 Failure & re-run rules

Each program DSPLYs its result; the night chain sequences steps as separate SBMJOBs so a failed step can be re-submitted alone.

F. Developer Reference ↑ top

The complete program surface, from src/sources.mjs. All objects are in library AQUILA. RPG source is authored as column-exact fixed-form C/D-specs (helpers C()/D()/Ccond()) mixed with /free blocks; some programs are totally-free-form (**FREE).

F.1 Programs & languages

UTRATLD — RPG (fixed F-spec + /free)

Seeds the 7-tier rate plan into UTRATE (ELE×3, WAT×2, GAS×2), each top tier carrying the sentinel 999999999 upper bound and BASECHG on tier 1.

UTMNT — RPG (callable, dcl-pi *ENTRY)

Customer/meter create/change/inquire (CC/MC/CI/MI). Full-key CHAIN, validate-before-write, re-CHAIN before each UPDATE; reports via pOutFound/pOutMsg.

UTBLGEN — RPG (fixed C-specs + /free)

The tiered billing engine (F.2). Two-phase: compute-and-validate in wide working storage, then persist only a validated bill (no torn write).

UTCSHPST — RPG

Cash posting; forward-READ over UTBILL to find the oldest open bill per SPNO, partial (D) vs full (P), roll SPBAL down, ledger 'P'.

UTDELINQ — RPG

Aging pass over UTAGELF; flags bill/SP/customer delinquent, ledger 'A'. (Honest note: no grace period; per-bill — see C.2.)

UTFEECAL — RPG (packed-decimal calc)

Flat $5.00 + 1.50% interest on delinquent bills, wide-packed multiply then half-up to cents; per-bill 'F'-row idempotency guard; ledger 'F'.

UTRECON — RPG (two passes)

Pass 1 reconnects paid-up disconnected SPs; pass 2 restores a customer only if no other SP of theirs is still disconnected; ledger 'R'.

UTGLPST — SQLRPGLE (**FREE, commitment control)

Embedded-SQL SUM/INSERT into UTGLF; three balanced DR/CR pairs; COMMIT/ROLLBACK on the balance check.

UTBILLPR — RPG (PRTF)

Bill print over UTBILL + UTBLINL to the UTBILLP spool.

UTAGE — RPG

Aged-AR bucket report over UTAGELF.

UTACCTIQ / UTBILLIQ / UTMENU — RPG WORKSTN

Account inquiry (plain), bill inquiry (SFL/SFLCTL subfile), operator menu (indicator-conditioned fixed-form dynamic CALL to the two inquiries).

UTGLRPT — ILE COBOL

Indexed FD over UTBILL (zoned fields PIC S9(n), packed COMP-3); totals charges, adds ledger fees via embedded SQL, cross-checks the UTGLF A/R debit, prints IN BALANCE/OUT OF BALANCE.

UTSETUP / UTNIGHT — CL

Build/journal/authority/seed; night-batch chain documentation.

F.2 The tiered-billing algorithm (UTBLGEN)

For a read's usage U under rate class R, walk UTRATE tiers in TIERNO order (full composite-key CHAIN(E) on RATECD:TIERNO):

1. Band width for tier t = TIERUB - prior TIERUB.
2. Usage billed in the tier = MIN(remaining, band); line amount = usage × UNITPRC.
3. On tier 1 add BASECHG; the sentinel-topped last tier absorbs any remaining usage.
4. CHARGE = BASECHG + Σ(tier amounts).

Two-phase, torn-write-safe. Phase 1 computes the whole bill in wide 11P2 accumulators, writing nothing; if the computed charge (or any single tier amount) exceeds what the persistable 9P2 fields can hold, the read is rejected cleanly. Phase 2 runs only for a validated bill, re-walking the tiers deterministically to write the UTBLIN lines, then the UTBILL header, the SPBAL roll-up and the ledger 'B' row — so a detail line is never written for a read whose header would later fail. Packed math spans 9P0/7P4/9P2/11P2 widths.

F.3 Ledger key bands & idempotency

UTLEDG is a UNIQUE-keyed PF on LEDGSEQ (not a bare arrival file): a keyed WRITE appends, so the ledger accumulates across the whole night into a durable trail. Every posting program assigns LEDGSEQ from a disjoint numeric band so keys never collide:

The three high-water-mark programs (UTRECON/UTFEECAL/UTDELINQ) forward-scan their own band with a full-key SETLL to find the current max key before assigning, so a second run in the same business day that adds ≥1 new row does not restart at 0 and collide (which would raise SNX1021 duplicate-key). This is what makes those steps safely re-runnable.

F.4 Platform accommodations (honest)

Documented in the source and PLAN.md; operationally the app behaves as described, but these are the real reasons certain names and idioms look the way they do:

• USAGE field renamed. A DDS field literally named USAGE breaks the RPG→COBOL compile bridge (USAGE is COBOL-reserved), so meter consumption is RUSAGE and bill usage is BUSAGE.
• Full-key CHAIN, not partial-key SETLL/READE. Keyed access uses the full composite key (e.g. RATECD:TIERNO) via the CHAIN retry loop, avoiding a partial-key access quirk on unique files.
• Separate SBMJOBs for the night chain. Rows written to an output-opened file may be invisible to a called subprogram until close, so each batch step is its own job (not one CL calling several posting programs in-process).
• Re-CHAIN before every UPDATE. Every maintenance/posting UPDATE re-CHAINs the full key immediately before writing, so a stale read is never double-updated.
• UNIQUE-keyed output PFs. The ledger and masters are UNIQUE-keyed so writes route through the keyed append path (avoiding an arrival-PF double-write regression and an output-open truncation that would otherwise leave only the last program's rows).
• Fixed-form LEAVESR; no free-form elseif. The subroutine exit is a fixed-form C … LEAVESR and option routing uses nested if/else/endif, both to sidestep known free-form lowering quirks.
• PRTF position digits end at DDS col 44; COBOL FD zoned = PIC S9(n), packed = COMP-3. The bill PRTF and the COBOL report obey these layout rules.
• DSPJRN single-paren FILE(). Filter journal entries with FILE(AQUILA/UTLEDG), not the double-paren list form.
• Ledger authority = *CHANGE. *PUBLIC gets *CHANGE (read+add+update), the authority the batch posting path actually needs, as a deliberate restriction.

G. Glossary ↑ top

Arrival file

A physical file read in the order rows were added (via SETLL *START / forward READ). Here UTREAD and UTCASH are read in arrival order for their one-pass batch programs (they are UNIQUE-keyed for the write path but read sequentially).

Base charge (BASECHG)

The fixed monthly service charge for a rate class, added on tier 1 of a bill regardless of usage.

BILLNO scheme

A bill's key = 'B' + last 7 digits of (READID + 10000000), making it deterministic per read (READID 1001 → B0001001) so re-running the billing engine never duplicates a bill.

Commitment control

The transaction scope under which UTGLPST posts to UTGLF; it COMMITs only if the batch balances, else ROLLBACK. Honored on the SQL path, so GL posting is done entirely in embedded SQL.

Delinquency bucket / aging

Classifying open bills by their due date. UTAGELF keys UTBILL by DUEDT for the aging pass; UTAGE splits balances into open vs delinquent.

Disconnect / reconnect

Setting a service point SPSTAT='D' when its bill is delinquent (UTDELINQ) and back to 'A' once paid up (UTRECON) — the signature utility service-lifecycle arc.

Idempotent

Safe to run again with the same result. UTBLGEN and UTFEECAL are idempotent within a pass; the high-water-mark posting steps are re-run safe on the ledger key; UTGLPST is not (it re-posts cumulative totals).

Journaling

Recording before/after images of file changes to a journal receiver. UTREAD and UTLEDG are journaled with IMAGES(*BOTH) to UTJRN/UTRCV, inspectable with DSPJRN/WRKJRNA.

Ledger (UTLEDG) / LTYPE

The immutable A/R audit trail. LTYPE tags the event: B bill, P payment, A adjustment (delinquency), F fee, R reconnect.

LEDGSEQ band

The disjoint numeric range each posting program draws its ledger key from (F.3), so keys never collide across the night.

Packed decimal (nP d)

A compact numeric storage format (two digits per byte). AQUILA's billing and fee math uses wide packed accumulators (up to 15P4) so multiplies never overflow before rounding to cents.

PRTF / spool

A printer file and the spooled output it produces. UTBILLP is the bill printer file; UTBILLPR writes the spool.

Rate class / tier (UTRATE)

A utility's stepped price schedule (ELE/WAT/GAS), keyed by RATECD + TIERNO; each tier has an upper bound and a unit price, with the top tier sentinel-topped to absorb the rest.

SBMJOB / *JOBQ

Submit Job to a job queue — how the night-batch steps are sequenced so each program closes its files before the next opens them.

Service point (UTSVCPT)

A metered point of service for a customer under one utility type and rate class, carrying its own status and running balance.

Subfile (SFL/SFLCTL)

A 5250 construct listing many rows on one screen. UTBILLIQ's BSFL lists a bill's tier lines under control record BCTL.

Tiered (stepped) billing

Billing each band of usage at its own unit price (F.2), plus a base charge, rather than a single flat rate.