VIII. SPECIAL FEATURES

END OF ASSEMBLY INFORMATION

Upon termination of an assembly, and before the symbol table is output, three items of information may be printed: the total number of errors encountered, the total number of warnings encountered, and the address of the last byte of code assembled.

The number of errors is always printed in the following manner:

0 ERROR(S) DETECTED

The number of warnings are printed only if warnings have not been suppressed by the 'W' option on the command line and if the number is greater than zero (ie. only if there was a warning):

0 ERROR(S) DETECTED 2 WARNING(S) REPORTED

The last assembled address is printed only if the assembled output listing is turned off by the 'L' option on the command line. It is actually the last address which the assembler's program counter register was pointing to, so there may not really be an assembled byte of code at this address. For example if the last instruction in a program except for the END was an RMB directive, the address would be the last byte reserved by that command. This information is presented as follows:

LAST ASSEMBLED ADDRESS: 1055

The address is printed as a 4-digit hexadecimal value.

EXCESSIVE BRANCH OR JUMP INDICATOR

A mechanism has been included in the assembler to inform the programmer when a long branch or jump could be replaced by a short branch. The purpose is to allow size and speed optimization of the final code. This indicator is a greater-than sign placed just before the address of the long branch or jump instruction which could be shortened. The following section of code shows just how it looks:

3420 B6 E004 INCH LDA $E004
3423 84 01 ANDA #$01
>3425 1027 FFF7 LBEQ INCH
3429 B6 E005 LDA $E005
342C 81 20 CMPA #$20
342E 24 06 BHS OUTCH
>3430 BD 3436 JSR OUTCH
>3433 7E 3420 JMP INCH
3436 34 04 OUTCH PSHS B

These indicator flags may be suppressed by selecting the 'W' option in the command line option list.

AUTO FIELDING

The assembler automatically places the four fields of a source line (label, mnemonic, operand, and comment) in columns in the output assembled listing. This allows the programmer to edit a condensed source file without impairing the readability of the assembled listing. The common method of doing this is to separate the fields by only one space when editing. The assembled output places all mnemonics beginning in column 8, all opcodes beginning in column 15, and all comments beginning in column 25 assuming the previous field does not extend into the current one. There are a few cases where this automatic fielding can break down such as lines with errors, but these cases are rare and generally cause no problem.

AUTO TABLE SETUP

The assemble automatically sets up all necessary tables and buffers depending on the amount of memory contained in your system. The amount of memory contained is determined by reading the memory end value (MEMEND) in FLEX. The tables or buffers which can vary in size are as follows:

SYMBOL TABLE This table is where all symbols are maintained during assembly. Each entry into the symbol table requires 8 bytes, 6 for the name and two for the address or value associated with it. This assembler uses a hashed symbol table technique which can mean that symbols are pseudo-randomly scattered throughout the table. This method is very fast but has one drawback - the assembler is usually not able to completely fill all positions in the table. Thus a symbol table full error message does not necessarily mean that every position in the table is really full. It simply means the assembler was unable to put any more symbols in the table due to the hashing technique used. The larger the table, the faster the hashing method will execute and accordingly, the faster the assembler will run. If possible, it is good to have 50% more space in the symbol table than will be required to actually hold the number of symbols in a program.

SOURCE BUFFER This is the buffer which holds the source program to be assembled. To gain speed, the assembler reads as many lines as it can into this buffer all at once. The assembly operation is carried out on each buffer individually. This buffer may be any size so long as it will hold the longest line that may be encountered in the source. There must also be a reserved 256-byte overflow area directly following the end of the source buffer.

MACRO TEXT BUFFER This is the buffer where macros are stored upon definition. If few macros are to be used, it can be very small. The more macros anticipated, the larger the buffer should be.

MACRO NAME TABLE This is a table where macro names and locations are stored. Each entry requires 8 bytes, 6 for the macro name and 2 for the address of the macro body in the macro text buffer. Again, if few macros are to be defined, this table can be quite small.

