High Level Assembler for z/OS & z/VM & z/VSE. Language Reference (Version 1 Release 6)

Chapter

1. Introduction

A computer can understand and interpret only machine language. Machine

language is in binary form and, thus, 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 to do this 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 1. Assembling and link-editing your assembler language program

Your program, written in the assembler language, is 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 is

input to be processed by the linker or the binder. The linker or binder produces a

load module (z/OS and CMS), or a phase (z/VSE), that the computer can load into

its memory and run. Your source module and the object code produced are

printed, along with other information, on a program listing.

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:

v Macro instructions with names that conflict with High Level Assembler symbolic

operation codes

v SET symbols with names that conflict with the names of High Level Assembler

system variable symbols

v Dependencies on the type attribute values of certain variable symbols or macro

instruction operands

Except for these possible conflicts, and with the appropriate High Level Assembler

option values, 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.

z/VSE The DOS/VSE Assembler can process macro definitions to create

“E-decks”. It can then use these E-decks instead of the original macro

definitions for assembling programs that use the macros. High Level

Assembler does not support E-decks. Instead, you can use the z/VSE

ESERV program to convert any E-decks that you already have into macro

definitions that you can use with High Level Assembler.

See the section titled Using the High Level Assembler Library Exit for

Processing E-Decks in the z/VSE: Guide to System Functions. 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. The assembler language is useful

when:

v You need to control your program closely, down to the byte and even the bit

level.

v 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:

v Machine instructions

v Assembler instructions

v Macro instructions

Machine instructions

A machine instruction is the symbolic representation of a machine language

instruction. High Level Assembler supports the following instruction sets:

HLASM V1R6 Language Reference

v IBM System/370

v IBM System/370 Extended Architecture (370-XA)

v Enterprise Systems Architecture/370 (ESA/370)

v Enterprise Systems Architecture/390 (ESA/390)

v 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,” on page 75.

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,” on page 51, Chapter 5, “Assembler

instruction statements,” on page 99, and Chapter 9, “How to write conditional

assembly instructions,” on page 319.

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 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, 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 Chapter 6,

“Introduction to macro language,” on page 239 through Chapter 10, “MHELP

instruction,” on page 403.

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

Chapter 1. Introduction

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 binder.

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:

v Data sets used by the assembler

v Program source statements

v Macros used by the assembler

v Program symbols

v Program object code

v 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 chapter “Controlling Your Assembly with

Options” in the HLASM Programmer's Guide. A subset of assembler options can

be specified in your source program using the *PROCESS statement described in

“*PROCESS statement” 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:

v Producing associated data

v Assigning base registers

v Defining data constants

v Controlling listing output

v Redefining operation codes

v Sectioning and linking programs

v Defining symbols

These instructions are described in Chapter 5, “Assembler instruction

statements,” on page 99.

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 Chapter 6, “Introduction to macro language,” on page 239

through Chapter 10, “MHELP instruction,” on page 403.

Conditional Assembly Instructions

These instructions let you perform general arithmetic and logical

HLASM V1R6 Language Reference

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. Some processing is done 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:

v The assembler evaluates absolute and relocatable expressions (sometimes

called assembly-time expressions)

v Some instructions, such as ADATA, ALIAS, CATTR and XATTR (z/OS

and CMS), DC, DS, ENTRY, EXTRN, PUNCH, and REPRO, produce

output for later processing by programs such as the binder.

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 binder uses such information at link-edit

time to convert one or more object modules into a load module. To run the

program, the operating system loads the load module produced by the binder into

storage and branches to the load module's entry point.

Relationship of assembler to operating system

High Level Assembler operates under the z/OS operating system, the CMS

component of the z/VM operating system, the z/VSE operating system, and Linux

for z Systems. These operating systems provide the assembler with services for:

v Assembling a source module

v Running the assembled object module as a program

z/OS provides the following services:

v For assembling the source module:

- A control program

- Sequential data sets to contain source code

- Libraries to contain source code and macro definitions

Chapter 1. Introduction

- Utilities

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

object module:

- A control program

- Storage allocation

- Input and output facilities

- Binder

- Loader

