MEDCLAIM/i — Healthcare Claims Administration

SteelFrame X application operation manual · ← back to Operation Manuals · Sign On

MEDCLAIM/i is a healthcare benefit-adjudication application: it takes provider claims in, edits and eligibility-checks them, then adjudicates each one against the member's live benefit accumulator (deductible-met and out-of-pocket-met year-to-date), pays providers weekly, and closes the books monthly and annually. The spine of the system is the accumulator: because adjudication reads it, applies benefits against it, and writes it back, every claim pays differently because of the claims that came before it. The benefit maths and the invariant plan liability + member responsibility = allowed live in the RPG adjudication engine; the CL job cycles orchestrate the programs. This manual is grounded entirely in the committed source of library MEDCLAIM (claims-app/src/sources.mjs, src/seed.mjs, and the test/hc_*.mjs drivers), and is honest where the application deliberately lacks a feature the domain might imply.

Contents

A. Overview & architecture A.1 What it does A.2 The accumulator & the benefit maths A.3 Component & flow A.4 Object inventory B. Online transactions & screens B.1 The command/entry line B.2 The menu & inquiry screens B.3 Controls & audit workflow C. Batch jobs & the periodic cycle C.1 Full batch program set C.2 Daily / weekly / monthly / annual detail C.3 Ordering & dependencies D. Data files (data dictionary) E. Operations runbook E.1 Day-in-the-life E.2 Month-end & year-end close E.3 Failure & re-run rules F. Developer reference F.1 The adjudication algorithm F.2 Program reference F.3 Re-runnability & the ledger F.4 Denial / pend / status codes F.5 Known honest limitations G. Glossary

A. Overview & Architecture ↑ top

A.1 What it does

MEDCLAIM/i administers the full life of a healthcare benefit claim:

Intake & eligibility — structurally edit each newly entered claim (service lines present, lines roll up to the header, a valid service date), then test it against member coverage and provider network status, denying with a reason code where it fails.
Adjudication — price the claim at the network contract rate, apply the member's deductible first, split the remainder by co-insurance, cap the member at the out-of-pocket maximum, update the accumulator, and distribute the header amounts down to the service lines — holding the invariant plan + member = allowed exactly.
Provider payment — weekly, group adjudicated claims by provider, write one remittance payment per provider, stamp the claims paid, and print the remittance advice; claims needing a human decision go on the pended worklist.
Monthly close — post the claims-expense GL distribution, report the medical loss ratio, and accrue IBNR (incurred-but-not-reported) by completion factor.
Annual roll — summarise the closing year, reset every member's accumulator to zero for the new plan year (auditing the closing position first), and re-enrol continuing members.

A.2 The accumulator & the benefit maths

Adjudication of a single claim follows a fixed pipeline, all in program HCADJUD:

  allowed         = billed × provider contract rate      (network pricing, PVRATE)
  deductible part = min(allowed, plan deductible − deductible met)   -> member pays whole
  remainder       = allowed − deductible part
  plan share      = remainder × plan coinsurance rate    (PCOINS; POONCOI out-of-net)
  member share    = remainder − plan share
  member resp     = deductible part + member share
                    then CAPPED so (out-of-pocket met + member resp) never
                    exceeds the plan out-of-pocket maximum; the excess -> plan
  INVARIANT       plan liability + member responsibility = allowed, ALWAYS

The accumulator (HCACCUM, one row per MEMBID, ACCYR) is what makes this stateful: adjudication reads the member's DEDMET / OOPMET, applies benefits against them, and writes them back, so the next claim for that member in that plan year pays differently. The worked example the tests assert (GOLD plan, deductible 500.00, 80/20 co-insurance, OOP max 2000.00, in-network rate 1.0000):

CLM000001 billed 800.00, deductible met 0.00:
  allowed 800.00; deductible min(800,500)=500.00 (member); remainder 300.00
  plan 300×0.80=240.00; member 500+60=560.00;  240+560=800  INVARIANT OK
  accumulator now: deductible met 500.00, out-of-pocket met 560.00
CLM000002 billed 1000.00 (same member, deductible now met):
  deductible 0.00; plan 1000×0.80=800.00; member 200.00; accum OOP met 760.00
CLM000003 billed 8000.00 (OOP cap bites):
  member capped at 2000−760=1240.00; plan takes the rest 6760.00 (not 6400.00)

A.3 Component & flow

  DAILY  (HCDAILY)        WEEKLY (HCWEEK)         MONTHLY (HCMONTH)
  --------------          --------------          -----------------
  HCINTAKE  edit          HCPEND    worklist      HCGLDST  GL distribution
  HCELIG    eligibility   HCPAYRUN  provider pay  HCLOSSR  loss ratio
  HCADJUD   ADJUDICATE    HCREMIT   remittance    HCIBNR   IBNR accrual
     |                       |                     HCACCRP  accum audit (COBOL)
     v                       v
  HCACCUM  <---read/write--  HCCLM / HCCLML       ANNUAL (HCYEAR)
  (member accumulator)       (claim hdr + lines)  -----------------
     |                          |                 HCYRSUM  year summary
     +--> HCLEDG  <-- every posting program       HCYRRST  accumulator reset
          (durable, re-runnable audit ledger)     HCREENR  re-enrolment sweep

  ONLINE   HCMENU (5250) --1--> HCMEMBIQ  member benefit inquiry
                          --2--> HCCLMIQ   claim inquiry (service-line subfile)

A daily event flows: a claim entered as CSTAT='E' → HCINTAKE validates it to 'V' (or denies to 'D') → HCELIG tests coverage/network → HCADJUD prices it, applies benefits against HCACCUM, writes the header and service-line amounts, and lays down the durable HCLEDG row that makes the claim un-repeatable. Everything runs in library MEDCLAIM.

