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
readable text file. 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 expanded (see Section 6.3),
and the inclusion of USE directives in the body of
a conditional block (see Chapter 5)
will only have an effect if the expressions governing
the execution of that conditional block have appropriate values.
If USE directives nested too deeply,
a "too many use levels" error will be raised.
All versions of SMAL should support at least 2 levels of nesting.
USE directives are commonly used for inserting standard macro
definitions (see Chapter 6) and assignments of
symbolic values (see Section 2.2)
into a program, or
for inserting shared COMMON definitions
(see Section 4.3)
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:
If the first file is stored in a file known to the operating
system as standard.h, assembling the user file will result in the
following listing:
Note that, by default, the contents of the used file are not listed
as they are processed; this can be changed using the LIST directive.
For example, in the above listing, the contents of standard.h
are not listed, but the assembler has seen its contents, as is shown by the
values produced when A and B were used.
File name suffixes such as .a or .h have no meaning to
SMAL. They are merely parts of the file name. The convention of
adding a .h (header) suffix is a sensible way to name
files holding definitions intended to be inserted by
USE directives at the head of a source file.
When a hierarchically structured file system is used where there is a
clear syntactic distinction between absolute 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.
Under Unix (including Linux), if the assembler is currently
reading from "library/src.a" and USE "entry.h" is
encountered, the assembler will read from library/entry.h.
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, and if a USE directory has been specified using the
-U command-line option
(see Section 10.1),
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 (see Section 6.1).
The only function of the END directive is to mark the ends
of files and macros.
If an END directive is explicitly given in a file,
all lines after it will be ignored.
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.
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:
If no starting address is give, the loader may set a default.
The run-time system determines how the starting address is used.
Some systems may require use of a
standard external symbol such as MAIN. Some systems
may use the starting address to set an initial breakpoint.
The assembler normally only lists lines from the base file,
and does not list lines resulting from macro expansion
(see Section 6.3) and USE insertions
(see Section 7.1).
This default may be overridden by the
LIST directive.
At all times, the assembler keeps a record of the number of macro or
USE nesting levels to be included in the listing.
The operand of the LIST directive is adjusts this.
Poitive operands cause that many additional levels to be listed.
Negative operands cause that many fewer to be listed.
The line containing the LIST directive will not be printed if it causes
listing to be turned on.
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:
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 the next page
heading. 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:
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.
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
conditional (see Chapter 5)
and macro (see Chapter 6)
assembly, for example, to report an illegal parameter.
; FILE OF STANDARD DEFINITIONS
A =: 0
B =: 1
; A USER FILE
USE "standard.h"
W A
W B
1 ; A USER FILE
2 USE "standard.h"
+000000: 00000000 3 W A
+000004: 00000001 4 W B
5 END
7.2. End of File
<symbolic directive> ::= END
7.3. Starting Address Specification
<symbolic directive> ::= S <expression>
TITLE MAIN PROGRAM
S START
START:
7.4. Listing Control
<symbolic directive> ::= LIST <expression>
7.5. Titles and Subtitles
<symbolic directive> ::= TITLE { <lexeme> }
| SUBTITLE { <lexeme> }
7.6. Pagination
<symbolic directive> ::= PAGE
7.7. Deliberate Error Messages
<symbolic directive> ::= ERROR { <lexeme> }