7. Miscellaneous Assembly Directives

Part of the SMAL Manual
by Douglas W. Jones
THE UNIVERSITY OF IOWA Department of Computer Science


  1. Text Insertions
  2. End of File
  3. Starting Address Specification
  4. Listing Control
  5. Titles and Subtitles
  6. Pagination
  7. Deliberate Error Messages

7.1. Text Instertions

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:

    A = 0
    B = 1

    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.

7.2. End of File

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.

7.3. Starting Address Specification

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:

        S       START

If no starting address is specified, a default may be established by the loader.

7.4. Listing Control

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.


7.5. Titles and Subtitles

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.


7.6. Pagination

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.

7.7. Deliberate Error Messages

<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.