A.4 Object inventory

Object	Type	Role
HCMEMB	PF	Member / subscriber enrolment master.
HCPLAN	PF	Benefit plan (deductible, co-insurance, OOP max).
HCPROV	PF	Provider network master (contract rate).
HCCLM	PF	Claim header (the workflow spine).
HCCLML	PF	Claim service lines (composite CLMNO,CLINE).
HCACCUM	PF	Member accumulator (composite MEMBID,ACCYR) — the heart.
HCPAY	PF	Provider payment / remittance header.
HCLEDG	PF	Durable adjudication / accounting ledger (re-run guard).
HCAPPL	PF	Denial appeal tracking.
HCWORK	PF	Pended-claim worklist.
HCCLMLF	LF	Claims keyed by MEMBID (member access path).
HCCLMLP	LF	Claim lines keyed by PROVID (provider access path).
HCGLDIST	SQL table	Claims-expense GL distribution (+ index HCGLDACC).
HCMEMBD / HCCLMD / HCMENUD	DSPF	Member inquiry / claim subfile / main menu.
HCREMP	PRTF	Provider remittance advice printer file.
HC* (17)	RPG / SQLRPGLE	Seed, intake, eligibility, adjudication, pend, pay, remit, GL, loss-ratio, IBNR, reset, re-enrol, appeal, summary, 2 inquiries, menu.
HCACCRP	ILE COBOL	Accumulator audit report.
HCSETUP	CL	Create every object & compile every program.
HCDAILY / HCWEEK / HCMONTH / HCYEAR	CL	The four job cycles.

The full catalogue is 10 PFs + 2 LFs + 1 SQL table (with index), 4 DSPF/PRTF members, 17 RPG/SQLRPGLE programs + 1 ILE COBOL program, driven by 5 CL programs. Sections D and F expand each.

B. Online Transactions & Screens ↑ top

B.1 The command/entry line

MEDCLAIM/i has no CICS transaction identifiers and no transid switch. On IBM i, each program is reached by name from a 5250 command-entry line (or a JOBQ/scheduler for the batch cycles). Before invoking anything, the job's library list must include MEDCLAIM — the tested jobs run with LIBL = QSYS QGPL MEDCLAIM QTEMP and CURLIB = MEDCLAIM. Each CL cycle begins with its own ADDLIBLE LIB(MEDCLAIM).

To do this	Type on the command line
Open the operator main menu	`CALL MEDCLAIM/HCMENU`
Member benefit inquiry directly	`CALL MEDCLAIM/HCMEMBIQ`
Claim inquiry (service-line subfile) directly	`CALL MEDCLAIM/HCCLMIQ`
Build/compile the whole application	`CALL MEDCLAIM/HCSETUP` then `CALL MEDCLAIM/HCREFLD`
Run the daily adjudication cycle	`CALL MEDCLAIM/HCDAILY` (or `SBMJOB` it)
Run the weekly payment cycle	`CALL MEDCLAIM/HCWEEK`
Run the monthly close	`CALL MEDCLAIM/HCMONTH`
Run the annual plan-year roll	`CALL MEDCLAIM/HCYEAR`

The batch programs take no CALL parameters. Unlike a control-row application, MEDCLAIM/i's processing dates, batch numbers and plan year are compile-time literals inside the programs (e.g. HCPEND/HCPAYRUN use run 202631, HCGLDST batch 202608, HCIBNR/HCYRRST plan year 2026/2027). A scheduled submission is therefore a bare CALL; changing the processing period is a source change, not a data change. Only HCMENU, HCMEMBIQ and HCCLMIQ are interactive.

Honest note on claim entry: there is no online claim-capture screen in this application. Claims arrive as rows written directly into HCCLM/HCCLML (in the emulator, by the test drivers) with CSTAT='E'; the online programs are read-only inquiries. MEDCLAIM/i is a claims adjudication system, not a data-entry front end.

B.2 The menu & inquiry screens

HCMENU (HCMENUD). A plain menu: option 1 CALLs HCMEMBIQ, option 2 CALLs HCCLMIQ, any other non-blank option shows Invalid option.; F3 ends the program. Control returns to the menu when a called inquiry exits.

MEDCLAIM/i Main Menu 1. Member Benefit Inquiry 2. Claim Inquiry Option . . . . : _ F3=Exit Enter=Select

HCMEMBIQ (HCMEMBD) is a plain (non-subfile) member benefit inquiry. Key a member id and Enter; it CHAINs HCMEMB, the member's plan (HCPLAN) and the member's plan-year accumulator (HCACCUM, key MEMBID, 2026), and renders the enrolment plus the live derived position — deductible remaining and out-of-pocket remaining are computed on the screen (PDEDUCT−DEDMET, floored at 0), not stored. An unknown member shows Member not found. and clears the detail.

Member Benefit Inquiry - MEDCLAIM/i Member id: MB0000001 Name . . . . . : ALDEN R HOLLOWAY Plan . . . . . : PLAN0001 Status . . . . : A Deductible . . : 500.00 Ded met . . . : 500.00 Ded remaining : 0.00 OOP maximum . : 2,000.00 OOP met . . . : 760.00 OOP remaining : 1,240.00 F3=Exit Enter=Inquire