CMS provides the following services:

v For assembling the source module:

- An interactive control program

- Files to contain source code

- Libraries to contain source code and macro definitions

- Utilities

v 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

z/VSE provides the following services:

v For assembling the source module:

- A control program

- Sequential data sets to contain source code

- Libraries to contain source code and macro definitions

- Utilities

v 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

Linux for z Systems provides the following services:

v For assembling the source module:

- An interactive control program

- Files to contain source code

- Utilities

v 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

In writing a source module, you must include instructions that request required

service functions not provided by the operating system, for example obtaining and

freeing storage.

HLASM V1R6 Language Reference

Coding made easier

It can be difficult to write an assembler language program using only machine

instructions. The assembler provides additional functions that make this task easier.

Here is a summary of these additional functions:

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 “Symbols” on 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

Relocatability

The assembler can produce 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 relative-immediate or

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 52.

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.

Chapter 1. Introduction

A discussion of sectioning and linking is contained in “Source program structures”

on page 52.

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 99, and in “Processing

statements” on page 257. Assembler options and user I/O exits are discussed in

the chapters “Controlling Your Assembly with Options” and “Providing User

Exits” 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

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 the section “BATCH” in the HLASM Programmer's Guide.

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.

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

book, 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. To enter

shift-in and shift-out characters you might need to edit the source code in

hexadecimal. Typically, the shift-in and shift-out characters are displayed as spaces

on your screen and in printed listings.

The following figure summarizes the DBCS notation used throughout this manual.

Characters Represents

Notes^®

Shift-out (SO) X'0E'

An Assembler instruction can include

a less-than and greater-than symbols

Shift-in (SI) X'0F'

that you enter using the less-than and

greater-than keys on your keyboard in

the normal way. The characters also

show as less-than and greater-than

symbols on your screen and in printed

listings, for example: DC C’<>’

D1D2D3... Double-byte characters

DaDbDc... Double-byte characters

HLASM V1R6 Language Reference

Characters Represents

Notes^®

.A.B.C.'.&., EBCDIC characters in double-byte

The use of full-stop to represent X'42'

form: A, B, C, apostrophe, ampersand,

applies only when it is shown between

and comma. The dots separating the

shift-in and shift-out.

letters represent the hexadecimal value

X'42'. A double-byte character that

contains the value of an EBCDIC

ampersand or apostrophes in either

byte is not recognized as a delimiter

when enclosed by SO and SI.

abcd...

Single-byte (EBCDIC) characters

XXX

Extended continuation indicator for

macro-generated statements

+++

Alternative extended continuation

indicator for macro-generated

statements

Chapter 1. Introduction

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 Table 2.

Table 2. Standard character set

Character Type

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, refer to the web page “Coded Character

Set Reference Material”, which is located at:

http://www.ibm.com/software/globalization/g11n-res.html

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 apostrophes, 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 use strings of alphanumeric characters to

represent terms, and special characters as:

v Arithmetic operators in expressions

v Data or field delimiters

v 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 apostrophes, or within the positional

and keyword operands of macro instructions.

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:

Table 3. Double-byte character set (DBCS)

Character or code

Description

Double-byte space

X'4040'

Double-byte characters

Each double-byte character contains 2 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 section “DBCS” in the HLASM Programmer's

Guide.

2. When the DBCS assembler option is specified, double-byte characters can be used

anywhere that EBCDIC characters enclosed by apostrophes can be used.

3. Regardless of the invocation option, double-byte characters can 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 Table 4. For a description of the DBCS notation used in the examples, see

“Double-byte character set notation” on page 8.

Table 4. Examples using character set

Characters

Usage

Example

Constituting

Alphanumeric

In ordinary symbols Label

Terms

FIELD#01

Save_Total

&EASY_TO_READ

In variable symbols

&EASY_TO_READ

Digits

As decimal

Terms

self-defining

terms

Special

Characters

As operators

Addition

NINE+FIVE

Expressions

HLASM V1R6 Language Reference

Table 4. Examples using character set

(continued)

Characters

Usage

Example

Constituting

Subtraction

NINE-5

Expressions

Multiplication

9*FIVE

