Assembler Language

"Boot Camp"
Part 4 - Arithmetic;
Program Structures
SHARE in Minneapolis
July 22 - 27, 2001
Session 8184

1
Introduction
Who are we?

John Dravnieks, IBM

John Ehrman, IBM

Michael Stack, Northern Illinois University

2
Introduction
Who are you?
An applications programmer who needs to write
something in S/390 assembler?
An applications programmer who wants to
understand S/390 architecture so as to better
understand how HLL programs work?
A manager who needs to have a general
understanding of assembler?

Our goal is to provide for professionals a brief

introduction to the S/390 assembly language
3
Introduction
These sessions are based on notes of a course in
assembler language at Northern Illinois University

The notes are in turn based on the textbook,

Assembler Language with ASSIST and ASSIST/I by
Ross A Overbeek and W E Singletary, Fourth
Edition, published by Macmillan

4
Introduction
The original ASSIST (Assembler System for
Student Instruction and Systems Teaching) was
written by John R Mashey at Penn State University

ASSIST/I, the PC version of ASSIST, was written

by Bob Baker, Terry Disz and John McCharen at
Northern Illinois University

Both ASSIST and ASSIST/I are in the public

domain, and are compatible with the System/370
architecture of about 1975 (fine for beginners) 5
Introduction
Both ASSIST and ASSIST/I are available at
http://mstack.cs.niu.edu/pub/assist

Other materials described in these sessions can

be found at the same site, at
http://mstack.cs.niu.edu/pub/share

Disclaimer: please keep in mind that neither Penn

State nor NIU are able to provide support for
ASSIST or ASSIST/I
6
Introduction
Other references used in the course at NIU are:
Principles of Operation
System/370 Reference Summary
High Level Assembler Language Reference

Access to PoO and HLASM Ref is normally online

Students use the white "green card" booklet all

the time, including during examinations
(SA22-7209)
7
Our Agenda for the Week
Session 8181: Numbers and Basic Arithmetic

Session 8182: Instructions and Addressing

Session 8183: Assembly and Execution; Branching

Session 8184: Arithmetic; Program Structures

Session 8185: Decimal and Logical Instructions

8
Today's Agenda
The MULTIPLY and DIVIDE Instructions

EQUate and Extended Branch Mnemonics

Literals, LOAD ADDRESS, and Looping

Subroutines and Linkage Conventions

9
The MULTIPLY and
DIVIDE Instructions

In Which We Encounter
"Higher" Math

10
Multiplication
MULTIPLY, like ADD and SUBTRACT, comes in
two flavors: RR and RX

Both require the first operand to be an even/odd

pair of registers, implicitly specified by the even
register

The RR and RX formats are

label MR R1,R2
label M R1,D2(X2,B2)
11
Multiplication
The multiplicand is in R1+1 (the 2nd of the pair)

The multiplier is in R2 or at D2(X2,B2)

The product will be two words long in the

even/odd pair R1/R1+1

The Condition Code is not changed by MULTIPLY

12
Multiplication
For example: if c(R9) = 00000003,
c(R7)=FFFFFFFD (-3), and c(R6) is anything
Then MR R6,R9 leaves R9 unchanged and the
result is R6/R7 = FFFFFFFF FFFFFFF7 (-9)

Note that the magnitude of the result must be

very large before the even-numbered register has
anything besides the sign

Note that MR R8,R9 squares the value in R9,

with the result in R8/R9 13
Multiplication Examples
Some examples, all of which assume:
c(R0)=F01821F0, c(R1)=FFFFFFFF
c(R2)=00000003, c(R3)=00000004
WORD1 DC F'10'
WORD2 DC F'-2'

MR 2,1: R2/R3 = FFFFFFFF FFFFFFFC (-4)

MR 0,2: R0/R1 = FFFFFFFF FFFFFFFD (-3)

MR 2,3: R2/R3 = 00000000 00000010 (16) 14

Multiplication Examples
MR 2,2
R2/R3 = 00000000 0000000C (12)

M 0,WORD1
R0/R1 = FFFFFFFF FFFFFFF6 (-10)

M 0,WORD2
R0/R1 = 00000000 00000002 (2)

M 2,WORD1
R2/R3 = 00000000 00000028 (40)
15
Division
Division also comes in two flavors: RR and RX

Both also require the first operand to be an

even/odd pair of registers, implicitly specified by
the even register

The RR and RX formats are

label DR R1,R2
label D R1,D2(X2,B2)

16
Division
The dividend is two words long and in the
even/odd pair R1/R1+1

The divisor is in R2 or at D2(X2,B2)

The quotient will be in R1+1, with the sign

