Dave's HLASM tips

Attend the HLASM conference sessions
Obtain the HLASM toolkit
Resolving macro problems with the HLASM
Getting started with the HLASM Toolkit IDF, Interactive Debug Facility
HLASM for VM tips (Prepare yourself for disappointment)
Use Structured Assembler Macros [2006-01-01]

Attend the HLASM conference sessions:

Attend the HLASM sessions at the Share or OS/390 EXPO conferences. They have been presented in the past by John R. Ehrman, the father of the HLASM. If you can't wait for the next conference, maybe you still have the IBM video from 1992 where he introduced the HLASM to the masses.

John Ehrman speaking
(Sorry: bad image)

Obtain the HLASM Toolkit

IBM bundles the High Level Assembler with z/OS but you should consider buying the very inexpensive HLASM toolkit (about $99 a month). It includes:

Disassembler
Interactive Debugger
Structured Macros
Program Understanding Tool
Source XREF utility
Enhanced SuperC utility

John Ehrman of IBM posted the following on the Assembler Mailing list (1998-09-18):

First, the HL Assembler's Toolkit Feature Release 2 requires OS/2 only for the Program Understanding Tool component; the other five components (disassembler, cross-reference, debugger, macros, and comparison utility) all run on mainframe operating systems (MVS, OS390, VM, and VSE).

Second, it was announced with HLASM R3 that the Program Understanding Tool will also support Windows, with delivery planned for 4Q 1998. The standard Toolkit package will be generally available Sept. 25, 1998.

Third, another part of HLASM R3's Toolkit is a set of enhancements to the Cross-Reference Facility, including what are called "Control Flow" reports. These reports list external references and entry points, and can be sorted both by "caller" and by "callee" (reference or definition).

