The engineering notebook

Fifteen items, transcribed

The program cycle on the front page is not a paraphrase of RPG's behaviour. It is the fifteen numbered items printed beside figure 31 of IBM's Report Program Generator Language, form C24-3337-3, November 1968, transcribed one at a time. The test requires a distinctive clause from every one of the fifteen to appear in the archived copy, so an item reworded to read better turns the build red.

Three of the fifteen are yours: items 6, 7 and 11, the calculations and the output. The other twelve are the compiler's, and that is the whole subject. You did not write the loop. The loop was wrapped around what you wrote, and it read a record, set indicators, took the branches and printed the totals whether or not you had thought about any of it.

The manual has a real text layer, so no character recognition is involved anywhere in this page's quotations. That matters more than it sounds: an OCR'd 1968 manual would put invented commas into sentences the test then demands verbatim.

Why two control levels and not one

RPG supports control levels L1 through L9, nested, so a report can break on branch inside region inside division. The page drives two, and the reason is that one level never shows why they are numbered.

With a single level you see a group total print. With two you see something you cannot see any other way: a break at L2 turns L1 on with it, so the division total prints underneath the group totals that make it up, in that order, without anybody writing the order down. The deck on the page is arranged so the arithmetic can be checked three independent ways — the group totals sum to the division totals, the division totals sum to the final total, and the final total equals the sum of the deck.

Levels three to nine are simply never reached by this deck. The engine carries all nine indicators and sets them all on at end of file, which is what the manual says happens.

A card is eighty columns, and the columns are the language

You did not type a program. You wrote it on a pre-printed form and the compiler read each field out of its own columns: Factor 1 in 18 to 27, the operation in 28 to 32, the result field in 43 to 48. A name beginning one column too far left was a different field, or no field at all.

Every column range on the specification sheet is quoted from the manual's own prose, and the sheet is checked the way a compiler would check it: writing a card from the boxes and reading it back must return every field unchanged, and shifting the card one column must change what the compiler reads. That second test is the one that carries the subject. It is easy to say that columns mattered; it is better to have a check that fails when they stop mattering.

A name too long for its field loses its tail rather than overflowing, because that is what the card does. Six characters of Result Field is six characters.

The return code worth caring about is 4

The compiler graded every diagnostic it found and returned the worst severity. At 8 and above you got a listing and no program, which cost you a day and was obvious. At 4 you got a program, because the compiler had assumed something on your behalf and carried on.

That is the failure this page would keep if it could only keep one. Not the day you lost to an error: the day you did not lose, because output came back and it was the wrong output. A misspelt field name is a warning, the deck compiles, the field is assumed to be zero, and the report is full of zeros that look like a business result.

So the sheet's diagnostics are graded on the compiler's own scale, and the day counter is fed by them rather than by a set of buttons. What your specifications get wrong is what decides how many days the deck took to come back. There is no second way to set the faults, because two ways to answer one question is two answers.

The messages themselves are this page's words, not IBM's. The manual's diagnostic text is in its Appendix G and that part of the scan is too damaged to quote, so the wording is ours and the ledger says so. What is not invented is the grading.

The cycle outlived the manual

The manual on this page is dated November 1968 and describes a System/360. The cycle it defines did not stop there. RPG went to the System/3, the System/34 and /38, and then to the AS/400 in 1988, which became the System i; the language became RPG/400 and later RPG IV, and the implicit cycle came with it. Code written against the 1968 description kept running on machines sold decades later.

That is the reason this page's era reads 1964 to the 1990s rather than stopping at the manual's date. The interesting fact about the program cycle is not that it existed in 1968. It is that it was still doing the work long after everyone had stopped thinking about it, on hardware nobody in 1968 had designed, being maintained by people who inherited it.

Where this page was wrong first

• Four colours that did not exist. The stylesheet read --la-surface, --la-line, --la-fg and --la-mono, none of which the shared sheet declares. An undefined var() with no fallback is not a wrong colour: the whole declaration is invalid and thrown away. Seven form controls rendered with no border at all, through seventeen green gates, and it was found by looking at a screenshot. There is a gate for it now.
• A ledger that had gone stale against its own page. One entry said a specification sheet with column numbers would be a different machine, and it said so while that sheet was being added, and another said the page drove one control level while it drove two.
• A quotation the archive could not see. Four accurate quotations were reported as words no source contained, because the source snapshot was capped at 400,000 characters and the manual extracts to 576,410. The gate could not tell a document that does not say a thing from a snapshot that did not keep the part that does.
• A scrollable card no keyboard could reach. The eighty-column card scrolls sideways on a phone, and a region you can only read by dragging is a region a keyboard cannot read.

What is not here

JCL, which was its own language and its own class of overnight failure. Matching and secondary files. Table lookup. Exception output. The other specification sheets: this page has the calculation sheet and nothing else, so a check it cannot make is a check nobody wrote. And the day count is a model rather than a log. One submission a day is a round number standing in for a range that ran from two hours to three days depending on the shop, the operator and whether the tape you needed was mounted on another job.