following the normal rules of algebra

The remainder will be in R1, with its sign the same

as the dividend's
17
Division
If the quotient cannot be represented as a 32-bit
signed integer, a "fixed-point divide" exception
occurs. This also happens if the divisor is zero.

The Condition Code is unchanged by DIVIDE

N.B. The dividend will often fit into a single

register, but the sign must be correct in both
registers of the pair

This is assured by first multiplying by 1 18

Division Examples
Some examples, all of which assume:
c(R2) = 00000000, c(R3) = 00000014
c(R4) = FFFFFFFF, c(R5) = FFFFFF10 (-240)
c(R1) = 00000003
WORD1 DC F'-4'
WORD2 DC F'14'

DR 2,1 (so dividend is in R2/R3)

R2/R3 = 00000002 00000006 (2,6)

19
Division Examples
DR 2,4
R2/R3 = 00000000 FFFFFFEC (0,-20)

DR 2,5
R2/R3 = 00000014 00000000 (20,0)

DR 4,1 (so dividend is in R4/R5)

R4/R5 = 00000000 FFFFFFB0 (0,-80)

D 2,WORD1
R2/R3 = 00000000 FFFFFFFB (0,-5) 20
Division Examples
D 2,WORD2
R2/R3 = 00000006 00000001 (6,1)

D 4,WORD1
R4/R5 = 00000000 0000003C (0,60)

D 4,WORD2
R4/R5 = FFFFFFFE FFFFFFEF (-2,-17)

21
 Register EQUates &
Extended BRANCH
Mnemonics
In Which We Find More Than One
Way to Say the Same Thing

22
Register EQUates
It is possible to define symbols using the EQU
instruction
label EQU expression

Then, when the assembler encounters label it

will substitute expression

For now, expression is an integer

And we can define symbolic register names

R0 EQU 0 etc
23
Register EQUates
Be careful how you think about the symbols,
though - all the assembler does is substitute

For example, assuming that all register equates are

available, consider the object code for
L R3,R4 (!) (58300004)
L R3,R4(R5,R6) (58356004)

It should be clear that using symbols does not

change the object code, it just makes the program
more readable (it is fervently to be hoped)
24
Extended BRANCH Mnemonics
The BRANCH ON CONDITION instructions
(BC,BCR) require a branch mask

We have thus far given the mask as B'xxxx'

There are, however, special mnemonics which

incorporate the mask into the "op code"

So, for example, after a compare instruction, use

BE addr instead of
BC B'1000',addr
25
 Literals,
LOAD ADDRESS,
and Looping
In Which We Face a Most Difficult
But Very Important Concept

26
Literals
Recall that the DC instruction defines an area of
storage within a program, with an initial value
Since that value is only initial, it can easily be
changed (and very often is)

There is also a need for a "constant," a value in

storage which is intended to remain that value
M R4,ONE
...
ONE DC F'1'

27
Literals
We can instead define the constant as part of the
instruction, directly as the second operand
M R4,=F'1'

In this case, the second operand is a literal, which

is indicated by the preceding equal sign

This is also good documentation, as the value is

seen immediately, rather than after searching the
program listing for a data area

28
Literals
But where will the storage for this literal be?
With a DC (or DS) the location is exactly where
the instruction occurs

A literal, however, will be located in a "pool" of

literals whose location is defined by using the
LTORG (LiTeral pool OriGin) instruction

As many LTORGs as needed may be used, and

each creates a pool for all "unpooled" literals
The same literal (e.g., =F'1') may appear in
multiple pools 29
The LOAD ADDRESS Instruction
This is very simply stated
label LA R1,D2(X2,B2)
Replaces the contents of R1 with the address of the
second operand (D2(X2,B2))

Here is a key to understanding:

L R5,WORD is the same as the pair:
LA R5,WORD followed by
L R5,0(,R5)

30
The LOAD ADDRESS Instruction
Sometimes only D2 is specified - that is, X2 and B2
are zero
LA R5,4 (0<=D2<=4095)
This is a long-standing method to place a small
number in a register with no other memory access
Note: this is the same as LA R5,4(0,0)