HCCLMIQ (HCCLMD) is the app's subfile screen. The DDS record LSFL under control record LCTL pages the claim's service lines (SFLPAG(5), SFLSIZ(20), ROLLUP/ROLLDOWN). Key a claim number and Enter: it renders the header (member, billed, allowed, plan paid, member, status) and loads one subfile row per adjudicated service line. The load order is deliberate — the subfile is cleared, then loaded for the key just typed, then displayed — so an inquiry that finds nothing never shows the previous claim's lines underneath.

Claim Inquiry - MEDCLAIM/i Claim number: CLM000001 Member . . . . : MB0000001 Billed . . . . : 800.00 Allowed . : 800.00 Plan paid . . : 240.00 Member . . : 560.00 Status . . . . : A Lin Svc Billed Allowed Plan pd Member 1 99214 600.00 600.00 180.00 420.00 2 81002 200.00 200.00 60.00 140.00 F3=Exit Roll=Page Enter=Inquire

Screen fields of note

Field	Screen	Shows
IMEMB / ICLM	HCMEMBD / HCCLMD	The keyed member id / claim number (input/output).
DDREM / DOREM	HCMEMBD	Deductible / out-of-pocket remaining, derived live, floored at 0.
DCPLAN / DCMEMR	HCCLMD	Claim header plan paid / member responsibility.
SLINE..SMEMB	HCCLMD (LSFL)	Subfile line: number, service code, billed, allowed, plan pd, member.
DMSG	all	Highlighted status line (found / not found / invalid option).

Both inquiry programs use amounts pre-formatted with the RPG %editc(...:'K') edit code into alphanumeric display fields (e.g. 1,240.00). The subfile line amounts are the service-line values HCADJUD distributed pro rata from the header; on a two-line claim the two rows correctly carry different amounts, with the last line absorbing the rounding residue.

B.3 Controls & audit workflow (no four-eyes maker–checker)

Honest statement: MEDCLAIM/i does not model a true four-eyes maker–checker / separate-authorization workflow. No batch program requires a second user to approve what a first user posted: HCADJUD adjudicates, HCPAYRUN pays, and the annual reset runs, each in one flow. The control model the application does have is enforced structurally:

The pended worklist (HCWORK) is the human gate. HCPEND lifts out of the straight- through flow any claim that needs a person: high-dollar plan liability over 5000.00 (P1), out-of-network needing an authorisation check (P2), denied on an eligibility reason a human can override (P3), or a suspected duplicate (P4). This is a review queue, not an approval gate — a pended claim is not blocked from the payment run by the worklist alone.
The durable ledger (HCLEDG) is the accountability trail. Every adjudication, every provider remittance, every IBNR accrual and every year-end accumulator close writes a ledger row with a stable, business-derived key. It is both the audit record and the re-run guard (section F.3).
Status gating. Business rules gate what each program touches by CSTAT: HCINTAKE only edits 'E' claims, HCELIG and HCADJUD only 'V', HCPAYRUN only pays 'A' (adjudicated) claims and stamps them 'X'. A claim cannot skip a stage.
The appeal path (HCAPPL). A filed appeal is resolved by HCAPPEAL: a D3 denial (service date outside coverage — often a retroactive enrolment) is overturned and the claim pushed back to 'V' for re-adjudication; everything else is upheld. This is the review-and-correct loop.
The accumulator audit (HCACCRP, COBOL). An independent read-only report of every member's deductible-met / out-of-pocket-met / paid-YTD and the plan-wide totals — the figure an actuarial team reconciles the engine against.

In sum, the control posture is a human worklist + status/state gating + a durable audit ledger + an independent audit report, all enforced in the data and program layer, rather than a segregation-of-duties approval workflow.

C. Batch Jobs & the Periodic Cycle ↑ top

MEDCLAIM/i runs as four periodic cycles, each a CL program that CALLs its member programs in order: a daily cycle (intake → eligibility → adjudication), a weekly cycle (worklist → provider payment → remittance), a monthly cycle (GL → loss ratio → IBNR → accum audit) and an annual cycle (year summary → accumulator reset → re-enrolment). All member programs take no CALL parameters; their dates/periods are compile-time literals. The scheduled idiom is a bare SBMJOB of the cycle:

-- submit a (parameterless) cycle as a batch job
SBMJOB CMD(CALL PGM(MEDCLAIM/HCDAILY)) JOB(HCDAILY)
-- or run a single member program directly
CALL MEDCLAIM/HCADJUD

C.1 Full batch program set

