Digital PDFs

AA-L676A-TC

November 1981

108 pages

Original

5.0MB

Document:	RSX-11M/M-PLUS Guide to Program Development
Order Number:	AA-L676A-TC
Revision:	0
Pages:	108
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V4.1_Apr83/4_ProgramDevelopment/AA-L676A-TC_gdPgmDevel_198111.pdf

OCR Text

RSX-11 M/M-PLUS
Guide to Program Development
Ord~r No. AA-L676A-TC

RSX-11 M Version 4.0
RSX-11 M-PLUS Version 2.0

digital equipment corporation . maynard, massachusetts

First Printing, May 1979
Revised, November 1981
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 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 on
equipment that is not supplied by Digital Equipment Corporation or its
affiliated companies.

1979, 1981 by Digital Equipment Corporation
All Rights Reserved.

Printed in U.S.A.

The postpaid 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:
DEC
DECnet
DECsystem-10
DECSYSTEM-20
DEC US

DECwriter
DIBOL

EduSystem
IAS
MAS SB US
PDP
PDT
RSTS

RSX
UNIBUS
VAX
VMS
VT

~nmnomn
ZK2053

CONTENTS

Page
PREFACE

vii

CHAPTER 1

THE PROGRAM DEVELOPMENT ENVIRONMENT

1.1
SOFTWARE TOOLS
. • . • . . • • 1-1
1.1.1
Command Line Interpreters
1-1
1.1.2
Text Editors • • • • • • • •
• • • • • • 1-3
1.1. 3
Assembly Language
• • • 1-4
1.1.4
Task Creation
• 1-5
1.1.5
Debugging Aids ••
. . . . . . . . . . . . 1-6
, ,
,
J..J..:>.J.
On-Line Debugging Tool
• • • • • • 1-6
1.1.5.2
Postmortem Dump
• • • • • •
• • 1-7
1.1.5.3
Snapshot Dump • • • •
• • • • • • • • • 1-7
1.1.6
General Utilities
• • • • • • • • • • 1-8
1.1.6.1
Cross-Reference Processor
• • 1-8
1.1.6.2
Peripheral Interchange Program
• • • • 1-8
1.1.6.3
Queuing and Spooling • • • • • •
• • 1-8
1.1.6.4
Librarian Operations • • • • • • • • • • • • • 1-9
1. 2
DIGITAL-SUPPLIED SYSTEM SOFTWARE •
• • • • • • 1-9
1. 2.1
System Directives - Macro Libraries
1-9
1. 2. 2
System Subroutines - Object Libraries
1-10
1. 3
HARDWARE FOR PROGRAM DEVELOPMENT • • • • •
1-12
l. 3.1
Disks • • • • • • • • • • • • • • • •
1-12
1. 3. 2
Terminals • • • • • • • • • • • • • •
1-12
1. 3. 3
Printers • • • • • • • • • • • • • • •
1-12
1. 4
THE PROGRAM DEVELOPMENT PROCESS - OVERVIEW •
1-13
GUIDE TO FURTHER READING
• • • • • • •
1-14
1. 5
~

CHAPTER 2

CREATING MACR0-11 SOURCE FILES

2.1
2.1.1
2.1.2

MACR0-11 SKELETON SOURCE FILE FORMAT •
• • •
.TITLE Directive
• • • • •
• ••
.!DENT Directive •
• •••••
2.1. 3
Author Line
• • •
2.1. 4
Changes Section • • • •
• •
2.1.5
Module Function
• • • • •
• • • • • •
2.1. 6
Some Useful Di rec ti ves •
• • • • •
• •
2.1.6.1
.PAGE Directive
• • • • •
2.1.6.2
.SBTTL Directive • • • • • • •
• •••••
2.1.6.3
.LIST TTM Directive • • • •
2.1.6.4
.NLIST BEX Directive •
• •••
2.1.6.5
.MCALL Directive • • • • • • •
• ••
2.1.6.6
.END Directive • • • • • • • •
• ••
2.1. 7
Local Definitions
• • •
2.1. 8
Local Macro Definitions • • • • • • • • • • • •
Local Data Blocks
• • •
2.1. 9
2 .1.10
Module Function - Detailed • • • • •
• ••
2.1.11
.PSECT Directive • • • • •
• •••••••

iii

2-1
2-3
2-5
2-5
2-5
2-5
2-6
2-6
2-6
2-6
2-6
2-6
2-7
2-7
2-8
2-8
2-8
2-8

CONTENTS
Page
2.2
CREATING A SOURCE FILE FROM A SKELETON FILE • • • 2-9
2.2.1
Performing the Initial Input • • • • • • •
• 2-9
2.2.1.1
Inserting Blank Lines in Text • • • • • • • • 2-9
2.2.1.2
Terminating the Input and the EDI Program
2-10
2.2.2
Creating a Source File from the Skeleton • • •
2-12
2.3
EDITING THE SOURCE FILE • • • • • • • • • • • • 2-12
2.3.1
Displaying Text • • • • • • • • • • • • • • • 2-13
2.3.2
~ocating Text and Positioning the Line Pointer
2-14
2-16
2.3.3
Changing Text
• • • • • • •
• •••
2.3.4
Inserting Code in the Source File
2-18
2.4
GUIDE TO FURTHER READING •
• • • • • • • • • 2-24
CHAPTER 3
3.1
3.2
3.2.l
3.2.2
3.2.3
3.2.4
3.3
3.4
3.5
3.6
3.7
3.8
CHAPTER 4
4.1
4.1.l
4.1.2
4.1.3
4.2
4.3
4.3.l
4.3.2
4.3.3
4.4
4.5
CHAPTER 5
5.1
5.1.1
5.1.2
5.1.3
5.1.4
5.1.5
5.1.6
5.1.7
5.1.8
5.2
5.3
5.4

ASSEMBLING AND CORRECTING A PROGRAM MODULE
PERFORMING A DIAGNOSTIC RUN ON A SOURCE FILE •
3-1
TYPICAL ERRORS ENCOUNTERED DURING ASSEMBLY • • • • 3-2
The MACR0-11 Error Code A
• • • • • • • • • 3-2
The MACR0-11 Error Code U
• • • • • • • • • 3-3
The MACR0-11 Error Code Q
• • 3-4
The MACR0-11 Error Code E
• • • 3-4
GENERATING A PROGRAM MODULE AND A LISTING • • • • 3-4
EXAMINING A LISTING AT THE TERMINAL
• • • • • 3-6
GENERATING A CROSS-REFERENCE LISTING •
• • 3-7
SPOOLING A COPY OF LISTINGS
• • • • •
• 3-8
CLEANING UP THE DISK DIRECTORY •
3-9
GUIDE TO FURTHER READING • • •
3-10
BUILDING AND TESTING A TASK
CREATING A TASK IMAGE
• • • •
• •
Supplying a Single Object Module •
• • •
Supplying Multiple Object Modules
• • • •
Using the· Fast Task Builder
• •
TASK BUILDER DEFAULTS • • • • • • • • • • • • • •
GENERATING A MAP AND A GLOBAL CROSS-REFERENCE
LISTING
• • • • • • • • • • • • • •
Requesting a Map and a Global Cross~Reference
Listing • • • • • • • • • • • • • • • • • • • •
Examining the Map at the Terminal
• • • • • • •
Requesting a Full Map • • • • • • • • • • • • •
RUNNING THE TASK AND CORRECTING TYPICAL ERRORS • •
GUIDE TO FURTHER READING • • • • • • • • • • • • •

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

USING DEBUGGING AIDS
THE ON-LINE DEBUGGING TOOL
5-1
Including ODT in a Task
5-1
Preparing to Use ODT •
• • 5-2
Setting up the Task
• • • • • • 5-2
Relocation Registers • • •
• • 5-2
Examining Locations
• • • • • •
5-4
Setting Breakpoints Within the Task
5-6
Changing the Contents of Locations with ODT
5-7
Error Conditions and Terminating Task Execution 5-8
POSTMORTEM DUMP • • • •
• • • • • 5-9
THE SNAPSHOT DUMP
• • • • • • • •
• • 5-9
GUIDE TO FURTHER READING •
• • • • 5-10

CONTENTS
Page
CHAPTER 6
6.1
6 .1.1
6.1. 2
6.2
6.2.1
6.2.2
6.2.3
6.2.4
6.3
6.3.l
6.3.2
6.3.3
6.4
CHAPTER 7
7.1
7.2
7.2.l
7.2.2
7.2.3
7.2.4
7.2.5
7.3

CREATING AND USING PROGRAM LIBRARIES
CREATING AND USING A MACRO SOURCE LIBRARY
• • 6-1
Creating the Macro Library • • • • • • •
• 6-1
Using the Macro Definitions from the Library • • 6-3
CREATING AND USING AN OBJECT MODULE LIBRARY
• 6-4
Creating the Object Module Library • • • • • • • 6-4
Using the Object Modules from the Library • • • 6-6
Using the Library to Resolve Undefined Global
Symbols
• • • • • • • • •
• • 6-8
Dual Use of the Library
• • • • 6-8
MAINTAINING USER LIBRARIES
6-9
Adding Modules to a Library
6-9
6-10
Replacing a Module in a Library
Obtaining Information about a Library
6-11
6-12
GUIDE TO FURTHER READING • • • • • • • • •
FORTRAN IV PROCEDURES
OVERVIEW OF PDP-11 FORTRAN IV
FORTRAN IV PROGRAM DEVELOPMENT
Creating the Source File • •
Performing a Diagnostic Run
Creating an Object Module
Creating a Task Image
Running and Debugging a Task
GUIDE TO FURTHER READING • • •

• • • • • •
PROCEDURES

. .
. .

7-1
• 7-2

.
.

• • • •
•
•

INDEX

7-2
. . 7-3
. . 7-5
• • 7-5
• 7-6
• • 7-9
INDEX-1

EXAMPLES
EXAMPLE 2-1
2-2
2-3
2-4
2-5
5-1
5-2
6-1
7-1

Sample Source File Skeleton • • • •
Creating the Skeleton File SKEL.MAC
••••
Source Code for FILE.MAC • •
• ••••••
Source Code for FILEA.MAC
• • • • •
• •••
Source Code for FILEB.MAC • • • • •
Memory Allocation Synopsis from Task BUG Map • •
Portion of Assembly Listing for NUMA
MACR0-11 Library Source Definitions
• •
•
FORTRAN IV Sample Source Code AVERAGE.FTN

• 2-4
2-11
2-19
2-21
2-23
• 5-3
• 5-4
• 6-2
• 7-3

FIGURES
FIGURE

1-1
2-1
2-2

• .
The Program Development Process
MACR0-11 Source File Format
MACR0-11 Source Statement Format

.
i-i 3
• • 2-2
. . 2-3

TABLES
TABLE

1-1
1-2
3-1

DIGITAL-Supplied Macro Libraries •
DIGITAL-Supplied Object Libraries
Terminal Output Control Commands •

• • 1-9
1-11
• • 3-7

PREFACE

MANUAL OBJECTIVES
The RSX-llM/M-PLUS Guide to Program Development introduces the program
development environment on the RSX-llM and RSX-llM-PLUS systems.
It
provides a synopsis of the information immediately useful in getting
started in the program development process. The book also gives an
overview of the software environment and some guidelines on program
design.

INTENDED AUDIENCE
This book is intended for the person who is already familiar with the
general, basic operations of an RSX-llM/M-PLUS system: ga1n1ng access
to the system, using the terminal and related devices, and requesting
simple Executive services through the command interface. The greater
part of the book addresses assembly language programming because that
language is the one provided with all systems.
Included is one
chapter summarizing the program development
procedures
for
a
high-level language, PDP-11 FORTRAN IV.
However, most of the topics
covered for the assembly language programmer -- using a text editor,
creating an executable image, using library facilities -- apply to
programmers using any computer language.
If you are not familiar with the general, basic operations of the
system, you should first read the Introduction to RSX-llM and
RSX-llM-PLUS. This book describes how to access the -System, use a
terminal, and use the system command interface.

STRUCTURE OF THIS DOCUMENT
This guide is meant to be read as you use the system.
For this
reason, the examples are presented in an order that you can follow at
the terminal. Rather than demonstrate the complexity of the system,
these
examples
are
designed to demonstrate practical program
development operations.
This guide is also meant to be used with other manuals in your
documentation set.
Toward this end, a selection of further reading
material is listed in the last section of each chapter. By using this
guide, then, you can become increasingly familiar with other, more
advanced manuals until you need not refer to this introductory text
except as a refresher.

vii

PREFACE
The information in this book is
follows:

organized

into

seven

chapters,

•

Chapter 1, The Program Development Environment, introduces the
software and hardware on which you develop programs.

•

Chapter 2, Creating MACR0-11 Source Files, describes how to
create an assembly language source program using a skeleton
file and text editor.

•

Chapter 3, Assembling
describes how to use
object module.

•

Chapter 4, Building and Testing a Task, describes how to use
the Task Builder to link object modules to create a loadable
task image.

•

Chapter 5, Using Debugging Aids, introduces debugging aids and
discusses how to use them.

•

Chapter 6, Creating and Using Program Libraries, describes how
to create and maintain a library of macro source statements
and a library of object module subroutines.

•

Chapter 7, FORTRAN IV Procedures, briefly
FORTRAN IV program development process.

and Correcting a Program
Module,
the MACR0-11 Assembler to generate an

introduces

the

ASSOCIATED DOCUMENTS
As mentioned above, documents recommended for further reading are
listed at the end of each chapter.
In addition, the RSX-llM
Information Directory and Index and the RSX-llM-PLUS Information
Directory and Index list ancf"" describe all the documents in the
documentation sets for each system.

CONVENTIONS USED IN THIS DOCUMENT
Throughout this book, symbols and other notation conventions are used
to represent keyboard characters, to convey textual information, and
to otherwise ease the presentation of material.
The symbols and
conventions used are explained below.
Meaning

Convention

A 1- to 3-character symbol indicates that
you press a key on the terminal;
for
example, ~ indicates the RETURN key and @
indicates the LINE FEED key.
The symbol
~
indicates that you must
press
the
key labeled CTRL while you
simultaneously press another
key;
for
example,
~
indicates the CTRL and 0
keys.
In examples,
this
control
key
sequence is shown as Ax;
for example, AO
indicates the result of
typing
~
because that is how the system echoes many
control key combinations.

viii

PREFACE
Meaning

Convention

The circumflex character, appearing with
another character, represents the system
response to receiving a control character
(CTRL/n).
For exampie, when you type ~ne
CTRL/Z combination while running some system
tasks, the system echoes "Z.
(On some
terminals, the circumflex is replaced by the
up-arrow Ct) character.)
"print" and "type"

As these words are used in the text,
system prints and the user types.

the

MCR>

This is the explicit prompt of the Monitor
Console Routine (MCR), one of the command
interfaces used on RSX-llM and RSX-llM-PLUS
systems.

DCL>

This is the explicit prompt of the DIGITAL
Command Language (DCL) , one of the command
interfaces used on RSX-llM and RSX-llM-PLUS
systems.

A right-angle bracket is the system command
Whenever
interface
prompting character.
user
task
control is returned to the
terminal and you can type input, the prompt
appears.
RSX-llM and RSX-llM-PLUS systems can have
one
or
more command line interpreters
(CLis). All systems include MCR and many
systems include DCL.
To determine which
command interface your terminal has, type
the CTRL/C combination and the explicit
prompt (either MCR> or DCL>) will appear.

red ink

Color-highlighted information in examples
indicates
information
that
you
type.
Information
in
examples
not
in
the
contrasting
color
constitutes
computer
output.
Commas in commands separate
parameters.
They also indicate positional entries on a
command line.
A period in a file specification
the file name and the file type.

separates

specification
A semicolon
in
a
file
separates the file type and file version
number.

CHAPTER 1
THE PROGRAM DEVELOPMENT ENVIRONMENT

This chapter introduces the software and hardware that you typically
need
to
develop
programs
on
an
RSX-llM
or
RSX-llM-PLUS
multiprogramming system.
Its aim is to orient you to the environment
in which you will be working.
The remaining chapters in the guide
further describe and illustrate how to use the tools and facilities
introduced in the following sections.

1.1

SOFTWARE TOOLS

RSX-llM and RSX-llM-PLUS make software tools available as executable
entities called system tasks.
The system tasks include one or more
editors, the MACR0-11 Assembler, the RSX-llM/M-PLUS Task Builder,
several aids to debugging, and a number of utility tasks. Your system
may also
include one or more high-level language compilers or
interpreters.
These elements combined form the program development
environment.
In general, the system manager makes these tasks
accessible to you by installing them on the system.l
To invoke a task, you need not know where the task resides.
The
RSX-llM and RSX-llM-PLUS operating systems offer two command line
interpreters for communicating with the system and
invoking system
services.
These are the Monitor Console Routine (MCR) and the DIGITAL
Command Language
(DCL).
MCR is included in all RSX-llM/M-PLUS
systems, whereas DCL is optional.
Each terminal is set to recognize
either MCR or DCL upon logging in.

1.1.1

Command Line Interpreters

RSX-iiM/M-PLUS systems can have one or more command line interpreters
(CLis).
All systems include MCR.
Many systems include DCL, and some
systems include user-written CLis.
Both MCR and DCL include commands
to invoke most system tasks and utilities to se~ and display certain
system characteristics.
In general, MCR commands invoke tasks such as
PIP, a utility used to manipulate files (for example, copying them).
DCL commands specify actions directly, as in the COPY command or the
TYPE command.
MCR is the fundamental CLI for the RSX-llM/M-PLUS operating systems.
From an MCR terminal, tasks installed with names in the form ••• abc

1. On systems with fewer resources, some tasks may not be permanently
installed.
Such systems may use the "flying install" feature, or
require you to use some form of the RUN command to
install system
tasks temporarily.
See your system manager for further information.
This manual assumes that all tasks are installed.

1-1

THE PROGRAM DEVELOPMENT ENVIRONMENT
can be invoked simply by typing the abc portion of the task name.
Most system tasks and utilities are installed with names of that form.
MCR also provides commands to set and display certain system and
device characteristics.
MCR provides the most direct interface with
the operating system, either RSX-llM or RSX-llM-PLUS.
DCL is an optional CLI included in most systems with heavy terminal
use.
Commands in DCL are English-like words and follow well-defined
syntax rules.
You are not required to use the full form of DCL commands, however.
Usually, you need type only the command elements required to form a
unique command. Most examples in this manual are in full
format for
clarity, but you should keep in mind that unless you are keeping a
copy of your terminal activity for possible future reference, you can
use much shorter forms than those in the examples. You will always be
able to shorten any command or qualifier to four characters.
Most
commands and qualifiers can be entered with even fewer characters.
DCL prompts you for all required command elements.
If you do not
understand a prompt, type in a question mark (?). DCL will print HELP
text explaining the format and function of the command and then
reprompt you for required input.
DCL is actually a CLI task that translates DCL commands into MCR
commands for execution by the system.
The DCL SET DEBUG command
displays the MCR translation for any DCL command on your terminal
without executing the command. Depending on the kind of use you make
of your system and the nature of your system, you may find
it more
convenient to use one CLI or the other, or both. All nonprivileged
system functions are available directly from DCL, but some privileged
functions are not. All program development facilities and all common
utility functions are available from DCL.
Your terminal is set to either MCR or DCL.
You can determine which by
typing a CTRL/C.
The explicit prompt identifies the CLI.
You can change from DCL to MCR, or vice versa, at any time.
The DCL
command SET TERM MCR switches you from DCL to MCF.
The MCR command
SET /DCL=TI:
switches you from MCR to DCL.
In addition, you can
enter a single DCL command from an MCR terminal with the DCL command
or enter a single MCR command from a DCL terminal with the MCR
command.
For example, the following commands have the same effect:
DCL>MCR PIP TI:=filespec
MCR>DCL TYPE f ilespec
NOTE
As shipped, DCL includes the SET DEBUG
and MCR commands.
These commands may be
disabled at some installations.
As
shipped, DCL also rejects any commands
it does
not
recognize,
but
some
installations may have enabled a feature
that allows any command unrecognized by
DCL
to
"fall through"
to MCR for
interpretation. See your system manager
for more information on the limits of
DCL at your installation.
The RSX-llM/M-PLUS Guide to Program Development concentrates on the
actual program development process and not on DCL or MCR.
However,
1-2

THE PROGRAM DEVELOPMENT ENVIRONMENT
some of the program development facilities require different commands
in DCL and MCR.
In particular,
the commands for
the MACR0-11
Assembler, the Librarian Utility Program, and the RSX-llM/M-PLUS Task
Builder are different.
While this will probably not interfere with
your use of the system, it may be confusing at first.
The programming
demonstrations in this manual are documented first using DCL commands,
then once again using MCR commands.
This duplication enables you to
see the differences between DCL and MCR.

1.1.2

Text Editors

A text editor is the means by which you create a
source code file.
Most RSX-llM/M-PLUS systems include the Line Text Editor EDI and the
DEC Standard Editor EDT.
Both of these editors are
interactive
editing programs that enable you to enter ASCII text at a terminal and
store the text in a disk file.
They also let you access text in a
disk file;
examine, delete, and change text;
and insert new text.
The disk file is then used as input to other tasks in further steps of
the program development process.
EDI is introduced
in this manual and further documented
in the
RSX-llM/M-PLUS
Utilities
Manual.
EDT
is
introduced
in the
introduction to R~X-llM and RSX-llM-PLUS and further documented in the
EDT Editor Manual.
You can use EDI or EDT or some other editor found at your installation
with the examples in this book.
DCL users invoke an editor in the
following manner:
DCL>EDIT/EDI f ilespec
DCL>EDIT/EDT filespec
MCR users invoke an editor in the following manner:
MCR>EDI f ilespec
MCR>EDT f ilespec
In both DCL and MCR, the EDT command line can
elements to invoke special features of EDT.

include

other

command

EDI may be the only editor available on smaller systems.
EDI is a single-pass, line-oriented editor.
In its typical mode of
operation, called block mode,
it reads from a disk file a block of
text -- as much text as will fit in
its text buffer.
You perform
editing operations on text in the EDI buffer.
After editing text in
the buffer, you request the editor to renew the buffer with the next
block of text.
To change text in a previously edited buffer, you must
close the current editing session, open the file again by reinvoking
EDI, and read from the beginning of the file to the block of text.
Editing functions are on a line-by-line basis. New text is
inserted
into the buffer one line at a time.
Current text in the buffer is
changed by your locating the line or lines on which EDI must make the
change.
To preserve currently existing text, EDI performs all processing on a
temporary copy of the file being edited. As you renew text in the
buffer, EDI writes the edited text to a temporary file.
This action
has two advantages and one drawback.
First, the current version of
your text file is always left intact.
Second, when you exit from the
editing session, you have the option of storing the edited file in a
1-3

THE PROGRAM DEVELOPMENT ENVIRONMENT
new version of the old file or of creating an entirely new file (that
is, one with a different name and version number). The drawback of
the temporary file is that, in the event of a system crash, edits you
are making are lost. After a crash, the new version of the file has a
zero length because EDI did not have time to preserve the edits from
the temporary file.

1.1.3

Assembly Language

RSX-llM and RSX-llM-PLUS systems support many programming languages.
However, the one language distributed on all systems is the PDP-11
assembly language, MACR0-11. MAC is the task that assembles MACR0-11
language files.
It accepts a disk source input file in ASCII format
and can create a relocatable object module and a listing file of the
source language.
The object module contains all the object records
and relocation information needed to link with other object modules.
All symbol definition done by the assembler has a base address of
zero. The allocation of virtual addresses and relocation is left for
the task-building process.
DCL users invoke MAC with the MACRO command.
with the MAC command.

MCR

users

invoke

MAC

Source input to MACR0-11 consists of free-format statements, each line
of input containing a single statement. Input statements are either
PDP-11 instructions, MACR0-11 Assembler directives, macro calls, or
di~ect assignments.
St~tements can contain labels to allow control to
change locally {within the module) or to enable control to be passed
between modules (globally) •
Source input usually contains user-defined symbols, which are either
local or global. A local symbol is defined in the current source file
and is referenced only within the current file. A global symbol is
defined in one source file but can be referenced in one or more other
source files.
The assembler allows you to use both local and global symbols as
labels for statementse When a global symbol appears as a lab~l, the
related statement is referred to as an entry point (that is, a point
at which other modules can transfer control to the current object
module). You can use local symbols as statement labels to define
points to which control transfers within an object module.
The assembler evaluates all local symbol definitions in a source file.
Any symbols remaining undefined are classified as global. Thus, after
an assembly, all local symbols are assigned relative locations, but
the moaule may contain references for which definitions must be
supplied.
The resolution of these references is left for the
task-building process.
Assembler directives in a source file allow you to perform
such as the following:
•

Program sectioning

•

Listing control

•

Conditional assembly

•

Data storage

operations

Program sectioning allows code or data within an object module to be
overlaid by, or concatenated with, code or data in other object
modules or in noncontiguous locations within the same module. Program
1-4

THE PROGRAM DEVELOPMENT ENVIRONMENT
sectioning is especially useful where convenient physical ordering
differs
from
logical
reference
ordering
{for
example,
in
table-generating macro statements). Listing control directives enable
documentation features such as listing-heading lines, listing-page
formatting, and table of contents generation. Conditional assembly
directives allow optional omission or inclusion of lines of code or
user=defined symbols. Using data storage directives, you can control
the size and contents of data areas.
Special statements called macro directives allow you to reference a
predefined symbol that causes the assembler to expand a single line
source statement into multiple lines of code or data and insert the
assembled result in the object module.
Such macro symbols are
typically used for recurring coding sequences. The insertion of the
code sequence occurs at each point you refer to the macro symbol.
Definitions for such macro symbols can occur in the source file itself
or can reside in a macro library. Generally, you place infrequently
used macro definitions in the source file that invokes them, and store
frequently used macro definitions in a macro library. The Executive
and file-processing services are made available to the program through
macro symbols that are defined in a DIGITAL-supplied macro library.
MACR0-11 is a 2-pass assembler. During the first pass, the assembler
groups all symbols as either local or global, performs statement
generation, locates all macro symbols, and, if necessary, reads the
macro definitions from libraries. At the end of pass 1, the assembler
must have processed all local references (such as all undefined global
symbols) that are to be resolved by the Task Builder.
During the second pass, the assembler actually generates the object
module and listing files, flagging with an error code in the listing
file those source statements containing errors. If you requested a
cross-reference listing of symbols, the assembler also generates a
request for the Cross-Reference Processor (CRF) to create the proper
information. {CRF is introduced in Section 1.1.6 in this chapter.}
The MACR0-11 listing file provides both documentation for the module
and a tool for debugging the code. As a reference aid, the assembler
generates and includes line numbers in the listing for each statement
in the source file. It also maintains a current location counter for
each program section defined in the source file.
In addition, the
listing includes a symbol table showing symbols, their attributes, and
their values if known at assembly time.
The location counter value given in the listing file is vital in
debugging because it provides the offsets into the module for each
program section. An offset, combined with the base load address for a
program section (from the Task Builder map), allows you to access
locations in the memory-resident task image during debugging.

