High Level Assembler for z/OS & z/VM & z/VSE Programmer's Guide Version 1 Release 6 SC26-4941-06 Note Before using this information and the product it supports, be sure to read the general information under “Notices” on page 397. This edition applies to IBM High Level Assembler for z/OS & z/VM & z/VSE, Release 6, Program Number 5696-234 and to any subsequent releases until otherwise indicated in new editions. Make sure that you are using the correct edition for the level of the product. Order publications through your IBM representative or the IBM branch office serving your locality. IBM welcomes your comments. For information on how to send comments, see “How to send your comments to IBM” on page xix. © Copyright IBM Corporation 1992, 2013. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Figures ...............ix *PROCESS statement options .......37 Default options ............37 Tables ...............xi Invoking the assembler dynamically .....37 Coding rules .............37 Assembler options ............38 About this document ........xiii ADATA...............39 Who should use this document .......xiii ALIGN ...............39 Programming interface information ......xiii ASA (z/OS and CMS) ..........40 Organization of this document........xiii BATCH...............40 High Level Assembler documents .......xv CODEPAGE .............41 Documents .............xv COMPAT ..............42 Collection kits ............xvi DBCS ...............43 Related publications ...........xvi DECK ...............43 Syntax notation .............xvi DISK (CMS) .............44 DXREF ...............44 How to send your comments to IBM xix ERASE (CMS) ............45 If you have a technical problem .......xix ESD................45 EXIT................46 Summary of changes ........xxi FLAG ...............48 FOLD ...............51 Chapter 1. Introduction ........1 GOFF (z/OS and CMS) .........51 INFO ...............52 Requirements ..............1 LANGUAGE .............53 System requirements...........1 LIBMAC ..............54 Machine requirements ..........1 LINECOUNT .............54 Storage requirements ..........2 LIST ................55 Compatibility ..............2 MACHINE .............56 Assembler language support ........2 MXREF ...............58 Migration considerations .........2 OBJECT ..............59 OPTABLE ..............59 Chapter 2. Using the assembler listing . 5 PCONTROL .............61 High Level Assembler option summary .....6 PESTOP ..............63 External Symbol Dictionary (ESD) .......9 PRINT (CMS).............63 Source and object ............12 PROFILE ..............63 Relocation dictionary (RLD) .........18 RA2................64 Ordinary symbol and literal cross reference....19 RENT ...............65 Unreferenced symbols defined in CSECTs ....22 RLD................65 Macro and copy code source summary .....22 RXREF ...............66 Macro and copy code cross reference ......23 SECTALGN .............66 Effects of LIBMAC and PCONTROL(MCALL) SEG (CMS) .............66 options ...............24 SIZE................67 DSECT cross reference...........26 SUPRWARN .............69 USING map ..............27 SYSPARM ..............69 General Purpose Register cross reference ....28 TERM ...............70 Diagnostic cross reference and assembler summary 29 TEST ...............71 Terminal output .............32 THREAD ..............71 TRANSLATE .............72 Chapter 3. Controlling your assembly TYPECHECK .............72 with options ............35 USING ...............73 The sources of assembler options .......35 WORKFILE .............75 Precedence of assembler options ......35 XOBJECT (z/OS and CMS) ........76 Fixed installation default options ......36 XREF ...............76 *PROCESS OVERRIDE Statement Options . 36 ASMAOPT options ...........36 Chapter 4. Providing user exits ....79 Invocation options ...........36 Exit types ...............79 © Copyright IBM Corp. 1992, 2013 iii Specifying user exits ...........80 Pointer to return string (SETCF) ......141 Loading user exits ............81 Pointer to parm string n (SETCF) ......141 Calling user exits ............81 Exit parameter list ............82 Chapter 6. Diagnosing assembly Request info pointer ..........83 errors...............143 Buffer pointer ............90 Assembly error diagnostic messages......143 Error buffer pointer...........90 MNOTE statements ...........144 Exit-specific information pointer ......91 Suppression of error messages and MNOTE DCB pointer .............91 statements ..............146 Static assembler information pointer .....91 Reference information for statements in error. 146 HLASM Services Interface pointer ......92 Abnormal assembly termination .......146 Error handling .............92 MHELP - macro trace facility ........146 Exit-Specific Information Block ........92 SOURCE exit processing ..........95 OPEN ...............95 Chapter 7. Assembling your program CLOSE ...............96 on z/OS ..............149 READ ...............96 Input to the assembler ..........149 PROCESS ..............97 Output from the assembler .........149 LIBRARY exit processing ..........98 Invoking the assembler on z/OS .......149 OPEN ...............98 Invoking the assembler on TSO .......151 CLOSE ...............99 Invoking the assembler dynamically......152 READ ...............99 Batch assembling ............154 PROCESS MACRO or PROCESS COPY ....99 Input and output data sets .........154 FIND MACRO or FIND COPY ......100 Specifying the source data set: SYSIN ....157 END OF MEMBER ..........102 Specifying the option file: ASMAOPT ....157 LISTING exit processing..........103 Specifying macro and copy code libraries: OPEN ...............104 SYSLIB ..............158 CLOSE ..............105 Specifying the listing data set: SYSPRINT . 158 WRITE ..............105 Directing assembler messages to your terminal: PROCESS .............105 SYSTERM .............158 OBJECT (z/OS and CMS) and PUNCH exit Specifying object code data sets: SYSLIN and processing ..............107 SYSPUNCH .............158 OPEN ...............107 Specifying the associated data data set: CLOSE ..............108 SYSADATA .............159 WRITE ..............108 Specifying the utility data data set: SYSUT1 . 159 PROCESS .............108 Return codes .............159 ADATA exit processing ..........110 OPEN ...............110 Chapter 8. Linking and running your CLOSE ..............111 program on z/OS ..........161 WRITE ..............111 The program management binder ......161 PROCESS..............111 The loader ..............163 TERM exit processing ..........112 Creating a load module ..........163 OPEN ...............112 Creating a load module on z/OS ......163 CLOSE ..............113 Creating a load module on TSO ......163 WRITE ..............113 Input to the binder ...........164 PROCESS..............113 Data sets for binder processing ......165 Sample user exits ............114 Additional object modules as input .....165 User exit coding example .........114 Output from the binder ..........166 OBJECT and PUNCH exit—OBJEXIT ....115 Binder processing options ........166 ADATA Exit—ADEXIT .........115 Specifying binder options through JCL ....167 TERM exit—TRMEXIT .........116 Specifying binder options using the TSO LINK command .............168 Chapter 5. Providing external AMODE and RMODE attributes ......168 functions .............135 Overriding the defaults .........169 External function processing ........135 Detecting binder errors .........169 Linkage conventions ...........136 Running your assembled program ......169 External function parameter list .......136 Running your assembled program in batch . 169 Request information list .........138 Running your assembled program on TSO . 169 Pointer to user work area ........140 Pointer to static assembler information ....140 Pointer to msg buffer..........141 iv High Level Assembler for z/OS & z/VM & z/VSE: Programmer's Guide Chapter 9. z/OS system services and Passing parameters to your assembler language programming considerations ....171 program ...............196 Adding definitions to a macro library .....171 Using cataloged procedures ........172 Chapter 13. Assembling your program Cataloged procedure for assembly (ASMAC) 172 on z/VSE .............199 Cataloged procedure for assembly and link Input to the assembler ..........199 (ASMACL) .............173 Output from the assembler .........199 Cataloged procedure for assembly, link, and run Invoking the assembler in batch .......199 (ASMACLG) ............175 Invoking the assembler on ICCF .......200 Cataloged procedure for assembly and run Invoking the assembler dynamically......203 (ASMACG) .............176 Batch assembling ............203 Overriding statements in cataloged procedures 178 Controlling your assembly .........204 Examples of cataloged procedures .....178 Input and output files ..........205 Operating system programming conventions . 180 Specifying the source file: SYSIPT .....207 Saving and restoring general register contents 180 Specifying macro and copy code libraries: Ending program execution .........180 LIBDEF job control statement .......207 Accessing execution parameters .......181 Specifying the listing file: SYSLST .....207 Object program linkage ..........181 Directing assembler messages to your console Modifying program modules ........182 log: SYSLOG ............207 Specifying object code files: SYSLNK and Chapter 10. Assembling your program SYSPCH ..............207 onCMS..............183 Specifying