Digital PDFs

AA-DO19B-TE

March 1980

175 pages

Original

6.8MB

Document:	VAX-11 Linker Reference Manual
Order Number:	AA-DO19B-TE
Revision:	000
Pages:	175
Original Filename:

OCR Text

VAX-11
Linker Reference Manual
Order No. AA-00198-TE

March 1980
This document describes how the VAX-11 Linker works and how to use it.

VAX-11
Linker Reference Manual
Order No. AA-00198-TE

SUPERSESSION/UPDATE INFORMATION:

This revised document supersedes the
VAX-11 Linker Reference Manual
(Order No. AA-D019A-TE)

OPERATING SYSTEM AND VERSION:

VAX/VMS V02

SOFTWARE VERSION:

VAX/VMS V02

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts 01754

diaital eauioment corooration · maunard. massachusetts

First Printing, August 1978
Revised, March 1980
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 only be used or copied 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 or its affiliated companies.

The postage prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in
preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DIGITAL
DEC
PDP
DECUS
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-11
VAX
DECnet
DATA TR I EVE

DECsystem-10
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8
VMS
!AS
TRAX

MASS BUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-11
TMS-11
ITPS-1.0
SB!
PDT

CONTENTS

Page
ix

PREFACE
CHAPTER

CHAPTER

LINKER OVERVIEW

1-1

1.1
1.1.1
1.1.2
1.1.3
1.2
1. 2 .1
1. 2. 2
1. 2. 3
1. 2. 4

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

1. 2. 5

REASON FOR A LINKER
Modular Programming
Simplifying Compilation And Assembly
Debug Capability
LINKER OPERATION AND FUNCTIONS
Virtual Memory Allocation
Resolution Of Symbolic References
Image Initialization
Image Map
Symbol Table File

SYMBOLS AND REFERENCES

2-1

2.1
2.2
2.2.1
2.2.2
2.2.2.1
2.2.2.2
2.2.2.3
2.2.2.4
2.2.3

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

2.3.1

DEFINITIONS:
"SYMBOL" AND "REFERENCE"
TYPES OF SYMBOLS AND REFERENCES
Local Symbols
Global Symbols
Strong Definition
Weak Definition
Strong Reference
Weak Reference
Universal Symbols
SYMBOL TABLES
Global Symbol Table As Separate Output

LIBRARIES

3-1

3.1
3.2

3-1

3.5

LIBRARY TABLES USED BY THE LINKER
LINKER'S USE OF LIBRARIES
USER-DEFINED DEFAULT LIBRARIES
DEFAULT SYSTEM LIBRARY
VMS RTL
STARLET
EXAMPLE OF USING LIBRARIES

THE LINK COMMAND

4-1

4.1
4.2
4.2.1
4.2.2
4.3

COMMAND FORMAT
COMMAND AND FILE QUALIFIERS
Command Qualifiers
File Qualifiers
EXAMPLES

4-1
4-2
4-4
4-10

THE /OPTIONS FILE QUALIFIER

5-1

5.1

USES FOR AN OPTIONS FILE
Entering Frequently Used Input
Specifications

5-1

2.3

CHAPTER

3.3

3.4
3.4.1
3.4.2
CHAPTER

CHAPTER

5 .1.1

iii

1-5
1-5

2-3
2-3

2-4
2-4
2-4
2-5

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

4-11

5-1

CONTENTS

Page
5-2

5.1.4
5.2
5.3

Identifying A Shareable Image As Input
Entering More Input Than The Command
Language Can Handle
Entering Non-standard Link Instructions
CREATING AND SPECIFYING AN OPTIONS FILE
SPECIAL OPTIONS

IMAGE MAP

6-1

6.1
6.2
6.2.l
6.2.2
6.2.3
6.2.4
6.2.5
6.2.6
6.2.7
6.2.8

IMAGE MAP CONTENTS
IMAGE MAP SECTIONS
Object Module Synopsis
Image Section Synopsis
Program Section Synopsis
Symbols By Name
Symbol Cross Reference
Symbols By Value
Image Synopsis
Link Run Statistics

6-1
6-3
6-3
6-3
6-5
6-8
6-8
6-8
6-10
6-10

IMAGE CREATION

7-1

7.1
7.2
7.3
7.4
7.5
7.5.l
7.5.2
7.5.3
7.5.4
7.5.4.l
7.5.4.2
7.5.4.3
7.5.4.4
7.5.4.5
7.5.4.6
7.5.4.7
7.5.4.8
7.5.4.9
7.5.4.10
7.6
7.6.l
7.6.2
7.6.3
7.7
7.8
7.9

PROGRAM SECrrIONS
IMAGE SECTIONS
CLUSTERS
OBJECT MODULE CONTENTS
PROGRAM SECTIONS
Program Section Name
Program Section Size
Program Section Alignment
Program Section Attributes
Relocatability (REL and ABS)
Concatenated versus Overlaid (CON and OVR)
Scope - Local versus Global (LCL and GBL)
Executability (EXE and NOEXE)
Writeability (WRT and NOWRT)
Readability (RD and NORD)
Position Independence (PIC and NOPIC)
Shareability (SHR and NOSHR)
User versus Library {USR and LIB)
Protection {VEC and NOVEC)
TYPES OF IMAGES
Executable Images
Shareable Images
System Images
GENERATION OF IMAGE SECTIONS
COMPRESSION OF UNINITIALIZED IMAGE SECTIONS
MECHANICS OF CLUSTERING

7-1
7-1
7-1
7-2
7-2
7-3
7-3
7-3
7-3
7-3
7-4
7-4
7-4
7-5
7-5
7-5
7-5
T-5
7-5
7-5
7-6
7-6
7-7
7-7

SHAREABLE IMAGES

8-1

8.1

SHAREABLE IMAGES: BENEFITS AND USES
Conserving Physical Memory
Conserving Disk Storage Space
Reducing Paging I/O
Using Shared Memory-Resident Data Bases
Making Software Updates Compatible

8-1
8-1
8-1
8-2
8-2
8-2

5.1. 2
5.1. 3

CHAPTER

8 .1.1
8 .1. 2
8 .1. 3
8 .1. 4
8.1.5

5-2
5-2
5-4
5-5

i-8

7-10

CONTENTS

Page
8-2
8-3
8-3
8-5

8.4.2
8.5

WRITING SOURCE PROGRAMS FOR SHAREABLE IMAGES
Shareable and Nonshareable Data
Position Independence
Transfer Vectors
Rules for Creating Upwardly Compatible
Shareable Images
LINK COMMAND AND PERTINENT OPTIONS
UNIVERSAL= Option
GSMATCH= Option
PROTECT = Option and /PROTECT Qualifier
EXAMPLES OF SHAREABLE IMAGES
Example of Transfer Vector and Universal
Symbols
Example of FORTRAN Shared COMMON
USING SHAREABLE IMAGES

APPENDIX

LINKER MESSAGES

A-1

APPENDIX

IMAGE MAP ILLUSTRATIONS

B-1

8.2
8.2.1
8.2.2
8.2.3
8.2.4
8.3
8.3.1
8.3.2
8.3.3
8.4
8.4.l

8-9
8-20
8-35

B-2
B-4
B-6

BRIEF MAP
DEFAULT MAP
FULL MAP
APPENDIX

8-7
8-8
8-8
8-8
8-9
8-9

VAX-11 OBJECT LANGUAGE

C-1

C-1
INTRODUCTION
C.l
C-1
Summary of Language
C.1.1
GLOBAL AND UNIVERSAL SYMBOLS AND NAME FORMAT C-3
C.2
C-3
C.3
HEADER RECORDS (HOR)
C-3
Module Header Records (MHD)
C.3.1
C-4
Header Type
C.3.1.1
C-4
Structure Level OBJ$C STRLVL
C.3.1.2
C-4
Maximum Record Size OBJ$C MAXRECSIZ
C.3.1.3
C-4
Module Name
C.3.1.4
C-4
Module Version
C.3.1.5
C-4
Dates and Times
C.3.1.6
C-5
Other Header Records
C.3.2
C-5
Header Types 1 through 4 and 6
C.3.2.1
C-5
Maintenance Status Header Record (MTC)
C.3.2.2
C-6
Record Type
C.3.2.2.1
C-6
Header Type
C.3.2.2.2
C-6
Patch Utility Name
C.3.2.2.3
C-6
Utility Version
C.3.2.2.4
C-6
C.3.2.2.5
U.I.C
C-6
Input File Specification
C.3.2.2.6
C-7
Correction File Specification
C.3.2.2.7
C-7
Date & Time
C.3.2.2.8
C-7
Sequential Patch Number
C.3.2.2.9
GLOBAL SYMBOL DIRECTORY (GSD) RECORDS
C.4
C-7
(OBJ$C GSD)
Program Section Definition (OBJ$C_GSD_PSC) C-7
C.4.1
C-8
Program Section Name
C.4ol.l
C-8
C.4.1.2
Alignment
C-8
Flags
C.4.1.3
C-9
Allocation Field
C.4.1.4

CONTENTS

Page
C.4.2
C.4.2.1
C.4.2.2
C.4.2.3
C.4.2.4
C.4.3

Global Symbol Specification OBJ$C_GSD_SYM
Data Type
Flags
Program Section Index
Value
Entry Point Symbol and Mask Definition
(OBJ$C GSD EPM)
Entry MaskC.4.3.1
C.4.4
Procedure with Formal Argument Definition
(OBJ$C GSD PRO)
C.4.4.1
Minimum ana Maximum Actual Argument Counts
C.4.4.2
Formal Argument Descriptors
C.4.4.2.1
Argument Validation Control Byte
C.4.4.2.2
Remaining Byte Count
C.5
TEXT INFORMATION AND RELOCATION (TIR)
RECORDS (OBJ$C TIR)
Commands
C.5.1
C.5.1.1
Stack Group
C.5.1.2
Store Group
C.5.1.3
Operator Group
C.5.1.4
Control Group
C.5.2
Record Length
Side Effects and Optimization
C.5.3
c.6
END OF MODULE (EOM) RECORD (OBJ$C_EOM)
C.6.1
Error Severity
C.6.2
Transfer Address Flags
C.7
DEBUGGER INFORMATION (DBG) RECORDS
(OBJ$C DBG)
C.7.1
Traceback Information (TBT) Records
(OBJ$C TBT)
C.8
LINK OPTION SPECIFICATION (LINK) RECORDS
(OBJ$C_LNK)
APPENDIX

C-9
C-10
C-10
C-11
C-11
C-11
C-11
C-11
C-12
C-13
C-13
C-13
C-14
C-14
C-15
C-18
C-21
C-22
C-23
C-23
C-24
C-24
C-24
C-25
C-25
C-25

THE ANALYZE PROGRAM

D-1

D.l
D.2
D.2.1
D.2.2
D.2.3
D.2.4
D.2.5
D.2.6

THE ANALYZE COMMAND
THE OUTPUT FILE
Debugger Information Record
End of Module Record
Global Symbol Directory (GSD) Record
Module Header Record
Subheader Records
Text Information and Relocation
(TEXT/RELOCATION) Record
Traceback Information Records
ANALYZE PROGRAM ERROR MESSAGES

D-1
D-2
D-2
D-3
D-3
D-3
D-4

D.2.7
D.3
INDEX

D-4
D-4
D-4
Index-1

CONTENTS

Page

FIGURE

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

8-8
8-9
8-10
8-11
C-1

Modular Programming
Local and Global Symbols
Library Tables
Object Module Synopsis Section
Image Section Synopsis Section
Program Section Synopsis Section
Symbols by Name Section
Symbol Cross Reference Section
Symbols by Value Section
Image Synopsis Section
Link Run Statistics Section
No Transfer Vectors
Transfer Vectors
Transfer Vector Example Listing
Transfer Vector Example Link Command
Transfer Vector Example Map
Listing of FORTRAN Shared COMMON Subprogram
LINK Command for FORTRAN Shared COMMON
Subprogram
Map of FORTRAN Shared COMMON Subprogram
Listing of FORTRAN Program Using Shared
COMMON
LINK Command for FORTRAN Program Using
Shared COMMON
Map of FORTRAN Program Using Shared COMMON
Order of Records Within an Object Module

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

n-4

6-7
6-7
6-9

n-9

n-11
6-11
8-5
8-6.
8-11
8-14
8-15
8-21

8-23
8-24
8-28
8-30
8-31
C-2

TABLES
TABLE

4-1
4-2
5-1
6-1
6-2
7-1
C-1

Command Qualifiers
File Qualifiers
Special Options
Image Map Sections
PSECT Attributes
Order of Image Sections in Clusters
Interpretation of GSY$V WEAK and
GSY$V DEF

vii

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

n-6

7-9
C-10

PREFACE

MANUAL OBJECTIVES
The VAX-11 Linker Reference Manual describes how the VAX-11 Linker
works and tells you how to u-se~it. This manual is designed to educate
as well as to provide easy reference.

INTENDED AUDIENCE
This manual is intended for programming specialists and nonspecialists
alike.
Certain parts of the manual are designed specifically to meet
the needs of certain types of readers.
•

If you are not yet proficient in programming under the VAX/VMS
system or if you do not need to become an expert, this manual
is designed to teach you the main concepts and techniques of
linking as clearly as possible.
Chapters 1 through 6 and
Appendixes A and B are aimed especially at this type of
reader.

•

If you are already proficient in programming under the VAX/VMS
system, this manual provides detailed information about some
of the more complex aspects of linking. Chapters 7 and 8 and
Appendixes C and D are aimed especially at this type of
reader.

STRUCTURE OF THIS DOCUMENT
Chapter 1 introduces the linker.
It defines significant terms,
presents the reasons for the linker's existence, and discusses in
general terms how the linker works.
Chapters 2 and 3 focus on concepts important to understanding the
linker's operation.
The discussion of symbols and references in
Chapter 2 derives from the linker's function of resolving symbolic
references between modules.
Chapter 3 explains libraries, which
normally contain frequently used modules that the linker can include
in user images.
Chapter 4 discusses the LINK command and its command and file
qualifiers.
Chapter 5 focuses on the /OPTIONS file qualifier,
describing how to create and use a linker options file.
Chapter 6 explains the various forms of the image map that the linker
produces on request.
This map provides information about the image
that was created and about the linking process itself.

Chapter 7 goes more deeply into the process by which the linker
creates images. Chapter 7 expands on concepts introduced in Chapter 1
and introduces new concepts.
Chapter 8 presents detailed explanations of shareable images.
The
complex information in this chapter is intended mainly for more
sophisticated programmers and application designers.
The appendixes provide supplementary information.
Appendix A lists
the
error messages that the linker can generate.
Appendix B
illustrates complete brief, default, and full maps of the same image.
Appendix C is a specification of the object language accepted by the
linker; this information is useful to anyone designing a compiler or
assembler whose output must be acceptable to the VAX-11 Linker.
Appendix D explains the object module analysis (ANALYZE) program.

ASSOCIATED DOCUMENTS
The following documents contain information pertinent to linking:
Inforf'!at_!~~--D!E~~!-_()_!."y__~nd

•

VAX-11

Index

•

VAX/VMS Prim~~

•

VAX/VMS Command

•

The user's guide for your programming language(s)

L~_!}-9_!!_~~--.Y_§_~--L~.l:l___.9,!-! . !. 9~

This document uses the following conventions:

Meaning

Convention
Uppercase words
and letters

Uppercase words and letters, used in examples,
indicate that you should type the word or
letter exactly as shown.

Lowercase words
and letters

Lowercase words and letters, used in format
examples, indicate that you are to substitute
a word or value of your choice.

Quotation marks
Apostrophes

The term quotation marks is used to ref er to
marks
(").
The
term
double quotation
apostrophe
(')
is used to refer to a single
quotation mark.
Square brackets indicate that the enclosed
item is optional
(except when used in file
specifications where square brackets delimit
directory names).

{}

Braces are used to enclose lists
one element is to be chosen.

from

which

A horizontal ellipsis indicates that
the
preceding item(s) can be repeated one or more
times.
A vertical ellipsis indicates that not all of
the statements in an example or figure are
shown.
x

SUMMARY OF TECHNICAL CHANGES

This manual describes the VAX-11 Linker, Version 2.
technical changes from the previous version.

The following are

User-defined default object libraries are allowed. These libraries do
not have to be explicitly specified in the LINK command and are
searched before the system default libraries.
The LINK command
qualifier /USERLIBRARY controls user-defined default object libraries.
When creating a shareable image, the linker defers the relocation of
virtual addresses.
Deferred relocation allows the linker to create
position-independent shareable images that contain relocatable address
data.
Each user is given a private copy of image sections that
contain relocatable address data.
The linker supports 31-character symbol names.
The linker can create three new kinds of images:
1) system images
with image headers, 2) executable images that are only stored in PO
address space, and 3) protected shareable images.
The LINK command
qualifiers /HEADER, /POIMAGE, and /PROTECT are used to create these
images. The PROTECT= linker option and the VEC program section
attribute can also be used to create protected shareable images.
The order of image sections within a cluster and the order of clusters
within an image section has been changed.
The PSECT ATTR= linker option changes program section attributes when
an image Ts being linked. The COLLECT= linker option collects program
sections into specified clusters.
The default values for the GSMATCH= option have changed.
An
executable image that is linked with a shareable image created with
the default GSMATCH= option must be relinked if the shareable image is
changed.
The ANALYZE utility is provided to analyze the contents of object
modules and to ensure that they conform to the object language
specification.

CHAPTER 1
LINKER OVERVIEW

The VAX-11 Linker is a programming development tool that takes the
output of a native mode language translator, such as an assembler or
compiler, and binds it into a form that can be executed on the VAX-11
hardware.
The primary input to the VAX-11 Linker is the primary
output from the VAX-11 language compilers and assembler:
files that
contain object modules.
The primary output of the linker is a file
called an image.
The linker can produce three types of images. The most common type,
called executable, is activated in response to a command that you
enter (such as RUN).
Another type of image, called system, is
intended for stand-alone execution on the VAX-11 hardware. The third
type, called shareable, provides a means for sharing procedures and
data among multiple processes within the system. You use a shareable
image by running an executable image that has been linked with it.
Shareable
images also provide a way of linking a very large
application program in a number of smaller phases.
Chapter 7
discusses image creation in detail. Chapter 8 focuses on shareable
images.
The linker assigns values and virtual addresses not only to symbols
defined within each module, but also to symbols defined outside the
module that refers to them. If a symbol is not defined in a module
named in the LINK command, the linker searches one or more libraries
to find the definition of the symbol. Chapter 2 discusses the various
types of symbols. Chapter 3 discusses the use of libraries.
The linker is activated by the LINK command, which you can enter
interactively or within a command procedure. The LINK command permits
many command and file qualifiers, most of which have default values
that are suitable for most cases.
One input file qualifier is
/OPTIONS, which allows you to
convey
additional
input
file
specifications and special instructions for the linker. Chapter 4
explains the LINK command and all its qualifiers. Chapter 5 focuses
on the /OPTIONS qualifier and the special items or options that can
appear in an options file.
The linker can produce, in addition to the image itself, a printable
image map.
You can control the level of detail provided in various
parts of the map. Chapter 6 explains and illustrates the image map.

1-1

LINKER OVERVIEW
1.1

REASON FOR A LINKER

The object modules that a VAX-11 language compiler or assembler
creates are nonexecutable.
You must link the object modules before
you can run them.
The VAX-11 language compilers
several reasons:

and

assembler

require

•

Linking simplifies modular programming.

•

The linker simplifies the job of
assembler.

each

•

The VAX-11 Symbolic
accessed easily.

and

1.1.1

Debugger

language
other

linker

for

compiler

features

can

Modular Programming

Modular programming is the process of combining separately compiled or
assembled modules into an executable program or image. Modular
programming has two aspects:
•

Automatic modularity because
different
source
language
statements generate calls to the same routine developed by
DIGITAL (such as a routine to open or close a file)

•

Modular programming that you design into your program

Some routines developed by DIGITAL that perform commonly needed
functions are the procedures in the VAX-11 Common Run-Time Procedure
Library, which is installed in the system as a shareable image. These
routines can be linked into different images regardless of the
program's original source language. At run time each routine can be
shared by a number of different processes because each routine is
relocatable and reentrant.
(Reentrant code does not modify itself and
consequently can be reused by different processes.)
Users can also make their programs deliberately modular.
Under this
practice, a single complex program is written as a number of smaller
program modules. The modules are compiled or assembled separately and
later linked to create an executable image. Figure 1-1 illustrates
program development in this environment.
In this example, two
programmers write two program modules:
a main section in VAX-11
FORTRAN to perform various calculations, and a second section in
VAX-11 MACRO to handle specific exception conditions.
Modular programming offers several advantages over the traditional
practice of having one programmer write an entire complex program as a
single source module:
•

Smaller modules are usually
write.

•

Different modules of the same program can be written in
different languages.
You can select the language that best
suits the nature of the module's function or your own personal
preference.

•

Errors are easier to analyze and correct in smaller modules.

1-2

manageable

and

easier

LINKER OVERVIEW

CALC.

XCEPT.
MAR

FOR

CALC.

EXE

MAP
Optional

Figure 1-1

1.1.2

Modular Programming

Simplifying Compilation And Assembly

Having a linker perform certain essential functions eliminates the
need
for every native compiler and assembler to handle these
functions. For example, the linker is able to allocate virtual memory
and to provide the memory management interface between the program and
the operating system.
A program's virtual memory can be allocated efficiently only after all
its constituent modules are known.
The linker contains the logic
necessary to group parts of programs according to specific attributes,
with the goal of conserving memory and reducing the amount of paging
activity at run time.
Most programs interact with the operating system.
For example, a
program may use VAX/VMS system services. The linker can generate the
proper program-to-system interfaces that are required.

1.1.3

Debug Capability

Use of the VAX-11 Linker allows you to access the VAX-11 Symbolic
Debugger from the executable image. If you request the debugger, you
can choose whether to activate it at run time.
The ·vAX-11 Symbolic
Debugger Reference Manual explains the capabilities and use of the
debugger.
Programmers should also refer to the information on
debugging in their language user's guides.

1-3

LINKER OVERVIEW
LINKER OPERATION AND FUNCTIONS

1.2

The linker performs the following operations when it creates an image:
•

Allocates virtual memory for the image

•

Resolves symbolic references amonq modules

•

Initializes the image contents

•

Generates the image map, if requested

•

Generates a symbol table file, if requested

Virtual Memory Allocation

1.2.l

The language translators that produce object modules do
addresses for two reasons:

not

allocate

•

They do not know how the modules and sections of modules
be grouped in the final executable image.

will

•

They do not know how much address space is required for many
of the external modules that are called by the module being
assembled or compiled.

The linker, then, must assume the task of allocating virtual memory
for the image. Each object file input to the linker consists of one
or more program sections. The linker groups program sections from
different object files according to various section attributes--for
example, whether the program section is concatenated or overlaid and
what its memory protection requirements are. For further information
on how the linker maps the image, see Chapter 7.

Resolution Of Symbolic References

1.2.2

When a module makes references to symbols outside itself, the linker
searches for these references in other modules explicitly named in the
LINK command. If you specify any libraries, the linker searches them
to resolve references made by preceding files named in the LINK
command. If any references still remain unresolved, the linker
searches any user-defined default libraries and the default system
library. For a detailed discussion of libraries, see Chapter 3.

Image Initialization

1.2.3

After it maps virtual memory and resolves references, the linker fills
in the actual contents of the image.
This image initialization
consists mainly of copying the binary data and code that was written
by the compiler or assembler. However, the linker must perform two
additional functions to initialize the image contents:
•

It must insert addresses into instructions that refer to
externally defined fields. For example, if a module contains
an instruction moving FIELDA to FIELDB, and if FIELDB is
defined in another module, the linker must determine the
virtual address of FIELDS and insert it into the instruction.

1-4

LINKER OVERVIEW

•

1.2.4

It must compute values that depend on externally defined
fields.
For example, if a module initializes location X to
contain Y plus z, and if Y and Z are defined in an external
module, the linker must compute the value of Y plus Z and
insert it in x.

Image Map

If you so request, the linker generates an image map.
The actual
contents of the map depend on the map-reiated command qualifiers that
you enter with the LINK command;
however, entering just the /MAP
qualifier generates a default map with the following sections:
•

An object module synopsis

•

A program section synopsis

•

A list of symbols, with the name and value of each

•

An image synopsis

•

Statistics of the link run

Chapter 6 discusses the command qualifiers that affect the image map.
It also illustrates the map sections and explains significant items.

1.2.5

Symbol Table File

If you so request, the linker produces a file that records the values
of symbols defined within the image. Section 2.3.1 contains further
information on the symbol table file.

1-5

CHAPTER 2
SYMBOLS AND REFERENCES

One of the linker's functions is to resolve symbolic references
between modules. The linker recognizes different types of symbols and
follows guidelines for each type when it tries to supply addresses or
values to statements that refer to these symbols.

2.1

DEFINITIONS: •sYMBOL• AND •REFERENCE•

A symbol is a name associated with a coding statement or with a data
area or field.
A reference is the use of a symbol in a program
statement or a data definition. Consider the following examples (not
tied to a specific programming language):

2.2

•

A program statement identified as ROUTINEA moves FIELDA to
FIELDS.
ROUTINEA is the symbol associated with the program
statement. FIELDA and FIELDS are references made by the
statement.

•

A data definition statement defines FIELDA as being equal to
(A+S)/2.
FIELDA is the symbol associated with the computed
value of (A+S)/2. A and s are references.

TYPES OF SYMBOLS AND REFERENCES

Each symbol is local, global, or universal:
•

Local symbols are available for reference
program module that defines them.

•

Global symbols can be referred to by modules outside the
module that defines them. A global symbol has a strong or a
weak definition (see Section 2.2.2). Another module can make
a strong or a weak reference to a global symbol (regardless of
whether the symbol's definition is weak or strong).
The
linker
resolves
the global references with the global
definition in the other module.

•

Universal symbols are a special type of global symbol that can
be specified only for shareable images.

2-1

only

within

the

SYMBOLS AND REFERENCES
Figure 2-1 illustrates references to local and global symbols in three
modules.
(The statements do not reflect a specific programming
language.) An arrow is drawn between each reference and the symbol to
which it refers.
MODULEA
.--~~·----~--~-

LOCAL1
LOCAL2---+~~~--

Move LOCAL 1 to LOCAL2
Call GLOBAL3
MODULES

MODULEC

LOCAL1

LOCAL1--~~~---1,___

LOCAL2--~~~-+-+-o

LOCAL2-4-----+-i

to LOCAL1
Move LOCAL1
to LOCAL2

Move LOCAL2
to LOCAL1

Figure 2-1

Local and Global Symbols

Local and global symbols can be designated either automatically by the
language compiler or explicitly by qualifiers in program statements.
You can specify the local or global symbol type only in certain
languages.
In VAX-11 MACRO, for example, you can define a symbol as
local or global by using one or two equal signs or colons, as the
following statements show. Note that the term "local symbol" in this
context is different from the term "local label" (for example, 10$:)
in the context of a MACRO program.
Effect

Statement
CRFC MAXREC=292

Assigns a value of 292 to
CRFC MAXREC

the

local

symbol

CRFC MAXREC==292

Assigns a value of 292 to the
CRFC MAXREC

global

symbol

ERR BRANCH:

Makes the coding statement label ERR BRANCH a
local symbol

ERR BRANCH::

Makes the coding statement label ERR BRANCH a
global symbol

In certain other languages, the compiler determines whether a symbol
is local or global. For example, the FORTRAN compiler makes statement
numbers local symbols, and it makes module entry points and common
area names global symbols. For information about designating symbol
type in a specific programming language, see the appropriate language
reference manual.

2-2

SYMBOLS AND REFERENCES
Universal symbols must be specified by the UNIVERSAL= option in the
linker options file.
Chapter 5 explains the use of the /OPTIONS
qualifier with the LINK command.

2.2.1

Local Symbols

You can refer to local symbols only within the object module
defines them. Most symbols in a typical program are local.

that

The compiler or assembler resolves references to
therefore they are not passed on to the linker.

and

2.2.2

local

symbols,

Global Symbols

Global symbols can be referred to by object
module that defines them.

modules

other

than

the

Each global symbol has either a strong or a weak definition.
An
external module can make a strong reference or a weak reference to any
global symbol.

2.2.2.l Strong Definition - A global symbol with a strong definition
is available for reference if the module that defines it is either
explicitly named in the LINK command or contained in a library that is
searched by the linker.
Global symbols usually have a strong
definition, and strong is the default if neither weak nor strong is
specified.
The librarian utility makes an entry for each global symbol with a
strong definition in the global symbol table of a library. Libraries
are discussed in Chapter 3.

2.2.2.2 Weak Definition - A global symbol with a weak definition is
available for reference only if the module that defines it is
explicitly included in the linking operation; that is, the module is
listed as an input file, specified with the INCLUDE qualifier, or
included from a library because another (strong) symbol in the module
is needed.
Weak symbols can be defined in VAX-11 MACRO and ·vAX-11
BLISS. See the VAX-11 MACRO Language Reference Manual for more
information.
The librarian utility routine does not make entries for global symbols
with weak definitions in the global symbol table of a library.

2.2.2.3 Strong Reference - A strong reference is one·whose resolution
is critical to the linking operation. If the linker cannot resolve
all strong references by searching named input modules and libraries
and the default system library, it reports errors and assumes that the
symbol referred to has a value of zero.
Most references to global
default.

symbols

are

2-3

strong,

and

strong

the

SYMBOLS AND REFERENCES
2.2.2.4 Weak Reference - A weak reference is one whose resolution is
not critical to the linking operation. For a weak reference, the
linker searches only named input modules, but not user libraries or
the default system library. The linker does not treat an unresolved
weak reference as an error, but it does assume that the symbol
referred to has a value of zero. Weak references can be made in
VAX-11 MACRO.
An example of the use of weak references might occur in a program that
you want to link now, but that you want to add to and relink later.
In a particular subroutine you might make a weak reference to a symbol
in an external module that will not be written until later. You can
link the image and run it, as long as it does not try to use the
nonexistent symbol during the run.

2.2.3

Universal Symbols

A universal symbol is a special type of global symbol in a shareable
image.
A universal symbol is accessible by other modules when they
link with the shareable image. Universal symbols in a shareable image
contrast with ordinary global symbols in the modules that make up the
shareable image; the ordinary global symbols are available only when
the modules are being linked to create the shareable image.
VAX-11 MACRO provides the .TRANSFER directive to identify an important
class of universal symbols, namely transfer vectors. Otherwise, you
must identify universal symbols with the UNIVERSAL= option in a linker
options file (see Chapter 5). For example, the following LINK command
shows how to designate A and B as universal symbols in the shareable
image ABBOTT.
COSTELLO is an options file that includes the record
UNIVERSAL=A,B.
$ LINK/SHAREABLE ABBOTT,COSTELLO/OPTIONS

COSTELLO.OPT

UNIVERt=~~]
An example of the need for universal symbols might occur if you write
an error-handling routine with several modules to be linked as a
shareable image. You define global symbols for references between the
modules.
However, you must designate as universal any global symbols
that are to be available when an executable image is linked with the
shareable image.
For example, the executable image needs access to
the error-handling shareable image's entry points and perhaps some
constants for defining possible errors.

2.3

SYMBOL TABLES

An image can have neither,
tables:

one,

•

A debug symbol table

•

A global symbol table

2-4

both

the

following

symbol

SYMBOLS AND REFERENCES
The debug symbol table is included only if you specify /DEBUG at link
time.
This debug symbol table normally contains the following types
of information:
•

Module names

•

Routine names and/or program section names

•

All local symbols

However, the local symbols are included only if you request
both compilation time and link time.

debug

The global symbol table is included in an executable image whenever
you include debug in the link. The global symbol table is always
included in a shareable image, regardless .of the qualifiers you
specify at link time. The global symbol table contains an entry for
each global symbol in an executable image and for each universal
symbol in a shareable image. These symbols are listed in the Symbols
by Name section of the image map.

2.3.1

Global Symbol Table As Separate Output

You can output a copy of the image's global symbol table as a separate
file by using the /SYMBOL TABLE qualifier at link time. The symbol
table file is a sequential file containing variable-length records.
Its format is identical to that of object modules (Appendix C explains
this format in detail).
You can specify a symbol table file as input to a linking operation.
The linker makes the global symbols in the symbol table file and their
values available to the object ·modules being linked, without also
linking the entire image with which the global symbols are associated.
One primary use for specifying symbol table files at link time is to
make global symbols in a system image available to a number of other
images without binding the system image into each of the other images.

2-5

CHAPTER 3
LIBRARIES

A library contains object modules and related information, including a
list of the names of the modules and a list of the global symbols
contained in the modules.
(A library can contain modules other than
object modules;
however, the linker is only concerned with object
libraries.) The linker searches one or more libraries to resolve
references to global symbols that are not defined in the object files
previously specified in the LINK command.
When the linker matches a global symbol having an unresolved strong
reference with an entry in a library's table of global symbols, it
binds the module that defines the symbol into the image.
You can
eliminate the need for the linker to search the global symbol table of
the library by explicitly including modules from a library in an
image.
In addition to any libraries that you specify, the linker
automatically searches the following for any unresolved
strong
references:
•

User-defined default libraries, if there are any (See
3.3)

•

The default system library

To create a library, you must use the LIBRARY command,
explained in the VAX/VMS Command Language User's Guide.

3.1

Section

which

that

the

LIBRARY TABLES USED BY THE LINKER

Each object module library contains two lists
linker uses to resolve symbolic references:

tables

•

A module name table, containing an entry for each object
module in the library. Each entry includes the name of the
module and its location within the library file.

•

A global symbol table, containing an entry for each global
symbol in the modules in the library. Each entry includes the
name of the symbol and the location of the module that defines
the symbol.

For example, in a hypothetical library named MINE2, one of the modules
is MODULEZ, which contains the global symbols TAGl and TAG2. Although
it is not intended as an exact schematic illustration, Figure 3-1
shows the relationship of the module name table and the global symbol
table to the rest of the library.

3-1

LIBRARIES
MINE2.0LB
LIBRARY
HEADER
MODULE NAME
TABLE

MODULEZ

0 ne entry in the module name table for

each object module in the library.

GLOBAL SYMBOL
TABLE

Pointers to
the associated
module

TAGl
r--

ne entry in the global symbol table
f or each global symbol in each module.

TAG2

MODULEZ

>O BJECT MODULES

MODULEB

L--

Figure 3-1

3.2

LINKER~S

USE OF LIBRARIES

You can include library modules in
explicitly:
•

Library Tables

the

image

either

implicitly

Implicit inclusion occurs when a module specified in the LINK
command refers to a global symbol defined in a library that
the linker searches. For example, an instruction in a module
named MODULE! moves FIELDA to FIELDS, yet FIELDB is defined
only in the module LIBMOD3 in the library BOBLIB.OLB. You can
specify:
$ LINK MODULEl,BOBLIB/LIBRARY

This causes the linker to search BOBLIB for any unresolved
references from MODULE!.
When it discovers that FIELDB is
defined in LIBMOD3, the linker includes that module in the
image.
•

Explicit inclusion occurs when you name a module with the
/INCLUDE qualifier after the library name. To use the example
in the explanation of implicit inclusion, if you know that
FIELDS is defined in module LIBMOD3 in BOBLIB, you can
simplify the linker's search and explicitly include LIBMOD3 in
the final executable image by specifying:
$ LINK MODULE1,BOBLIB/INCLUDE=LIBMOD3

3-2

LIBRARIES
The linker follows these conventions in using libraries:

•

It processes all input files, including libraries, in the
sequence in which you name them. Thus, the linker searches a
library for unresolved strong references only from previously
named input files.
For example, assume that you enter the
following command:
$LINK A,B,C/LIBRARY,D,E
The linker searches library C for unresolved strong references
from object modules A and B, but not D and E. The search of
library C continues until no more symbols can be resolved.
For example, if module X is included from library C and module
X also has some unresolved strong references, the linker makes
another search of library c.

•

