A symbol is a single character or combination of characters used as a label or operand.
Symbols may consist of numeric digits, underscores, periods, uppercase or lowercase letters, or any combination of these. The symbol cannot contain any blanks or special characters, and cannot begin with a digit. Uppercase and lowercase letters are distinct.
If a symbol must contain blank or special characters because of external references, the .rename pseudo-op can be used to treat a local name as a synonym or alias for the external reference name.
From the assembler's and loader's perspective, the length of a symbol name is limited only by the amount of storage you have.
Note: Other routines linked to the assembler language files may have their own constraints on symbol length.
With the exception of control section (csect) or Table of Contents (TOC) entry names, symbols may be used to represent storage locations or arbitrary data. The value of a symbol is always a 32-bit quantity.
The following are valid examples of symbol names:
The following are not valid symbol names:
| 7_sum | (Begins with a digit.) |
| #ofcredits | (The # makes this a comment.) |
| aa*1 | (Contains * , a special character.) |
| IN AREA | (Contains a blank.) |
You can define a symbol by using it in one of two ways:
You can define a symbol by using it as a label. For example:
.using dataval[RW],5 loop:
bgt cont . .
bdz loop cont: l 3,dataval
a 4,3,4 . .
.csect dataval[RW] dataval: .short 10
The assembler gives the value of the location counter at the instruction or pseudo-op's leftmost byte. In the example here, the object code for the l instruction contains the location counter value for dataval .
At run time, an address is calculated from the dataval label, the offset, and GPR 5, which needs to contain the address of csect dataval[RW] . In the example, the l instruction uses the 16 bits of data stored at the dataval label's address.
The value referred to by the symbol actually occupies a memory location. A symbol defined by a label is a relocatable value.
The symbol itself does not exist at run time. However, you can change the value at the address represented by a symbol at run time if some code changes the contents of the location represented by the dataval label.
Use a symbol as the name operand of a .set pseudo-op to define the symbol. This pseudo-op has the format:
The assembler evaluates the exp operand, then assigns the value and type of the exp operand to the symbol name. When the assembler encounters that symbol in an instruction, the assembler puts the symbol's value into the instruction's object code.
.set number,10 .
.
ai 4,4,number
In the preceding example, the object code for the ai instruction contains the value assigned to number , that is, 10.
The value of the symbol is assembled directly into the instruction and does not occupy any storage space. A symbol defined with a .set pseudo-op can have an absolute or relocatable type, depending on the type of the exp operand. Also, because the symbol occupies no storage, you cannot change the value of the symbol at run time; reassembling the file will give the symbol a new value.
A symbol also can be defined by using it as the name operand of a .comm, .lcomm, .csect, .dsect, or .rename pseudo-op. Except in the case of the .dsect pseudo-op, the value assigned to the symbol describes storage space.
A symbol can also be defined when used as the qualname operand of the .csect pseudo-op. When used in this context, the symbol is defined as the name of a csect with the specified storage mapping class. Once defined, the symbol takes on a storage mapping class that corresponds to the name qualifier.
A qualname operand takes the form of:
where XX is the storage mapping class.
For more information, see the .csect pseudo-op.
Provisions have been made for the special symbol TOC. In XCOFF format modules, this symbol is reserved for the TOC anchor, or the first entry in the TOC. The symbol TOC has been predefined in the assembler so that the symbol TOC can be referred to if its use is required. The .toc pseudo-op creates the TOC anchor entry. For example, the following data declaration declares a word that contains the address of the beginning of the TOC:
.long TOC[TC0]
This symbol is undefined unless a .toc pseudo-op is contained within the assembler file.
For more information, see the .toc pseudo-op.
A symbol can be defined when used as the Name operand of the .tc pseudo-op. When used in this manner, the symbol is defined as the name of a TOC entry with a storage mapping class of TC.
The Name operand takes the form of:
For more information, see the .tc pseudo-op.
It is possible to use a symbol before you define it. Using a symbol and then defining it later in the same file is called forward referencing. For example, the following is acceptable:
# Assume that GPR 6 contains the address of .csect data[RW].
l 5,ten(6)
.
.
.csect data[RW]
ten: .long 10
If the symbol is not defined in the file in which it occurs, it may be an external symbol or an undefined symbol. When the assembler finds undefined symbols, it gives an error message unless the -u flag of the as command is used to suppress this error message. External symbols may be declared in a statement using the .extern pseudo-op.
If a local symbol is used that is defined in another module, the .extern pseudo-op is used to declare that symbol in the local file as an external symbol. Any undefined symbols that do not appear in a statement with the .extern or .globl pseudo-op will be flagged with an error.
The atof subroutine.
The .comm pseudo-op, .csect pseudo-op, .double pseudo-op, .dsect pseudo-op, .float pseudo-op, .lcomm pseudo-op, .tc pseudo-op, .toc pseudo-op, .tocof pseudo-op.