Mainframe S390 Assembler Programming

Name of Document Mainframe Assembler Programming

Department ITS
Version Draft
Author Prakash Verma
Approver
Release Date
Table of Contents
1 INTRODUCTION TO ASSEMBLER PROGRAMMING ........................................................................................................ 4

1.1 NUMBER SYSTEM.............................................................................................................................................................. 4

1.2 ASSEMBLER PROGRAM FORMAT .......................................................................................................................................... 5
1.3 BASE AND DISPLACEMENT –................................................................................................................................................ 6
1.4 INSTRUCTION FORMAT ....................................................................................................................................................... 6
1.5 LINKAGE CONVENTION ....................................................................................................................................................... 8
1.6 FIRST ASSEMBLER PROGRAM .............................................................................................................................................. 9

2 DEFINING AND MOVING DATA .................................................................................................................................. 10

2.1 DEFINE CONSTANT (DC) .................................................................................................................................................. 10

2.2 DATA TYPES ................................................................................................................................................................... 10
2.3 DEFINE STORAGE (DS) ..................................................................................................................................................... 12
2.4 MOVE INSTRUCTIONS ...................................................................................................................................................... 13
2.5 LOAD AND STORE INSTRUCTIONS........................................................................................................................................ 14

3 COMPARE AND BRANCH ............................................................................................................................................ 16

3.1 COMPARE INSTRUCTIONS ................................................................................................................................................. 16

3.2 BRANCH INSTRUCTIONS.................................................................................................................................................... 17

4 BINARY ARITHMETIC .................................................................................................................................................. 21

4.1 ADD INSTRUCTIONS ......................................................................................................................................................... 21

4.2 SUBTRACT INSTRUCTIONS ................................................................................................................................................. 21
4.3 MULTIPLY INSTRUCTIONS ................................................................................................................................................. 22
4.4 DIVIDE INSTRUCTIONS ...................................................................................................................................................... 23

5 PACK DECIMAL ARITHMETIC ...................................................................................................................................... 24

5.1 PACK (PACK) INSTRUCTION.............................................................................................................................................. 24

5.2 ADD DECIMAL (AP) INSTRUCTION ...................................................................................................................................... 24
5.3 ZERO AND ADD PACK (ZAP) INSTRUCTION........................................................................................................................... 25
5.4 SUBTRACT PACK (SP) INSTRUCTION.................................................................................................................................... 25
5.5 MULTIPLY PACK (MP) INSTRUCTION .................................................................................................................................. 25
5.6 DIVIDE PACK (DP) INSTRUCTION........................................................................................................................................ 26
5.7 COMPARE DECIMAL (CP) INSTRUCTION .............................................................................................................................. 26
5.8 UNPACK (UNPK) INSTRUCTION ......................................................................................................................................... 27
5.9 OTHER IMPORTANT PACK DECIMAL INSTRUCTIONS - ............................................................................................................... 28

6 ASSEMBLER MACROS FOR DATASETS ........................................................................................................................ 29

6.1 DCB--CONSTRUCT A DATA CONTROL BLOCK (QSAM) .......................................................................................................... 29

6.2 OPEN—CONNECT PROGRAM AND DATA. ........................................................................................................................... 31
6.3 GET – OBTAIN NEXT LOGICAL RECORD ................................................................................................................................. 32
6.4 PUT – WRITE A RECORD ................................................................................................................................................... 32

APPENDIX - LIST OF INSTRUCTIONS................................................................................................................................ 34

SOURCES ........................................................................................................................................................................... 36
1 Introduction to Assembler Programming

 Why to learn Assembler -

 Assembler is closer to Machine Language so it is faster than any 3GL or 4GL languages.
 There are many legacy applications in large organizations written in Assembler and it is not
economical to rewrite in other language.
 Since each language is ultimately reduced to Machine Language so it makes you a better
programmer if you know how Assembly language works.
 Some applications are simply easier to write in Assembler.

 Mainframe Assembler language is often referred to as BAL (Basic Assembler Language) or HLASM (High
Level Assembler), it is also called second generation language –

 First generation of language is Machine Language, here is an example of an instruction written

in machine language -

0001100011001111  18CF  Load R15 to R12

 Assembler is second generation language, here is an example of an instruction written in

Assembler Language -

L R12,R15
MVC A,B
CLC C,D

 COBOL, FORTRAN, BASIC, PASCAL, C are some examples of third generation language.

1.1 Number System

Data and instructions are represented by binary number system in all computers, so it is important to
understand number system.

 Binary Number System – Binary number system is composed of zeros and ones.

Binary Decimal
0000 0
0001 1
0010 2
0011 3
1111 15
  Hexadecimal Number System – It is easier for computers to understand the binary system but
very difficult for human being to understand and maintain, so hexadecimal number system is
commonly used in place of binary system to understand or write a machine language or assembly
language programs.

Binary Decimal Hexadecimal

0000 0 0
0001 1 1
0010 2 2
0011 3 3
1001 9 9
1010 10 A
1011 11 B
1100 12 C
1101 13 D
1119 14 E
1111 15 F
00011011 22 1B

1.2 Assembler Program Format

Assembler programs can be coded in a free format; however it is very difficult to maintain codes written in
free format.

Current convention is as follows –

PROGRAM BEGIN
CLC A,B COMPARE A AND B
BL LABEL1 IF LESS THEN
MVC C,A MOVE A TO C
B RETURN
LABEL1 MVC C,B ELSE B TO C
RETURN BR R14
1.3 Base and Displacement –
All the instruction or data in memory are stored at an address; these addresses are called absolute
address. You have the option to explicitly count the instruction and data area lengths and manually keep
track of where every instruction begins. This is quite tedious and error prone. Alternatively you can have
the assembler calculate these addresses for you and use relative addressing instead. All you need to do
is tell the assembler where you want it to start counting from. This value need to be in a register. This
register is called the base register.

Any register except register 0 can be base register. Relative from this base register you can use a
displacement to address your program (data or instructions). Displacement is stored in a 12-bit area, so
the maximum value a displacement can store is 4096 byte or 4 KB using a single base register.

1.4 Instruction Format

Instructions can be categorized under five types:

Instruction type Meaning Instruction Length Data processed

