Elizabeth Joseph, Camillo Sassano, and the IBM Industrial Design Program provided an STL file for the z15 you see above. My son, Bret, printed this one.
Check out Fans of IBM z and consider joining.
Category Archives: IBM Mainframe Assembler
Introduction to VSAM for Assembler Programmers: Part 2
I’ve added a second video as part of the introduction to VSAM for Assembler Programmers. You can find the first and second videos, as well as the related Powerpoints in the Video Course . Many thanks to Melvyn Maltz for generously making suggestions and pointing out corrections. I’ll add Part 3 soon.
Filed under IBM Mainframe Assembler, VSAM
How to Print a Register
A friend of mine, Melvyn Maltz, was amused by some code I wrote recently. The code simply printed out the contents of a register, and I took a quick and dirty approach: Store the register in a buffer, use PUT to print the buffer, SET HEX ON. It’s a technique I often use when debugging on a mainframe. I should tell you that my friend is an expert in most things IBM – a master programmer. He’s also generous enough to read or watch some of the material on this site and offer suggestions. In any case, the code amused him, and he reminded me that it’s not that hard to print a register – and it’s instructive. I realized I had never written about how to print a hexadecimal representation of a register (or small field) on this site, so I’ll do that now. It involves TR and UNPK.
Let’s start with UNPK which treats each byte of the sending field (except the last) the same. UNPK separates the zone and numeric parts of each byte (dare I call them nibbles?) into two bytes after appending a hexadecimal F on the front of each nibble, like this:
| B 3 |
/ \
| F B| F 3 |A moment’s thought here is instructive. The 3 is converted to x’F3’, which is exactly what we need to print it in a character format. The same would be true for all digits 0-9. The treatment given to B doesn’t work so well. The same bad treatment would occur for digits A-F. So, bytes x’FA’, x’FB’, … x’FF’ would have to be repaired after applying UNPK. Can we fix those? Yes. TR can do the trick.
So, the basic idea is to use UNPK followed by TR. What about that last byte that UNPK converts by simply flipping the nibbles? We can avoid that problem by adding a byte (logically or physically) to the field we are unpacking. Problem solved.
What about the TR table? What does that look like? My friend might suggest this,
HEXTABLE DC C’0123456789ABCDEF’How do we get away without defining a 256-byte table? The solution leverages the fact that we are only translating a narrow range of sequential values: x’F0’ – x’FF’ – every byte we need to translate begins with x’F’. We can pretend to have created a 256-byte table by coding TR this way (assuming the register we want to print is R5):
ST R5,FWRD
UNPK HEXAREAX,FWRDX
TR HEXAREA,HEXTABLE-240
…
DS 0F ALIGNMENT
FWRDX DS 0CL5
FWRD DS F
DC X'00' AN EXTRA BYTE FOR UNPK
HEXAREAX DS 0CL9 8 HEX DIGITS+1 IN CHARACTER
HEXAREA DS CL8 8 HEX DIGITS IN CHARACTER
DC X'00' AN EXTRA BYTE FOR UNPK
We can do this, confident that the first 240 bytes of our fictitious table will never be referenced by TR. (240 is the offset to a character 0). After translation, HEXAREA contains the result. Variations of this technique use explicit lengths and leaving off an extra byte. The only drawback to the technique is that the relative address HEXTABLE-240 may generate an addressability error if it references an address that is smaller than the base register address. This rarely happens.
My friend may get another chuckle out of this, but I’m going to suggest a second solution that uses a 256-byte table:
HEXTABLE DC 256AL1(*-HEXTABLE) NEUTRAL TABLE
ORG HEXTABLE+X'FA' FIX X'FA' THROUGH X'FF'
DC C'ABCDEF'
ORG ,
The rest of the solution is similar and looks like this:
ST R5,FWRD
UNPK HEXAREAX,FWRDX UNPK SLIGHTLY LARGER FIELDS
TR HEXAREA,HEXTABLE TRANSLATE THE SMALLER FIELD
…
DS 0F ALIGNMENT
FWRDX DS 0CL5
FWRD DS F
DC X'00' AN EXTRA BYTE FOR UNPK
HEXAREAX DS 0CL9 8 HEX DIGITS+1 IN CHARACTER FORMAT
HEXAREA DS CL8 8 HEX DIGITS IN CHARACTER FORMAT
DC X'00' AN EXTRA BYTE FOR UNPK
After executing the first three lines above, HEXAREA will contain a printable version of register 5.
This leads into how we can print larger areas of memory in a hexadecimal format. There’s always the old standby: SNAP. Melvyn sent a nice example of TROT, but I’ll save that gem for another post.
Filed under IBM Mainframe Assembler
New Video: Introduction to VSAM for Assembler Programmers
Here is a shoutout to Ravi Cheepa for suggesting I needed to add some VSAM material to the site. I’ll start with this video that contains some basic information about VSAM and its macros: ACB, RPL, EXLST, PUT, GET, MODCB, …
I’ve always thought that looking at code is the best way for programmers to learn, so I’ll follow this up with a series of demo programs that do something interesting and efficiently. I’ll also add some video to explain the programs and why the techniques they use are efficient. More soon …
Filed under IBM Mainframe Assembler
New Video: External DSECTS – Q-cons, CXDs, and DXDs
Q-cons, CXDs, and DXDs enlist the help of the Binder to make it easy for you to allocate storage dynamically for all your CSECTS. They also widen the possibilities for how you can design multi-CSECT programs. Some companies use these ideas to promote the separation of storage and code. In any case, this is an interesting HLASM path to explore.
I’ve created a video to explain these ideas and a sample program listed below that you can use as skeleton code for further exploration.
PRINT ON,NODATA,NOGEN
**********************************************************************
********************** STORAGE FOR ASECT ****************************
**********************************************************************
ASTOR DSECT
A1 DS CL80 SOME VARIABLES FOR ASECT
A2 DS CL30
A3 DS CL5
A4 DS PL10
A5 DS 200CL5
SAVEA DS 18F AREA FOR MY CALLEE TO SAVE & RESTORE MY REGS
**********************************************************************
********************** STORAGE FOR PARMS ****************************
**********************************************************************
PARMSECT DSECT
X DS CL80
Y DS CL80
Z DS CL80
**********************************************************************
********************** ASECT CONTROL SECTION ***********************
**********************************************************************
ASECT CSECT
ASECT AMODE 31
ASECT RMODE 24
********************** ENTRY LOGIC *********************************
STM 14,12,12(R13) SAVE CALLER'S REGS
BASR R12,0 ESTABLISH
USING *,R12 ADDRESSABILITY
L R8,EDSLEN GRAB LENGTH OF STORAGE NEEDED
STORAGE OBTAIN,LENGTH=(R8),ADDR=(R11)
LR R10,R11 GRAB ADDRESS FOR ALL STORAGE
A R10,ASECTO ADD OFFSET FOR MY DSECT
USING ASTOR,R10 I HAVE ADDRESSABILITY
ST R13,SAVEA+4 BACK-CHAIN CALLER'S FROM MINE
LA R13,SAVEA POINT TO MY LOWER-LEVEL SA
********************** BEGIN LOGIC *********************************
OPEN (FILEOUT,(OUTPUT))
PUT FILEOUT,=CL80'ENTERING PROGASECT'
LR R9,R11 POINT AT DYNAMIC STORAGE
A R9,PARMO ADD THE OFFSET FOR PARMS
USING PARMSECT,R9 I HAVE ADDRESSABILITY
MVC X,=CL80'THIS IS PARM X' INITIALIZE ...
MVC Y,=CL80'THIS IS PARM Y' ... PARMS
MVC Z,=CL80'THIS IS PARM Z'
LA R1,=A(FILEOUT,PARMO) PASS THE DCB AND PARMO
L R15,=A(BSECT) CALLING BSECT
BASR R14,R15 BRANCH THERE
PUT FILEOUT,=CL80'RETURNED TO PROGA1'
LR R9,R11 POINT AT ALLOCATED STORAGE
A R9,XXXAO ADD THE OFFSET TO XXX
PUT FILEOUT,0(R9) R9 POINTS AT XXX
CLOSE FILEOUT
STORAGE RELEASE,LENGTH=(R8),ADDR=(R11)
*********************** STARDARD EXIT ********************************
RETURN EQU * BRANCH TO HERE FOR NORMAL RETURN
L R13,SAVEA+4 POINT TO CALLER'S SAVE AREA
LM R14,R12,12(R13) RESTORE CALLER'S REGS
LA R15,0 SET RETURN CODE REG 15 = 0
BR R14
****************** LOCAL DATA AREAS ********************************
FILEOUT DCB DSORG=PS, X
MACRF=(PM), X
DEVD=DA, X
DDNAME=FILEOUT, X
RECFM=FB, X
LRECL=80
ASECTO DC Q(ASTOR) OFFSET TO ASTOR
PARMO DC Q(PARMSECT) OFFSET TO PARMSECT
XXX DXD CL80 DECLARATION OF XXX IN EDS
XXXAO DC Q(XXX) OFFSET TO XXX
EDSLEN CXD FULLWORD TOTAL SPACE NEEDED
LTORG
YREGS
**********************************************************************
********************** STORAGE FOR BSECT ****************************
**********************************************************************
BSTOR DSECT
B1 DS F THE STORAGE AREAS NEEDED IN BSECT
B2 DS CL20
B3 DS PL5
B4 DS CL100
B5 DS CL5
SAVEB DS 18F BSECT SAVE AREA
**********************************************************************
********************** BSECT CONTROL SECTION ***********************
**********************************************************************
BSECT CSECT
STM 14,12,12(R13) SAVE CALLER'S REGS
BASR R12,0 ESTABLISH
USING *,R12 ADDRESSABILITY
LR R10,R11 SET UP...
A R10,BSECTO ... ADDRESSABILITY FOR BSECT
USING BSTOR,R10 I HAVE STORAGE ADDRESSABILITY
LR R9,R11 POINT AT ALLOCATED MEMORY
L R6,4(R0,R1) R6 POINTS AT PARMO
A R9,0(R0,R6) ADD THE OFFSET FOR PARMS
USING PARMSECT,R9 I HAVE PARM ADDRESSABILITY
ST R13,SAVEB+4
LA R13,SAVEB
********************** BEGIN LOGIC *********************************
L R5,0(R0,R1) R5 POINTS AT MY RECOUT DCB
PUT (R5),=CL80'ENTERED BSECT'
PUT (R5),X PRINT THE PARMS
PUT (R5),Y
PUT (R5),Z
*
* USE BSTOR FIELDS CAN BE USED HERE
*
MVC B4,=CL80'THIS IS B4 DATA'
PUT (R5),B4
*
* PREPARE TO USE XXX
*
LR R9,R11 POINT AT XDS WITH R9
A R9,XXXBO ADD THE OFFSET TO XXX
MVC 0(80,R9),=CL80'XXX IN ASECT WAS CHANGED IN BSECT'
*
PUT (R5),=CL80'ABOUT TO LEAVE BSECT'
*********************** STARDARD EXIT ********************************
L R13,SAVEB+4 STANDARD EXIT CODE
LM R14,R12,12(R13)
BR R14
************* INITIALIZED DATA AREAS AND PARMS ***********************
BSECTO DS Q(BSTOR) OFFSET FOR BSECT STORAGE
XXXBO DC Q(XXX) OFFSET TO XXX
LTORG
END ASECTFiled under IBM Mainframe Assembler
New Video: Using COM Control Sections
I’ve recently added a video that covers COM control sections – an old idea that’s interesting to try. If your program consists of multiple CSECTs, you can create a COM section – an uninitialized storage area that becomes part of the object module – and which can be shared selectively among the CSECTs that comprise the program. You can find the video here and some sample code to play with here. There’s also links to these items in the Video Course.
Filed under IBM Mainframe Assembler
Links Updated
I’ve updated the links to a few html pages that used Flash to reference mp4 files. If you have any trouble playing video from my site, send me the link and I’ll repair it.
Filed under IBM Mainframe Assembler
Updating the Site
Evidently, I have a number of pages on the site that invoke a Flash player that is no longer supported in most browsers. I am working to repair this problem as quickly as possible. I apologize for the inconvenience.
Filed under IBM Mainframe Assembler
Don’t Have Mainframe Access? Try This
If you want to learn IBM mainframe assembly language but don’t have access to an IBM System/z machine, there is an excellent alternative: Z390 Portable Mainframe Assembler and Emulator. (Even if you do have access, you can find it helpful.) This product has a long, successful history, is freely distributed, and runs on Windows, Linux, and Mac PC’s. It also supports all the instructions described in the Principles of Operation manual of October, 2019 – very impressive!
I asked Don Higgins, the creator, to write a short article about his product. Here it is.
Z390 Portable Mainframe Assembler and Emulator Overview
Don Higgins
November 20, 2020
Z390 is an open-source, Java-based mainframe assembler and emulator designed to run on Windows, Linux, and Mac PC’s. The predecessor to z390 was the PC/370 shareware mainframe assembler and emulator for MS-DOS PC’s. PC/370 was used by thousands of students at universities in the 1980s. In 1993 I sold PC/370 to Micro Focus, and in 1995 I went to work for Micro Focus developing the assembler component of the Micro Focus Mainframe Express product for Windows PCs. In 2004 I left Micro Focus and started the z390 open source project.
The original goal of z390 was to assemble, link, and execute problem state application programs on any platform that supports Java runtime. Over the years, the following major features have been added to z390:
- Macro process and assembler compatible with HLASM
- Linker to create executable modules
- Emulator with the following support:
- Problem state instruction execution
- Trace and dump options
- Floating-point, including HFP, BFP, and DFP.
- Storage management including GETMAIN and FREEMAIN
- QSAM, BDAM, and VSAM file management
- Sort merge utility
- zCOBOL compiler which generates z390 assembler
- zCICS transaction support developed by Melvyn Maltz
- Graphical User Interface
In 2012, I retired from z390 development for a while. Abe Kornelis and Melvyn Maltz continued to develop z390. In 2020 I returned and have spent most of 2020 upgrading the z390 assembler to correctly assemble all the IBM mainframe instructions in the Principles of Operation manual published in Oct. 2019. A test program named ZOPCHECK was developed to verify all 2357 opcode, mnemonic, and operand combinations.
References:
Filed under IBM Mainframe Assembler
z/OS Training at Marist College Enrolling Now
Marist College through the Institute of Data Center Professionals (IDCP) offers a variety of mainframe-based courses and professional z/OS certificates all online. Working jointly with IBM, these worldwide programs were designed to educate personnel who are entering the field as well as those with experience in z/OS and a variety of application programming tracks including COBOL, DB2 and Assembler language.
If you are looking for specialized mainframe training online, look no further. Fall classes start August 31, 2020. Here is the best link for the program: https://conta.cc/30UErq3e
For a number of years I’ve taught the two-course assembler sequence for Marist to people located around the globe. The course evolves each year and I take pride in adding new topics and videos each time I teach it. I’d love to work with you individually to master IBM Assembly language in a small-group asynchronous online setting. Together, we will work through a sequence of on-target programming assignments. At the end, you’ll have the necessary skills to begin working as an assembler programmer. But don’t wait, classes are starting soon.
Filed under IBM DB2, IBM Enterprise Cobol, IBM Mainframe Assembler
