Introduction to S/370 Reference Summary

Having successfully executed our IEFBR14 program, let's backtrack and see how it did what it did.

When we executed our IEFBR14 program, our JCL specified


The STEPLIB simply told MVS that JMM.S370ASM.LOAD contains the IEFBR14 load module LKED produced. No other datasets are defined in our JCL, since we don't need them.

Once our job begins to execute the IEFBR14 step, MVS will read the load module into memory and pass control to our program. Of course, this presumes a lot has happened to the S/370 hardware before "pass control to our program" happens. The MVS operating system has been IPLed (which we're not ready to talk about), MVS has done it's initialization, and loads of other things have happened.

We're going to stop this flurry of activity and drill down to individual S/370 instructions for the duration of our program, pretending we're the S/370 CPU. The first S/370 instruction is:

000000 1FFF                           2          SLR   15,15
Since we're pretending to be the CPU, what we care about is the object code not the source code. The object code for the first instruction is X'1FFF'.

At this point in our journey we're not as smart as the CPU, so we need to find out some things about this instruction. Let's begin with the REFSUM, because POPs is too intimidating at this stage of the game.

S/370 Reference Summary

Let's take a moment to scan the REFSUM's contents.

First, is the title page, which includes something IBM calls the "form number". The form number for the S/370 REFSUM is GX20-1850-3 (at least for the one I'm using). GX20-1850-3 isn't just numbers, it also contains letters as well. Such is IBM-speak; they call things what they call things. The form number is structured into several fields, each separated by a dash. You can think of GX20 as a category, 1850 as a manual number, and 3 as a version number. Version numbers start at zero, and increment each time the publication undergoes a significant change.

While it might seem silly to concentrate on such minutiae, understanding IBM documentation is a crucial skill. There's a lot more that could be said about IBM publications, but let's forge ahead.

Inside the REFSUM, there are sections for

Machine Instructions
Extended Mnemonic Instructions
Some EDIT and EDMK Pattern Characters
Condition Codes
CNOP Alignment
Assembler Instructions
Summary of Constants
I/O Command Codes
Code Translation Table
Machine Instruction Formats
Control Registers
Program Status Word
Channel Command Word
Channel Status Word
Program Interruption Codes
Fixed Storage Locations
Limited Channel Logout
Machine Check Interruption Code
Dynamic Address Translation
Hexadecimal and Decimal Conversion

We're already in trouble, just about none of this makes any sense. And yet, upon closer examination, there are some English-like words here and there. "Machine Instructions" looks promising. "Assembler Instructions" we've already heard a little about, so that looks vaguely familiar. As for the rest, we'll blissfully ignore them and move on for now. But we'll be back.

Let's begin with the Machine Instructions section.

Machine Instructions

Were we taking a source code approach, the Machine Instructions section would indeed be useful. Here, the S/370 instructions are alphabetized by opcode (labeled Name, as in instruction name).

Mnemonic looks to be what we called the assembler source opcode when we talked about source code formatting. That'll be handy to remember, since we can find an instruction's name from it's mnemonic.

Next up is opcode, which is a hexadecimal number. Normally the machine opcode is one byte, but looking down the list, we do see some with two byte opcodes like the Halt I/O instruction (X'9E00'). Curiously, instructions having to do with I/O seem to have two byte opcodes but they're not the only two byte opcodes. So far, no real pattern has emerged. Let's move on.

At first glance, Format appears to be just some random letters. Looking back over the list of REFSUM sections, we do notice a section called Machine Instruction Formats so once we've looked through Machine Instructions we'll look there.

The final field is Operands, and there does seem to be a pattern there although it's not quite clear what that pattern means.

Before we leave Machine Instructions, let's see if we can find out something about our SLR and BR instructions. And here we have our first bit of success with IBM publications: the SLR mnemonic is the Subtract Logical (c) instruction. Having found SLR, we could run off to POPs to look it up in all it's glory but let's stick with the REFSUM for now.

Oh, this is interesting. The (c) appears at the end of the Machine Instructions section, and says "Condition code is set". So perhaps the (c) isn't part of the instruction's name after all. We have no idea what a "condition code" is, but we're convinced that SLR sets it.

And what of the BR instruction? It doesn't appear to be listed in Machine Instructions. That's somewhat troubling, but we'll just have to cope as best we can. At first, we might be tempted to look for it in Assembler Instructions but we recall that the BR instruction generated object code so it can't be there. Go ahead, check, I don't mind.

Assembler Instructions does show CSECT and END, and the ENTRY statement we heard about but haven't seen yet. While Assembler Instructions look interesting, let's stay focused on the task at hand: finding out something about the BR instruction.

Perhaps we need another approach? Let's switch our viewpoint away from the source code back to the CPU's perspective. The object code for BR is X'07FE'. Since we know the BR instruction has an operand (14), and we notice that 14 = X'E' maybe the assembler stored the operand in the instruction? Let's keep that thought on the back burner (where things are starting to get a bit crowded) since we don't have any proof for such a supposition.

So, where might we find something out about an instruction whose machine opcode is either X'07' or X'07FE'? Let's glance back over the REFSUM sections, maybe something will turn up.

Sadly, none of the sections seem to describe anything familiar enough to be helpful so we just start plowing into the REFSUM. It's not until we reach the Code Translation Table that anything seems to click.

Code Translation Table

Once we reach the Code Translation Table, we notice a column variously labeled "Instruction (RR)", "Instruction (RX)", "Instruction and Format", and "Instruction (SS)". Well, at least the RR seems mildly familiar. It was the Format of the SLR instruction. Maybe using the SLR instruction, we can intuit something about the Code Translation Table that will be helpful in our BR opcode X'07' or X'07FE' search?

As we recall, the SLR mnemonic was named Subtract Logical, it set something called a condition code, it's opcode was X'1F', and it was an RR Format instruction. So we really know quite a bit about the SLR instruction so far, except perhaps what it does (although the name is quite a good clue). We learned all that from the Machine Instructions section of the REFSUM, so let's look through the Code Translation Table to see what we learn there.

There are seven main columns in the Code Translation Table: Dec (decimal), Hex (hexadecimal), Instruction (something), Graphics and Controls (with three subcolumns), 7-Track Tape, Card Code, and Binary.

Let's start eliminating things we don't care about. Graphics and Controls appears to be kind of random until we get above 128 decimal and then it looks like upper and lower case letters and numbers. We'll remember that and skip ahead. 7-Track Tape doesn't interest us in the least. Card Code can't possibly be useful, we don't use punched cards. Binary merely restates the decimal and hexadecimal value. So the only thing left here is Instruction (something).

Well, the Instruction column isn't alphabetized; that much is clear. Rather, the Code Translation Table is ordered on decimal/hexadecimal/binary value. So let's look up X'1F' matching the SLR mnemonic. There it is, under the Instruction (RR) column. Before we forget, let's look for X'07' or X'07FE' matching the BR mnemonic.

Well, that didn't seem to have worked out. First, there's no X'07FE', only X'07'. And then to add insult to injury, the Instruction (RR) is BCR not BR. Temptingly close, but not an exact match.

We're now at a bit of a loss. We know quite a bit about SLR, but very little about BR. Further, we've got this confusing difference between X'07' BCR (from the Code Translation Table) and X'07' or X'07FE' BR (from IEFBR14's object code).

Maybe we can at least clear up the difference between BCR and BR? Let's look up BCR in Machine Instructions. Its Name is Branch On Condition, its Mnemonic is BCR, opcode X'07', Format RR, and Operands M1,R2.

Still no help on the difference between BR and BCR. Before we give up in exasperation, let's take one more pass through the various REFSUM sections; maybe we missed something.

Extended Mnemonic Instructions

It's not until we get to the Extended Mnemonic Instructions that we notice a new reference to BCR. First, let's examine the Extended Mnemonic Instructions column headings: Use, Extended Code* (RX or RR), Meaning, and Machine Instr.* (RX or RR). Meaning, some of that would be nice.

Curiously, the whole Extended Mnemonic Instructions table seems to be dedicated to BC or BCR. And then, just as we're about to give up ... BR appears under the Extended Code* (RX or RR) column. Well, now we've got a specific line in the table to look at: Use=General, Extended Code=B or BR, Meaning=Unconditional Branch, and Machine Instruction=BC or BCR 15,. Given that we've found BR and BCR on the same line in the Extended Mnemonic Instructions, let's presume they're somehow related (especially since they seem to be related via the X'07' opcode). And what's up with a comma at the end of each line?

It's at this point that we decide that only POPs can help us understand what's going on. Click NEXT to follow the link to the next section.