If you specify both the /LIBRARY and /INCLUDE qualifiers after
a library's file specification, the linker includes the named
modules first and then, if necessary, searches the library.
This is true regardless of the order of the two qualifiers.
For example, the following two commands cause the linker to
perform identical actions:
$ LINK A,B/INCLUDE=(MOD1,MOD2)/LIBRARY
$ LINK A,B/LIBRARY/INCLUDE=(MOD1,MOD2)

•

The linker searches the following default libraries for
unresolved strong references after it has processed all named
input files, including user libraries:
- Any user-defined default libraries (see Section 3.3)
- The default system library (see Section 3.4)

These conventions allow you considerable choice when the same global
symbol name is defined differently in modules in different libraries.
For example, if you know that a particular symbol is defined as you
need it in a particular module but is defined differently in another
module (in one of your libraries or the default system library), you
can choose the desired definition by specifying the module with the
/INCLUDE qualifier. If you know that your own library has global
symbols that are defined differently in the default system library,
you can include your own symbols by specifying your library with the
/LIBRARY qualifier.

3.3

USER-DEFINED DEFAULT LIBRARIES

You can define one or more default libraries for the linker to search
before it searches the default system library. You must equate the
logical names LNK$LIBRARY, LNK$LIBRARY 1, and
so
on
(up
to
LNK$LIBRARY 999) to the file specifications of your default libraries.
You can define these logical names in the process, group, and system
logical name tables.
The linker automatically searches any user-defined default libraries
for
unresolved
strong
references,
unless
you
specify
the
/NOUSERLIBRARY qualifier in the LINK command. You can specify in the
/USERLIBRARY qualifier the tables, PROCESS, GROUP, or SYSTEM, that you
want the linker to search. If you specify /USERLIBRARY without a

3-3

LIBRARIES
table list (or do not specify it at all), the linker assumes all
tables are to be searched (/USERLIBRARY=ALL).
The
search
of
user-defined default libraries proceeds as follows:
1.

If you specify /USERLIBRARY=PROCESS or /USERLIBRARY, the
linker searches the process logical name table for the name
LNK$LIBRARY. If this entry exists, the linker translates the
logical
name
and
searches the specified library for
unresolved strong references. If you exclude PROCESS from
the table lsit in /USERLIBRARY or if no entry exists for
LNK$LIBRARY, the linker proceeds to step 4 (searching the
group logical name table).

If any unresolved strong references remain, the linker
searches
the process logical name table for the name
LNK$LIBRARY 1, and follows the logic of step 1. If no entry
exists for- LNK$LIBRARY 1, the linker proceeds to step 4
(searching the group logTcal name table).

If any unresolved strong references remain, the linker
follows the logic of step 1 for LNK$LIBRARY 2, LNK$LIBRARY 3,
and so on, until it finds no match in the- process logical
name table, at which point it proceeds to step 4.

If you specify /USERLIBRARY=GROUP or /USERLIBRARY, the linker
follows the logic in steps 1-3 using the group logical name
table.
If you exclude GROUP from the table list
in
/USERLIBRARY or when any logical name translation fails, the
linkBr proceeds to step 5.

If you specify /USERLIBRARY=SYSTEM or /USERLIBRARY, the
linker follows the logic in steps 1-3 using the system
logical name table. If you exclude SYSTEM from the table
list in /USERLIBRARY or when any logical name translation
fails, the linker searches the default system library (if any
unresolved strong references remain).

An example use of user-defined default libraries is that you may want
the linker to use your private libraries MINEl.OLB and MINE2.0LB as
default libraries, and everyone in your group may want the linker to
use [PROJX]PROJECTX.OLB as a default library. Moreover, the system
manager may want SYS$LIBRARY:MYSITE.OLB as a default library for all
users.
The following commands make the necessary logical name
definitions (the GRPNAM and SYSNAM privileges are required to use the
/GROUP and /SYSTEM qualifiers, respectively):
$ DEFINE LNK$LIBRARY DBAl: [GOLD]MINEl
$ DEFINE LNK$LIBRARY 1 DBAl: [GOLD]MINE2
$ DEFINE/GROUP LNK$LlBRARY DBAl: [PROJX]PROJECTX
$ DEFINE/SYSTEM LNK$LIBRARY SYS$LIBRARY:MYSITE
Note that the logical names in each table must be used consecutiv~ly
(LNK$LIBRARY, LNK$LIBRARY 1, LNK$LIBRARY 2, ••• ). In the preceding
example, if you were to deTete LNK$LIBRARY-from the process logical
name table, the linker would not search for LNK$LIBRARY 1 in the
process logical name table, because it proceeds to the next table as
soon as logical name translation fails.

3-4

LIBRARIES
3.4

DEFAULT SYSTEM LIBRARY

If any unresolved strong references remain after the linker has
processed all your input, it begins a search of the default system
library. This "library" is in fact two files: one a shareable image
called VMSRTL (default file specification is SYS$LIBRARY:VMSRTL.EXE)
and the other an object library called STARLET (default
file
specification is SYS$LIBRARY:STARLET.OLB).

3.4.1

VMSRTL

If the linker needs to search the default system library, it searches
the VMSRTL shareable image first. This shareable image contains most
of the procedures described in the VAX-11 Run-Time Procedure Library
Reference Manual, including many routines required by almost all high
level language programs.
If the linker finds no symbols that it needs in the shareable image,
it does not include the shareable image VMSRTL in the image being
created.
You can use the /NOSYSSHR qualifier with the LINK command to
the linker's search of VMSRTL (see Chapter 4).

3.4.2

suppress

STARLET

STARLET is an object module library. It contains all the object files
used to create the shareable image version of the Run-Time Library, as
well as other less frequently used procedures.
This object library
also contains modules for interfacing to VAX/VMS system services.
The linker searches STARLET if any unresolved strong references remain
after it has searched VMSRTL.
You can use the /NOSYSLIB qualifier to the LINK command to suppress
the linker's search of both STARLET and VMSRTL (see Section 4.2.1).

3.5

EXAMPLE OF USING LIBRARIES

The following example shows how you can specify both explicit and
implicit inclusion of modules from libraries.
(Assume that there are
no user-defined default libraries.)
$ LINK LAUREL,HARDYMINE2/INCLUDE=MODULEZ,MINE3/LIBRARY
These statements tell the linker:
1.

Link the object modules LAUREL and HARDY.

Extract MODULEZ from the library MINE2 and link it
object modules LAUREL and HARDY.

3-5

with

the

LIBRARIES
3.

If any unresolved strong references remain in LAUREL, HARDY,
or MODULEZ, search the library MINE3, and extract and link
any modules needed to resolve these references.

For any strong references that are still
the default system library.

unresolved,

Note that the linker will not search MINE3.0LB and the default system
library if the only unresolved references are weak references.
For a
discussion of weak references, see Section 2.2.2.4.

3-6

CHAPTER 4
THE LINK COMMAND

To invoke the VAX-11 Linker, use the DIGITAL Command Language {DCL)
LINK command.
You can enter the LINK command interactively, or you
can include it in a command procedure.
The LINK command recognizes a number of command qualifiers and file
qualifiers. A command qualifier conveys information about the linking
operation and the image to be created
for example, whether to
generate an image map, or whether to include a debugger in the image.
A file qualifier specifies information about a file that is input to
the linker
for example, identifying the file as a library. Some
qualifiers are valid only if they are used with other qualifiers, and
some qualifiers are incompatible with other qualifiers.
This chapter discusses the LINK command and its qualifiers, but
discusses command syntax only where necessary to avoid errors or
misunderstanding. For detailed information on command syntax, see the
VAX/VMS Command Language User's Guide.

4.1

COMMAND FORMAT

The LINK command is usually entered in the following format:
$ LINK/command-qualifier ••• file-spec/file-qualifer, •••

You must enter at least the LINK command name and one input file name.
You can enter multiple command qualifiers and file specifications, and
one or more file qualifiers for each file specification.
Slashes {/) separate qualifiers from each other and from the command
name or file specification with which they are associated. One or
more spaces or tabs must separate the last command qualifier from the
first input file specification. A comma must precede the second and
subsequent input file specifications.
The following examples show some acceptable
command {Section 4.3 explains these examples).

formats

$ LINK PROGA
$ LINK/MAP/DEBUG PAYROLL,FICA,PAYLIB/LIBRARY
$ LINK/MAP/FULL/EXECUTABLE=STOOGES CURLY,-

LARRY,MOE,TVLIB/INCLUDE=OLDIES,COMEDY/LIBRARY,SLAPSTICK/OPTIONS

4-1

the

LINK

THE LINK COMMAND
The names assigned to the image file, the map file, and other output
files depend on the first input file name, unless you specify
differently.
You can specify a different output
filename
by
specifying
a
name
in
an
/EXECUTABLE, /SHAREABLE, /MAP, or
/SYMBOL TABLE qualifier or by entering one of these qualifiers after a
file specification (see Section 4.2). In the second of the preceding
examples, the image file and the map file will be named PAYROLL.
In
the third example, the image file will be named STOOGES because you so
specified with the /EXECUTABLE qualifier, but the map file will be
named CURLY.
(To name the map file STOOGES, you must specify
/MAP=STOOGES.)

4.2

COMMAND AND FILE QUALIFIERS

You can enter many command and file qualifiers, but normally you will
not need to because most qualifiers have default values that the
linker uses if you omit the qualifier.
Some qualifiers are incompatible with certain other qualifiers.
The
linker
takes
one of two actions if you specify incompatible
qualifiers:
either it invalidates the entire LINK command and
displays
an
error
message, or it ig1~ores certain qualifiers
(generally, all except the last valid one) and allows the link to
continue.
For example, if you specify /FULL and /BRIEF for the map,
the linker rejects the entire command;
but if you specify the
positive and negative forms of a qualifier (say, /EXECUTABLE and
/NOEXECUTABLE), the linker accepts the last one entered.
Tables 4-1 and 4-2 list the command and file qualifiers, the default
value
for each command qualifier, the function for each file
qualifier, and incompatible qualifiers. A [NO]
indicates that the
qualifier can be negated by prefixing NO (without brackets) -- for
example, /NODEBUG or /NOEXECUTABLE.
Any entry after a negative
qualifier is not valid; for example, it would be nonsense to enter
/NOEXECUTABLE=PAYROLL.
Sections 4.2.l and 4.2.2 discuss the command qualifiers and file
qualifiers individually.
Within each section the qualifiers are
presented in alphabetical order.

4-2

THE LINK COMMAND
Table 4-1
Command Qualifiers
Incompatible
Command Qualifier
Default
Qualifiers
i---------------------+--------------+-------------/BRIEF

Default map

/NOMAP,/FULL,
/CROSS_REFERENCE

/[NO]CONTIGUOUS

/NOCONTIGUOUS

/NOEXECUTABLE

/[NO]CROSS_REFERENCE

/NOCROSS_REFERENCE

/NOMAP,/BRIEF

/[NO]DEBUG[=file-spec]

/NODEBUG

/NOTRACEBACK,
/SHAREABLE,/SYSTEM,
/NOEXECUTABLE

/[NO]EXECUTABLE[=file-spec]

/EXECUTABLE

/SHAREABLE

/FULL

Default map

/NOMAP, /BRIEF

/HEADER
/[NO]MAP[=file-spec]

/NOMAP (interactive)
/MAP (batch)

/PO IMAGE
/PROTECT

/SYSTEM,
/EXECUTABLE

/[NO]SHAREABLE[=file-spec]

/NOSHAREABLE

/[NO]SYMBOL_TABLE[=file-spec]

/NOSYMBOL_TABLE

/[NO]SYSLIB

/SYS LIB

/[NO]SYSSHR

/SYSSHR

/NOSYSLIB

/[NO]SYSTEM[=base-address]

/NOSYSTEM

/DEBUG,
/SHAREABLE

/[NO]TRACEBACK

/TRACEBACK

/[NO]USERLIBRARY[=(table[, ••• ])]

/USERLIBRARY=ALL

4-3

/SYSTEM,
/DEBUG,
/EXECUTABLE

THE LINK COMMAND
Table 4-2
File Qualifiers

File Qualifier

Function

Incompatible
Qualifiers

/INCLUDE=module-name[, ••• ]

Includes one or
All others, except
more object modules /LIBRARY
from a library in
the link

/LIBRARY

Identifies an
object module
library

All others, except
/INCLUDE

/OPTIONS

Identifies a
linker options
file

All others

/SELECTIVE_SEARCH

Includes only
global symbols
ref erred to by
previously named
input files

All others, except
/SHAREABLE

/SHAREABLE[=[NO]COPY]

Identifies a
shareable image
input file; valid
only in a linker
options file

All others, except
/SELECTIVE_SEARCH

. . ····-···

4.2.1

.. ·····---·--·----------'------------ .

Command Qualifiers

/BRIEF
/BRIEF produces a brief form of the image
contains only the following sections:
•

Object Module Synopsis

•

Image Synopsis

•

Link Run Statistics

map.

brief

map

A brief map does not contain the Program Section Synopsis and the
Symbols by Name sections, which are included in the default map.
/BRIEF is valid only if you also specify /MAP in the LINK
command. /BRIEF is incompatible with /FULL and /CROSS_REFERENCE •.
For illustrations and explanations of the image map sections, see
Section 6.2.

4-4

THE LINK COMMAND

/CONTIGUOUS
/NOCONTIGUOUS
/CONTIGUOUS forces the entire image to be placed in consecutive
disk blocks. If sufficient contiguous space is not available on
the output disk, the linker reports the error and terminates the
link operation without generating an image.
You can use the /CONTIGUOUS qualifier to
improve
paging
performance for all types of images because an image usually runs
slower if it is not contiguous. You can also use the /CONTIGUOUS
qualifier to satisfy the requirement of bootstrap programs for
certain system images, since many bootstrap programs cannot
handle discontiguous images.
If you do not specify
/CONTIGUOUS,
the
linker
assumes
/NOCONTIGUOUS by default.
That is, if sufficient contiguous
space is not available, the image is divided and placed in
different areas on disk.
{However, the operating system still
tries to make the image as close to contiguous as possible.)
/CROSS REFERENCE
/NOCROSS_REFERENCE
/CROSS REFERENCE causes the Symbols by Name section of the image
map to be replaced by a Symbol Cross Reference section, which
lists global symbols in alphabetical order and the following
information about each symbol:
•

Its value

•

The name of the first module that defines it

•

The name of each module that refers to it

The number of symbols listed in the cross reference depends on
whether you specified /FULL for the map or accepted the default
map. A full map contains global symbols from all modules in the
image, including modules extracted from libraries. The default
map generally excludes global symbols that are defined and
referred to only within the default system library.
/CROSS REFERENCE is valid only if you also specify /MAP in
LINK command. /CROSS_REFERENCE is incompatible with /BRIEF.

the

If you do not request a cross reference, none is provided;
the
map still lists global symbols in alphabetical order, but gives
only the value for each one.
/DEBUG[=file-spec]
/NODEBUG
/DEBUG tells the linker to bind a debugging module into the
image.
When the image is run, the debugger receives control
first. /DEBUG does not have any effect on the location of code
within the image;
the image map is the same with /DEBUG or
/NODEBUG.
If you specify /DEBUG, you can also enter the file specification
of a user-written debug module. If you enter a debugging module
file specification without specifying the file type, the linker
assumes OBJ.

4-5

THE LINK COMMAND
If you specify /DEBUG without entering a file specification, the
linker uses the VAX-11 Symbolic Debugger. This debugger includes
a debug symbol table (discussed in Section 2.3) and coding logic
to help in debugging the image at run time.
For further
information, see the VAX-11 Symbolic Debu9ger Reference Manual.
/DEBUG automatically includes /TRACEBACK. If you specify /DEBUG
and /NOTRACEBACK, the linker overrides your specification and
includes traceback information.
If you do not specify /DEBUG, the linker assumes /NODEBUG.
/EXECUTABLE[=file-spec]
/NOEXECTABLE
/EXECUTABLE tells the linker to create an executable image, as
opposed to a shareable image or a system image. You can also
enter a file specification for the image; however, if you do not
enter one, the linker uses the file name of the first input file
or if you specify /EXECUTABLE after an input file specification,
the name of the modified file. If you do not enter a file type
after the filename, the linker assumes a file type of EXE.
If you specify both /SYSTEM and /EXECUTABLE, the linker creates a
system image but uses the /EXECUTABLE qualifier to determine the
image's file-specification.
/NOEXECUTABLE tells the linker to perform all the actions
involved in creating an executable image, but not to output it.
You can use /NOEXECUTABLE to test combinations of files and
qualifiers without actually creating an image.
If you do not specify /NOEXECUTABLE, /SHAREABLE, or /SYSTEM,
linker assumes /EXECUTABLE.

the

/FULL
/FULL produces the most complete map of the image. The full map
contains all the sections found in the default map, although
several sections contain more detailed information. The full map
also contains two sections not found in the default map. The
following sections of a full map contain information about all
modules in the image.
(In the default map, these sections
generally omit information about modules from the default system
library.)
•

Object Module Synopsis

•

Program Section Synopsis

•

Symbols by Name

The following sections are included in a full map, but not in the
default map:
•

Image Section Synopsis

•

Symbols by Value

For illustrations and explanations of the image map sections, see
Section 6.2.
/FULL is valid only if you also specify /MAP in the LINK command.
/FULL is incompatible with /BRIEF but not with /CROSS_REFERENCE.

4-6

THE LINK COMMAND
/HEADER
/HEADER is used with /SYSTEM; it tells the linker to create a
system image with a header.
If you specify /SYSTEM without
/HEADER, the linker creates a system image without a header.
Executable and shareable images always have image headers;
consequently, /HEADER is ignored in LINK commands creating these
images.
/MAP[=file-spec]
/NO MAP
/MAP causes the linker to create an image map as a separate file.
You can enter a file specification for the image map file;
however, if you do not enter one, the linker uses the file name
of the first input file or, if you specify /MAP after an input
file specification, the name of the modified file. If you do not
enter a file type after the file name, the linker assumes a file
type of MAP.
If you enter /MAP, you can further specify the contents of the
map with the /BRIEF, /FULL, and /CROSS REFERENCE qualifiers. If
you enter /MAP and no related qualifier~ the linker produces a
default map that contains the following sections:
•

Object Module Synopsis

•

Program Section Synopsis

•

Symbols by Name

•

Image Synopsis

•

Link Run Statistics

For illustrations and explanations of the image map sections, see
Section 6.2.
If you do not specify /MAP, the default for interactive mode is
/NOMAP;
that is, the linker does not generate an image map. In
a batch job the default is /MAP; that is, the linker generates
its standard (default) map.
/PO IMAGE
/POIMAGE is used to create executable images that modify Pl
address space. The linker places the stack and RMS buffers that
usually go in Pl address space in PO address space.
See the
VAX-11 Architectur~ __!!_9ndbook for a description of PO and Pl
address space.
/PROTECT
/PROTECT is used with /SHAREABLE;
it tells the linker to protect
the shareable image, making it a privileged shareable image. A
privileged shareable image can execute change mode instructions
even when it is linked into a nonprivileged executable image.
See the VAX/VMS Real-Time User's Guide for more information on
privileged shareable images.

4-7

THE LINK COMMAND
/SHAREABLE[=file-spec]
/NOSHAREABLE
/SHAREABLE tells the linker to create a shareable image.
(For an
explanation of shareable images, see Section 7.6.2 and Chapter
8.) You can also enter a file specification for the shareable
image;
however, if you do not enter one, the linker uses the
file name of the first input file or, if you specify /SHAREABLE
after an input file specification, the name of the modified file.
If you do not enter a file type after the file name, the linker
assumes a file type of EXE.
You cannot run a shareable image, but you can link it with object
modules or other shareable images.
(See the explanation of the
/SHAREABLE file qualifier in Section 5.1.2.)
If you specify /SHAREABLE, you cannot specify /SYSTEM or /DEBUG.
If you specify both /SHAREABLE and /EXECUTABLE, the linker
ignores /EXECUTABLE and creates a shareable image.
If you do not
specify
/SHAREABLE,
the
linker
assumes
/NOSHAREABLE; that is, the image is not a shareable image.
(See
the explanation of the /EXECUTABLE command qualifier in this
section.)
/SYMBOL TABLE[=file-spec]
/NOSYMBOL_TABLE
/SYMBOL TABLE tells the linker to create a separate file, with a
default- file type of STB, containing the image's global symbol
table. This qualifier does not affect the global symbol table in
the image itself; rather, it causes an additional global symbol
table to be created in object module format. You can also enter
a file specification for the global symbol table file; however,
if you do not make this entry, the linker uses the name of the
first input file or, if you specify /SYMBOL TABLE after an input
file specification, the name of the modified-file.
You can include the symbol table file as input to future linking
operations, just as if it were an object module. For further
information, see Section 2.3.1.
If you do not
/NOSYMBOL TABLE;
file.
-

specify /SYMBOL TABLE, the
linker
assumes
that is, it does not generate a symbol table

/SYSLIB
/NOSYSLIB
/SYSLIB tells the linker to search the default system library for
unresolved strong references to global symbols after it has
searched any specified user libraries and any user-defined
default libraries.
(Section 3.4 explains the default syst~m
library.) You will probably want the linker to search the default
system library for almost all linking operations. If you do not
specify /NOSYSLIB, the linker assumes /SYSLIB by default.
/NOSYSLIB tells the linker not to search the default system
library
(VMSRTL.EXE
and STARLET.OLB).
You should specify
/NOSYSLIB only if you know that other specified libraries allow
the linker to resolve all symbolic references and if you have a
good reason for suppressing the system library search.
If you
specify both /NOSYSLIB and /SYSSHR, the /SYSSHR qualifier is
ignored.

4-8

THE LINK COMMAND
/SYSSHR
/NOSYSSHR
/SYSSHR tells the linker to search the default system run time
library
shareable image
(VMSRTL.EXE) for unresolved strong
references to global symbols.
If any symbol within
this
shareable image resolves an outstanding reference, the shareable
image is included in your program as the highest-addressed part
of the program region.
The primary use of this qualifier, however, is in its negative
form.
/NOSYSSHR tells the linker not to try to resolve symbolic
references by including the default system shareable image.
Instead it directs the linker to use only the default object
library (STARLET.OLB), which includes all the routines in VMSRTL.
To tell the linker to search neither the default system shareable
image nor the default system object library, use the /NOSYSLIB
qualifier.
/SYSTEM[=base-address]
/NOSY STEM
/SYSTEM tells the linker to create a system image.
(For an
explanation of system images, see Section 7.n.3.) You can also
specify a base address at which the system image will be loaded
at run time, and you can express this address in decimal (%D),
hexadecimal (%X), or octal (%0) format. If you specify /SYSTEM
without a base address, the linker assumes %X80000000. The
linker uses the filename of the first input file and the file
type EXE. If you want a different output file-specification, you
must also specify /EXECUTABLE.
If you specify /SYSTEM, you cannot specify /SHAREABLE or /DEBUG.
If you do not specify /SYSTEM, the linker assumes /NOSYSTEM;
that is, the image is not a system image.
(See the explanation
of the /EXECUTABLE command qualfier in this section.)
/TRACEBACK
/NOTRACEBACK
/TRACEBACK tells the linker to include traceback information in
the image.
Traceback ~s a facility that automatically displays
information from the call stack when a fatal program error
occurs.
The output shows which modules were called before the
error occurred.
The linker assumes /TRACEBACK unless you exclude the facility by
specifying
/NOTRACEBACK.
If you enter /DEBUG, the linker
automatically includes traceback also; therefore, if you specify
both
/DEBUG and /NOTRACEBACK, you receive a warning that
/NOTRACEBACK has been ignored.
/USERLIBRARY[=(table[, ••• ])]
/NOUSERLIBRARY
/USERLIBRARY tells the linker to search any user-defined default
libraries after it has searched any specified user libraries.

4-9

THE LINK COMMAND
The linker searches the process, group, and system logical name
tables to find the file specifications of the user-defined
libraries.
(Section
3.3
explains
user-defined
default
libraries.) You can specify the following tables that you want
the linker to search:
ALL

The linker searches the
logical
name
tables
definitions.

GROUP

The linker searches the group logical
user-defined library definiti~ns.

NONE

The linker does not search any logical name table;
/USERLIBRARY=NONE is equivalent to /NOUSERLIBRARY.

PROCESS

The linker searches the process logical name
user-defined library definitions.

table

for

SYSTEM

The linker searches the system logical
user-defined library definitions.

table

for

/NOUSERLIBRARY
/USERLIBRARY=ALL

or
by

If
you
do
not
/USERLIBRARY=(table),
default.

process, group, and system
for
user-defined
library

specify
either
the linker assumes

/NOUSERLIBRARY tells the linker not to
default libraries.

4.2.2

name

any

table

for

user-defined

File Qualifiers

