Digital PDFs

DEC-XV-UCHNA-A-D

December 1975

72 pages

Original

19MB

Document:	CHAIN XVM/EXECUTE/XVM Utility Manual
Order Number:	DEC-XV-UCHNA-A-D
Revision:
Pages:	72
Original Filename:	http://bitsavers.org/pdf/dec/pdp15/XVM/DEC-XV-UCHNA-A-D-CHAIN_XVM_EXECUTE_XVM_UTILITY_MANUAL.pdf

OCR Text

XVMIEXECUTE XVM
UTILITY MANUAL
DEC-XV-UCHNA-A-D

CHAIN XVMIEXECUTE XVM

UTILITY MANUAL
DEC-XV-UCHNA-A-D

digital equipment corporation • maynard. massachusetts

First Printing, December 1975

The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may be used or copied only in accordance with the terms of such
license.
Digital Equipment Corporation assumes no "responsibility for the use or
reliability of its software on equipment that is not supplied by
DIGITAL.

(§)

1975 by Digital Equipment Corporation, Maynard, Mass.

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

DECsystem-10
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8

MASSBUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-IO
TYPESET-ll

1/76-6

CONTENTS
Page
vii

PREFACE
CHAPTER

INTRODUCTION

CHAPTER

THE OVERLAY SYSTEM

2-1

2.1
2.2
2.3
2.4
2.5
2.6
2.7

RESIDE~T

EXTERNAL LINK COMPONENTS
INTERNAL LINK COMPONENTS
BLANK COfVI..MON
LABELFD CONMON
RESTRICTING C01":MON AREAS
THE LINK TABLE

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

CHAPTER

SOURCE OF RELOCATABLE BINARY UNITS

3-1

CHAPTER

LINK ENTRY POINTS AND FILE NAMES

4-1

CHAPTER

THE RELOCATION PROCESS

5-1

CHAPTER

I/O DEVICE ASSIGNMENTS

6-1

CHAPTER

BUILDING AN OVERLAY STRUCTURE

7-1

7.1
7.2
7.3
7.4
7.4.1
7.4.2
7.4.3
7.4.4
7.4.5
7.4.6
7.4.7
7.4.8
7.4.9
7.4.10
7.4.11
7.4.12
7.4.13
7.4.14
7.4.15
7.4.16
7.4.17
7.4.18
7.5
7.6
7.6.1
7.6.2
7.7
7.8

cm1fvl.Atm INPUT
CONDITIONAL MESSAGES
NAME XCT FILE
LIST OPTIONS AND PARAMETERS
BKR
BOO:nnK
BOT:nnnnn
GM
nnnK

NOX
PAL
PAR
PGR
SAC
RES or RES/nam1,nam2, ... ,namN/
SL:aaaaaa
SZ
UL:aaaaaa
VTC or VTC/nam1,nam2, ... ,namN/
XVM
Mode Values and Locations
RFSIDENT CODE DEFINITION
LINK AND STRUCTURE DEFINITION
Link Definitions
Overlay Structure Description
TERMINATION OF COMMAND INPUT
EXAMPLES

7-1
7-2
7-2
7-2
7-2
7-3
7-3
7-3
7-3
7-3
7-3
7-3
7-3
7-4
7-4
7-4
7-4
7-4
7-4
7-4
7-5
7-5
7-<)
7-5
7-5
7-6
7-8
7-9

EXECUTION OF AN OVERLAY SYSTEM

8-1

CHAPTER

ROUTI~ES

t-' M

iii

CONTENTS (Cant. )
Page
APPENDIX A

THE LINK TABLE

APPENDIX B

THE XCT FILE

APPENDIX C

XCT FILE RECORD FORfvlATS

APPENDIX D

CORE ALLOCATION DURING CHAIN

APPENDIX E

CORE ALLOCATION DURING EXECUTE

APPENDIX F

ALPHABETICAL LIST OF CHAIN MESSAGES

Index

Index-l

LIST OF ALL XVM MANUALS

The following is a list of all XVM manuals and their DEC numbers, including the latest version available.

Within this manual, other XVM

manuals are referenced by title only.

Refer to this list for the

DEC numbers of these referenced manuals.
BOSS XVM USER'S MANUAL

DEC-XV-OBUAA-A-D

CHAIN XVM/EXECUTE XVM UTILITY MANUAL

DEC-XV-UCHNA-A-D

DDT XVM UTILITY MANUAL

DEC-XV-UDDTA-A-D

EDIT/EDITVP/EDITVT XVM UTILITY MANUAL

DEC-XV-UETUA-A-D

8TRAN XVM UTILITY MANUAL

DEC-XV-UTRNA-A-D

FOCAL XVM LANGUAGE MANUAL

DEC-XV-LFLGA-A-D

FORTRAN IV XVM LANGUAGE MANUAL

DEC-XV-LF4MA-A-D

FORTRAN IV XVM OPERATING ENVIRONMENT MANUAL

DEC-XV-LF4EA-A-D

LINKING LOADER XVM UTILITY MANUAL

DEC-XV-ULLUA-A-D

MACll XVM ASSEMBLER LANGUAGE MANUAL

DEC-XV-LMLAA-A-D

MACRO XVM ASSEMBLER LANGUAGE MANUAL

DEC-XV-LMALA-A-D

MTDUMP XVM UTILITY MANUAL

DEC-XV-UMTUA-A-D

PATCH XVM UTILITY MANUAL

DEC-XV-UPUMA-A-D

PIP XVM UTILITY MANUAL

DEC-XV-UPPUA-A-D

SGEN XVM UTILITY MANUAL
SRCCOM XVM UTILITY MANUAL
UPDATE XVM UTILITY MANUAL
VP15A XVM GRAPHICS SOFTWARE MANUAL

DEC-XV-USUTA-A-D
DEC-XV-USRCA-A-D
DEC-XV-UUPDA-A-D
DEC-XV-GVPAA-A-D

VT15 XVM GRAPHICS SOFTWARE MANUAL

DEC-XV-GVTAA-A-D

XVM/DOS KEYBOARD COMMAND GUIDE

DEC-XV-ODKBA-A-D

XVM/DOS READERS GUIDE AND MASTER
INDEX

DEC-XV-ODGIA-A-D

XVM/DOS SYSTEM MANUAL

DEC-KV-ODSAA-A-D

XVM/DOS USERS MANUAL

DEC-XV-ODMAA-A-D

XVM/DOS ViA SYSTEM INSTALLATION GUIDE

DEC-XV-ODSIA-A-D

XVM/RSX SYSTEM MANUAL

DEC-XV-IRSMA-A-D

XVM UNICHANNEL SOFTWARE MANUAL

DEC-XV-XUSMA-A-D

PREFACE
The operation and use of the CHAIN XVM/EXECUTE XVM Utility Program is
described in this manual.

It was assumed in the preparation of this

manual, that the reader is familiar with the operation of the XVfvI
equipment and the contents of the following manuals:
XW1/DOS System Manual
XVM/DOS Users Manual

vii

CHAPTER 1
INTRODUCTION
The programs CHAIN XVM (CHAIN) and EXECUTE XVM (EXECUTE) facilitate a
user generated system of core overlays in an XVM/DOS (DOS) environment.
This system of overlays consists of a resident main program, and may
include other indicated resident routines, a resident blank COMMON
storage area, and a set of subroutines which overlay each other as
directed by the user.
LINKS.

These subroutines are grouped into units called

Many or all LINKS may overlay each other, and several LINKS

may overlay a larger LINK without overlaying each other.

Cascading of

sub-overlays is not limited.
A LINK is loaded into core when a subroutine within the LINK is called
and remains resident until overlaid.

A LINK's core image is not re-

corded or "swapped out" when it is overlaid.

The same image is brought

into core each time a LINK is loaded.
Subroutines are called and return control to the calling routine in
the normal fashion, except when a calling routine will be overlaid
by a called routine.

In the latter case, no arguments can be conveyed

via the call, and subroutine exit must be accomplished by calling
another routine.
Within links, there is no imposed order in which routines must be
called nor is there restriction of the routines callable by any
routine.
l
The Overlay System, when recorded, is called an XCT file .
The program CHAIN is used to build an XCT file and the program EXECUTE
supervises core residency during the execution of a CHAIN-built Overlay System.

lAn "XCT file" is actually two files

1-1

(see Appendix B) .

- '.

CHAPTER 2
THE OVERLAY SYSTEM
CHAIN-built Overlay Systems consist of 1) resident ar;d non-resident
code, 2) COMMON storage, and 3) a Link Table, all cf which are described below.
The Overlay System is built onto an I/O device (XCT file) and the
core that will be required to run it need not be available (or existent)
to build it.
I/O handlers are not included in an XCT file, but are loaded prior to
execution per .DAT slot assignments and remain in core throughout a run.
2.1

RESIDENT ROUTINES

CHAIN requests a list of resident routines.

All routines listed and

any library routines they may call remain in core throughout a run.
The first resident routine is the program to which initial control of
the execution of the Overlay Systems is given by EXECUTE.

All other

routines in the Overlay System are either subroutines or co-routines.
Resident subroutines may be called by any routine (resident or LINK
component) i therefore, the names assigned to resident routines must
be unique throughout the Overlay System.
2.2