RR register to register 2 bytes binary
RX register to storage with index 4 bytes binary
RS register to storage 4 bytes binary
SI Storage to immediate 4 bytes Any data type
SS storage to storage with index 6 bytes Packed or character data

RR instruction

The RR instructions do operations between registers.

+--------+-----+-----+
| op-code| op1 | op2 | 2 bytes long
+--------+-----+-----+
0 8 12 16

Format:
mnemonic op1,op2

Instruction Memory content

label LR 12,15 /* 18CF */

RX instruction

The RX instructions do operations between registers and storage areas. It processes binary fullwords
from register to storage and storage to registers. You can load a value into a register to use as an index
register. If you do not use an index a zero will be in the index position for this instruction.
 +--------+-------+-------+---+---+
| op-code| R | X | B | D | D | D | 4 bytes long
+--------+-------+-------+---+---+
0 8 16 24 31

Format:
mnemonic R,D(X,B)

Instruction Memory content

label A R1,40(5,7) /* 5A157028 */

The displacement of decimal 40 was converted to hex 28 and stored in the displacement area of the
instruction.

RS instruction

The RS instructions processed binary data 1 to 4 bytes in length.

+--------+-------+-------+---+---+
| op-code| R1| R3| B | D | D | D | 4 bytes long
+--------+-------+-------+---+---+
0 8 16 24 31

Format:
mnemonic R1,R3,D(B)

SI instruction

The SI instruction is known as a storage immediate instruction. These instructions used single bytes to
perform move or compare functions.

+--------+-------+-------+---+---+
| op-code| I | B | D | D | D | 4 bytes long
+--------+-------+-------+---+---+
0 8 16 24 31

Instruction Memory content

MVI 50(10),X'00' /* 9200A032 */
The displacement of 50 was converted to hex 32 and register 10 is stored as 'A'.

SS instruction

This is the longest instruction and occupies 6 bytes. 3 different formats of this instruction type can be
used.

Format 2:
mnemonic D1,(L1,B1),D2(L2,B2)
+--------+----+----+-------+---+---+---+---+---+---+
| op-code|L1-1|L2-1| B1| D1| D1| D1| B2| D2| D2| D2| 6 bytes
+--------+----+----+-------+---+---+---+---+---+---+
0 8 16 24 32 40 47
Example
MVC 0(5,R2),0(5,R3)
1.5 Linkage Convention

Every program that executes in the system has certain responsibilities when it starts and right before it
finishes. These tasks are known as the linkage conventions.

When your program starts you need to save all the registers before you start working with them. The
address where you save these registers is called SAVEAREA. We need to do this because many
programs are running on the system at the same time and only 1 set of 16 general purpose registers are
available for everyone to share. You also need to allocate a SAVEAREA for registers. This area has to be
18 Fullwords in length.

BEGIN CSECT
STM R14,R12,12(13)
BALR R12,0
USING ENTRY,12
BASE ST R13,SAVE+4
LA R13,SAVE
.
.
.
L R13,SAVE+4
LM R14,R12,12(R13)
BR R14
SAVE DS 18F

Length of SAVEAREA has to be 72 bytes, here is an example how SAVEAREA should look like -

0-3 UNUSED
4-7 BACKWARD SAVE AREA POINTER
8-11 FORWARD SAVE AREA POINTER
12-15 GR14
16-19 GR15
20-23 GR0
24-27 GR1
28-31 GR2
32-35 GR3 72 - Bytes
36-39 GR4
40-43 GR5
44-47 GR6
48-51 GR7
52-55 GR8
56-59 GR9
60-63 GR10
64-67 GR11
67-71 GR12

BACKWARD SAVE AREA POINTER  Save area address of calling program.

FORWARD SAVE AREA POINTER  Save area address of called program.
1.6 First Assembler Program

The smallest program that can be run on mainframe is a previous version of IEFBR14, which is widely
used in JCL to allocate or delete a dataset –

****************************************************************
* REMARKS : IEFBR14 – A VERY SMALL PROGRAM *
****************************************************************
IEFBR14 CSECT
BR R14

The first version of IEFBR14 takes only 2 bytes.

The following program will load values in two registers and add the contents of both the registers; it also
has instructions to follow the linkage convention.

****************************************************************
* REMARKS : This program will add contents of 2 *
* Registers *
****************************************************************
BEGIN CSECT
STM R14,R12,12(13)
BALR R12,0
USING ENTRY,12
BASE ST R13,SAVE+4
LA R13,SAVE
LA R2,10
LA R5,20
AR R2,R5
EXIT L R13,SAVE+4
LM R14,R12,12(R13)
BR R14
SAVE DS 18F
2 Defining and Moving Data

2.1 Define Constant (DC)

The “define constant” instruction defines storage with an initial value. The word constant is misleading
because this value can be changed at any time. This storage area will take up space in your program

Instruction Format –

LABEL DC dtl’v’

d – Duplication Factor
t – Type
l – Length
v - value

Example –

ARRAY DC 100CL3‟ASM‟

2.2 Data Types

Followings are the valid data types in assembler –

 F - Fullword (4 bytes)
 H - Halfword (2 bytes)
 X - Hex value (1 byte)
 B - Binary data (1 byte)
 C - Character data (1 byte)
 E or D - Floating Point Numbers
 P - Packed Decimal
 Z - Zoned Decimal
 A - Address Constant
 V - Address Constant

F - Fullword

This value is a signed, binary integer and it takes 4 byte storage. The range of numbers storable in a
fullword is -2^31 and +2^31.

FCONST1 DC F'18' /* Define a fullword containing */

/* 00000012 */
FCONST2 DC F'-5' /* Area will contain FFFFFFFB */
/* The two's complement of +5 is stored */
FCONST2 DC FL3'32' /* Define a two's complement 3 byte no */
/* boundary aligned binary integer */
/* value. The storage area consist of */
/* '000020' */
H - Halfword

This value is a signed, binary integer and it takes 2 byte storage. The range of numbers storable in a
fullword is -2^15 and +2^15.

HCONST1 DC H'12' /* '000C' will be in this storage area */

HCONST2 DC 3H'12' /* '000C000C000C' will be stored in */
/* this area */

X - Hex