/INCLUDE=module-name[, ••• J
/INCLUDE tells the linker to include the named module or modules
from the associated library in the image. To specify more than
one module, enclose the list in parentheses and separate module
names with commas. /INCLUDE does not cause the linker to search
the rest of the associated library for unresolved references,
unless you also specify /LIBRARY. For further information on
libraries, see Chapter 3.
The following two examples show uses of the /INCLUDE qualifier
with a library named NATIONAL that contains many modules, among
them REDS, DODGERS, and PHILS.
$ LINK LEAGUE,NATIONAL/INCLUDE=(REDS,DODGERS,PHILS)

This example tells the linker to extract modules REDS, DODGERS,
and PHILS from the library NATIONAL and include them in the
executable image which will be named LEAGUE (since that is the
name of the first input file).
$ LINK LEAGUE,NATIONAL/LIBRARY/INCLUDE=(REDS,DODGERS,PHILS)
This example also tells the linker to include REDS, DODGERS, and
PHILS in LEAGUE.
However, the /LIBRARY qualifier tells the
linker to search the rest of the library NATIONAL and link in any
other modules needed to resolve strong symbolic references in
LEAGUE, REDS, DODGERS, and PHILS.

4-10

THE LINK COMMAND
/LIBRARY
/LIBRARY identifies a file as a library.
The linker searches
libraries that you specify if any unresolved strong symbolic
references between modules remain after it links the previously
named input files and any previously named library modules
specified with the /INCLUDE qualifier. For further information
on libraries, see Chapter 3.
/LIBRARY cannot be the only qualifier on the first input file,
since there are as yet no outstanding references to be resolved
from this library.
/OPTIONS
/OPTIONS identifies a file as a linker options file.
This file
can contain input file specifications, as well as special
instructions recognized only by the linker and not by the command
interpreter.
Chapter 5 explains how to create an options file and what it can
contain.
Chapter
5
also discusses each of the special
instructions you can include in the options file.
/SELECTIVE_SEARCH
/SELECTIVE SEARCH tells the linker to include in the image's
global symbol table only those global symbols in the associated
file that previously named input files refer to. If you do not
specify /SELECTIVE SEARCH for an input file, all of its global
symbols are included in the global symbol table of the image.
/SHAREABLE[=[NO]COPY]
/SHAREABLE as an input file qualifier is valid only within a
linker options file.
Section 5.1.2 explains the use of the
/SHAREABLE file qualifier.

4.3

EXAMPLES
1.

$ LINK PROGA

The linker binds the object module PROGA and creates an
executable image named PROGA.
The linker searches any
user-defined default libraries and the default system library
for any unresolved strong symbolic references in PROGA.OBJ.
All linker defaults are used.
2.

$ LINK/MAP/DEBUG PAYROLL,FICA,PAYLIB/LIBRARY

The linker binds object modules PAYROLL and FICA, searching
the library PAYLIB for unresolved strong references in the
two object modules before searching any user-defined default
libraries or the default system library. The linker also
includes the VAX-11 Symbolic Debugger in the image.
The name of the executable image is PAYROLL. The linker also
generates an image map (in the default map format) with a
file name of PAYROLL and a file type of MAP.

4-11

THE LINK COMMAND

$ LINK/MAP/FULL/EXECUTABLE=STOOGES CURLY,-

LARRY,MOE,TVLIB/INCLUDE=OLDIES,COMEDY/LIBRARY,SLAPSTICK/OPTIONS
The linker binds object modules CURLY, LARRY, and MOE, as
well as the module OLDIES from the library TVLIB. The linker
searches the library COMEDY for any unresolved symbolic
references in CURLY, LARRY, MOE, and OLDIES, before searching
any user-defined default libraries or the default system
library.
The linker uses the options file SLAPSTICK for
additional input file specifications or special instructions.
The linker generates a full map, with the default file name
of CURLY and the file type of MAP. The executable image is
named STOOGES.

4-12

CHAPTER 5
THE /OPTIONS FILE QUALIFIER

The /OPTIONS file qualifier identifies a linker options file.
include two types of information in this file:
•

Input file specifications and associated file qualifiers,
addition to any that you enter in the LINK command itself

•

Special instructions to the linker
through the DCL command language

that

are

When you specify an opt~ons file at link time, the
file before performing the linking operation.

5.1

You can

not

linker

available
reads

the

USES FOR AN OPTIONS FILE

You can create an options file and use the /OPTIONS
number of reasons:

qualifier

for

•

To give the linker a series of file specifications and
qualifiers that you use frequently in linking operations

file

•

To identify a shareable image as an input
operation

link

•

To enter a longer list of files and file qualifiers than the
VAX/VMS command interpreter can hold in its command input
buffers

•

To specify information that applies only to
other command

file

LINK

the

and

Entering Frequently Used Input Specifications

5.1.1

You can create an options file containing a
group
of
file
specifications and file qualifiers that you link frequently, and you
can specify this options file as input to the linker. The advantages
of
this method are convenience and flexibility.
Consider the
following two examples.
1.

You want to create an executable image named
PAYROLL
containing modules named PAYCALC, FICA, FEDTAX, STATETAX, and
OTHERDED. You also want to be able to make changes to any of
the modules and conveniently relink the image.
To accomplish these goals, you can use the EDIT or CREATE
command to create the file PAYROLL.OPT containing the file

5-1

THE /OPTIONS FILE QUALIFIER
specifications of the five modules. Then, to link the image
initially or to relink it any time thereafter, you can simply
enter $LINK PAYROLL/OPTIONS, instead of having to enter the
/EXECUTABLE=PAYROLL qualifier and the file specifications of
all the input modules each time.
(Note that using the
options
file in this example produces an image named
PAYROLL.) The more file specifications and file qualifiers
that
you need to link an image, the greater is the
convenience of using an option file.
2.

Two programmers, one writing PROGX and the other PROGY, both
need to include the modules MODA, MODB, and MODC, and to
search the library LIBZ. Someone can create an options file
(say,
[Gl5]GROUP15.0PT) containing the file specifications
for MODA, MODB, and MODC, and the specification for LIBZ
followed by /LIBRARY.
At link time, then, each programmer
needs to specify only the name of his or her module and the
options file-- for example:
$LINK/MAP PROGX,[Gl5]GROUP15/0PTIONS

5.1.2

Identifying A Shareable Image As Input

To identify a shareable image as an input file to the linker, you must
use the /SHAREABLE file qualifier within an options file.
(If you
include /SHAREABLE in the LINK command, the linker assumes that it is
a command qualifier, not an input file qualifier.)
The format for /SHAREABLE as an input file qualifier is as follows:
/SHAREABLE[=[NO]COPY]

5.1.3

•

/SHAREABLE identifies the associated input file as a shareable
image.

•

You can optionally specify COPY or NOCOPY as keywords.
COPY
causes the linker to produce a private copy of the shareable
image in the image being created.
NOCOPY, which is the
default, causes the linker not to produce a private copy.

Entering More Input Than The Command Language Can Handle

At times you may need to link a series of input files and file
qualifiers that exceeds the buffer capacity of the command interpreter
(255 characters). The maximum number of entries depends on the length
of the specific entries themselves and how much of each line you use.
However, as a general guideline, if your LINK command statement
exceeds six or seven lines, the command interpreter may not be able .to
process it. In this case, you must put some or all of the input file
specifications and file qualifiers in an options file.

5.1.4

Entering Non-standard Link Instructions

The linker is more complex than most VAX/VMS utilities;
it can
perform a number of optional functions in creating an image. Although
the LINK command could have been designed to accept a very large
number of command qualifiers, some of these optional functions are not
frequently used and apply only to the linker -- for
example,

5-2

THE

specifying
can use.

the

/OPTIONS FILE QUALIFIER

image's base address or the number of I/O channels it

Therefore, to keep the size of the command interpreter's internal
tables and code to a manageable level, the /OPTIONS qualifier was
developed. /OPTIONS is recognizable to the command interpreter, but
the
special
functions that the options file can specify are
recognizable only to the linker. When you specify an options file,
then, the command interpreter passes the file to the linker, which
reads and interprets its contents.
Table 5-1 lists the special functions that you can request only in an
options file, giving the following information for each: its format,
the default value (if applicable), and a brief explanation.
Section
5.3 provides detailed explanations of each special function.
Table 5-1
Special Options
Format

Explanation

Default

BASE=n

%X200 for executable
and shareable
%X80000000 for
system

Base virtual
address for the
image

CHANNELS=n

128 (See Section 5.3)

Maximum number of
I/O channels the
image can use
during execution;
reserved for future
use

CLUSTER=cluster-name,- (See explanation
[base-address] ,in Section 5.3.)
[pfc],file-spec[, ••• ]

Defines a
cluster

COLLECT=cluster-name,psect-name [, ••• ]

Moves the named
program sections to
the specified
cluster

DZRO MIN=n

Minimum number of
uninitialized pages
before demand zero
compression can
occur

GSMATCH=keyword,major-id,minor-id

EQUAL,x,y
(see Section 5.3)

Sets match control
parameters of a
shareable image

I OSEGMENT=n, [[NO] POBUFS]

32, POBUFS

Number of pages for
the image I/O
segment

ISO MAX=n

Approximately 96
(See Section 5.3)

Maximum number of
image sections
(continued on next page)

5-3

THE /OPTIONS FILE QUALIFIER
Table 5-1 (Cont.)
Special Options
Format

PROTECT=

{~~S}

Default

Specifies protected
clusters when
creating a
shareable image

PSECT ATTR=psect-name,attribute [, ••• ]
STACK=n

Explanation

Specifies the
attributes of a
program section
Initial number of
pages for the user
mode stack

SYMBOL=name,value

Defines the named
symbol as global
and assigns it a
value

UNIVERSAL=symbol-name

Identifies a global
symbol as universal

[

5.2

, ... ]

CREATING AND SPECIFYING AN OPTIONS FILE

To use the /OPTIONS qualifier, you must first create the options file.
Use the EDIT command, specifying any valid file name and a file type
of OPT.
(You can use any file type, but the linker uses a default
file type of OPT with the /OPTIONS qualifier.)
The options file can contain input file specifications and associated
file qualifiers, or the special link options outlined in Table 5-1, or
both types of information. The following rules apply to the contents
of a linker options file:
1.

You must enter any input file specificatipns and associated
file qualifiers before any special options {see Table 5-1 for
the
available
special
options).
The
input
file
specifications must be on the first line of the options file
or on a continuation of the first line and must be separated
by commas.

You cannot enter command qualifiers.

You cannot enter the /OPTIONS file qualifier.

You can enter /SHAREABLE as an input file qualifier
an options file (see Section 5.1.2).

You cannot enter more than one special option on a line.

You can continue a
option line.

file

specification

5-4

line

only

special

THE /OPTIONS FILE QUALIFIER
7.

You can enter comments after an exclamation point (!).

You can shorten the name of a special option, as long as you
enter at least the first four characters (for example,
CHAN=SO instead of CHANNELS=SO).

The following example shows a file named PROJECT3.0PT
both input file specifications and special options:

that

contains

PROJECT 3. OPT
MOD1,MOD7,LIB3/LIBRARY,LIB4/LIBRARY/INCLUDE=(MODX,MODY, MODZ),MOD12/SELECTIVE SEARCH
STACK=75
SYMBOL=JOBCODE,5
To include all the specifications and options in this example at link
time, you need specify only the file name followed by /OPTIONS. For
example:
$ LINK/MAP/CROSS REFERENCE PROGA, PROGB,PROGC, PROJECT3/0PTIONS
If you have entered the SET VERIFY command, the contents
options file are displayed as the file is processed.

You can specify one
statement.

command

several

options

files

LINK

the

If you want the LINK command to be in a command procedure, you can
specify SYS$INPUT:
as an options file. Otherwise the LINK command
will be in two files. For example, a command procedure, LINKPROC.COM
could contain the following:
$ LINK MAIN,SUB1,SUB2,SYS$INPUT:/OPTIONS
MYPROC/SHAREABLE
SYS$LIBRARY:APPLPCKGE/SHAREABLE
STACK=75
$ •

5.3

SPECIAL OPTIONS

This section lists the available special options in alphabetical order
and explains each o~e. Each option has the general format:
option_name=parameter[, ••• ]
If the parameter is a number (indicated by "n"), you can express it in
decimal (%0), hexadecimal (%X), or octal (%0) format. The default and
maximum numeric values in this manual are expressed in decimal, as are
the values in any linker error or warning messages relating to these
options.

THE /OPTIONS FILE QUALIFIER
BASE=n
BASE= specifies the base virtual address of the default
cluster.
If you do not define any clusters with the CLUSTER=
option, the BASE= option value also specifies the base virtual
address of the whole image. If you specify an address that is
not divisible by 512, the linker automatically adjusts it
upward to the next multiple of 512 (that is, the next highest
page boundary).
The default base address is hexadecimal 200 (decimal 512) for
executable and shareable images, and hexadecimal 80000000 for
system images.
CHANNELS=n
CHANNELS= specifies the maximum number of I/O channels that
the image can use while it is running.
This option is
currently ignored by the linker. All images have a maximum of
128 channels.
CLUSTER=cluster-name, [base-address], [pfc],file-spec[, ••• ]
CLUSTER= defines
Chapters 7 and 8.
information:

a cluster.
Clusters are discussed
in
The CLUSTER= option specifies the following

•

The name the linker will assign to it

•

Optionally, the base virtual address of the cluster

•

Optionally, the page fault cluster (pfc) -- that is,
the number of pages to be read into memory when a
fault occurs for a page in the cluster

•

Specifications for the file or files that the linker
is to use in creating the cluster. Note that you
should not specify in th~ LINK command itself any
files that you specify with the CLUSTER= option
(unless you want two copies of each file included in
the final image).

If you omit the base address or the
both, you must still enter the
parameter. For example:

page fault clustar, or
comma after each omitted

CLUSTER=AUTHORS,,,TWAIN,DICKENS
The linker uses the following defaults in connection with
CLUSTER= option:

the

•

If you do not use the CLUSTER= option, the linker
creates a default cluster, as described in Section
7.9.

•

If you use the CLUSTER= option but do not specify a
base
address,
the linker allocates the cluster
according to the procedure described in Section 7.9.

•

If you use the CLUSTER= option but do not
page
fault
cluster,
VAX/VMS
memory
determines the value.

5-6

specify a
management

THE /OPTIONS FILE QUALIFIER
COLLECT=cluster-name,psect-name[, ••• ]
COLLECT= causes the named program sections to be placed in the
specified cluster.
If the cluster name is also used in a
CLUSTER= option, the named program sections are added to that
defined cluster.
If the cluster name is not also used in a
CLUSTER= option, the COLLECT= option defines the cluster.
The COLLECT= option can only specify program sections
with the GBL attribute.
The COLLECT= option cannot specify any program
are defined in shareable images.

defined

sections

that

DZRO MIN=n
DZRO MIN= is an option that gives you some control over the
linker's compression of uninitialized pages in an executable
image. Before the linker writes the binary data and code of
the image, it attempts to compress certain uninitialized areas
by converting them to demand zero image sections.
("Demand
zero" means that although an area does not occupy physical
space in the image on disk, when the area is accessed during
execution, a portion of memory is allocated for it and
initially filled with binary zeroes.) An uninitialized area
is eligible for this compression if it can be written in by
the user and if its size is equal to or greater than a
threshold value:
that is, the DZRO MIN= value. The linker
will not, however, continue creating- demand zero sections
after the total number of image sections reaches the maximum
(see the ISD_MAX= option in this section).
The default value for DZRO MIN= is 5;
that
is,
an
uninitialized, writeable area is not eligible for compression
unless it occupies five or more contiguous pages. A DZRO MIN=
value less than 5 might
(depending on the contents of the
object modules) cause the linker to compress more sections and
create a greater number of image sections, possibly reducing
the image size on disk but decreasing its paging performance.
A value greater than 5 might cause the linker to compress
fewer sections and create a smaller number of image sections,
possibly increasing the image size on disk but providing
better performance during execution.
GSMATCH=keyword,major-id,minor-id
GSMATCH= sets the match control parameters for a shareable
image that you are now creating. After the shareable image
has been linked with an executable image, and when the
executable image is being run, these parameters guide the
VAX/VMS image activator in choosing global sections.
For
further information on this process, see Section 8.3.2.
The GSMATCH= option specifies the following information:
•

A keyword expressing the match relationship between
the minor identifications in the user shareable image
section and in the installed global section.
This
keyword is one of the following:
EQUAL The minor identification
of
the
user
shareable image section must be identical to that
of the installed shareable image section.

5-7

THE /OPTIONS FILE QUALIFIER
LEQUAL The minor identification of
the
user
shareable image section must be less than or equal
to that of the installed shareable image section.
LEQUAL permits the creator of a shareable image to
update it (increasing the minor identification) and
install it, and yet avoid the need for programs
using that shareable image to be relinked.
(The
minor
identification
of that shareable image
section in programs that are linked to it will be
less than the minor identification of the updated
installed shareable image section.)
NEVER The linker is to assume that global sections
will never match (perhaps because the shareable
image will never be installed).
Therefore, the
linker will always create a private copy of this
shareable image in any image that links to it.
(This keyword overrides any stated or defaulted
NOCOPY keyword in the /SHAREABLE file qual~fier in
any subsequent link operation . that names this
shareable image as an input file.)
ALWAYS This keyword causes the image activator to
match image sections by name only and to ignore the
major and minor identifications.
(However, the
syntax of this option requires that you still enter
major and minor identifications.)
•

The major identification of the user shareable image
section, expressed as a number from 0 through 255.

•

The minor identification of the user shareable image
section, expressed as a number from 0 through 2**24-1.

The linker
option:

uses

the

following

defaults

for

the

GSMATCH=

GSMATCH=EQUAL,x,y
where "x" and "y" together are the middle 32 bits of th~
2-longword creation time that is stored in the shareable image
file header. This default value forces user images that are
linked to this (installed) shareable image to be relinked each
time the shareable image is updated.
To ensure that other
users will not have to relink images that are linked to your
shareable image whenever you modify it, specify the following
GSMATCH= value:
GSMATCH=LEQUAL,O,O
IOSEGMENT=n[, [NO]POBUFS]
IOSEGMENT= specifies the number of pages for the image I/O
segment, which holds the buffers and VAX-11 RMS control
information for all files that the image's process uses.
If
the process needs more space than the IOSEGMENT value during
execution, VAX-11 RMS adds space for it at the end of the
program (PO) region.
You can also specify POBUFS or NOPOBUFS as parameters.
POBUFS, which is the default, permits RMS to use the program
region
(PO) for any additional buffers that it
needs.
NOPOBUFS
denies RMS the option of using PO space for
additional buffers.

5-8

THE /OPTIONS FILE QUALIFIER
The default value for IOSEGMENT= is 32,POBUFS.
The only
reason to specify a number of pages greater than the default
is to guarantee that the program region will be contiguous if
you need to extend it and if the total size of your program's
buffers and VAX-11 RMS control information exceeds 32 pages.
In this case, you also need to specify NOPOBUFS.
ISD MAX=n
ISD MAX= is an option that gives you some control over the
linker's compression of uninitialized pages in an executable
image.
(For an explanation of compression, see the DZRO MIN=
option in this section.) The ISD MAX= value specifies the
maximum number of image sections allowed in the image. If the
linker is compressing the image by creating demand zero
sections and the total number of image sections reaches the
ISD_MAX= value, the compression ceases at that point.
The default value for ISD MAX= is approximately 96. Note that
any value you specify Ts also an approximation. The linker
determines an exact ISD MAX=
value
based
on
certain
characteristics
of
the- image, including the different
combinations of section attributes. The exact value, however,
will be equal to or slightly greater than what you specify;
it will never be less.
PROTECT=

{~~S}
PROTECT= controls whether clusters are protected. PROTECT=YES
specifies that all clusters defined (in a CLUSTER or COLLECT
option) between it and the next PROTECT= option are protected.
PROTECT=NO (default condition) specifies that all clusters
defined between it and the next PROTECT= option are not
protected.
Protected
clusters
are used 1n privileged
shareable images to execute privileged instructions. See the
VAX/VMS
Real-Time User's Guide for more information on
privileged shareable images.

PSECT_ATTR=psect-name,attribute[, ••• ]
PSECT ATTR= specifies one or more attributes of the named
program section.
This option is used to change the compiled
or assembled attributes of a program section.
You must use the abbreviation given in Section 6.2.3 for each
attribute.
If you do not list a complete set of attributes,
this option does not change any attributes that are not
listed. For example, the option
PSECT_ATTR=ALPHA,NOWRT
can .be used to make the program section ALPHA not writeable
instead of writeable; however, all other attributes of ALPHA
remain the same.
STACK=n
STACK= specifies the initial number of pages to be allocated
for the image's user mode stack area. If when the program is
executed it requires more stack space than was allocated, the
stack is automatically expanded.
The default value is 20.

5-9

THE /OPTIONS FILE QUALIFIER
SYMBOL=name,value
SYMBOL= defines "name" as an absolute global symbol with the
specified value. The value must be expressed as a number.
Because the linker processes special options before input file
specifications, the name and value specified by the SYMBOL=
option constitute the first definition of that symbol. If an
input object module also defines that symbol, one of the
following occurs:
•

If the object
module
defines
the
symbol
as
relocatable,
that definition is ignored and the
definition by the SYMBOL= option is used.
A warning
message is issued.

•

If the object module defines the symbol as absolute,
that definition is ignored and the definition by the
SYMBOL= option is used. No warning message is issued.

UNIVERSAL=symbol-name[, ••• ]
UNIVERSAL= identifies one or more global symbols of
a
shareable image as universal symbols. For a discussion of
universal symbols, see Section 2.2.3.

5-10

CHAPTER 6
IMAGE MAP

If you so request, the linker produces an image map containing
information about the contents of the image and about the linking
process itself.
To obtain a map, you must include the /MAP qualifier in the LINK
command.
You can specify a file name with the MAP qualifier, or you
can let the linker assign a default. You can further specify the type
of map with the /BRIEF or /FULL qualifier. If you enter either /MAP
alone or /MAP with /FULL, you can also include a symbol cross
reference in the map by specifying /CROSS REFERENCE. However, if you
enter /MAP and no other map-related qualifiers, the linker generates
its default map.
The map is placed on your output disk and assigned a default file type
of MAP. You can print a copy of the map with the PRINT command.
The following examples show the LINK command qualifiers
produce different types of maps:

Command Qualifiers

Type of Map Produced

$ LINK/MAP/BRIEF

Brief map

$ LINK/MAP

Default map

$ LINK/MAP/CROSS REFERENCE

Default map with symbol
cross reference

$ LINK/MAP/FULL

Full map

$ LINK/MAP/FULL/-

Full map with symbol
cross reference

CROSS REFERENCE

6.1

necessary

IMAGE MAP CONTENTS

A listing of the image map contains several sections;
however, the
number of sections and the contents of certain sections depend on the
qualifiers that you enter.
Table 6-1 lists all the possible section names in the order in which
they appear, the types of map in which each appears, and a brief
explanation of each section. A section shown as appearing in "all" is
included in all types of image maps; "default" and "full" identify
sections appearing in default and full maps, respectively.
A brief
map thus contains only the map sections designated as "all." For
detailed explanations and illustrations of map sections, see Section
6.2.

6-1

IMAGE MAP

Table n-1
Image Map Sections
Section Name

Appears In

Explanation

Object Module Synopsis

All

Object modules in the image

Image Section Synopsis

Full

Image sections and clusters

Program Section Synopsis

Default
Full

Program sections and
modular contributions

Symbols by Name
or
Symbol Cross Reference

Default
Full

Symbols
by
Name
lists
global symbol
names
and
values.
However, if you
specify
/CROSS REFERENCE,
Symbol
Cross - Reference
appears
instead, listing
symbol
names,
values,
defining
modules,
and
referring modules.

Symbols by Value

Full

Hexadecimal symbol values
and names of symbols with
those values

Image Synopsis

All

Statistics
information
output image

Link Run Statistics

All

Statistics about the link
run that created the image

'--------·-···-----~---~-------·· ---~

and
about

other
the

---··-·-·--·-········

The contents of the following sections vary depending on
map type is default or full:
•

Object Module Synopsis

•

Program Section Synopsis

•

Symbols by Name

•

Symbol Cross Reference

whether

The difference between these sections in a default map and in
map is in the number of items:
•

the

full

A default map generally includes only information that applies
to modules and shareable images that you name as input to the
linker or that are extracted from libraries you name.
A
default map normally does not list information that applies
only to modules taken from the default system library.

map includes information that applies to all modules
• Aandfullshareable
images, including those extracted from the
default system library.

n-2

IMAGE MAP
6.2

IMAGE MAP SECTIONS

The rest of this chapter explains and illustrates each available image
map section.
The sections are presented in the order in which they
appear in a full map. Brief and default maps do not have all of these
sections, but the sections that they do have are in the order
presented here.
The illustrations reflect an image created from a simple FORTRAN
program (similar to the example developed in the VAX/VMS Primer).
Each illustration is from a full map.
Headings and items in each
illustration are explained only if they are not self-explanatory.
Appendix B contains examples of the brief, default, and full forms
the image map.

6.2.1

Object Module Synopsis

The Object Module Synopsis lists object modules in the order in which
the linker processed them. This section appears in all types of maps.
The Object Module Synopsis provides the
each module listed:

following

information

•

Module name

•

Module identification as it appears in the module header

•

Module length in bytes

•

Complete file specification for the module

•

Module creation date

•

Language translator that created the module

about

The Object Module Synopsis also lists any errors that the linker
detected when it wrote the binary data and code--for example, a
warning message that a module refers to an undefined symbol.
The
message appears immediately below the line that indicates the module
that the linker was processing when the error occurred •.
Figure 6-1 illustrates the Object Module Synopsis section.

6.2.2

Image Section Synopsis

The Image Section Synopsis lists information about the image sections
in the order in which they are mapped in the image. The Image Section
Synopsis appears only in a full map.
The Image Section Synopsis lists the following information about
image section:
•

Cluster in which the sections were allocated or found

•

Code used internally by the linker

•

Number of pages

•

Base virtual address within the image

6-3

each

AVERAGE

I.INKER V02a40

22•FEB•1980 14114

+•······-········-·······+
1 ObJect Module
I
+··-·----·-··-············

P1;1

Sv~op111

Module Name

I dent

AVERAGE
OTSSLINKAGE
SYSVECTOR
VMSRTL

li'1

F11 e

Bvtea

C1"11tio,, Date
..............

--···
222 _oea21[GOLDMANJAVERAGE.08Jr1

22•Feb•l981 14115
1q•FEB•1980 21157
1q•FEB•l980 21159
20•FEB•l980 18155

3 .DRA51[SYSLIBJSTARL.ET.OLBs1

1•003

0219
.EXEJ1

0
~

.DRA5a[SYSLIBJSTARLET,OL~s1
.oRA5a[SYSLIBJV~SRTL.EXEr1

Figure 6-1

Cl"eatOI"

····-··

VAX•11 FORTRAN T1 1 95•3o
VAX•11 MICl'O V02,4l
VAX•11 MICl'O V02 1 41
LINt<•32 v02,n

Object Module Synopsis Section

.-t

O"I

Cl
tSl

I
~

.DBB2:(GOLDM.AN]AvcRAGE.EXE11

------Cluster

DEFAULT.CLUSTER

+-----------------------·+
1 Im1ge Section Svnoo1;1 I
+---·-----------····-···-+

Tvoe P1ge1
~

253

1
1
1
20

3
3

"'~0\.H~20~

0130000~0

7FFFD8011

30~1i'.'082i.'
l.'ltllli'01E0~

1q3
4

v.!001A"'et!rJ

G1ob11 Sec. N1rne

Baae Addr Disk VAN PFC Protection '"d P1g1no

ii'0000ae0

Id READ ONLY
:d RE40 WRITE.

~EAO

CO~Y

M1tcti

M1Jol'id

M1 l'IOl"i d

REF

ONl..Y

0 REAO wRITE

OE~4NO

ZERO
VMSATL..,.001

1 REAO ONLY

0 READ ONLY
~ REAO wRrTE

Figure 6-2

P1ge

L.INKER V02.40

........ ···--··
---·-------··-·· --·-·

--·- ----- --------- -------- --- --------------------·
ill
QI

VMSRTL

22•FEB•1960 14114

VMSRTl.. ...'1102

COPY ON REF

VMSRTL..,.2103 .

Image Section Synopsis Section

LESS/EWUAL.
1..ESS/EQUAL
LESS/EQUAL

2000

l
1

20d0
201H

.,,>

IMAGE MAP

•

Base virtual block number within the image file on disk
(zero
indicates that the image section is not in the image file)

•

Page Fault Cluster (PFC) (zero indicates that
management determines the value)

•

Protection characteristic ("read-only" or "read/write") and
paging
information
("copy on reference," "copy always"
(shareable images only), "demand zero," or blank for standard
handling)

•

Global section name if the cluster is a shareable image

•

Match control of global sections

•

Major and minor identification of global sections

VAX/VMS

memory

Figure 6-2 illustrates the Image Section Synopsis section.

6.2.3

Program Section Synopsis

The Program Section Synopsis lists information about program sections
(PSECTs), including relative addresses within the image and PSECT
attributes. This section appears in default and full maps.
The address information enables you to translate an address from a
program module listing into a virtual address in the image, and vice
versa. This ability can help you isolate errors or problems in the
image at run time--for example, by allowing you to relate an address
in an error message to a specific location within a specific module.
The attributes of each program section are also listed.
The linker
considers certain attributes when it groups PSECTs into image sections
(ISECTs). For further information on this process, see Section 7.7.
The Program Synopsis, illustrated in Figure 6-3,
information about each program section:
•

Program section name, in
addresses

•

Name of the module or modules that contribute binary
code to the program section

data

•

Base and ending virtual addresses,
module's contribution to the PSECT

each

•

Alignment for the start of each module that contributes to the
PSECT.
The number that follows the alignment description is
the power of 2 that expresses the length in bytes.
(For
example, 2 to the power of 2 equals 4, the number of bytes in
a longword.) The alignment column can contain these entries:
BYTE O WORD 1 LONG 2 QUAD 3 PAGE 9 -

order

lists the following

increasing

base

hexadecimal,

virtual

Byte alignment (1 byte)
Word alignment (2 bytes)
Longword alignment (4 bytes)
Quadword alignment (8 bytes)
Page alignment (512 bytes)

Most attributes are
of the PSECT.
• Attributes
contrasting
pairs.
Table
6-2
lists
the

parts of
attribute
abbreviations (in alphabetical order), their meanings, and any
attributes.
Section
7.5.4
explains
the
contrasting
attributes.
6-5

IMAGE MAP

Table 6-2
PSECT Attributes
Abbreviation

Meaning

Contrasts With

ABS

Absolute

REL

CON

Concatenated

OVR

EXE

Executable

NOEXE

GBL

Global

LCL

Local

GBL

LIB

Library (from
shareable image)

USR

NO EXE

Not executable

EXE

NOP IC

Not positionindependent code

PIC

NORD

Not readable

NOS HR

Not shareable

SHR

NOV EC

Not vectors for
privileged
shareable image

VEC

NOWRT

Not writeable

WRT

OVR

Overlaid

CON

PIC

Position-independent
code

NOP IC

Readable

NORD

REL

Relocatable

ABS

SHR

Shareable

NOS HR

USR

User

LIB

VEC

Vectors for
privileged
shareable image

NOV EC

WRT

Writeable

NOWRT

6-6

.oee21[GOLOMAN]AVEHAGE.EXEJ1

22•FE8•1980

+·····----·-······--·······+
l
Sy"oc1i1 l
+·······---··-------·······+
Pro;ra~

P1eet

P'la111e

----------

Module Name

····--·-···

Seet1o~

.E"d..

Lenot,,

Attribute•

Al igl'I

·---··

-·-··

·-······-·

00000200 00000233 0000003~ c
00000200 ~0000233 0000003U C

52.> LONG 2
52.l LONG 2

PIC1USR,CON,REL1LCL1

AVERAGE

00000400 0000040F 00000010 C
0~0004~F 00000010 (

10.) LONG 2
U.) LOi-.G 2

PIC1USR1CON,REL1LCL1NOSHR,NOEXE1

~0000400

~0000699 0000009A C
00000600 00000099 0000009A (

154.) LONG 2
154.) LONG 2

PIC1USR,CON,REL1LCL1

SHR,

EXE,

RD,NOWRT,NOVEC

AVERAGE

l.) LONG 2
3.) LONG 2

~HR,

EX~,

RO,NOWRl,NOVEC

0~00009C

c
c

PIC1USR,CON,REL1LCL1

OTSSLINl<AGE

00000800 00000800 00000000 (
00000800 00000800 00000000 (
00000800 00000800 00000000 (

0.> BYTE 0 NOPIC1USR,CON1REL1LCL1NOSHR,

RO,

0,) BYTE 0

EXE,

OTSSLINKlGE
SYSVECTOR

SCOOE
4

AVEFUGE

SPDATA

SLOCAL

Base
....

Page

LINKER 1/02.40

1~114

0e000b00

0TSSCODE

, BLA"'ll< ,

0000009C 00e0Ao9E 00000003
0000~09E 00000003

SHR, NOEXE.1

RO,NOlllRT,~OVEC

RO,

WRT,NOVEC

~RT,NOV~C
1-t

0,) BYTE 0

Figure 6-3

.....i

Program Section Synopsis Section

DBB21[GOLDMAN]AVEAAGE,EXEs1

22•,EB•19!B 14114

tllJ

LINK!R VH,41

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

P~ge

& Sv•bo11 By Neme &
•••••••••••••••••••

......
Sy111bo1

AVERAGE

.....
Velue

00Hl!IH0•R

......

.....
V•lue

Symbol

8ASSINPUT 4 LINE

.......
Sy11bo1

HH1180•AU

BASSSCALE•D•A 1

.....

~ynibo1

V~1Ut

llHUT&•RU

•
•

FOASio ...x.oA
FORSLINKAGE
FOR,OPEN

•
00000970•AU
00000o9C•R
00000978•RU

• 4 0UTPUT
LIBSPUT
LIBSREVERT
LIBSSCANC

•

01!1000D58•AU
H000D60•RU
00090068•AU

Figure 6-4

MTHIDUP•

MTHSDEXP ...R6
MTHIOfXP 4 R7

• •••••

f'OAISCB.POP

......
Yal ue

0HB0E10•RU

•

90H8A,8•RU

•

•
•
•
OTSHFREEN.,OD

H8H811J0•AU

OTSS5'REENgDDo

000HC28•AU
011leHC30•RU

HHIBH•RU

OTHSGETi. D

0HHC88•RU

•

Symbols by Name Section

•
•

.,,>'3

IMAGE MAP
6.2.4

Symbols By Name

The Symbols by Name section lists global symbols in alphabetical order
and gives the hexadecimal value of each one. The value may have one
of the following suffixes: -R for a relocatable symbol, -U for a
universal symbol, -RU for a relocatable universal symbol, -W for a
weak definition, or -* for an undefined symbol.
(The linker assigns a
value of zero to undefined global symbols.)
The Symbols by Name section appears only in a default or full map that
does not have a cross reference. If you include /CROSS REFERENCE in
the LINK command, the Symbols by Name section is replaced by the
Symbol Cross Reference section.
Figure 6-4 illustrates the Symbols by Name section.

6.2.5

Symbol Cross Reference

The Symbol Cross Reference section
lists
global
symbols
in
alphabetical order and gives the following information about each one:

•

Hexadecimal value • The value can have one of the following
suffixes:
-R for relocatable, -W for a weak definition, -*
for undefined, -u for universal, or RU for relocatable
universal.

•

Name of the first module that defines the symbol (blank if the
symbol is undefined).

•

Name of each module that refers to the symbol. The name has
the prefix WK- if the module makes a weak reference to the
symbol.

The Symbol Cross Reference section appears only in a default or full
map for which you specify /CROSS REFERENCE. It replaces the Symbols
by Name section.
A primary value of the Symbol Cross Reference section is that it shows

which modules are affected by each symbol. For example, if you want
to change a symbol definition, the Symbol Cross Reference section
tells you where it is defined and what other modules may be affected
by the change.
Figure 6-5 illustrates the Symbol Cross Reference section.

6.2.6

Symbols By Value

The Symbols by Value section lists the hexadecimal values of global
symbols in ascending numeric sequence, with the symbol or symbols that
correspond to each value.
The symbol name can have one of the
following prefixes: R- for relocatable, U- for universal, or RU- for
relocatable universal.
This section appears only in a full image map.
Figure 6-6 illustrates the Symbols by Value section.

6-8

22•,E8•1981 14114

.oee21[GOLOMAN]AVERAGE.EXErZ

·-···-····················
l
Cro11 Refere"c• &
+••··-······---·-·········

LINKER YIZ.40

Pa_ge

P•;e

sv~bo1

"•Cl By

Symbol

V•lue

Oeff

AVERAGE

li50000H0•R

AVERAGE

000008A8•RU

VMSRTL
VMSRTL
VMSRTI..
VMSRTl
VHSATL

•

l'ORSIO,.END
FORUO,.FC,.R
FORUO,.FC,.V
FORSIQ,.F .,R
FORSIO,.F .,'II

~0_,00940•RU

00000948•RU

.a00008B0•RU
00000888•RU

Refere"c•d By •••

---···--·------··
AVERAGE
AVERAGE

Figure 6-5

Symbol Cross Reference Section

....
O"I

.oee21CGOLOMAN]AVERAGE.EXEr1

22•1'EB•1980 14114

+•·········------··+
& Symbols Bv V•lue &
+••···--···········+

I
\0

Y•lue
00000600
00fill0069C

eeeeeeee
00000808

HllJ00810

0011100818

R•AVERAGE
R•BASSLlNKAGE
RU•FORSCLOSE
RU•l'ORSOECOOE.MF
RU•FORSOECODE.MO
RU•FORSENCODE.MF

R•OTSSLINl<AGE

Kev for 1pecie1 cher•cter1 ebove1

·······-············
I * • U"defi"ed

& U • U"tver1•1
&
& R • Re1oc•t•b1e &
' WK • Week

Cl
tWJ

Sy111bo11 •••
..........

R•FORSLINKAGE

LINKER VllS2.4B

••••••••••••••••••••
Figure 6-6

Symbols by Value Section

IMAGE MAP
6.2.7

Image Synopsis

The Image Synopsis, which appears in all maps, gives miscellaneous
information about the output image. The virtual memory allocation
lists (in hexadecimal radix) the image's starting address, ending
address, and total size in bytes and (in decimal radix) the total size
in bytes and pages. The other items are self-explanatory.
Numbers
are decimal if they are followed by a point (.); otherwise, they are
hexadecimal.
Figure 6-7 illustrates the Image Synopsis section.

6.2.8

Link Run Statistics

The Link Run Statistics section, which appears in all maps, gives
statistics of the link run that produced the image. The items are
self-explanatory.
Figure 6-8 illustrates the Link Run Statistics section.

6-10

.oee21CGOLDMANJAVERAGE.EXEs1

LINKER vez.u

22•,EB•1t81 14114

+·················
&
sv"oD1f1 &
···-··············

P1ae

I~•ae

0000~201

Vfrtue1 memory e11ocetedl
St•ck 1fze1
Im•ae heeder vfrtue1 b1ock 1fmft11
Im•ae bfn•rv vfrtu•l b1ock lfmft11
Imege "•me •"d fdentfftc•tfo"I
Number of ff1e11
~umber of moau1111
Number of proar•m 1ectf on11
~umber of globel 1vmbot11
~umber of •••ae 1ectfon11
User tr•"•fer eddre111
Oebuaaer tr•n1fer •ddre111
Im•a• tvP•I
Map format&
E1tim•t•d map lengths

1911A7FF 89B1A601 (108132. bvtel1 z11. P•ae1)
2111. o•a••
1. (
1. block)
1.
3. b1ock1)
2.
(
AVERAGE 01

"·

3.
4.
9.

271.

00000&00
8~0"'"1&8

EXECUTABLE.
Full fn ff le
58.

·~DBB21CGOLDM•NJAVERAGE.~•Ps1•

blOCICI

Figure 6-7

+···------------------+
I Lfnk Run St•t11ttc1 &
+---------------------·

"'
I

......
......

Image Synopsis Section

Perform•nce Indfc•tors

P•a• Feult1

Comm•nd oroce11tng1
Pe11 11
A11ocatfon/Relocetfons
P•11 21
M•D date after object module 1vnopst11
Symbol t•ble outout1
Totel run velue11
u1fng • worktno set

li~fted

15
3qc;

....
3

Gl
tllJ

CPU The

Ehp1ed Tfme

1110100100.05

BBIHIH.27
00100 UJ2 • 73

001HI01e17
001210100.2&

00100100.u

"1HH.a010111.25

00100111. 43

150
12
723

210100101.e11

121011110103.45

001tH510lll.01
00100101.&2

BIUH10a. u

to Z73 01oe1 •"d 48 oege1 of d•t• 1tor•ae CexcludfnQ

Bli'8 00 I 08 • 46
t~•ae)

Total "U~ber object record• re•d Cboth P•11e1)1
175
of w~tc~ b7 were f" 1t~r•rte1 •nd 4 were DEBUG d•t• record• cont•ini"Q 158 byte1
143 bvte1 of DEBUG det• were wrftte"••t•~tf"~ et VSN 5 with 1 block1 •11oc•t•d
Nu~ber of ~odul•• extr•cted exo1icftlv
wtt~ 2 extr•cted to re1olve u"deff"ed
~

• 0
1vmbol1

1fbr•rv •••rche1 were for 1vmbot1 "ot t" the

A tot•l of 0 g1ob•l

1v~bo1

t•ble

~•cord•

1fbr•~Y

1e•~ched

w•• written

/"AP/FULL AVERAGE

Figure 6-8

Link Run Statistics Section

.,,>

CHAPTER 7
IMAGE CREATION

This chapter discusses the allocation of virtual memory and the
different kinds of images that the linker can produce. The concepts
of program sections, image sections, and clusters are introduced,
along with a description of the way in which the linker builds the
final image.

7.1

PROGRAM SECTIONS

Program sections are areas of memory that have a name, a length, and a
series of attributes (detailed in Section 7.5.4) that describe the
intended or permitted usage of that portion of memory.
The program
section is the vehicle by which a language compiler describes the
memory requirements of a particular object module.

7.2

IMAGE SECTIONS

Image sections are named collections of pages; each page in an image
section has the same hardware protection characteristics and the same
sharing nature. The image sections describe the memory requirements
of the whole image to the VAX/VMS memory management software.
The linker creates image sections by collecting program sections that
have similar (but not necessarily identical) attributes. The mann~r
in which program sections are grouped into image sections depends upon
both the attributes of each program section and the type of image
being produced (see Section 7.7).

7.3

CLUSTERS

Clusters are collections of image sections. Clustering provides a way
for the designer of an application program to ensure that an imag~
section is near, in virtual memory, to the image sections that it
references and that reference it. Having related image sections near
each other improves the performance of large application programs.
An example of an application prog.ram that could use clustering is a
compiler. A compiler usually goes through a number of distinct phases
during a single compilation run. Each phase of the compiler could be
made into a separate cluster to improve the compiler's performance.
Every image consists of at least one cluster.
You can specify
additional clusters in two ways:
by object modules or by program
sections. The CLUSTER= option (see Section 5.3) causes image sections

7-1

IMAGE CREATION

created from the specified object modules to be in the same cluster.
The COLLECT= option (see Section 5.3) causes image sections created
from the specified program sections to be in the same cluster. In
both cases, the image sections are put in the cluster in the order
described in Section 7.7.
Note that clusters are relevant only to the linker itself;
they do
not appear as a structure to anything else (such as to the VAX-11
memory management software). See Section 7.9 for more information.

7.4

OBJECT MODULE CONTENTS

Each object module contains several types of records.
All object
modules have header records and an end-of-module record. Some also
have other kinds of records, depending on the options specified at
compilation.
All object modules also contain the following records
for each of the program sections:
•

A global symbol record that includes the program section's
attributes.
(A global symbol record is also used to describe
each global symbol defined in the module.)

text information and relocation record, containing the
• Asection's
binary data or code and certain commands to the
linker.
Appendix C contains a detailed specification of
accepted by the linker.

7.5

the

object

language

PROGRAM SECTIONS

A program section is defined to the linker by the following:
•

A name

•

A size

•

An alignment

•

A series of single-bit
program section is:

attributes

expressing

whether

the

Relocatable or absolute
Concatenated or overlaid
Local to a cluster or global across all clusters
Executable or not
Writeable or not
Readable or not
Position-independent or not
Potentially shareable or not
Created by a user program or by the linker for internal use
Has protected vectors or not
7-2

IMAGE CREATION
7.5.1

Program Section Name

The program section name is an ASCII character string, 1 through 31
characters in length.
You can use any printable ASCII character in
the name, but are cautioned against using the dollar sign ($), to
avoid possible naming conflicts with software supplied by DIGITAL.
Program sections with the same name but from different modules
normally must have the same attributes. Any exceptions to this rule
are noted in the discussions of specific attributes.

7.5.2

Program Section Size

The size field of a program section definition record is a 32-bit
count of the number of bytes that this module contributes to the
program section.

7.5.3

Program Section Alignment

The alignment field describes the address boundary at which the
module's contribution to the program section will be placed. The
alignment is expressed as a number from O through 9, representing a
power of 2. The base address of the program section is rounded up to
a multiple of that power of two.
In an overlaid program section, all contributing modules must specify
the same alignment;
otherwise, the linker generates a diagnostic
error. In a concatenated program section, each contributing module
can specify a different alignment.
The total allocation of the
concatenated program section is aligned on a boundary which is a
multiple
of the highest power of 2 specified by any of the
contributing modules.

7.5.4

Program Section Attributes

The following subsections explain the attributes that a program
section can havea
Section 7.7 describes how the linker considers
certain significant attributes as it constructs different types of
images. Section 5.3 describes the PSECT ATTR option, which allows you
to change the attributes of a program section.

7.5.4.1 Relocatability (REL and ABS) - A program section can be
relocatable or absolute.
A relocatable program section is one that
the linker can position in virtual memory according to the memory
allocation strategy for the type of image being produced.
Absolute program sections, on the other hand, are not considered in
the allocation of virtual memory.
They contain no binary data or
code, and all appear as if they were based at a virtual address of
zero.
Absolute program sections are used primarily to define global
symbols.

7-3

IMAGE CREATION
7.5.4.2 Concatenated versus Overlaid (CON and OVR) - This attribute
determines the relationship between the memory allocations when
several modules contribute program sections with the same name.
A concatenated program section contribution requires separate address
space in the image. If two program sections from different modules
have the same name, the sections will be placed in separate but
contiguous address spaces.
For example, if PSECTA in MODULE! and
PSECTA in MODULE2 have the concatenated attribute, the allocation of
PSECTA from MODULE! will be followed by the allocation of PSECTA from
MODULE2. The total size of a concatenated program section is the sum
of the individual contributions and any padding allowed for the
individual alignments.
An overlaid program section contribution, however, can share an
address space with other program sections that have the same name.
For example, if PSECTA in MODULE! and PSECTA in MODULE2 each have the
overlaid
attribute, both program section contributions will be
allocated starting at the same base address in the image.
The total
size
of
an overlaid program section is that of the largest
contribution.
Note that any module can initialize the contents of an overlaid
program section. Because of this, the order in which you specify the
input modules is important:
the contents of an overlaid program
section are determined by the last contributing module specified.
BASIC and FORTRAN common areas are the most frequently
program sections.

used

overlaid

