z390 Support in VisibleZ

I envisioned VisibleZ as a teaching tool for assembly language – I wanted to force students to deal with object code as a way to learn the assembly language. With VisibleZ, after writing a few bytes of object code, you can watch the effects of a given instruction on the state of the machine, and in the process learn a thing or two.  Or, you can simply step through the hundreds of pre-written program snippets that comes with it.  I’ve tried to make it easy to write program snippets – two hex characters represent a byte, with bytes separated by spaces – all in a text file. No need to write a large program to get some experience with an instruction.

A few months ago, James Cray, one of the contributors to  z390, the Portable Assembler and Emulator Project , suggested it would be nice to be able to load z390 object modules into VisibleZ.  If you’re not familiar with that project, and you don’t have access to a mainframe, you should check it out.  Using z390 you can write large, well-developed assembler programs and run them on your pc.  It also supports Cobol and CICS!

I didn’t want to want to change my original file format, but I decided to take James’ advice by providing some support for z390.  I’ve just posted an experimental version (executable jar / codes.zip -code snippets) of VisibleZ that will take the assembler listings produced by z390 and scrape off the object code and format it it to run in VisibleZ.  You will have to install z390 separately and tell VisibleZ where it lives on your machine.  After that you can assemble a program and run your program, all within VisibleZ.

The experimental version runs on Windows only.  If there is any interest in getting this to run on Linux, let me know.  I’ll remind you that VisibleZ still has limited support for QSAM files – 80 byte records and a limit of three input and three output files.


Filed under IBM Mainframe Assembler

Why you should be using LAY

The ability to load an address in assembler is a powerful tool. Working with an object from a distance (Load Address) rather than directly (Load) gives us the power of pointers and opens up the possibility of creating data structures. LA, an RX instruction, was the traditional instruction for working with addresses. LAY, an RXY-a instruction, offers some advantages over LA that you should consider. Read about the differences in these instructions here.

Leave a comment

Filed under IBM Mainframe Assembler

Revising the lectures

I’m in the process of revising lecture videos and notes for the entire site. The beginning videos (Starting Assembler 1 and 2) are now revisions of older ones that correct typos, misspeakings, etc., and include some new material on System/z. I’ve also added a third video that walks through the architectural components mentioned in the first two videos using VisibleZ as a demonstration tool – a good introduction for beginners.


Filed under IBM Mainframe Assembler

Techniques for Converting From Binary to Packed-Decimal

If you are generating a binary result in a register and converting the result back to packed-decimal, you need to be keenly aware of the limitations of each of these data types. For large binary values, you will need some conversion techniques that aren’t found in Principles of Operation. This article discusses several approaches for converting double-precision binary back to packed-decimal.

Leave a comment

Filed under IBM Mainframe Assembler

VZ Update 5/23/2016

This update in VisualZ corrects a flaw in the packed decimal arithmetic instructions that occurred when using large values.  You should also download codes.zip which includes many new packed decimal test programs.  To get the latest versions, click the Download VZ tab on the homepage.

Leave a comment

Filed under IBM Mainframe Assembler

VisualZ Update 5/17/2016

I’ve updated the RunnerB.jar file for VisualZ.  Replacing your copy of RunnerB.jar with this one will give you the most up-to-date version of VisibleZ.   This update fixes a problem with condition code settings that occurred in some cases for A, AH, S, and SH.  This version also includes many new immediate arithmetic instructions.   LARL was also added to the instruction set.  You should also download codes.zip, upzip it, and replace your Codes directory with this one.  The new Codes directory contains sample programs for each of the new instructions that was added.

Leave a comment

Filed under IBM Mainframe Assembler

Visual Prompts for Grande Arithmetic

Can’t remember all the details of the Divide Single Grande Fullword Register instruction (DSGFR)?  Not sure of the set up for Multiply Single (MS)?  Consulting Principles of Operation for the umpteenth time today?  You can quickly learn (or review) 21 grande arithmetic instructions using the visual clues I’ve provided on four new pages (pdf). Check out the pages below and leave the POPS manual for the hard stuff.

