Planet MVS Planet MVS Dave's unofficial HLASM web page Dave's z/Architecture Assembler FAQ

Dave's z/Architecture Assembler FAQ

Do you have any assembler programming style suggestions?




Should I code everything in Assembler?


Assembler is a lot of fun, but consider REXX or some other tool if:
  • It's not a system exit
  • Performance isn't critical
  • It doesn't invoke any API's (or programming interfaces) only available to assembler
You'll have more time to code things that really should be done in assembler. Case in point is my ISPF to 3270 datastream assembler program that didn't really need to be written in assembler (but then again, REXX wasn't available back then).



Are there any PC-based S/390 assemblers?


Yes, here are the ones I know about:

Non-Commerical products
z390 portable mainframe macro assembler and emulator. The z390 macro assembler, linker, and emulator toolkit provides a way to develop, test, and deploy mainframe compatible assembler programs using any computer that supports the Sun Microsystems Java J2SE 1.5.0 runtime. The entire toolkit is distributed in both Java source and executable form under the open source GPL license.
Assembly and execution
ASSIST (copy hosted by Northern Illinois University). ASSIST (Assembler System for Student Instruction and Systems Teaching) is an IBM System/370-compatible assembler/interpreter developed in the 1970s at Penn State University. Originally, ASSIST was available only to universities and was implemented at over one hundred of them. In 1998, Penn State declared that ASSIST was no longer copyrighted and that the program was freely available.
Assembly and execution
PC/370 v4.2 IBM 370 assembler and emulator This link is to a ZIP file which was last updated in 1991. This package was written by Donald S. Higgins and has been turned it into a product sold by Micro Focus.
Assembly and execution
Commerical products
Micro Focus Mainframe Express "To support applications that need to access mainframe assembler routines, an assembler run-time facility is now embedded in Mainframe Express."
Assembly and execution
SimoX390 SimoX390 is a mainframe Assembler Analysis Tool. This tool is provided to assist in the initial evaluation phase of offloading, maintaining, developing, and/or testing of mainframe assembler programs using Mainframe Express from MERANT. SimoX390 is also very useful for getting a quick overview of the mainframe assembler programs and their dependent macro and copy files.
Analysis only (no assembly or execution)
Systems/ASM Systems/ASM is Dignus' HLASM compatible assembler product for the IBM mainframe. Systems/ASM assembler software allows users to develop mainframe applications on a mainframe, or on UNIX and Windows workstations.

Their Systems/C product also generates HLASM-compatible assembler code.
Generates S/390 Assembler code
Tachyon 390 Cross Assembler Develop And Maintain 370/390 Assembler Programs From Your Workstation! Runs on Windows, OS/2, UNIX and Linux. Quoting the vendor:
The Tachyon Operating System includes the powerful Tachyon 390 Emulator and its integrated symbolic debugger. Most of the ESA/390 instruction set and many of the IBM OS/390 and DFSMSdfp services and control blocks are emulated, enabling the Tachyon Operating System to execute application-level programs and even some system-level programs.
Feature Article: New Relationship With Tachyon Software to Benefit SAS/C Cross-Platform Compiler Users Sites
Assembly and Execution


NOTE: HLASM is a trademark of IBM All other trademarks are owned by their respective companies. Please don't take this list as any type of endorsement of any of the products.

What are the missing opcodes?


You may have seen the list of assembler instructions that IBM hasn't implemented yet at: http://kurtz.tcimet.net/humor/f/opcodes.html Some of my favorites: A larger assembler opcode list is at (that includes my favorite: BCF - Branch and Catch Fire): http://www.umr.edu/~huilman/jokes/assemble

Bruce A. Black points out that both of those lists are missing his favorite: It was more popular in the 60s. Here's yet another list: Secret Assembler Mnemonics


What are some good MVS assembler books?


Going beyond the basics, here are the two most highly recommended assembler books for MVS Systems Programmers:

In a post on the ASSEMBLER-LIST mailing list dated 2000-06-02, John Ehrman of IBM posted the following collection of books that has been recommended by others: You may want to check out the FAQ author's Assembler books

This might be of interest: Architecture of the IBM System/360 from 1964.


Are there any Mainframe Assembler courses available on the Internet?


What Mainframe Assembler education is available?


Here are a few companies that offer courses that are known to the FAQ author:


Are there any LE/370 migration issues?


You can make S/390 Assembler programs LE/370 enabled by using the IBM-supplied LE housekeeping macros. See CEE.SCEESAMP(CEEIVP) for a sample Assembler program that uses LE/370 macros. Here's a short discourse on Save Area chaining in a LE/370 environment.
Dave's personal recommendation: If all you need is the current date and time, don't invoke LE/370 routines, use the IBM TIME macro. If you need the julian date converted to gregorian, you could use the CONVTOD, and STCKCONV macros to do this for you.


How can I subtract 64-bit unsigned integers using 32 bit instructions only?


Here is a post made by Edward E. Jaffe on comp.lang.asm370 in January 1998:

 To subtract two TOD clock values (64-bit unsigned integers), I generally
 use something like (for A-B):

          LM    R0,R1,A       Load A
          SL    R1,B+4        Subtract low order part of B
          BC    11,*+6        Branch if no borrow
          BCTR  R0,0          Perform borrow
          SL    R0,B          Complete the subtraction
          .
          .
 A        DS    2F
 B        DS    2F

John Erhman of IBM sent me some sample programs which do 128-bit Math. These are provided without warranty - "any bugs/disasters are the responsibility of the user."


How do I do conditional assemblies based on a macro library level?


Often times, you want your S/390 Assembler program to assemble on any version of a macro library. To do this:

To make this clearer. Let's say you have a program that you would like to use the CSVQUERY macro if the MVS macro library is at the level that has it. Here is some sample code that does conditional assemblies based on the MVS macro library level: 
         CVT   DSECT=YES,LIST=NO
         ...
         AIF   (NOT D'CVTH4430).MVS43X At MVS 4.3 maclib or higher?
         CSVQUERY ...
.MVS43X  ANOP  ,
To see a program that does extensive MVS macro library level checking, see Gilbert Saint-flour's SHOWMVS which is in File492 of the CBT tape


What are the top ten ways to Shoot yourself in the foot using S/390 Assembler?


I have this on a separate page which also has Ways to avoid "Shooting yourself in the foot" and Ways to make debugging easier.

What colleges teach Mainframe assembler?


IBM has a list at Higher Education and S/390 I NEED A NEW LINK!!!!!!!!!!!!!!!

I see that the college I graduated from, University of North Texas, still uses the mainframe along with client/server in their 1999-2000 BCIS (Business Computer Information Systems) Course and Subject Guide. Hire a UNT BCIS graduate - they already have seen and used JCL!


How does the ED instruction work?


This is from a post on the Assembler mailing list on 2000-01-08 by John Murray EDIT (ED) is one of the most feared instructions of the original S/360 instruction set. Even career (professional) programmers have shied away from ED, many developing complex macro instructions and/or subroutines to shield them from this poor instruction's use.

As it turns out, and if you ignore all the BS about "field separators" (nobody ever uses them, it was perhaps a good idea that went astray or perhaps temporary insanity on the part of the original hardware engineers), ED turns out to be a fairly nice and easy to use instruction.

There are no pointers involved. The EDMK (Edit and Mark instruction can feedback an address that tells you where the first significant digit is, but not edit).

The edit instruction has target and source fields like many other SS instructions. The target is the first operand which must contain the edit pattern (or mask) before the instruction is executed. The edit pattern is the way you tell the machine how to edit the data. The source field is usually a packed decimal field, if it isn't watch out for S0C7 problems. The length of the first operand governs the result of the edit operation.

Special attention must be given to the edit pattern. The first byte of the pattern is the fill character, usually a blank. Subsequent bytes are typically "digit select" characters or constants to insert in the result to pretty it up. There is also some consideration for "significance start" and signs (eg. +, -, CR, DB, etc.) that can be inserted in the edited result. I don't have all this on the tip of my brain, so I'll stick with a simple case to give you the hang of the instruction, the rest can be found in the POP.

Assume you have a three byte packed field containing the year (YEAR DC XL3'02000C') and you would like to display this value as "2,000". You can do this with a simple edit pattern and the ED instruction.

Since there are 5 digits in the year counting the leading zero, you must allow for this in your edit pattern which will look something like this "X'4020206B202020'". The first byte (X'40') is the fill character. The next two bytes (X'20's) are digit select characters and act like filters in that zeros do not pass through the filter unless there has been a prior non-zero digit. When there has not been a prior non-zero digit, zero is replaced by the fill character. The X'6B' is a comma that will be inserted in the result to pretty it up. The final three X'20's are the rest of the digit select characters necessary for properly editing the year.

The instructions: 

          MVC     OUT(7),=X'4020206B202020'
          ED      OUT(7),YEAR
will correctly edit this result and leave the variable OUT = X'4040F26BF0F0F0'.

That should take some of the mystery out of it and get you on the right track for using ED productively.


What does BINZER mean?


BINary ZERo

For more, see http://www.binzer.org


What is the format of the 64-bit Save Area?


This entry was taken from a post by Peter Relson of IBM on the IBM-Main newsgroup/mailing-list: 
The recommended format is:

Bytes 0-3: reserved
Bytes 4-7: character string 'F4SA' (analogous to 'F1SA' at this
           offset when regs are saved in the linkage stack)
Bytes 8-127: 8-byte GPRs in order 14-12
Bytes 128-135: address of previous savearea
Bytes 136-143: address of next savearea

It is z/OS 1.2 that will introduce storage above 2G. But that release does
not support passing control between programs in AMODE 64. Modules are
expected to get control in AMODE 31 and switch when needed to AMODE 64. The
system will not give control to modules in AMODE 64.

When you control your caller, you can have the caller provide a 144-byte
savearea and then you can use the linkage convention described above. When
you cannot control your caller (or your caller is the system) you likely
need to live with the 72-byte savearea that an unchanged caller would
provide, and that means that you need to save registers on the linkage
stack, or need to save the high halves of the GPRs in your own dynamic
storage after you have obtained it. This latter case is the "F5SA" case
which looks just like the "F4SA" case except it has the character string
"F5SA" at bytes 4-7, and has an additional 72 bytes following byte 143, for
saving the high halves of GPRs 0-15 (plus 8 reserved bytes).

The savearea types are as follows:
-- 72-byte standard savearea that we know and love
-- F1SA at bytes 4-7: 72-byte SA, caller's regs saved on
   linkage stack
-- F4SA at bytes 4-7: 144-byte SA, caller's regs saved in
   caller's 144-byte SA in the F4SA format above
-- F5SA at bytes 4-7: 216-byte SA, low halves of caller's
   regs saved in caller's 72-byte save area, high halves
   saved in callee's dynamic area as described earlier
-- F6SA at bytes 4-7: 144-byte SA, caller's regs saved on
   linkage stack

Please note carefully that just as certain registers are "expected" to
remain unchanged when using standard linkage, a target program should take
care to preserve the high halves of registers 2 through 14 so that they are
unchanged upon return.


Also see this Save Area Definitions page.


What Assembler Debuggers are available?


If you know of other ones, please email me.


Are there any S/390 disassemblers?


There are a few free disassemblers on the CBT Tape.

There are a few disassemblers that I know of that are included in commercial products: Others? Send me an email... Planet MVS contact page
Warning: Just because you CAN disassemble a module doesn't mean that you LEGALLY have the right to do so...

Some random things:



Where is the Dead Zone in z/OS? New [2006-01-01]


The "dead zone" is the single, contiguous area between 2G and 4G. IARV64 simply does not allocate any virtual storage in the 2GB-4GB range. Referencing such an address will result in a 0C4 abend with reason code 38, 39, 3A, or 3B.

This item was created from two posts to the ASSEMBLER-LIST mailing list by Edward E. Jaffe and Jim Mulder.

Is it safe to convert lowercase to uppercase by ORing with x'40'? New [2006-01-01]


No. Code pages other than 37 or 1047 have uppercase alphabetic characters that fall outside the x'C1' to x'F9' range.

This item was created from a post to the ASSEMBLER-LIST mailing list by Edward E. Jaffe 2004-06-24.

What instruction gives you the opcode DEAD BEEF CAFE? New [2006-01-01] 


ED   3823(174,11),2814(12)


What is an Architectural Level Set? New [2006-01-01]


An architectural level set occurs when the operating system folks draw a "line in the sand" saying their system will not run on any machine that does not have features "x, y, and z". The first architectural level set (now known as ALS1) occurred with OS/390 V2R10. The features it required can be found in this list:

http://www.ibm.com/servers/s390/os390/plug.html

The second architectural level set (now known as ALS2) was not established by technical people but rather by edict from the "geniuses" in marketing. That's why it backfired and angered so many customers. It occurred with z/OS V1R1. The additional features it required can be found in this list:

http://www.ibm.com/servers/s390/os390/plug1.html

The next "line in the sand" was the requirement by z/OS V1R6 to run in z/Architecture mode. Some have called this ALS3. All z/OS releases will still run on the original "freeway" (z900) machines and there have been no level sets since.

The next level set probably won't occur for years. When it does eventually arrive, most of us will probably consider it to be ALS4 -- even if IBM abandons the "level set" terminology in favor of something new.

Again, a new hardware generation with new features is not an architectural level set. Rather, an architectural level set is a list of hardware features required by the operating system. Or, put another way, a program can determine which hardware features are guaranteed to be available by testing the level of the operating system in the CVT.

This entry was created from a post on the IBM-Main newsgroup by Ed Jaffe.



S/390 is a registered trademark of IBM.
If you find this page useful, you may also want to check out IBM's HLASM web site

BC 15,Dave's HLASM web page.

Dave's S/390 Assembler FAQ web page IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.


Last Updated: 2006-01-01
This web page is © 1997-2006+ by David Alcock. All Rights Reserved.