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

Using a length modifier can give you the advantage of explicitly specifying the

length attribute value assigned to the label naming the area reserved. However,

your areas are not aligned automatically according to their type. If you omit the

nominal value in the operand, use a length modifier for the binary (B), character

(C), graphic (G), hexadecimal (X), and decimal (P and Z) type areas. If you do not,

their labels are given a length attribute value of 1 (2 for G and CU type).

When you need to reserve large areas, you can use a duplication factor. However,

in this case, you can only refer to the first area by its label. You can also use the

character (C) and hexadecimal (X) field types to specify large areas using the

length modifier. Duplication has no effect on implicit length.

Although the nominal value is optional for a DS instruction, you can put it to good

use by letting the assembler compute the length for areas of the B, C, G, X, and

decimal (P or Z) type areas. You achieve this by specifying the general format of

the nominal value that is placed in the area at execution time.

If a nominal value and no length modifier are specified for a Unicode character

string, the length of the storage reserved is derived by multiplying by two the

number of characters specified in the nominal value (after pairing).

To force alignment

Use the DS instruction to align the instruction or data that follows, on a specific

boundary. You can align the location counter to a doubleword, a fullword, or a

halfword boundary by using the correct constant type (for example, D, F, or H)

and a duplication factor of zero. No space is reserved for such an instruction, yet

the data that follows is aligned on the correct boundary. For example, the

following statements set the location counter to the next doubleword boundary

and reserve storage space for a 128 byte field (whose first byte is on a doubleword

boundary).

AREA

CL128

Alignment is forced whether or not the ALIGN assembler option is set.

To name fields within an area

Using a duplication factor of zero in a DS instruction also provides a label for an

area of storage without reserving the area. Use DS or DC instructions to reserve

storage for, and assign labels to, fields within the area. These fields can then be

addressed symbolically. (Another way of accomplishing this is described in

“DSECT instruction” on page 182.) The whole area is addressable by its label. In

addition, the symbolic label has the length attribute value of the whole area.

Within the area, each field is addressable by its label.

For example, assume that 80-character records are to be read into an area for

processing and that each record has the following format:

Positions 5-10

Payroll Number

Positions 11-30

Employee Name

Positions 31-36

Date

Positions 47-54

Gross Wages

Positions 55-62

Withholding Tax

Chapter 5. Assembler instruction statements

181

The following example shows how DS instructions might be used to assign a name

to the record area, then define the fields of the area and allocate storage for them.

The first statement names the whole area by defining the symbol RDAREA; this

statement gives RDAREA a length attribute of 80 bytes, but does not reserve any

storage. Similarly, the fifth statement names a 6 byte area by defining the symbol

DATE; the three subsequent statements define the fields of DATE and allocate storage

for them. The second, ninth, and last statements are used for spacing purposes

and, therefore, are not named.

RDAREA DS

0CL80

CL4

PAYNO

CL6

NAME

CL20

DATE

0CL6

DAY

CL2

MONTH

CL2

YEAR

CL2

CL10

GROSS

CL8

FEDTAX

CL8

CL18

Here are some more examples of DS statements:

ONE

CL80

One 80 byte field, length attribute of 80

TWO

80C

Eighty 1 byte fields, length attribute of 1

THREE

6 fullwords, length attribute of 4

FOUR

1 doubleword, length attribute of 8

FIVE

4 halfwords, length attribute of 2

SIX

GL80

One 80 byte field, length attribute of 80

SEVEN

80G

Eighty 2 byte fields, length attribute of 2

To define four 10 byte fields and one 100 byte field, the respective DS statements

might be as follows:

FIELD

4CL10

AREA

CL100

Although FIELD might have been specified as one 40 byte field, the preceding

definition has the advantage of providing FIELD with a length attribute of 10. This

is pertinent when using FIELD as an SS machine instruction operand.

DSECT instruction

The DSECT instruction identifies the beginning or continuation of a dummy

control section. One or more dummy sections can be defined in a source module.

►►

DSECT

►◄

symbol

Is one of the following:

v An ordinary symbol

v A variable symbol that has been assigned a character string with a value that

is valid for an ordinary symbol

v A sequence symbol

182

HLASM V1R6 Language Reference

The DSECT instruction can be used anywhere in a source module after the ICTL

instruction.

If symbol denotes an ordinary symbol, the ordinary symbol identifies the dummy

section. If several DSECT instructions within a source module have the same

symbol in the name field, the first occurrence initiates the dummy section and the

rest indicate the continuation of the dummy section. The ordinary symbol denoted

by symbol represents the address of the first byte in the dummy section, and has a

length attribute value of 1.

If symbol is not specified, or if name is a sequence symbol, the DSECT instruction

initiates or indicates the continuation of the unnamed control section.