EXTERNAL LINK COMPONENTS

Each LINK consists of one or more subroutines, whose calling will result in the loading of the LINK when non-resident.

These subroutines

may be called by any routine, resident, or LINK component, and are
called External Link Components.

The names of External Link Components

must also be unique throughout the Overlay System.
2.3

INTERNAL LINK COMPONENTS

A LINK may also contain subroutines which are only to be called from
within the LINK.

These subroutines are called Internal Link Components,

2-1

The Overlay System

and may be used as internal components of other LINKS.

The names of

Internal Link Components must be unique only within their LINK.
2.4

BLANK COMMON

Blank COMMON is universal COMMON.

It is resident throughout a run and

is available to all routines.
2.5

LABELED COMMON

Labeled CO~~ON blocks declared by resident code are also resident and
available to all routines.

(This feature has been included to allow

a resident initialized block to be available to all routines.)
A labeled CO~~ON block declared within a LINK with a block name that
does not match a resident

CO~~ON

block name, is internal to the LINK.

It is initialized (if BLOCK DATA or .CBS) or cleared when the LINK is
loaded, and overlaid '\-,hen the LINK is overlaid.

The same COMMON block

may be initialized by more than one routine as long as all initializing
routines are contained within the same link.

Using the same name for

labeled COMMON blocks in different LINKS does not force an equivalence
(see Example 3, page 7-12).
CHAIN provides a command option which causes

L~~ELED CO~~ON

BLOCKS of

the same name to be allocated core only once, and to allow elements
of LABELED COMMON to be referenced from any co-resident LINK.

(With-

out this option, LABELED COMMON is considered internal to LINKS.)
option abbreviation accepted by CHAIN is "SAC"
Commons).

The