LA may also be used to increment (but not

decrement) a value in a register
LA R6,1(,R6) Increase c(R6) by 1
N.B. The high order bit or byte of R6 is set to zero
31
Demo Program to Build a Table - 1
* The following program builds a table of fullwords and then exits
* the completed program. It reads one number off each input card,
* recognizing the end of input when a trailer card containing
* 999999 is encountered. The logic of the program is:
*
* Step 1. Initialize R3 to point to the first entry in the table.
* R4, which is used to count the entries in the table, is
* Initially set to 0.
*
* Step 2. Read the first card.
*
* Step 3. Check for the trailer. If it is the trailer go to Step 6
* to exit the program.
*
* Step 4. Put the number into the table (adding 1 to the count of
* entries and incrementing the pointer to the next entry).
*
* Step 5. Read the next card and go back to Step 3.
*
* Step 6. Exit the program. 32
Demo Program to Build a Table - 2
*********************************************************************
TABUILD CSECT
USING TABUILD,R15
*
***<Step 1> Initialize counter and pointer to next entry
*
SR R4,R4 Set count of entries to 0
LA R3,TABLE Point at first entry (next one to fill)
*
***<Step 2> Read the first card
*
XREAD CARD,80 It is assumed that there is a card and
* that it contains a number
XDECI R2,CARD
*
***<Step 3> Check for trailer
*
TRAILCHK C R2,TRAILER Check for trailer
BE ENDINPUT
*
33
Demo Program to Build a Table - 3
*
***<Step 4> Add the number to the table
*
ST R2,0(,R3) Put number into next slot in the table
LA R4,1(,R4) Add 1 to count of entries in the table
LA R3,4(,R3) Move “next entry” pointer forward 1 entry
*
***<Step 5> Read the next card and get the number into R2
*
XREAD CARD,80
XDECI R2,CARD The next number is now in R2
*
B TRAILCHK
*
***<Step 6> Return to the caller
*
ENDINPUT BR R14 Exit from the program
*

34
Demo Program to Build a Table - 4
LTORG
CARD DS CL80 Card input area
TABLE DS 50F Room for 50 entries
TRAILER DC F'999999'
R2 EQU 2
R3 EQU 3
R4 EQU 4
R14 EQU 14
R15 EQU 15
END TABUILD
$ENTRY
123
456
789
234
567
890
345
999999

35
Looping Using BCT and BCTR
The loop we saw in the demo is controlled by the
number of records in the input file

Sometimes, a loop is to be executed n times

1. Set I equal to n
2. Execute the body of the loop
3. Set I <- I-1
4. If I .NE. 0, go back to 2
5. Otherwise, continue (fall through)

This loop is always executed at least once

36
Looping Using BCT and BCTR
There is a single instruction which implements this
loop control - BRANCH ON COUNT
label BCTR R1,R2
label BCT R1,D2(X2,B2)

The logic is
Decrement R1 by one
If c(R1) .NE. 0, branch; otherwise, continue

In BCTR, if c(R2) = 0, no branch is taken, although

the R1 register is still decremented 37
Looping Using BCT and BCTR
How many times is each loop executed?
************************
LA R12,6
LOOP ...
BCT R12,LOOP
************************
LOOP LA R12,200
...
BCT R12,LOOP
************************
LA R10,LOOP
LA R11,413
LOOP ...
BCTR R11,R10
************************
LA R0,LOOP
LA R1,10
LOOP ...
BCTR R1,R0 38
 Subroutines and
Linkage Conventions
In Which We Show That You Can
Go Home Again, and How

39
The Program Status Word (PSW)
The PSW is a two-word aggregation of a number
of important pieces of information, including
The address of the next instruction
The Interruption Code
The Condition Code (CC)
The Program Mask
The Instruction Length Code (ILC) (in ASSIST only)

N.B. - The "basic" PSW format used in ASSIST

dates to the 1970s and is not current; even so, it
does have some fields which will help us
40
The Program Status Word (PSW)
The PSW fields in ASSIST that we want are
Bits 16-31: Interruption Code
Bits 32-33: Instruction Length Code
Bits 34-35: Condition Code
Bits 36-39: Program Mask
Bits 40-63: Next Instruction Address

We will need all of these when we analyze a

problem with a program, but for now we need
only the last four, which make up the second half
of the PSW
41
The Program Status Word (PSW)
The Instruction Length Code (bits 32-33) has the
following meaning for its four possible values
Op Code Instruction
ILC (Dec) ILC (Bin)
Bits 0-1 Length
Not
0 00
Available
1 01 00 One
halfword
2 10 01 Two
halfwords
2 10 10 Two
halfwords
Three
3 11 11
halfwords 42
The Program Status Word (PSW)
The Instruction Length Code can be used to
determine the address of the current instruction
Multiply by two to get the number of bytes in the
current instruction
Subtract it from the address of the next instruction

We will use this later, in analyzing a program

problem

43
BAL/BALR and Subroutines
There is a very important instruction which is
used to control access to subroutines, BRANCH
AND LINK

The RR and RX formats are

label BALR R1,R2
label BAL R1,D2(X2,B2)

