Terms

A term is the smallest element of the assembler language that represents a distinct and separate value. It can, therefore, be used alone or in combination with other terms to form expressions. Terms are classified as absolute or relocatable, depending on the effect of program relocation upon them. Program relocation is the loading of the object program into storage locations other than those originally assigned by the assembler. Terms have absolute or relocatable values that are assigned by the assembler or that are inherent in the terms themselves.

A term is absolute if its value does not change upon program relocation. A term is relocatable if its value changes by n if the origin of the control section in which it appears is relocated by n bytes.

Terms in parentheses

Terms in parentheses are reduced to a single value; thus the terms in parentheses, in effect, become a single term.

You can use arithmetically combined terms, enclosed in parentheses, in combination with terms outside the parentheses, as follows:

14+BETA-(GAMMA-LAMBDA)

When the assembler encounters terms in parentheses in combination with other terms, it first reduces the combination of terms inside the parentheses to a single value which may be absolute or relocatable, depending on the combination of terms. This value is then used in reducing the rest of the combination to another single value.

You can include terms in parentheses within a set of terms in parentheses:

A+B-(C+D-(E+F)+10)

The innermost set of terms in parentheses is evaluated first. Any number of levels of parentheses are allowed. A level of parentheses is a left parenthesis and its corresponding right parenthesis. An arithmetic combination of terms is evaluated as described in Expressions. Table 5 summarizes the various types of terms, and gives a reference to the page number that discusses the term and the rules for using it.

Table 5. Summary of terms
 
Terms
Term can be absolute Term can be relocatable Value is assigned by assembler Value is inherent in term Topic reference
Symbols X X X Symbols
Literals X X X Literals, constants, and self-defining terms
Self-defining terms X X Self-defining terms
Location counter reference X X Location counter
Symbol length attribute X X Symbol length attribute reference
Other data attributes1 X X Other attribute references
Notes:
  1. Other valid data attributes are scale and integer.

For more information about absolute and relocatable expressions, see Absolute and relocatable expressions.

Symbols

You can use a symbol to represent storage locations or arbitrary values. If you write a symbol in the name field of an instruction, you can then specify this symbol in the operands of other instructions and thus refer to the former instruction symbolically. This symbol represents a relocatable address.

You can also assign an absolute value to a symbol by coding it in the name field of an EQU instruction with an operand whose value is absolute. This lets you use this symbol in instruction operands to represent:

For details of these program elements, see Operand entries.

The advantages of symbolic over numeric representation are:

Symbol table

When the assembler processes your source statements for the first time, it assigns an absolute or relocatable value to every symbol that appears in the name field of an instruction. The assembler enters this value, which normally reflects the setting of the location counter, into the symbol table. It also enters the attributes associated with the data represented by the symbol. The values of the symbol and its attributes are available later when the assembler finds this symbol or attribute reference used as a term in an operand or expression. See "Symbol length attribute reference" and "Self-defining terms" in this chapter for more details. The three types of symbols recognized by the assembler are:

Ordinary symbols

Ordinary symbols can be used in the name and operand fields of machine and assembler instruction statements. There are two types of ordinary symbol, internal and external. Code them to conform to these rules:

External symbols are placed in the External Symbol Dictionary of the object module, where they are available to link editors and binders for linking with other separately translated programs. Internal symbols are normally discarded at the end of the assembly, but may be placed in the SYSADATA file (see "Input and output files" in the HLASM Programmer's Guide) for use by other programs such as debuggers.

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

The following examples are valid ordinary symbols:

ORDSYM#435A         HERE           $OPEN
K4                  #0123          X
B49467LITTLENAIL    @33            _TOTAL_SAVED
Variable symbols

Variable symbols must begin with an & followed by an alphabetic character and, optionally, up to 61 alphanumeric characters. Variable symbols can be used in macro processing and conditional assembly instructions, and to provide substitution in machine and assembler instructions. They allow different values to be assigned to one symbol. A complete discussion of variable symbols appears in How to specify macro definitions.

The following examples are valid variable symbols:

&VARYINGSYMABC      &@ME
&F346944            &A
&EASY_TO_READ
System variable symbol prefix

A variable symbol should not begin with the characters &SYS as they are used to prefix System Variable Symbols. See System variable symbols for a list of the System Variable Symbols provided with High Level Assembler.

Sequence symbols

Sequence symbols consist of a period (.) followed by an alphabetic character, and up to 61 additional alphanumeric characters. Sequence symbols can be used in macro processing and conditional assembly instructions. They indicate the position of statements within the source program or macro definition. They are used in AIF and AGO statements to vary the sequence in which statements are processed by the assembler program. (See the complete discussion in How to write conditional assembly instructions.)

The following examples are valid sequence symbols:

.BLABEL04            .#359
.BRANCHTOMEFIRST     .A
Symbol definition

An ordinary symbol is defined in:

Ordinary symbols can also be defined in instructions generated from model statements during conditional assembly.

In Figure 8, the assembler assigns a value to the ordinary symbol in the name entry according to the following rules:

  1. The symbol is assigned a relocatable address value if the first byte of the storage field contains one of the following:

    The address value assigned is relocatable, because the object code assembled from these items is relocatable. The relocatability of addresses is described in Addresses.

  2. The symbol is assigned the value of the first or only expression specified in the operand of an EQU instruction. This expression can have a relocatable (see  4  in Figure 8) or absolute (see  5  in Figure 8) value, which is then assigned to the ordinary symbol.

    The value of an ordinary absolute symbol must lie in the range -231 through +231-1. Relocatable symbols have unsigned address values in the range from 0 to 224-1, or 0 to 231-1 if the GOFF option is specified.

Figure 8. Transition from assembler language statement to object code
  Assembler Language     |  Address Value  |      Object Code
      Statements         |    of Symbol    |     in Hexadecimal
-------------------------+-----------------+----------------------------------
                         |  Relocatable    |              *------ Address
                         |                 |              V       of AREA
                         |                 |     *--*-*-*----*
LOAD     L     3,AREA    1  LOAD ----------+---->|58|3|0|xxxx|
                         |                 |     *--*-*-*----*
                         |                 |
                         |                 |     *-----------*
AREA     DS    F         2  AREA ----------+---->|xx x x xxxx|
                         |          *------+---->*-----------*
                         |          |      |
                         |          |      |     *-----------*
F200     DC    F'200'    3  F200 ----------+---->|00 0 0 00C8|
                         |          |   *--+---->*-----------*
-------------------------+----------+---+--+-----------------------------------
FULL     EQU   AREA      |  FULL ---*   |  |
                         4              |  |
TW00     EQU   F200      |  TW00 -------*  |
-------------------------+-----------------+-----------------------------------
                         |    Absolute     |
                         |                 |
R3       EQU   3         5  R3=3           |              *------ Address
                         |                 |              V       of FULL
                         |                 |     *--*-*-*----*
         L     R3,FULL   |                 |     |58|3|0|xxxx|
                         |                 |     *--+-+-+----*
         A     R3,TW00   |                 |     |5A|3|0|xxxx|
                         |                 |     *--*-*-*----*
                         |                 |              ^       Address
                         |                 |              *------ of TW00
Restrictions on symbols

A symbol must be defined only once in a source module with one or more control sections, with the following exceptions:

z/VM and z/OS
End of z/VM and z/OS

An ordinary symbol is not defined when:

Previously defined symbols

An ordinary symbol is previously defined if the statement that defines it is processed before the statement in which the symbol appears in an operand.

An ordinary symbol must be defined by the time the END statement is reached, however, it need not be previously defined when it is used as follows:

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

Literals may contain symbolic expressions in modifiers, but any ordinary symbols used must have been previously defined.

Self-defining terms

A self-defining term lets you specify a value explicitly. With self-defining terms, you can also specify decimal, binary, hexadecimal, or character data. If the DBCS assembler option is specified, you can specify a graphic self-defining term that contains pure double-byte data, or include double-byte data in character self-defining terms. These terms have absolute values and can be used as absolute terms in expressions to represent bit configurations, absolute addresses, displacements, length or other modifiers, or duplication factors.

Using self-defining terms

Self-defining terms represent machine language binary values and are absolute terms. Their values do not change upon program relocation. Some examples of self-defining terms and the binary values they represent are given below:

Self-Defining Term Decimal Value Binary Value
15 15 1111
241 241 1111 0001
B'1111' 15 1111
B'11110001' 241 1111 0001
B'100000001' 257 0001 0000 0001
X'F' 15 1111
X'F1' 241 1111 0001
X'101' 257 0001 0000 0001
C'1' 241 1111 0001
C'A' 193 1100 0001
C'AB' 49,602 1100 0001 1100 0010
G'<.A>' 17,089 0100 0010 1100 0001

The assembler carries the values represented by self-defining terms to 4 bytes or 32 bits, the high-order bit of which is the sign bit. (A '1' in the sign bit indicates a negative value; a '0' indicates a positive value.)

The use of a self-defining term is distinct from the use of data constants or literals. When you use a self-defining term in a machine instruction statement, its value is used to determine the binary value that is assembled into the instruction. When a data constant is referred to or a literal is specified in the operand of an instruction, its address is assembled into the instruction. Self-defining terms are always right-justified. Truncation or padding with zeros, if necessary, occurs on the left.

Decimal self-defining term

A decimal self-defining term is simply an unsigned decimal number written as a sequence of decimal digits. High-order zeros may be used (for example, 007). Limitations on the value of the term depend on its use. For example, a decimal term that designates a general register should have a value between 0 and 15. A decimal term that represents an address should not exceed the size of storage. In any case, a decimal term may not exceed 2,147,483,647 (231-1). A decimal self-defining term is assembled as its binary equivalent. Some examples of decimal self-defining terms are: 8, 147, 4092, and 00021.

Hexadecimal self-defining term

A hexadecimal self-defining term consists of hexadecimal digits enclosed in single quotation marks and preceded by the letter X; for example, X'C49' and X'00FF00FF00'.

Each hexadecimal digit is assembled as its 4-bit binary equivalent. Thus, a hexadecimal term used to represent an 8-bit mask would consist of 2 hexadecimal digits. The maximum value of a hexadecimal term is X'FFFFFFFF'; this allows a range of values from -2,147,483,648 through 2,147,483,647.

The hexadecimal digits and their bit patterns are as follows:

0 - 0000   4 - 0100   8 - 1000   C - 1100
1 - 0001   5 - 0101   9 - 1001   D - 1101
2 - 0010   6 - 0110   A - 1010   E - 1110
3 - 0011   7 - 0111   B - 1011   F - 1111

When used as an absolute term in an expression, a hexadecimal self-defining term has a negative value if the high-order bit is 1.

Binary self-defining term

A binary self-defining term is written as an unsigned sequence of 1s and 0s enclosed in single quotation marks and preceded by the letter B; for example, B'10001101'. A binary term may have up to 32 bits, not counting leading zero bits. This allows a range of values from -2,147,483,648 through 2,147,483,647.

When used as an absolute term in an expression, a binary self-defining term has a negative value if the term is 32 bits long and the high-order bit is 1.

Binary representation is used primarily in designating bit patterns of masks or in logical operations.

The following shows a binary term used as a mask in a Test Under Mask (TM) instruction. The contents of GAMMA are to be tested, bit by bit, against the pattern of bits represented by the binary term.

ALPHA    TM              GAMMA,B'10101101'
Character self-defining term

A character self-defining term consists of 1-to-4 characters enclosed in single quotation marks, and must be preceded by the letter C. All letters, decimal digits, and special characters may be used in a character self-defining term. In addition, any of the remaining EBCDIC characters may be designated in a character self-defining term. Examples of character self-defining terms are:

C'/'
C' ' (space)
C'ABC'
C'13'

Because of the use of single quotation marks in the assembler language and ampersands in the macro language as syntactic characters, the following rule must be observed when using these characters in a character self-defining term:

For C-type character self-defining terms, each character in the character sequence is assembled as its 8-bit code equivalent (see Appendix D. Standard character set code table). The two single quotation marks or ampersands that must be used to represent a single quotation mark or ampersand within the character sequence are assembled as a single quotation mark or ampersand. Double-byte data may appear in a character self-defining term, if the DBCS assembler option is specified. The assembled value includes the SO and SI delimiters. Hence a character self-defining term containing double-byte data is limited to one double-byte character delimited by SO and SI. For example, C'<.A>'.

Since the SO and SI are stored, the null double-byte character string, C'<>', is also a valid character self-defining term.

Note:
The assembler does not support character self-defining terms of the form CU'x' because self-defining terms are required by definition of the Assembler Language to have fixed values.

There are many EBCDIC code pages; some characters have different encodings in different code pages. To be sure that your character constants and self-defining terms have the representations and value, use just these 82 invariant characters:

These characters have the same binary representation across all single-byte EBCDIC code pages. If you use any other character, the Assembler will use its bit pattern as its value, so it may not display as the same character in environments where a different code page is used by default.

Graphic self-defining term

If the DBCS assembler option is specified, a graphic self-defining term can be specified. A graphic self-defining term consists of 1 or 2 double-byte characters delimited by SO and SI, enclosed in single quotation marks and preceded by the letter G. Any valid double-byte characters may be used. Examples of graphic self-defining terms are:

G'<.A>'
G'<.A.B>'
G'<Da>'
G'<.A><.B>'

The SO and SI are not represented in the assembled value of the self-defining term, hence the assembled value is pure double-byte data. A redundant SI/SO pair can be present between two double-byte characters, as shown in the last of the above examples. However, if SO and SI are used without an intervening double-byte character, this error is issued:

ASMA148E Self-defining term lacks ending quote or has bad character

Location counter

The assembler maintains a location counter to assign storage addresses to your program statements. It is the assembler's equivalent of the execution-time instruction counter in the computer. You can refer to the current value of the location counter at any place in a source module by specifying an asterisk (*) as a term in an operand.

As the instructions and constants of a source module are being assembled, the location counter has a value that indicates a location in the program. The assembler increments the location counter according to the following:

  1. After an instruction or constant has been assembled, the location counter indicates the next available location.
  2. Before assembling the current instruction or constant, the assembler checks the boundary alignment required for it and adjusts the location counter, if necessary, to the correct boundary.
  3. While the instruction or constant is being assembled, the location counter value does not change. It indicates the location of the current data after boundary alignment and is the value assigned to the symbol, if present, in the name field of the statement.
  4. After assembling the instruction or constant, the assembler increments the location counter by the length of the assembled data to indicate the next available location.

These rules are shown below:

Location in               Source
Hexadecimal               Statements

000004         DONE       DC  CL3'ABC'
000007         BEFORE     EQU *
000008         DURING     DC  F'200'
00000C         AFTER      EQU *
000010         NEXT       DS  D

You can specify multiple location counters for each control section in a source module; for more details about the location counter setting in control sections, see Location counter setting.

Maximum location counter value

The assembler carries internal location counter values as 4-byte (31-bit unsigned) values. When you specify the NOGOFF assembler option, the assembler uses only the low-order 3 bytes for the location counter, and prints only the low-order 3 bytes in the assembly source and object code listing if the LIST(121) option is active. All four bytes are displayed if the LIST(133) option is active. In this case the maximum valid location counter value is 224-1.

z/VM and z/OS

When you specify the GOFF assembler option, the assembler requires the LIST(133) option, and uses the entire 4-byte value for the location counter and prints the 4-byte value in the assembly listings. In this case the maximum valid location counter value is 231-1.

End of z/VM and z/OS

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

ASMA039S Location counter error
Controlling the location counter value

You can control the setting of the location counter in a particular control section by using the START or ORG instruction, described in Program structures and addressing and Assembler instruction statements, respectively. The counter affected by either of these assembler instructions is the counter for the control section in which they appear.

Location counter reference

You can refer to the current value of the location counter at any place in a program by using an asterisk as a term in an operand. The asterisk is a relocatable term, specified according to the following rules:

For the value of the asterisk in address constants with duplication factors, see Subfield 1: Duplication Factor of DC instruction, and Address constants--A and Y. For a discussion of location counter references in literals, see Subfield 1: Duplication Factor.

Symbol length attribute reference

The length attribute of a symbol may be used as a term. Reference to the attribute is made by coding L' followed by the symbol, as in:

L'BETA

The length attribute of BETA is substituted for the term. When you specify a symbol length attribute reference, you obtain the length of the instruction or data named by a symbol. You can use this reference as a term in instruction operands to:

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

The value of the length attribute is normally the length in bytes of the storage area required by an instruction, constant, or field represented by a symbol. The assembler stores the value of the length attribute in the symbol table along with the address value assigned to the symbol.

When the assembler encounters a symbol length attribute reference, it substitutes the value of the attribute from the symbol table entry for the symbol specified.

The assembler assigns the length attribute values to symbols in the name field of instructions as follows:

For assembler instructions such as DC, DS, and EQU, the length attribute of the location counter reference (L'* -- see  6  in Table 6) is equal to 1. For machine instructions, the length attribute of the location counter reference (L'* -- see  7  in Table 6) is equal to the length attribute of the instruction in which the L'* appears.

Table 6. Assignment of length attribute values to symbols in name fields
Source Module Length Attribute Reference Value of Symbol Length Attribute At Assembly Time
MACHA     MVC  TO,FROM
MACHB     L    3,ADCON
MACHC     LR   3,4

TO        DS   CL80
FROM      DS   CL240
ADCON     DC   A(OTHER)
CHAR      DC   C'YUKON'
DUPL      DC   3F'200'

RELOC1    EQU  TO          3 
RELOC2    EQU  TO+80       3 
RELOC3    EQU  TO,44       3 
ABSOL1    EQU  FROM-TO     3 
ABSOL2    EQU  ABSOL1      3 

SDT1      EQU  102         3 
SDT2      EQU  X'FF'+A-B   3 
SDT3      EQU  C'YUK'

ASTERISK  EQU  *+10        3 

LOCTREF   EQU  L'*         3 
LENGTH1   DC   A(L'*)


LENGTH2   MVC  TO(L'*),FROM
LENGTH3   MVC  TO(L'TO-20),FROM
L'MACHA
L'MACHB
L'MACHC

L'TO
L'FROM
L'ADCON
L'CHAR
L'DUPL

L'RELOC1
L'RELOC2
L'RELOC3
L'ABSOL1
L'ABSOL2

L'SDT1
L'SDT2
L'SDT3

L'ASTERISK

L'LOCTREF
L'*
L'LENGTH1

L'*
L'TO
6     1 
4     1 
2     1 

80    2 
240   2 
4     2 
5     2 
4     2 

80
80
44
240
240

1     4 
1     4 
1     4 

1     5 

1     6 
1     6 
4

6     7 
80
Note:
Instructions that contain length attribute references L'SDT1, L'SDT2, L'SDT3, L'ASTERISK, and L'LOCTREF as shown in this figure may 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.

A1       DS              CL8
B2       DC              CL2'AB'
HIORD    MVC             A1(L'B2),B2
LOORD    MVC             A1+L'A1-L'B2(L'B2),B2

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

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

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.


[ Top of Page | Previous Page | Next Page | Contents | Index ]