Mainframe S390 Assembler Programming
For the brave warriors left to defend the crown.
For the brave warriors left to defend the crown.
›› Introduction to Assembler programming
Index
Throughout this page code fragments will be in light blue boxes like the one below. This is pre formated code and you should be able to copy and paste the code exactly as it appears into your programs.
Code fragments
Assembler instructions follow standard formats. The instruction format references will be provided in orange boxed as the example below.
Instruction format
D1(L,B1),S2
For the most part assembler programs is coded in a free format. Assembler coders over time have discovered this free format will be impossible to maintain later on and has come up with a convention to have some standard for developing code.
The current convention is as follows:
The following rules have to be followed:
Comments start with a *. Anything beyond the * will be considered comments.
The label value has naming restrictions. The length use to be limited to 8 characters but these days it can
be up to 63 bytes long. The label have to start with a alphabetic letter or one of these special characters $, @ or #.
It may contain numeric data after these rules has been followed.
Beyond these rules anything goes.
Labels will be used in your program by the assembler during your assembly process to determine the implicit address for this storage area. If you did not code a label you would have to define a base and displacement address for every storage element you want to use. Using the base and displacement method of accessing storage is called the explicit address.
Base and displacement addressing
When you write programs in assembler 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 the base address. Later when we talk about linkage conventions you will see certain registers would not make good base register choices.
Relative from this base register you use a displacement to get through your program. The displacement value is stored in a 12 bit area. The maximum value that can be stored in 12 bits is a range from 0 to is 4095. With a single base register you can address a program with a length of 4095. If the program gets larger then this size you will have to allocate multiple base registers. We will discuss multiple base registers in later sections.
Some instructions also allow you to specify a index value in addition to the displacement. This value need to be placed in a register and this register becomes the index register. The effective address is the index value, the displacement and base register content added together. Once again you can not use register 0 as the index register. If you use register 0 as the index or base it would act like you omitted these values.
You can use the BALR instruction to load a base register. This instruction will be discussed in more detail later as it does much more that load base registers.
After you load a value into a register you need to tell the assembler
to use this register as a base. You do this using the USING assembler directive.
Here is an example:
BEGIN CSECT
BALR 12,0 /* Load address of SR into */
USING BEGIN,12 /* register 12 and tell the */
SR 5,5 /* assembler to use this as */
/* the base address */
The BALR instruction loads the next instruction to be executed into the location counter. It then branches to the address specified. By using register 0 in the BALR instruction we effectively did not branch anywhere causing the next instruction address to be loaded into register 12. USING isn't an machine instruction and as such the next instruction was SR. USING told the assembler to start using register 12 as the base address.
Every program that executes in the system has certain responsibilities when it starts and right before it finished. These tasks is 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 will be provided to you in register 13.
The person giving up control to you have loaded register 13 with this address.
You are doing this because many people 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 save area for registers.
This area has to be 18 fullwords in length.
BEGIN CSECT
STM 14,12,12(13) /* */
BALR 12,0 /* */
USING ENTRY,12 /* */
BASE ST 13,SAVE+4 /* */
LA 13,SAVE /* */
.
.
.
SAVE DS 18F /* */
STM saves register 14 to register 12 in the address register 13 points too plus 12 bytes. This sounds strange to go from 14 to 12. Remeber this will wrap so 14, 15, 1, 2 etc. We then load the address of the next instruction into register 12. Our SAVE area address plus 4 gets stored into register 13 and we load the address of our SAVE area into resister 13. Load the address of our SAVE area into register 13 to allow the next person who gets control to save our register in our SAVE area.
After this is done we have the registers from the program who gave up control for us to run saved in the area he provided for this in register 13. We loaded our base register into register 12 and we are ready to start our program.
At the end of your program you have to do some work too. You need to restore some registers to allow someone else to get control again.
Here is a standard termination sample piece of code:
L 13,SAVE+4 /* */
LM 14,12,12(13) /* */
BCR X'F',14 /* */
.
.
.
SAVE DS 18F /* */
We are doing the reverse from the entry logic. First we load the address stored in our SAVE area + 4 into register 13. We then load register 14 to 12 from the storage area starting 12 bytes from the address in register 13. BCR branches unconditionally to the address in register 14. Register 14 now contains the return address for the program who gave control up for us to execute. It just so happen register 14 was the return address to the guy who gave up control to us. This was no surprise because this is part of the linkage convention rules.
Normal register conventions are register 13 points to your register save area. Register 14 points to the address of the next instruction to execute in your program. Register 0 and 1 is used to pass parameters between calling and sub programs. Register 15 gets loaded with the entry address to your program.
You program will mostly consist of instructions and data. These elements will cause the instruction locater during assembly time to be incremented every time the assembler passes over them. In addition to these elements you can also code directives to instruct or help the assembler. These are called assembler directives and they do not move the location counter. A good example was the USING directive you already saw in the previous sections. Even though USING was between BALR and the next instruction the BALR did not load the address of the USING directive but it loaded the address of the instruction following USING.
USING directive
USING S,R
This directive tells the assembler to use the address in R as a base register and assume this register contains the address for storage area S. At assembly this this register will not contain any value and you have to load this value at execution time. In our sample we used the BALR instruction to do this. Notice this directive had no label.
EQU directive
symbol EQU expression
Example1:
R12 EQU 12
R13 EQU 13
R14 EQU 14
L R13,SAVE+4 /* */
LM R14,R12,12(R13) /* */
BCR X'F',R14 /* */
Example2:
DATA DS 0F
NAME DS CL20
LASTNAME DS CL20
LENGTH EQU *-DATA /* Length from beginning of */
/* storage area to current */
/* address is calculated and */
/* stored in LENGTH */
The EQU allows you to define symbols. In example 1 we made the program easier to read by defining symbols where registers will be used. In example 2 we has the assembler calculate the length of the DATA area for us and we stored this value into LENGTH.
CSECT directive
The CSECT marks the beginning of your program. CSECT means control section. The programs you write initially will only have one control section but advanced programs could have many CSECTs.
symbol CSECT Example1: PROGRAM1 CSECT /* Beginning of PROGRAM1 */
END directive
The END directive signals the end of a CSECT or control section. The relocatable value is the address of the first instruction to execute and usually match the symbol of the CSECT name.
END relocatable expression
Example1:
PROGRAM1 CSECT /* Beginning of PROGRAM1 */
.
.
.
END PROGRAM1
Instructions can be categorized in under these 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 does 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 does 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 a index register. If you do not use a 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 instructions 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 instructions and occupy 6 bytes. 3 different formats of this instruction type can be used.
Format 1:
mnemonic D1,(L,B1),(D2,B2)
+--------+-------+-------+---+---+---+---+---+---+
| op-code| L-1 | B1| D1| D1| D1| B2| D2| D2| D2| 6 bytes
+--------+-------+-------+---+---+---+---+---+---+
0 8 16 24 32 40 47
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
Format 3:
mnemonic D1,(L1,B1),D2(B2),M3
+--------+----+----+-------+---+---+---+---+---+---+
| op-code|L1-1| M3 | B1| D1| D1| D1| B2| D2| D2| D2| 6 bytes
+--------+----+----+-------+---+---+---+---+---+---+
0 8 16 24 32 40 47
FORMAT 1
The first format move data from one storage area to another. Notice the first operand contains a length value. This is the amount of data that would be involved in this instruction.
The length value is 8 bits long and contain maximum 256 or data from 0 to 255.
The displacement values both contain 12 bits and can store a value up to 4095.
FORMAT 2
In format 2 the length area need to be shared between L1 and L2. This implies a maximum value of 15 x'F' can be stored in these areas. The rest of this instruction is the same as format 1.
FORMAT 3
Format 3 is very different. It has a M3 value following the L1 value and is 4 bits in length witch only allow a value of 15 to be stored in it.
Pay attention to the location of where the length value are in the instructions. It always start in the second byte. Later we will see instructions where we use the execute EX instruction to modify this byte to dynamically alter the length of the instruction to suite our needs.
These 6 instruction formats for the bases for all the instructions we will be covering. Make sure to understand them well as it will be of great value during you assembler coding career.
Links