7.5.4.3 Scope - Local versus Global (LCL and GBL) - The local or
global attribute is significant for an image that has more than one
cluster. The attribute determines whether program sections with the
same name but from modules in different clusters are finally placed in
separate clusters (LCL attribute) or in the same cluster (GBL
attribute).
The memory of a global program section is allocated in
the cluster that contains the first contributing module.
BASIC and FORTRAN common areas are
sections.

implemented

with

global

program

7.5.4.4 Executability (EXE and NOEXE) - Although the current VAX-11
hardware does not implement any kind of execute protection, this
attribute is reserved for possible future implementation.
This
attribute also permits possible future extension of link time error
detection and of software security protection.
The current version of the linker takes this attribute into account in
only two ways:
•

Error-checking on an image start address. The linker issues a
diagnostic message if a program transfer address is defined in
a nonexecutable program section.

•

Sorting of program sections into image sections.
Executable
program sections in executable and shareable images are placed
in image sections separate from program sections that are not
executable.

7-4

IMAGE CREATION
7.5.4.5 Writeability (WRT and NOWRT) - This attribute determines
whether the program section contents will be protected against
modification when the image is executed.
If the program attempts to
modify
the contents of a non-writeable program section during
execution, an access violation occurs.
For executable and shareable images, writeable and nonwriteable
program sections are placed in different image sections.
For system
images, this attribute is ignored, since by definition the VAX/VMS
system is not normally in control of the memory management of a system
image.

7.5.4.6 Readability (RD and NORD) - The current version of the linker
ignores this attribute.
It is provided merely to allow the possible.
future implementation of a data security system.

7.5.4.7 Position Independence
(PIC and
NOPIC) - This
attribute
identifies whether the content of a program section depends on where
that program section or something that it refers to is allocated in
the virtual address space.
For example,
the following types of
program sections are position independent:
•

A program section that contains no virtual addresses

•

A program section whose references to virtual memory are in
the form of a displacement from itself, if the targets of the
references must always be at the same displacement from the
calls which refer to them

This attribute applies only to shareable images, which
in Chapter 8.

are

discussed

7.5.4.8 Shareability (SHR and NOSHR) - As its name suggests,
this
attribute is significant only for shareable image memory allocation
and memory management (see Chapter 8).

7.5.4.9 User versus Library
(USR and LIB) - This attribute
is
reserved for possible future enhancements to the linker.
It is
ignored for the current release but should be set to USR to guarantee
future compatibility.

7.5.4.10 Protection (VEC and NOVEC) - The VEC attribute specifies
that the program section contains privileged change mode vectors.
Program sections with the VEC attribute are automatically protected in
shareable images. See the description of privileged shareable images
in the VAX/VMS Real-Time User's Guide for more information.

7.6

TYPES OF IMAGES

The linker creates three types of images:
executable, shareable, and
system.
Each
type
has specific uses.
System images differ
substantially in content and organization from executable images and
shareable images. The following subsections define each type.
7-5

IMAGE CREATION
7.6.1

Executable Images

An executable image is a program that you can activate by the RUN
command.
The most common use of the linker is to create executable
images.
An executable image cannot be linked with other images. However, the
object modules that make up one executable image can be linked in
different combinations or with different link options to
form
different executable images.

7.6.2

Shareable Images

There are two major reasons for shareable images:
•

To provide a means of sharing a single physical copy of a set
of
procedures
and/or data between multiple application
programs

•

To facilitate the linking of very large applications
hundreds of modules) in manageable segments

(say,

As with executable images, when the link of a shareable image is
complete, all symbolic references are resolved and memory is allocated
to a group of image sections. A description of each image section is
written to the image header. Unlike an executable image, however, a
shareable image normally has a symbol table appended to it.
A shareable image is not directly runnable.
It is intended for
reprocessing by the linker--that is, to be included in a subsequent
image. In processing a shareable image, the linker reads the image
header and generates a separate image cluster from the set of image
sections it finds.
After generating the cluster that is the incoming shareable image, the
linker processes the symbol table appended to the image just as if it
were an object module. This allows the shareable image to resolve
symbols (usually routine names) referred to by the modules with which
it is being linked. These symbols are called universal symbols (see
Section 2.2.3).
When you run a program that has been linked with a shareable image,
the VAX-11 image activator checks to see if the shareable image has
been installed by the system manager. If it has been installed, the
image activator sets a pointer that enables the process to use the
shareable image.
Thus, whenever multiple processes request
an
installed shareable image, the operating system makes the same
physical copy of the shareable image available to each requesting
process.
Shareable images can therefore conserve physical memory at
run time. If the shareable image has not been installed, the image
activator creates a private copy of the shareable image.
Chapter 8 discusses shareable images further. At this point, however,
note the following information and conventions pertaining to shareable
images:
•

The default common Run-Time Procedure Library
the VAX/VMS system is a shareable image.

•

You cannot link the VAX-11 Symbolic Debugger with a
image.

7-h

provided

with

shareable

IMAGE CREATION
•

You can request that the linker produce a private copy of a
shareable image in an executable image file. By default,
however, the linker does not do so, thereby saving disk space.

•

Chapters 4 and 5 describe LINK command qualifiers and link
time options specifically intended for dealing with shareable
images. See the following:
/SYSSHR

qualifiers

/SHAREABLE
UNIVERSAL=!

options

GSMATCH=

7.6.3

System Images

A system image is intended for stand-alone operation on the VAX-11
hardware;
that is, it does not run under the control of the VAX/VMS
operating system.
The allocation of memory to a system image is much simpler than for
the other two types of images. The linker allocates memory to the
program sections based on the alphabetical order of the program
section names.
The only other factors that the linker considers are
program section size, alignment, and the following
attributes:
concatenated or overlaid, and relocatable or absolute. These factors
are treated as described in Section 7.5.
The resulting image is a fixed-length record file, each record being a
512-byte block.
A system image has no image header (unless the
/HEADER qualifier is specified), no debug data, and no symbol tables.
It has no set format. That is to say, it contains binary data and
code just as they would appear in memory.

7.7

GENERATION OF IMAGE SECTIONS

The linker makes two passes over the input object modules. The first
pass builds the symbol table and the program section tables. The
second pass writes the binary contents of the image.
Memory
allocation is performed between the two passes; the linker uses the
program section table of each cluster and generates an image section
table for each cluster.
When the first pass is complete, the linker has determined the sizes
of all the relocatable program sections by considering specific
attributes and the alignment, as discussed in Section 7.5. The linker
has also determined relative addresses of each module's contribution
to a particular program section. What remains to be done is to group
the program sections into image sections, and to position the whole
image cluster in the virtual address space.

7-7

IMAGE CREATION
Depending on the type of image being produced, the linker establishes
a mask for the program section attributes that it will consider:
•

For an executable image, this mask includes
only
the
writeability (WRT and NOWRT), executability (EXE and NOEXE),
and protected vector (VEC and NOVEC) attributes.

•

For a shareable image, this mask includes the writeability,
executability,
position
independence
(PIC
and NOPIC),
shareability (SHR and NOSHR), and protected vector (VEC and
NOVEC) attributes.

For each possible combination of the significant attributes, the
linker searches the program section list of a cluster. If the linker
finds any program section with this combination of attributes, it
generates an image section.
Each program section with matching
attributes in the image section is assigned an address relative to the
base of the image section, in alphabetical order by program section
name.
All combinations of significant attributes are handled in this way,
until the complete set of image sections for the particular cluster is
generated. Table 7-1 lists the order that the linker stores the image
sections within a cluster.
Each line of the table specifies a
possible combination of significant attributes. The next cluster (if
there is one) is then treated in the same way.
At this point in image
creation,
all
image
sections
have
cluster-relative base addresses, and all program sections have image
section-relative addresses. The next step consists of allocating
virtual address space to the cluster and then relocating all image
sections and program sections within the cluster.
The choice of address space for the cluster depends on whether you
specified an address in the CLUSTER= option, and whether the cluster
contains a shareable image. It also depends on the order in which you
specified the clusters.

7.8

COMPRESSION OF UNINITIALIZED IMAGE SECTIONS

At the end of its first pass across the object modules, the linker
sorts all the program sections into a group of distinct image
sections. The sorting is determined by program section attributes and
results in the complete allocation of the user virtual space.
In its second pass, the linker writes the binary contents of the
image.
During this image initialization, the linker keeps track of
the program section being initialized and the image section to which
it has been allocated.
The first attempt to initialize part of an
image section causes the linker to allocate a buffer in its own
program region to contain the binary contents of the generated image
section. This allocation is achieved by the expand region system
service, and it requires that the linker have available a virtually
contiguous region of its own memory at least as large as the image
section being initialized.
After completing the second pass across the object modules, the linker
scans
the
list of image sections in an attempt to compress
uninitialized pages from the image, which is about to be written. The
linker attempts to perform this compression by creating demand zero
image sections. The linker scans the image sections and attempts to
compress uninitialized pages when it is creating executable images
only.
7-8

IMAGE CREATION
Table 7-1
Order of Image Sections in Clusters
Type of Image

Image Section PSECT Attributes
~-··~--~----

·---------··-~----·-···-

Executable

NOWRT
WRT
NOWRT
WRT
NOWRT
WRT
NOWRT
WRT

NO EXE
NOEXE
EXE
EXE
NOEXE
NOEXE
EXE
EXE

NOV EC
NOV EC
NOV EC
NOV EC
VEC
VEC
VEC
VEC
------~-

Shareable

System

NOWRT
WRT
NOWRT
WRT

NOEXE
NO EXE
EXE
EXE

SHR
SHR
SHR
SHR

NOP IC
NOP IC
NOP IC
NOP IC

NOV EC
NOV EC
NOV EC
NOV EC

NOWRT
WRT
NOWRT
WRT

NOEXE
NO EXE
EXE
EXE

NOS HR
NOS HR
NOS HR
NOS HR

NOP IC
NOP IC
NOP IC
NOP IC

NOV EC
NOV EC
NOV EC
NOV EC

NOWRT
WRT
NOWRT
WRT

NOEXE
NO EXE
EXE
EXE

SHR
SHR
SHR
SHR

PIC
PIC
PIC
PIC

NOV EC
NOV EC
NOV EC
NOV EC

NOWRT
WRT
NOWRT
WRT

NOEXE
NO EXE
EXE
EXE

NOS HR
NOS HR
NOS HR
NOS HR

PIC
PIC
PIC
PIC

NOV EC
NOV EC
NOV EC
NOV EC

NOWRT
WRT
NOWRT
WRT

NOEXE
NO EXE
EXE
EXE

SHR
SHR
SHR
SHR

NOP IC
NOP IC
NOP IC
NOP IC

VEC
VEC
VEC
VEC

NOWRT
WRT
NOWRT
WRT

NOEXE
NOEXE
EXE
EXE

NOS HR
NOS HR
NOS HR
NOS HR

NOP IC
NOP IC
NOP IC
NOP IC

VEC
VEC
VEC
VEC

NOWRT
WRT
NOWRT
WRT

NO EXE
NO EXE
EXE
EXE

SHR
SHR
SHR
SHR

PIC
PIC
PIC
PIC

VEC
VEC
VEC
VEC

NOWRT
WRT
NOWRT
WRT

NO EXE
NOEXE
EXE
EXE

NOS HR
NOS HR
NOS HR
NOS HR

PIC
PIC
PIC
PIC

VEC
VEC
VEC
VEC

-----

(only one image section)
····~~-~--

7-9

IMAGE CREATION
If the linker finds an image section that does not have a buffer
allocated, it considers splitting the section into multiple image
sections, some demand zero and others copy on reference.
To be
eligible for splitting, the image section must be writeable to the
user and larger than the minimum compression threshold size (see the
DZRO_MIN= option in Chapter 5). If the image section can be split,
the linker calls a memory management system service, passing it a
description of the image section buffer and the compression threshold
value. By calling this service in a loop, the linker finds out which
segments of the buffer are both larger than the threshold number of
pages and previously unmodified by the linker. This process results
in the replacement of a single image section by a potentially large
number of alternating demand zero and copy on reference image
sections.
The linker continues the splitting process, scanning the list of image
sections until it reaches the end or until the total number of image
sections reaches the limit specified or defaulted for the ISO MAX=
option (see Chapter 5). During the entire process, the linker keeps
track of the size of the image header (where descriptors of the image
sections will be written) and of the image binary contents. Thus, at
the end of the scan the linker knows the precise size of the image
header and the contents, and it can then create the image file.
When the image file is successfully created, the linker makes another
scan of the image section descriptor list. During this scan it writes
the contents of all existing image section buffers to the image file,
assigning them virtual block numbers as it does so. Finally, the
linker writes the image header, starting at virtual block number 1 of
the image file.
By

default,

the linker creates the image with
the
attribute
best try," which becomes a permanent attribute of the
image file. However, you can specify the /CONTIGUOUS qualifier to
force the image file to be created contiguously (see Chapter 4).
"contiguo~s

7.9

MECHANICS OF CLUSTERING

Section 5.3 describes the CLUSTER= and COLLECT= options, which are
used to define the position, character, and content of clusters. The
cluster name is merely for convenience in reading the Image Section
Synopsis of the image map.
Every image produced by the linker is automatically given a default
cluster.
This cluster contains any object modules not explicitly
positioned in other clusters. The BASE= option serves to position the
default cluster in the address space.
A shareable image is treated as a cluster.
If the image is not
position independent (NOPIC), it has a base address already assigned
and is treated in the same manner as a user-specified cluster that has
a base address.

7-10

IMAGE CREATION
The linker allocates
following order:

virtual

address

space

for

clusters

the

•

Clusters that have fixed bases (including position-dependent
shareable images).
If any of these clusters overlap, the
linker displays an error message.

•

User-specified clusters without
allocated in the order specified.

These

are

•

Default cluster (if it contains any modules and does not
a fixed base)

have

•

Position-independent shareable images

•

Run-time library shareable image (if it
image)

fixed

bases.

included

the

Clustering is not likely to have any performance advantage for
applications smaller than 200K bytes. The reason is that each cluster
contains a group of image sections, and thus the address space is more
fragmented than it would be without clustering. Fragmentation can
reduce program performance under certain circumstances.

7-11

CHAPTER 8
SHAREABLE IMAGES

This chapter describes in detail the nature and use of shareable
images. The material in this chapter is more complex than much of the
earlier material. Therefore, you are presumed to be familiar with the
earlier chapters of this manual, particularly Chapter 7.

8.1

SHAREABLE IMAGES:

BENEFITS AND USES

The following subsections expand on the discussion in Section 7.n of
the benefits you can obtain from the use of shareable images. These
subsections also discuss the conceptual nature of shareable images.

8.1.1

Conserving Physical Memory

Main physical memory is one of the prime resources that any operating
system has to control. The installation of shareable images produces
a set of global sections of memory -- one for each image section built
in the shareable image. These global sections are the mechanism by
which sharing is realized, for they can be mapped into the address
space of many processes. The fact that the same physical pages of a
global section are mapped into many processes means that
the
requirements for physical memory are reduced.

8.1.2

Conserving Disk Storage Space

All programs executed under the VAX/VMS system must be disk resident.
The use of shareable images, however, provides a way of reducing the
amount of disk space required.
When a shareable image is linked into an executable image, it is not
necessary to copy the physical contents of the shareable image. The
installation of a shareable image causes the location of that image on
disk to be recorded in the system's global section data base. The
subsequent running of a program that uses that shareable image causes
the VAX/VMS memory management software to load the copy from the
separate shareable image file. Thus, many programs can reside on disk
and be bound with a particular shareable image, and only one physical
copy of that shareable image file need exist on disk.

8-1

SHAREABLE IMAGES
8.1.3

Reducing Paging I/O

Paging occurs when a process attempts to access a virtual address
which is not in the process working set. When the fault occurs, the
page either is in a disk file (in which case paging I/O is required)
or is already in physical memory. One of the reasons a page can be
resident when a fault occurs is that it is a shared page, already
faulted by some other process which is sharing it. In this case, no
I/O operation is required before mapping the page into the working
sets of subsequent processes.
Thus, if many processes are using a
shareable image, it is very likely that its pages are already
physically resident.

8.1.4

Using Shared Memory-Resident Data Bases

There are many applications, particularly in data acquisition and
control systems, in which response times are so critical that control
variables and data readings must remain in main memory.
Frequently,
many programs must make use of this data.
Shareable images help to simplify the implementation
of
such
applications. The shared data base may be a named FORTRAN common area
built into a shareable image. The shareable image may also include
routines to synchronize access to such data. When programs of the
application bind with the shareable image, they have easy access to
the data (and routines) at the FORTRAN level.
It is possible, moreover, for such data bases to contain initial
values, and for the most recent values to be written back to disk on
system shutdown or at regular intervals.
Recording the values at
regular intervals makes it possible for a system restart to use the
most recent values of the variables of an online process.

8.1.5

Making Software Updates Compatible

A major problem in maintaining a large software installation is how to
incorporate a new version of a piece of software in all programs that
use it. Packaging software facilities as shareable images can help
alleviate the problem.
By
carefully
organizing
a
shareable
image
and
by
using
position-independent coding techniques, you can make significarit
changes and enhancements to the content of the shareable image and yet
eliminate the need to relink all the images bound with it.

8.2

WRITING SOURCE PROGRAMS FOR SHAREABLE IMAGES

In order to obtain all the benefits of a shareable image, you must
observe certain conventions in the source programs used to create it.
This section describes these conventions.

8-2

SHAREABLE IMAGES
8.2.1

Shareable and Nonshareable Data

The sharing of routines between two or more processes must address the
issue of whether each process has access to data that one or more
other processes are using. Sometimes this sharing is a requirement,
as in the case of industrial data acquisition applications. However,
if a piece of data used by a routine is, for instance, a loop counter,
each process must have a separate counter, or the routine cannot be
shared simultaneously. It is for this situation that the shareable
(SHR) attribute of program sections was introduced. Users familiar
with this situation recognize it as part of the problem referred to as
reentrancy.
As was mentioned in Chapter 7, the linker allocates program sections
with the SHR attribute in image sections separate from program
sections with the NOSHR attribute. The image activator also treats
image sections containing SHR program sections differently from image
sections containing NOSHR program sections. The linker indicates this
difference by an image section attribute called "copy on reference" in
the case of writeable NOSHR program sections.
(If the program section
is not writeable, all processes can use the same copy regardless of
SHR/NOSHR, since no form of data privacy or security is currently
implemented.)
Thus, a copy on reference image section is one whose initial contents
are established from the copy contained in the shareable image file,
but which from then on during program execution is treated just like a
user private image section.
For each user, completely separate
physical copies are produced for the copy on reference image sections
contained in shareable images, and the system paging file is used to
contain the pages of such sections when they are removed from the
working set.
On the other hand, if an image section is not copy on reference, each
user has access to the same physical copy of its pages. In addition,
when a page of such an image is removed from all user working sets, it
is eventually written back into the shareable image file on disk.
This last aspect makes it possible to rerun such applications as data
acquisition or transaction processing with the most recent values of
shareable, modifiable data.
Note that the cooperating user programs in applications like these are
responsible for synchronizing access to such data. Note further that
should it be necessary to revert to the initial values of the data,
you must have made a separate copy before running the application the
first time.
The FORTRAN example in Section 8.4.2 shows both kinds of data:
variables generated by the compiler and the program are in copy on
reference image sections, whereas the common areas are in shared data
regions.

8.2.2

Position Independence

A position independent piece of code will execute correctly no matter
where it is placed in the virtual address space after it is linked.
That is, it can execute at an address different from the one at which
the linker placed it. This section deals with position independence
only as it concerns shareable images.

8-3

SHAREABLE IMAGES

A shareable image is position independent
conditions are true:

all

the

following

•

The only addresses that appear in the image are known to be
fixed in the virtual address space (for example, the system
service vectors of VAX/VMS).
Note that if you specify a
relocatable address in a shareable image, the linker will
maintain the position independence by deferred relocation of
the address.

•

All instruction stream references to such addresses use
absolute addressing mode (autoincrement deferred off the PC).

•

All data references to such
complete virtual address.

•

All references to any other location are relative to some base
that is added to the address computation at execution time.
For example, in the instruction stream, PC re la ti ve (or
displacement from the PC) addressing mode would be used.

•

There is no possibility that, after linking, the relationship
between the target of a reference and the base to which it was
made relative can be changed.

fixed

addresses

contain

the

The current version of the linker is unable to verify that all the
above conditions have been met. Therefore, the following strategy has
been adopted:
the

resultant

•

If any base address has been specified,
shareable image is not position independent.

•

The state of the position-independence attribute of the
program sections is left to the user, and is considered only
in gathering program sections into image sections.
That is,
the linker simply places PIC program sections in image
sections separate from NOPIC program sections.

•

With assistance from the compiler or assembler, the linker
produces position-independent instruction stream references.
(Refer to the discussi©n of the general addressing mode in the
VAX-11 MACR.() Language Refe~en_s=.e.~al!~-~·) Basically, this means
that the linker will choose the addressing mode
(if so
directed) based on the relocatability of the target of the
reference.

assistance from the compiler or assembler, the linker
• With
address data by means of
produces
position-independent
deferred relocation.
•

A shareable image that is not position independent is place·d
at its link-time base address when it is subsequently bound
into a user image.

•

A shareable image that is position independent is allocated
after user-defined clusters when it is subsequently bound into
a user image.

•

Shareable images that are not
considered first by the linker.

position

independent

are

Def erred relocation is the relocation of address data that is deferred
until the executable image is linked from the shareable image. The
linker uses deferred relocation when an image section contains a

8-4

SHAREABLE IMAGES

.ADDRESS directive (VAX-11 MACRO) specifying a relocatable address.
The linker marks the image section as COPY ALWAYS. When an executable
image is linked from the shareable image, the linker copies the image
section into the executable image and then calculates the correct
address.
Note that to retain the benefits of a shareable image, .ADDRESS with a
relocatable address should only occur in an image section that
contains nonshareable data. These are the image sections that have
the NOSHR and WRT attributes.
If shareable images are to be most useful among many processes, they
should be position independent.
The VAX-11 instruction set and
addressing modes lend themselves to
convenient
generation
of
position-independent code.
All the code generated by the VAX-11
FORTRAN and VAX-11 BASIC compilers is position independent.

Transfer Vectors

8.2.3

In its simplest form, a transfer vector is a labeled virtual memory
location that contains an address of, or a displacement to, a second
location in virtual memory. The second location is the start of the
instruction stream of interest. In the use of shareable images under
VAX/VMS, transfer vectors are normally displacements rather than
virtual addresses, for reasons of position independence.
There are two main reasons for transfer vectors in shareable images:
•

They make it easy to modify and enhance the
shareable image.

•

They allow you to avoid relinking
bound to the shareable image.

other

contents
programs

the

that

are

In Figure 8-1, the two routines A and B are bound into a shareable
image, which is then bound into a user program. No transfer vectors
are used. The user program calls both A and B.
Thus, the user
program contains a representation of the addresses of both A and B.

-Routine A
is expanded

t---------- -- 1
New position
of Routine B
for larger A

Routine B

1---------New Expansion Area

User Program

Routine A

{

Expansion Area
Shareable Image

Figure 8-1

No Transfer Vectors

8-5

..
...

CALL

SHAREABLE IMAGES
Using the example in Figure 8-1, assume that it becomes necessary to
add more code to routine A. When the shareable image is relinked,
routine A will have the same address but because routine A has
increased
in
size,
routine
B
must
be
given
a "higher"
address -- higher by the amount of code added to A.
If the user
program is not relinked, it can successfully call A, since its address
has not changed. However, the call to B would result in a transfer of
control to the old address of B (which is now somewhere in the
enlarged routine A), and the desired result would not occur.
Note
that if the total size of the shareable image is larger, the user
program must be relinked.
(See Section 8.2.4).
In Figure 8-2, the same routines are built into a shareable image, but
this time with transfer vectors at the beginning.

Transfer Vectors

1-----

BRW

A-X

BRW

- - --

B-Y

User Program

..
CALL
... B
CALL

Routine

..--1

Routine

The transf.er vector contains
a branch instruction which
uses a displacement from
vector address to actual
routine.
The user program actually
calls the appropriate vector
instruction.

Expansion Area
Shareable Image

Figure 8-2

Transfer Vectors

In Figure 8-2, if routine A is expanded and the shareable image is
relinked, the contents of the vector will change with no adverse
affect on the user program. This is true so long as the user program
calls the appropriate vector and the vector addresses do not change.
The use of transfer vectors also allows you to add new routines t6 a
shareable image without needing to relink programs that use existing
routines. If a third routine (C) were added, it would be desirable
not to have to relink a user program that used only A and B. Without
a vector, you would need to link the three routines in the address
sequence A,B,C; -- otherwise A or B could b~ in a different place and
all user programs linked to the shareable image would need to be
relinked.
If you use a transfer vector, however, you can allocate a
new vector location to C (after those for A and B). You can then link
the three routines in any order.
Although you cannot create transfer vectors with FORTRAN, you can do
so easily with VAX-11 MACRO. However, before you can create transfer
vectors, you must define or permit the compiler to define entry
points.
With FORTRAN, the definition of entry points is done
automatically, but with VAX-11 MACRO, you must explicitly define them.
As an illustration, assume in Figure 8-2 that routines A and B are

8-6

SHAREABLE IMAGES
written in FORTRAN. In this case, the two global symbols A and B are
defined as entry points, and the definitions given to the linker
include a description of the registers to be saved with the call
instruction.
(You can achieve the same effect with the MACRO
directive .ENTRY. See the VAX-11 MACRO Language Reference Manual.)
To create the transfer vector, you must use the VAX-11 MACRO assembler
language. Consider the following fragment of MACRO code:
.TRANSFER
.MASK
BRW

A
A
A+2

;Begin transfer vector to A
;Store register save mask
;BR to routine, beyond the
register save mask

As the example suggests, register save masks (required at the target
of a CALL instruction) occupy two bytes of memory. Thus, since it is
the vector that you actually call, the register save mask is stored in
the vector.
The .MASK directive in the above example allocates the
two bytes and directs the linker to (1) find the register save mask
accompanying symbol A, and (2) write the word as the first two bytes
of the vector. This mask is followed by a branch instruction that
transfers control to routine A, at the instruction beyond the entry
mask.
(This example assumes that A is within 32K bytes of the vector;
otherwise a JMP instruction would be required.)
The .TRANSFER directive has two purposes:
•

It is an implicit universal declaration of symbol A if you are
building a shareable image.

•

It causes the linker to assign the universal symbol A the
address of the vector, rather than the address of the routine
within the image. This occurs after all uses of A within the
shareable image have been given the value within the image.

Thus, all entry points of a shareable image are universal when
vectored in this way. The user program outside the shareable image
can call the routine A in the same way as it would an ordinary object
module.

8.2.4

Rules for Creating Upwardly Compatible Shareable Images

To be able to make changes to shareable images and not have to relink
users of that shareable image, you must observe the following rules:
•

Transfer vectors must not be rearranged or removed.

•

The new shareable image must have exactly the same
image sections.

•

The shareable image must not be larger than it originally was
unless the shareable image is the cluster with the largest
virtual address in the image (this position is usually
reserved for the run-time library).

number

While a shareable image is being developed, it is useful to reserve
expansion space to allow the image to grow.
If you exceed the
expansion space, you must relink all executable images that are linked
with the shareable image. Because there is a substantial overhead for
increasing the size of a shareable image (one entry in the system's
Global Page Table per shareable page), you should reduce the expansion
area when the shareable image is no longer being developed.

8-7

SHAREABLE IMAGES
8.3

LINK COMMAND AND PERTINENT OPTIONS

The LINK command for creating a shareable image is similar to that for
any
other
type
of
image,
except
that
you must use the
/SHAREABLE[=file-spec] qualifier, which is described in Chapter 4.
The UNIVERSAL=, GSMATCH=, and PROTECT= options and the /PROTECT
qualifier are provided specifically to control characteristics of
shareable images. Chapter 5 describes the syntax of these options.
Sections 8.3.1, 8.3.2, and 8.3.3 describe their purpose.

8.3.l

UNIVERSAL= Option

Universal symbols are the global symbols of a shareable image which
are of use to the programs that subsequently link with the shareable
image. It is possible for none or all of the global symbols of a
shareable image to be universal symbols. Typically, however, a very
small set of the global symbols of the image are universal because few
of them are of use outside the shareable image. Universal symbols are
the only symbols written to the symbol table of a shareable image.
Most programming languages provide no way of characterizing a symbol
as universal.
(VAX-11 MACRO, however, has a declaration for creating
transfer vectors. See Section 8.2.3.) Thus, to tell the linker which
symbols are to be universal, the option UNIVERSAL= is provided.
Normally, all the entry points (routine names) provided in a shareable
image are universal symbols. Sometimes, however, other constants are
of interest to users of the facility, and these can also be declared
as universal symbols. Section 8.4.l contains an example showing the
declaration of several such constants in the Cross Reference Facility
as universal symbols.

8.3.2

GSMATCH= Option

When a shareable image is bound into a user executable image, its
image sections are promoted to global sections.
(The VAX/VMS system
promotes image sections to global sections when a shareable image is
installed.) When an executable image is run, the image activator
checks to see if the shareable image that the executable image was
linked with matches the current one. The image activator compares the
values specified in the GSMATCH= option when the shareable images were
linked (see Section 5.3).
The GSMATCH= option sets the matching requirements for versions of the
shareable image and causes a two-part identification field to be
associated with the global section name.
During the search for a
global section at image activation time, the global section name and
the major part of the identification must match exactly. The behavior
of the comparison with the minor part of the identification is
determined by the keyword specified in the GSMATCH= option.
The
keyword can be:
•

EQUAL -- the minor identifications must match.

•

LEQUAL -- the minor identification of the global section in
the user image must be less than or equal to that in the
global data base.

8-8

SHAREABLE IMAGES

•

NEVER -- even if both parts of the identification match
exactly, the image activator rejects the shareable image. The
purpose of NEVER is to specify that the linker should always
produce a private copy of this shareable image in each
executable image file.

•

ALWAYS -- the image activator only checks to see that the
global section names are the same and ignores both parts of
the identification.

The GSMATCH= option is provided to set these parameters when the
shareable image is being linked. See Section 8.5 for mre information
on the effects of these parameters.

8.3.3

PROTECT =Option and /PROTECT Qualifier

The PROTECT= option and the /PROTECT command qualifier are used to
create privileged shareable images. A privileged shareable image can
execute change mode to kernel and execute change mode to executive
instructions even when it is linked with a nonprivileged executable
image. A privileged shareable image allows executable images to call
user-written procedures with enhanced privileges in the same way that
they call system services.
The PROTECT= option protects specified image clusters, and the
/PROTECT command qualifier protects the entire shareable image.
Another way to protect code is by using the VEC program section
attribute which protects an individual program section.
There are three effects of protecting a segment of a shareable image:
•

The shareable image is made a privileged shareable image.

•

Within the protected segment, the change mode instructions are
allowed even when the process does not have the necessary
privilege.

•

Code executing in user mode cannot write in protected areas.

When creating a privileged shareable image, you should protect the
clusters that require privilege, and not protect the clusters to which
code executing in user mode needs write access. The /PROTECT command
qualifier should only be used when the entire shareable image needs to
be protected. The VEC program section attribute should only be used
for the program section that contains the change mode dispatch
vectors. See the VAX/VMS Real-Time User's Guide for more information
on privileged shareable images.

8.4

EXAMPLES OF SHAREABLE IMAGES

The following sections contain examples of shareable images.

8.4.1

Example of Transfer Vector and Universal Symbols

Figure 8-3 is a listing of the source code for the module that is the
transfer vector for the Cross Reference Facility. Figure 8-4 shows
the LINK command and options files used to create the shareable image
CRFSHR on the logical device EXEC$:. Figure 8-5 shows the map that
resulted from this link operation.
8-9

SHAREABLE IMAGES
Note that of the 26 global symbols in the image, only 17 are of
interest outside the image -- 8 vectored entry points and 9 constants.
Note also that the transfer vector is placed in its own cluster to
ensure that it is allocated at the low-addressed end of the address
space.
(As you can see from the example, explicitly defined clusters
are allocated first in the address space.)
The values of the transfer vector symbols retain the values of the
routine addresses.
(See the listing of the relocatable universal
symbols in the map in Figure 8-5.)

8-10

CR,.TRANS,ER
YU,02

11•,!l•J•ll 111tl1J7
··~UL•1•71 1s11•1ll

TRANl,!R.YICTORI
IHI
HH

Hie
0111
HH
111108

eeee

0800

"""

0000
0000
09H
0009

""""
0S00
0H0
0HliJ

0000
000'11

0090

0000
"1001d

1:1000

0000
0000
0000
0000
0000

00000000
titliH'10

0000
091110
11000• 0000
FFFD• 31 011102
0905
001115
111111rae• 011105
,,,8. 31 001117
liJHA

l'fl'l'J"

68 ,

69 ,
NONE
70 ,
71 t INPUT PARAMETERSI
72 r
73 ,
NONE
74 '
75 J IMPLICIT INPUTS1
76
77 ',
NONE
78 s' OUTPUT PARAMETERS1
79
80 '

111000
0000

0.080.

6J ,

000111

0000

.....I
.....

0eru
08'1A

eeec

tll

,,>

82 '

tZl

87 J COMPLETION CODESI
88 '
NONE
89 '
90 '
91 J SIDE E,FECTS1
92 '
«
NONE
93 '
94
95 ,' ••
96
97
98
,PSECT SSVECTOR.a.CR,,PIC,SHR,NO~RT,EX!
99
, 1 CR, .TRANSFER I
r INSERTS A CROSS REFERENCE KEY
108
CR'8INSRTKEY
I TRANSFER
,MASK
111J1
CRP:SINIRTKEY
8RW
CRll'UNIRTKEY+2
102
103
r INSERTS A REFERENCE TO A KEY
, TIUNSF!R
104
CRlflINSRTREll'
,MASK
105
CRP:UNIRTREI'
81hl
CR,.INSRTREl'+z
106
107
r OUTPUTS CROSS REl'ERENCE SUMMARY
,TRANSFER
CR,. OUT
108
,MASK
19'
C""OUT
IRJI
11111
CRll'SOUT+2

00811'
018,

11 t

HH• SHI'
!I'll'![• 31 Hll

.2
.J
.4

"814

3
~3~

60 ., THIS MODULI 0!'1NH TH! TRANl"R VECTORS FOR TH! ENTRY POINTS CALLED
65 J BY A Ul!R O' CR,, THII MODULI ENAILES CR' TO BE LINKED Al A IHARAB~E IMA;E,
66 ,
67 J CALLING IEQUENCEI

000111
0000

111000

"•Cl•

H
,llTTL TRANl,IR.YICTORI
61 t++
62 t 'UNCTIONAL DllCRiltTIONt

NONE
81 '
83 J IMPLICIT OUTPUTSI
80 ,
85 ,
NONE

008'1

0900

YAX•li Mel~O Yll1l1

+D9111~CR,,IRCJCR'!'RY!C 1 MARt9

Figure 8-3

,TRANll'!R
eMASK
IRJI

LlHCRl'•INl•KU
LillCR'•INS•KEY
Ll81CRl'•INl•K!Y+2

' INSERT CROSS RE~ERENCE KEY

Transfer Vector Example Listing

>
!XI
C""
tZl
1-1

>
Cl
tZl
tll

CRF ... TRANSFER
v01.~2

~014

FFfq•

FFE4•

0000• 14014
31 lhHb
"019
0019
0000• 0019
31

CXl

I
1--'

20•,EB•l980 00151137
b•JUL•l978 15109124

TRANSFER.., VECTORS

FFDF•

!\.)

FF De•

00000200

0018

01!1E
'111'l1E
~iUE

ld02l
13"21
0021
0024
0024
0200

.s
.&
.1

,e
,9

.10

.11

.12
.13
.14
.15
.1&
.17
.18
.19
113

VAX•ll Mecro V02,41
Pe;e
.. oee01[CRF,SRCJCRFTFRV[C,MARJ9

4
~ 3~

,TRANSFER
,MASK
BRW

LIBSCR, •INS ..REI"
LIBSCRfl' .. INS ..REF
LIBICRfl' .. INS ..REF+2

INSERT REFERENCE TO A KEY

• TRANSfl'ER
,MASI<
BRW

LIBSCRF ..OUTPUT
LIBICRF ..,.OUTPUT
LIBICRl" .. OUTPUT+2

OUTPUT CROSS REl"ERENCE

, TRANSFER

CRFSGET ..MEM
CRFSGET ..MEM

Blhl

ALLOCATE DYNAMIC MEMORY
' JS8 ENTRY

°'

,TRANSFER
BRW

CRFSFREE..,MEM
CRFSFREE..,MEM

' DEALLOCATE DYNAMIC MEMORY

....

,BLKB
.ENO

512•< 1 •CRF ..TRANSFER>

' PAD TO FULL PAGE

en
::c
)II

:::0
tSJ

)II

t"t
tSJ

tSJ
00

Figure 8-3 (Cont.)

Transfer Vector Example Listing

CRF 4 TRANSFER
5ymbo1 t•bl•
CR.FSFREE.MEM
CRFSGET.MEM
CRFSilllSRTKEY
CRFSINSRTREF
CRFSOUT
CRF 4 TRANSFER
L.IBSCRfl' .INS 4 KEY
L.IBSCRF.INS.._REF
LIBSCRF.OUTPUT

20•fl'!B•1•80 08151137
6•JUL•1978 1511•124

********
********
********
********
********

02
02

)(

0000001110 R

********
********
********

x
x

VAX•11 Macro VBZ,41
Pe;e
.osae1tCRF,IRClCRFTFRVEC,MARJ9

5
~ 3)

02
02
02
02
02

+••···-······-····
& Paect avnopafa &
+•····-··········+
PSECT P'la111e

A11oc•tfo,.,

• ABS •
• BLANK •
SSVECTOR.,0.,CRF

00000000
00000i,,00
000Gl0200

0.>
0,)