MACRO ACTIVATION BUFFER This buffer is an area where the macro processor builds an activation stack for all macros currently under execution. Each time a macro is called, certain information about it is placed on this stack. If no parameters are supplied on the calling line, an entry on the stack requires some 10 bytes. Any calling line parameters will raise this amount. If macros are not nested, only one entry will be on the stack at a time. However, if one macro calls another, there must be two entries on the stack and so on. The minimum size of the stack necessary depends on the amount of macro nesting done.

The assembler attempts to provide a general sizing of these tables for any size system in which it is run. This sizing is done according to the following approximate formulae:

Let AVM = MEMEND - MEMBEG
where AVM implies available memory
MEMEND refers to the end of memory as in FLEX
MEMBEG is the start of the RAM buffer area

Then

SYMBOL TABLE = (AVM-1K)*0.625
MACRO TEXT BUFFER = (AVM-1K)*0.188
MACRO NAME TABLE = (AVM-1K)*0.031
MACRO ACTIVATION BUFFER = (AVM-1K)*0.031
SOURCE BUFFER = AVM-256-(sum of above spaces)

These formulae change if there is enough memory to produce a symbol table of larger than 16K according to the symbol table formula given above. In that case, the symbol is limited to 16K (enough for almost 2000 symbols) and the remaining space is divided equally between the macro text buffer and the source buffer.

These table sizes can be set manually by the programmer if so desired. See the section on adapting to your system for details.

COMMAND LINE PARAMETERS

In the section on using the assembler at the beginning of this manual, command line parameters are discussed. That section describes how to place a parameter on the command line for passing into the source, but it does not elaborate on how the programmer tells the assembler where in the source to substitute those parameters. If you have read the section on macros, you should already understand the concept of parameter substitution. If not, read that section before continuing here.

Much as in macro parameter substitution, there are 2-character symbols or dummy parameters which, if placed anywhere in the source, will be replaced by the parameters supplied on the command line. In macros, the parameters from the macro calling line were substituted into the macro body during expansion of the macro. Here, the parameters from the command line are substituted into the source as it is read in from the disk. In macros, there were 10 possible parameters. Here there are three possible. The 2-character dummy parameters for these three are '&A', '&B', and '&C'. These correspond to the three possible command line parameters represented here:

+++ASMB,<filename>,+<options>,+<prm.A>,<prm.B>,<pm.C>

As can be seen, the three parameters are separated by commas.

Just as in macros, the dummy parameters can be ignored by placing a backslash directly in front of the ampersand. Thus the following line of edited source:

VALUE EQU MASK\&COUNT

would be read into the assembler as:

VALUE EQU MASK&COUNT

A quick example should help clarify the preceding descriptions. The following program contains one dummy parameter, '&A'.

* ROUTINE TO OUTPUT TO ONE OF TWO PORTS
OPT PAG,CON
TTL OUTPUT ROUTINE FOR PORT #&A
PAG
IFN (&A=0)|(&A=l)
ERR NOT A VALID PORT NUMBER
ELSE
IF &A=0
ACIA EQU $E000
ELSE
ACIA EQU $E004
ENDIF
ENDIF

OUTCH LDB ACIA
ANDB #$02
BEQ OUTCH
STA ACIA
RTS

END

Now if this file were assembled with a command line like:

+++ASMB,FILE,+BGDS,+1

(assuming the file is very creatively called, 'FILE'), we would see the following assembled output:

OUTPUT ROUTINE FOR PORT #l TSC ASSEMBLER PAGE 1

IFN (1=0)1(1=1)
ERR NOT A VALID PORT NUMBER
ELSE
IF l=0
ACIA EQU $E000
ELSE
E004 ACIA EQU $E004
ENDIF
ENDIF

0000 F6 E004 OUTCH LDB ACIA
0003 C4 02 ANDB #$02
0005 27 F9 BEQ OUTCH
0007 B7 E004 STA ACIA
000A 39 RTS

END

0 ERROR(S) DETECTED

Note that the first page of output is not shown.