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

v Operands must be separated by commas. No spaces are allowed between the

operands and the commas that separate them.

v A space normally indicates the end of the operand entry, unless the operand is

in apostrophes. This applies to machine, assembler, and macro instructions.

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

–

“Logical (SETB) expressions” on page 372

–

“Character (SETC) expressions” on page 378

There are two examples of operands containing spaces in Figure 6 on page 26;

the last box in Row 3, and the middle box in Row 4.

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

R1,4+5

No space

The following instruction appears 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 an LA R1,4, which is possibly not

what you intended.

A space inside unquoted parentheses is an error, and leads to a diagnostic. The

following instruction is correctly coded:

CL(L’STRLEN)’ ’

Space within quotes

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

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:

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

Remarks entries: Remarks are used to describe the current instruction. The

following rules apply to remarks:

v Remarks are optional.

v They can contain any character from the EBCDIC character set, or the

double-byte characters set.

v They can follow any operand entry.

v 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. For example:

END

End of Program

Chapter 2. Coding and structure

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

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 3 on page 23, and not in the other

figures.

The machine instruction statements are described in Figure 4 on page 24, discussed

in Chapter 4, “Machine instruction statements,” on page 75, and summarized in the

z/Architecture Principles of Operation information.

Assembler instruction statements are described in Figure 5 on page 25, discussed in

Chapter 3, “Program structures and addressing,” on page 51 and Chapter 5,

“Assembler instruction statements,” on page 99, and are summarized in

Appendix A, “Assembler instructions,” on page 407.

Conditional assembly instruction statements and the macro processing statements

(MACRO, MEND, MEXIT, MNOTE, AREAD, ASPACE, and AEJECT) are described

in Figure 6 on page 26. The conditional assembly instructions are discussed in

Chapter 9, “How to write conditional assembly instructions,” on page 319, and

macro processing instructions in Chapter 7, “How to specify macro definitions,” on

page 245. Both types are summarized in Appendix A, “Assembler instructions,” on

page 407.

Macro instruction statements are described in Figure 7 on page 27, and discussed

in Chapter 8, “How to write macro instructions,” on page 297.

HLASM V1R6 Language Reference

Overview of assembler language structure

┌─────────────────────────┐

│

Source module

│

made up of

│

source statements

│

!────────────┬────────────┘

│

⌂ Which can be

│

EITHER │ OR

┌──────────────────────────◄─┴─►──────────────────────────┐

⌂

┌────────────┴────────────┐

│

INSTRUCTION

│

COMMENT

│

STATEMENTS

│

STATEMENTS

│

!────────────┬────────────┘

│

⌂ Which are of

│

│ three main types

│

┌─────────────────────┼─────────────────────┐

│

⌂

│

┌───────┴───────┐

│

│ MACHINE

│

│ ASSEMBLER

│

│ MACRO

│

│ Instructions │

│

!───────┬───────┘

│

⌂

│

!─────────────────────┼─────────────────────┘

│

⌂ Which are composed of

│

│ from one to four fields

│

┌─────────────────────┼─────────────────────┬─────────────────────┐

│

⌂

│

┌───────┴───────┐

│

NAME

│

│ OPERATION

│

OPERAND

│

REMARKS

│

!───────┬───────┘

⌂

│

⌂

│

┌───────┴───────┐

│

!───────────►─┤

│

No DBCS

│

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 3. Overview of assembler language structure

Chapter 2. Coding and structure

Machine instructions

┌───────────────┐

│

NAME

│

│ OPERATION

│

OPERAND

│

Field

│

│ Field

│

Field

│

!───────┬───────┘

│

⌂ Which

│ can be

│ must be

│ can be

┌───────┴───────┐

│

│ A Symbol¹

│

│ A symbolic

│

│ Zero or more │

│

(or space)

│

│ Operation

│

│ arguments

│

│ Code

│

!───────────────┘

!───────┬───────┘

│

⌂ Composed of one of

┌────────────────────────┬───────────┴────────────┐

⌂

┌───────┴───────┐

│

│ Exp(Exp,Exp) │

│ Expression

│

Exp(Exp)

│

│ or

│

│ Exp(,Exp)

│

!───────┬───────┘

!───────────────┘

│

⌂ Which can be one of

┌────────────┴───────────┐

⌂

┌───────┴───────┐

│

│ Arithmetic

│

Term

│

│ combination

│

│ of terms

