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 sheet that says where a field is

The calculation sheet works on names: ADD AMOUNT TO TOTAL. The names come from the Input specifications sheet, which says which columns of the card each field occupies, and the manual is explicit about what that buys you: “Once the card columns of the field have been specified and the appropriate field name has been defined for the field, other references to this field are made by using its field name rather than writing down the specific card columns each time.”

You say it once and everything afterwards trusts the name. Which is why a field described one column out is not a syntax error anywhere.

What an abend is, exactly

This site is named for the abnormal end and everything above it is a fault the job survives. An abend is the other kind: the machine stops in the middle, having already done some of the work. The one this page is about is a data exception. It said “the commonest one on this hardware” until an outside reader asked where the count was, and there is no count: nobody here has measured it. It is worth being precise about anyway, because it is not a bug in arithmetic. It is arithmetic being asked to read something that is not a number.

The machine, drawn

Where the fields sit on the calculation sheet

Seven fields, each one a fixed range of columns on an eighty-column card. Everything the compiler knows about your program is where these boundaries fall.

Packed, against the same number written as characters

Four bytes, twice. Packed, they hold seven digits and a sign in the last half-byte; written as characters they hold four digits and no sign at all. Only one of them is a number, and the two do not hold the same count of them: four packed digits and their sign need three bytes, not four. The drawing used to be captioned as the same four digits both ways, which no arrangement of these cells is.

The return code worth caring about is 4

The compiler graded every diagnostic it found and returned the worst severity. The scale is Table 8 of the manual, and it grades the outlook for running the program rather than whether one came out: minor errors at 4 with successful execution probable, errors at 8 with unsuccessful execution possible, serious errors at 12 with it probable, and critical errors at 16 where normal execution is impossible. The table’s own note sends you to the job control language, because whether the next step ran on a given code was the COND parameter of the job and nothing to do with the compiler. This page said “at 8 and above you got a listing and no program” on both of its surfaces, and an outside reader was right that that is neither the manual’s definition nor how a job behaved. 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.

The other end of the era needs saying too, because a bare 1964–1990s does not say what is being dated. It is not the language: RPG is older than both documents here, having started on IBM machines before the System/360, and this page does not date it. 1964 is the Principles of Operation, which is where the packed decimal format, the digit and sign codes and the data exception itself come from — the architecture the fault on this page is a fault of. The cycle is the 1968 manual’s.

The 1990s end is the reason the range is a range rather than a 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.