High Level Assembler for z/OS & z/VM & z/VSE 

General Information
Release 6

GC26-4943-05
High Level Assembler for z/OS & z/VM & z/VSE 

General Information
Release 6

GC26-4943-05
 Note!
Before using this information and the product it supports, be sure to read the general
information under “Notices” on page 87.

Sixth Edition (July 2008)

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 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
Reader Comments
DTX/E269
555 Bailey Avenue
SAN JOSE, CA 95141-1003
U.S.A.
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 1981, 2008. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About this manual . . . . . . . . . . v Specifying assembler options in the source
Who should use this manual . . . . . . . . . v program . . . . . . . . . . . . . . 16
Organization of this manual . . . . . . . . . v IBM-supplied default assembler options . . . . . 17
Hardcopy Publications . . . . . . . . . . vi
Online publications . . . . . . . . . . viii Chapter 4. Macro and conditional
assembly language extensions . . . . 19
Chapter 1. What’s new in High Level The macro language . . . . . . . . . . . 19
Assembler release 6 . . . . . . . . . 1 General advantages in using macros . . . . . 19
Assembler editing of the macro definition . . . 20
Chapter 2. Introduction to High Level Macro language extensions . . . . . . . . . 20
Redefining macros . . . . . . . . . . . 20
Assembler . . . . . . . . . . . . . . 3 Inner macro definitions . . . . . . . . . 21
Language compatibility . . . . . . . . . . . 3 Generated macro instruction operation codes . . 22
Highlights of High Level Assembler . . . . . . 3 Multilevel sublists in macro instruction operands 22
The Toolkit Feature . . . . . . . . . . . . 4 Macro instruction name entries . . . . . . . 23
Planning for High Level Assembler . . . . . . . 4 DBCS language support . . . . . . . . . 23
Year 2000 support for High Level Assembler. . . . 4 Source stream input—AREAD . . . . . . . 24
Source stream insertion—AINSERT . . . . . 25
Chapter 3. Assembler language Macro definition listing control—ASPACE and
extensions . . . . . . . . . . . . . 5 AEJECT . . . . . . . . . . . . . . 26
Additional assembler instructions . . . . . . . 5 Other macro language extensions . . . . . . 26
Revised assembler instructions . . . . . . . . 6 Conditional assembly language extensions . . . . 26
2-Byte relocatable address constants . . . . . . 8 External function calls . . . . . . . . . . 26
Character set support extensions . . . . . . . . 8 Built-in functions . . . . . . . . . . . 27
Standard character set . . . . . . . . . . 8 AIF instruction . . . . . . . . . . . . 27
Double-byte character set . . . . . . . . . 8 AGO instruction . . . . . . . . . . . . 27
Translation table . . . . . . . . . . . . 9 Extended continuation statements . . . . . . 27
Unicode support . . . . . . . . . . . . 9 SET symbols and SETx statements . . . . . . 27
Assembler language syntax extensions . . . . . . 9 Substring length value . . . . . . . . . . 30
Blank lines . . . . . . . . . . . . . . 9 Attribute references . . . . . . . . . . . 30
Comment statements . . . . . . . . . . 9 Redefining conditional assembly instructions . . 33
Mixed-case input . . . . . . . . . . . . 9 System variable symbols . . . . . . . . . 34
Continuation lines . . . . . . . . . . . 9 &SYSTIME and the AREAD statement . . . . 36
Continuation lines and double-byte data. . . . 10
Continuation error warning messages . . . . 10 Chapter 5. Using exits to complement
Symbol length . . . . . . . . . . . . 10 file processing . . . . . . . . . . . 37
Underscore . . . . . . . . . . . . . 11 User exit types . . . . . . . . . . . . . 37
Literals . . . . . . . . . . . . . . . 11 How to supply a user exit to the assembler . . . . 38
Levels within expressions . . . . . . . . . . 11 Passing data to I/O exits from the assembler source 38
Generalized object format modules (z/OS and CMS) 11 Statistics . . . . . . . . . . . . . . . 38
Extended addressing support . . . . . . . . 11 Disabling an exit . . . . . . . . . . . . 39
Addressing mode (AMODE) and residence mode Communication between exits . . . . . . . . 39
(RMODE) . . . . . . . . . . . . . . 11 Reading edited macros (VSE only) . . . . . . . 39
Channel Command Words (CCW0 and CCW1) 12 Sample exits provided with High Level Assembler
Programming sectioning and linking controls . . . 12 (z/OS and CMS) . . . . . . . . . . . . 39
Read-only control sections . . . . . . . . 12
Association of code and data areas . . . . . 13
Multiple location counters . . . . . . . . 13
Chapter 6. Programming and
External dummy sections . . . . . . . . . 13 diagnostic aids . . . . . . . . . . . 41
Number of external symbols . . . . . . . . 13 Assembler listings . . . . . . . . . . . . 41
Addressing extensions . . . . . . . . . . . 14 Option summary . . . . . . . . . . . 42
Labeled USINGs and qualified symbols . . . . 14 External Symbol Dictionary . . . . . . . . 45
Dependent USINGs. . . . . . . . . . . 15 Source and object . . . . . . . . . . . 46
Specifying assembler options in external file or Relocation dictionary . . . . . . . . . . 49
library member . . . . . . . . . . . . . 16 Ordinary symbol and literal cross reference . . . 50

© Copyright IBM Corp. 1981, 2008 iii

 Unreferenced symbols defined in CSECTs . . . 52 Appendix A. Assembler options . . . . 75
General Purpose Register cross reference . . . 52
Macro and copy code source summary . . . . 53 Appendix B. System variable symbols 79
Macro and copy code cross reference . . . . . 54
DSECT cross reference . . . . . . . . . . 55
USING map . . . . . . . . . . . . . 56 Appendix C. Hardware and software
Diagnostic cross reference and assembler requirements . . . . . . . . . . . . 83
summary . . . . . . . . . . . . . . 57 Hardware requirements . . . . . . . . . . 83
Improved page-break handling . . . . . . . 60 Software requirements . . . . . . . . . . . 83
Diagnostic messages in open code . . . . . . . 60 Assembling under z/OS . . . . . . . . . . 83
Macro-generated statements . . . . . . . . . 61 Assembling under VM/CMS . . . . . . . . 84
Sequence field in macro-generated statements . . 61 Assembling under VSE . . . . . . . . . . 85
Format of macro-generated statements . . . . 62
Macro-generated statements with PRINT Notices . . . . . . . . . . . . . . 87
NOGEN . . . . . . . . . . . . . . 62 Trademarks . . . . . . . . . . . . . . 88
Diagnostic messages in macro assembly . . . . . 63
Error messages for a library macro definition . . 63 Bibliography . . . . . . . . . . . . 89
Error messages for source program macro
High Level Assembler Publications . . . . . . 89
definitions . . . . . . . . . . . . . . 64
Toolkit Feature Publications . . . . . . . . . 89
Terminal output . . . . . . . . . . . . . 64
Related Publications (Architecture) . . . . . . 89
Input/output enhancements . . . . . . . . . 65
Related Publications for z/OS . . . . . . . . 89
CMS interface command . . . . . . . . . . 65
Related Publications for z/VM . . . . . . . . 89
Macro trace facility (MHELP) . . . . . . . . 66
Related Publications for z/VSE . . . . . . . . 90
Abnormal termination of assembly . . . . . . 67
Diagnosis facility . . . . . . . . . . . . 67
Index . . . . . . . . . . . . . . . 91
Chapter 7. Associated Data
Architecture . . . . . . . . . . . . 69

Chapter 8. Factors improving

performance . . . . . . . . . . . . 73

iv HLASM: V1R6 General Information

About this manual
This book contains general information about IBM High Level Assembler for z/OS
& z/VM & z/VSE, Licensed Program 5696-234, hereafter referred to as High Level
Assembler, or simply the assembler.

This book is designed to help you evaluate High Level Assembler for your data
processing operation and to plan for its use.

Who should use this manual

HLASM General Information helps data processing managers and technical
personnel evaluate High Level Assembler for use in their organization. This
manual also provides an introduction to the High Level Assembler Language for
system programmers and application programmers.

The assembler language supported by High Level Assembler has functional

extensions to the languages supported by Assembler H Version 2 and DOS/VSE
Assembler. To fully appreciate the features offered by High Level Assembler you
should be familiar with either Assembler H Version 2 or DOS/VSE Assembler.

Organization of this manual

This manual is organized as follows:
v Chapter 1, “What’s new in High Level Assembler release 6,” gives a summary
of the features and enhancements introduced in High Level Assembler Release 5.
v Chapter 2, “Introduction to High Level Assembler,” gives a summary of the
main features of the assembler and its purpose.
v Chapter 3, “Assembler language extensions,” describes the major extensions to
the basic assembler language provided by High Level Assembler, and not
available in earlier assemblers.
v Chapter 4, “Macro and conditional assembly language extensions,” briefly
describes some of the features of the macro and conditional assembly language,
and the extensions to the macro and conditional assembly language provided by
High Level Assembler that were not available in earlier assemblers.
v Chapter 5, “Using exits to complement file processing,” describes the facilities
in the assembler to support user-supplied input/output exits, and how these
might be used to complement the output produced by High Level Assembler.
v Chapter 6, “Programming and diagnostic aids,” describes the many assembly
listing and diagnostic features that High Level Assembler provides to help in the
development of assembler language programs and the location and analysis of
program errors.
v Chapter 7, “Associated Data Architecture,” gives a summary of the Associated
Data Architecture, and the associated data file produced by High Level
Assembler.
v Chapter 8, “Factors improving performance,” describes some of the methods
used by High Level Assembler to improve performance relative to earlier
assemblers.
v Appendix A, “Assembler options,” lists and describes the assembler options
you can specify with High Level Assembler.

© Copyright IBM Corp. 1981, 2008 v

Organization of this manual

v Appendix B, “System variable symbols,” lists and describes the system variable
symbols provided by High Level Assembler.
v Appendix C, “Hardware and software requirements,” provides information
about the operating system environments in which High Level Assembler will
operate.
v The Bibliography lists other IBM publications which may serve as a useful
reference to this book.

Throughout this book, we use these indicators to identify platform-specific

information:
v Prefix the text with platform-specific text (for example, “Under CMS...”)
v Add parenthetical qualifications (for example, “(CMS)”)
v Marking lines above and below the text. Here are some of the marking lines we
use:

z/OS

Informs you of information specific to z/OS®.

End of z/OS

z/VM

Informs you of information specific to z/VM®.

End of z/VM

z/VSE

Informs you of information specific to z/VSE™.

End of z/VSE

CMS is used in this manual to refer to Conversational Monitor System on z/VM.

Hardcopy Publications
The books in the High Level Assembler library are shown in Table 1. This figure
shows which books can help you with specific tasks, such as application
programming.
Table 1. IBM High Level Assembler for z/OS & z/VM & z/VSE Publications
Task Publication Order Number
Evaluation and Planning HLASM V1R6 General GC26-4943
Information
Installation and HLASM V1R6 Installation SC26-3494
Customization and Customization Guide
HLASM V1R6 Programmer’s SC26-4941
Guide
HLASM V1R6 Toolkit GC26-8711
Feature Installation Guide

vi HLASM: V1R6 General Information

 Organization of this manual

Table 1. IBM High Level Assembler for z/OS & z/VM & z/VSE Publications (continued)
Task Publication Order Number
Application HLASM V1R6 Programmer’s SC26-4941
Programming Guide
HLASM V1R6 Language SC26-4940
Reference
HLASM V1R6 General GC26-4943
Information
HLASM V1R6 Toolkit GC26-8710
Feature User’s Guide
HLASM V1R6 Toolkit GC26-8709
Feature Interactive Debug
Facility User’s Guide
Diagnosis HLASM V1R6 Installation SC26-3494
and Customization Guide
Warranty HLASM V1R6 Licensed GC26-4944
Program Specifications

HLASM General Information

Introduces you to the High Level Assembler product by describing what it
does and which of your data processing needs it can fill. It is designed to
help you evaluate High Level Assembler for your data processing
operation and to plan for its use.
HLASM Installation and Customization Guide
Contains the information you need to install and customize, and diagnose
failures in, the High Level Assembler product.
The diagnosis section of the book helps users determine if a correction for
a similar failure has been documented previously. For problems not
documented previously, the book helps users to prepare an APAR. This
section is for users who suspect that High Level Assembler is not working
correctly because of some defect.
HLASM Language Reference
Presents the rules for writing assembler language source programs to be
assembled using High Level Assembler.
HLASM Licensed Program Specifications
Contains a product description and product warranty information for High
Level Assembler.
HLASM Programmer’s Guide
Describes how to assemble, debug, and run High Level Assembler
programs.
HLASM Toolkit Feature Installation and Customization Guide
Contains the information you need to install and customize, and diagnose
failures in, the High Level Assembler Toolkit Feature.
HLASM Toolkit Feature User’s Guide
Describes how to use the High Level Assembler Toolkit Feature.
HLASM Toolkit Feature Debug Reference Summary
Contains a reference summary of the High Level Assembler Interactive
Debug Facility.

About this manual vii

Organization of this manual

HLASM Toolkit Feature Interactive Debug Facility User’s Guide

Describes how to use the High Level Assembler Interactive Debug Facility.

Online publications
The High Level Assembler publications are available in the following softcopy
formats:
v z/OS Collection CD-ROM: SK3T-4269 (Book), SK3T-8334 (PDF)
v z/VM Collection CD-ROM: SK2T-2401 (Book), SK3T-8330 (PDF)
v z/VSE Collection CD-ROM: SK2T-2402 (Book), SK3T-8331 (PDF)

For more information about High Level Assembler, see the High Level Assembler
web site, at
http://www-306.ibm.com/software/awdtools/hlasm/

viii HLASM: V1R6 General Information

Chapter 1. What’s new in High Level Assembler release 6
High Level Assembler Release 6 provides these enhancements over High Level
Assembler Release 5:

Changed Assembler instructions

v New QY-type and SY-type address constants provide resolution into
long-displacement.
v Support for three decimal floating-point data types, increasing instruction
addressability and reducing the need for additional instructions.

Unified Opcode table

v OPTABLE option
– The OPTABLE option is permitted on the *PROCESS statement.

Mnemonic tagging
v Suffix tags for instruction mnemonics let you use identically-named macro
instructions and machine instructions in the same source program.

New features
v High Level Assembler for Linux™ on System z™

New options
v WORKFILE

Changed assembler instructions

v DC/DS
– Decimal floating-point constants
– Unsigned binary constants

Changed assembler statements

v OPTABLE option for ACONTROL

Services Interface
v HLASM Services Interface for I/O exits added

Miscellany
v Qualifiers identified in symbol cross-reference.

High Level Assembler Release 6 requires processors supporting Architecture Level

Set 1 (ALS-1), for example:
v S/390® Multiprise® 3000 (or compatible server)
v S/390 Parallel Enterprise — G5, G6 (or compatible server)
v zSeries® z900, z990, and z800 servers (or compatible)
and later systems. For details, see
http://www.ibm.com/S390/os390/plug.html

© Copyright IBM Corp. 1981, 2008 1

What’s new in High Level Assembler release 6

2 HLASM: V1R6 General Information

Chapter 2. Introduction to High Level Assembler
High Level Assembler is an IBM licensed program that helps you develop
programs and subroutines to provide functions not typically provided by other
symbolic languages, such as COBOL, FORTRAN, and PL/I.

Language compatibility
The assembler language supported by High Level Assembler has functional
extensions to the languages supported by Assembler H Version 2 and DOS/VSE
Assembler. High Level Assembler uses the same language syntax, function,
operation, and structure as these earlier assemblers. The functions provided by the
Assembler H Version 2 macro facility are all provided by High Level Assembler.

Migration from Assembler H Version 2 or DOS/VSE Assembler to High Level

Assembler requires an analysis of existing assembler language programs to ensure
that they do not contain macro instructions with names that conflict with the High
Level Assembler symbolic operation codes, or SET symbols with names that
conflict with the names of High Level Assembler system variable symbols.

With the exception of these possible conflicts, and with appropriate High Level
Assembler option values, assembler language source programs written for
Assembler H Version 2 or DOS/VSE Assembler, that assemble without warning or
error diagnostic messages, should assemble correctly using High Level Assembler.

High Level Assembler, like its predecessor Assembler H Version 2, can assemble
source programs that use the following machine instructions:
v S/370™
v System/370 Extended Architecture (370-XA)
v Enterprise Systems Architecture/370™ (ESA/370)
v Enterprise Systems Architecture/390 (ESA/390)
v z/Architecture™

The set of machine instructions that you can use in an assembler source program
depend upon which operation code table you use for the assembly.

Highlights of High Level Assembler

High Level Assembler is a functional replacement for Assembler H Version 2 and
DOS/VSE Assembler. It offers all the proven facilities provided by these earlier
assemblers, and many new facilities designed to improve programmer productivity
and simplify assembler language program development and maintenance.

Some of the highlights of High Level Assembler are:

v Extensions to the basic assembler language
v Extensions to the macro and conditional assembly language, including external
function calls and built-in functions
v Enhancements to the assembly listing, including a new macro and copy code
member cross reference section, and a new section that lists all the unreferenced
symbols defined in CSECTs.
v New assembler options

© Copyright IBM Corp. 1981, 2008 3

Highlights of High Level Assembler

v A new associated data file, the ADATA file, containing both language-dependent
and language-independent records that can be used by debugging and other
tools
v A DOS operation code table to assist in migration from DOS/VSE Assembler
v The use of 31-bit addressing for most working storage requirements
v A generalized object format data set
v Internal performance enhancements and diagnostic capabilities

This book contains a summary of information designed to help you evaluate the
High Level Assembler licensed product. For more detailed information, see
HLASM Programmer’s Guide and HLASM Language Reference.

The Toolkit Feature

The optional High Level Assembler Toolkit Feature provides a powerful and
flexible set of tools to improve application recovery and development. The tools
include the Cross-Reference Facility, the Program Understanding Tool, the
Disassembler, the Interactive Debug Facility, Enhanced SuperC, and an extensive
set of Structured Programming Macros.

Planning for High Level Assembler

The assembler language and macro language extensions provided by High Level
Assembler include functional extensions to those provided by Assembler H Version
2 and the DOS/VSE assembler. The following chapters and appendices help you
evaluate these extensions, and plan the installation and customization process.
They include:
v A description of the language differences and enhancements that will help you
decide if there are any changes you need to make to existing programs.
v A summary of the assembler options to help you decide which ones are
appropriate to your installation.
v A summary of the system variable symbols to help you determine if they
conflict with symbols already defined in your programs.
v A description of the hardware and software required to install and run High
Level Assembler.

Year 2000 support for High Level Assembler

High Level Assembler is available as an element of z/OS. z/OS is certified as a
Year 2000 ready operating system by the Information Technology Association of
America (ITAA).

4 HLASM: V1R6 General Information

Chapter 3. Assembler language extensions
The instructions, syntax and coding conventions of the assembler language
supported by High Level Assembler include functional extensions to those
supported by Assembler H Version 2 and DOS/VSE Assembler. This chapter
describes the most important of those extensions, and the language differences
between High Level Assembler and the earlier assemblers.

Additional assembler instructions

The following additional assembler instructions are provided with High Level
Assembler:
*PROCESS statement:
The *PROCESS statement lets you specify assembler options in the
assembler source program. See “Specifying assembler options in the source
program” on page 16.
ACONTROL instruction:
The ACONTROL instruction lets you change many assembler options
within a program.
ADATA instruction:
The ADATA instruction allows user records to be written to the associated
data file.
ALIAS instruction:
The ALIAS instruction lets you replace an external symbol name with a
string of up to 64 bytes.
CEJECT instruction:
The CEJECT instruction allows page ejects to be done conditionally, under
operand control.
CATTR instruction (z/OS and CMS):
You can use the CATTR instruction to establish a program object external
class name, and assign binder attributes for the class. This instruction is
only valid when you specify the GOFF assembler option to produce
generalized object format modules. See “Generalized object format
modules (z/OS and CMS)” on page 11. By establishing the deferred load
attribute, text is not loaded when the program is brought into storage, but
is partially loaded, for fast access when it is requested.
EXITCTL instruction:
The EXITCTL instruction allows data to be passed from the assembler
source to any of the input/output user exits. See Chapter 5, “Using exits to
complement file processing,” on page 37.
RSECT instruction:
The RSECT instruction defines a read-only control section. See “Read-only
control sections” on page 12.
XATTR instruction (z/OS and CMS):
The XATTR instruction enables attributes to be assigned to an external
symbol. The instruction is only valid when you specify the GOFF
assembler option to produce generalized object format modules. See

© Copyright IBM Corp. 1981, 2008 5

 Additional assembler instructions

“Generalized object format modules (z/OS and CMS)” on page 11. The
linkage conventions for the symbol are established using this instruction.

Revised assembler instructions

Several assembler instructions used in earlier assemblers have been extended in
High Level Assembler.
CNOP instruction:
Symbols in the operand field of a CNOP instruction do not need to be
previously defined.
The operands of the CNOP instruction are extended to allow for any
boundary within a quadword to be specified. Valid values for the first
operand are the even numbers from 0 to 14 inclusive, while the values for
the second operand are 4, 8, or 16. Note that any present use of CNOP
may generate different object code but the new object code will not change
the execution.
COPY instruction:
Any number of nestings (COPY instructions within code that has been
brought into your program by another COPY instruction) is permitted.
However, recursive COPY instructions are not permitted.
A variable symbol that has been assigned a valid ordinary symbol may be
used as the operand of a COPY instruction in open code:
&VAR SETC ’LIBMEM’
COPY &VAR
+ COPY LIBMEM Generated Statement
DC instruction:
| The DC instruction has been enhanced to cater for the new binary and
| decimal floating-point numbers, Unicode character constants, and
doubleword fixed-point and A-type address constants. As well, the J-type,
Q-type and R-type address constants have been added.
A new data type, CA, has been added to indicate an ASCII character
constant type to be represented. This constant is not modified by the
| TRANSLATE option. The CE data type generates an EBCDIC constant that
| is not modified by the TRANSLATE option.
A new subfield has been added for the program type of symbol.
DROP instruction:
The DROP instruction now lets you end the domain of labeled USINGs
and labeled dependent USINGs. See “Labeled USINGs and qualified
symbols” on page 14 and “Dependent USINGs” on page 15.
DS instruction:
A new subfield has been added for the program type of symbol.
DXD instruction:
The DXD instruction now aligns external dummy sections to the most
restrictive alignment of the specified operands (instead of that of the first
operand).
EQU instruction:
Symbols appearing in the first operand of the EQU instruction do not need
to be previously defined. In the following example, both WIDTH and LENGTH
can be defined later in the source code:

6 HLASM: V1R6 General Information

 Revised assembler instructions

Name Operation Operand

VAL EQU 40-WIDTH+LENGTH

Two new operands are provided for the EQU instruction, a program-type
operand, and an assembler-type operand.
ISEQ instruction:
Sequence checking of any column on input records is allowed.
OPSYN instruction:
You can code OPSYN instructions anywhere in your source module.
ORG instruction:
Two new operands are provided for the ORG statement that will specify
the boundary and offset to be used to set the location counter.
The BOUNDARY operand is an absolute expression that must be a power
of 2 with a range from 8 (doubleword) to 4096 (page).
The OFFSET operand is any absolute expression.
If BOUNDARY and/or OFFSET are used, then the resultant location
counter will be calculated by rounding the expression up to the next
higher BOUNDARY and then adding the OFFSET value.
POP instruction:
An additional operand, NOPRINT, can be specified with the POP
instruction to cause the assembler to suppress the printing of the specified
POP statement. The operand ACONTROL saves the ACONTROL status.
PRINT instruction:
Seven additional operands can be specified with the PRINT instruction.
They are:
MCALL | NOMCALL
The MCALL operand instructs the assembler to print nested macro
call instructions.
The NOMCALL operand suppresses the printing of nested macro
call instructions.
MSOURCE | NOMSOURCE
The MSOURCE operand causes the assembler to print the source
statements generated during macro processing, as well as the
assembled addresses and generated object code of the statements.
The NOMSOURCE operand suppresses the printing of the
generated source statements, but does not suppress the printing of
the assembled addresses and generated object code.
UHEAD | NOUHEAD
The UHEAD operand causes the assembler to print a summary of
active USINGs following the TITLE line on each page of the source
and object program section of the assembler listing.
The NOUHEAD operand suppresses the printing of this summary.
NOPRINT
The NOPRINT operand causes the assembler to suppress the
printing of the PRINT statement that is specified.
The assembler has changed the way generated object code is printed in the
assembler listing when the PRINT NOGEN instruction is used. Now the