│

!───────┬───────┘

!───────────────┘

│

⌂ Which can be any of

├────────────────────────┬────────────────────────┬────────────────────────┬────────────────────────┐

⌂

┌───────┴───────┐

│

│ A Symbol

│

│ Location

│

│ Symbol

│

│ A

│

│ A Literal

│

│ Counter

│

│ Attribute

│

│ Self-Defining │

│

│ Reference

│

│ 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 4. Machine instructions

HLASM V1R6 Language Reference

Assembler instructions

┌───────────────┐

│

NAME

│

│ OPERATION

│

OPERAND

│

Field

│

│ Field

│

Field

│

!───────┬───────┘

│

⌂ Which

│ can be

│ must be

│ can be

┌───────┴───────┐

│

A Symbol¹

│

│ A symbolic

│

│ Zero or more │

│

(or space)

│

│ Operation

│

│ operands

│

│ Code²

│

!───────────────┘

!───────┬───────┘

│

┌───────────────────────────────────────────────┴────────────────────────────┐

⌂

┌──────────┴──────────┐

│ 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. 10 E B L2

’12’

│

│ One or more nominal values

!──┴──┴──┴───┴─────┘

│

┌────────────────────────┬────────────┴─────────────┬──────────────────────────┐

⌂

│

⌂

┌───┴───┴───────┐

┌───────┴───────┐

┌──────┴──────┐

┌───────┴───────┐

│ ’Decimal

│

│ (Expression)

│

│ ’Character

│

│ ’Graphic

│

│ number’

│

│ string’

│

│ string’⁴

│

│ (e.g. ’12’)

│

│ (e.g. (ADDR)) │

│ (e.g. ’ABC’)│

│ (e.g. ’<.A>’) │

!───────────────┘

!─────────────┘

!───────────────┘

¹ 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 5. Ordinary assembler instruction statements

Chapter 2. Coding and structure

Conditional assembly instructions

┌───────────────┐

│

NAME

│

│ OPERATION

│

OPERAND

│

Field

│

│ Field

│

Field

│

!───────┬───────┘

│

⌂ Which

│

│ can be

│

┌────────────┴────────────┐

⌂ Which

⌂

│ must be

│ can be

┌───────┴───────┐

│

│ Sequence

│

│ Variable

│

│ A symbolic

│

│ Zero or more

│

│ Symbol

│

│ Symbol

│

│ Operation

│

│ operands

│

│ or space

│

│ Code

│

(e.g. .SEQ)

│

(e.g. &VAR)

│

!───────────────┘

!───────┬───────┘

│

⌂ Composed of

┌─────────────────────────┬─────────────────────────┬─────────────────────────┤

⌂

┌───────┴───────┐

│

│ Sequence

│

│ Variable

│

│ Expression

│

│ (Exp)seq─sym

│

│ Symbol

│

│ Symbol

│

│ or

│

