Dave's z/Architecture Assembler FAQ

• View an uncredited assembler programming style discussion that was on the IBM mainframe assembler mailing list a while back.
  
  
• Some old timers don't like labels that are longer than 8 characters. So they hate my code! I heard one person say recently "You should be able to fit all you need in 8 characters".
  
  This is a personal taste issue. I point to IBM's usage of longer labels in SYS1.MACLIB.
  
  
• Don't code "R0" on "BCTR Rx,0" instruction. In this case, you are not using register zero.
  
  
• Restrict the use of in-line executes:

   MVC 0(0,R4),0(R5) ** Executed **
   EX R3,*-6 Move string to output line
   

  I use to code like this but now move the executed statement out of program flow. Even worse are things like "B *+12"
  
  
• Some feel that you should have the assembler do all the work including counting characters:

   MVC 0(12,R5),=C'somedatahere' *** BAD ***
   MVC 0(L'DATA,R5),DATA *** GOOD line 1 ***
   DATA DC C'somedatahere' *** GOOD line 2 ***
   

  Sometimes I'm lazy and don't always follow this practice.
  
  
• Don't overuse USINGs. Consider the following code:

   L R4,CVTPTR -> CVT
   L R4,CVTJESCT-CVTMAP(R4) -> JESCT
   L R4,JESSSCT-JESCT(R4) -> SSCVT
   

  A lot of people would have two extra USING and DROPs for the CVT and JESCT DSECTS. I feel this obscures the code with extra statements that get in the way. If you're looking at a lot of fields in a DSECT, use a USING, if only one or two, use the FIELD-DSECT(R?) method.

• It's not a system exit
• Performance isn't critical
• It doesn't invoke any API's (or programming interfaces) only available to assembler

• BOB - BRANCH ON BUG
• KCE - KILL CONSULTANT ON ERROR
• SRDR - SHIFT RIGHT DOUBLE RIDICULOUS

• BOH- Branch on Operator High

• Advanced Assembler Language and MVS Interfaces
  For IBM Systems and Application Programmers
  by Carmine Cannatello - 1991 (2nd Edition 1999)
• MVS Power Programming
  by Mitchell Mark and Penelope Davis - 1992

• "The IBM 370: Computer Organization and Assembly Language" by Gordon L. Bailes and Robert R. Riser
• "Assembler Language Programming: The IBM System/370 Family" (Third Edition) by George Struble 1984, 525 pages, Addison-Wesley Publishing Co. Inc. ISBN 0-201-07815-5
• "Assembler Language with ASSIST and ASSIST/I" by Ross Overbeek and W.E. Singletary, Macmillan, 1991.
• "IBM 370 Assembly Language with ASSIST, Structured Concepts & Advanced Topics" by Charles J. Kacmar. Prentice-Hall, 1988. (Superseded by the previous book, I think?)
• "Assembler Language Programming for the IBM 370" by Frank Carrano.
• "Assembler Language Programming for the IBM 370, ASSIST Edition" by Frank M. Carrano, The Benjamin/Cummings Publishing Company, 1988 ISBN 0-8053-1810-0
• "Programming Assembler Language; Second Edition" by Peter Abel. Prentice-Hall: Reston, Virginia, 1984. 581 pages (ISBN 0-13-728924-3)
• "Assembler Language Programming of IBM and IBM Compatible Computers", by Stern, Sager, and Stern; John Wiley & Sons, Inc.
• "Advanced Assembler Language and MVS Interfaces: for IBM Systems and Application Programmers" (2nd edition, August 1999) by Carmine Cannatello. John Wiley & Sons, Inc.
• "MVS Assembler Language" (1987) by Kevin McQuillen and Anne Prince. Mike Murach & Associates.

• Western Illinois University's CS310 IBM Mainframe Assembly Programming is on the web at http://www.wiu.edu/users/mflll/cs310/head.html - Contributed by Mike Theys
  
  
• Ehud Lamm's Five session intro to ASM/370 programming
  
  
• You may get some benefit from reading Using Assembler Language at the NIH Computer Center

• Michel Castelein
• IBM Education
• The Trainer's Friend

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.

 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

• Put a mapping macro at the top of your program source
• Use the D'field method to determine if a given field is defined. This will tell you the macro library level.

 CVT DSECT=YES,LIST=NO
 ...
 AIF (NOT D'CVTH4430).MVS43X At MVS 4.3 maclib or higher?
 CSVQUERY ...
.MVS43X ANOP ,

 MVC OUT(7),=X'4020206B202020'
 ED OUT(7),YEAR

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.

• XDC/SE from Cole Software
• Xpediter from Compuware
• TSO TEST (Free), HLASM IDF (nearly free) and Debug Tool from IBM
• AllFusion CA-InterTest from Computer Associates
• TraceMaster from Macro4
• Metamon Live works in batch, CICS and TSO.

• IBM's HLASM Toolkit has a full function disassembler which processes:
  • MVS - An object module, a program object or load module
  • CMS - An object deck or CMS module
  • VSE - An object module or a phase
• Cole Software's XDC/SE
• Serena's StarTool - Here's an example of the output for IEFBR14.
• SAS C compiler has a object module disassembler called omd. Here are some more instructions.
• Waterloo's C Demonstration and Utility Programs page has a CMS TEXT file and MVS object code disassembler.

Warning: Just because you CAN disassemble a module doesn't mean that you LEGALLY have the right to do so...

Some random things:

• I didn't mention the AMASPZAP utility which does a very primitive disassembly (just instructions) during a module dump. Here's an example of "DUMPT IEFBR14 IEFBR14":
  
  

  **CCHHR- 0343000A0A RECORD LENGTH- 000008 MEMBER NAME IEFBR14
   000000 1BFF 07FE
   SR BCR
  

  
  This function is so ancient and can get "mixed up" easily unlike a full function two-pass disassembler like the one that is included in the HLASM Toolkit.
  
  
• I like the way Compuware's ABENDAID does a small disassembly of the code around the PSW at ABEND time. Here's an example:
  
  

   The next sequential instruction to be executed in
   program GETABEND was at displacement 000000A6.
   00000098 18D1 LR R13,R1
   0000009A 58101004 L R1,4(,R1)
   0000009E 58101018 L R1,24(,R1)
   000000A2 50000000 ST R0,0
   NSI==> 000000A6 D2130000E008 MVC 0(20,R0),8(R14)
   000000AC 58D0D004 L R13,4(,R13)
   000000B0 41F00000 LA R15,0
   000000B4 58E0D00C L R14,12(,R13)
   000000B8 980CD014 LM R0,R12,20(R13)

  
  I have no experience using them but it appears that at least one of their competitors also has this capability: CA-SymDump (which mentions having this function) and Dumpmaster (which doesn't that I could find).