1.1.4

Task Creation

The Task Builder (TKB) on RSX-llM and RSX-llM-PLUS systems is a
multiple-purpose tool.
It allows you to create a loadable entity
(called a task image) , define and structure a shared area of memory
(called a resident common) , and arrange shareable routines to reside
in memory (called resident libraries). TKB has many complex aspects
but this guide introduces only its most frequent usage: building a
task image.
DCL users invoke TKB with the LINK command.
with the TKB command.

MCR users invoke the

To build a task image, TKB accepts, as basic input, the
1-5

output

TKB
of

THE PROGRAM DEVELOPMENT ENVIRONMENT
language processor: an object module or multiple object modules. TKB
can optionally generate a file of executable code (the task image), a
file of memory allocation information (a map), and a special file of
symbol definitions used in constructing the task
(the
symbol
definition file).
The task image, residing on disk, is in a format
suitable to be loaded into memory and executed.
If you generate a
cross-reference listing, the listing itself contains only global
symbols and is appended to the map file.
In creating a task image, TKB's primary functions are linking, address
binding, and building system data structures.
Linking involves
resolving global references in all object modules and resolving
program section references among all object modules. Address binding
is assigning virtual address space within the task.
Building system
data structures involves creating elements that the system requires to
load the task image into memory and to execute the task.
To resolve
global symbols that are not defined in any of the input object
modules, TKB searches any object libraries you specify and, as a
default condition, searches the system object library.
Because the PDP-11 processor can address only 32K words
(the address
limit of 16 bits) at any one time, a task cannot reference more than
32K words at a time.
However, if you use certain advanced programming
techniques, TKB allows a task to access more code or data than can fit
within the address limits.
Techniques to overcome the addressing
limits include the following:
•

Overlaying segments of a task
code

with

either

disk-resident

mcmory~resident

•

Mapping to different regions of memory
limits of the current task space

outside

the

physical

Because these are advanced techniques, they are not shown in the
examples in this guide. For more information on themj refer to the
RSX-llM/M-PLUS Task Builder Manual.
The memory allocation information, or map, produced by TKB shows you
how program sections are arranged in task memory (their starting
virtual addresses and extents on mapped systems and physical addresses
and extents on unmapped systems), what contributions are in a program
section, any undefined symbols, and the optional cross-reference
listing
of global symbols.
You can use the starting virtual
addresses, combined with the current location counter values (provided
by
the assembler), as offsets to access locations within the
memory-resident task during debugging.

1.1.5

Debugging Aids

This section introduces the debugging aids described in this guide and
provided
with
RSX-llM
and RSX-llM-PLUS systems to assist in
identifying faulty code.

1.1.5.1 On-Line Debugging Tool - The On-Line Debugging Tool
(ODT)
allows interactive control of task execution. You specify to TKB that
you want a debugging aid included in a task.
TKB inserts into the
task the module LB:[l,l]ODT.OBJ.
When you run a task that includes ODT, execution begins at the ODT
transfer address rather than at the task starting address. Therefore,
ODT gains control and allows you to type special commands that
establish base addresses and that set breakpoint locations within the
1-6

THE PROGRAM DEVELOPMENT ENVIRONMENT
task. After you tell ODT to begin task execution, ODT saves the
instructions at breakpoint locations you specified and replaces them
with PDP-11 breakpoint (BPT) instructions. Upon encountering a BPT
instruction in the task, the Executive passes control to ODT at its
breakpoint routine. ODT saves task registers in special locations,
restores instructions to the breakpoint locations, and transfers
control to the user task terminal. By typing ODT commands, you can
examine and alter any instructions or data within task memory.
ODT also enables the BPT synchronous system trap (SST) entry point in
the task. If a task generates an SST error, ODT gains control at its
SST entry point, prints a notice at the user terminal, and passes
control to the terminal. You can use the ODT commands to discover the
cause of the error, correct it, and perhaps continue executing the
task.
To successfully modify instructions, you must have a
thorough
understanding of the PDP-11 instruction set. If you are programming
in a high-level language, you should avoid interactive debugging
whenever possible.

1.1.5.2 Postmortem Dump - Postmortem Dump (PMD) is an installed task
that is directed by the Executive to extract run-time related data
about a terminated task, format it, and request a printed listing.I
Normally, when a task generates a synchronous system trap (SST), such
as that caused by an improper reference to an odd address or a
reference to a nonexistent memory location, the Executive tries to
transfer control to an SST entry point defined by the task.
If the
task does not have an SST routine defined for the particular type of
trap, the Executive aborts the task.
To terminate the task, the Executive performs an abort operation and
notifies the Task Termination Notification program (TKTN). TKTN
displays, on the user terminal, the reason for the termination and the
contents of the task registers.2 Without PMD, you can acquire no
further information about the task.3
By enabling Postmortem Dumps for a task that itself does not handle
synchronous system traps, you tell the Executive to supply more data
at abnormal task termination. That is, the Executive follows the
abort procedure and, in addition, creates a request for PMD to create
the dump. PMD examines system and task structures to preserve status
and run-time data, reads the task image from memory, and writes it to
disk in a readable format. PMD then queues a request to print the
file containing the dump data, after which the Executive completes the
task abort procedurea

1.1.5.3 Snapshot Dump - The snapshot dump {$SNAP), also using PMD,
generates an edited dump of a running task. Because the snapshot dump

1. PMD requires
termination and
generation time.

task
for
abnormal
that the Executive option
device-not-ready messages be selected at system

2. The TKTN task must be
messages.

installed

the

system

display

the

3. Commands exist that allow you to fix a task in memory and
physically examine the contents of the task image. However, this is a
complicated procedure and beyond the scope of this book.
1-7

THE PROGRAM DEVELOPMENT ENVIRONMENT
requires you to insert special code
(for example, the $SNAP macro
call)
in a task, it is more difficult to use than PMD.
However, by
inserting the snapshot dump code in the task, you can choose the
location at which the dump is created and select the extent and format
of the dump.
In addition, you can generate the dump from more than
one location and,
therefore, as many times as needed during task
execution.
It is often useful to include debugging facilities such as $SNAP in
your task based on defining a conditional variable. To include the
facility while you are debugging, simply define the variable. You can
then omit the facility by reassembling the code with the conditionaJ
variable undefined.

1.1.6

General Utilities

This section introduces the general-purpose utility programs that
mentioned in this guide.

are

1.1.6.1 Cross-Reference Processor - The
Cross-Reference
Processor
(CRF)
is an installed task that receives requests from MACR0-11 and
TKB to generate cross-reference listings of symbols. CRF generates a
specially formatted file containing the cross-reference data and
appends that file to the assembler listing or the task map file.
Therefore,
if you request a cross-reference listing of symbols, it
always appears at the end of a listing or map file.
A request for the ser~ices of the Cross-Reference Processor is
included in your command line to the MACR0-11 Assembler and TKB. From
DCL, use the /CROSS REFERENCE qualifier to the MACRO and LINK
commands.
From
MCR, use the /CR switch on the proper file
specification in the MAC and TKB command lines.

1.1.6.2 Peripheral Interchange Program - The Peripheral
Interchange
Program
(PIP) is the standard DIGITAL program for performing file and
device-related functions:
transferring files from one medium or User
File
Directory
(UFD}
to another, obtaining directory listings,
renaming files, deleting files, and changing file protection codes.
PIP handles all Files-11 file-structured devices and is used for
almost all file operations.
The noteworthy exception
to
PIP
capabilities is certain PDP-11 Record Management Services (RMS-11)
file operations, for which DIGITAL supplies special RMS-11 utilities.
MCR users access PIP services through various PIP commands.
DCL
includes the DIRECTORY, DELETE, PURGE, COPY, RENAME, TYPE, APPEND, and
SET PROTECTION commands, which give you transparent access to PIP
services.

1.1.6.3 Queuing and Spooling - RSX-llM
and
RSX-llM-PLUS
systems
differ in the manner in which each provides queuing and spooling
facilities, but both systems generally offer the same user functions.
Almost all program development tasks automatically generate requests
to the proper queuing tasks to print an ASCII output file on the
system's default printer.
If your installation has the proper tasks
installed, the spooling task dequeues such requests and prints the
requested output file on the proper device. You should consult the
system manager at your installation for the exact details~

1-8

THE PROGRAM DEVELOPMENT ENVIRONMENT
1.1.6.4 Librarian Operations - The Librarian Utility Program
(LBR)
can create and maintain specially formatted library files on disk:
one for macro call definitions and one for object module subroutines.l
The MACR0-11 Assembler and TKB can access these library files and
extract the proper code from them.
Libraries are convenient to use
because they encourage sharing of code, provide faster access to
multiple modules (only one file need be opened and closed), occupy
less space than the equivalent number of separate modules, and impose
a coding standard. The library files you create using LBR are in the
same format as those that DIGITAL supplies with the operating system.
DCL includes a series of LIBRARY commands that give you access to LBR
services. MCR users access LBR services through various LBR commands.

1.2

DIGITAL-SUPPLIED SYSTEM SOFTWARE

DIGITAL supplies system software in two standard library formats:
macro call definitions and object module subroutines. You use macro
libraries as input to the assembler and object libraries as input to
TKB- The following two subsections describe these system libraries=

1.2.l

System Directives - Macro Libraries

DIGITAL makes available system directives and system-related features
through calls; definitions for these calls reside in macro libraries.
The libraries are stored in a predefined file area known as a User
File Directory or UFD.
The UFD is [1,1] on the system library device
(referenced explicitly by the device-independent designation LB:).
Table 1-1 summarizes the macro libraries that DIGITAL supplies.
Table 1-1
DIGITAL-Supplied Macro Libraries
File Name and Type

Description of Contents

RSXMAC.SML

System Macro Library.
Contains the macro
definitions for all RSX-llM and RSX-llM-PLUS
system, directives and File Control Service
(FCS) file-processing calls. Default iibrary
for the assembler.

EXEMC.MLB

Executive Macro Library.
Contains the symbol
and offset definitions for the Executive data
structures.

RMSMAC.MLB

PDP-11 Record Management Services
(RMS-11)
Library. Contains the definitions for RMS-11
calls for sequential and relative file I/O.
If your system has the optional RMS-llK
software,
this library will also contain
calls for indexed file operations.

1. The Librarian can also create a universal library file
any of one file type you prefer.
1-9

contain

THE PROGRAM DEVELOPMENT ENVIRONMENT
To use these libraries, you should follow the specific procedures
described in the system documentation. Typically, you supply in the
source code the appropriate names of the modules as parameters of a
.MCALL MACR0-11 directive.
This action tells the assembler to
generate an entry for that call in its macro symbol table and to
search the appropriate library for the definition of the macro symbol.
In translating source code, the assembler first checks for macro
symbols.
When the assembler finds an operator on a source line, it
searches its macro symbol table to see whether the operator is a macro
symbol.
An operator is any PDP-11 operation code, MACR0-11 Assembler
directive, or macro symbol. If the operator is a macro symbol, the
assembler applies the local definition for the macro symbol or
extracts the definition from a library you specified or from the
system library.
By searching the user-supplied library first, the
assembler allows you to tailor the definitions of system macro calls
or PDP-11 instructions. MACR0-11 assembles the macro definition with
any accompanying parameters and includes the assembled code in the
object module.
As a result, the proper code is included from a
library.
Through the use of the system macro library, you are provided with the
code that enables a task to issue system directives and to obtain the
File Control Services (FCS). These services enable a task to obtain
run-time and system information, perform input/output functions,
communicate with other tasks, manipulate logical and virtual address
space, control execution, and properly exit. In general, most RSX-llM
and RSX-llM-PLUS features are m~d~ available to a task through macro
calls to the system macro library.
For the system macro library
RSXMAC, you need not designate the library name to the assembler.
As
a default condition, the assembler automatically searches the system
macro library.
Through the use of the Executive macro library EXEMC.MLB, you are
provided with code to allow software to refer to offsets within the
Executive and system definitions of the Executive data structures.
This library is provided for assembling privileged tasks and for
incorporating specially written device drivers into the system.
(This
topic is covered fully in the RSX-llM-PLUS Guide to Writinq an I/O
Driver, the RSX-llM ~ to Writing ~ I/O Driver, and~ the
RSX-llM/M-PLUS Task Builder Manual, and is not mentioned further in
this guide.)
The Record Management Services library RMSMAC.MLB is provided to
support file and record access to RMS-11 data.
RMS-11 is an
upwards-compatible extension qf FCS and offers more functions such as
indexed sequential (keyed) access to data. You include the RMS-11
macro symbols in the source code and supply to the assembler the name
of the RMS-11 library to use. The assembler extracts the definitions
from the library and includes the RMS-11 code in the object module.

1.2.2

System Subroutines - Object Libra~ies

On RSX-llM and RSX-llM-PLUS systems, system object libraries provide
general utility functions and special-purpose Executive features.
These libraries, like the macro libraries, reside in UFD [1,1] on the
system library device (LB:). Table 1-2 lists and describes the object
libraries that DIGITAL supplies.

1-10

THE PROGRAM DEVELOPMENT ENVIRONMENT
Table 1-2
DIGITAL-Supplied Object Libraries

File Name and Type

Description of Contents

SYSLIB.OLB

System Library. Gontains register handling,
arithmetic,
data
conversion,
output
formatting, File Control Services (FCS), and
FCS command line processing subroutines.
Optionally contains a set of real-time data
acquisition routines.
Default library for
TKB.

VMLIB.OLB

Virtual Memory Management Library. Contains
dynamic memory, core allocation, virtual
memory, and page management subroutines.

EXELIB.OLB

Executive Library. Contains the definitions
of the Executive symbols.

ANSLIB.OLB

ANSI Ma~netic Tape Library.
On RSX-llM
systems
only,
an alternate version of
SYSLIB. Contains ANSI magnetic tape label
handling routines and FCS big buffering
support.
(On RSX-llM-PLUS
systems
and
systems
with limited disk space, these
routines are in SYSLIB.)

RMSLIB.OLB

Services
Library.
Record
Management
Contains the routines for sequential and
relative (RMS-11) and, optionally, indexed
(RMS-llK) I/O.

FOROTS.OLB
F4POTS.OLB

FORTRAN IV and FORTRAN IV-PLUS
Library
(optional). The Object Time System (OTS)
and other routines for the PDP-11 FORTRAN IV
language processors.

You typically include system object routines in a task by specifying
the routine name as the operand of a CALL macro or Jump To Subroutine
(JSR) instruction in the source code. The language processor, at the
point of the reference, generates the instructions to transfer control
to the external subroutine. The name of the subroutine is left as an
externally-defined global symbol for TKB to resolve.
To ensure that subroutines are placed in the task image, TKB, as a
default operation, searches the library SYSLIB.OLB for routine names
that remain undefined after the search of
any
user-specified
libraries.
TKB attempts to match the undefined global reference (the
subroutine name in a module) with an entry point name in the SYSLIB
library.
~~en
it finds a match, TKB extracts a copy of the module
defining the symbol from SYSLIB and inserts the subroutine in the task
image.
Any further references to that symbol in the task are defined
by the subroutine, and TKB need not add any code to resolve further
references.
If a module references routines that are in an object library other
than SYSLIB.OLB, you must specify that library when you build the
task. TKB performs the same search operations on user-supplied
libraries as it does on the default search of SYSLIB. TKB also
searches any user-specified libraries in the order in which you
specify them before it searches the system library.

1-11

THE PROGRAM DEVELOPMENT ENVIRONMENT
1.3

HARDWARE FOR PROGRAM DEVELOPMENT

Basically, you need three types of devices for program development:
disks, terminals, and printers. This section briefly introduces these
devices and tells where you can find further information. In general,
each hardware unit on the system is delivered with relevant hardware
documentation that provides programming information in addition to
operational instructions. Your installation should have a library of
such hardware documentation. If you are not writing any specially
tailored code for these devices, the system software handles them
transparently through such mechanisms as the print spooler and PIP.

1.3.1

Disks

Disks are the main storage media on RSX-llM and RSX-llM-PLUS systems.
Disk drives are either public (that is, accessible to all users) or
private (that is, accessible to a restricted set of users).
Almost
all utility programs work with disks as their default device. You can
share public disk resources to create source program files and, as
needed, allocate your own private drive to store reserved copies of
source and documentation files.

1.3.2

Terminals

Terminals are the means by which you communicate with the system.
DIGITAL terminals handle 7-bit ASCII characters and system software
usually ignores any eighth, or parity, bit. You perform input to the
system through a typewriter-like keyboard; the system returns output
to you either on a screen at a video-display terminal or on paper at a
hard-copy terminal.
Video-display terminals are more convenient
because they typically operate at faster rates than hard-copy devices.
Hard-copy terminals, however, have the advantage of providing a record
of what transpired during a session on the system.
Terminals are connected to the computer through either a direct line
or a modem unit over a dial-up telephone line. If you are not
familiar with using a terminal, you should read the Introduction to
RSX-llM and RSX-llM-PLUS and the RSX-llM/M-PLUS Command Language
Manual. These manuals explain how to access the system and basic
system functions using DCL. The RSX-llM/M-PLUS MCR Operations Manual
explains how to access the system and basic system functions using
MCR.

1.3.3

Printers

Printers provide hard-copy output of data.
On larger systems, you
communicate with the printer through the Queue Manager subsystem.
(See the RSX-llM/M-PLUS Batch and Queue Operations Manual for more
information on the Queue Manager.) MCR provides a PRI command and DCL
a PRINT command on systems with the Queue Manager.
On smaller
systems, you may have to specify explicitly that output is to go to a
line printer. All systems have a terminal or other output device
serving as a line printer. All listings from the MACR0-11 Assembler
or TKB are queued to the system line printer.

1-12

THE PROGRAM DEVELOPMENT ENVIRONMENT
1.4

THE PROGRAM DEVELOPMENT PROCESS - OVERVIEW

Figure 1-1 illustrates the steps in the program development process.
The following paragraphs briefly describe these steps, which are
treated in greater detail in Chapters 2 through 7.
START

TEXT
EDITOR (EDI)

SOURCE
FILE (.MAC)

MACRO
LIBRARY FILE
I
(DEFAULT=RSXMAC.SML))

CREATING AND
FORMATTING
MACR0-11
SOURCE
FILES

ASSEMBLING
AND
CORRECTING
A PROGRAM
MODULE

}

CORRECT
SOURCE
FILE
YES

BU~~6NG
1
J

TESTING A

SYMBOL DEFINITION
FILE (.STB)
APPLY SOURCE
CORRECTIONS
AS NEEDED

TASK

TASK IMAGE

RUN AND
DEBUG

DUMP
FILE (.PMD)
INUFD [1,4]
}

RUNNING
AND
DEBUGGING
A TASK

ZK-319-81

Figure 1-1

The Program Development Process

The steps normally taken to prepare a program to run on the system are
as follows:
1.

Create a source program in a file on disk.

buom1~ the source file to a language processor (assembler
compiler) to produce an object module.

Submit the file (or files) containing the object or modules
to TKB to create a file containing a loadable task image.

Request the Executive to execute the task.

You use a text editor to create the source file.
For MACR0-11
programmers, this guide suggests a skeleton format for source files
and shows how to replicate and modify the skeleton file. The skeleton
file becomes a common base from which you create each new source file.

1-13

THE PROGRAM DEVELOPMENT ENVIRONMENT
A language processor creates the file of relocatable object code. For
assembly language processing, MACR0-11 also accesses the system macro
library to include code for system directives in the object file. For
compilers, system directives are invoked by calls to subroutines in
the system object library SYSLIB.
TKB creates the file of loadable code, assuming certain default
conditions
about
the
run-time environment and building these
characteristics into the task.
TKB also accesses
system
and
user-specified libraries to resolve references in the task.
Once you have a task image, you request the Executive to run the
program.
If any errors are encountered, you must edit the source
file, reassemble or recompile, build a new task image file, and try
again.

1.5

GUIDE TO FURTHER READING

The sections or chapters in the following documents contain additional
information on the subjects described in this chapter.
Document
Introduction to RSX-llM and RSX-llM-PLUS
RSX-llM/M-PLUS Command Language Manual
Chapter 1,
Chapter 3,
Chapter 4,
Chapter 6,

Introduction
Terminal Operations
Handling Files
Program Development

RSX-llM/M-PLUS MCR Operations Manual
Chapter 1, Introduction to MCR
Chapter 2, System Conventions
RSX-llM/M-PLUS Utilities Manual
Chapter 1, Introduction
EDT Editor Manual
Chapter 1, Introduction to EDT
RMS-11 User's Guide

1-14

CHAPTER 2
CREATING MACR0-11 SOURCE FILES

Your first step in program development is to create a file that
contains MACR0-11 source statements. One way to do this is to create
a skeleton source file that you can use as a framework for all your
source programs. This chapter describes a source file format that you
can use as a guideline to create your own skeleton file, presents some
MACR0-11 statements to include in the file, and explains some
elementary editing commands that you can use to create and modify
source files.
DIGITAL has established a coding standard to enhance the readability
and maintainability of its MACR0-11 source programs. That standard is
outlined in an appendix of the PDP-11 MACR0-11 Language Reference
Manual, the reference for which is given in the list of further
reading at the end of this chapter.

2.1

MACR0-11 SKELETON SOURCE FILE FORMAT

This section presents the skeleton and source statement formats and
discusses
each
of the elements in the skeleton.
Figure 2-1
illustrates the basic elements of the
skeleton:
a
preface,
definitions, functional descriptions, and the code itself.
The source file preface, or preamble, should be on the first page.
The preface essentially describes the code, states its ownership,
identifies the author, defines the changes to the code, and gives a
brief description of the module's function.
After the preface of the module comes the detail of the code.
Declarations, such as local symbol, macro, and data definitions,
appearing toward the front of the code, make reading the code easier.
Preceding the routines in the module you should place detailed
descriptions of what the routines do, and define what is required for
input to the routines, what the routines produce, and what effects
result from execution.
Each statement line in a source
format, as shown in Figure 2-2.

file

2-1

should

consistent

CREATING MACR0-11 SOURCE FILES

Title
Identification

Statement of Ownership

Module Preface
on ti rst page

Authorship

Change History

Module Function
(General)

Local Symbol Definitions

Local Macro Definitions

Local Data Blocks

Module Function
(Detailed)
Inputs, Outputs,
and
Side Effects

Module Code
ZK-320-81

Figure 2-1

MACR0-11 Source File Format

2-2

CREATING MACR0-11 SOURCE FILES

PF
I

Tab Position 0
Column 1

Operand(s)

; Comments

Tab Position 1
Column 9

Tab Position 2
Column 17

Tab Position 4
Column 33
ZK-321-81

Figure 2-2

MACR0-11 Source Statement Format

Although the assembler allows free formatting of statements, you
should follow the recommended format because it is easy to follow and
creates readable, consistent code.
In the source statement format shown in Figure 2-2, the label is any
user-defined symbol that identifies a reference location in the code.
An operator is any PDP-11 operation code,
MACR0-11
Assembler
directive, or macro symbol.
An operand is any argument(s)
or
parameter(s) of an operator.
Comments consist of information you
provide to describe what effect you desire from the execution of the
instruction. Comments do not affect program execution; the assembler
merely transfers them to the listing file produced during the
assembly.
Comments, accompanied by selected MACR0-11 Assembler directives,
constitute the source file skeleton.
This skeleton provides the
structure on which you build the source file.
Directives in the
source file skeleton identify the code and control the format of the
listing. Example 2-1 shows a sample skeleton.
Sections 2.1.1 through 2.1.12 describe the parts of
skeleton in detail.

2.1.1

the

source

file

.TITLE Directive

The .TITLE directive allows you to name the module.
The assembler
takes the first six nonblank characters, up to the first blank or
horizontal tab character, as the module name. Following the name in
the .TITLE directive, you can use up to 24 characters to describe
generally the function of the module. The name and the description
appear as the first entry in the header line of each page in the
assembly listing.
For example, consider the
following
.TITLE
directive:
.TITLE SKELTN SOURCE FILE SKELETON
The assembler takes the characters SKELTN as the module name.
The
rema1n1ng characters up to the 30th character are taken as the
description. Any remaining characters after the 30th character would
be discarded.
The assembler does not relate the name you specify in the .TITLE
directive to the name you specify for the source or object files.
To
minimize confusion, however, it is helpful to apply the name specified
in the .TITLE directive to the source file.
(Note that the sample
code and commands shown in this guide use different names to help you
distinguish their usages.)

2-3

CREATING MACR0-11 SOURCE FILES
Example 2-1

.TITLE
• IDENT

SKELTN
/01/

Sample Source File Skeleton

SOURCE

FILE

SKELETON

AUTHOR: Z

CHANGES:

MODULE FUNCTION:

.PAGE
.SBTTL
•. LIST
+NL I ST
.MCALL

; BREAK PAGE FOR PREFACE
SYMBOL, HACRO, DATA DEFINITIONS
TTM
BEX
;SUPPRESS BIN EXTENSION
EXIT$S
;EXEC'S EXIT MACRO

LOCAL SYMBOL DEFINITIONS:

LOCAL MACROS:

LOCAL DATA BLOCKS:
.PSECT

DATA,D,RW

FUNCTION DETAILS:

INPUTS:
OUTPUTS:
SIDE EFFECTS:
START CODE HERE
.PAGE
.SBTTL
.PSECT
START:
END:

EXITSS
.END

;EXIT CLEANLY TO EXEC
;TELL ASSEMBLER END OF CODE

2-4

CREATING MACR0-11 SOURCE FILES
Moreover, the name the assembler extracts from the .TITLE directive is
important in subsequent steps of program development.
The Task
Builder (TKB) lists this name in its memory allocation synopsis to
show which object modules made contributions to each program section
in the task image.
In addition, if the object module is inserted in

an object library, the Librarian Utility Program (LBR) keeps this name
in the directory of the library to refer to the object module.

2.1.2

.!DENT Directive

The .!DENT directive records the version of the module.
You can
establish
your
own
version
identification
conventions.
The
identification follows the module into the task image and is displayed
in the map.
Knowing whether the correct version of the module was
linked into the task image helps in the debugging and maintenance
process.

2.1.3

Author Line

The author line identifies the originator of the code.

2.1.4

Changes Section

This section of the source file describes any modifications that

been

made

the

module.

have

You can develop a convention whereby the

author's initials and a number can tag a change. The author of the
change can identify the change in this section and flag each line of
code with an additional comment, such as the following:

; TOM JONES
8-AUG-81
;TJOOl
ADD STATE TAX TO TOTAL
Then, in the code a changed or added line
notation TJOOl.

with

the

This procedure helps the author recall what changes were made to
module and assists others in determining the extent of changes.!

the

ADD

2.1.5

A,B

;TOTAL WITH TAX

can

flagged

;TJOOl

Module Function

In the module function part of the source file, you can describe the
general
processing
operations
that
the code performs.
This
description can include how the module relates to the system or

specific

application,

that

is, what type of processing precedes and

follows the execution of this module.

1. A utility called the Source Language Input Program (SLP)
is
supplied with the system and can be used for source file maintenance.
SLP provides the means to update lines in an existing source file and
to apply an audit trail to identify lines deleted, replaced, and
added. MCR users access SLP through various SLP commands. DCL users
access SLP through the EDIT/SLP command.
2-5

CREATING MACR0-11 SOURCE FILES
2.1.6

Some Useful Directives

local
symbol
Between the module function description and the
definitions is a convenient place to insert some general-purpose
directives. The following subsections describe these directives.

2.1.6.1 .PAGE Directive - The .PAGE directive causes a page break in
the assembly listing.
It appears as shown in Figure 2-3 to keep the
preamble alone on the first page of the listing (after the table of
contents).
You can use the .PAGE directive throughout the module to
generate page breaks for different subroutines.

2.1.6.2 .SBTTL Directive - The .SBTTL directive creates an entry for
the assembly listing table of contents printed at the front of the
listing.
A table of contents is helpful in
summarizing
the
subroutines in a large module. Therefore, the text you supply with
the directive ought to describe what the related subroutine does.
In
addition to appearing in the table of contents, the text appears on
the second line of the heading at the top of each listing page.
If
your modules typically contain only a small number of subroutines, you
probably will not find the table of contents feature very useful.

?.41.6.3 .LIST TTM Directive - The
.LIST TTM directive creates
a
listing formatted more conveniently for ouput on a terminal.
(Section
3.4 of this guide shows how to display a listing at a terminal.)
The
directive
can be included during the early stages of program
development and removed from the stabilized code.

2.1.6.4 .NLIST BEX Directive - The .NLIST BEX directive suppresses
the binary extension of statements beyond what can fit on one source
statement line. Using this directive saves much excess printing in
the assembiy iisting. For example, only the binary value of the first
three characters of an ASCII string would appear in the listing.
The
directive simply makes the listing more readable and saves paper.

2.1.6.5 .MCALL Directive - The .MCALL directive is the means by which
you tell the assembler the names of the externally defined macro calls
that appear in the snur~e file.
Th~ directive ~auses the assembler to
create entries in its macro symbol table for the macro names and to
look up the definitions of the related calls in either a user or a
system macro library. The assembler includes the definitions from the
library in the module where the calls themselves appear.l

1. If you do not include the directive .LIST ME
(list
macro
expansions)
or
.LIST MEB
(list macro expansion lines that generate
object code) in the source file, the assembler does not insert in the
listing the expanded source code of the macros it assembles.
2-6

CREATING MACR0-11 SOURCE FILES
The EXIT$S directive (shown in the
.MCALL statement)
should be in
every user program for a clean exit.
It is the last statement the
program (task) executes before it returns control to the Executive.
· (The
EXIT$S
directive
performs
important system housekeeping
operations for the task.) The related definition for EXIT$S resides in
the file RSXMAC.SML in UFO [1,1] on the library device {LB:). DIGITAL
recommends that user tasks exit by using the EXIT$S directive=
(An
alternative form of exiting allows a task to exit and post status.)
If a call for an externally defined macro statement appears in the
source file but is not preceded by an .MCALL directive and the macro
name, the assembler treats the unrecognized macro call as an implicit
.WORD data storage directive.
(If the macro call has parameters, the
assembler may generate an error because of illegal syntax for a
.WORD
directive.)
Later, when you build the task with the related object
module and the macro name is not a valid symbol, TKB flags the name as
an undefined reference.
Thus, without the .MCALL directive, the
assembler does not know that it must search libraries to resolve the
macro symbol.

2.1.6.6 .END Directive - The .END directive in a module signals the
logical end of source inout and optionally specifies the task transfer
address. The transfer address is the -location at which program
execution begins.
Although each source file should contain an .END
directive, only one source file should define the transfer address.
The assembler does not process lines beyond the one on which the .END
directive appears.

2.1.7

Local Definitions

In this section of your source file, you collect symbols in direct
assignment statements. Because symbols in MACR0-11 can be defined as
expressions of other symbols, having the definitions in one place is
an advantage.
In addition, good programming practice encourages using
symbols instead of simply supplying a numeric constant.
For example, in defining a 10-byte buffer, the best method is
define a symbol and then use the symbol in the buffer definition.

LOCAL DEFINITIONS
;

SIZB = 10.

LOCAL DATA BLOCKS
;

BUFB:

.BLKB

SIZB

This method has several advantages:
•

If a single constant that is referred to in numerous places in
the code must be altered, you need perform only one edit (to
the symbol definition) to effect the change.

•

If all the symbols are gathered in one place
order, reading the code is simplified.

2-7

alphabetical

CREATING MACR0-11 SOURCE PILES
•

You can find all references to a symbol in a cross-reference
listing. The cross-reference capability allows you to examine
all the references to a symbol and confidently assess the
effects of altering the symbol definition.

These advantages are lost if you use constants.
Thus, the symbol list would contain such local symbol definitions as
SIZB = 10. The symbols themselves would appear in the module code.

Local Macro Definitions

2.1.8

The definition of a macro statement can appear anywhere in the source
file as long as the definition appears before the first occurrence of
the macro statement.
It is better programming practice, then, to
place all macro definitions in a standard place near the front of the
source file.

Local Data Blocks

2.1.9

This section of the source file defines such data as buffers, status
words, and status bytes. Generally, it describes the local storage
that the module references.
It is good programming practice to use a
separate .PSECT directive for data. See Section '-~l:ll:

2.1.10

Module Function - Detailed

This section of the source file can be as general or specific as
needed to describe the functions of the module. A complex module
should have a lengthy discussion; a simple module need not have as
much.
At a minimum, this section should state the register usage on
input to and output from the module.

2.1.11

.PSECT Directive

The .PSECT directive establishes a name and attributes for a program
section.
A program section is a unit allocation of memory reserved
for either code or data. For example, you can establish a program
section to contain data for your program as follows:
.PSECT DATA,D,RW
The .PSECT directive creates the program section named DATA with the
attributes data
(D)
and read/write
(RW).
You may give a program
section for data either the read-only (RO)
or the read/write
(RW)
attribute.
(The assembler applies other default attributes not
relevant to this discussion.)
RSX-llM systems do not support hardware protection of program sections
that have the RO attribute.
RSX-llM-PLUS systems support hardware protection of program sections
that have the RO attribute if they are in the pure code of a multiuser
task.

2-8

CREATING MACR0-11 SOURCE FILES
Consult the RSX-llM/M-PLUS Task Builder Manual
program section allocation in multiuser tasks.

for

discussion

The three most important aspects of the .PSECT directive are:
•

Contributions defined for a specific program section can be in
separate places in a source file or in separate source files.

•

The attributes of the program section are passed to TKB.

Contributions for a specific program section with the same
• attributes
are collected in one continuous allocation of
memory space by TKB.
In the skeleton file, it is useful to define one program section to
contain the data elements referenced in the task and to define another
program section to contain the code.

2.2

CREATING A SOURCE FILE FROM A SKELETON FILE

This section describes how to use an editor, EDI, to create a skeleton
file and then to create a source file from the skeleton.
If you are
using EDT or some other editor, follow the text for EDI and perform
the functions using your editor.

2.2.1

Performing the Initial Input

To create the skeleton file using MCR, type EDI and the specification
of a new file, that is, one that is not in your directory. For DCL,
use the command EDIT/EDI and the specification of a new file.
Here is the sequence from a DCL terminal:
DCL>EDIT/EDI SKEL.MAC
[CREATING NEW FILE]
INPUT
Here is the sequence from an MCR terminal:
MCR>EDI SKEL.MAC
[CREATING NEW FILE]
INPUT
The editor runs, determines that the file does not exist, creates
file, and tells you to begin typing the input.

the

Type the input according to Example 2-2.
Leave any typographical
errors until after you have become familiar with the editing commands
described in Section 2.3. The notation conventions appearing in the
figure are described in the Preface at the front of this guide.

2.2.1.1 In'serting Blank Lines in Text - To insert a blank line in the
source file as shown in Example 2-2, type a space or tab on a new line
followed by the RETURN key.
If you type the RETURN key twice in
succession (that is, type the RETURN key to enter a line of text and
immediately type the RETURN key again on the new line), EDI terminates
the input.
Thus, to enter a blank line, you need type only one
nonprinting character, such as TAB, on a new line.

2-9

CREATING MACR0-11 SOURCE FILES
2.2.1.2 Terminating the Input and the EDI Program - To terminate the
input, type the RETURN key twice in succession. EDI prints the
asterisk to request a command. Type the EXIT ~ommand to close the
file and terminate EDI. For example:
last line of text

*EXIT
[EXIT]

>
When EDI exits, it prints the message [EXIT] and returns control to
the operating system. The implicit prompt (>) indicates that the CLI
is ready to accept a new command. The remainder of this chapter makes
changes in the source file SKEL.MAC and demonstrates EDI commands at
the same time. If you are using EDT or some other editor, follow the
changes as demonstrated and make them in your file using your editor.
If you are using DCL, remember to use the EDIT/EDI or EDIT/EDT
command.

2-10

CREATING MACR0-11 SOURCE FILES
Example 2-2

Creating the Skeleton File SKEL.MAC

>EDI SKEL.MAC
CCREATING NEW FILEJ

INPUT
~
QM)

.TITLE~ SKELTN~SOURCE
.IDENT~ /01/

FILE

SKELETON

;

; AUTHOR: Z
f
QM) ffi)

;

; CHANGES:

;

QM) ffi)

;

; MODULE FUNCTION:
;
(ffiW ffi)

;

• PAGE ~ @ID
; BREAK PAGE FOR
.SBTTL@m SYMBOL, MACRO, DATA DEFINITIONS

.LIST ~ TTM ~ ~
• NLIST (f@ BEX ~ @ID
.MCALL~ EXIT$S ~ ~

@j
@j

PREFACE

HERHINAL LISTING MODE
; SUPPRESS BIN EXTENSION
;EXEC'S EXIT MACRO

~ ffi)

;

; LOCAL SYMBOL DEFINITIONS:

; LOCAL MACROS:

; LOCAL DATA BLOCKS:

; FUNCTION DETAILS:
~ ffi)

INPUTS:

OUTPUTS:

SIDE EFFECTS:

~ ffi)

.PAGE
.SBiTL
.PSECT
~
START CODE HERE
START:
@ID
~

•

~ ffi)

END: @ID EXIT$S ~ ~
• END ~ @ID (f@
~

;EXIT CLEANLY TO EXEC
;TELL ASSEMBLER END OF CODE

ffi)

*EXIT
CEXITJ

>
2-11

CREATING MACR0-11 SOURCE FILES
2.2.2

Creating a Source File from the Skeleton

After you create the skeleton file, you can use it many times to
create different source files by running the editor again as described
in Section 2.2.1.
For example:
MCR>EDI SKEL.MAC
[00054 LINES READ IN]
[PAGE l]

*
This time EDI finds the file you just created, reads it
and prints an asterisk to request a command.

into

memory,

The EXIT command with a file specification creates a new file having
that name and containing all of the text in your skeleton. For
example:
*EXIT FILE.MAC
[EXIT]

>
EDI creates either the new file FILE.MAC;l in your directory or,
if
the file already exists, a new version of the file.
It retains the
input file SKEL.MAC. You can repeat this process to create as many
new source files as you need.
At this point, the contents of SKEL.MAC and your new file are exactly
the same -- typographical errors and all. Now you must use editing
commands to change your new file to make it unique.
Section 2.3
describes some of these commands and gives examples of their usage to
enable you to perform the most common editing functions.

By using the same skeleton file each time you want

to create a new
source file, you save typing time and have a better chance of creating
consistent, easily readable, and well-documented code. After you have
gone through Section 2.3 and learned the editing commands, you may
want to correct the errors in the skeleton file.

2.3

EDITING THE SOURCE FILE

This section describes how to use a subset of EDI commands to edit a
source file.
By following the examples in this section, you will
create three source files that you can use in subsequent stages of the
program development cycle.
You can abbreviate most of the commands in EDI.
For example, the EXIT
command can be abbreviated EX.
The descriptions of each command
include (within parentheses) the accepted abbreviation, if one exists.

2-12

CREATING MACR0-11 SOURCE FILES
2.3.1

Displaying Text

Use the EDI command to access a source file to edit.

For example:

MCR>EDI FILE.MAC
[00054 LINES READ IN]
[PAGE 1]

*
Two keys, RETURN and ESCAPE, cause EDI to move forward and backward,
respectively, one line and to display the new line. By using these
two keys, you can step line by line through a file.
For example:
* ffiJ
.TITLE

SKELTN

• IDENT

/01/

.TITLE

SKELTN

SOURCE FILE SKELETON

* ffiJ
*(@
SOURCE FILE SKELETON

*
Typing the RETURN key twice advances the pointer two times and
displays each line. Typing the ESCAPE key moves the pointer back to
the previous line and displays the line.

TYPE n {TY n)
The TYPE n command displays n lines at a time but does not
line position. For example:
*TYPE 2
.TITLE SKELTN
• IDENT /01/

alter

the

SOURCE FILE SKELETON

*
The 2 in the TYPE command causes EDI to display the current line and
the next line.
If you give the TYPE command without a number, EDI
displays the current line (that is, one line}.

LIST (LI)
The LIST command displays all lines in the buffer starting at the
current line and stopping at the last line in the buffer (that is, end
of buffer). For example:
*LIST
(all lines are listed)
*TYPE
[*BOB*]
*EXIT
[EXIT]

>
The LIST command positions the line pointer at the beginning of the
buffer. The TYPE command shows the position of the line pointer.
EDI
prints the blank line it maintains at the beginning of the buffer and
the message
[*BOB*]
to remind you that the line pointer is at the
beginning of the buffer.
EDI always keeps a blank line at the
beginning of the buffer to allow you to insert lines before the first
line of text in the buffer.

2-13

CREATING MACR0-11 SOURCE FILES
2.3.2

Locating Text and Positioning the Line Pointer

Editing a file requires you to locate a line of text in the buffer and
to position the pointer to that line. This section describes several
of the commands most commonly used in editing files.

BEGIN (B), END (E)
The BEGIN and END commands position the pointer to fixed lines in the
buffer -- the beginning and ending lines. The END command also prints
the last line of the buffer. For example:
MCR>EDI FILE.MAC
[00054 LINES READ IN]
[PAGE l]
*END
CT@

• END

CT@

CT@ ;

TELL ASSEMBLER END OF CODE

*
The END command is useful for quickly assessing what the last line in
the buffer is.
The BEGIN command is helpful in quickly positioning
the pointer at the beginning (or top) line of the buffer, thus
enabling you to make multiple passes over a buffer. For example:
*BEGIN
*TYPE
[*BOB*]

*
Because the BEGIN command does not display any text, you can use the
TYPE command to display the first line in the buffer. The command in
the example shows the blank line at the beginning of the buffer.
EDI
prints [*BOB*] to show you that it is positioned at the beginning of
the buffer. For example:
*~
@ID

• TITLE

@ID

SKELTN

CT@

SOURCE FILE SKELETON

*
Typing the RETURN key advances the pointer and displays the
follows:

line,

LOCATE (L)
If the text you want to examine is within the buffer, you can type the
LOCATE command with a string to be located. For example:
*LOCATE MODULE
; MODULE FUNCTION:

*
A space should separate the command and the search string to be
located. EDI displays the line on which it found the first occurrence
of the string. If EDI does not find the string, it prints a message
indicating that the end of buffer has been reached. For example:
*LOCATE NODULE
[*EOB*]

2-14

CREATING MACR0-11 SOURCE FILES
After an unsuccessful search, EDI leaves the line pointer at the
line of the buffer.

last

PLOCATE (PL)
If the string for which you are searching is not in the buffer, you
can use the PLOCATE command to tell EDI to search successive buffers
until it locates the string. For example:
*BEGIN
*PLOCATE .END
• END @ID (JM)

@ID

TELL ASSEMBLER END OF CODE

*
EDI searches the buffer starting at the current line. i~ the string
is not found in the buffer, EDI preserves the contents of the buffer
and reads in more lines from the input file to fill the buffer again.
It prints a message telling the number of lines searched. When EDI
finds the string, it displays the line on which the string occurs. If
EDI does not find the string, it prints a message indicating that the
end of file has been reached. For example:
*PLOCATE .ENDR
[*EOF*]

*
At the end of file (signaled by [*EOF*]), EDI leaves an empty buffer
in which you can either insert new text (which follows all the text
currently in the file) or exit to preserve any changes made and to
start at the beginning of the file again. Note that, once EDI has
preserved a buffer, you cannot go back to it except by starting at the
beginning of the file again. For example:
*EXIT
[EXIT]

>
You can also use the PLOCATE command with a string known not to
in the file to position EDI after the last line of the file.

exist

RENEW (REN)
The RENEW command lets you read new lines from the
example:

input

file.

For

*EDI FILE.MAC
[00054 LINES READ IN]
[PAGE l]
*RENEW
[*EOF*]
[PAGE 2]
*EXIT
rPYT'T'1
L .,,,..,...,,. .. J

>
The RENEW command writes the lines in the buffer to the temporary
output file before it reads in new lines from the input file. If
there are no more lines left in the file, EDI signals the end of file.
This command is useful for casually inspecting the contents of a file.

2-15

CREATING MACR0-11 SOURCE FILES
2.3.3

Changing Text

CHANGE (C)
The CHANGE command alters text on the current line, allowing you to:
1.

Replace an old string with a new string

Add a string at the start of a line

Delete a string from a line

The command requires that you type, within character delimiters, the
old string
(the text to be altered) followed by the new string. The
only requirement for the delimiting character is that it does not
appear in either the old or the new string.l A convenient character to
use as a delimiter is the slash character
{/), as shown in the
following example:
MCR>EDI FILE.MAC
[00054 LINES READ IN]
[PAGE l]
*~
.TITLE SKELTN
SOURCE FILE SKELETON
*C /SKELTN/NUMA/ ~
.TITLE NUMA
SOURCE FILE SKELETON
After you enter the C command, EDI searches the line for the old
string
(SKELTN) and replaces it with the new string {NUMA).
EDI then
prints the changed line to allow you to verify the operation.
If EDI
cannot locate the old string, it prints the message [NO MATCH] and
reprints the prompt.
To save typing long strings, EDI allows you
( ••• ) in the old string. For example:

include

ellipsis

*C /SO ••• ON/COUNT NUMBER OF A'S/
• TITLE
@ID
NUMA @ID
COUNT NUMBER OF A'S

*
EDI takes the characters so, all
intervening characters, and the
characters ON as the old string.
The ellipsis, used in this manner,
reduces the amount of typing required to specify a string to be
changed.
Three other forms of the ellipsis allow variations of the
abbreviation:

I ... /

By itself, the ellipsis means the entire line

/old string ••• /

From old string to the end of the line

I .. . old string/

From the beginning of the line to old string

The slash characters shown as delimiters with the ellipsis can be
unique character.

any

1. The ampersand character {&) should not be used as a delimiter
because EDI treats it as a concatenation character.
If you must use
it as a delimiter, follow the special procedures presented in the EDI
chapter
in
the RSX-llM/M-PLUS Utilities Manual for using the
Concatenation Character (CC) command.
2-16

CREATING MACR0-11 SOURCE FILES
To place a string at the beginning of a line, specify the null
as the old string. For example:

string

*C //OLD STRING/ IB0
OLD STRING
~
• TITLE @§) NUMA @§) COUNT NUMBER OF A'S

*
EDI replaces the null string at the beginning of
STRING and prints the changed line.

the

line

with

OLD

To delete a string from the line, specify the null string as
string as follows:

the

new

*C /OLD STRING// IBm
~
• TITLE ~ NUMA @§) COUNT NUMBER OF Ai S

*
EDI replaces OLD STRING with the null string:
STRING and prints the changed line.

that is, it deletes OLD

AP
A special command, AP, adds a string at the end of a line.
The
command does not need delimiting characters since only one string can
be specified. Simply specify a space to separate the command and the
string as follows:

*IBm
*AP

• !DENT /01/
IDENTIFY MODULE VERSION
• ID ENT /0 l/
r'fABl

IDENTIFY MODULE VERSION

*
After adding the text at the end of the line, EDI displays the changed
line.

DP n
To remove a line or lines from the text in the buffer, specify the
DP n command, where n is the number of lines to be deleted. You can
use the TYPE n command with the DP n command to display the lines to
be deleted. For example:
*TYPE 3
;AUTHOR:Z
*DP 2
;AUTHOR:Z

*
The TYPE 3 command displays the current line and two succeeding lines
(the pointer remains positioned at the current line). The DP 2
command deletes the current line and one succeeding line~
EDI moves
the pointer to the line after the last one deleted and prints that
line.

2-17

CREATING MACR0-11 SOURCE FILES

EXIT (EX)
After changing text
follows:

the

file,

the

editing

session,

*EXIT
[EXIT]

>
The EXIT command without a file name creates a new version of the
current file and copies the remainder of the file to the new version.
Because exiting preserves the edits you have made to that point, you
should exit fairly often from a lengthy editing session.
If a system
crash occurs, EDI retains the old version of your file
(that is, it
retains the edits up until you last exited) but does not retain the
changes you are making.
Frequent exits minimize the amount of editing
that can be lost if a system crash occurs.

2.3.4

Inserting Code in the Source File

INSERT (I)
The INSERT, or I, command allows you to add multiple lines of text in
the source file.
To insert code in the source file FILE.MAC, use
positioning commands to locate the line preceding where von w~nt to
place the new material. The I command places new lines 1~-th~-~~ffer
after the current line. For example:
MCR>EDI FILE.MAC
[00052 LINES READ IN]
[PAGE l]
*L FUNCTION:
; MODULE FUNCTION:
*I IBIT)
THIS MODULE LOADS A BUFFER,
COUNTS THE NUMBER OF A'S (UPPER
CASE ONLY) IN THE BUFFER, CONVERTS
THE NUMBER TO OCTAL, AND REPORTS
;
THE NUMBER OF A'S FOUND. fB@
fB@

*
The L command (for LOCATE) positions EDI to the line preceding where
you want to place the new lines.
Typing the I command followed by the
RETURN key places EDI in insert mode. After you type the lines, press
the RETURN key twice in succession to leave insert mode.
Continue using positioning and editing commands to
remainder of the source program shown in Example 2-3.

2-18

type

the

CREATING MACR0-11 SOURCE FILES
Example 2-3

•TITLE
•I DENT

NUHA
/01/

Source Code for FILE.MAC

COUNT NUMBER OF A'S
; IDENTIFY HODULE VERSION

AUTHOR: Z

CHANGES:

MODULE FUNCTION:
THIS MODULE LOADS BUFFERr
COUNTS THE NUMBER OF A'S <UPPER
CASE ONLY> IN THE BUFFERr CONVERTS
THE .NUMBER TO OCTAL• AND REPORTS
THE NUMBER OF A'S FOUND.
.PAGE
.SBTTL
.LIST
• NLIST
.MCALL

; BREAK PAGE FOR PREFACE
SYHBOLr HACROr DATA DEFINITIONS
TTH
TERMINAL LISTING MODE
BEX
SUPPRESS BIN EXTENSION
EXITtS
; EXEC'S EXIT MACRO

LOCAL SYMBOL DEFINITIONS:
MSGLEN = NUMEND-HSG
SIZ
== SO.
SIZA
= 6.

; LOCAL MACROS: NONE

LOCAL DATA BLOCKS:

A:
BUFl:
MSG:
NUMA:
NUHEND
NUHC:
;

.PSECT

DATArDrRW

.ASCII
.BLKB
.ASCII
+BLKB

/A/
f DEFINE AN A
; DEFINE BUFFER
SIZ
/THE NUMBER OF A'S IS I
SIZA
DEFINE OCTAL COUNT
END OF HESS AGE
S NUMBER OF CHARS TYPED
1

=•

+BLKW

2-19

CREATING MACR0-11 SOURCE FILES

Example 2-3 (Cont.)

Source Code for FILE.MAC

FUNCTION DETAILS:
INPUTS:
BUF1 IS LOADED WITH CHARACTERS
OUTPUTS:
NUMA HOLDS THE NUKBER OF A'S
SIDE EFFECTS: NONE
START CODE HERE
.PAGE
+SBTTL
.PSECT

ROUTINE TO COUNT A'S

START:
CALL
TST
BEQ
CLR
HOV