│ (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

│

│ Expression

│

│ Expression

│

│ (e.g.

│

│ (e.g. &A+1)

│

│ (&B1 OR &B2)) │

│ (e.g. ’JAN&C’)│

!───────────────┘

Figure 6. Conditional assembly instructions

Macro instruction statements are described in Figure

7 on page 27.

HLASM V1R6 Language Reference

Macro instructions

Prototype

┌───────────────┐

Statement

│

│ Symbolic

│

│ 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

│

│ Field

│

Field

│

!───────┬───────┘

!───────────────┘

!───────┬───────┘

⌂

│

┌───────┴───────┐

│

│ Zero or more

│

│ Operands

│

!───────┬───────┘

│

⌂ 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

├─────────────────────┬─────────────────────┐

┌──────────┴──────────┐

⌂

┌───────┴───────┐

│

│ Ordinary

│

Sequence

│

Variable

│

│ Character

│

’Character

│

│ Symbol

│

Symbol

│

Symbol

│

│ String

│

String’

│

(or space)

│

(excluding

│

(including

│

spaces and

│

spaces)

│

commas)

│

!───────────────┘

Figure 7. Macro instructions

Mnemonic tags

With mnemonic tagging, you can add a “:ASM” or “:MAC” suffix to an operation

code. The mnemonic directs the assembler in this way:

:ASM The assembler searches for machine or assembler instructions only. Macros

of the same name are ignored. If the operation code is not found, then the

search ends.

:MAC The assembler searches for macro instructions only. Machine and assembler

instructions are ignored. If the entry is not found in the current table, then

a search for a definition of opcode is done on SYSLIB (the normal search).

Chapter 2. Coding and structure

For example, say there is a machine code entry named AR. Then AR finds that

entry (no change). AR:ASM is the same; the assembler looks for a machine or

assembler instruction. With AR:MAC, the assembler looks for a macro named AR. If

it is not found in the internal table then the assembler searches on SYSLIB.

Assuming AR is found, the assembler adds a macro entry for AR to the table, and

this entry is used for this instruction.

Note: Library macros are added after any existing entry of the same name, while

an inline macro is added before any existing entry. This is done to preserve the

current behavior when mnemonic tags are not used.

Terms, literals, and expressions

The most basic element of the assembler language is the term. Terms can 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. Table 6 summarizes the various types of terms, and

gives a reference to the page number where the term is discussed and the rules for

using it are described. For more information about absolute and relocatable

expressions, see “Absolute and relocatable expressions” on page 48.

Table 6. Summary of terms

Value is

Term can be Term can be assigned by

inherent in Page

Terms

absolute

relocatable assembler

term

reference

Symbols

“Symbols”

on page 29

Literals

“Literals,

constants,

and

self-defining

terms” on

page 42

Self-defining terms X

“Self-

defining

terms” on

page 34

Location counter

“Location

reference

counter” on

page 36

HLASM V1R6 Language Reference

Table 6. Summary of terms (continued)

Value is

Term can be Term can be assigned by

inherent in Page

Terms

absolute

relocatable assembler

term

reference

Symbol length

“Symbol

attribute

length

attribute

reference”

on page 38

Other data

“Other

attributes¹

attribute

references”

on page 42

Notes:

1. Other valid data attributes are scale and integer.

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 can 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)+10)

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

Symbols

You can use a symbol to represent a storage location or an arbitrary value. 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:

v Registers

v Displacements in explicit addresses

v Immediate data

v Lengths

v Implicit addresses with absolute values

For details of these program elements, see “Operand entries” on page 83.

Chapter 2. Coding and structure

The advantages of symbolic over numeric representation are:

v Symbols are easier to remember and use than numeric values, thus reducing

programming errors and increasing programming efficiency.

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

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

v If the symbols are relocatable, the assembler can calculate displacements and

assign base registers for you.

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

- 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” on page 38” and ““Self-defining terms” on page 34” in

this chapter for more details. The three types of symbols recognized by the

assembler are:

v Ordinary symbols

v Variable symbols

v Sequence symbols

Ordinary symbols: Ordinary symbols can be used in the name and operand fields

of machine and assembler instruction statements. There are two types of ordinary

symbol, internal and external. Code them to conform to these rules:

v 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 can be alphabetic characters, digits, or a combination of the two.

v The assembler does not distinguish between upper-case and lower-case letters

used in symbols.

v If the GOFF option is not specified, external symbols must not consist of more

than eight characters.

v No other special characters can be included in an ordinary symbol.

v No spaces are allowed in an ordinary symbol.

v No double-byte data is allowed in an ordinary symbol.

External symbols are placed in the External Symbol Dictionary of the object

module, where they are available to link editors and binders for linking with other

separately translated programs. Internal symbols are normally discarded at the end

HLASM V1R6 Language Reference

of the assembly, but might be placed in the SYSADATA file (see “Input and output

files” in the HLASM Programmer's Guide) for use by other programs such as

debuggers.

In the following sections, the term symbol refers to the ordinary symbol.

The following examples are valid ordinary symbols:

ORDSYM#435A

HERE

$OPEN

#0123

B49467LITTLENAIL

@33

_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 245.

The following examples are valid variable symbols:

&VARYINGSYMABC

&@ME

&F346944

&EASY_TO_READ

System variable symbol prefix: Do not begin a variable symbol with the

characters &SYS, as these characters are used to prefix System Variable Symbols. See

“System variable symbols” on page 263 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,” on page

319.)

The following examples are valid sequence symbols:

.BLABEL04

.#359

.BRANCHTOMEFIRST

Symbol definition: An ordinary symbol is defined in:

v The name entry in a machine or assembler instruction of the assembler language

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

v Any machine or assembler instruction, except the EQU or OPSYN instruction

(see ▌1▐ in Figure 8 on page 32). F004 is the address of the area.

Chapter 2. Coding and structure

