Using macros to punch source code is a very powerful feature. HLASM is mostly written in Assembler itself, but it uses some PL/X code for the disassembler subroutine ASMADOP, and that needs PL/X data definitions for the instructions and for the instruction formats. The process was partly automated using a program to read the load module containing the compiled definitions and write a file containing the PL/X definitions. However, I reworked the process so that both PL/X data definition files are now produced simply by assembling the corresponding assembler definitions (copy books containing lots of macros) with a flag that tells the macros to generate PL/X source (using PUNCH) instead of assembler source.
I must admit that I have primarily seen the Reference Summary as a debugging aid for Assembler programmers, especially at a very low level, where what I've often wanted is a more general assembler programming productivity aid, enabling me for example to find the most appropriate instruction sequence that is supported on the target hardware level. The I/O information on the card was useful in the 1970s and 1980s when I was using EXCP on OS/VS and DOS/VS for local terminals, Bisync terminals and DASD (CKD or FBA), but I've rarely had any use for the current I/O information, nor any other deep hardware stuff such as machine checks. Information about hardware-assigned low storage locations and interrupt codes is usefully concise in the Reference Summary, but I often require information about software fields in low storage as well, so I used to browse a listing from assembling IHAPSA and extensions for z/OS, and similarly NUCON for CMS (with a separate copy for zCMS). The instruction list in the HLASM Programmer's Guide includes all opcodes known to HLASM, including extended mnemonics, for which it shows the base instruction mnemonic, although it doesn't specifically show how it expands in terms of the base instruction, which is however well documented in the useful Appendix J of Principles of Operation. Jonathan Scott -----Original Message----- From: IBM Mainframe Assembler List <[email protected]> On Behalf Of Abe Kornelis Sent: 21 October 2025 10:05 To: [email protected] Subject: Re: Do you still use the IBM z/Architecture Reference Summary (SA22-7871)? All, I love that everyone is promoting their personal preference! Here's mine: - opcode tables: https://bixoft.nl/english/opcd00.htm - opcode lists: https://bixoft.nl/english/oplist.htm - visualised stratification: https://bixoft.nl/english/opcodes.htm They're all up to date with z17. What's more: I use macros and AREAD logic to produce all those pages (except the stratification one) from a single source member. And yes, those macros actually PUNCH the html. I'm too lazy to do all that typing myself ;-) Kind regards & happy programming! Abe ===