(Single Allocation of

With the SAC option selected, a LABELED COMMON BLOCK is

made a part of the first LINK listed in the Overlay Description that
contains a declaration for the COMMON BLOCK.
This option facilitates an overlayable inter-LINK communication area.
For example, SUB2, SUB3, and SUB4 each contains a
COMMON/COMBLK/A,B,C,
statement.

With the SAC option and the following Overlay Description,

the LABELED COMMON BLOCK "COMBLK" would reside in SUB2, and would be
available for communication between SUB3 and SUB4 (which overlay each
other) .
SUBI:SUB2,SUB3
SUB3 :SUB4

2-2

The Overlay System
CAUTION:

Since there can be references to elements of a LABELED COM-

MON BLOCK from outside its LINK, a

CO~MON

BLOCK may be overlaid while

references to it still exist in other LINKS.
2.6

RESTRICTING COMMON AREAS

CHAIN option "VTC" allows the user to restrict COMMON areas to bank
boundaries.
in

CO~~ON,

This is useful to the VT15 user who builds display files
since the VT15 cannot cross bank boundaries directly (i.e.,

13-bit addressing).

There are two forms of the option and the giving

of one cancels out the other form if it was given previously.
"VTC" option without names restricts all common areas to bank boundaries.

The "VTC" option is delimited by being the first option in the

command string or by a comma on the left, and by a comma or altmode on
the right.
"VTC/NAM1,NAM2, ••. ,NAM3/" option with names restricts to bank boundaries
only those COMMON areas named (Note:

Blank common is .XX).

More than

one VTC option with names may be given in the command string and all
names specified will be restricted.

The option is delimited by being

the first option in the command string or by a comma on the left, and
a slash on the right.

The name field within the option is delimited

by a slash right after the "VTC" and the slash that terminates the option.

Names in the list are separated by commas.

The VTC option will not restrict COMMON areas declared in BLOCK DATA
SUBPROGRAMS.
The COMMON area is restricted to bank boundaries even if CHAIN is running in page relocation mode.
The RES option has the same format as the VTC option but it restricts
Labeled Common Blocks to Extended Memory (above the bootstrap).
2.7

THE LINK TABLE

Also resident throughout a run is a table with an eleven-word entry
for each External Link Component, a one-word buffer, and a transfer
vector to an entry point to EXECUTE.
Table.

This table is called the Link

Calls to External Link Components are loaded as JMS's to the

2-3

The Overlay System
appropriate Link Table entry.

Transfer of control from the table is

dependent on LINK residency (see Appendix A.I

2-4

CHAPTER 3
SOURCE OF RELOCATABLE BINARY UNITS
When describing an Overlay System, the names of files are listed as
containing either resident code or LINK components.
are read from the "User Program Device"

The named files

(see Chapter 6).

Library

Routine names may also be used when describing resident code.

The

Library Routine names used are distinguished from file names by a
"Library Indicator".

The indicator is a pound sign (#) which may pre-

cede, follow, or appear within the name.

The indicator is useful when

it is desirable to force a Library Routine, which is not called by a
resident routine to be included as resident code (for example, to
"factor" a Library Routine out of all or many LINKS) .
CHAIN accepts library indicators (#) on both internal and external
components.

The name given must correspond to the GLOBAL name of the

routine desired in the library.

3-1

CHAPTER 4
LINK ENTRY POINTS AND FILE NAMES
Each External Link Component has only one entry point whose calling will
result in the loading of the LINK, if non-resident.

This entry point

name (GLOBAL symbol definition) must be the same as the

filename

the file containing the binary unit of the External Component.

The

names of files containing either resident code or Internal LINK Components need not correspond to routine names (although normally they
would) .
The following must be considered to ensure the correct naming of files:
1.

For External Components written in FORTRAN, the name of the
source file should be the same as the subroutine name in the
subroutine statement.

For External Components written in assembly language, the
name of the source file should be the same as the label on
the major entry point (the entry point should be defined as
a GLOBAL symbol).

4-1

CHAPTER 5
THE RELOCATION PROCESS
Each LINK is relocated and output as a unit in the format described in
Appendix C.

The resident code, although not formally a LINK,

relocated and output in LINK format,

and is denoted LINK #000.

is also
1

CHAIN relocates into the XCT file rather than into core to avoid requiring sufficient core for itself and a LINK while it is being constructed.

This results in the incorrect recording of 1) transfer

vectors to routines not yet relocated

(except External Link Components),

2) transfer vectors for elements of COMMON blocks not yet defined,
and 3) string code address corrections

(Standard Loader Codes 20 and

21).

it is stored in a core resi-

As this information is developed,

dent "Patch Table" and is recorded after all routines of the LINK or
resident code have been relocated and output (see Appendix C) •
A core resident "Symbol Table" is used for global symbols, COMMON
blocks, and COMMON symbols.

Before any relocation, a GLOBAL symbol

definition entry is made for each External Link Component such that
calls to these routines will result in a transfer to the appropriate
Link Table entry.
When relocating the resident code, a second Symbol Table entry is
made for all names flagged with library indicators (i.e.,

#).

This

entry is a dummy GLOBAL symbol reference which is only recognized
when searching for unresolved GLOBAL symbol references.

It is used

to ensure the inclusion of library routines not called by a resident
routine.
Whenever a PGR (page) or BKR (bank) command option is specified, CHAIN
performs a

.USER macro for the <PAG> or <BNK> UIC respectively in

.UFDT-1 to ensure that the correct library is searched during relocation.
1 This standardization is imposed to minimize the size of EXECUTE.
The
Link Table is also recorded in LINK format and is denoted LINK #777
(actually #377777).
5-1

The Relocation Process
After the relocation of each LINK, the Symbol Table is trimmed back
to contain only entries made while relocating the resident code.
The Patch Table is constructed in increasing core from the first availl
The Symbol Table is constructed in decreasing core

able register.

writing over the lower third of CHAIN's code (which is no longer needed).
The overlapping of the Symbol and Patch Tables results in a terminal
error.
The image of the resident code and each LINK is recorded in the XCT file
by relocating and outputting the routines from the indicated files on
the user program device.

If unresolved GLOBAL symbol references

(refer-

ences : to yet unrelocated routine) exist, the user's Library (if existent)
and the System Library are scanned, relocating and outputting any routines which contain a GLOBAL symbol definition that matches an unresolved
GLOBAL symbol reference, thus resolving them.

This Library search con-

tinues until all GLOBAL symbol references have been resolved or the
libraries have been exhausted.

The user's library is searched repeat-

edly until no GLOBAL symbol references are resolved.

Then, the system

library is scanned repeatedly until no GLOBALS are resolved.

If un-

resolved GLOBALs still remain, the library search starts again with
the user's library.

The library search terminates either when no

unresolved GLOBALs remain or when a search through both libraries results in no resolved GLOBALs.

After each routine has been relocated

and output, and if a load map has not been suppressed (NM option), a
line will be typed out containing the routine name (unless GM option)
and the limits of core the routine will occupy.
CHAIN calculates the number of 400

word-blocks needed to store the
8
overlay system, by LINKs, as a core image. This information is stored
in the environment indicator in bits

octal number.

through 11 as a right-justified

The number calculated does not include the LINK table

(LINK 377777) or the resident code (LINK

lDetermined from .SCOM+2

5-2

~).

- '.

CHAPTER 6
I/O DEVICE ASSIGNMENTS
CHAIN's I/O operations are accomplished via six .DAT slots.

The slots

and the functions assigned each are:
.DAT -1

System Library - The system library (default .LIBR) is
scanned to satisfy unresolved GLOBAL references •

• DAT -2

Command Input - Normally the console terminal, but
may be the batch device under Batch Mode .

• DAT -3

Typed output device - Must be the console terminal .

• DAT -4

User program device - All routines listed during command input, which are not indicated as residing in a
library, are relocated from this device.

.DAT -5

User's Library - The current user library (default
.LIBR5) is scanned to satisfy unresolved GLOBAL symbol
references.

If a user's Library does not exist,

.DAT -5

must be assigned "NONE" •
• DAT -6

Relocated output device - The XCT file is written on
this device.

CHAIN never has more than two files open at the same time.

''ihenever

two files are open, one is open for input and the other for output.
The handler functions are limited to:
.WRITE,

.WAIT, and .CLOSE (i.e.,

.INIT,

.ENTER,

.SEEK,

.READ,

"B" type handlers may be used).

6-1

CHAPTER 7
BUILDING AN

OV~ERLAY

STRUCTURE

Before calling CHAIN, the user should be sure that the proper .DAT slot
assignments have been made (see 7.8).
CHAIN is called by typing "CHAIN" following the monitor's $ request.
When loaded, CHAIN will type its name and version number and make the
following requests:
NAME XCT FILE
LIST OPTIONS & PARAMETERS
DEFINE RESIDENT CODE
DESCRIBE LINKS & STRUCTURE

A response to each request via the command input device is necessary.
7.1

COMMAND INPUT

CHAIN reads commands via the console Teletype or, in Batch mode, via
the current Batch device.

All input is accepted in logical lines,

which consist of one or more physical lines.

A carriage return (or

card column 81) is used to continue a logical line onto the next physical line.

An ALTMODE is used to terminate a

logical line.

A line

(logical) consists of names (file, routine, option, parameter), library
indicators (resident code definition only), and break characters (name
terminators).

Blanks are ignored.

Names consist of up to 6 "RADSO"

(A to Z, 0 to 9, ".", and "%") characters and a library indicator ("#")
which may appear anywhere within or around the name
The characters "=", ",",
characters.

":", and "/,, are all considered to be "break"

Each individual break character is only valid in the appro-

priate context (see below for each case) •
When an error is detected, the entire logical line containing the error
is rejected.
lines.

lOPS ASCII editing (RUBOUT andtU) apply only to physical

A tP issued prior to the end of the overlay structure definition

7-1

Building an Overlay structure

will restart CHAIN and will reset all defaults as well as erasing any
effects the command input has had.

A tp issued after the completion

of the overlay structure definition will cause control to be returned
to the XVM/DOS monitor.
An angle bracket

( ">

II )

is typed to indi ca te the beginning of aline.

A hyphen ("_") indicates that a line is being continued across more
than one physical line.
7.2

CONDITIONAL MESSAGES

CHAIN's error messages attempt to indicate the source of any error.

recovery is possible, either by retyping a line (logical) or by typing
tp and restarting CHAIN, CHAIN will type an angle bracket at the left

margin to indicate that input is requested.

If recovery is not possible,

CHAIN will exit to XVM/DOS after typing the appropriate error message.
A list of CHAIN's messages, their meaning and possible recovery procedures, is contained in Appendix F.
7.3

NAME XCT FILE

A 1- to 6-character filename terminated by an ALTMODE is required.

This

name is used when requesting EXECUTE to run the overlay system being
built.
7.4

LIST OPTIONS AND PARAMETERS

options and environmental parameters are li"sted on a (logical) line,
separated by commas. An exception to this rule are the RES and VTC
switches with arguments, in these cases no comma may follow the "/".
A zero length line (ALTMODE only) indicates no options or parameters
specified.

The following options and parameter abbreviations are

recognized by CHAIN.
7.4.1

BKR

Components of the overlay structure being built will be relocated
within BANKS (8K) of core.

Instructions which reference memory will

be assumed to have 13 bits of direct addressability.

7-2

--.

Building an Overlay Structure

7.4.2

BOO:nnK

The system for which the overlay structure is being built will have a
bootstrap at nnK (where nn is 24 or 32).
7.4.3

BOT:nnnnn

The overlay structure will be built upward from address nnnnn toward
the current bootstrap address.

Allocation of extended memory (see

nnnK) will be from the first word following the bootstrap toward the
current value of the memory size (nnnK).
7.4.4

If a load map is output, names are to be file and global symbol rather
than program names.
7.4.5

nnnK

The overlay structure being built will be run on a machine with at
least nnnK words of memory.

If the value of nnn is greater than 32

then the XVM parameter (see below) will be turned on.
7.4.6

No memory map is to be output.
7.4.7

NOX

The overlay structure being built will be run on a machine without the
XM15 option or with the XM15 option disabled (monitor command XVM

OFF) •
7.4.8

PAL

CHAIN will pause after each link is relocated.

This includes the resi-

dent code (link 0) and the link table (link 377777).

To continue the

user must enter t P.
7.4.9

PAR

CHAIN will pause after the resident code is relocated.
user must enter t P.
7-3

To continue the

Building an Overlay Structure
7.4.10

PGR

Components of the overlay structure being built will be relocated within PAGES (4K) of core.

Instructions which reference memory will be

assumed to have 12 bits of direct addressability.
7.4.11

SAC

Named common blocks may be referenced from any link.
7.4.12

RES or RES/naml,nam2, .•• ,namN/

If the RES switch is used without arguments, all uninitialized common
blocks will be forced to reside in extended memory.

Extended memory

is any memory above the current bootstrap address.

If the RES switch

is used with arguments only those common blocks named in the argument
list, plus any uninitialized common blocks specified in the resident
code, will be forced to reside in extended memory.

All common blocks

which are forced to reside in extended memory by the RES switch become part of the resident code.

If extended memory is filled and a

common block has the RES switch applied to it, CHAIN will terminate
rather than place the specified block in low memory.

This restriction

may be avoided by referencing, perhaps by a dummy reference, the common blocks from the resident code and not using the RES option.
7.4.13

SL:aaaaaa

CHAIN will search the library named "aaaaaa" on .DAT -1 to resolve
global references.
7.4.14

The size of the link table, common blocks, and routines are to be included in the load map.
7.4.15

The size is listed following the core limits.

UL:aaaaaa

CHAIN will search the library named "aaaaaa" on .DAT -5 to resolve
global references.
7.4.16

VTC or VTC/nam1,nam2, ••• ,namN/

If the VTC switch is used without arguments, all common blocks will be
forced to reside within a bank (8K) of memory.
7-4

If the VTC switch is

Building an Overlay Structure

used with arguments, then only those common blocks named will be forced
to reside within a bank.
and RES switches.
7.4.17

This switch is independent of both the SAC

XVM

The overlay structure being built will be run on a machine with the
XM1S option enabled (monitor command XVM ON).
7.4.18

Mode Values and Locations

The relocation mode (BKR, PGR) , bootstrap address (BOO), and the XVM
mode (NOX, XVM) take values from the current state of .SCOM.

The

initial core allocation mode is top down (BOT changes this).

The cur-

rent memory size (nnnK) is that of the current machine.

SAC, RES, and

VTC are off. The default user and system libraries are .LIBRS and
.LIBR respectively.
7.S

RESIDENT CODE DEFINITION

The names of files containing relocatable binary units of routines to
be resident throughout a run and the names of Library Routines (flagged
by library indicators (#) to be resident throughout a run are listed
on a line, separated by commas (,).

EXECUTE transfers initial control

to the entry point of the first resident routine relocated, i.e., the
first routine of the first file listed, unless resident code is exclusively Library Routines.

The response to "DEFINE RESIDENT CODE" must

be at least one name.
7.6

LINK AND STRUCTURE DEFINITION

The overlay structure is described in terms of LINK names.

When a

LINK is to consist of only one external component, the name of the file
containing the external component may be used as the LINK name.

How-

ever, when a LINK is to consist of more than one external component, the
LINK must be named and defined.
7.6.1

Link Definitions

Each LINK definition requires one line of command input conSisting of
the LINK's name followed by an equal sign (=) followed by the LINK
definition.

7-S

Building an Overlay structure

A LINK definition is a list of the names of files which contain the
relocatable binary units that comprise the LINK components.

The indi-

vidual filenames listed are separated by commas (,); the two types of
LINK components which may be used (external and internal) are separated
within the definition by a slash (/).

All external LINK component names

must be listed before (to the left of) the slash separator; all internal
LINK components must be listed after (to the right of) the slash.

Ex-

ternal LINK components are accepted only from files with names which
match the external component name (i.e., GLOBAL symbol definition).

DOS external and internal link components can be retrieved from a
library by the use of #, but the GLOBAL name must be used in the command input.

.. - --....

Example:
ABC=SUBl,SUB2/SUB3,SUB4
In the above example, SUBl and SUB2 are external components of LINK ABC,
and SUB3 and SUB4 are internal components of LINK ABC.
Rules for defining a LINK:
1.

A LINK may not be a component of another LINK.

The names of the components of a LINK may not be used as
l
LINK names.

A filename used in the resident code description cannot be
used in a LINK definition.

A filename preceding a slash may be used only once.

A filename following a slash may be used in other LINK definitions (following a slash).

7.6.2

Overlay Structure Description

An overlay structure is described using the names of defined LINKS, or
the names of files containing LINK components and the operators colon
(:) and comma (,), under the following set of rules:

lWhen a LINK consists of only one component, the component's filename
may be used as the LINK name in the "overlay structure descrip~ion",
but not in a LINK definition: i.e., it is not necessary to def1ne a
single component LINK but, if defined, the LINK name cannot be the
component name.
7-6

Building an Overlay Structure

A line is an independent statement processed from left to
right.

A colon is read "is overlaid by" .

A comma is read "and".

Example:
SUB1:SUB2
SUB2:SUB3,SUB4
is interpreted as

SUBl is overlaid by (uses the same core

as) SUB2, SUB2 is overlaid by SUB3 and SUB4, but SUB3 and
SUB4 do not overlay each other.
4.

A colon operator may not be used in a line after a comma has
been used.

This restriction prevents the following ambiguity:

SUB2:SUB3,SUB4:SUB5
The above line is rejected by CHAIN because it is not clear
whether SUB5 overlays SUB3 or SUB4 or both.

All four of

the following examples are acceptable:
SUB2:SUB3,SUB4

SUB5 uses the same core as SUB4

SUB4:SUB5

but not the same core as SUB3.

SUB2:SUB3,SUB4

SUB5 uses the same core as SUB3

SUB3:SUB5

but not the same core as SUB4.

SUB2:SUB5:SUB3,SUB4

SUB5 uses the same core as SUB3
and SUB4.

SUB3 and SUB4 are

loaded individually (if nonresident) as called.
LINK=SUB3,SUB4

SUB5 uses the same core as SUB3 and

SUB2:LINK:SUB5

SUB4.

Both SUB3 and SUB4 are

loaded (if non-resident) whenever
either is called.
5.

A LINK name may appear only once preceding a colon and only
once following another colon.

If a LINK name is used twice, it must be used following a
colon before being used preceding another colon.

Several LINKS overlaying each other may be defined in one
statement.

lA loading order is not implied; just core mapping.

7-7

Building an Overlay Structure

Example:
SUBl:SUB2:SUB3,SUB4 l
NOTE
This is a short method of defining the same
overlay structure as in the first example,
under rule 3.
Rules 5 and 6, although they may appear restrictive, do not limit the
user's description of an overlay structure, but do prevent multiple
description of the position of a LINK in an overlay structure.

LINK may be both overlaid and overlaying, and it may not be possible
or convenient to describe both conditions by using the LINK name only
once, as follows:
SUB2 is overlaying SUBl and is

SUBl:SUB2:SUB3

overlaid by SUB3
Therefore, when a LINK is both overlaying and overlaid, its LINK name
may be used twice, but the LINK(S) overlaid by it must be described
before the LINK(S) by which it is overlaid.
Example:
SUB2:SUB3,SUB4

SUB3 overlays SUB2

SUB3:SUB5

SUB3 is overlaid by SUB5
NOTE

The description of an overlay structure only
defines a desired core mapping; i.e., stating
that SUBl is overlaid by SUB2 means that both
are to be relocated to the same core and cannot co-reside, but does not imply that SUBl
must be called before SUB2.
There is no imposed
order in which routines must be called, nor
is there restriction of the routines callable
by any routine.
7.7

TERMINATION OF COMMAND INPUT

When the last line of overlay structure description has been input,

lA loading order is not implied; just core mapping.
7-8

Building an Overlay Structure
command input is terminated by a zero length line (ALTMODE only).

this time, relocation of the resident code will begin and tp restart will
no longer be possible because the command input code will be written over
by the Symbol Table.
Command input may also be terminated aft er describing only resident code
by typing an ALTMODE in response to the DESCRIBE LINKS & STRUCTURE request.

This allows CHAIN & EXECUTE to be a useful alternative to the

LINKING LOADER when the routines to be loaded and the loader cannot fit
in core together, or when a job is to be run often and it is desirable
to be able to load it with a simple command.
7.8

Viz., E JOBNAM.

EXAMPLES

The following source code is used in examples 1 through 6.
C
C

FILE: MAIN
MAIN PROGRAM

10
20
30
40
50
C

COMMON A,B
CALL SUBl (4, p)
CALL SUB2(2,0)
IF (P-Q) 40,10,40
IF (A-P) 40,20,40
IF (B-Q) 40,30,40
IF (P+Q) 50,40,50
PAUSE
STOP
END
FILE: SUB1

SUBROUTINE SUB1 (N,X)
DIMENSION C(4)
COMMON A/XXX/C
X=C(N)
A=C(N)
RETURN

END
C

FILE: SUB2

SUBROUTINE SUB2(N,X)
DIMENSION C(4)
COMMON A,B/XXX/C
X=C (N) *C (N)
B=C(N)*C(N)
RETURN
END
C

FILE: BDATA

BLOCK DATA
DIMENSION C (4)
COMMON /XXX/C
DATA C/1.0.2.0.3.0.4.0/
END

NOTE

A complete list of error messages produced by
CHAIN is given in Appendix F.

7-9

Building an Overlay Structure
EXAMPLE 1
The angle bracket (">") in the left margin indicates the beginning of a
logical line of command input: the remainder of the line is keyed in by
the user and terminated by an ALTMODE.
ter.

ALTMODE is a non-printing charac-

Both the minimum and maximum core locations occupied by the link

table, a routine, or a common block, are output in the load map as octal
constants.

Also note that all common blocks associated with the resident

code are listed both in the link defining the particular common block
and in the section of the load map named "RESIDENT COMMON BLOCKS".
Common block "XXX" is initialized via the block data subroutine "BDATA",
and is available to both SUBl and SUB2.

NFtt'l E

1. ) . - . "",

,",c· I

r.1 LC.

>:":FN

LIST OPTIONS & PARAMETERS
)S:,49K,XVM,800 . 2 4K
DEFINE RESIDENT CODE
)i'1A IN .. Bi)ATA

DESCRIBE LINKS & STRUCTURE
>~:'UBl

. SUB2

....

L r NK TFIE:LE
957607-057636 000038
PES I DENi COI)E

