IBM High Level Assembler for MVS & VM & VSE
Programmer’s Guide Release 5
SC26-4941-04
IBM High Level Assembler for MVS & VM & VSE
Programmer’s Guide Release 5
SC26-4941-04
Note!
Before using this information and the product it supports, be sure to read the general information under “Notices” on page 422.
Fifth Edition (June 2004)
This edition applies to IBM High Level Assembler for MVS & VM & VSE, Release 5, Program Number 5696-234 and to any subsequent releases until otherwise indicated in new editions. Make sure 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. Publications are not stocked at the address below.
A form for reader's comments is provided at the back of this publication. If the form has been removed, address your comments to: IBM Corporation J87/D325 555 Bailey Avenue SAN JOSE, CA 95141-1003 United States of America
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.
Copyright International Business Machines Corporation 1982, 2004. All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents
Contents
About this Manual ...... xi Who Should Use this Manual ...... xi Programming Interface Information ...... xi Organization of this Manual ...... xi IBM High Level Assembler for MVS & VM & VSE Publications ...... xiv Publications ...... xiv Softcopy Publications ...... xv The High Level Assembler web site ...... xv | Using LookAt to look up Message Explanations ...... xv Related Publications ...... xvi Syntax Notation ...... xvi
Summary of Changes ...... xix
Part 1. Understanding and Using the Assembler ...... 1
Chapter 1. Introduction ...... 5 Requirements ...... 5 System Requirements ...... 5 Machine Requirements ...... 5 Storage Requirements ...... 6 Compatibility ...... 7 Assembler Language Support ...... 7 Migration Considerations ...... 7
Chapter 2. Using the Assembler Listing ...... 8 High Level Assembler Option Summary ...... 9 External Symbol Dictionary (ESD) ...... 13 Source and Object ...... 16 Relocation Dictionary (RLD) ...... 23 Ordinary Symbol and Literal Cross Reference ...... 24 Unreferenced Symbols Defined in CSECTs ...... 27 Macro and Copy Code Source Summary ...... 27 Macro and Copy Code Cross Reference ...... 28 DSECT Cross Reference ...... 32 USING Map ...... 33 General Purpose Register Cross Reference ...... 34 Diagnostic Cross Reference and Assembler Summary ...... 35
Chapter 3. Controlling Your Assembly with Options ...... 41 The Sources of Assembler Options ...... 41 Precedence of Assembler Options ...... 41 Fixed Installation Default Options ...... 42 *PROCESS OVERRIDE Statement Options ...... 42 ASMAOPT Options ...... 42 Invocation Options ...... 42 *Process Statement Options ...... 43 Default Options ...... 44 Invoking the Assembler Dynamically ...... 44
Copyright IBM Corp. 1982, 2004 iii Contents
Coding Rules ...... 44 Assembler Options ...... 45 ADATA ...... 45 ALIGN ...... 46 ASA (MVS and CMS) ...... 46 BATCH ...... 47 CODEPAGE ...... 47 COMPAT ...... 48 DBCS ...... 49 DECK ...... 50 DISK (CMS) ...... 50 DXREF ...... 50 ERASE (CMS) ...... 51 ESD ...... 51 EXIT ...... 52 FLAG ...... 55 FOLD ...... 58 GOFF (MVS and CMS) ...... 58 INFO ...... 60 LANGUAGE ...... 60 LIBMAC ...... 61 LINECOUNT ...... 62 LIST ...... 62 | MACHINE ...... 63 MXREF ...... 65 OBJECT ...... 66 OPTABLE ...... 66 PCONTROL ...... 68 PESTOP ...... 70 PRINT (CMS) ...... 70 PROFILE ...... 70 RA2 ...... 71 RENT ...... 72 RLD ...... 72 RXREF ...... 73 | SECTALGN ...... 73 SEG (CMS) ...... 73 SIZE ...... 74 | SUPRWARN ...... 76 SYSPARM ...... 76 TERM ...... 77 TEST ...... 78 THREAD ...... 78 TRANSLATE ...... 79 | TYPECHECK ...... 79 USING ...... 80 XOBJECT (MVS and CMS) ...... 83 XREF ...... 83
Chapter 4. Providing User Exits ...... 85 Exit Types ...... 85 Specifying User Exits ...... 86 Loading User Exits ...... 87 Calling User Exits ...... 88
iv HLASM V1R5 Programmer’s Guide Contents
Exit Parameter List ...... 88 Request Info Pointer ...... 90 Buffer Pointer ...... 97 Error Buffer Pointer ...... 97 Exit-Specific Information Pointer ...... 97 DCB Pointer ...... 97 Static Assembler Information Pointer ...... 98 HLASM VRM ...... 98 PTF Level ...... 98 System ID ...... 98 | Numeric Version ...... 98 Error Handling ...... 99 Exit-Specific Information Block ...... 99 Member Name ...... 101 Member Type ...... 101 Data Set Name ...... 101 Volume Serial ...... 101 Relative Record Number ...... 102 Absolute Record Number ...... 103 Linecount ...... 103 Current Page Number ...... 103 SOURCE Exit Processing ...... 104 OPEN ...... 104 CLOSE ...... 104 READ ...... 104 PROCESS ...... 105 LIBRARY Exit Processing ...... 106 OPEN ...... 106 CLOSE ...... 107 READ ...... 107 PROCESS MACRO or PROCESS COPY ...... 108 FIND MACRO or FIND COPY ...... 108 END OF MEMBER ...... 110 LISTING Exit Processing ...... 112 OPEN ...... 113 CLOSE ...... 114 WRITE ...... 114 PROCESS ...... 114 OBJECT (MVS and CMS) and PUNCH Exit Processing ...... 116 OPEN ...... 117 CLOSE ...... 118 WRITE ...... 118 PROCESS ...... 118 ADATA Exit Processing ...... 120 OPEN ...... 120 CLOSE ...... 121 | WRITE ...... 121 PROCESS ...... 121 TERM Exit Processing ...... 122 OPEN ...... 123 CLOSE ...... 124 WRITE ...... 124 PROCESS ...... 124 Sample User Exits ...... 125
Contents v Contents
User Exit Coding Example ...... 125
Chapter 5. Providing External Functions ...... 144 External Function Processing ...... 144 Linkage Conventions ...... 145 External Function Parameter List ...... 145 Request Information List ...... 148 Pointer to User Work Area ...... 150 | Pointer to Static Assembler Information ...... 150 Pointer to Msg Buffer ...... 150 Pointer to Return String (SETCF) ...... 150 Pointer to Parm String n (SETCF) ...... 151
Chapter 6. Diagnosing Assembly Errors ...... 152 Assembly Error Diagnostic Messages ...... 152 MNOTE Statements ...... 154 Suppression of Error Messages and MNOTE Statements ...... 156 Reference Information for Statements in Error ...... 156 Abnormal Assembly Termination ...... 157 MHELP—Macro Trace Facility ...... 157
Part 2. Developing Assembler Programs on MVS ...... 159
Chapter 7. Assembling Your Program on MVS ...... 161 Input to the Assembler ...... 161 Output from the Assembler ...... 161 Invoking the Assembler on MVS ...... 161 Invoking the Assembler on TSO ...... 163 Invoking the Assembler Dynamically ...... 164 Batch Assembling ...... 166 Input and Output Data Sets ...... 167 Specifying the Source Data Set: SYSIN ...... 169 Specifying the Option File: ASMAOPT ...... 170 Specifying Macro and Copy Code Libraries: SYSLIB ...... 170 Specifying the Listing Data Set: SYSPRINT ...... 170 Directing Assembler Messages to Your Terminal: SYSTERM ...... 170 Specifying Object Code Data Sets: SYSLIN and SYSPUNCH ...... 171 Specifying the Associated Data Data Set: SYSADATA ...... 171 Return Codes ...... 171
Chapter 8. Linking and Running Your Program on MVS ...... 172 The Program Management Binder ...... 172 The Loader ...... 174 Creating a Load Module ...... 174 Creating a Load Module on MVS ...... 174 Creating a Load Module on TSO ...... 175 Input to the Binder ...... 175 Data Sets for Binder Processing ...... 176 Additional Object Modules as Input ...... 177 Output from the Binder ...... 178 Binder Processing Options ...... 178 Specifying Binder Options Through JCL ...... 179 Specifying Binder Options Using the TSO LINK Command ...... 180
vi HLASM V1R5 Programmer’s Guide Contents
AMODE and RMODE Attributes ...... 180 Overriding the Defaults ...... 181 Detecting Binder Errors ...... 181 Running Your Assembled Program ...... 181 Running Your Assembled Program in Batch ...... 181 Running Your Assembled Program on TSO ...... 181
Chapter 9. MVS System Services and Programming Considerations ... 183 Adding Definitions to a Macro Library ...... 183 Using Cataloged Procedures ...... 184 Cataloged Procedure for Assembly (ASMAC) ...... 184 Cataloged Procedure for Assembly and Link (ASMACL) ...... 186 Cataloged Procedure for Assembly, Link, and Run (ASMACLG) ...... 188 Cataloged Procedure for Assembly and Run (ASMACG) ...... 190 Overriding Statements in Cataloged Procedures ...... 191 Examples of Cataloged Procedures ...... 192 Operating System Programming Conventions ...... 194 Saving and Restoring General Register Contents ...... 194 Ending Program Execution ...... 195 Accessing Execution Parameters ...... 195 | Object Program Linkage ...... 196 Modifying Program Modules ...... 196
Part 3. Developing Assembler Programs on CMS ...... 199
Chapter 10. Assembling Your Program on CMS ...... 200 Input to the Assembler ...... 200 Output from the Assembler ...... 200 Accessing the Assembler ...... 200 Invoking the Assembler on CMS ...... 201 Batch Assembling ...... 202 Controlling Your Assembly ...... 202 Input and Output Files ...... 203 Specifying the Source File: SYSIN ...... 205 Specifying the Option File: ASMAOPT ...... 207 Specifying Macro and Copy Code Libraries: SYSLIB ...... 207 Specifying the Listing File: SYSPRINT ...... 207 Directing Assembler Messages to Your Terminal: SYSTERM ...... 208 Specifying Object Code Files: SYSLIN and SYSPUNCH ...... 208 Specifying the Associated Data File: SYSADATA ...... 208 Return Codes ...... 208 Diagnostic Messages Written by CMS ...... 209
Chapter 11. Running Your Program on CMS ...... 210 Using the CMS LOAD and START Commands ...... 210 Using the CMS GENMOD Command ...... 210 Using the CMS LKED and OSRUN Commands ...... 211 Using the CMS Batch Facility ...... 212
Chapter 12. CMS System Services and Programming Considerations .. 213 Using Macros ...... 213 Assembler Macros Supported by CMS ...... 213 Adding Definitions to a Macro Library ...... 213
Contents vii Contents
Operating System Programming Conventions ...... 213 Saving and Restoring General Register Contents ...... 213 Ending Program Execution ...... 214 Passing Parameters to Your Assembler Language Program ...... 215
Part 4. Developing Assembler Programs on VSE ...... 217
Chapter 13. Assembling Your Program on VSE ...... 218 Input to the Assembler ...... 218 Output from the Assembler ...... 218 Invoking the Assembler in Batch ...... 218 Invoking the Assembler on ICCF ...... 220 Invoking the Assembler Dynamically ...... 222 Batch Assembling ...... 222 Controlling Your Assembly ...... 223 Input and Output Files ...... 224 Specifying the Source File: SYSIPT ...... 226 Specifying Macro and Copy Code Libraries: LIBDEF Job Control Statement 226 Specifying the Listing File: SYSLST ...... 227 Directing Assembler Messages to Your Console Log: SYSLOG ...... 227 Specifying Object Code Files: SYSLNK and SYSPCH ...... 227 Specifying the Associated Data File: SYSADAT ...... 228 Return Codes ...... 228
Chapter 14. Link-Editing and Running Your Program on VSE ...... 229 The Linkage Editor ...... 229 Creating a Phase ...... 229 Input to the Linkage Editor ...... 230 Inputting Object Modules ...... 230 Files for Linkage Editor Processing ...... 230 Inputting additional Object Modules ...... 231 Linkage Editor Control Statements ...... 231 Output from the Linkage Editor ...... 232 Running your Assembled Program ...... 233
Chapter 15. VSE System Services and Programming Considerations ... 234 Adding Definitions to a Macro Library ...... 234 Processing E-Decks ...... 234 Operating System Programming Conventions ...... 235 Saving and Restoring General Register Contents ...... 235 Ending Program Execution ...... 236 Accessing Execution Parameters ...... 236
Appendixes ...... 237
Appendix A. Earlier Assembler Compatibility and Migration ...... 240 Comparison of Instruction Set and Assembler Instructions ...... 240 Comparison of Macro and Conditional Assembly Statements ...... 243 Comparison of Macro and Conditional Assembly ...... 246 Comparison of Language Features ...... 249 Comparison of Assembler Options ...... 252 Comparison of Assembler Listing ...... 254 viii HLASM V1R5 Programmer’s Guide Contents
Comparison of Diagnostic Features ...... 256 Other Assembler Differences ...... 258
Appendix B. Cross-System Portability Considerations ...... 259 | Using Machine Instructions ...... 259 Using System Macros ...... 259 Migrating Object Programs ...... 259
Appendix C. Object Deck Output ...... 261 ESD Record Format ...... 261 TXT Record Format ...... 263 RLD Record Format ...... 263 END Record Format ...... 264 SYM Record Format ...... 265
Appendix D. Associated Data File Output ...... 268 Record Types ...... 270 ADATA Record Layouts ...... 275 Common Header Section ...... 276 Job Identification Record—X'0000' ...... 277 ADATA Identification Record—X'0001' ...... 279 ADATA Compilation Unit Start/End Record—X'0002' ...... 279 | Output File Information Record—X'000A' ...... 279 | Options File Information—X'000B' ...... 283 Options Record—X'0010' ...... 284 External Symbol Dictionary Record—X'0020' ...... 289 Source Analysis Record—X'0030' ...... 290 Source Error Record—X'0032' ...... 293 DC/DS Record—X'0034' ...... 294 DC Extension Record—X'0035' ...... 302 DC extension record ...... 302 Machine Instruction Record—X'0036' ...... 302 Relocation Dictionary Record—X'0040' ...... 302 Symbol Record—X'0042' ...... 303 | Symbol and Literal Cross Reference Record—X'0044' ...... 304 Register Cross Reference Record—X'0045' ...... 305 Library Record—X'0060' ...... 306 Library Member and Macro Cross Reference Record—X'0062' ...... 307 User-supplied Information Record—X'0070' ...... 308 USING Map Record—X'0080' ...... 308 Statistics Record—X'0090' ...... 309
Appendix E. Sample Program ...... 313
Appendix F. MHELP Sample Macro Trace and Dump ...... 328
Appendix G. High Level Assembler Messages ...... 336 Message Code Format ...... 336 Message Descriptions ...... 337 Assembly Error Diagnostic Messages ...... 339 Message Not Known ...... 341 Messages ...... 342 Abnormal Assembly Termination Messages ...... 380 ASMAHL Command Error Messages (CMS) ...... 385
Contents ix Contents
Appendix H. User Interface Macros ...... 389
Appendix I. Sample ADATA User Exits (MVS and CMS) ...... 390 Sample ASMAXADT User Exit to Filter Records ...... 390 | Sample ASMAXADC User Exit to Control Record Output ...... 396 | Sample ASMAXADR User Exit to Reformat Records ...... 398
Appendix J. Sample LISTING User Exit (MVS and CMS) ...... 401
Appendix K. Sample SOURCE User Exit (MVS and CMS) ...... 403
Appendix L. How to Generate a Translation Table ...... 404
Appendix M. How to Generate a Unicode Translation Table ...... 406
| Appendix N. TYPECHECK Assembler Option ...... 411 | Extensions to the DC, DS, and EQU Assembler Instructions ...... 411 | Type Checking Behavior for REGISTER ...... 413 | Access Register Type Checking ...... 414 | General Rregister Type Checking ...... 415 | Control Register Type Checking ...... 418 | Floating-Point Register Type Checking ...... 419 | Type Checking Behavior for MAGNITUDE ...... 420
Notices ...... 422 Trademarks ...... 422
Glossary ...... 424
Bibliography ...... 429 High Level Assembler Publications ...... 429 Toolkit Feature Publications ...... 429 Related Publications (Architecture) ...... 429 Related Publications for MVS ...... 429 Related Publications for VM ...... 430 Related Publications for VSE ...... 430
Index ...... 431
x HLASM V1R5 Programmer’s Guide Organization of this Manual
About this Manual
This manual describes how to use the IBM High Level Assembler for MVS & VM & VSE licensed program, hereafter referred to as High Level Assembler, or simply the assembler. It is intended to help you assemble, link, and run your High Level Assembler programs. It is meant to be used in conjunction with the HLASM Language Reference.
Throughout this book, we use these indicators to identify platform-specific information: Prefix the text with platform-specific text (for example, “Under CMS...”) Add parenthetical qualifications (for example, “(CMS only)”) Bracket the text with icons. The following are some of the icons that we use: Informs you of information specific to MVS
Informs you of information specific to CMS
Informs you of information specific to VSE | MVS is used in this manual to refer to Multiple Virtual Storage/Enterprise Systems | Architecture (MVS/ESA), to OS/390, and to z/OS.
| CMS is used in this manual to refer to Conversational Monitor System on z/VM.
| VSE is used in this manual to refer to Virtual Storage Extended/Enterprise Systems | Architecture (VSE/ESA), and z/VSE.
Who Should Use this Manual The HLASM V1R5 Programmer's Guide is for application programmers coding in the High Level Assembler language. To use this manual, you should be familiar with the basic concepts and facilities of your operating system.
Programming Interface Information This manual is intended to help the customer create application programs. This manual documents General-Use Programming Interface and Associated Guidance Information provided by IBM High Level Assembler for MVS & VM & VSE.
General-use programming interfaces allow the customer to write programs that obtain the services of IBM High Level Assembler for MVS & VM & VSE.
Organization of this Manual This manual is organized as follows: Part 1. Understanding and Using the Assembler Chapter 1, Introduction, describes High Level Assembler, and defines the environmental requirements for using the assembler.
Copyright IBM Corp. 1982, 2004 xi Organization of this Manual