The location counter for a dummy section is always set to an initial value of 0.

However, when an interrupted dummy control section is continued using the

DSECT instruction, the location counter last specified in that control section is

continued.

The source statements that follow a DSECT instruction belong to the dummy

section identified by that DSECT instruction.

Notes:

1. The assembler language statements that appear in a dummy section are not

assembled into object code.

2. When establishing the addressability of a dummy section, the symbol in the

name field of the DSECT instruction, or any symbol defined in the dummy

section can be specified in a USING instruction.

3. A symbol defined in a dummy section can be specified in an address constant

only if the symbol is paired with another symbol from the same dummy

section, and if the symbols have opposite signs.

To effect references to the storage area defined by a dummy section, do the

following:

v Provide one of:

- An ordinary or labeled USING statement that specifies:

- A general register that the assembler can use as a base register for the

dummy section.

- A label in the dummy section. The USING instruction tells the assembler

that the register contains the address of this label.

- A dependent or labeled dependent USING statement that specifies:

- A supporting base address (for which there is a corresponding ordinary

USING statement) that lets the assembler determine a base register and

displacement for the dummy section.

- A value from the dummy section that the assembler can assume is the

same as the supporting base address.

v Ensure that the base register is loaded with one of:

- The actual address of the storage area if an ordinary USING statement or a

labeled USING statement was specified.

- The base address specified in the corresponding ordinary USING statement if

a dependent or labeled dependent USING statement was specified.

Chapter 5. Assembler instruction statements

183

The values assigned to symbols defined in a dummy section are relative to the

initial statement of the section. Thus, all machine instructions that refer to names

defined in the dummy section refer, at execution time, to storage locations relative

to the address loaded into the register.

Figure 27 shows an example of how to code the DSECT instruction. The sample

code is referred to as “Assembly-2”.

Assume that two independent assemblies (Assembly-1 and Assembly-2) have been

loaded and are to be run as a single overall program. Assembly-1 is a routine that

1. Places a record in an area of storage

2. Places the address of the storage area in general register 3

3. Branches to Assembly-2 to process the record

The storage area from Assembly-1 is identified in Assembly-2 by the dummy

control section (DSECT) named INAREA. Parts of the storage area that you want

to work with are named INCODE, OUTPUTA, and OUTPUTB. The statement

USING INAREA,3 assigns general register 3 as the base register for the INAREA

DSECT. General register 3 contains the address of the storage area. The symbols in

the DSECT are defined relative to the beginning of the DSECT. This means that the

address values they represent are, at the time of program execution, the actual

storage locations of the storage area that general register 3 addresses.

ASEMBLY2 CSECT

USING

*,15

USING

INAREA,3

CLI

INCODE,C’A’

ATYPE

MVC

OUTPUTA,DATA_B

MVC

OUTPUTB,DATA_A

FINISH

ATYPE

MVC

OUTPUTA,DATA_A

MVC

OUTPUTB,DATA_B

FINISH BR

DATA_A DC

CL8’ADATA’

DATA_B DC

CL8’BDATA’

INAREA DSECT

INCODE DS

CL1

OUTPUTA DS

CL8

OUTPUTB DS

CL8

END

Figure 27. Sample code using the DSECT instruction (Assembly-2)

184

HLASM V1R6 Language Reference

DXD instruction

The DXD instruction identifies and defines an external dummy section. See also

“External dummy sections” on page 58.

►► symbol DXD

type

►

duplication_factor

type_extension

►

►◄

modifier

▼

nominal_value

symbol

Is an external symbol which is one of the following:

v An ordinary symbol

v A variable symbol that has been assigned a character string with a value that

is valid for an ordinary symbol

duplication_factor

Is the duplication factor subfield equivalent to the duplication factor subfield

of the DS instruction.

type

Is the type subfield equivalent to the type subfield of the DS instruction.

type_extension

Is the type extension subfield equivalent to the type extension subfield of the

DS instruction.

modifiers

Is the modifiers subfield equivalent to the modifiers subfield of the DS

instruction.

nominal_value

Is the nominal-value subfield equivalent to the nominal-value subfield of the

DS instruction. The nominal value is optional. If specified, it is not generated.

The DXD instruction can be used anywhere in a source module, after the ICTL

instruction.

In order to reference the storage defined by the external dummy section, the

ordinary symbol denoted by symbol must appear in the operand of a Q-type

constant. This symbol represents the address of the first byte of the external

dummy section defined, and has a length attribute value of 1.

The subfields in the operand field (duplication factor, type, type extension,

modifier, and nominal value) are specified in the same way as in a DS instruction.

The assembler computes the amount of storage and the alignment required for an

external dummy section from the area specified in the operand field. For more

information about how to specify the subfields, see “DS instruction” on page 179.

For example:

Chapter 5. Assembler instruction statements