MAIN

857513-057606 000074

***
BLOCK DATA SUBROUTINE -- BOATA
',)'.)'.,'
..", . . .',

STOP
PAUSE
SF-i'lSi]
F IOF'S

FPF'
OTS Ef;:

(1575(1:;':-'(1::;-;-'5.1.2 80;<11,)1.0

(1.}S 1215 7 42:;::-(t~5 {'::i~I:;:~
(106 (157406-·(1 ;:i74;;::1
012 ~~i5 '( ~:r:: 7-'~:f::i 7'4(1~:;
[-4(1 (1::i6(14~-(I::i ?~:66
F1 ::; ~)5 54~~IE;- ~13E; ~:)4::;
F14 (1551. 7 J:-iZI ::i::;41-;)~i

i);<H)(I,:; 1
(I'~I ~1':I1. 4

0001 1

(

ii:1':ll .:i:;;:: .i.
tl')~1441)

0;<1021 .::

L I W< -- :;;Uc::l
SU81
0551?3-055172 000040

. DA

012 055056-0551?2 000855

L 1 Nrc: -- SI.IB2
(1551.1.4-~)551"(·~:

SUB2

. DR

":)~:I(IO ~:; ' ·

012 0550?7-05511? 000055

BLANK COj'lt'10N

RESIDENT COMMON BLOCKS
XXX
05750l-057512 000010

CORE REQ ' D

.055016-11777 7 042 742

7-10

Building an Overlay Structure

EXAMPLE 2

Both links LKl and LK2 contain the block data subroutine BDATA.

Note

that the error message produced by the memory size 128K" is warning
only, and that CHAIN built the overlay structure properly.

NAt'lE :-:CT F I L.E
(

>:·<:FN
LIST OPTIONS & PARAMETERS
>S~::: .• BOO. :>H:: .. NO::;; .• ?:::K .. F'C:iF:

- QUESTIONABLE MEMORY SIZE -- 25K
DEFINE RESIDENT CODE
)tl.i I N

DESCRIBE LINKS & STRUCTURE
:::U<J =:;1.1,: )/E;::'r,l fi
)L f.:2~ SUi 2/E:[:'f;' F:
)LKJ . L1<~
•...

l INK TABLE

057607-0576l6 000010
~:ES I [)ENT

COCIE

MAIN

05751~-057606

000074

'(' 4 :;:2 -'~I::i,?::i l~:

i~JO€li~161

STOP

(jj.~I:::

.~I:::i

F'AI.JSE
::;Pt'1SG

(106
012

t21~i7416'-'i2l::i

~J 57:27 7 -'~15 741.5

'~10'~1.1.1. "

lOPS

D4~~1

~~156 ~:;) ::i6-· (15 j;.':;;~ 'f"~;

':11i.1.1.~: 2: .1.

r ....,r"".

F1:::
F14

(!~j54:1.

6 _. ~~I~it;(I::i::i

~1~1~144(1

~215::; ~:~;)::- (I~i~:i41.::j

'X!»2::1 ::::

r' r r

OTSER

, 4:::1. OIi.I'~I;;I1.4

LINK -- Ltd.
SU81

05514?-055202 000040

XXX

0551l?-0551.42 000010
012 055056-0551l2 000055

*** BLOCK DATA SUBROUTINE -- BDATA
· DR

L INi< -- LI<2
SU82
055.1.24-055202 00005'?

*** BLOCK DRTR SUBROUTINE -- BDRTA
XXX

· DR

055114-055123 000010
012 055037-055113 000055

8i..ANK COr'1r'10N

...

067774-067777 000004

· ')'.'
,'~
~,

COF.:E

~:EG:"

r;,
055036-067777 012742

7-11

Building an Overlay structure

EXAMPLE 3

The overlay system being built will be relocated from location 60000
upward. Note the use of odd memory sizes and the use of the library
indicator on global .DA to factor that routine out of the non-resident
portion of the overlay structure.
Only link LK1 has an initialized labeled common block XXX, the COMMON
declaration in SUB2 has resulted in the allocation of core within link
LK2 for an uninitialized labeled common block XXX.

NAt'1E :'<CT FILE

>:":FN

LIST OPTIONS & PARAMETERS
>S:;:., PGI':., PAL.., BO·j . 61211~IiW., :,:vt'i.. ~31(
- QUESTIONABLE MEMORY SIZE -- 33K
DEFINE RESIDENT eaCE
)t1AIN,. Dr,,"
DESCRIBE LINKS & STRUCTURE
>L K1==::'I) :: l./B[:Ofl Hi

L r:·:?
-)LK1.
•....

LINK TABLE
060020-060047 000010
RES WENT COCIE

MAIN
. DA
STOP
PAUSE
SPMSG
FlOPS
. FPP
orSER
PAUSE

060050-06014l 000074
012 060144-060220 000055
008 060221-060301 800061
aos 060302- 860315 000014
012 060?16-068434 000117
D40 060435-061655 001221
F18 061656-062315 000440
F14 062316-062538 00021:
#~~n)IZI€I·-·F'

LINK -- LK1
SU81

062531-862570 000840

*** 8LOCK DATA SU8ROUTINE - - BCATA
XXX

PAUSE

062571-862680 000818

#(I(n:l1·-·F"

U NK -- U (2

51.182
XXX

062531-062687 000057
062610-062617 880018
F' f iUS E # ~:H:1I,) ;2"". F'

F'j,USE #77'~'7'~·F·
8LAr~~,:

. xx

COt'lt'1GN
100000-100003 088004

COf<:E f':EG:' D

7-12

Building an Overlay structure

EXAMPLE 4

Block Data subroutines do not have an entry point (filename defined as
a global symbol) and therefore cannot be an external link component.
I

NA t1E :;. :c: T FILE
>:;,:F~l

LIST OPTIONS & PARAMETERS
>::'2 .• PCiF

DEFINE RESIDENT CODE
>t'1A IN
DE SCF.: I E:E L. I NJ<S

I~:

s: r~:UC'1'U~:E

>U(j; SUE:.1. E::[:·H: ,;
>LK2 .~ : ,I ; ,:
>Lf<l : L.I::?

...
,

LINK TABi..E
f~ESIDENT

MAIN

STOP
PRUSE
SPMSG
FlOPS
. FFP
OTSER

CODE

077588-877573 888874
008 QT7417-077477 808861
006 877403-077416 080814
912 077264-0774Q~ 000117
D40 076843-077263 001221
F18 87540~-076042 008440
F14 075178-075482 80 8 21~

L. I NK --' U:.1.

SUBl
~**

8751~8-075167 080848
BLOCK DATA SUBROUTINE -- EDATA

XXX
075128-875127 000010
. DR
012 075041-075117 000055
MISSING GLOBAL DEF -- BDATA

7-13

Building an Overlay Structure

EXAMPLE 5
SUBl and SUB2 have been misspelled in the link definitions.

Since SUBl

and SUB2 are called by the main program, global references for the
symbols SUBl and SUB2 are made.

Neither SUBl nor SUB2 are defined in

a library, nor do they appear as link components.

Therefore, the

attempt to resolve the global references fails.

LIST OPTIONS & PARAMETERS

DEFINE RESIDENT CODE
>i'lRIN

DESCRIBE LINkS & STRUC ~ URE
>L t~::.i. =SJ ,/Bi) r: i n
:> L t( :~~' ~:: :.: 2 ~.I (~D ~j I F.

::..LKl LV ::'
....
L XNr< TABLE
~1?76~~1(-'~~17 ;:'63:'::

f;:ES 1C·EN T COC·E
MAIN

07751,~-077606

,::1(1 ::;: 121(,743:2-1217751;;::
PAUSE 006 (1774:16 - 'ZI7('4 3:1
012 07727("-0,'?41!:i
SPi'iSi3
FlOPS C'4(1 ~17' E; ~15 t: _. i.;J "(' '(' ~~: 'c' E:
F 1::; j.~17·541~:- ~~I('~;O~:i ~i
FPP'
OTSEF<: F14 ~)(52~13:-1Z17!'54:1.~j
UNRESOLVED GLOBAL ( S),

::'TOF'

SUE:l
SU82

7-14

Building an Overlay Structure

EXAMPLE 6
Miscellaneous recoverable errors.

NAi'1E :'-:0 F I L.E
>:·':FN,l': ·
.-. NAi'1E LENGTh ERf':
::'-:'·:FN

LI ST OprrONS & PARAMETERS
)'T'L . USEf;:L , E:KF.: .,:
.-. I i'1PF.:OPER Bf':EAK CHHF.:
>UL USERL}BKR.~VN
~ UNRECOGNIZED SYM80L
~VN
>US.USERL.BKR,XVM
- IMFROFER BREAK CHRR
>UL.USERL,BKR,XVM
DEFINE RESIDENT CODE
::'-i1A I N.... BDATA
- IMFROFER BRERK CHAR
)hi.l N., B£:oATFi
DESCRIBE LINK; & STRUCTURE
>Lf<1 it=::;U81/SC'ATA
~ LIB IND ON LINK NAME -- LKl
)L K 1 ='::; UEi 1,.' B [)AT R
- INTERNAL NAME USED FRV -- BDATA
)LK1=SU81/LE:DATA
::'-LK2~5U81/L8DATA

- EXTERNAL NAME USED PRV -- SUB1
>LD2=5U82/L8DATA
>LKl . LD2 • t·m IN
~ RES ROUTINE NAME USED AS LINK NAME -- MAIN
>It::l . LD2

>LKl . :;US:;:
- NAME USED LEFT OF COLON TWICE -- L.Kl
>'- D2 . SU8:;.
(17 (' 5? 4 -l2I'(' 763:E:

F.:ES WENT CODE
MAIN
077500-077573
~** BLOCK DATA SUBROUTINE
~~17(4 71(1-'~177'4('{1

7-15

CHAPTER 8
EXECUTION OF AN OVERLAY SYSTEM
The program EXECUTE controls the execution of an overlay structure
built with CHAIN.
Before calling EXECUTE, the user should be sure that the "XCT" file
is on the device assigned to .DAT slot -4, and that the .DAT slots required by the overlay system are properly assigned.
EXECUTE is called by typing "EXECUTE" or "E" followed by the XCT filename,

in response to XVM/DOS's $ request.

The command and filename

must be separated by at least one space.
The system loader (.SYSLD) will open and process the XCT file to
determine the overlay system's .DAT slot requirements, load EXECUTE
and any required I/O handlers, and transfer control to EXECUTE.
EXECUTE will announce itself and then open the XCT file named in the
original "E" command, load the Link Table (if any) and the resident
code, and transfer control to the main program.

The order in which

the links are loaded is a function of the overlay system being executed,
a link is loaded whenever control is transferred and the link is
non-resident.
EXECUTE will detect and indicate the following errors:
1.

CAN'T FIT
The overlay system will not fit in the available core.

CAN'T RUN
The overlay system was built with "BANK" addressing and
"PAGE" is on or vice versa.

WRONG MODE
The overlay system was built with "XVM" off and "XVM" is on
or vice versa.

8-1

Execution of an Overlay System

--,
4•

WRONG BOOT

The overlay system was built for a bootstrap address of 32K
and the current bootstrap address is 24K or vice versa.
5.

READ ERR

A portion of the XCT file is unreadable.
EXECUTE reads the XCT file,

from .DAT -4, once prior to entering the

main code in order to set up the Link Tran Table.

The Link Tran Table

consists of a two word entry for each link in the overlay structure.
The first word is the block number within which the link begins and
the second word is the offset within the block to the beginning of the
link.

After this pass is made, the XCT file is closed and not used

again.
The XCT file is not allowed to reside on a non-block device, i.e.,
paper tape, magtape, cards, etc.

8-2

APPENDIX A
THE LINK TABLE
The Link Table is the mechanism by which EXECUTE is able to field calls
to non-resident links.

The Link Table consists of a transfer vector

to and entry point in EXECUTE (EXUTV), a one-word buffer (BUF) for the
AC, and an eleven word entry for each link component.
When CHAIN built the Link Table it created a JMS* to the first word of
the Link Table for each external link component.

At the time the Link

Table is loaded by EXECUTE the proper word in the Link Table is loaded
with the address of the entry point to EXECUTE.
Non-resident Link Table Entry Format

o
DAC BUF
JMS* EXUTV
DAC* .+3
LAC BUF
JMP* .+2
ENTRY
ENTRY+l
LINK NUMBER
BASE ADDRESS
TOP ADDRESS

/ENTRY POINT
/SAVE AC
/CALL EXECUTE
/STORE RETURN ADDRESS
/RESTORE AC.
/ENTER CALLED ROUTINE
/CALLED ROUTINE ENTRY ADDRESS
/CALLED ROUTINE ENTRY ADDRESS+l
/IDENTIFIER FOR EXECUTE
/LOWEST ADDRESS OF LINK
/HIGHEST ADDRESS OF LINK.

Thus, calling a non-resident subroutine transfers control to EXECUTE
pointing to the fourth word of the Link Table entry for the external
link component called.
EXECUTE then performs the following functions:
1.

Fetches the link number from the link table, clears memory
from the lowest address to the highest address of the new
link and loads the link containing the called routine.

Places a LAC .-2 instruction in the third word of the Link
Table entry for each component of the link just loaded.

Places a JMS* EXUTV instruction in the third word of the Link
Table entry for each component of each link overlayed by the
link just loaded.

A-1

The Link Table
4.

Transfers control to the third word of the Link Table entry
for the called routine, which simulates the original call.

While the link is resident, further calls of external components result in a transfer from the Link Table directly to the subroutine.

A-2

APPENDIX B
THE XCT FILE
The XCT file is actually two files, one with an extension of "XCT" and
the other with an extension of "XCU".

Both have the filename given by

the user in response to CHAIN's "NAME XCT FILE" request.
CHAIN writes the XCU file first.

It contains the resident code (link

0) and all of the actual links numbered sequentially from one.

The

last information output is the XCT file which contains the Link Table,
parameters required by EXECUTE, and the .IODEV information required by
.SYSLD.

The XCT file is written in the standard link format (see next

appendix) and is designated link 377777 (octal).

This allows EXECUTE

to load the Link Table by simply loading link 377777.
The XCT file is opened and read by .SYSLD (to retrieve the .IODEV information) and by EXECUTE before the XCU file is opened.

Thus, by not

including the XCT file information at the end of the XCU file, two
passes to the end of a file, each time EXECUTE is loaded, have been
eliminated.

B-1

APPENDIX C
XCT FILE RECORD FORMATS
C.l
C.l.l

TYPE 1 RECORDS
Link ID (Other than Link No. 377777)
lOPS Record Length (word 1)
lOPS Checksum (word 2)
"1" (octal) In the higher order 3 bits of the word
(lxxxxx).
xxxxx is the link number (word 3)

C.l.2

Link No. 377777

One special case of a type 1 record exists.

Since certain information

must be conveyed to both .SYSLD (for allocation and loading of I/O
handlers) and EXECUTE (for proper placement of the links and common
blocks) the type 1 record with a link number of 377777 (octal) has
been reserved for this type of information.

The record format for

this particular type of ID record is as follows.

Each word is de-

scribed and, when necessary, the bits of the word are also described.
lOPS Record length (word 1)
lOPS Checksum (word 2)
Rec~rd Type (lxxxxx (octal»
(word 3)
Link Number (377777 (octal»
(word 4)
First Address of Blank Common (word 5)
Resident Code Entry Point (word 6)
First Address of the Link Table (word 7)
Last Address of the Link Table (word 8)
Lowest Address Used by the Overlay Structure (word 9)
Highest Address Used by ~he Overlay Structure (word 10)
Operating Environment Indicators (word 11)
Bits 0-11 -- number of blocks in the XCU file.
Bit 12

unused

Bit 13

Operating system indicator

o implies that the overlay structure was built
under DOS-15.
1 implies that the overlay structure was built
under XVM/DOS.

C-l

XCT File Record Formats

Bit 14 -- Bootstrap location.
Bit 14=0 implies that the bootstrap resides at 57636
(octal) .
Bit 14=1 implies that the bootstrap resides at 77636
(octal) .

Bit 15 -- XVM mode bit
Bit 15=0 implies that the XM15 option should be disabled
to run the overlay structure.
Bit 15=1 implies that the XM15 option should be enabled
to run the overlay structure.

Bit 16 -- Addressing mode
Bit 16=0 implies that the overlay structure will run in
PAGE mode.
Bit 16=1 implies that the overlay structure will run in
BANK mode.

Bit 17 -- reserved (currently unused)

.DAT Slots -18 through -1 (word 12)
.DAT Slots -1 through -17 (word 13)
.DAT Slots -18 through -35 (word 14)
.DAT Slots -36 through -53 (word 15)
Extended Memory Limits (word 16) :
If the contents of this word are positive and non-zero then
.SCOM+76 (the lower limit of extended memory) is set to this
value.
If the contents of this word are zero then .SCOM+76 and
.SCOM+77 (the lower and higher limits of extended ·memory) are
left alone and not initialized.
If the contents of this word are negative then .SCOM+76 (the
lower limit of extended memory) is set to the two's complement
of this word.
RESERVED -- Currently unused (word 17)
NOTE
When link 377777 (octal) is loaded by EXECUTE,
the Link Table is loaded into memory. When
link 000000 is loaded the resident code portion
of the overlay structure is loaded into memory.
C.2

TYPE 2 RECORDS (CONTIGUOUS MEMORY INITIALIZATION)
lOPS Record Length (word 1)
lOPS Checksum (word 2)
C-2

XCT File Record Formats

Record Identification - (2) in the high order three bits
(0 to 2) of the word, followed by the number of contiguous
words to be initialized. The word format is "2XXXXX" where
2 is the record type and XXXXX is the number.
(word 3)
Starting Address of the Memory Area to be Initialized (word 4)
Number of Words to be Stored in Memory - XXXXX number of
words to be stored in memory starting at the specified
address given in the previous word and incrementing that
address by one for each word stored.
(word 5)
C.3

TYPE 3 RECORD (PATCH ADDRESS)
lOPS Record Length (word 1)
lOPS Checksorn (word 2)
Record type identifier (3) in the high order three bits
(0 to 2) of the word followed by the total number of patches
to be made for this link of the overlay structure. For
example, "3XXXXX" where 3 is the record type and XXXXX is
the number of patches.
(word 3)
Number of patches contained in the current input record.

(word 4)

Patch records at two words per record - Patch descriptor
in the high order three bits (0 to 2) of the word followed
by the address, i.e., "NXXXXX" where XXXXX is the address
to be patched and N is the type of patch to perform.
(word 5)
N=O implies the second word of the patch record is to be
stored at address XXXXX.
N=l implies that the second word of the patch record is
to be stored in the address field (12 or 13 bits depending
on the type of addressing) of the instruction located at
XXXXX.
N=2 implies that the base address of blank cornmon is to be
added to the second word of the patch record and the result
stored at XXXXX.

C-3

APPENDIX D
CORE ALLOCATION DURING CHAIN
Core map #1 is representative of

CB~IN

during the link and overlay

description entry, prior to the beginning of relocation of the links.
Core map #2 is representative of CHAIN during the relocation of the
resident code and the links.
#1

BOOTSTRAP

CHAIN

- --- - -TTL's

(command
input code)

LINK TABLE
free core
SYMBOL
TABLES
TTL's

ODT

PATCH
TABLES

LDT

RCL

NCL

.SCOM+2

The core used the NCL (Named Common List, generated by the use of the
VTC and RES options), the RCL (Resident Code List), and the LDT (Link
Definition Table), and ODT (Overlay Description Table), and the TTL's
(Trunk-to-Twig Lists) is shown here to help when reading the program
listing.

This information is not necessary for the proper usage of

CHAIN.

D-1

APPENDIX E
CORE ALLOCATION DURING EXECUTE
E.l

TOP-DOWN ALLOCATION WITH NO EXTENDED MEMORY

BOOTSTRAP
OVERLAY SYSTEM

-TOP OF
LOW CORE

Blank Common
.SCOM+3

FREE CORE

.SCOM+2
EXECUTE, ITS I/O
HANDLER, AND ANY
ADDITIONAL
HANDLERS REQUIRED
BY THE OVERLAY
SYSTEM
RESIDENT MONITOR

E-l

Core Allocation During Execute

E.2

TOP-DOWN ALLOCATION WITH EXTENDED MEMORY

RESIDENT
COMMON
BLOCKS

TOP OF
EXTENDED
MEMORY

.XX (blank common)
• SCOM+7 "J..
FREE CORE
.SCOM+7 6

BOOTSTRAP

OVERLAY SYSTEM
.SCOM+3

FREE CORE

.SCOM+2
EXECUTE AND
I/o HANDLERS

E-2

/TOP OF
LOW MEMORY

Core Allocation During Execute

E.3

BOTTOM-UP ALLOCATION WITH NO EXTENDED MEMORY

BOOTSTRAP
UNUSED

.XX (blank common)
OVERLAY SYSTEM
LINK TABLE
.SCOM+3

FREE CORE

.SCOM+2
EXECUTE AND I/O
HANDLERS

RESIDENT MONITOR

E-3

TOP OF
LOW MEMORY

Core Allocation During Execute

E.4

BOTTOM-UP ALLOCATION WITH EXTENDED MEMORY

.SCOM+77r-.

TOP OF
EXTENDED
MEMORY

FREE CORE
.SCOM+76
.XX (blank common)
RESIDENT
COMMON
BLOCKS
BOOTSTRAP
-

UNUSED

OVERLAY SYSTEM

.SCOM+3

LINK TABLE

FREE CORE

.SCOM+2
EXECUTE AND
I/O HANDLERS
RESIDENT MONITOR

E-4

TOP OF
LOW MEHORY

APPENDIX F

ALPHABETICAL LIST OF CHAIN MESSAGF.S
The following contractions and symbols are used throughout this
appendix:
RES

Resident

PRV

DEF

Definition

LIB

Library

IND

Indicator

BLK

Rlock

ERR

Error

ABS

Absolute

PROG

Program

rtnnam

Routine Name

blknam

Common Block ~ame

glbsym

External Global Symbol

symbol

Any of the above

brkchr

Break Character

Inknam

Link Name
CHAIN Error Messages

ABS PROG
MEANING:

An element of code being CHAINed is not a relocatable

binary module.

CHAIN is terminated and control is returned to XVM/

DOS.
RECOVERY:

Reassemble the module in qUestion as relocatable binary

and rerun CHAIN.
ABSOLUTE LOAD ADDRESS
MEANING:
address.

A module has been read which has an absolute starting

CHAIN is unable to relocate the module and control is re-

turned to XVM/DOS.

F-l

Alphabetical List of Chain Messages

RECOVERY:

Reassemble the module in question and rerun CHAIN.

BLANK COMMON
MEANING:
Blank Common.

CHAIN is about to print the top and bottom limits of

***BLOCK DATA SUBROUTINE -- rtnnam
MEANING:

CHAIN has encountered a block data subroutine with

the name "rtnnam".
CHAIN XVM VnAxxx
MEANING:

CHAIN is announcing its presence prior to accepting

user commands.

This message will appear every time tP is used to

restart CHAIN during the options processing section.
tCOLON MUST FOLLOW FIRST LINK NAME
MEANING:

The user has entered an overlay description in which

the first break character is not a ":".

The current input line is

ignored.
RECOVERY:

Reenter the line correctly.

COMMON BLOCK TOO BIG -- blknam
MEANING:

The user has attempted to allocate a common block

larger than 77777 (octal, 32K-l) in length.
question appears in the message.

~he

name of the block in

CHAIN terminates and control is re-

turned to XVM/DOS.
RECOVERY:

Correct the error in the appropriate module, recompile

or reassemble it, and rerun CHAIN.
tCOMPONENT NAME USED AS LINK NAME
MEANING:

An element of an overlay description not specified

in the link description has the same name as a previously defined
link.

The current input line is ignored.

F-2

....."

Alphabetical List of Chain Messages

RECOVERY:

Correct the error by either redefining the previously

entered links to avoid using the component name or rename and recompile
the appropriate overlay component to avoid using the same link name.
CORE REQ'D
MEANING:

CHAIN is about to list the upper and lower core limits

of the overlay structure just built.
DEFINE RESIDENT CODE
MEANING:

CHAIN is requesting the user to enter those modules

which are to be permanently resident throughout the running of the
overlay structure to be built.

The input format has been discussed

in previous sections.
DESCRIBE LINKS AND STRUCTURE
MEANING:

CHAIN is requesting the user to enter the link descrip-

tions and the overlay structure to be built.

Tht link descriptions

are entered first followed by the overlay descriptions.

The format of

the link and overlay descriptions has been discussed earlier.
DUPLICATE GLOBAL DEF -- glbsym
MEANING:

The symbol printed with the message has appeared at

least once within the link as an internal global symbol name.

CHAIN

terminates and control is returned to XVM/DOS.
RECOVERY:

The user must correct the error in the appropriate

module, reassemble or recompile the module, and rerun CHAIN.
tEXTERNAL NAME USED PRV
MEANING:
link.

An external module name has appeared in more than one

The current input line is ignored.
RECOVERY:

Enter the corrected line and continue with the defini-

tion of links and overlays.

F-3

Alphabetical List of Chain Messages

GLOBAL SYMBOL TOO BIG -- symbol
MEANING:

The user has attempted to reference an area beyond the

scope of the given symbol.

This error usually occurs when utilizing

the common block definition facilities of MACRO XVM.

The module within

which the error occurs will be the last module displayed in the memory
map.
RECOVERY:

Correct the appropriate module, reassemble or recom-

pile the module, and rerun CHAIN.
HIGH CORE OVERFLOW -- symbol
MEANING:

The given symbol would not fit in high memory (above 32K)

and was required to be there, i.e., it was the target of the RES option.
CHAIN terminates and control is returned to XVM/DOS.
RECOVERY:

Rerun CHAIN with the appropriate common block speci-

fied without the RES option being applied.
ILLEGAL ATTEMPT TO INITIALIZE COMMON BLOCK -- blknam
MEANING:

The user has attempted to perform one of the following

actions:
1.

Attempted to initialize a common block with the RES switch
applied to it.

Attempted to initialize a common block associated with the
"resident" code from a link.

Common blocks become part of the

resident code if either the SAC option or the RES option applies
to them.
CHAIN terminates and control is returned to XVM/DOS.
RECOVERY:

Alter the appropriate module to either not initialize

the common block in question

or initialize a different one.

or recompile the module and rerun CHAIN.

F-4

Reassemble

Alphabetical List of Chain Messages

ILLEGAL LOADER CODE
MEANING:

CHAIN has detected an unrecognizable loader code.

CHAIN

terminates and control is returned to XVM/DOS.
RECOVERY:

Verify that all modules are binary modules.

If all

modules are good then reassemble appropriate modules and rerun CHAIN.
tIMPROPER BREAK CHARACTER -- brkchr
~NG:

The character displayed is not a valid character within

the context of the option selected, i.e., using a colon inside a RES
or VTC list.

The current line is ignored.

RECOVERY:

Enter the corrected line and proceed with CHAIN.

tINTERNAL NAME REPEATED IN LINE
MEANING:

The user has used an internal name as a symbol in a

previous part of the internal specification of the link.

The current

line is ignored.
RECOVERY:

Enter the correct line and continue with CHAIN.

tINTERNAL NAME USED PRV
MEANING:

The user has entered an internal component name which

is the same as a previosuly defined external component.

The current

input line is ignored.
RECOVERY:

Enter the correct line or restart CHAIN and redefine

the link and overlay descriptions properly.
LABELED COMMON BLK SIZE ERR -- blknam
MEANI NG:

The user has attempted to change the size of the speci-

fied common block after it has been defined.
was to make it larger.

The size change attempted

CHAIN terminates and control is returned to

XVM/DOS .
RECOVERY:

Change the appropriate common block definition, re-

assemble or recompile the changed module, and rerun CHAIN.
F-5

Alphabetical List of Chain Messages

tLIB IND ON LINK NAME
MEANING:
(¥)

The user has incorrectly applied the library indicator

to a link name.
RECOVERY:

The current input line is ignored.

Enter the correct line and continue with CHAIN.

LINK -- lnknam
MEANING:

CHAIN is announcing the beginning of the relocation of

a new link.
tLINK DEF WITHIN OVERLAY DESCRIPTION
MEANING:

The user has entered a new link definition after the

first overlay description has been processed.

The current input line

is ignored.
RECOVERY:

If the link definition is unnecessary the user may simply

continue with the overlay descriptions.

If the link definition is

necessary then the user must restart CHAIN and reenter all previous
data along with the new link definition.
tLINK NAME USED PRV
MEANING:

The user has used a link name which was used previously.

The current input line is ignored.
RECOVERY:

Enter the line with a new link name.

LINK TABLE
MEANING:

CHAIN is about to print the lower and upper bounds of

the link table necessary to the proper execution of the overlay structure to be built.
LIST OPTIONS AND PARAMETERS
MEANING:

CHAIN is requesting the user to enter a list of pro-

cessing options which will define the environment in which the overlay
structure will run.

F-6

Alphabetical List of Chain Messages

LOW CORE OVERFLOW
MEANING: The executable code portion, including initialized
common blocks, of the overlay structure defined by the user will not
fit into the available core.

CHAIN terminates and control is returned

to XVM/DOS.
RECOVERY:

The user has two options.

memory (above 32K), if possible.

The first is to use extended

The second is to redesign the overlay

structure in an attempt to reduce the core limits necessary to run the
program.
MISSING GLOBAL DEF -- glbsym
MEANING:

The symbol "glbsym" was specified as a link component

but was not resolved during the relocation process.

CHAIN terminates

and control is returned to XVM/DOS.
RECOVERY:

Make sure that the appropriate module has the correct

internal .GLOBL specifications.

Modify the module, reassemble or re-

compile it, and rerun CHAIN.
tMORE THAN ONE LINK OVERLAYED
MEANING:

The user has entered an overlay description which re-

quires that one link be overlayed by more than one link.

The current

input line is ignored.
RECOVERY:

The user may either correct the line if

it is in

error or restart CHAIN and redefine the link and overlay descriptions
in order to avoid the error.
tNAME LENGTH ERR
MEANING:

The user has entered a name which is either null (con-

sisting of no characters) or too long (consisting of more than six
characters).
RECOVERY:

The current input line is ignored.
Enter the correct line and continue with CHAIN.

F-7

Alphabetical List of Chain Messages

tNAME RIGHT OF COLON USED PRV
MEANING:

The user has entered an overlay description which requires

one link to overlay more than one other link at a time.
ILl:L2" and IL3:L2" would cause the error.
ignored.

For example,

The current input line is

RECOVERY:
Enter the correct line or restart CEAIN and redefine
the link properly.
+NAME USED LEFT OF COLON TWICE
MEANING:

The user has entered an overlay description which would

require one link to be overlayen by multiple links.

The current input

line is ignored.
RECOVERY:

Enter the correct line if possible or restart CHAIN

and redefine the link and overlay descriptions appropriately.
+NAME USED MORE THAN ONCE
MEANING:

The user has requested the same module twice when defin-

ing the resident code.
RECOVERY:

The current input line is ignored.

Enter the correct resident code definition and continue

with CHAIN.

tNAME USED MORE THAN TWICE
MEANING:

The user has entered an overlay description in which the

following construct has been detected " ..• :Ll: ... " and the link Ll
also appears elsewhere in the overlay description.

The current input

line is ignored.
RECOVERY:

Enter the correct line if possible or restart CHAIN

and redefine the links and overlays so as to avoid the error.
NAME XCT FILE
MEANING:

CHAIN is requesting the user to enter an output file name.

The file named will become the XCT and XCU files output by CHAIN.

F-8

Alphabetical List of Chain Messages

NON-FILE ORIENTED INPUT DEVICE
MEANING:

One of CHAIN's input .DAT slots is assigned to a non-

directoried device.
DOS.

CHAIN terminates and control is returned to XVM/

RECOVERY:

Reassign the appropriate .DAT slot and rerun CHAIN.

MEANING:

The user has entered either the PAR or PAL options.

RECOVERY:

To allow CHAIN to continue processing enter tP.

PAUSE

tQUESTIONABLE MEMORY SIZE
MEANING:
multiple of 8.

The user has entered a core size (nnnK) which is not a
The message is only a warning and CHAIN will correctly

build the overlay for the desired memory size.
READ ERROR
MEANING:

An unrecoverable I/O error was detected during the

processing of input files.

CHAIN terminates and control is returned

to XVM/DOS.
RECOVERY:

Reassemble the appropriate file and rerun CHAIN.

the problem persists and cannot be accounted for call your DEC field
service office.
tRES ROUTINE NAME USED AS LINK NAME
MEANING:

The last link name used is the same as one of the routines

defined to be an element of the resident code.

The current input line

is ignored.
RECOVERY:

Choose another link name and reenter the link defini-

tion rejected by CHAIN.

F-9

Alphabetical List of Chain Messages

tRES ROUTINE REQ'D
MEANING:

The user has attempted to build an overlay structure

with no resident code section.
RECOVERY:

The current input line is ignored.

Define a set of resident code before continuing with

CHAIN.
RESIDENT CODE
MEANING:

CHAIN is about to print the memory map of the resident

code section.
RESIDENT COMMON BLOCKS
MEANING:

CHAIN is about to print a list of all common blocks

associated with the resident code section of the overlay structure.
Blank common is excluded from this list and is printed separately.
TABLE OVERLAP
MEANING:
core.

The internal tables used by CHAIN have run out of free

CHAIN terminates and control is returned to XVM/DOS.
RECOVERY:

Build the overlay structure in a machine with more

core if possible (32K instead of 24K). Otherwise, redesign the overlay structure to reduce the number of symbols kept in CHAIN's internal
tables.
tUNRECOGNIZED SYMBOL
MEANING:
nized.

The user entered an option to CHAIN which was not recog-

The current input line is ignored.

RECOVERY:

Enter the correct option and continue with CHAIN.

UNRESOLVED GLOBALS:
MEANING:

CHAIN is about to print a list of global symbols which

were not resolved during the relocation process.

CHAIN terminates

after printing the symbols and control is returned to XVM/DOS.

F-10

Alphabetical List of Chain Messages

RECOVERY:
Include the appropriate modules in the proper link to
define the missing global symbols.
tZERO LENGTH LIBRARY NAME
MEANING:

The user has entered a null (consisting of zero char-

acters) name to the UL or SL options.

The current input line is

ignored.
RECOVERY:

Enter the correct library name and continue with chain.

F-ll

INDEX

Abbreviations for parameters,

7-2
ALTMODE, 7-9
Angle bracket «)usage, 7-·2,
7-10

Global search, 7-4
Global symbol load map, 7-3
GLOBAL symbol references, 5-1

Handlers, 2-1
Bank boundaries, 2-3
Bank COnlllland option, 5-1
Bank mode, 8-1
Bank relocation, 7-2
Batch mode, 7-1
Blank COMMON, 2-2
Block size, 7-4
Bootstrap, 7-3, 8-2
Break characters, 7-1

Calling CHAIN, 7-1
CHAIN error messages, F-l
Colon (:) usage, 7-7
Command input, 7-1
termination of, 7~8
Comma (,) usage, 7-7
Common blocks, 7-4, 7-10
Core
allocation, 0-1, E-l
locations, 7-10
mapping, 7-8
overlays, 1-1
see also Memory
Co-routines, 2-1

.DAT slots, 8-1
Device assignments, 6-1

Entry point, 4-1
Error in input line, 7-1
Error messages, F-l
Execution of an overlay
structure, 8-1
Extended memory, 7-3, 7-4
External link components, 2-1,
5-1, 7-6

Filenames, 4-1

Input, 7-1
Internal link components, 2-1,
7-6
I/O device assignments, 6-1

Labeled COMMON, 2-2
Library indicators (#), 3-1, 5-1
Library routines, 2-1, 7-5
Library search, 7-4
Line (definition mf), 7-7
continuation and termination,
7-1
Link
components, 2-1
definitions, 7-5
loading, 1-1
names, 7-5
overlaid, 1-1
relocation, 5-1, 7-3
table, 2-3, A-l
Load map, 7-3, 7-10
Locations, 7-5
Logical lines, 7-1

Memory
allocation, 0-1, E-l
map, 7-3
size, 7-5
see also Core
Memory, extended, 7-3, 7-4
Mode values, 7-5

Named common blocks, 7-4
Names
of files, 4-1
of links, 7-5
of routines, 2-1
with VTC option, 2-3
Number sign (#), 3-1

Index-l

INDEX (Cant.)
Options, 7-2
Option VTC (CHAIN), 2-3
Overlay structure, 7-6
Overlay systems, 2-1

Page command option, 5-1
Page mode, 8-1
Page relocation, 7-4
Parameter abbreviations, 7-2
tP command, 7-1, 7-3, 7-9
Pound sign (#), 3-1

Recovery from errors, 7-2
Relocation, 5-1
Resident code
definition, 7-5
relocation, 7-3
Resident routines, 2-1
RES option, 2-3, 7-4
Routine size, 7-4
Routines, 2-1
RUBOUT, 7-1

SAC (Single Allocation of
Commons) option, 2-2
Size of the link table, common
blocks, and routines, 7-4
Structure definition, 7-5
Subroutines, 2-1
System library, 5-2
System loader, 8-1
Symbol table, 5-1

Table size, 7-4
Termination of command input, 7-8

tu command, 7-1
User's library, 5-2

VTC option (CHAIN); 2-3, 7-4

XCT file, 8-1, B-1
record formats, C-l
XVM ON/OFF, 7-3, 7-5, 8-1

INDEX-2

CHAIN XVM/EXECUTE XVM
Utility Manual
DEC-XV-UCHNA-A-D

READER'S COMMENTS
NOTE:

This form is for document corrments only.
Problems
with software should be re p orted on a Software
Problem Repcrt (SPR) form.

Did you find errors in this rr.anual?

If so, specify by page.

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

Is there sufficient documentation on associated system programs
required for use of the software described in this manual? If not,
what material is missing and where should it be placed?

Please indicate the type of user/reader that you most nearly represent.
[] Assembly language programmer
[]

Higher-level language programmer

[]

Occasional programmer (experienced)

[] User with little programming experience
[] Student programmer
[] Non-programmer interested in computer concepts and capabilities
Name

Date ___________________________

Organization __________________________________________________________________
Street ______________________________________________________________________
City ___________________________ State _____________ Zip Code ______________
or
Country
If you require a written reply, please check here.

[]

.------------------------------------------------------------Fold flere------------------------------------------------------------

-"
.----------------------------------------------- Do Not Tear - «'old flcre and Staple -----------------------------------------------

FIRST CLASS
PERMIT NO. 33
MAYNARD, MASS .
BUSI)\;ESS REPLY MAIL
)\;0 POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES

Postage will be p aid by:

Software Communications
P. O. Box F
Maynard, Massachusetts 01754

digital equipment corporation

PRINTED IN U.S.A.