CVTFREE-APP — RPG Fixed→Free Conversion Corpus

CVTFREE-APP is not a business application — it is a modernization corpus: a set of realistic, hand-written fixed-form RPG IV programs (an order-processing mini-app — ORDCALC, ORDVAL, ORDPOST, ORDRPT) that are mechanically converted to fully-free RPG by the CVTRPGFREE tool and then proven equivalent by a compile-both-and-diff oracle. Its purpose is to exercise the SteelFrame X conversion surface (ibmi/cvtfree.js) against source written the way a real shop writes it — column-exact C/D/F specs, KLIST/KFLD, CASxx, DIV+MVR, half-adjust arithmetic, date-duration math, string BIFs — and to confirm the tool's honest refusals on the constructs that cannot be expressed in free form. This manual documents it as what it is: a fixed→free conversion reference. It is grounded entirely in the committed source (cvtfree-app/run_corpus.mjs — the corpus, conversion driver and oracle in one file — and the engine surface it drives, ibmi/cvtfree.js).

A. Overview & Architecture ↑ top

A.1 What cvtfree modernization is

CVTRPGFREE is a source-to-source modernization step: it reads a program written in classic column-exact fixed-form RPG (the format where factor-1, opcode, factor-2 and the result field each live in fixed card columns) and rewrites it into fully-free RPG (the modern, column-independent syntax with dcl-s, dcl-pi, eval, structured for/dow, and ;-terminated statements). It is the SteelFrame X analogue of IBM's own fixed-to-free conversion: the same program, the same behaviour, expressed in the maintainable modern form.

CVTFREE-APP exists to answer one question rigorously: does the conversion preserve behaviour? A synthetic snippet can hide corner cases; this corpus instead uses a realistic order-processing mini-app — the kind of program a shop actually ships — so the conversion is stressed across the opcode families that matter: half-adjust arithmetic, DIV+MVR remainder pairing, MOVE/MOVEL padding semantics, the string BIFs (CAT/SUBST/XLATE/SCAN/CHECK), array LOOKUP, keyed I/O via KLIST/KFLD, CASxx dispatch, DO loops, date-duration math, TESTN, and TIME. It equally documents where the tool must refuse — GOTO/TAG, program-described O/I specs, cycle/level indicators — because free RPG cannot express them, and a silent mis-conversion there would be far worse than an honest stop.

A.2 The compile-both-and-diff oracle: proof by execution

The corpus does not trust the converter's output by inspection. Every program is validated by an emulator-as-oracle loop — the SteelFrame X emulator itself is the reference implementation, and the two source forms must produce byte-identical results when actually run:

• 1. COMPILE + RUN the original fixed-form. CRTBNDRPG the fixed-form member, call it, capture its DSPLY output (and, for file-writing programs, the after-image of the physical file).
• 2. CONVERT. Drive the real CVTRPGFREE CL command (the workbench path, not a direct function call) to produce a fully-free member.
• 3. COMPILE + RUN the converted free-form. CRTBNDRPG the converted member, call it, capture the same outputs.
• 4. DIFF. Compare the two runs' DSPLY lines (and file after-images) byte for byte. Equivalence holds only if they are identical.

On top of the diff, several checks assert hand-computed expected values (e.g. the next order number, a delinquency-tier LOOKUP result, the exact MOVEL vs MOVE overlay bytes), so the oracle proves not just "the two agree" but "the two agree and the answer is the mathematically correct one". Where a program is non-deterministic (the TIME wall-clock read in ORDRPT) or self-referential (the file-appending ORDPOST), the harness masks the volatile field or re-seeds identical file state between the two runs, so the comparison stays fair.

A.3 Component & flow

  FIXED-FORM SOURCE          CONVERT                 FREE-FORM SOURCE
  -----------------          -------                 ----------------
  ORDLIB/QRPGLESRC(ORDCALC)  CVTRPGFREE  --------->  ORDLIB/QRPGLESRC(ORDCALCF)
  ORDLIB/QRPGLESRC(ORDVAL)     SRCMBR -> TOMBR       ORDLIB/QRPGLESRC(ORDVALF)
  ORDLIB/QRPGLESRC(ORDPOST)    (ibmi/cvtfree.js      ORDLIB/QRPGLESRC(ORDPOSTF)
  ORDLIB/QRPGLESRC(ORDRPT)      convert())           ORDLIB/QRPGLESRC(ORDRPTF)
         |                                                   |
         | CRTBNDRPG + CALL                 CRTBNDRPG + CALL |
         v                                                   v
     fixed DSPLY  ----------  DIFF (byte-for-byte)  ----  free DSPLY
     file after-image  <-----  must be identical  ----->  file after-image
                                    |
                                    v
                          ok(name, cond) -> PASS/FAIL  (17 checks, +findings)

  REFUSAL SET (must NOT convert): GOTO/TAG, program-described O-spec, L1 cycle indicator
  DATA: ORDLIB/OCUSTP (customer master, keyed) + ORDLIB/OORDP (order detail, 2-part key)

A single check flows: the driver emits the fixed-form member as an array of column-exact lines → put() writes it to QRPGLESRC (guarding the 112-byte record length) → oracle() runs CVTRPGFREE, compiles both members, calls both, and returns both outputs → same() / a hand-computed assertion decides PASS or FAIL → the result is pushed and printed. When a real conversion defect surfaces, it is written up in LANG-QA-FINDINGS.md as a numbered finding.

A.4 Object inventory

The corpus is 4 realistic programs (+ their converted twins) over 2 keyed DDS files, plus a handful of minimal probe programs, driven by 1 Node file that both emits the fixed-form source and verifies the conversion. Sections D and F expand each.

B. "Online" — How It Is Run ↑ top

B.1 The conversion driver (there is no screen)

Honest statement: CVTFREE-APP has no 5250 screen, no menu, and no interactive transaction. It is a source-transform corpus. The "operator experience" is running one Node command:

-- run the whole conversion + equivalence corpus
node cvtfree-app/run_corpus.mjs

That single command boots a fresh SteelFrame X object filesystem in a private scratch root (cvtfree-app/.data-corpus, created and wiped at start), initialises the emulator's object store, jobs, VSAM/PF layer and SQL engine, starts one job (CVTAPPQA under QPGMR), then walks the corpus. Everything it does is what a developer would otherwise type at a workbench: create a library and source files, key in the fixed-form members, issue CVTRPGFREE, compile with CRTBNDRPG, and CALL the programs. The driver simply scripts that developer session and adds the diff.

B.2 The CVTRPGFREE command

Conversion is driven through the real CL command so the corpus exercises the workbench path, not just a bare call to cvt.convert(). The command shape used throughout is:

CVTRPGFREE SRCFILE(lib/QRPGLESRC) SRCMBR(ORDCALC) TOMBR(ORDCALCF)
CVTRPGFREE SRCFILE(lib/QRPGLESRC) SRCMBR(QAGOTO) TOMBR(QAGOTOF) TODO(*YES)

The command returns a result object the driver inspects: converted (boolean), lines (the emitted free-form source) and todos (the reasons a conversion was refused or flagged). A clean conversion is converted === true with an empty todos; a refusal is converted === false with one or more todos[].reason strings. Under the covers the command reads the member and calls ibmi/cvtfree.js's convert(source, opts).

B.3 The self-check report (the "screen" you actually watch)

What an operator watches is not a green screen but the driver's PASS/FAIL scoreboard on stdout. Each check calls ok(name, cond, detail), printing PASS or **FAIL and a short detail; at the end it prints the tally and exits non-zero if any check failed.

The two logged findings (P0.1, P0.2) are expected-failure repros: they PASS when the known conversion defect still reproduces (the corpus routes around each so the rest can proceed) and would only "fail" if the underlying engine bug were fixed — see F.4.

C. Batch — the Conversion + Equivalence Run ↑ top

The corpus is the "batch job". A run is a single deterministic pass (the volatile TIME field is masked, so a re-run gives the same scoreboard). It proceeds in a fixed order: the environment is built once, then each program is emitted, converted, compiled twice, run twice and diffed, then the three refusals are asserted. All work happens in library ORDLIB.

C.1 The corpus build & run sequence

1. Boot the emulator. Wipe/create the scratch data root, init objfs, jobs, VSAM, the runtime build, and SQL; start job CVTAPPQA.
2. Create the environment. CRTLIB ORDLIB, the two source PFs (QRPGLESRC/QDDSSRC at RCDLEN(112)), and the two keyed data files (OCUSTP, OORDP) from DDS; seed three customers.
3. Probe CVTFREE-QA-01 (P0.1) — the SUBST-of-a-literal repro, run first so the rest of the corpus can be written to route around it.
4. Program 1 — ORDCALC (P1.0–P1.2): convert, compile both, assert the *ENTRY PLIST→dcl-pi synthesis. Run indirectly via ORDPOST.
5. Program 2 — ORDVAL (P2.0–P2.1): convert + run + diff for a valid order and a bad-input order.
6. Probe CVTFREE-QA-02 (P0.2) — the long-continuation-line over-RCDLEN repro.
7. Program 3 — ORDPOST (P3.0–P3.2): convert + run + diff DSPLY and the keyed file after-image, with identical re-seeding between the two runs.
8. Program 4 — ORDRPT (P4.0–P4.1): convert + run + diff, with TIME masked.
9. Program 5 — refusals (P5.0–P5.4): assert GOTO/TAG, program-described O-spec, and L1 cycle indicator all refuse, and that the CL command honours TODO(*NO) (writes nothing) vs TODO(*YES) (writes with markers).
10. Append findings & tally. Any confirmed defect is appended to LANG-QA-FINDINGS.md; print cvtfree-app corpus: N/total and exit 0 only if all passed.

C.2 Per-program equivalence checks

C.3 Ordering & dependencies

• Environment before everything. The library, source PFs and data files must exist and be seeded before any member is emitted or converted.
• QA probes before the programs they inform. CVTFREE-QA-01 runs before ORDCALC (which stages a literal into the WKOVL work field to sidestep it); CVTFREE-QA-02 runs before ORDPOST (which splits its status memo into several short EVALs to sidestep it).
• ORDCALC before ORDPOST. ORDCALC is a called module with no DSPLY of its own; its real equivalence exercise is through ORDPOST's CALL+PARM to it, so ORDCALC must be converted and compiled first.
• ORDPOST needs re-seeding, not back-to-back runs. ORDPOST reads OORDP to compute the next order number and then writes a row, so it is not idempotent. The oracle clears and re-seeds the file to the same two-order baseline before each of the two runs, or the free run would see the fixed run's extra row and diverge.
• Within a program the sequence is fixed: convert → compile fixed → compile free → run fixed → run free → diff.

D. Data Files (the corpus DDS) ↑ top

The corpus uses two DDS-described keyed physical files in ORDLIB, grounded in the DDS members emitted into QDDSSRC. They exist to give ORDPOST real keyed I/O (CHAIN, SETLL/READE, WRITE) and ORDRPT a real full-file scan to convert — not to model an order-management business. Both are declared UNIQUE. Money fields are packed decimal; the order number is zoned.

OCUSTP — Customer master (record OCUSTR; key CUSTNO, UNIQUE)

Seeded rows: ('C0001','ACME CORP',50000.00), ('C0002','GLOBEX LLC',15000.00), ('C0003','INITECH',2000.00).

OORDP — Order detail (record OORDR; 2-part key CUSTNO+ORDNO, UNIQUE)

Seeded before each ORDPOST run: ('C0002',1,'2026-01-05',300.00,'P') and ('C0002',2,'2026-02-10',450.00,'P') — the two-order baseline the next-number logic must see identically on both the fixed and free run.