185

DXD

CL20

20 bytes, byte alignment

DXD

3F,XL4

20 bytes, fullword alignment

DXD

16 bytes, quadword alignment

The linker uses the information provided by the assembler to compute the total

length of storage required for all external dummy sections specified in a program.

Notes:

1. The DSECT instruction also defines an external dummy section, but only if the

symbol in the name field appears in a Q-type offset constant in the same source

module. Otherwise, a DSECT instruction defines a dummy section.

2. If two or more external dummy sections for different source modules have the

same name, the linker uses the most restrictive alignment, and the largest

section to compute the total length.

EJECT instruction

The EJECT instruction stops the printing of the assembler listing on the current

page, and continues the printing on the next page.

►►

EJECT

►◄

sequence_symbol

Is a sequence symbol.

The EJECT instruction causes the next line of the assembler listing to be printed at

the top of a new page. If the line before the EJECT statement appears at the bottom

of a page, the EJECT statement has no effect.

An EJECT instruction immediately following another EJECT instruction is ignored.

A TITLE instruction immediately following an EJECT instruction causes the title to

change but no additional page eject is performed. (The TITLE instruction normally

forces a page eject.)

The EJECT instruction statement itself is not printed in the listing.

END instruction

Use the END instruction to end the assembly of a program. You can also supply an

address in the operand field to which control can be transferred after the program

is loaded. The END instruction must always be the last statement in the source

program.

►►

END

►◄

sequence_symbol

expression

,language

sequence_symbol

Is a sequence symbol.

186

HLASM V1R6 Language Reference

expression

Specifies the point to which control can be transferred when loading of the

object program completes. If the GOFF option is in effect this parameter is

ignored. This point is normally the address of the first executable instruction in

the program, as shown in the following sequence:

NAME

CSECT

AREA

50F

BEGIN

BALR

2,0

USING

*,2

END

BEGIN

If specified, expression can be generated by substitution into variable symbols.

It must not be a literal. It must also satisfy one of these conditions:

v It is a simply relocatable expression representing an address in the source

module delimited by the END instruction.

v If it contains an external symbol, the external symbol must be the only term

in the expression, or the remaining terms in the expression must reduce to

zero.

language

A marker for use by language translators that produce assembly code. The

operand has three suboperands. The values in the operand are copied into the

END record in the object deck if the NOGOFF option is specified, or in a

B_IDRL record if the GOFF option is specified.

The syntax of the operand is

(char10,char4,char5)

where all three suboperands and the commas and parentheses are required.

char10 is a one to ten character code. It is intended to be a language translator

identifier. char4 must be exactly four characters long. It is intended to be a

version and release code. char5 must be exactly five characters long, and

should be a date in the format “YYDDD”. It is intended to be the compile date.

For example:

END

ENTRYPT,(MYCOMPILER,0101,00273)

Notes:

1. If the END instruction is omitted, one is generated by the assembler, and

message ASMA140W END record missing is issued.

2. Refer to the text in “Generating END statements” on page 341 about lookahead

processing, and the effect it has on generated END statements.

3. If the END statement is not the last statement in the input stream, and the

BATCH option has been specified, the assembler initiates assembly of a new

source module when the current assembly is completed. (For more information

about the BATCH option, see the section “BATCH” in the HLASM Programmer's

Guide)

ENTRY instruction

The ENTRY instruction identifies symbols defined in this source module as

“external” so that they can be referred to by another source module. These

symbols are entry symbols.

Chapter 5. Assembler instruction statements

187

▼

►►

ENTRY

entry_point

►◄

sequence_symbol

Is a sequence symbol.

entry_point

Is a relocatable symbol that:

v Is a valid symbol

v Is defined in an executable control section

v Is not defined in a dummy control section, a common control section, or an

external control section

Up to 65535 individual control sections, external symbols, and external dummy

sections can be defined in a source module. However, the practical maximum

number depends on the amount of table storage available to the program that links

the object module.

The assembler lists each entry symbol of a source module in an external symbol

dictionary, along with entries for external symbols, common control sections, parts,

and external control sections.

A symbol used as the name entry of a START or CSECT instruction is also

automatically considered an entry symbol, and does not have to be identified by

an ENTRY instruction.

A symbol identified by an ENTRY instruction should not also be declared by an

EXTRN instruction, but it can be referenced in the nominal value of a V-type

address constant in the same source module.

The length attribute value of entry symbols is the same as the length attribute

value of the symbol at its point of definition.

EQU instruction

The EQU instruction assigns absolute or relocatable values to symbols. Use it to:

v Assign single absolute values to symbols.

v Assign the values of previously defined symbols or expressions to new symbols,

thus letting you use different mnemonics for different purposes.

v Compute expressions whose values are unknown at coding time or difficult to