Data is allocated on a byte boundary and the minimum number of bytes required to store the value will be
used. The data is stored as unsigned hex integer. 2 digits can fit into one byte. If you specify an uneven
number of digits the assembler will pad your value on the left with a zero. The maximum number of
characters you can store in this data type is 256 bytes. Valid data are hex digits 0-9 and A-F.

XCONST1 DC X'ABCDE' /* This data stored is 0ABCDE. The 0 */

/* was added to complete the uneven byte */
XCONST2 DC X'C1E2E2C5D5C2D4C5E1' /* Also store 'ASSEMBLER' */
XCONST3 DC XL3'678' /* Define 3 bytes and the storage will */
/* contain '000678' */

B - Binary

Allow you to define your data in binary format. If you do not define the data on a 1 byte multiple the
assembler will pad your data on the left with zeros.

BCONST1 DC B'1010' /* 00001010 will be stored */

C - Character data

Defines and valid EBCDIC character data.

CCONST1 DC C'ASSEMBLER'/* Define storage area containing the */

/* word 'ASSEMBLER' */
CCONST2 DC CL5'DOG' /* Storage will consist of ' DOG' */
CCONST3 DC CL3'BIGDOG' /* Storage will consist of 'BIG'. */
/* Because the explicit length were */
/* specified truncation occurred. */

P - Packed Decimal data

In packed format each byte represents 2 numbers and the last digit indicates the sign. The number range is
from 1 - 31 digits.

Z - Zoned Decimal data

Each byte consists of two pieces. The left half (4 bits) of the byte represent the zone and the right half (4
bits) represent the number.
 A - Address Constant

This is also known as an A-CON. This storage area consists of an absolute or relocatable expression. On
difference with A_CON definitions is the constant (c) value is defined in parentheses instead of quotes.

ACONST1 DC A(ACONST1) /* Store the address of ACONST1 in this */

/* storage area. */
ACONST2 DC A(*) /* Use the address in the location */
/* counter and store it in this area. */
/* This is the same as A(CONST2). */
ACONST3 DC A(HOME+4) /* Add 4 to the address where HOME is */
/* and store the address in ACONST3 */
ACONST4 DC AL3(HOME+8) /* Add 8 to the address where HOME is */
/* and store the address in ACONST4 but */
/* the address will only be 3 bytes long*/

V - Address Constant

This is also known as a V-CON. This storage area will consist of an symbol. As with A_CON's the constant
(c) value is defined in parentheses instead of quotes.

L R15,=V(SUBPGM) /* Entry of SUBPGM stored in R15 */

BALR R14,R15 /* Go to address in R15 and set R14 */
/* to the return address. */

2.3 Define storage (DS)

The instruction format is very similar to the DC instruction. The major difference is with DS you define or
reserve the storage but the storage area does not get initialized to an initial value at definition time. If you
do supply a constant value it would not be used. As with DC the duplication value can be set to zero to
force boundary alignment. The bytes skipped will not be set to zero.

Examples of DS -

FSTG1 DS F /* Reserve a fullword (4 bytes) */

FSTG2 DS 2F /* Reserve 2 fullwords */
HSTG1 DS 50H /* Reserve 50 halfwords */
XSTG1 DS 5X /* 5 bytes reserved with no boundary */
/* alignment */
BSTG1 DS 5B /* Same as above but will describe the */
/* data content to humans more clearly */
/* Do this to make later debugging */
/* easier. */
XTG1 DS X'1111' /* The assembler will determine the */
/* length of the constant define the */
/* storage area with 2 bytes BUT the */
/* area will but be initialized to this*/
/* values. */
ALIGN DS 0F /* */
DS X'12345678' /* Define a data area the size of a */
/* fullword and force boundary alignment*/
/* of a fullword by using a zero */
/* duplication factor. */
2.4 Move instructions

MVC (Move Character) Instruction

One of the most used instructions in Assembler is MVC instruction. It copies content of one field to
another. It is storage to storage instruction and can move maximum 256 bytes of data.

Example –

MVC NAME(4),FNAME
MVC NAME+4(5),LNAME
.
.
ENAME DS 0CL20
FNAME DC CL10’JOHN’
LNAME DC CL’10’SMITH’

The amount of bytes to be copied is determined by the length of the receiving field. You need to either
explicitly define the length or the assembler will determine the destination length at assembly time.

MVI (Move Immediate) Instruction

MVI instruction can move one byte date to a storage area.

Example –

MVI AREA,C'A' /* Move 'A' into AREA */

MVI NAME+6,C'B' /* Move 'B' into name + 6 */
MVI BINARY,X'00' /* Move x'00' to BINARY */

Example to initialize a field to SPACE –

MVI AREA,C' '

MVC AREA+1(L’AREA-1),AREA

MVCL (Move character long) Instruction

If we have to move more than 256 bytes of data, we can either use set of MVC instructions or MVCL
instruction. This instruction will use 4 registers in two even-odd register pairs.

+--------+---+---+
| op-code| R2| R4| 4 bytes long x '0E'
+--------+---+---+
0 8 15

Format:
MVCL R2,R4
 The maximum amount of data that can be copied with this instruction is 16 megabytes as the length
indicator is the right 3 bytes of the odd register values.

Example –

MVCLEX1 EQU *
RECEIVE DC CL'SOMEDATA'
SEND DC CL'A LONGER FIELD'

LA R6,RECEIVE
LH R7,=H'8'
LA R8,SEND
LH R9,='14'
MVCL R6,R8

After this is done the field would look like this:

REVEICE DC C'A LONGER'
SEND DC C'A LONGER FIELD'

2.5 Load and Store instructions

L (Load) Instruction

This instruction will load a register with the content of a memory location.

L R1,VAR1 /*Copy fullword from effective*/

VAR1 DC F'80' /* into R1 */

LA (Load Address) Instruction

This instruction will load a register with the address of a memory location.

LA R1,VAR1 /*Copy address of VAR1 */

VAR1 DC F'80' /* into R1 */
LA R2,5 /* Load the number 5 into R2 */

LH (Load Halfword) Instruction

Loads the content of an halfword into a register. The storage address must be on a fullword boundary.

LH R1,REG1 /* Copy data from storage */

REG1 DC H'80' /* area REG1 to register 1 */

Load Multiple (LM) instruction

Loads the contents of a memory location in multiple registers

