Digital PDFs

AA-KX10A-TC

October 1987

256 pages

Original

9.7MB

Document:	PDP-11 MACRO-11 Language Reference Manual 198805
Order Number:	AA-KX10A-TC
Revision:	0
Pages:	256
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsts_e/V09/7_MACRO_Programming/AA-KX10A-TC_RSTS_E_V9.5_PDP-11_MACRO-11_Language_Reference_Oct87.pdf

OCR Text

PDP-11 MACRO-11 Language
Reference Manual
Order Number AA-KX 1OA- TC

This manual describes how to use the MACRO-II relocatable assembler to develop PDP-II
assembly language programs. Although no prior knowledge of MACRO-II is required, you
should be familiar with the PDP-II processor addressing modes and instruction set. This
manual presents detailed descriptions of MACRO-II's features, including source and command
string control of assembly and listing functions, directives for conditional assembly and program
sectioning, and user-defined and system macro libraries. The chapters on operating procedures
were previously found in two separate manuals, the Macro-ll Language Reference Manual and
the IAS/RSX Macro-ll Reference Manual. This manual should be used with a system-specific
user's guide as wen as a Linker or a Task Builder manual.

Revision/Update Information:

This manual supersedes previous editions AA-V027ATC, published 1983, AA-S07SB-TC, published 1980,
AA-S07SA-TC, published 1977, and DEC-11-0IMRAB-D, published 1976.

Operating Systems:

lAS Version 3.2
MICRO/RSX Version 3.0
MICRO/RSTS Version 2.1
RSTSjE Version 9.S
RSX-11M Version 4.2
RSX-11M-PLUS Version 3.0
RT-ll VersionS.S
P lOS Version 3
VAX/VMS Version 4.4

Software:

MACRO-II Version S.S

digital equipment corporation
Imayn,ard, massachusetts

First Printing, August 1977
Revised, January 1980
Updated, December 1981
Revised, March 1983
Updated, May 1984
Updated, October 1985
Revised, October 1987
The information in this document is subject to change without notice and should not be construed as a
commitment by Digital Equipment Corporation.
Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document.
The software, if any, described in this document is furnished under a license and may be used or copied
only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of
software or equipment that is not supplied by Digital Equipment Corporation or its affiliated companies.
Copyright ©1977,1980,1981,1983,1984,1985,1987 by Digital Equipment Corporation.
All Rights Reserved.
Printed in U.S.A.
The READER'S COMMENTS form on the last page of this document requests the user's critical evaluation
to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
CTS-300
DECsystem-lO
DIBOL

P/OS
RSTS
VAX

DEC
DECSYSTEM-20
MASSBUS
Professional
RSX
VMS

DECmate
DECUS
MicroPDP-ll
Q-bus
RT
VT

DECnet
DECwriter
PDP
Rainbow
UNIBUS
Work Processor

~urnUD~DTM
ML-S685

Contents
Preface

Part II
Chapter 1
1.1
1.2

The MACRO-11 Assembler

Assembly Pass 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assembly Pass 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2

1-1
1-2

Source Program Format

Prograrnming Standards and Conventions
2.1
2.2
Statement Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .,
2.2.1
Label Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.2
Opera~or Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .,
2.2.3
Operand Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,
2.2.4
Comment Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,
2.3
Format Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-1
2-1
2-2
2-3
2-4
2-4
2-5

Part n
Chapter 3
3.1
3.1.1
3.1.2
3.1.3
3.2
3.2.1
3.2.2
3.3
3.4
3.5
3.6

3.7
3.8

Symbols and Expressions

(:haracter Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Separating and Delimiting Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invalid Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unary and Binary Operators . . . . . . . . . . . . . . . . . . . . . . . . -. . . . . . . . . . . . .
MACRO-11 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Perrrlanent Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
User-Defined and Macro Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Direct Assignment Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
I{egister Symbols . ., . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
l,ocal Symbols . . . , . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Current Location Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Numbers . . . . . . , . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
l'erms . . . . . . . . ., . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-1
3-2
3-3
3-3
3-5
3-5
3-5

3-7
3-8
3-10
3-11
3-13

3-14
iii

3.9

Expressions..................................................

Chapter 4

Relocation and Linking

Chapter 5

Addressing Modes

5.1
5.2
5.3
5.4
5.5
5.6
5.7
5.8
5.9
5.10
5.11
5.12
5.13
5.14

Register Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Register Deferred Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Autoincrement Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ".
Autoincrement Deferred Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ".
Autodecrement Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ".
Autodecrement Deferred Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ".
Index Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ".
Index Deferred Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,.
Immediate Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,.
Absolute Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,.
Relative Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Relative Deferred Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Branch Instruction Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,.
Using TRAP Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . "

3-14

5-3
5-3
5-4
5-4
5-4
5-4
5-5
5-5
5-6
5-6
5-7
5-8
5-8
5-9

Part III
Chapter 6

General Assembler Directives

6.1
Listing Control Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.LIST And .NLIST Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.1
.TITLE Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.2
6.1.3
.SBTTL Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.4
.IDENT Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.5
.PAGE Directive/Page Ejection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.6
.REM Directive/Begin Remark Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2
Function Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.ENABL and .DSABL Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.1
6.2.2
Cross-Reference Directives: .CROSS and .NOCROSS . . . . . . . . . . . . . . . . . . . . .
6.3
Data Storage Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.1
.BYTE Directive . . . . . . . . . . . . . . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . .
6.3.2
.WORD Directive . . . . . . . . . . . . . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . .
6.3.3
ASCII Conversion Characters . . . . . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . .
6.3.4
.ASCII Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.5
.ASCIZ Directive. . . . . . . . . . . . . . . . . . . . . . . . . . , . . . . . . . . . . . . . . . . . .
6.3.6
.RAD50 Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . " . . . . . ..
6.3.7
Temporary Radix-50 Control Operator . . . . . . . . ... " . . . . . . . . . . . . . . . . ..
iv

6-3
6-6
6-10
6-11
6-12
6-12
6-13
6-13
6-14
6-16
6-17
6-17
6-18
6-19
6-20
6-21
6-22
6-24

6.3.8
.PACKED Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24
Radix and Numeric Control Facilities . . . . . . . . . . . . . . . .
6.4
6-26
6.4.1
Radix Control and Unary Control Operators . . . . . . . . . .
6-26
6.4.1.1
.RADIX Directive . . . . . . . . . . . . . . . . . . . . . . . . . .
6-26
6.4.1.2
Temporary Radix Control Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 6-27
6.4.2
Numeric Directives and Unary Control Operators. . . . . . . . . . . . . . . . . . . . ... . 6-28
6.4.2.1
One's Complement Operator: AC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29
6.4.2.2
Floating-Point Storage Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
6.4.2.3
Floating-Point Operator: AF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
Location Counter Control Directives .
6.5
6-31
.EVEN Directive . . . . . . . .
6.5.1
6-31
6.5.2
.ODD Directive . . . . . . . . .
6-32
6.5.3
.BLKB and .BLKW Directives
6-32
.LIMIT Directive . . . . . . . .
6.5.4
6-33
Terminating Directive: .END Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34
6.6
6.7
Prograrn Sectioning Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34
6.7.1
.PSECT Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6-35
6.7.1.1
Crea ting Program Sections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6-38
6.7.1.2
. . . . . . . . . . . . .
Code or Data Sharing. . . . . . . . . . . . . . . . .
6-40
Memory Allocation Considerations . . . . . .
. . . . . . . . . . . . . . . . . . 6-40
6.7.1.3
6.7.2
.ASECT and .CSECT Directives . .. . . . . . .
. .................. .
6-40
6.7.3
.SAVE Directive . . . . . . . . . . . . . .
6-41
.RESTORE Directive . . . . . . . . . . .
6.7.4
6-41
Symbol Control Directives . . . . . . . . . . .... .
6.8
6-43
6.8.1
.GLOBL Directive . . . . . . . . . . . . . . . . . . .
6-43
6.8.2
'6-44
.WEAK Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.9
Conditional Assembly Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 6-45
6.9.1
Conditional Assembly Block Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-45
6.9.2
Subconditional Assembly Block Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48
6.9.3
Immediate Conditional Assembly Directive . .
. . . . . . . . . . . . . . . . . .
6-50
6.10 File Control Directives . . . . . . . . . . . .
6-51
.LIBRARY Directive . . . . . . . . . . . .
6.10.1
6-51
6.10.2 .INCLUDE Directive . . . . . . . . . . .
6-52

Part IIV
Chapter 7

Macro Directives

7.1
Defining Macros . . . . . . . . .
7.1.1
.MACRO Directive .... .
7.1.2
.ENDM Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.MEXIT Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.1.3
7.1.4
MACRO Definition Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-2
7-2
7-3
7-4
7-4

7.2
7.3
7.3.1
7.3.2
7.3.3
7.3.4
7.3.5
7.3.6
7.3.7
7.4
7.4.1
7.4.2
7.4.3
7.5
7.6
7.6.1
7.6.2
7.7
7.8
7.9

Calling Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Arguments in Macro Definitions and Macro Calls . . . . . . . . . . . . . . . . . . . . . . . . .
Macro Nesting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Special Characters in Macro Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Passing Numeric Arguments as Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Number of Arguments in Macro Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Local Symbols Automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Keyword Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Concatenation of Macro Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Macro Attribute Directives: .NARC, .NCHR, and .NTYPE . , . . . . . . . . . . . . . . . . . .
.NARC Directive. . . . . . . . . . . . . . . . . . . . . . . . . . .' . . . . . . . . . . . . . .... .
.NCHR Directive. . . . . . . . . . . . . . . . . . . . . . . . ...' . . . . . . . . . . . . . . . . . .
.NTYPE Directive . . . . . . . . . . . . . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . .
.ERROR and .PRINT Directives . . . . . . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . .
Indefinite Repeat Block Directives: .IRP and .IRPC ..... " . . . . . . . . . . . . . . . . . .
.IRP Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . .
.IRPC Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . .
Repeat Block Directive: .REPT, .ENDR . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . .
Macro Library Directive: .MCALL . . . . . . . . . . . . . . . . " . . . . . . . . . . . . . . ... .
Macro Deletion Directive: .MDELETE . . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . .

Chapter 8

IAS/RSX-11 M/RSX-11 M-PLUS Operating Procedures

8.1
RSX-IIMjRSX-IIM-PLUS Operating Procedures . . . . . . '. . . . . . . . . . . . . . . . . . .
Running MACRO-ll Under RSX~llMjRSX-IIM-PLUS . . . . . . . . . . . . . . . . . . .
8.1.1
8.1.1.1
Direct MACRO-ll Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.1.2
Single Assembly . . . . . . . . . . . .' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.1.3
Install, Run Immediately, and Remove on Exit . . . . . . . . . . . . . . . . . . . . . . . .
Indirect Command Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.1.4
8.1.2
Default RSX-ll File Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.3
MCR Command String Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DCL Operating Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.4
8.1.5
MACRO-ll Command String Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2
lAS MACRO-ll Operating Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running MACRO-ll Under lAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.1
lAS Command String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2
8.2.3
lAS Indirect Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.4
lAS Command String Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3
Cross-Reference Processor (CREF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IASjRSX-IIMjRSX-IIM-PLUS File Specification . . . . . . . . . . . . . . . . . . . . . . . . .
8.4
MACRO-ll Error Messages Under IASjRSX-IIMjRSX-IIM-PLUS . . . . . . . . . . . . .
8.5

7-5
7-5
7-7
7-8
7-8
7-9
7-9
7-11
7-12
7-13
7-13
7-15
7-16
7-18
7-19
7-19
7-20
7-21
7-22
7-23

8-1
8-2
8-2
8-2
8-3
8-3
8-4
8-4
8-7
8-11
8-11
8-11
8-12
8-13
8-14
8-14
8-17
8-18

Chapter 9

RSTS/RT -11 Operating Procedures

9.1
MACRO-II Under RSTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RT-l1 Through RSTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.1.1
RSX Through RSTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.1.2
Running MACRO-II Under RT -11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .
9.2
RT-l1 Command String (CSI) Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.2.1
RT-l1 CSI Comnland Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.2.2
RT -11 Digital Command Language (DCL) Format . . . . . . . . . . . . . . . . . . . . . . .
9.2.3
Cross-Reference (CREF) Table Generation Option . . . . . . . . . . . . . . . . . . . . . . . . .
9.3
Obtaining a Cross-Reference Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.3.1
Handling Cross-Reference Table Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.3.2
MACRO-II Error Messages Under RT -11 . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.3.3

Appendix A
A.1
A.2
A.3

B.1
B.2
B.3

A-I
A-8
A-9

MACRO-11 Assembly Language and Assembler Directives

Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Summary of Address Mode Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Assembler Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .,

Appendix C
C.1
C.2
C.3
C.4

MACRO-11 Character Sets

DEC Multinational Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Radix-50 Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
DEC Multinational Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..

Appendix B

9-1
9-1
9-1
9-2
9-2
9-4
9-5
9-6
9-6
9-7
9-8

B-1
B-2
B-3

Permanent Symbol Table

()p Codes . . . . . . '. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Commercial Instruction Set (CIS) Op Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,
Floating-Point Processor Op Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
MACRO-II Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,

Appendix D

Error Messages

Appendix E

Sample Coding Standard

l.ine Form.at .... " . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.l
C:omments . . . . . .' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.2
Naming Standards .' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.3
Registers . . . . . .' . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.3.1
Processor
Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.3.2
Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.3.3
Symbol Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.3.3.1
Local Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E.3.3.2

C-1
C-5
C-7
C-9

E-l
E-1
E-2
E-2
E-2
E-2
E-3
E-3

vii

Global Symbols. . . . . . . . . . . . . . . .
E.3.3.3
Macro Names (RSX-ll) .
E.3.3.4
General Symbols
E.3.3.S
Program Modules . .
E.4
The Module Preface
E.4.1
The Module
E.4.2
Module Example
E.4.3
Modularity
E.4.4
Calling Conventions (Inter-Module/lntra-Module) o.
E.4.4.1
Exiting
E.4.4.2
Success/Failure Indication
E.4.4.3
Module Checking Routines
E.4.4.4
Code Format .
E.S
Program Flow
E.S.l
Common
Exits
E.S.2
Code with Interrupts Inhibited
E.S.3
Code in System State.
E.S.4
E.6 Instruction Usage . . . . .
Forbidden Instructions
E.6.1
Conditional Branches . . . . . . .
E.6.2
Program Source Files
E.7
PDP-II Version Number Standard
E.B
Displaying the Version Identifier . . . . . . . .
E.B.l
Use of the Version Number in the Program .....
E.B.2
0

•

••

•

0"'-

• •-

••••

•••

•

0.,

•

••

•

••

•

••

•

•••

••

•

••

•

••••

••

•

••

•

•••

••••

•••

•••••

• • • • • • •

•

••••

•

•••

•

••••

• • • • • • • •

••

•

•••

•

"• •

•

••••

•••

•

•••

••

••••

••

• • • • • • • •

•••

••••

•

••••

•

E-4
E-4
E-4
E-4
E-4
E-4

E-6
E-B
E-B

E-9
E-9
E-9
E-9
E-9
E-I0
E-12
E-12
E-12
E-12
E-13
E-14
E-14
E-IS
E-IS

Appendix F Allocating Virtual Memory
F.l
F.2
F.3

General Hints and Space Saving Guidelines .....
Macro Definitions and Expansions .
Operational Techniques .....
0

Appendix G
Gol
G.2

•

••••

•

••••

•

• • • • • • • • • •

• • • • • • •

•

••••

•

••

• • • • • • • • • • • • • • • •

••

F-l
F-2
F-3

Writing Position-Independent Code

Introduction to Position-Independent Code ..
Examples
0

••••

•

••••

•

• • • • • • •

•

••

•

•••

•••••

••

G-l
G-2

Appendix H

Sample Assembly and Cross-Reference Listing

Appendix I

Obsolete MACRO-11 Directives, Syntax, and Command Line Options

1.1
1.2

viii

Obsolete Directives and Syntax .
Obsolete Command Line Option . . . . . . .
0

•

••

•

•••

•

1-1
1-1

Appendix J
J.1
J.1.1
J.1.2
J.1.3
J.1.4
J.1.S
J.1.6
J.2
J.2.1
J.2.2
J.2.3
J.2.4
J.2.S
J.2.6
J.3
J.3.1
J.3.2
J.3.3
J.3.4
J.3.5
J.3.6

Release Notes

Changes-All Versions of MACRO-II .... " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.S Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.4 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.3 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.2 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.1 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.O Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changes-MACRO-l1/RSX Version Only. . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
VS.S Update C~anges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.4 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.3 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.2 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.1 Update Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.O Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changes-MACRO-Jll/RT-11 Version Only ".. . . . . . . . . . . . . . . . . . . . . . . . ..
VS.S Update Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.4 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.3 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
VS.2 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .
V5.1 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . ".
V5.0 Update Changes . . . . . . . . . . . . . " . . . . . . . . . . . . . . . . . . . . . . . . . . .

J-1
J-1
J-2
J-2
J-3
J-3
J-4
J-S
J-S
J-S
J-6
J-6
J-6
J-6
J-6
J-6
J-7
J-7
J-7
J-7
J-7

Index
Figures
3-1
6-1
6~2

6-3
6-4
6-S
6-6
6-7

6-8
7-1
7-2
7-3
7-4

8-1
A-I
G-l
G-2

Assembly Listing Showing Local Symbol Block . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Example of Line Printer Assembly Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6-4
Example of Terminal Assembly Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6-5
Listing Produced with Listing Control Directives . . . . . . . . . . . . . . . . . . . . . . . . . .
6-9
Assembly Listing Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
Example of .ENABL and .DSABL Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16
Example of the .PACKED Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 6-25
Example of .BLKB and .BLKW Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33
Example of .sAVE and .RESTORE Directives . . . . . . . . . . . . . . . . . . . . . . . . . . .. 6-42
Example of .NARG Directive . . . . . . . . . . . . . . . . . . . . . . . . . . " . . . . . . . . . . . 7-14
Example of .NCHR Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 7-16
Example of .NTYPE Directive in Macro Definition . . . . . . . . . . . . . . . . . . . . . . . .. 7-17
Example of .IRP and .IRPC Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 7-21
Sample lAS CREF Listing . . . . . . . . . . . . . . . '. . . . . . . . . . . . . . . . . . . . . . . . . . 8-16
DEC Multinational Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
Example of Position-Dependent Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-3
Example of Position-Independent Code . . . . . . . . . . . . . . . . . ~ . . . . . . . . . . . . . . G-4

Tables
3-1

3-2
3-3
3-4
3-5
5-1

5-2
5-3
6-1
6-2
6-3
6-4
6-5
6-6

6-7
7-1
8-1
8-2
8-3
8-4
9-1
9-2
9-3
A-I

A-2
A-3

1-1

Special Characters Used in MACRO-II . .
. . . . . . .
. . . . . . . . . . . . . .
Valid Separating Characters . .
. . . . . . ...
Valid Argument Delimiters. . . . . . . . . . . . . . . . . . . . .
. .... .
Valid Unary Operators . . . . . . . . . . . . . . . .
. .... .
. ........... .
Valid Binary Operators . . . . . . . . . .
Symbols Used in Chapter 5 . . . . . . . . . . . . .
. .......... .
Addressing Modes ... . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . .
Instruction Differences Among PDP-II Processors. . . . . . . . . . . . . . . . . . . . . . .. .
Directives in Chapter 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Symbolic Arguments of Listing Control Directives . . . . . . . . . . . . . . . . . . . . . . .. .
Symbolic Arguments of Function Control Directives . . . . . . . . . . . . . . . . . . . . . . . .
Symbolic Arguments of .PSECT Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Program Section Default Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Valid Condition Tests for Conditional Assembly Directives . . . . . . . . . . . . . . . ....
Subconditional Assembly Block Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Directives in Chapter 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RSX-ll File Specification Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RSX-ll File Specification Switches for MACRO-II . . . . . . . . . .
RSX -11 DCL Command Qualifiers . . . . . . . . . . . . . . . . . . . . .
RSX-ll DCL Parameter Qualifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RT -11 Default File Specification Values . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Specification Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IC Option Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEC Multinational Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Radix-50 Character Set . . . . . . . . .
Radix-50 Character Equivalents ... .
Old and New Directives and Syntax.

3-1
3-3
3-3

3-4
3-4
5-1

5-2
5-3
6-1
6-7
6-14
6-35
6-41
6-46
6-48
7-1
8-4
8-6
8-7
8-10
9-2
9-4
9-7
A-I

A-8
A-8
1-1

Preface
Manual Objectives and Reader Assumptions
This manual is intended to enable you to write programs in the MACRO-II assembly
language.
No prior knowledge of the MACRO-It Relocatable Assembler is assumed, but you
should be familiar with PDP-II processors and related terminology, as presented
in the PDP-ll Processor Handbook. You are also encouraged to become familiar
with the linking process, as presented in the applicable system manual (see the
Associated Doculnents section below), because linking is necessary for the development
of executable programs.
If a terminal is available, we suggest that you try some of the examples in the manual
or write a few simple programs that illustrate the concepts covered. Even experienced
programmers find that working with a simple program helps them to understand a
confusing feature of a new language.

The examples in this manual were done on an RT -11 system. You can also use
MACRO-ll on lAS, RSX-llM, RSX-l1M-PLUS and RSTS systems (see Part IV for
information about operating procedures).
All references to RSX-llM also apply to RSX-llM-PLUS with the exception of those
in Chapter 8, which deals with each system individually.

Document Structure
This manual has four parts and eight appendixes.
Part I introduces MACRO-ll:
•

Chapter 1 lists the key features of MACRO-ll.

•

Chapter 2 discusses the advantages of following programming standards and
conventions and describes the format used in coding MACRO-ll source programs.

Part II presents general information essential to programming with the MACRO-ll
assembly language:
•

Chapter 3 lists the character set and describes the symbols, terms, and expressions
that form the elements of MACRO-1l instructions.

•

Chapter 4 describes MACRO-ll output and presents concepts essential to the
proper relocation and linking of object modules.

•

Chapter 5 describes how data stored in memory can be accessed and manipulated
by using the addressing modes recognized by the PDP-ll hardware.

Part III describes the MACRO-II directives that control the processing of source
statements during assembly:
•

Chapter 6 discusses directives used for generalized MACRO-II functions.

•

Chapter 7 discusses directives used in the definition and expansion of macros.

Part IV presents the operating procedures for assembling MACRO-II programs:
•

Chapter 8 covers the lAS, RSX-IIM, and RSX-11M-PLUS systems.

•

Chapter 9 covers the RSTS jRT-11 systems.

Appendix A lists the ASCII and Radix-50 character sets used in MACRO-II programs.
Appendix B lists the special characters recognized by MACRO-II, summarizes the
syntax of the various addressing modes used in PDP-II processors, and briefly
describes the MACRO-II directives in alphabetical order.
Appendix C lists alphabetically the permanent symbols that have been defined for use
with MACRO-II.
Appendix D lists alphabetically the error codes produced by MACRO-II to identify
'
various types of errors detected during the assembly process.
Appendix E contains a coding standard that is recon1mended practice in preparing
MACRO-II programs.
Appendix F discusses several methods of conserving dynamic memory space for users
of small systems who may experience difficulty in assembling MACRO-II programs.
Appendix G is a discussion of position-independent code (PIC).
Appendix H contains an assembly and cross-reference listing.
Appendix I contains obsolete MACRO-II directives, syntax, and command line options.
Appendix J describes the differences from the last release of MACRO-II.

Associated Documents
For descriptions of documents associated with this manual, refer to the applicable
documentation directory listed below:

lAS Documentation Directory
RSX-11M-PLUS Information Directory and Master Index
RSX-11MjRSX-11S Information Directory and Index
Guide to RT-11 Documentation
RSTS jE Documentation Directory

Conventions
The color red is used in command string examples to indicate user input.
The term printing characters includes all characters that display or print a symbol.

xii

The tenn nonprinting characters includes all characters other than those defined as
printing characters. It includes space, horizontal and vertical tab, carriage return,
line feed, and form feed, even though those characters cause cursor or print head
movement.
The symbols defined below are used throughout this manual.
Symbol

Definition

[]

Brackets indicate that the enclosed argument is optional.
Ellipsis indicates optional continuation of an argument list in the form
of the last specified argument.

UPPERCASE
CHARACTERS

Uppercase characters indicate elements of the language that must be
used exactly as shown.

lowercase
characters

Lowercase characters indicate elements of the language that are supplied
by the programmer.

Subscripts

Subscripts indicate the radix of a number. For example, 100 8 indicates
100, base 8.

(base)

The symbol (base) indicates the radix of numbers in code examples.
For example, 100 (octal) indicates that 100 is an octal value, while
100(decimal) indicates a decimal value.

ICTRL/~ or "x

ICTRL/xl signifies a control character,

generated by simultaneously

pressing the CTRL key and the x key.
CTRL characters are sometimes represented in command line examples
by "x; do not confuse this representation of CTRL characters with
MACRO-II unary operators such as "B, "D, "0, and "R (see
Section 6.4.1.2).

xiii

Part I

Chapter 2

Source Program Format
2.1 Programming Standards and Conventions
Programming standards and conventions allow code written by a person (or group)
to be easily understood by another person or group. These standards also make the
program easier to:

•

Plan

•
•
•

Comprehend
Test

•

Convert

M:odify

The actual standard used must meet local user requirements. A sample coding standard
is provided in Appendix E. Used by DIGITAL and its users, this coding example
simplifies both communications and the continuing task of software maintenance and
improvement.

2.2 Statement Format
A source program is composed of assembly-language statements. Each statement must
be completed on one line. Although a line can contain 132 10 characters (a longer line
causes an error (L) in the assembly listing), a line of 80 10 characters is recommended
because of constraints imposed by listing format and terminal line size. Blank lines,
although valid, have no significance in the source program.
A MACRO-II statement may have as many as four fields. These fields are identified
by their order within the statement and/or by the separating characters between the
fields. The general format of a MACRO-II statement is:
Label:

Operator Operand

;Commellt(s)

All the fields are optional, although the operator and operand fields are interdependent;
when both operator and operand fields are present in a source statement, each field is
evaluated by MACRO-II in the context of the other.
A statement can contain an operator and no operand, but the reverse is not true.
A statelnent containing an operand with no operator is invalid and is interpreted by
MACRO-II during assembly as an implicit. WORD directive (see Section 6.3.2).
MACRO-II interprets and processes source program statements one by one. Each
statelnent causes MACRO-II either to perform a specified assembly process or to
generate one or lnore binary instructions or data words.

Source Program Format

2-1

2.2.1 Label Field
A label is a user-defined symbol which is assigned the value of the current location
counter and entered into the user-defined symbol table, The current location counter
is used by MACRO-II to assign memory addresses to the source program statements
as they are encountered during the assembly process. Thus, a label is a means of
symbolically referring to a specific statement.
When a program section is absolute, the value of the current location counter is
absolute; its value references an absolute virtual memory address, such as location
1100 s . Similarly, when a program section is reloca.table, the value of the current
location counter is relocatable; a relocation bias calculated at link time is added to the
apparent value of the current location counter to establish its effective absolute virtual
address at execution time. (For a discussion of progranl sections and their attributes,
see Section 6.7.)
If present, a label must be the first field in a source statement and must be terminated
by a colon (:). For example, if the value of the current location counter is absolute
1100 s ' the statement:
ABCD:

MOV

A,B

assigns the value 1100 s to the label ABCD. If the location counter value were relocatable,
the final value of ABCD would be 1100s+K, where K represents the relocation bias of
the program section, as calculated by the Task Builder or Linker at link time.
You can assign multiple labels to the same location by putting them on successive
lines. For example, the statements:
ABC:
$DD:
A7.7:

MOV

A,B

assign the same value to all three labels. This method of assigning multiple labels is
preferred, because positioning the fields consistently within the source program makes
the program easier to read (see Section 2.3).
More than one label can appear also within a single label field. Each label so specified
is assigned the same address value. For example, if the value of the current location
counter is 1100 s , the multiple labels in the following statement are each assigned the
value 1100 s :
ABC:

$DD:

A7 . 7 :

MOV

A, B

However, this method of assigning multiple labels to the same location is more difficult
to read and is not recommended.
A double colon (::) defines the label as a global symbol. For example, the statement:
ABCD::

MOV

A,B

establishes the label ABCD as a global symbol. A global symbol can be referenced from
an object module other than the module in which the global symbol is defined (see
Section 6.8). References from other modules to a global symbol are resolved when the
modules are linked as a composite executable image.

2-2 PDP-ll MACRO-ll Language Reference Manual

Chapter 1

The MACRO-11 Assembler
MACRO-II provides the following features:
•

Source and command string control of assembly functions

•

Device and filename specifications for input and output files

•

Error listing on command output device

•

Alphabetized, formatted symbol table listing; optional cross-reference listing of
symbols

•

Relocatable object modules

•

Global symbols for linking object modules

•

Conditional assembly directives

•

Program sectioning directives

•

User-defined macros and macro libraries

•

Comprehensive system macro library

•

Extensive source and command string control of listing functions

MACRO-II assembles one or more source files containing MACRO-II statements
into a single relocatable binary object file. The output of MACRO-II consists of a
binary object file and a listing file containing the table of contents, the assembly listing,
and the symbol table. An optional cross-reference listing of symbols and macros is
available. A sample assembly listing is provided in Appendix H.

1 . 1 Assembly Pass 1
During pass I, NIACRO-ll locates and reads all required macros from libraries, builds
symbol tables and program section tables for the program, and performs a rudimentary
assembly of each source statement.
In the first step of assembly pass I, MACRO-II initializes all the impure areas (areas
containing data) that will be used internally for the assembly process. These areas
include all dynarnic storage and buffer areas used as file storage regions. MACRO-II
then calls a system subroutine which transfers a command line into memory. This
comrnand line contains the specifications of all files to be used during assembly. After
scanning the cOn'lmand line for proper syntax, MACRO-II opens the specified output
files. These files are opened to determine if valid output file specifications have been
passed in the cOlnmand line.

The MACRO-l1 Assembler

1-1

MACRO-11 then initiates a routine which reads source lines from the input file. If
no input file is open, as is the case at the beginning of assembly, MACRO-11 opens
the next input file specified in the command line and starts assembling the source
statements. MACRO-11 first determines the length of the instructions, then assembles
them according to length as one word, two words, or three words.
At the end of assembly ,pass 1, MACRO-11 reopens the output files described above.
Such information as the object module name, the program version number, and the
global symbol directory (GSD) for each program section are written to the object file
to be used later in linking the object modules. After \vriting out the GSD for a given
program section, MACRO-11 scans through the symbol tables to find all the global
symbols that are bound to that particular program section. MACRO-11 then writes
out GSD records to the object file for these symbols. This process is done for each
program section.

1.2 Assembly Pass 2
On pass 2 MACRO-11 writes the object records to the binary output file. MACRO-11
also generates the assembly listing and the symbol table listing for the program, plus
a cross-reference table if one was requested.
Basically, assembly pass 2 consists of the same steps performed in assembly pass 1,
except that all source statements containing MACRO-I1-detected errors are flagged
with an error code as the assembly listing file is created. The object file that is
created as the final consequence of pass 2 contains all the object records, together with
relocation records that hold the information necessary for linking the object file.
The information in the object file, when passed to the Task Builder or Linker, enables
the global symbols in the object modules to be associated with absolute or virtual
memory addresses, thereby forming an executable body of code.
You may want to become familiar with the macro object file format and description,
although you do not need to know the format to use MACRO-I1 successfully.
This information is presented in the applicable system manual (see the Associated
Documents section in the Preface).

1-2 PDP-ll MACRO-ll Language Reference Manual

The valid characters for defining labels are:

•
•

A through Z

•

Period (.)

•

Dollar Sign ($)

o through 9

NOTE
By convention, the dollar sign ($) and period (.) are
reserved for use in defining DIGITAL system software
sYlnbols. Therefore these characters should not be used
in defining labels in MACRO-II source programs.
A label can be any length; however, only the first six characters are significant and,
therefore, must be unique among all the labels in the source program. An error code
(M) is generated in the assembly listing if the first six characters in two or more labels
are the same.
A symbol used as a label must not be redefined within the source program. If the
symbol is redefined, a label with a multiple definition results, causing MACRO-II to
generate an error code (M) in the assembly listing. Furthermore, any statement in the
source program 'which references a multi-defined label generates an error code (D) in
the assembly listing.

2.2.2 Operator Field
The operator field specifies the action to be performed. It can consist of an instruction
mnemonic (op code), an assembler directive, or a macro call. Chapters 6 and 7 describe
these three types of operators.
When the operator is an instruction mnemonic, a machine instruction is generated and
MACRO-II evaluates the addresses of the operands which follow. When the operator
is a directive, MACRO-II performs certain control actions or processing operations
during the assen1bly of the source program. When the operator is a macro call,
MACRO-II inserts the code generated by the macro expansion.
Leading and trailing spaces or tabs in the operator field have no significance; such
characters serve only to separate the operator field from the preceding and following
fields.
An operator is terminated by a tab, space, or any non-Radix-SO character,l as in the
following examples:
MOV

(gA, B

; The tab terminates the operator MOV.

MOV @A,B

;The space terminates the operator MOV.

MOV@A,B

;The @ character terminates the operator MOV.

1 Section A.2 contains a table of Radix-50 characters.

Source Program Format

2-3

Although the statements above are all equivalent in function, the first statement is
the recommended form because it is the most readable and conforms to MACRO-II
coding conventions.

2.2.3 Operand Field
When the operator is an instruction mnemonic (op code), the operand field contains
program variables that are to be evaluated/manipulated by the operator. The operand
field can also supply arguments to MACRO-II directives and macro calls, as described
in Chapters 6 and 7, respectively.
Operands can be expressions or symbols, depending on the operator. :Multiple
expressions used in the operand field of a MACRO-II statement must be separated
by a comma; multiple symbols similarly used must be delimited by a valid separator
(a comma, tab, and/or space). An operand should be preceded by an operator field;
if it is not, the statement is treated by MACRO-II as an implicit . WORD directive (see
Section 6.3.2).
When the operator field contains an op code, associated operands are always
expressions, as shown in the following statement:
MOV

RO,A+2(Rl)

On the other hand, when the operator field contains a MACRO-II directive or a macro
call, associated operands are normally symbols, as shown in the following statement.
Assume . COMPR is the name of a user-defined macro:
.COMPR ALPHA SYM1,SYM2

Refer to the description of each MACRO-II directive (Chapter 7) to determine the
type and number of operands required in issuing the directive.
The operand field is terminated by a semicolon when the field is followed by a
comment. For example, in the following statement:
LABEL:

MOV

A,B

;Comment field

the tab between MOV and A terminates the operator field and defines the beginning of
the operand field, a comma separates the operands A and B, and a semicolon terminates
the operand field and defines the beginning of the comment field. When no comment
field follows, the operand field is terminated by "the end of the source line.

2.2.4 Comment Field
The comment field normally begins in column 33 and extends through the end of
the line, although comments can also be entirely separate lines within the program.
This field is optional and can contain any 7-bit ASCII or 8-bit DEC Multinational
printing characters plus space and horizontal tab. All other characters appearing in the
comment field, even special characters reserved for use in MACRO-II, are checked
only for ASCII validity and then included in the assembly listing as they appear in
the source text.
Comment fields must begin with a semicolon (;). When a lengthy comment extends
beyond the end of the source line (column 80), the comment can be continued on the

2-4 PDP-ll MACRD-ll Language Reference Manual

following line. The continued comment must be preceded by another semicolon. For
readability the continued comment can be indented to begin in the same column as
the start of the comment on the previous line.
Comments do not affect assembly processing or program execution.
However,
comrr\ents are necessary in source listings for later analysis, debugging, or
documenta tion purposes.

2.3 Format Control
Horizontal formatting of the source program is controlled by the space and tab
characters. These characters have no effect on the assembly process unless they
are embedded within a symbol, number, or ASCII text string, or unless they are used
as the operator field terminator. Thus, space and tab characters can be used to make
the source program orderly and readable.
DIGITAL's standard source line format is shown below:
•

Label-begins in column 1

•

Operator-begins in column 9

•

Operands-begin in column 17

•

Comments-begin in column 33

These formatting conventions are not mandatory; free-field coding is permissible.
However, note the increased readability after formatting in the example beluw:
REGTST:BIT#MASK,VALUE;COMPARES BITS IN OPERANDS.
1
9
REGTST: BIT

17
#MASK , VALUE

33
(columns)
;Compares bits in operands.

Page formatting and assembly listing considerations are discussed in Chapter 6 in the
context of MACRO-II directives that can be specified to accomplish desired formatting
operations. Appendix E contains a sample coding standard.

Source Program Format

2-5

Part II

Chapter 3

Symbols and Expressions
This chapter describes the components of MACRO-II instructions: the character set,
the conventions for constructing symbols, and the use of numbers, operators, terms,
and expressions.

3.1 C:haracter Set
The following characters are valid in MACRO-II source programs:
4.

The letters A through Z. Both uppercase and lowercase letters are acceptable,
although lowercase can be forced to uppercase if desired (see Section 6.2.1,
.DSABL LC).

Characters in the DEC Multinational character set (MCS). Appendix A contains
a table showing the MCS. Specific support for the MCS is included with the
description of each directive.

The digits 0 through 9.

The characters period (.) and dollar sign ($). These characters are reserved for
use in Digital Equipment Corporation system program symbols .

. 1.

The special characters listed in Table 3-1.

Table 3-1:

Special Characters Used in MACRO-11

Character

Designation

Function

Colon

Label terminator

Double colon

Label terminator; defines the label as a global label

Equal sign

Direct assignment operator and macro keyword
Indicator

Double equal sign

Direct assignment operator; defines the symbol as
a global symbol

Equal sign colon

Direct assignment operator; macro keyword
indicator; causes error (M) in listing if an attempt
is made to change the value of the symbol

Double equal sign colon

Direct assignment operator; defines the symbol as
a global symbol; causes error (M) in listing if an
attempt is made to change the value of the symbol

Percent sign

Symbols and Expressions

3-1

Table 3-1 (Cont.):

Special Characters Used in MACRO-11

Designation

Function

Horizontal tab

Item or field terminator

Space

Item or field terminator

Number sign

Immedia te expression indica tor

At sign

Deferred addressing indicator

Left parenthesis

Initial register indicator

Right parenthesis

Terminal register indicator

Period

Current location counter

Comma

Operand field separator

Semicolon

Comment field indicator

Character

<
>

Left angle bracket

Initial argument or expression indicator

Right angle bracket

Terminal argument or expression indicator

Plus sign

Unary plus, arithmetic addition operator,
autoincrement indicator

Minus sign

Unary minus, arithmetic subtraction operator, or
auto decrement indicator

lie

Asterisk

Arithmetic multiplication operator

Slash

Arithmetic division operator

Ampersand

Logical AND opera tor

Exclamation point

Logical inclusive OR operator

Double quote

Double ASCII character indicator

Single quote

Single ASCII character indicator or concatenation
indicator

Circumflex

Universal unary operator or argument indicator

Backslash

Macro call nunle:ric argument indicator

3.1.1 Separating and Delimiting Characters
Valid separating characters and valid argument delimiters are defined in Table 3-2 and
Table 3-3, respectively.

3-2 PDP-ll MACRO-ll Language Reference Manual

Table 3-2: Valid Separating Characters
Character

Definition

Space

One or more
and/or tabs

Usage

spaces

Comma

A space is a valid separator between instruction
fields and between symbolic arguments within
the operand field. Spaces within expressions are
ignored (see Section 3.9).
A comma is a valid separator between symbolic
arguments within the operand field. Multiple
expressions used in the operand field must be
separated by a comma.

3.1.2 Invalid Characters
A character is invalid for one of two reasons:
•

If a character is not an element of the recognized MACRO-11 character set, it is
replaced in the listing by a question mark, and an error code (I) is printed in the
assembly listing. The exception to this is an embedded null which, when detected,
is ignored.

•

If a valid MACRO-11 character is used in a source statement with invalid or
questionable syntax, an error code (Q) is printed in the assembly listing.

Table 3-3: Valid Argument Delimiters
Character

Definition

Usage

< ... ::>

Paired angle brackets

Paired angle brackets can be used
anywhere in a program to enclose an
expression for treatment as a single
term. Paired angle brackets are also
used to enclose a macro argument,
particularly when that argument
contains separating characters (see
Section 7.3).

"x ... x

Circumflex (unary operator) construction, where the circumflex is followed
by an argument that is bracketed by
any paired printing characters (x).

This construction is equivalent in
function to the paired angle brackets
described above and is generally used
only where the argument itself contains
angle brackets.

3.1.3 Unary and Binary Operators
Table 3-4 describes valid MACRO-11 unary operators. Unary operators are used
in connection with single terms (arguments or operands) to indicate an action to be
performed on tha.t term during assembly" Because a term preceded by a unary operator
is considered to contain that operator, a term so specified can be used alone or as an
element of an expression.

Symbols and Expressions

3-3

Table 3-4: Valid Unary Operators
Unary
Operator

Name

Example

Explanation

Plus sign

Ignored; equivalent to the value of
A

Minus sign

-A

Produces the negative
complement) value of A

Circumflex, universal unary
operator;
this usage is
described in detail in
Section 6.4

"C24

Produces the one's cOluplement
value of 24 8 , Other unary operators
using this syntax include AB, "0, "F,
"0, "R, and "X.

(two's

Unary operators can be used adjacent to each other or in constructions involving
multiple terms, as shown below:
-"050

Equivalent to - <"050>

"C"012

Equivalent to "C <"012>

Although angle brackets are not required, DIGITAL recommends that you use them
for clarity.
Table 3-5 describes valid MACRO-II binary operators. In contrast to unary operators,
binary operators specify actions to be performed on multiple items or terms within an
expression.
Table 3-5: Valid Binary Operators
Binary
Operator

Name

Example

Explanation

Addition operator

A+B

Produces two's complement sum of A
and B

Subtraction operator

A-B

Produces two's complement difference of
A and B

Multiplication operator

A*B

Produces two's complement signed 16bit product

Division operator

AlB

Produces two's complement signed 16bit quotient

Logical AND operator

A&B

Perfornls bitwise logical AND between
A and B

Logical inclusive OR
operator

A!B

Performs bitwise logical inclusive OR
between A and B

All binary operators have equal priority. Terms enclosed by angle brackets are
evaluated first, and remaining operations are performed from left to right, as shown
in the examples below:

3-4 PDP-ll MACRO-ll Language Reference Manual

. WORD
. WORD

1+2*3
1+<2*3>

;Equals 11(8)
;Equals 7(8)

3.2 MACRO-11 Symbols
MACRO-11 maintains a symbol table for each of the three symbol types that may
be defined in a MACRO-11 source program: the Permanent Symbol Table, the User
Symbol Table, and the Macro Symbol Table. The Permanent Symbol Table contains
all the permanent symbols defined within (and thus automatically recognized by)
MACRO-11 and is part of the MACRO-·11 image. The User Symbol Table (for userdefined symbols) and Macro Symbol Table (for macro symbols) are constructed as the
source program is assembled.

3.2.1 Permanent Symbols
Permanent symbols consist of the instruction mnemonics (see Appendix C) and
MACRO-11 directives (see Chapters 6 and 7 and Appendix B). These synlbols are
a pennanent part of the MACRO-11 image and need not be defined before being used
in the operator field of a MACRO-11 source statement (see Section 2.2.2).

3.2.2 User-Defined and Macro Symbols
User-defined symbols are those symbols that are equated to a specific value through
a direct assignment statement (see Section 3.3), appear as labels (see Section 2.2.1), or
act as dummy arguments (see Section 7.1.1). These symbols are added to the User
Symbol Table as they are encountered during assembly.
Macro symbols are those symbols used as macro names (see Section 7.1). They are
added to the Macro Symbol Table as they are encountered during assembly.
The following rules govern the creation of user-defined and macro syrnbols:
•

Symbols can be composed of alphanumeric characters, dollar signs ( $ ), and periods
(.) only (see Note below).

•

The first character of a symbol must not be a number (except in the case of local
symbols; see Section 3.5).

•

The first six characters of a symbol must be unique. A symbol can be written
with more than six valid characters, but the seventh and subsequent characters are
checked only for ASCII validity and are not otherwise evaluated or recognized by
MACRO-11.

•

Spaces, tabs, and invalid characters rnust not be embedded within a symbol. The
valid MACRO-11 character set is defined in Section 3.1.
NOTE
The dollar sign ($ ) and period ( . ) characters are reserved
for use in defining Digital Equipment Corporation system
software symbols. For example, $READ and . READ are
file-processing system macros for RSX-11 and RT -11,
respectively. DIGITAL suggests that you not use these

Symbols and Expressions

3-5

characters in constructing user-defined symbols or macro
symbols to avoid possible conflicts with existing or future
Digital Equipment Corporation system software symbols.
The value of a symbol depends upon its use in the program. A symbol in the operator
field can be anyone of the three symbol types described above; permanent, userdefined, or macro. To determine the value of an operator-field symbol, MACRO-II
searches the symbol tables in the following order:
1.

Macro Symbol Table

Permanent Symbol Table

User Symbol Table

This search order allows permanent symbols to be used as macro symbols, but you
must keep in mind the sequence in which the search for symbols is performed to avoid
incorrect interpretation of the symbol's use.
When a symbol appears in the operand field, the search order is:
1.

User Symbol Table

Permanent Symbol Table

Depending on their use in the source program, user-defined symbols have either a
local (internal) attribute or a global (external) attribute.
Normally, MACRO-II treats all user-defined symbols as local; that is, their definition
is limited to the module in which they appear. However, symbols can be explicitly
declared to be global symbols through one of three methods:
•

Use of the .GLOBL directive (see Section 6.S.1)

•

Use of the double colon (::) in defining a label (see Section 2.2.1)

•

Use of the double equal sign (= =) or double equal colon sign (= =:) in a direct
assignment statement (see Section 3.3)

All symbols within a module that remain undefined at the end of assembly are treated
as default global references, unless you use the .DSABL GBL directive (see Section 6.2.1).
If . ENABL GBL is in effect, the undefined symbols are assigned a value of 0 and placed
into the User Symbol Table as undefined default global references. If the . DSABL GBL
directive is in effect, however, the statement containing the undefined symbol is flagged
with an error code (U) in the assembly listing.
Global symbols provide linkages between independently assembled object Inodules
within the task image. For example, a global symbol defined as a label may serve as
an entry point address to another section of code within the image. Such symbols are
referenced from other source modules in order to transfer control throughout execution.
These global symbols are resolved at link time, ensuring that the resulting image is a
logically coherent and complete body of code.

3-6 PDP-ll MACRO-ll Language Reference Manual

3.3 Direct Assignment Statements
The general fonnat for a direct assignment statement is:
symbol=expression

or:
symbol==expression

where:
expression

can have only one level of forward reference (see list of rules, below) and
cannot contain an undefined global reference.

The colon format for a direct assignment statement is:
symbol=:expression

or:
symbol==:expression

where:
expression

can have only one level of forward reference (see list of rules, below) and
cannot contain an undefined global reference.

All the direct assignment statements above allow you to equate a symbol with a
specific value. After the symbol has been defined, it is entered into the User Symbol
Table. If the general format is used (= or = =) the value of the symbol can be changed
in subsequent direct assignment statements. However, if the colon format is used (=:
or = =: :), any attempt to change the value of the symbol generates an error eM) in the
assembly listing.
A direct assignment statement using either the double equal (= =) sign or the double
equal colon (= =:) sign, as shown above, defines the symbol as global (see Section 6.8.1).
The following examples illustrate the coding of direct assignment statements.
Example 1:
A=10

;Direct assignment

B==30

; Global assignment

A=15

;Valid reassignment

L=:5

; Equal colon assignment

M==:A+2 ;Double equal colon assignment
;M becomes equal to 17
L=4

;Invalid reassignment
;M error is generated

Symbols and Expressions

3-7

; Example 2:

c:
D=.
E:

;The symbol D is equated to ., and
;the labels C and E are assigned a
;value that is equal to the location
;of the MOV instruction. C, D, and E
;all have the same value.

MOV #l,ABLE

The code in Example 2 above would not usually be used and is shown only to illustrate
the performance of MACRO-11 in such situations. See Section 3.6 for a description
of the period (.) as the current location counter symbol.
The following rules apply to the coding of direct assignment statements:
•

An equal sign (=), double equal sign (= =), equal colon sign (=:), or double
equal colon sign (= =:) must separate the symbol from the expression defining the
symbol's value. Spaces preceding and/or following the direct assignment operators,
although permissible, have no significance in the resulting value.

•

The symbol being assigned in a direct assignment statement is placed in the label
field.

•

Only one symbol can be defined in a single direct assignment statement.

•

A direct assignment statement can be followed only by a comment field.

•

Only one level of forward referencing is allowed. The following example would
cause an error code (U) in the assembly listing on the line containing the invalid
forward reference:

x=y

;Invalid forward reference

Y=Z

;Valid forward reference

Z=l

Although one level of forward referencing is allowed for local symbols, no forward
referencing is allowed for global symbols. In other words, the expression being
assigned to a global symbol can contain only previously defined symbols. A forward
reference in a direct assignment statement defining a global symbol causes an error
code (A) in the assembly listing.

3.4 Register Symbols
The eight general registers of the PDP-11 processor are numbered 0 through 7 and
can be expressed in the source program in the following manner:

%0
%1

%7
where % indicates a reference to a register rather than a location. The digit specifying
the register can be replaced by any valid, absolute term that can be evaluated during
the first assembly pass.
3-8 PDP-ll MACRO-ll Language Reference Manual

The register definitions listed below are the normal default values predefined by
MACRO-11. They remain valid for all register references within a source program.
RO=%O
R1=%1
R2=%2
R3=%3
R4=%4
R5=%5
SP=%6
PC=%7

;Register 0 definition.
;Register 1 definition.
;Register 2 definition.
;Register 3 definition.
;Register 4 definition.
;Register 5 definition.
;Stack pointer definition.
;Program counter definition.

Registers 6 and 7 are given special names because of their unique system functions. The
symbolic default names assigned to the registers, as listed above, are the conventional
names used in all DIGITAL-supplied PDP-11 system programs. For this reason, you
are advised to follow these conventions.
A register symbol can be defined in a direct assignment statement appearing in the
program. The defining expression of a register symbol must be a valid, absolute
value between 0 and 7, inclusive, or an error code (R) will appear in the assembly
listing. Although you can reassign the standard register symbols through the use of
the . DSABL REG directive (see Section 6.2.1), this practice is not recommended. An
attempt to redefine a default register symbol without first specifying the . DSABL REG
directive to override the normal register definitions causes that assignment statement
to be flagged with an error code (R) in the assembly listing. All nonstandard register
symbols must be defined before they are referenced in the source program.
The % character can be used with any valid term or expression to specify a register.
For example, the statement:
CLR

%3+1

is equivalent in function to the statement:
CLR

and dears the contents of register 4.
In contrast, the statement:
CLR

clears the contents of virtual memory location 4.
The accumulator registers used in floating-point instructions can be defined in a similar
manner. For example, with the definition:
ACO=%O

the statement:
MULF

(~RO

. ACO

multiplies the contents of floating-point accumulator register ACO by the floating-point
number addressed by RO.

Symbols and Expressions

3-9

3.5 Local Symbols
Local symbols are specially formatted symbols used as labels within a block of coding
that has been delimited as a local symbol block. Local symbols are of the form n$,
where n is a decimal integer from 1 to 65535, inclusive. Examples of local symbols
are:
1$:
27$:
59$:
104$:

A local symbol block is delimited in one of three ways:
•

The range of a local symbol block usually consists of those statements between
two normally constructed symbolic labels (see Figure 3-1). Note that a statement
of the form:
ALPHA=EXPRESSION

is a direct assignment statement (see Section 3.3) but does not create a label and
thus does not delimit the range of a local symbol block.
•

The range of a local symbol block is normally terminated upon encountering a
. PSECT, . CSECT, . ASECT, or . RESTORE directive in the source program (see Figure 3-1).

•

The range of a loca] symbol block is delimited through MACRO-II directives, as
follows:
Starting delimiter: . ENABL LSB (see Section 6.2.1)
Ending delimiter: . DSABL LSB
or one of the following:
Symbolic label (see Section 2.2.1)
· PSECT (see Section 6.7.1)
· CSECT (see Section 6.7.2)
· ASECT (see Section 6.7.2)
· RESTORE (see Section 6.7.4)
encountered after a . DSABL LSB (see Section 6.2.1).

Local symbols provide a convenient means of generating labels for branch instructions
and other such references within local symbol blocks. Using local symbols reduces
the possibility of symbols with multiple definitions appearing within a user program.
In addition, the use of local symbols differentiates entry-point labels from local labels,
since local symbols cannot be referenced from outside their respective local symbol
blocks. Thus, local symbols of the same name can appear in other local symbol blocks
without conflict. Local symbols do not appear in cross--reference listings and require
less symbol table space than other types of symbols. Their use is recommended.
When defining local symbols, use the range from 1$ to 29999$ first. Local symbols
within the range 30000$ through 65535$, inclusive, can be generated automatically as
a feature of MACRO-II. Such local symbols are useful in the expansion of macros
during assembly (see Section 7.3.5).

3-1 0

PDP-l1 MACRO-ll Language Reference Manual

Be sure to avoid multiple definitions of local symbols within the same local symbol
block. For example, if the local symbol 10$ is defined more than once within the
same local symbol block, each symbol represents a different address value. Such a
multidefined symbol causes an error code (P) in the assembly listing.
For examples of local symbols and local symbol blocks as they appear in a source
program, see Figure 3-1.
Figure 3-1:

Assembly Listing Showing Local Symbol Block

; Simple illustration of local symbols; the second block is delimited
; by the label XCTPAS.

3
4

6000000
7 000004
8 000006

9 000012
10
11 000014
12 000020
13 000022
14 000026
16 000030
16

012"00 XCTPRG: .MOV
ooOOOOG
006020 1$:
CLR
020027
CMP
OOOOOOG
001374
BNE
012700 XCTPAS:
ooOOOOG
006020 1$:
020027
ooOOOOG
001374
000207

# IMPURE ,RO

;Point to impure area

(RO)+
RO,#IMPURT

;Clear a word
;Test if at top of area

MOV

#IMPPAS,RO

;Iterate if not
;Fall in. to perform pass initialization
;Point to pass storage area

CLR
eMP

(RO)+
RO,#IMPPAT

;Clear the area
; Test if at top of area

ENE
RETURN

;Iterate if not
; Return if so

3.6 Current Location Counter
The period (.) is the symbol for the current location counter. When used in the
operand field of an instruction, the period represents the address of the first word of
the instruction, as shown in this example:
A:

MOV

#. ,RO

;The period C.) refers to the address
;of the MOV instruction.

The function of the number sign (#) is explained in Section 5.9.
When used in the operand field of a MACRO-II directive, the period represents the
address of the current byte or word, as shown here:
SAL=O
.WORD 177535, .+4,SAL

;The operand .+4 in the .WORD
;directive represents a value
;that is stored as the second
;of three words during
; assembly.

Assume that the current value of the location counter is 1500 8 , During assembly,
MACRO-II reserves storage in response to the . WORD directive (see Section 6.3.2),
beginning with location 1500 8 , The operands accompanying the . WORD directive
determine the values so stored. The value 177535 8 is thus stored in location 1500.
The value represented by .+4 is stored in location 1502; this value is derived as the
current value of the location counter (which is now 1502), plus the absolute value
4, thereby depositing the value 1506 in location 1502. Finally, the value of SAL,
previously equated to 0, is deposited in location 1504:

Symbols and Expressions

3-11

Location 1500:
Location 1502:
Location 1504:

177535
001506
000000

At the beginning of each assembly pass, MACRO-11 resets the location counter.
Normally, consecutive memory locations are assigned to each byte of object data
generated. However, the value of the location counter can be changed through a
direct assignment statement of the following form:
.=expression

The current location counter symbol ( . ) is either absolute or relocatable, depending on
the attribute of the current program section.
The attribute of the current location counter can be changed only through the program
sectioning directives (. PSECT, . ASECT, . CSECT, and . RESTORE), as described in Section 6.7.
Therefore, assigning to the current location counter an expression having an attribute
other than that of the current program section will generate an error code (A) in the
assembly listing.
Furthermore, an expression assigned to the current location counter cannot contain
a forward reference (a reference to a symbol that is not previously defined). You
must also be sure that the expression assigned does not force the current location
counter into another program section, even if both sections involved have the same
relocatability. Either of these conditions causes MACRO--II to generate incorrect object
file code, and may cause statements following the error to be flagged with an error
code (P) in the assembly listing.
The following coding illustrates the use of the current location counter:
. ASECT
.=1500
FIRST:

MOV

. +10,COUNT

. =1520
SECOND: MOV

. , INDEX

;Set location counter to
;absolute 1500(octal) .
;The label "FIRST" has the value
;1500(octal).
; .+10 equals 1510(octal). The
;contents of the location
;1510(octal) will be deposited
;in the location "COUNT" .
;The assembly location counter
;now has a value of
;absolute 1520(octal).
;The label "SECOND" has the
;value 1520(octal).
;The contents of location
;1520(octal), that is, the binary
;code for the instruction
;itself, will be deposited in the
;location "INDEX" .

. PSECT
.=.+20
THIRD:

3-1 2

. WORD

PDP-ll MACRO-l1 Language Reference Manual

;Set location counter to
;relocatable 20 of the
;unnamed program section.
;The label "THIRD" has the
;value of relocatable 20.

Storage areas can be reserved in the program by advancing the location counter. For
example, if the current value of the location counter is 1000, each of the following
statelnents:
.=.+40

or:
.BLKB 40

or:
.BLKW 20

reserves 40 8 bytes of storage space in the source program starting at location 1000.
The . BLKB and . BLKW directives, however, are the preferred ways to reserve storage
space (see Section 6.5.3).

3.7 Numbers
MACRO-II assumes that all numbers in the source program are to be interpreted
in octal radix, unless otherwise specified. An exception to this assumption is that
operands associated with Floating Point Processor instructions and Floating Point Data
directives are treated as decimal (see Section. 6.4.2). The default radix (octal) can be
changed with the .RADIX directive (see Section 6.4.1.1). Also, individual numbers can
be designated as binary, octal, decimal, or hexadecimal numbers through temporary
radix control operators (see Section 6.4.1.2).
If a statement in the source program contains a digit that is not in the current radix,

MACRO-II generates an error code (N) in the assembly listing. However, MACRO-II
continues with the scan of the statement and evaluates each such number encountered
as a decimal value.
Negative numbers must be preceded by a minus sign; MACRO-II translates such
numbers into two's complement form. Positive numbers may (but need not) be
preceded by a plus sign.
A number containing more than 16 significant bits (greater than 1777778 ) is truncated
from the left and flagged with an error code (T) in the assembly listing.
Numbers are always considered to be absolute values; therefore, they are never
reloca table.
Single-'word floating-point numbers can be generated with the
Section 6.4.2.3) and are stored in the following format:.

-F

operator (see

115114
716
:=Q]
1 sIEEEEEEEEIMMMM~

Sign (1 bit)
Exponent (8 bits)
Mantissa (7 bits)
Refer to the PDP--ll Processor Handbook for details of the floating-point number format.

Symbols and Expressions

3-1 3

3.8 Terms
A term is a component of an expression and can be one of the following:
•

A number (see Section 3.7) whose 16-bit value is used.

•

A symbol (see Section 3.2). Symbols are evaluated as follows:
a.

A period (.) specified in an expression causes the value of the current location
counter to be used.

A defined symbol is located in the User Symbol Table and its value is used.

A permanent symbol's basic value is used, with zero substituted for the
addressing modes. (Appendix C lists all op codes and their values.)

An undefined symbol is assigned a value of zero and inserted in the User
Symbol Table as an undefined default global reference. If the . DSABL GBL
directive (see Section 6.2.1) is in effect, the automatic global reference default
function of MACRO-II is inhibited, and the statement containing the undefined
symbol is flagged with an error code (U) in the assembly listing.

•

A single quote followed by a single ASCII character, or a double quote followed by
two ASCII characters. This type of expression construction is explained in detail
in Section 6.3.3.

•

An expression enclosed in angle brackets ( < ». Any expression so enclosed is
evaluated and reduced to a single term before the remainder of the expression in
which it appears is evaluated. For example, angle brackets can be used to alter
the left-to-right evaluation of expressions, as in A*B+C versus A*<B+C>, or to apply
a unary operator to an entire expression, as in -<A+B>.l

•

A unary operator followed by a symbol or number.

3.9 Expressions
Expressions are combinations of terms joined together by binary operators (see
Table 3-5). Expressions reduce to a 16-bit value. The evaluation of an expression
includes the determination of its attributes. A resultant expression value can be any
one of four types: relocatable, absolute, external, or complex relocatable.
Expressions are evaluated from left to right with no operator hierarchy rules, except
that unary operators take precedence over binary operators. A term preceded by a
unary operator is considered to contain that operator. (Terms are evaluated, where
necessary, before their use in expressions.) Multiple unary operators are valid and are
treated as follows:
-+-A

is equivalent to:
-<+<-A»

1 The maximum depth of an expression is governed by the MACRO-ll assembler's expr l2ssion stack space. If an expression exceeds the
assembler's maximum expression depth, the statement is marked with an (E) error, and processing continues.

3-14 PDP-ll MACRO-ll Language Reference Manual

A missing term, expression, or external symbol is interpreted as a zero. A nlissing or
invalid operator terminates the expression analysis, causing error codes (A) and/or
(Q), to be generated in the assembly listing, depending on the context of the expression
itself. For example, the expression:
A + B 177777

is evaluated as:
A+ B

because the first nonblank character following the symbol B is not a valid binary
operator, an expression separator (a comma), or an operand field terminator (a
semicolon or the end of the source line).
Spaces within expressions can serve as delimiters only between symbols. In other
words, the expressions:
A+ B

and:
A+B

are the same, but the symbols:
B17

and:
B 17

are not (B 17 is not a single symbol).
At assembly time the value of an external (global) expression is equal to the value
of the absolute part of that expression. For example, the expression EXTERN+A, where
EXTER.N is an external symbol, has a value at assembly time that is equal to the value
ot'the internal (local) symbol A. However, when evaluated at link time, this expression
takes on the resolved value of the symbol 'EXTERN plus the value of symbol A.
When evaluated by MACRO-11, expressions are one of four types: relocatable,
absolute, external, or complex relocatable. The following distinctions are important:
•

An expression is relocatable if its value is fixed relative to the base address of
the program section in which it appears; it will have an offset value added at
link time. Terms that contain labels defined in relocatable program sections will
have a relocatable value; similarly, a period (.) in a relocatable program section,
representing the value of the current location counter, will also have a relocatable
value.

•

An expression is absolute if its value is fixed. An expression whose terms are
numbers and ASCII conversion characters will reduce to an absolute value. A
relocatable expression or term minus a relocatable term, where both elements
being evaluated belong to the same program section, is an absolute expression.
This is because every term in a program section has the same relocation bias. When
one term is subtracted from another, the resulting bias is zero. MACRO-11 can
then treat the expression as absolute and reduce it to a single term upon completion
Symbols and Expressions

3-1 5

of the expression scan. Terms that contain labels defined in an absolute program
section also have an absolute value.
•

An expression is external (or global) if it contains a single global reference (plus or
minus an absolute expression value) that is not defined within the current program.
Thus, an external expression is only partially defined following assembly and must
be resolved at link time.

•

An expression is complex relocatable if anyone of the following conditions
applies:
It contains a global reference and a relocatable symbol.
It contains more than one global reference.
It contains relocatable terms belonging to different program sections.

The value resulting from the expression has more than one level of relocation.
For example, if the relocatable symbols TAG1 and TAG2, associated with the
same program section, are specified in the expression TAG1 +TAG2, two levels of
relocation will be introduced, since each symbol is evaluated in terms of the
relocation bias in effect for the program section.
An operation other than addition is specified on an undefined global symbol.
An operation other than addition, subtraction, negation, or complementation is
specified for a relocatable value.
The evaluation of relocatable, external, and complex relocatable expressions is
completed at link time. The maximum number of terms that can be specified in
a complex expression is 2010 and is limited by the maximum size of the object record.

3-1 6

PDP-ll MACRO-ll Language Reference Manual

Chapter 4

Relocation and Linking
The output of MACRO-II is an object nlodule that must be processed or linked before
it can be loaded and executed. Linking fixes (makes absolute) the values of relocatable
or external symbols in the object module, thus transforming the object module, or
several object modules, into an executable image.
To allow the value of an expression to be fixed at link time, MACRO-II writes certain
instructions in the object file, together with other required parameters. For relocatable
expressions in the object module, the base of the associated relocatable program
section is added to the value of the relocatable expression provided by MACRO-II.
For external expression values (those containing a reference to a global symbol defined
in another module), the value of the external term in the expression (since the external
symbol must be defined in one of the other object modules being linked together)
is determined and then added to the absolute portion of the external expression, as
provided by MACRO-II.
All instructions that require modification at link time are flagged in the assembly
listing, as illustrated in the example below. The single quote (') following the octal
expansion of the instruction indicates that simple relocation is required; the letter G
indicates that the value of an external (global) symbol must be added to the absolute
portion of an expression; and the letter C indicates that complex relocation analysis at
link time is required in order to fix the value of the expression.

Example:
005065 CLR
000040'

RELOC(R5)

;Assuming that the value of the
;symbol II RELOC " , 40, is relocatable
;the relocation bias
;will be added to this value.

005065 CLR
OOOOOOG

EXTERN (R5)

;The value of the symbol "EXTERN" is
;assembled as zero and is
;resolved at link time.

005065 CLR
000006G

EXTERN+6(R5)

;The value of the symbol "EXTERN"
;is resolved at link time
;and added to
;the absolute portion (+6) of
;the expression.

005065 CLR
OOOOOOC

-<EXTERN+RELOC> (R5)
;This expression is complex
;relocatable because it requires
;the negation of an expression
;that contains a global "EXTERN"
;reference and a relocatable term.

For a complete description of object records written by MACRO-II, refer to the
applicable systerrL manual (see the Associated Documents section in the Preface).

Relocation and Linking

4-1

Chapter 5

Addressing Modes
To understand how the address modes operate and how they assemble, you must
understand the action of the program counter. The key rule to remember is:
"Whenever the processor implicitly uses the program counter (PC) to fetch a word
from memory, the program counter is automatically incremented by 2 after the
fetch operation is completed."
The PC always contains the address of the next word to be fetched. This word will be
either the address of the next instruction to be executed or the second or third word
of the current instruction.
Table 5-1 lists the symbols used in this chapter to describe the address modes, and
Table 5·-2 lists the address modes. This chapter illustrates each mode of address using
the single operand instruction CLR or the double operand instruction MOV. Section B.2
gives a summary of address mode syntax.
Certain special instruction/address mode combinations, which are rarely or never used,
do not operate the same on all PDP-II processors. There are three major classes of
instructions you are most likely to encounter. These are listed in Table 5-3.1 Avoid
using these addressing modes if there is the slightest chance a program will ever have
to run on more than one type of processor. MACRO-II prints an error code (Z) in
the assembly listing with each instruction containing an addressing mode incompatible
among all members of the PDP-II family.
Table 5-1:

Symbols Used in Chapter 5

Symbol

Explanation

.------------------------------------------------------------.--------

Any expression, as defined in Chapter 3.

A register expression; that is, any expression containing a term preceded by a
percent sign (%) or a symbol previously equated to such a term, as shown
below:

RO=%O
R1=RO+1
R2=1+%1

;General register O.
;General register 1.
;General register 2.

This symbol may also represent any of the normal default register definitions
(see Section 3.4).

A register expression ·or an absolute expression in the range 0 to 7, inclusive.

1 The PDP-ll Architecture Handbook lists all the differences among all PDP-ll processors.

Addressing Modes

5-1

Table 5-2:

Addressing Modes

Mode

Form

Reference3

5.1

@R or (ER)

5.2

Autoincrement model

(ER)+

5.3

Autoincrement deferred model

@(ER)+

5.4

Autodecrement model

- (ER)

5.5

Autodecrement deferred model

@-(ER)

5.6

Index mode 2

E(ER)

5.7

@E(ER)

5.8

Immediate mode 2

5.9

Absolute mode 2

@#E

5.10

Relative mode 2

5.11

Relative deferred mode 2

5.12

Branch

Address

5.13

Index deferred mode

1 Does not increase the length of an instruction.
2 Adds one word to the instruction length for each occurrence of an operand of this form.
3Section B.2 contains a summary of addressing mode syntax.

5-2

PDP-ll MACRO-ll Language Reference Manual

Table 5-3: Instruction Differences Among PDP-11 Processors
Instruction

Operation A

Operation B

OPR 1

R, (R) +2

OPR

R, - (R)

Initial contents of R are used as the
source operand 6

OPR

R,@(R)+

Contents of R are incremented (or
decremented) by 2 before being
used as the source operands

OPR

R,@-(R)

OPR

PC,E(R)

Location A will contain the PC of

OPR

OPR+4 5

OPR+2 6

OPR

PC,@E(R)
PC,A3

OPR

PC,@A

Contents of R are incremented by
2, then used as the new PC 7

Initial contents of R are used as the
new PCB

JMP

(R)+

JSR

Rn, (R)+4

10PR represents any two-operand instruction
2R is the same for both source and destination
3 A represents any address expression
4Rn is not necessarily the same as R
5 23/ 24, 15/20,35/40,60, J11, and III processors
604, 05/10, 34, 44, 45, and 70 processors
705 / 10 and 15/20 processors
BAll except 05/10 and 15/20 processors

5.1 Register Mode
Format:
R

The register R contains the operand for the instruction.
Example:
CLR

;Clears register 3.

5.2 IRegister Deferred Mode
Format:
@R
(ER)

The register R contains the address of the operand for the instruction.
Example:
CLR
CLR
CLR

@R1
(R1)
(%1)

;All these instructions clear
;the word at the address
;contained in register 1.

Addressing Modes

5-3

5.3 Autoincrement Mode
Format:
(ER)+

The contents of the register ER are incremented immediately after being used as the
address of the operand (see Table 5-3 for possible processor incompatibilities).
Example:
CLR
CLR
CLR

(RO)+
(R4)+
(R2)+

;Each instruction clears
;the word at the address
;contained in the specified
;register and increments
;that register's contents
;by 2.

5.4 Autoincrement Deferred Mode
Format:
<HER) +

The register ER contains a pointer to the address of the operand. The contents of the
register are incremented after being used as pointer.
Example:
CLR

@(R3)+

;The contents of register 3 point
;to the address of a word to be
;cleared before the contents of the
;register are incremented by 2.

5.5 Autodecrement Mode
Format:
-(ER)

The contents of the register ER are decremented before being used as the address of
the operand (see Table 5-3 for possible processor incompatibilities).
Example:
CLR

-(RO)

CLR
CLR

-(R3)
-(R2)

;Decrement the contents of the
;specified register (a, 3, or 2)
;by 2 before using its contents
;as the address of the word to be
;cleared.

5.6 Autodecrement Deferred Mode
Format:
@-(ER)

The contents of the register ER are decremented before being used as a pointer to the
address of the operand.
5-4 PDP-ll MACRO-ll Language Reference Manual

Example:
CLR

@-(R3)

;Decrement the contents of
;register 3 by 2 before
;using its contents as a pOinter
;to the address of the word to be
; clear~3d.

5. 7 ~ndex Mode
Format:
E(ER)

An expression E, plus the contents of a register ER, yields the effective address of the
operand. In other words, the value E is the offset of the instruction, and the contents
of register ER form the base. The value of the expression E is stored as the second or
third word of the instruction.
Example:
CLR

X+2(R1)

MOV

RO,-2(R3)

;The effective address of the word
;to be cleared is X+2, plus the
;contents of register 1.
;The effective address of the
;destination location is -2, plus
;the contents of register 3.

5.8 Iindex Deferred Mode
Format:
@E(ER)

An expression E, plus the contents of register ER, yields a pointer to the address of the
operand. The value E is the offset of the instruction, and the contents of register ER
form the base. The value of the expression E is stored as the second or third word of
the instruction.
Example:
CLR

@114(R4)

;If register 4 contains 100, this
; value , plus the offset 114, yields
;the pointer 214. If location 214
;contains the address 2000, location
;2000 would be cleared.

NOTE
The expression @(ER) can be used, but it will be assembled
as if it were written @o (ER), and a word will be used to
store the O.

Addressing Modes

5-5

5.9 Immediate Mode
Format:
#E

Immediate mode stores the operand itself (E) as the second or third word of the
instruction. The number sign (#) is an addressing mode indicator. This character
appearing in the operand field specifies the immediate addressing mode, indicating to
MACRO-II that the operand itself immediately follows the instruction word. This
mode is assembled as an autoincrement of the PC.
Example:
MOV
MOV

#100,RO
#X,RO

;Move the value 100 into register O.
;Move the value of symbol X into
;register O.

The operation of this mode can be shown through the first example, MOV #100, RO,
which assembles as two words:
Location n:
Location n+2:
Location n+4:

012700
000100
Next instruction

The source operand (the value 100) is assembled immediately following the instruction
word. Upon execution of the instruction, the processor fetches the first word (MOV)
and increments the PC by 2, so that it points to the second word, location n+2, which
contains the source operand.
After the next fetch and increment cycle, the source operand (100) is moved into
register 0, leaving the PC pointing to location n+4 (the next instruction).

5.10 Absolute Mode
Format:
@#E

Absolute mode is the equivalent of immediate mode deferred. The address expression
@#E specifies an absolute address that is stored as the second or third word of the
instruction. In other words, the value immediately following the instruction word is
taken as the absolute address of the operand. Absolute mode is assembled as an
autoincrement deferred of the PC. You can use this mode to reference specific memory
addresses from within position-independent code.
Example:
MOV

@#100,RO

CLR

@#X

;Move the contents of absolute
;location 100 into register RO.
;Clear the contents of the location
;whose address is specified by
;the symbol X.

The operation of this mode can be shown through the first example:
MOV

5-6

@#100,RO

PDP-ll MACRO-ll Language Reference Manual

which assembles as two words:
Location n:
Location n+2:
Location n+4:

013700
000100
Next instruction

The absolute address 100 is assembled immediately following the instruction word.
Upon execution of the instruction, the processor fetches the first word (MOV) and
increnlents the PC by 2, so that it points to the second word, location n+2, which
contains the absolute address of the source operand. After the next fetch and increment
cycle, the contents of absolute address 100 (the source operand) are moved into register
0, leaving the PC pointing to location n+4 (the next instruction).

5.11 Relative Mode
Format:
E

Relative mode is the normal mode for memory references within your program. It
is assembled as index mode, using the PC as the index register. The offset for the
address calculation is assembled as the second or third word of the instruction. This
value is added to the contents of the PC to yield the address of the source operand.
Example:
CLR
MOV

1.00
RO,Y

;Clear absolute location 100
;Move the contents of register 0
;to location Y

Assume the current value of the PC is 1020. The operation of relative mode can be
shown with the statement:
MOV

1.00,R3

which assembles as two words:
Location 1020: 01.6703
Location 1022: 177054
Location 1024: Next instruction

The offset, the constant 177054, is assembled immediately following the instruction
word. Upon execution of the instruction, the processor fetches the first word (MOV) and
incrernents the PC by 2, so that it points to the second word, location 1022, containing
the value 177054. After the next fetch and increment cycle, the processor calculates
the effective address of the source operand by taking the contents of location 1022
(the offset) and adding it using two's complement arithmetic to the current value of
the PC, which now points to location 1024 (the next instruction). Thus, the source
operand address is the result of the calculation:
OFFSET+PC = 177054+1024 = 100 8
so the contents of location 100 are ,moved into register 3.
The index mode statement:
MOV

100-.-4(PC),R3

Addressing Modes

5-7

is equivalent to the relative mode statement:
MOV

100,R3

The term 100-.-4 is the offset for the index mode statement. The current location
counter (.) holds the address of the first word of the instruction (1020, in this case),
and the PC has to move down four bytes to reach location 1024 (the next instruction).
So, the offset could be written as 100-1020-4, or 177054 8 ,
Therefore, for the index mode, the offset (177054 8 ) added to the PC (1024 8 ) yields the
effective address (177054 + 1024 = 100 8 ) of the operand.
Thus, both statements move the contents of location 100 into register 3.

NOTE
The addressing form @#E differs froml form E in that
the second or third word of the instruction contains
the absolute address of the operand, rather than the
relative distance between the operand and the PC (see
Section 5.10). Thus, the instruction CLR @#100 clears
absolute location 100, even if the instruction is moved
from the point at which it was assembled.
See
Section 6.2.1 for a description of the. ENABL AMA function,
which causes all relative mode addresses to be assembled
as absolute mode addresses.

5.12 Relative Deferred Mode
Format:
@E

Relative deferred mode is similar in operation to relative mode, except that the
expression E is used as a pointer to the address of the operand. In other words, the
operand following the instruction word is added to the contents of the PC to yield a
pointer to the address of the operand.
Example:
MOV

@X,RO

;Relative to the current value of
;the PC, move the contents of the
; location whose address is pOinted
;to by location X into register O.

5.13 Branch Instruction Addressing
Branch instructions are I-word instructions. The high-order byte contains the operator,
and the low-order byte contains an 8-bit signed offset (seven bits, plus sign), which
specifies the branch address relative to the current value of the PC. The hardware
calculates the branch address as follows:
1.

Extends the sign of the offset through bits 8 to 15.

Multiplies the result by 2, creating a byte offset rather than a word offset.

5-8 PDP-ll MACRO-ll Language Reference Manual

Adds the result to the current value of the PC to form the effective branch address.

MACRO-II performs the reverse operation to form the word offset from the specified
address:
Word offset = (E-PC)j2, truncated to eight bits.
When the offset is added to the PC, the PC is moved to the next word (PC=.+2).
Hence the -2 in the following calculation:
Word offset = (E-.-2)j2, truncated to eight bits.
The following conditions generate an error code (A) in the assembly listing:
•

Branching froIn one program section to another

•

Branching to a location that is defined as an external (global) symbol

•

Specifying a branch address that is out of range, meaning that the branch offset is
a value that exceeds the range -128 10 to +12710

5.14 Using TRAP Instructions
Since the EMT and TRAP instructions do not use the low-order byte of the instruction
word, information is transferred to the trap handlers in the low-order byte. If the EMT
or TRAP instruction is followed by an expression, the value of the expression is stored
in the low-order byte of the word. Expressions greater than 3778 are truncated to
eight bits, and an error code (A) is generated in the assembly listing.
For more information on traps, see the PDP-ll Processor Handbook and the applicable
system Inanual (see the Associated Documents section in the Preface).

Addressing Modes

5-9

Part III

Chapter 6

General Assembler Directives
A MACRO-II directive is placed in the operator field of a source line. Only one
directive is allowed per source line. A directive may have a blank operand field or
one or more operands. Valid operands differ with each directive.
General assembler directives are divided into the following categories:

•

Listing control

•
•

Function control

•

Radix and numeric control

•

Location counter control

•

Tennina tor

•

Program sectioning and boundaries

•

Synlbol control

•

Conditional assembly

•

File control

Data storage

Each is described in its own section of this chapter. See Table 6-1 for an alphabetical
listing of the directives and the associated section reference. Also refer to Section B.3
for a complete list of all MACRO-II assembler directives.
Table 6-1:

Directives in Chapter 6

Directive

Function

.ASCII

Stores delimited string as a sequence of the 8-bit ASCII code of
their characters.

6.3.4

.ASCIZ

Sanle as . ASCII except the string is followed by a zero byte.

6.3.5

. ASECT

Similar to . PSECT.

6.7.2

.BLKB

Allocates bytes of data storage.

6.5.3

.BLKW

Allocates words of data storage.

6.5.3

. BYTE

Stores successive bytes of data.

6.3.1

. CROSS

Enables cross referencing.

6.2.2

Section
Reference

General Assembler Directives

6-1

Table 6-1 (Cont.):

6-2

Directives in Chapter 6

Directive

Function

Section
Reference

.CSECT

Similar to . PSECT .

6.7.2

. DSABL

Disables specified assembler functions.

6.2.1

.ENABL

Enables specified assembler functions.

6.2.1

.END

Indicates end of source input.

6.6

.ENDC

Indicates end of conditional assembly block.

6.9.1

. EVEN

Ensures that current value of the location counter is even.

6.5.1

.FLT2

Generates 2 words of storage for each floating-point number
argument.

6.4.2.2

.FLT4

Generates 4 words of storage for each floating-point number
argument.

6.4.2.2

.GLOBL

Defines listed symbols as global.

6.8.1

.IDENT

Provides additional means of labeling an object module.

6.1.4

.IF

Assembles block if specified conditions are met.

6.9.1

.IFF

Assembles block if condition tests false.

6.9.2

.IFT

Assembles block if condition tests true.

6.9.2

.IFTF

Assembles block regardless of whether condition tests true or false.

6.9.2

.IIF

Permits writing a I-line conditional assembly block.

6.9.3

. INCLUDE

Includes another MACRO-II source file.

6.10.2

. LIBRARY

Adds file to MACRO-II library search list.

6.10.1

.LIMIT

Allocates 2 words for storage. At link time the Linker or Task
Builder puts the lowest address of the load image in the first of
the saved words and the address of the first free word following
the image in the second.

6.5.4

.LIST

Increments listing count or lists certain types of code.

6.1.1

.NLIST

Decrements listing count or suppresses certain types of code.

6.1.1

. NOCROSS

Disables cross referencing.

6.2.2

.000

Ensures that the current value of the location counter is odd.

6.5.2

. PACKED

Generates packed decimal data, two digits per byte.

6.3.8

. PAGE

Starts a new listing page.

6.1.5

.PSECT

Declares names for program sections and establishes their
attributes.

6.7.1

.RAD50

Generates data in Radix-50 packed format.

6.3.6

PDP-ll MACRO-ll Language Reference Manual

Table 6-1 (Cont.):

Directives in Chapter 6
Section
Reference

Directive

Function

. RADIX

Changes the default radix throughout orin portions of the source
program.

6.4.1.1

. REM

Delimits a section of comments.

6.1.6

. RESTORE

Retrieves a previously" SAVEd program section.

6.7.4

. SAVE

Places the current program section on top of the program section
context stack.

6.7.3

.SBTTL

Produces a table of contents ilnmediately preceding the assembly
listing and puts subheadings on each page in the listing.

6.1.3

.TITLE

Assigns a name to the object module and puts headings on each
page of the assembly listing.

6.1.2

. WEAK

Defines listed symbols as WEAK.

6.8.2

. WORD

Generates successive words of data in the object module.

6.3.2

6.1 l.isting Control Directives
Listing control directives control the content, format, and pagination of all line printer
(see Figure 6-1) and terminal (see Figure 6-2) assembly listing output. On the first
line of each page/' MACRO-II prints the following (from left to right):
1.

Title of the object module, as established through the . TITLE directive (see
Section 6.1.2)

Assembler version identification

3. Day of the week
4.

Date

Time of day

Page number

The second line of each assembly listing page contains the subtitle text specified in the
last-encountered . SBTTL directive (see Section 6.1.3).
In line printer format (Figure 6-1), binary extensions for statements generating more
than one word are listed horizontally.
In terminal format (Figure 6-2), binary extensions for statements generating more than
one word are listed vertically. There is no explicit truncation of output to 80 characters
by the assembler..

General Assembler Directives

6-3

Figure 6-1:

Example of Line Printer Assembly Listing
;+

2
3
4
5
6
7
8 000126
9 000130
10 000136
11 000142
12 000144
13 000146
14 000154
15 000156
16 000162
17 000164
18 000166
19 000172
20 000176
21 000202
22 000204
23 000206
24 000212
25 000216
26 000222
27 000224
28 000226
29 000232
30 000236
31 000240
32 000244
33 000246
34 000252
35 000254
36 000260
37
38
39
40
41
42
43
44 000262
45 000272
46 000302
47 000312
48 000322
49 000332
50 000342
51 000352
52 000362
53 000372
54 000402
55 000412
56 000422

GETSYM
Scan off a RAD50 symbol. Leave with scan pointer set at next non-blank
char past end of symbol. Symbol buffer clear and Z set if no symbol
seen; in this case scan pointer is unaltered.
R1,-(SP)
GETSYM: : MOV
;Save work register
010146
MOV
CHRPNT,SYMBEG
; Save scan point'er in case of rescan
016767 OOOOOOG OOOOOOG
#SYMBOL+4,Rl
MOV
;Point at end of symbol buffer
012701 000004G
CLR
- (Rl)
;Now clear it
005041
CLR
- (Rt)
005041
CTTBL(R5),#CT.ALP ;Test first char for alphabetic
BITB
136527 OOOOOOG OOOOOOG
BEQ
;Exit if not, with Z set
001436
4$
CTTBL2(R5),RO
116500 000262'
1$:
MOVB
;Map to RAD50
BLE
; Exi t if not val:ld RAD50
003431
3$
ASL
; Make word index
006300
RO
MOV
R50TBl (RO) , (Rl) ;Load the high char
016011 OOOOOOG
GETCHR
;Get another char
CTTBL2(R5),RO
MOVB
;Handle it as above
116500 000262'
BLE
3$
003421
ASL
006300
RO
ADD
R50TB2(RO) , (Rl)
066011 OOOOOOG
GETCHR
; Now get low ord4!r char
MOVB
CTTBL2(R5),RO
;Map and test it
116500 000262'
BLE
3$
003411
RO, (Rt)+
ADD
;Just add in the low char, advance pOinte:r;
060021
2$:
GETCHR
;Get following char
CMP
Rl,#SYMBOL+4
; Test if at end of symbol buffer
020127 000004G
BNE
;Go again if no
1$
001347
TSTB
CTTBL2(R5)
;Flush to end of symbol if it yes
105765 000262'
BGT
2$
003370
3$:
SETNB
;Now scan to a non-blank char
(SP)+,Rl
4$:
MOV
; Restore work register
012601
MOV
SYMBOL,RO
;Set Z if no symbol found
016700 OOOOOOG
RETURN
000207
;+
Table CTTBL2
; Index with 7-bit ASCII value to get corresponding RAD50 value
; If EQ 0 then space, i f LT 0 then not RAD50; Other bits reserved.
200
200
200
200
200
200
036
046
200
010
020
030
200

200
200
200
200
200
200
037
047
001
011
021
031
001

200
200
200
200
200
200
040
200
002
012
022
032
002

.NLIST
CTTBL2: . BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE

BEX
200,200,200,200,200,200,200,200
200,200,200,200,200,200,200,200
200,200,200,200,200,200,200,200
200,200,200,200,200,200,200,200
200,200,200,200,033,200,200,200
$
200,200,200,200,200,200,034,200
036,037,040,041,042,043,044,045 ;01234567
046,047,200,200,200,200,200,200 ;89
200,001,002,003,004,005,006,007 ; ABCDEFG
010,011,012,013,014,015,016,017 ;HIJKLMNO
020,021,022,023,024,025,026,027 ;PQRSTUVW
030,031,032,200,200,200,200,200 ;XYZ
200,001,002,003,004,005,006,007 ; abcdefg

6-4 PDP-ll MACRO-ll Language Reference Manual

FigurEt 6-2:

Exarmple of Terminal Assembly Listing
;+

GETSYM
Scan off a RAD60 symbol. Leave with scan pOinter set at next non-blank
char past end of symbol. Symbc.l buffer clear and Z set if no symbol
seen; in this case scan pointer is unaltered.

3
4
6
6
7

8 000126
9 000130
10 000136
11 000142
'12 000144
13 000146
14 000164
16 000166
16 000162
17 000164
18 000166
19 000172
20 000176
21 000202
22 000204
23 000206
24 000212
26 000216
26 000222
27 000224
28 000226
29 000232
30 000236
31 000240
32 000244
33 000246
34 000262
36 000264
36 000260
37
38
39
40
41
42
43
44 000262
46 000272
46 000302
47 000312
48 000322
49 000332
60 000342
61 000362
62 000362
63 000372
64 000402
66 000412
66 000422

Rl,-(SP)
;Save work register
010146 GETSYM: : MOV
016767
CHRPNT,SYMBEG
;Save scan pointer in case of rescan
MOV
OOOOOOG
OOOOOOG
MOV
#SYMBOL+4,R1
012701
;Point at end of symbol buffer
000004G
-(Rl)
;Now clear it
006041
CLR
-(Rl)
006041
CLR
136627
BITB
CTTBL(R6),#CT.AI.P ;Test first char for alphabetic
OOOOOOG
OOOOOOG
001436
BEQ
4$
;Exit if not, with Z set
MOVB
CTTBL2(R6),RO
;Map to RAD60
116600 1$:
000262'
BLE
3$
; Exi t if not valid RAD50
003431
006300
ASL
RO
;Make word index
MOV
R60TB1(RO),(R1) ;Load the high char
016011
OOOOOOG
GETCHR
; Get another char
116600
MOVB
CTTBL2(R5),RO
;Handle it as above
000262'
003421
BLE
3$
006300
ASL
RO
ADD
R60TB2(RO),(R1)
066011
OOOOOOG
GETCHR
;Now get low order char
116600
MOVB
CTTBL2(R6),RO
;Map and test it
000262'
003411
3$
BLE
RO, (Rl)+
060021
ADD
;Just add in the low char, advance pointer
;Get following char
2$:
GETCHR
Rl,#SYMBOL+4
CMP
;Test if at end of symbol buffer
020127
000004G
BNE
1$
;Go again if no
001347
TSTB
CTTBL2(R6)
106766
;Flush to end of symbol if it yes
000262'
BGT
2$
003370
SETNB
;Now scan to a non-blank char
3$:
MOV
(SP)+,Rl
012601 4$:
;Restore work register
MOV
SYMBOL,RO
;Set Z if no symbol found
016700
OOOOOOG
000207
RETURN
;+

Table CTTBL2
; Index with 7-bit ASCII value to get corresponding RAD60 value
; If EQ 0 then space, if LT 0 then not RAD60; Other bits reserved.
200
200
200
200
200
200
036
046
200
010
020
030
200

.NLIST
CTTBL2: .BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE
. BYTE

BEX
200,200,200,200,200,200,200,200
200,200,200,200,200,200,200,200
200,200,200,200,200,200,200,200
200,200,200,200,200,200,200,200
200,200,200,200,033,200,200,200
$
200,200,200,200,200,200,034,200
036,037,040,041,042,043,044,045 ;01234667
046,047,200,200,200,200,200,200 ;89
200,001,002,003,004,006,006,007; ABCDEFG
010,011,012,013,014,016,016,017 ;HIJKLMNO
020,021,022,023,024,026,026,027 ;PQRSTUVW
030,031,032,200,200,200,200,200 ;XYZ
200,001,002,003,004,006,006,007; abcdefg

General Assembler Directives

6-5

6.1.1 .LIST And .NLIST Directives
Format:
.LIST
.LIST
.NLIST
.NLIST

arg
arg

where:
arg

represents one or more of the optional symbolic arguments defined in
Table 6-2.

As indicated above, the listing control directives can be used without arguments, in
which case the listing directives alter the listing level count. The listing level count
is initialized to zero. At each occurrence of a . LIST directive, the listing level count
is incremented; at each occurrence of a . NLIST directive, the listing level count is
decremented. When the level count is negative, the listing is suppressed (unless the
line contains an error). Conversely, when the level count is greater than zero, the
listing is generated regardless of the context of the line. Finally, when the count is
zero, the line is either listed or suppressed, depending on the listing controls currently
in effect for the program. The following macro definition employs the . LIST and . NLIST
directives to list selected portions of the macro body 'Nhen the macro is expanded:
. MACRO LTEST
;List test
A-this line should list
;Listing level count is O.
. NLIST
;Listing level count is -1.
B-this line should not list
.NLIST
;Listing level count is -2.
C-this line should not list
.LIST
; Listing level count is -1.
D-this line should not list
. LIST
;Listing level count is O.
E-this line should list
;Listing level count is O.
F-this line should list
;Listing level count is O.
G-this line should list
;Listing level count is O.
.ENDM

.LIST ME
LTEST
A-this line should list
E-this line should list
F-this line should list
G-this line should list

;List macro expansion.
;Call the macro
;Listing level count is O.
;Listing level count is O.
; Listing level count is O.
;Listing level count is O.

Note that the lines following line E will list because the listing level count remains O.
If a . LIST ME directive is placed at the beginning of a program, all macro expansions
will be listed unless a . NLIST directive is encountered.

6-6

PDP-ll MACRO-ll Language Reference Manual

An important purpose of the level count is to allow macro expansions to be listed
selectively and yet exit with the listing level count restored to the value existing prior
to the macro calL
When used with arguments, the listing directives do not alter the listing level count.
However, the. LIST and. NLIST directives can be used to override current listing control,
as shown in the example below:
. MACRO

.LIST

;List next line.

.NLIST

;Do not list remainder of macro
; expansion .

X=.

. ENDM
.NLIST
XX

;Do not list macro expansions.

X=.

Table 6-2 describes the symbolic arguments you can use with . LIST and . NLIST. These
arguments can be used singly or in combination with each other. If multiple arguments
are specified in a listing directive, each argument must be separated by a comma, tab,
or space. For any argument not specifically included in the control statement, the
associated default assumption (List or No List) is applicable throughout the source
program. The default assumptions for the listing control directives also appear in
Table 6-2.
Table 6-2:

Symbolic Arguments of Listing Control Directives

Argument

Default

Function

BEX

List

Controls the listing of binary extensions (the locations and
binary contents beyond those that will fit on the source
statement line). This is a subset of the BIN argument.

List

Controls the listing of generated binary code. If this field is
suppressed through a . NLIST BIN directive, left-justification of
the source code field occurs in the same manner described
above for the LOC field.

CND

List

Controls the listing of unsatisfied conditional coding and
associated . IF and . ENDC directives in the source program.
A . NLIST CND directive lists only satisfied conditional coding.

COM

List

Controls the listing of comments. This is a subset of the SRC
argument. The . NLIST COM directive reduces listing time and
space when comments are not desired.

1If the .NLIST arguments SEQ, LOC, BIN, and SRC are in effect at the same time, that is, if all four significant fields in the listing are
to be suppressed, the printing of the resulting blank line is inhibited.

General Assembler Directives

6-7

Table 6-2 (Cont.):

Symbolic Arguments of Listing Control Directives

Argument

Default

Function

HEX

No list

Controls radix used for assembly listing.
If you- specify
. LIST HEX, addresses and contents are given in hexadecimal,
rather than octal.

List

Controls the listing of the current location counter field.
Normally, this field is not suppressed. However, if it is
suppressed through the . NLIST LOC directive, MACRO-II does
not generate a tab, nor does it allocate space for the field,
as is the case with the SEQ field described above. Thus, the
suppression of the current location counter (LOC) field effectively
left-justifies all subsequent fields (while preserving positional
relationships) to the position normally occupied by the counter's
field.

List

Controls the listing of macro calls and repeat range expansions.

List

Controls the listing of macro definitions and repeat range
expansions.

No list

Controls the listing of macro expansions.

MEB

No list

Controls the listing of macro expansion binary code.
A
. LIST MEB directive lists only those macro expansion statements
that generate binary code. This is a subset of the ME argument.

List

Controls the listing of the sequential numbers assigned
If this number field is suppressed
to the source lines.
through a . NLIST SEQ directive, MACRO-II generates a
tab, effectively allocating blank space for the field. Thus,
the positional relationships of the other fields in the listing
remain undisturbed. During the assembly process, MACRO-II
examines each source line for possible error conditions. For any
line in error, the error code is printed preceding the number
field. (MACRO-II does not assign line numbers to files that
have had line numbers assigned by an editor such as 50S.)

SRC 1

List

Controls the listing of source lines.

SYM

List

Controls the listing of the symbol table resulting from the
assembly of the source program.

TOC

List

Controls the listing of the table of contents during assembly
pass 1 (see Section 6.1.3 describing the . SBTTL directive). This
argument does not affect the printing of the full assembly listing
during assembly pass 2.

TTM

No list

Controls the listing output format. The default is set to line
printer format. Figure 6-1 illustrates line printer output format;
Figure 6-2 illustrates terminal output format.

6-8

PDP-ll MACRO-ll Language Reference Manual

If you use an argument in a . LIST/. NLIST directive other than those listed in Table 6-2,
the directive is flagged with an error code (A) in the assembly listing.

You can also specify the listing control options at assembly time through qualifiers
included in the command string to MACRO-11 (see Table 8-3 and/or the appropriate
systern Inanual). The use of these qualifiers overrides all corresponding listing control
( . LIST or . NLIST) directives specified in the source program.
Figure 6-3 shows a listing produced in line printer format that shows the use of . LIST
and. NLIST directives in the source program and the effects the directives have on the
assembly listing output.
Figure 6-3:

Listing Produced with Listing Control Directives

.TITLE

LISTING CONTROL EXAMPLE

2
3

.LIST

;List macro expansions

; Listing control test macro

7
8

.MACRO
.NLIST
. WORD
.LIST
.ENDM

10
11

12
13
14
15 000000
000001
000004

000002

.NLIST
. WORD

000003

16
17 000010
.NLIST
.WORD

000010

BIN
1,2,3,4

LSTMAC ARG
ARG
1,2,3,4
ARG

LSTMAC LOC
LOC
1,2,3,4
.LIST

LOC

LSTMAC

BIN

;This is a test comment

;Location counter test
;This is a test comment

;Generated binary test

;This is a test commen.t
.LIST
BIN

19 000020
000020

000001

000002

000003

20
21 000030
000030
000036

000001
000004

000002

000003

LSTMAC BEX
.NLIST BEX
.WORD
1,2,3,4
.LIST
BEX

;Binary extensions test

LSTMAC

SRC

;Source lines test

.LIST

SRC

LSTMAC
.NLIST
. WORD

COM
COM
1,2,3,4

.LIST

COM

LSTMAC
.NLIST
. WORD
.LIST

<COM,BEX>
COM,BEX
1,2,3,4
COM,BEX

;This is a test comment

23 000040
000040
000046

000001
000004

000002

000003

24
25 000050
000050

000001

000002

000003

;Comment lines test

;Comment lines and extended binary test

Figure 6-3 Cont'd. on next page

General Assembler Directives

6-9

Figure 6-3 (Cont.):

.LIST

27
28
29 000060
000060
000062
000064
000066

000001
000002
000003
000004

30
31 000070

000070
32
33

Listing Produced with Listing Control Directives

000001
000001

TTM

LSTMAC SEQ
.NLIST SEQ
. WORD 1,2,3,4

;Enable narrow listing
;Sequence numbers test
; This is a test comment

. LIST

SEQ

LSTMAC
.NLIST
. WORD
.LIST

BEX
BEX

;Binary extensions test

1,2,3,4

;This is a test comment

BEX

. END

6.1.2 .TITLE Directive
Format:
.TITLE string

where:
string

represents an identifier of from one to six Radix-SO characters. The identifier
can be followed by a string of one or more 7-bit ASCII or S··bit DEC
Multinational printing characters plus space and horizontal tab. Any MCS
character must be preceded by six Radix-SO characters. Characters after
the first 31 10 do not appear in the title line of the listing,

Section A,I contains a table that includes all MCS characters, Section A.2 contains a
table of Radix-50 characters.
The . TITLE directive assigns a name to the object utodule, The name assigned is
the first six nonblank Radix-50 characters following the. TITLE directive. MACRO-II
ignores all spaces and/or tabs up to the first nonspace/nontab character following the
. TITLE directive, Any characters beyond the first six Radix-50 characters are optional,
and are checked only for MCS validity.
The name of an object module (specified in the . TITLE directive) appears in the load
map produced at link time. This is also the module name which the Librarian will
recognize.
If the . TITLE directive is not specified, MACRO-II assigns the default name . MAIN.
to the object module. If more than one . TITLE directive is specified in the source

program, the last . TITLE directive encountered during assembly pass 1 establishes the
name for the entire object module.
If the . TITLE directive is specified without an object :module name, or if the first

nonspace/nontab character in the object nlodule name is not Radix-50 character, the
directive is flagged with an error code (A) in the assembly listing; some combinations
of invalid characters may also give a (Q) error.

6-1 0

PDP-ll MACRO-ll Language Reference Manual

6.1.3 .SBTTl Directive
Format:
.SBTTL string

where:
represents an identifier of one or more 7-bit ASCII or 8-bit DEC
Multinational printing characters plus space and horizontal tab. Only
the first 8010 characters appear in the subtitle line of the listing, although
. SBTTL strings up to the full width of the line appear on the contents page.

string

The text strings following . SBTTL directives produce a table of contents listing
immediately preceding the assembly listing. The text following each . SBTTL directive
also prints as the second line of the header of each page in the listing following the
. SBTTL directive. The subheading is listed until altered by a subsequent. SBTTL directive
in the program. For example, the directive:
.SBTTL

Conditional assemblies

prints the text:
Conditional assemblies

as the second line in the header of the assembly listing.
During assembly pass I, a table of contents containing the line sequence number,
the page number, and the text accompanying each . SBTTL directive is printed for
the assembly listing. The listing of the table of contents is suppressed whenever a
. NLIST TOC directive is encountered in the source program (see Table 6-2). An example
of a table of contents listing is shbwn in Figure 6-4.
Figure 6-4:

Assembly Listing Table of Contents

MTTEMT - RT--ll MULTI-TTY EMT SE
Table of contents
50-'
51-'
52-'
54-'
55-'
56-'
575859-60-62-63--

1
1
1
1
1
1
1
1
1
1
1
1

MACRO V05.04

Tuesday 02-Jun-87 15:47

.MTOUT - Single character output EMT
.MTRCTO - Reset CTRL/O EMT
.MTATCH - Attach to terminal EMT
.MTDTCH - Detach from a terminal EMT
.MTPRNT - Print message EMT
.MTSTAT - Return multi-terminal system status EMT
MTTIN - Single character input
MTTGET - Get a character from the ring buffer
TTRSET - Reset terminal status bits'
MTTPUT - Single character output
MTRSET - Stop and detach all terminals attached to a job
ESCAPE SEQUENCE TEST SUBROUTINE

General Assembler Directives

6-11

6.1.4 .1 DENT Directive
Format:
.IDENT

Istringl

where:
string

represents a string of six or fewer Radix-50 characters which establish the
program identification or version number. This string is included in the
global symbol directory of the object module and is printed in the link map
and Librarian listing.

/ ... /

represent delimiting characters. These delimiters can be any paired printing
characters other than the colon (:) and left angle bracket ( <), as long as
the delimiting character is not contained within the text string itself. The
equal sign (=) and the semicolon (;) can be used with caution, as explained
in Section 6.3.4. If the delimiting characters do not match, or if an invalid
delimiting character is used, the directive is flagged with an error code (A)
in the assembly listing.

In addition to the name assigned to the object module with the . TITLE directive (see
Section 6.1.3), the . IDENT directive allows you to label the object module with the
program version number.
An example of the . IDENT directive is shown below:
.IDENT IV01.001

The character string is converted to Radix-50 representation and is included in the
global symbol directory of the object module. This character string also appears in the
link map produced at link time and the Librarian directory listings.
When more than one . IDENT directive is encountered in a given program, the last such
directive encountered establishes the character string which forms part of the object
module identification 1 .
The RSX-11M Task Builder allows a . IDENT string for each module in the program. The
Task Builder uses the first . IDENT directive in each module to establish the character
string that will be identified with that module. Like the RT-11 Linker, the RSX-11M
Task Builder uses the. IDENT directives encountered on the first pass.

6.1.5 .PAGE Directive/Page Ejection
Format:
. PAGE

The . PAGE directive is used within the source program to start the listing on a new
page at desired points in the listing. This directive takes no arguments and causes
a skip to the top of the next page when encountered. It also increments the page
number and (under RT-11) clears the line sequence counter. The . PAGE directive does
not appear in the listing.
1 The RT -11 Linker allows only one .IDENT string in a program. The Linker uses the first .IDENT directive encountered during the first pass to
establish the character string that will be identified with all of the object modules.

6-12 PDP-ll MACRO-ll Language Reference Manual

When used within a macro definition, the. PAGE directive js ignored during the assembly
of the macro definition. Rather, the page eject operation is performed as the macro
itself is expanded. In this case, the page number is also incremented. . PAGE directives
in unexpanded macros are ignored.
Page ejection is accomplished in three other ways:
•

After reaching a count of 58 lines in the listing, MACRO-II automatically performs
a page eject to skip over page perforations on line printer paper and to formulate
ternlinal output into pages. The page number is not changed.

•

A page eject is performed when a form feed character is encountered. If the form
feed character appears within a macro definition, a page eject occurs during the
assembly of the macro definition, but not during the expansion of the macro itself.
A page eject resulting from the use of the form feed character increments the page
nunlber and (under RT -11) clears the line sequence counter.

•

A page eject is performed when a new source file is encountered. In this case, the
page number is incremented and the line sequence count reset.

If the listing is already at top-of-page, no action is taken.

6.1.6 .REM Directive/Begin Remark Lines
Format:
.REM comment-character

where:
comment-character

represents a 7-bit ASCII or 8-bit DEC Multinational character that
marks the end of the comment block when the character recurs.

The . REM directive lets you insert a block of comments into a MACRO-II source
,program without having to precede the comment lines with the comment character
(;). The text between the specified delimiting characters is treated as comments. The
comlnents can span any number of lines. The following example uses ampersand (&)
as the delimiting character:
.TITLE
Remark example
. REM
&
All the text that resides here is interpreted by MACRO--ll
to be comment lines until another ampersand character is
found. Any character can be used in place of the ampersand.&
CLR
PC
.END

6.2 Function Directives
The following function directives are included in a source program to invoke or inhibit
certain MACRO--ll functions and operations incidental to the assembly process itself.

General Assembler Directives

6-1 3

6.2.1 .ENABL and .DSABL Directives
Format:
.ENABL
. DSABL

arg
arg

where:
arg

represents one or more of the optional symbolic arguments defined in
Table 6-3.

If you specify any argument in a . ENABL/. DSABL directive other than those listed in
Table 6-3, the line will be flagged with an error code (A) in the assembly listing.

Table 6-3:

6-14

Symbolic Arguments of Function Control Directives

Argument

Default

Function

ABS

Disable

Enabling this function produces output in absolute binary (. LDA)
format.

AMA

Disable

Enabling this function causes all relative addresses (address
mode 67) to be assembled as absolute addresses (address mode
37). This function is useful during the debugging phase of
program development.

CDR

Disable

Enabling this function causes source columns from 73 to the end
of the line to be treated as a comment. The most common use
of this feature is to permit sequence numbers in card columns
73 to 80.

CRF

Enable

Disabling this function inhibits the generation of cross-reference
output. This function has meaning only if cross-reference
output generation is specified in the command string.

FPT

Disable

Enabling this function causes floating-point truncation;
disabling this function causes floating-point rounding.

GBL

Enable

Disabling this function causes MACRO-tt to mark all
undefined references in assembly pass 2 with a (U) error in
the assembly listing. The default for this option is Enable, so
MACRO-tt normally treats all undefined symbol references as
global, allowing the Linker to resolve them.

Enable

Disabling this function causes MACRO-tt to convert all ASCII
input to uppercase before processing it. An example of the
. ENABL LC and . DSABL LC directives, as typically used in a
source program, is shown in Figure 6-5.

LCM

Disable

Enabling this function causes the MACRO-1t conditional
assembly directives . IF IDN and . IF DIF to be alphabetically
case sensitive. By default, these directives are not case sensitive.

PDP-ll MACRO-ll Language Reference Manual

Table 6-3 (Cont.):

Symbolic Arguments of Function Control Directives

Argument

Default

Function

LSB

Disable

This argument permits the enabling or disabling of a local
symbol block. Although a local symbol block is normally
established by encountering a new symbolic label, a . PSECT
directive, or a . RESTORE directive in the source program,
a . ENABL LSB directive establishes a new local symbol
block which is not terminated until another . ENABL LSB is
encountered, or another symbolic label, . PSECT directive,
or . RESTORE directive is encountered following a paired
. DSABL LSB directive.

.--------.-----------------------------------------------.--------------

The basic function of this directive with regard to . PSECT is
limited to those instances where it is desirable to leave a
program section temporarily to store data, followed by a return
to the original program section. This temporary dismissal of the
current program section can also be accomplished through the
. SAVE and . RESTORE directives (see Sections 6.7.3 and 6.7.4).
Attempts to define local symbols in an alternate program section
are flagged with an error code (P) in the assembly listing.
MCL

Disable

Enabling this function causes MACRO-II to search all known
macro libraries for a macro definition that matches any
undefined symbols appearing in the op code field of a MACRO11 statement. By default, this option is disabled. If MACRO11 finds an unknown symbol in the op code field, it either
declares a (U) undefined symbol error or declares the symbol
an external symbol, depending on the . ENABL/ . DSABL setting
of GBL.

PNC

Enable

Disabling this function inhibits binary output until a . ENABL PNC
statement is encountered within the same module.

REG

Enable

Disabling this function inhibits the normal MACRO·-ll default
register definitions. The default register definitions are listed
below:

RO=%O
R1=%1
R2=%2
R3=%3
R4:=%4
R5=%5
SP=%6

PC:=%7
The. ENABL REG directive can be used as the logical complement
of the . DSABL REG directive. The use of these directives,
however, is not recommended. For logical consistency, use
the normal default register definitions listed above.

General Assembler Directives

6-1 5

Figure 6-5:

Example of .ENABL and .DSABL Directives

.ENABL/.DSABL MACRO V05.04

Wednesday 03-Jun-87 09:48
.TITLE

Page 1
.ENABL/.DSABL

2
3

; ILLUSTRATE .ENABL/.DSABL LC

5
6
7

.ENABL LC

8
9

. MACRO

10
11

12
13
14
15

TEXT
. ASCII
. EVEN
.ENDM

;Store macro in lowercase

•••
/This ••• a lowercase stringl

.LIST ME
.NLIST BEX

17 000000
000000

124

18
19
20
21 000032
000032
22
23

150

151

TEXT
.ASCII
. EVEN

is
; Call macro :in lowercase mode
/This is a lowercase string/

.DSABL LC
124

110

111

000001

TEXT
.ASCII
. EVEN

;Now disable lowercase mode

WAS
;CALL MACRO AGAIN IN UPPERCASE
/THIS WAS A LOWERCASE STRINGI

.END

6.2.2 Cross-Reference Directives: .CROSS and .NOCROSS
Format:
. CROSS
.CROSS syml.sym2 .... symn
. NOCROSS
.NOCROSS syml.sym2 .... symn

where:
symI, sym2, ... symn

represent valid symbolic nanles. When multiple symbols are
specified, they are separated by any valid separator (comma,
space, and/or tab).

The . CROSS and the . NOCROSS directives control which symbols are included in the
cross-reference listing produced by the MACRO-11 assembler. These directives have
an effect only if the IC [R] or the ICROSS qualifier was used in the command line to
select the cross-reference capability.
By default, the cross-reference listing includes the definition and all the references to
every user symbol in the module. The cross-reference listing can be disabled for all
symbols or for a specified list of symbols.
When the . NOCROSS directive is used without a symbol list, the cross-reference listing
of all the symbols in the module is disabled. The cross-reference listing of all the
symbols in the module is reenabled when the . CROSS directive is used without a symbol
list. Any symbol definition or reference that appears after a . NOCROSS directive that is
used without a symbol list and before the next . CROSS directive that is used without a
symbol list is excluded from the cross-reference listing.

6-16

PDP-ll MACRO-ll Language Reference Manual

The . NOCROSS directive used with a symbol list disables the cross-reference listing
for the listed symbols. When the . CROSS directive is used with a symbol list, the
cross-reference listing of the listed symbols is reenabled.
In the following example, the definition of LABEL! and the reference to LOC! and LOC2
are not included in the cross-reference listing .
. NOCROSS
LABEL!: MOV
LOC!.LOC2
. CROSS

;Stop cross reference
;Copy data
;Reenable cross reference

In the next .example, the definition of LABEL2 and the reference to LOC2 are included in
the cross reference, but the reference to LOC! is not included.
.NOCROSS LOC1
LABEL2: MOV
LOC1.LOC2
.CROSS LOC!

;Do not cross reference LOC!
;Copy data
;Reenable cross reference
; of LOC1.

The . CROSS directive used without a symbol list cannot be used to reenable the crossreference listing of a symbol specified in the symbol list of a . NOCROSS directive. In
addition, if the cross-reference listing of all the symbols in a module is disabled, the
. CROSS directive used with a symbol list will have no effect until the cross-reference
listing is reenabled by the . CROSS directive used without a symbol list.
The . CROSS directive with no symbol list is equivalent to the . ENABL CRF directive, and
the . NOCROSS directive with no symbol list is equivalent to the. DSABL CRF directive.

6.3 Data Storage Directives
A wide range of data and data types can be generated with the directives, ASCII
conversion characters, and radix-control operators described in the following sections.

6.3:1 .BYTE Directive
Format:
.BYTEexp
. BYTE

;Stores the binary value of the
;expression in the next byte .

exp1.exp2.expn ;Stores the binary values of the list
;of expressions in successive bytes.

where:
expl, exp2, ... expn

represent expressions that must 'be reduced to eight bits of
data or less. Each expression will be read as. a 16-bit word
expression, the high-order byte to be truncated. The highorder byte must be all zeros, or a (A) error results. Multiple
expressions must be separated by commas.

The . BYTE directive stores successive bytes of binary data in the object module.

General Assembler Directives

6-1 7

Example:
SAM=5
.=1410
.BYTE

;The value 060 (octal equivalent of 48
;decimal) is stored in location 1410.
;The value 005 is stored in location
; 1411.

~D48,SAM

The construction ~D in the first operand of the . BYTE directive above illustrates the use
of a temporary radix-control operator. The function of these special unary operators
is described in Section 6.4.1.2. At link time, it is likely that a relocatable expression
will result in a value having more than eight bits, in which case the Linker or Task
Builder issues a truncation (T) error for the object module in question. For example,
the following statements create such a possibility:
.BYTE 23

;Stores octal 23 in next byte.

.BYTE A

;Relocatable value A will probably
;cause truncation error.

If an expression following the . BYTE directive is null, it is interpreted as a zero:
.=1420
;Zeros are stored in bytes 1420, 1421,
;1422, and 1423.

. BYTE

In the above example, four bytes of storage result from the . BYTE directive. The three
commas in the operand field represent an implicit declaration of four null values, each
separated from the other by a comma. Hence, four bytes, each containing a value of
zero (0), are reserved in the object module.

6.3.2 .WORD Directive
Formats:
. WORD

exp

;Stores the binary equivalent of the
;expression in the next word .

. WORD

exp1,exp2,expn ;Stores the binary equivalents of the
;list of expressions in successive words.

where:
exp1, exp2, ... expn

represent expressions that lnust reduce to 16 bits of data or
less. Multiple expressions m.ust be separated by commas.

The . WORD directive stores successive words of data in the object module.
Example:
SAL=O
.=1500
. WORD

177535, .+4,SAL

;Stores the values 177535, 1506, and
;0 in words 1500, 1502, and 1504,
;respectively.

If an expression following the . WORD directive contains a null value, it is interpreted as
a zero, as shown in the following example:

6-18

PDP-ll MACRO-ll Language Reference Manual

·=1500
. WORD

,5,

;Stores the values 0, 5, and 0 in
;location 1500, 1502, and 1504,
;respectively.

A statement with a blank operator field (one that contains a symbol other than a macro
call, an instruction mnemonic, a MACRO-II directive, or a semicolon) is interpreted
during assembly as an implicit . WORD directive, as shown in the example below:
.=1440
LABEL: 100,LABEL

;Stores the value 100 in location 1440
;and the value 1440 in location 1442.

NOTE
You should not use this technique to generate . WORD
directives because it may not be included in future PDP11 assemblers.

6.3.3 ASCII Conversion Characters
The single quote (') and the double quote (") characters are unary operators that
can appear in any MACRO-II expression. Used in MACRO-II expressions, these
characters generate a 16-bit expression value.
When the single quote is used, MACRO,-ll takes the next character in the expression
and converts it from its 7-bit ASCII or 8-bit DEC Multinational character set value
to a 16-bit expression value. The high-order byte of the resulting expression value
is always zero (0). The 16-bit value is then used as an absolute term within the
expression. For example, the statement:
MOV

#'A,RO

moves the 16-bit binary expression value:
10000oooo10100000~

into register O. (01000001 2 is the binary value of ASCII A.)
Thus, the expression ' A results in a value of 101 8 ,
The single quote (') character must not be followed by a carriage return, null, RUBOUT,
line feed, or form feed character; if it is, an error code (A) is generated in the assembly
listing. When the double quote is used, MACRO-II converts the next two characters
in the expression to a 16-bit binary expression value from their 7-bit ASCII or 8-bit
DEC Multinational values. This 16-bit value is then used as an absolute term within
the expression. For example, the statement:
MOV

#"AB,RO

moves the 16-bit expression value:
~001010100000JJ

into register O. (0100001001000001 2 is the concatenated binary byte values of the
ASCII characters A and B.)

General Assembler Directives

6-1 9

Thus, the expression "AB results in a value of 041101 8 ,
The double quote (") character, like the single quote (') character, must not be followed
by a carriage-return, null, RUBOUT, line-feed, or form-feed character; if it is, an error
code (A) is generated in the assembly listing.
The DEC Multinational character set is listed in Section A.l.

6.3.4 .ASCII Directive
Format:
.ASCII

/string 1/ ... /string n/

where:
string

is a string of 7-bit ASCII or 8-bit DEC Multinational printing characters, plus
space and horizontal tab. All nonprinting characters except carriage return
and form feed cause an error code (I) if used in a . ASCII string. Carriage
return and form feed characters are flagged with an error code (A) because
they end the scan of the line, preventing MACRO-II from detecting the
matching delimiter at the end of the character string.

/ ... /

represent delimiting characters. These delimiters can be any paired printing
characters other than the colon (:) and left angle bracket ( <), as long as
the delimiting character is not contained within the text string itself. The
equal sign (=:;) and the semicolon (;) can be used with caution, as explained
below. If the delimiting characters do not match, or if an invalid delimiting
character is used, the directive is flagged with an error code (A) in the
assembly listing.

The .ASCII directive translates character strings into their 7-bit ASCII or 8-bit DEC
Multinational equivalents and stores them in the object module. A nonprinting
character can be expressed only by enclosing its equivalent octal value within angle
brackets. Each set of angle brackets so used represents a single character. For example,
in the following statement:
.ASCII

<15>/ABC/<A+2>/DEF/<5><4>

the expressions <15>, <A+2>, <5>, and <4> represent the values of non printing characters.
Each bracketed expression must reduce to eight bits of absolute data or less. The
expression cannot contain any global symbols.
Angle brackets can be embedded between delimiting characters in the character string,
but angle brackets so used do not take on their usual significance as delimiters for
nonprinting characters. For example, the statement:
.ASCII

/ABC<expression>DEF/

contains a single ASCII character string, and performs no evaluation of the embedded,
bracketed expression. This use of the angle brackets is shown in the third example of
the .ASCII directive below:
.ASCII

/HELLO/

6-20 PDP-ll MACRO-ll Language Reference Manual

;Stores the binary representation
;of the letters HELLO in five
;consecutive bytes.

.ASCII

/ABC/<15><12>/DEF/ ;Stores the binary representation
;of the characters A.B.C.carriage
; return. line feed.D.E.F in eight
;consecutive bytes .

. ASCII

/A<15>B/

;Stores the binary representation
;of the characters A. <. 1. 5. >.
;and B in six consecutive bytes.

The colon (:) character can never be used as a delimiting character. The semicolon
(;) and equal sign (=) can be used as delimiting characters in the string, but care
must be exercised in so doing because of their significance as a comment indicator and
assignnlent operator, respectively, as illustrated in the examples below:
.ASCII ;ABC;/DEF/

;Stores the binary representation of
;the characters A. B. C. D. E. and
;F in six consecutive bytes;
;not recommended practice .

. ASCII /ABC/;DEF;

;Stores the binary representations of
;the characters A. B. and C in three
;consecutive bytes; the characters D.
;E. F. and; are treated as a comment .

. ASCII /ABC/=DEF=

;Stores the binary representation of
;the characters A. B. C. D. E. and
;F in six consecutive bytes;
;not recommended practice.

An equal sign is treated as an assignment operator when it appears as the first character
in the ASCII string, as illustrated by the following example:
.ASCII =:DEF=

;The direct assignment operation
; .ASCII=DEF is performed. and a
;syntax error (Q) is generated upon
; encountering the second = sign.

6.3.5 .ASCIZ Directive
Format:
.ASCIZ

/string 1/ ... /string n/

where:
string

is a string of 7-bit ASCII or 8-bit DEC Multinational printing characters, plus
space and horizontal tab . All nonprinting characters except carriage return
and form feed cause an error code (I) if used in a . ASCII string. Carriage
return and form feed characters are flagged with an error code (A) because
they end the scan of the line, preventing MACRO-II from detecting the
matching delimiter at the end of the character string.

General Assembler Directives

6-21

/ ... /

The . ASCIZ directive is similar to the . ASCII directive described above, except that a
zero byte is automatically inserted as the final character of the string. Thus, when
a list or text string has been created with a . ASCIZ directive, a search for the null
character in the last byte can effectively determine the end of the string, as reflected
in the example below:

HELLO:

10$:

CR=15
LF=12
.ASCIZ
. EVEN

<CR><LF>/MACRO--ll V05.00/<CR><LF>

MOV
MOV
MOVB
BNE

#HELLO,Rl
#LINBUF,R2
(Rl) +, (R2) +
10$

; Introductory message

;Get address of message.
;Get address of output buffer.
;Move a byte to output buffer.
;If not null, move a.nother byte.

6.3.6 .RAD50 Directive
Format:
.RAD50

/string 1/ ... /string n/

where:
string

represents a series of characters to be packed. The string must consist of the
characters A through Z, 0 through 9, dollar sign ($), period (.) and space
( ). An invalid printing character causes an error flag (Q) to be printed in
the assembly listing.
If fewer than three characters are to be packed, the string is packed left-

justified within the word, and trailing spaces are assumed.
All nonprinting characters except carriage return and form feed cause an
error code (I) if used in a . ASCII string. Carriage return and form feed
characters are flagged with an error code (A) because they end the scan of
the line, preventing MACRO-11 from detecting the matching delimiter at
the end of the character string.

6-22

PDP-ll MACRO-l1 Language Reference Manual

/ ... /

The . RAD50 directive generates data in Radix-50 packed format. Radix-50 form allows
three characters to be packed into 16 bits (one word); therefore, any 6-character
symbol can be stored in two consecutive words. Examples of . RAD50 directives are
shown below:
.RAD50 IABCI
. RAD50 IABI
. RAD50 IABCDI

;Packs ABC into one word .
;Packs AB (SPACE) into one word .
;Packs ABC into first word and
;D (SPACE) (SPACE) into second word .
. RAD50 IABCDEFI ;Packs ABC into first word, DEF into
;second word.

Each character is translated into its Radix-50 equivalent, as indicated in the following
table:
Character

Radix-50 Octal Equivalent

(space)

A-Z

01-32

33
34

(undefined)

0-9

36-47

The Radix-50 equivalents for characters 1 through 3 (C1,C2,C3) are combined as
follows:
Radix-50 value == «C1*50 8)+C2)*50 8+C3
For example:
Radix-50 value of ABC = «1 *508)+2)*5°8+3 = 3223 8
Refer to Section A.2 for a table of Radix-50 equivalents.
Angle brackets ( < > ) must be used in the . RAD50 directive whenever special codes
are to be inserted in the text string, as shown in the example below:

General Assembler Directives

6-23

.RAD50
CHR1=1
CHR2=2
CHR3=3

IAB/<35> ;Stores 3255 in one word.

.RAD50 <CHR1><CHR2><CHR3> ;Equivalent to .RAD50 IABC/.

6.3.7 Temporary Radix-50 Control Operator
Format:

where:
ccc

represents a maximum of three characters to be converted to a 16-bit Radix50 value. If more than three characters are specified, any following the third
character are ignored. If fewer than three are specified, the trailing characters
are assumed to be blanks.

The AR operator converts its argument to Radix-50 fannat. This allows up to three
characters to be stored in one word. If you use AR with no argument, MACRO-II
generates a word of O.
The following example shows how the AR operator might be used to pack a 3-character
file type specifier (MAC) into a single I6-bit word.
MOV #ARMAC,FILEXT

;Store RAD50 MAC as file extension

The number sign (#) indicates immediate data (data. to be assembled directly into
object code). AR specifies that the characters MAC are to be converted to Radix-50.
This value is then stored in location FILEXT.

6.3.8 .PACKED Directive
Format:
.PACKED decimal-string[,symbol]

where:
decimal-string

represents a decimal number from 0 to 3110 digits long. Each digit must
be in the range 0 to 9. The number can have a sign, but it is not required
and is not counted as a digit in the total of 31 10 ,

symbol

is assigned a value equivalent to the number of decimal digits in the
string.

The. PACKED directive generates packed decimal data, four bits per digit (two digits per
byte) plus a 4-bit sign designator. The sign designator can have one of three values:

6-24

PDP-ll MACRO-ll Language Reference Manual

1100 2

Positive

1101 2

Negative

11112

Unsigned

Arithmetic and operational properties of packed decimals are similar to those of numeric
strings. Figure 6-6 is an example of the . PACKED directive.
Figure 6-6:

Example of the .PACKED Directive

:1
. LIST BEX
2 000000
017
3 000001
014
4 000002
015
5 000003
037
6 000004
034
'7 000005
035
8 000006
001
000007
057
9 000010
001
000011
054
10 000012
001
000013
055
11 000014
001
000015
043
000016
105
000017
147
000020
211
000021
017
12 000022
001
000023
043
000024
105
000025
147
000026
211
00002"
014
13 000030
001
000031
043
000032
105
000033
147
000034
211
000035
015
14
. EVEN
15
. END
16 000001

. PACKED 0, UOLEN
.PACKED +0, POLEN
.PACKED -0, NOLEN
. PACKED 1, U1LEN
. PACKED +1, P1LEN
. PACKED -1, N1LEN
. PACKED 12, U12LEN
. PACKED +12, P12LEN
. PACKED -12, N12LEN
. PACKED

1234567890, UXLEN

.PACKED +1234567890, PXLEN

.PACKED -1234567890, NXLEN

Symbol table
NXLEN :: 000012
NOLEN = 000001
N1LEN = 000001
N12LEN= 000002

PXLEN = 000012
POLEN :: 000001
P1LEN = 000001
P12LEN= 000002

UXLEN = 000012
UOLEN = 000001
U1LEN = 000001
U12LEN= 000002

General Assembler Directives

6-25

6.4 Radix and Numeric Control Facilities
6.4.1 Radix Control and Unary Control Operators
Any numeric or expression value in a MACRO-II source program is read as an octal
value by default. Occasionally, however, an alternate radix is useful. By using the
MACRO-II facilities described below, you can declare a radix to affect a term or an
entire program depending on your needs.
NOTE
When two or more unary operators appear together,
modifying the same term, the operators are applied to
the term from right to left.
6.4.1.1 .RADIX Directive

Format:
.RADIX

where:
represents one of the radices 2, 8, 10, or 16. Any value other than null or one
of the acceptable radices is flagged with an error code (A) in the assembly
listing. If no argument is specified, the octal default radix is assumed. The
argument (n) is always read as a decimal value.

Numbers used in a MACRO-II source program are initially assumed to be octal
values; however, with the. RADIX directive you can declare alternate radices applicable
throughout the source program or within specific portions of the program.
Any alternate radix declared in the source program through the. RADIX directive remains
in effect until altered by the occurrence of another such directive, for example:
.RADIX 10

;Begins a section of code having a
;decimal radix .

. RADIX

;Reverts to octal radix.

In general, macro definitions should not contain or rely on radix settings established
with the . RADIX directive. Rather, temporary radix control operators should be used
within a macro definition. Where a possible radix conflict exists within a macro
definition or source program, specify numeric or expression values using the temporary
radix control operators described below.
NOTE
All hexadecimal values used with . RADIX 16 must begin
with a digit, which can be O.
For example, the
hexadecimal value F3 must be written as OF3. Otherwise,
MACRO-II assumes the item is a symbolic name, not a
hexadecimal number.

6-26

PDP-ll MACRO-ll Language Reference Manual

6.4.1.2 Temporary Radix Control Operators

Formats:
n is evalua.ted as a binary number
n is evalua.ted as a decimal number
n is evaluated as an octal number
n is evaluated as a hexadecimal number

These unary operators establish an alternate radix for a single term. A temporary
alternate is useful because, after you have specified a radix for a section of code or
have decided to use the default octal radix, you may discover a number of cases
where an alternate radix is more convenient or desirable (particularly within macro
definitions). Creating a mask word (used to check bit status), for example, might be
accomplished best through the use of a binary radix.
An alternate radix can be declared temporarily to meet a localized requirement in the
source program., The temporary radix control operator can be used any time regardless
of the radix in effect or other radix declarations within the program. Because the
operator affects only the term immediately following it, it can be used anywhere a
nUITleric value is valid. The term (or expression) associated with the temporary radix
control operator is evaluated during assembly as a 16-bit entity.
The expressions below are representative of the methods of specifying temporary radix
control operators:
~D123

Decimal Radix

a 47

Octal Radix

00001101

Binary Radix

AO<A+13>

Octal Radix

"XOF3

Hexadecimal Radix

The circumflex and the radix control operator cannot be separated, but the radix control
operator and the following term or expression can be separated by spaces or tabs for
legibility or formatting. A multielement term or expression that is to be interpreted in
an alternate radix should be enclosed within angle brackets, as shown in the last of
the four temporary radix control expressions above.
The following example also illustrates the use of angle brackets to delimit an expression
that is to be interpreted in an alternate radix. When the temporary radix control operator
is used, only numeric values are affected. Any symbols used with the operator are
evaluated with respect to the radix in effect at their declaration:
.RADIX 10
A=10
.WORD -O<A+10>*10

When the temporary radix expression in the . WORD directive above is evaluated, it
yields the following equivalent statement:
.WORD 180

General Assembler Directives

6-27

MACRO-II also allows a temporary radix change to decimal by specifying a number
immediately followed by a decimal point (.), as shown below:
;Equivalent to 144(octal)
;Equivalent to 2540(octal)
;Equivalent to 200(octal)

100.
1376.
128.

The above expression forms are equivalent in function to:
AD100
AD1376
AD128

NOTE
All hexadecimal values used with AX must begin with
a digit, which can be O. For example, the hexadecimal
value F3 must be written as OF3. Otherwise, MACRO-II
assumes the item is a symbolic name, not a hexadecimal
number.

6.4.2 Numeric Directives and Unary Control Operators
Two storage directives and two numeric control operators are available to simplify the
use of the floating-point hardware on the PDP-II. These facilities allow floating-point
data to be created in the program, and numeric values to be complemented or treated
as floating-point numbers.
A floating-point number is represented by a string of one or more decimal digits.
The string can contain an optional decimal point and can be followed by an optional
exponent indicator in the form of the letter E and a signed decimal integer exponent.
The number cannot contain embedded blanks, tabs, or angle brackets and cannot be
an expression; such a string will result in one or more errors (A and/or Q) in the
assembly listing.
The list of numeric representations below contains seven distinct, valid representations
of the same floating-point number:
3
3.

3.0
3.0EO
3EO
.3E1
300E-2

As can be inferred, the list could be extended indefinitely (3000E-3, .03E2, and so
on). A leading plus sign is optional (3.0 is considered to be +3.0). A leading minus
sign complements the sign bit. No other operators are allowed; for example, 3.0+N is
invalid.

6-28

PDP-ll MACRO-ll Language Reference Manual

All floating-point numbers are evaluated as 64 bits in the following format:
[63162
55154
01
[}ITEEEEEEEEIMMM< ..... MMMI
Sign (1 bit)
Exponent (8 bits)
Mantissa (55 bits)

MACRO-II returns a value of the appropriate size and precision by means of floatingpoint directives. The value returned can be truncated or rounded (see Section 6.2.1).
Floating-point numbers are normally rounded. That is, when a floating-point number
exceeds the limits of the field in which it is to be stored, the high-order bit of the
unretained word is added to the low-order bit of the retained word, as shown below.
For example, if the number is to be stored in a 2-word field, but more than 32 bits
are needed to express its exact value, the highest bit (32) of the unretained field is
added to the least significant bit (0) of the retained field (see illustration below). The
. ENABL FPT directive is used to enable floating-point truncation; . DSABL FPT is used to
return to floating-point rounding (see Table 6-3).

@L
Retained field

0132
01
Unretained field

All numeric operands associated with Floating Point Processor instructions are
automatically evaluated as single-word, decimal, floating-point values unless a
temporary radix control operator is specified. For example, to add (floating) the
constant 41040 8 to the contents of floating accumulator zero, the following instruction
must be used:
ADDF

#A041040,FO

where:

is assumed to represent floating accumulator zero.

Floating-point numbers are described in greater detail in the PDP-II Processor
Handbook.
6.4.2.1 One's Complement Operator: AC
The AC unary operator complements an argument as it is evaluated during assembly.

As with the radix control operators such as AD and AD, the numeric control operator
AC can be used anywhere in the source program that an expression value is valid.
Such a construction is evaluated by MACRO-II as a 16-bit binary value before being
complemented. For example, the following statement:
TAG4:

. WORD

AC151

stores the one's complement of the value 151 8 as a 16-bit value in the program. The
resulting value expressed in octal form is 177626 8 ,

General Assembler Directives

6-29

Because the -c construction is a unary operator, the operator and its argument are
regarded as a term. Thus, more than one unary operator can be applied to a single
term. For example, the following construction:
-C-D25

complements the value 25 10 during assembly.
expressed in octal form, reduces to 177746 8 ,

The resulting binary value, when

The term created through the use of the temporary numeric control operator can
be used alone or in combination with other expression elements. For example, the
following construction:
-C2+6

is equivalent in function to:
<-C2>+6

This expression is evaluated during assembly as the one's complement of 2, plus the
absolute value of 6. When these terms are combined, the resulting expression value
generates a carry beyond the most significant bit, lea.ving 000003 8 as the reduced
value.
6.4.2.2 Floating-Point Storage Directives

Format:
.FLT2
.FLT4

arg1,arg2, ... argn
arg1,arg2, ... argn

where:
argl,arg2, ... argn

represent one or more floating-point numbers as described in
Section 6.4.2. Multiple arguments must be separated by commas .

. FLT2 generates two words of storage for each argument, while . FLT4 generates four
words of storage for each argument. As in the . WORD directive, the arguments are
evaluated and the results stored in the object module.
6.4.2.3 Floating-Point Operator: ~F

The -F unary operator for numeric control lets you specify an argument that is a
I-word floating-point number. For example, the following statement:
A:

MOV

#-F3.7,RO

creates a I-word floating-point number at location A+2 containing the value 3.7
formatted as shown below:
115114
716
01
1 slEEEEEEEEIMMMMMMMI

Sign (1 bit)
Exponent (8 bits)
Man tissa (7 bits)

6-30

PDP-ll MACRO-ll Language Reference Manual

The importance of ordering with respect to unary operators is shown below:
AF1. 0
-F-1. 0
--F1.0
- "'F-1. 0

040200
140200
137600
037600

The value created by the "'F unary operator and its argument is, like -c and its
argument, a term that can be used by itself or in an expression. For example:
"'C"F6.2

is equivalent to:
"'C<-F6.2>

Expressions used as terms or arguments of a unary operator must be explicitly grouped.
As illustrated above and in Section 6.4.2.1, when a temporary numeric control operator
and its argument are coded as a term within an expression, angle brackets should be
used as delimiters to ensure precise evaluation and readability.

6.5 Location Counter Control Directives
The directives used in controlling the value of the current location counter and in
reserving storage space in the object program are described in the following sections.
Several MACRO-I1 statements (listed below) may allocate an odd number of bytes:
•

. BYTE directive

•

. BLKB directive

•

. ASCI I or

•

. ODD directive

•

. PACKED directive

•

A direct assignment statement of the form . =. +expression, which results in the
assignment of an odd address value.

. ABelZ directive

In cases that yield an odd address value, the next instruction on a word boundary
automatically forces the location counter to an even value, but that instruction is
flagged with an error code (B) in the assembly listing.

6.5.1 . EVEN Directive
Fornlat:
. EVEN

The . EVEN directive ensures that the current location counter contains an even value
by adding 1 if the current value is odd. If the current location counter is already even,
no action is taken. Any operands following a . EVEN directive are flagged with an error
code (Q) in the assembly listing.

General Assembler Directives

6-31

The . EVEN directive is used as follows:
.ABelZ /This is a test/
. EVEN
;Ensures that the next statement will
;begin on a word boundary .
. WORD XYZ

6.5.2 .000 Directive
Format:
. ODD

The . ODD directive ensures that the current location counter contains an odd value by
adding 1 if the current value is even. If the current location counter is already odd,
no action is taken. Any operands following a . ODD directive are flagged with an error
code (Q) in the assembly listing.

6.5.3 .BLKB and .BLKW Directives
Format:
.BLKB
.BLKW

exp
exp

where:
exp

represents the specified number of bytes or words to be reserved in the object
program. Any expression that is defined at assembly time and that reduces
to an absolute value is valid. If the expression specified in either of these
directives is not an absolute value, the statement is flagged with an error
code (A) in the assembly listing. Furthermore, if the expression contains a
forward reference (a reference to a symbol that is not previously defined),
MACRO-II generates incorrect object file code and may cause statements
following the . BLKB/ . BLKW directive to be flagged with phase (P) errors.
These directives should not be used without arguments. However, if no
argument is present, a default value of 1 is assumed.

The . BLKB directive reserves byte blocks in the object module; the . BLKW directive
reserves word blocks. Figure 6-7 illustrates the use of the . BLKB and. BLKW directives.

6-32

PDP-ll MACRO-ll Language Reference Manual

Figure 6-7:

Example of .BlKB and .BlKW Directives

1
2

,
,

Illustrate use of .BLKB and .BLKW directives

4 000000

.PSECT

IMPURE,D,GBL,RYV

.BLKW

;Character counter

80.

;Message text buffer

COUNT:

6 000000
7
8 000002

MESSAG: .BLKB

10 000122
11
12 000123
13
14 000124

CHRSAV: .BLKB

;Saved character

FLAG:

;Flag byte

.BLKB

MAGPTR: .BLKW

;Message buffer pOinter

The. BLKB directive in a source program has the same effect as the following statement:
.=.+expression

which adds the value of the expression to the current value of the location counter.
The . BLKB directive, however, is easier to interpret in the context of the source code in
which it appears and is therefore recomlmended.

6.5.4 .LIMIT Directive
Forrrlat:
.LIMIT

To know the upper and lower address boundaries of the image is often desirable.
When the . LIMIT directive is specified in the source program, MACRO-II generates
the following instruction:
.BLKW

and reserves two storage words in the object module. Later, at link time, the lowest
address in the load image (the initial value of SP) is inserted into the first reserved
word, and the address of the first free word following the image is inserted into the
second reserved word.
During linking, the size of the image is rounded upward to the nearest 2-word
boundary.

General Assembler Directives

6-33

6.6 Terminating Directive: .END Directive
Format:
.END

[exp]

where:
exp

represents an optional expression value which, if present, indicates the
program-entry point, which is the transfer address where the program begins.

When MACRO-ll encounters a valid occurrence of the . END directive, it terminates
the current assembly pass. Any text beyond this point in the current source file, or in
additional source files identified in the command line, is ignored.
When an image consisting of several object modules is created, only one object module
can be terminated with a . END exp statement (where exp is the starting address). All
other object modules must be terminated with a . END statement (where . END has no
argument); otherwise, an error message will be issued at link time. If no starting
address is specified in any of the object modules, image execution begins at location 1
of the image and immediately faults because of an odd addressing error.
The . END statement must not be used within a macro expansion or a conditional
assembly block; if it is so used, it is flagged with an error code (0) in the assembly
listing. The. END statement can be used, however, in an immediate conditional
statement (see Section 6.9.3).
If the source program input is not terminated with a . END directive, an error code (E)
results in the assembly listing.

6.7 Program Sectioning Directives
The MACRO-ll program sectioning directives declare names for program sections
(p-sections) and establish certain program section attributes essential to linking.

6-34 PDP-ll MACRO-ll Language Reference Manual

6.7.1 .PSECT Directive
Fornlat:
.PSECT

name,argl,arg2, ... argn

where:
nam.e

represents the symbolic name of the program section, as described
in Table 6-4.
represents any valid separator (comma, tab and/or space).

argl, arg2, ... argn

represent one or more of the valid symbolic arguments defined for
use with the . PSECT directive, as described in Table 6-4. The
slash separating each pair of symbolic arguments listed in the table
indicates that one or the other, but not both, can be specified.
Multiple arguments must be separated by a valid separating character.
Any symbolic argument specified in the . PSECT directive other than
those listed in Table 6-4 will be flagged with an error code (A) in
the assembly listing.

Table 6-4:

Symbolic Arguments o.f .PSECT Directive

Argument

Default

Meaning

NAME

Blank

Establishes the program section name, which is specified as one
to six Radix-50 characters. If this argument is omitted, a comma
must appear in place of the name parameter. The Radix-50
character set is listed in Section A.2.

Defines which type of access is permitted to the program section:
RO = Read··Only Access
RW = Read/Write Access
RT-ll and RSX-IIM use only Read/Write access.

Defines the contents of the program section:
I = Instructions. If a p-section has the I attribute and the
program is overlaid, all calls to the p-section are referenced
through a body of overlay code stored in the root.
If a concatenated p-section has the I attribute, code is
concatenated on even bytes.
D = Data. If a p-section has the D attribute, all calls to the
p-section are referenced directly.
If a concatenated p-section has the D attribute, code is
concatenated on the next byte regardless of whether the byte
is odd or even.

1Where two possible arguments are separated by a slash (/), you can choose one or the other.

General Assembler Directives

6-35

Table 6-4 (Cont.):

Symbolic Arguments of .PSECT Directive

--------------------------

Argument

Default

Meaning

GBL/LCL 1

LCL

Defines the scope of the progratn section, as it will be interpreted
at link time:
LCL = Local. If an object module contains a local program
section, then the storage allocation for that module will remain
in the segment containing the module. Many modules can
contribute (allocate memory) to this same program section;
the memory allocation for each contributing module is either
concatenated or overlaid within the segment, depending on
the allocation argument of the program section (see CON/OVR
below).
GBL = Global. If a global program section is used in more than
one segment of a program, all references to the p-section are
collected across segment boundaries. The program sections
are then stored in the segment (of those originally containing
the p-sections) that is nearest the root.
RT -11 stores the collected p-sections in the root.
The GBL/LCL arguments apply only in the case of overlays;
in building single-segment non overlaid programs, the GBL/LCL
arguments have no meaning, because the total memory allocation
for the program will go into the root segment of the image.

ABS/REL 1

REL

Defines the relocatability attribute of the program section:
ABS = Absolute (non-relocatable). The ABS argument causes the
Linker or Task Builder to treat the p-section as an absolute
module; therefore, no relocation is required. The program
section is assembled and loaded, starting at absolute virtual
address O.
The location of data in absolute program sections must fall
within the virtual memory limits of the segment containing the
program section; otherwise, an error results at link time. For
example, the following code, although valid during assembly,
may generate an error message (A) if virtual location 100000
is outside the segment's virtual address space:
.PSECT

ALPHA,ABS

.=.+100000
. WORD

REL = Relocatable. The REL argument causes the Linker or
Task Builder to treat the p-section as a relocatable module
and a relocation bias is added to all location references within
the program section making the references absolute.

1 Where two possible arguments are separated by a slash (/), you can choose one or the other.

6-36

PDP-ll MACRO-ll Language Reference Manual

Table 6-4 (Cont.):

Symbolic Arguments of .PSECT Directive

Argument

Ddault

Meaning

CON/OVRl

CON

Defines the allocation requirements of the program section:
CON = Concatenated. All references to one program section
are concatenated t,o determine the total memory space needed
for the p-section.
OVR = Overlaid. All references to one program section are
overlaid; the total memory space needed equaling the largest,
individual p-section.

SAV/NOSAV l

NOSAV

Determines where the Linker allocates storage for the program
section:
SAV = Save.
The Linker always forces allocation for the
program section to the root of the image.
NOSAV = No Save. The Linker allocates the program section
normally.

-------------------------------------------------------------------------

1 Where two possible arguments are separated by a slash (/), you can choose one or the other.

is the only position-dependent argument for the . PSECT directive.
omitted, a comma must be used in its place. For example, the directive:

NAME

.PSECT

If NAME is

,GBL

shows a . PSECT directive with a blank name argunlent and the GBL argument. Default
values (see Table 6-4) are assumed for all other unspecified arguments.
The .PSECT directive can be used without a name or arguments (see Section 6.7.1.1).
The ,PSECT directive lets you create program sections (see Section 6.7.1.1) and to share
code and data among the sections you have created (see Section 6.7.1.2). In declaring
the program sections (also called p-sections), you can declare the attributes of the
p-sections. This lets you control memory allocation and at the same time increases
progrmn modularity. (For a discussion of memory allocation, refer to the applicable
system manual--see the Associated Documents section in the Preface.)
MACRO-11 provides for 256 10 progran1 sections, as listed below:
•

One default absolute program section (, ABS,)

•

One default relocatable program section (, BLK.)1

•

254 10 named program sections. (You can have more, but only the first 254 appear
in the symbol table.)

1 In RT-ll, this program section is unnamed.

General Assembler Directives

6-37

For each program section specified or implied, MACRO-11 maintains the following
information:
Program section name
Contents of the current location counter
Maximum location counter value encountered
Program section attributes (described in Table 6-4)
6.7.1.1 Creating Program Sections
The first statement of a source program is always an implied . PSECT directive; this
causes MACRO-11 to begin assembling source statements at relocatable zero of the
unnamed program section.

The first occurrence of a . PSECT directive with a given name assumes that the current
location counter is set at relocatable zero. The scope of this directive then extends
until a directive declaring a different program section is specified. Subsequent . PSECT
directives cause assembly to resume where the named section previously ended; for
example:
A:
B:

C:
X:
Y:
D:

.PSECT
. WORD
. WORD
. WORD
.PSECT
. WORD
. WORD
.PSECT
. WORD

o
o
o
ALPHA

o
o
o

;Declares unnamed relocatable program
;section assembled at relocatable
;addresses 0 through 5.
;Declares relocatable program section
;named ALPHA assembled at relocatable
;addresses 0 through 3.
;Returns to unnamed relocatable
;program section and continues assem;bly at relocatable address 6.

A given program section can be defined completely upon encountering its first . PSECT
directive. Thereafter, the section can be referenced by specifying its name only or by
completely respecifying its attributes. For example, a program section can be declared
through the directive:
.PSECT

ALPHA,ABS,OVR

and later referenced through the equivalent directive:
.PSECT

ALPHA

which requires no arguments. If arguments are specified, they must be identical to
the ones previously declared for the p-section. If the arguments differ, the arguments
of the first . PSECT will remain in effect, and an error code (A) will be generated as a
warning.
By maintaining separate location counters for each program section, MACRO-11
lets you write statements that are not physically sequential but that can be loaded
sequentially following assembly, as shown in the following example.

6-38 PDP-ll MACRO-ll Language Reference Manual

A:
B:
C:
ST:

.PSECT
. WORD
. WORD
. WORD
CLR
CLR
CLR
.PSECT

SEC1,REL,RO
0
0
0
A
B
C
SECA,ABS

. WORD
.PSECT
INC
BR

. +2,A
SECl
A
ST

;Start a relocatable program section
;named SECl assembled at relocatable
;addresses 0 through 5.
;Assemble code at relocatable
;addresses 6 through 21(octal).
;Start an absolute program section
;named SECA . Assemble code at
;absolute addresses 0 through 3.
;Resume relocatable program section
;SEC1. Assemble code at relocatable
;addresses ~2 through 27(octal).

All labels in an absolute program section are absolute; likewise, all labels in a relocatable
section are relocatable. The current location counter symbol (.) is relocatable or
absolute when referenced in a relocatable or absolute program section, respectively.
Any labels appearing on a line containing a . PSECT (or . ASECT or . CSECT) directive are
assigned the value of the current location counter before the . PSECT (or other) directive
takes effect. Thus, if the first statement of a program is:
A:

.PSECT ALT,REL

the label A is assigned to relocatable address zero of the unnamed program section.
Since it is not known during assembly where relocatable program sections will be
loaded, all references to relocatable program sections are assembled as references
relative to the base of the referenced section.
In the following example, references to the symbols X and Yare translated into
references relative to the base of the relocatable program section named SEN .
. PSECT ENT,ABS
.=.+1.000
A:
CLR
X

Y:
X:

;Assembled as CLR base of
;relocatable section + 10(octal).
;Assembled as JMP base of
;relocatable section + 6(octal).

JMP

.PSECT
MOV
JMP
HALT
. WORD

SEN,REL
RO,Rl
A
;Assembled as JMP 1000.

NOTE
In the preceding example, using a constant in conjunction
with the current location counter symbol (.) in the
form . =1000 would result in an error, because constants
are always absolute and are always associated with the
program's. ASECT (. ABS.). If the form. =1000 were used,
a program section incompatibility would be detected. See
Section 3.6 for a discussion of the current location counter.

General Assembler Directives

6-39

Thus, MACRO-11 provides the Linker or Task Builder with the necessary information
to resolve the linkages between various program sections. Such information is not
necessary, however, when an absolute program section is referenced, because all
instructions in an absolute program section are associated with an absolute virtual
address.
6.7.1.2 Code or Data Sharing

Named relocatable program sections with the arguments GBL and OVR operate in the
same manner as FORTRAN COMMON; that is, program sections of the same name
with the arguments GBL and OVR from different assemblies are all loaded at the same
location at link time. All other program sections (those with the argument CON) are
concatenated.
A single symbol could name both an internal symbol and a program section.
Considering FORTRAN again, using the same sy:mbolic name is necessary to
accommodate the following statement:
COMMON

IXI A,B,C,X

where:

represents the base of the program section and also the fourth element of
that section.

6.7.1.3 Memory Allocation Considerations

MACRO-11 does not generate an error when a module ends at an odd location. You
can, therefore, place odd length data at the end of a nlodule. However, when several
modules contain object code contributions to the same program section having the
concatenate attribute (see Table 6-4; CON/OVR), odd length modules (except the last)
may cause succeeding modules to be linked starting at odd locations, thereby making
the linked program unexecutable. To avoid this problem, separate code and data from
each other and place them in separately named program sections (see Table 6-4; riD).
The Linker or Task Builder can then begin each program section on an even address.
Refer to the applicable system manual for further information on memory allocation
of tasks (see the Associated Documents section in the Preface).

6.7.2 .ASECT and .CSECT Directives
Format:
. ASECT
.CSECT
.CSECT

symbol

where:
symbol

represents one or more of the arguments in Table 6-4.

lAS and RSX-11M assembly language programs use the . PSECT and . ASECT directives
exclusively, because the . PSECT directive provides all the capabilities of the . CSECT
directive defined for other PDP-11 assemblers. MACRO-11 accepts both . ASECT and
. CSECT directives, but assembles them as though they were . PSECT directives with the
default attributes listed in Table 6-5. Compatibility exists between other MACRO-11

6-40 PDP-ll MACRO-ll Language Reference Manual

programs and the lAS and RSX-11M Task Builders, because the Task Builders also
treat the . ASECT and . CSECT directives like . PSECT directives with the default values
listed in Table 6--5.

Table 6-5:

Program Section Default Values
Default Value

Attribute

.ASECT

.CSECT
(named)

.CSECT
(unnamed)

.PSECT

Name

. ABS.

name

. BLK. 1

name

Access

Scope

GBL

LCL

Relocation

ABS

REL

Allocation

OVR

CON

Type

lIn RT-ll, this program section has no default name.

Note that the statement:
.CSECT

JIM

is identical to the statement:
.PSECT

JIM,GBL,OVR

because the . CSECT default values GBL and OVR are assumed for the named program
section.

6.7.3 .SAVE Directive
Format:
. SAVE
The . SAVE directive stores the current program section context on the top of the
program section context stack, while leaving the current program section context in
effect. If the program section context stack is full when . SAVE is issued, the directive is
flagged with an error code (A) in the assembly listing. The program section context
stack can handle 16 . SAVEs. The program section context includes the values of the
current location counter and the maximum value assigned to the location counter in
the current program section.
See Figure 6-8 for an example of . SAVE.

6.7.4 .RESTORE Directive
Format:
. RESTORE

General Assembler Directives 6-41

The . RESTORE directive retrieves the program section context from the top of the
program section context stack. If the program section context stack is empty when
. RESTORE is issued, the directive is flagged with an error code (A) in the assembly
listing. When . RESTORE retrieves a program section, it restores the current location
counter to the value it had when the program section was saved.
When saving and restoring program sections, be careful not to store data in a program
section for which you have saved but not yet restored the context; when you restore
the context, the data will be lost. For example, the . WOR.D 1000 in the following series
of instructions has no effect:
.PSECT A
. SAVE
.PSECT A
.WORD
1000
. RESTORE

;Save context of psect A
;Re-establish psect A
;The effect of this instruction ...
;gets wiped out by this .RESTORE directive
;that restores the old context of psect A

See Figure 6-8 for an example of . RESTORE.
Figure 6-8:

Example of .SAVE and .RESTORE Directives

.MAIN. MACRO V05.04 Wednesday 03-Jun-87 10:05 Page 1
Example of .SAVE/.RESTORE usage
1
.SBTTL Example of .SAVE/.RESTORE usage
2
;+
3
; MACRO DS
4
; Define local impure storage
5
6
7
NAME, SIZE
. MACRO DS
8
. SAVE
;Save the current .PSECT
9
.PSECT IMPURE,D,GBL
;Store the data in the IMPURE .PSECT
10
11
NAME:
.BLKW
SIZE
;Set aside the space
. RESTORE
;Reentor the current .PSECT
12
.ENDM
13
14
;+
15
; SCANSY
16
; Scan the hash table for valid entrie!1
17
18
19
SYMBAS,Rl
SCANSY: MOV
;Get base of table
20 000000 016701 000000'
MOV
Rl,CURSYM
;Initialize pointer to table
21 000004 010167 000002'
SYMSIZ,Rl
ADD
; Point past the table
22 000010 066701 000004'
Rl,SYMTOP
MOV
;Save ond address
23 000014 010167 000006'
24
Rest of SCANSY routine ....
25
26
;Table is scanned, exit.
27 000020 000207
RETURN
28
;+
29
30
; Local data
31
32
DS
33 000022
SYMBAS
Base address of symbol table
DS
34 000022
CURSYM
Current symbol pointer during scan
DS
SYMSIZ
Size of table, in bytes
35 000022
DS
SYMTOP
Set to end address of table
36 000022
37

Figure 6-8 Cont'd. on next page

6-42

PDP-ll MACRO-ll Language Reference Manual

Figure 6-8 (Cont.):

Example of .SAVE and .RESTORE Directives

; SSORT

; Perform shell sort on symbol table prior to listing

42
43 000022
44
45
46
47

016701

000006'

SSORT: . MOV

SYMTOP,R1

;Get end of table

; Additional code ....
000001

. END

6.8 Symbol Control Directives
The symbol control directives are used to set the type of a given symbol.

6.S.1 .GLOBL Directive
Format:
.GLOBL

sym1,sym2, ... symn

where:
sym 1,sym2, ... symn

represent valid symbolic names. When multiple symbols are
specified, they are separated by any valid separator (comma, space,
and/or tab).

A statement line containing a . GLOBL directive can also include a label field and/or a
comment field.
The . GLOBL directive defines (and thus provides linkage to) symbols not otherwise
defined as global symbols within a module. In defining global symbols, the directive
. GLOBL A, B, C is similar to:
A==:expression
B==:expression
C==:expression

A==expression
B==expression
C==expression

A' .
B"
C· .

Because object modules are linked by global symbols, these symbols are vital to a
program. The following paragraph, describing the processing of a program from
assembly to linking, explains the global's role.

In assembling a source program, MACRO-II produces a relocatable object module
and a listing file containing the assembly listing and symbol table. The Linker or
Task Builder joins separately assembled object modules into a single executable image.
During linking, object modules are relocated relative to the base of the module and
linked by global symbols. Because these symbols will be referenced by other program
modules, they nlust be singled out as global symbols in the defining modules. As
shown above, the. GLOBL directive, global assignment operator, or global label operator
will define a synlbol as global.
AU internal symbols appearing within a given program must be defined at the end
of asselnbly pass 1, or they will be assumed to be default global references. Refer to
Section 6.2.1 for a description of enabling/disabling of global references.

General Assembler Directives

6-43

In the following example, A and B are entry-point symbols. The symbol A has been
explicitly defined as a global symbol by means of the .. GLOBL directive, and the symbol
B has been explicitly defined as a global label by means of the double colon (::). Since
the symbol C is not defined as a label within the current assembly,' it is an external
(global) reference if . ENABL GBL is in effect.
Define a subroutine with 2 entry points which calls an
external subroutine
. PSECT
. GLOBL
MOV
MOV
JSR
RTS
MOV
CLR
BR

A:
X:

@(R5)+.RO
#X.Rl
PC.C
R5
(R5)+.Rl
R2

;Declare the unnamed program section .
;Define A as a global symbol .
;Define entry point A.
;Call external subroutine C.
;Exit.
;Define entry point B.

External symbols can appear in the operand field of an instruction or MACRO-II
directive as a direct reference, as shown in the examples below:
CLR
. WORD
CLR

EXT
EXT
@EXT

External symbols can also appear as a term within an expression, as shown below:
CLR
. WORD
CLR

EXT+A
EXT-2
@EXT+A(Rl)

An undefined external symbol cannot be used in the evaluation of a direct assignment
statement or as an argument in a conditional assembly directive (see Sections 3.3,
6.9.1, and 6.9.3).

6.8.2 .WEAK Directive
Format:
.WEAK syml.sym2 .... symn

where:
sym 1,sym2, ... symn

represent valid symbolic names. When multiple symbols are
specified, they are separated by any valid separator (comma, space,
and/or tab).

Example:
. WEAK

SUB1.SUB2

A statement line containing a . WEAK directive can also include a label field and/or a
comment field.

6-44

PDP-ll MACRO-ll Language Reference Manual

The . WEAK directive is used to specify symbols that are either defined externally in
another module or defined globally in the current module. This directive suppresses
object library sea.rches for specified external symbols.
When the. WEAK directive specifies a symbol that is externally defined, it is considered
a global symbol. If the Linker finds the symbol's definition in another module, it uses
that definition. If the Linker does not find an external definition, the symbol is given
a value of O. The Linker does not search a library for the global symbol, but if a
module brought in from a library for another reason contains the symbol's definition,
the Linker uses that definition.
If a symbol that is defined in the curr~nt module is specified by the . WEAK directive, the
symbol is considered globally defined. However, if the current module is inserted in an
object library, the symbol is not inserted in the library's symbol table. Consequently,
the rnodule is not found when the library is searched at link time to resolve the
symbol.

NOTE
The . WEAK directive is supported only by the RT-ll
Librarian (LIBR) and Li.nker (LINK). Support is not
yet implemented in the RSX-ll Task Builder (TKB) or
Librarian (LBR).

6.9 Conditional Assembly Directives
Conditional assembly directives allow you to include or exclude blocks of source code
during the assembly process, based on the evaluation of stated condition tests within
the body of the program.

6.9.1 Conditional Assembly Block Directives
Format:
.IF cond,argument(s)

;Start conditional assembly block.

range

;Range of conditional assembly block .

. ENDC

;End of conditional assembly block.

where:
cond

represents a specified condition that must be met if the block is to be
included in the assembly. The conditions that can be tested by the
conditional assembly directives are defined in Table 6-6.
represents any valid separator (comma, space, and/or horizontal tab).

General Assembler Directives

6-45

argument(s)

represent(s) the symbolic argument(s) or expression(s) of the specified
conditional test. These arguments are thus a function of the condition
to be tested (see Table 6-6).

range

represents the body of code that is either included in the assembly, or
excluded, depending upon whether the condition is met.

.ENDC

terminates the conditional assembly block. This directive must be present
to end the conditional assembly block.

A condition test other than those listed in Table 6-6, an invalid argument, or a null
argument specified in a . IF directive causes that line to be flagged with an error code
(A) in the assembly listing.
Table 6-6: Valid Condition Tests for Conditional Assembly Directive:s
Conditions
Positive

Complement

Arguments

Assemble Block If:

Expression

Expression is equal to 0 (or
not equal to 0).

Expression

Expression is greater than 0
(or less than or equal to 0).

Expression

Expression is less than 0 (or
greater than or equal to 0).

NDF

Symbolic argument

Symbol is defined (or not
defined).

~acrolargument

Argument is blank (or not
blank).

IDN

DIF

Two 7-bit ASCII or 8-bit
DEC ~ultinational macro 1
arguments

Arguments are identical (or
different). The . IF IDN and
. IF DIF conditional directives
are not alphabetically case
sensitive by default. You can
enable these directives to be
case sensitive by using the
. ENABL option (. ENABL LCM).

-none-

Assembler is in pass 1. 2

-none-

Assembler is in pass 2.2

1 A macro argument (a form of symbolic argument) is enclosed within angle brackets or delimited by the circumflex construction, as
described in Section 7.3. For example,
<A,B,C>
"/124/
2Use PI and P2 with great care. Most programs do not need them. If used incorrectly, they can cause P (phase) errors during assembly.
Before you use PI or P2, examine your program and make sure you are not trying to use them to disguise some sort of logic error in
the way the program is written.

6-46

PDP-ll MACRO-ll Language Reference Manual

An example of a conditional assembly directive follows:
.IF EQ

;Assemble block if ALPHA+l=O

ALPHA+l

.ENDC

The two operators & and! have special Ineaning within DF and NDF conditions, in that
they are allowed in grouping symbolic arguments.
Logical AND operator

Logical inclusive OR operator

For example, the conditional assembly statement:
.IF DF

SYMl & 8YM2

.ENDC

results in the assembly of the conditional block if the symbols 8YMl and 8YM2 are both
defined. Nested conditional directives take the form:
.IF conditionl
.IF condition2

.ENDC
.ENDC

;condition2
;conditionl

For example, the following conditional directives:
.IF DF SYMl
.IF DF 8YM2

.ENDC
.ENDC

;DF 8YM2
;DF 8YMl

can govern whether assembly is to occur. In the example above, if the outermost
condition is unsatisfied, no deeper level of evaluation of nested conditional statements
within the program occurs.
Although indentation is not required, you can indent nested conditionals to improve
readability, and you can include comments on . ENDC statements to help you match
them to their corresponding conditional assembly directives, as shown above.
Each conditional assembly block must terminate with a . ENDC directive. A. ENDC
directive encountered outside a conditional assembly block is flagged with an error
code (0) in the assembly listing.
MACRO-II permits a nesting depth of 16 10 conditional assembly levels. Any statement
that attempts to exceed this nesting level depth is flagged with an error code (0) in
the assembly listing.
General Assembler Directives

6-47

6.9.2 Subconditional Assembly Block Directives
Formats:
.IFF
. IFT
.IFTF

Subconditional directives can be placed within conditional assembly blocks to indicate:
•

The assembly of an alternate body of code when the condition of the block tests
false

•

The assembly of a noncontiguous body of code 'Nithin the conditional assembly
block, depending upon the result of the conditional test in entering the block

•

The unconditional assembly of a body of code within a conditional assembly block

Subconditional directives are described in detail in Table 6-7. If a subconditional
directive appears outside a conditional assembly block, an error code (0) is generated
in the assembly listing.
Table 6-7:

Subconditional Assembly Block Directives

Subconditional
Directive

Function

.IFF

If the condition tested upon entering the conditional assembly

block is false, the code following this directive, and continuing
up to the next occurrence of a. sub conditional directive or to the
end of the conditional assembly block, is to be included in the
program.

.IFT

If the condition tested upon entering the conditional assembly

block is true, the code following this directive, and continuing
up to the next occurrence of .a sub conditional directive or to the
end of the conditional assembly block, is to be included in the
program.

.IFTF

The code following this directive, and continuing up to the next
occurrence of a subconditional directive or to the end of the
conditional assembly block, is to be included in the program,
regardless of the result of the condition tested upon entering the
conditional assembly block.

The implied argument of a sub conditional directive is the condition test specified upon
entering the conditional assembly block, as reflected by the initial directive in the
conditional coding examples below. Conditional or subconditional directives in nested
conditional assembly blocks are not evaluated if the previous (or outer) condition in
the block is not satisfied. Examples 3 and 4 below illustrate nested directives that are
not evaluated because of previously unsatisfied conditional coding.

6-48

PDP-ll MACRO-ll Language Reference Manual

Example 1: Assume that symbol SYM is defined.
.IF DF

SYM

;Tests TRUE, 8YM is defined. Assemble
;the following code.

.IFF

;Tests FALSE. SYM is defined. Do not
;assemble the following code.

.IFT

;Tests TRUE. 8YM is defined. Assem;ble the following code.

.IFTF

;Assemble following code uncondition;ally.

.IFT

;Tests TRUE. 8YM is defined. Assem;ble remainder of conditional assem;bly block.

.ENDC

;DF SYM

Example 2: Assume that symbol X is defined and that symbol Y is not defined.
. IF DF
. IF DF
.IFF

.IFT

;DF Y

.ENDC
.ENDC

;DF Y
;DF X

Y
;DF Y

;Tests TRUE, symbol X is defined .
;Tests FALSE, symbol Y is not defined .
;Tests TRUE, symbol Y is not defined,
;assemble the following code.
;Tests FALSE, symbol Y is not defined.
;Do not assemble the following code.

Example 3: Assume that symbol A is defined and that symbol B is not defined .
. IF DF

MOV

A,@Rl

.IFF

;DF A

MOV

;Tests FALSE. A is defined. Do not
;assemble the following code.

Rl,RO

.IF NDF B

.ENDC
.ENDC

;Tests TRUE. A is defined.
;Assemble the following code.

;Nested conditional directive is not
; evaluated.

;NDF B
;DF A
General Assembler Directives

6-49

Example 4: Assume that symbol X is not defined and that symbol y is defined.
;Tests FALSE. Symbol X is not defined.
;Do not assemble the following code.
;Nested conditional directive is not
; evaluated.

.IF DF

.IFF

;DF Y

;Nested subconditional directive is
;not evaluated.

.IFT

;DF Y

;Nested s~bconditional directive is
;not evaluated.

.ENDC
.ENDC

;DF Y
;DF X

6.9.3 Immediate Conditional Assembly Directive
Format:
.IIF

cond,arg, statement

where:
represents a valid condition test defined for conditional assembly blocks in
Table 6-6.

cond

represents any valid separator (comma, space, and/or tab), unless cond
is B or NB; in that case, a comma must be used unless the argument is
enclosed in angle brackets or delimited by the circumflex construction (see
Table 3-3).
arg

represents the argument associated with the immediate conditional directive;
an expression, symbolic argument, or macro argument (see Table 6-6).
represents the separator between the conditional argument and the
statement field. If the preceding argument is an expression, then a comma
must be used; otherwise, a comma, space, and/or tab can be used.

statement

represents the specified statement to be assembled if the condition is
satisfied.

An immediate conditional assembly directive lets you write a I-line conditional
assembly block. The use of this directive requires no terminating . ENDC statement
and the condition to be tested is completely expressed within the line containing the
directive.
For example, the immediate conditional statement:
.IIF

DF FDD,BEQ ALPHA

generates the code:
BEQ

ALPHA

if the symbol FDD is defined within the source program.

6-50

PDP-ll MACRO-ll Language Reference Manual

As with the . IF directive, a condition test other than those listed in Table 6-6, an
invalid argument, or a null argument specified in a . IIF directive results in an error
code (A) in the assembly listing.

6. 1 0 File Control Directives
The MACRO-l Jl file control directives are used to add file names to macro library lists
and to insert a source file into the source file being currently used.

6.10.1 .LIBRARY Directive
Format:
.LIBRARY string

where:
string

represents a delimited string that is the file specification of a macro library.

The . LIBRARY directive adds a file nanle to a macro library list that is searched. A
library list is searched whenever a . MCALL or an undefined op code is encountered
within a MACRO-II program. The libraries that make up the list are searched in the
reverse order in which they were specified to the MACRO-II assembler.
If any information was omitted from the macro library argument, default values are
assumed. The default library device and file type for MACRO-lljRT-ll are DK: and
. MLB, and for other systems they are SY: and . MLB.
The . LIBRARY directive is used as follows:
.LIBRARY IDB1: [SMITH]USERLIB/
.LIBRARY ?DK:SYSDEF.MLB?
.LIBRARY \CURRENT.MLB\

MACRO-II searches all macro libraries if it finds an unknown symbol in the op code
field and the auto-mcall option has been previously enabled by . ENABL MCL.
NOTE
If you are using MACRO-II with the RT-ll operating
system, the device handler for the device the . LIBRARY file
resides on must already be loaded, either explicitly with
the KMON LOAD command, or implicitly by reference to
the device on the original MACRO-II command line. The
maximum number of . LIBRARY files that you can specify
is limited to twelve minus the number of files specified
in the MACRO-II command line. Up to eight files can
be specified on a MACRO-II jRT-11 command line, so
at least four slots are available for . LIBRARY files.

General Assembler Directives

6-51

6.10.2 .INCLUDE Directive
Format:
.INCLUDE string

where:
string

represents a delimited string that is the file specification of a macro source
file.

The. INCLUDE directive inserts a source file within the source file currently being used.
When this directive is encountered, an implicit . PAGE directive is issued, status of the
current source file is stacked, and the source file specified by the directive is read
into memory. When the end of the specified source file is reached, an implicit . PAGE
directive is issued, the original source file status is popped from the stack, and assembly
resumes at the line following the directive. A source file can also be inserted within
a source file that has already been specified by the . INCLUDE directive. In this case,
the status of the original source file and the first source file specified by the . INCLUDE
directive are stacked, and the second specified source file is read into memory. When
the end of the second source file is reached, the status of the first specified source file
is popped from the stack, and assembly resumes at the line following the directive.
When the end of the first specified source file is reached, the status of the original
source file is popped from the stack, and· assembly of that file is started again at the
line following the . INCLUDE directive. An implicit . PAGE directive precedes and follows
each included source file. The maximum nesting level of source files specified by the
. INCLUDE directive is five.
If any information is omitted from the source file argument, default values are assumed.
The default source file device and file type for MACRO-ll/RT -11 are DK: and . MAC,
and for other systems they are SY: and . MAC.

The . INCLUDE directive is used as follows:
. INCLUDE
. INCLUDE
. INCLUDE

/DR3: [1 ,2] MACROS/
?DK:SYSDEF?
\CURRENT.MAC\

;File MACROS.MAC

NOTE
If you are using MACRO-II with an RT-ll operating
system, the device handler for the device that the
. INCLUDE file resides on must already be loaded, either
explicitly with the KMON LOAD command, or implicitly
by reference to the device on the ·original MACRO-II
command line.

6-52

PDP-ll MACRO-ll Language Reference Manual

Part IV

Chapter 7

Macro Directives
This chapter tells you how to use MACRO-11/s macro directives to define and write
macros. Macro directives let you:

•

Define macros

•
•

Call macros

•

Test macro attributes

•
•

Report error conditions

•

Call macros from libraries

•

Delete macro definitions

Test and substitute ,macro arguments

Perform counted or indefinite repeat loops

Each function is described in its own section of this chapter. Table 7-1 gives an
alphabetical list of all directives described in this chapter and the associated section
reference. Also refer to Section B.3 for a complete list of all MACRO-11 directives.
Table 7-1:

Directives in Chapter 7

Directive

Function

Section
Reference

.ENDM

Terrninates a macro definition.

7.1.2

.ENDR

Terminates a counted or indefinite repeat block.

7.7

. ERROR

Writes a message to the listing file to flag invalid macro arguments
or conditions.

7.5

.lRP

Creates an indefinite repeat block.

7.6.1

. lRPC

Creates an indefinite repeat block for character string arguments.

7.6.2

. MACRO

Begins a macro definition.

7.1.1

. MCALL

Calls a previously-defined macro from a library.

7.8

.MDELETE

Deletes a macro definition from MACRO-II's macro symbol table.

7.9

.MEXlT

Prematurely terminates execution of a macro.

7.1.3

. NARC

Returns number of macro arguments.

7.4.1

. NCHR

Returns number of characters in an argument.

7.4.2

Macro Directives 7-1

Table 7-1 (Cont.):

Directives in Chapter 7

Directive

Function

Section
Reference

.NTYPE

Returns addressing mode of an argument.

7.4.3

. PRINT l

Writes a message to the listing file to flag invalid macro arguments
or conditions, and generates a (P) error.

7.5

.REPT

Creates a counted repeat block.

7.7

IMACRO-11's .PRINT directive is not the same as the RT-ll monitor .PRINT request; be careful not to confuse the two. Under RT-11,
if you .MCALL .PRINT, you will get the RT-ll monitor .PRINT request; otherwise, you will get MACRO-11's .PRINT directive.

7.1 Defining Macros
By using macros, you can use a single line to insert a sequence of lines into a source
program.
A macro definition is headed by a . MACRO directive (see Section 7.1.1) followed by
the source lines. The source lines may optionally contain dummy arguments. If such
arguments are used, each one is listed in the . MACRO directive.
A macro call (see Section 7.3) is the statement you use to call the macro into the
source program. It consists of the macro name followed by the real arguments needed
to replace any dummy arguments used in the macro.
Macro expansion is the insertion of the macro source lines into the main program.
Included in this insertion is the replacement of the dummy arguments by the real
arguments.
Macro directives provide the means to define macros and control macro expansions.
Only one directive is allowed per source line. Each directive may have a blank operand
field or one or more operands. Valid operands differ with each directive. This chapter
describes the macro directives available in MACRO-II and their arguments.

7.1.1 . MACRO Directive
Format:
[label:] .MACRO

name, dummy argument list

where:
label

represents an optional statement label.

name

represents the user-assigned symbolic name of the macro. This name can
be any valid symbol and can be used as a label elsewhere in the program.
represents any valid separator (comma, space, and/or tab).

7-2

PDP-ll MACRO-ll Language Reference Manual

dum. my
argument
list

represents a number of valid symbols (see Section 3.2.2) that can appear
anywhere in the body of the macro definition, even as a label. These
dummy symbols can be used elsewhere in the program with no conflict
of definition. Multiple dummy arguments specified in this directive can be
separated by any valid separator. The detection of a duplicate or an invalid
symbol in a dummy argument list terminates the scan and causes an error
code (A) to be generated.

The first statement of a macro definition must be a . MACRO directive.
A comnlent can follow the dummy argument list in a . MACRO directive, as shown below:
. MACRO

ABS

A,B

;Defines macro ABS with two arguments.

Although it is acceptable for a label to appear on a . MACRO directive, this practice is
discouraged, especially in the case of nested macro definitions, because invalid labels
or labels constructed with the concatenation character will cause the macro directive
to be ignored. This may result in improper termination of the macro definition.

7.1.2 .ENDM Directive
Format:
.ENDM

[name]

where:
name

represents an optional argument specifying the name of the macro being
terminated by the directive.

Example:
.ENDM
. ENDM

;Terminates the current
;macro definition .
ABS

;Terminates the current
;macro definition named ABS.

The final statement of every macro definition must be a . ENDM directive.
If specified, the macro name in the . ENDM statement must match the name specified
in the corresponding . MACRO directive. Otherwise, the statement is flagged with an

error code (A) in the assembly listing. In either case, the current macro definition is
terminated. Specifying the macro name in the. ENDM statement permits MACRO-II to
detect missing. ENDM statements or improperly nested macro definitions.
The . ENDM directive must not have a label. If a valid label is attached, the label is
ignored; if an invalid label is attached, the directive is ignored.

Macro Directives 7-3

The . ENDM directive can be followed by a comment field, as shown below:
.MACRO
JSR
. WORD
.ENDM

TYPMSG MESSGE
R5,TYPMSG
MESSGE

;Type a message.
;End of TYPMSG macro.

You can also use the . ENDM directive to terminate indefinite repeat blocks (see
Section 7.6) and repeat blocks (see Section 7.7).

7.1.3 .MEXIT Directive
Format:
.MEXIT

The . MEXIT directive terminates a macro expansion before the end of the macro is
encountered. This directive is also valid within repeat blocks (see Sections 7.6 and
7.7). It is most useful in nested macros. The . MEXIT directive terminates the current
macro as though a . ENDM directive had been encountered. A . MEXIT also terminates
any pending . IF directives.
Using the . MEXIT directive bypasses the complexities of nested conditional directives
and alternate assembly paths, as shown in the following example:
.MACRO ALTR N,A,B

. IF EQ N

;Start conditional assembly block .

. MEXIT
. ENDC

;Terminate macro expansion .
;End conditional assembly block .

. ENDM

;Normal end of macro .

In an assembly where the dummy symbol N is replaced by 0 (zero) (see Table 6-6),
the . MEXIT directive would assemble the conditional block and terminate the macro
expansion. When macros are nested, a . MEXIT directive exits to the next higher level of
macro expansion. A . MEXIT directive encountered outside a macro definition is flagged
with an error code (0) in the assembly listing.

7.1.4 MACRO Definition Formatting
A form feed character within a macro definition causes a page eject during the assembly
of the macro definition. However, no page eject is done when the macro is expanded.
Conversely, when the. PAGE directive is used in a macro definition, it is ignored during
the assembly of the macro definition, but a page eject is performed when that macro
expansion is listed.

7 -4

PDP-ll MACRO-ll Language Reference Manual

7.2 Calling Macros
Format:
[label:]

name

real arguments

where:
label

represents an optional statement label.

name

represents the name of the macro, as specified in the . MACRO directive
(see Section 7.1.1).

real arguments

represent symbolic arguments which replace the dummy arguments listed
in the . MACRO directive. When multiple arguments occur, they are
separated by any valid separator. Arguments to the macro call are
treated as character strings, their usage is determined by the macro
definition.

A macro must be defined with the. MACRO directive (see Section 7.1.1) before the macro
can be called and expanded within the source program.
When a macro name is the same as a user label, the appearance of the symbol in the
operator field designates the symbol as a. macro call; the appearance of the symbol in
the operand field designates it as a label, as shown below:
ABS:

MOV

eRa) ,R1

;ABS is defined as a label.

ABS

;ABS is considered to be a label.

ABS

#4,ENT,LAR

;ABS is a macro call.

You can also assign a value to a symbol that has the same name as a nlacro, as
illustrated in this example:
ABS

:1.00

; ABS is a user symbol.

ABS

#4,ENT,LAR

;ABS is a macro call.

7.3 Arguments in Macro Definitions and Macro Calls
Multiple arguments within a macro definition or macro call must be separated by
one of the valid separating characters described in Section 3.1.1. Macro definition
argunlents (dumlny) and macro call arguments (real) normally maintain a strict
positional relationship. That is, the first real argument in a macro call corresponds with
the first dummy argument in a macro definition. Only the use of keyword arguments
in a macro call can override this correspondence (see Section 7.3.6).

Macro Directives

7-5

For example, the following macro definition and its associated macro call contain
multiple arguments:
. MACRO

REN A.B.C

REN

ALPHA.BETA.<Cl.C2>

Arguments which themselves contain separating characters must be enclosed in paired
angle brackets. For example, the macro call:
REN

<MOV X.Y>.#44.WEV

uses the entire expression:
MOV

X.Y

to replace all occurrences of the symbol A in the macro definition. Real arguments
within a macro call are considered to be character strings and are treated as a single
entity during the macro expansion.
The circumflex (") construction allows angle brackets to be passed as part of the
argument. For example, this construction could have been used in the above macro
call, as follows:
REN

~/<MOV

X.Y>I.#44.WEV

passing the character string <MOV X. Y> as an argument.
Because of the use of the circumflex (") shown above, you must be careful when
passing an argument beginning with a unary operator (~o, ~D, AB, AR, AF .... ). These
arguments must be enclosed in angle brackets (as shown below) or MACRO-11 will
read the character following the circumflex as a delimjter.
REN

<~O

411>.X.Y

The following macro call:
REN

#44.WEV~/MOV

X,YI

contains only two arguments (#44 and WEVA IMOV X, YI), because the circumflex is a unary
operator (see Section 3.1.3) and it is not preceded by an argument separator.
As shown in the examples above, spaces can be used within bracketed argument
constructions to increase the legibility of such expressions.
When 8-bit DEC Multinational character set (MCS) ~haracters are used in argument
strings, they must be enclosed in angle brackets ( < > ) or the argument delimiter
( /) must be preceded by a circumflex ("). The following are valid uses of the MCS
characters in the argument string:
<This string can contain MCS characters>
~/This

string can contain MCS charactersl

7 -6 PDP-ll MACRO-ll Language Reference Manual

7.3.1 Macro Nesting
Macro nesting occurs where the expansion of one macro includes a call to another.
The depth of nesting allowed depends upon the amount of dynamic memory used by
the source program being assembled.
To pass an argument containing valid argument delimiters to nested macros, enclose
the argument in the macro definition within angle brackets, as shown in the coding
sequence below. This extra set of angle brackets for each level of nesting is required
in the macro definition, not in the macro call .
. MACRO
LEVEL2
LEVEL2
.ENDM

LEVEL1 DUM1,DUM2
<DUM1>
<DUM2>

. MACRO
DUM3
ADD
MOV
.ENDM

LEVEL2 DUM3
#10,40
RO, CR1) +

A call to the LEVEL1 macro, as shown below, for example:
LEVEL1

causes the following macro expansion to occur:
MOV
ADD
MOV
MOV
ADD
MOV

X,RO
#10,RO
RO, CR1) +
R2,RO
#10,RO
RO, CR1) +

When Inacro definitions are nested, the i.nner definition cannot be called until the outer
macro has been called and expanded. For example, in the following coding:
. MACRO

LVi A,B

. MACRO

LV2 C

.ENDM
.ENDM

the LV2 macro cannot be called and expanded until the LVi macro has been expanded.
Likewise, any macro defined within the LV2 macro definition cannot be called and
expanded until LV2 has also been expanded.

Macro Directives 7-7

7.3.2 Special Characters in Macro Arguments
If an argument does not contain spaces, tabs, semicolons, or commas, it can include

special characters without enclosing them in a bracketed construction. For example:
.MACRO
MOV
.ENDM

PUSH ARG
ARG,-(SP)

PUSH

X+3(%2)

generates the following code:
MOV

X+3(%2),-(SP)

7.3.3 Passing Numeric Arguments as Symbols
If the unary operator backslash (\) precedes an argument, the macro treats that

argument as a numeric value in the current program. radix. The ASCII characters
representing this value are inserted in the macro expansion, and their function is
defined in the context of the resulting code. The backslash operator cannot take a
forward reference (the argument must be defined at the time it is used), and the
argument cannot be a relocatable symbol.
The following example illustrates the use of the backslash operator:
.LIST

3
4
6

; Example of the use of the backs lash (\) operator
.MACRO RESERV X
.BLKW X
.ENDM

7
8
9

;Note difference in the way the macro gets expanded when backslash
;is used and when it is not. (In this case the reQuIting binary
;code is the same.)

12
13
14

000010

SIZE-l0

16 000000
000000
16
17 000020
000020
18
19

000001

RESERV
.BLKW

SIZE
SIZE

;Call macro without backs lash on argument

RESERV
.BLKW

\SIZE
10

; Call macro with bllckslash on argument

. END

Another, more complicated, example is given below:
.MACRO INC A,B
CON
A,\B
B=B+l
A'B:

C=o

.ENDM
.MACRO CON A,B
. WORD
4
.ENDM

INC

X,C

7 -8 PDP-ll MACRO-ll Language Reference Manual

;B is treated as a number in current
;program radix.

The above macro call (INC) would thus expand to:
XO:

. WORD

In this expanded code, the label xO: results from the concatenation of two. real
arguments. The single quote (') character in the label A' B: concatenates the real
arguments X and 0 as they are passed during the expansion of the macro. This type
of argument construction is described in more detail in Section 7.3.7.
A subsequent call to the same macro would generate the following code:
Xi:

.WORD 4

and so on, for later calls. The two macro definitions are necessary, because the
symbol associated with dummy argument B (that is, c) cannot be updated in the CON
macro definition, because the character 0 (zero) has replaced C in the argument string
(INC X. C). In the CON macro definition, the number that is passed is treated as a string
argument. (Where the value of the real argument is 0 (zero), only a single 0 character
is passed to the nlacro expansion.)
Passing numeric values in this manner is useful in identifying source listings. For
example, versions of programs created through conditional assemblies of a single
source program can be identified through such coding as that shown below. Assume,
for example, that the symbol ID in the Inacro call (lDT) has been equated elsewhere
in the source program to the value 6 .
. MACRO IDT 8YM
.IDENT /VOi. '8YM/
. ENDM

IDT

;Assume that the symbol ID takes
;on a unique 2-digit value .
;Where VOi is the update
;version of the program.

\ID

The above macro call would then expand to:
.IDENT /VOi. 6/
where 6 is the numeric value of the symbol ID.

7.3.4 Number of Arguments in Macro Calls
A macro can be defined with or without arguments. If more arguments appear
in the macro caU than in the macro definition, an error code (Q) is generated
in the assembly listing. If fewer arguments appear in the macro call than in the
macro definition, missing arguments are assumed to be null values. The conditional
directives . IF Band . IF NB (see Table 6-6) can be used within the macro to detect
missing arguments. The number of arguments can also be determined by using the
. NARG directive (Section 7.4.1).

7.3.5 Creating Local Symbols Automatically
A label is often required in an expanded macro. In the conventional macro facilities
thus far described, a label must be explicitly specified as an argument with each
macro call. You must be careful in issuing subsequent calls to the same macro in
order to avoid duplicating labels. This concern can be eliminated through a feature
Macro Directives 7-9

of MACRO-II that creates a unique symbol where a label is required in an expanded
macro.
MACRO-II can automatically create local symbols of the form n$, where n is an integer
in the range 30000 10 through 65535 10 , inclusive. Such local symbols are created by
MACRO-II in numerical order, as shown below:
30000$
30001$

65534$
65535$

This automatic generation occurs on each call of a macro whose definition contains a
dummy argument preceded by the question mark (?) character, as shown in the macro
definition below:
.MACRO ALPHA, A,?B
TST

BEQ
ADD

B
#5,A

;Contains dummy argument B preceded by
;question mark.

B:
.ENDM

A local symbol is created automatically by MACRO-II only when a real argument of
the macro call is either null or missing, as shown in Example 1 below. If the real
argument is specified in the macro call, however, MACRO-II inhibits the generation
of a local symbol and normal argument replacement occurs, as shown in Example 2
below. (Examples 1 and 2 are both expansions of the ALPHA macro defined above.)
Example 1: Create a Local Symbol for the Missing Argument
ALPHA
TST

BEQ
ADD

R1
R1
30000$
#5,R1

;Second argument is missing.
;Local symbol is created.

30000$:

Example 2: Do Not Create a Local Symbol
ALPHA
TST

BEQ
ADD

R2,XYZ
R2
XYZ
#5,R2

;Second argument XYZ is specified.
;Normal argument replacement occurs.

XYZ:

Automatically created local symbols are restricted to the first 16 10 arguments of a
macro definition.
Automatically created local symbols resulting from the expansion of a macro, as
described above, do not establish a local symbol block in their own right.
When a macro has several arguments earmarked for automatic local symbol generation,
substituting a specific label for one such argument risks assembly errors because

7 -1 0

PDP-ll MACRO-ll Language Reference Manual

MACRO-tt constructs its argument substitution list at the point of macro invocation.
Therefore, the appearance of a label, the . ENABL LSB directive, or the . PSECT directive,
in the macro expansion will create a new local symbol block. The new local symbol
block could leave local symbol references in the previous block and their symbol
definitions in the new one, causing error codes in the assembly listing. Furthermore,
a later macro expansion that creates local symbols in the new block may duplicate
one of the symbols in question, causing an additional error code (P) in the assembly
listing.

7.3.6 Keyword Arguments
Format:
name=string

where:
name

represents the dummy argument.

string

represents the real symbolic argument.

The keyword argument cannot contain embedded argument separators unless delimited
as described in Section 7.3.
Macros can be defined with, and/or called with, keyword arguments. When a keyword
argument appears in the dummy argument list of a macro definition, the specified string
becomes the default real argument at macro call. When a keyword argument appears
in the real argument list of a macro call, however, the specified string becomes the
real argument for the dummy argument that matches the specified name, whether or
not the dummy argument was defined with a keyword. If a match fails, the entire
argument specification is treated as the next positional real argument.
The DEC Multinational character set can be used in keyword arguments if enclosed in
angle brackets ( < > ).
A keyword argument can be specified anywhere in the dummy argument list of a macro
definition and is part of the positional ordering of argument. A keyword argument
can also be specified anywhere in the real argument list of a macro call but, in this
case, does not affect the positional ordering of the arguments.
1
2
3
4
5
6
7
8
9
10

.LIST

Define a macro having keywords in dummy argument
list

. MACRO
. WORD
. WORD
. WORD
.ENDM

TEST CONTRL=l,BLOCK,ADDRES=TEMP
CONTRL
BLOCK
ADD RES

11
12
13

Now call several times

Macro Directives 7-11

16
17 000000
000000
000002
000004
18
19 000006
000006
000010
000012
20
21 000014
000014
000016
000020
22
23 000022
000022
000024
000026
24
25 000030
000030
000032
000034
26
27 000036
000036
000040
000042
28
29
000001
30

OOOOOOG
OOOOOOG
OOOOOOG

TEST
. WORD
. WORD
. WORD

A,B,C
A
B
C

000040
000030
000020

TEST
. WORD
. WORD
. WORD

ADDRES=20,BLOCK=30,CONTRL=40
40
30
20

000001
000005
OOOOOOG

TEST
. WORD
. WORD
. WORD

BLOCK=5
1
5
TEMP

000005
000000
OOOOOOG

TEST
. WORD
. WORD
. WORD

CONTRL=5,ADDRES=VARlAB
5

000001
000000
OOOOOOG

TEST
. WORD
. WORD
. WORD

000001
000000
OOOOOOC

TEST
. WORD
. WORD
. WORD

VARlAB
1
TEMP
ADDRES=JACK!JILL
1
JACK! JlLL

.END

7.3.7 Concatenation of Macro Arguments
The single quote or apostrophe character (') operates as a valid delimiting character in
macro definitions. A single quote that precedes and/or follows a dummy argument in
a macro definition is removed, and the substitution of the real argument occurs at that
point. For example, in the following statements:
A'B:

.MACRO DEF A,B,C
.ASClZ /C/
. BYTE "A,' 'B
.ENDM

when the macro DEF is called through the statement:
DEF

X,Y,<MACRO-ll>

it expands as follows:
XY:

.ASClZ /MACRO-ll/
. BYTE 'X, 'Y

During expansion of the first line, the scan for the first argument terminates upon
finding the first single quote (') character. Since A is a dummy argument, the single
quote (') is removed. The scan then resumes with B; B is also noted as another dummy
7 -1 2

PDP-ll MACRO-ll Language Reference Manual

argument. The two real arguments X and Yare then concatenated to form the label
XY:. The third dummy argument is noted in the operand field of the . ASCIZ directive,
causing the real argument MACRO-II to be substituted in this field.
When the arguments of the . BYTE directive are evaluated during expansion of the
second line, the scan begins with the first single quote (') character. Since it is neither
preceded nor followed by a dummy argument, this single quote remains in the macro
expansion. The scan then encounters the second single quote, which is followed by
a dummy argument and is therefore discarded. The scan of argument A is terminated
upon encountering the comma (,). The third single quote is neither preceded nor
followed by a dummy argument and again remains in the macro expansion. The
fourth (and last) single quote is followed by another dummy argument and is likewise
discarded. (Four single quote characters were necessary in the macro definition to
generate two single quote characters in the macro expansion.)

7.4 Macro Attribute Directives: .NARG, .NCHR, and .NTYPE
MACRO-II has three directives that let you determine certain attributes of macro
arguments: . NARG, . NCHR, and . NTYPE. The use of these directives permits selective
modifications of a macro expansion, depending on the nature of the arguments being
passed. These directives are described below.

7.4. 1 . NARG Directive
Format:
[label:] .NARG symbol

where:
label

represents an optional statement label.

symbol

represents any valid symbol. This symbol is equated to the number of
nonkeyword arguments in the macro call currently being expanded. If a
symbol is not specified, the . NARG directive is flagged with an error code (A)
in the assembly listing.

The. NARG directive determines the number of nonkeyword arguments in the macro call
current! y being expanded. Hence, the . NARG directive can appear only within a macro
definition; if it appears elsewhere, an error code (0) is generated in the assembly
listing.
An example of the . NARG directive is shown in Figure 7-1.

Macro Directives

7-13

Figure 7-1:

Example of . NARG Directive

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 000000

.LIST

; Example of the .NARG directive
,

. MACRO

NULL
.NARG
.IF EQ
.MEXIT
.IFF
.REPT
NOP
. EN DR
.ENDC

NUM
SYM
SYM
NUM

.ENDM

20
21 000000
000001

000006

22
23

NARG

000000

000000
000002
000004
000006
000010
000012

. TITLE

000240
000240
000240
000240
000240
000240
000001

7 -14 PDP-ll MACRO-ll Language Reference Manual

NULL
.NARG
.IF EQ
.MEXIT
.IFF
.REPT
NOP
.ENDR
.ENDC
NULL
.NARG
.IF EQ
.MEXIT
.IFF
.REPT
NOP
.ENDR
NOP
NOP
NOP
NOP
NOP
NOP
.ENDC
.END

SYM
SYM

SYM
SYM
6

7.4.2 .NCHR Directive
Format:
[label:] .NCHR symbol,<string>

where:
label

represents an optional statement label.

symbol

represents any valid symbol. This symbol is equated to the number of
characters in the specified character string. If a symbol is not specified, the
. NCHR directive is flagged with an error code (A) in the assembly listing.
represents any valid separator (comma, space, and/or tab).

represents a string of 7-bit ASCII or 8-bit DEC Multinational printing
characters. If the character string contains a valid separator (comma, space,
and/ or tab), the whole string must be enclosed within angle brackets ( < > )
or be delimited by the circumflex (") construction (see Section 7.3). If
the delimiting characters do not match or if the ending delimiter cannot
be detected because of a syntactical error in the character string (thus
prematurely terminating its evaluation), the . NCHR directive is flagged with
an error code (A) in the assembly listing.

The . NCHR directive, which can appear anywhere in a MACRO-II program, determines
the number of characters in a specified character string. This directive is useful in
calculating the length of macro arguments.
An example of the . NCHR directive is shown in Figure 7-2.

Macro Directives

7 -1 5

Figure 7-2:

Example of .NCHR Directive

1
2
3
4
5
6
7

. TITLE

NCHR

.LIST

; Illustrate the .NCHR directive
,

. MACRO

8
9

10
11
12
13
14
15 000000
000000
000002
000003
000004
000005
000006

STRING MESSAG
$$$, MESSAG
. NCHR
$$$
. WORD
.ASCII /MESSAG/
. EVEN

.ENDM
MSG1:
000005
000005
110
145
154
154
157

STRING
. NCHR
. WORD
.ASCII

<Hello>
$$$, Hello
$$$
/Hello/

. EVEN
16
17

000001

.END

7.4.3 .NTYPE Directive
Format:
[label:] .NTYPE symbol,aexp

where:
label

represents an optional statement label.

symbol

represents any valid symbol. This symbol is equated to the 6-bit addressing
mode of the following expression (aexp). If a symbol is not specified, the
. NTYPE directive is flagged with an error code (A) in the assembly listing.
represents any valid separator (comma, space, and/or tab).

aexp

represents any valid address expression, as used with an op code. If no
argument is specified, an error code (A) will appear in the assembly listing.

The. NTYPE directive determines the addressing mode of a specified macro argument.
Hence, the . NTYPE directive can appear only within a macro definition; if it appears
elsewhere, it is flagged with an error code (0) in the assembly listing.
An example of a . NTYPE directive in a macro definition is shown in Figure 7-3.

7 -1 6

PDP-ll MACRO-ll Language Reference Manual

Figure 7-3:

Example of . NTVPE Directive in Macro Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 000000

NTYPE

.LIST

;+
, Illustrate the

.NTYPE directive

. MACRO
.IF EQ

SAVE
ARG
.NTYPE $$$, ARG
$$$&70
ARG,-(SP)
MOV

; Save in register mode

.IFF
MOV

#ARG,-(SP)

;Save in non-register mode

SAVE
.NTYPE
$$$&70
MOV

R1
$$$, R1
R1,-(SP)

; Save in register mode

MOV

#R1,-(SP)

; Save in non-register mode

SAVE
.NTYPE
$$$&70
MOV

TEMP
$$$, TEMP
TEMP,-(SP)

;Save in register mode

MOV

#TEMP,-(SP)

;Save in non-register mode

. WORD

.ENDC
.ENDM
000001
.IF EQ

000000

. TITLE

010146
.IFF
.ENDC

18
19 000002
000067
.IF EQ
.IFF
000002

012746
000006'
.ENDC

20
21 000006
22
23

000000
000001

TEMP:

. END

For additional information concerning addressing modes, refer to Chapter 5 and
Section B.2.

Macro Directives 7-17

7.5 .ERROR and .PRINT Directives
Format:
[label:] .ERROR [expr]

;text

where:
label

represents an optional statement label.

expr

represents an optional expression whose value is output when the . ERROR
directive is encountered during assembly.
denotes the beginning of the text string.

text

represents the message associated with the . ERROR directive. The text can
be 7-bit ASCII or 8-bit DEC Multinationa.l characters.

The . ERROR directive writes a message to the listing file during assembly pass 2. A
common use of this directive is to warn you about a rejected or erroneous macro call
or an invalid set of conditions in a conditional assembly. If the listing file is not
specified, the. ERROR messages are written to the comnland output device.
Upon encountering a . ERROR directive anywhere in a source program, MACRO-II
writes a single line containing:
1.

An error code (P)

2. The sequence number of the . ERROR directive statelnent
3.

The value of the current location counter

The value of the expression, if one is specified

5. The source line containing the. ERROR directive.

For example, the following line tests an argument to be sure its value is at least 100,
and writes a message if it is not:
.IIF LT <A-l00> .ERROR A

; Invalid macro argument

If A had a value of 76, a line in the following form would be written to the listing file:

Seq. Loc.
No. No.

Exp.
Value

512 005642

000076

Text
.ERROR A

; Invalid macro argument

The . PRINT! directive is identical in function to the . ERROR directive, except that it is
not flagged with the error code (P).

1 MACRO-ll's .PRINT directive is not the same as the RT-ll monitor .PRINT request; be careful not to confuse the two. Under RT-ll, if you
.MCALL .PRINT, you will get the RT-ll monitor .PRINT request; otherwise, you will get MACRO-ll's .PRINT directive.

7-18 PDP-ll MACRO-ll Language Reference Manual

7.6 Indefinite RelPeat Block Directives: .IRP and .IRPC
An indefinite repeat block is similar to a macro definition with only one dummy
argument. At each expansion of the indefinite repeat range, this dummy argument is
replaced with successive elements of a real argument list. Since the repeat directive
and its associated range are coded inline within the source program, this type of macro
definition and expansion does not require calling the macro by name, as required in
the expansion of the conventional macros previously described in this chapter.
An indefinite repeat block can appear either within or outside another macro definition,
indefinite repeat block, or repeat block. The rules for specifying indefinite repeat block
arguments are the same as for specifying macro arguments (see Section 7.3).

7.6.1 .IRP Directive
Format:
[label:] .IRP sym,<argument list>

(range of indefinite repeat block)

.ENDR

where:
label

represents an optional statement label.
Although it is valid for a label to appear on a .IRP directive,
this practice is discouraged, especially in the case of nested macro
definitions, because invalid labels or labels constructed with the
concatenation character will cause the macro directive to be ignored.
This may result in improper termination of the macro definition.
This also applies to . IRPC and . REPT.

sym

represents a dummy argument that is replaced with successive real
arguments from within the angle brackets. If no dummy argument
is specified, the .IRP directive is flagged with an error code (A) in
the assembly listing.
represents any valid separator (comma, space, and/or tab).

represents a list of real arguments enclosed within angle brackets
that is to be used in the expansion of the indefinite repeat range. A
real argument can consist of one or more 7-bit ASCII or 8-bit DEC
Multinational characters; multiple arguments must be separated by
any valid separator (comma, space, and/or tab). If no real arguments
are specified, no action is taken.

Macro Directives

7-1 9

range

represents the block of code to be repeated once for each occurrence
of a real argument in the list.
The range can contain other
macro definitions, repeat ranges and/or the . MEXIT directive (see
Section 7.1.3).

.ENDR

indicates the end of the indefinite repeat block range. You can also
terminate an indefinite repeat block with . ENDM.

The. IRP directive replaces a dummy argument with successive real arguments specified
in an argument string. This replacement process occurs during the expansion of an
indefinite repeat block range.
Use the . MEXIT directive to leave a .IRP loop if you want to exit the loop before its
normal completion.
An example of the. IRP directive is shown in Figure 7--4.

7.6.2 .IRPC Directive
Format:
[label:] .IRPC

sym,<string>

(range of indefinite repeat block)

.ENDR

where:
label

represents an optional statement label (see discussion in Section 7.6.1).

sym

represents a dummy argument that is replaced with successive real
arguments from within the angle brackets. If no dummy argument is
specified, the . IRPC directive is flagged with an error code (A) in the
assembly listing.
represents any valid separator (comma, space, and/or tab).

represents a list of 7-bit ASCII or 8-bit DEC Multinational characters,
enclosed within angle brackets, to be used in the expansion of the indefinite
repeat range. Although the angle brackets are required only when the string
contains separating characters, their use is recommended for legibility.

range

represents the block of code to be repeated once for each occurrence of
a character in the list. The range can contain macro definitions, repeat
ranges, and/or the. MEXIT directive (see Section 7.1.3).

.ENDR

indicates the end of the indefinite repeat block range. You can also terminate
an indefinite repeat block with . ENDM.

The. IRPC directive does single character substitution, rather than argument substitution.
On each iteration of the indefinite repeat range, the durnmy argument is replaced with
successive characters in the specified string.

7 -20

PDP-ll MACRO-ll Language Reference Manual

Use the . MEXIT directive to leave a . IRPC loop, if you want to exit the loop before its
normal completion.
An example of the . IRPC directive is shown in Figure 7-4.
Figure 7-4:

Example of .IRP and .IRPC Directives

. TITLE

IRPTST

.LIST

2
3
4

; Illustrate the .IRP and .IRPC directives
; by creating a pair of RAD50 tables

9 000000
10
11
000000
000002
000004
000006
000010
000012
000014
000016
12
13 000020
14
15
000020
000022
000024
000026
000030
000032
000034
000036
16
17

.IRP
.RAD50
.ENDR
.RAD50
.RAD50
.RAD50
.RAD50
.RAD50
.RAD50
.RAD50
.RAD50

REG,<PC,SP,R5,R4,R3,R2,R1,RO>
/REG/

NUM,<76543210>
/R'NUM/

073110
073040
072770
072720
072650
072600
072530
072460

.IRPC
.RAD50
.ENDR
.RAD50
.RAD50
.RAD50
.RAD50
.RAD50
.RAD50
.RAD50
.RAD50

000001

.END

REGS:
062170
074500
072770
072720
072650
072600
072530
072460
REGS2:

/PC/
/SP/
/R5/
/R4/
/R3/
/R2/
/R1/
/RO/

/R7/
/R6/
/R5/
/R4/
/R3/
/R2/
/R1/
/RO/

7.7 Repeat Blocl< Directive: .REPT, .ENDR
Fonnat:
[label:] .REPT

exp

(range of repeat block)

. EN DR

Macro Directives

7 -21

where:
label

represents an optional statement label (see discussion in Section 7.6.1).

exp

represents any valid expression. This value controls the number of times the
block of code is to be assembled within the program. When the expression
value is less than or equal to zero, the repeat block is not assembled. If this
expression is not an absolute value, the . REPT statement is flagged with an
error code (A) in the assembly listing.

range

represents the block of code to be repeated. The repeat block can contain
macro definitions, indefinite repeat blocks, other repeat blocks and/or the
. MEXIT directive (see Section 7.1.3).

.ENDR

indicates the end of the repeat block range. You can also terminate a repeat
block with . ENDM.

The . REPT directive duplicates a block of code, a certain number of times, in line with
other source code.
Use the . MEXIT directive to leave a . REPT loop, if you 'Nant to exit the loop before its
normal completion.

7.8 Macro Library Directive: .MCALL
Format:
.MCALL

argl,arg2, ... argn

where:
arg1,arg2, ... argn

represent the symbolic names of the macro definitions required in
the assembly of the source progra.m. The names must be separated
by any valid separator (comma, space, and/or tab).

The .MCALL directive identifies any system and/or user-defined macro definitions that
are not defined within the source program but which are required to assemble the
program.
The . MCALL directive must appear before the first occurrence of a call to any externally
defined macro if:
•

Auto-Mcall mode is disabled (the default)

•

The name of the macro being called is the same as one of MACRO's permanent
symbols or directives, such as SUB, . ERROR, or . PRINT. Otherwise, MACRO will use
the permanent symbol or directive instead of the lItaCro from the library.

The /ML switch (see Section 8.1.3) under RSX-IIM and the /LIBRARY qualifier (see
Section 8.2.2) under lAS and RT -11, used with an input file specification, indicate to
MACRO-II that the file is a macro library. Additional macro libraries to be searched
can also be specified in the MACRO-II program itself, using the MACRO-II . LIBRARY
directive. See Section 6.10.1 for a description of the. LIBRARY directive. When a macro
call is encountered in the source program, MACRO-II first searches the user macro

7 -22

PDP-ll MACRO-ll Language Reference Manual

library for the named macro definitions and, if necessary, continues the search with
the system macro library.
You can specify any number of user-supplied libraries l . For multiple library files,
the search for the named macros begins with the last such file specified. The files are
searched in reverse order un til the required macro definitions are found, finishing, if
necessary, with a search of the system macro library.
If any named macro is not found upon completion of the search, the . MCALL statement
is flagged with an error code (U) in the assembly listing. Furthermore, a statement
elsewhere in the source program that attempts to expand such an undefined macro is
flagged with an error code (0) in the assembly listing.

The command strings to MACRO-ll, through which file specifications are supplied,
are described in detail in the applicable system manual (see the Associated Documents
section in the Preface).

7.9 Macro Deletnon Directive: .MDELETE
Format:
.MDELETE namel,name2, ... namen

where:
name l,name2, ... namen

represent valid macro names. When multiple names are
specified, they are separated by any valid separator (comma,
space, and/or tab).

The . MDELETE directive deletes the definitions of the specified macro(s), freeing virtual
memory. If references are made to deleted macros, the referencing line is flagged with
an op code (0) error.
An example of the . MDELETE directive is shown below .
. MDELETE

.EXIT,EXIT$S

1 The number is restricted under R'T-11. See Section 6.10.1.

Macro Directives

7 -23

Chapter 8

IAS/RSX-11M/RSX-11M-PLUS Operating
Procedures
MACRO-II assembles one or more ASCII source files containing MACRO-II
statements into a single relocatable binary object file. This binary object file contains
the table of contents listing, the assembly listing, and the symbol table listing. An
optional cross-reference listing of symbols and macros is available. A sample assembly
listing is provided in Appendix H.

8.1 RSX-11 M/RSX-11 M-PLUS Operating Procedures
On RSX-IIM and RSX-IIM-PLUS systems, two command languages are available:
the Monitor Console Routine (MCR) and the DIGITAL Command Language (DCL).
When you log onto the system, you are given either MCR or DCL as the default
command language. Your default command language is contained in your account file.
By pressing ICTRL/cl (echoed as "C) at the monitor prompt, you can see the explicit
prompt for the command language you are currently using:
> AC
MeR>
> AC
DCL>

You can switch from one command language to the other. To switch froin DCL to
MCR, type the following command:
DeL> SET TERMINAL MCR

To switch fromMCR to DCL, type the following command:
MeR> SET IDCL=TI:

In addition to switching from one command language to the other, you can type a
DCL command from a terminal set to MCR, and an MCR command from a terminal
set to DCL, as shown below:
MeR> DCL cmd-string
DeL> MCR cmd-string

IAS/RSX-ll M/RSX-ll M-PLUS Operating Procedures

8-1

8.1.1 Running MACRO-11 Under RSX-11 M/RSX--11 M-PLUS
The following sections describe those MACRO-II operating procedures that apply to
both the Monitor Console Routine and the DIGITAL Command Language. You can
use any of the four methods shown below to run MACRO-II:
•

Direct MACRO-II call

•

Single assembly

•

Install, run immediately, and remove on exit

•

Indirect command processor

8.1.1.1 Direct MACRO-11 Call

MCR Format:
MCR>MAC
MAC>cmd-string

When you call MACRO-II directly, the Monitor Console Routine (MCR) accepts MAC
as input and runs MACRO-I1. Since a command string is not present with the MCR
line, MACRO-II then asks for input with the prompting sequence MAC> and waits for
command string input. After the assembly of the specified files has been completed,
MACRO-II again asks for command strin input with the MAC> prompting sequence.
This process repeats until you press CTRL/Z.
DCL Format:
DCL> MACRO[/qualifier(s)]
File(s)? filespec [/qualifiers] ...

DCL accepts MACRO as input and runs MACRO-II. In addition, you can include
the qualifiers contained in Table 8-3. Since no file specifications are included in the
DCL command line, MACRO-II asks for input with the File(s)? prompt. You can
then enter the name of one or more source files plus any of the qualifiers listed in
Table 8-4. When you press RETURN, MACRO-It does the assembly.
8.1.1.2 Single Assembly

MCR Format:
MCR>MAC cmd-string

DCL Format:
DCL> MACRO cmd-string

When you do a single assembly, no prompting from MACRO-II occurs, since the
command line includes the command string input. MACRO-II assembles the source
files in the command string and exits when finished.

8-2

PDP-ll MACRO-ll Language Reference Manual

8.1.1"3 Install, Run Immediately, and Remove on Exit

Fornlat:
>RUN $MAC
MAC> cmd-string

Use this method when MACRO~tt is not permanently installed in the system. On
RSX·-tlM, the system must be generated for this type of call support. MAC is run
from the system directory. MACRO-tt asks for command string input. The command
string must have the MCR format, even if run from a DCL terminal. When MACRO-tt
exits, it: is removed from th~ system.
If· the system has the "flying install" feature, the RUN $ calling format is not needed.
8.1.1.4 Indirect Command Processor

MCR Formats:
MCR> MAC
MAC> @filespec

or:
MCR>MAC @filespec

or:
MAC>RUN $MAC[/UIC=[g.m]]
MAC> @filespec

These commands use the indirect command processor, which effectively substitutes
"@filespec" for the "cmd-string" input used in the other methods. In the commands
shown above, the indirect command processor passes commands to MACRO-tt. The
file specified as @filespec contains MACRO-tt command strings. After this file is
opened, command lines are read from the file until the end-of-file is detected. Three
nested levels of indirect files are permitted in MACRO-tt.
MCR and DCL Format:
DCL> @filespec

These forms use the indirect command processor to pass commands to the command
language. This is the only form you can use with DCL. The indirect command file
@filespec must contain one of the comlnand lines to run MACRO-tt as listed in the
other methods.
NOTE
MACRO-tt can be terminated by entering a ICTRL/Z I any
time a request for command string input is pending.

IAS/RSX-ll M/RSX-ll M-PLUS Operating Procedures 8-3

8.1.2 Default RSX-11 File Specifications
MACRO-II accepts as input or creates as output up to six types of files. When using
the MACRO-II assembler, you should keep in mind the default device, directory,
name, and types listed in Table 8-1. Table 8-1 lists the default values for eacl1 file
specific a tion.
Table 8-1:

RSX-11 File Specification Default Values
Default V,dues

File

Device

Directory

Filename

Type

Object file

Your default volume

Current

None

.OBJ

Listing file

Device used for object
file

Directory used in object file

None

.LST

Source

Your default volume

Current;
used for
source 1 or device
of last source file
specified

None

. MAC

User macro library

Your default volume

Current, if macro file·
is specified first; if not,
directory of last source
file

None

.MLB

System macro library

Library device

Library [1,1]

RSXMAC

.SML

Indirect command file

Your default volume

Current

None

.CMD

8.1.3 MCR Command String Format
In response to the MAC> prompting sequence printed by MACRO-II, type the output
and input file specifications in the form shown below:
MAC>objeet.listing=srel.sre2 ..... sren

where:
object

represents the binary object (output) file.

listing

represents the assembly listing (output) file containing the table of
contents, the assembly listing, and the symbol table.
separates output file specifications from input file specifications.

src 1,src2, ... srcn

represent the ASCII source (input) files containing the MACRO11 source program or the user-supplied macro library files to be
assembled.

Only two output file specifications in the command string are recognized by MACRO11; any more than two output files are ignored. No limit is set on the number of
source input files. If the entire command string is longer than 80 characters and less
than or equal to 132 characters, a hyphen can be placed at the end of the first line as
a continuation character.

8-4 PDP-ll MACRO-ll Language Reference Manual

A null specification in either of the output file specification fields signifies that the
associated output file is not desired. A null specification in the input file field,
however, is an error condition, resulting in the error message MAC-Illegal filename
on the command output device (see Section 8.5). The absence of both the device
name (dev:) and the name of the file (filename. type) from a file specification is the
equivalent of a null specification.

NOTE
When no listing file is specified, any errors encountered
in the source program are ,printed on the terminal from
which MACRO-II was started. When the /NL switch is
used in the listing file specification without an argument,
the errors and symbol table are written to the file specified.
Each file specification contains the following information:
filespec /switch:value ...

where:
filespec
jswitch

I
i.s the standard file specification.

represents an ASCII name identifying a switch option. This switch option
can be specified in three forms, as shown below, depending on the function
desired:
jswitch
Enables the specified switch action.
jnoswitch

Negates the specified switch action.

j-switch

Negates the specified switch action.

In addition, the switch identifier can be accompanied by ASCII character strings, octal
numbers, or decimal numbers. The default assumption for a numeric value is octal.
Decimal values lIlUSt be followed by a decimal point (.).
Any numeric value preceded by a number sign (#) is regarded as an explicit octal
declaration; this option is provided for command line documentation and ready
identification of octal values.
Also, any numeric value can be preceded by a plus sign (+) or a minus (-) sign.
The positive specification is the default assumption. If an explicit octal declaration is
specified (#), the sign indicator, if included, must precede the number sign.
All switch values must be preceded by a colon (:).
The switch specifications are interpreted in the context of the program to which they
apply. The switch options applicable to MACRO-II are described in Table 8-2.
If MACRO-II detects a syntax error in the command string, MACRO-II writes the
error message MAC-Command syntax error to the command output device, followed
by a copy of the entire command string.

IASjRSX-l1 MjRSX-ll M-PLUS Operating Procedures 8-5

At assembly time, you may want to override certain MACRO-II directives appearing
in the source program or to provide MACRO-II with information establishing how
certain files are to be handled during assembly. You can do so through one or
more switches, which can be selectively included as additional parameters in each
file specification. The available switches for MACRO-II file specifications under
RSX-IIMjRSX-IIM-PLUS are listed in Table 8-2.
Table 8-2:

RSX-11 File Specification Switches for MACRO-11

Switch

Function

/LI:arg
/NL:arg

Listing control switches; these options accept ASCII switch values (arg) which
are equivalent in function and name to the arguments for the . LIST and
. NLIST directives you can include in your source program (see Section 6.1.1).
Arguments that you specify with the /LI: arg and /NL: arg switches override
any arguments that you may have specified with the . LIST and . NLIST
directives and remain in effect for the entire assembly process.

/EN:arg
/DS:arg

Function control switches; these options accept ASCII switch values (arg) which
are equivalent in function and name to the arguments for the . ENABL and
.DSABL directives you can include in your source program (see Section 6.2.1).
Arguments that you specify with the /EN: arg and /DS: arg switches override
any arguments that you may have specified with the . ENABL and . DSABL
directives and remain in effect for the entire assembly process.

/ML

The /ML switch, which takes no accompanying switch values, identifies an input
file as a macro library file. As noted in Section 7.8, any macro that is defined
externally must be identified by a . MCALL directive before it can be retrieved
from a macro library file and assembled with the user program. In locating
macro definitions, MACRO-II performs a fixed search algorithm, beginning
with the last specified user macro file, continuing in reverse order with each
such specified file, and terminating, if necessary, with a search of the system
macro library file. If a required macro definition is not found upon completion
of the search, an error code (U) is written in the assembly listing. Therefore, a
user macro library file must be specified in the command line or by using the
MACRO-II .LIBRARY directive (see Section 6.10.1) prior to the source file(s)
that use macros defined in the library file.
MACRO-II does not prescan the command line for macro libraries; when a
new source file is needed, MACRO-II parses the next input file specification.
If that file specification contains the /ML switch, it is appended to the front of
the library file list. As a result, a user macro library file must be specified in
the command line prior to the source files which require it, in order to resolve
macro definitions.

8-6

/SP

Spool listing output (default value).

/NOSP

Do not spool output.

/CR: [arg]

Produce a cross-reference listing (see Section 8.3).

PDP-ll MACRO-ll Language Reference Manual

Switches for the object file are limited to lEN and IDS; when specified, they apply
throughout the entire command string. Switch options for the listing file are limited to
ILl, INL, ISP, ICR, and INoSP. Switches for input files are limited to IML, lEN, and IDS;
the option IML applies only to the file immediately preceding the option so specified,
whereas the lEN and IDS options, as noted above, are also applicable to subsequent
files in the command string.
Do not specify the same switch more than once following a file specification. If you
do, the values included with any duplicate switch specification override any previously
specified values. If you want to include two or more values for the same switch,
separate them by colons, as shown below:
ILI:SRC:MEB

8.1.4 DCI. Operating Procedures
RSX-1 1MjRSX-l 1M-PLUS indicates its readiness to accept a command by prompting
with the DCL prompt. In response to the prompt, enter the command string in one of
the forrnats shown below:
>MACRo[/qualifiers]
FILE? filespec [/qualifiers] [,filespec [/qualifiers] ... ]

or:
[DCL]>MACRo[/qualifiers] filespec [/qualifiers] [,filespec [/qualifiers] ... ]

where:
qualifiers

affect either the entire command string (command qualifiers) or the filespec
(parameter qualifiers). See Table 8-3 for a description of the command
qualifiers and Table 8-4 for a description of the parameter qualifier.

filespec

is the standard file specification shown in Section 8.4.

Use a comma (,) to separate file specifications. MACRO-II concatenates all the files
and then perfornls the assembly.
Table 8-3:

RSX-11 DCl Command Qualifiers

Qualifier

Function

I [NO] CROSS_REFERENCE

Suppresses or generates a cross-reference listing (see
Section 8.3). When the cross-reference is generated, a listing
file is also generated, whether or not the ILIST qualifier is
present in the command string.
The default is INoCROSS_REFERENCE.

IAS/RSX-ll M/RSX-ll M-PLUS Operating Procedures 8-7

Table 8-3 (Cont.):

RSX-11 DCl Command Qualifiers

Qualifier

Function

/DISABLE:arg
/ENABLE:arg
/DISABLE:(arg,arg ... )
/ENABLE: (arg,arg ... )

Overrides the . DISABLE or. ENABLE assembler directives in
the source program. When more than one argument is entered,
arguments must be enclosed in parentheses and separated by
commas.
You can specify any of the following arguments with the
/DISABLE or /ENABLE qualifier:

ABSOLUTE

If enabled, MACRO-II assembles all relative
addresses (address mode 67) as absolute
addresses (address mode 37).

The default is Disabled.
If enabled, MACRO-II searches all known
macro libraries for a macro definition that
matches any undefined symbols appearing in
the op code field of a MACRO-II statement.

The default is Disabled. If MACRO·-II finds
an unknown symbol in the op code field,
it either declares an undefined symbol (U)
error, or declares the symbol as an external
symbol, depending upon the GLOBAL argument
described below.

BINARY

If enabled, MACRO-II produces absolute
binary output in FILES-II format.

The default is Disabled.

CARD_FORMAT

If enabled, MACRO-II treats columns 73
through the end of the line as comnlents.

The default is Disabled.

CASE_MATCH

If enabled, MACRO-II makes the conditional
assembly directives . IF IDN and . IF DIF
alphabetically case sensitive.

The default is not case sensitive.

GLOBAL

If disabled, MACRO-II flags all undefined
symbol references with an error code (U) on
the assembly listing.

The default is Enabled; MACRO-II treats
all symbols that are undefined at the end of
assembly pass I as default global references.

8-8 PDP-ll MACRO-ll Language Reference Manual

Table 8-3 (Cont.):

RSX-11 DCl Command Qualifiers

Qualifier

Function

LOCAL

If enabled, MACRO-II treats all symbols as

local symbols.
When enabled, all global
symbols are flagged with the undefined
symbol (U) error message.
The default is Disabled.

LOWER_CASE

If disabled, MACRO-II converts all lowercase

ASCII input to uppercase.
The default is Enabled.

REGISTER_DEFINITIONS
If disabled, MACRO-II ignores the normal

TRUNCATION

If enabled, MACRO-II performs floatingpoint truncation. If disabled, MACRO-II

performs floating-point rounding.
The default is Disabled.

I[NO]LIST[:filespec]

Specifies whether or not MACRO-II should create and print
a listing file. You can include ILIST as a qualifier for either
a command or a file specification. If ILIST qualifies the
command, the listing file is both entered in your directory
and printed on the line printer. If you do not include a file
specification, the listing file has a . LST file type and is named
after the last file named in the MACRO command. The listing
file cannot be a library file. (The LINK command and all other
language commands use the name of the first file named in
the command as the default file name.) If ILIST qualifies a
file specification, the file is entered in your directory but is not
printed on the line printer. The listing file is named after the
file it qualifies.
The default is INOLIST.

I[NO]OBJECT[:filespec]

Specifies whether or not MACRO-II should create an object
module. If you do not include a file specification in the
command line, MACRO-II creates an object file with the
same file name as the source file and a .OBJ extension.
The default is IOBJECT.

I[NO]SHOW:arg
I[NO]SHOW: (arg,arg ... )

Overrides any . LIST and . NLIST assembler directives that
may be included in the source file. You can use any of the
following arguments with the ISHOW qualifier:

BINARY

Controls the listing of macro
expansion binary code.

IAS/RSX-ll M/RSX-ll M-PLUS Operating Procedures 8-9

Table 8-3 (Cont.):

RSX-11 DCl Command Qualifiers

Qualifier

Function

/ [NO] WIDE

Table 8-4:

CALLS

Controls listing of macro calls
and repeat range expansions.

COMMENTS

Controls listing of comments.

CONDITIONALS

Controls listing of unsatisfied
conditional coding.

CONTENTS

Controls listing of the table of
contents during assembly pass 1.

COUNTER

Controls listing of the current
location counter field.

DEFINITIONS

Controls listing of macro definitions and repeat range expansions.

EXPANSIONS

Controls listing of macro expansions.

EXTENSIONS

Controls listing of binary expansions.

LISTING_DIRECTIVES

Controls listing of listing control
directives without arguments,
that is, directives that alter the
listing level counter.

OBJECT_BINARY

Controls listing of the generated
binary code.

SEQUENCE_NUMBERS

Controls listing of source line
sequence numbers.

SOURCE

Controls listing of source lines.

SYMBOLS

Controls listing of the symbol table resulting from the assembly.

When set to /WIDE, the listing is printed in 132-column format.
When set to /NOWIDE, the listing is printed in 80-column
format. The default is /NOWIDE.

RSX-11 DCl Parameter Qualifier

Qualifier

Function

/LIBRARY

Specifies that an input file is a macro library file.
The assembler processes the files listed in the command line in reverse order.
Therefore, a library file cannot be the last file in the command line.

8-10

PDP-ll MACRO-ll Language Reference Manual

8.1.5 MACRO-11 Command String Examples
Exanlple 1:
The following commands assemble the source file FILNAM. MAC into a relocatable object
module named FILNAM. oBJ:
MCR> MAC FILNAM=FILNAM
DCL> MACRO
FILE? FILNAM
DCL> MACRO FILNAM

Exanlple 2:

The following commands assemble the source file FILNAM. MAC and produce an object
file with the name TESTA. oBJ:
MCR> MAC TESTA=FILNAM
DCL> MACR%BJECT:TESTA FILNAM

Example 3:
The following commands concatenate and assemble the source files named FILNAM. MLB,
TESTA.MAC, SPAN3"MAC, and SHELL. MAC and create an object file named SHELL.oBJ:
MCR> MAC SHELL=FILNAM/ML,TESTA,SPAN3,SHELL
DCL> MACRO FILNAM/LIBRARY,TESTA,SPAN3,SHELL

Example 4: The following commands produce an object module and an assembly
listing. Any . LIST TTM or . LIST COM directives in the source file are ignored. The listing
produced by this command includes no comments and is printed in wide format:
MCR> MAC FILNAM,FILNAM/NL:TTM:CoM=FILNAM
DCL> MACRo/LIST/NoSHoW:CoMMENTS/WIDE FILNAM

8.2 lAS MACRO-11 Operating Procedures
The foHowing sections describe those MACRO-11 operating procedures that apply
exclusively to the lAS system.

8.2.1 Running MACRO-11 Under lAS
The MACRO command used under lAS assembles one or more ASCII source files
containing MACRO-11 statements into a relocatable binary object file. MACRO-11
also produces an assembly listing followed by a symbol table listing. A cross-reference
listing can also be produced by means of the /CRoSSREFERENCE qualifier (see Section 8.3
below).
You can call MACRO-11 directly frorn the terminal (interactive mode) or from a
batch file (batch mode). For interactive mode, use the MACRO command, which can be
issued whenever the lAS Program Development System (PDS) is at command level, a
condition signified by the appearance of the prompt:
PDS>

IASjRSX-ll MjRSX-ll M-PLUS Operating Procedures 8-11

For batch mode, use the $MACRO command.
When the assembly is completed, MACRO-II terminates operations and returns control
to PDS. (Refer to the lAS User's Guide for further information about interactive and
batch mode operations.)

8.2.2 lAS Command String
Formats:
Interactive Mode:
filespec /LIBRARY +

PDS> MACRO qualifiers

or:
PDS> MACRO qualifiers
FILES?

filespec /LIBRARY

Batch Mode:
$MACRO qualifiers

filespec /LIBRARY + ...

where:
filespec

is the specification of an input file (see Section 8.4) that contains ]\.1ACRO11 source program code. When the program consists of multiple files, a
plus sign (+) must be used to separate each file specification from the next.
The "wild card" form of a file specification is not allowed.

/LIBRARY

specifies that an input file is a macro library file. Library files hold the
definitions of externally defined macros. As noted in Section 7.8, an
externally defined macro must be identified in a . MCALL directive before
it can be retrieved and assembled with your program. When MACRO-II
encounters a . MCALL directive, a search begins for the definitions of the
macros listed.
The search order is important, because a macro might have two different
definitions in library files LIBl and LIB2. For example, if you need the
definition in LIB1, you must place LIBl after LIB2 in the command line,
because MACRO-II searches the last file specified in the comnland line
first, then moves backwards through the given files until all have been
searched.
If a macro's definition is not found in any of the files named by the
user, MACRO-II automatically searches the system macro library; if the

definition is still not found, an error code (U) is generated in the assembly
listing.

8-1 2

PDP-ll MACRO-ll Language Reference Manual

qualifiers

specifies one or more of the following:
jOBJECT[:filespec]

produces an object file as specified by filespec (see
Section 8.4). The default is a file with the same
filename as the last named source file and a . DBJ
extension. IDBJECT is always the default condition.

jNOOBJECT

does not produce an object file.

jLIST[:filespec]

produces an assembly listing file according to
filespec (see Section 8.4).
If filespec is not
specified, the listing is printed on the line printer.
The default in interactive mode is INDLIST and in
batch mode is ILIST.

jNOLIST

does not produce a listing file.
The default in
interactive mode is INDLIST and in batch mode is
ILIST.

When no listing file is specified, any errors
encountered in the source program are displayed at
the terminal from which MACRO-II was initiated.
jCROSSREFERENCE[:argI ... arg4]
produces a cross-reference listing. Arg1 through arg4
are described in Section 8.3. This qualifier can be
abbreviated to IC.

A MACRO~II command string can be specified by using anyone of the three formats
shown above for the interactive and batch modes. In interactive mode, if the input
file specification (filespec) does not begin on the same line as the MACRO command
and its qualifiers, PDS prints the following prompting message:
FILES?

then waits for you to specify the input file(s).
In batch mode, the $MACRD command and its arguments must appear on the same line
unless the PDS line continuation symbol (-) is used.

8.2.3 lAS Indirect Command Files
Format:
@filespec

where:
@

specifies that the name that follows is an indirect file.

filespec

is the file specification (see Section 8.4) of a file that contains a command
string. The default extension for the file name is . CMD.

You can use the indirect command file facility of PDS with MACRO-II command
strings. Create an ASCII file that contains the desired command strings (or portions
thereof) in the forms shown in Section 8.2.2. When an indirect command file reference

IASjRSX-ll MjRSX-ll M-PLUS Operating Procedures

8-1 3

is used in a MACRO-II command string, the contents of the specified file are taken
as all or part of the command string.
An indirect command file reference must always be the rightmost entry in the command
(see Section 8.2.4 for examples).

8.2.4 lAS Command String Examples
The following examples show typical PDS MACRO-II command strings.
Example 1:
PDS> MACRO /NOLIST
FILES? A+BOOT.MAC;3

In this example, the source files A.MAC and BOOT .MAC;3 are assembled to produce·
an object file called BOOT.OBJ. No listing is produced.
Example 2:
Where the indirect command file TEST. CMD contains the command string:
MACRO/OBJECT:MYFILE A+B

the command:
PDS>@TEST

assembles the two files A. MAC and B. MAC into an object file called MYFILE. OBJ.
Example 3:
Where the indirect command file IND02. CMD contains the command string segment:
ATEST/LIBRARY+BTEST+SRT1.021

the command:
PDS>MACRO/LIST:DK1:TST

@IND02

assembles the files BTEST. MAC and SRT1.021, using the macro library file ATEST. MAC to
produce an object file named SRT1. OBJ. A listing file named TST. LST is placed on disk
unit 1.
Example 4:
$MACRO/LIST:DKO:MICR/NOOBJECT
LIB1/LIBRARY+MICR.MAC;002

In this example, the library file is assembled with the file MICR. MAC; 002. The program
listing file named MICR. LST is placed on disk unit O.

8.3 Cross-Reference Processor (CREF)
The CREF processor is used to produce a listing that includes cross-references to
symbols that appear in the source program. The cross·-reference listing is appended to
the assembly listing. Such cross-references are helpful in debugging and in reading
long programs.

8-14 PDP-ll MACRO-ll Language Reference Manual

A cross-reference listing can include up to four sections:
•

User-defined symbols

•

Macro symbols

•

Permanent symbols

To generate a cross-reference listing, specify the ICR switch in the MACRO-II command
string. Optional arguments can also be specified. The form of the switch is:
SYM
MAC
REG
PST
SEC
ERR

/CR

where:
SYM

specifies user-defined symbols (default).

MAC

specifies macro symbols (default).

REG

specifies register symbols.

PST

specifies permanent symbols.

SEC

specifies program sections.

ERR

specifies error lines (default).

If you want to generate listings for user,-defined and macro symbols only, use ICR. No
argument is necessary.

However, if an argument is specified, only that type of cross-reference listing is
generated. For example:
ICR:SYM

produces a cross-reference listing of user-defined symbols only. No listing of macro
symbols is generated. Thus, to produce all six types of cross-reference listings, you
must specify all six arguments; the order in which they are specified is not significant.
Use a colon to separate arguments, for example:
ICR:REG:SYM:MAC:PST:SEC:ERR

The CREF processor (CRF) is more fully described in the Utilities Reference Manual
supplied with your system.

IAS/RSX-ll M/RSX-ll M-PLUS Operating Procedures 8-1 5

Figure 8-1 illustrates a complete cross-reference listing. In the listing, references are
made in the form page-line. To make the listing more informative, the CREF processor
uses the following signs:
somewhere in the source program the symbol listed is defined by a direct
assignment statement.

destructive reference; the value of the symbol is changed (its previous contents
destroyed) by the program instruction at the line number marked by the
asterisk ("').

symbol definition; the symbol is defined by a direct assignment statement, a
colon sign (:), or a double colon sign (::) at the line number marked by the
number sign (#).

Figure 8-1:

Sample lAS CREF Listing

R50UNP
CREATED BY MACRO ON 4-AUG-87 AT 12:17
SYMBOL CROSS REFERENCE
SYMBOL VALUE
REFERENCES
R50UNP
000000 RG
#2-42
SYMBOL = ****** G
2-38
2-43
2-51
TABLE
000062 R
2-66
#2-70

PAGE 1
CREF
V02

R50UNP
CREATED BY MACRO ON 4-AUG-87 AT 12:17
REGISTER SYMBOL CROSS REFERENCE
SYMBOL
REFERENCES
RO
2-66
*2-64
*2-65
*2-49
2-49
R1
*2-44
R2
*2-66
R3
2-65
*2-45
*2-47
R4
2-42
2-51
*2-43
*2-44
SP
*2-42
*2-53

PAGE 2
CREF
V02

R50UNP
CREATED BY MACRO ON 4-AUG-87 AT 12:17
PERMANENT SYMBOL TABLE CROSS REFERENCE
SYMBOL
REFERENCES
BNE
2-52
CALL
2-46
2-48
2-50
CLR
2-64
CMP
2-51
DIV
2-65
MOV
2-42
2-43
2-44
2-45
2-53
MOVB
2-66
RETURN
2-54
2-67
2-70
. BYTE
2-71
2-72
2-73
. END
2-76
.GLOBL
2-38
.IDENT
1-2
.NLIST
2-69
.PSECT
2-40
.SBTTL
2-25
.TITLE
1-1

PAGE 3
CREF
V02

Figure 8-1 Cont'd. on next page

8-16

PDP-ll MACRO-ll Language Reference Manual

*2-53

2-47

2-74

2-49

Figure 8-1 (Cont.):

Sample lAS CREF Listing

R50UNP
CREATED BY MACRO
SECTION CROSS REFERENCE
SECTION NAME
REFERENCES
0-0
2-40
PUREI
#0-0
. ABS.

ON 4-AUG-87 AT 12:17

PAGE 4
CREF
V02

8.4 IAS/RSX-11 M/RSX-11 M-PlUS File Specification
Format:
dev: [g,m]name.ext;ver

where:
dev:

is the name of the device where the desired file resides. A device name
consists of two characters followed by a 1- or 2-digit device unit number
(octal) and a colon (for example, DP1:, DKO:, DT3:). The default device is
specified in Table 8-1. The default device under lAS is established initially
by the system manager for each user and can be changed through the SET
command.

[g,m]

is the User File Directory (UFD) code. This code consists of a group number
(octal), a comma (,) and an owner (member) number (octal) all enclosed in
brackets ([ D. An example of a UFD code is: [200,30].
The default UFD is equivalent to the User Identification Code (UIC) given at
login time. Under lAS, the UFD can be changed through the SET DEFAULT
command.

name

is a 1- to 9-character alphanumeric filename. There is no default.

.ext

is a 1- to 3-character alphanumeric filename extension or type that is preceded
by a period (.). An extension is normally used to identify the nature of the
file. Default values depend on the context of the file specification and are as
follows:
· CMD
Indirect command (input) file

;ver

· LST

A listing (print format) file

· MAC

MACRO-II source module (input file)

.OBJ

MACRO-II object module (output file)

· CRF

Intermediate CREF input file created by MACRO-II

is an octal number between 1 and 77777 that is used to differentiate between
versions of the same file. This number is prefixed by a semicolon (;).
For input files, the default value is the highest version number of the file
that exists.
For output files, the default value is the highest version number of the file
that exists increased by 1. If no version number exists, the value 1 is used.

IAS/RSX-ll M/RSX-ll M-PLUS Operating Procedures

8-1 7

This is the general form for a file specification in IAS/RSX-11M/RSX-11M-PLUS
systems. Detailed information is provided in the applicable system user's guide or
operating procedures manual (see the Associated Documents section in the Preface).

8.5 MACRO-11 Error Messages Under
IASjRSX-11 MjRSX-11 M-PLUS
MACRO-11 writes an error message to the command output device when one of
the error conditions described below is detected. MACRO-11 writes below the error
message the command line that caused the error. If the error is a . INCLUDE or a
. LIBRARY directive file error, MACRO-11 writes both the source line and the command
line that caused the error.
MAC -- Error message
MACRO-11 source line
MACRO-11 command line

These error messages reflect operational problems and should not be confused with
the error codes (see Appendix D) produced by MACRO-11 during assembly.
All the error messages listed below, with the exception of the MAC-Command I/O
error message, terminate the current assembly; MACRO-11 then attempts to restart
by reading another command line. In the case of a command I/O error, however,
MACRO-11 exits, since it is unable to obtain additional command line input.
MAC-Command file/open failure
Either the file from which MACRO-II is reading a command could not be opened
initially or between assemblies; or the indirect conlmand file specified as @filename
in the MACRO-II command line could not be opened. See MAC-Open failure on

input file.
MAC-Command I/O error
An error was returned by the file system during MACRO-II's attempt to read a
command line. This is an unconditionally fatal error, causing MACRO-II to exit. No
MACRO-II restart is attempted when this message appears.

MAC-Command syntax error
An error was detected in the syntax of the MACRO-II command line.

MAC-Illegal filename
Neither the device name nor the filename was present in the input file specification (the
input file specification was null), or a wild card convention (asterisk) was employed
in an input or output file specification.
Wildcard options ("') are not permitted in MACRO-II file specifications.

MAC-Illegal switch
An invalid switch was specified for a file, an invalid value was specified with a switch,
or an invalid use of a switch was detected by MACRO-II.

8-1 8

PDP-l1 MACRO-ll Language Reference Manual

MAC-.INCLUDE directive file error
The file specified in the . INCLUDE statement either does not exist or is invalid, the
device specified in the command line is not available, or the . INCLUDE stacking depth
exceeds five.

MAC-Indirect command syntax error
The name of the indirect command file (@filename) specified in the MACRO-II
command line is syntactically incorrect.

MAC-Indirect file depth exceeded
An attempt to exceed the maximum allowable number of nested indirect command files
has occurred. (Three levels of indirect command files are permitted in MACRO-It.)

MAC-Insufficient dynamic memory
There is not enough physical memory available for MACRO-II to page its symbol
table. Reinstall MACRO-II in a larger partition, or see Section F.3.

MAC-Invalid format in macro library
The library file has been corrupted, or it was not produced by the Librarian utility
program (LBR).

MAC-I/O error on input file
In reading a record from a source input file or macro library file, the file system
detected an error; for example, a line containing more than 132 10 characters was
encountered. This message may also indicate that a device problem exists or that
either a source file or a macro library file has been corrupted with incorrect data.

MAC-I/O error on macro library file
Same meaning as MAC-I/O error on input file, except that the file is a macro library
file and not a source input file.

MAC-I/O error on output file
The file system detected an error while writing a record to the object output file or
the listing output file. This message may also indicate that a device problem exists or
that the device is full.

MAC-I/O error on work file
A read or write error occurred on the work file used to store the symbol table. This
error is most likely caused by a problem on the device or by an attempt to write to a
full device.

MAC-.LIBRARY directive file error
The file specified in the . LIBRARY statement either does not exist or is invalid, the file
specification in the . LIBRARY directive is for a nonrandom access device, the device
specified in the command line is not available, or the. LIBRARY stacking depth exceeds
the maximum depth allowed.

IAS/RSX-ll M/RSX-ll M-PLUS Operating Procedures 8-1 9

MAC-Open failure on input file
One of the following conditions exists:
•

The specified device does not exist.

•

The volume is not mounted.

•

A problem exists with the device.

•

The specified directory file does not exist.

•

The specified file does not exist.

•

You do not have access privilege to the file directory or to the file itself.

MAC-Open failure on output file
One of the following conditions exists:

•

The specified device does not exist.

•

The volume is not mounted.

•

A problem exists with the device.

•

The specified directory file does not exist.

•
•

You do not have access privilege to the file directory.
The volume is full, or the device is write protected.

•

There is insufficient space for File Control Blocks.

MAC-64K storage limit exceeded
64K words of work file memory are available to MACRO-II. This message indicates

that the assembler has generated so many symbols (about 13,000 to 14,000) that it has
run out of space. Either the source program is too large to start with, or it contains a
condition that leads to excessive size, such as a macro expansion that recursively calls
itself without a terminating condition.

8-20

PDP-ll MACRO-ll Language Reference Manual

Chapter 9

RSTS/RT-11 Operating Procedures
9.1 MACRO-11 Under RSTS
The only way a MACRO-II program can run on a RSTS system is through either the
RT-II or RSX run-time systems.

9.1.1 RT-11 Through RSTS
There are two ways to run MACRO-II under the RT-II run-time system on RSTS:
•

Use the RT-II Emulator. This is done by typing 8W RT11. The terminal will respond
with the RT--II prompt (a dot printed by the keyboard monitor). You can then
use the RT-II commands (see Section 9.2).

•

Type the conlmand RUN $MACRD. 8AV. The terminal will respond with an asterisk (*)
prompt. You can then enter a command string of the form:
objfil.lstfil=srel •... sre6

where:
objfil

is an object (output) file with the default extension. DBJ.

lstfil

is a listing (output) file with the default extension . L8T.

srcl,,,.src6

are source (input) files with the default extension . MAC. Six input
files are allowed in this command.

9.1.2 RSX Through RSTS
To run MACRO-II under the RSX run-time system on RSTS, type the command:
RUN $MAC. T8K. The terminal will display:
MAC>

In response, enter a command string of the form:
objfil.lstfil=srel .... sren

where:
objfil

is an object (output) file with the default extension . DBJ.

lstfil

is a listing (output) file with the default extension . L8T.

srcl,,,.srcn

are source (input) files with the default extension . MAC.

RSTS/RT-11 Operating Procedures

9-1

NOTE
You can use other RSTS commands to call the RT -11 and
RSX run-time systems, but they are site dependent and
so are not mentioned here.

9.2 Running MACRO-11 Under RT-11
The following sections describe those MACRO-II operating procedures that apply
only to the RT-ll system. Table 9-1 lists the default file specifications for RT-l1.
Table 9-1:

RT-11 Default File Specification Values
Default

File

Device

Filename

Type

Object

OK:

Must specify

.OBJ

Listing

Same as for object file

Must specify

.LST

Logical device name CF:,

CREF

.TMP

WRK

.TMP

Must specify

. MAC

Must specify

. MAC

SYSMAC

.SML

Must specify

.MLB

CREF

if it has been defined;

otherwise, OK:
Work

Logical device name WF:,
if it has been defined;
otherwise, OK:

First source

OK:

Additional source

Same as for
source file

preceding

System macro library System device SY:
User macro library

OK: if first file; otherwise,

same as for
source file

preceding

9.2.1 RT-11 Command String (CSI) Format
To call the MACRO-II assembler from the system device, respond to the system
prompt (a dot printed by the keyboard monitor) by typing:
.R MACRO

When the assembler responds with an asterisk (*), it is ready to accept command
string (CSI) input.
Format:
dev:obj.dev:list.dev:cref/s:arg=dev:srcl.src2 ..... dev:srcn/s:arg

where:

9-2 PDP-ll MACRO-l1 Language Reference Manual

dev:

is any valid RT -11 device for output; any file-structured device for
input. If dev: is omitted, DK: is assumed.

obj

is the file specification of the binary object file that the assembly
process produces; the device for this file should not be TT: or LP:.

list

is the file specification of the assembly and symbol listing that the
assembly process produces.

cref

is the file specification of the CREF temporary cross-reference file
that the assembly process produces. Omission of dev: cref does
not preclude a cross-reference listing, however. If you specify /C
without a CREF filename, MACRO-II uses a default name for the
CREF temporary file on logical device name CF:, if it has been
defined, or on DK:.

/s:arg

is a set of file specification options and arguments (see Table 9-2).

srcl,src2, ... srcn

represent the ASCII source (input) files containing the MACRO11 source progratn or the user-supplied macro library files to be
assembled. You can specify as many as six source files.

The following cOlmmand 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.
*DK:BINF.OBJ.LP:=DK:SRC.MAC

All output file specifications are optional. The system does not produce an output file
(except for the CREF temporary file, if you include the /C option), 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 conlmand string, as determined by the number of commas in the string. For
example, to omit the object file, you must begin the command string with a comma.
The following command produces a listing, including a cross-reference table, but not
a binary object file.
*.LP:/C=SRC1.SRC2

Notice that you need not include a conlma after the final output file specification in
the command string.
Table 9-1 lists the default values for each file specification.
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.
MACRO-II writes WRK. TMP to the logical name WF:, if it has been defined. Otherwise,
MACRO-II puts the work file on DK:. To assigrrthe logical name WF: to a device,
enter the following command:
.ASSIGN dev: WF

where:
dev:

is the file-structured device that will hold WRK. TMP.

RSTS/RT-11 Operating Procedures

9-3

The default size of WRK. TMP is 200 8 blocks. You can increase the size to a maximum of
400 8 blocks with a customization patch. Refer to the file CUSTOM. TXT on your RT -11
distribution kit.

9.2.2 RT-11 CSI Command Line Options
At assembly time, you may need to override certain MACRO directives appearing
in the source programs. You may also need to direct MACRO-II on the handling
of certain files during assembly. You can satisfy these needs by using the switches
described in Table 9-2.
Table 9-2:

File Specification Options

Option

Explanation

IL:arg
IN:arg

Listing control options; these options accept ASCII values (arg) which are
equivalent in function and name to the arguments for the . LIST and
. NLIST directives you can include in your source program (see Section 6.1.1).
Arguments that you specify with the ILl: arg and INL: arg options override any
arguments that you may have specified with the . LIST and . NLIST directives
and remain in effect for the entire assembly process.

IE:arg
ID:arg

Function control options; these options accept ASCII values (arg) which
are equivalent in function and name to the arguments for the . ENABL and
. DSABL directives you can include in. your source program (see Section 6.2.1).
Arguments that you specify with the IE: arg and ID: arg options override any
arguments that you may have specified with the. ENABL and. DSABL directives
and remain in effect for the entire assembly process.

Indicates input file is a MACRO library file. 'When the assembler encounters
a . MCALL directive in the source code, it searches macro libraries according
to their order of appearance in the command string, starting from the right.
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:

* (output file specification)=ALIB/M,BLIB/M,XIZ
Assume that each of the two macro libraries, ALIB. MLB and BLIB. MLB, contains
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.
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. Therefore, if macro library ALIB. MLB contains a definition of
a macro called . READ, that definition of . READ overrides the standard . READ
macro definition in SYSMAC. SML.
IC:arg

Controls contents of cross-reference table.

9-4 PDP-ll MACRO-ll Language Reference Manual

The 1M option affects only the source file to which it is appended. The other options
affect the entire command string.

9.2.3 RT-11 Digital Command Language (DCl) Format
You can enter the MACRO DCL command in response to the monitor prompt (.) to run
MACRO·-ll under RT -11.
Format:

MACRO

jCROSSREFERENCE[:type[ ... :type]]
jDISABLE:type[ ... :type]
jENABLE:type[ ... :type]
jLIST[:filespec]
j ALLOCATE:size
j[NO]OBJECT[:filespec]
j ALLOCATE[:size]
j[NO]SHOW:type[ ... :type]

~ filespecs

[jLIBRARY]

where:
j ALLOCATE:size

reserves space for output file; a size of -1 reserves the
largest possible space.

jCROSSREFERENCE[:type[ ... :type]]
produces CREF listing; type can be:
C
Control section names
E
Error codes
~
~acro names
P
Permanent names
R
Register symbols
S
user-defined symbols
blank
equivalent to :E:~:S
jDISABLE:type[ ... :type]]

specifies . DSABL directives; type can be:
ABS
Produces absolute binary output
A~A
Assembles absolute addresses as relative
addresses
CDR
Treats source columns beyond 72 as a comment
DBG
Writes internal symbol director (ISD) records
FPT
Truncates floating point
GBL
Assumes undefined symbols are globals
LC
Accepts lower~ase characters in source programs
LSB
Defines local symbol block
~CL
Enables or disables automatic . MCALL
PNC
Enables or disables binary output
REG
Defines default register mnemonics

jENABLE:type[ ... :type]]

specifies . ENABL directives; type can be any of the types
listed under jDISABLE.

jLIBRARY

identifies a macro library file.

RSTS/RT-11 Operating Procedures

9-5

jLIST[ :filespec ]

writes program listing to the printer or to filespec.

tNO]OBJECT[:filespec]

[does not] generate a ,OBJ file; output filespec defaults to
input filespec.

[NO]SHOW:type[ ... :type]

specifies MACRO-II . LIST and . NLIST directives; type
can be:
BEX
Extended binary code
BIN
Generated binary code
CND
Unsatisfied conditionals and . IF and . ENDC
statements
COM
Comments
LaC
Location counter
MC
Macro calls, repeat range expansions
MD
Macro definitions, repeat range expansions
ME
Macro expansions
MEB
Macro expansions, binary code
SEQ
Source line sequence numbers
SRC
Source code
SYM
Symbol table
TOC
Table of contents
TTM
Wide or narrow listing format

9.3 Cross-Reference (CREF) Table Generatiion Option
A cross-reference (CREF) table lists all or a subset of the symbols in a source program,
identifying the statements that define and use symbols.

9.3.1 Obtaining a Cross-Reference Table
To obtain a CREF table you must include the IC: arg option in the command string.
Usually you include the IC: arg option with the assembly listing file specification, but
it can appear anywhere on the command line.
If the command string does not include a CREF file specification but does include IC,
MACRO-ll automatically writes a temporary file CREF. TMP to logical name CF:, if it
has been defined. Otherwise, MACRO-ll uses DK:. If you want to use a device other
than DK: for the temporary CREF workfile, include the dev: cref field in the command
string, or assign the logical name CF: to the device you want to use.

A complete CREF listing contains the following sections:
•

A cross reference of program symbols-labels used in the program and symbols
followed by an operator.

•

A cross reference of register symbols-RO, Rl, R2, R3, R4, R5, SP, and PC.

•

A cross reference of MACRO symbols-symbols defined by . MACRO and . MCALL
directives.

•

A cross reference of permanent symbols-all operation mnemonics and assembler
directives.

9-6 PDP-ll MACRO-l1 Language Reference Manual

•

A cross reference of program sections-the names you specify as operands of
. CSECT or . PSECT directives.

•

A cross reference of errors-all flagged errors from the assembly, grouped and
listed by type.

You can include any or all of these sections on the cross-reference listing by specifying
the appropriate arguments with the IC option. These arguments are listed and described
in Table 9-3.
Table 9-3:

Ie Option Arguments

Argument

CREF Section

User defined symbols

MACRO symbolic names

Permanent symbols including instructions and directives

Control and program sections

Error code grouping

NOTE
Specifying IC with no arguments is equivalent to
specifying IC: s: M: E. That special case excepted, you must
explicitly request each CREF section by including its
arguments. No cross-reference file is written if you omit
the IC option, even if the command string includes a
CREF file specification.

9.3.2 Handling Cross-Reference Table Files
When you request a cross-reference listing with the IC option, MACRO-II generates a
temporary file CREF. TMP and writes this file to logical device name CF:, if it is defined.
Otherwise, MACRO-II writes CREF. TMP to DK:.
If the device MACRO-II attempts to use for CREF. TMP is write-protected, or if it contains
insufficient free space for the temporary file, you can specify another device for the file
in your command string. To use another device, you can specify a third output file in
the command string; that is, include a dev: cref specification for the CREF temporary
file in addition to the file specifications for the binary and listing files. (You must still
include the IC option to control the form and content of the listing. The dev: cref
specification is ignored if the IC option is not also present in the command string.)

MACRO-II then uses dev: cref instead of CF: CREF . TMP or DK: CREF . TMP. In any case,
CREF deletes the file automatically after producing the CREF listing.
For example, with the following command string MACRO-II uses RK2: TEMP. TMP as the
temporary CREF file:
*.LP: .RK2:TEMP.TMP=SDURCE/C

RSTS/RT-11 Operating Procedures

9-7

Another way to assign an alternative device for the CREF. TMP file is to assign the logical
name CF: to the device you want to use for CREF. TMP, prior to running MACRO-11:
.ASSIGN dev: CF

This method is convenient if you intend to do several assemblies, as it relieves you
from having to include a dev: cref specification for the CREF file in each command
string. If you enter the ASSIGN dev: CF command, and later include a cref file
specification in a command string, the specification in the command string prevails for
that assembly only.
The system lists requested cross-reference tables following the MACRO assembly
listing. Each table begins on a new page.
The system prints 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 on 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
(lie) next to a reference indicates a destructive reference-an operation that alters the
contents of the addressed location.

9.3.3 MACRO-11 Error Messages Under RT-11
MACRO-11 writes an error message to the command output device when one of
the error conditions described below is detected. MACRO-11 writes below the error
message the command line that caused the error. If the error is a . INCLUDE or a
. LIBRARY directive file error, MACRO-11 writes both the source line and the command
line that caused the error.
?MACRO-s-Error message
MACRO-il source line
MACRO-ll command line

The s in the error message represents the letter code that indicates the severity level
of the error.
These error messages reflect operational problems and should not be confused with
the error codes (see Appendix D) produced by MACRO·-11 during assembly.

9-8 PDP-ll MACRO-ll Language Reference Manual

Message and Meaning

How to Respond

?MACRO-F-Device full <dev:>
The output volume does not have enough
roonl for an output file specified in the
command string.

• Delete unnecessary files from the output
volume, perhaps transferring them to a backup
volume.
• Use another volume with more space.
• Specify an explicit output file size by using
the / ALLOCATE option or include the file size
in square brackets as part of the output file
specification.
• Consolidate free space on the volume by
using the monitor's SQUEEZE command.
• Refer to other techniques for gaining file
space in the RT-ll System Message .Manual.

?MACRO-F-File not found <dev:filnam.typ>
An input file in the command line is not
on the specified. device.

Correct any file specification errors in the
command line and enter it again.

?MACRO-F-.INCLUDE directive file error
1.

The file specified in the . INCLUDE
statement does not exist or is invalid.

The device specified in the command
line is not availahle or its handler is
not loaded.

The. INCLUDE stacking depth exceeds
five.

Check for a typing error in the command
line. Use file specifications that are valid
with the . INCLUDE directive.

Enter the command line again, specifying
an available device, or load the device
handler.

Make sure that the . INCLUDE stacking
depth does not exceed five.

?MACRO-F-Insufficient memory
MACRO-II lacks the minimum amount of
memory (16K words) necessary to run.

• Use the SHOW command to find out
what device handlers are loaded, then use
the UNLOAD command to remove those
that are not necessary.
After unloading
any unnecessary handlers, you may need to
unload, then reload, handlers that you plan
to use so that free space is concatenated. Be
careful not to unload any handler being used
by a foreground or system job.

RSTSjRT -11 Operating Procedures

9-9

Message and Meaning

How to Res]pond

• Terminate and unload the foreground job or
a system job.
• If you are using the FB monitor, SET USR
SWAP (see the RT-11 System User's Guide) to
allow USR swapping.

• Create a new monitor with SYSGEN (see
the RT-11 System Generation Guide) containing
only those features that you absolutely need.
• If you have extended memory available, use
VBGEXE to run MACRO-II.

?MACRO-F-Internal error
MACRO-II detected an unexpected
condition while checking its internal tables.

This error should not occur. If you get this
error, please send an SPR to DIGITAL along
with a method of reproducing the problem.

?MACRO-F-Invalid command
The command line contains a syntax error
or specifies more than six input files.

Correct and retype the command line.

?MACRO-F-Invalid device
The device specified in the command line
is not on the system.

Install the device or substitute another.

?MACRO-F-Invalid macro library
The library file has been corrupted, or it
was not produced by the RT -11 librarian,
LIBR.

Obtain a new copy of SYSMAC. SML from
your distribution kit. If you have modified
SYSMAC.SML, carefully check the procedures
you used.

?MACRO-F-Invalid option: Ix
The specified option was not recognized
by the program.

Check for a typing error in the command line.
Use only a valid listing control or a functional
control (or CREF) option.

?MACRO-F-I/O error on <dev:filnam.typ>
A hardware error occurred during a read
from or write to the specified file.

• Be sure the device is on line and write
enabled.
• Refer to other procedures for recovery from
hard error conditions listed in the RT-11
System Message Manual.

9-10 PDP-ll MACRO-ll Language Reference Manual

Message and Meaning

How to Respond

?MACRO-F-IjO error on workfile
MACRO failed to read, write, or open its
work file WRK. TMP, possibly because of a
hard error condition.

• Be sure the device is on line and write
enabled.
• Be sure there is enough contiguous free space
on the output volume to accommodate the
workfile. If not, use the monitor's SQUEEZE
command, or delete unnecessary files.
• Refer to other procedures for recovery from
hard error conditions listed in the RT-11

System Message Manual.
?MACRO-F-.LIBRARY directive file error
1.

The file specified in the . LIBRARY
directive does not exist or is invalid.

The file specification in the . LIBRARY
directive is for a non-random-access
device.

The device specified in the command
line is not available.

The. LIBRARY stacking depth exceeds
the maximum depth allowed.

Check for a typing error in the command
line. Use file specifications that are valid
with the . LIBRARY directive.

Make sure that the file specification used
in the . LIBRARY directive is for a randomaccess device.

Enter the command line again, specifying
an available device.

Make sure that the . LIBRARY stacking
depth does not exceed the maximum
depth allowed.

?MACRO-F-Protected file already exists <dev:filnam.typ>
An attempt was made to create a file
having the same name as an existing
protected file.

Use the monitor UNPROTECT command to
change the protection level of the existing file,
or use a different name to create the new file.

?MACRO-F-Storage limit exceeded (64K)
MACRO's virtual symbol table can store
symbols and macros up to 64K words (400 8
blocks) in any combination. The program
contains more than 64K of one or both of
these elements.

Check the program logic for a condition that
leads to excessive size, such as a macro
expansion that recursively calls itself without
a terminating condition. If necessary, reduce
the requirements of the source program by
segmenting it into separate modules, and
assemble each separately.

RSTSjRT-11 Operating Procedures

9-11

Message and Meaning

How to Respond

?MACRO-F-Workfile space exceeded
The size required by MACRO-II' s virtual
symbol table has exceeded the amount of
space available in the temporary workfile.

• Increase the size of the workfile by patching
location WRKSIZ. (Refer to the file CUSTOM. TXT
on your distribution kit.) The default size of
the workfile is 200 8 blocks; it can be patched
to a maximum size of 400 8 blocks.
• Check the program logic for a condition
that leads to excessive size, such as a macro
expansion that recursively calls itself without
a terminating condition. You may also have
If
a missing . ENDM or . ENDR statement.
necessary, reduce the requirements of the
source program by segmenting it into separate
modules, and assemble each separately.

?MACRO-W-I/O error on CREF file: CREF aborted
Not enough space was available to perform
the operation, or an I/O error occurred
while the CREF work file was being
written. CREF processing is terminated,
but the assembly will continue.

• Delete unnecessary files from the output
volume, perhaps transferring them to a backup
volume.
• Use another volume with more space.
• Include the CREF workfile specification in
the MACRO-II command line, and include
the file size in square brackets as part of the
file specification.
• Consolidate free space on the volume by
using the monitor's SQUEEZE command.
• Refer to other techniques for gaining file
space in the RT-11 System Message Manual.

----------------------------------------------

9-1 2

PDP-ll MACRO-ll Language Reference Manual

Appendix A

MACRO-11 Character Sets
A.1 DEC Multinational Character Set
Empty positions are reserved for future standardizations.

Table A-1:

DEC Multinational Character Set

Left
Byte
Octal

Right
Byte
Octal

Hex

Decimal

000000
000400

000
001

00
01

001000

002

001400

Character

Remarks

0
1

NUL
SOH

STX

003

ETX

002000

004

EOT

002400
003000
003400
004000

005
006
007
010

05
06
07
08

5
6
7
8

ENQ
ACK
BEL
BS

004400
005000

011
012

09
OA

9
10

HT
LF

005400
006000

013
014

OB
OC

11
12

VT
FF

006400

015

007000

016

007400

017

010000
010400

020
021

10
11

16
17

DLE
DC1

011000

022

DC2

011400

023

DC3

Null; tape feed; CTRL/@
Start of heading; SOM, start of
message; CTRL/ A
Start of text; EOA, end of address;
CTRL/B
End of text; EOM, end of message;
CTRL/C
End of transmission (END); shuts off
TWX terminals; CTRL/D
Enquiry (ENQRY); WRU; CTRL/E
Acknowledge; RU; CTRL/F
Rings the bell; CTRL/G
Backspace; FEO, format effector;
backspaces some terminals; CTRL/H
Horizontal tab; CTRL/I
Line feed or Line space (new line);
CTRL/J
Vertical tab (VTAB); CTRL/K
Form feed to top of next page (PAGE);
CTRL/L
Carriage return to beginning of line;
CTRL/M
Shift out; changes ribbon color to red;
CTRL/N
Shift in; changes ribbon color to black;
CTRL/O
Data link escape; DCO; CTRL/P
Device control 1; turns transmitter
(READER) on; XON; CTRL/Q
Device control 2; turns punch or
auxiliary on; TAPE; AUX ON; CTRL/R
Device control 3; turns transmitter
(READER) off; XOFF; CTRL/S

MACRO-ll Character Sets A-1

Table A-1 (Cont.):

A-2

DEC Multinational Character Set

Left
Byte
Octal

Right
Byte
Octal

Hex

Decimal

Character

Remarks

012000

024

DC4

012400

025

NAK

013000
013400

026
027

16
17

22
23

SYN
ETB

014000
014400
015000
015400
016000
016400
017000
017400
020000
020400
021000
021400
022000
022400
023000
023400
024000
024400
025000
025400
026000
026400
027000
027400
030000
030400
031000
031400
032000
032400
033000
033400
034000
034400
035000
035400
036000
036400

030
031
032
033
034
035
036
037
040
041
042
043
044
045
046
047
050
051
052
053
054
055
056
057
060
061
062
063
064
065
066
067
070
071
072
073
074
075

18
19
lA
IB
lC
ID
IE
IF
20
21
22
23
24
25
26
27
28
29
2A
2B
2C
2D
2E
2F
30
31
32
33
34
35
36
37
38
39
3A
3B
3C
3D

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

CAN
EM
SUB
ESC
FS
GS
RS
US
SP

Device control 4·, turns punch or
auxiliary off; AUX OFF; CTRL/T
Negative acknowledge; ERR; ERROR;
CTRL/U
Synchronous file (SYNC); CTRL/V
End of transmission block; LEM, logical
end of medium; CTRL/W
Cancel (CANCL); CTRL/X
End of medium; CTRL/Y
Substitute; CTRL/Z
Escape; CTRL/[
File separator; CTRL/\
Group separator; CTRL/]
Record separator; CTRL/"
Unit separator; CTRL/_
Space
Exclamation mark
Double quote
Number sign
Dollar sign
Percent sign
Ampersand
Single quote; apostrophe; accent acute
Left parenthesis
Right parenthesis
Asterisk
Plus sign
COlnma
Minus sign or hyphen
Period
Slash
Number zero
Number one
Number two
Number three
Number four
Number five
Number six
N umber seven
Number eight
Number nine
Colon
Semicolon
Left angle bracket
Equal sign

PDP-l1 MACRO-ll Language Reference Manual

%
&

*
+

/
0
1
2
3
4
5
6
7
8
9

Table A-1 (Cont.):

DEC Multinational Character Set

Left
'Byte
Octal

Right
Byte
Octal

Hex

Decimal

037000
037400
040000
040400
041000
041400
042000
042400
043000
043400
044000
044400
045000
045400
046000
046400
047000
047400
050000
050400
051000
051400
052000
052400
053000
053400
054000
054400
055000
055400
056000
056400
057000

076
077
100
101
102
103
104
105
106
107
110
111
112
113
114
115
116
117
120
121
122
123
124
125
126
127
130
131
132
133
134
135
136

3E
3F
40
41
42
43
44
45
46
47
48
49
4A
4B
4C
4D
4E
4F
50
51
52
53
54
55
56
57
58
59
5A
5B
5C
5D
5E

62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

057400

137

060000
060400
061000
061400
062000
062400
063000
063400
064000

140
141
142
143
144
145
146
147
150

60
61
62
63
64
65
66
67
68

96
97
98
99
100
101
102
103
104

Character

Remarks

Right angle bracket
Question mark
At sign
Uppercase A
Uppercase B
Uppercase C
Uppercase D
Uppercase E
Uppercase F
Uppercase G
Uppercase H
Uppercase I
Uppercase J
Uppercase K
Uppercase L
Uppercase M
Uppercase N
Uppercase a
Uppercase P
Uppercase Q
Uppercase R
Uppercase S
Uppercase T
Uppercase U
Uppercase V
Uppercase W
Uppercase X
Uppercase Y
Uppercase Z
Left square bracket
Backslash
Right square bracket
Circumflex; appears as up arrow ( i ) on
some terminals
Underscore; appears as left arrow (~)
on some terminals
Accent grave
Lowercase a
Lowercase b
Lowercase c
Lowercase d
Lowercase e
Lowercase f
Lowercase g
Lowercase h

?
@
A
B
C
D
E
F
G
H
I

J
K
L
M
N

P
Q
R
S
T
U
V
W
X
y

Z
[

\
]

a
b
c
d
e
f
g
h

MACRO-ll Character Sets A-3

Table A-1 (Cont.):

A-4

DEC Multinational Character Set

Left
Byte
Octal

Right
Byte
Octal

Hex

Decimal

064400
065000
065400
066000
066400
067000
067400
070000
070400
071000
071400
072000
072400
073000
073400
074000
074400
075000
075400
076000
076400
077000
077400
100000
100400
101000
101400
102000
102400
103000
103400
104000
104400
105000
105400
106000
106400
107000
107400
110000
110400
111000
111400
112000
112400

151
152
153
154
155
156
157
160
161
162
163
164
165
166
167
170
171
172
173
174
175
176
177
200
201
202
203
204
205
206
207
210
211
212
213
214
215
216
217
220
221
222
223
224
225

69
6A
6B
6C
6D
6E
6F
70
71
72
73
74
75
76
77
78
79
7A
7B
7C
7D
7E
7F
80
81
82
83
84
85
86
87
88
89
8A
8B
8C
8D
8E
8F
90
91
92
93
94
95

105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

PDP-ll MACRO-ll Language Reference Manual

Character

j
k
I

m
n
0

q
r
s
t
u
v
w
x
Y

z
{

I
}

DEL

IND
NEL
SSA
ESA
HTS
HTJ
VTS
PLD
PLU
RI
SS2
SS3
DCS
PU1
PU2
STS
CCH
MW

Remarks

Lowercase i
Lowercase j
Lowercase k
Lowercase I
Lowercase m
Lowercase n
Lowercase 0
Lowercase p
Lowercase q
Lowercase r
Lowercase s
Lowercase t
Lowercase u
Lowercase v
Lowercase w
Lowercase x
Lowercase y
Lowercase z
Left brace
Vertical bar
Right brace
Tilde
Delete, Rubout
Reserved
Reserved
Reserved
Reserved
Index
Next line
Start selected area
End selected area
Horizontal tab set
Horizontal tab justify
Vertical tab set
Partial line down
Partial line up
Reverse index
Single shift G2
Single shift G3
Device control string
Private use 1
Private use 2
Set transmit state
Cancel character
Message waiting

Table A-1 (Cont.):

DEC Multinational Character Set

Left
Byte
Octal

Right
Byte
Octal

Hex

Decimal

Character

Remarks

113000
113400
114000
114400
115000
115400
116000
116400
117000
117400
120000
120400
121000
121400
122000
122400
123000
123400
124000
124400
125000
125400
126000
126400
127000
127400
130000
130400
131000
131400
132000
132400
133000
133400
134000
134400
135000
135400
136000
136400
137000
137400
140000
140400
141000

226
227
230
231
232
233
234
235
236
237
240
241
242
243
244
245
246
247
250
251
252
253
254
255
256
257
260
261
262
263
264
265
266
267
270
271
272
273
274
275
276
277
300
301
302

96
97
98
99
9A
9B
9C
9D
9E
9F
AO
Al
A2
A3
A4
A5
A6
A7
A8
A9
AA
AB
AC
AD
AE
AF
BO
B1
B2
B3
B4
B5
B6
B7
B8
B9
BA
BB
BC
BD
BE
BF
CO
C1
C2

150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194

SPA
EPA

Start protected area
End protected area
Reserved
Reserved
Reserved
Control sequence introduction
String terminator
Operating system command
Privacy message
Application program command
Reserved
Inverted exclamation mark
Cent sign
British pound
Reserved
Japanese yen
Reserved
Section sign
General currency
Copyright
Feminine ordinal
Double open angle bracket
Reserved
Reserved
Reserved
Reserved
Degree
PI us or min us
Superscript 2
Superscript 3
Reserved
Micro
Pilcrow
Middle dot
Reserved
Superscript 1
Masculine ordinal
Double close angle bracket
One-fourth
One-half
Reserved
Inverted question mark
Uppercase A grave
Uppercase A acute
Uppercase A circumflex

CSI
ST
OSC
PM
APC
i

a
©

.a
«

p,
~

»
%
1/z
i,

A
A
A

MACRO-ll Character Sets A-5

Table A-1 (Cont.):

A-6

DEC Multinational Character Set

Left
Byte
Octal

Right
Byte
Octal

Hex

Decimal

Character

Remarks

141400
142000
142400
143000
143400
144000
144400
145000
145400
146000
146400
147000
147400
150000
150400
151000
151400
152000
152400
153000
153400
154000
154400
155000
155400
156000
156400
157000
157400
160000
160400
161000
161400
162000
162400
163000
163400
164000
164400
165000
165400
166000
166400
167000
167400

303
304
305
306
307
310
311
312
313
314
315
316
317
320
321
322
323
324
325
326
327
330
331
332
333
334
335
336
337
340
341
342
343
344
345
346
347
350
351
352
353
354
355
356
357

C3
C4
C5
C6
C7
C8
C9
CA
CB
CC
CD
CE
CF
DO
D1
D2
D3
D4
D5
D6
D7
D8
D9
DA
DB
DC
DD
DE
DF
EO
E1
E2
E3
E4
E5
E6
E7
E8
E9
EA
EB
EC
ED
EE
EF

195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239

A
A
A

Uppercase A tilde
Uppercase A umlaut
Uppercase A ring
Uppercase AE diphthong
Uppercase C cedilla
Uppercase E grave
Uppercase E acute
Uppercase E circumflex
Uppercase E umlaut
Uppercase I grave
Uppercase I acute
Uppercase I circumflex
Uppercase I umlaut
Reserved
Uppercase N tilde
Uppercase 0 grave
Uppercase 0 acute
Uppercase 0 circumflex
Uppercase 0 tilde
Uppercase 0 umlaut
Uppercase OE ligature
Uppercase 0 slash
Uppercase U grave
Uppercase U acute
Uppercase U circumflex
Uppercase U umlaut
Uppercase Y umlaut
Reserved
German small sharp s
Lowercase a grave
Lowercase a acute
Lowercase a circumflex
Lowercase a tilde
Lowercase a umlaut
Lowercase a ring
Lowercase ae diphthong
Lowercase c cedilla
Lowercase e grave
Lowercase e acute
Lowercase e circumflex
Lowercase e umlaut
Lowercase i grave
Lowercase i acute
Lowercase i circumflex
Lowercase i umlaut

PDP-ll MACRO-ll Language Reference Manual

<;
E
E
f:

1
t
1

6
6
0

0
0
CE

0
0

0
0
Y
B

a
a

a
a
re
~

e
e
e

Table A-1 (Cont.):

DEC Multinational Character Set

Left
Byte
Octal

Right
Byte
Octal

Hex

Decimal

170000
170400
171000
171400
172000
172400
173000
173400
174000
174400
175000
175400
176000
176400
177000
177400

360
361
362
363
364
365
366
367
370
371
372
373
374
375
376
377

FO
F1
F2
F3
F4
F5
F6
F7
F8
F9
FA
FB
Fe
FD
FE
FF

240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255

Character
ft

0
6
6
0
0
re
0

U
U
U
U

Remarks

Reserved
Lowercase n tilde
Lowercase 0 grave
Lowercase 0 acute
Lowercase 0 circumflex
Lowercase 0 tilde
Lowercase 0 umlaut
Lowercase oe ligature
Lowercase 0 slash
Lowercase u grave
Lowercase u acute
Lowercase u circumflex
Lowercase u umlaut
Lowercase y umlaut
Reserved
Reserved

MACRO-ll Character Sets A-7

A.2 Radix-50 Character Set
Table A-2:

Radix-50 Character Set

Character

Octal
Equivalent

Radix-50
Equivalent

Space

040

000

A-Z

101-132

001-032

044

033

056

034
035

Unused

0-9

036-047

060-071

The maximum Radix-50 octal value is therefore:
47 * 50 2 + 47 * 50 + 47 = 174777

Table A-3 provides a convenient means of translating between the ASCII character set
and its Radix-50 equivalents. For example, given the ASCII string X2B, the Radix-50
equivalent is (arithmetic is performed in octal):
X=113000
2=002400
B=000002
X2B=115402

Table A-3:

Radix-50 Character Equivalents

Single Character or
First Character

Space
A
B
C
D

E
F
G
H
I

J
K

L
M
N

A-8

000000
003100
006200
011300
014400
017500
022600
025700
031000
034100
037200
042300
045400
050500
053600
056700
062000

Second Character

Space
A
B
C
D

E
F
G
H
I

J
K

L
M
N

000000
000050
000120
000170
000240
000310
000360
000430
000500
000550
000620
000670
000740
001010
001060
001130
001200

PDP-ll MACRO-ll Language Reference Manual

Third Character

Space
A
B
C
D

E
F
G
H
I

J
K

L
M
N

a
P

000000
000001
000002
000003
000004
000005
000006
000007
000010
000011
000012
000013
000014
000015
000016
000017
000020

Table A-3 (Cont.):

Radix-50 Character Equivalents

Single Character or
:Pirst Character

Second Character

Third Character

065100
070200
073300
S
076400
T
101500
U
104600
V
107700
W
113000
X
y
116100
121200
Z
124300
:$
127400
Unused 132500
135600
0
1
140700
2
144000
147100
.3
-4
152200
,5
155300
6
160400
7
163500
166600
8
9
171700

001250
001320
001370
T
001440
001510
U
V
001560
W
001630
X
001700
Y
001750
Z
002020
$
002070
002140
Unused 002210
002260
0
1
002330
2
002400
002450
3
4
002520
002570
5
002640
6
002710
7
002760
8
9
003030

R
S

U
V
W

X
Y
Z

$
Unused

0
1
2
3
4
5
6
7
8
9

000021
000022
000023
000024
000025
000026
000027
000030
000031
000032
000033
000034
000035
000036
000037
000040
000041
000042
000043
000044
000045
000046
000047

A.3 DEC Multinational Character Set
Figure A-I contains the DEC multinational character set; empty positions are reserved
for future standardizations.

MACRO-ll Character Sets

A-9

:t>
I

"T1

"""tJ
D
"""tJ

cE'
c:
""'II

:s;:

86 B51

BITS

B4BJB}B'~

::0

NUL I u IDLE

3
40
3i

:::l

SOHI

IDC1

4H
til
49

(XONI

'4(j

811

9
iOO

11B
80

o 0

STX I ' I DC2 I ;~

::0

Cal

ETX I 3 I DC3 I })
(XOFr=,

EOT I • I DC4 I I'

:::l

#
$

'3
J~

b
Hl

53
li4

M·l

10i
130
8:2

:s;:
Q)

ENQI: INAK

ACKI6 ISYN I ~

~!~ I

I ~::

NEL

:::l

163
A3
144
164

ETB ! ~~

BEL
Ion

01 Ii

10
8

CAN! 30

,~~16

Ai,

165

'SUB
ESC

*
1

33
11

,'7

;; I FS

',9

3'
,18

1 lC

"v
SA

SI I :~ I US

s::

'"
U'1
U'1

DO
-.J

911

{

1~1
2311

j',

I:I~

lilY

DEL

ASCII CONTROL
SET

ASCII GRAPHIC CHARACTER SET

Ll.1!J ~:~'M'"

)::(

]70

88
]71

1 168

184

I'::

.85
B9

1151

]1;

OSC
PM

'56
9C
lJS

C4
305

306
198
C6

E
E
E
O

°E

'I.
'I,

'89

'90
BE

211
191

115
AF

20'
C9

20]
313
203
C8
314
204

CC
315

158
9£

310
100
C8
311

1S5

lJI

o
6

321
1C9

360
240
FO

210

a 1m
El

32.
0

~1~

~13

316

'm o

I ~43

1244

~1'

E3
, 344

n8
E4
345

,~~

£5

346

1]30
E6

1 131

06
]15

]16

08
]17

]19

3/0

e I

U 1]49

133
E9

135
EB
354
136
EC
355
237

..
0,0

ED
356

140

F8
371
F9

u
353

335
221

OE
337

124/

1/1

]20

22]

333

00
336

311

0' 1]46

e '13]

334

FS
366

372
']50
373

314

]5]

(")

c:
;:;

:i'
I»
r+

364

350

33~

327

330

i 362
1242
Fl

E1
343

nil;:
,
o

a 1116

~11

1 36'

341

323

206

:t>
~

342

316

101

340

90
lJ6

ADD'L CONTROL
SET

197

]74
11]

173

SS31 14 3 I APC

194

303
195

134
'40

193
Cl

31]

'::~ I PLD I'~~ I CS1 I': I «
1 8e

19~

CO
301

250

;31C
I 1C8

304

181

KEY~I'~~~-------============
~ OCTAL
DEC MULTINATIONAL CHARACTER SET

ASCII CHARACTER

18~

186

libl
SS21'42
Jf
ClE
1',11

181
B5
266

il6

}

f,[)

264
180
84

?3J

"'I PLU

I'"

:~~I VTS 1 112

19'

'J,1

:30
15] I

HTS

183

HTJ I'~~

11':;

,9rl9

M
'6
7'

1\1
A6

5
~

'.'01

:;o IGS I~:
:~ IRS

")4

119

]47

EPA

"91

:,1

I 10

246

206
134

SPA I ;~

91 I

18
31

I SSAI
ESA

118

~65

133,MW

'I
13

30]

163

c:::

Po.

STS' ii3

Po.

~6]

i43

±
2

146
92

300

~61

~41

ii4

116

~60

~160

144

nO~"~~40

'~ I CCHI':

IND

IPU212n

131'

90,

PU1

c:::

I DCS

l,l()

FC
315
253
FO
316

35)~~3l)
239
"'\.I }SS
EF

DEC SUPPLEMENTAL GRAPHIC SET

-----------============::j
.,

::l
I»

(")
~

I»
I»

""'II

CJ)

Appendix B

MACRO-11 Assembly Language and Assembler
Directives
B. 1 Special Characters

Character

ITABI

I§EJ
#

@
(
)

, (comma)
+

/
&

(single quote)

<
>
\
vertical tab

Function

Label terminator
Direct assignment operator
Register term indicator
Item terminator or field ternlinator
Item terminator or field terminator
Immediate expression indicator
Deferred addressing indicator
Initial register indicator
Terminal register indicator
Operand field separator
Comment field indicator
Arithmetic addition operator or autoincrement indicator
Arithmetic subtraction operator or auto decrement indicator
Arithmetic multiplication operator
Arithmetic division operator
Logical AND operator
Logical OR operator
Double ASCII character indicator
Single ASCII character indicator or concatenation indicator
Assembly location counter
Initial argument indicator
Terminal argument indicator
Universal unary operator or argument indicator
Macro call numeric argument indicator
Source line terminator

MACRO-ll Assembly Language and Assembler Directives

B-1

8.2 Summary of Address Mode Syntax
Address Mode
Format l

Name

Number

Meaning

@R or (ER)

(ER) +

Autoincrement

The contents of the register specified as
(ER) are incremented after being used
as the address of the operand.

@(ER)+

Autoincrement Deferred

The register specified as (ER) contains
the pointer to the address of
the operand; the register (ER) is
incremented after use.

- (ER)

Autodecrement

The contents of the register specified
as (ER) are decremented before being
used as the address of the operand.

@-(ER)

Autodecrement Deferred

The contents of the register specified
as (ER) are decremented before being
used as the pointer to the address of
the operand.

E(ER)

Index

The expression E, plus the contents of
the register specified as (ER), form the
address of the operand.

@E(ER)

Index Deferred

The expression E, plus the contents of
the register specified as (ER), yield a
pointer to the address of the operand.

Immediate

The expression E is the operand itself.

Absolute

The expression E is the address of the
operand.

Relative

The address of the operand E,
relative to the instruction, follows the
instruction.

Relative Deferred

The address of the operand is pointed
to by E, whose address, relative to the
instruction, follows the instruction.

1 Symbols used in the table:
n is an integer, 0 to 7, representing a register number.
R is a register expression.
E is an expression.
ER is a register expression or an expression whose value is in the range 0 to 7.

8-2

PDP-ll MACRO-ll Language Reference Manual

B.3 Assembler Directives
The MACRO-ll assembler directives are summarized in the following table. For a
detailed description of each directive, refer to the appropriate sections in the body of
the manual.
Reference

Operation

6.3.3
7.3.7

Followed by one ASCII character, a single quote
(apostrophe) generates a word which contains
the 7-bit ASCII representation of the character
in the low-order byte and zero in the high-order
byte. Single quote is also used as a concatenation
indicator in the expansion of macro arguments.

6.3.3

Followed by two ASCII characters, a double
quote generates a word which contains the 7bit ASCII representation of the two characters.
The first character is stored in the low-order byte;
the second character is stored in the high -order
byte.

ABn

6.4.1.2

A temporary radix control, causes the value n to
be treated as a binary number.

ACexpr

6.4.2.1

A temporary numeric control, causes the
expression's value to be one's complemented.

ADn

6.4.1.2

A temporary radix control, causes the value n to
be treated as a decimal number.

AFn

6.4.2.3

A temporary numeric control, causes the value n
to be treated as a 16-bit floating-point number.

AO n

6.4.1.2

A temporary radix control, causes the value n to
be treated as an octal number.

ARccc

6.3.7

Converts ccc to Radix-50 form.

AXn

6.4.1.2

A temporary radix control, causes the value n to
be treated as a hexadecimal number. The value
n must begin with a digit, which may be O.

.ASCII /string/

6.3.4

Generates a block of data containing the ASCII
equivalent of the character string (enclosed in
delimiting characters), one character per byte.

.ASCIZ /string/

6.3.5

Generates a block of data containing the ASCII
equivalent of the character string (enclosed in
delimiting characters), one character per byte,
with a zero byte terminating the specified string.

. ASECT

6.7.2

Begins or resumes the absolute program section.

.BLKB exp

6.5.3

Reserves a block of storage space whose length in
bytes is determined by the specified expression.

Form

MACRO-ll Assembly Language and Assembler Directives

8-3

8-4

Form

Reference

Operation

.BLKW exp

6.5.3

Reserves a block of storage space whose length in
words is determined by the specified expression.

.BYTE expl.exp2 ....

6.3.1

Generates successive bytes of data; each byte
contains the value of the corresponding specified
expression.

.CROSS syml.sym2 ....

6.2.2

Enables the cross-reference listing for the
specified synlbol list. If a symbol list is not
specified, this directive reenables the crossreference listing for all symbols in the program .

. CSECT [name]

6.7.2

Begins or resumes named or unnamed
relocatable program section. This directive is
provided for compatibility with other PDP-II
assemblers.

.DSABL arg

6.2.1

Disables the function specified by the argument.

.ENABL arg

6.2.1

Enables the function specified by the argument.

. END [exp]

6.6

Indicates the logical end of the source program .
The optional argument specifies the transfer
address where program execution is to begin.

.ENDC

6.9.1

Indicates the end of a conditional assembly block.

. ENDM [name]

7.1.2

Indicates the end of the current repeat block,
indefinite repeat block, or macro definition. The
optional name, if used, must be identical to the
name specified in the macro definition.

.ENDR

7.7

Indicates the end of the current repeat block.
This directive is provided for compatibility with
other PDP-II assemblers.

.ERROR exp;text

7.5

A user-called error directive, causes output to
the listing file or the command output device
containing the optional expression and the
statement containing the directive.

. EVEN

6.5.1

Ensures that the current location counter contains
an even address by adding 1 if it is odd.

.FLT2 argl.arg2 ....

6.4.2.2

Generates successive 2-word floating-point
equivalents for the floating-point numbers
specified as arguments.

.FLT4 argl.arg2 ....

6.4.2.2

Generates successive 4-word floating-point
equivalents for the floating-point numbers
specified as arguments.

.GLOBL syml.sym2 ....

6.8.1

Defines the listed symbol(s) as global symbol(s).

PDP-ll MACRO-ll Language Reference Manual

Form

Reference

Operation

.IDENT /string/

6.1.4

Provides a means of labeling the object module
with the program version number. The version
number is the Radix-50 string appearing between
the paired delimiting characters.

.IF cond,argl,arg2, ...

6.9.1

Begins a conditional assembly block of source
code, which is included in the assembly only if
the stated condition is met with respect to the
specified argument(s).

.IFF

6.9.2

Appears only within a conditional assembly
block, indicating the beginning of a section of
code to be assembled if the condition upon
entering the block tests false.

.IFT

6.9.2

Appears only within a conditional assembly
block, indicating the beginning of a section of
code to be assembled if the condition upon
entering the block tests true.

.IFTF

6.9.2

Appears only within a conditional assembly
block, indicating the beginning of a section of
code to be assembled unconditionally.

.IIF cond,arg, statement 6.9.3

Acts as a I-line conditional assembly block where
the condition is tested for the specified argument.
The statement is assembled only if the condition
tests true.

. INCLUDE filespec

6.10.2

Inserts a specified source file within the source
file currently being used.

.IRP sym, <argl ,arg2 .... > 7.6.1

Indicates the beginning of an indefinite repeat
block in which the specified symbol is replaced
with successive elements of the real argument
list enclosed within angle brackets.

.IRPC sym,<string>

7.6.2

Indicates the beginning of an indefinite repeat
block in which the specified symbol takes on
the value of successive characters, optionally
enclosed within angle brackets.

.LIBRARY filespec

6.10.1

Adds a specified file name to a macro library list
that is searched.

.LIMIT

6.5.4

Reserves two words into which the Linker or
Task Builder inserts the low and high addresses
of the task image.

MACRO-ll Assembly Language and Assembler Directives

8-5

8-6

Form

Reference

Operation

· LIST [arg]

6.1.1

Without an argument, the . LIST directive
increments the listing level count by 1. With
an argument, this directive does not alter the
listing level count, but formats the assembly
listing according to the specified argument.

· MACRO name, arg1 , arg2, ... 7.1.1

Indicates the start of a macro definition having
the specified name and the following dummy
arguments.

· MCALL arg1, arg2, . . .

7.8

Specifies the symbolic names of the user
or system ITtacro definitions required in the
assembly of the current user program, but which
are not defined within the program.

· MDELETE name1, name2, . .. 7.9

Deletes the definitions of the specified macro(s),
freeing virtual memory.

.MEXIT

7.1.3

Causes an exit from the current macro expansion
or indefinite repeat block.

.NARG symbol

7.4.1

Appearing only within a macro definition,
equates the specified symbol to the number
of arguments in the macro call currently being
expanded.

.NCHR symbol,<string>

7.4.2

Appearing anywhere in a source program,
equates the specified symbol to the number of
characters in the specified string.

.NLIST [arg]

6.1.1

Without an argument, decrements the listing
level count by 1.
With an argument, this
directive suppresses that portion of the listing
specified by the argument.

.NOCROSS sym1,sym2, ...

6.2.2

Disables the cross-reference listing for the listed
symbols. If a symbol list is not specified, this
directive disables the cross-reference listing for
all symbols in the program.

.NTYPE symbol,aexp

7.4.3

Appearing only within a macro definition,
equates the symbol to the 6-bit addressing mode
of the specified address expression.

.ODD

6.5.2

Ensures that the current location counter contains
an odd address by adding 1 if it is even.

. PACKED

6.3.8

Causes a decimal number of 3110 digits or less
to be packed two digits per byte.

. PAGE

6.1.5

Causes the assembly listing to skip to the top of
the next page and to increment the page count.

PDP-ll MACRO-ll Language Reference Manual

Form

Reference

Operation

.PRINT exp;text

7.5

User-called message directive; causes output
to the listing file or the command output
device containing the optional expression and
the statement containing the directive.

.PSECT name,att1, ...

6.7.1

Begins or resumes a named or attn unnamed
program section having the specified attributes .

. RAD50 !string!

6.3.6

Generates a block of data containing the Radix50 equivalent of the character string enclosed
within delimiting characters.

.RADIX n

6.4.1.1

Alters the current program radix to n, where n is
2, 8, 10, or 16.

.REM comment-character

6.1.6

Allows a programmer to insert a block of
comments into a MACRO-II source program
without having to precede the comment lines
with the comment character (;).

.REPT exp

7.7

Begins a repeat block; causes the section of code
up to the next . ENDM or . EN DR directive to be
repeated the number of times specified as expo

. RESTORE

6.7.4

Retrieves a previously . SAVEd program section
context from the top of the program section
context stack leaving the current program section
in effect.

. SAVE

6.7.3

Stores the current program section context on the
top of the program section context stack leaving
the current program section in effect.

.SBTTL string

6.1.3

Causes the specified string to be printed as part
of the assembly listing page header. The string
component of each . SBTTL directive is collected
into a table of contents at the beginning of the
assembly listing.

.TITLE string

6.1.2

Assigns the first six Radix-50 characters in the
string as an object module name and causes the
string to appear on each page of the assembly
listing.

.WEAK sym1,sym2, ...

6.8.2

Specifies symbols that are defined either
externally in another module or globally in the
current module.

.WORD exp1,exp2, ...

6.3.2

Generates successive words of data; each word
contains the value of the corresponding specified
expression.

MACRO-l1 Assembly Language and Assembler Directives

8-7

Appendix C

Permanent Symbol Table
The mnemonics for the PDP-ll operation (op) codes and MACRO-ll assembler
directives are stored in the Permanent Symbol Table. The Permanent Symbol Table
contains the symbols that are automatically recognized by MACRO-ll.
For a detailed description of the op codes, see the PDP-II Processor Handbook.

C.1 Op Codes

Instruction
Mnemonic

Octal
Value

Operation

ADC

005500

Add Carry

ADCB

105500

Add Carry (Byte)

ADD

060000

Add Source To Destination

ASH

072000

Shift Arithmetically

ASHC

073000

Arithmetic Shift Combined

ASL

006300

Arithnletic Shift Left

ASLB

106300

Arithnletic Shift Left (Byte)

ASR

006200

Arithmetic Shift Right

ASRB

106200

Arithmetic Shift Right (Byte)

BCC

103000

Branch If Carry Is Clear

BCS

103400

Branch If Carry Is Set

BEQ

001400

Branch If Equal

BGE

002000

Branch If Greater Than Or Equal

BGT

003000

Branch If Greater Than

BHI

101000

Branch If Higher

BHIS

103000

Branch If Higher Or Same

BIC

040000

Bit Clear

BICB

140000

Bit Clear (Byte)

BIS

050000

Bit Set:

BISB

150000

Bit Set: (Byte)

Permanent Symbol Table

C-1

C-2

Instruction
Mnemonic

Octal
Value

Operation

BIT

030000

Bit Test

BITB

130000

Bit Test (Byte)

BLE

003400

Branch If Less Than Or Equal

BLO

103400

Branch If Lower

BLOS

101400

Branch If Lower Or Same

BLT

002400

Branch If Less Than

BMI

100400

Branch If Minus

BNE

001000

Branch If Not Equal

BPL

100000

Branch If Plus

BPT

000003

Breakpoint Trap

000400

Branch Unconditional

BVC

102000

Branch If Overflow Is Clear

BVS

102400

Branch If Overflow Is Set

CALL

004700

Jump To Subroutine (JSR PC,xxx)

CALLR

000100

Jump (JMP addr)

CCC

000257

Clear All Condition Codes

CLC

000241

Clear C Condition Code Bit

CLN

000250

Clear N Condition Code Bit

CLR

005000

Clear Destination

CLRB

105000

Clear Destination (Byte)

CLV

000242

Clear V Condition Code Bit

CLZ

000244

Clear Z Condition Code Bit

CMP

020000

Compare Source To Destination

CMPB

120000

Compare Source To Destination (Byte)

COM

005100

Complement Destination

COMB

105100

Complement Destination (Byte)

DEC

005300

Decrement Destination

DECB

105300

Decrement Destination (Byte)

DIV

071000

Divide

EMT

104000

Emulator Trap

FADD

075000

Floating Add

PDP-ll MACRO-ll Language Reference Manual

Instruction
Mnemonic

Octal
Value

Operation

FDIV

075030

Floating Divide

FMUL

075020

Floating Multiply

FSUB

075010

Floating Subtract

HALT

000000

Halt

INC

005200

Increment Destination

INCB

105200

Increment Destination (Byte)

lOT

000004

Input/Output Trap

JMP

000100

Jump

JSR

004000

Jump To Subroutine

MARK

006400

Mark

MED6X

076600

PDP-11/60 Maintenance

MFPI

006500

Move From Previous Instruction Space

MFPS

106700

Move From PS (LSI-II, LSI-11/23, LSI-11/2)

MFPT

000007

Move From Processor Type

MOV

010000

.Move Source To Destination

MOVB

110000

Move Source To Destination (Byte)

MTPI

006600

Move To Previous Instruction Space

MTPS

106400

Move To PS (LSI-II, LSI-11/23, LSI-l1/2)

MUL

070000

Multiply

NEG

005400

Negate Destination

NEGB

105400

Negate Destination (Byte)

Nap

000240

No Operation

RESET

000005

Reset External Bus

RETURN

000207

Return From Subroutine (RTS PC)

ROL

006100

Rotate Left

ROLB

106100

Rotate Left (Byte)

ROR

006000

Rotate Right

RORB

106000

Rotate Right (Byte)

RTI

000002

Return From Interrupt (permits trace trap)

RTS

000200

Return From Subroutine

RTT

000006

Return From Interrupt (inhibits trace trap)

Permanent Symbol Table

C-3

Instruction
Mnemonic

Octal
Value

Operation

SBC

005600

Subtract Carry

SBCB

105600

Subtract Carry (Byte)

SCC

000277

Set All Condition Code Bits

SEC

000261

Set C Condition Code Bit

SEN

000270

Set N Condition Code Bit

SEV

000262

Set V Condition Code Bit

SEZ

000264

Set Z Condition Code Bit

SOB

077000

Subtract One And Branch

SUB

160000

Subtract Source FroITl Destination

SWAB

000300

Swap Bytes

SXT

006700

Sign Extend

TRAP

104400

Trap

TST

005700

Test Destination

TSTB

105700

Test Destination (Byte)

TSTSET

007200

Test Destination And Set Low Bit

WAIT

000001

Wait For Interrupt

WRTLCK

007300

Read/Lock Destination. Write/Unlock RO Into Destination

XOR

074000

Exclusive OR

C-4 PDP-ll MACRO-l1 Language Reference Manual

C.2 Commercial Instruction Set (CIS) Op Codes
Every operation listed in the CIS table has two instruction mnemonics. The suffix
I, attached to every second mnemonic, indicates that the addresses are inline. CIS
instructions take no arguments.
Instruction
Mnemonic

Octal
Value

Operation

ADDN

076050

Add Numeric

ADDNI

076150

Add Numeric

ADDP

076070

Add Packed

ADDPI

076170

Add Packed

ASHN

076056

Arithmetic Shift Numeric

ASHNI

076156

Arithmetic Shift Numeric

ASHP

076076

Arithmetic Shift Packed

ASHPI

076176

Arithmetic Shift Packed

CMPC

076044

Compare Character String

CMPCI

076144

Compare Character String

CMPN

076052

Compare Numeric

CMPNI

076152

Compare Numeric

CMPP

076072

Compare Packed

CMPPI

076172

Compare Packed

CVTLN

076057

Convert Long To Numeric

CVTLNI

076157

Convert Long To Numeric

CVTLP

076077

Convert Long To Packed

CVTLPI

076177

Convert Long To Packed

CVTNP

076055

Convert Numeric To Packed

CVTNPI

076155

Convert Numeric To Packed

CVTPN

076054

Convert Packed To Numeric

CVTPNI

076154

Convert Packed To Numeric

DIVP

076075

Divide Decimal

DIVPI

076175

Divide Decimal

LOCC

076040

Locate Character

LOCCI

076140

Locate Character

07602n

Load 2 Descriptors @(Rn)+

L2Dn

In-Oto7.

Permanent Symbol Table

C-5

Instruction
Mnemonic

Octal
Value

Operation

07606n

Load 3 Descriptors @(Rn)+

MATC

076045

Match Character

MATCI

076145

Match Character

MOVC

076030

Move Character

MOVCI

076130

Move Character

MOVRC

076031

Move Reverse Justified Character

MOVRCI

076131

Move Reverse Justified Character

MOVTC

076032

Move Translated Character

MOVTCI

076132

Move Translated Character

MULP

076074

Multiply Decimal

MULPI

076174

Multiply Decimal

SCANC

076042

Scan Character

SCANCI

076142

Scan Character

SKPC

076041

Skip Character

SKPCI

076141

Skip Character

SPANC

076043

Span Character

SPANCI

076143

Span Character

SUBN

076051

Subtract Numeric

SUBNI

076151

Subtract Numeric

SUBP

076071

Subtract Packed

SUBPI

076171

Subtract Packed

L3Dn

In = 0 to 7.

C-6 PDP-ll MACRO-ll Language Reference Manual

C . 3 Floating-Point Processor Op Codes

Instruction
Mnemonic

Octal
Value

Operation

ABSD

170600

Make Absolute Double

ABSF

170600

Make Absolute Floating

ADDD

172000

Add Double

ADDF

172000

Add Floating

CFCC

170000

Copy Floating Condition Codes

CLRD

170400

Clear Double

CLRF

170400

Clear Floating

CMPD

173400

Compare Double

CMPF

173400

Compare Floating

DIVD

174400

Divide Double

DIVF

174400

Divide Floating

LDCDF

177400

Load And Convert From Double To Floating

LDCFD

177400

Load And Convert From Floating To Double

LDCID

177000

Load And Convert Integer To Double

LDCIF

177000

Load And Convert Integer To Floating

LDCLD

177000

Load And Convert Long Integer To Double

LDCLF

177000

Load And Convert Long Integer To Floating

LDD

172400

Load Double

LDEXP

176400

Load Exponent

LDF

172400

Load Floating

LDFPS

170100

Load FPPs Program Status

MFPD

106500

Move From Previous Data Space

MODD

171400

Multiply And Integerize Double

MODF

171400

Multiply And Integerize Floating

MTPD

106600

Move 'To Previous Data Space

MULD

171000

Multiply Double

MULF

171000

Multiply Floating

NEGD

170700

Negate Double

NEGF

170700

Negate Floating

Permanent Symbol Table

C-7

C-8

Instruction
Mnemonic

Octal
Value

Operation

SETD

170011

Set Double Mode

SETF

170001

Set Floating Mode

SETI

170002

Set Integer Mode

SETL

170012

Set Long Integer Mode

SPL

000230

Set Priority Level

STAO

170005

Diagnostic Floating Point

STBO

170006

Diagnostic Floating Point

STCDF

176000

Store And Convert From Double To Floating

STCDI

175400

Store And Convert From Double To Integer

STCDL

175400

Store And Convert From Double To Long Integer

STCFD

176000

Store And Convert From Floating To Double

STCFI

175400

Store And Convert From Floating To Integer

STCFL

175400

Store And Convert From Floating To Long Integer

STD

174000

Store Double

STEXP

175000

Store Exponent

STF

174000

Store Floating

STFPS

170200

Store FPPs Program Status

5TST

170300

Store FPPs Status

SUBD

173000

Subtract Double

SUBF

173000

Subtract Floating

TSTD

170500

Test Double

TSTF

170500

Test Floating

PDP-ll MACRO-ll Language Reference Manual

C.4 MACRO-11 Directives
The MACRO-II directives that follow are described in greater detail in Appendix B.
Directive

Function

. ASCII

Translates character string to ASCII equivalents .

.ASCIZ

Translates character string to ASCII equivalents; inserts zero byte as last
character.

. ASECT

Begins absolute program section (provided for compatibility with other PDP-II
assemblers).

.BLKB

Reserves byte block in accordance with value of specified argument.

.BLKW

Reserves word block in accordance with value of specified argument.

. BYTE

Generates successive byte data in accordance with specified arguments .

. CROSS

Enables cross-reference listing for specified symbols; enables cross-reference for
all symbols.

.CSECT

Begins relocatable program section (provided for compatibility with other PDP11 assemblers).

. DSABL

Disables specified function .

. ENABL

Enables specified function .

. END

Defines logical end of source program .

. ENDC

Defines end of conditional assembly block .

.ENDM

Defines end of macro definition, repeat block, or indefinite repeat block.

.ENDR

Defines end of current repeat block (provided for compatibility with other
PDP-II assemblers).

. ERROR

Outputs diagnostic message to listing file or command output device .

. EVEN

Word aligns the current location counter .

.FLT2

Generates two words of storage for each floating-point argument.

.FLT4

Generates four words of storage for each floating-point argument.

. GLOBL

Declares global attribute for specified symbol(s) .

. IDENT

Labels object module with specified program version number .

. IF

Begins conditional assembly block .

.IFF

Begins subconditional assernbly block (if conditional assembly block test is
false).

. IFT

Begins subconditional assembly block (if conditional assembly block test is true) .

.IFTF

Begins subconditional assembly block (whether conditional assembly block test
is true or false).

Permanent Symbol Table

C-9

C-10

Directive

Function

.IIF

Assembles immediate conditional assembly statement (if specified condition is
satisfied).

. INCLUDE

Inserts specified source file within source file currently being used .

.IRP

Begins indefinite repeat block;
successive real arguments.

.IRPC

Begins indefinite repeat block; replaces specified symbol with value of successive
characters in specified string.

. LIBRARY

Adds a specified file name to a macro library list that is searched .

. LIMIT

Reserves two words of storage for high and low addresses of task image .

. LIST

Controls listing level count and format of assembly listing .

. MACRO

Denotes start of macro definition .

. MCALL

Identifies required macro definition(s) for assembly .

. MDELETE

Deletes the definitions of the specified macro(s) .

.MEXIT

Exits from current macro definition or indefinite repeat block.

.NARG

Equates specified symbol to the number of nonkeyword arguments in the macro
expansion.

. NCHR

Equates specified symbol to the number of characters in the specified character
string.

.NLIST

Controls listing level count and suppresses specified portions of the assembly
listing.

. NOCROSS

Disables cross-reference listing for specified symbols; disables cross-reference
listing for all symbols.

.NTYPE

Equates specified symbols to the addressing mode of the specified argument.

. 000

Byte aligns the current location counter .

. PACKED

Generates packed decimal data, two digits per byte .

. PAGE

Advances form to top of next page .

. PRINT

Prints specified message on command output device .

. PSECT

Begins specified program section having specified attributes .

. RAD50

Generates data block having Radix-50 equivalents of specified character string .

. RADIX

Changes current program radix to specified radix .

. REM

Inserts a block of comments into a MACRO--Il source program without having
to precede comment lines with the comment character (;).

.REPT

Begins repeat block and replicates it according to the value of the specified
expression.

PDP-l1 MACRO-l1 Language Reference Manual

replaces specified symbol with specified

Directive

Function

. RESTORE

Stores the current program section context on the top of the program section
context stack.

. SAVE

Retrieves the program section from the top of the program section context stack.

.SBTTL

Prints specified subtitle text as the second line of the assembly listing page
header.

. TITLE

Prints specified title text as object module name in the first line of the assembly
listing page header.

. WEAK

Specifies symbols that are either defined externally in another module or are
defined globally in the current module.

. WORD

Generates successive word data in accordance with specified arguments .

Permanent Symbol Table

C-11

Appendix D

Error Messages
An error code is printed as the first character in a source line containing an error. This
error code identifies the error condition detected during the processing of the line. For
example:
Q

26 000236 010102 MOV

R1,R2,A

The extraneous argument A in the MOV instruction above causes the line to be flagged
with a Q (syntax) error.
Error
Code
A

Meaning

Assembly error. Because many different conditions produce this error message,
the directives which may yield a general assembly error have been categorized
below to reflect these error conditions:

CATEGORY 1: INVALID ARGUMENT SPECIFIED
.ENABL/.DSABL
Table 6-3 contains a list of the valid arguments
for this directive.

.IF/.IIF

An invalid conditional test (see Table 6-6),
an invalid argument expression value, or no
conditional argument is specified in the directive.

. IRP/.IRPC

No dummy argument is specified in the directive .

.LIST/.NLIST

Table 6-2 contains a list of the valid arguments
for this directive.

. MACRO

There is an invalid or duplicate symbol in the
dummy argument list.

. NARG/.NCHR
.NTYPE

No symbol is specified in the directive .

.PSECT

Other than a valid argument (see Table 6-4)
is specified with the directive, or the attribute
arguments of a previously declared program
section change (see Section 6.7.1.1).

. RADIX

A value other than 2, 8, 10, or 16 is specified as
a new radix.

. TITLE

Program name is not specified in the directive, or
first non-blank character following the directive is
a non-Radix-50 character.

Error Messages

0-1

Error
Code

Meaning

CATEGORY 2:
UNMA TCHED DELIMITER/INV ALID ARGUMENT
CONSTRUCTION
.ASCII/.ASCIZ
Character string or argument string delimiters do
.RAD50/.IDENT
not match, or an invalid character is used as a
delimiter, or an invalid argument construction is
used in the directive.
. NCHR

Character string delimiters do not match, or an
invalid character is used as a delimiter in the
directive.

CATEGORY 3: GENERAL ADDRESSING ERRORS
This type of error results from one of several possible conditions:
•

Permissible range of a branch instruction (from -128 10 to +12710 words)
has been exceeded.

•

A statement makes invalid use of the current location counter. For example,
a . =expression statement attempts to force the current location counter to
cross program section (. PSECT) boundaries.

•

A statement contains an invalid address expression:

In cases where an absolute address expression is required, specifying a
global symbol, a relocatable value, or a complex relocatable value (see
Section 3.9) results in an invalid address expression. For example, this
error occurs with . BLKB/ . BLKW/ . REPT if other than an absolute value or
an expression which reduces to an absolute value is specified with the
directive.
If an undefined symbol is made a default global reference by the . ENABL GBL
directive (see Section 6.2.1) during pass I, any attempt to redefine the sym-

bol during pass 2 will result in an invalid address expression.
In cases where a relocatable address expression is required, either a relocatable or absolute value is permissible, but a global symbol or a complex
relocatable value in the statement results in an invalid address expression.
•

Multiple expressions are not separated by a comma. This condition causes
the next symbol to be evaluated as part of the current expression.

•

. SAVE-The stack is full when the . SAVE directive is issued.

•

. RESTORE-The stack is empty when the . RESTORE directive is issued.

0-2 PDP-ll MACRO-ll Language Reference Manual

Error

Code

Meaning

CATEGORY 4: INVALID FORWARD REFERENCE

This type of error results from either of two possible conditions:

•

A global assignment statement (symbol= =expression or symbol= =: expression)
contains a forward reference to another symbol.

•

An expression defining the value of the current location counter contains a
forward reference.

Bounding error. Instructions or word data are being assembled at an odd
address. The location counter is incremented by 1.
Insert a . EVEN statement before the statement that generates the error.

Doubly-defined symbol referenced. Reference was made to a symbol which is
defined more than once.
Remove one of the definitions or rename one of the symbols to something else.

End directive not found. When the end-of-file is reached during source input
and the . END directive has not yet been encountered, MACRO-II generates
this error code, ends assembly pass -1, and proceeds with assembly pass 2.
Put: a . END directive at the end of the program.
This error is also caused by assembler stack overflow. In this case MACRO11 places a question mark (?) into the line at the point where the overflow
occurred.
Invalid character detected. Invalid characters which are also nonprinting are
replaced by a question mark (?) on the listing. The character is then ignored.
Delete the characters, or replace them with characters in the valid MACRO-II
character set.

Input line is greater than 132 10 characters. This error condition is caused only
during macro expansion when longer real arguments, replacing the dummy
arguments, cause a line to exceed 132 10 characters.
Rewrite the macro so this does not occur.

Multiple definition of a label. A label was encountered which was equivalent
(in the first six characters) to a previously encountered label.
Rename one of the labels to something else.

A number contains a digit that is not in the current program radix. The number
is evaluated as a decimal value.
Change the erroneous digit so the number is valid in the current program radix,
or redefine the current radix with the . RADIX directive or one of the temporary
radix operators.

Error Messages

0-3

Error

Code

Meaning

Op code error. Directive out of context. Permissible nesting level dep.th for
conditional assemblies has been exceeded. Attempt to expand a macro which
was unidentified after a . MCALL search.
Check syntax and context. Make sure conditional nesting does not exceed 16
levels.

Phase error. A label's definition of value varies from one assembly pass to
another, or a multiple definition of a local symbol has occurred within a local
symbol block. This situation may occur if you define a local symbol block using
the . ENABL LSB directive, then attempt to define a local symbol in a program
section other than that which was in effect when the block was entered. An
error code P also appears if a . ERROR directive is assembled. You may also be
using the conditional tests . IF P1 and . IF P2 incorrectly.
Check and correct program logic.

Questionable syntax. Arguments are missing, too many arguments are specified,
or the instruction scan was not completed.
Verify that instruction syntax is correct. Also, be sure the program does not
contain a carriage return with no line feed or a colon instead of a semicolon at
the beginning of a comment.

Register error. An invalid use of or reference to a register has been made, or
an attempt has been made to redefine a standard register symbol without first
issuing the . DSABL REG directive.

Truncation error. A number generated more than 16 bits in a word. You may
get this error if you specify an octal or decimal value but the radix is set to
hexadecimal or if you specify an octal value but the radix is set to decimal.

Undefined symbol.
An undefined symbol was encountered during the
evaluation of an expression; such an undefined symbol is assigned a value
of zero. Other possible conditions which result in this error code include
unsatisfied macro names in the list of . MCALL arguments and a direct assignment
(symbol=expression or symbol=: expression) statement which contains a
forward reference to a symbol whose definition also contains a forward
reference; also, a local symbol may have been referenced that does not exist in
the current local symbol block.

Instruction error. The instruction so flagged is not compatible among all
members of the PDP-II family. See Section 5.3 for details.

---------------------------

0-4

PDP-ll MACRO-ll Language Reference Manual

Appendix E

Sample Coding Standard
Local user requirements must be met in a coding standard, b~t following this model
as closely as possible helps you and DIGITAL by simplifying communication and
software maintenance. Remember that this is a sample and may not entirely apply to
your system.

E.1 Line Format
Source lines are from 1 to 80 characters in the following format:
1.

Label Field--If present, begins in column 1. This field should be coded in uppercase
only.

Operation field-Begins in column 9 (tab stop 1). This field should be coded in
uppercase only.

Operand field-Begins in column 17 (tab stop 2). This field should be coded in
uppercase only.

Comment field-Begins in column 33 (tab stop 4). If the operand field extends
beyond column 33 (tab stop 4), leave a space and start the comment. This field
should be coded in uppercase and lowercase to increase readability.

E.2 Comments
To make the program easier to understand, use comments to explain the logic behind
the instructions. In general, you should use a comment per line of code. However, if
a particularly difficult or obscure section of code is used, precede that section with a
longer explanation.
Comments that are too long for the comment field can be continued on the following
line. Begin the new line with a semicolon, space over to the column the comment
began in, and continue writing. All comments should be written in uppercase and
lowercase to increase readability.
If a lengthy text is needed for an explanation, begin the comment with a line containing
only the characters ; + and end it with a line containing only the characters ; -. The
lines between these delimiters should each begin with a semicolon and a space. For
example:
;+

The invert routine accepts
a list of random numbers and
; applies the Kolmogorov Algorithm
; to alphabetize them.

Sample Coding Standard

E-1

E.3 Naming Standards
E.3.1 Registers
For the general purpose registers, use the default names:
RO=%O
Ri=%i
R2=%2
R3=%3
R4=%4
R5=%5
SP=%6
PC=%7

;REG 0
;REG 1
;REG 2
;REG 3
;REG 4
;REG 5
;Stack painter (REG 6)
;Program counter (REG 7)

For hardware registers, use the hardware definition. Examples are PS (Program Status
Register) and SWR (Switch Register).
For device registers, use the hardware notation. For example, the control status register
for the RK disk is RKCS.

E.3.2 Processor Priority
Test or alter the processor priority by using the symbols:
PRO, PRi, PR2,

PR7

which should be equated to their corresponding priority bit pattern.

E.3.3 Symbols
The following chart diagrams the syntax of the five major types of symbol names 1
symbol

pos-l

pos-2

pos-3

pos-4

pos-S

pos-6

length

nonglobal
symbol

letter

a-num/
null

> =1

global
symbol

$/.

a-num/
null

> =1

global
offset

letter

$j.

a-num

a-num/ '
null

a-num/
null

> =3

global bit
pattern

letter

a-num

$j.

a-num

a-num/
null

> =4

local
symbol

number

NOTES:

letter

is A-Z.

a-num

is an alphanumeric character.

1 Symbols that are branch targets are also called labels, but in this appendix the term symbol includes labels.

E-2

PDP-ll MACRO-ll Language Reference Manual

> =2

pos-l

symbol

pos-2

pos-3

pos-4

pos-5

pos-6

length

null

is the absence of a character in the position.

$ /.

are reserved for DIGITAL-supplied software; do not use $ or . in your global
symbols to avoid possible conflict with globals, for example, in distributed
libraries.

number

is in the range 0 to 65535 10 ,

E.3.3.1 Syrnbol Examples

Nonglobal Symbols:
AlB
ZXCJl
INSRT

Global Address Symbols:
$JIM
.VECTR
$SEC

Global Absolute Offset Symbols:
A$JIM
A$XT
A.ENT

Global Bit Pattern Symbols:
Al$20
B3.6

JI.M

Local Symbols:
37$
271$
6$

E.3.3.2 Local Symbols

When defining target symbols for branches that exist solely for positional reference,
use local symbols of the form:
<number>$:

Define local synlbols so the numbers proceed sequentially down the page and from
page to page.

Sample Coding Standard

E-3

E.3.3.3 Global Symbols

Restrict your use of global symbols, within reason, to those cases where reference to
the code occurs external to the code.
Never put a . GLOBL statement in a program without showing cause.
E.3.3.4 Macro Names (RSX-11)

In a macro name, the last two characters (last character possibly being null) have
special significance: the next to last character is a $, the last character specifies the
mode of the macro.
For example, in the three RSX-II macro forms inline, stack, and p-section, the inline
form has no suffix, the stack has an S suffix, and the p-section a c. Thus the RSX-II
Queue I/O macro can be written as any of:
QIO$
QIO$S
QIO$C

depending on the form required. These are not reserved letters.
E.3.3.5 General Symbols

Make frequently used bit patterns such as carriage return and line feed conventional
symbols as they are needed, for example:
CR =
LF

015
012

E.4 Program Modules
There are no assembler limits on program size. However, since the virtual memory
capacity of a computer is finite, keep programs as compact as possible by:
•

Creating them for a single function

•

Writing them in accordance with the memory allocation guidelines in Appendix F

Code areas are different from data areas. Code is read-only, but data can be read-only
or read-write; read-only data should be segregated from read-write data. Both areas,
code and data, should have explanatory comments.

E.4.1 The Module Preface
Put each program module in a separate file. For easy reference, the file name should
be similar to the name of the module. The availability of File Control Services and
File Control Primitives simplify version number maintenance.

E.4.2 The Module
Below is a list of the information that is included in the example MACRO-II module
(see Section E.4.3). The information is formatted as foHows. The first six items appear
on the same page and do not have explicit headings.

E-4

PDP-ll MACRO-ll Language Reference Manual

A .NLIST statement, followed by any .ENABL/ . DSABL or .NLIST/ .LIST options that are
relevant to the assembly of this module, followed by a matching . LIST statement.
The . NLIST statement has a comment appended to it specifying the module edit
level.

A . TITLE statement that specifies the name of the module. If a module contains
more than one routine, . SBTTL statements are used.

3. Several. SBTTL statements giving the name, general function, and version number
of the module. The . SBTTL directive inserts this information in the table of contents
for quick reference.
4. A . IDENT statement that specifies the version number of the module (see
Section E.8).
5. A copyright statement, and a disclaimer, followed by a form feed. The copyright,
even though a comment, should be all uppercase. This ensures that the copyright
will be presented correctly, even on a terminal that has only uppercase.
6. The name of the program or software package that the module is a part of.
7. The name of the author.
8.

The date of module creation.

9. A 1- or 2-line abstract of the function(s) of the module.
10. A description of all external references made by the module, one per line, in

alpha betical order.
11. A chronological edit trail of modifications to the module that includes the

following:
•

Edit number

•

Editor1s identification

•

Edit date

•

Description of the modification made

NOTE
Items 7 through 11 should appear on the same page.
12. Any references to external files by the. LIBRARY and. INCLUDE directives.
13 .. MCALLs to any externally defined macros.

14. A list of the definitions of all equated symbols used in the module. These definitions

should appear one per line and in alphabetical order.
15. All local macro definitions, preferably in alphabetical order.
16. All local data. The comments in this section should include:

•

Description of each element (type, size, and so forth)

Sample Coding Standard

E-5

•

Organization (functional, alphabetical, adjacent, and so forth)

•

Adjacency requirements (if any)

17. A form feed, followed by a . SBTTL statement describing the routine that follows.
18. A routine header, giving the following information:

•

Routine name

•

Description

•

Inputs

•

Calling sequence

•

Outputs

•

Side effects, register usage, and so forth
NOTE
Repeat items 17 and 18 for every routine within the
module.

E.4.3 Module Example
.NLIST
.ENABL GBL
.LIST MEB
. TITLE MACINI - Once-only code for the MACRO-ll assembler
.SBTTL
.IDENT /Y05.01/

;*****************************************************************************
COPYRIGHT (c) 1982, 1983
BY DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
ALL RIGHTS RESERVED.
;*
;*
;*
;*
;*
;*
;*
;*
;*
;*
;*
;*
;*
;*
;*

*
*
*
**

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED *
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE *
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER *
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY *
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY *
TRANSFERRED.
*
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL.

*
*
*
*
*
*
*
*

;*****************************************************************************
;++

E-6

PDP-l1 MACRO-ll Language Reference Manual

Facility:

MACRO-ll

The PDP-ll macro assembler for RT/RSX/VMS and RSTS/E

Author:

Joe Worrall

Created:

21-Aug-82

Abstract:

MACINI contains code only executed once per task invocation.

Externals
---------

Description
File-ID of the system library account (LB: [1,1])
File-ID of the P/OS library account (LB: [1,5])
Workfile statistics buffer

$LIBID
$POSID
$STABF
Edit

Who

Date

Description of modification

001
002
003

Jrw
Jrw
Jrw

25-Aug-82
05-Sep-82
10-Nov-82

Handle P/OS .PARSE module.
Allow recursive FINIT$'s.
Setup statistics buffer.

External file references
/MACLIB/
/MACPRE/

. LIBRARY
. INCLUDE:

;Add MACLIB.MLB to macro library list
;Include MACPRE.MAC in assembly

External library iI.MCALL's" for this module
.MCALL

FINIT$

Equated symbols
· .. Equated symbols ...
Local macros
· .. Local macros ...
Local data
· .. Local data
.SBTTL

$INIT - Handle once only code for MACRO-ll assembler

Sample Coding Standard

E-7

$INIT
This routine is a collection of all the code. only executed
once in anyone run of the MACRO-11 task. It's collected
here because:
o
o

It's logical to keep it in one place
It keeps the code out of the root. keeping
the a~sembler SMALL.

INPUTS:

n/a

CALL: CALL

$INIT

OUTPUTS:
Record management. statistics. and FCS buffers
are setup. If the system contains EIS support.
the DIV and MUL routine vectors are setup to
point to the hardware instructions.
RO - R5

EFFECTS:

Destroyed!

. .. Begin module code .. ,

E.4.4 Modularity
No other characteristic has more impact on the ultimate engineering success of a
system than does modularity. Adherence to a set of call and return conventions helps
achieve this modularity.
E.4.4.1 Calling Conventions (lnter-Module/lntra-Module)

Transfer of Control
Macros exist for call and return. The actual transfer is via a JSR PC instruction. For
register save routines, a JSR Rn. SAVE is permitted.
The CALL macro is:
CALL

subr-name

The RETURN macro is:
RETURN

Register Conventions
On entry, a subroutine minimally saves all registers it intends to alter except result
registers. On exit, it restores these registers. (The preservation of the register state is
assumed across calls.)
Argument Passing
Any registers can be used, but their use should follow a coherent pattern. For example,
if passing three arguments, use RO, R1, and R2 rather than RO, R2, and R5. Saving and

restoring occurs in one place.

E-8

PDP-ll MACRO-ll Language Reference Manual

E.4.4.2: Exiting

All subroutine exits occur through a single RETURN macro.
E.4.4.3 Success/Failure Indication

The C-bit is used to return the success/failure indicator, where success equals 0, and
failure equals 1. The argument registers can be used to return values or additional
success/failure data.
E.4.4.4 Module Checking Routines

Modules are responsible for verifying the validity of arguments passed to them. The
design of a module's calling sequence should aim at minimizing the validity checks
by minimizing invalid combinations. Programmers may add test code to perform
additional testing during checkout. All code should aim at discovering an error as
close (in terms of instruction executions) to its occurrence as possible.

E.5 Code Format
E.S.1 Program Flow
Programs are organized on the listing so that they flow down the page, even at the cost
of an extra branch or jump. All unconditional branch and jump instructions should
be followed by a blank line. This causes these instructions to stand out in the source
code, allowing the code to be traced more easily. For example:

procesJ

AAA

' - - - - - - - - - I Common I------~

MLO-1256-87

Sample Coding Standard

E-9

appears on the listing as:
TST
BNE

BBB

CMN

AAA:

BBB:
CMN:

rather than:
TST
BNE

BBB

CMN

AAA:

CMN:

BBB:

E.5.2 Common Exits
A common exit appears as the last code sequence on the listing. Thus, the flow chart:

PR1

PR3

PR2

PR4

Exit
MLO-1257-87

E-10

PDP-ll MACRO-ll Language Reference Manual

appears on the listing as:
PR1:
BR

EXIT

PR2:

PR3:

PR4:

EXIT:

and not as:
PR1 :

EXIT:

PR2:
BR

EXIT

PR3:

PR4:

Sample Coding Standard

E-11

E.S.3 Code with Interrupts Inhibited
Code executed with interrupts inhibited is flagged by a 3-semicolon (;;;) comment
delimiter, for example:
.. ERTZ:

;Enable by returning
;by system subroutines,
#PR7,PS
#PR7,2(SP)
10$

BIS
BIT
BEQ
RTT

inhibit interrupts
c
o
m
m

10$:

n
t

E.S.4 Code in System State
RSX-llM executive subroutines and other privileged code executed in systern state is
flagged by a 2-semicolon (;;) comment delimiter, for example:
Switch to system state, ...
and exit.

CALL

$SWSTK,EXIT

Inhibit context switching
Return in system state

Go back to user state (EXIT)
; User state code

RETURN
EXIT:

E.6 Instruction Usage
E.6.1 Forbidden Instructions
You should avoid certain instruction combinations because they make a program hard
to read, debug, and maintain. Avoid the following programming practices:
•

The use of instructions or index words as literals of the previous instruction. For
example:
MOV
BIC

@PC,REGISTER
SRC,DST

uses the bit clear instruction as a literal. This m.ay seem to be a very neat way
to save a word, but the practice can easily confuse the next person who has to
work on the program. To compound the problem, the instruction will not execute
properly if liD space is enabled. In that case, @PC is a D-space reference.

E-1 2

PDP-ll MACRO-ll Language Reference Manual

•

The use of the MOV instruction instead of a JMP instruction to transfer program
control to another location. For example:
MOV

#ALPHA,PC

transfers control to location ALPHA. Besides taking longer to execute, the use of MOV
instead of JMP makes it nearly impossible to pick up someone else's program and
tell where transfers of control take place. As a more general issue, other operations
such as ADD and SUB from PC should be discouraged.
•

The seemingly clever use of all single-word instructions where one double-word
instruction could be used, which would execute faster and not consume any
additional memory. Consider the following instruction sequence:
CMP
CMP

-(Rl) ,-(Rl)
-(Rl),-(Rl)

The intent of this instruction sequence is to subtract 8 from register Rl (not to set
condition codes). This can be accomplished in approximately 1/3 the time via a
SUB instruction at no additional cost in memory space. The practice can also cause
a memory management fault on a mapped system if the value in Rl happens to
look like an unmapped address.
•

Self-·relative address arithmetic (. +n) is absolutely forbidden in branch instructions;
its use in other contexts must be avoided if at all possible and practical.

E.6.2 Conditional Branches
When using the PDP-II conditional branch instructions, you must make the correct
choice between the signed and the unsigned branches.
Signed

Unsigned

BGE
BLI
BGI

BHIS (BCC)

BLE

BLOS (BCS)

BLO
BHI

A comrnon pitfall is to use a signed branch (for example, BGT) when comparing two
memory addresses. This works until the two addresses have opposite signs; that is,
one of them goes across the 16K (100000 8 ) bound. This type of coding error usually
results from relinking the program at different addresses and/or changing the size of
the program.

Sample Coding Standard

E-1 3

E.7 Program Source Files
Source creation and maintenance are done in base levels. A base level is the point at
which the program source files have been frozen. From the freeze point to the next
base level, corrections are not made directly to the base level itself. Rather, a file of
corrections is accumulated for each file in the base level. Whenever an updated source
file is desired, the correction file is applied to the base file.
The accumulation of corrections proceeds until a logical breaking point has occurred
(a milestone or significant implementation point has been reached). At this time, all
accumulated corrections are applied to the previous base level to create a new base
level, and correction files are started for the new base level.

E.8 PDP-11 Version Number Standard
The PDP-II Version Number Standard applies to all modules, parameter files, complete
programs, and libraries which are written as part of the PDP-II Software Development
effort. It is used to provide unique identification of all released, prereleased, and inhouse software.
The version number is limited in that only six characters of identification are used.
Future implementations of the Macro Assembler, Linker, and Librarian should provide
for at least nine characters, and possibly twelve. It is expected that this standard will
be improved as the need arises.
Version Identifier Format:
<version> <edit> <patch>

where:
<version>

consists of two decimal digits which represent the release number of a
program. The version number starts at 00 and is incremented to reflect the
number of major changes in the program.

<edit>

consists of two decimal digits which represent the number of alterations
made to the source program. The edit number begins at 01 (is blank if
there are no edits) and is incremented with each alteration.

<patch>

is a letter between Band Z which represents the number of alterations
made to the binary form of the program.. The patch number begins at B (is
blank if there are no patches) and changes alphabetically with each patch.

These fields are interrelated. When <version> is changed, then <patch> and <edit>
must be reset to blank. It is intended that when <edit> is incremented, then <patch>
will be reset to blank, because the various bugs have been fixed.

E-14

PDP-ll MACRO-ll Language Reference Manual

E.8.1 Displaying the Version Identifier
The visible output of the version identifier should appear as:
Program
Name <key-letter> <version> . <edit> <patch>

where the following Key Letters have been identified:
X

in-house experimental version

field test, prerelease, or in-house release version

released or frozen version

'X' corresponds roughly to individual support, 'Y' to group support, and 'v' to company
support.
The dot (.) which separates <version> from <edit> is not used if both <edit> and
<patch> are null. When a version identifier is displayed as part of program identification,
then the format is:
programname <space><key-letter><version> . <edit><patch>

Exalnples:
PIP VOS.OO
LINK V08.00
MACRO VOS.OO

E.8.2 Use of the Version Number in the Program
All sources must contain the version number in a . IDENT directive. In programs (or
libraries) which consist of more than one module, each module must have a version
number. The version number of the program or library is not necessarily related to the
version numbers of the constituent modules; it is perfectly reasonable, for example,
that the first version of a new FORTRAN library, VOO, contain an existing SIN routine,
for example VOS. 01.
Parameter files are also required to contain the version number in a . IDENT directive.
Because the assembler records the last . IDENT seen, parameter files must precede the
program.
Entities which consist of a collection of modules or programs (for example, the
FORTRAN Library) have an identification module in the first position. An identification
module exists solely to provide identification. For example:
;OTS identification
.TITLE FTNLIB
.IDENT /V02.00/
.END

is an identification module.

Sample Coding Standard

E-1 5

Appendix F

Allocating Virtual Memory
This appendix is intended for the MACRO-II user who wants to avoid the problem of
thrashing by optimizing the allocation of virtual memory. If you have a small system,
yeu should pay particular attention to these conventions.
This appendix discusses the following topics:
•

General hints and space-saving guidelines

•

Macro definitions and expansions

•

Operational techniques

This discussion assumes that you have used modular programming, as advised in
Appendix E. Modular programming results in bodies of code that are small, distinct,
and highly functional. Using such code, which presents many advantages, one can
usually avoid the problem of insufficient dynamic memory during assembly.

F.1 General Hints and Space Saving Guidelines
Working memory is shared by a number of MACRO-II's tables, each of which is
allocated space on demand (64K words of dynamically page able storage are available
to the assembler). The tables and their corresponding entry sizes are as follows:
•

User-defined symbols-five words

•

Local symbols-three words

•

Program sections-six words

•

Macro names--five words

•

Macro text-nine words

•

Source files-six words

In addition, several scratch pad tables are used during the assembly process, as follows:
•

Expression analysis-five words

•

Object code generation-five words

•

Macro argument processing-three words

•

. MCALL argument processing-five words

This information can serve as a guide for estimating dynamic storage requirements and
for determining ways to reduce such requirements.

Allocating Virtual Memory

F-1

For example, the use of local symbols whenever possible is highly encouraged, since
their internal representation requires 25 percent less dynamic storage than that required
for regular user-defined symbols. The usage of local symbols can often be maximized
by extending the scope of local symbol blocks through the . ENABL LSB/. DSABL LSB
MACRO-II directives (see Sections 3.5 and 6.2.1).
Since MACRO-II does not support a purge function, once a symbol is defined,
it permanently occupies its dynamic memory allocation. Numerous instances occur
during conditional assemblies and repeat loops when a temporarily assigned symbol is
used as a count or offset indicator. If possible, the sy:mbols so used should be reused.
In keeping with the same principle, special treatment should be given to the definition
of commonly used symbols. Instead of simply appending a prefix file which defines all
possibly used symbols for each assembly, group symbols into logical classes. Each class
can then become a shortened prefix file or a macro in a library (see Section F.2 below).
In either case, selective definition of symbolic assignments is achieved, resulting in
fewer defined (but unreferenced) symbols.
An example of this idea is seen in the definition of lAS and RSX-IIM standard
symbols. The RSX system macro library, for example, supplies several macros used to
define distinct classes of symbols. These groupings and associated macro names are
as follows:
DRERR$

Directive return status codes

FILIO$

File-related I/O function codes

IOERR$

I/O return status codes

SPCIO$

Special I/O function codes

F.2 Macro Definitions and Expansions
Dynamic storage is used most heavily for the storage of macro text. Upon macro
definition or the issuance of a . MCALL directive, the entire macro body is stored,
including all comments appearing in the macro definition. For this reason, comments
should not be included as part of the macro text. Under RSX-ll, a Librarian function
switch (lsz) is available to compress macro source text by removing all trailing blanks
and tabs, blank lines, and comments. The RSX-ll system macro library (RSXMAC. SML)
has already been compressed. User-supplied macro libraries (. MLB) and macro definition
prefix files should also be compressed. For additional information regarding these two
utility tasks, consult the applicable RSX-IIM or RSX-·l1M-PLUS Utilities Manual (see
the Associated Documents section in the Preface).
It often seems practical to include a file of commonly used macro definitions in each

assembly. This practice, however, may produce the undesirable allocation of valuable
dynamic storage for unnecessary macros. This waste of memory can be avoided by
making the file of macro definitions a user-supplied macro library file (see Table 8-1).
In that case, the names of desired macros must be listed as arguments in the . MCALL
directive (see Section 7.8), or the automatic MACRO call, . ENABL MCL, must be enabled
(see Section 6.2.1).

F-2

PDP-ll MACRO-ll Language Reference Manual

You can delete ITlaCrO definitions after they have been called by using the . MDELETE
request (see Section 7.9). This practice not only frees storage space, it also eliminates the
overhead and the dynamic memory wasted by calling a useless macro. Alternatively,
certain types of Inacros can be redefined to null after they have been called. The
practice of deleting macros or redefining macros to null applies mainly to thos"e that
define symbolic assignments, as shown in the example below. The redefinition process
can be accomplished as follows:
.MACRO DEFIN
SYMl = VALl
SYM2 = VAL2

OFFl
OFF2
OFF3

SYMBOL
OFF1+SIZl
OFF2+SIZ2

OFFN

OFFM+SIZM

. MACRO DEFIN
.ENDM
.ENDM

;Define symbolic assignments.

;Define symbolic offsets.

;Macro null redefinition .

DEFIN

Macros that are to be deleted or redefined should be defined (or read via the . MCALL
directive) and called before all other macro definition and/or . MCALL processing. This
procedure ensures more efficient use of dynamic memory.

F.3 Operational Techniques
When, despite your adherence to the guidelines discussed above, performance still
falls below expectations, several additional measures can be taken to increase dynamic
memory.
The first measure involves shifting the burden of symbol definition from MACRO11 to the Linker or Task Builder. In most cases, the definition of system I/O and
File Control Services (FCS) symbols (and user-defined symbols of the same nature)
is not necessary during the assembly process, since such symbols are defaulted to
global references (Appendix D, error code A). The Linker or Task Builder attempts
to resolve all global references from user-specified default libraries and/or the system
object library (SYSLIB). Furthermore, by applying the selective search option for object
modules consisting only of global symbol definitions, the actual additional burden to
the Linker is minimal.
The second way is to produce only one output file (either object or listing), as opposed
to two. The additional memory required to support the second output file is allocated
from available dynamic memory at the start of each assembly.

Allocating Virtual Memory

F-3

Appendix G

Writing Position-Independent Code
G.1 Introduction to Position-Independent Code
The output of a MACRO-II assembly is a relocatable object module. The Task Builder
or Linker binds one or more modules together to create an executable task image. Once
created, if the program is to run, it must be loaded at the virtual address specified at
link time. This is because the Task Builder or Linker has to modify some instructions
to reflect the memory locations in which the program is to run. Such a body of code
is considered position-dependent (dependent on the virtual addresses to which it is
bound).
All PDP-II processors offer addressing modes that make it possible to write code
that does not depend on the virtual addresses to which it is bound. Such code is
termed position-independent and to run can be loaded at any virtual address. Positionindependent code can, improve system efficiency, both in use of virtual address space
and in conservation of physical memory.
In multiprogramnling systems like lAS, RSX-IIM, and RSX-IIM-PLUS, it is important
that many tasks be able to share a single physical copy of common code, for example,
a library routine. To make the optimum use of a task's virtual address space, shared
code should be position-independent. Position-dependent code can also be shared,
but it must appear in the same virtual locations in every task using it. This restricts
the placement of such code by the Task Builder or Linker and can result in the loss of
virtual addressing space.
The construction of position-independent code is closely linked to the proper usage
of PDP--II addressing modes. The remainder of this Appendix assumes that you are
familiar with the addressing modes described in Chapter 5.
All addressing modes involving only register references are position-independent.
These nlodes are as follows:
R

(R)

(R)+

autoincrement mode

@(R)+

autoincrement deferred mode

- (R)

auto decrement mode

@_. (R)

autodecrement deferred mode

When you use these addressing modes, your code is guaranteed position-independent,
provided the contents of the registers have been supplied such that they are not
dependent upon a particular virtual menlory location.

Writing Position-Independent Code

G-1

The relative addressing modes are position-independent when a relocatable address is
referenced from a relocatable instruction. These modes are as follows:
A

relative mode

relative deferred mode

Relative modes are not position-independent when an absolute address (that is a nonrelocatable address) is referenced from a relocatable instruction. In this case, absolute
addressing (@#A) can be used to make the reference position-independent.
Index modes can be either position-independent or position-dependent, according to
their use in the program. These modes are as follows:
X(R)

index mode

@X(R)

index deferred mode

If the base, x, is an absolute value (for example, a control block offset), the reference

is position-independent. For example:
MOV

2(SP),RO

; Position-independent

N(SP),RO

; Position-independent

N=4

MOV

However, if X is a relocatable address, the reference is position-dependent. For example:
CLR

ADDR(Rl)

; Position-dependent

Immediate mode can be either position-independent or not, according to its usage.
Immediate mode references are formatted as follows:
#N

immediate mode

When an absolute expression defines the value of N, the code is position-independent.
When a relocatable expression defines N, the code is position-dependent. That is,
immediate mode references are position-independent only when N is an absolute
value.
Absolute mode addressing is position-independent only in those cases where an
absolute virtual location is being referenced. Absolute mode addressing references are
formatted as follows:
@#A

absolute mode

An example of a position-independent absolute reference is a reference to the directive
status word ($DSW) from a relocatable instruction. For example:
MOV

@#$DSW,RO

;Retrieve directive status

G.2 Examples
The RSX-IIM library routine PWRUP is a FORTRAN-caHable subroutine that establishes
or removes a user power failure Asynchronous System Trap (AST) entry point address.
Embedded within the routine is the AST entry point that saves all registers, effects a
call to the user-specified entry point, restores all registers on return, and executes an

G-2

PDP-ll MACRO-ll Language Reference Manual

AST exit directive. The following examples are excerpts from this routine. The first
example, Figure G-l, has been modified to illustrate position-dependent references.
The second example, Figure G-2, is the position-independent version.
Figure G-1:

Exarnple of Position-Dependent Code

; Position-dependent code example
PWRUP:: CLR

-(SP)

;AsBume success

Perform further initialization ...

10$:

MOV

'$OTSV,R4

MOV
BNE
CLR
MOV
MOV

(SP)+,R2
10$
-(SP)
R2,F.PF(R4)
#BA,-(SP)

;Point R4 at object time system save area
;the above reference to $OTSV is position; dependent
;Retrieve AST entry point address
;Branch if one was specified
;1f none, specify no power fail routine
;Set the AST entry pOint
;Push the AST service address
the above reference to BA is position; dependent

20$:
; Continue processing ...
;+

; AST service routine
BA:

MOV

RO,-(SP)

;Preserve RO

; Rest of routine follows ...

Writing Position-Independent Code

G-3

Figure G-2:

Example of Position-Independent Code

; Position independent code example
PWRUP:: CLR

-(SP)

;Assume success

Perform necessary initialization ...

10$:

MOV

@#$OTSV,R4

MOV
BNE
CLR
MOV
MOV
ADD

(SP)+,R2
10$
-(SP)
R2,F.PF(R4)
PC,-(SP)
#BA-. , (SP)

;Point R4 at object time system save area
;the above reference to $OTSV is position; independent
;Retrieve AST entry pOint address
;Branch if one was specified
;If none, specify no power fail routine
;Set the AST entry point
;Push our PC to relocate our AST service addr
;Relocate our AST service address now
the above reference to BA is position; dependent

20$:
; Continue processing ...
;+

; AST service routine
BA:

MOV

RO,-(SP)

;Preserve RO

; Rest of routine follows ...

The position-dependent version of the subroutine contains a relative reference to an
absolute symbol ($OTSV) and a literal reference to a relocatable symbol (BA). Both
references are bound by the Task Builder to fixed rrtemory locations. Therefore, the
routine will not execute properly as part of a resident library if its location in virtual
memory is not the same as the location specified at link time.
In the position-independent version, the reference to $OTSV has been changed to an
absolute reference. In addition, the necessary code has been added to conlpute the
virtual location of BA, based upon the value of the program counter. In this case, the
value is obtained by adding the value of the program counter to the fixed displacement
between the current location and the specified symbol. Thus, execution of the modified
routine is not affected by its location in the image's virtual address space.

G-4

PDP-ll MACRO-ll Language Reference Manual

The MACRO-II Assembler provides a way of checking whether the code is positionindependent. In an assembly listing, MACRO-II inserts a single quote (') character
following the contents of any word which requires the Task Builder or Linker to
perform a relocation operation and, therefore, may not be position-independent code.
Cases that are flagged by a single quote in the assembly listing are as follows:
•

Absolute mode references, when the reference is relocatable. References are not
flagged when they are absolute. For example:
MOV

ADDR(Rl),R5
@ADDR(Rl),R5

For

;Non-PIC if ADDR is relocatable.
;Non-PIC if ADDR is relocatable.

Relative and relative deferred mode references, when the specified address is
relocatable with respect to another program section. For example:
MOV
MOV

;PIC only if ADDR is absolute.

Index and index deferred mode references, when the offset is relocatable.
example:
MOV
MOV

•

@#ADDR,Rl

ADDR1,Rl
@ADDR1,Rl

;Non-PIC when ADDRl is absolute.

Immediate mode references to relocatable addresses.
MOV

#ADDR,Rl

;Non-PIC when ADDR is relocatable.

In one case, MACRO-II does not flag a potential position-dependent reference. This
occurs where a relative reference is made to an absolute virtual location from a
relocatable instruction (see the MOV $OTSV" R4 instruction in Figure G-I).
References requiring more than simple relocation at link time are indicated in the
assembly listing. Simple global references are flagged with the letter G. Statements
that contain multiple global references or require complex relocation are flagged with
the letter C (see Section 3.9 and Chapter 4). It is difficult to state with certainty
'whether or not a C-flagged statement is position-independent. However, in general,
position dependence can be decided by applying the guidelines discussed earlier in
this Appendix to the resulting address value produced at link time.

Writing Position-Independent Code

G-5

Appendix H

Sample Assembly and Cross-Reference Listing
R60UNP MACRO V06.04
Table of contents
2-

Wednesday 26-Mar-87 16:49

RAD60 unpack routine

R60UNP

MACRO V06.04

Wednesday 26-Mar-87 16:49
.TITLE
.IDENT

3
4

10
11
12
13
14
16
16
17
18
19
20
21
22
23

This software is furnished under a license and may be used and copied
only in accord with the terms of such license and with the
inclusion of the above copyright notice. This software or any other
copies thereof may not be provided or otherwise made available to any
other person. No title to and ownership of the software is hereby
transferred.
The information in this software is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation.
Digital assumes no responsibility f,)r the use or reliability of its
software on equipment which is not supplied by Digital.
Update history:
D.H. Cutler
SGW

R60UNP MACRO V06.04
RAD60 unpack routine

9
10
11
12
13
14
16
16 000000
17
18 000000
19 000002
20 000006
21 000010
22 000014
23 000020
24 000024
26 000030
26 000032

10-Feb-73
26-Mar-87

Wednesday 26-Mar-87 16:49
.SBTTL

2
3
4
6
6
7

R60UNP
/03/

6
6
7
8
9

Page 1

Page 2

RAD60 unpack routine

R60UNP
Unpack a 6 char RAD60 symbol "to ASCII
Enter with R2 -> Output ASCII string
SYMBOL, SYMBOL+2 = RAD60 symbol to unpack
Return with R2 -> Past output string
RO, Rl, R3 destroyed

.GLOBL

SYMBOL

.PSECT

PUREI,I

010446 R60UNP: : MOV
012704
MOV
OOOOOOG
012401 1$:
MOV
MOV
012703
003100
004767
CALL
000030
012703
MOV
000060
004767
CALL
000020
MOV
010100
004767
CALL
000016

R4,-(SP)
#SYMBOL,R4

;Save R4
;Point at RAD60 symbol buffer

(R4)+,Rl
#60*60,R3

;Get next RAD60 word
;Set divisor for high character

10$

;Unpack and store the character

#60,R3

;Now set divisor for middle character

10$

;Unpack and store the character

Rl,RO
11$

;Copy remaining character
;Translate and store it

Sample Assembly and Cross-Reference Listing

H-1

R4,#SYMBOL+4
; Test if last word done
CMP
27 000036 020427
oooo04G
; Branch if no
1$
28 000042 001361
BNE
(SP)+,R4
;Restore R4
MOV
29 000044 012604
;Return to caller
RE11JRN
30 000046 000207 3$:
31
Translate RAD60 character code to ASCII
32
space
33
o
34
1-32 • A-Z
$
36
33 36
34 =
37
unused code
36 36-47 .. 0-9
38
39
;Divide RAD60 word, get
40 000060 006000 10$:
CLR
RO
DIV
R3,RO
;remainder (RAD60 char) in RO
41 000062 071003
MOVB
TABLE(RO),(R2)+ ;Get ASCII equivalent of RAD60
42 000064 116022 11$:
000062'
RE11JRN
43 000060 000207
44
.NLIST BEX
46
'A, 'B, 'C, '0, 'E, 'F, 'G
040 TABLE: . BYTE
46 000062
47 000072
110
. BYTE
'H, 'I, 'J, 'K, 'L, 'M, 'N, '0
'P, 'Q, 'R, 'S, 'T, 'U, 'V, 'w
48 000102
120
. BYTE
I? '0, '1
49 000112
. BYTE
'X, 'Y, 'Z, '$, ,
130
t

R60UNP MACRO V06.04
RAD60 unpack routine

Wednesday 26-Mar-87 16:49

60 000122
61
62

. BYTE

062

R60UNP

OOOOOORG

. ABS.

000000
000000
PURE I
000132
Errors detected:

' 2 , ' 3 , ' 4 , ' 6 , '6, ' 7, ' 8 , '9

.END

000001

R60UNP MACRO V06.04
Symbol table

Page 2-1

Wednesday 26-Mar-87 16:49
002 SYMBOL- ****** G

000
001
002
0

Page 2-2
TABLE

(RW,I,GBL,ABS,OVR)
(RW,I,LCL,REL,CON)
(RW,I,LCL,REL,CON)

*** Assembler statistics
Work file reads: 0
Work file writes: 0
1 Pages)
Size of work file: 64 Words
Size of core pool: 17920 Words ( 70 Pages)
Operating system: RT-l1
Elapsed time: 00:00:02.46
R60UNP,R60UNP/L:TTM/C:C:R:S=R60UNP
R60UNP MACRO V06.04 Wednesday 26-Mar-87 16:49 Page S-l
Cross reference table (CREF V06.04)
R60UNP
SYMBOL
TABLE

2-18#
2-14
2-42

2-19
2-46#

2-27

R60UNP MACRO V06.04 Wednesday 26-Mar-87 16:49 Page R-l
Cross reference table (CREF V06.04)
RO
Rl
R2
R3
R4
SP

2-26*
2-20*
2-42*
2-21*
2-18
2-18*

2-40*
2-26

2-41*

2-42

2-23*
2-19*
2-29

2-41
2-20

2-27

2-29*

R60UNP MACRO V06.04 Wednesday 26-Mar-87 16:49 Page C-l
Cross reference table (CREF V06.04)
. ABS.
PUREI

H-2

0-0
0-0
2-16

PDP-ll MACRO-ll Language Reference Manual

000062R

002

Appendix I

Obsolete MACRO-11 Directives, Syntax, and
Command Line Options
I. 1 Obsolete Directives and Syntax
Although supported in older versions of MACRO-II, the following directives and
syntax are not supported in the current release. Table 1-1 shows both the old
directives and syntax and the new syntax to use. All MACRO-II code that contains
the old directives and syntax should be updated to use the new syntax.
Table 1·-1:

Old and New Directives and Syntax

Syntax no longer supported

New syntax to use

.EDT

None

.IFZ xxx or .IFEQ xxx

.IF EQ,xxx

.IF Z,XXX

.IF EQ,xxx

. IFNZ xxx or . IFNE xxx

.IF NE,xxx

.IF NZ,xxx

.IF NE,xxx

. IFL xxx or . IFLT xxx

.IF LT,xxx

.IF L,xxx

.IF LT,xxx

.IFG xxx or .IFGT xxx

.IF GT,xxx

.IF G,xxx

.IF GT,xxx

.IFLE xxx

.IF LE,xxx

.IFDF xxx

.IF DF,xxx

.IFNDF xxx

.IF NDF,xxx

1.2 Obsolete Conlmand Line Option
DIGITAL no longer supports the MACRO-II command line option IP [ASS] : n. This
option was originally created to speed up assemblies in some cases by scanning a
given file with only one pass of the assembler. However, DIGITAL has found that
the IP [ASS] : n switch has many side effects; it has caused more problems than can be
documented reasonably.
Although the IP [ASS] : n option is still accepted by MACRO-II, DIGITAL no longer
accepts SPRs relating to the option and has removed all documentation for it.
You should update any assembly command files containing the IP [ASS] : n option
by removing the references to the option.
Obsolete MACRO-ll Directives, Syntax, and Command Line Options

1-1

Appendix J

Release Notes
This appendix explains the changes that have been made to MACRO-II for each
version release since Version 5.0. The new features mentioned are documented in
Chapters 1 through 9 of this manual. Previous versions of this appendix assigned
some of the changes to the wrong version numbers of the software. Accordingly, this
appendix has been rearranged so that each change is listed under the version number
when the change was actually made. If you have Version 5.5 of MACRO-II, you
need not worry about when the changes happened, because all the changes will be in
place. If you are still using an older version of MACRO-II, however, this appendix
can help you determine whether or not a problem in that version has been fixed in a
later version of the software.

NOTE
The version numbers of MACRO-II and its host
operating system are completely independent of each
other. MACRO-II V5.3 was distributed with RT-ll V5.2,
for example. Either version number may change without
affecting the other. Be careful not to confuse the two.

J.1 Changes-AU Versions of MACRO-11
J.1.1 VS.5 Update Changes
•

Hexadecimal support was added:
AX, for temporary hexadecimal radix
. RADIX 16, for permanent radix change
. LIST HEX, to produce a hexadecimal listing

•

Two new conditionals were added: . IF Pl and. IF P2.

•

MACRO-II now accepts more than 254 10 program sections, although only the
first 254 appear in the symbol table. Previously, more than 254 program sections
caused an assembly error.

•

If a . PAGE directive is issued with the listing already at top-of-page, the . PAGE
directive is ignored. In previous versions of MACRO-II, the page nUlnber was
incremented, even though a new physical page was not printed.

•

A. PAGE directive in an un expanded Inacro is now- ignored.

•

The XOR instruction is now flagged with the Z error for certain addressing modes
(execution may be different on different processors).

Release Notes

J-1

•

Space between a macro name and the opening left angle bracket of an argulnent list
is now optional. In previous versions, a space or tab was required. For example, if
BUILD is a macro name, BUILD<A,B,C> is now valid; previously, it had to be written
as BUILD <A,B,C>.

•

In previous versions of MACRO-II, it was possible to change the value of a symbol
that was assigned a value by using the =: operator, even though values assigned
with =: are supposed to be permanent. MACRO-II now retains a symbol's
permanent attribute in all cases.

•

. SBTTL lines in listings now include up to 80 characters.

•

The .IRPC directive now accepts arguments of up to 124 characters; the previous
limit was 96 characters.

•

The error ?MACRO-F-Internal error (on RT-11jRSTS) or MAC-Internal error (on
IASjRSX) was added. If you get this error, please submit an SPR to DIGITAL
along with a method of duplicating the problem.

J.1.2 VS.4 Update Changes
In previous versions of MACRO-II, the assembler parsed the arguments of . IF
conditional statements even if the . IF statements were within unsatisfied conditional
code blocks. This could cause assembly errors when there should be none. MACRO11 no longer parses the arguments of conditional statements within blocks of code that
do not get assembled.

J.1.3 VS.3 Update Changes

J-2

•

MACRO-II did not mark symbolic expressions as complex when they contained
a symbol from a relocatable psect and a symbol from an absolute psect. That
resulted in incorrect Linker output if the base of the absolute psect was not zero.
Those symbolic expressions are now correctly marked as complex.

•

MACRO-II did not mark symbolic expressions as complex when they contained
symbols from different absolute psects. That resulted in incorrect Linker output if
the base of either psect was not zero. Those symbolic expressions are now correctly
marked as complex.

•

When MACRO-II directly assigned the current location counter symbol (.) to
a global symbol in an absolute psect, MACRO-l1 incorrectly bound the global
symbol to the. ABS. psect. MACRO-II now correctly binds the global symbol
to the absolute psect in which the assignment occurred.

•

If MACRO-II encountered a label containing invalid characters, MACRO-l1 would
hang in an infinite loop if there existed a macro with the same name as the valid
part of the label name. MACRO-II now correctly returns an error.

PDP-ll MACRO-ll Language Reference Manual

J" 1.4 VS.2 Update Changes
•

MACRO-II does not allow the colon (:) character as a delimiter for .ASCII or
.ASCIZ strings. This is now documented in Chapter 6.

•

MACRO-II now provides support for the 8-bit DEC Multinational character set
(MCS). A chart showing the MCS is located in Appendix A.
The following directives support the MCS. For specific support information, consult
the description of each directive.
Macro
Directive

Section

.ASCII

6.3.4

.ASCIZ

6.3.5

. ERROR

7.5

.IF

6.9.1

.IF DIF
.IF IDN
.IFF

6.9.2

.IFF DIF
.IFF IDN
.IRP

7.6.1

.IRPC

7.6.2

. NCHR

7.4.2

.PRINT

7.5

. REM

6.1.6

.SBTTL

6.1.3

. TITLE

6.1.2

Further information on the 8-bit DEC Multinational character set is located in
sections:
2.2.4

Comment field

6.3.3

ASCII conversion characters

7.3

Arguments in macro definitions and macro calls

7.3.6

Keyword arguments

J.1.S VS.1 Update Changes
•

MACRO-II processed some index deferred arguments as floating-point numbers
by default. MACRO-It now processes all index deferred arguments as octal by
default.

Release Notes J-3

•

MACRO-II did not mark internal displaced relocatable statements as relocatable
with a single quote (') in the assembly listing. They are now marked correctly.

•

MACRO-II set bit 3, an unused bit, in all . PSECT object records. MACRO-II no
longer sets bit 3. That change makes object files created with the new version of
MACRO-II different from object files created with previous versions of MACRO11. As a result, they will have different PAT checksums, and a binary comparison
of the files will show differences. However, the resulting task or . SAV image files
will be the same.

J.1.6 V5.0 Update Changes
•

The op code CALLR addr (Call-Return) has been added to the permanent symbol
table (PST). This op code is equivalent to the JMP addr op code. The CALLR addr
op code was added to complement the CALL addr op code, which is equivalent to
the JSR PC, addr op code.

•

The previous version of MACRO-II used a range of 64$ to 127$ for automatic
local symbol generation. MACRO-II now uses a range of 30000$ to 65535$ when
generating local symbols.

•

Most assembler generated listing text is now in uppercase and lowercase. This
change was made to increase the readability of MACRO-II code. Lines of code
that include the . SBTTL or the . TITLE directive are not converted to uppercase.

•

Lines of code that include the . SBTTL directive are listed in the table of contents of
an assembly listing, even if a . NLIST statement is in effect at the time the . SBTTL
lines are encountered. You can specify the. NLIST directive with the TOC argument
to prevent the table of contents from being printed.

•

The symbol table is printed at the end of an assenlbly, even if the . NLIST directive
is in effect. You can specify the. NLIST directive V\'ith the SYM argument to prevent
the symbol table from being printed.

•

All page headers include the day of the week.

•

The assembler statistics information that appears at the end of the assembly listing
file has been updated to include the following additional information:
Total number of virtual workfile reads
Total number of virtual workfile writes
Maximum amount of virtual memory used (in words and pages)
Size of physical memory free space (in words and pages)
Operating system and environment that the assembler is running under
Total elapsed assembly time
MACRO-II command line

•

The program section (. PSECT) synopsis that is printed after the symbol table in the
listing file includes the program section attributes.

J-4 PDP-ll MACRO-ll Language Reference Manual

The maximunl number of relocatable terms in a complex expression has been
changed. The maximum size of a .OBJ record that MACRO-11 can produce was
increased from 42 10 bytes to 128 10 bytes.

Do not compare. OBJ files that have been created by different versions of MACRO11 when verifying whether your code generation is correct. Changes that have
been made for this version of MACRO-11 (mentioned above) invalidate a direct
comparison of assembler .OBJ output. Verify code generation by linking or
taskbuilding the .OBJ files involved and then comparing the . SAVor the . TSK
image files.

NOTE
.OBJ files produced by this version of MACRO-11 are
different from those produced by older versions. If
you use the PAT (object file patch utility), checksums
must be recomputed on any object patches assembled
with this new version of MACRO-11.
•

The default for the LC argument has been changed from . DSABL LC to . ENABL LC.

The following . ENABL/ . DSABL options have been added:
.:ENABL LCM/.DSABL LCM
.:ENABL MCL/.DSABL MCL

The following directives have been added to MACRO-11 and documented in this
manual.
. CROSS
. INCLUDE
. LIBRARY
.MDELETE
. NOCROSS
. REM
. WEAK

J.2 Changes-MACRO-11/RSX Version Only
J.2.1 V5.5 Update Changes
There were no RSX-specific changes made to MACRO-11 VS.5.

J.2.2 V5.4 Update Changes
There were no RSX-specific changes made to MACRO-11 VS.4.

Release Notes

J-5

J.2.3 V5.3 Update Changes
•

Previous versions of MACRO-11 would hang in an infinite loop if they encountered
a record with an invalid record size. That problem has been fixed.

•

MACRO-11 now fully supports RSX logical names by calling the . CSI4: SYSLIB
parsing routine.

J.2.4 V5.2 Update Changes
There were no RSX-specific changes made to MACRO-11 VS.2.

J.2.S V5.1 Update Changes
•

Previous versions of MACRO-11 would exit with SUCCESS exit status even though
errors were reported. That problem has been fixed.

•

If MACRO-11 detected an I/O error while reading a command file, MACRO-11

would produce an odd-address trap. Now, MACRO-11 reports the error message
MAC-Command I/O error.

J.2.6 V5.0 Update Changes
•

The cross-reference options SEC and ERR have been added.
NOTE
The RSX-11 CREF program (CRF) has been updated
to include support for these two new macro crossreference options. Only the new RSX-11 CRF version
(V2) distributed with RSX-11M V4.1 and RSX-11MPLUS V2.1 should be used with this version of
MACRO-11.

•

The default for the command line option I [-] SP has been modified fro:m ISP to
l-sP. The new default may be modified by the system manager by using the TKB
GBLPAT option described in the MACRO-11/RSX Task Build command file.

J.3 Changes-MACRO-11/RT-11 Version Only
J.3.1 VS.5 Update Changes
•

In previous versions the error message ?MACRO-F-I/O Error on workjlle could
occur either because of an actual I/O error or because the workfile was full. A
new error message was added, ?MACRO-F-Workfile space exceeded, and the I/O
error message reserved for I/O errors only.
You can increase the size of the RT -11 MACRO-11 workfile to a maximum of
400 8 blocks with a customization patch. Refer to the file CUSTOM. TXT on your
distribution kit for the address of the location to patch. If your program requires

J-6 PDP-ll MACRO-ll Language Reference Manual

workfile space greater than 400 8 blocks, you will get the error message ?MACROF-Storage limit exceeded (64K). This limit cannot be increased.
•

In previous versions, if you requested a CREF listing of only error codes (lc: E)
but your program had no errors, CREF would hang. CREF now handles this case
properly.

J.3.2 V5.4 Update Changes
•

Invalid nonprinting characters in a MACRO-II source file were not being detected.
MACRO-II now detects invalid nonprinting characters and flags them with an I
error.

•

CREF did not produce a correct cross-reference listing of a MACRO·-ll source with
a page length of more than 999 lines. CREF now handles pages of more than 999
lines correctly.

J.3.3 V5.3 Update Changes
•

When running in memory configurations smaller than 8K words, MACRO-II
sometimes tra.pped with an invalid EMT error, indicating that the input . MAC file
was not found when in fact the file did exist, or displayed spurious assembly errors.
MACRO-II now runs correctly in memory configurations smaller than 8K words.

J.3.4 VS.2 Update Changes
There were no RT-ll-specific changes made to MACRO-II VS.2.

J.3.5 V5.1 Update Changes
There were no RT -II-specific changes made to MACRO-II VS .1.

J.3.6 V5.0 Update Changes
•

The message:
Errors detected: 0

is no longer printed on the console terminal. MACRO-II prints the message on
the terminal only if errors have been detected in the module being assembled.
•

If the first character in a MACRO-II jRT -11 command line is a semicolon (;), the
line is treated as a comment and is ignored. This change was made to maintain
compatibility with the RSX-ll version of MACRO-l1.

Release Notes

J-7

•

RSX-II style command line switches may be used in addition to the I-character
options:
1M

IE
10
IP

IL
IN

can be represented as 1M [LIB]
can be represented as IE [NABL]
can be represented as 10 [SABL]
can be represented as IP [ASS]
can be represented as IL [1ST]
can be represented as IN [LIST]

•

The default file extension for macro libraries has been changed to . MLB to conform
with RSX-Il. The RT-II V5 LIBR program defaults its macro library output to
the . MLB extension, also.

•

Prior to this release of MACRO-II, if you specified more than one . MLB file
on a command line and each file had a definition of the same macro, the first
specified macro library would be used for the macro definition if called in the
source program. This has been modified to work the same as the RSX-II macro
assembler. The RT-II macro assembler now scans .MLB files from the last specified
file (either in the MACRO-II command line or by using the. LIBRARY directive) to
the first specified file. The assembler then scans the system default macro library,
SY : SYSMAC . SML.

•

J-8

The default for the GBL argument has been changed from .OSABL GBL to . ENABL GBL.

PDP-ll MACRO-ll Language Reference Manual

Index
A
ABS
argument for .ENABLj.DSABL, 6-14
argument for .PSECT, 6-·36
. ABS. default program section name, 6-37
Absolute expressions, 3-14
definition, 3-15
Addition operator, 3-4
Addressing modes, 5-1
absolute, 5-6
autodecrement, 5-4
autodecrement deferred, 5-4
autoincrement, 5-4
autoincrement deferred, 5-4
difference between absolute and relative, 5-8
effect of .ENABL AMA, 5-8
immediate, 5-6
index, 5-5
index deferred, 5-5
register, 5-3
register deferred, 5-3
relative, 5-7
relative deferred, 5-8
summary, B-2
table of, 5-2
A error
.ASCII, 6-20
.ASCIZ, 6-21
.BLKlBj.BLKW, 6-32
.BYTE,6-17
.ENABLj.DSABL, 6-14
.ENDM, 7-3
for invalid floating point number, 6-28
.IF, 6-46
.IIF, 6-51
in bad expression, 3-15
inconsistent current location counter
attribute, 3-12
invalid forward reference defining global,
3-8
.IRP, 7-20
.IRPC, 7-20

A error (cont'd.)
.LIST j.NLIST, 6-9
.MACRO, 7-3
.NARG,7-13
.NCHR,7-15
.NTYPE, 7-16
on EMT and TRAP instructions, 5-9
.PSECT, 6-35, 6-38
.RAD50, 6-22
.RADIX, 6-26
.REPT, 7-22
.RESTORE, 6-42
.sAVE, 6-41
single or double quote character storage,
6-20
.TITLE, 6-10
AMA
argument for .ENABLj.DSABL, 6-14
Ampersand
AND operator, 3-4
special character in MACRO-II, 3-2
special meaning within .IF DF jNDF
conditional, 6-47
AND operator
special meaning within .IF DF jNDF
conditional, 6-47
summary, 3-4
Angle brackets
argument delimiter, 3-3
enclose expressions, 3-14
required for special .RAD50 values, 6-23
spaces may increase readability of
arguments, 7-6
to insert special values in .ASCII, .ASCIZ
strings, 6-21
use in keyword arguments, 7-11
Apostrophe
see Single quote
Argument delimiters
angle brackets, 3-3
circumflex, 3-3
table of, 3-3

Index-1

ASCII character set, A-I
ASCII character storage techniques, 6-19
.ASCII directive, 6-20
changes current location counter, 6-31
inserting special values with angle brackets,
6-21
summary, 6-1
.ASCIZ directive, 6-21
changes current location counter, 6-31
inserting special values with angle brackets
see .ASCII directive
summary, 6-1
.ASECT directive, 6-40
assigns attributes to current location counter,
3-12
default characteristics, 6-41
special case of .PSECT, 6-40
summary, 6-1
terminates local symbol block, 3-10
Assembler directives
see Directives
Asterisk
in cross-reference table, 8-15
multiplication operator, 3-4
special character in MACRO-II, 3-2
At sign
special character in MACRO-II, 3-2
used in absolute addressing mode, 5-6
used in auto decrement deferred mode, 5-4
used in autoincrement deferred mode, 5-4
used in index deferred mode, 5-5
used in register deferred mode, 5-3
used in relative deferred addressing mode,
5-8

B
for temporary binary radix, 6-27
Backslash
cannot take forward reference, 7-8
cannot use with relative symbol, 7-8
special character in MACRO-II, 3-2
used to pass numeric argument as symbol,
7-8
B conditional assembly test, 6-46
only comma valid as separator, 6-50
B error
odd current location counter, 6-31

Index-2

BEX
argument for .LISTj.NLIST, 6-7
BIN
argument for .LIST j.NLIST, 6-7
Binary operators
ampersand, 3-4
asterisk, 3-4
exclamation mark, 3-4
minus sign, 3-4
plus sign, 3-4
priority, 3-4
slash, 3-4
table of, 3-4
use, 3-4
used in expressions, 3-14
BLK. default program section name, 6-37
.BLKB directive, 6-32
changes current location counter, 6-31
preferred way to reserve space, 3-13
summary, 6-1
.BLKW directive, 6-32
preferred way to reserve space, 3-13
summary, 6-1
Branch instruct!ans, 5-8
.BYTE directive, 6-17
changes current location counter, 6-31
example using concatenated macro argument,
7-13
summary, 6-1

c
C

flag in assembly listing, 4-1
"C

one's complement operator, 6-29
represents pressing ICTRL/cl in command
lines, 8-1
jC[R] option
relationship to .CROSSj.NOCROSS, 6-16
Carriage return
cannot follow single or double quote, 6-20
CDR
argument for ,ENABLj.DSABL, 6-14
Characters
invalid, 3-3
Character set
ASCII, A-I
DEC multinational, A-I
DEC multinational chart, A-10

Character set (cont'd.)
definition, 3-1
radix·-50, A-8
Circumflex
construct for argument delimiter, 3-3
different meanings, 7-6
passing angle brackets as part of macro
argument, 7-6
passing DEC multinational characters, 7-6
special character in MACRO-II, 3-2
universal unary operator, 3-4
CND
argument for .LISTj.NLIST, 6-7
Coding standard, E-1
Colon
invalid as .ASCII string delimiter, 6-21
invalid as .ASCIZ string delimiter, 6-22
invalid as .IDENT string delimiter, 6-12
invalid as .RAD50 string delimiter, 6-23
must precede switch value in RSX command
string, 8--5
never as character string delimiter, 6-21
special character in MACRO-II, 3-1
terminates a label, 2-2
COM
argument for .LIST j.NLIST, 6-7
Comma
in macro argUlnent, 7-8
separating character, 3-3
special character in MACRO-II, 3-2
used in operand field, 2--4
Command string examples (lAS), 8-14
Command string format (lAS), 8-12
Comment field
begins with semicolon, 2.-4
definition of, 2-4
using .REM, 6-13
valid characters, 2-4
Commercial instruction set (list), C-4
Complement operator CC), 6-29
Complex relocatable expressions, 3-14
definition, 3-16
maximum number of terms, 3-16
CON
argument for .PSECT, 6--37
cannot share data, 6-39
if section ends with odd address, 6-40
Concatenation of arguments
example, 7-9

Concatenation of macro arguments, 7-12
Conditional assembly directives, 6-45
.IF, 6-45
.IFF, 6-48
.1FT, 6-48
.IFTF, 6-48
.IIF, 6-50
CREF
see Cross-reference
CRF
argument for .ENABLj.DSABL, 6-14
.CROSS directive, 6-16
relationship to jC[R] or jCROSS option,
6-16
summary, 6-1
jCROSS option
relationship to .CROSSj.NOCROSS, 6-16
Cross-reference listing
sample, H-1
Cross-reference processor
options with lAS jRSX, 8-14
options with RT-11, 9-7
use with lAS jRSX, 8-14
with RT -II, 9-6
Cross-reference table
special symbols, 8-15
.CSECT directive, 6-40
assigns attributes to current location counter,
3-12
default characteristics, 6-41
special case of .PSECT, 6-40
summary, 6-2
terminates local symbol block, 3-10
Current location counter, 3-11
cannot assign value with forward reference,
3-12
change with direct assignment statement,
3-12
changing attributes of, 3-12
effect of odd value, 6-31
list of statements that may leave as odd
value, 6-31
using to reserve space, 3-13
Current location counter symbol (period), 3-7,
3-11
assign new value to, 3-12
in program sections, 6-39

Index-3

D
AD
for temporary decimal radix, 6-27
D

argument for .PSECT, 6-35
Data storage directives, 6-17
DCL command language (RSX), 8-1
DCL command qualifiers (RSX), 8-7
DCL operating procedures (RSX), 8-7
DEC multinational character set
, chart, A-I0
table, A-I
use in keyword arguments, 7-11
using circumflex when passing as arguments,
7-6
Delimiters
See argument delimiters
D error
multiply-defined label reference, 2-3
DF conditional assembly test, 6-46
DIF
conditional assembly test, 6-46
effect of .ENABLj.DSABL LCM, 6-46
Direct assignment statements, 3-7
double equal colon sign, 3-7
double equal sign, 3-7
equal colon sign, 3-7
equal sign, 3-7
forward referencing, 3-8
may change current location counter, 6-31
requirements, 3-8
use of space character, 3-8
Directives
conditional assembly, 6-45
data storage, 6-17
file control, 6-51
function, 6-13
indefinite repeat, 7-19
listing control, 6-3
list of obsolete, 1-1
macro, 7-1
macro attribute, 7-13, 7-15
overriding permanent definitions with
.MCALL, 7-22
summary, B-3, B-4, B-5, B-6, B-7, C-8
symbol control, 6-43
table of general, 6-1
Division operator, 3-4

Index-4

Dollar sign
reserved for DIGITAL system symbols, 3-1,
3-5
Double colon
effect when defining a label, 3-6
special character in MACRO-II, 3-1
terminates a label, 2-2
Double equal colon sign
used in direct assignment statements, 3-7
Double equal sign
effect when defining a label, 3-6
special character in MACRO-II, 3-1
used in direct assignment statements, 3-7
Double equal sign colon
effect when defining a label, 3-6
special character in MACRO-II, 3-1
Double quote
component of a term, 3-14
for ASCII character storage, 6-19
special character in MACRO-II, 3-2
.DSABL directive, 6-14
summary, 6-2
table of symbolic arguments, 6-14
.DSABL FPT
disables floating point truncation, enables
rounding, 6-29
.DSABL GBL
effect on undefined symbols, 3-6, 3-14
.DSABL LC
effect on valid character set, 3-1
.DSABL LCM
effect on .IF IDNj.IF DIF, 6-46
.DSABL LSB
terminates local symbol block, 3-10
Dummy arguments in macro definition, 7-2
relationship to real arguments, 7-5

E
E error
.END,6-34
EMT instructions, 5-9
.ENABL AMA
difference between absolute and relative
addressing, 5-8
.ENABL directive, 6-14
summary, 6:-2
table of symbolic arguments, 6-14
.ENABL FPT

.ENABL FPT (cont'd.)
enables floating point truncation, disables
rounding, 6-29
.ENABL GBL
effect on undefined symbols, 3-6
.ENABL LCM
effect on .IF IDNj.IF DIF, 6-46
.ENABL LSB
begins local symbol block, 3-10
may confuse automatic local symbol
generation in macro, 7-11
.ENABL MCL
relationship to .LIBRARY, 6-51
.ENDC directive
error if outside conditional block, 6-47
not required with .IIF, 6--50
sumrnary, 6-2
.END directive, 6-34
sumrnary, 6-2
.ENDM directive, 7-3
cannot have label, 7-3
can terminate repeat blocks, 7-4
sumrnary, 7-1
terminates macro definition, 7-3
.ENDR directive, 7-21
summary, 7-1
terminates .IRP, 7-20
terminates .IRPC, 7-20
terminates .REPT, 7-22
EQ conditional assembly test, 6-46
Equal colon sign
used in direct assignment statements, 3-7
Equal sign
in cross-reference table, 8-15
special character in MACRO-II, 3-1
used as character string delimiter, 6-21
used in direct assignment statements, 3-7
Equal sign colon
special character in MACRO-II, 3-1
Error codes, D-1
A

.ASCII, 6-20
.ASCIZ, 6-21
.BLKBj.BLKW, 6-32
.BYTE,6-17
.ENDM,7-3
from .ENABLj.DSABL, 6-14
.IF, 6-46
.1IF, 6-51

Error codes
A (cont'd.)
in bad expression, 3-15
inconsistent current location counter
attribute, 3-12
invalid floating point number, 6-28
invalid forward reference defining global,
3-8
.IRP, 7-20
.IRPC, 7-20
.LIST j.NLIST, 6-9
.MACRO, 7-3
.NARG,7-13
.NCHR, 7-15
.NTYPE, 7-16
on EMT and TRAP instructions, 5-9
.PSECT, 6-35, 6-38
.RAD50, 6-22
.REPT, 7-22
.RESTORE, 6-42
.sAVE, 6-41
single or double quote character storage,
6-20
.TITLE, 6-10
B
from odd current location counter, 6-31
D

multiply-defined label reference, 2-3
E

.END, 6-34
.ASCII, 6-20
.ASCIZ, 6-21
invalid character, 3-3
.RAD50, 6-22
M

multiply-defined label, 2-3
redefine permanently-assigned symbol,
3-7
N

number not in current radix, 3-13
.END,6-34
.ENDC, 6-47
.IF directive nesting, 6-47
.MCALL, 7-23
.MDELETE, 7-23
.MEXIT, 7-4
.NARG, 7-13

Index-5

Error codes
o (cont'd.)
.NTYPE, 7-16
with .IFF, .1FT, .IFTF, 6-48
P

.ERROR, 7-18
inconsistent program section attribute,
3-12
multiple definition of local symbol, 3-11
when defining local symbols, 6-15

Q
.EVEN,6-31
for invalid floating point number, 6-28
in bad expression, 3-15
invalid syntax, 3-3
.ODD,6-32
.TITLE, 6-10
too many arguments in macro call, 7-9

R
invalid redefinition of default register
symbol, 3-9
T

number more than 16 bits long, 3-13
U,3-6
invalid forward reference, 3-8
.MCALL, 7-23
relationship to .ENABLj.DSABL MCL or
GBL,6-15
undefined symbol, 3-14

flags inconsistent instructions, 5-1
table of applicable instructions, 5-3
.ERROR directive, 7-18
summary, 7-1
Error messages
system messages for IAS/RSX, 8-18, 8-19,
8-20
system messages for RT-11, 9-8, 9-9, 9-10,
9-11, 9-12
.EVEN directive, 6-31
summary, 6-2
Exclamation mark
logical inclusive OR operator, 3-4
special character in MACRO-II, 3-2
special meaning within .IF DF /NDF
conditional, 6-47
Expressions, 3-14
components of a term, 3-14
definition, 3-14

Index-6

Expressions (con1' d.)
evaluation rules, 3-14
types, 3-14, 3-15
value of global at assembly, 3-15
External expressions, 3-14
definition, 3-16

F
AF
I-word floating point operator, 6-30
File control directives, 6-51
File specifications
default for RSX-11M, 8-2
defaults for RT-11, 9-2
lAS /RSX, 8-17
Floating point numbers
formats, 6-28
single-word format, 3-13
using AF operator, 3-13
Floating point processor op codes (list), C-6
.FLT2 directive, 6-30
summary, 6-2
.FLT4 directive, 6-30
summary, 6-2
Format
of a MACRO--11 statement, 2-1
recommended source line format, 2-5
Form feed
cannot follow single or double quote, 6-20
effect inside macro definition, 7-4
generates new page in listing, 6-13
Forward reference
invalid in current location counter
assignment, 3-12
Forward referencing
in direct assignments statements, 3-8
FPT
argument for .ENABL/.DSABL, 6-14
Function directives, 6-13

G
G

flag in assembly listing, 4-1
GBL
argument for .ENABLj.DSABL, 6-14
argument for .PSECT, 6-36
use for data sharing, 6-39
GE conditional assembly test, 6-46
Global expressions

Global expressions (cont'd.)
definition, 3-16
Global symbols
creatilng with direct assignment statements,
3-7
defining, 3-6
function, 3-6
value at assembly time, 3-15
.GLOBL directive, 6-43
defines global user symbols, 3-6
sumrnary, 6-2
GT conditional assembly test, 6-46

H
HEX
argument for .LIST/.NLIST, 6-8

argument for .PSECT, 6--35
lAS
command string examples, 8-14
command string format, 8-12
operating procedures, 8-·11, 8-13
system error messages, 8-18, 8-19, 8-20
lAS file specification, 8-17
.IDENT directive, 6-12
sumrnary, 6-2
IDN
conditional assembly test, 6-46
effect of .ENABLj.DSABL LCM, 6-46
I error
.ASCII, 6-20
.ASCIZ, 6-21
invalid character, 3-3
.RAD50, 6-22
.IF B
use to detect missing arguments, 7-9
.IF DF
logical AND, OR operators have special
meaning, 6-47
.IF DIF
effect of .ENABLj.DSABL LCM, 6-14
.IF directive, 6-45
maximum nesting level, 6-47
summary, 6-2
table of valid condition tests, 6-46

.IFF directive, 6-48
summary, 6-2
.IF IDN
effect of .ENABLj.DSABL LCM, 6-14
.IF NB
use to detect missing arguments, 7-9
.IF NDF
logical AND, OR operators have special
meaning, 6-47
.1FT directive, 6-48
summary, 6-2
.IFTF directive, 6-48
summary, 6-2
.IIF directive, 6-48
does not require .ENDC, 6-50
summary, 6-2
.INCLUDE directive, 6-52
default device and file type, 6-52
does implicit .PAGE, 6-52
maximum nesting level, 6-52
restriction on RT -11 systems, 6-52
summary, 6-2
Inclusive OR operator
summary, 3-4
Indefinite repeat directives, 7-19
Invalid characters, 3-3
.IRPC directive, 7-20
restriction using label, 7-20
summary, 7-1
.IRP directive, 7-19
summary, 7-1

K
Keyword arguments, 7-11
order, 7-11
using DEC multinational character set, 7-11

L
Label
definition of, 2-2
if same as macro name, 7-5
maximum length, 2-3
not recommended on .MACRO directive, 7-3
on line containing .PSECT, .ASECT, or
.CSECT, 6-39
terminated with colon, 2-2
terminated with double colon, 2-2
terminates local symbol block, 3-10

Index-7

Label (cont'd.)
user label may confuse automatic local
symbol generation in macro, 7-10
valid characters for, 2-3
valid formats, 2-2
LC
argument for .ENABLj.DSABL, 6-14
LCL
argument for .PSECT, 6-36
LCM
argument for .ENABLj.DSABL, 6-14
LE conditional assembly test, 6-46
Left angle bracket
invalid as .ASCII string delimiter, 6-21
invalid as .ASCIZ string delimiter, 6-22
invalid as .IDENT string delimiter, 6-12
invalid as .RAD50 string delimiter, 6-23
special character in MACRO-II, 3-2
Left parenthesis
special character in MACRO-II, 3-2
.LIBRARY directive, 6-51
default device and file type, 6-51
limit on number of files, 6-51
relationship to .ENABL MCL, 6-51
relationship to .MCALL, 6-51, 7-22
restriction on RT-11 systems, 6-51
summary, 6-2
jLIBRARY option
relationship to .MCALL, 7-22
.LIMIT directive, 6-33
summary, 6-2
Line feed
cannot follow single or double quote, 6-20
Linking, discussion, 4-1
.LIST directive, 6-6
overriding with command line options, 6-9
summary, 6-2
table of arguments, 6-7
Listing (sample), H-1
Listing control directives, 6-3
.IDE NT, 6-12
overriding with command line options, 6-9
.PAGE,6-12
.REM,6-13
.SBTTL, 6-11
table of arguments, 6-7
.TITLE, 6-10
Listing format, 6-3

Index-8

LOC
argument for .LIST j.NLIST, 6-8
Local symbol block
ways to delimit, 3-10
Local symbols
automatic generation limitations, 7-10
cautions with automatic generation, 7-10
creating automatically in macros, 7-9
definition, 3-10
generate automatically in macro expansion,
3-10
range of valid values, 7-10
range of values, 3-10
uses, 3-10
Location counter
see Current location counter
Logical AND operator
special meaning within .IF DF jNDF
conditional, 6-47
summary, 3-4
Logical inclusive OR operator
special meaning within .IF jNDF conditional,
6-47
summary, 3-4
LSB
argument for ,ENABLj.DSABL, 6-15
LT conditional assembly test, 6-46

M
Macro argument delimiters
table of, 3-3
.MACRO directive, 7-2
label not recommended, 7-3
summary, 7-1
Macro directives, 7-1
.ENDM,7-3
.MACRO, 7-2
.MEXIT, 7-4
table, 7-1
Macros, 7-2
argument concatenation example, 7-9
arguments in definitions and calls, 7-5
attribute directives, 7-13, 7-15
begin with .MACRO, 7-2
calling, 7-5
concatenation of arguments, 7-12
creating local symbols automatically, 7-9
defining, 7-2
definition of terms, 7-2

Macros (cont'd.)
dumrnyarguments, 7-2
formatting of definitions, 7-4
if narne is same as user label, 7-5
keyword arguments, 7-11
keywords can override positional
relationship, 7-5
nesting, 7-7
Inaximum level, 7-7
number of arguments in calls, 7-9
passing numeric arguments as symbols, 7-8
relationship of dummy and real arguments,
7-5
separators for arguments). 7-5
special characters in arguments, 7-8
special treatment of DEC multinational
characters in arguments, 7-6
Macro symbols, 3-5
rules, 3-5
.MAIN.
default of .TITLE, 6-10
MC
argument for .LIST j.NLIST, 6-8
.MCALL directive, 7-22
overriding permanent symbol definitions,
7-22
relationship to .LIBRARY, 6-51, 7-22
summary, 7-1
when required, 7-22
MCL
argument for .ENABLj.DSABL, 6-15
MCR command language (RSX), 8-1
MCR command string format, 8-4
MD
argunlent for .LISTj.NLIST, 6-8
.MDELETE directive, 7-23
summary, 7-1
ME
argument for .LIST j.NLIST, 6-8
MEB
argument for .LIST j.NLIST, 6-8
Memory
allocation considerations, 6-40
using efficiently, F-1
M error
multiply-defined label, 2--3
redefine permanently-assigned symbol, 3-7
.MEXIT directive, 7-4
exit .IRP before normal completion, 7-20

.MEXIT directive (cont'd.)
exit .IRPC before normal completion, 7-21
exit .REPT before normal completion, 7-22
summary, 7-1
terminates macro before completion, 7-4
valid in repeat blocks, 7-4
Minus sign
complements switch in RSX command string,
8-5
special character in MACRO-II, 3-2
subtraction operator, 3-4
unary minus operator, 3-4
jML option
relationship to .MCALL, 7-22
:Modes
see Addressing modes
:Multiplication operator, 3-4

N
NAME
argument for .PSECT, 6-35
.NARC directive, 7-13
summary, 7-1
use to detect missing arguments, 7-9
NB conditional assembly test, 6-46
only comma valid as separator, 6-50
.NCHR directive, 7-15
summary, 7-1
NDF conditional assembly test, 6-46
NE conditional assembly test, 6-46
N error
number not in current radix, 3-13
Nesting macros, 7-7
maximum level, 7-7
.NLIST directive, 6-6
overriding with command line options, 6-9
summary, 6-2
table of arguments, 6-7
"NLIST TOC
suppresses table of contents, 6-11
"NOCROSS directive, 6-16
relationship to jC[R] or jCROSS option,
6-16
summary, 6-2
NOSAV
argument for .PSECT, 6-37
.NTYPE directive, 7-16
summary, 7-2

Index-9

Null
cannot follow single or double quote, 6-20
Numbers, 3-13
changing default radix, 3-13
components of a term, 3-14
floating point using ~F, 3-13
initial default is octal, 3-13
never relocatable, 3-13
Number sign
in cross-reference table, 8-15
signifies octal number in RSX command
string, 8-5
special character in MACRO-II, 3-2
used in absolute addressing mode, 5-6
used in immediate addressing mode, 5-6

Options
list of obsolete, I-I
OR operator
special meaning within .IF jNDF conditional,
6-47
summary, 3-4
OVR
argument for .PSECT, 6-37
if section ends with odd address, 6-40
use for data sharing, 6-39

conditional assembly test, 6-46
.PACKED directive, 6-24
changes current location counter, 6-31
summary, 6-2
.PAGE directive, 6-12
implicit with .INCLUDE, 6-52
inside macro definition, 7-4
summary, 6-2
Page eject
if .PAGE directive encountered, 6-12
if form feed encountered, 6-13
if more than 58 lines, 6-13
if new source file, 6-13
operation of form feed inside macro
definition, 7-4
Pass 1, what happens, 1-1
Pass 2, what happens, 1-2
PC
see Program counter
Percent sign
defines register symbols, 3-8, 3-9
special character in MACRO-II, 3-1
Period
component of a term, 3-14
current location counter symbol, 3-7, 3-11,
3-14
assign new value to, 3-12
makes expression relocatable, 3-15
reserved for DIGITAL system symbols, 3-1,
3-5
signified decimal number in RSX command
string, 8-5
special character in MACRO-II, 3-2

for temporary octal radix, 6-27
Obsolete
command line options, I-I
directives, I-I
Octal radix
initial default for numbers, 3-13
Odd address
at end of program sections, 6-40
.ODD directive, 6-32
changes current location counter, 6-31
summary, 6-2
o error
.END,6-34
.ENDC, 6-47
.IF directive nesting, 6-47
.IFF, .1FT, .IFTF, 6-48
.MCALL, 7-23
.MDELETE, 7-23
.MEXIT, 7-4
.NARG, 7-13
.NTYPE, 7-16
Operand field
definition of, 2-4
valid formats, 2-4
valid terminators, 2-4
Operating procedures (RSTSjRT-11), 9-1
Opera tor field
definition of, 2-3
implicit .WORD if blank, 6-18
valid formats, 2-3
valid terminators, 2-3

Index-10

p
PI
conditional assembly test, 6-46
P2

Permanent symbols, 3-5
overriding with .MCALL, 7-22
Permanent symbol table
list, C-1
P error
.ERROR, 7-18
inconsistent program section attribute, 3-12
multiple definition of local symbol, 3-11
when defining local symbols 6-15
PIC
'
see Position-independent code
Plus sign
addition operator, 3-4
default switch value in RSX command string,
8-5
special character in MACRO-II, 3-2
unary plus operator, 3-4
PNC
argument for .ENABL/.DSABL, 6-15
Position-independent code, G-1
.PRINT directive, 7-18
sumlnary, 7-2
Priority of binary operators, 3-4
Processor differences, table of, 5-3
Prograrn counter operation, 5-1
Prograrn section directives, 6-34
Program sections
context information maintained by MACROII, 6-38
creating, 6-38
default characteristics, 6-41
default names, 6-37
effect of ending with odd address, 6-40
maximum number, 6-37
memory allocation considerations, 6-40
separating code and data, 6-40
sharing code or data, 6-39
P-sect
see Program sections
.PSECT directive, 6-35
assigns attributes to current location counter
3-12
'
default characteristics, 6-41
list of symbolic arguments, 6-35
may confuse automatic local symbol
generation in macro, 7-11
summary, 6-2
terminates local symbol block, 3-10

Q
Q error
.EVEN,6-31
in bad expression, 3-1S
invalid floating point number, 6-28
invalid syntax, 3-3
.ODD,6-32
.TITLE, 6-10
too many arguments in macro call 7--9
Question mark
'
used to generate local symbols, 7-10

R
.RADSO directive, 6-22
See also Radix-SO character set
character equivalents, 6-23
formula, 6-23
inserting special values with angle brackets,
6-23
summary, 6-2
valid characters, 6-22
Radix-SO character set, A-8
See also .RADSO directive
Radix-50 character terminates operator field,
2-3
Radix-SO storage
see also .RADSO directive
temporary with "R, 6-24
Radix control, 6-26
changing default, 3-13
list of temporary operators, 6-27
temporary, 3-13
when to use temporary, 6-26
.RADIX directive, 6-26
discussed, 3-13
restriction if .RADIX 16, 6-26
summary, 6-3
REG
argument for .ENABLj.DSABL, 6-1S
Register symbols, 3-8
default definitions, 3-8
requirements, 3-9
REL
argument for .PSECT, 6-36
Release notes, J-1
Relocatable expressions, 3-14
definition, 3-1S
Relocation, discussion, 4-1

Index-11

Relocation and linking, 4-1
.REM directive, 6-13
summary, 6-3
.REPT directive, 7-21
restriction using label, 7-20
summary, 7-2
Requirements
for direct assignment statements, 3-8
for register symbols, 3-9
R error
invalid redefinition of default register
symbol, 3-9
invalid register symbol, 3-9
.RESTORE directive, 6-41
assigns attributes to current location counter,
3-12
summary, 6-3
terminates local symbol block, 3-10
Right angle bracket
special character in MACRO-II, 3-2
Right parenthesis
special character in MACRO-II, 3-2
RO
argument for .PSECT, 6-35
hR operator, 6-24
RSTS operating procedures, 9-1
RSX-11M
default file specifications, 8-2
file specification, 8-17
file specification switches, 8-6
operating procedures, 8-1
system error messages, 8-18, 8-19, 8-20
under RSTS, 9-1
RT-11
CSI command line format, 9-2
CSI command line options, 9-4
DCL command line format, 9-5
default file specifications, 9-2
operating procedures, 9-2
system error messages, 9-8,9-9,9-10,9-11,
9-12
under RSTS, 9-1
Rubout
cannot follow single or double quote, 6-20
RW

argument for .PSECT, 6-35

s
SAV

Index-12

SAV (cont'd.)
argument for .PSECT, 6-37
.sAVE directive, 6-41
maximum number, 6-41
summary, 6-3
.sBTTL directive, 6-11
generates table of contents, 6-11
summary, 6-3
text appears in listing heading, 6-3
Search order of symbol tables, 3-6
Semicolon
begins comment field, 2-4
in macro argument, 7-8
special character in MACRO-II,. 3-2
used as character string delimiter, 6-21
Separa ting characters
comma, 3-3
space, 3-3
table of, 3-3
SEQ
argument for .LIST j.NLIST, 6-8
Sharing code or data, 6-39
Single quote
component of a term, 3-14
example of concatenation, 7-9
flag in assembly listing, 4-1
for ASCII character storage, 6-19
special character in MACRO-II, 3-2
use to concatenate macro arguments, 7-12
Slash
division operator, 3-4
special character in MACRO-II, 3-2
Space
delimiter in expressions, 3-15
in direct assignment statements, 3-8
in macro argument, 7-8
separating character, 3-3
special character in MACRO-II, 3-2
terminates operator field, 2-3
used in operand field, 2-4
valid in angle bracket arguments, 7-6
Special characters
ampersand, 3-2
angle brackets, 3-14, 6-21, 6-23
asterisk, 3-2
at sign, 3-2, 5-3, 5-4, 5-5, 5-6, 5-8
backslash, 3-2
carriage return, 6-20
circumflex, 3-2, 7-6
colon, 3-1, 6--12, 6-21, 6-22, 6-23

Special characters
colon (cont'd.)
label terminator, 2-2
comIna, 3-2
used in operand field, 2-4
dollar sign
reserved for DIGITAL system symbols,
2-3, 3-1, 3-5
double colon, 3-1, 3-6
label terminator, 2-2
double equal sign, 3-1, 3-6
double equal sign colon, 3-1, 3-6
double quote, 3-2,3-14, 6-19
equal sign, 3-1, 6-21
equal sign colon, 3-1
exclamation mark, 3-2
formfue~ 6-13,6-20
in macro arguments, 7-8
left angle bracket, 3-2, 6-12, 6-21, 6-22,
6-23
left parenthesis, 3-2
line feed, 6-20
minus sign, 3--2
null, 6-20
number or pound sign, 3-2
number sign, 5-6
percent sign, 3-1
defines register symbols, 3-8, 3-9
period, 3-2, 3-15
assign new value to current location
counter, 3-12
current location counter, 3-14
current location counter symbol, 3-7
reserved for DIGITAL system symbols,
2-3, 3-1, 3-5
symbol for current location counter, 3-11
plus sign, 3-2
right angle bracket, 3-2
right parenthesis, 3-2
rubout, 6-20
semicolon, 3-2, 6-21
begins comment field, 2-4
single quote, 3-2,3-14, 4-1,6-19
slash, 3-2
space, 3-2, 3-15
in direct assignment statements, 3-8
terminates operator field, 2-3
used in operand field, 2-4

Special characters
tab, 3-2
terminates operator field, 2-3
used in operand field, 2-4
table, B-1
table of, 3-1
SRC
argument for .LIST j.NLIST, 6-8
Standard for coding programs, E-1
Standards and conventions, 2-1
Starting address of program
specify with .END directive, 6-34
Statement format, 2-1
Subtraction operator, 3-4
SYM
argument for .LIST j.NLIST, 6-8
Symbol control directives, 6-43
Symbols
assumed value of undefined, 3-14
components of a term, 3-14
macro, 3-5
rules, 3-5
order of symbol table searches, 3-6
permanent, 3-5
types, 3-5
user-defined, 3-5
rules, 3-5
Symbol table
list of permanent, C-1

T
Tab
in macro argument, 7-8
special character in MACRO-11, 3-2
terminates operator field, 2-3
used in operand field, 2-4
Table of contents
generated by .SBTTL, 6-11
Terms
components of expressions, 3-14
definition and possible elements, 3-14
Terror
number more than 16 bits long, 3-13
.TITLE directive, 6-10
defaults to .MAIN., 6-10
result if more than one, 6-10
summary, 6-3
text appears in listing heading, 6-3

Index-13

Toe
argument for .LIST j.NLIST, 6-8
TRAP instructions, 5-9
TTM
argument for .LISTj.NLIST, 6-8

.WORD directive (cont'd.)
summary, 6-3

x
"X

u
U error
invalid forward reference, 3-8
.MCALL, 7-23
relationship to .ENABLj.DSABL GBL, 6-14
relationship to .ENABL/.DSABL MCL or
GBL, 6-15
undefined symbol, 3-6, 3-14
Unary operators
"B, 6-27
"C, 6-29
circumflex, 3-4
components of a term, 3-14
"D,6-27
double quote, 6-19
"F, 6-30
minus sign, 3-4
"0,6-27
plus sign, 3-4
single quote, 6-19
table of, 3-4
treatment of multiple, 3-14
use, 3-3, 3-4
"X, 6-27
Undefined symbols
assumed value, 3-14
User-defined symbols, 3-5
rules, 3-5

v
Virtual memory
allocating, F-1

w
.WEAK directive, 6-44
summary, 6-3
supported only in RT -II, 6-45
.WORD directive, 6-18
compared with .FLT2, .FLT4, 6-30
implicit, 2-1, 2-4
implicit if blank operator field, 6-18
operation described, 3-11

Index-14

for temporary hexadecimal radix, 6-27
restriction, 6-28

z
Z error
flags inconsistent instructions, 5-1
table of applicable instructions, 5-3

HOW TO ORDER
ADDITIONAL DOCUMENTATION

From

Call

Alaska, Hawaii,
or New Hampshire

603-884-6660

Rest of U.s.A.
and Puerto Rico*

800-258-1710

Write

Digital Equipment Corporation
P.O. Box CS2008
Nashua, NH 03061

II< Prepaid orders from Puerto Rico must be placed with DIGITAL's local subsidiary (809-7547575)

Canada

800-267-6219
(for software
documentation)
613-592-5111
(for hardware
documentation)

Software Distribution Center (SDC)
Digital Equipment Corporation
Westminster, MA 01473

Internal orders
(for software
documentation)
Internal orders
(for hardware
documentation)

Digital Equipment of Canada Ltd.
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6
Attn: Direct Order desk

617-234-4323

Publishing & Circulation Servo (P&CS)
NR03-1/W3
Digital Equipment Corporation
Northboro, MA 01532

Reader's Comments

PDP-11 MACRO-11 Language
Reference Manual
AA-KX 1OA-TC

Your comments and suggestions will help us improve the quality of our future documentation. Please note
that this form is for comments on documentation only.

I rate this manual's:
Accuracy (product works as described)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

0
0
0
0
0
0
0
0

o
o

0
0
0

o
o
o
o
o

0
0
0

What I like best about this manual:
What I like least about this manual:

I found the following errors in this manual:
Page

Description

My additional comments or suggestions for improving this manual:

Please indi.cate the type of user/reader that you most nearly represent:

o Administrative Support
o Computer Operator
o Educator/Trainer
o Programmer/Analyst
o Sales

Name/Title

o Scientist/Engineer
o Software Support
o System Manager
o Other (please specify)

Dept.
Date

Company
Mailing Address
Phone
10/87

Do Not Tear -

Fold Here and Tape

-- -

--I

OPOSTAGE

NECESSARY
IF MAILED
IN THE
UNITED STATES

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
CORPORATE USER PUBLICATIONS
ML05-5/E45
146 MAIN STREET
MAYNARD, MA 01754-2571

111"1111111'111.1.11111111.1111.1111.11111111111111
Do Not Tear -

Fold Here