How the corpus programs use these files

• ORDPOST / OCUSTP — a full-key CHAIN via KLIST CKEY/KFLD WCUST to look up the customer name (indicator 90 = not found).
• ORDPOST / OORDP — a partial-key forward scan (SETLL then READE looping while *IN92 = *OFF) via KLIST PKEY/KFLD WCUST2 to find the highest existing order number, then +1 and a WRITE OORDR of the new row.
• ORDRPT / OCUSTP — a plain SETLL *LOVAL + READ/DOWEQ *OFF full-file scan, counting rows and totalling CREDLIM.

E. Operations Runbook ↑ top

E.1 Running the corpus

1. From the repository root, run the driver: node cvtfree-app/run_corpus.mjs.
2. No parameters, no setup: the driver creates and wipes its own scratch data root (cvtfree-app/.data-corpus) each run, so it is fully self-contained and repeatable.
3. Watch the stdout scoreboard — one PASS/**FAIL line per check — and the final cvtfree-app corpus: N/total tally.
4. The process exits 0 only if every check passed; a non-zero exit means at least one check failed (a CI gate can key on that).

Pre-checks: run from a checkout where ibmi/cvtfree.js, ibmi/compile.js, server/runtimebuild.js etc. are present (the driver imports them by relative path from its own directory); a Node with ESM support.

E.2 The 17/17 verification — what a healthy run asserts

A healthy run is 17 of 17 checks green (the ok() guard for an unexpected exception is the 18th call and stays dormant on a clean run). The 17 are:

E.3 Failure & findings

Because this is a QA corpus, a "failure" is a signal about the converter (or, for P0.x, a signal that a known bug has changed), never about a business transaction.

F. Developer Reference ↑ top

The complete corpus surface, from cvtfree-app/run_corpus.mjs. Every fixed-form program is built from column-exact line builders (cC for C-specs, cX for extended-factor-2 continuations, dS/dDS/dSub for D-specs) so the source lands in the exact card columns the parser expects. All objects live in library ORDLIB.

F.1 The corpus programs

ORDCALC — order-economics callee (*ENTRY PLIST, no DSPLY)

A called module taking 10 parameters (4 in: amount, qty, pack, ISO date; 6 out: tax, discount, whole cases, leftover units, due date, memo). Computes tax as amount × 0.0825 half-adjusted; a discount tier via CASGE (≥10000→10%, ≥1000→5%, else 0%); cases and remainder via DIV+MVR; an XFOOT over a 3-element line-item array with MOVEA staging; a due date via ADDDUR 30:*D with EXTRCT *M; and a formatted memo via CAT/SUBST/XLATE. Verified indirectly through ORDPOST's CALL. Note: its SUBST overlay reads from the WKOVL work field (INZ 'XX-YY-ZZ'), not a literal — a deliberate route around CVTFREE-QA-01.

ORDVAL — order-edit validation (two data cases: ORDVAL, ORDVALB)

Classic "edit a line" program: TESTN digit-classifies the order-number field (resulting indicators 60/61/62); two COMP range checks (negative amount, over-limit); a CASGT/CAS dispatch to HASERR/NOERR subroutines; SCAN/CHECK/CHECKR over a free-text description; and a CAT building the summary line. ERRCNT is staged into a char field via MOVE before the CAT (a %char() inline in a fixed CAT operand is refused by the base compiler itself — the idiomatic fixed-form pattern). ORDVAL runs the valid path (→OK 0); ORDVALB runs the all-blank/negative path (→ERRORS FOUND 2).

ORDPOST — order posting (keyed I/O, the fullest program)

Against the two keyed files: a full-key CHAIN on OCUSTP (KLIST CKEY/KFLD WCUST); a partial-key forward scan on OORDP (SETLL+READE looping *IN92=*OFF, KLIST PKEY/KFLD WCUST2) to find the max order number; a LOOKUP on an ASCEND compile-time array (TIERC = H/L/M via **CTDATA) with nearest-high; a DO 1..3 loop building a running total; a CALL 'ORDCALC' with 10 PARMs; and a WRITE OORDR. Its status memo is built across eight short EVALs (not one long continuation) — a deliberate route around CVTFREE-QA-02.

ORDRPT — customer report (MOVE/MOVEL padding, TIME)

Read-only full-file scan (SETLL *LOVAL+READ/DOWEQ *OFF) over OCUSTP, counting rows and totalling CREDLIM. Demonstrates MOVE/MOVEL faithful padding: MOVEL 'XY' into '123456' left-overlays to XY3456; MOVE 'XY' into 'AB' right-overlays (unpadded) to AB  XY. Uses TIME (6,0) for a run timestamp (masked in the diff) and CAT for header/footer.

F.2 Opcode families demonstrated as convertible

These are the fixed-form idioms the corpus proves CVTRPGFREE converts correctly (fixed and free runs byte-identical), with the program that exercises each:

F.3 Honest-refusal boundaries

Some fixed-form constructs have no faithful free-form equivalent. The correct behaviour there is to refuse loudly (return converted:false with a todos[].reason), never to emit silently-wrong free source. The corpus asserts each refusal with a minimal program:

GOTO / TAG (P5.0)

Fully-free RPG has no GOTO and no TAG label; arbitrary jumps cannot be re-expressed as structured control flow mechanically. The converter reports a GOTO reason and refuses. (GOTO/TAG are among the converter's TODO_OPS — the opcodes it will not silently translate.)

Program-described O-spec / I-spec (P5.1)

A program-described printer file with O-specs (column-positioned output fields, e.g. QSYSPRT O F 132 PRINTER + O field lines) is not expressible in free-form, which requires externally-described (DDS) files for record I/O. The converter refuses with an "O-spec" reason.

Level / cycle indicators (P5.2)

An RPG-cycle level indicator such as L1 in a C-spec's conditioning columns depends on the program cycle, which fully-free RPG does not run. The converter refuses with a "level/SR indicator" reason.

The write policy that makes refusal safe: by default (TODO(*NO)) a refused conversion writes nothing — P5.3 asserts the destination member does not even exist after a refused run. With TODO(*YES) (P5.4) the tool writes the best-effort free source but annotates every unconvertible statement with a // TODO(CVTFREE) <reason>: <original> comment, so a human can finish the conversion by hand and can never mistake a partial result for a complete one.

F.4 The two logged findings

Building the corpus surfaced two real conversion defects, each reproduced twice (standalone probe + a corpus program that hit it independently), then routed around so the equivalence coverage could proceed. Both are logged to LANG-QA-FINDINGS.md.

CVTFREE-QA-01 — SUBST of a quoted literal converts to an uncompilable %subst-of-a-literal

A fixed-form SUBST 'XX-YY-ZZ':1 TGT converts to %subst(TGT:1:5) = %subst('XX-YY-ZZ':1:5);, which the free-form RPG-to-COBOL backend cannot compile (it emits a reference-modification subscript on a quoted-literal MOVE source, a syntax error). Severity: high (a silently-uncompilable program from an extremely common template-overlay idiom). Confirmed twice. The shared root cause is in the RPG-to-COBOL backend's %subst-of- a-literal codegen (outside cvtfree.js), but the converter is what walks a user into it — it has no reason to route a literal source through %subst() at all. Corpus workaround: ORDCALC stages the literal into the WKOVL work field and SUBSTs from that field.

CVTFREE-QA-02 — a long continuation statement converts to one unwrapped free line over RCDLEN

A legal multi-line extended-factor-2 statement (each physical line well under 112) converts to a single free-form line longer than the destination member's record length. Writing it back silently truncates at 112 bytes — often mid string-literal — corrupting the converted program. Severity: high (silent truncation → fails to compile, or worse, silently wrong). Confirmed twice. The write-side truncation in objfs.writeSource() is correct behaviour for a physical source member; the gap is cvtfree.js not re-wrapping its own long output (or at least warning) to fit. Corpus workaround: ORDPOST builds its status memo across eight short EVALs instead of one long continuation.

F.5 The oracle helpers (how a check is built)

put(lib, file, mbr, srctype, lines)

Writes a source member, but first fails loudly if any line exceeds RCDLEN(112) — an own-code guard so a too-long line is caught here, not as a mysterious downstream compile error (the lesson behind CVTFREE-QA-02).

oracle(lib, srcMbr, newMbr, {skipRun})

The equivalence engine: runs the real CVTRPGFREE CL command (SRCMBR→TOMBR); if refused, returns an err with the join of todos[].reason; otherwise CRTBNDRPGs both members, calls both, and returns {fixedOut, newOut}. skipRun converts+returns without running (used for the no-DSPLY ORDCALC).

same(o) / line1(o)

same is the pass predicate — no error, non-empty fixed output, and JSON.stringify(fixedOut) === JSON.stringify(newOut). line1 formats both outputs (or the error) for the check's detail string.

ok(name, cond, detail)

Records and prints one check ( PASS/**FAIL), truncating detail to 160 chars; the final tally and exit code are driven off the collected results.

logFinding(id, title, body)

Collects a numbered finding; all findings are appended to LANG-QA-FINDINGS.md at the end of the run under a header comment.

G. Glossary ↑ top

Fixed-form RPG

Classic column-exact RPG IV, where factor-1, opcode, factor-2 and the result field each occupy fixed card columns (the format the corpus programs are written in, and the input to conversion).

Fully-free RPG

Modern column-independent RPG syntax (dcl-s, dcl-pi, eval, for/dow, ;-terminated statements) — the conversion target.

CVTRPGFREE

The CL command that converts a fixed-form source member (SRCMBR) to a fully-free member (TOMBR); driven throughout this corpus. Backed by ibmi/cvtfree.js's convert().

Conversion corpus

A curated set of realistic programs used to exercise and validate a converter — here, an order-processing mini-app used purely as conversion test material, not as an operable system.

Compile-both-and-diff oracle

The validation method: compile and run BOTH the fixed and converted forms, then diff their outputs (and file after-images) byte-for-byte. The emulator itself is the reference implementation.

Equivalence

The property being proved: the converted program produces byte-identical results to the original when actually run.

Honest refusal

The converter declining (converted:false + a reason) on a construct with no faithful free-form equivalent, rather than emitting silently-wrong source. Applies to GOTO/TAG, program-described O/I specs, and cycle/level indicators.

TODO(CVTFREE)

The comment marker the converter leaves on each unconvertible statement when TODO(*YES) forces a best-effort write, so a human can finish the conversion by hand.

Half-adjust

RPG rounding (the (H) extender, e.g. MULT(H)): round the result to its declared decimal positions rather than truncate.

DIV + MVR

The fixed-form idiom for integer division with remainder: DIV produces the quotient, MVR immediately after retrieves the remainder.

KLIST / KFLD

A named composite key list (KLIST) and its constituent key fields (KFLD) used for keyed file operations like CHAIN/SETLL/READE.

MOVE / MOVEL

Right-adjusted (MOVE) and left-adjusted (MOVEL) character overlay with faithful unpadded semantics — a converter must preserve exactly which bytes are overwritten.

RCDLEN

The record length of a source physical file (here 112, the classic QRPGLESRC default). A converted line longer than RCDLEN is silently truncated on write — the crux of CVTFREE-QA-02.

Extended factor-2

The free-form-like expression area of certain fixed-form opcodes (e.g. EVAL), which may span several continuation lines; the converter joins them, which is where over-length output can arise.

DSPLY

The RPG operation that writes a message line; the corpus captures each program's DSPLY output as the primary equivalence signal.

After-image

The byte contents of a physical file's records after a program runs; ORDPOST's equivalence check compares fixed vs free after-images record-for-record.