v A storage area defined by the DS instruction (see ▌2▐ in Figure 8). Symbol

AREA is 4 byte storage area at location counter 00000004.

v Any constant defined by the DC instruction (see ▌3▐ in Figure 8). Symbol

F200 is a 4 byte constant defined at location counter 00000008, with the object

code initialized to a value of x’000000c8’.

The address value assigned is relocatable, because the object code assembled

from these items is relocatable. The relocatability of addresses is described in

“Addresses as machine instruction operands” on page 85.

The symbol is assigned the value of the first or only expression specified in the

operand of an EQU instruction. This expression can have one of the following

values, which is then assigned to the ordinary symbol:

relocatable

See ▌4▐ in Figure 8. Symbols FULL and TWO00 are relocatable symbols

whose value is set by the location counters of AREA and FULL

respectively.

absolute

See ▌5▐ in Figure 8. Symbol R3 is an absolute symbol, whose value is 3.

See ▌6▐ in Figure 8. Statements 26, 27 illustrate the relocatable symbols being

used. The object code and ADDR2 value show the resolved values of the two

relocatable symbols

The value of an ordinary absolute symbol must lie in the range -2³¹ through

+2³¹-1. Relocatable symbols have unsigned address values in the range 0 - 2²⁴-1,

or 0 - 2³¹-1 if the GOFF option is specified.

LPSAMP04 Sample Program - LRSAMP04 - HLASM

Page

Active Usings: None

Loc

Object Code

Addr1

Addr2

Stmt Source Statement

HLASM R6.0

2015/02/24 13.32

2 ***********************************************************************

3 *

4 * Licensed Materials - Property of IBM

5 *

6 *

5696-234

7 *

9 *

10 * US Government Users Restricted Rights - Use, duplication

11 * or disclosure restricted by GSA ADP Schedule Contract

12 * with IBM Corp.

13 *

14 ***********************************************************************

LPSAMP04 Assembler source to Object code

Page

Active Usings: None

Loc

Object Code

Addr1

Addr2

Stmt Source Statement

HLASM R6.0

2015/02/24 13.32

00000000

00000000 00000014

16 LPSAMP04 CSECT

0000000E

17 R14

EQU

0000000F

18 R15

EQU

R:F 00000000

USING *,R15

00000000 5830 F004

00000004

20 LOAD

R3,AREA ▌1▐

00000004 00000000

21 AREA

F’0’

▌2▐

00000008 000000C8

22 F200

F’200’

▌3▐

00000004

23 FULL

EQU

AREA ▌4▐

00000008

24 TWO00

EQU

F200 ▌4▐

00000003

25 R3

EQU

▌5▐

0000000C 5830 F004

00000004

26 ▌6▐

R3,FULL

00000010 5A30 F008

00000008

27 ▌6▐

R3,TWO00

END

Figure 8. 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:

HLASM V1R6 Language Reference

v 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. It identifies the resumption of the control section specified by the

name field.

z/VM and z/OS

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.

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

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

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

An ordinary symbol is not defined when:

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

v It is used as the operand of a V-type address constant.

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

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

v In operand expressions of certain instructions such as CNOP instructions and

some ORG instructions

v In modifier expressions of DC, DS, and DXD instructions

v In the first operand of an EQU instruction

v In Q-type constants

When using the forward-reference capability of the assembler, avoid the following

types of errors:

v Circular definition of symbols, such as:

EQU

Chapter 2. Coding and structure

v Circular location-counter dependency, as in this example:

(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 can contain symbolic expressions in modifiers, but any ordinary symbols

used must have been previously defined.

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. Here are some examples of self-defining terms and the binary values

they represent:

Self-Defining Term

Decimal Value

Binary Value

1111

241

1111 0001

B’1111’

1111

B’11110001’

241

1111 0001

B’100000001’

257

0001 0000 0001

X’F’

1111

X’F1’

241

1111 0001

X’101’

257

0001 0000 0001

C’1’

241

1111 0001

C’A’

193

1100 0001

C’AB’

49,602

1100 0001 1100 0010

G’<.A>’

17,089

0100 0010 1100 0001

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-aligned. Truncation or padding with zeros, if necessary, occurs on the left.

Decimal self-defining term: A decimal self-defining term is an unsigned decimal

number written as a sequence of decimal digits. High-order zeros can be used (for

HLASM V1R6 Language Reference

example, 007). Limitations on the value of the term depend on its use. For

example, a decimal term that designates a general register must have a value 0 -

15. A decimal term that represents an address must not exceed the size of storage.

In any case, a decimal term must not exceed 2,147,483,647 (2³¹-1). A decimal

self-defining term is assembled as its binary equivalent. Some examples of decimal

self-defining terms are: 8, 147, 4092, and 00021.

Hexadecimal self-defining term: A hexadecimal self-defining term consists of

hexadecimal digits enclosed in apostrophes and preceded by the letter X; for

example, X’C49’ and X’00FF00FF00’.

Each hexadecimal digit is assembled as its 4 bit binary equivalent. Thus, a

hexadecimal term used to represent an 8 bit mask consists of two hexadecimal

digits.

The hexadecimal digits and their bit patterns are as follows:

0 - 0000

4 - 0100

8 - 1000

C - 1100

1 - 0001

5 - 0101

9 - 1001

D - 1101

2 - 0010

6 - 0110

A - 1010

E - 1110

3 - 0011

7 - 0111

B - 1011

F - 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 apostrophes and preceded by the letter B; for

example, B’10001101’. A binary term can have up to 32 bits, not counting leading

zero 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’10101101’

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

characters enclosed in apostrophes, and must be preceded by the letter C. All

letters, decimal digits, and special characters can be used in a character

self-defining term. In addition, any of the remaining EBCDIC characters can 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 apostrophes 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 apostrophe or ampersand you want in a character self-defining term,

two apostrophes or ampersands must be written. For example, the character

Chapter 2. Coding and structure

value A’# is written as ’A’’#’, while a single apostrophe followed by a space

and another apostrophe is written as ’’’ ’’’.

For C-type character self-defining terms, each character in the character sequence is

assembled as its 8 bit code equivalent. For more details, refer to the web page

“Coded Character Set Reference Material”, which is located at:

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

The two apostrophes or ampersands that must be used to represent an apostrophe

or ampersand within the character sequence are assembled as an apostrophe or

ampersand. Double-byte data can 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 does 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.

The following Invariant characters have the same encoding (binary value) in all

EBCDIC code pages. When you enter an invariant character you can be sure that

the resulting binary value does not depend on which EBCDIC code page your

input device (editor) is using. It will display or print as the same character

regardless of which EBCDIC code page the output device (display or printer) is

using.

v space

v decimal digits

v upper-case and lower-case letters A through Z

v these special characters:

+ < = > % & * " ’ ( ) , _ - . / : ; ?

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 apostrophes and

preceded by the letter G. Any valid double-byte characters can 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

HLASM V1R6 Language Reference

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

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.

Here is an example of the application of these rules:

Location in

Source

Hexadecimal

Statements

000004

DONE

DC CL3’ABC’

000007

BEFORE

EQU *

000008

DURING

DC F’200’

00000C

AFTER

EQU *

000010

DS 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 62.

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 4 bytes are displayed if the

LIST(133) option is active. In this case the maximum valid location counter value is

2²⁴-1.

z/VM and z/OS

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 2³¹-1.

If the location counter exceeds its valid maximum value the assembler issues error

message

ASMA039S 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,” on page 51 and

Chapter 2. Coding and structure

Chapter 5, “Assembler instruction statements,” on page 99. 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:

v The asterisk can be specified only in the operands of:

- Machine instructions

- DC and DS instructions

- EQU, ORG, and USING instructions

v It can also be specified in literal constants. See “Literals” on page 42. For

example:

THERE

1,=3A(*)

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

*+8

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 136 of “DC instruction” on page 129, and

“Address constants—A and Y” on page 156. For a discussion of location counter

references in literals, see “Subfield 1: Duplication Factor” on page 136.

Symbol length attribute reference

The length attribute of a symbol can 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:

v Specify assembler-determined storage area lengths

v Cause the assembler to compute length specifications for you

v Build expressions to be evaluated by the assembler

The symbol length attribute reference must be specified according to the following

rules:

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

v Symbols must be defined in the same source module in which the symbol length

attribute reference is specified.

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

HLASM V1R6 Language Reference

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.

The assembler assigns the length attribute values to symbols in the name field of

instructions as follows:

v For machine instructions (see ▌1▐ in Figure 9 on page 40), it assigns 2, 4, or 6,

depending on the format of the instruction.

v For the DC and DS instructions (see ▌2▐ in Figure 9 on page 40), 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.

v For the EQU instruction, it assigns the length attribute value of the first or only

term (see ▌3▐ in Figure 9 on page 40) of the first expression in the first operand,

unless a explicit 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 9 on page 40)

