7. Miscellaneous Assembly Directives
Part of
the SMAL Manual
|
SMAL32 allows text to be inserted into the body of a program from
an alternate source file at assembly time. The only requirements are that
the alternate source file be itself a legal SMAL program, and that insertions
are not nested deeper than the implementation allows. The USE directive
causes text insertion.
<symbolic directive> ::= USE <quoted string>
The string operand on a USE directive must contain the name of a file
from which additional text may be read.
The USE directive is not executed by a preprocessor; thus, the inclusion of
USE directives in the body of a macro will have no effect until that
macro is called, and the inclusion of USE directives in the body of
a conditional block will only have an effect if the expressions governing
the execution of that conditional block have appropriate values.
If too many levels of nested USE directives are encountered, a "too many use
levels" error will be raised.
All versions of SMAL should support at least 2 levels of nesting, so that
one used file can use another.
USE directives are commonly used for inserting standard macro definitions into a program, or for inserting common definitions into one of a group of programs which are to be linked together. The following two source files demonstrate the use of the USE directive:
; FILE OF STANDARD DEFINITIONS
A = 0
B = 1
; A USER FILE
USE "STANDARD"
W A
W B
If the first file is stored in a file known to the operating system as "STANDARD", assembling the second file will result in the following listing:
1 ; A USER FILE
2 USE "STANDARD"
+000000: 00000000 3 W A
+000004: 00000001 4 W B
5 END
Note that, by default, the contents of the used file are not listed as they are processed. For example, in the above listing, the contents of "STANDARD" are not listed, but the assembler has seen its contents, as is shown by the values produced when "A" and "B" were used.
When a hierarchically structured file system is used where there is a clear syntactic distinction between absolute file names and relative file names, the SMAL32 assembler will interpret relative file names in the context of the directory immediately containing the file from which the line containing the file name was read. This is not necessarily the same as the user's current working directory. For example, under Unix, if the assembler is currently reading from "library/dir" and the directive "USE 'entry'" is encountered, the assembler will read from "library/entry". In the same context, if the directive "USE '/usr/public/lib'" will result in reading from "/usr/public/lib", since that file name was specified absolutely.
If the SMAL32 assembler cannot find the desired relative file name on its first try, following the rules in the above paragraph, and if a USE directory has been specified using the -U command-line option, it will look in that directory for the file before giving up.
The assembler automatically inserts an END directive at the end of each source file from which it reads, and at the end of each macro body it processes. The only function of the END directive is to mark the ends of files and macros.
<symbolic directive> ::= END
It is legal to explicitly include an END directive at the end of a file; if additional lines are included in the file after the end directive, they will always be ignored.
Explicit inclusion of an END directive in a macro body requires that the END directive be enclosed in single quotes to prevent it from being mistaken for the end of file. About the only reason to do this is to include special comments on the end of a macro or to adjust the indenting of the END directive in a listing.
The assembler allows the address at which the object program is to begin execution to be passed through to the loader by the use of the start directive.
<symbolic directive> ::= S <expression>
Only one S directive may be given per program, and it is suggested that that directive be given at the head of the program so that it is easy to find. A typical program might begin as follows:
TITLE MAIN PROGRAM
S START
START:
If no starting address is specified, a default may be established by the loader.
The assembler normally only lists source lines from the base file from which it is assembling, and does not list the results of macro calls and text insertions. The listing behavior may be manually controlled by the list directive.
<symbolic directive> ::= LIST <expression>
At all times, the assembler keeps a record of the number of macro or include nesting levels it is to include in the listing. The operand of the LIST directive is added to this counter. Thus, if the operand is positive, it will cause additional nesting levels to be listed, and if it is negative, it will suppress the listing of some number of nesting levels.
The line containing the LIST directive will not be printed if it causes listing to be turned on or off. Thus, macros which use LIST directives to selectively list parts of their expansions will not clutter the listing with the LIST directives themselves.
By default, SMAL32 listings are titled with the version of the assembler and the name of the file being assembled. The following two directives may be used to modify this behavior:
<symbolic directive> ::= TITLE { <lexeme> }
| SUBTITLE { <lexeme> }
| ERROR { <lexeme> }
The subtitle on each listing page will appear directly below the title. The remainder of the line following the TITLE or SUBTITLE directive is used as the title or subtitle, including comments. The text of the title or subtitle must be lexically valid; this usually causes no problems, since any sequence of words is lexically valid as a sequence of identifiers.
Programs should usually contain only one TITLE directive, and may contain any number of SUBTITLE directives. Each SUBTITLE directive will force the start of a new page in the listing, and in addition, will be used during the first pass of the assembler to construct a table of contents.
SUBTITLE directives encountered while listing is disabled will not cause a page eject, but the new subtitles will show up on later page ejects. A PAGE directive followed by a SUBTITLE directive will cause only one page eject.
By default, the assembly listing contains page breaks every 60 lines, Thee TITLE and SUBTITLE directives produce additional breaks, and if additional breaks are desired, the PAGE directive may be used:
<symbolic directive> ::= PAGE
PAGE directives encountered while listing is disabled will not cause a page eject. A PAGE directive followed by a SUBTITLE directive will cause only one page eject.
<symbolic directive> ::= ERROR { <lexeme> }
The ERROR directive, like TITLE and SUBTITLE, allows any text to be included in the remainder of the line; this directive always forces an assembly error message that will list that line, at the point where it was encountered during the assembly process. This is most likely to be useful inside complex macro and conditional assembly code, for example, to report that a macro parameter is out of bounds.