A mainframe credit card system, modernized one slice at a time.

1 · The system

What CardDemo is

CardDemo simulates the back office of a credit card company. AWS built it as a realistic mainframe application for trying out analysis and migration tools, and publishes it under the Apache 2.0 license (source on GitHub).

3 · Slice 1

What we did, step by step

The daily posting job reads the day's card transactions and, for each one, either posts it to the account or rejects it with a reason code: unknown card (100), unknown account (101), over the credit limit (102) or account expired (103).

1. Inventory the system

   We read every program, job and copybook, mapped which programs read and write which files, and listed 12 risks with file and line references. POSTTRAN came out as the best first slice: one 619-line program, clear inputs and outputs, and sample data included.

2. Run the original and keep its results

   No mainframe needed for this step: the unchanged COBOL program runs on Linux with GnuCOBOL, an open-source COBOL compiler. The harness loads CardDemo's sample data into indexed files the way VSAM holds them, pins the clock so every run is repeatable, runs the job, and saves every output file as the reference.

3. Catch a silent error, in our own first run

   The first run looked fine: 257 posted, 43 rejected, a normal end. It was wrong. Mainframes store the sign of an amount inside its last digit (a G there means +7, a } means −0), and the compiler had not been told. It read $504.77 as $504.70 and a $919.00 refund as a $919.00 purchase. A newer compiler version misread it differently and rejected 299 of 300 transactions.

   With the sign convention set, both compiler versions agree byte for byte: 262 posted, 38 rejected. Every run is now also checked against an independent model of the posting rules written in Python, which fails on the wrong result. This is exactly the kind of error a conversion can introduce without anyone noticing.

4. Fill the gaps in the test data

   The sample data only ever triggers one of the four rejection rules (over the limit). We added nine crafted transactions: an unknown card, a card pointing at a missing account, transactions dated on and after an account's expiry date, a purchase landing exactly on the credit limit, one cent over it, and a refund. All four rules and their boundaries are now tested.

5. Write the Java version

   A Java 21 program that reads and writes the same record files as the COBOL. It follows the original's rules exactly, including details that are easy to miss: which rejection code wins when two rules fail, and leftover bytes the COBOL carries from one record into the next. Any change in behavior sits behind an explicit switch, off by default.

6. Compare old and new

   Test data	Transactions	Posted	Rejected	Result
   CardDemo sample	300	262	38	Identical
   Edge cases	309	265	44	Identical

   Identical means every record in every output file (posted transactions, rejects, accounts and category balances) and every line the program prints. The only field set aside is the fraction of a second in the processing timestamp, which comes from the real clock.

7. Report what the tests found

   The credit-limit check adds up the cycle's purchases and subtracts its refunds. Refunds are stored as negative amounts, so subtracting them adds them back: a refund lowers the balance but counts as extra spending against the limit. After a $50 refund, one test account had $2,070 counted against a $2,020 limit.

   It already affects the published sample data: 17 of the 38 rejections happen only because of it. Switching on the fix changes 19 decisions, not 17: the 17 transactions now post, and 2 later ones on the same accounts are rejected because the extra purchases use up the limit first.

   The Java version keeps the original behavior. Whether refunds should count against the limit is a business decision, so the fix stays off until it is approved, with the list of the 19 transactions it changes.

5 · Slice 3

Daily transaction report

Job TRANREPT sorts the day's transactions by card and prints them: one line per transaction with its type and category, a total after each card, a total at the foot of each page and a grand total at the end. It is also the report users request from the online Reports screen.

1. Run it last, on what posting and interest wrote

   As in the nightly batch, the posted transactions and the interest charges are merged into the transaction file first, then the report runs on them: 312 transactions on 50 cards. The job's own dates (January to early July 2022) are older than our pinned run date, so every transaction would be filtered out; we report on the run date instead.

2. Compare a printed report, line by line

   The output is a report, not data records, so every line is compared in full, all 133 characters including trailing blanks, along with everything the program prints. The job's sort step, which runs on the mainframe's sort utility, is reproduced by a small script; the report program itself runs unchanged. An independent model of the report checks every line.

3. Report what the tests found

   This program had the most to show:

   • The grand total is wrong. At the end of the file the program adds the last transaction a second time: $79,254.29 instead of $79,233.86. The difference, $20.43, is exactly the last transaction.
   • The last card's total is never printed. 49 card totals for 50 cards.
   • Pages run on. Pages are meant to be 20 lines, but 8 of the 18 pages run to 40 or 42 lines.
   • "Account Total" is really a card total. An account with two cards gets two totals.
   • The report can stop early and still report success. The date range is set in two places, the sort step and a date file. If they disagree, the report stops at the first transaction outside the range, with no page total and no grand total, and the job still ends normally. The online Reports screen writes the same dates into both; running the job directly does not.