Chapter 3. Assembler language extensions 7

Revised assembler instructions

object code for the first generated instruction, or the first 8 bytes of
generated data is printed in the object code column of the listing on the
same line as the macro call instruction. The DC, DS, DXD, and CXD
instructions can cause the assembler to generate zeros as alignment data.
With PRINT NOGEN the generated alignment data is not printed in the
listing.
PUSH instruction:
An additional operand, NOPRINT, can be specified with the PUSH
instruction to cause the assembler to suppress the printing of the specified
PUSH statement. The operand ACONTROL restores the ACONTROL
status.
USING statements:
Labeled USINGs and dependent USINGs provide you with enhanced
control over the resolution of symbolic expressions into base-displacement
form with specific base registers. Dependent USINGs can be labeled or
unlabeled.
The end of range parameter lets you specify a range for the USING
statement, rather than accepting the default range. See “Labeled USINGs
and qualified symbols” on page 14 and “Dependent USINGs” on page 15.

2-Byte relocatable address constants

The assembler now accepts 2 as a valid length modifier for relocatable A-type
address constants, such as AL2(*). A 2-byte, relocatable, A-type address constant is
processed in the same way as a Y-type relocatable address constant, except that no
boundary alignment is provided.

Character set support extensions

High Level Assembler provides support for both standard single-byte characters
and double-byte characters.

Standard character set

The standard character set used by High Level Assembler is EBCDIC. A subset of
the EBCDIC character set can be used to code terms and expressions in assembler
language statements.

In addition, all EBCDIC characters can be used in comments and remarks, and
anywhere that characters can appear between paired single quotation marks.

Double-byte character set

In addition to the standard EBCDIC set of characters, High Level Assembler
accepts double-byte character set (DBCS) data.

When the DBCS option is specified, High Level Assembler accepts double-byte
data as follows:
v Double-byte data, optionally mixed with single-byte data, is permitted in:
– The nominal value of character (C-type) constants and literals
– The value of character (C-type) self-defining terms
– The operand of MNOTE, PUNCH and TITLE statements
v Pure double-byte data is supported by:
– The pure DBCS (G-type) constant and literal
– The pure DBCS (G-type) self-defining term

8 HLASM: V1R6 General Information

 Character set support extensions

Double-byte data in source statements must always be bracketed by the shift-out

(SO) and shift-in (SI) characters to distinguish it from single-byte data.

Double-byte data is supported in the operands of the AREAD and REPRO

statements, and in comments and remarks, regardless of the invocation option.
Double-byte data assigned to a SETC variable symbol by an AREAD statement
contain the SO and SI.

Translation table
In addition to the standard EBCDIC set of characters, High Level Assembler can
use a user-specified translation table to convert the characters contained in
character (C-type) data constants (DCs) and literals. High Level Assembler
provides a translation table to convert the EBCDIC character set to the ASCII
character set. The assembler can also use a translation table supplied by the
programmer.

Unicode support
High Level Assembler can be used to create Unicode character constants. The
CODEPAGE option selects which codepage to use and the CU constant is used to
define the data that will be translated into the Unicode.

Assembler language syntax extensions

The syntax of the assembler language deals with the structure of individual
elements of any instruction statement, and with the order that the elements are
presented in that statement. Several syntactical elements of earlier assembler
languages are extended in the High Level Assembler language.

Blank lines
High Level Assembler allows blank lines to be used in the source program. In open
code, each blank line is treated as equivalent to a SPACE 1 statement. In the body
of a macro definition, each blank line is treated as equivalent to an ASPACE 1
statement.

Comment statements
A macro comment statement consists of a period in the begin column, followed by
an asterisk, followed by any character string. An open code comment consists of an
asterisk in the begin column followed by any character string.

High Level Assembler allows open code statements to use the macro comment
format, and processes them like an open code comment statement.

Mixed-case input
High Level Assembler allows mixed-case input statements, and maintains the case
when it produces the assembler listing. You can use the COMPAT and FOLD
assembler options to control how the assembler treats mixed-case input.

Continuation lines
You are allowed as many as nine continuation lines for most ordinary assembler
language statements. However, you are allowed to specify as many continuation
lines as you need for the following statements:
v Macro prototype statements
v Macro instruction statements

Chapter 3. Assembler language extensions 9

 Assembler language syntax extensions

v The AIF, AGO, SETx, LCLx, and GBLx conditional assembly instructions.

When you specify the FLAG(CONT) assembler option, the assembler issues new
warning messages if it suspects that a continuation statement might be incorrect.

Continuation lines and double-byte data

If the assembler is called with the DBCS option, then:
v When an SI occurs in the end column of a continued line, and an SO occurs in
the continue column of the next line, the SI and SO are considered redundant
and are removed from the statement before the statement is analyzed.
v An extended continuation indicator provides you with a flexible end column on
a line-by-line basis so that any alignment of double-byte data in a source
statement can be supported.

Continuation error warning messages

The FLAG(CONT) assembler option directs the assembler to issue warning
messages for continuation statement errors for macro calls in the following
circumstances:
v The operand on the continued record ends with a comma and a continuation
statement is present but continuation does not start in the continue column
(usually column 16).
v A list of one or more operands ends with a comma, but the continuation column
(usually column 72) is blank.
v The continuation record starts in the continue column (usually column 16) but
there is no comma present following the operands on the previous record.
v The continued record is full but the continuation record does not start in the
continue column (usually column 16).

Symbol length
High Level Assembler supports three types of symbols:
Ordinary symbols
The format of an ordinary symbol consists of an alphabetic
character, followed by a maximum of 62 alphanumeric characters.
Variable symbols
The format of a variable symbol consists of an ampersand (&)
followed by an alphabetic character, followed by a maximum of 61
alphanumeric characters.
Sequence symbols
The format of a sequence symbol consists of a period (.) followed
by an alphabetic character, followed by a maximum of 61
alphanumeric characters.

External symbols are ordinary symbols used in the name field of START, CSECT,
RSECT, COM, DXD, and ALIAS statements, and in the operand field of ENTRY,
EXTRN, WXTRN, and ALIAS statements. Symbols used in V-type and Q-type
| address constants are restricted to 8 characters, unless the GOFF option is
| specified, which allows symbols up to 63 characters. You can specify an alias string
of up to 64 characters to represent an external symbol.

10 HLASM: V1R6 General Information

 Assembler language syntax extensions

Underscore
High Level Assembler accepts the underscore character as alphabetic. It is accepted
in any position in any symbol name.

Literals
The following changes have been made to previous restrictions on the use of
literals:
v Literals can be used as relocatable terms in expressions. They no longer have to
be used as a complete operand.
v Literals can be used in RX-format instructions in which an index register is used.

Levels within expressions

The number of terms or levels of parentheses in an expression is limited by the
storage buffer size allocated by the assembler for its evaluation work area.

Generalized object format modules (z/OS and CMS)

High Level Assembler provides support for generalized object format modules.
The GOFF or XOBJECT assembler option instructs the assembler to produce the
generalized object data set. The following new or modified instructions support the
generation of the generalized object format records:
v ALIAS
v AMODE
v RMODE
v CATTR
v XATTR

For further details about this facility refer to DFSMS/MVS V1R4 Program
Management.

Extended addressing support

High Level Assembler provides several instructions for the generation of object
modules that exploit extended addressing. These instructions are:
v AMODE
v RMODE
v CCW0
v CCW1

Addressing mode (AMODE) and residence mode (RMODE)

Use the AMODE instruction to specify the addressing mode to be associated with
the control sections in the object program. The addressing modes are:
24 24-bit addressing mode
31 31-bit addressing mode
64 64-bit addressing mode - See note below
ANY The same as ANY31
ANY31 24-bit or 31-bit addressing mode
ANY64 24-bit, 31-bit, or 64-bit addressing mode

Use the RMODE instruction to specify the residence mode to be associated with
the control sections in the object program. The residence modes are:
24 Residence mode of 24. The control section must reside below the
16MB line.

Chapter 3. Assembler language extensions 11

Extended addressing support

31 Residence mode of either 24 or 31. The control section can reside

above or below the 16MB line.
64 Residence mode of 64 - See note below.
ANY Is understood to mean RMODE(31).

You can specify the AMODE and RMODE instructions anywhere in the assembly
source. If the name field in either instruction is left blank, you must have an
unnamed control section in the assembly. These instructions do not initiate an
unnamed control section.

Note: The 64-bit addressing and residence modes are accepted and processed by
the assembler. However, other operating system components and utility
programs may not be able to accept and process information related to these
operands.

Channel Command Words (CCW0 and CCW1)

The CCW0 instruction performs the same function as the CCW instruction, and is
used to define and generate a format-0 channel command word that allows a 24-bit
data address. The CCW1 instruction result is used to define and generate a
format-1 channel command word that allows a 31-bit data address.

The format of the CCW0 and CCW1 instructions, like that of the CCW instruction,
consists of a name field, the operation, and an operand (that contains a command
code, data address, flags, and data count).
Using EXCP or EXCPVR access methods:
If you use the EXCP or EXCPVR access method, only CCW or
CCW0 is valid, because EXCP and EXCPVR do not support 31-bit
data addresses in channel command words.
Using RMODE ANY:
If you use RMODE ANY with CCW or CCW0, an invalid data
address in the channel command word can result at execution
time.

Programming sectioning and linking controls

High Level Assembler provides several facilities that allow increased control of
program organization. These include:
v Association of code and data areas
v Multiple location counters
v Multiple classes and parts for code and data
v External dummy sections
v Support for up to 65535 external symbols

Read-only control sections

With the RSECT instruction, you can initiate a read-only executable control section,
or continue a previously initiated read-only executable control section.

When a control section is initiated by the RSECT instruction, the assembler

automatically checks the control section for non-reentrant code. As the assembler
cannot check program logic, the checking is not exhaustive. If the assembler detects
non-reentrant code it issues a warning message.

The read-only attribute in the object module shows which control sections are
read-only.

12 HLASM: V1R6 General Information

 Programming sectioning and linking controls

Association of code and data areas

To provide for the support of application program reentrancy and dynamic
binding, the assembler provides a way to associate code and data areas. This is
achieved by defining and accessing ’associated data areas’ which are referred to as
PSECTs. A PSECT, when instantiated, becomes the working storage for an
invocation of a reentrant program.

Multiple location counters

Multiple location counters are defined in a control section by using the LOCTR
instruction. The assembler assigns consecutive addresses to the segments of code
using one location counter before it assigns addresses to segments of code using
the next location counter. By using the LOCTR instruction, you can cause your
program object-code structure to differ from the logical order appearing in the
listing. You can code sections of a program as independent logical and sequential
units. For example, you can code work areas and constants within the section of
code that requires them, without branching around them. Figure 1 shows this
procedure.

┌───────────────────────────┐
│ MAINCODE LOCTR │
│ • ├────────────────────────────┐
│ • │ │
└───────────────────────────┘ │
│
┌───────────────────────────┐ │
│ WORKAREA LOCTR │ Addresses follow │ Assembled with
│ XXX DC XXX ├─── combined sections ├─── consecutive
│ XXX DS XXX │ of MAINCODE │ addresses
└───────────────────────────┘ │
│
┌───────────────────────────┐ │
│ MAINCODE LOCTR │ │
│ • ├────────────────────────────┘
│ • │
└───────────────────────────┘

Figure 1. LOCTR instruction application

External dummy sections

An external dummy section is a reference control section that you can use to describe
a communication area between two or more object modules that are link-edited
together. The assembler generates an external dummy section when you define a
Q-type address constant that contains the name of a reference control section
specified in a DXD or DSECT instruction.

z/VSE

External dummy sections are only supported by VSE/ESA™ Version 2 Release 2 or

later.
End of z/VSE

Number of external symbols

The assembler can support up to 65535 independently relocatable items. Such
items include control section names, names declared in EXTRNs and so forth. The

Chapter 3. Assembler language extensions 13

Programming sectioning and linking controls

names of some of these items can appear in the external symbol dictionary (ESD)
of the assembler’s object module. Note that other products might not be able to
handle as many external symbols as the assembler can produce.

Assembler instructions that can produce independently relocatable items and

appear in the ESD are:
v START
v CSECT
v RSECT
v COM
v DXD
v EXTRN
v WXTRN
v ALIAS
v CATTR
v V-type address constant
v DSECT if the DSECT name appears in a Q-type address constant

Many instructions can cause the initiation of an unnamed CSECT if they appear
before a START or CSECT statement. Unnamed CSECTs appear in the external
symbol dictionary with a type of PC.

Addressing extensions
High Level Assembler extends the means that you can use to establish
addressability of a control section with two powerful new facilities:
v Labeled USINGs and qualified symbols
v Dependent USINGs

Labeled USINGs and qualified symbols

The format of the assembler USING instruction now lets you code a symbol in the
name entry of the instruction. When a valid ordinary symbol, or a variable symbol
that has been assigned a valid ordinary symbol, is specified in the name entry of a
USING instruction, it is known as the USING label, and the USING is known as a
labeled USING.

Labeled USINGs provide you with enhanced control over the resolution of symbolic
expressions into base-displacement form with specific base registers. The assembler
uses a labeled USING when you qualify a symbol with the USING label. You
qualify a symbol by prefixing the symbol with the label on the USING followed by
a period.

Labeled USING domains

You can specify the same base register or registers in any number of labeled
USING instructions. However, unlike ordinary USING instructions, as long as all
the labeled USINGs have unique labels, the assembler considers the domains of all
the labeled USINGs to be active and their labels can be used as qualifiers. With
ordinary USINGs, when you specify the same base register in a subsequent USING
instruction, the domain of the prior USING is ended.

The domain of a labeled USING instruction continues until the end of a source
module, except when:
v You specify the label in the operand of a subsequent DROP instruction.
v You specify the same label in a subsequent USING instruction.

14 HLASM: V1R6 General Information

 Addressing extensions

Labeled USING ranges

You can specify the same base address in any number of labeled USING
instructions. You can also specify the same base address in an ordinary USING and
a labeled USING. However, unlike ordinary USING instructions that have the
same base address, if you specify the same base address in an ordinary USING
instruction and a labeled USING instruction, the assembler does not treat the
USING ranges as coinciding. When you specify an unqualified symbol in an
assembler instruction, the assembler uses the base register specified in the ordinary
USING to resolve the address into base-displacement form. You can specify an
optional parameter on the USING instruction. This option sets the range of the
USING, overwriting the default of 4096.

Dependent USINGs
The format of the assembler USING instruction now lets you specify a relocatable
expression instead of a base register in the instruction operand. When you specify
a relocatable expression, it is known as the supporting base address, and the USING
is known as a dependent USING. If a valid ordinary symbol, or a variable symbol
that has been assigned a valid ordinary symbol, is specified in the name entry of a
dependent USING instruction, the USING is known as a labeled dependent USING.

A dependent USING depends on the presence of one or more corresponding

ordinary or labeled USINGs to resolve the symbolic expressions in the dependent
USING range.

Dependent USINGs provide you with further control over the resolution of
symbolic expressions into base-displacement form. With dependent USINGs you
can reduce the number of base registers you need for addressing by using an
existing base register to provide addressability to the symbolic address.

Dependent USING domains

The domain of a dependent USING begins where the dependent USING
instruction appears in the source module and continues until the end of the source
module, except when:
v You end the domain of the corresponding ordinary USING by specifying the
base register or registers from the ordinary USING instruction in a subsequent
DROP instruction.
v You end the domain of the corresponding ordinary USING by specifying the
same base register or registers from the ordinary USING instruction in a
subsequent ordinary USING instruction.
v You end the domain of a labeled dependent USING by specifying the label of
the labeled dependent USING in the operand of a subsequent DROP instruction.

Dependent USING ranges

The range of a dependent USING is 4096 bytes, or as limited by the end operand,
beginning at the base address specified in the corresponding ordinary or labeled
USING instruction. If the corresponding ordinary or labeled USING assigns more
than one base register, the dependent USING range is the composite USING range
of the ordinary or labeled USING.

If the dependent USING instruction specifies a supporting base address that is

within the range of more than one ordinary USING, the assembler determines
which base register to use during base-displacement resolution as follows:
v The assembler computes displacements from the ordinary USING base address
that gives the smallest displacement, and uses the corresponding base register.

Chapter 3. Assembler language extensions 15

Addressing extensions

v If more than one ordinary USING gives the smallest displacement, the assembler
uses the higher-numbered register for assembling addresses within the
coinciding USING ranges.

Specifying assembler options in external file or library member

High Level Assembler accepts options from an external file (z/OS and CMS) or
library member (VSE). The file or library member may contain multiple records.
This facility is provided to help avoid the limitation in both z/VSE and z/OS
which restricts the length of the options list to 100 characters.

Specifying assembler options in the source program

Process (*PROCESS) statements let you specify selected assembler options in the
assembler source program. You can include them in the primary input data set or
provide them from a SOURCE user exit.

You can specify a maximum of 10 process statements in one assembly. After

processing 10 process statements, the assembler treats the next input record as an
ordinary assembler statement; in addition the assembler treats further process
statements as comment statements. You cannot continue a process statement from
one statement to the next.

When the assembler detects an error in a process statement, it produces one or

more warning messages. If the installation default option PESTOP is set, then the
assembler stops after it finishes processing any process statements. If the keyword
OVERRIDE is added to a process statement, then the nominated assembler option
is not overridden by specifications at a lower level of precedence. If the specified
option is not accepted on a process statement and a different value has been
supplied as an invocation or input file option, the option is not accepted and a
warning message is issued.

The ACONTROL instruction lets you specify selected assembler options anywhere
through the assembler source program, rather than at the beginning of the source
(as provided by *PROCESS statements).

The assembler recognizes the assembler options in the following order of

precedence (highest to lowest):
1. Fixed installation defaults
2. Options on *PROCESS OVERRIDE statements
3. Options in the External File (z/OS and CMS) or Library member (z/VSE)
4. Options on the PARM parameter of the JCL EXEC statement under z/OS and
z/VSE or the High Level Assembler command under CMS
5. Options on the JCL OPTION statement (z/VSE only)
6. Options specified via the STDOPT (Standard JCL Options) command (z/VSE)
7. Options on *PROCESS statements
8. Non-fixed installation defaults

Options specified by the ACONTROL instruction take effect when the specifying
ACONTROL instruction is encountered during the assembly. An option specified
by an ACONTROL instruction may override an option specified at the start of the
assembly.

16 HLASM: V1R6 General Information

 Specifying assembler options in external file or library member

The assembler lists the options specified in process statements in the High Level
Assembler Option Summary section of the assembler listing.

Process statements are also shown as comment lines in the source and object section
of the assembler listing.

IBM-supplied default assembler options

Table 2 shows the changes made to the IBM-supplied default assembler options for
High Level Assembler Release 5:
Table 2. Changes to High Level Assembler default options
New in Release 6 Previously in Release 5
WORKFILE Not available

See Appendix A, “Assembler options,” on page 75 for a list of all assembler

options.

Chapter 3. Assembler language extensions 17

18 HLASM: V1R6 General Information
Chapter 4. Macro and conditional assembly language
extensions
The macro and conditional assembly language supported by High Level Assembler
provides a number of functional extensions to the macro languages supported by
Assembler H Version 2 and DOS/VSE Assembler. This chapter provides an
overview of the language, and describes the major extensions.

The macro language

The macro language is an extension of the assembler language. It provides a
convenient way to generate a preferred sequence of assembler language statements
many times in one or more programs. There are two parts to the macro language
supported by High Level Assembler:
Macro definition
A named sequence of statements you call with a macro instruction. The
name of the macro is the symbolic operation code used in the macro
instruction. Macro definitions can appear anywhere in your source module;
they can even be nested within other macro definitions. Macros can also be
redefined at a later point in your program.
Macro instruction
Calls the macro definition for processing. A macro instruction can pass
information to the macro definition which the assembler uses to process
the macro.

There are two types of macro definition:

Source macro definition
A macro definition defined in your source program.
Library macro definition
A macro definition that resides in a library data set.

Either type of macro definition can be called from anywhere in the source module
by a macro instruction, however a source macro definition must occur before it is
first called.

You use a macro prototype statement to define the name of the macro and the
symbolic parameters you can pass it from a macro instruction.

General advantages in using macros

The main use of a macro is to insert assembler language statements into your
source program each time the macro definition is called by a macro instruction.
Values, represented by positional or keyword symbolic parameters, can be passed
from the calling macro instruction to the statements within the body of a macro
definition. The assembler can use global SET symbols and absolute ordinary
symbols created by other macros and by open code.

The assembler assigns attribute values to the ordinary symbols and variable
symbols that represent data. By referencing the data attributes of these symbols, or

© Copyright IBM Corp. 1981, 2008 19

The macro language

by varying the values assigned to these symbols, you can control the logic of the
macro processing, and, in turn, control the sequence and contents of generated
statements.

The assembler replaces the macro call with the statements generated from the
macro definition. The generated statements are then processed like open code
source statements.

Using macros gives you a flexibility similar to that provided by a problem-oriented

language. You can use macros to create your own procedural language, tailored to
your specific applications.

Assembler editing of the macro definition

The initial processing of a macro definition is called editing. In editing, the
assembler checks the syntax of the instructions and converts the source statements
to an edited version used throughout the remainder of the assembly. The edited
version of the macro definition is used to generate assembler language statements
when the macro is called by a macro instruction. This is why a macro must always
be edited, and consequently be defined, before it can be called by a macro
instruction.

z/VSE

“Reading edited macros (VSE only)” on page 39 describes how you can use a
LIBRARY exit to allow High Level Assembler to read edited macros.
End of z/VSE

Macro language extensions

Extensions to the macro language include the following:
v Macro redefinition facilities
v Inner macro definitions
v Multilevel sublists in macros
v DBCS language support
v AINSERT instruction that enables the creation of records to be inserted into the
assembler’s input stream
v Instructions to control the listing of macro definitions
v Support for internal and external arithmetic and character functions
v Many new system variable symbols

Redefining macros
You can redefine a macro definition at any point in your source module. When a
macro is redefined, the new definition is effective for all subsequent macro
instructions that call it.

You can save the function of the original macro definition by using the OPSYN
instruction before you redefine the macro. If you want to reestablish the initial
function of the operation code, you can include another OPSYN instruction to
redefine it. The following example shows this:
Name Operation Operand Comment

MACRO
MAC1 , The symbol MAC1 is assigned as the
name of this macro definition.

20 HLASM: V1R6 General Information

 Macro language extensions

.
.
.
MEND
.
.
.
MAC2 OPSYN MAC1 MAC2 is assigned as an alias for MAC1.
MACRO
MAC1 , MAC1 is assigned as the name of this
new macro definition.
.
.
.
MEND
.
.
.
MAC1 OPSYN MAC2 MAC1 is assigned to the first
definition. The second
definition is lost.

You can issue a conditional assembly branch (AGO or AIF) to a point before the
initial definition of the macro and reestablish a previous source macro definition.
Then that definition will be edited and effective for subsequent macro instructions
calling it.

See “Redefining conditional assembly instructions” on page 33.

Inner macro definitions

High Level Assembler allows both inner macro instructions and inner macro
definitions. The inner macro definition is not edited until the outer macro is
generated as the result of a macro instruction calling it, and then only if the inner
macro definition is encountered during the generation of the outer macro. If the
outer macro is not called, or if the inner macro is not encountered in the
generation of the outer macro, the inner macro definition is never edited. Figure 2
on page 22 shows the editing of inner macro definitions.

Chapter 4. Macro and conditional assembly language extensions 21

 Macro language extensions

┌─────────────┐
│ MACRO │
│ MAC1 ├─────────────────────────────────────┐
│ • │ │
└─────────────┘ │
┌─────────────┐ │
│ MACRO │ │
│ MAC2 ├──────────────────┐ │
│ • │ │ │
└─────────────┘ │ │
┌─────────────┐ │ │
│ MACRO │ │ │
│ MAC3 │ │ │
│ • │ Edited when │ Edited when │ Edited when
│ • ├── MAC2 is called ├── MAC1 is called ├── definition first
│ • │ and generated │ and generated │ encountered
│ • │ │ │
│ MEND │ │ │
└─────────────┘ │ │
┌─────────────┐ │ │
│ • ├──────────────────┘ │
│ MEND │ │
└─────────────┘ │
┌─────────────┐ │
│ • ├─────────────────────────────────────┘
│ MEND │
└─────────────┘

Figure 2. Editing inner macro definitions

First MAC1 is edited, and MAC2 and MAC3 are not. When MAC1 is called, MAC2 is edited
(unless its definition is bypassed by an AIF or AGO branch); when MAC2 is called,
MAC3 is edited. No macro can be called until it has been edited.

There is no limit to the number of nestings allowed for inner macro definitions.

Generated macro instruction operation codes

Macro instruction operation codes can be generated by substitution, either in open
code or inside macro definitions.

Multilevel sublists in macro instruction operands

Multilevel sublists (sublists within sublists) are permitted in macro instruction
operands and in the keyword default values in prototype statements, as shown in
the following:
MAC1 (A,B,(W,X,(R,S,T),Y,Z),C,D)
MAC2 &KEY=(1,12,(8,4),64)

The depth of this nesting is limited only by the constraint that the total length of
| an individual operand cannot exceed 1024 characters.

To access individual elements at any level of a multilevel operand, you use

additional subscripts after &SYSLIST or the symbolic parameter name. Table 3 on
page 23 shows the value of selected elements if &P is the first positional parameter
and the value assigned to it in a macro instruction is (A,(B,(C)),D).

22 HLASM: V1R6 General Information

 Macro language extensions

Table 3. Multilevel sublists

Selected Elements Selected Elements Value of
from &P from &SYSLIST Selected Element

&P &SYSLIST(1) (A,(B,(C)),D)

&P(1) &SYSLIST(1,1) A
&P(2) &SYSLIST(1,2) (B,(C))
&P(2,1) &SYSLIST(1,2,1) B
&P(2,2) &SYSLIST(1,2,2) (C)
&P(2,2,1) &SYSLIST(1,2,2,1) C
&P(2,2,2) &SYSLIST(1,2,2,2) null
N’&P(2,2) N’&SYSLIST(1,2,2) 1
N’&P(2) N’&SYSLIST(1,2) 2
N’&P(3) N’&SYSLIST(1,3) 1
N’&P N’&SYSLIST(1) 3

Sublists may also be assigned to SETC symbols and used in macro instruction
operands. However, if you specify the COMPAT(SYSLIST) assembler option, the
assembler treats sublists in SETC symbols as character strings, not sublists, when
used in the operand of macro instructions.

Macro instruction name entries

You can write a name field parameter on the macro prototype statement. You can
then assign a value to this parameter from the name entry in the calling macro
(instruction). Unlike in earlier assemblers, the name entry need not be a valid
symbol.

The name entry of a macro instruction can be used to:

v Pass values into the called macro definition.
v Provide a conditional assembly label (sequence symbol) so that you can branch
to the macro instruction during conditional assembly.

DBCS language support

Double-byte data is supported by the macro language with the following:
v The addition of a pure DBCS (G-type) self-defining term.
v Double-byte data is permitted in the operands of the MNOTE, PUNCH and
TITLE statements.
v The REPRO statement exactly reproduces the record that follows it, whether it
contains double-byte data or not.
v Double-byte data can be used in the macro language, wherever quoted EBCDIC
character strings can be used.
v When a shift-in (SI) code is placed in the end column of a continued line, and a
shift-out (SO) code is placed in the continue column of the next line, the SI and
SO are considered redundant and are removed from the statement before it is
analyzed.
v Redundant SI/SO pairs are removed when double-byte data is concatenated
with double-byte data.
v An extended continuation indicator provides the ability to:
– Extend the end column to the left on a line-by-line basis, so that any
alignment of double-byte data in a source statement can be supported.

Chapter 4. Macro and conditional assembly language extensions 23

Macro language extensions

– Preserve the readability of a macro-generated statement on a DBCS device by

splitting double-byte data across listing lines with correct SO/SI bracketing.

Source stream input—AREAD

The AREAD assembler operation permits a macro to read a record directly from
the source stream into a SETC variable symbol. The card image is assigned in the
form of an 80-byte character string to the symbol specified in the name field of the
instruction. Figure 3 shows how the instruction is used:

Open Code Macro Definition

• 2 MACRO
• MAC
• •
1 MAC •
4 JOHN L. SMITH ────┤3 &S AREAD
│ •
│ •
│ MEND
│
│

5 &S contains │J O H N L . S M I T H │

└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴...┴─┘
1 6 11 80

Figure 3. AREAD assembler operation

The assembler processes the instructions in Figure 3 as follows:

The macro instruction MAC (1) causes the macro MAC (2) to be called. When the
AREAD instruction (3) is encountered, the next sequential record (4) following
the macro instruction is read and assigned to the SETC symbol &S (5).

Repeated AREAD statements read successive records.

When macro instructions are nested, the records read by AREAD must always
follow the outermost macro instruction regardless of the level of nesting in which
the AREAD instruction is found.

If the macro instruction is found in code brought in by the COPY instruction (copy
code), the records read by the AREAD instruction can also be in the copy code. If
no more records exist in the copy code, subsequent records are read from the
ordinary input stream.

Records that are read in by the AREAD instruction are not checked by the
assembler. Therefore, no diagnostic is issued if your AREAD statements read
records that are meant to be part of your source program. For example, if an
AREAD statement is processed immediately before the END instruction, the END
instruction is lost to the assembler.

24 HLASM: V1R6 General Information

 Macro language extensions

AREAD listing options

Normally, the AREAD input records are printed in the assembler listing and
assigned statement numbers. However, if you do not want them to be printed or
assigned statement numbers, you can specify NOPRINT or NOSTMT in the
operand of the AREAD instruction.

AREAD clock functions

You can specify the CLOCKB or CLOCKD operand in the AREAD instruction to
obtain the local time. The time is assigned to the SETC symbol you code in the
name field of the AREAD instruction. The CLOCKB operand obtains the time in
hundredths of a second. The CLOCKD operand obtains the time in the format
HHMMSSTH.

Macro input/output capability

The AREAD facility complements the PUNCH facility to provide macros with
direct input/output (I/O) capability. The total I/O capability of macros is as
follows:
Implied input: Parameter values and global SET symbol values
that are passed to the macro
Implied output: Generated statements passed to the assembler for
later processing. See also the AINSERT operation
below.
Direct input: AREAD
Direct output: MNOTE for printed messages; PUNCH for
punched records
Conditional I/O: SET symbol values provided by external functions,
using the SETAF and SETCF conditional assembly
instructions.

For example, you can use AREAD and PUNCH to write simple conversion
programs. The following macro interchanges the left and right halves of records
placed immediately after a macro instruction calling it. End-of-input is indicated
with the word FINISHED in the first columns of the last record in the input to the
macro.
Name Operation Operand

MACRO
SWAP
.loop ANOP
&CARD AREAD
AIF (’&CARD’(1,8) EQ ’FINISHED’).MEND
&CARD SETC ’&CARD’(41,40).’&CARD’(1,40)
PUNCH ’&CARD’
AGO .LOOP
.MEND MEND

Source stream insertion—AINSERT

The AINSERT assembler operation inserts statements into the input stream. The
statements are stored in an internal buffer until the macro generator is completed.
Then the internal buffer is used to provide the next statements. An operand
controls the sequence of insertion of statements within the buffer. Statements can
be inserted at the front or back of the queue, though they are removed only from
the front of the queue.

Chapter 4. Macro and conditional assembly language extensions 25

Macro language extensions

Macro definition listing control—ASPACE and AEJECT

You can use the ASPACE and AEJECT instructions to control the listing of your
macro definitions. The ASPACE instruction is similar to the SPACE instruction, but
instead of controlling the listing of your open code, you can use it to insert one or
more blank lines in your macro definition listing. Similarly, the AEJECT instruction
is like the EJECT instruction, but you can use it to stop printing the macro
definition on the current page and continue printing on the next page.

Other macro language extensions

High Level Assembler provides the following extensions to some earlier macro
languages:
v You can insert blank lines in macro definitions provided they are not
continuation lines. See also “Blank lines” on page 9.
v Macro names, variable symbols (including the ampersand), and sequence
symbols (including the period), can be a maximum of 63 alphanumeric
characters.
v You can insert comments (both ordinary and internal macro types) between the
macro header and the prototype and, for library macros, before the macro
header. These comments are not printed with the macro generation.
v You can use a macro definition to redefine any machine or assembler instruction.
When you subsequently use the machine or assembler instruction the assembler
interprets it as a macro call.
v You can include any instruction, except ICTL and *PROCESS statements, in a
macro definition.
v You no longer need to precede the SET symbol name with an ampersand in
LCLx and GBLx instructions, except for created SET symbols.
v The SETA and SETB instructions now allow you to use predefined absolute
symbols in arithmetic expressions.

Conditional assembly language extensions

Extensions to the conditional assembly language provides you with a flexible and
powerful tool to increase your productivity, and simplify your coding needs. These
include:
v New instructions that support external function calls
v New built-in functions
v Extensions to existing instructions
v Extensions to SET symbol usage
v New system variable symbols
v New data attributes

External function calls

You can use the new SETAF and SETCF instructions to call your own routines to
provide values for SET symbols. The routines, which are called external functions,
can be written in any programming language that conforms to standard OS linkage
conventions. The format of the SETAF and SETCF instructions is the same as a
SETx instruction, except that the first operand of SETAF is a character string.

The assembler calls the external function load module, and passes it the address of
an external function parameter list. Each differently named external function called
in the same assembly is provided with a separate parameter list.

26 HLASM: V1R6 General Information

 Conditional assembly language extensions

SETAF instruction:
You use the SETAF instruction to pass parameters containing arithmetic
values to the external function module. The symbol in the name field of
the instruction is assigned the fullword integer value returned by the
external function module.
SETCF instruction:
You use the SETCF instruction to pass parameters containing character
values to the external function module. The symbol in the name field of
the instruction is assigned the character string value returned by the
external function module. The length of the returned character string can
be from 0 to 255 bytes.

Built-in functions
The assembler provides you with many built-in functions that you can use in SETx
instructions to perform logical, arithmetic, and character string operations on
SETA, SETB and SETC expressions.

For a complete list, see “Summary of built-in functions” in the HLASM Language
Reference.

AIF instruction
The AIF instruction can include a string of logical expressions and related sequence
symbols that is equivalent to multiple AIF instructions. This form of the AIF
instruction is described as an extended AIF instruction. There is no limit to the
number of expressions and symbols that you can use in an extended AIF
instruction.

AGO instruction
An AGO instruction lets you make branches according to the value of an
arithmetic expression in the operand. This form of the AGO instruction is
described as a computed AGO instruction.

Extended continuation statements

For the following statements, the assembler allows as many continuation
statements as are needed:
v Prototype statement of a macro definition
v Macro instruction statement
v AGO conditional assembly statement
v AIF conditional assembly statement
v GBLA, GBLB, and GBLC conditional assembly statements
v LCLA, LCLB, and LCLC conditional assembly statements
v SETA, SETB, and SETC conditional assembly statements

SET symbols and SETx statements

The most powerful element of the conditional assembly language is SET symbol
support. SET symbols are variable symbols that provide you with arithmetic,
binary, or character data, and whose values you can set at conditional assembly
time with the SETA, SETB, and SETC instructions, respectively. This section
discusses some of the major features of this support, and the extensions High Level
Assembler provides.

Chapter 4. Macro and conditional assembly language extensions 27

Conditional assembly language extensions

SET symbol definition

When you define a SET symbol, you determine its scope. The scope of the SET
symbol is that part of a program for which the SET symbol has been declared. A
SET symbol can be defined as having local scope or global scope.

If you declare a SET symbol to have local scope, you can use it only in the
statements that are part of:
v The macro definition in which it was defined, or
v Open code, if it was defined in open code

If you declare a SET symbol to have global scope, you can use it in the statements
that are part of:
v The same macro definition
v A different macro definition
v Open code

To help you with SET symbol definition, High Level Assembler provides the
following facilities:
v A SET symbol is declared implicitly when it appears in the name field of a SETx
instruction, and it has not been declared in a LCLx or GBLx instruction. It is
assigned as having local scope. If the assembler subsequently encounters any
local scope explicit declaration of the symbol, the symbol is flagged as a
duplicate declaration. A SET symbol is declared as an array if the name field of
the SETx instruction contains a subscript. See “Array processing with SET
symbols” on page 29.
v Global and local SET symbol declarations are processed at conditional assembly
time. Both a macro definition and open code can contain more than one
declaration for a given SET symbol, as long as only one is encountered during a
given macro generation or conditional assembly of open code.
v A SET symbol can be defined as an array of values by specifying a subscript
when you declare it, either explicitly or implicitly. All such SET symbol arrays
are open-ended; the subscript value specified in the declaration does not limit
the size of the array, as shown in the following example:
Name Operation Operand

LCLA &J(50)
&J(45) SETA 415
&J(89) SETA 38

Created SET symbols

You can create SET symbols during the generation of a macro. A created SET
symbol has the form &(e), where e represents one or more of the following:
v Variable symbols, optionally subscripted
v Strings of alphanumeric characters
v Predefined symbols with absolute values
v Other created SET symbols

After substitution and concatenation, e must consist of a string of 1 to 62

alphanumeric characters, the first being alphabetic. This string is then used as the
name of a SETx variable. For example:
Name Operation Operand

&X(1) SETC ’A1’,’A2’,’A3’,’A4’

&(&X(3)) SETA 5

&X is a variable whose value is the name of the variable to be updated.

28 HLASM: V1R6 General Information

 Conditional assembly language extensions

These statements have an effect identical to:

&A3 SETA 5

You can use created SET symbols wherever ordinary SET symbols are permitted,
including declarations; they can even be nested in other created SET symbols.

The created SET symbol can be thought of as a form of indirect addressing. With
nested created SET symbols, you can use such indirect addressing to any level.

Created SET symbols can also offer an “associative memory” facility. For example,
a symbol table of numeric attributes can be referenced by an expression of the
form &(&SYM)(&I) to yield the I-th element of the symbol substituted for &SYM.
Note that the value of &SYM need not be the name of a valid symbol; thus created
SET symbols may have arbitrary names.

Created SET symbols also allow you to achieve some of the effect of
multidimensional arrays by creating a separate named item for each element of the
array. For example, a three-dimensional array of the form &X(&I,&J,&K) can be
addressed as &(X&I.$&J.$&K). Then &X(2,3,4) is represented as a reference to the
symbol &X2$3$4.

Note that what is being created here is a SET symbol. Both creation and
recognition occur at macro-generation time. In contrast, the names of parameters
are recognized and encoded (fixed) at macro-edit time. If a created SET symbol
name happens to coincide with a parameter name, the coincidence is ignored and
there is no interaction between the two.

Array processing with SET symbols

You can use the SET statement to assign lists or arrays of values to subscripted
SET symbols. For example, a list of 100 SETx values can be coded in one extended
SETx statement. The extended SETx statement has the following format:
Name Operation Operand

&SYM(exp) SETx X1,X2,,X4,...,Xn

where:
&SYM is a dimensioned SET symbol
exp is a SETA arithmetic expression
SETx is SETA, SETB, or SETC

An operand can be omitted by specifying two commas without intervening blanks.

Whenever an operand is omitted, the corresponding element of the dimensioned
variable SET symbol (&SYM) is left unchanged.

Using SETC variables in arithmetic expressions

You can use a SETC variable as an arithmetic term if its character string value
represents a valid self-defining term. This includes the G-type self-defining term. A
null value is treated as zero. This use of the SETC variable lets you associate
numeric values with EBCDIC, DBCS, or hexadecimal characters, and can be used
for such applications as indexing, code conversion, translation, or sorting.

For example, the following set of instructions converts a hexadecimal value in &X
into the decimal value 243 in &VAL.

Chapter 4. Macro and conditional assembly language extensions 29

Conditional assembly language extensions

Name Operation Operand

&X SETC ’X’’F3’’’

&VAL SETA &X

Using ordinary symbols in SETx statements

In addition to variable symbols, self-defining terms, and attribute references,
predefined symbols that have absolute values can be used in SETA and SETB
statements. You can use this facility to do arithmetic or logical operations on
expressions whose values are unknown at coding time, or are difficult to calculate.
For example, the following code could be used to assign the length of a CSECT to
a SETA symbol:
Name Operation Operand

BEGIN CSECT
.
.
.
CSECTLEN EQU *-BEGIN
&CSCTLEN SETA CSECTLEN

Similarly, in addition to character expressions and type attribute references,

predefined symbols that have absolute values can be used in SETC statements. For
example, the following code could be used to assign a string of fifty spaces to a
SETC symbol:
Name Operation Operand

FIFTY EQU 50
.
.
.
&SPACES SETC (FIFTY)’ ’

Substring length value

You can specify an asterisk as the second subscript value of the substring notation.
This indicates that the length of the extracted string is equal to the length of the
character string, less the number of characters before the starting character.

The following examples show how the substring notation can be used:
Name Operation Operand Comment

&Z SETC ’Astring’(2,3) length specified

&Y SETC ’Astring’(2,*) length not specified
&X SETC (UPPER ’&Y’(3,*)) length not specified

These statements have the following effect:

&Z contains the character value 'str'
&Y contains the character value 'string'
&X contains the character value 'RING'

Attribute references
Data such as instructions, constants, and areas have characteristics called data
attributes. The assembler assigns attribute values to the ordinary symbols and
variable symbols that represent the data.

You can determine up to eight attributes of symbols you define in your program
by means of an attribute reference. By testing attributes in conditional assembly
instructions, you can control the conditional assembly logic.

30 HLASM: V1R6 General Information

 Conditional assembly language extensions

Attributes of symbols produced by macro generation or substitution in open code

are available immediately after the referenced statement is generated.

Table 4 shows the data attributes.

Table 4. Data attributes
Attribute Purpose Notation
Type Gives a letter that identifies the type of data represented by an T'
ordinary symbol, a macro instruction operand, a SET symbol, and
a literal
Length Gives the number of bytes occupied by the data that is named by L'
the symbol, or literal, specified in the attribute reference
Scaling Refers to the position of the decimal point in decimal, fixed-point, S'
and floating-point constants
Integer Is a function of the length and scaling attributes of decimal, I'
fixed-point, and floating-point constants
Count Gives the number of characters that would be required to K'
represent the current value of the SET symbol or the system
variable symbol. It also gives the number of characters that
constitute the macro operand instruction.
Number Gives the number of sublist entries in a macro instruction operand N'
sublist
Defined Indicates whether the symbol referenced has been defined prior to D'
the attribute reference
Operation Indicates whether a given operation code has been defined prior to O'
Code the attribute reference

Where attribute references can be used

References to the type (T'), length (L'), scaling (S'), and integer (I') attributes of
ordinary symbols and SETC symbols can be used in:
v Conditional assembly instructions
v Any assembler instruction that accepts an absolute expression as an operand
v Any machine instruction

For example:
Name Operation Operand Comment

&TYPE SETC T’PACKED Type

LENGTH LA 2,L’PACKED Length
ADTYPE LA 2,T’PACKED Value of Type (C’P’)
&SCALE SETA S’PACKED Scaling
INTEGER DC AL1(I’PACKED) Integer
.
.
.
PACKED DC P’123.45’ Referenced Symbol

Attribute references to the count (K') and number (N') attributes, however, can
only be used in conditional assembly instructions.

Attribute references and SETC variables