512.l

PSECT No.

Attributea

00 (
01 (
02 c

NOP IC
NOP IC
PIC

0,)

1,)
2,)

USR
USR
USR

CON
CON
CON

ABS
REL.
REL

LCL NOSHR NOEXE NORD
LCL NOSHR
EXE
RO
LCL
SHR
EXE
RD

+•······--------·-·······+
1 Perfor111ance f P'ldfcatora i
+••··--------·--·····--·-+
p1,.1e

co
I

-----

z,.,ithliutio,.,
Co111111and procea1f P'lg
Pua 1
Symbol table sort
Pan 2
Sylllbo1 table output
Paect 1vnopai1 output
Cro11•reference output
Assembler ru" totals

P•Q• hul ta
23
----------32
1"'5
0
37
1

"0
208

CPU Time

·-······
"'0100100.05

00100100.211
0111100100.&2
00100100,01
0Gl100100,4&
00100100,01
00100100,02
00u0100.00
00100101,111

E1 apaed Tfllle
•..........•
011l1001011l UI
001001e2,112
0010010&,25
00100100,1211
0r1100103,46
0

001111~100.01

00HHH00.02
00100100,00
00100112.57

The workfr'lg set limit was s0e ca;e1,
1399 bytes C3 pegea) of virtual 111e111orv were used to buffer the fntermedf•te code.
There were 10 c•oe• of av111bol t•ble apace allocated to hold 9 nor'l•1oca1 •"d 0 local avmbola.
135 source 11,.,ea were reed 1,., P••• 1, P~oducin; 12 object records in Pe11 2.
0 pages of virtual ~e111orv were uaeo to deff,.,e 0 macro•.

····-·-····················+
I Macro libr•ry atatlat1ca I
+··························+
Macro 11brarv name

Macro• def11'1ed

.DBB41[CRF,OBJ]CRF,MLBJ1
.DBB41[SYSLIB]STARL.ET.MLB'l
TOTALS Call 11brarfea)

0
0
0

0 GETS were required to defil'le 0 111ecro1.
There were no errors, warl'lin;1 or inforMation ~e•••G•••
ILIS•L.ISS1CRFTFRVEC/OBJ•OBJS1CRFTFRVEC MSRCS1CRfl'Tfl'RVE~•LI8S1CRfl'/LI8

Figure 8-3 (Cont.)

Transfer Vector Example Listing

NOwRT NOVEC BYTE
lllRT NOVEC BYTE
NOiliRT lllOVEC BYTE

::c

>
~

tllJ

>
t1'

C""

tllJ

.....
3:

tllJ

I
I

'
J
'
P•f•P•P'lce
•s '' LtP'lk
s DELETE
EXEl1CAfl'8HR.EXE,*1MAPl1wMAP1•
' /SHARE•EXES1CRFIHR
s LINK
/MAP•MAPS1CRFSHR
s

[ CRF • C0 M
cro11

CR' S HRL NK• C0 M
fectltty

I
I Opt ioP'll t "Put

/FULL

SYSSINPUT/OPTIONS

'
CREATE A SEPARATE CLUSTER AT LOW ADDRESSED ENO FOR THE
'
TRANSFER VECTORS.
'CLU8TER•TRAN8FER
...
'
;&MATCH • LEQUALr lr 111
08JSICRF/INCLUDE•CCRF.CREF)/LIBRARY
I

CX>

.......
OS::.

V£CTOR,,,oaJl1CRF/INCLUDE•CAF.TRA~8,ER

UNIVEASAL•CRFIK.ASCICr•
CRfl'IK,..IUN,..UlZr •
CRFIK,..DEF,CRFSK,..REF,•
CRf'SK.YALUIESr•
CRFSK.VALl,..R!f'lr•
CRfl'SK.J)Efl'8 4 R!FS,•
CRFSK,..DELfTE,CRFSK 4 SAVE
SYMBOL•CRfSC ...HASHUZE1719

Figure 8-4

UNIVERSALIZE THE NON ENTRY
POINT SYMBOLS THAT USERS
MAY NEED.

tJl

::c
>
::a

tZl

>
tD
t""

tZl
1-1

Cl
tZl

tJl

I HASH TABLE SIZE •• SHOULD BE PRIME

Transfer Vector Example Link Command

EXES1CRFSl-IR

Module Name
(X)

I
~

lJ1

·---------·
CAF..,TRANSFER
CRF..,CREF
GETl"EM
CRFGBL
CR FOR
CRFSUB
SYSVECTOR

20•FEB•1980 17154

I dent

·-·--

v01.02
v02.01
v01.0s
Vli12.U
xcu.01

vet .en
fd219

...512 .oBB41[CRF.OBJ]CRF,Ol.Bsl
·-···

Bvtea

Fil•

1747 .DB841[CRF,OBJ]CRF.Ol.BJ1
282 ..,DBB41[CRF,OBJ]CR~.01.es1
~ .o8B41[CRF,08J]CRF,OLBr1
76 ...DB841(CRF 1 08J]CRF.OLBs1
202 .ossaa[CRF,08J]CRF.OLBs1
0 4 DBB4a[SYSLIBJSTARLET,OLBr1

P•g•

I.INKER V02.39

+•··················-··••+
l ObJect Module Svnoo1t1 l
+··-·····················+

Cf'eetton Date
..............
20•FEB•1980 00151
20•Feb•1980 00152
20•FE8•1980 0e1s0
20•FEB•1980 00149
20•FE8•1980 00150
20•FEB•1980 00151
19•FEB•1980 21159

.......
Crieatof'

VAX•11
VAX•11
VAX•11
VAX•11
VAX•11
VAX•11
VAX•11

V02,41
Blt11•32 vi•&22
MaCf'O V02,41
Macro V02,41
M•crio V02.41
M•ero V02,41
Macro V02.41
MaCf'O

:z:
>'

">m
t1IJ

t""
tZJ

.....
3

tZJ

Figure 8-5

Transfer Vector Example Map

DBB41[CRF,OBJJCRFSHR,EXE71

20•FE8•1980 171Sij

L.INKER

Vlr.12,3~

P1ge

+·~---·------··--··--·--·+
I Im1g1 Section Synopsis 1

+·-··---------·-······-··+
Cluster
TRANSFER,.VECTOP

DHAULT~CLUSTEF(

co
I

.......

°'

Type P•ges

Base Addr Disk VSN PFC Protection end P1gfng
1'10'5'11\1l2i:H1

I:'

READ ONL.Y

~000Cll4~·~

READ ONLY

0884:(CRF,OBJ)CRFSHR,EXE•1

20•FEB•1980 17154

M1Jorf a

··-··-·

1-'i nol"f d

LINKER V02,39

+·---·---------------------+
I ·Proor1m Section Svnoc1f1 1
·-·--·-·-----------····-··-+

------

Met ch

Page

>
::a
tzl

--------·-·

----

End

C'lF ... TRANSFER

0~0~02J0
000~020~

~~0~03FF
0~00~3FF

00000200 C
00000200 C

0~0~~200
0~~~02~~

00~002~0

00000~0~
0~00000~

c
c

0.) BYTE ~ ~OPICrUSR,CON 1 REL. 1 L.CL. 1 NOSHR 1
0,) BYTE 0

EXE,

Cl\'F ... TRANSFER

00000933
00000&03
00000A03
0000011•
000~0BEO 00000C38 0000004C
000~0C39 000000~2 000000C•

2307.) L.ONG 2 NOPIC1USR1CON,REL1LCL1NOSHR,
174 7 •) I.ONG 2
282.) BYTE 0

EXE,

RO, NOir.RT, "'40VEC

CRF ... CREF
GETMEM
CPFOR
CRFSUB

00000E00 00000E00

EXE,

RD,

"lodul e t-.eme

---------SSVECTOR ... 0,.CRF

SCOOES

, BLANK •
GETMEM
CRFGBL
CR FOR
CRFSUB
SYSVECTOR

0~0~~40~
000~04~0

---

000e0200

L.engtl'I

0~0000~2
000e~A02
0~~00BEC

0000000~

C
C
C
C

00000E00 00A00E00 00000000 C

00000E00 00000000 C
00000E00 00000E00 00000000 C
00000E00 00P00E00 00000000 C

000~0f.00

00000E00 00000E00 00000000 C

Figure 8-5 (Cont.)

(fl

Base

P1eet Name

• Bl.ANt< •

Glob•l Sec. N1me
·---·~--·-··-·-·

Attributu

A 1f0"'

····-

512,) BYTE 0
512.l 8YTE 0

°'I:""'tzl

·----·-···
PIC1USR1CON1REL.1L.CL.1

SHR 1

EXE,

~D,NOiliiRT,NOIJE:.C

:I:

RO,

IWRT,NOVEC

70.) BYTE 0

0.) BYTE 0

0,) BYTE 0
0,) 8YTE e

Transfer Vector Example Map

>
G)
tzl

(fl

202,) BYTE 0
~.l BYTE ~ NOPIC1USR1CON,REl.1L.CL.,NOSHR,
0.) BYTE 0
0.) BYTE 0

iitjRT,NOVEC

.......................&

.Dl841[CR,,OBJJCR,IHR,!XIJ1

, •• ,, •• , ••• 17114

LlNK!R YH,H

P~;e

I.I

I IY•b011 By·N•1111

......
Sy111bo1

co
I
~

.....J

.....
Ya11t1•

CR'5C.,HASHSIZE ~Hll!JlC,
CR,.C..,MAXCOL
HH004flJ
CRFst.MAKLINWID 0101flJ884
CRFSFRE:E..,MEH
00HeB6D•RU
CRFSGET ..,MEM
HH0AE,•RU
CRFSINSRTKEY
0B00flJ558•RU
CRf'SINSRTREF
000005H•RU
CRFSK..,ASCIC
000000H•U
CRFSK.,BIN..,Ulc
0000H01•U
CRFSK..,DEF
00000001-u
CRFSK..,DEFS..,AEFS 00000002•U
CRFSK.,DELETE
00000000-u
CRFSK.,REF
0000111000•U
CRFSK.,SAVE
00000001-u
CRFSK,.VALS..,REFS 00000001•U
CRFSK..,VALUES
00000000-u
CRFSOUT
00000781•RU
,REE..,MEM
0000086D•A
GET..,HEM
00000AFA•R
GET,.ZMEM
ra0000AD3•R
LIBSCRF,.INS..,KEY 000008ED•RU
LIBSCRF,.INS,.REF 00000C02•RU
LIBSCRF,.OUTPUT 00000C1B•RU
SORT..,HASH..,TABLE 00000C6t•R
SYSSEXPREG
80000148
SYSSF•O
80000150

......
Symbo1

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

v.11,,.
.....

......
Sy111bet

.....
Ye1 ye

~y111bo1

• •••••

.....
Y•lue

::c

)II

"
tSJ

)II

O::J
tot
tSJ

.....

)II

Gl
tSJ

Figure 8-5 (Cont.)

Transfer Vector Example Map

.DBB41[CRF.OBJ]CRFSHR.EXErl

20•FEB•1980 17154

+······-···-··-····+
I Svmbo11 Bv Velue 1
+·············--···+

Value

··--·

H00001a0

00000001
00000002
000000'10
0H00084

co
I

......

000002CF
IHH0558
00000589
0000A7B1

H0HA03
B0000AEF
H000AFA
HBIHB60
BHHBED

eeeaec02

eeeeec1e
0HB0C61
80080148
88880150

LINKER V02.39

Pege

Symbol••••

U•CRFSK..,ASCIC
U•CRFSK..,BIN.U32
U•CRFSK..,DEFS..,AEFS
CRF'SC..,HAXCOL
CRFSC..,MAXLINWID
CRFSC..,HASHSIZE
R•CRFSINSRTl<EY
R•CAFSINSRTREF
R•CRFSOUT
R•GET..,ZMEM
R•CRFSGET..,MEM
R•G!T..,MEM
R•CRf IFREE..,MEH
R•LIBSCRF..,INS..,KEY
R•LIBSCRF..,IN8..,REF
R•LIBSCRF..,OUTPUT
R•SORT..,HASM.TABLE
SYSIEXPREG

·-········ l.l•CRFSK..,REF

U•CRF$K..,OELETE
U•CRFSK..,OEF

U•CRFSK..,SAVE

U•CRFSK..,VALUES
U•C~FSK..,VALS.REFS

>
:::0
tSl

>
l:XJ
t""'

tSl

.....
3

R•FREE..,MEH

tSl

SYS5'AO

Kev for 1peciel cherecter1 ebovea

···················+
I * • U"defi"ed
I U • U"1VeP1e1

I WK • Ntek

& R • Re,ocet•b1• I

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

Figure 8-5 (Cont.)

Transfer Vector Example Map

.DBB4sCCRF.OBJlCRFSHR.EXEJ1

i0•FE8•1980 17154

·················+
i Imao• Synop11• I
+••···············

Virtual memory a11ocat•dl
Stack l i H I
Image header vtrtua1 block 1im1t11
Image binary vtrtua1 block 11m1t11
Image name and tdenttftcatton1
Number of file•I
Number of modul•••
Number of prcoram ••ct1on11
Number of global 1ymbol11
Number of tmage 1ectton11
Im•o• types
Map fol"mata
E1ttmated map lengt~I

a. pagea

1.
2.
CRFSHR .OLBJ

1. block)
o, block1)

9,
10.
4.

PIC, SHAREABLE, Global aectton match • •LESS/EQUAL'• G,S, Ident, MaJor•1,
FULL tn f11• ·.DBB41CCRF,LISJCRFSH~.MAPs1•
zq. block•

+••···----··-·········+
a Link Run Stat11ttca &
+···-··-·--···········+

11~1ted

(Jl

::c
E1apHd T t me

tZl

49
109
15

001001ee.17
00100100. 82

C""'

23
20
5
221

00101u 00. 29

00100110.e5
00100105, 00
00100100,u
011100102.26
001ee100,87

eia100100,1n
00100100.21
00100100.00
00 U!l0101, b0

00100 I fcHih 20

ee1001e<J,86

Total number obJect record• read (both ca11e1)1
169
of which 173 were tn 1ibl"a~1•• and 26 were DEBUG data record• contein1no 907 byte1
of module1 extracted expltc1t1v
with 5 extracted to r••o1v• undefined 1vmbol1

2 lfb~•rv 1ea1"Che1 were for aymbo1a "ot 1n the library ••arched
A tot1l of 4 ;1oba1 1ymbol table record• w11 written
/SHARE•EXES1CRFSHRIMAP•~APS1CR,SHRIFULL

>
~

............

to 500 cege1 end 78 c1ge1 of data 1toreoe Cexc1ud1ng tmege)

Nu~b•r

M1nor•1~1

CPU Time

Pao• Fault•

Command proce11tno1
Pa11 11
Allocation/Reloeatton1
P111 21
Map data aftel" object module 1vnop1t11
Symbol table outputs
Tota1 l"un valu••I
U11ng • wo1"k1no 1et

1. C
7. C

CX>

\.0

Pao•

00000200 00000DFF 000e0c00 (3072. bvt••· •• P•O••)

Performance Indicator•
I

LINKER VU.39

SYSSINPUTIOPTIONS

Figure 8-5 (Cont.)

Transfer Vector Example Map

°'
tZl

Cl
tZl
(Jl

SHAREABLE IMAGES
8.4.2

Example of FORTRAN Shared COMMON

This section contains an example of FORTRAN shared COMMON.
The
FORTRAN subroutine SHRSUB is a shareable image that contains two
COMMON areas. One is a shared or global COMMON area (GLOBAL COMMON).
This is a data area that is shared by all executable images linked
with the shareable image.
The other is a nonshared COMMON area
(LOCAL COMMON);
each
executable
image
has its own copy of
LOCAL COMMON. The program section attributes control whether a COMMON
area Ts shared or not. Note the attributes of such program section
in particular, GBL, OVR, and SHR.
•

The GBL attribute causes the program section to be recorded in
the symbol table of the shareable image for later use by an
executable image. The FORTRAN compiler sets the GBL attribute
for all COMMON areas.

•

The OVR attribute ensures that all modules contributing to the
program section start at the same address space. The FORTRAN
compiler sets the OVR attribute for all COMMON areas.

•

The SHR attribute specifies that only one copy of the COMMON
area is to appear in physical memory. The FORTRAN compiler
sets the SHR attribute for all COMMON areas.
Note that a
PSECT ATTR option in an options file changes the program
secti~n attribute of LOCAL COMMON to NOSHR.

Figure 8-6 shows the listing of the FORTRAN subprogram SHRSUB that
defines GLOBAL COMMON and LOCAL COMMON;
Figure 8-7 shows the LINK
command to create the shareable image;
and Figure 8-8 shows the
resulting map. Figure 8-9 shows the listing of a FORTRAN program MAIN
and
that calls SHRSUB; Figure 8-10 shows the LINK command for MAIN;
Figure 8-11 shows the resulting map.

8-20

VAX•11 ,ORTRAN Ti 1 95•J•

S•Me,.•1911 11111151
5•M•r'•1911 17159111
IH"l

SUBROUTINE SHRSUB

c
c
c
c

lli!l02

LOCAL.COMMON will be Pr'fvete per'•fm•G• commo"
GLOBAL.COMMON wfll be e eher'e•ble co1111110"
COMMON /LOCAL.COMMON/ J,JlC511)
COMMON /GLOBAL.COMMON/ 1<,1<1cs11>

liJ003

TYPE •,• J fe f" the COPY•ON•RfF commo"'
1 I< fe fn • eh•reebl• commo"•
TYPE *1• E"ter'fng • Zer'o wf11 leeve the ver'f•ble u"ch•"ged•
TYPE •,• •
TYPE•,• Pr'evfoue velueea J • •,J,• K • •,1<
IF CM 1 NE, 0) J • M
IF (N ,NE, 0) K • N
TYPE .,. CUr'r'e"t velueea J . •,J,•
K • •,K
TYPE •,• E"ter' new veluea for' J,1<•
ACCEPT •,M,N
IF (CM ,EQ, 0) ,ANO, CN 1 EQ 1 0)) RETUR~
GOTO 10
END

1/1021&
1/1005
000f)

P~ge

4DIBZ1[00LDMA~J~H~au1;,0Rr5

0007
0008
000q
111010
1/1011

0012
0013
0011.i
0015

(/)

P~OGRAf"!

tZl

I'll•"'•

I
I-'

SE.CTIONS
Byte a

SCODE
SPDA T.A
2 SLOCAL
3 L.OC•L ..COMMON
4 GLOBAL. .. COMMON

lib

Iii
1

191
72

2048
2048

°'

At t r'f butH

SHR
EXE
PIC CON REL LCL
SHR NOEXE
PIC CON REL LCL
PIC CON REL LCL NOSHR NOEXE
SHR NOEXE
PIC OVR REL GBL
SHR NOEX!
PIC OVR REL GBL

tZl

RD NOWRT LONG
RD NOlllRT LONG
lliRT LONG
RD
WRT LONG
RD
WRT LONG
RD

>
Cl
tZl
(/)

ENTkY POitliTS
.lddreaa

Type

0•00000000

N•me
SHRSU8

VARI.l8L.ES
.lddr•••

Type

N•me

3•0000000PI

I•4

Addr•••

Type

Neme

Addr'ee1

Type

Neme

Add,.•••

TvP•

N•m•

4•00000000

1•4

2•11101011

I•4

l•01100114

I*4

ARRAYS
Addr'eea

Type

t11e111e

Byt••

Dfme"efo"'

3•00000004
4•00000001&

I•4
I•4

Jl
I< 1

Z044

(511)

2044

(511)

Figure 8-6

Listing of FORTRAN Shared COMMON Subprogram

SHRSUB

5•M•P•t•e• 1e1111SJ

S•Mel'•l•!I 171S•ili

YAX•11 ,QRTRAN T1 1 •S•J•
.oa121tQOLDAANJIHRIUl;,oR1S

P~oe i

LABELS
Add!'eU
1•0001/JI003F

Label
llil

Total Spece Allocet•d • 4&75 Bvt••

tll

::c

COMM•NO QUALIFIERS
00

"'"'

">
tsl

FORTRAN /LIST SHRSUB
/CHECK•CNOBOUNDS,OVERFLOW)
/DEBUGs(NOSYMBOLS1TRACEBACK)
/F77 /NOG 4 FLOATING 114 /OPTIMIZE

t"'
tsl

/WARNINGS

/NOD 4 LINES

/NOMACHUIE 4 CODE

/CONTlNUATIONS•19

COMPILATION STATISTICS
Rul'I Ti111e1
Ehp1ed Thel
Peoe Faul t11

Dyl'lemic Hemol'yl

1-4

lellJ3 aeCOl'ldl
a.2ti ••conda
342
37 peOH

Figure 8-6 (Cont.)Listing of FORTRAN Shared COMMON Subprogram

tsl
tll

Cll

S LINK /SHARE:SHRSUB /HAP:SHRSUB /FULL SHRSUB, SYSiINPUTl/OPTIONS

)Ill

co
I
N

I Options ;nout for SHRSU8

1harea~le

image

PSECT:LOCAL..,CO"IMON, ~40SHR
COLLECT:LOCAL~CLUSTER,LOCAL..,CO~MON
UNIVE~SAL:SHRSU8

)II

t'llJ

OJ
t""
tSl

.....
3
>
Cl
tSl
Cll

Figure 8-7

LINK Command for FORTRAN Shared COMMON Subprogram

SHRSUB

Lil'llKER 1/02.40

22•FEB•1980 1412b

Page

+•···-------------------·+
1
Svnooais 1
+···--·----·----····---·-+
O~Ject

"lodu 1 e "la"'e

ltjel"lt

SHRSUB
OTS5Ll"4r<AGE

V~SRTL

•EXE r 1

Bvtes

~oou1e

Fi le

Cl"eatiol"I D•te

4bb5 4 D882:[GOLD~AN]SHRSU6.08JJ1

3 .O~A5:[SYSLIBJSTARLET.OLSJ1
~ 4 0RAS1[SYSLIBJl/~SRTL,EXEJ1

1•iJ'13

.oBB2:[GCLD~ANJSHRSu8.EXEs1

22•FEA•19~0

+------------------------+
Sect1ol"I Svnoos1s 1
t
+---·--------------------·

Cl"eator-

22•Feb•1q80 1412&
1q•FE8•1980 21157
20•FE8•1q8~

14&2c

18155

L.Il'llKER

VAX•11 FORTRA~ T1.95•3b
V4X•11 ~•cro 1/02,41
LINK•32 1/02,H

Pa9e

l/~2,40

I
I'.)

.i:::.

C11,11te,.

-------

LOCAL,.CLUSTER
DEFAULT 4 CLUSTER

Tvi:>e

P•qes

---- ----- -----·-·- -------- --- -------------------··
2

"''1'-'t.1e'2rH'

;,00~1t'Ae1·

.a1110~0C0l1

~lti'011.114['1~1

1
1

00001o0U

3
3

ten

~00~ 180C1

3
3

l/MSRTL

Bese AddP' Disk VaN PFC Protection ana Peging
~

READ WRITE

i21 REAO
0 REAO
0 READ
0 READ

ONLY
wR ITE
ONLY
wR ITE

~121~02E0C

""0

1 READ ONLY
0 READ ONLY

t~~ 1th"lt,~1

Figure 8-8

READ wR ITE

COPY ON l(fF

:c
)II

I~age

t'IJ

)II

D:J

Met ch

Global Sec, Nel'lle

··--·

·--··------·----

-----·· ··----M~JOl'id

t-11 nor1 d

t"'
t'IJ

1-t

)II

Cl
t'IJ

rn
COPY ALiliAYS

COPY ON REF

VMSRTl.,..001
VMSRTL..,002
l/MSRTL..,H3

LESS/EQUAL
LESS/EQUAL
LESS/EQUAL

Map of FORTRAN Shared COMMON Subprogram

1
1
1

2000
201d0
2000

.oaa21[GOLDHAN]SHRSUB.EXEfl

Paect Name

·····-····

"odu1 • t.i11111e
...........

1.0CAl..COM"10N

22·~£8•1•&•

.B•••
...

···························+
I Ppog,1111 Section ly"op1i1 l
+••························+

...

......

El"ld

Le"gtl'I

1412•

.....
A1ion

P~ge

I.INKER Vl2e41

.......•..
Attr'tbutH

SHRSUB

000009FF 00100800 C
00000200 00000~FF 00019800 C

2148.) LONG 2
2048.) LONG 2

PlCrUSR,OVR,REL,G8L1NOSHA,NO!XE1

S1'4RSU8

00000A00 00000ABE 0000008F C
00000A00 00000ABE 000010BF C

191.) LONG 2
191 e) I.ONG 2

PIC1USR,CON,REL1l.CL1

00~00200

SPOA TA

SHR,NOEXE,

R(),

illRT,NOVEC

RD,NOWRT,NOVEC

['I.)

• BL.ANK •

00000A00 00000000 C
00000A00 00000A00 00000000 (

~0000A00

OTSSl.INKAGE

GLOBAL..,COMMON

tZJ

0.) BYTE 0 NOPIC1USR1CON,REL1LCL1NOSHR,
0.) BYTE 0

EXE,

RO,

WIU,NOVEC

°'t""'

WRT,NOVEC

.....

tZJ

000~0C~0 ~0001l~F 00000800 C
00000C00 000~1lFF 00000800 C

2048.) I.ONG 2·
2048.) LONG 2

PIC1USR10VA,REl.1GBl.1

SHA, NOUE,

SHRSUB

00001531 00000132 (
00001531 00000132 (

306.) LONG 2
l0o.) LONG 2

PIC1USR1CON,REl.1LCL1

SH.R,

EXE,

RO,NOwRT,NOYEC

SMRSUB

00~~1Q00
000~14~0

00001534 ~0001536 00000003 (
000~1514 ~0001530 000A0003 (

3.) LONG 2
3.) LONG 2

PIC1USR,CON,REL1LCL1

SHR,

EXE,

RD,~OlllRT,NOVEC

OTSSLINKAGE

P-~0~1&~0

e0~~1o47

0~~~1b~~

00001647 00000048 (

72.) LONG 2
72.) LONG 2

PIC 1 USR,CON,REL1LCL1NOSHR,NOEXE,

SHRSUB

SC ODE
~OT SSC ODE

SLOCAL

0000~048

Figure 8-8 {Cont.)

,,::c>'
>'

RO,

Map of FORTRAN Shared COMMON Subprogram

RO,

WRT 1 NOVE.C

tZJ

..DBBZ1[GOLDMAN]SHRSUB.EXEJl

......

.....

BAIUCB,.GU

0111002380•RU

22•FEB•19B0

+·-------··-··-···+
l Symbol1 Bv N•m• 1
··················+

------

IAlllBLNK ..LINE
IAHICB,.POP

HH2370•RU

.....

11111534
IHllHI

000020B0•RU

BASSSTATUS
BASSSTR,.D

000021E6•RU

22•FEB•1980 14126

+····--····--------+
l Symbol• Bv Velue I
+··················+

Value

11111411

Symbol

····-BASSSCRATCH

300021F0•RU

BASSI N,.F ,.R

°'

Velue

BASSI NS TR
BASSI ~ .... D,.R

0'108UA0•RU

.01B21[GOLDMAN]SHRSUB.EXEJ1

-----

Symbol

Value

h•bol

1~126

LINKER v02.u

.....
Value

0HHlH•RU
HH2338•RU

erae.ezece•Ru

LINl<ER V02. lh1

$ylftb01

Vah1•

•••••

llllHH•lltU

llllfl11•11tD
FOAllERRINl.SAV 1111.lll•RO

~ORllCB.RET

ti.>

P~ge

>
::c

tZJ

>
to
tZJ

---·-·····
~·FORSLINKAGE

......
,ORISCB.PUIH

I:"'

Svmbol1, ••

RU•SHRSUB
R•BASILINKAGE
RU•FORSCLOSE

Page

t-4

R•OTSSLit.jKAGE

>
Cl
tZJ
ti.>

Key for 1pect11 cher1cter1 aboves

····---·--·········+
& * • Undeftr1ed
& U • Untv•~••l

l
I A • Re1oceteb1e l
' WK - Week
'

···--------··--·---+
Figure 8-8 (Cont.)

Map of FORTRAN Shared COMMON Subprogram

~D8621(GOLDMAN]SHRSUB,EXE11

22•FEB•1q80 1412&

~irtual memorv allocated:
Stack size:
Image ~eader virtual block lim;ts;
Image binary virtual block limits:
Image name and ;dentificatio":
Number of Hlell
Number of modules:
Number of progre"' sect;ons:
Number of glohal symbols:
Number of image sections:
I1T1age types
Map for"'at:
Estimated map le"qth1

L.INKER v.a2,40

I
~

....J

~~00~20J

~00187Ff

?~~1~6~0

(112128. bytes, 219,

pa~es)

oages

13,

1. block)
11. blocks)

2.
s1-1i:;sus ,08Js
3.

12.

3,
q,

242.
q,

PIC,
~ULL

ss.

S~AREABLE.

1n f;le
r-1ocks

Performance Indicators

Global section match

= "EQUAL", G,s. Ident, MaJor=2uu, ~1nor:82&091S

"~DB82&[GOLDMANJSHRSU6,MAPs1"

tn
:El

wor~;ng

set limited to 2b8 oaQes

tZl

E 1 a1:11ed Time

t12

0~1(/:010fl'l,06

0~:~0H~~. 78

I:'""
tZl

182
P2

'3~1it!01~w. 71
0~:00r~rn.2&

0~;:00102.35

70
159

01i1rn0:,rn.21

'31t110ia:~1.41

00:001~1.84

e0HH'S03.&4

20
57'5

an~

,,>

CPU T4 me

Page Faults

COMMano processing:
Pass 11
Allocation/Relocat;on:
Pass 2:
~aD oata after object mo~ule synopsis:
sv~bol table output:
Total run values:
UsinQ a

51 Daqes of data

0~100H1~,91

0~10011!'~, 13

0~1t;0:~J.83

0e.rntH03,23

00: ..hH0q.92

stora~e

Cewcludinq image)

Total nuMber object records read Cbot~ passes):
75
of which 1~ ~ere i" libraries •nd 4 ~ere DE~'IG jata records conteininq 149 bytes
Number of ~odules extracted exolicitlv
with 1 extracted to resolve undefined svmtols
0

l~brary

searches were for symbols not in t"e liDrary searc"eo

A total of 21.i global sy111bo1 taole records .... as written
/SHARE:Sn~SUB/HAP:SHRSU8/FULL

SHRSU~ 1 SYS$!NPUT1/0PTIO~S

Figure 8:_8

·------------····+
l Image Svnop•1• 1
+·---------------·

·---------------------+
! Link Run Stat,stics l
+---------------------+
CX)

Page

(Cont. )

Map of FORTRAN Shared COMMON Subprogram

°'

Cl
tZl
tn

22•Feb•1980 14126158
29•Nov•1979 15124120
0001
0002

VAX•11 FORTRAN T1.95•36
.oaa21CGOLOMAN]MAIN.FORs1

Page 1

PROGRAM MAIN
COMMON /LOCAL.COMMON/ J,J1C511)
COMMON /GLOBAL.COM~ON/ K1K1C512l

0003
0004
0005

TYPE*•' Thia orogrem te1t1 COPY•ON•REF common1'
CALL S"RSUB
TYPE *1' Finel valu11: J : '1J1'
K a ' 1K
STOP 'Common test complete'
END

000b

0007
0008

PROGRA"1 SECTIONS
Byte1

~ame

0 $CODE

I
I\.>
00

1 SPOA TA

115
Bl!>

2 SLOCAL

3 LOCAL .. COMMON

2'1i'48

2t52

GLOBAL .. C:OMMON

AttP'1bute1
PIC CON REL LCL
SHR
EXE
PIC CON REL LCL.
SHR NOEXE
PIC CON REL L.CL NOSHR ~OEXE
PIC OvR REL GBL.
SHR lliOEXE
PIC OVR REL. GBL
SHR NOEXE

~OwRT

I.ONG

RD NOl'fRT LONG

?O
RD

.-iRT LONG
I.ONG
INRT I.ONG
~RT

Cf.I

::c
)II
::a
~

)II

t""

ENTRY

POI~TS

t-4

AddP'elS

TvPI

31:

Na111e

)ii

Cl
0-e0000~00

MAIN

VARIABLES
AddP'eSI

Type

Name

3·0~~0000~

I•4

Addl"lll

Type

Na"'e

Bytes

3•000000P.l.I
4•0000000U

1•4
1•4

J1
I< 1

2044

4ddP'lll

Tyi:>e

I.I• (I II)~ 0 0 ir.'0 ~

I•4

Name

ARRAYS

2048

Figure 8-9

Dime"1iona
(511)
(512)

Listing of FORTRAN Program Using Shared COMMON

FUNCTIONS AND SUBROUTINES REFERENCED
SHRSUB

Tote1 Spec• A11oceted •

433~

Bvt••

MAIN

22•Feb•1980 1412&158
29•Nov•1q7q 1512412~

VAX•11 FORTRAN T1.95•3&
.DBB21[GOLDMAN]MAIN.f0RJ1

COMMiND QUA~IFIERS
FORT~AN

::c
::a

/LIST MAIN

)II

ICHECK:CNOSOUNOS,OVERFLOW)
:X>

I
:-...>

/DE8UG:(~OSY~b0LS,TRACE9ACK)
/F77 /NOG~FLOATING /IQ /OPTI~llE

tZJ

)II
/WAR~INGS

/~OO~LINES

/NQMAC~lNE~CODE

/CONTINUATIONS:19

Run Times
Dvna111; c

~emorv I

tD
C""'
tZJ
H

COMPILATION STATISTICS
Elapseo Time:
Page Faults:

Page 2

seconds
3.82 89CO!"ldS
3lb
3b Pages

io.59

Figure 8-9 {Cont.)

tZJ

Listing of FORTRAN Program Using Shared COMMON

LINK /EXE:MAIN

/MAP:~AIN

/FULL

~AIN 1

SYS$JNPUT1/0PTIONS

Ootion• input to 1;nk main
00

SHRSUB/SHARE

PSECT:LOCAL 4 CO~~QN,NOSHR

P~og~am

en
::a

>
XS

tSJ

>
tD
t""
tZJ

......
3

Cl
tSJ

t'J)

Figure 8-10

LINK Command for FORTRAN Program Using Shared COMMON

~AI~

I.INKER

22•FEB•1980 14127

Pege

V~2.40