4. Test the cases the data never reaches

   Six extra transactions on two extra cards: a second card for an existing account, the largest amount the report can print ($123,456,789.01), a negative adjustment, a zero amount (it prints as blanks), and a transaction from the day before, which the sort step filters out. A third run widens the sort step's dates so that one transaction gets through to the program, to show the early stop.

5. Compare old and new

   Test data	Transactions	Report lines	Result
   Nightly data	312	519	Identical
   Edge cases	317	540	Identical
   Dates out of step	318	537, no totals	Identical: Java stops at the same line

   Two compiler versions, GnuCOBOL 3.1.2 and 3.2, produce byte-identical reports.

6. Show exactly what each fix would change

   Three fixes are written and switched off. Counting the last transaction once and printing the last card's total gives a grand total of $79,233.86, exactly posted plus interest. Breaking pages at 20 lines gives 25 even pages with the same totals. Skipping a transaction outside the dates, instead of stopping, brings the totals back.

   Totals per card instead of per account stay as they are: changing that changes the report's layout and sort order, so it is a business decision. You can switch the report fixes on in the Parity Lab and see the end of both reports side by side.

8 · The first screen that writes

Updating an account, and proving what gets saved

The Update Account screen (program COACTUPC) is CardDemo's largest program: 4,236 lines that check about forty fields, ask for confirmation with F5, and rewrite the account and its customer together. Here parity means two things: the same screens, and the same bytes saved.

1. Add the writes to the CICS stand-in

   The view screen's stand-ins gain three commands: READ UPDATE, REWRITE, and SYNCPOINT with ROLLBACK. The rewrite stand-in keeps a before-image of each record it changes, so a rollback really puts the old record back. The program's date check calls an IBM Language Environment service, CEEDAYS, which gets a small stand-in of its own. The terminal stand-in now also refuses to type into protected fields, as a real 3270 does. After every scenario, the files are written out again and every changed record is kept.

2. Record 389 screens, and every write

   Twenty scenarios: field checks one rule at a time (about 70 wrong values, each answered by its own message), dates and leap years, money in every form the program accepts, saving, clearing optional fields, other keys, and all 50 sample accounts. Four of them change the data behind the user's back: another user changes the record or deletes the account or the customer between Enter and F5, or the customer rewrite is made to fail.

3. Carry the rules over, then compare

   The Java service takes the rules over one by one, in the program's order and with its exact messages. The way the screen reads money fields (5000, -5,000.50, $1,000, 5000CR) follows the compiler's own routine, and was checked against it on 40,000 generated inputs with no disagreement. Saving is one transaction: the database locks both rows, checks nobody changed them, and writes both or neither.

   Run	Screens	Records saved	Result
   Java service on the record files	389	8	Identical, except one case (below)
   Java service on PostgreSQL	389	8	Identical, except the same case

   The exception is a day typed as one digit. The original saves it as 2014-11-5 , which no date column can hold, so the Java side refuses the save and says why, and the comparison lists it as an expected difference. Changing a single rule in the Java (a FICO limit of 851 instead of 850) makes the comparison fail.

4. What the tests found

   • The account group is saved in the wrong place. The record the program writes has no zip-code field, so the group lands where the zip code belongs and the real group field is blanked. A new group never shows again, and the value that was in the zip-code position is overwritten.
   • A one-digit day is accepted and saved as 2014-11-5 , a date other programs cannot read. A one-digit month is rejected.
   • Zip codes that start with 0 can never be saved. For Connecticut, Massachusetts, Maine, New Hampshire, New Jersey, Puerto Rico, Rhode Island and Vermont, the program's state table holds the second and third digits of the zip code instead of the first two. A Hartford address, 06103, is rejected; 60103 is accepted.
   • Cleared fields are written as binary zeros. PostgreSQL text cannot hold them, so the database version needs a decision; here it keeps a stand-in character and gives the zeros back on export.
   • When the customer record cannot be locked, the screen says "Changes committed to database" next to the error, though nothing was written.
   • Pressing Enter without changing anything counts as a change when a field is blank, so the checks run on stored data, and a save then writes the blank as binary zeros.
   • The second and third parts of the SSN are checked only when the first part is a number: an IF statement is closed by a full stop, not by its END-IF.
   • None of the 50 sample accounts passes the program's own checks as stored: zip codes that do not match the state, FICO scores under 300, area codes not in the program's list. Rules this strict, on data this loose, have to be settled before a migration, not after.

   Seven of these are switches in the Java service, off by default. With a switch on, the comparison shows which screens and bytes change, and why.

5. Try it

   The account update in the Parity Lab runs both on AWS on fresh copies of the data: pick an account and some changes, or one of the cases above. You see each step's 3270 screen, the Java service's answer, and the records both sides saved, byte by byte.