The symbol referenced by an attribute reference of length (L'), type (T'), scaling (S'),
integer (I'), and defined (D'), can only be an ordinary symbol. The name of the
ordinary symbol can, however, be specified in three different ways:
v The name of the ordinary symbol itself

Chapter 4. Macro and conditional assembly language extensions 31

Conditional assembly language extensions

v The name of a symbolic parameter whose value is the name of the ordinary
symbol
v The name of a SETC symbol whose value is the name of the ordinary symbol

Attribute references and literals

In addition to symbols, you can reference literals with the type, length, defined,
scaling, and integer attribute references. For example:
Name Operation Operand Comment

LENGTH LA 2,L’=C’ABCXYZ’ Length attribute has value 6

TYPE EQU T’=F’1000’ Type attribute has value ’F’

Type attribute of a CNOP label

The type attribute (T') of a CNOP label has been changed to ‘I’. In Assembler H
Version 2 the attribute value was ‘J’.

Defined attribute (D')

The defined attribute (D') can be used in conditional assembly statements to
determine if a given symbol has been defined at a prior point in the source
module. If the symbol is already defined, the value of the defined attribute is one;
if it has not been defined, the value is zero. By testing a symbol for the defined
attribute, you can avoid a forward scan of the source code. See “Forward
attribute-reference scan” on page 33.

Operation code attribute (O')

The operation code attribute (O') can be used in conditional assembly statements to
determine if a given operation code has been defined prior to the attribute
reference. The following letters are used for the operation code attribute value:
A Assembler operation codes
E Extended mnemonic operation codes
M Macro operation codes
O Machine operation codes
S Macro found in SYSLIB (z/OS and CMS) or library (by Librarian on VSE)
U Undefined operation codes

If an operation code is redefined using the OPSYN instruction the attribute value
represents the new operation code type. If the operation code is deleted using the
OPSYN instruction the attribute value is ‘U’.

The following example checks to see if the macro MYMAC is defined. If not, the
MYMAC macro instruction is bypassed. This example prevents the assembly from
failing when the macro is not available.
Name Operation Operand

&CHECKIT SETC O’MYMAC

AIF (’&CHECKIT’ EQ ’U’).NOMAC
MYMAC
.NOMAC ANOP
.
.
.
DATAAREA DC F’0’

32 HLASM: V1R6 General Information

 Conditional assembly language extensions

Number attributes for SET symbols

The number attribute (N') can be applied to SETx variables to determine the
highest subscript value of a SET symbol array to which a value has been assigned
in a SETx instruction. For example, if the only occurrences of the definitions of the
SETA symbol &A are:
Name Operation Operand

&A(1) SETA 0
&A(2) SETA 0
&A(3) SETA &A(2)
&A(5) SETA 5
&A(10) SETA 0

then N'&A is 10.

The number attribute is zero for a SET symbol that has been defined but not
assigned any value, regardless of whether it is subscripted or not. The number
attribute is always 1 for a SET symbol that is not subscripted and when the SET
symbol has been assigned a value.

The number attribute also applies to the operands of macro instructions.

Forward attribute-reference scan

If you make an attribute reference to an undeclared symbol, the assembler scans
the source code either until it finds the symbol in the name field of a statement in
open code, or until it reaches the end of the source module. The assembler makes
an entry in the symbol table for the symbol, as well as for any other previously
undefined symbols it encounters during the scan. The assembler does not
completely check the syntax of the statements for which it makes entries in the
symbol table. Therefore, a valid attribute reference can result from a forward scan,
even though the statement is later found to be in error and therefore not accepted
by the assembler.

You must be careful with the contents of any AREAD input in your source
module. If an AREAD input record is encountered before the symbol definition,
and the record has the same format as an assembler language statement, and the
name field contains the symbol referred to in the attribute reference, then the
forward scan will attempt to evaluate that record instead.

Redefining conditional assembly instructions

You can use the OPSYN instruction to redefine conditional assembly instructions
anywhere in your source module. A redefinition of a conditional assembly
instruction affects only macro definitions occurring after the OPSYN instruction.
The original definition of a conditional assembly instruction is always used during
the processing of subsequent calls to a macro that was defined before the OPSYN
instruction.

An OPSYN instruction that redefines the operation code of an assembler or

machine instruction generated from a macro instruction is effective immediately,
even if the definition of the macro was made prior to the OPSYN instruction.
Consider the following example:
Name Operation Operand Comment

MACRO Macro header

MACRDEF ... Macro prototype
AIF ...
MVC ...

Chapter 4. Macro and conditional assembly language extensions 33

Conditional assembly language extensions

.
.
.
MEND Macro trailer
.
.
.
AIF OPSYN AGO Assign AGO properties to AIF
MVC OPSYN MVI Assign MVI properties to MVC
.
.
.
MACRDEF ... Macro call
(AIF interpreted as AIF instruct-
ion; generated AIFs not printed)
+ MVC ... Interpreted as MVI instruction
.
.
.
Open code started at this point
AIF ... Interpreted as AGO instruction
MVC ... Interpreted as MVI instruction

In this example, AIF and MVC instructions are used in a macro definition. AIF is a
conditional assembly instruction, and MVC is a machine instruction. OPSYN
statements assign the properties of AGO to AIF and assign the properties of MVI
to MVC. In subsequent calls of the macro MACRDEF, AIF is still defined, and used
as an AIF operation, but the generated MVC is treated as an MVI operation. In
open code following the macro call, the operations of both instructions are derived
from their new definitions assigned by the OPSYN statements. If the macro is
redefined (by another macro definition), the new definitions of AIF and MVC (that
is, AGO and MVI) are used for further generations.

This description does not apply to nested macro definitions because the assembler
does not edit inner macro definitions until it encounters them during the
generation of its outer macro. An OPSYN statement placed before the outer macro
instruction can affect conditional assembly statements in the inner macro
definition.

System variable symbols

System variable symbols are read-only, local-scope or global-scope variable
symbols whose values are determined and assigned only by the assembler. System
variable symbols that have local scope are assigned a read-only value each time a
macro definition is called by a macro instruction. You can only refer to local-scope
system variable symbols inside macro definitions. System variable symbols that
have global scope are assigned a read-only value for the whole assembly. You can
refer to global-scope system variable symbols in open code and in macro
definitions.

The format of the following two system variables has changed since Assembler H
Version 2:
v &SYSLIST treats parenthesized sublists in SETC symbols as sublists when passed
to a macro definition in the operand of a macro instruction. The
COMPAT(SYSLIST) assembler option can be used to treat sublists in the same
way as Assembler H Version 2, that is, parenthesized sublists are treated as
character strings, not sublists.
v &SYSPARM can now be up to 255 characters long, subject to restrictions
imposed by job control language.

34 HLASM: V1R6 General Information

 Conditional assembly language extensions

Some of the new system variable symbols introduced with High Level Assembler
supplement the data provided by system variables available in previous
assemblers.
&SYSCLOCK: &SYSCLOCK provides the date and time the macro is generated.
&SYSDATE and &SYSDATC:
&SYSDATE provides the date in the format MM/DD/YY without
the century digits, and the year digits are in the lowest-order
positions.
The new variable symbol &SYSDATC provides the date with the
century, and the year digits in the highest-order positions. Its
format is YYYYMMDD.
&SYSECT and &SYSSTYP:
All previous assemblers have supported the &SYSECT variable to
hold the name of the enclosing control section at the time a macro
was invoked. This allows a macro that needs to change control
sections to resume the original control section on exit from the
macro. However, there was no capability to determine what type of
control section to resume.
The &SYSSTYP variable provides the type of the control section
named by &SYSECT. This permits a macro to restore the correct
previous control section environment on exit.
&SYSMAC: Retrieves the name of any macro called between open code and the
current nesting level.
&SYSM_HSEV:
Provides the highest MNOTE severity code for the assembly so far.
&SYSM_SEV: Provides the highest MNOTE severity code for the macro most
recently called from this macro or open code.
&SYSOPT_XOBJECT:
Determines if the XOBJECT assembler option was specified.
&SYSNDX and &SYSNEST:
All previous assemblers have supported the &SYSNDX variable
symbol, which is incremented by one for every macro invocation in
the program. This permits macros to generate unique ordinary
symbols if they are needed as local labels. Occasionally, in
recursively nested macro calls, the value of the &SYSNDX variable
was used to determine either the depth of nesting, or to determine
when control had returned to a particular level.
Alternatively, the programmer could define a global variable
symbol, and in each macro insert statements to increment that
variable on entry and decrement it on exit. This technique is both
cumbersome (because it requires extra coding in every macro) and
unreliable (because not every macro called in a program is likely to
be under the programmer’s control).
High Level Assembler provides the &SYSNEST variable to keep
track of the level of macro-call nesting in the program. The value
of &SYSNEST is incremented globally on each macro entry, and
decremented on each exit.

Chapter 4. Macro and conditional assembly language extensions 35

Conditional assembly language extensions

&SYSTIME and the AREAD statement

The &SYSTIME variable symbol is provided by High Level Assembler and
Assembler H, but not by earlier assemblers. It provides the local time of the start
of the assembly in HH.MM format. This time stamp may not have sufficient
accuracy or resolution for some applications.

High Level Assembler provides an extension to the AREAD statement, discussed

in more detail in “AREAD clock functions” on page 25, that may be useful if a
more accurate time stamp is required.

Appendix B, “System variable symbols,” on page 79 describes all the system

variable symbols.

36 HLASM: V1R6 General Information

Chapter 5. Using exits to complement file processing
The High Level Assembler EXIT option lets you provide an exit module that can
replace or complement the assembler’s data set input/output processing. This
chapter describes the exits available to you and how to use them.

User exit types

You can select up to seven exit types during an assembly on z/OS and CMS, or six
on z/VSE:
Exit type Exit processing
SOURCE Use this exit to replace or complement the assembler’s primary
input file processing. It can read primary input records instead of
the assembler, or it can monitor and optionally modify the records
read by the assembler before they are processed. You can also use
the SOURCE exit to provide additional primary input records.
LIBRARY Use this exit to replace or complement the assembler’s MACRO
and COPY library processing. It can read MACRO and COPY
library records instead of the assembler, or it can monitor and
optionally modify the records read by the assembler before they
are processed. You can also use the LIBRARY exit to provide
additional MACRO and COPY source records.
LISTING Use this exit to replace or complement the assembler’s listing
output processing. It can write the listing records provided by the
assembler, or it can monitor and optionally modify the records
before they are written by the assembler. You can also use the
LISTING exit to provide additional listing records.
OBJECT (z/OS and CMS) Use this exit to replace or complement the
assembler’s object module output processing. It can write object
module records provided by the assembler, or monitor and
optionally modify the records before they are written by the
assembler. You can also use the OBJECT exit to provide additional
object module records.
The OBJECT exit is the same as the PUNCH exit, except that you
use it when you specify the OBJECT assembler option to write
object records to SYSLIN.
PUNCH On z/OS and CMS, the PUNCH exit is the same as the OBJECT
exit, except that you use it when you specify the DECK assembler
option to write object records to SYSPUNCH.
On z/VSE, use this exit to replace or complement the assembler’s
object module output processing. It can write object module
records provided by the assembler, or monitor and optionally
modify the records before they are written by the assembler. You
can also use the PUNCH exit to provide additional object module
records.
ADATA Use this exit to replace or complement the assembler’s ADATA
I/O. The ADATA exit can modify the records, discard records, or
provide additional records.

© Copyright IBM Corp. 1981, 2008 37

User exit types

TERM Use this exit to replace or complement the assembler’s terminal

output processing. It can write the terminal records provided by
the assembler, or it can monitor and optionally modify the records
before they are written by the assembler. You can also use the
TERM exit to provide additional terminal output records.

Note: The ASMAOPT file does not have an I/O exit.

How to supply a user exit to the assembler

You must supply a user exit as a module that is available in the standard module
search order.

You may write an exit in any language that allows it to be loaded once and called
many times at the module entry point, and conforms to standard OS Linkage
conventions.

On entry to the exit module, Register 1 points to an Exit Parameter list supplied by
the assembler. The Exit Parameter list has a pointer to an Exit-Specific Information
block that contains specific information for each exit type. High Level Assembler
provides you with a macro, called ASMAXITP, which lets you map the Exit
Parameter list and the Exit Specific Information block.

You specify the name of the exit module in the EXIT assembler option. You can
also pass up to 64 characters of data to the exit, by supplying them as a suboption
of the EXIT option. The assembler passes the data to your exit during assembler
initialization.

Passing data to I/O exits from the assembler source

You can use the EXITCTL instruction to pass data from the assembler source to
any of the exits. The assembler maintains four signed, fullword, exit-control
parameters for each type of exit. You use the EXITCTL instruction to set or modify
the contents of the four fullwords during the assembly, by specifying the following
values in the operand fields:
v A decimal self-defining term with a value in the range −231 to +231−1.
v An expression in the form *±n, where * is the current value of the
corresponding exit-control parameter to which n, a decimal self-defining term, is
added or from which n is subtracted. The value of the result of adding n to or
subtracting n from the current exit-control parameter value must be in the range
−231 to +231−1.

If a value is omitted, the corresponding exit-control parameter retains its current

value.

The assembler initializes all exit-control parameters to binary zeros.

Statistics
The assembler writes the exit usage statistics to the Diagnostic Cross Reference and
Assembler Summary section of the assembler listing.

38 HLASM: V1R6 General Information

 Disabling an exit

Disabling an exit
A return code of 16 allows an EXIT to disable itself. The EXIT is not called again
during this assembly, or any following assemblies if the BATCH option is being
used.

Communication between exits

The Common User field in the Request information block provides a mechanism
by which all exits can communicate and share information.

Reading edited macros (VSE only)

An E-Deck refers to a macro source book of type E that can be used as the name of
a macro definition to process in a macro instruction. E-Decks are stored in edited
format, however High Level Assembler requires library macros to be stored in
source statement format. You can use the LIBRARY exit to analyze a macro
definition, and, in the case of an E-Deck, call the VSE/ESA ESERV program to
change, line by line, the E-Deck definition back into source statement format.

See the subsection Using the High Level Assembler Library Exit for Processing E-Decks,
in Chapter 4 Using VSE Libraries, section High Level Assembler Considerations, in
VSE/ESA Guide to System Functions. This section describes how to set up a
LIBRARY exit and use it to process E-Decks.

Sample exits provided with High Level Assembler (z/OS and CMS)
The following sample exits are provided with High Level Assembler:
ADATA exit:
The ADATA exit handles the details of interfaces to the assembler. It
provides ADATA records to a number of filter routines, and also to exits
which control the ADATA record output, or reformat ADATA records from
new to old format.
The filter routines inspect the records to extract the information they
require. This lets you add or modify a filter routine without impacting
either the exit or the other filter routines.
The design of the exit:
v Supports multiple simultaneous filter routines.
v Simplifies the ADATA-record interface for each filter, because you do not
need to be concerned about the complex details of interacting directly
with the assembler.
v Supports filter routines written in high-level languages.
v Supports an exit to control the ADATA record output.
v Supports an exit to reformat ADATA records from new to old format.
There are three components that make up the functional ADATA filter
routine:
1. The exit, ASMAXADT, which the assembler invokes.
2. A table of filter-routine names, contained in a Filter Management Table
(FMT), module ASMAXFMT. The exit routine loads the FMT.
3. The filter routines. The exit loads these as directed by the FMT.

Chapter 5. Using exits to complement file processing 39

Sample exits provided with High Level Assembler (z/OS and CMS)

The functional ADATA exit, ASMAXADC, controls ADATA record output.

ASMAXADC uses parameters specified on the assembler EXIT option to
determine if it, or the assembler, will perform output processing for the
ADATA records, and which record types are to be kept or discarded.
The functional exit, ASMAXADR, reformats ADATA records from the High
Level Assembler Release 5 format, back to the Release 4 format.
ASMAXADR uses parameters specified on the assembler EXIT option to
determine which ADATA types are to be reformatted.
No exit modules are provided with High Level Assembler. “Sample
ADATA user exits (z/OS and CMS)” in the HLASM Programmer’s Guide
describes the exit and the input format of the exit routines.
LISTING exit:
Use the LISTING exit to suppress the High Level Assembler Options Summary
section, or the Diagnostic Cross Reference and Assembler Summary section, or
both from the assembler listing. The exit can also direct the assembler to
print the options summary at the end of the assembler listing. You specify
keywords as suboptions of the EXIT option to control how the assembler
processes these sections of the listing.
The LISTING exit is called ASMAXPRT.
“Sample LISTING user exit (z/OS and CMS)” in the HLASM Programmer’s
Guide describes the exit and the keywords you can use to select the print
options.
SOURCE exit:
Use the SOURCE exit to read variable-length source data sets. Each record
that is read is passed to the assembler as an 80-byte source statement. If
any record in the input data set is longer than 71 characters the remaining
part of the record is converted into continuation records.
The exit also reads a data set with a fixed record length of 80 bytes.
The SOURCE exit is called ASMAXINV.
“Sample SOURCE user exit (z/OS and CMS)” in the HLASM Programmer’s
Guide describes this exit.

40 HLASM: V1R6 General Information

Chapter 6. Programming and diagnostic aids
High Level Assembler has many assembler listing and diagnostic features to aid
program development and to simplify the location and analysis of program errors.
You can also produce terminal output to assist in diagnosing assembly errors. This
chapter describes these features.

Assembler listings
High Level Assembler produces a comprehensive assembler listing that provides
information about a program and its assembly. Each section of the assembler
listing is clear and easily readable. The following assembler options are used to
control the format and which sections of the listing to produce:
ASA (z/OS and CMS) Allows you to use American National Standard
printer control characters, instead of machine printer control
characters.
DXREF Produces the DSECT Cross Reference section.
ESD Produces the External Symbol Dictionary section.
EXIT(PRTEXIT(mod3))
Supplies a listing exit to replace or complement the assembler’s
listing output processing.
FOLD Instructs the assembler to print the assembler listing in uppercase
characters, except for quoted strings and comments.
LANGUAGE Produces error diagnostic messages in the following languages:
v English mixed case (EN)
v English uppercase (UE)
v German (DE)
v Japanese (JP)
v Spanish (ES)
When you select either of the English languages, the assembler
listing headings are produced in the same case as the diagnostic
messages.
When you select either the German language or the Spanish
language, the assembler listing headings are produced in mixed
case English.
When you select the Japanese language, the assembler listing
headings are produced in uppercase English.
The assembler uses the installation default language for messages
produced in CMS by the High Level Assembler command.
LINECOUNT Specifies how many lines should be printed on each page,
including the title and heading lines.
LIST Controls the format of the Source and Object section of the listing.
NOLIST suppresses the entire listing.
MXREF Produces one, or both, of the Macro and Copy Code Source Summary
and Macro and Copy Code Cross Reference sections.

© Copyright IBM Corp. 1981, 2008 41

Assembler listings

PCONTROL Controls what statements are printed in the listing, and overrides
some PRINT instructions.
RLD Produces the Relocation Dictionary section.
RXREF Produces the General Purpose Register Cross Reference section.
USING(MAP) Produces the Using Map section.
XREF Produces one, or both, of the Ordinary Symbol and Literal Cross
Reference and the Unreferenced Symbols Defined in CSECTs sections.

Option summary
High Level Assembler provides a summary of the options current for the assembly,
including:
v A list of the overriding parameters specified in the external file or library
member (VSE only)
v A list of the overriding parameters specified when the assembler was called
v The options specified on *PROCESS statements
v In-line error diagnostic messages for any overriding parameters and *PROCESS
statements in error
You cannot suppress the option summary unless you suppress the entire listing, or
you supply a user exit to control which lines are printed.

On z/OS and CMS, High Level Assembler provides a sample LISTING exit that
allows you to suppress the option summary or print it at the end of the listing. See
the description of the sample listing exit on page 40.

Figure 4 shows an example of the High Level Assembler Option Summary. The
example includes assembler options that have been specified in the external file or
library member, the invocation parameters and in *PROCESS statements. It also
shows the *PROCESS statements in the Source and Object section of the listing.

42 HLASM: V1R6 General Information

 Assembler listings

1 High Level Assembler Option Summary Page 1

1 2
- HLASM R6.0 2008/07/11 17.48
0 Overriding ASMAOPT Parameters - sysparm(thisisatestsysparm),rxref
Overriding Parameters- NOOBJECT,language(en),size(4meg),xref(short,unrefs),nomxref,norxref,adata,noadata
Process Statements- OVERRIDE(ADATA,MXREF(full))
ALIGN
noDBCS
MXREF(FULL),nolibmac
FLAG(0)
noFOLD,LANGUAGE(ue)
NORA2
NODBCS
XREF(FULL)

3
** ASMA400W Error in invocation parameter - size(4meg)
** ASMA438N Attempt to override ASMAOPT parameter. Option norxref ignored.
** ASMA425N Option conflict in invocation parameters. noadata overrides an earlier setting.
** ASMA423N Option ADATA, in a *PROCESS OVERRIDE statement conflicts with invocation or default option. Option is not
permitted in a *PROCESS statement and has been ignored.
** ASMA422N Option LANGUAGE(ue) is not valid in a *PROCESS statement.
** ASMA437N Attempt to override invocation parameter in a *PROCESS statement. Suboption FULL of XREF option ignored.

Options for this Assembly

4
3 NOADATA
5 ALIGN
NOASA
BATCH
CODEPAGE(047C)
NOCOMPAT
5 NODBCS
NODECK
DXREF
ESD
NOEXIT
5 FLAG(0,ALIGN,CONT,EXLITW,NOIMPLEN,NOPAGE0,PUSH,RECORD,NOSUBSTR,USING0)
5 NOFOLD
NOGOFF
NOINFO
3 LANGUAGE(EN)
5 NOLIBMAC
LINECOUNT(60)
LIST(121)
MACHINE(,NOLIST)
1 MXREF(FULL)
3 NOOBJECT
OPTABLE(UNI,NOLIST)
NOPCONTROL
NOPESTOP
NOPROFILE
5 NORA2
NORENT
RLD
2 RXREF
SECTALGN(8)
SIZE(MAX)
NOSUPRWARN
2 SYSPARM(thisisatestsysparm)
NOTERM

Figure 4. Option summary including options specified on *PROCESS statements (Part 1 of 2)

Chapter 6. Programming and diagnostic aids 43

Assembler listings

1 High Level Assembler Option Summary Page 2

- HLASM R6.0 2008/07/11 17.48
0 NOTEST
THREAD
NOTRANSLATE
TYPECHECK(MAGNITUDE,REGISTER)
USING(NOLIMIT,MAP,WARN(15))
3 XREF(SHORT,UNREFS)

5
No Overriding DD Names
1 External Symbol Dictionary Page 3
-Symbol Type Id Address Length Owner Id Flags Alias-of HLASM R6.0 2008/07/11 17.48
0A SD 00000001 00000000 00000000 00
1 Page 4
Active Usings: None
0 Loc Object Code Addr1 Addr2 Stmt Source Statement HLASM R6.0 2008/07/11 17.48
6
0 1 *PROCESS OVERRIDE(ADATA,MXREF(full))
2 *PROCESS ALIGN
3 *PROCESS noDBCS
4 *PROCESS MXREF(FULL),nolibmac
5 *PROCESS FLAG(0)
6 *PROCESS noFOLD,LANGUAGE(ue)
7 *PROCESS NORA2
8 *PROCESS NODBCS
9 *PROCESS XREF(FULL)
000000 00000 00000 10 A CSECT
R:F 00000 11 USING *,15

Figure 4. Option summary including options specified on *PROCESS statements (Part 2 of 2)

The highlighted numbers in the example are:

1 The product description. Shown on each page of the assembler listing. (You
can use the TITLE instruction to generate individual headings for each
page of the source and object program listing.)
2 The date and the time of the assembly.
3 Error diagnostic messages for overriding parameters and *PROCESS
statements. These immediately follow the list of *PROCESS statement
options. The error diagnostic messages are:
ASMA400W - The value specified as the size option is not valid. The
valid option is SIZE(4M).
ASMA438N - The option RXREF is specified in the ASMAOPT file and
the conflicting option NORXREF is specified as an
invocation parameter. The ASMAOPT options have
precedence over the invocation parameters and the
NORXREF option is ignored.
ASMA425N - The ADATA option specified as an invocation parameter
overrides the option NOADATA which was also specified
as an invocation parameter. When conflicting options are
received from the same source, the last occurrence takes
precedence.
ASMA423N - The option ADATA has been specified in a *PROCESS
statement with the OVERRIDE option. The option cannot
be set by a *PROCESS statement, and the option conflicts
with an invocation or default option. This message is
printed when an option that cannot be set by a *PROCESS
statement (see “*PROCESS statement options” in the
HLASM Programmer’s Guide) is included in a *PROCESS

44 HLASM: V1R6 General Information

 Assembler listings

OVERRIDE statement and the option conflicts with an

invocation or default option. If the option does not conflict
with the invocation or default option no message is
printed.
ASMA422N - The option LANGUAGE is not permitted in a *PROCESS
statement.
ASMA437N - The option XREF(FULL) which is specified in the last
*PROCESS statement conflicts with the option NORXREF
which is specified as an invocation parameter. The option
XREF(FULL) is ignored.
4 A flag beside each option indicates the source of the option. This table
shows the sources:
Table 5. Flags used in the option summary
Flag Meaning
1 The option came from a *PROCESS OVERRIDE statement.
2 The option came from the ASMAOPT options file (z/OS and CMS) or
ASMAOPT.USER library member (VSE).
3 The option came from the invocation parameters.
4 The permanent job control options set by the VSE command STDOPT.
5 The option came from a *PROCESS statement.
(blank) The option came from the installation defaults.

5 On z/OS and CMS, if the assembler has been called by a program and any
standard (default) DDnames have been overridden, both the default
DDnames and the overriding DDnames are listed. Otherwise, this
statement appears:
No Overriding DD Names
6 The *PROCESS statements are written as comment statements in the
Source and Object section of the listing.

External Symbol Dictionary

Figure 5 shows the external symbol dictionary (ESD) information passed to the
linkage editor or loader, or z/OS Program Management Binder in the object
module.

Chapter 6. Programming and diagnostic aids 45

Assembler listings

SAMP01 External Symbol Dictionary Page 2

1 2 3 4
Symbol Type Id Address Length Owner Id Flags Alias-of HLASM R6.0 2008/07/11 17.48
SAMP01 SD 00000001
B_PRV ED 00000002 00000001
B_TEXT ED 00000003 00000000 000000E0 00000001 00
SAMP01 LD 00000004 00000000 00000003 00
ENTRY1 LD 00000005 00000000 00000003 00
KL_INST SD 00000006
B_PRV ED 00000007 00000006
B_TEXT ED 00000008 00000000 00000000 00000006 00
KL_INST CM 00000009 00000000 00000008 00
SD 0000000A
B_PRV ED 0000000B 0000000A
B_TEXT ED 0000000C 000000E0 00000000 0000000A 00
Date0001 ER 0000000D 0000000A RCNVDATE
RCNVTIME ER 0000000E 0000000A

Figure 5. External Symbol Dictionary

1 Shows the name of every external dummy section, control section, entry
point, external symbol, and class.
2 Indicates whether the symbol is the name of a label definition, external
reference, unnamed control section definition, common control section
definition, external dummy section, weak external reference, or external
definition.
3 Shows the length of the control section.
4 When you define a symbol in an ALIAS instruction, this field shows the
external symbol name of which the symbol is an alias.

You can suppress this section of the listing by specifying the NOESD assembler
option.

Source and object

On z/OS and CMS, the assembler can produce two formats of the source and
object section: a 121-character format and a 133-character format. To select one, you
must specify either the LIST(121) assembler option or the LIST(133) assembler
option. Both sections show the source statements of the module, and the object
code of the assembled statements.

The 133-character format shows the location counter, and the first and second
operand addresses (ADDR1 and ADDR2) as 8-byte fields in support of 31-bit
addresses. This format is required when producing the extended object file; see
“Generalized object format modules (z/OS and CMS)” on page 11. The
133-character format also contains the first eight characters of the macro name in
the identification-sequence field for statements generated by macros.

Figure 6 on page 47 shows an example of the Source and Object section of the
listing. This section shows the source statements of the module, and the object
code of the assembled statements.

The fixed heading line printed on each page of the source and object section of the
assembler listing indicates if the control section, at the time of the page eject, is a
COM section, a DSECT or an RSECT.

High Level Assembler lets you write your program and print the assembler listing
headings in mixed-case.

46 HLASM: V1R6 General Information

 Assembler listings

121-Character listing format

Figure 6 shows an example of the source and object section in 121-character format,
and in mixed-case.

SAMP01 Sample Listing Description Page 3

Active Usings: None
1 2 3 4
Loc Object Code Addr1 Addr2 Stmt Source Statement HLASM R6.0 2008/07/11 17.48
000000 00000 000E0 2 Samp01 Csect
22 Entry1 SAMPMAC Parm1=YES 00002300
000000 18CF 23+Entry1 LR 12,15 01-SAMPM
24+ ENTRY Entry1 01-SAMPM
5
R:C 00000 25+ USING Entry1,12 Ordinary Using 01-SAMPM
000002 0000 0000 00000 26+ LA Savearea,10 01-SAMPM
6 ** ASMA044E Undefined symbol - Savearea
6 ** ASMA029E Incorrect register specification - Savearea
7 ** ASMA435I Record 6 in SAMP01 MACLIB A1(SAMPMAC) on volume: EAR191
000006 50D0 A004 00004 27+ ST 13,4(,10) 01-SAMPM
00000A 50A0 D008 00008 28+ ST 10,8(,13) 01-SAMPM
00000E 18DA 29+ LR 13,10 01-SAMPM
R:A35 00010 30+ USING *,10,3,5 Ordinary Using,Multiple Base 01-SAMPM
** ASMA303W Multiple address resolutions may result from this USING and the USING on statement number 25
8 ** ASMA435I Record 10 in SAMP01 MACLIB A1(SAMPMAC) on volume: EAR191
9
31+ DROP 10,3,5 Drop Multiple Registers 01-SAMPM
32 COPY SAMPLE 00002400
33=* Line from member SAMPLE
C 02A 00000 0002A 34 Using IHADCB,INDCB Establish DCB addressability 00002500
C 07A 00000 0007A 35 ODCB Using IHADCB,OUTDCB 00002600
36 push using 00002700
10
R:2 00000 37 PlistIn Using Plist,2 Establish Plist addressability 00002800
00004 38 la 0,plistin.parm2 00002900
SAMP01 Sample Listing Description Page 4
| 11 Active Usings (1):Entry1,R12 IHADCB(X’FD4’),R12+X’2C’ PlistIn.plist,R2 ODCB.IHADCB(X’F84’),R12+X’7C’
ODCB.IHADCB(X’F86’),R12+X’7A’
Loc Object Code Addr1 Addr2 Stmt Source Statement HLASM R6.0 2008/07/11 17.48
000010 1851 40 ?Branch LR R5,R1 Save Plist pointer 00003100
** ASMA147E Symbol too long, or first character not a letter - ?Branch
** ASMA435I Record 30 in SAMP01 ASSEMBLE A1 on volume: EAR191
000012 5820 5000 00000 41 L R2,0(,R5) R2 = address of request list 00003200
000016 47F0 C022 00022 42 B Open 00003300
697 End 00055100
0000D0 00000001 698 =f’1’
0000D4 00000000 699 =V(RCNVDATE)
0000D8 00000000 700 =V(RCNVTIME)
0000DC 00000002 701 =f’2’

Figure 6. Source and object listing section—121 format

1 Shows, in hexadecimal notation, the assembled address of the object code.
2 Shows, in hexadecimal notation, the object code generated by assembly of
the statement. The object code of machine instructions is printed in full.
Only 8 bytes of object code are printed for assembled constants, unless the
PRINT DATA instruction or the PCONTROL(DATA) assembler option is
specified, in which case all the object code is printed.
3 Shows the statement number. If you specify the PCONTROL(GEN)
assembler option, or if you specify the PRINT GEN instruction before a
macro instruction, the statements generated by the macro instruction is
printed. A plus sign (+) suffixes the statement numbers of generated
statements.
4 Shows the source statement.
5 The Addr1 and Addr2 columns show the first and second operand

Chapter 6. Programming and diagnostic aids 47

Assembler listings

addresses in the USING instructions. The base registers on an ordinary

USING instruction are printed, right justified in the Object Code columns,
preceded by the characters R:.
6 Displays the error diagnostic messages immediately following the source
statement in error. Many error diagnostic messages include the segment of
the statement that is in error. You can use the FLAG assembler option to
control the level of diagnostic messages displayed in your listing.
7 Displays the informational message, ASMA435I, that describes the origin of
the source statement in error. This message is only printed when you
specify the FLAG(RECORD) assembler option.
8 Displays the informational message, ASMA435I, that describes the origin of
the source statement in error. Conditional assembly statements and
comment statements contribute to the record count of macro definitions.
9 The macro name in the identification-sequence field is truncated after the
first five characters.
10 The Addr1 and Addr2 columns show the first and second operand
addresses in the USING instructions. The register and resolved base
displacement for a dependent USING instruction are printed in the Object
Code columns, as register displacement. The base address is shown in the
Addr1 column, and the explicit base displacement is shown in the Addr2
column.
11 Shows active USINGs.
In this example, the first is an ordinary USING, the second a dependent
USING, the third a labeled dependent USING, and the last two are labeled
USINGs.

133-character listing format

Figure 7 shows an example of the Source and Object section when the same
assembly is run with assembler option LIST(133), and is followed by a description
of its differences with Figure 6 on page 47:

48 HLASM: V1R6 General Information

 Assembler listings

SAMP01 Sample Listing Description Page 3

Active Usings: None
1
Loc Object Code Addr1 Addr2 Stmt Source Statement HLASM R6.0 2008/07/11 17.48
00000000 00000000 000000E0 2 Samp01 Csect
22 Entry1 SAMPMAC Parm1=YES 00002300
00000000 18CF 23+Entry1 LR 12,15 01-SAMPMAC
24+ ENTRY Entry1 01-SAMPMAC
2
R:C 00000000 25+ USING Entry1,12 Ordinary Using 01-SAMPMAC
00000002 0000 0000 00000000 26+ LA Savearea,10 01-SAMPMAC
** ASMA044E Undefined symbol - Savearea
** ASMA029E Incorrect register specification - Savearea
** ASMA435I Record 6 in SAMP01 MACLIB A1(SAMPMAC) on volume: EAR191
00000006 50D0 A004 00000004 27+ ST 13,4(,10) 01-SAMPMAC
0000000A 50A0 D008 00000008 28+ ST 10,8(,13) 01-SAMPMAC
0000000E 18DA 29+ LR 13,10 01-SAMPMAC
3
R:A35 00000010 30+ USING *,10,3,5 Ordinary Using,Multiple Base 01-SAMPMAC
** ASMA303W Multiple address resolutions may result from this USING and the USING on statement number 25
** ASMA435I Record 10 in SAMP01 MACLIB A1(SAMPMAC) on volume: EAR191
31+ DROP 10,3,5 Drop Multiple Registers 01-SAMPMAC
32 COPY SAMPLE 00002400
33=* Line from member SAMPLE
C 02A 00000000 0000002A 34 Using IHADCB,INDCB Establish DCB addressability 00002500
C 07A 00000000 0000007A 35 ODCB Using IHADCB,OUTDCB 00002600
36 push using 00002700
R:2 00000000 37 PlistIn Using Plist,2 Establish Plist addressability 00002800
R:3 00000000 38 PlistOut Using Plist,3 00002900
SAMP01 Sample Listing Description Page 4
Active Usings (1):Entry1,R12 IHADCB(X’FD6’),R12+X’2A’ PlistIn.plist,R2 PlistOut.plist,R3
ODCB.IHADCB(X’F86’),R12+X’7A’
Loc Object Code Addr1 Addr2 Stmt Source Statement HLASM R6.0 2008/07/11 17.48
00000010 1851 40 ?Branch LR R5,R1 Save Plist pointer 00003100
** ASMA147E Symbol too long, or first character not a letter - ?Branch
** ASMA435I Record 30 in SAMP01 ASSEMBLE A1 on volume: EAR191
00000012 5820 5000 00000000 41 L R2,0(,R5) R2 = address of request list 00003200
00000016 47F0 C022 00000022 42 B Open 00003300
697 End 00055100
000000D0 00000001 698 =f’1’
000000D4 00000000 699 =V(RCNVDATE)
000000D8 00000000 700 =V(RCNVTIME)
000000DC 00000002 701 =f’2’

Figure 7. Source and object listing section—133 format

1 The assembled address of the object code occupies 8 characters.

2 The Addr1 and Addr2 columns show 8-character operand addresses.
3 The first 8 characters of the macro name are shown in the
identification-sequence field.

Relocation dictionary
Figure 8 shows an example of the Relocation Dictionary section of the listing, which
contains information passed to the linkage editor, or z/OS Program Management
Binder, in the object module. The entries describe the address constants in the
assembled program that are affected by relocation.

SAMP01 Relocation Dictionary Page 5

1 2 3 4 5
Pos.Id Rel.Id Address Type Action HLASM R6.0 2008/07/11 17.48
00000003 00000003 000000B8 A 4 +
00000003 0000000D 000000D4 V 4 ST
00000003 0000000E 000000D8 V 4 ST

Figure 8. Relocation dictionary

Chapter 6. Programming and diagnostic aids 49

Assembler listings

1 Indicates the ESD ID assigned to the ESD entry for the control section in
which the address constant is defined.
2 Indicates the ESD ID assigned to the ESD entry for the control section to
which this address constant refers.
3 Shows the assembled address of the address constant.
4 Indicates the type and length of the address constant. The type may be one
of the following:
A A-type address constant
V V-type address constant
Q Q-type address constant
J J-type address constant or CXD instruction
R R-type address constant
RI Relative Immediate offset
5 Indicates the relocation action. The action may be one of the following:
+ the relocation operand is added to the address constant
- the relocation operand is subtracted from the address constant
ST the relocation operand overwrites the address constant

You can suppress this section of the listing by specifying the NORLD assembler
option.

Ordinary symbol and literal cross reference

Figure 9 shows an example of the Ordinary Symbol and Literal Cross Reference section
of the listing. It shows a list of symbols and literals defined in your program. This
is a useful tool for checking the logic of your program. It helps you see if your
data references and branches are correct.

50 HLASM: V1R6 General Information

 Assembler listings

SAMP01 Ordinary Symbol and Literal Cross Reference Page 6

1 2 3 4 5 6 7 8 9 10
Symbol Length Value Id R Type Asm Program Defn References HLASM R6.0 2008/07/11 17.48
DCBBIT0 1 00000080 FFFFFFFF A U 68 101 109 122 146 179 181 182 184 207 210 230 234 249 286
344
DCBBIT1 1 00000040 FFFFFFFF A U 69 102 110 124 147 148 157 163 179 181 183 184 212 230 232
234 252 253 254 289 290 344
DCBBIT2 1 00000020 FFFFFFFF A U 70 103 111 125 126 127 147 148 152 158 163 179 180 185 214
235 236 257 258 259 293 294 345
DCBBIT3 1 00000010 FFFFFFFF A U 71 104 125 127 128 147 160 186 217 235 238 261 262 263 297
298 345
DCBBIT4 1 00000008 FFFFFFFF A U 72 112 161 162 163 187 218 240 245 246 266 267 301 302 304
305 346
DCBBIT5 1 00000004 FFFFFFFF A U 73 113 168 190 191 220 240 242 243 246 270 272 273 274 308
309 310 311 346
DCBBIT6 1 00000002 FFFFFFFF A U 74 105 169 170 173 190 192 221 277 278 279 280 314 315 316
317 347
DCBBIT7 1 00000001 FFFFFFFF A U 75 106 169 171 173 194 225 282 283 320 321 323 324
Entry1 2 00000000 00000003 I 23 24 25U
IHADCB 1 00000000 FFFFFFFF J 56 34U 35U 83 132 203 328 335 353
INDCB 2 0000002A 00000003 H H 46 34U
Open 2 00000022 00000003 H H 366 42B
OUTDCB 2 0000007A 00000003 H H 48 35U
plist 1 00000000 FFFFFFFE J 360 37U 38U
| PlistIn ***QUALIFIER*** 00000001 U 37 38
RCNVDATE 1 00000000 0000000D T 699 699
RCNVTIME 1 00000000 0000000E T 700 700
r1 1 00000001 00000003 A U 369 40
r2 1 00000002 00000003 A U 370 41M
r5 1 00000005 00000003 A U 373 40M 41
Samp01 1 00000000 00000003 J 2 20 45 47 356 363 365
Savearea ***UNDEFINED*** 00000000 A U 26
=f’1’ 4 000000D0 00000003 F 698 396
=f’2’ 4 000000DC 00000003 F 701 400
=V(RCNVDATE)
4 000000D4 00000003 V 699 397
=V(RCNVTIME)
4 000000D8 00000003 V 700 399

Figure 9. Ordinary symbol and literal cross reference

1 Each symbol or literal. Symbols are shown in the form in which they are
defined, either in the name entry of a machine or assembler instruction, or
in the operand of an EXTRN or WXTRN instruction. Symbols defined
using mixed-case letters are shown in mixed-case letters, unless the FOLD
assembler option was specified.
2 The byte length of the field represented by the symbol, in decimal notation.
3 Shows the hexadecimal address that the symbol or literal represents, or the
hexadecimal value to which the symbol is equated.
4 Shows the ESD ID assigned to the ESD entry for the control section in
which the symbol or literal is defined.
5 Symbols DCBBIT0, DCBBIT1, etc. are absolute symbols and are flagged “A”
in the R column. A symbol that is the result of a complex relocatable
expression would be flagged “C” in the R column. Symbol INDCB is simply
relocatable and is not flagged. (Column title R is an abbreviation for
“Relocatability Type”.)
6 Indicates the type attribute of the symbol or literal.
7 Indicates the assembler type of the symbol.
8 Indicates the program type of the symbol.
9 Indicates the number of the statement in which the symbol or literal was
defined.
10 Shows the statement numbers of the statements in which the symbol or
literal appears as an operand. Additional indicators are suffixed to
statement numbers as follows:

Chapter 6. Programming and diagnostic aids 51

Assembler listings

B The statement contains a branch instruction, and the symbol is

used as the branch-target operand.
D The statement contains a DROP instruction, and the symbol is used
in the instruction operand.
M The statement caused the field named by the symbol to be
modified.
U The statement contains a USING instruction, and the symbol is
used in one of the instruction operands.
X The statement contains an EX machine instruction and the symbol,
in the second operand, is the symbolic address of the target
instruction.

You can suppress this section of the listing by specifying the NOXREF assembler
option. You can also suppress all symbols not referenced in the assembly by
specifying the XREF(SHORT) assembler option.

Unreferenced symbols defined in CSECTs

Figure 10 shows an example of the Unreferenced Symbols Defined in CSECTs section
of the listing. This section contains a list of symbols defined in CSECTs in your
program that are not referenced. It helps you remove unnecessary labels and data
definitions, and reduce the size of your program. Use the XREF(UNREFS)
assembler option to produce this section.

SAMP01 Unreferenced Symbols Defined in CSECTs Page 7

1 2
Defn Symbol HLASM R6.0 2008/07/11 17.48
35 ODCB
37 PlistIn
38 PlistOut
368 r0
378 r10
379 r11
380 r12
381 r13
382 r14
383 r15
371 r3
372 r4
374 r6
375 r7
376 r8
377 r9

Figure 10. Unreferenced symbols defined in CSECTS

1 Shows the statement number that defines the symbol.

2 Shows the symbol name.

General Purpose Register cross reference

Figure 11 shows an example of the General Purpose Register Cross Reference section of
the listing. It lists the registers, and the lines where they are referenced. This helps
find all references to registers, particularly those generated by macros that do not
use symbolic names, or references using symbolic names than the common R0, R1,
and so on.

52 HLASM: V1R6 General Information

 Assembler listings

General Purpose Register Cross Reference Page 11

Register References (M=modified, B=branch, U=USING, D=DROP, N=index) HLASM R6.0 2008/07/11 17.48
1 2
0(0) (no references identified)
1(1) 40 396M 397M 400M
2(2) 37U 41M 399M
3(3) 30U 31D 38U
4(4) (no references identified) 3
5(5) 30U 31D 40M 41
6(6) (no references identified)
7(7) (no references identified)
8(8) (no references identified)
9(9) (no references identified)
10(A) 27 28 29 30U 31D
11(B) (no references identified)
12(C) 23M 25U
13(D) 27 28 29M
14(E) (no references identified)
15(F) 23

Figure 11. General Purpose Register cross reference

1 Lists the sixteen general registers (0–15).

2 The statements within the program that reference the register. Additional
indicators are suffixed to the statement numbers as follows:
(blank) Referenced
M Modified
B Used as a branch address
U Used in USING statement
D Used in DROP statement
N Used as an index register
3 The assembler indicates when it has not detected any references to a
register.

You can produce this section of the listing by specifying the RXREF

Note: The implicit use of a register to resolve a symbol to a base and displacement
does not create a reference in the General Purpose Register Cross Reference.

Macro and copy code source summary

Figure 12 shows an example of the Macro and Copy Code Source Summary section of
the listing. This section shows where the assembler read each macro or copy code
member from. It helps you ensure you have included the correct version of a
macro or copy code member. Either the MXREF(SOURCE), or MXREF(FULL)
assembler option generates this section of the listing.

SAMP01 Macro and Copy Code Source Summary Page 8

1 2 3 4
Con Source Volume Members HLASM R6.0 2008/07/11 17.48
L1 SAMP01 MACLIB A1 FAL191 SAMPLE SAMPMAC
L2 OSMACRO MACLIB S2 MNT190 DCBD IHBERMAC

Figure 12. Macro and copy code source summary

1 Shows the concatenation value representing the source of the macros and

Chapter 6. Programming and diagnostic aids 53

Assembler listings

copy code members. This number is not shown if the source is PRIMARY
INPUT. The number is prefixed with L which indicates Library. The
concatenation value is cross referenced in the Macro and Copy Code Cross
Reference section, and the Diagnostic Cross Reference and Assembler Summary
section.
2 Shows the name of each library from which the assembler read a macro or
a copy code member. The term PRIMARY INPUT is used for in-line
macros.
3 Shows the volume serial number of the volume on which the library
resides.
4 Shows the names of the macros or copy members.

You can suppress this section of the listing by specifying the NOMXREF assembler
option, or by specifying the MXREF(XREF) assembler option.

Macro and copy code cross reference

Figure 13 shows an example of the Macro and Copy Code Cross Reference section of
the listing. This section lists the names of macros and copy code members used in
the program, and the statement numbers where each was called. Either the
MXREF(XREF), or MXREF(FULL) assembler option generates this section of the
listing.

SAMP01 Macro and Copy Code Cross Reference Page 28

1 2 3 4 5
Macro Con Called By Defn References HLASM R6.0 2008/07/11 17.48
A PRIMARY INPUT 826 971, 973, 998
AINSERT_TEST_MACRO
PRIMARY INPUT 3 16
AL PRIMARY INPUT 873 981, 983
DCBD L3 PRIMARY INPUT - 113
IHBERMAC L3 DCBD - 113
L PRIMARY INPUT 816 966, 968
MAC1 PRIMARY INPUT 28 36
N PRIMARY INPUT 933 991
O PRIMARY INPUT 953 993
SAMPLE L1 PRIMARY INPUT - 85C 6
SAMPMAC L1 PRIMARY INPUT - 64
SAVE L3 PRIMARY INPUT - 42
SL PRIMARY INPUT 883 986, 988
ST PRIMARY INPUT 836 976, 978
TYPCHKRX PRIMARY INPUT 745 775, 845, 892
X PRIMARY INPUT 943 996
XIT1 L1 PRIMARY INPUT - 30C
XIT2 L2 PRIMARY INPUT - 32C
XIT3 L1 PRIMARY INPUT - 34C

Figure 13. Macro and copy code cross reference

1 Shows the macro or copy code member name.

2 Shows the concatenation value representing the source of the macro or
copy code member. This value is cross-referenced in the Macro and Copy
Code Source Summary section, and under Datasets Allocated for this Assembly
in the Diagnostic Cross Reference and Assembler Summary section.
3 Shows the name of the macro that calls this macro or copy code member,
or PRIMARY INPUT, meaning that the macro or copy code member was
called directly from the primary input source.
4 Shows one of the following:

54 HLASM: V1R6 General Information

 Assembler listings

v The statement number for macros defined in the primary input file
v A dash (–) for macros or copy code members read from a library.
5 Shows the statement number that contains the macro call or COPY
instruction.
6 Shows the statement reference number with a suffix of C, which indicates
that the member is specified on a COPY instruction.

Figure 14 shows an example of the Macro and Copy Code Cross Reference section
when you specify the LIBMAC assembler option.

SAMP01 Macro and Copy Code Cross Reference Page 81

Macro Con Called By Defn References HLASM R6.0 2008/07/11 17.48
1
A PRIMARY INPUT 3667 3812, 3814, 3839
AINSERT_TEST_MACRO
PRIMARY INPUT 3 16
AL PRIMARY INPUT 3714 3822, 3824
DCBD L3 PRIMARY INPUT 224X 2329
IHBERMAC L3 DCBD 2331X 2954
L PRIMARY INPUT 3657 3807, 3809
MAC1 PRIMARY INPUT 28 36
N PRIMARY INPUT 3774 3832
O PRIMARY INPUT 3794 3834
SAMPLE L1 PRIMARY INPUT - 195C
SAMPMAC L1 PRIMARY INPUT 153X 174
SAVE L3 PRIMARY INPUT 43X 130
SL PRIMARY INPUT 3724 3827, 3829
ST PRIMARY INPUT 3677 3817, 3819
TYPCHKRX PRIMARY INPUT 3586 3616, 3686, 3733
X PRIMARY INPUT 3784 3837
XIT1 L1 PRIMARY INPUT - 30C
XIT2 L2 PRIMARY INPUT - 32C
XIT3 L1 PRIMARY INPUT - 34C

Figure 14. Macro and copy code cross reference - with LIBMAC option

1 The “X” flag indicates the macro was read from a macro library and
imbedded in the input source program immediately preceding the
invocation of that macro. For example, in Figure 14, you can see that
SAMPMAC was called by the PRIMARY INPUT stream from LIBRARY L1, at
statement number 174, after being imbedded in the input stream at
statement number 153.

You can suppress this section of the listing by specifying the NOMXREF assembler
option, or the MXREF(SOURCE) assembler option.

DSECT cross reference

Figure 15 shows an example of the DSECT Cross Reference section of the listing.
This section shows the names of all internal and external dummy sections defined
in the program, and the statement number where the definition of the dummy
section begins.

Chapter 6. Programming and diagnostic aids 55

Assembler listings

SAMP01 Dsect Cross Reference Page 9

1 2 3 4
Dsect Length Id Defn HLASM R6.0 2008/07/11 17.48
IHADCB 00000034 FFFFFFFF 56
plist 00000008 FFFFFFFE 360

Figure 15. DSECT cross reference

1 Shows the name of each dummy section defined in your program.
2 Shows, in hexadecimal notation, the assembled byte length of the dummy
section.
3 Shows the ESD ID assigned to the ESD entry for external dummy sections.
For internal dummy sections it shows the control section ID assigned to
the dummy control section. You can use this field in conjunction with the
ID field in the Ordinary Symbol and Literal Cross Reference section to relate
symbols to a specific DSECT.
4 Shows the number of the statement where the definition of the dummy
section begins.

You can suppress this section of the listing by specifying the NODXREF assembler
option.

USING map
Figure 16 shows an example of the Using Map section of the listing. It shows a
summary of the USING, DROP, PUSH USING, and POP USING instructions used
in your program.

SAMP01 Using Map Page 10

HLASM R6.0 2008/07/11 17.48
1 2 3 4 5 6 7 8
Stmt -----Location----- Action ----------------Using----------------- Reg Max Last Label and Using Text
Count Id Type Value Range Id Disp Stmt
25 00000002 00000003 USING ORDINARY 00000000 00001000 00000003 12 000DC 400 Entry1,12
30 00000010 00000003 USING ORDINARY 00000010 00001000 00000003 10 00000 *,10,3,5
30 00000010 00000003 USING ORDINARY 00001010 00001000 00000003 3 00000
30 00000010 00000003 USING ORDINARY 00002010 00001000 00000003 5 00000
31 00000010 00000003 DROP 10 10
31 00000010 00000003 DROP 3 3
31 00000010 00000003 DROP 5 5
34 00000010 00000003 USING DEPENDENT +0000002A 00000FD6 FFFFFFFF 12 IHADCB,INDCB
35 00000010 00000003 USING LAB+DEPND +0000007A 00000F86 FFFFFFFF 12 ODCB.IHADCB,OUTDCB
36 00000010 00000003 PUSH
37 00000010 00000003 USING LABELED 00000000 00001000 FFFFFFFE 2 00000 PlistIn.Plist,2
38 00000010 00000003 USING LABELED 00000000 00001000 FFFFFFFE 3 00000 PlistOut.Plist,3
403 000000E0 0000000C POP

Figure 16. USING map

1 Shows the number of the statement that contains the USING, DROP, PUSH
USING, or POP USING instruction.
2 Indicates whether the instruction was a USING, DROP, PUSH, or POP
instruction.
3 Shows the type of USING instruction. A USING instruction can be an
ordinary USING, a labeled USING, a dependent USING, or a labeled
dependent USING.

56 HLASM: V1R6 General Information

 Assembler listings

4 For ordinary and labeled USING instructions, this field indicates the base
address specified in the USING. For dependent USING instructions, this
field is prefixed with a plus sign (+) and indicates the hexadecimal offset
of the address of the second operand from the base address specified in
the corresponding ordinary USING.
5 Shows the range of the USING. For more information, see the description
of the USING statement in the HLASM Language Reference.
6 For USING instructions, this field indicates the ESDID of the section
specified on the USING statement.
7 Indicates the registers specified in USING instructions, and DROP
instructions. There is a separate line in the USING map for each register
specified in the instruction.
8 Shows the maximum displacement from the base register that the
assembler calculated when resolving symbolic addresses into
base-displacement form.

You can suppress this section of the listing by specifying the USING(NOMAP)
assembler option, or the NOUSING assembler option.

Diagnostic cross reference and assembler summary

Figure 17 shows an example of the Diagnostic Cross Reference and Assembler
Summary section of the listing. This sample listing is from a CMS assembly, and
shows CMS data set information.

This section includes a summary of the statements flagged with diagnostic

messages, and provides statistics about the assembly. You cannot suppress this
section unless you use a LISTING exit to discard the listing lines.

See the description of the sample LISTING exit on page 40, which lets you
suppress this section.

Chapter 6. Programming and diagnostic aids 57

Assembler listings

Diagnostic Cross Reference and Assembler Summary Page 9

HLASM R6.0 2008/07/11 17.48
Statements Flagged
1
1(P1,0), 3(P1,3), 4(P1,4), 5(P1,5), 6(P1,6), 7(P1,7), 8(P1,8), 170(L3:DCBD,2149)

2 8 Statements Flagged in this Assembly 16 was Highest Severity Code

High Level Assembler, 5696-234, RELEASE 5.0
SYSTEM: CMS 11 JOBNAME: (NOJOB) STEPNAME: (NOSTEP) PROCSTEP: (NOPROC) 3
Datasets Allocated for this Assembly 4
Con DDname Data Set Name Volume Member
A1 ASMAOPT XITDIS OPTIONS A1 ADISK
P1 SYSIN XITDIS ASSEMBLE A1 ADISK
L1 SYSLIB TEST MACLIB A1 ADISK
L2 DSECT MACLIB A1 ADISK
L3 OSMACRO MACLIB S2 MNT190
L4 OSMACRO1 MACLIB S2 MNT190
5 SYSLIN XITDIS TEXT A1 ADISK
SYSPRINT XITDIS LISTING A1 ADISK

External Function Statistics 6

----Calls---- Message Highest Function
SETAF SETCF Count Severity Name
3 1 5 22 MSG
1 0 2 8 MSG1
1 0 1 0 MSG2
7
Input/Output Exit Statistics
Exit Type Name Calls ---Records--- Diagnostic
Added Deleted Messages
LIBRARY CTLXIT 258 0 0 2
LISTING ASMAXPRT 195 0 52 0
8
Suppressed Message Summary
Message Count Message Count Message Count Message Count Message Count
169 0 306 0 309 0 320 0

94622K allocated to Buffer Pool,

16 Primary Input Records Read 3072 Library Records Read
1 ASMAOPT Records Read 141 Primary Print Records Written
2 Punch Records Written 0 ADATA Records Written
Assembly Start Time: 12.06.06 Stop Time: 12.06.07 Processor Time: 00.00.00.1771 10
Return Code 016

Figure 17. Diagnostic cross reference and assembler summary

1 The statement number of a statement that causes an error message, or

contains an MNOTE instruction, appears in this list. Flagged statements are
shown in either of two formats. When assembler option
FLAG(NORECORD) is specified, only the statement number is shown.
When assembler option FLAG(RECORD) is specified, the format is:
statement(dsnum:member,record), where:
statement
is the sequential, absolute statement number as shown in the
source and object section of the listing.
dsnum is the value applied to the source or library dataset, showing the
type of input file and the concatenation number. “P” indicates the
statement was read from the primary input source, and “L”
indicates the statement was read from a library. This value is
cross-referenced to the input datasets listed under the sub-heading
“Datasets Allocated for this Assembly” 4.
member
is the name of the macro from which the statement was read. On

58 HLASM: V1R6 General Information

 Assembler listings

z/OS, this may also be the name of a partitioned data set member
that is included in the primary input (SYSIN) concatenation.
record is the relative record number from the start of the dataset or
member which contains the flagged statement.
2 The number of statements flagged, and the highest non-zero severity code
of all messages issued.
3 Provides information about the system on which the assembly was run.
4 On z/OS and CMS, all data sets used in the assembly are listed by their
standard DDname. The data set information includes the data set name,
and the serial number of the volume containing the data set. On z/OS, the
data set information may also include the name of a member of a
partitioned data set (PDS).
If a user exit provides the data set information, then the data set name is
the value extracted from the Exit-Specific Information Block described in
“Exit-Specific Information Block” in the HLASM Programmer’s Guide.
The “Con” column shows the concatenation value assigned for each input
data set. You use this value to cross-reference flagged statements, and
macros and copy code members listed in the Macro and Copy Code Cross
Reference section.
5 Output data sets do not have a concatenation value.
6 The usage statistics of external functions for the assembly. The following
statistics are reported:
SETAF function calls The number of times the function was
called from a SETAF assembler instruction.
SETCF function calls The number of times the function was
called from a SETCF assembler instruction.
Messages issued The number of times the function
requested that a message be issued.
Messages severity The maximum severity for the messages
issued by this function.
Function name The name of the external function module.
7 The usage statistics of the I/O exits you specified for the assembly. If you
do not specify an exit, the assembler does not produce any statistics. The
following statistics are reported:
Exit type
The type of exit.
Name The name of the exit module as specified in the EXIT assembler
option.
Calls The number of times the exit was called.
Records
The number of records added and deleted by the exit.
Diagnostic messages
The number of diagnostic messages printed, as a result of exit
processing.

Chapter 6. Programming and diagnostic aids 59

Assembler listings

All counts are shown right justified and leading zeroes are suppressed,
unless the count is zero.
8 The suppressed message statistics for the assembly.
These messages have been suppressed by means of the SUPRWARN
option.
9 Statistics about the assembly.
10 On z/VSE, the assembly start and stop times in hours, minutes and
seconds.
On z/OS and CMS, the assembly start and stop times in hours, minutes
and seconds and the approximate amount of processor time used for the
assembly, in hours, minutes, and seconds to four decimal places.

Improved page-break handling

In order to prevent unnecessary page ejects that leave blank pages in the listing,
the assembler takes into account the effect EJECT, SPACE and TITLE instructions
have when the assembler listing page is full. The EJECT and TITLE instruction
explicitly starts a new page, while the assembler implicitly starts a new page when
the current page is full.

When an explicit new page is pending the following processing occurs:

v Successive EJECT statements are ignored
v Successive TITLE statements allow the title to change but the EJECT is ignored
v A SPACE statement forces a new page heading to be written, followed by the
given number of blank lines. The number of blank lines specified can cause an
implicit page eject if the number exceeds the page depth.

When an implicit new page is pending the following processing occurs:

v An EJECT statement converts the implicit new page to an explicit pending new
page.
v A TITLE statement converts the implicit new page to an explicit pending new
page and redefines the title.
v Any other statement forces a new page heading to be printed.

Diagnostic messages in open code

The Source and Object section of the assembler listing shows in-line diagnostic
messages. The Diagnostic Cross Reference and Assembler Summary shows the total
number of diagnostic messages and the statement numbers of flagged statements.
Many in-line messages include a copy of the segment of the statement that is in
error.

When you specify the FLAG assembler option, the assembler may print additional
diagnostic messages. The FLAG(ALIGN) option directs the assembler to issue
diagnostic messages when there is an alignment error between an operation code
and the operand data address. The FLAG(CONT) option directs the assembler to
issue diagnostic messages when the assembler detects a possible continuation error.
The FLAG(RECORD) option directs the assembler to print an additional
informational message after the last error diagnostic message for each statement in
error. Figure 18 shows the effect of the FLAG(RECORD) option:

60 HLASM: V1R6 General Information

 Diagnostic messages in open code

000000 1 CSECT
.
.
.
22 COMM
** ASMA057E Undefined operation code - COMM
** ASMA435I Record 22 in ’HLASM3.SAMPLE.SOURCE(SAMP01)’ on volume: HLASM3
.
.
.
000000 35 DS (*+5)F
** ASMA032E Relocatable value found when absolute value required - (*+5)F
** ASMA435I Record 35 in ’HLASM3.SAMPLE.SOURCE(SAMP01)’ on volume: HLASM3
000000 00000000 36 2NAME DC F’0’
** ASMA147E Symbol too long, or first character not a letter - 2NAME
** ASMA435I Record 36 in ’HLASM3.SAMPLE.SOURCE(SAMP01)’ on volume: HLASM3
.
.
.
118 &C SETC ’AGO’
119 &C .X
ASMA001E Operation code not allowed to be generated - AGO
ASMA435I Record 119 in ’HLASM3.SAMPLE.SOURCE(SAMP01)’ on volume: HLASM3
.
.
.
151 END

Figure 18. In-line error messages in open code

You can locate messages in your assembly listing by searching for “** ASMA” in
the listing. The preferred alternative is to specify the TERM option.

Macro-generated statements
A macro-generated statement is a statement generated by the assembler after a
macro call. During macro generation, the assembler copies any model statements
processed in the macro definition into the input stream for further processing.
Model statements are statements from which assembler language statements are
generated during conditional assembly. You can use variable symbols as points of
substitution in a model statement to vary the contents or format of a generated
statement.

Open code: Model statements can also be included in open code by using variable
symbols as points of substitution.

Sequence field in macro-generated statements

The Source and Object section of the listing includes an identification-sequence field
for macro-generated statements. This field is printed to the extreme right of each
generated statement in the listing.

When a statement is generated from a library macro, the identification-sequence

field of the generated statement contains the nesting level of the macro call in the
first two columns, a hyphen in the third column, and the macro definition name in
the remaining columns.

On z/OS and CMS, when you specify the LIST(121) assembler option, the first 5
characters of the macro name are printed after the hyphen. When you specify the
LIST(133) assembler option, the first 8 characters of the macro name are printed
after the hyphen.

Chapter 6. Programming and diagnostic aids 61

Macro-generated statements

On z/VSE, only the first 5 characters of the macro name are printed after the
hyphen.

This information can be an important diagnostic aid when analyzing output

dealing with macro calls within macro calls.

When a statement is generated from an in-line macro or a copied library macro,

the identification-sequence field of the generated statement contains the nesting
level of the macro call in the first two columns, a hyphen in the third column, and
the model statement number from the definition in the remaining columns.

Format of macro-generated statements

Whenever possible, the assembler prints a generated statement in the same format
as the corresponding macro-definition (model) statement. The assembler preserves
the starting columns of the operation, operand, and comments fields unless they
are displaced by field substitution, as shown in the following example:

Loc Object Code Addr1 Addr2 Stmt Source Statement HLASM R6.0 2008/07/11 17.48
1 macro
2 macgen
3 &A SETC ’abcdefghijklmnopq’
4 &A LA 1,4 Comment
5 &B SETC ’abc’
6 &B LA 1,4 Comment
7 mend
8 macgen
000000 4110 0004 00004 9+abcdefghijklmnopq LA 1,4 Comment 01-00004
000004 4110 0004 00004 10+abc LA 1,4 Comment 01-00006
11 end

Figure 19. Format of macro-generated statements

Macro-generated statements with PRINT NOGEN

The PRINT NOGEN instruction suppresses the printing of all statements generated
by the processing of a macro. PRINT NOGEN also suppress the generated
statement for model statements in open code. When the PRINT NOGEN
instruction is in effect, the assembler prints one of the following on the same line
as the macro call or model statement:
v The object code for the first instruction generated. The object code includes the
data that is shown under the ADDR1 and ADDR2 columns of the assembler
listing.
v The first 8 bytes of generated data from a DC instruction

When the assembler forces alignment of an instruction or data constant, it

generates zeros in the object code and prints the generated object code in the
listing. When you use the PRINT NOGEN instruction the generated zeros are not
printed.

Note: If the next line to print after macro call or model statement is a diagnostic
message, the object code or generated data is not shown in the assembler
listing.

Figure 20 shows the object code of the first statement generated for the wto
macro instruction when PRINT NOGEN is effective. The data constant (DC)
for jump causes 7 bytes of binary zeroes to be generated before the DC to
align the constant on a double word. With PRINT NOGEN effective, these

62 HLASM: V1R6 General Information

 Macro-generated statements

are not shown, but the location counter accounts for them.

Loc Object Code Addr1 Addr2 Stmt Source Statement HLASM R6.0 2008/07/11 17.48
..
.
000016 1851 13 lr 5,1
14 print nogen
000018 4510 F026 00002 15 wto ’Hello’
000028 C1 23 dc cl1’A’
000030 4238000000000000 24 jump dc d’56’
..
.

Figure 20. The effect of the PRINT NOGEN instruction

Diagnostic messages in macro assembly

The diagnostic facilities for High Level Assembler include diagnostic messages for
format errors within macro definitions, and assembly errors caused by statements
generated by the macro.

Error messages for a library macro definition

Format errors within a particular library macro definition are listed directly
following the first call to that macro. Subsequent calls to the library macro do not
result in this type of diagnostic. You can bring the macro definition into the source
program with a COPY statement or by using the LIBMAC assembler option. The
format errors then follow immediately after the statements in error. The macro
definition in Figure 21 shows a format error in the LCLC instruction:

Name Operation Operand Comment

MACRO
MAC1
.
.
.
LCLC &.A Invalid variable symbol
.
.
.
&N SETA &A
.
.
.
MEND

Figure 21. Macro definition with format error

Chapter 6. Programming and diagnostic aids 63

Diagnostic messages in macro assembly

Figure 22 shows the placement of error messages when the macro is called:

1 MAC1
** ASMA024E Invalid variable symbol - MACRO - MAC1
.
.
.
** ASMA003E Undeclared variable symbol; default=0, null, or type=U - LIBMA/A
.
.
.
36 MAC1
.
.
.
** ASMA003E Undeclared variable symbol; default=0, null, or type=U - LIBMA/A
.
.
.
66 END

Figure 22. Error messages for a library macro definition

Error messages for source program macro definitions

The assembler prints diagnostic messages for macro-generated statements even if
the PRINT NOGEN instruction is in effect. In-line macro editing error diagnostic
messages are inserted in the listing directly following the macro definition
statement in error. Errors analyzed during macro generation produce in-line
messages in the generated statements.

Terminal output
On z/OS and CMS, the TERM option lets you receive a summary of the assembly
at your terminal. You may direct the terminal output to a disk data set.

On z/VSE, the TERM option lets you send a summary of the assembly to SYSLOG.

The output from the assembly includes all error diagnostic messages and the
source statement in error. It also shows the number of flagged statements and the
highest severity code.

The terminal output can be shown in two formats. Figure 24 on page 65, the wide
format, shows the source statements in the same columns as they were in the input
data set. Figure 23, the narrow format, shows the source statements which have
been compressed by replacing multiple consecutive blanks with a single blank. Use
the TERM assembler option to control the format.

1 &abc setc l’f 00000100

ASMA137S Invalid character expression - l’f
000000 3 dc c’’ 00000300
ASMA068S Length error - ’
Assembler Done 2 Statements Flagged / 12 was Highest Severity Code

Figure 23. Sample terminal output in the NARROW format

64 HLASM: V1R6 General Information

 Terminal output

1 &abc setc l’f

00000100
ASMA137S Invalid character expression - l’f
000000 3 dc c’’
00000300
ASMA068S Length error - ’
Assembler Done 2 Statements Flagged / 12 was Highest Severity Code

Figure 24. Sample terminal output in the WIDE format

You can replace or modify the terminal output using a TERM user exit. See
Chapter 5, “Using exits to complement file processing,” on page 37.

Input/output enhancements
High Level Assembler includes the following enhancements:
v QSAM Input/Output
The assembler uses QSAM input/output for all sequential data sets.
v System-Determined Blocksize
Under z/OS, High Level Assembler supports DFSMS System-Determined
Blocksize (SDB) for all output datasets, except SYSPUNCH and SYSLIN.
SDB is applicable when all of the following conditions are true:
– You run High Level Assembler under a z?OS operating system that includes a
DFSMS level of 3.1 or higher.
– You DO NOT allocate the data set to SYSOUT.
– Your JCL omits the blocksize, or specifies a blocksize of zero.
– You specify a record length (LRECL).
– You specify a record format (RECFM).
– You specify a data set organization (DSORG).
If these conditions are met, DFP selects the appropriate blocksize for a new data
set depending on the device type you select for output.
If the System-Determined Blocksize feature is not available, and your JCL omits
the blocksize, or specifies a blocksize of zero, the assembler uses the logical
record length as the blocksize.

CMS interface command

The name of the CMS interface command is ASMAHL. Your installation can create
a synonym for ASMAHL when High Level Assembler is installed.

You can specify assembler options as parameters when you issue the High Level
Assembler command. You may delimit each parameter using either a space or
comma. There must be no intervening spaces when you specify suboptions and
their delimiters.

The following invocation of High Level Assembler is not correct:

ASMAHL XREF( SHORT )

The assembly continues but issues message ASMA400W ERROR IN INVOCATION

PARAMETER in the High Level Assembler Options Summary section of the assembly
listing.

The correct way to specify the option is as follows:

Chapter 6. Programming and diagnostic aids 65

CMS interface command

ASMAHL XREF(SHORT)

The Assembler H Version 2 CMS-specific options NUM, STMT, and TERM have
been removed. SYSTERM support is provided by the standard assembler TERM
option.

The new SEG and NOSEG options let you specify from where CMS should load
the High Level Assembler modules. By default the assembler loads its modules
from the Logical Saved Segment (LSEG), but if the LSEG is not available, it loads
the modules from disk. You can specify the NOSEG option to force the assembler
to load its modules from disk, or you can specify the SEG option to force the
assembler to load its modules from the Logical Saved Segment (LSEG). If the
assembler cannot load its modules it terminates with an error message.

Macro trace facility (MHELP)

The assembler provides you with a set of trace and dump facilities to assist you in
debugging errors in your macros and conditional assembly language. You use the
MHELP instruction to invoke these trace and dump facilities. You can code a
MHELP instruction anywhere in open code or in macro definitions. The operands
on the MHELP instruction let you control which facilities to invoke. Each trace or
dump remains in effect until you supersede it with another MHELP instruction.

The MHELP instruction lets you select one or more of the following facilities:
Macro Call Trace
A one-line trace for each macro call
Macro Branch Trace
A one-line trace for each AGO and true AIF conditional assembly
statement within a macro
Macro Entry Dump
A dump of parameter values from the macro dictionary immediately after
a macro call is processed
Macro Exit Dump
A dump of SET symbol values from the macro dictionary on encountering
a MEND or MEXIT statement
Macro AIF dump
A dump of SET symbol values from the macro dictionary immediately
before each AIF statement that is encountered
Global Suppression
Suppresses the dumping of global SET symbols in the two preceding types
of dump
Macro Hex Dump
An EBCDIC and hexadecimal dump of the parameters and SETC symbol
values when you select the Macro AIF dump, the Macro Exit dump or the
Macro Entry dump
MHELP suppression
Stops all active MHELP options.
MHELP Control on &SYSNDX
Controls the maximum value of the &SYSNDX system variable symbol.
The limit is set by specifying the number in the operand of the MHELP
instruction. When the &SYSNDX value is exceeded, the assembler

66 HLASM: V1R6 General Information

 Macro trace facility (MHELP)

produces a diagnostic message, terminates all current macro generation,

and ignores all subsequent macro calls.

Abnormal termination of assembly

Whenever the assembler detects an error condition that prevents the assembly
from completing, it issues an assembly termination message and, in most cases,
produces a specially formatted dump. This feature helps you determine the nature
of the error. The dump is also useful if the abnormal termination is caused by an
error in the assembler itself.

Diagnosis facility
If there is an error in the assembler, the IBM service representative may ask for the
output produced by the assembler, and the source program to help debug the
error. A new internal trace facility in the assembler can provide the IBM service
representative with additional debugging information. The IBM service
representative determines the need for this information and the circumstances
under which it can be produced. Until this facility is invoked, its inclusion in the
assembler does not impact the performance.

Chapter 6. Programming and diagnostic aids 67

68 HLASM: V1R6 General Information
Chapter 7. Associated Data Architecture
This chapter describes High Level Assembler support for the associated data
architecture. Associated data was previously known as assembler language
program data. This support includes a general-use programming interface which
lets you write programs to use the associated data records the High Level
Assembler produces.

The associated data (ADATA) file contains language-dependent and

language-independent records. Language-dependent records contain information
that is relevant only to programs assembled by the High Level Assembler.
Language-independent records contain information that is common to all
programming languages that produce ADATA records, and includes information
about the environment the program is assembled in. You use the ADATA
assembler option to produce this file.

The ADATA file contains variable-length blocked records. The maximum record
length is 32756 bytes, and the maximum block size is 32760 bytes.

The file contains records classified into different record types. Each type of record
provides information about the assembler language program being assembled.
Each record consists of two parts:
v A 12-byte header section which has the same structure for all record types
v A variable-length data section, which varies by record type

The header section contains:

v The language code
v The record code, which identifies the type of record
v The associated data file architecture level
v A continuation flag indicator
v The record edition number
v The length of data following

The records written to the ADATA file are:

Job identification
This record provides information about the assembly job, and its
environment, including the names of primary input files.
ADATA identification
This record contains the Universal Time, and the Coded Character Set used
by the assembler.
ADATA compilation-unit (Start)
This record contains the assembly start time.
ADATA compilation-unit (End)
This record contains the assembly stop time, and the number of ADATA
records written.
Output file information
This record provides information about the data sets the assembler
produces.

© Copyright IBM Corp. 1981, 2008 69

Associated Data Architecture

Options file information

This record provides information about the external options file the
assembler read, if provided
Options
This record contains the assembler options specified for the assembly.
External Symbol Dictionary (ESD)
This record describes all the control sections, including DSECTs, defined in
the program.
Source analysis
This record contains the assembled source statements, with additional data
describing the type and specific contents of the statement.
Source error
This record contains error message information the assembler produces
after a source statement in error.
DC/DS
This record describes the constant or storage defined by a source program
statement that contains a DC or DS instruction. If a source program
statement contains a DC or DS instruction, then a DC/DS record is written
following the Source record.
DC extension
This record describes the object code generated by a DC statement when
the DC statement has repeating fields. This record is only created if the DC
statement has a duplication factor greater than 1 and at least one of the
operand values has a reference to the current location counter (*).
Machine instruction
This record describes the object code generated for a source program
statement. If a source program statement causes machine instructions to be
generated, then a Machine Instruction record is written following the
Source record.
Relocation Dictionary (RLD)
This record describes the relocation dictionary information that is included
in the object module.
Symbol
This record describes a single symbol or literal defined in the program.
Ordinary symbol and literal cross reference
This record describes references to a single symbol.
Macro and copy code source summary
This record describes the source of each macro and copy code member
retrieved by the program.
Macro and copy code cross reference
This record describes references to a single macro or copy code member.
USING map
This record describes all USING, DROP, PUSH USING, and POP USING
statements in the program.
Statistics
This record describes the statistics about the assembly.
User-supplied information
This record contains data from the ADATA instruction.

70 HLASM: V1R6 General Information

 Associated Data Architecture

Register cross reference

This record describes references to a single General Purpose register.

Chapter 7. Associated Data Architecture 71

Associated Data Architecture

72 HLASM: V1R6 General Information

 Chapter 8. Factors improving performance
This chapter describes some of the methods used by High Level Assembler that
improve assembler execution performance relative to earlier assemblers. These
improvements are gauged on the performance of typical assemblies, and there
might be cases where the particular circumstances of your application or system
configuration do not achieve them. The main factors that improve the performance
of High Level Assembler are:
v Logical text stream and tables that are a result of the internal assembly process
remain resident in virtual storage, whenever possible, throughout the assembly.
v High Level Assembler can be installed in shared virtual storage.
v High Level Assembler exploits 31-bit addressing.
v High Level Assembler runs entirely in storage: the utility files, SYSUT1 or
IJSYS03, are no longer used.
v Two or more assemblies can be done with one invocation of the assembler.
v High Level Assembler edits only the macro definitions that it encounters during
a given macro generation or during conditional assembly of open code, as
controlled by AIF and AGO statements.
v Source text assembly passes are consolidated. The edit and generation of macro
statements are done on a demand basis in one pass of the source text.

Resident tables and source text: Keeping intermediate text, macro definition text,
dictionaries, and symbol tables in main storage whenever possible improves
| performance. High Level Assembler writes working storage blocks to the assembler
| work data set only if necessary, and then only if the WORKFILE option is
| specified. Less input and output reduces system overhead and frees channels and
input/output devices for other uses.

The amount of working storage allocated to High Level Assembler is determined

by the SIZE assembler option, and is limited only by the amount available in the
address space.

Shared virtual storage: High Level Assembler is a reentrant program that can be
installed in shared virtual storage, such as the z/OS Link Pack Area (LPA), a CMS
logical saved segment or in a VSE Shared Virtual Area (SVA). When High Level
Assembler is installed in shared virtual storage, the demand for system resources
associated with loading the assembler load modules is reduced. In a multi-user
environment, multiple users are able to share one copy of the assembler load
modules.

31-bit addressing: High Level Assembler takes advantage of the extended address
space, available in extended architecture operating systems, by allowing most of its
data areas to reside above the 16-megabyte line. I/O areas and exit parameter lists
remain in storage below the 16-megabyte line to satisfy access method
requirements and user exits using 24-bit addressing mode. The High Level
Assembler’s modules can be loaded above the 16-megabyte line, except for some
| initialization routines. 31-bit addressing increases the assembler’s available work
area, which allows larger programs than previously possible to be assembled
in-storage. In-storage assemblies reduce the input and output system overhead and
free channels and input/output devices for other uses.

© Copyright IBM Corp. 1981, 2008 73

Factors improving performance

Multiple assembly: You can run multiple assemblies, known as batching, with one
invocation of the assembler. Source records are placed together, with no
intervening ‘/*’ JCL statement.

Batch assembly improves performance by eliminating job and step overhead for
each assembly. It is especially useful for processing related assemblies such as a
main program and its subroutines.

Macro-editing process: High Level Assembler edits only those macro definitions
encountered during a given macro generation or during conditional assembly or
open code, as controlled by AIF and AGO statements.

A good example of potential savings by this feature is the process of system

generation. During system generation, High Level Assembler edits only the set of
library macro definitions that are expanded; as a result, High Level Assembler may
edit fewer library macro definitions than previous assemblers.

Unlike DOS/VSE Assembler, High Level Assembler requires that library macros be
stored in source format. This removes the necessity to edit library macros before
they can be stored in the library.

Consolidating source text passes: Consolidating assembly source text passes and
other new organization procedures reduce the number of internal processor
instructions used to handle source text in High Level Assembler, which causes
proportionate savings in processor time. The saving is independent of the size or
speed of the system processor involved; it is a measure of the relative efficiency of
the processor.

74 HLASM: V1R6 General Information

Appendix A. Assembler options
High Level Assembler provides you with many assembler options for controlling
the operation and output of the assembler. You can set default values at assembler
installation time for most of these assembler options. You can also fix a default
option so the option cannot be overridden at assembly time. See “IBM-supplied
default assembler options” on page 17 for a list of the changes to the IBM-supplied
default assembler options from High Level Assembler Release 4.

You specify the options at assembly time on:

v An external file (z/OS and CMS) or library member (z/VSE)
v The JCL PARM parameter of the EXEC statement on z/OS and z/VSE, or the
ASMAHL command on CMS.
v The JCL OPTION statement On z/VSE.
v The *PROCESS assembler statement.

The assembler options are:

ADATA | NOADATA
Produce the associated data file.
ALIGN | NOALIGN
Check alignment of addresses in machine instructions and whether DC,
DS, DXD, and CXD are aligned on correct boundaries.
ASA | NOASA
(z/OS and CMS) Produce the assembly listing using American National
Standard printer-control characters. If NOASA is specified the assembler
uses machine printer-control characters.
BATCH | NOBATCH
Specify multiple assembler source programs are in the input data set.
CODEPAGE(X’047C’)
Specify the code page module to be used to convert Unicode character
constants
COMPAT(suboption) | NOCOMPAT
Direct the assembler to remain compatible with earlier assemblers in its
handling of lowercase characters in the source program, and its handling
of sublists in SETC symbols, and its handling of unquoted macro operands.
The LITTYPE suboption instructs the assembler to return ’U’ as the type
attribute for all literals.
DBCS | NODBCS
Specify that the source program contains double-byte characters.
DECK | NODECK
Produce an object module.
DXREF | NODXREF
Produce the DSECT Cross Reference section of the assembler listing.
ERASE | NOERASE
(CMS) Delete specified files before running the assembly.

© Copyright IBM Corp. 1981, 2008 75

Assembler options

ESD | NOESD
Produce the External Symbol Dictionary section of the assembler listing.
EXIT(suboption1,suboption2,...) | NOEXIT
Provide user exits to the assembler for input/output processing.
ADEXIT(name(string)) | NOADEXIT
Identify the name of a user-supplied ADATA exit module.
INEXIT(name(string)) | NOINEXIT
Identify the name of a user-supplied SOURCE exit module.
LIBEXIT(name(string)) | NOLIBEXIT
Identify the name of a user-supplied LIBRARY exit module.
OBJEXIT(name(string)) | NOOBJEXIT
Identify the name of a user-supplied OBJECT exit module.
PRTEXIT(name(string)) | NOPRTEXIT
Identify the name of a user-supplied LISTING exit module.
TRMEXIT(name(string)) | NOTRMEXIT
Identify the name of a user-supplied TERM exit module.
FLAG(suboption1,suboption2,...)
Specify the level and type of error diagnostic messages to be written.
FOLD | NOFOLD
Convert lowercase characters to uppercase characters in the assembly
listing.
GOFF | NOGOFF
(z/OS and CMS) Set generalized object format.
INFO | NOINFO
Display service information selected by date.
LANGUAGE(EN | ES | DE | JP | UE)
Specify the language in which assembler diagnostic messages are
presented. High Level Assembler lets you select any of the following:
v English mixed case (EN)
v English uppercase (UE)
v German (DE)
v Japanese (JP)
v Spanish (ES)
When you select either of the English languages, the assembler listing
headings are produced in the same case as the diagnostic messages.
When you select either the German language or the Spanish language, the
assembler listing headings are produced in mixed case English.
When you select the Japanese language, the assembler listing headings are
produced in uppercase English.
The assembler uses the default language for messages produced on CMS
by the High Level Assembler command.
LIBMAC | NOLIBMAC
Instruct the assembler to imbed library macro definitions in the input
source program.
LINECOUNT(integer)
Specify the number of lines to print in each page of the assembly listing.

76 HLASM: V1R6 General Information

 Assembler options

LIST | LIST(121 | 133 | MAX) | NOLIST

(z/OS and CMS) Specify whether the assembler produces an assembly
listing. The listing may be produced in 121-character format or
133-character format.
LIST | NOLIST
(VSE only) Specify whether the assembler produces an assembly listing.
| MACHINE([370 | S370XA | S370ESA | S390 | S390E | ZSERIES | ZS |
| ZSERIES-2 | ZS-2 | ZSERIES-3 | ZS-3& vbar; ZSERIES-4 | ZS-4][,LIST |
| NOLIST])
Specify the operation code table to use to process machine instructions in
the source program. A alternative to the OPTABLE option, the operands
are also synonyms of, but are not identical to, those of the OPTABLE
option.
MXREF | MXREF(FULL | SOURCE | XREF) | NOMXREF
Produce the Macro and Copy Code Source Summary, or the Macro and Copy
Code Cross Reference, or both, in the assembly listing.
OBJECT | NOOBJECT
Produce an object module.
| OPTABLE([DOS | ESA | UNI | XA | 370 | YOP | ZOP | ZS3 | ZS4][,LIST |
| NOLIST])
Specify the operation code table to use to process machine instructions in
the source program.
PCONTROL(suboption1,suboption2,...) | NOPCONTROL
Specify whether the assembler should override certain PRINT statements
in the source program.
PESTOP
Specify that the assembler should stop immediately if errors are detected
in the invocation parameters.
PRINT | DISK | NOPRINT
(CMS) Specify that the assembler should write the LISTING file on the
virtual printer.
PROFILE | PROFILE(name) | NOPROFILE
Specify the name of a library member, containing assembler source
statements, that is copied immediately following an ICTL statement or
*PROCESS statements, or both. The library member can be specified as a
default in the installation options macro ASMAOPT.
RA2 | NORA2
Specify whether the assembler is to suppress error diagnostic message
ASMA066 when 2-byte relocatable address constants are defined in the
source program.
RENT | NORENT
Check for possible coding violations of program reenterability.
RLD | NORLD
Produce the Relocation Dictionary section of the assembler listing.
RXREF
Produce the Register Cross Reference section of the assembler listing.
SECTALGN(alignment)
Specify the desired alignment for all sections, expressed as a power of 2
with a range from 8 (doubleword) to 4096 (page).

Appendix A. Assembler options 77

 Assembler options

SEG | NOSEG
(CMS) Specify that assembler modules are loaded from the Logical Saved
Segment (LSEG).
SIZE(value)
Specify the amount of virtual storage that the assembler can use for
working storage.
SUPRWARN(msgnum1,msgnum2,...) | NOSUPRWARN
Specify one or more message numbers, of warning (4) or less severity, to be
suppressed.
SYSPARM(value)
Specify the character string that is to be used as the value of the
&SYSPARM system variable.
TERM(WIDE | NARROW) | NOTERM
Specify whether error diagnostic messages are to be written to the terminal
data set On z/OS and CMS, or SYSLOG On z/VSE.
TEST | NOTEST
Specify whether special symbol table data is to be generated as part of the
object module.
THREAD | NOTHREAD
Specify whether or not the location counter is to be reset at the beginning
of each CSECT.
TRANSLATE(AS | suffix) | NOTRANSLATE
Specify whether characters contained in character (C-type) data constants
(DCs) and literals should be translated using a user-supplied translation
table. The suboption AS directs the assembler to use the ASCII translation
table provided with High Level Assembler.
TYPECHECK(suboption1,suboption2) | NOTYPECHECK
Control whether or not HLASM performs type checking of machine
instruction operands.
USING(suboption1,suboption2,...) | NOUSING
Specify the level of monitoring of USING statements required, and whether
the assembler is to generate a USING map as part of the assembly listing.
| WORKFILE | NOWORKFILE
| If storage apart from central storage is required during assembly, use the
| utility file for temporary storage.
XREF(SHORT | UNREFS | FULL) | NOXREF
Produce the Ordinary Symbol and Literal Cross Reference, or the Unreferenced
Symbols Defined in CSECTs, or both, in the assembly listing.

78 HLASM: V1R6 General Information

Appendix B. System variable symbols
System variable symbols are a special class of variable symbols, starting with the
characters &SYS. The values are set by the assembler according to specific rules. You
cannot declare system variable symbols in local SET symbols or global SET
symbols, nor can you use them as symbolic parameters.

You can use these symbols as points of substitution in model statements and
conditional assembly instructions. You can use some system variable symbols both
inside macro definitions and in open code, and some system variable symbols only
in macro definitions.

In High Level Assembler enhancements have been made to some system variable
symbols and many new system variable symbols have been introduced.

No new system variables are introduced in High Level Assembler Release 5.

No new system variables are introduced in High Level Assembler Release 4.

The system variable symbols introduced in High Level Assembler Release 3 are:
Variable Description
&SYSCLOCK A local-scope variable that holds the date and time
at which a macro is generated.
&SYSMAC A local-scope variable that can be subscripted, thus
referring to the name of any of the macros opened
between open code and the current nesting level.
&SYSOPT_XOBJECT A global-scope variable that indicates if the
XOBJECT assembly option was specified.
&SYSM_HSEV A global-scope variable that indicates the latest
MNOTE severity so far for the assembly.
&SYSM_SEV A global-scope variable that indicates the latest
MNOTE severity for the macro most recently called
from this level.

The system variable symbols introduced in High Level Assembler Release 2 are:
Variable Description
&SYSADATA_DSN A local-scope variable containing the name of the
data set where associated data (ADATA) records
are written.
&SYSADATA_MEMBER A local-scope variable containing the name of the
partitioned data set member where associated data
(ADATA) records are written.
&SYSADATA_VOLUME A local-scope variable containing the volume
identifier of the first volume containing the
ADATA data set.
&SYSLIN_DSN A local-scope variable containing the name of the
data set where object module records are written.

© Copyright IBM Corp. 1981, 2008 79

System variable symbols

&SYSLIN_MEMBER A local-scope variable containing the name of the

partitioned data set member where object module
records are written.
&SYSLIN_VOLUME A local-scope variable containing the volume
identifier of the first volume containing the object
module data set.
&SYSPRINT_DSN A local-scope variable containing the name of the
data set where listing records are written.
&SYSPRINT_MEMBER A local-scope variable containing the name of the
partitioned data set member where listing records
are written.
&SYSPRINT_VOLUME A local-scope variable containing the volume
identifier of the first volume containing the listing
data set.
&SYSPUNCH_DSN A local-scope variable containing the name of the
data set where object module records are written.
&SYSPUNCH_MEMBER A local-scope variable containing the name of the
partitioned data set member where object module
records are written.
&SYSPUNCH_VOLUME A local-scope variable containing the volume
identifier of the first volume containing the object
module data set.
&SYSTERM_DSN A local-scope variable containing the name of the
data set where terminal messages are written.
&SYSTERM_MEMBER A local-scope variable containing the name of the
partitioned data set member where terminal
messages are written.
&SYSTERM_VOLUME A local-scope variable containing the volume
identifier of the first volume containing the
terminal messages data set.

System variable symbols introduced in High Level Assembler Release 1 are:

Variable Description
&SYSASM A global-scope variable containing the name of the
assembler product being used.
&SYSDATC A global-scope variable containing the date, with
the century designation included, in the form
YYYYMMDD.
&SYSIN_DSN A local-scope variable containing the name of the
input data set.
&SYSIN_MEMBER A local-scope variable containing the name of the
current member in the input data set.
&SYSIN_VOLUME A local-scope variable containing the volume
identifier of the first volume containing the input
data set.
&SYSJOB A global-scope variable containing the job name of
the assembly job, if available, or '(NOJOB)'.

80 HLASM: V1R6 General Information

 System variable symbols

&SYSLIB_DSN A local-scope variable containing the name of the

library data set from which the current macro was
retrieved.
&SYSLIB_MEMBER A local-scope variable containing the name of the
current macro retrieved from the library data set.
&SYSLIB_VOLUME A local-scope variable containing the volume
identifier of the first volume containing the library
data set from which the current macro was
retrieved.
&SYSNEST A local-scope variable containing the current macro
nesting level. &SYSNEST is set to 1 for a macro
called from open code.
&SYSOPT_DBCS A global-scope Boolean variable containing the
value 1 if the DBCS assembler option was
specified, or 0 if NODBCS was specified.
&SYSOPT_OPTABLE A global-scope variable containing the name of the
operation code table specified in the OPTABLE
assembler option.
&SYSOPT_RENT A global-scope Boolean variable containing the
value 1 if the RENT assembler option was
specified, or 0 if NORENT was specified.
&SYSSEQF A local-scope variable containing the
identification-sequence field information of the
macro instruction in open code that caused,
directly or indirectly, the macro to be called.
&SYSSTEP A global-scope variable containing the step-name,
if available, or '(NOSTEP)'.
&SYSSTMT A global-scope variable that contains the statement
number of the next statement to be generated.
&SYSSTYP A local-scope variable containing the current
control section type (CSECT, DSECT, RSECT or
COM) at the time the macro is called.
&SYSTEM_ID A global-scope variable containing the name and
release level of the operating system under which
the assembly is run.
&SYSVER A global-scope variable containing the maintenance
version, release, and modification level of the
assembler.

In addition, High Level Assembler provides the following system variable symbols
not provided by DOS/VSE Assembler but provided by Assembler H Version 2:
Variable Description
&SYSDATE A global-scope variable containing the date in the
form MM/DD/YY.
&SYSLOC A local-scope variable containing the name of the
location counter now in effect. &SYSLOC can only
be used in macro definitions.
&SYSNDX A local-scope variable containing a number from 1

Appendix B. System variable symbols 81

System variable symbols

to 9999999. Each time a macro definition is called,

the number in &SYSNDX increases by 1.
&SYSTIME A global-scope variable containing the time the
assembly started, in the form HH.MM.

82 HLASM: V1R6 General Information

Appendix C. Hardware and software requirements
This appendix describes the environments in which High Level Assembler runs.

Hardware requirements
High Level Assembler, and its generated object programs, can run in any IBM
ES/9000®, 937X, or zSeries processor supported by the operating systems listed
below under Software requirements. However, you can only run a generated object
program that uses 370-XA machine instructions on a 370-XA mode processor under
an operating system that provides the necessary architecture support for the
370-XA instructions used. Similarly, you can only run a generated object program
that uses ESA/370, ESA/390, or zSeries machine instructions on an associated
processor under an operating system that provides the necessary architecture
support for the ESA/370, ESA/390, and zSeries instructions used.

Software requirements
High Level Assembler runs under the operating systems listed below. Unless
otherwise stated, the assembler also operates under subsequent versions, releases,
and modification levels of these systems:
v OS/390® Version 2 Release 10.0
v VM/ESA® Version 3 Release 1.0
v z/VM Version 5 Release 2
v VSE/ESA Version 2 Release 6
v z/VSE Version 3 Release 1 andVersion 4
v z/OS Version 1 Release 2.0
In addition, installation of High Level Assembler requires one of the following:
z/OS IBM System Modification Program/Extended (SMP/E). All load modules
are reentrant, and you can place them in the link pack area (LPA).
z/VM IBM VM Serviceability Enhancements Staged/Extended (VMSES/E) and
VMFPLC2. Most load modules are reentrant, and you can place them in a
logical saved segment.
z/VSE Maintain System History Program (MSHP). Most phases are reentrant, and
you can place them in the shared virtual area (SVA).

Assembling under z/OS

The minimum amount of virtual storage required by High Level Assembler is 610K
bytes. 410K bytes of storage are required for High Level Assembler load modules.
The rest of the storage allocated to the assembler is used for assembler working
storage.

At assembly time, and during subsequent link-editing, High Level Assembler

requires associated devices for the following types of input and output:
v Source program input
v Options file
v Printed listing
v Object module in relocatable card-image format, or the new object-file format
v Terminal output
v ADATA output
© Copyright IBM Corp. 1981, 2008 83
Assembling under z/OS

Table 6 shows the DDNAME and allowed device types associated with a particular
class of assembler input or output:
Table 6. Assembler input/output devices (z/OS)
Function DDNAME Device type When required
1
Input SYSIN DASD Always
Magnetic tape
Card reader
Macro library SYSLIB DASD When a library macro is
called or a COPY statement
used 1
Options file ASMAOPT DASD When assembler options are
to be provided via an
external file
Print SYSPRINT DASD When the LIST assembler
Magnetic tape option is specified 1
Printer
Output to linkage SYSLIN DASD When the OBJECT assembler
editor Magnetic tape option or the XOBJECT
assembler option is specified
1

Output to linkage SYSPUNCH DASD When the DECK assembler

editor (card deck) Magnetic tape option is specified 1
Card punch
Display SYSTERM DASD When the TERM assembler
Magnetic tape option is specified 1
Terminal
Printer
Assembler language SYSADATA DASD When the ADATA assembler
program data Magnetic tape option is specified 1
Note:
1. You can specify a user-supplied exit in place of this device. For more information about
the EXIT option, see Appendix A, “Assembler options,” on page 75.

Assembling under VM/CMS

High Level Assembler runs under the Conversational Monitor System (CMS)
component of z/VM, and, depending upon system requirements, requires a virtual
machine size of at least 1800K bytes.

A minimum of 610K bytes of storage is required by High Level Assembler. 410K

bytes of storage are required for High Level Assembler load modules. The rest of
the storage allocated to the assembler is used for assembler working storage.

At assembly time, and during subsequent object module processing, High Level
Assembler requires associated devices for the following types of input and output:
v Source program input
v Options file
v Printed listing
v Object module in relocatable card-image format
v Terminal output
v ADATA output

84 HLASM: V1R6 General Information

 Assembling under VM/CMS

Table 7 shows the characteristics of each device required at assembly time:

Table 7. Assembler input/output devices (CMS)
Function DDNAME Default file Device type When required
type
1
Input SYSIN ASSEMBLE DASD Always
Magnetic tape
Card reader
Macro library SYSLIB MACLIB DASD When a library macro is
called or a COPY
statement used 1
Options file ASMAOPT User DASD When assembler options
defined are to be provided via
an external file
Print SYSPRINT LISTING DASD When the LIST
Magnetic tape assembler option is
Printer specified
Object module SYSLIN TEXT DASD When the OBJECT
Magnetic tape assembler option is
Card punch specified 1
Text deck SYSPUNCH N/A DASD When the DECK
Magnetic tape assembler option is
Card punch specified 1
Display SYSTERM N/A DASD When the TERM
Magnetic tape assembler option is
Terminal specified 1
Printer
Assembler SYSADATA SYSADATA DASD When the ADATA
language program Magnetic tape assembler option is
data specified 1
Note:
1. You can specify a user-supplied exit in place of this device. For more information about
the EXIT option, see Appendix A, “Assembler options,” on page 75.

Assembling under VSE

The minimum amount of virtual storage required by High Level Assembler is 610K
bytes. 410K bytes of storage are required for High Level Assembler load modules.
The rest of the storage allocated to the assembler is used for assembler working
storage.

At assembly time, and during subsequent link-editing, High Level Assembler

requires appropriate devices for the following types of input and output:
v Source program input
v Macro library input
v Printed listing
v Object module in relocatable card-image format
v Terminal output
v ADATA output
Table 8 on page 86 shows the file name and allowed device types associated with a
particular class of assembler input or output:

Appendix C. Hardware and software requirements 85

Assembling under VSE

Table 8. Assembler input/output devices (VSE)

Function File name Device type When required
1
Input IJSYSIN DASD Always
(SYSIPT) Magnetic tape
Card reader
Macro Library LIBRARIAN DASD When a library macro is
sublibraries called, a COPY or an
assembler option member is
to be supplied
Print IJSYSLS DASD When the LIST assembler
(SYSLST) Magnetic tape option is specified 1
Printer
Output to linkage IJSYSLN DASD When the OBJECT assembler
editor (SYSLNK) Magnetic tape option is specified
Output to LIBR IJSYSPH DASD When the DECK assembler
utility (card deck) (SYSPCH) Magnetic tape option is specified 1
Card punch
Display SYSLOG Terminal When the TERM assembler
option is specified 1
Assembler language SYSADAT DASD When the ADATA assembler
program data (SYSnnn) Magnetic tape option is specified 1
Note:
1. You can specify a user-supplied exit in place of this device. For more information about
the EXIT option, see Appendix A, “Assembler options,” on page 75.

86 HLASM: V1R6 General Information

Notices
This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
Mail Station P300
2455 South Road
Poughkeepsie New York 12601-5400
U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law: INTERNATIONAL
BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION ″AS IS″
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR

© Copyright IBM Corp. 1981, 2008 87

Notices

PURPOSE. Some states do not allow disclaimer of express or implied warranties in

certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

If you are viewing this information softcopy, the photographs and color
illustrations may not appear.

Trademarks
The following are trademarks of International Business Machines Corporation in
the United States, or other countries, or both:

IBM
The IBM Logo
ibm.com
DFSMS
DFSMS/MVS
DFSMSdfp
ES/9000
Enterprise Systems Architecture/370
MVS
MVS/DFP
Multiprise
OS/390
REXX
S/390
System z
System/370
VM/ESA
VSE/ESA
z/Architecture
z/OS
z/VM
z/VSE
zSeries

Linux is a registered trademark of Linus Torvalds in the United States, other

countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other
countries.

88 HLASM: V1R6 General Information

Bibliography
z/OS MVS Programming: Authorized Assembler
High Level Assembler Services Reference, Volumes 1 - 4, SA22-7609 -
Publications SA22-7612
HLASM General Information, GC26-4943 z/OS MVS Program Management: User’s Guide
HLASM Installation and Customization Guide, and Reference, SA22-7643
SC26-3494 z/OS MVS System Codes, SA22-7626
HLASM Language Reference, SC26-4940 z/OS MVS System Commands, SA22-7627
HLASM Licensed Program Specifications, z/OS MVS System Messages, Volumes 1 - 10,
GC26-4944 SA22-7631 - SA22-7640
HLASM Programmer’s Guide, SC26-4941 z/OS Communications Server: SNA Programming,
SC31-8829
Toolkit Feature Publications OS/390:
OS/390 MVS System Messages, Volumes 1 - 5,
HLASM Toolkit Feature User’s Guide, GC26-8710
GC28-1784 - GC27-1788
HLASM Toolkit Feature Debug Reference
UNIX System Services:
Summary, GC26-8712
z/OS UNIX System Services User’s Guide,
HLASM Toolkit Feature Interactive Debug Facility
SA22-7801
User’s Guide, GC26-8709
DFSMS/MVS™:
HLASM Toolkit Feature Installation and
Customization Guide, GC26-8711 z/OS DFSMS Program Management, SC27-1130
z/OS DFSMSdfp Utilities, SC26-7414
Related Publications TSO/E (z/OS):
(Architecture) z/OS TSO/E Command Reference, SA22-7782
TSO/E (OS/390):
Enterprise Systems Architecture/390 Principles of
Operation, SA22-7201 OS/390 TSO/E Command Reference, SC28-1969
Enterprise Systems Architecture/370 Principles of SMP/E (z/OS):
Operation, SA22-7200 SMP/E Messages, Codes, and Diagnosis,
System/370 Principles of Operation, GA22-7000 GA22-7770
System/370 Extended Architecture Principles of SMP/E Reference, SA22-7772
Operation, SA22-7085 SMP/E User’s Guide, SA22-7773
z/Architecture Principles of Operation, SA22-7832 SMP/E (OS/390):
OS/390 SMP/E Messages and Codes, SC28-1738
Related Publications for z/OS OS/390 SMP/E Reference, SC28-1806
z/OS: OS/390 SMP/E User’s Guide, SC28-1740
z/OS MVS JCL Reference, SA22-7597
z/OS MVS JCL User’s Guide, SA22-7598 Related Publications for z/VM
z/OS MVS Programming: Assembler Services z/VM: VMSES/E Introduction and Reference,
Guide, SA22-7605 GC24-6130
z/OS MVS Programming: Assembler Services z/VM: Service Guide, GC24-6117
Reference, Volumes 1 and 2, SA22-7606, z/VM: CMS Commands and Utilities Reference,
SA22-7607 SC24-6073
z/OS MVS Programming: Authorized Assembler z/VM: CMS File Pool Planning, Administration,
Services Guide, SA22-7608 and Operation, SC24-6074

© Copyright IBM Corp. 1981, 2008 89

 z/VM: CP Planning and Administration,
SC24-6083
z/VM: Saved Segments Planning and
Administration, SC24-6116
z/VM: Other Components Messages and Codes,
GC24-6120
z/VM: CMS and REXX/VM Messages and Codes,
GC24-6118
z/VM: CP System Messages and Codes,
GC24-6119
z/VM: CMS Application Development Guide,
SC24-6070
z/VM: CMS Application Development Guide for
Assembler, SC24-6070
z/VM: CMS User’s Guide, SC24-6079
z/VM: XEDIT User’s Guide, SC24-6132
z/VM: XEDIT Commands and Macros Reference,
SC24-6132
z/VM: CP Commands and Utilities Reference,
SC24-6081

Related Publications for z/VSE

z/VSE: Guide to System Functions, SC33-8233
z/VSE: Administration, SC33-8224
z/VSE: Installation, SC33-8222
z/VSE: Planning, SC33-8221
z/VSE: System Control Statements, SC33-8225
z/VSE: Messages and Codes, Vol.1, SC33-8226
z/VSE: Messages and Codes, Vol.2, SC33-8227
z/VSE: Messages and Codes, Vol.3, SC33-8228
REXX/VSE Reference, SC33-6642
REXX/VSE User’s Guide, SC33-6641

90 HLASM: V1R6 General Information

Index
Special characters assembler instructions (continued)
revised 6
assembler options (continued)
TRANSLATE 78
*PROCESS statements assembler language extensions 5 TRMEXIT 76
description 16 assembler options 75 TYPECHECK 78
new statement 5 *PROCESS statement 16 USING 57, 78
&SYSNDX, MHELP control on 66 ADATA 69, 84, 85, 86 WORKFILE 78
ALIGN 75 XOBJECT 11, 84
ASA 75 XREF 52, 78
Numerics BATCH 75 assembling under CMS 84
121-character format 46 changing with ACONTROL 5 assembling under VSE
133-character format 46 CODEPAGE 75 VSE requirements 85
31-bit addressing 73 COMPAT 34, 75 assembling under z/OS 83
improved performance 73 DBCS 75, 81 assembling under z/VM 84
LIST assembler option 77 DECK 37, 75, 84, 85, 86 assembly
source and object listing 46 DXREF 75 abnormal termination of 67
ERASE 75 processor time 60
ESD 76 start time 60
A EXIT 38, 60, 76
FLAG 10, 48, 60, 76
stop time 60
associated data file output 75, 76
abnormal termination of assembly 67 FOLD 51, 76 attribute references
absolute symbols, predefined 26 GOFF 5, 76 CNOP label, type attribute 32
ACONTROL instruction 5, 16 INEXIT 76 defined attribute (D') 32
ADATA INFO 76 forward 33
assembler option 69, 75 LANGUAGE 76 number attribute (N') for SET
file 69 LIBEXIT 76 symbols 33
instruction 5 LIBMAC 55, 63, 76 operation code attribute (O') 32
records written by the assembler 69 LINECOUNT 76 with literals 32
ADATA assembler option 84, 85, 86 LIST 46, 61, 77, 84, 85, 86 with SETC variables 31
ADATA file MACHINE 77
description of 69 MXREF 53, 54, 55, 77
additional assembler instructions 5
addressing extensions 14
NODBCS 81
NODXREF 56
B
ADEXIT, EXIT assembler suboption 76 BATCH assembler option 75
NOESD 46
AEJECT macro instruction 26 batch assembly, improving
NOGOFF 76
AGO instruction performance 74
NOMXREF 54, 55
alternate format 27 binary floating-point numbers
NORENT 81
computed 27 changes to DC instruction 6
NORLD 50
extended 27 blank lines 9
NOSEG 66
AIF instruction books, High Level Assembler vii
NOTHREAD 78
alternate format 27 built-in functions, macro 3, 27
NOUSING 57
extended 27 NOXREF 52
extended form 27 OBJECT 37, 77, 84, 85, 86
macro AIF dump 66 OBJEXIT 76 C
AINSERT 20 OPTABLE 77 C-type
AINSERT macro instruction 25 PCONTROL 47, 77 constant 8
ALIAS instruction 5 precedence of 16 self-defining term 8
ALIGN assembler option 75 PRINT 77 CATTR instruction 5
alternate format of continuation lines 9 PROFILE 77 CCW0 instruction 12
AMODE instruction 11 PRTEXIT 76 CD-ROM publications viii
AREAD RA2 77 CEJECT instruction 5
clock functions 25 RENT 77, 81 channel command words 12
macro instruction 24 RLD 77 character set 8, 9
punch capability 25 RXREF 53, 77 character variables used in arithmetic
statement operands 36 SECTALGN 77 expressions 29
arithmetic expressions, using SETC SEG 78 clock functions 25
variables 29 SIZE 73, 78 CMS
array processing with set symbols 29 SUPRWARN 60, 78 assembling under 84
ASA assembler option 75 SYSPARM 78 interface command 65
ASCII translation table 9 TERM 64, 66, 78, 84, 85, 86 use of saved segment by High Level
ASPACE macro instruction 26 TEST 78 Assembler 73
assembler instructions 8 THREAD 78 virtual storage requirements 84
additional 5

© Copyright IBM Corp. 1981, 2008 91

CNOP instruction 6 documentation, High Level extended object support (continued)
CNOP label, type attribute 32 Assembler vii THREAD assembler option 78
code and data areas 13 double-byte data extended source and object listing 77
CODEPAGE assembler option 75 C-type constant 8 extended symbol length 10
comment statements 9, 26 C-type self-defining term 8 external
COMPAT assembler option 34, 75 concatenation of 23 symbols, length of 10
COMPAT(SYSLIST) with multilevel continuation of 10, 23 external dummy sections 13
sublists 23 double-byte character set 8 external function calls, macro 25, 26
conditional assembly extensions G-type constant 8 external symbol dictionary (ESD)
alternate format 9 G-type self-defining term 8, 23, 29 listing 45
attribute reference in AREAD and REPRO 8 restrictions on 13
defined attribute (D') 32 in MNOTE, PUNCH and TITLE 8, external symbol dictionary listing 45
forward 33 23 external symbols, number of 13
number attribute (N') for SET macro language support 23
symbols 33 MNOTE operand 8
operation code attribute (O') 32
with SETC symbols 31
PUNCH operand 8
pure DBCS data 8, 23
F
factors improving performance 73
created SET symbols 28 SI/SO 8, 10, 23
finding error messages
extended AGO instruction 27 TITLE operand 8
TERM assembler option 61
extended AIF instruction 27 DROP instruction 6
FLAG assembler option 10, 48, 60, 76
extended continuation statements 27 DS instruction
FOLD assembler option 51, 76
extended GBLx instruction 27 changes to DS instruction 6
formatted dump, produced by abnormal
extended LCLx instruction 27 DSECT
termination 67
extended SETx instruction 27, 29 cross reference listing 55
forward attribute-reference scan 33
system variable symbols referenced in Q-type address
&SYSLIST with multilevel constant 13
sublists 22 dummy sections
&SYSNDX, MHELP control on 66 aligning with DXD 6 G
CONT, FLAG assembler option 10 DXD instruction 6 G-type
continuation DXD, referenced in Q-type address constant 8
error warning messages 10 constant 13 self-defining term 8, 23, 29
extended indicator for double-byte DXREF assembler option 75 General Information book vii
data 10, 23 general purpose register cross reference
extended line format 27 listing 52
lines with double-byte data 9
number of lines 9
E generated macro operation codes 22
generated statement
E-Decks, reading 39
control sections, read-only 12 attribute reference for 31
edited macros 39
COPY instruction 6 format of 62
editing inner macro definitions 22
created SET symbols 28 sequence field of 61
editing macro definitions 20
Customization book vii suppress alignment zeroes 62
EJECT instruction 60
with PRINT NOGEN 62
ENTRY instruction 11
global SET symbol
EQU instruction 6
D ERASE assembler option 75
declaration 28
suppression of dump (in MHELP
DBCS assembler option 75, 81 error messages
options) 66
DC instruction 6 in library macros 63
GOFF assembler option 5, 76
DECK assembler option 37, 75, 84, 85, in open code 60
86 in source macros 64
declaration of SET symbols ESD assembler option 76
dimensioned SET symbols 28 ESD symbols, number of 13 H
implicit declaration 28 EXIT hardcopy publications vi
multiple declaration 28 communicating 39 hardware requirements 83
deferred loading 5 disabling 39 High Level Assembler
defined attribute (D') 32 EXIT assembler option 38, 60, 76 highlights 3
dependent USING 15 EXITCTL instruction 5, 38 machine requirements 83
diagnostic facilities extended planning for 4
diagnostic cross reference and AGO instruction 27 publications vii
assembler summary listing 57 AIF instruction 27 required operating environments 83
error messages for library macros 63 continuation indicator 10, 23 use of CMS saved segment 73
error messages for source macros 64 SETx instruction 27, 29 use of VSE shared virtual area
internal trace 67 extended addressing support 11 (SVA) 73
messages in open code 60 extended continuation statements 27 use of z/OS link pack area (LPA) 73
source record information 60 extended object support High Level Assembler option
using FLAG(RECORD) assembler CODEPAGE assembler option 75 summary 42
option 60 GOFF assembler option 76
dimension of SET symbol, maximum 28 instructions 11
documentation NOGOFF assembler option 76
High Level Assembler 89 NOTHREAD assembler option 78

92 HLASM: V1R6 General Information

I M mixed-case input, changes to 9
mnemonic operation codes used as macro
I/O Exit Usage Statistics MACHINE assembler option 77 operation codes 26
in the listing 59 machine instructions, publications 89 MNOTE operand, double-byte character
I/O exits machine requirements 83 set 8
description 37 macro model statements 61
usage statistics 38 AIF dump 66 multilevel sublists 22
implicit declaration of SET symbols 28 assembly diagnostic messages 63 multiple assembly 74
INEXIT assembler option 76 branch trace 66 multiple declaration of SET symbols 28
INFO assembler option 76 built-in functions 27 multiple location counters 13
inner macro definitions 21 call trace 66 MXREF assembler option 53, 54, 55, 77
input/output capability of macros 25 calls by substitution 22
input/output enhancements 37, 65 comment statements 9, 26
installation and customization entry dump 66
book information vii exit dump 66 N
internal macro comment statements 9, general advantages 19 nesting macro definitions 21
26 hex dump 66 NODBCS assembler option 81
ISEQ instruction 7 input/output capability of 25 NODXREF assembler option 56
suppressing dumps 66 NOESD assembler option 46
use of 20 NOGOFF assembler option 76
L macro and copy code
cross reference listing 54
NOMXREF assembler option 54, 55
NORENT assembler option 81
labeled USING 14 NORLD assembler option 50
source summary listing 53
LANGUAGE assembler option 76 NOSEG assembler option 66
macro definition 19
language compatibility 3 NOTHREAD assembler option 78
bypassing 20
Language Reference vii NOUSING assembler option 57
editing 20
LCLx and GBLx Instructions 26 NOXREF assembler option 52
inner macro definitions 21
LIBEXIT assembler option 76 number attribute (N') for SET
instructions allowed in 26
LIBMAC assembler option 55, 63, 76 symbols 33
listing control 26
library macro, error messages for 63
nesting 21
license inquiry 87
placement 19
Licensed Program Specifications vii
LINECOUNT assembler option 76
redefinition of 20 O
macro editing OBJECT assembler option 37, 77, 84, 85,
link pack area (LPA) 73
for inner macro definitions 21 86
LIST assembler option 46, 61, 77, 84, 85,
improving performance 74 object module output 76
86
in general 20 object modules, extended format 11
listing
macro input/output capability 25 OBJEXIT assembler option 76
*PROCESS statements 42
macro instruction 19 online publications viii
121-character format 46
name entries 23 operating systems for High Level
133-character format 46
nested 21 Assembler 83
diagnostic cross reference and
macro instruction operation code, operation code attribute (O') 32
assembler summary 57
generated 22 operation codes, redefining conditional
DSECT cross reference 55
macro language extensions assembly
external symbol dictionary 45
declaration of SET symbols 28 See instruction sets
general purpose register cross
instructions permitted in body of OPSYN instruction
reference 52
macro definition 26 operation codes 7
macro and copy code cross
mnemonic operation codes redefined placement 7
reference 54
as macros 26 to redefine conditional assembly
macro and copy code source
nesting definitions 21 instructions 33
summary 53
overview 20 to rename macro 20
option summary 42
placement of definitions 19 OPTABLE assembler option 77
ordinary symbol and literal cross
redefinition of macros 20 option
reference 50
sequence symbol length 10 MHELP 66
page-break improvements 60
source stream language input, summary listing 42
relocation dictionary 49
AREAD 24 option summary listing 42
source and object 46, 47
substitution, macro calls by 22 ordinary symbol and literal cross
source and object, 121-character
variable symbol length 10 reference listing 50
format 47
macro language overview 19 ORG instruction 7
source and object, 133-character
macro name, length of 26 organization of this manual v
format 48
macro prototype 19
unreferenced symbols defined in
macro-generated statements 61
CSECTs 52
macro-generated text
USING map 56
format of 62 P
literals, removal of restrictions 11 page-break improvements 60
sequence field of 61
local SET symbol parentheses 11
with PRINT NOGEN 62
declaration 28 PCONTROL assembler option 47, 77
manuals, High Level Assembler vii
location counters, multiple 13 performance
MHELP instruction 66
LOCTR instruction 13 improvement factors 73
migration considerations 3

Index 93
PESTOP assembler option 77 sectioning and linking extensions symbolic parameter
planning for High Level Assembler 4 external dummy sections 13 conflicting with created SET
POP instruction 7 multiple location counters 13 symbol 29
precedence of options 16 no restrictions on ESD items 13 syntax extensions
PRINT assembler option 77 read-only control sections 12 blank lines 9
PRINT instruction 7 SEG assembler option 78 character variables in arithmetic
printer control characters 75 sequence field in macro-generated expressions 29
process (*PROCESS) statements 16 statements 61 continuation lines, number of 9
processor time sequence symbol length 10, 26 levels of parentheses
in assembly listing 60 SET symbol in macro instruction 22
reduced instruction path 74 built-in macro functions 27 in ordinary assembler
processor time for the assembly 60 created 28 expressions 11
PROFILE assembler option 77 declaration number of terms in expression 11
Programmer’s Guide vii implicit 28 removal of restrictions for literals 11
prototype, in macro definitions 19 multiple 28 symbol length 10
PRTEXIT assembler option 76 defined as an array of values 28 SYSLIST (&SYSLIST) with multilevel
PSECT 13 dimension 28 sublists 23
publications global scope 28 SYSNDX (&SYSNDX), MHELP control
High Level Assembler vii, 89 local scope 28 on 66
HLASM Toolkit 89 SET symbol format and definition SYSPARM assembler option 78
machine instructions 89 changes 28 system determined blocksize 65
online (CD-ROM) viii SETAF instruction 27 system variable symbols 34, 79
z/OS 89 SETC symbol &SYSLIST with multilevel sublists 23
z/VM 89 attribute reference with 31 &SYSNDX, MHELP control on 66
z/VSE 90 in arithmetic expressions 29 system-determined blocksize 65
PUNCH operand, double-byte character SETCF instruction 27 SYSTERM output 64
set 8 SETx instruction
PUNCH output capability 25 built-in macro functions 27
PUSH instruction 8 extended 27, 29
using ordinary symbols 30
T
TERM assembler option 64, 66, 78, 84,
shared virtual area (SVA) 73
85, 86
R shared virtual storage 73
shift-in (SI) character (DBCS) 8
terminal output 64, 76
RA2 assembler option 77 terms, number of, in expressions 11
shift-out (SO) character (DBCS) 8
read-only control sections 12 TEST assembler option 78
SI (shift-in) character (DBCS) 8
reading edited macros 39 THREAD assembler option 78
SIZE assembler option 73, 78
record numbers 60 time of assembly 36
SO (shift-out) character (DBCS) 8
redefining conditional assembly TITLE instruction 60
softcopy publications viii
instructions 33 TITLE operand, double-byte character
software requirements 83
redefining macro names 20 set 8
source and object listing
redefining standard operation codes as Toolkit Customization book vii
121-character format 47
macro names 26 Toolkit installation and customization
133-character format 48
Release 6, what’s new 1 book information vii
description 46
relocatable address constants, 2-byte 8 TRANSLATE assembler option 78
source macro, error messages for 64
relocation dictionary listing 49 translation table 9
source stream input (AREAD) 24
RENT assembler option 77, 81 TRMEXIT assembler option 76
source stream insertion (AINSERT) 25
requirements type attribute of a CNOP label 32
SPACE instruction 60
hardware 83 TYPECHECK assembler option 78
start time of assembly 60
software 83
statistics
storage 85
I/O exit usage 38
resident macro definition text 73
resident source text 73
in the listing 60 U
stop time of assembly 60 underscore, in symbol names 11
resident tables 73
sublists, multilevel 22 Unicode support 9
revised assembler instructions 6
substitution in macro instruction unreferenced symbols defined in
RLD assembler option 77
operation code 22 CSECTs 52
RMODE instruction 11
substring length value 30 USING assembler option 57, 78
RSECT instruction 5, 12
suppress USING instruction
RXREF assembler option 53, 77
alignment zeroes in generated dependent USING 15
text 62 example of map listing 56
dumping of global SET symbols (in labeled USING 14
S MHELP options) 66 using map listing 56
sample I/O exits 39 suppressed messages listing 60
sample interchange program using SUPRWARN assembler option 78
macros 25
saved segment in CMS 73
symbol and literal cross reference
listing 50
V
variable symbol length 10
SDB 65 symbol name definition 10, 11
virtual storage
SECTALGN assembler option 77
CMS requirements 84

94 HLASM: V1R6 General Information

virtual storage (continued)
performance improvements 73
VSE requirements 85
z/OS requirements 83

W
what’s new in High Level Assembler
release 6 1
WORKFILE assembler option 78

X
XATTR instruction 5
XOBJECT assembler option 11, 84
XREF assembler option 52, 78

Z
z/OS
assembling under 83
use of link pack area by High Level
Assembler 73
virtual storage requirements 83
z/OS publications 89
z/VM
assembling under CMS 84
CMS interface command 65
CMS saved segment 73
z/VM publications 89
z/VSE publications 90
zeroes, suppress alignment 62

Index 95
96 HLASM: V1R6 General Information
Readers’ Comments — We’d Like to Hear from You
High Level Assembler for z/OS & z/VM & z/VSE
General Information
Release 6

Publication No. GC26-4943-05

We appreciate your comments about this publication. Please comment on specific errors or omissions, accuracy,
organization, subject matter, or completeness of this book. The comments you send should pertain to only the
information in this manual or product and the way in which the information is presented.

For technical questions and information about products and prices, please contact your IBM branch office, your
IBM business partner, or your authorized remarketer.

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any
way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use
the personal information that you supply to contact you about the issues that you state on this form.

Comments:

Thank you for your support.

Send your comments to the address on the reverse side of this form.
If you would like a response from IBM, please fill in the following information:

Name Address

Company or Organization

Phone No. E-mail address

 ___________________________________________________________________________________________________
Readers’ Comments — We’d Like to Hear from You Cut or Fold
GC26-4943-05  Along Line

_ _ _ _ _ _ _Fold
_ _ _and
_ _ _Tape
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please
_ _ _ _ _do
_ _not
_ _ staple
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold
_ _ _and
_ _ Tape
______

NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES

BUSINESS REPLY MAIL

FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK

POSTAGE WILL BE PAID BY ADDRESSEE

IBM Corporation
Reader Comments
DTX/E269
555 Bailey Avenue
San Jose, CA
U.S.A. 95141-9989

_________________________________________________________________________________________
Fold and Tape Please do not staple Fold and Tape

Cut or Fold
GC26-4943-05 Along Line


Program Number: 5696-234

Printed in USA

GC26-4943-05