100% found this document useful (1 vote)

628 views

HLASM Language Reference

HLASM

Uploaded by

ArvindUpadhyay

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

100% found this document useful (1 vote)

628 views

HLASM Language Reference

HLASM

Uploaded by

ArvindUpadhyay

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 474

High Level Assembler for MVS & VM & VSE

IBM

Language Reference
Release 5

SC26-4940-04

High Level Assembler for MVS & VM & VSE

IBM

Language Reference
Release 5

SC26-4940-04

Note!
Before using this information and the product it supports, be sure to read the general information under
Notices on page 425.

Fifth Edition (June 2004)

This edition applies to IBM High Level Assembler for MVS & VM & VSE, Release 5, Program Number 5696-234 and to any
subsequent releases until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the
product.
Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the
address below.
A form for reader's comments is provided at the back of this publication. If the form has been removed, address your comments to:
IBM Corporation
J87/D325
555 Bailey Avenue
SAN JOSE, CA 95141-1003
United States of America
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes
appropriate without incurring any obligation to you.
Copyright International Business Machines Corporation 1982, 2004. All rights reserved.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents

About this Manual . . . . . . . . . . . . . . . . . . . . . . . . .

Who Should Use this Manual . . . . . . . . . . . . . . . . . . .
Programming Interface Information . . . . . . . . . . . . . . . .
Organization of this Manual . . . . . . . . . . . . . . . . . . . .
IBM High Level Assembler for MVS & VM & VSE Publications
Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Softcopy Publications . . . . . . . . . . . . . . . . . . . . . .
The High Level Assembler web site . . . . . . . . . . . . . .
Using LookAt to look up Message Explanations . . . . . . .
Related Publications . . . . . . . . . . . . . . . . . . . . . . . .
Syntax Notation . . . . . . . . . . . . . . . . . . . . . . . . . . .
Double-Byte Character Set Notation . . . . . . . . . . . . . . .
Summary of Changes

. . . . . . . . . .

x
x
. x
. xi
. xii
. xii
xiii
xiii
xiii
xiv
xiv
xvi

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xvii

Part 1. Assembler LanguageStructure and Concepts

|
|

. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .
. . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

Chapter 1. Introduction . . . . . . . . . . . .
Language Compatibility . . . . . . . . . . . . . .
Assembler Language . . . . . . . . . . . . . . .
Assembler Program . . . . . . . . . . . . . . . .
Relationship of Assembler to Operating System
Coding Made Easier . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

Chapter 2. Coding and Structure . . . . . .

Character Set . . . . . . . . . . . . . . . . . . .
Standard Character Set . . . . . . . . . . . .
Double-Byte Character Set . . . . . . . . . .
Translation Table . . . . . . . . . . . . . . . .
Assembler Language Coding Conventions . .
Field Boundaries . . . . . . . . . . . . . . . .
Continuation Lines . . . . . . . . . . . . . . .
Blank Lines . . . . . . . . . . . . . . . . . . .
Comment Statement Format . . . . . . . . .
Instruction Statement Format . . . . . . . . .
Assembler Language Structure . . . . . . . . .
Overview of Assembler Language Structure
Machine Instructions . . . . . . . . . . . . . .
Assembler Instructions . . . . . . . . . . . .
Conditional Assembly Instructions . . . . . .
Macro Instructions . . . . . . . . . . . . . . .
Terms, Literals, and Expressions . . . . . . . .
Terms . . . . . . . . . . . . . . . . . . . . . .
Literals . . . . . . . . . . . . . . . . . . . . . .
Expressions . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .

Chapter 3. Program Structures and Addressing

Object Program Structures . . . . . . . . . . . . . . .
Source Program Structures . . . . . . . . . . . . . .

Copyright IBM Corp. 1982, 2004

. . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . .

1
3
4
4
6
8
9
11
11
11
12
14
14
14
15
18
18
19
21
23
24
25
26
27
28
28
40
44
50
50
51

iii

Contents

Source Module . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sections, Elements, and Parts . . . . . . . . . . . . . . . . . . .
Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reference Control Sections . . . . . . . . . . . . . . . . . . . . .
Classes (MVS and CMS) . . . . . . . . . . . . . . . . . . . . . .
Parts (MVS and CMS) . . . . . . . . . . . . . . . . . . . . . . . .
Location Counter Setting . . . . . . . . . . . . . . . . . . . . . .
Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Addressing within Source Modules: Establishing Addressability
Base Register Instructions . . . . . . . . . . . . . . . . . . . . .
Qualified Addressing . . . . . . . . . . . . . . . . . . . . . . . . .
Dependent Addressing . . . . . . . . . . . . . . . . . . . . . . .
Relative Addressing . . . . . . . . . . . . . . . . . . . . . . . . .
Literal Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Establishing Residence and Addressing Mode . . . . . . . . . .
Symbolic Linkages . . . . . . . . . . . . . . . . . . . . . . . . . .
External Symbol Dictionary Entries . . . . . . . . . . . . . . . .
Summary of Source and Object Program Structures . . . . . .

|
|
|
|

Part 2. Machine and Assembler Instruction Statements

Chapter 5. Assembler Instruction Statements

64-bit Addressing Mode . . . . . . . . . . . . . .
*PROCESS Statement . . . . . . . . . . . . . . .
ACONTROL Instruction . . . . . . . . . . . . . . .
ADATA Instruction . . . . . . . . . . . . . . . . . .
AINSERT Instruction . . . . . . . . . . . . . . . .
ALIAS Instruction . . . . . . . . . . . . . . . . . .
AMODE Instruction . . . . . . . . . . . . . . . . .

HLASM V1R5 Language Reference

. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .

. . . . . . . . . . . . . . . . . .

Chapter 4. Machine Instruction Statements . . . . . . . . . .

. . . . . . . .

. . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .

52
52
53
56
59
61
61
63
64
66
66
67
67
68
68
68
72
73

75
78
78
79
79
79
80
80
83
83
84
85
86
87
90
91
91
91
93
94
95
95
97
97
100
101
102
103
107
108
109
110

Contents

CATTR Instruction (MVS and CMS) . . .

CCW and CCW0 Instructions . . . . . . .
CCW1 Instruction . . . . . . . . . . . . . .
CEJECT Instruction . . . . . . . . . . . . .
CNOP Instruction . . . . . . . . . . . . . .
COM Instruction . . . . . . . . . . . . . . .
COPY Instruction . . . . . . . . . . . . . .
CSECT Instruction . . . . . . . . . . . . .
CXD Instruction . . . . . . . . . . . . . . .
DC Instruction . . . . . . . . . . . . . . . .
Rules for DC Operand . . . . . . . . . .
General Information About Constants .
Padding and Truncation of Values . . .
Subfield 1: Duplication Factor . . . . .
Subfield 2: Type . . . . . . . . . . . . .
Subfield 3: Type Extension . . . . . . .
Subfield 4: Program type . . . . . . . .
Subfield 5: Modifier . . . . . . . . . . .
Subfield 6: Nominal Value . . . . . . .
DROP Instruction . . . . . . . . . . . . . .
DS Instruction . . . . . . . . . . . . . . . .
DSECT Instruction . . . . . . . . . . . . .
DXD Instruction . . . . . . . . . . . . . . .
EJECT Instruction . . . . . . . . . . . . . .
END Instruction . . . . . . . . . . . . . . .
ENTRY Instruction . . . . . . . . . . . . .
EQU Instruction . . . . . . . . . . . . . . .
Using Conditional Assembly Values . .
EXITCTL Instruction . . . . . . . . . . . . .
EXTRN Instruction . . . . . . . . . . . . .
ICTL Instruction . . . . . . . . . . . . . . .
ISEQ Instruction . . . . . . . . . . . . . . .
LOCTR Instruction . . . . . . . . . . . . .
LTORG Instruction . . . . . . . . . . . . .
Literal Pool . . . . . . . . . . . . . . . .
Addressing Considerations . . . . . . .
Duplicate Literals . . . . . . . . . . . . .
MNOTE Instruction . . . . . . . . . . . . .
OPSYN Instruction . . . . . . . . . . . . .
ORG Instruction . . . . . . . . . . . . . . .
POP Instruction . . . . . . . . . . . . . . .
PRINT Instruction . . . . . . . . . . . . . .
Process Statement . . . . . . . . . . . . .
PUNCH Instruction . . . . . . . . . . . . .
PUSH Instruction . . . . . . . . . . . . . .
REPRO Instruction . . . . . . . . . . . . .
RMODE Instruction . . . . . . . . . . . . .
RSECT Instruction . . . . . . . . . . . . .
SPACE Instruction . . . . . . . . . . . . .
START Instruction . . . . . . . . . . . . . .
TITLE Instruction . . . . . . . . . . . . . .
USING Instruction . . . . . . . . . . . . . .
How to Use the USING Instruction . .
Base Registers for Absolute Addresses

. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .

Contents

112
115
116
118
119
121
122
123
125
126
128
129
130
132
133
134
135
136
140
172
174
178
180
181
182
183
184
187
187
189
189
190
191
193
194
195
195
196
198
200
204
204
208
208
209
210
211
212
213
214
215
218
219
220

Contents

Ordinary USING Instruction . . . . . . . . . . . . . . . .

Labeled USING Instruction . . . . . . . . . . . . . . . .
Dependent USING Instruction . . . . . . . . . . . . . .
WXTRN Instruction . . . . . . . . . . . . . . . . . . . . . .
XATTR Instruction (MVS and CMS) . . . . . . . . . . . .
Association of Code and Data Areas (MVS and CMS)

Part 3. Macro Language

. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6. Introduction to Macro Language

Using Macros . . . . . . . . . . . . . . . . . . .
Macro Definition . . . . . . . . . . . . . . . . . .
Model Statements . . . . . . . . . . . . . . .
Processing Statements . . . . . . . . . . . .
Comment Statements . . . . . . . . . . . . .
Macro Instruction . . . . . . . . . . . . . . . . .
Source and Library Macro Definitions . . . . .
Macro Library . . . . . . . . . . . . . . . . . .
System Macro Instructions . . . . . . . . . .
Conditional Assembly Language . . . . . . . .

Chapter 7. How to Specify Macro Definitions .

Where to Define a Macro in a Source Module . .
Format of a Macro Definition . . . . . . . . . . . . .
Macro Definition Header and Trailer . . . . . . . .
MACRO Statement . . . . . . . . . . . . . . . . .
MEND Statement . . . . . . . . . . . . . . . . . .
Macro Instruction Prototype . . . . . . . . . . . . .
Body of a Macro Definition . . . . . . . . . . . . . .
Model Statements . . . . . . . . . . . . . . . . . . .
Variable Symbols as Points of Substitution . . .
Listing of Generated Fields . . . . . . . . . . . .
Rules for Concatenation . . . . . . . . . . . . . .
Rules for Model Statement Fields . . . . . . . .
Symbolic Parameters . . . . . . . . . . . . . . . . .
Positional Parameters . . . . . . . . . . . . . . .
Keyword Parameters . . . . . . . . . . . . . . .
Combining Positional and Keyword Parameters
Subscripted Symbolic Parameters . . . . . . . .
Processing Statements . . . . . . . . . . . . . . . .
Conditional Assembly Instructions . . . . . . . .
Inner Macro Instructions . . . . . . . . . . . . . .
Other Conditional Assembly Instructions . . . .
AEJECT Instruction . . . . . . . . . . . . . . . .
AINSERT Instruction . . . . . . . . . . . . . . . .
AREAD Instruction . . . . . . . . . . . . . . . . .
ASPACE Instruction . . . . . . . . . . . . . . . .
COPY Instruction . . . . . . . . . . . . . . . . . .
MEXIT Instruction . . . . . . . . . . . . . . . . .
Comment Statements . . . . . . . . . . . . . . . . .
Ordinary Comment Statements . . . . . . . . . .
Internal Macro Comment Statements . . . . . .
System Variable Symbols . . . . . . . . . . . . . .

. . . . . . . . . . . . .

HLASM V1R5 Language Reference

220
223
226
229
230
232

235
238
238
238
239
240
240
241
241
242
242
242
243
243
244
244
244
245
245
247
247
248
248
249
251
253
254
255
255
255
256
256
256
256
257
257
257
259
260
260
261
261
261
262

Contents

Scope and Variability of System Variable Symbols

&SYSADATA_DSN System Variable Symbol . . .
&SYSADATA_MEMBER System Variable Symbol
&SYSADATA_VOLUME System Variable Symbol .
&SYSASM System Variable Symbol . . . . . . . . .
&SYSCLOCK System Variable Symbol . . . . . . .
&SYSDATC System Variable Symbol . . . . . . . .
&SYSDATE System Variable Symbol . . . . . . . .
&SYSECT System Variable Symbol . . . . . . . . .
&SYSIN_DSN System Variable Symbol . . . . . . .
&SYSIN_MEMBER System Variable Symbol . . . .
&SYSIN_VOLUME System Variable Symbol . . . .
&SYSJOB System Variable Symbol . . . . . . . . .
&SYSLIB_DSN System Variable Symbol . . . . . .
&SYSLIB_MEMBER System Variable Symbol . . .
&SYSLIB_VOLUME System Variable Symbol . . .
&SYSLIN_DSN System Variable Symbol . . . . . .
&SYSLIN_MEMBER System Variable Symbol . . .
&SYSLIN_VOLUME System Variable Symbol . . .
&SYSLIST System Variable Symbol . . . . . . . . .
&SYSLOC System Variable Symbol . . . . . . . . .
&SYSMAC System Variable Symbol . . . . . . . .
&SYSM_HSEV System Variable Symbol . . . . . .
&SYSM_SEV System Variable Symbol . . . . . . .
&SYSNDX System Variable Symbol . . . . . . . . .
&SYSNEST System Variable Symbol . . . . . . . .
&SYSOPT_DBCS System Variable Symbol . . . .
&SYSOPT_OPTABLE System Variable Symbol . .
&SYSOPT_RENT System Variable Symbol . . . .
&SYSOPT_XOBJECT System Variable Symbol . .
&SYSPARM System Variable Symbol . . . . . . . .
&SYSPRINT_DSN System Variable Symbol . . . .
&SYSPRINT_MEMBER System Variable Symbol .
&SYSPRINT_VOLUME System Variable Symbol .
&SYSPUNCH_DSN System Variable Symbol . . .
&SYSPUNCH_MEMBER System Variable Symbol
&SYSPUNCH_VOLUME System Variable Symbol
&SYSSEQF System Variable Symbol . . . . . . . .
&SYSSTEP System Variable Symbol . . . . . . . .
&SYSSTMT System Variable Symbol . . . . . . . .
&SYSSTYP System Variable Symbol . . . . . . . .
&SYSTEM_ID System Variable Symbol . . . . . . .
&SYSTERM_DSN System Variable Symbol . . . .
&SYSTERM_MEMBER System Variable Symbol .
&SYSTERM_VOLUME System Variable Symbol .
&SYSTIME System Variable Symbol . . . . . . . .
&SYSVER System Variable Symbol . . . . . . . . .
Chapter 8. How to Write Macro Instructions
Macro Instruction Format . . . . . . . . . . . . .
Alternative Formats for a Macro Instruction .
Name Entry . . . . . . . . . . . . . . . . . . .
Operation Entry . . . . . . . . . . . . . . . . .
Operand Entry . . . . . . . . . . . . . . . . .

262
263
264
265
265
266
266
267
267
269
270
271
272
272
273
273
274
275
275
276
278
279
279
280
281
283
284
285
285
285
286
286
288
288
289
290
290
291
292
292
292
293
294
295
295
296
296

. . . . . . . . . . . . . . . . . . .

297
297
298
299
299
300

Contents

vii

. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .

Contents

Sublists in Operands . . . . . . . . . . . . . . .
Values in Operands . . . . . . . . . . . . . . . .
Omitted Operands . . . . . . . . . . . . . . .
Unquoted Operands . . . . . . . . . . . . . .
Special Characters . . . . . . . . . . . . . . .
Nesting Macro Instruction Definitions . . . . . .
Inner and Outer Macro Instructions . . . . . . .
Levels of Macro Call Nesting . . . . . . . . . .
General Rules and Restrictions . . . . . . .
Passing Values through Nesting Levels . . .
System Variable Symbols in Nested Macros

Chapter 9. How to Write Conditional Assembly Instructions

SET Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subscripted SET Symbols . . . . . . . . . . . . . . . . . . . .
Scope of SET Symbols . . . . . . . . . . . . . . . . . . . . . .
Scope of Symbolic Parameters . . . . . . . . . . . . . . . . . .
SET Symbol Specifications . . . . . . . . . . . . . . . . . . . .
Subscripted SET Symbol Specification . . . . . . . . . . . . .
Created SET Symbols . . . . . . . . . . . . . . . . . . . . . . .
Data Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Attributes of Symbols and Expressions . . . . . . . . . . . . .
Type Attribute (T') . . . . . . . . . . . . . . . . . . . . . . . . .
Length Attribute (L') . . . . . . . . . . . . . . . . . . . . . . . .
Scale Attribute (S') . . . . . . . . . . . . . . . . . . . . . . . .
Integer Attribute (I') . . . . . . . . . . . . . . . . . . . . . . . .
Count Attribute (K') . . . . . . . . . . . . . . . . . . . . . . . .
Number Attribute (N') . . . . . . . . . . . . . . . . . . . . . . .
Defined Attribute (D') . . . . . . . . . . . . . . . . . . . . . . .
Operation Code Attribute (O') . . . . . . . . . . . . . . . . . .
Sequence Symbols . . . . . . . . . . . . . . . . . . . . . . . . . .
Lookahead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Open Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conditional Assembly Instructions . . . . . . . . . . . . . . . . .
Declaring SET Symbols . . . . . . . . . . . . . . . . . . . . . . .
GBLA, GBLB, and GBLC Instructions . . . . . . . . . . . . . .
LCLA, LCLB, and LCLC Instructions . . . . . . . . . . . . . .
Assigning Values to SET Symbols . . . . . . . . . . . . . . . . .
SETA Instruction . . . . . . . . . . . . . . . . . . . . . . . . . .
SETB Instruction . . . . . . . . . . . . . . . . . . . . . . . . . .
SETC Instruction . . . . . . . . . . . . . . . . . . . . . . . . . .
Extended SET Statements . . . . . . . . . . . . . . . . . . . .
SETAF Instruction . . . . . . . . . . . . . . . . . . . . . . . . .
SETCF Instruction . . . . . . . . . . . . . . . . . . . . . . . . .
Branching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AIF Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . .
AGO Instruction . . . . . . . . . . . . . . . . . . . . . . . . . .
ACTR Instruction . . . . . . . . . . . . . . . . . . . . . . . . . .
ANOP Instruction . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 10. MHELP Instruction

Part 4. Appendixes
viii

. . . . . . . . .

318
319
319
319
319
320
322
323
324
326
328
332
333
334
335
336
337
337
339
340
342
343
343
344
345
347
347
362
369
387
388
389
390
390
392
394
395

. . . . . . . . . . . . . . . . . . . . . . . . . .

397

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

HLASM V1R5 Language Reference

304
307
307
308
308
311
312
312
313
314
316

401

Contents

Appendix A. Assembler Instructions

. . . . . . . . . . . . . . . . . . . . . . .

402

Appendix B. Summary of Constants

. . . . . . . . . . . . . . . . . . . . . . .

407

Appendix C. Macro and Conditional Assembly Language Summary

. . . .

409

. . . . . . . . . . . . . . .

421

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

425
425

Appendix D. Standard Character Set Code Table

Notices . .
Trademarks

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

427
427
427
427
427
428
428

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

429

Contents

Bibliography . . . . . . . . . . . .
High Level Assembler Publications
Toolkit Feature Publications . . . .
Related Publications (Architecture)
Related Publications for MVS . . .
Related Publications for VM . . . .
Related Publications for VSE . . .
Index

About this Manual

This manual describes the syntax of assembler language statements, and provides
information about writing source programs that are to be assembled by IBM High
Level Assembler for MVS & VM & VSE, Licensed Program 5696-234, hereafter
referred to as High Level Assembler, or simply the assembler. It is meant to be
used in conjunction with HLASM Programmer's Guide.
Detailed definitions of machine instructions are not included in this manual. See
Bibliography on page 427 for a list of manuals that provide this information.
Throughout this book, we use these indicators to identify platform-specific
information:
Prefix the text with platform-specific text (for example, Under CMS...)
Add parenthetical qualifications (for example, (CMS only))
Bracket the text with icons. The following are some of the icons that we use:
Informs you of information specific to MVS
Informs you of information specific to CMS
Informs you of information specific to VSE
|
|

MVS is used in this manual to refer to Multiple Virtual Storage/Enterprise Systems

Architecture (MVS/ESA), to OS/390, and to z/OS.

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

|
|

VSE is used in this manual to refer to Virtual Storage Extended/Enterprise Systems

Architecture (VSE/ESA), and z/VSE.

Who Should Use this Manual

HLASM Language Reference is for application programmers coding in the High
Level Assembler language. It is not intended to be used for tutorial purposes, but
is for reference only. If you are interested in learning more about assemblers, most
libraries have tutorial books on the subject. It assumes you are familiar with the
functional details of the Enterprise Systems Architecture, and the role of
machine-language instructions in program execution.

Programming Interface Information

This manual is intended to help the customer create application programs. This
manual documents General-Use Programming Interface and Associated Guidance
Information provided by IBM High Level Assembler for MVS & VM & VSE.
General-use programming interfaces allow the customer to write programs that
obtain the services of IBM High Level Assembler for MVS & VM & VSE.

Copyright IBM Corp. 1982, 2004

Organization of this Manual

This manual is organized as follows:
Part 1, Assembler LanguageStructure and Concepts
Chapter 1, Introduction, describes the assembler language and how the
assembler processes assembler language source statements. It also
describes the relationship between the assembler and the operating
system, and suggests ways to make the task of coding easier.
Chapter 2, Coding and Structure, describes the coding rules for and the
structure of the assembler language. It also describes the language
elements in a program.
Chapter 3, Program Structures and Addressing describes the concepts
of addressability and symbolic addressing. It also describes control
sections and the linkage between control sections.
Part 2, Machine and Assembler Instruction Statements
Chapter 4, Machine Instruction Statements, describes the machine
instruction types and their formats.
Chapter 5, Assembler Instruction Statements, describes the assembler
instructions in alphabetical order.
Part 3, Macro Language
Chapter 6, Introduction to Macro Language, describes the macro facility
concepts including macro definitions, macro instruction statements, source
and library macro definitions, and conditional assembly language.
Chapter 7, How to Specify Macro Definitions, describes the components
of a macro definition.
Chapter 8, How to Write Macro Instructions, describes how to call
macro definitions using macro instructions.
Chapter 9, How to Write Conditional Assembly Instructions, describes
the conditional assembly language including SET symbols, sequence
symbols, data attributes, branching, and the conditional assembly
instructions.
Chapter 10, MHELP Instruction, describes the MHELP instruction that
you can use to control a set of macro trace and dump facilities.
Appendixes
Appendix A, Assembler Instructions, summarizes the assembler
instructions and assembler statements, and the related name and operand
entries.
Appendix B, Summary of Constants, summarizes the types of constants
and related information.
Appendix C, Macro and Conditional Assembly Language Summary,
summarizes the macro language described in Part 3. This summary also
includes a summary table of the system variable symbols.
Appendix D, Standard Character Set Code Table, shows the code table
for the assembler's standard character set.

About this Manual

IBM High Level Assembler for MVS & VM & VSE Publications

IBM High Level Assembler for MVS & VM & VSE Publications
High Level Assembler runs under MVS, VM and VSE. Its publications for the MVS,
VM and VSE operating systems are described in this section.

Publications
The books in the High Level Assembler library are shown in Figure 1. This figure
shows which books can help you with specific tasks, such as application
programming.
Figure 1. IBM High Level Assembler for MVS & VM & VSE Publications
Task

Publication

Order Number

Evaluation and Planning

HLASM V1R5 General

Information

GC26-4943

Installation and
Customization

HLASM V1R5 Installation

and Customization Guide

SC26-3494

HLASM V1R5
Programmer's Guide

SC26-4941

HLASM V1R5 Toolkit

Feature Installation Guide

GC26-8711

HLASM V1R5
Programmer's Guide

SC26-4941

HLASM V1R5 Language

Reference

SC26-4940

HLASM V1R5 General

Information

GC26-4943

HLASM V1R5 Toolkit

Feature User's Guide

GC26-8710

HLASM V1R5 Toolkit

Feature Interactive Debug
Facility User's Guide

GC26-8709

Diagnosis

HLASM V1R5 Installation

and Customization Guide

SC26-3494

Warranty

HLASM V1R5 Licensed

Program Specifications

GC26-4944

Application
Programming

HLASM V1R5 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 V1R5 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.

xii

HLASM V1R5 Language Reference

IBM High Level Assembler for MVS & VM & VSE Publications

HLASM V1R5 Language Reference

Presents the rules for writing assembler language source programs to
be assembled using High Level Assembler.
HLASM V1R5 Licensed Program Specifications
Contains a product description and product warranty information for High
Level Assembler.
HLASM V1R5 Programmer's Guide
Describes how to assemble, debug, and run High Level Assembler
programs.
HLASM V1R5 Toolkit Feature Installation Guide
Contains the information you need to install and customize, and
diagnose failures in, the High Level Assembler Toolkit Feature.
HLASM V1R5 Toolkit Feature User's Guide
Describes how to use the High Level Assembler Toolkit Feature.
HLASM V1R5 Toolkit Feature Debug Reference Summary
Contains a reference summary of the High Level Assembler Interactive
Debug Facility.
HLASM V1R5 Toolkit Feature Interactive Debug Facility User's Guide
Describes how to use the High Level Assembler Interactive Debug
Facility.

Softcopy Publications
The High Level Assembler publications are available in the following softcopy
formats:

z/OS V1Rx Collection, SK3T-4269

z/OS V1Rx and Software Products DVD Collection, SK3T-4271
z/VM Collection, SK2T-2067
VSE Collection, SK2T-0060

The High Level Assembler web site

The High Level Assembler web site, at
|

http://www.ibm.com/software/awdtools/hlasm
provides access to all HLASM publications, in downloadable or directly viewable
PDF and BookMaster formats.
The web site also provides access to other information relevant to High Level
Assembler.

|
|
|
|
|
|
|
|

Using LookAt to look up Message Explanations

LookAt is an online facility that lets you look up explanations for most of the IBM
messages you encounter, as well as for some system abends and codes. Using
LookAt to find information is faster than a conventional search because in most
cases LookAt goes directly to the message explanation.
You can use LookAt from the following locations to find IBM message explanations
for z/OS elements and features, z/VM, VSE/ESA, and Clusters for AIX and
Linux:

About this Manual

xiii

|
|

The Internet. You can access IBM message explanations directly from the
LookAt Web site at http://www.ibm.com/eserver/zseries/zos/bkserv/lookat/

|
|
|
|

Your z/OS TSO/E host system. You can install code on your z/OS or z/OS.e
systems to access IBM message explanations, using LookAt from a TSO/E
command line (for example, TSO/E prompt, ISPF, or z/OS UNIX System
Services running OMVS).

|
|
|
|

Your Microsoft Windows workstation. You can install code to access IBM
message explanations on the z/OS Collection (SK3T-4269), using LookAt from
a Microsoft Windows command prompt (also known as the DOS command
line).

|
|
|
|
|

Your wireless handheld device. You can use the LookAt Mobile Edition with a
handheld device that has wireless access and an Internet browser (for
example, Internet Explorer for Pocket PCs, Blazer, or Eudora for Palm OS, or
Opera for Linux handheld devices). Link to the LookAt Mobile Edition from the
LookAt Web site.

|
|
|
|
|

You can obtain code to install LookAt on your host system or Microsoft Windows
workstation from a disk on your z/OS Collection (SK3T-4269), or from the LookAt
Web site (click Download, and select the platform, release, collection, and location
that suit your needs). More information is available in the LOOKAT.ME files
available during the download process.

Related Publications
See Bibliography on page 427 for a list of publications that supply information you
might need while you are using High Level Assembler.

Syntax Notation
Throughout this book, syntax descriptions use the structure defined below.
Read the syntax diagrams from left to right, from top to bottom, following the
path of the line.
The symbol indicates the beginning of a statement.
The symbol indicates that the statement syntax is continued on the next
line.
The symbol indicates that a statement is continued from the previous line.
The indicates the end of a statement.
Diagrams of syntactical units other than complete statements start with the
symbol and end with the symbol.
Keywords appear in uppercase letters (for example, ASPACE) or upper and
lower case (for example, PATHFile). They must be spelled exactly as shown.
Lower case letters are optional (for example, you could enter the PATHFile
keyword as PATHF, PATHFI, PATHFIL or PATHFILE).
Variables appear in all lowercase letters in a special typeface (for example,
integer). They represent user-supplied names or values.
If punctuation marks, parentheses, or such symbols are shown, they must be
entered as part of the syntax.

xiv

HLASM V1R5 Language Reference

Required items appear on the horizontal line (the main path).

INSTRUCTIONrequired item
Optional items appear below the main path. If the item is optional and is the
default, the item appears above the main path.
default item
INSTRUCTION
optional item
When you can choose from two or more items, they appear vertically in a
stack.
If you must choose one of the items, one item of the stack appears on the
main path.
INSTRUCTIONrequired choice1
required choice2
If choosing one of the items is optional, the whole stack appears below the
main path.
INSTRUCTION
optional choice1
optional choice2
An arrow returning to the left above the main line indicates an item that can be
repeated. When the repeat arrow contains a separator character, such as a
comma, you must separate items with the separator character.
,
repeatable item
INSTRUCTION
A repeat arrow above a stack indicates that you can make more than one
choice from the stacked items, or repeat a single choice.
The following example shows how the syntax is used.
Format
A

,
1
INSTRUCTION
optional item
1:
operand choice1
(1)
operand choice2

operand choice3
Note:
1 operand choice2 and operand choice3 must not be specified together

The item is optional, and can be coded or not.

The INSTRUCTION key word must be specified and coded as shown.

About this Manual

The item referred to by 1 is a required operand. Allowable choices for

this operand are given in the fragment of the syntax diagram shown
below 1 at the bottom of the diagram. The operand can also be
repeated. That is, more than one choice can be specified, with each
choice separated by a comma.

Double-Byte Character Set Notation

Double-byte character set (DBCS) characters in terms, expressions, character
strings, and comments are delimited by shift-out and shift-in characters. In this
manual, the shift-out delimiter is represented pictorially by the < character, and the
shift-in delimiter is represented pictorially by the > character. The EBCDIC codes
for the shift-out and shift-in delimiters are X'0E' and X'0F', respectively.
The following figure summarizes the DBCS notation used throughout this manual.
Character(s)

Represents

Shift-out (SO)

Shift-in (SI)

D1D2D3...

Double-byte characters

DaDbDc...

Double-byte characters

.A.B.C.'.&.,

EBCDIC characters in double-byte form: A, B, C, single quotation mark,

ampersand, and comma. The dots separating the letters represent the
hexadecimal value X'42'. A double-byte character that contains the
value of an EBCDIC ampersand or single quotation mark in either byte
is not recognized as a delimiter when enclosed by SO and SI.

eeeeeee

Single-byte (EBCDIC) characters

abcd...

Single-byte (EBCDIC) characters

XXX

Extended continuation indicator for macro-generated statements

+++

Alternative extended continuation indicator for macro-generated

statements

EBCDIC character containing all 0 bits.

EBCDIC character containing all 1 bits.

xvi

HLASM V1R5 Language Reference

Summary of Changes
Date of Publication June 2004
Form of Publication Fifth Edition, SC26-4940-04
Here is a list of the changes to HLASM that are explained in this document.
Extended support for machine instructions
When the GOFF option is in force, the RI machine instructions are able to
reference one or more external symbols (RI Format on page 91).
Support for 20-bit displacement instructions
Changed Assembler instructions
Quadword alignment
CA data type
CE data type
8-byte Q, R, J and V-cons
CNOP
DC/DS
EQU
ORG
Changed assembler statements
Support PART and PRIORITY attributes on the CATTR statement, for MVS and
CMS (CATTR Instruction (MVS and CMS) on page 112).
AMODE
ANY64 operand added (AMODE Instruction on page 110)
Unified Opcode table
A single opcode table is provided.
OPTABLE option
The OPTABLE option is permitted on the *PROCESS statement.
ADATA enhancements
The following enhancements are made to ADATA:
Revised layout of the ADATA records.
The ADATA Exit processing is changed such that it mirrors the processing of
other exits.
GOFF ESD and RLD information are provided.
The maximum record length is increased.

Copyright IBM Corp. 1982, 2004

xvii

Miscellany
The ASCII translation table is upgraded.
The Relocation Dictionary in the assembler listing is reformatted.
A Numeric assembler version identifier is introduced.
Additional diagnostic messages are provided.
Enhancements to the External function parameter list.
Enhancements to the Assembler summary listing.
A new exit call - REINIT.
Remove the internal dependency on the blocksize of SYSUT1.
New limit of 1K for SETC and parameter string lengths.
Enhancements to internal conditional assembly functions.

xviii

HLASM V1R5 Language Reference

Part 1. Assembler LanguageStructure and Concepts

Chapter 1. Introduction . . . . . . . . . . . . . . .
Language Compatibility . . . . . . . . . . . . . . . . .
Assembler Language . . . . . . . . . . . . . . . . . .
Machine Instructions . . . . . . . . . . . . . . .
Assembler Instructions . . . . . . . . . . . . . .
Macro Instructions . . . . . . . . . . . . . . . .
Assembler Program . . . . . . . . . . . . . . . . . . .
Basic Functions . . . . . . . . . . . . . . . . . .
Associated Data . . . . . . . . . . . . . . . . . .
Controlling the Assembly . . . . . . . . . . . . .
Processing Sequence . . . . . . . . . . . . . .
Relationship of Assembler to Operating System . .
Coding Made Easier . . . . . . . . . . . . . . . . . .
Symbolic Representation of Program Elements
Variety in Data Representation . . . . . . . . .
Controlling Address Assignment . . . . . . . .
Relocatability . . . . . . . . . . . . . . . . . . .
Sectioning a Program . . . . . . . . . . . . . .
Linkage between Source Modules . . . . . . .
Program Listings . . . . . . . . . . . . . . . . .
Multiple Source Modules . . . . . . . . . . . . .
Chapter 2. Coding and Structure . . . . . .
Character Set . . . . . . . . . . . . . . . . . . .
Standard Character Set . . . . . . . . . . . .
Double-Byte Character Set . . . . . . . . . .
Translation Table . . . . . . . . . . . . . . . .
Assembler Language Coding Conventions . .
Field Boundaries . . . . . . . . . . . . . . . .
Statement Field . . . . . . . . . . . . . . .
Continuation-Indicator Field . . . . . . . .
Identification-Sequence Field . . . . . . .
Continuation Lines . . . . . . . . . . . . . . .
Alternative Statement Format . . . . . . .
Continuation of double-byte data . . . . .
Blank Lines . . . . . . . . . . . . . . . . . . .
Comment Statement Format . . . . . . . . .
Instruction Statement Format . . . . . . . . .
Statement Coding Rules . . . . . . . . . .
Assembler Language Structure . . . . . . . . .
Overview of Assembler Language Structure
Machine Instructions . . . . . . . . . . . . . .
Assembler Instructions . . . . . . . . . . . .
Conditional Assembly Instructions . . . . . .
Macro Instructions . . . . . . . . . . . . . . .
Terms, Literals, and Expressions . . . . . . . .
Terms . . . . . . . . . . . . . . . . . . . . . .
Symbols . . . . . . . . . . . . . . . . . . .
Self-Defining Terms . . . . . . . . . . . . .
Location Counter . . . . . . . . . . . . . .
Copyright IBM Corp. 1982, 2004

3
4
4
5
5
5
6
6
6
6
7
8
9
9
9
9
9
9
10
10
10
11
11
11
12
14
14
14
14
15
15
15
16
16
18
18
19
19
21
23
24
25
26
27
28
28
29
34
36

Part 1. Assembler LanguageStructure and Concepts

Symbol Length Attribute Reference . . . . . .

Other Attribute References . . . . . . . . . .
Literals . . . . . . . . . . . . . . . . . . . . . . . .
Literals, Constants, and Self-Defining Terms
General Rules for Using Literals . . . . . . .
Literal Pool . . . . . . . . . . . . . . . . . . . .
Expressions . . . . . . . . . . . . . . . . . . . . .
Rules for Coding Expressions . . . . . . . . .
Evaluation of Expressions . . . . . . . . . . .
Absolute and Relocatable Expressions . . .
|
|

Chapter 3. Program Structures and Addressing . . . . . . . .

Object Program Structures . . . . . . . . . . . . . . . . . . . . . . .
Source Program Structures . . . . . . . . . . . . . . . . . . . . . .
Source Module . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Beginning of a Source Module . . . . . . . . . . . . . . . . .
End of a Source Module . . . . . . . . . . . . . . . . . . . . .
Sections, Elements, and Parts . . . . . . . . . . . . . . . . . . .
Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
First Section . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unnamed Section . . . . . . . . . . . . . . . . . . . . . . . . .
Reference Control Sections . . . . . . . . . . . . . . . . . . . . .
Dummy Control Sections . . . . . . . . . . . . . . . . . . . . .
Common Control Sections . . . . . . . . . . . . . . . . . . . .
External Dummy Sections . . . . . . . . . . . . . . . . . . . .
Classes (MVS and CMS) . . . . . . . . . . . . . . . . . . . . . .
Class Binding and Loading Attributes . . . . . . . . . . . . .
Default Class Assignments . . . . . . . . . . . . . . . . . . .
Parts (MVS and CMS) . . . . . . . . . . . . . . . . . . . . . . . .
Location Counter Setting . . . . . . . . . . . . . . . . . . . . . .
Location Counter and Length Limits . . . . . . . . . . . . . .
Use of Multiple Location Counters . . . . . . . . . . . . . . .
Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Addressing within Source Modules: Establishing Addressability
How to Establish Addressability . . . . . . . . . . . . . . . . .
Base Register Instructions . . . . . . . . . . . . . . . . . . . . .
Qualified Addressing . . . . . . . . . . . . . . . . . . . . . . . . .
Dependent Addressing . . . . . . . . . . . . . . . . . . . . . . .
Relative Addressing . . . . . . . . . . . . . . . . . . . . . . . . .
Literal Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Establishing Residence and Addressing Mode . . . . . . . . . .
Symbolic Linkages . . . . . . . . . . . . . . . . . . . . . . . . . .
Establishing symbolic linkage . . . . . . . . . . . . . . . . . .
Referring to external data . . . . . . . . . . . . . . . . . . . .
Branching to an external address . . . . . . . . . . . . . . . .
Establishing an external symbol alias . . . . . . . . . . . . .
External Symbol Dictionary Entries . . . . . . . . . . . . . . . .
Summary of Source and Object Program Structures . . . . . .

|
|

|
|
|
|

HLASM V1R5 Language Reference

38
40
40
41
42
44
44
45
46
47
50
50
51
52
52
52
52
53
54
55
56
56
57
57
59
60
60
61
61
62
63
63
64
64
66
66
67
67
68
68
68
69
69
69
71
72
73

Introduction

Chapter 1. Introduction
A computer can understand and interpret only machine language. Machine
language is in binary form and, thus, very difficult to write. The assembler
language is a symbolic programming language that you can use to code
instructions instead of coding in machine language.
Because the assembler language lets you use meaningful symbols made up of
alphabetic and numeric characters, instead of just the binary digits 0 and 1 used in
machine language, you can make your coding easier to read, understand, and
change. The assembler must translate the symbolic assembler language into
machine language before the computer can run your program. The specific
procedures followed to do this may vary according to the system you are using.
However, the method is basically the same for all systems:

Your assembler

language source

statements

HIGH LEVEL ASSEMBLER

Messages

Machine language

and

version of your
listings
program

LINKER

Executable module

Figure 2. Assembling and Link-Editing Your Assembler Language Program

Your program, written in the assembler language, becomes the source module that
is input to the assembler. The assembler processes your source module and
produces an object module in machine language (called object code). The object
module can be used as input to be processed by the linker or the binder. The
linker or binder produces a load module (MVS and CMS), or a phase (VSE), that
can be loaded later into the main storage of the computer. When your program is
loaded, it can then be run. Your source module and the object code produced are
printed, along with other information, on a program listing.

Copyright IBM Corp. 1982, 2004

Language Compatibility

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 Assembler H Version 2. Similarly, 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 High Level Assembler symbolic
operation codes
SET symbols with names that conflict with the names of High Level Assembler
system variable symbols
Dependencies on the type attribute values of certain variable symbols or macro
instruction operands
With the exception of these possible conflicts, and with the appropriate High Level
Assembler option values, source 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.
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, and High Level Assembler requires that library macros be
stored in source statement format. A library input exit can be used to analyze a
macro definition, and, in the case of an E-Deck, call the VSE/ESA ESERV program
to change, the E-Deck definition, line by line, back into source format required by
the assembler, without modifying the original library file.
See the section titled Using the High Level Assembler Library Exit for Processing
E-Decks in the IBM VSE/ESA Guide to System Functions manual. This section
describes how to set up the exit and how to use it.

Assembler Language
The assembler language is the symbolic programming language that lies closest to
the machine language in form and content. You will, therefore, find the assembler
language useful when:
You need to control your program closely, down to the byte and even the bit
level.
You must write subroutines for functions that are not provided by other
symbolic programming languages, such as COBOL, FORTRAN, or PL/I.
The assembler language is made up of statements that represent either instructions
or comments. The instruction statements are the working part of the language and
are divided into the following three groups:
Machine instructions
Assembler instructions

HLASM V1R5 Language Reference

Assembler Language

Macro instructions

Machine Instructions
A machine instruction is the symbolic representation of a machine language
instruction of the following instruction sets:

IBM System/370
IBM System/370 Extended Architecture (370-XA)
Enterprise Systems Architecture/370 (ESA/370)
Enterprise Systems Architecture/390 (ESA/390)
z/Architecture

It is called a machine instruction because the assembler translates it into the

machine language code that the computer can run. Machine instructions are
described in Chapter 4, Machine Instruction Statements.

Assembler Instructions
An assembler instruction is a request to the assembler to do certain operations
during the assembly of a source module; for example, defining data constants,
reserving storage areas, and defining the end of the source module. Except for the
instructions that define constants, and the instruction used to generate no-operation
instructions for alignment, the assembler does not translate assembler instructions
into object code. The assembler instructions are described in Chapter 3, Program
Structures and Addressing, Chapter 5, Assembler Instruction Statements, and
Chapter 9, How to Write Conditional Assembly Instructions.

Macro Instructions
A macro instruction is a request to the assembler program to process a predefined
sequence of instructions called a macro definition. From this definition, the
assembler generates machine and assembler instructions, which it then processes
as if they were part of the original input in the source module.
IBM supplies macro definitions for input/output, data management, and supervisor
operations that you can call for processing by coding the required macro
instruction. (These IBM-supplied macro instructions are described in the applicable
Macro Instructions manual.)
You can also prepare your own macro definitions, and call them by coding the
corresponding macro instructions. Rather than code all of this sequence each time
it is needed, you can create a macro instruction to represent the sequence and
then, each time the sequence is needed, simply code the macro instruction
statement. During assembly, the sequence of instructions represented by the
macro instruction is inserted into the source program.
A complete description of the macro facility, including the macro definition, the
macro instruction, and the conditional assembly language, is given in Part 3,
Macro Language.

Chapter 1. Introduction

Assembler Program

Assembler Program
The assembler program, also referred to as the assembler, processes the machine,
assembler, and macro instructions you have coded (source statements) in the
assembler language, and produces an object module in machine language.

Basic Functions
Processing involves the translation of source statements into machine language,
assignment of storage locations to instructions and other elements of the program,
and performance of auxiliary assembler functions you have designated. The output
of the assembler program is the object program, a machine language translation of
the source program. The assembler produces a printed listing of the source
statements and object program statements and additional information, such as error
messages, that are useful in analyzing the program. The object program is in the
format required by the linker.

Associated Data
The assembler can produce an associated data file that contains information about
the source program and the assembly environment. The ADATA information
includes information such as:

Data sets used by the assembler

Program source statements
Macros used by the assembler
Program symbols
Program object code
Assembly error messages

Different subsets of this information are needed by various consumers, such as

configuration managers, debuggers, librarians, metrics collectors, and many more.

Controlling the Assembly

You can control the way the assembler produces the output from an assembly,
using assembler options and assembler language instructions.
Assembler options are described in the HLASM Programmer's Guide. A subset of
assembler options can be specified in your source program using the *PROCESS
statement described on page 102.
Assembler language instructions are assembler language source statements that
cause the assembler to perform a specific operation. Some assembler language
instructions, such as the DC instruction, generate object code. Assembler
language instructions are categorized as follows:
Assembler Instructions
These include instructions for:

HLASM V1R5 Language Reference

Producing associated data

Assigning base registers
Defining data constants
Controlling listing output
Redefining operation codes
Sectioning and linking programs
Defining symbols

Assembler Program

These instructions are described in Chapter 5, Assembler Instruction

Statements.
Macro Instructions
These instructions let you define macros for generating a sequence of
assembler language statements from a single instruction. These
instructions are described in Part 3, Macro Language.
Conditional Assembly Instructions
These instructions let you perform general arithmetic and logical
computations, and condition tests that can vary the output generated by
the assembler. These instructions are described under Conditional
Assembly Instructions on page 343.

Processing Sequence
The assembler processes the machine and assembler language instructions at
different times during its processing sequence. You should be aware of the
assembler's processing sequence in order to code your program correctly.
The assembler processes most instructions twice, first during conditional assembly
and, later, at assembly time. However, as shown below, it does some processing
only during conditional assembly.
Conditional Assembly and Macro Instructions: The assembler processes
conditional assembly instructions and macro processing instructions during
conditional assembly. During this processing the assembler evaluates arithmetic,
logical, and character conditional assembly expressions. Conditional assembly
takes place before assembly time.
The assembler processes the machine and ordinary assembler instructions
generated from a macro definition called by a macro instruction at assembly time.
Machine Instructions: The assembler processes all machine instructions, and
translates them into object code at assembly time.
Assembler Instructions: The assembler processes ordinary assembler
instructions at assembly time. During this processing:
The assembler evaluates absolute and relocatable expressions (sometimes
called assembly-time expressions)
Some instructions, such as ADATA, ALIAS, CATTR and XATTR (MVS and
CMS), DC, DS, ENTRY, EXTRN, PUNCH, and REPRO, produce output for
later processing by programs such as the linker.
The assembler prints in a program listing all the information it produces at the
various processing times discussed above. The assembler also produces
information for other processors. The linker uses such information at link-edit time
to combine object modules into load modules. At program fetch time, the load
module produced by the linker is loaded into virtual storage. Finally, at execution
time, the computer runs the load module.

Chapter 1. Introduction

Relationship of Assembler to Operating System

High Level Assembler operates under the OS/390 operating system, the MVS/ESA
operating system, the CMS component of the VM/ESA operating system, and the
VSE/ESA operating system. These operating systems provide the assembler
with services for:
Assembling a source module
Running the assembled object module as a program
In writing a source module, you must include instructions that request any required
service functions from the operating system.
MVS: MVS provides the following services:
For assembling the source module:

A control program
Sequential data sets to contain source code
Libraries to contain source code and macro definitions
Utilities

For preparing for the execution of the assembler program as represented by

the object module:

A control program
Storage allocation
Input and output facilities
Linker or binder
Loader

CMS: CMS provides the following services:

For assembling the source module:

An interactive control program

Files to contain source code
Libraries to contain source code and macro definitions
Utilities

For preparing for the execution of the assembler program as represented by

the object modules:

An interactive control program

Storage allocation
Input and output facilities
Linker
A loader

VSE: VSE provides the following services:

For assembling the source module:

A control program
Sequential data sets to contain source code
Libraries to contain source code and macro definitions
Utilities

For preparing for the execution of the assembler program as represented by

the object module:

HLASM V1R5 Language Reference

Coding Made Easier

A control program
Storage allocation
Input and output facilities
Linker

Coding Made Easier

It can be very difficult to write an assembler language program using only machine
instructions. The assembler provides additional functions that make this task
easier. They are summarized below.

Symbolic Representation of Program Elements

Symbols greatly reduce programming effort and errors. You can define symbols to
represent storage addresses, displacements, constants, registers, and almost any
element that makes up the assembler language. These elements include
operands, operand subfields, terms, and expressions. Symbols are easier to
remember and code than numbers; moreover, they are listed in a symbol cross
reference table, which is printed in the program listings. Thus, you can easily find a
symbol when searching for an error in your code. See page 29 for details about
symbols, and how you can use them in your program.

Variety in Data Representation

You can use decimal, binary, hexadecimal, or character representation of machine
language binary values in writing source statements. You select the representation
best suited to the purpose. The assembler converts your representations into the
binary values required by the machine language.

Controlling Address Assignment

|
|

If you code the correct assembler instruction, the assembler computes the relative
offset, or displacement from a base address, of any symbolic addresses you
specify in a machine instruction. It inserts this displacement, along with the base
register assigned by the assembler instruction, into the object code of the machine
instruction.
At execution time, the object code of address references must be in
relative-immediate or base-displacement form. The computer obtains the required
address by adding the displacement to the base address contained in the base
register, or from the relative-immediate offset of the instruction.

Relocatability
The assembler produces an object module that is independent of the location it is
initially assigned in virtual storage. That is, it can be loaded into any suitable virtual
storage area without affecting program execution. This is made easier because
most addresses are assembled in their base-displacement form.

Sectioning a Program
You can divide a source module into one or more control sections. After assembly,
you can include or delete individual control sections from the resulting object
module before you load it for execution. Control sections can be loaded separately
into storage areas that are not contiguous. A discussion of sectioning is contained
in Source Program Structures on page 51.

Chapter 1. Introduction

Coding Made Easier

Linkage between Source Modules

You can create symbolic linkages between separately assembled source modules.
This lets you refer symbolically from one source module to data and instructions
defined in another source module. You can also use symbolic addresses to branch
between modules.
A discussion of sectioning and linking is contained in Source Program Structures
on page 51.

Program Listings
The assembler produces a listing of your source module, including any generated
statements, and the object code assembled from the source module. You can
control the form and content of the listing using assembler listing control
instructions, assembler options, and user I/O exits. The listing control instructions
are described in Chapter 5, Assembler Instruction Statements on page 100, and
in Processing Statements on page 256. Assembler options and user I/O exits are
discussed in the HLASM Programmer's Guide.
The assembler also prints messages about actual errors and warnings about
potential errors in your source module.
|
|
|
|

Multiple Source Modules

|
|
|

An input stream may contain one or more source modules, and may also consist
of one or more data sets if the host operating system supports data set or file
concatenation. A source module is a single assembly.

The assembler can assemble more than one source module in a single input
stream, if the BATCH option is specified. For more information about the BATCH
option, see HLASM Programmer's Guide.

HLASM V1R5 Language Reference

Character Set

Chapter 2. Coding and Structure

This chapter provides information about assembler language coding conventions
and assembler language structure.

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

Standard Character Set

The standard (default) character set used by High Level Assembler is a subset of
the EBCDIC character set. This subset consists of letters of the alphabet, national
characters, the underscore character, digits, and special characters. The complete
set of characters that make up the standard assembler language character set is
shown in Figure 3.
Figure 3. Standard Character Set
Alphabetic characters

a through z
A through Z
national characters @, $, and #
underscore character _

Digits

0 through 9

Special characters

+ - , = . ( ) ' / &
space

For a description of the binary and hexadecimal representations of the characters

that make up the standard character set, see Appendix D, Standard Character Set
Code Table on page 421.
When you code terms and expressions (see Terms, Literals, and Expressions on
page 28) in assembler language statements, you can only use the set of
characters described above. However, when you code remarks, comments or
character strings between paired single quotation marks, you can use any character
in the EBCDIC character set.
The term alphanumeric characters includes both alphabetic characters and digits,
but not special characters. Normally, you would use strings of alphanumeric
characters to represent terms, and special characters as:
Arithmetic operators in expressions
Data or field delimiters
Indicators to the assembler for specific handling
Whenever a lowercase letter (a through z) is used, the assembler considers it to be
identical to the corresponding uppercase character (A through Z), except when it is
used within a character string enclosed in single quotation marks, or within the
positional and keyword operands of macro instructions.

Copyright IBM Corp. 1982, 2004

Character Set

Compatibility with Earlier Assemblers: You can specify the

COMPAT(MACROCASE) assembler option to instruct the assembler to maintain
uppercase alphabetic character set compatibility with earlier assemblers for
unquoted macro operands. The assembler converts lowercase alphabetic
characters (a through z) in unquoted macro operands to uppercase alphabetic
characters (A through Z).

Double-Byte Character Set

In addition to the standard EBCDIC set of characters, High Level Assembler
accepts double-byte character set (DBCS) data. The double-byte character set
consists of the following:
Figure 4. Double-Byte Character Set (DBCS)
Double-byte space

X'4040'

Double-byte characters

Each double-byte character contains two bytes, each of

which must be in the range X'41' to X'FE'. The first byte
of a double-byte character is known as the ward byte. For
example, the ward byte for the double-byte representation
of EBCDIC characters is X'42'.

Shift codes

Shift-out (SO) - X'0E'

Shift-in (SI) - X'0F'

Note:
1. SO and SI delimit DBCS data only when the DBCS assembler option is specified. The
DBCS assembler option is described in the HLASM Programmer's Guide.
2. When the DBCS assembler option is specified, double-byte characters may be used
anywhere that EBCDIC characters enclosed by single quotation marks can be used.
3. Regardless of the invocation option, double-byte characters may be used in remarks,
comments, and the statements processed by AREAD and REPRO statements.

Examples showing the use of EBCDIC characters and double-byte characters are
given in Figure 5. For a description of the DBCS notation used in the examples,
see Double-Byte Character Set Notation on page xvi.
Figure 5 (Page 1 of 2). Examples Using Character Set
Characters

Usage

Example

Constituting

Alphanumeric

In ordinary symbols

Label
FIELD#1
Save_Total
&EASY_TO_READ

Terms

1
9

Terms

In variable symbols
Digits

HLASM V1R5 Language Reference

As decimal
self-defining
terms

Character Set

Figure 5 (Page 2 of 2). Examples Using Character Set

Characters

Usage

Special
Characters

As operators

Example

Constituting

Addition

NINE+FIVE

Expressions

Subtraction

NINE-5

Expressions

Multiplication

9FIVE

Expressions

Division

TEN/3

Expressions

(Unary)

+NINE

+ or

Terms

-FIVE

As delimiters
Spaces

Between fields

LABEL

Comma

Between operands

OPND1,OPND2

Operand field

Single
Quotation Marks

Enclosing
character strings

'STRING'

String

Attribute operator

L'OPND1

Term

Parentheses

Enclosing subfields
or subexpressions

MOVE MVC TO(8),FROM(A+B(C-D))

Statement
Expression

SO and SI

Enclosing
double-byte data

C'<.A.B.C>abc'
G'<D1D2D3D4>'

Mixed string
Pure DBCS

Statement

3,4

As indicators for
Ampersand

Variable symbol

&VAR

Term

Period

Symbol qualifier

QUAL.SYMBOL

Term

Sequence symbol

.SEQ

(label)

Comment statement
in macro definition

.THIS IS A COMMENT

Statement

Concatenation

&VAR.A

Term

Bit-length
specification

DC CL.7'AB'

Operand

Decimal point

DC F'1.7E4'

Operand

Location counter
reference

+72

Expression

Comment statement

THIS IS A COMMENT

Operand

Literal reference

Operand

Keyword

&KEY=D

Asterisk

|
|

|
|
|

Equal sign

6,=F'2'

Keyword
parameter

Note:
1. If these are passed as macro arguments, they are treated as expressions, not terms. Expressions
cannot be substituted into SETA expressions.

Chapter 2. Coding and Structure

Assembler Language Coding Conventions

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. You can supply a translation table using the TRANSLATE assembler
option described in the HLASM Programmer's Guide.

Self-defining Terms: Self-defining terms are not translated when a translation

table is used. See How to Generate a Translation Table in the HLASM
Programmer's Guide.

Assembler Language Coding Conventions

Figure 6 shows the standard format used to code an assembler language
statement.

1 2 3 4 5 6 7 8 9 1 ... 71 72 73 74 75 76 ... 8

Statement Field Identification-Sequence Field

ContinuationIndicator Field

Figure 6. Standard Assembler Coding Format

Field Boundaries
Assembler language statements usually occupy one 80-character record, or line.
For information about statements that occupy more than 80 characters, see
Continuation Lines on page 15. Each line is divided into three main fields:
Statement field
Continuation-indicator field
Identification-sequence field
If it can be printed, any character coded into any column of a line, or otherwise
entered as a position in a source statement, is reproduced in the listing printed by
the assembler. Whether it can be printed or not depends on the printer.
Uppercase Printing: Use the FOLD assembler option to instruct the assembler to
convert lowercase alphabetic characters to uppercase alphabetic characters before
they are printed.

Statement Field
The instructions and comment statements must be written in the statement field.
The statement field starts in the begin column and ends in the end column. The
continuation-indicator field always lies in the column after the end column, unless
the end column is column 80, in which case no continuation is possible. The
identification-sequence field usually lies in the field after the continuation-indicator
field. Any continuation lines needed must start in the continue column and end in
the end column.
Blank lines are acceptable. For more information, see Blank Lines on page 18.

HLASM V1R5 Language Reference

Assembler Language Coding Conventions

The assembler assumes the following standard values for these columns:
The begin column is column 1
The end column is column 71
The continue column is column 16
These standard values can be changed by using the Input Format Control (ICTL)
assembler instruction. The ICTL instruction can, for example, be used to reverse
the order of the statement field and the identification-sequence field by changing
the standard begin, end, and continue columns. However, all references to the
begin, end, and continue columns in this manual refer to the standard values
described above.

Continuation-Indicator Field
The continuation-indicator field occupies the column after the end column.
Therefore, the standard position for this field is column 72. A non-space character
in this column indicates that the current statement is continued on the next line.
This column must be a space character on the last (or only) line of a statement. If
this column is not a space, the assembler treats the statement that follows on the
next line as a continuation line of the current statement.
If the DBCS assembler option is specified, then:
When an SI is placed in the end column of a continued line, and an SO is
placed in the continue column of the next line, the SI and SO are considered
redundant and are removed from the statement before statement analysis is
done.
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.
The double-byte delimiters SO and SI cannot be used as
continuation-indicators.

Identification-Sequence Field
The identification-sequence field can contain identification characters or sequence
numbers or both. If the ISEQ instruction has been specified to check this field, the
assembler verifies whether or not the source statements are in the correct
sequence.
The columns checked by the ISEQ function are not restricted to columns 73
through 80, or by the boundaries determined by any ICTL instruction. The columns
specified in the ISEQ instruction can be anywhere on the input statement, including
columns that are occupied by the statement field.

Continuation Lines
To continue a statement on another line, follow these rules:
1. Enter a non-space character in the continuation-indicator field (column 72).
This non-space character must not be part of the statement coding. When
more than one continuation line is needed, enter a non-space character in
column 72 of each line that is to be continued.
2. Continue the statement on the next line, starting in the continue column
(column 16). Columns to the left of the continue column must be spaces.
Comment statements may be continued after column 16.
Chapter 2. Coding and Structure

Assembler Language Coding Conventions

If an operand is continued after column 16, it is taken to be a comment. Also, if the

continuation-indicator field is filled in on one line and you try to start a new
statement after column 16 on the next line, this statement is taken as a comment
belonging to the previous statement.
Specify the FLAG(CONT) assembler option to instruct the assembler to issue
warning messages when it suspects a continuation error in a macro call instruction.
Refer to the FLAG option description in the HLASM Programmer's Guide for details
about the situations that might be flagged as continuation errors.
Unless it is one of the statement types listed below, nine continuation lines are
allowed for a single assembler language statement.

Alternative Statement Format

The alternative statement format, which allows as many continuation lines as are
needed, can be used for the following instructions:
AGO conditional assembly statement, see Alternative Format for AGO
Instruction on page 393
AIF conditional assembly statement, see Alternative Format for AIF Instruction
on page 392
GBLA, GBLB, and GBLC conditional assembly statements, see Alternative
Format for GBLx Statements on page 345
LCLA, LCLB, and LCLC conditional assembly statements, see Alternative
Format for LCLx Statements on page 347
Macro instruction statement, see Alternative Formats for a Macro Instruction
on page 298
Prototype statement of a macro definition, see Alternative Formats for the
Prototype Statement on page 246
SETA, SETB, SETAF, SETCF and SETC conditional assembly statements, see
Alternative Statement Format on page 388
Examples of the alternative statement format for each of these instructions are
given with the description of the individual instruction.

Continuation of double-byte data

No special considerations apply to continuation:
Where double-byte data is created by a code-generation program, and
There is no requirement for double-byte data to be readable on a device
capable of presenting DBCS characters
A double-byte character string may be continued at any point, and SO and SI must
be balanced within a field, but not within a statement line.
Where double-byte data is created by a workstation that has the capability of
presenting DBCS characters, such as the IBM 5550 multistation, or where
readability of double-byte data in High Level Assembler source input or listings is
required, special features of the High Level Assembler language may be used.
When the DBCS assembler option is specified, High Level Assembler provides the
flexibility to cater for any combination of double-byte data and single-byte data.
The special features provided are:
Removal of redundant SI/SO at continuation points. When an SI is placed in
the end column of a continued line, and an SO is placed in the continue

HLASM V1R5 Language Reference

Assembler Language Coding Conventions

column of the next line, the SI and SO are considered redundant and are
removed from the statement before statement analysis.
An extended continuation-indicator provides a flexible end column on a
line-by-line basis to support any alignment of double-byte data in a source
statement. The end column of continued lines may be shifted to the left by
extending the continuation-indicator.
To guard against accidental continuation caused by double-byte data ending in
the continuation-indicator column, neither SO nor SI is regarded as a
continuation-indicator. If either is used, the following warning message is
issued:
ASMA21W SO or SI in continuation column - no continuation
assumed
The examples below show the use of these features. Refer to Double-Byte
Character Set Notation on page xvi for the notation used in the examples.
Source Input Considerations

|
|

Extended continuation-indicators may be used in any source statement,

including macro statements and statements included by the COPY instruction.
This feature is intended for source lines containing double-byte data, however it
becomes available to all lines when the DBCS option is set.
On a line with a non-space continuation-indicator, the end column is the first
column to the left of the continuation-indicator which has a value different from
the continuation-indicator.
When converting existing programs for assembly with the DBCS option, ensure
that continuation-indicators are different from the adjacent data in the end
column.
The extended continuation-indicators must not be extended into the continue
column, otherwise the extended continuation-indicators are treated as data, and
the assembler issues the following error message:
ASMA25E Extended continuation column must not extend into continue
column
For SI and SO to be removed at continuation points, the SI must be in the end
column, and the SO must be in the continue column of the next line.
Examples:
Name

Operation

Operand

Continuation

C'<D1D2D3D4D5D6D7D8D9>XXXXXXXXXXXXXXXXXXXX
<DaDb>'

DBCS1

DBCS2

C'abcdefghijklmnopqrstuvwxyz123456789XXXX
<DaDb>'

DBCS3

C'abcdefghijklmnopqrstuv<D1D2D3D4D5D6D7>XX
<DaDb>'

DBCS1: The DBCS1 constant contains 11 double-byte characters bracketed by SO

and SI. The SI and SO at the continuation point are not assembled into the
operand. The assembled value of DBCS1 is:
<D1D2D3D4D5D6D7D8D9DaDb>
Chapter 2. Coding and Structure

Assembler Language Coding Conventions

DBCS2: The DBCS2 constant contains an EBCDIC string which is followed by a

double-byte string. Because there is no space for any double-byte data on the first
line, the end column is extended three columns to the left and the double-byte data
started on the next line. The assembled value of DBCS2 is:
abcdefghijklmnopqrstuvwxyz123456789<DaDb>
DBCS3: The DBCS3 constant contains 22 EBCDIC characters followed by 9
double-byte characters. Alignment of the double-byte data requires that the end
column be extended one column to the left. The SI and SO at the continuation
point are not assembled into the operand. The assembled value of DBCS3 is:
abcdefghijklmnopqrstuv<D1D2D3D4D5D6D7DaDb>
Source Listing Considerations
For source that does not contain substituted variable symbols, the listing
exactly reflects the source input.
Double-byte data input from code-generation programs, that contain no
substituted variables, are not readable in the listing if the source input was not
displayable on a device capable of presenting DBCS characters.
Refer to Listing of Generated Fields Containing Double-Byte Data on
page 249 for details of extended continuation and macro-generated
statements.

Blank Lines
Blank lines are accepted in source programs. 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 Statement Format

Comment statements are not assembled as part of the object module, but are only
printed in the assembly listing. You can write as many comment statements as you
need, provided you follow these rules:
Comment statements require an asterisk in the begin column. Internal macro
definition comment statements require a period in the begin column, followed
by an asterisk. Internal macro comments are accepted as comment statements
in open code.
Any characters of the EBCDIC character set, or double-byte character set can
be used (see Character Set on page 11).
Comment statements must lie within the statement field. If the comment
extends into the continuation-indicator field, the statement following the
comment statement is considered a continuation line of that comment
statement.
Comment statements must not appear between an instruction statement and its
continuation lines.

HLASM V1R5 Language Reference

Assembler Language Coding Conventions

Instruction Statement Format

Instruction statements must consist of one to four entries in the statement field.
They are:

A name entry
An operation entry
An operand entry
A remarks entry

These entries must be separated by one or more spaces, and must be written in
the order stated.

Statement Coding Rules

The following general rules apply to the coding of an instruction statement:
The entries must be written in the following order: name, operation, operand,
and remarks.
The entries must be contained in the begin column (1) through the end column
(71) of the first line and, if needed, in the continue column (16) through the end
column (71) of any continuation lines.
The entries must be separated from each other by one or more spaces.
If used, a name entry must start in the begin column.
The name and operation entries, each followed by at least one space, must be
contained in the first line of an instruction statement.
The operation entry must begin at least one column to the right of the begin
column.
Statement Example: The following example shows the use of name, operation,
operand, and remarks entries. The symbol COMP names a compare instruction, the
operation entry (CR) is the mnemonic operation code for a register-to-register
compare operation, and the two operands (5,6) designate the two general registers
whose contents are to be compared. The remarks entry reminds readers that this
instruction compares NEW SUM to OLD.
COMP

5,6

NEW SUM TO OLD

Descriptions of the name, operation, operand, and remarks entries follow:

Name Entry: The name entry is a symbol created by you to identify an instruction
statement. A name entry is usually optional. Except for two instances, the name
entry, when provided, must be a valid symbol at assembly time (after substituting
variable symbols, if specified). For a discussion of the exceptions to this rule, see
TITLE Instruction on page 215 and Macro Instruction Format on page 297.
|

The symbol must consist of 63 or fewer alphanumeric characters, the first of which
must be alphabetic. It must be entered with the first character appearing in the
begin column. If the begin column is a space, the assembler program assumes no
name has been entered. No spaces or double-byte data may appear in the
symbol.
Operation Entry: The operation entry is the symbolic operation code specifying
the machine, assembler, or macro instruction operation. The following rules apply
to the operation entry:

Chapter 2. Coding and Structure

Assembler Language Coding Conventions

|
|

An operation entry is mandatory, and it must appear on the same line as any
name entry.
For machine and assembler instructions, it must be a valid symbol at assembly
time (after substitution for variable symbols, if specified), consisting of 63 or
fewer alphanumeric characters, the first which must be alphabetic. Most
standard symbolic operation codes are five characters or fewer. For a
description of machine instructions, see the applicable Principles of Operation
manual. For a summary of assembler instructions, see Appendix A,
Assembler Instructions.
The standard set of codes can be changed by OPSYN instructions (see
OPSYN Instruction on page 198).
For macro instructions, the operation entry can be any valid symbol.
An operation entry cannot be continued on the next statement.
Operand Entries: Operand entries contain zero or more operands that identify
and describe data to be acted upon by the instruction, by indicating such
information as storage locations, masks, storage area lengths, or types of data.
The following rules apply to operands:
One or more operands are usually required, depending on the instruction.
Operands must be separated by commas. No spaces are allowed between the
operands and the commas that separate them.
A space normally indicates the end of the operand entry, unless the operand is
in single quotes. This applies to machine, assembler, and macro instructions.

|
|

A space does not end the operand in some types of SET statement. Spaces
that do not end operands are discussed further at:

Arithmetic (SETA) Expressions on page 352

Logical (SETB) Expressions on page 365

Character (SETC) Expressions on page 371

|
|

There are two examples of operands containing spaces in Figure 10 on

page 26; the last box in Row 3, and the middle box in Row 4.

|
|

The alternative statement format uses slightly different rules. For more
information, see Alternative Formats for a Macro Instruction on page 298.
The following instruction is correctly coded:
LA

R1,4+5

No space

The following instruction may appear to be the same, but is not:

R1,4 + 5

Spaces included

In this example, the embedded space means that the operand finishes after 4.
There is no assembler error, but the result is a LA
R1,4, which may not be what
you intended.
A space inside unquoted parentheses is an error, and leads to a diagnostic. The
following instruction is correctly coded:
DC

CL(L'STRLEN)' '

Space within quotes

The following instruction, with an extra space, is not correct:

HLASM V1R5 Language Reference

Assembler Language Structure

CL(L'STRLEN )' '

Space not within quotes

The following example shows a space enclosed in quotes, as part of a string. This
space is properly accounted for:
MVC
|

AREA1,=C'This Area' Space inside quotes

In quotes, spaces and parentheses can occur in any quantity and in any order:
LA

R1,=C'This is OK (isn''t it)'

Remarks Entries: Remarks are used to describe the current instruction. The
following rules apply to remarks:
Remarks are optional.
They can contain any character from the EBCDIC character set, or the
double-byte characters set.
They can follow any operand entry.
In statements in which an optional operand entry is omitted, but you want to
code a comment, indicate the absence of the operand by a comma preceded
and followed by one or more spaces, as shown below:
END

End of Program

Assembler Language Structure

This section describes the structure of the assembler language, including the
statements that are allowed in the language, and the elements that make up those
statements.
Statement Coding Rules on page 19 describes the composition of an assembler
language source statement.
The figures in this section show the overall structure of the statements that
represent the assembler language instructions, and are not specifications for these
instructions. The individual instructions, their purposes, and their specifications are
described in other sections of this manual.
Model statements, used to generate assembler language statements, are described
in Chapter 7, How to Specify Macro Definitions.
The remarks entry in a source statement is not processed by the assembler, but it
is printed in the assembler listing. For this reason, it is only shown in the overview
of the assembler language structure in Figure 7 on page 23, and not in the other
figures.
The machine instruction statements are described in Figure 8 on page 24,
discussed in Chapter 4, Machine Instruction Statements, and summarized in the
applicable Principles of Operation manual.
Assembler instruction statements are described in Figure 9 on page 25, discussed
in Chapter 3, Program Structures and Addressing and Chapter 5, Assembler
Instruction Statements, and are summarized in Appendix A, Assembler
Instructions.

Chapter 2. Coding and Structure

Assembler Language Structure

Conditional assembly instruction statements and the macro processing statements

(MACRO, MEND, MEXIT, MNOTE, AREAD, ASPACE, and AEJECT) are described
in Figure 10 on page 26. The conditional assembly instructions are discussed in
Chapter 9, How to Write Conditional Assembly Instructions, and macro
processing instructions in Chapter 7, How to Specify Macro Definitions. Both
types are summarized in Appendix A, Assembler Instructions.
Macro instruction statements are described in Figure 11 on page 27, and
discussed in Chapter 8, How to Write Macro Instructions on page 297.

HLASM V1R5 Language Reference

Assembler Language Structure

Overview of Assembler Language Structure

|
|
|

Source module

made up of

source statements

Which can be

EITHER OR

INSTRUCTION

COMMENT

STATEMENTS

Which are of

three main types

MACHINE

ASSEMBLER

MACRO

Instructions
Instructions
Instructions

Which are composed of

from one to four fields

NAME

OPERATION

OPERAND

REMARKS

No DBCS

Which, for machine

instructions, is

composed of

EXPRESSIONS

Which are

composed of

Which are

composed of

TERMS

Combination

Any

of terms

Characters

Which are
composed of

EBCDIC and DBCS

CHARACTERS

Figure 7. Overview of Assembler Language Structure

Chapter 2. Coding and Structure

Assembler Language Structure

Machine Instructions

NAME

Field

Which
can be

A Symbol

(or space)

OPERATION

Field

Which
must be

A symbolic

Operation

Code

OPERAND

Field

Which
can be

Zero or more
arguments

Composed of one of

Exp(Exp,Exp)

Expression

Exp(Exp)

Exp(,Exp)

Which can be one of

Arithmetic

Term

combination

of terms

Which can be any of

A Symbol

Location

Symbol

A Literal

Counter

Attribute

Self-Defining

Reference

Term

(e.g. HERE)

(i.e. )

(e.g. L'HERE)

(e.g. =H'9')

Which can be any of

Decimal

Hexadecimal

Binary

Character

Graphic

(e.g. 9)

(e.g. X'F9')
(e.g. B'111')
(e.g. C'JAN')
(e.g. G'.A')

Can be an ordinary symbol, a variable symbol, or a sequence symbol

With DBCS option only

Figure 8. Machine Instructions

HLASM V1R5 Language Reference

Assembler Language Structure

Assembler Instructions

NAME

Field

Which
can be

A Symbol

(or space)

OPERAND

Field

Which
can be

Zero or more
operands

For Data Definition

For all other

(DC and DS

ordinary Assembler
Instructions)

Instructions

Operands can be
Operands
composed of one
can be composed
to five subfields
of

Duplication
Type

Type
Modifiers

Nominal

factor

Extension

Value

Expression Character
Symbolic

(e.g.+14)
String

Option

(e.g. 'XX')
(e.g. GEN)

e.g. 1 E B
L2 '12'

One or more nominal values

'Decimal

(Expression)
'Character
'Graphic

number'

string'

(e.g. '12')

(e.g. (ADDR))
(e.g. 'ABC')
(e.g. '<.A>')

OPERATION

Field

Which
must be

A symbolic

Operation

Code

Can be an ordinary symbol, a variable symbol, or a sequence symbol

Includes symbolic operation codes of macro definitions
Discussed more fully where individual instructions are described
With DBCS option only

Figure 9. Ordinary Assembler Instruction Statements

Chapter 2. Coding and Structure

Assembler Language Structure

Conditional Assembly Instructions

NAME

Field

Which
can be

Sequence

Variable

Symbol

or space

(e.g. .SEQ)
(e.g. &VAR)

OPERATION

Field

Which
must be

A symbolic

Operation

Code

OPERAND

Field

Which
can be

Zero or more
operands

Composed of

Sequence

Variable

Expression

(Exp)seqsym

Symbol

(e.g.

(Expression)
(&A EQ 1).SEQ)

Which can be any

combination of
variable symbols
and other characters
that constitute an

Arithmetic

Logical

Character

Expression

(e.g.

(e.g. &A+1)

(&B1 OR &B2))
(e.g. 'JAN&C')

Figure 10. Conditional Assembly Instructions

Macro instruction statements are described in Figure 11 on page 27.

HLASM V1R5 Language Reference

Assembler Language Structure

Macro Instructions
Prototype
Statement

Symbolic

Zero or more

Parameter

Operation

Symbolic

Code

Parameters

Which can be
Must be the
Which can be

same as

Macro

Instruction

Statement

NAME

OPERATION

OPERAND

Field

Zero or more

Operands

Which can be
Which can be

A Symbol

Character

Operands with
Sublists with

String

one value

one or more

entries

Each entry

can have a

value

Which can be
Which can be

Ordinary

Sequence

Variable

Character

'Character

Symbol

String

String'

(or space)

(excluding

(including

spaces and

spaces)

commas)

Figure 11. Macro Instructions

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

The most basic element of the assembler language is the term. Terms may be
used alone, or in combination with other terms in expressions. This section
describes the different types of terms used in the assembler language, and how
they can be used.

Terms
A term is the smallest element of the assembler language that represents a distinct
and separate value. It can, therefore, be used alone or in combination with other
terms to form expressions. Terms are classified as absolute or relocatable,
depending on the effect of program relocation upon them. Program relocation is
the loading of the object program into storage locations other than those originally
assigned by the assembler. Terms have absolute or relocatable values that are
assigned by the assembler or that are inherent in the terms themselves.
A term is absolute if its value does not change upon program relocation. A term is
relocatable if its value changes by n if the origin of the control section in which it
appears is relocated by n bytes.
Terms in Parentheses: Terms in parentheses are reduced to a single value; thus
the terms in parentheses, in effect, become a single term.
You can use arithmetically combined terms, enclosed in parentheses, in
combination with terms outside the parentheses, as follows:
14+BETA-(GAMMA-LAMBDA)
When the assembler encounters terms in parentheses in combination with other
terms, it first reduces the combination of terms inside the parentheses to a single
value which may be absolute or relocatable, depending on the combination of
terms. This value is then used in reducing the rest of the combination to another
single value.
You can include terms in parentheses within a set of terms in parentheses:
A+B-(C+D-(E+F)+1)
The innermost set of terms in parentheses is evaluated first. Any number of levels
of parentheses are allowed. A level of parentheses is a left parenthesis and its
corresponding right parenthesis. An arithmetic combination of terms is evaluated
as described in Expressions on page 44. Figure 12 summarizes the various
types of terms, and gives a reference to the page number that discusses the term
and the rules for using it.
Figure 12 (Page 1 of 2). Summary of Terms

Terms

Term
can be
absolute

Term can
be
relocatable

Value is
assigned
by
assembler

Symbols

Literals

Self-defining terms

HLASM V1R5 Language Reference

Value is
inherent
in term

Page
reference

Terms, Literals, and Expressions

Figure 12 (Page 2 of 2). Summary of Terms

Terms

Term
can be
absolute

Location counter
reference

Term can
be
relocatable

Value is
assigned
by
assembler

Value is
inherent
in term

Page
reference

Symbol length
attribute

Other data
attributes

Notes:
1. Other valid data attributes are S and I.

|
|

For more information about absolute and relocatable expressions, see Absolute
and Relocatable Expressions on page 47.

Symbols
You can use a symbol to represent storage locations or arbitrary values. If you
write a symbol in the name field of an instruction, you can then specify this symbol
in the operands of other instructions and thus refer to the former instruction
symbolically. This symbol represents a relocatable address.
You can also assign an absolute value to a symbol by coding it in the name field of
an EQU instruction with an operand whose value is absolute. This lets you use this
symbol in instruction operands to represent:

Registers
Displacements in explicit addresses
Immediate data
Lengths
Implicit addresses with absolute values

For details of these program elements, see Operand Entries on page 85.
The advantages of symbolic over numeric representation are:
Symbols are easier to remember and use than numeric values, thus reducing
programming errors and increasing programming efficiency.
You can use meaningful symbols to describe the program elements they
represent. For example, INPUT can name a field that is to contain input data, or
INDEX can name a register to be used for indexing.
You can change the value of one symbol that is used in many instructions
(through an EQU instruction) more easily than you can change several numeric
values in many instructions.
|
|

If the symbols are relocatable, the assembler can calculate displacements and
assign base registers for you.
Symbols are entered into a cross reference table that is printed in the Ordinary
Symbol and Literal Cross Reference section of the assembler listing. The cross
reference helps you find a symbol in the source and object section of the listing
because it shows:

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

The number of the statement that defines the symbol. A symbol is defined
when it appears in the name entry of a statement.
The number of all the statements in which the symbol is used as an
operand.
Symbol Table: When the assembler processes your source statements for the
first time, it assigns an absolute or relocatable value to every symbol that appears
in the name field of an instruction. The assembler enters this value, which normally
reflects the setting of the location counter, into the symbol table. It also enters the
attributes associated with the data represented by the symbol. The values of the
symbol and its attributes are available later when the assembler finds this symbol
or attribute reference used as a term in an operand or expression. See Symbol
Length Attribute Reference and Self-Defining Terms in this chapter for more
details. The three types of symbols recognized by the assembler are:
Ordinary symbols
Variable symbols
Sequence symbols
Ordinary Symbols: Ordinary symbols can be used in the name and operand
fields of machine and assembler instruction statements. Code them to conform to
these rules:
The symbol must not consist of more than 63 alphanumeric characters. The
first character must be an alphabetic character. An alphabetic character is a
letter from A through Z, or from a through z, or $, _, #, or @. The other
characters in the symbol may be alphabetic characters, digits, or a combination
of the two.
|
|

The assembler makes no distinction between upper-case and lower-case

letters used in symbols.

|
|

If the GOFF option is not specified, external symbols may not consist of
more than 8 characters.
No other special characters may be included in an ordinary symbol.
No spaces are allowed in an ordinary symbol.
No double-byte data is allowed in an ordinary symbol.
In the following sections, the term symbol refers to the ordinary symbol.
The following examples are valid ordinary symbols:
ORDSYM#435A
K4
B49467LITTLENAIL

HERE
#123
@33

$OPEN
X
_TOTAL_SAVED

Variable Symbols: Variable symbols must begin with an & followed by an

alphabetic character and, optionally, up to 61 alphanumeric characters. Variable
symbols can be used in macro processing and conditional assembly instructions,
and to provide substitution in machine and assembler instructions. They allow
different values to be assigned to one symbol. A complete discussion of variable
symbols appears in Chapter 7, How to Specify Macro Definitions on page 243.
The following examples are valid variable symbols:

HLASM V1R5 Language Reference

Terms, Literals, and Expressions

&VARYINGSYMABC
&F346944
&EASY_TO_READ

&@ME
&A

System Variable Symbol Prefix: A variable symbol should not begin with the
characters &SYS as they are used to prefix System Variable Symbols. See System
Variable Symbols on page 262 for a list of the System Variable Symbols provided
with High Level Assembler.

Sequence Symbols: Sequence symbols consist of a period (.) followed by an

alphabetic character, and up to 61 additional alphanumeric characters. Sequence
symbols can be used in macro processing and conditional assembly instructions.
They indicate the position of statements within the source program or macro
definition. They are used in AIF and AGO statements to vary the sequence in
which statements are processed by the assembler program. (See the complete
discussion in Chapter 9, How to Write Conditional Assembly Instructions.)
The following examples are valid sequence symbols:
.BLABEL4
.BRANCHTOMEFIRST

.#359
.A

Symbol Definition: An ordinary symbol is defined in:

The name entry in a machine or assembler instruction of the assembler
language
One of the operands of an EXTRN or WXTRN instruction
Ordinary symbols can also be defined in instructions generated from model
statements during conditional assembly.
In Figure 13 on page 32, the assembler assigns a value to the ordinary symbol in
the name entry according to the following rules:
1. The symbol is assigned a relocatable address value if the first byte of the
storage field contains one of the following:
Any machine or assembler instruction, except the EQU or OPSYN
instruction (see 1 in Figure 13)
A storage area defined by the DS instruction (see 2 in Figure 13)
Any constant defined by the DC instruction (see 3 in Figure 13)
A channel command word defined by the CCW, CCW0, or CCW1
instruction
The address value assigned is relocatable, because the object code assembled
from these items is relocatable. The relocatability of addresses is described in
Addresses on page 87.
2. The symbol is assigned the value of the first or only expression specified in the
operand of an EQU instruction. This expression can have a relocatable (see
4 in Figure 13) or absolute (see 5 in Figure 13) value, which is then
assigned to the ordinary symbol.
|
|
|

The value of an ordinary absolute symbol must lie in the range 231 through
+2311. Relocatable symbols have unsigned address values in the range from
0 to 2241, or 0 to 2311 if the GOFF option is specified.

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

Assembler Language
Address Value
Object Code
Statements

of Symbol

in Hexadecimal

Relocatable

Address

of AREA

LOAD
L
3,AREA 1 LOAD 583xxxx

AREA
DS
F
2 AREA xx x x xxxx

F2
DC
F'2' 3 F2 C8

FULL
EQU
AREA
FULL

4

TW
EQU
F2
TW

Absolute

R3
EQU
3
5 R3=3

Address

of FULL

L
R3,FULL

583xxxx

A
R3,TW

5A3xxxx

Address

of TW
Figure 13. Transition from Assembler Language Statement to Object Code

Restrictions on Symbols: A symbol must be defined only once in a source

module with one or more control sections, with the following exceptions:
The symbol in the name field of a CSECT, RSECT, DSECT, or COM instruction
can be the same as the name of previous CSECT, RSECT, DSECT, or COM
instruction, respectively. It identifies the resumption of the control section
specified by the name field.

The symbol in the name field of a CATTR instruction can be the

same as the name of a previous CATTR instruction. It identifies the resumption
of the class specified by the name field.

The symbol in the name field of a LOCTR instruction can be the same as the
name of a previous START, CSECT, RSECT, DSECT, COM, or LOCTR
instruction. It identifies the resumption of the location counter specified by the
name field.
The symbol in the name field of a labeled USING instruction can be the same
as the name of a previous labeled USING instruction. It identifies the
termination of the domain of the previous labeled USING instruction with the
specified name.
A symbol can be used as an operand of a V-type constant and as an ordinary
label, without duplication, because the operand of a V-type constant does not
define the symbol in the symbol table.

|
|

HLASM V1R5 Language Reference

Terms, Literals, and Expressions

An ordinary symbol is not defined when:

It is used in the name field of an OPSYN or TITLE instruction. It can,
therefore, be used in the name field of any other statement in a source module.
It is used as the operand of a V-type address constant.
It is only used in the name field of a macro instruction and does not appear in
the name field of a macro-generated assembler statement. It can, therefore, be
used in the name field of any other statement in a source module.
It is only used in the name field of an ALIAS instruction and does not appear in
one of the following:
The name field of a START, CSECT, RSECT, COM, or DXD instruction.
The name field of a DSECT instruction and the nominal value of a Q-type
address constant.
The operand of an ENTRY, EXTRN or WXTRN instruction.

Previously Defined Symbols: An ordinary symbol is previously defined if the

statement that defines it is processed before the statement in which the symbol
appears in an operand.
An ordinary symbol must be defined by the time the END statement is reached,
however, it need not be previously defined when it is used as follows:
In operand expressions of certain instructions such as CNOP instructions and
some ORG instructions
In modifier expressions of DC, DS, and DXD instructions
In the first operand of an EQU instruction
In Q-type constants
When using the forward-reference capability of the assembler, avoid the following
types of errors:
Circular definition of symbols, such as:
X
Y

EQU
EQU

Y
X

Circular location-counter dependency, as in this example:

A
B

DS
LR

(B-A)C
1,2

The first statement in this example cannot be resolved because the value of the
duplication factor is dependent on the location of B, which is, in turn, dependent
upon the length and duplication factor of A.
Literals may contain symbolic expressions in modifiers, but any ordinary symbols
used must have been previously defined.

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

Self-Defining Terms
A self-defining term lets you specify a value explicitly. With self-defining terms, you
can also specify decimal, binary, hexadecimal, or character data. If the DBCS
assembler option is specified, you can specify a graphic self-defining term that
contains pure double-byte data, or include double-byte data in character
self-defining terms. These terms have absolute values and can be used as
absolute terms in expressions to represent bit configurations, absolute addresses,
displacements, length or other modifiers, or duplication factors.
Using Self-Defining Terms: Self-defining terms represent machine language
binary values and are absolute terms. Their values do not change upon program
relocation. Some examples of self-defining terms and the binary values they
represent are given below:
Self-Defining Term

Decimal Value

Binary Value

1111

241

1111 1

1111

B'11111'

241

1111 1

B'11'

257

1 1

X'F'

1111

X'F1'

241

1111 1

X'11'

257

1 1

C'1'

241

1111 1

C'A'

193

11 1

C'AB'

49,62

11 1 11 1

G'<.A>'

17,89

1 1 11 1

B'1111'

The assembler carries the values represented by self-defining terms to 4 bytes or

32 bits, the high-order bit of which is the sign bit. (A '1' in the sign bit indicates a
negative value; a '0' indicates a positive value.)
The use of a self-defining term is distinct from the use of data constants or literals.
When you use a self-defining term in a machine instruction statement, its value is
used to determine the binary value that is assembled into the instruction. When a
data constant is referred to or a literal is specified in the operand of an instruction,
its address is assembled into the instruction. Self-defining terms are always
right-justified. Truncation or padding with zeros, if necessary, occurs on the left.
Decimal Self-Defining Term: A decimal self-defining term is simply an unsigned
decimal number written as a sequence of decimal digits. High-order zeros may be
used (for example, 7). Limitations on the value of the term depend on its use.
For example, a decimal term that designates a general register should have a value
between 0 and 15. A decimal term that represents an address should not exceed
the size of storage. In any case, a decimal term may not consist of more than 10
digits, nor exceed 2,147,483,647 (2311). A decimal self-defining term is
assembled as its binary equivalent. Some examples of decimal self-defining terms
are: 8, 147, 492, and 21.

HLASM V1R5 Language Reference

Terms, Literals, and Expressions

Hexadecimal Self-Defining Term: A hexadecimal self-defining term consists of

1-to-8 hexadecimal digits enclosed in single quotation marks and preceded by the
letter X; for example, X'C49'.
Each hexadecimal digit is assembled as its 4-bit binary equivalent. Thus, a
hexadecimal term used to represent an 8-bit mask would consist of 2 hexadecimal
digits. The maximum value of a hexadecimal term is X'FFFFFFFF'; this allows a
range of values from 2,147,483,648 through 2,147,483,647.
The hexadecimal digits and their bit patterns are as follows:

1
2
3

1
1
11

4
5
6
7

1
11
11
111

8
9
A
B

1
11
11
111

C
D
E
F

11
111
111
1111

When used as an absolute term in an expression, a hexadecimal self-defining term

has a negative value if the high-order bit is 1.
Binary Self-Defining Term: A binary self-defining term is written as an unsigned
sequence of 1s and 0s enclosed in single quotation marks and preceded by the
letter B; for example, B'1111'. A binary term may have up to 32 bits. This
allows a range of values from 2,147,483,648 through 2,147,483,647.
When used as an absolute term in an expression, a binary self-defining term has a
negative value if the term is 32 bits long and the high-order bit is 1.
Binary representation is used primarily in designating bit patterns of masks or in
logical operations.
The following shows a binary term used as a mask in a Test Under Mask (TM)
instruction. The contents of GAMMA are to be tested, bit by bit, against the pattern of
bits represented by the binary term.
ALPHA

GAMMA,B'11111'

Character Self-Defining Term: A character self-defining term consists of 1-to-4

characters enclosed in single quotation marks, and must be preceded by the letter
C. All letters, decimal digits, and special characters may be used in a character
self-defining term. In addition, any of the remaining EBCDIC characters may be
designated in a character self-defining term. Examples of character self-defining
terms are:
C'/'
C' ' (space)
C'ABC'
C'13'
Because of the use of single quotation marks in the assembler language and
ampersands in the macro language as syntactic characters, the following rule must
be observed when using these characters in a character self-defining term:
For each single quotation mark or ampersand you want in a character
self-defining term, two single quotation marks or ampersands must be written.
For example, the character value A'# would be written as 'A''#', while a
single quotation mark followed by a space and another single quotation mark
would be written as ''' '''.

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

For C-type character self-defining terms, each character in the character sequence
is assembled as its 8-bit code equivalent (see Appendix D, Standard Character
Set Code Table on page 421). The two single quotation marks or ampersands
that must be used to represent a single quotation mark or ampersand within the
character sequence are assembled as a single quotation mark or ampersand.
Double-byte data may appear in a character self-defining term, if the DBCS
assembler option is specified. The assembled value includes the SO and SI
delimiters. Hence a character self-defining term containing double-byte data is
limited to one double-byte character delimited by SO and SI. For example,
C'<.A>'.
Since the SO and SI are stored, the null double-byte character string, C'<>', is also
a valid character self-defining term.
Note: The assembler will not support character self-defining terms of the form
CU'x' because self-defining terms are required by definition of the Assembler
Language to have fixed values.
Graphic Self-Defining Term: If the DBCS assembler option is specified, a
graphic self-defining term can be specified. A graphic self-defining term consists of
1 or 2 double-byte characters delimited by SO and SI, enclosed in single quotation
marks and preceded by the letter G. Any valid double-byte characters may be
used. Examples of graphic self-defining terms are:
G'<.A>'
G'<.A.B>'
G'<Da>'
G'<.A><.B>'
The SO and SI are not represented in the assembled value of the self-defining
term, hence the assembled value is pure double-byte data. A redundant SI/SO pair
can be present between two double-byte characters, as shown in the last of the
above examples. However, if SO and SI are used without an intervening
double-byte character, this error is issued:
ASMA148E Self-defining term lacks ending quote or has bad character

Location Counter
The assembler maintains a location counter to assign storage addresses to your
program statements. It is the assembler's equivalent of the execution-time
instruction counter in the computer. You can refer to the current value of the
location counter at any place in a source module by specifying an asterisk () as a
term in an operand.

|
|

As the instructions and constants of a source module are being assembled, the
location counter has a value that indicates a location in the program. The
assembler increments the location counter according to the following:
1. After an instruction or constant has been assembled, the location counter
indicates the next available location.
2. Before assembling the current instruction or constant, the assembler checks the
boundary alignment required for it and adjusts the location counter, if
necessary, to the correct boundary.
3. While the instruction or constant is being assembled, the location counter value
does not change. It indicates the location of the current data after boundary

HLASM V1R5 Language Reference

Terms, Literals, and Expressions

alignment and is the value assigned to the symbol, if present, in the name field
of the statement.
4. After assembling the instruction or constant, the assembler increments the
location counter by the length of the assembled data to indicate the next
available location.
These rules are shown below:
Location in
Hexadecimal
4
7
8
C
1

Source
Statements
DONE
BEFORE
DURING
AFTER
NEXT

DC
EQU
DC
EQU
DS

CL3'ABC'

F'2'

D

You can specify multiple location counters for each control section in a source
module; for more details about the location counter setting in control sections, see
Location Counter Setting on page 61.

|
|
|
|

|
|

Maximum Location Counter Value: The assembler carries internal location

counter values as 4-byte (31-bit unsigned) values. When you specify the NOGOFF
assembler option, the assembler uses only the low-order 3 bytes for the location
counter, and prints only the low-order 3 bytes in the assembly source and object
code listing if the LIST(121) option is active. All four bytes are displayed if the
LIST(133) option is active. In this case the maximum valid location counter value is
2241.
When you specify the GOFF assembler option, the assembler requires
the LIST(133) option, and uses the entire 4-byte value for the location counter and
prints the 4-byte value in the assembly listings. In this case the maximum valid
location counter value is 2311.
If the location counter exceeds its valid maximum value the assembler issues error
message
ASMA39S Location counter error
Controlling the Location Counter Value: You can control the setting of the
location counter in a particular control section by using the START or ORG
instruction, described in Chapter 3, Program Structures and Addressing and
Chapter 5, Assembler Instruction Statements, respectively. The counter affected
by either of these assembler instructions is the counter for the control section in
which they appear.
Location Counter Reference: You can refer to the current value of the location
counter at any place in a program by using an asterisk as a term in an operand.
The asterisk is a relocatable term, specified according to the following rules:
The asterisk can be specified only in the operands of:
Machine instructions
DC and DS instructions
EQU, ORG, and USING instructions

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

It can also be specified in literal constants. See Literals on page 40. For
example:
|

THERE

generates three identical address constants, each with value A(THERE).

|
|

The value of the location counter reference (*) is the same as the value of the
symbol THERE, the current value of the location counter of the control section
in which the asterisk (*) is specified as a term. The asterisk has the same
value as the address of the first byte of the instruction in which it appears. For
example:
HERE

=3A()

where the value of is the value of HERE.

For the value of the asterisk in address constants with duplication factors, see
Subfield 1: Duplication Factor on page 132 of DC Instruction on page 126, and
Address ConstantsA and Y on page 153. For a discussion of location counter
references in literals, see Subfield 1: Duplication Factor on page 132.

|
|

Symbol Length Attribute Reference

The length attribute of a symbol may be used as a term. Reference to the attribute
is made by coding L' followed by the symbol, as in:
L'BETA
The length attribute of BETA is substituted for the term. When you specify a symbol
length attribute reference, you obtain the length of the instruction or data named by
a symbol. You can use this reference as a term in instruction operands to:
Specify assembler-determined storage area lengths
Cause the assembler to compute length specifications for you
Build expressions to be evaluated by the assembler
The symbol length attribute reference must be specified according to the following
rules:
|
|
|

The format must be L' immediately followed by a valid symbol (L'SYMBOL), an

expression (L'SYMBOL+SYMBOL2-SYMBOL7), or the location counter reference (L').
If the operand is an expression, the length attribute of its leftmost term is used.

Symbols must be defined in the same source module in which the symbol
length attribute reference is specified.
The symbol length attribute reference can be used in the operand of any
instruction that requires an absolute term. However, it cannot be used in the
form L' in any instruction or expression that requires a previously defined
symbol.
The value of the length attribute is normally the length in bytes of the storage area
required by an instruction, constant, or field represented by a symbol. The
assembler stores the value of the length attribute in the symbol table along with the
address value assigned to the symbol.
When the assembler encounters a symbol length attribute reference, it substitutes
the value of the attribute from the symbol table entry for the symbol specified.

HLASM V1R5 Language Reference

Terms, Literals, and Expressions

The assembler assigns the length attribute values to symbols in the name field of
instructions as follows:
For machine instructions (see 1 in Figure 14), it assigns either 2, 4, or 6,
depending on the format of the instruction.
For the DC and DS instructions (see 2 in Figure 14), it assigns either the
implicitly or explicitly specified length of the first or only operand. The length
attribute is not affected by a duplication factor.
For the EQU instruction, it assigns the length attribute value of the first or only
term (see 3 in Figure 14) of the first expression in the first operand, unless a
specific length attribute is supplied in a second operand.
Note the length attribute values of the following terms in an EQU instruction:
Self-defining terms (see 4 in Figure 14)
Location counter reference (see 5 in Figure 14)
L'* (see 6 in Figure 14)

|
|

For assembler instructions such as DC, DS, and EQU, the length attribute of the
location counter reference (L'* see 6 in Figure 14) is equal to 1. For
machine instructions, the length attribute of the location counter reference (L'*
see 7 in Figure 14) is equal to the length attribute of the instruction in which the
L'* appears.
Figure 14. Assignment of Length Attribute Values to Symbols in Name Fields

Source Module

|
|

Length Attribute
Reference

Value of Symbol
Length Attribute At
Assembly Time
1
1
1

MACHA
MACHB
MACHC

MVC
L
LR

TO,FROM
3,ADCON
3,4

L'MACHA
L'MACHB
L'MACHC

6
4
2

TO
FROM
ADCON
CHAR
DUPL

DS
DS
DC
DC
DC

CL8
CL24
A(OTHER)
C'YUKON'
3F'2'

L'TO
L'FROM
L'ADCON
L'CHAR
L'DUPL

8 2
24 2
4
2
5
2
4
2

RELOC1
RELOC2
RELOC3
ABSOL1
ABSOL2

EQU
EQU
EQU
EQU
EQU

TO
TO+8
TO,44
FROM-TO
ABSOL1

L'RELOC1
L'RELOC2
L'RELOC3
L'ABSOL1
L'ABSOL2

8
8
44
24
24

SDT1
SDT2
SDT3

EQU
EQU
EQU

12
3
X'FF'+AB 3
C'YUK'

L'SDT1
L'SDT2
L'SDT3

1
1
1

4
4
4

ASTERISK

EQU

L'ASTERISK

LOCTREF
LENGTH1

EQU
DC

L'
A(L')

L'LOCTREF
L'
L'LENGTH1

1
1
4

6
6

LENGTH2
LENGTH3

MVC
MVC

TO(L'),FROM
TO(L'TO2),FROM

L'
L'TO

6
8

3
3
3
3
3

Note: Instructions that contain length attribute references L'SDT1, L'SDT2, L'SDT3,
L'ASTERISK, and L'LOCTREF as shown in this figure may generate ASMA019W.

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

The following example shows how to use the length attribute to move a character
constant into either the high-order or low-order end of a storage field.
A1
B2
HIORD
LOORD

DS
DC
MVC
MVC

CL8
CL2'AB'
A1(L'B2),B2
A1+L'A1-L'B2(L'B2),B2

A1 names a storage field 8 bytes in length and is assigned a length attribute of 8.

B2 names a character constant 2 bytes in length and is assigned a length attribute
of 2. The statement named HIORD moves the contents of B2 into the first 2 bytes of
A1. The term L'B2 in parentheses provides the length specification required by the
instruction.
The statement named LOORD moves the contents of B2 into the rightmost 2 bytes of
A1. The combination of terms A1+L'A1-L'B2 adds the length of A1 to the beginning
address of A1, and subtracts the length of B2 from this value. The result is the
address of the seventh byte in field A1. The constant represented by B2 is moved
into A1 starting at this address. L'B2 in parentheses provides the length
specification in both instructions.
For ease in following the preceding example, the length attributes of A1 and B2 are
specified explicitly in the DS and DC statements that define them. However, keep
in mind that the L'symbol term makes coding such as this possible in situations
where lengths are unknown. For example:
C3
STRING

DC
MVC

C'This is too long a string to be worth counting'

BUF(L'C3),C3

Other Attribute References

Other attributes describe the characteristics and structure of the data you define in
a program; for example, the kind of constant you specify or the number of
characters you need to represent a value. These other attributes are:

Count (K')
Defined (D')
Integer (I')
Number (N')
Operation code (O')
Scale (S')
Type (T'); allowed only in conditional assembly.

You can refer to the count (K'), defined (D'), number (N'), and operation code
(O') attributes only in conditional assembly instructions and expressions. For full
details, see Data Attributes on page 324.

Literals
You can use literals as operands in order to introduce data into your program. The
literal is a special type of relocatable term. It behaves like a symbol in that it
represents data. However, it is a special kind of term because it also is used to
define the constant specified by the literal. This is convenient because:
The data you enter as numbers for computation, addresses, or messages to be
printed is visible in the instruction in which the literal appears.
You avoid the added effort of defining constants elsewhere in your source
module and then using their symbolic names in machine instruction operands.

HLASM V1R5 Language Reference

Terms, Literals, and Expressions

The assembler assembles the data item specified in a literal into a literal pool (See
Literal Pool on page 44). It then assembles the address of this literal data item in
the pool into the object code of the instruction that contains the literal specification.
Thus, the assembler saves you a programming step by storing your literal data for
you. The assembler also organizes literal pools efficiently, so that the literal data is
aligned on the correct boundary alignment and occupies a minimum amount of
space.

Literals, Constants, and Self-Defining Terms

Literals, constants, and self-defining terms differ in three important ways:
Where you can specify them in machine instructions, that is, whether they
represent data or an address of data
Whether they have relocatable or absolute values
What is assembled into the object code of the machine instruction in which they
appear
Figure 15 on page 42 shows examples of the differences between literals,
constants, and self-defining terms.

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

1. A literal with a relocatable address:

F33

L
L
.
.
.
DC

3,=F'33'
3,F33

Register 3 set to 33.

See note 1
See note 2

F'33'

2. A literal with a self-defining term and a symbol with an absolute value

FLAG
ZERO

MVC
MVI
MVI
.
.
.
DS
EQU

FLAG,=X''
FLAG,X''
FLAG,ZERO

FLAG set to X''.

FLAG set to X''.
FLAG set to X''.

See note 1
See note 3
See note 4

X
X''

3. A symbol having an absolute address value specified by a self-defining term

LOCORE

LA
LA
.
.
.
EQU

4,LOCORE
4,1

Register 4 set to 1.

See note 4
See note 3

Notes:
1. A literal both defines data and represents data. The address of the literal is assembled
into the object code of the instruction in which it is used. The constant specified by the
literal is assembled into the object code, in the literal pool.
2. A constant is represented by a symbol with a relocatable value. The address of a
constant is assembled into the object code.
3. A self-defining term has an absolute value. In this example, the absolute value of the
self-defining term is assembled into the object code.
4. A symbol with an absolute value does not represent the address of a constant, but
represents either immediate data or an absolute address. When a symbol with an
absolute value represents immediate data, it is the absolute value that is assembled into
the object code.
Figure 15. Differences between Literals, Constants, and Self-Defining Terms

General Rules for Using Literals

You can specify a literal as either a complete operand in a machine instruction, or
as part of an expression in the operand of a machine instruction. A literal can also
be specified as the name field on a macro call instruction.
Because literals define read-only data, they must not be used in operands that
represent the receiving field of an instruction that modifies storage.
The assembler requires a description of the type of literal being specified as well as
the literal itself. This descriptive information assists the assembler in assembling
the literal correctly. The descriptive portion of the literal must indicate the format of
the constant. It can also specify the length of the constant.

HLASM V1R5 Language Reference

Terms, Literals, and Expressions

|
|
|

The method of describing and specifying a constant as a literal is nearly identical to

the method of specifying it in a single operand of a DC assembler instruction. The
only difference is that the literal must start with an equal sign (=), which indicates to
the assembler that a literal follows. The length of the literal, including the equal
sign, constant type and modifiers, delimiters, and nominal values is limited to a
maximum of 256 characters.
A literal may be coded as indicated here:
=1XL5'F3'
where the subfields are:
Duplication factor 1
Type
X
Modifiers
L5
Nominal value
'F3'
The following instruction shows one use of a literal:
GAMMA

1,=F'274'

The statement GAMMA is a load instruction using a literal as the second operand.
When assembled, the second operand of the instruction refers to the relative
address at which the value F'274' is stored.
|
|
|
|

You cannot rely on the ordering of literals in the literal pool remaining the same.
For this reason, referring to a point that extends beyond the bounds of a literal is
flagged with warning message ASMA015W. Here is an example of such a
reference:

BETA

1,=F'274'+4

In general, literals can be used wherever a storage address is permitted as an

operand, including in conjunction with an index register in instructions with the RX
format. For example:
DELTA

5,=H'11,23,39,48,64'(6)

is equivalent to:
DELTA

LENGTHS

LH
.
.
.
DC

5,LENGTHS(6)

H'11,23,39,48,64'

See DC Instruction on page 126 for a description of how to specify the subfields
in a literal.

|
|

Literals cannot be used in any assembler instruction where a previously defined

symbol is required, but length attribute references to previously defined literals are
allowed. Literals are relocatable terms because the address of the literal, rather
than the literal-generated constant itself, is assembled in the statement that
references a literal. The assembler generates the literals, collects them, and places
them in a specific area of storage, as explained under Literal Pool on page 44.
Because the assembler determines the order in which literals are placed in the
literal pool, the effect of using two literals as paired relocatable terms (see Paired
Relocatable Terms on page 47) is unpredictable.

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

Location Counter Reference on page 37 describes how you can use the current
location counter in a literal.
|

The rules for determining whether two literals are identical are:

|
|

1. A literal which contains a location counter reference is not identical to any other
literal.

|
|

2. Otherwise, two literals are identical (and will be generated only once), if their
source forms are identical.
Contrast with Immediate Data: You should not confuse a literal with the
immediate data in an SI instruction. Immediate data is assembled into the
instruction.

Literal Pool
The literals processed by the assembler are collected and placed in a special area
called the literal pool. You can control the positioning of the literal pool. Unless
otherwise specified, the literal pool is placed at the end of the first control section.
You can also specify that multiple literal pools be created. However, the assembler
controls the sequence in which literals are ordered within the pool. Further
information on positioning literal pools is in LTORG Instruction on page 193.

Expressions
This section discusses the expressions used in coding operand entries for source
statements. You can use an expression to specify:

An address
An explicit length
A modifier
A duplication factor
A complete operand

Expressions have absolute and relocatable values. Whether an expression is

absolute or relocatable depends on the value of the terms it contains. The
assembler evaluates relocatable and absolute expressions at assembly time.
Figure 16 on page 45 shows examples of valid expressions.
|

In addition to expressions used in coding operand entries, there are three types of
expression that you can use only in conditional assembly instructions: arithmetic,
logical, and character expressions. They are evaluated during conditional
assembly. For more information, see Assigning Values to SET Symbols on
page 347.

|
|

An expression is composed of a single term or an arithmetic combination of terms.

The assembler reduces multiterm expressions to single values. Thus, you do not
have to compute these values yourself. The following are examples of valid
expressions:

HLASM V1R5 Language Reference

Terms, Literals, and Expressions

AREA1+X'2D'
+32
N25
FIELD+332
FIELD
(EXITENTRY+1)+GO
ALPHABETA/(1+AREAL'FIELD)1
=A(1,133,175,221)+8

BETA1
B'11'
C'ABC'
29
L'FIELD
LAMBDA+GAMMA
TEN/TWO
=F'1234'

Figure 16. Examples of Valid Expressions

Rules for Coding Expressions

The rules for coding an absolute or relocatable expression are:
Unary (operating on one value) operators and binary (operating on two values)
operators are allowed in expressions.
An expression can have one or more unary operators preceding any term in
the expression or at the beginning of the expression.
|
|

An expression must not begin with a binary operator, nor can it contain two
binary operators in succession. When + and are used as prefix operators,
then they are unary, and not binary, operators.

|
|

An expression starting with is interpreted as a location counter reference, and

not a multiplication operator.
An expression must not contain two terms in succession.
No spaces are allowed between an operator and a term, nor between two
successive operators.
An expression can contain any number of unary and binary operators, and any
number of levels of parentheses.
A single relocatable term is not allowed in a multiply or divide operation. Note
that paired relocatable terms have absolute values and can be multiplied and
divided if they are enclosed in parentheses. See Paired Relocatable Terms
on page 47.
Figure 17 on page 46 shows the definitions of absolute and relocatable
expressions.

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

Absolute

Expression

Can be any of

Rel. Exp. Absolute Abs. Exp. Abs. Exp. Abs. Exp. Abs. Exp. (Abs. Exp.) +Abs. Exp. Abs. Exp.

Term

+

Rel. Exp.
Abs. Exp. Abs. Exp. Abs. Exp. Abs. Exp.

Can be any of

unary operators

Absolute
Self Symbol
Symbol
Symbol

Valued
Defining Length
Integer
Scale

Ordinary
Term
Attribute Attribute Attribute

Symbol

Relocatable
Expression

Can be any of

Operators Allowed

Relocatable Rel. Exp. Rel. Exp. (Rel. Exp.) +Rel. Exp. Rel. Exp.
Unary: + Positive
Term

+

Negative

Abs. Exp. Abs. Exp.

Binary: + Addition

Subtraction

Multiplication
Can be any of

/ Division

unary operators

Relocatable Location
Rel. Exp. = Relocatable Expression
Valued
Counter

Abs. Exp. = Absolute Expression

Ordinary
Reference
Symbol

Figure 17. Definitions of Absolute and Relocatable Expressions

Evaluation of Expressions
A single-term expression, like 29 or BETA, has the value of the term involved. The
assembler reduces a multiterm expression, like 251+A/B or BETA+1, to a single
value, as follows:
1. It evaluates each term.
2. It does arithmetic operations from left to right. However:
a. It does unary operations before binary operations.
b. It does binary operations of multiplication and division before the binary
operations of addition and subtraction.
3. In division, it gives an integer result; any fractional portion is dropped. Division
by zero gives 0.

HLASM V1R5 Language Reference

Terms, Literals, and Expressions

4. In parenthesized expressions, the assembler evaluates the innermost

expressions first and then considers them as terms in the next outer level of
expressions. It continues this process until the outermost expression is
evaluated.
5. A term or expression's intermediate value and computed result must lie in the
range of 231 through +2311.
The assembler evaluates paired relocatable terms at each level of expression
nesting.

Absolute and Relocatable Expressions

An expression is absolute if its value is unaffected by program relocation. An
expression is relocatable if its value depends upon program relocation. The two
types of expressions, absolute and relocatable, take on these characteristics from
the term or terms composing them. A description of the factors that determine
whether an expression is absolute or relocatable follows.
Absolute Expression: An absolute expression is one whose value remains the
same after program relocation. The value of an absolute expression is called an
absolute value.
An expression is absolute, and is reduced to a single absolute value if the
expression:
1. Comprises a symbol with an absolute value, a self-defining term, or a symbol
length attribute reference, or any arithmetic combination of absolute terms.
2. Contains relocatable terms alone or in combination with absolute terms, and if
all these relocatable terms are paired.
Relocatability Attribute: The relocatability attribute describes the attribute of a
relocatable term. If a pair of terms are defined in the same control section, they
are characterized as having the same relocatability attribute.
|
|

If the terms are defined in different control sections, or have different relocatability
attributes, the expression is said to be complex relocatable.

|
|

The relocatability attribute is the same as the ESDID for external symbols, and the
Relocation ID in the listing.
Paired Relocatable Terms: An expression can be absolute even though it
contains relocatable terms, provided that all the relocatable terms are paired. The
pairing of relocatable terms cancels the effect of relocation.
The assembler reduces paired terms to single absolute terms in the intermediate
stages of evaluation. The assembler considers relocatable terms as paired under
the following conditions:
The paired terms must have the same relocatability attribute.
The paired terms must have opposite signs after all unary operators are
resolved. In an expression, the paired terms do not have to be contiguous
(that is, other terms can come between the paired terms).
The value represented by the paired terms is absolute.

Chapter 2. Coding and Structure

Terms, Literals, and Expressions

The following examples show absolute expressions. A is an absolute term; X and Y

are relocatable terms with the same relocatability:
A-Y+X
A
AA
X-Y+A
(+)-(+)
-

|
|

A reference to the location counter must be paired with another relocatable term
from the same control section; that is, with the same relocatability. For example:
-Y
Relocatable Expression: A relocatable expression is one whose value changes
by n if the origin of the control section in which it appears is relocated n bytes.
A relocatable expression can be a single relocatable term. The assembler reduces
a relocatable expression to a single relocatable value if the expression:
1. Is composed of a single relocatable term, or
2. Contains relocatable terms, alone or in combination with absolute terms, and
a. All the relocatable terms but one are paired. Note that the unpaired term
gives the expression a relocatable value; the paired relocatable terms and
other absolute terms constitute increments or decrements to the value of
the unpaired term.
b. The relocatability attribute of the whole expression is that of the unpaired
term.
c. The sign preceding the unpaired relocatable term must be positive, after all
unary operators have resolved.
The following examples show relocatable expressions. A is an absolute term, W
and X are relocatable terms with the same relocatability attribute, and Y is a
relocatable term with a different relocatability attribute.
Y32A
(reference to
location counter)

WX+
WX+W
WX+Y

=F'1234' (literal)
Y
AA+WW+Y

Complex Relocatable Expressions: Complex relocatable expressions, unlike

relocatable expressions, can contain:
Two or more unpaired relocatable terms
An unpaired relocatable term preceded by a negative sign
|
|

Using the same symbols, the following are examples of complex relocatable
expressions:

|
|

W+X
X-Y

+
A-W+Y

Complex relocatable expressions are used in A-type and Y-type address constants
to generate address constant values. For more details, refer to Complex
Relocatable Expressions, and Address ConstantsA and Y on page 153.
V-type and S-type constants may not contain complex relocatable expressions.

HLASM V1R5 Language Reference

Terms, Literals, and Expressions

You can assign a complex relocatable value to a symbol using the EQU instruction,
as described on page 184.

Chapter 2. Coding and Structure

Chapter 3. Program Structures and Addressing

This chapter describes how you use symbolic addresses to refer to data in your
assembler language program, and how you divide a large program into smaller
parts and use symbolic addresses in one part to refer to data in another part.

Object Program Structures

|
|
|
|
|
|
|

High Level Assembler supports two object-program models. The older load
module model generally involves one or more independently relocatable control
sections combined into a single block of machine language text, which is loaded
into a single contiguous portion of memory. Addresses within this block of text are
resolved to locations within the block, or are left unresolved. Such programs may
be considered one-dimensional structures. Examples include MVS load modules,
CMS modules, and VSE phases.

|
|
|
|
|
|
|
|
|
|

The second object-program model supports a two-dimensional

structure called a program object. The loaded program may consist of one or more
contiguous blocks of machine language text grouped in classes and placed in
different portions of memory. Each contribution of machine language text to a class
is provided by an owning section, and the independently relocatable text from a
section that contributes to a class is an element. For certain types of class, an
element may contain parts. Unlike a control section, a program object section may
specify more than one independently relocatable block of text. Addresses within
each class may be resolved to addresses in the same or different classes. A class
in a program object has behavior properties similar to those of a load module.

|
|
|
|

Section names are specified with the CSECT, RSECT, and START statements, and
class and part names are specified with the CATTR statement. Additional
attributes can be assigned to external symbols with the XATTR statement.

|
|
|
|

The program object model can be created only when the GOFF option is specified.
The load module model can be created when either the NOGOFF or GOFF option
is specified, but there are limitations on source program statements if GOFF is
specified.

|
|
|
|

Note: The term section is used in different senses for each object-program model.
In the load module model, a section is a control section. In the program object
model, a section is a one-dimensional cross-section of program object data
containing contributions to one or more classes.

|
|
|
|
|

Note: Features supported by High Level Assembler when you specify

the GOFF option may not be supported by the system linker/binder or run-time
environment where the assembled program will be processed. You should check
the relevant product documentation before utilizing the assembler's features.

The following figure illustrates the differences between the object-program models.

Copyright IBM Corp. 1982, 2004

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

Control

Section

Control

Section

:
:
:
:
:
:

Load Module Model

Class
Class
Class

part

Section element element

part

Section element element part

:
:
:
:
:
:
:
:
:
:

Program Object Model

Figure 18. Load Module and Program Object Structures

Source Program Structures

This part of the chapter explains how to subdivide a large program into smaller
parts that are easier to understand and maintain. It also explains how to divide
these smaller parts such as one section or element to contain executable
instructions, and another to contain data constants and work areas.
You should consider two different subdivisions when writing an assembler language
program:

|
|

The source module

The control section (load module model), or sections, elements, and parts
(program object model)
You can divide a program into two or more source modules. Each source module
is assembled into a separate object module. The object modules can then be
combined to form an executable program.

|
|

You can also divide a source module into two or more sections, or (in the program
object model) into sections containing multiple classes. Each section is assembled
as part of the same object module. By writing the correct linker control statements,
you can select a complete object module or any individual section of the object
module to be linked and later loaded as an executable program.

|
|
|
|

Size of Program Components: If a source module becomes so large that its

logic is not easily understood, divide it into smaller modules. For some instructions,
at most 4096 bytes can be addressed by one base register. Long-displacement
instructions allow you to address 1048576 bytes with one base register.

Communication between Program Components: You must be able to

communicate between the components of your program; that is, be able to refer to
data in a different component or branch to an instruction in another component.
To communicate between two or more source modules, you must link them
together with applicable symbolic references.

To communicate between two or more sections or elements within a source

module, you must correctly establish the addressability of each to the others.

Chapter 3. Program Structures and Addressing

Source Module
A source module is composed of source statements in the assembler language.
You can include these statements in the source module in two ways:
You can enter them directly into the file that contains your source program.
You specify one or more COPY instructions among the source statements
being entered. When High Level Assembler encounters a COPY instruction, it
replaces the COPY instruction with a predetermined set of source statements
from a library. These statements then become a part of the source module.
See COPY Instruction on page 122 for more details.

Beginning of a Source Module

The first statement of a source module can be any assembler language statement,
except MEXIT and MEND. You can initiate the first control section of a source
module by using the START instruction. However, you can write some source
statements before the beginning of the first control statement. See First Section
on page 54 for more details.

End of a Source Module

|
|
|
|
|
|
|
|
|

The END instruction marks the end of a source module. However, you can code
several END instructions; conditional assembly processing can determine which of
several coded or substituted END instructions is to be processed. Also, specifying
the BATCH option allows you to supply more than one source module in a single
input stream; when BATCH is specified, the assembler completes assembling a
source module when an END statement is encountered, and if further statements
are found in the input stream, assembly of a new source module is begun. See
END Instruction on page 182 for more details, and HLASM Programmer's Guide
for information about the BATCH option.
Conditional Assembly: Conditional assembly processing can determine which of
several coded or substituted END instructions is to be processed.

|
|

Sections, Elements, and Parts

In the load module model, a control section is the smallest subdivision of a program
that can be relocated as a unit. The assembled control sections contain the object
code for machine instructions, data constants, and areas.

|
|
|
|

In the program object model, elements and parts are the smallest subdivisions of a
program that can be relocated as a unit. Sections allow grouping all element and
part contributions under a single name. The assembled sections, elements, and
parts contain the object code for the machine instructions, data, and areas.
Consider the concept of a control section at different processing times:

At coding time: You create a control section or an element or part when you
write the instructions it contains. In addition, you establish the addressability of
each component within the source module, and provide any symbolic linkages
between components that lie in different source modules. You also write the linker
control statements to combine sections into a load module or program object, and
to provide an entry point address for the beginning of program execution.

|
|
|

HLASM V1R5 Language Reference

At assembly time: High Level Assembler translates the source statements into
object code. Each source module is assembled into one object module. The
contents of the object module are relocatable.

At linking time: As specified by linker or binder control statements, the linker or

binder combines the object code of one or more sections into one load module or
program object. It also calculates the addresses needed to accommodate common
sections and external dummy sections from different object modules. In addition, it
calculates the space needed to accommodate external dummy sections.
You can specify the relocatable address of the starting point for program execution
in a linker control statement or request a starting address in the operand field of an
assembler END instruction.

|
|

At program fetch time: The control program loads the load module or program
object into virtual storage. All the relocatable addresses are converted to fixed
locations in storage.

At execution time: The control program passes control to the loaded program
now in virtual storage, and your program is run.

|
|
|
|
|
|
|

Sections
In the load module model, control sections may generate machine language text
containing instructions and data, or define mappings of storage areas to be
referenced at execution time. Control sections that generate machine language
text are called executable control sections, even though they may contain only
data. Control sections that create only mappings are called reference control
sections.

|
|
|
|
|

In the program object model, sections may define classes containing

elements. (Classes are described in Classes (MVS and CMS) on page 59.)
Elements may contain machine language text or define mappings, or both.
Elements may in turn contain one or more parts, which are described at Parts
(MVS and CMS) on page 61.

|
|
|

Elements containing machine language text are usually linked in a class comprising
other elements containing machine language text, and elements defining mappings
are usually linked in a class with other elements defining mappings.

|
|
|
|
|
|

The section name is used in binder operations to refer to its entire collection of
elements and parts, but a program object section is not the same as a load module
control section. A section name may be referenced as an external name only if
defined as an entry point in an element belonging to that section. (By default, the
assembler will generate an entry point in class B_TEXT with the section's name.
See Classes (MVS and CMS) on page 59 for more information.)

|
|

The term executable is used to describe both executable control sections in the
load module model, or sections in the program object model.

You initiate a section by using the START, CSECT, or RSECT instruction, as

described below:
The START instruction can be used to initiate the first or only section of a
source module. For more information about the START instruction, see
START Instruction on page 214.
Chapter 3. Program Structures and Addressing

The CSECT instruction can be used anywhere in a source module to initiate or

continue a section. For more information about the CSECT instruction, see
CSECT Instruction on page 123.
Like the CSECT instruction, the RSECT instruction can be used anywhere in a
source module to initiate or continue a section. Unlike the CSECT instruction,
however, the RSECT instruction causes the assembler to check the coding in
the section for possible violations of reenterability. For more information about
the RSECT instruction, see RSECT Instruction on page 212.
A section can also be initiated as an unnamed section, or private code, without
using the START, CSECT, or RSECT instruction. For more information, see
Unnamed Section on page 55.

First Section
|

Before you initiate the first section in your source module, you may code only
certain instructions. The following information lists those instructions that initiate
the first section, and those instructions that may precede the first section.

What must appear before the first section: The ICTL instruction, if specified,
must be the first statement in a source module.
*PROCESS statements must precede all other statements in a source module,
except the ICTL instruction. There is a limit of 10 *PROCESS statements allowed
in a source module. Additional *PROCESS statements are treated as assembler
comment statements. See page 102 for a description of the *PROCESS statement.

What can optionally appear before the first executable control section: The
instructions or groups of instructions that can optionally be specified before the first
executable control section are:

The following assembler instructions:

ACONTROL
DXD
MACRO
PUSH

|
|

ADATA
EJECT
MEND
REPRO

AINSERT
ENTRY
MEXIT
SPACE

ALIAS
EXITCTL
POP
TITLE

CEJECT
EXTRN
PRINT
WXTRN

COPY
ISEQ
PUNCH
XATTR

Comment statements, including macro format comment statements

Any statement which is part of an inline macro definition
Common control sections
Dummy control sections
Any conditional assembly instruction
Macro instructions that do not generate statements that establish the first
section

The above instructions or groups of instructions belong to a source module, but are
not considered part of an executable section.

HLASM V1R5 Language Reference

Instructions that establish the first section: Any instruction that affects the
location counter, or uses its current value, establishes the beginning of the first
executable section. The instructions that establish the first section include any
machine instruction and the following assembler instructions:
|
|
|

CCW
DC
RSECT

|
|

CSECT, RSECT, and START start a possibly named control section. The other
statements start an unnamed control section.

CCW
DS
START

CCW1
EQU
USING

CNOP
LOCTR

CSECT
LTORG

CXD
ORG

These instructions are always considered a part of the control section in which they
appear.
The statements copied into a source module by a COPY instruction determine
whether it initiates the first control section. The PROFILE option causes the
assembler to generate a COPY statement as the first statement after any ICTL or
*PROCESS statements.
The DSECT, COM, and DXD instructions initiate reference control sections and do
not establish the first executable section.
Any instructions copied by a COPY instruction, or generated by the processing of a
macro instruction before the first section, must belong exclusively to one of the
groups of instructions shown above. Any other instructions cause the assembler to
establish the first section.
All the instructions or groups of instructions listed above can also appear as part of
a section.
If you specify the PROFILE assembler option the assembler generates a COPY
statement as the first statement in the assembly after any ICTL or *PROCESS
statements. The copy member should not contain any ICTL or *PROCESS
statements.

Unnamed Section
The unnamed section is an executable section that can be initiated in one of the
following two ways:
By coding a START, CSECT, or RSECT instruction without a name entry
By coding any instruction, other than the START, CSECT, or RSECT
instruction, that initiates the first executable section
|
|
|
|
|

An unnamed control section is sometimes referred to as private code. Private code

sections are sometimes difficult to manage with other system components such as
linkers and configuration management tools. Avoiding their use is recommended.
(Zero-length private code sections are sometimes ignored or discarded by system
linkers.)
All sections should be given names so they can be referred to symbolically:
Within a source module
In EXTRN and WXTRN instructions

Chapter 3. Program Structures and Addressing

|
|

in linker control statements for section ordering and replacement, and for
linkage between source modules
Unnamed common control sections or dummy control sections can be defined if the
name entry is omitted from a COM or DSECT instruction.
If you include an AMODE or RMODE instruction in the assembly and leave the
name field blank, you must provide an unnamed control section.

Reference Control Sections

A reference control section is one you initiate by using the DSECT, COM, or DXD
instruction, as follows:
You can use the DSECT instruction to initiate or continue a dummy control
section. For more information about dummy sections, see Dummy Control
Sections.
You can use the COM instruction to initiate or continue a common control
section. For more information about common sections, see Common Control
Sections on page 57.
You can use the DXD instructions to define an external dummy section. For
more information about external dummy sections, see External Dummy
Sections on page 57.
At assembly time, reference control sections are not assembled into object code.
You can use a reference control section either to reserve storage areas or to
describe data to which you can refer from executable control sections. These
reference control sections are considered empty at assembly time, and the actual
binary data to which they refer is not available until execution time.

Dummy Control Sections

A dummy control section is a reference control section that describes the layout of
data in a storage area without actually reserving any virtual storage.
You may want to describe the format of an area whose storage location is not
determined until the program is run. You can do so by describing the format of the
area in a dummy section, and using symbols defined in the dummy section in the
operands of machine instructions.
The DSECT instruction initiates a dummy control section or indicates its
continuation. For more information about the DSECT instruction, see DSECT
Instruction on page 178.
How to use a dummy control section: A dummy control section (dummy
section) lets you write a sequence of assembler language statements to describe
the layout of data located elsewhere in your source module. The assembler
produces no object code for statements in a dummy control section, and it reserves
no storage in the object module for it. Rather, the dummy section provides a
symbolic format that is empty of data. However, the assembler assigns location
values to the symbols you define in a dummy section, relative to its beginning.
Therefore, to use a dummy section, you must:
Reserve a storage area for the data

HLASM V1R5 Language Reference

Ensure that the locations of the symbols in the dummy section actually
correspond to the locations of the data being described
Establish the addressability of the dummy section in combination with the
storage area
You can then refer to the data symbolically by using the symbols defined in the
dummy section.

Common Control Sections

A common control section is a reference control section that lets you reserve a
storage area that can be used by one or more source modules. One or more
common sections can be defined in a source module.
The COM instruction initiates a common control section, or indicates its
continuation. For more information about the COM instruction, see COM
Instruction on page 121.
How to use a common control section: A common control section (common
section) lets you describe a common storage area in one or more source modules.
When the separately assembled object modules are linked as one program, the
required storage space is reserved for the common control section. Thus, two or
more modules may share the common area.
Only the storage area is provided; the assembler does not assemble the source
statements that make up a common control section into object code. You must
provide the data for the common area at execution time.
The assembler assigns locations to the symbols you define in a common section
relative to the beginning of that common section. This lets you refer symbolically to
the data that is placed in the common section at execution time. If you want to
refer to data in a common control section, you must establish the addressability of
the common control section in each source module that contains references to it. If
you code identical common sections in two or more source modules, you can
communicate data symbolically between these modules through this common
section.
|
|
|
|

Communicating with Modules in Other Languages: Some high-level languages

such as COBOL, PL/I, C, and FORTRAN use common control sections. This lets
you communicate between assembler language modules and modules written in
those languages.

External Dummy Sections

An external dummy section is a reference control section that lets you describe
storage areas for one or more source modules, to be used as:
Work areas for each source module
Communication areas between two or more source modules
|

Note: External dummy sections are also called pseudo-registers in other contexts.
When the assembled object modules are linked and loaded, you can dynamically
allocate the storage required for all your external dummy sections at one time from
one source module (for example, by using the MVS GETMAIN macro instruction).

Chapter 3. Program Structures and Addressing

This is not only convenient, but it saves space and reduces fragmentation of virtual
storage.
|
|
|
|

Typical bind-time processing of external dummy sections involves merging the

attributes of identically-named external dummy sections, retaining only the longest
length and strictest alignment. In particular, the lengths of identically-named
external dummy sections are not additive.
To generate and use the external dummy sections, you need to specify a
combination of the following:
DXD or DSECT instruction
Q-type address constant
CXD instruction
For more information about the DXD and CXD instructions, see DXD Instruction
on page 180 and CXD Instruction on page 125.

|
|
|

Note: The names of dummy external control sections may match the names of
other external symbols that are not names of dummy control sections, without
conflict.

|
|

Generating an external dummy section: An external dummy section is

generated when you specify a DXD instruction, or when you specify a DSECT
instruction whose name appears in a Q-type address constant.

|
|
|
|

When a DSECT name is used as an operand of a Q-type address constant, that

name becomes an external symbol with type XD. The name must satisfy the
name-length requirements of the object file format specified in the assembler
options.

|
|

DXD names may match the names of other types of external symbols without
conflict.
Use the Q-type address constant to reserve storage for the offset to the external
dummy section whose name is specified in the operand. This offset is the distance
in bytes from the beginning of the area allocated for all the external dummy
sections to the beginning of the external dummy section specified. You can use
this offset value to address the external dummy section.
Using external dummy sections: To use an external dummy section, you must
do the following:
1. Identify and define the external dummy section. The assembler computes the
length and alignment required. The linker will merge this definition with other
definitions of the same name, assigning the longest length and strictest
alignment.

|
|
|

2. Provide a Q-type constant for each external dummy section defined.

3. Use the CXD instruction to reserve a fullword area into which the linker or
loader inserts the total length of all the external dummy sections that are
specified in the source modules of your program. The linker computes this
length from the accumulated lengths of the individual external dummy sections
supplied by the assembler.
4. Allocate a storage area using this computed total length.

HLASM V1R5 Language Reference

5. Load the address of the allocated area into a register.

6. Add to the address in the register the offset into the allocated area of the
applicable external dummy section. The linker inserts this offset into the area
reserved by the associated Q-type address constant.
7. Establish the addressability of the external dummy section in combination with
the portion of the allocated area reserved for the external dummy section.
You can now refer symbolically to the locations in the external dummy section.
Note that the source statements in an external dummy section are not assembled
into object code. Thus, you must create the data described by external dummy
sections at execution time.
|
|
|
|
|
|
|
|
|
|
|
|
|

Note: During linking, external dummy sections may be arranged in any order. Do
not assume any ordering relationship among external dummy sections.

Classes (MVS and CMS)

Each section's contributions to a program object are assigned to one or more
classes, according to their desired binding and loading properties. Class names
are assigned either by default (see Default Class Assignments on page 60) or
explicitly. You define a class with the CATTR instruction, which must follow the
initiation of an executable section. The class name is provided in the name entry of
the CATTR instruction, and attributes of the class are provided by the operands of
the first CATTR instruction declaring the class. (See CATTR Instruction (MVS and
CMS) on page 112 for further information.) The element containing subsequent
machine language text or storage definitions is defined by the combination of the
section and class names, as illustrated in Figure 18 on page 51.

For example, suppose you define two classes, CLASS_X and CLASS_Y:

|
|
|
|
|

SECT_A
CLASS_X

|
|
|
|
|

The statements following the first CATTR instruction will be assigned to an element
defined by the section name SECT_A and the class name CLASS_X. Similarly, the
statements following the second CATTR instruction will be assigned to an element
defined by the section name SECT_A and the class name CLASS_Y. CLASS_Y will be
loaded below 16Mb, and CLASS_X may be loaded anywhere below 2Gb.

|
|

Class names are rarely referenced, because the attributes of the class, such as
RMODE, are much more important.

|
|
|

You can resume a class by providing additional CATTR statements with the class
name in the name entry. No attributes of the class may be specified after the first
CATTR statement declaring the class.

|
|

Resuming a section will cause subsequent text to be placed in the B_TEXT class if
there is no intervening CATTR statement defining or resuming a different class:

CLASS_Y

CSECT ,
CATTR RMODE(ANY)
- - CATTR RMODE(24)
- - -

Define section SECT_A

Define class CLASS_X
Statements for CLASS_X
Define class CLASS_Y
Statements for CLASS_Y

Chapter 3. Program Structures and Addressing

|
|
|
|
|
|
|
|
|

SECT_A
CLASS_X

|
|
|

Class Binding and Loading Attributes

CLASS_Y
SECT_A
CLASS_X

CSECT
CATTR
- - CATTR
- - CSECT
- - CATTR
- - -

,
RMODE(ANY)
RMODE(24)
,
,

Define section SECT_A

Define class CLASS_X
Statements for CLASS_X
Define class CLASS_Y
Statements for CLASS_Y
Resume section SECT_A
Statements for class B_TEXT
Resume class CLASS_X
More statements for CLASS_X

Each class is bound into a separately relocatable loadable segment, using one of
two binding attributes.

|
|
|
|
|
|
|

Classes containing parts use merge binding (described at Parts (MVS and
CMS) on page 61). Parts are the smallest independently relocatable
components of a merge class.
Classes not containing parts use concatenation binding, in which elements,
after suitable alignment, are placed one after another. Zero-length elements are
retained but take no space in the program object. Elements are the smallest
independently relocatable components of a concatenation class

|
|
|
|

Each class must have uniform binding and loading attributes. More than one class
may have identical attributes, and the binder may put such classes into one
segment. The most usual class attributes are RMODE, alignment, and Loadability;
see CATTR Instruction (MVS and CMS) on page 112 for further information.

|
|
|

Class loading attributes determine the load-time placement of segments in virtual

storage. Loadable segments are loaded as separately relocated non-contiguous
entities at different origin addresses.

|
|
|
|
|

Default Class Assignments

High Level Assembler provides compatible behavior with load module model
object files generated when the NOGOFF option is active. When the GOFF option
is specified, the assembler automatically follows each CSECT, RSECT, and START
statement by defining two classes: B_TEXT and B_PRV.

|
|
|
|
|
|

B_TEXT contains the machine language text associated with the section name,
and is assigned the RMODE of the section name. The section name is
assigned to an entry point at the origin of the class. If a subsequent CATTR
statement declares a class name before any other statements have defined
storage, the element defined by the section name and the B_TEXT class name
will be empty.

|
|
|
|

B_PRV contains any external dummy sections defined by DXD instructions, or by

DSECTs named in Q-type address constants. If none are defined, the
elements in this class will be empty. (PRV is the binder's term for a Pseudo
Register Vector, the cumulative collection of external dummy sections.)

|
|

High Level Assembler assigns the name of the section as an entry name at the
initial byte of B_TEXT, and assigns to it the AMODE of the section name.

|
|
|

These two classes are bound in the same way as ordinary control sections and
dummy external sections are bound in the load module model, and can be used to
generate a load module if certain restrictions are satisfied.

HLASM V1R5 Language Reference

|
|
|
|
|
|

You may declare other classes in addition to the defaults, but the resulting program
object will not be convertible to a load module.

Parts (MVS and CMS)

Parts are the smallest externally named and independently relocatable subdivisions
of elements in a merge class. A class containing parts may contain only parts, and
a class containing anything other than parts may not contain any parts.

ENTRY statements may not define an entry point in a part.

|
|
|
|
|
|

You define a part with the CATTR instruction, which must follow the initiation of an
executable section. The name of the class to which the part belongs is provided in
the name entry of the CATTR instruction, and the name of the part is specified as
an operand. The first definition of a class name may also specify the attributes of
the class. (See CATTR Instruction (MVS and CMS) on page 112 for further
information.)

For example, suppose you define two parts in a class:

|
|
|
|
|
|
|

SECT_B
PClass

|
|
|
|

These statements define a merge class PClass containing two parts, Part_R and
Part_S. If other classes or other object files declare parts with the same names in
the same class, the binder will merge their contents to determine the final part
definition in the program object.

|
|
|
|

You may provide additional statements for a part by specifying a CATTR statement
with the class name in the name entry and the part name specified as the operand.
No other class attributes may be specified following the first CATTR statement
declaring the class.

|
|
|
|
|
|

Parts are automatically assigned a merge attribute, meaning that more than one
identically named part may appear in a class defined in other assemblies or
compilations. The binder will assign the longest length and strictest alignment of all
such identically-named parts, and will merge the machine language text
contributions of each to form the final text belonging to that part. The order of text
merging depends on the sequence of parts processing by the binder.

|
|

Note: During linking, parts may be arranged in any order, depending on their
priority attribute. Do not assume any ordering relationship among parts.

PClass
PClass

CSECT
CATTR
- - CATTR
- - CATTR
- - -

,
Define section SECT_B
Part(Part_R),RMODE(ANY) Define class PClass, part Part_R
Statements included in Part_R
Part(Part_S) Define part Part_S in class PClass
Statements included in Part_S
Part(Part_R) Resume class PClass and part Part_R
More statements included in Part_R

Location Counter Setting

|
|
|
|
|
|

The assembler maintains a separate location counter for each section, element,
and part. The location counter setting for the first section starts at 0, except when
an initial section is started with a START instruction that specifies a nonzero
location counter value. The location values assigned to the instructions and other
data in a section, element, or part are, therefore, relative to the location counter
setting at the beginning of that section, element, or part.

Chapter 3. Program Structures and Addressing

|
|

For executable sections, the location values that appear in the listings depend on
the THREAD option:

|
|
|

If you specify NOTHREAD, the location counter values for each section,
element, or part restart at 0, except possibly those associated with a first
section initiated by a START instruction with a nonzero address.

|
|
|

If you specify THREAD, location counter values do not restart at 0 for each
subsequent section, element, or part. They continue, after suitable alignment,
from the end of the previous section, element, or part.
For reference control sections, the location values that appear in the listings always
start from 0.
You can continue a control section, element, or part that has been discontinued
and, thereby, intersperse code sequences from different control sections, elements,
or parts. Note that the location values that appear in the listings for such
discontiguous sequences are divided into segments that follow from the end of one
segment to the beginning of the subsequent segment.
The location values, listed for the next defined control section, element, or part,
begin after the last location value assigned to the preceding such item.
On VSE, or when you specify the NOGOFF assembler option on MVS and CMS,
the maximum value of the location counter and the maximum length of a control
section is 2241, or X'FFFFFF' bytes. If LIST(133) is in force, then the high-order
is shown as zero.

|
|

When you specify the GOFF assembler option, the maximum value of
the location counter and the maximum length of an element or part is 2311, or
X'7FFFFFFF' bytes.

Location Counter and Length Limits

|
|
|

The assembler also maintains a length counter for each individually relocatable
component of the program: executable and reference control sections, elements,
and parts.

|
|

If any location counter overflows its maximum value, High Level Assembler issues
the severe error message:

ASMA39S Location counter error

|
|

and continues assembling with the location counter value wrapping around to
zero.

|
|
|
|
|

The length of a section, element, or part cannot exceed the maximum allowed
length described above. If the length counter reaches this maximum value, it stays
fixed at that value without an error condition or error message. Exceeding the
length counter will cause overflow of the location counter, producing the ASMA39S
message.

|
|
|
|
|

The location counter setting is relative to the beginning of the location it represents,
and the length counter represents the cumulative length of the control section. This
means that the length counter is nearly always greater than the location counter,
and can exceed its maximum value before the location counter. Even if the
location counter overflows, the length counter value may be correct, and

HLASM V1R5 Language Reference

Addressing

|
|

reassembling with the NOTHREAD option may avoid the location counter overflow
condition.

Use of Multiple Location Counters

High Level Assembler lets you use multiple location counters for each individual
control section. Use the LOCTR instruction (see LOCTR Instruction on page 191)
to assign different location counters to different parts of a control section. The
assembler then rearranges and assembles the coding together, according to the
different location counters you have specified: all coding using the first location
counter is assembled together, then the coding using the second location counter is
assembled together, and so forth.
An example of the use of multiple location counters is shown in Figure 19. In the
example, executable instructions and data areas have been interspersed
throughout the coding in their logical sequence, each group of instructions
preceded by a LOCTR instruction identifying the location counter under which it is
to be assembled. The assembler rearranges the control section so that the
executable instructions are grouped together and the data areas are grouped
together. Symbols are not resolved in the order they appear in the source
program, but in location counter sequence.
SOURCE MODULE

LINKED MODULE
(shown in source code format)

INST
CSECT

LR
12,15

LR
12,15

USING INST,12

USING INST,12

.

TM
CODE,X'3'

DATA
LOCTR

BM
NEWREC

INPUTREC DS
CL8

RECCODE DS
CL1

INST
LOCTR

TM
CODE,X'3'

BM
NEWREC

INPUTREC DS
CL8

RECCODE DS
CL1

DATA
LOCTR

VAL1
DC
F'56'
VAL1
DC
F'56'

VAL2
DC
F'84'
VAL2
DC
F'84'

NEXT
CSECT

controlled
by INST
location
counter

controlled
by DATA
location
counter

control
section

INST

control
section
NEXT

Figure 19. Use of Multiple Location Counters

|
|

The interactions of the LOCTR instruction with sections, classes, and parts is
described at LOCTR Instruction on page 191.

Addressing
This part of the chapter describes the techniques and introduces the instructions
that let you use symbolic addresses when referring to instructions and data. You
can address code and data that is defined within the same source module, or code
and data that is defined in another source module. Symbolic addresses are more
meaningful and easier to use than the corresponding object code addresses
required for machine instructions. The assembler can convert the symbolic
addresses you specify into their object code form.

Chapter 3. Program Structures and Addressing

Addressing

The System/390 and z/Architecture architectures have two ways of resolving

addresses in your program, depending on the machine instruction type:
base-displacement, where the address is computed by adding the
displacement to the contents of a base register.
relative-immediate, where the address is computed by adding 2 the signed
immediate operand field to the instruction's address (refer to RI Format on
page 91 and RSI Format on page 95).

Addressing within Source Modules: Establishing Addressability

You can use symbolic addresses in machine instructions and certain assembler
instructions. This is much easier than explicitly coding the addresses in the form
required by the hardware. Symbolic addresses you code in the instruction
operands are implicit addresses, and addresses in which you specify the
base-displacement or intermediate form are explicit addresses.
The assembler converts your implicit addresses into the explicit addresses required
for the assembled object code of the machine instruction. However, for
base-displacement operands, you must first establish addressability, as described
below.
Base Address Definition: The term base address is used throughout this manual
to mean the location counter value within a control section, element, or part from
which the assembler can compute displacements to locations, or addresses. The
base address need not always be the storage address of a control section,
element, or part when it is loaded into storage at execution time.

How to Establish Addressability

To establish the addressability of a control section, element, or part (see Sections,
Elements, and Parts on page 52), you must:
Specify a base address from which the assembler can compute displacements
to the addresses within the control section, element, or part.
Assign the base registers to contain the base addresses.
Write the instructions that load the base registers with the base addresses.
The following example shows the base address at MYPROG, that is assigned by
register 12. Register 12 is loaded with the value in register 15, which by convention
usually contains the storage address (set by the operating system) of the control
section (CSECT) when the program is loaded into storage at execution time.
MYPROG

CSECT
USING MYPROG,12
LR
12,15

The base address

Assign the base register
Load the base address

Similarly, you can use a BASR or similar instruction to put the address of the
following instruction into register 12.
BASR 12,
USING ,12
The USING instruction indicates that register 12 may be used as a base register
containing that address.

HLASM V1R5 Language Reference

Addressing

During assembly, the implicit addresses you code are converted into their explicit
base-displacement form; then, they are assembled into the object code of the
machine instructions in which they have been coded.
During execution, the base address is loaded into the base register.
|
|
|

If you specify multiple classes, you must provide addressability for

each element. For example, suppose you define two classes that must reference
positions in the other:

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

MYPROG
CLASS_A

|
|
|
|

A class specifying the deferred load (DEFLOAD) attribute on its defining CATTR
statement cannot be referenced from other classes using A-type or V-type address
constants. However, A-type and V-type address constants may be used within a
deferred-load class to refer to locations within that class.

|
|
|
|

The loading service for deferred-load classes will provide the origin address of the
deferred-load segment containing the classes. You can then use Q-type address
constants in other classes to calculate the addresses of items in the loaded
classes. For example:

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

MYPROG
CLASS_A

ADATA
Addr_B
CLASS_B

BDATA
Addr_A

CSECT
CATTR
BASR
USING
- - L
USING
- - DS
DC
- - CATTR
BASR
USING
- - L
USING
- - DS
DC

,
RMODE(24)
12,
,12

Define class CLASS_A

Local base register
Addressability for this element

1,Addr_B
BDATA,1

Address of BDATA in CLASS_B

F
A(BDATA)

Data in CLASS_A

RMODE(31)
11,
,11

Define class CLASS_B

Local base register
Addressability for this element

2,Addr_A
ADATA,2

Address of ADATA in CLASS_A

D
A(ADATA)

Data in CLASS_B

CSECT ,
CATTR RMODE(31)
BASR 12,
Set base register
USING ,12
Addressability for this element
- - Address of CLASS_B segment assumed to be returned in register 8
- - A
8,BDATAOff
Add offset of BDATA in CLASS_B
USING BDATA,8
- - BDATAOff DC
Q(BDATA)
Offset of BDATA
- - CLASS_B CATTR DEFLOAD,RMODE(ANY) Define deferred-load class
- - BDATA
DS
F
Data in deferred-load class

Chapter 3. Program Structures and Addressing

Addressing

|
|
|
|

Parts must always be referenced using Q-type address constants using the
techniques shown in this example, whether or not they reside in deferred load
classes. This is because parts are subject to reordering during binding.

Base Register Instructions

The USING and DROP assembler instructions enable you to use expressions
representing implicit addresses as operands of machine instruction statements,
leaving the assignment of base registers and the calculation of displacements to
the assembler.
In order to use symbols in implicit addresses in the operand field of machine
instruction statements, you must:
Code a USING instruction to assign one or more base registers to a base
address or sequence of base addresses
Code machine instructions to load each base register with the base address
Having the assembler determine base registers and displacements relieves you of
the need to separate each address into an explicit displacement value and an
explicit base register value. This feature of the assembler eliminates a likely source
of programming errors, thus reducing the time required to write and test programs.
You use the USING and DROP instructions to take advantage of this feature. For
information about how to use these instructions, see USING Instruction on page
218 and DROP Instruction on page 172.

Qualified Addressing
Qualified addressing lets you use the same symbol to refer to data in different
storage locations. Qualified symbols are simply ordinary symbols prefixed by a
symbol qualifier and a period. A symbol qualifier is used to specify which base
register the assembler should use when converting an implicit address into its
explicit base-displacement form. Before you use a symbol qualifier, you must have
previously defined it in the name entry of a labeled USING instruction. For
information about labeled USING instructions, see USING Instruction on
page 218. When defined, you can use a symbol qualifier to qualify any symbol
that names a storage location within the range of the labeled USING. Qualified
symbols may be used anywhere a relocatable term may be used.
The following examples show the use of qualified symbols. SOURCE and TARGET are
both symbol qualifiers previously defined in two labeled USING instructions. X and
Y are both symbols that name storage locations within the range of both labeled
USING instructions.
MVC
MVC
XC
LA

HLASM V1R5 Language Reference

TARGET.X,SOURCE.X
TARGET.Y+5(3),SOURCE.Y+5
TARGET.X+1(L'X-1),TARGET.X+1
2,SOURCE.Y

Addressing

Dependent Addressing
Dependent addressing lets you minimize the number of base registers required to
refer to data by making greater use of established addressability. For example, you
may want to describe the format of a table of data defined in your source module
with a dummy control section (see Dummy Control Sections on page 56). To
refer to the data in the table using the symbols defined in the dummy section, you
need to establish the addressability of the dummy section. To do this you must:
Code a USING instruction to assign one or more base registers to a base
address
Code machine instructions to load each base register with the base address
However, dependent addressing offers an alternative means of establishing
addressability of the dummy section.
When you have established addressability of the control section in which the table
is defined, you can establish addressability of the dummy section by simply coding
a USING statement which specifies the name of the dummy section and the
address of the table. When you subsequently refer to the symbols in the dummy
section, the assembler makes use of the already established addressability of the
control section when converting the symbolic addresses into their
base-displacement form.
|
|

For example, suppose addressability has been established for a control section
containing a data structure that is mapped by a dummy control section:

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

DATAMAP
FIELD1
FIELD2
FIELD3

DSECT
DS
DS
DS
- - CODE
CSECT
BASR
USING
- - USING
L
LA
- - REALDATA DS
DATA1
DC
DATA2
DC
DATA3
DC

,
F
CL32
CL24

DSECT describing data structure

,
12,
,12

Program code
Set base register
Provide addressability

DATAMAP,REALDATA
2,FIELD1
3,FIELD3

Map DSECT onto REALDATA

F
Data mapped by DATAMAP
F'32'
CL32'Actual Data'
CL24'Additional Data'

Relative Addressing
Relative addressing is the technique of addressing instructions and data areas by
designating their location in relation to the location counter or to some symbolic
location. This type of addressing is always in bytesnever in bits, words, or
instructions. Thus, the expression +4 specifies an address that is 4 bytes greater
than the current value of the location counter. In the sequence of instructions in
the following example, the location of the CR machine instruction can be expressed
in two ways, ALPHA+2, or BETA-4, because all the machine instructions in the
example are for 2-byte instructions.

Chapter 3. Program Structures and Addressing

Addressing

ALPHA

BETA

LR
CR
BCR
AR

3,4
4,6
1,14
2,3

Literal Pools
Literals, collected into pools by the assembler, are assembled as part of the
executable control section to which the pools belong. If a LTORG instruction is
specified at the end of each control section or element, the literals specified for that
section or element are assembled into the pool starting at the LTORG instruction.
If no LTORG instruction is specified, a literal pool containing all the literals used in
the whole source module is assembled at the end of the first control section or at
the end of the B_TEXT class belonging to the first section. This literal pool appears
in the listings after the END instruction. For more information about the LTORG
instruction, see LTORG Instruction on page 193.

|
|

Independently Addressed Segments: If any control section is divided into

independently addressed segments, a LTORG instruction should be specified at the
end of each segment to create a separate literal pool for that segment.

Establishing Residence and Addressing Mode

The AMODE and RMODE instructions specify the addressing mode (AMODE) and
the residence mode (RMODE) to be associated with control sections in the object
deck. These modes may be specified for the following types of control sections:
Control section (for example START, CSECT)
Unnamed control section
Common control section (COM instruction)
The assembler sets the AMODE and RMODE indicators in the ESD record for each
applicable control section in an assembly. The linker stores the AMODE and
RMODE values in the load module. They are subsequently used by the loader
program that brings the load module into storage. The loader program uses the
RMODE value to determine where it loads the load module, and passes the
AMODE value to the operating system to establish the addressing mode.
|
|
|
|
|
|

When you specify the GOFF option, the RMODE value specified for a
section is by default assigned to the B_TEXT class, and the AMODE specified for the
section is assigned to an entry point having the section name and the location of
the first byte of class B_TEXT. If the source program defines additional classes,
each class may be assigned its own RMODE, and an entry point in any class may
be assigned its own AMODE.
For more information about the AMODE and RMODE instructions, see AMODE
Instruction on page 110 and RMODE Instruction on page 211.

Symbolic Linkages
Symbols can be defined in one module and referred to in another, which results in
symbolic linkages between independently assembled program sections. These
linkages can be made only if the assembler can provide information about the
linkage symbols to the linker, which resolves the linkage references at link-edit
time.

HLASM V1R5 Language Reference

Addressing

Establishing symbolic linkage

You must establish symbolic linkage between source modules so that you can refer
to or branch to symbolic locations defined in the control sections of external source
modules. You do this by using external symbol definitions, and external symbol
references. To establish symbolic linkage with an external source module, you
must do the following:
In the current source module, you must identify the symbols that are not
defined in that source module, if you want to use them in instruction operands.
These symbols are called external symbols, because they are defined in
another (external) source module. You identify external symbols in the EXTRN
or WXTRN instruction, or the V-type address constant. For more information
about the EXTRN and WXTRN instructions, see EXTRN Instruction on
page 189 and WXTRN Instruction on page 229.
In the external source modules, you must identify the symbols that are defined
in those source modules, and that you refer to from the current source module.
The two types of definitions that you can use are control section names
(defined by the CSECT, RSECT, and START instructions), and entry symbols.
Entry symbols are so called because they provide points of entry to a control
section in a source module. You identify entry symbols with the ENTRY
instruction. For more information about the ENTRY instruction, see ENTRY
Instruction on page 183.
To reference the external symbols, you must either

|
|

provide the A-type or V-type address constants needed by the assembler to

reserve storage for the addresses represented by the external symbols, or
reference an external symbol in the same class in a relative branch
instruction.
The assembler places information about entry and external symbols in the external
symbol dictionary. The linker uses this information to resolve the linkage addresses
identified by the entry and external symbols.

Referring to external data

Use the EXTRN instruction to identify the external symbol that represents data in
an external source module, if you want to refer to this data symbolically.
For example, you can identify the address of a data area as an external symbol
and load the A-type address constant specifying this symbol into a base register.
Then, you use this base register when establishing the addressability of a dummy
section that describes this external data. You can now refer symbolically to the
data that the external area contains.
You must also identify, in the source module that contains the data area, the
address of the data as an entry symbol.

Branching to an external address

Use the V-type address constant to identify the external symbol that represents the
address in an external source module that you want to branch to.
For example, you can load into a register the V-type address constant that
identifies the external symbol. Using this register, you can then branch to the
external address represented by the symbol.

Chapter 3. Program Structures and Addressing

Addressing

If the symbol is the name entry of a START, CSECT, or RSECT instruction in the
other source module, and thus names an executable control section, it is
automatically identified as an entry symbol. If the symbol represents an address in
the middle of a control section, you must identify it as an entry symbol for the
external source module.
You can also use a combination of an EXTRN instruction to identify, and an A-type
address constant to contain, the external branch address. However, the V-type
address constant is more convenient because:
You do not have to use an EXTRN instruction.
The external symbol you specify, can be used in the name entry of any other
statement in the same source program.
|
|
|
|

It will work correctly even if the program is linked as an overlay module, so long
as the reference is not to a symbol in an exclusive segment. See z/OS MVS
Program Management: User's Guide and Reference, SA22-7643 for further
information.
The following example shows how you use an A-type address constant to contain
the address of an external symbol that you identify in an EXTRN instruction. You
cannot use the external symbol name EXMOD1 in the name entry of any other
statement in the source program.

EX_SYM

.
.
L
BASR
.
.
DC
EXTRN
.
.

15,EX_SYM
14,15

Load address of external symbol

Branch to it

A(EXMOD1)
EXMOD1

Address of external symbol

Identify EXMOD1 as external symbol

The following example shows how you use the symbol EXMOD1 as both the name of
an external symbol and a name entry on another statement.

EXMOD1

EX_SYM

.
.
L
BASR
.
.
DS
.
.
DC
.
.

15,EX_SYM
14,15

Load address of external symbol

Branch to it

Using EXMOD1 as a name entry

V(EXMOD1)

Address of external symbol

If the external symbol that represents the address to which you want to branch is to
be part of an overlay-structured module, you should identify it with a V-type address
constant, not with an EXTRN instruction and an A-type address constant. You can
use the supervisor CALL macro instruction to branch to the address represented by
the external symbol. The CALL macro instruction generates the necessary V-type
address constant.

HLASM V1R5 Language Reference

Addressing

|
|

You may branch to external symbols in the same class using relative
branch instructions.

|
|
|
|
|
|
|
|
|
|
|

MYPROG
CLASS_A

|
|

You may also use a relative branch instruction to branch to an externally defined
symbol:

|
|
|
|
|
|
|

MYPROG
MYCLASS

|
|

A separate source module must define the entry point TARGET in class MYCLASS.

HISPROG
CLASS_A
ENTRYB

CSECT
CATTR
- - BRAS
- - CSECT
CATTR
- - STM
- - END

CSECT
CATTR
EXTRN
- - BRAS
- - END

,
RMODE(31)

Define section MYPROG

Define class CLASS_A

14,ENTRYB

Branch to external symbol

,
RMODE(31)

Define section HISPROG

Define class CLASS_A

14,12,12(13)

Entry point referenced externally

,
RMODE(31)
TARGET

Define section MYPROG

Define class MYCLASS
Declare external symbol TARGET

14,TARGET

Branch to external symbol

Establishing an external symbol alias

You can instruct the assembler to use an alias for an external symbol in place of
the external symbol itself, when it generates the object module. To do this you
must code an ALIAS instruction which specifies the external symbol and the alias
you want the assembler to use. The external symbol must be defined in a START,
CSECT, RSECT, ENTRY, COM, DXD, external DSECT, EXTRN, or WXTRN
instruction, or in a V-type address constant.
The following example shows how you use the ALIAS instruction to specify an alias
for the external symbol EXMOD1.

EXMOD1

EX_SYM
EXMOD1

.
.
L
BASR
.
.
DS
.
.
DC
ALIAS
.
.

15,EX_SYM
14,15

Load address of external symbol

Branch to it

Using EXMOD1 as a name entry

V(EXMOD1)
C'XMD1PGM'

Address of external symbol

XMD1PGM is the real external name

See ALIAS Instruction on page 109 for information about the ALIAS instruction.

Chapter 3. Program Structures and Addressing

Addressing

External Symbol Dictionary Entries

For each section, class, part, entry, external symbol, and dummy external control
section, the assembler keeps a record of the following external symbol dictionary
(ESD) information:

Symbolic name, if one is specified

Type code
Individual identification number (ESDID)
Starting address
Length
Owning ESDID, if any
Symbol attributes
Alias, if one is specified

Figure 20 lists the assembler instructions that define control sections and dummy
control sections, classes and parts, or identify entry and external symbols, and tells
their associated type codes. You can define up to 65535 individual control sections
and external symbols in a source module if the NOGOFF option is specified, or up
to 999999 external symbols if the GOFF option is specified.
Figure 20. Defining External Symbols
Name Entry

Instruction

Coding Entered into External Symbol

Dictionary
NOGOFF option

GOFF option

If present

START, CSECT, or RSECT

SD, ED, LD

If omitted

START, CSECT, or RSECT

Instructiondependent

Any instruction that initiates

the unnamed section

Optional

COM

Optional

DSECT

None

Mandatory

DXD or external DSECT

Mandatory

CATTR

Not applicable

Mandatory

CATTR PART(name)

Not applicable

ENTRY

Not applicable

EXTRN

Not applicable

DC (V-type address constant) ER

Not applicable

WXTRN

Refer to Appendix C Object Deck Output in the HLASM Programmer's Guide,

SC26-4941 for details about the ESD entries produced when you specify the
NOGOFF assembler option.
Refer to z/OS MVS Program Management: Advanced Facilities,
SA22-7644 for details about the ESD entries produced when you specify the GOFF
assembler option.

HLASM V1R5 Language Reference

Addressing

|
|
|
|

Summary of Source and Object Program Structures

The differences between the load module model and the program object model,
and their interactions with assembler language instructions, are summarized in the
following table:

| Property

Load Module Model

Program Object Model

| Form of object program

One-dimensional module

Two-dimensional module

| Smallest indivisible independently

| relocatable component

Control section

Element and part

| Residence Mode

Only one

One per class

| Addressing Mode

Only one

One per entry point

| Compatibility
|

Can be converted to program

object

Can be converted to load module

with limitations

| Assembler Option

NOGOFF or GOFF

GOFF only

| Assembler statements
|

CSECT, RSECT, START

CSECT, RSECT, START, CATTR,

XATTR

| Assignable loadable-program
| attributes

RMODE

RMODE, alignment, load type

| External symbol types

SD/CM, LD, ER/WX, PR

SD, ED, LD, ER/WX, PR, PD

| External symbol maximum length

8 characters

256 characters

| External symbol scope

Module (WX), Library (ER)

Section, Module, Library,

Import/Export

| External symbol attributes

|
|

AMode, RMode

AMode, RMode, scope, PSect name,

linkage type, reference type,
extended attributes

| Object module record types

ESD, TXT, RLD, END, SYM

HDR, ESD, TXT, RLD, END, LEN

| Address constant types

A, V, Q, CXD

A, V, Q, J, R, CXD

| Binding attributes
|
|

Catenate (SD),
Merge-like (CM,PR)

Catenate (non-Merge classes),

Merge classes (Parts,
Pseudo-Registers)

| Text types
|

Byte stream

Byte stream, records (structured and

unstructured)

| Maximum contiguous text length

16MB

1GB

| Figure 21. Object Program Structure Comparison

Chapter 3. Program Structures and Addressing

Addressing

HLASM V1R5 Language Reference

Part 2. Machine and Assembler Instruction Statements

Chapter 4. Machine Instruction Statements . . . . . . . . . .

General Instructions . . . . . . . . . . . . . . . . . . . . . . . . . .
Decimal Instructions . . . . . . . . . . . . . . . . . . . . . . . . . .
Floating-Point Instructions . . . . . . . . . . . . . . . . . . . . . .
Control Instructions . . . . . . . . . . . . . . . . . . . . . . . . . .
Input/Output Operations . . . . . . . . . . . . . . . . . . . . . . .
Branching with Extended Mnemonic Codes . . . . . . . . . . . .
Alternative Mnemonics for some Branch Relative Instructions
Statement Formats . . . . . . . . . . . . . . . . . . . . . . . . . .
Symbolic Operation Codes . . . . . . . . . . . . . . . . . . . . . .
Operand Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Register Usage by Machine Instructions . . . . . . . . . . .
Register Usage by System . . . . . . . . . . . . . . . . . .
Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Implicit Address . . . . . . . . . . . . . . . . . . . . . . . . .
Explicit Address . . . . . . . . . . . . . . . . . . . . . . . . .
Relative Address . . . . . . . . . . . . . . . . . . . . . . . .
Relocatability of Addresses . . . . . . . . . . . . . . . . . .
Machine or Object Code Format . . . . . . . . . . . . . . .
Lengths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Immediate Data . . . . . . . . . . . . . . . . . . . . . . . . . .
Examples of Coded Machine Instructions . . . . . . . . . . . . .
RI Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RR Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RS Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RSI Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RX Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SI Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 5. Assembler Instruction Statements
64-bit Addressing Mode . . . . . . . . . . . . . .
*PROCESS Statement . . . . . . . . . . . . . . .
ACONTROL Instruction . . . . . . . . . . . . . . .
ADATA Instruction . . . . . . . . . . . . . . . . . .
AINSERT Instruction . . . . . . . . . . . . . . . .
ALIAS Instruction . . . . . . . . . . . . . . . . . .
AMODE Instruction . . . . . . . . . . . . . . . . .
CATTR Instruction (MVS and CMS) . . . . . . .
CCW and CCW0 Instructions . . . . . . . . . . .
CCW1 Instruction . . . . . . . . . . . . . . . . . .
CEJECT Instruction . . . . . . . . . . . . . . . . .
CNOP Instruction . . . . . . . . . . . . . . . . . .
COM Instruction . . . . . . . . . . . . . . . . . . .
COPY Instruction . . . . . . . . . . . . . . . . . .
CSECT Instruction . . . . . . . . . . . . . . . . .
CXD Instruction . . . . . . . . . . . . . . . . . . .
DC Instruction . . . . . . . . . . . . . . . . . . . .
Rules for DC Operand . . . . . . . . . . . . . .
Copyright IBM Corp. 1982, 2004

78
78
79
79
79
80
80
83
83
84
85
86
86
87
87
88
88
88
89
89
90
91
91
91
93
94
95
95
97
97
100
101
102
103
107
108
109
110
112
115
116
118
119
121
122
123
125
126
128

Part 2. Machine and Assembler Instruction Statements

General Information About Constants . . . . . . . . . . . . . . . . . .

Length Attribute Value of Symbols Naming Constants . . . . . . .
Alignment of Constants . . . . . . . . . . . . . . . . . . . . . . . .
Padding and Truncation of Values . . . . . . . . . . . . . . . . . . . .
Padding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subfield 1: Duplication Factor . . . . . . . . . . . . . . . . . . . . . .
Subfield 2: Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subfield 3: Type Extension . . . . . . . . . . . . . . . . . . . . . . . .
Subfield 4: Program type . . . . . . . . . . . . . . . . . . . . . . . . .
Subfield 5: Modifier . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Length Modifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scale Modifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exponent Modifier . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subfield 6: Nominal Value . . . . . . . . . . . . . . . . . . . . . . . .
Binary ConstantB . . . . . . . . . . . . . . . . . . . . . . . . . . .
Character ConstantC . . . . . . . . . . . . . . . . . . . . . . . .
Graphic ConstantG . . . . . . . . . . . . . . . . . . . . . . . . . .
Hexadecimal ConstantX . . . . . . . . . . . . . . . . . . . . . . .
Fixed-Point ConstantsF and H . . . . . . . . . . . . . . . . . . .
Decimal ConstantsP and Z . . . . . . . . . . . . . . . . . . . . .
Address Constants . . . . . . . . . . . . . . . . . . . . . . . . . . .
Offset ConstantQ . . . . . . . . . . . . . . . . . . . . . . . . . . .
Length ConstantJ . . . . . . . . . . . . . . . . . . . . . . . . . . .
PSECT ReferenceR . . . . . . . . . . . . . . . . . . . . . . . . .
Hexadecimal Floating-Point ConstantsE, EH, D, DH, L, LH, LQ
Binary Floating-Point ConstantsEB, DB, LB . . . . . . . . . . .
Floating-Point Special Values . . . . . . . . . . . . . . . . . . . . .
Literal Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DROP Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DS Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Use the DS Instruction . . . . . . . . . . . . . . . . . . . .
DSECT Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DXD Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EJECT Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
END Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ENTRY Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EQU Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Conditional Assembly Values . . . . . . . . . . . . . . . . . . .
EXITCTL Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXTRN Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ICTL Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISEQ Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOCTR Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LTORG Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Literal Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Addressing Considerations . . . . . . . . . . . . . . . . . . . . . . . .
Duplicate Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MNOTE Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OPSYN Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Redefining Conditional Assembly Instructions . . . . . . . . . . . .
ORG Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
POP Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PRINT Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

HLASM V1R5 Language Reference

129
129
129
130
131
132
132
133
134
135
136
136
138
139
140
141
142
145
147
148
151
153
159
160
160
161
167
170
171
172
174
176
178
180
181
182
183
184
187
187
189
189
190
191
193
194
195
195
196
198
200
200
204
204

Part 2. Machine and Assembler Instruction Statements

Process Statement . . . . . . . . . . . . . . . . . . . . . .
PUNCH Instruction . . . . . . . . . . . . . . . . . . . . . .
PUSH Instruction . . . . . . . . . . . . . . . . . . . . . . .
REPRO Instruction . . . . . . . . . . . . . . . . . . . . . .
RMODE Instruction . . . . . . . . . . . . . . . . . . . . . .
RSECT Instruction . . . . . . . . . . . . . . . . . . . . . .
SPACE Instruction . . . . . . . . . . . . . . . . . . . . . .
START Instruction . . . . . . . . . . . . . . . . . . . . . . .
TITLE Instruction . . . . . . . . . . . . . . . . . . . . . . .
Deck ID in Object Records . . . . . . . . . . . . . .
Printing the Heading . . . . . . . . . . . . . . . . . .
Printing the TITLE Statement . . . . . . . . . . . . .
Sample Program Using the TITLE Instruction . . . .
Page Ejects . . . . . . . . . . . . . . . . . . . . . . .
Valid Characters . . . . . . . . . . . . . . . . . . . .
USING Instruction . . . . . . . . . . . . . . . . . . . . . . .
How to Use the USING Instruction . . . . . . . . . . .
Base Registers for Absolute Addresses . . . . . . . . .
Ordinary USING Instruction . . . . . . . . . . . . . . . .
Range of an Ordinary USING Instruction . . . . . .
Domain of an Ordinary USING Instruction . . . . . .
Labeled USING Instruction . . . . . . . . . . . . . . . .
Range of a Labeled USING Instruction . . . . . . .
Domain of a Labeled USING Instruction . . . . . . .
Dependent USING Instruction . . . . . . . . . . . . . .
Range of a Dependent USING Instruction . . . . . .
Domain of a Dependent USING Instruction . . . . .
WXTRN Instruction . . . . . . . . . . . . . . . . . . . . . .
XATTR Instruction (MVS and CMS) . . . . . . . . . . . .
Association of Code and Data Areas (MVS and CMS)

. . . . . . . . . . . . .

208
208
209
210
211
212
213
214
215
215
216
216
216
217
217
218
219
220
220
222
223
223
225
226
226
228
228
229
230
232

Part 2. Machine and Assembler Instruction Statements

General Instructions

Chapter 4. Machine Instruction Statements

This chapter introduces a sample of the more common instruction formats and
provides general rules for coding them in their symbolic assembler language
format.
For the complete specifications of machine instructions, their object code format,
their coding specifications, and their use of registers and virtual storage areas, see
the applicable Principles of Operation manual for your processor. If your program
requires vector facility instructions, see the applicable Vector Operations manual for
the complete specifications of vector-facility instructions.
At assembly time, the assembler converts the symbolic assembler language
representation of the machine instructions to the corresponding object code. The
computer processes this object code at execution time. Thus, the functions
described in this section can be called execution-time functions.
Also at assembly time, the assembler creates the object code of the data constants
and reserves storage for the areas you specify in your data definition assembler
instructions, such as DC and DS (see Chapter 5, Assembler Instruction
Statements). At execution time, the machine instructions can refer to these
constants and areas, but the constants themselves are not normally processed.
As defined in the applicable Principles of Operation manual, there are five
categories of machine instructions:

General instructions
Decimal instructions
Floating-Point instructions
Control instructions
Input/Output operations

Each is discussed in the following sections.

General Instructions
Use general instructions to manipulate data that resides in general registers or in
storage, or that is introduced from the instruction stream. General instructions
include fixed-point, logical, and branching instructions. In addition, they include
unprivileged status-switching instructions. Some general instructions operate on
data that resides in the PSW or the TOD clock.
The general instructions treat data as four types: signed binary integers, unsigned
binary integers, unstructured logical data, and decimal data. Data is treated as
decimal by the conversion, packing, and unpacking instructions.
For further information, see General Instructions in the applicable Principles of
Operation manual.

Copyright IBM Corp. 1982, 2004

Decimal Instructions

Decimal Instructions
Use the decimal instructions when you want to do arithmetic and editing operations
on data that has the binary equivalent of decimal representation.
Decimal data may be represented in either zoned or packed format. In the zoned
format, the rightmost four bits of a byte are called the numeric bits and normally
consist of a code representing a decimal digit. The leftmost four bits of a byte are
called the zone bits, except for the rightmost byte of a decimal operand, where
these bits may be treated either as a zone or as a sign.
In the packed format, each byte contains two decimal digits, except for the
rightmost byte, which contains a sign to the right of a decimal digit.
Decimal instructions treat all numbers as integers. For example, 3.14, 31.4, and
314 are all processed as 314. You must keep track of the decimal point yourself.
The integer and scale attributes discussed in Data Attributes on page 324 can
help you do this.
Additional operations on decimal data are provided by several of the instructions in
General Instructions in the applicable Principles of Operation manual. Decimal
operands always reside in storage.
For further information, see Decimal Instructions in the applicable Principles of
Operation manual.

Floating-Point Instructions
Use floating-point instructions when you want to do arithmetic operations on data in
the floating-point representation. Thus, you do not have to keep track of the
decimal point in your computations. Floating-point instructions also let you do
arithmetic operations on both very large numbers and very small numbers, usually
providing greater precision than fixed-point decimal instructions.
For further information, see Floating-Point Instructions in the applicable Principles
of Operation manual.

Control Instructions
Control instructions include all privileged and semiprivileged machine instructions,
except the input/output instructions described on page 80.
Privileged instructions may be processed only when the processor is in the
supervisor state. An attempt to process an installed privileged instruction in the
problem state generates a privileged-operation exception.
Semiprivileged instructions are those instructions that can be processed in the
problem state when certain authority requirements are met. An attempt to process
an installed semiprivileged instruction in the problem state when the authority
requirements are not met generates a privileged-operation exception or some other
program-interruption condition depending on the particular requirement that is
violated.

Chapter 4. Machine Instruction Statements

Input/Output Operations

For further details, see Control Instructions in the applicable Principles of

Operation manual.

Input/Output Operations
Use the input/output instructions (instead of the IBM-supplied system macro
instructions) when you want to control your input and output operations more
closely.
The input or output instructions let you identify the channel or the device on which
the input or output operation is to be done. For information about how and when
you can use these instructions, see the applicable system manual.
For more information, see Input/Output Operations in the applicable Principles of
Operation manual and the applicable system manuals.

Branching with Extended Mnemonic Codes

Branch instructions let you specify an extended mnemonic code for the condition on
which a branch is to occur. Thus, you avoid having to specify the mask value, that
represents the condition code, required by the BC, BCR, and BRC machine
instructions. The assembler translates the extended mnemonic code into the mask
value, and then assembles it into the object code of the BC, BCR, or BRC machine
instruction.
|
|
|
|

The extended branch mnemonics for the BC instruction require a base register; the
extended mnemonics for the BCR and BRC instructions do not. The extended
mnemonics for the BRC instruction begin with the letter J, and are sometimes
called Jump instructions, as indicated in Figure 22.
The extended mnemonic codes are given in Figure 22 on page 81. They can be
used as operation codes for branching instructions, replacing the BC, BCR, and
BRC machine instruction codes (see 1 in Figure 22). Note that the first operand
(see 2 in Figure 22) of the BC, BCR, and BRC instructions must not be present
in the operand field (see 3 in Figure 22) of the extended mnemonic branching
instructions.

HLASM V1R5 Language Reference

Branching with Extended Mnemonic Codes

Extended Code

(Symbolic) Machine
Instruction Equivalent

3
4

B
D(X,B)
BR
R
J
label
NOP
D(X,B)
NOPR
R
JNOP
label

Meaning

Unconditional Branch
Unconditional Jump
No Operation

Format

RX
RR
RI
RX
RR
RI

BC
BCR
BRC
BC
BCR
BRC

2

15,D(X,B)
15,R
15,label
,D(X,B)
,R
,label

RX
RR
RI
RX
RR
RI
RX
RR
RI
RX
RR
RI
RX
RR
RI
RX
RR
RI

BC
BCR
BRC
BC
BCR
BRC
BC
BCR
BRC
BC
BCR
BRC
BC
BCR
BRC
BC
BCR
BRC

2,D(X,B)
2,R
2,label
4,D(X,B)
4,R
4,label
8,D(X,B)
8,R
8,label
13,D(X,B)
13,R
13,label
11,D(X,B)
11,R
11,label
7,D(X,B)
7,R
7,label

RX
RR
RI
RX
RR
RI
RX
RR
RI
RX
RR
RI
RX
RR
RI
RX
RR
RI
RX
RR
RI
RX
RR
RI

BC
BCR
BRC
BC
BCR
BRC
BC
BCR
BRC
BC
BCR
BRC
BC
BCR
BRC
BC
BCR
BRC
BC
BCR
BRC
BC
BCR
BRC

2,D(X,B)
2,R
2,label
4,D(X,B)
4,R
4,label
8,D(X,B)
8,R
8,label
1,D(X,B)
1,R
1,label
13,D(X,B)
13,R
13,label
11,D(X,B)
11,R
11,label
7,D(X,B)
7,R
7,label
14,D(X,B)
14,R
14,label

Used After Compare Instructions

BH
BHR
JH
BL
BLR
JL
BE
BER
JE
BNH
BNHR
JNH
BNL
BNLR
JNL
BNE
BNER
JNE

D(X,B)
R
label
D(X,B)
R
label
D(X,B)
R
label
D(X,B)
R
label
D(X,B)
R
label
D(X,B)
R
label

Branch on High
Jump on High
Branch on Low
Jump on Low
Branch on Equal
Jump on Equal
Branch on Not High
Jump on Not High
Branch on Not Low
Jump on Not Low
Branch on Not Equal
Jump on Not Equal

Used After Arithmetic Instructions

BP
BPR
JP
BM
BMR
JM
BZ
BZR
JZ
BO
BOR
JO
BNP
BNPR
JNP
BNM
BNMR
JNM
BNZ
BNZR
JNZ
BNO
BNOR
JNO

D(X,B)
R
label
D(X,B)
R
label
D(X,B)
R
label
D(X,B)
R
label
D(X,B)
R
label
D(X,B)
R
label
D(X,B)
R
label
D(X,B)
R
label

Branch on Plus
Jump on Plus
Branch on Minus
Jump on Minus
Branch on Zero
Jump on Zero
Branch on Overflow
Jump on Overflow
Branch on Not Plus
Jump on Not Plus
Branch on Not Minus
Jump on Not Minus
Branch on Not Zero
Jump on Not Minus
Branch on No Overflow
Jump on No Overflow

Figure 22 (Part 1 of 3). Extended Mnemonic Codes

Chapter 4. Machine Instruction Statements

Branching with Extended Mnemonic Codes

Used After Test Under Mask Instructions

BO
BOR
BM
BMR
BZ
BZR
BNO
BNOR
BNM
BNMR
BNZ
BNZR

D(X,B)
R
D(X,B)
R
D(X,B)
R
D(X,B)
R
D(X,B)
R
D(X,B)
R

Branch if Ones
Branch if Mixed
Branch if Zero
Branch if Not Ones
Branch if Not Mixed
Branch if Not Zero

RX
RR
RX
RR
RX
RR
RX
RR
RX
RR
RX
RR

BC
BCR
BC
BCR
BC
BCR
BC
BCR
BC
BCR
BC
BCR

1,D(X,B)
1,R
4,D(X,B)
4,R
8,D(X,B)
8,R
14,D(X,B)
14,R
11,D(X,B)
11,R
7,D(X,B)
7,R

Branch Relative on Condition Long

BRUL

label

Unconditional Br Rel Long

RIL

BRCL

15,label

|
|
|
|
|
|

BRHL
BRLL
BREL
BRNHL
BRNLL
BRNEL

label
label
label
label
label
label

Br
Br
Br
Br
Br
Br

Rel
Rel
Rel
Rel
Rel
Rel

Long
Long
Long
Long
Long
Long

on
on
on
on
on
on

High
Low
Equal
Not High
Not Low
Not Equal

RIL
RIL
RIL
RIL
RIL
RIL

BRCL
BRCL
BRCL
BRCL
BRCL
BRCL

2,label
4,label
8,label
13,label
11,label
7,label

|
|
|
|
|
|
|
|

BRPL
BRML
BRZL
BROL
BRNPL
BRNML
BRNZL
BRNOL

label
label
label
label
label
label
label
label

Br
Br
Br
Br
Br
Br
Br
Br

Rel
Rel
Rel
Rel
Rel
Rel
Rel
Rel

Long
Long
Long
Long
Long
Long
Long
Long

on
on
on
on
on
on
on
on

Plus
Minus
Zero
Overflow
Not Plus
Not Minus
Not Zero
Not Overflow

RIL
RIL
RIL
RIL
RIL
RIL
RIL
RIL

BRCL
BRCL
BRCL
BRCL
BRCL
BRCL
BRCL
BRCL

2,label
4,label
8,label
1,label
13,label
11,label
7,label
14,label

Branch Relative on Condition

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

BRO
BRP
BRH
BRL
BRM
BRNE
BRNZ
BRE
BRZ
BRNL
BRNM
BRNH
BRNP
BRNO
BRU

RI
RI
RI
RI
RI
RI
RI
RI
RI
RI
RI
RI
RI
RI
RI

BRC
BRC
BRC
BRC
BRC
BRC
BRC
BRC
BRC
BRC
BRC
BRC
BRC
BRC
BRC

1,label
2,label
2,label
4,label
4,label
7,label
7,label
8,label
8,label
11,label
11,label
13,label
13,label
14,label
15,label

label
label
label
label
label
label
label
label
label
label
label
label
label
label
label

Branch on Overflow
Branch on Plus
Branch on High
Branch on Low
Branch on Minus
Branch on Not Equal
Branch on Not Minus
Branch on Equal
Branch on Zero
Branch on Not Low
Branch on Not Minus
Branch on Not High
Branch on Not Plus
Branch on No Overflow
Unconditional Branch

Figure 22 (Part 2 of 3). Extended Mnemonic Codes

HLASM V1R5 Language Reference

Alternative Mnemonics for some Branch Relative Instructions

Jump on Condition Long

JLU
JLNOP

label
label

Unconditional Jump Long

No operation

RIL
RIL

BRCL
BRCL

15,label
,label

JLH
JLL
JLE
JLNH
JLNL
JLNE

label
label
label
label
label
label

Jump
Jump
Jump
Jump
Jump
Jump

Long
Long
Long
Long
Long
Long

on
on
on
on
on
on

High
Low
Equal
Not High
Not Low
Not Equal

RIL
RIL
RIL
RIL
RIL
RIL

BRCL
BRCL
BRCL
BRCL
BRCL
BRCL

2,label
4,label
8,label
13,label
11,label
7,label

JLP
JLM
JLZ
JLO
JLNP
JLNM
JLNZ
JLNO

label
label
label
label
label
label
label
label

Jump
Jump
Jump
Jump
Jump
Jump
Jump
Jump

Long
Long
Long
Long
Long
Long
Long
Long

on
on
on
on
on
on
on
on

Plus
Minus
Zero
Overflow
Not Plus
Not Minus
Not Zero
Not Overflow

RIL
RIL
RIL
RIL
RIL
RIL
RIL
RIL

BRCL
BRCL
BRCL
BRCL
BRCL
BRCL
BRCL
BRCL

2,label
4,label
8,label
1,label
13,label
11,label
7,label
14,label

Notes:
1. D=displacement, X=index register, B=base register, R=register containing branch address
2. The addresses represented are explicit address (see 4). However, implicit addresses can also be used in this type of
instruction.
3. Avoid using BM, BNM, JM, and JNM after the TMH or TML instruction.

Figure 22 (Part 3 of 3). Extended Mnemonic Codes

|
|
|
|
|
|
|
|
|
|
|
|

Alternative Mnemonics for some Branch Relative Instructions

For some branch relative statements, there are alternative mnemonics. These are:
Instruction Alternative Description
-------------------------------------------------------------BRAS
JAS
Branch Relative and Save
BRASL
JASL
Branch Relative and Save Long
BRCT
JCT
Branch Relative on Count
BRCTG
JCTG
Branch Relative on Count
BRXH
JXH
Branch Relative on Index High
BRXHG
JXHG
Branch Relative on Index High
BRXLE
JXLE
Branch Rel. on Index Low or Equal
BRXLG
JXLEG
Branch Rel. on Index Low or Equal

Statement Formats
Machine instructions are assembled into 2, 4, or 6 bytes of object code according
to the format of each instruction. Machine instruction formats include the following
(ordered by length attribute):
Length
2
4
6

Attribute Basic Formats

RR
RI, RS, RSI, RX, SI
SS

See the applicable Principles of Operation manual for complete details about
machine instruction formats. See also Examples of Coded Machine Instructions
on page 91.
When you code machine instructions, you use symbolic formats that correspond to
the actual machine language formats. Within each basic format, you can also code
Chapter 4. Machine Instruction Statements

Symbolic Operation Codes

variations of the symbolic representation, divided into groups according to the basic
formats shown below.
The assembler converts only the operation code and the operand entries of the
assembler language statement into object code. The assembler assigns to a name
entry symbol the value of the address of the first byte of the assembled instruction.
When you use this same symbol in the operand of an assembler language
statement, the assembler uses this address value in converting the symbolic
operand into its object code form. The length attribute assigned to the symbol
depends on the basic machine language format of the instruction in which the
symbol appears as a name entry.
A remarks entry is not converted into object code.
An example of a typical assembler language statement follows:
LABEL

4,256(5,1)

LOAD INTO REG4

where:
is the name entry
is the operation code mnemonic (converted to hex 58)
is the register operand (converted to hex 4)
are the storage operand entries (converted to hex 5A100)
are remarks not converted into object code

LABEL
L
4
256(5,1)
LOAD INTO REG4

The object code of the assembled instruction, in hexadecimal, is:

5845A1 (4 bytes in RX format)

Symbolic Operation Codes

You must specify an operation code for each machine instruction statement. The
symbolic operation code, or mnemonic code as it is also called, indicates the type
of operation to be done; for example, A indicates the addition operation. See the
applicable Principles of Operation for a complete list of symbolic operation codes
and the formats of the corresponding machine instructions.
The general format of the machine instruction operation code is:
Operation Code Format
VERB
MODIFIER DATA TYPE MACHINE FORMAT

Verb: The verb must always be present. It usually consists of one or two
characters and specifies the operation to be done. The verb is underscored in the
following examples:
A
MVC

3,AREA
TO,FROM

A indicates an add operation

MV indicates a move operation

The other items in the operation code are not always present. They include the
following (underscores are used to indicate modifiers, data types, and machine
formats in the examples below):
Modifier: Modifier, which further defines the operation:

HLASM V1R5 Language Reference

Operand Entries

3,AREA

L indicates a logical operation

Data Type: Type qualifier, which indicates the type of data used by the instruction
in its operation:
CVB 3,BINAREA

B indicates binary data

MVC TO,FROM

C indicates character data

2,FLTSHRT

E indicates normalized short

floating-point data

2,FLTLONG

D indicates normalized long

floating-point data

Machine Format: Format qualifier, R indicating a register operand, or I indicating

an immediate operand. For example:
ADR 2,4

R indicates a register operand

MVI FIELD,X'A1'
AHI 7,123

I indicates an immediate operand

Operand Entries
You may specify one or more operands in each machine instruction statement to
provide the data or the location of the data upon which the machine operation is to
be done. The operand entries consist of one or more fields or subfields, depending
on the format of the instruction being coded. They can specify a register, an
address, a length, or immediate data. You can omit length fields or subfields,
which the assembler computes for you from the other operand entries. You can
code an operand entry either with symbols or with self-defining terms.
The rules for coding operand entries are:
A comma must separate operands.
Parentheses must enclose subfields.
A comma must separate subfields enclosed in parentheses.
If a subfield is omitted because it is implicit in a symbolic address, the
parentheses that would have enclosed the subfield must be omitted.
If two subfields are enclosed in parentheses and separated by commas, the
following applies:

If both subfields are omitted because they are implicit in a symbolic entry,
the separating comma and the parentheses that would have been needed
must also be omitted.
If the first subfield is omitted, the comma that separates it from the second
subfield must be written, as well as the enclosing parentheses.
If the second subfield is omitted, the comma that separates it from the first
subfield must be omitted; however, the enclosing parentheses must be
written.
Spaces must not appear within the operand field, except as part of a character
self-defining term, or in the specification of a character literal.

Chapter 4. Machine Instruction Statements

Operand Entries

Registers
You can specify a register in an operand for use as an arithmetic accumulator, a
base register, an index register, and as a general depository for data to which you
want to refer repeatedly.
You must be careful when specifying a register whose contents have been affected
by the execution of another machine instruction, the control program, or an
IBM-supplied system macro instruction.
For some machine instructions, you are limited in which registers you can specify in
an operand.
The expressions used to specify registers must have absolute values; in general,
registers 0 through 15 can be specified for machine instructions. However, the
following restrictions on register usage apply:
If the NOAFPR assembler option is specified, then only the floating-point
registers (0, 2, 4, or 6) may be specified for floating-point instructions.
The even-numbered registers (0, 2, 4, 6, 8, 10, 12, 14) must be specified for
the following groups of instructions:
The double-shift instructions
The fullword multiply and divide instructions
The move long and compare logical long instructions
If the AFPR assembler option is specified, then one of the floating-point
registers 0, 1, 4, 5, 8, 9, 12 or 13 can be specified for the instructions that use
extended floating-point data in pairs of registers, such as AXR, SXR, LTXBR,
and SQEBR.
If the NOAFPR assembler option is specified, then either floating-point register
0 or 4 must be specified for these instructions.
For a processor with a vector facility, the even-numbered vector registers (0, 2,
4, 6, 8, 10, 12, 14) must be specified in vector-facility instructions that are used
to manipulate long floating-point data or 64-bit signed binary data in vector
registers.
The assembler checks the registers specified in the instruction statements of the
above groups. If the specified register does not comply with the stated restrictions,
the assembler issues a diagnostic message and does not assemble the instruction.
Binary zeros are generated in place of the machine code.

Register Usage by Machine Instructions

Registers that are not explicitly coded in symbolic assembler language
representation of machine instructions, but are nevertheless used by assembled
machine instructions, are divided into two categories:
Base registers that are implicit in the symbolic addresses specified. (See
Addresses on page 87.) The registers can be identified by examining the
object code or the USING instructions that assign base registers for the source
module.
Registers that are used by machine instructions, but don't appear in assembled
object code.

HLASM V1R5 Language Reference

Operand Entries

For double shift and fullword multiply and divide instructions, the
odd-numbered register, whose number is one greater than the
even-numbered register specified as the first operand.
For Move Long and Compare Logical Long instructions, the odd-numbered
registers, whose number is one greater than even-numbered registers
specified in the two operands.
For Branch on Index High (BXH) and the Branch on Index Low or Equal
(BXLE) instructions, if the register specified for the second operand is an
even-numbered register, the next higher odd-numbered register is used to
contain the value to be used for comparison.
For Load Multiple (LM, LAM) and Store Multiple (STM, STAM) instructions,
the registers that lie between the registers specified in the first two
operands.
For extended-precision floating point instructions, the second register of the
register pair.
For Compare and Form Codeword (CFC) instruction, registers 1, 2 and 3
are used.
For Translate and Test (TRT) instruction, registers 1 and 2 are used.
For Update Tree (UPT) instruction, registers 0-5 are used.
For Edit and Mark (EDMK) instruction, register 1 is used.
For certain control instructions, one or more of registers 0-4 and register 14
are used. See Control Instructions in the applicable Principles of
Operation manual.
For certain input/output instructions, either or both registers 1 and 2 are
used. See Input/Output Instructions in the applicable Principles of
Operation manual.
On a processor with a vector facility:
1. For instructions that manipulate long floating-point data in vector
registers, the odd-numbered vector registers, whose number is one
greater than the even-numbered vector registers specified in each
operand.
2. For instructions that manipulate 64-bit signed binary data in vector
registers, the odd-numbered vector registers, whose number is one
greater than the even-numbered vector registers specified in each
operand.

Register Usage by System

The programming interface of the system control programs uses registers 0, 1, 13,
14, and 15.

Addresses
You can code a symbol in the name field of a machine instruction statement to
represent the address of that instruction. You can then refer to the symbol in the
operands of other machine instruction statements. The object code requires that
addresses be assembled in a numeric relative-offset or base-displacement format.
This format lets you specify addresses that are relocatable or absolute. Chapter 3,

Chapter 4. Machine Instruction Statements

Operand Entries

Program Structures and Addressing on page 50 describes how you use symbolic
addresses to refer to data in your assembler language program.
Defining Symbolic Addresses: Define relocatable addresses by either using a
symbol as the label in the name field of an assembler language statement, or
equating a symbol to a relocatable expression.
Define absolute addresses (or values) by equating a symbol to an absolute
expression.
Referring to Addresses: You can refer to relocatable and absolute addresses in
the operands of machine instruction statements. (Such address references are
also called addresses in this manual.) The two ways of coding addresses are:
Implicitlyin a form that the assembler must first convert into an explicit
relative-offset or base-displacement form before it can be assembled into object
code.
Explicitlyin a form that can be directly assembled into object code.

Implicit Address
An implicit address is specified by coding one expression. The expression can be
relocatable or absolute. The assembler converts all implicit addresses into their
relative-offset or base-displacement form before it assembles them into object code.
The assembler converts implicit addresses into explicit base-displacement
addresses only if a USING instruction has been specified, or for small absolute
expressions, where the address is resolved without a USING. The USING
instruction assigns both a base address, from which the assembler computes
displacements, and a base register, which is assumed to contain the base address.
The base register must be loaded with the correct base address at execution time.
For more information, refer to Addressing on page 63.

Explicit Address
An explicit address is specified by coding two absolute expressions as follows:
The first is an absolute expression for the displacement, whose value must lie
in the range 0 through 4095 (4095 is the maximum value that can be
represented by the 12 binary bits available for the displacement in the object
code).
The second (enclosed in parentheses) is an absolute expression for the base
register, whose value must lie in the range 0 through 15.
An explicit base register designation must not accompany an implicit address.
However, in RX-format instructions, an index register can be coded with an implicit
address as well as with an explicit address. When two addresses are required,
each address can be coded as an explicit address or as an implicit address.

Relative Address
A relative address is specified by coding one expression. The expression may be
relocatable or absolute. If a relocatable expression is used, then the assembler
converts the value to a signed number of halfwords relative to the current location
counter, and then uses that value in the object code. An absolute value may be
used for a relative address, but the assembler issues a warning message, as it
uses the supplied value, and this may cause unpredictable results.

HLASM V1R5 Language Reference

Operand Entries

Relocatability of Addresses
If the value of an address expression changes when the assumed origin of the
program is changed, and changes by the same amount, then the address is simply
relocatable. If the addressing expression does not change when the assumed origin
of the program is changed, then that address is absolute. If the addressing
expression changes by some other amount, the address may be complexly
relocatable.
Addresses in the relative-offset or base-displacement form are relocatable,
because:
Each relocatable address is assembled as a signed relative offset from the
instruction, or as a displacement from a base address and a base register.
The base register contains the base address.
If the object module assembled from your source module is relocated, only the
contents of the base register need reflect this relocation. This means that the
location in virtual storage of your base has changed, and that your base
register must contain this new base address.
Addresses in your program have been assembled as relative to the base
address; therefore, the sum of the displacement and the contents of the base
register point to the correct address after relocation.
Absolute addresses are also assembled in the base-displacement form, but always
indicate a fixed location in virtual storage. This means that the contents of the
base register must always be a fixed absolute address value regardless of
relocation.

Machine or Object Code Format

Addresses assembled into the object code of machine instructions have the format
given in Figure 23 on page 90. Not all of the instruction formats are shown in
Figure 23.
The addresses represented have a value that is the sum of a displacement (see
1 in Figure 23) and the contents of a base register (see 2 in Figure 23).
Index Register: In RX-format instructions, the address represented has a value
that is the sum of a displacement, the contents of a base register, and the contents
of an index register (see 3 in Figure 23).

Chapter 4. Machine Instruction Statements

Operand Entries

Format Coded or Symbolic

Object Code
Representation of
Representation
Explicit Address
of Addresses

8 bits
4
4
4
12 bits
4
12 bits

Operation bits bits bits Displacement

bits Displacement

Code

Base

Reg.

2
1

RS
D(B)
OP CODE
R R B
D

3 (Index Register)

RX
D(X,B)
OP CODE
R X B
D

SI
D(B)
OP CODE

I
B
D

2
1

SS
D(,B),D(B)
OP CODE

L
B
D
B
D

I
represents an immediate value
L
represents a length
B, R and R represent registers
Figure 23. Format of Addresses in Object Code

Lengths
You can specify the length field in an SS-format instruction. This lets you indicate
explicitly the number of bytes of data at a virtual storage location that is to be used
by the instruction. However, you can omit the length specification, because the
assembler computes the number of bytes of data to be used from the expression
that represents the address of the data.
See page 97 for more information about SS-format instructions.
Implicit Length: When a length subfield is omitted from an SS-format machine
instruction, an implicit length is assembled into the object code of the instruction.
The implicit length is either of the following:
For an implicit address, it is the length attribute of the first or only term in the
expression representing the implicit address.
For an explicit address, it is the length attribute of the first or only term in the
expression representing the displacement.
Explicit Length: When a length subfield is specified in an SS-format machine
instruction, the explicit length always overrides the implicit length.
An implicit or explicit length is the effective length. The length value assembled is

HLASM V1R5 Language Reference

Examples of Coded Machine Instructions

always one less than the effective length. If you want an assembled length value
of 0, an explicit length of 0 or 1 can be specified.
In the SS-format instructions requiring one length value, the allowable range for
explicit lengths is 0 through 256. In the SS-format instructions requiring two length
values, the allowable range for explicit lengths is 0 through 16.

Immediate Data
In addition to registers, numeric values, relative addresses, and lengths, some
machine instruction operands require immediate data. Such data is assembled
directly into the object code of the machine instructions. Use immediate data to
specify the bit patterns for masks or other absolute values you need.
Specify immediate data only where it is required. Do not confuse it with address
references to constants and areas, or with any literals you specify as the operands
of machine instructions.
Immediate data must be specified as absolute expressions whose range of values
depends on the machine instruction for which the data is required. The immediate
data is assembled into its binary representation.

Examples of Coded Machine Instructions

The examples that follow are grouped according to machine instruction format, and
the groups are shown in order of the instruction length. They show the various
ways in which you can code the operands of machine instructions. Both symbolic
and numeric representation of fields and subfields are shown in the examples.
Therefore, assume that all symbols used are defined elsewhere in the same source
module.
The object code assembled from at least one coded statement per group is also
included. A complete summary of machine instruction formats with the coded
assembler language variants can be found in the applicable Principles of Operation
manual.
The examples that follow show the various instruction formats, and are not meant
to show how the machine instructions should be used.

RI Format
The operand fields of RI-format instructions designate a register and an immediate
operand, with the following exception:
In BRC branching instructions, a 4-bit branching mask with a value between 0
and 15 inclusive replaces the register designation.
Symbols used to represent registers (such as REG1 in the example) are assumed
to be equated to absolute values between 0 and 15. The 16-bit immediate operand
has two different interpretations, depending on whether the instruction is a
branching instruction or not.
There are two types of non-branching RI-format instructions.

Chapter 4. Machine Instruction Statements

Examples of Coded Machine Instructions

For most, the immediate value is treated as a signed binary integer (a value
between 32768 and +32767). This value may be specified using self-defining
terms or equated symbols.

Op Code R OpCd
I

8
12
16
31
For logical instructions such as TMH, the immediate field is a 16 bit mask.

Op Code M OpCd
I

8
12
16
31
Examples:
ALPHA1
ALPHA2
BETA1

AHI
MHI
TMH

REG1,2
3,1234
7,X'81'

When assembled, the object code for the instruction labeled BETA1, in
hexadecimal, is
A7781
where:
A7. is the operation code
7
is register R
81 is the immediate data I2
For branching RI-format instructions, the immediate value is treated as a signed
binary integer representing the number of halfwords to branch relative to the current
location.
The branch target may be specified as a relocatable expression, in which case the
assembler performs some checking, and calculates the immediate value.
The branch target may also be specified as an absolute value in which case the
assembler issues a warning before it assembles the instruction.
Examples:
ALPHA1
ALPHA2
BETA1

BRAS
BRC
BRCT

1,BETA1
3,ALPHA1
7,ALPHA1

When assembled, the object code for the instruction labeled BETA1, in
hexadecimal, is
A776FFFC
where:
A7.6 is the operation code
7
is register R
FFFC is the immediate data I2; a value of 4 decimal
|
|

If the GOFF assembler option is active, then it is possible to specify the target
address as one or more external symbols (with or without offsets).

HLASM V1R5 Language Reference

Examples of Coded Machine Instructions

|
|
|
|

If an offset is specified it may be specified as a relocatable expression or an

absolute value. If the offset is specified as a relocatable expression, the assembler
performs some checking and calculates the immediate value. If the offset is an
absolute expression the assembler issues warning message ASMA056W.

Examples:

|
|
|

ALPHA1 BRAS
ALPHA2 BRASL
BETA1 BRC

|
|

14,A-B+C+1
14,A-B+C+1
15,A-B+C+1

where A, B and C are external symbols

When assembled, the object code for the instruction labeled BETA1, in
hexadecimal, is

A7F45

where:

|
|
|

A7.4 is the operation code

F
is the condition code
5 is the immediate data I2; a value of 5 decimal.

|
|

In addition GOFF Relocation Dictionary Data Items are generated for the external
symbols A, B and C.

RR Format
The operand fields of RR-format instructions designate two registers, with the
following exceptions:
In BCR branching instructions, when a 4-bit branching mask replaces the first
register specification (see 8 in the instruction labeled GAMMA1 below)
In SVC instructions, where an immediate value (between 0 and 255) replaces
both registers (see 2 in the instruction labeled DELTA1 below)

Op Code R R

8
12 15
Symbols used to represent registers in RR-format instructions (see INDEX and REG2
in the instruction labeled ALPHA2 below) are assumed to be equated to absolute
values between 0 and 15.
Symbols used to represent immediate values in SVC instructions (see TEN in the
instruction labeled DELTA2 below) are assumed to be equated to absolute values
between 0 and 255.
Examples:
ALPHA1
ALPHA2
GAMMA1
DELTA1
DELTA2

LR
LR
BCR
SVC
SVC

1,2
INDEX,REG2
8,12
2
TEN

When assembled, the object code of the instruction labeled ALPHA1, in

hexadecimal, is:
1812

Chapter 4. Machine Instruction Statements

Examples of Coded Machine Instructions

where:
18
1
2

is the operation code

is register R
is register R

RS Format
The operand fields of RS-format instructions designate two registers, and a virtual
storage address (coded as an implicit address or an explicit address).

Op Code R R B
D

8
12
16
2
31
In the Insert Characters under Mask (ICM) and the Store Characters under Mask
(STCM) instructions, a 4-bit mask (see X'E' and MASK in the instructions labeled
DELTA1 and DELTA2 below), with a value between 0 and 15, replaces the second
register specifications.

Op Code R M B
D

8
12 16
2
31
Symbols used to represent registers (see REG4, REG6, and BASE in the instruction
labeled ALPHA2 below) are assumed to be equated to absolute values between 0
and 15.
Symbols used to represent implicit addresses (see AREA and IMPLICIT in the
instructions labeled BETA1 and DELTA2 below) can be either relocatable or absolute.
Symbols used to represent displacements (see DISPL in the instruction labeled
BETA2 below) in explicit addresses are assumed to be equated to absolute values
between 0 and 4095.
Examples:
ALPHA1
ALPHA2
BETA1
BETA2
GAMMA1
DELTA1
DELTA2

LM
LM
STM
STM
SLL
ICM
ICM

4,6,2(12)
REG4,REG6,2(BASE)
4,6,AREA
4,6,DISPL(BASE)
2,15
3,X'E',124(1)
REG3,MASK,IMPLICIT

When assembled, the object code for the instruction labeled ALPHA1, in
hexadecimal, is:
9846C14
where:
98
4
6
C
14

is
is
is
is
is

the operation code

HLASM V1R5 Language Reference

Examples of Coded Machine Instructions

When assembled, the object code for the instruction labeled DELTA1, in
hexadecimal, is:
BF3EA4
where:
BF is the operation code
3
is register R
E
is mask M
A
is base register B
4 is displacement D from base register B

RSI Format
The operand fields of RSI-format instructions designate two registers and a 16-bit
immediate operand.

Op Code R R
I

8
12
16
31
Symbols used to represent registers (See REG1 below) are assumed to be
equated to absolute values between 0 and 15.
The immediate value is treated as a signed binary integer representing the number
of halfwords to branch relative to the current location.
The branch target may be specified as a label in which case the assembler
calculates the immediate value and performs some checking of the value.
The branch target may also be specified as an absolute value in which case the
assembler issues a warning before it assembles the instruction.
Examples:
ALPHA1
BETA1

BRXH
BRXLE

REG1,REG3,BETA1
1,2,ALPHA1

When assembled, the object code for the instruction labeled ALPHA1, in
hexadecimal, is
84132
where:
84
1
3
2

is
is
is
is

the operation code

RX Format
The operand fields of RX-format instructions designate one or two registers,
including an index register, and a virtual storage address (coded as an implicit
address or an explicit address), with the following exception:
In BC branching instructions, a 4-bit branching mask (see 7 and TEN in the
instructions labeled LAMBDAn below) with a value between 0 and 15,
replaces the first register specification.
Chapter 4. Machine Instruction Statements

Examples of Coded Machine Instructions

Op Code R X B
D

8
12
16
2
31
Symbols used to represent registers (see REG1, INDEX, and BASE in the ALPHA2
instruction below) are assumed to be equated to absolute values between 0 and
15.
Symbols used to represent implicit addresses (see IMPLICIT in the instructions
labeled GAMMAn below) can be either relocatable or absolute.
Symbols used to represent displacements (see DISPL in the instructions labeled
BETA2 and LAMBDA1 below) in explicit addresses are assumed to be equated to
absolute values between 0 and 4095.
Examples:
ALPHA1
ALPHA2
BETA1
BETA2
GAMMA1
GAMMA2
DELTA1
LAMBDA1
LAMBDA2

L
L
L
L
L
L
L
BC
BC

1,2(4,1)
REG1,2(INDEX,BASE)
2,2(,1)
REG2,DISPL(,BASE)
3,IMPLICIT
3,IMPLICIT(INDEX)
4,=F'33'
7,DISPL(,BASE)
TEN,ADDRESS

When assembled, the object code for the instruction labeled ALPHA1, in
hexadecimal, is:
5814AC8
where:
58 is the operation code
1
is register R
4
is index register X
A
is base register B
C8 is displacement D from base register B
When assembled, the object code for the instruction labeled GAMMA1, in
hexadecimal, is:
5824xyyy
where:
58 is the operation code
2
is register R
4
is the index register X
x
is base register B
yyy is displacement D from base register B

HLASM V1R5 Language Reference

Examples of Coded Machine Instructions

SI Format
The operand fields of SI-format instructions designate immediate data and a virtual
storage address.

Op Code
I
B
D

8
16
2
31
Symbols used to represent immediate data (see HEX4 and TEN in the instructions
labeled ALPHA2 and BETA1 below) are assumed to be equated to absolute values
between 0 and 255.
Symbols used to represent implicit addresses (see IMPLICIT and KEY in the
instructions labeled BETA1 and BETA2) can be either relocatable or absolute.
Symbols used to represent displacements (see DISPL4 in the instruction labeled
ALPHA2 below) in explicit addresses are assumed to be equated to absolute values
between 0 and 4095.
Examples:
ALPHA1
ALPHA2
BETA1
BETA2

CLI
CLI
CLI
CLI

4(9),X'4'
DISPL4(NINE),HEX4
IMPLICIT,TEN
KEY,C'E'

When assembled, the object code for the instruction labeled ALPHA1, in
hexadecimal, is:
954928
where
95 is the operation code.
4 is the immediate data.
9
is the base register.
28 is the displacement from the base register

SS Format
The operand fields and subfields of SS-format instructions designate two virtual
storage addresses (coded as implicit addresses or explicit addresses) and,
optionally, the explicit data lengths you want to include. However, note that, in the
Shift and Round Decimal (SRP) instruction, a 4-bit immediate data field (see 3 in
SRP instruction below), with a value between 0 and 9, is specified as a third
operand.

Chapter 4. Machine Instruction Statements

Examples of Coded Machine Instructions

//
Op Code
L
B
D
B
D

//

8
16
2
32
36
47
//
Op Code L L B
D
B
D

//

8
12
16
2
32
36
47
//
Op Code L I B
D
B
D

//

8
12
16
2
32
36
47
//
Op Code R R B
D
B
D

//

8
12
16
2
32
36
47
Symbols used to represent base registers (see BASE8 and BASE7 in the instruction
labeled ALPHA2 below) in explicit addresses are assumed to be equated to absolute
values between 0 and 15.
Symbols used to represent explicit lengths (see NINE and SIX in the instruction
labeled ALPHA2 below) are assumed to be equated to absolute values between 0
and 256 for SS-format instructions with one length specification, and between 0 and
16 for SS-format instructions with two length specifications.
Symbols used to represent implicit addresses (see FIELD1 and FIELD2 in the
instruction labeled ALPHA3, and FIELD1,X'8' in the SRP instructions below) can be
either relocatable or absolute.
Symbols used to represent displacements (see DISP4 and DISP3 in the instruction
labeled ALPHA5 below) in explicit addresses are assumed to be equated to absolute
values between 0 and 4095.
See page 90 for more information about the lengths of SS-format instructions.
Examples:
ALPHA1
ALPHA2
ALPHA3
ALPHA4
ALPHA5
BETA1
BETA2
BETA3

AP
AP
AP
AP
AP
MVC
MVC
MVC
SRP

4(9,8),3(6,7)
4(NINE,BASE8),3(SIX,BASE7)
FIELD1,FIELD2
AREA(9),AREA2(6)
DISP4(,8),DISP3(,7)
(8,8),(7)
DISP(,8),DISP(7)
TO,FROM
FIELD1,X'8',3

When assembled, the object code for the instruction labeled ALPHA1, in
hexadecimal, is:
FA8582871E

HLASM V1R5 Language Reference

Examples of Coded Machine Instructions

where:
FA is the operation code.
8
is length L
5
is length L
8
is base register B
28 is displacement D from base register B
7
is base register B
1E is displacement D from base register B
When assembled, the object code for the instruction labeled BETA1, in hexadecimal,
is:
D24F87
where:
D2
4F
8

7

is
is
is
is
is
is

the operation code

length L
base register B
displacement D from base register B
base register B
displacement D from base register B

Chapter 4. Machine Instruction Statements

Chapter 5. Assembler Instruction Statements

This chapter describes, in detail, the syntax and usage rules of each assembler
instruction. There is also information about assembly instructions on Conditional
Assembly Instructions on page 256. The following table lists the assembler
instructions by type, and provides the page number where the instruction is
described.
Figure 24 (Page 1 of 2). Assembler Instructions
Type of Instruction

Instruction

Program Control

AINSERT

108

CNOP

119

COPY

122

END

182

EXITCTL

187

ICTL

189

ISEQ

190

LTORG

193

ORG

200

POP

204

PUNCH

208

PUSH

209

REPRO

210

CEJECT

118

EJECT

181

204

SPACE

213

TITLE

215

OPSYN

198

Listing Control

Operation Code Definition

100

Page No.

Copyright IBM Corp. 1982, 2004

64-bit Addressing Mode

Figure 24 (Page 2 of 2). Assembler Instructions

Type of Instruction

Instruction

Program Section and Linking

ALIAS

109

AMODE

110

CATTR (MVS and CMS)

112

COM

121

CSECT

123

CXD

125

DSECT

178

DXD

180

ENTRY

183

EXTRN

189

LOCTR

191

RMODE

211

RSECT

212

START

214

WXTRN

229

XATTR (MVS and CMS)

230

DROP

172

USING

218

CCW

115

CCW0

115

CCW1

116

126

174

Symbol Definition

EQU

184

Associated Data

ADATA

107

Assembler Options

*PROCESS

102

ACONTROL

103

Base Register

Data Definition

Page No.

64-bit Addressing Mode

Some instructions have an operand or operands that pertain to 64-bit addressing
mode (for example, 64 for AMODE). This operand is 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 this operand.

Chapter 5. Assembler Instruction Statements

101

*PROCESS Statement

*PROCESS Statement
Process (*PROCESS) statements specify assembler options in an assembler
source program. You can include them in the primary input data set or provide
them from a SOURCE user exit.
To ensure that certain assembler options cannot be changed for a given source file,
put the OVERRIDE keyword as the first and only keyword on the process
statement, followed by a list of options. This means that default and invocation
options cannot override the specified options.
You can specify up to 10 process statements in each source program. Except for
the ICTL instruction, process statements must be the first statements in your source
program. If you include process statements anywhere else in your source program
the assembler treats them as comments.
A process statement has a special coding format, unlike any other assembler
instruction, although it is affected by the column settings of the ICTL instruction.
You must code the characters PROCESS starting in the begin column of the source
statement, followed by one or more spaces. You can code as many assembler
options that can fit in the remaining columns up to, and including the end column of
the source statement.
You cannot continue a process statement on to the next statement.

,
assembler option
PROCESS

assembler option)
OVERRIDE(

assembler_option
is any assembler option.
A number of options are not accepted from a process statement. If the option is
specified on a process override statement and differs from the option in effect at
the time of processing the statement, the assembler issues a warning message.
These options are:
ADATA
ASA
DECK
EXIT
GOFF

|
|

LANGUAGE
LINECOUNT
LIST
OBJECT
SIZE

SYSPARM
TERM
TRANSLATE
XOBJECT

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

message in the High Level Assembler Option Summary section of the assembler
listing. If the installation default option PESTOP is set then the assembler stops
after it finishes processing any remaining process statements.
The assembler lists the options from process statements in the High Level
Assembler Option Summary section of the assembler listing. The process
statements are also shown as comment lines in the Source and Object section of
the assembler listing.

102

HLASM V1R5 Language Reference

ACONTROL Instruction

ACONTROL Instruction
The ACONTROL instruction can change these HLASM options within a program:

AFPR
COMPAT
FLAG (except the RECORD/NORECORD and the PUSH/NOPUSH suboptions)
LIBMAC
RA2
TYPECHECK

Note: The AFPR option is not available as an assembler option at invocation of

the assembler.
The selections which can be specified are documented here for completeness.

,
selection
ACONTROL
sequence_symbol

sequence_symbol
is a sequence symbol.
selection
is one or more selections from the group of selections described below.
Because ACONTROL is making changes to existing values, there are no default
values for the ACONTROL instruction.

AFPR
NOAFPR

AFPR
instructs the assembler that the additional floating point registers 1, 3, 5 and 7
through 15 may be specified in the program.
Note: The assembler starts with AFPR enabled.
NOAFPR
instructs the assembler that no additional floating point registers, that is, only
floating point registers 0, 2, 4 and 6 may be specified in the program.

Chapter 5. Assembler Instruction Statements

103

ACONTROL Instruction

NOCOMPAT

keyword )
COMPAT(
keyword:
CASE
NOCASE

LITTYPE
NOLITTYPE

MACROCASE
NOMACROCASE
SYSLIST
NOSYSLIST

COMPAT(CASE), abbreviation CPAT(CASE)

instructs the assembler to maintain uppercase alphabetic character set
compatibility with earlier assemblers.
COMPAT(NOCASE), abbreviation CPAT(NOCASE)
instructs the assembler to allow mixed case alphabetic character set.
COMPAT(LITTYPE), abbreviation CPAT(LIT)
instructs the assembler to return 'U' as the type attribute for all literals.
COMPAT(NOLITTYPE), abbreviation CPAT(NOLIT)
instructs the assembler to return the correct type attribute for literals.
COMPAT(MACROCASE), abbreviation CPAT(MC)
instructs the assembler to convert internally lowercase alphabetic characters in
unquoted macro operands to uppercase alphabetic characters prior to macro
expansion. (The source statement is unchanged).
COMPAT(NOMACROCASE), abbreviation CPAT(NOMC)
instructs the assembler not to convert lowercase alphabetic characters (a
through z) in unquoted macro operands.
COMPAT(SYSLIST), abbreviation CPAT(SYSL)
instructs the assembler to treat sublists in SETC symbols as compatible with
earlier assemblers.
COMPAT(NOSYSLIST), abbreviation CPAT(NOSYSL)
instructs the assembler not to treat sublists in SETC symbols as character
strings, when passed to a macro definition in an operand of a macro
instruction.
NOCOMPAT, abbreviation NOCPAT
instructs the assembler to allow lowercase alphabetic characters in all language
elements, to treat sublists in SETC symbols as sublists when passed to a
macro definition in the operand of a macro instruction, and to return the correct
type attribute for literals.

104

HLASM V1R5 Language Reference

ACONTROL Instruction

|
|

,
integer)
FLAG(
ALIGN
NOALIGN
CONT
NOCONT

EXLITW
NOEXLITW
IMPLEN
NOIMPLEN
PAGE
NOPAGE
SUBSTR
NOSUBSTR
USING
NOUSING

integer
specifies that error diagnostic messages with this or a higher severity code are
printed in the source and object section of the assembly listing.
FLAG(ALIGN), abbreviation FLAG(AL)
instructs the assembler to issue diagnostic message ASMA33I, ASMA212W, or
ASMA213W when an inconsistency is detected between the operation code and
the alignment of addresses in machine instructions.
FLAG(NOALIGN), abbreviation FLAG(NOAL)
instructs the assembler not to issue diagnostic message ASMA33I ASMA212W, or
ASMA213W when an inconsistency is detected between the operation code and
the alignment of addresses in machine instructions.
FLAG(CONT)
specifies that the assembler is to issue diagnostic messages ASMA43W through
ASMA433W when an inconsistent continuation is encountered in a statement.
FLAG(NOCONT)
specifies that the assembler is not to issue diagnostic messages ASMA43W
through ASMA433W when an inconsistent continuation is encountered in a
statement.
|
|
|

FLAG(EXLITW)
instructs the assembler to issue diagnostic warning ASMA016W when a literal
is specified as the object of an EX instruction.

|
|
|

FLAG(NOEXLITW)
instructs the assembler to suppress diagnostic warning message ASMA016W
when a literal is specified as the object of an EX instruction.
FLAG(IMPLEN)
instructs the assembler to issue diagnostic message ASMA169I when an explicit
length subfield is omitted from an SS-format machine instruction.
FLAG(NOIMPLEN)
instructs the assembler not to issue diagnostic message ASMA169I when an
explicit length subfield is omitted from an SS-format machine instruction.

Chapter 5. Assembler Instruction Statements

105

ACONTROL Instruction

FLAG(PAGE0)
instructs the assembler to issue diagnostic message ASMA39W when an
operand is resolved to a baseless address and a base and displacement is
expected.
FLAG(NOPAGE0)
instructs the assembler not to issue diagnostic message ASMA39W when an
operand is resolved to a baseless address and a base and displacement is
expected.
FLAG(SUBSTR), abbreviation FLAG(SUB)
instructs the assembler to issue warning diagnostic message ASMA94I when
the second subscript value of the substring notation indexes past the end of the
character expression.
FLAG(NOSUBSTR), abbreviation FLAG(NOSUB)
instructs the assembler not to issue warning diagnostic message ASMA94I
when the second subscript value of the substring notation indexes past the end
of the character expression.
FLAG(USING0), abbreviation FLAG(US0)
instructs the assembler to issue diagnostic warning message ASMA36W for a
USING that is coincident with or overlaps the implied USING 0,0, when the
USING(WARN) suboption includes the condition numbers 1 and/or 4.
FLAG(NOUSING0), abbreviation FLAG(NOUS0)
instructs the assembler to suppress diagnostic warning message ASMA36W

NOLIBMAC
LIBMAC

LIBMAC, abbreviation LMAC

specifies that, for each macro, macro definition statements read from a macro
library are to be imbedded in the input source program immediately preceding
the first invocation of that macro.
NOLIBMAC, abbreviation NOLMAC
specifies that macro definition statements read from a macro library are not to
be included in the input source program.

NORA2
RA2

RA2
instructs the assembler to suppress error diagnostic message ASMA66W when
2-byte relocatable address constants are defined in the source
NORA2
instructs the assembler to issue error diagnostic message ASMA66W when
2-byte relocatable address constants are defined in the source

106

HLASM V1R5 Language Reference

ADATA Instruction

|
|
|
|
|
|
|
|
|
|
|

NOTYPECHECK

MAGNITUDE

(1)
TYPECHECK(
)
NOMAGNITUDE
REGISTER

NOREGISTER
Note:
Choose at least one option.

|
|
|

TYPECHECK(MAGNITUDE)
specifies that the assembler performs magnitude validation of signed
immediate-data fields of machine instruction operands.

|
|
|

TYPECHECK(NOMAGNITUDE)
specifies that the assembler not perform magnitude validation of signed
immediate-data fields of machine instruction operands.

|
|
|

TYPECHECK(REGISTER)
specifies that the assembler performs type checking of register fields of
machine instruction operands.

|
|
|

TYPECHECK(NOREGISTER)
specifies that the assembler not perform type checking of register fields of
machine instruction operands.

|
|
|

NOTYPECHECK
specifies that the assembler not perform any type checking of machine
instruction operands.

|
|

For further details of the TYPECHECK option, refer to the High Level Assembler
Programmer's Guide.

ADATA Instruction
The ADATA instruction writes records to the associated data file.

ADATA
sequence_symbol
value1,value2,value3,value4,character_string

sequence_symbol
is a sequence symbol.
value1-value4
up to four values may be specified, separated by commas. If a value is
omitted, the field written to the associated data file contains binary zeros. You
must code a comma in the operand for each omitted value. If specified, value1
through value4 must be a decimal self-defining term with a value in the range
231 to +2311.

Chapter 5. Assembler Instruction Statements

107

AINSERT Instruction

character_string
is a character string up to 255 bytes long, enclosed in single quotes. If omitted,
the length of the user data field in the associated data file is set to zero.
Notes:
1. All operands may be omitted to produce a record containing binary zeros in all
fields except the user data field.
2. The record written to the associated data file is described under User-Supplied
Information Record X'0070', in Appendix D, Associated Data File Output of
the HLASM Programmer's Guide.
3. If you do not specify the ADATA assembler option, or the GOFF(ADATA) or the
XOBJECT(ADATA) assembler option (MVS or CMS), the assembler only
checks the syntax of an ADATA instruction, and prints it in the assembler
listing.
4. The assembler writes associated data records to the SYSADATA (MVS or
CMS), or the SYSADAT (VSE) file if the ADATA assembler option has been
specified.

AINSERT Instruction
The AINSERT instruction inserts statements into the input stream. These
statements are queued in an internal buffer until the macro generator has
completed expanding the current outermost macro instruction. At that point the
internal buffer queue provides the next statement or statements. An operand
controls the sequence of the statements within the internal buffer queue.
Note: While inserted statements may be placed at either end of the buffer queue,
the statements are removed only from the front of the buffer queue.

AINSERT'statement',BACK
sequence_symbol
,FRONT

sequence_symbol
is a sequence symbol.
statement
is the statement stored in the internal buffer. It may be any characters
enclosed in single quotation marks.
The rules that apply to this character string are:
Variable symbols are allowed.
The string may be up to 80 characters in length. If the string is longer than
80 characters, only the first 80 characters are used. The rest of the string
is ignored.
BACK
The statement is placed at the back of the internal buffer.

108

HLASM V1R5 Language Reference

ALIAS Instruction

FRONT
The statement is placed at the front of the internal buffer.
Notes:
1. The ICTL instruction does not affect the format of the stored statements. The
assembler processes these statements according to the standard begin, end
and continue columns.
2. The assembler does not check the stored statements, even when the ISEQ
instruction is active.
Example:

|
|
|
|
|
|
|
|
|

MACRO
MAC1
.
.A
AINSERT
.B
AINSERT
.C
AINSERT
.
.
.
&FIRST AREAD
.
.D
AINSERT
.
&SECOND AREAD
.
MEND
CSECT
.
MAC1
.
END

'INSERT RECORD NUMBER ONE',FRONT

'INSERT RECORD NUMBER TWO',FRONT
'INSERT RECORD NUMBER THREE',BACK

Insert record into the input stream

Insert record at the top of the input stream
Insert record at the bottom of the input stream

Retrieve record TWO from the top of the input stream

'INSERT RECORD NUMBER FOUR',FRONT

Insert record at the top of the input stream

Retrieve record FOUR from the top of the input stream

In this example the variable &FIRST receives the operand of the AINSERT
statement created at .B. &SECOND receives the operand of the AINSERT
statement created at .D. The operand of the AINSERT statements at .A and .C are
in the internal buffer in the sequence .A followed by .C and are the next statements
processed when the macro generator has finished processing.
Figure 65 on page 263 shows code using AINSERT in statements 16, 22, and 23.

ALIAS Instruction
The ALIAS instruction specifies alternate names for the external symbols that
identify control sections, entry points, and external references. The instruction has
nothing to do with the link-time aliases in libraries.
symbolALIASalias_string

symbol
is an external symbol that is represented by one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol

Chapter 5. Assembler Instruction Statements

109

AMODE Instruction

alias_string
is the alternate name for the external symbol, represented by one of the
following:
A character constant in the form C'aaaaaaaa', where aaaaaaaa is a string
of characters each of which has a hexadecimal value of X'42' to X'FE'
inclusive
A hexadecimal constant in the form X'xxxxxxxx', where xxxxxxxx is a
string of hexadecimal digits, each pair of which is in the range X'42' to
X'FE' inclusive
The ordinary symbol denoted by symbol must also appear in one of the following in
this assembly:
The name entry field of a START, CSECT, RSECT, COM, or DXD instruction
The name entry field of a DSECT instruction and the nominal value of a Q-type
offset constant
The operand of an ENTRY, EXTRN or WXTRN instruction
The nominal value of a V-type address constant
The assembler uses the string denoted by alias_string to replace the external
symbol denoted by symbol in the external symbol dictionary records in the object
module. If the string is shorter than 8 characters, or 16 hexadecimal digits, it is
padded on the right with EBCDIC spaces (X'40'). If the string is longer than 8
characters, it is truncated. Some programs that process object modules do not
support external symbols longer than 8 characters.
If the extended object format is being generated (GOFF assembler
option), the alias_string can be up to 256 characters, or 512 hexadecimal digits.

The following examples are of the ALIAS instruction, and show both formats of the
alternate name denoted by alias_string.
EXTSYM1
EXTSYM2

ALIAS
ALIAS

C'lower1'
X'9396A68599F2'

The alias_string must not match any external symbol, regardless of case.
Aliased names are not checked against other internal or external symbols or
ALIASes for possible duplicates or conflicts.

AMODE Instruction
The AMODE instruction specifies the addressing mode associated with control
sections in the object deck.

AMODE24
name
31
64
ANY
ANY31
ANY64

110

HLASM V1R5 Language Reference

AMODE Instruction

name

is the name field that associates the residence mode with a control
section. If there is a symbol in the name field, it must also appear in the
name field of a START, CSECT, RSECT, or COM instruction in this
assembly. If the name field is space-filled, there must be an unnamed
control section in this assembly. If the name field contains a sequence
symbol (see Symbols on page 29 for details), it is treated as a blank
name field.
If the extended object format is being generated (GOFF
assembler option), name is a relocatable symbol that names an entry point
specified on an ENTRY instruction.

Specifies that 24-bit addressing mode is to be associated with a control

section, or entry point.

Specifies that 31-bit addressing mode is to be associated with a control

section, or entry point.

Specifies that 64-bit addressing mode is to be associated with a control

section, or entry point (see 64-bit Addressing Mode on page 101).

ANY

The same as ANY31.

ANY31 The control section or entry point is not sensitive to whether it is entered in
AMODE 24 or AMODE 31.
|
|

ANY64 The control section or entry point is not sensitive to whether it is entered in
AMODE 24, AMODE 31, or AMODE 64.
Any field of this instruction may be generated by a macro, or by substitution in open
code.
If symbol denotes an ordinary symbol, the ordinary symbol associates the
addressing mode with a control section. The ordinary symbol must also appear in
the name field of a START, CSECT, RSECT, or COM instruction in this assembly.
If symbol is not specified, or if name is a sequence symbol, there must be an
unnamed control section in this assembly.
Notes:
1. AMODE can be specified anywhere in the assembly. It does not initiate an
unnamed control section.

|
|

2. AMODE is permitted on external labels (EXTRNs) and Entry labels for both
GOFF and OBJ formats and Parts for GOFF formats.
3. An assembly can have multiple AMODE instructions; however, two AMODE
instructions cannot have the same name field.
4. The valid and invalid combinations of AMODE and RMODE are shown in the
following table. Note that combinations involving AMODE 64 and RMODE 64
are subject to the support outlined in 64-bit Addressing Mode on page 101.

Chapter 5. Assembler Instruction Statements

111

CATTR Instruction

Figure 25. AMODE/RMODE Combinations

RMODE 24

RMODE 31

RMODE 64

AMODE 24

invalid

AMODE 31

invalid

AMODE ANY|ANY31

invalid

AMODE 64|ANY64

5. AMODE or RMODE cannot be specified for an unnamed common control

section.
6. The defaults used when zero or one MODE is specified are shown in the
following table. Note that combinations involving AMODE 64 and RMODE 64
are subject to the support outlined in 64-bit Addressing Mode on page 101.
Figure 26. AMODE/RMODE Defaults

Specified

Default

Neither

AMODE 24, RMODE 24

AMODE 24

RMODE 24

AMODE 31

RMODE 24

AMODE ANY|ANY31

RMODE 24

AMODE 24

RMODE 31 (was ANY)

AMODE 31

AMODE 64

RMODE 31

AMODE ANY64

RMODE 31

RMODE 64

AMODE 64

CATTR Instruction (MVS and CMS)

The CATTR instruction establishes a program object external class name, and
assigns binder attributes for the class. This instruction is valid only when you
specify the GOFF or XOBJECT assembler option.

,
attribute
class_nameCATTR

class_name
is a valid program object external class name. The class name must follow the
rules for naming external symbols, except that:
Class names are restricted to a maximum of 16 characters
Class names with an underscore (_) in the second character are reserved
for IBM use; for example B_TEXT. If you use a class name of this format,
it might conflict with an IBM-defined binder class.
attribute
is one or more binder attributes that are assigned to the text in this class:

112

HLASM V1R5 Language Reference

CATTR Instruction

|
|

ALIGN(n)
Aligns the text on a 2n boundary. n is an integer in the range from 0 to 12,
inclusive. If not specified, then the SECTALGN value (8 is the default) is
used.

|
|
|

Note: Execution time support of the desired alignment depends on its

being respected by other operating system components such as linkers and
loaders.
EXECUTABLE
The text can be branched to or executedit is instructions, not data.
DEFLOAD
The text is not loaded when the program object is brought into storage, but
will probably be requested, and therefore should be partially loaded, for fast
access.
MERGE
The text has the merge binding property. For example, pseudo-registers or
external dummy sections have the merge binding property.
Merge classes can contain initial text. If they do contain initial text, they
must have a class name beginning with C_.
MOVABLE
The text can be moved, and is reenterable (that is, it is free of
location-dependent data such as address constants, and executes normally
if moved to a properly aligned boundary).
NOLOAD
The text for this class is not loaded when the program object is brought into
storage. An external dummy section is an example of a class which is
defined in the source program but not loaded.
NOTEXECUTABLE
The text cannot be branched to or executed (that is, it is data, not
instructions).
NOTREUS
The text is marked not reusable.

|
|
|
|

PART(part-name)
Identifies or continues the part with the name part-name. The part-name
can be up to 63 characters in length. An invalid part-name is ignored and
diagnostic message 'ASMA062E Illegal operand format xxxxxx' is issued.

|
|
|

Binding attributes assigned to the class are also assigned to the part. Both
the class and the part are assigned to Name Space 3 and are assigned the
merge attribute.

|
|
|

Text within a part cannot contain an entry point. If an entry point is found
within the part it is ignored and diagnostic message 'ASMA048E Entry error
- xxxxxxx' is issued.

|
|

The following rules apply to the validation of the PART attribute on the
CATTR instruction:

|
|

If the PART attribute has not been specified on the first CATTR
statement for the class, but is specified on subsequent CATTR

Chapter 5. Assembler Instruction Statements

113

CATTR Instruction

|
|
|
|
|
|

statements for the class, the attribute is ignored and diagnostic

message ASMA191W is issued.
If the PART attribute has been specified on the first CATTR statement
for the class, but is not specified on subsequent CATTR statements for
the class, the diagnostic message ASMA155S is issued.
Multiple parts may be defined within a class.

|
|
|
|
|

PRIORITY(nnnnn)
The binding priority to be attached to this part. The value must be
specified as an unsigned decimal number and must lie between 0 and
2311. An invalid priority is ignored and diagnostic message 'ASMA062E
Illegal operand format xxxxxx' is issued.

|
|
|
|

The PRIORITY attribute may be specified on the first CATTR instruction for
the part. If the PRIORITY attribute is specified on second and subsequent
CATTR instructions for the part it is ignored and the diagnostic message
ASMA191W is issued.

|
|
|

The PRIORITY attribute is ignored if there is no PART attribute on the

CATTR instruction and the diagnostic message 'ASMA062E Illegal operand
format xxxxxx' is issued.
READONLY
The text is storage-protected.
REFR
The text is marked refreshable.
RENT
The text is marked reenterable.
REUS
The text is marked reusable.
RMODE(24)
The text has a residence mode of 24.
RMODE(31)
The text has a residence mode of 31.
RMODE(ANY)
The text may be placed in any addressable storage.
Refer to the z/OS MVS Program Management: User's Guide and Reference,
SA22-7643 for details about the binder attributes.
Default Attributes: When you don't specify attributes on the CATTR instruction
the defaults are:
ALIGN(3),EXECUTABLE,NOTREUS,RMODE(24)
The LOAD attribute is the default if neither DEFLOAD nor NOLOAD are specified.
Where to Use the CATTR Instruction: Use the CATTR instruction anywhere in a
source module after any ICTL or *PROCESS statements. The CATTR instruction
must be preceded by a START, CSECT, or RSECT statement, otherwise the
assembler issues diagnostic message ASMA190E.

114

HLASM V1R5 Language Reference

CCW and CCW0 Instructions

If several CATTR instructions within a source module have the same class name,
the first occurrence establishes the class and its attributes, and the rest indicate the
continuation of the text for the class. If you specify attributes on subsequent
CATTR instructions having the same class name as a previous CATTR instruction,
the assembler ignores the attributes and issues diagnostic message ASMA191W.
If you specify conflicting attributes on the same instruction, the assembler uses the
last one specified. In the following example, the assembler uses RMODE(ANY):
MYCLASS

CATTR RMODE(24),RMODE(ANY)

Syntax Checking Only: If you code a CATTR instruction but don't specify the
GOFF or XOBJECT option, the assembler checks the syntax of the instruction
statement and does not process the attributes.

CCW and CCW0 Instructions

The CCW and CCW0 instructions define and generate an 8-byte, format-0 channel
command word for input/output operations. A format-0 channel command word
allows a 24-bit data address. The CCW and CCW0 instructions have identical
functions. If a control section has not been established, CCW and CCW0 will
initiate an unnamed (private) control section.

CCW
symbol CCW
command_code,data_address,flags,data_count

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
command_code
is an absolute expression that specifies the command code. This expression's
value is right-justified in byte 0 of the generated channel command word.
data_address
is a relocatable or absolute expression that specifies the address of the data to
operate upon. This value is treated as a 3-byte, A-type address constant. The
value of this expression is right-justified in bytes 1 to 3 of the generated
channel command word.
flags
is an absolute expression that specifies the flags for bits 32 to 37, and zeros for
bits 38 and 39, of the generated channel command word. The value of this
expression is right-justified in byte 4 of the generated channel command word.
Byte 5 is set to zero by the assembler.

Chapter 5. Assembler Instruction Statements

115

CCW1 Instruction

data_count
is an absolute expression that specifies the byte count or length of data. The
value of this expression is right-justified in bytes 6 and 7 of the generated
channel command word.
The generated channel command word is aligned at a doubleword boundary. Any
skipped bytes are set to zero.
The internal machine format of a channel command word is shown in Figure 27.
Figure 27. Channel Command Word, Format 0
Byte

Bits

Usage

0-7

Command code

1-3

8-31

Address of data to operate upon

32-37

Flags

38-39

Must be specified as zeros

40-47

Set to zeros by assembler

6-7

48-63

Byte count or length of data

If symbol is an ordinary symbol or a variable symbol that has been assigned an

ordinary symbol, the ordinary symbol is assigned the value of the address of the
first byte of the generated channel command word. The length attribute value of
the symbol is 8.
The following are examples of CCW and CCW0 statements:
WRITE1
WRITE2

CCW
CCW

1,DATADR,X'48',X'5'
1,DATADR,X'48',X'5'

The object code generated (in hexadecimal) for either of the above examples is:
1 xxxxxx 48 5
where xxxxxx contains the address of DATADR, and DATADR must reside below 16
megabytes.

Using EXCP or EXCPVR access methods: If you use the EXCP or EXCPVR
access method, you must use CCW or CCW0, because EXCP and EXCPVR do
not support 31-bit data addresses in channel command words.
Specifying RMODE: Use RMODE 24 with CCW or CCW0 to ensure that valid
data addresses are generated. If you use RMODE ANY with CCW or CCW0, an
invalid data address in the channel command word can result at execution time.

CCW1 Instruction
The CCW1 instruction defines and generates an 8-byte format-1 channel command
word for input/output operations. A format-1 channel command word allows 31-bit
data addresses. A format-0 channel command word generated by a CCW or CCW0
instruction allows only a 24-bit data address. If a control section has not been
established, CCW1 will initiate an unnamed (private) control section.

116

HLASM V1R5 Language Reference

CCW1 Instruction

CCW1command_code,data_address,flags,data_count
symbol

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
command_code
is an absolute expression that specifies the command code. This expression's
value is right-justified in byte 0 of the generated channel command word.
data_address
is a relocatable or absolute expression that specifies the address of the data to
operate upon. This value is treated as a 4-byte, A-type address constant. The
value of this expression is right-justified in bytes 4 to 7 of the generated
channel command word.
flags
is an absolute expression that specifies the flags for bits 8 to 15 of the
generated channel command word. The value of this expression is
right-justified in byte 1 of the generated channel command word.
data_count
is an absolute expression that specifies the byte count or length of data. The
value of this expression is right-justified in bytes 2 and 3 of the generated
channel command word.
The generated channel command word is aligned at a doubleword boundary. Any
skipped bytes are set to zero.
The internal machine format of a channel command word is shown in Figure 28.
Figure 28. Channel Command Word, Format 1
Byte

Bits

Usage

0-7

Command code

8-15

Flags

2-3

16-31

Count

Must be zero

4-7

33-63

Data address

The expression for the data address should be such that the address is within the
range 0 to 2311, inclusive, after possible relocation. This is the case if the
expression refers to a location within one of the control sections that are link-edited
together. An expression such as 1 yields an acceptable value only
when the value of the location counter (*) is 1000000000 or higher at assembly
time.

Chapter 5. Assembler Instruction Statements

117

CEJECT Instruction

If symbol is an ordinary symbol or a variable symbol that has been assigned an

CCW1

X'C',BUF1,X'',L'BUF1

The object code generated (in hexadecimal) for the above examples is:
C yyyy xxxxxxxx
where yyyy is the length of BUF1 and xxxxxxxx is the address of BUF1.
reside anywhere in virtual storage.

BUF1 can

CEJECT Instruction
The CEJECT instruction conditionally stops the printing of the assembler listing on
the current page, and continues the printing on the next page.

CEJECT
sequence_symbol
number_of_lines

sequence_symbol
is a sequence symbol.
number_of_lines
is an absolute value that specifies the minimum number of lines that must be
remaining on the current page to prevent a page eject. If the number of lines
remaining on the current page is less than the value specified by
number_of_lines, the next line of the assembler listing is printed at the top of a
new page.
You may use any absolute expression to specify number_of_lines.
If number of lines is omitted, the CEJECT instruction behaves as an EJECT
instruction.
If zero, a page is ejected unless the current line is at the top of a page.
If the line before the CEJECT statement appears at the bottom of a page, the
CEJECT statement has no effect. A CEJECT instruction without an operand
immediately following another CEJECT instruction or an EJECT instruction is
ignored.
Notes:
1. The CEJECT statement itself is not printed in the listing unless a variable
symbol is specified as a point of substitution in the statement, in which case the
statement is printed before substitution occurs.
2. The PRINT DATA and PRINT NODATA instructions can alter the effect of the
CEJECT instruction, depending on the number of assembler listing lines that
are required to print the generated object code for each instruction.

118

HLASM V1R5 Language Reference

CNOP Instruction

CNOP Instruction
The CNOP instruction aligns any instruction or other data on a specific halfword
boundary. This ensures an unbroken flow of executable instructions, since the
CNOP instruction generates no-operation instructions to fill the bytes skipped to
achieve specified alignment. If a control section has not been established, CNOP
will initiate an unnamed (private) control section.

CNOPbyte,boundary
symbol

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
|
|
|

|
|

The name is assigned to the next halfword aligned location. There may be a
single byte before that location, but this is skipped for alignment. There may be
zero or more NOP(R)s generated at or after that location.
byte
is an absolute expression that specifies at which even-numbered byte in a
fullword, doubleword, or quadword the location counter is set. The value of the
expression must be 0 to boundary-2.
boundary
is an absolute expression that specifies the byte specified by boundary is in a
fullword, doubleword, or quadword. A value of 4 indicates the byte is in a
fullword, a value of 8 indicates the byte is in a doubleword, and a value of 16
indicates the byte is in a quadword.
Figure 29 shows valid pairs of byte and word.
Figure 29 (Page 1 of 2). Valid CNOP Values
Values

Specify

0,4

Beginning of a word

2,4

Middle of a word

0,8

Beginning of a doubleword

2,8

Second halfword of a doubleword

4,8

Middle (third halfword) of a doubleword

6,8

Fourth halfword of a doubleword

0,16

Beginning of a quadword

2,16

Second halfword of a quadword

4,16

Third halfword of a quadword

6,16

Fourth halfword of a quadword

8,16

Fifth halfword of a quadword

Chapter 5. Assembler Instruction Statements

119

CNOP Instruction

Figure 29 (Page 2 of 2). Valid CNOP Values

Values

Specify

10,16

Sixth halfword of a quadword

12,16

Seventh halfword of a quadword

14,16

Eighth halfword of a quadword

Figure 30 shows the position in a doubleword that each of these pairs specifies.
Note that both 0,4 and 2,4 specify two locations in a doubleword.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

Quadword

Doubleword

Fullword

Halfword

Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte Byte

,4
2,4
,4
2,4
,4
2,4
,4
2,4

,8
2,8
4,8
6,8
,8
2,8
4,8
6,8

,16
2,16
4,16
6,16
8,16
1,16
12,16
14,16

Figure 30. CNOP Alignment

Use the CNOP instruction, for example, when you code the linkage to a subroutine,
and you want to pass parameters to the subroutine in fields immediately following
the branch and link instructions. These parametersfor example, channel
command wordscan require alignment on a specific boundary. The subroutine
can then address the parameters you pass through the register with the return
address, as in the following example:
LINK

CNOP
BALR
CCW

6,8
2,1
1,DATADR,X'48',X'5'

Assume that the location counter is aligned at a doubleword boundary. Then the
CNOP instruction causes the following no-operations to be generated, thus aligning
the BALR instruction at the last halfword in a doubleword as follows:

|
|
|

LINK

BCR
BC
BALR
CCW

,
,X'7'
2,1
1,DATADR,X'48',X'5'

After the BALR instruction is generated, the location counter is at a doubleword

boundary, thereby ensuring that the CCW instruction immediately follows the
branch and link instruction.
The CNOP instruction forces the alignment of the location counter to a halfword,
fullword, doubleword or quadword boundary. It does not affect the location counter
if the counter is already correctly aligned. If the specified alignment requires the
location counter to be incremented, no-operation instructions are generated to fill
the skipped bytes. Any single byte skipped to achieve alignment to the first
no-operation instruction is filled with zeros, even if the preceding byte contains no
machine language object code. A length attribute reference to the name of a
CNOP instruction is always invalid. Message ASMA042E will be issued, and a
default value of 1 is assigned.

120

HLASM V1R5 Language Reference

COM Instruction

COM Instruction
The COM instruction identifies the beginning or continuation of a common control
section.

COM
symbol

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
The COM instruction can be used anywhere in a source module after the ICTL
instruction.
If symbol denotes an ordinary symbol, the ordinary symbol identifies the common
control section. If several COM instructions within a source module have the same
symbol in the name field, the first occurrence initiates the common section and the
rest indicate the continuation of the common section. The ordinary symbol denoted
by symbol represents the address of the first byte in the common section, and has
a length attribute value of 1.
If symbol is not specified, or if name is a sequence symbol, the COM instruction
initiates, or indicates the continuation of, the unnamed common section.
See CSECT Instruction on page 123 for a discussion on the interaction between
COM and the GOFF assembler option.
The location counter for a common section is always set to an initial value of 0.
However, when an interrupted common control section is continued using the COM
instruction, the location counter last specified in that control section is continued.
If a common section with the same name (or unnamed) is specified in two or more
source modules, the amount of storage reserved for this common section is equal
to that required by the longest common section specified.
The source statements that follow a COM instruction belong to the common section
identified by that COM instruction.
Notes:
1. The assembler language statements that appear in a common control section
are not assembled into object code.
2. When establishing the addressability of a common section, the symbol in the
name field of the COM instruction, or any symbol defined in the common
section, can be specified in a USING instruction.
3. An AMODE cannot be assigned to a common section.

Chapter 5. Assembler Instruction Statements

121

COPY Instruction

In the following example, addressability to the common area of storage is

established relative to the named statement XYZ.

XYZ
PDQ

.
.
L
USING
MVC
.
.
COM
DS
DS
.
.

1,=A(XYZ)
XYZ,1
PDQ(16),=4C'ABCD'

16F
16C

A common control section may include any assembler language instructions, but no
object code is generated by the assembly of instructions or constants appearing in
a common control section. Data can only be placed in a common control section
through execution of the program.
If the common storage is assigned in the same manner by each independent
assembly, reference to a location in common by any assembly results in the same
location being referenced.

COPY Instruction
Use the COPY instruction to obtain source statements from a source language
library and include them in the program being assembled. You can thereby avoid
writing the same, often-used sequence of code over and over.

COPYmember
sequence_symbol

sequence_symbol
is a sequence symbol.
member
is an ordinary symbol that identifies a source language library member to be
copied from either a system macro library or a user macro library. In open
code it can also be a variable symbol that has been assigned a valid ordinary
symbol.
The source statements that are copied into a source module:
Are inserted immediately after the COPY instruction.
Are inserted and processed according to the standard instruction statement
coding format, even if an ICTL instruction has been specified.
Must not contain either an ICTL or ISEQ instruction.
Can contain other COPY statements. There are no restrictions on the number
of levels of nested copy instructions. However, the COPY nesting must not be
recursive. For example, assume that the source program contains the
statement:

122

HLASM V1R5 Language Reference

CSECT Instruction

COPY

and library member A contains the statement:

COPY

In this case, the library member B must not contain a COPY A or COPY B
statement.
Can contain macro definitions. Note, however, that if a source macro definition
is copied into a source module, both the MACRO and MEND statements that
delimit the definition must be contained in the same level of copied code.
Notes:
1. The COPY instruction can also be used to copy statements into source macro
definitions.
2. The rules that govern the occurrence of assembler language statements in a
source module also govern the statements copied into the source module.
3. Whenever the assembler processes a COPY statement, whether it is in open
code or in a macro definition, the assembler attempts to read the source
language library member specified in the COPY statement. This means that all
source language library members specified by COPY statements in a source
program, including those specified in macro definitions, must be available
during the assembly. The HLASM Programmer's Guide describes how to
specify the libraries when you run the assembler.
4. If an END instruction is encountered in a member during COPY processing, the
assembly is ended. Any remaining statements in the COPY member are
discarded.

CSECT Instruction
The CSECT instruction initiates an executable control section or indicates the
continuation of an executable control section.

CSECT
symbol

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
The CSECT instruction can be used anywhere in a source module after any ICTL
or *PROCESS statements. If it is used to initiate the first executable control
section, it must not be preceded by any instruction that affects the location counter
and thereby causes a control section to be initiated.
If symbol denotes an ordinary symbol, the ordinary symbol identifies the control
section. If several CSECT instructions within a source module have the same
Chapter 5. Assembler Instruction Statements

123

CSECT Instruction

symbol in the name field, the first occurrence initiates the control section and the
rest indicate the continuation of the control section. The ordinary symbol denoted
by symbol represents the address of the first byte in the control section, and has a
length attribute value of 1.
If symbol is not specified, or if name is a sequence symbol, the CSECT instruction
initiates, or indicates the continuation of the unnamed control section.
If the first control section is initiated by a START instruction, the CSECT instruction
which continues the section must have the same name as the START instruction.
When the GOFF option is not specified a control section is initiated or
resumed by the CSECT, RSECT, and COM statements. Any machine language
text created by statements that follow such control section declarations belongs to
the control section, and is manipulated during program linking and binding as an
indivisible unit.
When the GOFF option is specified, the behavior of CSECT, RSECT, and COM
statements is somewhat different. By default, the assembler creates a definition of
a text class named B_TEXT, to which subsequent machine language text belongs if
no other classes are declared. If you specify other class names using the CATTR
statement, machine language text following such CATTR statements belongs to
that class.
The combination of a section name and a class name defines an element, which is
the indivisible unit manipulated during linking and binding. All elements with the
same section name are owned by that section, and binding actions (such as
section replacement) act on all elements owned by a section.
When the GOFF option is specified, and if no CATTR statements are present, then
all machine language text is placed in the default class B_TEXT, and the behavior
of the elements in the bound module is essentially the same as the behavior of
control sections when the OBJECT option is specified. However, if additional
classes are declared, a section name can best be thought of as a handle by
which elements within declared classes are owned.
The beginning of a control section is aligned on a boundary determined by the
SECTALGN option. However, when an interrupted control section is continued
using the CSECT instruction, the location counter last specified in that control
section is continued. Consider the coding in Figure 31:

ALPHA

START
BALR 12,
USING
.
.
NEWCSECT CSECT
.
.
.
ALPHA
CSECT
.
.
.

ALPHA

NEWCSECT

Figure 31. How the Location Counter Works

124

HLASM V1R5 Language Reference

CXD Instruction

The source statements following a CSECT instruction that either initiate or indicate
the continuation of a control section are assembled into the object code of the
control section identified by that CSECT instruction.
The end of a control section or portion of a control section is marked by:
Any instruction that defines a new or continued control section
The END instruction
The CSECT instruction may interact with any LOCTR instructions that are present.
For more information about this interaction, see LOCTR Instruction on page 191.

CXD Instruction
The CXD instruction reserves a fullword area in storage. The linker or loader
inserts into this area the total length of all external dummy sections specified in the
source modules that are assembled and linked into one program. If a control
section has not previously been established, CXD will initiate an unnamed (private)
control section.

CXD
symbol

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
The linker or loader inserts into the fullword-aligned fullword area reserved by the
CXD instruction the total length of storage required for all the external dummy
sections specified in a program. If the GOFF assembler option is specified, CXD
returns the length of the B_PRV class. If symbol denotes an ordinary symbol, the
ordinary symbol represents the address of the fullword area. The ordinary symbol
denoted by symbol has a length attribute value of 4.
The following examples shows how external dummy sections may be used:
ROUTINE A
ALPHA
BETA
OMEGA

DXD
DXD
CXD
.
.
DC
DC
.
.

2DL8
4FL4

Q(ALPHA)
Q(BETA)

Chapter 5. Assembler Instruction Statements

125

DC Instruction

ROUTINE B
GAMMA
DELTA
ZETA

DXD
DXD
DXD
.
.
DC
DC
.
.

5D
1F
XL22

Q(GAMMA)
Q(DELTA)

ROUTINE C
EPSILON
ZETA

DXD
DXD
.
.
DC
.
.

4H
4F

Q(EPSILON,ZETA)

Each of the three routines is requesting an amount of work area. Routine A wants
2 doublewords and 4 fullwords; Routine B wants 5 doublewords, 10 fullwords, and
22 bytes; Routine C wants 4 halfwords and 4 fullwords. During program linking,
identically named dummy sections are combined, retaining their strictest alignment
and longest length. For example, Routines B and C both request storage named
ZETA: the resulting allocation will be 22 bytes on a fullword boundary. When
program linking is complete, the sum of these individual dummy external section
lengths is placed in the location of the CXD instruction labeled OMEGA. Routine A
can then allocate the amount of storage that is specified in the CXD location, and
each dummy external section's offset within the allocated storage is found in the
Q-type offset constant referencing its name. Q-type offset constants are described
at Offset ConstantQ on page 159.

|
|
|
|
|
|
|
|
|
|
|

DC Instruction
You specify the DC instruction to define the data constants you need for program
execution. The DC instruction causes the assembler to generate the binary
representation of the data constant you specify into a particular location in the
assembled source module; this is done at assembly time.
|
|
|
|
|
|

Note that the DC instruction's name Define Constant is somewhat misleading:

DC simply creates initial data in an area of the program. The contents of that area
may be modified during program execution, so the original data isn't truly
constant. If you want to declare values that are more likely to behave like
constants, use literals (Literals on page 40); the assembler attempts to detect and
diagnose instructions that might change the contents of a field defined by a literal.
If a control section has not been established previously, DC will initiate an unnamed
(private) control section.
The DC instruction can generate the following types of constants:

126

HLASM V1R5 Language Reference

DC Instruction

Figure 32. Types of Data Constants

Type of
Constant

Function

Example

Defines address mainly

for the use of fixed-point
and other instructions

ADCON

L
DC

5,ADCON
A(SOMWHERE)

Binary

Defines bit patterns

FLAG

B'1'

Character

Defines character strings

or messages

CHAR

C'string of characters'

Decimal

Used by decimal
instructions

PCON
AREA

ZAP
DC
DS

AREA,PCON
P'1'
PL3

Used by the fixed-point

and other instructions

FCON

L
DC

3,FCON
F'1'

Used by floating-point
instructions

ECON

LE
DC

2,ECON
E'1.5'

Address

Fixed-point
Floating-point
Graphic

Defines character strings

or messages that contain
pure double-byte data

DBCS

G'<.D.B.C.S. .S.T.R.I.N.G>'

Hexadecimal

Defines large bit patterns

PATTERN

X'FFFF'

,
operand
DC
symbol

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
If symbol denotes an ordinary symbol, the ordinary symbol represents the
address of the first byte of the assembled constant. If several operands are
specified, the first constant defined is addressable by the ordinary symbol. The
other constants can be reached by relative addressing.
operands
An operand of six subfields. The first five subfields describe the constant. The
sixth subfield provides the nominal values for the constants.
A DC operand has this format:

type
duplication_factor
type_extension
nominal_value
program_type modifier

Chapter 5. Assembler Instruction Statements

127

DC Instruction

duplication_factor
causes the nominal_value to be generated the number of times indicated by
this factor. See Subfield 1: Duplication Factor on page 132.
type
further determines the type of constant the nominal_value represents. See
Subfield 2: Type on page 133.
type_extension
determines some of the characteristics of the constant. See Subfield 3: Type
Extension on page 134.
|
|
|
|

program_type
assign a programmer determined 32-bit value to the symbol naming the DC
instruction, if a symbol was present. See Subfield 4: Program type on
page 135.
modifier
describes the length, the scaling, and the exponent of the nominal_value. See
Subfield 5: Modifier on page 136.
nominal_value
defines the value of the constant. See Subfield 6: Nominal Value on
page 140.
For example, in:
1EBP(7)L2'12'
the six subfields are:

Duplication factor is 1
Type is E
Type extension is B
Program type is P(7)
Modifier is L2
Nominal value is 12
If all subfields are specified, the order given above is required. The first, third,
fourth and fifth subfields can be omitted, but the second and sixth must be
specified in that order.

Rules for DC Operand

1. The type subfield and the nominal value must always be specified unless the
duplication factor is zero. If the duplication factor is zero, only the type must be
specified.
|

2. The duplication factor, type extension, program type, and modifier subfields are
optional.
3. When multiple operands are specified, they can be of different types.
4. When multiple nominal values are specified in the sixth subfield, they must be
separated by commas and be of the same type. Multiple nominal values are
not allowed for character or graphic constants.

|
|
|

5. The descriptive subfields, apart from the program type, apply to all the nominal
values. The program type applies to only the symbol naming the DC
instruction, if a symbol was present. Separate constants are generated for
each separate operand and nominal value specified.

128

HLASM V1R5 Language Reference

DC Instruction

6. No spaces are allowed:

Between subfields
Between multiple operands

General Information About Constants

Constants defined by the DC instruction are assembled into an object module at
the location at which the instruction is specified. However, the type of constant
being defined, and the presence or absence of a length modifier, determines
whether the constant is to be aligned on a particular storage boundary or not (see
Alignment of Constants).
Symbolic Addresses of Constants: The value of the symbol that names the DC
instruction is the address of the first byte (after alignment) of the first or only
constant.

Length Attribute Value of Symbols Naming Constants

The length attribute value assigned to the symbols in the name field of the
constants is equal to:
The implicit length (see Implicit Length in Figure 33) of the constant when no
explicit length is specified in the operand of the constant, or
The explicit length (see Value of Length Attribute in Figure 33) of the
constant.
If more than one operand is present, the length attribute value of the symbol is the
length in bytes of the first constant specified, according to its implicit or explicit
length.

Alignment of Constants
The assembler aligns constants on different boundaries according to the following:
On boundaries implicit to the type of constant (see Implicit Boundary
Alignment in Figure 34 on page 130) when no length is specified.
On byte boundaries (see Boundary Alignment in Figure 34) when an explicit
length is specified.
Bytes that are skipped to align a constant at the correct boundary are not
considered part of the constant. They are filled with binary zeros.
Notes:
1. The automatic alignment of constants and areas does not occur if the
NOALIGN assembler option has been specified.
2. Alignment can be forced to any boundary by a preceding DS or DC instruction
with a zero duplication factor. This occurs whether or not the ALIGN option is
set.
Figure 33 (Page 1 of 2). Length Attribute Value of Symbol Naming Constants
Type of
constant

Implicit
Length

Examples

Value of
Length
Attribute

as needed

B'11'

Chapter 5. Assembler Instruction Statements

129

DC Instruction

Figure 33 (Page 2 of 2). Length Attribute Value of Symbol Naming Constants

|
|
|
|

Examples

Value of
Length
Attribute

DC
DC
DC
DC

C'ABC'
CL8'WOW'
CU'ABC'
CUL4'XX'

3
8
6
4

as needed

DC
DC

G'<DaDb>'
GL8'<DaDb>'

4
8

as needed

DC
DC

X'COFFEE'
XL2'FFEE'

3
2

H
F
FD

2
4
8

DC
DC
DC

H'32'
FL3'32'
FD'32'

2
3
8

as needed

DC
DC
DC
DC

P'123'
PL4'123'
Z'123'
ZL1'123'

2
4
3
10

E
D
L
LQ

4
8
16
16

DC
DC
DC
DC

E'565.4'
DL6'565.4'
LL12'565.4'
LQ'565.4'

4
6
12
16

Y
A
AD

2
4
8

DC
DC
DC

Y(HERE)
AL1(THERE)
AD(WHERE)

2
1
8

S
V
VD
J
JD
Q
QD
R
RD

2
4
8
4
4
8
4
8

DC
DC
DC
DC
DC
DC
DC
DC
DC

S(THERE)
VL3(OTHER)
VD(BIGOTHER)
J(CLASS)
JD(LARGECLASS)
QL1(LITTLE)
QD(BIGLITTLE)
R(APSECT)
RD(BPSECT)

2
3
8
4
8
1
8
4
8

Type of
constant

Implicit
Length

as needed

Note:
1. Depends on whether or not an explicit length is specified in the constant.

Padding and Truncation of Values

The nominal values specified for constants are assembled into storage. The
amount of space available for the nominal value of a constant is determined:
By the explicit length specified in the length modifier, or
If no explicit length is specified, by the implicit length according to the type of
constant defined (see Appendix B, Summary of Constants on page 407).

130

HLASM V1R5 Language Reference

DC Instruction

Figure 34. Alignment of Constants

|
|
|
|

Type of
constant

Implicit
Boundary
Alignment

Examples

Boundary
Alignment

byte

B'111'

byte

C
CU

byte
byte

DC
DC

C'Character string'
CU'Character string'

byte
byte

byte

G'<.D.B.C.S

byte

X'22221222'

byte

halfword

fullword

doubleword

DC
DC
DC
DC
DC

H'25'
HL3'25'
F'225'
FL7'225'
FD'225'

halfword
byte
fullword
byte
doubleword

P
Z

byte
byte

DC
DC
DC

P'2934'
Z'1235'
ZL2'1235'

byte
byte
byte

fullword

doubleword

L
LQ

doubleword
quadword

DC
DC
DC
DC
DC
DC

E'1.25'
EL5'1.25'
8D'95'
8DL7'95'
L'2.57E65'
LQ'.1'

fullword
byte
doubleword
byte
doubleword
quadword

Y
A
AD
S

halfword
fullword
doubleword
halfword

fullword

VD
J
JD
Q
QD
R
RD

doubleword
fullword
doubleword
fullword
doubleword
fullword
doubleword

DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC

Y(HERE)
AL1(THERE)
AD(WHERE)
S(LABEL)
SL2(LABEL)
V(EXTERNAL)
VL3(EXTERNAL)
VD(BIGOTHER)
J(CLASS)
JD(LARGECLASS)
QL1(DUMMY)
QD(BIGDUMMY)
R(APSECT)
RD(BPSECT)

halfword
byte
doubleword
halfword
byte
fullword
byte
doubleword
fullword
doubleword
byte
doubleword
fullword
doubleword

.S.T.R.I.N.G>

Note:
1. Depends on whether or not an explicit length is specified in the constant.

The padding and truncation rules discussed below apply to single nominal values.

Padding
If more space is specified than is needed to accommodate the binary
representation of the nominal value, the extra space is padded:
With binary zeros on the left for the binary (B), hexadecimal (X), fixed-point
(H,F), packed decimal (P), and all address (A,Y,S,V,J,Q,R) constants
With sign extension for constants that support sign extension of the nominal
value (H, F, Y, A), as described in Figure 42 on page 149.
With EBCDIC zeros on the left (X'F0') for the zoned decimal (Z) constants

Chapter 5. Assembler Instruction Statements

131

DC Instruction

With EBCDIC spaces on the right (X'40') for the character (C) constants
With EBCDIC spaces on the right (X'40') for the Unicode character (CU)
constant prior to translation
With double-byte spaces on the right (X'4040') for the graphic (G) constants
Notes:
1. In floating-point constants (E,D,L), the fraction is extended to occupy the extra
space available.
2. Padding is on the left for all constants except the character constant and the
graphic constant.

Truncation
If less space is available than is needed to accommodate the nominal value, the
nominal value is truncated and part of the constant is lost. Truncation of the
nominal value is:
On the left for the binary (B), hexadecimal (X), fixed-point (H and F), and
decimal (P and Z)
On the right for the character (C) constant, the Unicode character (CU)
constant, and the graphic (G) constant
On the left for absolute or relocatable address (A and Y), the external address
(V), offset (Q), length (J) and PSECT address (R) constants. The actual value
stored and any possible truncation is dependent on the values inserted by the
linker/binder and the length of the constant.
Notes:
1. If significant bits are lost in the truncation of fixed-point constants, error
diagnostic message ASMA72E Data item too large is issued.
2. Floating-point constants (E, D, L) are not truncated. They are rounded to fit the
space availablesee Figure 50 on page 162 for rounding modes.
3. The above rules for padding and truncation also apply when using the
bit-length modifier (see Subfield 5: Modifier on page 136).
4. Double-byte data in C-type constants cannot be truncated because truncation
creates incorrect double-byte data. Error ASMA28E Truncation into
double-byte data is not permitted is issued if such truncation is attempted.
5. Truncation of double-byte data in CU-type and G-type constants is permitted
because the length modifier restrictions (see Subfield 5: Modifier on
page 136) ensure that incorrect double-byte data cannot be created by
truncation. However, truncating bit-length constants may create incorrect
double-byte data.

|
|

Subfield 1: Duplication Factor

The syntax for coding the duplication factor is shown in the subfield format on page
127.
You may omit the duplication factor. If specified, it causes the nominal value or
multiple nominal values specified in a constant to be generated the number of times
indicated by the factor. It is applied after the nominal value or values are

132

HLASM V1R5 Language Reference

DC Instruction

assembled into the constant. Symbols used in subfield 1 need not be previously
defined. This does not apply to literals.
The duplication factor can be specified by an unsigned decimal self-defining term or
by an absolute expression enclosed in parentheses.
The factor must have a positive value or be equal to zero.
Notes:
1. A duplication factor of zero is permitted, except for literals, with the following
results:
No value is assembled.
Alignment is forced according to the type of constant specified, if no length
attribute is present (see Alignment of Constants on page 129).
The length attribute of the symbol naming the constant is established
according to the implicitly or explicitly specified length.
When the duplication factor is zero, the nominal value may be omitted. The
alignment is forced, even if the NOALIGN option is specified.
When the duplication factor is zero for a literal, the assembler issues message
ASMA67S Illegal duplication factor.

|
|
|
|
|

2. If duplication is specified for an address constant whose nominal value contains

a location counter reference, the value of the location counter reference is
incremented by the length of the constant before each duplication is done (see
Address ConstantsA and Y on page 153). If the duplication factor is zero,
the value of the location counter reference is not incremented by the length of
each constant that would have been generated for a non-zero duplication
factor. Thus, in each of the following two statements, the first generates an
ASMA072E error message for "Data item too large", but the second does not:

|
|

A
B

DC Y(,32768-(-A))
DC Y(,32768-(-B))

However, if duplication is specified for an address-type literal constant

containing a location counter reference, the value of the location counter
reference is not incremented by the length of the literal before each duplication
is done. The value of the location counter reference is the location of the first
byte of the literal in the literal pool, and is the same for each duplication.
The location counter value is that of the instruction in which the literal appears
for A-type constants, but for S-type constants it is the location where the literal
actually appears.
3. The maximum value for the duplication factor is 2241, or X'FFFFFF' bytes. If
the maximum value for the duplication factor is exceeded, the assembler issues
message ASMA67S Illegal duplication factor.

Subfield 2: Type
The syntax for coding the type is shown in the subfield format on page 127.
You must specify the type subfield. From the type specification, the assembler
determines how to interpret the constant and translate it into the correct format.
The type is specified by a single-letter code as shown in Figure 35, the type
extension as shown in Figure 36.
Chapter 5. Assembler Instruction Statements

133

DC Instruction

Further information about these constants is provided in the discussion of the

constants themselves under Subfield 6: Nominal Value on page 140.
Figure 35. Type Codes for Constants
Code

Constant Type

Machine Format

Character

8-bit code for each character

Graphic

16-bit code for each character

Hexadecimal

4-bit code for each hexadecimal digit

Binary

Binary format

Fixed-point

Signed, fixed-point binary format; normally a fullword

Fixed-point

Signed, fixed-point binary format; normally a halfword

Floating-point

Short floating-point format; normally a fullword

Floating-point

Long floating-point format; normally a doubleword

Floating-point

Extended floating-point format; normally two doublewords

Decimal

Packed decimal format

Decimal

Zoned decimal format

Address

Value of address; normally a fullword

Address

Value of address; normally a halfword

Address

Base register and displacement value; a halfword

Address

Space reserved for external symbol addresses; normally a

fullword

Address

Space reserved for length of class or DXD; normally a

fullword

Address

Space reserved for external dummy section offset

Address

Space reserved for PSECT addresses; normally a fullword

The type in conjunction with an optional type extension specification indicates to the
assembler:
1. How to assemble the nominal value(s) specified in subfield 6; that is, which
binary representation or machine format the object code of the constant must
have.
2. At what boundary the assembler aligns the constant, if no length modifier is
present.
3. How much storage the constant occupies, according to the implicit length of the
constant, if no explicit length modifier is present (for details, see Padding and
Truncation of Values on page 130).

Subfield 3: Type Extension

The syntax for coding the type extension is shown in the subfield format on page
127.
You may omit the type extension subfield. If specified, the assembler, using this
field in conjunction with the type subfield, determines how to interpret the constant
and translate it into the correct format. The type extension is specified by a
single-letter code as shown in Figure 36.

134

HLASM V1R5 Language Reference

DC Instruction

Figure 36. Type Extension Codes for Constants

Type

Type
Extension

Description

ASCII character constant

EBCDIC character constant

Unicode UTF-16 character constant

New hexadecimal floating-point constant

Binary floating-point constant

New hexadecimal floating-point constant

Binary floating-point constant

New hexadecimal floating-point constant

Binary floating-point constant

Hexadecimal floating-point, quadword alignment

Doubleword fixed-point constant

Doubleword address constant

The type extension specification, in conjunction with the type subfield, indicates to
the assembler:
1. How to assemble the nominal value(s) specified in subfield 6; that is, which
binary representation or machine format the object code of the constant must
have.
2. At what boundary the assembler aligns the constant, if no length modifier is
present.
3. How much storage the constant occupies, according to the implicit length of the
constant, if no explicit length modifier is present (for details, see Padding and
Truncation of Values on page 130).

Subfield 4: Program type

|
|

The syntax for coding the program type is shown in the subfield format on page
127.

|
|
|
|
|

You may omit the program type subfield. If specified, the assembler assigns the
value to the symbol naming the DC instruction, if a symbol was present. It can be
specified as a decimal, character, hex or binary self-defining term and is stored as
a 32-bit value. The value is not used in any way by the assembler, and may be
queried by using the SYSATTRP built-in function.

|
|

The program type is specified within a P prefixed set of parenthesis - P(). For
example:

|
|

Prog1
Prog2

DC
DC

CP(7)'Perth'
3XP(C'APC')'FF'

Program type is 7
Program type is C'APC'

Chapter 5. Assembler Instruction Statements

135

DC Instruction

|
|

Symbols used in subfield 4 need not be previously defined, except in literals. For
example:

|
|

SYM
Rate5

All expressions in program type must be evaluatable when the DC is processed.

|
|

If program type is omitted, the assembler assigns a null to the program type, and
querying the value using the SYSATTRP build-in function returns a null value.

DC
EQU

FP(Rate5)'35.92'
5

Subfield 5: Modifier
The syntax for coding the modifier is shown in the subfield format on page 127.
You may omit the modifier subfield. Modifiers describe the length in bits or bytes
you want for a constant (in contrast to an implied length), and the scaling and
exponent for the constant.
The three modifiers are:
The length modifier (L), that explicitly defines the length in bytes you want for a
constant. For example:
LENGTH

XL1'FF'

The scale modifier (S), that is only used with the fixed-point or floating-point
constants (for details, see Scale Modifier on page 138). For example:
SCALE

FS8'35.92'

The exponent modifier (E), that is only used with fixed-point or floating-point
constants, and indicates the power of 10 by which the constant is to be
multiplied before conversion to its internal binary format. For example:
EXPON

EE3'3.414'

If multiple modifiers are used, they must appear in this sequence: length, scale, and
exponent. For example:
ALL3

DL7S3E5'2.7182'

Symbols used in subfield 5 need not be previously defined, except in literals. For
example:
SYM
X

DC
EQU

FS(X)'35.92'
7

Length Modifier
The length modifier indicates the number of bytes of storage into which the
constant is to be assembled. It is written as Ln, where n is either a decimal
self-defining term or an absolute expression enclosed by parentheses. It must
have a positive value.
When the length modifier is specified:
Its value determines the number of bytes of storage allocated to a constant. It
therefore determines whether the nominal value of a constant must be padded
or truncated to fit into the space allocated (see Padding and Truncation of
Values on page 130).

136

HLASM V1R5 Language Reference

DC Instruction

No boundary alignment, according to constant type, is provided (see Alignment

of Constants on page 129).
Its value must not exceed the maximum length allowed for the various types of
constant defined.
|
|

The length modifier must not truncate double-byte data in a C-type constant,
except for bit-length modifiers.
The length modifier must be a multiple of 2 in a G-type or CU-type constant.
When no length is specified, for character and graphic constants (C and G),
hexadecimal constants (X), binary constants (B), and decimal constants (P and Z),
the whole constant is assembled into its implicit length.
Bit-Length Modifier: The length modifier can be specified to indicate the number
of bits into which a constant is to be assembled. The bit-length modifier is written
as L.n where n is either a decimal self-defining term, or an absolute expression
enclosed in parentheses. It must have a positive value. Such a modifier is
sometimes called a bit-length modifier, to distinguish it from a byte-length
modifier. You may not combine byte-length and bit-length modifiers. For example, a
12-bit field must be written L.12, not L1.4.
The value of n must lie between 1 and the number of bits (a multiple of 8) that are
required to make up the maximum number of bytes allowed in the type of constant
being defined. The bit-length modifier can never be used with the CU-, G-, S-, V-,
R-, J- and Q-type constants, and cannot be used with the A-type or Y-type constant
if the operand is simply or complexly relocatable.
When only one operand and one nominal value are specified in a DC instruction,
the following rules apply:
1. The bit-length modifier allocates a field into which a constant is to be
assembled. The field starts at a byte boundary and can run over one or more
byte boundaries, if the bit length is greater than 8.
If the field does not end at a byte boundary and if the bit length is not a
multiple of 8, the remainder of the last byte is filled with binary zeros. For
example, DC FL.12'-1' generates X'FFF'.
2. The nominal value of the constant is assembled into the field:
a. Starting at the high order end for the C-, E-, D-, and L-type constants
b. Starting at the low-order end for the remaining types of constants that
support a bit-length modifier
3. The nominal value is padded or truncated to fit the field (see Padding and
Truncation of Values on page 130).

|
|
|

Note that padding is not the same as filling. In padding, the designated bit
field is completed according to the rules for the constant type. Filling is always
binary zeros placed at the right end of an incomplete byte.

|
|
|
|

C-type character constants are padded with EBCDIC spaces (hexadecimal

X'40', and CA-type character constants are padded with ASCII spaces
(hexadecimal X'20'). Other constant types are padded either by sign
extension or with zeros, according to the type of the constant.

Chapter 5. Assembler Instruction Statements

137

DC Instruction

The length attribute value of the symbol naming a DC instruction with a specified bit
length is equal to the minimum number of integral bytes needed to contain the bit
length specified for the constant. Consider the following example:
TRUNCF

FL.12'276'

L'TRUNCF is equal to 2. Thus, a reference to TRUNCF addresses both the two bytes
that are assembled.
When more than one operand is specified in a DC instruction, or more than one
nominal value in a DC operand, the above rules about bit-length modifiers also
apply, except:
1. The first field allocated starts at a byte boundary, but the succeeding fields start
at the next available bit. For example, BL1 DC FL.12'-1,1' generates
X'FFF3E8'.
2. After all the constants have been assembled into their respective fields, the bits
remaining to make up the last byte are filled with zeros. For example, BL2 DC
FL.12'-1,1,-2' generates X'FFF3E8FFE'
If duplication is specified, filling with zeros occurs once at the end of all the
fields occupied by the duplicated constants. For example, BL3 DC 3FL.12'-2'
generates X'FFEFFEFFE'.
3. The length attribute value of the symbol naming the DC instruction is equal to
the number of integral bytes needed to contain the bit length specified for the
first constant to be assembled. For example, the symbols BL1, BL2, and BL3
in the preceding examples each have length attribute 2.
For Double-Byte Data in C-Type Constants: If bit-lengths are specified, with a
duplication factor greater than 1, and a bit-length which is not a multiple of 8, then
the double-byte data is no longer valid for devices capable of presenting DBCS
characters. No error message is issued.
Storage Requirement for Constants: The total amount of storage required to
assemble a DC instruction is the sum of:
1. The requirements for the individual DC operands specified in the instruction.
The requirement of a DC operand is the product of:
The sum of the lengths (implicit or explicit) of each nominal value
The duplication factor, if specified
2. The number of bytes skipped for the boundary alignment between different
operands; such skipped bytes are filled with binary zeros.

Scale Modifier
The scale modifier specifies the amount of internal scaling that you want for:
Binary digits for fixed-point constants (H, F)
Hexadecimal digits for floating-point constants (E, D, L)
The scale modifier can be used only with the above types of constants. It cannot
be used with EB, DB, and LB floating point constants.
The range for each type of constant is:
Fixed-point constant H
Fixed-point constant F

138

HLASM V1R5 Language Reference

187 to +346
187 to +346

DC Instruction

Floating-point constant E, EH
Floating-point constant D, DH
Floating-point constant L, LH

0 to 14
0 to 14
0 to 28

The scale modifier is written as Sn, where n is either a decimal self-defining term,
or an absolute expression enclosed in parentheses. Both forms of the modifier's
value n can be preceded by a sign; if no sign is present, a plus sign is assumed.
Scale Modifier for Fixed-Point Constants: The scale modifier for fixed-point
constants specifies the power of two by which the fixed-point constant must be
multiplied after its nominal value has been converted to its binary representation,
but before it is assembled in its final scaled form. Scaling causes the binary point
to move from its assumed fixed position at the right of the rightmost bit position.
Notes:
1. When the scale modifier has a positive value, it indicates the number of binary
positions occupied by the fractional portion of the binary number.
2. When the scale modifier has a negative value, it indicates the number of binary
positions deleted from the integer portion of the binary number.
3. When low-order positions are lost because of scaling (or lack of scaling),
rounding occurs in the leftmost bit of the lost portion. The rounding is reflected
in the rightmost position saved.
Scale Modifier for Hexadecimal Floating-Point Constants: The scale modifier
for hexadecimal floating-point constants must have a positive value. It specifies the
number of hexadecimal positions that the fractional portion of the binary
representation of a floating-point constant is shifted to the right. The hexadecimal
point is assumed to be fixed at the left of the leftmost position in the fractional field.
When scaling is specified, it causes an unnormalized hexadecimal fraction to be
assembled (unnormalized means the leftmost positions of the fraction contain
hexadecimal zeros). The magnitude of the constant is retained, because the
exponent in the characteristic portion of the constant is adjusted upward
accordingly. When non-zero hexadecimal positions are lost, rounding occurs in the
leftmost hexadecimal position of the lost portion. The rounding is reflected in the
rightmost position saved.

Exponent Modifier
The exponent modifier specifies the power of 10 by which the nominal value of a
constant is to be multiplied before it is converted to its internal binary
representation. It can only be used with the fixed-point (H and F) and floating-point
(E, D, and L) constants. The exponent modifier is written as En, where n can be
either a decimal self-defining term, or an absolute expression enclosed in
parentheses.
The decimal self-defining term or the expression can be preceded by a sign. If no
sign is present, a plus sign is assumed. The range for the exponent modifier is 85
to +75. If a type extension is used to define a floating-point constant, the exponent
modifier can be in the range 231 to 2311. If the nominal value cannot be
represented exactly, a warning message is issued.

Chapter 5. Assembler Instruction Statements

139

DC Instruction

Notes:
1. Don't confuse the exponent modifier with the exponent that can be specified in
the nominal value subfield of fixed-point and floating-point constants.
The exponent modifier affects each nominal value specified in the operand,
whereas the exponent written as part of the nominal value subfield only affects
the nominal value it follows. If both types of exponent are specified in a DC
operand, their values are added together before the nominal value is converted
to binary form. However, this sum must lie within the permissible range of 85
to +75, unless a type extension is specified.
2. The value of the constant, after any exponents have been applied, must be
contained in the implicitly or explicitly specified length of the constant to be
assembled.

Subfield 6: Nominal Value

The syntax for coding the nominal value is shown in the subfield format on page
127.
You must specify the nominal value subfield unless a duplication value of zero is
specified. It defines the value of the constant (or constants) described and affected
by the subfields that precede it. It is this value that is assembled into the internal
binary representation of the constant. Figure 37 shows the formats for specifying
constants.
Figure 37. Specifying Constant Values
Constant
Type

Single
Nominal Value

Multiple
Nominal Value

Page No.

'value'

not allowed

142

'<.v.a.l.u.e>'

not allowed

145

B
X
H
F
P
Z
E
D
L

'value'

'value,value,...value'

141
147
148
148
151
151
161, 167
161, 167
161, 167

A
Y
S
V
R

(value)

(value,value,...value)

153
153
153
153
153

(value)

(value,value,...value)

159

(value)

(value,value,...value)

160

As the above list shows:

A data constant value (any type except A, Y, S, Q, J, R and V) is enclosed by
single quotation marks.
An address constant value (type A, Y, S, V, R) or an offset constant (type Q) or
a length constant (type J) is enclosed by parentheses.

140

HLASM V1R5 Language Reference

DC InstructionBinary Constant

To specify two or more values in the subfield, the values must be separated by
commas, and the whole sequence of values must be enclosed by the correct
delimiters; that is, single quotation marks or parentheses.
Multiple values are not permitted for character constants.
Spaces are allowed and ignored in nominal values for the quoted constant types
(BDEFHLPXZ). Spaces are significant for C and G constant types.
How nominal values are specified and interpreted by the assembler is explained in
each of the subsections that follow. There is a subsection for each of the following
types of constant:
Binary
Character
Graphic
Hexadecimal
Fixed-Point
Decimal
Packed Decimal
Zoned Decimal
Address
Floating-Point
Literal constants are described on page 171.

Binary ConstantB
The binary constant specifies the precise bit pattern assembled into storage. Each
binary constant is assembled into the integral number of bytes (see 1 in
Figure 38) required to contain the bits specified, unless a bit-length modifier is
specified.
The following example shows the coding used to designate a binary constant. BCON
has a length attribute of 1.
BCON
BTRUNC
BPAD
BFOUR

DC
DC
DC
DC

B'111111'
BL1'1111'
BL1'11'
B'1111 1 1111 1'

BTRUNC assembles with the leftmost bit truncated, as follows:

111
BPAD assembles with five zeros as padding, as follows:
11
Figure 38 (Page 1 of 2). Binary Constants

Subfield

Value

1. Duplication factor

Allowed

2. Type

3. Type Extension

Not Allowed

4. Program type

Allowed

Example

Result

Chapter 5. Assembler Instruction Statements

141

DC InstructionCharacter Constant

Figure 38 (Page 2 of 2). Binary Constants

Subfield
5. Modifiers
Implicit length:
(length modifier
not present)

Value

Example

Result

As needed

B
C

L'B = 1 1
L'C = 1 1

Alignment:

Byte

Range for length:

1 to 256
(byte length)

DC
DC

B'111111'
B'11'

.1 to .2048
(bit length)
Range for scale:

Not allowed

Range for exponent:

Not allowed

6. Nominal value
Represented by:

Binary digits
(0 or 1)

Enclosed by:

Single quotation
marks

Exponent allowed:

Number of values
per operand:

Multiple

Padding:

With zeros at left

Truncation of
assembled value:

At left

Character ConstantC
The character constant specifies character strings, such as error messages,
identifiers, or other text, that the assembler converts into binary representations. If
no type extension is provided, then the constant may be changed, depending on
the value of the TRANSLATE option. If the type extension of E is provided, then
the representation is also EBCDIC, but it cannot be changed by the TRANSLATE
option. For information about type extension A see ASCII data in character
constants on page 144, and for information about type extension U see Unicode
UTF-16 data from character constants on page 144.
Any of the 256 characters from the EBCDIC character set may be designated in a
character constant. Each character specified in the nominal value subfield is
assembled into one byte (see 1 in Figure 39 on page 143).
A null nominal value is permitted if a length is specified. For example:
DC

CL3''

is assembled as three EBCDIC spaces with object code X'404040', whereas

CAL3''

is assembled as three ASCII spaces with object code X'202020'.

Multiple nominal values are not allowed because a comma in the nominal value is
considered a valid character (see 2 in Figure 39) and is assembled into its binary

142

HLASM V1R5 Language Reference

DC InstructionCharacter Constant

(EBCDIC) representation (see Appendix D, Standard Character Set Code Table

on page 421). For example:
DC

C'A,B'

is assembled as A,B with object code X'C16BC2'.

Give special consideration to representing single quotation marks and ampersands
as characters. Each single quotation mark or ampersand you want as a character
in the constant must be represented by a pair of single quotation marks or
ampersands. Each pair of single quotation marks is assembled as one single
quotation mark, and each pair of ampersands is assembled as one ampersand (see
3 in Figure 39).
Figure 39 (Page 1 of 2). Character Constants
Subfield

Value

1. Duplication factor

Allowed

2. Type

3. Type Extension

U
A
C

4. Program type

Allowed

|
|

5. Modifiers
Implicit length:
(length modifier
not present)

Evaluate as an
even number, if
Type Extension of
U is specified

Alignment:

Byte

Range for length:

1 to 256
(byte length)

Example

Result

C
A
E

DC
DC
DC

CU'UNICODE'
CA'ASCII'
CE'EBCDIC'

L'C = 14
L'C = 5
L'E = 5

C'LENGTH'

L'C = 6

Must be a multiple
of 2 when the
Type Extension is U
.1 to .2048
(bit length)
(Not permitted
if Type Extension
of U is specified.)
Range for scale:

Not allowed

Range for exponent:

Not allowed

6. Nominal value
Represented by:

|
|

Characters
(all 256 8-bit
combinations)

Enclosed by:

Single quotation
marks

Exponent allowed:

No (would be
interpreted as
character data)

DC C'A''B'
DC CU'AA'
DC CA'AB'

Object code
X'C17DC2' 3
X'00410041'
X'4142'

Chapter 5. Assembler Instruction Statements

143

DC InstructionCharacter Constant

Figure 39 (Page 2 of 2). Character Constants

Subfield

Value

Example

Result

Number of values
per operand:

One

DC C'A,B'

Object code
X'C16BC2' 2

Padding:

With spaces at
right (X'40'
EBCDIC, X'20'
ASCII)

Truncation of
assembled value:

At right

|
|

In the following example, the length attribute of FIELD is 12:

FIELD

C'TOTAL IS 11'

However, in this next example, the length attribute is 15, and three spaces appear
in storage to the right of the zero:
FIELD

CL15'TOTAL IS 11'

In the next example, the length attribute of FIELD is 12, although 13 characters
appear in the operand. The two ampersands are paired, and so count as only one
byte.
FIELD

C'TOTAL IS &&1'

In the next example, a length of 4 has been specified, but there are five characters
in the constant.
FIELD

3CL4'ABCDE'

The generated constant would be:

ABCDABCDABCD
The same constant could be specified as a literal.
MVC

AREA(12),=3CL4'ABCDE'

On the other hand, if the length modifier had been specified as 6 instead of 4, the
generated constant would have been:
ABCDE ABCDE ABCDE (with one trailing space)
|
|
|
|
|
|

ASCII data in character constants: For Character ASCII (CA) constants the
character string is converted to ASCII, using the codepage 37 table. Any paired
occurrences of ampersands and apostrophes are converted to a single occurrence
of such a character prior to conversion. The assembler then maps each EBCDIC
character into its ASCII equivalent. This constant is not modified by the
TRANSLATE option.
Unicode UTF-16 data from character constants: For Character Unicode (CU)
constants the value is converted to Unicode UTF-16 using the code page identified
via the CODEPAGE assembler option. Any paired occurrences of ampersands and
apostrophes are converted to a single occurrence of such a character prior to
conversion. If necessary the value is padded with EBCDIC spaces on the right

144

HLASM V1R5 Language Reference

DC InstructionGraphic Constant

(X'40'). The assembler then maps each EBCDIC character into its 2-byte Unicode
UTF-16 equivalent.
For example:
UA
UB
UC

DC
DC
DC

CU'UTF-16'
CUL4'L'
CUL2'XYZ'

object code X' 5554462D3136'

object code X' 4C2'
object code X' 58'

Double-byte data in character constants: When the DBCS assembler option is

specified, double-byte data may be used in a character constant. The start of
double-byte data is delimited by SO, and the end by SI. All characters between SO
and SI must be valid double-byte characters. No single-byte meaning is drawn
from the double-byte data. Hence, special characters such as the single quotation
mark and ampersand are not recognized between SO and SI. The SO and SI are
included in the assembled representation of a character constant containing
double-byte data.
If a duplication factor is used, SI/SO pairs at the duplication points are not
removed. For example, the statement:
DBCS

3C'<D1>'

results in the assembled character string value of:

<D1><D1><D1>
Null double-byte data (SO followed immediately by SI) is acceptable and is
assembled into the constant value.
The following examples of character constants contain double-byte data:
DBCS
DBCS1
DBCS2
DBCS3

DC
DC
DC
DC

C'<>'
C'<.D.B.C.S>'
C'abc<.A.B.C>'
C'abc<.A.B.C>def'

The length attribute includes the SO and SI. For example, the length attribute of
DBCS is 2, and the length attribute of DBCS2 is 11. No truncation of double-byte
character strings within C-type constants is allowed, since incorrect double-byte
data would be created.
|

It is possible to generate invalid DBCS data in these situations:

|
|

You specify a bit-length modifier that causes truncation of the DBCS data or
the shift-out and shift-in characters.

You specify the TRANSLATE option.

Graphic ConstantG
When the DBCS assembler option is specified, the graphic (G-type) constant is
supported. This constant type allows the assembly of pure double-byte data. The
graphic constant differs from a character constant containing only double-byte data
in that the SO and SI delimiting the start and end of double-byte data are not
present in the assembled value of the graphic constant. Because SO and SI are
not assembled, if a duplication factor is used, no redundant SI/SO characters are
created. For example, the statement:
DBCS

3G'<D1>'

Chapter 5. Assembler Instruction Statements

145

DC InstructionGraphic Constant

results in the assembled character string value of:

D1D1D1
Examples of graphic constants are:
DBCS1
DBCS2
DBCS3

DC
DC
DC

G'<.A.B.C>'
GL1'<.A.B.C>'
GL4'<.A.B.C>'

Because the length attribute does not include the SO and SI, the length attribute of
DBCS1 is 6. The length modifier of 10 for DBCS2 causes padding of 2 double-byte
spaces at the right of the nominal value. The length modifier of 4 for DBCS3 causes
truncation after the first 2 double-byte characters. The length attribute of a graphic
constant must be a multiple of 2.
Type Attribute of G-Type Constant: Don't confuse the G-type constant character
with the type (data) attribute of a graphic constant. The type attribute of a graphic
constant is @, not G. See the general discussion about data attributes on page
324, and Type Attribute (T') on page 328.
Figure 40. Graphic Constants

Subfield

Value

Example

Result

1. Duplication factor

Allowed

DC 3G'<.A>'

Object code
X'42C142C142C1'

2. Type

3. Type Extension

Not allowed

4. Program type

Allowed
GC

L'GC = 4

DC
DC

G'<.&.'>'
G'<.A><.B>'

Object code
X'4250427D'
X'42C142C2'

G'<.A.,.B>'

Object code
X'42C1426B42C2'

GL6'<.A>'

Object code
X'42C140404040'

GL2'<.A.B>'

Object code
X'42C1'

5. Modifiers
Implicit length:
(length modifier
not present)
Alignment:

Byte

Range for length:

2 to 256, must be
multiple of 2
(byte length)
bit length not
allowed

6. Nominal value
Represented by:

DBCS characters
delimited by SO
and SI

Enclosed by:

Single quotation
marks

Number of values
per operand:

One

Padding:

With DBCS
spaces at right
(X'4040')

Truncation of
assembled value:

146

As needed
(twice the number
of DBCS
characters)

HLASM V1R5 Language Reference

G'<.A.B>'

At right

DC InstructionHexadecimal Constant

Hexadecimal ConstantX
Hexadecimal constants generate large bit patterns more conveniently than binary
constants. Also, the hexadecimal values you specify in a source module let you
compare them directly with the hexadecimal values generated for the object code
and address locations printed in the program listing.
Each hexadecimal digit (see 1 in Figure 41) specified in the nominal value
subfield is assembled into four bits (their binary patterns can be found in
Self-Defining Terms on page 34). The implicit length in bytes of a hexadecimal
constant is then half the number of hexadecimal digits specified (assuming that a
high-order hexadecimal zero is added to an odd number of digits). See 2 and
3 in Figure 41.
An 8-digit hexadecimal constant provides a convenient way to set the bit pattern of
a full binary word. The constant in the following example sets the first and third
bytes of a word with all 1 bits.
TEST

DS
DC

F
X'FFFF'

The DS instruction sets the location counter to a fullword boundary. (See DS

Instruction on page 174.)
The next example uses a hexadecimal constant as a literal and inserts a byte of all
1 bits into the rightmost 8 bits of register 5.
IC

5,=X'FF'

In the following example, the digit A is dropped, because 5 hexadecimal digits are
specified for a length of 2 bytes:
ALPHACON DC

3XL2'A6F4E'

Generates 6F4E 3 times

The resulting constant is 6F4E, which occupies the specified 2 bytes. It is

duplicated three times, as requested by the duplication factor. If it had been
specified as:
ALPHACON DC

3X'A6F4E'

Generates A6F4E 3 times

the resulting constant would have a hexadecimal zero in the leftmost position.
A6F4EA6F4EA6F4E
Figure 41 (Page 1 of 2). Hexadecimal Constants

Subfield

Value

1. Duplication factor

Allowed

2. Type

3. Type Extension

Not allowed

4. Program type

Allowed

5. Modifiers
Implicit length:
(length modifier
not present)
Alignment:

As needed

Example

Result

X
Y

L'X = 3 2
L'Y = 3 2

DC
DC

X'FFA2'
X'FA2'

Byte

Chapter 5. Assembler Instruction Statements

147

DC InstructionFixed-Point Constants

Figure 41 (Page 2 of 2). Hexadecimal Constants

Subfield
Range for length:

Value

Example

Result

DC
DC

Object code
X'1F' 1
X'091F' 3

1 to 256
(byte length)
.1 to .2048
(bit length)

Range for scale:

Not allowed

Range for exponent:

Not allowed

6. Nominal value
Represented by:

Hexadecimal
digits
(0 to 9 and
A to F)

Enclosed by:

Single quotation
marks

Exponent allowed:

Number of values
per operand:

Multiple

Padding:

With zeros at left

Truncation of
assembled value:

At left

X'1F'
X'91F'

Fixed-Point ConstantsF and H

Fixed-point constants let you introduce data that is in a form suitable for the
arithmetic operations of the binary fixed-point machine instructions. The constants
you define can also be automatically aligned to the correct doubleword, fullword or
halfword boundary for the instructions that refer to addresses on these boundaries
(unless the NOALIGN option has been specified; see General Information About
Constants on page 129). You can do algebraic operations using this type of
constant because they can have positive or negative values.
A fixed-point constant is written as a decimal number, which can be followed by a
decimal exponent. The format of the constant is as follows:
1. The nominal value can be a signed (see 1 in Figure 42 on page 149)
integer, fraction, or mixed number (see 2 Figure 42) followed by a signed
exponent (see 3 in Figure 42). If a sign is not specified for either the number
or exponent, + is assumed.
2. The exponent must lie within the permissible range (see 4 in Figure 42). If
an exponent modifier is also specified, the algebraic sum (see 5 in Figure 42)
of the exponent and the exponent modifier must lie within the permissible
range.
Some examples of the range of values that can be assembled into fixed-point
constants are given below:

148

HLASM V1R5 Language Reference

DC InstructionFixed-Point Constants

Length
8
4
2
1

Range of values that can

be assembled
263 to 2631
231 to 2311
215 to 2151
2 to 21

The range of values depends on the implicitly or explicitly specified length (if
scaling is disregarded). If the value specified for a particular constant does not lie
within the allowable range for a given length, the constant is not assembled, but
flagged as an error.
A fixed-point constant is assembled as follows:
1. The specified number, multiplied by any exponents, is converted to a binary
number.
2. Scaling is done, if specified. If a scale modifier is not provided, the fractional
portion of the number is lost.
3. The binary value is rounded, if necessary. The resulting number does not differ
from the exact number specified by more than one in the least significant bit
position at the right.
4. A negative number is carried in two's-complement form.
5. Duplication is applied after the constant has been assembled.
The statement below generates 3 fullwords of data. The location attribute of CONWRD
is the address of the first byte of the first word, and the length attribute is 4, the
implied length for a fullword fixed-point constant. The expression CONWRD+4 could
be used to address the second constant (second word) in the field.
CONWRD

3F'658474'

Figure 42 (Page 1 of 2). Fixed-Point Constants

Subfield

Value

1. Duplication factor

Allowed

2. Type

F and H

3. Type Extension

D permitted with
type F

4. Program type

Allowed

5. Modifiers
Implicit length:
(length modifier
not present)

Doubleword: 8 bytes
Fullword: 4 bytes
Halfword: 2 bytes

Alignment:
(Length modifier
not present)

Doubleword,
fullword or
halfword

Range for length:

1 to 8
(byte length)

Example

Result

.1 to .64
(bit length)

Chapter 5. Assembler Instruction Statements

149

DC InstructionFixed-Point Constants

Figure 42 (Page 2 of 2). Fixed-Point Constants

Subfield

Value

Example

Result

value=2x10

Range for scale:

F: 187 to +346
H: 187 to +346

Range for exponent:

85 to +75 4

DC HE+75'2E73'
5

Decimal
digits
(0 to 9)

Doubleword
DC FD'2' 1

6. Nominal value
Represented by:

Fullword
DC FS4'2.25' 2
Halfword:
DC H'+2'
DC HS4'.25'
Enclosed by:

Single quotation
marks

Exponent allowed:

Yes

Doubleword:
DC FD'2E6'
Fullword:
DC F'2E6' 3
Halfword:
DC H'2E6'

Number of values
per operand:

Multiple

Padding:

With sign bits at

left

Truncation of
assembled value:

At left
(error message
issued)

In the following example, the DC statement generates a 2-byte field containing a

negative constant. Scaling has been specified in order to reserve 6 bits for the
fractional portion of the constant.
HALFCON

HS6'25.46'

In the following example, the constant (3.50) is multiplied by 10 to the power 2

before being converted to its binary format. The scale modifier reserves 12 bits for
the fractional portion.
FULLCON

HS12'3.5E2'

The same constant could be specified as a literal:

7,=HS12'3.5E2'

The final example specifies three constants. The scale modifier requests 4 bits for
the fractional portion of each constant. The 4 bits are provided whether or not the
fraction exists.
THREECON DC

150

HLASM V1R5 Language Reference

FS4'1,25.3,1'

DC InstructionDecimal Constants

|
|

Remember that commas separate operands. For readability, use spaces instead,
as shown in this example:

|
|

TWOCONS
ONECON

DC
DC

F'123,445'
F'123 456'

Two constants
One constant

Decimal ConstantsP and Z

The decimal constants let you introduce data in a form suitable for operations on
decimal data. The packed decimal constants (P-type) are used for processing by
the decimal instructions. The zoned decimal constants (Z-type) are in the form
(EBCDIC representation) you can use as a print image, except for the digit in the
rightmost byte.
The nominal value can be a signed (plus is assumed if the number is unsigned)
decimal number. A decimal point may be written anywhere in the number, or it
may be omitted. The placement of a decimal point in the definition does not affect
the assembly of the constant in any way, because the decimal point is not
assembled into the constant; it only affects the integer and scaling attributes of the
symbol that names the constant.
The specified digits are assumed to constitute an integer (see 1 in Figure 43).
You may determine correct decimal point alignment either by defining data so that
the point is aligned or by selecting machine instructions that operate on the data
correctly (that is, shift it for purposes of decimal point alignment).
Decimal constants are assembled as follows:
Packed Decimal Constants: Each digit is converted into its 4-bit binary coded
decimal equivalent (see 2 in Figure 43). The sign indicator (see 3 in
Figure 43) is assembled into the rightmost four bits of the constant.
Zoned Decimal Constants: Each digit is converted into its 8-bit EBCDIC
representation (see 4 in Figure 43). The sign indicator (see 5 in Figure 43)
replaces the first four bits of the low-order byte of the constant.
The range of values that can be assembled into a decimal constant is shown
below:
Type of
decimal
constant

Range of values that

can be specified

Packed
Zoned

10311 to 1031
10161 to 1016

For both packed and zoned decimals, a plus sign is translated into the hexadecimal
digit C, a minus sign into the digit D. The packed decimal constants (P-type) are
used for processing by the decimal instructions.
If, in a constant with an implicit length, an even number of packed decimal digits is
specified, one digit is left unpaired because the rightmost digit is paired with the
sign. Therefore, in the leftmost byte, the leftmost four bits are set to zeros and the
rightmost four bits contain the unpaired (first) digit.

Chapter 5. Assembler Instruction Statements

151

DC InstructionDecimal Constants

Figure 43. Decimal Constants

Subfield

Value

1. Duplication factor

Allowed

2. Type

P and Z

3. Type Extension

Not allowed

4. Program type

Allowed

5. Modifiers
Implicit length:
(length modifier
not present)

As needed

Alignment:

Byte

Range for length:

1 to 16
(byte length)

Example

Result

Packed:
P DC P'+593'

L'P = 2

Zoned:
Z DC Z'593'

L'Z= 3

Packed:
DC P'5.5' 1
DC P'55' 1
DC P'+555' 2
DC P'-777'

Object code
X'055C'
X'055C'
X'555C' 3
X'777D' 3

.1 to .128
(bit length)
Range for scale:

Not allowed

Range for exponent:

Not allowed

6. Nominal value
Represented by:

Decimal
digits
(0 to 9)

Zoned:
DC Z'555' 4
Enclosed by:

Single quotation
marks

Exponent allowed:

Number of values
per operand:

Multiple

Padding:

Packed:
with binary
zeros at left

Object code
X'F5F5D5' 5

Zoned:
with EBCDIC
zeros (X'F0')
at left
Truncation of
assembled value:

At left

In the following example, the DC statement specifies both packed and zoned
decimal constants. The length modifier applies to each constant in the first
operand (that is, to each packed decimal constant). A literal could not specify both
operands.

152

HLASM V1R5 Language Reference

DC InstructionAddress Constants

DECIMALS DC

PL8'+25.8,3874,+2.3',Z'+8,3.72'

The last example shows the use of a packed decimal literal.

UNPK

OUTAREA,=PL2'+25'

Address Constants
An address constant is an absolute or relocatable expression, such as a storage
address, that is translated into a constant. Address constants can be used for
initializing base registers to facilitate the addressing of storage. Furthermore, they
provide a means of communicating between control sections of a multisection
program. However, storage addressing and control section communication also
depends on the USING assembler instruction and the loading of registers. See
USING Instruction on page 218.
The nominal value of an address constant, unlike other types of constants, is
enclosed in parentheses. If two or more address constants are specified in an
operand, they are separated by commas, and the whole sequence is enclosed by
parentheses. There are seven types of address constants: A, Y, S, R, Q, J and V.
A relocatable address constant may not be specified with bit lengths.
Complex Relocatable Expressions: A complex relocatable expression can only
specify an A-or Y-type address constant. These expressions contain two or more
unpaired relocatable terms, or two or more negative relocatable terms in addition to
any absolute or paired relocatable terms. A complex relocatable expression might
consist of external symbols and designate an address in an independent assembly
that is to be linked and loaded with the assembly containing the address constant.
The following example shows how, and why, a complex relocatable expression
could be used for an A or Y address constant:
B

EXTRN
DC

X
A(X-)

Offset from B to X

Address ConstantsA and Y: The following sections describe how the different
types of address constants are assembled from expressions that usually represent
storage addresses, and how the constants are used for addressing within and
between source modules.
In the A-type and Y-type address constants, you can specify any of the three
following types of assembly-time expressions whose values the assembler then
computes and assembles into object code. Use this expression computation as
follows:
Relocatable expressions for addressing
Absolute expressions for addressing and value computation
Complex relocatable expressions to relate addresses in different source
modules
Literals, which are relocatable forms, are not allowed as operands, but length, scale
and integer attribute references to literals are allowed.
Here are some examples:

Chapter 5. Assembler Instruction Statements

153

DC InstructionAddress Constants

DC
DC
DC

A(L'=F'1.23')
A(I'=F'3.45')
A(S'=FS6'7.89)

Notes:
1. No bit-length modifier (see 1 in Figure 44) is allowed when a relocatable or
complex relocatable expression (see 2 in Figure 44) is specified. The only
explicit lengths that can be specified with relocatable or complex relocatable
address constants are:
2 through 8 bytes for AD-type constants
2, 3, or 4 bytes for A-type constants
2 bytes for Y-type constants
The linkage editor/binder/loader you use determines which lengths are actually
supported. Please see the appropriate product manual for more information.
For absolute operands, you may specify byte or bit lengths:
byte lengths 1 through 8, or bit lengths .1 through .128, for A-type
constants
byte lengths 1 or 2, or bit lengths .1 through .16, for Y-type constants
2. The value of the location counter reference (*) when specified in an address
constant varies from constant to constant, if any of the following, or a
combination of the following, are specified:
Multiple operands
Multiple nominal values (see 3 in Figure 44)
A duplication factor (see 4 in Figure 44)
The location counter is incremented with the length of the previously assembled
constant.
3. When the location counter reference occurs in a literal address constant, the
value of the location counter is the address of the first byte of the instruction.
Note that the behavior of location counter references in A-type address
constants is different from that in S-type address constants (Address
ConstantS on page 156).
Figure 44 (Page 1 of 2). A and Y Address Constants

Subfield

Value

Example

1. Duplication factor

Allowed

2. Type

A and Y

3. Type Extension

D permitted for A
type only

4. Program type

Allowed

5. Modifiers
Implicit length:
(length modifier
not present)

A-type: 4 bytes
AD-type: 8 bytes
Y-type: 2 bytes

Alignment:
(Length modifier
not present)

154

HLASM V1R5 Language Reference

A-type: fullword
AD-type: doubleword
Y-type: halfword

Result

5AL1(A) 4 Object code

X'0001020304'

DC InstructionAddress Constants

Figure 44 (Page 2 of 2). A and Y Address Constants

Subfield
Range for length:

Value

Example

Result

A-type:
2 to 4 1
(byte length)
AD-type:
2 to 8
(byte length)
Y-type:
2 only
(byte length)

Range for scale:

Not allowed

Range for exponent:

Not allowed

6. Nominal value
Represented by:

Absolute,
relocatable,
or complex
relocatable
expressions 2

A-type:
DC A(ABSOL+1)
Y-type:
DC Y(RELOC+32)
A DC Y(A,+4) 3values=0,A+6

Enclosed by:

Parentheses

Exponent allowed:

Number of values
per operand:

Multiple

Padding:

If an absolute
term is present, by
sign extension.
Otherwise, with
zeros at left.

Truncation of
assembled value:

At left

Take care when using Y-type address constants and 2-byte A-type address
constants for relocatable addresses, as they can only address a maximum of
65,536 bytes of storage. Using these types of address constants for relocatable
addresses results in message ASMA066W being issued unless the assembler
option RA2 is specified.
The A-type and Y-type address constants are processed as follows: If the nominal
value is an absolute expression, it is computed to its 32-bit value and then
truncated or sign-extended on the left to fit the implicit or explicit length of the
constant. If the nominal value is a relocatable or complex relocatable expression, it
is not completely evaluated until linkage edit time. The relocated address values
are then placed in the fields set aside for them at assembly time by the A-type and
Y-type constants.
In the following examples, the field generated from the statement named ACON
contains four constants, each of which occupies four bytes. The statement
containing the LM instruction shows the same set of constants specified as literals
(that is, address constant literals).

Chapter 5. Assembler Instruction Statements

155

DC InstructionAddress Constants

ACON

DC
LM

A(18,LOP,ENDSTRT,+496)
4,7,=A(18,LOP,ENDSTRT,+496)

A location counter reference () appears in the fourth constant (+496). The value
of the location counter is the address of the first byte of the fourth constant. When
the location counter reference occurs in a literal, as in the LM instruction, the value
of the location counter is the address of the first byte of the instruction.
Note: It is important to remember that expression evaluation for address constants
is restricted to using 32-bit internal arithmetic. The result is then sign-extended to
the length of the constant. This means that certain expressions in AD-type
constants may not yield expected results, especially if the resulting value is
negative.
Address ConstantS: Use the S-type address constant to assemble an explicit
address in base-displacement form. You can specify the explicit address yourself
or let the assembler compute it from an implicit address, using the current base
register and address in its computation.
The nominal values can be specified in two ways:
1. As one absolute or relocatable expression (see 1 in Figure 45 on page 157)
representing an implicit address.
2. As two absolute expressions (see 2 in Figure 45) the first of which
represents the displacement and the second, enclosed in parentheses,
represents the base register.
The address value represented by the expression in 1 in Figure 45, is converted
by the assembler into the correct base register and displacement value. An S-type
constant is assembled as a halfword and aligned on a halfword boundary. The
leftmost four bits of the assembled constant represent the base register
designation; the remaining 12 bits, the displacement value.
Notes:
1. The value of the location counter (*) when specified in an S-type address
constant varies from constant to constant if one or more the following is
specified:
Multiple operands
Multiple nominal values
A duplication factor
In each case the location counter is incremented with the length of the
previously assembled constant, except when multiple S-type address constants
are specified in a literal. In a literal, the same location counter value is used for
each of the multiple values.
2. If a length modifier is used, only 2 bytes may be specified.
3. S-type address constants can be specified as literals. The USING instructions
used to resolve them are those in effect at the place where the literal pool is
assembled, and not where the literal is used.
4. The location counter value used in the literal is the value at the point where the
literal is used, not where it is defined.
For example:

156

HLASM V1R5 Language Reference

DC InstructionAddress Constants

USING ,15
DC
2S()
LA
1,=2S()

generates FF2
generated constants are F4F4

Note that this behavior is different from that in A-type address constants and
Y-type address constants.
Figure 45. S Address Constants

Subfield

Value

1. Duplication factor

Allowed

2. Type

3. Type Extension

Not allowed

4. Program type

Allowed

5. Modifiers
Implicit length:
(length modifier
not present)

Example

Result

Absolute or
relocatable
expression 1

DC
DC

S(RELOC)
S(124)

Base Disp
X
YYY
0
400

Two absolute
expressions 2

S(512(12))

2 bytes

Alignment:
(Length modifier
not present)

Halfword

Range for length:

2 only
(no bit length)

Range for scale:

Not allowed

Range for exponent:

Not allowed

6. Nominal value
Represented by:

Enclosed by:

Parentheses

Exponent allowed:

Number of values
per operand:

Multiple

Padding:

Not applicable

Truncation of
assembled value:

Not applicable

200

Address ConstantV: The V-type constant reserves storage for the address of a
location in a control section that is defined in another source module. Use the
V-type address constant only to branch to an external address, because link-time
processing may cause the branch to be indirect (for example, an assisted linkage in
an overlay module). That is, the resolved address in a V-type address constant
might not contain the address of the referenced symbol. In contrast, to refer to
external data you should use an A-type address constant whose nominal value
specifies an external symbol identified by an EXTRN instruction.
Because you specify a symbol in a V-type address constant, the assembler
assumes that it is an external symbol. A value of zero is assembled into the space

Chapter 5. Assembler Instruction Statements

157

DC InstructionOffset Constant

reserved for the V-type constant; the correct relocated value of the address is
inserted into this space by the linkage editor before your object program is loaded.
The symbol specified (see 1 in Figure 46) in the nominal value subfield does not
constitute a definition of the symbol for the source module in which the V-type
address constant appears.
The symbol specified in a V-type constant must not represent external data in an
overlay program.
Figure 46. V Address Constants
Subfield

Value

1. Duplication factor

Allowed

2. Type

3. Type Extension

4. Program type

Allowed

5. Modifiers
Implicit length:
(length modifier
not present)

|
|

V-type: 4 bytes
VD-type: 8 bytes
V-type: Fullword
VD-type: Doubleword

Range for length:

V-type: 4 or 3 only
VD-type: 3, 4 or 8
(no bit length)

Range for scale:

Not allowed

Range for exponent:

Not allowed

6. Nominal value
Represented by:

Result

VL4(ExtSym)

Alignment:
(Length modifier
not present)

Example

A single external
symbol

Enclosed by:

Parentheses

Exponent allowed:

Number of values
per operand:

Multiple

Padding:

None

Truncation of
assembled value:

Not applicable

DC
DC

V(MODA) 1
V(EXTADR) 1

In the following example, 12 bytes are reserved, because there are three symbols.
The value of each assembled constant is zero until the program is link-edited.
VCONST

158

HLASM V1R5 Language Reference

V(SORT,MERGE,CALC)

DC InstructionLength Constant

Offset ConstantQ
Use this constant to reserve storage for the offset into a storage area of an external
dummy section, or the offset to a label in a class. The offset is entered into this
space by the linker. When the offset is added to the address of an overall block of
storage set aside for external dummy sections, it addresses the applicable section.
For a description of the use of the Q-type offset constant in combination with an
external dummy section, see External Dummy Sections on page 57. See also
Figure 47 for details.
In the following example, to access the external dummy section named VALUE, the
value of the constant labeled A is added to the base address of the block of
storage allocated for external dummy sections.
A

Q(VALUE)

The DXD or DSECT names referenced in the Q-type offset constant need not be
previously defined.
Figure 47. Q Offset Constants
Subfield

Value

1. Duplication factor

Allowed

2. Type

3. Type Extension

4. Program type

Allowed

|
|

5. Modifiers
Implicit length:
(length modifier
not present)

Example

Q(DXDEXT)
Q-type: 4 bytes
QD-type: 8 bytes

Alignment:
(Length modifier
not present)

Q-type: Fullword
QD-type: Quadword

Range for length:

Q-type: 1 to 4 bytes QL2(DXDEXT)

QD-type: 1 to 8 bytes
(no bit length)

Range for scale:

Not allowed

Range for exponent:

Not allowed

6. Nominal value
Represented by:

Result

A DXD or DSECT
name (an
external symbol)

Enclosed by:

Parentheses

Exponent allowed:

Number of values
per operand:

Multiple

Padding:

None

Truncation of
assembled value:

Not applicable

DC
DC

Q(DUMMYEXT)
Q(DXDEXT)

Chapter 5. Assembler Instruction Statements

159

DC InstructionLength Constant

Length ConstantJ
Use this constant to reserve storage for the length of a DXD, class or DSECT. The
assembler fills the field with binary zeros, and the length is entered into this space
by the linker. This constant is only available if the GOFF option is specified.
In the following example, the value at A is the length of CLASS.
A

J(CLASS)

The DXD or DSECT names referenced in the J-type length constant need not be
previously defined.
Figure 48. J Length Constants
Subfield

Value

1. Duplication factor

Allowed

2. Type

3. Type Extension

4. Program type

Allowed

5. Modifiers
Implicit length:
(length modifier
not present)

J-type: 4 bytes
JD-type: 8 bytes

Alignment:
(Length modifier
not present)

J-type: Fullword
JD-type: Doubleword

Range for length:

J-type: 2 to 4 bytes,
or 8
JD-type: 2 to 4 bytes,
or 8
(no bit length)

Range for scale:

Not allowed

Range for exponent:

Not allowed

|
|

6. Nominal value
Represented by:

A single DXD, class,

or DSECT name

Enclosed by:

Parentheses

Exponent allowed:

Number of values
per operand:

Multiple

Padding:

None.

Truncation of
assembled value:

At left

Example

Result

J(CLASS)

PSECT ReferenceR
The R-type constant reserves storage for the address of the PSECT of symbol1 as
specified in the associated XATTR statement (XATTR Instruction (MVS and CMS)
on page 230). It is the caller's responsibility to establish the definition of the R-type
address constant referencing the called routine's PSECT, and to pass that address
to the called routine. This constant is only available if the GOFF option is specified.

160

HLASM V1R5 Language Reference

DC InstructionHexadecimal Floating-Point Constants

Note: If a program is to be reentrant, R-type address constants may not appear in

shared (read-only) text. They should be in the caller's PSECT, and be provided to
the called routine using an appropriate convention. That is, R-type address
constants referring to PSECTs should themselves reside in PSECTs. If not, there
can be only a single instantiation of the PSECT work area, and the program cannot
be reentrant.
Figure 49. R Address Constants
Subfield

Value

1. Duplication factor

Allowed

2. Type

3. Type Extension

4. Program type

Allowed

|
|

5. Modifiers
Implicit length:
(length modifier
not present)

Example

R-type: 4 bytes
RD-type: 8 bytes

Alignment:
(Length modifier
not present)

R-type: Fullword
RD-type: Doubleword

Range for length:

R-type: 3 or 4 only
RD-type: 3, 4 or 8
(no bit length)

Range for scale:

Not allowed

Range for exponent:

Not allowed

6. Nominal value
Represented by:

Result

An ordinary symbol

Enclosed by:

Parentheses

Exponent allowed:

Number of values
per operand:

Multiple

Padding:

With zeros at left

Truncation of
assembled value:

Not applicable

R(PSECT1)

Hexadecimal Floating-Point ConstantsE, EH, D, DH, L, LH, LQ

Floating-point constants let you introduce data that is in the form suitable for the
operations of the floating-point feature instructions. These constants have the
following advantages over fixed-point constants:
You do not have to consider the fractional portion of a value you specify, nor
worry about the position of the decimal point when algebraic operations are to
be done.
You can specify both much larger and much smaller values.
You retain greater processing precision; that is, your values are carried in more
significant figures.
The nominal value can be a signed (see 1 in Figure 51 on page 162) integer,
fraction, or mixed number (see 2 Figure 51) followed by a signed exponent (see
Chapter 5. Assembler Instruction Statements

161

DC InstructionHexadecimal Floating-Point Constants

3 in Figure 51). If a sign is not specified for either the number or exponent, a
plus sign is assumed. If you specify the 'H' type extension you can also specify a
rounding mode that is used when the nominal value is converted from decimal to its
hexadecimal form. The syntax for nominal values (including the binary
floating-point constants) is shown in Figure 53 on page 168. The valid rounding
mode values are:
1
4
5
6
7

Round by adding one in the first lost bit position

Unbiased round to nearest, with tie-breaking rule
Round towards zero (that is, truncate)
Round up towards the maximum positive value
Round down towards the minimum negative value

Figure 50. Rounding Mode Values

See 4 in Figure 51.

The exponent must lie within the permissible range. If an exponent modifier is also
specified, the algebraic sum of the exponent and the exponent modifier must lie
within the permissible range.
Figure 51 (Page 1 of 3). Hexadecimal Floating-Point Constants
Subfield

Value

1. Duplication factor

Allowed

2. Type

E, D, and L

3. Type Extension

Omitted or H or Q

4. Program type

Allowed

5. Modifiers
Implicit length:
(length modifier
not present)

E-type: 4 bytes
D-type: 8 bytes
L-type: 16 bytes

Alignment:
(Length modifier
not present)

162

HLASM V1R5 Language Reference

E-type: Fullword
D-type: Doubleword
L-type: Doubleword
LQ-type: Quadword

Example

DC InstructionHexadecimal Floating-Point Constants

Figure 51 (Page 2 of 3). Hexadecimal Floating-Point Constants

Subfield
Range for length:

Value

Example

E-type:
1 to 8 (byte length)
.1 to .64 (bit length)
EH-type:
.12 to .64 (bit length)
D-type:
1 to 8 (byte length)
.1 to .64 (bit length)
DH-type:
.12 to .64 (bit length)
L-type:
1 to 16 (byte length)
.1 to .128 (bit length)
LH-type:
.12 to .128 (bit length)
LQ-type:
.12 to .128 (bit length)

|
|
Range for scale:

E-type: 0 to 14
D-type: 0 to 14
L-type: 0 to 28

Range for exponent:

85 to +75

6. Nominal value
Represented by:

Decimal digits

E-type:
DC E'+525' 1
DC E'5.25' 2
D-type:
DC D'525' 1
DC D'+.1' 2
L-type:
DC L'525'
DC L'3.414' 2

Enclosed by:

Single quotation marks

Exponent allowed:

Yes

E-type:
DC E'1E+6' 3
D-type:
DC D'2.5E1' 3
L-type:
DC L'3.712E3' 3

Rounding mode allowed

if type extension
specified:

Yes (see Figure 50 for

values)

E-type:
DC EH'1E+6R1' 4
D-type:
DC DH'2.5E1R4' 4
L-type:
DC LH'3.712E3R5' 4

Chapter 5. Assembler Instruction Statements

163

DC InstructionHexadecimal Floating-Point Constants

Figure 51 (Page 3 of 3). Hexadecimal Floating-Point Constants

Subfield

Value

Example

Number of values
per operand:

Multiple

Padding:

Correct fraction is
extended to the right and
rounded

Truncation of
assembled value:

Only if rounding mode 5; rounded otherwise.

The format of the constant is shown in Figure 52 on page 165.

The value of the constant is represented by two parts:
An exponent portion (see 1 in Figure 52 on page 165), followed by
A fractional portion (see 2 in Figure 52)
A sign bit (see 3 in Figure 52) indicates whether a positive or negative number
has been specified. The number specified must first be converted into a
hexadecimal fraction before it can be assembled into the correct internal format.
The quantity expressed is the product of the fraction (see 4 in Figure 52) and the
number 16 raised to a power (see 5 in Figure 52). Figure 52 shows the
external format of the three types of floating-point constants.
Here is the range of values that can be assembled into hexadecimal floating-point
constants:
Type of
Constant

Range of Magnitude (M) of Values

(Positive and Negative)

1665 M (1166) x 1663

1665 M (11614) x 1663

1665 M (11628) x 1663

E, D, L

5.4 x 1079 M 7.2 x 1075 (approximate)

|
|

If the value specified for a particular constant does not lie within these ranges, the
assembled value then depends on these factors:

|
|

With type extension H, overflows assemble to the largest magnitude for the
specified type, underflows will denormalize the value or return zero, depending
on the value and rounding mode.

|
|
|

Without type extension H, certain combinations of exponents (modifier and

nominal value) may produce invalid results (message ASMA071E), and if the
exponent is too large it is ignored and the nominal value of the constant
preceding the exponent is assembled instead.

164

HLASM V1R5 Language Reference

DC InstructionHexadecimal Floating-Point Constants

Type Called
Format

E
Short

1 7-bit Characteristic

2 24-bit Fraction
EH
Floating- 3 +
Point
/ /
Number
/ /

Bits
1
7
8
31

D
Long

7-bit Characteristic
56-bit Fraction
DH
Floating-
+
Point

/ /
Number

/ /

Bits
1
7
8
63

High-order 56 bits
L
Extended

7-bit Characteristic
of 112-bit Fraction
LH
Floating-
+
LQ
Point

/ /
Number

/ /

Bits
1
7
8
63

Low-order 56 bits

7-bit Characteristic

of 112-bit Fraction

/ /

Bits
1

7
8
63

Set in second half

of L-type constant
Characteristic
Hexadecimal Fraction

a
b
c
5
16E
X [ + + + ... ]

16
16
16

where a,b,c ... are hexadecimal digits, and E is an exponent that has a positive or negative
value indicated by the characteristic
Figure 52. Hexadecimal Floating-Point External Formats

Representation of Hexadecimal Floating Point: The assembler assembles a

floating-point constant into its binary representation as follows: The specified
number, multiplied by any exponents, is converted to the required two-part format.
The value is translated into:
A fractional portion represented by hexadecimal digits and the sign indicator.
The fraction is then entered into the leftmost part of the fraction field of the
constant (after rounding).
An exponent portion represented by the excess-64 binary notation, which is
then entered into the characteristic field of the constant.

Chapter 5. Assembler Instruction Statements

165

DC InstructionHexadecimal Floating-Point Constants

The excess-64 binary notation is obtained by adding +64 to the value of the
exponent (which lies between 64 and +63) to yield the characteristic (which lies
between 0 and 127).
Notes:
1. The L-type floating-point constant resembles two contiguous D-type constants.
The sign of the second doubleword is assumed to be the same as the sign of
the first.
The characteristic for the second doubleword is equal to the characteristic for
the first minus 14 (the number of hexadecimal digits in the fractional portion of
the first doubleword). No indication is given if the characteristic of the second
doubleword is zero.
|
|
|

The L-type and LH-type floating-point constants are double-word aligned. The
LQ-type is quad-word aligned. A DC LQ forces the alignment to a quad-word
boundary.
2. If scaling has been specified, hexadecimal zeros are added to the left of the
normalized fraction (causing it to become unnormalized), and the exponent in
the characteristic field is adjusted accordingly. (For further details on scaling,
see Subfield 5: Modifier on page 136.)
3. The fraction is rounded according to the implied or explicit length of the
constant. The resulting number does not differ from the exact value specified
by more than one in the last place.
Note: You can control rounding by using the 'H' type extension and
specifying the rounding mode.
4. Negative fractions are carried in true representation, not in the
two's-complement form.
5. Duplication is applied after the constant has been assembled.
6. An implied length of 4 bytes is assumed for a short (E) constant and 8 bytes for
a long (D) constant. An implied length of 16 bytes is assumed for an extended
(L) constant. The constant is aligned at the correct word (E) or doubleword (D
and L) boundary if a length is not specified. However, any length up to and
including 8 bytes (E and D) or 16 bytes (L) can be specified by a length
modifier. In this case, no boundary alignment occurs.
7. Signed zero values are correctly generated for type extensions H and B.
Without a type extension, zero values of either sign are assembled with positive
sign.
Any of the following statements can be used to specify 46.415 as a positive,
fullword, floating-point constant; the last is a machine instruction statement with a
literal operand. Note that each of the last two constants contains an exponent
modifier.
DC
DC
DC
DC
DC
AE

E'46.415'
E'46415E3'
E'+464.15E1'
E'+.46415E+2'
EE2'.46415'
6,=EE2'.46415'

The following would generate 3 doubleword floating-point constants.

166

HLASM V1R5 Language Reference

DC InstructionBinary Floating-Point Constants

FLOAT

DE+4'+46,3.729,+473'

Binary Floating-Point ConstantsEB, DB, LB

Binary floating-point numbers may be represented in any of three formats: short,
long or extended. The short format is 4 bytes with a sign of one bit, an exponent of
8 bits and a fraction of 23 bits. The long format is 8 bytes with a sign of one bit, an
exponent of 11 bits and a fraction of 52 bits. The extended format is 16 bytes with
a sign of one bit, an exponent of 15 bits and a fraction of 112 bits.
There are five classes of binary floating-point data, including numeric and related
nonnumeric entities. Each data item consists of a sign, an exponent and a
significand. The exponent is biased such that all exponents are nonnegative
unsigned numbers, and the minimum biased exponent is zero. The significand
consists of an explicit fraction and an implicit unit bit to the left of the binary point.
The sign bit is zero for plus and one for minus values.
All finite nonzero numbers within the range permitted by a given format are
normalized and have a unique representation. There are no unnormalized
numbers, which might allow multiple representations for the same value, and there
are no unnormalized arithmetic operations. Tiny numbers of a magnitude below the
minimum normalized number in a given format are represented as denormalized
numbers, because they imply a leading zero bit, but those values are also
represented uniquely.
The classes are:
1. Zeros have a biased exponent of zero, a zero fraction and a sign. The implied
unit bit is zero.
2. Denormalized numbers have a biased exponent of zero and a nonzero fraction.
The implied unit bit is zero.
|
|
|

The smallest denormalized numbers have approximate magnitudes 1.4 10**-45

(short format), 4.94 10**-324 (long format) and 6.5 10**-4966 (extended
format).

|
|
|
|
|

3. Normalized numbers have a biased exponent greater than zero but less than
all ones. The implied unit bit is one and the fraction may have any value. The
largest normalized numbers have approximate magnitudes 3.4 10**38 (short
format), 1.8 10**308 (long format), and 1.2 10**4932 (extended format). The
smallest normalized numbers have approximate magnitudes 1.18 10**-38 (short
format), 2.23 10**-308 (long format), and 3.4 10**-4392 (extended format).
4. An infinity is represented by a biased exponent of all ones and a zero fraction.
5. A NaN (Not-a-Number) entity is represented by a biased exponent of all ones
and a nonzero fraction. NaNs are produced in place of a numeric result after
an invalid operation when there is no interruption. NaNs may also be used by
the program to flag special operands, such as the contents of an uninitialized
storage area. There are two types of NaNs, signaling and quiet. A signaling
NaN (SNaN) is distinguished from the corresponding quiet NaN (QNaN) by the
leftmost fraction bit: zero for the SNaN and one for QNaN. A special QNaN is
supplied as the default result for an invalid-operation condition; it has a plus
sign and a leftmost fraction bit of one, with the remaining fraction bits being set
to zeros. Normally, QNaNs are just propagated during computations, so that
they remain visible at the end. An SNaN operand causes an invalid operation
exception.

Chapter 5. Assembler Instruction Statements

167

DC InstructionBinary Floating-Point Constants

To accommodate the definition of both hexadecimal and binary floating-point

constants the syntax for coding a DC instruction is:

DCE
dup_factor D B program_type modifier
L H
LQ
nominal_value

|
|

nominal_value (no type extension):

+
'value'
-
exponent
nominal_value (type extension B):
+
R4
'value'
-
exponent R1
5
6
7
nominal_value (type extension H):
+
R1
'value'
-
exponent R4
5
6
7

Figure 53. DC Instruction Syntax

dup_factor
causes the constant to be generated the number of times indicated by the
factor.
type
indicates that the constant is either short, long or extended floating point.
type extension
the type of conversion required to assemble the constant. Valid values are:

|
|
|

null

Hexadecimal floating-point constant which is converted using the

conversion logic of rounding mode 1 and slightly less precise algorithms

Binary floating-point constant which is converted allowing all rounding

modes

Hexadecimal floating-point constant which is converted allowing all

rounding modes

program_type
assign a programmer determined 32-bit value to the symbol naming the DC
instruction, if a symbol was present.
modifier
describes the length, the scaling and the exponent of the nominal_value. The
minimum length of the 'H' hexadecimal constant is 12 bits. The minimum
length in bits of the binary constant is:
9

168

Short floating-point constant

HLASM V1R5 Language Reference

DC InstructionBinary Floating-Point Constants

Long floating-point constant

Extended floating-point constant

This minimum length allows for the sign, exponent, the implied unit bit which is
considered to be one for normalized numbers and zero for zeros and
denormalized numbers.
The exponent modifier can be in the range from 231 to 2311 if either B or H is
specified as a type extension
nominal_value
defines the value of the constant and can include the integer, fraction or mixed
number followed by an optional signed exponent and an optional explicit
rounding mode.
The assembler imposes no limits on the exponent values that may be specified.
The BFP architecture limits the actual values that can be represented; a
warning message is issued whenever a specified value can not be represented
exactly.
The rounding mode identifies the rounding required when defining a
floating-point constant. The valid values are those displayed in Figure 50 on
page 162

|
|
|
|

Note: As binary floating-point does not support scaling, the scale modifier is
ignored and a warning message issued if the scaling modifier is specified when
defining a binary floating-point constant. The H type extension causes HLASM to
uses a different conversion algorithm for hexadecimal floating-point data. The
results are correctly rounded for all values. Without the H type extension, some rare
values could be in error by 1 unit in the last place (ulp).
Conversion to Binary Floating-Point
For decimal to binary floating-point conversion, the assembler conforms to
ANSI/IEEE Std 754-1985, IEEE Standard for Binary Floating-Point Arithmetic,
dated August 12, 1985, with the following differences: exception status flags are
not provided and traps are not supported.

|
|

Conversion of values within the represented range is correctly rounded.

Conversion of values outside the represented range is as follows. If the
resultant value before rounding is larger in magnitude than MAX (the maximum
allowed value) as represented in the specified length, then, depending on the
rounding mode, either MAX or infinity is generated, along with a warning
message. If the resultant nonzero value is less than Dmin (the minimum
allowed value) as represented in the specified length, then, depending on the
rounding mode, either Dmin or zero is generated, along with a warning
message.

Chapter 5. Assembler Instruction Statements

169

DC InstructionBinary Floating-Point Special Values

Floating-Point Special Values

For special values, the syntax of the DC statement is:

DCEB
dup_factor D H program_type
L
nominal_value
length_modifier

nominal_value (type extension B):

+
'(SNAN)'
- (QNAN)
(NAN)
(INF)
(MAX)
(MIN)
(DMIN)
nominal_value (type extension H):
+
'(MAX)'
- (MIN)
(DMIN)

program_type
assign a programmer determined 32-bit value to the symbol naming the DC
instruction, if a symbol was present.
length_modifier
describes the length in bytes or bits into which the constant is to be assembled.
For NANs and INF the minimum length in bits of the constant is:
11

Short floating-point constant

Long floating-point constant

Extended floating-point constant

This minimum length allows for the sign, exponent and two fraction bits.

170

HLASM V1R5 Language Reference

DC InstructionBinary Floating-Point Special Values

nominal_value
defines the special value to be generated.
Notes:
1. The nominal value can be in mixed case.
2. SNAN assembles with an exponent of ones and 01 in the high order fraction
bits with the remainder of the fraction containing zeros.
3. QNAN assembles with an exponent of ones and 11 in the high order fraction
bits with the remainder of the fraction containing zeros.
4. NAN assembles with an exponent of one and 10 in the high order fraction bits
with the remainder of the fraction containing zeros.
|
|

5. MIN assembles as a normalized minimum value, that is an exponent of one

and a fraction of zeros for binary constants, and a fraction with a leading
hexadecimal digit 1 followed by zeros for hexadecimal constants.

|
|

6. DMIN assembles as a denormalized minimum value with an exponent of zeros

and a fraction of all zeros except for a low order bit of one.
7. INF assembles with an exponent of ones and a fraction of zeros.

|
|
|

8. MAX assembles with a fraction of all ones and an exponent of all ones for
hexadecimal constants, and an exponent of all ones except for the low bit for
binary constants.

Literal Constants
Literal constants let you define and refer to data directly in machine instruction
operands. You do not need to define a constant separately in another part of your
source module. The differences between a literal, a data constant, and a
self-defining term are described in Literals on page 40.
A literal constant is specified in the same way as the operand of a DC instruction.
The general rules for the operand subfields of a DC instruction also apply to the
subfield of a literal constant. Moreover, the rules that apply to the individual types
of constants apply to literal constants as well.
However, literal constants differ from DC operands in the following ways:
Literals must be preceded by an equal sign.
Multiple operands are not allowed.
The duplication factor must not be zero.
Symbols used in the duplication factor or length modifier must be previously
defined. Scale and Exponent modifiers do not need pre-definition.
If an address-type literal constant specifies a duplication factor greater than one
and a nominal value containing the location counter reference, the value of the
location counter reference is not incremented, but remains the same for each
duplication.
The assembler groups literals together by size. If you use a literal constant,
the alignment of the constant can be different than might be the case for an
explicit constant. See Literal Pool on page 44.

Chapter 5. Assembler Instruction Statements

171

DROP Instruction

DROP Instruction
The DROP instruction ends the domain of a USING instruction. This:
Frees base registers previously assigned by the USING instruction for other
programming purposes
Ensures that the assembler uses the base register you want in a particular
coding situation, for example, when two USING ranges overlap or coincide
If a control section has not been established, DROP will initiate an unnamed
(private) control section

DROP
sequence_symbol
,
base_register

label

sequence_symbol
is a sequence symbol.
base_register
is an absolute expression whose value represents one of the general registers
0 through 15. The expression in base_register indicates a general register,
previously specified in the operand of an ordinary USING statement, that is no
longer to be used for base addressing.
label
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
The ordinary symbol denoted by label must be a symbol previously used in the
name field of a labeled USING statement or a labeled dependent USING
statement.
If neither base_register nor label is specified in the operand of a DROP instruction,
all active base registers assigned by ordinary, labeled, and labeled dependent
USING instructions are dropped.
After a DROP instruction:
The assembler does not use the register or registers specified in the DROP
instruction as base registers. A register made unavailable as a base register
by a DROP instruction can be reassigned as a base register by a subsequent
USING instruction.
The label or labels specified in the DROP instruction are no longer available as
symbol qualifiers. A label made unavailable as a symbol qualifier by a DROP
instruction can be reassigned as a symbol qualifier by a subsequent labeled
USING instruction.
The following statements, for example, stop the assembler using registers 7 and 11
as base registers, and the label FIRST as a symbol qualifier:

172

HLASM V1R5 Language Reference

DROP Instruction

DROP
DROP

7,11
FIRST

Labeled USING: You cannot end the domain of a labeled USING instruction by
coding a DROP instruction that specifies the same registers as were specified in
the labeled USING instruction. If you want to end the domain of a labeled USING
instruction, you must code a DROP instruction with an operand that specifies the
label of the labeled USING instruction.
Dependent USING: To end the domain of a dependent USING instruction, you
must end the domain of the corresponding ordinary USING instruction. In the
following example, the DROP instruction prevents the assembler from using register
12 as a base register. The DROP instruction causes the assembler to end the
domain of the ordinary USING instruction and the domains of the two dependent
USING instructions. The storage areas represented by INREC and OUTREC are both
within the range of the ordinary USING instruction (register 12).

INREC
OUTREC

USING
USING
USING
.
.
DROP
.
.
DS
DS

,12
RECMAP,INREC
RECMAP,OUTREC

CL156
CL156

To end the domain of a labeled dependent USING instruction, you can code a
DROP instruction with the USING label in the operand. The following example
shows this:
PRIOR
POST

INREC
OUTREC

USING
USING
USING
.
.
DROP
.
.
DS
DS

,12
RECMAP,INREC
RECMAP,OUTREC

PRIOR,POST

CL156
CL156

In the above example, the DROP instruction makes the labels PRIOR and POST
unavailable as symbol qualifiers.
When a labeled dependent USING domain is dropped, none of any subordinate
USING domains are dropped. In the following example the labeled dependent
USING BLBL1 is not dropped, even though it is dependent on the USING ALBL2 that
is dropped:

Chapter 5. Assembler Instruction Statements

173

DS Instruction

ALBL1

ALBL2
BLBL1

DSECTA
A
DSECTB
B

USING
USING
USING
.
.
USING
.
USING
.
DROP
.
DSECT
DS
DSECT
DS

DSECTA,14
DSECTA,14
DSECTB,ALBL1.A

DSECTA,ALBL1.A
DSECTA,ALBL2.A+4
ALBL2

A
A

A DROP instruction is not needed:

If the base address is being changed by a new ordinary USING instruction, and
the same base register is assigned. However, the new base address must be
loaded into the base register by an appropriate sequence of instructions.
If the base address is being changed by a new labeled USING instruction or a
new labeled dependent USING instruction, and the same USING label is
assigned; however, the correct base address must be loaded into the base
register specified in the USING instruction by an appropriate sequence of
instructions.
At the end of a source module

DS Instruction
The DS instruction:

Reserves areas of storage

Provides labels for these areas
Uses these areas by referring to the symbols defined as labels
If a control section has not previously been established, DS will initiate an
unnamed (private) control section

,
operand
DS
symbol

174

HLASM V1R5 Language Reference

DS Instruction

specified, the first storage area defined is addressable by the ordinary symbol.
The other storage areas can be reached by relative addressing.
operand
is an operand of six subfields. The first five subfields describe the attributes of
the symbol. The sixth subfield provides the nominal values that determine the
implicit lengths; however no constants are generated.
A DS operand has this format:

type
duplication_factor
type_extension
nominal_value
program_type modifier

The format of the DS operand is identical to that of the DC operand; exactly the
same subfields are used and are written in exactly the same sequence as they are
in the DC operand. For more information about the subfields of the DC instruction,
see DC Instruction on page 126.
Unlike the DC instruction, the DS instruction causes no data to be assembled.
Therefore, you do not have to specify the nominal value (sixth subfield) of a DS
instruction operand. The DS instruction is the best way of symbolically defining
storage for work areas, input/output buffers, etc.
Although the formats are identical, there are two differences in the specification of
subfields. They are:
The nominal value subfield is optional in a DS operand, but it is mandatory in a
DC operand. If a nominal value is specified in a DS operand, it must be valid.
The maximum length that can be specified for the character (C) and
hexadecimal (X) type areas is 65,535 bytes rather than 256 bytes for the same
DC operands. The maximum length for the graphic (G) type is 65,534 bytes.
If symbol denotes an ordinary symbol, the ordinary symbol, as with the DC
instruction:
Has an address value of the first byte of the area reserved, after any boundary
alignment is done
Has a length attribute value, depending on the implicit or explicit length of the
type of area reserved
If the DS instruction is specified with more than one operand or more than one
nominal value in the operand, the label addresses the area reserved for the field
that corresponds to the first nominal value of the first operand. The length attribute
value is equal to the length explicitly specified or implicit in the first operand.
Bytes Skipped for Alignment: Unlike the DC instruction, bytes skipped for
alignment are not set to zero. Also, nothing is assembled into the storage area
reserved by a DS instruction. No assumption should be made as to the contents of
the skipped bytes or the reserved area.

Chapter 5. Assembler Instruction Statements

175

DS Instruction

The size of a storage area that can be reserved by a DS instruction is limited only
by the size of virtual storage or by the maximum value of the location counter,
whichever is smaller.

How to Use the DS Instruction

Use the DS instruction to:
Reserve storage
Force alignment of the location counter so that the data that follows is on a
particular storage boundary
Name fields in a storage area.
To Reserve Storage: If you want to take advantage of automatic boundary
alignment (if the ALIGN option is specified) and implicit length calculation, you
should not supply a length modifier in your operand specifications. Instead, specify
a type subfield that corresponds to the type of area you need for your instructions.
Using a length modifier can give you the advantage of explicitly specifying the
length attribute value assigned to the label naming the area reserved. However,
your areas are not aligned automatically according to their type. If you omit the
nominal value in the operand, you should use a length modifier for the binary (B),
character (C), graphic (G), hexadecimal (X), and decimal (P and Z) type areas;
otherwise, their labels are given a length attribute value of 1 (2 for G and CU type).
When you need to reserve large areas, you can use a duplication factor. However,
in this case, you can only refer to the first area by its label. You can also use the
character (C) and hexadecimal (X) field types to specify large areas using the
length modifier. Duplication has no effect on implicit length.
Although the nominal value is optional for a DS instruction, you can put it to good
use by letting the assembler compute the length for areas of the B, C, G, X, and
decimal (P or Z) type areas. You achieve this by specifying the general format of
the nominal value that is placed in the area at execution time.
If a nominal value and no length modifier are specified for a Unicode character
string, the length of the storage reserved is derived by multiplying by two the
number of characters specified in the nominal value (after pairing).
To Force Alignment: Use the DS instruction to align the instruction or data that
follows, on a specific boundary. You can align the location counter to a
doubleword, a fullword, or a halfword boundary by using the correct constant type
(for example, D, F, or H) and a duplication factor of zero. No space is reserved for
such an instruction, yet the data that follows is aligned on the correct boundary.
For example, the following statements set the location counter to the next
doubleword boundary and reserve storage space for a 128-byte field (whose first
byte is on a doubleword boundary).
AREA

DS
DS

D
CL128

Alignment is forced whether or not the ALIGN assembler option is set.

To Name Fields within an Area: Using a duplication factor of zero in a DS
instruction also provides a label for an area of storage without actually reserving the
area. Use DS or DC instructions to reserve storage for, and assign labels to, fields

176

HLASM V1R5 Language Reference

DS Instruction

within the area. These fields can then be addressed symbolically. (Another way of
accomplishing this is described in DSECT Instruction on page 178.) The whole
area is addressable by its label. In addition, the symbolic label has the length
attribute value of the whole area. Within the area, each field is addressable by its
label.
For example, assume that 80-character records are to be read into an area for
processing and that each record has the following format:
Positions
Positions
Positions
Positions
Positions

5-10
11-30
31-36
47-54
55-62

Payroll Number
Employee Name
Date
Gross Wages
Withholding Tax

The following example shows how DS instructions might be used to assign a name
to the record area, then define the fields of the area and allocate storage for them.
The first statement names the whole area by defining the symbol RDAREA; this
statement gives RDAREA a length attribute of 80 bytes, but does not reserve any
storage. Similarly, the fifth statement names a 6-byte area by defining the symbol
DATE; the three subsequent statements actually define the fields of DATE and
allocate storage for them. The second, ninth, and last statements are used for
spacing purposes and, therefore, are not named.
RDAREA
PAYNO
NAME
DATE
DAY
MONTH
YEAR
GROSS
FEDTAX

DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS

CL8
CL4
CL6
CL2
CL6
CL2
CL2
CL2
CL1
CL8
CL8
CL18

Additional examples of DS statements are shown below:

ONE
TWO
THREE
FOUR
FIVE
SIX
SEVEN

DS
DS
DS
DS
DS
DS
DS

CL8
8C
6F
D
4H
GL8
8G

One 8-byte field, length attribute of 8

8 1-byte fields, length attribute of 1
6 fullwords, length attribute of 4
1 doubleword, length attribute of 8
4 halfwords, length attribute of 2
One 8-byte field, length attribute of 8
8 2-byte fields, length attribute of 2

To define four 10-byte fields and one 100-byte field, the respective DS statements
might be as follows:
FIELD
AREA

DS
DS

4CL1
CL1

Although FIELD might have been specified as one 40-byte field, the preceding
definition has the advantage of providing FIELD with a length attribute of 10. This
would be pertinent when using FIELD as an SS machine instruction operand.

Chapter 5. Assembler Instruction Statements

177

DSECT Instruction

DSECT Instruction
The DSECT instruction identifies the beginning or continuation of a dummy control
section. One or more dummy sections can be defined in a source module.

DSECT
symbol

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
The DSECT instruction can be used anywhere in a source module after the ICTL
instruction.
If symbol denotes an ordinary symbol, the ordinary symbol identifies the dummy
section. If several DSECT instructions within a source module have the same
symbol in the name field, the first occurrence initiates the dummy section and the
rest indicate the continuation of the dummy section. The ordinary symbol denoted
by symbol represents the address of the first byte in the dummy section, and has a
length attribute value of 1.
If symbol is not specified, or if name is a sequence symbol, the DSECT instruction
initiates or indicates the continuation of the unnamed control section.
The location counter for a dummy section is always set to an initial value of 0.
However, when an interrupted dummy control section is continued using the
DSECT instruction, the location counter last specified in that control section is
continued.
The source statements that follow a DSECT instruction belong to the dummy
section identified by that DSECT instruction.
Notes:
1. The assembler language statements that appear in a dummy section are not
assembled into object code.
2. When establishing the addressability of a dummy section, the symbol in the
name field of the DSECT instruction, or any symbol defined in the dummy
section can be specified in a USING instruction.
3. A symbol defined in a dummy section can be specified in an address constant
only if the symbol is paired with another symbol from the same dummy section,
and if the symbols have opposite signs.
To effect references to the storage area defined by a dummy section, do the
following:
Provide either:

178

HLASM V1R5 Language Reference

DSECT Instruction

An ordinary or labeled USING statement that specifies both a general

register that the assembler can use as a base register for the dummy
section, and a value from the dummy section that the assembler may
assume the register contains, or
A dependent or labeled dependent USING statement that specifies a
supporting base address (for which there is a corresponding ordinary
USING statement) that lets the assembler determine a base register and
displacement for the dummy section, and a value from the dummy section
that the assembler may assume is the same as the supporting base
address
Ensure that the base register is loaded with either:
The actual address of the storage area if an ordinary USING statement or a
labeled USING statement was specified, or
The base address specified in the corresponding ordinary USING statement
if a dependent or labeled dependent USING statement was specified.
The values assigned to symbols defined in a dummy section are relative to the
initial statement of the section. Thus, all machine instructions that refer to names
defined in the dummy section refer, at execution time, to storage locations relative
to the address loaded into the register.
Figure 54 shows an example of how to code the DSECT instruction. The sample
code is referred to as Assembly-2.
Assume that two independent assemblies (Assembly-1 and Assembly-2) have been
loaded and are to be run as a single overall program. Assembly-1 is a routine that
1. Places a record in an area of storage
2. Places the address of the storage area in general register 3
3. Branches to Assembly-2 to process the record
The storage area from Assembly-1 is identified in Assembly-2 by the dummy
control section (DSECT) named INAREA. Parts of the storage area that you want
to work with are named INCODE, OUTPUTA, and OUTPUTB. The statement
USING INAREA,3 assigns general register 3 as the base register for the INAREA
DSECT. General register 3 contains the address of the storage area. Because the
symbols in the DSECT are defined relative to the beginning of the DSECT, the
address values they represent are, at the time of program execution, the actual
storage locations of the storage area that general register 3 addresses.

Chapter 5. Assembler Instruction Statements

179

DXD Instruction

ASEMBLY2 CSECT
USING
USING
CLI
BE
MVC
MVC
B
ATYPE
DS
MVC
MVC
FINISH
BR
DATA_A
DC
DATA_B
DC
INAREA
DSECT
INCODE
DS
OUTPUTA DS
OUTPUTB DS
END

,15
INAREA,3
INCODE,C'A'
ATYPE
OUTPUTA,DATA_B
OUTPUTB,DATA_A
FINISH
H
OUTPUTA,DATA_A
OUTPUTB,DATA_B
14
CL8'ADATA'
CL8'BDATA'
CL1
CL8
CL8

Figure 54. Sample Code Using the DSECT Instruction (Assembly-2)

DXD Instruction
The DXD instruction identifies and defines an external dummy section.

symbolDXDtype
duplication_factor
type_extension

modifier

nominal_value

symbol
is an external symbol which is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
duplication_factor
is the duplication factor subfield equivalent to the duplication factor subfield of
the DS instruction.
type
is the type subfield equivalent to the type subfield of the DS instruction.
type_extension
is the type extension subfield equivalent to the type extension subfield of the
DS instruction.
modifiers
is the modifiers subfield equivalent to the modifiers subfield of the DS
instruction.

180

HLASM V1R5 Language Reference

EJECT Instruction

nominal_value
is the nominal-value subfield equivalent to the nominal-value subfield of the DS
instruction. The nominal value is optional. If specified, it is not generated.
The DXD instruction can be used anywhere in a source module, after the ICTL
instruction.
In order to reference the storage defined by the external dummy section, the
ordinary symbol denoted by symbol must appear in the operand of a Q-type
constant. This symbol represents the address of the first byte of the external
dummy section defined, and has a length attribute value of 1.
The subfields in the operand field (duplication factor, type, type extension, modifier,
and nominal value) are specified in the same way as in a DS instruction. The
assembler computes the amount of storage and the alignment required for an
external dummy section from the area specified in the operand field. For more
information about how to specify the subfields, see DS Instruction on page 174.
For example:
A
B
C

DXD
DXD
DXD

CL2
3F,XL4
LQ

2 bytes, byte alignment

2 bytes, fullword alignment
16 bytes, quadword alignment

The linker uses the information provided by the assembler to compute the total
length of storage required for all external dummy sections specified in a program.
Notes:
1. The DSECT instruction also defines an external dummy section, but only if the
symbol in the name field appears in a Q-type offset constant in the same
source module. Otherwise, a DSECT instruction defines a dummy section.
2. If two or more external dummy sections for different source modules have the
same name, the linker uses the most restrictive alignment, and the largest
section to compute the total length.

EJECT Instruction
The EJECT instruction stops the printing of the assembler listing on the current
page, and continues the printing on the next page.

EJECT
sequence_symbol

sequence_symbol
is a sequence symbol.
The EJECT instruction causes the next line of the assembler listing to be printed at
the top of a new page. If the line before the EJECT statement appears at the
bottom of a page, the EJECT statement has no effect.
An EJECT instruction immediately following another EJECT instruction is ignored.
A TITLE instruction immediately following an EJECT instruction causes the title to

Chapter 5. Assembler Instruction Statements

181

END Instruction

change but no additional page eject is performed. (The TITLE instruction normally
forces a page eject.)
The EJECT instruction statement itself is not printed in the listing.

END Instruction
Use the END instruction to end the assembly of a program. You can also supply
an address in the operand field to which control can be transferred after the
program is loaded. The END instruction must always be the last statement in the
source program.

END
sequence_symbol
expression ,language

sequence_symbol
is a sequence symbol.
expression
specifies the point to which control can be transferred when loading of the
object program completes. If the GOFF option is in effect this parameter is
ignored. This point is usually the address of the first executable instruction in
the program, as shown in the following sequence:
NAME
AREA
BEGIN

CSECT
DS
BALR
USING
.
.
.
END

5F
2,
,2

BEGIN

If specified, expression may be generated by substitution into variable symbols.

It must be a simply relocatable expression representing an address in the
source module delimited by the END instruction, or
If it contains an external symbol, the external symbol must be the only term
in the expression, or the remaining terms in the expression must reduce to
zero.
It must not be a literal.
language
a marker for use by language translators that produce assembly code. The
operand has three sub-operands. The values in this operand are copied into
the END record in the object deck.
The syntax of this operand is
(char1,char4,char5)
where all three sub-operands, and the commas and parentheses are required.
char1 is a one to ten character code. It is intended to be a language translator
identifier. char4 must be exactly four characters long. It is intended to be a
version and release code. char5 must be exactly five characters long, and

182

HLASM V1R5 Language Reference

ENTRY Instruction

should be a date in the format YYDDD. It is intended to be the compile date.

For example:
END

ENTRYPT,(MYCOMPILER,11,273)

Notes:
1. If the END instruction is omitted, one is generated by the assembler, and
message ASMA14W END record missing is issued.
2. Refer to the note on page 341 about lookahead processing, and the effect it
has on generated END statements.
3. If the END statement is not the last statement in the input stream, and the
BATCH option (see HLASM Programmer's Guide) has been specified, the
assembler will initiate assembly of a new source module when the current
assembly is completed.

ENTRY Instruction
The ENTRY instruction identifies symbols defined in one source module so that
they can be referred to in another source module. These symbols are entry
symbols.

,
entry_point
ENTRY
sequence_symbol

sequence_symbol
is a sequence symbol.
entry_point
is a relocatable symbol that:
Is a valid symbol
Is defined in an executable control section
Is not defined in a dummy control section, a common control section, or an
external control section
Up to 65535 individual control sections, external symbols, and external dummy
sections can be defined in a source module. However, the practical maximum
number depends on the amount of table storage available to the program that links
the object module.
The assembler lists each entry symbol of a source module in an external symbol
dictionary, along with entries for external symbols, common control sections, parts,
and external control sections.
A symbol used as the name entry of a START or CSECT instruction is also
automatically considered an entry symbol, and does not have to be identified by an
ENTRY instruction.
The length attribute value of entry symbols is the same as the length attribute value
of the symbol at its point of definition.
Chapter 5. Assembler Instruction Statements

183

EQU Instruction

EQU Instruction
The EQU instruction assigns absolute or relocatable values to symbols. Use it to:
Assign single absolute values to symbols.
Assign the values of previously defined symbols or expressions to new
symbols, thus letting you use different mnemonics for different purposes.
Compute expressions whose values are unknown at coding time or difficult to
calculate. The value of the expressions is then assigned to a symbol.
Assign length and type attributes to symbols, either implicitly or explicitly.
|

Assign program type and assembler type values to symbols.

EQU also assigns attributes. It takes the value, relocation, and length attributes of
the operand and assigns them to the name field symbol, and sets the integer and
scale attributes to zero. The type attributes of an absolute expression is always 'U',
and its length attribute is always 1 (unless the second and third operands are
specified.
When there is a symbol naming a complex relocatable expression, or a complex
relocatable expression is eventually reduced to an absolute or simply relocatable
expression, the first symbol is used for attribute assignment.

|
|

The program type is always null, and the assembler type is always null, except
when the appropriate operand is specified.

|
|
|

(1)
symbolEQUexpression_1,
,
expression_2

|
|

,,
expression_3
expression_4
expression_5

|
|

Note:
Use commas as placeholders when there is an expression following

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
expression_1
represents a value and attributes that the assembler assigns to the symbol in
the name field. expression_1 may have any value allowed for an assembly
expression: absolute (including negative), relocatable, or complexly
relocatable. The assembler carries this value as a signed 4-byte (32-bit)
number; all four bytes are printed in the program listings opposite the symbol.
Implicitly, the relocation and length attributes are also assigned for certain types
of expressions.
Any symbols used in expression_1 need not be previously defined. However, if
any symbol is not previously defined, the value of expression_1 is not assigned
to the symbol in the name field until assembly time and therefore may not be

184

HLASM V1R5 Language Reference

EQU Instruction

used during conditional assembly (see Using Conditional Assembly Values on

page 187).
If expression_1 is a complexly relocatable expression, the whole expression,
rather than its value, is assigned to the symbol. During the evaluation of any
expression that includes a complexly relocatable symbol, that symbol is
replaced by its own defining expression. Consider the following example, in
which A1 and A2 are defined in one control section, and B1 and B2 in another:
X
Y

EQU
EQU

A1+B1
XA2B2

The first EQU statement assigns a complexly relocatable expression (A1+B1) to

X. During the evaluation of the expression in the second EQU statement, X is
replaced by its defining relocatable expression (A1+B1), and the assembler
evaluates the resulting expression (A1+B1-A2-B2) and assigns an absolute
value to Y, because the relocatable terms in the expression are paired. Note
that the expression may not contain literals.
expression_2
represents a value that the assembler assigns as a length attribute value to the
symbol in the name field. It is optional, but, if specified, must be an absolute
value in the range 0 to 65,535. This value overrides the normal length attribute
value implicitly assigned from expression_1.
All symbols appearing in expression_2 must have been previously defined, and
all expressions in expression_2 must be evaluatable when the EQU statement
is processed. For example, the second operand in the statements defining the
symbol X cannot be evaluated when the last statement has been processed,
because the value of the symbol X is unknown until the symbol A has been
defined.
Z
Y
X
A

DS
DS
EQU
DS

XL(L'A)
XL7
Z,-Z
XL5

Z
Y
X
A

DS XL(A)
DS XL7
EQU Z,-Z
EQU 5

If expression_2 is omitted, the assembler assigns a length attribute value to the

symbol in the name field according to the length attribute value of the leftmost
(or only) term of expression_1, as follows:
1. If the leftmost term of expression_1 is a location counter reference (*), a
self-defining term, or a symbol length attribute value reference, the length
attribute is 1. This also applies if the leftmost term is a symbol that is
equated to any of these values.
2. If the leftmost term of expression_1 is a symbol that is used in the name
field of a DC or DS instruction, the length attribute value is equal to the
implicit or explicit length of the first (or only) constant specified in the DC or
DS operand field.
3. If the leftmost term is a symbol that is used in the name field of a machine
instruction, the length attribute value is equal to the length of the
assembled instruction.
4. Symbols that name assembler instructions, except the DC, DS, CCW,
CCW0, and CCW1 instructions, have a length attribute value of 1.
Symbols that name a CCW, CCW0, or CCW1 instruction have a length
attribute value of 8.

Chapter 5. Assembler Instruction Statements

185

EQU Instruction

5. The length attribute value described in cases 2, 3, and 4 above is the

assembly-time value of the attribute.
For more information about the length attribute value, see Symbol Length
Attribute Reference on page 38.
For example:
X
Y

DS
EQU

CL8
X,4

X has length attribute 8

Y has length attribute 4

expression_3
represents a value that the assembler assigns as a type attribute value to the
symbol in the name field. It is optional, but, if specified, it must be an absolute
value in the range 0 to 255.
All symbols appearing in expression_3 must have been previously defined, and
all expressions in expression_3 must be evaluatable when the EQU statement
is processed.
If expression_3 is omitted, the assembler assigns a type attribute value of U to
the symbol, which means the symbol in the name field has an undefined (or
unknown or unassigned) type attribute. See the general discussion about data
attributes on page 324, and Type Attribute (T') on page 328.
For example:
A
B
|
|
|
|
|
|
|

DS
EQU

D
A,,C'X'

A has type attribute D

B has type attribute X

expression_4
represents a value that the assembler assigns as a program type value to the
symbol in the name field. It is optional. It can be specified as a decimal,
character, hex or binary self-defining term and is stored as a 4-byte (32-bit)
number; all four bytes are printed in the program listings opposite the symbol.
The value is not used in any way by the assembler, and may be queried by
using the SYSATTRP built-in function.

|
|
|

All symbols appearing in expression_4 must have been previously defined, and
all expressions in expression_4 must be evaluatable when the EQU statement
is processed.

|
|
|

If expression_4 is omitted, the assembler assigns a null to the program type,

and querying the value using the SYSATTRP built-in function returns a null
value.

|
|
|
|
|
|
|

expression_5
represents a character value from 1-4 bytes in length, that the assembler
assigns as an assembler type value to the symbol in the name field. It is
optional. It is stored as a 4-byte string; all four bytes are printed in the program
listings opposite the symbol. The value is used by the assembler when
type-checking has been activated, and may be queried by using the
SYSATTRA built-in function.

Valid values for this expression are:

186

HLASM V1R5 Language Reference

EXITCTL Instruction

|
|
|
|
|
|
|
|

AR
CR
CR32
CR64
FPR
GR
GR32
GR64

|
|
|

If expression_5 is omitted, the assembler assigns a null value to the assembler

type, and querying the value using the SYSATTRA build-in function returns a
null value.

Access
Control
Control 32-bit
Control 64-bit
Floating-Point
General
General 32-bit
General 64-bit

The EQU instruction can be used anywhere in a source module after the ICTL
instruction. Note, however, that the EQU instruction will initiate an unnamed control
section (private code) if it is specified before the first control section.

Using Conditional Assembly Values

The following rules describe when you can use the value, length attribute value, or
type attribute value of an equated symbol in conditional assembly statements:
If you want to use the value of the symbol in conditional assembly statements,
then:
The EQU statement that defines the symbol must be processed by the
assembler before the conditional assembly statement that refers to the
symbol.
The symbol in the name field of the EQU statement must be an ordinary
symbol.
Expression_1 must be an absolute expression, and must contain only
self-defining terms or previously defined symbols.
If only expression_1 is specified, the assembler assigns a value of 1 to the
length attribute, and a value of U to the type attribute of the symbol during
conditional assembly. You can use these values in conditional assembly
statements, although references to the length attribute may be flagged.
If you specify expression_2 or expression_3 and you want to use the explicit
attribute value during conditional assembly processing, then:
The symbol in the name field must be an ordinary symbol.
The expression must contain only self-defining terms.

EXITCTL Instruction
The EXITCTL instruction sets or modifies the contents of the four signed fullword
exit-control parameters that the assembler maintains for each type of exit.

EXITCTL
sequence_symbol

,
(1)
exit_type

_
control value
Note:
From one to four values to be supplied.

Chapter 5. Assembler Instruction Statements

187

EXITCTL Instruction

sequence_symbol
is a sequence symbol.
exit_type
identifies the type of exit to which this EXITCTL instruction applies. Exit_type
must have one of the following values:
SOURCE

Sets the exit-control parameters for the user-supplied exit module

specified in the INEXIT suboption of the EXIT assembler option.
LIBRARY Sets the exit-control parameters for the user-supplied exit module
specified in the LIBEXIT suboption of the EXIT assembler option.
LISTING
Sets the exit-control parameters for the user-supplied exit module
specified in the PRTEXIT suboption of the EXIT assembler option.
PUNCH
Sets the exit-control parameters for the user-supplied exit module
specified in the OBJEXIT suboption of the EXIT assembler option
when it is called to process the object module records generated
when the DECK assembler option is specified.
OBJECT (MVS and CMS)
Sets the exit-control parameters for the user-supplied exit module
specified in the OBJEXIT suboption of the EXIT assembler option
when it is called to process the object module records generated
when the OBJECT or GOFF assembler option is specified.
ADATA
Sets the exit-control parameters for the user-supplied exit module
specified in the ADEXIT suboption of the EXIT assembler option.
TERM
Sets the exit-control parameters for the user-supplied exit module
specified in the TRMEXIT suboption of the EXIT assembler option.
control_value
is the value to which the corresponding exit-control parameter should be set.
For each exit type, the assembler maintains four exit-control parameters known
as EXITCTL_1, EXITCTL_2, EXITCTL_3, and EXITCTL_4. Therefore, up to
four values may be specified. Which exit-control parameter is set is determined
by the position of the value in the operand of the instruction. You must code a
comma in the operand for each omitted value. If specified, control_value must
be either:
A decimal self-defining term with a value in the range 231 to +2311.
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 +2311.
If control_value is omitted, the corresponding exit-control parameter retains its
current value.
The following example shows how to set the exit-control parameters EXITCTL_1
and EXITCTL_3 for the LISTING exit without affecting the contents of the other
exit-control parameters:
EXITCTL LISTING,256,,+128
See the HLASM Programmer's Guide for information about how EXITCTL values
are passed to each type of exit.
The assembler initializes all exit-control parameters to binary zeros.

188

HLASM V1R5 Language Reference

EXTRN Instruction

EXTRN Instruction
The EXTRN instruction identifies symbols referred to in a source module but
defined in another source module. These symbols are external symbols.

,
external_symbol
EXTRN
sequence_symbol

sequence_symbol
is a sequence symbol.
external_symbol
is a relocatable symbol that:
Is a valid symbol
Is not used as the name entry of a source statement in the source module
in which it is defined
Up to 65535 individual control sections, external symbols, and external dummy
sections can be defined in a source module. However, the practical maximum
number depends on the amount of table storage available during link-editing.
The assembler lists each external symbol identified in a source module in the
external symbol dictionary, along with entries for entry symbols, common control
sections, parts, and external control sections.
External symbols have a length attribute of 1. See also WXTRN Instruction on
page 229.

ICTL Instruction
The ICTL instruction changes the begin, end, and continue columns that establish
the coding format of the assembler language source statements.

ICTLbegin
,end
,continue

begin
specifies the begin column of the source statement. It must be a decimal
self-defining term within the range of 1 to 40, inclusive.
end
specifies the end column of the source statement. When end is specified it
must be a decimal self-defining term within the range of 41 to 80, inclusive. It
must be not less than begin +5, and must be greater than continue. If end is
not specified, it is assumed to be 71.
continue
specifies the continue column of the source statement. When specified,
continue must be a decimal self-defining term within the range of 2 to 40, and it
Chapter 5. Assembler Instruction Statements

189

ISEQ Instruction

must be greater than begin. If continue is not specified, or if column 80 is

specified as the end column, the assembler assumes that continuation lines are
not allowed.
Default
1,71,16
Use the ICTL instruction only once, at the very beginning of a source program. If
no ICTL statement is used in the source program, the assembler assumes that 1,
71, and 16 are the begin, end, and continue columns, respectively.
With the ICTL instruction, you can, for example, increase the number of columns to
be used for the identification or sequence checking of your source statements. By
changing the begin column, you can even create a field before the begin column to
contain identification or sequence numbers. For example, the following instruction
designates the begin column as 9 and the end column as 80. Since the end
column is specified as 80, no continuation records are recognized.
ICTL

9,8

COPY Instruction: The ICTL instruction does not affect the format of statements
brought in by a COPY instruction or generated from a library macro definition. The
assembler processes these statements according to the standard begin, end, and
continue columns described in Field Boundaries on page 14.

ISEQ Instruction
The ISEQ instruction forces the assembler to check if the statements in a source
module are in sequential order. In the ISEQ instruction, you specify the columns
between which the assembler is to check for sequence numbers.

ISEQ
sequence_symbol
left,right

sequence_symbol
is a sequence symbol.
left
specifies the first column of the field to be sequence-checked. If specified, left
must be a decimal self-defining term in the range 1 to 80, inclusive.
right
specifies the rightmost column of the field to be sequence checked. If
specified, right must be a decimal self-defining term in the range 1 to 80,
inclusive, and must be greater than or equal to left.
If left and right are omitted, sequence checking is ended. Sequence checking can
be restarted with another ISEQ statement. An ISEQ statement that is used to end
sequence checking is itself sequence-checked.
The assembler begins sequence checking with the first statement line following the
ISEQ instruction. The assembler also checks continuation lines.

190

HLASM V1R5 Language Reference

LOCTR Instruction

Sequence numbers on adjacent statements or lines are compared according to the

8-bit internal EBCDIC collating sequence. When the sequence number on one line
is not greater than the sequence number on the preceding line, a sequence error is
flagged, and a warning message is issued, but the assembly is not ended.
If the sequence field in the preceding line is spaces, the assembler uses the last
preceding line with a non-space sequence field to make its comparison.
The assembler checks only those statements that are specified in the coding of a
source module. This includes any COPY instruction statement or macro instruction.
The assembler does not check:
Statements inserted by a COPY instruction
Statements generated from model statements inside macro definitions or from
model statements in open code (statement generation is discussed in detail in
Chapter 7, How to Specify Macro Definitions on page 243)
Statements in library macro definitions

LOCTR Instruction
The LOCTR instruction specifies multiple location counters within a control section.
The assembler assigns consecutive addresses to the segments of code using one
location counter before it assigns addresses to segments of coding using the next
location counter.

symbolLOCTR

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
By using the LOCTR instruction, you can code your control section in a logical
order. For example, you can code work areas and data constants within the
section of code, using them without having to branch around them:

Chapter 5. Assembler Instruction Statements

191

LOCTR Instruction

B
C
B
A
DUM
C

CSECT
LR
USING
.
LOCTR
.
LOCTR
.
LOCTR
.
LOCTR
.
DSECT
LOCTR
.
END

,
12,15
A,12

See note 1

See note 2

,
,

See note 3

See note 4

,
,

See note 1
See note 5

LOCTRs are ordered by their definition order. So in the previous example, the
ordering is A, B and C. When there are statements in LOCTR groups, the code is
generated using currently active USINGs and then moved to the final location.
Notes:
1. The first location counter of a section, class or part is defined by the name of
the START, CSECT, DSECT, RSECT, CATTR or COM instruction defining the
section.
2. The LOCTR instruction defines a location counter.
3. The LOCTR continues a previously defined location counter. A location
counter remains in use until it is interrupted by a LOCTR, CSECT, DSECT, or
COM instruction.
4. A LOCTR instruction with the same name as a control section continues the
first location counter of that section. However, an unnamed LOCTR cannot be
used to continue an unnamed (private code) control section.
5. A LOCTR instruction with the same name as a LOCTR instruction in a previous
control section causes that control section to be continued using the location
counter specified, even though the LOCTR instruction may follow the definition
(or resumption) of a different section.
6. To continue a location counter in an unnamed section, a named location
counter must first be specified for the section by a LOCTR in the unnamed
section.
A control section cannot have the same name as a previous LOCTR instruction. A
LOCTR instruction placed before the first control section definition initiates an
unnamed control section before the LOCTR instruction is processed.
The length attribute of a LOCTR name is 1.
LOCTR instructions do not force alignment; code assembled under a location
counter other than the first location counter of a control section is assembled
starting at the next available byte after the previous segment.
|
|
|

A LOCTR name may be referenced as an ordinary symbol. If the LOCTR name

does not match a section name, its value is the location counter value assigned to
its first appearance, and it may have arbitrary alignment and other attributes. If the

192

HLASM V1R5 Language Reference

LTORG Instruction

|
|
|
|

LOCTR name is also a control section name, the value assigned is that of the
origin of the control section. So a LOCTR with the same name as the CSECT will
resume the first location counter within the CSECT. A CSECT instruction will
resume the last location counter used.
Figure 55. LOCTR behavior with NOGOFF option
LOCTR
name

Effect

Section

Resumes assembling with the first location counter of that section

Other

If the LOCTR name was previously declared, resumes assembling with

the location counter of that LOCTR group
If the LOCTR name was not previously declared, begins processing a
new LOCTR group of statements to be assembled following the most
recently processed section or LOCTR group

Figure 56. LOCTR behavior with GOFF option

LOCTR
name

Effect

|
|

Section

Resumes assembling with the first location counter of the element in the
B_TEXT class of that section

Class

Not allowed

Part

Resumes assembling with the first location counter of the part

|
|
|
|
|

Other

If the LOCTR name was previously declared, resumes assembling with

the location counter of that LOCTR group
If the LOCTR name was not previously declared, begins processing
statements in a new LOCTR group to be assembled following the most
recently processed class, part, or LOCTR group.

LTORG Instruction
Use the LTORG instruction so that the assembler can collect and assemble literals
into a literal pool. A literal pool contains the literals you specify in a source module
either after the preceding LTORG instruction, or after the beginning of the source
module.
If a control section has not been established, LTORG will initiate an unnamed
(private) control section.

LTORG
symbol

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol

Chapter 5. Assembler Instruction Statements

193

LTORG Instruction

If symbol is an ordinary symbol or a variable symbol that has been assigned an

ordinary symbol, the ordinary symbol is assigned the value of the address of the
first byte of the literal pool. This symbol is aligned on a boundary specified by the
SECTALGN option, and has a length attribute of 1. If bytes are skipped after the
end of a literal pool to achieve alignment for the next instruction, constant, or area,
the bytes are not filled with zeros. If the literal pool includes any items that require
quadword alignment and the SECTALGN value defaults to 8, then the assemble of
the literal causes the issue of an ASMA500W message.

|
|
|
|
|

The assembler ignores the borders between control sections when it collects literals
into pools. Therefore, you must be careful to include the literal pools in the control
sections to which they belong (for details, see Addressing Considerations on
page 195).
The creation of a literal pool gives the following advantages:
Automatic organization of the literal data into sections that are correctly aligned
and arranged so that minimal space is wasted in the literal pool.
Assembling of duplicate data into the same area.
Because all literals are cross-referenced, you can find the literal constant in the
pool into which it has been assembled.

Literal Pool
A literal pool is created under the following conditions:
Immediately after a LTORG instruction.
If no LTORG instruction is specified, and no LOCTRs are used in the first
control section, a literal pool generated after the END statement is created at
the end of the first control section, and appears in the listing after the END
statement.
If no LTORG instruction is specified, and LOCTRs are used in the first control
section, a literal pool generated after the END statement is created at the end
of the most recent LOCTR segment of the first section, and appears in the
listing after the END statement.
To force the literal pool to the end of the control section when using LOCTRs,
you must resume the last LOCTR of the CSECT before the LTORG statement
(or before the END statement if no LTORG statement is specified).
Each literal pool has five segments into which the literals are stored (a) in the order
that the literals are specified, and (b) according to their assembled lengths, which,
for each literal, is the total explicit or implied length, as described below.
|
|

The first segment contains all literal constants whose assembled lengths are a
multiple of 16.
The second segment contains those whose assembled lengths are a multiple of
8, but not of 16.
The third segment contains those whose assembled lengths are a multiple of 4,
but not a multiple of 8.
The fourth segment contains those whose assembled lengths are even, but not
a multiple of 4.

194

HLASM V1R5 Language Reference

LTORG Instruction

The fifth segment contains all the remaining literal constants whose assembled
lengths are odd.
|
|
|
|

Since each literal pool is aligned on a SECTALGN alignment, this guarantees that
all literals in the second segment are doubleword aligned; in the third segment,
fullword aligned; and, in the fourth, halfword aligned. The minimum value of
SECALGN is doubleword, so quadword alignment is not guaranteed. No space is
wasted except, possibly, at the origin of the pool, and in aligning to the start of the
statement following the literal pool.
Literals from the following statements are in the pool, in the segments indicated by
the parenthesized numbers:
FIRST

START
.
MVC
AD
IC
MVC
LM
AH
L
MVC

TO,=3F'9'
2,=D'7'
2,=XL1'8'
MTH,=CL3'JAN'
4,5,=2F'1,2'
5,=H'33'
2,=A(ADDR)
FIVES,=XL16'5'

(3)
(2)
(5)
(5)
(2)
(4)
(3)
(1)

Addressing Considerations
If you specify literals in source modules with multiple control sections, you should:
Write a LTORG instruction at the end of each control section, so that all the
literals specified in the section are assembled into the one literal pool for that
section. If a control section is divided and interspersed among other control
sections, you should write a LTORG instruction at the end of each segment of
the interspersed control section.
When establishing the addressability of each control section, make sure (a) that
all of the literal pool for that section is also addressable, by including it within a
USING range, and (b) that the literal specifications are within the corresponding
USING domain. The USING range and domain are described in USING
Instruction on page 218.
All the literals specified after the last LTORG instruction, or, if no LTORG instruction
is specified, all the literals in a source module are assembled into a literal pool at
the end of the first control section. You must then make this literal pool
addressable, along with the addresses in the first control section. This literal pool
is printed in the program listing after the END instruction.

Duplicate Literals
If you specify duplicate literals within the part of the source module that is
controlled by a LTORG instruction, only one literal constant is assembled into the
pertinent literal pool. This also applies to literals assembled into the literal pool at
the end of the first or only control section of a source module that contains no
LTORG instructions.
Literals are duplicates only if their specifications are identical, not if the object code
assembled happens to be identical.

Chapter 5. Assembler Instruction Statements

195

MNOTE Instruction

When two literals specifying identical A-type, Y-type or S-type address constants
contain a reference to the value of the location counter (*), both literals are
assembled into the literal pool. This is because the value of the location counter
may be different in the two literals. Even if the location counter value is the same
for both, they are still both assembled into the literal pool.
The following examples show how the assembler stores pairs of literals, if the
placement of each pair is controlled by the same LTORG statement.
=X'F'
=C''

Both are
stored

=XL3''
=HL3''

Both are
stored

=A(+4)
=A(+4)

Both are
stored

=X'FFFF'
=X'FFFF'

Identical,
only one copy is stored

MNOTE Instruction
The MNOTE instruction generates your own error messages or displays
intermediate values of variable symbols computed during conditional assembly.
The MNOTE instruction can be used inside macro definitions or in open code, and
its operation code can be created by substitution. The MNOTE instruction causes
the generation of a message that is given a statement number in the printed listing.

MNOTEmessage
sequence_symbol
severity,
,
,

sequence_symbol
is a sequence symbol.
severity
is a severity code. The severity operand may be any absolute expression
allowed in the operand field of a SETA instruction. The term must have a
value in the range 0 through 255. The severity code is used to determine the
return code issued by the assembler when it returns control to the operating
system. The severity may also change the value of the system variable
symbols &SYSM_HSEV and &SYSM_SEV (see &SYSM_HSEV System
Variable Symbol on page 279 and &SYSM_SEV System Variable Symbol on
page 280).
message
is the message text. It may be any combination of characters enclosed in single
quotation marks.
The rules that apply to this character string are as follows:

196

HLASM V1R5 Language Reference

MNOTE Instruction

Variable symbols are allowed. The single quotation marks that enclose the
message can be generated from variable symbols.
Two ampersands and two single quotation marks are needed to generate
an ampersand or a single quotation mark, respectively. If variable symbols
have ampersands or single quotation marks as values, the values must be
coded as two ampersands or two single quotation marks.
If the number of characters in the character string plus the rest of the
MNOTE operand exceeds 1024 bytes the assembler issues diagnostic
message
|
|

Note: The maximum length of the second operand is three less than the
maximum supported length of SETC character string.
ASMA62E Illegal operand format
The notation can be used as a continuation.
Here is an example taken from a CICS macro:
MNOTE 8,'FIELD IS DEFINED OUTSIDE OF THE SIZE OPERAND'
MNOTE ,'PARAMETERS SPECIFIED IN THE DFHMDI MACRO,'
MNOTE ,'MACRO REQUEST IS IGNORED.'
A further advantage of this approach is that only one severity 8 error is
seen instead of three.
Double-byte data is permissible in the operand field when the DBCS
assembler option is specified. The double-byte data must be valid.
The DBCS ampersand and apostrophe are not recognized as delimiters.

A double-byte character that contains the value of an EBCDIC ampersand

or apostrophe in either byte is not recognized as a delimiter when enclosed
by SO and SI.

Remarks: Any remarks for the MNOTE instruction statement must be separated
by one or more spaces from the single quotation mark that ends the message.
If severity is provided, or severity is omitted but the comma separating it from
message is present, the message is treated as an error message; otherwise the
message is treated as comments. The rules for specifying the contents of severity
are:
The severity code can be specified as any arithmetic expression allowed in the
operand field of a SETA instruction. The expression must have a value in the
range 0 through 255.
Example:
MNOTE 2,'ERROR IN SYNTAX'
The generated result is:
2,ERROR IN SYNTAX
If the severity code is omitted, but the comma separating it from the message
is present, the assembler assigns a default value of 1 as the severity code.
Example:
MNOTE ,'ERROR, SEV 1'
The generated result is:

Chapter 5. Assembler Instruction Statements

197

OPSYN Instruction

,ERROR, SEV 1
An asterisk in the severity code subfield causes the message and the asterisk
to be generated as a comment statement.
Example:
MNOTE ,'NO ERROR'
The generated result is:
,NO ERROR
If the severity code subfield is omitted, including the comma separating it from
the message, the assembler generates the message as a comment statement.
Example:
MNOTE 'NO ERROR'
The generated result is:
NO ERROR
Notes:
1. An MNOTE instruction causes a message to be printed, if the current PRINT
option is ON, even if the PRINT NOGEN option is specified.
2. The statement number of the message generated from an MNOTE instruction
with a severity code is listed among any other error messages for the current
source module. However, the message is printed only if the severity code
specified is greater than or equal to the severity code nnn specified in the
FLAG(nnn) assembler option.
3. The statement number of the comments generated from an MNOTE instruction
without a severity code is not listed among other error messages.

OPSYN Instruction
The OPSYN instruction defines or deletes symbolic operation codes.
The OPSYN instruction has two formats. The first format defines a new operation
code to represent an existing operation code, or to redefine an existing operation
code for:
Machine and extended mnemonic branch instructions
Assembler instructions, including conditional assembly instructions
Macro instructions
Define Operation Code
symbolOPSYNoperation_code_2
operation_code_1

The second format deletes an existing operation code for:

Machine and extended mnemonic branch instructions
Assembler instructions, including conditional assembly instructions
Macro instructions

198

HLASM V1R5 Language Reference

OPSYN Instruction

Delete Operation Code

operation_code_1OPSYN

symbol
is one of the following:
An ordinary symbol that is not the same as an existing operation code
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol and is not the same as an existing
operation code
operation_code_1
is one of the following:
An operation code described in this chapter, or in Chapter 4, Machine
Instruction Statements on page 78, or Chapter 9, How to Write
Conditional Assembly Instructions on page 318
The operation code defined by a previous OPSYN instruction
The name of a previously defined macro.
operation_code_2
is one of the following:
An operation code described in this chapter, or in Chapter 4, Machine
Instruction Statements on page 78, or Chapter 9, How to Write
Conditional Assembly Instructions on page 318
The operation code defined by a previous OPSYN instruction
In the first format, the OPSYN instruction assigns the properties of the operation
code denoted by operation_code_2 to the ordinary symbol denoted by symbol or
the operation code denoted by operation_code_1.
In the second format, the OPSYN instruction causes the operation code specified in
operation_code_1 to lose its properties as an operation code.
The OPSYN instruction can be coded anywhere in the program to redefine an
operation code.
The symbol in the name field can represent a valid operation code. It loses its
current properties as if it had been defined in an OPSYN instruction with a
space-filled operand field. In the following example, L and LR both possess the
properties of the LR machine instruction operation code:
L

OPSYN

When the same symbol appears in the name field of two OPSYN instructions, the
latest definition takes precedence. In the example below, STORE now represents the
STH machine operation:
STORE
STORE

OPSYN
OPSYN

ST
STH

Note: OPSYN is not processed during lookahead mode (see Lookahead on

page 340). Therefore it cannot be used during lookahead to replace an opcode that
must be processed during lookahead, such as COPY. For example, assuming
Chapter 5. Assembler Instruction Statements

199

ORG Instruction

AFTER is defined in COPYBOOK, the following code gives an ASMA042E error

(Length attribute of symbol is unavailable):
AIF (L'AFTER LT 2).BEYOND
OPSYN COPY
OPSYN not processed during look ahead
OPCOPY COPYBOOK
OPCOPY fails
.BEYOND ANOP ,
OPCOPY

Redefining Conditional Assembly Instructions

A redefinition of a conditional assembly instruction only comes into effect in macro
definitions occurring after the OPSYN instruction. The original definition is always
used when a macro instruction calls a macro that was defined and edited before
the OPSYN instruction.
An OPSYN instruction that redefines the operation code of an assembler or
machine instruction generated from a macro instruction is, however, effective
immediately, even if the definition of the macro was made prior to the OPSYN
instruction. Consider the following example:

AIF
MVC

MACRO
MAC
AIF
MVC
.
MEND
.
OPSYN
OPSYN
.
MAC

MVC
.
.
AIF
MVC

...
...
...

Macro header
Macro prototype

Macro trailer
AGO
MVI

Assign AGO properties to AIF

Assign MVI properties to MVC

...

Macro call
(AIF interpreted as AIF instruction; generated AIFs not printed)
Interpreted as MVI instruction

...
...

Open code started at this point

Interpreted as AGO instruction
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
instructions are used to assign the properties of AGO to AIF and to assign the
properties of MVI to MVC. In subsequent calls of the macro MAC, 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
instructions. 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.

ORG Instruction
The ORG instruction alters the setting of the location counter and thus controls the
structure of the current control section. This redefines portions of a control section.
If a control section has not been previously established, ORG will initiate an
unnamed (private) control section.

200

HLASM V1R5 Language Reference

ORG Instruction

ORG
symbol
|
|
|
|

expression
,boundary

,offset
,offset

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
If symbol denotes an ordinary symbol, the ordinary symbol is defined with the
value that the location counter had before the ORG statement is processed.
expression
is a relocatable expression, the value of which is used to set the location
counter. If expression is omitted, the location counter is set to the next
available location for the current control section.
|
|
|
|

boundary
is an absolute expression that must be a power of 2 with a range from 8
(doubleword) to 4096 (page). If boundary exceeds the SECTALGN value,
message ASMA500E is issued.

|
|

offset
Any absolute expression

|
|
|

If boundary or offset are provided, then the resultant location counter is calculated
by rounding the expression up to the next higher boundary and then adding the
offset value.
In general, symbols used in expression need not have been previously defined.
However, the relocatable component of expression (that is, the unpaired relocatable
term) must have been previously defined in the same control section in which the
ORG statement appears, or be equated to a previously defined value.
A length attribute reference to the name of a ORG instruction is always invalid.
Message ASMS042E is issued, and a default value of 1 is assigned.
An ORG statement cannot be used to specify a location below the beginning of the
control section in which it appears. For example, the following statement is not
correct if it appears less than 500 bytes from the beginning of the current control
section.
ORG

This is because the expression specified is negative, and sets the location counter
to a value larger than the assembler can process. The location counter wraps
around (the location counter is discussed in detail in Location Counter on
page 36).
Chapter 5. Assembler Instruction Statements

201

ORG Instruction

If you specify multiple location counters with the LOCTR instruction, the ORG
instruction can alter only the location counter in use when the instruction appears.
Thus, you cannot control the structure of the whole control section using ORG, but
only the part that is controlled by the current location counter.
An ORG statement cannot be used to change sections or LOCTR segments. For
example:
AA
X
Y
BB

CSECT
DS
DS
CSECT
ORG

D
F
Y

is invalid, because the section containing the ORG statement (BB) is not the same
as the section in AA in which the ORG operand expression Y is defined.
With the ORG statement, you can give two instructions the same location counter
values. In such a case, the second instruction does not always eliminate the
effects of the first instruction. Consider the following example:
ADDR
B

DC
ORG
DC

A(ADDR)
4
C'BETA'

In this example, the value of B ('BETA') is destroyed by the relocation of ADDR

during linkage editing.
|
|

The following example shows some examples of ORG using the boundary and
offset operands:

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

origin

csect
ds
org
org
org
translate dc
org
dc
org
dc
org
dc
org
dc
org
dc
org
dc
org
end

235x
origin,,3
,8
,8,-2
cl256' '
translate+c'a'
c'ABCDEFGHI'
translate+c'j'
c'JKLMNOPQR'
translate+c's'
c'STUVWXYZ'
translate+c'A'
c'ABCDEFGHI'
translate+c'J'
c'JKLMNOPQR'
translate+c'S'
c'STUVWXYZ'
,

Define 235 bytes

Move location counter back to start + 3
Align on 8 byte boundary
Align to 8 byte boundary -2 bytes
Define aligned translate table

Using Figure 57 on page 203 as an example, to build a translate table (for

example, to convert EBCDIC character code into some other internal code):
1. Define the table (see 1 in Figure 57) as being filled with zeros.
2. Use the ORG instruction to alter the location counter so that its counter value
indicates a specific location (see 2 in Figure 57) within the table.

202

HLASM V1R5 Language Reference

ORG Instruction

3. Redefine the data (see 3 in Figure 57) to be assembled into that location.
4. After repeating the first three steps (see 4 in Figure 57) until your translate
table is complete, use an ORG instruction with a null operand field to alter the
location counter. The counter value then indicates the next available location
(see 5 in Figure 57) in the current control section (after the end of the
translate table).
Both the assembled object code for the whole table filled with zeros, and the object
code for the portions of the table you redefined, are printed in the program listings.
However, the data defined later is loaded over the previously defined zeros and
becomes part of your object program, instead of the zeros.
That is, the ORG instruction can cause the location counter to be set to any part of
a control section, even the middle of an instruction, into which you can assemble
data. It can also cause the location counter to be set to the next available location
so that your program can be assembled sequentially.
Source Module

Object Code

FIRST
START

1
TABLE
DC
XL256''
TABLE
(in Hex)
2
ORG
TABLE+
+

DC
C''
3

DC
C'1'

ORG
TABLE+13
+13
.

DC
C'D'

DC
C'E'

.
4

ORG
TABLE+C'D'

DC
AL1(13)
+196
13

DC
AL1(14)

ORG
TABLE+C''
+24
.

DC
AL1()

DC
AL1(1)

.
+255

ORG

5
GOON
DS
H

TABLE+256
.

TR
INPUT,TABLE

INPUT
DS
CL2

END

Figure 57. Building a Translate Table

Chapter 5. Assembler Instruction Statements

203

POP Instruction

POP Instruction
The POP instruction restores the PRINT, USING or ACONTROL status saved by
the most recent PUSH instruction.

,
PRINT
(1)
POP

sequence_symbol
USING
,NOPRINT
ACONTROL
Note:
Each keyword from this group may be selected only once.

sequence_symbol
is a sequence symbol.
PRINT
instructs the assembler to restore the PRINT status to the status saved by the
most recent PUSH instruction.
USING
instructs the assembler to restore the USING status to the status saved by the
most recent PUSH instruction.
ACONTROL
instructs the assembler to restore the ACONTROL status to the status saved
by the most recent PUSH instruction.
NOPRINT
instructs the assembler to suppress the printing of the POP statement in which
it is specified.
The POP instruction causes the status of the current PRINT, USING or
ACONTROL instruction to be overridden by the PRINT, USING or ACONTROL
status saved by the last PUSH instruction. For example:
PRINT
DCMAC
DC
PUSH
PRINT
DCMAC
POP
DCMAC
DC

GEN
X,27
X'27'
PRINT
NOGEN
X,33
PRINT
X,42
X'42'

Printed macro generated code

Call macro to generate DC
... Generated statement
Save PRINT status
Suppress macro generated code
Call macro to generate DC
Restore PRINT status
Call macro to generate DC
... Generated statement

PRINT Instruction
The PRINT instruction controls the amount of detail printed in the listing of
programs.

,
operand
PRINT
sequence_symbol

204

HLASM V1R5 Language Reference

PRINT Instruction

sequence_symbol
is a sequence symbol.
operand
is an operand from one of the groups of operands described below. If a null
operand is supplied, it is accepted by the assembler with no effect on the other
operands specified. The operands are listed in hierarchic order. The effect, if
any, of one operand on other operands is also described.

ON

OFF

ON
instructs the assembler to print, or resume printing, the source and object
section of the assembler listing.
OFF
instructs the assembler to stop printing the source and object section of the
assembler listing. A subsequent PRINT ON instruction resumes printing.
When this operand is specified the printing actions requested by the GEN,
DATA, MCALL, and MSOURCE operands do not apply.

GEN

NOGEN

GEN
instructs the assembler to print all statements generated by the processing of a
macro. This operand does not apply if PRINT OFF has been specified.
NOGEN
instructs the assembler not to print statements generated by conditional
assembly or the processing of a macro. This applies to all levels of macro
nesting; no generated code is displayed while PRINT NOGEN is in effect. If
this operand is specified, the DATA operand does not apply to constants that
are generated during macro processing. Also, if this operand is specified, the
MSOURCE operand does not apply. 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:
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.
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.

Chapter 5. Assembler Instruction Statements

205

PRINT Instruction

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.
The MNOTE instruction always causes a message to be printed.

NODATA

DATA

NODATA
instructs the assembler to print only the first 8 bytes of the object code of
constants. This operand does not apply if PRINT OFF has been specified. If
PRINT NOGEN has been specified, this operand does not apply to constants
generated during macro processing.
DATA
instructs the assembler to print the object code of all constants in full. This
operand does not apply if PRINT OFF has been specified. If PRINT NOGEN
has been specified, this operand does not apply to constants generated during
macro processing.

NOMCALL

MCALL

NOMCALL
instructs the assembler to suppress the printing of nested macro call
instructions.
MCALL
instructs the assembler to print nested macro call instructions, including the
name of the macro definition to be processed and the operands and values
passed to the macro definition. The assembler only prints the operands and
comments up to the size of its internal processing buffer. If this size is
exceeded the macro call instruction is truncated, and the characters ... MORE
are added to the end of the printed macro call. This does not affect the
processing of the macro call.
This operand does not apply if either PRINT OFF or PRINT NOGEN has been
specified.

MSOURCE

NOMSOURCE

MSOURCE
instructs the assembler to print the source statements generated during macro
processing, as well as the assembled addresses and generated object code of
the statements. This operand does not apply if either PRINT OFF or PRINT
NOGEN has been specified.

206

HLASM V1R5 Language Reference

PRINT Instruction

NOMSOURCE
instructs the assembler to suppress the printing of source statements generated
during macro processing, without suppressing the printing of the assembled
addresses and generated object code of the statements. This operand does
not apply if either PRINT OFF or PRINT NOGEN has been specified.

UHEAD

NOUHEAD

UHEAD
instructs 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. This operand does not apply if PRINT OFF has been
specified.
NOUHEAD
instructs the assembler not to print a summary of active USINGs.

NOPRINT

NOPRINT
instructs the assembler to suppress the printing of the PRINT statement in
which it is specified. The NOPRINT operand may only be specified in
conjunction with one or more other operands.
The PRINT instruction can be specified any number of times in a source module,
but only those operands actually specified in the instruction change the current print
status.
PRINT options can be generated by macro processing during conditional assembly.
However, at assembly time, all options are in force until the assembler encounters
a new and opposite option in a PRINT instruction.
The PUSH and POP instructions, described in PUSH Instruction on page 209 and
POP Instruction on page 204, also influence the PRINT options by saving and
restoring the PRINT status.
You can override the effect of the operands of the PRINT instruction by using the
PCONTROL assembler option. For more information about this option, see the
HLASM Programmer's Guide.
Unless the NOPRINT operand is specified, or the assembler listing is suppressed
by the NOLIST assembler option, the PRINT instruction itself is printed.

Chapter 5. Assembler Instruction Statements

207

Process Statement

Process Statement
The process statement is described under *PROCESS Statement on page 102.

PUNCH Instruction
The PUNCH instruction creates a record containing a source or other statement, or
an object record, to be written to the object file.

PUNCHstring
sequence_symbol

sequence_symbol
is a sequence symbol.
string
is a character string of up to 80 characters, enclosed in single quotation marks.
All 256 characters in the EBCDIC character set are allowed in the character
string. Variable symbols are also allowed.
Double-byte data is permissible in the operand field when the DBCS assembler
option is specified. However, the following rules apply to double-byte data:
The DBCS ampersand and the single quotation mark are not recognized as
delimiters.
A double-byte character that contains the value of an EBCDIC ampersand
or a single quotation mark in either byte is not recognized as a delimiter
when enclosed by SO and SI.
The position of each character specified in the PUNCH statement corresponds
to a column in the record to be punched. However, the following rules apply to
ampersands and single quotation marks:
A single ampersand initiates an attempt to identify a variable symbol and to
substitute its current value.
A pair of ampersands is punched as one ampersand.
A pair of single quotation marks is punched as one single quotation mark.
An unpaired single quotation mark followed by one or more spaces simply
ends the string of characters punched. If a non-space character follows an
unpaired single quotation mark, an error message is issued and nothing is
punched.
Only the characters punched, including spaces, count toward the maximum of
80 allowed.
The PUNCH instruction causes the data in its operand to be punched into a record.
One PUNCH instruction produces one record, but as many PUNCH instructions as
necessary can be used.
You can code PUNCH statements in:
A source module to produce control statements for the linker. The linker uses
these control statements to process the object module.

208

HLASM V1R5 Language Reference

PUSH Instruction

Macro definitions to produce, for example, source statements in other computer

languages or for other processing phases.
The assembler writes the record produced by a PUNCH statement when it writes
the object deck. The ordering of this record in the object deck is determined by the
order in which the PUNCH statement is processed by the assembler. The record
appears after any object deck records produced by previous statements, and before
any other object deck records produced by subsequent statements.
The PUNCH instruction statement can appear anywhere in a source module. If a
PUNCH instruction occurs before the first control section, the resultant record
punched precedes all other records in the object deck.
The record punched as a result of a PUNCH instruction is not a logical part of the
object deck, even though it can be physically interspersed in the object deck.
Notes:
1. The identification and sequence number field generated as part of other object
deck records is not generated for the record punched by the PUNCH
instruction.
2. If the NODECK and NOOBJECT assembler options are specified, no records
are punched for the PUNCH instruction.
|
|

3. Do not use the PUNCH instruction if the GOFF option is specified, as the
resulting file may be unusable.

PUSH Instruction
The PUSH instruction saves the current PRINT, USING or ACONTROL status in
push-down storage on a last-in, first-out basis. You restore this PRINT, USING or
ACONTROL status later, also on a last-in, first-out basis, by using a POP
instruction.

,
PRINT
(1)
PUSH

_
sequence symbol
USING
,NOPRINT
ACONTROL
Note:
Each keyword from this group may be selected only once.

sequence_symbol
is a sequence symbol.
PRINT
instructs the assembler to save the PRINT status in a push-down stack.
USING
instructs the assembler to save the USING status in a push-down stack.
ACONTROL
instructs the assembler to save the ACONTROL status in a push-down stack.

Chapter 5. Assembler Instruction Statements

209

REPRO Instruction

NOPRINT
instructs the assembler to suppress the printing of the PUSH statement in
which it is specified.
The PUSH instruction only causes the status of the current PRINT, USING or
ACONTROL instructions to be saved. The PUSH instruction does not:
Change the status of the current PRINT or ACONTROL instructions
Imply a DROP instruction, or change the status of the current USING
instructions

REPRO Instruction
The REPRO instruction causes the data specified in the statement that follows to
be punched into records, to be written to the object file.

REPRO
sequence_symbol

sequence_symbol
is a sequence symbol.
The REPRO instruction can appear anywhere in a source module. One REPRO
instruction produces one punched record, but as many REPRO instructions as
necessary can be used. Records are created as the object file is being created, so
records may be interspersed among object code. The punched records are part of
the object file, but are not intended to contain normal object code or symbols.
The statement to be reproduced can contain any of the 256 characters in the
EBCDIC character set, including spaces, ampersands, and single quotation marks.
Unlike the PUNCH instruction, the REPRO instruction does not allow values to be
substituted into variable symbols before the record is punched.
Notes:
1. The identification and sequence numbers generated as part of other object
deck records is not generated for records punched by the REPRO instruction.
2. If the NODECK and NOOBJECT assembler options are specified, no records
are punched for the REPRO instruction, or for the object deck of the assembly.
3. Since the text of the line following a REPRO statement is not validated or
changed in any way, it can contain double-byte data, but this data is not
validated.
|
|

4. Do not use the REPRO instruction if the GOFF option is specified, as the
resulting file may be unusable.

210

HLASM V1R5 Language Reference

RMODE Instruction

RMODE Instruction
The RMODE instruction specifies the residence mode to be associated with control
sections in the object deck.

RMODE24
name
31
64
ANY

name
is the name field that associates the residence mode with a control section. If
there is a symbol in the name field, it must also appear in the name field of a
START, CSECT, RSECT, or COM instruction in this assembly. If the name
field is space-filled, there must be an unnamed control section in this assembly.
If the name field contains a sequence symbol (see Symbols on page 29 for
details), it is treated as a blank name field.
24 specifies that a residence mode of 24 is to be associated with the control
section; that is, the control section must be resident below 16 megabytes.
31 specifies that a residence mode of either 24 or 31 is to be associated with the
control section; that is, the control section can be resident above or below 16
megabytes.
64 Specifies that a residence mode of 64 is to be associated with the control
section (see 64-bit Addressing Mode on page 101).
ANY
is understood to mean RMODE 31.
Any field of this instruction may be generated by a macro, or by substitution in open
code.
Notes:
1. RMODE can be specified anywhere in the assembly. It does not initiate an
unnamed control section.
2. An assembly can have multiple RMODE instructions; however, two RMODE
instructions cannot have the same name field.
3. The valid and invalid combinations of AMODE and RMODE are shown in the
following table. Note that combinations involving AMODE 64 and RMODE 64
are subject to the support outlined in 64-bit Addressing Mode on page 101.
Figure 58. AMODE/RMODE Combinations
RMODE 24

RMODE 31

RMODE 64

AMODE 24

invalid

AMODE 31

invalid

AMODE ANY|ANY31

invalid

AMODE 64

Chapter 5. Assembler Instruction Statements

211

RSECT Instruction

4. AMODE or RMODE cannot be specified for an unnamed common control

section.
5. The defaults used when zero or one MODE is specified are shown in the
following table. Note that combinations involving AMODE 64 and RMODE 64
are subject to the support outlined in 64-bit Addressing Mode on page 101.
Figure 59. AMODE/RMODE Defaults
Specified

Default

Neither

AMODE 24,RMODE 24

AMODE 24

RMODE 24

AMODE 31

RMODE 24

AMODE ANY|ANY31

RMODE 24

AMODE 24

RMODE 31 (was ANY)

AMODE 31

AMODE 64

RMODE 31

RMODE 64

AMODE 64

RSECT Instruction
The RSECT instruction initiates a read-only executable control section or indicates
the continuation of a read-only executable control section.

RSECT
symbol

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
When an executable control section is initiated by the RSECT instruction, the
assembler automatically checks the control section for possible coding violations of
program reenterability, regardless of the setting of the RENT assembler option. As
the assembler cannot check program logic, the checking is not exhaustive.
Non-reentrant code is diagnosed by a warning message.
The RSECT instruction can be used anywhere in a source module after the ICTL
instruction. If it is used to initiate the first executable control section, it must not be
preceded by any instruction that affects the location counter and thereby causes
the first control section to be initiated.
If symbol denotes an ordinary symbol, the ordinary symbol identifies the control
section. If several RSECT instructions within a source module have the same
symbol in the name field, the first occurrence initiates the control section and the

212

HLASM V1R5 Language Reference

SPACE Instruction

rest indicate the continuation of the control section. The ordinary symbol denoted
by symbol represents the address of the first byte in the control section, and has a
length attribute value of 1.
If symbol is not specified, or if name is a sequence symbol, the RSECT instruction
initiates or indicates the continuation of the unnamed control section.
See CSECT Instruction on page 123 for a discussion on the interaction between
RSECT and the GOFF assembler option.
|
|

The beginning of a control section is aligned on a boundary determined by the

SECTALGN option. However, when an interrupted control section is continued
using the RSECT instruction, the location counter last specified in that control
section is continued.
The source statements following a RSECT instruction that either initiate or indicate
the continuation of a control section are assembled into the object code of the
control section identified by that RSECT instruction.
Notes:
1. The assembler indicates that a control section is read-only by setting the
read-only attribute in the object module.
2. The end of a control section or portion of a control section is marked by (a) any
instruction that defines a new or continued control section, or (b) the END
instruction.

SPACE Instruction
The SPACE instruction inserts one or more blank lines in the listing of a source
module. This separates sections of code on the listing page.

SPACE
sequence_symbol
number_of_lines

sequence_symbol
is a sequence symbol.
number_of_lines
is an absolute expression that specifies the number of lines to be left blank.
You may use any absolute expression to specify number_of_lines. If
number_of_lines is omitted, one line is left blank. If number_of_lines has a
value greater than the number of lines remaining on the listing page, the
instruction has the same effect as an EJECT statement.
The SPACE statement itself is not printed in the listing unless a variable symbol is
specified as a point of substitution in the statement, in which case the statement is
printed before substitution occurs.

Chapter 5. Assembler Instruction Statements

213

START Instruction

START Instruction
The START instruction can be used to initiate the first or only control section of a
source module, and optionally to set an initial location counter value.

START
symbol
expression

symbol
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
A sequence symbol
expression
is an absolute expression, the value of which the assembler uses to set the
location counter to an initial value for the source module.
Any symbols referenced in expression must have been previously defined.
The START instruction must be the first instruction of the first executable control
section of a source module. It must not be preceded by any instruction that affects
the location counter, and thereby causes the first control section to be initiated.
Use the START instruction to initiate the first or only control section of a source
module, because it:
Determines exactly where the first control section is to begin, thus avoiding the
accidental initiation of the first control section by some other instruction.
Gives a symbolic name to the first control section, which can then be
distinguished from the other control sections listed in the external symbol
dictionary.
Specifies the initial setting of the location counter for the first or only control
section.
If symbol denotes an ordinary symbol, the ordinary symbol identifies the first control
section. It must be used in the name field of any CSECT instruction that indicates
the continuation of the first control section. The ordinary symbol denoted by
symbol represents the address of the first byte in the control section, and has a
length attribute value of 1.
If symbol is not specified, or if name is a sequence symbol, the START instruction
initiates an unnamed control section.
The assembler uses the value expression in the operand field, if specified, to set
the location counter to an initial value for the source module. All control sections
are aligned on the boundary specified by the SECTALGN option. Therefore, if the
value specified in expression is not divisible by the SECTALGN value, the
assembler sets the initial value of the location counter to the next higher required
boundary. If expression is omitted, the assembler sets the initial value to 0.

|
|
|

214

HLASM V1R5 Language Reference

TITLE Instruction

The source statements that follow the START instruction are assembled into the
first control section. If a CSECT instruction indicates the continuation of the first
control section, the source statements that follow this CSECT instruction are also
assembled into the first control section.
Any instruction that defines a new or continued control section marks the end of the
preceding control section. The END instruction marks the end of the control
section in effect.

TITLE Instruction
The TITLE instruction:
Provides headings for each page of the source and object section of the
assembler listing. If the first statement in your source program is an ICTL
instruction or a *PROCESS statement then the title is not printed on the first
page of the Source and Object section, because each of these instructions
must precede all other instructions.
Identifies the assembly output records of your object modules. You can specify
up to 8 identification characters that the assembler includes as a deck ID in all
object records, beginning at byte 73. If the deck ID is less than 8 characters,
the assembler puts sequence numbers in the remaining bytes up to byte 80.
TITLEtitle_string
name

name
You can specify name only once in the source module. It is one of the
following:
A string of printable characters
A variable symbol that has been assigned a string of printable characters
A combination of the above
A sequence symbol
Except when the name is a sequence symbol, the assembler uses the first 8
characters you specify, and discards the remaining characters without warning.
title_string
is a string of 1 to 100 characters enclosed in single quotation marks
If two or more TITLE instructions are together, the title provided by the last
instruction is printed as the heading.

Deck ID in Object Records

When you specify the name, and it is not a sequence symbol, it has a special
significance. The assembler uses the name value to generate the deck ID in object
records. The deck ID is placed in the object records starting at byte 73. It is not
generated for records produced by the PUNCH and REPRO instructions. The
name value does not need to be on the first TITLE instruction.

Chapter 5. Assembler Instruction Statements

215

TITLE Instruction

The name value is not defined as a symbol, so it can be used in the name entry of
any other statement in the same source module, provided it is a valid ordinary
symbol.
GOFF Assembler Option (MVS and CMS): When you specify the GOFF
assembler option the deck ID is not generated.

Printing the Heading

The character string denoted by title_string is printed as a heading at the top of
each page of the source and object section of the assembler listing. The heading
is printed beginning on the page in the listing that follows the page on which the
TITLE instruction is specified. A new heading is printed each time a new TITLE
instruction occurs in the source module. If the TITLE instruction is the first
instruction in the source module the heading is printed on the first page of the
listing.
When a TITLE instruction immediately follows an EJECT instruction, the assembler
changes the title but does not perform an additional page-eject.

Printing the TITLE Statement

The TITLE statement is printed in the listing when you specify a variable symbol in
the name, or in the title_string, in which case the statement is printed before
substitution occurs.

Sample Program Using the TITLE Instruction

The following example shows three TITLE instructions:
PGM1
PGM1

&VARSYM

TITLE 'The First Heading'

CSECT
USING PGM1,12
TITLE 'The Next Heading'
LR
12,15
SETC 'Value from Variable
TITLE 'The &VARSYM'
BR
14
END

Assign the base register

Load the base address
Symbol'
Return

After the program is assembled, the characters PGM1 are placed in bytes 73 to 76 of
all object records, and the heading appears at the top of each page in the listing as
shown in Figure 60 on page 217. The TITLE instruction at statement 7 is printed
because it contains a variable symbol.

216

HLASM V1R5 Language Reference

TITLE Instruction

PGM1
The First Heading
Active Usings: None
Loc Object Code
Addr1 Addr2

4
R:C
PGM1
The Next Heading
Active Usings: PGM1,R12
Loc Object Code
Addr1 Addr2
18CF

Page
Stmt
Source Statement
2 PGM1
CSECT
3
USING PGM1,12

Stmt
Source
5
6 &VARSYM
7
PGM1
The Value from Variable Symbol
Active Usings: PGM1,R12
Loc Object Code
Addr1 Addr2 Stmt
Source
2 7FE
8
9

HLASM R5.

24/6/11 17.48
LRM2

Assign the base register

Page

Statement
HLASM R5.
LR
12,15
Load the base address
SETC 'Value from Variable Symbol'
TITLE 'The &VARSYM'

24/6/11 17.48

Page
Statement
BR
14
END

HLASM R5.

24/6/11 17.48

Return
LRM9

Figure 60. Sample Program Using TITLE Instruction

Page Ejects
Each inline TITLE statement causes the listing to be advanced to a new page
before the heading is printed unless it is preceded immediately by one of the
following:
A CEJECT instruction
An EJECT instruction
A SPACE instruction that positions the current print line at the start of a new
page
A TITLE instruction
If the TITLE statement appears in a macro or contains a variable symbol and
PRINT NOGEN is specified, the listing is not advanced to a new page.

Valid Characters
Any printable character specified appears in the heading, including spaces.
Double-byte data can be used when the DBCS assembler option is specified. The
double-byte data must be valid. Variable symbols are allowed. However, the
following rules apply to ampersands and single quotation marks:
The DBCS ampersand and single quotation mark are not recognized as
delimiters.
A double-byte character that contains the value of an EBCDIC ampersand or
single quotation mark in either byte is not recognized as a delimiter when
enclosed by SO and SI.
A single ampersand initiates an attempt to identify a variable symbol and to
substitute its current value.
A pair of ampersands is printed as one ampersand.
A pair of single quotation marks is printed as one single quotation mark.
An unpaired single quotation mark followed by one or more spaces simply ends
the string of characters printed. If a non-space character follows an unpaired
single quotation mark, the assembler issues an error message and prints no
heading.

Chapter 5. Assembler Instruction Statements

217

USING Instruction

Only the characters printed in the heading count toward the maximum of 100
characters allowed. If the count of characters to be printed exceeds 100, the
heading that is printed is truncated and error diagnostic message
ASMA62E Illegal operand format
is issued.

USING Instruction
The USING instruction specifies a base address and range and assigns one or
more base registers. If you also load the base register with the base address, you
have established addressability in a control section. If a control section has not
been established, USING will initiate an unnamed (private) control section.
To use the USING instruction correctly, you should know:
Which locations in a control section are made addressable by the USING
instruction
Where in a source module you can use implicit addresses in instruction
operands to refer to these addressable locations
Base Address: The term base address is used throughout this manual to mean
the location counter value within a control section from which the assembler can
compute displacements to locations, or addresses, within the control section. Don't
confuse this with the storage address of a control section when it is loaded into
storage at execution time.
The USING instruction has three formats:
The first format specifies a base address, an optional range, and one or more
base registers. This format of the USING instruction is called an ordinary
USING instruction, and is described under Ordinary USING Instruction on
page 220.
The second format specifies a base address, an optional range, one or more
base registers, and a USING label which may be used as a symbol qualifier.
This format of the USING instruction is called a labeled USING instruction, and
is described under Labeled USING Instruction on page 223.
The third format specifies a base address, an optional range, and a relocatable
expression instead of one or more base registers. This format of a USING
instruction is called a dependent USING instruction, and is described under
Dependent USING Instruction on page 226. If a USING label is also
specified, this format of the USING instruction is called a labeled dependent
USING instruction.
Note: The assembler identifies and warns about statements where the implied
alignment of an operand does not match the requirements of the instruction.
However, if the base for a USING is not aligned on the required boundary, the
assembler cannot diagnose a problem. For example:

218

HLASM V1R5 Language Reference

USING Instruction

DS1
|
|

|
|
|
|

DSECT
DS
REGPAIR DS
DS2
DSECT
REGPAIR_ALIGN
CSECT
...
USING
USING
STPQ
STPQ

H
2ADL8

Halfword alignment

DS 2ADL8

Doubleword alignment

DS1,R1
DS2,REGPAIR
R,REGPAIR
R,REGPAIR_ALIGN

Ordinary USING
Dependent USING
REGPAIR is not a quadword
But REGPAIR_ALIGN is

The first STPQ instruction is diagnosed as an alignment error. The second STPQ
instruction is not, even though the same storage location is implied by the code.
You must take care to ensure base addresses match the alignment requirements of
storage mapped by a USING. For a description of the alignment requirements of
instructions, see the relevant Principles of Operation.

How to Use the USING Instruction

Specify the USING instruction so that:
All the required implicit addresses in each control section lie within a USING
range.
All the references for these addresses lie within the corresponding USING
domain.
You could, therefore, place all ordinary USING instructions at the beginning of the
control section and specify a base address in each USING instruction that lies at
the beginning of each control section.
For Executable Control Sections: To establish the addressability of an
executable control section defined by a START or CSECT instruction, specify a
base address and assign a base register in the USING instruction. At execution
time, the base register must be loaded with the correct base address.

|
|

|
|
|
|
|

If a control section requires addressability to more than 4096 bytes, you must
assign more than one base register, or make implicit references using only
instructions supporting 20-bit displacements (long displacements). This
establishes the addressability of the entire control section with one USING
instruction.
For Reference Control Sections: A dummy section is a reference control section
defined by the DSECT instructions. To establish the addressability of a dummy
section, specify the address of the first byte of the dummy section as the base
address, so that all its addresses lie within the pertinent USING range. The
address you load into the base register must be the address of the storage area
being described by the dummy section. However, if all references to fields withing
the DSECT are made with instructions supporting long displacements, the base
address need not be the first byte of the dummy section.
When you refer to symbolic addresses in the dummy section, the assembler
computes displacements accordingly. However, at execution time, the assembled
addresses refer to the location of real data in the storage area.

Chapter 5. Assembler Instruction Statements

219

USING Instruction

Base Registers for Absolute Addresses

Absolute addresses used in a source module must also be made addressable.
Absolute addresses require a base register other than the base register assigned to
relocatable addresses (as described above).
However, the assembler does not need a USING instruction to convert absolute
implicit addresses in the range 0 through 4095 to their explicit form. The assembler
uses register 0 as a base register. Displacements are computed from the base
address 0, because the assembler assumes that a base or index of 0 implies that a
zero quantity is to be used in forming the address, regardless of the contents of
register 0. The USING domain for this automatic base register assignment is the
entire source module.
|
|

If a register is specified with base address zero, the assembler will use it in
preference to the default use of register zero. For example:

|
|

USING 3,
LA
7,5

|
|

generates the instruction X'41703005'; in the absence of the USING statement, the
generated instruction would be X'41700005'.
For absolute implicit addresses greater than 4095 and in the absence of
long-displacement instructions, a USING instruction must be specified according to
the following:
With a base address representing an absolute expression
With a base register that has not been assigned by a USING instruction in
which a relocatable base address is specified
This base register must be loaded with the base address specified.

Ordinary USING Instruction

The ordinary USING instruction format specifies a base address and one or more
base registers.
Ordinary USING
USINGbase
sequence_symbol
(base)
,end

,base_register

sequence_symbol
is a sequence symbol.
base
specifies a base address, which can be a relocatable or an absolute
expression. The value of the expression must lie between 0 and 2311.
end
specifies the end address, which can be a relocatable or an absolute
expression. The value of the expression must lie between 0 and 2311. The
end address may exceed the (base address + default range) without error. The

220

HLASM V1R5 Language Reference

USING Instruction

end address must be greater than the base and must have the same
relocatability attributes.
The resolvable range of a USING with an 'end' operand is
base,MIN(495,end-1)
Thus USING base,reg is equivalent to USING (base,base+496),reg.
base_register
is an absolute expression whose value represents general registers 0 through
15.
The default range is 4096 per base register.
The assembler assumes that the base register denoted by the first base_register
operand contains the base address base at execution time. If present, the
subsequent base_register operands represent registers that the assembler
assumes contain the address values base+4096, base+8192, and so forth.
For example:
USING

BASE,9,1,11

has the logical equivalent of:

USING
USING
USING

BASE,9
BASE+496,1
BASE+8192,11

In another example, the following statement:

USING

,12,13

tells the assembler to assume that the current value of the location counter is in
general register 12 at execution time, and that the current value of the location
counter, incremented by 4096, is in general register 13 at execution time.
Computing Displacement: If you change the value in a base register being used,
and want the assembler to compute displacements from this value, you must tell
the assembler the new value by means of another USING statement. In the
following sequence, the assembler first assumes that the value of ALPHA is in
register 9. The second statement then causes the assembler to assume that
ALPHA+1 is the value in register 9.
USING
.
.
USING

ALPHA,9

ALPHA+1,9

Using General Register Zero: You can refer to the first 4096 bytes of storage
using general register 0, subject to the following conditions:
The value of operand base must be either absolute or relocatable zero.
Register 0 must be specified as the first base_register operand.
The assembler assumes that register 0 contains zero. Therefore, regardless of the
value of operand base, it calculates displacements as if operand base were
absolute or relocatable zero. The assembler also assumes that subsequent
registers specified in the same USING statement contain 4096, 8192, etc.

Chapter 5. Assembler Instruction Statements

221

USING Instruction

If register 0 is used as a base register, the referenced control section (or dummy
section) is not relocatable, despite the fact that operand base may be relocatable.
The control section can be made relocatable by:
Replacing register 0 in the USING statement
Loading the new register with a relocatable value
Reassembling the program

Range of an Ordinary USING Instruction

The range of an ordinary USING instruction (called the ordinary USING range, or
simply the USING range) is the 4096 bytes beginning at the base address specified
in the USING instruction, or the range as specified by the range end, whichever is
the lesser. For long-displacement instructions, the range is the addresses between
(base_address-524288) and (base_address+524287). Addresses that lie within the
USING range can be converted from their implicit to their explicit
base-displacement form using the designated base registers; those outside the
USING range cannot be converted.

|
|

The USING range does not depend upon the position of the USING instruction in
the source module; rather, it depends upon the location of the base address
specified in the USING instruction.
The USING range is the range of addresses in a control section that is associated
with the base register specified in the USING instruction. If the USING instruction
assigns more than one base register, the composite USING range is the union of
the USING ranges that would apply if the base registers were specified in separate
USING instructions.
|

Note that USING ranges need not be contiguous. For example, you could specify

|
|

USING X,4
USING X+6,5

|
|

and implicit addresses with values between X+4096 and X+5999 would not be
addressable by instructions with unsigned 12-bit displacements.
Two USING ranges coincide when the same base address is specified in two
different USING instructions, even though the base registers used are different.
When two USING ranges coincide, the assembler uses the higher-numbered
register for assembling the addresses within the common USING range. In effect,
the domain of the USING instruction that specifies the lower-numbered register is
ended by the other USING instruction. If the domain of the USING instruction that
specifies the higher-number register is subsequently terminated, the domain of the
other USING instruction is resumed.
Two USING ranges overlap when the base address of one USING instruction lies
within the range of another USING instruction. You can use the WARN suboption
of the USING assembler option to find out if you have any overlapping USING
ranges. When an overlap occurs the assembler issues a diagnostic message.
However, the assembler does allow an overlap of one byte in USING ranges so
that you don't receive a diagnostic message if you code the following statements:
PSTART

222

CSECT
LR
LA
USING
USING

HLASM V1R5 Language Reference

R12,R15
R11,495(,R12)
PSTART,R12
PSTART+495,R11

USING Instruction

In the above example, the second USING instruction begins the base address of
the second base register (R11) in the 4096th byte of the first base register (R12)
USING range. If you don't want the USING ranges to overlap, you can code the
following statements:
PSTART

CSECT
LR
LA
LA
USING
USING

R12,R15
R11,495(,R12)
R11,1(,R11)
PSTART,R12
PSTART+496,R11

|
|
|
|
|
|

When two ranges overlap, the assembler computes displacements from the base
address that gives the smallest non-negative displacement; or if no non-negative
displacement can be found, for long-displacement instructions, the base register
giving the smallest negative displacement; it uses the corresponding base register
when it assembles the addresses within the range overlap. This applies only to
implicit addresses that appear after the second USING instruction.

LOCTR does not affect the USING domain.

Domain of an Ordinary USING Instruction

The domain of an ordinary USING instruction (called the ordinary USING domain,
or simply the USING domain) begins where the USING instruction appears in a
source module. It continues until the end of a source module, except when:
A subsequent DROP instruction specifies the same base register or registers
assigned by a preceding USING instruction.
A subsequent USING instruction specifies the same register or registers
assigned by a preceding USING instruction.
The assembler converts implicit address references into their explicit form when the
following conditions are met:
The address reference appears in the domain of a USING instruction.
The addresses referred to lie within the range of some USING instruction.
The assembler does not convert implicit address references that are outside the
USING domain. The USING domain depends on the position of the USING
instruction in the source module after conditional assembly, if any, has been done.

Labeled USING Instruction

The labeled USING instruction specifies a base address, one or more base
registers, and a USING label which can be used as a symbol qualifier.
Labeled USING

,base_register
labelUSINGbase
(base)
,end

label
is one of the following:
An ordinary symbol
Chapter 5. Assembler Instruction Statements

223

USING Instruction

A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
base
specifies a base address, which can be a relocatable or an absolute
expression. The value of the expression must lie between 0 and 2311.
end
specifies the end address, which can be a relocatable or an absolute
expression. The value of the expression must lie between 0 and 2311. The
end address may exceed the (base address + default range) without error. The
end address must be greater than the base and must have the same
relocatability attributes.
base_register
is an absolute expression whose value represents general registers 0 through
15.
The default range is 4096 per base register.
The essential difference between a labeled USING instruction and an ordinary
USING instruction is the label placed on the USING statement. To indicate to the
assembler that the USING established with the label is to provide resolution of base
and displacement for a symbol, the label must be used to qualify the symbol.
Qualifying a symbol consists of preceding the symbol with the label on the USING
followed by a period. The only symbols resolved by the labeled USING are those
symbols qualified with the label. This label cannot be used for any other purpose in
the program, except possibly as a label on other USING instructions.
The following examples show how labeled USINGs are used:
PRIOR
NEXT

USING
USING
MVC

IHADCB,R1
IHADCB,R2
PRIOR.DCBLRECL,NEXT.DCBLRECL

The same code without labeled USINGs could be written like this:
USING
MVC

IHADCB,R1
DCBLRECL,DCBLRECL-IHADCB(R2)

In the following example, a new element, NEW, is inserted into a doubly-linked list
between two existing elements LEFT and RIGHT, where the links are stored as
pointers LPTR and RPTR:

224

HLASM V1R5 Language Reference

USING Instruction

LEFT
RIGHT
NEW

ELEMENT
LPTR
RPTR

USING
USING
USING
.
.
MVC
MVC
ST
ST
.
.
DSECT
DS
DS
.
.

ELEMENT,R3
ELEMENT,R6
ELEMENT,R1

NEW.RPTR,LEFT.RPTR
NEW.LPTR,RIGHT.LPTR
R1,LEFT.RPTR
R1,RIGHT.LPTR

Move previous Right pointer

Move previous Left pointer
Chain new element from Left
Chain new element from Right

A
A

Link to left element

Link to right element

Range of a Labeled USING Instruction

The range of a labeled USING instruction (called the labeled USING range) is the
4096 bytes beginning at the base address specified in the labeled USING
instruction, or the range as specified by the range end, whichever is the lesser.
Addresses that lie within the labeled USING range can be converted from their
implicit form (qualified symbols) to their explicit form; those outside the USING
range cannot be converted.

Like the ordinary USING range, the labeled USING range is the range of addresses
in a control section that is associated with the base register specified in the labeled
USING instruction. If the labeled USING instruction assigns more than one base
register, the composite labeled USING range is the product of the number of
registers specified in the labeled USING instruction and 4096 bytes. The
composite labeled USING range begins at the base address specified in the
labeled USING instruction. Unlike the ordinary USING range, however, you cannot
specify separate labeled USING instructions to establish the same labeled USING
range. For example,

specifies a range of 8192 bytes beginning at BASE, but

|
|

IN
IN

specifies a single labeled USING range of 4096 bytes beginning at BASE+4096.

USING BASE,1,11

USING BASE,1
USING BASE+496,11

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, High Level Assembler does not treat
the USING ranges as coinciding. When you specify an unqualified symbol in an
assembler instruction, the base register specified in the ordinary USING is used by
the assembler to resolve the address into base-displacement form. An example of
coexistent ordinary USINGs and labeled USINGs is given below:
SAMPLE

USING
USING
MVC

IHADCB,R1
IHADCB,R2
DCBLRECL,SAMPLE.DCBLRECL

Chapter 5. Assembler Instruction Statements

225

USING Instruction

In this MVC instruction, the (unqualified) first operand is resolved with the ordinary
USING, and the (qualified) second operand is resolved with the labeled USING.

Domain of a Labeled USING Instruction

The domain of a labeled USING instruction (called the labeled USING domain)
begins where the USING instruction appears in a source module. It continues to
the end of the source module, except when:
A subsequent DROP instruction specifies the label used in the preceding
labeled USING instruction.
A subsequent USING instruction specifies the same label used in the preceding
labeled USING instruction. The second specification of the label causes the
assembler to end the domain of the prior USING with the same label.
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 eligible to be used as symbol
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 assembler converts implicit address references into their explicit form using the
base register or registers specified in a labeled USING instruction when the
following conditions are met:
The address reference appears in the domain of the labeled USING instruction.
The address reference takes the form of a qualified symbol and the qualifier is
the label of the labeled USING instruction.
|

The address lies within the range of the labeled USING instruction.

Dependent USING Instruction

The dependent USING instruction format specifies a base address and a
relocatable expression instead of one or more base registers. If a USING label is
also specified, this format USING instruction is called a labeled dependent USING
instruction.
Dependent USING
USINGbase,address
label
(base)
sequence_symbol
,end

label
is one of the following:
An ordinary symbol
A variable symbol that has been assigned a character string with a value
that is valid for an ordinary symbol
sequence_symbol
is a sequence symbol.

226

HLASM V1R5 Language Reference

USING Instruction

base
specifies a base address, which must be a relocatable expression. The value
of the expression must lie between 0 and 2311.

|
|
|

address
is a simply relocatable expression that represents an implicit address within the
range of an active USING instruction. The range of an active USING is
considered to be that which is valid for generating 12-bit or 20-bit
displacements.
end
specifies the end address, which can be a relocatable or an absolute
expression. The value of the expression must lie between 0 and 2311. The
end address may exceed the (base address + default range) without error. The
end address must be greater than the base and must have the same
relocatability attributes.
The implicit address denoted by address specifies the address where base is to be
based, and is known as the supporting base address. As address is a relocatable
expression, it distinguishes a dependent USING from an ordinary USING. The
assembler converts the implicit address denoted by address into its explicit
base-displacement form. It then assigns the base register from this explicit address
as the base register for base. The assembler assumes that the base register
contains the base address base minus the displacement determined in the explicit
address. The assembler also assumes that address is appropriately aligned for the
code based on base. Warnings are not issued for potential alignment problems in
the dependent USING address.
A dependent USING depends on the presence of one or more corresponding
labeled or ordinary USINGs being in effect to resolve the symbolic expressions in
the range of the dependent USING.
The following example shows the use of an unlabeled dependent USING:
EXAMPLE

DCBUT2

CSECT
USING
.
.
USING
LH
.
.
DCB

EXAMPLE,R1,R11

Ordinary USING

IHADCB,DCBUT2
R,DCBBLKSI

Unlabeled dependent USING

Uses R1 or R11 for BASE

DDNAME=SYSUT2,...

The following example shows the use of two labeled dependent USINGs:
EXAMPLE

DCB1
DCB2

DCBUT1
DCBUT2

CSECT
USING
.
.
USING
USING
MVC
.
.
DCB
DCB

EXAMPLE,R1,R11

Ordinary USING

IHADCB,DCBUT1
IHADCB,DCBUT2
DCB2.DCBBLKSI,DCB1.DCBBLKSI

Labeled dependent USING

Labeled dependent USING
Uses R1 or R11 for BASE

DDNAME=SYSUT1,...
DDNAME=SYSUT2,...

Chapter 5. Assembler Instruction Statements

227

USING Instruction

Range of a Dependent USING Instruction

The range of a dependent USING instruction (called the dependent USING range)
is either the range as specified by the range end, or the range of the corresponding
USING minus the offset of address within that range, whichever is the lesser. If the
corresponding labeled or ordinary USING assigns more than one base register, the
maximum dependent USING range is the composite USING range of the labeled or
ordinary 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:
The assembler computes displacements from the ordinary USING base
address that gives the smallest displacement, and uses the corresponding base
register.
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.

Domain of a Dependent USING Instruction

The domain of a dependent USING instruction (called the dependent USING
domain) begins where the dependent USING appears in the source module and
continues until the end of the source module, except when:
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.
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.
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.
You end the domain of a labeled dependent USING by specifying the label of
the labeled dependent USING in the operand of a subsequent labeled USING
instruction.
When a labeled dependent USING domain is dropped, none of any subordinate
USING domains are dropped. In the following example the labeled dependent
USING BLBL1 is not dropped, even though it appears to be dependent on the
USING ALBL2 that is being dropped:

228

HLASM V1R5 Language Reference

WXTRN Instruction

ALBL1

ALBL2
BLBL1

DSECTA
A
DSECTB
B

USING
USING
.
.
USING
.
USING
.
DROP
.
DSECT
DS
DSECT
DS

DSECTA,14
DSECTB,ALBL1.A

DSECTA,ALBL1.A
DSECTA,ALBL2.A
ALBL2

A
A

A dependent USING is not dependent on another dependent USING. It is

dependent on the ordinary or labeled USING that is finally used to resolve the
address. For example, the USING at BLBL1 is dependent on the ALBL1 USING.
Remember that all dependent USINGs must eventually be based on an ordinary or
labeled USING that provides the base register used for base-displacement
resolutions.

WXTRN Instruction
The WXTRN statement identifies weak external symbols referred to in a source
module but defined in another source module. The WXTRN instruction differs from
the EXTRN instruction (see EXTRN Instruction on page 189) as follows:
The EXTRN instruction causes the linker to automatically search libraries (if
automatic library call is in effect) to find the module that contains the external
symbols that you identify in its operand field. If the module is found, linkage
addresses are resolved; the module is then linked to your module, which
contains the EXTRN instruction.
The WXTRN instruction suppresses automatic search of libraries. The linker
only resolves the linkage addresses if the external symbols that you identify in
the WXTRN operand field are defined:
In a module that is linked and loaded along with the object module
assembled from your source module, or
In a module brought in from a library because of the presence of an
EXTRN instruction in another module linked and loaded with yours.

,
external_symbol
WXTRN
sequence_symbol

sequence_symbol
is a sequence symbol.

Chapter 5. Assembler Instruction Statements

229

XATTR Instruction

external_symbol
is a relocatable symbol that is not:
Used as the name entry of a source statement in the source module in
which it is defined
The external symbols identified by a WXTRN instruction have the same properties
as the external symbols identified by the EXTRN instruction. However, the type
code assigned to these external symbols differs.
V-Type Address Constant: If a symbol, specified in a V-type address constant, is
also identified by a WXTRN instruction, it is assigned the same ESD type code as
the symbol in the WXTRN instruction, and is treated by the linkage editor as a
weak external symbol.
If an external symbol is identified by both an EXTRN and WXTRN instruction in the
same source module, the first declaration takes precedence, and subsequent
declarations are flagged with diagnostic messages.

XATTR Instruction (MVS and CMS)

The XATTR instruction enables attributes to be assigned to an external symbol.
This instruction is only valid when you specify the GOFF assembler option.

,
attribute
symbolXATTR

symbol
is a symbol which has been declared implicitly or explicitly as an external
symbol. Further, if the PSECT attribute is specified, must be a RSECT,
CSECT or START name or an ENTRY name (where the entry is in one of the
preceding types of section)
attribute
is one or more attributes from the group of attributes described below. The
assembler sets the appropriate attribute flags in the GOFF External Symbol
Directory record.
Notes:
1. If more than one value is specified for a given attribute, no diagnostic is issued
and only the last value is used.
2. All attributes of an external symbol must be specified in a single XATTR
statement (which may be continued).
ATTRIBUTES
ATTRIBUTES(label)

ATTRIBUTES(label), abbreviation ATTR(label)

is a symbol (internal or external) known in the declaring program. It names the
location of the extended attribute information to be associated with symbol.

230

HLASM V1R5 Language Reference

XATTR Instruction

Instructs the assembler to place the ESDID and offset of the label in the GOFF
External Symbol Dictionary record.
LINKAGE
LINKAGE(OS)
XPLINK

LINKAGE(OS), abbreviation LINK(OS)

Instructs the assembler to set the Linkage Type attribute to standard OS
linkage.
LINKAGE(XPLINK), abbreviation LINK(XPLINK)
Instructs the assembler to set the Linkage Type attribute to indicate Extra
Performance Linkage.
PSECT
PSECT(name)

PSECT (name)
Identifies the private read-write section or PSECT associated with name by its
being an internal or external symbol belonging to an element in the class to
which the PSECT belongs. The name is one of:
an ENTRY name, where the entry is in the same section (CSECT or
RSECT) as name, but in a different class. For reentrant code, the PSECT
is normally a non-shared class, so a separate CATTR statement is needed
to declare that class and its attributes.
an internal label within the PSECT.
REFERENCE
,
DIRECT
(1)
REFERENCE(
)
INDIRECT

(1)

DATA
CODE
Note:
Select no more than one option from each group.

REFERENCE(DIRECT), abbreviation REF(DIRECT)

Instructs the assembler to reset (clear) the Indirect Reference attribute.
REFERENCE(INDIRECT), abbreviation REF(INDIRECT)
Instructs the assembler to assign the Indirect Reference attribute.
REFERENCE(CODE), abbreviation REF(CODE)
Instructs the assembler to set the Executable attribute.
REFERENCE(DATA), abbreviation REF(DATA)
Instructs the assembler to set the Not Executable attribute.

Chapter 5. Assembler Instruction Statements

231

XATTR Instruction

SCOPE
SCOPE(SECTION)
MODULE
LIBRARY
IMPORT
EXPORT

SCOPE(SECTION), abbreviation SCOPE(S)

Instructs the assembler to set the binding scope to Section.
SCOPE(MODULE), abbreviation SCOPE(M)
Instructs the assembler to set the binding scope to Module.
SCOPE(LIBRARY), abbreviation SCOPE(L)
Instructs the assembler to set the binding scope to Library.
SCOPE(IMPORT), abbreviation SCOPE(X)
Instructs the assembler to set the binding scope to Export-Import (see note
following this list).

|
|

SCOPE(EXPORT), abbreviation SCOPE(X)

Instructs the assembler to set the binding scope to Export-Import.
|
|
|
|

This statement indicates only that the name field symbol has the specified scope. A
symbol having SCOPE(X) will have IMPORT status only if declared in an EXTRN
statement, and will have EXPORT status only if declared explicitly in an ENTRY
statement, or declared implicitly as an entry on a CSECT or RSECT statement.

|
|
|

The SCOPE(IMPORT) or SCOPE(EXPORT) attribute is required for using Dynamic

Link Libraries under the Language Environment. For details, refer to z/OS
V1R6.0 Language Environment Programming Guide (SA22-7561).

|
|
|
|
|
|

Association of Code and Data Areas (MVS and CMS)

To provide support for application program reentrancy and dynamic binding, the
assembler provides a way to associate read-only code and read-write data areas.
This is done by defining and accessing associated data areas called PSECTs. A
PSECT (Private or Prototype Control Section) when instantiated becomes the
non-shared working storage for an invocation of a shared reentrant program.

|
|
|

In the Program Object model, a PSECT is an element within the same section as
the element containing the shared code to which it belongs. The two classes
defining these elements will have attributes appropriate to their respective uses.

|
|

Typically, V-type and R-type address constants are used to provide code and
data-area addressability for a reentrant program using PSECTs.

|
|
|
|
|
|

Figure 61 on page 233 shows an example of two sections A and B, each with a
PSECT. When the program object AB containing A and B is instantiated, a single
copy of the reentrant CODE class is loaded into read-only storage, and a copy of
the PSECT class belonging to AB is loaded into read-write storage. The invoker of
A provides the address of A's PSECT so that A can address its own read-write
data. A later instantiation of AB would load only a new copy of the PSECT class.

232

HLASM V1R5 Language Reference

XATTR Instruction

|
|
|
|
|
|
|
|
|
|
|
|
|
|

CODE Class

Section A

DC V(B)

Section B

PSECT Class

(A's PSECT)

DC R(B)

(B's PSECT)

Program Object AB

Figure 61. Program Object with PSECTs, Example 1

|
|
|
|

When a program in the CODE class of section A calls a program in the CODE
class of section B, a linkage convention might require loading the entry address of
B into general register 15 and the address of B's PSECT into general register 0.
For example:

|
|
|
|
|
|

L
L
BASR

15,=V(B)
,=R(B)
14,15

B's entry point address

B's PSECT address (from A's PSECT)
Linkage to B

Further information about linkage conventions for referencing Dynamic Link

Libraries (DLLs) under the Language Environment can be found in z/OS V1R6.0
Language Environment Programming Guide (SA22-7561).

Chapter 5. Assembler Instruction Statements

233

XATTR Instruction

234

HLASM V1R5 Language Reference

Part 3. Macro Language

Chapter 6. Introduction to Macro Language
Using Macros . . . . . . . . . . . . . . . . . . .
Macro Definition . . . . . . . . . . . . . . . . . .
Model Statements . . . . . . . . . . . . . . .
Processing Statements . . . . . . . . . . . .
Comment Statements . . . . . . . . . . . . .
Macro Instruction . . . . . . . . . . . . . . . . .
Source and Library Macro Definitions . . . . .
Macro Library . . . . . . . . . . . . . . . . . .
System Macro Instructions . . . . . . . . . .
Conditional Assembly Language . . . . . . . .

Chapter 7. How to Specify Macro Definitions . . .

Where to Define a Macro in a Source Module . . . .
Format of a Macro Definition . . . . . . . . . . . . . . .
Macro Definition Header and Trailer . . . . . . . . . .
MACRO Statement . . . . . . . . . . . . . . . . . . .
MEND Statement . . . . . . . . . . . . . . . . . . . .
Macro Instruction Prototype . . . . . . . . . . . . . . .
Body of a Macro Definition . . . . . . . . . . . . . . . .
Model Statements . . . . . . . . . . . . . . . . . . . . .
Variable Symbols as Points of Substitution . . . . .
Listing of Generated Fields . . . . . . . . . . . . . .
Rules for Concatenation . . . . . . . . . . . . . . . .
Rules for Model Statement Fields . . . . . . . . . .
Symbolic Parameters . . . . . . . . . . . . . . . . . . .
Positional Parameters . . . . . . . . . . . . . . . . .
Keyword Parameters . . . . . . . . . . . . . . . . .
Combining Positional and Keyword Parameters . .
Subscripted Symbolic Parameters . . . . . . . . . .
Processing Statements . . . . . . . . . . . . . . . . . .
Conditional Assembly Instructions . . . . . . . . . .
Inner Macro Instructions . . . . . . . . . . . . . . . .
Other Conditional Assembly Instructions . . . . . .
AEJECT Instruction . . . . . . . . . . . . . . . . . .
AINSERT Instruction . . . . . . . . . . . . . . . . . .
AREAD Instruction . . . . . . . . . . . . . . . . . . .
ASPACE Instruction . . . . . . . . . . . . . . . . . .
COPY Instruction . . . . . . . . . . . . . . . . . . . .
MEXIT Instruction . . . . . . . . . . . . . . . . . . .
Comment Statements . . . . . . . . . . . . . . . . . . .
Ordinary Comment Statements . . . . . . . . . . . .
Internal Macro Comment Statements . . . . . . . .
System Variable Symbols . . . . . . . . . . . . . . . .
Scope and Variability of System Variable Symbols
&SYSADATA_DSN System Variable Symbol . . .
&SYSADATA_MEMBER System Variable Symbol
&SYSADATA_VOLUME System Variable Symbol .
&SYSASM System Variable Symbol . . . . . . . . .
&SYSCLOCK System Variable Symbol . . . . . . .
Copyright IBM Corp. 1982, 2004

238
238
238
239
240
240
241
241
242
242
242
243
243
244
244
244
245
245
247
247
248
248
249
251
253
254
255
255
255
256
256
256
256
257
257
257
259
260
260
261
261
261
262
262
263
264
265
265
266

235

Part 3. Macro Language

&SYSDATC System Variable Symbol . . . . . . . .

&SYSDATE System Variable Symbol . . . . . . . .
&SYSECT System Variable Symbol . . . . . . . . .
&SYSIN_DSN System Variable Symbol . . . . . . .
&SYSIN_MEMBER System Variable Symbol . . . .
&SYSIN_VOLUME System Variable Symbol . . . .
&SYSJOB System Variable Symbol . . . . . . . . .
&SYSLIB_DSN System Variable Symbol . . . . . .
&SYSLIB_MEMBER System Variable Symbol . . .
&SYSLIB_VOLUME System Variable Symbol . . .
&SYSLIN_DSN System Variable Symbol . . . . . .
&SYSLIN_MEMBER System Variable Symbol . . .
&SYSLIN_VOLUME System Variable Symbol . . .
&SYSLIST System Variable Symbol . . . . . . . . .
&SYSLOC System Variable Symbol . . . . . . . . .
&SYSMAC System Variable Symbol . . . . . . . .
&SYSM_HSEV System Variable Symbol . . . . . .
&SYSM_SEV System Variable Symbol . . . . . . .
&SYSNDX System Variable Symbol . . . . . . . . .
&SYSNEST System Variable Symbol . . . . . . . .
&SYSOPT_DBCS System Variable Symbol . . . .
&SYSOPT_OPTABLE System Variable Symbol . .
&SYSOPT_RENT System Variable Symbol . . . .
&SYSOPT_XOBJECT System Variable Symbol . .
&SYSPARM System Variable Symbol . . . . . . . .
&SYSPRINT_DSN System Variable Symbol . . . .
&SYSPRINT_MEMBER System Variable Symbol .
&SYSPRINT_VOLUME System Variable Symbol .
&SYSPUNCH_DSN System Variable Symbol . . .
&SYSPUNCH_MEMBER System Variable Symbol
&SYSPUNCH_VOLUME System Variable Symbol
&SYSSEQF System Variable Symbol . . . . . . . .
&SYSSTEP System Variable Symbol . . . . . . . .
&SYSSTMT System Variable Symbol . . . . . . . .
&SYSSTYP System Variable Symbol . . . . . . . .
&SYSTEM_ID System Variable Symbol . . . . . . .
&SYSTERM_DSN System Variable Symbol . . . .
&SYSTERM_MEMBER System Variable Symbol .
&SYSTERM_VOLUME System Variable Symbol .
&SYSTIME System Variable Symbol . . . . . . . .
&SYSVER System Variable Symbol . . . . . . . . .
Chapter 8. How to Write Macro Instructions
Macro Instruction Format . . . . . . . . . . . . .
Alternative Formats for a Macro Instruction .
Name Entry . . . . . . . . . . . . . . . . . . .
Operation Entry . . . . . . . . . . . . . . . . .
Operand Entry . . . . . . . . . . . . . . . . .
Sublists in Operands . . . . . . . . . . . . . . .
Values in Operands . . . . . . . . . . . . . . . .
Omitted Operands . . . . . . . . . . . . . . .
Unquoted Operands . . . . . . . . . . . . . .
Special Characters . . . . . . . . . . . . . . .
Nesting Macro Instruction Definitions . . . . . .

236

HLASM V1R5 Language Reference

266
267
267
269
270
271
272
272
273
273
274
275
275
276
278
279
279
280
281
283
284
285
285
285
286
286
288
288
289
290
290
291
292
292
292
293
294
295
295
296
296
297
297
298
299
299
300
304
307
307
308
308
311

Part 3. Macro Language

Inner and Outer Macro Instructions . . . . . . .

Levels of Macro Call Nesting . . . . . . . . . .
General Rules and Restrictions . . . . . . .
Passing Values through Nesting Levels . . .
System Variable Symbols in Nested Macros

. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .

Chapter 9. How to Write Conditional Assembly Instructions

312
312
313
314
316

. . . . . . . . .

318
319
319
319
319
320
322
323
324
326
328
332
333
334
335
336
337
337
339
340
342
343
343
344
345
347
347
362
369
387
388
389
390
390
392
394
395

. . . . . . . . . . . . . . . . . . . . . . . . . .

397

Part 3. Macro Language

237

Introduction to Macro Language

Chapter 6. Introduction to Macro Language

This chapter introduces the basic macro concept: what you can use the macro
facility for, how you can prepare your own macro definitions, and how you call
these macro definitions for processing by the assembler.
Macro language is an extension of assembler language. It provides a convenient
way to generate a sequence of assembler language statements many times in one
or more programs. A macro definition is written only once; thereafter, a single
statement, a macro instruction statement, is written each time you want to generate
the sequence of statements. This simplifies the coding of programs, reduces the
chance of programming errors, and ensures that standard sequences of statements
are used to accomplish the functions you want.
In addition, conditional assembly lets you code statements that may or may not be
assembled, depending upon conditions evaluated at conditional assembly time.
These conditions are usually tests of values which may be defined, set, changed,
and tested during assembly. Conditional assembly statements can be used within
macro definitions or in open code.

Using Macros
The main use of macros is to insert assembler language statements into a source
program.
You call a named sequence of statements (the macro definition) by using a macro
instruction, or macro call. The assembler replaces the macro call by the
statements from the macro definition and inserts them into the source module at
the point of call. The process of inserting the text of the macro definition is called
macro generation or macro expansion. Macro generation occurs during conditional
assembly.
The expanded stream of code then becomes the input for processing at assembly
time; that is, the time at which the assembler translates the machine instructions
into object code.

Macro Definition
A macro definition is a named sequence of statements you can call with a macro
instruction. When it is called, the assembler processes and usually generates
assembler language statements from the definition into the source module. The
statements generated can be:
Copied directly from the definition
Modified by parameter values and other values in variable symbols before
generation
Manipulated by internal macro processing to change the sequence in which
they are generated
You can define your own macro definitions in which any combination of these three
processes can occur. Some macro definitions, like some of those used for system

238

Copyright IBM Corp. 1982, 2004

Introduction to Macro Language

generation, do not generate assembler language statements, but do only internal

processing.
A macro definition provides the assembler with:
The name of the macro
The parameters used in the macro
The sequence of statements the assembler generates when the macro
instruction appears in the source program.
Every macro definition consists of a macro definition header statement (MACRO), a
macro instruction prototype statement, one or more assembler language
statements, and a macro definition trailer statement (MEND), as shown in
Figure 62.
MACRO

Prototype
&LABEL
MACID
&PARAM1,&PARAM2

2
3

5
Body of macro

MEND

Macro instruction

MACID

OPERAND1,OPERAND2

Figure 62. Parts of a Macro Definition

The macro definition header and trailer statements (MACRO and MEND)
indicate to the assembler the beginning and end of a macro definition (see 1
in Figure 62).
The macro instruction prototype statement names the macro (see 2 in
Figure 62), and declares its parameters (see 3 in Figure 62). In the operand
field of the macro instruction, you can assign values (see 4 in Figure 62) to
the parameters declared for the called macro definition.
The body of a macro definition (see 5 in Figure 62) contains the statements
that are generated when you call the macro. These statements are called
model statements; they are usually interspersed with conditional assembly
statements or other processing statements.

Model Statements
You can write machine instruction statements and assembler instruction statements
as model statements. During macro generation, the assembler copies them exactly
as they are written. You can also use variable symbols as points of substitution in
a model statement. The assembler enters values in place of these points of
substitution each time the macro is called.

Chapter 6. Introduction to Macro Language

239

Introduction to Macro Language

The three types of variable symbols in the assembler language are:

Symbolic parameters, declared in the prototype statement
System variable symbols
SET symbols, which are part of the conditional assembly language
The assembler processes the generated statements, with or without value
substitution, at assembly time.

Processing Statements
Processing statements are processed during conditional assembly, when macros
are expanded, but they are not themselves generated for further processing at
assembly time. The processing statements are:

AEJECT instructions
AREAD instructions
ASPACE instructions
Conditional assembly instructions
Inner macro calls
MEXIT instructions
MNOTE instructions

The AEJECT and ASPACE instructions let you control the listing of your macro
definition. Use the AEJECT instruction to stop printing the listing on the current
page and continue printing on the next. Use the ASPACE instruction to insert
blank lines in the listing. The AEJECT instruction is described on page 257. The
ASPACE instruction is described on page 259.
The AREAD instruction assigns a character string value, of a statement that is
placed immediately after a macro instruction, to a SETC symbol. The AREAD
instruction is described on page 257.
Conditional assembly instructions, inner macro calls, and macro processing
instructions are described in detail in the following chapters.
The MNOTE instruction generates an error message with an error condition code
attached, or generates comments in which you can display the results of a
conditional assembly computation. The MNOTE instruction is described on page
196.
The MEND statement delimits the contents of a macro definition, and also provides
an exit from the definition. The MEND instruction is described on page 245.
The MEXIT instruction tells the assembler to stop processing a macro definition,
and provides an exit from the macro definition at a point before the MEND
statement. The MEXIT instruction is described on page 260.

Comment Statements
One type of comment statement describes conditional assembly operations and is
not generated. The other type describes assembly-time operations and is,
therefore, generated. For a description of the two types of comment statements,
see Comment Statements on page 261.

240

HLASM V1R5 Language Reference

Introduction to Macro Language

Macro Instruction
A macro instruction is a source program statement that you code to tell the
assembler to process a particular macro definition. The assembler generates a
sequence of assembler language statements for each occurrence of the same
macro instruction. The generated statements are then processed as any other
assembler language statement.
The macro instruction provides the assembler with:
The name of the macro definition to be processed.
The information or values to be passed to the macro definition. The assembler
uses the information either in processing the macro definition or for substituting
values into a model statement in the definition.
The output from a macro definition, called by a macro instruction, can be:
A sequence of statements generated from the model statements of the macro
for further processing at assembly time.
Values assigned to global SET symbols. These values can be used in other
macro definitions and in open code.
You can call a macro definition by specifying a macro instruction anywhere in a
source module. You can also call a macro definition from within another macro
definition. This type of call is an inner macro call; it is said to be nested in the
macro definition.

Source and Library Macro Definitions

You can include a macro definition in a source module. This type of definition is
called a source macro definition, or, sometimes, an in-line macro definition.
You can also insert a macro definition into a system or user library by using the
applicable utility program. This type of definition is called a library macro definition.
The IBM-supplied macro definitions are examples of library macro definitions.
You can call a source macro definition only from the source module in which it is
included. You can call a library macro definition from any source module if the
library containing the macro definition is available to the assembler.
Syntax errors in processing statements are handled differently for source macro
definitions and library macro definitions. In source macro definitions, error
messages are listed following the statements in error. In library macros, however,
error messages cannot be associated with the statement in error, because the
statements in library macro definitions are not included in the assembly listing.
Therefore, the error messages are listed directly following the first call of that
macro.
Because of the difficulty of finding syntax errors in library macros, a macro
definition should be run and debugged as a source macro before it is placed in a
macro library. Alternatively, you can use the LIBMAC assembler option to have the
assembler automatically include the source statements of the library macro in your
source module. For more information about the LIBMAC option, see the HLASM
Programmer's Guide.
Chapter 6. Introduction to Macro Language

241

Introduction to Macro Language

Macro Library
The same macro definition may be made available to more than one source
program by placing the macro definition in the macro library. The macro library is a
collection of macro definitions that can be used by all the assembler language
programs in an installation. When a macro definition has been placed in the macro
library, it can be called by coding its corresponding macro instruction in a source
program. Macro definitions must be in a macro library with a member name that is
the same as the macro name. The procedure for placing macro definitions in the
macro library is described in the applicable utilities manual.
The DOS/VSE assembler requires library macro definitions to be placed in the
macro library in a special edited format. High Level Assembler does not require
this. Library macro definitions must be placed in the macro library in source
statement format. If you wish to use edited macros in VSE you can provide a
LIBRARY exit to read the edited macros and convert them into source statement
format. A library exit is supplied with VSE and is described in VSE/ESA Guide to
System Functions.

System Macro Instructions

The macro instructions that correspond to macro definitions prepared by IBM are
called system macro instructions. System macro instructions are described in the
applicable operating system manuals that describe macro instructions for supervisor
services and data management.

Conditional Assembly Language

The conditional assembly language is a programming language with most of the
features that characterize a programming language. For example, it provides:

Variables
Data attributes
Expression computation
Assignment instructions
Labels for branching
Branching instructions
Substring operators that select characters from a string

Use the conditional assembly language in a macro definition to receive input from a
calling macro instruction. You can produce output from the conditional assembly
language by using the MNOTE instruction.
Use the functions of the conditional assembly language to select statements for
generation, to determine their order of generation, and to do computations that
affect the content of the generated statements.
The conditional assembly language is described in Chapter 9, How to Write
Conditional Assembly Instructions on page 318.

242

HLASM V1R5 Language Reference

How to Specify Macro Definitions

Chapter 7. How to Specify Macro Definitions

A macro definition is a set of statements that defines the name, the format, and the
conditions for generating a sequence of assembler language statements. The
macro definition can then be called by a macro instruction to process the
statements. See page 241 for a description of the macro instruction. To define a
macro you must:

Give it a name
Declare any parameters to be used
Write the statements it contains
Establish its boundaries with a macro definition header statement (MACRO)
and a macro definition trailer statement (MEND)

Except for conditional assembly instructions, this chapter describes all the
statements that can be used to specify macro definitions. Conditional assembly
instructions are described in Chapter 9, How to Write Conditional Assembly
Instructions on page 318.

Where to Define a Macro in a Source Module

Macro definitions can appear anywhere in a source module. They remain in effect
for the rest of your source module, or until another macro definition defining a
macro with the same operation code is encountered, or until an OPSYN statement
deletes its definition. Thus, you can redefine a macro at any point in your program.
The new definition is used for all subsequent calls to the macro in the program.
This type of macro definition is called a source macro definition, or, sometimes, an
in-line macro definition. A macro definition can also reside in a system library; this
type of macro is called a library macro definition. Either type can be called from
the source module by the applicable macro instruction.
Macro definitions can also appear inside other macro definitions. There is no limit
to the levels of macro definitions permitted.
The assembler does not process inner macro definitions until it finds the definition
during the processing of a macro instruction calling the outer macro. The following
example shows an inner macro definition:
Example:

Copyright IBM Corp. 1982, 2004

MACRO
OUTER
AIF
MACRO
INNER
.
.
MEND
ANOP
.
MEND

&A,&C=
('&C' EQ '').A

Macro header for outer macro

Macro prototype
Macro header for inner macro
Macro prototype

Macro trailer for inner macro

Macro trailer for outer macro

243

MACRO and MEND Statements

The assembler does not process the macro definition for INNER until OUTER is called
with a value for &C other than a null string.
Open Code: Open code is that part of a source module that lies outside of any
source macro definition. At coding time, it is important to distinguish between
source statements that lie in open code, and those that lie inside macro definitions.

Format of a Macro Definition

The general format of a macro definition is shown in Figure 63. The four parts are
described in detail in the following sections.

MACRO
Header statement

ANYNAME
Prototype statement

Body of macro

MEND
Trailer statement

Figure 63. Format of a Macro Definition

Macro Definition Header and Trailer

You must establish the boundaries of a macro definition by coding:
A macro definition header statement as the first statement of the macro
definition (a MACRO statement)
A macro definition trailer statement as the last statement of the macro definition
(a MEND statement)
The instructions used to define the boundaries of a macro instruction are described
in the following sections.

MACRO Statement
Use the MACRO statement to indicate the beginning of a macro definition. It must
be the first non-comment statement in every macro definition. Library macro
definitions may have ordinary or internal macro comments before the MACRO
statement.

MACRO

The MACRO statement must not have a name entry or an operand entry.

244

HLASM V1R5 Language Reference

Prototype Statement

MEND Statement
Use the MEND statement to indicate the end of a macro definition. It also provides
an exit when it is processed during macro expansion. It can appear only once
within a macro definition and must be the last statement in every macro definition.

MEND
sequence_symbol

sequence_symbol
is a sequence symbol.
See MEXIT Instruction on page 260 for details on exiting from a macro before the
MEND statement.

Macro Instruction Prototype

The macro instruction prototype statement (hereafter called the prototype
statement) specifies the mnemonic operation code and the format of all macro
instructions that you use to call the macro definition.
The prototype statement must be the second non-comment statement in every
macro definition. Both ordinary comment statements and internal comment
statements are allowed between the macro definition header and the macro
prototype. Such comment statements are listed only with the macro definition.
operation_field
name_field
,
symbolic_parameter

name_field
is a variable symbol.
You can write a name field parameter, similar to the symbolic parameter, as the
name entry of a macro prototype statement. You can then assign a value to
this parameter from the name entry in the calling macro instruction.
If this parameter also appears in the body of a macro, it is given the value
assigned to the parameter in the name field of the corresponding macro
instruction.
operation_field
is an ordinary symbol.
The symbol in the operation field of the prototype statement establishes the
name by which a macro definition must be called. This name becomes the
operation code required in any macro instruction that calls the macro.
Any operation code can be specified in the prototype operation field. If the
entry is the same as an assembler or a machine operation code, the new
definition overrides the previous use of the symbol. The same is true if the
specified operation code has been defined earlier in the program as a macro,
or is the operation code of a library macro.

Chapter 7. How to Specify Macro Definitions

245

Prototype Statement

Macros that are defined inline may use any ordinary symbol, up to 63
characters in length, for the operation field. However, operating system rules
may prevent some of these macros from being stored as member names.
The assembler requires that the library member name and macro name be the
same; otherwise error diagnostic message ASMA126S Library macro name
incorrect is issued.
symbolic_parameter
The symbolic parameters are used in the macro definition to represent the
operands of the corresponding macro instruction. A description of symbolic
parameters appears under Symbolic Parameters on page 253.
The operand field in a prototype statement lets you specify positional or
keyword parameters. These parameters represent the values you can pass
from the calling macro instruction to the statements within the body of a macro
definition.
The operand field of the macro prototype statement must contain 0 to 32000
symbolic parameters separated by commas. They can be positional
parameters or keyword parameters, or both.
If no parameters are specified in the operand field and if the absence of the
operand entry is indicated by a comma preceded and followed by one or more
spaces, remarks are allowed.
The following is an example of a prototype statement:
&NAME

MOVE

&TO,&FROM

Alternative Formats for the Prototype Statement

The prototype statement can be specified in one of the following three ways:
The normal way, with all the symbolic parameters preceding any remarks
An alternative way, allowing remarks for each parameter
A combination of the first two ways
The continuation rules for macro instructions are different from those for machine or
assembler instruction statements. This difference is important for those who write
macros that override a machine/assembler mnemonic.
The following examples show the normal statement format (&NAME1), the alternative
statement format (&NAME2), and a combination of both statement formats (&NAME3):
Name

246

Operation
Operand

Comment

Cont.

&NAME1 OP1

&OPERAND1,&OPERAND2,&OPERAND3 This is the normal

statement format

&NAME2 OP2

&OPERAND1,
&OPERAND2

This is the alternative statement format

&NAME3 OP3

&OPERAND1,
&OPERAND2,&OPERAND3,
&OPERAND4

This is a combination
of both

X
X

HLASM V1R5 Language Reference

Body of a Macro Definition

Notes:
1. Any number of continuation lines is allowed. However, each continuation line
must be indicated by a non-space character in the column after the end column
on the preceding line.
2. For each continuation line, the operand field entries (symbolic parameters) must
begin in the continue column; otherwise, the whole line and any lines that
follow are considered to contain remarks.
No error diagnostic message is issued to indicate that operands are
treated as remarks in this situation. However, the FLAG(CONT) assembler
option can be specified so that the assembler issues warning messages if
it suspects an error in a continuation line.
3. The standard value for the continue column is 16 and the standard value for
the end column is 71.
4. A comma is required after each parameter except the last. If you code excess
commas between parameters, they are considered null positional parameters.
No error diagnostic message is issued.
5. One or more spaces is required between the operand and the remarks.
6. If the DBCS assembler option is specified, the continuation features outlined in
Continuation of double-byte data on page 16 apply to continuation in the
macro language. Extended continuation may be useful if a macro keyword
parameter contains double-byte data.

Body of a Macro Definition

The body of a macro definition contains the sequence of statements that constitutes
the working part of a macro. You can specify:
Model statements to be generated
Processing statements that, for example, can alter the content and sequence of
the statements generated or issue error messages
Comment statements, some that are generated and others that are not
Conditional assembly instructions to compute results to be displayed in the
message created by the MNOTE instruction, without causing any assembler
language statements to be generated
The statements in the body of a macro definition must appear between the macro
prototype statement and the MEND statement of the definition. The body of a
macro definition can be empty, that is, contain no statements.
Nesting Macros: You can include macro definitions in the body of a macro
definition.

Model Statements
Model statements are statements from which assembler language statements are
generated during conditional assembly. They let you determine the form of the
statements to be generated. By specifying variable symbols as points of
substitution in a model statement, you can vary the contents of the statements

Chapter 7. How to Specify Macro Definitions

247

Model Statements

generated from that model statement. You can also substitute values into model
statements in open code.
A model statement consists of one or more fields, separated by one or more
spaces, in columns 1 to 71. The fields are called the name, operation, operand,
and remarks fields.
Each field or subfield can consist of:
An ordinary character string composed of alphanumeric and special characters
A variable symbol as a point of substitution, except in remarks fields and
comment statements
Any combination of ordinary character strings and variable symbols to form a
concatenated string
The statements generated from model statements during conditional assembly must
be valid machine or assembler instructions, but must not be conditional assembly
instructions. They must follow the coding rules described in Rules for Model
Statement Fields on page 251 or they are flagged as errors at assembly time.
Examples:
LABEL
LABEL2
&LABEL
FIELD&A

L
L
L
L

3,AREA
3,2(4,5)
3,&AREA
3,AREA&C

Variable Symbols as Points of Substitution

Values can be substituted for variable symbols that appear in the name, operation,
and operand fields of model statements; thus, variable symbols represent points of
substitution. The three main types of variable symbol are:
Symbolic parameters (positional or keyword)
System variable symbols (see System Variable Symbols on page 262)
SET symbols (global-scope or local-scope SETA, SETB, or SETC symbols)
Examples:
&PARAM(3)
&SYSLIST(1,3)
&SYSLIST(2)
&SETA(1)
&SETC(15)
Symbols That Can Be Subscripted: Symbolic parameters, SET symbols, and
the system variable symbols &SYSLIST and &SYSMAC, can all be subscripted. All
remaining system variable symbols contain only one value.

Listing of Generated Fields

The different fields in a macro-generated statement or a statement generated in
open code appear in the listing in the same column as they are coded in the model
statement, with the following exceptions:
If the substituted value in the name or operation field is too large for the space
available, the next field is moved to the right with one space separating the
fields.

248

HLASM V1R5 Language Reference

Model Statements

If the substituted value in the operand field causes the remarks field to be
displaced, the remarks field is written on the next line, starting in the column
where it is coded in the model statement.
If the substituted value in the operation field of a macro-generated statement
contains leading spaces, the spaces are ignored.
If the substituted value in the operation field of a model statement in open code
contains leading spaces, the spaces are used to move the field to the right.
If the substituted value in the operand field contains leading spaces, the spaces
are used to move the field to the right.
If the substituted value contains trailing spaces, the spaces are ignored.
Listing of Generated Fields Containing Double-Byte Data: If the DBCS
assembler option is specified, then the following differences apply:
Any continuation indicators present in the model statement are discarded.
Double-byte data that must be split at a continuation point is always readable
on a device capable of presenting DBCS charactersSI and SO are inserted
at the break point, and the break-point always occurs between double-byte
characters.
The continuation indicator is extended to the left, if necessary, to fill space that
cannot be filled with double-byte data because of alignment and delimiter
considerations. The maximum number of columns filled is 3.
If continuation is required and the character to the left of the continuation
indicator is X, then + is used as the continuation indicator so as to clearly
distinguish the position of the end column. This applies to any generated field,
regardless of its contents, to prevent ambiguity.
Redundant SI/SO pairs may be present in a field after substitution. If they
occur at a continuation point, the assembler does not distinguish them from SI
and SO inserted in the listing by the assembler to preserve readability. Refer
to the generated object code to resolve this ambiguity. For more information,
see Figure 64 on page 250.

Rules for Concatenation

If a symbolic parameter in a model statement is immediately preceded or followed
by other characters or another symbolic parameter, the characters that correspond
to the symbolic parameter are combined in the generated statement with the other
characters, or with the characters that correspond to the other symbolic parameter.
This process is called concatenation.
When variable symbols are concatenated to ordinary character strings, the following
rules apply to the use of the concatenation character (a period). The concatenation
character is mandatory when:
1

An alphanumeric character follows a variable symbol.

A left parenthesis that does not enclose a subscript follows a variable

symbol.

34 A period (.) is to be generated. Two periods must be specified in the

concatenated string following a variable symbol.
The concatenation character is not required when:
Chapter 7. How to Specify Macro Definitions

249

Model Statements

An ordinary character string precedes a variable symbol.

A special character, except a left parenthesis or a period, is to follow a

variable symbol.

A variable symbol follows another variable symbol.

A variable symbol is used with a subscript. The concatenation character

must not be used between a variable symbol and its subscript; otherwise,
the characters are considered a concatenated string and not a subscripted
variable symbol.

Figure 64, in which the numbers correspond to the numbers in the above list, gives
the rules for concatenating variable symbols to ordinary character strings.
Figure 64. Rules for Concatenation

Values to be
Substituted
Concatenated String
&FIELD.A
&FIELDA

Variable
Symbol

Value

&FIELD
&FIELDA

AREA
SUM

AREAA
SUM

&DISP.(&BASE)

2
6

&DISP
&BASE

1
1

1(1)

DC D'&INT..&FRACT'

3

&INT
&FRACT

99
88

DC D'99.88'

4
DC D'9988'

DC D'&INT&FRACT'

7

FIELD&A 5

FIELDA

&A+&B3-D

6

&A
&B

A
B

A+B3-D

&SYM(&SUBSCR)

8

&SUBSCR
&SYM(1)

1
ENTRY

ENTRY

Notes:
1. The concatenation character is not generated.

250

Generated Result

HLASM V1R5 Language Reference

Model Statements

Concatenation of Fields Containing Double-Byte Data: If the DBCS assembler

option is specified, then the following additional rules apply:
Because ampersand is not recognized in double-byte data, variable symbols
must not be present in double-byte data.
The concatenation character is mandatory when double-byte data is to follow a
variable symbol.
The assembler checks for redundant SI and SO at concatenation points. If the
byte to the left of the join is SI and the byte to the right of the join is SO, then
the SI/SO pair is considered redundant and is removed.
Note: The rules for redundant SI and SO are different for variable substition
and listing display, which are described at Listing of Generated Fields
Containing Double-Byte Data on page 249.
The following example shows these rules:
&SYMBOL
DBCS

SETC
DC

'<DcDd>'
C'<DaDb>&SYMBOL.<.&.S.Y.M.B.O.L>'

The SI/SO pairs between double-byte characters Db and Dc, and Dd and .&, are
removed. The variable symbol &SYMBOL is recognized between the double-byte
strings but not in the double-byte strings. The result after concatenation is:
DBCS

C'<DaDbDcDd.&.S.Y.M.B.O.L>'

Rules for Model Statement Fields

The fields that can be specified in model statements are the same fields that can
be specified in an ordinary assembler language statement. They are the name,
operation, operand, and remarks fields. You can also specify a
continuation-indicator field, an identification-sequence field, and, in source macro
definitions, a field before the begin column if the correct ICTL instruction has been
specified. Character strings in the last three fields (in the standard format only,
columns 72 through 80) are generated exactly as they appear in the model
statement, and no values are substituted for variable symbols.
Model statements must have an entry in the operation field, and, in most cases, an
entry in the operand field in order to generate valid assembler language
instructions.

Name Field
The entries allowed in the name field of a model statement, before generation, are:

Space
An ordinary symbol
A sequence symbol
A variable symbol
Any combination of variable symbols, or system variable symbols such as
&SYSNDX, and other character strings concatenated together

The generated result must be spaces (if valid) or a character string that represents
a valid assembler or machine instruction name field. Double-byte data is not valid
in an assembler or machine instruction name field and must not be generated.
Variable symbols must not be used to generate comment statement indicators ( or
.).
Chapter 7. How to Specify Macro Definitions

251

Model Statements

Notes:
1. You can not reference an ordinary symbol defined in the name field of a model
statement until the macro definition containing the model statement has been
called, and the model statement has been generated.
2. Restrictions on the name entry of assembler language instructions are further
specified where each individual assembler language instruction is described in
this manual.

Operation Field
The entries allowed in the operation field of a model statement, before generation,
are given in the following list:
An ordinary symbol that represents the operation code for:

Any machine instruction

A macro instruction
MNOTE instruction
A variable symbol
A combination of variable strings concatenated together
All assembler instructions, except ICTL and conditional assembly
instructions

The following rules apply to the operation field of a model statement:

Operation code ICTL is not allowed inside a macro definition.
The MACRO and MEND statements are not allowed in model statements; they
are used only for delimiting macro definitions.
If the REPRO operation code is specified in a model statement, no substitution
is done for the variable symbols in the statement line following the REPRO
statement.
Variable symbols can be used alone or as part of a concatenated string to
generate operation codes for:
Any machine instruction
Any assembler instruction, except COPY, ICTL, ISEQ, REPRO, and MEXIT
The generated operation code must not be an operation code for the following
(or their OPSYN equivalents):
A conditional assembly instruction
The following assembler instructions: COPY, ICTL, ISEQ, MACRO, MEND,
MEXIT, and REPRO
Double-byte data is not valid in the operation field.

Operand Field
The entries allowed in the operand field of a model statement, before generation,
are:
Spaces (if valid)
An ordinary symbol
A character string, combining alphanumeric and special characters (but not
variable symbols)

252

HLASM V1R5 Language Reference

Symbolic Parameters

A variable symbol
A combination of variable symbols and other character strings concatenated
together
If the DBCS assembler option is specified, character strings may contain
double-byte data, provided the character strings are enclosed by apostrophes.
The allowable results of generation are spaces (if valid) and a character string that
represents a valid assembler, machine instruction, or macro instruction operand
field.
Variable Symbols: Variable symbols must not be used in the operand field of a
ICTL, or ISEQ instruction. A variable symbol must not be used in the operand field
of a COPY instruction that is inside a macro definition.

Remarks Field
The remarks field of a model statement can contain any combination of characters.
No substitution is done for variable symbols appearing in the remarks field.
Using spaces: One or more spaces must be used in a model statement to
separate the name, operation, operand, and remarks fields from each other.
Spaces cannot be generated between fields in order to create a complete
assembler language statement. The exception to this rule is that a combined
operand-remarks field can be generated with one or more spaces to separate the
two fields. Note, however, that if the generated operand field is part of a macro
instruction, the entire string (including spaces) is passed as an operand.

Symbolic Parameters
Symbolic parameters let you receive values into the body of a macro definition from
the calling macro instruction. You declare these parameters in the macro prototype
statement. They can serve as points of substitution in the body of the macro
definition and are replaced by the values assigned to them by the calling macro
instruction.
By using symbolic parameters with meaningful names, you can indicate the
purpose for which the parameters (or substituted values) are used.
Symbolic parameters must be valid variable symbols. A symbolic parameter
consists of an ampersand followed by an alphabetic character and from 0 to 61
alphanumeric characters.
The following are valid symbolic parameters:
&READER
&A23456
&X4F2

&LOOP2
&N
&$4

The following are not valid symbolic parameters:

CARDAREA
&256B
&BCD%34
&IN AREA

first character is not an ampersand

first character after ampersand is not alphabetic
contains a special character other than initial ampersand
contains a special character [space] other than initial ampersand

Chapter 7. How to Specify Macro Definitions

253

Positional Parameters

Symbolic parameters have a local scope; that is, the name and value they are
assigned only applies to the macro definition in which they have been declared.
The value of the parameter remains constant throughout the processing of the
containing macro definition during each call of that definition.
Notes:
1. Symbolic parameters must not have multiple definitions or be identical to any
other variable symbols within the given local scope. This applies to the system
variable symbols described in System Variable Symbols on page 262, and to
local-scope and global-scope SET symbols described in SET Symbols on
page 319.
2. Symbolic parameters should not begin with &SYS because these characters are
used for system variable symbols provided with High Level Assembler.
The two kinds of symbolic parameters are:
Positional parameters
Keyword parameters
Each positional or keyword parameter used in the body of a macro definition must
be declared in the prototype statement.
The following is an example of a macro definition with symbolic parameters.
&NAME
&NAME

MACRO
MOVE
ST
L
ST
L
MEND

&TO,&FROM
2,SAVE
2,&FROM
2,&TO
2,SAVE

Header
Prototype
Model
Model
Model
Model
Trailer

In the following macro instruction that calls the above macro, the characters HERE,
FIELDA, and FIELDB of the MOVE macro instruction correspond to the symbolic
parameters &NAME, &TO, and &FROM, respectively, of the MOVE prototype statement.
HERE

MOVE

FIELDA,FIELDB

If the preceding macro instruction were used in a source program, the following
assembler language statements would be generated:
HERE

ST
L
ST
L

2,SAVE
2,FIELDB
2,FIELDA
2,SAVE

Positional Parameters
You should use a positional parameter in a macro definition if you want to change
the value of the parameter each time you call the macro definition. This is because
it is easier to supply the value for a positional parameter than for a keyword
parameter. You only have to write the value you want the corresponding argument
to have in the correct position in the operand of the calling macro instruction.
However, if you need a large number of parameters, you should use keyword
parameters. The keywords make it easier to keep track of the individual values you

254

HLASM V1R5 Language Reference

Keyword Parameters

must specify at each call by reminding you which parameters are being given
values.
See Positional Operands on page 300 for details of how to write macro definitions
with positional parameters.

Keyword Parameters
You should use a keyword parameter in a macro definition for a value that changes
infrequently, or if you have a large number of parameters. The keyword, repeated
in the operand, reminds you which parameter is being given a value and for which
purpose the parameter is being used. By specifying a standard default value to be
assigned to the keyword parameter, you can omit the corresponding keyword
argument operand in the calling macro instruction. You can specify the
corresponding keyword operands in any order in the calling macro instruction.
See Keyword Operands on page 301 for details of how to write macro definitions
with keyword parameters.

Combining Positional and Keyword Parameters

By using positional and keyword parameters in a prototype statement, you combine
the benefits of both. You can use positional parameters in a macro definition for
passing values that change frequently, and keyword parameters for passing values
that do not change often.
Positional and keyword parameters can be mixed freely in the macro prototype
statement.
See Combining Positional and Keyword Operands on page 303 for details of how
to write macro definitions using combined positional and keyword parameters.

Subscripted Symbolic Parameters

Subscripted symbolic parameters must be coded in the format:
&PARAM(subscript)

where &PARAM is a variable symbol and subscript is an arithmetic expression. The

subscript can be any arithmetic expression allowed in the operand field of a SETA
instruction (arithmetic expressions are discussed in SETA Instruction on
page 347). The arithmetic expression can contain subscripted variable symbols.
Subscripts can be nested to any level provided that the total length of an individual
operand does not exceed 1024 characters.
The value of the subscript must be greater than or equal to one. The subscript
indicates the position of the entry in the sublist that is specified as the value of the
subscripted parameter (sublists as values in macro instruction operands are fully
described in Sublists in Operands on page 304).

Chapter 7. How to Specify Macro Definitions

255

Processing Statements

Processing Statements
Conditional Assembly Instructions
Conditional assembly instructions let you determine at conditional assembly time
the content of the generated statements and the sequence in which they are
generated. The instructions and their functions are listed below:
Conditional Assembly

Operation Done

GBLA, GBLB, GBLC

LCLA, LCLB, LCLC

Declaration of variable symbols (global-scope and local-scope

SET symbols) and setting of default initial values

SETA, SETB, SETC

Assignment of values to variable symbols (SET symbols)

SETAF, SETCF

External function assignment of values to variable symbols

(SET symbols)

ACTR

Setting loop counter

AGO

Unconditional branch

AIF

Conditional branch (based on logical test)

ANOP

Pass control to next sequential instruction (no operation)

Conditional assembly instructions can be used both inside macro definitions and in
open code. They are described in Chapter 9, How to Write Conditional Assembly
Instructions.

Inner Macro Instructions

Macro instructions can be nested inside macro definitions, allowing you to call other
macros from within your own definition.

Other Conditional Assembly Instructions

Several additional instructions can help you write your macro definitions. The
instructions and their functions are listed below:

256

Inner Macro Instruction

Operation Done

AEJECT

Skip to next page

AINSERT

Insert statement into input stream

AREAD

Assign an arbitrary character string to a variable symbol

(SETC symbol)

ASPACE

Insert one or more blank lines in listing

COPY

Copy the source statements from a source language

library member.

MEXIT

Exit from the macro definition

HLASM V1R5 Language Reference

AEJECT Instruction

AEJECT Instruction
Use the AEJECT instruction to stop the printing of the assembler listing of your
macro definition on the current page, and continue the printing on the next page.

AEJECT
sequence_symbol

sequence_symbol
is a sequence symbol.
The AEJECT instruction causes the next line of the assembly listing of your macro
definition to be printed at the top of a new page. If the line before the AEJECT
statement appears at the bottom of a page, the AEJECT statement has no effect.
An AEJECT instruction immediately following another AEJECT instruction causes a
blank page in the listing of the macro definition.
Notes:
1. The AEJECT instruction can only be used inside a macro definition.
2. The AEJECT instruction itself is not printed in the listing.
3. The AEJECT instruction does not affect the listing of statements generated
when the macro is called.

AINSERT Instruction
The AINSERT instruction, inside macro definitions, harnesses the power of macros
to generate source statements, for instance, using variable substitution. Generated
statements are queued in a special buffer and read after the macro generator
finishes.
The specifications for the AINSERT instruction, which can also be used in open
code, are described in AINSERT Instruction on page 108.

AREAD Instruction
The AREAD instruction assigns an arbitrary character string value to a SETC
symbol.
The AREAD instruction has two formats. The first format lets you assign to a
SETC symbol the character string value of a statement that is placed immediately
after a macro instruction.
The AREAD instruction can only be used inside macro definitions.
Assign Character String Value
SETC_symbolAREAD
NOPRINT
NOSTMT

The second format of the AREAD instruction assigns to a SETC symbol a character
string containing the local time.

Chapter 7. How to Specify Macro Definitions

257

AREAD Instruction

Assign Local Time

SETC_symbolAREADCLOCKB
CLOCKD

SETC_symbol
is a SETC symbol. See SETC Instruction on page 369.
NOSTMT
specifies that the statement to be read by the AREAD instruction is printed in
the assembly listing, but not given any statement number.
NOPRINT
specifies that the statement does not appear in the listing, and no statement
number is assigned to it.
CLOCKB
assigns an 8-character string to SETC_symbol containing the local time in
hundredths of a second since midnight.
CLOCKD
assigns an 8-character string to SETC_symbol containing the local time in the
format HHMMSSTH, where HH is a value between 00 and 23, MM and SS
each have a value between 00 and 59, and TH has a value between 00 and
99.

Assign Character String Value

The first format of AREAD functions in much the same way as symbolic
parameters, but instead of providing your input to macro processing as part of the
macro instruction, you can supply full input records from either the AINSERT buffer
(if any are present), or from the records in the primary input stream that follow
immediately after the macro instruction. Any number of successive statements can
be read into the macro for processing.

|
|

SETC_symbol may be subscripted. When the assembler encounters a Format-1

AREAD statement during the processing of a macro instruction, it reads the source
statement following the macro instruction and assigns an 80-character string to the
SETC symbol in the name field. In the case of nested macros, it reads the
statement following the outermost macro instruction.
If no operand is specified, the statement to be read by AREAD is printed in the
listing and assigned a statement number. The AREAD action is indicated in the
listing by a minus sign between the statement number and the first character of the
record.

|
|
|

Repeated AREAD instruction statements read successive statements. In the

following example, the input record starting with INRECORD1 is read by the first
AREAD statement, and assigned to the SETC symbol &VAL. The input record
starting with INRECORD2 is read by the second AREAD statement, and assigned to
the SETC symbol &VAL1.
Example:

258

HLASM V1R5 Language Reference

ASPACE Instruction

MACRO
MAC1
.
&VAL
AREAD
.
&VAL1
AREAD
.
MEND
CSECT
.
MAC1
INRECORD1 THIS IS THE STATEMENT TO BE PROCESSED FIRST
INRECORD2 THIS IS THE NEXT STATEMENT
.
END
The records read by the AREAD instruction can be in code brought in with the
COPY instruction, if the macro instruction appears in such code. If no more
records exist in the code brought in by the COPY instruction, subsequent
statements are read from the AINSERT buffer or the primary input stream.

Assign Local Time of Day

The second format of AREAD functions in much the same way as a SETC
instruction, but instead of supplying the value you want assigned to the SETC
symbol as a character string in the operand of the AREAD instruction, the value is
provided by the operating system in the form of an 8-character string containing the
local time. A Format-2 AREAD instruction does not cause the assembler to read
the statement following the macro instruction.
Example:

&VAL
&VAL1

MACRO
MAC2
.
AREAD
DC
AREAD
DC
.
MEND

CLOCKB
C'&VAL'
CLOCKD
C'&VAL1'

When the macro definition described above is called, the following statements are
generated:
MAC2
DC
DC

+
+

C'32514'
C'9154'

ASPACE Instruction
Use the ASPACE instruction to insert one or more blank lines in the listing of a
macro definition in your source module. This separates sections of macro definition
code on the listing page.

ASPACE
sequence_symbol
number_of_lines

Chapter 7. How to Specify Macro Definitions

259

COPY Instruction

sequence_symbol
is a sequence symbol.
number_of_lines
is a non-negative decimal integer that specifies the number of lines to be left
blank. If number_of_lines is omitted, one line is left blank. If number_of_lines
has a value greater than the number of lines remaining on the listing page, the
instruction has the same effect as an AEJECT statement.
Notes:
1. The ASPACE instruction can only be used inside a macro definition.
2. The ASPACE instruction itself is not printed in the listing.
3. The ASPACE instruction does not affect the listing of statements generated
when the macro is called.

COPY Instruction
The COPY instruction, inside macro definitions, lets you copy into the macro
definition any sequence of statements allowed in the body of a macro definition.
These statements become part of the body of the macro before macro processing
takes place. You can also use the COPY instruction to copy complete macro
definitions into a source module.
The specifications for the COPY instruction, which can also be used in open code,
are described in COPY Instruction on page 122.

MEXIT Instruction
The MEXIT instruction provides an exit for the assembler from any point in the
body of a macro definition. The MEND instruction provides an exit only from the
end of a macro definition (see MEND Statement on page 245 for details).
The MEXIT instruction statement can be used only inside macro definitions.

MEXIT
sequence_symbol

sequence_symbol
is a sequence symbol.
The MEXIT instruction causes the assembler to exit from a macro definition to the
next sequential instruction after the macro instruction that calls the definition. (This
also applies to nested macro instructions, which are described in Nesting Macro
Instruction Definitions on page 311.)
For example, the following macro definition contains an MEXIT statement:

260

HLASM V1R5 Language Reference

Comment Statements

MACRO
EXITS
DC
DC
DC
MEXIT
DC
DC
DC
MEND

C'A'
C'B'
C'C'
C'D'
C'E'
C'F'

When the macro definition described above is called, the following statements are
generated:
EXITS
DC
C'A'
DC
C'B'
DC
C'C'

+
+
+

Comment Statements
Two types of comment statements can be used within a macro definition:
Ordinary comment statements
Internal macro comment statements

Ordinary Comment Statements

Ordinary comment statements let you make descriptive remarks about the
generated output from a macro definition. Ordinary comment statements can be
used in macro definitions and in open code.
An ordinary comment statement consists of an asterisk in the begin column,
followed by any character string. The comment statement is used by the
assembler to generate an assembler language comment statement, just as other
model statements are used by the assembler to generate assembler statements.
No variable symbol substitution is done.

Internal Macro Comment Statements

You can also write internal macro comments in the body of a macro definition to
describe the operations done during conditional assembly when the macro is
processed.
An internal macro comment statement consists of a period in the begin column,
followed by an asterisk, followed by any character string. No values are substituted
for any variable symbols that are specified in internal macro comment statements.
Internal macro comment statements may appear anywhere in a macro definition.
Notes:
1. Internal macro comments are not generated.
2. The comment character string may contain double-byte data.
3. Internal macro comment statements can be used in open code, however, they
are processed as ordinary comment statements.

Chapter 7. How to Specify Macro Definitions

261

System Variable Symbols

System variable symbols are a special class of variable symbols, starting with the
characters &SYS. Their values are set by the assembler according to specific rules.
You cannot declare them in local-scope SET symbols or global-scope SET
symbols, nor use them as symbolic parameters in macro prototype statements.
You can use these symbols as points of substitution in model statements and
conditional assembly instructions.
All system variable symbols are subject to the same rules of concatenation and
substitution as other variable symbols.
A description of each system variable symbols begins on page 263.
You should not prefix your SET symbols with the character sequence &SYS.
The assembler uses this sequence as a prefix to all system variable symbol
names, and using them for other SET symbol names might cause future
conflicts.

Scope and Variability of System Variable Symbols

Global Scope: Some system variable symbols have values that are established at
the beginning of an assembly and are available both in open code and from within
macros. These symbols have global scope. Most system variable symbols with
global scope have fixed values, although there are some whose value can change
within a single macro expansion. The global-scope system variables symbols with
variable values are &SYSSTMT, &SYSM_HSEV, and &SYSM_SEV.
Local Scope: Some system variable symbols have values that are available only
from within a macro expansion. These system variables have local scope. Since
the value of system variable symbols with local scope is established at the
beginning of a macro expansion and remains unchanged throughout the expansion,
they are designated as having constant values, even though they might have
different values in a later expansion of the same macro, or within inner macros.
Over half of the system variable symbols have local scope and therefore are not
available in open code.

262

HLASM V1R5 Language Reference

&SYSADATA_DSN System Variable Symbol

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

F2FFF46FF66
1A F1
1B
1C 1

1
2
3
4
5
6
7
8
9
1
11
12
14
15
16
17
18
19
2
21
22
23
24
25
26
27

macro
getlocalsys
.
Define globals for values of interest
Gblc &clock,&location,&dsname,&nest
Gbla &nesta
.
now update the globals from within the macro
&clock
setc '&sysclock'
&location setc '&sysloc'
&dsname setc '&sysin_dsn'
&nest
setc '&sysnest'
&nesta
seta &sysnest
mend
r
csect

define globals in opencode

Gblc &clock,&location,&dsname,&nest
Gbla &nesta

invoke macro to update the global values

getlocalsys

now use the updated values

dc
c'&clock'
+
dc
c'24-6-11 17:48:42.914829'
28
dc
c'&nest'
+
dc
c'1'
29
dc
f'&nesta'
+
31

dc
f'1'
end r

Figure 65. Exposing the Value of a Local Scope Variable to Open Code

Uses, Values and Properties: System variable symbols have many uses,
including:
Helping to control conditional assemblies
Capturing environmental data for inclusion in the generated object code
Providing program debugging data
Refer to Appendix C, Macro and Conditional Assembly Language Summary on
page 409 for a summary of the values and properties that can be assigned to
system variable symbols.

&SYSADATA_DSN System Variable Symbol

Use &SYSADATA_DSN in a macro definition to obtain the name of the data set to
which the assembler is writing the associated data.
The local-scope system variable symbol &SYSADATA_DSN is assigned a
read-only value each time a macro definition is called.
When the assembler runs on the MVS operating systems, the value of
the character string assigned to &SYSADATA_DSN is always the value stored in
the JFCB for SYSADATA. If SYSADATA is allocated to DUMMY, or a NULLFILE,
the value in &SYSADATA_DSN is NULLFILE.
For example, &SYSADATA_DSN might be assigned a value such as:
IBMAPC.SYSADATA

Chapter 7. How to Specify Macro Definitions

263

&SYSADATA_MEMBER System Variable Symbol

When the assembler runs on the CMS component of the VM operating

systems, the value of the character string assigned to &SYSADATA_DSN is
determined as follows:
Figure 66. Contents of &SYSADATA_DSN on CMS
SYSADATA Allocated To:

Contents of &SYSADATA_DSN:

CMS file

The 8-character filename, the

8-character filetype, and the
2-character filemode of the file, each
separated by a space

Dummy file (no physical I/O)

DUMMY

Labeled tape file

The data set name of the tape file

Unlabeled tape file

TAPn, where n is a value from 0 to 9,

or A to F.

For example, &SYSADATA_DSN might be assigned a value such as:

SAMPLE

SYSADATA A1

The value of the character string assigned to &SYSADATA_DSN is the

file id from the SYSADAT dlbl.
For example, &SYSADATA_DSN might be assigned a value such as:
MYDATA

Notes:
1. The value of the type attribute of &SYSADATA_DSN (T'&SYSADATA_DSN) is
always U.
2. The value of the count attribute of &SYSADATA_DSN (K'&SYSADATA_DSN)
is equal to the number of characters assigned as a value to
&SYSADATA_DSN. In the CMS example above, the count attribute of
&SYSADATA_DSN is 20.

&SYSADATA_MEMBER System Variable Symbol

The value of &SYSADATA_MEMBER is always null. The value of the
type attribute is O, and the value of the count attribute is 0.
You can use &SYSADATA_MEMBER in a macro definition to obtain
the name of the data set member to which the assembler is writing the associated
data.
The local-scope system variable symbol &SYSADATA_MEMBER is assigned a
read-only value each time a macro definition is called.

264

HLASM V1R5 Language Reference

&SYSADATA_VOLUME System Variable Symbol

If the data set to which the assembler is writing the associated data is not an MVS
partitioned data set, &SYSADATA_MEMBER is assigned a null character string.

Notes:
1. The value of the type attribute of &SYSADATA_MEMBER
(T'&SYSADATA_MEMBER) is U, unless &SYSADATA_MEMBER is assigned a
null character string, in which case the value of the type attribute is O.
2. The value of the count attribute of &SYSADATA_MEMBER
(K'&SYSADATA_MEMBER) is equal to the number of characters assigned as
a value to &SYSADATA_MEMBER. If &SYSADATA_MEMBER is assigned a
null character string, the value of the count attribute is 0.

&SYSADATA_VOLUME System Variable Symbol

Use &SYSADATA_VOLUME in a macro definition to obtain the volume identifier of
the first volume containing the data set to which the assembler is writing the
associated data.
The local-scope system variable symbol &SYSADATA_VOLUME is assigned a
read-only value each time a macro definition is called.
If the assembler runs on the CMS component of the VM operating
system, and the associated data is being written to a Shared File System CMS file,
&SYSADATA_VOLUME is assigned the value SFS.
If the volume on which the data set resides is not labeled, &SYSADATA_VOLUME
is assigned a null character string.
Notes:
1. The value of the type attribute of &SYSADATA_VOLUME
(T'&SYSADATA_VOLUME) is U, unless &SYSADATA_VOLUME is assigned a
null character string, in which case the value of the type attribute is O.
2. The value of the count attribute of &SYSADATA_VOLUME
(K'&SYSADATA_VOLUME) is equal to the number of characters assigned as a
value to &SYSADATA_VOLUME. If &SYSADATA_VOLUME is assigned a null
character string, the value of the count attribute is 0. The maximum length of
this system variable symbol is 6.

&SYSASM System Variable Symbol

Use &SYSASM to obtain the name of the assembler being used to assemble your
source module. &SYSASM has a global scope. For example, when IBM High
Level Assembler for MVS & VM & VSE is used, &SYSASM has the value:
HIGH LEVEL ASSEMBLER
Notes:
1. The value of the type attribute of &SYSASM (T'&SYSASM) is always U.
2. The value of the count attribute (K'&SYSASM) is the number of characters
assigned. In the above example, the count attribute of &SYSASM is 20.

Chapter 7. How to Specify Macro Definitions

265

&SYSCLOCK System Variable Symbol

Use &SYSCLOCK to obtain the TOD clock date and time at which the macro was
generated, based on Universal Time (GMT).
The local-scope system variable symbol &SYSCLOCK is assigned a read-only
value each time a macro definition is called.
The value of &SYSCLOCK is a 26-character string in the format:
YYYY-MM-DD HH:MM:SS.mmmmmm
where:
YYYY

is a four-digit field that gives the year, including the century. It has a value
between 0000 and 9999, inclusive.

is a two-digit field that gives the month of the year. It has a value between
01 and 12, inclusive.

is a two-digit field that gives the day of the month. It has a value between
01 and 31, inclusive.

is a two-digit field that gives the hour of the day. It has a value between
00 and 23, inclusive.

is a two-digit field that gives the minute of the hour. It has a value
between 00 and 59, inclusive.

is a two-digit field that gives the second of the minute. It has a value
between 00 and 59, inclusive.

mmmmmm is a six-digit field that gives the microseconds within the seconds. It
has a value between 000000 and 999999, inclusive.
Example:
21-6-8 17:36:3 43284
Notes:
1. The value of the type attribute of &SYSCLOCK (T'&SYSCLOCK) is always U.
2. The value of the count attribute (K'&SYSCLOCK) is always 26.

&SYSDATC System Variable Symbol

Use &SYSDATC to obtain the date, including the century, on which your source
module is assembled. &SYSDATC has a global scope.
The value of &SYSDATC is an 8-character string in the format:
YYYYMMDD
where:
YYYY is four-digit field that gives the year, including the century. It has a value
between 0000 and 9999, inclusive.

266

is two-digit field that gives the month of the year. It has a value between 01
and 12, inclusive.

is two-digit field that gives the day of the month. It has a value between 01
and 31, inclusive.

HLASM V1R5 Language Reference

&SYSDATE System Variable Symbol

Example:
2328
Notes:
1. The date corresponds to the date printed in the page heading of listings and
remains constant for each assembly.
2. The value of the type attribute of &SYSDATC (T'&SYSDATC) is always N.
3. The value of the count attribute (K'&SYSDATC) is always 8.

&SYSDATE System Variable Symbol

Use &SYSDATE to obtain the date, in standard format, on which your source
module is assembled. &SYSDATE has a global scope.
The value of &SYSDATE is an 8-character string in the format:
MM/DD/YY
where:
MM

is a two-digit field that gives the month of the year. It has a value between
01 and 12, inclusive.

is a two-digit field that gives the day of the month. It has a value between
01 and 31, inclusive. It is separated from MM by a slash.

is a two-digit field that gives the year of the century. It has a value between
00 and 99, inclusive. It is separated from DD by a slash.

Example:
6/11/4
Notes:
1. The date corresponds to the date printed in the page heading of listings and
remains constant for each assembly.
2. The value of the type attribute of &SYSDATE (T'&SYSDATE) is always U.
3. The value of the count attribute (K'&SYSDATE) is always 8.

&SYSECT System Variable Symbol

Use &SYSECT in a macro definition to generate the name of the current control
section. The current control section is the control section in which the macro
instruction that calls the definition appears. You can't use &SYSECT in open code.
The local-scope system variable symbol &SYSECT is assigned a read-only value
each time a macro definition is called.
The value assigned is the symbol that represents the name of the current control
section from which the macro definition is called. Note that it is the control section
in effect when the macro is called. A control section that has been initiated or
continued by substitution does not affect the value of &SYSECT for the expansion
of the current macro. However, it may affect &SYSECT for a subsequent macro
call. Nested macros cause the assembler to assign a value to &SYSECT that

Chapter 7. How to Specify Macro Definitions

267

&SYSECT System Variable Symbol

depends on the control section in force inside the outer macro when the inner
macro is called.
Notes:
1. The control section whose name is assigned to &SYSECT can be defined by a
program sectioning statement. This can be a START, CSECT, RSECT,
DSECT, or COM statement.
2. The value of the type attribute of &SYSECT (T'&SYSECT) is always U.
3. The value of the count attribute (K'&SYSECT) is equal to the number of
characters assigned as a value to &SYSECT.
4. Throughout the use of a macro definition, the value of &SYSECT is considered
a constant, independent of any program sectioning statements or inner macro
instructions in that definition.
The next example shows these rules:
MACRO
INNER
&INCSECT CSECT
DC
MEND

CSOUT1

MACRO
OUTER1
CSECT
DS
INNER
INNER
DC
MEND

&INCSECT
A(&SYSECT)

Statement 1
Statement 2

Statement 3
1C
INA
INB
A(&SYSECT)

Statement 4
Statement 5
Statement 6

MACRO
OUTER2
DC
A(&SYSECT)
Statement 7
MEND
------------------------------------------------------------------MAINPROG CSECT
Statement 8
DS
2C
OUTER1
Statement 9
OUTER2
Statement 1
------------------------------------------------------------------Generated Program
------------------------------------------------------------------MAINPROG CSECT
DS
2C
CSOUT1
CSECT
DS
1C
INA
CSECT
DC
A(CSOUT1)
INB
CSECT
DC
A(INA)
DC
A(MAINPROG)
DC
A(INB)
In this example:

268

HLASM V1R5 Language Reference

&SYSIN_DSN System Variable Symbol

Statement 8 is the last program sectioning statement processed before

statement 9 is processed. Therefore, &SYSECT is assigned the value
MAINPROG for macro instruction OUTER1 in statement 9. MAINPROG is substituted
for &SYSECT when it appears in statement 6.
Statement 3 is the program sectioning statement processed before statement 4
is processed. Therefore, &SYSECT is assigned the value CSOUT1 for macro
instruction INNER in statement 4. CSOUT1 is substituted for &SYSECT when it
appears in statement 2.
Statement 1 is used to generate a CSECT statement for statement 4. This is
the last program sectioning statement that appears before statement 5.
Therefore, &SYSECT is assigned the value INA for macro instruction INNER in
statement 5. INA is substituted for &SYSECT when it appears in statement 2.
Statement 1 is used to generate a CSECT statement for statement 5. This is
the last program sectioning statement that appears before statement 10.
Therefore, &SYSECT is assigned the value INB for macro instruction OUTER2 in
statement 10. INB is substituted for &SYSECT when it appears in statement 7.

&SYSIN_DSN System Variable Symbol

Use &SYSIN_DSN in a macro definition to obtain the name of the data set from
which the assembler is reading the source module.
The local system variable symbol &SYSIN_DSN is assigned a read-only value each
time a macro definition is called.
If concatenated data sets are used to provide the source module,
&SYSIN_DSN has a value equal to the data set name of the data set that contains
the open code source line of the macro call statement, irrespective of the nesting
depth of the macro line containing the &SYSIN_DSN reference.
When the assembler runs on the MVS operating systems, the value of the
character string assigned to &SYSIN_DSN is always the value stored in the JFCB
for SYSIN.
When the assembler runs on the CMS component of the VM operating
systems, the value of the character string assigned to &SYSIN_DSN is determined
as follows:
Figure 67. Contents of &SYSIN_DSN on CMS
SYSIN Allocated To:

Contents of &SYSIN_DSN:

CMS file

The 8-character filename, the

8-character filetype, and the
2-character filemode of the file, each
separated by a space

Reader

READER

Terminal

TERMINAL

Labeled tape file

The data set name of the tape file

Unlabeled tape file

TAPn, where n is a value from 0 to 9,

or A to F.

Chapter 7. How to Specify Macro Definitions

269

&SYSIN_MEMBER System Variable Symbol

When the assembler runs on the VSE operating system, the value of the
character string assigned to &SYSIN_DSN is determined as follows:
Figure 68. Contents of &SYSIN_DSN on VSE
SYSIPT Assigned To:

Contents of &SYSIN_DSN:

Job stream (SYSIPT)

SYSIPT

Disk

The file-id

Labeled tape file

The file-id of the tape file

Unlabeled tape file

SYSIPT

Examples:
On MVS, &SYSIN_DSN might be assigned a value such as:
IBMAPC.ASSEMBLE.SOURCE
On CMS, &SYSIN_DSN might be assigned a value such as:
SAMPLE

ASSEMBLE A1

Notes:
1. If the SOURCE user exit provides the data set information then the value in
&SYSIN_DSN is the value extracted from the Exit-Specific Information block
described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSIN_DSN (T'&SYSIN_DSN) is always U.
3. The value of the count attribute of &SYSIN_DSN (K'&SYSIN_DSN) is equal to
the number of characters assigned as a value to &SYSIN_DSN. In the CMS
example above, the count attribute of &SYSIN_DSN is 20.
4. Throughout the use of a macro definition, the value of &SYSIN_DSN is
considered a constant.

&SYSIN_MEMBER System Variable Symbol

The value of &SYSIN_MEMBER is always null.
The value of the type attribute is O, and the value of the count attribute is 0.

You can use &SYSIN_MEMBER in a macro definition to obtain the

name of the data set member from which the assembler is reading the source
module. If concatenated data sets are used to provide the source module,
&SYSIN_MEMBER has a value equal to the name of the data set member that
contains the macro instruction that calls the definition.
The local-scope system variable symbol &SYSIN_MEMBER is assigned a read-only
value each time a macro definition is called.

270

HLASM V1R5 Language Reference

&SYSIN_VOLUME System Variable Symbol

If the data set from which the assembler is reading the source module is not an
MVS partitioned data set or a CMS MACLIB, &SYSIN_MEMBER is assigned a null
character string.
Notes:
1. If the SOURCE user exit provides the data set information then the value in
&SYSIN_MEMBER is the value extracted from the Exit-Specific Information
block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSIN_MEMBER (T'&SYSIN_MEMBER) is
U, unless &SYSIN_MEMBER is assigned a null character string, in which case
the value of the type attribute is O.
3. The value of the count attribute of &SYSIN_MEMBER (K'&SYSIN_MEMBER)
is equal to the number of characters assigned as a value to
&SYSIN_MEMBER. If &SYSIN_MEMBER is assigned a null character string,
the value of the count attribute is 0.
4. Throughout the use of a macro definition, the value of &SYSIN_MEMBER is
considered a constant.

&SYSIN_VOLUME System Variable Symbol

Use &SYSIN_VOLUME in a macro definition to obtain the volume identifier of the
first volume containing the data set from which the assembler is reading the source
module.
If concatenated data sets are used to provide the source module,
&SYSIN_VOLUME has a value equal to the volume identifier of the first volume
containing the data set that contains the macro call instruction.
The local-scope system variable symbol &SYSIN_VOLUME is assigned a read-only
value each time a macro definition is called.
If the assembler runs on the CMS component of the VM operating
system, and the source module is being read from a Shared File System CMS file,
&SYSIN_VOLUME is assigned the value SFS.
If the volume on which the input data set resides is not labeled, &SYSIN_VOLUME
is assigned a null character string.
Notes:
1. If the SOURCE user exit provides the data set information then the value in
&SYSIN_VOLUME is the value extracted from the Exit-Specific Information
block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSIN_VOLUME (T'&SYSIN_VOLUME) is
U, unless &SYSIN_VOLUME is assigned a null character string, in which case
the value of the type attribute is O.
3. The value of the count attribute of &SYSIN_VOLUME (K'&SYSIN_VOLUME) is
equal to the number of characters assigned as a value to &SYSIN_VOLUME. If
&SYSIN_VOLUME is assigned a null character string, the value of the count
attribute is 0. The maximum length of this system variable symbol is 6.
4. Throughout the use of a macro definition, the value of &SYSIN_VOLUME is
considered a constant.
Chapter 7. How to Specify Macro Definitions

271

&SYSJOB System Variable Symbol

Use &SYSJOB to obtain the jobname of the assembly job used to assemble your
source module. &SYSJOB has a global scope.
When the assembler runs on the CMS component of the VM operating systems,
&SYSJOB is assigned a value of (NOJOB).
Notes:
1. The value of the type attribute of &SYSJOB (T'&SYSJOB) is always U.
2. The value of the count attribute (K'&SYSJOB) is the number of characters
assigned.

&SYSLIB_DSN System Variable Symbol

Use &SYSLIB_DSN in a macro definition to obtain name of the data set from which
the assembler read the macro definition statements. If the macro definition is a
source macro definition, &SYSLIB_DSN is assigned the same value as
&SYSIN_DSN.
The local-scope system variable symbol &SYSLIB_DSN is assigned a read-only
value each time a macro definition is called.
When the assembler runs on the MVS operating systems, the value of the
character string assigned to &SYSLIB_DSN is always the value stored in the JFCB
for SYSLIB.
When the assembler runs on the CMS component of the VM operating systems,
and the macro definition is a library macro definition, &SYSLIB_DSN is assigned
the file name, file type, and file mode of the data set.
When the macro definition is a library macro definition, &SYSLIB_DSN is
assigned the library name and sublibrary name of the VSE Librarian file.
Examples
Under MVS, &SYSLIB_DSN might be assigned a value such as:
SYS1.MACLIB
Under CMS, &SYSLIB_DSN might be assigned a value such as:
DMSGPI MACLIB S2
Under VSE, &SYSLIB_DSN might be assigned a value such as:
IJSYSRS.SYSLIB
Notes:
1. If the LIBRARY user exit provides the data set information then the value in
&SYSLIB_DSN is the value extracted from the Exit-Specific Information block
described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSLIB_DSN (T'&SYSLIB_DSN) is always
U.

272

HLASM V1R5 Language Reference

&SYSLIB_MEMBER System Variable Symbol

3. The value of the count attribute of &SYSLIB_DSN (K'&SYSLIB_DSN) is equal

to the number of characters assigned as a value to &SYSLIB_DSN.
4. Throughout the use of a macro definition, the value of &SYSLIB_DSN is
considered a constant.

&SYSLIB_MEMBER System Variable Symbol

Use &SYSLIB_MEMBER in a macro definition to obtain the name of the data set
member from which the assembler read the macro definition statements. If the
macro definition is a source macro definition, &SYSLIB_MEMBER is assigned the
same value as &SYSIN_MEMBER.
The local-scope system variable symbol &SYSLIB_MEMBER is assigned a
read-only value each time a macro definition is called.
Notes:
1. If the LIBRARY user exit provides the data set information then the value in
&SYSLIB_MEMBER is the value extracted from the Exit-Specific Information
block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSLIB_MEMBER (T'&SYSLIB_MEMBER)
is U, unless &SYSLIB_MEMBER is assigned a null character string, in which
case the value of the type attribute is O.
3. The value of the count attribute of &SYSLIB_MEMBER
(K'&SYSLIB_MEMBER) is equal to the number of characters assigned as a
value to &SYSLIB_MEMBER. If &SYSLIB_MEMBER is assigned a null
character string, the value of the count attribute is 0.
4. Throughout the use of a macro definition, the value of &SYSLIB_MEMBER is
considered a constant.

&SYSLIB_VOLUME System Variable Symbol

Use &SYSLIB_VOLUME in a macro definition to obtain the volume identifier of the
volume containing the data set from which the assembler read the macro definition
statements. If the macro definition is a source macro definition,
&SYSLIB_VOLUME is assigned the same value as &SYSIN_VOLUME.
The local-scope system variable symbol &SYSLIB_VOLUME is assigned a
read-only value each time a macro definition is called.
If the assembler runs on the CMS component of the VM operating system, and the
source module is being read from a Shared File System CMS file,
&SYSLIB_VOLUME is assigned the value SFS.
Notes:
1. If the LIBRARY user exit provides the data set information then the value in
&SYSLIB_VOLUME is the value extracted from the Exit-Specific Information
block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSLIB_VOLUME (T'&SYSLIB_VOLUME)
is U, unless &SYSLIB_VOLUME is assigned a null character string, in which
case the value of the type attribute is O.
3. The value of the count attribute of &SYSLIB_VOLUME (K'&SYSLIB_VOLUME)
is equal to the number of characters assigned as a value to
Chapter 7. How to Specify Macro Definitions

273

&SYSLIN_DSN System Variable Symbol

&SYSLIB_VOLUME. If &SYSLIB_VOLUME is assigned a null character string,

the value of the count attribute is 0. The maximum length of this system
variable symbol is 6.
4. Throughout the use of a macro definition, the value of &SYSLIB_VOLUME is
considered a constant.

&SYSLIN_DSN System Variable Symbol

Use &SYSLIN_DSN in a macro definition to obtain the name of the data set to
which the assembler is writing the object records when assembler option OBJECT,
GOFF or XOBJECT is specified.
The local-scope system variable symbol &SYSLIN_DSN is assigned a read-only
value each time a macro definition is called.
The value of the character string assigned to &SYSLIN_DSN is always
the value stored in the JFCB for SYSLIN. If SYSLIN is allocated to DUMMY, or a
NULLFILE, the value in &SYSLIN_DSN is NULLFILE.
The value of the character string assigned to &SYSLIN_DSN is
determined as follows:
Figure 69. Contents of &SYSLIN_DSN on CMS
SYSLIN Allocated To:

Contents of &SYSLIN_DSN:

CMS file

The 8-character filename, the

8-character filetype, and the
2-character filemode of the file, each
separated by a space

Dummy file (no physical I/O)

DUMMY

Punch

PUNCH

Labeled tape file

The data set name of the tape file

Unlabeled tape file

TAPn, where n is a value from 0 to 9,

or A to F.

The value of the character string assigned to &SYSLIN_DSN is

determined as follows:
Figure 70. Contents of &SYSLIN_DSN on VSE
SYSLNK Assigned To:

Contents of &SYSLIN_DSN:

Disk file

The file-id

Labeled tape file

The file-id of the tape file

Unlabeled tape file

SYSLNK

Examples:
On MVS, &SYSLIN_DSN might be assigned a value such as:

274

HLASM V1R5 Language Reference

&SYSLIN_MEMBER System Variable Symbol

IBMAPC.OBJ
On CMS, &SYSLIN_DSN might be assigned a value such as:
SAMPLE

TEXT

Notes:
1. If the OBJECT user exit provides the data set information then the value in
&SYSLIN_DSN is the value extracted from the Exit-Specific Information block
described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSLIN_DSN (T'&SYSLIN_DSN) is always
U.
3. The value of the count attribute of &SYSLIN_DSN (K'&SYSLIN_DSN) is equal
to the number of characters assigned as a value to &SYSLIN_DSN.

&SYSLIN_MEMBER System Variable Symbol

The value of &SYSLIN_MEMBER is always null.
The value of the type attribute is O, and the value of the count attribute is 0.

You can use &SYSLIN_MEMBER in a macro definition to obtain the

name of the data set member to which the assembler is writing the object module
when the assembler option OBJECT, GOFF or XOBJECT is specified.
The local-scope system variable symbol &SYSLIN_MEMBER is assigned a
read-only value each time a macro definition is called.
If the library to which the assembler is writing the object records is not an MVS
partitioned data set, &SYSLIN_MEMBER is assigned a null character string.

Notes:
1. If the OBJECT user exit provides the data set information then the value in
&SYSLIN_MEMBER is the value extracted from the Exit-Specific Information
block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSLIN_MEMBER (T'&SYSLIN_MEMBER)
is U, unless &SYSLIN_MEMBER is assigned a null character string, in which
case the value of the type attribute is O.
3. The value of the count attribute of &SYSLIN_MEMBER
(K'&SYSLIN_MEMBER) is equal to the number of characters assigned as a
value to &SYSLIN_MEMBER. If &SYSLIN_MEMBER is assigned a null
character string, the value of the count attribute is 0.

&SYSLIN_VOLUME System Variable Symbol

Use &SYSLIN_VOLUME in a macro definition to obtain the volume identifier of the
object data set. The volume identifier is of the first volume containing the data set.
&SYSLIN_VOLUME is only assigned a value when you specify the OBJECT, GOFF
or XOBJECT assembler option.

Chapter 7. How to Specify Macro Definitions

275

&SYSLIST System Variable Symbol

The local-scope system variable symbol &SYSLIN_VOLUME is assigned a

read-only value each time a macro definition is called.
If the assembler runs on the CMS component of the VM operating system, and the
assembler listing is being written to a Shared File System CMS file,
&SYSLIN_VOLUME is assigned the value SFS.
If the volume on which the data set resides is not labeled, &SYSLIN_VOLUME is
assigned a null character string.
Notes:
1. If the OBJECT user exit provides the data set information then the value in
&SYSLIN_VOLUME is the value extracted from the Exit-Specific Information
block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSLIN_VOLUME (T'&SYSLIN_VOLUME)
is U, unless &SYSLIN_VOLUME is assigned a null character string, in which
case the value of the type attribute is O.
3. The value of the count attribute of &SYSLIN_VOLUME (K'&SYSLIN_VOLUME)
is equal to the number of characters assigned as a value to
&SYSLIN_VOLUME. If &SYSLIN_VOLUME is assigned a null character string,
the value of the count attribute is 0. The maximum length of this system
variable symbol is 6.

&SYSLIST System Variable Symbol

Use &SYSLIST instead of a positional parameter inside a macro definition; for
example, as a point of substitution. By varying the subscripts attached to
&SYSLIST, you can refer to any sublist entry in a macro call operand, or any
positional operands in a macro call. You can also refer to positional operands for
which no corresponding positional parameter is specified in the macro prototype
statement.
The local-scope system variable symbol &SYSLIST is assigned a read-only value
each time a macro definition is called.
&SYSLIST refers to the complete list of positional operands specified in a macro
instruction. &SYSLIST does not refer to keyword operands. However, &SYSLIST
cannot be specified as &SYSLIST without a subscript. One of the two following
forms must be used for references or as a point of substitution:
1. &SYSLIST(n) can be used to refer to the n-th positional operand
2. If the n-th operand is a sublist, then &SYSLIST(n,m) can be used to refer to the
m-th operand in the sublist.
3. When referring to multilevel (nested) sublists in operands of macro instructions,
refer to elements of inner sublists by using the applicable number of subscripts
for &SYSLIST.
The subscripts n and m can be any arithmetic expression allowed in the operand of
a SETA instruction (See SETA Instruction on page 347). The subscript n must
be greater than or equal to 0. The subscript m and any additional subscripts after
m must be greater than or equal to 1.

276

HLASM V1R5 Language Reference

&SYSLIST System Variable Symbol

The examples below show the values assigned to &SYSLIST according to the
value of its subscripts n and m.
Macro instruction:
-----------------NAME
MACALL
Use Within a
Macro Definition:
--------------------&SYSLIST(2)
&SYSLIST(3,1)
&SYSLIST(3,2,2)

ONE,TWO,(3,(4,5,6),,8),,TEN,()
Value
-----------TWO
3
5

See note:
---------

&SYSLIST(4)

Null

&SYSLIST(12)
&SYSLIST(3,3)

Null
Null

1
2

&SYSLIST(3,5)

Null

&SYSLIST(2,1)
&SYSLIST(2,2)

TWO
Null

&SYSLIST()
&SYSLIST(3)
&SYSLIST(11)
&SYSLIST(11,1)

NAME
(3,(4,5,6),,8)
()
Null

Notes:
1. If the position indicated by n refers to an omitted operand, or refers to an entry
past the end of the list of positional operands specified, the null character string
is substituted for &SYSLIST(n).
2. If the position (in a sublist) indicated by the second subscript, m, refers to an
omitted entry, or refers past the end of the list of entries specified in the sublist
referred to by the first subscript n, the null character string is substituted for
&SYSLIST(n,m).
3. If the n-th positional operand is not a sublist, &SYSLIST(n,1) refers to the
operand. However, &SYSLIST(n,m), where m is greater than 1, will cause the
null character string to be substituted.
4. If the value of subscript n is 0, then &SYSLIST(n) is assigned the value
specified in the name field of the macro instruction, except when it is a
sequence symbol.
Attribute references can be made to the previously described forms of &SYSLIST.
The attributes are the attributes inherent in the positional operands or sublist entries
to which you refer. However, the number attribute of &SYSLIST (N'&SYSLIST) is
different from the number attribute described in Data Attributes on page 324.
One of two forms can be used for the number attribute:
To indicate the number of positional operands specified in a call, use the form
N'&SYSLIST.
To indicate the number of sublist entries that have been specified in a
positional operand, use the form N'&SYSLIST(n).

Chapter 7. How to Specify Macro Definitions

277

&SYSLOC System Variable Symbol

To indicate the number of entries in nested sublists, specify the appropriate set
of subscripts need to reference the selected sublist.
Notes:
1. N'&SYSLIST includes any positional operands that are omitted. Positional
operands are omitted by coding a comma where an operand is expected.
2. N'&SYSLIST(n) includes those sublist entries specifically omitted by specifying
the comma that would normally have followed the entry.
3. If the operand indicated by n is not a sublist, N'&SYSLIST(n) is 1. If it is
omitted, N'&SYSLIST(n) is 0.
The COMPAT(SYSLIST) assembler option instructs the assembler to treat sublists
in macro instruction operands as character strings, not sublists. See the HLASM
Programmer's Guide for a description of the COMPAT(SYSLIST) assembler option.
Examples of sublists:
Macro Instruction
MACLST
MACLST
MACLST
MACLST
MACLST
MACLST
MACLST

1,2,3,4
A,B,,D,E
,A,B,C,D
(A,B,C),(D,E,F)
KEY1=A,KEY2=B
A,B,KEY1=C

N'&SYSLIST
4
5
5
2

2
N'&SYSLIST(2)

MACSUB
MACSUB
MACSUB
MACSUB
MACSUB
MACSUB
MACSUB
MACSUB

A,(1,2,3,4,5),B
A,(1,,3,,5),B
A,(,2,3,4,5),B
A,B,C
A,,C
A,(),C
A,KEY=(A,B,C)

5
5
5
1

1

&SYSLOC System Variable Symbol

Use &SYSLOC in a macro definition to generate the name of the location counter
in effect. If you have not coded a LOCTR instruction between the macro instruction
and the preceding START, CSECT, RSECT, DSECT, or COM instruction, the value
of &SYSLOC is the same as the value of &SYSECT.
The assembler assigns to the system variable symbol &SYSLOC a local read-only
value each time a macro definition containing it is called. The value assigned is the
symbol representing the name of the location counter in use at the point where the
macro is called.
&SYSLOC can only be used in macro definitions; it has local scope.

278

HLASM V1R5 Language Reference

&SYSMAC System Variable Symbol

Notes:
1. The value of the type attribute of &SYSLOC (T'&SYSLOC) is always U.
2. The value of the count attribute (K'&SYSLOC) is equal to the number of
characters assigned as a value to &SYSLOC.
3. Throughout the use of a macro definition, the value of &SYSLOC is considered
a constant.

&SYSMAC System Variable Symbol

By varying the subscripts attached to the &SYSMAC you can refer to the name of
any of the macros called between open code and the current nesting level, that is,
&SYSMAC(&SYSNEST) returns 'OPEN CODE'. Valid subscripts are 0 to
&SYSNEST. If &SYSMAC is used with a subscript greater than &SYSNEST, a null
character string is returned.
&SYSMAC with no subscript is treated as &SYSMAC(0) and so provides the name
of the macro being expanded. This is not considered to be an error and so no
message is issued.
The local-scope system variable symbol &SYSMAC is assigned a read-only value
each time a macro definition is called.
Notes:
1. The value of the type attribute of &SYSMAC (T'&SYSMAC(n)) is U, unless
&SYSMAC(n) is assigned a null character string, in which case the value of the
type attribute is O.
2. The value of the count attribute (K'&SYSMAC(n)) is equal to the number of
characters assigned as a value to &SYSMAC(n).

&SYSM_HSEV System Variable Symbol

Use &SYSM_HSEV to get the highest MNOTE severity so far for the assembly.
The global-scope system variable symbol &SYSM_HSEV is assigned a read-only
value. The assembler compares this value with the severity of MNOTE assembler
instructions as they are encountered and, if lower, updates it with the higher value.
Notes:
1. The value of the variable symbol is supplied as three numeric characters, not
as an arithmetic (binary) value.
2. The value of the type attribute of &SYSM_SEV (T'&SYSM_SEV) is always N.
3. The value of the count attribute (K'&SYSM_SEV) is always 3.
4. The value of &SYSM_HSEV is unreliable if any MNOTE is incorrectly coded
such that a diagnostic message is generated for the MNOTE statement. The
cause of the diagnostic message must be corrected.
In Figure 71 on page 281 the &SYSM_HSEV variable is updated immediately
when an MNOTE is issued with a higher severity.

Chapter 7. How to Specify Macro Definitions

279

&SYSM_SEV System Variable Symbol

Use &SYSM_SEV to get the highest MNOTE severity code for the macro most
recently called directly from this level.
The global-scope system variable symbol &SYSM_SEV is assigned a read-only
value. The assembler assigns a value of zero when a macro is called and when a
macro returns (MEND or MEXIT), the highest severity of all MNOTE assembler
instructions executed in the called macro is used to update the variable.
Notes:
1. The value of the variable symbol is supplied as three numeric characters, not
as an arithmetic (binary) value.
2. The value of the type attribute of &SYSM_SEV (T'&SYSM_SEV) is always N.
3. The value of the count attribute (K'&SYSM_SEV) is always 3.
4. The value of &SYSM_SEV is unreliable if any MNOTE is incorrectly coded such
that a diagnostic message is generated for the MNOTE statement. The cause
of the diagnostic message must be corrected.
In Figure 71 on page 281 the &SYSM_SEV variable has a value of 0 until INNER
returns. The OUTER macro uses &SYSM_SEV to determine which statements to
generate, and in this case issues an MNOTE to pass the severity back to the open
code.

280

HLASM V1R5 Language Reference

&SYSNDX System Variable Symbol

8
ASMA254I MNOTE
1 4
18 4
ASMA254I MNOTE
2 8
28 88
ASMA254I MNOTE
3 88

38 88

1
MACRO
2
OUTER &SEV
3
DC
A(&SYSM_HSEV,&SYSM_SEV) outer 1
4
MNOTE &SEV,'OUTER - parm severity=&SEV'
5
DC
A(&SYSM_HSEV,&SYSM_SEV) outer 2
6
INNER
7
DC
A(&SYSM_HSEV,&SYSM_SEV) outer 3
8
AIF ('&SEV' GT '&SYSM_SEV').MN
9
MNOTE &SYSM_SEV,'OUTER - returned severity=&SYSM_SEV'
1 .MN ANOP
11
DC
A(&SYSM_HSEV,&SYSM_SEV) outer 4
12
MEND
13
MACRO
14
INNER
15
DC
A(&SYSM_HSEV,&SYSM_SEV) inner 1
16
MNOTE 8,'INNER'
17
DC
A(&SYSM_HSEV,&SYSM_SEV) inner 2
18
MEND
19 E_G CSECT
2 ,OPEN CODE
an mnote comment - sev=
21
DC
A(&SYSM_HSEV,&SYSM_SEV) open_code
+
DC
A(,)
open_code
22
OUTER 4
23+
DC
A(,)
outer 1
24+
4,OUTER - parm severity=4
25+
DC
A(4,)
outer 2
26+
DC
A(4,)
inner 1
27+
8,INNER
28+
DC
A(8,)
inner 2
29+
DC
A(8,8)
outer 3
3+
8,OUTER - returned severity=8
31+
DC
A(8,8)
outer 4
32 ,OPEN CODE
an mnote comment - sev=
33
DC
A(&SYSM_HSEV,&SYSM_SEV) open_code
+
DC
A(8,8)
open_code
34
END

Figure 71. Example of the behavior of the &SYSM_HSEV and &SYSM_SEV variables.

&SYSNDX System Variable Symbol

For each macro invocation, a new value of &SYSNDX is assigned. The previous
value is incremented by 1. Thus, you can attach &SYSNDX to the end of a symbol
inside a macro definition to generate a unique suffix for that symbol each time you
call the definition. Although an apparently identical symbol is to be generated by
two or more calls to the same definition, the suffix provided by &SYSNDX produces
two or more unique symbols. For example, the symbol ABC&SYSNDX could
generate ABC0001 on one invocation of a macro, and ABC0002 on the next
invocation. Thus you avoid an error being flagged for multiply defined symbols.
The local-scope system variable symbol &SYSNDX is assigned a read-only value
each time a macro definition is called from a source module.
The value assigned to &SYSNDX is a number from 1 to 9999999. For the
numbers 0001 through 9999, four digits are generated. For the numbers 10000
through 9999999, the value is generated with no zeros to the left. The value 0001
is assigned to the first macro called by a program, and is incremented by one for
each subsequent macro call (including nested macro calls).

Chapter 7. How to Specify Macro Definitions

281

&SYSNDX System Variable Symbol

The maximum value for &SYSNDX can be controlled by the MHELP instruction
described under MHELP Control on &SYSNDX on page 398.
Notes:
1. &SYSNDX does not generate a valid symbol, and it must:
Follow the alphabetic character to which it is concatenated
Be concatenated to a symbol containing 59 characters or fewer
2. The value of the type attribute of &SYSNDX (T'&SYSNDX) is always N.
3. The value of the count attribute (K'&SYSNDX) is equal to the number of digits
generated. If a symbol generated by one macro is to be referenced by code
generated by another macro, the two macros must provide means for
communicating the necessary information. Their respective values of &SYSNDX
cannot be guaranteed to differ by any fixed amount.
The example that follows shows the use of &SYSNDX, and a way to communicate
local &SYSNDX values among macro instructions. It is assumed that the first
macro instruction processed, OUTER1, is the 106th macro instruction processed by
the assembler.
MACRO
INNER1
GBLC
A&SYSNDX SR
CR
BE
B
MEND

&NDXNUM
2,5
2,5
B&NDXNUM
A&SYSNDX

Statement 1
Statement 2
Statement 3

MACRO
OUTER1
GBLC
&NDXNUM
&NDXNUM SETC
'&SYSNDX'
Statement 4
&NAME
SR
2,4
AR
2,6
INNER1
Statement 5
B&SYSNDX S
2,=F'1'
Statement 6
MEND
------------------------------------------------------------------ALPHA
OUTER1
Statement 7
BETA
OUTER1
Statement 8
------------------------------------------------------------------ALPHA
SR
2,4
AR
2,6
A17
SR
2,5
CR
2,5
BE
B16
B
A17
B16
S
2,=F'1'
BETA
SR
2,4
AR
2,6
A19
SR
2,5
CR
2,5
BE
B18
B
A19
B18
S
2,=F'1'
&NAME

282

HLASM V1R5 Language Reference

&SYSNEST System Variable Symbol

Statement 7 is the 106th macro instruction processed. Therefore, &SYSNDX is

assigned the number 0106 for that macro instruction. The number 0106 is
substituted for &SYSNDX when it is used in statements 4 and 6. Statement 4 is
used to assign the character value 16 to the SETC symbol &NDXNUM Statement 6
is used to create the unique name B16.
Statement 5 is the 107th macro instruction processed. Therefore, &SYSNDX is
assigned the number 17 for that macro instruction. The number 17 is
substituted for &SYSNDX when it is used in statements 1 and 3. The number 16
is substituted for the global-scope SETC symbol &NDXNUM in statement 2.
Statement 8 is the 108th macro instruction processed. Therefore, each occurrence
of &SYSNDX is replaced by the number 18. For example, statement 6 is used to
create the unique name B18.
When statement 5 is used to process the 108th macro instruction, statement 5
becomes the 109th macro instruction processed. Therefore, each occurrence of
&SYSNDX is replaced by the number 19. For example, statement 1 is used to
create the unique name A19.

&SYSNEST System Variable Symbol

Use &SYSNEST to obtain the current macro instruction nesting level.
The local-scope system variable symbol &SYSNEST is assigned a read-only value
each time a macro definition is called from a source module.
The value assigned to &SYSNEST is a number from 1 to 99999999. No leading
zeros are generated as part of the number. When a macro is called from open
code, the value assigned to &SYSNEST is the number 1. Each time a macro
definition is called by an inner macro instruction, the value assigned to &SYSNEXT
is incremented by 1. Each time an inner macro exits, the value is decremented by
1.
Notes:
1. The value of the type attribute of &SYSNEST (T'&SYSNEST) is always N.
2. The value of the count attribute (K'&SYSNEST) is equal to the number of digits
assigned.
The following example shows the values assigned to &SYSNEST:

Chapter 7. How to Specify Macro Definitions

283

&SYSOPT_DBCS System Variable Symbol

MACRO
OUTER
DC
INNER1
INNER2
MEND
MACRO
INNER1
DC
INNER2
MEND

A(&SYSNEST)

Statement 1
Statement 2
Statement 3

A(&SYSNEST)

Statement 4
Statement 5

MACRO
INNER2
DC
A(&SYSNEST)
Statement 6
MEND
-------------------------------------------------------------------OUTER
Statement 7
+
DC
A(1)
+
DC
A(2)
+
DC
A(3)
+
DC
A(2)
Statement 7 is in open code. It calls the macro OUTER. &SYSNEST is assigned a
value of 1 which is substituted in statement 1.
Statement 2, within the macro definition of OUTER, calls macro INNER1. The value
assigned to &SYSNEST is incremented by 1. The value 2 is substituted for
&SYSNEST in statement 4.
Statement 5, within the macro definition of INNER1, calls macro INNER2. The value
assigned to &SYSNEST is incremented by 1. The value 3 is substituted for
&SYSNEST in statement 6.
When the macro INNER2 exits, the value assigned to &SYSNEST is decremented by
1. The value of &SYNEST is 2.
When the macro INNER1 exits, the value assigned to &SYSNEST is decremented by
1. The value of &SYSNEST is 1.
Statement 3, within the macro definition of OUTER, calls macro INNER2. The value
assigned to &SYSNEST is incremented by 1. The value 2 is substituted for
&SYSNEST in statement 6.

&SYSOPT_DBCS System Variable Symbol

You can use &SYSOPT_DBCS to determine if the DBCS assembler option was
supplied for the assembly of your source module. &SYSOPT_DBCS is a Boolean
system variable symbol, and has a global scope.
If the DBCS assembler option was specified, &SYSOPT_DBCS is assigned a value
of 1. If the DBCS assembler option was not specified, &SYSOPT_DBCS is
assigned a value of 0.

284

HLASM V1R5 Language Reference

&SYSOPT_OPTABLE System Variable Symbol

For more information about the DBCS assembler option, see the HLASM
Programmer's Guide.
Notes:
1. The value of the type attribute of &SYSOPT_DBCS (T'&SYSOPT_DBCS) is
always N.
2. The value of the count attribute (K'&SYSOPT_DBCS) is always 1.

&SYSOPT_OPTABLE System Variable Symbol

Use &SYSOPT_OPTABLE to determine the value that was specified for the
OPTABLE assembler option. &SYSOPT_OPTABLE has a global scope.
The value that was specified for the OPTABLE assembler option indicates which
operation code table the assembler has loaded, and is using.
For more information about the OPTABLE assembler option, see your HLASM
Programmer's Guide.
Notes:
1. The value of the type attribute of &SYSOPT_OPTABLE
(T'&SYSOPT_OPTABLE) is always U.
2. The value of the count attribute (K'&SYSOPT_OPTABLE) is the number of
characters assigned.

&SYSOPT_RENT System Variable Symbol

Use &SYSOPT_RENT to determine if the RENT assembler option was specified for
the assembly of your source module. The RENT option instructs the assembler to
check for possible coding violations of program reenterability. &SYSOPT_RENT is
a Boolean system variable symbol, and has a global scope.
If the RENT assembler option was specified, &SYSOPT_RENT is assigned a value
of 1. If the RENT assembler option was not specified, &SYSOPT_RENT is
assigned a value of 0.
For more information about the RENT assembler option, see your HLASM
Programmer's Guide.
Notes:
1. The value of the type attribute of &SYSOPT_RENT (T'&SYSOPT_RENT) is
always N.
2. The value of the count attribute (K'&SYSOPT_RENT) is always 1.

&SYSOPT_XOBJECT System Variable Symbol

The &SYSOPT_XOBJECT system variable is set to 1 if GOFF or XOBJECT is
specified, otherwise it is set to 0.
&SYSOPT_XOBJECT is a Boolean system variable symbol with global scope.

Chapter 7. How to Specify Macro Definitions

285

&SYSPARM System Variable Symbol

Notes:
1. The value of the type attribute of &SYSOPT_XOBJECT
(T'&SYSOPT_XOBJECT) is always N.
2. The value of the count attribute (K'&SYSOPT_XOBJECT) is always 1.

&SYSPARM System Variable Symbol

The &SYSPARM system variable is assigned a read-only value from the assembler
option SYSPARM. It is treated as a global-scope SETC symbol in a source module
except that its value cannot be changed. (Refer to chapter 3 of the Programmer's
Guide for information on assembler options.)
Notes:
1. The largest value that &SYSPARM can hold is 1024 characters. However, if
the PARM field of the EXEC statement is used to specify its value, the PARM
field restrictions reduce its maximum possible length.
2. No values are substituted for variable symbols in the specified value, however,
on MVS and VSE, you must use double ampersands to represent a single
ampersand.
3. On MVS and VSE, you must use two single quotation marks to represent a
single quotation mark, because the entire EXEC PARM field is enclosed in
single quotation marks.
4. If the SYSPARM assembler option is not specified, &SYSPARM is assigned the
default value that was specified when the assembler was installed on your
system.
If a default value for SYSPARM was not specified when the assembler was
installed on your system, &SYSPARM is assigned a value of the null character
string.
5. The value of the type attribute of &SYSPARM (T'&SYSPARM) is U, unless
&SYSPARM is assigned a null value, in which case the value of the type
attribute is O.
6. The value of the count attribute (K'&SYSPARM) is the number of characters
assigned as a value to &SYSPARM. If &SYSPARM is assigned a null character
string, the value of the count attribute is 0.
7. If the SYSPARM option is passed to the assembler via the ASMAOPT file
(CMS and MVS) or Librarian member (VSE) and the option contains imbedded
spaces, it must be enclosed in quotes.

&SYSPRINT_DSN System Variable Symbol

Use &SYSPRINT_DSN in a macro definition to obtain the name of the data set to
which the assembler writes the assembler listing.
The local-scope system variable symbol &SYSPRINT_DSN is assigned a read-only
value each time a macro definition is called.
When the assembler runs on the MVS operating systems, the value of the
character string assigned to &SYSPRINT_DSN is always the value stored in the
JFCB for SYSPRINT. If SYSPRINT is allocated to DUMMY, or a NULLFILE, the
value in &SYSPRINT_DSN is NULLFILE.

286

HLASM V1R5 Language Reference

&SYSPRINT_DSN System Variable Symbol

When the assembler runs on the CMS component of the VM operating systems,
the value of the character string assigned to &SYSPRINT_DSN is determined as
follows:
Figure 72. Contents of &SYSPRINT_DSN on CMS
SYSPRINT Allocated To:

Contents of &SYSPRINT_DSN:

CMS file

The 8-character filename, the

8-character filetype, and the
2-character filemode of the file, each
separated by a space

Dummy file (no physical I/O)

DUMMY

Printer

PRINTER

Labeled tape file

The data set name of the tape file

Unlabeled tape file

TAPn, where n is a value from 0 to 9,

or A to F.

Terminal

TERMINAL

When the assembler runs on VSE, the value of the character string assigned to
&SYSPRINT_DSN is determined as follows:
Figure 73. Contents of &SYSPRINT_DSN on VSE
SYSLST Assigned To:

Contents of &SYSPRINT_DSN:

Disk file (not for dynamic partitions)

The file-id

Printer

SYSLST

Labeled tape file

The file-id of the tape file

Unlabeled tape file

SYSLST

Examples:
On MVS, &SYSPRINT_DSN might be assigned a value such as:
IBMAPC.IBMAPCA.JOB6734.D12.?
On CMS, &SYSPRINT_DSN might be assigned a value such as:
SAMPLE

LISTING

Notes:
1. If the LISTING user exit provides the listing data set information then the value
in &SYSPRINT_DSN is the value extracted from the Exit-Specific Information
block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSPRINT_DSN (T'&SYSPRINT_DSN) is
always U.
3. The value of the count attribute of &SYSPRINT_DSN (K'&SYSPRINT_DSN) is
equal to the number of characters assigned as a value to &SYSPRINT_DSN.

Chapter 7. How to Specify Macro Definitions

287

&SYSPRINT_MEMBER System Variable Symbol

The value of &SYSPRINT_MEMBER is always null.
The value of the type attribute is O, and the value of the count attribute is 0.

You can use &SYSPRINT_MEMBER in a macro definition to obtain

the name of the data set member to which the assembler is writing the assembler
listing.
The local-scope system variable symbol &SYSPRINT_MEMBER is assigned a
read-only value each time a macro definition is called.
If the data set to which the assembler is writing the assembler listing is not an MVS
partitioned data set, &SYSPRINT_MEMBER is assigned a null character string.

Notes:
1. If the LISTING user exit provides the listing data set information then the value
in &SYSPRINT_MEMBER is the value extracted from the Exit-Specific
Information block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSPRINT_MEMBER
(T'&SYSPRINT_MEMBER) is U, unless &SYSPRINT_MEMBER is assigned a
null character string, in which case the value of the type attribute is O.
3. The value of the count attribute of &SYSPRINT_MEMBER
(K'&SYSPRINT_MEMBER) is equal to the number of characters assigned as a
value to &SYSPRINT_MEMBER. If &SYSPRINT_MEMBER is assigned a null
character string, the value of the count attribute is 0.

&SYSPRINT_VOLUME System Variable Symbol

Use &SYSPRINT_VOLUME in a macro definition to obtain the volume identifier of
the first volume containing the data set to which the assembler writes the
assembler listing.
The local-scope system variable symbol &SYSPRINT_VOLUME is assigned a
read-only value each time a macro definition is called.
If the assembler runs on the CMS component of the VM operating system, and the
assembler listing writes to a Shared File System CMS file, &SYSPRINT_VOLUME
is assigned the value SFS.
If the volume on which the data set resides is not labeled, &SYSPRINT_VOLUME
is assigned a null character string.
Notes:
1. If the LISTING user exit provides the listing data set information then the value
in &SYSPRINT_VOLUME is the value extracted from the Exit-Specific
Information block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSPRINT_VOLUME
(T'&SYSPRINT_VOLUME) is U, unless &SYSPRINT_VOLUME is assigned a
null character string, in which case the value of the type attribute is O.

288

HLASM V1R5 Language Reference

&SYSPUNCH_DSN System Variable Symbol

3. The value of the count attribute of &SYSPRINT_VOLUME

(K'&SYSPRINT_VOLUME) is equal to the number of characters assigned as a
value to &SYSPRINT_VOLUME. If &SYSPRINT_VOLUME is assigned a null
character string, the value of the count attribute is 0. The maximum length of
this system variable symbol is 6.

&SYSPUNCH_DSN System Variable Symbol

Use &SYSPUNCH_DSN in a macro definition to obtain the name of the data set to
which the assembler is writing the object records when assembler option DECK is
specified.
The local-scope system variable symbol &SYSPUNCH_DSN is assigned a
read-only value each time a macro definition is called.
When the assembler runs on the MVS operating systems, the value of the
character string assigned to &SYSPUNCH_DSN is always the value stored in the
JFCB for SYSPUNCH. If SYSPUNCH is allocated to DUMMY, or a NULLFILE, the
value in &SYSPUNCH_DSN is NULLFILE.
When the assembler runs on the CMS component of the VM operating systems,
the value of the character string assigned to &SYSPUNCH_DSN is determined as
follows:
Figure 74. Contents of &SYSPUNCH_DSN on CMS
SYSPUNCH Allocated To:

Contents of &SYSPUNCH_DSN:

CMS file

The 8-character filename, the

8-character filetype, and the
2-character filemode of the file, each
separated by a space

Dummy file (no physical I/O)

DUMMY

Punch

PUNCH

Labeled tape file

The data set name of the tape file

Unlabeled tape file

TAPn, where n is a value from 0 to 9,

or A to F.

On VSE, the value of the character string assigned to &SYSPUNCH_DSN is

determined as follows:
Figure 75. Contents of &SYSPUNCH_DSN on VSE
SYSPCH Assigned To:

Contents of &SYSPUNCH_DSN:

Disk file

The file-id

Punch

SYSPCH

Labeled tape file

The file-id of the tape file

Unlabeled tape file

SYSPCH

Examples:
On MVS, &SYSPUNCH_DSN might be assigned a value such as:
IBMAPC.IBMAPCA.JOB6734.D13.?
Chapter 7. How to Specify Macro Definitions

289

&SYSPUNCH_MEMBER System Variable Symbol

On CMS, &SYSPUNCH_DSN might be assigned a value such as:

PUNCH
Notes:
1. If the PUNCH user exit provides the punch data set information then the value
in &SYSPUNCH_DSN is the value extracted from the Exit-Specific Information
block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSPUNCH_DSN (T'&SYSPUNCH_DSN)
is always U.
3. The value of the count attribute of &SYSPUNCH_DSN (K'&SYSPUNCH_DSN)
is equal to the number of characters assigned as a value to
&SYSPUNCH_DSN.

&SYSPUNCH_MEMBER System Variable Symbol

The value of &SYSPUNCH_MEMBER is always null.
The value of the type attribute is O, and the value of the count attribute is 0.

You can use &SYSPUNCH_MEMBER in a macro definition to obtain

the name of the data set member to which the assembler is writing the object
records when the assembler option DECK is specified.
The local system variable symbol &SYSPUNCH_MEMBER is assigned a read-only
value each time a macro definition is called.
If the data set to which the assembler is writing the object records is not an MVS
partitioned data set, &SYSPUNCH_MEMBER is assigned a null character string.

Notes:
1. If the PUNCH user exit provides the punch data set information then the value
in &SYSPUNCH_MEMBER is the value extracted from the Exit-Specific
Information block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSPUNCH_MEMBER
(T'&SYSPUNCH_MEMBER) is U, unless &SYSPUNCH_MEMBER is assigned
a null character string, in which case the value of the type attribute is O.
3. The value of the count attribute of &SYSPUNCH_MEMBER
(K'&SYSPUNCH_MEMBER) is equal to the number of characters assigned as
a value to &SYSPUNCH_MEMBER. If &SYSPUNCH_MEMBER is assigned a
null character string, the value of the count attribute is 0.

&SYSPUNCH_VOLUME System Variable Symbol

Use &SYSPUNCH_VOLUME in a macro definition to obtain the volume identifier of
the object data set. The volume identifier is of the first volume containing the data
set. &SYSPUNCH_VOLUME is only assigned a value when you specify the DECK
assembler option.
The local-scope system variable symbol &SYSPUNCH_VOLUME is assigned a
read-only value each time a macro definition is called.

290

HLASM V1R5 Language Reference

&SYSSEQF System Variable Symbol

If the assembler runs on the CMS component of the VM operating system, and the
object records are being written to a Shared File System CMS file,
&SYSPUNCH_VOLUME is assigned the value SFS.
If the volume on which the data set resides is not labeled, &SYSPUNCH_VOLUME
is assigned a null character string.
Notes:
1. If the PUNCH user exit provides the punch data set information then the value
in &SYSPUNCH_VOLUME is the value extracted from the Exit-Specific
Information block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSPUNCH_VOLUME
(T'&SYSPUNCH_VOLUME) is U, unless &SYSPUNCH_VOLUME is assigned
a null character string, in which case the value of the type attribute is O.
3. The value of the count attribute of &SYSPUNCH_VOLUME
(K'&SYSPUNCH_VOLUME) is equal to the number of characters assigned as
a value to &SYSPUNCH_VOLUME. If &SYSPUNCH_VOLUME is assigned a
null character string, the value of the count attribute is 0. The maximum length
of this system variable symbol is 6.

&SYSSEQF System Variable Symbol

Use &SYSSEQF in a macro definition to obtain the value of the
identification-sequence field of the macro instruction in open code that caused,
directly or indirectly, the macro to be called.
The local-scope system variable symbol &SYSSEQF is assigned a read-only value
each time a macro definition is called from a source module.
The value assigned to &SYSSEQF is determined as follows:
1. If no ICTL instruction has been specified and sequence checking is not active,
the contents of columns 73 to 80 inclusive of the source statement are
assigned to &SYSSEQF.
2. If an ICTL instruction has been specified, but sequence checking is not active,
the contents of the columns of the source statement to the right of the
continuation-indicator column are assigned to &SYSSEQF. If the end column or
the continuation-indicator column is 80, &SYSSEQF is assigned a null
character string.
3. If an ISEQ instruction with operands has been specified to start sequence
checking, the contents of columns specified in the ISEQ instruction operand are
assigned to &SYSSEQF.
4. If an ISEQ instruction without an operand has been specified to end sequence
checking, steps (1) and (2) are used to determine the value assigned to
&SYSSEQF.

Chapter 7. How to Specify Macro Definitions

291

&SYSSTEP System Variable Symbol

Notes:
1. The value of the type attribute of &SYSSEQF (T'&SYSSEQF) is U, unless
&SYSSEQF is assigned a null character string, in which case the value of the
type attribute is O.
2. The value of the count attribute of &SYSSEQF (K'&SYSSEQF) is equal to the
number of characters assigned as a value to &SYSSEQF. If &SYSSEQF is
assigned a null character string, the value of the count attribute is 0.
3. Throughout the use of a macro definition, the value of &SYSSEQF is
considered a constant.

&SYSSTEP System Variable Symbol

Use &SYSSTEP to obtain the stepname of the job step used to assemble your
source module. &SYSSTEP has a global scope.
On CMS and VSE the value of &SYSSTEP is always (NOSTEP).
Notes:
1. The value of the type attribute of &SYSSTEP (T'&SYSSTEP) is always U.
2. The value of the count attribute (K'&SYSSTEP) is the number of characters
assigned.

&SYSSTMT System Variable Symbol

Use &SYSSTMT to obtain the next statement number that is assigned to a
statement by the assembler. &SYSSTMT has a global scope.
The value assigned to &SYSSTMT is an 8-character string, padded on the left with
leading zero (X'F0') characters. The following example shows the value assigned
to &SYSSTMT. It assumes that the DC statement is in open code, and is the 23rd
statement in the source module.
23
+

DC
DC

C'&SYSSTMT'
C'24'

Notes:
1. The value of the type attribute of &SYSSTMT (T'&SYSSTMT) is always N.
2. The value of the count attribute of &SYSSTMT (K'&SYSSTMT) is always 8.

&SYSSTYP System Variable Symbol

Use &SYSSTYP in a macro definition to generate the type of the current control
section. The current control section is the control section in which the macro
instruction that calls the definition appears.
The local-scope system variable symbol &SYSSTYP is assigned a read-only value
each time a macro definition is called.
The value assigned is the symbol that represents the type of the current control
section in effect when the macro is called. A control section that has been initiated
or continued by substitution does not affect the value of &SYSSTYP for the
expansion of the current macro. However, it does affect &SYSSTYP for a
subsequent macro call. Nested macros cause the assembler to assign a value to

292

HLASM V1R5 Language Reference

&SYSTEM_ID System Variable Symbol

&SYSSTYP that depends on the control section in force inside the calling macro
when the inner macro is called.
The control section whose type is assigned to &SYSSTYP can be defined by a
program sectioning statement. This can be a START, CSECT, RSECT, DSECT, or
COM statement, or, for the first control section, any instruction described in First
Section on page 54. Depending upon the instruction used to initiate the current
control section, the value assigned to &SYSSTYP is either CSECT, RSECT,
DSECT, or COM. If the current control section is an executable control section
initiated by other than a CSECT or RSECT instruction, the value assigned to
&SYSSTYP is CSECT.
If a control section has not been initiated, &SYSSTYP is assigned a null character
string.
Notes:
1. The value of the type attribute of &SYSSTYP (T'&SYSSTYP) is U, unless
&SYSSTYP is assigned a null character string, in which case the value of the
type attribute is O.
2. The value of the count attribute of &SYSSTYP (K'&SYSSTYP) is equal to the
number of characters assigned as a value to &SYSSTYP. If &SYSSTYP is
assigned a null character string, the value of the count attribute is 0.
3. Throughout the use of a macro definition, the value of &SYSSTYP is
considered a constant.

&SYSTEM_ID System Variable Symbol

Use &SYSTEM_ID to obtain the name and release of the operating system under
which your source module is being assembled. &SYSTEM_ID has a global scope.
For example, on MVS, &SYSTEM_ID might contain one of the following:
z/OS 1.4.
z/OS 1.5.
... etc.
on CMS, &SYSTEM_ID might contain one of the following:
CMS 18
CMS 19
... etc.
on VSE, &SYSTEM_ID might contain one of the following:
VSE/AF 6.6.
... etc.
Notes:
1. The value of the type attribute of &SYSTEM_ID (T'&SYSTEM_ID) is always U.
2. The value of the count attribute (K'&SYSTEM_ID) is the number of characters
assigned.

Chapter 7. How to Specify Macro Definitions

293

&SYSTERM_DSN System Variable Symbol

Use &SYSTERM_DSN in a macro definition to obtain the name of the data set to
which the assembler is writing the terminal records.
The local-scope system variable symbol &SYSTERM_DSN is assigned a read-only
value each time a macro definition is called.
When the assembler runs on the MVS operating systems, the value of the
character string assigned to &SYSTERM_DSN is always the value stored in the
JFCB for SYSTERM. If SYSTERM is allocated to DUMMY, or a NULLFILE, the
value in &SYSTERM_DSN is NULLFILE.
When the assembler runs on the CMS component of the VM operating systems,
the value of the character string assigned to &SYSTERM_DSN is determined as
follows:
Figure 76. Contents of &SYSTERM_DSN on CMS
SYSTERM Allocated To:

Contents of &SYSTERM_DSN:

CMS file

The 8-character filename, the

8-character filetype, and the
2-character filemode of the file, each
separated by a space

Dummy file (no physical I/O)

DUMMY

Printer

PRINTER

Labeled tape file

The data set name of the tape file

Unlabeled tape file

TAPn, where n is a value from 0 to 9,

or A to F.

Terminal

TERMINAL

On VSE, the value of the character string assigned to &SYSTERM_DSN is always

SYSLOG.
Examples:
On MVS, &SYSTERM_DSN might be assigned a value such as:
IBMAPC.IBMAPCA.JOB6734.D14.?
On CMS, &SYSTERM_DSN might be assigned a value such as:
TERMINAL
Notes:
1. If the TERM user exit provides the terminal data set information then the value
in &SYSTERM_DSN is the value extracted from the Exit-Specific Information
block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSTERM_DSN (T'&SYSTERM_DSN) is
always U.
3. The value of the count attribute of &SYSTERM_DSN (K'&SYSTERM_DSN) is
equal to the number of characters assigned as a value to &SYSTERM_DSN.

294

HLASM V1R5 Language Reference

&SYSTERM_VOLUME System Variable Symbol

&SYSTERM_MEMBER System Variable Symbol

The value of &SYSTERM_MEMBER is always null.
The value of the type attribute is O, and the value of the count attribute is 0.

You can use &SYSTERM_MEMBER in a macro definition to obtain

the name of the data set member to which the assembler is writing the terminal
records.
The local-scope system variable symbol &SYSTERM_MEMBER is assigned a
read-only value each time a macro definition is called.
If the data set to which the assembler is writing the terminal records is not an MVS
partitioned data set, &SYSTERM_MEMBER is assigned a null character string.

Notes:
1. If the TERM user exit provides the terminal data set information then the value
in &SYSTERM_MEMBER is the value extracted from the Exit-Specific
Information block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSTERM_MEMBER
(T'&SYSTERM_MEMBER) is U, unless &SYSTERM_MEMBER is assigned a
null character string, in which case the value of the type attribute is O.
3. The value of the count attribute of &SYSTERM_MEMBER
(K'&SYSTERM_MEMBER) is equal to the number of characters assigned as a
value to &SYSTERM_MEMBER. If &SYSTERM_MEMBER is assigned a null
character string, the value of the count attribute is 0.

&SYSTERM_VOLUME System Variable Symbol

The value of &SYSTERM_VOLUME is always null.
The value of the type attribute is U, and the value of the count attribute is 0.

You can use &SYSTERM_VOLUME in a macro definition to obtain the

volume identifier of the first volume containing the data set to which the assembler
is writing the terminal records.
The local-scope system variable symbol &SYSTERM_VOLUME is assigned a
read-only value each time a macro definition is called.
If the assembler runs on the CMS component of the VM operating system, and the
terminal records are being written to a Shared File System CMS file,
&SYSTERM_VOLUME is assigned the value SFS.
If the volume on which the data set resides is not labeled, &SYSTERM_VOLUME is
assigned a null character string.

Chapter 7. How to Specify Macro Definitions

295

&SYSTIME System Variable Symbol

Notes:
1. If the TERM user exit provides the terminal data set information then the value
in &SYSTERM_VOLUME is the value extracted from the Exit-Specific
Information block described in the HLASM Programmer's Guide.
2. The value of the type attribute of &SYSTERM_VOLUME
(T'&SYSTERM_VOLUME) is U, unless &SYSTERM_VOLUME is assigned a
null character string, in which case the value of the type attribute is O.
3. The value of the count attribute of &SYSTERM_VOLUME
(K'&SYSTERM_VOLUME) is equal to the number of characters assigned as a
value to &SYSTERM_VOLUME. If &SYSTERM_VOLUME is assigned a null
character string, the value of the count attribute is 0. The maximum length of
this system variable symbol is 6.

&SYSTIME System Variable Symbol

Use &SYSTIME to obtain the time at which your source module is assembled. It
has local scope, but can be used in open code. It is assigned a read-only value.
The value of &SYSTIME is a 5-character string in the format:
HH.MM
where:
HH

is two-digit field that gives the hour of the day. It has a value between 00
and 23, inclusive.

is two-digit field that gives the minute of the hour. It has a value between 00
and 59, inclusive. It is separated from HH by a period.

Example:
9.45
Notes:
1. The time corresponds to the time printed in the page heading of listings and
remains constant for each assembly.
2. The value of the type attribute of &SYSTIME (T'&SYSTIME) is always U.
3. The value of the count attribute (K'&SYSTIME) is always 5.

&SYSVER System Variable Symbol

Use &SYSVER to obtain the version, release, and modification level of the
assembler being used to assemble your source module. &SYSVER has a global
scope. For example, when IBM High Level Assembler for MVS & VM & VSE
Release 5.0 is used, &SYSVER has the value 1.5.0.
Notes:
1. The value of the type attribute of &SYSVER (T'&SYSVER) is always U.
2. The value of the count attribute (K'&SYSVER) is the number of characters
assigned. In the above example, the count attribute of &SYSVER is 5.

296

HLASM V1R5 Language Reference

How to Write Macro Instructions

Chapter 8. How to Write Macro Instructions

This chapter describes macro instructions; where you can use them and how you
specify them.
The first section on page 297 describes the macro instruction format, including
details on the name, operation, and operand entries, and what is generated as a
result of a macro instruction.
Sublists in Operands on page 304 describes how you can use sublists to specify
several values in an operand entry.
Values in Operands on page 307 describes the values you can specify in an
operand entry when you call a macro definition.
Nesting Macro Instruction Definitions on page 311 describes how you can use
nested macro call instructions to call macros from within a macro.
What is a Macro Instruction: The macro instruction provides the assembler with:
The name of the macro definition to process
The information or values to pass to the macro definition
This information is the input to a macro definition. The assembler uses the
information either in processing the macro definition, or for substituting values into
model statements in the definition.
The output from a macro definition can be:
A sequence of statements generated from the model statements of the macro
for further processing at assembly time.
Values assigned to global-scope SET symbols. These values can be used in
other macro definitions and in open code (see SET Symbols on page 319).
Where Macro Instructions Can Appear: A macro instruction can be written
anywhere in your program, provided the assembler can find the macro definition.
The macro definition can be found either in a macro library, or in the source
program before the macro instruction, or be provided by a LIBRARY user exit.
However, the statements generated from the called macro definition must be valid
assembler language instructions and allowed where the calling macro instruction
appears.

Macro Instruction Format

operation_code
name_field
,
operand
sequence_symbol

name_field
is a special positional operand that can be used to pass a value into the called
macro definition. For a detailed description of what form name_entry can take,
see Name Entry on page 299.
Copyright IBM Corp. 1982, 2004

297

Macro Instruction Format

sequence_symbol
is a sequence symbol. If a sequence symbol is coded in the name entry of a
macro instruction, the value of the symbol is not passed to the called macro
definition and therefore cannot be used as a value for substitution in the macro
definition.
operation_code
is the symbolic operation code which identifies the macro definition that you
want the assembler to process. For more information, see Operation Entry on
page 299.
operand
The positional operands or keyword operands that you use to pass values into
the called macro definition. For more information, see Operand Entry on
page 300.
If no operands are specified in the operand field, and if the absence of the operand
entry is indicated by a comma preceded and followed by one or more spaces,
remarks are allowed.
The entries in the name, operation, and operand fields correspond to entries in the
prototype statement of the called macro definition (see Macro Instruction
Prototype on page 245).

Alternative Formats for a Macro Instruction

A macro instruction can be specified in one of the three following ways:
The normal way, with the operands preceding any remarks
The alternative way, allowing remarks for each operand
A combination of the first two ways
The following example show the normal statement format (NAME1), the alternative
statement format (NAME2), and a combination of both statement formats (NAME3).
Name

Operation
Operand

NAME1

OP1

OPERAND1,OPERAND2,OPERAND3

This is the normal

statement format

NAME2

OP2

OPERAND1,
OPERAND2

This is the alternative statement format

NAME3

OP3

OPERAND1,
OPERAND2,OPERAND3

This is a combination
of both

Comment

Cont.

Notes:
1. Any number of continuation lines are allowed. However, each continuation line
must be indicated by a non-space character in the column after the end column
of the previous statement line (see Continuation Lines on page 15).
2. If the DBCS assembler option is specified, the continuation features outlined in
Continuation of double-byte data on page 16 apply to continuation in the
macro language. Extended continuation may be useful if a macro operand
contains double-byte data.

298

HLASM V1R5 Language Reference

Macro Instruction Format

3. Operands on continuation lines must begin in the continue column (column 16),
or the assembler assumes that the current line and any lines that follow contain
remarks.
If any entries are made in the columns before the continue column in
continuation lines, the assembler issues an error message and the whole
statement is not processed.
4. One or more spaces must separate the operand from the remarks.
5. A comma after an operand indicates more operands follow.
6. The last operand requires no comma following it, but using a comma does not
cause an error.
7. You do not need to use the same format when you code a macro instruction as
you use when you code the corresponding macro prototype statement.
8. Continued comments for a macro with an operand list that terminates in a null
operand will be recognized provided each continued comment begins in the
same or later column as the preceding line's comment.

Name Entry
Use the name entry of a macro instruction to:
Pass a value into a macro definition through the name entry declared in the
macro definition
Provide a conditional assembly label (see Sequence Symbols on page 339)
so that you can branch to the macro instruction during conditional assembly if
you want the called macro definition expanded.
The name entry of a macro instruction can be:
Space
An ordinary symbol, such as HERE
A variable symbol, such as &A.
Any combination of variable symbols and other character strings concatenated
together, such as HERE.&A
Any character string allowed in a macro instruction operand, such as 'Now is
the hour' or STRING, excluding sublist entries and certain attribute references
(see Values in Operands on page 307)
A sequence symbol, which is not passed to the macro definition, such as .SEQ

Operation Entry
The operation entry is the symbolic name of the operation code that identifies a
macro definition to process.
The operation entry must be a valid symbol, and must be identical to the operation
field in the prototype statement of the macro definition.
The assembler searches for source macro definitions before library macro
definitions. If you have a source macro definition that has the same name as a
library macro definition, the assembler only processes the source macro definition.

Chapter 8. How to Write Macro Instructions

299

Macro Instruction Format

You can use a variable symbol as a macro instruction. For example if MAC1 has
been defined as a macro, you can use the following statements to call it:
&CALL

SETC
&CALL

'MAC1'

You cannot use a variable symbol as a macro instruction that passes operands to
the macro. The second statement in the following example generates an error:
&CALL

SETC
&CALL

'MAC1 OPERAND1=VALUE'

You must specify operand entries after the variable symbol, as shown in the
following example:
&CALL

SETC
'MAC1'
&CALL OPERAND1=VALUE

Operand Entry
Use the operand entry of a macro instruction to pass values into the called macro
definition. These values can be passed through:
The symbolic parameters you have specified in the macro prototype, or
The system variable symbol &SYSLIST if it is specified in the body of the
macro definition (see &SYSLIST System Variable Symbol on page 276).
The two types of operands allowed in a macro instruction are positional and
keyword operands. You can specify a sublist with multiple values in both types of
operands. Special rules for the various values you can specify in operands are
also given below.

Positional Operands
You can use a positional operand to pass a value into a macro definition through
the corresponding positional parameter declared for the definition. You should
declare a positional parameter in a macro definition when you want to change the
value passed at every call to that macro definition.
You can also use a positional operand to pass a value to the system variable
symbol &SYSLIST. If &SYSLIST, with the applicable subscripts, is specified in a
macro definition, you do not need to declare positional parameters in the prototype
statement of the macro definition. You can thus use &SYSLIST to refer to any
positional operand. This allows you to vary the number of operands you specify
each time you call the same macro definition.
The positional operands of a macro instruction must be specified in the same order
as the positional parameters declared in the called macro definition.
Each positional operand constitutes a character string. This character string is the
value passed through a positional parameter into a macro definition.
The specification for each positional parameter in the prototype statement definition
must be a valid variable symbol. Values are assigned (see 1 in Figure 77 on
page 301) to the positional operands by the corresponding positional arguments
(see 2 in Figure 77) specified in the macro instruction that calls the macro
definition.

300

HLASM V1R5 Language Reference

Macro Instruction Format

Source Module

Macro

MACRO

Definition

POSPAR
&POS1,&POS2,&POS3

MEND

.
1 1 1

START

Macro

POSPAR
ONE,TWO,THREE
2
Instruction
.

END

Figure 77. Positional Operands

Notes:
1. An omitted operand has a null character value.
|

2. Each positional operand can be up to 1024 characters long.

3. If the DBCS assembler option is specified, the positional operand can be a
string containing double-byte data. The string need not be quoted.
The following are examples of macro instructions with positional operands:
MACCALL
MACCALL
MACCALL
MACCALL
MACCALL

VALUE,9,8
&A,'QUOTED STRING'
EXPR+2,,SYMBOL
(A,B,C,D,E),(1,2,3,4)
&A,'<.S.T.R.I.N.G>'

The following list shows what happens when the number of positional operands in
the macro instruction is equal to or differs from the number of positional parameters
declared in the prototype statement of the called macro definition:
Equal

Valid, if operands are correctly specified.

Greater than

Meaningless, unless &SYSLIST is specified in definition to refer to

excess operands.

Less than

Omitted operands give null character values to corresponding

parameters (or &SYSLIST specification).

Keyword Operands
You can use a keyword operand to pass a value through a keyword parameter into
a macro definition. The values you specify in keyword operands override the
default values assigned to the keyword parameters. The default value should be a
value you use frequently. Thus, you avoid having to write this value every time you
code the calling macro instruction.

Chapter 8. How to Write Macro Instructions

301

Macro Instruction Format

When you need to change the default value, you must use the corresponding
keyword operand in the macro instruction. The keyword can indicate the purpose
for which the passed value is used.
Any keyword operand specified in a macro instruction must correspond to a
keyword parameter in the macro definition called. However, keyword operands do
not have to be specified in any particular order.
The general specifications for symbolic parameters also apply to keyword
operands. The actual operand keyword must be a valid variable symbol. A null
character string can be specified as the standard value of a keyword operand, and
is generated if the corresponding keyword operand is omitted.
A keyword operand must be coded in this format:
KEYWORD=VALUE
where:
KEYWORD has up to 62 characters without an ampersand.
VALUE
can be up to 1024 characters.

The corresponding keyword parameter in the called macro definition is specified as:
&KEYWORD=DEFAULT
If a keyword operand is specified, its value overrides the default value specified for
the corresponding keyword parameter.
If the DBCS assembler option is specified, the keyword operand can be a string
containing double-byte data. The string need not be quoted.
If the value of a keyword operand is a literal, two equal signs must be specified.
The following examples of macro instructions have keyword operands:
MACKEY
MACKEY
MACKEY
MACKEY
MACKEY

KEYWORD=(A,B,C,D,E)
KEY1=1,KEY2=2,KEY3=3
KEY3=2,KEY1=,KEYWORD=HALLO
KEYWORD='<.S.T.R.I.N.G>'
KEYWORD==C'STRING'

To summarize the relationship of keyword operands to keyword parameters:

The keyword of the operand corresponds (see 1 in Figure 78 on page 303)
to a keyword parameter. The value in the operand overrides the default value
of the parameter.
If the keyword operand is not specified (see 2 in Figure 78), the default value
of the parameter is used.
If the keyword of the operand does not correspond (see 3 in Figure 78) to
any keyword parameter, the assembler issues an error message, but the macro
is generated using the default values of the other parameters.
The default value specified for a keyword parameter can be the null character
string (see 4 in Figure 78). The null character string is a character string
with a length of zero; it is not a space, because a space occupies one
character position.

302

HLASM V1R5 Language Reference

Macro Instruction Format

4 Null character string

is default value
MACRO

MACCORR &KEY1=DEFAULT,&KEY2=,&KEY3=123
.
.
DC
C'&KEY1&KEY2&KEY3'
.
.
MEND

OPEN
START
.
.
1
1
1
MACCOOR KEY1=OVERRIDE,KEY2=,KEY3=456
.

+
DC
C'OVERRIDE456'

.
MACCOOR 2
.
KEY2 has null character
.

string as default
.

+
DC
C'DEFAULT123'
.
.
.
3
MACCOOR
KEY4=SYMBOL,KEY2=
ASMA17W WARNING Undefined keyword parameter . . .
.
.
.
+
DC
C'DEFAULT123'
.
.
.
MACCOOR
KEY1=,KEY3=456
.
KEY1 parameter has null
.

character string value

.

KEY2 has null character
+
DC
C'456'
string as default
END
Figure 78. Relationship between Keyword Operands and Keyword Parameters and Their
Assigned Values

Combining Positional and Keyword Operands

You can use positional and keyword operands in the same macro instruction. Use
a positional operand for a value that you change often, and a keyword operand for
a value that you change infrequently.
Positional and keyword parameters can be mixed freely in the macro prototype
statement (see 1 in Figure 79). The same applies to the positional and keyword
operands of the macro instruction (see 2 in Figure 79). Note, however, that the
order in which the positional parameters appear (see 3 in Figure 79) determines

Chapter 8. How to Write Macro Instructions

303

Sublists in Operands

the order in which the positional operands must appear. Interspersed keyword
parameters and operands (see 4 in Figure 79) do not affect this order.
4

MACRO

1
MIX
&P1,&KEY1=A,&P2,&P3,&P4,&KEY2=,&P5
.

3
.
.
MEND

START
.
.
.

3
2
MIX
KEY1=B,ONE,TWO,THREE,KEY2=33,FOUR,FIVE
.

.

.
4
END
Figure 79. Combining Positional and Keyword Parameters

&SYSLIST( n): The system variable symbol &SYSLIST(n) refers only to the
positional operands in a macro instruction.

Sublists in Operands
You can use a sublist in a positional or keyword operand to specify several values.
A sublist is a character string that consists of one or more entries separated by
commas and enclosed in parentheses.
If the COMPAT(SYSLIST) assembler option is not specified, a variable symbol that
has been assigned a character string that consists of one or more entries
separated by commas and enclosed in parentheses is also treated as a sublist.
However, if the COMPAT(SYSLIST) assembler option is specified, a sublist
assigned to a variable symbol is treated as a character string, not as a sublist.
A variable symbol is not treated as a sublist if the parentheses are not present.
The following example shows two calls to macro MAC1. In the first call, the value of
the operand in variable &VAR1 is treated as a sublist. In the second call, the value
of the operand is treated as a character string, not a sublist, because the variable
&VAR2 does not include parentheses.
&VAR1
&VAR2

SETC
MAC1
SETC
MAC1

'(1,2)'
KEY=&VAR1
'1,2'
KEY=(&VAR2)

To refer to an entry of a sublist code, use:

The corresponding symbolic parameter with an applicable subscript, or
The system variable symbol &SYSLIST with applicable subscripts, the first of
which refers to the positional operand, and the second to the sublist entry in
the operand. &SYSLIST can refer only to sublists in positional operands.

304

HLASM V1R5 Language Reference

Sublists in Operands

Figure 80 on page 305 shows that the value specified in a positional or keyword
operand can be a sublist.
A symbolic parameter can refer to the whole sublist (see 1 in Figure 80), or to an
individual entry of the sublist. To refer to an individual entry, the symbolic
parameter (see 2 in Figure 80) must have a subscript whose value indicates the
position (see 3 in Figure 80) of the entry in the sublist. The subscript must have
a value greater than or equal to 1.
|

A sublist, including the enclosing parentheses, must not contain more than 1024
characters. It consists of one or more entries separated by commas and enclosed
in parentheses; for example, (A,B,C,D,E). () is a valid sublist with the null
character string as the only entry.

MACRO
SUBLISTS &P1,&P2,&KEY=(F,F,)
.

Refers to default value
.
3
in keyword operand
.

&KEY(1) DC
&KEY(2)'&KEY(3)'
.
.
3
Refers to value in
&P1(1)
DC
&P1(2)'&P1(3)'

positional operand
.
2

DC
A&P2

.
1

MEND

OPEN
START

SUBLISTS (H2,H,2),(A,B,C)

.
+F
DC
F''
.
.
+H2
DC
H'2'
.
.
+
DC
A(A,B,C)
.
.
END
Figure 80. Sublists in Operands

Figure 81 shows the relationship between subscripted parameters and sublist

entries if:

A sublist entry is omitted (see 1 in Figure 81).

The subscript refers past the end of the sublist (see 2 in Figure 81).
The value of the operand is not a sublist (see 3 in Figure 81).
The parameter is not subscripted (see 4 in Figure 81).

Chapter 8. How to Write Macro Instructions

305

Sublists in Operands

&SYSLIST( n,m): The system variable symbol, &SYSLIST(n,m), can also refer to
sublist entries, but only if the sublist is specified in a positional operand.
Figure 81. Relationship between Subscripted Parameters and Sublist Entries

Parameter

Sublist specified in
corresponding operand
or as default value
of a keyword parameter

Value generated or
used in computation

1 &PARM1(3)

(1,2,,4)

Null character string

2 &PARM1(5)

(1,2,3,4)

Null character string

&PARM1
3 &PARM1(1)
&PARM1(2)

A
A
A

A
A
Null character string

4 &PARM1
&PARM1(1)
2 &PARM1(2)

(A)
(A)
(A)

(A)
A
Null character string

&PARM1
&PARM1(1)
&PARM1(2)

()
()
()

()
Null character string
Null character string

&PARM1(2)

(A, ,C,D)

Nothing

&PARM1(1)

( )

Nothing

&PARM1
&PARM2(3)
&SYSLIST(2,3)

A,(1,2,3,4)
A,(1,2,3,4)
A,(1,2,3,4)

A
3
3

Notes:
1. Considered a sublist.
2. The space indicates the end of the operand field.
3. Produces error diagnostic message ASMA88E Unbalanced parentheses in
macro call operand.
4. Positional operands.

Multilevel Sublists
You can specify multilevel sublists (sublists within sublists) in macro operands. The
depth of this nesting is limited only by the constraint that the total operand length
must not exceed 1024 characters. Inner elements of the sublists are referenced
using additional subscripts on symbolic parameters or on &SYSLIST.

N'&SYSLIST(n) gives the number of operands in the indicated n-th level sublist.
The number attribute (N') and a parameter name with an n-element subscript array
gives the number of operands in the indicated (n+1)-th operand sublist. Figure 82
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).

306

HLASM V1R5 Language Reference

Values in Operands

Figure 82. Multilevel Sublists

Selected Elements
from &P

Selected Elements
from &SYSLIST

Value of
Selected Element

&P
&P(1)
&P(2)
&P(2,1)
&P(2,2)
&P(2,2,1)
&P(2,2,2)
N'&P(2,2)
N'&P(2)
N'&P(3)
N'&P

&SYSLIST(1)
&SYSLIST(1,1)
&SYSLIST(1,2)
&SYSLIST(1,2,1)
&SYSLIST(1,2,2)
&SYSLIST(1,2,2,1)
&SYSLIST(1,2,2,2)
N'&SYSLIST(1,2,2)
N'&SYSLIST(1,2)
N'&SYSLIST(1,3)
N'&SYSLIST(1)

(A,(B,(C)),D)
A
(B,(C))
B
(C)
C
null
1
2
1
3

Passing Sublists to Inner Macro Instructions

You can pass a suboperand of an outer macro instruction sublist as a sublist to an
inner macro instruction. However, if you specify the COMPAT(SYSLIST) assembler
option, a sublist assigned to a variable symbol is treated as a character string, not
as a sublist.

Values in Operands
You can use a macro instruction operand to pass a value into the called macro
definition. The two types of value you can pass are:
Explicit values or the actual character strings you specify in the operand
Implicit values, or the attributes inherent in the data represented by the explicit
values
The explicit value specified in a macro instruction operand is a character string that
can contain zero or more variable symbols.
|

The character string must not be greater than 1024 characters after substitution of
values for any variable symbols. This includes a character string that constitutes a
sublist.
The character string values in the operands, including sublist entries, are assigned
to the corresponding parameters declared in the prototype statement of the called
macro definition. A sublist entry is assigned to the corresponding subscripted
parameter.

Omitted Operands
When a keyword operand is omitted, the default value specified for the
corresponding keyword parameter is the value assigned to the parameter. When a
positional operand or sublist entry is omitted, the null character string is assigned to
the parameter.

Chapter 8. How to Write Macro Instructions

307

Values in Operands

Notes:
1. Spaces appearing between commas (without surrounding single quotation
marks) do not signify an omitted positional operand or an omitted sublist entry;
they indicate the end of the operand field.
2. Adjacent commas indicate omission of positional operands; no comma is
needed to indicate omission of the last or only positional operand.
The following example shows a macro instruction preceded by its corresponding
prototype statement. The macro instruction operands that correspond to the third
and sixth operands of the prototype statement are omitted in this example.
EXAMPLE
EXAMPLE

&A,&B,&C,&D,&E,&F
17,+4,,AREA,FIELD(6)

macro prototype
macro instruction

Unquoted Operands
The assembler normally retains the case of unquoted macro operands. However,
to maintain uppercase alphabetic character set compatibility with earlier
assemblers, High Level Assembler provides the COMPAT(MACROCASE)
assembler option. When you specify this option, the assembler internally converts
lowercase alphabetic characters (a through z) in unquoted macro instruction
operands to uppercase alphabetic characters (A though Z), before macro expansion
begins.

Special Characters
Any of the 256 characters of the EBCDIC character set can appear in the value of
a macro instruction operand (or sublist entry). However, the following characters
require special consideration:

Ampersands
A single ampersand indicates the presence of a variable symbol. The assembler
substitutes the value of the variable symbol into the character string specified in a
macro instruction operand. The resultant string is then the value passed into the
macro definition. If the variable symbol is undefined, an error message is issued.
Double ampersands must be specified if a single ampersand is to be passed to the
macro definition.
Examples:
&VAR
&A+&B+3+&C1
'&MESSAGE'
&&REGISTER

Single Quotation Marks

A single quotation mark is used:
To indicate the beginning and end of a quoted string
In a length, type, integer, opcode, or scale attribute reference notation that is
not within a quoted string
Examples:

308

HLASM V1R5 Language Reference

Values in Operands

'QUOTED STRING'
L'SYMBOL
T'SYMBOL

Shift-out (SO) and Shift-in (SI)

If the DBCS assembler option is specified, then SO (X'0E') and SI (X'0F') are
recognized as shift codes. SO and SI delimit the start and end of double-byte data
respectively.

Quoted Strings and Character Strings

A quoted string is any sequence of characters that begins and ends with a single
quotation mark (compare with conditional assembly character expressions
described in Character (SETC) Expressions on page 371).
Two single quotation marks must be specified inside each quoted string. This
includes substituted single quotation marks.
A character string is a sequence of characters, not delimited with quotes. So a
character string is the contents of a quoted string.
Quoted strings can contain double-byte data, if the DBCS assembler option is
specified. The double-byte data must be bracketed by the SO and SI delimiters.
Only valid double-byte data is recognized between the SO and SI. The SI may be
in any odd-numbered byte position after the SO. If the end of the operand is
reached before SI is found, then error ASMA23E Unbalanced double-byte
delimiters is issued.
Macro instruction operands can have values that include one or more quoted
strings. Each quoted string can be separated from the following quoted string by
one or more characters, and each must contain an even number of single quotation
marks.
Examples:
''
'L''SYMBOL'
'QUOTE1'AND'QUOTE2'
A'B'C

Attribute Reference Notation

You can specify an attribute reference notation as a macro instruction operand
value. The attribute reference notation must be preceded by a space or any other
special character except the ampersand and the single quotation mark. See Data
Attributes on page 324 for details about data attributes, and the format of attribute
references.
Examples:
MAC1
MAC1

L'SYMBOL,1+L'AREAL'FIELD
I'PACKED-S'PACKED

Chapter 8. How to Write Macro Instructions

309

Values in Operands

Parentheses
In macro instruction operand values, there must be an equal number of left and
right parentheses. They must be paired, that is, each left parenthesis needs a
following right parenthesis at the same level of nesting. An unpaired (single) left or
right parenthesis can appear only in a quoted string.
Examples:
(PAIRED-PARENTHESES)
()
(A(B)C)D(E)
(IN'('STRING)

Spaces
One or more spaces outside a quoted string indicates the end of the operands of a
macro instruction. Thus spaces should only be used inside quoted strings.
Example:
'SPACES ALLOWED'

Commas
A comma outside a quoted string indicates the end of an operand value or sublist
entry. Commas that do not delimit values can appear inside quoted strings or
paired parentheses that do not enclose sublists.
Examples:
A,B,C,D
(1,2)3'5,6'

Equal Signs
An equal sign can appear in the value of a macro instruction operand or sublist
entry:

As the first character

Inside quoted strings
Between paired parentheses
In a keyword operand
In a positional operand, provided the parameter does not resemble a keyword
operand

Examples:
=H'21'
A'='B
C(A=B)
2X=B
KEY=A=B
The assembler issues a warning message for a positional operand containing an
equal sign, if the operand resembles a keyword operand. Thus, if we assume that
the following is the prototype of a macro definition:
MAC1

the following macro instruction generates a warning message:

MAC1

310

HLASM V1R5 Language Reference

K=L

(K appears to be a valid keyword)

Nesting Macro Instruction Definitions

while the following macro instruction does not:

MAC1

2+2=4

(2+2 is not a valid keyword)

Periods
A period (.) can be used in the value of an operand or sublist entry. It is passed as
a period. However, if it is used immediately after a variable symbol, it becomes a
concatenation character. Two periods are required if one is to be passed as a
character.
Examples:
3.4
&A.1
&A..1

Nesting Macro Instruction Definitions

A nested macro instruction definition is a macro instruction definition you can
specify as a set of model statements in the body of an enclosing macro definition.
This lets you create a macro definition by expanding the outer macro that contains
the nested definition.
Note that all nested inner macro definitions are effectively black boxes: there is no
visibility to the outermost macro definition of any variable symbol or sequence
symbol within any of the nested macro definitions. This means that you cannot use
an enclosing macro definition to tailor or parameterize the contents of a nested
inner macro definition.
This lack of parameterization can be overcome in some cases by using the
AINSERT statement. This lets you generate a macro definition from within another
macro generation. A simple example is shown at Where to Define a Macro in a
Source Module on page 243. In Figure 83 on page 312, macro
ainsert_test_macro generates the macro mac1 using a combination of AINSERT
and AREAD instructions. The mac1 macro is then called with a list of seven
parameters.

Chapter 8. How to Write Macro Instructions

311

Inner and Outer Macro Instructions

1
macro
2 &name
ainsert_test_macro
3
ainsert
'
Macro',back
4
ainsert
'
mac1',back
5
ainsert
'Blah blah blah',front
6 &aread
aread
7 &aread
setc
'&aread'(1,1)
8
ainsert
'&&n
seta n''&&syslist ',back
9
ainsert
'
dc a(&&n)',back
1
ainsert
'
dc c''&aread'' ',back
11
ainsert
'
mend',back
12
mend
13
14 testains csect
15
16
ainsert_test_macro
17+
ainsert
'
Macro',back
18+
ainsert
'
mac1',back
19+
ainsert
'Blah blah blah',front
2-Blah blah blah
21+
ainsert
'&&n
seta n''&&syslist ',back
22+
ainsert
'
dc a(&&n)',back
23+
ainsert
'
dc c''Blah blah '' ',back
24+
ainsert
'
mend',back
25>
Macro
26>
mac1
27>&n
seta n'&syslist
28>
dc a(&n)
29>
dc c'Blah blah '
3>
mend
31
32
mac1 a,b,c,d,e,f,g
33+
dc a(7)
34+
dc c'Blah blah '
35
36
end
Figure 83. Expanding Nested Macro Definitions

Inner and Outer Macro Instructions

Any macro instruction you write in the open code of a source module is an outer
macro instruction or call. Any macro instruction that appears within a macro
definition is an inner macro instruction or call.

Levels of Macro Call Nesting

The code generated by a macro definition called by an inner macro call is nested
inside the code generated by the macro definition that contains the inner macro
call. In the macro definition called by an inner macro call, you can include a macro
call to another macro definition. Thus, you can nest macro calls at different levels.
The &SYSNEST system variable indicates how many levels you called. It has the
value 1 in an outer macro, and is incremented by one at a macro call.

312

HLASM V1R5 Language Reference

Levels of Macro Call Nesting

Recursion
You can also call a macro definition recursively; that is, you can write macro
instructions inside macro definitions that are calls to the containing definition. This
is how you define macros to process recursive functions.

General Rules and Restrictions

Macro instruction statements can be written inside macro definitions. Values are
substituted in the same way as they are for the model statements of the containing
macro definition. The assembler processes the called macro definition, passing to
it the operand values (after substitution) from the inner macro instruction. In
addition to the operand values described in Values in Operands on page 307,
nested macro calls can specify values that include:
Any of the symbolic parameters (see 1 in Figure 84) specified in the
prototype statement of the containing macro definition
Any SET symbols (see 2 in Figure 84) declared in the containing macro
definition
Any of the system variable symbols such as &SYSDATE, &SYSTIME, etc.
(see 3 in Figure 84).
Parameters

MACRO

OUTERMAC
&P1,&P2,&KEY1=VALUE
Prototype
.

.
1
.

LCLC &C2
.

&C
SETC 'ABC'

.

INNERMAC
&P1,&KEY1,&C
Inner macro call
.

.
Operands
.
MEND

MACRO
OUT
Prototype
.
.
.
3
3
3
IN
&SYSLIST(3),&SYSECT,A&SYSDNX Inner macro call
.
.
MEND
Figure 84. Values in Nested Macro Calls

The number of nesting levels permitted depends on the complexity and size of the
macros at the different levels; that is, the number of operands specified, the
number of local-scope and global-scope SET symbols declared, and the number of
sequence symbols used.

Chapter 8. How to Write Macro Instructions

313

Levels of Macro Call Nesting

When the assembler processes a macro exit instruction, either MEXIT or MEND, it
selects the next statement to process depending on the level of nesting. If the
macro exit instruction is from an inner macro, the assembler processes the next
statement after the statement that called the outer macro. The next statement in
open code might come from the AINSERT buffer. If the macro exit instruction is
from an outer macro, the assembler processes the next statement in open code,
after the statement that called the inner macro.

Passing Values through Nesting Levels

The value contained in an outer macro instruction operand can be passed through
one or more levels of nesting (see Figure 85 on page 315). However, the value
specified (see 1 in Figure 85) in the inner macro instruction operand must be
identical to the corresponding symbolic parameter (see 2 in Figure 85) declared
in the prototype of the containing macro definition.
Thus, a sublist can be passed (see 3 in Figure 85) and referred to (see 4 in
Figure 85) as a sublist in the macro definition called by the inner macro call. Also,
any symbol (see 5 in Figure 85) that is passed carries its attribute values through
the nesting levels.
If inner macro calls at each level are specified with symbolic parameters as
operand values, values can be passed from open code through several levels of
macro nesting.
COMPAT(SYSLIST) Assembler Option: If the COMPAT(SYSLIST) assembler
option is specified, and a symbolic parameter is only a part of the value specified in
an inner macro instruction operand, only the character string value given to the
parameter by an outer call is passed through the nesting level. Inner sublist entries
are, therefore, not available for reference in the inner macro.

314

HLASM V1R5 Language Reference

Levels of Macro Call Nesting

MACRO
OUTER
.
.
.
INNER
.
.
.
MEND

&P1,&P2,&P3

MACRO
INNER
&Q,&R,&S
.
.

L
3,&Q(1)
A
3,&Q(2) 4
ST
3,&Q(3)
.

.
MVC
&R,&S
.
.
MEND

START

.
5
.

OUTER
(AREA,F2,SUM),TO,FROM
.

.
3
.
+
L
3,AREA
+
A
2,F2
+
ST
3,SUM
.
.
+
MVC
TO,FROM
.
.
END
Notes:
1. The following inner macro call statement is generated, but not listed unless the
PCONTROL(MCALL) option is specified, or the assembler instruction
ACONTROL MCALL is active:
INNER (AREA,F2,SUM),TO,FROM
Figure 85. Passing Values Through Nesting Levels

Chapter 8. How to Write Macro Instructions

315

Levels of Macro Call Nesting

System Variable Symbols in Nested Macros

The fixed global-scope system variable symbols (see System Variable Symbols
on page 262) are not affected by the nesting of macros. The variable global-scope
system variable symbols have values which may change during the expansion of a
macro definition. The following system variable is influenced by nested macros:
&SYSM_SEV Provides the highest MNOTE severity code from the nested macro
most recently called.
The local system variable symbols are given read-only values each time a macro
definition is called.
The following system variable symbols can be affected by the position of a macro
instruction in code or the operand value specified in the macro instruction:
&SYSCLOCK The assembler assigns &SYSCLOCK the constant string value
representing the TOD clock value at the time at which a macro call
is made. The time portion of this value is precise to the
microsecond. For any inner macro call, the value assigned to
&SYSCLOCK differs from that of its parent.
&SYSECT

The assembler gives &SYSECT the character string value of the

name of the control section in use at the point at which a macro call
is made. For a macro definition called by an inner macro call, the
assembler assigns to &SYSECT the name of the control section in
effect in the macro definition that contains the inner macro call, at
the time the inner macro is called.
If no control section is generated within a macro definition, the value
assigned to &SYSECT does not change. It is the same for the next
level of macro definition called by an inner macro instruction.

&SYSLIB_DSN, &SYSLIB_MEMBER, &SYSLIB_VOLUME

The assembler assigns the character string value of the &SYSLIB
system variable symbols at the point at which a macro is called.
For an inner macro call whose definition is from a library member,
these values may differ, if this is the first time this macro is invoked.

316

&SYSLIST

If &SYSLIST is specified in a macro definition called by an inner

macro instruction, &SYSLIST refers to the positional operands of
the inner macro instruction.

&SYSLOC

The assembler gives &SYSLOC the character string value of the

name of the location counter in use at the point at which a macro is
called. For a macro definition called by an inner macro call, the
assembler assigns to &SYSLOC the name of the location counter in
effect in the macro definition that contains the inner macro call. If
no LOCTR or control section is generated within a macro definition,
the value assigned to &SYSLOC does not change. It is the same
for the next level of macro definition called by an inner macro
instruction.

&SYSNDX

The assembler increments &SYSNDX by one each time it

encounters a macro call. It retains the incremented value
throughout the expansion of the macro definition called, that is,
within the local scope of the nesting level.

HLASM V1R5 Language Reference

Levels of Macro Call Nesting

&SYSNEST

The assembler increments &SYSNEST by one each time it

encounters a nested macro instruction. It retains the incremented
value within the local scope of the macro definition called by the
inner macro instruction. Subsequent nested macro instructions
cause &SYSNEST to be incremented by 1. When the assembler
exits from a nested macro it decreases the value in &SYSNEST by
1.

&SYSSEQF

The assembler assigns &SYSSEQF the character string value of

the identification-field of the outer-most macro instruction statement.
The value of &SYSSEQF remains constant throughout the
expansion of the called macro definition and all macro definitions
called from within the outer macro.

&SYSSTYP

The assembler gives &SYSSTYP the character string value of the

type of the control section in use at the point at which a macro is
called. For a macro definition called by an inner macro call, the
assembler assigns to &SYSSTYP the type of the control section in
effect in the macro definition that contains the inner macro call, at
the time the inner macro is called.
If no control section is generated within a macro definition, the value
assigned to &SYSSTYP does not change. It is the same for the
next level of macro definition called by an inner macro instruction.

Chapter 8. How to Write Macro Instructions

317

How to Write Conditional Assembly Instructions

Chapter 9. How to Write Conditional Assembly Instructions

This chapter describes the conditional assembly language. With the conditional
assembly language, you can carry out general arithmetic and logical computations,
and many of the other functions you can carry out with any other programming
language. Also, by writing conditional assembly instructions in combination with
other assembler language statements, you can:
Select sequences of these source statements, called model statements, from
which machine and assembler instructions are generated
Vary the contents of these model statements during generation
The assembler processes the instructions and expressions of the conditional
assembly language during conditional assembly processing. Then, at assembly
time, it processes the generated instructions. Conditional assembly instructions,
however, are not processed after conditional assembly processing is completed.
The conditional assembly language is more versatile when you use it to interact
with symbolic parameters and the system variable symbols inside a macro
definition. However, you can also use the conditional assembly language in open
code; that is, code that is not within a macro definition.

Elements and Functions

The elements of the conditional assembly language are:
SET symbols that represent data. See SET Symbols on page 319.
Attributes that represent different characteristics of symbols. See Data
Attributes on page 324.
Sequence symbols that act as labels for branching to statements during
conditional assembly processing. See Sequence Symbols on page 339.
The functions of the conditional assembly language are:
Declaring SET symbols as variables for use locally and globally in macro
definitions and open code. See Declaring SET Symbols on page 343.
Assigning values to the declared SET symbols. See Assigning Values to SET
Symbols on page 347.
Selecting characters from strings for substitution in, and concatenation to, other
strings; or for inspection in condition tests. See Substring Notation on
page 371.
Branching and exiting from conditional assembly loops. See Branching on
page 390.
The conditional assembly language can also be used in open code with few
restrictions. See Open Code on page 342.
The conditional assembly language provides instructions for evaluating conditional
assembly expressions used as values for substitution, as subscripts for variable
symbols, and as condition tests for branching. See Conditional Assembly
Instructions on page 343 for details about the syntax and usage rules of each
instruction.

318

Copyright IBM Corp. 1982, 2004

SET Symbols

SET Symbols
SET symbols are variable symbols that provide you with arithmetic, binary, or
character data, and whose values you can vary during conditional assembly
processing.
Use SET symbols as:

Terms in conditional assembly expressions

Counters, switches, and character strings
Subscripts for variable symbols
Values for substitution

Thus, SET symbols let you control your conditional assembly logic, and to generate
many different statements from the same model statement.

Subscripted SET Symbols

You can use a SET symbol to represent a one-dimensional array of many values.
You can then refer to any one of the values of this array by subscripting the SET
symbol. For more information, see Subscripted SET Symbol Specification on
page 322.

Scope of SET Symbols

The scope of a SET symbol is that part of a program for which the SET symbol has
been declared. Local SET symbols need not be declared by explicit declarations.
The assembler considers any undeclared variable symbol found in the name field of
a SETx instruction as a local SET symbol.
If you declare a SET symbol to have a local scope, you can use it only in the
statements that are part of either:
The same macro definition, or
Open code
If you declare a SET symbol to have a global scope, you can use it in the
statements that are part of any one of:
The same macro definition
A different macro definition
Open code
You must, however, declare the SET symbol as global for each part of the program
(a macro definition or open code) in which you use it.
You can change the value assigned to a SET symbol without affecting the scope of
this symbol.

Scope of Symbolic Parameters

A symbolic parameter has a local scope. You can use it only in the statements that
are part of the macro definition for which the parameter is declared. You declare a
symbolic parameter in the prototype statement of a macro definition.
The scope of system variable symbols is described in Figure 86 on page 320.

Chapter 9. How to Write Conditional Assembly Instructions

319

SET Symbols

SET Symbol Specifications

SET symbols can be used in model statements, from which assembler language
statements are generated, and in conditional assembly instructions. The three
types of SET symbols are: SETA, SETB, and SETC. A SET symbol must be a
valid variable symbol.
The rules for creating a SET symbol are:

The first character must be an ampersand (&)

The second character must be an alphabetic character
The remaining characters must be 0 to 61 alphanumeric
The first four characters should not be &SYS, which are used for system
variable symbols

Examples:
&ARITHMETICVALUE439
&BOOLEAN
&C
&EASY_TO_READ
Local SET symbols need not be declared by explicit declarations. The assembler
considers any undeclared variable symbol found in the name field of a SETx
instruction as a local SET symbol, and implicitly declares it to have the type
specified by the SETx instruction. The instruction that declares a SET symbol
determines its scope and type.
The features of SET symbols and other types of variable symbols are compared in
Figure 86.
Figure 86 (Page 1 of 3). Features of SET Symbols and Other Types of Variable Symbols
Features

Can be used in:

Open code

Macro definitions

320

HLASM V1R5 Language Reference

SETA,
SETB,
SETC
symbols

Symbolic
Parameters

System Variable
Symbols

Yes

&SYSASM
&SYSDATC
&SYSDATE
&SYSJOB
&SYSM_HSEV
&SYSM_SEV
&SYSOPT_DBCS
&SYSOPT_OPTABLE
&SYSOPT_RENT
&SYSOPT_XOBJECT
&SYSPARM
&SYSSTEP
&SYSSTMT
&SYSTEM_ID
&SYSTIME
&SYSVER

Yes

All

SET Symbols

Figure 86 (Page 2 of 3). Features of SET Symbols and Other Types of Variable Symbols
Features

Scope:
Local

Global

SETA,
SETB,
SETC
symbols

Symbolic
Parameters

System Variable
Symbols

Yes

&SYSADATA_DSN
&SYSADATA_MEMBER
&SYSADATA_VOLUME
&SYSCLOCK
&SYSECT
&SYSIN_DSN
&SYSIN_MEMBER
&SYSIN_VOLUME
&SYSLIB_DSN
&SYSLIB_MEMBER
&SYSLIB_VOLUME
&SYSLIN_DSN
&SYSLIN_MEMBER
&SYSLIN_VOLUME
&SYSLIST
&SYSLOC
&SYSMAC
&SYSNDX
&SYSNEST
&SYSPRINT_DSN
&SYSPRINT_MEMBER
&SYSPRINT_VOLUME
&SYSPUNCH_DSN
&SYSPUNCH_MEMBER
&SYSPUNCH_VOLUME
&SYSSEQF
&SYSTERM_DSN
&SYSTERM_MEMBER
&SYSTERM_VOLUME

Yes

&SYSASM
&SYSDATC
&SYSDATE
&SYSJOB
&SYSM_HSEV
&SYSM_SEV
&SYSOPT_DBCS
&SYSOPT_OPTABLE
&SYSOPT_RENT
&SYSOPT_XOBJECT
&SYSPARM
&SYSSTEP
&SYSSTMT
&SYSTEM_ID
&SYSTIME
&SYSVER

Chapter 9. How to Write Conditional Assembly Instructions

321

SET Symbols

Figure 86 (Page 3 of 3). Features of SET Symbols and Other Types of Variable Symbols
Features

Values can be
changed within
scope of symbol

SETA,
SETB,
SETC
symbols

Symbolic
Parameters

System Variable
Symbols

Yes

No, read only

value

No, read only

value

Notes:
1. The value assigned to a SET symbol can be changed by using the SETA, SETAF,
SETB, SETC, or SETCF instruction within the declared or implied scope of the SET
symbol.
2. A symbolic parameter and the system variable symbols (except for &SYSSTMT,
&SYSM_HSEV, and &SYSM_SEV) are assigned values that remain fixed throughout
their scope. Wherever a SET symbol appears in a statement, the assembler replaces
the symbol's current value with the value assigned to it.

SET symbols can be used in the name, operation, and operand fields of macro
instructions. The value thus passed through the name field symbolic parameter
into a macro definition is considered as a character string and is generated as
such. If the COMPAT(SYSLIST) assembler option is specified, the value passed
through an operand field symbolic into a macro definition is also considered a
character string and is generated as such. However, if the COMPAT(SYSLIST)
assembler option is not specified, SET symbols can be used to pass sublists into a
macro definition.

Subscripted SET Symbol Specification

The format of a subscripted SET symbol is shown below.

&symbol(subscript)

&symbol
is a variable symbol.
subscript
is an arithmetic expression with a value greater than or equal to 1.
Example:
&ARRAY(2)
The subscript can be any arithmetic expression allowed in the operand field of a
SETA instruction (see Arithmetic (SETA) Expressions on page 352).
The subscript refers to one of the many positions in an array of values identified by
the SET symbol.
A subscripted SET symbol can be used anywhere an unsubscripted SET symbol is
allowed. However, subscripted SET symbols must be declared as subscripted by a
previous local or global declaration instruction, or implicitly as a local subscripted
SET symbol in a SETx instruction of the desired type.

322

HLASM V1R5 Language Reference

SET Symbols

|
|
|
|
|

The dimension (the maximum value of the subscript) of a subscripted SET symbol
is not determined by the explicit or implicit declaration of the symbol. The
dimension specified can be exceeded in later SETx instructions. Note, however,
that increasing the dimension of a subscripted SET symbol also increases the
storage required. For example, referencing only &ARRAY(1000000) still causes the
preceding 999999 elements to be allocated. You can determine the maximum
subscript using the N' attribute (see Number Attribute (N') on page 336).
The subscript can be a subscripted SET symbol.

Created SET Symbols

The assembler can create SET symbols during conditional assembly processing
from other variable symbols and character strings. A SET symbol thus created has
the form &(e), where e represents one or more of the following:
Variable symbols, optionally subscripted
Strings of alphanumeric characters
Other created SET symbols

|
|
|
|

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

alphanumeric characters, the first of which is alphabetic. The assembler considers
the preceding ampersand and this string as the name of a SET variable. If this
created SET symbol has the same name as an existing SET symbol, they are
treated as identical. If this created SET symbol does not have the name of any
existing SET symbol, the usual rules for assigning type and scope apply.

|
|
|
|

You can use created SET symbols wherever ordinary SET symbols are permitted,
including declarations. A created SET symbol may not match the name of a
system variable symbol, nor the name of a symbolic parameter in a macro
prototype statement. You can also nest created SET symbols in other created SET
symbols.
Consider the following example:
&ABC(1)

SETC

'MKT','27','$5'

Let &(e) equal &(&ABC(&I)QUA&I).

|
|

&ABC(&I)

Created SET Symbol

Comment

1
2
3
4

MKT
27
$5

&MKTQUA1
&27QUA2
&$5QUA3
&QUA4

Valid
Invalid: character after '&' not alphabetic
Valid
Valid

The name of a created SET symbol cannot match the name of a system variable
symbol or of a symbolic parameter in a macro definition.
The created SET symbol can be thought of as a form of indirect addressing. With
nested created SET symbols, you can perform this kind of indirect addressing to
any level.
In another sense, created SET symbols offer an associative storage facility. For
example, a symbol table of numeric attributes can be referred to by an expression
of the form &(&SYM)(&I) to yield the Ith attribute of the symbol name in &SYM. As

Chapter 9. How to Write Conditional Assembly Instructions

323

Data Attributes

this example indicates, created SET symbols may be declared and used as arrays
of dimensioned variables.
Created SET symbols also enable you to achieve some of the effect of
multiple-dimensioned arrays by creating a separate name for each element of the
array. For example, a 3-dimensional array of the form &X(&I,&J,&K) could be
addressed as &(X&I.$&J.$&K), where &I, &J, and &K would typically have numeric
values. Thus, &X(2,3,4) would be represented by &X2$3$4. The $ separators
guarantee that &X(2,33,55) and &X(23,35,5) are unique:
&X(2,33,55) becomes &X2$33$55
&X(23,35,5) becomes &X23$35$5

Data Attributes
The data, such as instructions, constants, and areas, that you define in a source
module, can be described by its:
Type, which distinguishes a property of a named object or macro argument, for
example, fixed-point constants from floating-point constants, or machine
instructions from macro instructions
Length, which gives the number of bytes occupied by the object code of the
named data
Scaling, which shows the number of positions occupied by the fractional portion
of named fixed-point, floating-point, and decimal constants in their object code
form
Integer, which shows the number of positions occupied by the integer portion of
named fixed-point and decimal constants in their object code form
Count, which gives the number of characters that would be required to
represent the named data, such as a macro instruction operand, as a character
string
Number, which gives the number of sublist entries in a macro instruction
operand
Defined, which determines whether a symbol has been defined prior to the
point where the attribute reference is coded
Operation Code, which shows if an operation code, such as a macro definition
or machine instruction, is defined prior to the point where the attribute reference
is coded
These characteristics are called the attributes of the symbols naming the data. The
assembler assigns attribute values to the ordinary symbols and variable symbols
that represent the data.
Specifying attributes in conditional assembly instructions allows you to control
conditional assembly logic, which, in turn, can control the sequence and contents of
the statements generated from model statements. The specific purpose for which
you use an attribute depends on the kind of attribute being considered. The
attributes and their main uses are shown below:

324

HLASM V1R5 Language Reference

Data Attributes

Figure 87. Data Attributes

Attribute

Purpose

Main Uses

Type

Gives a letter that identifies

type of data represented

In tests to distinguish between

different data types
For value substitution
In macros to discover missing
operands

Length

Gives number of bytes that

data occupies in storage

For substitution into length fields

For computation of storage
requirements

Scaling

Refers to the position of the

decimal point in fixed-point,
floating-point and decimal
constants

For testing and regulating the

position of decimal points
For substitution into a scale
modifier

Integer

Is a function of the length and

scale attributes of decimal,
fixed-point, and floating-point
constants

To keep track of significant digits

(integers)

Count

Gives the number of

characters required to
represent data

For scanning and decomposing

character strings
As indexes in substring notation

Number

Gives the number of sublist

entries in a macro instruction
operand sublist, or the
maximum subscript of a
dimensioned SET symbol to
which a value has been
assigned.

For scanning sublists

As a counter to test for end of
sublist
For testing array limits

Defined

Shows whether the symbol

referenced has been defined
prior to the attribute reference

To avoid defining a symbol again if

the symbol referenced has been
previously defined

Operation
Code

Shows whether a given

operation code has been
defined prior to the attribute
reference

To avoid assembling a macro or

instruction if it does not exist.

Notes:
1. The number attribute of &SYSLIST(n) and &SYSLIST(n,m) is described in &SYSLIST
System Variable Symbol on page 276.

Attribute Reference
attribute_notation'ordinary_symbol
variable_symbol
literal
character_string

attribute_notation'
is the attribute whose value you want, followed by a single quotation mark.
Valid attribute letters are D, O, N, S, K, I, L, and T.
ordinary_symbol
is an ordinary symbol that represents the data that possesses the attribute. An
ordinary symbol cannot be specified with the operation code attribute.
Chapter 9. How to Write Conditional Assembly Instructions

325

Data Attributes

variable_symbol
is a variable symbol that represents the data that possesses the attribute.
literal
is a literal that represents the data that possesses the attribute. A literal cannot
be specified with the operation code attribute or count attribute.
character_string
is a character string that represents the operation code in the operation code
attribute.
Examples:
T'SYMBOL
L'&VAR
K'&PARAM
O'MVC
S'=P'975.32'
The assembler substitutes the value of the attribute for the attribute reference.
|
|
|

|
|
|
|
|

Reference to the count (K'), defined (D'), number (N'), operation code (O'), and
type (T') attributes can be used only in conditional assembly instructions or within
macro definitions. The length (L'), integer (I'), and scale (S') attribute references
can be in conditional assembly instructions, machine instructions, assembler
instructions, and the operands of macro instructions.

Attributes of Symbols and Expressions

Figure 88 shows attribute references (in the columns) and types of symbols (in the
rows). Each intersection shows whether (Yes) or not (No) you can validly apply
the attribute reference to that symbol type, or (in the case of SET symbols) to the
value of the symbol.
Figure 88 (Page 1 of 2). Attributes and Related Symbols

Symbols
Specified

Type
T'

Length
L'

Scale
S'

Integer
I'

Count
K'

Number
N'

Defined
D'

Operation
Code O'

In open code:
Ordinary
symbols

Yes

System variable
symbols with
global scope

Yes

Literals

Yes

326

HLASM V1R5 Language Reference

Data Attributes

Figure 88 (Page 2 of 2). Attributes and Related Symbols

Symbols
Specified

Type
T'

Length
L'

Scale
S'

Integer
I'

Count
K'

Number
N'

Defined
D'

Operation
Code O'

Ordinary
symbols

Yes

Symbolic
parameters

Yes

&SYSLIST

Yes

All others

Yes

In macro
definitions:

System variable
symbols:

|
|
|

Literals in
macro instruction
operands

|
|

The values of attribute references may be used in ordinary and conditional

assembly expressions, as shown in Figure 89.

| Figure 89. Using Attribute Values

|
|
|
|
|
|
|
|
|

Symbols
Specified

Type
T'

Length
L'

Scale
S'

Integer
I'

Count
K'

Number
N'

Defined
D'

Operation
Code O'

In open code:
SET symbols

SETB,
SETC

SETA,
SETB

SETB,
SETC

In ordinary assembly:

Yes

In macro
definitions:
SET symbols

SETB,
SETC

SETA,
SETB

SETB,
SETC

Note:
1. Only in character relations.
2. Only in arithmetic relations.

The value of an attribute for an ordinary symbol specified in an attribute reference

comes from the item named by the symbol. The symbol must appear in the name
field of an assembler or machine instruction, or in the operand field of an EXTRN or
WXTRN instruction.
The value of an attribute reference to an expression is the value of that attribute
reference to its leftmost term.
Notes:
1. You cannot refer to the names of instructions generated by conditional
assembly substitution or macro generation until the instruction is generated.
2. If you use a symbol qualifier to qualify an ordinary symbol in an attribute
reference, the qualifier is ignored.

Chapter 9. How to Write Conditional Assembly Instructions

327

Data Attributes

The value of an attribute for a variable symbol specified in an attribute reference

comes from the value substituted for the variable symbol as follows:
SET Symbols and System Variable Symbols: For SET symbols and all system
variable symbols other than &SYSLIST, the attribute values come from the current
value of these symbols.
Symbolic Parameters and &SYSLIST: For symbolic parameters and the system
variable symbol, &SYSLIST, the values of the count and number attributes come
from the operands of macro instructions. The name field entry of the call is an
operand, and is referenceable as &SYSLIST(0). The values of the type, length,
scale, and integer attributes, however, come from the values represented by the
macro instruction operands, as follows:
1. If the operand is a sublist, the entire sublist and each entry of the sublist can
possess attributes; all the individual entries and the whole sublist have the
same attributes as those of the first suboperand in the sublist (except for the
count attribute, which can be different, and the number attribute which is
relevant only for the whole sublist).
2. If the first character or characters of the operand (or sublist entry) constitute an
ordinary symbol, and this symbol is followed by either an arithmetic operator (+,
, *, or /), a left parenthesis, a comma, or a space, then the value of the
attributes for the operand are the same as for the ordinary symbol.
3. If the operand (or sublist entry) is a character string other than a sublist or the
character string described in the previous point, the type attribute is undefined
(U) and the length, scale, and integer attributes are invalid.
Because the count (K'), number (N'), and defined (D') attribute references are
allowed only in conditional assembly instructions, their values are available only
during conditional assembly processing. They are not available at ordinary
assembly time.
The system variable symbol &SYSLIST, with a valid subscript, can be used in an
attribute reference to refer to a macro instruction operand, and, in turn, to an
ordinary symbol. Thus, any of the attribute values for macro instruction operands
and ordinary symbols listed below can also be substituted for an attribute reference
containing &SYSLIST (see &SYSLIST System Variable Symbol on page 276).

Type Attribute (T')

The type attribute has a value of a single alphabetic character that shows the type
of data represented by:

An ordinary symbol
A macro instruction operand
A SET symbol
A literal
A system variable symbol

The type attribute can change during an assembly. The lookahead search might
assign one attribute, whereas the symbol table at the end of the assembly might
display another.

328

HLASM V1R5 Language Reference

Data Attributes

The type attribute reference can be used in the operand field of a SETC instruction
or as one of the values used for comparison in the operand field of a SETB or AIF
instruction.
The type attribute can also be specified outside conditional assembly instructions.
Then, the type attribute value is not used for conditional assembly processing, but
is used as a value at assembly time.
The following letters are used for the type attribute of data represented by ordinary
symbols and outer macro instruction operands that are symbols that name DC or
DS statements.
A
B
C
D
E
F
G
H
K
L
P
Q
R
S
V
X
Y
Z
@

A-, J-type address constant, implied length, aligned (also CXD instruction label)
Binary constant
Character constant
Long floating-point constant, implicit length, aligned
Short floating-point constant, implicit length, aligned
Fullword fixed-point constant, implicit length, aligned
Fixed-point constant, explicit length
Halfword fixed-point constant, implicit length, aligned
Floating-point constant, explicit length
Extended floating-point constant, implicit length, aligned
Packed decimal constant
Q-type address constant, implicit length, aligned
A-, S-, Q-, J-, R-, V-, or Y-type address constant, explicit length
S-type address constant, implicit length, aligned
R-, V-type address constant, implicit length, aligned
Hexadecimal constant
Y-type address constant, implicit length, aligned
Zoned decimal constant
Graphic (G) constant

When a literal is specified as the name field on a macro call instruction, and if the
literal has previously been used in a machine instruction, the type attribute of the
literal is the same as for data represented by ordinary symbols or outer macro
instructions operands.
The following letters are used for the type attribute of data represented by ordinary
symbols (and outer macro instruction operands that are symbols) that name
statements other than DC or DS statements, or that appear in the operand field of
an EXTRN or WXTRN statement:
I
J
M

T
W
$

Machine instruction
Control section name
The name field on a macro instruction, when the name field is:
a valid symbol not previously defined
a valid literal not previously defined
Identified as an external symbol by EXTRN instruction
CCW, CCW0, or CCW1 instruction
Identified as an external symbol by WXTRN instruction

The following letter is used for the type attribute of data represented by inner and
outer macro instruction operands only:
O Omitted operand (has a value of a null character string)

Chapter 9. How to Write Conditional Assembly Instructions

329

Data Attributes

The following attribute is used for the type attribute of the value of variable
symbols:
N The value is numeric
The following letter is used for symbols or macro instruction operands that cannot
be assigned any of the above letters:
U Undefined, unknown, or unassigned
The common use of the U type attribute is to describe a valid symbol that has
not been assigned any of the type attribute values described above. If the
assembler is not able to determine what the named symbol represents, it also
assigns the U type attribute. Thus, the U type attribute can mean undefined, or
unknown, or unassigned at the time of the reference. Consider the following
macro definition:
Name

Operation
Operand
macro
MAC1 &op1,&op2
setc T'&op1
setc T'&op2
DC C'&A'
DC containing type attribute for op1
DC C'&B'
DC containing type attribute for op2
mend

&A
&B

When the macro MAC1 is called in Figure 90, neither of the operands has
previously been defined, however GOOD_SYMBOL is a valid symbol name, whereas
?BAD_SYMBOL? is not a valid symbol name. The type attribute for both operands
is U, meaning GOOD_SYMBOL is undefined, and ?BAD_SYMBOL? is unknown.

E4
1 E4

8 a
9
1+
11+
12

csect
mac1 GOOD_SYMBOL,?BAD_SYMBOL?
DC C'U'
DC containing type attribute for op1
DC C'U'
DC containing type attribute for op2
end

Figure 90. Undefined and Unknown Type Attributes

When the macro MAC1 is called in Figure 91, GOOD_SYMBOL is a valid symbol
name, and has been defined in the DC instruction at statement 12.
?BAD_SYMBOL? is a not valid symbol name, and the assembler issues an error
message at statement 13. The type attribute for GOOD_SYMBOL is C, meaning the
symbol represents a character constant. The type attribute for ?BAD_SYMBOL? is
U, meaning the type is unknown.

8 a
csect
9
mac1 GOOD_SYMBOL,?BAD_SYMBOL?
C3
1+
DC C'C'
DC containing type attribute for op1
1 E4
11+
DC C'U'
DC containing type attribute for op2
2 A9
12 GOOD_SYMBOL dc cl1'z'
3 A9
13 ?BAD_SYMBOL? dc cl1'z'
ASMA147E Symbol too long, or first character not a letter - ?BAD_SYMBOL?
14
end

Figure 91. Unknown Type Attribute for Invalid Symbol

The type attribute value U, meaning undefined, unknown, or unassigned, is

assigned to the following:
Ordinary symbols used as labels:

330

HLASM V1R5 Language Reference

Data Attributes

For the LTORG instruction

For the EQU instruction without a third operand
For DC and DS statements that contain variable symbols, for example,
U1 DC &X'1'
|
|
|
|
|
|
|
|

That are defined more than once, even though only one instance of the
label is generated due to conditional assembly statements. A
lookahead scan for attributes of a symbol may encounter more than one
occurrence of a symbol, in which case the assembler can't yet tell which
statement(s) will be generated. In such cases, type attribute U is
assigned. At a later time, when the symbol has been generated, its type
attribute is changed to the correct value for the type of statement it
names.
SETC variable symbols that have a value other than a null character string
or the name of an instruction that can be referred to be a type attribute
reference
System variable symbols except:
&SYSDATC, &SYSM_HSEV, &SYSM_SEV, &SYSNDX, &SYSNEST,
&SYSOPT_DBCS, &SYSOPT_RENT, &SYSOPT_XOBJECT, and
&SYSSTMT, which always have a type attribute value of N
Some other character type system variable symbols which may be
assigned a value of a null string, when they have a type attribute value
of O
Macro instruction operands that specify a literal that is not a duplicate of a
literal used in a machine instruction
Inner macro instruction operands that are ordinary symbols
Notes:
1. Ordinary symbols used in the name field of an EQU instruction have the type
attribute value U. However, the third operand of an EQU instruction can be
used explicitly to assign a type attribute value to the symbol in the name field.
2. The type attribute of a sublist is set to the same value as the type attribute of
the first element of the sublist.
3. High Level Assembler and earlier assemblers treat the type attribute differently:
Because High Level Assembler allows attribute references to statements
generated through substitution, certain cases in which a type attribute of U
(undefined, unknown, or unassigned) or M (macro name field) is given
under the DOS/VSE Assembler, may give a valid type attribute under High
Level Assembler. If the value of the SETC symbol is equal to the name of
an instruction that can be referred to by the type attribute, High Level
Assembler lets you use the type attribute with a SETC symbol.
Because High Level Assembler allows attribute references to literals,
certain cases in which a type attribute of U (undefined, unknown, or
unassigned) is given by Assembler F and Assembler H for a macro
operand that specifies a literal, may give a valid type attribute under High
Level Assembler. If the literal specified in the macro instruction operand is
a duplicate of a literal specified in open code, or previously generated by
conditional assembly processing or macro generation, High Level

Chapter 9. How to Write Conditional Assembly Instructions

331

Data Attributes

Assembler gives a type attribute that shows the type of data specified in
the literal. The COMPAT(LITTYPE) option causes High Level Assembler to
behave like Assembler H, always giving a type attribute of U for the T'
literal.

Length Attribute (L')

The length attribute has a numeric value equal to the number of bytes occupied by
the data that is named by the symbol specified in the attribute reference.
If the length attribute value is desired for conditional assembly processing, the
symbol specified in the attribute reference must ultimately represent the name entry
of a statement in open code. In such a statement, the length modifier (for DC and
DS instructions) or the length field (for a machine instruction), if specified, must be
a self-defining term, of a predefined absolute symbol. If multiple operands are
specified in a DC or DS instruction, the attribute of the statement label is
determined from the first operand. The length modifier or length field must not be
coded as a multiterm expression, because the assembler does not evaluate this
expression until assembly time.
The assembler lets you use the length attribute with a SETC symbol, a system
variable symbol, or a symbolic parameter, if the value of the SETC symbol is an
ordinary symbol that can be referenced by the length attribute.
The length attribute can also be specified outside conditional assembly instructions.
Then, the length attribute value is not available for conditional assembly processing,
but is used as a value at assembly time.
Figure 92 is an example showing the evaluation of the length attribute for an
assembler instruction in statement 1 and for a conditional assembly instruction in
statement 8.
E74

1 CSYM DC
CL(L'ZLOOKAHEAD)'X' Length resolved later
2 &LEN SETA L'CSYM
ASMA42E Length attribute of symbol is unavailable; default=1
3
DC
C'&LEN ' REAL LENGTH NOT AVAILABLE
2 F14
+
DC
C'1 '
REAL LENGTH NOT AVAILABLE
4 &TYP SETC T'CSYM
5
DC
C'&TYP ' TYPE IS KNOWN
4 C34
+
DC
C'C '
TYPE IS KNOWN
6 &DEF SETA D'CSYM
7
DC
C'&DEF ' SYMBOL IS DEFINED
6 F14
+
DC
C'1 '
SYMBOL IS DEFINED
8 &LEN SETA L'zlookahead Length resolved immediately
9 CSYM2 DC
CL(&len)'X'
8 E74
+CSYM2 DC
CL(2)'X'
1 &LEN SETA L'CSYM2
11
DC
C'&LEN ' REAL LENGTH NOW AVAILABLE
A F24
+
DC
C'2 '
REAL LENGTH NOW AVAILABLE
C 1
12 ZLOOKAHEAD
DC
H'1'
13
END
Figure 92. Evaluation of Length Attribute References

In statement 2 the length of CSYM has not been established because the definition of
CSYM in statement 1 is not complete. The reference to the length attribute results in
a length of 1 and error message ASMA042E. However, statement 5 shows that the

332

HLASM V1R5 Language Reference

Data Attributes

type attribute is assigned, and statement 7 shows that the defined attribute is
assigned. In comparison, the length attribute for symbol CSYM2 is available
immediately, as it was retrieved indirectly using the conditional assembly instruction
in statement 8.

|
|

During conditional assembly, an ordinary symbol used in the name field of an EQU
instruction has a length attribute value that depends on the order of the symbol's
definition and the reference to its length attribute.

|
|

If the first operand of the EQU instruction is a self-defining term, the length
attribute value is 1.

|
|
|

If the first operand of the EQU instruction is a symbol whose value and length
attribute are defined, the length attribute value is that of the symbol in the first
operand.

|
|
|

If the first operand of the EQU instruction is a defined symbol and the EQU
instruction specifies a length value in the second operand, the length attribute
value is that of the second operand.

At assembly time, the symbol has the same length attribute value as the first term
of the expression in the first operand of the EQU instruction. However, the second
operand of an EQU instruction can be used to assign a length attribute value to the
symbol in the name field. This second operand can not be a forward reference to
another EQU instruction.
Notes:
1. The length attribute reference, when used in conditional assembly processing,
can be specified only in arithmetic expressions.
2. When used in conditional assembly processing, a length attribute reference to a
symbol with the type attribute value of M, N, O, T, U, or $ is flagged. The
length attribute for the symbol has the default value of 1.

Scale Attribute (S')

The scale attribute can be used only when referring to fixed-point, floating-point, or
decimal constants. The following table shows the numeric value assigned to the
scale attribute:
Constant
Types
Allowed

Type of DC or DS
Allowed

Value of Scale
Attribute Assigned

Fixed-Point

H and F

Equal to the value of the scale modifier

(187 through +346)

Floating Point

D, E, and L

Equal to the value of the scale modifier

(0 through 14 D, E)
(0 through 28 L)

Decimal

P and Z

Equal to the number of decimal digits

specified to the right of the decimal
point
(0 through 31 P)
(0 through 16 Z)

Chapter 9. How to Write Conditional Assembly Instructions

333

Data Attributes

The scale attribute can also be specified outside conditional assembly instructions.
Then, the scale attribute value is not used for conditional assembly processing, but
is used as a value at assembly time.
Notes:
1. The scale attribute reference can be used only in arithmetic expressions.
2. When no scale attribute value can be determined, the reference is flagged and
the scale attribute is 1.
3. If the value of the SETC symbol is equal to the name of an instruction that can
validly define the scale attribute, the assembler lets you use the scale attribute
with a SETC symbol.
4. Binary floating-point constants return an attribute of 0.
5. The scale attribute reference can only be used in arithmetic expressions in
conditional assembly instructions, and in absolute and relocatable expressions
in assembler and machine instructions.

Integer Attribute (I')

The integer attribute has a numeric value that depends on the length and scale
attribute values of the data being referred to by the attribute reference. The
formulas relating the integer attribute to the length and scale attributes are given in
Figure 93.
The integer attribute can also be specified outside conditional assembly
instructions. Then, the integer attribute value is not used for conditional assembly
processing, but is used as a value at assembly time.
Notes:
1. The integer attribute reference can be used only in arithmetic expressions.
2. When no integer attribute value can be determined, the reference is flagged
and the integer attribute is 1.
3. If the value of the SETC symbol is equal to the name of an instruction that can
validly define the integer attribute, the assembler lets you use the integer
attribute with a SETC symbol.
4. Binary floating-point constants return an attribute of 0.
5. The integer attribute reference can only be used in arithmetic expressions in
conditional assembly instructions, and in absolute and relocatable expressions
in assembler and machine instructions.
Figure 93 (Page 1 of 2). Relationship of Integer to Length and Scale Attributes

Constant Type
Fixed-point
(H and F)

334

Formula Relating Integer

to Length and Scale
Attributes

Examples

I' = 8L'S'1

HALFCON DC HS6'25.93'

I' = 8261
= 9

ONECON

I' = 8481
= 23

HLASM V1R5 Language Reference

DC FS8'1.3E2'

Values of the
Integer Attribute

Data Attributes

Figure 93 (Page 2 of 2). Relationship of Integer to Length and Scale Attributes

Constant Type

Formula Relating Integer

to Length and Scale
Attributes

Examples

Floating-point
(D, E, and L)

when L' 8
I' = 2(L'1)S'

SHORT

DC ES2'46.415'

I' = 2(41)2
= 4

LONG

DC DS5'3.729'

I' = 2(81)5
= 9

Values of the
Integer Attribute

L-type only

when L' > 8

I' = 2(L'1)S'2

EXTEND

DC LS1'5.312'

I' = 2(161)12
= 18

Decimal
Packed (P)

I' = 2L'S'1

PACK

DC P'+3.513'

I' = 2331
= 2

Zoned (Z)

I' = L'S'

ZONE

DC Z'3.513'

I' = 43
= 1

Notes:
1. The value of the integer attribute is equal to the number of digits to the left of the assumed decimal
point after the constant is assembled, and the value of the scale attribute is equal to the number of
digits to the right of the assumed decimal point.

Count Attribute (K')

The count attribute applies only to macro instruction operands, to SET symbols,
and to the system variable symbols. It has a numeric value equal to the number of
characters:
That constitute the macro instruction operand, or
That would be required to represent as a character string the current value of
the SET symbol or the system variable symbol.
Notes:
1. The count attribute reference can be used only in arithmetic expressions.
2. The count attribute of an omitted macro instruction operand has a value of 0.
3. Doubled quotes ('') in quoted character strings count as one character.
Doubled ampersands (&&) in quoted character strings count as two characters.
For more information about character pairs see Evaluation of Character
Expressions on page 382.
4. These pairing rules mean that the length attribute of a character variable
substituted into a character constant may be different from the count attribute of
the substituted variable.
5. The count attribute differs from the Number (N') attribute, described below.

Chapter 9. How to Write Conditional Assembly Instructions

335

Data Attributes

Number Attribute (N')

The number attribute applies to the operands of macro instructions and subscripted
SET symbols.
When applied to a macro operand, the number attribute is a numeric value equal to
the number of sublist entries.
When applied to a subscripted SET symbol, the number attribute is equal to the
highest element to which a value has been assigned in a SETx instruction.
Consider the example in Figure 94.

C889878885A2A34
28 D5A494828599496

1
2
3
4 &SETSUB(5)
5 &B
6 &C
7
8
9
1 a
11
12+
13+
14

macro
MAC1 &op1
lcla &SETSUB(1)
seta 2,,,7
seta N'&SETSUB
seta N'&op1
DC C'Highest referenced element of SETSUB = &B'
DC C'Number of sublist entries in OP1 = &C'
mend
csect
MAC1 (1,(3),(4))
DC C'Highest referenced element of SETSUB = 8'
DC C'Number of sublist entries in OP1 = 3'
end

Figure 94. Number Attribute Reference

N'&op1 is equal to 3 because there are three subscripts in the macro operand in
statement 11: 1, (3), and (4).
N'&SETSUB is equal to 8 because &SETSUB(8), assigned the value 70 in statement 4,
is the highest referenced element of the &SETSUB array entries.
Notes:
1. The number attribute reference can be used only in arithmetic expressions.
2. N'&SYSLIST refers to the number of positional operands in a macro
instruction, and N'&SYSLIST(n) refers to the number of sublist entries in the
n-th operand.
3. For positional macro parameters, either explicitly named or implicitly named as
&SYSLIST(n):
a. If the first character of an operand is a left parenthesis, count the number
of unquoted and un-nested commas between it and the next matching right
parenthesis. That number plus one is the number attribute of the operand.
b. If there is no initial left parenthesis, the number attribute is one.
4. For all other system variable symbols, the number attribute value is always one.
This is also true for &SYSMAC. The range of the subscript for &SYSMAC is
zero to &SYSNEST inclusive.
|
|
|
|

5. N' is always zero for unsubscripted set symbols. The number attribute (N'),
when used with a macro instruction operand, examines its list structure, not the
number of characters in the operand. (The number of characters is determined
by the count (K') attribute.)

336

HLASM V1R5 Language Reference

Data Attributes

Defined Attribute (D')

The defined attribute shows whether or not the ordinary symbol or literal referenced
has been defined prior to the attribute reference. A symbol is defined if it has been
encountered in the operand field of an EXTRN or WXTRN statement, or in the
name field of any other statement except a TITLE statement or a macro instruction.
A literal is defined if it has been encountered in the operand field of a machine
instruction. The value of the defined attribute is an arithmetic value that can be
assigned to a SETA symbol, and is equal to 1 if the symbol has been defined, or 0
if the symbol has not been defined.
The defined attribute can reference:

Ordinary symbols not constructed by substitution

Macro instruction operands
SETC symbols whose value is an ordinary symbol
System variable symbols whose value is an ordinary symbol
Literals

The following is an example of how you can use the defined attribute:
Name

Operation

Operand

A
.AROUND

AIF
LA
ANOP

(D'A).AROUND
1,4

In this example, assuming there has been no previous definition of the symbol A,
the statement labeled A would be assembled, since the conditional-assembly
branch around it would not be taken. However, if by an AGO or AIF
conditional-assembly branch the same statement were processed again, the
statement at A would not be assembled:
Name

Operation

Operand

.UP
A
.AROUND

AIF
LA
ANOP
.
.
AGO

(D'A).AROUND
1,4

.UP

You can save assembly time using the defined attribute which avoids lookahead
mode (see Lookahead on page 340 for more information. You can use the
defined attribute in your program to prevent the assembler from making this
time-consuming forward scan. This attribute reference can be used in the operand
field of a SETA instruction or as one of the values in the operand field of a SETB or
AIF instruction.

Operation Code Attribute (O')

The operation code attribute shows whether a given operation code has been
defined prior to the attribute reference. The operation code can be represented by
a character string or by a variable symbol containing a character string. The
variable must be set using a SETC assembler instruction prior to being referenced
by the operation code (O') attribute.

Chapter 9. How to Write Conditional Assembly Instructions

337

Data Attributes

The operation code attribute has a value of a single alphabetic character that
shows the type of operation represented.
This attribute reference can be used in the operand field of the SETC instruction or
as one of the values used in the operand field of a SETB or AIF instruction.
The following letters are used for the value of the operation code attribute:
A
E
M
O
S
U

Assembler operation code

Extended mnemonic operation code
Macro definition
Machine operation code
Macro definition found in library
Undefined, unknown, unassigned, or deleted operation code

Notes:
1. The operation code (O') attribute can only be used in a conditional assembly
statement.
2. The assembler does not enter lookahead mode to resolve the operation code
type, therefore only operation codes defined at the time the attribute is
referenced return an operation code type value other than U.
3. When the operation code is not an assembler instruction or a machine
instruction, and the operation code is not a previously defined macro, then all
libraries in the library data set definition list are searched. This may have an
adverse impact on the performance of the assembly, depending on the number
of libraries assigned in the assembly job and the number of times the operation
code attribute is used.
Examples:
Name

Operation

Operand

SETC

O'MVC

&A contains the letter O, because MVC is a machine operation code:

Name

Operation

Operand

&A
&B

SETC
SETC

'DROP'
O'&A

&B contains the letter A, because DROP is an assembler operation code.

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

Operation

Operand

&CHECKIT

SETC
AIF
MAC1
ANOP
.

O'MAC1
('&CHECKIT' EQ 'U').NOMAC

.NOMAC

338

HLASM V1R5 Language Reference

Sequence Symbols

Redefined Operation Codes: If an operation code is redefined using the OPSYN

instruction then the value returned by a subsequent operation code attribute
reference represents the new operation code. If the operation code is deleted using
the OPSYN instruction then the value returned is U.

Sequence Symbols
You can use a sequence symbol in the name field of a statement to branch to that
statement during conditional assembly processing, thus altering the sequence in
which the assembler processes your conditional assembly and macro instructions.
You can select the model statements from which the assembler generates
assembler language statements for processing at assembly time.
A sequence symbol consists of a period (.) followed by an alphabetic character,
followed by 0 to 61 alphanumeric characters.
Examples:
.BRANCHING_LABEL#1
.A
Sequence symbols can be specified in the name field of assembler language
statements and model statements; however, sequence symbols must not be used
as name entries in the following assembler instructions:
|
|
|
|

ALIAS
AREAD
CATTR
DXD

EQU
ICTL
LOCTR

OPSYN
SETA
SETB

SETC
SETAF
SETCF

Also, sequence symbols cannot be used as name entries in macro prototype

instructions, or in any instruction that already contains an ordinary or a variable
symbol in the name field.
Sequence symbols can be specified in the operand field of an AIF or AGO
instruction to branch to a statement with the same sequence symbol as a label.
Scope: A sequence symbol has a local scope. Thus, if a sequence symbol is
used in an AIF or an AGO instruction, the sequence symbol must be defined as a
label in the same part of the program in which the AIF or AGO instruction appears;
that is, in the same macro definition or in open code.
Symbolic Parameters: If a sequence symbol appears in the name field of a
macro instruction, and the corresponding prototype statement contains a symbolic
parameter in the name field, the sequence symbol does not replace the symbolic
parameter wherever it is used in the macro definition. The value of the symbolic
parameter is a null character string.
Example:

Chapter 9. How to Write Conditional Assembly Instructions

339

Lookahead

MACRO
MOVE
&TO,&FROM
Statement 1
ST
2,SAVEAREA
Statement 2
L
2,&FROM
ST
2,&TO
L
2,SAVEAREA
MEND
-----------------------------------------------------------------.SYM
MOVE
FIELDA,FIELDB
Statement 3
-----------------------------------------------------------------+
ST
2,SAVEAREA
Statement 4
+
L
2,FIELDB
+
ST
2,FIELDA
+
L
2,SAVEAREA
&NAME
&NAME

The symbolic parameter &NAME is used in the name field of the prototype statement
(Statement 1) and the first model statement (Statement 2). In the macro instruction
(Statement 3), a sequence symbol (.SYM) corresponds to the symbolic parameter
&NAME. &NAME is not replaced by .SYM and, therefore, the generated statement
(Statement 4) does not contain an entry in the name field.

Lookahead
Symbol attributes are established in either definition mode or lookahead mode.
Definition mode occurs whenever a previously undefined symbol is encountered in
the name field of a statement, or in the operand field of an EXTRN or WXTRN
statement during open code processing. Symbols within a macro definition are
defined when the macro is expanded.
Lookahead mode is entered:
When the assembler processes a conditional assembly instruction and
encounters an attribute reference (other than D' and O') to an ordinary symbol
that is not yet defined.
When the assembler encounters a forward AGO or AIF branch in open code to
a sequence symbol that is not yet defined.
Lookahead is a sequential, statement-by-statement, forward scan over the source
text.
If the attribute reference is made in a macro, forward scan begins with the first
source statement following the outermost macro instruction. During lookahead the
assembler:

Bypasses macro definition and generation

Does not generate object text
Does not perform open-code variable substitution
Ignores AIF and AGO branch instructions
Establishes interim data attributes for undefined symbols it encounters in
operand fields of instructions. The data attributes are replaced when a symbol
is subsequently encountered in definition mode.

Lookahead mode ends when the desired symbol or sequence symbol is found, or
when the END statement or end of file is reached. All statements read by

340

HLASM V1R5 Language Reference

Lookahead

lookahead are saved on an internal file, and are fully processed when the
lookahead scan ends.
If a COPY instruction is encountered during lookahead, it is fully processed at that
time, the assembler copies the statements from the library, scans them, and saves
them on the lookahead file. When lookahead mode has ended any COPY
instructions saved to the lookahead file are ignored, as the statements from the
copy member have already been read and saved to the lookahead file.
If a variable symbol is used for the member name of a COPY that is expanded
during lookahead, the value of the variable symbol at the time the COPY is
expanded is used.
For purposes of attribute definition, a symbol is considered partially defined if it
depends in any way upon a symbol not yet defined. For example, if the symbol is
defined by a forward EQU that is not yet resolved, that symbol is assigned a type
attribute of U.
In this case, it is quite possible that, by the end of the assembly, the type attribute
has changed to some other value.
Generating END statements: Because no variable symbol substitution is carried
out during lookahead, you should consider the following effects of using macro,
AINSERT or open code substitution to generate END statements that separate
source modules assembled in one job step (BATCH assembler option). If a symbol
is undefined within a module, lookahead might read statements past the point
where the END statement is to be generated. Lookahead stops when:
1. It finds the symbol
2. It finds an END statement
3. It reaches the end of the source input data set
In the first two cases, the assembler begins the next module at the statement after
lookahead stopped, which could be after the point where you wanted to generate
the END statement.

Lookahead Restrictions
The assembler analyzes the statements it processes during lookahead, only to
establish attributes of symbols in their name fields.
Variable symbols are not replaced. Modifier expressions are evaluated only if all
symbols involved were defined prior to lookahead. Possible multiple or inconsistent
definition of the same symbol is not diagnosed during lookahead because
conditional assembly may eliminate one (or more) of the definitions.
Lookahead does not check undefined operation codes against library macro names.
If the name field contains an ordinary symbol and the operation code cannot be
matched with one in the current operation code table, then the ordinary symbol is
assigned the type attribute of M. If the operation code contains special characters
or is a variable symbol, a type attribute of U is assumed. This may be wrong if the
undefined operation code is later substituted with a known operation code or is later
defined by OPSYN. OPSYN statements are not processed; thus, labels are treated
in accordance with the operation code definitions in effect at the time of entry to
lookahead.

Chapter 9. How to Write Conditional Assembly Instructions

341

Open Code

Sequence Symbols
The conditional assembly instructions AGO and AIF in open code control the
sequence in which source statements are processed. Using these instructions it is
possible to branch back to a sequence symbol label and re-use previously
processed statements. Due to operating system restrictions, the primary input
source can only be read sequentially, and cannot be re-read. Whenever a
sequence symbol in the name field is encountered in open code, the assembler
must assume that all subsequent statements may need to be processed more than
once. The assembler uses the lookahead file to save the statement containing the
sequence symbol label and all subsequent statements as they are read and
processed. Any subsequent AGO or AIF to a previously encountered sequence
symbol is resolved to an offset into the lookahead file and input continues from that
point.

Open Code
Conditional assembly instructions in open code let you:
Select, during conditional assembly, statements or groups of statements from
the open code portion of a source module according to a predetermined set of
conditions. The assembler further processes the selected statements at
assembly time.
Pass local variable information from open code through parameters into macro
definitions.
Control the computation in and generation of macro definitions using global
SET symbols.
Substitute values into the model statements in the open code of a source
module and control the sequence of their generation.
All the conditional assembly elements and instructions can be specified in open
code.
The specifications for the conditional assembly language described in this chapter
also apply in open code. However, the following restrictions apply:
To Attributes In Open Code: For ordinary symbols, only references to the type,
length, scale, integer, defined, and operation code attributes are allowed.
References to the number attribute have no meaning in open code, because
&SYSLIST is not allowed in open code, and symbolic parameters have no meaning
in open code.
To Conditional Assembly Expressions: Figure 95 shows the restrictions for
different expression types.
Figure 95 (Page 1 of 2). Restrictions on Coding Expressions in Open Code

342

Expression

Must not contain

Arithmetic
(SETA)

&SYSLIST
Symbolic parameters
Any attribute references to symbolic parameters, or system variable
symbols with local scope

HLASM V1R5 Language Reference

Conditional Assembly Instructions

Figure 95 (Page 2 of 2). Restrictions on Coding Expressions in Open Code

Expression

Must not contain

Character
(SETC)

Logical
(SETB)

Arithmetic expressions with the items listed above

Character expressions with the items listed above

System variables with local scope

Attribute references to system variables with local scope
Symbolic parameters
Predefined absolute symbols

Conditional Assembly Instructions

The remainder of this chapter describes, in detail, the syntax and rules for use of
each conditional assembler instruction. The following table lists the conditional
assembler instructions by type, and provides the page number where the instruction
is described in detail.
Figure 96. Assembler Instructions
Type of Instruction

Instruction

Establishing SET symbols

GBLA

344

GBLB

344

GBLC

344

LCLA

345

LCLB

345

LCLC

345

SETA

347

SETB

362

SETC

369

ACTR

394

AGO

392

AIF

390

ANOP

395

SETAF

388

SETCF

389

Branching

External Function Calling

Page No.

Declaring SET Symbols

You must declare a global SET symbol before you can use it. The assembler
assigns an initial value to a global SET symbol at its first point of declaration.
Local SET symbols need not be declared explicitly with LCLA, LCLB, or LCLC
statements. The assembler considers any undeclared variable symbol found in the
name field of a SETA, SETB, SETC, SETAF, or SETCF statement to be a local
SET symbol. It is given the initial value specified in the operand field. If the
symbol in the name field is subscripted, it is declared as a subscripted SET symbol.

Chapter 9. How to Write Conditional Assembly Instructions

343

GBLA, GBLB, and GBLC Instructions

Use the GBLA, GBLB, and GBLC instructions to declare the global SETA, SETB,
and SETC symbols you need. The SETA, SETB, and SETC symbols are assigned
the initial values of 0, 0, and null character string, respectively.

,
variable_symbol
GBLA
sequence_symbol GBLB
GBLC

sequence_symbol
is a sequence symbol.
variable_symbol
is a variable symbol, with or without the leading ampersand (&).
These instructions can be used anywhere in the body of a macro definition or in the
open code portion of a source module.
Any variable symbols declared in the operand field have a global scope. They can
be used as SET symbols anywhere after the pertinent GBLA, GBLB, or GBLC
instructions. However, they can be used only within those parts of a program in
which they have been declared as global SET symbols; that is, in any macro
definition and in open code.
The assembler assigns an initial value to the SET symbol only when it processes
the first GBLA, GBLB, or GBLC instruction in which the symbol appears. Later
GBLA, GBLB, or GBLC instructions do not reassign an initial value to the SET
symbol.
Multiple GBLx statements can declare the same variable symbol so long as only
one declaration for a given symbol is encountered during the expansion of a macro.
The following rules apply to the global SET variable symbol:
Within a macro definition, it must not be the same as any symbolic parameter
declared in the prototype statement.
It must not be the same as any local variable symbol declared within the same
local scope.
The same variable symbol must not be declared or used as two different types
of global SET symbol; for example, as a SETA or SETB symbol.
A global SET symbol should not begin with &SYS because these characters are
used for system variable symbols.

Subscripted Global SET Symbols

A global subscripted SET symbol is declared by the GBLA, GBLB, or GBLC
instruction.

344

HLASM V1R5 Language Reference

LCLA, LCLB, and LCLC Instructions

,
variable_symbol(dimension)
GBLA
sequence_symbol GBLB
GBLC

sequence_symbol
is a sequence symbol.
variable_symbol
is a variable symbol, with or without the leading ampersand (&).
dimension
is the dimension of the array. It must be an unsigned, decimal, self-defining
term greater than zero.
Example:
GBLA

&GA(25),&GA1(15)

There is no limit on the maximum subscript allowed. Also, the limit specified in the
global declaration (GBLx) can be exceeded. The dimension shows the number of
SET variables associated with the subscripted SET symbol. The assembler
assigns an initial value to every variable in the array thus declared.
Notes:
1. Global arrays are assigned initial values only by the first global declaration
processed, in which a global subscripted SET symbol appears.
2. A subscripted global SET symbol can be used only if the declaration has a
subscript, which represents a dimension; an unsubscripted global SET symbol
can be used only if the declaration had no subscript, except for a number
attribute reference to the name of a dimensioned SET symbol.

Alternative Format for GBLx Statements

The assembler permits the alternative statement format for GBLx instructions:
Cont.
GBLA

&GLOBAL_SYMBOL_FOR_DC_GEN,
&LOOP_CONTRL_A,
&VALUE_PASSED_TO_FIDO,
&VALUE_RETURNED_FROM_FIDO

X
X
X

LCLA, LCLB, and LCLC Instructions

Use the LCLA, LCLB, and LCLC instructions to declare the local SETA, SETB, and
SETC symbols you need. The SETA, SETB, and SETC symbols are assigned the
initial values of 0, 0, and null character string, respectively.

,
variable_symbol
LCLA
sequence_symbol LCLB
LCLC

Chapter 9. How to Write Conditional Assembly Instructions

345

LCLA, LCLB, and LCLC Instructions

sequence_symbol
is a sequence symbol.
variable_symbol
is a variable symbol, with or without the leading ampersand (&).
These instructions can be used anywhere in the body of a macro definition or in the
open code portion of a source module.
Any variable symbols declared in the operand field have a local scope. They can
be used as SET symbols anywhere after the pertinent LCLA, LCLB, or LCLC
instructions, but only within the declared local scope. Multiple LCLx statements can
declare the same variable symbol so long as only one declaration for a given
symbol is encountered during the expansion of a macro.
The following rules apply to a local SET variable symbol:
Within a macro definition, it must not be the same as any symbolic parameter
declared in the prototype statement.
It must not be the same as any global variable symbol declared within the
same local scope.
The same variable symbol must not be declared or used as two different types
of SET symbols; for example, as a SETA and a SETB symbol, within the same
local scope.
A local SET symbol should not begin with &SYS because these characters are
used for system variable symbols.

Subscripted Local SET Symbols

A local subscripted SET symbol is declared by the LCLA, LCLB, or LCLC
instruction.

,
variable_symbol(dimension)
LCLA
sequence_symbol LCLB
LCLC

&B(1)

There is no limit to SET symbol dimensioning. The limit specified in the explicit
(LCLx) or implicit (SETx) declaration can also be exceeded by later SETx
statements. The dimension shows the number of SET variables associated with

346

HLASM V1R5 Language Reference

Assigning Values to SET Symbols

the subscripted SET symbol. The assembler assigns an initial value to every
variable in the array thus declared.
Subscripted Local SET Symbol: A subscripted local SET symbol can be used
only if the declaration has a subscript, which represents a dimension; an
unsubscripted local SET symbol can be used only if the declaration had no
subscript, except for a number attribute reference to the dimensioned SET symbol.

Alternative Format for LCLx Statements

The assembler permits an alternative statement format for LCLx instructions:
Cont.
LCLA

&LOCAL_SYMBOL_FOR_DC_GEN,
&COUNTER_FOR_INNER_LOOP,
&COUNTER_FOR_OUTER_LOOP,
&COUNTER_FOR_TRAILING_LOOP

X
X
X

Assigning Values to SET Symbols

You can assign values to SET symbols by using the SETA, SETB, SETC, SETAF
and SETCF instructions (SETx). You can also use these instructions to implicitly
define local SET symbols. Local SET symbols need not be declared explicitly with
LCLA, LCLB, or LCLC statements. The assembler considers any undeclared
variable symbol found in the name field of a SETx statement to be a local SET
symbol. It is given the initial value specified in the operand field of SETA, SETB
and SETC instructions, and the value returned from the external function specified
in the operand of SETAF and SETCF instructions. If the symbol in the name field
is subscripted, it is declared as a subscripted SET symbol.
Note that spaces do not terminate the operand field when used in logical
expressions and in build-in functions. For more information, see Logical (SETB)
Expressions on page 365.

SETA Instruction
The SETA instruction assigns an arithmetic value to a SETA symbol. You can
specify a single value or an arithmetic expression from which the assembler
computes the value to assign.
You can change the values assigned to an arithmetic or SETA symbol. This lets
you use SETA symbols as counters, indexes, or for other repeated computations
that require varying values.
variable_symbolSETAexpression

variable_symbol
is a variable symbol.
A global variable symbol in the name field must have been previously declared
as a SETA symbol in a GBLA instruction. Local SETA symbols need not be
declared in a LCLA instruction. The assembler considers any undeclared
variable symbol found in the name field of a SETA instruction as a local SET
symbol. The variable symbol is assigned a type attribute value of N.
Chapter 9. How to Write Conditional Assembly Instructions

347

SETA Instruction

expression
is an arithmetic expression evaluated as a signed 32-bit arithmetic value that is
assigned to the SETA symbol in the name field. The minimum and maximum
allowable values of the expression are 231 and +2311, respectively.
Figure 97 defines an arithmetic expression.

Arithmetic
Expression

Can be any of

Arithmetic (Arith. Arith. Binary Arith. Arithmetic-Valued +Arith. -Arith.
Term
Exp.) Exp. Operator Exp. Built-in Function Exp. Exp.

Can be any of

unary operators

Predefined Self

Variable Absolute
Defining Attribute
Symbol
Ordinary
Term
Reference

Symbol

Operators Allowed

Unary: + Positive

Negative
Can
only be
Binary: + Addition

Subtraction
Length

Multiplication
Scale

/ Division
Integer

Count

Arith. Exp. = Arithmetic Expression

Number

Defined

Figure 97. Defining Arithmetic (SETA) Expressions

Figure 98 shows the variable symbols that are allowed as terms in an arithmetic
expression.
Figure 98 (Page 1 of 2). Variable Symbols Allowed as Terms in Arithmetic Expressions

348

Variable symbol

Restrictions

Example

Valid value

SETA

None

---

SETB

None

---

SETC

Value must evaluate to an

unsigned binary,
hexadecimal or decimal
self-defining term

123

Symbolic parameters

Value must be a
self-defining term

&PARAM

X'A1'

&SUBLIST(3)

C'Z'

HLASM V1R5 Language Reference

SETA Instruction

Figure 98 (Page 2 of 2). Variable Symbols Allowed as Terms in Arithmetic Expressions

Variable symbol

Restrictions

Example

Valid value

&SYSLIST(n)

Corresponding operand or
sublist entry must be a
self-defining term

&SYSLIST(3)

&SYSLIST(3,2)

B'11'

None

---

&SYSLIST(n,m)
&SYSDATC
&SYSM_HSEV
&SYSM_SEV
&SYSNDX
&SYSNEST
&SYSOPT_DBCS
&SYSOPT_RENT
&SYSOPT_XOBJECT
&SYSSTMT

The following example shows a SETA statement with a valid self-defining term in its
operand field:
&ASYM1

SETA

C'D'

&ASYM1 has value 196 (C'D')

The second statement in the following example is valid because in the two
positions in the SETA operand where a term is required (either side of the + sign),
the assembler finds a valid self-defining term:
&CSYM2
&ASYM3

SETC
SETA

'C''A'''
&CSYM2+&CSYM2

&CSYM2 has value C'A'

&ASYM3 has value 386 (C'A' + C'A')

A SET statement is not rescanned by the assembler to see whether substitutions

might affect the originally-determined syntax. The original syntax of the
self-defining term must be correct. Therefore the assembler does not construct a
self-defining term in a SETA statement. The third statement of the next example
shows this:
&CSYM3
&ASYM3
&ASYM4

SETC
SETA
SETA

'3'
&CSYM3
C'&ASYM3'

&CSYM has value 3 (C'3')

&ASYM has value 3
Invalid self-defining term

In this example C'&ASYM3' is not a valid term.

Subscripted SETA Symbols

The SETA symbol in the name field can be subscripted, but only if the same SETA
symbol has been previously declared in a GBLA or LCLA instruction with an
allowable dimension.
The assembler assigns the value of the expression in the operand field to the
position in the declared array given by the value of the subscript. The subscript
expression must not be 0 or have a negative value.
|
|
|

Introducing Built-In Functions

|
|

Each function returns one value - an arithmetic value for SETA, a binary bit for
SETB, and a character string for SETC.

There are two different forms of invocation for the built-in functions:

The assembler provides built-in functions for the SETA, SETB and SETC
expressions.

Chapter 9. How to Write Conditional Assembly Instructions

349

SETA Instruction

|
|
|
|
|

The logical-expression format encloses the function and operands in

parentheses. In the unary format, the function is followed by the one operand.
In the binary format, the function is placed between the two operands. For
both unary and binary formats, the function is separated from the operand or
operands by spaces.

Logical-expression unary format

(built-in functionoperand)

Logical-expression binary format

(operandbuilt-in functionoperand)

|
|
|

(A OR B) and (&J SLL 2) are examples of binary logical-expression format

functions, and (NOT C) and (SIGNED &J) are examples of unary
logical-expression format functions.

|
|

The function-invocation format has the function first, followed by one or more
operands in parentheses.

Function-invocation format

|
|
|

built-in function(operand)

,operand

|
|

FIND('abcde','d') is an example of a function-invocation format. (The

equivalent logical-expression format is ('abcde' FIND 'd').)

|
|

Spaces are not allowed between the arguments of functions in

function-invocation format.

|
|
|

In either format, the operand is an expression of the type expected by the built-in
function. (The particular details of the number of operands and the operand type
are provided with the information for each built-in function.)

|
|
|

Some functions are available in one format, some are available in both. Figure 99,
which provides a summary of all the built-in functions, shows the forms in which a
function is available.

Figure 99 (Page 1 of 3). Summary of Built-In Functions

Function

Type

A2B

Representation conversion

374

A2C

Representation conversion

375

A2D

Representation conversion

375

A2X

Representation conversion

375

AND

Logical

353

AND

Logical

365

AND NOT

Logical

365

B2A

Representation conversion

353

350

HLASM V1R5 Language Reference

L-E F-I

Result

Operands

Page

SETA Instruction

Figure 99 (Page 2 of 3). Summary of Built-In Functions

Function

Type

B2C

Representation conversion

375

B2D

Representation conversion

376

B2X

Representation conversion

376

BYTE

Representation conversion

376

C2A

Representation conversion

353

C2B

Representation conversion

377

C2D

Representation conversion

377

C2X

Representation conversion

377

D2A

Representation conversion

354

D2B

Representation conversion

377

D2C

Representation conversion

378

D2X

Representation conversion

378

DCLEN

String manipulation

354

DCVAL

String manipulation

378

DEQUOTE

String manipulation

379

DOUBLE

String manipulation

379

FIND

String scanning

355

INDEX

String scanning

355

ISBIN

Validity checking

365

ISDEC

Validity checking

366

ISHEX

Validity checking

366

ISSYM

Validity checking

366

LOWER

String manipulation

379

NOT

Logical

356

NOT

Logical

366

Logical

356

Logical

366

OR NOT

Logical

367

SIGNED

Representation conversion

380

SLA

Shift

356

SLL

Shift

356

SRA

Shift

357

SRL

Shift

357

SYSATTRA

Information retrieval

380

SYSATTRP

Information retrieval

380

UPPER

String manipulation

380

X2A

Representation conversion

358

X2B

Representation conversion

381

L-E F-I

Result

Operands

Chapter 9. How to Write Conditional Assembly Instructions

Page

351

SETA Instruction

Figure 99 (Page 3 of 3). Summary of Built-In Functions

Function

Type

X2C

Representation conversion

381

X2D

Representation conversion

381

XOR

Logical

358

XOR

Logical

367

XOR NOT

Logical

367

Notes:

L-E F-I

Result

Operands

1. If a is in this column, the function is available in the logical-expression format.

2. If a is in this column, the function is available in the function-invocation format.

3. Possible values in these columns are:

|
|
|

Page

A Arithmetic
B Binary
C Character

|
|

4. For these functions, the maximum length of the operand (and output) is the maximum
string length that the assembler supports, currently 1024.

Arithmetic (SETA) Expressions

Figure 100 shows how arithmetic expressions can be used.
Figure 100. Use of Arithmetic Expressions
Used in

Used as

Example

SETA instruction

Operand

&A1

SETA

AIF or SETB instruction

Term in arithmetic
relation

AIF

(&A1 GT 3).A

Subscripted SET symbols

Subscript

&ASYM(&A+1&C)

Substring notation

Subscript

'STRING'(&A2,&A1)

Sublist notation

Subscript

Given sublist (A,B,C,D)

named &PARAM,
if &A=1 then &PARAM(&A+1)=B

&SYSLIST

Subscript

&SYSLIST(&M+1,&N2)
&SYSLIST(N'&SYSLIST)

SETC instruction

Character string in
operand

Given &C SETC

if &A=1 then
&C=511 2
Given &D SETC
if &A=1 then
&D=5113

Built-in functions

Operand

&VAR
SETA

&A1+2

'51&A' 1

SETA (NOT &OP1) &VAR

BYTE(64)

When an arithmetic expression is used in the operand field of a SETC instruction

(see 1 in Figure 100), the assembler assigns the character value representing
the arithmetic expression to the SETC symbol, after substituting values (see 2 in
Figure 100) into any variable symbols. It does not evaluate the arithmetic
expression. The mathematical sign (+ or ) is not included in the substituted value

352

HLASM V1R5 Language Reference

SETA Instruction

of a variable symbol (see 3 in Figure 100), and any insignificant leading zeros
are removed.
Here are the built-in functions for arithmetic (SETA) expressions:
AND
Format: Logical-expression
Operands: Arithmetic
Output: (aexpr1 AND aexpr2) provides an arithmetic result where each bit
position in the result is set to 1 if the corresponding bit positions in both
operands contain 1, otherwise, the result bit is set to 0.
Example
After the following statements &VAR contains the arithmetic value +2.

Name

Operation

Operand

&OP1
&OP2
&VAR

SETA
SETA
SETA

1
2
(&OP1 AND &OP2)

B2A

|
|

Format: Function-invocation
Operands: Character

|
|

Output: B2A('bitstring') converts a character string argument containing

'' and '1' characters to an arithmetic value.

|
|
|
|
|
|

Fewer than 32 characters are padded internally on the left with ''
characters to a length of 32 characters.
Error conditions are detected if the argument contains invalid characters,
or if the argument length exceeds 32 characters, generating the message
ASMA214E.
Null argument strings return zero.

The result of the B2A function is the same as

&value

except that null strings are allowed by B2A but not by SETA.

Examples

|
|
|

B2A('')
has value
B2A('11')
has value 5
B2A('1111111111111111111111111111111')

SETA

B'bitstring'

has value -2

C2A

|
|

Format: Function-invocation
Operands: Character

|
|

Output: C2A('charstring') converts a character string of zero to four

characters to a binary arithmetic value having the same bit pattern.

|
|
|
|
|

Fewer than four characters are padded internally on the left with EBCDIC
null characters to a length of four characters.
An error condition is detected if the argument length exceeds 4
characters, generating the message ASMA214E.
Null argument strings return zero.

Chapter 9. How to Write Conditional Assembly Instructions

353

SETA Instruction

The result of C2A is the same as would be obtained from

&value

|
|

except that C2A gives a zero result for null strings, and does not pair
apostrophes or ampersands before conversion.

Example

|
|
|
|

C2A('')
C2A('+')
C2A('1')
C2A('')

SETA C'charstring'

has
has
has
has

value
value
value
value

78
241
-252645136

D2A

|
|

Format: Function-invocation
Operands: Character

|
|
|

Output: D2A('decstring') converts a character string argument containing an

optional leading plus or minus sign followed by decimal digits to an arithmetic
value. Error conditions are detected if

|
|
|
|
|

the argument contains invalid characters

no digits are present following a sign
the argument length exceeds 11 characters
the resulting value is too large
the argument string is null.

The result of the D2A function is the same as

&value

except that SETA does not allow leading plus or minus signs.

Examples

|
|
|
|
|

D2A('')
D2A('')
D2A('1')
D2A('+1')
D2A('-5')

SETA

decstring

indicates
has value
has value
has value
has value

an error condition

1
1
-5

DCLEN

|
|

Format: Function-invocation
Operands: Character

|
|
|
|
|

Output: DCLEN('cexpr') returns the length of its argument string after pairs of
apostrophes and ampersands have been internally replaced by single
occurrences. No change is made to the argument. Such pairing occurs only
once; that is, three successive occurrences of an apostrophe or ampersand
will result in two occurrences, not one.

Examples

|
|
|
|
|
|
|

DCLEN('')
DCLEN('''')
DCLEN('''''')
DCLEN('&&')
DCLEN('a''''b')
DCLEN('a''''b&&c')
DCLEN('&&&''''''')

|
|

Note: DCLEN is similar to DCVAL, except that DCLEN returns only the length
of the result, not the paired string.

354

HLASM V1R5 Language Reference

has
has
has
has
has
has
has

value
value
value
value
value
value
value

1
2
1
3
5
4

(null string)
(argument is a single apostrophe)
(argument is two apostrophes)
(argument is two ampersands)
(DCVAL string would be "a'b")
(DCVAL string would be "a'b&c")
(DCVAL string would be "&&''")

SETA Instruction

FIND
Format: Logical-expression, function-invocation
Operands: Character
Output: (string1 FIND string2) or FIND(string1,string2) finds the first
match of any character from operand2 within operand1. The value returned
by FIND indicates the position where the match occurs. FIND returns 0 if no
match occurs or if either operand is a null string.
Examples
After the following statements &VAR contains the arithmetic value 3.
Name

Operation

Operand

&OP1
&OP2
&VAR

SETC
SETC
SETA

'abcdef'
'cde'
('&OP1' FIND '&OP2')

In the above example the character c in &OP2 is the first character found in
&OP1. Consider the following example where the character c, in &OP1, has
been replaced with the character g.
Name

Operation

Operand

&OP1
&OP2
&VAR

SETC
SETC
SETA

'abcdef'
'gde'
('&OP1' FIND '&OP2')

&VAR contains the arithmetic value 4. The character d in &OP2 is the first
character found in &OP1.
In the following example, the ordering of the characters in the second operand
is changed to egd.
Name

Operation

Operand

&OP1
&OP2
&VAR

SETC
SETC
SETA

'abcdef'
'egd'
FIND('&OP1','&OP2')

&VAR still contains the arithmetic value 4. Because FIND is looking for a single
character from the character string, the order of the characters in the second
operand string is irrelevant.
INDEX
Format: Logical-expression, function-invocation
Operands: Character
Output: INDEX('cexpr1','cexpr2') or ('cexpr1' INDEX 'cexpr2') locates
the first occurrence of the second argument within the first argument, and
returns the position of the match. A zero value is returned if:
Either argument is null
No match is found
The second argument is longer than the first
Examples
INDEX('ABC','B')
INDEX('ABC','D')

has value 2
has value

Chapter 9. How to Write Conditional Assembly Instructions

355

SETA Instruction

NOT
Format: Logical-expression
Operands: Arithmetic
Output: (NOT aexp) provides the ones complement of the value contained or
evaluated in the operand.
Example
After the following statements &VAR contains the arithmetic value 11.
Name

Operation

Operand

&OP1
&VAR

SETA
SETA

1
(NOT &OP1)

OR
Format: Logical-expression
Operands: Arithmetic
Output: Each bit position in the result is set to 1 if the corresponding bit
positions in one or both operands contains a 1, otherwise the result bit is set
to 0.
Example
After the following statements &VAR contains the arithmetic value +1.
Name

Operation

Operand

&OP1
&OP2
&VAR

SETA
SETA
SETA

1
2
(&OP1 OR &OP2)

SLA
Format: Logical-expression
Operands: Arithmetic
Output: The 31-bit numeric part of the signed first operand is shifted left the
number of bits specified in the rightmost six bits of the second operand. The
sign of the first operand remains unchanged. Zeros are used to fill the
vacated bit positions on the right.
Example
After the following statements &VAR contains the arithmetic value +8.
Name

Operation

Operand

&OP1
&OP2
&VAR

SETA
SETA
SETA

2
2
(&OP1 SLA &OP2)

SLL
Format: Logical-expression
Operands: Arithmetic
Output: (aexp1 SLL aexp2) shifts the 32-bit first operand left the number of
bits specified in the rightmost six bits of the second operand. Bits shifted out
of bit position 0 are lost. Zeros are used to fill the vacated bit positions on the
right.

356

HLASM V1R5 Language Reference

SETA Instruction

Example
After the following statements &VAR contains the arithmetic value +4.
Name

Operation

Operand

&OP1
&OP2
&VAR

SETA
SETA
SETA

1
2
(&OP1 SLL &OP2)

SRA
Format: Logical-expression
Operands: Arithmetic
Output: The 31-bit numeric part of the signed first operand is shifted right the
number of bits specified in the rightmost six bits of the second operand. The
sign of the first operand remains unchanged. Bits shifted out of bit position 31
are lost. Bits equal to the sign are used to fill the vacated bit positions on the
left.
Examples
After the following statements &VAR contains the arithmetic value +2.
Name

Operation

Operand

&OP1
&OP2
&VAR

SETA
SETA
SETA

1
2
(&OP1 SRA &OP2)

After the following statements &VAR contains the arithmetic value 1.

Name

Operation

Operand

&OP1
&OP2
&VAR

SETA
SETA
SETA

-344
4
(&OP1 SRA &OP2)

Compare this result with the result in the second example under SRL below.
SRL
Format: Logical-expression
Operands: Arithmetic
Output: The 32-bit first operand is shifted right the number of bits specified in
the rightmost six bits of the second operand. Bits shifted out of bit position 31
are lost. Zeros are used to fill the vacated bit positions on the left.
Examples
After the following statements &VAR contains the arithmetic value +2.
Name

Operation

Operand

&OP1
&OP2
&VAR

SETA
SETA
SETA

1
2
(&OP1 SRL &OP2)

After the following statements &VAR contains the arithmetic value .

Chapter 9. How to Write Conditional Assembly Instructions

357

SETA Instruction

Name

Operation

Operand

&OP1
&OP2
&VAR

SETA
SETA
SETA

-344
4
(&OP1 SRL &OP2)

X2A

|
|

Format: Function-invocation
Operands: Character

|
|

Output: X2A('hexstring') converts a character string argument containing

hexadecimal digits to an arithmetic value.

|
|
|
|
|
|

If the character string contains fewer than 8 characters, it is padded

internally on the left with '' characters.
Error conditions are detected if the argument contains invalid characters,
or if the argument length exceeds 8 characters, generating the message
ASMA214E.
Null argument strings return zero.

The result of the X2A function is the same as

&value

except that null strings are allowed by X2A but not by SETA.

Examples

|
|
|
|

X2A('11')
X2A('C1')
X2A('')
X2A('FFFFFFF')

SETA

X'hexstring'

has
has
has
has

value
value
value
value

257
193

-16

XOR
Format: Logical-expression
Operands: Arithmetic
Output: Each bit position in the result is set to 1 if the corresponding bit
positions in the two operands are unlike, otherwise the result bit is set to 0.
Example After the following statements &VAR contains the arithmetic value +8.
Name

Operation

Operand

&OP1
&OP2
&VAR

SETA
SETA
SETA

1
2
(&OP1 XOR &OP2)

Rules for Coding Arithmetic Expressions: The following is a summary of coding

rules for arithmetic expressions:
1. Unary (operating on one value) operators and binary (operating on two values)
operators are allowed in arithmetic expressions.
2. An arithmetic expression can have one or more unary operators preceding any
term in the expression or at the beginning of the expression. The unary
operators are + (positive) and (negative).
3. The binary operators that can be used to combine the terms of an expression
are + (addition), (subtraction), (multiplication), and / (division).
4. An arithmetic expression must not begin with a binary operator, and it must not
contain two binary operators in succession.

358

HLASM V1R5 Language Reference

SETA Instruction

5. An arithmetic-valued function is a term.

6. An arithmetic expression must not contain two terms in succession.
7. An arithmetic expression must not contain a decimal point. For example,
123.456 is not a valid arithmetic term, but 123 is.
8. An arithmetic expression must not contain spaces between an operator and a
term, nor between two successive operators except for built-in functions using
the logical-expression format described at Logical (SETB) Expressions on
page 365.
9. Ordinary symbols specified in arithmetic expressions must be defined before
the arithmetic expression is encountered, and must have an absolute value.
10. An arithmetic expression can contain up to 24 unary and binary operators, and
is limited to 255 levels of parentheses. The parentheses required for sublist
notation, substring notation, and subscript notation count toward this limit.
An arithmetic expression must not contain two terms in succession; however,
any term may be preceded by up to 24 unary operators. +&A&B is a valid
operand for a SETA instruction. The expression &FIELD+ is invalid because it
has no final term.
Evaluation of Arithmetic Expressions: The assembler evaluates arithmetic
expressions during conditional assembly processing as follows:
1. It evaluates each arithmetic term.
2. It carries out arithmetic operations from left to right. However,
a. It carries out unary operations before binary operations, and
b. It carries out the binary operations of multiplication and division before the
binary operations of addition and subtraction.
3. In division, it gives an integer result; any fractional portion is dropped. Division
by zero gives a 0 result.
4. In parenthesized arithmetic expressions, the assembler evaluates the innermost
expressions first, and then considers them as arithmetic terms in the next outer
level of expressions. It continues this process until the outermost expression is
evaluated.
|
|
|

5. The computed result, including intermediate values, must lie in the range 231
through +2311. (Note that if the value 231 is substituted in a SETC
expression, its magnitude, 2147483648, is invalid if subsequently substituted in
a SETA expression.)
SETC Variables in Arithmetic Expressions: The assembler permits a SETC
variable to be used as a term in an arithmetic expression if the character string
value of the variable is a self-defining term. The value represented by the string is
assigned to the arithmetic term. A null string is treated as zero.
Examples:
&C(1)
&C(2)
&C(3)
&A

LCLC
SETC
SETC
SETC
SETA

&C(5)
'B''11'''
'C''A'''
'23'
&C(1)+&C(2)&C(3)

Chapter 9. How to Write Conditional Assembly Instructions

359

SETA Instruction

In evaluating the arithmetic expression in the fifth statement, the first term, &C(1), is
assigned the binary value 11 (decimal 5). To that is added the value represented
by the EBCDIC character A (hexadecimal C1, which corresponds to decimal 193).
Then the value represented by the third term &C(3) is subtracted, and the value of
&A becomes 5+19323=175.
This feature lets you associate numeric values with EBCDIC or hexadecimal
characters to be used in such applications as indexing, code conversion,
translation, and sorting.
Assume that &X is a character string with the value ABC.
&I
&VAL

SETC
SETA

'C'''.'&X'(1,1).''''
&TRANS(&I)

The first statement sets &I to C'A'. The second statement extracts the 193rd
element of &TRANS (C'A' = X'C1' = 193).
The following code converts a hexadecimal value in &H into a decimal value in
&VAL:
&X
&VAL

SETC
SETA

'X''&H'''
&X

The following code converts the double-byte character Da into a decimal value in
&VAL. &VAL can then be used to find an alternative code in a subscripted SETC
variable:
&DA
&VAL

SETC
SETA

'G''<Da>'''
&DA

Although you can use a predefined absolute symbol as an operand in a SETA

expression, you cannot substitute a SETC variable whose value is the same as the
symbol. For example:
ABS
&ABS
&CABS
&ABS

EQU
SETA
SETC
SETA

5
ABS
'ABS'
&CABS

&ABS has value 5

&CABS has value 'ABS'
invalid usage

DBCS Assembler Option: The G-type self-defining term is valid only if the DBCS
assembler option is specified.

Using SETA symbols

The arithmetic value assigned to a SETA symbol is substituted for the SETA
symbol when it is used in an arithmetic expression. If the SETA symbol is not used
in an arithmetic expression, the arithmetic value is converted to a character string
containing its absolute value, with leading zeros removed. If the value is 0, it is
converted to a single 0.
Example:

360

HLASM V1R5 Language Reference

SETA Instruction

MACRO
MOVE
&TO,&FROM
LCLA
&A,&B,&C,&D
&A
SETA
1
Statement 1
&B
SETA
12
Statement 2
&C
SETA
&A&B
Statement 3
&D
SETA
&A+&C
Statement 4
&NAME
ST
2,SAVEAREA
L
2,&FROM&C
Statement 5
ST
2,&TO&D
Statement 6
L
2,SAVEAREA
MEND
------------------------------------------------------------------HERE
MOVE
FIELDA,FIELDB
------------------------------------------------------------------+HERE ST
2,SAVEAREA
+
L
2,FIELDB2
+
ST
2,FIELDA8
+
L
2,SAVEAREA
&NAME

Statements 1 and 2 assign the arithmetic values +1 and +12, respectively, to the
SETA symbols &A and &B. Therefore, statement 3 assigns the SETA symbol &C
the arithmetic value 2. When &C is used in statement 5, the arithmetic value 2 is
converted to the character 2. When &C is used in statement 4, however, the
arithmetic value 2 is used. Therefore, &D is assigned the arithmetic value +8.
When &D is used in statement 6, the arithmetic value +8 is converted to the
character 8.
The following example shows how the value assigned to a SETA symbol may be
changed in a macro definition.
MACRO
MOVE
&TO,&FROM
LCLA
&A
&A
SETA
5
Statement 1
&NAME
ST
2,SAVEAREA
L
2,&FROM&A
Statement 2
&A
SETA
8
Statement 3
ST
2,&TO&A
Statement 4
L
2,SAVEAREA
MEND
------------------------------------------------------------------HERE
MOVE
FIELDA,FIELDB
------------------------------------------------------------------+HERE ST
2,SAVEAREA
+
L
2,FIELDB5
+
ST
2,FIELDA8
+
L
2,SAVEAREA
&NAME

Statement 1 assigns the arithmetic value +5 to SETA symbol &A. In statement 2, &A
is converted to the character 5. Statement 3 assigns the arithmetic value +8 to &A.
In statement 4, therefore, &A is converted to the character 8, instead of 5.
A SETA symbol may be used with a symbolic parameter to refer to an operand in
an operand sublist. If a SETA symbol is used for this purpose, it must have been
assigned a positive value.

Chapter 9. How to Write Conditional Assembly Instructions

361

SETB Instruction

Any expression that may be used in the operand field of a SETA instruction may be
used to refer to an operand in an operand sublist. Sublists are described in
Sublists in Operands on page 304.
The following macro definition adds the last operand in an operand sublist to the
first operand in an operand sublist and stores the result at the first operand. A
sample macro instruction and generated statements follow the macro definition.
MACRO
ADDX
&NUMBER,&REG
Statement 1
LCLA
&LAST
&LAST
SETA
N'&NUMBER
Statement 2
L
&REG,&NUMBER(1)
A
&REG,&NUMBER(&LAST) Statement 3
ST
&REG,&NUMBER(1)
MEND
------------------------------------------------------------------ADDX
(A,B,C,D,E),3
Statement 4
------------------------------------------------------------------+
L
3,A
+
A
3,E
+
ST
3,A
&NUMBER is the first symbolic parameter in the operand field of the prototype
statement (statement 1). The corresponding characters (A,B,C,D,E) of the macro
instruction (statement 4) are a sublist. Statement 2 assigns to &LAST the arithmetic
value +5, which is equal to the number of operands in the sublist. Therefore, in
statement 3, &NUMBER(&LAST) is replaced by the fifth operand of the sublist.

SETB Instruction
Use the SETB instruction to assign a bit value to a SETB symbol. You can assign
the bit values, 0 or 1, to a SETB symbol directly and use it as a switch.
If you specify a logical (Boolean) expression in the operand field, the assembler
evaluates this expression to determine whether it is true or false, and then assigns
the value 1 or 0, respectively, to the SETB symbol. You can use this computed
value in condition tests or for substitution.
variable_symbolSETBbinary_value

variable_symbol
is a variable symbol.
A global variable symbol in the name field must have been previously declared
as a SETB symbol in a GBLB instruction. Local SETB symbols need not be
declared in a LCLB instruction. The assembler considers any undeclared
variable symbol found in the name field of a SETB instruction as a local SET
symbol. The variable symbol is assigned a type attribute value of N.
binary_value
is a binary bit value that may be specified as:
A binary digit (0 or 1)

362

HLASM V1R5 Language Reference

SETB Instruction

A binary value enclosed in parentheses

An arithmetic value enclosed in parentheses is allowed. This value can be
represented by:

An unsigned, self-defining term

A SETA symbol
A previously defined ordinary symbol with an absolute value
An attribute reference other than the type attribute reference.

If the value is 0, the assembler assigns a value of 0 to the symbol in the

name field. If the value is not 0, the assembler assigns a value of 1.
A logical expression enclosed in parentheses
A logical expression is evaluated to determine if it is true or false; the SETB
symbol in the name field is then assigned the binary value 1 or 0,
corresponding to true or false, respectively. The assembler assigns the
explicitly specified binary value (0 or 1) or the computed logical value (0 or
1) to the SETB symbol in the name field.
Rules for Coding Logical Expressions: The following is a summary of coding
rules for logical expressions:
A logical expression must not contain two logical terms in succession.
A logical expression can contain two logical operators in succession; however,
the only allowed combinations are OR NOT, XOR NOT and AND NOT. The
two operators must be separated from each other by one or more spaces.
Any logical term, relation, or inner logical expression can be optionally enclosed
in parentheses.
The relational and logical operators must be immediately preceded and
followed by at least one space, except when written (NOT bexpr).
A logical expression can begin with the logical unary operator NOT.
A logical expression can contain up to 18 logical operators. The relational and
other operators used by the arithmetic and character expressions in relations
do not count toward this total.
Up to 255 levels of nested parentheses are allowed.
Absolute ordinary symbols specified in logical expressions must be defined
before the logical expression is encountered.
The assembler determines the type of a logical relation by the first comparand.
If the first comparand is a character expression that begins with a single
quotation mark, then the logical relation is a character relation, otherwise the
assembler treats it as an arithmetic relation.

Chapter 9. How to Write Conditional Assembly Instructions

363

SETB Instruction

|
|
|
|
|
|
|
|

Logical

Expression

Can be any of

Logical Operators Allowed

OR
Intersection

AND
Union
Logical Logical
OR NOT
Logical
NOT
Logical

NOT
Negation
Term
Expression AND
Term

Expression
XOR
Exclusive OR

AND NOT

XOR

XOR NOT

Can be any of

SETB

Predefined

Logical Variable Arithmetic

1
Absolute Logical
Relation Symbol
Value

Ordinary Function

Symbol

Can be any of

Arithmetic
Character
Relation

Relation

Relational Operators Allowed

Which is
Which is

EQ
Equal

EQ, NE

NE
Not equal
Arithmetic LE, LT
Arithmetic
Character LE, LT
Character
LE
Less than or equal
Comparand GE, GT
Comparand
Comparand GE, GT
Comparand
LT
Less than

GE
Greater than or equal

GT
Greater than

Which can be
Can be any of

Type
Character
Arithmetic
Character Substring Attribute Exp. and

Expression
Expression Notation Reference Substring

Notation

Notes:
1. Outermost expression must be enclosed in parentheses in SETB and AIF instructions.
2. Optional parentheses around terms and expressions at this level.

3. Must be in the range 0 through 1024 characters.

4. Must stand alone and not be enclosed in single quotation marks.

Figure 101. Defining Logical Expressions

Subscripted SETB Symbols

The SETB symbol in the name field can be subscripted, but only if the same SETB
symbol has been previously declared in a GBLB or LCLB instruction with an
allowable dimension.
The assembler assigns the binary value explicitly specified, or implicit in the logical
expression present in the operand field, to the position in the declared array given
by the value of the subscript. The subscript expression must not be 0 or have a
negative value.

364

HLASM V1R5 Language Reference

SETB Instruction

Logical (SETB) Expressions

You can use a logical expression to assign a binary value to a SETB symbol. You
can also use a logical expression to represent the condition test in an AIF
instruction. This use lets you code a logical expression whose value (0 or 1) varies
according to the values substituted into the expression and thereby determine
whether or not a branch is to be taken.
Figure 101 on page 364 defines a logical expression.
It is important to note that logical expressions contain unquoted spaces that do not
terminate the operand field. This is called logical-expression format, and such
expressions are always enclosed in parentheses.
A logical expression can consist of a logical expression and a logical term
separated by a logical operator delimited by spaces. The logical operators are:
AND
Format: Logical-expression
Operands: Binary
Output: (aexpr1 AND aexpr2) has value 1, if each logical expression
evaluates to 1, otherwise the value is 0.
Example
After the following statements &VAR contains the arithmetic value .
Name

Operation

Operand

&OP1
&OP2
&VAR

SETB
SETB
SETB

1

(&OP1 AND &OP2)

AND NOT
Format: Logical-expression
Operands: Binary
Output: The value of the second logical term is inverted, and the expression
is evaluated as though the AND operator was specified.
Example
(1 AND NOT ) is equivalent to (1 AND 1).
|

ISBIN

|
|

Format: Function-invocation
Operands: Character

|
|
|
|

Output: ISBIN('cexpr') determines the validity of cexpr, a string of 1 to 32

characters, as the nominal value of a binary self-defining term usable in a
SETA expression. If valid, ISBIN returns 1; otherwise, it returns zero. The
argument string may not be null.

Example

|
|
|
|

ISBIN('111')
returns 1
ISBIN('11111111111111111') returns (excess digits)
ISBIN('12121')
returns (non-binary digits)
ISBIN('')
indicates an error condition

Chapter 9. How to Write Conditional Assembly Instructions

365

SETB Instruction

ISDEC

|
|

Format: Function-invocation
Operands: Character

|
|
|
|

Output: ISDEC('cexpr') determines the validity of cexpr, a string of 1 to 10

characters, as the nominal value of a decimal self-defining term usable in a
SETA expression. If valid, ISDEC returns 1; otherwise, it returns zero. The
argument string may not be null.

Example

|
|
|
|
|

ISDEC('12345678')
ISDEC('+25')
ISDEC('2147483648')
ISDEC('5')
ISDEC('')

returns 1
returns
returns
returns
indicates

(non-decimal character)
(value too large)
(too many characters)
an error condition

ISHEX

|
|

Format: Function-invocation
Operands: Character

|
|
|
|

Output: ISHEX('cexpr') determines the validity of cexpr, a string of 1 to 8

characters, as the nominal value of a hexadecimal self-defining term usable in
a SETA expression. If valid, ISHEX returns 1; otherwise, it returns zero. The
argument string may not be null.

Example

|
|
|
|

ISHEX('ab34CD9F')
ISHEX('abcdEFGH')
ISHEX('123456789')
ISHEX('')

returns 1
returns (non-hexadecimal digits)
returns (too many characters)
indicates an error condition

ISSYM

|
|

Format: Function-invocation
Operands: Character

|
|
|

Output: ISSYM('cexpr') determines the validity of cexpr, a string of 1 to 63

characters, for use as an ordinary symbol. If valid, ISSYM returns 1;
otherwise, it returns zero. The argument string may not be null.

Examples

|
|
|
|
|

ISSYM('Abcd_1234')
ISSYM('_Abcd1234')
ISSYM('##@$_')
ISSYM('1234_Abcd')
ISSYM('')

returns 1
returns 1
returns 1
returns (invalid initial character)
indicates an error condition

NOT
Format:
Logical-expression, function-invocation
Operands: Binary
Output: NOT(bexp) inverts the value of the logical expression.
OR
Format: Logical-expression
Operands: Binary

366

HLASM V1R5 Language Reference

SETB Instruction

Output: (bexp1 OR bexp2) returns a value of 1, if either of the logical

expressions contain or evaluate to 1. If they both contain or evaluate to 0
then the value is 0.
OR NOT
Format: Logical-expression
Operands: Binary
Output: (bexp1 OR NOT bexp2) inverts the value of the second logical term,
and the expression is evaluated as though the OR operator was specified.
For example, (1 OR NOT 1) is equivalent to (1 OR ).
XOR
Format: Logical-expression
Operands: Binary
Output: (bexp1 XOR bexp2) evaluates to 1 if the logical expressions contain
or evaluate to opposite bit values. If they both contain or evaluate to the same
bit value, the result is 0.
XOR NOT
Format: Logical-expression
Operands: Binary
Output: (bexp1 XOR NOT bexp2) inverts the second logical term, and the
expression is evaluated as though the XOR operator was specified.
Example (1 XOR NOT 1) is equivalent to (1 XOR ).
Relational Operators: Relational operators provide the means for comparing two
items. A relational operator plus the items form a relation. An arithmetic relation is
two arithmetic expressions separated by a relational operator, and a character
relation is two character strings (for example, a character expression and a type
attribute reference) separated by a relational operator.
The relational operators are:
EQ
NE
LE
LT
GE
GT

equal
not equal
less than or equal
less than
greater than or equal
greater than

Evaluation of Logical Expressions: The assembler evaluates logical

expressions as follows:
1. It evaluates each logical term, which is given a binary value of 0 or 1.
2. If the logical term is an arithmetic or character relation, the assembler
evaluates:
a. The arithmetic or character expressions specified as values for comparison
in these relations
b. The arithmetic or character relation
c. The logical term, which is the result of the relation. If the relation is true,
the logical term it represents is given a value of 1; if the relation is false,
the term is given a value of 0.
Chapter 9. How to Write Conditional Assembly Instructions

367

SETB Instruction

The two comparands in a character relation are compared, character by

character, according to binary (EBCDIC) representation of the characters. If
two comparands in a relation have character values of unequal length, the
assembler always takes the shorter character value to be less.
3. The assembler carries out logical operations from left to right. However,
a. It carries out logical NOTs before logical ANDs, ORs and XORs
b. It carries out logical ANDs before logical ORs and XORs
c. It carries out logical ORs before logical XORs
4. In parenthesized logical expressions, the assembler evaluates the innermost
expressions first, and then considers them as logical terms in the next outer
level of expressions. It continues this process until it evaluates the outermost
expression.
Using SETB Symbols: The logical value assigned to a SETB symbol is used for
the SETB symbol appearing in the operand field of an AIF instruction or another
SETB instruction.
If a SETB symbol is used in the operand field of a SETA instruction, or in arithmetic
relations in the operand fields of AIF and SETB instructions, the binary values 1
(true) and 0 (false) are converted to the arithmetic values 1 and 0, respectively.
If a SETB symbol is used in the operand field of a SETC instruction, in character
relations in the operand fields of AIF and SETB instructions, or in any other
statement, the binary values 1 (true) and 0 (false), are converted to the character
values '1' and '', respectively.
The following example illustrates these rules. It assumes that (L'&TO EQ 4) is true,
and (S'&TO EQ ) is false.
MACRO
MOVE
&TO,&FROM
LCLA
&A1
LCLB
&B1,&B2
LCLC
&C1
&B1
SETB
(L'&TO EQ 4)
Statement 1
&B2
SETB
(S'&TO EQ )
Statement 2
&A1
SETA
&B1
Statement 3
&C1
SETC
'&B2'
Statement 4
ST
2,SAVEAREA
L
2,&FROM&A1
ST
2,&TO&C1
L
2,SAVEAREA
MEND
------------------------------------------------------------------HERE
MOVE
FIELDA,FIELDB
------------------------------------------------------------------+HERE ST
2,SAVEAREA
+
L
2,FIELDB1
+
ST
2,FIELDA
+
L
2,SAVEAREA
&NAME

Because the operand field of statement 1 is true, &B1 is assigned the binary value
1. Therefore, the arithmetic value +1 is substituted for &B1 in statement 3.

368

HLASM V1R5 Language Reference

SETC Instruction

Because the operand field of statement 2 is false, &B2 is assigned the binary value
. Therefore, the character value is substituted for &B2 in statement 4.

SETC Instruction
The SETC instruction assigns a character value to a SETC symbol. You can
assign whole character strings, or concatenate several smaller strings together.
The assembler assigns the composite string to your SETC symbol. You can also
assign parts of a character string to a SETC symbol by using the substring
notation; see Substring Notation on page 371.
You can change the character value assigned to a SETC symbol. This lets you
use the same SETC symbol with different values for character comparisons in
several places, or for substituting different values into the same model statement.
variable_symbolSETCcharacter_value

variable symbol
is a variable symbol.
A global variable symbol in the name field must have been previously declared
as a SETC symbol in a GBLC instruction. Local SETC symbols need not be
declared in a LCLC instruction. The assembler considers any undeclared
variable symbol found in the name field of a SETC instruction as a local SET
symbol. The variable symbol is assigned a type attribute value of U.
character_value
is a character value that may be specified by one of the following:
An operation code attribute reference
A type attribute reference
A character expression

The assembler assigns the character string value represented in the operand field
to the SETC symbol in the name field. The string length must be in the range 0
(null character string) through 1024 characters.
When a SETA or SETB symbol is specified in a character expression, the unsigned
decimal value of the symbol (with leading zeros removed) is the character value
given to the symbol.
A duplication factor can precede a character expression or substring notation. The
duplication factor can be any non-negative arithmetic expression allowed in the
operand of a SETA instruction. For example:
&C1

SETC

(3)'ABC'

assigns the value 'ABCABCABC' to &C1.

A zero duplication factor results in a null (zero-length) string.

Chapter 9. How to Write Conditional Assembly Instructions

369

SETC Instruction

Notes:
1. The assembler evaluates the represented character string (in particular, the
substring, see Substring Notation on page 371) before applying the
duplication factor. The resulting character string is then assigned to the SETC
symbol in the name field. For example:
&C2

SETC

'ABC'.(3)'ABCDEF'(4,3)

assigns the value 'ABCDEFDEFDEF' to &C2.

2. If the character string contains double-byte data, then redundant SI/SO pairs
are not removed on duplication. For example:
&C3

SETC

(3)'<.A.B>'

assigns the value '<.A.B><.A.B><.A.B>' to &C3.

3. To duplicate double-byte data, without including redundant SI/SO pairs, use the
substring notation. For example:
&C4

SETC

(3)'<.A.B>'(2,4)

assigns the value '.A.B.A.B.A.B' to &C4.

4. To duplicate the arithmetic value of a previously defined ordinary symbol with
an absolute value, first assign the arithmetic value to a SETA symbol. For
example:
A
&A1
&C5

EQU
SETA
SETC

123
A
(3)'&A1'

assigns the value '123123123' to &C5.

Subscripted SETC Symbols

The SETC symbol (see 1 in Figure 102 on page 371) in the name field can be
subscripted, but only if the same SETC symbol has been previously declared (see
2 in Figure 102) in a GBLC or an LCLC instruction with an allowable dimension.
The assembler assigns the character value represented in the operand field to the
position in the declared array (see 3 in Figure 102) given by the value of the
subscript. The subscript expression must not be 0 or have a negative value.

370

HLASM V1R5 Language Reference

Substring Notation

LCLC
&C1,&C2
LCLC
&SUBSCRC(2)
.

1
.
2

.
&SUBSCRC(1) SETC
'ABCDE'
.

3
&SUBSCRC Array:

/ // /

ABCDE

/ // /

1
2
3
4
1
11
12
13
2
Figure 102. Subscripted SETC Symbols

Character (SETC) Expressions

The main purpose of a character expression is to assign a character value to a
SETC symbol. You can then use the SETC symbol to substitute the character
string into a model statement.
You can also use a character expression as a value for comparison in condition
tests and logical expressions. Also, a character expression provides the string from
which characters can be selected by the substring notation.
Substitution of one or more character values into a character expression lets you
use the character expression wherever you need to vary values for substitution or
to control loops.

A character string consists of any combination of characters enclosed in single

quotation marks. Variable symbols are allowed. The assembler substitutes the
representation of their values as character strings into the character expression
before evaluating the expression. Up to 1024 characters are allowed in a character
expression.
An attribute reference must be the only term in a character expression.
Substring Notation: The substring notation lets you refer to one or more
characters within a character string. You can, therefore, either select characters
from the string and use them for substitution or testing, or scan through a complete
string, inspecting each character. By concatenating substrings with other
substrings or character strings, you can rearrange and build your own strings.
The substring notation can be used only in conditional assembly instructions.
Figure 103 shows how to use the substring notation.

Chapter 9. How to Write Conditional Assembly Instructions

371

Figure 103. Substring Notation in Conditional Assembly Instructions

Value
assigned to
SETC Symbol

Used in

Used as

Example

SETC instruction
operand

Operand

&C1

SETC

Part of
operand

&C2

SETC '&C1'(1,2).'DEF'

AIF or SETB
instruction operand
(logical expression)

Character value
in comparand of
character relation

AIF
SETB

'ABC'(1,3)

('&STRING'(1,4) EQ 'AREA').SEQ
('&STRING'(1,4).'9' EQ 'FULL9')

ABC
ABDEF
---

The substring notation must be specified as follows:

'CHARACTER STRING'(e1,e2)
where the CHARACTER STRING is a character expression from which the substring is
to be extracted. The first subscript (e1) shows the position of the first character
that is to be extracted from the character string. The second subscript (e2) shows
the number of characters to be extracted from the character string, starting with the
character indicated by the first subscript. Thus, the second subscript specifies the
length of the resulting substring.
The second subscript value of the substring notation can be specified as an
asterisk (), to indicate that all the characters beginning at the position of the first
expression should be used. The extracted string is equal to the length of the
character expression, less the number of characters before the starting character.
The character string must be a valid character expression with a length, n, in the
range 1 through 1024 characters. The length of the resulting substring must be in
the range 0 through 1024.

|
|

The subscripts, e1 and e2, must be arithmetic expressions.

|
|

When you use subscripted variable symbols in combination with substring notation,
take care to distinguish variable subscripts from substring-operation subscripts.

|
|
|
|
|

&C(1)
&C(2)
&C(3)
&C(4)

LCLC
SETC
SETC
SETC
SETC

&DVAR(1),&SVAR,&C(1)
'&DVAR(5)'
Select
'&SVAR'(1,3)
Select
'&DVAR(5)'(1,3)
Select
'&SYSLIST(1,3)'(1,3) Select

5th element of &DVAR

substring of &SVAR
substring of &DVAR(5)
substring of &SYSLIST(1,3)

Evaluation of Substrings: The following examples show how the assembler

processes substrings depending on the value of the elements n, e1, and e2.
In the usual case, the assembler generates a correct substring of the specified
length:
Notation
'ABCDE'(1,5)
'ABCDE'(2,3)
'ABCDE'(2,)
'ABCDE'(4,)
'&C'(3,3)
'&PARAM'(3,3)

372

HLASM V1R5 Language Reference

Value of Variable
Symbol

Character Value
of Substring

ABCDE
((A+3)1)

ABCDE
BCD
BCDE
DE
CDE
A+3

When e1 has a zero or negative value, the assembler generates a null string
and issues error message ASMA93E.
Notation

Character Value
of Substring

'ABCDE'(,5)
'ABCDE'(,)

null character string

When the value of e1 exceeds n, the assembler generates a null string and
issues error message ASMA92E.
Notation

Value of Variable
Symbol

'ABCDE'(7,3)
'ABCDE'(6,)

Character Value
of Substring
null character string
null character string

When e2 has a value less than one, the assembler generates the null character
string. If e2 is negative, the assembler also issues error message ASMA95W.
Notation

Value of Variable
Symbol

'ABCDE'(4,)
'ABCDE'(3,-2)

Character Value
of Substring
null character string
null character string

When e2 indexes past the end of the character expression (that is, e1+e2 is
greater than n+1), the assembler issues warning message ASMA94I, and
generates a substring that includes only the characters up to the end of the
character expression specified.
Notation

Value of Variable
Symbol

'ABCDE'(3,5)

Character Value
of Substring
CDE

Figure 104 shows the results of an assembly of SETC instructions with different
substring notations.
Loc

Object Code

ASMA93E Substring
ASMA92E Substring

ASMA95W Substring

ASMA94I Substring

Addr1 Addr2

Stmt
Source Statement
8 &STRING SETC 'STRING'
9 &SUBSTR1 SETC '&STRING'(,4)
expression 1 less than 1; default=null - OPENC
1 &SUBSTR2 SETC '&STRING'(7,4)
expression 1 points past string end; default=null - OPENC
11 &SUBSTR3 SETC '&STRING'(3,)
12 &SUBSTR4 SETC '&STRING'(3,-2)
expression 2 less than ; default=null - OPENC
13 &SUBSTR5 SETC '&STRING'(3,4)
14 &SUBSTR6 SETC '&STRING'(3,5)
goes past string end; default=remainder
15
END

HLASM R5.

24/6/11 17.48
8
9
1
11
12
13
14
15

Figure 104. Sample Assembly Using Substring Notation

You can suppress the ASMA094I message by specifying the FLAG(NOSUBSTR)

option or by setting the ACONTROL FLAG(NOSUBSTR) value. When this is done,
the listing changes (Figure 105 on page 374).

Chapter 9. How to Write Conditional Assembly Instructions

373

Loc

Object Code

Addr1 Addr2

Stmt
Source Statement
7
ACONTROL FLAG(NOSUBSTR)
8 &STRING SETC 'STRING'
9 &SUBSTR1 SETC '&STRING'(,4)
ASMA93E Substring expression 1 less than 1; default=null - OPENC
1 &SUBSTR2 SETC '&STRING'(7,4)
ASMA92E Substring expression 1 points past string end; default=null - OPENC
11 &SUBSTR3 SETC '&STRING'(3,)
12 &SUBSTR4 SETC '&STRING'(3,-2)
ASMA95W Substring expression 2 less than ; default=null - OPENC
13 &SUBSTR5 SETC '&STRING'(3,4)
14 &SUBSTR6 SETC '&STRING'(3,5)
15
END

HLASM R5.

24/6/11 17.48
8
9
1
11
12
13
14
15

Figure 105. Sample Assembly Using Substring Notation With Messages Suppressed

Character (SETC) expressions can be used only in conditional assembly

instructions. Figure 106 shows examples of using character expressions.
Figure 106. Use of Character Expressions

|
|
|
|
|

Used in

Used as

Example

SETC instruction

Operand

AIF or SETB instruction

Character string
in character
relation

AIF

Substring notation

First part of
notation

'SELECT'(2,5) returns 'ELECT'

Built-in functions

Operand

&VAR
&AB

SETC

'STRING'

('&C' EQ 'STRING1').B

SETC
SETA

(LOWER '&twenty.&six')
A2B('1')

Character-Valued Built-in Functions: Character-valued built-in functions have

arithmetic-only operands, character-only operands, or both arithmetic and character
operands. Each type is described in a separate section. The maximum string
length of any SETC variable is 1024 bytes. If this length is exceeded, the string
value is truncated, and message ASMA091E is generated.
Here are the SETC built-in functions:

A2B

|
|

Format: Function-invocation
Operands: Arithmetic

|
|
|
|

Output: A2B(aexpr) converts the value of its arithmetic argument to a string

of 32 zero ('') and one ('1') characters. The value of aexpr must be
representable as a 32-bit binary integer. If the aexpr argument is negative,
the result contains 32 characters, the first of which is '1'.

Examples

|
|
|
|
|

A2B()
A2B(5)
A2B(122)
A2B(-7)
A2B(234567891)

374

HLASM V1R5 Language Reference

has value
has value
has value
has value
indicates

''
'11'
'111111111'
'111111111111111111111111111111'
an error (value too large)

A2C

|
|

Format: Function-invocation
Operands: Arithmetic

|
|
|

Output: A2C(aexpr)
converts the value of its arithmetic argument to a string of four characters
whose bit pattern is the same as the argument's.

Examples

|
|
|
|

A2C()
A2C(241)
A2C(246)
A2C(-252645136)

has
has
has
has

value
value
value
value

'nnnn' (4 EBCDIC nulls)

'nnn1'
'nn++'
''

A2D

|
|

Format: Function-invocation
Operands: Arithmetic

|
|

Output: A2D(aexpr) converts the value of its arithmetic argument to a string

of decimal digits preceded by a plus or minus sign.

|
|

Note: The A2D function is similar to the SIGNED function, except that A2D
always provides an initial sign character.

Examples

|
|
|
|

A2C()
A2C(241)
A2C(16448)
A2C(-3)

has
has
has
has

value
value
value
value

'+'
'+241'
'+16448'
'-3'

A2X

|
|

Format: Function-invocation
Operands: Arithmetic

|
|

Output: A2X(aexpr) converts the value of its arithmetic argument to a string

of eight hexadecimal characters.

Examples

|
|
|
|
|

A2X()
A2X(1)
A2X(257)
A2X(122)
A2X(-7)

has
has
has
has
has

value
value
value
value
value

''
'A'
'11'
'3FE'
'FFFFFFF9'

B2C

|
|

Format: Function-invocation
Operands: Character

|
|
|

Output: B2C('bitstring') converts the bit-string character argument to

characters representing the same bit pattern. Null arguments return a null
string.

|
|

If needed, the argument string is padded internally on the left with zeros so
that its length is a multiple of eight.

|
|

The operand must contain only ones and zeros. Any other value causes the
message ASMA214E to be generated.

Examples

Chapter 9. How to Write Conditional Assembly Instructions

375

|
|
|
|
|
|

B2C('111111')
B2C('111111111')
B2C('')
B2C('111')
B2C('')
B2C('')

has
has
has
has
has
has

value
value
value
value
value
value

'3'
'1'
'n' (EBCDIC null character)
'nj'
'nn' (two EBCDIC nulls)
'' (null string)

B2D

|
|

Format: Function-invocation
Operands: Character

|
|
|
|

Output: B2D('bitstring') converts a bit-string argument of at most 32 ''

and '1' characters to one to ten decimal characters preceded by a plus or
minus sign, representing the value of the argument. Null arguments return
'+'.

Examples

|
|
|
|
|

B2D('')
has value '+'
B2D('111')
has value '+145'
B2D('11111')
has value '+241'
B2D('1111111111111111111111111111111') has value '+2147483647'
B2D('11111111111111111111111111111') has value '-15'

B2X

|
|

Format: Function-invocation
Operands: Character

|
|
|

Output: B2X('bitstring') converts the bit-string argument to hexadecimal

characters representing the same bit pattern. Null arguments return a null
string.

|
|

If needed, the argument string is padded internally on the left with zeros so
that its length is a multiple of four.

|
|

The operand must contain only ones and zeros. Any other value causes the
message ASMA214E to be generated.

Examples

|
|
|
|
|

B2X('')
B2X('')
B2X('111')
B2X('11111')
B2X('1111111')

has
has
has
has
has

value
value
value
value
value

'' (null string)

''
'91'
'F1'
'3F1'

BYTE
Format: Logical-expression, function-invocation
Operands: Arithmetic
Output: BYTE(aexpr) or (BYTE aexpr) returns a one-character EBCDIC
character expression in which the binary value of the character is specified by
the arithmetic argument. The argument must have a value between 0 and
255, inclusive.
This function might be used to introduce characters which are not on the
keyboard.
Examples

376

HLASM V1R5 Language Reference

BYTE()
BYTE(97)
BYTE(129)
|

has value 'n' (EBCDIC null character)

has value '/'
has value 'a'

C2B

|
|

Format: Function-invocation
Operands: Character

|
|
|

Output: C2B('charstring') converts the character argument to a string of ''

and '1' characters representing the same bit pattern. Null arguments return
a null string.

|
|

If the result is not too long, the length of the result is eight times the length of
the 'charstring' argument.

Examples

|
|
|
|
|

C2B('')
C2B('n')
C2B(' ')
C2B('1')
C2B('1234')

has
has
has
has
has

value
value
value
value
value

''
''
'1'
'11111'
'111111111111111111111'

C2D

|
|

Format: Function-invocation
Operands: Character

|
|
|
|

Output: C2D('charstring') converts a character-string argument of at most

four characters to one to ten decimal characters preceded by a plus or minus
sign, representing the numeric value of the argument. Null arguments return
'+'.

Examples

|
|
|
|

C2D('')
C2D('nj')
C2D('1')
C2D('')

has
has
has
has

value
value
value
value

'+'
'+145'
'+241'
'-2526451

C2X

|
|

Format: Function-invocation
Operands: Character

|
|
|

Output: C2X('charstring') converts the character-string argument to

hexadecimal characters representing the same bit pattern. Null arguments
return a null string.

|
|

If the result is not too long, the length of the result is two times the length of
the 'charstring' argument.

Examples

|
|
|
|
|

C2X('')
C2X('n')
C2X('1')
C2X('a')
C2X('1234567R')

|
|
|

has
has
has
has
has

value
value
value
value
value

''
''
'F1'
'81'
'F1F2F3F4F5F6F7D9'

D2B
Format: Function-invocation
Operands: Character

Chapter 9. How to Write Conditional Assembly Instructions

377

|
|
|
|

Output: D2B('decstring') converts an argument string of optionally signed

decimal characters to a string of 32 '' and '1' characters representing a bit
string with the same binary value. The value of decstring must be
representable as a 32-bit binary integer. The argument string may not be null.

Examples

|
|
|
|
|

D2B('')
D2B('')
D2B('+5')
D2B('122')
D2B('-7')

indicates
has value
has value
has value
has value

an error
''
'11'
'111111111'
'111111111111111111111111111111'

D2C

|
|

Format: Function-invocation
Operands: Character

|
|
|
|

Output: D2C('decstring') converts an argument string of optionally signed

decimal characters to a string of four characters whose byte values represent
the same binary value. The value of decstring must be representable as a
32-bit binary integer. The argument string may not be null.

Examples

|
|
|
|
|
|

D2C('')
D2C('')
D2C('126')
D2C('247')
D2C('23793')
D2C('-7')

indicates
has value
has value
has value
has value
has value

an error
'nnnn' (4 EBCDIC null bytes)
'nnn='
'nnn7'
'nn1'
'fff9' (f=byte of all 1-bits)

D2X

|
|

Format: Function-invocation
Operands: Character

|
|
|
|

Output: D2X('decstring') converts an argument string of optionally signed

decimal characters to a string of eight hexadecimal characters whose digits
represent the same hexadecimal value. The value of decstring must be
representable as a 32-bit binary integer. The argument string may not be null.

Examples

|
|
|
|
|
|
|

D2X('')
D2X('')
D2X('+5')
D2X('255')
D2X('122')
D2X('-7')
DSX('234567891')

indicates
has value
has value
has value
has value
has value
causes an

an error
''
'5'
'FF'
'3FE'
'FFFFFFF9'
error condition (value too large)

DCVAL

|
|

Format: Function-invocation
Operands: Character

|
|
|
|
|
|

Output: DCVAL('cexpr') performs a single scan of the argument string to find

successive pairs of apostrophes and ampersands, and returns a string value
in which each such pair has been replaced by a single occurrence. This
pairing action occurs only once; that is, three successive occurrences of an
apostrophe or ampersand will result in two occurrences, not one. A null
argument is returned unchanged.

378

HLASM V1R5 Language Reference

|
|

DCVAL is similar to DCLEN, except that DCLEN returns only the length of the
result, not the paired string.

Examples

|
|
|
|
|
|
|

DCVAL('')
has value "" (null string)
DCVAL('''')
has value "'" (single apostrophe)
DCVAL('&&')
has value "&" (single ampersand)
DCVAL('a''''b')
has value "a'b"
DCVAL('a''''b&&c')
has value "a'b&c"
. Suppose &C has value "&&&'''" (3 ampersands, 3 apostrophes)
&X SETC DCVAL('&C') &X has value "&&''" (2 of each)

DEQUOTE

|
|

Format: Function-invocation
Operands: Character

|
|
|

Output: DEQUOTE('cexpr') removes a single occurrence of an apostrophe

from each end of the argument string, if any are present. A null argument is
returned unchanged.

Examples

|
|
|
|
|
|
|
|

&C
&C
&C
&ARG
&C
&C
&ARG
&C

DOUBLE

SETC
SETC
SETC
SETC
SETC
SETC
SETC
SETC

DEQUOTE('charstring')
DEQUOTE('')
DEQUOTE('a')
'''a'''
DEQUOTE('&ARG')
DEQUOTE('a''b')
''''''
DEQUOTE('&ARG')

&C has value "charstring"

&C is a null string
&C has value "a"
&ARG has value "'a'"
&C has value "a"
&C has value "a'b"
&ARG has value "''"
&C has value "" (null string)

|
|

Format: Logical-expression, function-invocation

Operands: Character

|
|
|
|
|

Output: DOUBLE('cexpr') or (DOUBLE 'cexpr') converts each occurrence of

an apostrophe or ampersand character in the argument string to a pair of
apostrophes and ampersands. In this form, the string is suitable for
substitution into statements such as DC and MNOTE. Null arguments return
a null string. An error condition is detected if the resulting string is too long.

Examples

|
|

Suppose the SETC variable &C contains the characters "&&''&" (two
apostrophes, three ampersands):

DOUBLE('&C')

has value "&&&&''''&&"

LOWER
Format: Logical-expression, function-invocation
Operands: Character
Output: LOWER('cexpr') or (LOWER 'cexpr') converts the alphabetic
characters A-Z in the argument to lower case, a-z. Null arguments return a
null string.
Examples
LOWER('aBcDefG')

has value 'abcdefg'

Chapter 9. How to Write Conditional Assembly Instructions

379

SIGNED
Format: Logical-expression, function-invocation
Operands:
Arithmetic
Output: SIGNED(aexpr) or (SIGNED aexpr) converts its arithmetic argument to
a decimal character string representation of its value, with a leading minus
sign if the argument is negative.
Examples
SIGNED(1)
SIGNED(-1)

has value '1'

has value '-1'

Note: The SIGNED function creates properly signed values for display,
whereas assigning a SETA value to a SETC variable produces only the
magnitude of the SETA value. For example:
&A
&C
&A
&C
|

SETA
SETC
SETA
SETC

1
'&A'
-1
'&A'

&A
&C
&A
&C

has
has
has
has

value
value
value
value

1
'1'
-1
'1' (unsigned)

SYSATTRA

|
|

Format: Function-invocation
Operands: Character

|
|

Output: SYSATTRA('symbol') returns the assembler-type value for the

specified symbol.

The 1 to 4 assembler type is returned, with trailing spaces removed.

Symbols without an assigned assembler type return null.

Examples

|
|

Given that symbol Sym1 has previously been assigned an assembler type of
GR, and variable symbol &SName has a value of SYM1, then:

|
|

SYSATTRA('Sym1')
SYSATTRA('&Sname')

has value 'GR'

SYSATTRP

|
|

Format: Function-invocation
Operands: Character

|
|

Output: SYSATTRP('symbol') returns the program-type value for the specified

symbol.

The 4 byte program type is returned.

Symbols without an assigned program type return null.

Examples

|
|

Given that symbol Sym1 has previously been assigned a program type of
Box7, and variable symbol &SName has a value of SYM1, then:

|
|

SYSATTRP('Sym1')
SYSATTRP('&SName')

has value 'Box7'

UPPER
Format: Logical-expression, function-invocation
Operands: Character

380

HLASM V1R5 Language Reference

Output: UPPER('cexpr') or (UPPER 'cexpr') converts the alphabetic

characters a-z in the argument to upper case, A-Z. Null arguments return a
null string.
Examples
UPPER('aBcDefG')
|

has value 'ABCDEFG'

X2B

|
|

Format: Function-invocation
Operands: Character

|
|
|
|

Output: X2B('hexstring') converts the value of its argument string of

hexadecimal characters to a character string containing only zero ('') and
one ('1') characters representing the same bit pattern. Null arguments return
a null string.

|
|

If the result is not too long, the length of the result is four times the length of
the 'hexstring' argument.

|
|

The operand must contain only hexadecimal digits. Any other value causes
the message ASMA214E to be generated.

Examples

|
|
|
|
|

X2B('')
X2B('')
X2B('1')
X2B('F3')
X2B('F3')

has
has
has
has
has

value
value
value
value
value

'' (null string)

''
'1'
'111111'
'111111'

X2C

|
|

Format: Function-invocation
Operands: Character

|
|

Output: X2C('hexstring') converts the hexstring argument to characters

representing the same bit pattern. Null arguments return a null string.

|
|

If needed, the argument string is padded internally on the left with a zero
character so that its length is a multiple of two.

|
|

The operand must contain only hexadecimal digits. Any other value causes
the message ASMA214E to be generated.

Examples

|
|
|
|
|

X2C('')
X2C('F3')
X2C('')
X2C('F1F2F3F4F5')
X2C('F1')

has
has
has
has
has

value
value
value
value
value

'' (null string)

'3'
'n' (EBCDIC null character)
'12345'
'nn1'

X2D

|
|

Format: Function-invocation
Operands: Character

|
|
|
|

Output: X2D('hexstring') converts its argument string of at most eight

hexadecimal characters to one to ten decimal characters preceded by a plus
or minus sign, representing the value of the argument. Null arguments return
'+'. For example:

Chapter 9. How to Write Conditional Assembly Instructions

381

|
|
|
|
|

|
|
|
|
|
|
|
|

X2D('')
X2D('91')
X2D('F1')
X2D('7FFFFFFF')
X2D('FFFFFFF1')

has
has
has
has
has

value
value
value
value
value

'+'
'+145'
'+241'
'+2147483647'
'-15'

Character
Expression

Can be any of

Character CharExpr
Character-Valued (Duplication CharExpr

Value

. Built-In Function Factor)

CharExpr

Period (.) = Concatenation Character

Can be any of

Substring Variable Self Attribute

Symbol
Defining Reference

Term

T' or O'

Figure 107. Defining Character (SETC) Expressions

Notes:
1. The attribute reference term must not be preceded by a duplication factor.
Evaluation of Character Expressions: The value of a character expression is
the character string within the enclosing single quotation marks, after the assembler
carries out any substitution for variable symbols.
Character strings, including variable symbols, can be concatenated to each other
within a character expression. The resultant string is the value of the expression.
Notes:
1. Use two single quotation marks to generate a single quotation mark as part of
the value of a character expression.
The following statement assigns the character value L'SYMBOL to the SETC
symbol &LENGTH.
&LENGTH

SETC

'L''SYMBOL'

2. A double ampersand generates a double ampersand as part of the value of a

character expression. To generate a single ampersand in a character
expression, use the substring notation; for example:
&AMP

SETC

'&&'(1,1)

Note: A quoted single ampersand '&' is not a valid character string.

382

HLASM V1R5 Language Reference

The following statement assigns the character value HALF&& to the SETC
symbol &AND.
&AND

SETC

'HALF&&'

This is the only instance when the assembler does not pair ampersands to
produce a single ampersand. However, if you substitute a SETC symbol with
such a value into the nominal value in a DC instruction operand, or the operand
of an MNOTE instruction, when the assembler processes the DC or MNOTE
instruction, it pairs the ampersands and produces a single ampersand.
3. To generate a period, two periods must be specified after a variable symbol.
For example, if &ALPHA has been assigned the character value AB%4, the
following statement can be used to assign the character value AB%4.RST to the
variable symbol &GAMMA.
&GAMMA

SETC

'&ALPHA..RST'

4. To generate a period, the variable symbol may have a period as part of its
value. For example:
&DOT
&DELTA

SETC
SETC

'.'
'A&DOT.&DOT'

&DELTA has value 'A..'

5. Double-byte data can appear in the character string if the assembler is invoked
with the DBCS option. The double-byte data must be bracketed by the SO and
SI delimiters, and the double-byte data must be valid.
6. The DBCS ampersand and apostrophe are not recognized as delimiters.
7. A double-byte character that contains the value of an EBCDIC ampersand or
apostrophe in either byte is not recognized as a delimiter when enclosed by SO
and SI.
8. Duplication (replication) factors are permitted before character built-in functions.
|
|
|
|
|

9. Releases of HLASM prior to Version 1 Release 4 permitted predefined absolute

symbols in character expressions. To remove inconsistencies when handling
character and arithmetic expressions such usage is no longer permitted and
results in message ASMA137S if attempted. The built-in function BYTE can be
used to convert a numeric value in a character expression as shown.

|
|

RPTDS
&RPTC1

EQU
SETC

X'1'
'SEND

'.(BYTE RPTDS)

Concatenation of Character String Values: Character expressions can be

concatenated to each other or to substring notations in any order. The resulting
value is a character string composed of the concatenated parts. This concatenated
string can then be used in the operand field of a SETC instruction, or as a value for
comparison in a logical expression.
You need the concatenation character (a period) to separate the single quotation
mark that ends one character expression from the single quotation mark that begins
the next.
For example, either of the following statements may be used to assign the
character value ABCDEF to the SETC symbol &BETA.
&BETA
&BETA

SETC
SETC

'ABCDEF'
'ABC'.'DEF'

Chapter 9. How to Write Conditional Assembly Instructions

383

Concatenation of strings containing double-byte data: If the assembler is invoked

with the DBCS option, then the following additional considerations apply:
When a variable symbol adjoins double-byte data, the SO delimiting the
double-byte data is not a valid delimiter of the variable symbol. The variable
symbol must be terminated by a period.
The assembler checks for SI and SO at concatenation points. If the byte to the
left of the join is SI and the byte to the right of the join is SO, then the SI/SO
pair are considered redundant and are removed.
To create redundant SI/SO pairs at concatenation points, use the substring
notation and SETC expressions to create additional SI and SO characters. By
controlling the order of concatenation, you can leave a redundant SI/SO pair at
a concatenation point.
Instead of substring notation, you can use the BYTE function to create
additional SI and SO characters:
&SO
&SI

SETC (BYTE 14)

SETC (BYTE 15)

Examples:
&DBDA
&SO
&SI
&DBCS1A
&DBCS1E
&DBCS2
&DBCS2A
&DBCS3
&DBCS3P
&DBCS3Q
&DBCS3R

SETC
SETC
SETC
SETC
SETC
SETC
SETC
SETC
SETC
SETC
SETC

'<Da>'
BYTE(X'E')
BYTE(X'F')
'&DBDA.<Db>'
'&DBDA<Db>'
'&DBDA'.'<Db>'
'&DBDA'.'<Db>'.'&DBDA'
'&DBDA'.'&SI'.'&SO'.'<Db>'
'&DBDA'.'&SI'
'&SO'.'<Db>'
'&DBCS3P'.'&DBCS3Q'

These examples use the BYTE function to create variables &SO and &SI, which
have the values of SO and SI, respectively. The variable &DBCS1A is assigned the
value <DaDb> with the SI/SO pair at the join removed. The assignment to variable
&DBCS1E fails with error ASMA35E Invalid delimiter, because the symbol &DBDA is
terminated by SO and not by a period. The variable &DBCS2 is assigned the value
<DaDb>. The variable &DBCS2A is assigned the value <DaDbDa>. As with &DBCS1A,
redundant SI/SO pairs are removed at the joins. The variable &DBCS3 is assigned
the value <DaDb>. Although SI and SO have been added at the join, the
concatenation operation removes two SI and two SO characters, since redundant
SI/SO pairs are found at the second and third concatenations. However, by using
intermediate variables &DBCS3P and &DBCS3Q to change the order of concatenation,
the string <Da><Db> can be assigned to variable &DBCS3R. Note that substituting the
variable symbol &DBCS3R in the nominal value of a G-type constant results in
removal of the SI/SO pair at the join.

Using SETC Symbols

The character value assigned to a SETC symbol is substituted for the SETC
symbol when it is used in the name, operation, or operand field of a statement.
For example, consider the following macro definition, macro instruction, and
generated statements:

384

HLASM V1R5 Language Reference

MACRO
MOVE
&TO,&FROM
LCLC
&PREFIX
&PREFIX SETC
'FIELD'
Statement 1
&NAME
ST
2,SAVEAREA
L
2,&PREFIX&FROM
Statement 2
ST
2,&PREFIX&TO
Statement 3
L
2,SAVEAREA
MEND
------------------------------------------------------------------HERE
MOVE
A,B
------------------------------------------------------------------+HERE ST
2,SAVEAREA
+
L
2,FIELDB
+
ST
2,FIELDA
+
L
2,SAVEAREA
&NAME

Statement 1 assigns the character value FIELD to the SETC symbol &PREFIX. In
statements 2 and 3, &PREFIX is replaced by FIELD.
The following example shows how the value assigned to a SETC symbol may be
changed in a macro definition.
MACRO
MOVE
&TO,&FROM
LCLC
&PREFIX
&PREFIX SETC
'FIELD'
Statement 1
&NAME
ST
2,SAVEAREA
L
2,&PREFIX&FROM
Statement 2
&PREFIX SETC
'AREA'
Statement 3
ST
2,&PREFIX&TO
Statement 4
L
2,SAVEAREA
MEND
------------------------------------------------------------------HERE
MOVE
A,B
------------------------------------------------------------------+HERE ST
2,SAVEAREA
+
L
2,FIELDB
+
ST
2,AREAA
+
L
2,SAVEAREA
&NAME

Statement 1 assigns the character value FIELD to the SETC symbol &PREFIX.
Therefore, &PREFIX is replaced by FIELD in statement 2. Statement 3 assigns the
character value AREA to &PREFIX. Therefore, &PREFIX is replaced by AREA, instead
of FIELD, in statement 4.
The following example uses the substring notation in the operand field of a SETC
instruction.

Chapter 9. How to Write Conditional Assembly Instructions

385

MACRO
MOVE
&TO,&FROM
LCLC
&PREFIX
&PREFIX SETC
'&TO'(1,5)
Statement 1
&NAME
ST
2,SAVEAREA
L
2,&PREFIX&FROM
Statement 2
ST
2,&TO
L
2,SAVEAREA
MEND
------------------------------------------------------------------HERE
MOVE
FIELDA,B
------------------------------------------------------------------+HERE ST
2,SAVEAREA
+
L
2,FIELDB
+
ST
2,FIELDA
+
L
2,SAVEAREA
&NAME

Statement 1 assigns the substring character value FIELD (the first five characters
corresponding to symbolic parameter &TO to the SETC symbol &PREFIX. Therefore,
FIELD replaces &PREFIX in statement 2.
Notes:
1. If the COMPAT(SYSLIST) assembler option is not specified, you can pass a
sublist into a macro definition by assigning the sublist to a SETC symbol, and
then specifying the SETC symbol as an operand in a macro instruction.
However, if the COMPAT(SYSLIST) assembler option is specified, sublists
assigned to SETC symbols are treated as a character string, not as a sublist.
2. Regardless of the setting of the COMPAT(SYSLIST) assembler option, you can
not pass separate (as opposed to a sublist of) parameters into a macro
definition, by specifying a string of values separated by commas as the
operand of a SETC instruction and then using the SETC symbol as an operand
in the macro instruction. If you attempt to do this, the operand of the SETC
instruction is passed to the macro instruction as one parameter, not as a list of
parameters.
Concatenating Substring Notations and Character Expressions: Substring
notations (see Substring Notation on page 371) can be concatenated with
character expressions in the operand field of a SETC instruction. If a substring
notation follows a character expression, the two can be concatenated by placing a
period between the terminating single quotation mark of the character expression
and the opening single quotation mark of the substring notation.
For example, if &ALPHA has been assigned the character value AB%4, and &BETA has
been assigned the character value ABCDEF, the following statement assigns &GAMMA
the character value AB%4BCD:
&GAMMA

SETC

'&ALPHA'.'&BETA'(2,3)

If a substring notation precedes a character expression or another substring

notation, the two can be concatenated by writing the opening single quotation mark
of the second item immediately after the closing parenthesis of the substring
notation.

386

HLASM V1R5 Language Reference

Extended SET Statements

Optionally, you can place a period between the closing parenthesis of a substring
notation and the opening single quotation mark of the next item in the operand
field.
If &ALPHA has been assigned the character value AB%4, and &ABC has been assigned
the character value 5RS, either of the following statements can be used to assign
&WORD the character value AB%45RS.
&WORD
&WORD

SETC
SETC

'&ALPHA'(1,4).'&ABC'
'&ALPHA'(1,4)'&ABC'(1,3)

If a SETC symbol is used in the operand field of a SETA instruction, the character
value assigned to the SETC symbol must be 1-to-10 decimal digits (not greater
than 2147483647), or a valid self-defining term.
If a SETA symbol is used in the operand field of a SETC statement, the arithmetic
value is converted to an unsigned integer with leading zeros removed. If the value
is 0, it is converted to a single 0.

Extended SET Statements

As well as assigning single values to SET symbols, you can assign values to
multiple elements in an array of a subscripted SET symbol with one single SETx
instruction. Such an instruction is called an extended SET statement.

,
operand
variable_symbol(subscript)SETA
SETB
SETC

variable_symbol(subscript)
is a variable symbol and a subscript that shows the position in the SET symbol
array to which the first operand is to be assigned.
operand
is the arithmetic value, binary value, or character value to be assigned to the
corresponding SET symbol array element.
The first operand is assigned to the SET symbol denoted by
variable_symbol(subscript). Successive operands are then assigned to successive
positions in the SET symbol array. If an operand is omitted, the corresponding
element of the array is unchanged. Consider the following example:
LCLA
&LIST(3) SETA

&LIST(5)
5,1,,2,25,3

The first instruction declares &LIST as a subscripted local SETA symbol. The
second instruction assigns values to certain elements of the array &LIST. Thus, the
instruction does the same as the following sequence:
&LIST(3)
&LIST(4)
&LIST(6)
&LIST(7)
&LIST(8)

SETA
SETA
SETA
SETA
SETA

5
1
2
25
3

Chapter 9. How to Write Conditional Assembly Instructions

387

SETAF Instruction

Alternative Statement Format: You can use the alternative statement format for
extended SETx statements. The above coding could then be written as follows:
&LIST(3) SETA

5,
1,,
2,25,3

THIS IS
AN ARRAY
SPECIFICATION

X
X

SETAF Instruction
Use the SETAF instruction to call an external function to assign any number of
arithmetic values to a SETA symbol. You can assign a large number of
parametersthe exact number depending on factors such as the size of the
program and of virtual storageto pass to the external function routine.
The SETAF instruction can be used anywhere that a SETA instruction can be used.
variable_symbolSETAF'functionname'

,expression

variable symbol
is a variable symbol.
A global variable symbol in the name field must have been previously declared
as a SETA symbol in a GBLA instruction. Local SETA symbols need not be
declared in a LCLA instruction. The assembler considers any undeclared
variable symbol found in the name field of a SETA instruction as a local SET
symbol.
The variable symbol is assigned a type attribute value of N.
function_name
the name of an external function load module. The name must be specified as
a character expression, and must evaluate to a valid module name no longer
than 8 bytes.
Refer to Chapter 5, Providing External Functions for Conditional Assembly in
the HLASM Programmer's Guide for information about external function load
modules.
expression
is an arithmetic expression evaluated as a signed 32-bit arithmetic value. The
minimum and maximum allowable values of the expression are 231 and
+2311, respectively.
See SETA Instruction on page 347 for further information about setting SETA
symbols, and ways to specify arithmetic expressions.
The function name must be enclosed in single quotes. For example:
&MAX_VAL

388

SETAF

HLASM V1R5 Language Reference

'MAX',7,4

Calls the external function

MAX, passing values 7 and
4 as operands.

X
X

SETCF Instruction

SETCF Instruction
Use the SETCF instruction to call an external function to assign a character value
to a SETC symbol. You can specify a large number of parametersthe exact
number depending on factors such as the size of the program and of virtual
storageto pass to the external function routine.
The SETCF instruction can be used anywhere that a SETC instruction can be
used.
variable_symbolSETCF'functionname'

,character_value

The character value assigned to the variable symbol can have a string length in
the range 0 (for a null character string) through 1024.
function_name
the name of an external function load module. The name must be specified as
a character expression, and must evaluate to a valid module name no longer
than 8 bytes.
Refer to Chapter 5, Providing External Functions for Conditional Assembly in
the HLASM Programmer's Guide for information about external function load
modules.
character_value
is a character value that may be specified by one of the following:

A type attribute reference

An operation code attribute reference
A character expression
A substring notation
A concatenation of one or more of the above

The character value can have a string length in the range 0 (for a null character
string) through 1024.
When a SETA or SETB symbol is specified in a character expression, the unsigned
decimal value of the symbol (with leading zeros removed) is the character value
given to the symbol.
See SETC Instruction on page 369 for further information about setting SETC
symbols, and ways to specify character expressions.

Chapter 9. How to Write Conditional Assembly Instructions

389

Branching

Branching
You can control the sequence in which source program statements are processed
by the assembler by using the conditional assembly branch instructions described
in this section.

AIF Instruction
Use the AIF instruction to branch according to the results of a condition test. You
can thus alter the sequence in which source program statements or macro
definition statements are processed by the assembler.
The AIF instruction also provides loop control for conditional assembly processing,
which lets you control the sequence of statements to be generated.
It also lets you check for error conditions and thereby to branch to the appropriate
MNOTE instruction to issue an error message.
AIF(logical_expression)sequence_symbol
sequence_symbol

sequence_symbol
is a sequence symbol
logical_expression
is a logical expression (see Logical (SETB) Expressions on page 365) the
assembler evaluates during conditional assembly time to determine if it is true
or false. If the expression is true (logical value=1), the statement named by the
sequence symbol in the operand field is the next statement processed by the
assembler. If the expression is false (logical value=0), the next sequential
statement is processed by the assembler.
In the following example, the assembler branches to the label .OUT if &C = YES:
.ERROR

.OUT

AIF
ANOP
.
.
.
ANOP

('&C' EQ 'YES').OUT

The sequence symbol in the operand field is a conditional assembly label that
represents a statement number during conditional assembly processing. It is the
number of the statement that is branched to if the logical expression preceding the
sequence symbol is true.
The statement identified by the sequence symbol referred to in the AIF instruction
can appear before or after the AIF instruction. However, the statement must
appear within the local scope of the sequence symbol. Thus, the statement
identified by the sequence symbol must appear:
In open code, if the corresponding AIF instruction appears in open code
In the same macro definition in which the corresponding AIF instruction
appears.

390

HLASM V1R5 Language Reference

AIF Instruction

You cannot branch from open code into a macro definition or between macro
definitions, regardless of nested calls to other macro definitions.
The following macro definition generates the statements needed to move a fullword
fixed-point number from one storage area to another. The statements are
generated only if the type attribute of both storage areas is the letter F.
&N

.END

MACRO
MOVE
AIF
AIF
ST
L
ST
L
MEND

&T,&F
(T'&T NE T'&F).END
(T'&T NE 'F').END
2,SAVEAREA
2,&F
2,&T
2,SAVEAREA

Statement 1
Statement 2
Statement 3

Statement 4

The logical expression in the operand field of Statement 1 has the value true if the
type attributes of the two macro instruction operands are not equal. If the type
attributes are equal, the expression has the logical value false.
Therefore, if the type attributes are not equal, Statement 4 (the statement named
by the sequence symbol .END) is the next statement processed by the assembler.
If the type attributes are equal, Statement 2 (the next sequential statement) is
processed.
The logical expression in the operand field of Statement 2 has the value true if the
type attribute of the first macro instruction operand is not the letter F. If the type
attribute is the letter F, the expression has the logical value false.
Therefore, if the type attribute is not the letter F, Statement 4 (the statement named
by the sequence symbol .END) is the next statement processed by the assembler.
If the type attribute is the letter F, Statement 3 (the next sequential statement) is
processed.

Extended AIF Instruction

The extended AIF instruction combines several successive AIF statements into one
statement.

AIF
sequence_symbol
,
(logical_expression)sequence_symbol

sequence_symbol
is a sequence symbol
logical_expression
is a logical expression the assembler evaluates during conditional assembly
time to determine if it is true or false. If the expression is true (logical value=1),
the statement named by the sequence symbol in the operand field is the next
statement processed by the assembler. If the expression is false (logical
value=0), the next logical expression is evaluated.

Chapter 9. How to Write Conditional Assembly Instructions

391

AGO Instruction

The extended AIF instruction is exactly equivalent to n successive AIF statements.

The branch is taken to the first sequence symbol (scanning left to right) whose
corresponding logical expression is true. If none of the logical expressions is true,
no branch is taken.
Example:
AIF

('&L'(&C,1)
('&L'(&C,1)
('&L'(&C,1)
('&L'(&C,1)
('&L'(&C,1)
('&L'(&C,1)
('&L'(&C,1)

EQ
EQ
EQ
EQ
EQ
EQ
EQ

'$').DOLR,
'#').POUND,
'@').AT,
'=').EQUAL,
'(').LEFTPAR,
'+').PLUS,
'-').MINUS

Cont.
X
X
X
X
X
X

This statement looks for the occurrence of a $, #, @, =, (, +, and -, in that order;

and causes control to branch to .DOLR, .POUND, .AT, .EQUAL, .LEFTPAR, .PLUS, and
.MINUS, respectively, if the string being examined contains any of these characters
at the position designated by &C.

Alternative Format for AIF Instruction

The alternative statement format is allowed for extended AIF instructions. This
format is illustrated in the above example.

AIFBSynonym of the AIF Instruction

For compatibility with some earlier assemblers, High Level Assembler supports the
AIFB symbolic operation code as a synonym of the AIF instruction. However, you
should not use the AIFB instruction in new applications as support for it might be
removed in the future.

AGO Instruction
The AGO instruction branches unconditionally. You can thus alter the sequence in
which your assembler language statements are processed. This provides you with
final exits from conditional assembly loops.
AGOsequence_symbol
sequence_symbol

sequence_symbol
is a sequence symbol.
The statement named by the sequence symbol in the operand field is the next
statement processed by the assembler.
The statement identified by a sequence symbol referred to in the AGO instruction
can appear before or after the AGO instruction. However, the statement must
appear within the local scope of the sequence symbol. Thus, the statement
identified by the sequence symbol must appear:
In open code, if the corresponding AGO instruction appears in open code
In the same macro definition in which the corresponding AGO instruction
appears.

392

HLASM V1R5 Language Reference

AGO Instruction

Example:
&NAME

.FIRST
&NAME

.END

MACRO
MOVE
AIF
AGO
AIF
ST
L
ST
L
MEND

&T,&F
(T'&T EQ 'F').FIRST
.END
(T'&T NE T'&F).END
2,SAVEAREA
2,&F
2,&T
2,SAVEAREA

Statement 1
Statement 2
Statement 3

Statement 4

Statement 1 determines if the type attribute of the first macro instruction operand is
the letter F. If the type attribute is the letter F, Statement 3 is the next statement
processed by the assembler. If the type attribute is not the letter F, Statement 2 is
the next statement processed by the assembler.
Statement 2 indicates to the assembler that the next statement to be processed is
Statement 4 (the statement named by sequence symbol .END).

Computed AGO Instruction

The computed AGO instruction makes branches according to the value of an
arithmetic expression specified in the operand.

AGO
sequence_symbol
,
sequence_symbol
(arithmetic_expression)

sequence_symbol
is a sequence symbol.
arithmetic_expression
is an arithmetic expression the assembler evaluates to k, where k lies between
1 and n (the number of occurrences of sequence_symbol in the operand field)
inclusive. The assembler branches to the k-th sequence symbol in the list. If k
is outside that range, no branch is taken.
In the following example, control passes to the statement at .THIRD if &I= 3.
Control passes through to the statement following the AGO if &I is less than 1 or
greater than 4.
AGO

(&I).FIRST,.SECOND,
.THIRD,.FOURTH

Cont.
X

Alternative Format for AGO Instruction

The alternative statement format is allowed for computed AGO instructions. The
above example could be coded as follows:
AGO

(&I).FIRST,
.SECOND,
.THIRD,
.FOURTH

Cont.
X
X
X

Chapter 9. How to Write Conditional Assembly Instructions

393

ACTR Instruction

AGOBSynonym of the AGO Instruction

For compatibility with some earlier assemblers, High Level Assembler supports the
AGOB symbolic operation code as a synonym of the AGO instruction. However,
you should not use the AGOB instruction in new applications as support for it might
be removed in the future.

ACTR Instruction
The ACTR instruction sets a conditional assembly branch counter either within a
macro definition or in open code. The ACTR instruction can appear anywhere in
open code or within a macro definition.
Each time the assembler processes an AIF or AGO branching instruction in a
macro definition or in open code, the branch counter for that part of the program is
decremented by one. When the number of conditional assembly branches reaches
the value assigned to the branch counter by the ACTR instruction, the assembler
exits from the macro definition or stops processing statements in open code.
By using the ACTR instruction, you avoid excessive looping during conditional
assembly processing.
ACTRarithmetic_expression
sequence_symbol

sequence_symbol
is a sequence symbol.
arithmetic_expression
is an arithmetic expression used to set or reset a conditional assembly branch
counter.
A conditional assembly branch counter has a local scope; its value is decremented
by AGO and successful AIF instructions, and reassigned only by ACTR instructions
that appear within the same scope. Thus, the nesting of macros has no effect on
the setting of branch counters in other scopes. The assembler assigns a branch
counter for open code and for each macro definition. In the absence of an ACTR
instruction, a default value of 4096 is assigned.

Branch Counter Operations

Within the scope of a branch counter, the following occurs:
1. Each time an AGO or AIF branch is executed, the assembler checks the
branch counter for zero or a negative value.
2. If the count is not zero or negative, it is decremented by one.
3. If the count is zero or negative, the assembler takes one of two actions:
a. If it is processing instructions in open code, the assembler processes the
remainder of the instructions in the source module as comments. Errors
discovered in these instructions during previous passes are flagged.
b. If it is processing instructions inside a macro definition, the assembler
terminates the expansion of that macro definition and processes the next
sequential instruction after the calling macro instruction. If the macro
definition is called by an outer macro instruction, the assembler processes

394

HLASM V1R5 Language Reference

ANOP Instruction

the next sequential prototype instruction after the call; that is, it continues
processing at the next outer level of nested macros.
The assembler halves the ACTR counter value when it encounters serious syntax
errors in conditional assembly instructions.

ANOP Instruction
You can specify a sequence symbol in the name field of an ANOP instruction, and
use the symbol as a label for branching purposes.
The ANOP instruction carries out no operation itself, but you can use it to allow
conditional assembly to resume assembly or conditional generation at an instruction
that does not have a sequence symbol in its name field. For example, if you
wanted to branch to a SETA, SETB, or SETC assignment instruction, which
requires a variable symbol in the name field, you could insert a labeled ANOP
instruction immediately before the assignment instruction. By branching to the
ANOP instruction with an AIF or AGO instruction, you would, in effect, be branching
to the assignment instruction.
sequence_symbolANOP

sequence_symbol
is a sequence symbol.
No operation is carried out by an ANOP instruction. Instead, if a branch is taken to
the ANOP instruction, the assembler processes the next sequential instruction.
Example:
&NAME

&TYPE
.FTYPE
&NAME

MACRO
MOVE
LCLC
AIF
SETC
ANOP
ST&TYPE
L&TYPE
ST&TYPE
L&TYPE
MEND

&T,&F
&TYPE
(T'&T EQ 'F').FTYPE
'E'
2,SAVEAREA
2,&F
2,&T
2,SAVEAREA

Statement
Statement
Statement
Statement

1
2
3
4

Statement 1 determines if the type attribute of the first macro instruction operand is
the letter F. If the type attribute is not the letter F, Statement 2 is the next
statement processed by the assembler. If the type attribute is the letter F,
Statement 4 should be processed next. However, because there is a variable
symbol (&NAME) in the name field of Statement 4, the required sequence symbol
(.FTYPE) cannot be placed in the name field. Therefore, an ANOP instruction
(Statement 3) must be placed before Statement 4.
Then, if the type attribute of the first operand is the letter F, the next statement
processed by the assembler is the statement named by sequence symbol .FTYPE.
The value of &TYPE retains its initial null character value because the SETC
instruction is not processed. Because .FTYPE names an ANOP instruction, the next

Chapter 9. How to Write Conditional Assembly Instructions

395

ANOP Instruction

statement processed by the assembler is Statement 4, the statement following the

ANOP instruction.

396

HLASM V1R5 Language Reference

MHELP Instruction

Chapter 10. MHELP Instruction

The MHELP instruction controls a set of trace and dump facilities. MHELP
statements can occur anywhere in open code or in macro definitions. MHELP
options remain in effect until superseded by another MHELP statement.

MHELP Options
Options are selected by an absolute expression in the MHELP operand field.

MHELPoptions
sequence_symbol

sequence_symbol
is a sequence symbol.
options
is the sum of the binary or decimal options described below.
MHELP B'1' or MHELP 1, Macro Call Trace: This option provides a one-line
trace listing for each macro call, giving the name of the called macro, its nested
depth, and its &SYSNDX value. The trace is provided only upon entry into the
macro. No trace is provided if error conditions prevent entry into the macro.
MHELP B'10' or MHELP 2, Macro Branch Trace: This option provides a
one-line trace-listing for each AGO and AIF conditional assembly branch within a
macro. It gives the model statement numbers of the branched from and the
branched to statements, and the name of the macro in which the branch occurs.
This trace option is suppressed for library macros.
MHELP B'100' or MHELP 4, Macro AIF Dump: This option dumps
undimensioned SET symbol values from the macro dictionary immediately before
each AIF statement that is encountered.
MHELP B'1000' or MHELP 8, Macro Exit Dump: This option dumps
undimensioned SET symbols from the macro dictionary whenever an MEND or
MEXIT statement is encountered.
MHELP B'10000' or MHELP 16, Macro Entry Dump: This option dumps
parameter values from the macro dictionary immediately after a macro call is
processed.
MHELP B'100000' or MHELP 32, Global Suppression: This option suppresses
global SET symbols in two preceding options, MHELP 4 and MHELP 8.
MHELP B'1000000' or MHELP 64, Macro Hex Dump: This option, when used
with the Macro AIF dump, the Macro Exit dump, or the Macro Entry dump, dumps
the parameter and SETC symbol values in EBCDIC and hexadecimal formats.
Only positional and keyword parameters are dumped in hexadecimal; system
parameters are dumped in EBCDIC. The full value of SETC variables or
parameters is dumped in hexadecimal.

397

MHELP Instruction

MHELP B'10000000' or MHELP 128, MHELP Suppression: This option

suppresses all currently active MHELP options.
MHELP Control on &SYSNDX: The maximum value of the &SYSNDX system
variable can be controlled by the MHELP instruction. The limit is set by specifying a
number in the operand of the MHELP instruction that is not one of the MHELP
codes defined above, and is in the following number ranges:
256 to 65535
Most numbers in the range 65792 to 9999999. Refer to MHELP Operand
Mapping below for details.
When the &SYSNDX limit is reached, message ASMA13S ACTR counter exceeded is
issued, and the assembler in effect ignores all further macro calls.

MHELP Operand Mapping

The MHELP operand field is actually mapped into a fullword. The predefined
MHELP codes correspond to the fourth byte of this fullword, while the &SYSNDX
limit is controlled by setting any bit in the third byte to 1. If all bits in the third byte
are 0, then the &SYSNDX limit is not set.
The bit settings for bytes 3 and 4 are shown in Figure 108.
Figure 108. &SYSNDX Control Bits
Byte

Description

Byte 3 - &SYSNDX control

1...
.1..
..1.
...1
....
....
....
....

....
....
....
....
1...
.1..
..1.
...1

Bit
Bit
Bit
Bit
Bit
Bit
Bit
Bit

0
1
2
3
4
5
6
7

=
=
=
=
=
=
=
=

1.
1.
1.
1.
1.
1.
1.
1.

Value=32768. Limit &SYSNDX to 32768.

Value=16384. Limit &SYSNDX to 16384.
Value=8192. Limit &SYSNDX to 8192.
Value=4096. Limit &SYSNDX to 4096.
Value=2048. Limit &SYSNDX to 2048.
Value=1024. Limit &SYSNDX to 1024.
Value=512. Limit &SYSNDX to 512.
Value=256. Limit &SYSNDX to 256.

Byte 4

1...
.1..
..1.
...1
....
....
....
....

....
....
....
....
1...
.1..
..1.
...1

Bit
Bit
Bit
Bit
Bit
Bit
Bit
Bit

0
1
2
3
4
5
6
7

=
=
=
=
=
=
=
=

1.
1.
1.
1.
1.
1.
1.
1.

Value=128. MHELP Suppression.

Value=64. Macro Hex Dump.
Value=32. Global Suppression.
Value=16. Macro Entry Dump.
Value=8. Macro Exit Dump.
Value=4. Macro AIF Dump.
Value=2. Macro Branch Trace.
Value=1. Macro Call Trace.

Note: You can use any combination of bit settings in any byte of the MHELP
fullword to set the limit, provided at least one bit in byte 3 is set. This explains why
not all values between 65792 and 9999999 can be used to set the limit. For
example, the number 131123 does not set the &SYSNDX limit because none of the
bits in byte 3 are set to 1.
Examples:
MHELP
MHELP
MHELP
MHELP

398

256
1
65536
65792

HLASM V1R5 Language Reference

Limit &SYSNDX to 256

Trace macro calls
No effect. No bits in bytes 3,4
Limit &SYSNDX to 65792

MHELP Instruction

See Figure 109 on page 399 for more examples.

Combining Options
More than one MHELP option, including the limit for &SYSNDX, can be specified at
the same time by combining the option codes in one MHELP operand. For
example, call and branch traces can be invoked by:
MHELP B'11'
MHELP 2+1
MHELP 3
Substitution by variable symbols may also be used.

MHELP Instruction

MHELP Operand

MHELP Effect

Decimal
Hexadecimal

&SYSNDX MHELP

MHELP 4869

4869
13

5 Macro call trace and AIF dump;

&SYSNDX limited to 4869

MHELP 65536

65536 1

No effect

MHELP 16777232
16777232 1

1 Macro entry dump

MHELP 28678

28678
7

6 Macro branch trace and AIF dump;

&SYSNDX limited to 28678

MHELP 256+1

257
1

1 Macro call trace;

&SYSNDX limited to 257

MHELP B'11'

3 Macro call trace, and

macro branch trace

Figure 109. MHELP Control on &SYSNDX

Chapter 10. MHELP Instruction

399

400

HLASM V1R5 Language Reference

Appendixes

Part 4. Appendixes
Appendix A. Assembler Instructions

. . . . . . . . . . . . . . . . . . . . . . .

402

Appendix B. Summary of Constants

. . . . . . . . . . . . . . . . . . . . . . .

407

Appendix C. Macro and Conditional Assembly Language Summary

Appendix D. Standard Character Set Code Table

. . . .

409

. . . . . . . . . . . . . . .

421

401

Assembler Instructions and Statements

Appendix A. Assembler Instructions

Figure 110 summarizes the basic formats of assembler instructions, and
Figure 111 on page 405 summarizes assembler statements.
Figure 110 (Page 1 of 5). Assembler Instructions

402

Operation
Entry

Name Entry

Operand Entry

ACONTROL

A sequence symbol or space

One or more operands, separated by

commas

ACTR

A sequence symbol or space

An arithmetic SETA expression

ADATA

A sequence symbol or space

One-to-four decimal, self-defining terms,

and one character string, separated by
commas.

AEJECT

A sequence symbol or space

Taken as a remark

AGO

A sequence symbol or space

A sequence symbol

AIF

A sequence symbol or space

A logical expression enclosed in

parentheses, immediately followed by a
sequence symbol

AINSERT

A sequence symbol or space

A character string, followed by FRONT or

BACK

AMODE

Any symbol or space

24, 31, 64, ANY or ANY31

ALIAS

A symbol

A character string or a hexadecimal string

ANOP

A sequence symbol or space

Taken as a remark

AREAD

Any SETC symbol

NOPRINT, NOSTMT, CLOCKB, CLOCKD,

or spaces

ASPACE

A sequence symbol or space

An absolute expression

CATTR
(MVS and
CMS)

A valid program object

external class name

One or more attributes

CCW

Any symbol or space

Four operands, separated by commas

CCW0

Any symbol or space

Four operands, separated by commas

CCW1

Any symbol or space

Four operands, separated by commas

CEJECT

A sequence symbol or space

An absolute expression or space

CNOP

Any symbol or space

Two absolute expressions, separated by a

comma

COM

Any symbol or space

Taken as a remark

COPY

A sequence symbol or space

An ordinary symbol, or, for open code

statements, a variable symbol

CSECT

Any symbol or space

Taken as a remark

CXD

Any symbol or space

Taken as a remark

Any symbol or space

One or more operands, separated by

commas

DROP

A sequence symbol or space

One or more absolute expressions and

symbols, separated by commas, or space

Assembler Instructions and Statements

Figure 110 (Page 2 of 5). Assembler Instructions

Operation
Entry

Name Entry

Operand Entry

Any symbol or space

One or more operands, separated by

commas

DSECT

A symbol or space

Taken as a remark

DXD4,5

A symbol

One or more operands, separated by

commas

EJECT

A sequence symbol or space

Taken as a remark

END

A sequence symbol or space

A relocatable expression or space

ENTRY

A sequence symbol or space

One or more relocatable symbols,

separated by commas

EQU

A variable symbol or an
ordinary symbol

One to five operands, separated by

commas

EXITCTL

A sequence symbol or space

A character-string operand followed by one

to four decimal self-defining terms,
separated by commas

EXTRN

A sequence symbol or space

One or more relocatable symbols,

separated by commas

GBLA

A sequence symbol or space

One or more variable symbols that are to

be used as SET symbols, separated by
commas

GBLB

A sequence symbol or space

One or more variable symbols that are to

be used as SET symbols, separated by
commas

GBLC

A sequence symbol or space

One or more variable symbols that are to

be used as SET symbols, separated by
commas

ICTL

Space

One to three decimal self-defining terms,

separated by commas

ISEQ

A sequence symbol or space

Two decimal self-defining terms, separated

by a comma, or space

LCLA

A sequence symbol or space

One or more variable symbols that are to

be used as SET symbols, separated by
commas

LCLB

A sequence symbol or space

One or more variable symbols that are to

be used as SET symbols, separated by
commas

LCLC

A sequence symbol or space

One or more variable symbols separated

by commas

LOCTR

A variable or ordinary symbol

Space

LTORG

Any symbol or space

Taken as a remark

MACRO2,5

Space

Taken as a remark

MEND2,5

A sequence symbol or space

Taken as a remark

MEXIT2,5

A sequence symbol or space

Taken as a remark

MHELP

A sequence symbol or space

Absolute expression, binary or decimal

options

Appendix A. Assembler Instructions

403

Assembler Instructions and Statements

Figure 110 (Page 3 of 5). Assembler Instructions

404

Operation
Entry

Name Entry

Operand Entry

MNOTE

A sequence symbol or space

A severity code, followed by a comma,

followed by a 1-to-256-character string
enclosed in single quotation marks.
Double-byte characters are permitted if the
DBCS assembler option is specified.

OPSYN

An ordinary symbol

An machine instruction mnemonic

or an operation code defined by
a previous macro definition or
OPSYN instruction

An operation code mnemonic

Space

ORG

A sequence symbol or space

A relocatable expression or space

POP

A sequence symbol or space

One or more operands, separated by

commas

A sequence symbol or space

One or more operands, separated by

commas

PUNCH

A sequence symbol or space

A 1-to-80-character string enclosed in

single quotation marks. Double-byte
characters are permitted if the DBCS
assembler option is specified.

PUSH

A sequence symbol or space

One or more operands, separated by

commas

REPRO

A sequence symbol or space

Taken as a remark

RMODE

Any symbol or space

24, 31, 64 or ANY

RSECT

Any symbol or space

Taken as a remark

SETA

A SETA symbol

An arithmetic expression

SETAF

A SETA symbol

An external function module, and the

arithmetic expressions it requires,
separated by commas

SETB

A SETB symbol

A 0 or a 1, or a logical expression
enclosed in parentheses

SETC

A SETC symbol

A type attribute, a character expression, a

substring notation, or a concatenation of
character expressions and substring
notations. Double-byte characters are
permitted if the DBCS assembler option is
specified.

SETCF

A SETC symbol

An external function module, and the

character expressions it requires,
separated by commas

SPACE

A sequence symbol or space

An absolute expression

START

Any symbol or space

An absolute expression or space

TITLE3,5

A 1-to-8-character string, a
variable symbol, a
combination of character
string or variable symbol, a
sequence symbol, or space

A 1-to-100-character string enclosed in

single quotation marks. Double-byte
characters are permitted if the DBCS
assembler option is specified.

HLASM V1R5 Language Reference

Assembler Instructions and Statements

Figure 110 (Page 4 of 5). Assembler Instructions

Operation
Entry

Name Entry

Operand Entry

USING

A symbol or space

Either a single absolute or relocatable

expression or a pair of absolute or
relocatable expressions enclosed in
parentheses and followed by 1 to 16
absolute expressions, separated by
commas, or followed by a relocatable
expression

WXTRN

A sequence symbol or space

One or more relocatable symbols,

separated by commas

XATTR
(MVS and
CMS)

An external symbol

One or more operands, separated by

commas

Notes:
1.
2.
3.
4.
5.

SET symbols may be defined as subscripted SET symbols.

May only be used as part of a macro definition.
See TITLE Instruction on page 215 for a description of the name entry.
These instructions start a private section.
These instructions can be specified before the first executable control section.

Figure 111 (Page 1 of 2). Assembler Statements

Instruction Entry

Name Entry

Operand Entry

Model
Statements1 and 2

An ordinary symbol, variable

symbol, sequence symbol, or a
combination of variable
symbols and other characters
that is equivalent to a symbol,
or space

Any combination of characters

(including variable symbols)

Prototype
Statement

A symbolic parameter or space

Zero or more operands that are

symbolic parameters (separated
by commas), and zero or more
operands (separated by
commas) of the form symbolic
parameter, equal sign, optional
standard value

Macro Instruction
Statement

An ordinary symbol, a variable

symbol, or a combination of
variable symbols and other
characters that is equivalent to
a symbol, any character string,
a sequence symbol or space

Zero or more positional

operands (separated by
commas), and zero or more
keyword operands (separated by
commas) of the form keyword,
equal sign, value

Appendix A. Assembler Instructions

405

Assembler Instructions and Statements

Figure 111 (Page 2 of 2). Assembler Statements

Instruction Entry

Name Entry

Operand Entry

Assembler
Language
Statement12

An ordinary symbol, a variable

symbol, a sequence symbol, or
a combination of variable
symbols and other characters
that is equivalent to a symbol,
or space

Any combination of characters

(including variable symbols)

Notes:
1. Variable symbols may be used to generate assembler language mnemonic operation
codes (listed in Chapter 5, Assembler Instruction Statements on page 100), except
COPY, ICTL, ISEQ, and REPRO. Variable symbols may not be used in the name and
operand entries of COPY, ICTL, and ISEQ instructions, except for the COPY instruction
in open code, where a variable symbol is allowed for the operand entry.
2. No substitution is done for variables in the line following a REPRO statement.
3. May only be used as part of a macro definition.
4. When the name field of a macro instruction contains a sequence symbol, the sequence
symbol is not passed as a name field parameter. It only has meaning as a possible
branch target for conditional assembly.
5. Variable symbols appearing in a macro instruction are replaced by their values before
the macro instruction is processed.

406

HLASM V1R5 Language Reference

Summary of Constants

Appendix B. Summary of Constants

Figure 112 and Figure 113 on page 408 summarize the types of assembler
constants.
Figure 112. Summary of Constants (Part 1 of 2)

|
|

Constant

Type

Implicit
Length
(Bytes)

Alignment

Length
Modifier
Range

Specified By

Address

Fullword

.1 to 4

Any expression

Doubleword Address

Doubleword

2 to 8

Any expression

Binary

As needed

Byte

.1 to 256

Binary digits

Character

As needed

Byte

.1 to 256

Characters

ASCII Character

As needed

Byte

.1 to 256

Characters

Unicode Character

As needed

Byte

2 to 256

Characters

Floating Point Hex

Doubleword

.1 to 8

Decimal digits

Floating Point Hex

Doubleword

.12 to 8

Decimal digits

Floating Point Binary

Doubleword

.12 to 8

Decimal digits

Floating Point Hex

Fullword

.1 to 8

Decimal digits

Floating Point Hex

Fullword

.12 to 8

Decimal digits

Floating Point Binary

Fullword

.9 to 8

Decimal digits

Fixed Point

Fullword

.1 to 8

Decimal digits

Doubleword Fixed
Point

Doubleword

.1 to 8

Decimal digits

Graphic (DBCS)

As needed

Byte

2 to 256

DBCS characters

Fixed Point

Halfword

.1 to 8

Decimal digits

Length

Fullword

1 to 4

Class name or external DSECT name

Floating Point Hex

Doubleword

.1 to 16

Decimal digits

Floating Point Hex

Doubleword

.12 to 16

Decimal digits

Floating Point Binary

Doubleword

.16 to 16

Decimal digits

Floating Point Hex

Quadword

.1 to 16

Decimal digits

Decimal

As needed

Byte

.1 to 16

Decimal digits

Offset

Fullword

1 to 4

Symbol naming a DXD or DSECT

Address

Fullword

3, 4

Symbol

Address

Halfword

2 only

One absolute or relocatable expression, or

two absolute expressions: exp(exp)

Address

Fullword

3, 4

Relocatable symbol

Hexadecimal

As needed

Byte

.1 to 256

Hex digits

Address

Halfword

.1 to 2

Any expression

Decimal

As needed

Byte

.1 to 16

Decimal digits

Notes:
1. Bit length specification permitted with absolute expressions only; relocatable A-type constants, 2, 3, or 4 bytes only; relocatable
Y-type constants, 2 bytes only.
2. In a DS assembler instruction, C-and-X type constants can have length specification to 65535.
3. The length modifier must be a multiple of 2, and may be up to 65534 in a DS assembler instruction.
4. GOFF only.

407

Summary of Constants

Figure 113. Summary of Constants (Part 2 of 2)

Constant

Range for
Exponents

Range for
Scale

Truncation or Padding Side

Address

Multiple

Left

Binary

Multiple

Left

Character

One

Right

ASCII Character

One

Right

Unicode Character

One

Right

Floating Point Hex

Multiple

85 to +75

0 to 14

Right

Multiple

231 to 2311

0 to 14

Right

Floating Point Hex

Type

No. of
Constants
per
Operand

Floating Point Binary

Multiple

231 to 2311

N/A

Right

Floating Point Hex

Multiple

85 to +75

0 to 14

Right

Floating Point Hex

Multiple

231 to 2311

0 to 14

Right

N/A

Right

187 to +346

Left

Floating Point Binary

Multiple

231 to 2311

Fixed Point

Multiple

85 to +75

Graphic (DBCS)

One

Fixed Point

Multiple

Length

Multiple

Floating Point Hex

Multiple

85 to +75

0 to 28

Right

Right
85 to +15

187 to +346

Left
Left

Floating Point Hex

Multiple

231 to 2311

0 to 28

Right

Floating Point Binary

Multiple

231 to 2311

N/A

Right

Floating Point Hex

Multiple

231 to 2311

0 to 28

Right

Decimal

Multiple

Left

Offset

Multiple

Left

Address

Multiple

Left

Address

Multiple

Address

Multiple

Left

Hexadecimal

Multiple

Left

Address

Multiple

Left

Decimal

Multiple

Left

Notes:
1. Errors are flagged if significant bits are truncated or if the value specified cannot be contained in the implicit length of the
constant.

408

HLASM V1R5 Language Reference

Macro and Conditional Assembly Language Summary

Appendix C. Macro and Conditional Assembly Language

Summary
This appendix summarizes the macro and conditional assembly language described
in Part 3 of this publication. Figure 114 indicates which macro and conditional
assembly language elements may be used in the name and operand entries of
each statement. Figure 116 on page 413 summarizes the expressions that may
be used in macro instruction statements. Figure 118 on page 414 summarizes the
attributes that may be used in each expression. Figure 119 on page 415
summarizes the variable symbols that may be used in each expression.
Figure 120 on page 416 summarizes the system variable symbols that may be
used in each expression.

409

410

HLASM V1R5 Language Reference

Name
Operation
Operand

Name
Operand

Name
Operand,

Name
Operand

Operand

Model
Statement

SETA

SETAF

SETB

SETC

SETCF

ACTR

Name

Operand

Name

Name
Operand

Operand

Name

Name
Operand

Operand

Name

Name
Name
Operand

Operand

Name

Outer
Macro

Operand

Name

Operand

Name
Operand

Name,
Operand

Name
Operand

Name
Operation
Operand

Operand

Name

Operand

Name

Operand

Name
Operand,

Name
Operand

Name
Operand,

Name
Operand

Name
Operation
Operand

Operand

Name

MEND

Operand

Name

Operand

Name
Operand!,

Name
Operand!

Name
Operand

Name
Operation
Operand

Operand

Name

Operand

Name

Operand

Name
Operand

Name,
Operand

Name
Operand

Name
Operation
Operand

Operand

MNOTE

Operand

ASPACE

Name

Operand

Name
Operand,

Name
Operand

Name
Operand,

Name
Operand

Name
Operation
Operand

Operand

Sequence Symbol

MEXIT

Name

AREAD

ANOP

Operand

Name
Operand!,

Name
Operand!

Name
Operand

Name
Operation
Operand

Operand

SETC

Name
Operand

Operand

LCLC

Operand

LCLB

Operand

SETB

Local SET Symbols

AIF

Operand

LCLA

Operand

SETA

Name
Operand

Operand

GBLC

Operand

SETC

Name

Operand

GBLB

SETB

AGO

Operand

GBLA

SETA

Variable Symbols

AEJECT

Name
Operand

Symbolic Parameter

Prototype
Statement

MACRO

Statement

Global-scope SET Symbols

Figure 114 (Page 1 of 2). Macro Language Elements (Part 1)

Macro and Conditional Assembly Language Summary

Name
Operand

Inner
Macro

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

Name
Operand

SETA
Name
Operand

SETB
Name
Operand

SETC

Variable Symbols

Name
Operand

SETA
Name
Operand

SETB

Local SET Symbols

SETC
Name
Operand

Sequence Symbol
Name

Variable symbols in macro instructions are replaced by their values before processing.
Depending upon their values, system variable symbols with global scope can be used in the same way as global SET symbols, and system variable symbols with local scope can be used in the same way as local SET symbols.
Only if value is self-defining term.
Converted to arithmetic 0 or 1.
Only in character relations.
Only in arithmetic relations.
Only in arithmetic or character relations.
Converted to an unsigned number.
Converted to character 0 or 1.
Only if one to ten decimal digits, not greater than 2147483647.
Only in created SET symbols if value of parenthesized expression is an alphabetic character followed by 0 to 61 alphanumeric characters.
Only in created SET symbols (as described above) and in subscripts (see SETA statement).
The first operand of a SETAF or SETCF instruction must be a character (SETC) expression containing or evaluating to an eight byte module name.

Notes:

Symbolic Parameter

Statement

Global-scope SET Symbols

Figure 114 (Page 2 of 2). Macro Language Elements (Part 1)

Macro and Conditional Assembly Language Summary

Appendix C. Macro and Conditional Assembly Language Summary

411

412

HLASM V1R5 Language Reference

Operand

SETC

SETCF

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

Operand

Operand*

Operand

Operand*

Operand

Operand*

Operand

Integer

Operand

Operand*

Operand

Operand*

Operand

Count

Attributes

Operand

Operand*

Operand

Operand*

Operand

Number

Operand

Operand*

Operand

Operand*

Operand

Defined

Operand

Operand*

Operand

Operation Code

Operand

Type

Notes:

Outer
Macro

MEND

MNOTE

MEXIT

ASPACE

AREAD

ANOP

AIF

AGO

AEJECT

Operand

Operand*

Operand

SETB

Operand

ACTR

Operand

Scale

SETAF

Length

SETA

Model
Statement

LCLC

LCLB

LCLA

GBLC

GBLB

GBLA

Prototype
Statement

MACRO

Statement

Figure 115. Macro Language Elements (Part 2)

Macro and Conditional Assembly Language Summary

Figure 116 (Page 1 of 2). Conditional Assembly Expressions

Expression
Can
contain

Arithmetic
Expressions

Character
Expressions

Logical
Expressions

Self-defining terms

Any combination of characters

(including double-byte
characters, if the DBCS
assembler option is specified)
enclosed in single quotation
marks

A 0 or a 1

Absolute, predefined
ordinary symbols
Length, scale,
integer, count,
defined, and number
attributes
SETA and SETB
symbols
SETC symbols
whose values are a
self-defining term
Symbolic parameters
if the corresponding
operand is a decimal
self-defining term

Absolute, predefined
ordinary symbols

SETB symbols
Any variable symbol enclosed
in single quotation marks
A concatenation of variable
symbols and other characters
enclosed in single quotation
marks

Arithmetic relations
Character relations
Arithmetic value

Built-in Functions
A type or operation code
attribute reference
Substrings

Built-in Functions
&SYSDATC
&SYSLIST(n) if the
corresponding
operand is a decimal
self-defining term
&SYSLIST (n,m) if
the corresponding
operand is a decimal
self-defining term
&SYSOPT_DBCS,
&SYSOPT_RENT,
and
&SYSOPT_XOBJECT
&SYSM_HSEV and
&SYSM_SEV
&SYSNDX,
&SYSNEST, and
&SYSSTMT
Operations

+, (unary and
binary), *, and /;

Concatenation, with a period

(.), or by juxtaposition;
substrings

AND, OR, NOT, XOR

0 through 1024 characters

0 (false) or 1 (true)

Parentheses permitted

Parentheses
permitted

Range
of values

2 to +21

Appendix C. Macro and Conditional Assembly Language Summary

413

Macro and Conditional Assembly Language Summary

Figure 116 (Page 2 of 2). Conditional Assembly Expressions

Expression

Arithmetic
Expressions

Character
Expressions

Logical
Expressions

Used in

SETA operands

SETC operands

SETB operands

Arithmetic relations

Character relations

AIF operands

Created SET
symbols

Created SET symbols

Subscripted SET
symbols
&SYSLIST
subscript(s)
Substring notation
Sublist notation

Built-in functions fall into the following categories:

Figure 117. Built-in functions
Value Type

Functions

|
|

Arithmetic

AND, B2A, C2A, D2A, DCLEN, FIND, INDEX, NOT, OR, SLA, SLL,
SRA, SRL, X2A, XOR

|
|

Logical

AND, AND NOT, ISBIN, ISDEC, ISHEX, ISSYM, NOT, OR, OR

NOT, XOR, XOR NOT

|
|
|

Character

A2B, A2C, A2D, A2X, B2C, B2D, B2X, BYTE, C2B, C2D, C2X,
D2B, D2C, D2X, DCVAL, DEQUOTE, DOUBLE, LOWER, SIGNED,
UPPER, X2B, X2C, X2D

Figure 118 (Page 1 of 2). Attributes

Attribute

Notation

Type

Length

414

HLASM V1R5 Language Reference

Can be used only if

Type Attribute is:

Can be used in:

Ordinary symbols
defined in open code;
symbolic parameters
inside macro
definitions;
&SYSLIST(n),
&SYSLIST(n,m) inside
macro definitions; SET
symbols; all system
variable symbols

Any value

SETC operand fields

Ordinary symbols
defined in open code;
symbolic parameters
inside macro
definitions;
&SYSLIST(n), and
&SYSLIST(n,m) inside
macro definitions

Any value except M,

N, O, T, U

Can be used with:

Character relations

Arithmetic
expressions

Macro and Conditional Assembly Language Summary

Figure 118 (Page 2 of 2). Attributes

Attribute

Notation

Can be used only if

Type Attribute is:

Can be used in:

Scale

Ordinary symbols
defined in open code;
symbolic parameters
inside macro
definitions;
&SYSLIST(n), and
&SYSLIST(n,m) inside
macro definitions

H,F,G,D,E,L,K,P, and
Z

Arithmetic
expressions

Integer

Ordinary symbols
defined in open code;
symbolic parameters
inside macro
definitions;
&SYSLIST(n), and
&SYSLIST(n,m) inside
macro definitions

H,F,G,D,E,L,K,P, and
Z

Arithmetic
expressions

Count

Symbolic parameters
inside macro
definitions;
&SYSLIST(n), and
&SYSLIST(n,m) inside
macro definitions; SET
symbols; all system
variable symbols

Any letter or @

Arithmetic
expressions

Number

Symbolic parameters,
&SYSLIST and
&SYSLIST(n) inside
macro definitions, with
dimensioned SET
symbols

Any letter

Arithmetic
expressions

Defined

Ordinary symbols
defined in open code;
symbolic parameters
inside macro
definitions; &SYSLIST
and &SYSLIST(n)
inside macro
definitions; SETC
symbols whose value
is an ordinary symbol

Any value except M,

N, O, T, U

Arithmetic
expressions

Operation
Code

A character string, or
variable symbol
containing a character
string.

The @ and any letter

except N, O and (only
sometimes) U

SETC operand fields

Character relations

Can be used with:

Refer to Chapter 9, How to Write Conditional Assembly Instructions on page 318

for usage restrictions of the attributes in Figure 118.
Figure 119 (Page 1 of 2). Variable Symbols
Variable
Symbol

Declared
by:

Initialized
or set to:

Symbolic parameter

Prototype
statement

Corresponding
macro
instruction
operand

Value
changed
by:

May be used
in:

Constant
throughout
definition

Arithmetic expressions
if operand is
self-defining term
Character expressions

Appendix C. Macro and Conditional Assembly Language Summary

415

Macro and Conditional Assembly Language Summary

Figure 119 (Page 2 of 2). Variable Symbols

Variable
Symbol

Declared
by:

Initialized
or set to:

SETA

LCLA or
GBLA
instruction

Value
changed
by:
SETA
instruction

May be used
in:
Arithmetic expressions
Character expressions
Logical expressions

SETB

LCLB or
GBLB
instruction

SETB
instruction

Arithmetic expressions
Character expressions
Logical expressions

SETC

LCLC or
GBLC
instruction

String of
length 0 (null)

SETC
instruction

Arithmetic expressions
if value is self-defining
term
Character expressions
Logical expressions if
value is self-defining
term

Notes:
1. Can be used only in macro definitions.

Figure 120 (Page 1 of 5). System Variable Symbols

Type
Type Attr.

Value
changed
by

System Variable
Symbol

Availability

&SYSADATA_DSN

HLA2

U,O

Current associated
data file

Constant
throughout
assembly

Character expressions

&SYSADATA_MEMBER

HLA2

U,O

Current associated
data file member name

Constant
throughout
assembly

Character expressions

&SYSADATA_VOLUME

HLA2

U,O

Current associated
data file volume
identifier

Constant
throughout
assembly

Character expressions

&SYSASM

HLA1

Assembler name

Constant
throughout
assembly

Character expression

&SYSCLOCK

HLA3

Current date and time

Constant
throughout
macro
expansion

Character expressions

&SYSDATC

HLA1

C,A

Assembly date (with

century)

Constant
throughout
assembly

Arithmetic expressions

Scope Initialized or set to

May be used in

Character expressions

&SYSDATE

AsmH

Assembly date

Constant
throughout
assembly

Character expressions

&SYSECT

All

Name of control
section in effect where
macro instruction
appears

Constant
throughout
definition;
set by
START,
CSECT,
RSECT,
DSECT,
or COM

Character expressions

416

HLASM V1R5 Language Reference

Macro and Conditional Assembly Language Summary

Figure 120 (Page 2 of 5). System Variable Symbols

Type
Type Attr.

Value
changed
by

System Variable
Symbol

Availability

&SYSIN_DSN

HLA1

Current primary input

data set name

Constant
throughout
definition

Character expressions

&SYSIN_MEMBER

HLA1

U,O

Current primary input

member name

Constant
throughout
definition

Character expressions

&SYSIN_VOLUME

HLA1

U,O

Current primary input

volume identifier

Constant
throughout
definition

Character expressions

&SYSJOB

HLA1

Source module
assembly jobname

Constant
throughout
assembly

Character expressions

&SYSLIB_DSN

HLA1

Current macro library

filename

Constant
throughout
definition

Character expressions

&SYSLIB_MEMBER

HLA1

U,O

Current macro library

member name

Constant
throughout
definition

Character expressions

&SYSLIB_VOLUME

HLA1

U,O

Current macro library

volume identifier

Constant
throughout
definition

Character expressions

&SYSLIN_DSN

HLA2

Current object data set

name

Constant
throughout
assembly

Character expressions

&SYSLIN_MEMBER

HLA2

U,O

Current object data set

member name

Constant
throughout
assembly

Character expressions

&SYSLIN_VOLUME

HLA2

U,O

Current object data set

volume identifier

Constant
throughout
assembly

Character expressions

&SYSLIST

All

any

Not applicable

Not
applicable

N'&SYSLIST in
arithmetic expressions

&SYSLIST(n)
&SYSLIST(n,m)

All

any

Corresponding macro
instruction operand

Constant
throughout
definition

Arithmetic expressions if
operand is self-defining
term

Scope Initialized or set to

May be used in

Character expressions
&SYSLOC

AsmH

Location counter in
effect where macro
instruction appears

Constant
throughout
definition;
set by
START,
CSECT,
RSECT,
DSECT,
COM,
and
LOCTR

Character expressions

&SYSMAC

HLA3

U,O

Macro name

Constant
throughout
definition

Arithmetic expressions

&SYSMAC(n)

HLA3

U,O

Ancestor macro name

Constant
throughout
definition

Arithmetic expressions

Appendix C. Macro and Conditional Assembly Language Summary

417

Macro and Conditional Assembly Language Summary

Figure 120 (Page 3 of 5). System Variable Symbols

May be used in

Mnote

Arithmetic expressions

At
nesting
and
unnesting
of
macros,
from
MNOTE

Arithmetic expressions

Macro instruction index

Constant
throughout
definition;
unique
for each
macro
instruction

Arithmetic expressions

Macro instruction
nesting level

Constant
throughout
definition;
unique
for each
macro
nesting
level

Arithmetic expressions

DBCS assembler
option indicator

Constant
throughout
assembly

Arithmetic expressions

Availability

&SYSM_HSEV

HLA3

&SYSM_SEV

HLA3

&SYSNDX

All

&SYSNEST

&SYSOPT_DBCS

HLA1

Type
Type Attr.

Value
changed
by

System Variable
Symbol

Scope Initialized or set to

Character expressions

Character expressions
Logical expressions

&SYSOPT_OPTABLE

HLA3

OPTABLE assembler
option value

Constant
throughout
assembly

Character expressions

&SYSOPT_RENT

HLA1

RENT assembler
option indicator

Constant
throughout
assembly

Arithmetic expressions
Character expressions
Logical expressions

&SYSOPT_XOBJECT

HLA3

XOBJECT assembler
option indicator

Constant
throughout
assembly

Arithmetic expressions
Character expressions
Logical expressions

&SYSPARM

All

U,O

User defined or null

Constant
throughout
assembly

Arithmetic expressions if
value is self-defining term
Character expressions

&SYSPRINT_DSN

HLA2

Current assembler
listing data set name

Constant
throughout
assembly

Character expressions

&SYSPRINT_MEMBER

HLA2

U,O

Current assembler
listing data set member
name

Constant
throughout
assembly

Character expressions

&SYSPRINT_VOLUME

HLA2

U,O

Current assembler
listing data set volume
identifier

Constant
throughout
assembly

Character expressions

&SYSPUNCH_DSN

HLA2

Current object data set

name

Constant
throughout
assembly

Character expressions

418

HLASM V1R5 Language Reference

Macro and Conditional Assembly Language Summary

Figure 120 (Page 4 of 5). System Variable Symbols

Type
Type Attr.

Value
changed
by

System Variable
Symbol

Availability

&SYSPUNCH_MEMBER

HLA2

U,O

Current object data set

member name

Constant
throughout
assembly

Character expressions

&SYSPUNCH_VOLUME

HLA2

U,O

Current object data set

volume identifier

Constant
throughout
assembly

Character expressions

&SYSSEQF

HLA1

U,O

Outer-most macro
instruction
identification- sequence
field

Constant
throughout
definition

Character expressions

&SYSSTEP

HLA1

Source module
assembly job name

Constant
throughout
assembly

Character expressions

&SYSSTMT

HLA1

C,A

Next statement number

Assembler
increments
each
time a
statement
is
processed

Arithmetic expressions

Scope Initialized or set to

May be used in

Character expressions

&SYSSTYP

HLA1

U,O

Type of control section

in effect where macro
instruction appears

Constant
throughout
definition;
set by
START,
CSECT,
RSECT,
DSECT,
or COM

Character expressions

&SYSTEM_ID

HLA1

Assembly operating
system environment
identifier

Constant
throughout
assembly

Character expressions

&SYSTERM_DSN

HLA2

Current terminal data

set name

Constant
throughout
assembly

Character expressions

&SYSTERM_MEMBER

HLA2

U,O

Current terminal data

set member name

Constant
throughout
assembly

Character expressions

&SYSTERM_VOLUME

HLA2

U,O

Current terminal data

set volume identifier

Constant
throughout
assembly

Character expressions

&SYSTIME

AsmH

Source module
assembly time

Constant
throughout
assembly

Character expressions

Appendix C. Macro and Conditional Assembly Language Summary

419

Macro and Conditional Assembly Language Summary

Figure 120 (Page 5 of 5). System Variable Symbols

System Variable
Symbol

Availability

&SYSVER

HLA1

Type
Type Attr.
C

Scope Initialized or set to

Notes:
1. Availability:
All
AsmH
HLA1
HLA2
HLA3
HLA4
HLA5

All assemblers, including the DOS/VSE Assembler

Assembler H Version 2 and High Level Assembler
High Level Assembler Release 1
High Level Assembler Release 2
High Level Assembler Release 3
High Level Assembler Release 4
High Level Assembler Release 5

2. Type:
A
B
C

Arithmetic
Boolean
Character

3. Type Attr:
N
O
U

Numeric (self-defining term)

Omitted
Undefined, unknown, deleted or unassigned

4. Scope:
L
G

420

Local - only in macro

Global - in entire program

HLASM V1R5 Language Reference

Assembler release
level

Value
changed
by
Constant
throughout
assembly

May be used in
Character expressions

Standard Character Set Code Table

Appendix D. Standard Character Set Code Table

Figure 121. Standard Character Set Code Table - From Code Page 00037
Hex.

Dec.

EBCDIC

Binary

Hex.

Dec.

EBCDIC

Binary

1 1

1 11

1 1

1 11

111

1 111

1 1

1 11

111

1 111

1 11

111

1 111

111

1 111

1111

1 1111

1 1

11 1

1 1

11 1

1 11

11 11

1 1

11 1

1 11

11 11

1 11

11 11

1 111

11 111

1 1

11 1

1 11

11 11

1 11

11 11

1 111

11 111

1 11

11 11

1 111

11 111

1 111

11 111

1 1111

11 1111

421

Standard Character Set Code Table

Hex.

Dec.

EBCDIC

Binary

Hex.

SPACE

Dec.

EBCDIC

Binary

11 1

1 1

11 1

1 11

11 11

1 1

11 1

1 11

11 11

1 11

11 11

1 111

11 111

1 1

11 1

1 11

11 11

1 11

11 11

1 111

1 11

1 111

11 111

1 1111

111

11 1111

112

111

11 1

113

111 1

11 1

114

111 1

11 11

115

111 11

11 1

116

111 1

11 11

117

111 11

11 11

118

111 11

11 111

119

111 111

11 1

111 1

11 11

121

111 11

11 11

122

111 11

11 111

123

111 111

11 11

124

111 11

11 111

125

111 111

11 111

126

111 111

11 1111

127

422

HLASM V1R5 Language Reference

11 111
11 11

11 111

111 1111

Standard Character Set Code Table

Hex.

Dec.

128

129

EBCDIC

Binary

Hex.

Dec.

EBCDIC

Binary

1 1

161

11 1

1 1

162

11 1

131

1 11

163

11 11

132

1 1

164

11 1

133

1 11

165

11 11

134

1 11

166

11 11

135

1 111

167

11 111

136

1 1

168

11 1

137

1 11

169

11 11

138

1 11

11 11

139

1 111

171

11 111

1 11

172

11 11

141

1 111

173

11 111

142

1 111

174

11 111

143

1 1111

175

11 1111

144

176

111

145

11 1

177

111 1

146

11 1

178

111 1

147

11 11

179

111 11

148

11 1

111 1

149

11 11

181

111 11

11 11

182

111 11

151

11 111

183

111 111

152

11 1

184

111 1

153

11 11

185

111 11

154

11 11

186

111 11

155

11 111

187

111 111

156

11 11

188

111 11

157

11 111

189

111 111

158

11 111

111 111

159

11 1111

191

111 1111

Appendix D. Standard Character Set Code Table

423

Standard Character Set Code Table

Hex.

Dec.

192

193

Binary

Hex.

Dec.

224

111

11 1

225

111 1

194

11 1

226

111 1

195

11 11

227

111 11

196

11 1

228

111 1

197

11 11

229

111 11

198

11 11

111 11

199

11 111

231

111 111

11 1

232

111 1

11 11

233

111 11

11 11

234

111 11

11 111

235

111 111

11 11

236

111 11

11 111

237

111 111

11 111

238

111 111

11 1111

239

111 1111

111

1111

111 1

241

1111 1

111 1

242

1111 1

211

111 11

243

1111 11

212

111 1

244

1111 1

213

111 11

245

1111 11

214

111 11

246

1111 11

215

111 111

247

1111 111

216

111 1

248

1111 1

217

111 11

249

1111 11

218

111 11

1111 11

219

111 111

251

1111 111

111 11

252

1111 11

221

111 111

253

1111 111

222

111 111

254

1111 111

223

111 1111

255

1111 1111

424

EBCDIC

HLASM V1R5 Language Reference

EBCDIC

Binary

Notices

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 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.

425

Trademarks

AIX
BookMaster
CICS
DFSMS
DFSMS/MVS
DFSMSdfp
Enterprise Systems Architecture/370
Enterprise Systems Architecture/390
IBM
Language Environment
MVS
MVS/DFP
MVS/ESA
OS/390
SP
System/370
System/390
VM/ESA
VSE/ESA
z/OS

426

HLASM V1R5 Language Reference

Linux is a 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.
Microsoft and Windows are trademarks of Microsoft
Corporation in the United States, other countries, or
both.
Other company, product, and service names may be
trademarks or service marks of others.

Bibliography

Bibliography
|
|
|

z/OS MVS Programming: Authorized Assembler

Services Reference, Volumes 1 - 4, SA22-7609 SA22-7612

|
|

z/OS MVS Program Management: User's Guide and

Reference, SA22-7643

z/OS MVS System Codes, SA22-7626

HLASM Language Reference, SC26-4940

z/OS MVS System Commands, SA22-7627

HLASM Licensed Program Specifications,

GC26-4944

|
|

z/OS MVS System Messages, Volumes 1 - 10,

SA22-7631 - SA22-7640

High Level Assembler

Publications
HLASM General Information, GC26-4943
HLASM Installation and Customization Guide,
SC26-3494

OS/390:

HLASM Programmer's Guide, SC26-4941

OS/390 MVS JCL Reference, GC28-1757

OS/390 MVS JCL User's Guide, GC28-1758

Toolkit Feature Publications

HLASM Toolkit Feature User's Guide, GC26-8710

OS/390 MVS Programming: Assembler Services

Reference, GC28-1910

HLASM Toolkit Feature Debug Reference

Summary, GC26-8712

OS/390 MVS System Codes, GC28-1780

OS/390 MVS System Commands, GC28-1781

HLASM Toolkit Feature Interactive Debug Facility

User's Guide, GC26-8709

OS/390 MVS System Messages, Volumes 1 - 5,

GC28-1784 - GC27-1788

HLASM Toolkit Feature Installation and

Customization Guide, GC26-8711

OpenEdition:
MVS/ESA OpenEdition MVS User's Guide,
SC23-3013

Related Publications
(Architecture)
Enterprise Systems Architecture/390 Principles of
Operation, SA22-7201

MVS/DFP:

System/370 Enterprise Systems Architecture

Principles of Operation, SA22-7200

MVS/DFP Version 3.3: Linkage Editor and Loader,

SC26-4564

System/370 Principles of Operation, GA22-7000

DFSMS/MVS:

System/370 Extended Architecture Principles of

Operation, SA22-7085

z/OS UNIX System Services User's Guide,

SA22-7801

MVS/DFP Version 3.3: Utilities, SC26-4559

z/OS DFSMS Program Management, SC27-1130

z/OS DFSMSdfp Utilities, SC26-7414

z/Architecture Principles of Operation, SA22-7832

TSO/E (z/OS):

Related Publications for MVS

z/OS TSO/E Command Reference, SA22-7782

TSO/E (OS/390):

z/OS:

OS/390 TSO/E Command Reference, SC28-1869

z/OS MVS JCL Reference, SA22-7597

SMP/E (z/OS):

z/OS MVS JCL User's Guide, SA22-7598

|
|

z/OS MVS Programming: Assembler Services

Guide, SA22-7605

SMP/E Messages, Codes and Diagnosis,

GA22-7770

|
|
|

z/OS MVS Programming: Assembler Services

Reference, Volumes 1 and 2, SA22-7606,
SA22-7607

|
|

z/OS MVS Programming: Authorized Assembler

SMP/E Reference, SA22-7772

SMP/E User's Guide, SA22-7773
SMP/E (OS/390):
SMP/E Messages and Codes, SC28-1738

427

Bibliography

SMP/E Reference, SC28-1806

SMP/E User's Guide, SC28-1740

Related Publications for VM

|
|

z/VM XEDIT Command and Macro Reference,

SC24-5973

|
|

z/VM CP Command and Utility Reference,

SC24-5967

z/VM Planning and Administration, SC24-5995

z/VM:

z/VM Service Guide, GC24-5946

|
|

z/VM CMS Application Development Guide,

SC24-6002

|
|

z/VM VMSES/E Introduction and Reference,

GC24-5994

|
|

z/VM CMS Application Development Guide for

Assembler, SC24-6003

z/VM CMS User's Guide, SC24-5968

z/VM CMS Command Reference, SC24-5969

|
|

z/VM CMS File Pool Planning, Administration, and

Operation, SC24-6058

|
|

z/VM System Messages and Codes - CMS,

GC24-6031

z/VM XEDIT User's Guide, SC24-5972

428

HLASM V1R5 Language Reference

Related Publications for VSE

VSE/ESA Administration, SC33-6705
VSE/ESA Guide to System Functions, SC33-6711
VSE/ESA Installation, SC33-6704
VSE/ESA Planning, SC33-6703
VSE/ESA System Control Statements, SC33-6713
VSE/ESA Messages and Codes, Vols.1 - 3,
SC33-6796, SC33-6798, SC33-6799

Index

Index
Special Characters
'
See pairing rules
See quotation marks
/
as division operator

358

.
concatenation operator for strings
in qualified symbols 66

383

See asterisks ()
*PROCESS statement 102
initiating the first control section 54
restricted options 102
&
See ampersands (&)
See pairing rules
See variable symbols
&SYS
as start of system variable names 262
&SYSADATA_DSN system variable symbol 263
&SYSADATA_MEMBER system variable symbol 264
&SYSADATA_VOLUME system variable symbol 265
&SYSASM system variable symbol 265
&SYSCLOCK system variable symbol 266
&SYSDATC system variable symbol 266
&SYSDATE system variable symbol 267
&SYSECT system variable symbol 267
CSECT 268
DSECT 268
RSECT 268
&SYSIN_DSN system variable symbol 269
&SYSIN_MEMBER system variable symbol 270
&SYSIN_VOLUME system variable symbol 271
&SYSJOB system variable symbol 272
&SYSLIB_DSN system variable symbol 272
&SYSLIB_MEMBER system variable symbol 273
&SYSLIB_VOLUME system variable symbol 273
&SYSLIN_DSN system variable symbol 274
&SYSLIN_MEMBER system variable symbol 275
&SYSLIN_VOLUME system variable symbol 275
&SYSLIST system variable symbol 276
&SYSLOC system variable symbol 278
LOCTR 278
&SYSM_HSEV system variable symbol 279
&SYSM_SEV system variable symbol 280
&SYSMAC system variable symbol 279
&SYSNDX system variable symbol
controlling its value using MHELP 398
definition 281

&SYSNEST system variable symbol 283

&SYSOPT_DBCS system variable symbol 284
&SYSOPT_OPTABLE system variable symbol 285
&SYSOPT_RENT system variable symbol 285
&SYSOPT_XOBJECT system variable symbol 285
&SYSPARM system variable symbol 286
&SYSPRINT_DSN system variable symbol 286
&SYSPRINT_MEMBER system variable symbol 288
&SYSPRINT_VOLUME system variable symbol 288
&SYSPUNCH_DSN system variable symbol 289
&SYSPUNCH_MEMBER system variable symbol 290
&SYSPUNCH_VOLUME system variable symbol 290
&SYSSEQF system variable symbol 291
&SYSSTEP system variable symbol 292
&SYSSTMT system variable symbol 292
&SYSSTYP system variable symbol 292
CSECT 293
DSECT 293
RSECT 293
&SYSTEM_ID system variable symbol 293
&SYSTERM_DSN system variable symbol 294
&SYSTERM_MEMBER system variable symbol 295
&SYSTERM_VOLUME system variable symbol 295
&SYSTIME system variable symbol 296
&SYSVER system variable symbol 296

as negative unary operator 358

as subtraction operator 358
+
as addition operator 358
as positive unary operator 358
=
defining a literal constant 171

Numerics
24
AMODE instruction 111
RMODE instruction 211
31
AMODE instruction 111
RMODE instruction 211
64
AMODE instruction 111
RMODE instruction 211
64-bit addressing mode 101

A
A-type address constant 153
A2B (SETC built-in function) 374

429

Index

A2C (SETC built-in function) 375

A2D (SETC built-in function) 375
A2X (SETC built-in function) 375
absolute addresses
base registers for 220
absolute expression 47
absolute symbol
defined 31
absolute terms 28
ACONTROL
PUSH instruction 209
ACONTROL instruction 103
ACTR instruction 394
ADATA assembler option 108
ADATA instruction 107
address constants
A-type 153
complex relocatable 153
J-type 160
Q-type 159
R-type 160
S-type 156
V-type 157
Y-type 153
addressability
by means of the DROP instruction 172
by means of the USING instruction 218
dependent 67
establishing 64
qualified 66
relative 67
using base register instructions 66
addresses
absolute 87
explicit 64
implicit 64
relocatable 87
addressing mode
64-bit 101
addressing mode (AMODE) 68
AEJECT instruction 257
AFPR assembler option 86, 103
AGO instruction
alternative statement format 393
general statement format 392
AGOB
as synonym of AGO instruction 394
AIF instruction 390
alternative statement format 392
AIFB
as synonym of AIF instruction 392
AINSERT instruction 108, 257
ALIAS instruction 109
maximum operand length 110
ALIGN
suboption of FLAG 105

430

HLASM V1R5 Language Reference

ALIGN assembler option 129, 176

alphabetic character
defined 30
alternative statement format 246
AGO instruction 393
AIF instruction 392
continuation lines 16
extended SET statements 387
GBLx instructions 344
LCLx instructions 345
macro instructions 298
prototype statements 246
summary 16
AMODE
indicators in ESD 68
instruction to specify addressing mode 110
ampersands (&)
as special character 308
DBCS ampersand not delimiter 197
in variable symbols 30
not recognized in double-byte data 145
paired in CA string 144
paired in MNOTE message 197
paired in PUNCH instruction 208
paired in Unicode data 144
pairing in character relations 335
pairing in DC 144
representation in character constant 143, 208
variable symbol identifier in PUNCH statement 208
AND (SETA built-in function) 353
AND (SETB built-in function) 365
AND NOT (SETB built-in function) 365
ANOP instruction 395
ANY
AMODE instruction 111
RMODE instruction 211
ANY31
AMODE instruction 111
ANY64
AMODE instruction 111
apostrophes
paired in CA string 144
AREAD instruction 257
CLOCKB operand 258
CLOCKD operand 258
arithmetic (SETA) expressions
built-in functions 353
evaluation of 359
rules for coding 358
SETC variables in 359
using 347
arithmetic external function calls 388
arithmetic relations in logical expressions 367
array 322
dimensioned 319
subscripted 319

Index

ASCII character constants 144

type extension 135
ASCII translation table 14
ASPACE instruction 259
assembler instruction statements
base register instructions 66
data definition instructions 126
exit-control parameters 187
listing control instructions 215
operation code definition instruction 198
program control instructions 189
program sectioning and linking instructions 51
symbol definition instructions 184
assembler language
assembler instruction statements 4
coding aids summary 9
coding conventions of 14
coding form for 14
compatibility with other languages 4
conditional assembly instructions 318
introduction to 3
machine instruction statements 4, 78
macro instruction statements 4, 297
statements
summary of 405
structure of 21
summary of instructions 402
assembler options
ADATA 108
AFPR 86, 103
ALIGN 129, 176
BATCH 341
CODEPAGE 144
COMPAT 12, 103, 278, 304, 307, 308, 314, 322,
386
controlling output using 6
DBCS 12, 15, 34, 36, 145, 197, 208, 217, 247,
249, 251, 253, 284, 298, 301, 302, 309, 360, 404,
413
DECK 188, 289, 290
EXIT 188
FLAG 16, 103, 198, 247, 373
FOLD 14
GOFF 37, 62, 72, 108, 111, 112, 124, 125, 160,
216, 274, 275
LIBMAC 103, 241
NOAFPR 86
NOALIGN 129
NODECK 209, 210
NOGOFF 37, 62, 72
NOLIST 207
NOOBJECT 209, 210
NOXOBJECT 72
OBJECT 274, 275
OPTABLE 285
PROFILE 55

assembler options (continued)

RA2 103, 155
RENT 212, 285
SECTALGN 113, 194, 201
specifying with PROCESS statements 102
SYSPARM 286
TYPECHECK 103
USING 222
XOBJECT 72, 108, 110, 112, 274, 275
assembler program
basic functions 6
processing sequence 7
relationship to operating system 8
assembler type
returned by SYSATTRA built-in function 380
assembler type value
assigned by EQU instruction 186
associated data file
ADATA instruction 107
contents 6
EXITCTL instruction 187
writing to 107
association of code and data areas 232
asterisks (*)
as location counter reference 37
as multiplication operator 358
as relocatable term 37
defining comment statements 18
attribute reference
notation 325
attributes
assembler
EQU instruction 186
count (K') 335
data 324
defined (D') 337
definition mode 340
in combination with symbols 326
integer (I') 334
length (L') 332
lookahead 340
number (N') 336
of expressions 47, 326
of symbols 326
operation code (O') 337
program type
EQU instruction 186
reference notation 309
relocatable term 47
scale (S') 333
summary of 409, 415
type (T') 328
XATTR operands 230

Index

431

Index

B
B-type binary constant 141
B2A (SETA built-in function) 353
B2C (SETC built-in function) 375
B2D (SETC built-in function) 376
B2X (SETC built-in function) 376
base register instructions
DROP instruction 172
POP instruction 204
PUSH instruction 209
USING instruction 218
base registers
for absolute addresses 220
BATCH assembler option 341
binary constant (B) 141
binary floating point constant (DB) 167
binary floating point constant (EB) 167
binary floating point constant (LB) 167
binary floating-point constants 167
binary operators 358
binary self-defining term 35
bit patterns
for masks 91
bit-length modifier 137
blank lines
ASPACE instruction 259
in macros 18
in open code 18
books
High Level Assembler xii
branching
conditional assembly 390
AGO instruction 392
AIF instruction 390
extended AIF instruction 391
machine instructions
based 80
extended mnemonics 80
relative 80, 83
built-in functions
A2B 374
A2C 375
A2D 375
A2X 375
AND 353, 365
AND NOT 365
arithmetic (SETA) expressions 353
B2A 353
B2C 375
B2D 376
B2X 376
BYTE 376
C2A 353
C2B 377
C2D 377

432

HLASM V1R5 Language Reference

built-in functions (continued)

C2X 377
character (SETC) expressions 374
D2A 354
D2B 377
D2C 378
D2X 378
DCLEN 354
DCVAL 378
DEQUOTE 379
DOUBLE 379
FIND 355
function-invocation format 350
INDEX 355
introduction 349
ISBIN 365
ISDEC 366
ISHEX 366
ISSYM 366
logical-expression format 350
LOWER 379
NOT 356, 366
OR 356, 366
OR NOT 367
SIGNED 380
SLA 356
SLL 356
SRA 357
SRL 357
summary table 350
SYSATTRA 380
SYSATTRP 380
UPPER 380
X2A 358
X2B 381
X2C 381
X2D 381
XOR 358, 367
XOR NOT 367
BYTE (SETC built-in function) 376

C
C-type character constant 142
C-type character self-defining terms
C2A (SETA built-in function) 353
C2B (SETC built-in function) 377
C2D (SETC built-in function) 377
C2X (SETC built-in function) 377
CATTR instruction 112
CCW instruction 115
CCW0 instruction 115
CCW1 instruction 116
CD-ROM publications xiii
CEJECT instruction 118

Index

character (SETC) expressions

built-in functions 374
using 369
character constant 142
DBCS 145
Unicode UTF-16 144
character constant (C) 142
character expressions
evaluation of 382
character external function calls 389
character relations in logical expressions 367, 368
comparing comparands of unequal length 368
character self-defining term 35
character set
code table
standard 421
CODEPAGE option 144
default 11
double-byte 12
standard 11
translation table 14
character strings 309
concatenating 383
defined 371
evaluation of
logical 367
in SETC instruction 369
relational operators for 367
values 383
characters
special
See special characters
class names
assigned by default 60
assigned explicitly 59
CATTR instruction 112
classes
assignment to
by binding and loading properties 59
default names 60
defined by CATTR instruction 112
entry point 60
group of machine language blocks 50
CNOP instruction 119
COBOL communication 57
code areas
association with data areas 232
code table
standard character set 421
CODEPAGE assembler option 144
coding
functions in addition to machine instructions 9
coding aids summary 9
coding conventions
assembler language
alternative format for AGO 393
alternative format for AIF 392

coding conventions (continued)

assembler language (continued)
alternative format for LCLx 347
alternative format for SETx 388
alternative statement format for GBLx 345
coding conventions, assembler language
comment statement 18
continuation line errors 16
continuation lines 15
standard coding format 14
statement coding rules 19
COM instruction 57, 121
&SYSECT 268
&SYSSTYP 293
combining keyword and positional parameters 255,
303
comment statements
format 18
function of 240
internal macro 261
ordinary 261
comparisons in logical expressions 367
COMPAT assembler option 103, 314
CASE suboption 104
LITTYPE suboption 104
MACROCASE suboption 12, 104, 308
NOLITTYPE suboption 104
NOMACROCASE suboption 104
NOSYSLIST suboption 104
SYSLIST suboption 104, 278, 304, 307, 314, 322,
386
compatibility
default classes 60
object files 60
of HLASM with other languages 4
complex relocatable 47
address constant operands 155
address constants 153
defined 47
EQU instruction 184
expressions 48
computed AGO instruction 393
concatenating character string values 383
concatenation of characters in model statements 249
concatenation operator for strings 383
conditional assembly instructions
ACTR instruction 394
AGO instruction 392
alternative statement format 393
AIF instruction 390
alternative statement format 392
ANOP instruction 395
computed AGO instruction 393
extended AIF instruction 391
function of 256
GBLA instruction 344
alternative statement format 345

Index

433

Index

conditional assembly instructions (continued)

GBLB instruction 344
alternative statement format 345
GBLC instruction 344
alternative statement format 345
how to write 318
LCLA instruction 345
alternative statement format 347
LCLB instruction 345
alternative statement format 347
LCLC instruction 345
alternative statement format 347
list of 343
MHELP instruction 397
OPSYN assembler instruction 200
effect of 200
redefining 200
SETA instruction 347
alternative statement format 388
SETAF instruction 388
SETB instruction 362
alternative statement format 388
SETC instruction 369
alternative statement format 388
SETCF instruction 389
substring notations in 371
conditional assembly language
See also macro language
CATTR instruction 59, 61
summary 242
summary of expressions 413
constants
address 153, 157
alignment of 129
binary 141
binary floating-point 167
character 142
comparison with literals and self-defining terms
decimal 151
duplication factor 132
fixed-point 148
floating-point 161
hexadecimal 164
IEEE binary 169
general information 129
graphic 145
hexadecimal 147
length 129, 160
length attribute value of symbols naming 129
literal
See literal constants
modifiers of 136
nominal values of 140
offset 159
padding of values 130
subfield 1 (duplication factor) 132

434

HLASM V1R5 Language Reference

constants (continued)
subfield 2 (type) 133
subfield 3 (type extension) 134
subfield 4 (modifier) 136
subfield 5 (nominal value) 140
summary of 407
symbolic addresses of 129
truncation of values 130
type extension 134
types of 126, 133
CONT
suboption of FLAG 105
continuation line errors 247
continuation lines 15
See also alternative statement format
description 15
errors in 16
unlimited number of 16
continuation-indicator field 15
control instructions 79
control sections
concept of 52
defining blank common 57
executable 53
first 54
identifying 123, 212
reference 56
segments 68
unnamed 55
controlling the assembly 6
converting SETA symbol to SETC symbol 387
COPY instruction 122, 260
count attribute (K') 335
created SET symbols 323
CSECT instruction 123
&SYSECT 268
&SYSSTYP 293
interaction with LOCTR instruction 193
Customization book xii
CXD instruction 125

D
D' defined attribute 337
D-type floating-point constant 161
D2A (SETA built-in function) 354
D2B (SETC built-in function) 377
D2C (SETC built-in function) 378
D2X (SETC built-in function) 378
data
immediate
See immediate data
PRINT instruction 206
data areas
association with code areas 232

Index

data attributes 324

data definition instructions
CCW instruction 115
CCW0 instruction 115
CCW1 instruction 116
DC instruction 126
DS instruction 174
DB-type floating-point constant 167
DBCS
See also double-byte data
PUNCH instruction 208
DBCS assembler option 12, 15, 34, 36, 145, 197, 208,
217, 247, 249, 251, 253, 284, 298, 301, 302, 309,
360, 404, 413
&SYSOPT_DBCS system variable symbol 284
determining if supplied 284
extended continuation-indicators 17
DC instruction 126
DCLEN (SETA built-in function) 354
DCVAL (SETC built-in function) 378
decimal constant
P-type 151
packed 151
Z-type 151
zoned 151
decimal constant (P) 151
decimal constant (Z) 151
decimal instructions 79
decimal self-defining term 34
DECK assembler option 188, 290
&SYSPUNCH_DSN system variable symbol 289
&SYSPUNCH_MEMBER system variable
symbol 290
&SYSPUNCH_VOLUME system variable
symbol 290
defaults
class names 60
entry point 60
defined attribute (D') 337
definition mode 340
dependent addressing 67
dependent USING
domain 228
instruction syntax 226
range 228
DEQUOTE (SETC built-in function) 379
DH-type floating-point constant 161
dimensioned SET symbols 344, 346
documentation
High Level Assembler xii, 427
domain
dependent USING instruction 228
labeled USING instruction 226
ordinary USING instruction 223
DOUBLE (SETC built-in function) 379

double-byte character set (DBCS)

See double-byte data
double-byte data
code conversion in the macro language 360
concatenation in SETC expressions 384
concatenation of fields 251
continuation of 15, 16
definition of 12
duplication of 369
graphic constants 126, 145
graphic self-defining term 36
in C-type constants 145
in character self-defining terms 35
in comments 18
in G-type constants 145
in keyword operands 302
in macro comments 261
in macro operands 253
in MNOTE operands 197
in positional operands 301
in PUNCH operands 208
in quoted strings 309
in remarks 21
in REPRO operands 210
in TITLE operands 217
listing of macro-generated fields 249
mixed 145
notation xvi
pure 145
DROP instruction 172
DS instruction 174
DSECT instruction 56, 178
&SYSECT 268
&SYSSTYP 293
dummy section
external 57
identifying 56, 178
See also external dummy sections
duplication factor
and substrings 369
in character expressions 369
in constants 132
DXD instruction 180
no conflict with other external names 58

E
E-Decks
reading in VSE 4
E-type floating-point constant 161
EB-type floating-point constant 167
edited macros 242
edited macros in VSE 4
EH-type floating-point constant 161
EJECT instruction 181

Index

435

Index

elements of conditional assembly language 318

END instruction 182, 341
nominated entry point 182
ENTRY instruction 183
entry point symbol
referencing using the ENTRY instruction 183
transfer control to
using END instruction 182
EQU instruction 184
assembler type 184
assigning the length attribute 333
assigning the type attribute 341
program type 184
equal sign
designating a literal constant 43
ESD entries 72
exclusive OR (XOR)
SETA built-in function 358
EXCP access method 116
EXIT assembler option
ADEXIT suboption 188
INEXIT suboption 188
LIBEXIT suboption 188
OBJEXIT suboption 188
PRTEXIT suboption 188
TRMEXIT suboption 188
exit-control parameters 187
EXITCTL instruction 187
exiting macros 245
exits
See user I/O exits
EXLITW
suboption of FLAG 105
explicit address
specifying 88
explicit addresses 64
explicit length attribute 129
exponent modifier
floating-point constants 162
specifying 139
expressions
absolute 47
arithmetic 347
attributes 47
character 369
See also character expressions
complex relocatable 48
conditional assembly
summary of 413
discussion of 44
EQU instruction 184
evaluation of 367
character 382
multiterm 46
single-term 46
logical 362

436

HLASM V1R5 Language Reference

expressions (continued)
paired relocatable terms 47
relocatable 48
rules for coding 45, 363
extended AGO instruction 393
extended AIF instruction 391
extended continuation-indicator
double-byte data continuation 16
listing of macro-generated fields 249
extended SET statement 387
external dummy sections
CXD instruction to define cumulative length
discussion of 57
DSECT name in Q-type constant 58
DXD instruction to define an 180
external function calls
arithmetic 388
character 389
SETAF instruction 388
SETCF instruction 389
external names
no conflict with DXD instruction 58
external symbol dictionary entries 72
external symbols
See also symbols, external
ALIAS command 109
in V-type address constant 230
length restrictions 110
providing alternate names 109
EXTRN instruction 189

F
F-type fixed-point constant 148
field boundaries 14
FIND (SETA built-in function) 355
first control section 54
fixed-point constant (F) 148
fixed-point constant (H) 148
FLAG assembler option 103, 247
CONT suboption 16, 247
nnn suboption 198
NOSUBSTR suboption 373
floating point constant (D) 161
floating point constant (DH) 161
floating point constant (E) 161
floating point constant (EH) 161
floating point constant (L) 161
floating point constant (LH) 161
floating point constant (LQ) 161
floating point constants
binary
See binary floating-point constants
floating-point constants 161
floating-point instructions 79

125

Index

FOLD assembler option 14

format notation, description xivxvi
format-0 channel command word 115
format-1 channel command word 116
FORTRAN communication 57
function calls
See external function calls
function-invocation format built-in function 350
functions of conditional assembly language 318

G
G-type graphic constant 145
GBLA instruction 344
alternative statement format 345
GBLB instruction 344
alternative statement format 345
GBLC instruction 344
alternative statement format 345
GEN
PRINT instruction 205
General Information book xii
general instructions 78
generated fields
listing 248
generating END statements 341
global-scope system variable symbols 262
GOFF assembler option 72, 108, 124, 125, 160, 216,
274, 275
affect on RI-format instructions 92
CATTR instruction 112
entry point 111
location counter maximum value 37, 62
program object 50
sections 68
XATTR instruction 230
GOFF option
interaction with PUNCH instruction 209
interaction with REPRO instruction 210
graphic constant (G) 145
graphic self-defining term 36

H
H-type fixed-point constant 148
header
macro definition 244
hexadecimal constant (X) 147
hexadecimal self-defining term 35
High Level Assembler
publications xii

I
I' integer attribute

334

ICTL instruction 189

identification-sequence field 15
immediate data 91
in machine instructions 91
IMPLEN
suboption of FLAG 105
implicit address
specifying 88
implicit addresses 64
implicit length attribute 129
implied addresses
See implicit addresses
INDEX (SETA built-in function) 355
information retrieval functions
SYSATTRA 380
SYSATTRP 380
inner macro definitions 313
inner macro instructions 256, 312
passing sublists to 307
input format control statement
See ICTL instruction
input stream 10
input/output operations 80
installation and customization
book information xii
instruction statement format 19
instructions
&SYSOPT_OPTABLE system variable symbol
assembler
ACONTROL 103
ADATA 107
ALIAS 109
AMODE 110
CATTR 112
CCW 115
CCW0 115
CCW1 116
CEJECT 118
CNOP 119
COM 121
COPY 122
CSECT 123
CXD 125
DC 126
DROP 172
DS 174
DSECT 178
DXD 180
EJECT 181
END 182
ENTRY 183
EQU 184
EXTRN 189
ICTL 189
ISEQ 190
LOCTR 191
LTORG 193

Index

285

437

Index

instructions (continued)
assembler (continued)
OPSYN 198
ORG 200
POP 204
PRINT 204
PUNCH 208
PUSH 209
REPRO 210
RMODE 211
RSECT 212
SPACE 213
START 214
TITLE 215
USING 218
WXTRN 229
XATTR 230
conditional assembly
ACTR 394
AGO 392
AIF 390
ANOP 395
GBLA 344
GBLB 344
GBLC 344
LCLA 345
LCLB 345
LCLC 345
SETA 347
SETAF 388
SETB 362
SETC 369
SETCF 389
machine
examples 91
OPTABLE option 285
macro
AEJECT 257
AINSERT 108, 257
ASPACE 259
COPY 260
MEXIT 260
MHELP 397
MNOTE 196
integer attribute (I') 334
internal macro comment statement format 18
internal macro comment statements 261
ISBIN (SETB built-in function) 365
ISDEC (SETB built-in function) 366
ISEQ instruction 190
ISHEX (SETB built-in function) 366
ISSYM (SETB built-in function) 366

438

HLASM V1R5 Language Reference

J
J-type length constant

160

K
K' count attribute 335
keyword parameters 255, 301

L
L' length attribute 332
L-type floating-point constant 161
labeled dependent USING
as parameter of DROP instruction 172
definition 226
labeled USING 223
as parameter of DROP instruction 172
domain 226
range 225
labeled USING instruction
difference from ordinary using instruction 224
labels
on USING instructions 223
Language Reference xiii
LB-type floating-point constant 167
LCLA instruction 345
alternative statement format 347
LCLB instruction 345
alternative statement format 347
LCLC instruction 345
alternative statement format 347
length attribute
(L') 332
assigned by modifier in DC instruction 136
bit-length modifier 137
DC instruction
address constant 154
binary constant 141
character constant 144
decimal constant 151
fixed-point constant 148
floating-point constant 164
graphic constant 146
hexadecimal constant 147
length constant 160
offset constant 159
duplication factor 133
EQU instruction 333
explicit length 129
exponent modifier 140
implicit length 129
value assigned to symbols naming constants 129
length attribute reference 38
length constant (J) 160

Index

length fields in machine instructions 90

length modifier
constant 136
syntax 136
length of control section 62
LH-type floating-point constant 161
LIBMAC assembler option 103, 241
library macro definitions 241
license inquiry 425
Licensed Program Specifications xiii
lines
how to continue 15
LINKAGE
XATTR operands 231
linkages
by means of the ENTRY instruction 183
by means of the EXTRN instruction 189
by means of the WXTRN instruction 229
symbolic 68
linking 51
LIST(121) option
displaying location counter 37
LIST(133) option
displaying location counter 37
listing
generated fields 248
listing control instructions
AEJECT instruction 257
AINSERT instruction 108, 257
ASPACE instruction 259
CEJECT instruction 118
EJECT instruction 181
PRINT instruction 204
SPACE instruction 213
TITLE instruction 215
literal constants
coding 43
definition 171
literal pool 44, 68, 194
alignment 194
conditions of creation 194
LTORG instruction 193
literals
comparison with constants and self-defining
terms 41
duplicate 195
explanation of 40
general rules for usage 42
type attribute 331
local scope system variable symbols 262
location counter
defined 36
for control sections 62
maximum value 37
effect of GOFF assembler option 37
effect of NOGOFF assembler option 37

location counter reference

effect of duplication factor in constants 133
effect of duplication factor in literals 133
relocatable term 37, 44
location counter setting 61
LOCTR instruction 191
ORG instruction 200
START instruction 61
THREAD option 62
LOCTR instruction 191
&SYSLOC 278
interaction with CSECT instruction 193
logical (SETB) expressions 362, 365
logical functions
AND 353
NOT 356
OR 356
XOR 358
logical operators
AND 365
AND NOT 365
NOT 366
OR 366
OR NOT 367
XOR 358, 367
XOR NOT 367
logical XOR 358
logical-expression format
defined 365
logical-expression format built-in function 350
lookahead mode 340
LookAt message retrieval tool xiii
LOWER (SETC built-in function) 379
LQ-type floating-point constant 161
LTORG instruction 193

M
machine instruction formats
RI format 91
RR format 93
RS format 94
RSI format 95
RX format 95
SI format 97
SS format 97
machine instruction statements
addresses 87
control 79
decimal 79
floating-point 79
formats 83
general 78
immediate data 91
input/output 80
length field in 90

Index

439

Index

machine instruction statements (continued)

operand entries 85
symbolic operations codes in 84
machine instructions 24
machine instructions, publications 427
macro comment statement format 18
macro definition header (MACRO) 244
macro definition trailer (MEND) 244
macro definitions
alternative statement format 246
arguments 300
body of a 247
combining positional and keyword parameters
comment statements 261
COPY instruction 260
description 238
format of 244
header 239, 244
how to specify 243
inner macro instructions 256
internal macro comment statements 261
keyword parameters 255
MEXIT instruction 260
MNOTE instruction 196
model statements 239
name field parameter 245
nesting in 311
operand entry 300
parameters 245
parts of a macro definition 239
positional parameters 254
prototype 239
sequence symbols 339
subscripted symbolic parameters 255
symbolic parameters 253
trailer 239, 244
where to define in a source module 243
where to define in open code 243
macro instruction statements 297
macro instructions
See also inner macro instructions
See also outer macro instructions
alternative statement format 298
arguments 300
description 241, 297
format of 297
general rules and restrictions 313
inner and outer 311
M type attribute 329
multilevel sublists 306
name entry 299
name field type attribute 329
operand entry 300
operation entry 299
passing sublists to inner 307
passing values through nesting levels 314

440

HLASM V1R5 Language Reference

255

macro instructions (continued)

prototype statement 244
sequence symbols 339
sublists in operands 304
summary of 405
values in operands 307
macro language
comment statements 240
conditional assembly language 242
defining macros 238
library macro definition 241
macro instruction 241
model statements 239
processing statements 240
source macro definition 241
summary of 409
using 238
macro library 242
MACRO statement (header) 244
macros
continuation line errors 247
edited macros 242
effects of LIBMAC option 241
exiting 245
format of a macro definition 244
how to specify 243
library macro definition 241
macro definition 238
macro definition header (MACRO) 239, 244
macro definition trailer (MEND) 239, 244
macro instruction 241
macro library 242
macro prototype statement 239
MACRO statement (header) 244
MEND statement (trailer) 245
MEXIT instruction 260
MNOTE instruction 196
model statements 239
source macro definition 241
using macros 238
manuals
High Level Assembler xii, 427
masks
specifying their bit pattern using immediate data
MCALL
PRINT instruction 206
message retrieval tool, LookAt xiii
MEXIT instruction 260
MHELP instruction 397
mnemonic codes
extended 80
machine instruction 84
MNOTE instruction 196
model statements
explanation of 247
function of 239

Index

model statements (continued)

in macros 239, 247
in open code 248
rules for concatenation of characters in 249
rules for specifying fields in 251
summary of 405
variable symbols as points of substitution in 247
modifiers of constants
exponent 139
length 136
scale 138
MSOURCE
PRINT instruction 206
multilevel sublists 306
MVS publications 427

N
N' number attribute 336
name entry coding 19
name field parameter
in macro definition 245
nesting
macro calls 312
macro definition 311
passing values through nesting levels 314
recursion 311
system variable symbols in nested macros 316
nesting macro instructions
in calls 312
in definitions 313
NOAFPR assembler option 86
NOALIGN
suboption of FLAG 105
NOALIGN assembler option 129
NOCOMPAT assembler option 104
NOCONT
suboption of FLAG 105
NODATA
PRINT instruction 206
NODECK assembler option 209, 210
NOEXLITW
suboption of FLAG 105
NOGEN
PRINT instruction 205
NOGOFF assembler option 37, 62, 72
NOIMPLEN
suboption of FLAG 105
NOLIST assembler option 207
NOMCALL
PRINT instruction 206
nominal values of constants and literals
address 153
binary 141
binary floating-point 167
character 142

nominal values of constants and literals (continued)

decimal 151
fixed-point 148
floating-point 161
graphic 145
hexadecimal 147
NOMSOURCE
PRINT instruction 207
NOOBJECT assembler option 209, 210
NOPAGE0
suboption of FLAG 106
NOPRINT
PRINT instruction 207
PUSH instruction 210
NOPRINT operand
AREAD instruction 258
POP instruction 204
PRINT instruction 207
PUSH instruction 209
NOSUBSTR
suboption of FLAG 106
NOT (SETA built-in function) 356
NOT (SETB built-in function) 366
notation, description xivxvi
NOUHEAD
PRINT instruction 207
NOUSING0
suboption of FLAG 106
NOXOBJECT assembler option 72
number attribute (N') 336

O
O' operation code attribute 337
OBJECT assembler option 188, 274, 275
object external class name
establishing 112
object program structure
load module model 50
program object model 50
OFF
PRINT instruction 205
offset constant (Q) 159
omitted operands 307, 308
ON
PRINT instruction 205
online publications xiii
open code 244, 342
blank lines within 18
conditional assembly instructions in 342
defined 244
operand entries 20
operand entry 300
operands
assembler instruction statements 85
combining positional and keyword 303

Index

441

Index

operands (continued)
compatibility with earlier assemblers 308
in machine instructions 85
keyword 301
machine instruction statements 85
multilevel sublists in 306
omitted 307, 308
positional 300
special characters in 308
statement coding rules 20
sublists in 304
unquoted operands 308
values in 307
operating system
relationship to assembler program 8
operation code attribute (O') 337
operation codes, symbolic
extended 80
machine instruction 84
operation entry coding 19
operator
binary
See binary operators
unary
See unary operators
OPSYN instruction 198
OPTABLE assembler option 285
&SYSOPT_OPTABLE system variable symbol
determining value 285
OR (SETA built-in function) 356
OR (SETB built-in function) 366
OR NOT(SETB built-in function) 367
ordinary comment statements 261
ordinary symbols
defined 30
ordinary USING instruction
difference from labeled using instruction 224
ORG instruction 200
location counter setting 200
organization of this manual xi
outer macro definitions 313
outer macro instructions 312
OVERRIDE 102

P
P-type decimal constant 151
packed decimal constant 151
PAGE0
suboption of FLAG 106
paired relocatable terms 47
pairing rules
'' 335
&& 335
character self-defining terms
DC instruction 144

442

HLASM V1R5 Language Reference

285

parameters
combining positional and keyword 255
keyword 255
positional 254
subscripted symbolic 255
symbolic 253
parentheses
enclosing terms 28
PL/I communication 57
pool
literal
See literal pool
POP instruction 204
positional parameters 254, 300
predefined absolute symbols
in logical expressions 363
in SETA expressions 359
legal use 363
not permitted in character expressions 383
previously defined symbols 33
PRINT
PUSH instruction 209
PRINT instruction 204
DATA 206
GEN 205
MCALL 206
MSOURCE 206
NODATA 206
NOGEN 205
NOMCALL 206
NOMSOURCE 207
NOPRINT 207
NOUHEAD 207
OFF 205
ON 205
UHEAD 207
private code 54, 187
private control section
See private code
privileged instructions 79
process
override 102
PROCESS statement
See *PROCESS statement
processing of statements
conditional assembly instructions 256
COPY instruction 260
inner macro instructions 256
MEXIT instruction 260
MNOTE instruction 196
PROFILE assembler option 55
program control instructions
CNOP instruction 119
COPY instruction 122
END instruction 182
ICTL instruction 189

Index

program control instructions (continued)

ISEQ instruction 190
LTORG instruction 193
ORG instruction 200
POP instruction 204
PUNCH instruction 208
PUSH instruction 209
REPRO instruction 210
program object model
element 50
part 50
section 50
program sectioning 51
program sectioning and linking instructions
AMODE instruction 110
CATTR instruction 112
COM instruction 57, 121
CSECT instruction 123
CXD instruction 125
DSECT instruction 56, 178
DXD instruction 180
ENTRY instruction 183
EXTRN instruction 189
LOCTR instruction 191
RMODE instruction 211
RSECT instruction 212
WXTRN instruction 229
XATTR instruction 230
program type
assigned by modifier in DC instruction 135
program type value
assigned by EQU instruction 186
Programmer's Guide xiii
Prototype Control Section
See PSECT
prototype, macro instruction
alternative statement format 246, 298
format of 245
function of 244
name field 245
operand field 246
operation field 245
summary of 405
PSECT 232
address 132, 160
discussed 232
XATTR operands 231
pseudo-registers 57
publications xii
High Level Assembler xii, 427
HLASM Toolkit 427
machine instructions 427
MVS 427
online (CD-ROM) xiii
organization of this manual xi
VM 428

publications (continued)
VSE 428
PUNCH instruction 208
DBCS 208
PUSH instruction 209
ACONTROL 209
NOPRINT 210
PRINT 209
USING 209

Q
Q-type offset constant 159
qualified addressing 66
labeled USING instructions 66
qualified symbols 223
composition 66
labeled USING 223
qualifiers
for symbols 223
relocatable 224
quotation marks 371
as delimiter for character string in SETC 371
as string terminator PUNCH instruction 208
DBCS apostrophe not delimiter 197
not recognized in double-byte data 145
paired in MNOTE message 197
paired in PUNCH instruction 208
paired in Unicode data 144
representation in character constant 143
quoted strings 309

R
R-type address constant 132, 160, 232
RA2 assembler option 103, 155
railroad track format, how to read xivxvi
range
dependent USING instruction 228
labeled USING instruction 225
ordinary USING instruction 222
reading edited macros in VSE 4
redefining conditional assembly instructions
REFERENCE
XATTR operands 231
reference constant (R) 160
reference notation for attribute 309
register zero
as base address 222
in USING instruction 220
registers
use by machine instructions 86
relational operators
for character strings 367
relative address
specifying 88

200

Index

443

Index

relative addressing 67
relocatability attribute 47
relocatable expression
complex 48
definition 48
EQU instruction 184
relocatable symbol
defined 31
relocatable terms 28
See also self-defining terms
remarks entries 21
RENT assembler option 212, 285
&SYSOPT_RENT system variable symbol
determining if supplied 285
representation conversion functions
A2 375
A2B 374
A2D 375
A2X 375
B2A 353
B2C 375
B2D 376
B2X 376
BYTE 376
C2A 353
C2B 377
C2D 377
C2X 377
D2A 354
D2B 377
D2C 378
D2X 378
SIGNED 380
X2A 358
X2B 381
X2C 381
X2D 381
REPRO instruction 210
residence mode (RMODE)
See RMODE
RI format 91
RMODE
establishing values 68
indicators in ESD 68
instruction 211
RMODE instruction
24 211
31 211
64 211
ANY 211
RR format 93
RS format 94
RSECT instruction 212
&SYSECT 268
&SYSSTYP 293

444

HLASM V1R5 Language Reference

RSI format 95
rules for model statement fields
RX format 95

251

285

S' scale attribute 333

S-type address constant 156
scale attribute (S') 333
scale modifier 136, 138
SCOPE
XATTR operands 232
scope of SET symbols 319
SECTALGN assembler option
interaction with ALIGN 113
interaction with LTORG instruction 194
interaction with ORG instruction 201
sectioning, program
addressing mode of a control section 110
control sections 52
CSECT instruction 123
defining 180
ESD entries 72
external symbols 189
first control section 54
identifying a blank common control section 57
identifying a dummy section 56
location counter 61
maximum length of control section 62
multiple location counters in a control section 191
read-only control section 212
residence mode of a control section 211
source module 52
total length of external dummy sections 125
unnamed control section 55
weak external symbols 229
sections
See also control sections
GOFF option considerations 68
segments of control sections 68
self-defining terms
binary 35
character 35
comparison with literals and constants 41
decimal 34
graphic 36
hexadecimal 35
overview 34
using 34
semiprivileged instructions 79
sequence symbols 339
defined 31
SET statement
extended 387
SET symbols
See also symbols, SET

Index

SET symbols (continued)

arrays 319
assigning values to 347
created 323
declaring 343
global 344
local 345
description of 319
dimensioned 319
external function calls 388, 389
scope of 319
SETA (set arithmetic) 347
SETB (set binary) 362
SETC (set character) 369
specifications 320
specifications for subscripted 322
subscripted 319
SETA
arithmetic expression 347
built-in functions 353
instruction format 347
symbol in operand field of SETC
in arithmetic expressions 352
leading zeros 387
sign of substituted value 387
symbols
subscripted 347
using 360
SETAF instruction 388
SETB
character relations in logical expressions 367, 368
instruction format 362
logical expression 362
symbols
subscripted 362
using 368
SETC
built-in functions 374
character expression 369
character expressions 371
instruction format 369
SETA symbol in operand field 387
statement format 369
substring notation 369
symbols
subscripted 369
SETCF instruction 389
shift codes
shift-in (SI) DBCS character delimiter 12
shift-out (SO) DBCS character delimiter 12
shift functions
SLA 356
SLL 356
SRA 357
SRL 357

shift left arithmetic (SETA built-in function) 356

shift left logical (SETA built-in function) 356
shift right arithmetic (SETA built-in function) 357
shift right logical (SETA built-in function) 357
SI (shift-in) character
continuation of double-byte data 16
continuation-indicator field 15
double-byte character set 12
SI format 97
SIGNED (SETC built-in function) 380
simply relocatable address
defined 89
SLA (SETA built-in function) 356
SLL (SETA built-in function) 356
SO (shift-out) character
continuation of double-byte data 16
continuation-indicator field 15
double-byte character set 12
softcopy publications xiii
source macro definitions 241
source module 10
SPACE instruction 213
blank lines 213
special characters 308
SRA (SETA built-in function) 357
SRL (SETA built-in function) 357
SS format 97
stacked items xv
START instruction 214
&SYSECT 268
&SYSSTYP 293
beginning a source module 52
control section 53
syntax 214
statement coding rules 19
statement field 14
string manipulation functions
DCLEN 354
DCVAL 378
DEQUOTE 379
DOUBLE 379
LOWER 379
UPPER 380
string scanning functions
FIND 355
INDEX 355
strings
character 309
quoted 309
structure of assembler language 21
subfield 1 of constant (duplication factor) 132
subfield 2 of constant (type) 133
subfield 3 of constant (type extension) 134
subfield 4 of constant (modifier) 136
subfield 5 of constant (nominal value) 140

Index

445

Index

sublists
compatibility with Assembler H 278
effect of COMPAT(SYSLIST) assembler option 304,
307
in operands 304
multilevel 306
passing
to inner macro instructions 307
subscripted local SET symbol 347
subscripted SET symbols 319, 322
See also dimensioned SET symbols
subscripted symbolic parameters 255
SUBSTR
suboption of FLAG 106
substring notation
arithmetic expressions in 352
assigning SETC symbols 369, 389
concatenating double-byte data 384
concatenation 386
definition 371
duplicating double-byte data 370
duplication factor 369
evaluation of 372
level of parentheses 359
using count (K') attribute 325
symbol definition (EQU) instruction 184
symbol length attribute reference 38
symbol qualifier
label unavailable as result of DROP instruction 172
symbol qualifiers 223
symbol table 30
symbolic linkages 68
symbolic operation codes 84
defining 198
deleting 198
OPSYN 198
symbolic parameters 253
symbols
absolute 184
See also absolute symbol
attributes in combination with 326
complexly relocatable
EQU instruction 185
defining 31
explanation of 29
extended SET 387
external 157, 229
EXTRN instruction 189
labeled USING 223
length attribute reference 38
ordinary
See ordinary symbols
previously defined 33
qualifiers 223
relocatable 31
See also relocatable symbol

446

HLASM V1R5 Language Reference

symbols (continued)
restrictions on 32
sequence 339
See also sequence symbols
SET 347
declaring global 343
declaring local 345
USING instruction labels 223
variable
See also variable symbols
as points of substitution in model
statements 247
SET symbols 319
subscripted 319
symbolic parameters 253
weak 229
syntax notation, description xivxvi
SYSADATA file
ADATA instruction 107
SYSATTRA (SETC built-in function) 186, 380
SYSATTRP (SETC built-in function) 186, 380
SYSPARM assembler option 286
&SYSPARM system variable symbol 286
system macro instructions 241
system variable symbols
&SYS naming convention 262
&SYSADATA_DSN 263
&SYSADATA_MEMBER 264
&SYSADATA_VOLUME 265
&SYSASM 265
&SYSCLOCK 266
&SYSDATC 266
&SYSDATE 267
&SYSECT 267
&SYSIN_DSN 269
&SYSIN_MEMBER 270
&SYSIN_VOLUME 271
&SYSJOB 272
&SYSLIB_DSN 272
&SYSLIB_MEMBER 273
&SYSLIB_VOLUME 273
&SYSLIN_DSN 274
&SYSLIN_MEMBER 275
&SYSLIN_VOLUME 275
&SYSLIST 276
&SYSLOC 278
&SYSM_HSEV 196, 279
&SYSM_SEV 196, 280
&SYSMAC 279
&SYSNDX 281
&SYSNEST 283
&SYSOPT_DBCS 284
&SYSOPT_OPTABLE 285
&SYSOPT_RENT 285
&SYSOPT_XOBJECT 285
&SYSPARM 286

Index

Unicode UTF-16 constant nominal data

CODEPAGE option 144
unknown type attribute 330
unnamed control section 55
unquoted operands 308
unsigned integer conversion 387
UPPER (SETC built-in function) 380
user I/O exits 187
user records
ADATA instruction 107
USING
PUSH instruction 209
USING assembler option
WARN suboption 222
USING instruction 218
base registers for absolute addresses 220
dependent 226
discussion of 218
domain of a 223
for executable control sections 219
for reference control sections 219
labeled 223
labeled dependent 226
range
dependent 228
labeled 225
ordinary 222
USING0
suboption of FLAG 106
UTF-16 145
UTF-16 Unicode character constant 135

system variable symbols (continued)

&SYSPRINT_DSN 286
&SYSPRINT_MEMBER 288
&SYSPRINT_VOLUME 288
&SYSPUNCH_DSN 289
&SYSPUNCH_MEMBER 290
&SYSPUNCH_VOLUME 290
&SYSSEQF 291
&SYSSTEP 292
&SYSSTMT 292
&SYSSTYP 292
&SYSTEM_ID 293
&SYSTERM_DSN 294
&SYSTERM_MEMBER 295
&SYSTERM_VOLUME 295
&SYSTIME 296
&SYSVER 296
defined 262
in nested macros 316
in open code 262, 316, 343
summary of 416
variability 262

T
T' type attribute
See type attribute
terms 28
enclosed in parentheses 28
TITLE instruction 215
Toolkit Customization book xiii
trailer
macro definition 244
TRANSLATE option
converting default EBCDIC characters
not modifying ASCII 144
translation table 14
type attribute (T') 328
literals 330, 331
name field of macro instruction 329
undefined type attribute 330
unknown type attribute 330
type extension of constants 134
TYPECHECK assembler option 103
types of constants 133

U
UHEAD
PRINT instruction 207
unary operators 358
undefined type attribute 330
Unicode character constant 142
Unicode UTF-16
character constant 144

V
142

V-type address constant 157, 232

validity checking functions
ISBIN 365
ISDEC 366
ISHEX 366
ISSYM 366
values
passing through nesting levels 314
values in operands 307
variable symbols
See also SET symbols
See also symbols
&SYSADATA_DSN 263
&SYSADATA_MEMBER 264
&SYSADATA_VOLUME 265
&SYSASM 265
&SYSCLOCK 266
&SYSDATC 266
&SYSDATE 267
&SYSECT 267
&SYSIN_DSN 269
&SYSIN_MEMBER 270

Index

447

Index

variable symbols (continued)

&SYSIN_VOLUME 271
&SYSJOB 272
&SYSLIB_DSN 272
&SYSLIB_MEMBER 273
&SYSLIB_VOLUME 273
&SYSLIN_DSN 274
&SYSLIN_MEMBER 275
&SYSLIN_VOLUME 275
&SYSLIST 276
&SYSLOC 278
&SYSM_HSEV 279
&SYSM_SEV 280
&SYSMAC 279
&SYSNDX 281
&SYSNEST 283
&SYSOPT_DBCS 284
&SYSOPT_OPTABLE 285
&SYSOPT_RENT 285
&SYSOPT_XOBJECT 285
&SYSPARM 286
&SYSPRINT_DSN 286
&SYSPRINT_MEMBER 288
&SYSPRINT_VOLUME 288
&SYSPUNCH_DSN 289
&SYSPUNCH_MEMBER 290
&SYSPUNCH_VOLUME 290
&SYSSEQF 291
&SYSSTEP 292
&SYSSTMT 292
&SYSSTYP 292
&SYSTEM_ID 293
&SYSTERM_DSN 294
&SYSTERM_MEMBER 295
&SYSTERM_VOLUME 295
&SYSTIME 296
&SYSVER 296
attributes 326, 413
defined 30
dimensioned 322
implicitly declared 320, 322
SETA 347
SETB 362
SETC 369
subscripted 322
summary of 415
symbolic parameters 246
system
See system variable symbols
type 320
VM publications 428
VSE publications 428

448

HLASM V1R5 Language Reference

W
web site xiii
WXTRN instruction

229

X
X-type hexadecimal constant 147
X2A (SETA built-in function) 358
X2B (SETC built-in function) 381
X2C (SETC built-in function) 381
X2D (SETC built-in function) 381
XATTR instruction 230
XATTR operands
ATTRIBUTES 230
LINKAGE 231
PSECT 231
REFERENCE 231
SCOPE 232
XOBJECT assembler option 72, 108, 188, 274, 275
See also GOFF assembler option
ALIAS string 110
CATTR instruction 112
XATTR instruction 230
XOR (SETA built-in function) 358
XOR (SETB built-in function) 367
XOR NOT (SETB built-in function) 367

Y
Y-type address constant

153

Z
Z-type decimal constant 151
z/OS publications
zero
division by, in expression 46
zero, register
See register zero
zoned decimal constant
See Z-type decimal constant

We'd Like to Hear from You

High Level Assembler for MVS & VM & VSE
Language Reference
Release 5
Publication No. SC26-4940-04
Please use one of the following ways to send us your comments about this book:
MailUse the Readers' Comments form on the next page. If you are sending the form
from a country other than the United States, give it to your local IBM branch office or
IBM representative for mailing.
Electronic mailUse this Internet ID:
Internet: [email protected]
Be sure to include the following with your comments:
Title and publication number of this book
Your name, address, and telephone number if you would like a reply
Your comments should pertain only to the information in this book and the way the
information is presented. To request additional publications, or to comment on other IBM
information or the function of IBM products, please give your comments to your IBM
representative or to your IBM authorized remarketer.
IBM may use or distribute your comments without obligation.

Readers' Comments
High Level Assembler for MVS & VM & VSE
Language Reference
Release 5
Publication No. SC26-4940-04
How satisfied are you with the information in this book?
Very
Satisfied

Satisfied

Neutral

Dissatisfied

Very
Dissatisfied

Technically accurate
Complete
Easy to find
Easy to understand
Well organized
Applicable to your tasks
Grammatically correct and consistent
Graphically well designed
Overall satisfaction
Please tell us how we can improve this book:

May we contact you to discuss your comments? Yes No

Name

Company or Organization

Phone No.

Address

Readers' Comments
SC26-4940-04

IBM

Fold and Tape

Please do not staple

Cut or Fold
Along Line

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
J87/D325
555 Bailey Avenue
SAN JOSE, CA 95141-9989

Fold and Tape

SC26-4940-04

Please do not staple

Fold and Tape

Cut or Fold
Along Line

IBM

Program Number: 5696-234

Printed in the United States of America
on recycled paper containing 10%
recovered post-consumer fiber.

High Level Assembler Publications

SC26-4941
GC26-4943
GC26-4944
SC26-4940
SC26-3494

HLASM
HLASM
HLASM
HLASM
HLASM

Programmer's Guide.
General Information.
Licensed Program Specifications.
Language Reference.
Installation and Customization Guide.

High Level Assembler Toolkit Feature Publications

GC26-8709
GC26-8710
GC26-8711
GC26-8712

SC26-494-4

HLASM
HLASM
HLASM
HLASM

Toolkit
Toolkit
Toolkit
Toolkit

Feature
Feature
Feature
Feature

Interactive Debug Facility User's Guide.

User's Guide.
Installation and Customization Guide.
Debug Reference Summary.

IBM Assembly Language Coding (ALC) Part 1
100% (8)
IBM Assembly Language Coding (ALC) Part 1
68 pages
Interskill Catalogue Dt-Full
No ratings yet
Interskill Catalogue Dt-Full
308 pages
T363 GCIS House Rules - Part I (IaaS DBaaS) v1.0
0% (1)
T363 GCIS House Rules - Part I (IaaS DBaaS) v1.0
23 pages
Assembler Services Guide
No ratings yet
Assembler Services Guide
556 pages
How To Read A zOS Assembler Listing
No ratings yet
How To Read A zOS Assembler Listing
14 pages
Assembler Language II
No ratings yet
Assembler Language II
52 pages
Assembler Language IV
No ratings yet
Assembler Language IV
70 pages
Assembler Language III
No ratings yet
Assembler Language III
80 pages
ABendAid Manual
No ratings yet
ABendAid Manual
188 pages
CA7 Workload Automation RefGd
0% (1)
CA7 Workload Automation RefGd
378 pages
IMS Appl Prog
No ratings yet
IMS Appl Prog
419 pages
CA-idms Ads Alive User Guide 15.0
No ratings yet
CA-idms Ads Alive User Guide 15.0
142 pages
Mainframe Assembler Translation
No ratings yet
Mainframe Assembler Translation
16 pages
Assembler
100% (1)
Assembler
49 pages
Assembler Reference
100% (1)
Assembler Reference
115 pages
r01 Racf Unix Overview
No ratings yet
r01 Racf Unix Overview
53 pages
Assembler
100% (1)
Assembler
117 pages
GC28-0629-3 OS VS2 MVS System Programming Library TSO
No ratings yet
GC28-0629-3 OS VS2 MVS System Programming Library TSO
127 pages
Tso-E Clist
100% (1)
Tso-E Clist
222 pages
Debugging Natural Applications
No ratings yet
Debugging Natural Applications
53 pages
REXX Complete Reference
100% (2)
REXX Complete Reference
51 pages
IBM 370 Assembly Language - Day2
No ratings yet
IBM 370 Assembly Language - Day2
26 pages
DFSMSdss Storage Administration Manual
No ratings yet
DFSMSdss Storage Administration Manual
360 pages
Abend Aid User Ref
No ratings yet
Abend Aid User Ref
442 pages
How To Make SMF Report
No ratings yet
How To Make SMF Report
114 pages
TSO Commands
No ratings yet
TSO Commands
10 pages
Software Development With Natural
No ratings yet
Software Development With Natural
71 pages
Chapter 18: Security On z/OS
100% (1)
Chapter 18: Security On z/OS
40 pages
IBM Mainframe Assembler - Hints and Tips
100% (3)
IBM Mainframe Assembler - Hints and Tips
7 pages
Pli Qa
100% (3)
Pli Qa
41 pages
Rexx/Vm User's Guide: 5 Release 2
100% (1)
Rexx/Vm User's Guide: 5 Release 2
235 pages
z/OS System Programmer
No ratings yet
z/OS System Programmer
4 pages
Introduction To LANSA For I
No ratings yet
Introduction To LANSA For I
129 pages
PL1 Programming Guide
No ratings yet
PL1 Programming Guide
496 pages
Ims ppt1
100% (1)
Ims ppt1
74 pages
Idms Integrated Database Management System
No ratings yet
Idms Integrated Database Management System
258 pages
TSO - E Programming Guide
No ratings yet
TSO - E Programming Guide
188 pages
Rexx Faq S
No ratings yet
Rexx Faq S
42 pages
Seneca SQL
No ratings yet
Seneca SQL
37 pages
Comparison of CLIST Language and REXX
No ratings yet
Comparison of CLIST Language and REXX
10 pages
Atos White Paper Mainframes in Perspective
No ratings yet
Atos White Paper Mainframes in Perspective
24 pages
RACF V1.10 Command Syntax Booklet
No ratings yet
RACF V1.10 Command Syntax Booklet
68 pages
Lotus Script
No ratings yet
Lotus Script
222 pages
SDSF For JES3
No ratings yet
SDSF For JES3
126 pages
Converting JCL 2 REXX
No ratings yet
Converting JCL 2 REXX
15 pages
Restructured Executor Extended Language Is A Highly Versatile Programming
No ratings yet
Restructured Executor Extended Language Is A Highly Versatile Programming
13 pages
DB2 Story
No ratings yet
DB2 Story
8 pages
Control M
No ratings yet
Control M
4 pages
IMS-DC Presentacion
No ratings yet
IMS-DC Presentacion
37 pages
Ispf Dialog Tag Language Guide and Reference
No ratings yet
Ispf Dialog Tag Language Guide and Reference
562 pages
DSNTIAUL
No ratings yet
DSNTIAUL
8 pages
Ims DC Transition
100% (3)
Ims DC Transition
39 pages
Churchil Assembler
No ratings yet
Churchil Assembler
116 pages
Mainframe FAQ
No ratings yet
Mainframe FAQ
117 pages
DB2 Exam C2090-320 Practice Questions
From Everand
DB2 Exam C2090-320 Practice Questions
Robert Wingate
No ratings yet
PLI Basic Training Using VSAM, IMS and DB2
From Everand
PLI Basic Training Using VSAM, IMS and DB2
Robert Wingate
1/5 (1)
DB2 11 for z/OS: Intermediate Training for Application Developers
From Everand
DB2 11 for z/OS: Intermediate Training for Application Developers
Robert Wingate
No ratings yet
DB2 Exam C2090-320 Preparation Guide
From Everand
DB2 Exam C2090-320 Preparation Guide
Robert Wingate
No ratings yet
MVS JCL Utilities Quick Reference, Third Edition
From Everand
MVS JCL Utilities Quick Reference, Third Edition
Robert Wingate
5/5 (1)
DB2 Exam C2090-313 Preparation Guide
From Everand
DB2 Exam C2090-313 Preparation Guide
Robert Wingate
No ratings yet
Interview Questions for DB2 z/OS Application Developers
From Everand
Interview Questions for DB2 z/OS Application Developers
Robert Wingate
No ratings yet
Interview Questions for IBM Mainframe Developers
From Everand
Interview Questions for IBM Mainframe Developers
Robert Wingate
1/5 (1)
DB2 Bible
No ratings yet
DB2 Bible
200 pages
(WWW - Entrance-Exam - Net) - ICAR ARS NET Previous Questions On Agricultural Biotechnology 1
No ratings yet
(WWW - Entrance-Exam - Net) - ICAR ARS NET Previous Questions On Agricultural Biotechnology 1
5 pages
Cobol
100% (1)
Cobol
98 pages
Basic Pl/1 Built-In Functions
No ratings yet
Basic Pl/1 Built-In Functions
18 pages
Enterprise PL-I For Z-OS Language Reference
No ratings yet
Enterprise PL-I For Z-OS Language Reference
596 pages
CA7
No ratings yet
CA7
6 pages
PL/I Module 1
No ratings yet
PL/I Module 1
12 pages
Basic Pl/1 Assignments & Expressions
No ratings yet
Basic Pl/1 Assignments & Expressions
26 pages
COBOL - Interview Refresher
No ratings yet
COBOL - Interview Refresher
39 pages
Re Entrant
100% (1)
Re Entrant
26 pages
CA7 Commands
No ratings yet
CA7 Commands
9 pages
RecoverPoint For VMs 5.3 Flex Plugin Administrator Guide 01
No ratings yet
RecoverPoint For VMs 5.3 Flex Plugin Administrator Guide 01
65 pages
Demonstration Delivery & Support Vm/Esa 2.4.0 Demopkg System Reference Guide Release 4Q99
No ratings yet
Demonstration Delivery & Support Vm/Esa 2.4.0 Demopkg System Reference Guide Release 4Q99
230 pages
RidgeBot Deployment Quick Start Guide v4.2.2 Latest
No ratings yet
RidgeBot Deployment Quick Start Guide v4.2.2 Latest
98 pages
Input/Output Configuration Program User's Guide For ICP Iocp
No ratings yet
Input/Output Configuration Program User's Guide For ICP Iocp
338 pages
Oracle 19c Database - Larger SGA - Performance Best Practices - Dell Technologies Info Hub
0% (1)
Oracle 19c Database - Larger SGA - Performance Best Practices - Dell Technologies Info Hub
2 pages
Ibmrd 2505 M
No ratings yet
Ibmrd 2505 M
8 pages
Ethical Hacking Lab The Setup Guide
No ratings yet
Ethical Hacking Lab The Setup Guide
8 pages
AutoNest SVB 10253058
No ratings yet
AutoNest SVB 10253058
26 pages
IBM Mainframe History
100% (1)
IBM Mainframe History
42 pages
Hitachi Virtual Storage Platform Provisioning Guide For Open Systems PDF
No ratings yet
Hitachi Virtual Storage Platform Provisioning Guide For Open Systems PDF
654 pages
4.profit Maximization
No ratings yet
4.profit Maximization
14 pages
Pipeline Com Ref
No ratings yet
Pipeline Com Ref
442 pages
Monitor and Troubleshoot Your End-To-End Azure Network Infrastructure by Using Network Monitoring Tools
No ratings yet
Monitor and Troubleshoot Your End-To-End Azure Network Infrastructure by Using Network Monitoring Tools
31 pages
Iliou - TP2
No ratings yet
Iliou - TP2
12 pages
Active-Active Replication Witness
No ratings yet
Active-Active Replication Witness
15 pages
Nuage 210 WBX Software Installation Guide
No ratings yet
Nuage 210 WBX Software Installation Guide
91 pages
FortiAnalyzer KVM VM Install Guide
No ratings yet
FortiAnalyzer KVM VM Install Guide
21 pages
Z/VM and Ibm Zseries: - . - Your Path To Success
No ratings yet
Z/VM and Ibm Zseries: - . - Your Path To Success
24 pages
Unit 1
No ratings yet
Unit 1
72 pages
Ovn-Architecture 7 Openvswitch-Manual
No ratings yet
Ovn-Architecture 7 Openvswitch-Manual
16 pages
MEDC Project Report Bhathiya 318282
No ratings yet
MEDC Project Report Bhathiya 318282
44 pages
nutanix-NCM - Update - 13 March-2021
No ratings yet
nutanix-NCM - Update - 13 March-2021
48 pages
Hypervisor Case Study
No ratings yet
Hypervisor Case Study
8 pages
Mainframes Computer
No ratings yet
Mainframes Computer
4 pages
Azure VMs
No ratings yet
Azure VMs
2 pages
Mural: Pre-Installation Manual
No ratings yet
Mural: Pre-Installation Manual
54 pages
Microsoft Azure Network Security
No ratings yet
Microsoft Azure Network Security
18 pages
Manual47350010 Powerprotect Data Manager 19 14 Microsoft SQL Server User Guide
No ratings yet
Manual47350010 Powerprotect Data Manager 19 14 Microsoft SQL Server User Guide
237 pages