Expressions

Division

TEN/3

Expressions

+ or -

(Unary)

+NINE

-FIVE

Terms¹

As delimiters

Spaces

Between fields

LABEL AR

3,4

Statement

Comma

Between operands

OPND1,OPND2

Operand field

Apostrophes

Enclosing character

’STRING’

String

strings

Attribute operator

L’OPND1

Term

Parentheses

Enclosing subfields

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

Statement

or subexpressions

expression

SO and SI

Enclosing

C’<.A.B.C>abc’

double-byte data

G’<D1D2D3D4>’

Mixed string

Pure DBCS

As indicators for

Ampersand

Variable symbol

&VAR

Term

Period

Symbol qualifier

QUAL.SYMBOL

Term

Sequence symbol

.SEQ

(label)

Comment statement

.*THIS IS A COMMENT

Statement

in macro definition

Concatenation

&VAR.A

Term

Bit-length

DC CL.7’AB’

Operand

specification

Decimal point

DC F’1.7E4’

Operand

Asterisk

Location counter

*+72

Expression

reference

Comment statement

*THIS IS A COMMENT

Operand

Equal sign

Literal reference

6,=F’2’

Operand

Keyword

&KEY=D

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.

Using EBCDIC characters and double-byte characters

Examples showing the use of EBCDIC characters and double-byte characters are

given in Table 5 on page 14. For a description of the DBCS notation used in the

examples, see “Double-byte character set notation” on page 8.

Chapter 2. Coding and structure

Table 5. Examples using character set

Characters

Usage

Example

Constituting

Alphanumeric

In ordinary symbols

Label

Terms

FIELD#01

Save_Total

&EASY_TO_READ

In variable symbols

&EASY_TO_READ

Digits

As decimal

Terms

self-defining

terms

Special

Characters

As operators

Addition

NINE+FIVE

Expressions

Subtraction

NINE-5

Expressions

Multiplication

9*FIVE

Expressions

Division

TEN/3

Expressions

+ or -

(Unary)

+NINE

-FIVE

Terms¹

As delimiters

Spaces

Between fields

LABEL AR

3,4

Statement

Comma

Between operands

OPND1,OPND2

Operand field

Apostrophes

Enclosing character

’STRING’

String

strings

Attribute operator

L’OPND1

Term

Parentheses

Enclosing subfields

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

Statement

or subexpressions

expression

SO and SI

Enclosing

C’<.A.B.C>abc’

double-byte data

G’<D1D2D3D4>’

Mixed string

Pure DBCS

As indicators for

Ampersand

Variable symbol

&VAR

Term

Period

Symbol qualifier

QUAL.SYMBOL

Term

Sequence symbol

.SEQ

(label)

Comment statement

.*THIS IS A COMMENT

Statement

in macro definition

Concatenation

&VAR.A

Term

Bit-length

DC CL.7’AB’

Operand

specification

Decimal point

DC F’1.7E4’

Operand

Asterisk

Location counter

*+72

Expression

reference

Comment statement

*THIS IS A COMMENT

Operand

Equal sign

Literal reference

6,=F’2’

Operand

Keyword

&KEY=D

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.

HLASM V1R6 Language Reference

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 section “TRANSLATE” in the HLASM Programmer's Guide.

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

is used, except for C-type character self-defining terms where the

COMPAT(TRANSDT) assembler suboption in effect.

Assembler language coding conventions

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

│

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

│ 80 │

│

│ │

│

└──────────────────Statement Field──────────────────┴ │ ─┴─Identification-Sequence Field──┘

⌂

Continuation-

Indicator Field

Figure 2. Standard assembler coding format

Field boundaries

Assembler language statements normally occupy one 80-character record, or line.

For information about statements that occupy more than 80 characters, see

“Continuation lines” on page 16. Each line is divided into three main fields:

v Statement field

v Continuation-indicator field

v 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 normally 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 19.

The assembler assumes the following standard values for these columns:

Chapter 2. Coding and structure

v The begin column is column 1

v The end column is column 71

v 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:

v 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.

v An extended continuation-indicator provides the ability to extend the end

