Digital PDFs

AA-H266A-TC

June 1979

333 pages

Original

12MB

Document:	RSX-11M/M-PLUS Task Builder Manual
Order Number:	AA-H266A-TC
Revision:	0
Pages:	333
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V3.2_Jun79/3A_ProgramDevelopment/AA-H266A-TC_RSX-11M_V3.2_Task_Builder_197906.pdf

OCR Text

RSX-11 M/M-PLUS
Task Builder Manual
Order No. AA-H266A-TC

RSX-11 M Version 3.2
RSX-11M-PLUS Version 1.0

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

digital equipment corporation "maynard, massachusetts

First Printing, June 1979
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.

@) 1979 by Digital Equipment Corporation

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
DEC US
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-11
VAX
DECnet
DATATRIEVE

DECsystem-lo
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8
VMS
IAS
TRAX

7/80-14

MASS BUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-11
TMS-11
ITPS-10
SBI
PDT

CONTENTS
Page
PHEFACE

SUMMARY OF TECHNICAL CHANGES

CHAPTER

INTRODUCTION AND COMMAND SPECIFICATIONS

1-1

1.1
1.2
1.3
1. 4
1.5
1.6
1. 7
1.8

TASK COMMAND LINE
MULTIPLE LINE INPUT
OPTIONS
MULTIPLE TASK SPECIFICATIONS
INDIRECT COMMl\ND FILES
COMMENTS IN LINES
FILE SPECIFICATIONS
SUMMARY OF SYNTAX RULES

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

TASK BUILDER FUNCTIONS

2-1

2.1
2 .1.1

2-1

2.2
2.2.1
2.2.2
2.3
2.4

LINKING OBJECT MODULES
Allocating Program Sections
Resolving Global Symbols
ASSIGNING ADDRESSES
unmapped Systems
Mapped Systems
BUILDING SYSTEM DATA STRUCTURES
TASK RELOCATION ON MAPPED SYSTEMS

TYPICAL TASK BUILDER FACILITIES

3-1

3.1

SHARED REGIONS
3-1
The Symbol Definition File
3-3
Position-Independent Shared Regions
3-3
Absolute Shared Regions
3-6
Linking to a Shared Region
3-6
Example 1: Building and Linking to a Common
in MACR0-11
3-11
Example 2: Building and Linking to a Device
Common in MACR0-11
3-19
Example 3: Building and Linking to a
Resident Library in MACR0-11
3-23
Example 4: Building and Linking to a
Supervisor-Mode Library in MACR0-11
(RSX-llM-PLUS Only}
3-32
EXAMPLE 5: BUILDING A MULTIUSER TASK
(RSX-llM-PLUS ONLY}
3-44
EXAMPLE 6: BUILDING A TASK THAT CREATES A
DYNAMIC REGION
3-50
VIRTUAL PROGRAM SECTIONS
3-53
FORTRAN Run-Time Support for Virtual Program
Sections
3-56
Example 7: Building a Program that uses a
Virtual Program Section
3-59
EXAMPLE 8: PRIVILEGED TASKS
3-62

2 .1. 2

CHAPTER

3 .1.1

3 .1.2
3 .1. 3
3 .1. 4
3 .1. 5
3 .1. 6

3 .1. 7

3 .1. 8

3.2
3.3

3.4
3.4.1
3.4.2

3.5

iii

1-7

1-8
1-9

2-2
2-7

2-8
2-8
2-10
2-14
2-15

CONTENTS
Page
CHAPTER

OVERLAY CAPABILITY

4-1

4.1
4 .1.1
4 .1. 2

4-1
4-2

4.7
4.8

OVERLAY STRUCTURES
Disk-Resident Overlay Structures
Memory-Resident Overlay Structures (Not
Supported on RSX-118)
OVERLAY TREE
Loading Mechanism
Resolution of Global Symbols in a
Multisegment Task
Resolution of Global Symbols from the
Default Library
Allocation of Program Sections in a
Multisegment Task
OVERLAY DATA STRUCTURES AND RUN-TIME ROUTINES
OVERLAY DESCRIPTION LANGUAGE
.ROOT and .END Directives
.FCTR Directive
Exclamation Point Operator
.NAME Directive
.PSECT Directive
Indirect Command Files
MULTIPLE-TREE STRUCTURES
Defining a Multiple-Tree Structure
Multiple-Tree Example
OVERLAYING PROGRAMS WRITTEN IN A HIGH-LEVEL
LANGUAGE
EXAMPLE 9: BUILDING AN OVERLAY
SUMMARY OF THE OVERLAY DESCRIPTION LANGUAGE

OVERLAY LOADING METHODS

5-1

5.1
5 .1.1
5 .1. 2
5 .1. 3
5 .1. 4
5.2
5.2.1
5.2.2
5.3
5.4

AUTO LOAD
Autoload Indicator
Path Loading
Autoload Vectors
Autoloadable Data Segments
MANUAL LOAD
MACR0-11 Manual Load Calling Sequence
FORTRAN Manual Load Calling Sequence
ERROR HANDLING
GLOBAL CROSS-REFERENCE OF AN OVERLAID TASK

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

SWITCHES AND OPTIONS

6-1

6.1
6 .1.1
6 .1. 2
6 .1. 3
6 .1. 4
6 .1. 5
6 .1. 6
6 .1. 7
6 .1. 8
6 .1. 9
6 .1.10
6.1.11
6 .1.12

SWITCHES
/AC[:n] -- Ancillary Control Processor
/AL
Allocate Checkpoint Space
/CC
Concatenated Object Modules
/CM
Compatibility Mode Overlay Structure
/CP
Checkpointable
/CR
Cross-Reference
/DA
Debugging Aid
/DL
Default Library
/EA
Extended Arithmetic Element
/FP
Floating Point
/FU
Full Search
/HD
Header

6-1
6-5
6-6
6-7
6-8
6-9
6-10
6-12
6-13
6-14
6-15
6-16
6-17

4.2
4.2.1
4.2.2
4.2.3
4.2.4
4.3
4.4
4.4.1
4.4.2
4.4.3
4.4.4
4.4.5
4.4.6
4.5
4.5.1
4.5.2
4.6

CHAPTER

4-5
4-15
4-16
4-16
4-18
4-19
4-20
4-22
4-22
4-24
4-24
4-25
4-27
4-27
4-28
4-28
4-29
4-34
4-34
4-42

CONTENTS
Page
6 .1.13
6. 1. 14
6 .1.15
6 .1.16
6.1.17
6 .1.18
6 .1.19
6.1.20
6.1.21
6 .1. 22
6.1.23
6.1.24
6.1.25
6.1.26
6 .1. 27
6.1.28
6.1.29
6.1.30
6.2
6.2.l
6.2.2
6.2.3
6.2.4
6.2.5
6.2.6

6.2.25
6.2.26
6.2.27
6.2.28
6.2.29
6.2.30

/LB
Library File
/MA
Map Contents of File
0
/MM
Memory Management
/MP
Overlay Description
/MU
Multiuser
/PI
Position Independent
/PM
Postmortem Dump
/PR[:n] -- Privileged
/RO
Resident Overlay
/SE
Send
/SH
Short Map
/SL
Slave
/SP
Spool Map Output
/SQ
Sequential
/SS
Selective Search
/TR
Traceable
/WI
Wide Listing Format
/XT[:n] -- Exit on Diagnostic
OPTIONS
ABORT -- Abort the Task-Build
ABSPAT -- Absolute Patch
ACTFIL -- Number of Active Files
ASG -- Device Assignment
CMPRT -- Completion Routine
COMMON or LIBR -- System-Owned Resident
Common or System-Owned Resident Library
EXTSCT
Program Section Extension
EXTTSK
Extend Task Memory
FMTBUF
Format Buffer Size
GBLDEF
Global Symbol Definition
GBLPAT
Global Relative Patch
GBLREF
Global Symbol Reference
GBLXCL
Exclude Global Symbols
LIBR -- System-Owned Library
MAXBUF -- Maximum Record Buffer Size
ODTV -- ODT SST Vector
PAR -- Partition
PRI -- Priority
RESCOM or RESLIB -- Resident Common or
Resident Library
RESLIB -- Resident Library
RESSUP -- Resident Supervisor-Mode Library
ROPAR -- Read-Only Partition -- RSX-llM-PLUS
Only
STACK -- Stack Size
SUPLIB -- Supervisor-Mode Library -RSX-llM-PLUS Only
TASK -- Task Name
TSKV -- Task SST Vector
UIC -- User Identification Code
UNITS
Logical Unit Usage
VSECT -- Virtual Program Section
WNDWS -- Number of Address Windows

6-73
6-74
6-75
6-76
6-77
6-78
6-79

HOST AND TARGET SYSTEMS

7-1

7.1
7.2

INTRODUCTION
EXAMPLE: TRANSFERRING A TASK FROM A HOST TO
A TARGET SYSTEM

7-1

6.2.7
6.2.8
6.2.9
6.2.10
6.2.11
6.2.12
6.2.13
6.2.14
6.2.15
6.2.16
6.2.17
6.2.18
6.2.19
6.2.20
6.2.21
6.2.22
6.2.23
6.2.24

CHAPTER

6-18
6-20
6-21
6-22
6-23
6-24
6-25
6-26
6-27
6-28
6-29
6-36
6-37
6-38
6-39
6-42
6-43
6-44
6-45
6-48
6-49
6-50
6-51
6-52
6-53
6-54
6-55
6-56
6-57
6-58
6-59
6-60
6-61
6-62
6-63
6-64
6-65
6-66
6-68
6-69
6-71
6-72

7-2

CONTENTS
Page
CHAPTER

MEMORY DUMPS

8-1

8.1
8.2
8.2.1
8.2.2
8.2.3

POSTMORTEM DUMPS
SNAPSHOT DUMP
Format of the SNPBK$ Macro
Format of the SNAP$ Macro
Example of a Snapshot Dump

8-1
8-5
8-6
8-7
8-8

TASK BUILDER INPUT DATA FORMATS

A-1

DECLARE GLOBAL SYMBOL DIRECTORY RECORD
Module Name (Type O)
Control Section Name (Type 1)
Internal Symbol Name (Type 2)
Transfer Address (Type 3)
Global Symbol Name (Type 4)
Program Section N.ame (Type 5)
Program Version Identification (Type 6)
Mapped Array Declaration (Type 7)
Completion Routine Definition (Type 10)
END OF GLOBAL SYMBOL DIRECTORY RECORD
TEXT INFORMATION RECORD
RELOCATION DIRECTORY RECORD
Internal Relocation (Type l)
Global Relocation (Type 2)
Internal Displaced Relocation (Type 3)
Global Displaced Relocation (Type 4)
Global Additive Relocation (Type 5)
Global Additive Displaced Relocation
(Type 6)
Location Counter Definition (Type 7)
Location Counter Modification (Type 10)
Program Limits (Type 11)
Program Section Relocation (Type 12)
Program Section Displaced Relocation
(Type 14)
Program Section Additive Relocation
(Type 15)
Program Section Additive Displaced
Relocation (Type 16)
Complex Relocation (Type 17)
Resident Library Relocation (Type 20)
INTERNAL SYMBOL DIRECTORY RECORD
END OF MODULE RECORD

A-2
A-4
A-5
A-5
A-6
A-6
A-7
A-10
A-10

DETAILED TASK IMAGE FILE STRUCTURE

B-1

LABEL BLOCK GROUP
CHECKPOINT AREA
HEADER
Low-Memory Context
Logical Unit Table Entry
TASK IMAGE
Autoload Vectors
Segment Descriptor
Window Descriptor
Region Descriptor
Supervisor-Mode Vectors (RSX-llM-PLUS
Only)

B-1
B-7
B-7
B-8
B-12
B-12
B-14
B-14
B-16
B-16

APPENDIX A
A. l
A.1.1
A.l. 2
A.1.3
A.l. 4
A.l. 5
A.1.6
A.l. 7
A.1.8
A. l . 9
A. 2
A. 3
A.4
A. 4 .1
A. 4. 2
A.4.3
A.4.4
A. 4. 5
A. 4. 6

A.4.7
A. 4. 8
A.4.9
A.4.10
A. 4 .11

A.4.12
A.4.13
A.4.14
A.4.15
A.5
A. 6
APPENDIX B
B.l
B.2
B.3
B.3.1
B.3.2
B.4
B.4.1
B.4.2
B.4.3
B.4.4
B.4.5

A-11
A-11
A-11

A-12
A-14
A-15
A-15
A-16
A-16
A-17
A-18
A-18
A-18
A-19
A-19
A-20
A-21
A-22
A-23
A-24
A-24

B-17

CONTENTS
Page
APPENDIX c

RESERVED SYMBOLS

C-1

APPENDIX D

IMPROVING TASK BUILDER PERFORMANCE

D-1

EVALUATING AND IMPROVING TASK BUILDER
THROUGHPUT
Overlay Latency
Table Storage
Input File Processing
Summary
MODIFYING COMMAND SWITCH DEFAULTS
THE SLOW TASK BUILDER

D-1
D-2
D-2
D-7
D-7
D-7
D-11

APPENDIX E

THE FAST TASK BUILDER

E-1

APPENDIX F

ERROR MESSAGES

F-1

D.l
D.1.1
D.1.2
D.1.3
D.1.4
D.2
D.3

Index-1

INDEX
FIGURES
FIGURE

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

2-5
2-6
2-7
2-8
2-9
2-10
2-11
3-1
' 3-2
3-3

3-4
3-5
3-6
3-7
3-8
3-9
3-10
3-11
3-12
3-13
3-14
3-15
3-16
3-17
3-18
3-19
3-20
3-21
3-22

Relocatable Object Modules
Modules Linked for Mapped and Unmapped Systems
Allocation of Task Memory
Unmapped Memory
Layout for Unmapped System
Task Relocation in a Mapped System
Memory Management Unit's Division of Virtual
Address Space
Mapping for 4K Word and 6K Word Tasks
Disk Image
Memory Image
Window Block 0
Typical Resident Conunon
Typical Resident Library
Specifying APRs for a Position-Independent
Shared Region
Mapping for an Absolute Shared Region
Windows for Shared Region and Referencing Task
Common Area Source File in MACR0-11
Task Builder Map for MACCOM.TSK
Allocation Diagram for MACCOM.TSK
MACR0-11 Source Listing for MCOMl
MACR0-11 Source Listing for MCOM2
Assigning Symbolic References Within a Common
Task Builder Map for MCOMl.TSK
Assembly Listing for TTCOM
Task Builder Map for TTCOM
Assembly Listing for TEST
Memory Allocation Map for TEST
Source Listing for Resident Library LIB.MAC
Task Builder Map for LIB.TSK
Source Listing for MAIN.MAC
Task Builder Map for MAIN.TSK
Allocation of Virtual Address Space for
MAIN.TSK
Typical Mapping for Supervisor-Mode Library

vii

2-2
2-3
2-7
2-9
2-9
2-11
2-12
2-13
2-14
2-15
2-16
3-2
3-2
3-5
3-7
3-9
3-11
3-13
3-14
3-15
3-16
3-17
3-18
3-19
3-21
3-22
3-23
3-24
3-27
3-28
3-29
3-31
3-33

CONTENTS
FIGURES (Cont.)
Page
FIGURE

3-23
3-24
3-25
3-26
3-27
3-28
3-29
3-30
3-31
3-32
3-33
3-34
3-35
3-36
3-37
3-38
3-39
3-40
4-1
4-2
4-3
4-4
4-5
4-6
4-7
4-8
4-9
4-10
4-11
4-12
4-13
4-14
4-15
4-16
4-17
4-18
4-19
4-20
4-21
5-1
5-2
5-3
5-4
6-1
6-2
7-1
7-2

Task Mapping while Running in Supervisor Mode 3-34
3-36
Source Listing for SUPLIB.MAC
Task Builder Map for SUPLIB.TSK
3-39
3-·40
Source Listing for TSUP.MAC
3-43
Task Builder Map for TSUP.TSK
Allocation of Program Sections in a Multiuser
3-44
Task
3-45
Windows for a Multiuser Task
3-46
Source Listing for ROTASK.MAC
3-49
Task Builder Map for ROTASK.TSK
3-51
Source Listing for DYNAMIC.MAC
3-53
Task Builder Map for DYNAMIC.TSK
3-55
VSECT Option Usage
3-60
Source Listing for VSECT.FTN
3-61
Task Builder Map for VSECT.TSK
3-63
Mapping for /PR:4 and /PR:5
3-64
Source Code for PRIVEX
Task Builder Map for PRIVEX
3-68
Allocation of Virtual Address Space for PRIVEX 3-69
4-3
TKl Built as a Single-Segment Task
4-4
TKl Built as a Multisegment Task
4-6
TKl Built with Additional Overlay Defined
TK2 Built as a Single-Segment Task
4-8
4-9
TK2 Built as a Memory-Resident Overlay
Relationship Between Virtual Address Space
4-11
and Physical Memory -- Time 1 and Time 2
Relationship Between Virtual Address Space
4-13
and Physical Memory -- Time 3 and Time 4
4-16
Overlay Tree for TKl
Resolution of Global Symbols in a Multiseg4-18
ment Task
4-20
Resolution of Program Sections for TKl
4-21
Typical Overlay Root Segment Structure
Tree and Virtual Address Space Diagram
4-23
4-29
Overlay Tree for Modified TKl
Virtual Address Space and Physical Memory
for Modified TKl
4-31
Overlay Co-Tree for Modified TKl
4-32
Virtual Address Space and Physical Memory
for TKl as a Co-Tree
4-33
Overlay Tree of Virtual Address Space for
4-36
OVR.TSK
Map File for OVR.TSK
4-37
Allocation of Virtual Address Space for
4-38
OVR.TSK
Map File for RESOVR.TSK
4-40
Allocation of Virtual Address Space for
4-41
RESOVR.TSK
5-2
Details of Segment C of TKl
5-4
Path-Loading Example
5-4
Autoload Vector Format
5-10
Sample Overlaid Cross-Reference Listing
6-11
Cross-Reference Listing for OVR.TSK
Memory Allocation File (Map) Example
6-30
Task Builder Map for LIB.TSK
7-3
7-4
Task Builder Map for MAIN.TSK

viii

CONTENTS
FIGURES (Cont.}
Page
FIGURE

8-1
8-2
8-3
8-4
8-5
A-1
A-2
A-3
A-4
A-5
A-6
A-7
A-8
A-9
A-10
A-11
A-12
A-13
A-14
A-15
A-16
A-17
A-18
A-19
A-20
A-21
A-22
A-23
A-24
A-25
A-26
A-27
A-28
A-29
A-30
A-31
B-1
B-2
B-3
B-4
B-5
B-6
B-7
B-8
B-9
B-10
B-11

Sample Postmortem Dump (Truncated}
Snapshot Dump Control Block Format
Sample Program that Calls for Snapshot Dumps
Sample Snapshot Dump (in Word Octal and
Radix-SO}
Sample Snapshot Dump (in Byte Octal and
ASCII}
General Object Module Format
Global Symbol Directory Record Format
Module Name Entry Format
Control Section Name Entry Format
Internal Symbol Name Entry Format
Transfer Address Entry Format
Global Symbol Name Entry Format
Program Section Name Entry Format
Program Version Identification Entry Format
Mapped Array Declaration Entry Format
Completion Routine Entry Format
End of Global Symbol Directory Record Format
Text Information Record Format
Relocation Directory Record Format
Internal Relocation Entry Format
Global Relocation Entry Format
Internal Displaced Relocation Entry Format
Global Displaced Relocation Entry Format
Global Additive Relocation Entry Format
Global Additive Displaced Relocation Entry
Format
Location Counter Definition Entry Format
Location Counter Modification Entry Format
Program Limits Entry Format
Program Section Relocation Entry Format
Program Section Displaced Relocation Entry
Format
Program Section Additive Relocation Entry
Format
Program Section Additive Displaced Relocation
Entry Format
Complex Relocation Entry Format
Resident Library Relocation Entry Format
Internal Symbol Directory Record Format
End-of-Module Record Format
Task Image on Disk
Label Block 0 -- Task and Resident Library
Data
Label Blocks 1 and 2 -- Table of LUN
Assignments
Label Block 3 -- Segment Load List
Task Header, Fixed Part
Task Header, Variable Part
Vector Extension Area Format
Logical Unit Table Entry
Task-Resident Overlay Data Base
Autoload Vector Entry
Segment Descriptor

8-2
8-6
8-9
8-10
8-11
A-3
A-4
A-4
A-5
A-5
A-6
A-6
A-8
A-10
A-10
A-11
A-11
A-12
A-14
A-15
A-15
A-16
A-16
A-17
A-17
A-18
A-18
A-19
A-19
A-20
A-21
A-21
A-23
A-23
A-24
A-24
B-2
B-5
B-7
B-7
B-9
B-10
B-11
B-12
B-13
B-14
B-14

CONTENTS
FIGURES (Cont.)
Page
FIGURE

B-12
B-13
B-14

Window Descriptor
Region Descriptor
Supervisor-Mode Vector

B-16
B-17
B-17

TABLES
TABLE

2-1
2-2
2-3
2-4
6-1
6-2
6-3
A-1
A-2
A-3
B-1
B-2
D-1
D-2
D-3
D-4

Program Section Attributes
Program Sections for Modules INl, IN2,
and IN3
Individual Program Section Allocations
Resolution of Global Symbols for INl, IN2,
and IN3
Task Builder Switches
Input Files for SEL.TSK
Task Builder Options
Symbol Declaration Flag Byte -- Bit
Assignments
Program Section Name Flag Byte -- Bit
Assignments
Relocation Directory Command Byte -- Bit
Assignments
Task and Resident Library Data
Resident Library/Common Name Block Data
Task File Switch Defaults
Map File Switch Defaults
Symbol Table File Switch Defaults
Input File Switch Defaults

2-4
2-6
2-6
2-7
6-2
6-39
6-46
A-7

A-8
A-13
B-3
B-6
D-9
D-10
D-10
D-11

PREFACE
MANUAL OBJECTIVES
This manual describes the
RSX-llM/M-PLUS Task Builder.

concepts

and

capabilities

the

Working examples are used throughout this manual to introduce and
describe features of the Task Builder.
Because RSX-llM systems
support a large number of programming languages, it is not practical
to illustrate the Task Builder features in all of the languages
supported. In~tead, most of the examples in the main text of this
manual are written in MACR0-11.

INTENDED AUDIENCE
Before reading this manual, you should be familiar
with
the
fundamental
concepts
of
your
operating
system
(RSX-llM or
RSX--llM-PLUS) and with the operating procedures described in the
RSX-llM/M-PLUS MCR Operations Manual.
In addition, you should be
familiar with the programming concepts described in the RSX-llM/M-PLUS
Guide to Program Development.

STRUCTURE OF THIS DOCUMENT
This manual has eight chapters.
follows:

Their

contents

are

summarized

•

Chapter l describes the Task Builder command
you use to interact with the Task Builder.

•

Chapter 2 describes the basic Task
Builder
functions,
including the Task Builder's allocation of virtual address
space, the resolution of global symbols, and privileged tasks.

•

Chapter 3 describes some typical Task Builder
features
including tasks that access shared regions and device commons,
multiuser tasks, tasks that create dynamic regions, virtual
program sections and privileged tasks.

•

Chapter 4 describes the Task Builder's overlay capability
the language you must use to define an overlay structure.

and

•

Chapter 5 describes the two methods available to you
overlay segments.

load

•

Chapter 6 lists the Task Builder switches and options in two
sections.
Both
switches
and
options
are listed in
alphabetical order in their respective sections, and are
printed on colored stock to help you find them quickly.

sequences

that

•

Chapter 7 describes the considarations for building a task on
one system to run on a system with a different hardware
configuration.

•

Chapter 8
Snapshot.

describes

two

memory

dumps -- Postmortem

This manual also contains
summarized as follows:

six

appendixes.

Their

contents

and
are

•

Appendix A contains a detailed description of the Task Builder
input data structures.

•

Appendix B contains a detailed description of the
file structure.

•

Appendix C contains a list of the symbols and program
names reserved for Task Builder use.

section

•

Appendix D contains
performance.

Task

Builder

•

Appendix E describes the fast Task Builder.

•

Appendix F contains the Task Builder error messages.
are also printed on colored stock for quick reference.

These

information

improving

task

image

A Task Builder glossary follows the appendixes.

ASSOCIATED DOCUMENTS
Other manuals closely allied with this document are described in the
documentation directory for your operating system. This directory
defines the intended audi~nce of each manual in the documentation set
and provides a brief synopsis of each manual's contents.

CONVENTLONS USED IN THIS DOCUMENT
In this manual, horizontal ellipses ( ••• ) indicate that additional,
optional arguments in a statement format have been omitted. For
example:
input-spec, •••
This means that one or more input-spec items, separated by commas, can
be specified.
Vertical ellipses means that additional lines of code or lines in a
Task Builder map file are not pertinent to an example, have been
omitted. For example:
TKB>input-line

This means that one or more of
omitted.

the

xii

indicated

TKB

items

have

been

Finally, in the examples of Task Builder command sequences,
portion of the command sequence that you type is printed in red.
Task Builder's responses and prompts are printed in black.

xiii

the
The

SUMMARY OF TECHNICAL CHANGES

This manual documents RSX-llM-PLUS Task Builder enhancements.
The
following RSX-llM-PLUS features have been added to the Task Builder.
multiuser
share the

The MU switch has been added to provide for the building of
tasks.
Multiuser tasks allow more than one user to
read-only portions of a single task.
The following options have also been added:
•

ROPAR (read-only partition) specifies the partition in
the read-only portion of a multiuser task is to reside.

which

•

GBLXCL (global exclusion) specifies the symbols that are to be
excluded from the symbol definition file of a
resident
supervisor-mode library.

•

RESSUP (user-owned resident supervisor-mode library) specifies
that the
task expects to access a resident supervisor-mode
library.

(system-owned
resident
supervisor-mode
library)
• SUPLIB
specifies that the task expects to access a system-owned
resident supervisor-mode library.
•

CMPRT (completion routine) identifies the
in a supervisor-mode library.

These new features are described in Chapter
examples that illustrate them.

completion
Chapter

routine
contains

While you can specify these features
in the Task Builder command
sequence on both RSX-llM V3.2 and RSX-llM-PLUS systems, the resulting
tasks can be installed and run only on RSX-llM-PLUS systems.

CHAPTER 1
INTRODUCTION AND COMMAND SPECIFICATIONS

The basic steps in the development of a program are as follows:
1.

You write one or more routines in an RSX-llM/M-PLUS supported
source language and enter each routine as an ASCII text file,
through an editor.

You submit each text file
to the appropriate language
translator (an assembler or compiler), which converts it to a
relocatable object module.

You specify the object modules as input to the Task Builder,
which combines the object modules into a single task image
output file.

You install and run the task.

If you find errors in the task when you run it, you make corrections
to the text file, using the editor, and then repeat steps 2 through 4.
The Task Builder's main function
is to convert relocatable object
modules (.OBJ files) into a single task image (.TSK file) that you can
install and run on a RSX-llM or RSX-llM~PLUS system. The task is the
fundamental executable unit in both systems.
If your program consists of a single object module,
the use of the
Task Builder is appropriately simple.
You specify as input only the
name of the file containing the object module produced from the
translation of the program, and specify as output the task image file.
Typically, however, programs consist of more than a single object
module.
In this case,
you name each of the object module files as
input. The Task Builder links the object modules, resolves references
between them, resolves references to the system library, and produces
a single task image ready to b~ irstalled and executed.
The Task Builder makes a set of assumptions (defaults) about the task
image based on typical usage and storage requirements.
You can
override these assumptions by including switches and options
in the
task-building terminal sequence. Thus, you can build a task that is
tailored to its own input/output and storage requirements.
The Task Builder also produces
{upon request)
a memory allocation
(map)
file
that contains information describing the allocation of
address space, the modules that make up the task image, and the value
of all global symbols.
In addition, you can request that a list of
global symbols, accompanied by the name of each referencing module, be
appended to the file (global cross reference).

1-1

INTRODUCTION AND COMMAND SPECIFICATIONS
The following example shows a simple sequence for building a task:
>MAC
>TKB
>INS
>RUN

PROG=PROG
PROG=PROG
PROG
PROG

The first command (MAC) causes the MACR0-11 assembler to translate the
source code of the file FROG.MAC into a relocatable object module in
the file FROG.OBJ. The second command (TKB) causes the Task Builder
to process the file FROG.OBJ to produce the task image file PROG.TSK.
The third command (INS) causes the INSTALL processor to add the task
to
the Executive's directory of executable tasks
(System Task
Directory). The fourth command (RUN) causes the task to execute.
The example just given includes the command
>TKB PROG=PROG
This command illustrates the simplest use of the Task Builder.
It
gives the name of a single file as output and the name of a single
file as input.
This chapter describes basic Task Builder command forms and sequences.

1.1

TASK COMMAND LINE

The task command line contains the output file specifications,
followed by the input file specification&;
they are separated by an
equal sign (=). You can specify up to three output files and any
number of input files.
You must give the output files in a specific order:
the first
file
you name is the image (.TSK) file, the second is the memory allocation
(.MAP) file, and the third is the symbol definition (.STB) file.
The
map file lists information about the size and location of components
within the task. The symbol definition file contains the global
symbol definitions in the task and their virtual or relocatable
addresses in a format suitable for reprocessing by the Task Builder.
You specify this file when you are building a resident library or
common.
(Resident libraries and commons are described in Chapter 3.)
The Task Builder combines the input files to create a single task
image that can be installed and executed.
The task command line has the form:
task-image-file,map-file,symbol-definition-file=input-file, •••
You can omit any output file by replacing the file specification with
the delimiting comma that would normally follow it. The following
commands illustrate the ways the Task Builder interprets the output
file names.
Command

Output Files

>TKB IMGl,IMGl,IMGl=INl

The task image file is IMGl.TSK,
the memory
allocation
(map)
file
is IMGl.MAP, and the
symbol definition file is IMGl.STB.

>TKB IMGl=INl

The task image file is IMGl.TSK.

>TKB ,IMGl=INl

The map file is IMGl.MAP.

1-2

INTRODUCTION AND COMMAND SPECIFICATIONS
Command
>TK B

I ,

I MG .l =IN 1

Output Files
The symbol definition file is IMGl.STB.

>TKB IMGl I I IMGl=INl

The task image file
is IMGl.TSK
symbol definition file is IMGl.STB.

>TKB =INl

This is
files.

1.2

diagnostic

run

with

and
no

the

output

MULTIPLE LINE INPUT

Although you can specify a maximum of three output files,
you can
spec:ify any number of input files.
When you specify several input
files, a more flexible format is sometimes necessary
one that
cons:ists of several lines. This multiline format is also necessary
when you want to include options in your command sequence (see Section
1. 3) ·•
If you type TKB, the Monitor Console Routine (MCR) activates the Task
Builder.
The Task Builder then prompts for input until it receives a
line consisting only of the terminating slash characters
(//)
For
example:
>TKB
TKB>IMGl,IMGl=INl
TKB> IN2, IN3
TKB>//
This sequence produces the same result as the single line command:
>TKB IMGl,IMGl=INl,IN2,IN3
Both command sequences produce the task image file IMGl.TSK and the
map file IMGl.MAP from the input files INl.OBJ, IN2.0BJ, and IN3.0BJ.
You must specify the output file specifications and the equal sign (=)
on the first command line.
You can begin or continue input file
specifications on subsequent lines.
When you type the terminating slash characters (//),the Task Builder
stops accepting input, builds the task, and returns control to MCR.

1.3

OPTIONS

You use options to specify the characteristics of the task you are
building.
To include options in a task, you must use the multiline
format.
If you type a single slash
(/)
following the input file
specification,
the Task Builder requests option information by
displaying ENTER OPTIONS:
and prompting for input.
For example:
>TKB
TKB>IMGl,IMGl=INl
TKB> IN2, IN3
TKB>/
ENTER OPTIONS:
TKB>PRI=lOO
TKB>COMMON=JRNAL:RO
TKB>//

1-3

INTRODUCTION AND COMMAND SPECIFICATIONS
In this sequence there are two options:
PRI=lOO and COMMON=JRNAL:RO.
The two slashes end option input, initiate the task-build, and return
control to MCR upon completion.
NOTE
When you are building an overlaid task,
there are exceptions to the use of the
single slash (/).
Overlaid tasks are
described in Chapter 4.
The RSX-llM/M-PLUS Task Builder provides numerous options.
These are
described
in Chapter 6. The general form of an option is a keyword
followed by an equal sign (=) and an argument list. The ar~uments
in
the list are separated from one another by colons (:).
In the example
above, the first option consists of the keyword PRI and a single
argument indicating that the task is to be assigned the priority 100.
The second option consists of the keyword COMMON and an argument list,
JRNAL:RO,
indicating that the task accesses a resident common region
named JRNAL and that the access is read-only.
You can specify more
than one option on a line,
by using an exclamation point (1) to
separate the options.
For example:
TKB>PRI=lOO!COMMON=JRNAL:RO
This command is equivalent to the two lines:
TKB>PRI=lOO
TKB>COMMON=JRNAL:RO
Some options accept more than one set of argument lists.
comma (,) to separate the argument lists.
For example:

You

use

TKB>COMMON=JRNAL:RO,RFIL:RW
In this command, the first argument list indicates that the task has
requested read-only access to the resident common JRNAL. The second
argument list indicates that the task has requested read/write access
to the resident common RFIL.
The following three sequences are equivalent:
TKB>COMMON=JRNAL:RO,RFIL:RW
TKB>COMMON=JRNAL:RO!COMMON=RFIL:RW
TKB>COMMON=JRNAL:RO
TKB>COMMON=RFIL:RW

1.4

MULTIPLE TASK SPECIFICATIONS

If you intend to build more than one task,
you can use the single
slash
(/)
following option input. This directs the Task Builder to
stop accepting input, build the task, and request information for
the
next task-build.

1-4

INTRODUCTION AND COMMAND SPECIFICATIONS
For example:
>TKB
TKB> IMGl=INl
TKB> IN2, IN3

TKB>I
ENTER OPTIONS:
TKB>PRI=lOO
TKB>COMMON=JRNAL:RO

TKB>I
TKB>IMG2=SUB1

TKB>ll
The Task Builder accepts the output and input file specifications and
the option input;
it then stops accepting input upon encountering the
single slash
(I) during option input.
The Task Builder builds
IMGl.TSK and then returns to accept more input for building IMG2.TSK.

1.5

INDIRECT COMMAND FILES

You can enter commands to the Task Builder directly from the keyboard,
or
indirectly through the indirect command file facility.
To use the
indirect command file facility, you prepare a file that contains ·the
Task Builder commands you want to be executed.
Later, after you
invoke the Task Builder, you type an at sign (@) followed by the name
of the indirect command file.
For example, suppose you create a file called AFIL.CMD containing
following:

the

I MG 1 , I MG 1 = IN 1
IN2,IN3

PRI=lOO
COMMON=JRNAL:RO

II
Later, you can type:
>TKB
TKB>@AFIL
TKB>
or simply
>TKB @AFIL
When the Task Builder encounters the at sign
(@),
it directs
its
search for commands to the file named AFIL.CMD.
The example above is
equivalent to the keyboard sequence:
>TKB
TKB>IMGl,IMGl=INl
TKB> IN2, IN3

TKB>I
ENTER OPTIONS:
TKB>PRI=lOO
TKB>COMMON=JRNAL:RO

TKB>ll
When the Task Builder encounters two terminating slash characters (II)
in the
indirect command file,
it terminates indirect command file
processing, builds the task, and exits to MCR.

1-5

INTRODUCTION AND COMMAND SPECIFICATIONS
When the Task Builder encounters a single slash (I)
in an indirect
command file and the slash is the last character in the file, the Task
Builder directs its search for commands to the terminal. For example,
suppose the file AFIL.CMD in the last example is changed to read:
IMGl,IMGl=INl
IN2,IN3

Later, you can type:
>TKB
TKB>@AFIL
In this case, the Task Builder goes to the terminal and prompts:
ENTER OPTIONS:
TKB>
From this point, you input options to the Task Builder directly from
the keyboard.
If you then conclude option input from the keyboard
with double slashes (II), the Task
Builder
suspends
command
processing, as described above, and exits to MCR following the
task-build. If you conclude option input with a single slash Cl), the
Task Builder prompts for new command input following the task-build of
IMGl.TSK, as follows:
TKB>
Using the single slash Cl) following option input in indirect command
files is a convenient way to return control to your terminal between
successive task-builds. For example, suppose you create two indirect
command files. The first, AFIL.CMD, contains~
IMGl,IMGl=INl
IN2,IN3
I
PRI=lOO
COMMON=JRNAL
I
The second, AFILl.CMD, contains:
IMG2,IMG2=IN4
IN5,IN6
I
PRI=lOO

Then, the terminal sequence to build these two tasks is:
>TKB
TKB>@AFIL
TKB>@AFILl

NOTE
For interaction with a Task Builder
indirect
command
file as described
above, you must use the multiline format
when you specify the indirect command
file.

1-6

INTRODUCTION AND COMMAND SPECIFICATIONS
The Task Builder permits two levels of indirection in file references.
That is,
the indirect command file referenced in a terminal sequence
can contain a
reference to another
indirect command file.
For
example,
if the file BFIL.CMD contains all the standard options that
are used by a particular group of users at an installation,
you can
modify AFIL to include an indirect command file reference to BFIL.CMD
as a separate line in the option sequence.
The contents of AFIL.CMD would then be:
I MG 1 , I MG 1=IN1
IN2,IN3

PRI=lOO
COMMON=JRNAL:RO
@BFIL

II
To build these files, you type:
>TKB
TKB> @AFIL
Suppose the contents of BFIL.CMD are:
STACK=lOO
UNITS=5!ASG=DT1:5
The terminal equivalent of building these files is:
>TKB
TKB>IMGl ,IMGl=INl
TKB> IN2, IN3
TKB>I
ENTER OPTIONS:
TKB>PRI=lOO
TKB>COMMON=JRNAL:RO
TKB>STACK=lOO
TKB>UNITS=S!ASG=DTl:S

TKB>ll
The indirect command file reference must appear on a separate line.
For example,
if you modify AFIL.CMD by adding the @BFIL reference on
the same line as the COMMON=JRNAL:RO option,
the substitution would
not take place and the Task Builder would report an error.

1.6

COMMENTS IN LINES

You can include comments at any point in the command sequence,
except
in lines that contain file specifications.
You begin a comment with a
semicolon (;) and terminate it with a carriage return.
All text
between these delimiters is a comment.
For example, in the indirect command file,
AFIL.CMD, described
in
Section 1.5, you can add comments to provide more information about
the purpose and the status of the task.

1-7

INTRODUCTION AND COMMAND SPECIFICATIONS

TASK 33A
DATA FROM GROUP E-46 WEEKLY
;

IMGl ,IMGl=
; PROCESSING ROUTINES
INl
; STATISTICAL TABLES
IN2
;

; ADDITIONAL CONTROLS
IN3

PRI=lOO
;

COMMON=JRNAL:RO ; RATE TABLES
; TASK STILL IN DEVELOPMENT
;

1.7

FILE SPECIFICATIONS

The Task Builder adheres to the standard RSX-llMIM-PLUS conventions
for
file specifications.
For any file, you can specify the device,
the User File Directory (UFO), the file name, the file type, the file
version number, and any number of switches.
The file specification has the form:
device: [group,member]filename.type;versionlswllsw2 ••• lswn
When you specify files by name only the Task Builder applies
default switch settings for device, group, member, type, version.
example:

the
For

>TKB
TKB>IMGl,IMGl=INl
TK B>IN 2 , I N3

TKB>ll
If the current User Identification Code (UIC) of the terminal that the
Task Builder is running on is
[200,200],
the task
image file
specification of the example is assumed to be:
SY0:[200,200]IMG1.TSK;l
That is, the Task Builder creates the task image file on the system
device
(SYO:) under UFO [200,200]. The default type for a task image
file is .TSK and if the name IMGl.TSK is new, the version number is 1.
The default settings for all the task image switches also apply.
Switch defaults are described in detail in Chapter 6.

1-8

INTRODUCTION AND COMMAND SPECIFICATIONS
For 1example:
>TKB
TKB>[20,23]IMGl/CP/DA,IMGl/CR=INl
TK B>IN 2 ; 3 , IN 3
TKB>//
This sequence of commands instructs the Task Builder to create a
task
imag·e file
IMGl.TSK;l and a memory allocation (map) file MPl.MAP;l
(actually, it produces IMGl.TSK and IMGl.MAP with versions one higher
than the current versions) under UFD [20,23] on the device SY:. The
task image is checkpointable and contains the standard debugging aid
(ODT).
The Task· Builder outputs the map to the line printer with a
global cross-reference listing appended to
it.
The Task Builder
builds the task from the latest versions of INl.OBJ, IN3.0BJ, and the
specific version of IN2.0BJ. The input files are all found on the
system device.
For some files, a device specification is sufficient.
In the example
above,
the map file
is fully specified by the device LP:. The map
listing is produced on the line printer, but is not retained as a
file.
This example also used switches /CP, /CR, and /DA. The code,
and meaning for each switch are given in Chapter 6.

1.8

syntax,

SUMMARY OF SY~TAX RULES

The syntax rules for issuing commands
follows:

the

A task-build command can take any one
first form is a single line:

Task
of

Builder
four

are

forms.

>TKB task-command-line
The second form has additional lines for input file names:
>TKB
TKB>task-command-line
TKB>input-line

TKB>terminating-symbol
The third form allows you to specify options:
>TKB
TKB>task-command-line
TKB>/
ENTER OPTIONS:
TKB>option-line

TKB>terminating-symbol

1-9

as
The

INTRODUCTION AND COMMAND SPECIFICATIONS
The fourth form has both input lines and option lines:
>TKB
TKB>task-command-line
TKB>input-line

TKB>I
ENTER OPTIONS:
TKB>option-line

TKB>terminating-symbol
The terminating symbol can be:

if you intend to build more than one task
if you want the Task Builder to

return

control

specification

MCR

A task command line has one of the three forms:
output-file-list=input-file, •••
=input-file, •••
@indirect-command-file
The third form is an indirect command file
described in Section 1.5.

An ouput file list has one of the three forms:
task-image-file,map-file,symbol-definition-file
task-image-file,map-file
task-image-file
The task-image-file is the file specification for
the task
image file;
map-file is the file specification for the
memory allocation (map) file;
and symbol-definition-file is
the file specification for the symbol definition file.
Any
of the specfications can be omitted, so that,
for
example,
the following form is permitted:
task-image-file,,symbol~definition-file

An input line has one of two forms:
input-file, •••
@indirect-command-file
Both
input-file
specifications.

and

indirect-command-file

1-10

.are

file

INTRODUCTION AND COMMAND SPECIFICATIONS
5.

An option line has one of two forms:
option! •••
@indirect-command-file
The indirect-command-file is a file specification.

An option has the form:
keyword=argument-list,o••
The argument-list is:
arg: •••
The syntax for each option is given in Chapter 6.

file
specification conforms
comventions.
It has the form:

standard

RSX-lM/M-PLUS

devi~e: [group,member]filename.type;version/swl/sw2 ••• /swn

device:

The name of the physical device on which the volume
containing the desired file is mounted.
The name
consists of two ASCII characters followed
by an
optional 1- or
2-digit octal unit number and a
colon;
for example, LP:
or DTl:.

group

The group number, in the range of 1 through 377(8).

member

The member number, in the range 1 through 377(8).

filename The name of the desired file.
The file
contain up to 9 alphanumeric characters.

name

can

type

The 3-character file
type
idectification.
Files
having the same name but a different function are
distinguished from one another by the file
type;
for example, CALC.TSK and CALC.OBJ.

version

The version number, in octal, of the file.
Various
versions of the same file are distinguished from one
another by this number;
for example, CALC.OBJ;l and
CALC.OBJ;2.

All components of a file specification are optional.
The
combination of the group number and the member number is the
User File Directory (UFD) that contains the file name.

1-11

CHAPTER 2
TASK BUILDER FUNCTIONS

The process of building a task involves three distinct Task Builder
functions.
First,
the Task Builder is a linker.
It collects and
links the relocatable object modules that you specify to
it
into a
single task image and resolves references to global symbols across the
module boundaries.
Second, the Task Builder assigns addresses to the task
image.
On
mapped systems,
the Task Builder assigns addresses for
a
task
beginning at zero.
The Executive then relocates the addresses at
runtime.
On unmapped systems, the Task Builder assigns addresses for
a task beginning at the base address of the partition in which the
task
is to run.
The addresses of tasks that run on unmapped systems
are not relocated at runtime.
NOTE
Unless otherwise indicated,
references
to tasks that run on mapped systems
assume that the tasks are nonprivileged
and
residing within system-controlled
partitions.
Third, the Task Builder builds data structures into the task
image
that are required by the INSTALL processor to install the task and by
the Executive to run it.
This chapter describes the three Task Builder functions in detail.

2.1

LINKING OBJECT MODULES

When the language translators convert symbolic source code within a
module to object code, they assign provisional 16-bit addresses to the
code~
A single assembly or compilation produces a single object
module.
In their simplest form, each module begins at 0 and extends
upward to the highest address in the module.
Three object modules
produced at separate times might have the address limits shown in
Figure 2-1.

2-1

TASK BUILDER FUNCTIONS

1000-r-ir-~~~--

750

500

MODULE #1

MODULE #3
MODULE #2

RELOCATABLEO-----~~~--

RELOCATABLEO

Figure 2-1

---~~~--RELOCATABLEO

Relocatable Object Modules

If these modules represent the separate modules of a single program,
the Task Builder links them together and modifies the provisional
addresses to one of the following:
•

A single sequence of addresses beginning at 0 and extending
upward to the sum of all of the addresses of each module
(mapped system)

•

A single sequence of addresses beginning at a base address
assigned at task build time and extending upward to the sum of
all the addresses of each module (unmapped system)

For example, Figure 2-2A shows the three modules linked for a mapped
system, and Figure 2-2B shows the modules linked for an unmapped
system.

2.1.1

Allocating Program Sections

The language translators process source code and the Task Builder
links object modules within the context of program sections. A
program section is a block of code or data that consists of three
elements:
•

a name

•

a set of attributes

•

a length

2-2

TASK BUILDER FUNCTIONS

2250------

3250

MODULE #3

MODULE #2

MODULE #1

BASE 1000
MAPPED
SYSTEM

UNMAPPED
SYSTEM
2-28

2-2A

Figure 2-2

Modules Linked for Mapped and Unmapped Systems

Program sections are important because they are the basic unit used by
the ~rask Builder to determine the placement of code and data in a task
imagi~.
The language translators maintain a separate location counter
for
each program section in a
program.
The name of each program
section, its attributes, and its length are conveyed to the Task
Builder through the object module.
You can create as many program sections within a module as you wish by
explicitly declaring them (with the COMMON statement in FORTRAN or the
.PSECT directive in MACR0-11,
for
example)
or you can leave the
creation of program sections to the language translator.
If you do
not explicitly create a program section in your source code,
the
language translator you are working with will create a "blank" program
section within each module translated.
This program section will
appear on your listings and maps as • BLK ••
For more information on
explicitly declared program sections,
see your language
reference
manual.

2-3

TASK BUILDER FUNCTIONS
A program section's name is the name by which the language translator
and Task Builder
reference
it.
When processing files, both the
language translator and the Task Builder create internal tables that
contain program section names, attributes and lengths.
Program section attributes define a program section's contents,
its
placement in a
task
image, and, in some cases, the allowed mode of
access (read/write or read-only).

A program section's length determines how much address space the

Task

Builder must reserve for it.
When a program consists of more than one module, it is not unusual for
program sections of the same name to exist in more than one of the
modules.
Therefore, as the Task Builder scans the object modules,
it
collects scattered occurrences of program sections of the same name
and combines them into a single area of your
task
image file.
The
attributes listed in Table 2-1 control the way the Task Builder
collects and places each program section in the task image.
Table 2-1
Program Section Attributes
Attribute

Value

access-code

Read/write:
data can be read from,
written into, the program section

Read-only:
data can be read from,
but
cannot
be written into,
the program
section

Data:

Instruction:
the
program
section
contains either instructions, or data and
instructions

GBL

Global:
the program section name
is
recognized
across
overlay
segment
boundaries, the Task Builder allocates
storage for
the program section from
references outside the defining overlay
segment.

LCL

Local:
the program section name
is
recognized
only
within the defining
overlay segment;
the
Task
Builder
allocates storage for the program section
from references within
the
defining
overlay segment only

type-code 1

scope-code

Meaning
and

the program section contains data

1 Do not confuse these codes with the I and D
PDP-11 systemr.

space

hardware

(continued on next page)

2-4

TASK BUILDER FUNCTIONS
Table 2-1 (Cont.)
Program Section Attributes
Attribute

Value

Meaning

allocation-code

CON

Concatenate:
all references to a given
program section name are concatenated;
the total allocation is the sum of the
individual allocations

OVR

Overlay:
all
references to a
given
program section name overlay each other;
the total allocation is the length of the
longes~ individual allocation

REL

Relocatable:
the base address of the
program section is relocated relative to
the base address of the task

ABS

Absolute:
the base address
of
the
program section is not relocated;
it is
always 0

HIGH

High:
the program section
loaded into high-speed memory

LOW

Low:
the program section is to be loaded
into low-speed memory

relocation-code

memory-code 2

2 Not used by the Task Builder.
The type-code and scope-code are meaningful only when you define an
overlay structure for a
task.
These codes are described in later
chapters within the context of the descriptions of overlays. The Task
Builder does not use the memory-code.
The Task Builder uses
a
program
section's
access-code
and
allocation-code to determine its placement and size in a task image.
It divides address space into read/write and
read-only areas,
and
places the program sections in the appropriate area according to
access-code.
The Task Builder uses a program section's allocation-code to determine
its
starting
address
and
length.
If
a program section's
allocation-code indicates that th~ Task Builder is to overlay it,
the
Task Builder places each allocation to the program section from each
module at the same address within the task image.
The Task Builder
determines the total size of the program section from the length of
the longest allocation to it.
If a program section's allocation-code indicates that the Task Builder
is to concatenate it, the Task Builder places the allocation from the
modules one after the other in the task image,
and determines the
total allocation from the sum of the lengths of each allocation.
The Task Builder always allocates address space for a program section
beginning on a word boundary.
If the program section has the D (data)
and CON (concatenate) attributes, the Task Builder appends to the last
byte of the previous allocation all storage contributed by subsequent
modules.
It does this regardless of whether that byte is on a word or

2-5

TASK BUILDER FUNCTIONS
nonword boundary. For a program section with the I (instruction) and
CON attributes, however, the Task Builder allocates address space
contributed by subsequent modules beginning with the nearest following
word boundary.
For example, suppose three modules, INl, IN2, and IN3, are to be
task-built.
Table 2-2 lists these modules with the program sections
each contains and their access codes and allocation codes.
Table 2-2
Program Sections for Modules INl, IN2, and IN3
Program
Section
Name

Access
Code

Allocation
Code

Size
(octal)

RW
RW
RO

CON
OVR
CON

100
300
150

IN2

A
B

RW
RW

OVR
CON

250
120

IN3

CON

File Name
INl

B
A

In this example, the program section named B, with the attribute CON
(concatenate), occurs twice. Thus, the total allocation for B is the
sum of the lengths of each occurence;
that is, 100 + 120 = 220.
The
program section named A also occurs twice. However, it has the OVR
(overlay) attribute so its total allocation is the largest of the two
sizes, or 300.
Table 2-3 lists the individual program section
allocations.
Table 2-3
Individual Program Section Allocations

Program Section
Name

Total
Allocation

B
A

220
300
220

-...J

The Task Builder then groups the program sections according to their
access codes, and alphabetizes each group as shown in Figure 2-3.
NOTE
The example
shown
in
Figure
2-3
represents the Task Builder's default
allocation of program sections.
For
information on altering this default,
see the description of the SQ switch in
Chapter 6.

2-6

TASK BUILDER FUNCTIONS

c (220)

B (220)

A (300)
STACK

READ-ONLY
ACCESS
READ/WRITE
ACCESS

TASK MEMORY

HEADER

Figure 2-3

2.1.2

Allocation of Task Memory

Resolving Global Symbols

The Task Builder resolves references to global symbols across module
boundaries and any references
(explicit or implicit) to the system
library. When the language translators process a text file,
they
assume that references to global symbols within the file are defined
in other, separately assembled or compiled modules.
As the Task
Builder links the relocatable object modules, it creates an internal
table of the global symbols it encounters within each module.
If,
after the Task Builder examines and links all the object modules,
references remain to symbols that have not been defined,
the Task
Builder assumes that it will find the definition for the symbols
within the default system object module library
(LB: [l,l]SYSLIB.OLB).
If undefined symbols still remain after SYSLIB is examined, the Task
Builder flags the symbols as undefined.
If you have not specified an
output map in your Task Builder command sequen·ce, the Task Builder
reports the names of the undefined symbols to you on your terminal.
If you have specified an output map, the Task Builder outputs to your
terminal only the fact that the task contains undefined symbols.
The
names of the symbols appear on your map listing.
When creating the task image file, the Task Builder resolves global
references as shown in the following example. Table 2-4 lists the
three files INl, IN2, and IN3, showing the program sections within
each file, the global symbol definitions within each program section,
and the references to global symbols in each program section.
Table 2-4
Resolution of Global Symbols for INl, IN2, and IN3
File
Name

Program Section
Name

Global
Definition

Global
Reference

INl

Bl
B2

xxx

c
IN2
IN3

B2
Bl

2-7

TASK BUILDER FUNCTIONS
In processing the first file, INl, the Task Builder finds definitions
for Bl and B2 and references to A, Ll, Cl, and XXX.
Because no
definition exists for these references, the Task Builder defers the
resolution of these global symbols.
In processing the next file, IN2,
the Task Builder finds a definition for A, which resolves the previous
reference, and a reference to B2, which can be immediately resolved.
When all the object files have been processed, the Task Builder has
three unresolved global references -- Cl, Ll, and XXX. Assume that a
search of the system library LB: [l,l]SYSLIB.OLB resolves Ll. and XXX
and the Task Builder includes the defining modules in the task's
image.
Assume also that the Task Builder cannot resolve the global
symbol Cl. The Task Builder lists it as an undefined global symbol.
The relocatable global symbol Bl is defined twice.
The Task Builder
lists it as a multiply-defined global symbol. The Task Builder uses
the first definition of a multiply-defined symbol.
Finally, an absolute global symbol (for example,
symbol=lOO)
can be
defined more than once without being listed as multiply defined as
long as each occurrence of the symbol has the same value.

2.2

ASSIGNING ADDRESSES

The primary addressing mechanism of the PDP-11 is the 16-bit computer
word.
The maximum physical address space that the PDP-11 can
reference at any one time is a function of the length of this word.
The highest number that can be represented in 16 bits is 177777(8) or
65,535(10).
Because the PDP-11 is a byte-addressable machine,
the
16-bit word length allows it to address up to 65,535 bytes (32K words)
of physical address space at any one time.
The amount of address
space that a machine can reference at any one time is called virtual
address space.

2.2.1

Unmapped Systems

In an unmapped system, the machine's virtual address space and
physical address space coincide exactly, as shown in Figure 2-4.

its

In an unmapped system, the machine's address space is limited to 32K
words.
All of the machine's physical memory and all of its device
registers are accessible to all tasks running on the system. The top
4K words of address space are reserved for the UNIBUS addresses that
correspond to the peripheral device registers (the I/O page),
and a
segment of low memory is occupied by the Executive. Therefore, in an
unmapped system, the largest task size is 32K words minus the I/O page
and the size of the Executive.
Figure 2-5 shows the memory layout for
an unmapped system.
Unmapped systems contain only user--controlled partitions.
When the
Task Builder links the relocatable object modules of a task that is to
run on an unmapped system, it requires that you specify the partition
in which the task is to run, the partitions base address and length.
The Task Builder will set the base address of the task to the base
address of the partition.
This means that the task's location in
physical memory is bound to the partition and does not change.
Because all of physical memory in an unmapped system is directly
addressable, and the task's location within memory does not change,
the addresses that the Task Builder assigns coincide exactly with the
physical addresses of the machine and, therefore, do not need to be
relocated at runtime.
2-8

TASK BUILDER FUNCTIONS
VIRTUAL
32 K WORDS

PHYSICAL
32 K WORDS

VIRTUAL 0

PHYSICAL 0 ..___ _ __
VIRTUAL
ADDRESS SPACE

Figure 2-4

PHYSICAL
MEMORY

Unmapped Memory

32 K WORDS

1/0 PAGE

• EXECUTIVE•

Figure 2-5

Layout for Unmapped System

2-9

TASK BUILDER FUNCTIONS
2.2.2

Mapped Systems

In a mapped system, the relationship between virtual address space and
physical address space is different from that of an unmapped system.
The primary addressing mechanism for a mapped system is still the
16-bit word, and virtual address space is still 32K words. However, a
mapped system has a much greater physical memory capacity and,
therefore, physical memory and virtual address space do not coincid~.
To address all of physical memory in a mapped system, a machine must
have an effective word length of 18 or 22 bits, depending on the model
of the machine. When the Task Builder links the relocatable object
modules of a task that is to run on a mapped system, it assigns 16-bit
address to the task image.
The memory management unit's function
(under control of the Executive)
is to convert the task's 16-bit
addresses to effective 18- or 22-bit physical addresses.
The
mechanical
job of task relocation is performed by the Executive and
the memory management unit at task runtime.
Figure 2-6 illustrates
the relationship between physical memory and virtual address space in
a mapped system.
The memory management unit divides a machine's 32K words of virtual
address space into eight 4K word segments or pages.
Each page has two
registers associated with it:
•

A 16-bit Page Description Register
(PDR)
which contains
control and access information about the page with which it is
associated

•

A 16-bit Page Address
relocation register

(PAR)

which

address

The PDRs and PARs are always used as a pair. Each pair is called an
Active
Page Register
(APR).
Figure 2-7 shows how the memory
management unit divides the 32K words of virtual address space.
NOTES
1. A detailed description of the Memory
Management unit is beyond the scope of
this manual.
For a complete description
of
your machine's memory management
unit, refer to the Processor Handbook
for your machine.
2. Mapped machines have up to three
modes of operation: Kernel, Supervisor,
and User (11/34 machines do not have
supervisor mode).
The information in
this chapter is relevant to User mode
only.
The Executive allocates only as many APRs as are necessary to map a
given task into physical memory. Therefore, a 4K word task requires
one APR;
a 6K word task requires two.
Figure 2-8 illustrates this
mapping.

2-10

TASK BUILDER FUNCTIONS

•

•
•
•

•
•

HIGHEST
PHYSICAL
ADDRESS

PARTITION -~-...._-_....,.__..
BOUNDARY

____/

TASK
MEMORY

32K---·---~
MEMORY
MANAGEMENT
UNIT

HEADER

TASK
MEMORY

HEADER

TASK
MEMORY

SYSTEM-CONTROLLED
PARTITION

·O - ...______.....

HEADER

VIRTUAL ADDRESS
SPACE
FOR 32 K WORD
TASK

TASK
MEMORY

HEADER
TASK
MEMORY

PA RT IT I ON ......,.,..__H_E_A_D_E_R
_
BOUNDARY

• EXECUTIVE •
•
ETC.
•

•

Q_I.____I
PHYSICAL
MEMORY

Figore 2-6

Task Relocation in a Mapped System

2-11

TASK BUILDER FUNCTIONS

PAGE 7
VIRTUAL 160000

APR 7 PAGE 6

VIRTUAL 140000

APR6 PAGE 5

VIRTUAL 120000

APR 5 PAGE 4

VIRTUAL 100000

APR4 -

32K WORDS OF
VIRTUAL ADDRESS
SPACE

PAGE 3
VIRTUAL 60000

APR 3 PAGE 2

VIRTUAL 40000

VIRTUAL 20000

VIRTUAL 0

Figure 2-7

APR 2 -

APR 1

PAGE 1

PAGE 0

APR 0

Memory Management Unit's Division of Virtual Address Space

2-12

TASK .BUILDER FUNCTIONS

APR 7 -

160000 APn 7 -

140000 AP H 6 --,...

120000 APR 5 -

APR 5 -

100000 APR 4 -

APR4-

60000 APR 3 -

APR3-

40000 APR 2 -

APR 2 -

20000 APR 1 -

APR 1 -

TASK
MEMORY

VIRTUALO APRO-

HEADER & STACK

4 K WORDS

APRO-

HEADER & STACK

TASK B (6 K WORDS)

TASK A (4 K WORDS)

Figure 2-8

TASK
MEMORY

Mapping for 4K Word and 6K Word Tasks

2-13

TASK BUILDER FUNCTIONS
Finally, the layout of the virtual address space for a task that is to
run in a mapped system is different in most cases from that of a task
that is run in an unmapped system. Unless a task is privileged, the
I/O page and the Executive are not normally part of a task's virtual
address space and, unlike an unmapped system, a task is inhibited by
the system from accessing any portion of physical memory that it does
not specifically own.
Because the I/O page and the Executive are not
part of a task's virtual addres~ space, a task can be a full 32K words
long on a mapped system.

2.3

BUILDING SYSTEM DATA STRUCTURES

It is the Task Builder's responsibility to build the data structures
required by other system programs, and to incorporate them into the
task image. The Executive (which is the system task responsible for
the allocation of system resources) must have access to the data for
all tasks on the system.
It must know, for example, a task's size and
priority, and it must have information about the way each task expects
to use the system.
It is the Task Builder's responsibility to
allocate space in the task image for the data structures required by
the Executive. The Task Builder initializes some of these structures,
while the INSTALL processor initializes others when you install the
task.

The disk image file created by the Task Builder contains the linked
task and all of the information required by the system programs to
install and run it.
In its simplest form,
the disk image file
consists of three physically contiguous parts:
•

The label block group

•

The task header

•

The task memory image

Figure

2-9

illustrates the basic structure of this file.

0
:

MEMORY :

HEADER
LABEL
BLOCK

Figure 2-9 Disk Image

2-14

TASK BUILDER FUNCTIONS.
NOTE
Non-runnable images such as resident
shared regions do not have a header.
Resident shared regions are described in
Chapter 3.
The label block group contains data produced by the Task Builder and
used by the INSTALL processor. It contains information about the task
such as the task's name, the partition in which it runs, its size,
priority, and the logical units assigned to it. When you install the
task, the INSTALL processor uses this information to cre(it.~ a Task
Control Block entry for the task in the System Task Directory (STD
file) and to initialize the task's header information.
The task's header contains information that the Executive uses when it
runs the task. The header also provides a storage area for saving the
task's essential data when the task is checkpointed. The Task Builder
creates and partially initializes the header; the INSTALL processor
initializes the rest of the header.
The task memory contains the linked modules of the program and
therefore the code and data. It also contains the task's stack. The
stack is an area of task memory that a task can use for temporary
storage and subroutine linkage. It can be referenced through general
register 6, the stack pointer (SP). The label block group, the task's
header and the task memory are described in detail in Appendix c.
The task's memory image is the part of your task that the system reads
into physical memory at runtime.
The label block group is not
required in physical memory. Therefore, in its simplest form, the
task's memory image consists of only two parts: the task header and
task memory. Figure 2-10 shows the memory image.

TASK
MEMORY

HEADER

o-------Figure 2-10 Memory Image
2.4

TASK RELOCATION ON MAPPED SYSTEMS

As mentioned earlier, tasks that run on mapped systems must be
relocated at runtime.
When you build a task that is to run on a
mapped system, the Task Builder creates and places in the header of
the task one or more 9-word data structures called window blocks.
When you install a task the INSTALL processor initializes the window
block(s).
Once initialized, a window block describes a range of
continuous virtual addresses called a window.

2-15

TASK BUILDER FUNCTIONS
A window can be as small as 32 words or as large as 32K words. When a
task consists of one continuous range of addresses (a single region
task) only one window block is required to describe the entire task
from the beginning of its header to the highest virtual address in the
task. When a task consists of two or more regions
(such as a
task
that references a shared region as described in Chapter 3), each
region must have at least one window block associated with it that
describes all or a portion of the region.
When the Executive maps a task into physical memory, it extracts the
information it requires to set up the APRs of the memory management
unit from the task's window block.
Regardless of the number of regions associated with a task, the region
that contains the task's header is always described by window O.
Furthermore, this region is referred to as the task region and
is
identified as region O.
Figure 2-11 illustrates window block O.
When you run your task, the Executive determines where in physical
memory the task is to reside.
The Executive then loads the Page
Address Register portion of the APRs with a relocation constant that,
when combined with the addresses of the task, yields the 18- or 22-bit
physical address range of the task.
HIGHEST VIRTUAL
ADDRESS

TASK REGION -

WINDOW BLOCK

TASK
MEMORY

HEADER & STACK
LOWEST VIRTUAL
ADDRESS

Figure 2-11 Window Block 0

2-16

REGION 0

CHAPTER 3
TYPICAL TASK BUILDER FACILITIES

The Task Builder provides you with many facilities for tailoring your
tasks to meet your specific requirements.
This chapter describes some
of these facilities and their applications.
This chapter contains eight working examples.
The discussion of the
examples assume
that you are familiar with the programming concepts
described in the RSX-llM/M-PLUS Guide to Program Development and with
the first two chapters of this manual.

3.1

SHARED REGIONS

A shared region is a block of data or code that resides in memory and
can be used by any number of tasks.
Shared regions are useful because
they make more efficient use of physical memory:
•

By providing a way in which two or more tasks can share
data.
This is called a resident common.

their

providing a way in which a single copy of commonly used
• By
subroutines can be shared by several tasks.
This is called a
resident library.
The term "resident" is used to denote a shared region that is built
and installed
into the system separately from the task that links to
it.
Figure 3-1 shows a
typical
resident common.
Task A stores some
results
in resident common s, and Task B retrieves the data from the
common at a later time.
Figuire 3-2 sho.ws a typical resident library.
In this case,
common
reentrant subroutines are not included in each task image;
instead, a
single copy is shared by all tasks.

3-1

TYPICAL TASK BUILDER FACILITIES

RESIDENT COMMON

PARTITION BOUNDARY _ _.,._.,.,...........,.,..,.,.,..,..,...,..,..,..........,..,..,...,..,.,..,.,..,.,.,..__

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

TASK A

TASK B

i. . . Ii .l. .•.•.•. .

PA RT 1Tl ON BOUNDARY ----11-'-"·····.;..:..•••••......•••......
••••.....i .....
·••••.....•i..... •i .....
·•···......
•••••....

•••i."'"'ti

EXECUTIVE

PHYSICAL MEMORY
TIME 1

PHYSICAL MEMORY
TIME 2

Figure 3-1

Typical Resident Common

RESIDENT LIBRARY
CONTAINING
ROUTINE R

PARTITION BOUNDARY

ROUTINE R
TASK A
ROUTINE R

TASK A

TASK B

PARTITION BOUNDARY --+----------1
EXECUTIVE

EXECUTIVE

NONSHARED
PHYSICAL MEMORY

SHARED
PHYSICAL MEMORY

Figure 3-2

Typical Resident Library

3-2

TYPICAL TASK BUILDER FACILITIES
When you build a shared region, you must specify in the Task Builder
command sequence an output image file name for it.
But, because a
shared region is not an executable unit, it is not a task.
It does
not require a header or a stack area. Therefore, when you build a
sharE~d region, you always attach the negated header switch
(/-HD)
to
the
image file specification. This switch tells the Task Builder to
suppress the header within the image. To suppress the stack area,
in
the Task Builder command sequence during option input, you specify
STACK=O.
(Refer to Chapter 6 for a complete description of the HD
switch and the STACK option.)
In an RSX-llM system, a shared region must reside in its own
partition.
Therefore, when you generate your system,
you must
consider the physical memory requirements of any shared regions that
you expect to reside within your system.
If you do not consider these
requirements at system generation time, later, when you build a shared
region, you will have to go back and create a common partition for the
region.
In an RSX-llM-PLUS system, shared regions do not have to reside within
partitions of their own;
you can install a shared region in any
partition large enough to hold it.
In fact, the partition for which
the shared region was built does not have to exist in the system at
the time the shared region is installed.
If you attempt to install a
shared region in a partition that does not exist,
the INSTALL
processor will install it in partition GEN and print the following
message on your terminal:
INS--PARTITION parname NOT IN SYSTEM DEFAULTING TO GEN
When you build a shared region, you must specify the partition in
which the region is to reside.
You specify the partition name in the
Task Builder command sequence during option input.
(Refer to Chapter
6 for a description of the PAR option.)

3.1.l

The Symbol Definition File

When you build a shared region, you must specify a symbol definition
(.STB)
file in the Task Builder command sequence. This file contains
linkage information about the region.
Later, when you build a task
that links to the region, the Task Builder uses this .STB file to
resolve calls from within the referencing task to locations within the
region.
The contents of an .STB file for a shared region depend on whether the
shared region is position independent or absolute. The effects of
declaring a shared region position independent or absolute and the
resulting contents of the .STB file are described in the following
sections.

3.1.2

Position-Independent Shared Regions

A position-independent shared region can be placed anywhere
in a
referencing task's virtual address space when the system on which the
task runs has memory management hardware.
For example, in Figure 3-3, two tasks refer to the shared region s
task A and task B. The shared region S is 4K words long and therefore
requi~es that much space in the virtual address space of
both tasks.
Task A is 6K words long and requires two APRs (APR 0 and APR 1) to map

3-3

TYPICAL TASK BUILDER FACILITIES
its task region.
The first APR available to map the shared region
APR 2. Therefore, APR 2 can be specified when task A is built.

Task B is 16.SK words long.
It requires five APRs to map its task
region.
The first APR available to map the shared region S in task B
is APR 5. Therefore, APR 5 can be specified when task B is built.
If you do not.specify which APR the Task Builder is to use
to map a
position-independent
shared
region,
the
Task
Builder
will
automatically select the highest set of APRs available
in the
referencing task's virtual address space.
In Figure 3-3, for example,
if APR 2 in task A and APR 5 in task B had not been selected at
task-build time,
the Task Builder would have automatically selected
APR 7 in both cases.
Declaring a region to be position independent causes the Task Builder
to
include
in the .STB file for the region an entry for each program
section in the region.
Each entry declares the program section's
name, attributes, and length.
In addition, the Task Builder includes
in the .STB file every symbol in the shared
region and
its value
relative to the beginning of the region.
You specify that a shared region is position independent when you
build it by attaching the PI switch to the image file specification
for the region.
(Refer to Chapter 6 for a description of the PI
switch.) You should declare a region position independent if:
will
execute
correctly
the address space of the

•

The region contains code that
regardless of its location in
referencing task.

•

The region contains data that is not address dependent.

•

The region contains data that will be referenced by a
program (such data must reside in a named common).

Because
the
program
section
name
is
preserved
position-independent
region,
you
should observe the
precautions when building and referring to the region:

FORTRAN
in
a
following

•

No code or data in the region should be included in the
(. BLK.) program section.

•

No code or data in a
referencing task should appear
in a
program section of the same name as a program section in the
shared region.

•

The order in which memory is allocated to program ·sections
(alphabetic or sequential)
must be the same for the shared
region and its referencing tasks.
(Chapter
2 describes
alphabetic
ordering of program sections.
Refer to the
description of the SQ switch in Chapter 6 for
an explanation
of sequential ordering of program sections.)

3-4

blank

TYPICAL TASK BUILDER FACILITIES

4 K WORDS

SHARED
REGION

APR 7-·

APR 7-

APR 15-

APR 6SHARED
REGION

APR !5-

APR 5-

APR 4-·

APR 4-

APR :3-

APR 3SHARED
REGION

TASK B

APR :2-

APR 2-

APR 1TASK A

APR 0-

16.5 K
WORDS

APR 1-

6 K WORDS

..______,J

Fiqure 3-3

APR 0-

Specifying APRs for a Position-Independent Shared Region

3-5

TYPICAL TASK BUILDER FACILITIES
3.1.3

Absolute Shared Regions

When a shared region is absolute, the only program section name that
will appear in the .STB file for the region will be the absolute
program section name (.ABS.). The Task Builder includes in the
.STB
file for the region each symbol in the region and its value.
But,
because the Task Builder does not include the program section names of
an absolute shared region in its .STB file, all code or data in the
region must be referred to by global symbol name.
When a shared region is absolute, you select the virtual addresses for
it when you build it. Thus, an absolute shared region is fixed in the
virtual address space of all tasks that refer to it.
Figure 3-4 shows three tasks (task C, task D, and task E) and a single
absolute shared region, L. The absolute shared region L is 6K words
long and is built to occupy virtual addresses 120000(8) to 150000(8).
These addresses correspond to APR 5 and APR 6, respectively. Tasks C
and D can be linked to region L because at the time they are built APR
5 and APR 6 are unused in both tasks.
However, task E is 23K words
long and even though it has 8K words of virtual address space
available to map the shared region, APR 5 (which corresponds to
virtual address 120000, the base address of the shared region)
has
been allocated to the task region.
If shared region L were position
independent, task E could be linked to it.
You specify that a shared region is absolute when you build it by
simply omitting the PI switch from the task image file.
You establish
the virtual address for the region by specifying the base address of
the region as a parameter of the PAR option.
You should build a shared region absolute if:
•

The region contains code that must appear
in a
location in the address space of a referencing task.

•

The region contains data that is address dependent.

•

The region contains program sections of
program sections in referencing tasks.

the

same

specific

name

Because the Task Builder does not place program section names in the
.STB file of an absolute shared region, the Task Builder places no
restrictions on the way the program sections are ordered in either the
absolute shared region or the tasks that reference it.

3.1.4

Linking to a Shared Region

When you build a task that links to a shared region, you must indicate
to the Task Builder the name of the shared region and the type of
access the task requires to it
(read/write or read-only).
In
addition,
if the shared region is position independent, you can
specify which APR the Task Builder is to allocate for mapping the
region into the task's virtual address space.
Four options are
available for this action:
•

RESLIB (Resident Library)

•

RESCOM (Resident Common)

•

LIBR (System-Owned Resident Library)

•

COMMON (System-Owned Resident Common)
3-6

TYPICAL TASK BUILDER FACILITIES

6 K WORDS

ABSOLUTE
SHARED
REGION

VIRTUAL

120000

APR 7-

APR fi-

I ..________,
l_

APR 7-

ABSOLUTE
SHARED
HEGION

APR 6-

ABSOLUTE
SHARED
REGION

APR 6-

APR fi-

APR 5-

APR 4-

APR ~I-·

APR 3-

APR 2'-

APR 2-

APR 1-

APR 0-

TASK D

APR 2-

TASK C

APR 0-·

Figure 3-4

Mapping for an Absolute Shared Region

3-7

TASK E

TYPICAL TASK BUILDER FACILITIES
RESLIB and RESCOM accept a complete file specification as one of their
arguments.
Thus,
you can specify a device and UFD indicating to the
Task Builder the location of the
region's
image file and,
by
implication, its symbol definition file.
(Refer to Chapter 1 for more
information on file specifications and defaults.)
LIBR and COMMON accept a 1- to 6-character name.
When you specify
either of these options,
the shared region's image file and symbol
definition file must reside under UFD [1,1] on device LBO:.
The RESLIB and RESCOM options require that all users of the shared
region know the UFD under which the shared region's image file and
.STB file reside.
The LIBR and COMMON options require only that the
users of· the shared region know the name of the shared region.
When
you specify either LIBR or COMMON,
by default,
the Task Builder
expects to find the shared region's image and .STB files on device LB:
under UFD [1,1].
All four options accept two additional arguments:
•

The type of access the task requires (RO or RW)

•

The first APR that the Task Builder is to allocate for mapping
the
region
into the task's virtual address space.
As stated
earlier, this argument is valid only when the shared region is
position independent.

When you specify any of these options, the Task Builder expects to
find
a
symbol definition file of the same name as the shared region,
but with an extension of .STB, on the same device and under
the same
UFD as the shared region's image file.
The syntax of these options is given in Chapter 6.
When the Task Builder builds a task, it processes first any options
that appear
in the Task Builder command sequence. When the Task
Builder processes one of the four options above, it locates the disk
image of the shared region named in the option. The disk image of a
shared region does not have a header, but it does have a
label block
that contains the allocation information about the shared region (for
example, its base address, load size, the name of the partition for
which it was built).
The Task Builder extracts this data from the
shared region's label block and places it in the LIBRARY REQUEST
section of the label block for the referencing task.
The .STB file associated with the shared region is an object module
file.
The Task Builder processes it as an input file.
If the shared
region is position independent, its .STB file contains program section
names, attributes and lengths.
However, the program section names are
flagged within the file as "library" program sections and the Task
Builder does not add their allocations to the task image it is
building.
If the task links to only one shared region, and if neither the shared
region nor the task that links to it contain memory-resident overlays,
the Task Builder will allocate two window blocks in the header of the
task.
(Overlays are described in Chapter 4.)
When the task is
installed, the INSTALL processor will initialize these window blocks
as follows:
•

Window block 0 will describe the range
(the window) for the task region.

•

Window block 1 will describe the window for the shared region.

3-8

virtual

addresses

TYPICAL TASK BUILDER FACILITIES
Figure 3-5 shows the window-to-region relationship of such a task.

HIGHEST VIRTUAL
ADDRESS

SHARED
REGION

WINDOW BLOCK
1
WINDOW BLOCK

TASK
MEMORY

HEADER AND STACK
LOWEST V I R T U A L - - - - - ADDRESS

Figure 3-5

Windows for Shared Region and Referencing Task

3-9

TYPICAL TASK BUILDER FACILITIES
A shared region need not be installed before a task that links to
it
is built.
The
.STB file that you specify when you build the shared
region contains all the information required by the Task Builder to
resolve references from within a task to locations within the shared
region. The only requirement is that you install a shared region
before you install a task that links to it.
The number of shared regions to which a task can link is a function of
the number of window blocks required to map the task and the regions.
In an RSX-llM operating system, if a task is 4K words or less,
and
each shared region to which the task links is 4K words or less, then a
nonprivileged task can access as many as seven shared regions.
In an RSX-llM-PLUS operating system, if a task is 4K words or less,
and each shared region to which the task links is 4K words or less, a
nonprivileged task can refer to as many as 15 shared regions:
seven
in user-mode and eight in supervisor-mode.
(Supervisor-mode libraries
are described in later sections of this chapter.)
Finally, the way the Task Builder processes tasks that link to shared
regions leads to an important Task Builder restriction on tasks that
link to position-independent shared regions.
The Task Builder places
all program section names into its internal control section table.
This includes program section names from the .STB file of the .shared
region as well as the program section names from the other input
modules.
When the Task Builder builds a task that links to a shared
region,
if the task contains program sections of the same name as
program sections in the shared region, the Task Builder will attempt
to add the program section allocation in the task to the ~lready
existing allocation for the program section of the same name
in the
shared region.
This is not possible because the region's image has
already been built, is outside the address space of the task currently
being built and cannot be modified. Therefore, the program section
names within a task that links to a position-independent shared region
must normally be unique with respect to program section names within
the shared region.
Should this conflict occur and the program section within the
referencing task contain data, when the Task Builder attempts to
initialize the program section,
it will
recognize that it
is
attempting to store data in an image outside the address limits of the
task it is building. The Task Builder will then print the following
message on the terminal:
TKB--*DIAG*-LOAD ADDR OUT OF RANGE IN MODULE module-name
One exception to the above
following conditions exist:

restriction

develops

when

all

the

program sections
(in the shared region and
in the
• Both
referencing task)
have the
(D)
data and the OVR (overlay)
attributes
•

The program section in the task is equal to
the program section in the shared region

shorter

•

The program section in the task does not contain data.

than

When all of these conditions exist, there is nothing to be initialized
within the shared region. The Task Builder binds the base address of
the program section in the task to the base address of the program
section in the shared region.
If the program section in the task
contains global symbols, the Task Builder will assign addresses to
them that reflect their location relative to the beginning of the

3-10

TYPICAL TASK BUILDER FACILITIES
program section. You can use this technique to establish symbolic
offsets into resident commons.
Examples 1 and 2 in the following
sections illustrate how to establish these offsets.

Example 1: Building and Linking to a Common in MACR0-11

3.1.5

The text in this section and the figures associated with it illustrate
the~ development of a MACR0-11 position-independent resident common and
the development of two MACR0-11 tasks that share the common.
The
steps in building a position-independent common can be summarized as
follows:
1.

You create a source file that allocates the amount of space
required
for
the common.
In MACR0-11, either of the
assembler directives, .BLKB or .BLKW, provide the means of
allocating this space.

You assemble the source file.

You build the assembled module specifying both a
file and a symbol definition file.

task

image

You specify the -HD (no header) switch and declare the common
to be position independent with the PI switch.
Under options you specify:
STACK=O
PAR=parname
The parname in this PAR option is the name of the partition
in which the common is to reside.
(The HD and PI switches
and the STACK and PAR options are described in Chapter 6.)
If your system is an RSX-llM system, the common must reside
within a common partition of the same name as the common.
If your system is an RSX-llM-PLUS system,
the common
reside within any partition large enough to hold it.

can

You install the common.

Figure 3-6 below shows a MACR0-11 source file that, when assembled and
built, will create a positidn-independent resident common area named
MACCOM. The common area consists of two program sections named COMl
and COM2, respectively.
Each program section is 512(10) words long •
• TITLE MACCOM
COMl COM2 -

512 WORDS
512 WORDS

.PSECT COMl,RW,D,GBL,REL,OVR
.BLKW 512 •
• PSECT COM2,RW,D,GBL,REL,OVR
.BLKW 512 •
• END
Figure 3-6

Common Area Source File in MACR0-11

3-11

TYPICAL TASK BUILDER FACILITIES
Once this common has been assembled, the Task Builder command sequence
shown below can be used to build it.
TKB>MACCOM/PI-HD,MACCOM/-SP,MACCOM=MACCOM
TKB>/
ENTER OPTIONS:
TKB>STACK=O
TKB>PAR=MACCOM:0:4000
TKB>//
This command sequence directs the Task
Builder
to
build
a
position-independent (/P~), headerless (/-HD), common image file named
MACCOM.TSK.
It also specifies that the Task Builder is to create a
map file,
MACCOM.MAP, and a symbol definition file, MACCOM.STB. The
Task Builder will create all three files, MACCOM.TSK, MACCOM.MAP, and
MACCOM.STB on device SY:
under the UFD that corresponds to the
terminal UIC.
Because /-SP is attached to the map file,
the Task
Builder will not spool a map listing to the line printer.
Under options, STACK=O suppresses
image.

the

stack

area

the

common's

The PAR option specifies that the common area will
reside within a
common partition of the same name as the common, MACCOM.
As stated
above, on an RSX-llM system this is a requirement;
on an RSX-llM-PLUS
system it is not.
In addition,
the parameters in the PAR option
specify a base of zero and a length of octal bytes for the common
(Refer to Chapter 6 for descriptions of the switches and options used
in this example.)
Figure 3-7 shows the map resulting from this command sequence.
The task attributes section of this map reflects the switches and
options of the command string.
It indicates that the common resides
in a partition named MACCOM, that it was built under terminal UIC
[303,3],
that it is headerless and position independent, and that it
requires one window block to map.
The total length of the common is
1024(10)
words and its address limits range from 0 to 3777(8). The
common image (that portion of the disk image file that eventually will
be read into memory)
begins at file-relative disk block 3 . , • The
last block in the file is file-relative disk block 6 f.) and the common
image is four blocks long 8 .
The memory allocation synopsis details the Task Builder's allocation
for and the attributes of the program sections within the common.
For
example, reading from left to right,
the map indicates that the
program section COMl permits read/write access, that it contains data,
and that its scope is global.
It also
indicates that COMl
is
relocatable and that all contributions to COMl are to be overlaid.
Because COMl has the overlay attribute, the total allocation for
it
will be equal to the largest allocation request from the modules that
contribute to
it.
(For more information
on
program
section
attributes, see Chapter 2.)
Continuing to the right, the first 6-digit number
is COMl's base
address which is 0 () • The next two digits are its length (bytes) in
octal and decimal, respectively 0.

3-12

TYPICAL TASK BUILDER FACILITIES
The next line down lists the first object module that contributes to
COMl.
In this case there is only one:
the module MACCOM from the
file MACCOM.OBJ;2. The numbers on this line indicate the relative
base address of the contribution and the length of the contribution in
octail and dee imal 0 . If there had been more than one module input to
the Task Builder that contained a program section named COMl, the Task
Builder would have listed each module and
its contribution in this
section.
Notice that there is a program section named • BLK. shown on the map
just above the field for COMl. This is the "blank" program section
that is automatically created by the language translators.
The
attributes shown are the default attributes.
The allocation for
s
BLK.
is zero because the program sections in MACCOM were explicitly
declared.
If the program sections had not been explicitly declared,
all of the allocation for the common would have been within this
pro9ram section.
MACCOM.TSK;2

MEMORY ALLOCATION MAP TKB M36
7-FEB-79
13: 51

PAGE 1

PARTITION NAME
MACCOM
IDENTIFICATION
TASK UIC
[303,3]
TASK ATTRIBUTES: -HD,PI
TOTAL ADDRESS WINDOWS: 1.
TASI< !MAGE SIZE
: 10 24. WORDS
TASK ADDRESS LIMITS: 000000 003777
R-W DISK BLK LIMITS: 000003 000006 000004 00004.

Task
Attributes
Section

*** ROOT SEGMENT: MAC~~~

R/W MEM LIMITS: 000000 003777 004000 02048.
DISK BLK LIMITS: 000002 000005 000004 00004.
MEMORY ALLOCATION SYNOPSIS:
SEC'TION
• BLK.: (RW,I ,LCL.,REL,CON)
COMl
:(RW,D,GBL,REL,OVR)
COM2

000000
002000
002000
002000
002000

:(RW,D,GBL,REL,OVR)

TITLE

!DENT FILE

MAC COM

MACCOM.OBJ;2

MAC COM

MACCOM.OBJ;2

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 178.
WORK FILE READS: O.
WORK FILE WRITES: O.
SIZE OF CORE POOL: 8198. WORDS (32. PAGES)
SIZE OF WORK FILE: 768. WORDS (3~ PAGES)
ELAPSED TIME:00:00:06
Figure 3-7

Task Builder Map for MACCOM.TSK

3-13

TYPICAL TASK BUILDER FACILITIES
Figure 3-8 is a diagram that represents the disk image file
for
MACCOM.
The circled numbers in Figure 3-8 correspond to the circled
numbers in Figure 3-7.

RELATIVE
LOAD
ADDRESSES

RELATIVE
DISK BLOCK
NUMBERS

•
•

000006

COM 2

002000

000005

000004

•

COM 1

002000 (BYTES)

000000

000003

000002

•
•
•

LABEL BLOCK

000001
DISK IMAGE FILE

Figure 3-8

Allocation Diagram for MACCOM.TSK

Once you have built MACCOM, you can install it.
If your system is an
RSX-llM system, the common will be loaded into memory when you install
it.
It will remain there until you explicitly remove it with the MCR
command, REMOVE.
If your system is an RSX-llM-PLUS system,
the common
loaded until either one of the following occurs:

will

•

A task that is linked to it is run.

•

You explicitly fix the common in memory with the MCR
FIX.

not

command,

Figures 3-9 and 3-10 show two programs
MCOMl
and
MCOM2,
respectively.
Both of these programs reference the common area MACCOM
created above.
MCOMl in Figure 3-9 accesses the COMl portion of
MACCOM.
It inserts into the first ten words of COMl the numbers 1
through 10 in ascending order.
It then issues an Executive directive
request for the task MCOM2 and suspends itself.

3-14

TYPICAL TASK BUILDER FACILITIES
When MCOM2 runs, it sums the integers left in COMl by MCOMl and leaves
the result in the first word of COM2.
It then issues a resume
directive for MCOMl and exits.
When MCOMl resumes, it retrieves the answer left in COM2 and calls the
system library routine $EDMSG (edit message) to format the answer for
output to device TI:.
All of the Executive directives for both programs
(RQST$C, SPND$S,
QIOW$S, RSUM$C, and EXIT$S)
are documented in the RSX-llM-PLUS
Executive Reference Manual. The system library routine $EDMSG is
documented in the IAS/RSX-11 System Library Routines Reference Manual •
• TITLE
.IDENT

MCOMl
/01/

.MCALL

EXIT$S,SPND$S,RQST$C,QIOW$S

OUT:
.BLKW
FORMAT: .ASCIZ
MES:
.ASCII
LEN = •
• l~VEN

100.
/THE RESULT IS %D./
/ERROR FROM REQUEST/
- MES

; SCRATCH AREA

PSECT - COMl IS USED TO ACCESS THE FIRST 512. WORDS OF THE
COMMON •
INT:

• PSECT
.BLKW

COMl,GBL,OVR,D
10.

PSECT - COM2 IS USED TO ACCESS THE SECOND 512. WORDS OF THE
COMMON. IT WILL CONTAIN THE RESULT
ANS:

.PSECT
• BLKW

COM2,GBL,OVR,D
1

.PSECT
START:

10:~:

NUMBER OF INTEGERS TO SUM
START WITH A 1
PLACE VALUES IN lST 10 WORDS
OF COMMON
INITIALIZE COMMON
Rl, (R3) +
Rl
NEXT INTEGER
RO
ONE LESS TIME
10$
TO INITIALIZE
MCOM2
REQUEST THE SECOND TASK
ERRl
REQUEST FAILED
WAIT FOR MCOM2 TO SUM THE INTEGERS
#OUT,RO
ADDRESS OF SCRATCH AREA
#FORMAT,Rl
FORMAT SPECIFICATION
#ANS,R2
ARGUMENT TO CONVERT
$EDMSG
; DO CONVERSION
#IO.WVB,#5,#l,,,,<#OUT,Rl,#40>
#10. ,RO
#1,Rl
#INT,R3

MOV
MOV
MOV
MOV
INC
DEC
BNE
RQST$C
BCS
SPND$S
MOV
MOV
MOV
CALL
QIOW$S
EXIT$S

ERRl:
QIOW$S
EXIT$S
.END

#IO.WVB,#5,#l,,,,<#MES,#LEN,#40>
START

Figure 3-9

MACR0-11 Source Listing for MCOMl

3-15

TYPICAL TASK BUILDER FACILITIES

MES:

.TITLE
• !DENT

MCOM2
/01/

.MCALL

EXIT$S,QIOW$S,RSUM$C

.ASCII /ERROR FROM RESUME/
LEN = • - MES
.EVEN
PSECT - COMl IS USED TO ACCESS THE FIRST 10. WORDS OF THE
COMMON.
~PSECT

INT:

.BLKW

COMl,GBL,OVR,D
10.

PSECT - COM2 rs USED TO ACCESS THE SECOND 10. WORDS OF THE
COMMON. IT WILL CONTAIN THE RESULT
ANS:

.PSECT
• BLKW

COM2,GBL,OVR,D
1

.PSECT
START:

10$:

MOV
MOV

#10.,RO

CLR
ADD
DEC
BNE

ANS
{R3)+,ANS
10$

NUMBER OF INTEGERS TO SUM
PLACE VALUES IN lST 10 WORDS
OF COMMMON
INITIALIZE ANSWER
ADD IN VALUES
ONE LESS VALUE
TO SUM

RSUM$C
BCS
EXIT$S

MCOMl
ERR

RESUME MCOMl
RESUME FAILED

QIOW$S
EXIT$S
.END

#IO.WVB,#5,#1,,,,<#MES,#LEN,#40>

#INT,R3

ERR:

START

Figure 3-10

MACR0-11 Source Listing for MCOM2

Note that both tasks MCOMl and MCOM2 contain .PSECT declarations that
establish program section names that are the same as program section
names within the position-independent common to which the task is
linked
{MACCOM). As stated earlier, in most circumstances this would
be illegal.
In this application, however, the .PSECT directives have
been placed into the tasks to establish symbolic offsets in the
resident common. When either task is built,
the Task Builder will
assign to the symbol INT:
the base address of program section COMl,
and to the symbol ANS:
the base address of program section COM2.
Figure 3-11 illustrates this assignment.

3-16

TYPICAL TASK BUILDER FACILITIES

- - --

I N T : _ c_ _ _ _ _ _ _ _ _ __

Figure 3-11

Assigning Symbolic References Within a Common

Once you have assembled MCOMl and MCOM2, you can build them
following Task Builder command sequences:

with

the

>TKB
TKB>MCOMl,MCOMl/-SP=MCOMl
TKB>/
ENTER OPTIONS:
TKB>RESCOM=MACCOM/RW
'TKB>/ I

>TKB
TKB>MCOM2,MCOM2/-SP=MCOM2
TKB>/
ENTER OPTIONS:
TKB>RESCOM=MACCOM/RW
TKB>//
Under options in both of these command sequences,
the RESCOM option
tells the Task Builder that these programs intend to reference a
common data area named MACCOM and that the tasks require read/write
acceiss to it.
Because the RESCOM option is used, the Task Builder expects to find
the image file and the symbol definition file for the common on device
SY:
under the UFD that corresponds to the terminal UIC.
In addition,
because the optional APR specification was omitted from the RESCOM
option, the Task Builder a~locates virtual address space for
the
common starting with APR7 in both tasks {the highest APR available in
both tasks).
The Task Builder map for MCOMl is shown in Figure 3-12. The map for
MCOM2 is not essentially different from that of MCOMl and is therefore
not included here.

3-17

TYPICAL TASK BUILDER FACILITIES
MCOM1.TSK;23

PAGE l

MEMORY ALLOCATION MAP TKB M36
7-FEB-79
14:32

PARTITION NAME
GEN
IDENTIFICATION
01
TASK UIC
[303,3]
STACK
LIMITS: 000212 001211 001000 00512.
PRG XFR ADDRESS: 001566
TOTAL ADDRESS WINDOWS: 2.
TASK IMAGE SIZE
1120. WORDS
TASK ADDRESS LIMITS: 000000 004273
R-W DISK BLK LIMITS: 000002 000006 000005 00005.

Task
Attributes
Section

*** ROOT SEGMENT: MCOMl
R/W MEM LIMITS: 000000 004273 004274 02236.
DISK BLK LIMITS: 000002 000006 000005 00005.
MEMORY ALLOCATION SYNOPSIS:
TITLE

SECTION

-------

!DENT

001212 002630 01432.
. BLK.: (RW,I ,LCL,REL,CON) 001212
000574 00380. MCOMl 01

CO Ml

: (RW,D,GBL,REL,OVR) 160000
160000
COM2
: (RW,D,GBL,REL,OVR) 162000
162000
LNC$D : (RW,D,GBL,REL,CON) 004042
$DPB$$: (RW,I,LCL,REL,CON) 004044
004044
$$RESL: (RW,I,LCL,REL,CON) 004062
$$RESM: (RW,I,LCL,REL,CON) 004106

002000
000024
002000
000002
000002
000016
000016
000024
000166

01024.
00020. MCOMl
01024.
00002. MCOMl
00002.
00014.
00014 .. MCOMl
00020.
00ll8.

FILE
MCOM1.0BJ;2

MCOM1.0BJ;2

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 2125.
WORK FILE READS: O.
WORK FILE WRITES: O.
SIZE OF CORE POOL: 8198. WORDS (32. PAGES)
SIZE OF WORK FILE: 1024. WORDS (4. PAGES)
ELAPSED TIME:00:00:06
Figure 3-12

Task Builder Map for MCOMl.TSK

Note that the Task Builder has placed two window blocks in MCOMl's
header.
When
MCOMl is installed, the INSTALL processor will
initialize these window blocks as follows:
•

Window block 0 will describe the range
(the window) for MCOMl's task region.

•

Window block 1 will describe the window for the shared
MACCOM.

3-18

virtual

addresses
region

TYPICAL TASK BUILDER FACILITIES
3.1.6

Example 2: Building and Linking to a Device Common in MACR0-11

A device common is a special type of common that occupies physical
addresses on the I/O page. When mapped into the virtual address space
of a task, a device common permits the task to manipulate peripheral
device registers directly.
NOTE
Because any access to the I/O page is
_ potentially hazardous to the running
system, you
must
exercise
extreme
device
caution
when
working
with
commons.
The remaining text in this section and the figures associated with it
illustrate the development and use of a device common.
Figure 3-13
shows an assembly listing for a position-independent device common
named TTCOM.
When installed, TTCOM will map the control and data
registers of the console terminal.
Its physical base address will be
777500.

RCSR::
RBU.F'::
XCSR::
XBU.F'::

.TITLE TTCOM
.PSECT TTCOM
.=.+60
.BLKW
l
.BLKW
l
.BLKW
l
.BLKW
l
.END
Figure 3-13

Assembly Listing for TTCOM

The PDP-11 Peripherals Handbook defines the control and data register
addresses for the console terminal.
In Figure 3-13, the register
addresses and the symbol names that correspond to them are as follows:
Register

Address

Symbol

Keyboard Status
Keyboard Data
Printer Status
Printer Data

777560
777562
777564
777566

RCSR
RBUF
XCSR
XBUF

The double colon (::) following each symbol in Figure 3-13 establishes
the symbol as global.
The first symbol, RCSR, is offset from the
beginning of TTCOM by 60(8) bytes.
Each symbol thereafter is one word
removed from the symbol that precedes it.
Thus, when TTCOM is
installed at 777500, each symbol will be located at its proper
address.
Once you have assembled TTCOM, you can build it
Task Builder command sequence:

using

the

following

> TKB
TKB> LB: [l,l]TTCOM/-HD/PI,LB: [l,l]TTCOM/-WI,LB: [l,l]TTCOM=TTCOM
TKB> /
ENTER OPTIONS:
TKB> STACK=O
TKB> PAR=TTCOM:O:lOO
TKB> //
3-19

TYPICAL TASK BUILDER FACILITIES
This command sequence directs the Task Builder to create a common
image named TTCOM.TSK and a symbol d~finition file named TTCOM.STB.
The Task Builder will place both files on device LB:
under UFO [1,1].
The command sequence also specifies that the Task Builder is to spool
a map listing to the line printer. The -WI switch specifies an 80
column line printer listing format.
NOTE
For the command sequence above to work
in a multiuser protection system, it
must be
input
from
a
privileged
terminal.
Under options, STACK=O suppresses the stack area in the common's image
file.
The PAR option specifies that the device common will reside within a
partition of the same name as the common.
As with the data common in
Example 1 (Section 3.1.5),
this is a
requirement of the RSX-llM
system;
in an RSX-llM-PLUS system it is not.
The PAR option also
specifies that the base of the common is 0 and that it is 100(8) bytes
long.
The Task Builder map for TTCOM that results from the command sequence
above
is shown in Figure 3-14. The task attributes section of this
map indicates that the common is position independent and that no
header
is associated with it.
The common's image and symbol
definition file reside on device LB:
under UFO [1,1].
The map in Figure 3-14 shows the global symbols defined in the common
with their relative offsets into the common region. You establish the
virtual base address for the common and the virtual addresses for the
symbols within it when you build the tasks that link to the common.
You establish the physical addresses for
the common with the MCR
command, SET.
The keyword that you use with the SET command depends
on which system you are running.
If your system is an RSX-llM system,
use the command:
>SET

/MAIN=TTCOM:7775:1~

If your system is an RSX-llM-PLUS system, use the command:
>SET /PAR=TTCOM:7775:l:DEV
Both sequences create a main partition named TTCOM that begins at
physical address 777500.
The partition is one 64-byte block long,
(100(8) bytes). The arguments COM and DEV identify the partition
type. With the common built ~nd the partition for it created, you can
install TTCOM.
You can establish the partition for a device common at any time
in
both the RSX-llM and the RSX-llM-PLUS systems.
Partitions created to
accommodate a device common are not a system generation consideration
because they represent areas of physical address space above memory
and therefore cannot conflict with memory partitions.

3-20

TYPICAL TASK BUILDER FACILITIES
TTCOM.TSK;l

MEMORY ALLOCATION MAP TKB
9-NOV-78.
14:25

PAGE 1

PARTITION NAME : TTCOM
IDENTIFICATION :
TASK UIC
(1,1]
TASK ATTRIBUTES: -HD,PI
TOTAL ADDRESS WINDOWS: 1.
TASK IMAGE SIZE
32. WORDS
TASK ADDRESS LIMITS: 000000 000067
R-W DISK BLK LIMITS: 000003 000003 000001 00001.

TASK
ATTRIBUTES
SECTION

*** ROOT SEGMENT: TTCOM
R/W MEM LIMITS: 000000 000067 000070 00056.
DISK BLK LIMITS: 000002 000002 000001 00001.
MEMORY ALLOCATION SYNOPSIS:
TITLE

SECTION

• BLK.: (RW,I,LCL,REL,CON) 000000 000000 00000.
TTCOM : (RW,I,LCL,REL,CON) 000000 000070 00056.
000000 000070 00056. TTCOM

!DENT

FILE

TTCOM.OBJ;l

GLOBAL SYMBOLS:
RBUF

000062-R

RCSR

000060-R

XBUF

000066-R

XCSR

000064-R

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 220.
WORK FILE READS: O.
WORK FILE WRITES: O.
SIZE OF CORE POOL: 2062. WORDS (8. PAGES)
SIZE OF WORK FILE: 768. WORDS (3. PAGES)
ELAPSED TIME:00:00:02
Figure 3-14

Task Builder Map for TTCOM

Figure 3-15 shows an assembly listing for a demonstration program
named TEST.
When built and installed, TEST will print the letters A
through z on the console terminal by directly accessing the console
terminal status and data registers.
It will access the status and
data registers through the device common TTCOM.

3-21

TYPICAL TASK BUILDER FACILITIES
.TITLE TEST
• !DENT /01/
.MCALL EXIT$S
START:

MOV
CALL
MOV
CALL
MOV
MOV
OUTPUT: CALL
DEC
BNE
MOV
CALL
MOV
CALL
EXIT$S
OUTBYT: TSTB
BPL
MOV
INC
RETURN
.END

#15,RO
OUTBYT
#12,RO
OUTBYT
#101,RO
#26.,Rl
OUTBYT
Rl
OUTPUT
#15 ,RO
OUTBYT
#12 ,RO
OUTBYT
XCSR
OUTBYT
RO,XBUF
RO

START WITH A CARRIAGE RETURN
PRINT IT
THEN A LINE FEED
PRINT IT
FIRST LETTER IS AN "A"
NUMBER OF LETTERS TO PRINT
PRINT CURRENT LETTER
ONE LESS TIME
; AGAIN
ANOTHER CARRIAGE RETURN
ANOTHER LINE FEED
OUTPUT BUFFER READY?
IF NOT WAIT
MOVE CHARACTER TO OUTPUT BUFFER
INITIALIZE NEXT LETTER

START

Figure 3-15

Assembly Listing for TEST

Once you have assembled TEST, you can build it with the following Task
Builder command sequence:
>TKB
TKB>TEST,TEST/-WI/MA=TEST
TKB>/
ENTER OPTIONS:
TKB>COMMON=TTCOM:RW:l
TKB>//
Under options, the COMMON option in this command sequence tells the
Task Builder that TEST intends to access the device common TTCOM and,
that TEST will have read/write access to it.
It also directs the Task
Builder to reserve APR 1 for mapping the common into TEST's virtual
address space.
The Task Builder map that results from the command sequence
shown in Figure 3-16.

above

This map contains a global symbols section. The Task Builder included
it because the MA switch was applied to the memory allocation file at
task-build time. Note that the global symbols in this section, which
were defined in TTCOM, now have virtual addresses assigned to them.
The addresses assigned by the Task Builder are the result of the APR 1
specification in the COMMON= keyword during the task build.
It is important to remember that programs like TEST, which access the
I/O page, take complete control of the registers they reference.
Therefore, coding errors in such programs can disable the devices they
reference and can even make it impossible for the device drivers to
regain control of the device.
If this happens, you must reboot the
system.

3-22

TYPICAL TASK BUILDER FACILITIES
TES'I'. TSK; 2

PAGE 1

MEMORY ALLOCATION MAP TKB
9-NOV-78 14:35

PARTITION NAME : GEN
IDENTIFICATION : 01
TASK UIC
[301,356]
STACK
LIMITS: 000212 001211 001000 00512.
PRG XFR ADDRESS: 001212
TOTAL ADDRESS WINDOWS: 2.
TASK IMAGE SIZE
384. WORDS
TASK ADDRESS LIMITS: 000000 001317
R-W DISK BLK LIMITS: 000002 000003 000002 00002.

Task
Attributes
Section

*** ROOT SEGMEN~: TEST
R/W MEM LIMITS: 000000 001317 001320 00720.
DISK BLK LIMITS: 000002 000003 000002 00002.
MEMORY ALLOCATION SYNOPSIS:
TITLE

SEC~f!ON

• BLK.: (RW,I,LCL,REL,CON) 001212
001212
TTCOM : (RW,I,LCL,REL,CON) 020000
020000

000104
000104
000070
000070

!DENT

00068.
00068 • • MAIN. 01
00056.
00056. TTCOM 01

FILE

TEST.OBJ;l
TTCOM.STB;l

GLOBAL SYMBOLS:
RBUJP

020062-R

RCSR

020060-R

XBUF

020066-R

XCSR

020064-R

3.1.7

Memory Allocation Map for TEST

Example 3: Building and Linking to a Resident Library in MACR0-11

Resident libraries consist of subroutines that are shared by two or
more tasks. When such tasks reside in physical memory simultaneously,
resident libraries provide a considerable memory savings because the
subroutines within the library appear in memory only once.
The text in this section and the figures associated with it illustrate
the development and use of a resident library, called LIB.

3-23

TYPICAL TASK BUILDER FACILITIES
Figure 3-17 shows five FORTRAN callable subroutines:

• An integer addition routine, AADD
• An integer subtraction routine, SUBB
• An integer multiplication routine, MULL
• An integer division routine, DIVV
• A register save and restore coroutine, SAVAL
These subroutines are contained in a single source file,
LIB.MAC.
When assembled and built,
they will constitute an example of a
resident library.
FORTRAN callable routines were used in this example
so that the library can be accessed by either FORTRAN or MACR0-11
programs •
• TITLE
• !DENT

LIB
/01/

.PSECT

AADD,RO,I,GBL,REL,CON

;** FORTRAN CALLABLE SUBROUTINE TO ADD TWO INTEGERS
AADD::

CALL
MOV
MOV
ADD
MOV
RETURN

$SAVAL
@2(R5),RO
@4(R5),Rl
RO,Rl
Rl,@6(R5)

.PSECT

SUBB,RO,I,GBL,REL,CON

SAVE RO-.RS
FIRST OPERAND
SECOND OPERAND
SUM THEM
STORE RESULT
RESTORE REGISTERS AND RETURN

;** FORTRAN CALLABLE SUBROUTINE TO SUBTRACT TWO INTEGERS
SUBB: :

CALL
MOV
MOV
SUB
MOV
RETURN

$SAVAL
@2(R5),RO
@4(R5),Rl
Rl,RO
R0,@6(R5)

.PSECT

MULL,RO,I,GBL,REL,CON

Figure 3-17

SAVE RO-RS
FIRST OPERAND
SECOND OPERAND
SUBTRACT SECOND FROM FIRST
STORE RESULT
RESTORE REGISTERS AND RETURN

Source Listing for Resident Library LIB.MAC

3-24

TYPICAL TASK BUILDER FACILITIES
;** FORTRAN CALLABLE SUBROUTINE TO MULTIPLY TWO INTEGERS
MULL::

CALL
MOV
MOV
MUL
MOV
RETURN

$SAVAL
@2(RS),RO
@4(RS),Rl
RO,Rl
Rl,@6(RS)

.PSECT

DIVV,RO,I,GBL,REL,CON

SAVE RO-RS
FIRST OPERAND
SECOND OPERAND
MULTIPLY
STORE RESULT
RESTORE REGISTERS AND RETURN

;** FORTRAN CALLABLE SUBROUTINE TO DIVIDE TWO INTEGERS
DIVV::

CA.LL
MOV
MOV
CLR
DIV
MOV
RETURN

$SAVAL
@2(RS),R3
@4(RS),Rl
R2
Rl,R2
R2,@6(RS)

.PSECT

SAVAL,RO,I,GBL,REL,CON

SAVE REGS RO-RS
FIRST OPERAND
SECOND OPERAND
LOW ORDER 16 BITS
DIVIDE
STORE RESULT
RESTORE REGISTERS AND RETURN

;**ROUTINE TO SAVE REGISTERS
$SAVAL::
MOV
MOV
MOV
MOV
MOV
MOV
MOV
CALL
MOV
MOV
MOV
MOV
MOV
MOV
RETURN
.END

R4,-(SP}
R3,-(SP}
R2,-(SP)
Rl,-(SP}
RO,-(SP)
12 (SP),- (SP)
RS,14(SP)
@(SP)+
(SP)+,RO
(SP}+,Rl
(SP)+,R2
(SP)+,R3
(SP}+,R4
(SP)+,RS

Figure 3-17 (Cont.)

;SAVE R4
;SAVE R3
;SAVE R2
;SAVE Rl
;SAVE RO
;COPY RETURN
;SAVE RS
;CALL THE CALLER
;RESTORE RO
;RESTORE Rl
;RESTORE R2
;RESTORE R3
;RESTORE R4
;RESTORE RS

Source Listing for Resident Library LIB.MAC

3-2S

TYPICAL TASK BUILDER FACILITIES
Once you have assembled LIB, you can build it with the following
Builder command sequence:

Task

TKB>.LIB/PI/-HD,LIB/-WI,LIB=LIB
TKB>/
ENTER OPTIONS:
TKB>STACK=O
TKB>PAR=LIB:0:200
TKB>//
This

command

sequence instructs the Task Builder to
build
a
(/PI), headerless
(/-HD)
library image named
LIB.TSK. It instructs the Task Builder to create a map file LIB.MAP
and to output an 80 column listing (/-WI) to the line printer. It
also sp~cifies that the Task Builder is to create a symbol definition
file, LIB.STB. The Task Builder will create all three files, LIB.TSK,
LIB.MAP, LIB.STB on device SY:
under the UFO that corresponds to. the
terminal UIC.

position~independent

Under options, STACK=O suppresses the stack area within
library's image.

the

resident

The PAR option tells the Task Builder that the resident library will
reside within a partition of the same name as the library. As with
all shared regions, this is a requirement in an RSX-llM system;
in an
RSX-llM-PLUS system it is not.
In addition, the PAR option specifies
that the base of the library is 0 and that it is 200(8)
bytes long.
(For more information on the switches and options used in this
example, refer to Chapter 6.)
Figure 3-18 shows the Task Builder map that results from
sequence above.

the

command

Note in the global symbols section of the map in Figure 3-18 that the
Task Builder has assigned offsets to the symbols for each library
function. When the task that links to this library is built, the Task
Builder will assign virtual addresses to these symbols.
The program MAIN in Figure 3-19 exercises the routines in the resident
library LIB.TSK. When you assemble and build it, MAIN will call upon
the library routines to add, subtract, multiply, and divide the
integers contained in the labels OPl and OP2 within the program. MAIN
will print the results of each operation to device TI:.

3-26

TYPICAL TASK BUILDER FACILITIES
LIB .. TSK; 12

MEMORY ALLOCATION MAP TKB M36
7-FEB-79
14:47

PAGE 1

PARTITION NAME : LIB
IDENTIFICATION : 01
TASK UIC
[303,3]
TASK ATTRIBUTES: -HD,PI
TOTAL ADDRESS WINDOWS: 1.
TASK IMAGE SIZE
64. WORDS
TASK ADDRESS LIMITS: 000000 000163
R-W DISK BLK LIMITS: 000003 000002 000000 00000.

TASK
ATTRIBUTES
SECTION

*** ROOT SEGMENT: LIB

R/W MEM LIMITS: 000000 000163 000164 00116.
DISK BLK LIMITS: 000002 000002 000001 00001.
MEMORY ALLOCATION SYNOPSIS:
SECUON

---·----

BLK.: (RW,I ,LCL,REL,CON) 000000 000000
AADD : (RO,I,GBL,REL,CON) 000000 000024
000000 000024
DIVV : (RO,I,GBL,REL,CON) 000024 000026
000024 000026
MULL : (RO,I,GBL,REL,CON) 000052 000024
000052 000024
SAVJ\L : (RO,I,GBL,REL,CON) 000076 000042
000076 000042
SUBB : (RO,I ,GBL,REL,CON) 000140 000024
000140 000024

00000 •
00020.
00020.
00022.
00022.
00020.
00020.
00034.
00034.
00020.
00020.

TITLE

!DENT

FILE

LIB

LIB.OBJ;2

LIB

LIB.OBJ;2

LIB

LIB .OBJ; 2

LIB

LIB.OBJ;2

LIB

LIB.OBJ;2

GLOBAL SYMBOLS:
AADD
DIVV

000000-R
000024-R

MULL
000052-R SUBB
$SAVAL 000076-R

000140-R

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 376.
WORK FILE READS: O.
WORK FILE WRITES: O.
SIZE O.F CORE POOL: 8198. WORDS (32. PAGES)
SIZE OF WORK FILE: 768. WORDS (3. PAGES)
ELAPSED TIME:00:00:04
Figure 3-18

Task Builder Map for LIB.TSK

3-27

TYPICAL TASK BUILDER FACILITIES
.TITLE
• !DENT

MAIN
/01/

;+
;**MAIN - CALLING ROUTINE TO EXERCISE THE ARITHMETIC ROUTINES
FOUND IN THE RESIDENT LIBRARY, LIB.TSK.
;

OPl:
OP2:
ANS:

.MCALL

QIOW$S,EXIT$S

.WORD
.WORD
.BLKW

1
1
1

.BLKW
OUT:
FORMAT: .ASCIZ
.EVEN

100.
/THE ANSWER

.ENABL

LSB

MOV
MOV
MOV
MOV
MOV
CALL
CALL
MOV
CALL
CALL
MOV
CALL
CALL
MOV
CALL
CALL
EXIT$S

#ANS,-(SP}
#0P2,-(SP}
#OPl,-(SP}
#3,-(SP}
SP,RS
AADD
PRINT
SP,R5
SUBB
PRINT
SP,R5
MULL
PRINT
SP,R5
DIVV
PRINT

OPERAND 1
OPERAND 2
RESULT
FORMAT MESSAGE
%D./

START:
TO CONTAIN RESULT
OPERAND 2
OPERAND 1
PASSING 3 ARGUMENTS
ADDRESS OF ARGUMENT BLOCK
ADD TWO OPERANDS
PRINT RESULTS
ADDRESS OF ARGUMENT BLOCK
SUBTRACT SUBROUTINE
PRINT RESULTS
ADDRESS OF ARGUMENT BLOCK
MULTIPLY SUBROUTINE
PRINT RESULTS
ADDRESS OF ARGUMENT BLOCK
DIVIDE SUBROUTINE
PRINT RESULTS

;+
;** PRINT - PRINT RESULT OF OPERATION.
;-

PRINT:

MOV
MOV
MOV
CALL
QIOW$S
RETURN
.END

#OUT,RO
ADDRESS OF SCRATCH AREA
#FORMAT,Rl
FORMAT SPECIFICATION
#ANS,R2
ARGUMENT TO CONVERT
$EDMSG
; FORMAT MESSAGE
#IO.WVB,#5,#1,,,,<#0UT,Rl,#40>
; RETURN FROM SUBROUTINE
START
Figure 3-19

Source Listing for MAIN.MAC

3-28

TYPICAL TASK BUILDER FACILITIES
Once you have assembled MAIN, you can use the following
command sequence to build it:

Task

Builder

TKB>MAIN,MAIN/MA/-WI/-SP=MAIN
TKB>/
ENTER OPTIONS:
TKB>RESLIB=LIB/R0:3
TKB>//
This command sequence instructs the Task Builder to build a task file
named MAIN.TSK on device SY:
under the UFO that corresponds to the
terminal UIC.
It also specifies that the Task Builder is to create a
map file MAIN.MAP~ The MA switch requests an extended map format.
In
this example, /MA was applied to the device specification so that the
Task Builder would include in the map for the task the symbols within
the library LIB. The negated form of the wide listing switch
(/-WI)
was appended to the map specification to obtain an 80-column map
format.
In this example, the Task Builder will not output a map
listing to the line printer
Under options, the RESLIB option specifies that the task MAIN is to
access the library LIB and that it requires read-only access to LIB.
The Task Builder will use APR3 to map the library.
The Task Builder map that results from this command sequence is
in Figure 3-20.
MAIN.TSK;l5

MEMORY ALLOCATION MAP TKB M36
30-APR-79
10:33

PARTITION NAME
GEN
IDENTIFICATION
01
TASK UIC
[303,3]
STACK
LIMITS: 000212 001211 001000 00512.
PRG XFR ADDRESS: 001552
TOTAL ADDRESS WINDOWS: 2.
TASK IMAGE SIZE
1120. WORDS
TASK ADDRESS LIMITS: 000000 004213
R-W DISK BLK LIMITS: 000002 000006 000005 00005.

PAGE 1

TASK
ATTRIBUTES
SECTION

*** ROOT SEGMENT: MAIN
R/W MEM LIMITS: 000000 004213 004214 02188.
DISK BLK LIMITS: 000002 000006 000005 00005.
Figure 3-20

Task Builder Map for MAIN.TSK

3-29

shown

TYPICAL TASK BUILDER FACILITIES
MEMORY ALLOCATION SYNOPSIS:
SECTION

TITLE

-------

IDE NT

FILE

EDTMG
CBTA
CDDMG
CATB
C5TA
EDDAT

01
12
04.3
00
03
02
02

MAIN.OBJ;l
SYSLIB.OLB;40
SYSLIB .OLB; 40
SYSLIB.OLB;40
SYSLIB.OLB;40
SYSLIB.OLB;40
SYSLIB.OLB;40

LIB

LIB.STB;l3

LIB

LIB.STB;l3

EDTMG

SYSLIB.OLB;40

LIB

LIB.STB;l3

LIB

LIB.STB;l3

LIB

LIB.STB;l3

SAVRG

SYSLIB.OLB;40

001212 002564 01396.
. BLK.: (RW,I ,LCL,REL,CON) 001212
000530 00344. MAIN

AADD

: (RO,I,GBL,REL,CON)

DIVV

: (RO,I ,GBL,REL,CON)

LNC$D : (RW,D,GBL,REL,CON)
MULL

: (RO,I,GBL,REL,CON)

SAVAL : (RO,I,GBL,REL,CON)
SUBB

: (RO,! ,GBL,REL,CON)

$$RESL: (RW,I,LCL,REL,CON)
$$RESM: (RW,I,LCL,REL,CON)

001742 001016
002760 000216
003176 000126
003324 000074
003420 000110
003530 000246
060000 000024
060000 000024
060024 000026
060024 000026
003776 000002
003776 000002
060052 000024
060052 000024
060076 000042
060076 000042
060140 000024
060140 000024
004000 000024
004000 000024
004024 000166
004024 000066
004112 000100

00526.
00142.
00086.
00060.
00072.
00166.
00020.
00020.
00022.
00022.
00002.
00002.
00020.
00020.
00034.
00034.
00020.
00020.
00020.
00020.
00118.
00054.
00064.

ARI TH 03.02
DARI TH 0005

SYSLIB .OLB; 40
SYSLIB.OLB;40

GLOBAL SYMBOLS:
AADD
DIVV
IO.WVB
MULL

060000-R
060024-R
011000
060052-R

MAIN. TSK; 15
MAIN

$COTB
$C5TA
$DAT

003332-R
003420-R
003574-R

SAVAL
SUBB
$CBDAT
$CBDMG

060076-R
060140-R
002760-R
002766-R

$CBDSG
$CBOMG
$CBOSG
$CBTA

002774-R
003002-R
003010-R
003040-R

MEMORY ALLOCATION MAP TKB M36
30-APR-79
10:33

$DDIV
$DIV
$DMUL

004150-R
004054-R
004112-R

$EDMSG 002036-R
$LNCNT 003776-R
$MUL
004024-R

$CBTMG
$CBVER
$CDDMG
$CDTB

003016-R
003002-R
003176-R
003324-R

PAGE 2

$SAVRG 004000-R
$TIM
003652-R

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 2518.
WORK FILE READS: 0.
WORK FILE WRITES: 0.
SIZE OF CORE POOL: 8200. WORDS (32. PAGES)
SIZE OF WORK FILE: 1024. WORDS (4. PAGES)
ELAPSED TIME:OO:OO:l9
Figure 3-20 (Cont.)

Task Builder Map for MAIN.TSK

3-30

TYPICAL TASK BUILDER FACILITIES
This map contains a global symbols section.
Note that the symbols
within the library now have virtual addresses assigned to them and
that these addresses begin at 60000(8) -- the virtual base address of
APR 3.
The Task Builder's allocation of virtual address space for
MAIN.TSK is represented diagrammatically in Figure 3-21.

APR 7APR 6-

APR 5 APR4-

VI R:TUAL 60000 APR 3-

APR 2-

APR 1 -

""""""_.....L_i_s_.T_s_,.K.,.,.,...,.......... }

WINDOW 1 REGION 1

\ ii!!li

~-M-A-IN_._T_s_K

_ _ }wlNDOW 0 REGION 0

VIRTUAL 0 APR CY-

Figure 3-21

Allocation of Virtual Address Space for MAIN.TSK

The library LIB is position independent and can therefore be mapped
anywhere
in the referencing task's virtual address space.
APR 3 was
used in this example to contrast this mapping arrangement with the
mapping of MACCOM in the virtual address space of task MCOMl in
Example 1 (Section 3.1.5).
If the optional APR parameter
in the
RESLIB option above had been left blank, the Task Builder would have
allocated the highest available APR to map the library.
As described in earlier sections of this chapter,
program section
names within position-independent shared regions must normally be
unique with respect to program section names within tasks that
reference them.
When a shared_ region is a position-independent
resident common and you explicitly declare the program section names
within it, avoiding program section name conflicts is an easy matter.
However, when a
shared region is a
position-independent resident
library that contains calls to
routines within an object module
library (SYSLIB, for example), conflicts may develop that are not
apparent to you.
The problem arises when the position-independent
resident library and one or more tasks that link to it contain calls
to separate routines residing within the same program section of an
object module library.
When the Task Builder resolves a call
from within a module
it
is
processing to a routine within an object module library, it places the
routine from the library into the
image it is building.
It also
enters into its internal table the name of the program section in the

3-31

TYPICAL TASK BUILDER FACILITIES
object module library within which the routine resides.
If a
position-independent resident library contains a call to a routine
within a given program section of SYSLIB,
for
example,
and then
subsequently a task that links to the resident library contains a call
to a different routine within the same program section of SYSLIB, both
the resident library and the referencing task will contain the program
section name.
When you build the referencing task, the library's .STB
file will contain the program section name and a program section
conflict will develop.
(Refer
to Section 3.1.4 for
additional
information on the sequence in which the Task Builder processes tasks
and the potential program section name conflicts that can result.)
This situation and one possible solution to it can be illustrated with
Example 3.
When this example was first created, only the arithmetic
routines were included in the source file of the resident library
(LIB.MAC in Figure 3-17). The system library coroutine ($SAVAL) was
resolved from SYSLIB.
Because the first
instruction
of
each
arithmetic
routine called $SAVAL, the Task Builder included a copy of
it in the resident library's image at task-build time.
This turned
out to be unsatisfactory because of a call to the SYSLIB routine
$EDMSG (edit message) within the program MAIN that links to the
resident library.
Both routines ($SAVAL and $EDMSG) reside within the
unnamed or blank program section (.
BLK.) within SYSLIB.
Therefore,
a program section name conflict developed when MAIN was built.
To circumvent this problem, the source code for
$SAVAL was
included
into the source file
for the resident library under the explicitly
declared program section name, SAVAL.
Another solution would have been to build the
absolute.
In this case,
the Task Builder would
program section names from the resident library
definition file for the library when the library was

resident library
not have included
into the symbol
built.

It is important to note that the above program section name conflict
develops only when two different routines residing within the same
program section of an object module library are involved.
It presents
no problem when a resident library and a task that links to it contain
a call to the same routine in an object module library.
In that case,
the Task Builder copies the routine and the program section name in
which it resides into the resident library when the library is built.
Then,
when the task that calls the same routine is built, the Task
Builder will resolve the reference to the routine
in the resident
library instead of in the object module library.

3.1.8 Example 4: Building and Linking to a Supervisor-Mode Library in
MACR0-11 (RSX-llM-PLUS Only)
Supervisor-mode libraries are a special type of resident library that
provide you with the means to effectively double the address space of
your task and thereby extend the physical memory to which your
task
has access.
Supervisor-mode libraries are particularly useful when
used to accommodate large run-time systems.
Supervisor-mode libraries are mapped with the instruction space APRs
of
the
processor's supervisor mode
(Supervisor APR 0 through
Supervisor APR 7).
Once you have
linked
your
task
to
a
supervisor-mode library,
a call
from within your task to a global
symbol within the library automatically causes a context switch from
user mode to supervisor mode.
Control of the processor is then
assumed by the called library routine.
When the library routine
executes a
return,
control of the processor
is transferred to a

3-32

TYPICAL TASK BUILDER FACILITIES
completion routine within the library. It is the completion routine's
responsibility to perform the return context switch from supervisor
mode to user mode.
(Completion routines are described later in this
section.)
When you build a task that links to a supervisor-mode library, the
Task Builder replaces each call from the task to a routine within the
library with a 4-word vector. This vector contains a transfer of
control instruction to a routine ($SUPL) that switches the processor
from user mode to supervisor mode. It also contains the address of
the completion routine and the address of the entry point of the
called library routine.
(Refer to Figure B-14 in Appendix B.)
Figure 3-22 shows a typical mapping arrangement for a 14K
supervisor-mode library and a 24K word task that refers to it.

SUPERVISOR MODE
(INSTRUCTION SPACE)

word

USER MODE
(INSTRUCTION SPACE)

:::::::::::::::.Y.:~.Y.:$.:~:.9..::::::::::::::
APR 7 -

APR 7

APR fi

SUPERVISORMODE
LIBRARY

APR6-

APR !5

APR 5 -

APR 4

APR4-

APR :3

APR3 -

APR 2

APR 2 -

APR 1

APR 1 -

REFERENCING
TASK

HEADER & STACK

Figure 3-22

Typical Mapping for Supervisor-Mode Library

When the processor context switches from user mode to supervisor mode,
the system copies the user-mode instruction APRs (which map the task
image) into the supervisor-mode data space APRs. Therefore, when the
processor is running in supervisor mode under control of a library
routine, any data within the task image is available to the routine.
For example, library routines that require parameters or pointers to
parameters in registers or through low core impure area pointers can
obtain the parameters transparently.
Figure 3-23 shows a typical
mapping arrangement when a supervisor-mode routine is in control of
the processor.

3-33

TYPICAL TASK BUILDER FACILITIES

SUPERVISOR MODE
(INSTRUCTION SPACE)

USER MODE
(INSTRUCTION SPACE)

UNUSED
APR 7 -

APR6-

APR 7 -

I
SUPERVISORMODE
LIBRARY

APR 5 -

APR 6 -

APR 5/-

I
APR4-

I
I

APR3-

APR 2 -

· J

APRO-

SUPERVISOR MODE
(DATA SPACE)

APR6-

~~..-.-.-.

APR 3 -

APR2APR 1 -

APRO-

HEADER & STACK

;,/

APR4-

COPY
OF
REFERENCING
TASK

APR 2 -

APR 1 -

APRO-

REFERENCING
TASK

I
I
I
I
I
I
I I

APR5-

APR3-

APR7-

APR4-

APR 1 -

,!~! '~il li;Il ~f

HEADER & STACK

Figure 3-23

I
I

Task Mapping while Running in Supervisor Mode

3-34

TYPICAL TASK BUILDER FACILITIES
Building a supervisor-mode library is essentially the same as building
a conventional
resident library.
When you build a supervisor-mode
library, you suppress the header by attaching /-HD to the task
image
file~.
During option input, you suppress the stack area by specifying
STACK=O. You specify the partition in which the library is to
reside
and,, optionally,
the base address and length of the library with the
PAR option~
You indicate to the Task Builder that
you
are
building
a
supervisor-mode library with the CMPRT option. The argument for this
option identifies the entry symbol of the completion routine.
When
the Task Builder processes this option,
it places the completion
routine entry point in the library's .STB file.
{Refer to Chapter 6
for mo~e information on the CMPRT option).
The following
restrictions
supervisor-mode library.

are

placed

the

within

the

contents

Only subroutines using JSR PC, X should be
library.

used

The library must not contain subroutines that use the stack
to pass parameters if tasks referring to the library call the
same routines.

The library must not contain data of any kind.
This
includes:
user data,
buffers,
I/O status blocks,
and
directive parameter blocks {the $S directive form can be used
because the directive parameter block for
this form of
directive is pushed onto the stack at run time).

When you build a supervisor-mode library, you must include within it a
completion routine that performs the following:

Transfers any condition code bits that are relevant to your
user-mode task from the Processor Status Word {PSW) to the
Processor Status Word on the stack. All condition code bits
in the stacked PSW are set to 0 during the context switch
from user to supervisor-mode.

Writes an appropriate value into the user stack pointer,
because the user stack will not be context switched.

Executes an ·RTI instruction.

Following is an example of a completion routine from
library, LB: [l,l]SYSLIB.OLB which returns the carry bit:
$COMPL::

ADC
MOV
ADD
MTPI
RT!

2{SP)
#6,-(SP)
SP,{SP)
SP

the

system

;TRANSFER CARRY BIT
;CALCULATE USER SP VALUE
;CHANGE USER STACK POINTER VALUE
;RETURN TO CALLER

The system library contains two other completion routines:
e
e

$CMPAL
$CMPRV

which returns status bits NZVC
which sets up PS for privileged tasks

Figure 3-24 shows a module containing three routines:
a sort routine
{SORT::), a
search routine
{SEARCH::), and a completion routine
{$COMPL::). When assembled and built, these routines will constitute
an example of a supervisor-mode library.

3-35

TYPICAL TASK BUILDER FACILITIES
.TITLE
• !DENT

SUPLIB
/01/

CALL
TST
MOV
MOV
MOV
MOV
DEC

$SAVAL
(R5)+
(R5)+,RO
(R5)+,R4
(R4) ,R4
RO,R5
R4

SAVE ALL REGISTERS
SKIP OVER NUMBER OF ARGUMENTS
GET ADDRESS OF LIST
GET ADDRESS OF LENGTH OF LIST
GET LENGTH OF LIST

MOV
MOV

R5,RO
R4,R3

COPY
COPY LENGTH OF LIST

TST
CMP
BLE
MOV
MOV
MOV

(RO)+
(R5), (RO)
30$
(R5),R2
(RO), (R5)
R2,(RO)

MOVE POINTER TO NEXT ITEM
COMPARE ITEMS
IF LE IN CORRECT ORDER
SWAP ITEMS

DEC
BNE
DEC
BEQ
TST
BR

R3
20$
R4
40$
(R5)+
10$

DECREMENT LOOP COUNT
IF NE LOOP
DECREMENT
IF EQ SORT COMPLETED
GET POINTER TO NEXT ITEM TO BE COMPARED

CALL
CMP
BNE
MOV
MOV
MOV
MOV
MOV
MOV

$SAVAL
#4, (R5)+
20$
(R5)+,RO
(R5)+,Rl
(R5)+,R2
(R2) ,R2
(R5),R5
R2,R3

SAVE ALL THE REGISTERS
FOUR ARGUMENTS?
IF NE NO
GET ADDRESS OF NUMBER TO LOCATE
ADDRESS OF LIST SEARCHING
GET ADDRESS OF LENGTH OF LIST
GET LENGTH OF LIST
ADDRESS OF RETURNED VALUE
COPY LENGTH

CMP
BEQ
BM!
DEC
BNE

(RO),(Rl)+
30$
20$
R2
10$

IS THIS THE NUMBER?
IF EQ YES
IF MI NUMBER NOT THERE
DECREMENT LOOP COUNT
IF NE NOT AT END OF LIST

MOV
RETURN

#-1, (R5)

END OF LIST PASS BACK ERROR

SUB
INC
MOV
RETURN

R2,R3
R3
R3,(R5)

NUMBER FOUND - GET INDEX INTO LIST

SORT::

10$:
20$:

30$:

40$:
RETURN
SEARCH::

10$:

20$:
30$:

Figure 3-24

RETURN INDEX

Source Listing for SUPLIB.MAC

3-36

TYPICAL TASK BUILDER FACILITIES
$COMPL::
ADC
M~

ADD
MTPI
RTI

2(SP)
#6,-(SP)
SP,(SP)
SP

COMPLETION ROUTINE

RETURN TO USER MODE

.END
Figure 3-24

(Cont.)

Source Listing for SUPLIB.MAC

Once you have assembled SUPLIB, you can build it
Task Builder command string:

with

the

following

TKB>SUPLIB/-HD,SUPLIB/MA/-SP,SUPLIB=SUPLIB
TKB>/
ENTER OPTIONS:
TKB>STACK=O
TKB>CMPRT=$COMPL
TKB>PAR~SUPLIB:l60000:2000

TKB>GBLXCL=$SAVAL
TKB>//
This command sequence directs the Task Builder to create a headerless
image file (/-HD) named SUPLIB.TSK and to create an extended map file
(/MA) named SUPLIB.MAP. Because /-SP is appended to the map file, the
Task Builder will not output it to the line printer.
It also
specifies that the Task Builder is to create a
.STB file named
SUPLIB.STB.
Under options, STACK=O suppresses the stack area
in SUPLIB's task
image.
The CMPRT option identifies the global symbol of the
completion routine within SUPLIB. The Task Builder will place this
global symbol in a special entry in the library's .STB file.
The PAR
option specifies to the Task Builder that SUPLIB will reside within a
partition of the same name as the library.
This is not a requirement.
The PAR option also specifies to the Task Builder that SUPLIB will
have a base address of 160000, and that it will be 2000(8) bytes long.
The GBLXCL option directs the Task Builder to exclude from SUPLIB's
.STB file
the global symbol $SAVAL.
$SAVAL is a system library
coroutine that saves the contents of all general registers.
It uses
the stack to pass parameters. When SUPLIB is built, the Task Builder
will resolve the reference to $SAVAL by including the $SAVAL routine
into SUPLIB's image file.
Since it is known that the task TSUP
(described below) will be linked to SUPLIB at a later time,
and that
TSUP also contains a call to $SAVAL,
the symbol $SAVAL must be
excluded from SUPLIB's .STB file .o prevent the Task Builder from
resolving the call in TSUP to the $SAVAL routine in SUPLIB. The net
result of excluding the symbol from SUPLIB's .STB file
is that the
Task Builder will include separate copies of $SAVAL in SUPLIB and in
the task that links to it TSUP.
(For more information on the switches
and options used in this example, refer to Chapter 6.)
Suppose the symbol $SAVAL were not excluded from SUPLIB's .STB file.
When the Task Builder built TSUP, instead of resolving the reference
to SYSLIB, it would resolve the reference to the routine existing
within SUPLIB.
When TSUP ran,
t~e call to $SAVAL within it would
cause a context switch from user mode to supervisor mode.
$SAVAL
would execute but,
because it is a coroutine, it would attempt a
direct call back to TSUP (which resides in user mode)
instead of
returning to user mode through a completion routine.

3-37

TYPICAL TASK BUILDER FACILITIES
This illegal return call would fail and cause the system to trap.
Note also, that SUPLIB is built absolute.
That is,
the
PI
(position-independent) switch is not attached to the library image
file. As written, SUPLIB must be absolute to prevent a program
section name conflict between SUPLIB and the task that links to it,
TSUP. Even though the symbol $SAVAL was excluded from SUPLIB's .STB
file, the program section in which $SAVAL resides in SYSLIB was not.
When the Task Builder resolves the reference to $SAVAL in TSUP, it
will place the routine into TSUP's image file and the program section
name in which it resides will be placed into the Task Builder's
internal section table. If, when TSUP is built, the program section
name were allowed to remain in the .STB file, a conflict would
develop.
(Refer to Section 3.1.4 for additional information.)
The map that results from the above command sequence is shown in
Figure 3-25. Note that the virtual addresses for the symbols SEARCH,
SORT, $COMPL, and the entry point for the system library coroutine
$SAVAL have already been established. The Task Builder establishes
the virtual addresses for these symbols when it builds SUPLIB because
SUPLIB is absolute.
If SUPLIB were built position independent, the
Task Builder would defer the assignment of virtual addresses for these
symbols until the tasks that link to the library are built.
The program TSUP in Figure 3-26 uses the sort and search routines in
the example in Figure 3-24. When you link TSUP to SUPLIB, install and
run it, TSUP will prompt for a number by printing ARRAY= on your
terminal. When you type a number, TSUP will place the number you have
typed into ah array and prompt you again in the same manner. It will
continue to prompt you until it has prompted you 10 times or until you
type a O, whichever comes first. After you have input 10 numbers or
typed a O, TSUP will use the sort routine in SUPLIB to sort the
numbers in ascending order. It will then print them on your console
terminal.
Once it has printed the numbers, it will prompt for a
number with the following message:
NUMBER TO SEARCH FOR?
When you respond by typing a number, TSUP will use the search routine
in SUPLIB to search the array for the number. If the number is in the
array, TSUP will print it on your terminal. If the number is not in
the array, TSUP will report that fact.
TSUP uses three system library routines: $SAVAL (save all registers
coroutine), $EDMSG (edit message routine), and $CDTB (decimal to
binary conversion routine).
These routines are described in the
IAS/RSX-11 System Library Routines Reference Manual. The Executive
directives used by TSUP (QIOW$, DIR$, and QIOW$S) are described in the
RSX-llM/M-PLUS Executive Reference Manual.

3-38

TYPICAL TASK BUILDER FACILITIES
SUPLIB.TSK;l7

PAGE 1

MEMORY ALLOCATION MAP
TKB M35
29-DEC-78
09:18

PARTITION NAME : SUPLIB
IDENTIFICATION : 01
TASK UIC
[301,356]
TASK ATTRIBUTES: -HD
TOTAL ADDRESS WINDOWS: 1.
TASK IMAGE SIZE
96. WORDS
TASK ADDRESS LIMITS: 160000 160213
R-W DISK BLK LIMITS: 000003 000002 000000 00000.

TASK
ATTRIBUTES
SECTION

*** ROOT SEGMENT: SUPLIB
R/W MEM LIMITS: 160000 160213 000214 00140.
DISK BLK LIMITS: 000002 000002 000001 00001.
MEMORY ALLOCATION SYNOPSIS:
TITLE

SECTION

!DENT

• BLK.: (RW,I,LCL 1 REL,CON) 160000 000214 00140.
160000 000152 00106. SUPLIB 01
160152 000042 00034. SAVAL 00

FILE
SUPLIB.OBJ;l
SYSLIB .OLB; 6

GLOBAL SYMBOLS:
SEARCH 160056-R

SORT

160000-R

$COMPL 160134-R

$SAVAL 160152-R

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 229.
WORK FILE READS: O.
WORK FILE WRITES: O.
SIZE OF' CORE POOL: 2076. WORDS (8. PAGES)
SIZE OF' WORK FILE: 768. WORDS (3. PAGES)
ELAPSED TIME:OO:OO:OS
Figure 3-25

Task Builder Map for SUPLIB.TSK

3-39

TYPICAL TASK BUILDER FACILITIES
.TITLE
.IDENT

TSUP
/01/

.MCALL

QIOW$,DIR$,QIOW$S

WRITE: QIOW$
READ IN : QIOW$

IO.WVB,S,l,,,,<OUT,,40>
IO.RVB,S,l,,,,<OUT,S>

IARRAY: • BLKW
LEN:
.BLKW
IART:
.BLKW
INDEX:
.BLKW
OUT:
• BLKW
ARGBLK:
EDBUF:
• BLKW

12 •
1
1
1
100 •

FMTl:
FMT2:
FMT3:
FMT4:
FMTS:

/%2SARRAY(%D)=/
/%N%2SNUMBER TO SEARCH FOR?/
/%N%2S%D WAS FOUND IN ARRAY(%D)/
/%N%2S%D WAS NOT IN ARRAY/
/%2SARRAY (%D)=%D/

.ASCIZ
.ASCIZ
.ASCIZ
.ASCIZ
.ASCIZ

10 •

.EVEN
START:
MOV
MOV

#IARRAY,RO
#10,Rl

GET ADDRESS OF ARRAY
SET LENGTH OF ARRAY

CLR
DEC
BNE
MOV
MOV

(RO)+
Rl
S$
#IARRAY,RO
#INDEX ,R2

INITIALIZE ARRAY
LOOP

MOV

#FMTl,Rl

MOV
INC
CALL
CALL
MOV
BEQ
INC
CMP
BNE

(R2),EDBUF
EDBUF
PRINT
READ
IART, (RO)+
20$
(R2)
(R2) ,#10.
10$

FORMAT SPECIFICATION (ADDRESS
OF INPUT STRING)
GET INDEX

MOV
MOV
MOV
MOV
MOV
MOV
CALL
CLR
MOV

(R2),LEN
#ARGBLK,RS
# 2, (RS)+
#IARRAY, (RS)+
#LEN,(RS)
#ARGBLK,RS
SORT
R2
#IARRAY,RO

S$:

10$:

PRINT MESSAGE
READ INPUT
PUT BINARY KEYBOARD INPUT INTO ARRAY
ZERO MARKS END OF INPUT
IF NE YES

20$:

Figure 3-26

CALCULATE LENGTH OF ARRAY
GET ADDRESS OF ARGUMENT BLOCK
NUMBER OF ARGUMENTS
PUT ADDRESS OF ARRAY
SORT ARRAY
GET ARRAY ADDRESS

Source Listing for TSUP.MAC

3-40

TYPICAL TASK BUILDER FACILITIES
30$:
INC
MOV
MOV
MOV
CALL
CMP
BLT
MOV
CALL
CALL
MOV
MOV
MOV
MOV
MOV
MOV
MOV
CALL
TST
BLT
MOV
MOV
MOV
CALL
BR

R2
R2,EDBUF
(RO)+,EDBUF+2
#FMTS,Rl
PRINT
R2,LEN
30$
#FMT2,Rl
PRINT
READ
#ARGBLK,RS
#4, (RS)+
#IART, (RS)+
#I ARRAY, (RS)+
#LEN, (RS)+
#INDEX,(RS)
#ARGBLK,RS
SEARCH
INDEX
40$
IART,EDBUF
INDEX,EDBUF+2
#FMT3,Rl
PRINT
100$

INCREMENT INDEX
GET INDEX FOR PRINT
GET CONTENTS OF ARRAY
GET ADDRESS OF FORMAT SPECIFICATION

MOV
MOV
CALL

#FMT4,Rl
IART,EDBUF
PRINT

GET FORMAT ADDRESS
GET NUMBER

CALL

$EXST

EXIT WITH STATUS

CALL
MOV
MOV
CALL
MOV

$SAVAL
#OUT,RO ; ADDRESS
#EDBUF,R2
$EDMSG
;
Rl,WRITE+Q.IOPL+2

DIR$

#WRITE

SAVE ALL REGISTERS
OF OUTPUT BLOCK
START ADDRESS OF ARGUMENT BLOCK
FORMAT MESSAGE
; PUT LENGTH OF OUTPUT
BLOCK INTO PARAMETER BLOCK
WRITE OUTPUT BLOCK

CALL
DIR$
MOV
CALL
MOV
RE'rURN

$SAVAL
#READIN
#OUT,RO
$CDTB
Rl, IART

; SAVE ALL REGISTERS
READ REQUEST
GET KEYBOARD INPUT
; CONVERT KEYBOARD INPUT TO BINARY
; PUT INPUT INTO BUFFER

.END

START

MORE TO PRINT?
IF LE YES
GET ADDRESS OF FORMAT SPECIFICATION
OUTPUT MESSAGE
READ RESPONSE
SET NUMBER OF ARGUMENTS
SET ADDRESS OF NUMBER LOOKING FOR
SET ADDRESS OF ARRAY
SET ADDRESS OF LEN OF ARRAY
ADDRESS OF RESULT
SEARCH FOR NUMBER IN IART
WAS NUMBER FOUND?
IF LT NO
GET NUMBER LOOKING FOR
GET ARRAY NUMBER
GET FORMAT ADDRESS
DONE

40$:

100$:
PRINT:

RE'I~URN

READ:

Figure 3-26 (Cont.)

Source Listing for TSUP.MAC

3-41

TYPICAL TASK BUILDER FACILITIES
Once you have assembled TSUP, you can build it with the following Task
Builder command sequence:
TKB>TSUP,TSUP/MA/-WI/-SP=TSUP
TKB>/
ENTER OPTIONS:
TKB>RESSUP=SUPLIB/SV
TKB>//
This command sequence directs the Task Builder to build a task image
file TSUP.TSK and to create an extended (/MA) 80 column (/-WI) map
file named TSUP.MAP.
Because /-SP is appended to the map file,
the
Task Builder will not output the map file to the line printer.
Under options, the RESSUP option tells the Task Builder that the task
intends to access a supervisor-mode library and that context switching
vectors are required. The Task Builder expects to find a
library
image file SUPLIB.TSK and a symbol definition file SUPLIB.STB, on
device LB:
under the UFO that corresponds to the terminal UIC.
In
addition, the Task Builder expects to find a special entry in the .STB
file that contains the symbol definition for · the supervisor-mode
library's completion routine ($COMPL). This entry was created by the
Task Builder when SUPLIB was built as a result of the CMPRT option.
(Refer to Chapter 6 for more information on the switches and options
used in this example.) A portion of the map that results from the Task
Builder command sequence above is shown in Figure 3-27.
Note under global symbols in Figure 3-27 that the Task Builder has
changed the virtual addresses for symbols SEARCH, SORT, and $SAVAL
while leaving the virtual address of symbol $COMPL the same as it was
when SUPLIB was built. The new virtual addresses for the first three
symbols are addresses to the context switching vectors that the Task
Builder placed in TSUP's code. The Task Builder did not change the
virtual address of $COMPL because it is referenced only from within
the library.
Therefore,
calls to it do not constitute an initial
processor-mode context switch.
Finally, note that building a resident library as a supervisor-mode
library in no way precludes its use as a "standard" user-mode resident
library. A given resident library might be mapped by one task as a
supervisor-mode library while simultaneously being mapped by another
as a user-mode library.

3-42

TYPICAL TASK BUILDER FACILITIES
TSUP.TSK;6

PAGE 1

MEMORY ALLOCATION MAP TKB M35
29-DEC-78
16:39

PARTITION NAME : GEN
IDENTIFICATION : 01
TASK UIC
[301,356]
STACK
LIMITS: 000212 001211 001000 00512.
PRG XFR ADDRESS: 002046
TOTAL ADDRESS WINDOWS: 2.
TASK IMAGE SIZE
1312. WORDS
TASK ADDRESS LIMITS: 000000 005017
R-W DISK BLK LIMITS: 000002 000007 000006 00006.

TASK
ATTRIBUTES
SECTION

*** ROOT SEGMENT: TSUP
R/W MEM LIMITS: 000000 005017 005020 02576.
DISK BLK LIMITS: 000002 000007 000006 00006.
MEMORY ALLOCATION SYNOPSIS:
SECTION

TITLE

IDENT

FILE

• BLK.: (RW,I,LCL,REL,CON) 001212 003312 01738.
001212 001234 00668. MAIN

TSUP.OBJ;l

$$SUPL: (RW,I,LCL,REL,CON) 004760 000040 00032.
004760 000040 00032. $SUPL

SYSLIB.OLB;6

GLOBAL SYMBOLS:
IO •. RVB 010400
IO .. WVB 011000
SEARCH 004740-R
SORT
004750-R
$CBDAT 003602-R
$CBDMG 003610-R
$CBDSG 003616-R
$CBOMG 003624-R

$CBOSG 003632-R
$CBTA 003662-R
$CBTMG 003640-R
$CBVER 003624-R
$CDDMG 004020-R
$CDTB 002446-R
$COMPL 160134
$COTB 002454-R

$C5TA
$DAT
$DDIV
$DIV
$DMUL
$EDMSG
$EXST
$LNCNT

004146-R
004322-R
004676-R
004602-R
004640-R
002632-R
003522-R
004524-R

$MUL
$SAVAL
$SAVRG
$SUPL
$TIM

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 2544.
WORK FILE READS: O.
WORK FILE WRITES: O.
SIZE OF CORE POOL: 2076. WORDS (8. PAGES)
SIZE OF WORK FILE: 1024. WORDS (4. PAGES)
ELAPSED TIME:00:00:12
Figure 3-27

Task Builder Map for TSUP.TSK

3-43

004552-R
003540-R
004526-R
004766-R
004400-R

TYPICAL TASK BUILDER FACILITIES
3.2

EXAMPLE 5: BUILDING A MULTIUSER TASK (RSX-llM-PLUS ONLY)

A multiuser task is a task that shares the pure (read-only) portion of
its code with two or more copies of the impure (read/write) portion of
its code. When the system receives an initial
run request for
a
multiuser
task,
a copy of both the read-only and read/write portions
of the task are read into physical memory.
As long as the task
is
running, all
subsequent run requests for
it result in the system
duplicating only the
read/write portion of the task
in physical
memory. Thus, multiuser tasks are memory efficient.
You designate a task as multiuser when you build it by applying the MU
switch to the task image file.
This switch directs the Task Builder
to create two regions for
the task.
One region
(region 0)
will
contain the read-write portion of the task;
the other region (region
1) will contain the read-only portion of the task.
As with all other tasks, the Task Builder uses a program section's
access code to determine
its placement within a multiuser task's
image.
It divides address space into read/write and
read-only
sections.
Unlike a single user task, however, in a multiuser task,
the read-only portion of the task is hardware protected.
In addition,
the Task Builder separates the read/write portions of a multiuser task
from the read-only portions and places them in separate regions at
opposite ends of the. task's address space.
It allocates the low
address APRs to the read/write portion
(which includes the task's
header and stack area) and the highest available APRs to the read-only
portion.
Figure 3-28 illustrates this allocation •

...

:UNUSED

.·.·.··.·.·

APR 7 -

............. ·.·

READ-ONLY
PROGRAM
SECTIONS

APR 6 -

APR 5 -

APR4-

APR3-

APR 2 -

READ/WRITE
PROGRAM
SECTIONS

APR 1 -

APR O-

Figure 3-28

HEADER & STACK

Allocation of Program Sections in a Multiuser Task

3-44

TYPICAL TASK BUILDER FACILITIES
If neither the read-only nor
the read/write portion of the
task
contain memory-resident overlays the Task Builder will allocate two
window blocks in the header of the task.
When the task is installed,
the INSTALL processor will initialize these window blocks as follows:
•

Window block O will describe the range of virtual addresses
(the window)
for
the read/write portion of the task.
This
region will always contain the task's header.

•

Window block 1 will describe the range
for the read-only portion.

Figure 3-29 below
multiuser task.

shows

the

window-to-region

HIGHEST VIRTUAL
ADDRESS

virtual

addresses

relationship

· · · · · · · · · · ·~·~.~ ~·~· · · · · · · · · ·
READ-ONLY

REGION 1

WINDOW BLOCK

READ/WRITE
REGION 0

LOWEST VIRTUAL
ADDRESS

Figure 3-29

Windows for a Multiuser Task

If a multiuser task is an overlaid task, the read-only portion of
task can be made up of the following:
•

The read-only program sections of the root segment

3-45

the

TYPICAL TASK BUILDER FACILITIES
•

Branches of an overlay structure if
memory resident and read-only

the

complete

•

A co-tree structure if the entire co-tree is
and read-only.

memory

branch

resident

(Overlaid tasks are described in Chapter 4.)
Finally, the disk image of a multiuser task is somewhat different from
that of a single-user task.
The read-only portion of the task is
placed at the end of the disk image. The relative block number of the
read-only portion and the number of blocks it occupies appears in the
label block. The read-only portion of the image is described
in the
first library descriptor of the LIBRARY REQUEST section of the label
block.
(Refer to Appendix B for more information on the task image
data structures.
The remainder of the text in this section and the figures associated
with it illustrate the development of a multiuser task.
This example
was created by concatenating into a single file the resident library
file
(LIB.MAC)
and the task that links to it (MAIN.MAC) from Example
4.
It is not intended to represent a
typical multiuser task
application.
However,
it
does illustrate the Task Builder's
allocation of program sections in a multiuser task and that is its
primary value.
The concatenated source file, named ROTASK.MAC, for
this example is shown in Figure 3-30.
·

OPl:
OP2:
ANS:

.TITLE
.!DENT

ROTA SK
/01/

.MCALL

QIOW$S,EXIT$S

.WORD
.WORD
.BLKW

1
1
1

• BLKW
OUT:
FORMAT: .ASCIZ
.EVEN

100 •
/THE ANSWER

OPERAND 1
OPERAND 2
RESULT
FORMAT MESSAGE
%D,/

START:
MOV
MOV
MOV
MOV
MOV
CALL
CALL
MOV
CALL
CALL
MOV
CALL
CALL
MOV
CALL
CALL
EXIT$S

#ANS,-(SP)
#0P2,-(SP)
#OPl,-(SP)
#3
,-(SP)
SP,RS
AADD
PRINT
SP,RS
SUBB
PRINT
SP,RS
MULL
PRINT
SP,RS
DIVV
PRINT

Figure 3-30

TO CONTAIN RESULT
OPERAND 2
OPERAND 1
PASSING 3 ARGUMENTS
ADDRESS OF ARGUMENT BLOCK
ADD TWO OPERANDS
PRINT RESULTS
ADDRESS OF ARGUMENT BLOCK
SUBTRACT SUBROUTINE
PRINT RESULTS
ADDRESS OF ARGUMENT BLOCK
MULTIPLY SUBROUTINE
PRINT RESULTS
ADDRESS OF ARGUMENT BLOCK
DIVIDE SUBROUTINE
PRINT RESULTS

Source Listing for ROTASK.MAC

3-46

TYPICAL TASK BUILDER· FACILITIES
;+

;** PRINT - PRINT RESULT OF OPERATION.
;PRINT:

MOV
MOV
MOV
CALL
QIOW$S
RETURN

#OUT,RO
ADDRESS OF SCRATCH AREA
#FORMAT,Rl
FORMAT SPECIFICATION
#ANS,R2
ARGUMENT TO CONVERT
$EDMSG
; FORMAT MESSAGE
#IO.WVB,#S,#l,,,,<#OUT,Rl,#40>
; RETURN FROM SUBROUTINE

;** FORTRAN CALLABLE SUBROUTINE TO ADD TWO INTEGERS

AADD::

.PSECT

AADD,RO,I,GBL,REL,CON

CALL
MOV
MOV
ADD
MOV
RETURN

$SAVAL
@2(RS),RO
@4(RS),Rl
RO,Rl
Rl,@6(RS)

SAVE RO-RS
FIRST OPERAND
SECOND OPERAND
SUM THEM
STORE RESULT
RESTORE REGISTERS AND RETURN

;** FORTRAN CALLABLE SUBROUTINE TO SUBTRACT TWO INTEGERS

SUBB: :

.PSECT

SUBB,RO,I,GBL,REL,CON

CALL
MOV
MOV
SUB
MOV
RE: TURN

$SAVAL
@2(RS),RO
@4(RS),Rl
Rl,RO
R0,@6(RS)

SAVE RO-RS
FIRST OPERAND
SECOND OPERAND
SUBTRACT SECOND FROM FIRST
STORE RESULT
RESTORE REGISTERS AND RETURN

;** FORTRAN CALLABLE SUBROUTINE TO DIVIDE TWO INTEGERS

DIVV::

.PSECT

DIVV,RO,I,GBL,REL,CON

CALL
MOV
MOV
CLR
DIV
MOV
RE:TURN

$SAVAL
@2(RS),R3
@4(RS),Rl
R2
Rl,R2
R2,@6(RS)

SAVE REGS RO-RS
FIRST OPERAND
SECOND OPERAND
LOW ORDER 16 BITS
DIVIDE
STORE RESULT
RESTORE REGISTERS AND RETURN

;** FORTRAN CALLABLE SUBROUTINE TO MULTIPLY TWO INTEGERS

MULL: :

.PSECT

MULL,RO,I,GBL,REL,CON

CALL
MOV
MOV
MUL
MOV
RETURN
.END

$SAVAL
@2(RS),RO
@4(RS),Rl
RO,Rl
Rl,@6(RS)

SAVE RO-RS
FIRST OPERAND
SECOND OPERAND
MULTIPLY
STORE RESULT
RESTORE REGISTERS AND RETURN

START

Figure 3-30 (Cont.)

Source Listing for ROTASK.MAC

3-47

TYPICAL TASK BUILDER FACILITIES
Once you have assembled ROTASK, you can build it
command sequence:

with

the

following

TKB>ROTASK/MU,ROTASK/-WI/-SP=ROTASk
TKB>/
ENTER OPTIONS:
TKB>ROPAR=RDONLY
TKB>//
This command sequence directs the Task Builder to build a multiuser
(/MU)
task image named ROTASK.TSK and to create an 80 column (/-WI)
map file named ROTASK.MAP. Because /-SP is attached to the map file,
the Task Builder will not output a map to the line printer.
Under options, the ROPAR option specifies that the system is to load
the read-only portion of the task into a partition named RDONLY.
Specifying a separate partition for the task's read-only region is not
a system requirement.
The system will load the read/write portion
into partition GEN. The system will not load either region until
it
receives a run request for the task.
The map that results from this command sequence is shown in Figure
3-31.
Note that the Task Builder has added one field to the task
attributes section of this map describing the disk block limits of the
read-only portion of the task.
It has also added a field to the root
segment portion of the map that describes the memory limits of the
read-only portion of the task.
Finally, note that the Task Builder has allocated space for all the
program sections with the read-only attribute beginning with the
highest available APR (in this case, APR 7).

3-48

TYPICAL TASK BUILDER FACILITIES
ROTASK.TSK;6

PAGE 1

MEMORY ALLOCATION MAP TKB M35
6-JAN-79
13:58

PARTITION NAME : GEN
IDENTIFICATION : 01
TASK UIC
[301,356]
STACK
LIMITS: 000212 001211 001000 00512.
PRG XFR ADDRESS: 001552
TASK ATTRIBUTES: MU
TOTAL ADDRESS WINDOWS: 2.
TASK IMAGE SIZE
1120. WORDS
TASK ADDRESS LIMITS: 000000 004217
R-W DISK BLK LIMITS: 000002 000006 000005 00005.
R-0 DISK BLK LIMITS: 000007 000007 000001 00001.

TASK
ATTRIBUTES
SECTION

*** ROOT SEGMENT: ROTASK
R/W MEM LIMITS: 000000 004217 004220 02192.
R-0 MEM LIMITS: 160000 160177 000200 00128.
DISK BLK LIMITS: 000002 000006 000005 00005.
MEMORY ALLOCATION SYNOPSIS:
SECTION

TITLE

-------

ID ENT

FILE

001212 002570 01400 •
. BLK.: (RW,I ,LCL,REL,CON) 001212
000530 00344. ROTA SK

01
AADD

ROTASK.OBJ;6
(RO,I ,GBL,REL,CON) 160000
160000
01
ROTASK.OBJ;6
DIVV : (RO,I,GBL,REL,CON) 160024
160024
01
ROTASK.OBJ;6
LNC$D : (RW,D,GBL,REL,CON) 004002
MULL
: (RO,I,GBL,REL,CON) 160052
160052
01
ROTASK.OBJ;6
SUBB : (RO,I ,GBL,REL,CON) 160076
160076
01
ROTASK.OBJ;6
$$RESL: (RW,I,LCL,REL,CON) 004004
$$RESM: (RW,I,LCL,REL,CON) 004030
~

000024 00020.
000024 00020. ROT ASK'
000026 00022.
000026 00022. ROT ASK
000002 00002.
000024 00020.
000024 00020. ROTA SK
000024 00020.
000024 00020. ROT ASK
000024 00020.
000166 00118.

GLOBAL SYMBOLS:
AADD

160000-R

DIVV

160024-R

MULL

160052-R

SUBB

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 2365.
WORK FILE READS: O.
WORK FILE WRITES: O.
SIZE OF CORE POOL: 2076. WORDS (8. PAGES)
SIZE OF WORK FILE: 1024. WORDS (4. PAGES)
ELAPSED TIME:00:00:06
Figure 3-31

Task Builder Map for ROTASK.TSK

3-49

160076-R

TYPICAL TASK BUILDER FACILITIES
3.3

EXAMPLE 6:

BUILDING A TASK THAT CREATES A DYNAMIC REGION

In all the examples of tasks shown thus far in this chapter, the Task
Builder has automatically constructed and placed in the header of the
task all of the window blocks necessary to map all of the regions of
the task's image.
The INSTALL processor has been responsible for
initializing the window blocks when the task was installed.
In all
the examples, this has been possible because both the Task Builder and
the INSTALL processor have had all the
information concerning the
regions available to them.
When a task creates regions while it is running (dynamic regions), the
information concerning the regions is not available to either the Task
Builder on the INSTALL processor. Therefore, when the Task Builder
builds such a task, it does not automatically create window blocks for
the dynamic regions.
It creates only the window blocks necessary to
map the task region (the region containing the header and stack) and
any shared regions that the task references.
Dynamic regions are created and mapped with Executive directives that
are
imbedded in the task's code. When you build a task that creates
dynamic regions, you must explicitly specify to the Task Builder how
many window blocks (in excess of those created by the Task Builder for
the task region and any shared regions) it is to place in the task's
header.
The Executive will
initialize these window blocks when it
processes the region and mapping directives.
In all (including window
blocks for
the task region and shared regions), you can inlcude as
many as eight window blocks to a task in an RSX-llM system and as many
as 16 in an RSX-llM-PLUS system.
The text in the remainder of this section and the figures associated
with it illustrate the development of a task that creates dynamic
regions.
Figure 3-32 shows a task (DYNAMIC.MAC) that creates a 128
word dynamic region.
This task simply·creates an unnamed region, maps
to it, and fills it with an ascending sequence of numbers beginning at
the region's base and moving upwards.
When the region is full,
DYNAMIC detaches from it and prints the following message on your
terminal:
DYNAMIC IS NOW EXITING
The region is automatically deleted on detach.
All of the Executive directives used by DYNAMIC
(RDBBK$, WDBBK$,
DTRG$S, EXIT$S, CRRG$S, CRAW$S, QIOW$S, and QIOW$C) to create and
manipulate the region are described in the RSX-llM/M-PLUS Executive
Reference Manual.

3-50

TYPICAL TASK BUILDER FACILITIES
• TI~rLE
.!DENT

DYNAMIC
/VOl/

.MCALL
.MCALL

RDBBK$,WDBBK$,DTRG$S,EXIT$S,CRRG$S,CRAW$S
QIOW$C ,QIOW$S

.NLIST

BEX

REGION DESCRIPTOR BLOCK
WORD 0 SIZE OF REGION IN 32 DECIMAL WORD BLOCKS
WORD 1 REGION NAME
1111
WORD 2
WORD 3 NAME OF SYSTEM CONTROLLED PARTITION IN
WORD 4 WHICH REGION WILL BE CREATED
WORD 5 STATUS WORD
WORD 6 PROTECTION WORD
RDB:

RDBBK$

128.,,GEN,<RS.MDL!RS.ATT!RS.DEL!RS.RED!RS.WRT>,170017

WINDOW DESCRIPTOR BLOCK
WORD 0 APR TO BE USED TO MAP REGION
WORD 1 SIZE OF WINDOW IN 32-WORD BLOCKS
WORD 2 REGION ID
WORD 3 OFFSET INTO REGION TO START MAPPING
WORD 4 LENGTH IN 32-WORD BLOCKS TO MAP
WORD 5 STATUS WORD
WDB:

WDBBK$

MESl:

.ASCIZ /DYNAMIC IS NOW EXITING/
Sl = • - MESl
.ASCII /CREATE REGION FAILED/
SIZl = • - ERRl
.ASCII /CREATE ADDRESS WINDOW FAILED/
SIZ2 = • - ERR2
.ASCII /DETACH REGION FAILED/
SIZ3 = • - ERR3
.EVEN
.PAGE
.ENABL LSB

ERRl:
ERR2:
ERR3:

7,128.,0,0,,<WS.MAP!WS.WRT>

STAR'T:

20$:

CRRG$S
BCS
MOV
CRAW$S
BCS
MOV
MOV
.REPT
ASL
• ENDR
MOV
MOV
INC
DEC
BGT
DTRG$S
BCS
QIOW$C
EXIT$S

#ROB
; CREATE A 128 WORD UNNAMED REGION
1$
; FAILED TO CREATE REGION
RDB+R.GID,WDB+W.NRID ; COPY REGION ID INTO WINDOW BLOCK
#WDB
CREATE ADDR WINDOW AND MAP
2$
FAILED TO CREATE ADDR WINDOW
WDB+W.NBAS,RO
BASE ADDR OF CREATED REGION
WDB+W.NSIZ,R2
NUMBER OF 32. WORDS IN REGION
5
MULTIPLY
R2
BY
32 •
#1,Rl
INITIAL VALUE TO PLACE IN REGION
Rl,(RO)+
MOVE VALUE INTO REGION
Rl
NEXT VALUE TO PLACE IN REGION
R2
ONE LESS WORD LEFT
20$
TO FILL IN
#ROB
DETACH AND DELETE REGION
3$
; DETACH FAILED
IO~WVB,5,1,,,,<MESl,Sl,40>

Figure 3-32

Source Listing for DYNAMIC.MAC

3-51

TYPICAL TASK BUILDER FACILITIES

ERROR ROUTINES
;

1$:
2$:
3$:
6$:

MOV
MOV
BR
MOV
MOV
BR
MOV
MOV
QIOW$S
EXIT$S
.END

CREATE FAILED
#ERRl,RO
SIZ OF MESSAGE
#SIZl ,Rl
6$
WRITE MESSAGE
#ERR2,RO
CREATE ADDRESS WINDOW FAILED
#SIZ2,Rl
SIZE OF MESSAGE
6$
#ERR3,RO
DETACH FAILED
#SIZl ,Rl
; SIZE OF MESSAGE
#IO.WVB,#5,#l,,,,<RO,Rl,#40>
START

Figure 3-32 (Cont.)

Source Listing for DYNAMIC.MAC

Once you have assembled DYNAMIC, you can build it with
Task Builder command sequence:

the

following

TKB>DYNAMIC,DYNAMIC/-WI/-SP=DYNAMIC
TKB>/
ENTER OPTIONS:
TKB>WNDWS=l
TKB>//
This command sequence directs the Task Builder to create a task image
named DYNAMIC.TSK and an 80 column (/-WI) map file named DYNAMIC.MAP
on device SY:
under the terminal UIC.
Because /-SP is attached to
the map file,
the Task Builder will not output the file to the line
printer.
Under options, the WNDWS option directs the Task Builder to create one
window block over and above that required to map the task region.
Note that one window block must be created for each region the task
expects to be mapped to simultaneously.
The map that results from this command sequence
3-33.

shown

Figure

Note that creating dynamic regions always involves the assumption that
there will be enough room in the partition named in the task's region
descriptor block to create the region when the task is run.
In this
example, if DYNAMIC were to be run in a system whose partition GEN was
not large enough to accommodate the region it creates,
the CREATE
REGION directive would fail.

3-52

TYPICAL TASK BUILDER FACILITIES
DYNAMIC.TSK;l

MEMORY ALLOCATION MAP
6-JAN-79 14:13

TKB M35

PAGE 1

PARTITION NAME
GEN
IDENTIFICATION
VOl
TASK UIC
[301,356]
STACK
LIMITS: 000212 001211 001000 00512.
PRG XFR ADDRESS: 001406
TOTAL ADDRESS WINDOWS: 2.
TASK IMAGE SIZE
480. WORDS
TASK ADDRESS LIMITS: 000000 001673
R-W DISK BLK LIMITS: 000002 000003 000002 00002.

TASK
ATTRIBUTES
SECTION

*** ROOT SEGMENT: DYNAMI
R/W MEM LIMITS: 000000 001673 001674 00956.
DISK BLK LIMITS: 000002 000003 000002 00002.
MEMORY ALLOCATION SYNOPSIS:
SEC'TION

TITLE

• BLK.: (RW,I,LCL,REL,CON) 001212
001212
$DPB$$:(RW,I,LCL,REL,CON) 001642
001642

000430
000430
000030
000030

!DENT

00280.
00280. DYNAMI VOl
00024.
00024. DYNAMI VOl

FILE
DYNAMIC.OBJ;!
DYNAMIC.OBJ;!

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 518.
WORK FILE READS: O.
WORK FILE WRITES: 0.
SIZE OF CORE POOL: 2076. WORDS (8. PAGES)
SIZE OF WORK FILE: 768. WORDS (3. PAGES)
ELAPSED TIME:00:00:03
Figure 3-33

3.4

Task Builder Map for DYNAMIC.TSK

VIRTUAL PROGRAM SECTIONS

A virtual program section is a special Task Builder storage allocation
facility that permits you to create and refer to large data structures
by means of the mapping directives.
Virtual program sections are
supported in the Task Builder through the VSECT option and in FORTRAN
through a set of FORTRAN-callable subroutines that issue the necessary
mapping directives at runtime. With the Task Builder VSECT option you
can specify the following parameters for a relocatable program section
or FORTRAN common block that you have defined in your object module:
•

Base virtual address

•

Virtual length (window size)

•

Physical length
3-53

TYPICAL TASK BUILDER FACILITIES
By specifying the base address, you can align the program section on a
4K
address
boundary
as
required by the mapping directives.
Thereafter, references within the program need only point to the base
of the program section or to the first element in the common block, to
ensure proper boundary alignment.
By specifying the window size, you can fix
the amount of virtual
address space that the Task Builder allocates to the program section.
If the allocation made by a module causes the total size to exceed
this limit,
the allocation wraps around to the beginning of the
window.
By specifying the physical size, you can allocate, before runtime, the
physical memory that the program section will be mapped into at
runtime.
The Task Builder allocates this physical memory within an
area that precedes the task image. This area is called the mapped
array area.
The physical length parameter is optional.
If you intend to allocate
physical memory at
runtime through the Create Region directive, you
can specify a value of O.
Note that when you specify a nonzero value for
the physical memory
parameter,
the resulting allocation affects only the task's memory
image, not its disk image.
Note also that the Task Builder will attach the virtual attribute to a
relocatable program section you have specified in the VSECT option
only if the section is defined in your task through the common
statement.
For example:
TKB>VSECT=VIRT:l60000:20000:2000
In this example, virtual program section VIRT is allocated with a
window size of 4K words and a base virtual address of 160000.
In
physical memory, 32K words are reserved for mapping the section at
runtime.
Assume the program is written in FORTRAN, and includes
statement:

the

following

COMMON /VIRT/ARRAY(4) •••
This statement generates a program section to which the Task Builder
attaches the virtual attribute.
A reference to the first element of
the section, ARRAY(l), is translated by the Task Build~r to the
virtual address 160000.
Figure 3-34 shows the effect of this use of the VSECT option.

3-54

TYPICAL TASK BUILDER FACILITIES

WINDOW
160000 APR 7 -APR 6--

APR 5-APR 4--

TASK
IMAGE

APR 3--

APR 2--

(PROGRAM
0 SECTION
DEFINITION)

APR 1--

APR 0--

COMMON/VI RT/...

COMMON/VI RT/ ...

HEADER & STACK

VIRTUAL ADDRESS
SPACE

TKB >I
ENTER OPTIONS:
TKB >VSECT = VIRT:160000:20000:2000

PHYSICAL LENGTH
64-BYTE BLOCKS

MAPPED
ARRAY
AREA

• o e o

PHYSICAL MEMORY

Figure 3-34

VSECT Option Usage

3-55

TYPICAL TASK BUILDER FACILITIES
As mentioned previously, the Task Builder restricts the amount of
virtual address space allocated to the section to a value that is less
than or equal to the window size, wrapping around to the base
if the
window size is exceeded.
This process is illustrated in the following example, in which three
modules, A,
B, and C, each contain a program section named VIRT that
is 3000 words long.
A window size of 4K words has been set through
the VSECT option.
If the program section has the concatenate
attribute, the Task Builder allocates memory to each module as
follows:
Module

Low Limit

Length

High Limit

A
B

160000
1 74000
170000

14000
14000
14000

174000
170000
164000

The address limits for modules B and c illustrate the effect of
address wrap around when a component of the total allocation exceeds
the window boundary.
Note that the addresses generated will be
properly aligned with the contents of physical memory if the virtual
section is remapped in increments of the window size.

3.4.1

FORTRAN Run-Time Support for Virtual Program Sections

FORTRAN supports subroutines to make use of the mapping directives.
FORTRAN also supports calls to the following subroutines, which are
related to virtual program sections:
Function

Subroutine
ALSCT

Allocates a portion of physical memory
virtual section

for

use

RLSCT

Releases all physical memory
section

virtual

allocated

As mentioned earlier, the effect of one or more VSECT= declarations at
task-build time is to create a pool of physical memory below the task
image (the mapped array area).
Before a virtual section is referred
to,
the task must allocate a portion of this memory through a call to
ALSCT. When space is no longer required, it is released through a
call to RLSCT.
Note that these subroutines issue no mapping directives.
They
allocate and
release space using region and window descriptor arrays
that you supply. The resulting physical offsets are used
in the
task's subsequent calls, that perform the actual mapping.
The subroutine ALSCT is called to
virtual program section as follows:
CALL ALSCT (ireg,iwnd[,ists])

3-56

allocate

physical

memory

TYPICAL TASK BUILDER FACILITIES
ireg
A one-dimensional integer array that is 9 words long.
Elements 1
through 8 of the array contain a
region descriptor for the
physical memory to be mapped. The descriptor has the following
format:
ireg(l)

Region ID

ireg(2)

Size of region in units of 64-byte blocks

ireg(3)

Name of region
characters)

ireg(4)

(Second three characters)

ireg(S)

Name of main partition containing region

ireg(6)

The name is in Radix-50 format

ireg(7)

Region status word

ireg(8)

Region protection code

ireg(9)

Thread word:
this element links window descriptors
that are used to map portions of the region.
It is
maintained by the subroutine.

Radix-50

format

(first

three

The elements of the array that you set up consist of ireg(l), and
ireg(3)
through ireg(8). The thread word, ireg(9), must be zero
on the initial call;
thereafter, the subroutine maintains it.
When your task makes an allocation, ireg(l) and ireg(2) must be 0
on the initial call.
In this case, ALSCT obtains and stores the
region size in ireg(2). When the a~location is being made from a
separate region, the caller must supply both region ID and size.
Elements 3 through 8 are not referred to by the subroutine but
must be set up by the caller as required by the applicable system
directives.
For a detailed description of these parameters,
refer to the RSX-llM/M-PLUS Executive Reference Manual.
iwnd
A one-dimensional array that is 11 words long. The first 8 words
contain a window descriptor in the following format:
iwnd(l)

Base APR in bits 8 through 15;
the Executive Sets bits
0 through 7 when the appropriate mapping directives are
issued

iwnd(2)

Virtual base address

iwnd(3)

Window size in units of 64-byte blocks

iwnd(4)

Region ID

iwnd(S)

Offset into the region, in units of 64-byte blocks

iwnd(6)

Length to map, in units of 64-byte blocks

iwnd(7)

Status word

iwnd(8)

Address of send/receive buffer

3-57

TYPICAL TASK BUILDER FACILITIES
iwnd(9)

Base off set of physical block allocated to
units of 64-byte blocks

iwnd(lO)

Length of block in units of 64-byte blocks (supplied by
caller); set to maximum block offset by subroutine

iwnd(ll)

Thread word: this element links window descriptors
that are used to map other portions of the region. It
is maintained by the subroutine

The following array elements are
subroutine:

supplied

section

output

from

the

iwnd(4), iwnd(S), iwnd(9), iwnd(lO), and iwnd(ll)
The remaining elements must be set up as- required by the
Executive
directives.
Consult the RSX-llM/M-PLUS Executive
Reference Manual for a detailed description of these parameters.
ists
receives the result of the call.
returned:

One of the following values

Block successfully allocated. In this case, the region
and window descriptor arrays are set up as described
above.

-200.

Insufficient physical memory was available for allocating
the block

The subroutine RLSCT is called to deallocate
assigned to a virtual section as follows:

the

physical

memory

CALL RLSCT (ireg,iwnd)
ireg
The
A one-dimensional integer array that is 9 words long.
contents of the array are the same as those described for
subroutine ALSCT.
iwnd
The
A one-dimensional integer array that is 11 words long.
contents of the array are the same as those described for
subroutine ALSCT.
Upon return, element iwnd(lO) is the length
region in units of 64-byte blocks.
The procedure
follows:

for

using

these

subroutines

can

the
be

deallocated

summarized

•

You allocate storage in the program for one window
per VSECT, and for a single region descriptor.

descriptor

•

Your task calls the subroutine ALSCT to reserve
memory to which the program section will be mapped.

physical

3-58

TYPICAL TASK BUILDER FACILITIES

3.4.2

•

Your task issues the mapping directives to map the virtual
address space into a portion of the physical memory.
It is
the task's responsibility to ensure that the physical memory
to be mapped is always within the limits defined by iwnd(9)
and iwnd(lO).

•

When the space is no longer required, the task unmaps
releases it with a call to RLSCT.

and

Example 7: Building a Program that Uses a Virtual Program Section

Figure 3-35 shows the FORTRAN source file for a task named VSECT.FTN.
It illustrates the use of the ALSCT FORTRAN subroutine. When you
buUd, in.stall, and run VSECT, it will allocate the mapped array area
below its header, create a 4K-word window, and map to the area through
the window. ALSCT will then initialize the area and prompt for an
~rray subscript at your terminal by printing:
SUBSCRIPT?
When you input a subscript, it will respond with ELEMENT= and the
contents of the array element for the subscript you typed. VSECT will
continue to prompt until you type CTRL/Z.
Upon receiving a CTRL/Z
vsgcT will exit.
Once you have compiled VSECT, you can build it with the following Task
Builder command sequence:
TKB>VSECT,VSECT/-SP=VSECT,LB:[l,l]FOROTS/LB
TKB>/
ENTER OPTIONS:
TKB>WNDWS=l
TKB>VSECT=VIRt:l60000:20000:200
TKB>//
This command sequence directs the Task Builder to create a task image
file named VSECT.TSK and a short (by default) map file VSECT.MAP.
Because /-SP is appended to the map file, the Task Builder will not
output the map to the line printer.
The library switch (/LB) specifies that the Task Builder is to search
the FORTRAN run time library FOROTS.OLB to resolve any undefined
references in the input module VSECT.OBJ. Because the library switch
was applied to the FORTRAN library file without arguments, the Task
Builder extracts from the library and includes in the task image, any
modules in which references are defined.
Under options, the WNDWS option directs the Task Builder to add a
window block to the header in the task image. This window block will
be initialized by the Executive when it processes the mapping
directives within the task.
Th49 VSECT option directs the Task Builder to establish for the program
section named VIRT a base address of 160000 (APR 7) and a length of
20000(8) bytes (4K words). The program section VIRT is defined within
th49 task through the FORTRAN COMMON statement. The VSECT option also
specifies that the Task Builder is to allocate 200 64-byte blocks of
physical memory in the task's mapped array area below the task's
header.
(For more information on the switches and options used in
this example, refer to Chapter 6)
The map that results from this command sequence
3-36.
3-59

shown

Figure

TYPICAL TASK BUILDER FACILITIES

c
C

VSECT.FTN

c
C

INTEGER *2 SUB,IRDB{9),IWDB{ll),DSW
INTEGER *2 IARRAY(4096)
COMMON /VIRT/IARRAY
IWDB {1)
"3400
! USE APR 7 FOR WINDOW
IWDB (3)
128
!WINDOW SIZE = 128*32 WORDS
IWDB (5) = 0
!OFFSET
IWDB (7) = "402
!STATUS = WS.64B!WS.WRT
ALLOCATE 4K MAPPED ARRAY TO IWDB,IRDB
CALL ALSCT (IRDB,IWDB,DSW)
IF (DSW .NE. 1) GOTO 100

c
C

CREATE A 4K ADDRESS WINDOW
CALL CRAW {IWDB,DSW)
IF (DSW .NE. 1) GOTO 200
MAP 4K MAPPED ARRAY

CALL MAP {IWDB,DSW)
IF (DSW .NE. 1) GOTO 300
DO 1 I=l,4096
!ARRAY (I) = I

MAPPED ARRAY IS INITIALIZED, PROMPT FOR A SUBSCRIPT

c
c
3
5
4
6

WRITE {5,5)
FORMAT ('$SUBSCRIPT?')
READ {5,4,END=lOOO)SUB
FORMAT (!7)
WRITE {5,6)IARRAY (SUB)
FORMAT ( ' ELEMENT= ',I7)
GOTO 3

c
c

ERROR ROUTINES

100
101

WRITE {5,lOl)DSW
FORMAT {' ERROR FROM ALSCT. ERROR= ',I7)
GOTO 1000
WRITE {5,20l)DSW
FORMAT {' ERROR FROM CREATING ADDRESS WINDOW. ERRROR
GOTO 1000
WRITE (5,30l)DSW
I , I 7)
FORMAT {' ERROR FROM MAPPING. ERROR
CALL EXIT
END

200
201
300
301
1000

Figure 3-35

Source Listing for VSECT.FTN

3-60

I 7)

TYPICAL TASK BUILDER FACILITIES
VSECT.TSK;l

MEMORY ALLOCATION MAP TKB M35
8-JAN-79
11:41

PAGE 1

PARTITION NAME : GEN
IDENTIFICATION : $FORT
TASK UIC
[301,356]
STACK
LIMITS: 000216 001215 001000 00512.
PRG XFR ADDRESS: 001216
TOTAL ADDRESS WINDOWS: 2.
MAPPED ARRAY AREA: 4096. WORDS
TASK IMAGg SIZE
9440. WORDS
TOTAL TASK SIZE
13536. WORDS
TASK ADDRESS LIMITS: 000000 044653
R-W DISK BLK LIMITS: 000002 000046 000045 00037.

TASK
ATTRIBUTES
SECTION

*** ROOT SEGMENT: VSECT
R/W MEM LIMITS: 000000 044653 044654 18860.
DISK BLK LIMITS: 000002 000046 000045 00037.
MEMORY ALLOCATION SYNOPSIS:
SECTION

TITLE

!DENT

• BLK.: (RW,I,LCL,REL,CON) 001216 000000 00000.
001216 001020 00528 • • MAIN. $FORT

VIRT

: (RW,D,GBL,REL,OVR) 001216 020000 08192.
001216 020000 08192 • • MAIN. $FORT

FILE
VSECT.OBJ;l

VSECT.OBJ;l

GLOBAL SYMBOLS:
003506-R

FOO$

003532-R

MOL$IS 002736-R

TVQ$

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 16257.
WORK FILE READS: O.
WORK FILE WRITES: O.
SIZE OF CORE POOL: 4188. WORDS (16. PAGES)
SIZE OF WORK FILE: 3584. WORDS (14. PAGES)
ELAPSED TIME:00:00:32
Figure 3-36

Task Builder Map for VSECT.TSK

3-61

003144-R

TYPICAL TASK BUILDER FACILITIES
3.5

EXAMPLE 8: PRIVILEGED TASKS

There are two classes of tasks in the RSX-llM/M-PLUS systems:
privileged and nonprivileged.
The majority of tasks running on any
one system are nonprivileged.
The distinction between privileged and nonprivileged
tasks
is
primarily a distinction of system access capabilities.
Because, in an
unmapped system, all tasks have access to all of memory,
this
distinction is not hardware enforceable. Therefore, if your system is
unmapped your task must be responsible for observing the access rules
of your system.
In a mapped system, privileged tasks have special device and memory
access rights that nonprivileged tasks do not have. A privileged task
can, with certain exceptions, access the Executive routines and data
structures;
a nonprivileged task cannot. Some privileged tasks have
automatic I/P page mapping available to them;
nonprivileged tasks do
not.
Finally, a privileged task can bypass system security features
while a nonprivileged task cannot.
Because of their special access rights,
privileged
tasks
are
potentially hazardous to a running system. A privileged task with
coding errors can corrupt the Executive or unintentionally disable
peripheral devices.
Moreover,
problems caused by such a privileged
task can be obscure and difficult to isolate. For these reasons,
you
must exercise caution when developing and running a privileged task.
You designate a task as privileged with the PR
{privileged)
Task
Builder switch
{this switch is described in Chapter 6). The Task
Builder allocates address space for a privileged task based on the
memory management APR that you specify as an argument to this switch.
Three arguments are acceptable to the Task Builder:
O, 4, and 5. The
choice of which of these arguments to specify is based on the
considerations described below.
When you ?pecify 4 or 5, the Task Builder automatically reserves APR 7
for mapping the I/O page.
Moreover,
the Task Builder makes the
Executive available to your task by reserving the APRs necessary to
map the Executive into your task's virtual address space. Therefore,
if your task requires access to the Executive, you must specify an
argument of either 4 or 5.
The choice between APR 4 and 5 is dictated by the size of the
Executive area.
If the Executive is 16K words or less, you should
specify an argument of 4. The Task Builder applies a bias of 100000
{16K) to all addresses within your task.
If the Executive is 20K words, you must specify an argument of 5. The
Task Builder applies a bias of 120000 {20K) to all addresses within
your task.
The mapping for APR 4 and 5 is shown in Figure 3-37.
When you specify an ar~ument of 4, there will be 12K words of address
space between the beginning of the task and the start of the mapping
for the I/O page.
If your task expects to access the I/O page,
it
must not exceed this 12K word limit.
If it does, the Task Builder
will be forced to reserve APR 7 to map the task instead of the I/O
page.
When you specify an argument of 5, there will be 8K words of address
space between the beginning of the task and the start of the mapping
for the I/O page.
In this case, the task must not be greater than 8K
words if it expects to access the I/O page.
3-62

TYPICAL TASK BUILDER FACILITIES

1/0 PAGE

1/0 PAGE
APR 7APR6-

VIRTUAL 120000 -

APR 5 -

VIRTUAL 100000 -

APR 4 APR3-

APR 3 APR 2 -

APR 7 -

AVAILABLE
TASK SPACE

APR6-

AVAJABLE
TASK SPACE

APR 5 APR4-

VIRTUAL 160000 -

RESERVED FOR
EXECUTIVE
MAPPING

APR 2-

APR 1 -

•

RESERVED FOR
EXECUTIVE
MAPPING

APR 1 -VIRTUALO-

APRO-

APR 0 -

/PR:4

Figure 3-37

/PR:5

Mapping for /PR:4 and /PR:S

When a task overlaps the I/O page,
the Task Builder does not
necessarily generate an error message.
Before the Task Builder
generates an error message, a task designated to be mapped with APR 4
must be greater than 16K words;
a task designated to be mapped with
APR 5 must be greater than 12K words. Only when you install a task
that overlaps the I/O page does the INSTALL processor generate the
following message:
INS---WARNING--PRIVILEGED TASK OVERMAPS THE I/O PAGE
While this is not a fatal error message,
you should consider the
condition to be fatal if your task expects to access the I/O page.
When you specify an argument of O, the Task Builder reserves APR O for
mapping your task.
Virtual address space begins at virtual address 0
and extends upward as far as 32K words. Your task cannot access the
ExE~cutive
routines or data structures, and the Task Builder does not
automatically reserve an APR to map the I/O page.
A task mapped with APR O can access the I/O page through a device
common (refer to Chapter 3 for a description of device commons).
The MACR0-11 source program PRIVEX.MAC in Figure 3-38 illustrates
possible use of a privileged task.
NOTE
The nature of privileged tasks is such
that you must have a working knowledge
of system concepts to understand the
operation of one or to write one.
If
this example
deals
with
Executive
functions that are unfamiliar to you,
you may prefer to skip this section and
return to it at a later time.

3-63

one

TYPICAL TASK BUILDER FACILITIES
If you assemble, build, and install PRIVEX into your system,
it will
scan the system device tables and examine the UCBs of all non-pseudo
devices on your system.
It will determine whether each device is
attached by a . task and print on your terminal the names of all
attached devices on your system with the name of each attached
program.
PRIVEX accesses two Executive routines,
$SWSTK
(switch stack)
and
$SCDVT
(scan device tables).
The routine $SWSTK switches the
processor to system state (Kernel mode).
This switch to system state
is necessary because
it inhibits all other processes from modifying
the Executive data structures until PRIVEX is finished with them.
The
double semicolons
(;;)
indicate the portion of the task that is
running in system state.
The routine $SCDVT performs the actual scanning of the device
It returns to PRIVEX each time it accesses a new UCB.

tables.

PRIVEX also calls the system library routine $EDMSG (edit message)
to
format the data it has retrieved from the device tables. This routine
is documented in the IAS/RSX-11 System Library Routines Reference
Manual.
MACRO

LIBRARY CALLS
.TITLE PRIVEX
.!DENT /01/
.MCALL

ALUN$C,EXIT$S,QIOW$S

LOCAL DATA

ATTMES:
BUFMES:

QIOBUF:

.NLIST

BEX

.ASCIZ
.ASCIZ

/%2A%P: IS ATTACHED BY %2R/
/BUFFER OVERFLOW/

.LIST

BEX

.BLKB

132.

;MESSAGE OUTPUT BUFFER

.EVEN
BUFFER INTO WHICH INFORMATION IS STORED AT SYSTEM STATE FOR
PRINTING AT USER STATE. AN ENTRY IS FOUR WORDS LONG:
ADDRESS IN DCB OF THE TWO ASCII CHARACTER DEVICE NAME
BINARY UNIT NUMBER
FIRST RADSO WORD OF NAME OF ATTACHED TASK
SECOND RADSO WORD OF NAME OF ATTACHED TASK

Figure 3-38

Source Code for PRIVEX

3-64

TYPICAL TASK BUILDER FACILITIES

THE BUFFER IS TERMINATED BY A
0
-1

ALL UNITS IN THE SYSTEM HAVE BEEN EXAMINED
THE BUFFER WAS FILLED BEFORE ALL UNITS COULD BE EXAMINED

BUFFER: .BLKW
BUFEND=.-2

4*200.+l

START:

#BUFFER,R2
(R2)
Rl

;

;ADDRESS OF LAST WORD OF BUFFER

MOV
CLR
CLR

;GET ADDRESS OF INFORMATION BUFFER
;ASSUME NO UNITS ARE ATTACHED
;INITIALIZE CURRENT DCB ADDRESS

"CALL $SWSTK,FORMAT" SWITCHES TO SYSTEM STATE. ALL REGISTERS
ARE PRESERVED ACROSS THE TRANSITION FROM USER MODE TO KERNEL
MODE.
BEING IN SYSTEM STATE LOCKS OTHER PROCESSES OUT OF THE
EXECUTIVE (GUARANTEES THAT THE DATA BEING EXAMINED WILL NOT
CHANGE WHILE IT IS BEING EXAMINED). A "RETURN" WILL GIVE
CONTROL TO "FORMAT" AND WILL RESTORE THE CONTENTS OF THE
REGISTERS TO THEIR VALUES BEFORE THE "CALL $SWSTK".

20$:

.~T

40$:

60$:
80$:
100~?:

CALL
MOV

$SWSTK,FORMAT
#$SCDVT,-(SP)

CALL

@(?P)+

BCS

100$

THIS
R3
R4
RS

;SWITCH TO SYSTEM STATE
;;GET ADDRESS OF SCAN DEVICE TABLES
; ; COROUTINE
;;GET NEXT NONPSEUDO DEVICE UCB
ADDRESS
I I
;;IF CS NO MORE UCBS

POINT:
- ADDRESS OF THE DEVICE CONTROL BLOCK
- ADDRESS OF THE STATUS CONTROL BLOCK
- ADDRESS OF THE UNIT CONTROL BLOCK
Rl,R3
40$
R3,Rl
RO
D.UNIT(R3),RO
U.ATT(R5),R4
60$

CMP
BLOS
ADD
MOV
MOV
MOV
MOV
CLR
INC
BR
CALL
BCC
COM
RETURN

;;IS THIS A NEW DCB?
;;IF EQ NO
;;REMEMBER THIS DCB
;;FORM LOWEST UNIT NUMBER ON
;; THIS DCB
;;IS A TASK ATTACHED?
;;IF EQ NO
;;IF NE R4 IS TCB ADDRESS
#BUFEND,R2
;;ANY MORE ROOM IN BUFFER?
80$
;;IF LOS NO
#D.NAM,R3
;;FORM ADDRESS OF DEVICE NAME
R3,(R2)+
;;SAVE IT IN BUFFER
RO,(R2)+
;;SAVE UNIT NUMBER
T.NAM(R4),(R2)+ ;;SAVE NAME .OF ATTACHED TASK
T.NAM+2(R4), (R2)+ ;;
(R2)
;;ASSUME NO MORE ATTACHED UNITS
RO
;;INCREMENT UNIT NUMBER
20$
;;
@(SP)+
;;GET $SCDVT TO CLEAN OFF STACK
80$
;;
(R2)
;;SHOW BUFFER OVERFLOW
;;RETURN TO USER STATE AT FORMAT

.ENABL

LSB

CMP
BEQ
MOV
CLR
BISB
MOV
BEQ

Figure 3-38 (Cont.)

Source Code for PRIVEX

3-65

TYPICAL TASK BUILDER FACILITIES
FORMAT: TST
BEQ
CMP
BNE
MOV
CALL
EXIT:
EXIT$S
40$:
MOV
CALL
BR
.DSABL

(R2)
EXIT
#-l,(R2)
40$
#BUFMES,Rl
PRINT

;ANY MORE INFORMATION IN BUFFER?
;IF EQ NO
;OVERFLOWED BUFFER?
;IF NE NO
;GET ADDRESS OF OVERFLOW MESSAGE
; PRINT IT
;

#ATTMES,Rl
PRINT
FORMAT

;GET ADDRESS OF TEMPLATE
;FORMAT AND PRINT THE INFORMATION

LSB

PRINT - FORMAT AND PRINT A MESSAGE
INPUTS:
Rl - ADDRESS OF AN $EDMSG INPUT STRING
R2 - ADDRESS OF AN $EDMSG PARAMETER BLOCK
OUTPUTS:
R2 - ADDRESS OF NEXT PARAMETER IN THE $EDMSG PARAMETER BLOCK
RO, Rl, R3, R4 ARE DESTROYED
RS IS PRESERVED
PRINT:

#QIOBUF ,RO
RO,R3
$EDMSG

MOV
MOV
CALL

;GET ADDRESS OF OUTPUT BUFFER
;SAVE FOR QIOW$S
;FORMAT MESSAGE INTO OUTPUT BUFFER

REMOVE LEADING ZEROS FROM UNIT NUMBER

20$:

MOV
TST

R3,RO
(RO)+

MOV
DEC

RO,R4
Rl

CMPB
BEQ

#'0, (RO)+
20$
Rl
# I : ' - (RO)

INC

CMPB

40$:

BNE
MOVB
INC
MOVB
BNE

40$

#I 0' ( R4) +
Rl
(RO)+, ( R4) +
40$

;POINT AT OUTPUT BUFFER
;INCREMENT BY TWO (POINT PAST
;
DEVICE NAME)
;REMEMBER THIS SPOT
;ASSUME NEXT BYTE IS A LEADING ZERO
;
(REDUCE LENGTH OF MESSAGE)
;IS IT?
;IF EQ YES -- IGNORE IT
;COUNTERACT TOO MUCH DECREMENTING
;WAS THE BYTE A COLON (WAS THE UNIT
; NUMBER ZERO)?
;IF NE NO
;ADD A ZERO UNIT NUMBER
;INCREASE LENGTH OF MESSAGE
;TACK ON REST OF MESSAGE
;IF NE NOT DONE

PRINT THE MESSAGE ON LUN "OUTLUN'~
AND WAIT USING EVENT FLAG 1

(DEFINED BY THE TASK BUILD FILE)

QIOW$S
RETURN

#IO.WVB,#OUTLUN,#l,,,,<R3,Rl,<#'

.END

START
Figure 3-38 (Cont.)

Source Code for PRIVEX

3-66

TYPICAL TASK BUILDER FACILITIES
PRIVEX.MAC should be assembled with the
string:

following

assembler

command

MAC>PRIVEX,PRIVEXl-SP=[l,l]EXEMCIML,[200,200]RSXMCIPA:l,[301,311]PRIVEX
The file EXEMC is the Executive macro library and the file RSXMC
is
the Executive prefix file.
The switches used in the command string
are described
in the IASIRSX-11 MACR0-11 Programmer's Reference
Manual.
The Task Builder command sequence for PRIVEX is as follows:
>TKB
TKB> PRIVEXIPR:S,PRIVEXl-SP=PRIVEX
TKB> [2,54]RSX11M.STB,[l,l]EXELIBILB
TKB> I
ENTER OPTIONS:
TKB> UNITS=l
;DEFINE NUMBER OF LUNS
TKB> GBLDEF=OUTLUN:l
;DEFINE LUN ON WHICH TO PRINT MESSAGES
TKB> ASG=TIO:l
;ASSIGN LUN TO DEVICE
TKB> II

>
This command sequence directs the Task Builder to build PRIVEX as a
privileged task and to add a bias of 120000 to all locations within
it.
APR 5 was chosen in this example because the Executive in the
system on which this exam~le was originally built is 20K words long.
If the Executive in your system is 16K words or less,
you can use
IPR:4 when you build the task.
In the options section of the Task Builder command sequence,
the
UNITS=l option specifies that PRIVEX is going to use only one logical
unit.
The GBLDEF=OUTLUN:l option defines the symbol OUTLUN as being
equal to 1, and the ASG=TIO:l option associates device TIO:
with
logiqal unit 1.
The Task Builder map for PRIVEX is shown in Figure 3-39.
The GLOBAL
SYMBOL SECTION has been shortened to save space. Note that the task's
address limits begin at virtual address 120000. The diagram in Figure
3-40 illustrates how the Task Builder allocates virtual address space
for the program.

3-67

TYPICAL TASK BUILDER FACILITIES
PRIVEX.TSK;2

PAGE 1

MEMORY ALLOCATION MAP TKB M32
7-0CT-78
16:10

PARTITION NAME : GEN
IDENTIFICATION :
01
TASK UIC
[301,311]
STACK
LIMITS:
120146 121145 OOlOQO 00512.
PRG XFR ADDRESS:
124526
TASK ATTRIBUTES:
PR
TOTAL ADDRESS WINDOWS:
1.
TASK
IMAGE SIZE
1856. WORDS
TASK ADDRESS LIMITS:
120000 127147
R-W DISK BLK LIMITS:
000002 000011 000010 00008.

Task
Attributes
Section

*** ROOT SEGMENT:PRIVEX
R/W MEM LIMITS:
120000 127147 007150 03688.
DISK BLK LIMITS: 000002 000011 000010 00008.
MEMORY ALLOCATION SYNOPSIS:
SECTION

TITLE

• BLK.: (RW,I,LCL,REL,CON) 121146
121146
LNC$D : (RW,D,GBL,REL,CON) 127022
$$RESL: (RW,I,LCL,REL,CON) 127024
$$RESM: (RW,I,LCL,REL,CON) 127050

!DENT

FILE

005654
003656
000002
000024
000100

02988.
01966.
00002.
00020.
00064.

D.RS80
KINDR7
D.. RS81
KISARO

177660
17 2316
177657
172360

D.VKRB 000010

.DB3

020630

.MMl

PRIVEX.OBJ;2

PRIVEX 01

GLOBAL SYMBOLS:
AS.DEL
G.STAT
AS.EXT
HI$DIC

000010
000003
000004
000115

CI.PWF 177776
I.O.CLN ·003400
DV.ISP 002000
10.DET 002000

$rrT56
.TT22

033102
025634

$VTDCB 033406
.TT43 027314

D.VOUT 000004

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES:
185418.
WORK FILE READS: O.
WORK FILE WRITES: O.
SIZE OF CORE POOL:
9454. WORDS (36.
SIZE OF WORK FILE:
8448. WORDS (33.

PAGES)
PAGES)

ELAPSED TIME:00:00:30
Figure 3-39

Task Builder Map for PRIVEX

3-68

021620

TYPICAL TASK BUILDER FACILITIES

1/0 PAGE
APR 7-

........,.,.,.,.................,......................._VIRTUAL 160000

APR 6-

~~~~~~:

PRIVEX. TSK
APR 5-

VIRTUAL 127147 f
'TASK ADDRESS LIMITS
VIRTUAL 120000 J

APR 4-

APR 3EXECUTIVE
APR 2- -

APR 1- -

APRO

Figure 3-40

VIRTUALO

Allocation of Virtual Address Space for PRIVEX

3-69

CHAPTER 4
OVERLAY CAPABILITY

The Task Builder provides you with the means to reduce the memory
and/or virtual address space requirements of your task by using
tree--like overlay structures created with the Overlay Description
Language (ODL). You can specify two kinds of overlay segments:
those
that reside on disk and those that reside permanently in memory.

4.1

OVERLAY STRUCTURES

To create an overlay structure, you divide a task
segments consisting of:

into

series

•

A single root segment, which is always in memory and,

•

Any number of overlay segments, which either 1) reside on disk
and share virtual address space and physical memory with one
another (disk-resident overlays); or 2) reside in memory and
share
only
virtual
address
space
with
one another
(memory-resident overlays)!

Segmetnts consist of one or more object modules which in turn consist
of one or more program sections. Segments that overlay each other
must be logically independent;
that is, the components of one segment
cannot reference the components of a segment with which it shares
virtual address space.
In addition to the logical independence of the
overlay segments, the general flow of control within the task must be
considered when creating overlay segments.
You must also consider the kind of overlay segment to create at a
given position in the structure, and how to construct it. Dividing a
task into disk-resident overlays saves physical space, but introduces
the overhead activity of loading these segments each time they are
needed, but not present in memory. Memory-resident overlays, on the
other hand, are loaded from disk only the first time they are
referenced. Thereafter, they remain in memory and are referenced by
remapping.
Several large classes of tasks can be handled effectively by an
overlay structure.
For example, a
task that moves sequentially
through a set of modules is well suited to the use of an overlay
structure.
A task that selects one of a set of modules according to
the value of an item of input data is also well suited to the use of
an overlay structure.
1 Note that memory-resident overlays can be used only if the
hardware
has a memory management unit, and if support for the memory management
directives has been included in the system on which the task is to
run.

4-1

OVERLAY CAPABILITY
Disk-Resident Overlay Structures

4.1.1

Disk-resident overlays conserve virtual address space and physical
memory by sharing them with other overlays.
Segments that are
logically independent need not be present in memory at the same time.
They,
therefore,
can occupy a common physical area in memory (and,
therefore, common virtual address space) whenever either needs to be
used.
The use of disk-resident overlays is shown in this section by an
example,
task TKl,
which consists of four input files.
Each input
file consists of a single module with the same name as the file.
The
task is built by the command:
>TKB TKl=CNTRL,A,B,C
In this example, the modules A, B, and C
that is:

are

logically

independent;

A doea not call B or C and does not use the data of B or

B does not call A or C and does not use the data of A or

C does not call A or B and does not use the data of A or B.
A disk-resident overlay structure can be defined in which A, B, and C
are overlay segments that occupy the same storage area in physical
memory.
The flow of control for the task will be as follows:
CNTRL calls A and A returns to CNTRL.
CNTRL calls B and B returns to CNTRL.
CNTRL calls

c and c returns to CNTRL.

CNTRL calls A and A returns to CNTRL.
In this example, the loading of overlays occurs only four times during
the execution of the task.
Therefore, the virtual address space and
physical memory requirements of the task can be reduced without unduly
increasing the overhead activity.
The effect of the use of an overlay structure on the allocation of
virtual address space and physical memory for task TKl is described in
the following paragraphs.
The lengths of the modules are:
Module

Length (in octal)

CNTRL
A
B

20000
30000
20000
14000

bytes
bytes
bytes
bytes

Figure 4-1 shows the virtual address space and physical memory
requirements as a result of building TKl as a single-segment task on a
system with memory management hardware.
The virtual address space and physical memory requirement to build TKl
as a single-segment task is 104000(8) bytes.
In contrast, Figure 4-2 shows the virtual address space and physical
memory required to build TKl as a result of using the overlay
capability and building it as a multisegment task.
4-2

OVERLAY CAPABILITY

160000

APR 7--

140000

APR 6-·

120000

APR 5-·

100000

APR 4-

60000

APR 3-

40000

APR 2-

20000

104000
BYTES
A

CNTRL
(ROOT SEGMENT)

HEADER AND STACK

APR 1-

APR 0-

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY

Figure 4-1

TKl Built as a Single-Segment Task

4-3

OVERLAY CAPABILITY

160000 APR 7-

140000 APR 6-

120000 APR 5-

100000 APR 4-

60000

APR 3-

40000

APR 2A

B
20000

APR 1-

APR 0-

CNTRL
(ROOT SEGMENT)

HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY

Figure 4-2

TKl Built as a Multisegment Task

4-4

50000
BYTE

OVERLAY CAPABILITY
The multisegment task requires 50000(8) bytes.
NOTE
In addition to module storage, storage
is required for overhead in handling the
overlay structures.
This overhead is
not reflected in this example.
In the use' of the overlay capability, the amount of virtual address
space and physical memory required for the task is determined by the
length of the root segment and the length of the longest overlay
segment.
Overlay segments A and B in this example are much longer
than overlay segment c. If A and B are divided into sets of logically
independent modules, task storage requirements can be further reduced.
Segment A can be divided into a control program (AO) and two overlays
(Al and A2). Segment A2 can then be divided into the main part (A2)
and two overlays (A21 and A22). Similarly, segment B can be divided
into a control module (BO) and two overlays (Bl and B2).
Figure 4-3 shows the virtual address space and physical memory
required for the task produced by the additional overlays defined for
A and B.
As a single-segment task, TKl requires 104000 bytes of virtual address
space and physical memory. The first overlay structure reduces the
requirement by 34000 bytes.
The second overlay structure further
reduces the requirement by 14000 bytes.
The vertical and horizontal lines in the diagrams of Figures 4-2 and
4-3 represent the st~te of virtual address space and physical memory
at various times during the calling sequence of TKl. For example,
in
Figure 4·-3 the leftmost vertical line in both diagrams shows virtual
address space and physical memory, respectively, when CNTRL, AO, and
Al are loaded. The next vertical line shows virtual address space and
physical memory when CNTRL, AO, A2, and A21 are loaded, and so on.
The horizontal lines in the diagrams of Figures 4-2 and 4-3 indicate
segments that share virtual address space and physical memory.
For
example, in Figure 4-3, the uppermost horizontal line of the task
region in both diagrams shows Al, A21, A22, Bl, 82, and c, all of
which can use the same virtual address space and physical memory. The
next horizontal line shows Al, A2, Bl, 82, and c, and so on.

4.1.2

Memory-Resident Overlay Structures (Not Supported on RSX-llS)

The Task Builder provides for the creation of overlay segments that
are loaded from disk only the first time they are referenced.
Theireafter, they reside in memory.
Memory-resident overlays share
virtual address space just as disk-resident overlays do but, unlike
disk-resident overlays, memory-resident overlays do not share physical
memory.
Instead,
they reside in separate areas of physical memory,
each segment aligned on a 32-word boundary. Memory-resident overlays
save time for a running task because they do not need to be copied
from a secondary storage device each time they are to overlay other
segments.
"Loading" a memory-resident overlay, reduces to mapping a
set of shared virtual addresses to the unique physical area of memory
containing the overlaying segment.

4-5

OVERLAY CAPABILITY

160000

APR 7-

140000

APR 6-

120000 APR 5-

100000

APR 4-

60000

APR 3-

40000

APR 2-

20000

AO _ _ _ _
BO__.___
APR 1- ..__ _

______

.........

CNTRL
(ROOT SEGMENT)

[A21l A22
A1J
A2
AO

B1~
B2
c
BO

CNTRL
(ROOT SEGMENT)

O APR O- _ _
H_EA_D_E_R_A_N_D_ST_A_C_K_ _ _ _ _ _ _ _

HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY

Figure 4-3

TKl Built with Additional Overlay Defined

4-6

34000

OVERLAY CAPABILITY
The use of memory-resident overlays is shown in this section by an
example,
task TK2, which consists of four input files.
Each input
file consists of a single module with the same name as the file.
The
task is built by the command:
>TKB TK2=CNTRL,D,E,F
In this example, the modules D, E, and F
that is:

are

logically

independent;

D does not call E or F and does not use the data of E or F.
E does not call D or F and does not use the data of D or F.

F does not call D or E and does not use the data of D or E.
A memory-resident overlay structure can be defined in which D, E,
and
F are overlay segments that occupy separate physical memory locations
but which occupy the same virtual address space. The flow of control
for the task will be as follows:
CNTRL calls D and D returns to CNTRL.
CNTRL calls E and E returns to CNTRL.
CNTRL calls F and F returns to CNTRL.
The effect of the use of a memory-resident overlay structure on the
allocation of virtual address space and physical memory for task TK2
is descr1bed in the following paragraphs.
The lengths of the modules are:
Module
CNTRL
D
E
F

Len~th

(in octal)

20000
10000
14000
12000

Figure 4-4 shows the virtual address space and physical memory
requirements as a result of building TK2 as a single-segment task on a
system with memory management hardware.
The virtual address space and physical memory requirements when TK2 is
built as a single-segment task is 56000(8) bytes.
If TK2 is built using the Task Builder's memory-resident overlay
capability,
the relationship of virtual address space to physical
memory changes, as shown in Figure 4-5.

4-7

OVERLAY CAPABILITY

160000 APR 7-

14000

APR 6-

120000 APR 5-

100000 APR 4-

60000

40000

20000

....,

APR 3-

APR 2-

ii
56000
BYTES

CNTRL
(ROOT SEGMENT)

APR 1-

APR 0-

---------- -- - - - - ....,
HEADER AND STACK

HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY

Figure 4-4

TK2 Built as a Single-Segment Task

4-8

OVERLAY CAPABILITY

160000 APR 7-

140000

APR 6-

120000

APR 5-

100000 APR 4-

60000

AP fl 3-

40000

APR 2-

E
56000
BYTES
D

20000

CNTRL
(ROOT SEGMENT)

APR 0-

APR 1-

34000(8)
BYTES

HEADER AND STACK

CNTRL
(ROOT SEGMENT)
HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY

Figure 4-5

TK2 Built as a Memory-Resident Overlay

4-9

OVERLAY CAPABILITY
The physical memory requirements for TK2 do not change(56000(8)
bytes},
but the virtual address space requirements have been reduced
to 34000(8) bytes. This represents a savings in virtual address space
of 22000(8) bytes.
NOTE
In addition to module storage, storage
is required for overhead in handling the
overlay structures.
This overhead is
not reflected in this example.
In Figure 4-5, the vertical and horizontal lines in the virtual
address space diagram represent the state of virtual address space at
various times during the calling sequence of TK2.
The leftmost
vertical line shows virtual address space when CNTRL and D are loaded
and mapped. The next vertical line shows virtual address space when
CNTRL and E are loaded and mapped, and the third vertical line shows
virtual address space when CNTRL and F are loaded and mapped.
The uppermost horizontal line of the task region shows

that

segments

Di E, and F share virtual address space.

When TK2 is activated, the Executive loads TK2's root segment into
physical memory. The Executive loads segments D, E, and F into memory
as they are called. Once all segments in the structure have been
called,
"loading" of the overlay segments reduces to the remapping of
virtual address space to the physical locations in memory where the
overlay segments permanently reside.
Figures 4-6 and 4-7 illustrate
the relationship between virtual address space and physical memory for
task TK2 during four time periods:
•

TIME 1 (Figure 4-6A) - TK2 is run and the system loads
root segment (CNTRL) into physical memory and maps to it.

the

2 (Figure 4-68) - CNTRL calls segment D.
The system
• TIME
loads segment D into physical memory and maps to it. Segment

D returns to CNTRL.
•

TIME 3 (Figure 4-7A) - CNTRL calls segment E.
The system
loads segment E into physical memory, unmaps from segment D,
and maps to segment E. Segment E returns to CNTRL.

•

TIME 4 (Figure 4-78) - CNTRL calls segment F.
The system
loads segment F into physical memory, unmaps from segment E,
and remaps to segment F. Segment F returns to CNTRL

4-10

OVERLAY CAPABILITY

Figure 4-6A Time 1

160000

APR 7-

140000

APR 6-

'120000

APR 5-

'100000

APR 4-

()0000

APR 3-

40000

APR 2-

....

CNTRL
(ROOT SEGMENT)

API~ 0-

CNTRL
(ROOT SEGMENT)
HEADER AND STACK

HEADER AND STACK
'-------------'
VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY

Figure 4-6 Relationship Between Virtual Address Space
and Physical Memory -- Time 1 and Time 2

4-11

OVERLAY CAPABILITY

Figure 4-68 Time 2

160000

APR 7-

140000

APR 6-

120000

100000

APR 4-

60000

APR 3-

40000

APR 2-

20000

APR 1-

- - - CNTRL
(ROOT SEGMENT)

APR 0-

HEADER AND STACK

...
...

- - - -

CNTRL
(ROOT SEGMENT)
HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY

Figure 4-6 (Cont.)
Relationship Between Virtual Address Space
and Physical Memory -- Time 1 and Time 2

4-12

OVERLAY CAPABILITY

Figure 4-7A Time 3

HiOOOO

APR 7-

140000

APR 6-

120000

APR 5-

100000

APR 4-

60000

APR 3-

40000

APR 2-

.
::---_
----

....

E
20000

APR 1- ~----------1-

... _- - - -

APR 0-

CNTRL
(ROOT SEGMENT)

HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY

Figure 4-7 Relationship Between Virtual Address Space
and Physical Memory -- Time 3 and Time 4

4-13

OVERLAY CAPABILITY

Figure 4-78 Time 4

160000

APR 7-

140000

APR 6-

120000

APR 5-

100000

APR 4-

60000

APR 3F

40000

APR 2-

20000

APR 1-

CNTRL
(ROOT SEGMENT)

APR 0-

HEADER AND STACK

-- --

CNTRL
(ROOT SEGMENT)
HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY

Figure 4-7 (Cont.)
Relationship Between Virtual Address Space
and Physical Memory ~- Time 3 and Time 4

4-14

OVERLAY CAPABILITY
It is important to be careful
in choosing
whether
to
have
memory-resident overlays in a structure.
Careless use of these
segments can result
in inefficient allocation of virtual address
space.
This is because the Task Builder allocates virtual address
space in blocks of 4K words.
Consequently, the length of each overlay
segment should approach that limit if you are to minimize waste.
(A
segment that is one word longer than 4K words, for example, will be
allocated SK words of virtual address space. All but one word of the
second 4K words will be unusable.)
You can also conserve physical memory by maintaining control over the
contents of each segment.
The inclusion of a module in several
memory-resident segments that overlay one another causes physical
memory to be reserved for
each extra copy of that module.
Common
modules,
including those from the system object module library
(SYSLIB),
should be placed in a segment that can be accessed from all
referencing segments.
The primary criterion for choosing to have memory-resident overlays is
the need to save virtual address space when disk-resident overlays are
either undesirable
(because they would slow
the
system
down
unacceptably),
or
impossible
(because the segments are part of a
resident library or other shared region that must permanently reside
in memory).
Memory-resident overlays can help you use large systems to better
advantage because of the time savings realized when a large amount of
physical memory is available.
Resident libraries, in particular,
can
benE~fit
from the virtual address space saved when they are divided
into memory-resident segments.

4.2

OVERLAY TREE

The arrangement of overlay segments within the virtual address space
of a
task can be represented schematically as a tree-like structure.
Each branch of the
tree represents a segment.
Parallel branches
denote segments that overlay one another and therefore have the same
virtual address;
these segments must be logically independent.
Branches ~onnected end to end represent segments that do not share
virtual address space with each other;
these segments need not be
logically independent.
The Task Builder provides an overlay description language
(ODL)
for
representing an overlay structure consisting of one or more trees (the
ODL is described in Section 4.4).
The allocation of virtual address space for TKl
(see Section 4.1.1)
can be represented by the single JVerlay tree shown in Figure 4-8.

4-15

OVERLAY CAPABILITY

A22

A21

I
AO

CNTRL

Figure 4-8

Overlay Tree for TKl

The tree has a root (CNTRL) and three main branches (AO, BO,
It also has six leaves (Al, A21, A22, Bl, B2, and C).
The tree has as many paths as it has leaves.
from the leaf to the root.
For example:

and

C).

The path down is defined

A21-A2-AO-CNTRL
The path up is defined from the root to the leaf.

For

example~

CNTRL-BO-Bl
Knowing the properties of the tree and its paths is important to
understanding the overlay loading mechanism and the resolution of
global symbols.

4.2.1

Loading Mechanism

Modules can call other modules that exist on the same path.
The
module CNTRL
(Figure 4-8)
is common to every path of the tree and,
therefore, can call and be called by every module in the tree.
The
module A2 can call the modules A21, A22, AO, and CNTRL;
but A2 cannot
call Al, Bl, B2, BO, or C.
When a module in one overlay segment calls a module in another overlay
segment, the called segment must be in memory and mapped, or must be
brought into memory. The methods for loading overlays are described
in Chapter 5.

4e2.2

Resolution of Global Symbols in a Multisegment Task

In resolving global symbols for a multisegment task, the Task Builder
performs the same activities that it does for a single-segment task.
The rules defined in Chapter 2 for
resolving global symbols in a
single-segment task apply also in this case, but the scope of the
global symbols is altered by the overlay structure.
In a single-segment task, any module can refer to any global
definition.
In a multisegment task, however, a module can only refer
to a global symbol that is defined on a path that passes through the
called segment.

4-16

OVERLAY CAPABILITY
The following points, illustrated in the tree diagram in Figure 4-9,
describe the two distinct cases of multiply defined symbols and
ambiguously defined symbols.
In a single~-segment task, if you define two global symbols with the
same1 name,
the symbols are multiply defined, and an error message is
produced.
In a multisegment task, you can define two global symbols with the
same name if they are on separate paths, and not referenced from a
segment that is common to both.
If you define a global symbol more than once on separate paths, but
they are referenced from a segment that is common to both, the symbol
is ambiguously defined.
If you define a global symbol more than once
on a single path, it is multiply defined.
The Task Builder's procedure
summarized as follows:

for

resolving

symbols

global

The Task Builder selects an overlay segment for processing.

The Task Builder scans each module in the segment for
definitions and references.

If the symbol is a definition, the Task Builder searches all
segments on paths that pass through the segment being
processed, and looks for references that must be resolved.

If the symbol is a reference, the Task Builder performs the
tree search as described in step 3, looking for an existing
definition.

If the symbol is new, the Task Builder enters it in a list of
global symbols associated with the segment.

global

Overlay segments are selected for processing in an order corresponding
to their distance from the root. That is, the Task Builder processes
the segment farthest
from the root first,
before processing an
adjoining segment.
When the Task Builder processes
symbols proceeds as follows:

segment,

•

The segment being processed

•

All segments toward the root

•

All segments away from the root

•

All co-trees (see Section 4.5)

Figure 4-9 illustrates
multisegment task.

the

resolution

4-17

its

global

for

symbols

global

OVERLAY CAPABILITY
A22
R (REF)

A21
T (DEF)
S (REF)

0 (REF)
S (REF)

I
A1
0 (REF)
R (REF)
S (REF)
I

A2
R (DEF)

S(Ry
81
0 (REF)

Q (DEF)

0 (DEF)
S (DEF)

S (DEF)
T (DEF)

82
S (REF)

CNTRL
S (REF)

Figure 4-9

Resolution of Global Symbols in a Multisegment Task

The following notes discuss the resolution
4-9:

4.2.3

references

Figure

The global symbol Q is defined in both segment AO and segment
BO.
The references to Q in segment A22 and in segment Al are
resolved by the definition in AO.
The reference to Q in Bl
is
resolved by the definition in BO.
The two definitions of
Q are distinct in all respects and occupy
different overlay
paths.

The global symbol R is defined in segment A2.
The
reference
to R in A22 is resolved by the definition in A2 because there
is a
path
to
the
reference
from
the
definition
(CNTRL-AO-A2-A22).
The
reference
to R in Al, however, is
undefined because there is no definition for
R on a
path
through Al.

The global symbol S is defined in both segment AO and segment
BO.
References to S from segments Al,
A21, or A22 are
resolved by the definition in AO, and references to S
in Bl
and B2 are
resolved by the definition in BO.
However, the
reference to S in CNTRL cannot be resolved because there are
two definitions of S on separate paths through CNTRL.
The
global symbol S is ambiguously defined.

The global symbol T is defined
in both segment A21 and
segment AO.
Since
there
is a single path through the two
definitions
(CNTRL-AO-A2-A21),
the global
symbol
T
is
multiply defined.

Resolution of Global Symbols from the Default Library

The process of resolving global symbols may require
two passes over
the
tree structure.
The global symbols discussed in the previous
section are included in user-specified input modules that
the Task
Builder scans in the first pass.
If any undefined symbols remain, the
Task Builder initiates a second pass over the structure in an attempt

4-18

OVERLAY CAPABILITY
to resolve such symbols by searching the default object module library
(normally LBO:[l,l]SYSLIB.OLB).
The Task
Builder
reports
any
undefined symbols remaining after its second pass.
When multiple tree structures (co-trees) are defined, as described
in
Section 4.5, any resolution of global symbols across tree structures
during a second pass can result in multiple or ambiguous definitions.
In addition,
such references can cause overlay segments to be
inadvertently displaced from memory by the overlay loading routines,
thereby causing run-time failures.
To eliminate these conditions, the
tree search on the second pass is restricted to:
•

The segment in which the undefined reference has occurred

•

All segments in the current tree that are on
the segment

•

The root segment

path

through

When the current segment is the main root, the tree search is extended
to all segments.
You can unconditionally extend the tree search to
all segments by including the FU (full) switch in the task image file
specification.
(Refer to Chapter 6 for a description of the FU
switch.)

4.2.4

Allocation of Program Sections in a Multisegment Task

One of a program section's attributes indicates whether the program
section is local
(LCL)
to the segment in which it is defined or is
global (GBL).
Local program sections with the same name can appear in any number of
segments.
The Task Builder allocates virtual address space for each
local program section in the segment in which it is declared.
Global
program sections that have the same name, however, must be resolved by
the Task Builder.
When a global program section is defined in several overlay segments
along a
common path, the Task Builder allocates all virtual address
space for the program section in the overlay segment closest to the
root.
FORTRAN common blocks are translated into global program sections with
the overlay (OVR) attribute.
In Figure 4-10, the common block COMA is
defined in modules A2 and A21. The Task Builder allocates the virtual
address space for COMA in A2 because that segment is closer to the
root than the segment that contains A21.
If the segments AO and BO use a common block COMAB, however, the Task
Builder allocates the virtual address space for COMAB in both the
segment that contains AO and the segment that contains BO. AO and BO
cannot communicate through COMAB. When the overlay segment containing
BO is loaded, any data stored in COMAB by AO is lost.
You can specify the allocation of program sections explicitly.
If AO
and BO need to share the contents of COMAB,
you can force the
allocation of this program section into the root segment by the use of
the
.PSECT directive of the Task Builder's overlay description
language, described in Section 4.4.

4-19

OVERLAY CAPABILITY

~MA

COM AB

CO MAB

CNTRL

Figure 4-10

4.3

Resolution of Program Sections for TKl

OVERLAY DATA STRUCTURES AND RUN-TIME ROUTINES

When the Task Builder constructs an overlaid task,
it
builds
additional data structures and adds them to the task image. It also
includes into the task image a number of system library routines
(called overlay run-time routines).
The data structures contain
information about the overlay segments and describe the relationship
of each segment in the tree to the other segments in the tree. The
overlay run-time routines use the data structures to facilitate the
loading of the segments and to provide the necessary linkages from one
segment to another at run time.
The Task Builder links the majority of data structures and all of the
overlay run-time routines into the root segment of the task. The
number and type of data structures, and the functions the routines
perform, depend on two considerations:
•

Whether the task is built to use the Task
or manual load facilities

•

Whether the
resident

overlay

segment

memory

Builder's
resident

autoload
or

disk

These considerations have a marked impact on the size and operation of
the task. Chapter 5 describes the Task Builder's autoload and manual
load facilities and describes the methods for loading overlays.
Appendix B describes the data structures and their contents in detail.
The contents of the root segment for a task with an overlay
are discussed briefly in the following paragraphs.

structure

Depending on the considerations above, some or all of the following
data structures are required by the overlay run-time routines:
•

Segment tables

•

Autoload vectors

•

Window descriptors

•

Region descriptors

4-20

OVERLAY CAPABILITY
Figure 4-11 shows a typical overlay root segment structure.

TASK CODE & DATA
WINDOW DESCRIPTORS
REGION DESCRIPTORS
SEGMENT DESCRIPTORS
OVERLAY
RUN-TIME
ROUTINES
AUTO LOAD VECTORS

TYPICAL
MAIN TREE
ROOT SEGMENT

TASK CODE
AND
DATA

HEADER AND STACK

Figure 4-11

Typical Overlay Root Segment Structure

There is a segment descriptor for every segment in the task.
The
descriptor contains information about the load address, the length of
the segment, and the tree linkage.
When you build an overlaid task autoloadable, autoload vectors appear
in the root segment and in every segment that calls modules in another
segment located farther away from the root of the tree.
Window descriptors are allocated whenever a memory-resident overlay
structure
is
defined
for
the task.
The descriptor contains
information required by the Create Address Window system directive
(CRAW$). One descriptor is allocated for each memory-resident overlay
segment.
Region descriptors are allocated whenever a task is linked to a shared
region containing memory-resident overlays. The descriptor contains
information required by th.e Attach Region system directive (ATRG$).

4-21

OVERLAY CAPABILITY
4.4

OVERLAY DESCRIPTION LANGUAGE

The Task Builder provides a language, called the Overlay Description
Language {ODL), that allows you to describe the overlay structure of a
task.
An overlay description is a text file consisting of a series of
ODL directives, one directive per line. You enter this file in a Task
Builder command line, and identify it as an ODL file by specifying the
MP switch
{see Chapter 6) to the file name.
If you specify an ODL
file to the Task Builder, it must be the only input file you specify.
An ODL line takes the form:
label:

directive

argument-list

;comment

A label is required only for the .FCTR directive {see Section 4.4.2).
The ODL directives are listed below and described
through 4.4.6:
•

.ROOT and .END

•

.FCTR

•

Sections

4.4.l

{exclamation point operator)

.NAME

•

.PSECT

•

@ {at sign;

indirect command file specifier)

Directives act upon argument-list which consists of named input files,
overlay segments, program sections, and lines in the ODL file itself.
Operators group these named task elements,
or attach attributes to
them.
If the name belongs to a
file,
you can enter a complete file
specification.
Defaults for omitted parts of the file specification
are as described in Chapters 1 and 6, except that the default device
is SYO:, and the default UFD is taken from the terminal UIC.
In addition, the following restrictions apply to argument-lists:

4.4.1

•

You can only use the dot character {.)

in a file name.

•

Comments cannot appear on a line ending with a file name.

.ROOT and .END Directives

Each overlay description must begin with one .ROOT directive and end
with one
.END directive. The .ROOT directive tells the Task Builder
where to start building the tree, and the
.END directive tells the
Task Builder where the input ends.
The arguments of the .ROOT directive use three operators
concatenation, overlaying, and memory residency.

4-22

express

OVERLAY CAPABILITY
hyphen (-) operator indicates the concatenation of virtual
• The
address space.
For example, X-Y means that sufficient virtual
address space will be allocated to contain segment X and
segment Y simultaneously. The Task Builder allocates segment
X and segment Y in sequence.
•

The exclamation point (!) operator indicates memory-residency
of overlays.
(This operator is discussed in Section 4.4.3.)

•

The comma
(,)
operator,
appearing
within
parentheses,
indicates the overlaying of virtual address space.
For
example, Y,Z means that virtual address space can contain
either segment Y or segment z.
If no exclamation point (1)
precedes the left parenthesis, segment Y and segment Z also
share physical memory.
The comma (,) operator is also used to define
structures (as described in Section 4.5.1).

multiple

tree

You use parentheses to delimit a group of segments that start at the
same virtual address.
The number of nested parenthetical groups
cannot exceed 16.
For example:
.ROOT X-(Y,Z-(Zl,Z2))
.END
These directives describe the tree
address space shown in Figure 4-12:

its

corresponding

x
Figure 4-12

virtual

and

Tree and Virtual Address Space Diagram

To create the overlay description for
the task TKl in Figure 4-3
(Section 4.1.1), you could create a file called TFIL.ODL that contains
the directives:
.ROOT CNTRL-(A0-(Al,A2-(A21,A22)),BO-(Bl,B2),C)
.END
To build the task with that overlay structure, you would type:
>TKB TKl=TFIL/MP
The MP switch in the command string above tells the Task Builder that
there is only one input file (TFIL80DL), and that this file contains
an overlay description for the task.

4-23

OVERLAY CAPABILITY
4.4.2

.FCTR Directive

The .FCTR directive allows you
represent them clearly.

build

large,

complex

trees

and

The .FCTR directive has a label at the beginning of the ODL line that
is pointed to by a reference in a .ROOT or another .FCTR statement.
The label must be unique with respect to module names and other
labels. The .FCTR directive allows you to extend the tree description
beyond a single line, and thus allows you to provide a clearer
description of the overlay.
(There can be only one .ROOT directive.)
For example, to simplify the tree given in the file TFIL (described in
Section 4.4.1), you could use the
.FCTR directive in the overlay
description as follows:
AFCTR:
BFCTR:

.ROOT CNTRL-(AFCTR,BFCTR,C)
.FCTR AO-(Al,A2-(A21,A22))
.FCTR BO-(Bl,82)
.END

The label BFCTR is used in the
.ROOT directive to designate the
argument of the
.FCTR directive, BO-(Bl,82). The resulting overlay
description is easier to interpret than the original description. The
tree consists of a root, CNTRL, and three main branches. Two of the
main branches have sub-branches.
The .FCTR directive can be nested to a level of 16.
could further modify TFIL as follows:
AFCTR:
A2FCTR:
BFCTR:

4.4.3

For example,

you

.ROOT CNTRL-(AFCTR,BFCTR,C)
.FCTR AO-(Al,A2FCTR)
.FCTR A2-(A21,A22)
.FCTR BO-(Bl,82)
.END

Exclamation Point Operator

The exclamation point operator allows you to specify overlay segments
that will reside in memory rather than on disk (see Section 4.1.2).
You specify memory residency by placing an exclamation point
(1)
immediately before the left parenthesis enclosing the segments to be
affected. The overlay description for task TK2 in Figure 4-4 (Section
4.1.2) is as follows:
.ROOT CNTRL-1 (D,E,F)
.END
In the example above, segments D, E, and F are declared resident in
separate areas of physical memory.
The single starting virtual
address for D, E, and F is determined by the Task Builder, by rounding
the octal length of segment CNTRL up to the next 4K boundary. The
physical memory allocated to segments D, E, and F is determined by
rounding the actual length of each segment to the next 32-word
boundary (256-word boundary if the CM switch is in effect), and adding
this value to the total memory required by the task.

4-24

OVERLAY CAPABILITY
The exclamation point operator applies only to segments at the first
level inside a pair of parentheses;
segments in parentheses nested
within that level are not affected.
It is therefore possible to
define an overlay structure that combines the space-saving attributes
of disk-resident overlays with the speed of memory-resident overlays.
For example:
.ROOT A-1 (Bl-(82,83) ,C)
.END
In this example,
Bl and C are declared memory resident by the
exclamation point operator.
82 and 83 are declared disk resident,
however,
because no exclamation
point
operator
precedes
the
parentheses enclosing them.
Not~~

that while a memory-resident overlay can call a disk-resident
overlay, the converse is not legal;
that is, you cannot use an
exclamation point for segments emanating from a disk-resident segment.
For example, you cannot build the following structure:
.ROOT A-(Bl-1 (B2,B3),C)
.END

; this overlay description is illegal

In this example, Bl is declared disk resident, so it is illegal to use
the exclamation point to declare 82 and 83 memory resident.

4.4.4

.NAME Directive

The .NAME directive allows you to specify a name for a segment, and
then to assign attributes to the seg~ent. The name must b~ unique
with respect to file names, program section names, .FCTR labels, and
other segment names used in the overlay description. The chief uses
of this directive are:

To name a segment uniquely that is to be loaded
manual load facility (see Chapter 5)

through

the

To permit a segment that does not contain executable code
be loaded through the autoload mechanism

The format of the .NAME directive is:
.NAME segname[,attr] [,attr]
segname
A 1- to 6-character name;
this name can consist of the Radix-50
characters A-Z, 0-9, and$ (the period (.) cannot be used).
attr
One of the following:
GBL

The name is entered in the segment's global symbol
table.
The GBL attribute makes it possible to load
nonexecutable overlay segments by means of the
autoload mechanism (see Chapter 5).

4-25

OVERLAY CAPABILITY
NOD SK

No disk space is allocated to the named segment.
If a data overlay segment has no
initial values,
but will have its contents established by the
running task, no space for the named segment on
disk need be reserved.
If the code attempts to
establish initial values for data in a segment for
which no disk space is allocated (a segment with
the NODSK attribute), the Task Builder gives a
fatal error.

NOGBL

The name is not entered in
symbol table.
If the GBL attribute
assumed.

DSK

the
not

segment's
present,

global

NOGBL

Disk storage is allocated to the named segment.
If the NODSK attribute
assumed.

not

present,

DSK

The attributes described are not attached to a segment until the name
is used in a .ROOT or .FCTR statement that defines an overlay segment.
When multiple segment names are applied to a segment,
the attributes
of the last name given are in effect.
In the following modified ODL file for TKl
(Figure 4-3 of Section
4.1.1),
the three main branches, AO, BO, and c, are provided with
names by specifying them in the .NAME directive and using them in the
.ROOT directive.
The default attributes NOGBL and DSK are in effect
for BRNCHl and BRNCH3, but BRNCH2 has the complementary attributes
(GBL and NODSK)
that will cause the Task Builder to enter the name
BRNCH2 into the segment's global symbol table and ·to allocate disk
space for the segment to be suppressed.
BRNCH2 contains uninitialized
storage to be utilized at runtime •

AFCTR:
BFCTR:

• NAME BRNCHl
.NAME BRNCH2,GBL,NODSK
.NAME BRNCH3
.ROOT CNTRL-1 (BRNCH1-AFCTR,*BRNCH2-BFCTR,BRNCH3-C)
.FCTR AO-(Al,A2-(A21,A22))
.FCTR BO-*! (Bl,B2)
.END

(The asterisk (*)
Chapter 5.)

is the

autoload

indicator;

The data overlay segment BRNCH2 is loaded by including
statement in the program.

discussed
the

following

CALL BRNCH2
This action is immediately followed by an automatic return to the next
instruction in the program.
You can also use segment names in making patches with the
GBLPAT options (see Chapter 6).

4-26

ABSPAT

and

OVERLAY CAPABILITY
NOTE
In the absence of a
unique
.NAME
specification,
the
Task
Builder
establishes a segment name,
using the
first program section file, or library
module name occurring in the segment.

4.4.5

.PSECT Directive

You can use the .PSECT directive to directly specify the placement of
a 9lobal program section in an overlay structure. The name of the
pro9ram section (a 1- to 6-character name consisting of the Radix-50
characters A-Z, 0-9, and $) and its attributes are given in the .PSECT
directive. Thus, you can use the name to indicate to the Task Builder
the segment to which the program section will be allocated.
An
example of the use of .PSECT is given in the modified version of task
TKl
(the original version is shown in Figure 4-3 in Section 4.1.1)
shown below.
In this example, TKl has a disk-resident overlay structure.
The
example assumes that the programmer was careful about the logical
independence of the modules in the overlay segment, but failed to take
into account the requirement for
logical independence in multiple
executions of the same overlay segment.
The flow of task TKl can be summarized as follows.
CNTRL calls each
of the overlay segments, and the overlay segment returns to CNTRL in
the order A, B, C, A.
Module A is executed twice.
The overlay
segment containing A must be reloaded for the second execution.
Module A uses a common block named DATA3. The Task Builder allocates
DATl\3 to the overlay segment containing A. The first execution of A
stores some results in DATA3. The second execution of A requires
these values.
In this disk-resident overlay structure, hciwever, the
values calculated by the first execution of A are overlaid. When the
segment containing A is read in for the second execution, the common
block is in its initial state.
To permit the two executions of A to communicate, a
.PSECT directive
is used to force the allocation of DATA3 into the root. The indirect
command file for TKl, TFIL.ODL, is modified as follows:

AFCTR:
BFCTR:

.PSECT DATA3,RW,GBL,REL,OVR
.ROOT CNTRL-DATA3-(AFCTR,BFCTR,C)
.FCTR A0-(Al,A2-(A21,A22))
.FCTR BO-(Bl,B2)
.END

The attributes RW, GBL, REL, and OVR are described in Chapter 2.

4.4.6

Indirect Command Files

The Overlay Description Language processor can accept ODL text
indirectly, that is, specified in an indirect command file.
If an at
sign (@) appears as the first character in an ODL line, the processor
will read text from the file specified immediately after the at sign.
The processor accepts the ODL text from the file as input,
at the
point in the overlay description where the file is specified.

4-27

OVERLAY CAPABILITY
For example, suppose you create a file, called BIND.ODL, that contains
the text:
B:

.FCTR Bl-(B2,B3)

This text can be replaced by a
line beginning
position where the text would have appeared:

@BIND,

the

Direct

Indirect
.ROOT A-(B,C)
.FCTR Cl-(C2,C3)

with

C:
B:

@BIND
.END

.ROOT A-(B,C)
.FCTR Cl-(C2,C3}
.FCTR Bl-(B2,B3)
.END

The Task Builder allows two levels of indirection.

4.5

MULTIPLE-TREE STRUCTURES

You can define more than one tree within an overlay structure.
These
multiple tree structures consist of a main tree and one or more
co-trees. The root segment of the main tree
is loaded by the
Executive when the task is mad~ active, while segments within each
co-tree are loaded through calls to the overlay run-time routines.
Except
for
this distinction,
all overlay trees have identical
characteristics:
a root segment that resides in memory,
and two or
more overlay segments.
The main property of a structure containing more than one tree is that
storage is not shared among trees.
Any segment in a tree can be
referred to from another tree without displacing segments from the
calling tree.
Routines that are called from several main tree overlay
segments, for example, can overlay one another in a co-tree. The same
considerations in deciding whether to create memory-resident overlays
or disk-resident overlays in a single-tree structure apply in building
a structure containing co-trees.

Defining a Multiple-Tree Structure

4e5.l

Multiple-tree structures are specified within the Overlay Description
Language by extending the function of the comma operator.
As
described in Section 4.4, this operator, when included
within
parentheses,
defines a pair of segments that share storage. The
inclusion of the comma operator outside all parentheses delimits
overlay trees.
The first overlay tree thus defined is the main tree.
Subsequent trees are co-trees.
For example:

X:
Y:

.ROOT
.FCTR
.FCTR
.END

X,Y
XO-(Xl,X2,X3}
YO-(Yl,Y2}

In this example, two overlay trees are specified:
1)
a main tree
containing the root segment XO and three overlay segments, and 2) a
co-tree consisting of root segment YO and two overlay segments.
The
Executive loads segment XO into memory when the task is activated.
The task then loads the remaining segments through calls to the
overlay run-time routines.

4-28

OVERLAY CAPABILITY
A co-tree must have a root segment to establish linka~e with its own
overlay segments.
However, co-tree root segments need not contain
code or data and, therefore, can be 0 length.
You can create a
segment of this type, called a null segment, by means of the .NAME
directive. The previous example is modified, as shown below, to move
file YO.OBJ to the root and include a null segment.
X:
Y:

X,Y
XO-YO-(Xl,X2,X3)
YNUL
YNUL-(Yl,Y2)

.ROOT
.FCTR
.NAME
.FCTR
.END

The null segment YNUL is created by use of the .NAME directive,
replaces the co-tree root that formerly contained YO.OBJ.

4.5~2

and

Multiple-Tree Example

The following example illustrates the use of multiple trees to
the size o~ the task.

reduce

In this example, the root segment CNTRL of task TKl
(described in
Section 4.1.1) has had two routines added to it: CNTRLX and CNTRLY.
The routines are logically independent of each other, and both are
approximately 4000(8)
bytes long.
However, the routines have been
placed in the rciot segment of TKl instead of being overlaid because
both routines must be accessed from modules on all paths of the tree.
In a single-tree overlay structure, the root segment is the only
segment common to all paths of the tree. The schematic diagram for
the modified structure is shown in Figure 4-13.

A21

I
A1

A22

I
CNTRLY

CNTRLX
I

}

ROOT

SEGMENT

CNTRL
Figure 4-13

Overlay Tree for Modified TKl

4-29

OVERLAY CAPABILITY
One possible overlay description for this structure is shown below •
• ROOT CNTRL-CNTRLX-CNTRLY-(AFCTR,BFCTR,C)
AFCTR:
.FCTR AO-(Al,A2FCTR)
A2FCTR: .FCTR A2-(A2l,A22)
BFCTR:
.FCTR BO-(Bl,B2)
.END
Because TKl consists of disk-resident overlays and the new routines
are concatenated within the overlay structure, the new routines add
10000(8) bytes to both the virtual address ~pace and physical memory
requirements of the task. However, the added routines consume more
virtual address space than might be expected, as shown in Figure 4-14.
The expansion of TKl's virtual address space requirements caused the
task to extend 4-000(8) bytes beyond the next highest 4K word boundary
(APR 2).
Because the Executive must use an additional mapping
register (APR2) the apparent cost in virtual address space above APR 2
of 4000(8) bytes is in fact 20000(8) bytes.
(Compare the diagram in
Figure 4-14 with the diagram in Figure 4-3.) The shaded portion of the
unused virtual address space in Figure 4-14 represents the portion of
virtual address space that is allocated but is unusable as allocated.
Small tasks, such as TKl, are seldom adversely affected by the
inefficient allocation of virtual address space, but larger tasks may
be.
For example, a large task that contains code to create dynamic
regions
(see Chapter 3)
or that contains Executive directives to
extend its task region (see the RSX-llM/M-PLUS Executive Reference
Manual) will require at least 4K words of virtual address space to map
each region.
In such a task, the use of co-trees can often save
virtual address space and can, therefore, be of paramount importance.
TKl can be modified to reflect this.
As noted earlier,
the routines CNTRLX and CNTRLY are logically
independent.
Logical independence is a primary requirement for all
segments that overlay each other. However, CNTRLX and CNTRLY cannot
be structured into either of the main branches of TKl's tree because
it is further required that the routines be accessible from modules on
all paths of the tree. Therefore, the only way CNTRLX and CNTRLY can
be overlaid and still meet all of these requirements is through a
co-tree structure.
Figure 4-15 shows the schematic representation of
TKl as a co-tree structure.

4-30

OVERLAY CAPABILITY

APR7-

APR6-

APR5-

APR4-

APR3-

APR2-

A2
AO

lA21lA22Jl B1 @
A2
B2
c
AO
BO
I

A1 _I

BO
CNTRLY

APR1ROOT
SEGMENT

APRO-

...

- - - CNTRLX
- - -

r- t-

CNTRLY

- - - CNTRLX
- - - -

- - -

CNTRL

HEADER AND STAC.:

HEADER AND STACK

VIRTUAL ADDRESS
SPACE

PHYSICAL MEMORY

Figure 4-14

Virtual Address Space and Physical Memory for Modified TKl

4-31

OVERLAY CAPABILITY

A21

A22

I
BO

CNTRLX

CNTRLY

CNTRL

CNTRL2

MAIN TREE

CO-TREE

Figure 4-15

Overlay Co-Tree for Modified TKl

The root segment CNTRL2 of the co-tree is a null segment.
It contains
no code or data and has a length of O. As noted earlier, the root
segment is required by the Task Builder in order to establish linkage
with the overlay segments.
One possible overlay description for
building TKl as a two-tree structure is shown below •

AFCTR:
A2FCTR:
BFCTR:

• NAME CNTRL2
.ROOT CNTRL-(AFCTR,BFCTR,C),CNTRL2-(CNTRLX,CNTRLY)
.FCTR AO-(Al,A2FCTR)
.FCTR A2-(A21,A22)
.FCTR B0-(Bl,B2)
.END

The co-tree is defined in the .ROOT directive by placing the comma
operator outside all parenthesis
(immediately before CNTRL2). The
.NAME directive creates the null root segment.
Figure 4-16 shows the
new relationship between virtual address space and physical memory.
The diagrams in Figure 4-16 illustrate the savings (4000(8) bytes)
in
both virtual address space and physical memory that is realized by
overlaying CNTRLX and CNTRLY. What may be more important in some
applications,
however,
is that the top of TKl's task region has
dropped below the 4K boundary of APR 2. TKl has gained 4K words of
potentially usable virtual address space.
NOTE
The numbers used in this example have
been
simplified
for
illustrative
purposes.
In addition,
the
storage
required for overhead in handling the
overlay structures is not reflected in
this example.
Because the null root CNTRL2 is 0 bytes long, it does not require any
virtual address space or physical memory and, therefore, does not
appear in the diagrams in Figure 4-16.
Finally, you can define any number of co-trees.
Additional
can access all modules in the main tree and other co-trees.

4-32

co-trees

OVERLAY CAPABILITY

APR 7-

APR 6-

APR 5-

APR 4-

APR 3-

CNTRLX
A1

APR 1-

A211 A22
A2
AO

CNTRLY
B1 ~
B2

ROOT
- NULL
LENGTH=O

...

HEADER AND STACK

CNTRLY

l A21J A22 B1

i---

B2
BO

CNTRL
(ROOT SEGMENT)

APR 0-

CNTRLX

-- ---

HEADER AND STACK

VIRTUAL ADDRESS SPACE

PHYSICAL MEMORY

Figure 4-16 Virtual Address Space
and Physical Memory for TKl as a Co-Tree

4-33

OVERLAY CAPABILITY
4.6

OVERLAYING PROGRAMS WRITTEN IN A HIGH-LEVEL LANGUAGE

Programs written in a high-level language usually require the use of a
large number of library routines in order to execute. Unless care is
taken when overlaying such programs, the following problems can occur:
•

Task Builder throughput may be drastically reduced because
the number of library references in each overlay segment.

•

Library references from the default object module library,
that are resolved across tree boundaries can result in
unintentional displacement of segments from memory at runtime.

•

Attempts to task build such programs can result in multiple
and ambiguous symbol definitions when a co-tree structure is
defined.

The following procedures are effective in solving these problems:
•

Task Builder throughput can be increased if you link
used library routines into the main root segment.

commonly

•

Ambiguous and multiple definitions, and cross-tree references
can be eliminated by using the NOFU switch (the Task Builder
default) to restrict the scope of the default library search.

If sufficient memory is available,
the object time system can be
effectively placed in the root segment by building a memory-resident
library. This also reduces total system memory requirements if other
tasks are also currently using the library.
If a memory-resident library cannot be built, you can force
library
modules into the root by preparing a list of the appropriate global
references and linking the object module into the root segment.
For other ways to reduce task size, you
guide for the language you are using.

4.7

EXAMPLE 9:

should

consult

the

user's

BUILDING AN OVERLAY

The text in this section and the figures associated with it illustrate
the building of an overlay structure.
For this example, the routines
of the resident library LIB.TSK and the task that refer
to
it,
MAIN.TSK
(from Example 4, Chapter 3), are assembled as separate
modules and built as an overlaid task.
This task is built first with
disk-resident overlays and then with memory-resident overlays. The
·disk-resident version of the task is named
OVR.TSK
and
the
memory-resident version is named RESOVR.TSK.
NOTE
This example is intended to provide you
with
a working illustration of the
Overlay Description Language.
It does
not reflect the most efficient use of
it.

4-34

OVERLAY CAPABILITY
Two alterations were made to each of the routines for this example:
•

A .TITLE and
.END assembler directive was
routine to establish it as an unique module.

added

each

•

The following assembler directive was added to each arithmetic
routine to increase its allocation:
.BLKW 1024.*3
This was done to make the Task Builder allocation
space more obvious for documentation purposes.

address

The operation of the overlaid task is identical to that of Example 4
in Chapter 3. The routines and their titles as a result of the .TITLE
directives are as follows:

• The integer addition routine is named AD DOV
• The integer subtraction routine is named SUBOV
• The integer multiplication routine is named MULOV
• The integer division routine is named DIVOV
• The register save and restore routine is named SAVOV
• The print routine is named PRNOV
• The main calling routine is named ROOTM
The lengths of the modules are:
Modul~

Length (in octal)

AD DOV

14024 bytes

SUBOV

14024 bytes

MULOV

14024 bytes

DIVOV

14026 bytes

SAVOV

4042 bytes

PRNOV

4260 bytes

ROOTM

4104 bytes

The flow of control for OVR.TSK is as follows:
ROOTM calls AD DOV and ADDOV returns to ROOTM
ROOTM calls PRNOV to print the result and PRNOV returns to ROOTM
ROOTM calls SUBOV and SUBOV returns to ROOTM
ROOTM calls PRNOV to print the result and PRNOV returns to ROOTM
ROOTM calls DIVOV and DIVOV returns to ROOTM
ROOTM calls PRNOV to print the result and PRNOV returns to ROOTM
ROOTM calls MULOV and MULOV returns to ROOTM
ROOTM calls PRNOV to print the result and PRNOV returns to ROOTM
4-35

OVERLAY CAPABILITY
The print routine (contained in module PRNOV) is called between each
arithmetic operation by the control routine
(contained in module
ROOTM). To avoid loading it into physical memory each time it is
called, PRNOV can be placed in the root segment of the task.
In
addition, each arithmetic routine calls SAVOV. Therefore, SAVOV must
be on a path common to all segments in the tree. It too is placed in
the root segment of the task. One possible overlay configuration far
this task is shown in Figure 4-17.

SUBOV

DIVOV

I
AD DOV

MULOV

l_ _ _ _ _ _I·
SAVOV

I
}
PR~OV
SE~~OETNT

ROOTM

Figure 4-17

Overlay Tree of Virtual Address Space for OVR.TSK

To build this overlay, first create an ODL
contains its description:
.ROOT

file

(OVERTREE.ODL)

that

ROOTM-PRNOV-SAVOV-*(MULOV,ADDOV-(SUBOV,DIVOV))

.END
Then, after you have modified the modules and assembled them, you
build the task with the following command line:

can

TKB>OVR,OVR/-SP=OVRTREE/MP
This command instructs the Task Builder to build a task image OVR.TSK
and to create a map file, OVR.MAP, under the UFO that corresponds to
the terminal UIC. The negated spool switch (/-SP) inhibits the Task
Builder from spooling the map file to the line printer.
The overlay switch (/MP) attached to the input file tells the Task
Builder that the input file is an ODL file. Therefore, this file will
be the only input file specified.
Refer to Chapter 6 for a
description of the switches used in this example.
A portion of the map that results from this task
Figure 4-18.

4-36

build

shown

OVERLAY CAPABILITY
PARTITION NAME : GEN
IDENTIFICATION :
01
TASK UIC
[303,3]
STACK
LIMITS:
000176 001175 001000 00512.
PRG XFR ADDRESS:
010010 ----S::TOTAL ADDRESS WINDOWS:
1. ~
TASK IMAGE SIZE
10496. WORDS
TASK ADDRESS LIMITS:
000000 050753
R-W DISK BLK LIMITS:
000002 000106 000105 00069.

Task
Attributes
Section

OVR.TSK;ll OVERLAY DESCRIPTION:
BASE:

TOP

LENGTH
ROOTM
MULOV
AD DOV
SUBOV
DIVOV

08640.
06164.
06164.
06164.
06168.

*** ROOT SEGMENT:

ROOTM

R/W MEM LIMITS: 000000 020677 020700 08640.
DISK BLK LIMITS: 000002 000022 000021 00017.
MEMORY ALLOCATION SYNOPSIS:
SECnON

TITLE

• BLK.: (RW,I ,LCL,REL,CON) OOll 76 002034 01052.
ANS
:(RW,D,GBL,REL,OVR) 003232 004006 02054.
003232 004006 02054. ROOTM

IDENT

FILE

ROOTM.OBJ;lO

GLOBAL SYMBOLS:
AADJD
ANS

007276-R
007232-R

DIVV
MULL

007316-R
007266-R

PRINT
SAVAL

014274-R
020366-R

SUBB

007306-R

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 7768.
WORK FILE READS:
O.
WORK FILE WRITES:
0.
SIZE OF CORE POOL:
8198. WORDS (32.
SIZE OF WORK FILE:
3328. WORDS (13.

PAGES)
PAGES)

ELAPSED TIME:00:00:27
Figure 4-18

Map File for OVR.TSK

Figure 4-19 shows the allocation of virtual address space for OVR.TSK.
The circled numbers in Figure 4-18 correspond to the circled numbers
in Figure 4-19.

4-37

OVERLAY CAPABILITY

160000

APR 7-

140000

APR 6-

120000

APR 5-

100000

APR 4-

60000

APR 3-

SUBOV ·

40000

DIVOV

APR 2-

-~
- 034723

MULOV

AD DOV

- 020677

_________

.__

Figure 4-19

ROOT SEGMENT

- 001176
__,_~

Allocation of Virtual Address Space for OVR.TSK

4-38

OVERLAY CAPABILITY
Note that the root segment for OVR.TSK (ROOTM) has expanded with task
building while the segments containing the arithmetic routines have
not.
Before task building, the sum of the modules
(in octal bytes)
that comprise the root segment is:
4104 + 4260 + 4042 = 14,426 bytes
After task building, the root segment is 20,677(8)
bytes long.
The
Task Builder has added a header,
a stack area, and the overlay
run-time routines to
it.
The segments containing the arithmetic
routines have not changed.
If there had been calls from segments
nearer the root to segments up tree, the Task Builder would have added
data structures to the calling segments as well.
(Refer to Chapter 5
for a description of the overlay loading methods.)
You can build OVR as a memory-resident overlay by simply adding the
memory-resident operator (!) to the ODL file for OVR as shown below:
.ROOT
.END

ROOTM-PRNOV-SAVOV-*!(MULOV,ADDOV-!(SUBOV,DIVOV))

For this example, the name of the ODL file and the task image file
havE~
been changed to RESOVR.ODL to distinguish it from the disk
resident version.
You can build RESOVR with the following
command
1 i DE~:
TKB>RESOVR,RESOVR/-SP=RESOVR/MP
This command directs the Task Builder to build a task named RESOVR.TSK
and to create a map file named RESOVR.MAP. The negated spooling
switch (/-SP) inhibits spooling of the map file.
The MP switch on the input file tells the Task Builder that the file
is an ODL file and that it will be the only input file for this task
build.
Refer to Chapter 6 for a description of the switches used
in
th i :s example.
A portion of the map that results from this task
Figure 4-20.

build

shown

Figure 4-21 shows the allocation of virtual address space for
RESOVR.TSK.
The circled numbers
in Figure 4-20 correspond to the
numbers in Figure 4-21.

4-39

OVERLAY CAPABILITY
PARTITION NAME : GEN
IDENTIFICATION : 01
TASK UIC
[303~3]
STACK
LIMITS: 000236 001235 001000 00512.
PRG XFR ADDRESS: 010226 ~
TOTAL ADDRESS WINDOWS:
3. G
TASK IMAGE SIZE
16896. WORDS
TASK ADDRESS LIMITS: 000000 077777
R-W DISK BLK LIMITS: 000002 000107 000106 00070.

Task
Attributes
Section

RESOVR.TSK;2 OVERLAY DESCRIPTION:
BASE ~ TOP

LENGTH

~ ~;-;_m/ 0214~~--~8960.
040000
040000
060000

054077
054077
074077

014100
014100
014100

060000~0~4077~014100

ROOTM
MULOV
AD DOV
SUBOV
DIVOV

06208.
06208.
06208.

06208.

*** ROOT SEGMENT: ROOTM
R/W MEM LIMITS: 000000 021377 021400 08960.
DISK BLK LIMITS: 000002 000023 000022 00018.
MEMORY ALLOCATION SYNOPSIS:
TITLE

SECTION

• BLK.: (RW,I,LCL,REL,CON) 001236 002034 01052.
ANS
: (RW,D,GBL,REL,OVR) 003272 004006 02054.
003272 004006 02054. ROOTM

!DENT

FILE

ROOTM.OBJ;lO

GLOBAL SYMBOLS:
AADD
ANS

007336-R
007272-R

DIVV
MULL

007356-R
007326-R

PRINT
SAVAL

014512-R
020604-R

SUBB

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES:
7840.
WORK FILE READS
O.
WORK FILE WRITES :
O.
SIZE OF CORE POOL:
8198. WORDS (32.
SIZE OF WORK FILE:
3328. WORDS (13.

PAGES)
PAGES)

ELAPSED TIME:00:00:24
Figure 4-20

Map File for RESOVR.TSK

4-40

007346-R

OVERLAY CAPABILITY

160000

APR 7-

140000

APR 6-

120000

APR 5-

100000

APR 4-

60000

APR 3-

~~~~!ifm,;.;,;.;;~~~~~

::::::::::::: ..:::::::::::::::::/:::::-::.:::::::::::::::::<:::::::: ...·:..·:..-:.··:.··:.··

40000

20000

APR 1-

SYSLIB
SAVOV
PR NOV
ROOTM

ROOT SEGMENT

1--------------1 - 001236
0

APR 0-

Figure 4-21

HEADER AND STACK

Allocation of Virtual Address Space for RESOVR.TSK

4-41

OVERLAY CAPABILITY

Note that the Task Builder allocates virtual address space for each
level of overlay segment on a 4K word boundary. When built as a
disk-resident overlay, this structure requires 12K words of virtual
address space; when built as a memory-resident overlay structure, .it
requires 16K words of virtual address space. As noted earlier, you
must be careful when using memory-resident overlays to ensure that
virtual address space is used efficiently.
Finally, note in Figure 4-20 that the Task Builder has allocated three
window blocks to map RESOVR.TSK.
Each level of the overlay in a
memory-resident overlay requires a separate window block to map it.
In a disk-resident overlay, a single window block maps the entire
structure r~gardless of how many segment levels there are within the
structure.
This consideration can be important when you are building
an overlaid task that either creates dynamic regions or that accesses
a resident library or common because of the extra window blocks
required to use these features.

4.8

SUMMARY OF THE OVERLAY DESCRIPTION LANGUAGE

An overlay structure consists of one or more trees.
Each
tree contains at least one segment. A segment is one or more
modules containing one or more program sections that can be
loaded by a single disk access.
A tree can have only one root segment, but it
number of overlay segments.

can

have· any

An ODL file is a text file consisting of a series of overlay
description directives, one directive per line. You enter
this file in the Task Builder command line, and identify it
as an ODL file by attaching the MP switch to the file name.
If you enter an ODL file in the Task Builder command line, it
must be the only input file you specify.

The overlay description language provides five directives for
specifying the tree representation of the overlay structure:
a.

b.
c.
d.

.ROOT and .END -- There can be only one .ROOT and one
• END directive;
the .END directive must be the last
directive because it terminates input.
.PSECT
.FCTR
.NAME

.PSECT, .FCTR, and .NAME can be used in any order in the
file.
4.

ODL

You define the tree structure using the hyphen (-), comma
(,), and exclamation point (1) operators, and by using
parentheses.
a.

The hyphen operator (-) indicates that its arguments are
to be concatenated and thus are to coexist in memory.

The comma operator (,) within parentheses indicates that
its
arguments
are
to
overlay each other either
physically, if disk resident, or virtually, if memory
resident.

The comma operator
overlay trees.

not

4-42

within

parentheses

delimits

OVERLAY CAPABILITY
d.

The parentheses group segments that
point in memory.
For example:

begin

the

same

.ROOT A-B-(C,D-(E,F))
This ODL command line defines an overlay structure with a
root segment consisting of the modules A and B.
In this
structure, there are four overlay segments:
c, D, E, and
F.
The outer pair of parentheses indicates that the
overlay segments C and D start at the same virtual
address;
and similarly, the inner parentheses indicate
that E and F start at the same virtual address.
e.

The exclamation point operator {!) immediately before a
left parenthesis declares the enclosed segments to be
memory resident.
Nested segments in parentheses are not
affected by an exclamation point operator at a level
closer to the root.

The .ROOT directive defines the beginning overlay structure.
The arguments of the .ROOT directive are one or more of the
following:
a.

File specifications as described in Chapter 1

Factor labels

Segment names

Program-section names

The .END directive terminates input

The .FCTR directive provides a means for replacing text by a
symbolic reference
(the factor label). This replacement is
useful for two reasons:
a.

The
.FCTR directive extends the text of the
.ROOT
directive to more than one line and thus allows complex
trees to be represented.

The .FCTR directive allows the overlay description to be
written in a
form that makes the structure of the tree
more apparent.

For example:
.ROOT A-(B-(C,D),E-(F,G),H)
.END
Using the .FCTR directive this
written as follows:
Fl:
F2:

overlay

description

can

tree

has

.ROOT A-(Fl,F2,H)
.FCTR B-(C,D)
.FCTR E-(F,G)
.END

The second representation makes it clear that
three main branches.

4-43

the

OVERLAY CAPABILITY
8.

The .PSECT directive provides a means for directly specifying
the segment in which a program section is placed.
It accepts
the name of .the program section and its attributes.
For
example:
.PSECT ALPHA,CON,GBL,RW,I,REL
ALPHA is the program section name and the remaining arguments
are
the
program section's attributes
(program section
attributes are described in Chapter 2).
The program section name (composed of the characters A-Z,
0-9, and $)
must appear first in the .PSECT directive, but
the attributes can appear in any order, or can be omitted.
If an attribute is omitted, a default condition is assumed.
The defaults for program section attributes are RW,
I,
LCL,
REL, and CON.
In the example above, therefore, you need only specify the
attributes that do not correspond to the defaults:
.PSECT
ALPHA,GBL

The .NAME directive provides you with the means to designate
a segment name for use in the overlay description, and to
specify segment attributes. This directive is useful
for
creating a
null segment,
naming a segment that is to be
loaded manually, or naming a nonexecutable segment that is to
be autoloadable.
(Refer to Chapter 5 of this manual for a
description of manually loaded and automatically loaded
segments.)
If you do not use the .NAME directive, the Task
Builder uses the name of the first file, program section,
or
library module in the segment to identify the segment.
The .NAME directive creates a segment name as follows:
.NAME segname,attr,attr
where segname is the designated name
(composed of the
characters A-Z,
0-9, and $),
and attr
is an optional
attribute taken from the following:
GBL, NODSK, NOGBL, DSK.
The defaults are NOGBL and DSK. The defined name must be
unique with respect to the names of program ~ections,
segments, files, and factor labels.

10.

You can define a co-tree by specifying an additional tree
structure in the .ROOT directive. The first overlay tree
description
in the .ROOT directive is the main
tree.
Subsequent overlay descriptions are co-trees.
For example:
.ROOT A-B-(C,D-(E,F)),X-(Y,Z),Q-(R,S,T)
The main tree in this example has the root segment consisting
of files A.OBJ and B.OBJ. Two co-trees are defined;
the
first co-tree has the root segment X and the second co-tree
has the root segment Q.

4-44

CHAPTER 5

OVERLAY LOADING METHODS

The RSX-llM/M-PLUS systems
provide
two
disk-resident and memory-resident overlays:

methods
are

for

•

Autoload -- the Overlay Run-time
routines
called to load segments you have specified

•

Manual Load -- you include in the task explicit calls
Overlay Run-Time routines.

automatically

When you build an overlaid task, you must decide which one of
methods to use, because both cannot be used in the same task.

the
these

The loading process depends on the kind of overlay:
•

Disk resident -- a segment is loaded from disk into a
shared
area of physical memory, writing over whatever was present.

•

Memory resident -- a segment is "loaded" by mapping a
set of
shared virtual addresses to a unique unshared area of physical
memory, where the segment has been made permanently resident
(after having been initially brought in from the disk).

With the autoload method, the Overlay Run-Time routines handle loading
and error
recovery.
Overlays are automatically loaded by being
referenced through a transfer-of-control instruction
(CALL, JMP,
or
JSR).
No explicit calls to the Overlay Run-Time routines are needed.
In the manual load method,
you handle loading and error
recovery
explicitly~
Manual
loading saves space and gives you full control
over the loading process, including the ability to specify whether
loading is to be done synchronously or asynchronously.
In the manual load method, you must provide for
loading the overlay
segments of both the main tree and the root segments, as well as the
overlay segments, of the co-trees.
Once loaded, the root segment of a
co-tree remains in memory.

5.1

AUTOLOAD

To specify the autoload method, you use the autoload indicator,
an
asterisk
(*).
You place this indicator in the ODL description of the
task at the points where loading must occur.
The execution of a
transfer-of-control
instruction to an autoloadable segment up-tree
(farther away from the root)
automatically initiates the autoload
process.

5-1

OVERLAY LOADING METHODS
5.1.1

Autoload Indicator

The autoload indicator (*) marks as autoloadable the segment or other
task element (as defined below).
If you apply the autoload indicator
to an ODL statement enclosed in parentheses, every task element within
the parentheses is marked as autoloadable.
Placing the autoload
indicator at the outermost level of parentheses in the ODL description
marks every module in the overlay segments as autoloadable.
If, in the TKl example of Chapter 4, Section 4.1.1,
segment C
consisted of a set of modules Cl, C2, C3, C4, and CS, the tree diagram
would be as shown in Figure 5-1.

A21
I

A1
I

I
AO

A22
I

C4
C3

I
BO

C2
C1

CNTRL
Figure 5-1

Details of Segment C of TKl

Placing the autoload indicator at the outermost level of parentheses
ensures that,
regardless of the flow of control within the task, a
module will be properly loaded when it is called. The ODL description
for task TKl would be:
AFCTR:
BFCTR:
CFCTR:

.ROOT CNTRL-*(AFCTR,BFCTR,CFCTR)
.FCTR AO-(Al,A2-(A21,A22))
.FCTR BO-(Bl,B2)
.FCTR Cl-C2-C3-C4-CS
.END

Also, when the root segment of a co-tree is not a null segment,
you
must mark the co-tree's root segment (CNTRL2) as well as its outermost
level of parentheses to ensure that all modules of the co-tree are
properly loaded.
For example,
if the· co-tree root (CNTRL2) of the
multiple tree example, Section 4.5.2, had contained code or data it
would have been marked as follows:
.ROOT CNTRL-*(AFCTR,BFTCR,CFCTR) ,*CNTRL2-*(CNTRLX,CNTRLY)

You can apply the autoload indicator to the following elements:
make

all

components

the

file

File names - to
autoloadable.

•

Portions of ODL tree descriptions enclosed in parentheses - to
make all the elements within the parentheses autoloadable,
including elements within any nested parentheses.

•

Program section
names - to
make
the
program
section
autoloadable.
The program section must have the instruction
(I) attribute.

5-2

the

•

OVERLAY LOADING METHODS
•

Segment names defined by the
.NAME directive - to
components of the segment autoloadable.

make

all

•

.FCTR label names - to make the first component of the factor
autoloadable.
All elements specified in the .FCTR statement
are autoloadable if they are enclosed in parentheses.

In the following example, two .PSECT directives and a .NAME directive
are
introduced into the ODL description for TKl. Autoload indicators
are applied as follows:
AFCTR:
BFCTR~

CFCTR:

.ROOT CNTRL-(*AFCTR,*BFCTR,*CFCTR)
.FCTR AO-*ASUB1-ASUB2-*(Al,A2-(A21,A22))
.FCTR (BO-(Bl,82))
.FCTR CNAM-Cl-C2-C3-C4-C5
.NAME CNAM,GBL
.PSECT ASUBl,I,GBL,OVR
.PSECT ASUB2,I,GBL,OVR
.END

The following notes are keyed to the example above.
1.

The autoload
therefrire:

indicator

*AFCTR=*AO

•

*BFCTR=*(BO-(Bl-82))

•

*CFCTR=*CNAM

appli~d

each

factor

name;

CNAM, however, is an element defined by a
.NAME directive.
Therefore,
all components of the segment to which the name
applies are made autoloadable, that is, Cl, C2, C3, C4,
and
C5.
2.

The autoload indicator is applied to the name of a program
section with the
instruction
(I)
attribute
(*ASUBl), so
program section ASUBl is made autoloadable.

The autoload indicator is applied to a
description enclosed in parentheses:

portion

the

ODL

made

*(Al,A2-(A21,A22))
Thus,
every
autoloadable

element within
the
parentheses
(that is, files Al, A2, A21, and A22).

The net effect of this ODL description is to make every element except
program section ASUB2 autoloadable.

5.1.2

Path Loading

The autoload method uses path loading;
that is,
a call from one
segment to another segment up-tree
(farther away from the root)
ensures that all the segments on the path from the calling segment to
the called segment will reside in physical memory and be mapped.
Path
loading is confined to the tree in which the called segment resides.
A call from a segment in one tree to a segment in another tree results
in the loading of all segments on the path in the second tree from the
root to the called module.

5-3

OVERLAY LOADING METHODS

A22
I

A21

I
A1

I
A2

C5
C4
C3
C2
C1

CNTRL

Figure 5-2

Path-Loading Example

In Figure 5-2, if CNTRL calls A22, all the modules between the
and A2 are loaded.
In this case, modules AO and A2 are loaded.

CNTRL

With the autoload method, the Overlay Run-Time routines keep a record
of the segments that are loaded and mapped, and issue disk-load
requests only for segments that are not in memory.
If CNTRL calls A2
after calling Al, AO is not loaded again because it is already in
memory and mapped.
A reference from one segment to another segment down-tree
(closer to
the root)
is resolved directly.
For example, A2 can immediately
access AO because AO was path loaded in the call to A2.

5.1.3

Autoload Vectors

To resolve a reference up-tree to a global symbol in an autoloadable
segment,
the Task Builder generates an autoload vector for the
referenced global symbol. The reference in the code is changed to a
definition that points to an autoload vector entry. The format for
the autoload vector is shown in Figure 5-3.

JSR

PC,SUB
$AUTO

SEGMENT DESCRIPTOR ADDR.
ENTRY POINT ADDRESS

Figure 5-3

Autoload Vector Format

In the figure, a transfer-of-control instruction to the global
executes the call to the autoload routine, $AUTO.

symbol

An exception to the procedure for generating autoload vectors is made
in the case of a program section with the data (D) attribute.
References from a segment to a global symbol up-tree in a program
section with the data (D) attribute are resolved directly.
Because the Task Builder can obtain no information about the flow of
control within the task, it often generates more autoload vectors than
are necessary. However, your knowledge of the flow of control within
your task, and knowledge of path loading, can help you determine where
to place the autoload indicators.
By placing the autoload indicators

5-4

OVERLAY LOADING METHODS
only at the points where loading is actually required, you can
minimize the number of autoload vectors generated for the task.
In the following example, all the calls to overlays originate
in the
root segment.
That is, no module in an overlay segment calls outside
its segment.
The root segment CNTRL has the following contents:
PROGRAM CNTRL
CALL Al
CALL A21
CALL A2
CALL AO
CALL A22
CALL BO
CALL Bl
CALL B2
CALL Cl
CALL C2
CALL C3
CA.LL C4
CALL CS
E:ND
If you place the autoload indicator at the outermost level of
parentheses,
13 autoload vectors are generated for
this task;
however, because A2 and AO are loaded by path loading to A21,
the
autoload vectors for A2 and AO are unnecessary.
Moreover, the call to
Cl loads the segment that contains C2, C3, C4, and CS;
therefore,
autoload vectors for C2 through CS are unnecessary.
You can eliminate the unnecessary auto load vectors by placing the
autoload indicator only at the points where explicit loading is
required, as follows:
AFCTR:
BFCTR::
CFCTR:

.ROOT CNTRL-(AFCTR,*BFCTR,CFCTR)
.FCTR AO-(*Al,A2-*(A21,A22))
.FCTR (BO-(Bl,B2))
.FCTR *Cl-C2-C3-C4-C5
.END

With this ODL description, the Task Builder generates
vectors -- for Al, A21, A22, BO, Bl, 82, and Cl.

S.1.4

seven

autoload

Autoloadable Data Segments

You can make overlay segments that contain no executable code
autoloadable,
as follows.
First, you must include· a .NAME directive
and specify the GBL attribute, as described in Section 4.4.4.
For
example:

.ROOT A-*(B,C)
.NAME BNAME ,GBL
.FCTR BNAME-BFIL
.END

The global symbol BNAME is created and entered into the symbol table
of segment BNAME. Since this segment is marked to be autoloaded, root
segment A calls segment BNAME as follows:
CALL BNAME

S-5

OVERLAY LOADING METHODS
The segment is autoloaded and
occurs.

immediate

return

inline

code

The data of BFIL must be placed in a program section with the data
attribute to suppress the creation of autoload vectors.

5.2

(D)

MANUAL LOAD

If you decide to use the manual load method to load segments, you must
include
in your program explicit calls to the $LOAD routine.
These
load requests must supply the name of the segment to be loaded.
In
addition,
they
can
include
information necessary to perform
asynchronous load requests, and to handle load request failures.
The $LOAD routine does not path load.
A call to $LOAD loads only the
segment named in the request.
The segment is read in from disk and
mapped regardless of its previous status.
A MACR0-11 programmer calls the $LOAD routine directly.
A
programmer calls $LOAD using the FORTRAN subroutine MNLOAD.

FORTRAN

MACR0-11 Manual Load Calling Sequence

5.2.1

A MACR0-11 programmer calls $LOAD as follows:
MOV
CALL

#PBLK,RO
$LOAD

PBLK is the address of a parameter block with the following format:
PBLK:

.BYTE
.RAD50
.WORD
.WORD

length, event-flag
/seg-name/
[i/o-status]
[ast-trp]

length
The length of the parameter block

(3 to 5 words).

event-flag
The event flag number, used for
asynchronous loading.
If the event-flag number is O, synchronous loading is
performed.
seg-name
The name of the segment to be loaded:
a
6-character Radix-50 name, occupying twd words.

i/o-status
The address of the I/O status doubleword.
status codes apply.

Standard QIO

ast-trp
The address of an asynchronous trap service routine to
which control
is transferred at the completion of the
load request.
The condition code C-list is set or cleared on return, as follows:
•

If condition code C=O, the load request was accepted.

•

If condition code C=l, the load request was unsuccessful.
5-6

OVERLAY LOADING METHODS
For a synchronous load request, the return of the condition code C=O
means that the desired segment is loaded and is ready to be executed.
For an asynchronous load request, the return of the code C=O means
that the load
request was successfully queued to the device driver,
but the segment is not necessarily in memory.
Your program "must
ensure that loading has been completed, by waiting for the specified
event flag before calling any routines or accessing any data
in the
segment.

5.2o2

FORTRAN Manual Load Calling Sequence

To use the manual load mechanism in a FORTRAN program,
your program
must refer
to
the $LOAD routine by means of the MNLOAD subroutine.
The subroutine call has the form:
CALL MNLOAD(seg-name[,event-flag] [,i/o-status] [,ast-trp] [,ld-ind])
seg--name
A 2-word real variable containing the segment
Radix-SO format.

name

event-flag
An optional integer event flag
number used
for
an
asynchronous load request.
If the event flag number is
O, the load request is synchronous.
i/o--status
An optional 2-word integer array containing the I/O
status doubleword,
as described for the QIO directive
in the RSX-llM/M-PLUS Executive Reference Manual.
ast-·trp
An optional asynchronous trap subroutine entered at the
completion of a
request.
MNLOAD
requires that all
pending traps specify the same subroutine.
ld-i. nd
An optional integer variable containing the results of
the subroutine call.
One of the following values is
returned:
+l

Request was successfully executed.

-1

Request had bad parameters or was not
executed.

You can omit optional arguments.

successfully

The following calls are legal:

Call

Effect

CALL MN LOAD ( SEGAl)

Load segment named
synchronously.

CALL MNLOAD (SEGAl,O,,,LDIND)

Load segment named in SEGAl
synchronously
and
return
success indicator to LDIND.

5-7

SEGAl

OVERLAY LOADING METHODS

Call

Effect

CALL MNLOAD (SEGAl,l,IOSTAT,ASTSUB,LDIND)
Load segment named in SEGAl
asynchronously,
transferring
control
to
ASTSUB
upon
completion
of
the
load
request;
store the I/O Status
doubleword in IOSTAT, and the
success indicator in LDIND.
The following example uses the program CNTRL, previously discussed in
Section 5.1. In this example, there is sufficient processing between
the calls to the overlay segments to make asynchronous loading
effective.
The
autoload indicators are removed from the ODL
description and the FORTRAN programs are recompiled with explicit
calls to the MNLOAD subroutine, as follows:
PROGRAM CNTRL
EXTERNAL ASTSUB
DATA SEGAl /6RA1
DATA SEGA21 /6RA21

/
/

CALL MNLOAD (SEGAl,l,IOSTAT,ASTSUB,LDIND)

CALL Al

CALL MNLOAD (SEGA21,l,IOSTAT,ASTSUB,LDIND)

CALL A21

END
SUBROUTINE ASTSUB
DIMENSION IOSTAT(2)

END
When the AST trap routine
is used,
the I/O status
automatically supplied to the dummy variable IOSTAT.

5.3

doubleword

ERROR HANDLING

If you select the manual load method, you must provide error handling
routines that diagnose load errors and provide appropriate recovery.
If you use the autoload mechanism,
a simple recovery procedure is
provided that checks the Directive Status Word (DSW) for an error
indication.
If the DSW indicates that no system dynamic storage
is

5-8

OVERLAY LOADING METHODS
available,
the
routine issues a Wait for Significant Event directive
and tries again;
if the problem is not dynamic storage, the
recovery
procedure generates a
synchronous breakpoint trap.
If the task
services the trap and
returns without altering the state of the
program, the request will be retried.
A more comprehensive user-written error recovery subroutine can ·be
substituted
for
the
system-provided routine
if the following
conventions are observed:
1.

The error recovery routine must have
$ALERR.

the

entry

point

The contents of all registers must be saved and restored.

name

On entry to $ALERR, R2 contains the address of the segment descriptor
that could not be loaded.
Before recovery action can be taken, the
routine must determine the cause of the error by examining the
following words in the sequence indicated:

5.4

$DSW

The Directive Status Word may contain an error
status
code,
indicating
that
the Executive
rejected the I/O
request to load the overlay
segment.

N.OVPT

The contents of this location, offset by N.IOST,
point to a 2-word I/O status block containing the
results of the load overlay request returned by
the device driver.
The status code occupies the
low-order byte of word
O.
For example,
for
a
device not ready condition,
the code will be
IE .DNR.
(For more
information on these codes
refer to the IAS/RSX-11 I/O Operations Reference
Manual.)

GLOBAI. CROSS-REFERENCE OF AN OVERLAID TASK

This section illustrates a global cross-reference that has been
created for
an overlaid task.
The task consists of a root segment
containing the module ROOT.OBJ, and two overlay segments composed of
modules OVRl
and OVR2.
The overlay description of the file is as
follows:
.ROOT

ROOT-(OVR1,*0VR2)

Only segment OVR2 is autoloadable.
cross-reference listing.

Figure

5-4

shows

the

resulting

As shown, the global symbol OVRl is defined in module OVRl,
and a
single nonautolaodable,
up-tree
reference is made to this symbol by
the module ROOT, as indicated b the circumflex.
Note that segment
OVRl cannot be evaded because of the restriction against mixing manual
load and autoload in the same task.

5-9

OVERLAY LOADING METHODS

OVRTST

CREATED BY

TKB

ON l-OCT-76 AT 12:04

GLOBAL CROSS REFERENCE

CREF

SYMBOL

VALUE

REFERENCES •••

N.ALER
N. I OST
N.MRKS
N .OVLY
N.OVPT
N .RDSG
N.STBL
N.SZSG
OVRl
OVR2
ROOT
$ALBP1
$ALBP2
$ALERR
$AUTO
$DSW
$MARKS
$OTSV
$SAVRG
$VEXT
• FSRPT
.NALER
.N IOST
.NMRKS
.NOV LY
.NOVPT
• NRDSG
.NSTBL
.NSZSG

000010
000004
000016
000000
000054
000014
000002
000012
002014-R
002014-R
001176-R
001320-R
001416-R
001246-R
001302-R
000046
001546-R
000052
001452-R
0 00 0 56
000050
001442-R
001436-R
001450-R
001432-R
000042
001446-R
001434-R
001444-R

AUTO
OVCTL
# OVRES
OVCTL
AUTO
# OVRES
# OVRES
# OVRES
# OVRl
* OVR2
0 ROOT
# AUTO
# AUTO
# ALERR
# AUTO
ALERR
# OVCTL
# VCTDF
AUTO
# VCTDF
# VCTDF
# OVDAT
# OVDAT
# OVDAT
# OVDAT
# OVDAT
# OVDAT
# OVDAT
# OVDAT

OVRTST

CREATED BY

# OVRES

OVCTL ·

# VCTDF

ROOT
@ ROOT

OVDAT

# VCTDF
# SAVRG

TKB

ON l-OCT-76 AT 12:04

PAGE 2
CREF

SEGMENT NAME

RESIDENT MODULES

OVRl
OVR2
ROOT

OVRl
OVR2
ALERR
VCTDF

AUTO

VOl

# OVRES
# OVRES

SEGMENT CROSS REFERENCE

Figure 5-4

PAGE 1

OVCTL

CV DAT

OVRES

ROOT

VOl

SAVRG

Sample Overlaid Cross-Reference Listing

As shown, the global symbol OVRl is defined in module OVRl, and a
single nonautoloadable,
up-tree reference is made to this symbol by
the module ROOT, as indicated by the circumflex.
Note that segment
OVRl cannot be evaded because of the restriction against mixing manual
load and autoload in the same task.

5-10

OVERLAY LOADING METHODS
The asterisk preceding the module OVR2
indicates that the global
symbol OVR2
is an autoload symbol and is referenced from the module
ROOT through an autoload vector,
as shown by the at sign
(@)
character.
Down-tree references to the global symbol ROOT are made
OVRl and OVR2. These references are resolved directly.

from

modules

The segment cross-reference shows the segment name and modules in each
overlay.

5-11

CHAPTER 6
SWITCHES AND OPTIONS

You use switches and options to control the construction of your task
image.
This chapter provides detailed reference information on all
the Task Builder switches and options.

6.1

SWITCHES

The syntax for a file specification, as given in Chapter 1, is:
dev: [group,member]filename.type;version/swl/sw2 ••• /swn
Optionally, you can conclude a file specification with one or more
switches (swl,sw2, ••• swn). When you do not specify a switch, the Task
Builder establishes a default setting for it.
You designate a switch by a 2- to 4-character code preceded by a slash
(/).
If you precede the 2- to 4-character code with a minus sign (-)
or the letters NO, the Task Builder negates the function of the two
characters.
For example, the Task Builder recognizes the following
settings for the switch CP (checkpointable):
The task is checkpointable
The task is not checkpointable
The task is not checkpointable

/CP
/-CP
/NOCP

In some cases, two particular switches cannot both be used in a file
specification.
When &Jch a conflict occurs, the Task Builder selects
the overriding switch according to the following table:
Switch

Switch

Overriding Switch

AC (Ancillary Control
Processor)

PR (Privileged)

EA (Extended Arithmetic
Element)

FP (Floating Point
Processor)

CC (Concatenated object
file)

LB (Library file)

For example:
MCR>TKB IMGS=IN6,INS/LB/CC
The Task Builder assumes that the input file INS is a library file.
It searches the file for undefined global references. It does not
include in the task image all of the modules in INS.

6-1

SWITCHES AND OPTIONS
The switches that the Task Builder recognizes
are
given
in
alphabetical order
in Table 6-1. Sections 6.1.1 through 6.1.31 give
detailed descriptions of each switch,
in
alphabetical
order,
including:
•

The switch format

•

The file(s)

•

A description of the effect of the switch on the Task Builder

•

The default assumption made if the switch is not present

to which the switch can be applied

Table 6-1
Task Builder Switches

Format

Meaning

Applies
to File

Default

AC [: n]

Task is an ancillary control processor

.TSK

-AC

Task can be checkpointed to space
allocated in the task image file

.TSK

-AL

Input file consists of concatenated
object modules

.OBJ

Memory-resident overlays are aligned
on 256-word physical boundaries

.TSK

-CM

Task is checkpointable

.TSK

-CP

A global cross-reference listing
is appended to the memory allocation
file

.MAP

-CR

Task contains a debugging aid

• TSK,
.OBJ

-DA

Specified library file is a replacement for the system object
module library

.OLB

-DL

Task uses extended arithmetic
element

.TSK

-EA

Task uses the floating-point
processor

.TSK

-FP

1 The default is /MA for an
resident library .STB files.

input

file, and

/-MA

for

system

and

The default for the memory management switch is /MM if the host
system has memory management hardware and /-MM if the host system
does not have memory management hardware.
(continued on next page)

6-2

SWITCHES AND OPTIONS
Table 6-1 (Cont.)
Task Builder Switches

Format

Applies
to File

Meaning

Default

All cotree overlay segments are
searched for matching definition or
reference when modules from the default object module library are
being processed

.TSK

-FU

Task image includes a header

• TSK,
.STB

Input file is a library file

.OLB

-LB

Map file includes information
from the file

.MAP,
.TSK

MA or -MAl

System has memory management

.TSK

MM or -MM2

Input file contains an overlay
description

.ODL

-MP

Task is a multiuser task

.TSK

-MU

Task is position independent

• TSK,
.STB

-PI

Postmortem Dump is requested

.TSK

-PM

PR[:n]

Task has privileged access rights

.TSK

-PR

Memory-resident overlay operator
(!) is enabled

.TSK

Messages can be directed to the
task by means of the Executive
SEND directive

.TSK

Short memory allocation file is
requested

.MAP

Task is slaved to an initiating
task

.TSK

-SL

Spool map output

.MAP

Task program sections are
allocated sequentially

.TSK

-SQ

Selective Search for global
symbols

.OBJ

-SS

Task is to be traced

.TSK

-TR

Memory allocation file is printed
at a width of 132 characters

.MAP

XT[:n]

Task Builder exits after n
diagnostics

.TSK

-XT

6-3

SWITCHES AND OPTIONS

This page left blank intentionally

6-4

SWITCHES AND OPTIONS

AC
6.1.1

/AC[:n] -- Ancillary Control Processor

File

Task image
Syntax

file.TSK/AC:O=file.OBJ
or
file.TSK/AC:4=file.OBJ
or
file.TSK/AC:5=file.OBJ
Description

Your task is an ancillary control processor;
that is,
it is a
privileged task that extends certain Executive functions.
For
example, the system task FllACP is an ancillary control processor
that receives and processes FILES-11 related input and output
requests on behalf of the Executive.
Effect

Your task is privileged. The Task Builder sets the AC attribute
flag and the privileged attribute flag in your task's label block
flag word.
The value of n is an octal number that specifies the first KT-11
Active Page Register that you want the Executive to use to map
your task's image when your task is running in user mode.
Legal
values are O, 4, and 5.
If you do not specify n, the Task
Builder assumes a value of 5.
If you do not explicitly specify that your task is to run on a
mapped system (through the MM switch) and it is not otherwise
implied (the Task Builder is not running in a system with KT-11
hardware), the Task Builder merely tests the value of the switch
for validity, but otherwise ignores it.
Default

/-AC
NOTE
You should not use /AC and
same command line.

6-5

/PR

the

SWITCHES AND OPTIONS

AL
6.1.2

/AL -- Allocate Checkpoint Space

File
Task image

Syntax
file.TSK/AL=file.OBJ

Description
Your task is checkpointable.
The system will
space in your task's image file.

checkpoint

Effect
Your task
is checkpointable.
This switch directs the Task
BuiLder
to allocate additional space in your task image file to
contain the checkpointed task image.

Default
/-AL
NOTE
It does not make sense to use
/AL in the same command line.

6-6

/CP

and

SWITCHES AND OPTIONS

cc
6.1.3

/CC -- Concatenated Object Modules

File

Input
Syntax

file.TSK=file.OBJ/-CC
Description

This switch controls the way the Task
from your input file.

Builder

extracts

modules

Effect

By default, the Task Builder includes in your task image all the
modules of your input file.
If you negate this switch (as in the
"Syntax" section above), the Task Builder includes only the first
module of your input file.
Default

/CC

6-7

SWITCHES AND OPTIONS

CM
6.1.4

/CM -- Compatibility Mode Overlay Structure

File

Task image
Syntax

file.TSK/CM=file.OBJ
Description

Your task will be built in compatibility mode.
Effect

The Task Builder aligns memory-resident overlay segments on
256-word boundaries for compatibility with other implementations
of the mapping directives.
Default

/-CM

6-8

SWITCHES AND OPTIONS

CP
6.1.5

/CP -- Checkpointable

File
Task image
Syntax
file.TSK/CP=file.OBJ
Description
Your task is checkpointable. The system will checkpoint it to ·
space that you have allocated in the system checkpoint file on
the system disk. This switch assumes that you have allocated the
checkpoint space through the MCR command ACS.
(Refer to the
RSX-llM/M-PLUS MCR Operations Manual.)
Effect
The system writes your task to the system checkpoint file on
secondary storage when its physical memory is required by a task
of higher priority.
Default
/-CP
NOTE
It does not make sense to use
/AL in the same command line.

6-9

/CP

and

SWITCHES AND OPTIONS

CR
/CR -- Cross-Reference

6.1.6

File
Memory allocation (map)

Syntax
file.TSK,file.MAP/CR=file.OBJ

Description
This switch determines whether or not a cross
is added to your map file.

reference

listing

Effect
The Task Builder creates a special work
file
(file.CRF)
which
contains segment,
module,
and global symbol information.
The
Task Builder then calls the cross reference processor
(CRF)
to
process the file.
CRF creates a cross reference listing from the
information contained in the file,
and then deletes file.CRF.
(Refer
to
Appendix
D, RSX-11 Utilities Manual
for more
information on CRF.
The cross-reference listing and its contents are described in the
"Example" section below.
NOTE
In order for
this
switch
to
be
effective, CRF must be installed in your
system.

Default
/-CR

Example
Figure 6-1 shows a cross reference listing for
task OVR.
The
numbers
in the following text correspond to the circled numbers
in the listing •

•
•

The cross-reference page header gives the name of the memory
allocati-0n file,
the originating task (TKB), the date and
time
the memory allocation file was created,
and
the
cross-reference page number •
The cross-reference list contains an alphabetic listing of
each global symbol along with its value and the name of each
referencing module.
When a
symbol
is defined in several
segments within an overlay structure, the last defined value
is printed. Similarly, if a module is loaded
in several
segments within the structure,
the module name will be
displayed more than once within each entry.

6-10

SWITCHES AND OPTIONS
The suffix -R is appended to
relocatable.

the

value

the

symbol

Pref ix symbols accompanying each module name define the
of reference as follows:

is
type

Pref ix Symbol

Reference Type

blank

Module contains a reference that
is resolved
in the same segment or in a segment toward the
root.
Module contains a reference that is
resolved
directly in a segment away from the root or in
a co-tree.

•
OVR

Module contains a reference that
through an autoload vector.

Module contains a non-autoloadable definition.

Module contains an autoloadable definition.

resolved

The segment cross-reference lists the name of each overlay
segment and the modules that compose it.
If the task is a
single segment task, this section does not appear.
CREATED BY

TKB

ON ll-APR-79 AT 09:27

SYMBOL

VA.LUE

REFERENCES •••

AADD
ANS
DIVV
IO .WVB
MULL
PRINT
SAVAL
SUBB
$EDMSG

034700-R
007232-R
050724-R
011000
034700-R
014274-R
02:0366-R
050724-R
001272

* ADDOV
PRNOV
* DIVOV
PRNOV
* MULOV
# PRNOV
AD DOV
@ ROOTM
PRNOV

CREATED BY

VO~

@ ROOTM

# ROOTM
@ ROOTM
@ ROOTM

ROOTM
DIVOV
* SUBOV

TKB

MULOV

# SAVOV

ON ll-APR-79 AT 09:27

SUBOV

SEGMENT NJl,ME

RESIDENT MODULES

AD DOV
DIVOV
MULOV
ROOTM
SUBOV

AD DOV
DIVOV
MULOV
PRNOV
SUBOV

ROOTM

SAVOV

Cross Reference Listing for OVR.TSK

6-11

•

PAGE 2
CREF

SEGMENT CROSS REFERENCE

Figure 6-1

PAGE
CREF

GLOBAL CROSS REFERENCE

OVR

VOl

•

SWITCHES AND OPTIONS

DA
6.1.7

/DA -- Debugging Aid

File

Task image or input
Syntax

file.TSK/DA=file.OBJ
or
file.TSK=file.OBJ,file.OBJ/DA
Description

Your task
execution.

includes

debugging

aid

that

will

control

its

Effect

If you apply this switch to your task
Builder
automatically
includes
the
LBO:[l,l]ODT.OBJ into your task image.

the Task
image file,
system debugging aid

The Task Builder causes control to be passed
program when task execution is initiated.

the

debugging

If you apply this switch to one of your input files,
the Task
Builder assumes that the file is a debugging aid that you have
written. Such debugging programs can trace a task, printing out
relevant debugging information, or monitor the task's performance
for analysis.
In either case, /DA has the following effects on your task image:
•

The transfer address of the debugging aid
task transfer address.

overrides

the

•

The Task Builder initializes the header of your task so
that, on initial task load, registers RO through R4
contain the following values:
RO - Transfer address of task
Rl - Task name in Radix-SO format (word #1)
R2 - Task name (word #2)
R3 - The first three of six RADSO characters representing
the version number of your task. The Task Builder
derives this number from the first .IDENT directive
it encounters in your task. If no .IDENT directive
is in your task, this value will be O.
R4 - The second three RADSO characters
version number of your task.

Default

/-DA

6-12

representing

the

SWITCHES AND OPTIONS

DL
6.1.8

/DL -- Default Library

File
Input
Syntax
file.TSK=file.OBJ,file.OLB/DL
Description
Your input file is a replacement for
library.

the

system

object

module

Effect
The library file you have
specified
replaces
the
file
LBO:[l,l]SYSLIB.OLB as the library file that the Task Builder
searches to resolve undefined global
references.
The default
device for the replacement file is SYO:. The Task Builder refers
to it only when undefined symbols remain after it has processed
all the files you have specified.
You can apply the DL switch to
only one input file.
Default
/-DL

6-13

SWITCHES AND OPTIONS

EA
/EA -- Extended Arithmetic Element

6.1.9
File

Task image
Syntax

file.TSK/EA=file.OBJ
Description

Your task uses the KEll-A Extended Arithmetic Element.
Effect

The Task Builder allocates three words in your task's header
saving the state of the extended arithmetic element.
Default

/-EA
NOTE
You should not use /EA and
same command line.

6-14

/FP

the

for

SWITCHES AND OPTIONS

FP
6.1.10

/FP -- Floating Point

File
Task image

Syntax
file.TSK/FP=file.OBJ

Description
Your task uses the floating-point processor.

Effect
The Task Builder allocates 25 words in your
task's
saving the state of the floating-point processor.

Default
/-FP on RSX-llM systems
/FP on RSX-llM-PLUS systems
Notes
1.

You should not use /FP
the same command line.

In an RSX-llM system, the FP switch
will
be
effective only
if the
Floating
Executive supports
the
Point Processor.

In an RSX-llM system it a task
that
uses the Floating Point Processor is
built without the FP switch,
the
task will
run correctly until a
second task that uses the Floating
Point Processor
is run.
Then both
tasks will either crash or produce
incorrect
results.
For information
on changing the
Task
Builder's
defaults, refer to Appendix E.

6-15

and

/EA

header

for

SWITCHES AND OPTIONS

FU
6.1.11

/FU -- Full Search

File

Task image
Syntax

file.TSK/FU=file.ODL/MP
Description

This switch controls the Task Builder's search for undefined
symbols when it is processing modules from the default library.
Effect

When the Task Builder processes modules from the default object
module library, and it encounters undefined symbols within those
modules, it normally limits its search for definitions to the
root of the main tree and to the current tree. Thus, unintended
global references
between
co-tree
overlay
segments
are
eliminated.
When the FU switch is appended to the task image
file of an overlaid task, the Task Builder searches all co-tree
segments for a matching definition or reference.
Default

/-FU

6-16

SWITCHES AND OPTIONS

HD
6.1.12

/HD -- Header

File

Task image or symbol definition
Syntax

fileeTSK/-HD,,file.STB=file.OBJ
or
file.TSK,,file.STB/-HD=file.OBJ
Description

When negated this switch directs the Task Builder
header from your task image.

exclude

Effect

The Task Builder does not construct a header in your task image.
You use the negated form of this switch when you are building
commons, resident libraries, and loadable drivers.
Default

/HD

6-17

SWITCHES AND OPTIONS

LB
6.1.13

/LB -- Library File

File
Input
Syntax
file.TSK=file.OBJ,file.OLB/LB
or
file.TSK=file.OBJ,file.OLB/LB:mod-l:mod-2 ••• :mod-8
or
file.OBJ=file.OLB/LB:mod-l:mod-2,file.OLB/LB
Description
The file to which this switch is attached is an object module
library file.
The Task Builder's interpretation of this switch
depends upon the form you use. There are three forms:
1.

Without arguments (the first syntax given above)

With arguments (the second syntax given above)

Both with and without arguments (the third syntax
above)

given

Effect
If you apply this switch without arguments, the Task Builder
assumes that your input file is a library file of relocatable
object modules. The Task Builder searches the file immediately
to resolve undefined references in any modules preceding the
library specification and extracts from the
library,
for
inclusion in the task image, any modules that contain definitions
for such references.
If you apply the switch with arguments, the Task Build~r extracts
from the library the modules named as arguments of the switch
regardless of whether or not the modules contain definitions for
unresolved references.
If you want the Task Builder to search an object module library
file both to resolve global references and to select named
modules for inclusion in your task image, you must name the
library file twice: once, with the modules you want included in
your task image listed as arguments of the LB switch;
and a
second time, with the LB switch and no arguments.
The position of the library file within the Task Builder
sequence is important. The following rules apply:
1.

command

The library file must follow to the right of the input
file(s)
that contain references to be defined in the
library. For example:
TKB>file.TSK=infilel.OBJ,lib.OLB/LB

6-18

SWITCHES AND OPTIONS

The command above illustrates the correct usage of the
LB switch;
the following command illustrates incorrect
usage:
TKB>file.TSK=lib.OLB/LB,filel.OBJ
2.

If you are using the Task Builder's multiple line input,
and you specify a given library more than once during
the command sequence, you must attach the LB switch to
the library file each time you specify the library. For
example:
>TKB
TKB>file.TSK=filel.OBJ,file2.0BJ,lib.OLB/LB
TKB>file3.0BJ,file4.0BJ,lib.OLB/LB
II

When you are building an overlay structure, the Task
Builder limits the number of input files you can specify
to 1.
Therefore, you must specify object
module
libraries for an overlay structure within the Overlay
Description Language (ODL} file for the structure.
To
do this, you must use the .FCTR directive to specify the
library. For example:
AFCTR:
BFCTR:
LIB:

.ROOT CNTRL-LIB(AFCTR,BFCTR,C)
.FCTR AO-LIB(Al,A2-(A21,A22))
.FCTR BO-LIB(Bl,B2)
.FCTR LB: [303,3]LIBOBJ.OLB/LB
.END

The technique used in the ODL file above allows you to
control the placement of object module library routines
into the segments of your overlay structure.
(For more
information on overlaid tasks, see Chapter 4.)
NOTES
1.

You should not use the LB switch
and the CC switch in the same
command sequence.

You can use the SS switch
in
conjunction
with the LB switch
(with or without arguments)
to
perform
a selective search for
global definitions.

Default
/-LB

6-19

SWITCHES AND OPTIONS

MA
6.1.14

/MA -- Map Contents of File

File
Input or memory allocation
Syntax
file.TSK,file.MAP=file.OBJ,file.OBJ/-MA
or
file.TSK,file.MAP/MA=file.OBJ
Description
The Task Builder is to include information from your
in the memory allocation output file.

input

file

Effect
If you negate this switch and apply it to an input file, the Task
Builder will exclude from the map and cross-reference listings
all global symbols defined or referred to in the file.
In
addition, the Task Builder will not list the file in the "file
contents" section of the map.
If you apply this switch to the map file, the Task Builder will
include in the map file the names of routines it has added to
your task from SYSLIB. It will also include in the map file
information contained in the symbol definition file of any shared
region referred to by the task.
Default
/MA for input files.
/-MA for system library and resident library STB files.

6-20

SWITCHES AND OPTIONS

MM
6.1.15

/MM -- Memory Management

File
Task image
Syntax
file.TSK/MM=file.OBJ
or
file.TSK/-MM=file.OBJ
Description
The system on which your task is to
hardware.

run

has

memory

management

Effect
The Task Builder can build a task image for a mapped or unmapped
system independently of the mapping status of the system on which
your task is being built. If you specify /-MM, the Task Builder
assumes an unmapped system.
Default
/MM or /-MM. When you do not apply /MM to your task image file,
the Task Builder allocates memory according to the mapping status
of the system on which your task is being built.
NOTE
When you negate this switch
(/-MM),
it
suppresses
the
Task
Builder's
recognition
of
the
memory-resident
overlay operator (!). The Task Builder
checks the operator for correct syntax
but it does not create any resident
overlay segments.

6-21

SWITCHES AND OPTIONS

MP
6.1.16

/MP -- Overlay Description

File

Input
Syntax

file.TSK=file.ODL/MP
Description

Your input file is an Overlay Description Language (ODL) file.
Effect

The Task Builder receives all the input file specifications from
this file.
It allocates virtual address space as directed by the
overlay description.
If you use the Task Builder's multiline
command format (see section 1.3), the Task Builder automatically
requests option information at the console terminal by displaying
ENTER OPTIONS: •
NOTES
1.

If you use the multiline command
format when you specify an ODL file,
the
Task
Builder
automatically
prompts
for
option
input.
Therefore, you must not use the
single slash (/) to direct the Task
Builder to switch to option input
mode when you have specified /MP on
your input file.

When you specify /MP on the input
file for your task, it must be the
only input file that you specify.
Furthermore, the input file must
have a file type of .ODL.

Default

/-MP

6-22

SWITCHES AND OPTIONS

MU
6.1.17

/MU -- Multiuser

File
Input
Syntax
file.TSK/MU=file.OBJ
Description
Your task is a multiuser task.
Effect
The Task Builder separates your task's read-only and read/write
program sections. It then places the read-only program sections
in your task's upper virtual address space and the read/write
program sections in your task's lower virtual address space.
Default
/-MU

6-23

SWITCHES AND OPTIONS

Pl
6.1.18

/PI -- Position Independent

File
Task image or symbol definition

Syntax
file.TSK/PI=file.OBJ
or
file.TSK,,file.STB/PI=file.OBJ

Description
Your shared region contains
data.

only

position-independent

code

Effect
The Task
attribute
region.

Builder sets
flag
in the

the Position-Independent Code
(PIC)
label block flag word of your shared

Default
/-PI

6-24

SWITCHES AND OPTIONS

PM
6.1.19

/PM -- Postmortem Dump

File
Task image

Syntax
file.TSK/PM=file.OBJ

Description
If your task
terminates abnormally,
the
lists the contents of the memory image.,

system

automatically

flag

your

Effect
The Task Builder sets the Postmortem Dump
label flag word.
Notes

If your task issues an ABRT$
(abort
task} directive, the system will not
dump the task image even though the
Task Builder has set the Postmortem
Dump flag in your task's label flag
word.
In this case,
the system
assumes that a Postmortem Dump is
not necessary since you know why
your task was aborted.

The PMD utility must be installed in
your system and be able to get into
physical memory for this switch
to
be effective.

Default
/-PM

6-25

task's

SWITCHES AND OPTIONS

PR
6 .1. 20

/PR [: n] -- Privileged

File
Task image

Syntax
file.TSK/PR:O=file.OBJ
or
file.TSK/PR:4=file.OBJ
or
file.TSK/PR:5=file.OBJ

Description
Your task is privileged with respect to memory and device access
rights.
If you specify PR:O, your task does not have access to
the I/O page or the Executive.
However, if you specify PR:4 or
PR:5, your task does have access to the I/O page and the
Executive, in addition to its own partition.

Effect
The Task Builder sets the Privileged
task's label block flag word.

Attribute

flag

your

The value of n is an octal number that specifies the first Active
Page register that you want the Executive to use to map your task
image when your task is running in user mode.
Legal values are
O, 4, and 5. If you do not specify one of these values, the Task
Builder assumes a value of 5.
If you do not explicitly specify that your task is to
run on a
mapped system,
(through the MM switch) and it is not -Otherwise
implied (by the presence of KT-11 hardware on the system upon
which the Task Builder is running), the Task Builder merely tests
the value of the switch for validity, but otherwise
ignores it.
Privileged tasks are described in Chapter 2.

Default
/-PR
NOTE
You should not use /PR and
same command line.

6-26

/AC

the

SWITCHES AND OPTIONS

RO
6.1.21

/RO -- Resident Overlay

File
Task image

Syntax
file.TSK/-RO=file.ODL/MP

Descriptie>n
The Task Builder's recognition
operator (!) is enabled.

the

memory-resident

overlay

Effect
The memory-resident overlay operator (!),
when present
in the
overlay description file, indicates to the Task Builder that it
is to construct a
task
image that contains one or
more
memory-resident overlay segments.
If you negate this switch (as
in the "Syntax" section above),
the Task Builder checks the
operator for correct syntactical usage, but otherwise ignores it.
With the memory-resident overlay operator thus disabled, the Task
Builder
builds
a
disk-resident overlay from the overlay
description file.

Default
/RO

6-27

SWITCHES AND OPTIONS

SE
6.1.22

/SE -- Send

File
Task image
Syntax

file.TSK/-SE=file.OBJ
Description
This switch determines whether or not messages can be directed to
your task by means of the Executive Send directive.
(Refer to
the RSX-llM/M-PLUS Executive Reference Manual for information on
the Send directive)
Effect
By default, messages can be directed to your task by means of the
Executive Send directive. If you negate this switch (as in the
"Syntax" section above), the system inhibits the queuing of
messages to your task.
Default
/SE

6-28

SWITCHES AND OPTIONS

SH
6.1.23

/SH -- Short Map

FilE~

Memory allocation (map)

Syntax
file.TSK,file.MAP/-SH=file.OBJ
Desc~ription

The Task Builder
allocation file.

produces

the

short

version

the

memory

Efh~ct

The Task Builder does not produce the "file contents" section
the memory allocation file.

Default
/SH

Example
The memory allocation file consists of the following items:
1.

Page Header

Task Attributes Section

Overlay Description (if applicable)

Root Segment Allocation

Tree Segment Description (if applicable)

Undefined References

Task Builder Statistics

(if applicable)

An example of the memory allocation file (map) is shown in Figure 6-2.
The numbered and
lettered items in the notes following the figure
correspond to the numbers and letters in Figure 6-2.

6-29

SWITCHES AND OPTIONS
OVR.TSK;25

MEMORY ALLOCATION MAP TKB M36
13-APR-79
09:10

PAGE 1

TASK
NAME
• G) fh'\
PARTITION NAME ; GEN~
IDENTIFICATION : 01 \EJ
TASK UIC
: [303,3J@)
TASK PRIORITY
STACK
LIMITS: 000176 001175 001000 00512.(D
ODT XFR ADDRESS:{])
PRG XFR ADDRESS: 010010(6)
TASK ATTRIBUTES:G)
TOTAL ADDRESS WINDOWS: l.(D
MAPPED
ARRAY
TASK
EXTENSION
:
TASK
IMAGE SIZE
: 10496. WORDS@)
TOTAL TASK SIZE
:C!V
TASK ADDRESS LIMITS: 000000 050753@)
R-W DISK BLK LIMITS: 000002 000106 000105 00069.@
R-0 DISK BLK LIMITS:@)

PAGE HEADER

:G)

:CE)

TASK ATTRIBUTES
SECTION

OVR.TSK;25 OVERLAY DESCRIPTION:
BASE

TOP

000000
020700
020700
0347 24
034724

020677
034'23
034723
050747
050753

OVR .TSK; 25
ROOTM

LENGTH
020700
014024
014024
014024
014030

08640.
06164.
06164.
06164.
06168.

OVERLAY
DESCRIPTION

ROOTM
MULOV
AD DOV
SUBOV
DIVOV

PAGE 2

MEMORY ALLOCATION MAP TKB M36
13-APR-79
09:10

***ROOT SEGMENT: ROOTMG)
R/W MEM LIMITS: 000000 020677 020700 08640.@
DISK BLK LIMITS: 000002 000022 000021 00017.(S}
MEMORY ALLOCATION SYNOPSIS:
TITLE

SECTION

!DENT

FILE

ROOTM.OBJ; l@

:··;~~:~ (RW I I ,LCL ,REL ,CON) 001176 002034 01052 .@____ _
ANS

: (RW,D,GBL,REL,OVR) 003232 004006 02054.
003232 004006 02054.

ROOTM

A ROOT SEGMENT
W ALLOCATION

GLOBAL SYMBOLS:
AADD
ANS

007276-R
007232-R

DIVV
MULL

007316-R
007266-R

PRINT
SAVAL

014274-R
020366-R

SUBB

007306-R(D

FILE: ROOTM.OBJ;l TITLE: ROOTM
!DENT: Ol{Q)
<ANS
>: 003232 091.237 004006 02054.(E)
ANS
007232-R\.l)
<MAIN >: 010010 010105 000076 00062.Q)

************
UNDEFINED REFERENCES:(D

Figure 6-2 Memory Allocation File (Map) Example

6-30

SWITCHES AND OPTIONS
OVR .TSK; 25
MULOV

MEMORY ALLOCATION MAP TKB M36
13-APR-79
09:10

PAGE 4

*** SEGMENT: MULOV
R/W MEM LIMITS: 020700 034723 014024 06164.
DISK BLK LIMITS: 000023 000037 000015 00013.
MEMO~Y

ALLOC.l\TION SYNOPSIS:

SEC'rION

TITLE

!DENT

FILE

, BLK.:(RW,I,LCL,REL,CON) 020700 000000 00000.
MULL
:(RO,I,GBL,REL,CON) 020700 014024 06164.
020700 014024 06164.

MULOV

MULOV.OBJ;l

~TREE

SEGMENT

~ DESCRIPTION

GLOBAL SYMBOLS:
MULi:.

0 34 700-R
MULOV.OBJ;l TITLE: MULOV
!DENT: 01
<MULL >: 020700 034723 014024 06164.
MULL
034700-R

FILI~:

* ** .~ ** * * * * * *
UNDEFINED REFERENCES:

*** TASK BUH.DER STATISTICS:
TOTAL WOHK FILE REFERENCES: 8178.@
WORK Fil:.E READS: O.}fb\
WORK FILE WRITES: O. ~
SIZE OF CORE POOL: 8200. WORDS (32. PAGES)(D
SIZE OF WORK FILE: 3328. WORDS (13. PAGES)@)
ELAPSED TIME: 00: 00: 28

A
\:I

TASK BUILDER
STATISTICS

Figure 6-2(Cont.) Memory Allocation File (Map) Example

6-31

SWITCHES AND OPTIONS

Notes to Figure 6-2:

The Page Reader shows the name of the task image file and the
overlay segment name (if applicable), along with the date, time,
and version of the Task Builder that created the map.
The Task Attribute Section contains the following information:
Task Name -- The name specified in the TASK option. If you do
not use the TASK option, the Task Builder suppresses this
field.
Partition Name -- The partition specified in the PAR option.
If you do not specify a partition, the default is partition
GEN.
Identification -- The task version as specified in the .!DENT
assembler
directive.
If you do not specify the task
identification, the default is 01.
Task UIC -- The task UIC as specified in the UIC option.
If
you do not specify the UIC, the default is the terminal UIC.
Task Priority -- The priority of the task as specified in the
PRI option. If you do not specify PRI, the default is 50.
Stack Limits
The low and high octal addresses of the stack,
followed by its length in octal and decimal bytes.
ODT Transfer Address -- the starting address of the ODT
debugging aid.
If you do not specify the ODT debugging aid,
this field is suppressed.
Program Transfer Address -- The address
of
the
symbol
specified in the .END directive of the source code of your
task. If you do not specify a transfer address for your task,
the Task Builder automatically establishes a tranfer address
of 000001 for it. The Task Builder also suppresses this field
in the map if you do not specify a transfer address.
Task Attributes -- These attributes are listed only if they
differ from the defaults. One or more of the following may be
displayed:
AC

Ancillary control processor

Task is checkpointable, and task image file contains
checkpoint space allocation

Task is checkpointable, and task image file will
checkpointed to system checkpoint file

Task contains debugging aid

Task uses KEll-A extended arithmetic element

Task uses floating-point processor

-HD

Task image does not contain header

Task contains position-independent code and data

Postmortem Dump requested in the event
task termination

6-32

abnormal

SWITCHES AND OPTIONS

Task is privileged

-SE

Messages addressed to the task through the
directive will be rejected by the Executive

Task can be slaved

Task initial PS word has T-bit enabled

SEND

Total Address Windows -- the number of window blocks allocated
to the task.
Mapped Array -- the amount of physical memory (decimal words)
allocated through the VSECT option or Mapped Array Declaration
(GSD type 7, described in Section B.1.8 of Appendix B).
Task Extension -- the increment of physical memory
words) allocated through the EXTTSK or PAR option.

(decimal

Task Image Size -- the amount of memory
(decimal words)
required to contain your task's code. This number does not
include physical memory allocated through the EXTTSK option.
Total Task Size -- the amount
words)
allocated
including
extension area.

(decimal
of physical memory
mapped array area and task

Task Address Limits -- the lowest
and
highest
addresses
allocated
to the task, exclusive of
addresses allocated to VSECTs and shared regions.

virtual
virtual

Read/Write Disk Block Limits -- from left to right:
the first
octal relative disk block number of the task's header;
the
last octal relative disk block number of the task image;
the
total contiguous disk blocks required to accommodate the
read/write portion of the task image in octal and decimal.
Read-Only Disk Block Limits -- from left to right:
the first
© octal
relative disk block of the multiuser task's read-only
region;
the last octal relative disk block number of the
read-only region;
the total contiguous disk blocks required
to accommodate the read-only region in octal and decimal.
This field appears only when you are building a multiuser
task.
The Overlay Description shows, for each overlay segment in the
tree structure of an overlaid task, the beginning virtual address
(the base), the highest virtual address (the top), the length of
the segment in octal and decimal bytes, and the segment name.
Indenting is used to illustrate the ascending levels in the
overlay
structure.
The
Task
Builder prints the Overlay
Description only when an overlaid task is created.
The Root Segment
elements:

Allocation -- This

section

has

the

following

Root Segment -- The name of the root segment. If your task is
a single-segment task, the entire task is considered to be the
root segment.
Rec1d/Write Memory Limits -- From left to right:
the beginning
virtual address of the root segment (the base), the virtual
address of the last byte in the segment (the top), the length
of the segment in octal and decimal bytes.

6-33

SWITCHES AND OPTIONS

Disk Block Limits -- From left to right:
the first relative
block number of the beginning of the root segment, the last
relative block number of the root segment,
total number of
disk blocks in octal, and the total number of disk blocks in
decimal.
Memory Allocation Synopsis -- From left to right:
the program
section name, the program section attributes, starting virtual
address of the program section, total length of the program
section in octal and decimal bytes.
The program section shown as • BLK.
in this field is the
unnamed relocatable program section. Notice in this example
that there are 636(8) bytes allocated to it (2034 bytes - 1176
bytes= 636 bytes). This allocation is the result of calls to
routines that reside within the unnamed program section in
SYSLIB.
(For more information, see the description of the MA
switch in Section 6.1.14.)
Module contributor -- This field lists the modules that have
contributed to each program section. In this example, the
program section ANS was defined in module ROOTM.
The module
version is 01 (as a result of the .!DENT assembler directive)
and the file name from which the module was extracted is
ROOTM.OBJ;l.
If the program section ANS had been defined in
more than one module, each contributing module and the file
from which it was extracted would have been listed here.
NOTE
The absolute section, • ABS.
is not
shown because it appears in every module
and always has a length of O.
The global symbols section lists the global symbols defined in
the segment.
Each symbol is listed along with its octal
value. A -R is appended to th value if the symbol is
relocatable. The list is alphabetized in columns.
The file contents section (which is composed of the four fields listed
below) is printed only if you specify /-SH in the Task Builder command
sequence. The Task Builder creates this section for each segment in
an overlay structure. It lists the following information:
Input file -- File name, module name as established by the
.TITLE assembler directive, module version as established by
the .!DENT assembler directive.
Program section -- Program section name, starting virtual
address of the program section, ending virtual address of the
program section, length in octal and decimal bytes.
Global symbol -- Global symbol names within each program
section
and
their
octal values.
If the segment is
autoloadable (see Chapter 5), this value will be the address
of an autoload vector.
The autoload vector in turn will
contain the actual address of the symbol.
An -R is appended to the value if the symbol is relocatable.

6-34

SWITCHES AND OPTIONS

Program section -- This field
described in note g above.

identical

the

field

Undefined References -- This field lists the undefined global
symbols in the segment.
The Tree Segment Description is printed for every overlay segment
in an overlay structure.
Its contents are the same for each
overlay segment as the Root Segment Allocation is for the root
segment.
Task Builder Statistics lists the following information, which can
be used to evaluate Task Builder performance:
Work File References -- The number of times that
Builder accessed data stored in its work file.

the

Task

(§)

Work File Reads -- The number of times that
device was accessed to read work file data.

the

work

file

Work File Writes -- The number of times that
device was accessed to write work file data.

the

work

file

available

for

@ s i~~e of Pool -- The amount of memory that

was

work file data and table storage.

Size of Work File -- The amount of
required to contain the work file.

device

storage

that

was

Elapsed Time -- The amount of wall-clock time required to
construct the task image and produce the memory allocation
(map) file. Elapsed time is measured from the completion of
option input to the completion of map output. This value
excludes the time require to process the overlay description,
parse
the
list
of input file names, and create the
cross-reference listing (if specified).
See Appendix E for a more detailed discussion of the work file.

6-35

SWITCHES AND OPTIONS

SL
6.1.24

/SL -- Slave

File

Task image
Syntax

file.TSK/SL=file.OBJ
Description

Your task is slaved to an initiating task.
Effect

The Task Builder attaches the slave attribute to your task. When
your task successfully executes a Receive Data directive, the
system gives the UIC and TI: device of the sending task to it.
The slave task then assumes the indentity and privileges of the
sending task.
This switch only applies to you if your system has multiuser
protection.
(Refer to your system generation manual for more
information on multiuser protection and slave tasks.)
Default

/-SL

6-36

SWITCHES AND OPTIONS

SP
6.1.25

/SP -- Spool Map Output

File
Memory allocation (map)

Syntax
file.TSK,file.MAP/-SP=file.OBJ

Description
This switch determines whether or not the Task Builder calls the
print spooler to spool your memory allocation (map) file after
task build.

Effect
By de!fault, when you specify a map file in a Task Builder command
sequence, the Task Builder creates a map file on device SYO:
and
then has the file queued for listing on LPO:.
If you negate this switch
(as shown in the
"syntax"
section
above!),
the Task Builder will create the map file on device SYO:
but will not call the print spooler to output it to LPO:

Default
/SP

6-37

SWITCHES AND OPTIONS

SQ
6.1.26

/SQ -- Sequential

File

Task image
Syntax

file.TSK/SQ=file.OBJ
Description

The Task Builder constructs your task image from the program
sections you specified, in the order that you input them.
Effect

The Task Builder does not reorder
the
program
sections
alphabetically.
Instead, it collects all the references to a
given program section from your input object modules, groups them
according
to their access code and, within these groups,
allocates memory for them in the order that you input them.
You use this switch to satisfy any adjacency requirements that
existing code may have when you are converting it to run under
RSX-11. Use of this feature is otherwise discouraged for the
following reasons:
I/O handling
will not work

•

Standard library routines (such as FORTRAN
routines and FCS modules from SYSLIB)
properly.

•

Sequential allocation can result in errors if
the order in which modules are linked.

you

alter

Alternatively, you can achieve physical adjacency of program
sections by selecting names alphabetically to correspond to the
desired order.
Default

/-SQ

6-38

SWITCHES AND OPTIONS

SS
6.1.27

/SS -- Selective Search

File

Input
Syntax
fileuTSK=file.OBJ,file.OBJ/SS
or
fileuTSK=file.OBJ,file.STB/SS
or
fileuTSK=file.OBJ,file.OLB/LB/SS
Deficription
The SS switch directs the Task Builder to include into its
internal symbol table only those global symbols for which there
is a previously undefined reference.
Effect
When processing an input file, the Task Builder normally includes
into its internal symbol table each global symbol it encounters
within the file whether or not there are references to it.
When
you attach the SS switch to an input file, the Task Builder
checks each global symbol it encounters within that file against
its list of undefined references. If the Task Builder finds a
match, it includes the symbol into its symbol table.
Dej:ault
/-SS
E>cample
Assume that you are building a task named SEL.TSK. The task is
composed of input files containing global entry points and
references (calls) to them as shown in Table 6-2.
Table 6-2 Input Files for SEL.TSK
Input
File Name

Global Definition

INl

Global Reference
A

IN2

IN3
IN4

6-39

SWITCHES AND OPTIONS
File IN2 and IN4 contain global symbols of the same name that
represent
entry points to different routines within their
respective files.
Assume that you want the Task Builder to
resolve the reference to global symbol A in INl to the definition
for A in IN2. Assume further, that you want the Task Builder to
resolve the reference to global symbol C in IN3 to the definition
for C in IN4.
By selecting the sequence of the
input files
properly and applying the SS switch to files IN2 and IN4, the
Task Builder will
resolve
the
references correctly without
conflict.
The following command sequence illustrates the correct
sequence:
TKB>SEL.TSK-IN1.0BJ,IN2.0BJ/SS,IN3.0BJ,IN4.0BJ/SS
The Task Builder processes
input files
from left to
right,
therefore,
in processing the above command sequence, the Task
Builder processes file INl first and encounters the reference to
symbol A.
There is no definition for A within INl, therefore,
the Task Builder marks A as undefined and moves on to process
file IN2.
Because the SS switch is attached to IN2, the Task
Builder limits its search of IN2 to symbols
it has previously
listed as undefined,
in this case, symbol A.
The Task Builder
finds a definition for A and places A in its symbol table.
There
are no undefined
references to symbols B or C, so the Task
Builder does not place either of these symbols
in its symbol
table.
NOTE
It is important to realize that the SS
switch effects only the way the Task
Builder constructs its
internal symbol
table.
The routines for which symbols B
and C are entry points will be
included
in the task image even though there are
no references to them.
The Task Builder moves on to IN3.
It encounters the
references
to symbol c.
Since the Task Builder did not include symbol C
from IN2 in its symbol table, it cannot resolve the reference to
C in IN3. The Task Builder marks symbol C as undefined and moves
on to IN4.
When the Task Builder processes IN4 it encounters the definition
for C in that file and includes it in the table. Again, since
the SS switch is attached to IN4, the Task Builder includes only
C in its symbol table.
When the Task Builder has completed its processing of
the above
command sequence, it has constructed a task image composed of all
of the code from all of the modules, INl through IN4.
However,
only symbols A from IN2 and C from IN4 will appear in its
internal symbol table.
NOTE
The example above does not represent
good
programming
practice.
It is
included here to illustrate the effect
of the SS switch on the Task Builder
during a search sequence.

6-40

SWITCHES AND OPTIONS
The SS switch is particularly valuable when used to
limit the
size of the Task Builder's internal symbol table during the
building of a privileged task that
references the Executive's
routines and data structures.
By specifying the Executive's
Symbol Definition File (STB) as an input file and applying the SS
switch to
it,
the Task Builder will include into its internal
symbol table only those symbols in the Executive that the task
references.
An example of a Task Builder command sequence that
illustrates this is shown below:
TKB>OUTFILE.TSK/PR:S=INFILE.OBJ,RSXllM.STB/SS
The above command sequence directs the Task Builder
to build a
privileged task named OUTFILE.TSK from the input file INFILE.OBJ.
The specification of the Executive's STB file as an input file
with the SS switch applied to it directs Task Builder to extract
from RSXllM.STB only those symbols for which there are references
within OUTFILE.TSK.

6-41

SWITCHES AND OPTIONS

TR
6.1.28

/TR - Traceable

File
Task image
Syntax
f ile.TSK/TR=f ile.OBJ
Description
Your task is traceable.
Effect
The Task Builder sets the T-bit in the initial PS word of your
task.
When your task
is executed, a trace trap occurs on the
completion of each instruction.
Default
/-TR

6-42

SWITCHES AND OPTIONS

WI
6.1.29

/WI -- Wide Listing Format

File
Memory allocation (map)

Syntax
file.TSK,file.MAP/-WI=file.OBJ

Description
This switch controls the width of your map file.

Effect
By default, the Task Builder formats a map file 132 columns wide.
When you negate this switch (as in the "Syntax" section above),
the Task Builder formats the map file 80 columns wide.

Default
/WI

6-43

SWITCHES AND OPTIONS

XT
6.1.30

/XT[:n] -- Exit on Diagnostic

File
Task image
Syntax
file.TSK/XT:4=file.OBJ
Description
More than n errors are not acceptable.
Effect
The Task Builder exits after encountering n errors.
The number
of errors can be specified as a decimal or octal number, using
the convention:

indicates a decimal number
included).

#n or n

indicates an octal number.

(the decimal point

must

If you do not specify n, the Task Builder assumes that n is 1.
Default
/-XT

6-44

SWITCHES AND OPTIONS

6.2

OPTIONS

Task Builder options provide you with the means to give
Builder information about the characteristics of your task.

the

Task

These options which are listed in Table 6-2 can be divided into seven
categories.
The identifying abbreviation and a brief description of
each category are listed below:
l.

contr

You use control options to affect Task Builder
execution.
ABORT is the only member of this
category. You can direct the Task Builder to
abort the task-build with this option.

ident

You use identification options to identify your
task's characteristics. You can specify the name
of your task, its priority, user identification
code, and partition with options in this category.

alloc

You use allocation options to modify your task's
memory allocation.
With the options in this
category, you can change the size of your task's
stack
and program sections.
When you write
programs in a high-level language, you can change
the size of your work areas and buffers and
declare the virtual base address and size of
program sections.
Finally, you can declare the
number of additional window blocks (if any)
that
your task requires.

You use storage sharing options to indicate to the
Task Builder that your task intends to access a
shared region.

device

You use device specifying options to specify the
number of units required by your task, and the
assignment of logical unit numbers to physical
devices.

alter

You use the content altering options to define a
global 3ymbol and value, or to introduce patches
in your task image.

synch

You use synchronous trap
synchronous trap vectors.

options

define

Some Task Builder options are of interest to all users of the system;
others are of interest only to high-level language programmers; and
still others are of interest only to MACR0-11 programmers. Table 6-3
lists all the options alphabetically, and gives a brief description of
each.

6-45

SWITCHES AND OPTIONS
Table 6-3
Task Builder Options
Meaning

Interest 1

Category

PAH

Declares partition name and
dimensions

H,M

ident

PRJC

Declares priority

H,M

ident

RESCOM
RES LIB

Declare task's intention to access
a memory-resident shared region

H,M

REssup2

Declares task's intention to access a
resident supervisor-mode library

H,M

ROPAR2

Declares partition in which read-only
portion of multiuser task is to reside

H,M

ident

STJ\CK

Declares the size of the stack

H,M

alloc

SUPLIB2

Declares task's intention to access a
system-owned supervisor-mode library

H,M

TASK

Declares the name of the task

H,M

ident

TSKV

Declares the address of the task
SST vector

synch

UIC

Declares the user identification code
under which the task runs

H,M

ident

UNITS

Declares the maximum number of units

H,M

device

VSECT

Declares the virtual base address and
size of a program section

H,M

alloc

WNDWS

Declares the number of additional
address windows required by the task.

H,M

alloc

The user interest range is indicated as follows:
high-level

language

•

H indicates options of interest
(such as FORTRAN) programmers

•

M indicates options of interest to MACR0-11 programmers

These options are applicable to RSX-llM-PLUS systems only.

6-47

SWITCHES AND OPTIONS

ABORT
ABORT -- Abort the Task-Build

6.2.1

You use the ABORT option when you discover that an earlier error in
the terminal sequence will cause the Task Builder to produce an
unusable task image.
The Task Builder, on recognizing the keyword
input and restarts for another task-build.

ABORT,

stops

accepting

Syntax

ABORT=n
n

An integer value. The integer is required to satisfy the general
form of an option; however, the value is ignored in this case.
Default

none
NOTE
If you type a CTRL/Z at any time it will
cause the Task Builder to stop accepting
input and begin building the task.
The ABORT option is the only proper way
for you to restart the Task Builder if
you discover an error and decide you do
not want the Task Builder output.

6-48

SWITCHES AND OPTIONS

ABSPAT
ABSPAT -- Absolute Patch

6.2.2

You use the ABSPAT option to declare a series of object level
patches
starting at a specified base address.
You can specify up to 8 patch
values.

Syntax
ABSPAT=seg-name:address:vall:val2 ••• :va18
seg-name
The 1- to 6-character Radix-SO name of the segment.
address
The octal address of the first patch.
The address can be on a
byte boundary;
however, two bytes are always modified for each
patch:
the addressed byte and the following byte.
vall
An oct~l number in the range of 0 through 177777 to be stored
address.

An octal number in the range of 0 through 177777 to be stored
address+2

An octal number in the range of 0 through 177777 to be stored
address 14.

val2

val8

NOTE
All patches must be within the segment
address limits or the Task Builder will
generate the following error message:

Tl<B--*DIAG*--LOAD ADDRESS OUT OF RANGE IN module name

6-49

SWITCHES AND OPTIONS

ACTFIL
ACTFIL -- Number of Active Files

6.2.3

You use the ACTFIL option to declare the number of files that your
task can have open simultaneously.
For each active file that you
specify, the Task Builder allocates approximately 512 bytes.
If you specify less than four active files (the default), the ACTFIL
option saves space.
If you want your task to have more than four
active files, you must use the ACTFIL option to make the additional
allocation.
You must include an Object Time System (OTS) and record I/O service
routines
(FCS or RMS-11) in your task image for the extension to take
place. The program section that is extended has the reserved name
$$FSR1.
Syntax
ACTFIL=f ile-max
file-max
A decimal integer indicating the maximum number of files that can
be open at the same time.
Default
ACTFIL=4

6-50

SWITCHES AND OPTIONS

ASG
ASG -- Device Assignment

6.2.4

The ASG option declares the physical device that is assigned to one or
more logical units.

Syntax
ASG=device-name:unit-numl:unit-num2 ••• :unit-num8
device-name
A 2-character alphabetic device name followed by a 1- or
decimal unit number.
unit-numl
unit-num2

unit-num8
Decimal integers indicating the logical unit numbers.

ASG=SY0:1:2:3:4,TIO:S,CL0:6

6-51

2-digit

SWITCHES AND OPTIONS

CMPRT
6.2.5

CMPRT -- Completion Routine

The CMPRT option is available on RSX-llM-PLUS systems only.
You use
this option to identify a task as a supervisor-mode library. It also
identifies the entry point of the completion routine that the library
will use to return control to your program in user mode.
You should define your completion routine in the root segment of your
supervisor-mode library.
When your library is an overlay structure
with a root of O, the completion routine must appear in all of the
main branches of the overlay structure nearest to the root. The
completion routine also must have the same virtual address in all
branches.
When you specify a completion routine that does not appear in your
code, the Task Builder expects to find the routine in the System
Library (SYSLIB) on device LB: under UFD [1,1]. When it extracts the
completion routine from the System Library, the Task Builder places
the routine in the root of your task. This means that if you build an
overlaid supervisor-mode library with a root of O, the Task Builder
will expand the root to accommodate the completion routine.
Syntax
CMPRT=name
name
A 1- to 6-character
routine.

Radix-50

name

Default
none

6-52

identifying

the

completion

SWITCHES AND OPTIONS

COMMON
LIBR
6. 2. 6

COMMON or LIBR -- System-Owned Resident Common or
Resident Library

System-Owned

The COMMON and LIBR options are
functionally
identical;
they
both
declare that your task intends to access a system-owned shared region.
However, by convention, the COMMON option is used to identify a shared
region
that contains only data,
and
the LIBR option is used to
identify a shared region that contains only code.
The term "system-owned" means that the Task Builder expects
to find
the common or library named in the keyword and the symbol definition
file associated with it under UFD [1,1] on device LB:.
Syntax

COMMON=name:access-code[:apr]
or
LIBR=name:access-code[:apr]
name
The 1- to 6-character Radix-50 name
specifying the common or
library.
The Task Builder expects to find a symbol definition
file having the same name as
the common or
library with an
extension of .STB under [l,l] of device LB:.
access-code
The code RW (read/write) or the code RO
the type of access the task requires.

(read-only)

indicating

NOTE
A privileged task can issue QIOs to a
resident common even though the task has
been linked to the common with read-only
access.
apr
An integer in the range of l through 7 that specifies
the
first
Active Page Register
(APR)
that you want the Task Builder to
reserve for the shared region.
The Task Builder
recognizes
the
APR only
for
a mapped system,
you can specify it only for
position-independent shared
regions.
If you omit
the
APR
parameter and the shared region is position independent, the Task
Builder will select the highest available APR to map the
region.
When a shared region is absolute, the base address of the region,
and therefore, the APR the maps it,
is determined by the PAR
option when the region is built.
Refer to PAR in Section 6.2.17.
Default

None

6-53

SWITCHES AND OPTIONS

EXTSCT
6.2.7

EXTSCT -- Program Section Extension

You use the EXTSCT option to extend a program section.
If the program section to be extended has the attribute
CON
(concatenated), the Task Builder extends the section by the number of
bytes you specify in the EXTSCT option. If the program section has
the attribute OVR (overlay), the Task Builder will extend the section
only if the length you specify in the EXTSCT option is greater than
the length of the program section.
Syntax

EXTSCT=p-sect-name:extension
p-sect-name
A 1- to 6-character radix-SO name specifying the program
to be extended.

saction

extension
An octal integer that specifies the number of bytes by
extend the program section.

which

Example

In the following example, the program section BUFF is
long.

200

bytes

EXTSCT=BUFF:250
The number of bytes the Task Builder extends the program
BUFF depends on the CON/OVR attribute:
•

For CON, the extension is 250 bytes

•

For OVR, the extension is 50 bytes

section

The Task Builder will extend the program section if it encounters
the program section name in an input object file or in the
overlay description file.
Default

None

6-54

SWITCHES AND OPTIONS

EXTTSK
6.2.8

EXTTSK -- Extend Task Memory

You use the EXTTSK option to dlrect the system to allocate additional
memory for your task when it is installed in a system-controlled
partition.
The amount of memory that the system allocates for your task is the
sum of the task size plus the increment you specify (rounded up to the
nearest 32-word boundary). If the task is built for a user-controlled
partition, the allocation of task memory reverts to the partition
size.
In an unmapped system, the Task Builder ignores the EXTTSK keyword.
NOTES
1.

You should not use the
EXTTSK
option to extend a task containing
memory resident overlays because
the
system
will
not map the
extended area.

When you use the EXTTSK option to
extend a checkpointable task that
has been declared checkpointable
with the AL switch, the check point
file within the task image will be
the size of the task plus the size
of the extended task area.

Syntax
EXTTSK=length
length
A decimal number specifying
allocation (in words).

the

increase

task

memory

Default

The task is extended to the size
(Section 6.2.17).

6-55

specified

the

PAR

option

SWITCHES AND OPTIONS

FMTBUF
FMTBUF -- Format Buffer Size

6.2.9

You use the FMTBUF option to declare the length of
the
internal
wor~ing storage that you want the Task Builder to allocate within your
task for the compilation of format
specifications at
runtime.
The
length of
this area must equal or exceed the number of bytes in the
longest format string to be processed.
Run-time compilation occurs whenever an array is referred to as
the
The
source of formatting information within a FORTRAN I/O statement.
name
program section that the Task Builder extends has
the
reserved
$$0BF1.

Syntax
FMTBUF=max-format
max-format
A decimal integer, larger than the default,
that specifies
number of characters in the longest format specification.

Default
FMTBUF=l32

6-56

the

SWITCHES AND OPTIONS

GBLDEF
6.2.10

GBLDEF -- Global Symbol Definition

You use the GBLDEF option
symbol.

declare

the

definition

global

The Task Builder considers this symbol definition to be absolute.
overrides any definition in your input object modules.

Syntax
GBLDEF=symbol-name:symbol-value
symbol-name
A 1- to 6-character Radix-SO name of the defined symbol.
symbol-value
An octal number in the range of 0 through 177777 assigned to
defined symbol.
Default
None

6-57

the

SWITCHES AND OPTIONS

GBLPAT
6.2.11

GBLPAT -- Global Relative Patch

You use the GBLPAT option to declare a series of object level patch
values starting at an offset relative to a global symbol. You can
specify up to eight patch values.
Syntax
GBLPAT=seg-name:sym-name[+/-offset] :vall:val2 ••• :val8
seg-name
The 1- to 6-character Radix-50 name of the segment.
sym-name
A 1- to 6-character Radix-50 name specifying the global symbol.
offset
An octal number specifying the offset from the global symbol.
vall
An octal number in the range of 0 through 177777 to be stored
the octal address of the first patch.

An octal number in the range of 0 through 177777 to be stored
the first address+2.

An octal number in the range of 0 through 177777 to be stored
the first address+l4.

val2

val8

Default
None
NOTE
All patches must be within the segment
address limits or the Task Builder will
generate a fatal error.

6-58

SWITCHES AND OPTIONS

GBLREF
6.2.12

GBLREF -- Global Symbol Reference

You use the GBLREF option to declare a global symbol
reference.
The
reference originates in the root segment of the task.
This keyword is
used for memory-resident overlays of shared regions.

Syntax
GBLREF=symbol-name:symbol-name ••• :symbol-name
symbol-name
A 1- to 6-character name of a global symbol reference.

Default
None

6-59

SWITCHES AND OPTIONS

GBLXCL
6.2.13

GBLXCL -- Exclude Global Symbols

The GBLXCL option keyword directs the Task Builder to exclude from the
symbol definition file of a supervisor-mode library the symbol(s)
specified in the option.
It is important to exclude from the symbol definition file of
Supervisor-mode library a symbol that is defined in the library if:
1.

the symbol represents an entry point to a routine
the stack to pass parameters and,

that

the routine is called from the user-mode task linked
library.

uses
the

When the processor is switched from user to supervisor mode, two words
are pushed onto the stack. If a user-mode task is permitted to call a
routine in supervisor-mode that uses the stack to pass parameters, the
two words pushed onto the stack will not be anticipated by the routine
and both the called routine and the supervisor-mode completion routine
will fail.
(For more information on supervisor mode libraries, see
Chapter 3.)
Syntax

GBLXCL=symbol-name:symbol-name ••• :symbol-name
symbol-name
The symbol(s) to be excluded.
Default

None

6-60

SWITCHES AND OPTIONS

LIBR
6.2.14

LIBR -- System-Owned Library

Refer to COMMON in Section 6.2.6.

6-61

SWITCHES AND OPTIONS

MAXBUF
6.2.15

MAXBUF -- Maximum Record Buffer Size

You use the MAXBUF option to declare the maximum
required for any file used by the task.

record

buffer

If your task requires a maximum record size that exceeds the
buffer length, you must use this option to extend the buffer.

size

default

You must also include an Object Time System (OTS) in your task image
for the extension to take place. The program section that is extended
has the reserved name $$IOB1.
Syntax
MAXBUF=max-record
max-record
A decimal integer, larger than the default,
maximum record size in bytes.
Default
MAXBUF=l32

6-62

that

specifies

the

SWITCHES AND OPTIONS

ODTV
6.2.16

ODTV -- ODT SST Vector

You use the ODTV option to declare that a global symbol is the address
of the OD~r Synchronous System Trap vector. You must define the global
symbol in the main root segment of your task.
Syntax
ODTV=symbol-name:vector-length
symbol-name
A 1- to 6-character Radix-SO name of a global symbol.
vector-length
A decimal integer in the range of 1
length of the SST vector in words.
De1:ault
None

6-63

through

specifying

the

SWITCHES AND OPTIONS

PAR
6.2.17

PAR -- Partition

You use the PAR option to identify the partition for which
is built.

your

task

In a mapped system, you can install your task in any system partition
or user partition large enough to contain it. In an unmapped system,
your task is bound to physical memory. Therefore, you must install
your task in a partition starting at the same memory address as the
partition for which it was built.
Syntax

PAR=pname[:base:length]
pname
The name of the partition.
base
The octal byte address defining the start of the partition.
length
The octal number of bytes contained in the partition.
In a mapped system, a length of
partition.

implies

system-controlled

If the target system is mapped and you specify a partition length
that is greater than the length of your task, the Task Builder
will automatically extend the length of your task to match the
length of the partition. This procedure is equivalent to using
the EXTTSK keyword to increase the task memory.
If your task
size is greater than the partition size that you specify, TKB
will generate the following error message:
TKB--*DIAG*-TASK HAS ILLEGAL MEMORY LIMITS
If you do not specify the base and length, the Task Builder will try
to obtain that information from the system on which you are building
your task. If you have specified a partition that resides in that
system, the Task Builder can obtain the base and length.
The Task Builder binds the task to the addresses defined by the
partition base. If the partition is user-controlled, the Task Builder
verifies that the task does not exceed the length specification.
Default

PAR=GEN

6-64

SWITCHES AND OPTIONS

PRI
6.2.18

PRI -- Priority

You use the PR! option to declare your task's execution priority.
On systems with multiuser protection, you cannot run a task at a
priority that is greater than the system priority (SO) unless it is
installed or run from a privileged terminal. If you are working from
a privileged terminal, and you do not override this option by
specifying a different priority when you install your task, this
priority is used.
Syn.tax
PRI=priority-number
pr:iority-number
A decimal integer in the range of 1 through 250
DeJEault
Established by Install;
refer
Operations Reference Manual.

6-65

the

RSX-llM/M-PLUS

MCR

SWITCHES AND OPTIONS

RE SC OM
RESLIB
6.2.19

RESCOM or RESLIB -- Resident Common or Resident Library

The RESCOM and RESLIB options are functionally identical;
they both
declare that your task intends to access a user-owned shared region.
However, by convention the RESCOM option is used to identify a
shared
region that contains only data and the RESLIB option is used to
identify a shared region that contains only code.
The term "user-owned" means that the resident common or library and
the symbol definition file associated with it can reside under any UFD
that you choose.
You can specify the UFD and
remaining portions of
the file specification for both options.
You must not place comments
on the same line with either option.

Syntax
RESCOM=file-specification/access-code[:apr]
or
RESLIB=file-specification/access-code[:apr]
file-specification
The memory image file of the resident common or resident library.
The file specification format is discussed in Chapter 1.
access-code
The code RW (read/write) or the code RO
the type of access required by the task.

(read-only),

indicating

NOTE
A privileged task can issue QIOs to a
resident common even though the task has
been linked to the common with read-only
access.
apr
An integer in the range of 1 through 7 that specifies the first
Active Page Register
(APR)
that you want the Task Builder to
reserve for the common or library. The Task Builder recognizes
the APR argument only for a mapped system. You can specify it
only for position-independent shared regions.
If the
APR
parameter
is
omitted
and
the
shared
region
is
position-independent, the Task Builder will select the highest
available APR to map the region.
When a shared region is
absolute, the base address of the region, and therefore, the APR
that maps it, is determined by the PAR option when the region is
built.
Refer to PAR in Section 6.2.17. You can specify it only
for position-independent shared regions.

6-66

SWITCHES AND OPTIONS

NOTES
1.

The Task Builder expects to find a
symbol definition file having the
same name as the memory image file
but with a file version of .STB, on
the same device and under the same
UFD as the memory image file.

Regardless of the version number you
give in the file specification, the
Task Builder uses the latest version
of the .STB file.

Default
When you omit portions of the file-specification,
defaults apply:
•

UFD - taken from current terminal UIC

•

device - SYO:

•

file type -

•

file version - latest

.TSK

6-67

the

following

SWITCHES AND OPTIONS

RESLIB
6.2.20

RESLIB -- Resident Library

Refer to RESCOM in Section 6.2.19.

6-68

SWITCHES AND OPTIONS

RESS UP
6.2.21

RESSUP -- Resident Supervisor-Mode Library

You use the RESSUP option to declare that your task intends to access
a user-owned, supervisor-mode library. The term "user-owned" means
that the library and the symbol definition file associated with it can
reside under any UFD that you choose. You can specify the UFD and
remaining portions of the file specification.
You must not place
comments on the line with RESSUP.
Syntax

RESSUP=file-specification/[-]SV[:apr]
file-specification
The memory image file of the supervisor-mode library.
The file
specification
has
the standard RSX-llM/RSX-llM-PLUS format
discussed in Chapter 1.
/[-]SV
The code SV for supervisor vectors or -SV for no supervisor
vectors.
If you specify SV, the Task Builder replaces calls to
the supervisor-mode library within your task with
context
switching vectors. If you specify -SV, calls within your task to
the supervisor-mode library are resolved directly and you must
provide your own means for context switching.
NOTE
The elimination of supervisor vectors is
useful if the supervisor-mode library
contains threaded code.
apr
An integer in the range of 0 through 7 that specifies the first
Supervisor Active Page Register that you want the Task Builder to
reserve for your supervisor-mode library.
NOTES
1.

Regardless of the version number you
give in the file specification, the
Task Builder uses the latest version
of the .STB file.

6-69

SWITCHES AND OPTIONS

When the CMPRT and RESSUP options
sequence
appear
in
a
command
together, the CMPRT option must be
specified first.

Default

When you omit portions of the file specification,
defaults apply:
•

UFD - taken from the current terminal UIC

•

device - SYO:

file type - .TSK

•

file version - latest

6-70

the

following

SWITCHES AND OPTIONS

RO PAR
6.2o22

ROPAR -- Read-Only Partition -- RSX-llM-PLUS Only

You use this option to declare the partition in
portion of your multiuser task is to reside.

which

the

read-only

Syntax
ROPAR~parname

parname
The partition name in which your multiuser task is to reside.
Default
The partition
resides.

which

the

read/write

6-71

portion

the

task

SWITCHES AND OPTIONS

STACK
6.2.23

STACK -- Stack Size

You use the STACK option to declare the
required by your task.

maximum

size

the

stack

The stack is an area of memory that the MACR0-11 programmer uses for
temporary storage, subroutine calls, and synchronous trap service
linkage. The stack is referred to by hardware register 6 (SP, the
stack pointer).

Syntax
STACK=stack-size
stack-size
A decimal integer specifying the number of words required for the
stack.

Default
STACK=256

6-72

SWITCHES AND OPTIONS

SUPLIB
6.2.24

SUPLIB -- Supervisor-Mode Library -- RSX-llM-PLUS Only

You use this option to declare that your task intends to access a
system-owned, supervisor-mode library. The term "system-owned" means
that the Task Builder expects to find the supervisor-mode library and
the symbol definition file associated with it under UFD [1,1] on
device LB:.
Syntax

SUPLIB=name: [-] SV [: apr]
name
The 1- to 6-character Radix-50 name specifying the system-owned,
supervisor-mode library.
The Task Builder expects to find a
symbol definition file having the same name as the library with a
file version of .STB under [1,1] of device LB:.

: [-] sv
The code SV for supervisor vectors or -SV for no supervisor
vectors.
If you specify SV, the Task Builder replaces calls to
the supervisor-mode library within your task with
context
switching vectors.
If you specify -sv, calls within your task to
the supervisor-mode library all resolved directly and you must
provide your own means for context switching.

NOTE
The elimination of supervisor vectors is
useful if the supervisor-mode library
contains threaded code.

apr
An integer in the range of 0 through 7 that specifies the first
Supervisor Active Page Register that the Task Builder is to
reserve for the library.
NOTE
When the CMPRT and SUPLIB options appear
in a command sequence together, the
CMPRT option must be specified first.
Default

None

6-73

SWITCHES AND OPTIONS

TASK
6.2.25

TASK -- Task Name

You use the TASK option to give your task an installed name
from its task image name.

different

Syntax
TASK=task-name
task-name
A 1- to 6-character name identifying your task.
Default
The first six characters of the task image file name are used
identify the task when the task is installed.

6-74

SWITCHES ANb OPTIONS

TSKV
6.2.26

TSKV -- Task SST Vector

You use the TSKV option to declare that a global symbol is the address
of the task Synchronous System Trap (SST) vector. You must define the
global symbol in the main root segment of your task.
Syntax
TSKV=symbol-name:vector-length
symbol-name
A 1- to 6-character name of a global symbol.
vector-length
A decimal integer in the range of 1
length of the SST vector in words.
Default
None

6-75

through

specifying

the

SWITCHES AND OPTIONS

UIC
6.2.27

UIC -- User Identification Code

You use the UIC option to declare the User Identification Code
(UIC)
for your task when you run it with a time-based schedule request.
Syntax

UIC=[group,member]
group
An octal number in the range of 1 through 377, or a decimal
number in the range of 1 through 255. Decimal numbers must be
followed by a decimal point (.).
member
An octal number in the range of 1 through 377, or a decimal
number in the range of 1 through 255. Decimal numbers must be
followed by a decimal point (.).
Default

The UIC that the Task Builder
terminal UIC).

6-76

running

under

(normally

the

SWITCHES AND OPTIONS

UNITS
6.2.28

UNITS -- Logical Unit Usage

You use the UNITS option to declare the number of logical
are used by your task.

units

that

Syntax
UNITS=:max-uni ts
max-units
A decimal integer in the range of 0 through 250 specifying the
maximum number of logical units. Note that in mapped systems the
UNITS option creates tables that require
dynamic
memory.
Therefore, large arguments can exhaust dynamic memory.
(Refer to
the system generation manual for more information.)
Default
UNITS=:6

6-77

SWITCHES AND OPTIONS

VSECT
6.2.29

VSECT -- Virtual Program Section

You use the VSECT option to specify the virtual base address,
virtual
length,
and optionally,
the physical memory allocated to the named
program section.
Refer to Section 3.4 for more information on virtual
program sections.

Syntax
VSECT=p-sect-name:base:window[:physical-length]
p-sect-name
A 1- to 6-character program section name.
base
An octal value representing the virtual base address of the
program section in the range of 0 through 177777. If you use the
mapping directives the value you specify must be a multiple of
4K.
window
An octal value specifying the amount of virtual address space in
bytes allocated to the program section.
Base plus window must
not exceed 177777 (octal).
physical-length
An octal value specifying the minimum amount of physical memory
to be allocated to the section in units of 64-byte blocks.
The
Task Builder rounds this value up to the next 256-word limit.
This value,
when added to the task image size and any previous
allocation, must not cause the total to exceed 2048K bytes.
If
you do not specify a length, the Task Builder assumes a value of
0.

Default
Physical-length defaults to O.

6-78

SWITCHES AND OP'TIONS

WNDSW
6. 2 .. 30

WNDWS -- Number of Address Windows

The WNDWS option declares the number of address windows required by
the task in addition to those needed to map the task image, and any
mapped array or shared region. The number specified is equal to the
number of simultaneously mapped regions the task will use.
Syntax

WNDWS==n
n

An integer in the range 1 through 7 in an RSX-llM
through 15 in an RSX-llM-PLUS system.
Default

WNDWS==O

6-79

system

and

CHAPTER 7
HOST AND TARGET SYSTEMS

7.1

INTRODUCTION

You can build a task on one system (the host), and run it on another
(the
target).
For example,
your installation might consist of one
large computer system with mapping hardware,
and several
smaller
unmapped systems.
On the large system you could create and debug
tasks, and then transfer them to the smaller systems to run.
For example, if you are developing a task named TK3, using the default
partition of your host system, the Task Builder command could be:
>TKB TK3,TK3=SQ1,SQ2
When you are ready to move TK3 to a target system, you build it again,
indicating the mapping status of the target system, and naming the
partition in which the task is to reside:
>TKB
TKB>TK3/-MM,TK3=SQ1,SQ2
TKB>/
ENTER OPTIONS:
TKB>PAR=PART1:100000:40000
TKB>//
The resulting task image is
system.

ready

run

the

unmapped

You can transfer a task from the host system to the target
following these steps:

target

system

Build the task image specifying the partition in which the
task will
run.
If the target system is an unmapped system,
specify the partition's base address and size.

Ensure that any shared
regions
present in both systems.

If the target system and the host system do not have the same
mapping status,
set the Memory Management switch (/MM or
/-MM) to reflect the mapping status of the target system.

accessed

the

task

are

The task code must not use any hardware options (FPP, EIS, EAE,
etc.)
that are not present on the target system.
This is particularly
important if you are a FORTRAN user because FORTRAN tasks often use
mathematics
routines that are hardware dependent.
(Refer to the
IAS/RSX-11 FORTRAN IV Installation Guide and the IAS/RSX-11 FORTRAN IV
User's Guide for more information on FORTRAN requirements).

7-1

HOST AND TARGET SYSTEMS
7.2

EXAMPLE: TRANSFERING A TASK FROM A HOST TO A TARGET SYSTEM

In this section, the resident library LIB and the task that refers to
it MAIN (from Example 4, Chapter 3) are rebuilt to run on an unmapped
system. To save space, only the Task Builder command sequences are
shown.
Assuming that the target system has a partition within it named LIB,
only two changes need be made to the original command sequence that
builds the library:
1.

The negated memory management switch (/-MM) must be
to the image file specification

The partition base and length must be specified

attached

The modified command sequence is as follows:
TKB>LIB/-HD/PI/-MM,LIB/-WI,LIB=LIB
TKB> /
ENTER OPTIONS:
TKB> STACK=O
TKB> PAR= LIB: 136000: 20000
TKB> / /
If the target system does not contain a partition of the same name as
the shared
region you must change the name of the shared region to
match the name of an existing partition in the target system. This is
a requirement of RSX-llM;
on RSX-llM-PLUS systems it is not.
Assuming that the target system has a partition named GEN and that the
task MAIN
is to run in that partition in the target system, three
changes must be made to the command sequence that builds the task
MAIN:
1.

The negated memory management switch (/-MM) must be
to the task image file specific~tion

attached

The APR parameter of the RESLIB keyword must be eliminated

The partition in which the task
is to reside,
address, and length must be explicitly specified

its

base

The modified command sequence is as follows:
TKB>MAIN/-MM,MAIN/MA/-WI=MAIN
TKB>/
ENTER OPTIONS:
TKB>RESLIB=LIB/RO
TKB>PAR=GEN:30100:40000
TKB>//
Figure 7-1 shows the map file of the resident library LIB for an
unmapped system.
LIB is bound to the partition base specified by the
PAR keyword in the task-build command sequence. Note that the shared
region is declared position independent even though it is bound to the
partition base 136000. The position-independent declaration is not
necessary in this example because the referencing task MAIN does not
require the program section names within the library in order to refer
to
it.
However,
in applications
involving tasks that require the
program section names from the library, you must declare the library
position-independent so that the Task Builder will place the program
section names in the library's symbol definition file.

7-2

HOST AND TARGET SYSTEMS

L IB • '1' SK ; 5

MEMORY ALLOCATION MAP TKB M36
22-JAN-79
10:49

PAGE 1

PARTITION NAME : LIB
IDENTIFICATION : 01
TASK UIC
[303,3]
TASK ATTRIBUTES: -HD,PI
TOTAL ADDRESS WINDOWS: 1.
TASK
IMAGE SIZE
64. WORDS
TASK ADDRESS LIMITS: 136000 136163
R-W DISK BLK LIMITS: 000003 000003 000001 00001.

*** ROOT SEGMENT: LIB
R/W MEM LIMITS: 136000 136163 000164 00116.
DISK BLK LIMITS: 000002 000002 000001 00001.
MEMORY ALLOCATION SYNOPSIS:
SECTION

BLK.: (RW,I,LCL,REL,CON)
AADD :(RO,I,GBL,REL,CON)
DIVV

: (RO,I,GBL,REL,CON)

MULL

:(RO,I,GBL,REL,CON)

SAVAL :(RO,I,GBL,REL,CON)
SUBB

:(RO,I,GBL,REL,CON)

136000
136000
136000
136024
136024
136052
136052
136076
136076
136140
136140

000000 00000.
000024 00020.
000024 00020.
000026 00022.
000026 00022.
000024 00020.
000024· 00020.
000042 00034.
000042 00034.
000024 00020.
000024 00020.

TITLE

!DENT

FILE

LIB

LIB .OBJ; 2

LIB

LIB .OBJ; 2

LIB

LIB.OBJ;2

LIB

LIB.OBJ;2

LIB

LIB.OBJ;2

GLOBJl1L SYMBOLS:
AADD
DIVV

136000-R
136024-R

MULL
SAVAL

136052-R
136076-R

SUBB

136140-R

*** 'I'ASK BUILDER STATISTICS:
'I1 0TAL WORK FI LE REFERENCES:

WORK FILE READS:
WORK FILE WRITES:
SIZE OF CORE POOL:
SIZE OF WORD FILE:

3 76.
O.
O.
8200. WORDS (32. PAGES)
768. WORDS (3. PAGES)

ELAPSED TIME:00:00:05
Figure 7-1

Task Builder Map for LIB.TSK

Figure 7-2 shows the map file of the task MAIN for an unmapped system.
The task is bound to the partition base 30100 and linked to the shared
region LIB, which begins at 136000.

7-3

HOST AND TARGET SYSTEMS

MAIN.TSK;6

PAGE 1

MEMORY ALLOCATION MAP TKB M36
22-JAN-79
11:20

PARTITION NAME : GEN
IDENTIFICATION : 01
TASK UIC
[303,3]
STACK
LIMITS: 030312 031311 001000 00512.
PRG XFR ADDRESS: 031652
TOTAL ADDRESS WINDOWS: 2.
TASK IMAGE SIZE
1120 WORDS
TASK ADDRESS LIMITS: 030100 034313
R-W DISK BLK LIMITS: 000002 000006 000005 00005.

*** ROOT SEGMENT: MAIN
R/W MEM LIMITS: 030100 034313 004214 02188
DISK BLK LIMITS: 000002 000006 000005 00005.
MEMORY ALLOCATION SYNOPSIS:
SECTION

TITLE

• BLK.:(RW,I,LCL,REL,CON) 031312 002564 01396.
031312 000530 00344. MAIN

!DENT

FILE

MAIN.OBJ;l

GLOBAL SYMBOLS:
AADD
136000-R
DIVV
136024-R
I 0. WVB 011000
MULL
136052-R

SAVAL 136076-R
SUBB
136140-R
$CBDAT 033060-R
$CBDMG 033066-R

$CBDSG
$CBOMG
$CBOSG
$CBTA

033074-R
033102-R
0 33110-R
033140-R

$CBTMG 033116-R
$CBVER 033102-R
$CDDMG 033276-R
$CDTB 033424-R

*** TASK BUILDER STATISTICS:
TOTAL WORK FILE REFERENCES: 2518.
WORK FILE READS: O.
WORK FILE WRITES: O.
SIZE OF CORE POOL: 8200. WORDS (32. PAGES)
SIZE OF WORK FILE: 1024. WORDS (4~ PAGES)
ELAPSED TIME:00:00:08
Figure 7-2

Task Builder Map for MAIN.TSK

7-4

CHAPTER 8
MEMORY DUMPS

The RSX-llM/M-PLUS Postmortem Dump task
(PMD)
generates Postmortem
memory dumps of tasks that are abnormally terminated.
In addition,
PMD can produce edited dumps, called Snapshot Dumps,
for
tasks
that
are
running.
Section 8.1 describes Postmortem Dumps in general;
Section 8.2 di~cusses the specific case of Snapshot dumps.
Both types
of dump are very useful debugging aids.

8.1

POSTMORTEM DUMPS

You can make a task eligible for a Postmortem Dump
ways:

any

three

At task-build time, by specifying the PM switch for the task
file.
/-PM disables dumps;
it is the default condition.

When you install a task by using the PMD switch to override
/PMD=NO
the taskbuild option.
/PMD=YES enables dumping;
disables dumping.

When you use the MCR command ABORT
(described
in the
RSX-llM/M-PLUS MCR Operations Manual), by including the PMD
switch in the command line to specify a dump.

You should install PMD in a 4K partition in which all other tasks are
checkpointable.
This allows the dump to be generated in a timely
manne!r, and prevents the system from being locked up while the dump is
being generated.
PMD can dump either from memory or from the
checkpoint image of your task.
The PMD is sensitive to
the
location
of
the aborted task;
therefore, if the aborted task is checkpointed
during the dump, PMD switches to reading the chec~point
image.
Once
the task is checkpointed,
PMD locks it out of memory until it has
completed formatting the dump.
Dumps are always generated on the system disk under UFD
[1,4];
therefore,
to avoid errors from PMD, you must create a UFD for [1,4]
before installing the task.
When PMD finishes generating the dump, it
attempts to queue the dump to the print spooler for subsequent
printing.
If no spooler is installed, the dump file is left on the
disk and can be printed at a later time using the Peripheral
Interchange Program (PIP;
described
in Chapter
4 of the RSX-11
Utilities Manual).

8-1

MEMORY DUMPS
NOTE
Dump files tend to be somewhat large.
The dump of an SK partition averages
about 340 blocks.
Therefore,
if there
is little space on the disk,
it is
important to print and delete the dump
file without delay.
The print spooler
automatically deletes all files with the
type .PMD after printing them.
Figure 8-1 shows the contents of a Postmortem and Snapshot Dump;
the
notes that follow
the figure are keyed to figure and provide a
description of the dumps contents.
Snapshot Dumps ·are explained more
fully in Section 8.2.
POST-MORTEM DUMP
TASK: TT6

TIME: S-OCT-76 1S:06

PC: 000720

REGS:

RO - 00034S

Rl - 074400

R2 - 000120

R3 -

R4 - 000000

RS - 000000

SP - 000304

PS - 17 0000

IOT EXECUTION

TASK STATUS:

MSG AST DST -CHK HLT STP REM MCR

EVENT FLAG MASK FOR <1-16> 000001
CURRENT UIC:

DSW: 1. f)

[007 ,001)

PRIORITY: DEFAULT - 50.
LOAD DEVICE - DBO:

140130} e

RUNNING - SO.
LBN: 1,160034

I/O COUNT: O.

TI DEVICE - TT6:~

FLOATING POINT UNIT
STATUS - 000000
RO
Rl
R2
R3
R4
RS

000000
000000
000000
000000
000000
000000

LOGICAL UNITS
UNIT

DEVICE

1
2
3
4

DBO:
DBO:
DBO:
DBO:

FILE STATUS

OVERLAY SEGMENTS LOADED AND RESIDENT LIBRARIES MAPPED
STARTING RELATIVE BLOCK: 000002
STARTING RELATIVE BLOCK: 000004

BASE: 000000
BASE: 001454

}

LENGTH: 0014S4
LENGTH: 000264

TASK STACK
ADDRESS CONTENTS ASCII
000304 000045
%

Figure 8-1

Sample Postmortem Dump (Truncated)

8-2

MEMORY DUMPS

PARTITION: GEN
000000
000010
000020
000030
000040
000050
000060
000070
000100
000110
000120
000130
000140
000150
000160

000304
304 000
003401
001 007
000304
304 000
000000
000 000
000000
000 000
000000
000 000
000373
373 000
000000
000 000
000000
000 000
000000
000 000
067020
020 156
000020
020 000
170000
000 360
140130
130 300
000000
000 000

000162
162 000
003401
001 007
000000
000 000
000000
000 000
140162
162 300
000000
000 000
000000
000 000
074150
150 170
051646
246 123
051646
246 123
000000
000 000
000000
000 000
000720
320 001
000120
120 000
000000
000 000

VIRTUAL LIMITS: 000000 - 001777
000001
001 000
170017
017 360
000000
000 000
000000
000 000
074106
106 170
001104
104 002
000000
000 000
000004
004 000
000000
000 000
000000
000 000
001777
377 003
000600
200 001
000000
000 000
074400
000 171
000000
000 000

DUPLICATE THROUGH 000236

***

000240
00250
000260
00270
000300
000310
000320
000330
000340
000350
000360

000000
000 000
001454
054 003
000001
001 000
063014
014 146
001051
05.l 002
000000
000 000
000524
124 001
000000
000 000
131574
174 263
000000
000 000
001037
037 002

000000
000 000
000264
264 000
001612
212 003
131574
17 4 263
000001
001 000
000001
001 000
000000
000 000
000000
000 000
047123
123 116
016746
346 035
l 04377
377 210

I 06

A Q08!
ID
1AD3 AD3 8PQ E4!
1
D6
1
ID
1
I
OlZ SIO
Al

ol
p

r@ Fx
NT
D

Fk
SJX

D MON!
1
MON!

MON
MON
IQXP

Al
1
YW 03.!

&SI

I n

p
18P

IX BPFI
1
1

!01

SNP

I p p
E/I
Ix@ P
1
I

***

001110
110 002
000000
000 000
074360
360 170
000000
000 000
000045
045 000
000100
100 000
000000
000 000
000000
000 000
052120
120 124
177734
334 377
103456
056 207

Figure 8-1 (Cont.)

067426
026 157
000352
352 000
000000
000 000
000000
000 000
000001
001 000
000000
000 000
000000
000 000
051646
246 123
051646
246 123
000001
001 000
061404
004 143
007406
006 017
000000
000 000
000345
345 000
000000
000 000

000000
000 000
000000
000 000
003413
013 007
000000
000 000
050114
114 120
000304
304 000
000000
000 000
063014
014 146
052123
123 124
012746
346 025
005046
046 012

NX
H
TL

1,
4
AEC!
1
. 1
lPMD
3
1 f
M3
A
7 L361
1)
A AX D61
I
HT
I
!T
PMD!
1
1 ••• LUK MSX MS$!
1 3 SN
DlN 7T CTF!
f
1
MW U61 UYF AX81
1
A

vz SN

LP!

@ D 1

f I

PT ST!

& I

Sample Postmortem Dump (Truncated)

8-3

MEMORY DUMPS

Type of dump - Postmortem or Snapshot.
If it is
Dump, the dump identification is printed.

Snapshot

The name of the task being dumped, and the date and time
dump was generated.

the

The program counter at the time of the dump.
If
it
is a
Postmortem Dump, the reason the task was aborted is printed.

The general registers, stack pointer, and processor status at
the time of the dump.
The task status flags at the
time of
the dump.
See
description
of
ATL or TAL
in the RSX-llM/M-PLUS
Operations Manual for the meaning of the flags.

the
MCR

The task event flag mask word at the time of
the dump.
If
the dump
is a Snapshot Dump, the efn specified in the SNAP$
macro will be ON (see Section 8.2.2).
The task UIC and the current value of
word.

the

directive

status

The
task's priority and default
priority,
number
of
outstanding I/O
requests,
and the terminal from which the
task was initiated (TI:).

The task load device and the logical block
start of the task image on the device.

number

for

the

The floating-point
unit
(FPU)
registers
or
the extended
arithmetic element
(EAE) registers if the task is using one
of these hardware features.
If the task is not using the FPU
or EAE,
these
registers are not printed.
If the task uses
the FPU and does not speqify /FP on the task image
file,
or
if
it uses the EAE unit and has not specified the EA switch,
the registers are not printed.
If the machine you are
using
has both an FPU and an EAE, PMD assumes you are using the FPU
because it is the unit of choice for arithmetic computations.
The logical unit assignments at the time of the dump.
UNIT
is the logical unit number, and DEVICE is the device to which
the logical unit is assigned.
For Snapshot Dumps,
the
file
names of any open files are displayed under FILE STATUS.
Postmortem Dumps do not display this information because all
of
the files have been closed as a result of the I/O rundown
on the aborted task.
The following are display~d:
the overlay segments loaded and
resident
libraries mapped at
the
time of the dump;
the
relative block number of the segment;
the base address;
the
length of the segment;
and, for tasks using manual load, the
segment names.
For resident libraries, the library name
is
also displayed.
The block number can be used to determine
which
segment
is loaded,
by reference
to
the
memory
allocation file generated by the Task Builder.
The starting
block number for each segment is the relative block number of
the
segment.
By obtaining a match, the name of the segment
in memory can be determined.
Zero
length segments are
usually co-tree roots.

8-4

MEMORY DUMPS
The task stack at the time of
the dump.
The address
is
displayed,
along with the contents,
in octal, ASCII, and
Radix-so.
Each word on the stack is dumped.
If the
stack
pointer is above the initial value of the stack (H.ISP), only
one word is dumped.
The rest is dumped as part of
the task
image.

41)

The task image itself.
The partition being dumped and
the
limits of interest are displayed.
For Postmortem Dumps, all
address windows in use are dumped.
For Snapshot Dumps,
the
virtual task limits that you request are displayed.
The dump
routine rounds the requested low limit down to the nearest
multiple of eight bytes and rounds the requested high limit
up to the nearest multiple of eight bytes.
The dump image
displays
the virtual starting address of a 4-word block of
memory, the data in both octal and Radix-SO on the
first
line,
and byte octal and ASCII on the second line.
A 4-word
block that is repeated in a contiguous region of memory
is
printed once, and then noted by the message

***

DUPLICATE THROUGH xxxxxx

***

where xxxxxx indicates the last word that is duplicated.
If
the
task was aborted, all address windows in use are dumped.
If the dump is a Snapshot Dump, up to four contiguous blocks
of memory can be dumped, if requested.

8.2

SNAPSHOT DUMP

Snapshot Dumps are edited dumps produced for running tasks.
You can
request a Snapshot Dump any number of times during the execuiion of a
task.
The
information generated is under the control of
the
programmer.
Snapshot Dumps are generated by the following macros:
•

SNPDf$ -- defines offsets in the Snapshot Dump Control Block,
and defines control bits, which control the format of the dump

•

SNPBK$ -- allocates the Snapshot Dump Control Block
8-1)

•

SNAP$ -- causes a Snapshot Dump to be generated

(see Table

SNPBK$ and SNAP$ issue calls to SNPDF$;
so, you need not explicitly
issue the SNPDF$ macro call.
Sections 8.2.l and 8.2.2 describe the
SNPBK$ macro and the SNAP$ macro, respectively.

8-S

MEMORY DUMPS

Label

Offset

SB.CTL

CONTROL FLAGS

SB.DEV

DEVICE MNEMONIC

SB.UNT

UNIT NUMBER

SB.EFN

EVENT FLAG

SB.ID

SNAP IDENTIFICATION

( L 1)

12
14

MEMORY BLOCK
LIMITS

(H 1)
(L2)

16
20

MEMORY BLOCK
LIMITS

(H2)
(L3)

22
24

MEMORY BLOCK
LIMITS

(H3)
(L4)

26
30

MEMORY BLOCK
LIMITS

(H4)

SB. LM1

SB.PMD

32
34

Figure 8-2

8e2.l

"PMD ... "
IN RADIX-50

Snapshot Dump Control Block Format

Format of the SNPBK$ Macro

The format of the SNPBK$ macro call is:
SNPBK$ dev,unit,ctl,efn,id,Ll,Hl,L2,H2,L3,H3,L4,H4
dev
The 2-character ASCII name of the device to which
the dump is
directed.
If it is a directory device, the UFD (1,4] ·must be on
the volume.
The dump is written to the disk and then spooled to
the line printer.
If there is no print spooler, the file is left
on the disk.
If the device is not a directory device,
the dump
goes directly to the device.
unit
The unit number of the device to which the dump is directad.
ctl
The set of flags that control the format of the dump and the data
to be printed.
The flags are:
SC.HOR

Print the dump header

SC.LUN

Print information on all assigned LUNs (item 11)

SC.OVL

Print information about all
( i tern 12)

SC.STK

Print the user stack

8-6

( i terns 1 to 10 in Figure 8-1)

loaded

(item 13)

overlay

segments

MEMORY DUMPS
SC.WRD

Print the requested memory in octal words and Radix-SO
( i tern 14)

SC.BYT

Print the requested memory in octal
( i tern 14)

bytes

and

ASCII

efn
The event flag to be used to synchronize your program and PMD.
id
A number that identifies the Snapshot Dump.
Because dumps can be
requested at different times and under different conditions, this
ID is used to identify the place or reason for the dump.
Ll,L2,L3,L4
The starting addresses of the memory blocks to be dumped.
Hl ,H2 ,H3 ,H·4
The ending addresses of the memory blocks to be dumped.
NOTE
If no memory is to be dumped, each limit
(Ll,L2,L3,L4,Hl,H2,H3,H4) should be O.
Only one Snapshot Dump Control Block is
global label •• SPBK.

allowed.

generates

the

NOTE
Because SNPBK$
is used
to
allocate
storage
for
the Snapshot Dump Control
Block, all arguments except dev must be
valid
arguments for
.WORD or
.BYTE
directives.

8.2.2

Format of the SNAP$ Macro

The format of the SNAP$ macro is:
SNAP$ ctl,efn,id,Ll,Hl,L2,H2,L3,H3,L4,H4
ctl
The set of flags that control the format of the dump and the data
to be printed.
The flags are:
SC.HDR

Print the dump header

SC.LUN

Print information on all assigned LUNs

SC.STK

Print the user stack

SC.OVL

Print information about all loaded overlay segments

SC.WRD

Print the requested memory in octal words and Radix-SO

SC. BYT

Print the requested memory in octal bytes and ASCII

8-7

MEMORY DUMPS
efn
The event flag to be used to synchronize your program and PMD. A
Wait-For-Single-Event-Flag
directive
is always generated to
perform synchronization.
id
A number that identifies the Snapshot Dump.
Because dumps can be
requested at different times and under different conditions, this
·ID is used to identify the piace or reason for the dump.
Ll,L2,L3,L4
The starting addresses of memory blocks to be dumped.
Hl,H2,H3,H4
The ending addresses of memory blocks to be dumped.
NOTES

8.2.3

If no memory is to be dumped,
each
limit
(Ll,L2,L3,L4,Hl,H2,H3,H4) should be o.

The control flags
can be set
in
any
combination;
they
are
not
mutually
exclusive.
Thus, any number of options can
be
obtained;
for
example,
SC.HDR!SC.LUN!SC.WRD prints
the
header,
LUNs, and the requested memory in word octal
and Radix-SO mode.

Arguments should be specified
only
override the
information already
in
Snapshot Dump Control Block.

Because SNAP$ generates instructions to move
data
into the Snapshot Dump Control Block,
its arguments must be valid source operands
for MOV instructions.

to
the

Example of a Snapshot Dump

The sample program shown in Figure 8-3 causes two Snapshot Dumps to be
printed directly on LPO:. The first dump uses the parameters defined
in the Snapshot Dump Control Block. The header is generated, and the
data
in relative locations BLK to BLK+220 is displayed, in word octal
and Radix-SO.
The identification on the dump is 1.
The second dump causes the data in the locations BLK to BLK+220 to be
displayed in byte octal and ASCII. A header is also generated.
The
dump identification is 64 (100 octal).
Figures 8-4 and 8-S show the
dumps generated by the sample program.

8-8

MEMORY DUMPS
SNPT:3T - TEST SNAP DUMP AND PMD MACRO MlOlO

000000
000036
000041
000044

123
124
000

116
123

012700

000036'

120
124

03-SEP-76 1S:S7

BLK:
BUF:

7
8
9
10
11
12

000046
000216
000222
000226
000412

START:

000004
000046'

ABS.
000000
000414
ERROHS DETECTED:

SNPTST - TEST SNAP DUMP AND PMD
/01/
SNPBK$,SNAP$,CALL
LP,O,SC.HDR!SC.OVL!SC.WRD,l,l,BLK,BLK+220
/SNPTST/

.EVEN
SNAP$
MOV
CALL
SNAP$

#BUF,RO
$CATS
#SC.HDR!SC.OVL!SC.BYT,,#100

IOT

.END

SNPTST - TEST SNAP DUMP AND PMD MACRO MlOlO
SYMBOL TABLE
SB.EFN=
SB. ID =
SB.LMl=
SB.PMD=
SB.UNT=

BLK
OOOOOOR
BUF
000036R
IE.ACT= ****** GX
SB .c'rL= 000000
SB.DEV= 000002

PAGE l

.TITLE
• IDENT
.MCALL
SNPBK$
.ASCIZ

000006
000010
000012
000032
000004

START

03-SEP-76 15:57
SC.BYT=
SC.HOR=
SC.LUN=
SC.OVL=

000040
000001
000002
000004

PAGE 1-1
SC.STK= 000010
SC.WRD= 000020
START
000046R
$CATS = ****** GX

$DSW
$$$T2
.• SPBK
•.• SNP=

000
001
0

l33S WORDS
( 6 PAGES)
VIRTUAL MEMORY USED:
DYNAMIC MEMORY AVAILABLE FOR 30 PAGES
00:00:14
ASSEMBLY TIME (ELAPSED):
SNPTST,SNPTST=SNPTST

Figure 8-3

Sample Program that Calls for Snapshot Dumps

8-9

****** GX
000027
OOOOOORG
000032

MEMORY DUMPS
SNAPSHOT DUMP

ID: 1

TASK: TT6

TIME: S-OCT-76 1S:06

PC: 0 00 S22
RO

REGS:

000000

100104

140130

PS - 170000

SP - 000304

RS - 000000

R4 - 000000

000000

MSG -CHK STP WFR REM MCR

TASK STATUS:

EVENT FLAG MASK FOR <1-16> 000001
CURRENT UIC:

[007 ,001]

DSW: 1.

PRIORITY: DEFAULT - SO.

RUNNING - SO.

TI DEVICE - TT6:

I / 0 COUNT : 0 •

LBN: 1,160034

LOAD DEVICE - DBO:
FLOATING POINT UNIT
STATUS - 000000
RO
Rl
R2
R3
R4
RS

000000
000000
000000
000000
000000
000000

OVERLAY SEGMENTS LOADED AND RESIDENT LIBRARIES MAPPED
STARTING RELATIVE BLOCK: 000002

BASE: 000000

LENGTH: 0014S4

TASK IMAGE

PARTITION: GEN
000300
000310
000320
000330
000340
0003SO
000360
000370
000400
000410
000420
000430
000440
0004SO
000460
000470

ooosoo
OOOSlO
000520

OOlOSl
000000
OOOS24
000000
131S74
000000
001037
012746
017646
000002
012746
OOS046
012746
062766
000002
104377
000046
016746
104377
Figure B-4

000001
000001
000000
000000
047123
016746
104377
000304
000000
017666
0002S07
OOS046
000336
000002
000002
103006
001402
177576
012700

VIRTUAL LIMITS: 000304 - OOOS24
00002S
000001
000000
000000
OS2120
177734
1034S6
012746
062766
000002
104377
OOS046
017646
000002
012746
022737
000261
012746
000342

OS0114
000304
000000
063014
OS2123
012746
OOS046
000336
000002
000002
01343S
OOS046
000000
017666
003413
177771
000405
OOlOSl
004767

A
A

u L36
A

HT
PMD
LUK MSX MS$
DlN 7T CTF
MW U61 UYF AXB
.CTF D6 CTF EV
B
PLV
!EBV
B
B
B EBB
!CTF 31 U61 UX/
!AXB AXB AXB AXB
!CTF EV EBV
!PLV
B
B EBB
B
B CTF AEC
!U61 UQO FBO BI
B SJ DQ FU
!DlN SF CTF M3
!U61 CSH EZ AWl

Sample Snapshot Dump (in Word Octal and Radix-50)

B-10

MEMORY DUMPS
SNAPSHOT DUMP

ID: 64

TASK: TT6

TIME: 5-0CT-76 15:06

PC: 000716
REGS:

RO - 000345

Rl -

074400

R2 - 000120

R3 - 140130

R4 - 000000

RS - 000000

SP - 000304

PS - 170000

TASK STATUS:

MSG -CHK STP WFR REM MCR

EVEN'r FLAG MASK FOR <1-16> 000001
CURRENT UIC:

[007001]

PRIOJRITY: DEFAULT LOAD DEVICE - DBO:

DSW: 1.
RUNNING - 50.

50.

TI DEVICE - TT6:

I/O COUNT: 0.

LBN: 1,160034

FLOATING POINT UNIT
STATUS RO
Rl
R2
R3
R4
RS

000000

000000
000000
000000
000000
000000
000000

OVERLAY SEGMENTS LOADED AND RESIDENT LIBRARIES MAPPED
STARTING RELATIVE BLOCK: 000002
STARTING RELATIVE BLOCK: 000004

BASE: 000000
BASE: 001454

LENGTH: 001454
LENGTH: 000264

TASK IMAGE
PARTITION: GEN
000300
000310
000320
000330
000340
000350
000360
000370
000400
000410
000420
0004.30
000440
0004:50
000460
000470
000500
000510
000520

051 002
000 000
124 001
000 000
174 263
000 000
037 002
346 025
246 037
002 000
346 025
046 012
346 025
366 145
002 000
377 210
046 000
346 035
377 210
Figure 8-5

001
001
000
000
123
346
377
304
000
266
107
046
336
002
002
006
002
176
300

VIRTUAL LIMITS: 000304 - 000524
000
000
000
000
116
035
210
000
000
037
005
012
000
000
000
206
003
377
025

045 000
100 000
000 000
000 000
120 124
334 377
056 207
346 025
366 145
002 000
377 210
046 012
246 037
002 000
346 025
337 045
261 000
346 025
342 000

114 120
304 000
000 000
014 146
123 124
346 025
046 012
336 000
002 000
002 000
035 207
046 012
000 000
266 037
013 007
371 377
005 001
051 002
367 011

! )

LP
D

'T
f

3 SN PT ST
f
f
\
f

6
G
&
"

&
&

ve
f

!f
@

f
b

% y

Sample Snapshot Dump (in Byte Octal and ASCII)

8-11

APPENDIX A
TASK BUILDER INPUT DATA FORMATS

An object module is the fundamental unit of input to the Task Builder.
You create an object module by using any of the standard language
processors (for example, MACR0-11 or FORTRAN) or by using the Task
Builder itself (symbol definition file).
The RSX-llM/M-PLUS librarian
(LBR) gives you the capability to combine a number of object modules
into a single library file.
An object module consists of variable length records of
information
that describe the contents of the module.
These records guide the
Task Builder in translating the object language
into a
task
image.
Six record (block) types are included in the object language:
•

Declare global symbol directory

(GSD)

record

(type 1)

•

End of global symbol directory

(GSD)

record

(type 2)

•

Text information (TXT)

(type 3)

•

Relocation directory

•

Internal symbol directory

•

End-of-module record

record

(RLD)

record
(!SD)

(type 4)

record

(type 5)

(type 6)

The Task Builder requires at least five of these record types in each
object module.
The only record type that it does not require is the
internal symbol directory.
The various record types are defined according to a prescribed format,
as
illustrated in Figure A-1.
An object module must begin with a
declare-GSD record and end with an end-of-module record.
Additional
declare-GSD
records can occur anywhere
in the file but must occur
before an end-of-GSD record.
An end-of-GSD record must appear before
the
end-of-module record,
and at least one RLD record must appear
before the first TXT record.
Additional RLD and TXT records
can
appear anywhere
in the file.
The ISD records can appear anywhere in
the file between the initial declare-GSD record and the end-of-module
record.
Object module records are variable length and are
identified by a
record type code
in the first
byte of the record.
The format of
additional information in the record depends on the record type.
The following sections describe each of the six record
types
greater detail.
The outline of these sections is as follows

A-1

TASK BUILDER INPUT DATA FORMATS
A.l

A.2
A.3
A.4

A.5
A.6

A.l

Declare Global Symbol Directory Record
A.1.1
Module Name (Type 0)
A.1.2
Control Section Name (Type 1)
A.1.3
Internal Symbol Name (Type 2)
A.1.4
Trasfer Address (Type 3)
A.1.5
Global Symbol Name (Type 4)
A.1.6
Program Section Name ('fype 5)
A.1.7
Program Version Identification (Type 6)
A.1.8
Mapped Array Declaration -(Type 7)
A.1.9
Completion Routine Name (Type 10)
End of Global Symbol Directory Record
Text Information Record
Relocation Directory Record
A.4.1
Internal Relocation (Type 1)
A.4.2
Global Relocation (Type 2)
A.4.3
Internal Displaced Relocation (Type 3)
A.4.4
Global Displaced Relocation (Type 4)
A.4.5
Global Additive Relocation (Type 5)
A.4.6
Global Additive Displaced Relocation (Type 6)
A.4.7
Location Counter Definition (Type 7)
A.4.8
Location Counter Modification (Type 10)
A.4.9
Program Limits (Type 11)
A.4.10 Program Section Relocation (Type 12)
A.4.11
Program Section Displaced Relocation (Type 14)
A.4.12 Program Section Additive Relocation (Type 15)
A.4.13 Program Section Additive Displaced Relocation
Type 16)
A.4.14 Complex Relocaion (Type 17)
A.4.15 Resident Library Relocation (Type 20)
Internal Symbol Directory Record
End of Module Record

DECLARE GLOBAL SYMBOL DIRECTORY RECORD

The global symbol directory (GSD) record contains all the
information
required by the Task Builder to assign addresses to global symbols and
to allocate the virtual address space required by a task.
GSD records are the only records processed by the Task Builder in its
first
pass;
therefore, you can save significant time by placing all
GSD records at the beginning of a module (because the Task Builder has
to read less of the file).
GSD records contain nine types of entries:
•

Module name

(type 0)

•

Control section name

(type 1)

•

Internal symbol name

(type 2)

•

Transfer address- (type 3)

•

Global symbol name

•

Program section name

•

Program version identification (type 6)

•

Mapped array declaration (type 7)

•

Completion routine name

(type 4)
(type 5)

(type 10)

A-2

TASK BUILDER INPUT DATA FORMATS

TASK BUILDER DATA FORMATS

GSD

Initial Declare GSD

RLD

Initial Relocation Directory

GSD

Additional GSD

TXT

Text Information

TXT

Text Information

RLD

Relocation Directory

GSD

Additional GSD

....._

•
•

•

END GSD

End of GSD

ISD

Internal Symbol Directory

ISD

Internal Symbol Directory

TXT

Text Information

TXT

Text Information

TXT

Text Information

END MODULE

End of Module

Figure A-1

General Object Module Format

Each entry type is represented by four words in the GSD
record.
As
shown
in Figure A-2,
the
first
two words contain six Radix-50
characters, the third word contains a flag byte and
the entry type
identification,
and the fourth word contains additional information
about the entry.

A-3

TASK BUILDER INPUT DATA FORMATS .

RECORD
TYPE

= 1

RAD50
NAME
ENTRY TYPE

FLAGS
VALUE
RAD50
NAME

TYPE

FLAGS
VALUE

•
•
•
RAD50
NAME

TYPE

FLAGS

VALUE
RAD50
NAME

TYPE

FLAGS

VALUE

Figure A-2

A.1.1

Global Symbol Directory Record Format

Module Name (Type 0)

The module name entry declares the name of
the object module.
The
name need not be unique with respect to other object modules (that is,
modules are identified by file, not module name), but only one such
declaration can occur
in any given object module.
Figure A-3
illustrates the module entry name format.
MODULE
NAME
ENTRY
TYPE

= 0

0
0

Figure A-3

Module Name Entry Format

A-4

TASK BUILDER INPUT DATA FORMATS

A.1.2

Control Section Name (Type 1)

Control sections, which include absolute sections (ASECTs), blank and
named control sections· (CSECTs), are replaced in RSX-llM by program
sections (PSECTs).
For compatibility with other systems,
the Task
Builder processes ASECTs and both forms of CSECTs.
Section A.1.6
details the entry generated for a .PSECT directive.
ASECTs and CSECTs are
follows:

defined

terms

For a blank CSECT, a program section is
attributes:

.PSECT

defined

with

directives,
the

following

.PSECT ,LCL,REL,CON,RW,I,LOW
For a named CSECT, the program section is defined as:
.PSECT name, GBL,REL,OVR,RW,I,LOW
For an ASECT, the program section is defined as:
.PSECT • ABS.,GBL,ABS,I,OVR,RW,LOW
The Task Builder processes ASECTs and CSECTs as program sections with
the
fixed attributes defined above.
Figure A-4
illustrates the
control section entry name format.

CONTROL SECTION
NAME
ENTRY
TYPE

= 1

IGNORED

MAXIMUM LENGTH

Figure A-4

A.1.3

Control Section Name Entry Format

Internal Symbol Name (Type 2)

The internal symbol name entry declares the name of an internal symbol
(with
respect
to
the module).
The Task Builder does not support
internal symbol tables;
therefore, the detailed format of this entry
is undefined.
If the Task Builder encounters an internal symbol entry
while reading the GSD, it ignores that entry.
Figure A-5 illustrates
the internal symbol name entry format.
SYMBOL
NAME
ENTRY
TYPE

= 2

0
UNDEFINED

Figure A-5

Internal Symbol Name Entry Format

A-5

TASK BUILDER INPUT DATA FORMATS
A.1.4

Transfer Address (Type 3)

The transfer address entry declares the transfer address of a module
relative
to a program section.
The first two words of the entry
define the name of the program section, and the fourth word defines
the
relative offset from the beginning of that program section.
If a
transfer address is not declared in a module, then a transfer address
must not be included in the GSD, or a transfer address of 000001
relative to the default absolute program section
(.
ABS.)
must be
specified.
Figure A-6 illustrates the transfer address entry format.
NOTE
If the program section is absolute,
the
offset is the actual transfer address
(if not 000001).

SYMBOL
NAME
ENTRY = 3
TYPE

OFFSET
Figure A-6

A.1.5

Transfer Address Entry Format

Global Symbol Name (Type 4)

The global symbol name entry declares either a global reference or a
definition.
Definition entries must appear after the declaration of
the program section in which the global symbols are defined and before
the declaration of another program section
(see Section A.1.6).
Global references can be used anywhere within the GSD.
As shown in Figure A-7, the first two words of the entry define the
name of the global symbol. The flag byte declares the attributes of
the symbol, aud the fourth word defines the value of the symbol
relative to the program section in which the symbol is defined.

SYMBOL
NAME
ENTRY
TYPE = 4

FLAGS
VALUE

Figure A-7

Global Symbol Name Entry Format

Table A-1 lists the bit assignments of the flag
declaration entry.

A-6

byte

the

symbol

TASK BUILDER INPUT DATA FORMATS
Table A-1
Symbol Declaration Flag Byte -- Bit Assignments
Bit Number and Name
0

Weak

Qualifier

Setting

Meaning

The symbol
has
a
strong
definition and is resolved in
the normal manner.

The
symbol
has
a
weak
definition or reference.
The
Task Builder
ignores a weak
reference
(Bit 3 = 0).
It
also ignores a weak definition
(Bit 3 = 1) unless a previous
reference has been made.
Not used

Definition or
Reference Type

Definition

Normal
definition
reference.

Library definition.
If
the
symbol is defined in a resident
library STB file,
the
base
address of the library is added
to the value and the symbol
is
converted to absolute (bit 5 is
reset);
otherwise, the bit is
ignored.

Global symbol reference.

Global symbol definition.

4
5

Not used.
Relocation

Absolute symbol value.

Relative symbol value.

Not used.

A.1~6

Program Section Name (Type 5)

The program section name entry declares the name of a program section
and its maximum length in the module.
It also uses the flag byte to
declare the attributes of the program section.

A-7

TASK BUILDER INPUT DATA FORMATS
GSD records must be constructed such that once a program section name
has been declared, all global symbol definitions pertaining to it must
appear before another program section name
is declared.
Global
symbols are declared with symbol declaration entries.
Thus, the
normal format is a series of program section names each followed by
optional symbol declarations.
Figure A-8 illustrates the program
section name entry format.

PROGRAM SECTION
NAME

ENTRY
TYPE

= 5

FLAGS

MAXIMUM LENGTH

Figure A-8

Program Section Name Entry Format

Table A-2 lists the bit assignments of the flag byte
section name entry.

the

program

Table A-2
Program Section Name Flag Byte -- Bit Assignments
Bit Number and Name
0

Memory Speed

Library program
section

Allocation

Meaning

Setting
0

The program section is to occupy
low-speed (core) memory.

The program section is to occupy
high-speed (MOS/bipolar) memory.

Normal program section.

is
section
The
program
relocatable
and
refers to a
common
resident
library
or
block.

Program section references are to
be
concatenated
with
other
references to the same program
section to form the total memory
allocated to the section.

Program section references are to
be overlaid. · The total memory
allocated to the program section
is the largest request made by
individual references to the same
program section.
(continued on next page)
A-8

TASK BUILDER INPUT DATA FORMATS
Table A-2 (Cont.)
Program Section Name Flag Byte -- Bit Assignments
Bit Number and Name

Setting

Access

Relocation

Scope

Type

Meaning
Not used;
reserved
DIGITAL use.

for

Program section
access.

has

read/write

Program
access.

has

read-only

The program section is absolute
and requires no relocation.

The
program
section
is
relocatable and references to
the control section must have a
relocation
bias added before
they become absolute.

The scope of the program section
is local.
References to the
same
program
section
are
collected
only
within
the
segment in which the program
section is defined.

The scope of the program section
is global.
References to the
program section are collected
across segment boundaries.
The
segment in
which
a
global
program
section is allocated
storage is determined either by
the first module that defines
the program section on a path,
or by direct placement of a
program section in a segment
using the overlay description
language .PSECT directive.

The program section
contains
instruction {I) references.

The program section
data {D) references.

section

NOTE
The length of all absolute
zero.

A-9

sections

future

contains

TASK BUILDER INPUT DATA FORMATS
A.1.7

Program Version Identification (Type 6)

The program version identification entry declares the version of the
module.
The Task Builder saves the version identification of the
first module that defines a nonblank version.
It then
includes this
identification
on
the
memory
allocation map and writes the
identification in the label block of the task image file.
The first two words of the entry contain the version identification.
The flag byte and fourth words are not used and contain no meaningful ·
information.
Figure
A-9
illustrates
the
program
version
identification entry format.

SYMBOL
NAME
ENTRY
= 6
TYPE

0
0

Figure A-9

A.1.8

Program Version Identification Entry Format

Mapped Array Declaration (Type 7)

The mapped array declaration entry allocates space within the mapped
array area of
task memory.
The array name is added to the list of
task program section names and may be referred to by subsequent RLD
records.
The length
(in units of 64-byte blocks) is added to the
task's mapped array allocation.
The total memory allocated
to each
mapped array
is
rounded up to the nearest 512-byte boundary.
The
contents of the flag byte are reserved and assumed to be zero.
One additional window block is allocated whenever a
declared.

mapped

array

Figure A-10 illustrates the mapped array declaration entry format.

MAPPED ARRAY
NAME
ENTRY
TYPE

= 7

FLAGS

LENGTH (NUMBER OF 64-BYTE BLOCKS)

Figure A-10

Mapped Array Declaration Entry Format

A-10

TASK BUILDER INPUT DATA FORMATS

A.1.9

Completion Routine Definition (Type 10)

The completion routine definition declares the entry point for the
completion routine of a supervisor-mode library. This data structure
is cieated by the Task Builder and appears only in Symbol Definition
files of supervisor-mode libraries.
As shown in Figure A-11, the first two words of the entry define the
name of the entry point. The third word contains the entry type byte
and the flag byte. The flag byte contains no meaningful information.
The fourth word contains the symbol value.

COMPLETION ROUTINE
NAME
ENTRY
TYPE

0
VALUE

Figure A-11 Completion Routine Entry Format

A.2

END OF GLOBAL SYMBOL DIRECTORY RECORD

The end of global symbol directory (end-of-GSD) record declares that
no other GSD records are contained further on in the module. There
must be exactly one end-of-GSD record in every. object module.
As
shown in Figure A-12, this record is one word long.

RECORD
TYPE

Figure A-12

A.3

End of Global Symbol Directory Record Format

TEXT INFORMATION RECORD

The text information (TXT)
record contains a byte
string
of
information that is to be written directly into the task image file.
The record consists of a load address followed by the byte string.
TXT records can contain words and/or bytes of information whose final
contents have not yet been determined. This information will be bound
by a relocation directory record that immediately follows the text
record
(see Section A.4). If the TXT record needs no modification,
then no relocation directory record is needed.
Thus, multiple TXT
records can appear in sequence before a relocation directory record.
The load address of the TXT record is specified as an offset from the
current program section base.
At least one relocation directory
record must precede the first TXT record. This directory must declare
the current program section.

A-11

TASK BUILDER INPUT DATA FORMATS

The Task Builder writes a text record directly into the task image
file and computes the value of the load address minus 4. This value
is stored in anticipation of a subsequent relocation directory that
modifies words and/or bytes contained in the TXT record. When added
to a relocation directory displacement byte, this value yields the
address of the word and/or byte to be modified in the task image.
Figure A-13 illustrates the TXT record format.

RECORD
= 3
TYPE

LOAD ADDRESS
TEXT

TEXT

•
•
•

TEXT

Figure A-13

A.4

Text Information Record Format

RELOCATION DIRECTORY RECORD

The relocation directory
(RLD)
record contains the
information
necessary to relocate and link the preceding TXT record. Every module
must have at least one RLD record that precedes the first TXT record.
The first RLD record does not modify a preceding TXT record; rather
it defines the current program section and location.
RLD records
contain 15 types of entry, classified as relocation or location
modification entries:
•

Internal relocation (type 1)

•

Global relocation (type 2)

•

Internal displaced relocation (type 3)

•

Global displaced relocation (type 4)

•

Global additive relocation (type 5)

A-12

TASK BUILDER INPUT DATA FORMATS
•

Global additive displaced relocation (type 6)

•

Location counter definition (type 7)

•

Location counter modification (type 10)

•

Program limits (type 11)

•

Program section relocation (type 12)

•

Program section displaced relocation (type 14)

•

Program section additive relocation (type 15)

•

Program section additive displaced relocation (type 16)

•

Complex relocation (type 17)

•

Resident library relocation (type 20)

Each type of entry is represented by a command byte which specifies
the type of entry and the word/byte modification, followed by a
displacement byte, and then by the information required for the
particular type of entry. The displacement byte, when added to the
value calculated from the load address of the preceding TXT record
(see Section A.3), yields the virtual address in the image that is to
be modified.
Table A-3 lists the bit assignments of the command byte
entry.

each

RLD

Table A-3
Relocation Directory Command Byte -Bit Assignments
Bit Number and Name
0-6

Entry Type

Modification

Setting

Meaning
Potentially, 128 command types
can be specified; currently,
15 are implemented.

The command modifies an entire
word.

The command modifies only l
byte. The Task Builder checks
for truncation errors in byte
commands.
If
modification
(that
truncation is detected
is,
if the modification value
is greater than 255), an error
occurs.

Figure A-14 illustrates the RLD record format.

A-13

TASK BUILDER INPUT DATA FORMATS

RECORD
TYPE

0
DISP

CMD

INFO

••

INFO

CMD

INFO

DISP

= 4

INFO

Figure A-14

A.4.1

INFO

DISP

CMD

INFO

Relocation Directory Record Format

Internal Relocation (Type 1)

The internal relocation entry relocates a direct pointer to an address
within a module.
The Task Builder adds the current program section
base address to a specified constant and writes the result into the
task image file at the calculated address (that is, a displacement
byte is added to the value calculated from the load address of the
preceding text block).
A-14

TASK BUILDER INPUT DATA FORMATS

For example:

#A,RO

MOV
or

.WORD

Figure A-15 illustrates the internal relocation entry format.

DISP

ENTRY
TYPE = 1

CONSTANT
Figure A-15

A.4.2

Internal Relocation Entry Format

Global Relocation (Type 2)

The global relocation entry relocates a direct pointer to a global
symbol.
The Task Builder obtains the definition of the global symbol
and writes the result into the
task
image
file
at the calculated
address.
For example:
MOV

#GLOBAL,RO
or

.WORD

GLOBAL

Figure A-16 illustrates the global relocation entry format.

DISP

ENTRY
TYPE = 2

SYMBOL
NAME
Figure A-16

A.4.3

Global Relocation Entry Format

Internal Displaced Relocation (Type 3)

The internal displaced relocation entry relocates a relative reference
to an absolute address from within a relocatable control section.
The
Task Builder subtracts the address plus 2 that the relocated value
is
to be written into from the specified constant and writes the result
into the task image file at the calculated address.

A-15

TASK BUILDER INPUT DATA FORMATS
For example:
CLR

177550
or

MOV

177550,RO

Figure A-17
format.

illustrates

DISP

the

internal

displaced

ENTRY
TYPE = 3

relocation

entry

CONSTANT
Figure A-17

AD4.4

Internal Displaced Relocation Entry Format

Global Displaced Relocation (Type 4)

The global displaced relocation entry relocates a
relative
reference
to a global symbol. The Task Builder obtains the definition of the
global symbol, subtracts the address plus 2 that the
relocated value
is to be written into from the definition value, and writes the result
into the task image file at the calculated address.
For example:
CLR

GLOBAL
or

MOV

GLOBAL,RO

Figure A-18 illustrates the global displaced relocation entry format.

DISP

ENTRY = 4
TYPE

SYMBOL
NAME
Figure A-18

A.4.5

Global Displaced Relocation Entry Format

Global Additive Relocation (Type 5)

The global additive relocation entry relocates a direct pointer to a
global symbol with an additive constant.
The Task Builder obtains the
definition of the global symbol, adds the specified constant to the
definition value,
and writes the result into the task image file at
the calculated address.

A-16

TASK BUILDER INPUT DATA FORMATS

For example:
MOV

#GLOBAL+2,RO
or

.WORD

GLOBAL-4

Figure A-19 illustrates the global additive relocation entry format.

DISP

ENTRY = 5
TYPE

SYMBOL
NAME
CONSTANT
Figure A-19

A.4.6

Global Additive Relocation Entry Format

Global Additive Displaced Relocation (Type 6)

The global additive displaced relocation entry relocates a
relative
reference to a global symbol with an additive constant.
The Task
Builder obtains the definition of the global symbol,
adds
the
specified constant to the definition value, subtracts the address plus
2 that the relocated value is to be written into from the
resultant
additive value, and writes the result into the task image file at the
calculated address.
For example:
CLR

GLOBAL+2
or

MOV

GLOBAL-5,RO

Figure A-20 illustrates the global additive displaced relocation entry
format.

DISP

ENTRY = 6
TYPE

SYMBOL
NAME
CONSTANT
Figure A-20

Global Additive Displaced Relocation Entry Format

A-17

TASK BUILDER INPUT DATA FORMATS
A.4.7

Location Counter Definition {Type 7)

The location counter definition entry declares a current program
section and location counter value.
The Task Builder stores the
control base as the current control section, adds the current control
section base to the specified constant, and stores the result as the
current location counter value.
Figure A-21 illustrates the location counter definition entry format.

ENTRY = 7
TYPE

PROGRAM SECTION
NAME
CONSTANT
Figure A-21

A.4.8

Location Counter Definition Entry Format

Location Counter Modification {Type 10)

The location counter modification entry modifies the current location
counter.
The Task Builder actds the current program section base to
the specified constant and stores the result as the current location
counter.
For example:
.=.+N

or
.BLKB
Figure A-22
format.

N
illustrates

the

location

counter

modification

entry

ENTRY = 10
TYPE

CONSTANT
Figure A-22

Ae4.9

Location Counter Modification Entry Format

Program Limits {Type 11)

The program limits entry is generated by the .LIMIT assembler
directive.
The Task Builder obtains the first address above the
header (normally the beginning of the stack) and the highest address
allocated to the task. It then writes these two addresses into the
task image file at the calculated address and at the ·calculated
address plus 2, respectively.

A-18

TASK BUILDER INPUT DATA FORMATS

For example:
.LIMIT
Figure A-23 illustrates the program limits entry format.

ENTRY
TYPE

DISP

Figure A-23

A.4.10

Program Limits Entry Format

Program Section Relocation (Type 12)

The program section relocation entry relocates a direct pointer to the
beginning address of another program section (other than the program
section in which the reference is made) within a module.
The Task
Builder obtains the current base address of the specified program
section and writes it into the task
image file at
the calculated
address.
For example:
.PSECT

.PSECT
MOV

#B,RO

or
.WORD

Figure A-24 illustrates the program section relocation entry format.

DISP

ENTRY
=
TYPE

PROGRAM SECTION
NAME

Figure A-24

A.4.11

Program Section Relocation Entry Format

Program Section Displaced Relocation (Type 14)

The program section displaced relocation entry relocates a
relative
reference to the beginning address of another program section within a
module.
The Task Builder obtains the current base address of the
specified program section,
subtracts the address plus 2 that the
relocated value is to be written into from the base value, and writes
the result into the task image file at the calculated address.

A-19

TASK BUILDER INPUT DATA FORMATS
For example:
.PSECT

.PSECT
MOV

C
B,RO

Figure A-25 illustrates the program section displaced relocation entry
format.

DISP

ENTRY
=
TYPE

PROGRAM SECTION
NAME

Figure A-25

A~4.12

Program Section Displaced Relocation Entry Format

Program Section Additive Relocation (Type 15)

The program section additive relocation entry relocates a direct
pointer to an address in another program section within a module. The
Task Builder obtains the current base address of the specified program
section, adds this address to the specified constant, and writes the
result into the task image file at the calculated address.
For example:
.PSECT

.PSECT
MOV
MOV

#B+lO,RO
#C,RO

or
.WORD
.WORD

B+lO

Figure A-26 illustrates the program section additive relocation
format.

A-20

entry

TASK BUILDER INPUT DATA FORMATS

DISP

ENTRY
TYPE

= 15

PROGRAM SECTION
NAME
CONSTANT

Figure A-26

A.4.13

Program Section Additive Relocation Entry Format

Program Section Additive Displaced Relocation (Type 16)

The program section additive displaced relocation entry relocates a
relative
reference to an address in another program section within a
module. The Task Builder obtains the current base address of the
specified
program section, adds this address to the specified
constant, subtracts the address plus 2 that the relocated value is to
be written into from the resultant additive value, and writes the
result into the task image file at the calculated address.
For example:
.PSECT

.PSECT
MOV
MOV

B+lO,RO
C,RO

Figure A-27 illustrates
relocation entry format.

DISP

the

program

section

additive

ENTRY
=
TYPE

displaced

PROGRAM SECTION
NAME
CONSTANT

Figure A-27

Program Section Additive Displaced Relocation Entry Format

A-21

TASK BUILDER INPUT DATA FORMATS
A.4.14

Complex Relocation (Type 17)

The complex relocation entry resolves a complex relocation expression.
Such an expression is one in which any of the MACR0-11 binary or unary
operations are permitted with any type of argument,
regardless of
whether the argument is an unresolved global symbol, is relocatable to
any program section base, is absolute, or
is a complex relocatable
subexpression.
The RLD command word is followed by a string of numerically-specified
operation codes and arguments.
The operation codes each occupy one
byte.
The entire RLD command must fit
in a single record.
The
following 15 operation codes are defined:
•

No operation

byte 0

•

Addi ti on {+)

byte 1

•

Subtraction {-)

byte 2

• Multiplication {*) -- byte 3
• Division {/) -- byte 4
• Logical AND ( & ) -- byte 5
• Logical inclusive OR { 1 ) byte 6
• Negation {-) -- byte 10
• Complement <"c) -- byte 11
•

Store result {command termination) -- byte 12

•

Store result with displaced relocation
-- byte 13

•

Fetch global symbol -- byte 16. It is followed
by 4
containing the symbol name in Radix-50 representation.

•

Fetch relocatable value -- byte 17. It is followed by 1 byte
containing the sector number,
and 2 bytes containing the
offset within the sector.

•

Fetch constant
byte
containing the constant.

•

Fetch resident library base address -- byte 21.
If the file
is a
resident library STB file, the library base address is
obtained;
otherwise, the base address of the task
image
is
fetched.

20.

{command

followed

termination)

The STORE commands indicate that the value is to be written
task image file at the calculated address.

into

bytes

the

All operands are evaluated as 16-bit signed quantities using
2's
complement arithmetic.
The results are equivalent to expressions that
the assembler evaluates internally.
The following
rules should be
noted.
1.

An attempt to divide by zero yields a zero result.
The
Builder issues a nonfatal diagnostic error message.

A-22

Task

TASK BUILDER INPUT DATA FORMATS
2.

All results are truncated from the left to fit into 16 bits.
No diagnostic error message is issued if the number is too
large.
If the result modifies a
byte,
the Task Builder
checks for truncation errors as described in Section A.4.

All operations are performed
absolute 16-bit quantities.
the result only.

on relocated
(additive)
or
PC displacement is applied to

For example:
.PSECT

ALPHA

.PSECT

BETA

MOV

#A+B-<Gl/G2& "C< 1771201 G3» ,Rl

Figure A-28 illustrates the complex relocation entry format.

DISP

I BI

ENTRY
TYPE

= 17

COMPLEX STRING
12

Figure A-28

A.4.15

Complex Relocation Entry Format

Resident Library Relocation (Type 20)

The library relocation entry relocates a direct pointer to an
within a resident library.

address

If the current file is a
resident library symbol definition file
(STB), the Task Builder obtains the base address of the library;
adds
this address to the specified constant;
and writes
the
result
into
the
task
image file at the calculated address.
If the file is not
associated with a resident library, the Task Builder uses the task
bas:e address.
Figure A-29 illustrates the library relocation entry format.

ENTRY
TYPE

DISP

CONSTANT

Figure A-29

Resident Library Relocation Entry Format

A-23

TASK BUILDER INPUT DATA FORMATS
A.5

INTERNAL SYMBOL DIRECTORY RECORD

The internal symbol directory (!SD)
record declares definitions of
symbols that are local to a module.
The Task Builder does not support
this feature;
therefore, the detailed record format is undefined.
If
the Task Builder encounters this type of record, it ignores that
record.
Figure A-30 illustrates the !SD record format.

RECORD
TYPE

= 5

UNDEFINED

Figure A-30

A.6

Internal Symbol Directory Record Format

END OF MODULE RECORD

The end-of-module record declares the end of an object module.
There
must be exactly one end-of-module record in every object module.
As
shown in Figure A-31, this record is one word long.

RECORD
TYPE

Figure A-31

End-of-Module Record Format

A-24

APPENDIX B

DETAILED TASK IMAGE FILE STRUCTURE

Figure B-1 illustrates how the Task Builder records a task
image on
disk..
As noted in the following sections, many parts of the task disk
image shown in this figure are optional and may not be recorded for
every task image.
The following sections, which provide detailed information on the task
image file structure, are organized as follows:
B.l
B.2
B.3
B.4

B•1

Label Block Group
Checkpoint Area
Header
B.3.1 Low-memory Context
B.3.2 Logical Unit Table Entry
Task Image
B.4.1 Autoload Vectors
B.4.2 Segment Descriptor
B.4.3 Window Descriptor
B.4.4 Region Descriptor
B.4.5 Supervisor-Mode Vector

LABEL :BLOCK GROUP

The label block group precedes the task on the disk and contains data
that
is needed by the system to install and load a task but need not
reside in memory during task execution. This group consists of three
parts:
•

Task and resident library data

(label block 0)

•

Table of LUN assignments

•

The segment load list (label block 3)

(label blocks 1 and 2)

Table B-1 describes the task and resident library data.
Figure B-2
illustrates how the Task Builder organizes this data in label block O.
The INSTALL processor verifies the task and resident library data when
entering the tasks into the System Task Directory (STD) file.
You can
obtain the offsets shown in Figure B-2 by calling the LBLDF$ macro
that resides in macro library LB: [1,1] EXEMC.MLB.

B-1

DETAILED TASK IMAGE FILE STRUCTURE
Relative
disk block 0
Label block 0 - Task and
resident Ii brary data

Relative
disk block 1

Label block 1 - Table of
LUN assignments

Relative
disk block 2

Label block
group

Label block 2 - Table of
LUN assignments (optional)

Relative
disk block 3

Label block 3 - Segment
load list (optional)
Checkpoint area
(optional)
Task header Fixed part
Header
Task header Variable part
Root segment
t----

(contiguous blocks)
Segment table

Relative
disk block n

Task image

Overlay segments
(task-resident
overlay data base)

Autoload vector

Region descriptor

Window descriptors

Segment descriptors

Figure B-1

Task Image on Disk

B-2

DETAILED TASK IMAGE FILE STRUCTURE
Table B-1
Task and Resident Library Data
Pa1rameter

Definition

L$BTSK

Task name consisting of two words
in Radix-50
This parameter is set by the TASK keyword.

format.

L$BPAR

Partition name consisting of
two words
in Radix-50
format.
This parameter is set by the PAR keyword.

L$BSA

Starting address of task.
Marks the lowest task virtual
address.
This parameter is set by the PAR keyword.

L$BHGV

Highest virtual address mapped by address window O.

L$BMXV

Highest task virtual address.
When the task does not
have memory-resident overlays,
the value is set to
L$BHGV.

L$BLDZ

Task load size in units of 64-byte blocks.
represents the size of the root segment.

L$BMXZ

Task maximum size in units of 64-byte blocks.
This
value represents the size of the root segment plus any
additional physical memory needed to contain
task
overlays.

L$BOF'F

Task offset into partition in units of 64-byte blocks.
This value represents the size of the mapped array area,
which precedes the task's code and data
in
the
partition.

L$BWND

Number of task window blocks less library window
-- low byte

L$BSYS

System ID

L$BWND

Number of task windows (excluding resident libraries).

L$BSEG

Size of overlay segment descriptors (in bytes).

L$BFLG

Task flags word.

This

value

blocks

high byte

The following flags are defined:

Bit

Flag

Meaning when Bit = 1

TS$PIC

Task contains position-independent code
(P IC)

TS$NHD

Task has no header

TS$ACP

Task is ancillary control processor

TS$PMD

Task generates post-mortem dump

TS$SLV

Task can be slaved
(continued on next page)

B-3

DETAILED TASK IMAGE FILE STRUCTURE
Table B-1 (Cont.)
Task and Resident Library Data
Parameter
L$BFLG
(Cont.)

Definition

Bit

Flag

Meaning when Bit = 1

TS$NSD

No SEND can be directed to task
(not used)

L$BDAT

TS$PRV

Task is privileged

TS$CMP

Task is built in compatibility mode

TS$CHK

Task is not checkpointable

TS$RES

Task has memory-resident overlays

TS$SUP

Image linked as supervisor-mode library
(RSX-llM-PLUS systems only)

Three words containing the task creation date as 2-digit
integer values as follows:
Year since 1900
Month of year
Day of month

L$BLIB

Resident library entries.

L$BPRI

Task priority set by the PRI keyword.

L$BXFR

Task transfer address.
Used to initiate a bootable core
image, for example, the resident executive.

L$BEXT

Task extension size in units of 32-word
parameter is set by the EXTTSK keyword.

L$BSGL

Relative block number of segment load list.
no list is allocated.

L$BHRB

Relative block number of header.

L$BBLK

Number of blocks in label block group.

L$BLUN

Number of logical units.

L$BROB

Relative block number of R/O image.

L$BROL

R/O load size in 32-word blocks.

B-4

blocks.

This

Set to 0 if

DETAILED TASK IMAGE FILE STRUCTURE

Offset

Label
L$BTSK

L$BPAR

L$BSA

Task

Name

Task

Partition

Base address of task

L$BHGV

Highest window 0 virtual address

L$BMXV

Highest virtual address in task

L$BLDZ

Load size in 64-byte blocks

L$BMXZ

Maximum size in 64-byte blocks

L$BOFF

Task offset into partition

L$BWND/L$BSYS

System l.D.

I Number of window blocks~·

L$BSEG

Size of overlay segment descriptors

L$BFLG

Task flag word

L$BDAT

Task creation date - Year

L$BLIB

-Month

-Day

Library /common

Name

R$LNAM

Base address of library

R$LSA

Highest address in first library window

R$LHGV

Highest address in library

R$LMXV

Library load size (64-byte blocks)

R$LLDZ

Library maximum size (64-byte blocks)

R$LMXZ

Library offset into region

R$LOFF

Number of library window blocks

R$LWND

Size of I ibrary segment descriptors

R$LSEG

Library flag word

R$LFLG

Library creation date - Year

R$LDAT

-Month

- Day

344

L$BPRI

346

Task priority

L$BXFR

350

Task transfer address

L$BEXT

352

Task extension (64-byte blocks)

L$BSGL

354

Block number of segment load list

L$BHRB

356

Block number of header

L$BBLK

360

Number of blocks in label

L$BLUN

362

Number of logical units

L$BROB

364

Relative Block of R-0 Image

L$BROL

366

R-0 Load Size

Figure B-2

Library
Request
(maximum
of 7
14-word
entries in
RSX-11 M systems
and
maximum
of 15
14-word
entries in
RSX-11 M+ systems)

*Less library window blocks.

Label Block 0 -- Task and Resident Library Data

B-5

DETAILED TASK IMAGE FILE STRUCTURE
Table B-2 describes the contents of the resident shared region name
block.
The Task Builder constructs this block by referring to the
disk image of the resident shared region.
The format is identical to
words 3 through 16 of the label group block.

Table B-2
Resident Library/Common Name Block Data
Definition

Parameter
R$LNAM

Shared region name consisting of
format.

R$LSA

Base virtual address of library or common.

R$LHGV

Highest address mapped by first library window.

R$LMXV

Highest virtual address in library or common.

R$LLDZ

Shared region load size in 64-byte blocks.

R$LMXZ

Library maximum size in 64-byte blocks.
This value
represents the size of the root segment plus the sum of
all memory-resident overlays.

R$LOFF

Size of mapped array space allocated by
resident
library.
This value is added to the mapped array area
of the task.

R$LWND

Number of window blocks required by library.

R$LSEG

Size of library overlay segment descriptors in bytes.

R$LFLG

Library flags word.

R$LDAT

words

Radix-50

The following flags are defined:

Bit

Meaning

LD$ACC -- access intent (l=read/write,
O=read-only)

LD$SUP -- supervisor-mode library (l=yes)

LD$REL -- position-independent code
(l=PIC)

(PIC)

flag

Three words containing the shared region creation date
in 2-digit integer values as follows:
Year since 1900
Month of year
Day of month

The table of LUN assignments, illustrated in Figure B-3, contains the
name and logical unit number of each device assigned.
Label block 2
(the second block of LUN assignments) is allocated only if the number
of LUNs exceeds 128.

B-6

DETAILED TASK IMAGE FILE STRUCTURE
The Task Builder creates the segment load list if the image
is a
resident library
that contains memory-resident overlays.
Figure B-4
illustrates the segment load list.
Each entry in the list gives
the
length, in bytes, of a memory-resident overlay segment.

Device name
LUN 1
Unit number
Label
Block

••
•

Device name
LUN 128
Unit number

Device name
LUN 129
Unit number
Label
Block

••
•

Device name
LUN 255
Unit number

Figure B-3

Label Blocks 1 and 2 -- Table of LUN Assignments

Length of root segment
Length of first overlay segment
Length of second overlay segment

•
••
0

Figure B-4

B.2

Label Block 3 -- Segment Load List

CHECKPOINT AREA

The checkpoint area is created by the AL switch (refer to Chapter 6).
The checkpoint area will be as large as the task image plus any areas
created by the EXTTSK, PAR, or VSECT options.

B.3

HEADER

As shown in Figure B-1, the task header starts on a block boundary and
is
immediately followed by the task image. The header is read into
memory with the task image.
The header is divided into two parts:
a fixed part as shown in Figure
B-5 and a variable part as shown in Figure B-6. The offsets for the
fixed part are defined by macro HDRDF$ residing in LB:[l,l]EXEMC.MLB.

B-7

DETAILED TASK IMAGE FILE STRUCTURE

The variable part of the header contains window blocks
the following:
•

The task's virtual-to-physical mapping

•

Logical unit data

•

Task context

that

describe

Although the header is fully accessible to the task,
you should
consider only the information in the low-memory context (H.DSW through
H.VEXT) in the fixed part of the header to be accurate.
In a mapped
system, the Executive copies the header of an active task to protected
memory.
Subsequent Executive updates to the header are made to this
copy, not to the header copy within the running task.
The following sections provide more detail on the low-memory context
and on Logical Unit Table entries (the Logical Unit Table is part of
the variable part of the header;
see Figure B-6).
NOTE
To save the identification,
you should
move the
initial value set by the Task
Builder to local storage.
When the
program is fixed
in memory and being
restarted without being reloaded, you
must test the reserved program words for
their
initial
values
to
determine
whether the contents of R3 and R4 should
be saved.
The contents of RO, Rl, and R2 are only
set when a debugging aid is included in
the task image.

Be3.l

Low-Memory Context

The low-memory context for a task consists of the Directive Status
Word and the impure area vectors.
The Task Builder recognizes the
following global names:
Name

Meaning

.FSRPT

File Control Services work area and buffer pool vector

$OTSV

FORTRAN OTS work area vector

N.OVPT

Overlay run-time system work area vector

$VEXT

Vector extension area pointer

The only proper reference to these pointers is by symbolic name.
The
pointers are read-only.
If you write into them, the result will be
lost on the next context switch.
The impure area pointers contain the addresses of the storage used
the reentrant library routines listed above.

The address contained in the vector extension pointer locates an
of memory that can contain additional impure area pointers.

area

B-8

DETAILED TASK IMAGE FILE STRUCTURE

Label

Offset

H.CSP

Current Stack Pointer ( R6)

H.HDLN

Header length

H.EFLM

Event flag mask

Event flag address

H.CUIC

Current UIC

H.DUIC

Default U IC

H.IPS

Initial PS

H.IPC

Initial PC (R7)

H.ISP

Initial Stack Pointer (R6)

H.ODVA

ODT SST vector address

H.ODVL

ODT SST vector length

H.TKVA

Task SST vector address

H.TKVL

Task SST vector length

H.PFVA

Power fail AST control block

H.FPVA

Floating-point AST control block

H.RCVA

Receive AST control block

H.EFSV

Address of event flag context

H.FPSA

Address of floating-point context

H.WND

Pointer to number of window blocks

H.DSW

Directive Status Word

H.FCS

Address of FCS impure storage

H.FORT

Address of FORTRAN impure storage

H.OVLY

Address of overlay impure storage

H.VEXT

Address of impure vectors

H.SPRl/H.NML

Mailbox LUN

H.RRVA

Receive by reference AST control block

Reserved

H.GARD

Header guard word pointer

H.NLUN

Number of LUNs

Figure B-5

Swapping priority

Task Header, Fixed Part

B-9

Low-Core
Context

DETAILED TASK IMAGE FILE STRUCTURE

H.LUN

I LUN Table (2 words per LUN)
••
•

Number of window blocks

Offsets

Partition control block address

W.BPCB

Low virtual address limit

W.BLVR

High virtual address limit

W.BHVR

Address of attachment descriptor

W.BATT

Window size (in 32-word blocks)

W.BSIZ

Offset into partition (in 32-word blocks)

W.BOFF

Number of PD Rs to Map

First PDR Address

Contents of last PDR

W.BNPD/W.BFPD
W.BLPD

•

••
Current PS
Current PC

Initial Values

Current R5

Relative block number of header

Current R4

ldent. word #2

Current R3

ldent. word #1

Current R2

Task name word #2

Current R 1

Task name word #1

Current RO

Program transfer address

Header guard w?rd

Figure B-6

Task Header, Variable Part

Figure B-7 illustrates the format of the vector extension area.
Each
location within this region contains the address of an impure storage
area that is referred to by subroutines;
these subroutines must be
reentrant.
Addresses below $VEXTA, referred to by negative offsets,
are reserved for DIGITAL applications.
Addresses above
$VEXTA,
referred to by positive offsets, are allocated for user applications.

B-10

DETAILED TASK IMAGE FILE STRUCTURE

$VEXT

•

•
•
.PSECT $$VEXO

$VEXTA

.PSECT $$VEX1

l Reserved for

( DIGITAL use

}

Reserved for
user applications

--~~~~~~~~~~---

Figure B-7

Vector Extension Area Format

The program sections $$VEXO and $$VEX1 have the attributes D, GBL, RW,
REL, and OVR.
The program section attribute OVR facilitates the definition of
the
offset to the vector and the initialization of the vector location at
link time.
For example:
MAKE SURE VECTOR AREA IS LINKED

.G LOBL

$VEXTA

.PSECT

$$VEX1,D,GBL,RO,REL,OVR

BEG=.

LABE:L:

POINT TO BASE OF POINTER TABLE
.BLKW

OFFSET TO CORRECT LOCATION
IN VECTOR AREA

.WORD

IMPURE

SET IMPURE AREA ADDRESS
DEFINE OFFSET

OFFSET== LABEL-BEG
.PSECT
IMPURE:

You should centralize all offset definitions within a single module
from which the actual vector space allocation is made.
Also, you
should conditionalize the source to create two object modules:
one
that
reserves the vector storage and, one that defines the global
offsets which will be referred to by your resident
library's
subroutines.
Note that the sequence of instructions above
intentionally redefines
the global symbol.
The Task Builder will report an error if this
value differs from the centralized definition.

B-11

DETAILED TASK IMAGE FILE STRUCTURE
You can locate your vector through a sequence of instructions
to the following:
MOV @#VEXT,RO
MOV OFFSET(RO),RO
.END

B.3.2

similar

GET ADDRESS OF VECTOR EXTENSIONS
POINT TO IMPURE AREA

Logical Unit Table Entry

Figure B-8 illustrates the format of each entry in
Table.

the

Logical

Unit

UCB address
Window block pointer

Figure B-8

Logical Unit Table Entry

The first word contains the address of the device unit control block
in the Executive system tables.
That block contains device-dependent
information.
The second word is a pointer to the window block if the device is file
structured.
The UCB address is set during task installation if a corresponding ASG
parameter is specified at task build time.
You can also set this word
at run time with the Assign LUN Directive to the Executive.
The window block pointer is set when a file is opened on the device
whose UCB address is specified by word 1. The window block pointer is
cleared when the file is closed.

B .• 4

TASK IMAGE

The system reads the task image into memory beginning with the
task
header
(see Figure B-1).
The root segment of the task image is a set
of contiguous disk blocks;
it is therefore loaded with a single disk
access.
Each overlay segment of the task image begins on a block boundary (see
Figure B-1).
The relative block number for the segment is placed in
the segment table.
Note that a given overlay segment occupies as many
contiguous disk blocks as it needs to supply its space request.
The
maximum size for any segment, including the
root,
is 32K minus 32
words.

B-12

DETAILED TASK IMAGE FILE STRUCTURE
NOTE
One exception to the block boundary
alignment of segments occurs when shared
regions contain resident overlays. When
this occurs, the image is compressed
and, instead of being aligned on block
boundaries,
segments are aligned on
32-word boundaries.
This facilitates
the loading of regions.
Figure 'B-9 illustrates the structure and principal components
task-resident overlay data base.

@OAD
TOR

SEGMENT
DESCRIPTOR

the

1-----,

WINDOW
DESCRIPTOR

~-DAD

SEGMENT
DESCRIPTOR

AUTO LOAD
VECTOR

SEGMENT
DESCRIPTOR

fOR

Figure B-9

,.....,
WINDOW
DESCRIPTOR

REGION
DESCRIPTOR

t--

Task-Resident Overlay Data Base

Autoload vectors are generated whenever a reference is made to an
autoloadable entry point in a segment located farther away from the
root than the segment making the reference.
One segment descriptor is generated for each overlay segment in the
task or shared region. The segment descriptor contains information on
the size, virtual address, and location of the segment within the task
image file.
In addition, it contains a set of link words that point
to other segments. The overlay structure determines the link word
contents.
The window descriptor contains information required to issue the
mapping directives.
One window descriptor is allocated for each
memory-resident overlay in the structure.
The region descriptor contains information required to attach a
resident library or common block. It is allocated within each task
that refers to a shared region containing memory-resident overlays.
The following sections describe each data base
detail.

B-13

component

greater

DETAILED TASK IMAGE FILE STRUCTURE
B.4.1

Autoload Vectors

The autoload vector table consists of one
point in the form shown in Figure B-10.

entry

per

autoload

entry

PC,sub

JSR

$AUTO
Segment descriptor address
Entry point address

Figure B-10

Autoload Vector Entry

The autoload vector contains a JSR
instruction to the autoload
processor,
$AUTO,
followed by a pointer to the descript~r for the
segment to be loaded and the real address of the entry point.

B.4.2

Segment Descriptor

The segment descriptor consists of a
fixed part and two optional
parts.
The fixed part is six words long.
If the manual-load feature
is used ($LOAD), two words are added containing the segment name.
When a memory-resident overlay structure is included, a ninth word is
appended that points to the window descriptor.
Figure B-11 illustrates the contents of the segment descriptor.
Word

15
Status

Relative disk address
Load address

Length in bytes

Link up

Link down

Link next

Segment

name

Window descriptor address

Fixed Part

Figure B-11

Segment Descriptor

Word 0 contains the relative disk address in bits O through 11 and the
segment status in bits 12 through 15. Each segment in the task image
file begins on a disk block boundary.
The relative disk address
is
the block number of the segment relative to the start of the root
segment.

B-14

DETAILED TASK IMAGE FILE STRUCTURE
The

segm~nt

flags are defined as follows:

Bit
15

Setting
Always set to 1

Segment has disk allocation
Segment does not have disk allocation

0
1

Segment is not loaded from disk
Segment loaded from disk

0
1

Segment is loaded and mapped
Segment is either not loaded or not mapped

Word 1 contains the load address of the segment.
This address is the
first virtual address of the area where the segment will be loaded.
Word 2 specifies the length of the segment in bytes.
Words 3, 4, and 5 point to the following segment descriptors:
•

Link up -- the next segment away from the root

(O=none)

•

Link down

the next segment toward the root

(O=none)

•

Link next
the adjoining segment;
are linked in circular fashion

the

link

pointers

When the system loads a segment, the overlay run-time system follows
the
links
to determine which segments are being overlaid and should
therefore be marked out of memory.
For example:
A21

A22

I
AO

The segment descriptors are linked as follows:
A21
Al

A22

L,A2

A21

A22

Al~A2

~AO

.link up

link down

link next

If there is a co-tree, the link next for the root
points to the co-tree root segment descriptor.

segment

descriptor

Words 6 and 7 contain the.segment name in Radix-SO format.
Word 8 points to
( O=none).

the

window

descriptor

B-15

used

map

the

segment

DETAILED TASK IMAGE FILE STRUCTURE
B.4.3

Window Descriptor

The Task Builder allocates window descriptors only if
structure
containing
memory-resident
overlays.
illustrates the format of a window descriptor.
Word

8 7
Base Active Page Register

you define a
Figure
B-12

0
Window ID

Virtual base address

Window size in 64-byte blocks

Region ID

Offset in partition

Length to map

Status word

Send/receive buffer address (always 0)

Flags word

Address of region descriptor

Figure B-12

Window Descriptor

Words 0 through
7 constitute a window descriptor
in the format
required by the mapping directives.
If the memory-resident overlay is
part of the task, the region ID is zero.
If the memory-resident
overlay is part of a shared region, the ID is filled in at run time by
the overlay loading routine.
Words 8 and 9 contain additional data that
is referred to by the
overlay routines.
Bit 15 of the flags word, if set, indicates that
the window is currently mapped into the task's address space.
Word 9 contains the address of the associated region descriptor.
If
the memory-resident overlay
is part of the task,
and no region
descriptor is allocated, this value is zero.

B.4.4

Region Descriptor

The region descriptor
is allocated only when the memory-resident
overlay structure is part of a shared region.
Figure B-13 illustrates
the format of a region descriptor.

B-16

DETAILED TASK IMAGE FILE STRUCTURE

Region ID
Size of region

Region

name

Region

partition

Region status

Protection codes (always 0)

Flags

Figure B-13

Region Descriptor

Words 0 through
7 constitute a
region descriptor
in the format
required by the mapping directives.
The flags word is referred to by
the overlay load routine.
Bit 15 of the flags word, if set, indicates
that a valid region identification is
in word O.
If this bit is
clear, the overlay load routine
issues an Attach Region directive
(with protection code set to zero) to obtain the identification.

B.4.5

Supervisor-Mode Vectors (RSX-llM-PLUS Only)

A supervisor-mode vector consists of four words.
The Task Builder
replaces each call from a user-mode task to the root segment of a
supervisor-mode library with
one
of
these
structures.
The
supervisor-mode vector is shown in Figure B-14.

PC,sub

JSR

$SUPL
Completion routine address
Entry point address

Figure B-14

Supervisor-Mode Vector

The supervisor-mode vector contains a JSR instruction to the context
switching routine, $SUPL. $SUPL issues the SCAL$ Executive directive
to context switch the processor from user mode to supervisor mode.
The supervisor-mode vector also contains the address of the completion
routine within the supervisor-mode library and the entry point of the
library.

B-17

APPENDIX C
RESERVED SYMBOLS

Several global symbols and program section namesl are reserved for use
by
the Task Builder.2 Special handling occurs when the Task Builder
encounters a definition of one of these names in a task ~mage.
The definition of a reserved global symbol in the root segment causes
a word in the task image to be modified with a value calculated by the
Task Builder.
The relocated value of the symbol is taken as the
modification address.
The following global symbols are reserved by the Task Builder:
Global
Symbol

Modification
Value

.FSRPT

Address of file storage region work area

.MOLUN

Error message output device

.NLUNS

The number of logical units used by the task,
including the message output and overlay units

.NOV LY

The overlay logical unit number

N.OVPT

Address of overlay run-time system work area

.NSTBL

The address of the segment description tables;
this
location is modified only when the number of segments
is greater than one

.ODTLl

Logical unit number for the ODT terminal device TI:

.ODTL2

Logical unit number for the ODT line printer device CL:

$0TSV

Address of Object Time System work area

.TRLUN

The trace subroutine output logical unit number

$VEXT

Address of vector extension area

(.FSRCB)

not

(.NOVLY)

($0TSVA)

($VEXTA)

1 In RSX-llM and RSX-llM-PLUS, absolute sections
(ASECTs)
and both
blank and named control sections (CSECTs) are supplanted by program
sections (PSECTs).
The .PSECT assembler directive eliminates the need
for
.ASECT and .CSECT directives, except for compatibility with other
systems.
This manual refers to all
sections as program sections,
unless the specific characteristics of ASECTs or CSECTs apply.
2

All symbols and program section names containing a period (.)
dollar sign ($) are reserved for DIGITAL-supplied software.

C-1

RESERVED SYMBOLS
The Task Builder reserves the following program section names.
In
some cases,
the definition of a reserved program section causes that
program section to be extended if you specify the appropriate option.
Section
Name

Description

$$ALVC

Contains the segment autoload vectors

$$DEVT

The extension length (in bytes) is calculated from
formula:
EXT

the

= <S.FDB+52>*UNITS

The definition of S.FDB
is obtained from the
root
segment symbol table and UNITS is the number of logical
units used by the task, excluding the message output,
overlay, and ODT units.
$$FSR1

The extension of
ACTFIL option

this

section

specified

the

$$IOB1

The extension of
MAXBUF option

this

section

specified

the

$$0BF1

FORTRAN OTS uses this area to parse array type format
specifications;
this section can be extended by the
FMTBUF keyword

$$RGDS

Contains the region descriptors for resident
referred to by the task

$$RTS

Contains the return instruction

$$SLVC

Supervisor-mode library transfer vectors
only)

$$SGDO

Contains the program section adjoining the task segment
descriptors

$$SGD1

Contains the task segment descriptors

$$SGD2

Contains the program section following the task segment
descriptors

$$WNDS

Contains the task window descriptors

C-2

libraries

(RSX-llM-PLUS

APPENDIX D

IMPROVING TASK BUILDER PERFORMANCE

This appendix contains procedures to assist you
Builder performance.
These procedures include:

maximizing

Task

•

Evaluating and improving Task Builder throughput

•

Modifying command switch defaults to provide a more
user interface

efficient

•

Using the Slow Task Builder when
required

space

These procedures assume
features not found
in
Appendix F.

that the
the Fast

large

work

file

program to be linked
requires
Task Builder
(FTB) described in

Use of the procedures described in this appendix may require relinking
the Task Builder.
You can do this only in a system that has, as a
minimum, a 14K user-controlled or system-controlled partition.
In
some cases, you can make the modifications without relinking by using
the binary patch program ZAP (see the RSX-11 Utilities Manual).
Modifications to the Task Builder build file imply one or more of
the
following
files
located
under UFD
[1,24]
(mapped)
or
[1,20]
(unmapped):
RSX-llM systems:
BIGTKBBLD.CMD
TKBBLD.CMD
SLOTKBBLD.CMD
RSX-llM-PLUS systems:
TKBBIGBLD.CMD
TKBSLOBLD.CMD
These files reside on the
modules.

D.l

RKOS

disk

containing

the

system

EVALUATING AND IMPROVING TASK BUILDER THROUGHPUT

Task Builder throughput is determined by three factors:
1.

The amount of disk latency incurred because of overlays

The amount of memory available for table storage

The amount of disk latency due to input file processing
D-1

object

IMPROVING TASK BUILDER PERFORMANCE
The following sections outline methods
each of these three cases.

for

improving

throughput

Overlay Latency

D.1.1

The Task Builder is overlaid to reduce memory requirements.
Two
versions built with different overlay structures are supplied with the
system:
•

TKB.TSK, which is heavily overlaid but runs in an 8K partition

•

BIGTKB.TSK, which contains fewer
requires a 14K partition

overlays

than

TKB.TSK

but

You should install the appropriate version, that is,
one that saves
space or time, based on the system resources.
In addition, the task
should reside on the highest performance disk in the system.

Table Storage

D.1.2

The principal factor governing Task Builder performance is the amount
of memory available for table storage.
To reduce memory requirements,
a work file is used to store symbol definitions and other tables.
This work file cannot exceed 65,543 words.
As long as the size of
these tables is within the limits of available memory, the contents of
this file are kept in memory and the disk is not accessed.
If the
tables exceed this limit, some information must be displaced and moved
to the disk, degrading performance accordingly.
You can gauge work file performance
portion of the Task Builder map.
parameters:

by consulting the statistics
The map displays the following

•

Number of work file references
work file data was referred to.

total number of

times

that

•

Work file
reads -- number of work file
references
resulted in disk accesses to read work file data.

that

•

Work file writes -- number of work file
references
resulted in disk accesses to write work file data.

that

•

Size of core pool -- amount of in-core table storage in words.
This value is also expressed in units of 256-word pages
(information is read from and written to disk in blocks of 256
w~rds).

•

Size of work file -- amount of work file storage in words.
If
this value is less than the pool size, the number of work file
reads and writes is zero. That is, no work file pages are
removed to the disk. This value is also expressed in pages
(256-word blocks).

•

Elapsed time -- amount of time required to build the task
image and output the map.
This value excludes ODL processing,
option processing, and the time required to produce the global
cross-reference.

D-2

IMPROVING TASK BUILDER PERFORMANCE
You can reduce the overhead for gaining access to the work file in one
or more of the following ways:
•

By increasing the amount of memory available for table storage

•

By placing the work file on the fastest random access device

•

By decreasing system overhead required to gain access
file

•

By reducing the number of work file references

the

You can increase the amount of table storage by installing the Task
Builder in a larger partition or, if the Task Builder is running in a
system-controlled partition,
by using
the INSTALL/INC keyword to
allocate more space.
In a system that includes support for the Extend Task directive,
the
Task Builder automatically increases its size if it is checkpointable
and installed in a system-controlled partition.
You set the maximum
limit.
You can increase this maximum by issuing the MCR command SET
/MAXEXT.
Increasing the proportion of
resident dynamic memory reduces the
amount of I/O necessary for access to the Task Builder internal data
structures. As stated above,
once the
resident memory has been
filled, the data structures overflow into a temporary work file on the
device assigned to the workf ile logical unit number.
This logical
unit
number
(W$KLUN)
is specified
in the build command file.
Preferably, this unit number should be assigned to a device other thari
the system device;
e.g., a fixed head disk.
Displacement of pages to the workf ile is done on a least recently used
basis.
The workfile extends automatically as necessary to hold all
pages displaced.
The parameter W$KEXT is provided in the build
command file of the Task Builder and defines the file extension
properties.
A negative value indicates
that
the
extend
is
noncontiguous,
a positive value that the extend is contiguous.
If a
contiguous extend fails, a noncontiguous request is attempted;
if a
noncontiguous extend fails,
a fatal workfile I/O error is reported.
As long as the workfile remains contiguous, a higher access rate can
be obtained.
It is not possible to state exactly how many symbols the Task Builder
can process,
because there are many data structures included in
virtual memory.
The following is a list of the structures that are
stored in the virtual memory.
All the sizes given are approximate
only (sizes vary with characteristics of the task being built and may
vary from release to release).
Structure Name

Description

Approx. Size
(words)

Segment Descriptor

Contains listhead
sizes, the pointers
defining the overlay
tree, the segment name.
Part of this structure
becomes the segment
descriptor in the
resultant task image.

60.

D-3

IMPROVING TASK BUILDER PERFORMANCE
structure Name

Description

Approx. Size
(words)

P-section Descriptor

Contains the name,
address size, and
attributes of a
p-section.

10.

Symbol Descriptor

Contains symbol name,
value, flags, and
pointers to defining
segment and program
section descriptors.

8. (nonoverlaid
task)
15. (overlaid task)

Element Descriptor

Contains module
name, ident, filename,
count of program
section and some
flags.

8. -18.

Control Section
Mapping Table

Table of program
section size and
program section
descriptor addresses.

2 words per
program section in
each module

The maximum usage of virtual memory occurs during phase three of the
Task Builder, when the symbol table is built. However, phase one
makes significant use of virtual memory when an overlaid task is being
built.
It is at this point that all the segment descripto~s are
allocated, as well as an element descriptor for every filename
encountered during the parsing of the tree description. In addition,
a p-section descriptor is produced for every .PSECT
directive
encountered in the overlay description.
The parsing of the overlay description also makes use of dynamic
memory during the processing of each directive.
This memory is
released upon completion of the analysis;
during the analysis,
however, the whole tree description must fit into the resident portion
of the storage. If sufficient storage cannot be obtained in· the
resident
dynamic memory, the error message NO DYNAMIC STORAGE
AVAILABLE is returned. The method for increasing the ratio of dynamic
storage to virtual memory may be applied here possibly to allow a task
with a large overlay description to be built.
The amount of memory required during analysis depends on:
1.

The number of directives,

The length of .FCTR lines,

The number of operators
parentheses), and

The number of filenames encountered.

(i.e.,

commas,

dashes,

and

The amount of resident storage area available depends on the version
of the Task Builder used.
The smaller version (TKB) has enough
storage in an SK partition to handle the overlay description for all
privileged tasks.
The larger version (BIGTKB) links all
partition.

D-4

DEC-supplied

tasks

14K

IMPROVING TASK BUILDER PERFORMANCE
There are a number of ways to reduce the amount of virtual memory
required during the build of a specific task.
Reduction of the data
structures in virtual memory also increases the speed of searching the
tables and reduces the amount of paging to the workfile.
1.

Extract object modules by name from relocatable object
libraries
{e.g.,
LIBRY/LB:MODl:MOD2).
This
technique
requires smaller element descriptors and fewer filename
descriptors and is also faster because there are fewer files
to open and close.

Use concatenated object
above.

Use shared regions {resident libraries and common areas)
for
language and overlay run time systems and file control
services.
Such use of shared regions allows symbols and
p-sections to be defined only once, rather than on multiple
branches of the tree.

Place modules that occur on parallel branches of the tree
in
a
common segment {i.e., closer to root) for the same reasons
as 3 above.

Use the /SS switch on symbol table files {.STB) that describe
absolute symbol definitions so that only those symbols
referenced are extracted from the module.

Minimize the number of segments and keep the tree balanced.
For example,
if one segment is very long, there is no value
in putting a tree structure in parallel unless creation of
one segment in parallel would be longer.

modules

for

the

same

reasons

In addition to the above, a version of BIGTKB can be built which has
less throughput but requires less virtual memory per element than
BIGTKB. This version is built using the command file SLOTKBBLD.CMD
supplied on the RK05 utility disk or the RK06 and RP system disks
under UFD (1,20] (unmapped) or (1,24] {mapped).
There are four error
syst,em:

messages

associated

with

the

virtual

memory

NO DYNAMIC STORAGE AVAILABLE. This error occurs when there
is
insufficient resident storage for creation of some data
structure.
As much as possible of the data already allocated
{all unlocked pages)
has been paged to the workfile, but
there is still not enough free memory.
Such a
situation
might arise during the analysis of the overlay description,
early in the task-build run and particularly if
it
is a
complex tree.
Reduction of the ODL and extension of the Task
Builder memory allocation (see above)
are the
recommended
recovery procedures.

UNABLE TO OPEN WORKFILE.
are:

The probable causes of

•

Device assigned to logical unit 8 of the Task
not mounted.

•

The device is not FILES-11.

•

There is no space on the volume.

D-5

this

error

Builder

IMPROVING TASK BUILDER PERFORMANCE
•

The device is offline, not ready, write locked, or faulty.

•

There is no such device.

The MCR function LUN ••• TKB may be used to determine
device the Task Builder is attempting to use.
3.

which

WORKFILE I/O ERROR.

The probable causes of this error are:

•

Hardware error;

e.g., parity error on the disk.

•

Device is not ready, or is write-locked.

•

An extend failure has occurred;

e.g., the disk is full.

NO VIRTUAL MEMORY STORAGE AVAILABLE. The addressable limit
of the virtual memory has been reached.
There is no recovery
other than to reduce the virtual memory requirements of the
task being built along the lines suggested earlier.

The work iile normally resides on the device from which the Task
Builder was
installed.
You can change the device by reassigning
logical unit 8 through the Monitor Console Routine or by editing the
build file and relinking the Task Builder.
System overhead for work file accesses is incurred in translating a
relative block number
in the file to a physical disk address.
To
minimize this overhead,
the Task Builder requests disk space in
contiguous
increments.
The size of each increment is equal to the
value of symbol W$KEXT defined in the Task Builder build file.
A
larger positive value causes the file
to be extended in larger
contiguous increments and reduces the overhead required to gain access
to the file.
The increment should be set to a reasonable value
because the Task Builder resorts to noncontiguous allocation whenever
contiguous allocation fails.
You can reduce the size of the work file by:
Linking your task to a core-resident library containing
• commonly
FORTRAN Object Time
(for example,
used routines
System) whenever possible
•

Including common modules, such as components of an object time
system, in the root segment of an overlaid task

•

Using an object library or file of concatenated object modules
if many modules are to be linked

When you use either of the last two procedures,
system overhead is
also significantly reduced because fewer files must be opened to
process the same number of modules.
You can reduce the number of work file
references by eliminating
unneeded output files and cross-reference processing or by obtaining
the short map.
In addition, you can usually exclude selected files,
such as the default system object module library, from the map.
In
this case, you can obtain, and retain, a full map at less frequent
intervals.

D-6

IMPROVING TASK BUILDER PERFORMANCE

Input File Processing

D.1.3

The procedures for minimizing the size of the work file and number of
work
file
accesses also drastically reduce the amount of input file
processing.
A given module can be read up to four times when the task is built:
•

To build the symbol table

•

To produce the task image

•

To produce the long map

•

To produce the global cross reference

Files that are excluded from the long map are read only twice.
The
third and fourth
passes are eliminated for all modules when you
request a short map without a global cross reference.

Summary

D.1.4

In summary, you can use
Builder throughput:

the

following

procedures

improve

Task

table

Use the INSTALL/INC or EXTTSK keyword to allocate
• space

•

Increase maximum task size by raising
dynamic task extension

the

disk latency by placing the work file
• Reduce
random access device

D.2

system
on

limit
the

for

fastest

•

Reduce system overhead by modifying the command file
allocate work file space in larger contiguous increments

•

Decrease work file
size by
using
resident
concatenated object files, and object libraries

libraries,

•

Decrease work file size by including common modules
root segment of an overlaid task

into

•

Decrease the number of work file references by eliminating the
map and global cross reference, obtaining the short map, or
excluding files from the map

the

MODIFYING COMMAND SWITCH DEFAULTS

The default switch settings and values provided by the Task Builder as
released may not suit the requirements of all installations.
For
example, the default /-EA (no KEll Extended Arithmetic Element)
would
be unsatisfactory at an installation that made frequent use of this
hardware.

D-7

IMPROVING TASK BUILDER PERFORMANCE
the contents of
You can thus tailor the switch defaults by altering
Modifying the Task
the words
that contain initial switch states.
Builder in this way is a three-step process:
1.

Consult Tables D-1 through D-4 to determine the
and bit to be altered.

switch

word

Edit the appropriate Task Builder command file to include the
switch word modification through a GBLPAT keyword referring
to the global switch word name.

Relink the Task Builder using the modified command file.

The command files for system tasks,
as provided with the
released
system, require the standard set of Task Builder defaults;
therefore,
you must retain and use an unmodified copy of the Task Builder
whenever such tasks are relinked.
You use tables D-1 through D-4 to alter the defaults as follows:
•

You identify the switch and the file it applies to.

•

You consult the switch category entry in each table to
the applicable switch words.

•

You scan the switch settings to find the switch and associated
bit.

•

You OR the desired setting of
the associated bit
initial contents to obtain the new set of defaults.

with

the

•

You specify the revised value and switch word as arguments
a GBLPAT keyword.

•

You relink the Task Builder to produce
the appropriate defaults.

version

locate

containing

For example, to change the Task Builder Extended Arithmetic
default to /EA, perform the steps described below.

Element

By consulting Table D-1, you determine that two switch words,
$DFSWT
and $DFTSK, contain task file switches.
Of these, $DFTSK contains the
default setting for the EA switch in bit 13. Setting this bit to 1
changes the initial switch setting to /EA.
This new valu~ is combined
{ORed) with the initial contents to yield the revised setting 120002.
The required keyword input is:
TKB>GBLPAT=TASKB:$DFTSK:l20002
NOTE
The setting of bit positions not listed
in the tables must not be altered.
The only switches that have associated values are /AC and /PR.
In
these cases,
the value is the number of the initial APR used to map
the task.
The default can be altered by changing the value specified
in the build file GBLDEF keyword for the symbol D$FAPR. Only v~lues 4
or 5 can be used.

D-8

IMPROVING TASK BUILDER PERFORMANCE
Table D-1
Task File Switch Defaults
Switch Category:
Switch Word:

Task file

$DFSWT

Initial Contents:

Switch Settings:
Condition if Set to 1

Bit
15

Abort build on error

Sequential PSECT allocation

Full overlay tree search

-RO

Disable recognition of memory-resident
overlay operator

Switch Category:
Switch Word:

Task file

$DFTSK

Initial Contents:

100002

Switch Settings:
Bit

Condition if Set to 1
1

-CP, -AL

Not checkpointable

Floating-point processor

Extended Arithmetic Element

-HD

No header

Compatibility Mode

Debugging aid

Position independent

Privileged

Trace

Postmortem Dump

Slave task

-SE

No SEND to task

Ancillary control processor

-AL

No checkpoint allocation 1

Revised network protocol

1 The combination of not checkpointable with
checkpoint
allocation (100000) is illogical and should not be used.

D-9

IMPROVING TASK BUILDER PERFORMANCE
Table D-2
Map File Switch Defaults
Switch Category:
Switch Word:

Map file

$DFLBS

Initial Contents:

120000

Switch.Settings:
Bit

Condition if Set to 1

-MA

Switch Category:
Switch Word:

Do not include system
files in map

library

Map file

$DFMAP

Initial Contents:

2040

Switch Settings:
Bit

Condition if Set to 1

Short map

-SP

Do not spool

Cref

Wide format

Table D-3
Symbol Table File Switch Defaults
Switch Category:
Switch Word:

Symbol table file

$DFSTB

Initial Contents:

Switch Settings:
Bit

Condition if Set to l

-HD

Build task without header

Task is position independent

D-10

and

STB

IMPROVING TASK BUILDER PERFORMANCE
Table D-4
Input File Switch Defaults
Switch Category:
Switch Word:

Input file

$DFINP

Initial Contents:

000100

Switch Settings:
Bit

D.3

Condition if Set to l

-MA

Do not include1 file contents in map

File contains two or
object modules

concatenated

THE SLOW TASK BUILDER

The TKB.TSK and BIGTKB.TSK versions of the Task Builder each use a
symbol table structure that can be searched quickly,
but which
requires more work file space than previous versions.
You may thus
receive the following message in some instances:
NO VIRTUAL MEMORY STORAGE AVA! LABLE
If this occurs, you should try to reduce the work file size by using
the procedures described in Section D.l.
If these procedures do not
sufficiently reduce the work file size, you can link a
third version
of
the Task Builder,
the Slow Task Builder. This version requires
less storage, but runs considerably slower than the other versions.
The build file is SLOTKBBLD.CMD which resides on the same device and
UFD as the other Task Builder command files.

D-11

APPENDIX E
THE FAST TASK BUILDER

The Fast Task Builder (FTB) is intended for use as a load-and-go
of linker.
It contains very few options and does not support:
•

New map format

•

Overlaid programs

•

Linking to resident libraries

•

Production of symbol table files

•

Creation of resident libraries

•

Privileged tasks

The supported switches are:
/SP on map file

(default

/SP)

/CP on task file

(default

/CP)

/MM on task file

(default

/MM)

/FP on task file

(default

/FP)

/DA on input or task image (default

/-DA)

The support option inputs are:
ASG

(same defaults as TKB)

STACK

(same default as TKB)

UNITS
EXTSCT
ACTFIL

(same default as TKB)

MAXBUF

(same default as TKB)

1 No checkpoint space is allocated in the task image file.

E-1

type

THE FAST TASK BUILDER
FTB allocates symbol table space from the end of its image to the end
of the partition. It does not have a virtual symbol table. An Extend
Task or equivalent of 8K is recommended.
FTB does not dynamically
extend itself at run time.
FTB runs approximately four times faster than TKB on an 11/70 with
RP04s when TKB is running with a totally resident symbol table. In
smaller systems with slower disks, the ratio should be much higher.

E-2

APPENDIX F
ERROR MESSAGES

The Task Builder produces diagnostic and fatal error messages.
messages are printed in the following forms:

Error

'rKB -- *DIAG*-error-message
or
TKB -- *FATAL*-error-message
Some errors are correctable when command input is from a terminal. In
such a case, a diagnostic error message can be printed, the error
corrected, and the task building sequence continued. However, if the
samE~
error is detected in an indirect command file, a correction
cannot be made, and the Task Builder aborts.
diagnostic error messages merely advise you of an unusual
condition.
If you consider the condition normal for your task, you
can install and run the task image.

SomE~

NOTE
The Task Builder exits with 2 statuses:
it returns an ERROR status when it
encounters a diagnostic error and a
SEVER ERROR when it encounters a fatal
error.
(For more information about the
Exit-With-Status
directive,
see the
RSX-llM/M-PLUS
Executive
Reference
Manual.)
This appendix tabulates the error messages produced by the Task
Builder.
Most of the messages are self-explanatory. In some cases,
the line in which the error occurred is printed.
A Software Performance Report (SPR) should be submitted to DIGITAL in
cases where the explanation accompanying a message refers to a system
error.
ALLOCATION FAILURE ON FILE file-name

The Task Builder could not acquire sufficient disk space to store
the task image file, or did not have write-access to the UFD or
volume that was to contain the file.

F-1

ERROR MESSAGES
BLANK P-SECTION NAME IS ILLEGAL
overlay-description-line
The overlay-description-line printed contains a .PSECT
that does not have a p-section name.

directive

COMMAND I/O ERROR
I/O error on command input device.
possible hardware error.)

(Device may not be online, or

COMMAND SYNTAX ERROR
command-line
The command-line printed has incorrect syntax.
COMPLEX RELOCATION ERROR - DIVIDE BY ZERO:
module-name

MODULE

A divisor having the value zero was detected
in a complex
expression. The result of the divide was set to zero.
(Probable
cause - division by a global symbol whose value is undefined.)
FILE file-name ATTEMPTED TO STORE DATA IN VIRTUAL SECTION
The file contains a module that has
virtual section with data.

attempted

initialize

FILE file-name HAS ILLEGAL FORMAT
The file file-name contains an object module whose format is
valid.

not

ILLEGAL APR RESERVATION
An APR specified in a COMMON, LIBR, RESCOM, or RESLIB keyword
outside the range 0-7.

ILLEGAL D~FAULT PRIORITY SPECIFIED
option-line
The option-line printed contains a priority greater than 250.
ILLEGAL ERROR-SEVERITY CODE octal-list
System error (no recovery). An SPR should be submitted with
copy of the message containing the octal-list as printed.

ILLEGAL FILENAME
invalid-line
The invalid-line printed contains a wild card
(*)
specification. The use of wild cards is prohibited.

file

ILLEGAL GET COMMAND LINE ERROR CODE
System error (no recovery).
ILLEGAL LOGICAL UNIT NUMBER
invalid-line
The invalid-line printed contains a device assignment to a unit
number larger than the number of logical units specified by the
UNITS keyword or assumed by default if the UNITS keyword is not
used.

F-2

ERROR MESSAGES
ILLEGAL MULTIPLE PARAMETER SETS
invalid-line
The invalid-line printed contains multiple sets of parameters for
a keyword that allows only a single parameter set.

ILLEGAL NUMBER OF LOGICAL UNITS
invalid-line
The invalid-line printed contains a logical unit
than 250.

number

greater

ILLEGAL ODT OR TASK VECTOR SIZE
ODT or SST vector size specified greater than 32 words.

ILLEGAL OVERLAY DESCRIPTION OPERATOR
invalid-line
The invalid-line printed contains an unrecognizable operator
in
an overlay description.
This error occurs if the first character
in a p-section or segment name is a dot (.).

ILLEGAL OVERLAY DIRECTIVE
invalid-line
The
invalid-line
directive.

printed

contains

unrecognizable

overlay

ILLEGAL PARTITION/COMMON BLOCK SPECIFIED
invalid-line
User defined base or length not on 32-word boundary.

ILLEGAL P-SECTION/SEGMENT ATTRIBUTE
invalid-line
The invalid-line printed contains a program
attribute that is not recognized.

section

segment

ILLEGAL REFERENCE TO LIBRARY P-SECTION p-sect-name
A task has attempted to reference a p-sect-name existing
in a
shared
region but has not named the shared region in a keyword.
This error will occur when you explicitly specify an STB file as
an input file but you have not specified the library to which the
STB file belongs in an option.

ILLEGAL SWITCH
file-specification
The file-specification printed
switch value.

contains

illegal

switch

INCOMPATIBLE REFERENCE TO LIBRARY P-SECTION p-sect-name
A task has attempted to reference more storage in a shared region
than exists in the shared region definition.

INCORRECT LIBRARY MODULE SPECIFICATION
invalid-line
The invalid-line contains
character.

module

F-3

name

with

non-Radix-50

ERROR MESSAGES
INDIRECT COMMAND SYNTAX ERROR
invalid-line
The
invalid-line printed contains
indirect file specification.

syntactically

incorrect

INDIRECT FILE OPEN FAILURE
invalid-line
The invalid-line contains a reference to
which could not be located.

command

input

file

INSUFFICIENT PARAMETERS
invalid-line
The invalid-line contains a keyword with an
of parameters to complete its meaning.

insufficient

number

INVALID APR RESERVATION
invalid-line
APR specified on a keyword for an absolute library.

INVALID KEYWORD IDENTIFIER
invalid-line
The invalid-line printed contains an unrecognizable keyword.

INVALID PARTITION/COMMON BLOCK SPECIFIED
invalid-line
Partition is invalid for one of the following reasons:
1.

The Task Builder cannot find the partition name in
system in order to get the base and length.

The system is mapped, but the base address of the partition
is not on a 4K boundary for a non-runnable task or is not 0
for a runnable task.

The memory bounds for the partition overlap a shared region.

The partition name is identical to the name of
defined COMMON or LIBR shared region.

The top address of the partition for a runnable task exceeds
32K minus 32 words for a mapped system, or exceeds 28K minus
1 for an unmapped system.

A system-controlled partition was specified for
system.

the

host

previously

unmapped

INVALID REFERENCE TO MAPPED ARRAY BY MODULE module-name
The module has attempted to
initialize the mapped array with
data.
An SPR should be submitted if this problem is caused by
DIGITAL-supplied software.

F-4

ERROR MESSAGES
WINDOW BLOCK SPECIFICATION
inva1lid-line

INVJl~LID

The number of extra address windows specified exceeds the number
permitted.
On an RSX-llM system, you can specify as many as 7
extra window blocks;
on an RSX-llM-PLUS system, you can specify
as many as fifteen extra window blocks.
If you build a task on an RSX-llM system and specify more window
blocks,
you get this error message, but the task will build.
HowevE~r, it cannot be installed and run on an RSX-llM system.
I/O ERROR LIBRARY IMAGE FILE
An I/O error has occurred during an attempt to open or
Task Image File of a shared region.

read

the

I/O ERROR ON INPUT FILE file-name
This E~rror occurs when the Task Builder cannot read an input file
specification (for example, when the command line is greater than
eighty characters).
I/O ERROR ON OUTPUT FILE file-name
LABEL OR NAME IS MULTIPLY DEFINED
invalid-line
The invalid-line printed defines a name that has already appeared
as a .FCTR, .NAME, or .PSECT directive.
LIBRARY FILE filename HAS INCORRECT FORMAT
A module has been requested from a library file that has an empty
module name table.
LIBRARY REFERENCES OVERLAID LIBRARY
invalid-line
An attempt was made to link the resident library being built to a
shared region that has memory-resident overlays.
LOAD ADDR OUT OF RANGE IN MODULE module-name
An attempt has been made to store data in the task image outside
the address limits of the segment.
This problem is usually
caused by one of the following:

an attempt to initialize a p-section
region

an attempt to initialize an absolute location
limits of the segment or in the task header

a patch outside the limits of the segment it applies to

an attempt to initialize a segment having the NODSK attribute

cont~ined

shared

outside

the

LOOKUP FAILURE ON FILE filename
invalid-line
The invalid-line printed contains
located in the directory.

F-5

filename

that

cannot

ERROR MESSAGES
LOOKUP FAILURE ON SYSTEM LIBRARY FILE
The
Task
Builder
cannot
find
the
system
(SYO:[l,l]SYSLIB.OLB) file to resolve undefined symbols.

Library

LOOKUP FAILURE RESIDENT LIBRARY FILE
invalid-line
No symbol table or task image file can be found
region.

for

the

shared

MAXIMUM INDIRECT FILE DEPTH EXCEEDED
invalid-line
The invalid-line printed gives the file reference
the permissible indirect file depth (2).

that

exceeded

MODULE module-name AMBIGUOUSLY DEFINES P-SECTION p-sect-name
The p-section p-sect-name has been defined in two modules not on
a common path,
and referenced from a segment that is common to
both paths.
MODULE module-name AMBIGUOUSLY DEFINES SYMBOL sym-name
Module module-name references or defines a symbol sym-name whose
definition exists on two different paths, but is referenced from
a segment that is common to both paths.
MODULE module-name ILLEGALLY DEFINES XFR ADDRESS p-sect-name addr

The start address printed is odd.

The module module-name is in an overlay segment and has a
start address.
The start address must be in the root segment
of the main tree.

The address is in a p-section that has not yet been defined.
An
SPR
should
be
submitted
if this
is caused by
DIGITAL-supplied software.

MODULE module-name MULTIPLY DEFINES P-SECTION p-sect-name

The p-section p-sect-name has been defined more than once
the same segment with different attributes.

A global p-section has been defined more than once with
different attributes in more than one segment along a common
path.

MODULE module-name MULTIPLY DEFINES SYMBOL sym-name
Two definitions for the relocatable symbol sym-name have occurred
on a common path.
Or two definitions for an absolute symbol with
the same name but different values have occurred.
MODULE modu1e-name MULTIPLY DEFINES XFR ADDR IN SEG
segment-name
This error occurs when more than one module making
has a start address.

F-6

the

root

ERROR MESSAGES
MODULE module-name NOT IN LIBRARY
The Task Builder could not find the module named on the LB switch
in the library.
NO DYNAMIC STORAGE AVAILABLE
The Task Builder needs additional symbol table storage and cannot
obtain it.
(If possible, install the Task Builder in a larger
partition.)
NO MEMORY .~VAILABLE FOR LIBRARY library-name
The Task Builder could not find enough free virtual memory to map
the specified shared region.
NO ROOT SEGMENT SPECIFIED
The overlay description did not contain a .ROOT directive.
NO VIRTUAL MEMORY STORAGE AVAILABLE
Maximum permissible size of the work file exceeded.
The user
should consult Appendix D for suggestions on reducing the size of
the work file.
OPE!f FAILURE ON FILE file-name
OPTION SYNTAX ERROR
invalid-line
The invalid-line printed contains unrecognizable syntax.
OVERLAY DIRECTIVE HAS NO OPERANDS
invalid-line
All overlay directives except .END require operands.
OVEHLAY DIRECTIVE SYNTAX ERROR
invalid-line
The invalid-line printed contains a syntax error or references
line that contains an error.

PARTITION partition-name HAS ILLEGAL MEMORY LIMITS
1.

The partition-name defined in the
address alignment that is not
system.

The user has attempted to build a privileged task in a
partition whose length exceeds the task's available address
space (8K or 12K).

host system has a base
compatible with the target

PASS CONTROL OVERFLOW AT SEGMENT segment-name
System error. An SPR should be submitted with a copy of the
file associated with the error.

ODL

PIC LIBRARIES MAY NOT REFERENCE OTHER LIBRARIES
invalid-line
The user has attempted to build a position-independent
region that references another shared region.

F-7

shared

ERROR MESSAGES
P-SECTION p-sect-name HAS OVERFLOWED
A section greater than 32K has been created.
REQUIRED INPUT FILE MISSING
At least one input file is required for a task-build.
REQUIRED PARTITION NOT SPECIFIED
The PAR keyword was not used when running the Task Builder on an
RSX-llD host system.
The keyword must contain explicit base
address and length specifications.
RESIDENT LIBRARY BAS INCORRECT ADDRESS ALIGNMENT
invalid-line
The invalid-line specifies a shared region that has
following problems:

one

the

The library references another library with invalid
address bounds
(i.e.,
not on 4K boundary in a mapped
system).

The library has invalid address bounds.

RESIDENT LIBRARY MAPPED ARRAY ALLOCATION TOO LARGE
invalid-line
The invalid-line printed contains a reference to a shared region
that has allocated too much memory in the task's mapped array
area.
The total allocation exceeds 2.2 million bytes.
RESIDENT LIBRARY MEMORY ALLOCATION CONFLICT
keyword-string
One of the following problems has occurred:
1.

More than seven shared regions have been specified.

A shared region has been specified more than once.

Non-position-independent shared regions
allocations overlap, have been specified.

whose

memory

ROOT SEGMENT IS MULTIPLY DEFINED
invalid-line
The invalid-line printed contains the second
.ROOT
encountered. Only one .ROOT directive is allowed.
SEGMENT seg-name HAS ADDR OVERFLOW:

directive

ALLOCATION DELETED

Within a segment, the program has attempted to allocate more than
32K. A map file is produced, but no task image file is produced.
TASK HAS ILLEGAL MEMORY LIMITS
An attempt has been made to build a task whose size exceeds the
partition boundary.
If a task image file was produced, it should
be deleted.

F-8

ERROR MESSAGES
TASK HAS ILLEGAL PHYSICAL MEMORY LIMITS
mapped-array

task-image

task extension

The sum of the parameters displayed -- mapped array size,
task
image size, and task extension -- exceeds 2.2 million bytes.
The
quantities are shown as octal numbers in units of 64-byte blocks.
Any resulting task image file should be deleted.

TASK IMAGE :FILE filename IS NON-CONTIGUOUS
Insufficient contiguous disk space was available to contain the
task
image.
A non-contiguous file was created. After deleting
unnecessary files, the /CO switch in PIP should be used to create
a contiguous copy.

TASK REQUIRES TOO MANY WINDOW BLOCKS
The number of address windows required by the task and any shared
regions, exceeds 8 for RSX-llM tasks and sixteen for RSX-llM-PLUS
tasks.

TASK-BUILD ABORTED VIA REQUEST
option-line
The option-line contains a request from the
task-build.

user

abort

the

TOO MANY NESTED .ROOT/.FCTR DIRECTIVES
invalid-line
The invalid-line printed contains a .FCTR directive that
the maximum nesting level (16).

exceeds

TOO MANY PARAMETERS
invalid-line
The invalid-line printed contains a keyword with more
than required.

parameters

TOO MANY PARENTHESES LEVELS
invalid-line
The invalid-line printed contains a parenthesis that exceeds
maximum nesting level (16).

the

TRUNCATION ERROR IN MODULE module-name
An attempt has been made to load a global value greater than +127
or less than -128
into a byte. The low-order eight bits are
loaded.

UNABLE TO OPEN WORK FILE
The work file device is not mounted.
(The work file
located on the same device as the Task Builder.)

UNBA.LANCED PARENTHESES
invalid-line
The invalid-line printed contains unbalanced parentheses.

F-9

usually

ERROR MESSAGES
n UNDEFINED SYMBOLS SEGMENT seg-name
If no memory
The segment named contains n undefined symbols.
allocation file is requested, the symbols are printed on the
terminal.
VIRTUAL SECTION HAS ILLEGAL ADDRESS LIMITS
option-line
The option-line printed contains a VSECT
address plus window size exceeds 177777.

keyword

whose

base

I/O error during an attempt to reference data stored by the
Builder in its work file.

Task

WORK FILE I/O ERROR

F-10

INDEX

A
Access code,
grouping program sections by, 6-38
Active Page Register (APR), 2-10
declaring supervisor-mode 6-69
declaring system-owned
supervi.sor-mode, 6-7 3
reserving for system-owned shared
region, 6-52, 6-66
specifying, 6-5
Supervisor-mode, 3-32
Addresses,
Assignment of, 2-1
ALSCT subroutine, 3-56
APR, see Active Page Register
Asterisk,
in cross-reference listing, 6-11
in global cross-reference, 5-10
At sign (@), 1-5
in cross-reference listing, 6-11
in global cross-reference, 5-10
see also directives and operators
Attribute GBL
in .NAME directive, 5-5
$AUTO,
Autoload routine, 5-4
Autoload, 5-1
error handling, 5-8
Indicator, 5-2, 5-3
Autoloadable,
making file names, 5-2
making program sections, 5-2
Autoload vectors
efficient generation of, 5-5

B
.BLK see program sections, blank

c
Circumflex,
in cross-reference listing, 5-9
6-11
, (comma) , see directives and
operators
Command file,
indirect, 1-5
interaction with indirect, 1-6
levels of indirection, 1-7
Command line,
comments in 1-7
form, 1-2
Multiple line input, 1-3
option input, 1-3
order of output files, 1-2
terminating character, 1-3, 1-5

Completion Routine, 3-33
Contents of a, 3-35
example of, 3-35
Concatenated object modules,
using to reduce Task Builder
overhead, D-5
Co-trees, 4-28
resolution of global symbols
in, 4"'"19
Co-tree segment,
affecting symbol search on, 6-16
CTRL/Z
effect on Task Builder, 6-48

D
Data Structures,
building, 2-1
overlay, 4-20
Default library,
controlling search for symbols
in, 6-16
Device common,
development of a, 3-19
establishing physical addresses
for a, 3-20
Directives and operators,
Overlay Description Language,
4-22
.ROOT, 4-22
.END, 4-22
. FCTR, 4-24
! (exclamation point) , 4-24
.NAME, 4-25
.PSECT, 4-27
@ (at sign)
, (comma) , 4-23
- (hyphen) , 4-23
Disk image, 2-14
Multiuser task, 3-46
Double colon(::), 3-19

E
.END, see directives and operators
(exclamation point), see directives and operators
Examples,
Example 1: Building and linking
to a common in MACRO~ll, 3-11
Example 2: Building and linking
to a device common in MACR0-11,
3-19
Example 3: Building and linking
to a Resident library in
MACR0-11, 3-23
!

Index-1

INDEX
Examples (Cont.)
Example 4: Building and linking
to a supervisor-mode library
in MACR0-11, 3-32
Example 5: Building a Multiuser
task (RSX-llM-PLUS Only) , 3-44
Example 6: Building a task that
creates a dynamic region
Example 7: Building a Program
that uses a virtual program
section, 3-59
Example 8: Privileged tasks, 3-62
Example 9: Building An Overlay

F
.FCTR, see directives and operators
File names,
making components of autoloadable, 5-2
File specification,
defaults for, 1-8
conventions for, 1-8
FORTRAN common blocks, 4-19

G
GBL attribute,
in .NAME directive, 5-5
GEN partition, 6-64
Global symbol,
as address of ODT SST routine,
6-63
in autoloadable segment, 5-4
in cross-reference listing, 6-10
Global symbols,
ambiguously defined, 4-17
(co-tree) resolution of, 4-19
multiply-defined, 2-8, 4-7
resolution of, 2-7
resolving, 4-16
summary of resolution of, 4-17
undefined, 2-8

H
Header, 2-15
High-level language,
overlay programs written in 4-34
Host system,
building a task for another
system on, 7-1
- (hyphen) , see directives and
operators

Indirect command files, 4-27
Input,
aborting Task Builder, 6-48

Input file,
designating as debugging aid, 6-12
designating as library file, 6-18
directing selective global symbol
search on, 6-39
including contents of in map, 6-20
specifying as default library,
6-13
I/O page,
overlapping, 3-63

L
Label Block, 2-15
Library Object modules,
placing in an overlay structure,
6-19
Listing,
generating global cross-reference,
6-10
$LOAD routine, 5-6
Loading, asynchronous
example of, 5-8
LUN,
assigning physical devices to,
6-51

M
Manual load, 5-1
error handling, 5-8
FORTRAN calling sequence, 5-7
MACR0-11 calling sequence, 5-6
Map file, see memory allocation
file
Mapped Array Area, 3-54
Mapped regions,
declaring address windows for,
6-79
Memory Allocation file,
adding cross-reference to, 6-10
changing width of, 6-43
contents of, 6-29
description of, 6-32 to 6-35
example of, 6-29 to 6-31
general, 1-1
inhibiting spooling of, 6-37
Memory image, 2-15
Memory Management Unit, 2-10
Messages,
inhibiting system queing of, 6-28
Modules,
control of input to Task Builder,
6-7
extracting from library, 6-18
placing in segment to reduce
Task Builder overhead, D-5
Multisegment task,
see overlay structures,
see also overlay
Multiuser system
priority of tasks in, 6-65

Index-2

INDEX

Multiuser tasks, 3-44
declaring read-only partition for,
6-71

N
.NAME, see directives and operators
Number sign (#),
in cross-reference listing, 6-11

0
Obj1ect module,
contents of, A-1
overriding definition in, 6-57
using /SS on to include only
selective global symbols from,
16-39
Object module library file,
using /SS on to include
only selective global symbols
from, 16-39
Object Time System,
usage to extend record buffer,
6-62
ODL, see Overlay Description
Language,
Option,
categories of, 6-45
general form of, 1-4
processing, 3-8
sieparation of arguments lists, 1-4
options, 6-45 through 6-79
ABORT, 6-48
ABSPAT, 6-49
ACTFIL, 6-50
ASG, 6-51
CMPRT, 6-52
COMMON or LIBR' 6-53
EXTSCT, 6-54
EXTTSK, 6-55
FMTBUF, 6-56
GBLDEF, 6-57
GBLPAT, 6-58
GBLREF, 6-59
GBLXCL, 6-60
LIBR, 6-61
MAXBUF, 6-62
ODTV, 6-·63
PAR, 6-64
PRI, 6-65
RESCOM or RESLIB, 6-66
RESSUP, 6-69
ROPAR, 6-71
STACK, 6-72
SUPLIB, 6-73
TASK, 6-·7 4
TSKV, 6-·75
UIC, 6-76

Index-3

Option (Cont.)
UNITS, 6-77
VSECT, 6-78
WNDWS, 6-79
Overlay data structures, 4-20
Overlay description
effect on Task Builder
performance D-4
Overlay Description Langgage,
Autoload indicators in, 5-3
Autoload indicators placed
efficiently in, 5-5
directives and operators of, 4-22
.ROOT, 4-22
.END, 4-22
.FCTR, 4-24
! (exclamation point) , 4-24
.NAME, 4-25
.PSECT, 4-27
@ (at sign)
, (comma) , 4-23
- (hyphen) , 4-23
enabling memory-resident overlay
operator in, 6-27
summary of, 4-42
using indirect files with, 4-27
Overlay Description Language file,
declaring a, 6-22
Overlay operator,
enabling recognition of memoryresident, 6-27
suppression of memory-resident,
6-21
Overlay run-time, 4-20
Overlay segments,
Task Builder Processing of, 4-17
Overlay structures,
ambiguously defined global
symbols in, 4-17
classes of tasks handled
effectively by, 4-1
creating, 4-1
multiply defined global symbols
in a, 4-17
specifying library search in, 6-19
Overlay tree, 4-15
calling segments in an, 5-3
Overlays,
choosing whether to have memoryresident, 4-15
consuming physical memory when
using memory-resident, 4-15
defining multiple tree, 4-28
disk-resident, 4-2
loading disk-resident, 4-5
loading mechanism of, 4-16
loading of memory-resident, 4-10
loading methods, 5-1
loading synchronously and
asynchronously, 5-1

INDEX

Overlays (Cont.)
memory resident, 4-5
pathloading, 5-3
the effect on physical memory of
disk resident, 4-2
the effect on physical memory of
memory-resident, 4-7
the effect of virtual address
space of disk-resident, 4-2
the effect on virtual address
space of memory resident, 4-7

p
Page Address Register (PAR) , 2-10
Page Description Register (PDR) ,
2-10
Partition,
naming for target system, 7-1
pathloading, see overlays
PMD task,
installation for timely
operation, 8-1
Postmortem Dump,
description of contents, 8-4, 8-5
Sample of, 8-1
Privileged tasks,
accessing Executive with, 3-62
accessing I/O page with, 3-62
building, 3-62
Program Sections,
allocation of, 2-2
attributes of, 2-4
blank, 2-3, 3-4, 3-13
creating a, 2-3
elements of a, 2-2
explicitly specifying a, 4-19
making autoloadable, 5-2
ordering of, 3-4
(overlay structure) allocation
of, 4-19
restrictions of names for, 3-10,
3-31, 3-38
sequential ordering of adjacency
requirements for, 6-38
Program,
steps in the development of, 1-1
.PSECT, see directives and,
operators,
PSECT see program sections

R
Region descriptors, 4-21
Resident common,
building and linking to a, 3-11
device, 3-19
establishing offsets in, 3-11,
3-16

loading a, 3-14
steps in building a, 3-11
typical, 3-1
Resident library,
building a, 3-23
typical, 3-1
Resident Shared Region
absolute, 3-6
allocation of APRs for, 3-8
allocation of window blocks for,
3-8
declaring position independent
6-24
'
definition of, 3-1
including symbol definitions in
map file, 6-20
initializing window blocks for, 3-8
installing, 3-3, 3-10
linking to a, 3-6
options for linking to, 3-6
position independent, 3-3
precautions when specifying
position-independent, 3-4
procedure for building a, 3-3
restriction on position indepen-'
dent, 3-10
specifying partitions for, 3-3
specifying position-independent
3-4
I
type of access to, 3-8
using to reduce TKB overhead D-5
RLSCT subroutine, 3-56
'
Root segment,
defining completion routine in
6-52
'
global symbol as ODT SST vector
in, 6-63
.ROOT, see Directives and operators

s
Search of libraries, 6-18
Segment,
call to up-tree, 5-3
definition of a, 4-1
making autoloadable, 5-3
patching a, 6-49
patching by offset, 6-58
Segments,
limiting number of to reduce Task
Builder overhead, D-5
properly loading when called loading as part of co-tree, 5-2
Semicolon (;), 1-7
Slash,
double (//), 1-5
single (/), 1-3, 1-6

Index-4

INDEX

Snapshot dump
jaxample of, 8-8
format of Macro for creating, 8-7
Snapshot dump control block,
format ~f macro for, 8-6
SS switch,
using to reduce Task Builder
overhead, D-5
.s~rB file see Symbol Definition
file
Supervisor-mode library,
identifying completion routine
in I 6-52
\
linking to a, 3-32
restriction on contents of, 3-35
typical mapping for, 3-33
Supervisor vector, 3-33
$SUPL routine, 3-33
Switches,
l\C [ : n ] , 6 - 5
l\L I 6-6
CC, 6-7
CM, 6-8
CPI 6-9
CR, 6-10
DA I 6-12
DL I 6-13
EA I 6-14
}i'p I
6-1.5
Ji'U I 6-16
HD, 6-17
LB I 6-18
MA, 6-20
MM, 6-21
MP I 6-22
MU I 6-2.3
PI I 6-24
PM, 6-25
PR, 6-26
HO I 6-27
SE I 6-28
SH, 6-29
SL, 6-36
SP I 6-37
SQ, 6-38
SS I 6-39
']~R, 6-42
WI, 6-43
XT [ : n] , 6- 4 4
conflicts in, 6-1
Symbol Definition file,
contents of a, 3-3
E~xcluding symbols from a, 3-37,
6-60
for system-owned shared region,
6-52
for system-owned supervisor-mode
library, 6-73
for user-owned shared region, 6-67
for user-owned supervisor-mode
library, 6-69
Index-5

Symbol Definition file (Cont.)
specifying a, 3-3
UFD for, 3-8
using /SS on to include only
selective global symbols from,
16-39
using /SS on to reduce Task Builder overhead, D-5
Symbols,
affecting search for undefined,
6-16
in cross-reference listing, 6-11
Syntax rules,
summary of, 1-9
SYSLIB see system object module
library
System-controlled partition,
extendingmemory for task in, 6-55
System Object Module Library, 2-7
including contributions from in
map, 6-20
replacin.g as default, 6-13

T
Task,
allocating additional memory for
a, 6-55
assigning physical devices to
LUNs, 6-51
attaching slave attribute to, 6-36
building for target system, 7-1
changing alignment of memory-resident overlay segments in, 6-8
changing name of, 6-74
creating multiuser, 6-23, 3-44
data needed by system to install,
B-1
declaring access to system-owned
shared region, 6-52
declaring access to system-owned
supervisor-mode library, 6-73
declaring access to user-owned
supervisor-mode library, 6-69
declaring access to user-owned
shared region, 6-66
declaring additional address
windows for, 6-79
declaring execution priority for
6-65
declaring global symbol
references in a, 6-59
declaring length of format buffer
in a, 6-56
declaring maximum stack size of,
6-72
declaring number of active files
for, 6-50
declaring number of LUNs for, 6-77

INDEX
Task (Cont.)
declaring object-level patches
for, 6-49
declaring ODT SST vector in, 6-63
declaring read-only partition for
multiuser, 6-71
declare record buffer size maximum, 6-62
declaring synchronous system trap
vector address for a, 6-74
declaring UIC for time-based
schedule request, 6-76
effect of program section order
in creating, 6-38
enabling memory-resident overlay
operator, 6-27
enabling Postmortem Dump for, 6-25
enabling T-bit trace trapping in,
6-42
establishing privileged access
rights for, 6-26
example of transferring from host
to target system, 7-1
extending a program section in a,
6-54
extending to partition length,
6-64
identifying partition for, 6-64
including debugging aid (ODT) in,
6-12
indicating system mapping status
of, 6-21
inhibiting queuing of messages to,
6-28
list of attributes, 6-32, 6-33
making checkpointable, 6-9
patching relative to global
symbol, 6-58
relocation of, 2-10, 2-16
specifying as ancillary control
processor, 6-5
specifying use of floating point
processor in, 6-15
specifying use of KEll-A in, 6-14
specifying virtual program
section for a, 6-78
Task Builder,
exit on errors, 6-44
functions, 2-1
improving performance of, D-1 to
D-7 .
main function, 1-1
option for restarting input to,
6-48

Task Builder (Cont.)
reserved symbols for, C-1
virtual memory error messages,
D-5, D-6
Task header,
controlling creation of, 6-17
space for EAE context, 6-14
space for floating point context,
6-15
Task image,
allocating additional (checkpoint)
space in, 6-6
checkpoint area within, B-7
d~fault type, 1-8
Task memory, 2-15

Index-6

u
UFD
for Postmortem Dump, 8-1
Unamed program section, see blank
program section

v
Virtual address space,
mapped system, 2-10
unmapped system, 2-8
Virtual program section,
allocating physical memory to a,
3-56
building a task that uses a, 3-59
creating a, 3-53
specifying base address for a,
3-54
specifying physical size for a,
3-54
specifying window blocks for a,
3-59
specifyingwindow size for a, 3-54
support for a, 3-53

w
Window, 2-16
Window blocks, 2-16
creating, 3-50
Window descriptors, 4-21
Work file,
changing device to improve Task
Builder performance, D-6
Wrap around,
window, 3-56

RSX-llM/M-PLUS
Task Builder Manual
AA-H266A-TC
READER'S COMMENTS

NOTE:

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

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

Did you find errors in this manual?
pac;re number.

If so, specify the error and the

PlE!ase 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 _ _ _ _ _ _ _ _ _ _ __

Or9anization--~----------------------------

Street
Ci 1:.Y.---·----------- S t a t e - - - - - - - Zip Code _ _ _ _ _ __
or
Country

Do Not Tear - Fold Here and Tape -

~n~nomo

No Postage
Necessary
if Mailed in the
United States

1111 '

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

RT/C SOFTWARE PUBLICATIONS TW/A14
DIGITAL EQUIPMENT CORPORATION
1925 ANDOVER STREET

01876

TEWKSBURY, MASSACHUSETTS

Do Not Tear - Fold Here