Program	Cycle	Purpose	Reads	Writes / DSPLY
HCREFLD	setup	Seed plans, providers, members, opening accumulators.	—	HCPLAN(2) HCPROV(4) HCMEMB(4) HCACCUM(4); `PLANS=2 PROVS=4 MEMBERS=4 ACCUMS=4`.
HCINTAKE	daily 1	Structural edit of entered claims.	HCCLM, HCCLML	CSTAT E→V or E→D (E1/E2/E3); `VALID=/REJECT=/SKIP=`.
HCELIG	daily 2	Member coverage + provider network check.	HCCLM, HCMEMB, HCPROV	CSTAT V→D (D1..D5); `PASS=/DENY=/SKIP=`.
HCADJUD	daily 3	THE adjudication engine (deductible, co-ins, OOP cap, line split).	HCCLM, HCCLML, HCMEMB, HCPLAN, HCPROV, HCACCUM	Claim & line amounts, HCACCUM update, HCLEDG 'J' row; `ADJUDICATED=/SKIP=`.
HCPEND	weekly 1	Build the pended-claim worklist.	HCCLM, HCCLMLF, HCPROV	HCWORK rows (P1..P4); `PENDED=/SKIP=`.
HCPAYRUN	weekly 2	Provider payment run (group plan liability by provider).	HCPROV, HCCLM	HCPAY per provider, CSTAT A→X, HCLEDG 'Y' row; `PAYMENTS=/TOTAL=/SKIP=`.
HCREMIT	weekly 3	Print the provider remittance advice (EOB).	HCPAY, HCPROV, HCCLM	HCREMP spool; `CLAIMS=/TOTAL=`.
HCGLDST	monthly 1	Balanced claims-expense GL distribution (embedded SQL).	HCCLM, HCGLDIST	HCGLDIST DR/CR pairs; `BATCH=/ROWS=/INCURRED=`.
HCLOSSR	monthly 2	Medical loss ratio (incurred / earned premium).	HCMEMB, HCCLM	`MEMBERS=/PREMIUM=/INCURRED=/MEMBRESP=/RATIO=`.
HCIBNR	monthly 3	IBNR accrual by completion factor 0.8000.	HCCLM, HCLEDG	HCLEDG 'B' row; `REPORTED=/ULTIMATE=/ACCRUAL=/CLAIMS=`.
HCACCRP	monthly 4	Accumulator audit report (ILE COBOL).	HCACCUM	`DEDMET/OOPMET/PAIDYTD/ACCUMS` totals.
HCYRSUM	annual 1	Year-end claims summary (read-only).	HCCLM	`CLAIMS=/PAID=/DENIED=/BILLED=/ALLOWED=/PLAN=/MEMBER=`.
HCYRRST	annual 2	Accumulator reset: close 2026, open 2027 at zero.	HCACCUM, HCLEDG	HCLEDG 'Z' close row, new-year HCACCUM row; `RESET=/SKIP=`.
HCREENR	annual 3	Roll continuing members into the new plan year.	HCMEMB	MEFFDT/MTRMDT rolled; `RENEWED=/LAPSED=/SKIP=`.
HCAPPEAL	ad hoc	Resolve filed appeals (overturn D3, push back to V).	HCAPPL, HCCLM	ASTAT F→O/U, CSTAT D→V on overturn; `OVERTURNED=/UPHELD=/SKIP=`.

C.2 Daily / weekly / monthly / annual detail

Daily — HCDAILY (HCINTAKE → HCELIG → HCADJUD)

HCINTAKE edits every CSTAT='E' claim: no service lines → E1, line billed total ≠ header billed → E2, missing/impossible service date → E3; clean claims go to 'V'. HCELIG then tests each 'V' claim: member not found D1, coverage terminated D2, service date outside the member's MEFFDT..MTRMDT window D3, provider not found D4, provider not active D5. HCADJUD adjudicates each surviving 'V' claim per section A.2 / F.1.

Expected DSPLY (the 6-claim oracle set: 4 adjudicate, 1 denied E2, 1 denied elig):
  HCINTAKE VALID=5 REJECT=1 SKIP=0     CLM000006 fails E2 (400 hdr vs 250 lines)
  HCELIG   PASS=4 DENY=1 SKIP=1        CLM000005 denied (terminated member D2/D3)
  HCADJUD  ADJUDICATED=4 SKIP=2

Weekly — HCWEEK (HCPEND → HCPAYRUN → HCREMIT)

HCPEND builds the worklist (P1..P4). HCPAYRUN sweeps providers, totals each provider's adjudicated ('A') plan liability, writes one HCPAY remittance, stamps those claims 'X' with the payment number, and lays a HCLEDG 'Y' row. HCREMIT prints the remittance advice (one provider block, one detail line per claim).

Expected DSPLY (cycles oracle):
  HCPEND    PENDED=1 SKIP=...          one P1: plan liability 16000.00 > 5000.00
  HCPAYRUN  PAYMENTS=3 TOTAL=18200     only plan liability is remitted, not member resp
  HCREMIT   CLAIMS=4 TOTAL=18200.00

Only the plan's liability (CPLANPD) is remitted to providers; the member responsibility (CMEMRSP, 5800.00 in the oracle) is what the provider collects from the member and is deliberately not in the payment run.

Monthly — HCMONTH (HCGLDST → HCLOSSR → HCIBNR → HCACCRP)

HCGLDST posts balanced DR/CR pairs into the SQL HCGLDIST table for the movement since the last close: DR 6100-MEDCLM / CR 2100-CLMPAY (incurred), DR 2100-CLMPAY / CR 1010-CASH (remitted), and a memo member-receivable pair. HCLOSSR reports the medical loss ratio = incurred plan liability / earned premium, where premium is active members × 450.00 PMPM (the enrolment file carries no premium — this is a claims system, so the rate is a program literal). HCIBNR accrues incurred-but-not-reported by completion factor: ultimate = reported / 0.8000, accrual = ultimate − reported. HCACCRP (COBOL) audits the accumulator totals.

Expected DSPLY (cycles oracle):
  HCLOSSR  MEMBERS=3 PREMIUM=1350.00   3 active members × 450.00
  HCLOSSR  INCURRED=18200.00 MEMBRESP=5800.00
  HCLOSSR  RATIO=13.4814               18200 / 1350, truncated into 7P4
  HCIBNR   REPORTED=18200.00 ULTIMATE=22750.00
  HCIBNR   ACCRUAL=4550.00             22750 − 18200

Annual — HCYEAR (HCYRSUM → HCYRRST → HCREENR)

HCYRSUM reports the year's disposition (read-only). HCYRRST writes each member's closing 2026 accumulator to HCLEDG ('Z') then opens a fresh 2027 accumulator at zero. HCREENR rolls each active member's MEFFDT/MTRMDT to the 2027 window; a genuinely terminated (MSTAT='T') member is left to lapse; a member already carrying 2027 dates is skipped.

C.3 Ordering & dependencies

Within the daily cycle the order is fixed and mandatory: intake sets 'V' that eligibility consumes; eligibility narrows the 'V' set that adjudication consumes. Running adjudication before intake/eligibility would adjudicate un-edited, un-checked claims.
DAILY before WEEKLY. Only HCADJUD sets CSTAT='A' and the plan liability the payment run groups; the pended-worklist reasons (P1 high-dollar, P2 out-of-network) also key off adjudicated amounts. Adjudicate before you pay.
WEEKLY before MONTHLY. HCPAYRUN flips paid claims to 'X'; the GL distribution's cash-settlement leg keys off 'X', and the loss ratio / IBNR read the incurred plan liability. Pay before you close the month.
MONTHLY before ANNUAL. The accumulator reset (HCYRRST) wipes the year's position; run every month's close and the year summary first.
Appeals feed back to daily. An overturned appeal returns a claim to 'V', so the next daily HCADJUD re-adjudicates it.

D. Data Files (data dictionary) ↑ top

All files are in library MEDCLAIM, grounded in the DDS/SQL in claims-app/src/sources.mjs. Dates are stored as 8S 0 in YYYYMMDD form (accumulator/plan year as 4S 0 YYYY); rates are packed 5P 4 (0.8000 = 80%); money is packed 11P 2 (or 13P 2 for GL totals). Every physical file is UNIQUE-keyed.

HCMEMB — Member / subscriber enrolment (K MEMBID)

Field	Type	Meaning
MEMBID	9A	Member id (K) — the enrolment spine, e.g. `MB0000001`.
MNAME	30A	Member name.
MPLAN	8A	Benefit plan id (→ HCPLAN).
MSUBID	9A	Subscriber id (a dependent points at its subscriber).
MREL	1A	S subscriber, D dependent.
MEFFDT / MTRMDT	8S 0	Coverage effective / termination dates — the eligibility window.
MSTAT	1A	A active, T terminated, P pending re-enrolment.
MGROUP	6A	Employer / group id.

HCPLAN — Benefit plan (K PLANID)

Field	Type	Meaning
PLANID	8A	Plan id (K).
PLDESC	30A	Plan description.
PDEDUCT	11P 2	Annual individual deductible the member pays first.
PCOINS	5P 4	Plan's share of the post-deductible remainder (in-network).
POOPMAX	11P 2	Out-of-pocket maximum — caps total member liability.
PCOPAY	11P 2	Flat per-visit copay (carried; not applied by HCADJUD).
POONCOI	5P 4	Plan's lower coinsurance rate for out-of-network care.
PLSTAT	1A	A active.

Seeded plans: PLAN0001 GOLD 500/80/2000 (OON 0.6000, copay 25.00); PLAN0002 SILVER 1000/70/4000 (OON 0.5000, copay 40.00).

HCPROV — Provider network (K PROVID)

Field	Type	Meaning
PROVID	9A	Provider id (K).
PVNAME	30A	Provider name.
PVNET	1A	I in-network, O out-of-network (drives which coinsurance rate applies).
PVRATE	5P 4	Contracted rate: `allowed = billed × PVRATE`.
PVSPEC	3A	Specialty (benefit category).
PVSTAT	1A	A active, T terminated (a claim against T denies D5).
PVTIN	9A	Tax id.

HCCLM — Claim header (K CLMNO)

Field	Type	Meaning
CLMNO	9A	Claim number (K), e.g. `CLM000001`.
MEMBID / PROVID	9A	Owning member / billing provider.
CSVCDT / CRCVDT	8S 0	Service date / received date.
CBILLED	11P 2	What the provider charged.
CALLOWD	11P 2	Network-allowed amount (set by HCADJUD).
CDEDAPP	11P 2	Deductible applied on this claim.
CPLANPD	11P 2	Plan liability.
CMEMRSP	11P 2	Member responsibility (`CPLANPD+CMEMRSP=CALLOWD`).
CSTAT	1A	E entered, V validated, A adjudicated, X paid, D denied, P pended.
CDENCD	2A	Denial reason code (E1..E3 / D1..D5).
CPLANYR	4S 0	Plan year (selects the accumulator).
CPAYNO	9A	Remittance payment number once paid.

HCCLML — Claim service lines (K CLMNO, CLINE)

Field	Type	Meaning
CLMNO / CLINE	9A / 3S 0	Claim + line number (composite K).
LSVCCD	5A	Procedure / service code.
LUNITS	5P 2	Quantity billed.
LBILLED	11P 2	Line billed amount (rolls up to CBILLED).
LALLOWD / LPLANPD / LMEMRSP	11P 2	Line allowed / plan / member, pro-rated from the header by HCADJUD.
LSTAT	1A	A adjudicated.
PROVID	9A	Billing provider (basis of HCCLMLP).

HCACCUM — Member accumulator (K MEMBID, ACCYR)

Field	Type	Meaning
MEMBID / ACCYR	9A / 4S 0	Member + plan year (composite K).
DEDMET	11P 2	Deductible satisfied year-to-date.
OOPMET	11P 2	Out-of-pocket spent year-to-date.
ACLMCNT	5P 0	Claims adjudicated against this accumulator.
APAIDYTD	11P 2	Plan liability paid year-to-date for this member.
ASTAT	1A	A active.

Seeded: one row per member for 2026, all at zero. The composite key means every guard against it uses an RPG KLIST.

HCPAY — Provider payment / remittance header (K PAYNO)

Field	Type	Meaning
PAYNO	9A	Payment number (K), `PY` + provider digits.
PROVID	9A	Provider paid.
PAYRUN	6S 0	Payment-run number.
PAYAMT	11P 2	Total plan liability remitted.
PAYCNT	5P 0	Claims covered.
PAYDT	8S 0	Payment date.
PAYSTAT	1A	I issued.

HCLEDG — Adjudication / accounting ledger (K LSEQ)

Field	Type	Meaning
LSEQ	8S 0	Sequence (K) — DISJOINT numeric range per program (see F.3); the re-run guard.
LTYPE	1A	J adjudication, Y remittance, G GL, B IBNR, Z year-end.
LKEY	9A	Business key (member / provider / etc.).
LDT	8S 0	Posting date.
LAMT / LAMT2	11P 2	Primary / secondary amount (e.g. plan paid / member resp; IBNR accrual / reported base).
LREF	9A	Reference (claim / payment / 'ACCRUAL').
LMEMO	30A	Free-text memo.

HCAPPL — Appeal tracking (K APPLNO)

Field	Type	Meaning
APPLNO	9A	Appeal number (K).
CLMNO / MEMBID	9A	Appealed claim / member.
ADENCD	2A	The denial code being appealed.
AFILEDT / ARESLDT	8S 0	Filed / resolved dates.
ASTAT	1A	F filed, U upheld, O overturned.
AREASON	30A	Appeal reason.

HCWORK — Pended-claim worklist (K WKSEQ)

Field	Type	Meaning
WKSEQ	8S 0	Worklist sequence (K), derived from the claim (idempotent).
CLMNO	9A	Pended claim.
WKRUN	6S 0	Run number.
WKRSN	2A	Pend reason P1..P4 (see F.4).
WKAMT	11P 2	Amount at issue.
WKSTAT	1A	O open.
WKMEMO	30A	Memo.

HCGLDIST — Claims-expense GL distribution (SQL table, PK GDSEQ)

Columns GDSEQ, GDBATCH, GDACCT, GDDRCR, GDAMT, GDCAT, GDREF, GDDT. Written by HCGLDST as balanced DR/CR pairs; index HCGLDACC on (GDACCT, GDDRCR). Accounts used: 6100-MEDCLM, 2100-CLMPAY, 1010-CASH, 1210-MBRREC, 4100-MBROFF.

HCCLMLF / HCCLMLP — Alternate access paths

HCCLMLF (over HCCLM) keys claims by MEMBID for member-history and duplicate-suspicion walks; HCCLMLP (over HCCLML) keys service lines by PROVID for the provider payment/remittance walk. Both are non-unique by design.

Relationships

HCCLM.MEMBID → HCMEMB.MEMBID; HCCLM.PROVID → HCPROV.PROVID.
HCMEMB.MPLAN → HCPLAN.PLANID; HCADJUD reads the plan for the member.
HCCLML.(CLMNO,CLINE) roll up to HCCLM header amounts.
HCACCUM keyed (MEMBID, ACCYR); HCADJUD selects it by CLMNO's owning member and CPLANYR.
HCPAY.PROVID → HCPROV; HCCLM.CPAYNO → HCPAY.PAYNO once paid.
HCAPPL.CLMNO → HCCLM; HCWORK.CLMNO → HCCLM; HCLEDG rows reference each posting's business key.

E. Operations Runbook ↑ top

E.1 Day-in-the-life

Confirm the job's library list includes MEDCLAIM (each CL cycle also ADDLIBLEs it).
Submit the daily cycle: SBMJOB CMD(CALL PGM(MEDCLAIM/HCDAILY)).
Post-check the three DSPLY lines (intake / eligibility / adjudication) — see below.
Handle inquiries interactively through CALL MEDCLAIM/HCMENU (option 1 member benefit, option 2 claim / service-line subfile).
On the weekly day, submit HCWEEK; review the pended worklist (HCWORK) and the remittance total; spool the remittance advice.
Resolve any filed appeals with CALL MEDCLAIM/HCAPPEAL; overturned claims return to 'V' and adjudicate on the next daily run.

Post-checks after the daily cycle (against the 6-claim oracle in test/hc_daily.mjs):

HCINTAKE VALID=/REJECT= reconcile to the entered claims; a line/header mismatch shows as E2 (e.g. header 400.00 vs lines 250.00).
HCELIG PASS=/DENY=: a terminated member or a service date outside coverage is denied; a denied claim carries no allowed amount and no plan liability.
HCADJUD ADJUDICATED=: for every adjudicated claim, CPLANPD + CMEMRSP = CALLOWD exactly, and the accumulator's DEDMET/OOPMET advanced.

E.2 Month-end & year-end close

Confirm the month's dailies and weeklies have run (claims adjudicated and paid).
Submit HCMONTH. Confirm the GL ROWS=/INCURRED=, the loss ratio and the IBNR accrual DSPLYs, and the HCACCRP accumulator totals.
At year end, submit HCYEAR: confirm the summary, that every 2026 accumulator was closed to HCLEDG ('Z') and reset to a zero 2027 row, and re-enrolment renewed continuing members (terminated members lapse).

Reconciling figures (the same ones the cycles simulation checks against an independent JS oracle, test/hc_cycles.mjs):

Provider remittance — per provider, SUM(CPLANPD) over its 'A' claims; grand total = SUM over all remittances (oracle: 18200.00 over 4 claims, 3 payments).
Member responsibility is excluded from remittance — the 5800.00 of CMEMRSP is not in the payment run.
Loss ratio — incurred plan liability / (active members × 450.00 PMPM), e.g. 18200.00 / 1350.00 = 13.4814 (truncated into the 7P4 field).
IBNR — reported / 0.8000 = ultimate; accrual = ultimate − reported, e.g. 18200.00 / 0.80 = 22750.00, accrual 4550.00.
Ledger reconciliation — the adjudication ('J') and remittance ('Y') ledger rows tie out; HCACCRP's accumulator totals reconcile to the adjudicated claims.