Additionally, I’ve added a video to explain the visual clue sheets and exactly how these instructions work:

All of these items have been added to the video course.

Leave a comment

Filed under IBM Mainframe Assembler

Jumping Into Branches

Are you bewildered by the plethora of branch instructions in assembly language?  Perhaps you’re wondering what all that jumping around is about?  Not sure when to choose JNE over BNE or BC?  This new paper addresses those issues and a few more you might find helpful.  I’ll give you my own take on how to decide when to jump and when to branch.  You might also learn a new way to load base registers, get a grip on relative branching, or improve your understanding of addressability.  Click here for the pdf and jump in!

Leave a comment

Filed under IBM Mainframe Assembler

Elegant Machine Code:

“The Happy Mainframe” or “WWzD: What Would z Do?”

I am happy to welcome David Staudacher, who begins a series of blogs about solving problems with elegant, succinct assembler code – code that System z itself would write (if it could).  David has been writing Mainframe code in Assembler and COBOL for over 35 years,  in both vendor software and business application environments.  He is currently employed with the State Employees’ Credit Union of North Carolina  and co-manages the “Mainframe Assembler Professionals” and  “Mainframe [COBOL, etc] Experts” Groups on LinkedIn.

Problem: Read Error on Newly Allocated, Empty Sequential Disk Files


//SYSIN    DD *

NEWFL       00      4
REPRO       12     24

IEC141I 013-34,IGG0191I,,,INFILE

http://publibz.boulder.ibm.com/cgi-bin/bookmgr_OS390/BOOKS/IEA2M7C0/3.70 – IEC141I

Basically, there’s no EOF mark and no DCB information in the DSCB because the file was never OPENed for Output, even though RECFM and LRECL were specified in the JCL.

Essential Solution: A program to use with file allocation (rather than IEFBR14), sufficient just to Open and Close the file, thus creating a valid and usable DSCB.

Using this OPEN/CLOSE program instead of IEFBR14 …

// EXEC PGM=PSINIT “PSINIT” = (P)hysical (S)equential (INIT)ialization
//SYSIN    DD *

… now everything is hunky-dory:

NEWFL       00      9
REPRO       00     26

This is an excellent opportunity to “make the Mainframe happy” with some “elegant machine code” written in Assembler!

The essential solution can be accomplished with as little as one DCB, six machine instructions and a fullword aligned 4-byte Parameter List (DCB pointer with option bits in the high-order byte):


Note: The DCB here specifies “MACRF=W”, which makes this a BSAM DCB.

A QSAM DCB (MACRF=PM or PL) would work just as well, but since we only need OPEN and CLOSE, simple BSAM works just fine.

The DDNAME parameter (here = “NEWFILE”) must also match the DDNAME used in the JCL.

(2)    The fullword-aligned Parameter List (in 4 contiguous bytes) is:

  • Fullword Alignment: DC 0F’0’
  • Option Bits:  DC X’8F’ (see “Bit Settings for OPEN (SVC 19) and Bit settings for CLOSE (SVC 20)” below for bit meanings)
  • DCB Pointer: DC AL3(DCB)From “MVS Diagnosis Reference” (GA22-7588), the relevant option byte bit settings for the necessary OPEN (SVC 19) and CLOSE (SVC 20) in this case are:
    Bit Settings for OPEN (SVC 19) Bit Settings for CLOSE (SVC 20)
    1... .... = Last entry indicator
    .... 1111 = OUTPUT
    1... .... = Last entry indicator

    Notice how there is no overlap using these particular bit settings.   Thus, the same Parameter List can be used forboth OPEN and CLOSE.

(3)    The Six Machine Instructions are:

  1.   X’4120bddd’– Load R2 with the Address of the Parameter List (’bddd’is the Base+Displacement Parameter List address, determined at assembly time).Note: Loading R1 would be sufficient, but subsequent SVC 19 modifies R1 so the less volatile R2 is used instead so address can be easily reloaded for CLOSE (SVC 20).
  2. X’1812’ – Load R1 with address of required Parameter List for SVC 19 (OPEN).
  3. X’0A13’ – Issue SVC 19 (OPEN).
  4. X’1812’ – Reload R1 with address of required Parameter List for SVC 20 (CLOSE).
  5. X’0A14’ – Issue SVC 20 (CLOSE).
  6. X’07FE’ – BR 14