tBUFl,RO
tSIZrR1
READ
R2
END
R1
R2,NUKC

CMPB
BNE
INC

20$
Rl

IS CHAR = A?
IF NO, BET NEXT CHAR
COUNT AN A

R2
10$

ONE LESS CHAR
IF HOREr COMPARE NEXT

MOV
HOV

LOAD BUFFER ADDR
LOAD BUFFER SIZE
READ FROH TTY
ANY CHARS IN BUFFER?
IF NONE• FINISH UP
INIT I OF A'S COUNTER
SAVE t OF CHARS TYPED

10$:
O~OihA

20t:
DEC
BNE
+PAGE
•SB TTL
HOV
MOV

30$:
MOV

END:

BIC
ADD
HOVB
ASR
ASR
ASR
DEC
BNE
HOV
HOV
CALL
EXITtS
.END

TRANSLATE COUNT TO OCTAL
tNUHA+6rRO
SET PTR TO OCTAL t
t5rR2
SET COUNT OF DIGITS
Rlj;-(SP>
U77770r@SP
160,@SP
<SP>+r-<RO>
Rl
R1
Rl
R2
30$
tHSGrRO
tHSGLENrRl
WRITE

STACK IS TEKP AREA
STRIP LOW J BITS
MAKE OCTAL DIGIT
STORE OCTAL DIGIT
SHIFT TO
NEXT
3 BITS
ONE LESS DIGIT
IF HOREr REPEAT
LOAD ADDR OF BUFFER
LOAD SIZ OF HESSAGE
REPORT THE RESULTS
EXIT CLEANLY TO EXEC
TELL ASSEMBLER END OF CODE

2-20

CREATING MACR0-11 SOURCE FILES
After you have typed in the code, use the techniques described
previously to create two new source files, FILEA.MAC and FILEB.MAC,
from the skeleton file. The code for these two files is shown in
Examples 2-4 and 2-5. These two files and the file FILE.MAC will be
used in Chapter 4 to build and test a task. You may want to edit the

skeleton file before you create the two new source files.
Example 2-4

.TITLE
•I DENT
AUTHOR: DEF

TTREAD
/01/

Source Code for FILEA.MAC

TERMINAL READ SUBROUTINE

8-AUG-81

CHANGES: NONE

MOitULE FUNCTION:

THIS MODULE READS A LINE FROH A
TERMINAL INTO A BUFFER
.PAGE
.SBTTL
.LI Si
• NLIST
.MCALL

; BREAK PAGE FOR PREFACE
SYHBOLr HACROr DATA DEFINITIONS
iTH
iERHINAL LISiiNG HODE
BEX
; SUPPRESS BIN EXTENSION
llIO$S,WTSE$S

LOCAL SYMBOL DEFINITIONS:
EFNl
=1
LUNS
=5

LOCAL MACROS: NONE

LOCAL DATA BLOCKS:

IOST:

.BLKW

DEF IO STATUS WDS

2-21

CREATING MACR0-11 SOURCE FILES
Example 2-4 (Cont.)

Source Code for FILEA.MAC

FUNCTION DETAILS:
f

;
;

INPUTS: RO = ADDRESS OF BUFFER TO LOAD
Rl = LENGTH IN BYTES OF BUFFER
OUTPUTS:

R2 = NU"BER OF CHARS <BYTES> READ

SIDE EFFECTS:

IOT IF ERROR

.PAGE
.SBTTL START OF CODE
.PSECT
f START CODE HERE:
READ;;
; DEFINE ENTRY POINT
QIOSS
tIO.RLB.tLUN5.tEFN1··•IOST•r<RO.R1>
QIO DIR PARAMETERS:
RLB IS READ LOG BLOCK
LUNS = TKB DEFAULT
EFN1 IS EVENT FLAG 11
IOST = STATUS AREA
<> = PARAMETER LIST
RO = START OF BUFFER
R1 = SIZE OF BUFFER
10$
BCS
IF SET, DIR ACCEPT ERROR
WTS£$S tEFNl
WAIT FOR IO CO"PLETE~EF 1
TSTB
IOST
CHECK lO STATUS
10$
IF LTr IO ERROR
BLT
HOV
IOST+2rR2
SAVE t OF BYTES READ
GO BACK TO CALLER
RETURN
lOS:

HOV
HOVB
IOT
.END

nsw,Ro

SAVE DIR STAT WD
SAVE !O STAT BYTE
FORCE SST EX IT
TELL ASSEMBLER END OF CODE

IOSTPR1

2-22

CREATING MACR0-11 SOURCE FILES
Example 2-5

+TITLE
• IDENT

TTWRIT
/01/

Source Code for FILES.MAC

TERMINAL WRITE SUBROUTINE

AUTHOR: DEF 8-AUG-81

CHANGES: NONE

MODULE FU NC TI ON:
THIS MODULE WRITES A
LINE FROH A BUFFER TO
A TERMINAL

;

.PAGE
.SBTTL
.LIST
.NLIST
+MCALL

; BREAK PAGE FOR PREFACE
SYHBOLr HACROr DATA DEFINITIONS
TTH
; TERMINAL LISTING MODE .
BEX
; SUPPRESS BIN EXTENSION
tlIO$SrWTSESS

LOCAL SYMBOL DEFINITIONS:
EFN1
=1
LUN5
=5

LOCAL MACROS: NONE

LOCAL DATA BLOCKS:

IOST:

+BLKW

DEF 10 STATUS WDS

FUNCTION DETAILS:
INPUTS:
;

OUTPUTS:

RO = ADDR OF BUFFER TO WRITE
Rl = LENGTH IN BYTES OF BUFFER

SUCCESS !N !OST
SIDE EFFECTS: IOT IF ERROR

2-23

CREATING MACR0-11 SOURCE FILES
Example 2-5 (Cont.}

Source Code for FILES.MAC

.PAGE
.SBTTL START OF CODE
.PSECT
; START CODE HERE
WRITE::
; DEF ENTRY POINT
QIOSS
tIO.WLB.tLUNS.tEFN1.,1IOSf,,<RO.R1.140>
QIOSS PARAMETERS:
IO.WLB FUNCTION CODE
LUN5 CTKB DEFAULT>
EFNl IS EVENT FLAG 1
STATUS AREA = IOST
PARAHETER LIST <>
RO = START OF BUFFER
Rl = I OF CHARS TO WRITE
40 = OUTPUT <CR>•<LF>
10$
BCS
IF SET, DlR ACCEPT ERROR
WT SE SS IEFN1
WAIT FOR IO COMPLETE
TSTB
IOST
CHECK IO STATUS
10$
BLT
IF LT• IO ERROR
RETURN
GO BACK TO CALLER
10s:
MOV
SAVE DIR STAT WD
SAVE IO STAT VALUE
HOVB
IDT
SST DUHPS TASK REGS
TELL ASSEMBLER £ND OF CODE
.END

2.4

GUIDE TO FURTHER READING

The sections or chapters in the following documents contain additional
information on the subjects described in this chapter.
Document
PDP-11 MACR0-11 Language Reference Manual
Chapter 2, Source Program Format
Appendix E, Sample Coding Standard
Section 6.1, Listing Control Directives
Section 6.6, Terminating Directives
Section 6.7, Program Sectioning Directives
Section 7.8, MACRO Library Directive: .MCALL
RSX-llM/M-PLUS Task Builder Manual
Section 2.1, Linking Object Modules
Section 10.1.28, SG (Segregate Program Sections}
Section 10.1.32, SQ (Sequential Program Sections)
RSX-llM/M-PLUS Utilities Manual
Chapter 2, Line Text Editor (EDI)
RSX-llM/M-PLUS Executive Reference Manual
Section 1.4.1, Macro Name Conventions
Chapter 5, Task Exit (EXIT$S)
Chapter 5, Queue I/O Request and Wait

2-24

CHAPTER 3
ASSEMBLING AND CORRECTING A PROGRAM MODULE

This chapter describes a few uses of the MACR0-11 Assembler, some of
the common types of coding errors, some ways to uncover and correct
errors, and the way to generate a cross-reference listing.
The material in this chapter assumes that you have created
source files as described in Chapter 2.

3.1

the

three

PERFORMING A DIAGNOSTIC RUN ON A SOURCE FILE

Your first use of the MACR0-11 Assembler on a source file should be to
perform a diagnostic run.
You run the assembler only to check for
general errors, not to produce an object module or a listing file.
To perform a diagnostic run from a DCL terminal,
command line:

type

the

following

DCL>MACRO/NOOBJECT/DISABLE:GLOBAL FILE
(any error messages appear)

>
The source file is named FILE.MAC, but because the MACRO command
defaults to a file type of MAC, the file type need not be specified.
Normally, the MACRO command is used to create an object module, so
that the /NOOBJECT qualifier is necessary to override this standard
function. The MACRO command does not produce a listing file unless
you request one with the /LIST qualifier. When you do not make a
listing file, any errors that result from assembly are listed directly
on your terminal.
The /DISABLE:GLOBAL qualifier causes MACR0-11 to disable the setting
of undefined symbols to global and external.
Ordinarily, when
MACR0-11 finds a symbol that is not defined in the source file, it
assumes that the reference is to a symbol defined externally, that is,
in another module. By disabling this feature for your diagnostic run,
you ~eii the assembler to flag any potential global references as an
undefined symbol error. Since you already know which symbols in your
source file are global, this disabling method is a convenient way to
catch typographical errors in other symbol names.
To perform a diagnostic run from an MCR terminal, type
command line:
MCR>MAC /DS:GBL=FILE
(any error messages appear)

>
3-1

the

following

ASSEMBLING AND CORRECTING A PROGRAM MODULE
The right side of the equal sign gives the specification of the source
file.
The assembler searches for the file named FILE.MAC in your UFD.
The assembler applies the type MAC as a default. Because there are no
file specifications on the left side of the equal sign, MACR0-11 does
not produce any object module or listing file.
When you do not
specify a listing file in the command line, the assembler prints on
the input terminal the lines that generated errors and reports the
total number of errors found.
The left part of the command line (/DS:GBL) causes MACR0-11 to disable
the setting of undefined symbols to global and external. Ordinarily,
when MACR0-11 finds a symbol that is not defined in the source file,
it assumes that the reference is to a symbol that is defined external
to the module (in another module).
(The notation GX in the listing
symbol table denotes a global and externally defined symbol.) By
disabling this feature in the diagnostic run, you tell the assembler
to flag any potential global reference with an undefined symbol error.
This disabling method is a convenient way to catch typographical
errors in symbol names at assembly time rather than later when you
link your object modules together.
The appearance of MACR0-11 messages at the terminal during the
diagnostic run indicates that your module contains errors. If the
assembler does not find any errors, it simply returns control to the
Executive and MCR prints its prompt.
Errors in the assembly are
denoted by single letter codes printed at the beginning of the faulty
statement.
These errors are summarized in an appendix of the PDP-11
MACR0-11 Lanquaqe Reference Manuai'.
The only errors that should appear from the
following:

u
u

71 000010 004767
99 000110 004767
ERRORS DETECTED~
2
/DS:GBL=FILE

CALL
CALL

diagnostic

run

are

the

READ
WRITE

READ FROM TTY
REPORT THE RESULTS

The two undefined symbols READ and WRITE are the entry points defined
in the source files FILEA.MAC and FILEB.MAC.
These symbols are to be
resolved by TKB.
(Note that this example was generated by the MCR
command MAC /DS:GBL=F!LE.)

3.2

TYPICAL ERRORS ENCOUNTERED DURING ASSEMBLY

Four error codes cover the majority of errors made in an assembly
language source file.
The following sections describe some of the
most common conditions under which these error codes are generated.

3.2.1

The MACR0-11 Error Code A

Error code A indicates a general assembly error. Most of these errors
are caused by typing mistakes such as the following:
•

Omitting the semicolon (;) from a comment
The semicolon separates your comment from the portion of the
statement that the assembler evaluates.
If you omit the
semicolon, MACR0-11 attempts to evaluate your comment as part
of the rest of the statement line.

3-2

ASSEMBLING AND CORRECTING A PROGRAM MODULE
•

Omitting the period from a MACR0-11 directive
The leading period
(.)
in the operator field tells the
assembler that the statement contains a MACR0-11 directive.
If you forget to include the period on a directive, the
assembler cannot evaluate the operator as a directive. As a
result, error code A is generated, the directive and its
arguments are given a value of O, and they are designated as
global symbols.

•

Misspelling a PDP-11 instruction mnemonic
If you misspelled a PDP-11 instruction mnemonic (for example,
MOVE instead of MOV), the assembler can evaluate the operands
but not the operator. The PDP-11 MACR0-11 Language Reference
Manual
lists
all the mnemonics alphabetically.
(These
mnemonics make up the permanent symbol table
(PST)).
The
PDP-11 Programming Card also contains all the instruction
mnemonics.

•

Forming an illegal symbol
The first character of a symbol must not be a numeral.

•

Not properly delimiting a directive argument
Many MACR0-11 directives require a character or argument
string to begin and end with a certain delimiting character.
If you use the wrong character or omit one of the delimiters,
the
assembler cannot properly match the delimiters and
therefore cannot evaluate the directive.
For example, the
.ASCII directive requires the character string to begin and
end with the same delimiting character.

Another type of general assembly error involves general addressing
errors.
The typical addressing error is to exceed the range of a
branch instruction (that is, branching more than 128 words backwards
or 127 words forwards). To correct this type of error, replace the
branch instruction with code to test the proper condition, and with
the JMP instruction to transfer control.
Also common as a general assembly error are
illegal
forward
references.
If you define a symbol based on another symbol defined by
a forward reference, the assembler cannot evaluate the reference.
For
example:

A
B + 10.
C = A + 10.
The assembler cannot evaluate the
defined.

3.2.2

symbol

because

not

yet

The MACR0-11 Error Code U

Error code U signals an undefined symbol error.
This error usually
occurs because
(1)
a symbol name on the
.MCALL directive was
misspelled or, (2) reference was made to a local label that does not
exist in the current local symbol block.

3-3

ASSEMBLING AND CORRECTING A PROGRAM MODULE
3.2.3

The MACR0-11 Error Code Q

Error code Q indicates questionable syntax.
This error usually
results from either including too many (or too few) arguments in a
directive or specifying an incorrect number of operands on an
instruction.
In addition, this error occurs when you omit the
semicolon from a comment and the assembler attempts to evaluate the
comment as part of the statement.

3.2.4

The MACR0-11 Error Code E

Error code E means that you have omitted the .END directive from the
assembly language source file.
If the assembler does not find the
.END directive, it generates error code E with a line number of 0
after the last statement in the listing file.
Error code E also may indicate an expression overflow.
If the
assembler encounters a nested expression that is too complex, it
generates error code E and denotes the point of the overflow with a
question mark (?). To clear the error condition, either simplify the
expression or ask your system manager to build MACR0-11 with a larger
stack.

3.3

GENERATING A PROGRAM MODULE AND A LISTING

After you correct the errors uncovered in the diagnostic run, you are
ready to produce an object module and a listing file. The following
DCL command line produces an object module and a listing file:
DCL>MACRO FILE/LIST
(error summary printed)

>
This command line, like the command line for the diagnostic run,
assumes default file types for the object file and the listing file.
The assembler creates an object module called FILE.OBJ.
The /LIST
qualifier causes the assembler to create a file called FILE.LST. It
is good programming practice to use the assembler defaults for file
types and file names. Using the defaults helps you differentiate file
types and groups associated files under the same name. If you wish to
use other names and file types, you can override the defaults by
supplying complete file specifications as arguments to the /LIST and
/OBJECT qualifiers.
Note that the /LIST qualifier is added to the file specification
rather than to the MACRO command in the example. This placement of
the qualifier causes a listing file to be created in your directory,
but the file is not printed on the line printer. A MACRO command line
in the following format:
DCL>MACRO/LIST FILE
(error summary printed)
)

still causes the listing file FILE.LST to be created in your
directory, but the file is also printed on your system's line printer.

3-4

ASSEMBLING AND CORRECTING A PROGRAM MODULE
For the time being, you should use the /LIST qualifier as a file
specification qualifier, to keep from printing too many copies.
During the program development cycle, you create many files for which
you do not need a permanent copy. It is easier and less wasteful to
examine a listing file at your terminal than to generate numerous
printed copies of listing files that must be discarded because of
minor errors. After you attain an error-free assembly, you can print
a copy of the latest version of the listing file.
When you request a listing file, the errors are printed in the file,
not on your terminal.
All you see on your terminal is a message
giving the total number of errors found. If no message appears, there
are no errors. Note, however, that freedom from assembly errors does
not guarantee that the program will run properly.
The following command line performs the same
terminal:

functions

from

MCR

MCR>MAC FILE,FILE/-SP=FILE
(error summary printed)

>
This command line, like the command line for the diagnostic run,
depends on default file types that MACR0-11 automatically assigns.
The leftmost file specification creates an object module called
FILE.OBJ.
The file type OBJ denotes that the file is an object
module.
The comma following the object file specification in the command line
is a separating character that is required to distinguish different
file specifications in command lines.
Following the comma in the command line is the listing
file
specification that creates the file called FILE=LSTa The file type
LST denotes that the file is a listing of source code produced by an
assembler or compiler.
It is good programming practice to use the assembler defaults for file
types and to apply the name of the source file to both the object and
listing files. Using the defaults helps you to differentiate types of
files and keeping the same name helps relate different types of files
to the proper source file.
The designation /-SP following the listing file specification in the
command line inhibits automatic spooling of the listing to the line
printer. During the program development cycle, you create many files
for which you do not need a permanent copy. It is easier and less
wasteful to examine a listing file at your terminal than to generate
numerous copies of listing files that must be discarded because of
minor errors. After you attain an error-free assembly, you can spool
a copy of the latest version of the listing file retained on your
~;~~

u~~ne

When you request a listing file in the assembly, MACR0-11 does not
print error lines on the terminal. Instead, if the assembler detects
any errors, it prints a message giving the total number found.
If the
assembler finds no errors, it simply exits. The absence of a summary
of error messages from the assembler means an error-free assembly. If
there are errors, you can examine the listing file at the terminal.
However, an error-free assembly does not guarantee that the program
will run properly.

3-5

ASSEMBLING AND CORRECTING A PROGRAM MODULE
You can issue the following command lines to assemble the two other
source files, FILEA.MAC and FILES.MAC, which you created using the
procedures described in Chapter 2:
DCL>MACRO
DCL>MACRO

FILEA/LIST
FILEB/LIST

or
MCR>MAC FILEA,FILEA/-SP=FILEA
MCR>MAC FILEB,FILEB/-SP=FILEB
The two command lines create the object modules FILEA.OBJ
FILES.OBJ that you will need to link into your task in Chapter 4.

3.4

and

EXAMINING A LISTING AT THE TERMINAL

Use the TYPE command to display the listing file at your terminal,
shown:

DCL>TYPE FILE.LST
(file appears on screen)

>
From an MCR terminal, you can run the Peripheral Interchange Program
(PIP) to transfer a copy of your listing from your disk to your
terminal. The following command line starts the transfer:
MCR>PIP TI:=FILE.LST
(file appears on screen)

>
In the part of the command line to the left of the
designation TI:
specifies your terminal
(that
initiating the request) as the output device.

equal sign; the
is, the terminal

NOTE
If you omit the colon from TI:, PIP
creates a new file called TI in your UFD
and copies the input file to it.

To the right of the equal sign is the input file specification with
both a name and type. For PIP, you must specify? file type because
it does not apply a default file type for you.
(Without a file type,
PIP looks for a file with no type, that is, a file with a null type.)
You can use control commands to temporarily stop and restart the
display, and to alternately suppress and resume the output request.
The commands are summarized in Table 3-1.

3-6

ASSEMBLING AND CORRECTING A PROGRAM MODULE
Table 3-1
Terminal Output Control Commands
Effect

Command
CTRL/S

Temporarily stops the display

CTRL/Q

Restarts the display stopped by CTRL/S

CTRL/O

Alternately suppresses and resumes
the output to the terminal

The CTRL/S and CTRL/Q commands are used together to freeze tne display
on the screen and to request more lines to be displayed. While the
CTRL/S command is in effect, you can read what is on the screen.
The
CTRL/Q command tells the system to restart the display where it left
off when it sensed the CTRL/S command.
The CTRL/O command is used to suppress unwanted output.
The command
tells the system to stop sending characters to the terminal. The
program, however, continues processing but simply omits displaying the
output=
(While CTRL/O is in effect, the system disables keyboard
input and does not echo any characters typed at the terminal.) By
typing CTRL/O again, you tell the system to resume output to the
terminal. By typing successive CTRL/Os, you can skip unnecessary
portions of the output until the program reaches the correct part. If
the program finishes processing the output request while CTRL/O is in
effect, the system automatically reenables keyboard input and a prompt
appears on the terminal.

3.5

GENERATING A CROSS-REFERENCE LISTING

Worthwhile additions to the assembly listing are the symbol and macro
cross-reference listings. These listings give, in alphabetical order,
each symbol and macro name defined or referred to and the number of
the page and line in the listing where the definition or reference
occurs. From a DCL terminal, type the following command line:
DCL>MACRO/NOOBJECT FILE/CROSS_REFERENCE
(any .errors cause total number to be printed)

>
Note that the command line does not include the /LIST qualifier.
The
/CROSS REFERENCE qualifier implies the /LIST qualifier since the
cross-reference listing is attached to the assembly listing.
If you
wish to have the listing printed, use /CROSS REFERENCE as a command
qualifier instead of as a file qualifier.
Remember, you do not need to type the full form of the command unless
you are keeping a record of terminal activity. The following command
line has the same effect as the one above:
DCL>MAC/NOOB FILE/CR

3-7

ASSEMBLING AND CORRECTING A PROGRAM MODULE
From an MCR terminal, you
typing the following:

generate

the

cross-reference

listing

MCR>MAC ,FILE/CR/-SP=FILE
{any errors cause total number to be printed)

>
Because no file specification precedes the comma in th~ command,
MACR0-11 omits creating the object module and produces only a listing
file. The /CR designation tells the assembler to generate a request
for the CRF task to produce a cross-reference listing. (Omitting the
comma from the command causes an error because the command then
requests an object module only. With an object module specification,
the designations /CR and /-SP are illegal.)
NOTE
If, after you request a cross-reference
listing,
you
discover
that
the
information
is
missing
from
your
listing, the CRF task is either not
installed on your system
or
still
processing the request. Ask your system
manager to install the CRF task.
The CRF task appends the cross-reference listing to the end of the
listing file, denoting the cross-references by the titles SYMBOL CROSS
REFERENCE and MACRO CROSS REFERENCE.

3.6

SPOOLING A COPY OF LISTINGS

Once you have developed an error-free assembly, you can obtain a hard
copy of the listing for reference. From a DCL terminal, type one of
the following command lines:
DCL>PRINT FILE.LST

>
or
DCL>MCR PIP FILE.LST/SP

>
The command lines create a request to the spooling task to print the
file you specify.
(You can specify more than one file at a time by
listing more than one file specification in the command line,
separating each with a comma.) Your request is placed in a queue of
requests.
If your system does not have spooling, you can list the file
on the printer, as follows:

directly

DCL>MCR PIP LP:=FILE.LST

>
If the printer is not busy or allocated by another user,
the file to LPO:.

3-8

PIP

outputs

ASSEMBLING AND CORRECTING A PROGRAM MODULE
The process for obtaining a hard-copy listing is very similar from
MCR terminal.

From an MCR terminal, type one of the following command lines:
MCR>PRINT FILE.LST

>
or
MCR>PIP FILE.LST/SP

>
The command lines create a request to the spooling task to print the
file you specify.
(You can specify more than one file at a time by
listing more than one file specification in the command, separating
each with a comma.) Your request is placed in a queue of requests.
If your system does not have spooling, you can list the file
on the printer, as follows:

directly

MCR>PIP LP:=F!LE.LST

>
If the printer is not busy and is not allocated by another
outputs the file to LPO:.

3.7

user,

PIP

CLEANING UP THE DISK DIRECTORY

After you edit and reassemble the source files several times, your
directory becomes cluttered with multiple versions of the same files.
DCL includes a DIRECTORY command for listing information about files.
The following command lists all the files in your directory:
DCL>DIRECTORY
(the directory listing appears)

>
You will notice in the directory a number of files with the same name
and type, but different version numbers. Use the following command to
purge all but the most recent version of these files:
DCL>PURGE *.MAC,*.LST,*.OBJ
From an MCR terminal, you can list the name, types, version numbers,
and sizes of the files stored in your UFD by typing the following
command line:

(the directory listing appears)

>
The designation /LI causes PIP to list the directory information at
your terminal.
By default, the command line requests all names,
types, and versions of files in your UFD.

3-9

ASSEMBLING AND CORRECTING A PROGRAM MODULE
By examining the directory information, you notice that files with the
same name and type have multiple versions.
Use the following command
line to the PIP program to purge all but the most recent version of
the files:
MCR>PIP *.MAC,*.LST,*.OBJ/PU

>
The designation /PU purges all but the latest version of the files
specified.
The asterisk character in the command denotes all files
having any name and the type specified.

3.8

GUIDE TO FURTHER READING

The sections or chapters in the following documents contain additional
information on the subjects described in this chapter.
Document
RSX-llM/M-PLUS Command Language Manual
Section 6.2.1, MACRO Command
PDP-11 MACR0-11 Language Reference Manual
Chapter 8, IAS/RSX-llM/RSX-llM-PLUS Operating Procedures
8.1.1, Default File Specifications
8.1.2, MCR Command String Format
8.1.2.1, MCR File Specification Switches
8.1.3, DCL Operating Procedures
8.5, MACR0-11 Error Messages Under IAS/RSX-llM/M-PLUS
Appendix 0 1 Error Messages
RSX-llM/M-PLUS Utilities Manual
Chapter 3, Peripheral Interchange Program (PIP)
Appendix B, The Cross-Reference Processor {CRF)
RSX-llM-PLUS Batch and Queue Operations Manual
Chapter 2, Queuing Jobs
Section 2.1, PRINT Command

3-10

CHAPTER 4
BUILDING AND TESTING A TASK