E.3 Failure & re-run rules

Every posting program is re-runnable by design: the durable ledger key is derived from a stable business key (section F.3), and each program CHAINs that key with (EN) before it posts, so a re-run finds the existing row and skips (SKIP= counts it) rather than double-posting.

Situation	Behaviour	Action
Daily cycle re-run	Adjudicated claims have their HCLEDG 'J' row; HCADJUD CHAINs it and LEAVESRs.	Safe. Deductible is never applied twice, out-of-pocket never double-counted, accumulator not corrupted.
Weekly payment re-run	Each provider's HCLEDG 'Y' row is found; HCPAYRUN skips it.	Safe. RE-RUN PROOF: still exactly the same remittances/total, `PAYMENTS=0` on the re-run. A provider is never paid twice.
Pended worklist re-run	Worklist key is claim-derived; the existing HCWORK row is found.	Safe no-op — the claim is not re-pended.
IBNR / year-end reset re-run	Plan-year / per-member ledger key already present.	Safe. A second accumulator reset would wipe the new year — the guard is the strictest in the app and blocks it.
Appeal already resolved	Only `ASTAT='F'` appeals are touched.	Safe no-op on re-run.
GL distribution re-run	See F.5 — the SQL insert is refused on a duplicate GDSEQ, and the row is only counted when `SQLCOD=0`.	Re-run posts only the movement since the last close; watch the honest cross-month limitation in F.5.

Because every adjudication, remittance, accrual and year-end close writes a durable HCLEDG row (and the GL distribution writes balanced pairs), any cycle's effect is reconstructable after the fact for reconciliation and recovery.

F. Developer Reference ↑ top

All programs are in library MEDCLAIM, source in claims-app/src/sources.mjs. The RPG is fixed-form C-specs with /free blocks; the fixed-form/free-form mix in the inquiry and adjudication programs is deliberate (see the in-source comments).

F.1 The adjudication algorithm (HCADJUD)

Per validated claim, in claim-number order:

Re-run guard — compute WLSEQ = 10000000 + claim digits; CHAIN(EN) HCLEDG; if present, skip (already adjudicated).
Price — CHAIN provider; WALLOW = CBILLED × PVRATE. Missing provider/ member/plan → skip.
Plan & rate — CHAIN member → plan; WCOINS = PCOINS, or POONCOI when the provider is out-of-network (PVNET='O').
Accumulator — CHAIN HCACCUM by KLIST (MEMBID, ACCYR); read DEDMET/OOPMET (0 if absent).
Deductible first — WDAPP = clamp(PDEDUCT − DEDMET, 0, WALLOW), all the member's.
Co-insurance — WREM = WALLOW − WDAPP; WPLAN = WREM × WCOINS; member share = WREM − WPLAN; WMRSP = share + WDAPP.
OOP cap — WOOPRM = max(POOPMAX − OOPMET, 0); if WMRSP > WOOPRM, WMRSP = WOOPRM. Then the invariant: WPLAN = WALLOW − WMRSP.
Accumulator write-back — re-CHAIN (the earlier CHAINs moved the cursor); DEDMET += WDAPP, OOPMET += WMRSP, ACLMCNT += 1, APAIDYTD += WPLAN; UPDATE (or WRITE a new row).
Ledger row — write the 'J' HCLEDG row (LAMT plan, LAMT2 member) — the un-repeatable marker.
Line distribution — two passes over the lines: count lines/find the last, then allocate each line's allowed/plan/member pro rata by billed share, the last line absorbing the rounding residue so the lines sum to the header exactly. Each line is re-CHAINed by its composite KLIST (CLMNO, CLINE) before UPDATE (a partial key would match line 1 every time).
Header stamp — CALLOWD/CDEDAPP/CPLANPD/CMEMRSP set, CSTAT='A'.

F.2 Program reference

HCREFLD — reference-data seeder: Writes 2 plans, 4 providers (3 active, 1 terminated; in- and out-of-network), 4 members (subscriber/dependent), and 4 opening 2026 accumulators at zero.
HCINTAKE — intake edit (daily 1): Only CSTAT='E'; validates lines-present / lines=header / valid date; sets 'V' or 'D' (E1/E2/E3). Re-CHAINs the header after the service-line READEs.
HCELIG — eligibility (daily 2): Only 'V'; CHAINs member then provider; D1..D5. Re-CHAINs the claim after the member/ provider CHAINs.
HCADJUD — adjudication (daily 3): Section F.1. The program the application exists for.
HCPEND — worklist (weekly 1): P1 plan liability > 5000.00; P2 out-of-network overriding a P1; P3 reviewable eligibility denial (D2/D3/D5); P4 suspected duplicate (same member/provider/service date/billed via HCCLMLF walk). Idempotent on the claim-derived WKSEQ.
HCPAYRUN — provider payment (weekly 2): Totals each provider's 'A' plan liability, writes one HCPAY, stamps claims 'X'/CPAYNO, HCLEDG 'Y'. Guarded by 30000000 + provider digits.
HCREMIT — remittance advice (weekly 3): PRTF with page overflow (OFLIND(*IN90)); one provider block, one detail line per claim, billed/allowed/plan/member.
HCGLDST — GL distribution (monthly 1, SQLRPGLE): Embedded free-form SQL; balanced DR/CR pairs for the movement since the last close. See F.5.
HCLOSSR — loss ratio (monthly 2): Incurred plan liability / (active members × 450.00 PMPM), 7P4 ratio.
HCIBNR — IBNR accrual (monthly 3): Ultimate = reported / 0.8000; accrual = ultimate − reported; HCLEDG 'B' guarded by 70000000 + plan year.
HCACCRP — accumulator audit (monthly 4, ILE COBOL): Sequential sweep of HCACCUM on its composite RECORD KEY (a 13-byte group of MEMBID+ACCYR), totalling DEDMET/OOPMET/PAIDYTD and the accumulator count.
HCYRSUM / HCYRRST / HCREENR — annual: Read-only year summary; accumulator reset (close 2026 to HCLEDG 'Z', open 2027 at zero, guarded by 90000000 + member digits); member re-enrolment sweep to the 2027 window.
HCAPPEAL — appeals: Only ASTAT='F'; a D3 denial is overturned (claim → 'V', CDENCD cleared), all else upheld.
HCMEMBIQ / HCCLMIQ / HCMENU — online: Member benefit inquiry (derived remaining figures); claim service-line subfile; menu router.

