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
//IEFBR14 EXEC PGM=IEFBR14
//STEPLIB DD DSN=JMM.S370ASM.LOAD,DISP=SHR
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:
LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT
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 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
Extended Mnemonic Instructions
Some EDIT and EDMK Pattern Characters
Summary of Constants
I/O Command Codes
Code Translation Table
Machine Instruction Formats
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.
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.
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.
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
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.