The XREF facility also provides some information that I think would fit your definition of "demographics", as it can handle collections of many modules in a single invocation. (XREF also handles C/C++, but I don't know offhand if you can analyze a mix of assembler and C++ modules in a single run; I haven't tried it, and can't tell from a quick reading of the documentation.)

As posted on comp.lang.asm370 on Thu, 18 Feb 1999 09:04:35 GMT by Brian Kenn of IBM:

There was a brief discussion about the HLASM Program Understanding Tool late last year, and I thought I ought to correct a few misconceptions about it.

I am the current developer for the brand new ASMPUT, which will be replacing the current OS/2 version very soon now, and which offers the same functionality for Windows (95/98 and NT).

The code has been virtually re-written from scratch giving us a single, integrated application with a (hopefully) easy to use user interface.

The tool will provide the same sort of graphical analysis of the code flow in your program, plus in this new version we've included a fairly extensive code and register flow analysis which will highlight potential bugs in your code that aren't detected by the assembler.

For example, say you make a mistake and type "DS H" instead of "DS 0H" when defining a label. The tool will highlight this letting you know that you've coded a storage definition in the middle of your code. Of course it can detect whether you branch around your storage declarations, and will not flag them.

There are heaps of other potential errors that are detected, including the use of registers before they have any values set, unreachable code, bad operand alignments that the assembler doesn't detect, wild branches to low memory, and so on...

Anyway, enough advertising...I just thought the news group might like to know that the Program Understanding Tool is alive and kicking...

Resolving macro problems with the HLASM

Use the HLASM PARM=MXREF(SOURCE) parameter to find out where in the //SYSLIB concatenation a MACRO is being resolved from. From my experience, this feature has solved many assembler problems. Here is an example of the MXREF output that shows some of the JES2 macros coming from the MTS and some from the JES2 library:

 CWJESTAB             Macro and Copy Code Source Summary

  Con Source                  Volume    Members
   L1 ABENDAID.SORCMAC        PPXA17    CWINIT   RELEASE
   L2 SYS1.SMPMTS             ESA43R    $BUFFER  $DAS     $HASPEQU $HCCT
                                        $IOT     $SCAT    $SDB     $SJB
   L4 SYS1.HASPSRC            ESA43D    $HFAME   $PDDB    $TAB     $TQE
                                        $XECB

   L5 SYS1.MACLIB             SYS1R3    IOSDIEDB IOSDIOBE POST
   L6 SYS1.MODGEN             SYS1R3    IFGRPL   IFGRPLVS

Getting started with the HLASM Toolkit IDF:

The HLASM Toolkit IDF, Interactive Debug Facility, started off being only available internally in IBM and was initially a VM product. It took me a little bit longer than I thought it would to get my first debugging session started. Here are my sample JCL and REXX exec to setup the debugging datasets and invoke the debugger:

Sample JCL that assembles a test program with the ADATA parm, links it, and creates a ASMLANGX file.
Sample REXX that invokes the debugger. This REXX exec is designed for debugging personal programs and not those in the MVS Link List (although it could be tailored to do that).

Below is a sample debugging session (after using the REXX above to invoke the IDF debugger) shown as a looping animated GIF. First there is a blank screen showing the initial IDF screen. The next screen shows a couple of "windows" that have been created using the PF keys to show the registers and the disassembled code. The third screen starts a single step through the code until we hit an instruction that causes a S0C4 ABEND.

Want to
know how
I did this
animated GIF?

See my
3270 Demo
page.

This sample IDF debug session showing only a a very limited subset of IDF's debugging capabilites. Typically you would create breakpoints and only single step thru a small section of the code.

Quirks (which may have been addressed by now with PTFs):

When you invoke the ASMLANGX conversion program, you will see its VM background by the syntax of the parameter:
EXEC PGM=ASMLANGX,PARM='PROG1 (ASM LOUD ERROR DEBUG'
The port of TCP/IP for MVS is the same way.
The ASMLANGX program will put anything that is specified in the JCL parameter member field area as the member name of the ASMLANGX PDS as I found out when I converted my JCL from a proc to a standalone member and had "&M" as the member name. For example:
EXEC PGM=ASMLANGX,PARM='&M (ASM LOUD ERROR DEBUG'
I got a member called "&M" in the ASMLANGX PDS which doesn't follow normal TSO/ISPF naming standards.

This is really a short list of quirks when you consider that there are a slew of O'Reilly Annoyances books on Microsoft products: Windows Annoyances, Office 97 Annoyances, Word 97 Annoyances and Excel 97 Annoyances.

HLASM for VM tips

Even though Dave's HLASM tips are focused on MVS (z/OS, OS/390, whatever), I'll include VM tips when I hear about them.

Melinda Varian has written hla.xedit which is a easy way to invoke the HLASM while in XEDIT. This use to be on the web.
Short page on HLASM on VM from University of Connecticut Computer Center
VM/ESA CP/CMS Control Block

Use Structured Assembler Macros [2006-01-01]

Many assembler programmers have the feeling that "if I wanted to write COBOL, I'd write COBOL", but you can be more productive using the IBM HLASM Toolkit Structured Assembler macros.

Ed Jaffe made an excellent presentation at SHARE called Structured Assembler Language Programming Using HLASM (Acrobat PDF, 648k).

Ed's public-domain HLASM enhancements are now completely current with PK01283 for both HLASM 1.4 and HLASM 1.5. He also improved the FLOWASM program and save area stack manipulation code in the STKSAVE macro. They are available in this TSO XMIT file: asmmods.xmi (courtesy of Phoenix Software).

This is an XMIT file that you will either need to view using XMIT manager on Windows or upload to your mainframe into a FB LRECL=80 dataset and extracted using the RECEIVE TSO command.

Chuck Davis sent me this Structured Programming in Assembler Language (Acrobat PDF, 170k) with this:

The attached document has some references to a VSAMIO module that was in use when this document was written. I do not have access to those macros. However, I can supply the "Perform" macros if you want them.

Dave's HLASM tips pageIBM
High Level AssemblerHLASMS/390IBM
IBM's HLASM web site

BC 15,Dave's HLASM web page

Dave's HLASM tips 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.