Learn IBM Assemb;y Lsnhushr
Videos and word documents that cover how to program in IBM mainframe assembler language.
Stumped by a S0C1? S0C4? S0C7? Master dump reading with this series of videos that cover dump reading basics.
The series of debugging sessions will cover various abends. The first video starts with some helpful suggestions for debugging a S0C1. Along the way, you’ll also learn some debugging principles that apply to any kind of dump reading you need to do. Here is the video. Let’s get started!
The IF macro can be paired with an ELSEIF companion macro to build a simple case statement. In the code below, DAY is a one-byte character field containing a single digit representing a day of the week (1 = Sunday, 2 = Monday, …). We use the DAY field to build DAYO, a character version of the day. We combine this logic with an OR in the final condition to catch Saturday and Sunday.
LOOP EQU *
IF (CLC,DAY,EQ,=C'2')
MVC DAYO,=CL9'MONDAY'
ELSEIF (CLC,DAY,EQ,=C'3')
MVC DAYO,=CL9'TUESDAY'
ELSEIF (CLC,DAY,EQ,=C'4')
MVC DAYO,=CL9'WEDNESDAY'
ELSEIF (CLC,DAY,EQ,=C'5')
MVC DAYO,=CL9'THURSDAY'
ELSEIF (CLC,DAY,EQ,=C'6')
MVC DAYO,=CL9'FRIDAY'
ELSEIF (CLC,DAY,EQ,=C'1'),OR,(CLC,DAY,EQ,=C'7')
MVC DAYO,=CL9'WEEKEND'
ENDIF
PUT FILEOUT1,RECOUT PRINT THE RECORD
GET FILEIN1,RECIN GET THE NEXT RECORD
B LOOP GO BACK AND PROCESS
Here’s a simple case statement using the HLASM structured CASE macro. Register 4 is selected (your choice not = 0) and l0 is loaded into R4. The contents of the register are used to select the correct case. In this case, “Fall” is MVC-ed to the SEASON field. More complex CASE examples will be the subject of future posts.
LA R4,10
CASENTRY R4
CASE 12,1,2
MVC SEASON,=CL6’WINTER’
CASE 3,4,5
MVC SEASON,=CL6’SPRING’
CASE 6,7,8
MVC SEASON,=CL6’SUMMER’
CASE 9,10,11
MVC SEASON,=CL6’FALL’
ENDCASE
PUT FILEOUT,RECOUT
Build a while loop using the structured assembler Do macro. Here is the relevant code:
DO WHILE=(CP,X,LT,=P'10')
AP X,=P'1'
MVC XOUT,EDWD
ED XOUT,X
PUT FILEOUT1,RECOUT
ENDDO
The test at the top of the loop compares X with a packed decimal 10 and enters the loop if X is less than 10. Sweet! Here’s the complete program that makes it work:
//CSUP004A JOB (ASSY),'WOOLBRIGHT',CLASS=A,MSGCLASS=A,
// NOTIFY=&SYSUID,MSGLEVEL=(1,1)
//ASM EXEC PROC=HLASMCLG
//C.SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
// DD DSN=HLA.SASMMAC2,DISP=SHR
//SYSIN DD *
COPY ASMMSP
TITLE 'SKELETON ASSEMBLER PROGRAM'
PRINT ON,DATA,NOGEN
******************************************************************
* *
* PROGRAMMER: WOOLBRIGHT *
* COMMENTS : ASM SKELETON PROGRAM *
* *
******************************************************************
* *
* REGISTER EQUATES *
* *
******************************************************************
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
******************************************************************
* *
* SYMBOLIC EQUATES *
* *
******************************************************************
MACRO3 CSECT STANDARD ENTRY CODE
STM R14,R12,12(R13)
BASR R12,R0 ESTABLISH...
USING *,R12 ADDRESSABILITY
ST R13,SAVEAREA+4 BACKWARD CHAIN CALLER
LA R13,SAVEAREA ADDRESS OF MY SAVE AREA
******************************************************************
* BEGIN THE PROGRAM LOGIC. FIRST OPEN THE OUTPUT FILE
******************************************************************
OPEN (FILEOUT1,(OUTPUT))
ZAP X,=P'0'
LOOP EQU *
DO WHILE=(CP,X,LT,=P'10')
AP X,=P'1'
MVC XOUT,EDWD
ED XOUT,X
PUT FILEOUT1,RECOUT
ENDDO
EXIT EQU *
CLOSE (FILEOUT1)
L R13,SAVEAREA+4 POINT AT OLD SAVE AREA
LM R14,R12,12(R13) RESTORE THE REGISTERS
LA R15,0 RETURN CODE = 0
BR R14 RETURN TO OPERATING SYSTEM
******************************************************************
* *
* OUTPUT FILE - DATA CONTROL BLOCK *
* *
******************************************************************
DC X'FFFFFFFF'
FILEOUT1 DCB DSORG=PS, X
MACRF=(PM), X
DEVD=DA, X
DDNAME=FILEOUT1, X
RECFM=FB, X
LRECL=80
******************************************************************
*
* OUTPUT RECORD AREA
*
******************************************************************
RECOUT DS 0CL80 PRINT AREA
DC CL10' '
XOUT DS CL5
DC CL65' '
EDWD DC X'4020212060'
X DS PL2
******************************************************************
*
* REGISTER SAVE AREA
*
******************************************************************
SAVEAREA DS 18F
******************************************************************
*
* LITERAL POOL
*
******************************************************************
LTORG *
END MACRO3
/*
//G.SYSABOUT DD SYSOUT=*
//G.SYSUDUMP DD SYSOUT=*
//G.FILEOUT1 DD SYSOUT=*
//
The structured programming macros in HLASM are just too sweet to ignore. Make your programming life easier by adopting them. The SELECT statement works like Java’s SWITCH except the default behavior is to exit each case automatically (no pesky BREAKs) – just as God intended. The code below examines a two-byte character field that contains a 01 for January, 02 for February, …, 12 for December. The code substitutes a character version of the month in the output. Notice how clean the code looks compared to what we would write in native assembler.
SELECT CLC,MONTHIN,EQ
WHEN =C'01'
MVC MNTHOUT,=CL9'JANUARY'
WHEN =C'02'
MVC MNTHOUT,=CL9'FEBRUARY'
WHEN =C'03'
MVC MNTHOUT,=CL9'MARCH'
WHEN =C'04'
MVC MNTHOUT,=CL9'APRIL'
WHEN =C'05'
MVC MNTHOUT,=CL9'MAY'
WHEN =C'06'
MVC MNTHOUT,=CL9'JUNE'
WHEN =C'07'
MVC MNTHOUT,=CL9'JULY'
WHEN =C'08'
MVC MNTHOUT,=CL9'AUGUST'
WHEN =C'09'
MVC MNTHOUT,=CL9'SEPTEMBER'
WHEN =C'10'
MVC MNTHOUT,=CL9'OCTOBER'
WHEN =C'11'
MVC MNTHOUT,=CL9'NOVEMBER'
WHEN =C'12'
MVC MNTHOUT,=CL9'DECEMBER'
OTHRWISE
MVC MNTHOUT,=CL9'UNKNOWN'
ENDSEL
Just so you can see the difference, here is part of the generated code, which would be similar to the code we would write without the macro:
SELECT CLC,MONTHIN,EQ
WHEN =C'01'
+ CLC MONTHIN,=C'01'
+ BC 7,#@LB2
MVC MNTHOUT,=CL9'JANUARY'
WHEN =C'02'
+ BC 15,#@LB1 SKIP TO END
+#@LB2 DC 0H
+ CLC MONTHIN,=C'02'
+ BC 7,#@LB4
MVC MNTHOUT,=CL9'FEBRUARY'
WHEN =C'03'
+ BC 15,#@LB1 SKIP TO END
+#@LB4 DC 0H
+ CLC MONTHIN,=C'03'
+ BC 7,#@LB6
MVC MNTHOUT,=CL9'MARCH'
WHEN =C'04'
+ BC 15,#@LB1 SKIP TO END
Which is easier to debug and understand?
Back in the 70′s many thoughtful computer scientists weighed in on a now-dead issue of the GoTo statement in high-level languages. The issue seems to be pretty much settled now, with many new languages avoiding GoTo altogether, and high-level programmers avoiding their use except in very specialized circumstances. But assembler programmers depend on branch statements (conditional and unconditional) as a required part of any program logic. We can’t avoid coding Branch statements, so the goal is to use them in a reasonably straightforward way, avoiding spaghetti logic. Good assembler programmers do this intuitively after a while, but IBM has included some high-level macros that make the job even easier now. The macros are distributed in the HLASM Toolkit. The macros are stored in a library called hlg.SASMMAC2 (where hlq is a high-level qualifier that varies from system to system). If your system has the toolkit, include the macro library in your SYSLIB for the compile. On my system, the JCL looks like this:
//C.SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
// DD DSN=HLA.SASMMAC2,DISP=SHR
In the next few postings, we will look at the macros that are available. In this first note, we look at three macros that support if-statements: If, ELSE, and ENDIF.
The IF statement comes in a variety of formats, but I especially like the format below:
IF (CLC,X,LT,Y)
MVC SMALLER,X
MVC LARGER,Y
ELSE
MVC SMALLER,Y
MVC LARGER,X
ENDIF
The predicate in the If statement has four parts:
1) A compare instruction mnemonic (like CLC or CP)
2) The operand 1 field
3) A condition parameter (H – high, GT -greater than, L – low, LT – less than, E or EQ – equal)
4) The operand 2 field
Like if-statements in high-level languages, the true block occurs between the IF and the ELSE, and the false block occurs after the ELSE and before the ENDIF.
When the macros are assembled, the required branch statements and labels are inserted. IF statements can be nested and used in conjuction with other structured macros, just as you would hope for.
Examine the generated code by coding PRINT ON,NODATA,GEN just before the if statement, and PRINT ON,NODATA, NOGEN just after the ENDIF.
Give the IF statement a try – you’ll like it.
I used a good chunk of December organizing all the assembler materials I created over the years into a book format. I’ve been writing new material, updating the old to include System/z, and incorporating VisibleZ into the activities that accompany each chapter. I’ll use the book with my assembler class this year and try to get it into shape. Here’s the table of contents:
Chapter 1 Starting Assembler
In which we connect to the machine, learn to navigate the operating system, submit a job, and examine the output.
Chapter 2 Do You Zee What I Zee?
In which we examine the machine components that affect the programs we write.
Chapter 3 A First Program
In which we look at a complete program, discuss each and every component, and generally try to get the hang of what an assembler program contains.
. Chapter 4 How System/z Works
In which we examine how the machine finds a data field, become familiar with five kinds of instructions formats, and pay some attention to what the machine does all day long.
Chapter 5 Character Study
In which we examine the instructions that can be used to read, move, compare and print character data.
Chapter 6 File It Under I Or O
In which we learn to read and write records.
Chapter 7 Slowly I Turn …
In which we learn how to go from here to there and back again.
Chapter 8 Packing It In
In which we learn to add, subtract, multiply, and divide decimal data.
Chapter 9 Bin There, Done That!
In which we learn to add, subtract, multiply and divide binary data.
Chapter 10 Assembler for Dummies
In which we learn that working with dummies can be the smart thing to do.
Chapter 11 Calling All Programs
In which we learn how one program can call another.
Chapter 12 Bit By Bit
In which we examine some of the instructions that manipulate bits.
Chapter 13 Exotic Locales
In which we examine some of the more powerful instructions and explore some of the darker corners of the Assembler landscape.
Chapter 14 Exit Pursued By A Bear
In which we examine how to write exit routines.
Appendix 1 Arithmetic Conversions: Decimal, Binary, Hexadecimal
In which we learn to do conversions with a pencil and our brain.
Appendix 2 Two’s Complement Arithmetic
In which we figure out how a sequence of 1’s and 0’s can be negative
The book will be available this spring.
I’m also in the process of converting all the materials on the website to PDF format. New PDF links will gradually replace the old links to Word documents as I’m able to get to it.
Happy New Year!
Start learning the basics of decimal arithmetic in assembler by tackling how to add and subtract in packed decimal. This video will get you started on the road to mastering the arithmetic every assembler programmer needs to know.
I’ve added a link to all the video lessons on assembler topics at the top of the home page. I’ll be adding more lessons over the next few months. The material will be enough to get you started with all the basic skills of a journeyman programming in HLASM.
Assembly language won’t make much sense until you get a grip on the USING directive and the associated terms: Domain and Range. You can hear a lesson about this here. When things go wrong with USING directives, the result is an addressability error – usually lots of them! This video lesson, recorded in a real mainframe session, can make Addressability errors a snap.