Their operation is simple

1. Copy the second word of the PSW to R1
2. Branch to the address given by the second operand
44
BAL/BALR and Subroutines
Step 1 of the operation of BAL/BALR copies to
R1 the ILC, CC, Pgm Mask, and address of the
next instruction (this last is very important)

This operation means that, if we want to execute

a subroutine called SORT, we can
1. Use BAL R14,SORT in the main routine, to
place the address of the instruction following the
BAL in R14, then branch to SORT
2. Use BR R14 at the end of the SORT
routine to return and resume the main routine
45
BAL/BALR and Subroutines
The RR form, BALR, is very common, especially
BALR R14,R15 for "external" subroutines

A special use of BALR occurs when c(R2) = 0;

then no branch occurs after placing the address of
the next instruction in R1
BALR R12,0
USING NEWBASE,R12
NEWBASE ... (next instruction)

This is often used to establish a base register 46

The STM and LM Instructions
Having subroutines is all very nice, but with a
limited number of registers, it is useful for
subroutines to save registers at entry, then
restore them at exit

A third instruction format, RS, is used. Our first

instruction is STORE MULTIPLE
label STM R1,R3,D2(B2)
Copies the contents of the range of registers R1
through R3 to consecutive words of memory
beginning at D2(B2)
47
The STM and LM Instructions
Thus, STM R4,R8,SAVE would place the
contents of R4, R5, R6, R7, and R8 in the five
fullwords beginning at location SAVE

And STM R14,R1,SAVE would copy R14,

R15, R0, and R1 to four consecutive fullwords at
location SAVE [note the register wrap-around]

hOPhOPhR1hR3 hB2hD2hD2hD2 is the encoded form of

an RS instruction
48
The STM and LM Instructions
The inverse operation is LOAD MULTIPLE
label LM R1,R3,D2(B2)
Copies the contents of the consecutive words of
memory beginning at D2(B2) to the range of
registers R1 through R3

Since one of the responsibilities of a subroutine is

to assure that registers contain the same contents
at exit that they did at entry, we can use STM and
LM to save and restore them

We will generalize the method shortly 49

Saving and Restoring Registers
ROUTINE STM R0,R15,SAVEAREA Save all regs
...
body of routine
...
LM R0,R15,SAVEAREA Restore all regs
BR R14 Return to caller
...
SAVEAREA DS 16F Store regs here

50
Type A Data: Address Constants
label DC A(exp) [or DS A]
If exp is a non-negative integer, the generated
fullword will have the binary representation of the
integer (same as F'exp')
If exp is the label of an instruction or a data area,
or is of the form label+n or label-n, the generated
fullword will contain the appropriate address
If exp is the label of an EQU of a non-negative
integer, then the symbol is interpreted as a
non-negative integer, and the generated fullword will
have the binary representation of the integer
51
Type A Data: Address Constants
The following are examples
DC A(123) generates 0000007B
DC A(R12) generates 0000000C
DC A(SAVE) generates the address of SAVE

Very important: All that is known at assembly

time is the relative location, not the memory
address; it is left to the "program loader" to
adjust the relative location at execution time, to
make it the address in memory
52
Type A Data: Address Constants
But why bother? Why not just use LA? The
answer is that a single base register can address
only 4096 bytes (000-FFF)

LA R4,TABLE3 This fails!

...
L R4,ATABLE3 This works!
...
ATABLE3 DC A(TABLE3)
TABLE1 DS 1024F (= 4096 bytes)
TABLE2 DS 1024F
TABLE3 DS 1024F
...
53
External Subroutines
Subroutines which are known only to the
assembly in which they occur are internal; all
others are called external subroutines

External subroutines may be written in assembler

or another language

In order to communicate with an external

subroutine, there must be standards - lots of
standards: the source for the subroutine is often
unavailable for review
54
External Subroutines - Calling
This means that BAL R14,SORT can no longer
be used, as it assumes access to the label SORT

For similar reasons, the following may not work

L R15,=A(SORT)
BALR R14,R15

Instead, the standard method for calling an

external subroutine is
L R15,=V(SORT)
BALR R14,R15
55
External Subroutines - Calling
The V-type address will cause a search at load
time, usually of the appropriate subroutine library,
for the name within ( ), and the loading of the
subroutine by that name

Once all subroutine names are resolved and the

subroutines loaded, the program is ready for
execution

56
External Subroutines - Parameters
The following demonstrates a typical parameter
list and how it is passed to SORTTABL:
LA R1,PARMLIST
L R15,=V(SORTTABL)
BALR R14,R15
...
NUM DC F'20' Value to pass
PARMLIST DC A(TABLE) First parameter
DC A(NUM) Second parameter
DC A(RET) Third parameter
RET DS F Return code
TABLE DS 20F Table of values
57
External Subroutines - Parameters
We are clearly "passing by reference" rather than
"passing by value"