F.3 Re-runnability & the ledger

HCLEDG.LSEQ carries a disjoint numeric range per program, and each key is derived from a stable business key so a re-run recomputes the same key, the CHAIN(EN) guard finds the existing row, and the program refuses rather than double-posting:

Program	LTYPE	LSEQ formula
HCADJUD	J	10000000 + claim digits
HCPEND	(HCWORK)	20000000 + claim digits (worklist WKSEQ)
HCPAYRUN	Y	30000000 + provider digits
HCGLDST	G	continues from MAX(GDSEQ) ≥ 50000000 (see F.5)
HCIBNR	B	70000000 + plan year
HCYRRST	Z	90000000 + member digits

F.4 Denial / pend / status codes

Code	Set by	Meaning
E1 / E2 / E3	HCINTAKE	No service lines / line-header billed mismatch / missing-impossible service date.
D1 / D2 / D3	HCELIG	Member not found / coverage terminated / service date outside coverage window.
D4 / D5	HCELIG	Provider not found / provider not active.
P1 / P2 / P3 / P4	HCPEND	High-dollar plan liability / out-of-network auth / reviewable eligibility denial / suspected duplicate.
CSTAT	workflow	E entered, V validated, A adjudicated, X paid, D denied, P pended.
ASTAT	HCAPPEAL	F filed, U upheld, O overturned.

F.5 Known honest limitations

No online claim capture. Claims enter as file rows (CSTAT='E'); the online programs are read-only inquiries (section B.1).
Processing periods are compile-time literals, not a control row: run numbers, batch numbers and plan year live in the program source. Changing the period is a source change.
PCOPAY is carried but not applied. HCADJUD implements deductible + co-insurance + OOP cap; the flat per-visit copay field is stored on the plan but not used in the maths.
HCGLDST cross-month tracking — documented in the source. The program re-totals the whole adjudication ledger every run and derives GDSEQ by continuing from MAX(GDSEQ); on a duplicate primary key the SQL insert is refused, and the code correctly counts a row only when SQLCOD=0. The in-source comment is candid that an earlier version derived GDSEQ from a per-run counter that restarted at zero, so month 2 rebuilt month 1's keys and the distribution silently stopped tracking the ledger while still printing a growing incurred total. The committed program posts only the movement since the last close and checks SQLCOD; operators should still reconcile the GL ROWS= against the expected DR/CR pairs each month.
Duplicate detection is a pend, not a block. There is no duplicate detection in adjudication; a suspected duplicate is P4-pended for a human, because a legitimate same-day repeat service does happen.

G. Glossary ↑ top

Accumulator (HCACCUM): The per-member, per-plan-year record of deductible-met and out-of-pocket-met. Read, applied against, and written back by every adjudication, so a claim's payment depends on every claim before it.
Adjudication: Applying plan benefits to a priced claim: deductible first, then co-insurance on the remainder, capped by the out-of-pocket maximum (HCADJUD).
Allowed amount: What the network contract permits: billed × provider rate (PVRATE). Plan liability and member responsibility always sum to it.
Co-insurance: The plan's percentage share of the post-deductible remainder (PCOINS in-network, POONCOI out-of-network); the member pays the rest.
Completion factor: The fraction of a period's eventual claims already reported. IBNR uses 0.8000: ultimate = reported / 0.80.
Deductible: The annual amount a member pays in full before the plan shares cost (PDEDUCT), tracked in the accumulator's DEDMET.
EOB / remittance advice: The explanation of benefits printed to the provider (HCREMIT / HCREMP): billed, allowed, plan paid, member responsibility per claim.
IBNR — Incurred But Not Reported: An accrual for claims that exist but have not yet arrived, by completion factor (HCIBNR).
Idempotent / re-runnable: Safe to run again with the same result. Every MEDCLAIM/i posting program guards a stable HCLEDG key with CHAIN(EN), so a re-run skips rather than double-posts.
Medical loss ratio: Incurred claims / earned premium (HCLOSSR), premium derived at 450.00 PMPM per active member.
Out-of-pocket maximum (OOP max): The plan-year ceiling on total member liability (POOPMAX); once reached, the plan takes the rest. Tracked in the accumulator's OOPMET.
PMPM: Per-member-per-month — the premium rate the loss-ratio program uses (a program literal here).
Pended claim: A claim lifted onto the human worklist (HCWORK) rather than paid or denied straight through (reasons P1..P4).
Subfile: A 5250 display construct listing many rows (DDS SFL/SFLCTL). HCCLMIQ's service-line list is a subfile (SFLPAG 5 / SFLSIZ 20).