This chapter describes how to assemble MACRO--11 programs on the RT--11 operating system.
Output from the MACRO--11 assembler includes any or all of the following:
To use the MACRO--11 assembler, you should understand how to:
The following sections describe these topics. See the click here for an introductory explanation of how to assemble a MACRO--11 file, and see the click here for a detailed description of MACRO--11.
To call the MACRO--11 assembler from the system device, respond to the system dot prompt by typing:
When the assembler responds with an asterisk (*), it is ready to accept command string input. (You can also call the assembler using the keyboard monitor MACRO command; see the click here for a description of this command.)
To terminate the MACRO--11 assembler while it is waiting for input, press once. This returns you to system monitor control. To halt the assembly process at any time after you have completed the command string (thus beginning an assembly) press twice. This returns control to the system monitor, and a system monitor dot prompt appears on the terminal.
To restart the assembly process, issue the R MACRO command in response to the system monitor prompt.
The assembler expects a command string consisting of the following items, in sequence:
Format this command string as follows (punctuation is required where
shown):
dev:obj,dev:list,dev:cref/s:type=dev:source-1,...,dev:source-n/s:type
where: deftablefontspecstenpoint
The following command string calls for an assembly that uses one source file plus the system MACRO library to produce an object file BINF.OBJ and a listing. The listing goes directly to the line printer.
All output file specifications are optional. The system does not produce an output file unless the command string contains a specification for that file.
The system determines the file type of an output file specification by its position in the command string. Use commas in place of files you wish to omit. For example, to omit the object file, you must begin the command string with a comma. The following command produces a listing, including cross-reference tables, but not binary object files.
You need not include a comma after the final output file specification in the command string.
click here lists the default values for each file specification. defsubheadonefontspecsfourteenpointssbf presubheadonevskip30pt postsubheadonevskip18pt
Some assemblies need more symbol table space than available memory can ) contain. When this occurs the system automatically creates a temporary work file called WRK.TMP to provide extended symbol table space.
The default device for WRK.TMP is DK. To cause the system to assign a different device, enter the following command:
The dev parameter is the physical name of a file-structured device. The system assigns WRK.TMP to this device.
If possible, assign WF to the VM device. This can speed up the assembly process and save you some disk space.
At assembly time you may need to override certain MACRO directives appearing in the source programs. You may also need to direct MACRO--11 on the handling of certain files during assembly. You can satisfy these needs by including special options in the MACRO--11 command string in addition to the file specifications. click here lists the options and describes the effect of each.
The general format of the MACRO--11 command string is repeated below
for your convenience:
dev:obj,dev:list,dev:cref/s:type=dev:source-1,...,dev:source-n/s:type
The /M option affects only the particular source file specification to which it is directly appended in the command string.
Other options are unaffected by their placement in the command string. The /L option, for example, affects the listing file, regardless of where you place it in the command string.
The following section describes how to use the MACRO options. vskip4pt With two options, /L:type and /N:type, you can specify the content and format of assembler listings. With these options, you can also override at assembly time the arguments of .LIST and .NLIST directives in a source program.
Specifying the /N option with no argument causes the system to list only the symbol table, table of contents, and error messages. Specifying the /L option with no arguments causes the system to ignore .LIST and .NLIST directives that have no arguments. defsubheadonefontspecstenpointssbf presubheadonevskip24pt postsubheadonevskippostheadthreevskip deftablefontspecstenpoint normaltablerowvskip16pt
The following example command uses the /L and /N options. This command requests a listing of binary code throughout the assembly using the 132-column line-printer format, and suppresses the symbol-table listing.
click here shows an assembly listing of a small program. In this listing, most of the /L and /N arguments in the preceding table label the sections of the listing which they control. For example, the SEQ argument controls the appearance of the source-line sequence numbers.
Two options, /E:type and /D:type, allow you to enable or disable functions at assembly time, and thus influence the form and content of the binary object file. These functions can override .ENABLE and .DSABL directives in the source program.
The following table summarizes the acceptable /E and /D function arguments, their normal default status, and the functions they control.
For example, if you type the following commands the system assembles a file while treating columns 73 through 80 of each source line as commentary.
Because MACRO--11 is a two-pass assembler, you cannot read directly from any non-file-structured device. You must use PIP (or the keyboard monitor COPY command) to transfer input to a file-structured device before beginning the assembly.
Use either the function-control or listing-control option and arguments at
assembly time to override corresponding listing or function-control
directives in the source program. For example, assume that the source
program contains the following sequence:
.NLIST MEB
.
.(MACRO references)
.
.LIST MEB
In this example, you disable the listing of macro expansion binary code for some portion of the code and subsequently resume MEB listing. However, if you indicate /L:MEB in the assembly command string, the system ignores both the .NLIST MEB and the .LIST MEB directives. This enables MEB listing throughout the program. The /M option is meaningful only if appended to a source file specification. It designates its associated source file as a macro library.
If the command string does not include the standard system macro library SYSMAC.SML, the system automatically includes it as the first source file in the command string.
When the assembler encounters an .MCALL directive in the source code, it searches macro libraries according to their order of appearance in the command string. When it locates a macro record whose name matches that given in the .MCALL, it assembles the macro as indicated by that definition. Thus, if two or more macro libraries contain definitions of the same macro name, the macro library that appears rightmost in the command string takes precedence.
Consider the following command string:
Assume that each of the two macro libraries, ALIB and BLIB, contain a macro called .BIG, but with different definitions. Then, if source file XIZ contains a macro call .MCALL .BIG, the system includes the definition of .BIG in the program as it appears in the macro library BLIB.
Moreover, if macro library ALIB contains a definition of a macro called .READ, that definition of .READ overrides the standard .READ macro definition in SYSMAC.SML. A cross-reference (CREF) table lists all or a subset of the symbols in a source program, identifying the statements that define and use the symbols.
To obtain a CREF table you must include the /C:type option in the command string. Usually you include the /C:type option with the assembly listing file specification, though you can place it anywhere in the command string.
The /C option can have six arguments, each separated from one another by a colon. These arguments are alphabetically summarized as follows.
Note: Specifying /C with no argument is equivalent to specifying /C:S:M:E. That special case excepted, you must explicitly request each CREF section by including its arguments.You do not get a cross-reference file if you do not specify the /C option, even if you include a CREF file specification in the command string.
RT--11 places requested cross-reference tables after the MACRO assembly listing. Each table begins on a new page.
The following list describes the symbol contents of each of the six cross-reference tables. Each table begins on a page numbered to reference the table:
User-defined program symbols, beginning on page S-1.
These are labels used in the program and symbols defined by a direct assignment statement.
Register equate symbols, beginning on page R-1.
These normally include
R0, R1, R2, R3, R4, R5, SP, and PC, unless the REG function has
been disabled through a .DSABL REG directive or the /D:REG option. Also
included are any other symbols that are defined in the program by the
construct:
symbol = %n
where n represents the register number and has a value between 0 and 7.
MACRO symbols, beginning with page M-1.
These are the symbols defined by .MACRO and .MCALL directives.
Permanent symbols, beginning with page P-1.
These are all operation mnemonics and assembler directives.
Program sections, beginning with page C-1.
These are the names you specify as operands of .CSECT or .PSECT directives. Also included are the default program sections produced by the assembler, the blank p-sect, and the absolute p-sect, .ABS.
Errors, beginning with page E-1.
These are any errors, by error type, flagged by the assembler.
RT--11 displays symbols and also symbol values, control sections, and error codes, if applicable, beginning at the left margin of the page. References to each symbol are listed on the same line, left-to-right across the page. The system lists references in the form P-L, where P is the page in which the symbol, control section, or error code appears, and L is the line number on the page.
A number sign (#) next to a reference indicates a symbol definition. An asterisk (*) next to a reference indicates a destructive reference -- that is, an operation that alters the contents of the addressed location.
The Sample Cross-Reference Table on the next page lists all the CREF tables the assembler produces for the MACRO--11 program displayed in Sample Assembly Listing.
Note that these tables are combined onto one page. The page
breaks after each table have been deleted to save space.
wide
.MAIN. MACRO V05.5 Friday 25-Jan-90 11:08 Page S-1
Cross reference table (CREF V05.5)
.GLOBA 1-6
.TTYIN 1-9
ANSWER 1-20* 1-23#
BUFFER 1-8 1-14 1-24#
LF 1-1# 1-11
START 1-8# 1-17 1-25
SUBR1 1-6 1-15 1-16
SUBR2 1-6 1-18 1-19
.MAIN. MACRO V05.5 Friday 25-Jan-90 11:08 Page R-1
Cross reference table (CREF V05.5)
PC 1-15* 1-16* 1-18* 1-19*
R0 1-10 1-11 1-20
R2 1-8* 1-10* 1-13*
R3 1-14*
.MAIN. MACRO V05.5 Friday 25-Jan-90 11:08 Page M-1
Cross reference table (CREF V05.5)
.EXIT 1-2# 1-21
.TTYIN 1-2#
CALL 1-3# 1-15 1-18
.MAIN. MACRO V05.5 Friday 25-Jan-90 11:08 Page P-1
Cross reference table (CREF V05.5)
.BLKB 1-24
.BLKW 1-23
.CSECT 1-7
.END 1-25
.MACRO 1-3
.MCALL 1-2
BCS 1-17
BNE 1-12
CLRB 1-13
CMPB 1-11
EMT 1-21 1-22
JSR 1-15 1-16 1-18 1-19
MOV 1-8 1-14 1-20
MOVB 1-10
.MAIN. MACRO V05.5 Friday 25-Jan-90 11:08 Page C-1
Cross reference table (CREF V05.5)
0-0
. ABS. 0-0
PROG 1-7
.MAIN. MACRO V05.5 Friday 25-Jan-90 11:08 Page E-1
Cross reference table (CREF V05.5)
A 1-6 1-9 1-12
U 1-9 1-12
You specify a cross-reference listing by means of the /C option. When you do so the system creates a temporary work file whose default name is DK:CREF.TMP.
You can explicitly specify the file to use as the temporary work file by naming it as the third output file. The system then uses your file specification instead of DK:CREF.TMP and deletes it automatically after producing the CREF listing. The following command string causes the system to use RK2:TEMP.TMP as the temporary CREF file:
Note that you must still include the /C option to control the form and content of the listing. Your specification for a cross-reference file is ignored if the /C option is not also present in the command string.
Another way to assign an alternate device for the CREF.TMP file is to enter the following command prior to entering R MACRO:
This method is preferred if you intend to do several assemblies, because it relieves you from having to include the dev:cref specification in each command string. If you enter the ASSIGN dev: CF command, and later include a CREF specification in a command string, the specification in the command string prevails for that assembly only.
If you assign CF to a physical device, that device also becomes the default device for the LINK temporary file CREF.TMP created when you use the LINK/GLOBAL (/N) option.
If your command string does not include a CREF file specification, the system automatically generates a temporary file on device DK. If you need to have a device other than DK contain the temporary CREF file, you must include the DEV:CREF field in the command string.
If the listing device is magtape, load the handler for that device before issuing the command string, using the monitor LOAD command (see the click here for a description of that command).
The MACRO--11 system prints diagnostic error codes as the first character of a source line on which the assembler detects an error. This error code identifies the type of error; for example, a code of M indicates a multiple definition of a label. click here shows the error codes that might appear on an assembly listing. For detailed information on error code interpretation and debugging, see the click here.
click here lists the DCL MACRO command options that are equivalent to MACRO utility operations.
The first part of the table lists that part of the CSI MACRO command syntax that is equivalent to a DCL MACRO option. The rest of the table alphabetically lists all the MACRO options having DCL equivalents.
Note that the 1- and 3-letter type arguments to the utility options are the same arguments as those to the MACRO command qualifiers with three exceptions: