Chapter 7
Names

A program is full of names: labels, values defined with EQU, macros, segments. Chapter 2 called them symbols, and chapter 12 describes how each kind gets its value. This chapter is about how a name is spelled: the characters it can contain, how long it can be, whether upper and lower case matter, and which names are best avoided.

7.1 The characters of a name

A name is made of the characters in table 7.1, in any order, except that it must not start with a digit.

These are the characters M80 allows. All four names in this source are ordinary labels:

        cseg 
?tmp:           nop 
@loop:          nop 
my.name:        nop 
a_b$c:          nop
 

Four names that M80 allows cannot be names in TATARA: IXH, IXL, IYH and IYL, which are registers (section 9.5).

Any other character in a label stops TATARA with a name may hold only letters, digits, ? @ . _ and the dollar sign.

The underscore is the one most programs use, to join the words of a long name: print_string. The others are legal, but a reader may take my.name or a_b$c for something other than a name, so the examples do not use them.

A word that starts with a digit is a number (chapter 8). TATARA does accept 1st: as a label, but nothing can refer to it: jp 1st reads 1st as a badly written number, and stops:

DIGIT2.AS(3): ERROR: bad expression.
 

7.2 Length

The name of a symbol, a label or a value defined with EQU or DEFL, can be up to 255 characters long, and every character counts: two names that differ only in their last character are two different symbols. This source, from the example NAMES (chapter 31), defines two symbols whose names differ only in the last five characters:

first_pass_symbol_table_high_water_mark_in_bytes        defl    1024 
first_pass_symbol_table_high_water_mark_in_words        defl    512
 

M80 kept only the first six characters of a name, which is why so many programs from the CP/M era are written in abbreviations such as PRTSTR. With TATARA there is no need for them.

Symbol names keep their full length in the object file, so a public name in one module and the same name declared external in another are matched in full when TANREN links them (chapter 2).

The names of macros, segments and groups are shorter. A macro name can be up to 64 characters long, and a segment or group name (chapter 10) up to 16. A longer name is refused, not cut short, with one of these messages:

• a macro name may be at most 64 characters.
• a segment or group name may be at most 16 characters.

7.3 Upper and lower case

By default, as in M80, upper and lower case do not matter in a name: Counter, counter and COUNTER are the same name. The option /C (chapter 5) makes them three different names.

/C applies only to the names you choose. Instructions, registers and directives can be written in either case with or without it (chapter 6).

The example NAMES shows the difference. It defines two symbols that differ only in case, with DEFL, which allows a name to be given a new value:

; NAMES.AS - names as long as you like, in either case. 
; 
; A SYMBOL MAY BE 255 CHARACTERS AND ALL OF THEM COUNT. M80 keeps the 
; first six, which is why so much CP/M-era assembly is written in 
; abbreviations. The two names below differ only in their last five 
; characters and are two different symbols here. 255 is the limit, and 
; the test suite has a 240-character name in it; these are 48, which is 
; as long as a line can carry and still be read on an MSX screen. 
 
first_pass_symbol_table_high_water_mark_in_bytes        defl    1024 
first_pass_symbol_table_high_water_mark_in_words        defl    512 
 
; THE SAME SIX LETTERS IN TWO CASES. Without /C they are ONE symbol, 
; and the second line changes its value. With /C they are TWO, with 
; values 1 and 2. The symbol table of each run says which - and DEFL 
; is used rather than EQU because a redefinition is legal, so the 
; source assembles cleanly in both modes. 
 
Counter         defl    1 
counter         defl    2 
 
; DIRECTIVES, MNEMONICS AND REGISTER NAMES ARE CASE-INSENSITIVE IN 
; BOTH MODES. /C is about the names you choose, not the ones the Z80 
; already has. 
 
                cseg 
 
start:          LD      A,1 
                ld      b,a 
                DB      Counter 
                db      counter 
                ret 
 
                end     start   

Assembled without /C, Counter and counter are one symbol, and the second line gives it a new value, 2. This is the end of the symbol table that /S prints (chapter 19):

A:\TATARA\EXAMPLES\NAMES>tatara /q /p /s names.as 
... 
ASEG - absolute 
 
0002h  var        Counter 
0200h  var        first_pass_symbol_table_high_water_mark_in_words 
0400h  var        first_pass_symbol_table_high_water_mark_in_bytes
 

The table shows the name as it was written where it was first defined. With /C there are two symbols, with the values 1 and 2:

A:\TATARA\EXAMPLES\NAMES>tatara /q /p /c /s names.as 
... 
ASEG - absolute 
 
0001h  var        Counter 
0002h  var        counter 
0200h  var        first_pass_symbol_table_high_water_mark_in_words 
0400h  var        first_pass_symbol_table_high_water_mark_in_bytes
 

Use /C only when a program needs names that differ only in case, for instance because it was written for, or produced by, a tool that tells them apart. Otherwise the default is safer: a name typed in the wrong case still refers to the right symbol.

7.4 Names that are hard to reach

TATARA has no reserved words: it defines any name it is given. But in some places it looks a word up in a fixed list before it looks for a name, and there a name spelled like a word in the list is never reached. There are four such places.

The operation field.

TATARA looks for a directive first, then a macro, then an instruction. A macro named like a directive can never be called, and a macro named like an instruction is used instead of it (chapter 16).

An instruction’s operand.

If the first word of an operand is exactly the name of a register, the word is that register. The word ends at a space, a tab, a comma, a bracket, + or -, so c and c+0 both start with the register C, while bad is a word of its own and an ordinary name. The registers are A, B, C, D, E, H, L, BC, DE, HL, SP, AF, AF’, IX, IY, I and R.

A condition.

After JP, JR, CALL and RET, the conditions NZ, Z, NC, C, PO, PE, P and M come first.

An expression.

NOT, HIGH and LOW are always operators, and MOD, SHR, SHL, EQ, NE, LT, LE, GT, GE, AND, OR and XOR are operators wherever an operator can stand (chapter 8). A symbol named high is defined, but db high stops with bad expression.

The name c shows most of this at once, because it is a register, a condition and a legal name. This source defines it, and uses it four times:

c               equ     5 
                cseg 
                ld      a,c 
                ld      a,0+c 
                jp      c,c 
                db      c
 

Table 7.2 shows the bytes TATARA writes for each line, from its listing.

Written ld a,c+0, the second line fails, because the operand starts with the register name:

REGNAME.AS(4): ERROR: not a form this instruction has.
 

The safe rule is simple: do not give a name the spelling of a register, a condition, an operator, a directive or an instruction. Appendix A lists the directives and appendix B the instructions.

7.4.1 Names that start with two question marks

The directive LOCAL (chapter 16) makes up names for the labels inside a macro, so that each time the macro is used its labels are different. The names are ??0000, ??0001 and so on, and they appear in the symbol table like any other name:

CSEG - default code segment, 0009h bytes 
 
0000h             start 
0002h             ??0000 
0006h             ??0001
 

Do not define names of that form yourself, or they may clash with the ones LOCAL makes.

7.4.2 The dollar sign on its own

$ on its own is not a name but the location counter, the address of the current line (chapters 8 and 10). Inside a name, as in a_b$c, it is an ordinary character.