- Location counter reference (see ▌5▐ in Figure 9 on page 40)

- L'* (see ▌6▐ in Figure 9 on page 40)

For assembler instructions such as DC, DS, and EQU, the length attribute of the

location counter reference (L'* — see ▌6▐ in Figure 9 on page 40) is equal to 1. For

machine instructions, the length attribute of the location counter reference (L'* —

see ▌7▐ in Figure 9 on page 40) is equal to the length attribute of the instruction in

which the L'* appears.

Chapter 2. Coding and structure

LPSAMP05 Language Reference Sample Program - 5

Page

Active Usings: None

Loc

Object Code

Addr1

Addr2

Stmt Source Statement

HLASM R6.0

2015/02/26

16.08

00000000

00000000 000001B2

16 LPSAMP05 CSECT

00000003

17 R3

EQU

00000004

18 R4

EQU

0000000C

19 R12

EQU

0000000E

20 R14

EQU

0000000F

21 R15

EQU

R:C 00000000

USING LPSAMP05,R12

Assign the base register

00000000 18CF

R12,R15

Load the base address

00000002 E2A894829693F740

24 SYMBOL7 DC

CL12’Symbol7’

0000000E E2A894829693F240

25 SYMBOL2 DC

CL16’Symbol2’

0000001E E2A8948296934040

26 SYMBOL DC

CL8’Symbol’

00000001

27 CurrentLength

EQU L’*

calculate

00000008

28 SYMBOLLength

EQU L’SYMBOL

calculate

00000014

29 SYMBOLExpresion1 EQU L’SYMBOL+SYMBOL2-SYMBOL7

calculate

0000000C

30 SYMBOLExpresion2 EQU L’SYMBOL+L’SYMBOL2-L’SYMBOL7

calculate

31 SYMBOLExpresion3 EQU L’(SYMBOL+SYMBOL2-SYMBOL7)

calculate

** ASMA147E Symbol too long, or first character not a letter - (SYMBOL+SYMBOL2-SYMBOL7)

** ASMA158E Operand expression is defective; set to *

** ASMA435I Record 31 in SMORSA.BOOK.SAMPLE.ASM(LRSAMP05)

on volume: 37P003

32 *

00000026 D24F C046 C096 00000046 00000096

33 MACHA

MVC TO,FROM▌1▐

0000002C 5830 C188

00000188

34 MACHB

L R3,ADDC▌1▐

00000030 1834

35 MACHC

LR R3,R4▌1▐

36 *

00000006

37 LENGTH1

EQU L’MACHA

00000004

38 LENGTH2

EQU L’MACHB

00000002

39 LENGTH3

EQU L’MACHC

40 *

00000032

41 A

DS CL8

0000003A

42 B

DS CL12

00000046

43 TO

DS CL80

00000096

44 FROM

DS CL240

00000186 0000

00000188 00000096

45 ADDC

DC A(FROM)

0000018C E8E4D2D6D5

46 CHAR

DC C’YUKON’

00000191 000000

00000194 000000C8000000C8

47 DUPL

3F’200’

48 *

00000050

49 LENGTH4

EQU L’TO▌2▐

000000F0

50 LENGTH5

EQU L’FROM▌2▐

00000004

51 LENGTH6

EQU L’ADDC▌2▐

00000005

52 LENGTH7

EQU L’CHAR▌2▐

00000004

53 LENGTH8

EQU L’DUPL▌2▐

54 *

00000046

55 RELOC1

EQU TO▌3▐

00000096

56 RELOC2

EQU TO+80▌3▐

00000046 0000002C

57 RELOC3

EQU TO,44▌3▐

00000050

58 ABSOL1

EQU FROM-TO▌3▐

00000050

59 ABSOL2

EQU ABSOL1▌3▐

00000004

60 LENADDC

EQU L’ADDC

61 *

00000050

62 LENGTH9

EQU L’RELOC1

00000050

63 LENGTHA

EQU L’RELOC2

0000002C

64 LENGTHB

EQU L’RELOC3

000000F0

65 LENGTHC

EQU L’ABSOL1

Figure 9. Assignment of length attribute values to symbols in name fields (Part 1 of 2)

HLASM V1R6 Language Reference

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