column to the left on a line-by-line basis, so that any alignment of double-byte

data in a source statement can be supported.

v 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 the source statements are in the correct sequence.

The columns that are checked by the ISEQ function are not restricted to columns

73 through 80, or by the boundaries determined by any ICTL instruction. The

columns that are 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 can be continued after column 16.

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.

HLASM V1R6 Language Reference

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 section “FLAG” 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 in “Alternative statement format,”

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:

v AGO conditional assembly statement, see “Alternative format for AGO

instruction” on page 400

v AIF conditional assembly statement, see “Alternative format for AIF instruction”

on page 398

v GBLA, GBLB, and GBLC conditional assembly statements, see “Alternative

format for GBLx statements” on page 347

v LCLA, LCLB, and LCLC conditional assembly statements, see “Alternative

format for LCLx statements” on page 348

v Macro instruction statement, see “Alternative formats for a macro instruction”

on page 298

v Prototype statement of a macro definition, see “Alternative formats for the

prototype statement” on page 248

v SETA, SETB, SETAF, SETCF, and SETC conditional assembly statements, see

“Alternative statement format” on page 394

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:

v Where double-byte data is created by a code-generation program, and

v There is no requirement for double-byte data to be readable on a device capable

of presenting DBCS characters

A double-byte character string can 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 might 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:

v 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 column of

the next line, the SI and SO are considered redundant and are removed from the

statement before statement analysis.

v 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 can be shifted to the left by

extending the continuation-indicator.

Chapter 2. Coding and structure

v To guard against accidental continuation caused by double-byte data ending in

the continuation-indicator column, SO and SI are not continuation indicators. If

either falls in the continuation-indicator column, this warning message is issued:

ASMA201W SO or SI in continuation column - no continuation

assumed

The use of these features is shown in “Examples.” Refer to “Double-byte character

set notation” on page 8 for the notation used in the examples.

Source input considerations:

v Extended continuation-indicators can 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.

v 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.

v When converting existing programs for assembly with the DBCS option, ensure

that continuation-indicators are different from the adjacent data in the end

column.

v 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:

ASMA205E Extended continuation column must not extend into continue

column

v 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

│

⌂

DBCS1

C’<D1D2D3D4D5D6D7D8D9>XXXXXXXXXXXXXXXXXXXX

<DaDb>’

DBCS2

C’abcdefghijklmnopqrstuvwxyz0123456789XXXX

<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:

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:

abcdefghijklmnopqrstuvwxyz0123456789<DaDb>

DBCS3

The DBCS3 constant contains 22 EBCDIC characters followed by nine

double-byte characters. Alignment of the double-byte data requires that the

HLASM V1R6 Language Reference

end column is 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:

v For source that does not contain substituted variable symbols, the listing exactly

reflects the source input.

v 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.

v Refer to “Listing of generated fields containing double-byte data” on page 250

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:

v 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.

v Any characters of the EBCDIC character set, or double-byte character set can be

used (see “Character set” on page 11).

v 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.

v Comment statements must not appear between an instruction statement and its

continuation lines.

Instruction statement format

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

They are:

v A name entry

v An operation entry

v An operand entry

v 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:

v The entries must be written in the following order: name, operation, operand,

and remarks.

Chapter 2. Coding and structure

v 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.

v The entries must be separated from each other by one or more spaces.

v If used, a name entry must start in the begin column.

v The name and operation entries, each followed by at least one space, must be

contained in the first line of an instruction statement.

v 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 generally 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 219 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 that

no name has been entered. No spaces or double-byte data can 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:

v An operation entry is mandatory, and it must appear on the same line as any

name entry.

v 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, refer to the z/Architecture Principles of Operation

information. For a summary of assembler instructions, see Appendix A,

“Assembler instructions,” on page 407.

The standard set of codes can be changed by OPSYN instructions (see “OPSYN

instruction” on page 202).

v For macro instructions, the operation entry can be any valid symbol.

v 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:

v One or more operands are typically required, depending on the instruction.

HLASM V1R6 Language Reference

High Level Assembler for z/OS & z/VM & z/VSE. Language Reference (Version 1 Release 6) - page 2