Alternate Macro Libraries – Part 2

(Originally posted 2013-03-18.)

First, I’m indebted to Ray Mullins for his help in figuring out how to solve the problems I identified as remaining in Alternate Macro Libraries: A Way To Document Assembler Tables. Indeed he wrote a very handy blog post of his own: Wrapping your own macro code around vendor-supplied macros without changing source

This post, to summarise, shows how you can use the OPSYN instruction to create your own copy of a macro as a “shim” for a supplied macro of the same name. It’s a neat technique, involving renaming the macro in its own body, calling the now exposed original version, and then renaming the shim macro back.

The other thing we discussed was how to produce useful textual output from a macro invocation for use outside of the traditional purposes of an assembly listing. (In the original post’s case it was creating HTML documentation.) This isn’t nearly so nice a story: You can’t write a side file but you can write text to the assembly listing in a macro using MNOTE.

So a solution is to write lines using MNOTE with a special pair of delimiters that wrap the line. For example

MNOTE *,'XYZZY<table>XYZZY'

will do nicely. 🙂

Then read the assembly listing with DFSORT. (You could, of course, use REXX but DFSORT will do it just fine. If you wanted to do some additional processing REXX might be preferable.)

With DFSORT you can write two files in a single pass using OUTFIL:

• The HTML file, using OUTREC with PARSE to keep and edit the lines produced by the MNOTE instructions.
• A complete listing or one with the “XYZZY” lines stripped out, to its original destination. You can achieve the latter with the OUTFIL SAVE statement.

The question arises as to what the MNOTE lines actually look like: By experiment we’ve discovered it varies, depending on the assembler you’re using. For example, z390 produces different output from HLASM.

That’s not a significant problem: If you were using this technique with z390 you wouldn’t be using DFSORT to post-process the listing.

Instead you could use any of the Linux or Windows or OSX tools available to you. For example a simple sed invocation could extract the HTML, looking for the z390-specific version of the MNOTE lines.

The nice thing about this approach is it can be readily set up to produce the HTML documentation and the load module in the same job. That’s particularly desirable as it means the documentation will always be up to date. You could even have a final step that, with a clean assembly and linkedit, pushes the HTML to a documentation web server.