LMEX1 LM R1,R3,REG1 /* Copy data from storages */

REG1 DS F /* areas REG1, REG2, REG 3 */
REG2 DS F /* into register 1, 2 and 3. */
REG3 DS F /* */

LMEX2 LM R14,R12,SAVEAREA+4 /* Copy data from SAVEAREA */

SAVEAREA DS 18F
Store (ST) instruction (x'50')

The ST instruction will store the content from a register into a fullword storage area.

ST R1,SAVER1
SAVER1 DS F

Store Halfword (STH) instruction

The STH instruction will store the right most 2 bytes or a register into a storage area.

STH R1,HALF
HALF DS H

Store Multiple (STM) instruction

STM will store multiple consecutive registers into multiple consecutive storage areas. If you specify the
starting register to be higher than the ending register this instruction would wrap.

EXMP1 STM R1,R3,REG1 /* Copy R1, R2 AND R3 into */

REG1 DS F /* the 3 storage areas start */
REG2 DS F /* at REG1 */
REG3 DS F /* */

EXMP2 STM R14,R12,SAVEAREA /* Copy R14, R15, R0, R1...R12*/

DS SAVEAREA 15F /* into SAVEAREA */
3 Compare and Branch
There are instructions that compare two values and set a condition code based on the result. We can
then use this condition code to make decisions in our program.

The condition code is set to the following after the compare instruction is completed:

CLC A,B

CC is 0 if values are equal

CC is 1 if A < B (A low)
CC is 2 if A > B (A high)

3.1 Compare Instructions

Compare Register (CR) instruction

CR instruction compares two registers.

Example:

CR R8,R6

Assume the following registers contain the following HEX values:

R8 = 00000222 and R6 = 00000222 -> CC is 0 (equal)
R8 = 00000000 and R6 = 00000222 -> CC is 1 (left low)
R8 = 00000999 and R6 = 00000222 -> CC is 2 (left high)
R8 = 98765432 and R6 = 12345678 -> CC is 1 (left low)
R8 = 98765432 and R6 = 98765431 -> CC is 2 (left high)

The last two contains negative number where it starts with 9 (1001).
98765432 is a bigger negative number than 98765431.

Compare Register (C) instruction

This instruction compares content of a register with a Fullword memory location.

Example:
C R1,D2(X2,B2)
C R5,COUNT

Compare halfword (CH) instruction

This instruction compares content of a register with a Halfword memory location.

Example:
CH R1,HALF

Compare Logical Immediate (CLI) instruction

This instruction compares memory location with one byte immediate data.

Example:
 EXMP1 CLI DATA,C'X' /* */
EXMP2 L R8,SOMEDATA /* Load 4 bytes in R8 where */
/* SOMEDATA resolved too. */
CLI 3(R8),C'#' /* Compare 4th byte in R8 */
BE MATCH /* to 'X' and branch is =. */

Compare Logical Character (CLC) instruction

Compares two storage areas and set a condition code.

CLC DATA1(10),DATA2

DATA2 is compares to DATA1 for a length of 10 bytes.

Other Compare instructions

CL, CLR,…….

3.2 Branch Instructions

After comparing the values we may need to perform conditional operation. To do that we may have to
move around in our program, we move around in our program by using Branch Instructions.

Branch on Condition (BC, BCR) instruction

Format:
BC M1,D2(X2,B2)
BCR M1,R2

The BRANCH ON CONDITION instruction tests the condition code to see whether a branch should or
should not occur. The branch occurs only if the current condition code corresponds to a one bit in a mask
specified by the instruction.

Condition Condition Code Mask Value

Equal 0 8
Less 1 4
High 2 2
Overflow 3 1

BC B'1111',CALCDATE /* branch unconditional */

BC X'B',CALCDATE /* Branch if mask is 1011 */
BC 5,CALCDATE /* Branch on mask '0101' */

BC B'1111',R2 /* branch unconditional */

BC X'B',R2 /* Branch if mask is 1011 */
BC 5,R2 /* Branch on mask '0101' */

Extended mnemonics
We now know how to set a mask to branch if the condition code has a certain value but this if very error
prone and an easier way exist to do this. It's called extended mnemonics -

Description Instruction Meaning Equal instruction

Branch unconditional B RTN1 B b'1111' BC 15,RTN1
BR R4 BCR 15,R4
Branch on Equal BE RTN1 B b'1000' BC 8,RTN1
BER R4 BCR 8,R4
Branch on now equak BNE RTN1 B b'0111' BC 7,RTN1
BNER R4 BCR 7,R4
Branch on low BL RTN1 B b'0100' BC 4,RTN1
BLR R4 BCR 4,R4
Branch on not low BNL RTN1 B b'1011' BC 11,RTN1
BNLR R4 BCR 11,R4
Branch on high BH RTN1 B b'0010' BC 2,RTN1
BHR R4 BCR 2,R4
Branch on not high BNH RTN1 B b'1101' BC 13,RTN1
BNHR R4 BCR 13,R4
No branching takes place NOP RTN1 B b'0000' BC 0,RTN1
NOPR R4 BCR 0,R4

After arithmatic instructions:

Branch on Zero BZ RTN1 B b'1000' BC 8,RTN1
BZR R4 BCR 8,R4
Branch on not Zero BNM RTN1 B b'0111' BC 7,RTN1
BNMR R4 BCR 7,R4
Branch on Positive BP RTN1 B b'0010' BC 2,RTN1
BPR R4 BCR 2,R4
Branch on not Positive BNP RTN1 B b'1101' BC 13,RTN1
BNPR R4 BCR 13,R4
Branch on Minus BM RTN1 B b'0100' BC 4,RTN1
MBR R4 BCR 4,R4
Branch on not Minus BNM RTN1 B b'1011' BC 11,RTN1
BNMR R4 BCR 11,R4
Branch on Overflow BO RTN1 B b'0001' BC 1,RTN1
BOR R4 BCR 1,R4
Branch on not Overflow BNO RTN1 B b'1110' BC 14,RTN1
BNOR R4 BCR 14,R4

Branch on Count (BCT) instruction

Format:
BCT R1,D2(X2,B2)
nd
First operand in BCT instruction is a register and 2 operand is a memory location. Content of the first
register is subtracted by 1 and tested for zero, if it is zero it doesn‟t branch otherwise it branches to the
nd
address pointed by 2 operand.

