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

LPSAMP05 Language Reference Sample Program - 5

Page

Active Usings: LPSAMP05,R12

Loc

Object Code

Addr1

Addr2

Stmt Source Statement

HLASM

R6.0

2015/02/26

16.08

000000F0

66 LENGTHD EQU L’ABSOL2

67 *

00000066

68 SDT1

EQU 102▌3▐

000000F7

69 SDT2

EQU X’FF’+A-B▌3▐

00E8E4D2

70 SDT3 EQU C’YUK’▌3▐

71 *

00000001

72 LENGTHE EQU L’SDT1▌4▐

** ASMA019W Length of EQUated symbol SDT1 undefined; default=1

** ASMA435I Record 72 in SMORSA.BOOK.SAMPLE.ASM(LRSAMP05) on volume: 37P003

00000001

73 LENGTHF EQU L’SDT2▌4▐

** ASMA019W Length of EQUated symbol SDT2 undefined; default=1

** ASMA435I Record 73 in SMORSA.BOOK.SAMPLE.ASM(LRSAMP05) on volume: 37P003

00000001

74 LENGTHG EQU L’SDT3▌4▐

** ASMA019W Length of EQUated symbol SDT3 undefined; default=1

** ASMA435I Record 74 in SMORSA.BOOK.SAMPLE.ASM(LRSAMP05) on volume: 37P003

75 *

000001AA

76 ASTERISK EQU *+10▌3▐

00000001

77 LOCTREF EQU L’*▌3▐

000001A0 00000001

78 ADDLA

DC A(L’*)

000001A4 D205 C046 C096 00000046 00000096

79 MOVETO1

MVC TO(L’*),FROM

000001AA D23B C046 C096 00000046 00000096

80 MOVETO2

MVC TO(L’TO-20),FROM

81 *

00000001

82 LENGTHG EQU L’ASTERISK▌5▐

** ASMA019W Length of EQUated symbol ASTERISK undefined; default=1

** ASMA043E Previously defined symbol - LENGTHG

** ASMA435I Record 82 in SMORSA.BOOK.SAMPLE.ASM(LRSAMP05) on volume: 37P003

00000001

83 LENGTHH EQU L’LOCTREF▌6▐

** ASMA019W Length of EQUated symbol LOCTREF undefined; default=1

** ASMA435I Record 83 in SMORSA.BOOK.SAMPLE.ASM(LRSAMP05) on volume: 37P003

00000004

84 LENGTHI EQU L’ADDLA

00000050

85 LENGTHJ EQU L’TO▌7▐

86 *

000001B0 07FE

R14

Return

END

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

Note: Instructions that contain length attribute references L'SDT1, L'SDT2, L'SDT3,

L'ASTERISK, and L'LOCTREF as shown in this figure might generate ASMA019W.

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.

CL8

CL2’AB’

HIORD

MVC

A1(L’B2),B2

LOORD

MVC

A1+L’A1-L’B2(L’B2),B2

A1 names a storage field eight 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:

Chapter 2. Coding and structure

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

STRING

MVC

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:

v Count (K')

v Defined (D')

v Integer (I')

v Number (N')

v Operation code (O')

v Scale (S')

v Type (T')

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

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:

v The data you enter as numbers for computation, addresses, or messages to be

printed is visible in the instruction in which the literal appears.

v You avoid the added effort of defining constants elsewhere in your source

module and then using their symbolic names in machine instruction operands.

The assembler assembles the data item specified in a literal into a literal pool (See

“Literal pool” on page 45). 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:

v Where you can specify them in machine instructions, that is, whether they

represent data or an address of data

v Whether they have relocatable or absolute values

v What is assembled into the object code of the machine instruction in which they

appear

Figure 11 on page 43 shows examples of the differences between literals, constants,

and self-defining terms.

HLASM V1R6 Language Reference

1. A literal with a relocatable address:

3,=F’33’

3,F33

F33

F’33’

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

MVC FLAG,=X’00’

FLAG set to X’00’. See note 1

MVI FLAG,X’00’

FLAG set to X’00’. See note 3

MVI FLAG,ZERO

FLAG set to X’00’. See note 4

FLAG

ZERO

EQU

X’00’

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

4,LOCORE

4,1000

LOCORE EQU

1000

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

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

Chapter 2. Coding and structure

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 can be coded as indicated here:

=10XL5’F3’

where the subfields are:

Duplication factor 10

Type

Modifiers

Nominal value

’F3’

The following instruction shows one use of a literal:

GAMMA

10,=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

10,=F’274’+4

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

operand, including 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

5,LENGTHS(6)

LENGTHS DC

H’11,23,39,48,64’

See “DC instruction” on page 129 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 45.

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 48) is unpredictable.

“Location counter reference” on page 38 describes how you can use the current

location counter in a literal.

The rules for determining whether two literals are identical are:

HLASM V1R6 Language Reference

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

other literal.

2. Otherwise, two literals are identical (and are generated only once), if their

source forms are identical.

Summary of literal rules:

1. S-type address constants can be used in literals.

2. Location counter references (*) can be used in address constants.

3. When a literal address constant contains *, each use of that literal is assigned a

separate location in the literal pool.

4. When a literal address constant contains *, the value used for * is the address of

the (single) instruction in which the literal is used.

When not in a literal, * in an address constant refers to the first byte of the

constant.

5. When a literal address constant containing * also has a duplication factor, the

value of * does not change for each duplication, but remains equal to the

address if the first byte of the instruction in which the literal was used.

When not in a literal, if an address constant containing * is duplicated, the

value of * is updated for each duplication to refer to the address of that

duplication.

6. When an S-type address constant is used in a literal, regardless of whether it

contains *, the base register that is used to compute the base and displacement

that are parts of the S-type address constant is determined by the USING

statements that are in effect at the place that the literal is assembled, not the

USING statements in effect at the place where the literal is referenced in an

instruction. There are two different base-displacement calculations: one in the

instruction referring to the S-type address constant, and one in the S-type

address constant to determine how to address the object of the constant.

Contrast with immediate data: Do not confuse a literal with the immediate data.

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 about positioning literal pools is in “LTORG instruction” on page 198.

Expressions

This section discusses the expressions used in coding operand entries for source

statements. You can use an expression to specify:

v An address

v An explicit length

v A modifier

v A duplication factor

v 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

Chapter 2. Coding and structure

assembler evaluates relocatable and absolute expressions at assembly time.

Figure 12 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 348.

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. Here are examples of valid expressions:

BETA*10

AREA1+X’2D’

B’101’

*+32

C’ABC’

N-25

FIELD+332

L’FIELD

FIELD

LAMBDA+GAMMA

(EXIT-ENTRY+1)+GO

TEN/TWO

ALPHA-BETA/(10+AREA*L’FIELD)-100

=F’1234’

=A(100,133,175,221)+8

Figure 12. Examples of valid expressions

Rules for coding expressions

The rules for coding an absolute or relocatable expression are:

v Unary (operating on one value) operators and binary (operating on two values)

operators are allowed in expressions.

v An expression can have one or more unary operators preceding any term in the

expression or at the beginning of the expression.

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

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

not a multiplication operator.

v An expression must not contain two terms in succession.

v No spaces are allowed between an operator and a term, nor between two

successive operators.

v An expression can contain any number of unary and binary operators, and any

number of levels of parentheses.

v A single relocatable term is not allowed in a multiply or divide operation. Paired

relocatable terms have absolute values and can be multiplied and divided if they

are enclosed in parentheses. See “Paired relocatable terms” on page 48.

Figure 13 on page 47 shows the definitions of absolute and relocatable expressions.

HLASM V1R6 Language Reference

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

│

│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

│

│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 13. 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 25*10+A/B or BETA+10, 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.

Chapter 2. Coding and structure

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

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.

The absolute terms can include Integer and Scale attributes, but not Type

attributes.

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 two 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, if 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:

v The paired terms must have the same relocatability attribute.

v 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 following examples show absolute expressions. A is an absolute term; X and Y

are relocatable terms with the same relocatability:

HLASM V1R6 Language Reference

A-Y+X

A*A

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

Y-32*A

W-X+*

=F’1234’ (literal)

* (reference to

W-X+W

location counter)

W-X+Y

A*A+W-W+Y

Complex relocatable expressions: Complex relocatable expressions, unlike

relocatable expressions, can contain:

v Two or more unpaired relocatable terms

v An unpaired relocatable term preceded by a negative sign

Using the same symbols, here 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” on page 156, and “Address constants—A and Y” on page 156. V-type

and S-type constants cannot contain complex relocatable expressions. You can

assign a complex relocatable value to a symbol using the EQU instruction, as

described in “EQU instruction” on page 188.

Chapter 2. Coding and structure

Chapter 3. Program structures and addressing

This chapter describes:

v How you use symbolic addresses to refer to data in your assembler language

program.

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

considered one-dimensional structures. Examples include z/OS load modules,

CMS modules, and z/VSE phases.

z/VM and z/OS

The second object-program model is the Generalized Object File format

(GOFF). GOFF supports a two-dimensional structure called program

objects. For more information about GOFF, refer to z/OS MVS^™ Program

Management: Advanced Facilities. The loaded program can 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 can contain parts. Unlike a

control section, a program object section can specify more than one

independently relocatable block of text. Addresses within each class can be

resolved to addresses in the same or different classes. A class in a program

object has behavior properties like 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.

z/VM and z/OS

Note: Features supported by High Level Assembler when you specify the

GOFF option might not be supported by the system linker/binder or

run-time environment where the assembled program is 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.

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

Class

─ ─ ─

│

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

│ Control

│

│ part

│

│ Section

│

Section │ element │ element ├─────────┤

│

│ part

│

├─────────────┤

├─────────┼─────────┼─────────┼ ─ ─ ─┤

│ Control

│

│ Section

│

Section │ element │ element │ part

│

├─────────────┤

│

├─────────┼─────────┼─────────┼ ─ ─ ─┤

└─────────────┘

└─────────┴─────────┴─────────┴ ─ ─ ─┘

Load Module Model

Program Object Model

Figure 14. 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 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.

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:

v You can enter them directly into the file that contains your source program.

HLASM V1R6 Language Reference

v 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 125 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 control

section” on page 55 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. If further statements are

found in the input stream, assembly of a new source module is begun. See “END

instruction” on page 186 for more details, and the section “BATCH” in the HLASM

Programmer's Guide for information about the BATCH option.

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.

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

The linker or binder, as directed by its control statements, combines object

code of one or more sections into one load module or program object. It

also calculates the addresses needed to accommodate any common sections

and external dummy sections from different object modules. For

information on common and external dummy sections, see “Common

control sections” on page 57 and “External dummy sections” on page 58.

Chapter 3. Program structures and addressing

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 might 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 might contain only data.

Control sections that create only mappings are called reference control sections.

z/VM and z/OS

In the program object model, sections can define classes containing elements.

(Classes are described in “Classes (z/OS and CMS)” on page 59.) Elements

can contain machine language text or define mappings, or both. Elements

can in turn contain one or more parts, which are described at “Parts (z/OS

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 can be referenced as

an external name only if defined as an entry point in an element belonging

to that section. (By default, the assembler generates an entry point in class

B_TEXT with the section's name. See “Classes (z/OS and CMS)” on page 59

for more information.)

The term “executable” is used to describe executable control sections in the load

module model, or elements in the program, or sections in the program object

model, or elements in the program object model.

You initiate an executable section by using the START, CSECT, or RSECT

instruction, as described below:

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

v The CSECT and RSECT instructions 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 126. For more information about

the RSECT instruction, see “RSECT instruction” on page 216.

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

HLASM V1R6 Language Reference

First control section

Before you initiate the first control section in your source module, you can code

only certain instructions. The following information lists those instructions that

initiate the first control section, and those instructions that can precede the first

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

v The following assembler instructions:

ACONTROL ADATA

AINSERT ALIAS

CEJECT COPY

DXD

EJECT

ENTRY

EXITCTL EXTRN

ISEQ

MACRO

MEND

MEXIT

POP

PUNCH

PUSH

REPRO

SPACE

TITLE

WXTRN

XATTR

v Comment statements, including macro format comment statements

v Any statement which is part of an inline macro definition, between MACRO and

MEND statements, with the possible exception of *PROCESS and ICTL.

v Common control sections

v Dummy control sections

v Any conditional assembly instruction

v Macro instructions that do not generate statements that establish the first section

These instructions or groups of instructions belong to a source module, but are not

considered part of an executable section.

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

CCW0

CCW1

CNOP

COM

CSECT

CXD

DSECT

EQU

LOCTR

LTORG

ORG

RSECT

START

USING

COM, CSECT, DSECT, RSECT, and START start a possibly named control section.

The other statements start an unnamed control section.

These instructions are always considered a part of the control section in which they

appear.

The DSECT, COM, and DXD instructions initiate reference control sections and do

not establish the first executable section.

The statements copied into a source module by a COPY instruction determine

whether it initiates the first control section.

Chapter 3. Program structures and addressing

Any instructions copied by a COPY instruction, or generated by the processing of a

macro instruction before the first section, must belong 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:

v By coding a START, CSECT, RSECT, or COM instruction without a name entry

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

v Within a source module

v In EXTRN and WXTRN instructions

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

v You can use the DSECT instruction to initiate or continue a dummy control

section. For more information about dummy sections, see “Dummy control

sections” on page 57.

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

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

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

HLASM V1R6 Language 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 reserving any virtual storage.

You might 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 182.

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

template or mapping 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:

v Have access to a storage area for the data

v Ensure that the locations of the symbols in the dummy section correspond to the

locations of the data being described

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

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

Chapter 3. Program structures and addressing

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:

v Work areas for each source module

v 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 z/OS GETMAIN macro instruction).

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 the longest

length and strictest alignment among all identically-named external dummy

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

v DXD or DSECT instruction

v Q-type address constant

v CXD instruction

For more information about the DXD and CXD instructions, see “DXD instruction”

on page 185 and “CXD instruction” on page 128.

Note: The names of dummy external control sections might 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 in the External Symbol Dictionary

portion of the listing. The name must satisfy the name-length requirements of the

object file format specified in the assembler options.

HLASM V1R6 Language Reference

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

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.

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 might be arranged in any order. Do

not assume any ordering relationship among external dummy sections.

Classes (z/OS 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 (z/OS and

CMS)” on page 115 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 14 on page 52.

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

SECT_A CSECT ,

Define section SECT_A

CLASS_X CATTR RMODE(ANY)

Define class CLASS_X

- - -

Statements for CLASS_X

CLASS_Y CATTR RMODE(24)

Define class CLASS_Y

- - -

Statements for CLASS_Y

Chapter 3. Program structures and addressing

The statements following the first CATTR instruction are 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 are assigned to an element

defined by the section name SECT_A and the class name CLASS_Y. CLASS_Y is loaded

below 16 Mb, and CLASS_X might be loaded anywhere below 2 Gb.

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 can be specified after the first

CATTR statement declaring the class.

Resuming a section causes subsequent text to be placed in the B_TEXT class if there

is no intervening CATTR statement defining or resuming a different class:

SECT_A CSECT ,

Define section SECT_A

CLASS_X CATTR RMODE(ANY)

Define class CLASS_X

- - -

Statements for CLASS_X

CLASS_Y CATTR RMODE(24)

Define class CLASS_Y

- - -

Statements for CLASS_Y

SECT_A CSECT ,

Resume section SECT_A

- - -

Statements for class B_TEXT

CLASS_X CATTR ,

Resume class CLASS_X

- - -

More statements for CLASS_X

Class binding and loading attributes

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

binding attributes.

v Classes containing parts use merge binding (described at “Parts (z/OS and

CMS)” on page 61). Parts are the smallest independently relocatable components

of a merge class.

v 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

can have identical attributes, and the binder can put such classes into one segment.

The most usual class attributes are RMODE, alignment, and Loadability; see

“CATTR instruction (z/OS and CMS)” on page 115 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.

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

v 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

HLASM V1R6 Language Reference

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