calculate. The value of the expressions is then assigned to a symbol.

v Assign length and type attributes to symbols, either implicitly or explicitly.

v Assign program type and assembler type values to symbols.

EQU also assigns attributes. It takes the value, relocation, and length attributes of

the operand and assigns them to the name field symbol, and sets the integer and

scale attributes to zero. The type attributes of an absolute expression is always 'U',

and its length attribute is always 1 (unless the second and third operands are

specified.

188

HLASM V1R6 Language Reference

When there is a symbol naming a complex relocatable expression, or a complex

relocatable expression is eventually “reduced” to an absolute or simply relocatable

expression, the first symbol is used for attribute assignment.

The program type is always null, and the assembler type is always null, except

when the appropriate operand is specified.

(1)

►► symbol EQU value

►

length attribute value

►

type attribute value

program type value

►

►◄

assembler type value

Notes:

Use commas as placeholders when there is an expression following

symbol

Is one of the following:

v An ordinary symbol

v A variable symbol that has been assigned a character string with a value that

is valid for an ordinary symbol

value

Represents a value and attributes that the assembler assigns to the symbol in

the name field. value can have any value allowed for an assembly expression:

absolute (including negative), relocatable, or complexly relocatable. The

assembler carries this value as a signed 4 byte (32 bit) number; all 4 bytes are

printed in the program listings opposite the symbol. Implicitly, the relocation

and length attributes are also assigned for certain types of expressions.

Any symbols used in value need not be previously defined. However, if any

symbol is not previously defined, the value of value is not assigned to the

symbol in the name field until assembly time and therefore cannot be used

during conditional assembly (see “Using conditional assembly values” on page

191).

If value is a complexly relocatable expression, the whole expression, rather than

its value, is assigned to the symbol. During the evaluation of any expression

that includes a complexly relocatable symbol, that symbol is replaced by its

own defining expression. Consider the following example, in which A1 and A2

are defined in one control section, and B1 and B2 in another:

EQU

A1+B1

EQU

X-A2-B2

The first EQU statement assigns a complexly relocatable expression (A1+B1) to

X. During the evaluation of the expression in the second EQU statement, X is

replaced by its defining relocatable expression (A1+B1). The assembler

Chapter 5. Assembler instruction statements

189

evaluates the resulting expression (A1+B1-A2-B2) and assigns an absolute value

to Y, because the relocatable terms in the expression are paired. The expression

must not contain literals.

length attribute value

Represents a value that the assembler assigns as a length attribute value to the

symbol in the name field. It is optional, but, if specified, must be an absolute

value in the range 0 to 65,535. This value overrides the normal length attribute

value implicitly assigned from value. For example:

CL121

Define a print line buffer

ACC

Equ

A,1

Define first character, length 1

The symbol ACC has the same location value as A, but length attribute 1.

All symbols appearing in length attribute value must have been previously

defined, and all expressions in length attribute value must be evaluatable when

the EQU statement is processed. For example, the second operand in the

statements defining the symbol X cannot be evaluated when the last statement

has been processed, because the value of the symbol X is unknown until the

symbol A has been defined.

DS XL(L’A)

DS XL(A)

DS XL7

EQU Z,*-Z

DS XL5

EQU 5

If length attribute value is omitted, the assembler assigns a length attribute value

to the symbol in the name field according to the length attribute value of the

leftmost (or only) term of value, as follows:

1. If the leftmost term of value is a location counter reference (*), a

self-defining term, or a symbol length attribute value reference, the length

attribute is 1. This also applies if the leftmost term is a symbol that is

equated to any of these values.

2. If the leftmost term of value is a symbol that is used in the name field of a

DC or DS instruction, the length attribute value is equal to the implicit or

explicit length of the first (or only) constant specified in the DC or DS

operand field.

3. If the leftmost term is a symbol that is used in the name field of a machine

instruction, the length attribute value is equal to the length of the

assembled instruction.

4. Symbols that name assembler instructions, except the DC, DS, CCW,

CCW0, and CCW1 instructions, have a length attribute value of 1. Symbols

that name a CCW, CCW0, or CCW1 instruction have a length attribute

value of 8.

5. The length attribute value described in cases 2, 3, and 4 above is the

assembly-time value of the attribute.

For more information about the length attribute value, see “Symbol length

attribute reference” on page 38.

For example:

X DS

CL80

X has length attribute 80

Y EQU

X,40

Y has length attribute 40

type attribute value

Represents a value that the assembler assigns as a type attribute value to the

symbol in the name field. It is optional, but, if specified, it must be an absolute

value in the range 0 to 255.

190

HLASM V1R6 Language Reference

All symbols appearing in type attribute value must have been previously

defined, and all expressions in type attribute value must be evaluatable when

the EQU statement is processed.

If type attribute value is omitted, the assembler assigns a type attribute value of

U to the symbol, which means the symbol in the name field has an undefined

(or unknown or unassigned) type attribute. See the general discussion about

data attributes in “Data attributes” on page 325, and “Type attribute (T')” on

page 329.

For example:

A has type attribute D

EQU

A,,C’X’

B has type attribute X

program type value

Represents a value (any absolute expression) that the assembler assigns as a

program type value to the symbol in the name field. It is optional. It can be

specified as a decimal, character, hex, or binary self-defining term and is stored

as a 4 byte (32 bit) number; all 4 bytes are printed in the program listings

opposite the symbol. The value is not used in any way by the assembler, and

can be queried by using the SYSATTRP built-in function.

All symbols appearing in program type value must have been previously

defined, and all expressions in program type value must be evaluatable when the

EQU statement is processed.

If program type value is omitted, the assembler assigns a null to the program

type, and querying the value using the SYSATTRP built-in function returns a

null value.

assembler type value

Represents 2 to 4 characters that the assembler assigns as an assembler type

value to the symbol in the name field. It is optional. It is stored as a 4 byte

string; all 4 bytes are printed in the program listings opposite the symbol. The

value is used by the assembler when type-checking has been activated, and can

be queried by using the SYSATTRA built-in function.

Valid values for this operand are:

CR32

CR64

FPR

GR32

GR64

If assembler type value is omitted, the assembler assigns a null value to the

assembler type, and querying the value using the SYSATTRA built-in function

returns a null value.

The EQU instruction can be used anywhere in a source module after the ICTL

instruction. Note, however, that the EQU instruction initiates an unnamed control

section (private code) if it is specified before the first control section.

Using conditional assembly values

The following rules describe when you can use the value, length attribute value, or

type attribute value of an equated symbol in conditional assembly statements:

Chapter 5. Assembler instruction statements

191

v If you want to use the value of the symbol in conditional assembly statements,

then:

- The EQU statement that defines the symbol must be processed by the

assembler before the conditional assembly statement that refers to the symbol.

- The symbol in the name field of the EQU statement must be an ordinary

symbol.

- Expression_1 must be an absolute expression, and must contain only

self-defining terms or previously defined symbols.

v If only expression_1 is specified:

- The assembler assigns a type attribute value of U.

- If the EQU statement that defines the symbol is processed by the assembler

before the conditional assembly statement that refers to the symbol, the

assembler assigns the length attribute of expression_1. Otherwise, the

assembler assigns a length attribute value 1.

You can use these values in conditional assembly statements, although references

to the length attribute might be flagged.

v If you specify expression_2 or expression_3 and you want to use the explicit

attribute value during conditional assembly processing, then:

- The symbol in the name field must be an ordinary symbol.

- The expression must contain only self-defining terms.

EXITCTL instruction

The EXITCTL instruction sets or modifies the contents of the four signed fullword

exit-control parameters that the assembler maintains for each type of exit.

(1)

▼

►►

EXITCTL

exit_type

►◄

sequence_symbol

control_value

Notes:

From one to four values to be supplied.

sequence_symbol

Is a sequence symbol.

exit_type

Identifies the type of exit to which this EXITCTL instruction applies. Exit_type

must have one of the following values:

SOURCE

Sets the exit-control parameters for the user-supplied exit module

specified in the INEXIT suboption of the EXIT assembler option.

LIBRARY

Sets the exit-control parameters for the user-supplied exit module

specified in the LIBEXIT suboption of the EXIT assembler option.

LISTING

Sets the exit-control parameters for the user-supplied exit module

specified in the PRTEXIT suboption of the EXIT assembler option.

PUNCH

Sets the exit-control parameters for the user-supplied exit module

specified in the OBJEXIT suboption of the EXIT assembler option when

192

HLASM V1R6 Language Reference

it is called to process the object module records generated when the

DECK assembler option is specified.

OBJECT (z/OS and CMS)

Sets the exit-control parameters for the user-supplied exit module

specified in the OBJEXIT suboption of the EXIT assembler option when

it is called to process the object module records generated when the

OBJECT or GOFF assembler option is specified.

ADATA

Sets the exit-control parameters for the user-supplied exit module

specified in the ADEXIT suboption of the EXIT assembler option.

TERM Sets the exit-control parameters for the user-supplied exit module

specified in the TRMEXIT suboption of the EXIT assembler option.

control_value

Is the value to which the corresponding exit-control parameter should be set.

For each exit type, the assembler maintains four exit-control parameters known

as EXITCTL_1, EXITCTL_2, EXITCTL_3, and EXITCTL_4. Therefore, up to four

values can be specified. Which exit-control parameter is set is determined by

the position of the value in the operand of the instruction. You must code a

comma in the operand for each omitted value. If specified, control_value must

be either:

v A decimal self-defining term with a value in the range -2³¹ to +2³¹-1.

v An expression in the form *±n, where * is the current value of the

corresponding exit-control parameter to which n, a decimal self-defining

term, is added or from which n is subtracted. The value of the result of

adding n to or subtracting n from the current exit-control parameter value

must be in the range -2³¹ to +2³¹-1.

If control_value is omitted, the corresponding exit-control parameter retains its

current value.

The following example shows how to set the exit-control parameters EXITCTL_1

and EXITCTL_3 for the LISTING exit without affecting the contents of the other

exit-control parameters:

EXITCTL LISTING,256,,*+128

See the section “EXITCTLn” in the HLASM Programmer's Guide for information

about how EXITCTL values are passed to each type of exit.

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

EXTRN instruction

The EXTRN instruction identifies “external” symbols referred to in this source

module but defined in another source module. These symbols are external

symbols.

▼

►►

EXTRN

external_symbol

►◄

sequence_symbol

PART(

▼

external_symbol

)

Chapter 5. Assembler instruction statements

193

sequence_symbol

Is a sequence symbol.

external_symbol

Is a relocatable symbol that:

v Is a valid symbol

v Is not used as the name entry of a source statement in the source module in

which it is defined

PART(external_symbol)

external_symbol is a relocatable symbol as described above, that also:

v Is a reference to a part as defined on the CATTR instruction.

Up to 65535 individual control sections, external symbols, and external dummy

sections can be defined in a source module. However, the practical maximum

number depends on the amount of table storage available during link-editing.

The assembler lists each external symbol identified in a source module in the

external symbol dictionary, along with entries for entry symbols, common control

sections, parts, and external control sections.

A symbol identified by an EXTRN instruction should not also be declared by an

ENTRY instruction.

External symbols have a length attribute of 1. See also “WXTRN instruction” on

page 232.

ICTL instruction

The ICTL instruction changes the begin, end, and continue columns that establish

the coding format of the assembler language source statements.

►► ICTL begin

►◄

,end

,continue

begin

Specifies the begin column of the source statement. It must be a decimal

self-defining term with value 1 - 40.

end

Specifies the end column of the source statement. When end is specified it must

be a decimal self-defining term with 41 - 80. It must be not less than begin +5,

and must be greater than continue. If end is not specified, it is assumed to be

71.

continue

Specifies the continue column of the source statement. When specified, continue

must be a decimal self-defining term within the range of 2 to 40, and it must

be greater than begin. If continue is not specified, or if column 80 is specified as

the end column, the assembler assumes that continuation lines are not allowed.

Default

1,71,16

194

HLASM V1R6 Language Reference

Use the ICTL instruction only once, at the beginning of a source program. If no

ICTL statement is used in the source program, the assembler assumes that 1, 71,

and 16 are the begin, end, and continue columns.

With the ICTL instruction, you can, for example, increase the number of columns

to be used for the identification or sequence checking of your source statements.

By changing the begin column, you can even create a field before the begin column

to contain identification or sequence numbers. For example, the following

instruction designates the begin column as 9 and the end column as 80. Since the

end column is specified as 80, no continuation records are recognized.

ICTL

9,80

COPY Instruction: The ICTL instruction does not affect the format of statements

brought in by a COPY instruction or generated from a library macro definition.

The assembler processes these statements according to the standard begin, end,

and continue columns described in “Field boundaries” on page 15.

ISEQ instruction

The ISEQ instruction tells the assembler to check that sequence numbers in source

statement lines are in ascending order. In the ISEQ instruction, you specify the

columns between which the assembler is to check for sequence numbers.

►►

ISEQ

►◄

sequence_symbol

left,right

sequence_symbol

Is a sequence symbol.

left

Specifies the first column of the field to be sequence-checked. If specified, left

must be a decimal self-defining term with value 1 - 80.

right

Specifies the rightmost column of the field to be sequence checked. If specified,

right must be a decimal self-defining term with value 1 - 80, and must be

greater than or equal to left.

If left and right are omitted, sequence checking is ended. Sequence checking can be

restarted with another ISEQ statement. An ISEQ statement that is used to end

sequence checking is itself sequence-checked.

The assembler begins sequence checking with the first statement line following the

ISEQ instruction. The assembler also checks continuation lines.

Sequence numbers on adjacent statements or lines are compared according to the 8

bit internal EBCDIC collating sequence. When the sequence number on one line is

not greater than the sequence number on the preceding line, a sequence error is

flagged, and a warning message is issued, but the assembly is not ended.

If the sequence field in the preceding line is spaces, the assembler uses the last

preceding line with a non-space sequence field to make its comparison.

Chapter 5. Assembler instruction statements

195

The assembler checks only those statements that are specified in the coding of a

source module. This includes any COPY instruction statement or macro instruction.

The assembler does not check:

v Statements inserted by a COPY instruction

v Statements generated from model statements inside macro definitions or from

model statements in open code (statement generation is discussed in detail in

Chapter 7, “How to specify macro definitions,” on page 245)

v Statements in library macro definitions

LOCTR instruction

Use the LOCTR instruction to specify and control the use of multiple location

counters within a control section. The assembler assigns consecutive addresses to

the segments of code using one location counter before it assigns addresses to

segments of coding using the next location counter.

►► symbol LOCTR

►◄

symbol

Is one of the following:

v An ordinary symbol

v A variable symbol that has been assigned a character string with a value that

is valid for an ordinary symbol

By using the LOCTR instruction, you can code your control section in a logical

order. For example, you can code work areas and data constants within the section

of code, using them without having to branch around them:

CSECT ,

See note 1

12,15

USING A,12

LOCTR ,

See note 2

LOCTR ,

See note 3

LOCTR ,

See note 4

DUM

DSECT ,

See note 1

LOCTR ,

See note 5

END

LOCTRs are ordered by their definition order. So in the previous example, the

ordering is A, B, and C. When there are statements in LOCTR groups, the code is

generated using currently active USINGs and then moved to the final location.

Notes:

1. The first location counter of a section, class, or part is defined by the name of

the START, CSECT, DSECT, RSECT, CATTR, or COM instruction defining the

section.

2. The LOCTR instruction defines a location counter.

196

HLASM V1R6 Language Reference

3. The LOCTR continues a previously defined location counter. A location counter

remains in use until it is interrupted by a LOCTR, CSECT, DSECT, RSECT, or

COM instruction.

4. A LOCTR instruction with the same name as a control section continues the

first location counter of that section. However, an unnamed LOCTR cannot be

used to continue an unnamed (private code) control section.

5. A LOCTR instruction with the same name as a LOCTR instruction in a

previous control section causes that control section to be continued using the

location counter specified, even though the LOCTR instruction might follow the

definition (or resumption) of a different section.

6. To continue a location counter in an unnamed section, a named location

counter must first be specified for the section by a LOCTR in the unnamed

section.

A control section cannot have the same name as a previous LOCTR instruction. A

LOCTR instruction placed before the first control section definition initiates an

unnamed control section before the LOCTR instruction is processed.

The length attribute of a LOCTR name is 1.

LOCTR instructions do not force alignment; code assembled under a location

counter other than the first location counter of a control section is assembled

starting at the next available byte after the previous segment.

A LOCTR name can be referenced as an ordinary symbol. If the LOCTR name does

not match a section name, its value is the location counter value assigned to its

first appearance, and it might have arbitrary alignment and other attributes. If the

LOCTR name is also a control section name, the value assigned is that of the origin

of the control section. So a LOCTR with the same name as the CSECT resumes the

first location counter within the CSECT. A CSECT instruction resumes the last

location counter used.

Table 35. LOCTR behavior with NOGOFF option

LOCTR

name

Effect

Section

Resumes assembling with the first location counter of that section

Other

v If the LOCTR name was previously declared, resumes assembling with the

location counter of that LOCTR group

v If the LOCTR name was not previously declared, begins processing a new

LOCTR group of statements to be assembled following the most recently

processed section or LOCTR group

Table 36. LOCTR behavior with GOFF option

LOCTR

name

Effect

Section

Resumes assembling with the first location counter of the element in the

B_TEXT class of that section

Class

Not allowed

Part

Resumes assembling with the first location counter of the part

Chapter 5. Assembler instruction statements

197

Table 36. LOCTR behavior with GOFF option (continued)

LOCTR

name

Effect

Other

v If the LOCTR name was previously declared, resumes assembling with the

location counter of that LOCTR group

v If the LOCTR name was not previously declared, begins processing

statements in a new LOCTR group to be assembled following the most

recently processed class, part, or LOCTR group.

LTORG instruction

Use the LTORG instruction so that the assembler can collect and assemble literals

into a literal pool. A literal pool contains the literals you specify in a source

module either after the preceding LTORG instruction, or after the beginning of the

source module.

If a control section has not been established, LTORG initiates an unnamed (private)

control section.

►►

LTORG

►◄

symbol

Is one of the following:

v An ordinary symbol

v A variable symbol that has been assigned a character string with a value that

is valid for an ordinary symbol

v A sequence symbol

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

ordinary symbol, the ordinary symbol is assigned the value of the address of the

first byte of the literal pool. This symbol is aligned on a boundary specified by the

SECTALGN option, and has a length attribute of 1.

If bytes are skipped after the end of a literal pool to achieve alignment for the next

instruction, constant, or area, the bytes are not filled with zeros.

If the literal pool does not reside in a DSECT, and includes any items that require

quadword alignment, and the SECTALGN value defaults to 8, the assembly of the

literal causes the issue of an ASMA500W message.

The assembler ignores the borders between control sections when it collects literals

into pools. Therefore, you must be careful to include the literal pools in the control

sections to which they belong (for details, see “Addressing considerations” on page

199).

The creation of a literal pool gives the following advantages:

v Automatic organization of the literal data into sections that are correctly aligned

and arranged so that minimal space is wasted in the literal pool.

v Assembling of duplicate data into the same area.

198

HLASM V1R6 Language Reference

v Because all literals are cross-referenced, you can find the literal constant in the

pool into which it has been assembled.

Literal pool

A literal pool is created under the following conditions:

v Immediately after an LTORG instruction.

v If no LTORG instruction is specified, and no LOCTRs are used in the first

control section, a literal pool generated after the END statement is created at the

end of the first control section, and appears in the listing after the END

statement.

v If no LTORG instruction is specified, and LOCTRs are used in the first control

section, a literal pool generated after the END statement is created at the end of

the most recent LOCTR segment of the first section, and appears in the listing

after the END statement.

v To force the literal pool to the end of the control section when using LOCTRs,

you must resume the last LOCTR of the CSECT before the LTORG statement (or

before the END statement if no LTORG statement is specified).

Each literal pool has five segments into which the literals are stored (a) in the

order that the literals are specified, and (b) according to their assembled lengths,

which, for each literal, is the total explicit or implied length:

v The first segment contains all literal constants whose assembled lengths are a

multiple of 16.

v The second segment contains those whose assembled lengths are a multiple of 8,

but not of 16.

v The third segment contains those whose assembled lengths are a multiple of 4,

but not a multiple of 8.

v The fourth segment contains those whose assembled lengths are even, but not a

multiple of 4.

v The fifth segment contains all the remaining literal constants whose assembled

lengths are odd.

Since each literal pool is aligned on a SECTALGN alignment, this guarantees that

all literals in the second segment are doubleword aligned; in the third segment,

fullword aligned; and, in the fourth, halfword aligned. The minimum value of

SECALGN is doubleword, so quadword alignment is not guaranteed. No space is

wasted except, possibly, at the origin of the pool, and in aligning to the start of the

statement following the literal pool.

Literals from the following statements are in the pool, in the segments indicated by

the parenthesized numbers:

FIRST

START

MVC

TO,=3F’9’

(3)

2,=D’7’

(2)

2,=XL1’8’

(5)

MVC

MTH,=CL3’JAN’

(5)

4,5,=2F’1,2’

(2)

5,=H’33’

(4)

2,=A(ADDR)

(3)

MVC

FIVES,=XL16’05’ (1)

Addressing considerations

If you specify literals in source modules with multiple control sections, then:

Chapter 5. Assembler instruction statements

199

v Write an LTORG instruction at the end of each control section, so that all the

literals specified in the section are assembled into the one literal pool for that

section. If a control section is divided and interspersed among other control

sections, write an LTORG instruction at the end of each segment of the

interspersed control section.

v When establishing the addressability of each control section, make sure that:

- All the literal pool for that section is also addressable, by including it within a

USING range.

- The literal specifications are within the corresponding USING domain.

The USING range and domain are described in “USING instruction” on page

222.

All the literals specified after the last LTORG instruction, or, if no LTORG

instruction is specified, all the literals in a source module are assembled into a

literal pool at the end of the first control section. You must then make this literal

pool addressable, along with the addresses in the first control section. This literal

pool is printed in the program listing after the END instruction.

Duplicate literals

If you specify duplicate literals within the part of the source module that is

controlled by an LTORG instruction, only one literal constant is assembled into the

pertinent literal pool. This also applies to literals assembled into the literal pool at

the end of the first or only control section of a source module that contains no

LTORG instructions.

Literals are duplicates only if their specifications are identical, not if the object code

assembled happens to be identical.

When two literals specifying identical A-type, Y-type or S-type address constants

contain a reference to the value of the location counter (*), both literals are

assembled into the literal pool. This is because the value of the location counter

might be different in the two literals. Even if the location counter value is the same

for both, they are still both assembled into the literal pool.

The following examples show how the assembler stores pairs of literals, if the

placement of each pair is controlled by the same LTORG statement.

=X’F0’

Both are

=C’0’

stored

=XL3’0’

Both are

=HL3’0’

stored

=A(*+4)

Both are

=A(*+4)

stored

=X’FFFF’

Identical,

=X’FFFF’

only one copy is stored

MNOTE instruction

The MNOTE instruction generates your own error messages or displays

intermediate values of variable symbols computed during conditional assembly.

200

HLASM V1R6 Language Reference

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