In this case, both calling and called programs must

agree in advance on the number of parameters

Register 1 is always used to pass the parameter

list address

The value at RET is set by the called routine to

indicate success, failure, or other result
58
External Subroutines - Parameters
The instructions used by the called routine to
return a value to RET might be the following,
here assuming that R0 has the value to return:
L R2,8(,R1) Get address of RET
ST R0,0(,R2) Set value in RET

Summarizing, a parameter list is a list of addresses

of values to pass or be returned
This concept proves to be quite difficult for students

59
External Subroutines - Save Areas
None of the above conventions is particularly
difficult to understand or implement

The convention for saving registers, however, is

less obvious and requires more work

The principal conventions are

The calling program provides an 18-fullword save
area whose address is passed in R13
The called program saves and restores registers
The save areas are linked in both directions
60
External Subroutines - Save Areas
Most routines are both called and calling routines,
so must follow all conventions

Since the calling program has provided a save area

whose address is in R13, the called program's first
instruction is normally
STM R14,R12,12(R13)

This won't make a lot of sense until you see the

format of an 18-fullword save area

61
External Subroutines - Save Areas
*** Unused *** R4
Address of previous R5
save area
Address of next save R6
area
R14 R7

R15 R8

R0 R9

R1 R10

R2 R11

R3 R12 62
External Subroutines -
Standard Entry and Exit Linkage
Registers are restored in a similar manner before
returning to the calling program
LM R14,R12,12(R13)
BR R14

Since R1, R14, and R15 are used for subroutine

calls, they should not be used as base registers (or
anything else long-term)

A standard convention is to use R12 as program

base register, leading to entry/exit conventions
63
External Subroutines -
Standard Entry and Exit Linkage
PROGRAM CSECT
STM R14,R12,12(R13) Save regs at entry
LR R12,R15 Copy entry address
USING PROG,R12 Say it's available
*
LA R14,SAVEAREA Get a save area
ST R14,8(,R13) Caller's -> ours
ST R13,4(,R14) Ours -> caller's
LR R13,R14 For those we call
*
... (Main body of routine)
*
L R13,4(,R13) Get previous save area
LM R14,R12,12(R13) Restore regs at entry
BR R14 Return to caller
SAVEAREA DS 18F For those we call 64
External Subroutines -
Standard Entry and Exit Linkage
So, why go to all this extra effort? The primary
reason is to facilitate debugging

Consider the following program structure

MAIN
|
|------------|-------------|
| | |
BUILD SORT PRINT
| |
| |
SEARCH SEARCH
65
External Subroutines -
Standard Entry and Exit Linkage
Now, suppose an execution error occurs in
SEARCH; how do we know, or how can we
learn, whether BUILD or SORT called SEARCH -
knowing may help figure out what went wrong

The first item to check is R14 - it's got the return

address from somewhere, probably set by BALR

This would tell us the most recent subroutine call,

but not where we came from (R14 at entry to
SEARCH)
66
External Subroutines -
Standard Entry and Exit Linkage
At entry to SEARCH, R13 points to an available
save area, the one where SEARCH saved registers
(including the entry value of R14)

But what if SEARCH followed the standard linkage

convention and provided a save area in case it
called a subroutine?

We need to find the entry value of R13, so look

for the address of the previous save area in word
2 of the save area now pointed to by R13
67
External Subroutines -
Standard Entry and Exit Linkage
Once we have gone "up" one save area, look in its
word 4 to find the value of R14 at entry to
SEARCH

And if we link "up" one more save area (by using

the address in word 2), we would find in word 5
(R15) the entry point address of the routine which
called SEARCH - our goal is met

The save area chain is a doubly-linked list, so we

can go forward or backward from any point
68
External Subroutines -
Standard Entry and Exit Linkage
One last comment about standard linkage: a
common practice is to place a return code in R15
before returning, in which case we must avoid
restoring R15 with the rest of the registers
*
L R13,4(,R13) Get previous save area
L R14,12(,R13) Restore R14
LM R0,R12,20(R13) Restore the rest
BR R14 Return to caller

69
Next Time
Tomorrow, we will look at how decimal arithmetic
is performed, and how numbers are converted
from binary to decimal to character (and the
reverse)

Accurate decimal arithmetic is an important

characteristic of S/390, particularly for financial
applications

We'll also cover the instructions which perform

the logical operations AND, OR, and XOR
70