+----------~·--··---····-+
1 Object ~odule Svno~si1 £

+•···-------------------··

.....

Module Name

ldel'lt

SHRSUB
MAIN

,EXE rt

---

OTSSLINKAGE
SYSVECTOR

4332 .DBB21[GOLO~AN]MAIN,OBJJ1

1•fa"3

3 .DRAS1(SVSLIBJSTARLET,OLBs1

~21q

Bytes

Fi le

.......

Cl"eet i 01'1 Dete
...............

.DBB21[GOLOMAN]SHRSUB.EXEJ1
.DR•S1[SVSLIBJSTARLET,Ot.B11

22•FEB•1q80 14126
22•Feb•1980 14120
19•FEB•1qee 21157
19•FEB•1980 21159

Cl"eatol"

L.INK•li VH,40
VAX•11 FORTRAN Tl,95•36
VAX•11 M•el"O Vl.,41
VAX•11 Maero Vl2,41

tll

,,::c>
CZl

:JO

.D082s[GOLD~AN]~AIN.EXE:1

22•FE6•1q8~

14:27

LINKER

Page

V02.~0

·-------·----------------+
1 Image Sect;on Svnoosis 1
·------------------------·

:...J
~

Cluster

-------

SHRSUB

VMSRTL

DEFAULT.CLUSTER

TvPP Pages

Base Ador

Dis~

~A~

PFC

Prot~~t+on

READ W?ITE

a~d

---- ---·- --------- -------· --- -------------------·4

00~0080(i

0000113~~
00~~12~~

0
0

0 READ OlllLY
"' READ WRITE
0 READ ONLY
0 REAi) wRITE

00001A0t;

000ta1C0kl

3
3

11
U3

00"11' 1E0''

I!'

~001860"1

1
1
1
2{11

-~00"'0200

000~0'100

001l10ii'lb0Z

4
0

~
~

253

~i000340~

7FFFD80~

Figure 8-11

"rt-

1 READ ONLY
0 READ ONLY
0 READ WRITE

?aqtnq

COPY ON REF

°'
t""'
CZl

1--t

Gtobal Sec. Name

·----------·-·--

l"latcPI

---··

SHRSU8.,.001
SHRSUB.Hi
SHRSUB.003
SHRSUB ... 004

EQUAL
EQUAL
EQUAL
EQUAi.

VMSRTL..001

LtSS/ECilUAL
LESS/EQUAL
LESS/EQUAL

Maj 01" id

·---···

·-----·

2lHI

82&~915

2~4

82b0915
8260915
826'1915

2'14
244

Mi rior f d

COPY ALWAYS
VMSRTL.Hi

COPY ON REF

VMSRTL~H3

0 READ OlllLY
COPY ON REF
0 READ WRITE
0 READ ONLY
~ READ ~RITE DEMAND ZERO

Map of FORTRAN Program Using Shared COMMON

2000

1
1

20'10

200121

>
Cl
CZl
tll

.oee21[GOLDMAN]HAIN.EXE11

22•FES•1Q8~

+··-·-------··----------·-··
l
Seet;on Svnopsia &
·----·-··---------·-·······+

14127

LINKER

v02.o

Pao•

Prog~a~

P1ect N1me

-·······-SP OAT A

~odu le

Name

--··----·-·
~AIN

SLOCAL
MAIN

SC ODE
co
I

.OT SSC ODE

, BL.AN!\ •

ease
....

E.,,t'.'l

---

-----L.e,.,ot~

.....
• 1 i Ql"I

•ttrtbutn

·····-····

~~~~~200

~~~~~254

00000~55

PIC,USR,CON,REL,LCL1

~~~~~2sa

~000005s

(
c

85.) LOl'IG 2

~~~~~2~~
~~0~~ar~

~~0~~a1F

0e0~~~20

~~0~~a1F

00000~20

32.) LONG 2
32.) LOf\iG 2

PIC1USR,CO~,REL1LCL1N08HR,NO!XE1

~~~J0a00

es.> L.ONG 2

SHR1NO!X!1

RO,NOWRT,NOV!C
RD,

1on,.NOVEC
(I)

MAIN

~~~~0~~~
~~0~e60~

~~~~0&72
00~~~&72

~00~0~73
0~000073

(
c

115.) L.ONG 2
11S.) LONG 2

PIC1USR,CON,REL1LCLr

SHR1

EX!1

RO,NOWRT,NOVIC

OTSSLINKAGE

~J~00&7a
~0~~0b74

00~00&7&
00~~~&7&

0~0~0003
0~000~~3

c
(

3.) LONG 2
3.) LOlllG 2

PIC,USR1CON,REL,LCL1

SHR,

EXE,

RD1NOWRT1NOVCC

0~~~~8~~

~0~0~8~~

00000~0~

(

00~00800

00~00000

0.) BYTE 0 NOPIC,USR1CON,REL1LCL1NOSHR,

000008~~

0~000a~~

~0~~0s0~

0a000~00

~~~~08~~

00~0~FFF

a00008~0

SHRSUB

d~~008J~

~000~800

00000A0~

(

MAI~

~~0~08~~

~0~0~FFF

0~0008~~

SHRSUB
MAIN

l.~0~1200
0~0~120~
0~0~12~0

0~001A0l
~~0012~~
0~0~1A0l

~00008~4
~0000~~0
~00008~4

OTSSL.INKAGE
SYSVECTOR

LOCAL.._COMMON

GLOBAL.COMMON

Figure 8-11 (Cont.)

::c

>
::c
tZl

°'
t""'

tZl

0.> BYTE 0
0.) BYTE 0

EXE,

RD,

WRT,NOVIC

Cl
tZl

2~48.)

PIC,USR,OVR,REL,GBL1NOSHR,NOEXE1

RO,

lllRT, NOVEC

L.ONG 2
0.) LONG 2
2048.) LONG 2

(
(
(

2052.) LOlllG 2
0.) LONG 2
2@52.) LONG 2

PIC,USR,OVR,REL,GBL,

RD,

WRT,NOY!C

Map of FORTRAN Program Using Shared COMMON

SHR,NOf>CE,

(I)

.oee2:(GOLD~AN]MAI~.~XE:1

22•FE8•198~

14:27

LINKER

Page

V02.~0

+---·-----------·-·
1 Symcola 8y
&
+••··-------·-----·
~•me

------

-----

---·--

-----

~rn~l!l~o80•1W

------

BASiSCRATCH

eirc.1~02981'il•i:w

tiASSIN ... D...,R
SASiIN...,F ,,.R

---··

fi4~Vl~27F0•RiJ

1:US'SSTATUS

0~002938•RU

~'~0'1127E8•Ru

8ASSSTR,..O

00002bC0•RU

Value

Svmcol

8ASS\8LN1<,..Lit-;f
BAS$SC6.GE T
BASUCB.POP

Symool

•rn002cu~·Rl.I

J"111rn2970•RU

Symbol

Value

8AS$!~STk:

Value

Svmbol

Value

~rn002908•RU

FO~$$CB.PUSH
f0R$$C~ 4 RET

00002418•RU

FORSSERRSNS.SAV

~0002408•RU

00~02428•RU

(Jl

:c
)ii

.o Be 2 : ( G0 L(l ~A rJ l ~A IN. Ex E J 1

22•FEB•198~

14127

LINKER Vll'2.4ta

·---·-···-·----·--·+
1
By V11ue '
+···-----··-·--····+

Sy~bOll

w
w
Value

~00"'1A00

~·BAS$LlNKAGE

fo~

R•F OR$L.l Ni<AGE

•~eci11

cha~1cte~1

+•·····-·-·--······+
1 * • U"defi"ed
1 U •
1 R

)ii

tD
t""'
t:rJ

)ii

R•OTSSLINi<AGE

RU•SHRSUB

Kev

t:rJ

R•MAIN

000P~b7U

Symbol••••

~~0e00~0

Page

U"1ve~a1l

above1

• Re1ocat1ble 1

1 ~K • Weak

+••·······--·······+

Figure 8-11 (Cont.)

Map of FORTRAN Program Using Shared COMMON

t:rJ

(Jl

.a.DBP?1 lGOLD"1AN] ~A IN.EXE J 1

22•FEB•1980 14127

LINKER \102,40

+·····-···--·-···+
& Image Synopsis i
+------···------·+

virtual memory allocatedl
Stael< sizt>:
Image needer virtual block 11m;t1:
Image binary virtual block 1im1t11
Image name and identifications
Number of fi 1es:
Number of mo~ulesz
Number of proQram sect1on11
Number of g1oba1 symbols:
Humber of image sections:
User transfer address:
Debuqger transfer address:
Image tvPe:
~ac format:
Estimatea m~p lengtn:

~0~~~2~0 0~01BDFF
2~. Dages

'1:1

C113bo4, ovte11 2z2. a1ge1)

"· clocks)

'5.

13.
43"·

13.

tlltlf~~j~-,111~

s:.h'V'l1o8
OHUHBL.E.

FuLL 1n f11e
813, blocks

~.o~~2: [GOLDMA~JMAI~.~APrl"

·----·----------------+
L Link Run Stat;st;cs 1
+-------------------··+
00

Performance Indicators

Page Faults

Cornm•"d proce11ing1

----------·
24

.t>.

P111 11

01u0010111.11
00HH'.1101.30

aet limited to

30~

paaes end 50

0~1~0100.20

51
1b3

Pa11 21
Map d•t• after object module sy"oos;s:
Symbol t1ble outaut1
Total run value11
wor~ing

CPU T11111

302
73

Allocatfon/Relocatio~a

Usfno a

00100111i0.2e
00100102.0ci
00:00100.~1
00100104.~5

13
b2b
o&~es

~eta

1tor1ge Cexcludf";

:J:

>
::c
Ele;::iud Tim•
.............

HIHU1eH
1a0 8'Hll &85•1112

uue1ee, 75

001011ru. u
00100105.1'

0ra10111uia.sti
001001 u,ee
•~•;•)

Total number obJect record• read Cbotn passes):
21Q
of which b7 were 1n libraries end~ were DEBUG date record• containing 13q bvte1
124 byte1 of OEBuG date were wr1tten,sterting at va~ b with 1 blocks allocated
Numoer of modulea extracted explic;tly
with 2 extracted to resolve undefined symbols

0 library searches were for svmools not ;n the liDrary searched

A total of 0 qlobal symbol teble recoros was written
IEXE:MAIN/~AP:MAIN/FULL

1. t;\loclc)

2.
MAIN

0001BC~~

Pege

MAIN,SYS$!NPUT:IOPTIONS

Figure 8-11

(Cont. )

Map of FORTRAN Program Using Shared COMMON

tzl

°'

I:""'
tzl

G'l
tzl
ti')

SHAREABLE IMAGES
8.5

USING SHAREABLE IMAGES

To be of use, shareable images are normally linked into another image.
Usually shareable images are installed by the system manager to make
them available to the cooperating users at run time. Installation of
shareable images is dealt with in the VAX/VMS System Manager's Guide.
You must use an options file (see Chapter 5) to specify a shareable
image as input to the linker.
In an options file the /SHAREABLE
qualifier becomes a legal input file qualifier, identifying the
associated file as a shareable image.
The /SHAREABLE qualifier
optionally accepts the keywords COPY or NOCOPY, specifying whether the
linker is to create a private copy of the shareable image in the user
image. The default value is that no copy is produced.
When an executable image is linked with a shareable image, the
shareable image is assigned virtual address space in the executable
image. But the linker does not copy the shareable image binary into
the executable image file unless COPY is specified.
When an executable image that is linked with a shareable image is run,
the image activator opens the shareable image and checks the global
section match, as described in Section 8.2.3. If the match succeeds,
the image activator maps the shareable image into the assigned virtual
address space. One of two things happen depending on whether the
shareable image has been installed with the /SHARE qualifier.
If the shareable image has been installed with the /SHARE qualifier,
all processes share the same copy of the shareable image in physical
memory. If the executable image references a page of the shareable
image that is not currently in physical memory, th.at page is read in
from the shareable image. If the executable image references a page
that is already in physical memory, that page is used. Note that once
a page of a shareable image is read into physical memory for one
process, any other process can use the same page in physical memory.
If the shareable image has been installed without the /SHARE qualifier
or if it has not been installed, or if the global section has the
copy-on-reference attribute, the image activator creates a private
copy of the shareable image. In this case, the private copy of the
shareable image is treated as part of your executable image.
Each
process that is linked with the shareable image must have its own copy
of the shareable image in physical memory.
If the match fails, the image activator displays an error message
indicating that the required global sections are not available.
If the image activator cannot find the shareable image and if the
executable image has a private copy of the shareable image, that copy
is used. But if the executable image does not have a private copy,
the image activator displays an error message indicating that the
shareable image was not available.
Note that, if the image activator finds a shareable image and the
match fails, it will not use a private copy even if one is present in
the executable image.

SHAREABLE IMAGES

NOTE
The image activator assumes that both
installed
and
uninstalled shareable
images are in the directory defined by
the logical name SYS$SHARE. If you want
to use a shareable image that is in
another directory, you must assign the
file specification of the
shareable
image to the name of the shareable
image. Note that you should assign the
complete file specification, including
the device and directory. For example:
$ ASS~GN DBAO:[TEST]SHRSUB.EXE SHRSUB

8-36

APPENDIX A
LINKER MESSAGES

This appendix lists the code and text portions of messages that the
linker can issue.
The messages are listed in alphabetical order by
code.
The messages are designed to give you all the necessary information
about the error. Brief explanations are included for a few messages
that are not self-explanatory.
BADCCC, Module "[name]" has bad compilation completion code

[code]

BADIMGHDR, Bad shareable image header in (ile "[file-spec]"
BADPSC, Module "[name]" has
"[number]"

transfer

address

unknown

P-section

BASESYM, Base address symbol "[name]" is undefined or relocatable
CLOSERR, Close failure on "[file-spec]" code= %X[error code]
CONFMEM, Conflicting virtual memory requirement
[number of] pages for cluster "[name]"

%X[address]

for

CRE8ERR, Failed to create file "[file-spec]"
CRFERR, Error
Facility

code

%X[error

code]

received

from

Cross

Reference

DBGTFR, Image "[file-spec]" has no Debugger transfer address
DIAGSISUED, Completed but with diagnostics
EMPTYFILE, File "[file-spec]" contains no modules
ENDPRS, Parameter parse completion error, code = %X[error code]
EOMFTL, Module "[name]" specifies Linker abort
EOMSTK, Module "[name]" leaves [number of] items
stack

Linker

internal

ERRORS, Module "[name]" has compilation errors - image deleted
EXCPSC, Module "[name]" defines more than
EXCSPAR, Too many
"[file-spec]"

parameters

25~

option:

FAOBUG, FAQ failure

A-1

P-sections
[option

name]

file

LINKER MESSAGES
FATALERROR, Fatal error message issued
FIRSTMOD, First input being a library requires module extraction
FORMAT, File "[file-spec]" has illegal format
GSDTYP, File "[file-spec]" has an illegal GSD
code])

record

(type

ILLFMLCNT, Min. arg. count of [number] exceeds max.
formal spec. of "[routine name]"

[type

([number])

ILLKEY, Unrecognized keyword in parameter of option file "[file-spec]"
ILLQUALVAL, Illegal qualifier value
ILLREP, Module "[name]" has store repeated count [number] greater than
[number]
ILLTIR, Module "[name]" has illegal relocation command= [number]
ILLVAL, Illegal parameter value in option file "[file-spec]"
ILLVPS, Module "[name]" contains illegal position ([number])
([number]) in TIR$C_STO_VPS command

size

INITPRS, Parameter parse initialization error, code = %X[error code]
INSVIRMEM, Insufficient virtual
cluster "[name]"

memory

for

[number

of]

pages

for

INTSTKOV, Linker internal stack of [number
module "[name]"

of]

items

overflowed

INTSTKUN, Linker internal stack of [number
module "[name]"

of]

items

underflows

IVCHAR, Invalid character in parameter - option file "[file-spec]"
LIBFIND, Failed to find valid lib.
%X[address] %X[address]

mod.

or shr.

image STB.

LIBFMT, Library "[name]" (format = [bad format]) has incorrect
(not =[correct format]) for this Linker
•

Might be caused by a corrupt library or an attempt to
RSX-llM library.

LIBNAMLNG, Library module name
illegal

length

([number

RFA

format
use

characters])

LINERR, Command line segment in error
\[error]\
MATCHID, Global
([number])

section

match

ident

([number])

exceeds

maximum

MAXCHANS, [number of] channels exceeds maximum allowed of 64
MAXIOSEG, [number of] I/O segment pages

exceeds

maximum

allowed

65535

MAXISDS, [number of] I-sections exceeds maximum allowed of 65535

A-2

LINKER MESSAGES
MAXPFC, Page fault cluster factor of [number] exceeds maximum (255)
MAXSTACK, [number of] stack pages exceeds maximum allowed of n5535
MEMBUG, Memory (de)allocation bug [description] %X[address]
•

Internal linker error

MEMFUL, Linker virtual address space
link

insufficient

MINDZRO, [number of pages] as minimum I-section size
allowed of 65535
•

complete

this

exceeds

maximum

- not 1 to

[number

DZRO_MIN option value too high

MODNAM, Illegal module name of [number of] chars.
of] chars.
MSGERR, Linker has error message bug [hex data]

MULDEF, Symbol "[name]" multiply defined by module "[name]"
•

The named module defines a
already de£ined.

symbol

that

another

MULPSC, Module "[name]" has conflicting specifications
"[name]"
•

A previously encountered module has
program section with other attributes.

module

for

already

has

P-section

defined

the

MULTFR, Module "[name]" multiply defines transfer address
•

The named module defines the image transfer address (starting
point), but a previously processed module has already defined
the transfer address.

SPNAMLNG, Illegal symbol/P-section name of [number of] chars.
to [number of] chars.

- not 1

NOEOM, Module "[name]" not terminated with EOM record
NOEPM, Module "[name]"
"[name]"

references

undefined

NONBTAB, Non blank/tab between continuation
record in "[file-spec]"

entry
and

mask

symbol

comment

end

than

NOMODS, No input modules specified (or found)
NOPSCTS, No P-sections defined in module "[name]"
NOSUCHMOD, Library "[name]" does not contain module "[name]"
NOTPSECT, Module "[name]"
P-section base

sets

relocation

base

other

NOVALU Values not allowed in qualifier - option file "[file-spec]"
NUDFSYMS, "[number]" undefined symbol(s)
NULFIL, Null parameter in option file "[file-spec]"

A-3

LINKER MESSAGES
NULPAR, Missing required parameter in option line (erroneous line]
file "(file-spec]"

OPIDERR, Pass [number] failed to open file "[file-spec]"
OPTREDERR, Read
error
"(file-spec]"

(code=%X[error

code])

OUTSIMG, Attempted store location %X[address]
(%X[base address] to %X[ending address])
•

"Region" is expressed
Symbol Table."

OVRALI, Module "[name]"
P-section "(name]"

has

either

conflicting

option

file

outside

"[region]"

"image

binary"

alignment

"Debug

overlayed

PARMDEL, Invalid parameter delimiter in option file "[file-spec]"
PRIMIN, Input parameter parse error, code = %X[error code]
PRIMOUT, Image file specification error, code = %X[error code]
PSCALI, Illegal P-section alignment [number of bytes] - exceeds a page
PSCNXR, Transfer address in "[module-name]" not in EXE/REL P-section
•

The transfer address is normally in a program section with the
executable and relocatable attributes.

PSCOVFLO, P-section "[name]" overflows region to %X[address]
RECLNG, File "[file-spec)" contains record of illegal length
of) bytes)

((number

RECTYP, File "[file-spec)" has an illegal record (type= [type code])
REDERR, Read failure in pass [number] on file "[file-spec]"
SECOUT, Map file specification error, code = %X[error code]
SEQNCE, Illegal record sequence
SHRINSYS, Shareable image(s) cannot be linked into a system image
STRLVL, LINK [version] does not implement OBJ level [structure
- only to [structure level]
•

level)

The version of the object language is not compatible with
current version of the linker.

STKOVFLO, Stack of [number of] pages falls
%X[address]

below

control

region

the
to

TFRSYS, Transfer address in system image "[file-spec]" ignored
TIRLNG, Module "[name]" has relocation
bytes) overflowing record
TIRNYI, TIR command [number
"[name]")

name]

A-4

commarid
not

yet

data

([number

implemented

of]

(module

LINKER MESSAGES
TRACIGN, Suppression of traceback overridden by DEBUG specification
•

Occurs when you specify /NOTRACEBACK and /DEBUG.

TRIOUT, Symbol table file specification error, code = %X[error code]
TRUNC, Trunc. error in module "[name]",
%X[hex value]
TRUNCDAT, Computed value=
value] at %X[address]

%X[hex

value],

UDEFPSC, Attempt to reference P-section
"[module name]"
•

P-section

no.

value

"[name]",

offset

written

%X[hex

[number]

undefined

Undefined program section

UDFSYM, "[symbol name]"
•

Undefined symbol

UNMCOD, Initial file name was "[file-spec]", RMS error code
code]

%X[error

UNRECOPT, Unrecognized option in file "[file-spec]"
UNRECQUAL, Unrecognized qualifier in option file "[file-spec]"
USEUNDEF, Module "[name]" references undefined symbol "[name]"
USRTFR, Image "[file-spec]" has no user transfer address
WRNERS, Module "[name]" has compilation warnings
WRTERR, Write failure on file "[file-spec]", code= %X[error code]
VALREQ, Value required in qualifier - option file "[file-spec]"

A-5

APPENDIX B

IMAGE MAP ILLUSTRATIONS

This appendix illustrates the brief, default, and full forms of a
of the same image.
In addition, after the full form of the map, a Symbol Cross
map section is illustrated.
The image map is described in Chapter 6.

B-1

map

Reference

:a
m
-n

3:
.,,
)Ii

1-1

DEMO

t'P
I
I\.)

Module Name
...........
DEMO
SUB1
FUNl
FUN2

Ide"t

01
01

.....
BytH

26•F!l•199S 11117
•........................•
I ObJeet Modu1• Sv"op111 &
•··•·····················•

.....
File

388 .DBBi1[GOLDMAN]DEMO,OBJ12
179 .oee21[GOLDMAN]SUB1,0BJJl
2l .oee21CGOLDMAN]FUN1,0BJJ1
23 .oee21tGOLOMAN]FUN2,0BJJ1

LINKER VH.41

,~;·

>
Cl
tlJ

.............
Cl'Htio" Date

26•,•b•1981 11116
l6•Feb•1980 11115
26•Feb•l981 11115
26•,•b•1980 11115

.......
Cl'tltol'

VAX•11 FORTRAN Tl,95•36
VAX•l1 FORTRAN Tl,95•36
VAX•11 FORTRAN t1,95•l6
VAX•ll FORTRAN tt,95•36

.,,>
1-1

t""
t""

::0

>
~

1-1

.oae21tGOLDMAN]DE~O.EXE11

26•FEB•1~80

+••··-··········-+
I Imege Svnoo1i1 I
+···---·-········+

Virtual memory a1located1
Stacie 1ize1
Image header virtual block 1imit11
Image binary virtual block 11m;tsl
Imag• name end identifications
Null'lber of f11ell
~umber of module1t
Number of program 1ection11
Number of global 1vmbol11
Number of image 1ection11
User transfer addre111
Debugger transfer addressl
I111aQ• tvoel
MaD formats
Est1mated mep lengtn1

°'
w
I

0001A7FF
2J, oage1

000002~0

DEl'IO 01

0001A6~0
(

(

1.INKEF' Vla2.'f0

Pao•

(108032, bvte1, 211. page•>

1. o1oclc)
3. b1oclc1)

o,
o.

270.
!,

....

~PIQl00oU

8¥'10"'0168

EXECUTABLE,

BRIEF in file ".OBB2:CGOlDHAN]DEM08R,MAPr2"

tSJ

8 1 blcck1

·-----·--·-······-····+
l Link Run St1ti1tte1 l
··-··-----·-···-·-····+

Performance Indicators

Pa;e Faults

---------------------Command oroce11ing1

-·-···---·17

Pass 11
A11ocat1on/Relocation1
Pus 21
Map data after object module synopsis:
Sy111t:>ol table outputs
Total ru,, value11

Using a work;ng set limited

10117

"'
....

CPU Time

EhPHd Th•

~16100100,

·-------·-··
00100108, 69

--·-···· 18

195

00100100,95

00&'110&Cll0, 11

00100100.10

°'4

00100101t1.00
00100100.02
00100101,56

27'4

l""'
l""'

tll

toi

::a

00100111e.11
00100106. 44
00100112.98
014100100.00
00100103.54
00101119,96

toi

t-t

0
2:
tll

'o 2"'2 pages and 49 01ge1 of data storage (excluding image)

Total number object records read Cboth oas1e1)1
183
of which 51 were in libraries and 8 were DEBUG data record• containing 189 bytes
1&9 bvte1 of DEBUG data ~ere written,1tarting at V8N 5 with 1 bloelc1 allocated
Number of modu1e1 extracted exolicitly
w1th 1 extracted to reaolve undefined aymbol1
0 library 1earche1 were for

1y~bol1

not in the library

A total of 0 global avmbol table record• wa1 wr1tten

/MAP20EHOBR/BRIEF DEMO,SUB1 1 FUN1,FUN2

m
:a

• 0
1earc~ed

.,,m3:

>
~

DEMO

26•,!1•1988 11111

............................

Module Nut

Idel'lt

DEMO

SU81

F'UN1

01
01

ll'UN2

P1ect N1111e

···-···---·
DEMO

SLOCAL.

OJ
I
it:=.

DEMO
SU81
FU1111
FU1112

SCODf.

....•........

.....

Cfttatto" Dtte

388 .oee21[GOL.OMAN]DEM0.08J,2
179 .oee21[GOLDMAN]SUBl,OBJ12
23 .DBB21[GOL.DMAN],UN1,0BJ'l
23 .oee21CGOL.OMANJll'UN2,08J,1

Modu 1e N1rne

···-····-SPDATA

ht11

' ObJ•et Modu1• SV"OPlil '
·~························
ll't le

DE.,.O
SUB1
FUN1
FUN2

....
8111

LINKER VH,41

26•,•b•l••• 1111•
2••,•b•1•11 11115
Z••'•b•l911 11115
26•Feb•l•le 19115

···············-···········+
l P~og~em Sectto" Sv"op1i1 I
+···························

...
End

L.1nath

·····-

00000200 0000020F 00000010
00000200 0000020F' 00000010
00000400 ~0000588 0000018C
00000400 00000533 00000134
00000534 00~00583 00000050
0000A584 0000~587 00000004
00000588 00000588 00000004
00000&00 000006CA 000000CB
00000&00 ~000063F 00000040
00000640 000006A2 00000063
000006A4 00000686 00030013
000A0b88 00000bCA 00000013

(
(
C
(
(
(
(
C
C
(
(
C

.....
a.)

16,)
396,)
398,)
80,)
4el
4,)
203.)
64.)
99,)
19.)
19.)

PIC1USR,CON,REL1LCL1

Velu1

DEMO

00000b00•R
000006A4•R
00000b88•R

FU~1

FUN2
SUB1

Symbol

00000b4'1J•R

Kev

fo~

apecte1 c"1r•ct1ra abovet

+••················+
l * • U"deff "td
& U • Univ•~••l

1
I R • ~e1oc1teble &
' WK - Week
'

+•·················+

V11ue

.,,

m
J>
c:
r-1

VAX•11 ,ORTRAN T1,95•3•
YAX•ll ,ORTRAN f 1,9S•36
VAX•l1 ,ORTRAN Tl,95•36
VAX•l1 ,ORTRAN tl,95•36

:s::
J>
~

Attl"fbutu

1-t

IHR,NOEXE,

RO,NOW~T,NOVEC

tll

PIC1USR1CON1REL.1LCL.,NOIHR,NOEXf1

RO,

WRT,NOVEC

"O
1-t

PIC1USR,CON,REL1LCL1

SHR,

EXE,

R0 1 NOWRT,NOYEC

t"'
t"'

t--3
::0

t--3

+···············••+
& Symbo11 Bv Name &
+••·············••+
Sv111bo1

~l"HtOI"

• ••••••

..........

A1fg"

LONG 2
LONG 2
L.ONG 2
L.ONG 2
LONG 2
L.ONG 2
L.ONG 2
LONG 2
LONG 2
LONG 2
LONG 2
L.ONG 2

Page

1-t

Svmbo1

Ve1ue

......
SVmbo1

V•1ue

·····

.oee21[GOLOMAN]DE~O.EXEJ2

Virtu11 memory 111oceted1
St1clc 1ize1
Image hetder v1rtu•1 bloclc 1imit11
Im•o• binarv virtual block 11mit11
Im•g• n1me and 1dentific•t1onl
Number of f11eu
Number of module11
Number of oroor•m. 1eetion11
Number of g1ob•1 1vmbol11
Number of 1m1;e 1ection11
U1er tr•~•fer 1ddre111
Debugger tr1n1fer 1ddresa1
I1T1a9e tvPel
Mao formats
Eatimeted map length&

2o•FEB•1980 10118

+·················
1 Imt;e Svnoo111 I
+••··············+

U"I

Pt;e

00000200 0001A7FF 0001Ao00 (108032. bytea, 211. oa;ea)
20. p1ge1
.
1.
1. C
1. block)
2.
4. C
3. blockal
D~MQ

o.
o,
e.

27&,

'110000&00

80121001&8

)II

EXECUTA8LE,
DEFAULT 1n file

"~DB821[GOLDMAN]DEMOOEF.MAPJ2•

33, blocka

+-----------------·--·+
l Link Run St1t11tica l
+--------------------··

t:P
I

LINKER ve2.4e

Performance Ind1c1tor1

P1ge F1ulta

---------------------Commtnd eroceaaing1

----------21

P1aa 11
A11oc1tion/Reloc1tion1
Paa• 21
M1p d1t• efte~ object module svnops411
Svmbo1 t1bl• outputs
Tote1 run v1luea1

20&
15
30
11

7
2q0

.,,>3:
H

CPU Time

Elaoud Time

00H'l0UH~,09

----····---·
0011iHOl0&,84

--------

0111100101,02
00100100,08
00100100.15
0010010.0,07
00100100,02
00Hl0101,&3

t'"'
t'"'

t-i
::0

90100150, 70

00U0104, 70-

00UHIZ0,22
00100103.82
0011110101.20

H101ai7.48

Using 1 working set 11mit•d to 242 peQe1 1nd 4q 010•1 of d1ta 1tor1ge (excluding image)
Total number obJect ~•cords read (bot" P•••es)t
183
of which 51 were in 11b~arfea 1nd 8 were DEBUG date record• cont11nfng 189 bytes
1o9 bvte1 of DEBUG dat1 were wr1tten,start1no et VBN 5 wit~ 1 blocks •llocated
Number of module• extracted e•Plicitly
with 1 extr•cted to re•olv• undefined avmbola
0 11brarv 1eerche1 we~e for aymbola not

the librarv aeerched

A tot•1 of 0 g1oba1 avmbo1 table record• w1s
/MAP•DEMODEF DEM0 1 SUB11FUN1 1 FUN2

w~1tte"

m
"Tl

c>
r-

-t

.,,>

-n
rr3::
l>

.,,
DEMO

Module N1me

·····-----·
DEMO
CJ
I

SUB1
FUN1
FUN2
SYSVECTOR
VMSRTL

2&•FEB•1qe0 10120

+•····-·······-··········+
I Object Module Svnopaia I
+-·-···----····-··-······+

·---I dent

01
01
0219
•EXE '1

Bvte1

-·-··388 .oee21[GOL.DHAN]DEMO.OBJ,2
·---·
F fl•

17q .DBB21[GOLOMAN]SU81 1 0BJs2
23 .ose21[GOLOMAN]FUN1.08Js1
23 ~OBB21[GOLOMAN]FUN2 1 0BJs1
~ .ORA51(SYSLIBJSTARLET.OLBs1
0 .DRASa[SVSLIBJVMSRTL.EXErl

L.INl<ER

vaz.u

Peoe
t-4

.......
···-·-··---··
2b•Feb•1980 10116 VAX•11 FORTRAN T1,95•3b
Cre et ton Dete

2&•Feb•198e 10115
26•FeD•l980 10115
2&•Feb•l980 10115
19•FEB•198B 21159
20•FE8•1980 18155

Creetor

VAX•11
VAX•ll
VAX•11
VAX•11

FORTRAN Tt,95•36
FORTRAN T1.95•3b
FORTRAN T1,95•3&
MICl'O V02e41
L.1~1<•32 V02.l9

tll

>
"O
t-4

C""
C""

cti)

..;
::0

>
..;
t-4

ti)

1-4

_oss21[GOLDMANJDEMO,EXEr3

2o•FEB•1qe0 10120

+··--------·--·-·-----··-+
1
Sv"oP111 1
+•····-··················+
l~•ge

C1u1tel"

°'
I

.....J

···----

DEFAULT.CLUSTER

VHSRTL

Base Addi" Dflk VBN PFC p,.otectio" •"d Pegi~g
kililld0fd20'1

1
1

~"11000400

253

1!'101iHl0600
7FFF08krn

11
1q3

0000080t1

~001U00

00001~0(;!1

"
~

)II

Cl
tZJ

Seet1o~

---- ----- ··-·----- ------·· --· ····--------·········
Type P•ges

Page

LINKER V02,40

Glob•l Sec, N•me

·········---··-·

0 READ ONLY
0 READ WRITE
COPY ON REI'
0 READ ONLY
0 READ WRITE DEMAND ZERO
1 READ ONLY
0 READ ONLY
~ READ WRITE

H•Jo,.f d

Mil'I0,.1d

1-4

t"'
t"'

ti>
~

VMSRTL.H1

COPY ON REF

)II

..... ······· .......
Matel"I

VMSRTL.H2
VMSRTL ...Hl

LESS/EQUAL
LESS/EQUAL
LESS/EQUAL

1
1
1

"
)II
~
1-4

20011

2008
2000

ti>

"11

c:
r
r

3:
>
-a

.,,

c
rr3:
)>
-a
.ose21CGOLDMAN]DE~O.EXEr3

26•FEB•1980 10120

•··························•
I P,og,em Sectio" Sv"opaf I
+••·························

L.INl<!R VU.41

Peoe

P11ct Nerne

Module Nerne

·-·-·······

SPOATA
DEMO
SUBl
FUN1
FUN2
OJ
I
CX>

SLOCAI.
DEMO
SU81
FUN1
FUN2

SCOOE

DEMO
SUB1
FUN1
FUN2

• BLAN!\ •

SYSVECTOR

ea••
....
0~0002~0

000~0200
0~000210
~0000210
0000~21~

E"d

··-

-----Lt"Qt~

0000020F 00000010 C
0000020F 0000~010 C
00000210 00000000 c
~000~210 00000000 (
0000~21~ 00000000 (

00000~0~
0000A4~0

00000sea 000001ec

00000530

~0000583
~0000587

0~00058Q
0000~588

00000533 0~000134

c
C

00000050 (
~0000004 (
00000588 00000004 c

0~000b00

00~00&CA 00000~CB C
0000063F 00000040 C

0000064~

00~00642

00000b0~

0000~063

Vi0000666 00000·013 C
000~0bB8 00~00oCA 00000013 C

0tH!01dbU

0~~~~800
00~e0s00

00000~00
00~e0e00

00000000 c
00000000 c

A1 f gl'I

----16e)
lo.)
0.)
0.)
0.)

LONli 2
1,.0NG 2
L.ONG 2
LONG 2
L.ONli 2

396.) L.ONG 2
308.l LONG 2
80.) L.ONG 2
4.) LONG 2
4el LONG 2
203.)
b4e)
99.)
19.)
19.)

LONG 2
LONG 2
L.ONG 2
LONG 2
LONG 2

Attf"ibut11
••.....•..
PIC1USRrCON1REL1LCL1

SHR,NO!XE,

RO,NO~RT,NO\IEC

t:IJ

.,,>'
PICrUSR1CON,REL1LCL1NOSHR,NOEXE1

RO,

lilRT,NOVEC

....
t""
t""

tll
~

:a
PIC1USR,CON,REL1LCL1