This chapter describes ways to use the Task Builder (TKB)
program to
create a task image from program object modules. The procedures
described in this chapter assume that you have created
three
error-free object modules as described in Chapter 3.

4.1

CREATING A TASK IMAGE

The TKB program creates a task image file that can be loaded into
memory.
You can supply as input to TKB either a single object module
or multiple object modules.
In most cases, however, your programs
will consist of multiple object modules.
The following sections
describe the procedures and the way TKB reports error conditions.

4.1.1

Supplying a Single Object Module

Use the DCL LINK command to create a task image
object module:

file

from

single

DCL>LINK FILE
(any error messages appear)

>
Once again, all defaults are applied automatically. The LINK command
defaults to an object module in a file named FILE.OBJ and causes TKB
to produce a file named FILE.TSK containing the task image.
To perform the same function from an MCR terminal, enter the following
command line:
MCR>TKB FILE=FILE
(any error messages appear)

>
The right side of the equal sign specifies the file containing the
object module. TKB assumes that the type in the file specification is
OBJ. The left side of the equal sign gives the specification of the
task image file to which TKB assigns the file type TSK. Again, as
with the assembler, it is convenient to apply the same name to both
the output file and the input file and to let TKB apply the default
type specifications.

4-1

BUILDING AND TESTING A TASK
TKB tries to resolve all global references in the object module.
If
there are undefined
references after the module has been processed,
TKB searches the system object library SYSLIB.OLB in UFD [1,1] on the
library device
(LB:).
If no errors are encountered in the process,
TKB exits and the command prompt (>) appears.
If TKB detects an error during processing, it prints a message at
terminal in one of the following forms for MCR users:
TKB

the

*DIAG* - error message

or
TKB -- *FATAL* - error message
If TKB detects an error during processing, it prints a message in
of the following forms for DCL users:

one

LINK -- *DIAG* - error message
or
LINK -- *FATAL* - error message
TKB error messages are summarized in the RSX-llM/M-PLUS
Manual.

Task

Builder

If an error message appears and the error condition described
i~
not
operational (for example, lack of space for the task image file) or is
not a fatal error, TKB creates the task image file anyway.
Depending
on the error condition, you may have to remove the cause of the error
from the source file, reassemble the source file, and repeat the TKB
procedure.
In some instances, the diagnostic condition is merely a
warning and has no ill effect when the task runs.
(For guidelines on
typical error conditions, see Section 4.4.)
When you create the task image from the single object module FILE.OBJ,
TKB prints the following error message:
TKB -- *DIAG*-2 Undefined symbols segment FILE
READ
WRITE
The undefined symbols READ and WRITE are the entry points of the two
routines defined by the object modules FILEA.OBJ and FILEB.OBJ.
TKB
searches the system object library to resolve global references left
undefined
in your input.
Because TKB failed to find modules that
defined these symbols, it reported the error condition.
(This error
message is generated from the MCR command.) You can eliminate the
error condition by following the procedures described in the following
section.

4.1.2

Supplying Multiple Object Modules

TKB accepts multiple object modules as input to the LINK command.
At
a DCL terminal, type the names of the object files, separated by
commas, as shown:
DCL>LINK FILE,FILEA,FILEB
(any error messages appear)

>
4-2

BUILDING AND TESTING A TASK
The LINK command defaults to the file type OBJ for the three input
files.
The resulting task image file is named FILE.TSK. The LINK
command defaults to the name of the first object file named to derive
the name of the TSK file.
From an MCR terminal, specify the names of the multiple object files,
separated by commas, on the right side of the equal sign in your TKB
command line, as shown:
MCR>TKB FILE=FILE,FILEA,FILEB
(any error messages appear)

>
TKB performs the same actions as those described in Section 4.1.1 for
one object module from a DCL or MCR terminal. Only one of the object
modules specified must have been assembled with a .END directive
giving the starting address of the task. If one of the modules does
not contain the starting address, TKB assigns the default transfer
address of 1, which causes an error when you run the task. See
Section 4.4.
TKB can also accept as input a concatenated object module, which is
merely a file containing multiple object modules.
To create a
concatenated file, use the DCL COPY command, as shown:

DCL>COPY
From? FILE.OBJ,FILEA,FILEB
To? FILCON.OBJ

>
or
DCL>COPY FILE.OBJ,FILEA,FILEB FILCON.OBJ

>
The response to the From? prompt lists the files to be concatenated.
Note that you need specify the file type only on the first file
listed. This type becomes the default file type for subsequent files.
The COPY command automatically concatenates these files into a single
output file.
The single concatenated object file can then be the sole input to
LINK command, as shown in the following command line:

the

DCL>LINK/TASK:FILE FILCON
(any error messages appear)

>
This operation saves file-processing overhead for TKB. As a result,
building a task from a concatenated file is possibly 40 percent faster
than listing the object modules separately.
Use the following PIP command line to create a concatenated file
an MCR terminal:

from

MCR>PIP FILCON.OBJ=FILE.OBJ,FILEA,FILEB/ME

>
The right side of the command specifies the files to be concatenated.
You need specify the file type (OBJ) only on the first file because
PIP applies
it as the default file type for subsequent names.

4-3

BUILDING AND TESTING A TASK
The designation /ME tells PIP to merge
(concatenate)
all the files
into the one file specified on the left side of the equal sign.
(When
you supply multiple file specifications on the right side of the
command line, PIP uses /ME as a default condition. The command line
includes /ME merely to emphasize the
concatenate,
or
merge,
operation.)
The single concatenated object file can then be the sole input to TKB,
as in the following command line:
MCR>TKB FILE=FILCON
(any error messages appear)

>
This operation saves file-processing overhead for the TKB program
is faster than supplying the object modules separately.

4.1.3

and

Using the Fast Task Builder

Often you are performing repetitive, straightforward task-building
functions
where
speed is preferable to versatility.
In such
circumstances, you should use the Fast Task Builder (FTB). From a DCL
terminal, use the LINK command with the /FAST qualifier to specify the
FTB. Here is an example:
DCL>LINK/FAST/MAP FILE,FILEA,FILEB

>
To invoke the FTB from an MCR terminal, use the following command:

MCR>FTB FILE,FILE/-SP=F!LE;FILEA,FILEB

>
FTB runs three to four times faster than TKB but is less versatile
than TKB.
For example, FTB does not create a global cross-reference
listing or a symbol definition file.
In addition, the FTB map has
less information than the TKB map.

4.2

TASK BUILDER DEFAULTS

When you build a task image, TKB applies certain default conditions to

your

program,

including

the

partition in which your task runs, the

host
system
memory
management
characteristics,
the
task's
checkpointability, and the number of logical units your task can
access.
If your program does not use the default conditions, the
process of building a task becomes more complex. You can consult the
RSX-llM/M-PLUS Task Builder Manual for the procedures to override the
default conditions.
TKB assigns your program to be run in the default partition, called
GEN.
If you are building a task to run in another partition, you can
either supply the correct partition name at run time or rebuild the
task and specify the correct partition name then.

4-4

BUILDING AND TESTING A TASK
TKB applies memory management characteristics depending on the system
on which you build the task. If your system has memory management
hardware, TKB allocates memory starting at virtual address 0 and
assumes that the task will be relocated by memory management hardware.
Therefore, the task can be run in any partition large enough to
contain the image.
If your system does not have memory management
hardware, TKB assumes that the task runs at a fixed physical address
that the system must supply.
On RSX-llM systems, TKB assumes that the task is
and does not use the floating-point processor.

not

checkpointable

the
task
is
not
On RSX-llM-PLUS systems, TKB assumes that
checkpointable; however, it does use the floating-point processor.
TKB establishes the maximum number of logical units (six) the task can
access and supplies the assignments for these logical units. The
default assignments are: logical units 1 through 4 are assigned to
the system device (SY:);
unit 5 is the task-initiating terminal
(TI:); and unit 6 is the console listing device (CL:).
These
defaults mean that the task can simultaneously refer to at most four
files on the system device, one file on the task-initiating terminal,
and one file on the system console listing device.

4.3

GENERATING A MAP AND A GLOBAL CROSS-REFERENCE LISTING

Before you run the task and correct simple errors, you can produce a
memory allocation file (called a map) and a cross-reference listing of
global symbols. The map and global cross~reference file are useful in
later stages of program development and for program documentation.

4.3.l

Requesting a Map and a Global

Cross-Referen~e

Listing

In most situations, you need a standard
map
and
a
global
cross-reference listing for debugging a task. To create a map with a
global cross-reference listing from a DCL terminal, type the following
command line:
DCL>LINK/CROSS_REFERENCE/NOWIDE/NOTASK FILE,FILEA,FILEB

>
The /NOTASK qualifier suppresses the creation of a task image file.
You request a cross-reference listing with the /CROSS REFERENCE
qualifier. The designation /NOWIDE reduces the width of the listing
from 132 columns to 80 columns for display on a terminal. Since
/CROSS REFERENCE implies a map, you do not have to specify the /MAP
qualifTer.
If you wish to create both the task image file and the
cross~reference

map

with

the

includes

line:
DCL>LINK/CROSS/NOWIDE FILE,FILEA,FILEB

>
TKB creates both FILE.TSK
cross-reference listing.

and

FILE.MAP.

4-5

The

map

BUILDING AND TESTING A TASK
Here is the same procedure, as performed from an MCR terminal:
MCR>TKB ,FILE/CR/-SP/-WI=FILE,FILEA,FILEB

>
The right side of the equal sign is the input object module
{or
concatenated object module or multiple object modules).
The left side
of the equal sign in the command line specifies the map file name,
to
which TKB appends the file type MAP.
The comma preceding the map file
name suppresses the creation of the task image file.l
To create a new version of the task image file when you request the
map and global cross-reference listing, type the command as follows:
MCR>TKB FILE,FILE/CR/-SP/-WI=FILE,FILEA,FILEB

>
TKB creates both files.
The designation /CR tells TKB to generate a request for the CRF task
to produce a global cross-reference listing. The designation /-WI
reduces the width of the listing from 132 columns to 80 columns for
display on a terminal. The CRF task executes the request from TKB and
appends the global symbol cross-reference listing file to the end of
the map file.
The global cross-reference in the map listing is
denoted by the title GLOBAL CROSS REFERENCE.
NOTE
If,
after
you
request
a
global
cross-reference listing, you discover
that the map does not have one, the CRF
task is either not installed on the
system or still processing the request.
Consult the system manager to have the
CRF task installed.

4.3.2

Examining the Map at the Terminal

Use the DCL TYPE command, as described in Section 3.4, to examine
map at your terminal.
Here is the command line:

the

DCL>TYPE FILE.MAP
(file appears on screen)

>
From an MCR terminal, use the following PIP command line, as described
in Section 3.4, to examine the map at your terminal:
MCR>PIP TI:=FILE.MAP
(file appears on screen)

1. The task image specification is null when a comma appears first
in
the command line.
If you omit the comma, TKB treats the file name for
the map as a task image and generates a syntax error because the
designation /CR/-SP is illegal with a task image file.
4-6

BUILDING AND TESTING A TASK
Use the control commands CTRL/S, CTRL/Q, and
Table 3-1, to control the terminal output.

4.3.3

CTRL/O,

summarized

Requesting a Full Map

The map file produced, as described in Section 4.3.1, is a short form
of the map that contains most of the information needed for debugging
tasks. To generate a full form of the map, use the following command
line from a DCL terminal:
DCL>LINK/LONG/MAP:FULL/CRO/SYSTEM_LIBRARY DISPLAY/NOTASK FILE,FILEA,FILEB

>
The /LONG qualifier indicates that you want the LONG form of the map,
and causes TKB to add a "File Contents" section to the maps The /LONG
qualifier implies the /MAP qualifier, but /MAP is used here to give
the map file for the name FULL.MAP so that you can tell apart the maps
you have made for this demonstration session.
The /CRO is the
abbreviated
form
of
the
/CROSS REFERENCE
qualifier.
The
/SYSTEM LIBRARY DISPLAY qualifier (usually abbreviated to /SYS)
tells
TKB to- include system library contributions to the task in the file
contents section of the map.
(System symbols are also included in the
global cross-reference listing.)
To generate a full form of the map from an MCR terminal,
command line to TKB as follows:

specify

the

MCR>TKB ,FULL/-SP/-SH/MA/CR=FILE,FILEA,FILEB

>
The comma without a task image file name indicates you do not want TKB
to build a task. The name FULL for the map file is used here to give
that file the name FULL.MAP so that you can distinguish it from other
maps
you
have created as part of these demonstrations.
The
designation /-SH indicates that you do not want the short form of the
standard map. TKB therefore includes the file contents information in
the map. The designation /MA tells TKB to include system library
contributions to the task in the file contents section of the map.
{System symbols are also included in the global cross-reference
listing.)

4.4

RUNNING THE TASK AND CORRECTING TYPICAL ERRORS

You execute your task by using the RUN command and
task image file.I For example:

the

name

the

>RUN FILE
Because the task FILE is not installed on the system, the RUN command
searches your UFD on device SY:
for a file named FILE.TSK. RUN
installs it temporarily and runs it immediately.
(The task will be
automatically removed when the task exits.)

1. Both MCR and DCL include a RUN command, each of which has many
formats.
The form shown in the example is perhaps the most widely
used form for program development. This form, which is the same in
MCR and DCL, runs a task from a task image file in your UFD. See the
RSX-llM/M-PLUS MCR Operations Manual or the RSX-llM/M-PLUS Command
Language Manua-1--for more information on the functions of the RUN
command.
4-7

BUILDING AND TESTING A TASK
To run task FILE, the Executive transfers control to the task
starting, or transfer, address.
If your task encounters an error
condition, the Executive must decide whether to abort the task.
Errors that can cause the Executive to abort a task are either
hardware related or software related.
If the error is hardware
related, such as a memory parity error or a load failure,
the
Executive begins aborting the task.
In contrast, a synchronous system
trap (SST) error condition, such as an illegal instruction, causes the
Executive to attempt to transfer control to an SST routine. An SST
routine is a routine within a task that services a particular type of
SST condition.
If your task defines a routine to service the type of
trap, the Executive transfers control to it. If your task does not
have the routine defined, the Executive aborts the task.
Aborting a task forces an orderly termination of the task.
Included
in the termination is a request for the Task Termination and
Notification (TKTN) to display a message on your terminal.
The
program display includes the cause of the abort and a list of the task
registers and Processor Status Word (PS). For example:
14:16:26

Task
"TT30 n terminated
Odd address or other trap four
RO=OOOOOO
Rl=l00103
R2=147100
R3=140130
R4=000000
RS=OOOOOO
SP=OOll 72
PC=000003
PS=l70017

>
The information can help you ascertain the cause of the abort.l If the
cause of the error is hardware related, report the occurrence to your
system manager, who can consult the error-logging data to find where
the problem originated.
If the cause of the error was an SST
condition, you can use the data displayed by TKTN to find the problem.
The value of the program counter (PC) (minus 2) shown in the display
tells you the address of the instruction that was being executed when
the error was encountered.
In the example shown above, the PC is at
an odd address (000003). By examining the task map, you can ascertain
that the PC address is not within the task code.
This condition
demonstrates one of the more common error conditions. The main module
NUMA source file FILE.MAC does not define a task transfer address.
The
.END directive :in a so1Jrce fiJP, 11sed to define the starting
address of a task, does not have the address symbol of the first
instruction.
If you omit the starting address definition, TKB
supplies a default transfer address of 1. When you run the task, it
causes an odd address trap and terminates.
(Note that the PC has been
incremented to 000003 because it is pointing to the next instruction
in the code.)
Therefore, you should ensure that the source file
defines a starting address and that the address is even
(on a word
boundary) •
To correct any errors in your task, you must edit the source file(s)
concerned, reassemble the corrected file(s), and rebuild the task.

1. The format
RSX-llM-PLUS.

the

information

4-8

varies

between

RSX-llM

and

BUILDING AND TESTING A TASK
For example:
MCR>EDI FILE.MAC
[00103 LINES READ IN]
[PAGE
l]
*L ~ .END
.END
*C /D ~ /D ~ START/
.END
START
*EX
[EXIT]

TELL ASSEMBLER END OF CODE
TELL ASSEMBLER END OF CODE

>MAC FILE,FILE/-SP=FILE
>TKB FILE,FILE/-SP=FILE,FILEA,FILEB
>RUN FILE
ABCABCABAB
THE NUMBER OF A'S IS 0004

>
After you correct the errors and rebuild the task, you can run the
task again. The task reads the line of text that you type, counts the
number of As, displays the result, and exits.
The typical errors made in programming result in an SST condition.
The common conditions are either an odd address or a memory protection
trap.
Most of these errors occur when you use relative mode
addressing instead of immediate mode. For example:
MOV
MOV

iBUFl,RO
OFFSET(RO) ,Rl

The immediate mode reference #BUFl moves the address of BUFl into
register o. If you omit the number sign (#), however, you incorrectly
specify relative mode addressing, as follows:
MOV
MOV

BUFl,RO
OFFSET(RO),Rl

This instruction moves the contents of BUFl and not the address of
BUFl into RO. The subsequent indexed mode reference generates either
an odd address or memory protection trap.
(Your task is attempting
either to illegally reference an odd address or to reference a
location outside task memory). This type of error occurs often when
you are using system directives that require parameters as immediate
mode references, and when you omit the number sign from a parameter
that makes the reference relative.

4.5

GUIDE TO FURTHER READING

4-9

BUILDING AND TESTING A TASK
Document
RSX-llM/M-PLUS Task Builder Manual
Section 1.1, The Task Command Line
Section 10.1, Switches
Section 11.1, Options
Appendix G, The Fast Task Builder (FTB)
Appendix H, Error Messages
RSX-llM/M-PLUS Utilities Manual
Chapter 3, Peripheral Interchange Program (PIP)
Appendix B, The Cross-Reference Processor (CRF)

4-10

CHAPTER 5
USING DEBUGGING AIDS

This chapter introduces three debugging aids that are helpful
in
program
development
process:
the On-Line Debugging Tool,
Postmortem Dump, and the snapshot dump.

5.1

the
the

THE ON-LINE DEBUGGING TOOL

The On-Line Debugging Tool (CDT) is a special code that you include in
your task image to assist you during debugging.
ODT gives you
interactive control of task execution, and allows you to
set
breakpoints and to examine and change data and instructions within the
memory-resident task. The ODT module is linked into your task image,
thereby increasing the size of the task image. Therefore, you remove
ODT from your task when you finish debugging by rebuilding the task
and omitting the ODT module.
ODT commands differ from commands in other utility programs.
Most
programs
have
multiple-character commands that require a line
terminator before they are executed.
ODT commands, however, are
single characters and require no line terminator.
That is, ODT
interprets input on a character-per-character basis rather than on a
line-by-line basis.
Therefore, as soon as you type a character that
ODT recognizes as a command, ODT interprets it and performs the
specified function.
This difference in commands means that you must
be careful when you are debugging your task with ODT.

5.1.1

Including ODT in a Task

The /DEBUG qualifier to the LINK command is used to include ODT
task.
Here is an example:

DCL>LINK/DEBUG/TASK:BUG/MAP:BUG/CROSS_REFERENCE FILE,FILEA,FILEB

>
The /DEBUG qualifier specifies that you want to include ODT in the
task.
The /TASK:BUG quaiifier specifies that you want the task image
file to be named BUG.TSK. The /MAP:BUG qualifier specifies that you
want the map to be named BUG.MAP.
In this way, you can tell the
difference between the versions of the task-built file with ODT and
without. The Task Builder (TKB) accesses the file LB:[l,l]ODT.OBJ and
links it into the task. The /CROSS REFERENCE qualifier implies a /MAP
qualifier. An accurate map of the task is necessary for use with ODT.

5-1

USING DEBUGGING AIDS
To include ODT in a task from an MCR terminal,
similar to the following:

type

command

line

MCR>TKB BUG/DA,BUG/CR=FILE,FILEA,FILEB

>
The designation /DA accompanying the task image file specification
tells TKB to include ODT.
TKB accesses the file CDT.OBJ in UFO [1,1]
on the library device and links it into the task BUG.
You should
request a map of the task because an accurate map is necessary for use
with ODT.

5.1.2

Preparing to Use ODT

Before you run a task containing ODT, ensure that accurate listings of
the assembled source files are available. These listings show the
offsets into the modules in your task. The map of the task and the
assembled source listings provide the data you need to set breakpoints
and examine locations within the task.

5.1.3

Setting up the Task

When you run a task containing ODT, ODT gains control, identifies
itself (and the task it controls), and prints its command prompt. The
following lines show the sequence:
>RUN BUG
ODT:TT30
The notation TT30 is the name that the system dispatcher assigned to
the task. Such a name consists of the letters TT followed by the unit
number of the terminal that requested the task.
(The task shown here
was run from terminal number 30 (8).)
The underline character ( ) is ODT's prompt.
ready to accept commands.-

5.1.4

It indicates that ODT is

Relocation Registers

To access locations within the task, you should establish one or more
relocation registers.
This set of eight registers, numbered $RO
through $R7, allows you to specify locations within the task in terms
of offsets from the start of modules in the task image.
To establish the proper addressing using offsets, you must first
consult the location information in the task map.
On the map
printout, the portion titled Memory allocation synopsis contains the
location
information
for
each
program section and for each
contribution to the program sections from different modules. A sample
of the relevant portion of the map for the program BUG is shown in
Example 5-1.

5-2

USING DEBUGGING AIDS
Example 5-1

Memory Allocation Synopsis from Task BUG Map

HeaorY allocation synopsis!
Section

-------

BLK.!<Rw,1,LcL,REL,coN>

DATA

!<RW,D,LCLrRELrCON>

$$$0DT!<RW9IPGBLPREL,OVR)

Title
001202 000340 00224 •
001202 000122 00082. NUMA
001324 000110 00072. TT READ
001434 000106 00070. TTWRIT
001542 000166 00118.
001542 000156 00110 + NUMA
001720 000004 00004. TT READ
001724 000004 00004. TTWRIT
001730 005654 02988.
001730 005654 02988. ODTRSX

I dent

File

01
01
01

FILCON.OBJ 1
FILCON.OBJ 1
FILCON.OBJ 1

01
01
01

FILCON.OBJH
FILCON.OBJ;1
FILCON .OBJH

H06

ODT.OBJ9121

The location information for a program section is the octal starting
address of the program section and its extent in bytes (both octal and
decimal values). For example, for the blank program section, the
starting location is 1202 (8) and the extent is 340 (8), or 224 (10),
bytes. Under the program section location information are the octal
starting aaaresses ana extents in bytes for the contributions from
each object module. For example, the contribution from TTREAD in the
blank program section starts at location 1324 and extends for 110 (8),
or 72 (10), bytes.
The following example shows how to place the starting addresses of the
modules in relocation registers:
1202;0R
1324;1R
1434;2R
1542;3R
1720;4R
_1724;5R
The R commands place the addresses in relocation registers 0 through
5.
(The addresses are octal; ODT accepts only octal numbers.) As
soon as you type the R in the command line, ODT generates line feed
and carriage return operations and prints another prompt. This action
indicates that ODT has executed the command as soon as it was typed.
Therefore, before typing the R (or any command), ensure that the
command line is correct.
If you notice a typographical error in the line before you type the
command itself, simply type either CTRL/U, the number 8 or 9, or the
DELETE key, as shown in the following example:
1272; 08?
ODT considers the decimal number 8 an iiiegai character. L~ discards
the input line, displays a question mark (?) to signal an error, and
prints the prompt on a new line. You must retype the entire line. If
you do enter an incorrect address in the relocation register, simply
retype the command, as follows:
1272;0R
1202;0R
ODT stores the most recently entered value in the register.

5-3

USING DEBUGGING AIDS
To access a location within a task most conveniently, you must create
an address made up of the values stored in the relocation register and
a value showing the distance of the location from the relocation
register value.
The relocation register provides the base address of a module;
the
location counter value supplies an offset to the location within the
program section for the module.
The command 1202;0R places the
starting address of the NUMA contribution to the blank program section
in relocation register O.
Location counter value 20 in the assembly
listing for NUMA is 20 bytes from the start of the address in
relocation register O. You use the two values to form the address of
the location.
The address is formed by typing the number of the
relocation register, a comma (,), and the octal offset value.
For
example:
0,20
ODT adds the base value in relocation register 0 (1202 in this case)
and the offset typed after the comma (20). This creates an effective
address of 1222 (8). You use this syntax with various ODT commands to
access locations within the task address space.
Example 5-2 shows a portion of the assembly
program section in the module NUMA.
Example 5-2

Portion of

NUMA
COUNT NUMBER OF A'S
ROUTINE TO COUNT A'S
66
67 000000

MACRO H1200

for

the

blank

Listing for NU~-~
PAGE 3

8-AUG-Bl 12 :39

.SBTTL
.PSECT

ROUTINE TO COUNT A'S

START:

68 000000

5.1.5

A~~P.mbly

listing

69 000000
70 000004
71 000010
72 000014

012700
012701
004767
005702

HOV
HOV
CALL
TST

tBUF1 ,RO
tSIZ,R1
READ
R2

LOAD BUFFER ADDR
LOAD BUFFER SIZE
READ FROH TTY
ANY CHARS IN BUFFER?

73 000016

001436

!!E9

END

IF NONE• FINISH UP

74 000020
75 000022
76 000026
77 000026
78 000032
79 000034
80 000036
Bl 000036
82 000040

005001
010267

CLR
HOV

R1
R2rNUKC

INIT t OF A'S COUNTER
SAVE t OF CHARS TYPED

CHPB
BNE
INC

<RO>+ rA
20$
R1

IS CHAR = A?
IF NO, BET NEXT CHAR
COUNT AN A

DEC
BNE

R2
10$

ONE LESS CHAR
IF HORE, COMPARE NEXT

10$:
122067
001001
005201
20$:
005302
001372

Examining Locations

To examine words within a module, type the
slash (/) character, as follows:

address

followed

the

_0,20/005001
The slash character causes ODT to open the designated
word and display its contents.

5-4

location

USING DEBUGGING AIDS
To close the currently open location, type either the RETURN key or
the LINE FEED key. The RETURN key closes the location, as shown in
the following example:
_0,20/005001 ~