Example -

LA R2,10
LOOP EQU *
AR R3,R5
BCT R2,LOOP

In above example LOOP routine is performed 10 times.

Branch on Count Register (BCTR) instruction

Format:
BCTR R1,R2

nd
This is very similar to BCT instruction but in BCTR 2 operand will be a register. Content of the first
register is subtracted by 1 and then tested for a zero, if it is zero it doesn‟t branch otherwise it branches to
nd
the address stored in 2 register.

The BCTR instruction can be used to subtract 1 from a register and no condition code would be set.
Using a 0 as the will also cause no branching to occur.

Example -

LA R2,10
LA R6,LOOP
LOOP EQU *
AR R3,R5
BCTR R2,R6

Branch and Link Register (BALR) instruction

Format:
BALR R1,R2

BALR is RR type instruction, it branches to the address in R2. Before the branch takes place the address
of the next instruction in your program following the BALR instruction in placed in R1. If the second
operand is register R0, no branch takes place and the only action that would take place would be to load
the next instruction address into the first operand. This coding technique is often used to set the address
in a base register –

MYPROG DS 0H
USING MYPROG,R2
BALR R2,R0

Other use of BALR is call a subroutine or subprogram from your main program -

LA R6,CALCULATE
BALR R4,R6 /* Go to the CALCULATE and */
MAIN SR R4,R4 /* perform the routine */
.
.
.
CALCULATE EQU * /* */
.
.
BR R4 /* Return to MAIN */
Branch and Link (BAL) instruction

Format:
BAL R1,D2(X2,B2)

This Instruction is similar as the BALR instruction but instead of a register in second operand it uses a
memory location. If the second operand is 0 no branch takes place and the only action that would take
place would be to load the next instruction address into the first operand.

LA R6,CALCULATE
BAL R4,R6 /* Go to the CALCULATE and */
MAIN SR R4,R4 /* perform the routine */
.
.
.
CALCULATE EQU * /* */
.
.
BR R4 /* Return to MAIN */
4 Binary Arithmetic
There are two ways we can do arithmetic operations – Binary and Packed Decimal. In this chapter we will
discuss different instructions to perform binary arithmetic.

4.1 Add Instructions

Add (AR, A) instruction

Format:
AR R1,R2
A R1,D2(X2,B2)

The second operand is added to the first operand, and the sum is placed at the first-operand location.

Resulting Condition Code:

0 Result zero; no overflow

1 Result less than zero; no overflow
2 Result greater than zero; no overflow
3 Overflow

Example –

A DS F
B DS F
C DS H
D DS F

To add A+B+C and store in D we can write this code –

L R3,A
A R3,B
AH R3,C
ST R3,D

Add Halfword (AH) instruction

Format:
AH R1,D2(X2,B2)

The second operand is added to the first operand, and the sum is placed at the first-operand location. Second
operand is defined as halfword.

4.2 Subtract Instructions

Subtract (SR, S) instruction

Format:
SR R1,R2
S R1,D2(X2,B2)
The second operand is subtracted from the first operand, and the difference is placed at the first-operand location.

Subtract Halfword (SH) instruction

Format:
SH R1,D2(X2,B2)

The second operand is subtracted from the first operand, and the difference is placed at the first-operand location.

4.3 Multiply Instructions

Multiply (M, MR) instructions

Format:
MR R1,R2
M R1,D2(X2,B2)

The first operand is multiplied by the second operand, and the result is placed at the first-operand location. Note
that the first operand is always an even odd register pair. So that 32 bit binary integer is multiplied by 32 bit binary
integer and placed in 64-bit register pair.

If first operand is not an even register this instruction would give specification ABEND.

Example –

LA R2,0
LA R3,10
LA R5,4
MR R2,R5

After the execution of the above code value in R3 register would be 40.

The sign of the product is determined by the rules of algebra from the multiplier and multiplicand sign, except that
a zero result is always positive.

Condition Code: The code remains unchanged.

Multiply Halfword (MH) instruction

Format:
MH R1,D2(X2,B2)
nd
It works same as M or MR instructions but the 2 operand is a half word memory location.
4.4 Divide Instructions

Divide (D, DR) instructions

Format:
DR R1,R2
D R1,D2(X2,B2)

The first operand is an even-odd pair of registers (64-bit) and is divided by the second operand (32-bit), and the
result is placed at the first-operand location. After the division, remainder is placed in the even register and the
quotient is placed in odd register.

If first operand is not an even register this instruction would give specification ABEND. If divisor is zero then a
fixed-point-division exception (S0CB) is recognized.

Example –

LA R2,0
LA R3,10
LA R5,4
DR R2,R5

After the execution of the above code value in R2 register would be 2 and value in R3 would be 2.

Condition Code: The code remains unchanged.

Divide Halfword (DH) instruction

Format:
DH R1,D2(X2,B2)
nd
It works same as D or DR instructions but the 2 operand is a half word memory location.
5 Pack Decimal Arithmetic
In this chapter we will focus our discussion on “PACK DECIMAL” format. Pack Decimal format is a unique
format available only on IBM mainframes. A packed decimal representation stores two decimal digits in
one byte. A packed decimal representation stores decimal digits in each "nibble" of a byte. Each byte has
two nibbles, and each nibble is indicated by a hexadecimal digit.

Example –
Value 25  025C  Pack Decimal Format
Value -25  025D  Pack Decimal Format
Value 125  125C  Pack Decimal Format
Value 25  F2F5  Zone Decimal or Character Format
Value +25  F2C5  Zone Decimal Format
Value -25  F2D5  Zone Decimal Format

In Pack Decimal format sign is indicated by the last nibble. The C indicates a positive value, and D
indicates a negative value.

5.1 Pack (PACK) Instruction

Format:
PACK D1(L1,B1),D2(L2,B2)

The format of the second operand is changed from zoned to packed, and the result is placed at the first-
operand location.

Example –
A DC C’125’
B DS PL2
PACK B,A

F F F  ZONE

1 2 5  Numeric

1 2 5 C

After the execution of PACK instruction content of variable A would look like X‟125C‟.

5.2 Add Decimal (AP) Instruction

Format:
AP D1(L1,B1),D2(L2,B2)

The second operand is added to the first operand, and the resulting sum is placed at the first-operand
location. The operands and result are in the packed format.
 Example –
A DC P’5’
B DC P’4’
AP A,B

After the execution of AP instruction content of variable A would be 9 and it would look like X‟9C‟.

5.3 Zero and Add Pack (ZAP) Instruction

Format:
ZAP D1(L1,B1),D2(L2,B2)

The second operand is placed at the first-operand location. The operation is equivalent to an addition to
zero. The operand and result are in the packed format.

Example –
A DC P’5’
B DC P’4’
C DS PL1
ZAP C,A
AP C,B

After the execution of AP instruction content of variable C would be 9 and it would look like X‟9C‟.

5.4 Subtract Pack (SP) Instruction

Format:
SP D1(L1,B1),D2(L2,B2)

The second operand is subtracted from the first operand, and the resulting difference is placed at the first-
operand location. The operands and result are in the packed format.

Example –
A DC P’5’
B DC P’4’
C DS PL1
ZAP C,A
SP C,B

After the execution of SP instruction content of variable C would be 1 and it would look like X‟1C‟.

5.5 Multiply Pack (MP) Instruction

Format:
MP D1(L1,B1),D2(L2,B2)

The product of the first operand (the multiplicand) and the second operand (the multiplier) is placed at the
first-operand location. The operands and result are in the packed format.

 The second operand cannot exceed 15 digits (8 bytes) and must be less than the first operand
length; otherwise, a specification exception is recognized.

 The first operand must have at least as many bytes of leftmost zeros as the number of bytes in
the second operand; otherwise, a data exception is recognized. This restriction ensures that no
 product overflow occurs.

Example –

MP B,A
A DC PL2’100’  X’100C’
B DC PL4’10’  X’0000010C’  Two bytes of left most zero

After the execution of this instruction field B would have X’0001000C’

5.6 Divide Pack (DP) Instruction

Format:
DP D1(L1,B1),D2(L2,B2)

The first operand (the dividend) is divided by the second operand (the divisor). The resulting quotient and
remainder are placed at the first-operand location.

 Length of the second operand cannot exceed 8 bytes and must be less than the length of first
operand; otherwise, a specification exception is recognized.

 The quotient is placed leftmost in the first-operand location. The number of bytes in the quotient
field is equal to the difference between the dividend and divisor lengths (L1 - L2). The remainder
is placed rightmost in the first-operand location and has a length equal to the divisor length.
Together, the quotient and remainder fields occupy the entire first operand; therefore, the address
of the quotient is the address of the first operand.
 .

Example –

DP B,A
A DC PL2’100’  X’100C’
B DC PL4’10’  X’0000010C’  Two bytes of left most zero

After the execution of this instruction field B would have X’000C010C’

5.7 Compare Decimal (CP) Instruction

Format:
CP D1(L1,B1),D2(L2,B2)

The first operand is compared with the second operand, and the result is indicated in the condition code.

Example –
A DC P’5’
B DC P’4’
CP A,B
BH EXIT

Resulting Condition Code:

0 Operands equal
1 First operand low
2 First operand high
5.8 Unpack (UNPK) Instruction
Format:
UNPK D1(L1,B1),D2(L2,B2)

If we have to print a field which is in pack decimal format (e.g. – X‟125C‟), we will not be able to do that
without converting it to zone decimal (or character) format. If we do that we will get junk characters in
output. So we would need it to convert to zone decimal format. The instruction for doing so is UNPK.

Example –
A DC C’125’
B DS PL2
UNPK A,B

1 2 5 C

F F C  ZONE

1 2 5  Numeric

nd
After the execution of UNPK instruction pack decimal value of 2 operand is converted to zone decimal
nd
format. That is each digit in 2 operand is supplied with an „F‟ in their zone except the last digit which is
nd
supplied with the sign nibble of 2 operand.

After each UNPK instruction we also have to make sure that the last character of first operand becomes a
valid character –

OI A+2,X’F0’

F F C  ZONE

1 2 5  Numeric

0
=====================================

F F F  ZONE

1 2 5  Numeric
5.9 Other important pack decimal Instructions -

Convert to Decimal (CVD) instruction

Format:
CVD R1,D2(X2,B2)

The first operand is a register having binary values is changed to decimal, and the result is stored at the second-
operand location.

Example –

A DS PL8
LA R1,100
CVD R1,A

After the execution of above instruction field A would have X‟00 00 00 00 00 00 10 0C‟.

Convert to Binary (CVB) instruction

Format:
CVB R1,D2(X2,B2)

The second operand is changed from decimal to binary, and the result is placed at the first-operand Register.

Example –

A DC PL8’125’
CVB R1,A

After the execution of above instruction register R1 would have X‟00 00 00 00 00 00 00 7D‟.

EDIT (ED) instruction

EDIT and MARK (EDMK) instruction

Shift and Round Pack (SRP) instruction

6 Assembler Macros for Datasets
There are two ways we can do arithmetic operations – Binary and Packed Decimal. In this chapter we will
discuss different instructions to perform binary arithmetic.

6.1 DCB--Construct a Data Control Block (QSAM)

The data control block for a queued sequential access method (QSAM) data set is constructed during
assembly of the problem program. You must code DSORG and MACRF in the DCB macro, but the other
DCB parameters can be supplied to the data control block from other sources. Each DCB parameter
description contains a heading, "Source." The information under this heading describes the sources that
can supply the parameter. Each reference to a DCB OPEN exit routine applies also to a JFCBE exit
routine.

You can assemble the DCB macro into a program that resides above the 16 MB line, but the program
must move it below the line before using it. Except for the DCBE, all areas that the DCB refers to, such as
EXLST and EODAD, must be below the 16 MB line.

The format of the DCB macro for QSAM is:

[label] DCB [BFALN={F|D}]