St-IR 1

0.) BYTE 0 NOPIC,uSR,CON1REL1LCL1NOSMR,
0.) BYTE 0

t-t

>
Cl

EXE,

to«D, NOWFH, NOV EC

>
~

....

0
2S

tll

EXE,

RD,

lil~T,NOV~C

....
,,.DBB21lGOL.DMAN]DE~O.EXEJl

......
BASSSBL.Nl<,.L I NE ----000013A0•RU
Syll'lbo1

tD
I
\.0

BASSSCB,,.GET
BASSSCB.POP

BASSINIT,,.R8
BASS INPUT
BASUNPUT ,,.L.INE

26•FEB•1980 10120

+•··-··---········+
I Symbols By N•~• l
····----·····-·--·+

------

llel ue

Syrnbol

00001l80•RU
1210001370•RU

BASSINSTR
BASSIN..,D,,.R
BASSIN..,F ,,.R

00001118•RU

·---Ve1ue

Sv111bol

l110001080•RU
000011F0•RU
000011E8•RU

000~11A0•RU

BASSRSET ...R
BASSSCALE..,,D..,,Rt

0001iH 078•RU

00001P.A.0•RU

000~1160•RU

BASSSCRATC:H

000"1308•RU

····-·

BASSSTA.TUS
BASSSTR,..D
BASSSTR,,.F
DEMO •
FORSSCB,,.GET
FORSSCB,,.POP

Pege

L.INKER '102.40

.....
Velue

00001ll8•RU
001iHH0C0•RU
Hlil010Be•RU

•
0000061i.!0•R

00000E20•RU
00000E10•RU

......

Cl
tzl

.,,>3

......

Symbol

Velue

....

FORSSCB..,PUSH
0001110E08•RU
FORSSCB..,RET
~00~0E18•RU
FORllERRSNS,,.SAV 00000E28•RU

FORSIO~B.i.R

FORSIO,,.B,,.V
FORSio.oc..,R

t""
t""

Cf)

1-i

::a
>

1-i

....

01ihl008E0•RU
000008E8•RU
00000928•RU

Cf)

"'T1

r
r

31:

,,
)>

-n
c

rr
3:
J>

-a

....
31:

... ose21CGOLUMAN]DEMO.EXEr3

......
°'......
I

2o•FEB•1980 10120

Pege

LINKER v02.~0

Symbol

Value

Svmbol

Velue

S';'mbo1

Value

A0090E312l•RU

FUNt

H000U4•A

MTHUSI N...R5

~'lH:1008C0•RU

FUN?

01iUl00ft88•R

MTHUU~

800l!li!IU0•RU
eeeeUU•RU

OTSSCVT... L..TZ
OTSSCVT.., TI~L

SH8U1B•RU

Symbol

Velue

FORs10 ... oc ... v
FORSIO ... D._R

····-

fd'hHttHEA0•RU

t'ZJ

31:

....""

t"'
t"'

'90000640•R

SYSSIMGSTA

8011100108

SUBt

">....
~

.oea21LGOLDMAN]DEMO.EXEJl

2b•FE8•1980 10120

+••··-····-----····+
I Symbols By Value I
+-----·-··---·-····+

00000&40
0000VJ&U

00000&88

°'......
I

0000k'800

000008148

•.....•..•

R•OEMO
R•SUB1

tzJ

R•FUN1

R•FUN2

""'

RU•FO~SCLOSE
RU•FORSDECOOE~MF

......

•
800001&8

P~CI•

Sy111bo1••••

Value
H000b00

LINKER YH,41

r'1
r'1

,,>'m
"i

SYS$If'IGST4

"i
H

Kev fo,. special eha,.aetel"s above:

+··---·-----·······+
•
• Ur"ldefi,,ed
u

£ R

• Ul"l111e1"1a1
• Reloeetable

1 ~K • Weak

+•··--·-··---------+

.,,

c:
rr-

3::

.,,
>

.oee21CGOLDMANJDEMO,EXEs3

26•~EB•1980

+•···············+
1 Im•Qe SV"OPlil 1
•················•

Vtrtu11 memory 111oc1ted1
Shclc If HI
Im1ge header vtrtu11 block 1tm1t11
Imig• bf"1rv vf rtu•l block ltmtt11
Imig• "1me 1"d tde"tific1tton1
Number of filell
Number of modu1e11
Number of program 1ection11
Number of g1ob•1 1vmbol11
Number of tm1ge 11ctto"11
U1er tren1fer 1ddre111
Debugger transfer 1ddre111
lm1ge type&
M1p form1t1
E1ttm1ted mac lengths

10120

LINKER VH,41

00000200 0B01A7FF 0001A600 (108032, byte11 211, p1ge1)

20, PIQ81
1.
2.

DEMO 01

1, (
4, (

.....

!\.)

00000600
80000108

EXECUTABLE,
FULL in ft1e " 4 08B21CGOLDMAN]DEMOFULL,MAPJ2"
se. b1oc1c1

+··-··---------·--····+
l Link Run St1tt1ttc1 1
Paoe F1ult1

P111 11

E11,,,sed Time

259
72
&9
91

00100101.15
0"' 11110100, 30

8
51&

00100100,'113

00100133,31
00100104.07

001Q!010l,92

00101130,93

00100&'110,

~0100100,11

001001'51.98

··--·-······
00100 us. rn
00100121.u
00100101, o5
00100113,22

P1ge1 of d•t• 1tor1ge Cexcludtng im1ge)

Tote1 "umber object records reed Cboth ~11se1)1
183
of which 51 were in ltbr1rfe1 1nd e were DEBUG date records co"t1tnf"9 189 bytes
1&9 bvte1 of DEBUG d1t1 wel"e wrftten11tertfno et VBN 5 wfth 1 bloek1 1lloc1ted
Number of module• extl"•cted ••o11ctt1v
with 1 extr1cted to reaolve undefined 1vmbol1

•

not in the lfbr•rv 1earched

A tot•l of 0 glob•l 1ymbol t1ble records w11 written
/MAPsDEMOFULL/FULL

DE~O,SUB1,FUN1,FUN2

~
tZJ

·-··-··· 15

1vno~1t1:

Uatng 1 wor~tng set limited to 217 oeges and

CPU The

....
3

··-·····--17

Alloc1tion/Reloc1t~on1

1v~bol1

276,

--····----------·-····
Comm1nd proces1ing1

0 ltb,.erv ae1rche1 were for

..,,
.-.c:

••••
e.

Perform1nce Indic1tor1

Pan 21
Map d1t1 after object module
Sv1T1bol table outputs
Totel ""U" v1lue11

.,,

1. b1oclc)
1. b1octc1l

+····--·~·····-··-·-··+
to
I

fl•Gt

>
ta
1-4

C""'
C""'

tll
~

::0

>
~

1-4

tll

.oae21tGOLDMANJOEMO,EXEr4

......
Svmbo1

8ASSSBLNl<.LINE
BASSSCB... GET
I

•

DEMO •

°'......
I

FORSSCB ... GET
FORSSCB..,POP

•
•
FUN1
FUN2

•
•
•
SUB1

SYSUMGSU

.....
Value

26•,EB•1990 13111

+•························
I Svmbo1 Cro11 Refer•"c• I
+••··-··-················+
Defil'led Bv

0H013A0•RU

LINKER YH,48

'•;•

Refere"c•d By •••

.....

···-····-········

00001380•RU

•
•
00000600•R
00000E20•RU

00000E10•RU

.•

000006A4•R
00000688•R

00000640•R
80000168

tSJ

>
"O

DEMO
VMSRTL
VMS RTL

FU"41
FUN2

SU81
SYSVECTOR

tn
SUB1
SU81

DE~O

<
3:
m
0
r
0

:a
0

tn
tn

m
m
:a
m
z
0
m

-n

.....

t""'
t""'

ti>

ti
::0

)If

1-t

ti>

APPENDIX C
VAX-11 OBJECT LANGUAGE

The object language description in this appendix is taken from DIGITAL
software specifications. This appendix is useful for anyone writing a
compiler or assembler that must generate object modules acceptable for
input to the VAX-11 Linker.
The object module analysis program
(ANALYZE), discussed in Appendix D, checks an object module to see if
it
conforms
to
the
requirements
in
the
DIGITAL software
specifications.

C.l

INTRODUCTION

The VAX-11 object language is accepted by VAX-11
module librarians, and object patch utilities.

linkers,

object

The object language described herein is for use by all VAX-11 family
software -- that
is,
no
subsetting will occur.
All language
processors that produce code for execution in native mode are free to
use any or all of the described object language.

C.1.1

Summary of Language

Object modules are the input to the linker and are obtained from the
various language processors as individual files or as object library
files. All symbol table files created by the linker are also in the
format specified here.
An object module consists of an ordered set of
records, of which the following types are defined:

variable-length

OBJ$C HDR

0 - Header Record (HDR)

OBJ$C GSD

OBJ$C TIR

2 - Text Information and Relocation Record

OBJ$C EOM

3 -

OBJ$C_DBG = 4

Global Symbol Directory Record (GSD)
(TIR)

End of Module Record (EOM)
Debugger Information Record (DBG)

OBJ$C TBT

5 - Traceback Information Record

(TBT)

OBJ$C_LNK

n - Link Option Specification Record (LNK) (Currently
ignored)

Refer to Figure C-1 for an illustration of the order in which
appear in the object module.

C-1

records

VAX-11 OBJECT LANGUAGE

MHD

Module Header Record

GSD

Global Symbol Directory Record

TIR

Text Information and Relocation

TIR

Records

GSD

Additional Global Symbol Directory

..
.
DBG

Debugger Information Record

TBT

Traceback Information Record

TIR

More Text Information and Relocation

GSD

More global symbol information

TIR

More text

EOM

End of Module

Figure C-1

Order of Records Within an Object Module

It is mandatory that there be at least two HDR records, a Module
Header Record (MHD) and a Language Name Record (LNM), and exactly one
EOM Record.
These records must begin
and
end
the
module,
respectively.
Within the module, there must be at least one GSD
record and there may be any number of TIR, DBG, TBT and LNK records.
As is described below, some ordering is implicit within the set of GSD
records.
In this document, the term "reserved" implies that the item must not
be present because it is reserved for possible future use by the
linker and DIGITAL. The linker produces an error if a reserved item
is found in an object module.
All unused and ignored fields of records must be padded to conform to
the block lengths specified in this document. The content of such
fields will be completely ignored by the linker and any other
processors.
The remaining possible language record types are allocated as
but not defined in this document:
Type 7-100

Reserved for future use by linker

Type 101-200

Ignored always

Type 201-255

Reserved for customer use
(Ignored by current implementation)

C-2

follows

VAX-11 OBJECT LANG'UAGE
C.2

GLOBAL AND UNIVERSAL SYMBOLS AND NAME FORMAT

The linker deals with two types of symbols, global and universal.
Global symbols are those that are accessible to more than one module
of the set being linked. Universal symbols are a subset of the global
symbols. They are ones that the linker retains when linking an image
to which another set of object modules and/or images will subsequently
be bound.
The Object Language also deals with the names of program sections and
object modules and may contain the names of language processors and
utilities.
All names are represented by a !-byte character count followed by
ASCII character string.

the

The current implementation of the linker limits such name strings to
31 characters, except in the case of header record types 1-255 (see
Section C.3.2).

C.3

HEADER RECORDS (HOR)

The object language defines a general class of header records.
Module Header Record (MHD) is described in Section C.3.1.
The Language Name Record and the remaining header types are
in Section C.3.2.

C.3.1

The

described

Module Header Records (MHD)

The module header records (MHD) collect in one place all module-wide
information.
The module header records are needed by the librarian
and patch utilities and permit future expansion of the object
language.
The MHD (Module Header Record)
information in the format shown:

record

contains

RECORD TYPE 0

1 byte

HEADER TYPE 0

1 byte

STRUCTURE LEVEL

1 byte

MAXIMUM RECORD
SIZE

2 bytes

MODULE NAME

Variable (2-32)

MODULE VERSION

Variable (2-32)

CREATION TIME
AND DATE

17 bytes

TIME AND DATE
OF LAST PATCH

17 bytes

C-3

the

following

VAX-11 OBJECT LANGUAGE

All entries are required.

C.3.1.1

Detailed descriptions of the fields follow.

Header Type - The MHD header type is 0 (OBJ$C_HDR_MHD).

C.3.1.2 Structure Level OBJ$C STRLVL - It is intended that the format
of the MHD record remain fixed from first implementation onward. The
structure level is provided such that extensions to the language,
which require changes to other record formats, can be dealt with
without requiring recompilation of every module that conforms to the
previous format. The structure level is zero.

C.3.1.3 Maximum Record Size OBJ$C MAXRECSIZ - The size in bytes of
the longest record that can occur within this object module. The
maximum size is 2048 bytes.

C.3.1.4 Module Name - The module name conforms to the format of all
other names, that is, length contained in a byte followed by an ASCII
string. If the module is a symbol table created by the linker, the
name will be the image name assigned at link time.

C.3.1.5 Module Version - The module version conforms to the format of
all names in the object language.

C.3.1.6 Dates and Times - There are two date and time fields, one for
module creation and one for the last modification to the module (by an
object module patch utility). The format is a fixed 17-character
ASCII string:
dd-mmm-yyyy hh:mm
where:
dd = day of month
mmm = standard 3-character abbreviatidn of month
yyyy

= year; note the space that follows

hour of day 00 to 23

mm = minute of hour 00 to 59

C-4

VAX-11 OBJECT LANGUAGE

C.3.2

Other Header Records

The purpose of subheader records is primarily to contain optional
textual information in printable form. Each record consists of a byte
which is zero to indicate a header record, followed by a subtype byte.
The following subtypes are defined.
OBJ$C HDR LNM = 1

Language Processor (LNM) Name and Version.
One record is required and limited for the
current implementation to 35 characters. The
content of this record appears on the link
map output.

OBJ$C HDR SRC

List of file-specifications for the source
files from which object module was created.
Multiple records are permitted.
(Currently
ignored)

OBJ$C HDR TTL

Title text (e.g., brief module description).
Only
one
record
permitted.
(Currently
ignored)

OBJ$C_HDR_CPR

A copyright statement.
Only
permitted.
(Currently ignored)

one

record

OBJ$C HDR MTC

Maintenance Status.
(MTC) Multiple
permitted.
(Currently ignored)

records

OBJ$C HDR GTX

General Text.
Multiple
(Currently ignored)

records

permitted.

Types 7-100 are reserved.
Types 101-255 are always ignored.

C.3.2.1 Header Types l through 4 and 6 - The purpose of these records
is to allow the language processors to provide printable information
within the object modules for documentation purposes. The only format
definition is that the record contain printing ASCII characters.
Types 4 and 6 may be generated by users, whereas types 1 through 3 are
restricted to the language processors.

C.3.2.2 Maintenance Status Header Record (MTC) - This record is of
concern only to the object module patch utility and the object module
analysis (ANALYZE) utility (see Appendix D). It is ignored by the
librarian and the linker.

C-5

VAX-11 OBJECT LANGUAGE

The format is as follows:
RECORD TYPE

HEADER TYPE

1 byte
1 byte

··- ><-----·--·

PATCH
UTILITY NAME

____,

UTILITY
VERSION

______,

UIC

variable
2-32 bytes
variable
2-32 bytes
2 bytes

------···---··-···---!

INPUT FILE
SPECIFICATION

----

variable
2-42 bytes

CORRECTION FILE
SPECIFICATION

variable
2-42 bytes

DATE + TIME

17 bytes

SEQUENTIAL PATCH

1 byte

-¥-••-~

.,,,.-~

...___,.._,, ___.. -

A ••••• _ _ _ _ . _

C.3.2.2.1

Record Type - Zero signifies a header record.

C.3.2.2.2

Header Type - The type is 5 signifying a maintenance status

record.

Patch Utility Name - This name identifies the patch utility
used to perform this patch on the module. This field begins with one
byte containing the number of bytes in the field
(not including the
count byte itself).

c.3.2.2.3

Utility Version - The patch utility is further identified
by its version number. This field begins with one byte containing the
number of bytes in the field (not including the count byte itself).

C.3.2.2.4

C.3.2.2.5

U.I.C. - This is the user identification code

under

which

the patch was made.

Input File Specification - This filename identifies the
input file for this patch. This field begins with one byte containing
the number of bytes in the field
(not including the count byte
itself).

C.3.2.2.6

C-6

VAX-11 OBJECT LANGUAGE
C.3.2.2.7 Correction File Specification - This filename
identifies
the correction file for this patch. This field begins with one byte
containing the number of bytes in the field (not including the count
byte itself) •

C.3.2.2.8 Date & Time - This 17-byte field contains the date and time
that this patch was performed.
Format is as described above.

C.3.2.2.9 Sequential Patch Number - This number is a sequential count
of the patches made to this module.

C.4

GLOBAL SYMBOL DIRECTORY (GSD) RECORDS (OBJ$C_GSD)

Global symbol directory records contain all the information necessary
to allocate virtual address space and to combine all the program
sections into the separately protectable sections (image sections)
of
the image being created.
GSD records are of the following types:
OBJ$C GSD PSC
OBJ$C-GSD-SYM
OBJ$C-GSD-EPM

0
1
2

OBJ$C GSD PRO

Program section definition.
Global Symbol Specification.
Entry Point Symbol and Mask
Definition.
Procedure and Formal Argument
Definition.

Within any GSD record, there may be many entry types.
In such cases,
a single record appears as the concatenation of many, with the
omission of the byte containing the Object Language record type
(the
value OBJ$C_GSD).

C.4.1

Program Section Definition (OBJ$C_GSD_PSC)

The format of a program section definition is as follows:
RECORD TYPE 1

1 byte

GSD TYPE 0

1 byte

ALIGNMENT

1 byte

FLAGS

2 bytes

ALLOCATION

4 bytes

PROGRAM SECTION
NAME

Variable
2-32 bytes

C-7

VAX-11 OBJECT LANGUAGE
C.4.1.1 Program Section Name - This name has the same format
other symbol names.

all

C.4.1.2 Alignment - This field specifies the virtual address boundary
at which the program section will be placed. The alignment is 2 to
the power specified in the field.
Value

Alignment
1
2
4

1
2

(BYTE)
(WORD)
(LONGWORD)
(QUADWORD)

3
4

2** 9 (PAGE)

2**4

Nine indicates page alignment and is the
alignment.

limit

for

program

section

Each module contributing to a program section can specify its own
local alignment, with the restriction that program sections whose
contributions overlay each other must all have the same alignment. It
should also be noted that an alignment specified within a program
section (for example, the assembler .ALIGN directive) must be less
than or equal to the program section alignment to be guaranteed. For
example, byte alignment of the program section may or may not cause
longword aligned elements within the program section.

C.4.1.3 Flags - The flag bits in the program section definition
the following meaning:

have

Bit

Name

GPS$V PIC

Program
section
independent.

GPS$V LIB

The program section was defined in the symbol
table of a shareable image, to which thi~
image is bound.

GPS$V OVL

Contributions to the same program section are
overlaid.
(The complement is concatenation).

GPS$V REL

Program section requires relocation
(th~
complement,
bit=O,
means
absolute
and
contains only symbol definitions.
Thus the
allocation of an absolute program section is
zero) •

GPS$V GBL

The scope of program section is global.
complement is local).

GPS$V SHR

Program section is potentially
shareable
between two or more active processes.

GPS$V EXE

Content of the program section is executable.

Meaning If Set

C-8

defined

position

(The

VAX-11 OBJECT LANGUAGE
Bit

Name

GPS$V_RD

Content of the program section may be read.

GPS$V WRT

Content of
written.

GPS$V_VEC

Program section contains change mode dispatch
vectors.

10-15

Meaning If Set

the

program

section

may

Reserved.

Discussions of program section attributes may be found in the
documents.
(See also Section 7.5.4 of this manual.)

C.4.1.4 Allocation Field - The allocation field contains the length
contribution to the program section in bytes. It must be zero for an
absolute program section.
Program sections are assigned an identifying sequence number as their
respective GSD records are encountered. The program section number
ranges from 0 through 255 within any single module.
Note, however,
that the total number of program sections in a single link operation
is bounded only by the linker's virtual memory requirements.
This
program section number is used as an index in all references to the
program section. Note that this permits any mixture of GSD records,
as long as program sections are defined to the linker in the same
order as the index used by symbol definitions.

C.4.2

Global Symbol Specification OBJ$C_GSD_SYM

Global symbol specification records may appear
MHD and EOM records and in any order.

anywhere

between

the

The format of a global symbol specification is as follows:
RECORD TYPE 1

l byte

GSDTYPE l

l byte

DATA TYPE l

l byte

FLAGS

2 bytes

PSECT INDEX

l byte

VALUE

4 bytes

SYMBOL
NAME

Variable
2-32 bytes

The 5 bytes for PSECT INDEX and VALUE
(that is, when SYM$V_DEF=O).

C-9

are

omitted

for

reference.

VAX-11 OBJECT LANGUAGE
C.4.2.1 Data Type - The data type record is encoded as
Appendix c of the VAX-11 Arch i t~gt'=!_re J!.~ngJ?_Q.ok.

described

NOTE
The current implementation of the linker
ignores the data type field.

C.4.2.2 Flags - The flag bits in the global symbol specification have
the following meaning:
Bit

Name

Use

GSY$V WEAK

O for strong resolution.
1 for weak resolution.
Table C-1 describes the use of GSY$V WEAK
in conjunction with the definition- bit
(GSY$V_DEF).

GSY$V DEF

O for reference
1 for definition

GSY$V UNI

O for within facility
1 for universal symbol
This bit is
significant
only
on
a
definition.
It indicates the symbol is to
be retained if this facility is shareable.

GSY$V REL

0 for absolute symbol value
1 for

relative symbol and the value
is
augmented by the indexed program section
base
address
(of
this
module's
contribution)

4-15

Reserved.
Table C-1
Interpretation of GSY$V WEAK and GSY$V DEF

GSY$V_WEAK

GSY$V DEF

Interpretation

Strong Reference -- symbol
resolved

Weak Reference -- resolved only if the
symbol is defined for some reason
other than this reference.
Does not
incur any searches or module loads.
Has the value zero if undefined, with
no error report.

Strong Definition
remains
required symbol tables/maps.

Weak Definition -- is discarded from
all symbol tables/maps unless there
was a reference. Does not appear in
the global symbol table index of an
object module library.

C-10

must

all

VAX-11 OBJECT LANGUAGE
C.4.2.3 Program Section Index - The program section index is a number
between 0 and 255 to be used as an index into the sequence of program
section definition records.
This field exists only for symbol
definition records (GSY$V DEF=l) and identifies the program section in
which the symbol was defined. The index is also used in TIR commands
(see Section C.5.1.1) for reference to program section base addresses.
All symbols encountered must be defined within a program section,
independently of the relocatability of program sections or symbols.
For example, the linker does not require the base address of the
"owning" program section if the symbol is absolute. However, for the
purposes of generating a readable map, it is very useful to maintain
the hierarchy of symbol within program section within module within
file.
C.4.2.4 Value - This field contains the value assigned to the symbol
by the language processor. This field does not exist if the record is
a symbol reference (GSY$V_DEF=O).

C.4.3

Entry Point Symbol and Mask Definition (OBJ$C_GSD_EPM)

This format is an extended version of the global symbol definition
format above.
Following the symbol value (which will be an entry
point address) is a two-byte field for the procedure's register save
mask (as used by CALL instructions). The format is as shown below.
RECORD TYPE 3

1 byte

! - - - - - - - - - - · ---·-

GSD TYPE 2

1 byte

DATA TYPE

1 byte

FLAGS

2 bytes

PSECT INDEX

1 byte

VALUE

4 bytes

ENTRY MASK

2 bytes

SYMBOL
NAME

variable
2-32 bytes

C.4.3.1 Entry Mask - The entry mask is written at the entry point of
a procedure entered via a CALLS or CALLG instruction, and in some
cases also is used in transfer vectors to such procedures.
A TIR
command (see Section C.5) is provided for the language processor to
direct the linker to insert the mask at the procedure entry point or
at the transfer vector.

C.4.4

Procedure with Formal Argument Definiton (OBJ$C_GSD_PRO)

This GSD format is an extension of the entry point and mask definition
format to define the formal arguments of the procedure. The format is
as shown below.

C-11

VAX-11 OBJECT LANGUAGE

RECORD TYPE l

GSD TYPE 3

1 byte

DATA TYPE

1 byte

FLAGS

2 bytes

PSECT INDEX

1 byte

VALUE

4 bytes

ENTRY MASK

2 bytes

SYMBOL
NAME

variable
2-32 bytes

MINIMUM ACTUAL
ARGUMENTS

1 byte

MAXIMUM ACTUAL
ARGUMENTS

1 byte

byte

FORMAL ARG l
DESCRIPTOR

variable length
(2-256 byte)
descriptors of
formal arguments
arg n is optionally
function return
value.

FORMAL ARG n
DESCRIPTOR

Following is a description of the fields of a procedure definition
different from the fields described in the other types of GSD records.

C.4.4.1 Minimum and Maximum Actual Argument Counts - Permissible
values are O through 255 and specify, respectively, the minimum number
and the maximum number of arguments required for a valid call to this
procedure.
The counts must include the function return value if such
exists.
The current implementation does not validate
procedure
calls.
However, for its own integrity, the current implementation validates
that the minimum number of actuals is less than or equal to the
maximum number of arguments. The maximum number of actuals field is
then used to process the formal argument descriptors.

C-12

VAX-11 OBJECT LANGUAGE

C.4.4.2 Formal Argument Descriptors - Each of the formal argument
descriptors of the record shown above has the following format:
ARG. VAL. CTL.

1 byte ARG$B VALCTL

REM. BYTE CNT.

1 byte ARG$B BYTECNT

DETAILED
ARGUMENT
DESCRIPTION

variable
0-255 bytes
ignored by current
implementation

C.4.4J2.l Argument Validation Control Byte - This (the first) byte of
each formal description is used to control the validation of the
argument. The only field of this control byte used by the linker is
as follows:
Bits 0:1

ARG$V_PASSMECH

- Describes the mechanism by which the
argument of a valid call must be passed.

Bits 2:7

Reserved

- Ignored by the current implementation.

The following argument-passing mechanisms are defined:
ARG$K UNKNOWN
ARG$K-VALUE
ARG$K-REF
ARG$()ESC

O Unspecified
By value
2 By reference
= 3 By descriptor

= 1

C.4.4.2.2 Remaining Byte Count - This field gives the length of the
current
remainder
of
this
argument
descriptor.
For
the
implementation, it is used as a count of bytes to be ignored by the
linker. The content of these remaining bytes is reserved for possible
future implementations.
NOTE
Any use of formal
in which
ARG $B _ VALCTL

argument
bi ts 2: 7

descriptors
NE_Q 0

and/or
ARG$B BYTECNT

NEQ 0

means that, should argument validation
be
implemented
in a future VAX-11
Linker, recompilation
of
all
such
objects may be necessary.

C-13

VAX-11 OBJECT LANGUAGE
C.5

TEXT INFORMATION AND RELOCATION (TIR) RECORDS {OBJ$C_TIR)

Text information and relocation records contain a sequential series of
commands and data for the linker to compute and record the contents of
the image. The general form of a TIR record is as follows:

C.5.1

RECORD TYPE 2

1 byte

COMMAND 1

1 byte

DATA 1

Byte count implied by command

COMMAND 2

1 byte

DATA 2

Byte count implied by command

COMMAND N

1 byte

DATA N

Byte count implied by command

Commands

The linker's creation of the binary content of an image file is
completely driven by the language processor via the commands contained
in TIR records. To achieve this, the linker maintains an internal
stack.
The commands available allow values to be placed on the stack and
operations to be performed on the items on top of the stack. These
commands also permit the writing of values from the stack to the
output image.
Other commands permit the storing of a sequence of
bytes from object module to output image without alteration by the
linker.
They also provide for control of the relocation of the
position currently being written in the image.
In commands which refer to program sections, the names are identified
by the sequence numbers assigned to them as described above. The
program section indexes are in the range O through 255.
The command byte has two formats:
7 6

FORMAT

l~1__,__l_ _-_co_u~~-~.•..... J
7 6

FORMAT 2

C-14

VAX-11 OBJECT LANGUAGE

The only command with FORMAT 1 is the Store Immediate (STOIM), which
merely causes the copying of the following bytes (given by the
negative count in the range -1 through -128J into the output image.
All other commands are described by the second format.
groups of commands:

There are four

Stack Group
Store Group
Operator Group
Control Group
The stack on which these commands operate is longword aligned at all
times. Furthermore, it must be completely collapsed at end of module,
but is retained between all other record types.
The minimum stack
space available will be not less than 25 longwords.

C.5.1.1 Stack Group - The stack group of commands provides the
capability to store bytes, words, and longwords on the stack. The
value placed on the stack may follow the command in the TIR record;
it may be found from a global symbol; or it may be computed from the
base address of a program section. Except for stacking the value of
global
symbols
or stacking addresses
(calculated from program
sections), both signed extension to longword and zero extension to
longword are provided for byte and word stack operations. The codes
in the following list are decimal.
Code

Command

Stack Global
(TIR$C_STA_GBL)

Description/Interpretation

Symbol specification follows. As
with all other names, it consists
of the symbol length in a byte
followed by the ASCII
string
defining the symbol:
LENGTH

1 byte

SYMBOL

Variable
1-31 bytes

The value found from the symbol
table is a 32-bit quantity.
1

Stack Signed Byte
(TIR$C_STA_SB)

byte
Single
signed
follows. Value is sign
to 32 bits.

constant
extended

Stack Signed Word
(TIR$C_STA_SW)

word
Single
signed
follows. Value is sign
to 32 bits.

constant
extended

Stack Longword
(TIR$C_STA_LW)

Single longword constant follows.

Stack PSECT base
plus byte off set
(TIR$C_STA_PB)

1-byte program
section number
followed by single signed byte
offset.
A 32-bit quantity is
computed by addition of program
section base address and the byte
offset.

C-15

VAX-11 OBJECT LANGUAGE
Code
5

Command

Description/Interpretation

Stack PSECT base
plus word off set
TIR$C_STA_PW)

1-byte program
section number
followed by single signed word
offset.
A 32-bit quantity is
computed by addition of program
section base address and the word
offset.

Stack PSECT base
plus long word offset
(TIR$C_STA_PL}

1-byte program
section number
followed
by
signed
longword
offset.
A 32-bit quantity is
computed by addition of program
section base address and
the
longword offset.
Note that although the offsets in
the
above three commands are
signed, negative values are very
rarely correct.
Note also that
the base address is that of this
module's
contribution
to the
program section.

Stack Unsigned Byte
(TIR$C_STA_UB)

As for TIR$C STA SB except that
the value is zero-extended to 32
bits.

Stack Unsigned Word
(TIR$C_STA_UW)

As for TIR$C STA SW except that
the value is zero-extended to 32
bits.

Stack Byte From Image
(TIR$C_STA_BFI)

This command is reserved
for
future use. The longword on top
of
the stack is used as an
address, in the image, from which
to retrieve a byte. The byte is
zero extended and replaces the
top longword of stack.

Stack Word From Image
(TIR$C_STA_WFI}

This command is reserved
for
future use.
It is the
word
variant of the previous command.

Stack Longwocd From
Image (TIR$C_STA_LFI)

This command is reserved
for
future use.
It is analogous to
the previous two commands.

Stack Entry Point Mask
(TIR$C_STA_EPM)

This command has the same format
as
TIR$C STA GBL.
However,
instead of-stacking the value of
the symbol, the entry point mask
(unsigned word) which accompanies
the symbol definition is stacked.
An
error is produced if the
symbol referenced is not an entry
point.

C-16

VAX-11 OBJECT LANGUAGE
Code
13

Command

Compare procedure
arguments and stack
TRUE or FALSE.
(TIR$C_STA_CKARG)

Description/Interpretation

The format of
follows:

the command is as

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

COMMAND CODE
SYMBOL
NAME
i---------------i

ARG INDEX
ACTUAL
ARGUMENT
DESCRIPTOR
The purpose of this command is to
compare
an
actual
argument
descriptor
with
a
formal
descriptor
for
a
particular
procedure, stacking an indicator
based on match or mismatch of
arguments.
This indicator
is
TRUE if match is found or if
there is no
formal
argument
descriptor.
The indicator is
FALSE if (and only
if)
the
specified formal is described by
a procedure definition but the
descriptor does not match the
accompanying
actual
argument
descriptor.
The argument that is checked is
given by the index, and is thus
number 0 through 255. The format
of the actual argument descriptor
is identical to that of
the
procedure definition GSD record
described in
Section
C.4.4.2
above~
The
linker currently
compares
only
the
fields
ARG$V PASSMECH, stacking the TRUE
indicator if they agree, FALSE if
they do not.
14-19

Reserved Commands

C-17

VAX-11 OBJECT LANGUAGE

C.5.1.2 Store Group - All commands of the store group pop the top
longword from the stack upon completion of the command. Several of
the commands provide validation of the quantity being stored, with the
possibility of issuing truncation errors during the operation. Upon
completion of the command, the location counter is pointing to the
next byte in the output image.
Code

Command

Store Signed byte
(TIR$C_STO_SB)

Bits 31:7 must be identical.
byte written to image.

Store Signed Word
(TIR$C_STO_SW)

Bits 31:15 must be identical.
Lower word written to image.

Store Longword
(TIR$C_STO_LW)

One longword written to image.

Store Byte Displaced
(TIR$C_STO_BD)

Location counter subtracted from
top of stack.
Decrement value.
Bits
31:7 must be identical.
Byte is then written to image.

Store Word Displaced
(TIR$C_STO_WD)

plus
2
Location
counter
subtracted from top of stack.
Bits 31:15 must be identical.
Word written to image.

Store Longword
Displaced
(TIR$C_STO_LD)

Location
counter
plus
subtracted from top of stack.
Longword written to image.

Store Short Literal
(TIR$C_STO_LI)

One longword from
31:6 must be zero.
written to image.

Store PositionIndependent Data
Reference
(TIR$C_STO_PIDR)

The longword on top of stack is
assumed to be the address of a
data
item.
It occurs in a
nonexecutable program
section.
If
the
address is absolute,
command
behaves
as
store
longword.
If
address
is
relocatable, command behaves as
store longword displaced and in
addition provides information in
the image header for subsequent
linker processing.

Description/Interpretation

C-18

stack,
Single

Low

bits
byte

VAX-11 OBJECT LANGUAGE
Code

Command

Store PositionIndependent Code
Reference
(TIR$C_STO_PICR)

Description/Interpretation
The longword on top of the stack
is assumed to be the address of
an item to which a positionindependent
instruction
makes
reference.
The purpose of the
command
is
to
generate
a
position-independent
reference.
If the top of stack is absolute,
the byte "9F"
(hex) is written
(which is autoincrement def erred
addressing mode on the PC and
therefore absolute)
followed by
the top as for store longword.
If,
however,
top of stack
is
relocatable,
the byte "EF" (hex)
is written
(which is longword
displacement
mode off PC and
therefore relative addressing).
Location counter is incremented.
Then the longword is written just
as for store longword displaced.
This and the previous command are
discussed
further
in
the
references
on
generation
of
position independent images.

Store Repeated
Signed Byte
(TIR$C_STO_RSB)

The longword on top of the stack
is used as the repeat count. The
low order.byte of next longword
is written to the
on the stack
image the
indicated number of
are
Both
longwords
times.
cleaned off stack on completion.

Store Repeated
Signed Word
(TIR$C_STO_RSW)

As above
written.

Store Repeated
Analogous to above.
Longword (TIR$C_STO RL)

Store Arbitrary
Field (TIR$C_STO_VPS)

The bits 0 to (s-1) of the top
longword are written to
image
starting at bit p of the current
location. The command byte 1n
the object module is followed by
p and s (respectively) which are
unsigned
bytes.
Only
the
specified bits of the image are
altered.
After the operation the
location counter is the address
of the byte containing bit (p+s)
of the location modified.
Note
that the value of p+s must be
greater than zero and less than
or
equal
to
either
32 or
((P+8)/8)*8-l, whichever is less.

Store Unsigned Byte
(TIR$C_STO_USB)

Same as TIR$C STO SB except
bits 31:8 must be-zero.

C-19

except

that words are

that

VAX-11 OBJECT LANGUAGE
Code

Command

Description/Interpretation

Store Unsigned Word
(TIR$C_STO_USW)

Analogous to
must be zero)

