High Level Assembler for z/OS & z/VM & z/VSE. Language Reference (Version 1 Release 6) - page 13
LPSAMP01 Sample Program - LRSAMP01 - HLASM
Page
3
Active Usings: None
Loc
Object Code
Addr1
Addr2
Stmt Source Statement
HLASM R6.0
2015/02/23 09.31
2 ***********************************************************************
3 *
4 * Licensed Materials - Property of IBM
5 *
6 *
5696-234
7 *
8 * Copyright IBM Corporation 2008, 2015 All Rights Reserved.
9 *
10 * US Government Users Restricted Rights - Use, duplication
11 * or disclosure restricted by GSA ADP Schedule Contract
12 * with IBM Corp.
13 *
14 ***********************************************************************
LPSAMP01 The Program code title
Page
4
Active Usings: None
Loc
Object Code
Addr1
Addr2
Stmt Source Statement
HLASM R6.0
2015/02/23 09.31
00000000
00000000 00000004
16 LPSAMP01 CSECT
0000000C
17 R12
EQU 12
0000000E
18 R14
EQU 14
0000000F
19 R15
EQU 15
R:C 00000000
20
USING LPSAMP01,R12 Assign the base register
LPSAMP01 The Next Heading
Page
5
Active Usings: LPSAMP01,R12
Loc
Object Code
Addr1
Addr2
Stmt Source Statement
HLASM R6.0
2015/02/23 09.31
00000000 18CF
22
LR R12,R15 Load the base address
23 &VARSYM SETC ’Value from Variable Symbol’
24
TITLE ’The &VARSYM’
LPSAMP01 The Value from Variable Symbol
Page
6
Active Usings: LPSAMP01,R12
Loc
Object Code
Addr1
Addr2
Stmt Source Statement
HLASM R6.0
2015/02/23 09.31
00000002 07FE
25
BR R14 Return
26
END
Figure 29. Sample program using TITLE instruction
Page ejects
Each TITLE statement causes the listing to be advanced to a new page before the
heading is printed unless it is preceded immediately by one of the following:
v A CEJECT instruction
v An EJECT instruction
v A SPACE instruction that positions the current print line at the start of a new
page
v A TITLE instruction
If the TITLE statement appears in a macro or contains a variable symbol and
PRINT NOGEN is specified, the listing is not advanced to a new page.
Valid characters
Any printable character specified appears in the heading, including spaces.
Double-byte data can be used when the DBCS assembler option is specified. The
double-byte data must be valid. Variable symbols are allowed. However, the
following rules apply to ampersands and apostrophes:
v The DBCS ampersand and apostrophe are not recognized as delimiters.
v A double-byte character that contains the value of an EBCDIC ampersand or
apostrophe in either byte is not recognized as a delimiter when enclosed by SO
and SI.
v A single ampersand initiates an attempt to identify a variable symbol and to
substitute its current value.
Chapter 5. Assembler instruction statements
221
v A pair of ampersands is printed as one ampersand.
v A pair of apostrophes is printed as one apostrophe.
v An unpaired apostrophe followed by one or more spaces ends the string of
characters printed. If a non-space character follows an unpaired apostrophe, the
assembler issues an error message and prints no heading.
Only the characters printed in the heading count toward the maximum of 100
characters allowed. If the count of characters to be printed exceeds 100, the
heading that is printed is truncated and error diagnostic message
ASMA062E Illegal operand format
is issued.
USING instruction
The USING instruction specifies a base address and range and assigns one or more
base registers. If you also load the base register with the base address, you have
established addressability in a control section. If a control section has not been
established, USING initiates an unnamed (private) control section.
To use the USING instruction correctly, you should know:
v Which locations in a control section are made addressable by the USING
instruction
v Where in a source module you can use implicit addresses in instruction
operands to refer to these addressable locations
Base address
The term base address is used throughout this manual to mean the location counter
value within a control section from which the assembler can compute
displacements to locations, or addresses, within the control section. Do not confuse
this with the storage address of a control section when it is loaded into storage at
execution time.
The USING instruction has three formats:
v The first format specifies a base address, an optional range, and one or more
base registers. This format of the USING instruction is called an ordinary USING
instruction, and is described under “Ordinary USING instruction” on page 224.
v The second format specifies a base address, an optional range, one or more base
registers, and a USING label which can be used as a symbol qualifier. This
format of the USING instruction is called a labeled USING instruction, and is
described under “Labeled USING instruction” on page 227.
v The third format specifies a base address, an optional range, and a relocatable
expression instead of one or more base registers. This format of a USING
instruction is called a dependent USING instruction, and is described under
“Dependent USING instruction” on page 230. If a USING label is also specified,
this format of the USING instruction is called a labeled dependent USING
instruction.
Note: The assembler identifies and warns about statements where the implied
alignment of an operand does not match the requirements of the instruction.
However, if the base for a USING is not aligned on the required boundary, the
assembler cannot diagnose a problem. For example:
222
HLASM V1R6 Language Reference
DS1
DSECT
DS
H
REGPAIR DS
2ADL8
Halfword alignment
DS2
DSECT
REGPAIR_ALIGN DS 2ADL8
Doubleword alignment
CSECT
USING DS1,R1
Ordinary USING
USING DS2,REGPAIR
Dependent USING
STPQ R0,REGPAIR
REGPAIR is not a quadword
STPQ R0,REGPAIR_ALIGN
But REGPAIR_ALIGN is
The first STPQ instruction is diagnosed as an alignment error. The second STPQ
instruction is not, even though the same storage location is implied by the code.
You must take care to ensure base addresses match the alignment requirements of
storage mapped by a USING. For a description of the alignment requirements of
instructions, see the relevant z/Architecture Principles of Operation.
How to use the USING instruction
Specify the USING instruction so that:
v All the required implicit addresses in each control section lie within a USING
range.
v All the references for these addresses lie within the corresponding USING
domain.
You could, therefore, place all ordinary USING instructions at the beginning of the
control section and specify a base address in each USING instruction that lies at
the beginning of each control section.
For Executable Control Sections: To establish the addressability of an executable
control section defined by a START or CSECT instruction, specify a base address
and assign a base register in the USING instruction. At execution time, the base
register must be loaded with the correct base address.
If a control section requires addressability to more than 4096 bytes, you must
assign more than one base register, or make implicit references using only
instructions supporting 20 bit displacements (“long displacements”). This
establishes the addressability of the entire control section with one USING
instruction.
For Reference Control Sections: A dummy section is a reference control section
defined by the DSECT instructions. To establish the addressability of a dummy
section, specify the address of the first byte of the dummy section as the base
address, so that all its addresses lie within the pertinent USING range. The address
you load into the base register must be the address of the storage area being
described by the dummy section. However, if all references to fields within the
DSECT are made with instructions supporting long displacements, the base
address need not be the first byte of the dummy section.
When you refer to symbolic addresses in the dummy section, the assembler
computes displacements accordingly. However, at execution time, the assembled
addresses refer to the location of real data in the storage area.
Chapter 5. Assembler instruction statements
223
Base registers for absolute addresses
Absolute addresses used in a source module must also be made addressable.
Absolute addresses require a base register other than the base register assigned to
relocatable addresses (as described above).
However, the assembler does not need a USING instruction to convert absolute
implicit addresses in the range 0 through 4095 to their explicit form. The assembler
uses register 0 as a base register. Displacements are computed from the base
address 0, because the assembler assumes that a base or index of 0 implies that a
zero quantity is to be used in forming the address, regardless of the contents of
register 0. The USING domain for this automatic base register assignment is the
entire source module.
If a register is specified with base address zero, the assembler uses it in preference
to the default use of register zero. For example:
|
USING 0,3
LA
7,5
generates the instruction X'41703005'; in the absence of the USING statement, the
generated instruction is X'41700005'.
For absolute implicit addresses greater than 4095 and in the absence of
long-displacement instructions, a USING instruction must be specified according to
the following:
v With a base address representing an absolute expression
v With a base register that has not been assigned by a USING instruction in which
a relocatable base address is specified
This base register must be loaded with the base address specified.
Ordinary USING instruction
The ordinary USING instruction format specifies a base address and one or more
base registers.
Ordinary USING
▼
►►
USING
base
,base_register
►◄
sequence_symbol
(base
)
,end
sequence_symbol
Is a sequence symbol.
base
Specifies a base address, which can be a relocatable or an absolute expression.
The value of the expression is 0 - 231-1.
end
Specifies the end address, which can be a relocatable or an absolute expression.
The value of the expression is 0 - 231-1. The end address can exceed the (base
224
HLASM V1R6 Language Reference
address + default range) without error. The end address must be greater than
the base and must have the same relocatability attribute.
The resolvable range of a USING with an 'end' operand is
base,MIN(4095,end-1)
Thus USING base,reg is equivalent to USING (base,base+4096),reg.
base_register
Is an absolute expression whose value represents general registers 0 through
15.
The default range is 4096 per base register.
The assembler assumes that the base register denoted by the first base_register
operand contains the base address base at execution time. If present, the subsequent
base_register operands represent registers that the assembler assumes contain the
address values base+4096, base+8192, and so on.
For example:
USING
BASE,9,10,11
has the logical equivalent of:
USING
BASE,9
USING
BASE+4096,10
USING
BASE+8192,11
In another example, the following statement:
USING
*,12,13
tells the assembler to assume that the current value of the location counter is in
general register 12 at execution time, and that the current value of the location
counter, incremented by 4096, is in general register 13 at execution time.
Computing displacement
If you change the value in a base register being used, and want the assembler to
compute displacements from this value, you must tell the assembler the new value
with another USING statement. In the following sequence, the assembler first
assumes that the value of ALPHA is in register 9. The second statement then causes
the assembler to assume that ALPHA+1000 is the value in register 9.
USING
ALPHA,9
USING
ALPHA+1000,9
Using General Register Zero
You can refer to the first 4096 bytes of storage using general register 0, subject to
the following conditions:
v The value of operand base must be either absolute or relocatable zero.
v Register 0 must be specified as the first base_register operand.
The assembler assumes that register 0 contains zero. Therefore, regardless of the
value of operand base, it calculates displacements as if operand base were absolute
or relocatable zero. The assembler also assumes that subsequent registers specified
in the same USING statement contain 4096, 8192, and so on.
Chapter 5. Assembler instruction statements
225
If register 0 is used as a base register, the referenced control section (or dummy
section) is not relocatable, despite the fact that operand base might be relocatable.
The control section can be made relocatable by:
v Replacing register 0 in the USING statement
v Loading the new register with a relocatable value
v Reassembling the program
Range of an ordinary USING instruction
The range of an ordinary USING instruction (called the “ordinary USING range”,
or the “USING range”) is the 4096 bytes beginning at the base address specified in
the USING instruction, or the range as specified by the range end, whichever is the
lesser. For long-displacement instructions, the range is the addresses between
(base_address-524288) and (base_address+524287). Addresses that lie within the
USING range can be converted from their implicit to their explicit
base-displacement form using the designated base registers; those outside the
USING range cannot be converted.
The USING range does not depend upon the position of the USING instruction in
the source module; rather, it depends upon the location of the base address
specified in the USING instruction.
The USING range is the range of addresses in a control section that is associated
with the base register specified in the USING instruction. If the USING instruction
assigns more than one base register, the composite USING range is the union of
the USING ranges that applies if the base registers were specified in separate
USING instructions.
USING ranges need not be contiguous. For example, you can specify
USING X,4
USING X+6000,5
and implicit addresses with values X+4096 - X+5999 are not addressable by
instructions with unsigned 12 bit displacements.
Two USING ranges coincide when the same base address is specified in two
different USING instructions, even though the base registers used are different.
When two USING ranges coincide, the assembler uses the higher-numbered
register for assembling the addresses within the common USING range. In effect,
the domain of the USING instruction that specifies the lower-numbered register is
ended by the other USING instruction. If the domain of the USING instruction that
specifies the higher-number register is terminated, the domain of the other USING
instruction is resumed.
Two USING ranges overlap when the base address of one USING instruction lies
within the range of another USING instruction. You can use the WARN suboption
of the USING assembler option to find out if you have any overlapping USING
ranges. When an overlap occurs the assembler issues a diagnostic message.
However, the assembler does allow an overlap of one byte in USING ranges so
that you do not receive a diagnostic message if you code the following statements:
PSTART CSECT
LR
R12,R15
LA
R11,4095(,R12)
USING
PSTART,R12
USING
PSTART+4095,R11
226
HLASM V1R6 Language Reference
In the above example, the second USING instruction begins the base address of the
second base register (R11) in the 4096th byte of the first base register (R12) USING
range. If you do not want the USING ranges to overlap, you can code the
following statements:
PSTART CSECT
LR
R12,R15
LA
R11,4095(,R12)
LA
R11,1(,R11)
USING
PSTART,R12
USING
PSTART+4096,R11
When two ranges overlap, the assembler computes displacements from the base
address that gives the smallest non-negative displacement; or if no non-negative
displacement can be found, for long-displacement instructions, the base register
giving the smallest negative displacement; it uses the corresponding base register
when it assembles the addresses within the range overlap. This applies only to
implicit addresses that appear after the second USING instruction.
LOCTR does not affect the USING domain.
Domain of an ordinary USING instruction
The domain of an ordinary USING instruction (called the “ordinary USING
domain”, or the “USING domain”) begins where the USING instruction appears in
a source module. It continues until the end of a source module, except when:
v A subsequent DROP instruction specifies the same base register or registers
assigned by a preceding USING instruction.
v A subsequent USING instruction specifies the same register or registers assigned
by a preceding USING instruction.
The assembler converts implicit address references into their explicit form when
the following conditions are met:
v The address reference appears in the domain of a USING instruction.
v The addresses referred to lie within the range of some USING instruction.
The assembler does not convert implicit address references that are outside the
USING domain. The USING domain depends on the position of the USING
instruction in the source module after conditional assembly, if any, has been done.
Labeled USING instruction
The labeled USING instruction specifies a base address, one or more base registers,
and a USING label which can be used as a symbol qualifier.
Labeled USING
▼
►► label USING
base
,base_register
►◄
(base
)
,end
label
Is one of the following:
v An ordinary symbol
Chapter 5. Assembler instruction statements
227
v A variable symbol that has been assigned a character string with a value that
is valid for an ordinary symbol
base
Specifies a base address, which can be a relocatable or an absolute expression.
The value of the expression must lie between 0 and 231-1.
end
Specifies the end address, which can be a relocatable or an absolute expression.
The value of the expression must lie between 0 and 231-1. The end address can
exceed the (base address + default range) without error. The end address must
be greater than the base and must have the same relocatability attributes.
base_register
Is an absolute expression whose value represents general registers 0 through
15.
The default range is 4096 per base register.
The essential difference between a labeled USING instruction and an ordinary
USING instruction is the label placed on the USING statement. To indicate to the
assembler that the USING established with the label is to provide resolution of
base and displacement for a symbol, the label must be used to qualify the symbol.
Qualifying a symbol consists of preceding the symbol with the label on the USING
followed by a period. The only symbols resolved by the labeled USING are those
symbols qualified with the label. This label cannot be used for any other purpose
in the program, except possibly as a label on other USING instructions.
The following examples show how labeled USINGs are used:
PRIOR
USING IHADCB,R10
NEXT
USING IHADCB,R2
MVC
PRIOR.DCBLRECL,NEXT.DCBLRECL
The same code without labeled USINGs can be written like this:
USING IHADCB,R10
MVC
DCBLRECL,DCBLRECL-IHADCB(R2)
In the following example, a new element, NEW, is inserted into a doubly linked list
between two existing elements LEFT and RIGHT, where the links are stored as
pointers LPTR and RPTR:
LEFT
USING ELEMENT,R3
RIGHT
USING ELEMENT,R6
NEW
USING ELEMENT,R1
MVC
NEW.RPTR,LEFT.RPTR
Move previous Right pointer
MVC
NEW.LPTR,RIGHT.LPTR
Move previous Left pointer
ST
R1,LEFT.RPTR
Chain new element from Left
ST
R1,RIGHT.LPTR
Chain new element from Right
ELEMENT DSECT
LPTR
DS
A
Link to left element
RPTR
DS
A
Link to right element
Range of a labeled USING instruction
The range of a labeled USING instruction (called the labeled USING range) is the
4096 bytes beginning at the base address specified in the labeled USING
228
HLASM V1R6 Language Reference
instruction, or the range as specified by the range end, whichever is the lesser.
Addresses that lie within the labeled USING range can be converted from their
implicit form (qualified symbols) to their explicit form; those outside the USING
range cannot be converted.
Like the ordinary USING range, the labeled USING range is the range of addresses
in a control section that is associated with the base register specified in the labeled
USING instruction. If the labeled USING instruction assigns more than one base
register, the composite labeled USING range is the product of the number of
registers specified in the labeled USING instruction and 4096 bytes. The composite
labeled USING range begins at the base address specified in the labeled USING
instruction. Unlike the ordinary USING range, however, you cannot specify
separate labeled USING instructions to establish the same labeled USING range.
For example,
IN
USING BASE,10,11
specifies a range of 8192 bytes beginning at BASE, but
IN
USING BASE,10
IN
USING BASE+4096,11
specifies a single labeled USING range of 4096 bytes beginning at BASE+4096.
You can specify the same base address in any number of labeled USING
instructions. You can also specify the same base address in an ordinary USING and
a labeled USING. However, unlike ordinary USING instructions that have the
same base address, if you specify the same base address in an ordinary USING
instruction and a labeled USING instruction, High Level Assembler does not treat
the USING ranges as coinciding. When you specify an unqualified symbol in an
assembler instruction, the base register specified in the ordinary USING is used by
the assembler to resolve the address into base-displacement form. Here is an
example of coexistent ordinary USINGs and labeled USINGs:
USING IHADCB,R10
SAMPLE USING IHADCB,R2
MVC
DCBLRECL,SAMPLE.DCBLRECL
In this MVC instruction, the (unqualified) first operand is resolved with the
ordinary USING, and the (qualified) second operand is resolved with the labeled
USING.
Domain of a labeled USING instruction
The domain of a labeled USING instruction (called the labeled USING domain)
begins where the USING instruction appears in a source module. It continues to
the end of the source module, except when:
v A subsequent DROP instruction specifies the label used in the preceding labeled
USING instruction.
v A subsequent USING instruction specifies the same label used in the preceding
labeled USING instruction. The second specification of the label causes the
assembler to end the domain of the prior USING with the same label.
You can specify the same base register or registers in any number of labeled
USING instructions. However, unlike ordinary USING instructions, as long as all
the labeled USINGs have unique labels, the assembler considers the domains of all
the labeled USINGs to be active and their labels eligible to be used as symbol
qualifiers. With ordinary USINGs, when you specify the same base register in a
subsequent USING instruction, the domain of the prior USING is ended.
Chapter 5. Assembler instruction statements
229
The assembler converts implicit address references into their explicit form using
the base register or registers specified in a labeled USING instruction when the
following conditions are met:
v The address reference appears in the domain of the labeled USING instruction.
v The address reference takes the form of a qualified symbol and the qualifier is
the label of the labeled USING instruction.
v The address lies within the range of the labeled USING instruction.
Dependent USING instruction
The dependent USING instruction format specifies a base address and a relocatable
expression instead of one or more base registers. If a USING label is also specified,
this format USING instruction is called a labeled dependent USING instruction.
Dependent USING
►►
USING base
,address
►◄
label
(base
)
sequence_symbol
,end
label
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
sequence_symbol
Is a sequence symbol.
base
Specifies a base address, which must be a relocatable expression. The value of
the expression must lie between 0 and 231-1.
address
Is a simply relocatable expression that represents an implicit address within the
range of an active USING instruction. The range of an active USING is
considered to be that which is valid for generating 12 bit or 20 bit
displacements.
end
Specifies the end address, which can be a relocatable or an absolute expression.
The value of the expression must lie between 0 and 231-1. The end address can
exceed the (base address + default range) without error. The end address must
be greater than the base and must have the same relocatability attributes.
The implicit address denoted by address specifies the address where base is to be
based, and is known as the supporting base address. As address is a relocatable
expression, it distinguishes a dependent USING from an ordinary USING. The
assembler converts the implicit address denoted by address into its explicit
base-displacement form. It then assigns the base register from this explicit address
as the base register for base. The assembler assumes that the base register contains
the base address base minus the displacement determined in the explicit address.
230
HLASM V1R6 Language Reference
The assembler also assumes that address is appropriately aligned for the code based
on base. Warnings are not issued for potential alignment problems in the
dependent USING address.
A dependent USING depends on the presence of one or more corresponding
labeled or ordinary USINGs being in effect to resolve the symbolic expressions in
the range of the dependent USING.
The following example shows the use of an unlabeled dependent USING:
EXAMPLE CSECT
USING EXAMPLE,R10,R11
Ordinary USING
USING IHADCB,DCBUT2
Unlabeled dependent USING
LH
R0,DCBBLKSI
Uses R10 or R11 for BASE
DCBUT2
DCB
DDNAME=SYSUT2,...
The following example shows the use of two labeled dependent USINGs:
EXAMPLE CSECT
USING EXAMPLE,R10,R11
Ordinary USING
DCB1
USING IHADCB,DCBUT1
Labeled dependent USING
DCB2
USING IHADCB,DCBUT2
Labeled dependent USING
MVC
DCB2.DCBBLKSI,DCB1.DCBBLKSI
Uses R10 or R11 for BASE
DCBUT1
DCB
DDNAME=SYSUT1,...
DCBUT2
DCB
DDNAME=SYSUT2,...
Range of a dependent USING instruction
The range of a dependent USING instruction (called the dependent USING range)
is either the range as specified by the range end, or the range of the corresponding
USING minus the offset of address within that range, whichever is the lesser. If the
corresponding labeled or ordinary USING assigns more than one base register, the
maximum dependent USING range is the composite USING range of the labeled
or ordinary USING.
If the dependent USING instruction specifies a supporting base address that is
within the range of more than one ordinary USING, the assembler determines
which base register to use during base-displacement resolution as follows:
v The assembler computes displacements from the ordinary USING base address
that gives the smallest displacement, and uses the corresponding base register.
v If more than one ordinary USING gives the smallest displacement, the assembler
uses the higher-numbered register for assembling addresses within the
coinciding USING ranges.
Domain of a dependent USING instruction
The domain of a dependent USING instruction (called the dependent USING
domain) begins where the dependent USING appears in the source module and
continues until the end of the source module, except when:
v You end the domain of the corresponding ordinary USING by specifying the
base register or registers from the ordinary USING instruction in a subsequent
DROP instruction.
Chapter 5. Assembler instruction statements
231
v You end the domain of the corresponding ordinary USING by specifying the
same base register or registers from the ordinary USING instruction in a
subsequent ordinary USING instruction.
v You end the domain of a labeled dependent USING by specifying the label of
the labeled dependent USING in the operand of a subsequent DROP instruction.
v You end the domain of a labeled dependent USING by specifying the label of
the labeled dependent USING in the operand of a subsequent labeled USING
instruction.
When a labeled dependent USING domain is dropped, none of any subordinate
USING domains are dropped. In the following example the labeled dependent
USING BLBL1 is not dropped, even though it appears to be dependent on the
USING ALBL2 that is being dropped:
ALBL1
USING
DSECTA,14
USING
DSECTB,ALBL1.A
ALBL2
USING
DSECTA,ALBL1.A
BLBL1
USING
DSECTA,ALBL2.A
DROP
ALBL2
DSECTA DSECT
A
DS
A
DSECTB
DSECT
B
DS
A
A dependent USING is not dependent on another dependent USING. It is
dependent on the ordinary or labeled USING that is finally used to resolve the
address. For example, the USING at BLBL1 is dependent on the ALBL1 USING.
Remember that all dependent USINGs must eventually be based on an ordinary or
labeled USING that provides the base register used for base-displacement
resolutions.
WXTRN instruction
The WXTRN statement identifies “weak external” symbols referred to in a source
module but defined in another source module. The WXTRN instruction differs
from the EXTRN instruction (see “EXTRN instruction” on page 193) as follows:
v The EXTRN instruction causes the linker to automatically search libraries (if
automatic library call is in effect) to find the module that contains the external
symbols that you identify in its operand field. If the module is found, linkage
addresses are resolved; the module is then linked to your module, which
contains the EXTRN instruction.
v The WXTRN instruction suppresses automatic search of libraries. The linker only
resolves the linkage addresses if the external symbols that you identify in the
WXTRN operand field are defined in one of these ways:
- In a module that is linked and loaded along with the object module
assembled from your source module.
- In a module brought in from a library because of the presence of an EXTRN
instruction in another module linked and loaded with yours.
232
HLASM V1R6 Language Reference
,
▼
►►
WXTRN
external_symbol
►◄
sequence_symbol
,
▼
PART(
external_symbol
)
sequence_symbol
Is a sequence symbol.
external_symbol
Is a relocatable symbol that is not:
v 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.
The external symbols identified by a WXTRN instruction have the same properties
as the external symbols identified by the EXTRN instruction. However, the type
code assigned to these external symbols differs.
V-Type Address Constant: If a symbol, specified in a V-type address constant, is
also identified by a WXTRN instruction, it is assigned the same ESD type code as
the symbol in the WXTRN instruction, and is treated by the linkage editor as a
weak external symbol.
If an external symbol is identified by both an EXTRN and WXTRN instruction in
the same source module, the first declaration takes precedence, and subsequent
declarations are flagged with diagnostic messages.
XATTR instruction (z/OS and CMS)
The XATTR instruction enables attributes to be assigned to an external symbol.
This instruction is only valid when you specify the GOFF assembler option.
,
▼
►► symbol XATTR
attribute
►◄
symbol
Is a symbol which has been declared implicitly or explicitly as an external
symbol. Further, if the PSECT attribute is specified, must be an RSECT, CSECT,
or START name or an ENTRY name (where the entry is in one of the preceding
types of section)
attribute
Is one or more attributes from the group of attributes described below. The
assembler sets the appropriate attribute flags in the GOFF External Symbol
Directory record.
Chapter 5. Assembler instruction statements
233
Notes:
1. If more than one value is specified for a given attribute, no diagnostic is issued
and only the last value is used.
2. All attributes of an external symbol must be specified in a single XATTR
statement (which can be continued).
ATTRIBUTES
►► ATTRIBUTES(label)
►◄
ATTRIBUTES(label), abbreviation ATTR(label)
Is a symbol (internal or external) known in the declaring program. It names the
location of the extended attribute information to be associated with symbol.
Instructs the assembler to place the ESDID and offset of the label in the GOFF
External Symbol Dictionary record.
LINKAGE
►► LINKAGE( OS
)
►◄
XPLINK
LINKAGE(OS), abbreviation LINK(OS)
Instructs the assembler to set the “Linkage Type” attribute to standard OS
linkage.
LINKAGE(XPLINK), abbreviation LINK(XPLINK)
Instructs the assembler to set the “Linkage Type” attribute to indicate “Extra
Performance Linkage”.
PSECT
►► PSECT(name)
►◄
PSECT (name)
Identifies the private read-write “section” or PSECT associated with name by its
being an internal or external symbol belonging to an element in the class to
which the PSECT belongs. The name is one of:
v An ENTRY name, where the entry is in the same section (CSECT or RSECT)
as name, but in a different class. For reentrant code, the PSECT is normally a
non-shared class, so a separate CATTR statement is needed to declare that
class and its attributes.
v An internal label within the PSECT.
234
HLASM V1R6 Language Reference
REFERENCE
,
(1)
▼
►►
REFERENCE(
DIRECT
)
►◄
INDIRECT
(1)
DATA
CODE
Notes:
1
Select no more than one option from each group.
REFERENCE(DIRECT), abbreviation REF(DIRECT)
Instructs the assembler to reset (clear) the “Indirect Reference” attribute.
REFERENCE(INDIRECT), abbreviation REF(INDIRECT)
Instructs the assembler to assign the “Indirect Reference” attribute.
REFERENCE(CODE), abbreviation REF(CODE)
Instructs the assembler to set the Executable attribute.
REFERENCE(DATA), abbreviation REF(DATA)
Instructs the assembler to set the Not Executable attribute.
SCOPE
►► SCOPE( SECTION
)
►◄
MODULE
LIBRARY
IMPORT
EXPORT
SCOPE(SECTION), abbreviation SCOPE(S)
Instructs the assembler to set the binding scope to “Section”.
SCOPE(MODULE), abbreviation SCOPE(M)
Instructs the assembler to set the binding scope to “Module”.
SCOPE(LIBRARY), abbreviation SCOPE(L)
Instructs the assembler to set the binding scope to “Library”.
SCOPE(IMPORT), abbreviation SCOPE(X)
Instructs the assembler to set the binding scope to “Export-Import” (see note
following this list).
SCOPE(EXPORT), abbreviation SCOPE(X)
Instructs the assembler to set the binding scope to “Export-Import”.
This statement indicates only that the name field symbol has the specified scope. A
symbol having SCOPE(X) has IMPORT status only if declared in an EXTRN
Chapter 5. Assembler instruction statements
235
statement, and has EXPORT status only if declared explicitly in an ENTRY
statement, or declared implicitly as an entry on a CSECT or RSECT statement.
The SCOPE(IMPORT) or SCOPE(EXPORT) attribute is required for using Dynamic
Link Libraries under the Language Environment®. For details, refer to z/OS
Language Environment Programming Guide (SA22-7561).
Association of code and data areas (z/OS and CMS)
To provide support for application program reentrancy and dynamic binding, the
assembler provides a way to associate read-only code and read-write data areas.
This is done by defining and accessing “associated data areas” called PSECTs. A
PSECT (Private or Prototype Control Section) when instantiated becomes the
non-shared working storage for an invocation of a shared reentrant program.
In the Program Object model, a PSECT is an element within the same section as
the element containing the shared code to which it belongs. The two classes
defining these elements have attributes appropriate to their respective uses.
Typically, V-type and R-type address constants are used to provide code and
data-area addressability for a reentrant program using PSECTs.
Figure 30 shows an example of two sections A and B, each with a PSECT. When
the program object AB containing A and B is instantiated, a single copy of the
reentrant CODE class is loaded into read-only storage, and a copy of the PSECT
class belonging to AB is loaded into read-write storage. The invoker of A provides
the address for the PSECT of A, so that A can address its own read-write data. A
later instantiation of AB loads only a new copy of the PSECT class.
CODE Class
PSECT Class
┌────────────┐
┌─────────────┐
│A ─ ─ ─
│
│ (A’s PSECT) │
Section A
│
│
│
│
│
│
┌──┼─ DC R(B)
│
┌──┼─ DC V(B)
│
│
│
│
│
│
│
│
│
│
│
│
│
│
├─────────────┤
│
├────────────┤
!─►│ (B’s PSECT) │
!─►│B ─ ─ ─
│
│
│
Section B
│
│
│
│
│
│
│
│
!────────────┘
!─────────────┘
◄────── Program Object AB ───────►
Figure 30. Program object with PSECTs, example 1
When a program in the CODE class of section A calls a program in the CODE class
of section B, a linkage convention might require loading the entry address of B into
general register 15 and the address of B's PSECT into general register 0. For
example:
L
15,=V(B)
B’s entry point address
L
0,=R(B)
B’s PSECT address (from A’s PSECT)
BASR
14,15
Linkage to B
236
HLASM V1R6 Language Reference
Further information about linkage conventions for referencing Dynamic Link
Libraries (DLLs) under the Language Environment can be found in z/OS Language
Environment Programming Guide (SA22-7561).
Chapter 5. Assembler instruction statements
237
238
HLASM V1R6 Language Reference
Chapter 6. Introduction to macro language
This chapter introduces the basic macro concept: what you can use the macro
facility for, how you can prepare your own macro definitions, and how you call
these macro definitions for processing by the assembler.
Macro language is an extension of assembler language. It provides a convenient
way to generate a sequence of assembler language statements many times in one
or more programs. A macro definition is written only once; thereafter, a single
statement, a macro instruction statement, is written each time you want to generate
the sequence of statements. This simplifies the coding of programs, reduces the
chance of programming errors, and ensures that standard sequences of statements
are used to accomplish the functions you want.
In addition, conditional assembly lets you code statements that are assembled or
not, depending upon conditions evaluated at conditional assembly time. These
conditions are generally tests of values which can be defined, set, changed, and
tested during assembly. Conditional assembly statements can be used within macro
definitions or in open code.
Using macros
The main use of macros is to insert assembler language statements into a source
program.
You call a named sequence of statements (the macro definition) by using a macro
instruction, or macro call. The assembler replaces the macro call by the statements
from the macro definition and inserts them into the source module at the point of
call. The process of inserting the text of the macro definition is called macro
generation or macro expansion. Macro generation occurs during conditional
assembly.
The expanded stream of code then becomes the input for processing at assembly
time; that is, the time at which the assembler translates the machine instructions
into object code.
Macro definition
A macro definition is a named sequence of statements you can call with a macro
instruction. When it is called, the assembler processes and normally generates
assembler language statements from the definition into the source module. The
statements generated can be:
v Copied directly from the definition
v Modified by parameter values and other values in variable symbols before
generation
v Manipulated by internal macro processing to change the sequence in which they
are generated
You can define your own macro definitions in which any combination of these
three processes can occur. Some macro definitions, like some of those used for
system generation, do not generate assembler language statements, but do only
internal processing.
239
A macro definition provides the assembler with:
v The name of the macro
v The parameters used in the macro
v The sequence of statements the assembler generates when the macro instruction
appears in the source program.
Every macro definition consists of a macro definition header statement (MACRO),
a macro instruction prototype statement, one or more assembler language
statements, and a macro definition trailer statement (MEND), as shown in
Figure 31.
┌──────────────────────────────► MACRO
│
┌────────────────────────────────────────────┐
│ Prototype
│ &LABEL MACID
&PARAM1,&PARAM2
│
│
│
└─┬─┘
└──────┬──────┘
│
│
│
▌2▐
▌3▐
│
│
┌ ├────────────────────────────────────────────┤
│
│ │
│
▌1▐
│ │
│
│
│ │
│
│
▌5▐─┤ │
Body of macro
│
│
│ │
│
│
│ │
│
│
│ │
│
│
└ └────────────────────────────────────────────┘
└──────────────────────────────► MEND
▌4▐
┌───────┴───────┐
Macro instruction
MACID
OPERAND1,OPERAND2
Figure 31. Parts of a macro definition
v The macro definition header and trailer statements (MACRO and MEND)
indicate to the assembler the beginning and end of a macro definition (see ▌1▐ in
Figure 31).
v The macro instruction prototype statement names the macro (see ▌2▐ in
Figure 31), and declares its parameters (see ▌3▐ in Figure 31). In the operand
field of the macro instruction, you can assign values (see▌4▐ in Figure 31) to the
parameters declared for the called macro definition.
v The body of a macro definition (see ▌5▐ in Figure 31) contains the statements
that are generated when you call the macro. These statements are called model
statements; they are normally interspersed with conditional assembly statements
or other processing statements.
Model statements
You can write machine instruction statements and assembler instruction statements
as model statements. During macro generation, the assembler copies them exactly
as they are written. You can also use variable symbols as points of substitution in a
model statement. The assembler enters values in place of these points of
substitution each time the macro is called.
The three types of variable symbols in the assembler language are:
v Symbolic parameters, declared in the prototype statement
v System variable symbols
v SET symbols, which are part of the conditional assembly language
240
HLASM V1R6 Language Reference