[,BFTEK={S|A}]
[,BLKSIZE=absexp]
[,BUFCB=relexp]
[,BUFL=absexp]
[,BUFNO=absexp]
[,BUFOFF={absexp|L}]
[,DCBE=relexp] (1)
[,DDNAME=symbol] (1)
[,DEVD={{DA}
{TA
[,DEN={1|2|3|4}]
[,TRTCH={C|E|ET|T}|{COMP|NOCOMP}]}
{PR
[,PRTSP={0|1|2|3}]}
{PC
[,MODE=[C|E][R]]
[,STACK={1|2}]
[,FUNC={I|P|PW[XT]|R|RP[D]|
RW[T]|RWP[XT][D]|W[T]}]}
{RD
[,MODE=[C|E][O|R]]
[,STACK={1|2}]
[,FUNC={I|P|PW[XT]|R|RP[D]|
RW[T]|RWP[XT][D]|W[T]}]}}]
,DSORG={PS|PSU}
[,EODAD=relexp]
[,EROPT={ACC|SKP|ABE}]
[,EXLST=relexp]
[,LRECL={absexp|X|0K|nnnnnK}]
,MACRF={{(G{M|L|D}[C])}
{(P{M|L|D}[C])}
{(G{M|L|D}[C],P{M|L|D}[C])}}
 [,OPTCD={{B}
{T}
{U[C]}
{C[T][B][U]}
{H[Z][B]}
{J[C][U]}
{W[C][T][B][U]}
{Z[C][T][B][U]}
{Q[C][B][T]}]
{Z}}]
[,RECFM={{U[T][A|M]}
{V[B][S][T][A|M]}
{D[B][S][A]}
{F[B|S|T|BS|BT][A|M]}}]
[,SYNAD=relexp]

Example -

MYFILE DCB LRECL=80,RECFM=F,MACRF=G,EODAD=ATENDTCH,

DDNAME='MYFILE'

LRECL={absexp|X|0K|nnnnnK}
Specifies the length, in bytes, for fixed-length records. Or, it specifies the maximum length, in bytes, for
variable-length or undefined-length (output only) records. The value specified in LRECL cannot exceed
the value specified in BLKSIZE except when variable-length spanned records are used.

Unblocked fixed-length records: the value specified in LRECL must be equal to the value specified in
BLKSIZE.

Blocked fixed-length records: The value specified in LRECL must be evenly divisible into the value
specified in BLKSIZE. LRECL is required for blocked fixed-length records.

Variable-length records: the value specified in LRECL must include the maximum data length (up to
32752 bytes) plus 4 bytes for the record-descriptor word (RDW).

DDNAME=symbol
Specify the name that is used to identify the JCL data definition (DD) statement that defines the data set
being allocated or processed.

Source: DDNAME can be supplied in the DCB macro or by the problem program before an OPEN macro
is issued to open the data set.

DSORG={PS|PSU}
Specifies the data set organization and whether the data set contains any location-dependent information
that makes it unmovable. You can specify:
PS
specifies a physical sequential data set.
PSU
specifies a physical sequential data set containing location-dependent information that makes it
unmovable.

EODAD=relexp
 Specifies the address of the routine given control when the end of an input data set is reached. Control is
given to this routine when a GET macro is issued and there are no additional records to be retrieved.

If the end of the data set is reached but no EODAD address was supplied to the data control block (DCB)
or DCBE, or if a GET macro is issued after an end-of-data exit is taken, the task is abnormally terminated.

MACRF={{(G{M|L|D}[C])}
{(P{M|L|D}[C])}}
{(G{M|L|D}[C],P{M|L|D}[C])}}

Specifies the type of macros (GET, PUT or PUTX, CNTRL, RELSE, and TRUNC) and the transmittal
modes (move, locate, and data) that are used with the data set being created or processed. The
parameter can be coded in any of the combinations shown above. You can specify:
C

specifies that the CNTRL macro is used with the data set. If you specify C, the device must be one of
these described in "CNTRL--Control Directly Allocated Input/output Device (BSAM and QSAM)" in topic
2.2.10. The CNTRL option can be specified with GET in the move mode only. Use of the CNTRL macro is
invalid for 3525 input data sets.
D

specifies that the data transmittal mode is used (only the data portion of a record is moved to or from the
work area). Data mode is used only with variable-length spanned records.
G

specifies that GET macros are used. Specifying G also provides the routines that allow the problem
program to issue RELSE macros. G is required if the OPEN option is INPUT or UPDAT. It has no effect if
the OPEN option is OUTPUT or EXTEND.
L

specifies that the locate transmittal mode is used; the system provides the address of the buffer
containing the data.
M

specifies that the move transmittal mode is used; the system moves the data from the buffer to the work
area in the problem program.
P

specifies that PUT or PUTX macros are used. Specifying P also provides the routines that allow the
problem program to issue TRUNC macros. P is required if the OPEN option is OUTPUT or EXTEND. It
has no effect if the OPEN option is INPUT. P may be specified if the OPEN option is UPDAT.
Rule: For data sets processed by QSAM using MACRF=(GM) or MACRF=(PM), do not code BFTEK=A.

Source: MACRF can be supplied only in the DCB macro.

6.2 OPEN—Connect program and data.

Use the OPEN macro to open a data set.

 The format of the OPEN macro is:

+------------------------------------------------------------------------+
| [label] | OPEN | (address[, [(options)][,...]]) |
| | | [,MODE={24|31}] |
+------------------------------------------------------------------------+

Address:
Specifies the address of the ACB or DCB for the data sets being opened. You may specify the
address either in register notation (using a register from 2 through 12, in parentheses) or with an
expression that generates a valid relocatable A-type address constant. If you use register notation to
open one data set, enclose the expression identifying the register within two sets of parentheses:
OPEN ((2)).

options
specifies options parameters used only in opening non-VSAM data sets.
VSAM ignores options specified with the address of an access method
control block.

Because the OPEN parameters are positional, if options are not

specified, you must insert a comma before coding a subsequent
parameter.

6.3 Get – Obtain next logical record

The GET macro retrieves (reads) the next record. Various modes are available and are specified in the
DCB macro.

The format of the GET macro is:

+------------------------------------------------------------------------+
| [label] | GET | {dcb address|pdab address} |
| | | [,area address] |
| | | [,TYPE=P] |
+------------------------------------------------------------------------+

Example –

GET MYFILE,MYREC

6.4 Put – Write a record

Use the PUT macro to write (load) records to an empty data set, and insert or update records into an
existing data set.

The format of the PUT macro is:

+------------------------------------------------------------------------+
| [label] | PUT | dcb address |
| | | [,area address] |
+------------------------------------------------------------------------+
Example –

PUT MYFILE,MYREC
PUT MYFILE,HEADER1
Appendix - List of Instructions
Instruction Mnemonic Hex Format
Add A 5A R1,D2(X2,B2)
Add Halfword AH 4A R1,D2(X2,B2)
Add Logical AL 5E R1,D2(X2,B2)
Add Logical Registers ALR 1E R1,R2
Add Packed (Decimal) AP FA D1(L1,B1),D2(L2,B2)
Add Registers AR 1A R1,R2
Branch and Link BAL 45 R1,D2(X2,B2)
Branch and Link Register BALR 05 R1,R2
Branch and Save BAS 4D R1,D2(X2,B2)
Branch and Save Register BASM 0D R1,R2
Branch, Save and Set Mode BASSM 0C R1,R2
Branch on Condition BC 47 M1,D2(X2,B2)
Branch on Condition Register BCR 07 M1,R2
Branch on Count BCT 46 R1,D2((X2,B2)
Branch on Count Register BCTR 06 R1,R2
Branch and Set Mode BSM 0B R1,R2
Branch on Index High BXH 86 R1,R3,D2(B2)
Branch on Index Low/Equal BXLE 87 R1,R3,D2(B2)
Compare C 59 R1,D2(X2,B2)
Compare Double and Swap CDS BB R1,R3,D29B2)
Compare Halfword CH 49 R1,D2(X2,B2)
Compare Logical CL 55 R1,D2(X2,B2)
Compare Logical Characters CLC D5 D1(L,B1),D2(B2)
Compare Logical Characters Long CLCL 0F R1,R2
Compare Logical Immediate CLI 95 D1(B1),I2
Compare Logical under Mask CLM BD R1,M3,D2(B2)
Compare Logical Registers CLR 15 R1,R2
Compare Packed (Decimal) CP F9 D1(L1,B1),D2(L2,B2)
Compare Registers CR 19 R1,R2
Compare and Swap CS BA R1,R3,D2(B2)
Convert to Binary CVB 4F R1,D2((X2,B2)
Convert to Decimal CVD 4E R1,D2((X2,B2)
Divide D 5D R1,D2((X2,B2)
Divide Packed (Decimal) DP FD D1(L1,B1),D2(L2,B2)
Divide Registers DR 1D R1,R2
Edit ED DE D1(L1,B1),D2(B2)
Edit and Mark EDMK DF D1(L1,B1),D2(B2)
Execute EX 44 R1,D2(X2,B2)
Insert Character IC 43 R1,D2(X2,B2)
Insert Character under Mask ICM BF R1,M3,D2(B2)
Load L 58 R1,D2(X2,B2)
Load Address LA 41 R1,D2(X2,B2)
Load Complement Registers LCR 13 R1,R2
Load Halfword LH 48 R1,D2(X2,B2)
Load Multiple LM 98 R1,R3,D2(B2)
Load Negative LNR 11 R1,R2
Load Postive LPR 10 R1,R2
Load Register LR 18 R1,R2
Load and Test Register LTR 12 R1,R2
Multipy M 5C R1,D2(X2,B2)
Multipy Halfword MH 4C R1,D2(X2,B2)
Multipy Packed (Decimal) MP FC D1(L1,B1),D2(L2,B2)
Multipy Registers MR 1C R1,R2
Move Characters MVC D2 D1(L,B1),D2(B2)
Move Inverse MVCIN E8 D1(L,B1),D2(B2)
Move Characters Long MVCL 0E R1,R2
Move Immediate MVI 92 D1(B1),I2
Move Numerics MVN D1 D1(L,B1),D2(B2)
Move with Offset MVO F1 D1(L1,B1),D2(L2,B2)
Move Zones MVZ D3 D1(L,B1),D2(B2)
aNd N 54 R1,D2(X2,B2)
aNd Characters NC D4 D1(L,B1),D2(B2)
aNd Immediate NI 94 D1(B1),I2
aNd Registers NR 14 R1,R2
Or O 56 R1,D2(X2,B2)
Or Characters OC D6 D1(L,B1),D2(B2)
Or Immediate OI 96 D1(B1),I2
Or Registers OR 16 R1,R2
Pack PACK F2 D1(L1,B1),D2(L2,B2)
Subtract S 5B R1,D2(X2,B2)
Subtract Halfword SH 4B R1,D2(X2,B2)
Subtract Logical SL 5F R1,D2(X2,B2)
Shift Left Single SLA 8B R1,D2(B2)
Shift Left Double SLDA 8F R1,D2(B2)
Shift Left Double Logical SLDL 8D R1,D2(B2)
Shift Left Single Logical SLL 89 R1,D2(B2)
Subtract Logical Registers SLR 1F R1,R2
Subtract Packed (Decimal) SP FB D1(L1,B1),D2(L2,B2)
Subtract Registers SR 1B R1,R2
Shift Right Single SRA 8A R1,D2(B2)
Shift Right Double SRDA 8E R1,D2(B2)
Shift Right Double Logical SRDL 8C R1,D2(B2)
Shift Right Single Logical SRL 88 R1,D2(B2)
Shift and Round Decimal SRP F0 D1(L1,B1),D2(B2),I3
Store ST 50 R1,D2(X2,B2)
Store Character STC 42 R1,D2(X2,B2)
Store Character under Mask STCM BE R1,M3,D2(B2)
Store Halfword STH 40 R1,D2(X2,B2)
Store Multiple STM 90 R1,R3,D2(B2)
Supervisor Call SVC 0A I1
Test under Mask TM 91 D1(B1),I2
Translate TR DC D1(L1,B1),D2(B2)
Translate and Test TRT DD D1(L1,B1),D2(B2)
Unpack UNPK F3 D1(L1,B1),D2(L2,B2)
eXclusive Or X 57 R1,D2(X2,B2)
eXclusive Or Characters XC D7 D1(L,B1),D2(B2)
eXclusive Or Immediate XI 97 D1(B1),I2
eXclusive Or Registers XR 17 R1,R2
Zero Add Packed ZAP F8 D1(L1,B1),D2(L2,B2)
Sources

Principal of Operations

DFSMS Macro Instructions for Data Sets