ODT closes the location and prints its prompt on a new line.
Once you have opened a location, typing the LINE FEED key enables you
to examine successive words in the task image. The following example
shows the procedure:
0,32/001001 (bf)
0,000034 /005201 ~

In response to the LINE FEED key, ODT closes the current location,
opens the next sequential location in the task image, and displays the
address of the location, a space, the slash character, and the
contents of the location.
The slash character signals that the
location is open as a word.
NOTE
You can change the contents of the
currently open location to n by typing
the octal number n before typing the
RETURN or LINE FEED key. See Section
5. L 7.

To examine bytes within a task instead of words, type
followed by the backslash (\) character, as follows:

the

address

_0,32\001

The backslash character causes ODT to open the designated location as
a byte and display its contents. You can examine successive bytes by
typing the LINE FEED key, after which ODT closes the currently open
byte location, opens the next sequential byte location, and displays
its contents. For example:
32\001 (bf)
0,000033 \002 ~

The backslash character preceding
location is open as a byte.

the

contents

signals

that

the

Before you proceed in the debugging session, you should verify the
relocation register values by examining a location in each module and
comparing its contents with the values shown in the assembly listing.
The following sequence shows the procedure:
1,66/002403 IBm
-2' 72/000207 ~
-3,121\124 (B@
-4,0/000000 ~
=5,0/000000 (B@

As you examine each location, compare the contents ODT displays with
the assembly listing. If the values do not match, either you have an
incorrect listing or the relocation register value is wrong.
5-5

USING DEBUGGING AIDS
5.1.6

Setting Breakpoints Within the Task

To allow you to stop (or break) task execution, ODT provides eight
registers called breakpoint registers. These registers, numbered $BO
through $87, let you specify locations of instructions at which
execution should stop.
To establish breakpoints in the task, specify the location of the
instruction with the B command in the format a;nB, as in the following
example:
O,lO;OB
=l,74;1B
The command places the designated addresses in breakpoint registers
and 1.

NOTE
In specifying
the
address
of
an
instruction, ensure that the location is
the first word of the instruction.
As soon as you type the B in the command line, ODT generates the
carr1aga rsturn auu line feed operations and prints a prompt.
(Changing a breakpoint register is the same as changing a relocation
register;
simply retype the command line and give the altered
contents.)
After setting up the breakpoint registers, you can issue
command to begin task execution. For example:

the

(Go)

G
OB:0,000010
When you type the G command, ODT swaps a BPT instruction into each
breakpoint location.l ODT passes control to the starting address of
the task. The task executes until it reaches a BPT instruction, at
which point ODT regains control. When ODT regains control, the task
has not yet executed the instruction at the location where the
breakpoint is set. ODT swaps the instructions back into the locations
at which breakpoints are set, and prints a message giving:
•

The breakpoint register designation

•

The relocation address at which execution stopped

In the example above, the message shows breakpoint register 0 and its
contents (offset 10 from the base address in relocation register 0).

1. The eight breakpoint instruction registers, with register names $IO
through $I7, contain the actual instructions during task execution.
5-6

USING DEBUGGING AIDS
5.1.7

Changing the Contents of Locations with ODT

When execution stops at a breakpoint, you can examine and change data
within the task image address space.
When execution stops at a
breakpoint location, the task's general registers are stored in ODT
locations accessed by the names $0 through $7. The following sequence
shows a way to display general registers O, 1, and 2:
$0/ 001543

$1 /000120

$2 /135600

The slash (/) character opens the general register as a word location
and prints its contents. Typing the LINE FEED key closes the current
location and opens the next sequential location.
To change data, simply type a new value while the current location is
open. The following sequence shows a way you can change register 2:
_$2/ 135600 100

$3 /140130 (Brn
While the location (register 2) is open, you can type the new value to
replace the current contents. ODT writes the new value 100 (8) into
the currently open location before closing it and opening the next
sequential location.
Any locations within the task can be examined and changed.
The
following sequence shows a way to open a location as a byte and change
its contents:
3, 0\101 102 (Brn
3, 0\102 101 (Brn
The backslash (\) character opens the specified address as a byte
location.
The new value 102 (8) is written to the open location as a
byte value. Typing the RETURN key closes the location.
The next
command line examines offset 0 to verify that it contains 102 (8) and
then changes the contents back to 101.
After you examine and change locations, resume execution
(Proceed) command, as follows:

with

the

PABCABCABAB (Brn
TB:l,000074
The P command causes ODT to .swap in the BPT instructions, restore the
task general registers, and continue with the instruction at which the
break occurred.
NOTE
ODT does not supply a carriage return
and line feed after you type the P.
Therefore, the data that you type in
response to the READ routine will follow
the P on the same line.

5-7

USING DEBUGGING AIDS
Execution stops at the location contained in breakpoint register 1.
The G command is used to transfer
continue execution. For example:

control

another

address

and

_l,76G
ODT transfers control to offset 76 and continues execution there.
This command purposely tranfers control to the error routine to show
what occurs when an error is encountered. See Section 5.1.8.

5.1.8

Error Conditions and Terminating Task Execution

If the task generates an error condition, the Executive handles the
processing as a synchronous system trap (SST). Control is passed to
ODT, which prints a message similar to the following one:
!0:2,000000

This message gives a code describing the reasons for the trap and
tells the address following the location that generated the trap. In
the message above, IO means the !OT instruction. If you can discover
the cause of the trap, make the appropriate changes in the task and
proceed. If you cannot isolate the cause of the trap, you should exit
from ODT and start ~ new debugging session.
To help ascertain the cause of the trap, you can examine the task
registers and stack before you start a new debugging session. Use the
register name -- the dollar sign ($) followed by the register number
to access the task registers as described in Section 5.1.7. To
examine the stack, examine register 6 (the stack pointer) and use the
at sign (@) to open the location pointed to by the stack pointer. For
example:
$6/001200 @
001200 I 001216 ~

The slash (/) character opens the stack pointer as a word and displays
the address of the top of the stack. The at sign character (@) takes
the contents of the currently open location (that is, the stack
pointer) as the address of the next location to be opened, opens it,
and displ~ys its contents, which is the top word on the stack.
To exam!n~ Lh~ sLdck, Lype cne Li~~ FE~LJ key to open and display each
successive word on the stack. You can ascertain the highest address
the stack can have by consulting the line labeled Stack limits in the
task attributes section of the map. The line gives four numbers: the
low address of the stack area, the high address of the stack area, and
the octal and decimal extent of the stack area. The high address
tells you the last available location (that is, the bottom) of the
stack.
After you have examined the highest address, you have looked
at all the items on the stack and can type the RETURN key to close the
last available location.
To exit from the task by means of ODT, use the X command as follows:

x
ODT performs the exit
Executive.

task

directive

5-8

and

returns

control

the

USING DEBUGGING AIDS
5.2

POSTMORTEM DUMP

Another debugging aid is the Postmortem Dump (PMD).
It requires no
special code in your program. The examples show how to enable PMD for
your task using either the /POSTMORTEM qualifier or the /PM qualifier.
These qualifiers set a bit in the task flag word that causes a PMD
whenever the task exits unexpectedly.
To enable PMD from a DCL terminal, type the following command line:
DCL>LINK/MAP/POSTMORTEM FILE,FILEA,FILEB

>
From an MCR terminal, use the following command line:
MCR>TKB FILE/PM,FILE/-SP=FILE,FILEA,FILEB

>
The /POSTMORTEM qualifier in the LINK command is the equivalent of the
/PM in the TKB command after the task image file name. In either
case, TKB is instructed to set a bit in the task flag word.l (You can
tell whether a task includes PMD by inspecting the task attributes
section of the map. A line item called Task attributes will have the
designation PM.) When PMD is in effect for a task, the occurrence of
an error that generates a synchronous system trap (SST) causes the
Executive to handle the termination of your task in a special
manner.2 Instead of simply aborting the task, the Executive generates
a request for PMD to create a formatted disk file showing the task
image context. When a task generates a synchronous system trap, the
Executive
initiates the normal task termination procedure (the
printing of an error message and general register contents at the
terminal) and additionally generates the request for PMD. To inform
you that a dump is in effect, the Executive causes the following
message to appear at the terminal:
Pest mortem dump will be generated
PMD receives the request, creates a file in UFO [1,4] on the library
device, and generates a request to the spooler to print the file. The
file has the name of the task and a type of PMD.
The print spooler
automatically deletes a file with the file type PMD after it is
printed.

5.3

THE SNAPSHOT DUMP

The snapshot dump capability is a subset of the Postmortem Dump task
but requires special code in the task. Whereas PMD generates a dump
of an entire task, the snapshot dump can produce a dump of only a
portion of the task. Also, PMD generates a dump only when the task
terminates abnormally, but the snapshot code can produce a dump at any
place in the task execution.

1. You are not limited to specify PMD at the time you build the task.
Postmortem dumps can also be specified as part of the RUN, INSTALL,
and ABORT commands. See the RSX-llM/M-PLUS Command Languaie Manual or
the RSX-llM/M-PLUS MCR Operations Manual for more information.
2. This discussion assumes that the task does not handle synchronous
system traps through the SVTK$ directive and specially coded routines.
5-9

USING DEBUGGING AIDS
You include the necessary snapshot code in the task by editing the
source file and inserting the snapshot macro calls where you want to
produce a dump.l After you reassemble the modules containing the
snapshot calls,
rebuild the task and substitute the reassembled
modules. When you use snapshot macro calls, you do not need any
special switches or options for TKB.
When you run the task and that section containing the special code is
executed, a snapshot dump is taken. The special code generates a
request for the PMD task.
(No special messages are printed at the
terminal.)
To hold the dump, PMD creates a file with the name of the
task and a file type of PMD in the UFD that is the same as the UIC
under which the task is running.
PMD then generates a request for the
spooling task to print and delete the file.

5.4

GUIDE TO FURTHER READING

The sections or chapters in the following documents contain additional
information on the subjects described in this chapter.
Document
RSX-llM/M-PLUS Task Builder Manual
Appendix D, Memory Dumps
Section D.l, Postmortem Dumps
section D.2, Snapshot Dumps
IAS/RSX-11 ODT Reference Manual
Section
Section
Section
Chapter
Section
Chapter
Section
Section
Section

1.2, Linking ODT with a User Program
1.4, Returning Control to the Host System
2.2.1, Absolute and Relative Addressing
3, Controlling Program Execution
3.1, Setting and Removing Breakpoints
4, Displaying and Altering the Contents of Locations
4.10, Using Different Output Modes
5.2.l, Relocation Registers
7.1, Calculating Relocatable Addresses

1. The snapshot macro calls the PMD task as described in
of the RSX-llM/M-PLUS Task Builder Manual.
5-10

appendix

CHAPTER 6
CREATING AND USING PROGRAM LIBRARIES

This chapter describes the procedures to create and maintain a library
of macro source statements and a library of object module subroutines.
It also shows how to include in your task image the macro call
definitions and the object subroutines from user-created libraries.
The decision about whether to implement specific code as a macro call
or as an object module subroutine is left to the designer.
In
general, the difference between implementations is a tradeoff of
assembly time versus linking time and, secondarily, convenience versus
size. Each time your source file invokes a specific macro call, the
assembler must include the macro expansion in the object module.
However, when your program calls an external
subroutine,
the
resolution of the call is done during linking. Moreover, using the
macro call to generate in-line code is convenient, but each invocation
of the call increases the size of the resulting task image. However,
if your program calls a specific external subroutine more than once,
the subsequent invocations do not include that code in the task.

6.1

CREATING AND USING A MACRO SOURCE LIBRARY

The Librarian Utility Program (LBR)
creates and maintains library
files that can contain macro definitions, object modules, or other
elements. DCL users can invoke LBR functions through the LIBRARY
command.
MCR users can invoke LBR functions through the LBR command.
This section discusses creating a library file of macro definitions.
Such a file has the default type MLB and contains only macro
definitions.

6.1.1

Creating the Macro Library

Here is how to create a macro library from one input
definitions using the DCL LIBRARY/CREATE command:

file

source

DCL>LIBRARY/CREATE:(BLOCKS:25,MODULES:l28)/MACRO
Library? USRMAC
Module(s)? USRMAC

>
or
DCL>LIBRARY/CREATE:(BLOCKS:25,MODULES:l28)/MACRO USRMAC USRMAC

>
The /CREATE qualifier identifies the LBR function you want to invoke.
The arguments to /CREATE specify features of the library you are
creating. Because there is more than one argument, they are enclosed
in parentheses and separated by commas. The argument BLOCKS:25 gives
6-1

CREATING AND USING PROGRAM LIBRARIES
the length in blocks for the library file.
(DCL uses the decimal
value automatically for all LIBRARY command arguments.) If you omit
this argument, LBR creates a file 100 blocks long by default.
The
argument MODULES:l28 indicates the number of module name table entries
to allocate for this library.
(Each macro definition in the library
requires an entry in the module name table.) The /MACRO qualifier
identifies the type of library you wish to create. The default type
is /OBJECT (to create an object module library).
The Library? prompt requests that you name the library to be created.
For macro libraries, the default file type is MLB. The Modules?
prompt requests you to name the file or files containing the macro
definitions.
The default file type for this parameter is MAC.
(If
you do not name a file here, LBR creates an empty file.)
There is further discussion of how LBR creates a library included in
the MCR command description. Here is the MCR command line to create a
macro library:
MCR>LBR USRMAC/CR:25.::128.:MAC=USRMAC

>
The designation /CR tells LBR to create a library file.
LBR creates
the library file USRMAC.MLB. For input to the library file, LBR uses
the file or files specified to the right of the equal sign.
In
Example 6-1, the input file is USRMAC.MAC.
Example 6-1

MACR0-11 Library Source Definitions

SAVE - STORES REGISTER ON STACK
.MACRO
HOV
.ENDM

SAVE,REG
REGr-<SP>

PUSH REG ONTO STACK

RESTOR - POPS REGISTER VALUE OFF STACK
.MACRO RESTOR,REG
MOV
<SP>+•REG
.ENDH
+END

POP REG OFF STACK

Following the designation /CR in the command line are parameters,
9ep?r2ted by colons, that LBR ~scs tc crc~tc the library.I The first
parameter, 25 (decimal), gives the length in blocks for the library
file.
If you omit this parameter, LBR uses 100 (decimal) blocks as
the default length. When creating the library file, you can allow for
some future additions to the library by making the size larger than
necessary.
(LBR will expand a library file as needed if you add
modules that will cause the file to exceed its original size.
However, the library will no longer be contiguous.) The second
parameter is blank because it applies only to object libraries. The
third parameter, 128 {decimal), is the number of module name table
entries to allocate for this library. {An entry in the module name
table is required for each macro definition.) Following the third
parameter is the type of library to create (MAC for macro definition).

1. The numeric parameters are followed by decimal points to force LBR
to interpret them as decimal numbers. If you omit the decimal points,
LBR treats the numbers as octal.
6-2

CREATING AND USING PROGRAM LIBRARIES
You must specify this parameter
library.

because

the

default

object

In creating the macro library, LBR allocates the requested amount of
contiguous
file space.
If sufficient contiguous space is not
available, LBR generates the OPEN FAILURE error and terminates.
To
have the library created, you must either free up some space on the
volume or try a smaller library size.
When the library file is created, LBR attempts to insert into the
library the macro definitions from the input file.
LBR searches the
input file for .MACRO directives and .ENDM directives.
If the macro
definitions are nested, only the outermost directives are directly
callable from the library. From each macro definition, LBR extracts
the name and creates an entry in the module name table. The entry in
the module name table is the means by which the assembler finds the
associated macro definition in the library. Any code or comments
outside the directives are discarded and all trailing blank and tab
characters, blank lines, and comments are eliminated from the macro
text itself.
{This action, called squeezing, conserves memory for the
assembler
and
reduces
the space required to hold the macro
definitions.) Errors occurring during the insertion of definitions
usually indicate improper definitions, such as a missing .ENDM
directive.

6.1.2

Using the Macro Definitions from the Library

Once the macro definitions are in the library, you need perform only
three actions to have the assembler include the macro expansions in
your code.
1.

Include the name of the macro in a .MCALL directive
program source filec

Invoke the macro call within the source file.

Specify the name of the library file in the command
the assembler.

your

line

Thus, to invoke the two macro library definitions SAVE and RESTOR in
your program, precede the macro calls themselves with a statement such
as the following:
.MCALL

SAVE,RESTOR

; CALL DEFINITIONS FROM USRMAC

This statement should preferably occur at the start of the source
file.
When you assemble a source file that refers to a library file,
you must name both files in your DCL MACRO command line. Here is an
example:
DCL>MACRO USRMAC/LIBRARY, USRTST/LIST
The name of the macro library can appear anywhere but last in the list
of input files and must be marked with the /LIBRARY qualifier. The
next file named is the first source file.
There is further discussion of how LBR creates a library.
Use
f~llowing MCR command line to include a library in an assembly:

the

MCR>MAC USRTST,USRTST/-SP=USRMAC/ML,USRTST

>
To the right of the equal sign in the command line, specify the name
of the macro library and the designation /ML.
The comma separates the

6-3

CREATING AND USING PROGRAM LIBRARIES
macro library file name and the source file name. The designation /ML
indicates to the assembler that the file is a macro library. The name
of the macro library must precede the source file that refers to the
macro definitions.
NOTE
If the library specification follows the
source file name in the command and the
corresponding definitions are not in the
system macro library RSXMAC, MACR0-11
does not recognize the library file and
generates assembly errors in the lines
that
contain
calls
to
library
definitions.
To process the macro calls in the source file, the assembler uses the
names given in the .MCALL directive to generate symbols for the macro
symbol table.l To expand the macro calls not defined in the source
file,
the assembler searches the library you specified before it
searches the system default macro library. MACR0-11 does not search
the system macro library for definitions that are found in the user
library file.

6.2

CREATING AND USING AN OBJECT MODULE LIBRARY

LBR may be used to create a library file containing object modules.
Such a file has the file type OLB (object library) as a default and
can contain only object modules.

6.2.1

Creating the Object Module Library

To create an object module library, you must have a file or files that
contain the object modules ~o o~ inserted into the library. The
following command creates the object library and inserts the modules
FILEA.OBJ and FILES.OBJ. Here is the DCL command to create an object
module library consisting of the object modules in FILEA.OBJ and
FILES.OBJ:
DCL>LIBRARY/CREATE:(BLOCKS:25,GLOBALS:l28,MODULES:64)/0BJECT
Library? USROBJ
Modul~(~)?

~TtFai~!T~R

>
or
DCL>LIBR/CRE:(BL0:25,GLOB:l28,MOD:64)/0BJ USROBJ FILEA,FILEB

1. If you omit the name of the macro call from the
.MCALL directive,
the assembler cannot recognize the call itself in the code.
(A
corresponding entry is not in its macro symbol table.)
It treats an
unrecognized macro call as an implicit .WORD directive.
If the macro
name is not a valid symbol, its usage is flagged as an undefined
reference by TKB.
6-4

CREATING AND USING PROGRAM LIBRARIES
The /OBJECT qualifier is not required because it is the default, but
it is a good idea to include it. The default file type for an object
module library is OLB. The default file type for the object module
files is OBJ. The arguments to /CREATE are the same as those used in
creating a macro library with the addition of the GLOBALS argument,
which
applies to object libraries only.
The GLOBALS argument
specifies the number of entry point table slots to reserve.
(An entry
point is any global symbol in a module by which your program refers to
the associated module.) If you do not supply a value, LBR defaults to
GLOBALS:512.
If you supply a value of O, you can maintain modules
with duplicate entry points in the same library.
The names of the
modules must still be unique. When building a library with GLOBALS:O,
you must specify the correct module names to TKB when you build your
task.
See Section 6.2.2. A good estimate for the number of GLOBALS
is twice the number of modules the library will contain.
The value
should be a multiple of 64.
If not, LBR raises the number to the next
multiple of 64. Again, all these numbers are automatically decimal
numbers in DCL.
Here is the MCR command line:
MCR>LBR USROBJ/CR:25.:128.:64a=FILEA,FILEB

>
There is further discussion of how LBR
library in the MCR command description.

creates

object

module

The designation /CR tells LBR to create a library file.
LBR uses the
name preceding /CR as the name of the library and applies the default
file type OLB. Following /CR in the command line are parameters,
separated by colons, used in creating the file.I
The first parameter, 25 (10), gives the size in blocks at which to
create the library file.
If you omit the parameter, LBR supplies 100
(10) blocks as the default size. When creating the library, you can
·allow for future additions by making the size larger than necessary.
(LBR will expand a library file as needed if you add modules that will
cause the file to exceed its original size. However, the library will
no 109ger be contiguous.)
The second parameter, 128 (10), in the command gives the number of
entry point table slots to reserve.2 A good estimate for the number
of entry points is twice the number of modules the library will
contain
(that ·is, two entry points per module).
If you omit this
parameter, LBR supplies 512 (10) as the default number.
If the value
you supply is not an integral multiple of 64 (10), LBR raises the
number to the next highest multiple of 64 (10).
The third parameter, 64 (10), is the number of module name table
entries to create for the library.
(The module name is the means by
which LBR refers to the module code in the library.) If you omit this
parameter from the command line, LBR supplies 256 (10) as the default
number.
If the value y~u specify is not an integral multiple of 64
(10), LBR raises the number to the next highest multiple of 64 (10);

1. The numeric parameters are followed by decimal points to force LBR
to interpret them as decimal numbers.
If you omit the decimal points,
LBR treats the numbers as octal.
2. LBR allows you to build an object library having zero entry points.
This feature allows you to maintain modules with duplicate entry
points in the same library.
(The names of the modules must still be
unique.)
When using such a library, you must specify the correct
module name(s) to TKB when you build your task.
See Section 6.2.2.
6-5

CREATING AND USING PROGRAM LIBRARIES
The last parameter (omitted from the command line above) specifies the
type of library to build. LBR supplies OBJ as the default type.
In creating the object library file, LBR allocates the requested
amount of contiguous space. You can estimate the number of contiguous
blocks that LBR requires by using PIP. Request a directory listing of
all the files to be inserted in the library and use the total number
of blocks PIP calculates.
If sufficient contiguous space is not
available, LBR generates the OPEN FAILURE error and terminates. To
have the library created, you must either free up some space on the
volume or try to build a smaller object library.
When the object library is created; LBR attempts to insert into the
library the object modules from the input file(s). It arranges the
entries in the module name table in alphabetical order by module name.
The module name that LBR uses is the one you specified in the .TITLE
directive when you assembled the object module. The module names and
entry points must be unique.l LBR finds the global symbols in each
object module and enters them in the entry point table. If LBR finds
a module name or an entry point that duplicates one already used, it
prints an error message and stops processing.
If LBR finds an error, it does not insert any modules in the library
from the file containing the error. You must eliminate the error
condition and insert the modules from the corrected file again.
If
LBR does not find any errors, it enters all the modules in the
library. To ascertain what modules were inserted, obtain a listing of
the library as described in Section 6.3.3.

Using the Object Modules from the Library

6.2.2

When the object modules are in the library, you need perform only
actions to have TKB include the routines in your task~

two

Include the CALL x statement in the calling module (where x
is an entry point to the called module). (It is assumed that
the called module has a global statement to define the entry
point.;2

Specify the name of the library file and the
called modules in the command line to TKB.

Thus, to invoke subroutines from the library,
statements are in your program.

ensure

names
that

the

CALL

1. If you suppress including entry points in the library entry point
table, LBR allows you to insert, in the library, object modules having
duplicate entry points. This feature enables you to maintain slightly
different modules of the same general type in the same library@ You
select the correct module by specifying the unique module name to TKB
when you build your task. See Section 6.2.2.
2. CALL is a macro statement that is a permanent symbol in the
MACR0-11 Assembler.
It standardizes subroutine calling conventions.
CALL x translates to JSR PC,x (where x is the subroutine entry point).
6-6

CREATING AND USING PROGRAM LIBRARIES
When you build a task, use a DCL LINK
following:

command

line

similar

the

DCL>LINK/TASK:SUPLIB/MAP:SUPLIB
File(s)? FILE,USROBJ/INCLUDE:(TTREAD,TTWRIT)

>
or
DLC>LINK/TA:SUPLIB/MAP:SUPLIB FILE, USROBJ/INC:(TTREAD,TTWRIT)

>
By including filespecs as arguments to the /TASK and /MAP qualifiers,
you cause the outfiles from the LINK command to be named SUPLIB.TSK
and SUPLIB.MAP, respectively. The /INCLUDE qualifier identifies the
file USROBJ.OBJ as an object library.
The names appearing in
parentheses, after /INCLUDE, are the names of the modules to be
extracted from the library and placed in the task.
(Remember that
these module names are derived from the names given in the .TITLE
directive in the MACRO source files, and not from the file from which
these modules were assembled.)
This method of specifying an object library search is more direct and
faster than the method described in Section 6.2.3.
If you are using a
large library, TKB need only search the module name table for those
object modules you specify.
The disadvantage is that you have the
responsibility to specify the names of all the modules that your task
requires.
If, however, you are using a library with zero entry
points, the /INCLUDE qualifier is the only method of telling TKB which
modules to include from that library.
The following command line is the MCR equivalent
specific object modules from a library in your task:

for

including

MCR>TKB SUPLIB,SUPLIB/-SP=FILE,USROBJ/LB:TTREAD:TTWRIT

>
The designation /LB after a name in the command line indicates to TKB
that the file is an object library. TKB accesses the file USROBJ.OLB
in the UFO that is the same as the current UIC.
The names appearing
after /LB in the command line are the names of the modules to be
extracted from the library and placed in the task. TKB searches the
module name table of the library for these modules.
(Remember that
these module names are derived from the name given in the .TITLE
directive, and not from the file names from which the modules were
created.)
Note that the module names in the command line are preceded by colons,
which are necessary to distinguish the names as library module names.
Placing a comma before a name tells TKB to treat the name as an object
module and to search your UFO for a file with that name and a type of
OBJ. That is, the colon tells TKB to process what follows as an
argument of /LB, and the comma tells TKB to treat what follows as a
file name.
This method of specifying an object library search is more direct and
faster than the method described in Section 6.2,3.
If you are using a
large library, TKB need search only the module name table for those
object
modules
you
specify.
The
disadvantage is that the
responsibility is yours to specify the names of all the modules that
your task requires.
In one situation, this is the only method to use
a library.
If you are using a library with zero entry points, this is
the sole method of telling TKB which modules to include from that
library.

6-7

CREATING AND USING PROGRAM LIBRARIES
6.2.3

Using the Library to Resolve Undefined Global Symbols

Of ten the modules in a task refer to global symbols that are defined
in other modules.
If the modules that define the global symbols
reside in a library, you can have TKB search the library.
In DCL, the
/LIBRARY qualifier on an input file specification for a LINK command
indicates that the entire library is to be searched.
The /LIBRARY
qualifier replaces the /INCLUDE qualifier.
The following example
shows the form of the command line:
DCL>LINK/TASK:LB/MAP:LB FILE, USROBJ/LIBRARY

>
The /LIBRARY qualifier tells TKB to search the library entry point
table for symbols that are referred to but not defined. When TKB
finds a symbol in the table that is unresolved
in the task,
it
extracts the defining module and places it in the task.
If any
symbols remain unresolved after the user library search, TKB searches
the system library.
This method requires less effort on your part than using the /INCLUDE
qualifier, but if you are using a large library, the task build may
take considerable time.
The following command line is the MCR equivalent for using the TKB /LB
switch to search an entire library:
MCR>TKB LB,LB/-SP=FILE,USROBJ/LB

>
The designation /LB with no module names tells TKB to search the
library entry point table for symbols that are referred to but not
defined. When TKB finds a symbol in the table that is unresolved in
the task,
it extracts the defining module and places it in the task.
If any symbols remain unresolved after the user library search, TKB
searches the system library.
This method of specifying an object library search requires less
effort on your part than the method described in Section 6.2.2,
because TKB searches the entry point table to resolve any global
references undefined at that point in th7 processing.
If you are
using a large library, TKB may take longer in searching the entry
point table than if you had specified the names of the modules to
include in your task.

nn~1

----

,,,..,...
--'~

~t:

.....,_

.......... ,..

-··-

.;~ ..... ..._ ..... .

___ .._,.,....,. ... J

In certain circumstances, you may want TKB to definitely include
specific modules from the library and also to search the same library
to resolve any undefined references that may occur. For example, you
may have conditional code in the main part of a task and do not know
what global symbols are referenced. TKB allows you to specify the two
forms of the library search.
In DCL, this can be done by combining
the /INCLUDE qualifier and /LIBRARY qualifiers in the same command
line:
DCL>LINK/TASK:LBOPT/MAP:LBOPT
File(s}? FILE, USROBJ/INCLUDE:TTREAD, USROBJ/LIBRARY

>
or
DCL>LINK/TASK:LBOPT/MAP:LBOPT FILE, USROBJ/INC:TTREAD, USROBJ/LIB

>
6-8

CREATING AND USING PROGRAM LIBRARIES
Once again, the arguments to /TASK and /MAP qualifiers change the
names of the associated output files. The /INCLUDE qualifier on the
file specification for USROBJ.OLB instructs TKB to extract the named
module.
Notice that since only one module is named, the parentheses
are unnecessary. The /LIBRARY qualifier on the file specification for
USROBJ.OLB tells TKB to search that library for any unresolved global
symbols. TKB includes in the task any modules from the library that
are unresolved at that point in the building of the task. If any
unresolved symbols remain after the search of the user library, TKB
searches the system library.
The following command line shows the MCR procedure for specifying
forms of library search to TKB:

two

MCR>TKB LBOPT,LBOPT/-SP=FILE,USROBJ/LB:TTREAD,USROBJ/LB

>
The first appearance of the /LB designation tells TKB to extract the
named module.
The second occurrence tells TKB to search the library
for any unresolved global symbols.
TKB includes in the task any
modules from the library that define the global symbols that are
unresolved at that point in the building of the task.
If any
unresolved symbols remain after the user library search, TKB searches
the system library.

6.3

MAINTAINING USER LIBRARIES

This section decribes three simple operations to maintain a user
library:
adding modules to, replacing a module in, and obtaining
information about the library. MCR users accomplish these ends with
various
commands
to
LBR.
From DCL, use the LIBRARY/INSERT,
LIBRARY/REPLACE, and LIBRARY/LIST commands.

Adding Modules to a Library

6.3.1

Modules can be added to a library
Here is an example:

with

the

LIBRARY/INSERT

command.

DCL>LIBRARY/INSERT
Library? USRMAC.MLB
Module(s)? MAC1,MAC2

>
or
DCL>LIBRARY/INSERT USRMAC.MLB MAC1,MAC2

>
Give the name and type of the library in response to the Library?
prompt. Give the names of the files containing the library modules in
response to the Module(s)? prompt. The default file type for files
containing library modules is the same as for the type of library that
you specify.
You cannot add modules to a library that has no remaining entries in
the module name table. (If you are creating an object module library,
there must be sufficient entry point table slots as well.) When LBR
inserts a module in a library, it checks to be sure that a module of
the same name does not currently reside in the library.
If such a

6-9

CREATING AND USING PROGRAM LIBRARIES
module is found, LBR reports an error and exits.
(For inserting
object modules, LBR also checks for duplicate entry point names.) To
add modules with duplication, see the discussion of LIBRARY/REPLACE in
Section 6.3.2.
From an MCR terminal, modules can be added to a library
command line such as the following:

with

LBR

MCR>LBR USRMAC.MLB/IN=MAC1,MAC2

>
To add modules to a library, specify the name and type of the library
file and the /IN designation (insert) to the left of the equal sign in
the LBR command line. To the right of the equal sign, give the name
of the modules, separated by a comma. You need not supply a file type
because LBR applies the correct type as a default according to the
type of the library you specify.
The library must have a sufficient number of name table entries
available (and, for object modules, entry point table slots). Each
global symbol in an object module requires an available entry point
table slot.
A module name table entry must be available for each
object module and macro definition added. When inserting a module,
LBR checks to ensure that a module of the same name does not currently
reside in the library. If a duplicate name is found, the program
reports the duplicate name and terminates. For object modules being
inserted, LBR also checks for duplicate entry point names.
To add
modules with duplication, yvu must either eliminate the duplicate
names or change the /IN designation to /RP {replace).
See Section
6.3.2.

6.3.2

Replacing a Module in a Library

After you create a library, a typical maintenance function you will
perform is changing and updating modules in the library. Because a
module of the same name {and, for object modules, the same entry
points) already existst you must perform a replace operation.

In DCL, this is done with the LIBRARY/REPLACE command:
DCL>LIBRARY/REPLACE
Library? USROBJ
Module{s)? FILEA
Module "TTREAD" replac~d

>
or
DCL>LIBRARY/REPLACE USROBJ FILEA
Module "TTREAD" replaced

>
This command line causes LBR to logically delete the module TTREAD and
all associated entry points for that name from USROBJ.OLB. LBR then
inserts the new version of module TTREAD from FILEA.OBJ and prints a
message.
If a module to be replaced is not found in the library, LBR
performs an insertion but prints no message.
Note that LIBRARY/REPLACE causes a logical deletion and does not
reclaim the space occupied by the module you replace. To reclaim this
lost space, you should occasionally use the LIBRARY/COMPRESS command.

6-10

CREATING AND USING PROGRAM LIBRARIES
The following command line is the MCR equivalent
replace operation:

for

performing

the

MCR>LBR USROBJ/RP=FILEA
Module "TTREAD" replaced

>
LBR accesses the library file USROBJ.OLB, logically deletes the module
TTREAD and all of the entry points for that name, and inserts the new
version of module TTREAD from the file FILEA.OBJ.
LBR prints a
message telling you the name of each module it replaced. If a module
to be replaced does not exist in the library file, LBR assumes that
the module is to be inserted, automatically inserts it, but does not
print the message.
LBR does not automatically reclaim the space occupied by a module that
you replaced.
Therefore, to reclaim this lost space, you should
occasionally run LBR and compress the library file.

6.3.3

Obtaining Information about a Library

To obtain information about a library from a
LIBRARY/LIST command in the following format:

DCL

terminal,

type

DCL>LIBRARY/LIST:LBLIST/NAMES/FULL
Library? DD.OLB

>
or
DCL>LIB/LIS:LBLIST/NAMES/FULL DD.OLB

>
This command line causes LBR to access the library file DD.OLB.
The
list appears in the file in your UFD called LBLIST.LST. The qualifier
/FULL lists entry points and full information (size, date of creation,
and for object modules, identification).
To list the information on the terminal instead of a file, use the
LIBRARY/LIST command without a file specification argument to the
/LIST qualifier:
DCL>LIBRARY/LIST/FULL USRMAC.MLB
{LBR lists information)

>
To obtain information about a library from an
command line to LBR similar to the following:

MCR

terminal,

type

MCR>LBR DD.OLB,LBLIST/LE/FU/-SP

>
This command line causes LBR to access the library file DD.OLB in the
default UFD.
The comma separates the library file name from the
listing file specification. The designations /LE and /FU tell LBR to
list entry points and full information (size, date of creation, and,
for object modules, identification} in the file LBLIST.LST in the
default UFD. The designation /-SP inhibits automatic spooling of the
listing to the line printer.

6-11

CREATING AND USING PROGRAM LIBRARIES
To list information at the terminal, simply omit the
the command line, as follows:

file

name

from

omit

the

MCR>LBR USRMAC.MLB/FU
(LBR lists information)

>
Because a macro library does not have entry points, you can
/LE designation from the command line.
MCR>LBR [l,l]USROBJ.OLB,[303,lO]LBLIST/LE/FU

>
This command line causes LBR to access the library file USROBJ.OLB in
UFO [1,1]. The comma separates the library file name from the listing
file specification. The designations /LE and /FU tell LBR to list
entry points and full information (size, date of creation, and, for
object modules,
identification)
in the file LBLIST.LST in
UFO
[303,10].
If you omit the UFO specification from the listing file,
LBR creates the listing file in the UFO of the library.
To list information at the terminal, simply omit the
the command line, as follows:

file

name

from

omit

the

MCR>LBR [l,l]USRMAC.MLB/FU

>
Because a macro library does not have entry points, you can
/LE designation from the command line.

6.4

GUIDE TO FURTHER READING

PDP-11 MACR0-11 Language Reference Manual
Section 7.8, Macro Library Directive: .MCALL
Section 8.1.2, MCR Command String Format
Section 8.1.2.1, MCR File Specification Switches
Section 8.1.3, DCL Operating Procedures
RSX-llM/M-PLUS Utilities Manual
Chapter 10, Librarian Utility Program (LBR)

6-12

CHAPTER 7
FORTRAN IV PROCEDURES

PDP-11 FORTRAN IV is one of several high-level languages optionally
available on RSX-llM and RSX-llM-PLUS systems. This chapter briefly
program
development
introduces the product and summarizes its
procedures.

7.1

OVERVIEW OF PDP-11 FORTRAN IV

The FORTRAN IV language processor on RSX-llM and RSX-llM-PLUS consists
of the following elements:
•

The compiler task FOR

•

The DCL FORTRAN command

•

The MCR FOR command

•

An Object Time System (OTS) library

•

An optional resident library

The FORTRAN IV compiler accepts an ASCII disk file containing source
statements, and generates a disk file in object module format and,
optionally, a listing file suitable for printing. The user interface
to the compiler is similar to that of the MACR0-11 Assembler. The
program d~velopment procedures are like those for assembly language
modules:
You supply the object file to the Task Builder (TKB) to
obtain an executable program.
The DCL FORTRAN command parallels in function the DCL MACRO command,
and the MCR FOR command parallels in function the MCR MAC command.
The FORTRAN and FOR commands pass an ASCII source file to the FORTRAN
compiler, and the compiler generates an object module and, if desired,
a listing file.
The program development procedures are very similar
to those for assembly language modules: You pass the object module to
TKB using a LINK command to obtain a file containing an executable
task image.
The FORTRAN IV Object Time System (OTS)
is a collection of object
module subroutines the system uses as needed in creating an executable
program. On systems with more than one high-level language, the OTS
routines for FORTRAN IV must be segregated from those of other
languages. Sometimes, the OTS routines reside in the system object
library SYSLIB.
Regardless of their location, however, the OTS
routines must be accessible to the Task Builder.
The difference to
you is whether the library containing the OTS routines must be

7-1

FORTRAN IV PROCEDURES
explicitly named. If the OTS routines are in SYSLIB, the Task Builder
can locate them without an explicit specification because, as a
default condition, it automatically searches the system library.
The FORTRAN IV compiler does not generate all of the machine code
required by a task at run time. Common sequences of code reside in
the OTS libiary. During compilation, FORTRAN IV flags these common
sequences as undefined global symbois. The Task Builder must then
resolve the undefined references by selecting from the OTS those
modules that resolve the symbols in the object module.
In a narrow sense, the OTS contains the routines that the compiler has
previously designated to be linked into your task. In practice,
however, the OTS can contain various routines, callable by the user,
in
addition to the routines required by the compiler-assigned
references.
As an option, a system installation can have a common area containing
shareable FORTRAN IV OTS routines.
This common area, called a
resident library, contains the most frequently used routines, taken
from the OTS and made available for user tasks to link to and share at
run time. Thus, with a resident library, the Task Builder generates
references to the routines in the resident library that you specify
when you build the task. The Task Builder does not include those
routines in your task image. The routines use virtual address space
in the task but do not require additional physical memory in the task
image.
The resident library, tailored to the needs and requirements
of a particular system, saves task-build time nnd m~mory by the amount
of code that need not be repeated in each memory-resident FORTRAN IV
task.

7.2

FORTRAN IV PROGRAM DEVELOPMENT PROCEDURES

The program development procedures for FORTRAN IV are quite similar to
those for MACR0-11.
Therefore, this chapter does not include the
level of detail found in previous chapters of this manual. To edit a
FORTRAN IV source file, use the same commands you used to edit the
MACR0-11 files shown in Chapter 2. If you are using an editor other
than EDI, perform the same operations using your editor.

7.2.1

Creating the Source File

To create a sample FORTRAN IV source file, invoke the editor task EDI
a!1d
:.::::::
t~c
fcllc.·.d.~.g .::0111&i1ai.£u£ i..u ~w:>t:::t l. l..he .i ines ot coae shown in
Example 7-1.
MCR>EDI AVERAGE.FTN
[CREATING NEW FILE]
INPUT
insert the lines here and
type the RETURN key twice to exit from
insert mode
~
~

*EXIT
[EXIT]

7-2

FORTRAN IV PROCEDURES
Because EDI cannot insert a blank line in the text
(EDI requires at
least one nonprinting character such as a space or tab character; see
Section 2.2.1.1), be sure to use the C (comment line) in column 1 of
the source file in place of the blank line, for readability.
If you
insert a line with a space or tab character in it, the FORTRAN IV
compiler generates an error because it expects a valid label on a

nonblank line ..
You can use the TAB character to facilitate line formatting.
The
FORTRAN IV compiler positions the character following an initial TAB
character to the proper column.
That is, a digit following an initial
TAB is considered a continuation character (column 6), and a nondigit
is considered the beginning of the statement (column 7).
Example 7-1

FORTRAN IV Sample Source Code AVERAGE.FTN

PROGRAM AVERAGE
PROGRAM TO COMPUTE AVERAGE OF NUMBERS ENTERED AT TERMINAL
THE NUMBER '0' INDICATES END OF INPUT

C
C

TOTAL = 0

INITIALIZE ACCUMULATOR
INITIALIZE COUNTER

=0
N =N + 1

WRITE (5,10)
! PROMPT TO ENTER NUMBER
FORHAT (' ENTER NUMBER, END WITH 0' >
READ (5,20> K
READ NUMBER FROM TERMINAL
FORHAT I10
IF <K .EQ. 0) GOTO 40
0 MEANS NO HORE INPUT
TOTAL = TOTAL + I(
COMPUTE TOTAL WITH NUMBER
GO TO 5

10
20

c Now, COMPUTE TOTAL BY DIVIDING IT BY THE NUMBER OF TIMES

C THROUGH THE LOOP

TOTAL = TOTAL/N
WRITE (5,50) TOTAL
! DISPLAY THE RESULT
FORHAT <' AVERAGE IS '•F10.2>
STOP
END

7.2.2

Performing a Diagnostic Run

To determine whether there are any syntax or grammar errors in a
source file, you can perform a diagnostic run using the DCL FORTRAN
command line, as follows:
DCL>FORTRAN/NOOBJECT

AVERAGE/LIST

AVER.~G

FOR -- [AVERAG] ERRORS:

1, WARNINGS:

>
This command line requests FORTRAN IV to compile the file AVERAGE.FTN
and create a listing file,
AVERAGE.LST,
but no object file.
By
default, the listing file contains source code and diagnostic messages
only.

7-3

FORTRAN IV PROCEDURES

When you request a listing file in a compilation, FORTRAN IV reports
at the terminal the
ame of the program unit being compiled and a
summary of any errors. To discover what caused any errors, you must
examine the section of the listing entitled FORTRAN IV DIAGNOSTICS.
List the file on your terminal with the DCL TYPE command, as shown:
DCL>TYPE AVERAGE.LST
(PIP displays listing)

>
See the following discussion of the
reading the listing file.
To perform the diagnostic
following command line:

run

MCR

from

format
an

MCR>FOR ,AVERAGE/-SP=AVERAGE
AVERAG
FOR -- [AVERAG] ERRORS: 1, WARNINGS:

MCR

for

information

terminal,

issue

on
the

>
This command line requests FORTRAN IV to compile the file AVERAGE.FTN,
which resides in your UFD.
The compiler creates a listing file,
AVERAGE.LST, but no object module.
(The leading comma in the command
means a null file specification for the object file. If you omit the
comma~ FORTRAN IV creatP-s t.he object file but not the
listing file.)
As a default condition, the listing file contains source code and
diagnostic messages only.
When you request a listing file in a compilation, FORTRAN IV reports
at the terminal the name of the program unit being compiled and a
summary of errors found. To discover what caused any errors, you must
examine the section of the listing entitled FORTRAN IV DIAGNOSTICS.
Display the listing file by typing the following MCR command line:
MCR>PIP TI:=AVERAGE.LST
(PIP displays listing)

>
On a video display terminal, use the CTRL/S
stop and resume output.

and

CTRL/Q

commands

The following line appears in the diagnostic section of the listing:
IN LINE 0008,

ERROR:

SYNTAX ERROR

Line 0008 refers to the statement number 0008 assigned by the
compiler.
The error referred to is described in an appendix of the
language user's guide. In the source code part of the listing, line
0008 is shown as follows:
0008

FORMAT IlO

The compiler detected missing parentheses on the field descriptor in
the FORMAT statement. To correct the error, you must edit the source
file, as in the following example:
MCR>EDI AVERAGE.FTN
[00023 LINES READ IN]
[PAGE l]
*L IlO~

FORMAT !10
7-4

FORTRAN IV PROCEDURES
*C /IlO/(IlO)/
20
FORMAT (IlO}

*EXIT~

[EXIT]

>
The L command locates the line containing the string IlO and prints
the entire line. The C command replaces the string IlO with (IlO} and
prints the line so that you can verify the change. The EXIT command
terminates the editing session and creates the new, edited version of
the file. Next, you can use the edited version to create an object
module.

7.2.3

Creating an Object Module

To create an object module, simply omit the /NOOBJECT
the DCL command line you entered previously:

qualifier

from

DCL>FORTRAN AVERAGE/LIST
AVERAG

>
This command line requests FORTRAN IV to compile file AVERAGE.FTN, and
to create listing file AVERAGE.LST and object file AVERAGE.OBJ. If
FORTRAN IV detects any errors, it prints a summary at the terminal
(see Section 7.2.1).
If there are no errors, FORTRAN IV returns
control to DCL, which prints the > prompt.
Here is the same procedure from an MCR terminal:
MCR>FOR AVERAGE,AVERAGE/-SP=AVERAGE
AVERAG

>
This command line requests FORTRAN IV to compile file AVERAGE.FTN, and
to create object file AVERAGE.OBJ and listing file AVERAGE.LST. If
FORTRAN IV detects any errors, it prints a summary at the terminal as
described in Section 7.2.1.
If there are no errors, FORTRAN IV
returns control to MCR, which prints the > prompt.

7.2.4

Creating a Task Image

FORTRAN IV object modules do not contain all the object code required
at run time.
Therefore, when you run the Task Builder, either from
MCR or with the DCL LINK command, you must specify as input both the
name of the object module and the name of the library containing the
FORTRAN IV OTS routines. The commands for both DCL and MCR users
follow:
DCL>LINK AVERAGE, LB:[l,l]FOROTS/LIBRARY
or
MCR>TKB AVERAGE=AVERAGE,LB:[l,l]FOROTS/LB

7-5

FORTRAN IV PROCEDURES
These command lines request the Task Builder to resolve any undefined
references by searching the library FOROTS.OLB in UFD [1,1] on the
system library device,. and linking compiler-designated routines to
module AVERAGE.OBJ.! You can add, as input to the Task Builder, file
names of any external object modules that the main module calls. As a
result of the command line, the Task Builder creates a task image file
AVERAGE.TSK.
(A memory allocation file is not needed.) If the Task
Builder detects any errors, it proceeds according to whether the error
is fatal or diagnostic. Refer to an appendix in the RSX-llM/M-PLUS
Task Builder Manual for guidelines·on error processing.
NOTE
When building a task image, the library
FOROTS.OLB may contain routines that
support · the
FP-11
floating
point
processor.
If this is the case, the
commands for DCL and MCR users are as
follows:
DCL>LINK/CODE:FPP AVERAGE,LB:[l,l]FOROTS/LIBRARY
MCR>TKB AVERAGE/FP=AVERAGE,LB:[l,l]FOROTS/LB
You also must use these commands when
you rebuild your task after debugging
it.

The task image created by the Task Builder has certain default
conditions. The task AVERAGE can be built to run successfully without
having to override these default conditions. When you build a task
from a FORTRAN IV module, you may have to specify special switches in
the command line or supply options to the Task Builder. Refer to the
language user's guide for information regarding Task Builder default
FORTRAN IV conditions and FORTRAN-specific options and switches.
See
also the description of the FORTRAN command in of the RSX-llM/M-PLUS
Command Lanquage Manual.

7.2.5

Running and Debugging a Task

To execute the task AVERAGE, type the following
line:

DCL

MCR

command

) H.UN AVt;H.Al;.t:;

1. In the command line, the name shown for the FORTRAN IV Object Time
System (FOROTS) is only a convention recommended by DIGITAL. Consult
the system manager at your installation because the FORTRAN IV OTS
routines may reside in another library or in the system library
SYSLIB.
(If the OTS routines do reside in SYSLIB, you need not
specify the name of the OTS in the command line to the Task Builder
because the Task Builder automatically searches the system library.)
7-6

FORTRAN IV PROCEDURES

The program will then display the following lines on your terminal:
ENTER NUMBER, END WITH 0
66
ENTER NUMBER, END WITH 0
66
ENTER NUMBER, END WITH 0
0
AVERAGE IS
44.00
TT30
STOP
>
Obviously 44 is not the average of 66 and 66; therefore, there must
be an error in the program. If you cannot locate the error by looking
at the program listing, you can attempt to locate the error by placing
debugging statements in the code.
To add debugging statements to the program, simply edit the source
file with lines of code beginning with D in column 1. For example,
you can include statements to print values of variables before and
after the loop, as follows:
MCR>EDI AVERAG.FTN
[00023 LINES READ IN]
[ PAGE
l]
* L 5 ffiJ
5 N = N + 1
*I~
D~

D6@§)

WRITE (5,6) N,TOTAL
FORMAT (' ***DEBUG LINE N = I ,IlO, I , TOTAL = I ,Fl0.0) (Bfil)

*L 50~
ml
50 FORMAT ('AVERAGE IS ',Fl0.2)
*I (Bfilj
D~
WRITE (5, 51) N
DSl@ID
FORMAT (' ***DEBUG LINE N = ' 1 Il0) ~
ffi)

*EXIT 00)
[EXIT]

>
The L commands locate and print the contents of the lines that precede
where debugging statements are to be placed. The I commands insert
the debugging statements.
You terminate the insert operation by
typing two successive RETURN keys. After the inserts are made, the
EXIT command closes the file and terminates EDI.
Next, recompile the module and request FORTRAN IV to include the
debugging statements, as shown in the following DCL and MCR command
lines:
DCL>FORTRAN/OBJECT:DEBUG/D LINES/LIST:DEBUG
File(s)?

AVERAGE

AVERAG

>
or
MCR>FOR DEBUG,DEBUG=AVERAGE/DE
The compiler generates the files DEBUG.OBJ and DEBUG.LST. Because of
the /D LINES qualifier (/DE designation in the MCR line), the compiler
includes statements beginning with D in column 1. If you omit this
qualification, the debugging lines are treated simply as comment
lines.
7-7

FORTRAN IV PROCEDURES
Now, rebuild the task with debugging
command lines as shown:

lines,

using

the

DCL

with

ODT,

which

MCR

DCL> LINK DEBUG,LB:[l,l]FOROTS/LIBRARY
>
or
MCR>TKB DEBUG=DEBUG,LB:[l,l]FOROTS/LB
>
Note that this operation has nothing
MACR0-11 debugging tool.

Run the task with the following DCL or MCR command line:
>RUN DEBUG
1, TOTAL =
***DEBUG LINE N =
ENTER NUMBER, END WITH 0
66
***DEBUG LINE N =
2, TOTAL
ENTER NUMBER, END WITH 0
66
***DEBUG LINE N =
3. TOTAL
ENTER NUMBER, END WITH 0
0
AVERAGE IS
44.00
***DEBUG LINE N
3
TT30 -- STOP
>

o.
66.
132.

The debugging statements enable you to inspect the values
of
variables.
As you can see, the loop counter N is incremented one
extra time for the number O. The value N must be decremented by 1.
To correct the error, edit the source file as follows:
MCR>EDI AVERAGE.FTN
[00027 LINES READ IN]
[PAGE
l]

* L TOTAL/ (8@

40 TOTAL = TOTAL/N
*C ;N; (N-1);
40 TOTAL = TOTAL/(N-1)
*EXIT~

[EXIT]

>
Next, repeat the compile, link, and run operations.
terminal, use the following sequence of command lines:
DCL>FORTRAN AVERAGE/LIST
AVERAG
>LINK AVERAGE,LB:[l,l]FOROTS/LIBRARY
>RUN AVERAGE
ENTER NUMBER, END WITH 0
66
ENTER NUMBER, END WITH 0
66
ENTER NUMBER, END WITH 0
0
AVERAGE IS 66.00
TT30
STOP
>

7-8

From

DCL

FORTRAN IV PROCEDURES
The program is compiled without the debugging statements.
shows that the correction eliminated the error.

The

output

The

output

Here is the same procedure from an MCR terminal:
MCR>FOR AVERAGE,AVERAGE/-SP=AVERAGE
AVERAG
>TKB AVERAGE=AVERAGE,LB:[l,l]FOROTS/LB
>RUN AVERAGE
ENTER NUMBER, END WITH 0
66
ENTER NUMBER, END WITH 0
66
ENTER NUMBER, END WITH 0
0

AVERAGE IS
66.00
TT30
STOP

>
The program is compiled without the debugging statements.
shows that the correction eliminated the error.

7.3

GUIDE TO FURTHER READING

The section or chapters in the following documents contain
information on the subjects described in this chapter.

additional

Document
IAS, RSX, VAX/VMS, FORTRAN IV User's Guide
Section 1.3, Using the Task Builder to Link FORTRAN IV Programs
Section 1.6, Debugging a FORTRAN IV Program
Section 2.1, FORTRAN IV Object Time System
Section 2.2, Object Code
Section 2.9, OTS and Shareable Libraries
Appendix c, FORTRAN IV Error Diagnostics
RSX-llM/M-PLUS Command Language Manual
Section 6.2.3, FORTRAN Command
RSX-llM/M-PLUS Task Builder Manual
Appendix H, Error Messages

7-9

INDEX

ANSLIB.OLB (ANSI Magnetic Tape
library), 1-11
AP command (EDI), 2-17
Assembly,
language, 1-4 to 1-5
See also MACR0-11
listing,
examining at a terminal,
3-6
formatting, 2-6
generating, 3-4 to 3-6
page break, 2-6
printing, 3-8 to 3-9
spooling, 3-8 to 3-9
table of contents, 2-6
terminal format, 2-6
Asterisk character (*),
EDI, 2-10
PIP, 3-10
At sign (@),
ODT, 5-8
AVERAGE.FTN source code, 7-3

Creating (Cont.)
skeleton, 2-12
task image, 1-6, 4-1 to 4-2,
7-5 to 7-6
CRF (Cross-Reference
Processor) , 1-8
assembly cross-reference,
3-7 to 3-8
global cross-reference,
4-5 to 4-6
Cross-reference listing,
assembly, 3-7 to 3-8
global, 4-5 to 4-6
Cross-Reference Processor,
See CRF
CTRL/C command, 1-2
CTRL/O command, 3-7
CTRL/Q command, 3-7
CTRL/S command, 3-7
CTRL/U command, 5-3
Data block,
local, 2-8
Data storage,
control in assembly
language, 1-4 to 1-5
directive, 1-4 to 1-5
MACR0-11 definition, 2-8
program section, 2-8
DCL (DIGITAL Command
Language) , 1-1 to 1-3
Debugging,
introduction, 1-6 to 1-7
MACR0-11 source file,
3-3 to 3-4
task, 4-9, 5-1 to 5-2,
7-7 to 7-9
tool,
See ODT
using map, 5-2, 5... 9
DEC Standard Editor,
See EDT
Default,
file type,
MACR0-11, 3-5
TKB, 4-1
system library search,
MACR0-11, 1-5, 1-10, 2-7
TKB, 1-11, 4-2
transfer (starting) address,
4-8
Delimiter, 2-16
Diagnostic run,
FORTRAN IV source file,
7-3 to 7-4

B command (ODT), 5-6
Backslash character (\) ,
CDT, 5-5
BEGIN command (EDI), 2-14
Block mode (EDI), 1-3
Breakpoint register, 5-6
Breakpoints,
setting in a task, 5-6
Buffer,
text, 1-3

CHANGE command (EDI), 2-16,
7-5
CL! {Command Line
Interpreter) ,
DCL, 1-1 to 1-3
MCR, 1-1 to 1=3

Command Line Interpreter,
See CLI
COPY command (DCL) , 4-3
Creating,
macro library, 6-1 to 6-3
object library, 6-4 to 6-6
object module,
FORTRAN IV, 7-5
MACR0-11, 3-4 to 3-6
source file,
FORTRAN IV, 7-2 to 7-3
MACR0-11, 2-12
Index-1

INDEX

Diagnostic run (Cont.)
MACR0-11 source file,
3-1 to 3-2
DIGITAL Command Language,
See DCL
Directive,
assembler, 1-5
system, 1-9 to 1-10
use, 2-3, 2-5 to 2-6
Directory,
listing, 3-9
purging, 3-9 to 3-10
DIRECTORY command (DCL) , 3-9
Disk,
private, 1-12
public, 1-12
Do 11 a r sign ( $ ) ,
ODT, 5-6 to 5-8
DP command (EDI), 2-17
Dump,
See PMD

EDI, 1-3 to 1-4
abbreviating,
strings, 2-16
altering,
text, 2-16, 7-5
AP command, 2-17
asterisk (*), 2-10
BEGIN command, 2-14
block mode, 1-3
CHANGE command, 2-16, 7-5
commands, 2-12 to 2-18
correcting,
source file error,
7-4 to 7-5
task error, 4-9, 7-9
creating,
file, 2-9 to 2-10, 2-12,
7-2 to 7-3
deleting,
characters, 2-17
lines, 2-17
displaying,
text, 2-13
DP command, 2-17
ellipsis, 2-16
END command, 2-14
ESCAPE key, 2-13
EXIT command,
closing file, 2-10, 7-7
creating new file, 2-12,
2-18, 7-5
input,
initial, 2-9, 7-3
terminating, 2-10

EDI (Cont.)
INSERT command, 2-18, 7-7
insert mode, 2-18
inserting,
characters, 2-17
lines, 2-9, 2-18
LIST command, 2-13
LOCATE command, 2-14, 2-18,
7-4 to 7-5, 7-7
locating,
text, 2-14 to 2-15,
7-4 to 7-5
PLOCATE command, 2-15
positioning,
line pointer, 2-14 to 2-15
RENEW command, 2-15
RETURN key, 2-9 to 2-10,
2-13, 2-18, 7-7
slash character (/), 2-16
TYPE command, 2-13 to 2-14,
2-17
Editor,
text, 1-3 to 1-4
See also EDI, EDT
EDT, 1-3
Ellipsis,
EDI, 2-16
END command (EDI), 2-14
.END directive, 2-7, 3-4~ 4-3,
4-8
Entry point, 6-5 to 6-6
table, 6-5, 6-9 to 6-10
zero entry points, 6-7
Error message,
FORTRAN IV, 7-4
MACR0-11, 3-5
ODT, 5-3
TKB, 4-2
TKTN, 4-8
ESCAPE key,
EDI, 2-13
Executive,
library, 1-11
macro, 1-9 to 1-10
EXELIB.OLB (Executive
library), 1-11
EXEMC.MLB (Executive macro
library), 1-9 to 1-10
EXIT command (EDI), 2-10,
2-12, 2-18, 7-5, 7-7
EXIT$S directive, 2-7

F4POTS.OLB (FORTRAN IV and
FORTRAN IV-PLUS library),
1-11
Fast Task Builder,
See FTB

Index-2

INDEX

File,
creating,
source, 2-9 to 2-10
directory listing, 3-9
editing,
source, 2-9, 2-12 to 2-18
listing, 3-6
printing, 3-8 to 3-9
purging, 3-9 to 3-10
spooling, 1-8, 3-8 to 3-9
File type,
.FTN, 7-3 to 7-4
.LST, 3-4, 6-11, 7-3 to 7-4
.MAC, 3-1
.MAP, 4-6
.MLB, 6-1
.OBJ, 3-4, 7-5
• OLB, 6-4
• PMD, 5-10
• TSK, 4-1
FILEA.MAC source code,
2-21 to 2-22
FILEB.MAC source code,
2-23 to 2-24
FILE.MAC source code,
2-19 to 2-20
FOR command (MCR), 7-1, 7-4
FOR compiler task, 7-1
creating object module, 7-5
/DE, 7-7
debugging statements, 7-7
diagnostic run, 7-3 to 7-4
/D LINES, 7-7
FOR command (MCR), 7-1, 7-4
FORTRAN command (DCL), 7-1,
7-3
.FTN file type, 7-3 to 7-4
/LIST, 7-3, 7-7
/NOOBJECT, 7-3
/OBJECT, 7-3, 7-7
Format,
FORTRAN IV,
statement, 7-3
MACR0-11,
source file, 2-1 to 2-3
skeleton, 2-4
statement, 2-3
FOROTS.OLB (FORTRAN IV and
FORTRAN IV-PLUS library),
1-11
FORTRAN command (DCL), 7-1,
7-3
FORTRAN IV,
See also FOR compiler task
compiler task, 7-1
formatting source
statements, 7-3
library, 1-11

Index-3

FORTRAN IV (Cont.)
source file,
blank file, 7-3
comment file, 7~3
specifying OTS to TKB, 7-5
FORTRAN IV-PLUS,
library, 1-11
FTB (Fast Task Builder) , 4-4
.FTN file type, 7?3 to 7~4
See also FOR compiler task
G command (ODT), 5-6, 5-8
Global cross-reference,
listing, 4-5 to 4-6
Global default,
disabling in MACR0-11,
3-1 to 3-2
Global symbol, 1-4 to 1-5
entry point, 1-4,
6-5 to 6-6, 6-10
resolution, 4-2, 6-8 to 6-9
using library to resolve
undefined, 6-8 to 6-9

Hardware,
program development, 1-12

.!DENT directive, 2-5
INSERT command (EDI), 2-18,
7-7
Inserting,
characters in a line, 2-17
code in the source file,
2-18
lines in a file, 2-9, 2-18
modules in a library,
6-9 to 6-10
Language,
assembly, 1-4 to 1-5
See also MACR0-11
LBR command (MCR), 1-9, 6-2
See also LBR
LBR (Librarian Utility
Program) , 1-9
adding a module to a
library, 6-9 to 6-10
/COMPRESS, 6-10
/CR, 6-2, 6-5
/CREATEr 6-1, 6-4 to 6-5
efficiency, 1-9
/FU, 6-11 to 6-12

INDEX

LBR (Librarian Utility
Program) (Cont.)
/FULL, 6-11
/IN, 6-10
/INSERT, 6-9
LBR command (MCR), 1-9, 6-2
/LE, 6-11 to 6-12
LIBRARY command (DCL), 1-9,
6-1
/LIST, 6-9, 6-11
listing information,
6-11 to 6-12
/MACRO, 6-1 to 6-2
macro library, 6-1 to 6-3
/NAMES, 6-11
/OBJECT, 6-2, n-4 to 6-5
object module library,
6-4 to 6-6
.OLB file type, 6-4
/REPLACE, 6-9 to 6-10
replacing a module in a
library, 6-10 to 6-11
/RP, 6-10 to 6-11
/-SP, 6-11
Librarian Utility Program,
See LBR
Library,
See also Macro, Object, OTS
default search of system,
TKB, 4-2
DIGITAL-supplied, 1-9
macro, 6-1 to 6-3
maintenance, 6-10 to 6-11
object, 6-4 to 6-6
designating in TKB,
6-6 to 6-9
system, 1-11
using to resolve undefined
global symbols,
6-8 to 6-9
obtaining information about
a user, 6-11 to 6-12
OTS, 7-2
search,
MACR0-11, 1-5, 1-10, 2-7
TKB, 1-11
squeezing, 6-3
system,
macro (RSXMAC.SML), 1-5
LIBRARY command (DCL), 1-9,
6-1
See also LBR
LINE FEED key,
closing lo~ation (ODT), 5-5,
5-7
displaying word on stack
(ODT), 5-8·
opening location (ODT), 5-5,
5-7

Index-4

Line Text Editor,
See EDI
LINK command (DCL), 1-5, 4-1,
5-1, 5-9, 6-7
See also TKB
LIST command (EDI), 2-13
.LIST TTM directive, 2-6
Listing,
assembly, 3-4 to 3-5
control, 1-4 to 1-5, 2-6
directory, 3-9
examining at a terminal,
3-6, 7-4
FORTRAN IV, 7-5
global cross-reference,
4-5 to 4-6
printing, 3-8 to 3-9
spooling, 3-8 to 3-9
use in debugging, 5-4
Local data block, 2-8
Local macro, 2-8
definitions, 2-8
Local symbol, 1-4 to 1-5
definitions, 2-7 to 2-8
LOCATE command (EDI), 2-14,
2-18, 7-4 to 7-5, 7-7
Location counter, 1-4 to 1-5
use in debugging, 5-3 to 5-4
Logical unit number;
See LUN
.LST file type, 3-4, 6-11,
7-3 to 7-4
LUN (Logical unit number),
default by TKB, 4-4 to 4-5
MAC command (MCR), 1-4, 3-1,
3-5, 6-3
See also MACR0-11
.MAC file type, 3-1
MAC task, 1-4
See MACR0·-11

Macro,
call,
cross-reference of
symbols, 3-7 to 3-8
resolution, 1-4, 1-10, 2-7
unrecognized, 2-7
library, 6-1 to 6-3
adding modules,
6-9 to 6-10
creating a user,
6-1 to 6-3
definitions, 6-3 to 6-4
DIGITAL-supplied, 1-9
listing information,
6-11 to 6-12
replacing modules,
6-10 to 6-11

INDEX

Macro (Cont.)
search of system, 1-5,
1-10, 2-7
symbol,
definition, 1-4, 1-10,
2-7 I 6-4
MACRO command (DCL), 1-4, 3-1,
3-4, 6-3
See also MACR0-11
MACR0-11, 1-5
assembling source file,
3-1 to 3-2
/CR, 1-8, 3-8
/CROSS REFERENCE, 1-8, 3-7
cross-reference listing,
1-5, 1-7, 3-7 to 3-8
data storage,
definition, 2-8
default search of system
library 1-5, 1-10,
2-7
defining local symbols,
2-7 to 2-8
directives, 1-4 to 1-5
/DISABLE:GLOBAL, 3-1
disabling global default,
3-1 to 3-2
/DS:GBL, 3-1
error, 3-2 to 3-4
error code,
A, 3-2 to 3-3
E, 3-4
Q, 3-4
u, 3-3
error message, 3-2, 3-5
/LIBRARY, 6-3
/LIST, 3-1, 3-4 to 3-5, 3-7
listing, 3-4 to 3-5
generation, 3-6
location counter, 1-4 to 1-5
MAC command (MCR), 1-4, 3-1,
3-5, 6-3
macro,
cross-reference,
3-7 to 3-8
library usage, 6-3 to 6-4
symbol, 1-4, 2-7, 6-4
MACRO command (DCL), 1-4;
3-1, 3-4 I 6-3
/ML, 6-3 to 6-4
/NOOBJECT I 3-1
/OBJECT I 3-4
object module, 3-4 to 3-6
source file, 2-2
format, 2-1 to 2-3
skeleton, 2-4
source input, 1-4
/-SP, 3-5, 3-8
statement format, 2-3

Index-5

MACR0-11 (Cont.)
symbol,
cross-reference,
3-7 to 3-8
evaluation, 1-4,
3-1 to 3-2, 6-4
table of contents
generation, 2-6
Map,
debugging use, 5-2, 5-8
examining at terminal, 4-6
full, 4-7
generating, 4-5 to 4-7
reducing width, 4-5 to 4-6
stack limits, 5-8
standard, 4-5 to 4-6
.MAP file type, 4-6
.MCALL directive, 1-10,
2-6 to 2-7, 3-3
using with user macro
library, 6-3 to 6-4
MCR (Monitor Console Routine),
1-1 to 1-3
Memory allocation file,
See Map
.MLB file type, 6-1
Module name, 2-3, 2-5,
6-5 to 6-7
table, 6-9 to 6-10
macro library, 6-2 to 6-3
object library, 6-5, 6-7
Module version, 2-5
Monitor Console Routine,
See MCR

.NLIST BEX directive, 2-6

.OBJ file type, 3-4, 7-5
Object,
library,
adding modules,
6-9 to 6-10
creating a user,
6-4 to 6-6
default search of system,
1-11, 4-2
DIGITAL-supplied,
1-10 to 1-11
dual use, 6-8 to 6-9
listing information,
6-11 to 6-12
OTS, 7-1 to 7-2
using to resolve undefined
global symbols,
6-8 to 6-9

INDEX

Object (Cont.)
module,
concatenated, 4-3 to 4-4
FORTRAN IV, 7-5 to 7-6
input to TKB, 4-1
MACR0-11, 1-4, 3-4 to 3-6
Object Time System,
See OTS
CDT (On-Line Debugging Tool),
1-6 to 1-7
at sign (@), 5-8
B command, 5-6
backslash character (\) , 5-5
breakpoint register, 5-6
changing location contents,
5-7
correcting input, 5-3
dollar sign ($), 5-6 to 5-8
error conditions in task,
5-8
examining locations,
5-4 to 5-5
forming address, 5-4
G command, 5-6, 5-8
including in a task,
5-1 to 5-2
LINE FEED key, 5-5,
5-7 to 5-8
map use, 5-2
CDT.OBJ file, 5-1
P command, 5-7
question mark (?), 5-3
R command, 5-3
relocation register,
5-2 to 5-4
RETURN key, 5-8
setting breakpoints, 5-6
setting up a task with, 1-7
slash character 1 ( / ) , 5-4
source listing use, 5-4
SST within, 5-8
terminating task execution,
5-8
underline character ( ) , 5-2
X command, 5-8
OLB file type, 6-4
See also LBR
On-Line Debugging Tool,
See CDT
OTS (Object Time System) ,
library, 7-1 to 7-2

P command (ODT), 5-7
.PAGE directive, 2-6
PC (Program counter} ,
value, 4-8

Peripheral Interchange
Program,
See PIP
PIP (Peripheral Interchange
Program) , 1-8
asterisk (*), 3-10
cleaning up a UFD,
3-9 to 3-10
creating a concatenated
object module,
4-3 to 4-4
examining listing at
terminal, 3-6, 4-6, 7-4
/LI, 3-9
/ME, 4-3 to 4-4
printing listing, 3-8 to 3-9
/PU, 3-10
/SP, 3-8
spooling listing, 3-8 to 3-9
PLOCATE command (EDI), 2-15
.PMD file type, 5-10
See also PMD
PMD (Postmortem Dump) , 1-7
enabling with TKB, 5-9
Postmortem Dump,
See PMD
PRINT command (DCL), 1-12, 3-8
PRINT command (MCR) , 3-9
Printer, 1-12
Program,
sectioning, 1-4 to 1-5, 2-5,
2-8 to 2-9
user,
breakpoints,
setting, 5-6
FORTRAN IV, 7-3
library, 6-1
macro symbol, 6-4
definition placement,
1-5
module,
name, 2-3, 2-5
version, 2-5
object library routines,
6-6
overview of development,
1-13 to 1-14
section definiton,
2-8 to 2-9
system routines, 1-11
Program counter,
See PC
Programming,
advanced,
techniques, 1-6
.PSECT directive, 2-8 to 2-9
PURGE command (DCL) , 3-9

Index-6

INDEX

QMG (Queue Manager) , 1-12
Question mark (?),
ODT, 5-3
Queue Manager,
See QMG

Record Management Services,
See RMS-11
Register,
breakpoint, 5-6
relocation, 5-2 to 5-4
Relocation register,
5-2 to 5-4
RENEW command (EDI), 2-15
RETURN key,
closing location (ODT), 5-5,
5-8
displaying new line (EDI),
2-13
entering text (EDI), 2-9
terminating input (EDI),
2-9 to 2-10, 2-18, 7-7
RMS-11 (Record Management
Services) ,
library, 1-9, 1-11
RMSLIB.OLB (Record Management
Services library), 1-11
RMSMAC.MLB (Record Management
Services library), 1-9
RSXMAC.SML (System macro
1 ibrary) , 1-5,
1-9 to 1-10, 2-7
RUN command, 4-7, 5-2, 7-6

.SBTTL directive, 2-6
Skeleton,
source file (MACR0-11), 2-4
Slash character (/) ,
EDI, 2-16
ODT, 5-4
$SNAP (Snapshot dump) ,
1-7 to 1-8, 5-9 to 5-10
subset of Postmortem Dump
Task, 5-9 to 5-10
Snapshot dump,
See $SNAP
Source file (FORTRAN IV),
adding debugging statements,
7-7
blank line, 7-3
comment line, 7-3
creating, 7-2 to 7-3
editing, 7-4 to 7-5, 7-7,
7-9

Index-7

Source file (MACR0-11),
assembling, 3-1 to 3-2
creating from a skeleton,
2-12
editing, 2-13 to 2-18
error, 3-2 to 3-4
format, 2-1 to 2-3
skeleton, 2-4
inserting lines, 2-18
listing, 3-4 to 3-6
macro library call,
6-3 to 6-4
preface, 2-1
SST (Synchronous system trap) ,
ODT, 5-8
relation to Postmortem Dump,
1-7

role in task termination,
4-8 to 4-9
Statement,
MACR0-11, 1-4
format, 2-3
Symbol,
cross-reference, 3-7 to 3-8
global, 1-5
entry point, 1-4
resolution, 1-4 to 1-5,
4-2
local, 1-4 to 1-5,
2-7 to 2-8
definition, 2-7 to 2-8
macro,
definition, 1-4, 1-10,
2-7, 6-4
MACR0-11 evaluation, 1-4,
3-1 to 3-2
Synchronous system trap,
See SST
SYSLIB.OLB (System library),
1-11
System,
directive, 1-9 to 1-10
library,
contributions (in map),
4-7
macro (RSXMAC.SML), 1-5,
1-9 to 1-10
contents, 1-9
search, 1-5, 1-10, 2-7
object (SYSLIB.OLB), 1-11
contents, 1-11
search, 1-11, 4-2
task, 1-1

Task,
abort, 4-8

INDEX

Task (Cont.)
breakpoints,
setting, 5-6
building, 4-1, 7-6
correcting, 4-9
debugging, 4-9, 7-7 to 7-9
default conditions,
4-4 to 4-5, 4-7 to 4-8
macro calls, 6-3 to 6-4
map, 4-5
full, 4-7
standard, 4-5 to 4-6
object library routines, 6-6
running, 4-7 to 4-8, 7-6
SST I 4-8
system, 1-1
system library
contributions, 4-7
termination, 4-8
transfer (starting) address,
default, 4-3, 4-8
defining~ 2-7
Task Builder,
See TKB
Task image, 1-6, 4-1, 7-6
creating, 4-1 to 4-2,
7-5 to 7-6
Task Termination and

Notification;
See TKTN
Terminal,
examining a listing,
3-6 to 3-7
output,
controlling, 3-7
types, 1-12
Text,
buffer, 1-3
editor, 1-3 to 1-4
See also EDI, EDT
.TITLE directive, 2-3, 2-5,
6-7
TKB command (MCR), 1-5, 4-1,
5-2, 5-9, 6-7
See also TKB
TKB (Task Builder) , 1-5 to 1-6
/CR, 1-8, 4-6, 5-2
/CROSS REFERENCE, 1-8, 4-5,

TKB (Task Builder) (Cont.)
standard, 4-5 to 4-6
/INCLUDE, 6-7 to 6-9
input, 1-5 to 1-6
/LB, 6-7 to 6-9, 7-8
/LIBRARY, 6-8 to 6-9, 7-8
LINK command (DCL), 1-5,
4-1, 5-1, 5-9, 6-7
/LONG, 4-7
/MA, 4-7
/MAP, 4-5, 4-7, 5-1, 5-9,
6-7 to 6-9
/NOTASK, 4-5
/NOWIDE, 4-5
object library,
designation, 6-4 to 6-5
use, 6-8 to 6-9
output, 1-6
/PM, 5-9
/POSTMORTEM, 5-9
search of system library,
default I' 1-11
/-SH, 4-7
symbol,
undefined, 4-2
/SYSTEM LIBRARY DISPLAY, 4-7
/TASK, S-1, 6-7-to 6-9
TKB command (MCR), 1-5, 4-1,
5-2, 5-9, 6-7
transfer (starting) address,
default, 4-3
/-WI, 4-6
TKTN (Task Termination and
Notification),
abort message, 4-8
using with PMD, 1-7
Transfer (Starting) address,
defining, 2-7
system treatment of default,
4-3, 4-8
Trap,
See SST
.TSK file type, 4-1
TYPE command (DCL), 3-6, 4-6,
7-4
TYPE command (EDI),
2-13 to 2-14, 2-17

5-T

Underline character (_), ODT, 5-2
Utility programs, 1-8 to 1-9

/DA, 5-2
/DEBUG, 5-1
error, 4-2, 4-8 to 4-9
/FAST, 4-4
fast version, 4-4
generating,
cross-reference listing,
4-5 to 4-6
map,
full, 4-7

Virtual memory management,
library, 1-11
VMLIB.OLB (Virtual memory
management library), 1-11
X command (ODT), 5-8

Index-8

RSX-llM/M-PLUS Guide
to Program Development
AA-L676A-TC

READER'S COMMENTS
NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the
company's discretion. If you require a written reply and are eligible to receive one under Software
Performance Report (SPR) service, submit your comments on an SPR form.

Did you find this manual understandable, usable, and well-organized? Please make suggestions for improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent.

D
D
D
0
D
D

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify)

Organization
Street
State ______ Zip Code _ _ _ _ __
or Country

Do Not Tear-Fold Here and Tape -

~omoomo

No Postage
Necessary
if Mailed in the
United States

111111

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03061

Do Not Tear - Fold Here