Learn IBM370 Assembly Programming... For Mainframe Madness!

Don't like to read? you can learn while you watch and listen instead!

Every Lesson in this series has a matching YOUTUBE video... with commentary and practical examples

Visit the authors Youtube channel, or Click the icons to the right when you see them to watch the Lessons video!

You may have a computer in your phone, but once upon a time computers weren't so small!

The IBM System 370 was the successor to the 360 and was a room sized computer.

You can forget your Mouse, HD Display and SD card, the 370 read it input from punched cards, and sent its output to a printer and terminal monitor!

Fortunately thanks to modern computing, we can emulate a System 370 machine with the Hercules emulator, so we won't need a small warehouse for our cpu tower!

The IBM360
(I can't find a 370 photo on wikipedia!)

A printout from a compile job.

Documentation:

Reference Card

Assembler manual

JCL Manual - Job Control Language is used to send ASM files to the server for assembly and execution

Useful Links:

Hercules Emulator

OS Setup

Minimal ASM Example - See: Compile/Assemble and Execute

Bit Order!

Because IBM hate us and want us to suffer, the official documents refer to the leftmost bit of a 32 bit value as bit 0 - on any other CPU it would usually be considered bit 31. We'll use the more common convention in these tutorials.

We'll specify LSB and MSB to be clear... LSB 0 will be the rightmost bit... MSB 31 will be the leftmost

IBM Documentation written by drunk madmen Bit 31 is Least significant rightmost bit Bit 0 is Most significant leftmost bit	Bit: 0.1.2.........29.30.31 MSB --------- LSB
Everyone else in the entire world ever Bit 0 is Least significant rightmost bit Bit 31 is Most significant leftmost bit	Bit: 31.30.29.........2.1.0 MSB --------- LSB

	Most Significant Bts																Least Significant Bits
Normal	31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
Power PC	0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20	21	22	23	24	25	26	27	28	29	30	31
Bit Value	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	512	256	128	64	32	16	8	4	2	1

Registers

The CPU has 16 32 bit registers (R0-R15 / AKA 1-15)

Register	Details (suggested purpose)
R0	Subroutine Parameter / Hardwired Zero with addressing commands
R1	Subroutine Parameter / Parameter List
R2	Sometimes a Subroutine Parameter
R3
R4
R5
R6
R7
R8
R9
R10
R11
R12
R13	Save Area for subroutines (like a stack)
R14	Return Address
R15	Entry point register

Some are used by the OS, however Registers R2 - R11 are free for your use.

There is no stack, but R13 is used as a pointer to a 'Save Area' to back up or restore registers during a sub

PSW

The PSW is the 64 bit Program Status Word

IBM Bit	0	1	2-4	5	6	7	8-11	12	13	14	15	16-17	18-19	20	21	22	23	24-31	32	33-63
	System Mask													Program Mask						PC
Purpose	0	peR mask	0	daT mode	IO mask	EXtern -al Mask	PSW Key	Type	Machine check mask	Wait state	Problem state	Address Space control	Condition Code	Fixed Point Overflw	Decimal Overflw	Exponent Underflw	Signific ance	0	Address -ing Mode	Instruction Address
Normal Bit	63	62	59-61	58	57	56	55-52	41	50	49	48	47-46	45-44	43	42	41	40	39-32	31	30-0

Addressing

Format	Addressing Mode	Syntax	Meaning
RR	Register	R1,R2	R1=Destination Register R2=Register
RX	Base Index Displacement	R1,D2(X2,B2)	R1=Destination Register D2=Displacement (12 bit - UNSIGNED) X2=Index Reg (R0=none) B2=Base (R0=none)
SI	Immediate	D1(B1),I2	D1=Displacement (12 bit - UNSIGNED) B1=Base Register I2=Immediate (8 bit)
RS	Register , Base Displacement	R1,R2,D2(B2)	R2=Register 2 D2=Displacement (12 bit - UNSIGNED) B2=Base Register
SS #1	Sized (One Length)	D1(L,B1),D2(B2)	D1=Displacement (12 bit - UNSIGNED) B1=Base Register L=Length (8 bit) D2=Displacement (12 bit - UNSIGNED) B2=Base Register
SS #2	Sized (Two Lengths)	D1(L1,B1),D2(L2,B2)	D1=Displacement (12 bit - UNSIGNED) L1=Length (4 bit) B1=Base Register D2=Displacement (12 bit - UNSIGNED) L2=Length (4 bit) B2=Base Register

Source column and data type

Punched cards are 80 chars wide.

0........1.........2.........3.........4.........5.........

6.........7.........8

12345678901234567890123456789012345678901234567890123456789012345678901234567890

NAME     OP   
                  OPERANDS

                           USING
                  *,12          
                           I am a comment

                           WTO  'I am a
                  really really long line, Im so long I
                  need       -

                     
                            
                  two lines cos Im so awesome'

Free format is somewhat flexible, but in Fixed format the column position defines the purpose:

Column	Purpose
1-8	Name (Label)
10-14	Operation
16+	Operands
16	Continuation of last line
40+	Remarks
71	End of code
72	Continue indication (72) - any char here defines multiline Next line starts from Column 16

Notes

CNOP b,w - Align to byte B of word/doubleword W - eg CNOP 0,4 will align to a 32 bit boundary, CNOP 0,8 will align to 64 bit.

LTORG - Literal pool... Immedates cannot be used, so the assembler automatically puts them here when we use =

CSECT = Control Section - Regular code

DSECT = Dummy Section - Define symbols for a structure with no output code

* in ASM source = current line Address

0.........1.........2.........3.........4.........5.........

6.........7.........8

123456789012345678901234567890123456789012345678901234567890123456789012345678900

DOMSG EQU *

Will set DOMSG to the current address (like a label)

To Define reg numbers as Rxx use:

R0       EQU   0
R1       EQU   1
R2       EQU   2

and so on

Comment can use a full line starting with a * at char position 1 (Far left)

11111111112222222222333333333344444444445555555555666666666677777777778888888888

12345678901234567890123456789012345678901234567890123456789012345678901234567890

* I am a comment

Labels should be 8 chars max

everything should be UPPERCASE!

Save and Return for subs

(equivalent of stack)

SAVE (14,12) ;Back up ALL Regs 14-15, 0-12 to Save area at (13)

RETURN (14,12) ;Restore all Regs and return to address in reg 14

Two values are a range, with wrap around if A is higher than B, so (14,12) means 14,15,0,1,2,3,4,5,6,7,8,9,10,11,12 (everything but 13!)

Save area should be 18 words (72 bytes)

The command when the command "STM 14,12,12(13)" is seen 12(13) skips 12 bytes from the address in 13, This is because the first 3 words are reserved by the OS for the previous save area and other things.

Values

Character	Purpose	Notes	Example
B	Binary		`DC B'11110000' Value &F0`
C	Character	Character in EBDIC... not ASCII!	`DC C'ABC' Value &C1,&C2,&C3 (EBDIC)`
L	Length	Get the length of a value (or command line)	`TEST BR R3 Two byte command DC A(L'TEST) Defined as 00002`
X	Hexadecimal		`DC X'FF' Value 255`
=	Immediate In LORG pool	Define value at LTORG, and put pointer in code	`L R1,=X'FF' This will point to the LTORG section LTORG A Value of 255 will be put here`
H	Halfword	16 bit Value	`DC H'256' Value &0100`
F	FullWord	32 bit Value	DC F'256' `Value &00000100`
L	Literal	Fixed Literal {Repeat}{Type}L{Total} Type {Type} is defined, padded to {Total} and duplicated {Repeat} times	`DC 4CL3'A'` `Value &C14040,&C14040,&C14040`

EBDIC

Ascii is too boring for the IBM 370 - so it uses EBDIC!... OK actually EBDIC is designed to be convenient for punched cards.

NUL

SOH

STX

ETX

SEL

RNL

DEL

SPS

RPT

DLE

DC1

DC2

DC3

RES/ENP

POC

CAN

UBS

CU1

IFS

IGS

IRS

IUS/ITB

SOS

WUS

BYP/INP

ETB

ESC

SFE

SM/SW

CSP

MFA

ENQ

ACK

BEL

SYN

TRN

NBS

EOT

SBS

RFF

CU3

DC4

NAK

SUB

(

)

;

[

]

{

}

SVCs

SVC Number	Macro
0	EXCP XDAP
1	PRTOV WAIT WAITR
2	POST
3	EXIT
4	GETMAIN (TYPE 1) (get storage below 16 megabytes - with R operand)
5	FREEMAIN (TYPE 1)
6	LINK LINKX
7	XCTL XCTLX
8	LOAD
9	DELETE
10	FREEMAIN (free storage below 16 megabytes) GETMAIN (get storage below 16 megabytes - with R operand)
11	TIME
12	SYNCH SYNCHX
13	ABEND
14	SPIE
15	ERREXCP
16	PURGE
17	RESTORE
18	BLDL (TYPE D) FIND (TYPE D)
19	OPEN
20	CLOSE
21	STOW
22	OPEN (TYPE = J)
23	CLOSE (TYPE = T)
24	DEVTYPE
25	TRKBAL
26	CATALOG INDEX LOCATE
27	OBTAIN
28	Reserved
29	SCRATCH
30	RENAME
31	FEOV
32	REALLOC
33	IOHALT
34	MGCR/MGCRE QEDIT
35	WTO WTOR
36	WTL
37	SEGLD SEGWT
38	Reserved
39	LABEL
40	EXTRACT
41	IDENTIFY
42	ATTACH ATTACHX
43	CIRB
44	CHAP
45	OVLYBRCH
46	STIMERM(CANCEL OPTION) STIMERM(TEST OPTION) TTIMER
47	STIMER STIMERM(SET OPTION)
48	DEQ
49	Reserved
50	Reserved
51	SDUMP SDUMPX SNAP SNAPX
52	RESTART
53	RELEX
54	DISABLE
55	EOV
56	ENQ RESERVE
57	FREEDBUF
58	RELBUF REQBUF
59	OLTEP
60	ESTAE STAE
61	No macro
62	DETACH
63	CHKPT
64	RDJFCB
65	Reserved
66	BTAMTEST
67	Reserved
68	SYNADAF SYNADRLS
69	BSP
70	GSERV
71	ASGNBFR BUFINQ RLSEBFR
72	No macro
73	SPAR
74	DAR
75	DQUEUE
76	No macro
77	Reserved
78	LSPACE
79	STATUS
80	Reserved
81	SETDEV SETPRT
82	Reserved
83	SMFEWTM,BRANCH=NO SMFWTM
84	GRAPHICS
85	No macro
86	ATLAS (obsolete)
87	DOM
88	Reserved
89	Reserved
90	Reserved
91	VOLSTAT
92	TCBEXCP
93	TGET TPG TPUT
94	GTDEVSIZ GTSIZE GTTERM STATTN STAUTOCP STAUTOLN STBREAK STCC STCLEAR STCOM STFSMODE STLINENO STSIZE STTMPMD STTRAN TCLEARQ
95	SYSEVENT
96	STAX
97	No macro
98	PROTECT
99	DYNALLOC
100	No macro
101	QTIP
102	AQCTL
103	XLATE
104	TOPCTL
105	IMGLIB
106	Reserved
107	MODESET
108	Reserved
109	ESPIE IFAUSAGE MFDATA(RMF™) MFSTART(RMF) MSGDISP OUTADD OUTDEL
110	Reserved
111	No Macro
112	PGRLSE
113	PGANY PGFIX PGFREE PGLOAD PGOUT
114	EXCPVR
115	Reserved
116	CALLDISP CHNGNTRY IECTATNR IECTCHGA IECTRDTI RESETPL
117	DEBCHK
118	Reserved
119	TESTAUTH
120	FREEMAIN (free storage above 16 megabytes - TYPE 1) GETMAIN (get storage above 16 megabytes - TYPE 1) operand
121	No Macro (for VSAM)
122	EVENTS(TYPE 2) Extended LINK Extended LOAD Extended XCTL LINK - Extended LINK LOAD - Extended LOAD Service Processor Call STIMERE VALIDATE
123	PURGEDQ
124	TPIO
125	EVENTS(TYPE 1)
126	Reserved
127	Reserved
128	Reserved
129	Reserved
130	RACHECK
131	RACINIT
132	RACLIST
133	RACDEF
134	Reserved
135	Reserved
136	Reserved
137	ESR(TYPE 6)
138	PGSER
139	CVAF CVAFDIR CVAFDSM CVAFSEQ CVAFVOL CVAFVRF
143	CIPHER EMK(TYPE 4) GENKEY RETKEY
144	No macro
145	Reserved
146	BPESVC

JCL - Job Control Language

Command	Format	Example	Purpose
JOB	//{Jobname} JOB ({Account num}) {operands} {comments}	`//ASMFCLG JOB (001),'ASM HELLO WORLD', // CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),REGION=128K`	Job
EXEC	//{Stepname} EXEC {program} {operands} {comments}	`//HELLO EXEC ASMFCLG`	Execute
DD	//{dd name} DD {operands} {comments}	`//ASM.SYSUT1 DD UNIT=SYSDA`	Data Deefinition
PROC	//{name} PROC {operands} {comments}	`//DEF PROC STATUS=OLD,LIBRARY=SYSLIB,NUMBER=777777`	Procedure
PEND	//{name} PEND {comments}	`// PEND`	Procedure End
	/* //*	/* I am a comment	Comment

JOB:
Class = Time slicing class (A=Default) PRTY = Priority
MSGCLASS = Output class (A-z / 0-9)
MSGLEVEL= (statements,messages) .... 1,1 = output all
Region= Memory to allocate in 1024 byte blocks (eg 128K)

DD:

* = Prompt for input (//ddname DD *)
UNIT = device / group containing data set