Store Repeated
Unsigned Byte
(TIR$C_STO_RUB)

Analogous to above.

Store Repeated
Unsigned Word
(TIR$C_STO_RUW)

Analogous to above.

Store Byte
(TIR$C_STO_B)

If top
longword on
stack is
is negative, then bits 31:7 must
be 1. Otherwise, bits 31:8 must
be zero.
Low order byte
is
written to image. This command
permits any S bit value from -128
to 255 to be written to the
image.

Store Word
(TIR$C_STO_W)

If top longword is negative, bits
31:15 must be 1. Otherwise bits
31:16 must be zero. Low order
word is written to image.
This
command permits any 16-bit value
from -32768 to 65535
to
be
written to the image.

Store Repeated Byte
(TIR$C_STO_RB)

The repeated version of store
byte.
See
TIR$C STO RSB
for
description of repeat count.

Store Repeated Word
(TIR$C_STO_RW)

Analogous to above.

Store repeated
Immediate Variable
Bytes
(TIR$C_STO_RIVB)

One byte of byte count
(N) followed by N bytes.
The N bytes
are written to the image and
repeated the number of
times
specified by the top longword of
the stack, which is removed from
the stack on completion.
(A 0
repeat count stores nothing.)

Store Position
Independent
Reference Relative
(TIR$C_.STO_.PIRR)

The longword (longword 1) on the
top of the stack is the address
of a data item.
If it is an
absolute value the command is the
same as Store Longword except
that a second value is cleared
from the linker stack. If the
address
is
relocatable,
the
second longword
(longword 2) is
taken from the stack.
If its
value is -1, the current value of
the
location
counter
is
substituted for longword 2. The
value then stored is longword 1
minus longword 2).

43-49

Reserved Commands

C-20

above

(Bits 31:16

VAX-11 OBJECT LANGUAGE
C.5.1.3 Operator Group - The linker evaluates expressions in Post Fix
Polish form. All arithmetic operations are performed in signed 32-bit
2's complement integers. There is no provision for floating point,
string, or quadword computation.
The commands of the operator group take as operands the top one or two
longwords on the stack. Upon completion of the operation, the result
is the top longword on the stack. Attempts to divide by zero produce
a zero result, and a nonfatal diagnostic is issued.
Code

Description/Interpretation

Command

No-operation
(TIR$C_OPR_NOP)

Add (TIR$C_OPR_ADD)

Top two longwords are added.

Subtract
(TIR$C_OPR_SUB)

Top longword is
next.

Multiply
(TIR$C_OPR_MUL)

Top two longwords are multiplied.

Divide
(TIR$C_OPR_DIV)

Divisor is top longword.

Logical AND
(TIR$C_ OPR_AND)

Logical AND of top two longwords.

Logical Inclusive OR
(TIR$C_OPR_IOR)

Inclusive
longwords.

top

two

Logical Exclusive OR
(TIR$C_OPR_EOR)

Exclusive
longwords.

top

two

Negate
(TIR$C_OPR_NEG)

Top longword is negated.

Complement
(TIR$C_OPR_COM)

Top longword is complemented.

Insert Field
(TIR$C_OPR_INSV)

This command is reserved
for
future use. It is analogous to
the store of arbitrary bit field
TIR$C STO VPS (code 32).
The
only - difference
is that the
target for bits from top of stack
is
the next longword on the
stack, and location counter is
therefore unaffected. Note that
top longword is popped and that p
and s are bytes following command
in the TIR record.

Arithmetic Shift
(TIR$C_OPR_ASH)

The longword on top of stack is
the shift count to apply to next
longword.
Negative
quantity
causes a
right
shift
(with
replication
of
sign
bit).
Positive causes left shift with
zeroes moved into low order bits.

C-21

subtracted from

VAX-11 OBJECT LANGUAGE
Code

Command

Description/Interpretation

Unsigned Shift
(TIR$C_OPR_USH)

As above except that zeroes are
moved into high and low order.

Rotate
(TIR$C_OPR_ROT)

Rotate count is top longword to
apply in a rotate
(left
if
positive,
otherwise right) of
next longword on stack.
Rotate
count must have an absolute value
between 0 and 32.

Select
(TIR$C_OPR SEL)

Remove the top longword from the
stack. If it has the value TRUE
(low bit set) remove and discard
the next longword on the stack.
If the first longword removed has
the value FALSE (low bit clear)
copy the next longword on the
stack to the one that follows.
Thus, the command presumes there
are three longwords on the stack.
These are collapsed to a single
longword which is the value of
the second or third based on the
value of the first.

Redefine Symbol to
Current Location.
(TIR$C_OPR_REDEF)

The command has the same format
as the TIR$C STA GBL
command.
Causes
the -symbol
to
be
re-defined on output of symbol
table(s) to have the value of the
location
counter
when
this
command
is
processed.
The
re-definition
does
not occur
until after all image binary is
written.
If
no
binary
is
generated (or is aborted) the
redefinition does not occur.

66-79

Reserved Commands

C.5.1.4 Control Group - The control group of commands is provided
manipulation of the location counter.

fo~

Code

Command

Set Relocation Base
(TIR$C_CTL_SETRB)

The value on top of the stack is
popped into the location counter.

Augment Relocation
Base (TIR$C_CTL_AUGRB)

Signed
longword which
increment to location
follows the command.

Define Location
(TIR$C_CTL_DFLOC)

The top longword on the stack is
removed and used as an index.
The current location counter is
stored away, qualified by the
index
and
the object module
containing it. This command is
only legal in traceback and debug
records.

Description/Interpretation

C-22

is an
counter

VAX-11 OBJECT LANGUAGE
Code

Command

Set Location
(TIR$C_CTL_STLOC)

84-127

Reserved Commands

C.5.2

Description/Interpretation

The top longword on the stack is
removed and used as an index.
The saved location counter (from
a corresponding TIR$C CTL DFLOC)
is set as the current location
counter, and the location counter
saved for index (n) is deleted.
This command is only legal in
traceback and debug records.

Record Length

TIR records may be quite long.
There is an implementation limit
defined by OBJ$C MAXRECSIZ. The maximum record size of the module is
recorded in the header word.

C.5.3

Side Effects and Optimization

In the interest of performance of the linker a few implementation
decisions and their possible side effects should be noted.
1. For all store repeated commands, if the quantity being stored
is zero, the linker does not write the zeroes into the bytes.
The reason for this is that the pages of an image are
guaranteed to be zero unless otherwise initialized by the
compiler. To achieve this, demand zero pages are used within
the linker and were the linker to attempt to write zeroes, the
fact that these are still empty pages of the image is lost.
Thus, it becomes very difficult to compress from the image all
empty pages.
There is, however, a side effect to this behavior, in that if
a cell of an image has been previously initialized, it will
not be zeroed by any repeated store commands. This can occur
in
multiple
modules contributing to and attempting to
initialize the content of overlaid program sections.
Notice,
however, that the results of such multiple initialization are
then dependent on the order of processing of object modules.
This side effect is therefore considered to be acceptable.
2. The linker is a two-pass processor of object modules.
The
content of TIR records is completely ignored on the first pass
but verified and acted upon on the second pass.
However, if
no image is being produced because of a command or link time
error, all TIR records (as well as DBG and TBT records) are
ignored.
A side effect, considered quite acceptable, is that
errors (user or compiler) potentially detectable on pass two
will not be detected. Truncation errors are the most likely
example of such undetected situations.

C-23

VAX-11 OBJECT LANGUAGE
C.6

END OF MODULE (EOM) RECORD (OBJ$C_EOM)

This record declares the end of a module. It declares the severity of
errors encountered by language processor, and, optionally, it declares
a transfer address within a program section in this module.
The
format is as follows:
RECORD TYPE 3

1 byte

ERROR SEVERITY

byte

P-SECT INDEX

byte

TRANSFER
ADDRESS

4 bytes

TRANSFER FLAGS

1 byte

~--·----···----·

This record will be 2, 7, or 8 bytes, depending on the existence of a
transfer address.
Note that the program section specification is by
its index within the module, as used above. The transfer address is
an offset from the base of this module's contribution to the specified
program section. The transfer flags byte may only be present if the
transfer address is present.

C.6.1

Error Severity

The error severity byte specifies to the linker whether errors were
encountered in the source code. It also indicates the severity of any
errors encountered.
Value

Interpretation by linker

No errors

Warnings were generated by language processor.
with link but issue warning message.

Proceed

Errors were severe, proceed
produce an executable image.

Abort the link.

4-10

Reserved.

11-255

Ignored.

C.6.2

Transfer Address Flags

with

link,

The transfer address flags byte directs the linker in
of transfer addresses.
Bit
0

1:7

the

but

not

processing

Interpretation by linker
Weak transfer address. If a transfer address
is already defined, no error is produced.
Reserved, must be O.

C-24

VAX-11 OBJECT LANGUAGE
C.7

DEBUGGER INFORMATION (DBG) RECORDS (OBJ$C_DBG)

The purpose of debugger information records is to allow the language
processors
to pass information, such as descriptions of local
variables, of the compilation to the debugger.
The transmission of
this information may make use of all the functions
(commands)
available in the TIR set.
The command stream in DGB records generates what is ref erred to as the
debug symbol table (DST). The DST follows immediately the binary ~f
the user image and the image header contains a descriptor of where in
the file such data has been written. The production of the DST in
memory makes use of a separate location counter within the linker.
This location counter is initialized as if the DST were the highest
addressed part of the program region of the image. Note, however, the
DST is not in fact mapped into the user image.
The linker produces a DST only if the debugging qualifier was
specified at link time and only if an executable image is being
produced. If either of these is not true, DBG records are ignored.
See the above discussion of the side effects in TIR record processing.

C.7.1

Traceback Information (TBT) Records (OBJ$C_TBT)

Traceback information records are the means by which
language
processors pass information to the facility which produces a traceback
of the call stack. From the point of view of the linker and its
processing of these records, they are identical to DBG records. That
is, they may be mixed with OBG records and all data generated goes
into the DST as if they were in fact DBG records.
The purpose of separating this information from that contained in DBG
records is to allow inclusion of a DST containing only traceback data
when no debugging is requested at link time.
If the production of
traceback information is disabled at link time then these records are
ignored. See the above section on side effects in processing TIR
records.

C.8

LINK OPTION SPECIFICATION (LNK) RECORDS (OBJ$C_LNK)

The link option specification records are defined for the purpose of
allowing the compiler to provide the linker with default parameters
that are used if none were given by the user at link time. Options of
interest are libraries to be searched to resolve undefined symbols,
modules to be included in the link, adjustment of stack and buffer
region sizes.
The exact set of commands allowable will be supplied later, along with
the interaction of conflicting object module LNK records and user
commands.
The general philosophy is to use the most recently
specified parameters unless there are good reasons to the contrary.
These records are currently ignored by the linker.

C-25

APPENDIX D
THE ANALYZE PROGRAM

The object module analysis (ANALYZE) program checks an object module
to see if it is in the correct format for input to the VAX-11 Linker~
(The program can also analyze a concatenated file containing several
object modules.) This program is a diagnostic tool for writers of
compilers or assemblers that must generate native-mode code.
To use
this program intelligently, you must be familiar with the VAX-11
object language specification in Appendix C.
To invoke the program, use the DCL command ANALYZE. The program can
analyze the entire module or only specified types of records. It
checks the record type, contents, and sequence of each object module
record it examines. The program creates an output file containing a
record-by-record
analysis
of
the
object
module,
including
identification of any errors in the module.
The program, however, has a more limited set of
linker. The ANALYZE program:

operations

than

the

•

Does not verify that all data arguments to commands are in the
correct format

•

Does not check whether "store
within legal address limits

data"

commands

are

storing

These restrictions exist because the program does not actually perform
the object language commands in the module. Therefore, if you have
run ANALYZE against an object module and received no errors, you
should perform the additional check of linking the module, requesting
a full map.

D.l

THE ANALYZE COMMAND

The ANALYZE command requires no user privileges and follows the
standard DCL syntax conventions. For a complete discussion of this
command, see the VAX/VMS Command Language User's Guide.
The general
format of the command is as follows:
$ANALYZE

input-file-spec[/MHD] [/GSD] [/TIR] [/DBG] [/TBT] [/EOM]

Command Qualifiers:

Default:

/OUTPUT=file-spec

Output file name
input file name;
output file type = ANL

/INTERACTIVE

/NOINTERACTIVE -- you are not prompted
after each record is displayed.

D-1

THE ANALYZE PROGRAM
D.2

THE OUTPUT FILE

The analysis of each record contains information pertinent
record type, and begins with a line in the following format:
>>>>>RECORD [number] IS [record type]

that

[number of] BYTES LONG

For example:
>>>>>RECORD 4 IS A TEXT/RELOCATION 58 BYTES LONG
Errors in the object module are identified
asterisks. For example:

lines

beginning

with

***** RECORD 3 IS RESERVED TYPE 49 ******************
The program also prints the
erroneous record's contents.
appears later in this appendix.

hexa~ecimal
representation of
the
A complete list of the error messages

The following subsections (D.2.1 to D.2.7)
given for the following record types:

discuss

the

information

Debugger information record
End of module record
Global symbol directory (GSD) record
Module header record
Subheader record
Text information and relocation (TEXT/RELOCATION) record
Traceback information record
The record types are explained in alphabetical order for ease of
reference. In the actual output file, the order reflects the order of
the records in the module. The only requirement for sequence is that
a module header and any subheader records come first, and an end of
module record come last.

D.2.1

Debugger Information Record

Debugger information records identify one or more commands to the
linker, including the data or symbol associated with each command.
(The object language commands are discussed in Appendix C.) For
example, a Store Immediate (STOIM) command is followed by the decimal
number of bytes to be stored and the hexadecimal representation of
this data.
A Stack Global {STA GBL) command is followed by the name
of the symbol whose value is to be placed on the linker stack.
To the right of each command is the notation "STACK = n," where "n" is
the decimal number of bytes that would be on the linker's internal
stack if the linker were actually processing the object module.
The
ANALYZE program reports an error if the count is not equal to zero at
the end of each object module analysis (that is,
if bytes would be
left on the linker stack or if more bytes would be removed than were
placed on the stack).

D-2

THE ANALYZE PROGRAM
D.2.2

End of Module Record

The end of module record contains the following information:
•

Number of compiler errors and
abort specification by the
compilation errors

•

Number of the
address

•

Transfer address expressed
section base

•

Number of program sections defined in the module

D.2.3

program

section
as

warnings, including any link
language processor due to fatal
that
an

contains

offset

from

the

transfer

the

program

Global Symbol Directory (GSD) Record

A GSD record can contain one or more program section definitions,
or more global symbol specifications, or a combination or both.

one

For each program section
given:

information

definition,

the

following

•

Program section alignment

•

Flag bits that are set

•

Maximum length of the program section

For each global symbol specification,
given:

the

following

•

Specification function - that is, whether the specification is
a reference to a global symbol or a definition of a global
symbol

•

Data type (For example: "procedure entry mask," data type 23;
or "unknown," data type 0)

•

Flag bits that are set

•

Number of the program section in which the symbol
(for global symbol definitions only)

•

Value of the symbol (for global symbol definitions only)

•

Name of the global symbol

D.2.4

defined

Module Header Record

The module header record lists the
module:

following

information

•

Structure level of the object language

•

Maximum length that a record in the module can have

•

Name

D-3

about

the

THE ANALYZE PROGRAM

•

Identification

•

Creation date and time

•

Date and time of the last patch

D.2.5

Subheader Records

Most module subheader records consist of ASCII data and are printed as
such.
These subheader types include identification of the language
processor used, the compilation options specified, and the title
specified for the compilation listing.
Another type of subheader identifies the maintenance status if the
module has been patched.
The maintenance status subheader record
lists the following information:

D.2.6

•

Patch utility name and version number

•

UIC under which the patch was executed

•

Input file specification for the patch

•

Correction file specification for the patch

•

Date and time of the patch

•

Sequential patch number

Text Information and Relocation (TEXT/RELOCATION) Record

Text information and relocation records contain the same type
information as debugger information records (see Section D.2.1).

D.2.7

Traceback Information Records

Traceback information records contain the same type of information
debugger information records {see Section D.2.1).

D.3

ANALYZE PROGRAM ERROR MESSAGES

Errors in the object module are identified by lines beginning with
asterisks (*****). Most of these error messages appear in the output
file, but some are displayed on the terminal.
The messages are
presented in alphabetical order, with explanations for those that are
not self-explanatory.
ABSOLUTE PSECT HAS NON-ZERO LENGTH
All absolute program sections must have a length of zero.
ARGUMENT DESCRIPTOR MISSING FOR FORMAL ARGUMENT #[number]
The specified argument requires a character string descriptor.

D-4

THE ANALYZE PROGRAM

ARGUMENT INDEX IS MISSING
BYTE COUNT GOES BEYOND END OF RECORD [number of] BYTES
A byte count contained in the record indicates that the data that
follows does not fit within the record.
[number of] BYTES WERE LEFT ON THE LINKER'S STACK
The object language commands in the module place more bytes on
the linker's internal stack than they remove. The linker's stack
should be empty when it finishes processing each object module.
[number of] BYTES WERE NOT PLACED ON THE LINKER'S STACK BUT WERE
REMOVED FROM IT
The object language commands in the module remove more bytes from
the linker's stack than they place on it.
COMMAND [number] IS ILLEGAL TYPE. [number]
COMMAND [number] IS RESERVED [code]
(See Appendix C for a list of the assigned and reserved codes.)
CORRECTION FILE SPECIFICATION WAS NOT IN COMPRESSED FORM
The correction file specification in the maintenance
subheader record contains nulls, tabs, or blanks.

status

DATE/TIME FIELD CONTAINS ILLEGAL CHARACTER CHARACTER [position]
IS [ASCII representation] ([number] HEX)
ENTRY POINT GSD HAS ILLEGAL LENGTH [number
[minimum number] AND [maximum number]

of]

BYTES - NOT

BETWEEN

FILE [file name] DOES NOT END WITH EOM
The end of the module record is missing or out of sequence.
FIRST CHARACTER OF GLOBAL SYMBOL IS NUMERIC OR BLANK
FIRST CHARACTER OF CORRECTION FILE SPECIFICATION IS NUMERIC OR BLANK
FIRST CHARACTER OF INPUT FILE SPECIFICATION IN NUMERIC OR BLANK
FIRST CHARACTER OF MODULE NAME IS NUMERIC OR BLANK
FIRST CHARACTER OF PATCH UTILITY NAME IS NUMERIC OR BLANK
FIRST CHARACTER OF P-SECT NAME IS NUMERIC OR BLANK
FORMAL ARGUMENT DESCRIPTOR IS MISSING REMAINING BYTE COUNT
The record is not long enough to hold the remaining byte count.
GLOBAL SYMBOL CONTAINS ILLEGAL CHARACTERS
[ASCII representation] ([number] HEX)

CHARACTER

Valid characters are •
(period), $ (dollar sign),
0 through 9, and A through z.

D-5

[position]

(underscore),

THE ANALYZE PROGRAM

GLOBAL SYMBOL DEFINITION RECORD HAS ILLEGAL LENGTH
BYTES - NOT BETWEEN [minimum length] AND [maximum length]

[number

of]

GLOBAL SYMBOL FIELD LENGTH [length]
CHARACTERS

[number

of]

ILLEGAL

NOT

GLOBAL SYMBOL LENGTH { [number of] BYTES ) ILLEGAL - SHOULD
[number of] CHARACTERS

GLOBAL SYMBOL REFERENCE RECORD HAS ILLEGAL LENGTH [number
BYTES - NOT BETWEEN [minimum number] AND [maximum number]

TO
of]

GSD TYPE [number] DOES NOT EXIST
{Appendix C lists the valid GSD types.)
!DENT CONTAINS ILLEGAL CHARACTER
representation] {[number] HEX)

CHARACTER

[position]

[ASCII

!DENT LENGTH [length] ILLEGAL SHOULD BE 1 TO [number of] CHARACTERS
ILLEGAL ALIGNMENT - GREATER THAN [maximum permitted]
ILLEGAL CORRECTION FILE SPECIFICATION LENGTH OF ZERO, SHOULD BE
[number of] CHARACTERS
The correction file specification
subheader record is zero.
ILLEGAL INPUT FILE SPECIFICATION
[number of] CHARACTERS

LENGTH

the

maintenance

ZERO,

SHOULD

The input file specification in the maintenance status
record has a length of zero.
ILLEGAL MAXIMUM RECORD LENGTH - MUST BE BETWEEN [minimum
[maximum length]

status

subheader

length]

The maximum record length for the module, as specified
module header record, is outside the acceptable range.

AND

the

number]

AND

ILLEGAL PSECT ALLOCATION - EXCEEDS [number of] BYTES
ILLEGAL RECORD LENGTH
[maximum number] BYTES

[length]

NOT

BETWEEN

[minimum

ILLEGAL SEVERITY CODE [code]
The severity code specified in an end of module record is illegal
(see Section C.6.1).
ILLEGAL STARTING BIT POSITION- NOT 0 TO 31
A variable bit field command specifies an
position.

illegal

starting

bit

ILLEGAL STRUCTURE LEVEL - ONLY [highest level currently supported]
SUPPORTED

The structure level {format) of the object language in the module
is not yet supported by the ANALYZE program.
The program
analyzes only structure levels 0 through the level specified in
the message.

D-o

THE ANALYZE PROGRAM
ILLEGAL SUBHEADER TYPE OF [type]
The specified subheader type is not
program.

recognized

the

ANALYZE

ILLEGAL SYNTAX FOR DATE/TIME
The date and time must be in a fixed-length ASCII string with the
following format:
dd-mon-yy hh:mm:ss
ILLEGAL TRANSFER ADDRESS (NOT BETWEEN 0 AND [highest available virtual
address] )
The transfer address is outside the virtual address space.
[flag bit number] ILLEGALLY
The specified flag bit is set, but is reserved (invalid).
This
message follows the message "THE FOLLOWING FLAG BITS ARE SET:"
and a listing of the flag bits legally set.
INCOMPLETE RECORD - NEXT FIELD AT BYTE [location within record] BEYOND
RECORD
A byte count contained in a module header record is greater
the number of bytes remaining in the record.

than

INPUT FILE SPECIFICATION WAS NOT IN COMPRESSED FORM
The input file specification of the maintenance status
record contains blanks, nulls, or tabs.

subheader

INVALID ARGUMENT INDEX OF [number] NOT BETWEEN [minimum] AND [maximum]
INVALID MAXIMUM ACTUAL ARGUMENT COUNT OF [number] NOT BETWEEN [number]
AND [number]
INVALID MINIMUM ACTUAL ARGUMENT COUNT OF [number] NOT BETWEEN [number]
AND [number]
INVALID SEQUENCE - MHD SHOULD NOT FOLLOW TYPE [type] RECORD
The only record type that can precede a module header is type 3
(end of module record for the previous module in a concatenated
file).
INVALID SEQUENCE - SHOULD NOT FOLLOW EOM OR BEGIN A MODULE
Nothing can follow an end of module record except an
or a module header record in a concatenated file.
INVALID SEQUENCE - SUB-HEADER RECORD SHOULD
RECORD

NOT

A subheader record should only follow a module header
another subheader record.
INVALID SYNTAX OF CORRECTION FILE SPECIFICATION IN:

end-of-file
TYPE

[type]

record

[error part]

The correction file specification in the maintenance status
subheader record has a syntax error in the specified part.

D-7

THE ANALYZE PROGRAM

LANGUAGE PROCESSOR RECORD FOLLOWS (number of] TIR, GSD, OR TB'f RECORDS
The language processor subheader record should follow the
header record.

module

LANGUAGE PROCESSOR RECORD LARGER THAN [number of] CHARACTERS
MINIMUM IS GREATER THAN MAXIMUM
The minimum actual argument count specified is greater
maximum actual argument count specified.

than

the

MODULE NAME CONTAINS ILLEGAL CHARACTERS CHARACTER (position] IS (ASCII
representation] ((number] HEX)
MODULE NAME LENGTH ILLEGAL SHOULD BE 1 TO [number of] CHARACTERS
NO P-SECTIONS DEFINED IN MODULE
An object module must contain at least one program section.
PATCH UTILITY NAME CONTAINS ILLEGAL CHARACTER CHARACTER [position]
[ASCII representation] ([number] HEX)

The patch utility name in the maintenance status subheader record
contains the specified illegal character.
PATCH UTILITY
CHARACTERS

NAME

LENGTH

ILLEGAL

SHOULD

[number

The length of the patch utility name in
subheader record is illegal.

the

maintenance

of]

status

PATCH UTILITY VERSION CONTAINS ILLEGAL CHARACTERS
The patch utility version in the maintenance
record contains an illegal character.

status

PATCH UTILITY VERSION LENGTH [length] ILLEGAL SHOULD BE 1
of] CHARACTERS

subheader
TO

[number

The length of the patch utility version in the maintenance status
subheader record is outside the indicated range.
PROCEDURE WITH FORMAL ARGUMENT DEFINITION HAS ILLEGAL LENGTH ( [number
of] BYTES ) - NOT BETWEEN [minimum number] AND [maximum number]
PROCEDURE WITH FORMAL ARGUMENT DEFINITION IS
ARGUMENT COUNT

MISSING

MAXIMUM

ACTUAL

PROCEDURE WITH FORMAL ARGUMENT DEFINITION IS
ARGUMENT COUNT

MISSING

MINIMUM

ACTUAL

BYTES

NOT

P-SECT NAME CONTAINS ILLEGAL CHARACTER CHARACTER [position] IS
representation] ([number) HEX)

[ASCII

P-SECT DEFINITION RECORD HAS ILLEGAL LENGTH [number of]
BETWEEN [minimum length) AND [maximum length]

PSECT NAME LENGTH IS ILLEGAL [length)

D-8

THE ANALYZE PROGRAM

P-SECTION NUMBER EXCEEDS COUNT OF THOSE DEFINED IN MODULE
program sections defined]

[number

The program section number supplied in the program section index
field of an end of module record is greater than the number
assigned to any program section in the module. In other words,
the transfer address is specified as being in a nonexistent
program section.
[number of] PSECT(S) DEFINED - TIR REFERENCES PSECT NUMBER (number)
A text information and relocation record contains a reference to
a program section that is not defined in the module. Program
sections are assigned a number in the range 0 through 255, in the
order in which they are defined.
RECORD [number] IS ILLEGAL - ZERO LENGTH
The record length byte in the specified record contains zero.
RECORD [number] IS RESERVED TYPE [type]
The record type of the specified record in invalid.
RECORD [number] LENGTH ([length]) GREATER THAN MAX.
([maximum length])

PERMITTED

LENGTH

The length of the specified record is greater than the maximum
permitted length specified in the module header record. The last
number in the message is the actual length of the specified
record.
REQUIRED DATA NOT CONTAINED WITHIN RECORD
Inconsistencies exist within the record that make it impossible
for the ANALYZE program to interpret it. For example, a byte
count of 3 might be followed by a symbol with more than 3
characters.
This message is followed by
hexadecimal representation.

the

contents

the

record

RESERVED BIT #[number] SET IN ARGUMENT VALIDATION CONTROL BYTE
RESERVED DATA TYPE
(For a list of legal data types, see the "Procedure Calling and
Condition Handling" appendix in the VAX-11 Architecture Handbook
or in the VAX-11 Run-Time Library Referenc~_M.anu~.)

D-9

INDEX

A
command, D-1
ANALYZE utiltiy, D-1 through D-9
Analyzing object modules D-1
through D-9
Attributes of program sections,
5-9, 6-5 through 6-7, 7-2
through 7-5
changing, 5-9
concatenated (CON), 7-4
overlaid (OVR), 7-4
position independent code
(PIC), 7-5, 8-3 though 8-5
relocatable (REL), 7-3
shareable (SHR), 7-5, 8-3
Vector (VEC), 7-5

~WALYZE

Cross reference, 4-5, 6-8, 6-9
/CROSS REFERENCE command qualifier, 4-5

D
Debug capabilities, 1-3, 4-5,
4-6, C-25
/DEBUG command qualifier, 4-5
Default system library, 3-5,
4-8, 4-9
Default user libraries, 3-3, 3-4,
4-9, 4-10
Deferred Relocation, 8-4, 8-5
Demand zero image sections, 5-7,
7-8, 7-10
DZRO_MIN=option, 5-7, 7-8, 7-10

B
BASE= option, 5-6, 7-10, 7-11
/BRIEF command qualifier, 4-4, 6-2

c
Changing program section attributes, 5-9
CHANNELS= option, 5-6
CLUSTER= option, 5-7
Clusters, 5-7, 7-1, 7-2, 7-7
through 7-11
COLLECT= option, 5-7
Command qualifiers, 4-1 through
4-12
/BRIEF, 4-4
/CONTIGUOUS, 4-5
/CROSS REFERENCE, 4-5
/DEBUG-; 4-5, 4-6
/EXECUTABLE, 4-6
/FULL, 4-6
/HEADER, 4;...7
/MAP, 4-7
/POIMAGE, 4-7
/PROTECT, 4-7
/SHAREABLE, 4-8
/SYMBOL TABLE, 4-8
/SYSLIB-; 4-8
/SYSSHR, 4-9
/TRACEBACK, 4-9
/USERLIBRARY, 4-9, 4-10
Compression, 5-7, 5-9, 7-8, 7-10
Copy on reference image sections,
7-5, 8-3, 8-20
Concatenated attribute, 7-4
/CONTIGUOUS command qualifier,
4-5

E
Error messages, A-1 through A-5
/EXECUTABLE command qualifier,
4-6
Executable images, 1-1, 4-6, 7-6

F
File qualifiers, 4-1, 4-2, 4-4,
4-10 through 4-12, 5-2
/INCLUDE, 3-2, 3-3, 4-10
/LIBRARY, 3-2, 3-3, 4-11
/OPTIONS, 4-11, 5-1
/SELECTIVE SEARCH, 4-11
/SHAREABLE-; 4-11, 5-2, 8-35
/FULL command qualifier, 4-6

G
Global symbols, 2-1 through 2-5,
5-10, C-3, C-9, C-10
GSMATCH= option, 5-7, 5-8, 8-8,
8-9, 8-35

I
Image map, 1-5, 4-4 thr~ugh 4-7,
6-1 through 6-11, B-1
through B-13
Images, 1-1
types of, 7-5 through 7-7
Image sections, 7-1, 7-7 through
7-10

Index-!

INDEX

/INCLUDE file qualifier, 3-2,
3-3, 4-10
Initialization of image, 1-4,
1-5, 7-7 through 7-10
IOSEGMENT= option, 5-8, 5-9
!SD MAX= option, 5-9, 7-10

Options files, 5-1 through 5-10
rules for creating, 5-4, 5-5
uses, 5-1 through 5-3
Overlaid attribute, 7-4

/POIMAGE command q~alifier, 4-7
Position independent code, 7-5,
8-3 through 8-5
Program sections, 5-9, 6-5
through 6-7, 7-2 through 7-5.
alignment, 7-3
attributes, 5-9, 7-2 through 7-5
collecting into clusters, 5-7
name, 7-3
size, 6-5, 7-2
synopsis, 6-5 through 6-7
PROTECT= option, 5-9, 8-9
/PROTECT command qualifier, 4-7,
8-9
Protected shareable images, 4-7,
5-9, 7-5
PSECT ATTR= option, 5-9

Libraries, 3-1 through 3-6, 4-8
through 4-11
default system library, 3-5,
4-8, 4-9
default user libraries, 3-3,
3-4, 4-9' 4-10
/LIBRARY file qualifier, 3-2,
3-3' 4-11
LINK command, 4-1 through 4-12
examples, 4-11, 4-12
f o r ma t , 4 -1 , 4- 2
Local symbols, 2-1 through 2-3,
2-5

M
Map, 1-5, 4-4 through 4-7, 6-1
through 6-11, B-1 through
B-13
/MAP command qualifier, 4-7
Memory allocation, 1-4, 7-4, 7-7
through 7-11
Messages, A-1 through A-5
Modular programming, 1-2, 1-3

0
Object language, 7-2, C-1 through
C-25
Object modules, 1-1, 7-2
analyzing, D-1 through D-9
Options,
BASE=, 5-6, 7-10, 7-11
CHANNELS=, 5-6
CLUSTER=, 5-7
COLLECT=, 5-7
DZRO MIN=, 5-7, 7-8, 7-10
GSMATCH=, 5-7, 5-S, 8-8, 8-9,
8-35
IOSEGMENT=, 5-8, 5-9
ISD_MAX=, 5-9, 7-10
PROTECT=, 5-9
PSECT ATTR=, 5-9
STACK-;;, 5-9
SYMBOL=, 5-10
UNIVERSAL=, 2-4, 5-10, 8-8
/OPTIONS file qualifier, 4-11,
5-1

Q
Qualifiers - See "Command
qualifiers" and "File
qualifiers."

R
References, 2-1 through 2-4
strong, 2-3
weak, 2-3, 2-4
Relocatable attribute, 7-3
Relocation, deferred, 8-4, 8-5

s
/SELECTIVE SEARCH file qualifier, 4-11
Shareable attribute, 7-5, 8-3
/SHAREABLE command qualifier,
4-8
/SHAREABLE file qualifier, 4-11,
5-2, 8-35
Shareable images, 4-8, 7-5
through 7-7, 7-10, 7-11, 8-1
through 8-36
benefits and uses of, 8-1, 8-2
linking, 4-8, 8-8, 8-9
protected, 4-7, 5-9, 8-9
source programs for, 8-2
through 8-7
using, 8-35, 8-36

Index-2

INDEX

STACK= option, 5-9
STARLET.OLB, 3-5, 4-9
Strong reference, 2-3
Symbol cross reference, 4-5, 6-8,
6-9
SYMBOL= option, 5-10
/SYMBOL TABLE command qualifier,
4-8Symbo l tables, 2-4, 2-5, 4-8
Symbols, 2-1 through 2-5, 5-10
global, 2-1 through 2-5, 5-10
C-3, C-9, C-10
local, 2-1 through 2-3, 2-5
universal, 2-4, 5-10, 8-8
/SYSLIB command qualifier, 4-8
/SYSSHR command qualifier, 4-9
/SYSTEM command qualifier, 4-9
System images 4-7, 4-9, 7-7

u
UNIVERSAL= option, 2-4, 5-10,
8-8
Universal symbols, 2-4, 5-10,
8-8
User-defined default libraries,
3-3, 3-4, 4-9, 4-10
/USERLIBRARY command qualifier,
4-9, 4-10

v
VAX-11 object language, 7-2, C-1
through C-25
Vector Attribute, 7-5
VMSRTL.EXE, 3-5, 4-9

/TRACEBACK command qualifier, 4-9
Transfer vectors, 8-5 through 8-7

Weak reference, 2-4

Index-3

VAX-11

Linker Reference Manual
AA-D019B-TE
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.

______________ ___
,"

-----------------·-·

--------------·

-----------

~-----

-.E
··---------------·---~- -~-------

g>
0
0

Did you find errors in this manual?
page number.

If so, specify the error and the

________ _________ ___
,,

--------

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

- - - - ·------------------ ------ --------------·---------------··----·· ......------·----------------------··

__ -

,,,_.,.,,.

·-

______ _______...
,,

·--------~

---------------- -Please indicate the type of reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[] Student programmer
[] Other (please specify>~~~~---

Name _______________________________ Date _ _ _ _ _ __
Org ani za tion ______._. ________, ,
Street---~~------

---·------·-----

Ci t Y - - - - - - - - - - - - - - - - S t a t e - - - - -

Zip Code_~--~-
or
Country

Do Not Tear - Fold Here and Tape -

_______ ,
I
No Postage
Necessary
if Mailed in the
United States

POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS TW/A 14
DIGITAL EQUIPMENT CORPORATION
1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS

Do Not Tear - Fold Here

01876