This solution, unlike most written in so-called “high level” languages,  will work with any sequential disk file, of any valid record length and any Record Format.

Specific and essential DCB information, like RECFM, LRECL and BLKSIZE, are obtained via JCL and SMS defaults rather than hardcoded in the program.  Nice!

Here’s the Assembly ready code then, exactly as the machine might write it, with:

(1)    A “USING” on R15 (R15 = Base) since the machine “knows” R15 contains the Entry address at runtime.

(2)    A label “PLIST” on the Parameter List, giving the displacement so the address can be calculated at runtime.

(3)    A label “DCB” on the DCB, so “AL3(DCB)” will contain the DCB address at runtime.

       USING PSINIT,15     R15 = BASE
       LA     2,PLIST      R2 -> PARMLIST
       LR     1,2          R1 -> PARMLIST
       SVC    19           ISSUE OPEN SVC
       LR     1,2          R1 -> PARMLIST
       SVC    20           ISSUE CLOSE DCB
       BR     14           RETURN
PLIST  DC     0F’0’,X'8F',AL3(DCB)

Knowing the machine code generated by the “MF=E” forms of the OPEN and CLOSE macros, and the “MF=L” form of OPEN, the Assembly code can be simplified even further to just 9 statements…

       USING PSINIT,15    R15 = BASE
       LA    2,PLIST      R2 -> PARMLIST
       OPEN  MF=(E,(2))   OPEN FILE
       CLOSE MF=(E,(2))   CLOSE FILE
       BR    14           RETURN
       END   PSINIT

… which generate exactly the same load module.

– “OPEN MF=(E,(2))” generates “LR 1,2” and “SVC 19”.

– “CLOSE MF=(E,(2))” generates “LR 1,2” and “SVC 20”.

– “OPEN MF=L,(DCB,OUTPUT)” generates “DC 0F’0’”, “AL1(143)” and “AL3(DCB)”.  (note: “AL1(143)” = “X'8F'”)

NEXT: The same solution using AMODE 31 with an external DCB module, loaded dynamically at runtime.


Leave a comment

Filed under IBM Mainframe Assembler

Joe Goes Small (< 4k)

Joe Developer had an astute comment about “Lots of Code on One Base Register” when he reminded me that lots of long programs have been written that use one base register, and without resorting to relative branches. By modularizing the program into sections of < 4k, you can write as much code as you like on one base register. There are some real benefits in his reminders. When designing programs, small is always a beautiful way to think. I thought it might be helpful to have an example program that illustrates the ideas. I’ve placed a copy of it here.
At 13k+, you have to admit it’s relatively long for a program that doesn’t do much of anything. I threw in a few odds and ends to illustrate some related ideas and concepts that might be of interest to someone learning assembler. Let me point out a few:

  1. The program is one source module organized into four control sections.
  2. Each control section can call the others. In this case, MAIN1 calls SUBR1 and SUBR2, and SUBR2 calls SUBR3.
  3. MAIN1 uses the CALL macro and passes parameters.
  4. SUBR2 invokes SUBR3 and passes parameters without using a CALL.
  5. SUBR1 illustrates passing parameters by content and by reference.
  6. MAIN1 passes a DCB which is used in SUBR1.
  7. Each routine is < 4k and uses standard linkage techniques (save and restore registers in save areas, parameter passing).
  8. Each routine uses a single base register.
  9. Each routine avoids the use of relative branching (although this would be fine, too).
  10. We could easily add more routines and make this arbitrarily large.
  11. Passing large amounts of data could be handled with different techniques.

There are other ways to write large programs and perhaps Joe had a different idea in mind, but I think this is close to what he was driving at.  And as Joe points out, 4k is not much of a constraint in most cases.  You can write a lot of assembler code in a 4k space – plenty of room for most well-designed modules.

Leave a comment

Filed under IBM Mainframe Assembler