Digital PDFs

AA-5072D-TC

August 1990

350 pages

Original

101MB

Document:	RSTS/E V10 Task Builder Reference Manual
Order Number:	AA-5072D-TC
Revision:	0
Pages:	350
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsts_e/V10/AA-5072D-TC_RSTS_E_V10_Task_Builder_Reference_Manual_Aug1990.pdf

OCR Text

RSTS/E Task Builder Reference Manual
Order Number: AA-50720-TC

ware

RSTS/E Task Builder Reference Manual
Order Number: AA-5072D-TC

August 1990
This document describes the RSTS/E Task Builder (TKB). and tells how you use it to link
programs.

Operating System and Version: RSTS/E Version 10.0
Software Version:

digital equipment corporation
maynard, massachusetts

RSTS/E Version 10.0

August 1990
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 not supplied
by Digital Equipment Corporation or its affiliated companies.
Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer
Software clause at DFARS 252.227-7013.

© Digital Equipment Corporation 1990. All rights reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document requests
the user's critical evaluation to assist in preparing future documentation. The following are
trademarks of Digital Equipment Corporation:
ALL-IN-1
DEC/CMS
DECdx
DEC/FMS-11
DECmaii
DECnet
DECnetiE
DECSA
DECserver
DECsystem-10
DECSYSTEM-20
DECUS
DECworld
DELUA
DEONA

DEUNA
DIBOL
EDT
lAS
LA
LN01
Micro/RSX
OS/8
PDP
PDP-11
PDT
a-BUS
RMS-11
RSTS

RSX
RT
RT-11
TOPS-10
TOPS-21
ULTRIX
UNIBUS
VAX
VAXmate
VMS
VT
WPS-PLUS
Rainbow

~BmBDmDm

IBM is a registered trademark of International Business Machines Corporation.
RMS is a trademark of American Management Systems, Inc.

Contents
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 1
1.1

1.2

Part I

Introduction
What the Task Builder Does ................................... .
1.1.1
Linking ........................................... .
1.1.2
Overlays .......................................... .

1-2
1-2

Relationship to the DCL LINK Command .......................... .

1-4

1-3

Getting Started

Chapter 2
2.1

2.2

2.3

2.4

Building Programs
Job Area ................................................. .
2.1.1
Your Program Within the Job Area ........................ .

2-2

Libraries
2.2.1
2.2.2
2.2.3

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

Disk Libraries ...................................... .
Resident Libraries ................................... .
Comparison of Disk and Resident Libraries .................. .

How to Run the Task Builder .................................. .
2.3.1
Command Line ..................................... .
2.3.2
Multiline Command ................................... .
2.3.3
Options .......................................... .
2.3.4
The LlBR and RESLIB Options .......................... .
The CLSTR Option .................................. .
2.3.5
Examples of Simple Builds .................................... .
2.4.1
BASIC-PLUS-2 Examples Including Disk, Resident, and Cluster
Libraries .......................................... .
2.4.2
PDP-11 COBOL Example Including Two Disk Libraries ........... .
2.4.3
COBOL-81 Examples Including Disk Library and Cluster Libraries ... .
2.4.4
DIBOL Example Including Disk and Resident Libraries ........... .
2.4.5
FORTRAN-77 Examples Including One Disk Library ............ .
2.4.6
MACRO Examples Including Resident Libraries ............... .

2-2

2-7
2--8

2-9
2-10
2-10
2-11
2-14

2-15
2-16

2-16
2-16
2-17
2-17

iii

Part II

Overlays

Chapter 3
3.1
3.2

What are Overlays? ......................................... .

3-2
3-3
3-3

3.2.1
3.2.2
3.2.3
3.2.4

Constructing an ODL File: .ROOT, .FCTR, and .END Commands ......... .
The .ROOT Command ................................ .
The .FCTR Command ................................ .
The .END Command ................................. .
Flexibility of the Overlay Description Language ................ .

3-5
3-5

3.3

Using an ODL File When You Run TKB ........................... .

3-6

3.4

The Memory Map File ........................................ .

3-6

3.5

Designing Overlays Intelligently: Considering Space and Time .......... .
3.5.1
Considering Space: Two Possibilities for Example .............. .
3.5.2
Considering lime: Reducing Disk Access ................... .

3-7

3.6

Logical Independence of Items in Overlay Structure .................. .

3-10

3.7

Resolution of Global Symbols .................................. .
3.7.1
What Is a Global Symbol? .............................. .
3.7.2
Undefined, Multiply Defined, and Ambiguously Defined Global
Symbols .......................................... .
3.7.3
How Routines Are Inserted from Libraries ................... .
3.7.4
The Default Library .................................. .

3-11

Chapter 4

The Basic Concepts

3-4

3-8
3-9

3-11

3-12
3-13
3-15

Co-Trees: Another Way to Save Space

4.1

The Co-Tree Structure ....................................... .

4-1

4.2

Using the .NAME Command for a Co-Tree Root ....................•.

4-4

4.3

Designing the Most Space-Saving Co-Trees ........................ .

4-5

4.4

Co-Trees and High-Level Languages ............................. .
4.4.1
Sample Source Program and Subprograms .................. .
4.4.2
Outlining the Sample Program's Call Structure ................ .
4.4.3
Compiling the Sample Program and Subprograms .............. .
4.4.4
First Build for Sample Program: Putting Subprograms in the Root ... .
4.4.5
Second Build for Sample Program: Using a Co-Tree ............ .
4.4.6
Third Build for Sample Program: Restructured Tree and Library Routines
in Root ........................................... .
4.4.7
Further lips ....................................... .
4.4.8
Using Co-Tree Techniques with the Default Library ............. .

4-6
4-6

4-7
4-8

4-9
4-10
4-15
4-17
4-17

Chapter 5

(

The Autoload Indicator

5.1

What are Autoload Vectors?

5-1

5.2

Where are Autoload Vectors Really Needed? ....................... .

5-3

5.3

How to Request Specific Autoload Vectors ......................... .
5.3.1
Asterisk Before File Names and Program Sections ............. .
5.3.2
Asterisk Before Items in Parentheses ...................... .
5.3.3
Asterisk Before !'James Defined in .FCTR Commands ........... .
5.3.4
Asterisk Before Names Defined in .NAME Command ............ .

5-4
5-4

5.4

Example of Specific Autoload Vector Requests ...................... .

5-6

5.5

If You Make a Mistake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-6

Chapter 6

5-5
5-5
5-5

Working with Program Sections

6.1

What is a Program Section? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6-1

6.2

Allocating Space for Global Program Sections ...................... .

6-2

6.3

How the Task Builder Orders Program Sections ..................... .

6-3

6.4

The Task Builder's .PSECT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6-5

6.5

Using .NAME to Make a Data PSECT Autoloadable ................... .

6-5

6.6

More About Program Sections: Deciphering the Map ................. .
6.6.1
Source for Program USER ............................. .
6.6.2
Source for Subprogram INTRO . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6.3
Source for Subprogram CRUNCH ......................... .
6.6.4
Source for Subprogram CHATR . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6.5
Overlay Description File FRED.ODL ....................... .
6.6.6
Task Builder Command File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6.7
Task Builder Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6-6
6-8
6-8
6-8
6-8
6-8
6-9
6-9

Part III

Chapter 7

System Aspects

Building Your Own Memory-Resident Areas

7.1

What is a Resident Area? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-1

7.2

The Steps in Creating a Resident Area ........................... .

7-1

7.3

How to Build Memory-Resident Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3.1
Building Position-Independent Resident Areas ................ .
7.3.2
Building Absolute Resident Areas ......................... .

7-2
7-2
7-3

7.4

Resident Areas with Memory-Resident Overlays ..................... .
7.4.1
Specifying Memory-Resident Overlays ...................... .
7.4.2
Building Memory-Resident Overlays ....................... .

7-4
7-5
7-6

7.5

Building Your Own Cluster Libraries ............................. .
7.5.1
Rule 1: Position Independent or Built for Exact Address .......... .
7.5.2
Rule 2: Use Memory-Resident Overlays .................... .
7.5.3
Rule 3: No Required Parameters on the Stack ................ .
7.5.4
Rule 4: No Trap or Asynchronous Entry .................... .
7.5.5
Rule 5: No Calls to Routines in Another Cluster Library .......... .
7.5.6
Revectoring Cluster Libraries ............................ .
7.5.7
Sample Vector Table Code ............................. .
7.5.8
GBLXCL and GBLlNC Options ........................... .

7-9
7-9
7-10
7-10
7-12
7-12

7.6

FORTRAN Virtual Arrays ...................................... .

7-13

7.7

Virtual Program Selectors ..................................... .
7.7.1
FORTRAN Run-Time Support for Virtual Program Sections ........ .
7.7.1.1
The ALSCT Subroutine ........................ .
7.7.1.2
The RLSCT Subroutine ........................ .
Building a Program That Uses a Virtual Program Section ......... .
7.7.2

7-14
7-17
7-18
7-19
7-20

7.6

Advanced Programmed Region Control ........................... .
7.8.1
The EXTM$ Feature .................................. .

7-26

Fast-Mapping Facility ........................................ .
7.9.1
Fast-Mapping Code Provided by. TKB ...................... .
7.9.2
Programming Considerations ............................ .
7.9.2.1
Calling Sequence ............................ .
7.9.2.2
Returned Data .............................. .
7.9.2.3
Programming Examples ....................... .

7-28

7.9

Chapter 8

7-27

7-29
7-29
7-30
7-30
7-30

User-Mode I- and O-Space

6.1

User-Task Data Space ........................................ .

8-1

6.2

1- and D-Space Task Identification ............................... .

8-1

6.3

Comparison of Conventional Tasks and 1- and D-Space Tasks ........... .

8-1

6.4

Conventional Task Mapping ................................... .

8-2

6.5

1- and D-Space Task Mapping .................................. .

8-3

6.6

Designing an I-and D-Space Task ............................... .

8-4

6.7

Concurrent Libraries ......................................... .

8-4

Chapter 9

Supervisor-Mode Library

9.1

Mode-Switching Vectors ...................................... .

9-1

9.2

Completion Routines ........................................ .

9-2

9.3

Programming Considerations for the Contents of Supervisor-Mode
Libraries ................................................. .

9-2

9.4

7~
7~

Supervisor-Mode Library Mapping ............................... .
9.4.1
Supervisor-Mode Library Data ........................... .
9.4.2
Supervisor-Mode Libraries with 1- and D-Space Tasks ........... .

9-2
9-3
9-3

Building and Linking to Supervisor-Mode Libraries ................... .
9.5.1
Relevant TKB Options ................................ .
9.5.2
Mode-Switching Instruction ............................. .
9.5.2.1
Required Memory Layouts for Supported CSM
Instructions ................................ .
9.5.2.2
The CSM Library Dispatching Process .............. .

9-4

9.6

CSM Libraries ............................................. .
9.6.1
Building a CSM Library ................................ .
9.6.2
Linking to a CSM Library ............................... .
9.6.3
Example of a CSM Library and Building a Task ............... .
9.6.3.1
Building the Library SUPER ..................... .
9.6.3.2
Building TSUP .............................. .
9.6.3.3
Running TSUP ............................. .
9.6.4
Passing Parameters Using Stack Space .................... .

9-6
9-6
9-8
9-8
9-16
9-17
9-18
9-18

9.7

Using Supervisor-Mode Libraries as User-Mode Resident libraries ....... .

9-19

9.8

Multiple Supervisor-Mode Libraries

9-19

9.9

linking Supervisor-Mode Libraries

9-19

9.10

Writing Your Own Vectors and Completion Routines .................. .

9-19

9.11

Overlaid Supervisor-Mode Libraries .............................. .

9-20

9.12

Using ODT to Debug CMS Library ............................... .

9-20

9.13

Trap Handling with Supervisor Libraries ........................... .
9.13.1
Locating Service Routines .............................. .
9.13.1.1
FPPA$ AND SCCA$ .......................... .
9.13.1.2
SVTK$ and SVDB$ .......................... .

9-21
9-21
9-21
9-21

9.14

Building to a Supervisor-Mode RMS Library ........................ .

9-22

9.15

Map Supervisor D-Space ...................................... .

9-23

9.5
(
\

Part IV

9-5
9-5
9-5
9-5

Reference Section

Chapter 10

Task Builder Command Line Format

10.1

Running the Task Builder ..................................... .
10.1.1
Command Line ..................................... .
10.1.2
Multiline Command ................................... .

10-1
10-1
10-3

10.2

Options .................................................. .

10-3

10.3

Multiple Builds in One Run .................................... .

10-4

10.4

Indirect Command Files ...................................... .

10-4

10.5

Comments in Lines ......................................... .

10.6

File Specifications .......................................... .

10-6

vii

Chapter 11

viii

Task Builder Switches

11.1

ICC-Concatenated Programs and Subprograms

11-3

11.2

ICO-Bulld a Common Block Shared Region ....................... .

11-4

11.3

IDA-Debugging Aid ......................................... .

11-5

11.4

IDL-Default Library ......................................... .

11-6

11.5

IEL-Extend Library ......................................... .

11-7

11.6

IFM-Fast Map ............................................. .

11-8

11.7

IFO-Fast Map Overlay ....................................... .

11-9

11.8

IFP-Floating Point .......................................... .

11-10

11.9

IFU-Full Search ........................................... .

11-11

11.10

IHD-Header .............................................. .

11-12

11.11

IID-I- and D-Space ......................................... .

11-13

11.12

ILB-Library File ........................................... .

11-14

11.13

Ill-Build a Library Shared Region .............................. .

11-16

11.14

IMA-Map Contents of File .................................... .

11-17

11.15

IMP-Overlay Map .......................................... .

11-18

11.16

IMU-Multiuser Program ...................................... .

11-19

11.17

INM-No Diagnostic Messages ................................. .

11-20

11.18

IPI-Posltion Independent ..................................... .

11-21

11.19

IPM-Post-Mortem Dump ..................................... .

11-22

11.20

IRO-Resident Overlay ....................................... .

11-23

11.21

ISB-Slow BUild ............................................ .

11-24

11.22

ISG-Segregate Program Sections ............................... .

11-25

11.23

ISH-Short Map ............................................ .

11-26

11.24

ISP-Spool Map Output ...................................... .

11-32

11.25

ISO-Sequential ............................................ .

11-33

11.26

ISS-Selective Search ........................................ .

11-34

11.27

ITR-Traceable Program ...................................... .

11-36

11.28

IWI-Wide Listing Format ..................................... .

11-37

11.29

IXT[:n]-Exit on Error ........................................ .

11-38

Chapter 12

Task Builder Options

12.1

ABORT-Abort the Build ...................................... .

12-3

12.2

ABSPAT-Absolute Patch ..................................... .

12-4

12.3

ACTFIL-Number of Active Files ................................ .

12-5

12.4

ASG-Assign Devices ........................................ .

12-6

12.5

CLSTR-Cluster Libraries ..................................... ,

12-6

12.6

CMPRT-Completion Routine .................................. .

12-9

12.7

COMMON-Access System Common Block ........................ .

12-10

12.8

DSPPAT-Absolute Patch for D-Space ............................ .

12-11

12.9

EXTSCT-Extend Program Section .............................. .

12-12

12.10

EXTTSK-Extend Task Memory ................................. .

12-13

12.11

FMTBUF-Format Buffer Size .................................. .

12-14

12.12

GBLDEF-Define a Global Symbol ............................... .

12-15

12.13

GBLlNC-lnclude Global in .STB File ............................. .

12-16

12.14

GBLPAT-Global Relative Patch ................................. .

12-17

12.15

GBLREF-Global Symbol Reference ............................. .

12-18

12.16

GBLXCL-Exclude Global from .STB File .......................... .

12-19

12.17

HISEG-Deflne High Segment .................................. .

12-20

12.18

LlBR-Access System-Owned Resident Library ..................... .

12-21

12.19

MAXBUF-Maximum Record Buffer Size .......................... .

12-23

12.20

ODTV-ODT SST Vector ...................................... .

12-24

12.21

PAR-Partition for Resident Area ................................ .

12-25

12.22

RESCOM-Access Resident Common Block ........................ .

12-26

12.23

RESLlB-Access Resident Library ............................... .

12-27

12.24

RESSUP-Resident Supervisor-Mode Library ....................... .

12-29

12.25

RNDSEG-Round Segment .................................... .

12-30

12.26

STACK-Declare Stack Size ........................•...........

12-31

12.27

SUPLlB-Resident Supervisor-Mode Library ........................ .

12-32

12.28

TASK-Program Name for SYSTAT .............................. .

12-33

12.29

TSKV-Task SST Vector ...................................... .

12-34
ix

12.30

UNITS-Maximum Number of Units or Channels ..................... .

12-35

12.31

VARRAY - Virtual Array Specification and Usage ..................... .

12-36

12.32

VSECT-Virtual Program Section ................................ .

12-38

12.33

WNDWS-Number of Address Windows ........................... .

12-39

Chapter 13

Overlay Description Language (ODL)

13.1

ODL Command Line ......................................... .

13-1

13.2

The .END Command ......................................... .

13-2

13.3

The .FCTR Command ...............................•.........

13-2

13.4

The .NAME Command ........................................ .

13-2

13.5

The .PSECT Command ....................................... .

13-3

13.6

The .ROOT Command ........................................ .

13-4

13.7

Indirect Command Files

13-5

Appendixes

Appendix A

Error Messages

Appendix B

Task Builder Input Data Formats

B.1

Global Symbol Directory ...................................... .
8.1.1
Module Name ...................................... .
8.1 .2
Control Section Name ................................. .
Internal Symbol Name ................................ .
B.1.3
B.1 .4
Transfer Address .................................... .
8.1 .5
Global Symbol Name ................................. .
B.1.6
PSECT Name ...................................... .
B.1.7
Program Version Identification ........................... .
B.1.8
Mapped Array Declaration (Type 7) ........................ .
B.1.9
Completion Routine Definition (Type 10) .................... .

8-10
8-10
8-11

B.2

End of Global Symbol Directory ................................ .

8-12

B.3

Text Information ............................................ .

8-12

B.4

Relocation Directory ......................................... .
B.4.1
Internal Relocation ................................... .
B.4.2
Global Relocation ........................ : ........... .
B.4.3
Internal Displaced Relocation ............................ .
B.4.4
Global Displaced Relocation ............................ .
B.4.5
Global Additive Relocation .............................. .
B.4.6
Global Additive Displaced Relocation ...................... .

8-14
8-15
8-16
8-16
8-17
8-18
8-18

B-3
8-5
8-5

B-6
B-6
8-7

B-8

Location Counter Definition ............................. .
Location Counter Modification ........................... .
Program Limits ....................... ~ ............. .
PSECT Relocation ................................... .
PSECT Displaced Relocation ............................ .
PSECT Additive Relocation ............................. .
PSECT Additive Displaced Relocation ...................... .
Complex Relocation .................................. .
Additive Relocation .............................. " .... .

B-19
B-20
B-20
B-21
B-21
B-22
B-23
B-24
B-26

Internal Symbol Directory Record ............................... .
Overall Record Format . . . . . . . . . . . . . . . ................. .
8.5.1
B.5.2
TKB-Generated Records (Type 1) ......................... .
B.5.2.1
Start-of-Segment Item (Type 1) .................. .
B.5.2.2
Task Identification Item (Type 2) .................. .
Autoloadable Library Entry Point Item (Type 3) ........ .
8.5.2.3
Relocatable/Relocated Records (Type 2) .................... .
B.5.3
B.5.3.1
Module Name Item (Type 1) .................... .
Global Symbol Item (Type 2) .................... .
B.5.3.2
B.5.3.3
PSECT Item (Type 3) ......................... .
8.5.3.4
Line-number or PC Correlation Item (Type 4) ......... .
Internal Symbol Name Item (Type 5) ............... .
B.5.3.5
Literal Records (Type 4) ............................... .
B.5.4

B-26
B-27

B.4.7
B.4.8
B.4.9
B.4.10
B.4.11
B.4.12
B.4.13
B.4.14
B.4.15
B.5

B.6

Appendix C

B-28
B-28
B-29
B-30
B-30
B-31
B-32
B-32
B-34
B-34
B-36

End of Module ............................................. .

Executable File Structure

C.l

Label Block Group .......................................... .

C-2

C.2

Header
C.2.1

Low Core Context ................................... .

C-6
C-9

C.3

Overlay Data Structure ....................................... .
C.3.1
Autoload Vectors for Conventional Tasks .................... .
Segment Descriptor .................................. .
C.3.2
C.3.2.1
Autoload Vectors for 1- and D-Space Tasks .......... .
C.3.3
Window Descriptor ................................... .
C.3.4
Region Descriptor ................................... .

C-11
C-13
C-14
C-17
C-18
C-19

C.4

Root Segment ............................................. .

C-19

C.5

Overlay Segments .......................................... .

C-19

Appendix D

Reserved Symbols

Appendix E

Improving Task Builder Performance

E.1

Evaluating and Improving Task Builder Performance .................. .
E.1.1
The Task Builder Work File ............................. .
E.1.2
Input File Processing ................................. .

E-1
E-1

E-3

Index

Examples
3-1

Overlay Description of Memory Allocation Map . . . . . . . . . . . . . . . . . . . . . . . . .

3-7

4-1

First Page of Map File for Sample Program . . . . . . . . .................. .

4-10

4-2

Excerpts from Map File for Second Build of Sample Program .............. .

4-12

4-3

First Page of Map File for Third Build of Sample Program ................ .

4-16

7-1

VSECT2.CMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-20

7-2

Source Listing for VSECT2.FTN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-21

7-3

Task Builder Map (Edited) for VSECT2.TSK . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-23

7-4

VSECT.CMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-24

7-5

Source Listing for VSECT.FTN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-25

B-1

Code for SUPER.MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-9

B-2

Memory Allocation Map for Super . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-1 0

B-3

Completion Routine $CMPCS from SYSLlB.OLB ....................... .

B-11

9-4

Code for TSUP.MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-14

B-5

Memory Allocation Map for TSUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-16

11-1

Memory Allocation (Map) File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11-27

12-1

A Task Using a Virtual Array with the OVR Attribute .................... .

12-36

Figures

xii

1-1

Steps in Creating a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-1

1-2

The Task Builder Resolves Global References . . . . . . . . . . . . . . . . . . . . . . . . .

1-2

1-3

The Task Builder Constructs the Overlays You Specify. . . . . . . . . . . . . . . . . . . .

1-4

2-1

You Tell the Task Builder Which Libraries to Include .....................

2-1

2-2

Job Area: Two User Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-3

Disk and Resident Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2--6

2-4

Clustered Resident Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-13

3-1

The ODL File Is Your "Blueprint" for Overlays. . . . . . . . . . . . . . . . . . . . . . . . . .

3-1

3-2

Outlining the Call Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-2

3-3

A Simple Overlay in Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-3

3-4

Outline of First Call Structure for Example. . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-8

3-5

Outline of Second Call Structure for Example . . . . . . . . . . . . . . . . . . . . . . . . . .

3-9

3--6

Separate Paths in an Overlay Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-11

3-7

Resolving Global Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-13

3-8
4-1

Resolving Global Symbols from Disk Libraries .........................
Co-Trees Save More Space Than Simple Overlays. . . . . . . . . . . . . . . . . . . . . .

3-14
4-1

4-2

Putting A and B in the Root. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-2

4-3

A Co-Tree Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-2

4-4

How a Co-Tree Is Loaded During Program Execution ....................

4-4

4-5

Co-trees Save More Space When Pieces Are the Same Size . . . . . . . . . . . . . . .

4-5

4--6

Call Structure for Sample Program .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-7

First Build Structure for Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-8
4-9

4-8
4-9
4-10
5-1

Structure for Second Build of Sample Program. . . . . . . . . . . . . . . . . . . . . . . . .

4-10

Sketch of the Structure for Second Build of Sample Program ...............

4-14

Structure for Third Build of Sample Program

4-15

The Easiest Way to Use Autoload Indicators . . . . . . . . . . . . . . . . . . . . . . . . . .

5-1

5-2

The Four-Word Structure of a Vector Autoload ........................ .

5-2

5-3

An Overlay Structure Without Autoload Vectors ........................ .

5-3

6-1

The Task Builder Works with Program Sections ....................... .

6-1

6-2

Allocating Space for Global Program Sections ........................ .

6-3

Allocation of Program Sections for IN1, IN2, and IN3 .................... .

6-4

7-1

Memory-Resident Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-5

7-2

Using a Null Memory-Resident Overlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-9

7-3

Overview of How Inter-Cluster-Library Calls Work ...................... .

7-11

7-4

VSECT Option Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-16

8-1

Conventional Task Linked to a Region in 1- and D-Space System ........... .

8-2

1- and D-space Task Mapping in an 1- and D-space System ............... .

8-3
8-4

9-1

Mapping of a 24K Word Conventional User Task Linking to a 16K Word
Supervisor-Mode Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9-3

9-2

Mapping of a 40K Word 1- and D-Space Task Linking to an 8K Word
Supervisor-Mode Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9-4

9-3
8-1

Overlay Configuration Allowed for Supervisor-Mode Libraries .............. .

9-20

General Object Module Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-2

GSD Record and Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-4

8-3

Module Name Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-5

B-4

Control Section Name Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-6

8-5

Internal Symbol Name Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-6

Transfer Address Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-7

Global Symbol Name Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-7

B-8

PSECT Name Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-8

8-9

Program Version Identification Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-10

Mapped Array Declaration Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-11

Completion Routine Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-11

8-12

End-of-GSD Record Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-12

8-13

Text Information Record Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-13

8-14

Relocation Directory Record Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-15

Internal Relocation Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-16

Global Relocation Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-16

8-17

Internal Displaced Relocation Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-17

8-18

Global Displaced Relocation Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-17

8-19

Global Additive Relocation Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-18

8-20

Global Additive Displaced Relocation Entry Format ..................... .

8-19

8-21

Location Counter Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-19

8-22

Location Counter Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-20

8-23

Program Limits Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-20

8-24

PSECT Relocation Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-21

8-25

PSECT Displaced Relocation Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-22

8-26

PSECT Additive Relocation Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-23

8-27

PSECT Additive Displaced Relocation Entry Format .................... .

8-24

8-28

Complex Relocation Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-25

8-29

Additive Relocation Entry Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-26

8-30

General Format of All ISD Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-27

8-31

General Format of a TKB-Generated Record ......................... .

8-28

8-32

Format of TKB-Generated Start-of-Segment Item (1) .................... .

8-28

8-33

Format of TKB-Generated Task Identification Item (2) ................... .

8-29

xiii

8-34

Format of an Autoloadable Library Entry Point Item (3) .................. .

8-30

8-35

Format of a Module Name Item (Type 1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-31

8-36

Format of a Global Symbol Item (Type 2) ........................... .

8-32

8-37

Format of a PSECT Item (Type 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-33

8-38

Format of a Line-Number or PC Correlation Item (Type 4) ................ .

8-34

8-39

Format of an Internal Symbol Name Item (Type 5) ..................... .

8-35

B-40
B-41

Format of a Literal Record Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-36

End-of-Module Record Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-36

C-1

Task Image on Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-1

C-2

Label Block Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-3

Task Header Fixed Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-7

C-4

Task Header Variable Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-8

C-5

Vector Extension Area Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-10

C-6

Task-Resident Overlay Data Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-11

C-7

Task-Resident Overlay Database for and 1- and D-Space Overlaid Task ....... .

C-12

C-8

Autoload Vector Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-13

C-9

Segment Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-14

C-10

Sample Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-16

C-11

Segment Linkage Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-16

C-12

Autoload Vector Entry for 1- and D-Space Tasks ....................... .

C-17

C-13
C-14

Window Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-18

Region Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-19

2-1

Disk Libraries Used with RSTSIE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-4

2-2

Applicable Libraries for the CLSTR Option . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-12

6-1

Program Sections for IN1, IN2, AND IN3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6-4

Tables

Format of Region Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-18

7-2

Bit Meanings in the Mask Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-26

7-3

Values for the First Fast-Mapping Call Parameter ...................... .

7-29

8-1

Mapping Comparison Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-2

11-1

Task Builder Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11-1

11-2

Input Files for ISS Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11-34

12-1

Task Builder Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

12-1

7-1

xiv

8-1

GSD Entry Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-3

8-2

Types of Entries for Relocation Directory Records ...................... .

8-14

8-3

Defined Operation Codes for the RLD Command Word .................. .

8-24

C-1

Task and Resident Library Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-4

C-2

Contents of SRTSICommon Name Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

C-6

0-1

Task Builder Reserved Global Symbols ............................. .

0-1

0-2

PSECT Names Reserved by the Task Builder ......................... .

D-3

Preface

Objectives
This manual describes how to use the RSTSIE Task Builder to link your compiled
or assembled programs and subprograms into an executable program file to run
on RSTSIE.
On RSTSIE systems, your programs must be linked by the Task Builder if they
were written in languages for the compilers listed below. Note that this manual
is current for the versions shown in parentheses. Information about using the
Task Builder may change for subsequent versions.
Compiler (Version)
BASIC-PLUS-2 (V2.6)
FORTRAN-77 (V5.3)
PDP-ll C (V1.0)
COBOL-81 (V3.0)
DIBOL (V6.1)
This manual also applies to the MAC assembler (V5.5) for MACRO programs.

Audience
Although you do not need to be a computer expert to use this manual, you should
have a general understanding of computer languages and be familiar with using
programs and subprograms.

Document Structure
This manual contains four parts, as indicated by the divider sheets preceding
each section, and five appendixes:
Part I

Tells all you need to know to get a program built with the right libraries to run on a RSTSIE system. The two types of libraries (disk
libraries and memory-resident libraries) are explained, along with
details on how to link them with your program.

Part II

Part III

Discusses overlays. Chapter 3 describes how to specify an overlay
structure for programs that are too large to fit in the available space.
The key statements of the Overlay Description Language (ODL) are
described and examples are given. Chapter 4 extends the discussion
of overlays by describing a special overlay structure, called co-trees.
Chapter 5 explains the autoload indicator, an ODL symbol, and tells
how you can use this symbol to save some space in your program.
Chapter 6 describes overlays from another point of view: working with
units called "program sections." Special ODL commands are available
to deal with these units; they are described in this section, and more
examples are given.
Describes system aspects of Task Building. Chapter 7 describes how

to build your own memory-resident library, and how to build your own
cluster library. Chapter 8 describes techniques for revectoring cluster
libraries, and Chapter 9 describes the use of instruction and data (1- &
D-) space.

Part IV

Is a reference source. Chapters 10, 11, and 12 describe the full
Task Builder command format, switches, and options, respectively.
Chapter 13 describes the Overlay Description Language in detail.
Appendix A describes error messages provided by the Task Builder.
Appendixes Band C describe internal data formats used by the Task
Builder and the format of the executable file produced by the Task
Builder. Appendix D lists and describes global symbols and program
section names reserved for use by the Task Builder. Appendix E
describes how to improve Task Builder performance.

MK-{)0565-00

xvi

Conventions
UPPERCASE COMMANDS

In general command format descriptions, UPPERCASE
indicates commands that you must type as shown.

lowercase commands

Indicate variables that you supply. For example:

Red Print

In the Task Builder command examples, user input is
shown in red. The Task Builder's responses and prompts
are printed in black. For example:

.ROOT structure

ENTER OPTIONS:
TKB> UNITS=8

The dollar sign is the default DCL prompt.

Summary of Technical Changes
RSTSIE VIO.O is a major release of the RSTSIE PDP-ll operating system. This
manual describes the following technical changes to the Task Builder function:
•

There are two new switches: the /FM and /FO switches.

•

Four new options are available: RESSUP, SUPLIB, VARRAY AND VSECT.

•

Prior to RSTSIE V9.7, when a library was included in a task build, whichever
APRs were assigned to the RESLIB or LIBR libraries included both 1- and
D-spaces. Beginning with V9.7, both the 1- and D-spaces are initially assigned
to the libraries; however, the COMMON and RESCOM options can be used
to reallocate the D-space APRs to data-only regions. This feature, called
"concurrent libraries", allows for more efficient use of memory when I-only
code libraries (such as RMS) are used. Note that this feature is available only
on CPUs that support separate 1- and D- spaces .

xvii

Chapter 1

Introduction

You need to use the Task Builder (TKB) if you write programs on RSTSIE systems
in BASIC-PLUS-2, FORTRAN-77, PDP-ll C, COBOL-81, DIBOL, or the MACRO
assembly language using the MAC assembler.
The compilers and assemblers associated with these languages translate your
programs and subprograms (called source code) into machine instructions
(object code). The Task Builder applies the final touches, converting the object
code produced by the compilers to code that can be executed by the computer.
Figure 1-1 shows the steps involved in creating a program.
Figure 1-1: Steps in Creating a Program

MAIN.SRC
PROGRAM

MAIN.OBJ
0

A = S*C

011
101

PROGRAM.TSK
0
1000

(RSTS/E INFORMATION)
(STACK)

2000

END
(MAIN CODE)
SUS.SRC

1567

SUB-END

0CREATING
THE
SOURCE
(EDT OR OTHER
EDITOR)

25:1

SUB.OBJ

2263

1110

2375

101

0COMPILING
OR
ASSEMBLING

(LIBRARY ROUTINES)
(SUB CODE)
(LIBRARY ROUTINES)

(TKB)
(MAC, FORTRAN
BP2, DIBOL,
COBOL)

Introduction

1-1

1.1

What the Task Builder Does
The Task Builder handles two basic functions: linking and producing overlays.

1.1.1

Linking
Linking is necessary because you seldom write programs as one unit. It is
easier to work with programs that are written as modules - programs and
subprograms-that you can separately design, code, debug, and maintain.
Even if you code your program as one main program, with no separately assembled or compiled subprograms, every compiler translates some source statements
into calls to subroutines kept in libraries. For example, all the compilers generate calls to library subroutines to perform I/O or do mathematical calculations.
Libraries are provided with the system and with the compilers available with
RSTSIE systems.
The Task Builder links these separate modules-your main program, subprograms, and library routines-together in the order you specify, resolving any
references that cross module boundaries. For example, Figure 1-2 shows a call to
SUB1 from the program MAIN.
Figure 1-2:

The Task Builder Resolves Global References

OCTAL
ADDRESS

SUB SUB1

11216

SUBEND
RUN $TKB
TKB>MAIN = MAIN, SUB1, LB:F4POTS /LB
TKB>!/

1-2

Introduction

MK-{)0567-{)O

The command to the Task Builder (the line after RUN $TKB) says that these
two modules are to be linked together. In addition, any routines necessary from
the FORTRAN library are to be linked with these two modules. To simplify, the
figure shows only the linking of MAIN and SUBl. Part of the linking process
involves generating the proper succession of addresses. As Figure 1-1 showed,
the compilers and assemblers generate what are caned "relative addresses"; the
first address of each module (MAIN and SUBl) is numbered 0 at the compilation
stage. When the Task Builder links modules, it changes the addresses of the
second and following modules to begin where the addresses of the previous
module left off. So, the final addresses for the linked program, as assigned by the
Task Builder, range upward from 0 in succession.
The second aspect of linking is resolving references to what are called "global
symbols." At compile time, for example, MAIN's reference to SUBI cannot be
resolved. SUBl is flagged as a global reference (somewhere in the "world outside
of MAIN") when MAIN is compiled. Likewise, when SUBI is compiled, it is
again flagged as a global symbol; it win serve as an entry point from the "outside
world."
The Task Builder, as shown in Figure 1-2, keeps track of the addresses assigned
to global symbols and substitutes the address for the entry point of SUB 1 into the
call in MAIN. Then, when the program is run, and the call is executed, control
transfers to address 11216, the entry point for SUBl.

1.1.2

Overlays
The second necessary service that the Task Builder provides is a means to
construct overlays. The amount of memory from which programs can be executed
is limited on PDP-11 computers to 32,000 words. On RSTSIE systems, for reasons
described in Chapter 2, there are further limitations. If your program is too large
to fit in the space available, you must specify how you want it overlaid-such that
sections of code and data can be called into memory at different times (the new
sections "overlaying" the old).
Figure 1-3 shows the concept behind overlays. The Task Builder links both the
modules SUB1 and SUB2 to start at address 15,726. The Task Builder then
inserts code into MAIN such that, when MAIN's call to SUB2 is executed, SUB2
will replace SUB1, called and executed previously. SUBl does not have to be the
same length as SUB2, but both will be linked to start at the same address.
Figure 1-3 also shows something called the "high segment" in high address space.
This code is the main reason your program does not have the full 32,000 words
available on PDP-ll systems. For further information, see Chapter 2.

Introduction

1-3

Figure 1-3: The Task Builder Constructs the Overlays You Specify

RUN $TKB
TKB> PROG=OVR/MP
TKB>II

(THE 'MAP FILE'
OVRODL CONTAINS
AN OVERLAY
DESCRIPTION)

o
MAIN

I------i

15,726

1--_---1 21 ,322

(HIGH
SEGMENT)
MK-00568-00

1.2 Relationship to the DCl LINK Command
You can use the DeL LINK command to link your programs, as described in the
RSTS / E DeL User's Guide. Like all DeL commands, the LINK command is
somewhat simpler to use, compared to typing a RUN command to execute TKB.

However, the LINK command does not offer all the features and flexibility of the
Task Builder. Note that the DeL LINK command does not work any faster than
running TKB; LINK also runs the Task Builder to perform the requested action.

1-4 Introduction

Part I
Getting Started

Chapter 2

Building Programs
This chapter tells how to build nonoverlaid programs. How large can a program
be before it must be overlaid? The answer depends on the language you used to
write your program; Section 2.1 discusses some specifics. The library routines
built into your executable program also affect its size (Figure 2-1). Section 2.2
names and describes the disk libraries currently provided by Digital for the
various languages. Section 2.3 discusses the Task Builder command line in
general, and Section 2.4 gives specific examples for building programs written in
each of the various languages.
Figure 2-1:

You Tell the Task Builder Which Libraries to Include

MAIN

OJ
-U

(J)
(J)

r-v

RUN $TKB
TKB>MAIN, SUB1, LB: F4POTS/LB
TKB> I I
MK-0056!HlO

Building Programs

2-1

2.1

Job Area
As Chapter 1 mentions, the hardware imposes a limit on your program's size.
The PDP-11 computer handles instruction and data in terms of a "16-bit word."
A 16-bit word can reference 2 16 (65,536 10) bytes, or 32,768 words. Thus, unless
your program uses user-mode 1- and D-space, 32K words is the maximum area of
computer memory you can work with at one time.
If you have a PDP-11/44, 11/45, 11/50, 11/53, 11/55, 11/70, 11/73, 11/83, 11/84,

11/93 or 11/94 system, you can use user-mode 1- and D-space. This feature lets
you extend your task to 64K words of virtual address space (32K-word maximum
of instruction space, and 32K-word maximum of data space). See Chapter 7 for
more information on user-mode 1- and D-space.

2.1.1

Your Program Within the Job Area
Except in special applications such as BASIC-PLUS and RT-11, the monitor loads
programs. Monitor-loaded programs include BASIC-PLUS-2, PDP-ll C, PDP-11
COBOL, COBOL-81, DIBOL, FORTRAN-77, and MACRO programs assembled
with the MAC assembler.
This section describes how your program fits within the job area if your program
uses a run-time system.
The Task Builder constructs your executable program so that it fits within the
job area in the low address space, beneath the run-time system (see Figure 2-2).
Note the way your job area is constructed of various regions in physical memory.
For example, Figure 2-2 shows physical memory addresses for user program 2
that are actually higher than the so-called "hiseg" or run-time system. Yet the
Task Builder, when it builds a program, constructs addresses for the program
as though it operated within one 32K-word job area in memory. The RSTSIE
monitor resolves this difference by using active page registers (APRs).
The job area is sometimes called "virtual address space," because it appears to
you that your program and its associated run-time system reside in a contiguous
32K-word area. As Figure 2-2 shows, this is not actually the case in physical
memory.

2-2

Building Programs

Figure 2-2: Job Area: Two User Programs

PHYSICAL MEMORY

VIRTUAL ADDRESS
SPACE
o~~~~~~~~

JOB1

4K
8K
12K~~~~~~~~~k

16K
20K
24K
28K
32K

JOB2

0
4K
8K
12K
16K
20K
24K
28K
32K

MK-0057Q-OO

2.2 Libraries
As mentioned in Chapter 1, every compiler translates some source statements
into calls to subroutines. These subroutines are kept in what are called
"libraries." Digital supplies libraries of subroutines used with each language.
Because the Task Builder has no way of knowing the source language you used,
you must tell it what libraries contain routines that are referenced by your
program. Two general types of libraries may be available on your system: disk
libraries and resident libraries.

Building Programs 2-3

2.2.1

Disk Libraries
The libraries listed in Table 2-1 are currently shipped with RSTS/E and its
associated languages. Note that the table is current for the versions of the
software mentioned in the Preface. As new versions of languages are released,
library names and contents may change. In addition, other products available
with RSTS/E can have associated libraries, and your own installation may have
generated its own libraries.
One way to find out what libraries are available is to get a directory of the system
library device (LB:) with a wildcard file name and a file type of .OLB . (OLB
stands for object library.) For example:
DIR LB:* . OLB
Name

Size
220
300
225
178

. Typ

SYSLIB.OLB
RMSLIB.OLB
BP20TS . OLB
COBLIB.OLB

Prot

DR3: [1,1]

< 40>

< 40>
< 40>

< 40 >

Table 2-1 describes some of the libraries in this account that your program may
use.
Table 2-1:

Disk Libraries Used with RSTS/E

Disk L ib rary
Name

Description

SYSLIB.OLB

The system library. Contains many routines used by programs
written in MACRO (for the MAC assembler) and the higher-level
languages. The Task Builder always searches this library to resolve
undefined symbols. You do not need to specify it in a Task Builder
command line.

RMSLIB.OLB

Contains routines needed if you use RMS (Record Management
Services) on RSTSIE systems.

RMSDAP.OLB

Contains routines needed for network record access through RMS
on RSTSIE systems.

BP20TS.OLB

Contains routines needed to run your BASIC-PLUS-2 program
under the RSX run-time system.

DBLLIB.OLB

Contains routines needed to run your DIBOL program if it uses the
DIBOL Management System (DMS) for I/O. Note that you must also
declare a resident library (DBLRES) if you use this disk library. See
Section 2.3.4 for information on how to specify resident libraries.

DBRLIB.OLB

Contains routines needed to run your DIBOL program if you use the
Record Management System (RMS) for 110. Note that you must also
declare a resident library (DBRRES) if you use this disk library. See
Section 2.3.4 for information on how to specify resident libraries.

COBLIB.OLB

Contains routines needed to run your PDP-ll COBOL program. If
you use this library rather than COBOVR.OLB, your program will
take more memory but will run faster.

(continued on next page)

2-4

Building Programs

2.2.2

Table 2-1 (Cont.):

Disk Libraries Used with RSTS/E

Disk Library
Name

Description

COBOVR.OLB

Contains routines needed to run your PDP-ll COBOL program if
it is overlaid. You use this library if you use the PDP-ll COBOL
segmentation facility. However, if you use this library rather than
COBLIB.OLB, your program will run slower, as the routines are
called in as needed and overlay each other.

C8lCI8.0LB

Contains routines needed to run your COBOL-8l program if the
program was compiled with the ICIS switch. This is the normal
default if your computer has the Commercial Instruction Set (CIS)
option.

C8lLIB.OLB

Contains routines needed to run your COBOL-8l program if the
program was compiled with the I-CIS switch. This is the normal
default if your computer does not have the Commercial Instruction
Set (CIS) option.

FDVDBG.OLB

Contains routines needed if you use the FMS form driver with
debug mode support.

FDVLIB.OLB

Contains routines needed if you use the FMS form driver without
debug mode support.

F4POTS.OLB

Contains routines needed to run your FORTRAN-77 program.

F4PRMS.OLB

Contains routines for FORTRAN-77 programs using RMS (Record
Management Services) for 110.

Resident Libraries
In addition to disk libraries, you may also have to work with resident libraries
on RSTSIE systems. "Resident" means residing in computer memory. The system
manager defines libraries as resident so that they can be shared by more than
one user. Instead of building routines into your program (as is done with disk
libraries), you use a copy of the library. The copy is resident in memory as long
as you or someone else is using it.
The Task Builder links your program to appropriate routines in the resident
library by a technique called "mapping." Mapping is the process of accessing
different logical areas of memory. With the mapping technique, many programs
can use routines from the same space in computer memory. The system manager
usually defines a library to be resident when it is heavily used. In such cases,
less overall computer memory is taken by a resident library than by having each
program include its own copy of routines from the library.
Figure 2-3 shows the difference between disk and resident libraries. For disk
libraries, the Task Builder takes a copy of each routine that you reference in your
program and builds it into your program. Note that a copy of RTNA has been
built into both PROG 1 and PROG2 in this figure. However, both programs can
reference a resident library from the same area of physical memory.

Building Programs

2-5

Figure 2-3:

Disk and Resident Libraries

PROG2

PROG1

RTN E
RTN F

RTN E

RTNA

RTN C
RTN B
DISK LIBRARY: COPIES OF ROUTINES ARE BUILT INTO EACH PROGRAM.

PROG2

PROG1
PHYSICAL
MEMORY

/
RESIDENT
LIBRARY

RESIDENT LIBRARY: MANY PROGRAMS CAN USE ONE COpy OF THE LIBRARY IN MEMORY.

MK~057H)O

You need to be aware of the distinction between disk and resident libraries
because the Task Builder commands that cause a link to resident libraries differ
from those for disk libraries. You can tell what resident libraries are on your
system by running the SYSTAT program. One section of the system status report
is headed "Resident Libraries:". You can request just this section of the report by
using the SHOW LIBRARIES DCL command.
The following example shows resident libraries. The RMS libraries are supplied with all RSTS/E systems. They contain routines providing RMS (Record
Management Services) for input/output. The two BASIC resident libraries,
BP2RES and BP2SML are components of the layered product BASIC-PLUS-2 and
are discussed further in Section 2.2.3.
2-6 Building Programs

$ SHOW LIBRARY
Resident Libraries:
Acct
Name Prot
RMSRES < 42> DR1: [ 0,1
RMSLBB < 42> DR1: [ 0,1
RMSLBA < 42> DR1: [ 0,1
RMSLBC < 42> DR1: [ 0,1
RMSLBD < 42> DR1: [ 0,1
RMSLBE < 42> DR1: [ 0,1
RMSLBF < 42> DR1: [ 0,1
BP2RES < 42> DR1: [ 0,1
BP2SML < 42> DR1: [ 0,1

Size Users
4K
1
4K
1
4K
3K
2K
4K
4K
19K
8K

Comments
Temp, Addr:733
Temp, Addr:737
Temp, Addr:741
Non-Res, Addr:745
Temp, Addr:748
Temp, Addr:750
Temp, Addr:754
Non-Res, Addr:760
Temp, Addr:779

°
°
°
°
°
°
°
The Task Builder allows your program to access up to seven resident libraries on
RSTSIE systems.

2.2.3

Comparison of Disk and Resident Libraries
Resident libraries require a large amount of physical memory. However, if many
tasks run at the same time, resident libraries reduce the total amount of physical
memory required by these tasks .
For example, BP2RES contains most of the BASIC Object Time System (OTS),
that is, most of the library routines supplied with BASIC-PLUS-2. It occupies
19K words of physical memory and takes 8K words of virtual address space in
your program. BP2SML contains a subset of the most commonly used BASIC
routines. It uses 8K words of physical memory and 8K words of virtual address
space. Even though BP2RES takes up 19K words of physical memory, that would
be less than, say five running copies of a program each using 4K words of BP2
routines built into each copy from a disk library (20K words total).
Therefore, the main advantage of using resident libraries is that their code can
be shared by many programs. In addition, task building is much faster when
using resident libraries because the Task Builder does not have to access the
library on disk as often. If you prpgram in BASIC-PLUS-2, note that the resident
libraries (BP2SML and BP2RES) do not contain the entire OTS, therefore, most
BASIC-PLUS-2 programs will reference some entry points within the disk library
BP20TS.OLB.

2.3 How to Run the Task Builder
To run the Task Builder, type:

RUN $TKB
Or, if the system manager has installed TKB as a concise command language
(CCL) command, you can simply type:
TKB
The Task Builder responds with the prompt TKB> and you type a command. If
TKB has been installed as a CCL command, you can type TKB and the command
on the same line:
TKB command
We describe the format of Task Builder commands below. Note that the Task
Builder allows much flexibility in the way you can specify commands. The
following sections show only the simplest and most direct way. For a detailed
description of all the features available, including command file input to the Task
Builder, see Chapter 10.
Building Programs

2-7

2.3.1

Command Line
The Task Builder produces up to three files as output from its analysis of the
object files you specify as input. The general form of the command is shown
below in lowercase letters:
RUN $TKB
TKB>task-file,map-file,symbol-file=object, .... ,object
TKB>II
where:
task-file

is the file specification you give to name the executable program file
produced by the Task Builder. If you do not want this file produced,
simply type the comma. If you leave off the file type from the file
specification, the Task Builder supplies a default type of .TSK.

map-file

is the file specification you give to name the memory map file
produced by the Task Builder. This map can be very useful if you
are doing overlays; it is not particularly helpful otherwise. See
Chapters 3, 4, and 6, where overlays are discussed, for a description
of the map file.

If you do not want this file, simply type the comma delimiter. If you
leave off the file type from the file specification, the Task Builder
supplies a default type of .MAP.
symbol-file

is the file specification you give to name the symbol-table file
produced by the Task Builder. This file is necessary if you want to
build your own resident library. It is also used by the COBOL-81
symbolic debugger. It is not useful otherwise. See Chapter 7 for a
description of the symbol file.
If you do not want this file, simply leave out the file specification.
If you leave off the file type from the file specification, the Task
Builder supplies a default type of .STB.

object, ...

are the object files produced from the assembly or compilation of
your program and subroutines, plus disk library files containing
subroutines needed to complete the program. These files are input
to the Task Builder. The Task Builder combines these object files in
the order you specify, and resolves cross-references to produce the
task file.
You signify disk library files by appending the switch ILB to the file
specification. This notifies the Task Builder that the file named is
a library to be searched. The library is searched for routines that
resolve references to undefined global symbols in all files to the left
of the library file in the input list. So, be sure to put the library to
the right of all object files that may contain references to routines
in the library. (Usually, you put the library or libraries at the end of
the input list.)
If you do not specify file types, the Task Builder assumes a default
type of .OBJ for object files and a default type of .OLB for object
libraries.

If you give a device or project-programmer number in a file specification in the input list (to the right of the equal sign), it applies to
all file specifications to the right in the list.

Consider a build using MACRO object programs, for example. Assuming that
TKB has been installed as a concise command language (CCL) command, a
suitable command line is:
TKB EXE1,EXE1,EXE1=OBJ1,OBJ2,LB:RMSLIB/LB

2-8

Building Programs

The Task Builder constructs the executable file EXE1.TSK, the map file
EXE1.MAP, and the symbol table file EXE1.STB from the files OBJ1.0BJ,
OBJ2.0BJ, and relevant modules from the library LB:RMSLIB.OLB. (The relevant modules are those referenced in your program. You may have referred to
them in source statements, or the MAC assembler may have translated source
statements into calls referring to this library.)
To omit the map file, type:
TKB EXE1"EXE1=OBJ1,OBJ2,LB:RMSLIB/LB

To produce only the executable file, type:
TKB EXE1=OBJ1,OBJ2,LB:RMSLIB/LB

To produce no output files, type:
TKB=OBJ1,OBJ2,LB:RMSLIB/LB

The example above is useful if you are running the Task Builder only to see error
messages; that is, a diagnostic run.
Note how project-programmer numbers and device designators work when they
are given for a file specification in the input list:
TKB=OBJ1, [2,243)OBJ2 , OBJ3,LB:RMSLIB/LB,MYLIB/LB

For this command, the Task Builder would search for the file OBJ1.0BJ in the
user's account and for the files OBJ2.0BJ and OBJ3.0BJ in the account [2,243].
The project-programmer number also applies to the library; that is, the Task
Builder would look on the system library disk for a file RMSLIB.OLB under the
account [2,243]. Likewise, since the device name LB: also applies to MYLIB,
the Task Builder looks on the system library disk under account [2,243] for the
library file MYLIB.OLB.
If you do not want this to happen, respecify the project-programmer number
and device that you want to apply to remaining files. The simplest way to
accomplish this is to assign a logical name to the account [2,243] and use the
system-wide logical SY: to "get back to" your account on the public disk structure.
For example:
ASSIGN SY: [2,243) JOHN
Ready
TKB=OBJ1,JOHN:OBJ2,SY:OBJ3,LB:RMSLIB/LB,SY:MYLIB/LB

This can also be accomplished using multiline commands, as shown in the
following section.

2.3.2

Multiline Command
Because you can specify any number of input files to the Task Builder, you
sometimes need to use more than one line to enter a command.
If you type RUN $TKB or just TKB, so that the Task Builder prompts with
TKB>, it continues prompting for input until it teceives a line consisting only of
two slash characters (II). For example:
RUN $TKB
TKB> IMG1,IMG1,IMG1=SY: [2,243)FILEl
TKB> FILE2,FILE3,LB:RMSLIB/LB
TKB> MYLIB/LB
TKB> II

Building Programs

2-9

The above sequence produces the same result as the single-line command:
TKB IMG1,IMG1,IMG1=JOHN:FILE1,SY:FILE2,FILE3,LB:RMSLIB/LB,SY:MYLIB/LB

You must specify the output file specifications and the equal sign on the first line.
You can begin or continue input file specifications on subsequent lines.

2.3.3

Options
You may need to specify options to build a particular program. An option modifies
the action taking place during the build. To include options, you must use the
multiline format as shown below. When you type a line consisting of a single
slash (f), the Task Builder assumes that the last input file has been entered and
prompts for options by displaying "ENTER OPTIONS:" and another "TKB>"
prompt.
RUN $TKB
TKB>command
TKB>continued-command
TKB>I
ENTER OPTIONS:
TKB>option=value:value
TKB>II
The format for options is shown here because some languages require certain
options for a Task Build. If your language manual set includes a user's guide, you
will probably find helpful pointers about necessary or particularly useful options
for your language. Table 12-1 in the Reference Section of this manual (Part IV)
gives an overview of all the options available for the Task Builder. The options
are then described in detail in the remainder of Chapter 12.
The options you will probably find most useful regardless of source language are
RESLIB and LIBR. You need to use these options if you need to link to one or
more resident libraries. Since resident libraries are commonly used, these options
are discussed in the following section. Some examples of these and other options
are shown in Section 2.4.

2.3.4

The L1BR and RESLIB Options
You can link to a maximum of seven user mode resident libraries using the Task
Builder on RSTSIE systems. Supervisor mode resident libraries are explained in
Chapter 9. With either the LIBR or RESLIB option, you specify that you want to
link your program to one resident library. The choice between LIBR or RESLIB
depends on whether the library is "system-owned" or "user-owned."
The LIBR option declares that your program intends to access a "system-owned"
resident library. "System-owned" simply means that the file containing the
library is located in the library account (LB:). This can be any account on any
disk, as assigned by the system manager.

2-10

Building Programs

"User-owned" means that the library can be on some disk or account other than
LB:. With the RESLIB option, you specify the disk containing the resident library
files.
The formats for the options are:
LIBR=name:access-code[:apr]
RESLIB =file-specification/access-code[:a pr]
Note that with the LIBR option, you name only the resident library. The Task
Builder looks for the appropriate files (name.STB and name.TSK) on the system
library disk (LB:) when it is building the code necessary to load the resident
library. With the RESLIB option, you specify a complete file specification. This
names the device, account, and file name of the executable file to be loaded. You
do not specify the file type. The Task Builder uses the executable file and the
symbol table file for the library, and requires that they have file types of .TSK
and .STB.
The access-code is either RW (read/write) or RO (read-only), indicating how your
program intends to access the library. (It will be RO for Digital-provided resident
libraries such as RMSRES.)
The Active Page Register (APR) parameter is an integer in the range of 1 to 7
that specifies the first APR reserved for the library. If you leave this parameter
off, the Task Builder assigns the highest APR it can to the resident library.
It is not really necessary to understand Active Page Registers to understand or
use the APR modifier. Think of your 32K word user job area as divided into eight
parts of 4K words each, numbered from 0 through 7. Your program occupies one
or more of the lowest-numbered segments.

You can "map" resident libraries into the area between the top of the program
and the highest address of virtual memory. The map must begin on a 4K-word
boundary. For example, suppose your program takes 6K words and the run-time
system takes 4K words of memory. You can map up to 20K words of resident
library into your job, beginning with APR 2.
NOTE

With the use of advanced programming techniques, it is possible to
use resident libraries with certain run-time systems other than RSX.
However, Digital supports the use of resident libraries only under the
RSX run-time system.

2.3.5

The CLSTR Option
You can use the CLSTR option if you need to use more than one resident library.
CLSTR lets multiple resident libraries share the same virtual address space in
your program. However, not all resident libraries available with RSTSIE can take
advantage of this feature. Table 2-2 lists those libraries to which CLSTR can
apply.

Building Programs

2-11

Table 2-2:

Applicable Libraries for the CLSTR Option

Disk Library
Name

Description

BP2RES

Clusterable resident library for BASIC-PLUS-2 programs.

BP2SML

Clusterable resident library (a subset of BP2RES) for BASIC-PLUS-2
programs.

C81CIS

Clusterable resident library for COBOL-81 programs compiled with
the ICIS switch (normal default if your computer has the Commercial
Instruction Set [CIS] option).

C81LIB

Clusterable resident library for COBOL-81 programs compiled with
I-CIS switch (normal default if your computer does not have the CIS
option).

DIBOLR

Clusterable resident library for RMS DIBOL programs.

F4PCLS

Clusterable resident library for RMS FORTRAN-77 programs.

FDVRDB

Clusterable resident library for the FMS form driver with debug
mode support.

FDVRES

Clusterable resident library for the FMS form driver without debug
mode support.

RMSRES

Clusterable resident library for RMS-ll that supports sequential,
relative, and indexed file operations.

DAPRES

Clusterable resident library for network record access through RMS.

SMRES

Clusterable resident library for SORTIMERGE.

Refer to the documentation for your specific languages to see whether their
libraries can cluster.
Figure 2-4 illustrates the concept of cluster libraries. In the figure, three libraries
form a cluster for the user program: LIBl, LIB2, and LIB3. LIBl is the "default
library"; that is, it is mapped into the high end of the user program's address
space before any calls have been made to any library at execution time.
Figure 2-4 also illustrates that at "time 2" a call is executed to a routine in LIB3.
LIBl is unmapped from the high-address space, and LIB3 is mapped, so the
routine can be executed. When control passes from the library routine back to
the user program (time 3), LIB3 is unmapped, and LIBl (the default library) is
mapped again. At time 4, a call is executed to a routine in LIB2; again, LIBI is
unmapped and LIB2 is mapped to the high-address space.
This process of mapping and unmapping proceeds throughout execution of the
user program. The resident libraries forming a cluster share the same highaddress space in the job area (virtual address space). They take much less space
from the user program than they would if all three libraries were mapped to the
virtual address space at the same time.

2-12

Building Programs

Figure 2-4: Clustered Resident Libraries

USER
VIRTUAL
ADDRESS SPACE

PHYSICAL
MEMORY

USER
VIRTUAL
ADDRESS SPACE

PHYSICAL
MEMORY

USER
PROGRAM

LlB1
(default
library)

USER
PROGRAM

LlB1
(default
library)

LlB1

LlB3

LlB2

LlB2
Time 2

USER
VIRTUAL
ADDRESS SPACE

PHYSICAL
MEMORY

USER
VIRTUAL
ADDRESS SPACE

PHYSICAL
MEMORY

USER
PROGRAM

tlB1
(default
library)

USER
PROGRAM

LlBl
(default
library)

LlB3

LlB2

LlB2
Time 3

Time 4
MK--1l1048-00

'lb use cluster libraries, use the CLSTR option. The format is:
CLSTR=default-library,library-2, ... ,library-5:access-code[:apr]
The first library listed in the CLSTR option is the default library. Because of the
way clustering works, only certain libraries can be default libraries. If you want
to build libraries to be clusterable, the techniques are described in Chapter 7. If
you simply want to use libraries in a resident library cluster, the Digital-supplied
libraries are designed so the language library can always serve as the default
library.
Thus, for the resident libraries listed previously, you can use either BP2SML
or BP2RES for BASIC-PLUS-2 programs, or C8lCIS or C8lLIB for COBOL-8l
programs. As a secondary library in the cluster, you can use either FDVRES or
RMSRES or both.

Building Programs

2-13

Up to five resident libraries can fonn a cluster. A cluster for Digital-supplied
libraries must occupy the upper SK words of your address space. If your site
builds its own clusterable libraries, however, these libraries can occupy their own
separate cluster, as long as the limit of five resident libraries for each task build
is not exceeded. (You can have no more than five libraries involved in clusters.)
Thus, you can cluster either of two variations of the COBOL-Sllibrary (CSICIS
or CSILIB) with the FMS library (FDVRES) and/or the RMS library (RMSRES),
and any two of your own clusterable libraries either in the same cluster or in a
separate cluster in lower virtual address space.
Likewise, you can cluster BP2RES or BP2SML with the RMS (RMSRES) or
FMS (FDVRES) libraries or both, together with any two of your own clusterable
libraries.
The access-code is either RW (read/write) or RO (read-only). This code is an
attribute of the library itself. That is, you could not select RW (indicating your
program can read from or write to the library) if the library has been built RO.
The access-code is RO for Digital-provided resident libraries such as BP2RES,
FDVRES, CSICIS, and CSILIB. For example:
TKB> CLSTR=C81CIS,FDVRES,RMSRES:RO

The Active Page Register (APR) parameter is an integer in the range of 1 to 7
that specifies the first APR reserved for the clustered libraries. If you omit this
parameter, the Task Builder assigns the highest APR it can to the cluster (APRs
6 and 7 for the command line above).
Currently, Digital-supplied libraries are built to use the top two APRs available
to the cluster. APRs are assigned according to the following guidelines:
1. If the language library is part of a cluster, the cluster will occupy APRs 6 and

7. (You need not specify an APR parameter.)
2. If the language library is not part of a cluster and occupies the top two APRs,
such as the BP2SML resident library, the cluster will occupy APRs 4 and 5.
(You specify an APR parameter of 4.) This description applies mainly to users
who are building their own cluster libraries.
3. If a run-time system occupies the top APR (7), the cluster will occupy APRs 5
and 6. (You specify an APR parameter of 5.)

2.4 Examples of Simple Builds
The examples in this section illustrate building programs in various languages
and with various kinds of libraries. Note that in all the examples, an executable
program file is requested. You might want to request the other files once to see
what they look like. For these simple builds, however, neither the map file nor
symbol table file are particularly useful. Map files become useful when you are
working with overlays; they are described in Chapters 3, 4, and 6. Symbol table
files are chiefly useful when you are constructing your own resident libraries
(Chapter 7), or when you are using the COBOL-Sl symbolic debugger.

2-14

Building Programs

2.4.1

BASIC-PLUS-2 Examples Including Disk, Resident, and Cluster Libraries
Note that RSX directive emulation code must be installed on your system in order
to use BASIC-PLUS-2 V2.0.
To build a BASIC-PLUS-2 program using disk and resident libraries, you can

type:
RUN $TKB
TKB> PROG=OBJ1,OBJ2,OBJ3,LB:BP20TS/LB
TKB> I
ENTER OPTIONS:
TKB> LIBR=BP2SML:RO
TKB> LIBR=RMSRES:RO
TKB> UNITS=12
TKB> ASG=SY:5:6:7:8:9:10:11:12
TKB> EXTTSK=512
TKB> II

The first line tells the Task Builder to create the task image file, named
PROG.TSK. The object programs are OBJl.OBJ, OBJ2.0BJ, and OBJ3.0BJ.
The ILB switch references the BP20TS library. LB: is the system library device,
and the Task Builder assumes a default file type of .OLB for libraries.
You end the command line and indicate that you want to enter options by
typing a single slash (I) on a separate line. The Task Builder responds with
ENTER OPTIONS: and another TKB> prompt. You then enter the LIBR option,
designating BP2SML as the resident library to be mapped read-only. RMSRES is
the RMS resident library; it also is to be mapped read-only. (Symbols not resolved
by the resident library, BP2SML, will be resolved by BP20TS.OLB.)
The UNITS option declares the maximum number of 110 channels (units) that
your program will use. The ASG option relates these channels to devices. For
instance, the following example shows a maximum of twelve channels are used
by the program. Defaults are accepted for channels 1 through 4. Channels 5
through 12 are the public structure (SY:). EXTTSK allocates an additional 512
words of memory to your program. You then end Task Builder input by typing
two slash characters (II) on a separate line.
This BASIC-PLUS-2 example shows the use of cluster libraries:
RUN $TKB
TKB > MYPROG=PROG1,SUB1,SUB2,LB:BP20TS/LB
TKB> I
ENTER OPTIONS:
TKB> CLSTR=BP2RES,RMSRES:RO
TKB> UNITS=12
TKB> ASG=SY:5:6:7:8:9:10:11:12
TKB> EXTTSK=512
TKB> I I

In this example, you request the executable file MYPROG.TSK, consisting of the
object modules PROGl.OBJ, SUBl.OBJ, and SUB2.0BJ. The resident libraries
BP2RES and RMSRES are to be built to form a cluster using the upper 8K words
of address space (APRs 6 and 7). The libraries are to be mapped read-only. The
language library BP20TS is the default library.

Building Programs

2-15

2.4.2

PDP-11 COBOL Example Including Two Disk Libraries
To build a PDP-ll COBOL program, you can type:
RUN $TKB
TKB> OUT=PROG, SUB, SUB2,LB:COBLIB/LB,LB:RMSLIB/LB
TKB> / /

This command tells the Task Builder to create one file, the executable file,
named OUT.TSK The compiled object programs are PROG.OBJ, SUB.OBJ, and
SUB2.0BJ. Two libraries are referenced; COBLIB.OLB and RMSLIB.OLB. The
ILB switch indicates that the libraries are located in the library account (LB:).

2.4.3

COBOL-81 Examples Including Disk Library and Cluster Libraries
The following example illustrates building a COBOL-81 program:
RUN $TKB
TKB> FINAL=PROG1, PROG2, LB: C81CIS/LB
TKB> / /

With this command, the Task Builder creates the executable file FINAL.TSK from
the compiled object programs PROG1.0BJ and PROG2.0BJ, and from necessary
routines from the library for the Commercial Instruction Set (CIS), C81CIS.OLB.
The second example for COBOL-81 shows the use of cluster libraries:
RUN $TKB
TKB> FINAL=PROG1,PROG2,LB:C81CIS/LB
TKB> /
ENTER OPTIONS:
TKB> CLSTR=C81CIS, FDVRES, RMSRES :RO
TKB> / /

In the example above, you request the executable file FINAL.TSK, consisting of
the object modules PROG1.0BJ and PROG2.0BJ. The ILB switch references the
disk library C81CIS.OLB. The resident libraries C81CIS, FDVRES, and RMSRES
are to be built to form a cluster using the upper 8K words of address space (APRs
6 and 7). The libraries are to be mapped read-only. The language library C81CIS
is the default library. Note that while C81CIS in the command line refers to the
disk library, C81CIS in the CLSTR option refers to the resident library.

2.4.4

DIBOL Example Including Disk and Resident Libraries
The following example illustrates building a typical RMS DIBOL program:
RUN $TKB
TKB> PAY=HOURS,EMPLK,CHECK,MYLIB/LB, LB:DBRLIB/LB
TKB> /
ENTER OPTIONS:
TKB> LIBR=DBRRES :RO: 4
TKB> LIBR=RMSRES: RO: 6
TKB> / /

This example requests the executable file PAY.TSK The object modules used
are HOURS.OBJ, EMPLKOBJ, and CHECKOBJ. Modules are included from
the library MYLIB.OLB (on the system disk in your account) and the library
DBRLIB.OLB (in the system library account LB:). DBRRES is the DIBOL
resident library for RMS; it is to be mapped read-only, beginning in APR 4.
RMSRES is the RMS resident library; it also is to be mapped read-only, beginning
in APR 6.

2-16

Building Programs

2.4.5

FORTRAN-77 Examples Including One Disk Library
To build a FORTRAN-77 program, you can type:
RUN $TKB
TKB> BURNS=KNIGHT,DAY,LB:F4POTS/LB
TKB> / /

This example requests an executable file named BURNS.TSK. The files
KNIGHT.OBJ and DAY.OBJ are the compiled files to be used, along with
referenced routines from the library F4POTS.OLB.

2.4.6

MACRO Examples Including Resident Libraries
The following examples show the use of the LIBR and RESLIB options.
The first uses LIBR:
RUN $TKB
TKB> FINAL=FINAL,SUB1,SUB2
TKB> /
ENTER OPTIONS:
TKB> LIBR=RMSRES
TKB> / /

This example requests the executable file FINAL.TSK, constructed using the
compiled files FINAL.OBJ, SUBl.OBJ, and SUB2.0BJ. The resident library
RMSRES is linked in also. Note that in this case, no APR is given; the Task
Builder will use APRs 6 and 7 for RMSRES, so the system manager must have
installed the system with RSX directive emulation code as a part of the monitor.
The LIBR option is used because the files RMSRES.TSK and RMSRES.STB are
located on the system library device (LB:).
The next example uses the RESLIB option:
RUN $TKB
TKB> FINAL=FINAL,SUB1,SUB2
TKB> /
ENTER OPTIONS:
TKB> RESLIB=DRO: [1,150]RMSRES
TKB> / /

The same requests are made as in the previous example. In this case, the files
RMSRES.TSK and RMSRES.STB are located on the device DRO: in account
[1,150]. The RESLIB option is used instead of LIBR because the library is not in
LB:.

Building Programs

2-17

Part II
Overlays

Chapter 3

The Basic Concepts
If your program is too large to fit in the space available, you must specify an
overlay structure for it. The easiest way to find out if your program is too large is
to try to build it, using the steps outlined in Chapter 2. If you get the following
error message, your program is too large:
?Task has illegal memory limits

Languages that can dynamically allocate memory (such as BASIC-PLUS-2) may
not give this error at task build. Rather, they may produce another message at
run time, such as:
?Maximum memory exceeded

This chapter tells how to specify an overlay structure to eliminate this problem.
You design an overlay structure, such as the diagram in Figure 3-1, and describe
the structure to the Task Builder using an "ODL file"; a file written in the
Overlay Description Language.
Figure 3-1:

The OOL File Is Your "Blueprint" for Overlays

AWL:
BWL:
CWL:
LIB:

.ROOT MAIN-·(AWL, BWL, CWL)
.FCTR A-LIB- (A 1-LlB, A2-LlB)
.FCTR B-LlB
.FCTR C-LlB
.FCTR LB:BP20TS/LB
.END

MK-00573--00

The Basic Concepts

3-1

COBOL PROGRAMMERS NOTE

You cannot use the specific techniques described in this chapter to
construct overlays. In COBOL, you begin working with overlays within
the language itself by using the segmentation facility of the COBOL
compiler. Techniques are described in the PDP-ll COBOL User's Guide
and the RSTS IE COBOL-81 User's Guide.
COBOL programmers may want to read this chapter to get an idea of
what the PDP-ll COBOL or COBOL-81 compiler and MRG utility (for
PDP-ll COBOL) or BLDODL utility (for COBOL-81) are doing for you.
Chapter 6 describes overlays in terms of program sections and may also
be of interest to you.

3.1

What are Overlays?
The best way to explain overlays is by example. Suppose that the program
you have written consists of a main program (called MAIN) and two separately
compiled subroutines (called SUB1 and SUB2). Suppose further that MAIN calls
both SUB1 and SUB2, and that neither SUB1 nor SUB2 contain any calls to
separately compiled subroutines or to MAIN (see Figure 3-2).
Figure 3-2:

Outlining the Call Structure

MAIN

(CALL SUB 1)

(CALL SUB2)

6B
MK-00574-00

You can specify an overlay structure such that the run-time system (described in
Section 2.1) loads MAIN when the program is first run. When MAIN calls SUB1,
code built into MAIN by the Task Builder loads SUB1 for execution. Then, when
control passes back to MAIN and it calls SUB2, the loading code that was built
into MAIN brings SUB2 into memory overlaying SUB1 (see Figure 3-3).
Note that SUB1 and SUB2 do not call or use data from each other. This "logical
independence" is necessary for program pieces that overlay each other. In this
example, calls to routines or references to data that are not currently in memory
must be made from the "root"; the MAIN program.

3-2

The Basic Concepts

Figure 3-3:

A Simple Overlay in Memory

MAIN

SUB1
SUB2

(UNUSED MEMORY)
(UNuSED MEMORY)

TIME 1 --------~
..-

TIME 2

MK--Q0575-00

3.2 Constructing an ODL File: .ROOT, .FCTR, and .END
Commands
1b define an overlay structure to the Task Builder, you construct an "overlay
map": a file consisting of instructions written in a language called the "Overlay
Description Language." This file is often referred to as an ODL file.
Three commands form the heart of the Overlay Description Language: .ROOT,
.FCTR, and .END. 1b give you an idea of its simplicity, here is an ODL file for the
example shown in Figure 3-2:
MAINWL:
SUB1WL:
SUB2WL:
LIBR:

.ROOT
.FCTR
.FCTR
.FCTR
.FCTR

MAINWL-*(SUB1WL,SUB2WL)
MAIN-LIBR
SUB1-LIBR
SUB2-LIBR
LB:BP20TS/LB

. END

The .ROOT, .FCTR, and .END commands for this example are described in the
following sections.

3.2.1

The .ROOT Command
Every ODL file has one and only one .ROOT command; this command describes
the entire overlay structure. In the example at the start of Section 3.2, the
.ROOT command defines the entire structure in terms of "factors" defined in
following .FCTR commands. This is simply for the convenience of saving space in
the command line. You could have referred to the actual object files MAIN, SUB1,
SUB2, and the library LB:BP20TS in the .ROOT command and eliminated the
.FCTR commands entirely (see Section 3.2.4). However, the .ROOT command
would have been long and somewhat hard to read and interpret.

The Basic Concepts 3-3

The syntax of the .ROOT and .FCTR commands defines the overlay structure.
The first item following the .ROOT command indicates the root item, to be
assigned the lowest virtual addresses:
.ROOT

MAINWL-*(SUBIWL,SUB2WL)

The root item in tlus example is MAINWL. This item-named to denote "MAIN
With Library"-is defined in the following .FCTR command:
MAINWL:

.FCTR

MAIN-LIBR

For the moment, however, consider the .ROOT command. The following symbols
define the structure of the overlay:
Separates pieces to be concatenated in memory
Separates pieces to be overlaid in memory
( )

Groups pieces to be overlaid

Thus, the hyphen in the .ROOT command indicates that MAINWL is to be
concatenated with the structure (SUBIWL,SUB2WL). The parentheses indicate
grouping; they enclose items that are to overlay each other. The structure
inside-SUBIWL,SUB2WL-indicates SUBIWL and SUB2WL are to occupy the
same space, or overlay each other as necessary.
In other words, a comma separating two or more items within parentheses
indicates that they are to overlay each other. A dash between two items indicates
they are to be concatenated, with the item on the left assigned the lowest
addresses.
The asterisk (*) symbol shown in the example is an autoload indicator. It does
not affect the overlay structure, although it is very important. It tells the Task
Builder to generate what are called autoload vectors to ensure that overlay pieces
can be loaded properly when the program is executed.
The use of asterisks is discussed in detail in Chapter 5; you can save a little
space in your program if you use them carefully. However, the simplest rule, and
one that always ensures proper loading for overlay structures described in this
chapter, is to put an asterisk before the outermost left parenthesis in your ODL
file.

3.2.2

The .FCTR Command
Consider the example under discussion again:
MAINWL:
SUBIWL:
SUB2WL:
LIBR:

. ROOT
• FCTR
. FCTR
• FCTR
.FCTR
.END

MAINWL-*(SUBIWL,SUB2WL)
MAIN-LIBR
SUBI-LIBR
SUB2-LIBR
LB:BP20TS/LB

MAINWL, SUBIWL, and SUB2WL are all defined as factors in the lines following
the first line. The term "factor" is used in the sense of "ingredient." That is,
.FCTR commands are used to further define elements used in a .ROOT command
or a preceding .FCTR command.

3-4 The Basic Concepts

Note that the names used in the .ROOT command are defined in each .FCTR
command by the first field: the name terminated by a colon. Likewise, the name
LIBR, used in several of the .FCTR commands, is defined in the last .FCTR
command. In general, factor names can consist of 1-6 characters from the set A-Z,
0-9, and the dollar sign ($).
The .FCTR command also specifies an overlay structure; the same items and
operators used in a .ROOT command can also be used in a .FCTR command. In
the example, the first three .FCTR commands consist of two items separated by
a hyphen. Again, the hyphen separating two items means that the first item
is assigned the lowest addresses, and the second item is to be concatenated
following the first.
In the example shown at the start of Section 3.2, however, the concatenated
item is LIBR, defined by a later .FCTR command as the BP20TS library. When
an item in a hyphenated series is a file with the ILB switch, it means that the
first item's unresolved references are to be resolved from routines within that
disk library. In other words, the entire library is not concatenated. Only those
routines referenced are actually concatenated and added to the executable file.
The items MAIN, SUB1, and SUB2 are the compiled or assembled object files. As
with a simple build, the default file type for such files is .OBJ. The default file
type for a file with the ILB switch is .OLB.
Note that a .FCTR command can contain an item defined in another .FCTR
command. In general, .FCTR commands can be "nested" in this fashion up to 16
levels.

3.2.3

The .END Command
The .END command ends the ODL file; every ODL file must have one .ROOT
command and end with .END.

3.2.4

Flexibility of the Overlay Description language
From the preceding discussion, you probably have observed that there are many
ways to construct ODL files using the three basic commands and their operators.
For example, the fonowing ODL file has the same effect as the example in
Section 3.2:
.ROOT MAIN-LB:BP20TS/LB-*(SUBI-LB:BP20TS/LB,SUB2-LB:BP20TS/LB)
.END

The ODL file above has no .FCTR statements. The following file also produces
the same structure as the example at the beginning of Section 3.2:
.ROOT MAIN-LIBR-*(SUBI-LIBR,SUB2-LIBR)
LIBR:

.FCTR LB:BP20TS/LB
.END

The Basic Concepts

3-5

3.3 Using an OOL File When You Run TKB
To tell the Task Builder to build a program according to the structure specified in
an ODL file, you simply give the ODL file name with the switch IMP instead of
the object files in an ordinary command line. For example, to build the program
described in Sections 3.1 and 3.2, you can type:
RUN $TKB
TKB>MYFROG,MPFILE=OVERLY/MP
ENTER OPTIONS:
TKB>LIBR=BP2RES:RO
TKB>UNITS=12
TKB>ASG=SY:5:6:7:8:9:10:11:12
TKB>EXTTSK=512
TKB>//

When you specify IMP on the input file for your task, it must be the only input
file that you specify. Note that when you specify an ODL file, TKB automatically
prompts for option input. Therefore, do not use the single slash (/) to direct TKB
to prompt for options when you specify IMP on your input file.
The IMP switch indicates the file is an "overlay map," or ODL file. The default
file type for files with the IMP switch is .ODL. Thus, the file used here as an
overlay map is named OVERLY.ODL, on the system disk in the user's account.
The LIBR option declares that your program will access the resident library
BP2RES. UNITS, ASG, and EXTTSK are other options often useful with BASICPLUS-2 programs. For another language, use the appropriate command as
described in Chapter 2.
Note that you request a map file in this example. The map file is very useful
when working with overlays.

3.4 The Memory Map File
This section discusses how to determine the size of the programs and subprograms you want to overlay.
Suppose that the build in Section 3.3 produces the error "SEGMENT seg-name
HAS ADDR OVERFLOW: ALLOCATION DELETED". The program is too large;
you must reexamine it. Now, though, you have an important tool: the memory
map file, called in this case MPFILE.MAP. The first page of this map is shown
in Example 3-1. Note the highlighted section, titled "MYPROG.TSK OVERLAY
DESCRIPTION".
This section of the memory allocation map appears only if you request overlays
by using the IMP switch appended to an ODL file specification. To get this
information, then, you must specify the most reasonable overlay structure
possible without actually knowing the length of the pieces.
In the first three columns, this section gives, in octal, the base address, top address, and length, in bytes, of each overlay piece. The most relevant information
is given in the second of the two LENGTH columns: the decimal length of the
piece, in bytes. The MAIN program, for example, is 49,152 bytes long. SUB1 is
34,164 bytes, and SUB2 is 16,384 bytes.

3-6

The Basic Concepts

You are building the program to run under the RSX run-time system, which
allows 32K words, or 64K bytes for your program. Thus, you must restructure
the program to divide MAIN into further pieces to be overlaid. At 49152 bytes,
MAIN with SUB1 and SUB2 is too large to fit in the space available. 'lb do this
intelligently, however, you need to know more about the Task Builder.
Note that total task size and task image size show the space allocated for the
program minus a calculated overflow.

Example 3-1: Overlay Description of Memory Allocation Map
MAIN.TSK

Memory allocation map TKB 08.006
19-MAR-90
14:56

Page 1

Partition name
GEN
Identification
600319
Task Ule
[1,234]
Stack
limits: 001000 001777 001000 00512.
PRG xfr address: 012000
Total address windows: 2.
Task
extension
512. words
Task image size
25280. words
Total task size
25792. words
Task address limits: 000000 035047
R-W disk blk limits: 000002 000060 000057 00047.

MYPROG.TSK Overlay description:
Base
Top
Length
000000

042563

140000

49152.
34164.
16384.

MAIN
SUB1
SUB2

(Other pages of memory map)

3.5 Designing Overlays Intelligently: Considering Space and Time
The same considerations are necessary in designing an overlay structure as in
other aspects of computing: space and time. Some aspects of the problem of space
(how to get the pieces to fit) have been discussed. 'lb do the job well, you must
also consider the problem of time: how to get the pieces to fit so that they execute
in the least possible time.

The Basic Concepts

3-7

3.5.1

Considering Space: Two Possibilities for Example
Suppose that examining the program in our example reveals two possibilities for
dividing the program so that the pieces will fit.
In the first case, you divide MAIN into five parts by inserting calls in MAIN
in the source code. Now you have a "root" segment, MAIN, with five branches,
MAINl, MAIN2, MAIN3, SUBl, and SUB2. The call structure is outlined in
Figure 3-4.
Figure 3-4:

Outline of First Call Structure for Example

(CALL MAIN1) (CALL MAIN2) (CALL MAIN3) (CALL SUB 1) (CALL SUB2)

BB B BB
MK-00576-00

Note again the logical independence of the call structure for the items to be
overlaid. Defining the overlay structure based on the call structure is one way
to ensure the logical independence of the items in the overlay structure. In this
case, MAINl, MAIN2, MAIN3, SUB1, and SUB2 could not call each other or
refer to data in each other. These items overlay each other and will not reside
in memory at the same time. The ODL file for such a structure could look as
follows:
MAINWL:
MAINIL:
MAIN2L:
MAIN3L:
SUBIL:
SUB2L:
LIBR:

.ROOT MAINWL-*(MAINIL,MAIN2L,MAIN3L,SUBIL,SUB2L)
.FCTR MAIN-LIBR
.FCTR MAINI-LIBR
.FCTR MAIN2-LIBR
.FCTR MAIN3-LIBR
.FCTR SUBI-LIBR
.FCTR SUB2-LIBR
.FCTR LB:BP20TS/LB
.END

In the second case, you divide MAIN into two pieces and divide SUB2 into two
pieces called SUB2A and SUB2B. The outline for the call structure is shown in
Figure 3-5.

3-8 The Basic Concepts

Figure 3-5: Outline of Second Call Structure for Example

(CALL MAIN1)

(CALL SUB1)

(CALL MAIN2)

(CALL SUB2A)

ISUB~A I

(CALL SUB2B)

IS~B2B I
MK-00577-00

The ODL file for such a structure could look as shown below. Note the nested
parentheses used to group the pieces that overlay each other. In general, parentheses can be nested to 16 levels .
MAINWL:
MAINIL:
SUBIL:
MAIN2L:
SUB2AL:
SUB2BL:
LIBR:

. ROOT
.FCTR
.FCTR
.FCTR
.FCTR
.FCTR
.FCTR
.FCTR

MAINWL-*(MAINIL-SUBIL,MAIN2L-(SUB2AL,SUB2BL»
MAIN-LIBR
MAINI-LIBR
SUBI-LIBR
MAIN2-LIBR
SUB2A-LIBR
SUB2B-LIBR
LB:BP20TS/LB

. END

Now suppose you build the program successfully in both of the above cases. The
problem with space is resolved with either the structure shown in Figure 3-4
or in Figure 3-5. You would choose the structure that requires the least time to
execute, as described in the following section.

3.5.2

Considering Time: Reducing Disk Access
When you ask for overlays, the Task Builder inserts code into your program to
load the overlays properly. For the example in Figure 3-4, the Task Builder
inserts code into MAIN to load MAINl, MAIN2, MAIN3, SUBl, and SUB2 from
disk into memory when they are called. (MAIN itself is loaded by the run-time
system when the program is first run.)
Thus, when MAIN calls MAINl, the code inserted by the Task Builder is executed
to load MAINI from disk into memory for execution. When MAIN calls MAIN2,
this code is again executed to load MAIN2 from disk into memory, and so forth.
These disk accesses take time. You want to design your overlays to reduce the
number of disk accesses.

The Basic Concepts

3-9

In general, the Task Builder analyzes your ODL file to detennine the best way
to store pieces on disk so that they can be loaded quickly. It constructs the
executable program file in "segments" that are loaded with one disk access.
Pieces connected by a dash (-) are stored in one segment. Pieces separated by a
comma are stored in separate segments.
Thus, the executable file for the ODL file in Figure 3-4 consists of the main
program (loaded by the run-time system) and five segments each requiring
a separate disk access for loading. The executable file for the ODL file in
Figure 3-5 consists ofthe main program and four segments. MAINl and SUBl,
connected by a dash in the ODL file, are stored as one segment. When MAIN
calls MAINl, MAINl and SUBl are loaded together. Then, when MAINl calls
SUBl, no separate disk access is necessary: SUBl is already in memory.
MAIN2, SUB2A, and SUB2B are stored as separate segments. Each requires a
separate disk access.
Thus, assuming each call is made only once, the structure in Figure 3-4 calls for
five disk accesses. The structure in Figure 3-5 calls for four disk accesses. Since
both fit, you would choose the structure shown in Figure 3-5.

3.6 Logical Independence of Items in Overlay Structure
This section discusses the need for the logical independence of items in an overlay
structure and suggests that basing the overlay structure on the call structure is
a reasonable way to approach overlay structure design. If your program has a
complex call structure, however, this approach may not be feasible.
You can still visualize the tree-like structure we have shown previously, and you
can still specify an overlay structure in terms of separately assembled or compiled
program and subroutine files. However, you must consider the sequence of calls
these pieces make to each other. In general, you must structure the overlay tree
so that calls (or references to data) take place between pieces that are along the
same path. Calls or references to data cannot take place between pieces that are
along different paths. A path is simply any route from the root of the structure
that follows a series of branches to an outermost piece of the tree.
Figure 3-6 shows a structure that is specified by the following ODL commands:
FCTR1:
AL:
BL:
CL:
DL:
EL:
FL:
GL:
LIBR:

.ROOT
.FCTR
.FCTR
.FCTR
.FCTR
.FCTR
.FCTR
.FCTR
.FCTR
. FCTR
. END

AL-BL-*(CL,FCTR1)
DL-(EL,FL,GL)
A-LIBR
B-LIBR
C-LIBR
D-LIBR
E-LIBR
F-LIBR
G-LIBR
LB:F4POTS/LB

Figure 3-6 shows pieces that overlay each other as separate "branches" of the
tree. C and D would start at the same virtual address, as would E, F, and G. The
paths in this structure are A-B-C, A-B-D-E, A-B-D-E, and A-B-D-G. Calls may be
made between pieces on any of these paths. However, F could not call G, E, or C;
C could not call D, E, F, or G; and so forth.

3-10

The Basic Concepts

Figure 3-6:

Separate Paths in an Overlay Structure

FOUR PATHS:

C
I
I
I

r--- - -- - - - - - --- --~ :------- ------------ -- i
I

F
MK-D0578-00

3.7 Resolution of Global Symbols
In the last section, it was noted that overlay pieces that are on separate paths
cannot call each other or refer to data in each other. If you specify such a
structure, the Task Builder gives you error messages about multiply defined
or ambiguously defined global symbols. Since these errors can be one of the
most frustrating aspects of task building, further clarification of the underlying
concepts is necessary.

3.7.1

What Is a Global Symbol?
All languages provide the facility for defining and referring to symbols. In
general, a symbol is a name that is eventually translated to an address for a
location in computer memory. The location may contain data or a computer
instruction.
Symbols can be classified as either local or global. A local symbol is one that
is both defined and referenced within one program or subprogram. That is, its
definition and usage are in the same (local) area_
A global symbol is one that can be defined in one program or subprogram and
referred to by another separately compiled or assembled program or subprogram.
While you may not be aware of it, for example, the FORTRAN compiler defines
a name you give to a COMMON area as a global symbol. Similar translations
take place in all languages for common areas and entry points to programs and
subprograms, including subprograms contained in libraries.

The Basic Concepts

3-11

3.7.2

Undefined, Multiply Defined, and Ambiguously Defined Global Symbols
The Task Builder resolves references to global symbols at build time. In general,
you can define two global symbols with the same name if they are on separate
paths and are not referenced from a piece that is common to both paths.
If you define a global symbol on one path but refer to it on another path, the

symbol is diagnosed as undefined where it is referenced.
If you define two global symbols with the same name on the same path, the

symbol is multiply defined.
If you define two global symbols with the same name on different paths, but

the symbol is referenced from a piece that is common to both, the symbol is
ambiguously defined.
Examine the overlay structure in Figure 3-7. The global symbol Q is defined
in AO and BO. The references to Q in A22 and 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; the definitions and references occupy
separate paths.
The global symbol R is defined in 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 AO and BO. References to S from Al, A21,
or A22 are resolved by the definition in AO. References to S in Bl and B2 are
resolved by the definition in BO. However, the reference to Sin CNTRL cannot
be resolved, because there are two different definitions of S on separate paths
through CNTRL. The global symbol S is ambiguously defined.
The global symbol T is defined in both A21 and AO. Since there is a single path
through the two definitions (CNTRL-AO-A2-A21), the global symbol T is multiply
defined.

3-12 The Basic Concepts

Figure 3-7:

Resolving Global Symbols

eNTRl
S(REF)

80
Q(DEF)
S(DEF)

Q(DEF)
S(DEF)
T(DEF)

I
I
A1
Q(REF)
R(REF)
S(REF)

I
A21
T(DEF)
S(REF)

A2
R(DEF)

81
Q(REF)
S(REF)

I
82
S(REF)

I
A22
R(REF)
Q(REF)
S(REF)

MK-00579-00

3.7.3

How Routines Are Inserted from Libraries
In all the examples so far, we have shown a library concatenated (using the
dash in the ODL file) at the end of the root and every segment in the overlay
structure. Unless you know which library routines are used by each piece of your
program, this is the best way to ensure that library routines are properly inserted
from the desired disk libraries. The Task Builder then ensures that routines
referred to by more than one piece are accessible to all pieces. For example,
consider the following ODL file for the overlay structure shown in Figure 3-8:
ROOTL:
AL:
BL:
B1L:
B2L:
LIBR:

• ROOT
.FCTR
.FCTR
. FCTR
. FCTR
. FCTR
. FCTR
.END

ROOTL-*(AL,BL-(B1L,B2L»
ROOT-LIBR
A-Al-LIBR
B-LIBR
Bl-LIBR
B2-LIBR
LB:F4POTS/LB

The Basic Concepts

3-13

Figure 3-8:

Resolving Global Symbols from Disk Libraries

ROOT
REF $READ
REF $WRITE
$READ
$WRITE

I
I

A
REF $READ
REF $ASIN

B
REF $READ
REF $ASIN
REF $COS

A1
REF $WRITE

$ASIN
$COS

$ASIN

I
I

B1
REF $COS
REF $ABS

B2
REF $READ

$ABS

MK-00580-00

As shown in Figure 3-8, the ROOT section calls the routines $READ and
$WRITE. The Task Builder resolves these references by building the routines
into ROOT. The references to $READ in A and B are then resolved from ROOT.
The reference to $WRITE in Al is likewise resolved from ROOT.
Both A and B refer to the $ASIN routine. Since A and B are on different paths,
the Task Builder puts the $ASIN routine in both A and B.
Both Band Bl refer to the $COS routine; it is built into B because B is closer
to the root than Bl. The reference to $COS in Bl is resolved by referring to the
routine in B.
The $ABS routine is referred to in Bl only. It is built into Bl.

3-14 The Basic Concepts

If you know which routines are called from the various pieces of your program,
you can shorten the time necessary to build your program by specifying the
routines directly. You make a direct specification by appending a colon and the
routine name to the ILB switch. For example, to build the structure shown in
Figure 3-8, you could use:
ROOTL:
AL:
BL:
B1L:

.ROOT
.FCTR
.FCTR
.FCTR
.FCTR
.END

ROOTL-*(AL,BL-(B1L,B2»
ROOT-LB:F4POTS/LB:$READ:$WRITE
A-Al-LB:F4POTS/LB:$ASIN
B-LB:F4POTS/LB:$ASIN:$COS
Bl-LB:F4POTS/LB:$ABS

You could also request a different structure. To build all the required routines
into the root, for example, you could specify:
ROOTL:

.ROOT ROOTL-*(A-Al,B-(Bl,B2»
.FCTR ROOT-LB:F4POTS/LB:$READ:$WRITE:$ASIN:$COS:$ABS
. END

In general, up to eight routines can be specified on one ILB switch.

3.7.4 The Default Library
The Task Builder searches through the overlay structure to resolve global
symbols. If any symbols are undefined after it examines all the pieces you specify,
it will search the default library (normally LB:SYSLIB.OLB). If it can resolve a
global symbol by inserting a piece from this library, it will do so.
Note that because SYSLIB.OLB used the MACRO assembly language judiciously,
the code is not inserted as described in Section 3.7.3. Units called program
sections have been carefully defined using MACRO, such that the code in SYSLIB
takes as little space as possible. Program sections, and how the Task Builder
builds programs with them, are described in Chapter 6.
For libraries built from compiler-language routines, however, the information in
Section 3.7.3 would apply.

The Basic Concepts

3-15

Chapter 4

Co-Trees: Another Way to Save Space
Chapter 3 describes the basics of specifying an overlay structure in an ODL file.
This chapter discusses another overlay structure: co-trees. Co-trees are slightly
more complex structures than any previously discussed. If applicable to your
call structure, however, they can be extremely useful in cutting down the virtual
address space your program takes (see Figure 4-1).
Figure 4-1:

Co-Trees Save More Space Than Simple Overlays

ODL FILE:
.ROOT MANTRE, COTRE
MANTRE: .FCTR MAIN-L1B-.(SUB1-L1B, SUB2-L1B)
COTRE: .FCTR *COTREE-L1B-.(COSUB1-L1B, COSUB2-L1B)
LIB: .FCTR LB:BP20TS/LB
.END
MK-0058HlO

4.1 The Co-Tree Structu re
As the name implies, co-trees allow you to define more than one tree structure
in an overlay description. For example, suppose that A and B are routines that
are called from several branches of a tree. You could define A and B as part
Co-Trees: Another Way to Save Space

4-1

of the root, so that they are always accessible from any branch of the tree (see
Figure 4-2).
Figure 4-2:

Putting A and B in the Root

MAIN
(CALL
SUB1)

(CALL
SUB2)
(CALL
A)

A
(CALL
A)

SUB2

MK-00582-00

The ODL file for such a structure could appear as follows:
LIBR:

.ROOT MAIN-A-B-LIBR-*(SUB1-LIBR,SUB2-LIBR)
.FCTR LB:BP20TS/LB
.END

Since A and B never call each other, however, they do not need to reside in
memory at the same time. To save space, you could define A and B as part of a
co-tree, such that they overlay each other. Like the main tree, co-trees must have
a root. In this case, the root is called "COTRE" (see Figure 4-3).
Figure 4-3:

A Co-Tree Structure

----------n

(CALL SUB1) (CALL SUB2)

~cf

(CALL COTRE)

(CALL A)

(CALL B)

(CALL COTRE)
MK-00583-00

4-2 Co-Trees: Another Way to Save Space

The ODL file for such a structure could be:

MANTRE:
COTREE:
LIBR:

. NAME
. ROOT
.FCTR
. FCTR
.FCTR
.END

COTRE
MANTRE,COTREE
MAIN-LIBR-* (SUBI-LIBR, SUB2-LIBR)
*COTRE-LIBR-*(A-LIBR,B-LIBR)
LB:BP20TS/LB

To separate co-trees, use the comma-not enclosed in parentheses - as between
MANTRE and COTREE in the .ROOT statement above. (When the comma is
used within parentheses, it separates pieces to be overlaid.) Note also that you
put an autoload indicator (*) before the co-tree root and before the outermost left
parenthesis in the co-tree overlay description.
To get an idea of how co-trees are loaded during execution, see Figure 4-4. This
figure assumes that the call sequence is: MAIN calls SUBl, which calls COTRE
twice: once to execute A and once to execute B. MAIN then calls SUB2, which
calls COTRE to call A and B again.
The run-time loader loads MAIN. The remaining pieces are loaded by code
inserted in MAIN by the Task Builder. Once called (at time 3 in Figure 4-4),
COTRE is resident in memory for the rest of the run. Note that it begins at the
place where the longest part of the main tree ends (after SUB2).
As shown in Figure 4-4, storage is not shared between trees. Any piece in a
tree can call or refer to data in another tree without displacing pieces from the
calling tree. However, calls back and forth between trees (called cross-tree cans)
can cause problems. For example, suppose that at time 4 in Figure 4-4 the
subprogram A had called SUB2. SUB2 would be loaded, displacing SUBl from
the main tree. In the normal course of events, SUB2 would return control to
A, which would return control to an address generated for SUBl at build time.
SUBl is no longer in memory, however. Control would be passed to some location
in SUB2, which has displaced SUBl in memory.

To keep this from happening inadvertently, the Task Builder restricts its search
through the structure for references to the default library if you specify co-trees.
The Task Builder makes one pass through the entire structure trying to resolve
global symbols from the pieces you have specified in the ODL file. If there are
unresolved symbols after this first pass, the Task Builder makes another pass,
attempting to resolve undefined symbols from the default system library. If you
have specified co-trees, the Task Builder restricts its search during this second
pass.
For example, if the Task Builder resolves a symbol in one tree by inserting a
module from the default system library, it does not search through co-trees to see
if there are other unresolved references to this module. It restricts its search to
the current tree and the root of the main tree. This procedure eliminates crosstree calls like that described above; necessary code is not inadvertently displaced.

Co-Trees: Another Way to Save Space

4-3

Figure 4-4:

How a Co-Tree Is Loaded During Program Execution

MAIN

'7 CALL SUB1 :: _
~

SUB1

MAIN
SUB1
CALL COTRE ::::.

MAIN

SUB1

,
"

1--:-;;";";";'=---1 "

COTRE

~..;:;.:...;==-=---t "

TIME 1

TIME 2

TIME 3

TIME 4

TIME 5

MAIN
LOADED

MAIN CALLS
SUB1; SUB1
LOADED

SUB1 CALLS
COTRE;COTRE
LOADED

COTRE CALLS
A; A LOADED

COTRE CALLS
B; B LOADED

MAIN

SUB2

MAIN
CALL SUB2
SUB2

COTRE

rALL COTRE ~
'"
COTRE
/
CALL A
A

COTRE
CALL B

,
/

TIME 6

TIME 7

CONTROL FALLS
SUB2 CALLS
BACK TO MAIN,
COTRE(ALREADY
WHICH CALLS SUB2:
THERE)COTRE
SUB2 LOADED
CALLS A; A LOADED

TIME 8
COTRE CALLS
B; B LOADED
MK--{)0584-{)O

4.2 Using the .NAME Command for a Co-Tree Root
The example in Section 4.1 defined a separate co-tree root routine called COTRE.
You can eliminate the need for a real routine (which takes space) by using the
.NAME command to define the name of a dummy root for a co-tree. The calls out
of SUB 1 and SUB2 can then refer to A and B directly, and they will be loaded
properly. For example, the ODL file could be:

MANTRE:
COTREE:
LIBR:

.NAME
.ROOT
.FCTR
.FCTR
.FCTR
. END

NULL
MANTRE,COTREE
MAIN-LIBR-*(SUB1-LIBR,SUB2-LIBR)
NULL-*(A-LIBR,B-LIBR)
LB:BP20TS/LB

The .NAME command lets you give a name to a piece of the overlay structure.
(You can also use it to assign certain attributes to pieces of the overlay structure,
described further in Section 6.5.) The .NAME command is described in detail in
Section 13.4.
4-4

Co-Trees: Another Way to Save Space

Note in the preceding example that you do not need to use an autoload indicator
(*) before a null root in a co-tree.

4.3 Designing the Most Space-Saving Co-Trees
Co-trees can save the most space when the pieces being overlaid in each tree are
about the same size. For example, look at the structure of the example from the
previous sections. Figure 4-5 shows three different structures. Figure 4-5 also
shows a new way of looking at overlay structures that takes the size of the pieces
into account. You may find this particularly useful when dealing with co-trees.
Figure 4-5:

Co-trees Save More Space When Pieces Are the Same Size

MAIN

SUB1

SUB1 SUB2 SUB3
SUB2

A
SUB1

A
SUB2

NO CO-TREE

FIRST CO-TREE

REDESIGNED CO-TREE
MK-00585-00

The first structure in Figure 4-5 shows the original overlay design, with A
and B built after MAIN in the root of the overlay structure. SUBl and SUB2
overlay each other, after the root. The second structure in Figure 4-5 shows the
structure arrived at in the previous section: A and B are overlaid in a co-tree. By
comparing the first and second structures in Figure 4-5, you can see that co-trees
can save space. The total size of the program in virtual address space is smaller
using the co-tree.
Note in the second structure, however, that SUB2 and B are much larger than
their counterparts SUBl and A. The space shown between SUBl and the A-B
co-tree is essentially wasted. If you cut down SUB2, you can "squeeze" the co-tree
down further in virtual address space. Furthermore, if you reduce the size of B,
you can also reduce the total size of the program in virtual address space.
The third structure in Figure 4-5 shows a better co-tree. SUB2 has been divided
into two routines, SUB2 and SUB3. These routines are overlaid and are about
the same size as each other and SUBl. B has also been divided into two separate
routines, Band C. Again, the routines are overlaid and are about the same size as
each other and A. Note that the total size of the program in virtual address space
has been reduced even more than the second structure shown in Figure 4-5.

Co-Trees: Another Way to Save Space

4-5

Thus, the general rule for constructing tight programs using co-trees is: use small
subprograms of uniform size. If you are using co-trees at all, you are probably
more concerned with space than with your program's execution time. You may
not lose that much time, though, depending on how the calls are structured.
Remember that calls can be made between co-trees without necessarily causing a
new overlay segment to be loaded from disk.
For example, suppose that in the third structure of Figure 4-5, SUBl calls A
A will remain in memory until B or C is called. Suppose coIitrol passes back to
SUBl to call A again, back to MAIN, and on to SUB2, which is loaded and calls
A A is still in memory. It does not need to be loaded again.

4.4 Co-Trees and High-Level Languages
As you can see from the previous sections, using co-trees can save space. The first
time you try to build one using a high-level language, however, you will likely get
a number of diagnostic error messages flagging multiply defined, ambiguously
defined, and undefined symbols. This can be a bit disconcerting, especically since
many of the symbols will not be any that you have referred to or defined in your
program. Furthermore, the total virtual address space taken by the program may
be even larger than that taken without co-trees.
The symbols are from library routines that have been inserted by the Task
Builder. Note that the Task Builder is very careful about where it puts routines
that are called from outside the main tree root on different trees in a co-tree
structure. When you put general library references in your ODL file the Task
Builder builds any routine that is called from outside the main tree root on
two or more paths in two or more trees, into all the paths and trees where it is
referenced. The Task Builder then resolves references to a routine in a particular
path in a tree by referring to the routine built into that path on that tree.
So, the program will run as it has been built (unless you have made errors in
your program, of course). Still, you may not want these routines built into each
tree, where they can take more space than might actually be necessary. So,
the Task Builder flags the symbols it finds as multiply defined or ambiguously
defined, so that you can correct the situation if you want to.

4.4.1

Sample Source Program and Subprograms
Consider the following BASIC-PLUS-2 program and subprograms.
The main program, USER, simply calls three subprograms: INTRO, CRUNCH,
and CHATR. INTRO displays a question at the user's terminal, and accepts the
user's response: two integers. CRUNCH performs addition, multiplication, and
subtraction on the two input numbers and calls CALC2 and CALC1, passing on
the two input numbers. CHATR takes the sum, product, and difference calculated
by CRUNCH and displays the values on the user's terminaL It then calls CALCl
and CALC2. CALCl subtracts the two values and displays the difference. CALC2
adds the two values and displays the sum.

4-6

Co-Trees: Another Way to Save Space

Source for Program USER
10
20
30
40

CALL INTRO(A1%,B1%)
CALL CRUNCH(A1%,B1%,SUMM%,PRODUCT%,DIFFER%)
CALL CHATR(A1%,B1%,SUMM%,PRODUCT%,DIFFER%)
END

Source for Subprogram INTRO
10
20
30

SUB INTRO(AA%,BA%)
INPUT "INPUT TWO NUMBERS":AA%,BA%
SUBEND

Source for Subprogram CRUNCH
10
20
30
40
50
60
70

SUB CRUNCH(AB%,BB%,CA%,CB%,CC%)
CA%
AB% + BB%
CB% = AB% * BB%
CC% = AB% - BB%
CALL CALC2(AB%,BB%)
CALL CALC1(AB%,BB%)
SUBEND

Source for Subprogram CHATR
10
20
30
40
50
60
70

SUB CHATR(AC%,BC%,CA%,CB%,CC%)
PRINT "THE SUM OF ";AC%;" AND ";BC%;" IS ";CA%
PRINT "THE PRODUCT OF ";AC%;" AND ":BC%;" IS ";CB%
PRINT "THE DIFFERENCE OF ";AC%;" AND ";BC%;" IS ";CC%
CALL CALC1(AC%,BC%)
CALL CALC2(AC%,BC%)
SUBEND

Source for Subprogram CALC1
10
20
30
40

SUB CALC1(AD%,BD%)
DA%=AD%-BD%
PRINT "THE COTREE DIFFERENCE IS ":DA%
SUBEND

Source for Subprogram CALC2
10
20
30
40

SUB CALC2(AE%,BE%)
EA%=AE%+BE%
PRINT "THE COTREE SUM IS ";EA%
SUBEND

4.4.2 Outlining the Sample Program's Call Structure
As Figure 4-6 shows, the sample program and its subprograms fit the general
situation where co-trees can help: one or more subprograms called by one or more
other subprograms.

Co-Trees: Another Way to Save Space

4-7

Figure 4-6:

Call Structure for Sample Program

USER

I
(CALL INTRO)

(CALL CRUNCH)

(CALL CHATR)

INTRO

CRUNCH

CHATR

I
(CALL CALC2)

(CALL CALC1)

(CALL CALC2)

CALC2

CALC1

CALC2
MK-00586-00

4.4.3

Compiling the Sample Program and Subprograms
The general steps for compiling a BASIC-PLUS-2 program are:

RUN $BASIC2
BASIC2

- ..f - - - - - - -

OLD source-file

(the prompt from BASIC-PLUS-2)

BASIC2

- ..t__------------'

COMPILE

/OBJ

For example, to compile a source file named USERB2S, type:
RUN $BASIC2
BASIC2
OLD USER
BASIC2
COMPILE /OBJ

These commands compile the file USERB2S, creating the file USEROBJ. (.B2S
and .OBJ are the default file types assumed by BASIC-PLUS-2.)

4-8

Co-Trees: Anothl:lr Way to Save Space

4.4.4

First Build for Sample Program: Putting Subprograms in the Root
Mter creating the object files, the next step is task building. For the first build,
without co-trees, we put CALC1 and CALC2 in the root (Figure 4-7).
Figure 4-7:

First Build Structure for Sample Program

USER
CALC1
CALC2

INTRO

CRUNCH

CHATR
MK-00586-01

The ODL file for such a str ucture could be:
INTWL:
CRUNWL:
CHATWL:
LIBR:

.ROOT USER-CALCI-CALC2-LIBR-*(INTWL,CHATWL,CRUNWL)
.FCTR INTRO-LIBR
.FCTR CRUNCH-LIBR
.FCTR CHATR-LIBR
.FCTR LB:BP20TS/LB
.END

Calling the above file OVER1.0DL, the build process is:
RUN $TKB
TKB> TRY1,TRY1=OVER1/MP
ENTER OPTIONS:
TKB>UNITS=12
TKB>ASG=SY:5:6:7:8:9:10:11:12
TKB>EXTTSK=512
TKB> //

The build proceeds without error. Examining the map file, TRY1.MAP, you see
the first page shown in Example 4-1.
The significant information is highlighted in Example 4-1. The TASK IMAGE
SIZE is 6528 words, or 13056 bytes. This means that the total amount of virtual
address space that the program will take is 13056 bytes. Further down, the size
is itemized by segment. Segment USER (constructed from the files USER.OBJ,
CALC 1. OBJ, and CALC2.0BJ, plus library routines from BP20TS.OLB) requires
11348 bytes; INTRO, 1696 bytes; CHATR, 380 bytes; and CRUNCH, 196 bytes.
In subsequent builds, you will see the structure (shown by the way the segment
names are indented) and the sizes change.

Co-Trees: Another Way to Save Space

4-9

Example 4-1:
TRY1.TSK

First Page of Map File for Sample Program

Memory allocation map TKB 08.006
15-MAY-90
14:46

Page 1

Partition name
GEN
Identification
000708
Task UIC
[1,196]
Stack
limits: 001000 001777 001000 00512.
PRG xfr address: 022462
Total address windows: 1.
Task extension : 512 words
Task image size
6528. words
Total task size
7040. words
Task address limits: 000000 031363
R-W disk blk limits: 000002 000036 000035 00029.

TRY1.TSK Overlay description:
Base

Top

000000
026124
026124
026124

026123
031363
026717
026427

Length
026124
003240
000574
000304

11348.
01696.
00380.
00196.

USER
INTRO
CHATR
CRUNCH
MK-01049-00

4.4.5

Second Build for Sample Program: Using a Co-Tree
For the second build of the sample program, use the co-tree structure shown in
Figure 4-8.
Figure 4-8: Structure for Second Build of Sample Program

INTRO

CRUNCH

CHATR

CALC1

CALC2

MK-00586-02

The ODL file for such a structure could be:

COTRWL:
USERWL:
INTWL:
CHATWL:
CRUNWL:
LIBR:

4-10

.NAME NULL
.ROOT USERWL,COTRWL
.FCTR NULL-*(CALC1-LIBR,CALC2-LIBR)
.FCTR USER-LIBR-*(INTWL,CHATWL,CRUNWL)
.FCTR INTRO-LIBR
.FCTR CHATR-LIBR
.FCTR CRUNCH-LIBR
.FCTR LB:BP20TS/LB
. END

Co-Trees: Another Way to Save Space

Calling the file above OVER2.0DL, the build process is:
RUN $TKB
TKB> TRY2,TRY2=OVER2/MP
ENTER OPTIONS:
TKB> UNITS=12
TKB>ASG=SY:5:6:7:8:9:10:11:12
TKB>EXTTSK=512
TKB> //

This run, unlike the first, produces a blizzard of diagnostic error messages:
TKB -- *DIAG* --

MODULE CALCl AMBIGUOUSLY DEFINES SYMBOL xxxx

TKB -- *DIAG* --

MODULE $ICINI MULTIPLY DEFINES SYMBOL xxxx

TKB -- *DIAG* --

MODULE $JPMOV MULTIPLY DEFINES SYMBOL xxxx

It is useful to take note of the modules mentioned, for reasons that become clear
later when you look at the memory map. The modules are, in order: CALCl,
$ICINI, $JPMOV, $ICWRT, $ECONV, $ICFNS, $STFNl, CALC2, (and again)
$ICINI, $JPMOV, $ICWRT, $ECONV, $ICFNS, and $STFNl.
If you try running the program, (by typing RUN TRY2.TSK), it works. So the
Task Builder's error messages are only diagnostic messages, as indicated.

Example 4-2 shows two pages of the relevant information from the map file
TRY2.MAP. Page 2 of the map shows that the total size of the program has grown
from 6528 words in the first build to 7552 words for the second build. This would
seem an inauspicious start for a memory-saving co-tree structure, but you can be
prepared for this and look for the reasons.
Page 5 shows the start of the information you are most interested in at this point.
The highlighted portion under the TITLE column shows the names of library
routines that have been built into the INTRO piece of the overlay structure. You
know that they are library routines because the FILE column shows them as
from the library file BP20TS.OLB .
Following pages of the map (not shown in Example 4-2) would show similar
entries for library routines in the overlay pieces CRUNCH, CHATR, CALCl, and
CALC2.

Co-Trees: Another Way to Save Space

4-11

Example 4-2:

Excerpts from Map File for Second Build of Sample Program

Memory allocation map TKB 08.006
15-MAY-90
13:17

TRY2.TSK
CALC2

Page 2

Partition name
GEN
Identification
000708
Task UIC
[1,196]
Stack
limits: 001000 001777 001000 00512.
PRG xfr address: 016030
Total address windows: 1.
Task extension
512. words
Task image size
7552. words
Total task size
8064. words
Task address limits: 000000 035313
R-W disk blk limits: 000002 000054 000053 00043.

TRY2.TSK Overlay description:
Base

Top

Length

000000
021044
021044
021044
030524
030524
030524

021043
030523
026173
021577
030523
035313
035303

------

TRY2.TSK
USER

021044
007460
005130
000534
000000
004570
004560

08740.
03888.
02648.
00348.
00000.
02424.
02416.

USER
INTRO
CHATR
CRUNCH
NULL
CALC 1
CALC2

Memory allocation map TKB 08.006
15-MAY-90
13:17

Page 5

*** Segment: INTRO
R/W mem limits: 021044 030523 007460 03888.
Disk blk limits: 000024 000033 000010 00008.
Memory allocation synopsis:
Section

Title

Ident

File

-------

BLK.: (RW,I,LCL,REL,CON) 021044 000000 00000.
BP20TS: (RW,I,LCL,REL,CON) 021044 007272 03770.
021044 000422 00274.
021466 002004 01028.
023472 000656 00430.
024350 000642 00418.
025212 002404 01248.
027616 000226 00150.
030044 000202 00130.
030246 000070 00056.
$ARRAY: (RW,D,LCL,REL,CON) 030336 000000 00000.

4-12

Co-Trees: Another Way to Save Space

$ICINI 23CM
$ ICRED 53CM
$ ICWRT 40CM
$STMOS 16CM
$ ECONV 24CM
$ICFNS llRE
$STLSS 08CM
$STFN1 06CM

BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB

At this point, it is useful to sketch the information shown in the map file, listing
the routines included in each overlaid piece from the library BP20TS.OLB.
Figure 4-9 is such a sketch, showing the relative sizes of the pieces and naming
the library routines built into each of the overlaid pieces.
NOTE

Library routines have also been built into the root segment, USER, but
they are of no concern. It is theoretically possible that some of these
routines could be overlaid in their own tree. However, it is difficult to
know the sequence in which such routines are called from other trees.
You would have to look at an assembly-language listing of the compiled
code to determine the sequence of calls.
That is, overlaying such routines in their own tree could, and probably
would, result in the cross-tree call problem mentioned in Section 4.l.
An overlay piece could inadvertently displace another overlay piece in
memory, causing errors at execution time.
Figure 4-9 is the basis of the analysis for "fine-tuning" a build using co-trees with
a high-level language. Now you can see more clearly just what the Task Builder
has done and why.
First, it has built the routines $ICINI, $ICWRT, $ECONY, $ICFNS, and $STFNl
into two paths in each of the two trees: that is, into INTRO and CHATR in the
main tree, and CALCl and CALC2 in the co-tree. This was indeed the most
reasonable thing for the Task Builder to do; it had no way of knowing whether
to resolve the references in CALCl and CALC2 with the definitions in INTRO or
the definitions in CHATR. So, it built the routines into CALCl and CALC2 again,
and flagged the routines (modules) and symbols for your examination.

Co-Trees: Another Way to Save Space

4-13

Figure 4-9:

Sketch of the Structure for Second Build of Sample Program

USER

INTRO
3888 BYTES
$ICINI
$ICRED
$ICWRT
$STMOS
$ECONV
$ICFNS
$STLSS
$STFN1

8740 BYTES

CRUNCH
348 BYTES
$JPADD
$JPMOV
$JMUL
$JPSUB

CALC1
2424 BYTES
$ICINI
$JPMOV
$ICWRT
$ECONV
$ICFNS
$STFN1

CHATR
2648 BYTES
$ICINI
$JPMOV
$ICWRT
$ECONV
$ICFNS
$STFN1

CALC2
2416 BYTES
$ICINI
$JPMOV
$ICWRT
$ECONV
$ICFNS
$STFN1

MK-01050-00

To save space, then, you can build one copy of each of these routines into the
root, where they would be accessible from all branches of all trees (as shown in
Section 4.4.6. First, however, continue with the analysis.

4-14 Co-Trees: Another Way to Save Space

The only other routine that appears in more than one path on more than one
tree is $JPMOV, appearing in CRUNCH, CHATR, CALC1, and CALC2. Nowlook at the structure from the viewpoint of "overlaid pieces should be about the
same size." CRUNCH is quite small at 348 bytes. CHATR and CRUNCH together
about equal the size of INTRO. You can link CRUNCH and CHATR together
using the following ODL commands:

USERWL:

.FCTR

USER-LIB-* (INTWL, CRUNWL)

CRUNWL:

.FCTR

CRUNCH-CHATR-LIBR

This combination has the advantage in that it also consolidates the references
to $JPMOV from two paths in the main tree to only one path. The Task Builder
can then resolve the references to $JPMOV in CALC1 and CALC2 with the
routine built into the branch in the main tree. Since in this branch, CRUNCH
and CHATR both call CALC1 and CALC2, and since CALC1 and CALC2 will not
make calls to any other paths in the main tree, you will not have any problem
with inadvertently displaced pieces at runtime.

4.4.6

Third Build for Sample Program: Restructured Tree and Library
Routines in Root
You are ready to build the program again using the structure shown in
Figure 4-10.
Figure 4-10:

Structure for Third Build of Sample Program

~--------~
INTRO

CRUNCH

CALC1

CALC2

CHATR
MK-00586-03

Co-Trees: Another Way to Save Space

4-15

In addition to specifying the main program and subprograms, you also want to
build the library routines $ICINI, $ICWRT, $ECONY, $ICFNS, and $STFNI into
the root. Do this by using the ILB switch, followed by specific routine names
separated by colons. For example:

COTRWL:
USERWL:
INTWL:
CRUNWL:
LIB:
LIB1:
LIBR:

. NAME NULL
. ROOT USERWL,COTRWL
.FCTR NULL-*(CALC1-LIBR,CALC2-LIBR)
.FCTR USER-LIB-*(INTWL,CRUNWL)
.FCTR INTRO-LIBR
.FCTR CRUNCH-CHATR-LIBR
.FCTR LIB1-LIBR
. FCTR LB:BP20TS/LB:$ICINI:$ICWRT:$ECONV:$ICFNS:$STFN1
.FCTR LB:BP20TS/LB
.END

In general, you can specify up to eight routines as modifiers to one LB switch.
Calling this file OVER3 .0DL, the build process is:
RUN $TKB
TKB> TRY3,TRY3=OVER3/MP
ENTER OPTIONS:
TKB> UNITS=12
TKB>ASG=SY:5:6:7:8:9:10:11:12
TKB>EXTTSK=512
TKB> //

The build proceeds without error. The first page of the map file TRY3.MAP is
shown in Example 4-3. As shown, the total amount of virtual address space
taken by the program is 6400 words, smaller than the first build without co-trees,
which took 6528 words. And, as can be determined by typing RUN TRY3.TSK,
the program runs.
Example 4-3:

First Page of Map File for Third Build of Sample Program

Memory allocation map TKB 08.006
15-MAY-9 0
15:24

TRY3.TSK

Partition name
GEN
Identification
000708
Task UIC
[1,196]
Stack
limits: 001000 001777 001000 00512.
PRG xfr address: 022252
Total address windows: 1.
Task extension
512. words
Task image size
6400. words
Total task size
6912. words
Task address limits: 000000 030773
R-W disk blk limits: 000002 000037 000036 00030.
TRY3.TSK Overlay description:

4-16

Base

Top

000000
025254
025254
030514
030514
030514

025253
030513
026603
030513
030773
030763

Length

------

025254
003240
001330
000000
000260
000250

Co-Trees: Another Way to Save Space

10924.
01696 .
00728.
00000.
00176.
00168.

USER
INTRO
CRUNCH
NULL
CALC 1
CALC2

Page 1

4.4.7

Further Tips
The example program discussed in the previous sections is a simple one. For
a complex program having many overlays in many co-trees, some of the steps
described above are harder to follow; it may be very tedious to write down all the
routine names in the diagnostic error messages resulting from a "first-try" co-tree
build.
One way to get around this problem is to eliminate all library references in your
preliminary build. The routines and symbols will then show up on the map file
listing as "undefined symbols," and you can work from there.

4.4.8

Using Co-Tree Techniques with the Default Library
You can use the techniques discussed in this chapter for default library routines.
However, you must be even more careful than you were with the language
libraries. Routines in the default library were coded in the MACRO assembly
language using expert manipulation of program sections (see Chapter 6). For
example, a routine may use a data section that can be overlaid in low virtual
address space while instruction sections are built into separate paths of the tree.
Unless you are a MACRO programmer, aware of these program sections and
capable of dealing with them, you should not try overlaying routines from the
default library.
If you do want to try it, you will find the !MA and IFU switches useful. These

switches are described in detail in Chapter 11.
Briefly, the fMA switch appended to the map file specification calls for more detail
in the listing on routines built into the program from the default library.
Appending the IFU switch to the executable program file (default extension .TSK)
tells the Task Builder to make a "full search" during its second pass to resolve
undefined symbols from the default library. Suppose, for example, that the Task
Builder builds a definition from the default library into one path on the main tree
to resolve an undefined symbol. If this symbol is referred to from a path on a
co-tree and the IFU switch has been used, the Task Builder resolves the reference
in the co-tree with the definition in the main tree.
Note that if the symbol were referred to in more than one path on more than
one tree, the Task Builder proceeds as it does when it searches through library
references specified with a general-purpose ILB switch. That is, it builds the
piece into all paths on all trees and flags the symbols as multiply or ambiguously
defined. You can specify where you want individual program sections by using
the Task Builder's .PSECT command (Chapter 6).
Again, you should not try to overlay pieces from the default library unless you
are experienced in MACRO and can determine that cross-tree calls will not
inadvertently displace portions of the overlay structure.

Co-Trees: Another Way to Save Space

4-17

Chapter 5

The Autoload Indicator

Now that you understand the rules for specifying an overlay structure, it is
necessary to better understand the autoload indicator (*). The asterisk tells the
Task Builder to generate what are called "autoload vectors" for pieces of your
overlaid program. Autoload vectors are necessary for the pieces to be loaded
properly. As mentioned in Section 3.2.1, the easiest way to use the autoload
indicator is to put an asterisk (*) before the outermost parenthesis of the main
tree and call co-trees, and before any non-null co-tree roots (Figure 5-1).
This chapter tells what is happening when you use the autoload indicator, and
why. It also explains how you can save a small amount of space in your program
by using autoload indicators judiciously.
Figure 5-1:

The Easiest Way to Use Autoload Indicators

FOR A SINGLE TREE STRUCTURE:
.ROOT A-*(A1,A2,A3-(A31,A32))

'(BEFORE THE OUTERMOST PARENTHESIS)

FOR A CO-TREE STRUCTURE:
.ROOT MAIN, COTRE1, COTRE2
.FCTR A-~,A2,A3,)
.NAME NULL
(BEFORE OUTERMOST LEFT
COTRE1 : .FCTR NULL-!(B1 ,B2) PARENTHESIS IN MAIN TREE
COTRE2: .FCTR *C-\(C1 ,C2-(C21 ,C22)) AND EACH CO-TREE)
:

(BEFORE A NON-NULL CO-TREE ROOT)
.END
MK-{)0588-00

5.1

What are Autoload Vectors?
When overlays are not requested, the Task Builder resolves references to symbols
in transfer-of-control statements by figuring out the location (address) where the
symbol will reside when the program is executing. The Task Builder then puts
The Autoload Indicator 5-1

this address in the transfer-of-control instruction. For example, consider the
simple build:
RUN $TKB
TKB> OBJ=MAIN,SUB1,LB:F4POTS/LB
TKB> //

As described in Chapter 3, the Task Builder concatenates MAIN and SUBl and
resolves undefined references by concatenating modules from the library. When
MAIN calls SUBl, the Task Builder resolves the reference by substituting the
address it has calculated for the entry point for SUBl.
With overlays, the Task Builder does not assume that such direct substitutions
will work. When a call is made to a piece further away from the root, there is no
guarantee that the piece referenced will be in memory when the call is executed.
So, you must tell the Task Builder to generate autoload vectors for global symbols
outside the root that are referenced in transfer-of-control statements by a piece
closer to the root. And, where such a reference is made to a global symbol, the
Task Builder will then substitute the address of the autoload vector instead of the
direct address reference.
The generated autoload vectors are stored in every piece of your program that
calls another piece further away from the root. The general form of an autoload
vector is the four-word structure shown in Figure 5-2.
Figure 5-2 : The Four-Word Structure of a Vector Autoload

Autoload Vector Entry

JSR @PC+2
Offset to pointer to autoload code
Segment descriptor address
Entry point address

MK-01055-00

The JSR instruction passes control to the autoload processor, $AUTO. These two
words are followed by the address of the descriptor for the segment to be loaded
as well as the direct address calculated for the entry point of the piece to be
loaded, if necessary.
Thus, when your program executes a call to a piece of your program further
away from the root, control transfers to the autoload vector address and on to the
autoload routine (inserted as a part of your program by the Task Builder). The
autoload routine checks to see if the piece referred to is already in memory. If so,
control is transferred to the location where the called routine resides, that is, to
the entry point specified in the last word of the autoload vector.
If the desired piece is not currently in memory, the autoload routine loads the

piece from disk (using information from the segment descriptor pointed to by the
third word of the autoload vector). Once the appropriate piece is loaded, control
is transferred to the entry point specified in the last word of the autoload vector.

5-2

The Autoload Indicator

5.2 Where are Autoload Vectors Really Needed?
You can request autoload vectors for all the pieces of your program, if you want
to. If you use the easiest rule (described on the first page of this chapter) each
global symbol referred to in a transfer-of-control statement closer to the root will
have an autoload vector. But autoload vectors are only necessary when a transfer
of control is made to a piece that is not currently in memory, so that it can be
properly loaded. You can save four words for each unnecessary autoload vector
you eliminate by using the autoload indicator only where it is really needed.
1b understand how to request specific autoload vectors, you must understand how
the Task Builder has stored the pieces of your program on disk, and how and
when the appropriate pieces are loaded. This was discussed in Section 3.5.2; that
information is reviewed here with a more complex example.
When you request overlays, the Task Builder constructs your executable program
file such that pieces will be loaded in the most efficient manner. It does this by
analyzing your ODL file. Pieces connected by a hyphen (-) are stored such that
they will be loaded in one disk access. Pieces separated by a comma are stored
such that they require a separate disk access for each piece.
For example, consider the overlay structure in Figure 5-3.
Figure 5-3:

An Overlay Structure Without Autoload Vectors

eNTRl

81
82

83
84

A21

A22
MK-00589-00

This structure can be represented (including the FORTRAN library F4POTS.OLB)
by the following ODL file. Note that only the structure is shown-no autoload
vectors for the moment, although they will be needed .
AFCTR:
BFCTR:
AOWLIB:
AIWLIB:
A2WLIB:
A21WLB:
A22WLB:
LIBR:

. ROOT CNTRL-LIBR-(AFCTR,BFCTR)
.FCTR AOWLIB-(AIWLIB,A2WLIB-(A21WLB,A22WLIB)
.FCTR BI-B2-B3-B4-B5-LIBR
.FCTR AO-LIBR
.FCTR AI-LIBR
.FCTR A2-LIBR
.FCTR AI-LIBR
.FCTR A22-LIBR
.FCTR LB:F4POTS/LB
. END

The Autoload Indicator 5-3

Ignoring the factors needed to include the FORTRAN library, note that Bl
through B5 are connected by hyphens. Hence, they are stored on disk as one
segment. Suppose that the root, CNTRL, contains a call to B3. As long as an
autoload vector has been generated for B3, it and Bl, B2, B4, and B5 are loaded
when the call is made, since these pieces have been stored as one segment on
disk.
Once they are all loaded, B3 can call Bl, B2, B4 and/or B5 using direct references
(without autoload vectors). Likewise, they can all call each other using direct
address references. The only piece you must request an autoload vector for is
B3; you could have eliminated autoload vectors for Bl, B2, B4, and B5. (Or, if
CNTRL had called B5 first, you need have requested autoload vectors only for
B5-the call sequence is as important a consideration as the fact that the items
are connected by hyphens.)
For items separated by commas, the loading sequence is different. The Task
Builder stores items separated by commas in separate segments on disk. At
execute time, a reference to a piece "further out" (away from the root of the tree)
causes all pieces between the calling piece and the called piece to be loaded.
Suppose that in the above example, CNTRL calls A21. Assuming that an autoload
vector exists for the reference to A21, the pieces AO and A2 are loaded along with
A21. At this point, any routine in that path can call any other routine using a
direct reference. That is, CNTRL could call AO, A2, or A21; A21 could call A2 or
AO. A2 could call A21 or AO, and AO could call A2 or A21 using direct references.
So, as long as A21 is called first, it is the only piece along that path that needs
an indirect reference, an autoload vector, to ensure that it is loaded when a piece
closer to the root calls it.
Suppose, on the other hand, that CNTRL calls AO first. Only AO is loaded when
that particular call is made. AO needs an autoload vector. If AO then called A22,
A22 would also need an autoload vector. However, at that point, A2 and A22 will
be loaded into memory. CNTRL could call AO, A2, and A22; A22 could call A2, A2
could call AO, and AO could call A2 and A22 using direct references. No autoload
vector is necessary for A2 in this case.

5.3 How to Request Specific Autoload Vectors
You request autoload vectors for a specific piece of the overlay by using an
asterisk (*) in your ODL commands. For example, the following command causes
autoload vectors to be generated for global symbols in A and C that are referred
to in transfer-of-control statements from segments closer to the root. No autoload
vectors are generated for such global symbols in B, however. (No autoload vectors
are necessary for CNTRL since it is loaded by the run-time system when the
program is first executed.)
.ROOT CNTRL-(*A,B-*C)

You can put the asterisk before any item in an ODL .ROOT or .FCTR command.

5.3.1

Asterisk Before File Names and Program Sections
If you put an asterisk before a file name or a program section name with the I
(instruction) attribute t , an autoload vector is generated for each global symbol
in the file or section (such as an entry point) referred to in a transfer-of-control
statement from another piece closer to the root.

t Program sections are units processed by the Task Builder; they are described in Chapter 6.
5-4 The Autoload Indicator

5.3.2

Asterisk Before Items in Parentheses
If you put an asterisk before items enclosed in parentheses, autoload vectors are

generated for each item within the parentheses.
For example:
BRNCH1: .FCTR A-*(B,C,D)

Autoload vectors are generated for B, C, and D.

5.3.3

Asterisk Before Names Defined in .FCTR Commands
If you put an asterisk before a name later defined in a .FCTR command, an
autoload vector is generated for the first item in the .FCTR command. If the first
item in the .FCTR command is preceded by a left parenthesis, all items within
the parentheses in the .FCTR command will have autoload vectors, as long as
they are referred to in transfer-of-control statements from pieces closer to the
root.
For example:
AFCTR:
BFCTR:

.ROOT MAIN-(*AFCTR,*BFCTR)
.FCTR AO-ASUB1-ASUB2
.FCTR (BO-(Bl,B2»
.END

Autoload vectors are generated for AO, BO, Bl, and B2, as long as they are
referred to in transfer-of-control statements from pieces closer to the root.
Autoload vectors are not generated for ASUBI and ASUB2.

5.3.4

Asterisk Before Names Defined in .NAME Command
As mentioned in Section 4.2, the .NAME command assigns a name to a piece
of the overlay structure. The piece, as it turns out, is the "segment" defined
immediately following the name when the name is used in a .ROOT or .FCTR
command. (Remember that a segment was defined as loadable with one disk
access. See Section 3.5.2.)
For example, consider the following (unlikely) ODL file:

BFCTR:
CFCTR:

.NAME
.NAME
.NAME
. ROOT
.FCTR
.FCTR
.END

WE CAN
ONLY
WONDER
CNTRL-(WECAN-(A,B),BFCTR,CFCTR)
*ONLY-BO-Bl-B2-B3
Cl-(*WONDER-C2-(C3,C4»

The name WECAN applies to a null segment; this is how the .NAME command
would be used to define a null root for a co-tree, as described in Section 4.2.
There is no reason to generate an autoload vector for a null segment.
The name ONLY applies to the segment formed by the pieces BO, Bl, B2, and B3.
Hence, the asterisk before ONLY means that autoload vectors are generated for
each of these pieces.
The name WONDER applies to the segment formed by C2. Hence, the asterisk
before WONDER means that autoload vectors are generated for C2.

The Autoload Indicator 5-5

5.4 Example of Specific Autoload Vector Requests
Now that you understand how autoload indicators apply to the various element.s
possible in an OOL file, return to the specific example in Figure 5-3 and the OOL
file following it.
Suppose that CNTRL calls B3, which makes various calls to BI, B2, B4, and B5
before it returns control. CNTRL then calls A21, which calls A2 and AO. Control
returns to A21, which returns control to CNTRL. CNTRL then calls Al and A22.
Thus, you need apply the autoload indicator only to B3 in the "B" branch of the
structure. In the "A" branches, you must supply an autoload indicator for A21,
AI, and A22. You can accomplish this with the following OOL file:
AFCTR:
BFCTR:
AOWLIB:
A1WLIB:
A2WLIB:
A21WLB:
A22WLB:
LIBR:

.ROOT CNTRL-LIBR-(AFCTR,BFCTR)
.FCTR AOWLIB-(A1WLIB,A2WLIB-(A21WLB,A22WLIB)
.FCTR Bl-B2-*B3-B4-B5-LIBR
.FCTR AO-LIBR
.FCTR *Al-LIBR
.FCTR A2-LIBR
.FCTR *A21-LIBR
.FCTR *A22-LIBR
.FCTR LB:F4POTS/LB

. END

5.5 If You Make a Mistake
If you make an error in placing asterisks, you will have problems within your
program. Suppose you leave out an asterisk so that an autoload vector is not
generated for a piece of your program. That piece will then be called with a direct
reference, and if it is not actually in memory, control passes to whatever happens
to be there. The Task Builder cannot diagnose the error at build time, because it
does not attempt to analyze the sequence of calls in your program.
So, be very careful in requesting that the Task Builder generate autoload vectors
for only some of the pieces making up your program.

5-6 The Autoload Indicator

Chapter 6

Working with Program Sections
So far, overlay techniques have been discussed in terms of units you are
familiar with: files consisting of separately compiled or assembled programs
or subprograms, or of library files. This chapter discusses the units these files
consist of-the units the Task Builder actually works with-program sections.

6.1

What is a Program Section?
All the language translators produce program sections. With MACRO, you work
directly with program sections. The .PSECT directive of the MACRO language
lets you name and define exactly what goes into these units. With the higherlevel languages, the compiler handles most aspects of generating and assigning
attributes to program sections for you (Figure 6--1).
Figure 6-1:

The Task Builder Works with Program Sections

MK-D0590-00

The Task Builder allocates space differently for different parts of a program
or subprogram, depending on certain attributes. With program sections, you
can take full advantage of these attributes. A case where you would need program sections involves common areas, a programming feature of all languages.
Working with Program Sections

6-1

(COBOL programmers will recognize common areas as the LINKAGE SECTION
of the DATA DIVISION in their program or subprogram.)
Common areas are areas in memory that are shared between programs and
subprograms. A program can place data in a common area and pass control
to another program or subprogram that uses the data in the common area for
processing. Thus, one of the most obvious attributes of a program section is
whether or not it consists of instructions or data.
Another attribute inherent in common areas is that the space allocated in both
the program and subprogram should be overlaid, rather than concatenated. For
example, suppose two FORTRAN programs define a common area named A.
In each compilation, the compiler defines a program section named A with the
"overlay" attribute. The Task Builder, when requested to build an executable
program file from the two object files, can allocate one area of memory to A.
It can resolve references to A such that both programs refer to the same area.
(Note the word "can." Whether the Task Builder actually uses the same area or
not depends upon whether the two definitions reside along the same path of the
overlay structure, as described in Section 6.2.)
This illustrates yet another attribute of a program section: whether it is local
or global. The compiler defines common areas as global; that is, they can be
referred to by other separately compiled programs or subprograms. (MACRO
programmers, again, state the attributes of program sections directly.) That is,
global program section names can be referred to by other, separately compiled,
programs or subprograms.
A program section has two other attributes: (1) whether it can be accessed
read/write or read-only, and (2) whether its address is absolute or relocatable.
See the PDP-ll MACRO-ll Language Reference Manual if you are interested in
further detail about program section attributes.

6.2 Allocating Space for Global Program Sections
As mentioned in Section 6.1, one of the attributes of a program section is whether
it is local or global. The Task Builder must determine where to allocate space for
global program sections. If a FORTRAN program and subprogram both define a
common area A, for example, where is the space for A to be allocated?
Figure 6-2 shows two examples. The common block COMA is defined in the
pieces A2 and A21. The Task Builder allocates the space for COMA in A2
because that segment is closer to the root. The common block COMB, however,
is defined in AO and BO. These pieces are not on the same path, so the Task
Builder allocates space for COMB in both AO and BO. Note that AO and BO
cannot communicate through COMB. When the overlay containing BO is loaded,
for example, any data stored in COMB by AO is lost.

6-2

Working with Program Sections

Figure 6-2:

Allocating Space for Global Program Sections

ROOT

I
I

AO
DEF COMB
'

""""""

.....-----,.

A1
,

BO
DEF COMB

A2
DEF COMA

SPACE FOR COMB ALLOCATED IN
BOTH AO AND BO BECAUSE THEY
ARE ON DIFFERENT PATHS
'

:"""""1"""'''':'\

SPACE FOR COMA ALLOCATED
IN A2 BECAUSE IT IS CLOSER
TO THE ROOT

A21
DEF COMA

A22

MK-00591-00

6.3 How the Task Builder Orders Program Sections
As discussed in Chapter 3, the Task Builder creates the executable file in
segments such that each segment is loaded with one disk access. It also orders
program sections within each segment.
The Task Builder groups the program sections according to access code.
Read/write program sections are assigned the lower addresses; read-only
program sections follow in higher-address space. Within these groups, program
sections are ordered alphabetically. The higher-level language translators are
designed to create names for program sections to take advantage of this feature
of the Task Builder. (If you are programming in MACRO and for some reason
do not want alphabetic ordering of program sections, you can use the /SQ switch
(Section 11.25) to request sequential ordering of program sections.)
As an example, suppose that the Task Builder is working with a segment
consisting of three pieces named IN1, IN2, and IN3, specified in the ODL file as
follows:
FCTR1:

.FCTR IN1-IN2-IN3

Working with Program Sections 6-3

Table 6-1 shows the program sections each file contains and their access codes
and allocation codes.
Table 6-1:

Program Sections for IN1, IN2, AND IN3

FileName

Program
Section
Name

IN1

B
A

IN2

A
B

IN3

Access
Code

Allocation
Code

Size (octal)

RW
RW
RO
RW
RW
RO

CON
OVR
CON
OVR
CON
CON

100
300
150
250
120
50

The Task Builder first determines the amount of space to allocate for each
program section. Program section A appears in two files and has the overlay
(OVR) attribute. The OVR attribute causes the Task Builder to allocate the
largest of the two sizes, or 300 bytes, for A. Program section B appears twice and
has the concatenate (CON) attribute. Thus, the total allocation for B is the sum
of the lengths of each occurrence, or 220 bytes. The portion allocated for IN1 (100
bytes) is assigned the lowest addresses, since it appears first in the input file list.
Program section C appears twice and, since it has the concatenate attribute, is
allocated 200 bytes.
The Task Builder then groups the program sections according to their access
codes, with the read/write sections being allocated the lowest addresses, followed
by the read-only sections (see Figure 6-3).
Figure 6-3:

Allocation of Program Sections for IN1, IN2, and IN3

A (300)

Read/write

B (220)

Read/write
Read-only

C (200)

MK-00592-00

The only other factor contributing to how the Task Builder allocates and orders
program sections is whether the section consists of instructions or data. The Task
Builder always allocates address space for a program section beginning on a word
boundary. If the program section has the instruction (I) and concatenate (CON)
attributes, the Task Builder appends the space so that each piece begins on a
word boundary. (This eliminates the possibility of an odd-address transfer.) If the
program section has the data (D) and concatenate (CON) attributes, however, and
the space contributed by a piece ends on a byte rather than a word boundary, the
space for the next piece is appended starting with the next byte.
6-4 Working with Program Sections

6.4 The Task Builder's .PSECT Command
You can direct the placement of program sections at build time with the .PSECT
command. Suppose, for example, that you wanted to place the common block
COMB from the example in Figure 6-2 in the root section of the program. This
would make the area accessible from both AO and BO; they would be able to
pass data in the common area, as desired. This could be accomplished with the
following ODL commands:
.PSECT
. ROOT

COMB,RW,GBL,REL,OVR,D
ROOT-COMB-LIBR-*(AOWL-*(AIWL,A2WL-*(AIWL,A22WL»)

.END

In the .PSECT command, you specify the program section name first, followed by
its attributes in any order. The attributes shown here are typical for a common
block: read/write (RW), global (GBL), relocatable (REL), overlaid (OVR), and data
(D).

6.5 Using .NAME to Make a Data PSECT Autoloadable
You can construct an object file consisting only of data and make that file
autoloadable. For example, suppose that, using MACRO, you constructed a file
consisting of a program section containing error messages. Suppose further
that you wanted to overlay this file, because it was needed only when a certain
subprogram was running. Such overlaying can be accomplished, and is perhaps
best explained by example.
Consider the subprogram ERDAT.OBJ, which processes an error value. If the
value is 0, the subprogram calls a routine named ALRIT.OBJ. If the value is not
0, however, it displays one of the error messages contained in the file MSG.OBJ,
consisting of a program section with the D attribute, using, say, the MACRO
language .ASCII command to define each particular error message.
There is no reason why ALRIT and MSG must be in memory at the same time.
You can overlay ALRIT and MSG, by using the .NAME directive to define a name
and attributes for the file MSG. For example:

MSGF:

.ROOT
.NAME
.FCTR
. END

MAIN-*(OTHER,ERMSG-(ALRIT,MSG»
MESAGE,GBL
MESAGE-MSG

That is, you must include a .NAME command defining a global name (MESAGE
in this case) for the data file (MSG in this case). The Task Builder generates
the global symbol MESAGE and enters it into the symbol table for segment
MESAGE. Since this segment is included for the generation of autoload vectors,
an autoload vector is created for the segment referred to by the global symbol
MESAGE. Because it consists only of a program section with the data (D)
attribute, however, the Task Builder constructs a special autoload vector. The
last word, normally an "entry point address" for an autoloaded segment, instead
refers to the symbol $$RTS (generated by the Task Builder, and containing a
simple return instruction).

Working with Program Sections 6-5

So, program ERMSG includes a CALL ME SAGE statement or JSR PC,MESAGE
instruction to load the error message file MSG. At execution time, the CALL or
JSR would transfer control to the autoload vector, which would call the $AUTO
routine to load the necessary segment, if necessary, and then transfer control
inline (back to the statement or instruction in ERMSG following the CALL or
JSR).
In short, to make a data segment autoloadable:

1. Use a .NAME command with the GBL attribute to define a global name for
the segment.
2. Make sure that an autoload vector is generated for the segment by using the
autoload indicator as appropriate.
3. Load the segment by using a control instruction, such as CALL or JSR,
referencing the name defined in the .NAME command.
Section 13.4 describes the .NAME command in detail.

6.6 More About Program Sections: Deciphering the Map
The first time you look at a memory map file, particularly if you use one of the
higher-level languages, you may wonder "What has happened to my program?"
The listing for even a small program is lengthy, and contains symbols that you
never saw before.
The Task Builder presents a rather dazzling array of information in the memory
map. You have seen parts of a map file in previous chapters dealing with
overlays. Now that you understand what program sections are, and how the Task
Builder orders them, more of the pieces can be fit together.
The following pages show a BASIC-PLUS-2 program consisting of a main program
and three subroutines. (This program is a slight simplification of the one used
to describe co-trees in Chapter 4.) USER simply calls three subroutines; INTRO
accepts user input from the terminal; CRUNCH performs numeric computation;
and CHATR prints the results.
Following the source listing, the ODL file for building the compiled object files
USER.OBJ, INTRO.OBJ, CRUNCH.OBJ, and CHATR.OBJ is shown as a root
segment with three overlaid segments.
Next, you see the map produced from the build. Note that this is a "short" map;
you can request more information and more detail by using the IMA and joSH
switches on the map file name (see Sections 11.14 and 11.23). Section 11.23 gives
a complete description of all the information given in a map file, organized for
easy reference.
We used the /-WI switch to produce the 80-column listing for this manual. If you
use a typical line printer for your map file, you would probably want to produce a
132-column listing (the default).
In this chapter, focus is on the information contained in a map for each segment.
This information is interesting and may be helpful if you are trying to debug
a program at the machine-language level. The Task Builder provides complete
information on the structure of each segment it constructs.
Page 2 of the map, for example, shows the start of the information for the
segment USER (the root segment of the program). Note the memory allocation
synopsis; each program section in the segment USER is listed (under the heading
SECTION), continuing to page 3 of the map.

6-6

Working with Program Sections

The three columns of numbers to the right give the starting address (in octal)
and length (in octal and decimal) of each program section or piece of a program
section in the root. Note that the starting address of the first program section
in the root segment is 2000[8]. The starting address is not 0 (even though you
are dealing with relocatable addresses) because the Task Builder uses the first
2000[8] bytes in your program for some special-purpose information.
The run-time systems that your program can run under use the first 1000[8] bytes
of this space to pass information to the RSTSIE monitor. MACRO programmers
may be interested in this area (described in the RSTS / E System Directives
Manual). Note that programmers in other languages cannot access this area as
easily as MACRO programmers.
Likewise, the second 1000[8] bytes are allocated for what is called the stack. It
is an area that can be used by assembly language programmers to pass values
between programs or subprograms. A value can be "pushed on the stack" by
one program and "popped from the stack" by another. Assembly language and C
language programmers may be interested to know that you can allocate more (or
less) than 1000[8] bytes for the stack by using the stack option, as described in
Section 12.26. Higher-level programmers should not try to save space by reducing
the amount of space taken by the stack; the compiler may well have generated
code in your program to push data on the stack. Trying to decrease the size can
cause unpredictable results when your program is executed. C programmers, on
the other hand, may need to increase the amount of STACK space.

In any case, the first program section listed in segment USER is named ".BLK"this is the name given by the assembler and compilers to what is called the blank
common area. MACRO, FORTRAN, and BASIC programmers may recognize this;
it is simply the area assigned to common areas that you do not define a specific
name for in your program. In this case, no common areas are used, and so the
program section shows a length of 00000. bytes.
Next, the BP20TS section shows the library routines that the Task Builder has
inserted into the root segment from the BP20TS library. The routine names are
listed in the "TITLE" column.
The program sections whose names begin with $ have been generated by the
compiler. They contain the code and data generated by the compilation of the
source files. It is interesting to note, for example, that the program section named
$CODE is the only program section with the instruction (I) attribute. Logically
enough, this is the name that the compiler gives to the machine instructions it
generates from the source code, in this case for the USER program. If you look on
following pages, you see this same $CODE section appearing in all the segments,
and can begin to understand how the compilers have been designed to generate
names to take advantage of the Task Builder's alphabetic ordering of program
sections.
The program sections whose names begin with $$ have either been generated
by the Task Builder itself or are routines supplied from the default library
SYSLIB.OLB. For example, $$ALVC is the name of the program section
containing the autoload vectors for each segment. (Appendix D lists this and
other symbols reserved for use by the Task Builder.) Likewise, $$AUTO is the
autoloading code needed to load overlay segments outside the root. It is supplied
from the default library. The PSECT $$RTS is another example. This is the
return instruction, mentioned in Section 6.5, which can be used to load a data
segment.

Working with Program Sections 6-7

Following this listing of program sections and their memory allocations is a list
of global symbols defined or used in each segment. Note that the only global
symbols recognizable from the source program are USER, INTRO, CRUNCH, and
CHATR, assigned to the entry point of each routine by the compiler. The rest
have been assigned by the compiler, or belong to the library routines that have
been inserted into the segment.
The last page of the listing contains Task Builder statistics on the build. These
statistics are mainly useful in analyzing Task Builder performance on your
system, as described in Appendix E.

6.6.1

Source for Program USER
10
20
30
40

6.6.2

Source for Subprogram INTRO
10
20
30

6.6.3

SUB CHATR(AC%,BC%,CA%,CB%,CC%)
PRINT "THE SUM OF ";AC%;" AND ";BC%;" IS ";CA%
PRINT "THE PRODUCT OF ";AC%;" AND ";BC%;" IS ";CB%
PRINT "THE DIFFERENCE OF ";AC%;" AND ";BC%;" IS ";CC%
SUBEND

Overlay Description File FRED.ODL
USWL:
INTRWL:
CRUNWL:
CHATWL:
LIBR:

6-8

SUB CRUNCH(AB%,BB%,CA%,CB%,CC%)
CA%
AB% + BB%
CB% = AB% * BB%
CC% = AB% - BB%
SUBEND

Source for Subprogram CHATR
10
20
30
40
50

6.6.5

SUB INTRO(AA%,BA%)
INPUT "INPUT TWO NUMBERS";AA%,BA%
SUBEND

Source for Subprogram CRUNCH
10
20
30
40
50

6.6.4

CALL INTRO(A1%,B1%)
CALL CRUNCH(A1%,B1%,SUMM%,PRODUCT%,DIFFER%)
CALL CHATR(A1%,B1%,SUMM%,PRODUCT%,DIFFER%)
END

.ROOT USWL-*(INTRWL,CRUNWL,CHATWL)
.FCTR USER-LIBR
.FCTR INTRO-LIBR
.FCTR CRUNCH-LIBR
.FCTR CHATR-LIBR
.FCTR LB:BP20TS/LB
.END

Working with Program Sections

6.6.6

Task Builder Command File
USER,USER=FRED/MP
UNITS=12
ASG=SY:5:6:7:8:9:10:11:12
EXTTSK=512

6.6.7

Task Builder Listing

USER.TSK

Memory allocation map TKB 08.006
15-MAY-90
14:00

Page 1

Partition name
GEN
Identification
000708
Task UIC
[30,21]
limits: 001000 001777 001000 00512.
Stack
PRG xfr address: 016030
Total address windows: 1.
Task
extension
512. words
Task image size
6304. words
Total task size
6816. Words
Task address limits: 000000 030453
R-W disk blk limits: 000002 000041 000040 00032.

USER.TSK Overlay description:
Base

Top

000000
020774
020774
020774

020773
030453
021427
026023

USER.TSK
USER

Length

------

020774
007460
000434
005030

08700.
03888.
00284.
02584.

USER
INTRO
CRUNCH
CHATR

Memory allocation map TKB 08.006
15-MAY-90
14:00

Page 2

*** Root segment: USER
R/w mem limits: 000000 020773 020774 08700.
Disk blk limits: 000002 000022 000021 00017.

Working with Program Sections 6-9

Memory allocation synopsis:
Section

Title

------• BLK.: (RW,I,LCL,REL,CON)
BP20TS: (RO,I,LCL,REL,CON)

$ARRAY: (RW, D, LCL,REL, CON)
$CODE : (RO,I,LCL,REL,CON)
$FLAGR: (RW,D,GBL,REL,CON)
$FLAGS: (RW,D,GBL,REL,CON)
$FLAGS: (RW,D,GBL,REL,CON)
$ICIOO: (RW,D,GBL,REL,OVR)

6-10

002000 000000 00000.
002000 014030 06168.
002000 000352 00234.
002352 000026 00022.
002400 000460 00304.
003060 000132 00090.
003212 000746 00486.
004160 001114 00588.
005274 000000 00000.
005274 001554 00876.
007050 000450 00296.
007520 001102 00578.
010622 000022 00018.
010644 002156 01134.
013022 000162 00114.
013204 000374 00252.
013600 000260 00176.
014060 000062 00050.
014142 000222 00146.
014364 000230 00152.
014614 000000 00000.
014614 000114 00076.
014730 000242 00162.
015172 000004 00004.
015176 000070 00056.
015266 000266 00182.
015554 000062 00050.
015636 000034 00028.
015672 000112 00074.
016004 000024 00020.
016030 000000 00000.
016030 000000 00000.
016030 000204 00132.
016030 000204 00132.
016234 000000 00000.
016234 000000 00000.
016234 000010 00008.
016234 000002 00002.
016244 000000 00000.
016244 000000 00000.
016244 000030 00024.
016244 000000 00000.
016244 000030 00024.

Working with Program Sections

Ident

$CALLS 21CM
$ ICEND 07CM
$ERTHR 70CM
$JMOVS 05CM
$IEULT 31RE
$ IVOPN 60RE
$ICIOO 04CM
$BINIT 7lRE
$CNTRL 14CM
$STMSC 25CM
$CALLR 06CM
$ ERROR 76RE
$ ICRCL 16CM
$IMALQ 12CM
$ICFSS 27RE
$ ICCRL OOCM
$STGTA 04CM
$ICEOL 21CM
$BFPEI 06CM
$ERROT 7lRE
RQLCB 69CM
$BFPER 06CM
$PROCT OOCM
$ JCONV 03CM
$ BXTRA 05RE
$BBTKS 01RE
$ICULT 04CM
SAVRG 69CM

File

BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB

USER

000708 USER.OBJ

USER

000708 USER.OBJ

USER

000708 USER.OBJ

USER

000708 USER.OBJ

USER

000708 USER.OBJ

USER
000708 USER.OBJ
$ICIOO 04CM
BP20TS.OLB

USER.TSK
USER

Memory allocation map TKB 08.006
15-MAY-90
14 :00

$ICI01: (RW,D,GBL,REL,OVR)
$IDATA: (RW,D,LCL,REL,CON)
$PDATA: (RO,D,LCL,REL,CON)
$STRNG: (RW,D,LCL,REL,CON)
$TDATA: (RW,D,LCL,REL,CON)
$$ALER: (RO,I,LCL,REL,CON)
$$ALVC: (RO,I,LCL,REL,CON)
$$AUTO: (RO,I,LCL,REL,CON)
$$BP2 : (RW,D,GBL,REL,OVR)
$$MRKS: (RO,I,LCL,REL,OVR)
$$OVDT: (RW,D,LCL,REL,OVR)
$$OVRS: (RW,I,LCL,ABS,CON)
$$PDLS: (RO,I,LCL,REL,OVR)
$$RDSG: (RO,I,LCL,REL,OVR)
$$RESL: (RO,I,LCL,REL,CON)
$$RGDS: (RW,D,LCL,REL,CON)
$$RTQ : (RO, I, GBL,REL, OVR)
$$RTR : (RO,I,GBL,REL,OVR)
$$RTS : (RO,I,GBL,REL,OVR)
$$SGDO: (RW,D,LCL,REL,OVR)
$$SGD1: (RW,D,LCL,REL,CON)
$$SGD2: (RW,D,LCL,REL,OVR)
$$WNDS: (RW,D,LCL,REL,CON)

016274 000200
016274 000200
016474 000012
016474 000012
016506 000000
016506 000000
016506 000000
016506 000000
016506 000000
016506 000000
016506 000024
016532 000030
016562 000142
016724 001440
016724 001440
020364 000076
020462 000024
000000 000000
020506 000002
020510 000144
020654 000034
020710 000000
020710 000000
020710 000000
020710 000002
020712 000000
020712 000060
020772 000002
020774 000000

Page 3

00128.
00128.
00010.
00010.
00000.
00000.
00000.
00000.
00000.
00000.
00020.
00024.
00098.
00800.
00800.
00062.
00020.
00000.
00002.
00100.
00028.
00000.
00000.
00000.
00002.
00000.
00048.
00002.
00000.

USER

000708 USER.OBJ

USER

000708 USER.OBJ

USER

000708 USER.OBJ

USER

000708 USER.OBJ

USER

000708 USER.OBJ

USER

000708 USER.OBJ

Global symbols:
BEQ$
007202-R
BGE$
007212-R
BGT$
007210-R
BLE$
007200-R
BLT$
007222-R
BNE$
007220-R
BRA$
007214-R
CAL$
002000-R
CBR$
010622-R
CHATR 016552-R
CLB$S 003132-R
CLI$A 003142-R
CLI$M 003136-R
CLI$S 003132-R
CRUNCH 016542-R
DPI$
003060-R
END$
002352-R
EOL$
014364-R
ERL$
002562-R
ERN$
002542-R
ERR$
002600-R
USER.TSK
USER

ERT$
002612-R
ERT$X 002626-R
FLN$
002400-R
FPUERR 016272-R
FSS$
014002-R
GSC$
007066-R
GSU$
007050-R
INTRO 016532-R
JMC$
007130-R
LIN$
002400-R
LYN$
002562-R
MAD $
010602-R
MOI$IA 003104-R
MOI$IM 003100-R
MOI$IS 003074-R
MOI$MA 003126-R
MOI$MM 003122-R
MOI$MS 003116-R
MOI$SA 003070-R
MOI$SM 003064-R
MOI$SS 003060-R

MSI$IM 003100-R
NOBRA 007204-R
NOI$A 003204-R
NOI$M 003176-R
NOI$S 003170-R
002646-R
OEA$
002634-R
OEG$
OGB$
002706-R
OGS$
002736-R
ONI$A 003162-R
ONI$M 003154-R
ONI$S 003146-R
RCL$
013022-R
REG$
007164-R
RLI$M 003074-R
RLI$P 003116-R
RSI$M 003116-R
RSI$P 003110-R
002414-R
RSM$
002424-R
RSU$
SBE$
002102-R

Memory allocation map TKB 08.006
15-MAY-90
14: 00

ULK$
003212-R
$ABNEX 011416-R
$AFTS1 010634-R
$ATLIN 012260-R
$ATOI 015266-R
$BALBF 013474-R
$BALMP 013456-R
$BCL
005052-R
$BINPT 003760-R
$BOFS 004220-R
$BOP
004160-R
$BOPX 004176-R
$BOUTP 003342-R
$BREAD 003476-R
$BRTBF 013562-R
$BRTMP 013542-R
$CALFP 004114-R
$CALIN 012246-R
$CCHDL 014644-R
$CCXIT 014726-R
$CHKRL 014060-R
Page 4

Working with Program Sections

6-11

$CLFQB 003720-R
$CLOSR 013034-R
$CLSAL 013164-R
$CLSFQ 004106-R
$CLSHD 013152-R
$CLSTK 010220-R
$CLXRB 003742-R
$CNVIA 015456-R
$DATRC 006626-R
$DATRS 006604-R
$DOIT 012476-R
$DOIT1 012520-R
$ ERROR 014614-R
$ ERRT 1 010660-R
$ERTXT 011532-R
$EXTSP 007666-R
$FLSAL 014426-R
$FLSFR 014436-R
$FLSNL 014454-R
$FLUSH 014464-R
$FPASX 015174-R
USER.TSK
INTRO

$FPHSK 015172-R
$FPUER 014614-R
$FRCER 014634-R
$FSS
004030-R
$FSSCN 013600-R
$FSSCZ 013602-R
$GSACM 013204-R
$GTPTN 007734-R
$GTPTR 010022-R
$GTROM 007520-R
$GTR01 014142-R
$GTR23 014246-R
$GTSTN 007724-R
$GTSTR 010010-R
$ICIOO 016244-R
$ICJMP 015754-R
$ ICJM1 015754-R
$INITM 005274-R
$INITS 002270-R
$INTCM 006432-R
$IOERS 006724-R

$ IOERV 006710-R
$IOTST 004124-R
$MEMPR 014630-R
$MEMP1 011674-R
$MNIUS 010456-R
$MNSUB 010522-R
$MREST 011004-R
$NOREX 011520-R
$ODDAD 014624-R
$ODDA1 011654-R
$ONERG 011126-R
$OTSVA 016724-R
$POMSK 007440-R
$PROCT 015176-R
$POMSK 007242-R
$PSMS2 007234-R
$PSMS3 007226-R
$RELCB 014730-R
$REQCB 015032-R
$RSU2 010644-R
$SAVRE 016004-R

Memory allocation map TKB 08.006
15-MAY-90
14:00

$SETSC 006236-R
$SPEC 003224-R
$STCRE 010116-R
$STCRX 010122-R
$STMOV 010150-R
$STMVX 010162-R
$SYSHD 011274-R
$VALDC 015710-R
$ VAL ID 015672-R
$VREAD 003252-R
$XWRT 004002-R
$$MAXC 000017
· .B2TK 015640-R
· .CRLF 015576-R
015574-R
• .PMD
· .PTXT 015602-R
· .RSTT 015554-R
· .SVFQ 004136-R

Page 5

*** Segment: INTRO
R/W mem limits: 020774 030453 007460 03888.
Disk blk limits: 000023 000032 000010 00008.
Memory allocation synopsis:
Section
. BLK.: (RW,I,LCL,REL,CON)
BP20TS: (RO,I,LCL,REL,CON)

$ARRAY: (RW,D,LCL,REL,CON)
$CODE : (RO,I,LCL,REL,CON)
$FLAGR: (RW,D,GBL,REL,CON)
$FLAGS: (RW,D,GBL,REL,CON)
$FLAGT: (RW,D, GBL,REL, CON)
$IDATA: (RW,D,LCL,REL,CON)
$PDATA: (RO,D,LCL,REL,CON)
$STRNG: (RW, D, LCL,REL, CON)
$TDATA: (RW, D, LCL,REL, CON)
$$ALVC: (RO,I,LCL,REL,CON)
$$RTS : (RO,I,GBL,REL,OVR)

6-12

Title
020774 000000 00000.
020774 007272 03770.
020774 000422 00274.
021416 002004 01028.
023422 000656 00430.
024300 000642 00418.
025142 002404 01284.
027546 000226 00150.
027774 000202 00130.
030176 000070 00056.
030266 000000 00000.
030266 000000 00000.
030266 000134 00092.
030266 000134 00092.
016234 000000 00000.
016234 000000 00000.
016234 000010 00008.
016236 000002 00002.
016244 000000 00000.
016244 000000 00000.
030422 000004 00004.
030422 000004 00004.
030426 000026 00022.
030426 000026 00022.
030454 000000 00000.
030454 000000 00000.
030454 000000 00000.
030454 000000 00000.
030454 000000 00000.
020710 000002 00002.

Working with Program Sections

Ident

$ICINI 23CM
$ICRED 53CM
$ICWRT 04CM
$STMOS 16CM
$ECONV 24CM
$ICFNS 11RE
$STLSS 08CM
$STFN1 06CM

File

BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB

INTRO

000708 INTRO.OBJ

INTRO

000708 INTRO.OBJ

INTRO

000708 INTRO.OBJ

INTRO

000708 INTRO.OBJ

INTRO

000708 INTRO.OBJ

INTRO

000708 INTRO.OBJ

INTRO

000708 INTRO.OBJ

INTRO

000708 INTRO.OBJ

INTRO

000708 INTRO.OBJ

Global symbols:
ASC$
BUF$
CCP$
CHR$
III$
IIN$
ILI$
ILS$
INTRO

030234-R
027752-R
027630-R
030256-R
021226-R
021120-R
021206-R
021102-R
030266-R

USER.TSK
INTRO

021246-R
021002-R
021416-R
021524-R
021564-R
030022-R
030026-R
030224-R
021064-R

LIT$
021166-R
LMA$1 030070-R
LSS$AA 030000-R
LSS$AM 030020-R
LSS$AP 027774-R
LSS$MA 030050-R
LSS$PA 030044-R
MOS$AA 024556-R
MOS$AM 024502-R

Memory allocation map TKB 08.006
15-MAY-90
14:00

MOS$PS 024330-R
MOS$SA 024554-R
MOS$SM 024444-R
MOS$SP 024374-R
MOS$SS 024360-R
MOS$01 025056-R
MS1$01 024334-R
NMA$l 030172-R
NSS$AA 030136-R
NSS$MA 030162-R
USER.TSK
CRUNCH

IPT$
IRD$
IVF$A
IVI$A
IVS$A
LAM$1
LAM$2
LEN$
LIS$

NSS$PA 030156-R
PVD$SI 023422-R
PVF$SI 023432-R
PVI$SI 023572-R
PVS$AI 023442-R
RCT$
027604-R
RST$
020774-R
SPC$
030176-R
SPC$01 030176-R
STR$
030204-R

STS$
027616-R
TAB$
027546-R
WAT$
027732-R
$ATOD 025142-R
$CRLF 023724-R
$DMAXD 027544-R
$DTOA 026320-R
$DTOAX 026324-R
$FMAXD 027542-R
$FTOA 026252-R

Memory allocation map TKB 08.006
15-MAY-90
14:00

MOS$AP 024516-R
MOS$AS 024300-R
MOS$MA 024622-R
MOS$MM 024756-R
MOS$MP 024716-R
MOS$MS 024340-R
MOS$PA 024626-R
MOS$PM 024510-R
MOS$PP 024712-R
Page 6

$FTOAX 026256-R
$INPTT 022170-R
$ISETP 022034-R
$ I4ER 021504-R
$POS
027646-R
$PRNSP 024060-R
$PRNTL 024076-R
$SETUP 023772-R

Page 7

*** Segment: CRUNCH
R/W mem limits: 020774 021427 000434 00284.
Disk blk limits: 000033 000033 000001 00001.
Memory allocation synopsis:
Section

Title

-------

BLK.: (RW,I,LCL,REL,CON)
BP20TS: (RO,I,LCL,REL,CON)

$ARRAY: (RW,n, LCL, REL, CON)
$CODE : (RO,I,LCL,REL,CON)
$FLAGR: (RW,D, GBL,REL, CON)
$FLAGS: (RW,D,GBL,REL,CON)
$FLAGT: (RW,D,GBL,REL,CON)
$IDATA: (RW,D,LCL, REL, CON)
$PDATA: (RO,D,LCL,REL,CON)
$STRNG: (RW,D, LCL,REL, CON)
$TDATA: (RW,D,LCL,REL,CON)
$$ALVC: (RO,I,LCL,REL,CON)
$$RTS : (RO,I,GBL,REL,OVR)

020774 000000 00000.
020774 000234 00156.
020774 000046 00038.
021042 000074 00060.
021136 000024 00020
021162 000046 00038.
021230 000000 00000.
021230 000000 00000.
021230 000154 00108.
021230 000154 00108.
016234 000000 00000.
016234 000000 00000.
016234 000010 00008.
016240 000002 00002.
016244 000000 00000.
016244 000000 00000.
021404 000012 00010.
021404 000012 00010.
021416 000012 00010.
021416 000012 00010.
021430 000000 00000.
021430 000000 00000.
021430 000000 00000.
021430 000000 00000.
021430 000000 00000.
020710 000002 00002.

Ident

$JPADD 01CM
$JPMOV 02CM
$JMUL 01CM
$JPSUB 01CM

File

BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB

CRUNCH 000802 CRUNCH.OBJ
CRUNCH 000802 CRUNCH.OBJ
CRUNCH 000802 CRUNCH.OBJ
CRUNCH 000802 CRUNCH.OBJ
CRUNCH 000802 CRUNCH.OBJ
CRUNCH 000802 CRUNCH.OBJ
CRUNCH 000802 CRUNCH.OBJ
CRUNCH 000802 CRUNCH.OBJ
CRUNCH 000802 CRUNCH.OBJ

Working with Program Sections

6-13

Global symbols:
ADI$IP 020774-R
ADI$MP 021010-R
ADI$PA 021034-R
ADI$PM 021026-R
ADI$PP 021004-R
ADI$PS 021020-R
ADI$SP 020776-R
CLI$P 021130-R
USER.TSK
CHATR

CRUNCH 021230-R
MOI$IP 021042-R
MOI$MP 021056-R
MOI$PA 021074-R
MOI$PM 021102-R
MOI$PP 021052-R
MOI$PS 021066-R
MOI$SP 021044-R

MUI$IS
MUI$MS
MUI$PS
MUI$SS
NOI$P
ONI$P
SUI$IP
SUI$MP

021150-R
021144-R
021136-R
021152-R
021120-R
021110-R
021162-R
021176-R

Memory allocation map TKB 08.006
15-MAY-90
14:00

SUI$PA 021222-R
SUI$PM 021214-R
SUI$PP 021172-R
SUI$PS 021206-R
SUI$SP 021164-R

Page 8

*** Segment: CHATR
R/W mem limits: 020774 026023 005030 02584.
Disk blk limits: 000034 000041 000006 00006.
Memory allocation synopsis:
Section

Title

• BLK.: (RW,I,LCL,REL,CON)
BP20TS: (RO,I,LCL,REL,CON)

$ARRAY: (RW,D,LCL,REL,CON)
$CODE : (RO,I,LCL,REL,CON)
$FLAGR: (RW,D,GBL,REL,CON)
$FLAGS: (RW,D,GBL,REL,CON)
$FLAGT: (RW,D,GBL,REL,CON)
$IDATA: (RW,D,LCL,REL,CON)
$PDATA: (RO,D,LCL,REL,CON)
$STRNG: (RW,D,LCL,REL,CON)
$TDATA: (RW,D,LCL,REL,CON)
$$ALVC: (RO,I,LCL,REL,CON)
$$RTS : (RO,I,GBL,REL,OVR)

020774 000000 00000.
020774 004316 02254.
020774 000422 00274.
021416 000074 00060.
021512 000656 00430.
022370 002404 01284.
024774 000226 00150.
025222 000070 00056.
025312 000000 00000.
025312 000000 00000.
025312 000352 00234.
025312 000352 00234.
016234 000000 00000.
016234 000000 00000.
016234 000010 00008.
016242 000002 00002.
016244 000000 00000.
016244 000000 00000.
025664 000012 00010.
025664 000012 00010.
025676 000126 00086.
025676 000126 00086.
026024 000000 00000.
026024 000000 00000.
026024 000000 00000.
026024 000000 00000.
026024 000000 00000.
020710 000002 00002.

Ident

$ICINI 23CM
$JPMOV 02CM
$ICWRT 04CM
$ECONV 24CM
$ICFNS 11RE
$STFN1 06CM

File

BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB
BP20TS.OLB

CHATR

000802 CHATR.OBJ

CHATR

000802 CHATR.OBJ

CHATR

000802 CHATR.OBJ

CHATR

000802 CHATR.OBJ

CHATR

000802 CHATR.OBJ

CHATR

000802 CHATR.OBJ

CHATR

000802 CHATR.OBJ

CHATR

000802 CHATR.OBJ

CHATR

000802 CHATR.OBJ

Global symbols:
ASC$
BUF$
CCP$
CHATR
CHR$
CLI$P
III$
IIN$
ILI$
ILS$
IPT$

6-14

025260-R
025200-R
025056-R
025312-R
025302-R
021504-R
021226-R
021120-R
021206-R
021102-R
021246-R

IRD$
021002-R
LEN$
025250-R
LIS$
021064-R
LIT$
021166-R
MOI$IP 021416-R
MOI$MP 021432-R
MOI$PA 021450-R
MOI$PM 021456-R
MOI$PP 021426-R
MOI$PS 021442-R
MOI$SP 021420-R

Working with Program Sections

NOI$P
ONI$P
PVD$SI
PVF$SI
PVI$SI
PVS$AI
RCT$
RST$
SPC$
SPC$Ol
STR$

021474-R
021464-R
021512-R
021522-R
021662-R
021532-R
025032-R
020774-R
025222-R
025222-R
025230-R

025044-R
STS$
024774-R
TAB $
025160-R
WAT$
$ATOD 022370-R
$CRLF 022014-R
$DMAXD 024772-R
$DTOA 023546-R
$DTOAX 023552-R
$FMAXD 024770-R
$FTOA 023500-R
$FTOAX 023504-R

USER.TSK
CHATR
$POS

Memory allocation map TKB 08.006
15-MAY-90
14:00

025074-R

$PRNSP 022150-R

$PRNTL 022166-R

Page 9

$SETUP 022062-R

*** Task builder statistics:
Total work file references: 25363.
Work file reads: O.
Work file writes: o.
Size of core pool: 9630. words (37. pages)
Size of work file: 8960. words (35. pages)
Elapsed time:00:00:26

Working with Program Sections

6-15

Part III
System Aspects

Chapter 7

Building Your Own Memory-Resident Areas

Chapter 2 describes how to link a program to a resident library, one type of
resident area. This chapter describes how to build your own resident area of
routines or data.

7.1

What is a Resident Area?
A resident library (see Section 2.2.2) is one type of resident area. A resident
library, when in memory, can be shared by many programs. It can consist of
data or reentrant subroutines and is generally mapped read-only. (The term
"reentrant" means that the program does not change any values within itself
during execution. Thus the same code can be executed by one job while another
job is also executing it; it can be "reentered" before the first job finishes.)
A resident common is another type of resident area. A resident common provides
a way for two or more programs to communicate. One program can store data
in the resident common for another program to retrieve at a later time. The
resident common area is accessible to both. Resident common areas are generally
mapped read/write.

7.2 The Steps in Creating a Resident Area
There are three steps in creating a resident area: the first involves the Task
Builder. You must build the resident area and create a symbol table file that
later allows other executable programs to link to the resident area. The symbol
table file contains the global symbols defined in the library or common and either
relative or absolute addresses for the symbols. This symbol table file is later used
by the Task Builder when other builds reference the resident library or common.
The steps in building a resident area are described in the previous sections. The
steps in creating a resident library are:
1.

Using the MAKSIL utility to format Task Builder output to produce suitable
input to the RSTS/E monitor. This step is described in the RSTS / E

Programmer's Utilities Manual.
2.

Establishing the area as memory-resident. You can perform this operation
with the INSTALL DCL command as described in the RSTS / E System

Manager's Guide.

Building Your Own Memory-Resident Areas

7-1

7.3 How to Build Memory-Resident Areas
Building a memory-resident area is similar to building an executable program.
The differences are:
1. You must declare that the task file t is not to contain a "header." The header
on a task file contains information that is used by the loader in the run-time
system when it loads an executable program. The information is used to
set certain areas in the low 1000[8] bytes of address space in the user job
area. Since resident areas do not occupy this low-address range, you do not
need (and should not have) a header for the task file. You omit the header
by appending the switch /-HD or /NOHD to the task file specification in the
command line.

2. You must declare that no space is to be allocated for the "stack." The stack
is an area of memory that can be used for temporary storage. The stack is
accessed by the user program in low virtual address space (see Section 12.26).
It should not be built into a resident area, which will occupy high virtual
address space. You omit the stack by using the option STACK=O in the build.
3. You must request a symbol table file as well as a task file. The symbol table
file is the third output field on the TKB line. As described in Section 7.2, this
file is used by the Task Builder when it links the resident area to a program
that references the resident area.
4. You must declare whether the area is to be position independent (have
relative addresses, so that it can be loaded anywhere in the job area) or
absolute (have absolute addresses, so that it must be loaded into the same
place in the job area each time it is used). The next two sections explain how
to do this.

7.3.1

Building Position-Independent Resident Areas
A resident area can be either position independent or absolute. Positionindependent areas can be placed anywhere in the user job area.
Declaring an area to be position independent causes the Task Builder to:
1. Include definitions for each root segment program section in the symbol table
(.STB) file. A program can later reference this shared storage by program
section name.

2. Generate relative addresses for the resident area, such that the resident
area can be located anywhere in the user job area when it is linked to a
program that references it. (This allows you to choose the automatic selection
of the highest APR, or to select an APR in the LIBR, RESLIB, COMMON,
RESCOM, RESSUP, OR SUPLIB option.)
You should declare an area to be position independent if:
1. The area contains code that executes correctly regardless of its position in the
address space of the program that references it.

2. The area contains data that is not address dependent.

t The term "task file" is used instead of "executable file," since a memory-resident area is not executed with a RUN
command. Rather, it is eventually linked to an executable program in a later build. The task file is the first file that
you specify in a Task Builder command line, with default file type .TSK.

7-2 Building Your Own Memory-Resident Areas

3. The area contains data that is refer enced by a program (such data must
reside in a named common block).
Because the program section name is preserved in a position-independent area,
you should observe the following precautions when building and referring to such
an area:
1. No code or data in the area should be included in the blank (unnamed)
program section.
2. No code or data in a program that refers to the area should have a program
section with the same name as a program section in the resident area.
3. The order in which address space is allocated to program sections (alphabetic
or sequential) must be the same for the resident area and the program that
refers to it.
To make an area position independent, use the /PI switch on the task or symbol
table file name and specify the PAR option just to name a "partition" that the
area is to occupy. (Do not use PAR to indicate a starting address and length in
this case.) The partition name must be the same as the file name portion of the
task and symbol table files.
Example

The following command line builds a position-independent area from the input
files DAT1.DAT, DAT2.DAT, and DAT3 .DAT:
RUN $TKB
TKB> DATLIB/-HD/PI"DATLIB=DAT1.DAT,DAT2.DAT,DAT3.DAT
TKB> /
ENTER OPTIONS:
TKB> P AR=DATLIB
TKB> STACK=O
TKB> / /

The /-HD and /PI switches are described in Chapter 13.

7.3.2

Building Absolute Resident Areas
Absolute resident areas must always occupy the same place in the user job area
when linked to a program. If you build this type of area, only one program
section, named .ABS., is included in the symbol table file. All references to code
or data in such an area must be by global symbol name. Further, when you link a
program to an absolute resident area, you must use the APR parameter to specify
the correct location where the area is to be linked.
Use the PAR option to build an absolute resident area. The PAR option is
described in Chapter 12. Briefly, the format is:
PAR=pname:base:length
where:
pname

is the partition name; this must be the same as the file name portion of the
task file and symbol table file in the command line.

base

is the base address, in octal, that the resident area is always to occupy.

length

is the octal number of bytes of the area. If you omit the length argument, the
length of the task file is used.

Building Your Own Memory-Resident Areas

7-3

For example:
RUN $TKB
TKB> MYLIB/-HD"MYLIB=CODEl,CODE2,CODE3
TKB> /
ENTER OPTIONS:
TKB> PAR=MYLIB:140000
TKB> STACK=O
TKB> / /

The area above would always have to be linked as follows:
RUN $TKB
TKB> PROG=PROG
TKB> /
ENTER OPTIONS:
TKB> LIBR=MYLIB:RO:6
TKB> / /

That is, since it was built to begin at location 140000, it must always be linked
using APR 6. Note also that MYLIB.TSK and MYLIB.STB must be on the device
in the account denoted by the system logical LB :, because LIBR was used rather
than the RESLIB option.

7.4 Resident Areas with Memory-Resident Overlays
The Task Builder lets you construct what are called "memory-resident overlays"
for resident areas. Memory-resident overlay segments are loaded from disk
when your program is loaded; thereafter, they reside in memory as long as any
other program in memory is using them. Memory-resident overlays share virtual
address space, just as the disk-resident overlays that we have discussed. Unlike
disk-resident overlays, memory-resident overlays do not share actual memory.
Instead, they reside in separate areas of actual memory. The virtual address
space is shared by the mapping technique described in Chapter 2.
For example, consider Figure 7-1. At time 1, the job area in virtual address space
contains OVLY1, one segment of a resident area with memory-resident overlays.
At time 2, the job area in virtual address space contains OVLY2, the other
segment of the resident area with memory-resident overlays. Both segments
OVLY1 and OVLY2 reside in physical memory; they are mapped into the virtual
address space at different times.

7-4 Building Your Own Memory-Resident Areas

Figure 7-1:

Memory-Resident Overlays

VIRTUAL
ADDRESS SPACE

PHYSICAL;
MEMORY:

USER
PROGRAM

OVlY1

II:

II:
CD

::::i

OVLY2

A) TIME1: USER PROGRAM REFERS TO OVLY1.

USER
PROGRAM

OVlY2
OVLY1

II:

II:
CD

::::i

O\flY2

B) TIME2: USER PROGRAM REFERS TO OVLY2.
MK-{)0593-00

7.4.1

Specifying Memory-Resident Overlays
You can use many of the same techniques in doing memory-resident overlays
for resident areas as you use for disk-resident overlays. As with disk-resident
overlays, the branches of an overlay tree must be logically independent (see
Section 3.6). In the example in Figure 7-1, OVLY1 cannot call or refer to data in
OVLY2, or vice versa.
In the ODL file, use an exclamation point to specify memory-resident overlay
segments. Memory-resident overlay segments are indicated by placing an
exclamation point immediately before the left parenthesis enclosing the desired
segments. For example:
.ROOT A-! (B,C)

Building Your Own Memory-Resident Areas

7-5

In this example, segments Band C are declared resident in separate areas
of memory. The Task Builder determines the addresses for the resident area
(relative or absolute, depending on whether the resident area is built as position
independent or absolute) as follows. The starting address of segment A is 0
(position independent) or as specified in the PAR option. The length of segment A
is rounded up to the next 4K-word boundary; this determines the starting address
for Band C. The length of Band C are rounded up to the next 32-word boundary
to determine the total memory required by the area.
The exclamation point applies only to segments at the first level inside a pair of
parentheses; segments nested within the first level are not affected.
Note the significance of rounding up to the next 4K-word boundary; the least
amount of space that a memory-resident overlay can occupy is 4K words.
Likewise, each segment occupies some multiple of 4K words. An overlay segment
of 4097 words (one word over the 4096-word limit) will take 8K words of virtual
address space.
There is another consideration for memory-resident overlays. The user program
that is eventually linked to the resident area in the example in Figure 7-1 can
make calls to A, B, or C and they will be mapped properly. However, A cannot
call B or C. The reason is that the Task Builder does not build the necessary
autoloading code into the resident area; it (eventually) builds it into the root
segment of the user program to which the resident area is linked. A cannot
call B or C, because there is no way to tell whether B or C has been mapped at
any given time. B or C can call A, however, because it is known that A will be
resident in the next-lower 4K of virtual address space, regardless of whether B or
C is currently mapped.

7.4.2

Building Memory-Resident Overlays
As described above, a resident library containing memory-resident overlays
must define the overlay structure in an ODL file. The build for such an overlay
structure proceeds somewhat differently than for disk-resident overlays.
Specifically, the Task Builder does not include the overlay data base (segment
descriptions, autoload vectors, and so forth) or the code for loading overlays as
part of the resident area task file. Rather, the data base is made part of the
symbol table file. This data base is later built into the program that refers to the
resident area. Note that this increases the size of the program that refers to a
resident area.
The symbol table file contains global definitions for only those symbols that are
defined or referenced in the root segment of the area. Such symbols consist of the
following:
1. Entry points to routines and data elements that are in the root.

2. Autoload vector addresses that point to definitions within a memory-resident
overlay.
3. Definitions of symbols defined in a memory-resident overlay and referenced in
the root.
No global symbol appears in the symbol table file unless it is either defined in
the root segment, or referenced in the root segment and defined elsewhere in the
overlay structure.

7-6

Building Your Own Memory-Resident Areas

You can force the inclusion of a global reference in the root segment of the
resident area by using the GBLREF option (Section 12.15). Thus, the necessary
autoload vectors and definitions can be generated without explicitly including
such references in a segment. The syntax of the GBLREF option is:
GBLREF=name

where:
name

is the one- to six-character global symbol name. If the definition for the symbol
resides within an autoloadable segment, the Task Builder creates an autoload
vector, and includes it in the symbol table file. If the definition is not in an
autoloadable segment, the real value is obtained and defined in the root segment.

You need to include in the GBLREF option all global symbols that will be used
in transfer-of-control statements but are not defined or referenced in the root
segment of the resident overlay area.
For example, suppose you are building a resident library out of the programs
ADD, SUB, MULT, and DIV and that you want these four routines to be memoryresident overlays. The ODL file would be specified as follows:
.NAME
.ROOT
.END

NULL
NULL-*! (ADD, SUB, MULT, DIV)

ADD, SUB, MULT, and DIV are entry points that will probably be called by any
program that references the resident library, and none of these are defined or
referred to in the root segment of the overlay structure. Include these four global
symbols in the GBLREF option when the library is built so that data for these
symbols will be included in the symbol table file. For example:
RUN $TKB
TKB>MATHLB/-HD/PI"MATHLB/PI=OVERLY/MP
TKB> /
ENTER OP TIONS:
TKB> GBLREF=ADD,SUB,MULT,DIV
TKB>PAR=MATHLB
TKB>STACK=O
TKB> //

Any program can then later refer to ADD, SUB, MULT, and DIY, and the Task
Builder will resolve the references properly from the information in the library's
symbol table file. For example:
RUN $TKB
TKB>MYPROG=MYPROG
TKB>/
ENTER OPTIONS:
TKB>RESLIB=DRO: [1,210]MATHLB
TKB>//

Note that we are using the RESLIB option, so the option includes the device and
account where the files MATHLB.TSK and MATHLB.STB reside.

Building Your Own Memory-Resident Areas

7-7

7.5 Building Your Own Cluster Libraries
This section assumes that you already know how to build a resident library. It is
more difficult to build cluster libraries than noncluster libraries because of the
additional rules imposed, as described in the rest of this section.
As discussed in Section 2.3.5, resident libraries that have been built to take
advantage of the "clustering" feature of the Task Builder can be mapped to occupy
the same virtual address space, taking less space in the user job area than they
would otherwise.
You can build your own resident libraries to take advantage of the clustering
feature. It requires that you follow the rules summarized below. Following
subsections discuss these rules in detail.

1. All libraries in a cluster must be position independent or built for the same
address.
2. All libraries except the default library in a user's CLSTR option must use
memory-resident overlays.
3. A called library routine must not require parameters on the stack by the
caller.
4. No library may be entered using synchronous or asynchronous system traps.
5. A library should not call routines from other libraries in the same cluster
directly.

7.5.1

Rule 1: Position Independent or Built for Exact Address
The Task Builder must be able to place each library in a cluster at the same
virtual address. To do this, the libraries must be built as position independent or
be built to the exact address specified in a user's CLSTR option.

7.5.2

Rule 2: Use Memory-Resident Overlays
If you want your library to be referenced as other than the default library in a

user's CLSTR option, it must use memory-resident overlays. Furthermore, the
root of the memory-resident overlay structure must be null (of zero length).
If your library does not require overlays, you can still build it so it seems

that resident overlays are being used. This will build the code necessary for
cross-library linkage into your resident library.
For example, suppose you have a disk library file LB:USILIB.OLB that requires
7K words of memory that you wish to make into a cluster library. You do not
wish to use memory-resident overlays; the library will simply use two APRs when
it is linked with a user's program. To build the necessary linkage into the library,
you can specify an ODL file with a "null root" and a "null branch" (Figure 7-2).
The ODL file for such a structure could be:

NULLA:
US1FAC:

.NAME US1CLS
.ROOT US1CLS-*! (NULLA,US1FAC)
.FCTR LB:SYSLIB/LB:NULL
.FCTR LB:US1LIB/LB

. END

7-8 Building Your Own Memory-Resident Areas

Figure 7-2:

Using a Null Memory-Resident Overlay

NULL

US1 LIB
ROUTINES

NULL

MK-00831-00

7.5.3

Rule 3: No Required Parameters on the Stack
This rule applies to routines contained in libraries other than the default library.
A routine in a cluster library should not expect to receive infonnation from the
caller that was pushed on the stack. This is because the Task Builder autoload
routines ($AUTO) may have used the stack for its own purposes in remapping
to the called library. There is no way for your library routine to detennine at
run-time whether the autoload code has or has not placed mapping infonnation
on the stack. So, the best way to handle this type of infonnation exchange is to
pass the address of call parameters in general-purpose registers, for example, RO.
lf parameters must be passed on the stack, then the calling program can push
the infonnation on the stack, and save the contents of the stack pointer register
(SP) to another register, for example, RO. The called library routine can then use
RO to find the infonnation it needs from the stack.
NOTE

Assembly language programmers must use a JSR PC instruction to
transfer control to the desired library routine, and the library routine
must use an RTS PC instruction to return control to the caller.

7.5.4

Rule 4: No Trap or Asynchronous Entry
A routine built as part of a library that is to be used in a cluster cannot be
specified as the service routine for a synchronous trap or for asynchronous entry
as a result of a CtrJlC, for example. This is because the library may not be the
one that is mapped at the time of the trap. For example, if the default library
contains the service routine to display an error message upon odd address trap,
and the odd address fault occurs within one of the other libraries of the cluster,
the routine will not be available to service the trap.

Building Your Own Memory-Resident Areas

7-9

7.5.5

Rule 5: No Calls to Routines in Another Cluster Library
A resident library routine cannot directly call a routine in another resident
library in the same cluster. The called resident library may not be in memory
when the call is made. There are rather elaborate techniques for routing the call
through autoload vectors that must be built into the user program in the low
segment. These techniques are described in the next section; however, Digital
recommends that you do not make calls between resident libraries that may be in
the same cluster.

7.5.6

Revectoring Cluster Libraries
A cluster library cannot directly call a routine in another library in the cluster.
The general technique involves indirect references, routing calls through the
user program in the "low segment," so that control eventually passes through
the correct autoload vectors to the desired routine in the called library. Thus,
the called library can be loaded from disk and, if necessary, mapped. The called
routine is then executed, and eventually control is returned to the calling library.
The approach involves including a "vector table" in the calling library, and a
corresponding "jump table" in the user program in the low segment. Ideally,
the code necessary for the vector table and jump table would be included in the
system library, so this is what our example shows.
The vector table defines as entry points the desired entry points in the called
library. Each definition in the calling library defines an offset for the entry point.
The offset defines the location in the library, and a corresponding ''jump table" in
the user program in the low segment. Ideally, the code necessary for the vector
table and jump table would be included in the system library, so this is what our
example shows.
The vector table defines as entry points the desired entry points in the called
library. Each definition in the calling library defines an offset for the entry point.
The offset defines the location in the jump table for the address of the desired
autoload vector into the called library. The vector table also includes common
dispatch code to transfer control. This code transfers control through the jump
table, through the appropriate autoload vector in the user program, to the entry
point in the called library (see Figure 7-3).

7-10

Building Your Own Memory·Resident Areas

Figure 7-3:

Overview of How Inter-Cluster-library Calls Work

CALLING LIBRARY

CALLED LIBRARY

.OPEN::

(Vector Table)

.OPEN::(offset 30)
DISPAT:

USER PROGRAM

. FSRPT - - - - - 1.._

Pointer to index
table

A.JUMP - - - - - 1..-

Pointer to jump
table

Jump table for
called library

Autoload vector for
.OPEN in called lib

MK-01054-00

Building Your Own Memory-Resident Areas

7-11

7.5.7

Sample Vector Table Code
The code below illustrates part of a sample vector table.
.OPEN:: MOV

DISPAT:

DISPAT

;PUT OFFSET INTO USER PROGRAM
;JUMP TABLE ON THE STACK
;JOIN COMMON DISPATCH

MOV
MOV
ADD
MOV
MOV

RO,-(SP)
@it.FSRPT,RO
A.JUMP(RO),2(SP)
(SP)+, RO
@(SP)+,-(SP)
@(SP)+

;SAVE REGISTER
;GET POINTER TO DATA AREA
; ADD VECTOR BASE TO OFFSET
;RESTORE REGISTER
;PICK UP ADDRESS OF TARGET
;AND TRANSFER TO TARGET

JMP

#30, - (SP)

In the example above, the code at .OPEN pushes the known offset into the jump
table (30) onto the stack and transfers control to dispatch code, common for all
the revectored entry points. The code at DISPAT:

1. Pushes the contents of RO onto the stack, to save it.
2. Moves the address of the base of the data area into RO.
3. Adds the base address of the jump table to the index onto the stack.
4. Restores RO.
5.

Puts the address of the desired routine's autoload vector onto the stack.

6. Jumps to the autoload vector for the desired routine (.OPEN).

7.5.8

GBLXCL and GBLlNC Options
In the preceding example, notice that both the calling library and the called
library contain an entry point named .OPEN. You must exclude global symbols
for such revectored entry points from the calling library's symbol table (.STB)
file, or the Task Builder has a hard time figuring out which one to use when
the libraries are referenced during a user program's build. To do this, use the
GBLXCL option when you are building the calling library.
Another aspect of building the calling library is ensuring that the needed jump
tables are built into the user program when the calling library is referenced
there. This involves placing the code for the jump tables in the system library, or
a library always referenced by the user program, and ensuring that such code is
always included in the user program when the calling library is referred to in the
user program. You use the GBLINC option in the calling library to do this.
The example below shows the build for the "calling library," called USICLS.
RUN $TKB
TKB>USICLS/-HD,USICLS/CR/-SP/MA,USICLS=USILIB.OBJ
TKB>LB:SYSLIB/LB:FCSVEC
TKB> /
ENTER OPTIONS:
TKB> STACK=O
TKB>PAR=USICLS:140000:4000
TKB> GBLINC=.FCSJT
TKB> GBLXCL=.OPEN
TKB> //

7-12

Building Your Own Memory-Resident Areas

The example above shows the vector table (FCSVEC) as a module in the system
library. Building such a vector table as part of a commonly used library, such as
SYSLIB, makes it easier for more than one library to access the called library.
The GBLINC option shown forces the Task Builder to add a global reference entry
for .FCSJT in the library's .STB file. This ensures that the Task Builder links
the jump table modules required by the library into the user program. These
modules should be in the system library, or in a library always referenced by the
user program. Thus, this forced loading mechanism is invisible to the user.

7.6 FORTRAN Virtual Arrays
The FORTRAN-77 programming system automatically provides a virtual array
mechanism for up to 255K words of data. The FORTRAN user can generate a
unique dynamic region for data by making the proper declarations within the
control of the FORTRAN language. Refer to the FORTRAN-77 User's Guide and
other language manuals for more information.
NOTE

The size of the virtual arrays created may be limited by the dynamic
region limit. See the RSTS / E System Manager's Guide.
If a FORTRAN program requires more memory-based data than the virtual

arrays can provide, use virtual program selectors.
Use the following FORTRAN-77 statement to invoke the automatic virtual array
mechanism:
VIRTUAL var(index) , var2(index2), ...

The FORTRAN compiler informs the Task Builder of the required size of the
virtual array area. The TKB instructs the RSTS monitor to create the propersized dynamic region automatically. In RSX-llM-PLUS, this offset size is
additional memory allocated to the task partition. In RSTSIE, it is the size of
the dynamic region that will hold the virtual array data. This unnamed dynamic
region will be created when the task is loaded at run-time and will always have
the region ID value of zero. If not enough memory to allocate the dynamic region
exists (see the RSTS / E System Manager's Guide), the task will not start. The
FORTRAN language will automatically map the region as needed to access the
data.
You can use the automatic region creation feature in MACRO-ll programs by
including one of the following:
•

The program of a .PSECT of the form:
.psect NAME,D
varnam: :
UNORG

where:
name

is a unique section name

Building Your Own Memory-Resident Areas

7-13

•

The TKB VSECT option related to the PSECT above as follows:
VSECT=name:base:max_window_size:region_size

where:
name

is the related PSECT name

base

is the byte address of the window to map the dynamic
region (for example, 160000 for APR 7)
is the number of bytes the largest mapped window in the
region will have.
is the size the dynamic region will be in memory when
created in 32-word blocks (the maximum value on RSTSIE
is 17740, which equates to 255K words).

See Chapter 12 for more details on the VSECT option.
When the MACRO-ll task has been started, there will be a dynamic region
with a region ID of zero already created and attached to the job. Before the
region can be used, the program must create the window (CRAW$) and map
it to the APR (MAP$). It does not need to be the same APR indicated by the
"base" in the VSECT option, but if it is not, then the "varnam" global has no
utility in addressing the region.

7.7 Virtual Program Selectors
A virtual program section is a special TKB 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 TKB through the VSECT
option and in FORTRAN through a set of FORTRAN-callable subroutines that
issue the necessary mapping directives at run time. With the TKB 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

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 TKB 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 windows.
By specifying the physical size, you can allocate, before run time, the physical
memory that the program section will be mapped into at run time. TKB allocates
this physical memory within an area that is treated by RSTSIE as a dynamic
range. This area is called the mapped array area and can be up to 255K words in
size.

7-14 Building Your Own Memory-Resident Areas

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 TKB attaches the virtual attribute to a relocatable program section
you have specified in the VSECT option only if the section is defined in the root
segment of your task through either a FORTRAN COMMON or a MACRO-ll
.PSECT statement. The relocatable program section with the virtual attribute
in the root does not use address space in your task; using this procedure merely
assigns an address, window size, and physical length to a region yet to be mapped
at run time by your task. For example:
VSECT=MARRAY:160000:20000:2000

In this example, virtual program section MARRAY is allocated with a window
size of 4K words (20000 8 bytes) and a base virtual address of 160000. In physical
memory, 32K words are reserved for mapping the section at run time.
Assume that the program is written in FORTRAN and includes the following
statement:
COMMON!MARRAY!ARRAY(4096) ...

This statement generates a program section to which TKB attaches the virtual
attribute. However, this program section is not a FORTRAN virtual array;
the user program must manually map it. A reference to the first element of
the section, ARRAY(l), is translated by TKB to the virtual address 160000.
Figure 7-4 shows the effect of this use on the VSECT option.

Building Your Own Memory-Resident Areas

7-15

Figure 7-4:

VSECT Option Usage

WlNr:x:Y#
160000 APR 7 -I-------~
(VIRTUAL BYTE BASE ADDRESS)
APR6 APR5 -

TASK
IMAGE

APR4 APR3 APR 2 _

APR 1 APR 0 -

(PROGRAM
SECTION
DEFINITION)
COMMONIMARRAY/...

COMMONIMARRAY/...
HEADER & STACK
VIRTUAL ADDRESS
SPACE

••
•

•

TKB>/
Enter Options:
TKB>VSECT - MARRAY: 160000: 20000: 2000

••
•

PHYSICAL LENGTH
IN 64-BYTE BLOCKS

¥¥••

• Size of dynamic region is the total of all VSECT physical lengths.

7-16

Building Your Own Memory-Resident Areas

MAPPED
ARRAY
AREA
IN
DYNAMIC
REGION

PHYSICAL MEMORY

As mentioned previously, TKB 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 bases if the window size is exceeded.
This process is illustrated in the following example, in which three modules (A, B,
and C) each contains a program section named DIRT that is 3000 words long. A
window size of 4K words has been set through the VSECT option. If the program
has the concatenate attribute, the Task Builder allocates memory to each module
as follows:
Module

Low Limit

Length

High Limit

160000

14000

174000

14000

174000
170000

170000

14000

164000

The address limits for modules Band C illustrate the effect of address
wraparound 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 in order and remapped in increments
of the length's size.

7.7.1

FORTRAN Run-Time Support for Virtual Program Sections
FORTRAN supports subroutines to make use of the mapping directives, and it
supports calls to the following subroutines, which are related to virtual program
sections:
Subroutine

Function

ALSCT
RLSCT

Allocates a portion of physical memory for use as a virtual section
Releases all physical memory allocated to a virtual memory section

As mentioned earlier, the effect of one or more VSECT= declarations at task
build time is to create a pool of physical memory outside 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.
You can ask the ALSCT routine to either use the automatically created region or
create a region of its own. By creating new regions, it is possible for a FORTRAN
program to have over 1.5 megabytes of data resident in memory (if it physically
exists) without affecting program size. This is because the two D-APRs that are
not used by the RMSRES can each be used for a 255K-word region in addition to
the 255K-word region automatically created.
NOTE

FORTRAN does not provide any array bounds checking for these
arrays.

Building Your Own Memory-Resident Areas

7-17

7.7.1.1

The ALSCT Subroutine

The subroutine ALSCT is called to allocate physical memory to a virtual program
section as follows:
CALL ALSCT (ireg,iwnd[,ists])

The ireg parameter is a one-dimensional integer array that is nine words long.
Elements 1 through 8 of the array contain a region descriptor for the physical
memory to be mapped. The format of the descriptor is shown in Table 7-1.
Table 7-1:

Format of Region Descriptor

ireg(l)

Region ID (0 is the automatic region)

ireg(2)

Size of region in units of 64-byte blocks

ireg(3)

Name of region in Radix-50 format (first three characters)1

ireg(4)

(Second three characters) 1

ireg(5)

Name of main partition region in Radix-50 format (first three characters)1

ireg(6)

(Second 3 characters)l

ireg(7)

Region status word l

ireg(8)

Region protection code!

ireg(9)

Thread word-links window descriptors used to map portions of the region;
maintained by the subroutine

lNot supported on RSTSIE.

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 0 on the initial call each region used;
thereafter, the subroutine maintains it.
On the initial call to ALSCT for each region ID used, (ireg (1» has special
meaning in that it tailors the region descriptor to what has been specified. If
ireg(l)=O and ireg(2)=O, the system will use the automatic region and fill in
ireg(2) with the size of the dynamic region that was created at run-time. If ireg
(1)=-1, the system will create a new dynamic region of the size given in ireg(2) (if
memory is available) and return the region ID of the new region in ireg(l). After
the initial call to ALSCT, the program should not change either ireg(l) or ireg(2).
The subroutine does not refer to elements 3 through 8; the caller must set them
up as required by the applicable system directives (for example, CRRG$). For a
detailed description of these parameters, refer to the RSTS / E System Directives

Manual.
The iwnd is a one-dimensional array that is 11 words long. The first eight words
contain a window descriptor in the following format:

7-18

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 window used

iwnd(3)

Window size in units of 64-byte blocks

iwnd(4)

Region ID (0 is automatic region)

iwnd(5)

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

Building Your Own Memory-Resident Areas

iwnd(8)

Address of send/receive buffer

iwnd(9)

Base offset of physical block allocated to section in units of 64-byte blocks

iwnd(10)

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

iwnd(U)

Thread word-links window descriptors used to map other portions of the
region; maintained by the subroutine

You must set up iwnd(lO) before calling ALSCT.
The following array elements are supplied as output from the subroutine:
iwnd(4), iwnd(5), iwnd(9), iwnd(lO), and iwnd(ll)

The remaining elements must be set up as required by the Executive directives.
Consult the RSTS / E System Directives Manual for a detailed description of these
parameters.
The ists is a variable that receives the results of the call and returns one of the
following values:
+1

Block successfully allocated; in this case, the region and window descriptors
arrays are set up as described above.
'

-200.

Insufficient physical memory available for allocating the block. will contain the
region size available.

Ireg(l) will contain the new region ID or 0 for auto region. Ireg (2) will contain
the region size used. If the program uses both the automatic virtual array and
the manual virtual arrays in the automatically created region, you must first
allocate a place-holder window equal to the size of that used by the automatic
virtual array. Example 7-2 demonstrates how to do this.
7.7.1.2

The RLSCT Subroutine

The subroutine RLSCT is called to deallocate the physical memory assigned to a
virtual section as follows:
CALL RLSCT (ireg, iwnd)

As for ALSCT, ireg is a one-dimensional array that is nine words long. The
contents of the array are the same as those descriped for the ALSCT subroutine.
Likewise, iwnd is the same as for ALSCT, that is, a one-dimensional integer array
that is 11 words long. The contents of the array are the same as those described
for subroutine ALSCT.
Upon return, element iwnd(lO) is the length of the deallocated region in units of
64-byte blocks.
The procedure for using these subroutines can be summarized as follows:
1. Allocate storage in the program for one window descriptor for each virtual
program section and for a single region descriptor.

2. Your task calls the subroutine ALSCT to reserve the physical memory to
which the virtual program section will be mapped.
3. 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).
4. When the space is no longer required, the task unmaps and releases it with a
call to RLSCT.

Building Your Own Memory-Resident Areas

7-19

7.7.2

Building a Program That Uses a Virtual Program Section
Example 7-2 shows the FORTRAN source file for a task named VSECT.FTN. The
example illustrates the use of the ALSCT FORTRAN subroutine, and uses the
automatic region for both VARRAY and IARRAY. When you build, install, and run
VSECT2, it allocates the mapped array area in a dynamic region, creates a 4Kword window, and maps to the area through the window. ALSCT then initializes
the area and prompts for an array subscript at your terminal, as follows:
SUBSCRIPT?

When you input a subscript, it responds with ELEMENT= and the contents of
the array element for the subscript you typed. VSECT2 continues to prompt until
you press CtrllZ at which time it exits.
Once you have compiled VSECT2, you can build it with the following TKB
command sequence:
TKB @VSECT2

Examp le 7-1:

VSECT2.CMD

>
;
VSECT2 . CMD
SY : VSECT2/ID/FP,vsect2=vsect2.odl/MP
UNITS =12
ASG
=SY : 7 : 8:9:10 : 11:12
EXTTSK=512
MAXBUF=512
WNDWS=2
LIBR=RMSRES : RO : 6 : 0
VSECT=MARRAY:160000 : 20000:2000

Note the following in Example 7-1:
•

The lID allows the use of the D-APRs where the RMSRES is placed.

•

The RMSRES is at APR 6 and the APRs are unprotected in the D-space.

•

The VSECT option has a physical length of 4K words which will be added to
the length needed for the VARRAY( ).

•

The WNDWS option is set allow for both types of arrays used.

This command file sequence directs TKB to create a task image file named
VSECT.TSK and a map file named VSECT2.MAP. (See Example 7-3.)
The WNDS option directs TKB to add a window block to the header in the task
image. The Executive initializes this window block when it processes the mapping directives within the task. This allows two programmed address windows
(CRAW$) to be created in this region.
The VSECT option directs TKB to establish for the program section named
MARRAYa base address of 160000 (APR 7) and a length of (20000) 8 bytes (4K
words). The program section MARRAY is defined within the task through the
FORTRAN COMMON statement. The VSECT option also specifies that TKB is to

7-20

Building Your Own Memory-Resident Areas

allocate 200 64-byte blocks of physical memory in the task's mapped array area in
the automatic dynamic region. For more information on the switches and options
used in this example, refer to Chapters 11 and 12, respectively.)
This command sequence results in the map shown in Example 7-3.
The DCL link for FORTRAN-77 also creates the following ODL file:
VSECT2.0DL
; TKB .ODL file created by DCL LINK V10.0-F
@LB:RMSllM.ODL
@LB:RMSRLX.ODL
OTSROT-RMSROT
ROOT$$: .FCTR
LBR$$
. NAME
AO$,OTSALL,RMSALL
.ROOT
SY:VSECT2-ROOT$$-LBR$$
.FCTR
AO$:
.END

Example 7-2:

09-May-90

09:49 AM

Source Listing for VSECT2.FTN

vsect2.ftn

c
c

VIRTUAL VARRAY(1500)
integer *2 sub,irdb(9),iwdb(11),iwdb2(11),dsw
integer *2 IARRAY(4096)
common !MARRAY!IARRAY
Set up the window for the manual virtual array.
iwdb(1)="3400
!use apr 7 for window
iwdb(3)=128
!window size=128*32 words=4096 (1 apr)
iwdb(5)=0
!offset =0
iwdb(7)="422
!status=WS.64B!WS.WRT!WS.UDS
iwdb(10)= 128
!size to allocate =4Kw
Set up the window for the automatic virtual array.
This window will not actually be used--it is just a place-holder.
iwdb2(1)="3400
!use apr 7 for window
iwdb2(3)=96
!window size=96*32 words=3072
iwdb2(5)=0
!offset =0
iwdb2(7)="422
!status=WS.64B!WS.WRT!WS.UDS
iwdb2(10)= 96
!size to allocate =3Kw
irdb(2)=340
!region size expected (total)
irdb(9)=0
!assure link is zero for first call

Allocate 3K mapped area for the VARRAY (not to be used)

call ALSCT(irdb,iwdb2,dsw)
if (dsw .ne. 1) goto 100
c

Allocate 4K mapped array

call ALSCT(irdb,iwdb,dsw)
if (dsw .ne. 1) goto 100
c

Create a 4K window

call CRAW(iwdb,dsw)
if (dsw .ne. 1) goto 200
c

Map the array into virtual space

call MAP (iwdb,dsw)
if (dsw .ne. 1) goto 300

(continued on next page)

Building Your Own Memory-Resident Areas

7-21

Example 7-2 (Cont.):
10

Source Listing for VSECT2.FTN

do 10 i=1,4096
1ARRAY(i)=i

Mapped array initialized

30
35
40
60

write (5,35)
format ('subscript?')
read (5,40, END=1000) sub
format (i7)
write(5,60) I ARRAY (sub)
format (' element = , ,17)
goto 30

c
c

error entries

100
101

write (5,101)dsw
format (' error from ALSCT, error= , ,17)
goto 1000
write (5,201)dsw
format (' error from CRAW, error= , ,17)
goto 1000
write (5,201)dsw
format (' error from CRAW, error= , ,17)
goto 1000
write(5,301)dsw
format (' error from mapping, error= , ,17)
goto 1000
call exit
end

200
201
200
201
300
301
1000

7-22

Building Your Own Memory-Resident Areas

Example 7-3:

Task Builder Map (Edited) for VSECT2.TSK

VSECT2.TSK

Memory allocation map TKB M43.00
18-MAY-90
09:19

Page 1

Partition name
GEN
Identification
18MAY
Task PPN
[216,1]
Stack
limits: 001000 001777 001000 00512.
PRG xfr address: 002424
Task attributes: IO
Total address windows: 7.
Mapped array area: 35840. words
Task
extension
512. words
Task image size
6720. words, I-Space
5376. words, O-Space
6720. words, I-Space
Total task size
41728. words, O-Space
Task Address limits: 000000 032133 I-Space
000000 024703 O-Space
R-W disk blk limits: 000002 000142 000141 00097.
Memory allocation synopsis:
Section
• BLK.: (RW,I,LCL,REL,CON)
MARRAY: (RW,O,GBL,REL,OVR)

$VARS : (RW,O,LCL, REL, CON)
VSECT.OBJ
$VIRT : (RW,O,GBL,REL,CON)
VSECT.OBJ
$$ALER: (RO,I,LCL,REL,CON)

Title

Ident

001000 000000 00000.
160000 020000 08192.
160000 020000 08192 . . MAIN. 18MAY

File

VSECT.OBJ

002262 000104 00068.
002262 000104 00068. .MAIN. 18MAY
002000 000140 00096.
002000 000136 00094. .MAIN. 18MAY
003220 000040 00032.

Building Your Own Memory-Resident Areas 7-23

In the following examples, the IARRAYis put into a newly created dynamic
region separate from the automatic region containing VARRAY(). In this case,
there is no need to set aside space for VARRAY( ) in the VSECT.
The following is the VSECT.CMD for Example 7-5.
TKB @VSECT

Example 7-4:

VSECT.CMD

;
VSECT.CMD
SY:VSECT/ID/FP,vsect=vsect.odl/MP
UNITS =12
ASG
=SY:7:8:9:10:11:12
EXTTSK=512
MAXBUF=512
WNDWS=2
LIBR=RMSRES:RO:6:0
VSECT=MARRAY:160000:20000:0

In this command sequence, note that:
•

The lID allows the use of the D-aprs where the RMSRES is placed.

•

The RMSRES is placed at APR 6 and the APR's are unprotected in the
D-space.

•

No physical length is given on the VSECT option because a new region will
be created.

•

The WNDWS option is set allow for both types of arrays used.

The DCL link command creates the same ODL file for Example 7-5 as it did for
Example 7-2:
VSECT.ODL
; TKB .ODL file created by DCL LINK V10.0-F
@LB:RMSllM.ODL
@LB:RMSRLX.ODL
ROOT$$: .FCTR
OTSROT-RMSROT
LBR$$
. NAME
. ROOT
AO$,OTSALL,RMSALL
SY:VSECT-ROOT$$-LBR$$
AO$:
.FCTR
. END

7..,,24

Building Your Own Memory-Resident Areas

09-May-90

09:49 AM

Example 7-5:
c

Source Listing for VSECT.FTN

vsect.ftn

VIRTUAL varray(1500)
integer *2 sub,irdb(9),iwdb(11),dsw
integer *2 IARRAY(4096)
common /MARRAY/IARRAY
iwdb(1)="3400
!use apr 7 for window
iwdb(3)=128
!window size=128*32 words=4096 (1 apr)
iwdb(5)=0
!offset =0
iwdb(7)="422
!status=WS.64B!WS.WRT!WS.UDS
iwdb(10)= 128
!size to allocate =4Kw
irdb(2)=200
!region size expected
irdb(3)=0
!set name to no-name
irdb(4)=0
irdb(l)=-l
!set to create new region
irdb(9)=0
!assure link is zero for first call
c

Allocate 4K mapped array in a newly created dynamic region

call ALSCT(irdb,iwdb,dsw)
if (dsw .ne. 1) goto 100
c

create a 4K window

call CRAW(iwdb,dsw)
if (dsw .ne. 1) goto 200
c

Map the array into virtual space

call MAP (iwdb,dsw)
if (dsw .ne. 1) goto 300
do 10 i=1,4096
IARRAY(i)=i

Mapped array initialized

30
35
40
60

write (5,35)
format ('subscript?')
read (5,40, END=1000) sub
format (i7)
write (5, 60) IARRAY(sub)
format (' element = , ,I7)
goto 30

error entries

100
101
200
201
200
201
300
301
1000

write (5,101)dsw
format (' error from ALSCT, error= ',I7)
goto 1000
write (5,201)dsw
format (' error from CRAW, error= , ,I7)
goto 1000
write (5,201)dsw
format (' error from CRAW, error= , ,I7)
goto 1000
write(5,301)dsw
format (' error from mapping, error= ',I7)
goto 1000
call exit
end

Building Your Own Memory-Resident Areas

7-25

7.8 Advanced Programmed Region Control
The Task Builder can now provide information about the allocation of D-space
APRs for a task to the program at execution time. Together with the new EXTM$
memory extend function (see RSTS / E System Directives Manual), the TKB can
maximize the amount of D-space memory that a task can request.
Programmers can build tasks with libraries that have both 1- only and 1- and
D-space code. The Task Builder will calculate the minimum number of APRs that
each task requires to satisfy the D-space needs of all the libraries used by the
task.
To effectively utilize this feature, each library should be organized such that all
DATA space required in the library is located at the highest address in the library
space. You must know at the time the library is built how many APRs contain
D-space because this information is required as input to the Task Builder in the
ILl switch.
As part of the information the Task Builder associates with each individual
resident library, a bit mask representing the APRs used by the library is kept.
The default value represents the I-space APRs. RSTS will load the library with
the 1- and D-space equivalent, thereby automatically protecting any D-space
existing in the library.
However, the saved bit mask value may be modified by the programmer in the
library switch given to the Task Builder. The ILl switch, which is required to
build a library, may now include a value in the range 0 to 377 in the following
format:
ILl [:nnn]

where:
nnn

is the desired mask value.

The meaning of each bit in the mask value is the same as described in the
EXTM$ function and is given in Table 7-2.
Table 7-2:

Bit Meanings in the Mask Value

Bit 7
Bit 6

Represents APR 7

<200>

Represents APR 6

<100>

Bit 5

Represents APR 5

<40>

Bit 4

Represents APR 4

<20>

Bit 3

Represents APR 3

<10>

Bit 2

Represents APR 2

<4>

Bit 1

Represents APR 1

<2>

Bit 0

APR 0 not usable by library

Through this switch value, the programmer can inform the Task Builder which
APRs contain D-space requirements. This switch value, rather than the default,
will be associated with this library when it is used by the Task Builder in future
applications.
It is important to note that for libraries built by Task Builders prior to V9.6, the
mask value is zero by definition. This means that the library is defined as having
I-only code. If, however, the library does have D-space requirements, they may be

7-26 Building Your Own Memory-Resident Areas

protected at the time the application task is built, as described in the following
section.

7.8.1

The EXTM$ Feature
At the coding level, the application programmer must do the following two things
to use the EXTM$ feature:
•

Use the EXTM$ memory extension function instead of the EXTK$ function

•

Provide a properly addressed memory location for the Task Builder to fill in
the APR usage mask data

The following lines of code provide the properly addressed location for the Task
Builder to fill in:
.PSECT

$$TSKP,D

$TSKP: :
.PSECT

This PSECT can go anywhere in the code. However, if it is not at the end of the
code, reset the PSECT back to your required PSECT.
For the EXTM$ function to work beyond what the EXTK$ does, the application
task must be built with 1- and D-space on (lID switch).
The value loaded in to $TSKP by the Task Builder and readable on execution of
the program will be one of two values:
•

The value computed by the Task Builder based on the appplication task and
all reference libraries

•

An override value provided by an option line

If the Task Builder generates the value in $TSKP, it will be the logical OR of the
application tasks allocated D-space APR mask and the associated APR bit masks
for all libraries referenced by the task build.
For example, for a task that has two libraries where LIBl uses APRs 6 and 7 and
LIB2 uses APRs 5, 6, and 7, and 5KW of data space, the computed value would
be 343 octal as determinable from the APR representation in Table 7-2.
It is possible also to explicitly set the value in $TSKP at the time of the application task build. This is how a programmer who knows a library has additional
available D-space can inform the task of such knowledge. The following three
option lines have been amended to include this new level of information:
LIBR =name:accesscode[:baseAPR[:bitmask]]
RESLIB =file/accesscode[:baseAPR[:bitmask]]
CLSTR =libl,lib2,lib3 ... 1ibn:accesscode[:baseAPR[:bitmask]]

where:
bit mask

is the value logically ORed with the task's allocated D-space mask and
loaded by the Task Builder in location $TSKP.

Building Your Own Memory-Resident Areas

7-27

See Chapter 12 for further details on the use of the listed options.
When using cluster libraries, the bit mask value applies to all libraries; therefore,
the most limiting required value must be used.
When relocation of a position-independent coded library (PIC) is being done by
the base APR value, the bit mask value must be specified because the value
associated with the library was based on its original base and is not valid at the
new base. To spcify the bit mask value of the library, shift it up or down one bit
for each APR of relocation shift, and then combine it with the other mask values
required.
If using libraries that were built by versions of the Task Builder before V9.6 and
the library contains any D-space, the bit mask value must be specified to protect
that D-space at the time the application is task built. As of RSTSIE V9.6, the
only Digital-supplied library that can take advantage of this feature is RMSRES.
RMSRES is built as 1- only code; therefore, all the D-space APRs are available to
the MACRO-ll programmer through this feature.
If a mask value of 0 is given, the EXTM$ command behaves just as EXTK$ does
under RSX-llM-PLUS; that is, any request for more data space used by a library
will automatically turn that D-space over to the task D-space all the way to the
top of the virtual address space.

Refer to the EXTM$ in Chapter 5 of the RSTS / E System Directives Manual for
more details.

7.9 Fast-Mapping Facility
A new mapping facility has been added as an alternative to the MAPFQ
subfunction of the .PLAS directive, providing greatly enhanced performance and
compatibility with the fast-mapping facility of RSX-llM-PLUS. Applications that
are dependent on remapping of libraries in the normal course of execution could
see significant speed improvements.
However, the fast-mapping facility has the following restrictions:
•

Only the offset to the map field (FQSIZE) and, optionally, the length to the
map field (FQBUFL), may be modified by the fast-mapping facility.

•

The interface to the fast-mapping facility is designed for speed, not for ease
of programming. Debugging a task using fast-mapping may be more difficult
than using the .PLAS directive. Specifically, protecting the operating system
and its data structures is the only validation of parameters that is done.

•

The interface uses the PDP-ll lOT instruction. Tasks may use lOT for
internal communications and other functions, but tasks that use fast-mapping
cannot use the lOT instruction for any purpose other than fast-mapping.

•

The interface uses registers for passing parameters rather than using a
FIRQB, a savings of significant instructions over the .PLAS directive. This
means that the MACRO-ll programmer must be careful about register usage
when using fast-mapping.

These restrictions (particularly the second) should not deter the use of fastmapping in high-performance applications. However, Digital recommends that
you first get the application running with the .PLAS directive, varying only the
FQSIZE and FQBUFL fields, and then replace the directive with fast-mapping.

7-28 Building Your Own Memory-Resident Areas

7.9.1

Fast-Mapping Code Provided by TKB
If a program does not use the lOT instruction or ODT, fast-mapping is still
available when using resident libraries. Much of the mapping of resident libraries
is automatically provided by the Task Builder in the form of autovectoring. Fastmapping is possible by using the!FO and!FM switches (see Section 11). When
the!FO switch is used, the autovectoring code loads fast-mapping routines rather
than .PLAS calls. No code changes are required by the user.

7.9.2

Programming Considerations
Before issuing a fast-mapping call, the task must create and map the window
by using the Create Address Window (CRAFQ) and MAPFQ subfunctions of the
.PLAS directive. The FIRQB+12 (octal) in the CRAFQ directive must be at least
as large as the largest FQBUFL to be requested in fast-mapping.
Three parameters are required for the fast-mapping call. The first parameter is
the base APR times 10 (octal) plus the lID space flag (O=I-space and 100 (octal)=
D-space).
The second parameter is the offset field to map from the start of the library to
the base of the window. The third parameter is an optional length to map. If
the length to map is given, the high bit of the first parameter (the APR times 10
(octal)) must be set.
Table 7-3 lists the first parameter values.
Table 7-3:

Values for the First Fast-Mapping Call Parameter
Base

Space

APR

If No Length Given

User-I

APR 1-0 cannot be changed

User-I

000010

100010

User-I

000020

100020

User-I

000030

100030

User-I

000040

100040

User-I

000050

100050

User-I

000060

100060

User-I

000070

100070

User-D

APR D-O cannot be changed

User-D

000110

100110

User-D

000120

100120

User-D

000130

100130

User-D

000140

100140

User-D

000150

100150

User-D

000160

100160

User-D

000170

100170

With Length Given

The offset field (second parameter) is specified in 32-word slivers, in the same
way it would be for the FQSIZE value in the MAPFQ subfunction of the .PLAS
directive, and has the same meaning.
Building Your Own Memory-Resident Areas

7-29

If the length to map is not specified (high bit of RO is 0), the length is assumed
to be the length given in the last PLAS mapping (either the value in XRB at
W.NLEN is CRAW$ or MAP$, or FQBUFL if CRAFQ or MAPFQ).
If the length is specified (high bit of RO is 1), then that length is mapped. If a
length of 0 is given in R2, then the smaller of either the last .PLAS mapping
length or the remaining length in the library between the offset and the library
top is mapped. This handling is identical to that for the .PLAS mapping for the
same case.

Note the difference between the RSTSIE and RSX-llM-PLUS versions is that
User D-space must remain mapped to user's low core (APRO) at all times in
RSTSIE. RSX-llM-PLUS does not have such a restriction.
Note also that the speed of fast-mapping is affected by the parameter values. Not
specifying the length to map is the fastest and specifying a length equal to zero
is the slowest. The improvement over the .PLAS directive is in the range of six
to twelve times faster. The amount of improvement depends on the amount of
remapping done by the task.

Calling Sequence

7.9.2.1

RO
Rl
R2
7.9.2.2

Parameter 1

See Table 7-2

Parameter 2

Offset field

Parameter 3

Optional length specification

Returned Data
RO

Status

R2
Rl,R3

Length mapped

Is.sue if successful
IE.ITS or IE.ALG if failure

7.9.2.3

In slivers if successful
Indeterminate

Programming Examples
Changing only window offset in I-space:
MOV
MOV

HO,RO
:jf:200,Rl

lOT
TST
BMI

RO
ERROR

;window at APR 4 in I-space
;offset from base of library is 4K words
;200 slivers * 32 words/sliver
;R2 is not needed
;issue fast map call
; successful?
;no

Changing window offset and actual length specified:

7-30

MOV
MOV
MOV

#100150,RO
#100,R1
:jf:500,R2

lOT
TST
BMI

RO
ERROR

;window at APR 5 in D-space
;offset 2K words from library base
;specified length = 10K words
;this will use APRs 5, 6, & 7
;issue fast map call
; successful?
ino

Building Your Own Memory-Resident Areas

Changing window offset and defaulted length specified:
MOV
CLR
CLR

#l00140,RO
Rl
R2

lOT
TST
BMl
MOV

RO
ERROR
R2,MAPLEN

;window base at APR 4 in D-space
;offset=O, window begins at library base
;force calculation to FlRQB+12(octal) or
;rema~n~ng size of library
;issue fast map call
; successful?
; no
;copy of size actually mapped, in slivers

In the above text and examples, the tenn "library" means a resident library or
dynamic data region.
The following are additional notes on the use of the fast map facility:
•

Fast-mapping cannot be used if ODT is included in the task build, because
the lOT instruction is used differenctly for both facilities.

•

Fast map cannot be used for mapping supervisor modes or called from supervisor mode.

•

Fast-mapping can be turned on and off in the program by doing a .SET or
.CLEAR system call to RSTS/E (see the RSTS / E System Directives Manual
for details of usage). Note that RSX-llM-PLUS does not support this programmable control.

Building Your Own Memory-Resident Areas

7-31

Chapter 8

User-Mode 1- and O.. Space
This chapter describes how the Task Builder divides a user task into instruction
and data space (1- and D-space). A series of figures and text explain task
mapping and the use of task windows in a RSTSIE system with an 1- and D-space
task. In the text, comparisons are made between conventional tasks and land D-space tasks. A conventional task is one that does not separately map
instruction space and data space.
1- and D-space is available only on specific PDP-11 processors. You can run
conventional tasks on an I- and D-space system; however, you cannot run 1- and
D-space tasks on a system that does not have the hardware available. PDP-11
processors that can run 1- and D-space tasks are: 11/44, 11/45, 11/50, 11/53, 11/55,
11170, 11173, 11/83, 11/84, 11/93 and 11/94.

8.1

User-Task Data Space
User-task data space contains data. The user task accesses data space through
D-space APRs. The I- and D-space feature allows a total of 16 APRs to map your
task: eight APRs for data space and eight APRs for instruction space. If your
task uses both I- and D-space to its maximum capacity, it can contain 64K words
of virtual address space.
Your task must use .PSECTs to contain data or instructions or both.
Conventional tasks and tasks that separate instruction space and data space
differ in only a few areas. The following sections discuss these areas.

8.2

1_ and D-Space Task Identification
The monitor detennines whether a task uses 1- and D-space at run time.
Therefore, you can run tasks built without 1- and D-space on a system that
supports I- and D-space without rebuilding the task.
The 1- and D-space task is one in which the Task Builder separates the data areas
and instructions. In this task, data areas should be defined by the MACRO-11
.PSECT directive that has the data attribute. Similarly, the .PSECT directive
with the instruction attribute defines instruction areas.

8.3 Comparison of Conventional Tasks and 1- and D-Space Tasks
A conventional task operating in user mode can contain 32K words of virtual
address space and access up to 32K words of physical memory. However, a task
using both 1- and D-space APRs can contain 64K words of virtual address space
and access up to 64K words of memory.
User-Mode 1- and D-Space

8-1

The conventional task in an 1- and D-space system uses both sets of APRs.
However, the relocation addresses in both 1- and D-space APRs are identical.

An 1- and D-space task can use both 1- and D-space APRs independently; that
is, APRs used in this way are not overmapped. Because of this, the task can use
eight D-space APRs to access and use data, and eight I-space APRs to access and
execute instructions. Using 16 APRs allows the 1- and D-space task to access a
total of 64K words of physical memory at one time.
Table 8-1 summarizes APR mapping for various combinations of 1- and D-space
tasks and 1- and D-space systems.
Table 8-1:

Mapping Comparison Summary

lID Task

lID System

Mapping Summary

Yes

I-space APRs and D-space APRs contain the same
relocation addresses.

Yes

I-space APRs map instruction space. D-space APRs
map data space.

Yes

Missing special feature error at run time.

8.4 Conventional Task Mapping
Conventional tasks map their virtual addresses to their logical addresses through
both I-space and D-space APRs. That is, the Task Builder does not separate
instruction space or data space, and the system does not differentiate the spaces
except by the logic inherent in the task. Therefore, the task must map to its
logical address space by both sets of APRs, which are overmapped.
Figure 8-1 shows an 8K-word task that does not use 1- and D-space, and that is
built against an 8K-word resident library.

8-2

User-Mode 1- and D-Space

Figure 8-1:

Conventional Task Linked to a Region in 1- and O-Space System

PHYSICAL
MEMORY
D-SPACE
APRS
VIRTUAL
ADDRESS
SPACE
28K

20K

7
6

REGION

TASK

1-------1...

8K I------i'"

I-SPACE
APRS

REGION

OK ' - - - - - ,

[:=J REGION MAPPING

L).I TASK MAPPING
MK-01678-00

8.5 1- and D-Space Task Mapping
Figure 8-2 shows an 8K-word 1- and D-space task. The Task Builder separated
the data and instructions in this task. Because of the way the Task Builder
processes task space, the task header must physically reside at the beginning of
the task in I-space. The Task Builder puts the header that the monitor uses for
task control in D-space. The task's stack is also in D-space.
The task in Figure 8-2 uses two APRs because of its size (8K-word). D-space
APR 0 maps the task's header and stack and part of D-space.

User-Mode 1- and D-Space

8-3

Figure 8-2:

I- and D-space Task Mapping in an I- and D-space System

o
MK·02072·00

8.6 Designing an I-and D-Space Task
You design an I- and D-space task by specifying data space separately from
instruction space. Good programming practice suggests that all data areas
and buffers should be located in adjacent locations. Similarly, all instructions
should be located in adjacent locations. However, the Task Builder will separate
instruction and data space when it builds the task. For the Task Builder to do
this, you must tell it which statements are data and which are instructions.
If you program in MACRO-ll, use the MACRO-ll .PSECT directive to separate
instructions and data. Use this directive with the instruction (I) attribute for
all the instruction locations in your task's code. Use .PSECT with the data (D)
attribute for all the data locations. You must define a data .PSECT in an 1- and
D-space task even if no actual data is contained in the task. In this case, the
.PSECT can be of 0 length.
Note that a configuration consisting of libraries that map separate 1- and D-space
is not possible.

8.7 Concurrent Libraries
The Task Builder allows the optimization of a task's virtual address space on
machines that support separated 1- and D-spaces through the RSTSIE concurrent
libraries feature. This feature allows a data region to share the same APR as a
library that only contains I-space code (such as RMSRES).
8-4

User-Mode 1- and O-Space

When the RESCOM or COMMON options are used, the resulting task maps the
specified region in D-space only. Depending upon how the task is designed, the
equivalent I-space is mapped according to one of the following arrangements:
•

As part of the task's instruction low segment area

•

To a library containing I-space only code specified in a RESLIB or LIBR
option

•

Equal to the D-space for task builds done with no separate I- and D-spaces
(/-ID)

•

Not mapped at all if none of the above conditions is true

When RESLIB or LIBR options are used, the Task Builder initially gives both
the I-space and the D-space APRs to the library. However, the D-space can
be stripped from the library and given to another region under the following
conditions:
•

When a COMMON or RESCOM option is assignned to the same APR (see
above)

When an EXTTSK option expands the task's D-space into the same APR

If the program executes a EXTM$ call that expands the tasks D-space into
the same APR

•

If the program executes a CRAW$ (or CRAFQ) call with the User Data Space
(UDS) bit set that uses the APR

•

If the program creates a dynamic region that uses the APR

•

When a VSECT option is given that uses the APR

The D-space of one or more APRs of a library can be forced to stay with the
I-space (protected) by the use of the proper Bit Mask values. The protection can
occur at the following levels:
•

When the library is built (ILI:mask)

When the task is built (for example, RESLIB=MYLIB:RO:6:300 (300 is a
mask)

•

When the EXTM$ is executed (the mask is given as a parameter)

For more details on the protection mask and EXTM$, refer to Secton 7.S.1.
If the task is built without the lID switch, the D-space will remain with the
I-space for all APRs. Most of the items above will create some form of error if
used as concurrent libraries without the lID switch.
NOTE

The order in which options are presented to the Task Builder has no
bearing on the resulting mapping.

User-Mode 1- and D-Space

8-5

Chapter 9

Supervisor-Mode Library

A supervisor-mode library is a resident library that doubles a user task's virtual
address space by mapping the instruction space of the processor's supervisor
mode.
A call from within a user task to a subroutine within a supervisor-mode library
causes the processor to switch from user mode to supervisor mode. The user
task transfers control to a mode-switching vector that the Task Builder includes
within the task. Mter performing the mode switch, the vector transfers control
to the called subroutine within the supervisor-mode library. When the library
routine finishes executing, it transfers control to a completion routine within the
library, which switches the processor back to user mode. The user task continues
executing with the processor in user mode at the return address on the stack.

9.1

Mode-Switching Vectors
In a task that links to a supervisor-mode library, TKB includes a 4-word, modeswitching vector in the user task's address space for each entry point referred to
in a subroutine in the library.
The following example shows the contents of a mode-switching vector:
MOV #COMPLETION-ROUTINE,-(SP)
CSM #SUPERVISOR-MODE-ROUTINE ADDRESS

NOTE

When switching from user mode to supervisor mode, all registers of
the referencing task are preserved. All condition codes in the PSW are
saved on the stack before they are cleared and must be restored by the
completion routine.

Supervisor-Mode Library

9-1

9.2 Completion Routines
Mter the subroutine finishes executing, its RETURN statement transfers control
to a completion routine that switches from supervisor mode to user mode. The
completion routine returns program control back to the referencing task at the
instruction after the call to the subroutine. The system library (SYSLIB) contains
the following two completion routines:
$CMPCS

restores only the carry bit in the user mode PSW.

$CMPAL

restores all condition code bits in the user mode PSW.

9.3 Programming Considerations for the Contents of
Supervisor-Mode Libraries
The following requirements must be followed for code in a supervisor-mode
library:
•

Only subroutines entered in the form JSR PC, should be used to invoke the
library. Once within the library, other forms of calls are allowed.

•

The library must not contain subroutines that use the stack pointer (R6) to
pass parameters.

•

Data may be placed on the stack prior to calling a supervisor routine as long
as the data is pointed to by a register other than R6 and that the calling
parameters are removed from the stack only after return to user mode.

•

No asynchronous I/O calls (.WRITAI.READA) can be made from supervisor
mode.

•

If both the library and the referencing task link to a subroutine from the
system library, then the entry point name of the subroutine must be excluded
from the STB file for the library.

•

The library normally does not contain data of any kind (even read-only)
because the user supervisor D-space APRs map the user D-space of the task
by default. This includes user data, buffers, I/O status blocks, Directive
Parameter Blocks (only the $S directive form can be used, because the DPB
for this form is pushed onto the stack at run time).

9.4 Supervisor-Mode Library Mapping
Superv:isor-mode libraries are mapped with the supervisor I-space APRs.
Supervisor D space APRs map, by default, either the user I space in non- 1- and
D-tasks or the user D space in tasks with separate I-and D spaces. An example
of non-I- and D-task mapping is shown in figure 9-1. The MSDS$ directive can be
used to cause the D-space APRs to map supervisor I-space.

9-2 Supervisor-Mode Library

Figure 9-1:

Mapping of a 24K Word Conventional User Task linking to a 16K
Word Supervisor-Mode Library

VIRTUAL

PHYSICAL
MEMORY

APAs

ADDRESS
SPACE

USER
D-SPACE

24K

USER

TASK

I-SPACE

SUPERVISOR
D-SPACE
16K
SUPERVISOR

OKL....--~--

LIBRARY

32K J77lim7J77,~

SUI~;~~~SEOA

16K

li/L'!lLt.IJi!..t4 __
SUPERVISOR
30K

LIBRARY
OK ' - - - - - - ' -_ _

APR MAPPING
USER D-SPACE
USER I-SPACE
SUPERVISOR D-SPACE
SUPERVISOR I-SPACE

9.4.1

mapped as I-SPACE
0-5 map enltre user task
0-5 map entire user task
0-3 map library

Supervisor-Mode Library Data
The supervisor D-space APRs always over-map the user D-space APRs (for
programs built using lID). The supervisor D-space APRs over-map the user
I-space APRs (for programs that are built with I-ID).

9.4.2

Supervisor-Mode Libraries with 1- and D-Space Tasks
1- and D-space tasks may link to supervisor-mode libraries. Instead of mapping to
the entire user task, the supervisor-mode library's D-space APRs map the task's
data space. Because the 1- and D-space task maps its data with the D-space
APRs, the task's D-space APRs are copied into the supervisor-mode library's
D-space APRs. Therefore, the supervisor-mode library maps its own instructions
with supervisor-mode I-space APRs and the task's data with supervisor-mode
D-space APRs (Figure 9-2).

Supervisor-Mode Library

9-3

Figure 9-2:

Mapping of a 40K Word 1- and D-Space Task Linking to an 8K
Word Supervisor-Mode Library

PHYSICAL
MEMORY

APAs

32K

USER
D-SPACE

mrmm1J7J

256K

16K ,,",","r..u..<.I.I..J..=+_--

OK ' - - - - - - - ' - -

40K
1- and DUSER
TASK

32K rrn.,..,.."rrr?77:l\

USER

""+_ _

24K ""'"'"'-'-'-'.........

I-SPACE
USER
INSTRUCTIONS
OK ' - -_ _--.l._ __

32K

SUPERVISOR
D·SPACE

8K
SUPERVISOR

LIBRARY

16K

OK
32K

SUPERVISOR
I-SPACE

8K
OK

30K

SUPERVISOR
LIBRARY

APR MAPPING
USER D·SPACE
USER I-SPACE
SUPERVISOR D-SPACE
SUPERVISOR I·SPACE

0-3 map user data
0-5 map user instructions
0-3 map user data
0-1 map library
ZK·l105·82

9.5 Building and Linking to Supervisor-Mode Libraries
Building and linking to a supervisor-mode library is essentially the same as
building and linking to a conventional resident library (discussed in Chapter 7).
When you build a supervisor-mode library using the TKB command line, 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.

9-4 Supervisor-Mode Library

9.5.1

Relevant TKB Options
Use the following options to build and reference supervisor-mode libraries:
CMPRT

Indicates that you are building a supervisor-mode library and
specifies the name of the completion routine.

RESSUP (SUPLIB)

indicates that your task references a supervisor-mode library.

GBLXCL

excludes a global symbol from the STB file of the supervisormode library.

These options are discussed briefly in the next sections and are fully documented
in Chapter 12.

9.5.2

Mode-Switching Instruction
Mode switching occurs with a hardware instruction available with all processors
that support the CSM instruction. Processors that do not support the hardware
CSM instruction but do support supervisor mode (that is, the PDP-11/45, 11150,
11/55 and 11170) have the CSM instruction emulated by RSTSIE. Throughout the
remainder of the chapter, supervisor-mode libraries are referred to as Change
Supervisor-Mode (CSM) libraries.

9.5.2.1

Required Memory Layouts for Supported CSM Instructions
Only two forms of the CSM instruction are supported by Digital software:
CSM

# address

(7027)

CSM

(sp)+

(7026)

Any other form of the instruction does not put the target address where the vector
software expects. Under normal uses, the TKB will supply the CSM as part of
the vectoring.

9.5.2.2

The CSM Library Dispatching Process
When you build the referencing task and specify the SV or SW argument to the
RESSUP or SUPLIB option, TKB includes a 4-word context-switching vector for
each call to a subroutine in the library. This has been very generally discussed in
Section 9.2. This section discusses the CSM library vector in more detail.
CSM mode switching occurs as follows:
•

The vector is entered with the return address on top of the stack (TOS).

•

The vector pushes the completion-routine address on the stack.

•

A CSM instruction is executed with the supervisor-mode entry point as the
immediate addressing mode parameter.

The CSM instruction executes the following steps either through hardware action
or software emulation:
•

Evaluating the source parameter and storing the entry point address in a
temporary register

•

Copying the user stack pointer to the supervisor stack pointer

Supervisor-Mode Library

9-5

•

Placing the current PSW and PC on the supervisor stack, clearing the condition codes in the PSW

•

Pushing the entry point address on the supervisor stack

•

Placing the contents of location 10 in supervisor I-space into the PC and
transferring execution to that address in supervisor mode

The stack looks like this when the processor begins to execute at the contents of
virtual 10 in supervisor mode:
higher memory address
user sp ----> return address
completion routine address in super mode
PSW
PC
super sp ---> entry point address of routine in super mode
lower memory address

Because the CSM library mode-switching vector processor begins executing at the
contents of virtual 10 in supervisor mode, the completion routine must be located
at virtual O. In this way, virtual location 10 is within properly mapped memory.

9.6 CSM libraries
This section discusses how you build and link to CSM libraries. It also shows
an extended example of building and linking to a CSM library and explains the
context-switching vectors and completion routines for CSM libraries.

9.6.1

Building a CSM library
You can indicate to the Task Builder that you are building a CSM library by
specifying the name of the completion routine as the argument for the CMPRT
option. This option places the name of the completion routine into the library's
STB file. Link the completion routine, either $CMPAL or $CMPCS, located in
LB:SYSLIB.OLB, as the first input file. Although the completion routines are
located in the system library (which is ordinarily referenced by default), you must
explicitly indicate it and link it as the first input file. You must also specify in the
PAR option a base of 0 for the partition in which the library will reside. These
two steps locate the completion routine at virtual 0 of the library's virtual address
space. This placement is a requirement.
Specify the name of any global symbols that you would like to exclude from the
library's STB file as the argument to the GBLXCL option. You must exclude from
the STB file of a supervisor-mode library any symbol defined in the library that
represents the following:

9-6

•

An entry point to a subroutine that uses the stack pointer to address parameters

•

An entry point to a subroutine mapped in user mode that the referencing user
task calls and also exists in the CSM library

Supervisor-Mode Library

The following sample TKB command sequence builds a CSM library called
SUPER in directory [30,55] on device SY:
TKB> SUPER/-HD/LI/PI,SUPER/MA,SUPER=
TKB>LB:SYSLIB/LB:CMPAL,SY: [30,55]SUPER
TKB>/
Enter Options:
TKB>STACK=O
TKB>PAR=GEN:0:2000
TKB>CMPRT=$CMPCS
TKB>GBLXC=$SAVAL
TKB>//

The second line in this example is the key line. The first LB:SYSLIB indicates
the .OLB file from which the ILB:CMPAL is to be loaded. Note the different
meanings for the LB:s, and that by locating the CMPAL before the actual library
code, the contents of location 10 in supervisor mode is assured.
RSTSIE requires the output of the Task Builder to be converted to a loadable
library by the MAKSIL program (refer to the RSTS / E Programmer's Utilities
Manual for additional information on MAKSIL). An example of MAKSIL is shown
here:
$ run $maksil
MAKSIL V10 . 0-L
Resident Library name? SUPER
Task-built Resident Library input file <SUPER.TSK> ?
Include symbol table (Yes/No) <Yes> ?
Symbol table input file <SUPER . STB >?
Resident Library output file <SUPER . LIB> ?
SUPER built in 1 K-words, 21 symbols in the directory
SUPER.TSK renamed to SUPER.TSK <40>

The library is built without a header or stack, like all shared regions. It is
position-independent and has only one program section named .ABS. The ILl
switch in TKB accomplishes this, eliminating program section name conflicts
between the library and the referencing task.
The completion routine module CMPAL is specified first in the input line. The
library will run in partition GEN at 0 and is not more than lK words. These are
two aspects of building supervisor-mode libraries specific to these libraries: the
completion routine must be linked first and must reside at virtual O. (Why the
CSM library must reside at virtual 0 is discussed in the next section.)
The CMPRT option specifies the global symbol $CMPCS, which is the entry
point of the completion routine. Note that the name for the system library object
module is CMPCS and its corresponding global entry symbol is $CMPCS.
The GBLXCL option excludes $SAVAL from the library's STB file because the
user task must reference a copy of $SAVAL that is mapped with user mode APRs.

Supervisor-Mode Library

9-7

9.6.2

Linking to a CSM Library
If your task links to a user-owned CSM library, use the RESSUP option. If your
task links to a system-owned CSM library, use the SUPLIB option. These options
tell TKB that the task will link to a supervisor-mode library. The option takes up
to three arguments, as follows:

•

The file specification (RESSUP option) or name (SUPLIB option) of the library

•

A switch that tells TKB whether to use system-supplied, mode-switching
vectors

•

A switch that determines whether the library is to be attached read/write or
read-only

•

For position-independent libraries, an APR that must be APR 0 so that the
library's completion routine is mapped at virtual 0

This information enables TKB to find the STB file for the CSM library, include a
4-word mode-switching vector within the user task for each call to a subroutine
within the library, and correctly map the library at virtual 0 in the library image.
The following examples of TKB command sequences build a task named REF,
which references the library SUPER that you built in Section 9.6.1:
TKB> REF, REF=REF
TKB> /

Enter Options:
TKB> RESSUP=SUPER/ SV: 0
TKB> / /

This sequence tells TKB to include in the logical address space of REF a userowned, supervisor-mode library named SUPER. TKB includes a 4-word modeswitching vector within the user task for each call to a subroutine within the
library. The CSM library is position-independent and is mapped with APR O.
TKB> REF /ID/DA, REF=REF
TKB> /

Enter Options:
TKB> RESSUP=SUPER/ SW: 0
TKB> / /

This sequence does the same function except that it also includes ODT for use in
debugging the task together with the CSM library. Note the lID is required to
select the proper ODT version that contains supervisor-mode commands. The /SW
switch attaches the CSM library read/write so that breakpoints may be placed in
the library. The CSM library must also be INSTALLed with read/write access for
ODT to be able to make changes in it.

9.6.3

Example of a CSM Library and Building a Task
This example shows you the code and maps and the TKB command sequence for
building with a CSM library. Example 9-1 shows the code for the library SUPER
and Example 9-2 shows its accompanying map. Example 9-3 shows the code
for the completion routine $CMPCS that is linked into SUPER from the system
library. Example 9-4 shows the code for referencing task TSUP, and Example 9-5
shows its accompanying map.

9-8

Supervisor-Mode Library

Example 9-1:
.TITLE
.!DENT
SORT: :
CALL
TST
MOV
MOV
MOV
BEQ
MOV
DEC
10$:
MOV
MOV
20$:
TST
CMP
BLE
MOV
MOV
MOV
30$:
DEC
BGE
DEC
BLE
TST
BR
40$:
RETURN
SEARCH: :
CALL
CMP
BNE
MOV
MOV
MOV
MOV
BEQ
MOV
MOV
10$:
CMP
BEQ
BMI
DEC
BNE
20$:
MOV
RETURN
30$:
SUB
INC
MOV
RETURN
.END

Code for SUPER.MAC
SUPER
/01/
$SAVAL
(R5)+
(R5)+,RO
(R5)+,R4
(R4) ,R4
40$
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
IF NO ARGUMENTS

R5,RO
R4,R3

COpy
COPY LENGTH OF LIST

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

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

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

$SAVAL
#4, (R5) +
20$
(R5)+,RO
(R5)+,R1
(R5)+,R2
(R2) ,R2
20$
(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
IF NO ARGUMENTS
ADDRESS OF RETURNED VALUE
COPY LENGTH

(RO), (R1) +
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

#-1, (R5)

END OF LIST PASS BACK ERROR

R2,R3
R3
R3, (R5)

NUMBER FOUND - GET INDEX INTO LIST
RETURN INDEX

Note the use of the routine $SAVAL in both the Library SUPER.MAC and the
main program TSUP.MAC in Example 9-4. This double usage is the reason the
global is excluded from the library's STB with the GBLXCL option.

Supervisor-Mode Library

9-9

Example 9-2:
SUPER.TSK

Memory Allocation Map for Super
Memory Allocation Map TKB M43.00
11-AUG-90
15:41

Page 1

Partition name
GEN
Identification
03.01
Task UIC
[30,55]
Task attributes: -HD,PI
Total address windows: 1.
Task image size
128. words
Task address limits: 000000 000343
R-W disk blk limits: 000002 000002 000001 00001.
Root segment: CMPAL
R/W mem limits: 000000 000341 000342 00226.
Disk blk limits: 000002 000002 000001 00001.
Memory allocation synopsis:
Section

Title

Ident

File

00226.
00096. CMPAL
00096 . SUPER
00034. SAVAL

03.01
01
00

SYSLIB.OLB
SUPER.OBJ
SYSLIB.OLB

------.BLK.: (RW,I,LCL,REL,CON) 000000
000000
000140
000300

000342
000140
000140
000042

Global symbols:
SEARCH 000220-R
$SAVAL 000300-R

SORT
$SRTI

000140-R
000002-R

$CMPAL

000022-R

Task builder statistics:
Total work file references: 300.
Work file reads: O.
Work file writes: O.
Size of core pool: 6466. words (25. pages)
Size of work file: 1024. words (4. pages)
Elapsed time:00:00:08

9-10

Supervisor-Mode Library

$CMPCS 000l10-R

Example 9-3:

Completion Routine $CMPCS from SYSLlB.OLB

.TITLE
.!DENT

CMPAL
/0204/

COPYRIGHT (c) 1987,1989 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD
MASSACHUSETTS. ALL RIGHTS RESERVED.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED
AND COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE
AND WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS
SOFTWARE, OR ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR
OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON. NO TITLE TO AND
OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED.
THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTWARE ON EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL .
. ENABL

This module supports the "new" transfer vector format generated
by the Task Builder for entering super mode libraries. This
format is optimized for speed and size and supports user data
space tasks.
The CSM dispatcher routine and the standard completion routines
$CMPAL and $CMPCS are included in this module due to the close
interaction between them.
**-CSM Dispatcher-Dispatch CSM entry
This module must be linked at virtual zero in the supervisor-mode
library. It is entered via a four word transfer vector of the
form:
MOV
CSM

tcompletion-routine,-(SP)
troutine

Note: Immediate mode emulation of the CSM instruction is required
in the Executive for II/70s.
The CSM instruction transfers control to the address contained in
supervisor mode virtual 10. At this point the stack is the
following:
(SP)
2 (SP)
4(SP)
6(SP)
10(SP)

Routine address
PC (past end of transfer vector)
PSW with condition codes cleared
Completion-routine address
Return address

(continued on next page)

Supervisor-Mode Library

9-11

Example 9-3 (Cont.):

Completion Routine $CMPCS from SYSLlB.OLB

A routine address of 0 is special-cased to support return to
supervisor mode from a user mode debugging aid (ODT).
In this
case stack is the following:
(SP)
2(SP)
4(SP)
6(SP)
10(SP)

zero
PC from CSM to ,be discarded
PSW from CSM to be discarded
Super mode PC supplied by debugger
Super mode PSW supplied by debugger

To allow positioning at virtual zero, this code must be in the
blank PSECT which is first in the TKB's PSECT ordering .
• PSECT
.ENABL

LSB

Debugger return to super mode entry. Must start at virtual zero
CMP

(SP)+, (SP) +

; Clean off PSW and PC from CSM

**-$SRTI-SUPER mode RTI
This entry point performs the necessary stack management to
allow an RTI from super mode to either super mode or user mode.
In this case, the stack is the following:
(SP)
2(SP)

Super mode PC
Super mode PSW

$SRTI:: TST
2(SP)
; Returning to user mode?
BR
70$
; Join common code
CSM transfer address, this word must be at virtual 10 in super
mode
. WORD

CSMSVR

CSM dispatcher entry

Dispatch CSM entry
CSMSVR: MOV
JMP

6 (SP) , 2 (SP )
@(SP)+

Set completion routine address for RETURN
Transfer to super mode library routine

**-$CMPAL-Completion routine which sets up NZVC in the PSW
Copy all condition codes to stacked PSW.
(SP)
2(SP)
4(SP)

Current stack:

PSW with condition codes cleared
Completion routine address (to be discarded)
Return address

(continued on next page)

9-12 Supervisor-Mode Library

Example 9-3 (Cont.):
$CMPAL: :BPL
BNE
BVC
BIS
BR
BIS
10$:
BR
20$:
BVC
BIS
BR
30$:
BIS
BR
BNE
40$:
BVC
BIS
BR
BIS
50$:
BR
BVC
60\:
BIS

Completion Routine $CMPCS from SYSLlB.OlB

40$
20$
10$
#16, (SP)
$CMPCS
#14, (SP)
$CMPCS
30$
#12, (SP)
$CMPCS
#10, (SP)
$CMPCS
60$
50$
*6, (SP)
$CMPCS
H, (SP)
$CMPCS
$CMPCS
*2, (SP)

Set NZV
Set NZ

Set NV
Set N

Set ZV
Set Z

Set V

**-\CMPCS-Completion routine which sets up only C in the PSW
Copy only carry to stacked PSW.
(SP)
2(SP)
4(SP)
$CMPCS: :ADC
MOV
MOV
70$:
BPL
MOV
ADD
MTPI
80\:
RTT
. DSABL
.END

Current stack:

PSW with condition codes cleared
Completion routine address (to be discarded)
Return address
(SP)
4(SP),2(SP)
(SP) +, 2 (SP)
80$
*6,-(SP)
SP, (SP)
SP

Set up carry
Set up return address for RTT
And PSW. Returning to super mode?
If PL yes
Number of bytes for (SP) , PSW, and PC
Compute clean stack value
Set up previous stack pointer
Return to previous mode and caller

LSB

Supervisor-Mode Library

9-13

Example 9-4:

Code for TSUP.MAC

.TITLE
. !DENT
. MCALL
WRITE: QIOW$
READIN: QIOW$
IARRAY: . BLKW
.BLKW
LEN:
IART:
.BLKW
INDEX:
. WORD
OUT:
. BLKW
ARGBLK:
EDBUF:
. BLKW
FMT1:
.ASCIZ
FMT2:
.ASCIZ
FMT3:
.ASCIZ
.ASCIZ
FMT4:
FMT5:
.ASCIZ
. EVEN
START:
MOV
MOV
5$:
CLR
DEC
BNE
MOV
MOV
10$:
MOV

TSUP
/01/
QIOW$,DIR$,QIOW$S
IO.WVB,5,1",,<OUT,,40>
IO.RVB,5,1",,<OUT,5>
12 .
1
1
0
100 .
10 .
/%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/

#IARRAY,RO
#10,R1

GET ADDRESS OF ARRAY
SET LENGTH OF ARRAY

(RO) +
R1
5$
#IARRAY, RO
#INDEX,R2

INITIALIZE ARRAY
LOOP

#FMT1,R1

FORMAT SPECIFICATION (ADDRESS
OF INPUT STRING)
GET INDEX

MOV
INC
CALL
CALL
MOV
BEQ
INC
CMP
BNE

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

MOV
MOV
MOV
MOV
MOV
MOV
CALL

(R2) ,LEN
#ARGBLK,R5
#2, (R5) +
#IARRAY, (R5) +
#LEN, (R5)
#ARGBLK,R5
SORT

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

IF NE YES

20$:
CALCULATE LENGTH OF ARRAY
GET ADDRESS OF ARGUMENT BLOCK
NUMBER OF ARGUMENTS
PUT ADDRESS OF ARRAY

SORT ARRAY

;+
;Task Builder replaced call to SORT subroutine in SUPLIB with
;4-word context switching vector. Flow of control switches to SUPLIB
;via the vector and back via the completion routine $CMPCS. TSUP
;continues executing at the next instruction.
;-

CLR
MOV

R2
#IARRAY, RO

GET ARRAY ADDRESS

(continued on next page)

9-14

Supervisor-Mode Library

Example 9-4 (Cont.):

Code for TSUP.MAC

30$:
INC
MOV
MOV
MOV
CALL
CMP
BLT
MOV
CALL
CALL
MOV
MOV
MOV
MOV
MOV
MOV
MOV
CALL

R2
R2,EDBUF
(RO)+,EDBUF+2
tFMT5,R1
PRINT
R2,LEN
30$
tFMT2,R1
PRINT
READ
tARGBLK,R5
H, (R5)+
UART, (R5)+
UARRAY, (RS) +
tLEN, (R5)+
UNDEX, (R5)
tARGBLK,RS
SEARCH

INCREMENT INDEX
GET INDEX FOR PRINT
GET CONTENTS OF ARRAY
GET ADDRESS OF FORMAT SPECIFICATION
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

;Call to SUPLIB for SEARCH subroutine.
TST
BLT
MOV
MOV
MOV
CALL
BR

INDEX
40$
IART,EDBUF
INDEX,EDBUF+2
tFMT3,R1
PRINT
100$

WAS NUMBER FOUND?
IF LT NO
GET NUMBER LOOKING FOR
GET ARRAY NUMBER
GET FORMAT ADDRESS

MOV
MOV
CALL

tFMT4,R1
IART,EDBUF
PRINT

GET FORMAT ADDRESS
GET NUMBER

CALL

$EXST

EXIT WITH STATUS

CALL
MOV
MOV
CALL
MOV

$SAVAL
SAVE ALL REGISTERS
tOUT,RO
ADDRESS OF OUTPUT BLOCK
tEDBUF,R2
START ADDRESS OF ARGUMENT BLOCK
$EDMSG
FORMAT MESSAGE
R1,WRITE+Q.IOPL+2 ; PUT LENGTH OF OUTPUT
BLOCK INTO PARAMETER BLOCK
tWRITE
; WRITE OUTPUT BLOCK

DONE

40$:

100$:
PRINT:

DIR$
RETURN
READ:
CALL
DIR$
MOV
CALL
MOV
RETURN

$SAVAL
tREAD IN
tOUT,RO
$CDTB
R1,IART

.END

START

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

TSUP prompts you to enter numbers at your terminal. It calls a subroutine
in SUPER to sort the numbers. Then it displays the numbers you entered as
array entries and prompts you to request a number to search for. TSUP calls a
subroutine in SUPER.LIB to search for the number. Finally, TSUP indicates that
either the number was not found or the array location in which the number is
stored.

Supervisor-Mode Library

9-15

Example 9-5:
TSUP.TSK

Memory Allocation Map for TSUP
Memory allocation map TKB M43.00
11-AUG-90
15:41

Page 1

Partition name
GEN
Identification
01
Task UIC
[30,55]
Stack
limits: 000274 001273 001000 00512.
PRG xfr address: 002130
Total address windows: 2.
Task image size
1344. words
Task address limits: 000000 005133
R-W disk blk limits: 000002 000007 000006 00006.

*** Root segment: TSUP
R/W mem limits: 000000 005133 005134 02652.
Disk blk limits: 000002 000007 000006 00006.
Memory allocation synopsis:
Section
. BLK . : (RW,I,LCL,REL,CON)
CMPAL : (RW,I,LCL,REL,CON)
PUR$D : (RO,I,LCL,REL,CON)
PUR$I : (RO,I,LCL,REL,CON)
$$RESL : (RO,I,LCL,REL,CON)
$$SLVC : (RO,I,LCL,REL,CON)

Title
001274 002334 01244.
001274 001234 00668. TSUP
000000 000474 00316.
003630 000076 00062.
003726 000752 00490.
004700 000212 00138.
005112 000020 00016 .

TSUP.TSK;1 Memory Allocation Map TKB M43.00
11-AUG-90
15:41

Ident

File

TSUP.OBJ

Page 2

*** Task builder statistics:
Total work file references: 2477.
Work file reads: O.
Work file writes: O.
Size of core pool: 6988. words (27. pages)
Size of work file: 1024. words (4. pages)
Elapsed time:00:00:05

9.6.3.1

Building the Library SUPER
To build SUPER in directory [30,55] on device SY:, use the following TKB com-

mand sequence:
TKB> SUPER/-HD/LI/PI,SUPER/MA,SUPER=
TKB> LB:SYSLIB/LB:CMPAL,SY: [30,55]SUPER
TKB> /
Enter Options:
TKB> STACK=O
TKB> PAR=GEN:0 : 2000
TKB> CMPRT=$CMPCS
TKB> GBLXCL=$SAVAL
TKB> / /

9-16 Supervisor-Mode Library

$ run $maksil
MAKSIL V10.0-L
Resident Library name? SUPER
Task-built Resident Library input file <SUPER.TSK> ?
Include symbol table (Yes/No) <Yes> ?
Symbol table input file <SUPER.STB> ?
Resident Library output file <SUPER . LIB> ?
SUPER built in 1 K-words, 21 symbols in the directory
SUPER . TSK renamed to SUPER.TSK<40>

SUPER is built without a header or stack. It is position-independent and has
only one program section, named .BLK. The ILl switch eliminates program
section name conflicts between the library and the referencing task.
The completion routine module CMPAL is specified first in the input line. The
library will run in partition GEN at 0 and is not more than lK words.
The GBLXCL option excludes $SAVAL from the library's STB file. Exclude
$SAVAL from the STB file because the referencing task, TSUP, also calls $SAVAL.
If TSUP finds $SAVAL in the STB file of SUPER, it will not link a separate
copy of $SAVAL into its task image from the system library. If TSUP could not
link to a copy of $SAVAL that is mapped through user APRs, TSUP would call
$SAVAL as a subroutine residing within the supervisor-mode library but without
the necessary mode-switching vector and completion routine support. This option
forces TKB to link $SAVAL from the system library into the task image for TSUP.
The memory allocation map in Example 9-2 shows the following information:

9.6.3.2

•

SUPER begins a t vir t ual o.

•

The completion routine, $CMPAL, is linked into the library from the system
library at virtual o.

•

The entry point $CMPAL is located at virtual 22, SEARCH is located at 220,
and SORT is located at 140. All of these entry points are relocatable.

Building TSUP

Use the following TKB command sequence to build a task, TSUP, that links to
SUPER:
TKB> TSUP,TSUP =TSUP
TKB> I
Enter Options:
TKB> RES SUP=SUPERI SV: 0
TKB> II

This command sequence tells TKB to include in the logical address space of TSUP
a user-owned supervisor-mode library named SUPER. TKB includes a 4-word
mode-switching vector within the task image for each call to a subroutine within
the library. The library is position-independent and is mapped with supervisor
I-space APR O. This is a requirement for CSM libraries because the CSM library
expects to find the entry point of the completion routine at location 10.
The memory allocation map for TSUP in Example 9-5 shows the following information:
•

$CMPAL is linked from the STB file of the library and begins at location o.

•

The mode-switching vectors begin at 5112 and are 16 bytes in length. This
means that TSUP calls subroutines within the library two times (four words
for each vector).
Supervisor-Mode Library

9-17

<I>

<II

9.6.3.3

The initiation routine $SUPL is located at 4700.
The SEARCH and SORT subroutines that were located at virtual 220 and
140, respectively, in the virtual address space of SUPER have been relocated
to the mode-switching vectors residing at 5112 and 5122, respectively, in
TSUP.
The system library module SAVAL, containing $SAVAL, has been linked into
the task image instead of including $SAVAL from the library's STB file.

Running TSUP

Mter building SUPER and TSUP as indicated in the task-build command sequence discussed previously, install the library SUPER and run TSUP. TSUP
prompts you for the position in which to store the number in the array:
ARRAY (x)
x

Enter a number. TSUP stores the number in the array and prompts you again
for a number. This continues until you have entered a 0, an invalid number, or
10 numbers. Then TSUP cans the SORT routine in SUPER.
When you enter a number, TSUP cans the SEARCH routine in SUPER. TSUP
then outputs a message indicating whether the number was in the array.

9.6.4

Passing Parameters Using Stack Space
Note also the existence of the two independent stack pointers: (NOT stacks) one
for user mode and one for supervisor mode. The fact that a variable amount of
additional data is placed on one stack and not the other by the system is why the
SP cannot be used as a pointer to parameters. The following example shows a
method of properly using the stack to pass parameters to and from a CSM library
routine:
In the user mode program:

MOV
MOV
MOV
MOV
JSR
ADD

MOV

RO,-(SP)
;make a register available
DATA1,-(SP) ;parameters needed by CSM library routine
DATA2,-(SP) ;placed on stack as a packet
SP,RO
;put address of packet in another register
PC, SUPER_ROUTINE ;transfer to CSM library routine
;on return to user mode
;remove data packet from user stack
#4,SP
;restore register
(SP)+,RO

In the CSM library code:
SUPER ROUTINE:
MOV
MOV

(RO), R2
2(RO) ,R3

;put DATA2 in R2
;put DATAl in R3

Data may be returned from a CSM library in the same manner as long as the
data packet was reserved on the stack and addressed in the user mode prior to
the can to the CSM library routine.

9-18

Supervisor-Mode Library

9.7 Using SupervisoraMode libraries as User-Mode Resident
libraries
Supervisor-mode libraries can double as conventional resident libraries. For
position-independent supervisor-mode libraries, rebuild the referencing task using
the RESLIB option instead of the RESSUP option. Indicate the first available
user mode APR that you want to map the library. For CSM libraries, this will
always change because you cannot map a shared region with APR O. You do not
have to rebuild the library.
For absolute supervisor-mode libraries, rebuild the referencing task using the
RESLIB option instead of the RESSUP option. Rebuild the library only if the
beginning partition address in the PAR option is incompatible with the address
limits of your referencing task.
Once installed, the library can be used in either mode at any time. All APR
relocation is done when the task that references the library is built. There is no
change to the library itself.

9.8 Multiple Supervisor-Mode libraries
A user task can reference multiple supervisor-mode CSM libraries. However, all
the CSM libraries must use the completion routine that begins at virtual 0 in
supervisor-mode instruction space.

9.9 linking Supervisor-Mode libraries
You cannot link supervisor-mode libraries together, and you cannot link a
supervisor-mode library to a user-mode library. Calling a user-mode library is
not possible because its code is not mapped through the I-space APRs while in
the supervisor-mode library. However, you can link user mode libraries to a
supervisor-mode library.

9.10 Writing Your Own Vectors and Completion Routines
You can write your own mode-switching vectors and completion routines. This
may be necessary for threaded code. If you use your own vectors, build them into
the task and use the I-SV or the I-SW switch on the RESSUP or RESLIB option
when you build the referencing task. If you create your own completion routines,
write your completion routine to resemble the system-supplied completion
routines (see Example 9-3) as much as possible. If you do not retain the last
three lines of code as indicated in Example 9-3, the task may not complete if
the Executive processes an interrupt before the switch back to user mode has
completed.
The debugger ODT expects the presence of the system-supplied completion
routines to handle breakpoints and all other traps while in supervisor mode.
Lack of this code may cause the task to abort should a trap occur.

Supervisor-Mode Library

9-19

9.11

Overlaid Supervisor-Mode Libraries
It is possible to use overlaid supervisor-mode libraries. However, the following

restrictions must be noted when building these libraries:
•

The completion routine for the library must be in the root.

•

Only one level of overlaying is allowed (see Figure 9-3).

Figure 9-3:

Allowed

Overlay Configuration Allowed for Supervisor-Mode Libraries

Allowed

ABC

Not Allowed

A B

C D

9.12 Using ODT to Debug eMS library
The use of ODT with a CSM library is the same as with other types of tasks
except for following:

9-20

•

The CSM library must have been installed as RW and 1 user.
INSTALILIBINOREAD_ONLYINOSHAREABLE file[ppn]

•

When the task that uses the CSM library is Task built, the parameters
change:
+

Indicate the inclusion of the proper ODT.OBJ file by using the IDA and
lID switches.

Indicate that the library should be loaded ReadlWrite by replacing the
supervisor-mode vector switch ISV:O with the ISW:O switch.

•

Once in ODT, the Z command switches ODT to the supervisor mode and the
U command switches it back to user mode.

•

Only the UI, UD and ZI spaces are defined in ODT. Any attempt to use the
ZD (supervisor data) space will result in the nonexistent memory indicator
from ODT. However, the data in supervisor D-space is mapped the same as
the user data space and therefore is available using the UD command.

Supervisor-Mode Library

Breakpoints and single step work the same as in user space. There is,
however, no indicator as to which space, Z or U, the breakpoint was in. It is
the task of the user to determine or keep track of which space the program is
in when in ODT.

ODT operating with supervisor mode requires the use of the Digital systemsupplied supervisor-mode completion routines that handle the special mode
switching needs of ODT.

9,13 Trap Handling with Supervisor Libraries
Although asynchronous I/O calls (READA \ & WRITA) are illegal from a task that
is also using supervisor mode, other forms of traps may require handling by a
task that is using supervisor mode.
The two system asynchronous traps, FPP exception and Control-C interception,
as well as all forms of Synchronous Service Traps (88Ts) are permitted. The trap
service routines for these may be located in either user or supervisor mode.
If the service routines reside in supervisor mode, they must adhere to additional

requirements that their user mode counter-parts do not need.

9.13.1

The routine must exit using either the SSTX$ or ASTX$ cans. Whereas in
user mode, only service routines are allowed to clean the PC \ & PSW off
the stack and continue without returning, tasks using supervisor mode must
use an exit call. Note that the hardware prohibits an RTI instruction from
returning a task to supervisor mode from a service routine in user mode.

•

Routines located in supervisor space usually must obey all the rules of
supervisor library routines such as not calling user mode routines and having
no data within the code.

locating Service Routines
The task informs RSTSIE in which space the service routine is at the time the
respective service vectors are set up. The following calls set up the trap service
vectors for the task:
FPPA$
SCCA$
SVTK$
SVDB$

9.13.1.1

Floating point exception
Control-C interception
SST trap vector table
SST debugging trap vector table

FPPA$ AND SCCA$

In the cases of FPPA$ and SCCA$, the task issues a single-address vector. Which
space the service routine resides in is indicated by bit 0 of the vector. If it is zero,
the service routine is in user space. If the hit is 1 (an odd address vector), the
routine is in supervisor space.
9.13.1.2

SVTK$ and SVDB$

In the SVTK$ and SVDB$ cans, the task issues a list of vectors that will be
associated with the different events (BIT, for example). The bit 0 in each of the
individual service routine vector addresses indicates which mode that routine is
in, but in a different way from FPPA$ and SCCA$.

Supervisor-Mode Library 9-21

An even vector entry causes the SST routine to be executed in the same mode
(either user or supervisor) that the processor was in when the SVTK$ or SVDB$
call was issued. An odd vector entry causes the SST routine to be executed in
the other mode. For example, if the processor was in supervisor mode when an
SVTK$ was issued and the vector was odd (bit 0 set), the SST routine is executed
in the user mode. This method of designation of service routine location is the
same as RSX-llfM-Plus. This method allows the individual SSTs to be different
modes at the same time (BPT in user and address trap in supervisor). Bit 0,
which is the flag(s), is a member of the vector list, not the address pointer to the
vector list.

9.14 Building to a Supervisor-Mode RMS Library
On the RSTSIE systems that support supervisor mode, you may choose to use
RMSRES as a supervisor-mode library instead of user mode. Because this
configuration uses two otherwise idle supervisor-mode APRs to map most of the
RMS-ll code, the impact of the RMS-ll code on your user mode virtual address
space is reduced to the absolute minimum. There also may be slight performance
advantages over the clustered RMS-ll configuration.
To use RMSRES as a supervisor-mode library, use the following sequence of
commands:
TKB> command string
TKB> /
ENTER OPTIONS :
TKB> RESSUP=RMS$ :RMSRES/SV: 0
TKB> / /

The following modules must be included in the root of the task:
LB:RMSLIB/LB:ROEXSY : ROAUTS:ROIMPA

This can be done by either adding it to the task builder command string or by
adding @LB:RMSSLX in the users's ODL file.
If the task requires global definitions of the user-visible RMS-ll symbols, the
following should also be included: LB:RMSLIBILB:RMSSYM
To include remote access (DAP) support while also using RMSRES as a
supervisor-mode library, several options are available. Use the module ROAUTS
for task residen t DAP support. For resident library DAP support, use the
module ROAULS and specify DAPRES as a LIBR or CLSTR option in the
task builder command sequence. For overlaid DAP support, use the module
ROAUOS. The following example includes DAP using the resident library support:
LB:RMSDAPILB:ROAULS

This can be done either by adding it to the task builder command string or by
adding @LB:DAPSLX in the users's ODL file .
If inconsistencies are found in the modules at execution time, a BPT trap will be
generated and the value 175744 (the error code ER$LIB) will be in RO. This can
happen if not all segments of the library are installed or if the version numbers of
one or more segments do not match the root segment, the RMSDAP code, or the
task itself.

9-22

Supervisor-Mode Library

9.15 Map Supervisor D-Space
The Map Supervisor D-Space directive allows the issuing task to change the
mapping of its supervisor-mode D-space APRs. This directive also provides
information about the current mapping of the tasks supervisor-mode D-space
APRs and about the library's current mode.
When supervisor-mode library code is executing, the supervisor-mode I-space
APRs map supervisor-mode instruction space. However, the supervisor mode
D-space APRs normally map the user mode D-space. Code that resides in a
supervisor-mode library may need to use its instruction space as data space as
well for such items as error messages. The Map Supervisor Data Space directive
allows such code to over map the supervisor D-space and the supervisor I-space
on an APR by APR basis. This over mapping is the case even for tasks built as
separate 1- and D-space in the user space.
The Map Supervisor D-space directive allows the task to specify a 7-bit mask that
determines which space each supervisor D-space APR will use. The mask value
contains one bit for each APR beginning at APR1. Supervisor-mode D-APRO must
over map user mode D-APRO at all times and, therefore, is not included in the
mask value.
On the return from the MSDS$ call, the current supervisor-mode D-space
mapping mask is returned along with the high byte (mode bits) of the PSW. If
bit 15 of the mask value is set to 1 on the call no change occurs to supervisor
mapping but existing mapping is returned.
The MSDS$ call is designed to be made from the library whose mapping it is
intended to alter. This can allow a library to determine for itself which mode it is
in from the PSW mode bits returned. Further, if the MSDS$ call is issued from
user mode rather than supervisor mode, no mapping change occurs; however, the
mapping data and PSW are returned. Note that the MSDS$ call returns ONLY
the supervisor-mode mapping status; if the library is in user mode, no useful
mapping data is returned. Normally, a library in user mode will have its D-space
already mapped to user mode D-space unless the task builder or the program has
taken some overt action to remap the D-space.
Digital recommends that all required data be placed at the highest addresses in
the library. Not only does this remove it from the APRO restriction in supervisor
mode, but also allows the library to make proper use of the EXTM$ directive.
(See RSTS / E System Directives Manual if used in the user mode.)
Fortran Call

Not supported.
Macro Call

MSDS$

mask

Macro Expansion

.MACRO
.BYTE
.WORD
.ENDM

MSDS$
201.,2
mask

mask
;MSDS$ DIC code, DPB size= 2 words

Supervisor-Mode Library

9-23

Parameters
A 7-bit APR mask plus the following action flag infonnation:
bit 15

Flag: if =0, then set mapping; if =1, then report current supervisor-mode
D-space mapping (no changes); if issued from user mode, value forced to
=1

bit 14

APR 7 mapping switch

bit 13

APR 6 mapping switch

bit 12

APR 5 mapping switch

bit 11

APR 4 mapping switch

bit 10

APR 3 mapping switch

bit 9

APR 2 mapping switch

bit 8

APR 1 mapping switch

bits 0-7

Zero on input, set to PSW high byte on return

Note that if bits 8 through 14 equal 0, super D-space = user D-space. If they
equal 1, super D-space = super I-space.

Error Codes
IE.SDP

DIC or DPB size invalid

Example
The following code could exist in a supervisor library to print error messages:
TST
BPL

(RO)
DATAOK

;test some piece of user data
;skip next if data ok

MSDS$S
MOV
MOV

uOOOOO
$DSW,RO
RO,-(SP)

;get current mapping state

BIS
MSDS$S

HOo, RO
RO

;update mask to map APRl to super
;change the mapping

MOV
CALL

#MESSAG,Rl
OUTMSG

MOV
MSDS$S

(SP) +, RO
RO

;pointer to error message which is data
;call a routine in super mode to output
;text data message.
;get back the original mapping state
;now back to the original state

;save for future restoration

.. etc ...

This is created somewhere in APR 1 of the supervisor library:
MESSAG:

9-24

Supervisor-Mode Library

.ASCIZ

IError in datal

Part IV
Reference Section

Chapter 10

Task Builder Command Line Format

10.1

Running the Task Builder
To run the Task Builder, type:

RUN $TKB
Or, if the system manager has installed TKB as a concise command language
(eeL) command, you can type:

TKB
The Task Builder responds with the prompt TKB> and you type a command. If
TKB has been installed as a eeL command, you can type TKB and the command
on the same line:
TKB command

10.1.1

Command Line
The Task Builder produces up to three files as output from its analysis of the
object files you specify as input. The general form of the command is:
task-file,map-file,symbol-file=input-file, ... ,input-file
task-file

The file specification you give to the executable file produced by the Task
Builder. If you do not want this file produced, type the comma delimiter.
If you leave off the file type from the file specification, the Task Builder
supplies a default type of .TSK

map-file

The file specification you give to the memory map file produced by the Task
Builder. If you do not want this file produced, type the comma delimiter.
If you leave off the file type from the file specification, the Task Builder
supplies a default type of .MAP.

symbol-file

The file specification you give to the symbol-table file produced by the Task
Builder. If you do not want this file produced, simply leave out the file
specification. If you leave off the file type from the file specification, the
Task Builder supplies a default type of .STB.

Task Builder Command Line Format

10-1

input-files

The input to the Task Builder. For a simple (nonoverlaid) build, these are
the object files produced from the assembly or compilation of your program
and subroutines, plus disk library files containing subroutines needed to
complete the program.
You signify disk library files by appending the switch ILB to the file
specification. This notifies the Task Builder that the file named is a
library to be searched. The Task Builder searches the library for any
unresolved references in the object files appearing to the left of the library
file in the command line.
If you do not specify file types, the Task Builder assumes a default type of
.OBJ for object files and a default type of .OLB for object libraries.
For an overlaid build, the input file is an ODL file, signified with a IMP
switch. The Task Builder assumes a default file type of .ODL for files with
the IMP switch.
If you give a device designator or a project-programmer number in a file
specification in the input list (to the right of the equal sign), they apply
to all file specifications to the right in the list that do not have a device
designator or a project-programmer number.

For a build using MACRO object programs, for example, a suitable command line
is:
TKB EXE1,EXE1,EXE1=OBJ1,OBJ2,LB:RMSLIB!LB

The Task Builder constructs the executable file EXE1.TSK, the map file
EXE1.MAP and the symbol table file EXEl.STB from the files OBJl.OBJ,
OBJ2.0BJ, and relevant modules from the library RMSLIB.OLB . (The relevant
modules are those referenced in your program. You may have referred to them in
source statements, or the MAC assembler may have translated source statements
into calls referring to this library.)

To omit the map file, type:
TKB EXE1"EXE1=OBJ1,OBJ2,LB:RMSLIB!LB

To produce only the executable file, type:
TKB EXE1=OBJ1,OBJ2,LB:RMSLIB!LB

To produce no output files, type:
TKB=OBJ1,OBJ2,LB:RMSLIB!LB

The example above is useful if you are running the Task Builder only to see error
messages; that is, for a diagnostic run. Note how project-programmer numbers
and device designators work when given for a file specification:
TKB=OBJ1, [2,243jOBJ2,OBJ3,LB:RMSLIB!LB,MYLIB!LB

For this command, the Task Builder would search for the file OBJl.OBJ in the
user's account. It would attempt to find the files OBJ2.0BJ and OBJ3.0BJ on
the public disk structure in the account [2,243J. The project-programmer number
also applies to the libraries. That is, the Task Builder would look on the system
library disk for a file RMSLIB.OLB under the account [2,243J. Likewise, since
the device name LB : also applies to MYLIB, the Task Builder would look on the
system library disk in account [2,243J for the library file MYLIB .OLB.

10-2

Task Builder Command Line Format

If you do not want this to happen, you must respecify the project-programmer

number and device that you want to apply to remaining files. The simplest way
to accomplish this is to assign a logical name to the account [2,243] and use the
system-wide logical SY: to "go back to" your account on the public disk structure.
For example:
ASSIGN SY:[2,243] JOHN
Ready
TKB=JOHN:FILE1,SY:FILE2,FILE3,LB:RMSLIB/LB,SY:MYLIB/LB

This can also be accomplished using multiple command lines, as shown in the
following section.

10.1.2 Multiline Command
Because you can specify any number of input files to the Task Builder, it is
sometimes necessary to enter a command on more than one line.
If you run the Task Builder such that it prompts with TKB>, it continues

prompting for input until it receives a line consisting only of two slash characters
(II) . For example:
RUN $TKB
TKB> IMG1,IMG1,IMG1=SY : [2,243]FILEl
TKB> FILE2 , FILE3,LB:RMSLIB/LB
TKB> MYLIB/LB
TKB> //

This sequence produces the same result as the single line command:
TKB IMG1,IMG1,IMG1=JOHN:FILE1,SY : FILE2,FILE3,LB : RMSLIB/LB,SY : MYLIB/LB

In addition, it produces all three output files.
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.

10.2 Options
You may need to specify options to build a particular program. An option modifies
the action taking place during the build. To include options, you must use the
multiline format. If you specifY a line consisting of a single slash (I), the Task
Builder assumes that the last input file has been entered and prompts for options
by displaying "ENTER OPTIONS:" and another TKB> prompt. You then enter
the options you want and terminate the build with the double slash. For example:
RUN $TKB
TKB> command
TKB> continued-command
TKB> /
ENTER OPTIONS:
TKB> option
TKB> / /

Task Builder Command Line Format

10-3

10.3 Multiple Builds in One Run
If you want to build more than one program, you can use the single slash after
typing options for the preceding program. The Task Builder stops accepting
input, builds the program, and then requests information for the next build. For
example:
RUN $TKB
TKB> IMGl=INl,IN2,IN3
TKB> I
ENTER OPTIONS:
TKB> UNITS=4
TKB> ASG=SY:O:l,MTO:3,KB:4
TKB> COMMON=JRNAL:RO
TKB> I
TKB> IMG2=SUBl
TKB> I I

The Task Builder accepts the input for the first build; it then stops accepting
input when you type the single slash after the COMMON option. The Task
Builder builds IMGl.TSK and then prints TKB> to accept the input for building
IMG2.TSK.

10.4 Indirect Command Files
The descriptions of Task Builder commands, up to this point, assume that you
are entering them from the keyboard. You can also create indirect command files
containing Task Builder commands that you want executed. Later, when you run
the Task Builder, you type an at sign character (@) followed by the name of the
indirect command file. This capability is very useful if you repeat the same build
operation often.
For example, you can use a text editor to create a file called AFIL.CMD, which
contains:
IMGl,IMGl=INl,IN2,IN3

I
UNITS=4
ASG=SY:O:l,MTO:3,KB:4
COMMON=JRNAL:RO

Later, you can type:
RUN $TKB
TKB> @AFIL
TKB>

Or, if TKB is installed as a CCL command, you can type:
TKB @AFIL

When the Task Builder finds a line consisting of two slashes, it stops processing
the indirect command file, builds the program, and exits.
When the Task Builder finds a single slash on a line, and the slash is the last
character in the file, the Task Builder displays a prompt for input and lets you
finish the command from the terminal. For example, suppose the file AFIL.CMD
in the last example is changed to read:
IMGl,IMGl=INl,IN2,IN3

10-4

Task Builder Command Line Format

You run the command file as usual. The Task Builder accepts the command file
input, and displays the prompt for options:
RUN $TKB
TKB> @AFIL
ENTER OPTIONS :
TKB>

From this point, processing is as usual for keyboard input.
Using a single slash after options in indirect command files is a handy way to
return control to your terminal between successive builds. For example, suppose
you create two indirect command files . The first, AFIL.CMD, contains:
IMG1,IMG1=IN1,IN2,IN3

I
COMMON=JRNAL : RO

The second, AFIL2.CMD, contains:
IMG2,IMG2=IN4,INS,IN6

I
LIBR=RMSRES

The terminal interaction to build these two programs is:
RUN $TKB
TKB> @AFIL
TKB> @AFIL2

Note that you cannot use the CCL form to run the Task Builder to enter two
indirect command files. You must use the multiline format .
You can use an indirect command file reference within an indirect command file.
The Task Builder allows two levels of indirection. For example, you could put
standard options in an indirect command file, and refer to that file from another
command file. Suppose the file AFIL.CMD contains:
IMG1,IMG1=IN1,IN2,IN3

I
COMMON=JRNAL:RO
@BFIL

You must put the indirect file reference on a separate line. Now, suppose the file
BFIL.CMD contains:
STACK=lOO
UNITS =S
ASG=DT1:S

To build using these files, you type:
RUN $TKB
TKB> @AFIL

Note that you can also use an indirect command file to enter options only. For
example:
RUN $TKB
TKB> IMG1=IN1,IN2,IN3
TKB> I
TKB> @OPTIONS

Task Builder Command Line Format

10-5

10.5 Comments in lines
You can put comments anywhere in the command sequence. You begin a comment
with a semicolon (;) and terminate it with a carriage return. For example, you
could add comments to the indirect command file in the previous section as
follows:
; BUILD 32T
;THE OUTPUT FILES ARE
IMGl,IMG2=
;THE INPUT FILES ARE
INl,IN2,IN3

;OP TIONS ARE

I
COMMON=JRNAL:RO

;RATE TABLES

;

10.6 File Specifications
You use the standard RSTSIE conventions for file specifications. In general, the
format is:
device:[ppn]filename.type/swl/sw2 .. .lswn
If you do not specify a device, the public disk structure is assumed. The default
for project-programmer number is your account. The exception is when you
specify a device or project-programmer number for a file in a list of files. Such a
device designator or project-programmer number "sticks" to all file specifications
to the right. For example, consider the following input list:
TKB =OBJl, [2, 243]OBJ2,OBJ3,LB:RMSLIB/LB

The Task Builder looks for the file OBJl.OBJ in the user's account. It looks for
the files OBJ2.0BJ and OBJ3.0BJ on the public disk structure in account [2,243].
It looks for the file RMSLIB.OLB on the system library disk in account [2,243].
The default for file type depends on the switch you apply to the file specification.
If no switches are used, the defaults are:
file .TSK,fi le .MAP,fi le .STB=file .OBJ, ... ,file.OBJ

Defaults assumed when you use various switches are described in Chapter 11.
For example, the default file type when you use the ILB switch is .OLB.

10-6 Task Builder Command Line Format

Chapter 11

Task Builder Switches
The Task Builder lets you modify the action taken on a file by appending a switch
to the file specification. A switch is a slash (I) followed by a two- to four-character
code. In general, you can precede the two- to four-character code with a minus
sign (-) or the letters "NO", and the Task Builder negates the function of the code.
For example, the Task Builder recognizes the following settings for the switch

IMP:
IMP The file is an ODL file.
/-MP The file is not an ODL file.
/NOMP The file is not an ODL file.
The Task Builder assumes a default setting for each switch. For example, if you
do not specify any setting for the IMP switch, the Task Builder assumes /-MP
(that the file is not an ODL file). In the switch descriptions in this chapter, note
that the "Syntax" section shows where the switch is placed by using the opposite
of the default setting. (There is no need to specify a switch if you want to use the
default.)
Table 11-1 lists the Task Builder switches available on RSTS/E systems. They
are described in following subsections in alphabetical order.
Table 11-1:

Task Builder Switches

Switch

Meaning

ICC

Input file consists of concatenated
programs or subprograms.
Causes the Task Builder to build a
shared common.
Executable program contains a debugging aid.
Specified library file is a replacement for
the default system library.
Extend library
Enables the Fast Map feature of the
executive.
Indicates that the memory resident
overlay should use the Fast Map version .
Program uses Floating-Point processor.

ICO
IDA
IDL

IEL
!FM
!FO
IFP

Applies to
File

Default

.OBJ

ICC

.TSK,
.STB
.TSK,
.OBJ
.OLB

ICO

.TSK
.MAP

I-EL

.MAP

IFO

.TSK

IFP

I-DA
I-DL

I-FM

(continued on next page)

Task Builder Switches

11-1

Table 11-1 (Cont.):

Task Builder Switches
Applies to
File

Default

All co-tree overlay segments are searched
for matching definition or reference when
subroutines from the default system
library are processed.

.TSK

/-FU

IHD

Task file (executable program) includes a
header.

.TSK,
.STB

IHD

lID

Creates I-and D-space tasks.

.TSK

I-ID

ILB

Input file is a library file.

.OLB

I-LB

ILl

Informs the Task Builder to build a
shared library.

.TSK,
.STB

I-LI

IMA

Memory map file contains information
about the file.

.MAP,
.OBJ

IMP

Input file is an ODL (memory map) file.

.ODL

/-MP

IMU

Program is a multiuser program.

.TSK

I-MU

INM

No diagnostic messages on screen.

.TSK

I-NM

/PI

Resident area is position-independent.

.TSK,
.STB

I-PI

/PM

Post-mortem dump requested.

.TSK

I-PM

IRO

Memory-resident overlay operator (!) is
enabled.

.TSK

IRO

ISB

Causes the task to be built with the slow
mode.

.TSK,
.OBJ

I-SB

ISG

Allocates task program sections alphabetically by access code (RW followed by
RO).

.TSK

ISG

ISH

Short memory-map file is produced.

.MAP

ISH

/SP

Spool map file to line printer.

.MAP

ISP

ISQ

Program sections are allocated sequentially, rather than alphabetically.

.TSK

I-SQ

ISS

Selective search for global symbols.

.OBJ

I-SS

ITR

Executable program is to be traced.

.TSK

I-TR

/WI

Memory map file is printed at width of
132 characters (for I-WI, 80 characters).

.MAP

/WI

IXT:n

Task Builder exits after n diagnostics.

.TSK

I-XT

Switch

Meaning

/FU

tThe default is IMA for an input file, and I-MA for system and resident area symbol table (.STB)
files.

11-2 Task Builder Switches

11.1

ICC-Concatenated Programs and Subprograms
File

Input
Syntax

file. TSK=file.OBJ/-CC
Description

This switch controls the way the Task Builder extracts programs and subprograms from your input file. Your input file can contain more than one program or
subprogram. One way to achieve this is by concatenating more than one object
module.
By default, the Task Builder includes all the programs and subprograms in your
input file when it builds the executable program file. If you negate this switch (as
in the "Syntax" section above), the Task Builder includes only the first program
or subprogram of your input file.
This switch will not affect library files. If you try to use ICC and !LB, or I-CC
and !LB, in an attempt to limit or expand the Task Builder's normal processing of
libraries, the !LB simply overrides the ICC or I-CC .
Default

ICC
Example
RUN $TKB
TKB> FIRST1=BUNCH/-CC,LB:F4POTS/LB
TKB> / /

Task Builder Switches

11-3

11.2 ICO-Build a Common Block Shared Region
File

Task image
.STB file
Syntax
file.TSKlCO=file.OBJ
or
"file.STB/CO=file.OBJ
Description
The ICO switch informs the Task Builder that a shared common is being built. If
you build a shared common, you should use the ICO switch and the I-HD switch.
If you use the I-PI switch for an absolute shared common, all the program sections
in the common are marked absolute. Using the I-PII-HD switches without the ICO
switch causes the Task Builder to build a shared library.
If you use the /PI switch for a relocatable shared common, all program sections in
the common are marked relocatable.

In either case, the .STB file contains all the program section names, attributes,
lengths, and symbols. The Task Builder links common blocks by program sections. Therefore, the .STB file of a shared region built with the ICO switch
contains all defined program sections.
Using the /PII-HD switches without the ICO switch causes the Task Builder to
build a shared common.
The ICO switch does not have a I-CO form.
Effect
This switch causes the Task Builder to include all program section declarations in
the .STB file.
Defaults
ICO

Example
RUN $TKB
TKB> VAL/cOI-HD=vAL.OBJ
TKB> II

NOTE

Commons (read/write libraries) must still be processed using the
MAKSIL utility. See the RSTS / E Programmer's Utilities Manual for
more details about MAKSIL.

11-4 Task Builder Switches

11.3 IDA-Debugging Aid
File

Executable program file or input file

Syntax
file.TSKlDA=file.OBJ
or
file.TSK=file.OBJ,file.OBJIDA

Description
If you use the IDA switch on the executable program file, the Task Builder
automatically includes the system debugging aid LB:ODT.OBJ in the executable
program (LB:ODTID.OBJ if lID is also included).
If you use this switch on one of your input files, the Task Builder assumes that
the file is a debugging aid that you have written.

In either case, IDA has the following effects:
1.

The transfer address of the debugging aid overrides the executable program
transfer address.

2 . The Task Builder initializes the header of the program so that, when your
program is loaded, register RO through R4 contain the following values:
RO

Transfer address of program.

Task name in Radix-50 format (word 1). The Task Builder derives this name
from the TASK.:option. If no TASK.: is supplied, this value will be O.

Second word of task name.

The first three of six RAD50 characters representing the version number of
your program. The Task Builder derives this number from the first .IDENT
directive it encounters in your program. If no .IDENT directives appear, this
value will be O.

The second three RAD50 characters representing the version number of your
program.

Refer to your specific language reference manual for more information about
debugging aids.

Default
/-DA

Example
RUN $TKB
TKB> PROG/DA=OBJ,OBJ2,LB:F4POTS/LB
TKB> / /

Task Builder Switches

11-5

11.4 tDl-Default Library
File

Input
Syntax

file.TSK=file.OBJ,file.OLBIDL
Description

The library file you specify replaces the file LB:SYSLIB.OLB as the library file
that the Task Builder searches to resolve undefined global references. This file is
searched only when undefined symbols remain after all the files you specify have
been processed. The IDL switch can be used with only one input file.
Default

/-DL
Example
RUN $TKB
TKB> PROG=PROG,LB:F4POTS/LB,NEWLIB/DL
TKB> / /

11-6 Task Builder Switches

11.5 tEL-Extend Library
File

Executable program file
Syntax

file.TSKILI/-HDIEL=file.OBJ
Description

The IEL switch places the upper-address limit as determined by the PAR option
in the library's label block, though the actual size of the library may be smaller.
This switch is useful when building vectored libraries subject to size changes,
such as RMS.
The switch specifies the maximum possible size for the library according to the
size specified in the PAR option. The switch specifies a larger library virtual
address range than is actually present in the library to allow RMS to map its
vectored library segments.
Default

/-EL

Task Builder Switches

11-7

11.6 IFM-Fast Map
File

Memory allocation (map) file
Syntax

file.TSKlFM=file.obj
Description

The IFM quailfier tells TKB to set the proper bits in the task header to enable the
Fast Map feature of the executive.
Default

/-FM
Example
RUN $TKB
TKB> PROG!FM=OBJl
TKB> !!

11-8 Task Builder Switches

11.7 IFO-Fast Map Overlay
File

Memory allocation (map) file
Syntax

file.TSKIFO/FM=file.obj
Description

The /FO switch indicates that the overlay handler for memory resident overlay
should use the Fast Map version. This version is faster, but it does take more
space. Use the /FO switch in conjunction with the /FM switch so that RSTSIE
will use the lOT instruction for Fast Map rather than for application use for this
task.
Default

/FO
Example
RUN $TKB
TKB> PROG/FO/FM=OVERLY/MP
ENTER OPTIONS:
TKB> / /

Task Builder Switches

11-9

11.8 IFP-Floating Point
File

Executable program file
Syntax

file.TSKlFP=file.OBJ
Description

Setting the /FP switch causes the RSTS/E monitor to save the state of the
floating-point processor when the program is run. You must set this switch
on systems that have the floating-point processor (if the program uses the
floating-point processor), so that the run-time system can trap floating-point
errors properly. Setting or negating this switch has no effect on systems without
a floating-point processor.
Default

/FP
Example
RUN $TKB
TKB> PROG/FP=OBJ1,OBJ2,LB:F4POTS/LB
TKB> / /

11-10 Task Builder Switches

11.9 IFU-Full Search
File

Executable program file
Syntax

file .TSKIFU =file. ODLIMP
Description

The IFU switch affects how the Task Builder inserts code from the default
library when your overlay structure has co-trees. Normally, when the same
code (program section) is called or referenced from different co-trees, it is built
into both co-trees unless it can be resolved from code already built into the main
root. This prevents the problem of run-time errors caused by unintentionally
displacing segments with cross-tree calls, as described in Chapter 4.
If you use this switch, the Task Builder can resolve undefined global references

with code from the default library that is already built into other co-trees. This
can be useful if you want to try to cut down on the space taken by code inserted
into co-trees from the default library, as described in Section 4.4.8.
Default

/-FU
Example
RUN $TKB
TKB> PROG/FU=OVERLY/MP
ENTER OPTIONS:
TKB> / /

Task Builder Switches

11-11

11.10 IHD-Header
File

Executable program file or symbol definition file
Syntax

file. TSKI-HD "file.STB=file. OBJ
or
file.TSK"file.STB/-HD=file.OBJ
Description

The IHD switch causes the Task Builder to generate a header for your executable
program file. This header is used by the run-time system when it loads your
program for execution. The run-time system takes certain values from the header
and inserts them in the low 1000 bytes of your program. (This area is used
by the RSTSIE monitor, the run-time system, and-with a few languagesyour program itself. For example, this area contains the "core common" area
accessible to BASIC-PLUS-2 programs and the FIRQB and XRB areas used by
MACRO programs. The contents of this area may be of interest to you if you are
programming in MACRO. The area is described in the RSTS / E System Directives
Manual .
In any case, you must have a header for executable program files (this is the
default). If you are building a resident library or common, or a run-time system
itself, you must negate this switch.
Default

IHD
Example
RUN $TKB
TKB> DATLIB/-HD/pI"DATLIB/pI=DAT1.DAT,DAT2.DAT,DAT3.DAT
TKB> I
ENTER OPTIONS:
TKB> PAR=DATLIB
TKB> II

11-12

Task Builder Switches

11.11 110-1- and O-Space
File

Task image (.TSK).
Syntax

file.TSKlID=file.OBJ,file.OLB
Description

Use this switch to create 1- and D-space tasks. The switch directs the Task
Builder to mark your task as one that uses I-space APRs and D-space APRs in
user mode. The Task Builder separates I-PSECTs from D-PSECTs. See Chapter
8 for more information.
Default

/-ID
Example
RUN $TKB
TKB> PROG1.TSK/ID=PROG1.OBJ,PROG1.OLB/LB
TKB> / /

Task Builder Switches

11 - 13

11.12 ILB-Library File
File

Input file, or any file in an ODL command.

Syntax
file.TSK=file.OBJ,file.OLBILB
or
file.TSK=file.OBJ,file.OLBILB:mod-1:mod-2: ... :mod-8
or
file.OBJ=file.OBJ,file.OLBILB:mod-1:mod-2,file.OLBILB
or
(Any of the above forms in an ODL file)

Description
If you use the ILB switch, it indicates that the file is a library file. The Task
Builder's interpretation depends upon the form you use. If you use the switch

without arguments, the Task Builder assumes that your input file is a library file
of relocatable object routines. The Task Builder searches the file to resolve undefined references in any files you have specified preceding the library specification.
It extracts necessary routines (which contain definitions for undefined references)
and includes them in your executable program file.
If you use the switch with the mod-i arguments (mod-l:mod-2: ... and so forth),

the Task Builder extracts from the library the routines named as arguments
regardless of whether or not they contain definitions for unresolved references.
If you want the Task Builder to search a library both to resolve global references

and to select named routines, you must name the library twice: once, with the
routines named (ILB switch with modifiers) and a second time with the general
form (ILB switch without modifiers).
The position of the library file in the command line is important. The following
rules apply:
1. The library file must appear to the right of the input file(s) that contain
references to be resolved from the library. For example:
TKB>file.TSK=infilel.OBJ,infile2.0BJ,lib.OLB/LB

In this command, unresolved references from infile1.0BJ and infile2.0BJ are
resolved from the library.
In the following command, unresolved references from infile1.0BJ are resolved from the library, but references from infile2.0BJ are not:
TKB>file.TSK=infilel.OBJ,lib.OLB/LB,infile2.0BJ

11-14 Task Builder Switches

2. When you are building an overlay structure, you specify the library within
the ODL file. You use the hyphen to indicate concatenation; unresolved
references from the segment to the left of the hyphen are resolved from the
library specified to the right. For example:
AFCTR:
BFCTR:
CFCTR:
LIBR:

. ROOT
. FCTR
.FCTR
.FCTR
.FCTR
.END

AFCTR-(BFCTR,CFCTR)
A-LIBR
B-LIBR-(BI-LIBR,B2-LIBR)
C-CI-LIBR-(COI-LIBR,C02-LIBR)
LB:F4POTS/LB

Notice that in this example, there is no -LIBR entry after C. Since C and Cl
are constructed as one segment, putting a -LIBR entry after C would only
cause an unecessary and time-consuming search. Only one search is needed
for each segment; you can place the -LIBR entry at the end of the segment,
after Cl. Section 3.7.3 explains how routines are inserted into segments from
libraries.

Default
/-LB

Example
See the Description section above.

Task Builder Switches

11-15

11.13 Ill-Build a Library Shared Region
File

Task Image
.STB file
Syntax

file.TSKlLI[:apr bit mask]
or
"file.STBILI[:apr bit mask]
Description

The ILl switch makes the Task Builder build a shared library. However, you
must use the I-HD switch with the ILl switch to build the shared library. The ILl
switch does not have a I-LI form .
See the discussion on APR masks in Chapter 7.
Effect

The Task Builder includes only one program section declaration in the .STB file.
If you use the I-PI switch for an absolute library, the Task Builder names the

program section .ABS, makes the library position dependent, and defines all
symbols as absolute. Also, if you use the I-PI switch without the ILl switch, the
Task Builder assumes ILl to be the default.
If you use the /PI switch for a relocatable library, the Task Builder names the

program section the same as the root segment of the library. The Task Builder
forces this name to be the first and only declared program section in the library.
The Task Builder declares all global symbols in the .STB file relative to that
program section. Also, if you use the /PI switch without the ILl switch, the Task
Builder assumes that a shared common is to be built. (lCO is the default.)
Default

ILl [:nnn]
where:
n

is the bit mask representing the APR in I-space used by the library

Example
RUN $TKB
TKB> PARODI/LI/-HD=PARODI.OBJ
TKB> //

NOTE

Libraries must still be processed using the MAKSIL utility. See
the RSTS / E Programmer's Utilities Manual for more details about
MAKSIL.

11-16

Task Builder Switches

11.14 IMA-Map Contents of File
File

Input or memory allocation (map) file
Syntax
file.TSK,file.MAP=file.OBJ,file.OBJ/-MA
or
file.TSK,file.MAPIMA=file.OBJ
Description
If you negate this switch and apply it to an input file, the Task Builder leaves
the file off the "file contents" portion of the memory map. Furthermore, it will
exclude from the map all global symbols defined or referred to in the file.
If you set this switch for the map file, the Task Builder includes in the map
the names of routines it has added to your program from the default library
(LB:SYSLIB.OLB). It also includes in the map file information contained in the
symbol definition file of any shared region referred to by the program.

Default
/MA for input files

I-MA for system library and resident library .STB files.
I-MA for map file
Example
RUN $TKB
TKB> PROG,PROG/MA=OBJ1,OBJ2,LB:F4POTS/LB
TKB> //

Task Builder Switches

11-17

11.15 IMP-Overlay Map
File

Input

Syntax
file.TSK=file.ODLIMP

Description
Your input file is an overlay map (ODL file). The file contains directions for an
overlay structure in the Overlay Description Language. When you use the switch,
it must be the only input file that you specify. The default file type for a file with
the IMP switch is .ODL.

Default
/-MP

Example
RUN $TKB
TKB> PROG,PROG=OVERLY/MP
ENTER OPTIONS:
TKB> / /

NOTE

If you use the multiline command format when you specify an ODL file,
TKB automatically prompts for option input. Therefore, you must not
use the single slash (I) to direct TKB to switch to option input mode
when you have specified IMP on your input file.

11-18 Task Builder Switches

11.16 IMU-Multiuser Program
File

Executable program file

Syntax
file.TSKlMU=file.OBJ

Description
The IMU switch tells the Task Builder to separate the program's read-only and
read/write program sections. On RSTSIE systems, you only use this switch if you
want to build a program so that the read-only code from the root is accessible to
multiple users. For this reason, it is recommended that programs built with the
IMU switch be nonoverlaid. Several steps are involved in this procedure.
When you use IMU on the executable file, the Task Builder places the readonly sections in your program's upper virtual address space and the read/write
program sections in your program's lower virtual address space. You then have
to use the MAKSIL program (described in the RSTS/E Programmer's Utilities
Manual to make the read-only code accessible to multiple users, and add the
read-only code as a resident area using the DCL INSTALLILIBRARY command
(described in the RSTS/E System Manager's Guide) .
Multiple users can then run the program built, causing multiple copies of the
read/write code to be executed, but with only one copy of the read-only code
taking space in memory.
Note that a program built with the IMU switch cannot be run correctly until
it has been converted by MAKSIL into a separate executable file (consisting of
the read/write code) and a resident area, which in turn must be added with the
DCL INSTALLILIBRARY command (just like any resident area). Note also that,
when you build a program and use the IMU switch, you can also use the HISEG
option. If you build with HISEG, the Task Builder will put the read-only code
to occupy virtual address space below the run-time system. If you do not build
with HISEG, the Task Builder will put the read-only code so that it occupies the
highest possible address space (using APR 7).

Default
/-MU

Example
RUN $TKB
TKB> PROG/MU=OBJl, OBJ2, OBJ3
TKB> / /

Task Builder Switches

11-19

11.17 INM-No Diagnostic Messages
File

Executable program file
Syntax

file.TSKINM=file.OBJ
Description

Using the INM switch eliminates the display of diagnostic messages from a build.
Default

/-NM
Example
RUN $TKB
TKB> PROG/NM=OBJ1,OBJ2,LB:F4POTS/LB
TKB> //

11-20

Task Builder Switches

11.18 /PI-Position Independent
File

Executable program file or symbol definition
Syntax

file.TSKlPI=file.OBJ
or
file. TSK"file.STB/PI=file. OBJ
Description

Use the /PI switch when you are building a resident area that is position independent, that is, a region that can be placed anywhere in the program's address
space. (The other option is an absolute resident area, which is fixed in the program's address space.) See Section 7.3.1 for a discussion of position-independent
resident areas.
Default

I-PI
Example
RUN $TKB
TKB> DATLIB/-HD/PI"DATLIB=DATl.DAT,DAT2 . DAT,DAT3 . DAT
TKB> /
ENTER OPTIONS:
TKB> STACK=O
TKB> PAR=DATLIB
TKB> / /

Task Builder Switches

11-21

11.19 IPM-Post-Mortem Dump
File

Executable program file
Syntax

file.TSKlPM=file.OBJ
Description

Setting the /PM switch causes the Task Builder to set an indicator in your
executable program file. If your program terminates abnormally when it is
executed, the indicator causes the system to write automatically the contents of
the program in memory on a disk file. The file name for the created file is:
PMDnnn.PMD
where: nnn is your job number.
The file must be formatted by the PMDUMP program (see the RSTS / E Utilities
Reference Manual) before you can read it.
Default

I-PM
Example
RUN $TKB
TKB> PROG/PM=OBJ1, OBJ2,LB:F4POTS/LB
TKB> / /

11-22

Task Builder Switches

11.20 IRO-Resident Overlay
File

Executable program file

Syntax
file.TSKI-RO=file.ODLIMP

Description
When you use IRO, the Task Builder processes any memory-resident overlay
operators (!) in your ODL file. That is, the Task Builder uses the exclamation
point operator to construct an executable program file that contains one or more
memory-resident overlay segments.
If you negate this switch, the Task Builder checks the syntax of the exclamation
point where it appears in the ODL commands but does not construct memoryresident overlay segments.

Default
IRO

Example
RUN $TKB
TKB> PROG/-RO=OVERLY/MP
ENTER OPTIONS:
TKB> / /

Task Builder Switches

11-23

11.21 ISB-Slow Build
File

Executable program file
Syntax

file.TSKlSB=file.obj
Description

The ISB qualifier causes the task to be built with the slow mode of the Task
Builder. This option increases the amount on TKB internal storage and therefore
allows you to build larger or more complex tasks.
Default

I-SB
Example
RUN $TKB
TKB> PROG/SB=OVERLY/MP
ENTER OPTIONS:
TKB / /

11-24

Task Builder Switches

11.22 /SG-Segregate Program Sections
File

Task image
Syntax

file.TSKlSG=file.OBJ
Description

The ISG switch allocates virtual address space to all read/write (RW) program
sections and then to all read-only (RO) program sections .
Effect

The ISG switch gives you control over the ordering of program sections. By
using the ISG switch, you cause the Task Builder to order program sections
alphabetically by name within access code (RW followed by RO). If you specify
the ISQ switch with the ISG switch, the Task Builder orders program sections in
their input order by access code. (See the description of the ISQ switch for more
information.)
You use the negated switch, I-SG, to make the Task Builder interleave the RW
and RO program sections. Thus, the combination I-SG/SQ results in a task
with its program sections allocated in input order and its RW and RO sections
interleaved. Also, you can use I-SQI-SG to make the Task Builder order program
sections alphabetically with RW and RO sections interleaved. However, ISG is the
default.
When task building multiuser tasks, the /MU switch causes the Task Builder to
default to ISG. Therefore, to correctly build read-only tasks, you can use the /MU
switch only.
Default

ISG
Example
RUN $TKB
TKB> BARBEL/SG=BARBEL.OBJ
TKB> / /

Task Builder Switches

11-25

11 .23 ISH-Short Map
File

Memory allocation (map) file
Syntax

file .TSK,file.MAP/-SH=file.OBJ
Description

Negating this switch (-SH) requests the long version of the memory allocation
map. The Task Builder produces the "file contents" section of the map. An
example of the long version of the map is shown in Example 11-1. The letters in
brackets and the numbers in cirlces in the figure correspond to the notes following
the figure.
Default

ISH
Example
RUN $TKB
TKB> PROG,PROG/-SH=OBJl,OBJ2,LB:F4POTS/LB
TKB> / /

11-26

Task Builder Switches

Example 11-1:
ROOTM.TSK
Task

Memory Allocation (Map) File

Memory allocation map TKB 08.006
05-MAY-90
13:50

name

ROOTM

Page

~ 0

[A]

Partition name
GEN
[B]
Identification
01
[C]
Task UIC
[2,234]
[0]
Task priority
50.
[E]
Stack
limits: 001000 001777 001000 00512.
[F]
ODT xfr address: 011054
[G]
PRG xfr address: 002000
[H]
Task attributes: DA,MU
[I]
Total address windows: 2.
[J]
Task
extension
128. words
[K]
Task image size
9760. words
[L]
Total task size
9888. Words
[M]
Task address limits: 000000 046033
[N]
R-W disk blk limits: 000002 000101 000100 00064.
R-O disk blk limits: 000102 000112 000011 00009.

[0]
[P]

ROOTM.TSK Overlay description:
Base

Top

000000
016030
016030
032044
032044

016027
031247
032043
046033
045667

ROOTM.TSK
ROOTM

Length
016030
013220
014014
013770
013624

ROOTM
MULOV
ADDOV

07192.
05776.
06156.
06136.
06036.

SUBOV
DIVOV

Memory allocation map TKB 08.006
05-MAY-90
13:50

*** Root segment: ROOTM

Page 2

[A]

R/W mem limits: 000000 016027 016030 07192.
R-O mem limits: 160000 170577 010600 04480.
Disk blk limits: 000002 000020 000017 00015.

[B]
[ C]
[0]

Memory allocation synopsis:
Section

Title Ident

. BLK.: (RW,I,LCL,REL,CON)
CODE
: (RW,I,LCL,REL,CON)

File

002000 000000 00000 .
[E]
002000 000024 00020.
002000 000024 00020 . . MAIN.01 ROOTM.OBJ

[F]

Global symbols:
ADD 170076-R
BEG 002000-R

DATEND
DATO

010010-R DAT1
160000-R DIV

002024-R MUL
170116-R SUB

File: ROOTM.OBJ Title: .MAIN.
Ident: 01
<. ABS.>: 000000 000000 000000 00000.
»»»»»» Undefined reference: NOSYMB

170066-R .ODTL1 010434-R
170106-R .ODTL2 010436-R

[G]

[H]
[I]
[J]

(continued on next page)

Task Builder Switches

11-27

Example 11-1 (Cont.):

Memory Allocation (Map) File

<CODE >: 002000 002023 000024 00020.
BEG
002000-R
[K]
<DATA >: 160000 170041 010042 04130.

[L]

************
Undefined references:

[M]

NOSYMB
ROOTM.TSK
MULOV

Memory allocation map TKB 08.006
05-MAY-90
13:50

Page 4

*** Segment: MULOV

R/W mem limits: 016030 031247 013220 05776.
Disk blk limits: 000021 000034 000014 00012.
Memory allocation synopsis:
Title

Section
. BLK.: (RW,I,LCL,REL,CON)
$$ALVC: (RO,I,LCL,REL,CON)
$$RTS : (RO,I,GBL,REL,OVR)

016030
016030
031250
170570

013220
013220
000000
000002

05776.
05776. .MAIN.
00000.
00002.

Ident

File
MULOV.OBJ

Global symbols:
MUL

016030-R

File: MULOV.OBJ Title: .MAIN. Ident:
<. BLK.>: 016030 031247 013220 05776.
MUL
016030-R

*** Task builder statistics:
[A]
Total work file references: 4693.
Work file reads: O.
[B]
Work file writes: O.
[B]
Size of core pool: 4814 . words (18. pages)
Size of work file: 3072. words (12. pages)
Elapsed time:00:00:17

0)
[C]
[D]

[E]

o The page header shows the name of the executable program 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:

A. Task Name. The name specified in the TASK option. If you do not use the
TASK option, the Task Builder suppresses this field.

B. Partition Name. The partition specified in the PAR option. If you do not
specify a partition, the default is a partition named GEN.

C. Identification. The version as specified in the .IDENT assembler directive.
If you do not specify, the default is the same as the version of the Task
Builder.

11-28 Task Builder Switches

D. User Identification Code. The project-programmer number used to create
the executable program file.
E. Priority. (On RSTSIE systems, this field is ignored.) Priority is suppressed

if you do not use the PRI=: option.
F. Stack Limits. The low and high octal addresses of the stack, followed by
its length in octal and decimal bytes.
G. ODT Transfer Address. The starting address of the ODT debugging aid.
If you do not specify the ODT debugging aid, this field is suppressed.
H. Program Transfer Address. The starting address of your program. For
MACRO programmers, this is the address of the symbol specified in
the .END directive of the source code of your program. (The compilers
generate a starting address automatically.) If you do not specify a transfer
address for your program, the Task Builder automatically establishes a
transfer address of 000001 for it. The Task Builder also suppresses this
field in the map if no transfer address is specified.
I.

Attributes. Using certain switches indicates that your program has
certain attributes. Such switch settings are shown only if they differ from
the defaults. For example, the following could be displayed:
DA - the program contains a debugging aid.
MU - the program is broken into RO and RW sections for processing by
MAKSIL. See the description of the IMU switch in Section 11.16 of this
manual, and the MAKSIL chapter in the RSTS / E Programmer's Utilities
Manual, for more information.

J. Total Address Windows. The number of window blocks allocated to the
program.
K. Task Extension. The increment of physical memory (in decimal words)
allocated through the EXTTSK or PAR option.
L. Task Image Size. The amount of memory (in decimal words) required
to contain your program's code. This number does not include physical
memory allocated through the EXTTSK option.
M. Total Task Size. The amount of memory (in decimal words) allocated
to your program, including the physical memory allocated through the
EXTTSK option or PAR option.
N. Task Address Limits. The lowest and highest virtual addresses allocated
to the program, exclusive of resident areas.
O. Read/Write Disk Block Limits. From left to right: the first octal relative
disk block of the program's read/write region; the last octal relative disk
block number of the read/write region; the total contiguous disk blocks
required to accomodate the read/write region in octal and decimal.
P.

Read-Only Disk Block Limits. From left to right: the first octal relative
disk block of the multiuser program's read-only region; the last octal
relative disk block number of the read-only region; the total contiguous
disk blocks required to accomodate the read-only region in octal and
decimal. This field appears only when you are building a multiuser
program with the IMU switch.

o The Overlay Description shows, for each overlay segment in the tree structure
of an overlaid program, 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

Task Builder Switches

11-29

the overlay structure. The Task Builder prints the Overlay Description only
when an overlaid program is created.

e The Root Segment Allocation. This section has the following elements:
A. Root Segment. The name of the root segment. If your program has only
one segment, the entire program is considered to be the root segment.
B. Read/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.

C. Read-Only 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. This field appears only when you are building a multiuser program
with the IMU switch.
D. 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.
E. 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.
F.

Contributor. This field lists the pieces that have contributed to each
program section. In this example, the program section ANS was defined
in the file ROOTM.OBJ. The identification in this case is 01 as a result
of an .IDENT assembler directive. If the program section ANS had been
defined in more than one piece (for example, in more than one routine in
a library (.OLB) file), each contributing piece and the file from which it
was extracted would have been listed here.

G. Global Symbols. This section lists the global symbols defined in the
segment. Each symbol is listed along with its octal value. -R is appended
to the value if the symbol is relocatable. The list is alphabetized in
columns.
The File Contents Section is produced only if you specify the /-SH switch
in the Task Builder command sequence. The Task Builder then creates
this section for each segment in an overlay structure. It lists the following
information:
H. Input File. The file name, the name established by a .TITLE assembler directive, and the version as established by an .IDENT assembler
directive.

11-30

Program Section. Program section name, starting virtual address of
the program section, ending virtual address of the program section, and
length in octal and decimal bytes.

Undefined Reference. This section provides the names of undefined
symbols in the preceding program section.

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 address of the symbol. -R is appended to the value if
the symbol is relocatable.

Task Builder Switches

L. Program Section. This field is identical to the field described in note I.
The following sections in the map file appear regardless of whether you use
the /-SH switch or not.
M. Undefined References. This field lists the undefined global symbols in the
segment.

o 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.

o Task Builder Statistics list the following information, which can be used to
evaluate Task Builder performance:

A. Work File References. The number of times that the Task Builder accessed data stored in its work file.
B. Work File Reads. The number of times that the work file device was
accessed to read work file data.
Work File Writes. The number of times that the work file device was
accessed to write work file data.
C. Size of Pool. The amount of memory that was available for work file data
and table storage.
D. Size of Work File. The amount of device storage that was required to
contain the work file.
E. Elapsed Time. The amount of wall-clock time required to construct the
executable program and memory allocation (map) file. Elapsed time is
measured from when you entered the last option to the completion of
map output. This value excludes the time required to process the overlay
description and parse the list of input file names.
See Appendix E for a more detailed discussion of the work file.

Task Builder Switches

11-31

11.24 /SP-Spool Map Output
File

Memory allocation (map) file

Syntax
file.TSK,file.MAP/SP=file.OBJ

Description
This switch detennines whether your map file is automatically queued to the line
printer for output. If you use this switch, the Task Builder creates a map file and
queues it for printing. The default (if you specify a map file) is to create the map
file but not to queue it for printing.

Default
/-SP

Example
RUN $TKB
TKB> PROG,PROG/SP=OBJ1,OBJ2,LB:F4POTS/LB
TKB> //

11-32

Task Builder Switches

11.25 ISQ-Sequential
File

Executable program fiie

Syntax
file.TSK/SQ=file.OBJ

Description
If you set the /SQ switch, the Task Builder does not reorder program sections

alphabetically. Instead, it collects all the references to a given program section
from your input files, groups them according to their access code (read-only or
read/write), and within these groups, allocates memory for them in the order that
you input them.
You use this switch to satisfy requirements that certain program sections be
adjacent. Using this feature is otherwise discouraged because standard library
routines (such as FORTRAN I/O handling routines and File Control System (FCS)
routines from SYSLIB) will not work properly.
You can also make program sections adjacent by selecting their names alphabetically to correspond to the desired order.

Default
/-SQ

Example
RUN $TKB
TKB> PROG/SQ=OBJl,OBJ2,OBJ3
TKB> / /

Task Builder Switches

11-33

11.26 ISS-Selective Search
File

Input file
Syntax

file.TSK=file.OBJ/SS
or
file. TSK=file. OBJ ,file.STB/SS
or
file.TSK=file.OBJ,file.OLBILB/SS
Description

Setting the ISS switch tells the Task Builder to include in its internal symbol
table only those global symbols for which it has already encountered an undefined
reference.
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 ISS 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.
Default

I-SS
Example

Suppose that you are building a program consisting of input files containing
global entry points and references (calls) to them, as shown in Table 11-2.
Table 11-2:

Input Files for ISS Example

Input File Name

Global Definition

INl.OBJ
IN2.0BJ

Global Reference
A

A
B
C

IN3.0BJ
IN4.0BJ

A
B
C

Files IN2 and IN4 contain definitions for global symbols of the same name.
Assume that the global symbols represent entry points to different routines
within these files.

11-34 Task Builder Switches

Suppose that you want the Task Builder to resolve the reference to A in INl
with the definition of A in IN2. Further, assume that you want the reference to
global symbol C in IN3 to be resolved with the definition of C in IN4. You can
accomplish this by ordering the input files and using the ISS switch. For example:
TKB>SELECT=IN1,IN2/SS,IN3,IN4/SS

The Task Builder processes input files from left to right. Thus, the Task Builder
processes file INl first and finds the reference to symbol A. Since there is no
definition for A within INl, the Task Builder marks A as undefined and moves
on to process IN2. Because IN2 has the ISS switch, the Task Builder limits its
search of IN2 to symbols it has already marked as undefined, namely A. The Task
Builder finds a definition for A and puts A in its symbol table.
The Task Builder moves on to IN3, and encounters the reference to symbol C.
Since the Task Builder did not include symbol C from IN2 in its symbol table, it
marks C as undefined and moves on to IN4. When the Task Builder processes
IN4, it finds the definition for C, and includes that symbol in the table. Again,
since the ISS switch is attached, only symbol C is included in the Task Builder's
internal symbol table.
Thus, the reference to A in INl is resolved with the definition in IN2, and the
reference to C in IN3 is resolved with the definition in IN4. Note that the ISS
switch affects only the Task Builder's internal symbol table. The routines for
which symbols Band C are entry points will be included in the executable
program file even though there are no references to them.

Task Builder Switches

11-35

11.27 ITR-Traceable Program
File

Executable program file
Syntax

file.TSKlTR=file.OBJ
Description

When this switch is set, the Task Builder sets the T-bit in the initial program
status word (PSW) for your program. When your program is executed, a trace
trap occurs when each instruction is completed.
The system library (SYSLIB.OLB) contains a trace routine (TRACE.OBJ) that
processes the trap. You must explicitly build this routine into your executable
file if you want to use it. To do this, you must use the LBR utility (see the
RSTS / E Programmer's Utilities Manual) to remove TRACE.OBJ from the system
library. You then build TRACE.OBJ into your program using the fDA switch. The
example below shows TRACE.OBJ in the user's account on the public structure.
Default

/-TR
Example
RUN $TKB
TKB>PROG/TR=OBJl,OBJ2,OBJ3,TRACE/DA
TKB> /I

11-36

Task Builder Switches

11.28 /WI-Wide Listing Format
File

Memory allocation (map) file
Syntax

file.TSK,file.MAP/-WI=file.OBJ
Description

Negating this switch causes the Task Builder to format the map file 80 columns
wide. Setting the switch or accepting the default causes a map 132 columns wide.
Default

/WI
Example
RUN $TKB
TKB> PROG,PROG/ - WI=OBJ1,OBJ2,LB:F4POTS/LB
TKB> / /

Task Builder Switches

11-37

11.29 /XT[:n]-Exit on Error
File

Executable program file

Syntax
file.TSKlXT:n=file.OBJ

Description
Setting the IXT:n switch causes the Task Builder to exit after it finds n errors.
The number of errors can be specified in decimal or octal:
n.

Decimal number (decimal point must be there).

#n or n

Octal number.

If you do not specify n, the Task Builder assumes a value of 1.

Default
/-XT

Example
RUN $TKB
TKB> PROG/XT:I0 . =OBJ1 , OBJ2 , LB:F4POTS / LB
TKB> //

11-38 Task Builder Switches

Chapter 12

Task Builder Options
The options you specify to the Task Builder modify the action taken during the
build. The options available to RSTSIE users are listed in Table 12-1. Complete
descriptions of the options follow, in alphabetical order.
Table 12-1:

Task Builder Options

Option

Meaning

ABORT

Terminates command input and allows you to restart the input of command lines.

ABSPAT

Declares absolute patch values.

ACTFIL

Declares number of files that program can have open simultaneously.

ASG

Declares device assignment to logical units, or RSTSIE channels.

CLSTR

Declares a series of resident libraries to be clustered in one space in the
user job area.

CMPRT

Declares the completion routine for the supervisor-mode library.

COMMON

Declares a resident common area on LB: to be accessed by the program.

DSPPAT

Declares a series of object-level patches starting at the specified base
address.

EXTSCT

Declares extension of a program section.

EXTTSK

Declares extension of the program itself.

FMTBUF

Declares extension of buffer used by FORTRAN for processing format
strings at run time.

GBLDEF

Global symbol definition.

GBLINC

Includes a definition for a global symbol in the symbol table (.STB) file.

GBLPAT

Declares a series of object-level patch values relative to a global symbol.

GBLREF

Declares a global symbol reference.

GBLXCL

Excludes a definition for a global symbol from the symbol table (.STB) file.

HISEG

Associates an executable program with a high segment or run-time system.

LIBR

Declares a resident library on LB: to be accessed by the program.

MAXBUF

Declares an extension to the FORTRAN record buffer.

ODTV

Declares the address and size of the debugging aid SST vector.

PAR

Used to build resident area; defines the partition that the resident area is
to occupy.

RESCOM

Declares a resident common area to be accessed by the program.

(continued on next page)

Task Builder Options

12-1

Table 12-1 (Cont.):

Task Builder Options

Option

Meaning

RESLIB

Declares a user-owned resident library to be accessed by the program.

RESSUP

Declares that your task intends to access a user-owned supervisor-mode
library.

RNDSEG

Rounds the size of a named segment up to the nearest APR boundary
while building a resident library.

STACK

Defines the size of the stack.

SUPLIB

Declares that your task intends to access a systemwide supervisor-mode
library.

TASK

Names the executable program for SYSTAT.

TSKV

Declares the address of the program's SST vector.

UNITS

Declares the maximum number of units (channels).

VARRAY

Specifies an overlaid virtual array so that each segment of an overlaid task
that uses it defines the array in the same way that it is defined in the root
segment.

VSECT

Specifies the virtual base address, virtual length, and physical memory
allocated to the named program section.

WNDWS

Declares the number of additional address windows to be used by the
program.

12-2 Task Builder Options

12.1

ABORT-Abort the Build
The ABORT option is useful when you have made an error on an earlier line
of Task Builder input. When you type the ABORT=n in response to a TKB>
option prompt, the Task Builder stops accepting input for the current build and
prepares to accept input for a new build operation. You can then restart the same
or another command sequence.
Syntax

ABORT=n
where:
n

is any integer. (You must specify =n to satisfy the general form of the syntax for
options, but the value is ignored.)

Note that typing a CtrllZ (pressing the Ctrl and Z keys at the same time) causes
the Task Builder to stop accepting input and start building the current program.
ABORT is the only way to restart the Task Builder if you find an error and do not
want a build to take place.
Default

None
Example
RUN $TKB
TKB > PROG, PROG=OVERLY/MP
ENTER OPTIONS:
TKB> RESLIB=RMSRES
TKB> ABORT=1
TASK BUILD ABORTED VIA REQUEST
?TKB -- * FATAL *
ABORT = 1
TKB>

Task Builder Options

12-3

12.2 ABSPAT-Absolute Patch
The ABSPAT option declares a series of object-level patch values starting at a
specific base address. You can specify up to eight patch values.
Note that all patches must be within the segment address limits or the Task
Builder will generate a fatal error:
TKB-*DIAG*-LOAD ADDRESS OUT OF RANGE IN file-name
Syntax

ABSPAT=seg-name:address:vaI1 :vaI2: ... :val8
where:
seg-name

is the one- to six-character name of the segment.

address

is 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

is an octal number in the range of 0 through 177777 to be stored at the
address.

va12

is an octal number in the range of 0 through 177777 to be stored at the
address plus 2.

val8

is an octal number in the range of 0 through 177777 to be stored at the
address plus 14.

Default

None
Example
RUN $TKB
TKB> PROG,PROG=OBJl,OBJ2,LB:F4POTS/LB
TKB> /
ENTER OPTIONS:
TKB> ABSPAT=MYRTN:012156:143672:027001
TKB> / /

The ABSPAT option sets the word at location 012156 in segment MYRTN to
143672, and the word at location 012160 in segment MYRTN to 027001.

12-4 Task Builder Options

12.3 ACTFIL-Number of Active Files
The ACTFIL option declares the number of files that your program 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 program to have more than four active files, you must

use the ACTFIL option to make the additional allocation.
You must include a language library (object time system or OTS), and record
I/O service routines (such as RMS-ll) in your program for the extension to take
place. The program section that is extended has the reserved name $$FSRl.
Syntax

ACTFIL=n
where:
n

is a decimal integer indicating the maximum number of files that can be open at
the same time.

Default

ACTFIL=4
Example
RUN $TKB
TKB> PROG=OBJ1, OBJ2, LB: F4POTS/LB
TKB> I
ENTER OPTIONS:
TKB> ACTFIL=2
TKB> II

Task Builder Options

12-5

12.4 ASG-Assign Devices
The ASG option declares physical devices assigned to one or more logical units.
(A logical unit corresponds to a channel number in RSTSIE terminology). Note
that you cannot assign a unit number higher than the maximum number of units
declared in the UNITS option (Section 12.30).
Syntax

ASG=dev-name:unit-1:unit-2: ... ,dev-name:unit-n:...
where:
dev-name

is a two-character alphabetic device name followed by an optional one- or
two-digit decimal unit number.

unit-i

are decimal integers indicating the logical unit numbers (channels).

Default

ASG=SY:1:2:3:4,TI:5,TT:6
Example
RUN $TKB
TKB> PROG1=OBJ1, OBJ2, LB: F4POTS/LB
TKB> /
ENTER OPTIONS :
TKB > UNITS=8
TKB> ASG=SY:l:2:3:4:5:6:7,LPO:8

The above example declares a maximum of 8 logical units (the UNITS option
should be given before the ASG option). The channels 1-7 are allocated to the
public disk structure, and channel 8 is allocated to line printer unit O. Note that
in order to assign more than 8 logical units (channels) to a single device, you
must respecify the device name followed by the additional units to be assigned.
For example:
RUN $TKB
TKB> PROG1=OBJ1, OBJ2, LB: F4POTS/LB
TKB> /
ENTER OPTIONS:
TKB> UNITS=ll
TKB> ASG=SY:l:2:3:4:5:6:7:8,SY:9:10:11

12.5 CLSTR- Cluster Libraries
The CLSTR option lets you declare that multiple resident libraries are to share
the same virtual address space in your program. (See Section 2.3.5 for a general
discussion of how cluster libraries work.)
Syntax

CLSTR=default-library,library-2, ... ,library-5:access-code[:apr]
where:
default-library

12-6 Task Builder Options

library-5

The first library listed in the CLSTR option is the default library.
Because of the way clustering works, only certain libraries can be
default libraries. If you want to build libraries to be clusterable, see
Chapter 7 for a description of the techniques. If you simply want
to use libraries in a resident library cluster, the Digital-supplied
libraries are designed so that the language library can always serve
as the default library. Note that not all resident libraries that are
available with RSTSIE can take advantage of the clustering feature.
Those that can are:
BP2RES
Clusterable resident library for BASIC-PLUS-2 programs.
BP2SML

Clusterable resident library (a subset of BP2RES) for
BASIC-PLUS-2 programs.

C810IS

Clusterable resident library for COBOL-81 programs
compiled with lOIS switch (the normal default if your
system has the Commercial Instruction Set [CIS]
option).

C81LIB

Clusterable resident library for COBOL-81 programs
compiled with I-CIS switch (the normal default if your
system does not have the CIS option).

DIBOLR

Clusterable resident library for RMS DIBOL programs.

SMRES

Clusterable resident library for SORTIMERGE.

F4PCLS

Clusterable resident library for RMS FORTRAN-77
programs.

FDVRDB

Clusterable resident library for the form driver for
FMS (Form Management System), with debug mode
support.

FDVRES

Clusterable resident library for the form driver for
FMS, without debug mode support.

RMSRES

Clusterable resident library for RMS-ll that supports
sequential, relative, and indexed file operations.

DAPRES

Clusterable resident library for network record access
through RMS.

Thus, you can use C810IS or C81LIB (for COBOL-81 programs)
as the default library, and FDVRES and/or RMSRES as secondary
libraries in the cluster. Likewise, you can use BP2RES or BP2SML
as the default library, and FDVRES and/or RMSRES as secondary
libraries in the cluster. (See the reference manual for your specific
language for more information.)
Up to five resident libraries can form a cluster on RSTSIE systems.
A cluster for Digital-supplied libraries must occupy the upper 8K of
your address space. If your site builds its own clusterable libraries,
however, these libraries can occupy their own separate cluster, as
long as the limit of seven resident libraries for each task build is
not exceeded.
For example, you can cluster either of two variations of the COBOL81 library (C81OIS or C81LIB) with the FMS library (FDVRES)
and/or the RMS-ll library (RMSRES), and two or three of your
own clusterable libraries either in the same cluster or in a separate
cluster in lower virtual memory.

Task Builder Options

12-7

access-code

is either RW (read/write) or RO (read-only). This code indicates
how your program intends to access the library. (It will be RO
for Digital-provided resident libraries such as BP2RES, FDVRES,
C8ICIS, etc.) For example:
TKB>CLSTR=C81CIS,FDVRES:RO

apr

is an integer in the range of 1 to 7 that specifies the first Active
Page Register (APR) reserved for the clustered libraries. (See
Section 2.3.4 for information on APRs.) If you leave this parameter
off, the Task Builder assigns the highest APRs it can to the cluster
(APRs 6 and 7 for the above command line).
Currently, Digital-supplied libraries are built to use APRs 6 and 7
so that they can occupy 8K words at the highest end of the user job
area.

Default

None
Example
RUN $TKB
TKB> PROG,PROG=PROG,LB:C81CIS/LB
TKB> /
ENTER OPTIONS :
TKB> CLSTR=C81CIS,FDVRES:RO
TKB> / /

12-8 Task Builder Options

12.6 CMPRT-Completion Routine
Use this option to identify a shared region as a supervisor mode library. The
CMPRT option requires an argmnent that specifies the entry point of the
completion routine in the library. The completion routine switches the processor
back from supervisor mode to user mode, and returns program control to the
user task after the supervisor mode library subroutine finishes executing. The
completion routine is invoked by a RTS PC at the end of the supervisor mode
subroutine.
The following completion routines are available in the system library;
•

$CMPCS restores only the carry bit in the user mode PSW.

$CMPAL restores all the condition code bits in the user mode PSW.

These routines perform the necessary overhead to switch the processor from
supervisor mode to user mode and return program control to the user task at the
instruction following the call to supervisor mode library subroutine. Although
you can write your own completion routines, you should use either $CMPCS or
$CMPAL whenever possible. Chapter 9 discusses these routines in detail.
Syntax

CMPRT=name
where:
name

is a one- to six-character name identifying the completion to routine global
entry point.

Default

None

Task Builder Options

12-9

12.7 COMMON-Access System Common Block
The COMMON option indicates a resident library that should contain only
data. The fonnat of the COMMON option is the same as the LIBR option
(Section 12.18).
Syntax

COMMON=name:access-code[:apr[:mask]]
See the description of the LIBR option (Section 12.18) for a discussion of the
parameters.
Example
RUN $TKB
TKB> PROG,PROG=OVERLY/MP
ENTER OPTIONS:
TKB> COMMON=MYCOM:RW:5
TKB> //

12-10

Task Builder Options

12.8 DSPPAT-Absolute Patch for D-Space
Use the DSPPAT option to declare a series of object-level patches starting at the
specified base address, and to make patches to the D-space and 1- and D-space
task. A maximum of eight patches can be specified. You can also use this option
to patch a conventional task at any location.
Syntax
DSPPAT=seg-name:address:vaI1:vaI2: ... :vaI8
where:
seg-name

is the 1- to 6-character Radix-50 name of the segment.

address

is the octal address of the first patch. The address can only be on a byte
boundary; however, two bytes are always modified for each patch: the
addressed byte and the following byte.

vall

is an octal number in the range of 0 to 177777 to be stored at address.

val2

is an octal number in the range of 0 to 177777 to be stored at address+2.

val8

is an octal number in the range of 177777 to be stored at address+16.

Default
None
Example
RUN $TKB
TKB> PROG,PROG=OBJ1,OBJ2,LB:F4POTS/LB
TKB>
ENTER OPTIONS:
TKB> DSPPAT:MYDATA: 100: 1:2

The DSPPAT option sets the word at location 100 in segment MYDATA to 1, and
the word at location 102 in segment MYDATA to 2.
NOTE

All patches must be within the segment address limits or TKB generates the following error message:
TKB- -*DIAG*--Load address out of range in module-name

Task Builder Options

12-11

12.9 EXTSCT-Extend Program Section
The EXTSCT option extends the size of a program section. If the program section
has the concatenated (CON) attribute, its size is extended by the length specified.
If the program section has the overlay (OVR) attribute, its size is set equal to the
length specified, if the length specified is greater than the current size. (If the
length is less than the current size, the current size is allocated.)
Syntax

EXTSCT=psect-name:length
where:
psect-name

is the one- to six-character name of the program section to be extended.

length

is the octal number of bytes to extend the program section.

Default

None
Example
RUN $TKB
TKB> PROG=OBJ1,OBJ2, LB:F4POTS/LB
TKB> /
ENTER OPTIONS:
TKB> EXTSCT=BUFF:250
TKB> / /

Suppose that BUFF is initially 200[8] bytes long. Mter the above option is
specified, it will be allocated 450[8] bytes if it is concatenated (CON), or 250[8]
bytes if it is overlaid (OVR).

12-12

Task Builder Options

12.10 EXTTSK-Extend Task Memory
The EXTTSK option directs the system to allocate additional memory for your
executable program, up to a maximum of (32K-32736) words.
The amount of memory available to the program is the sum of the program's size
plus the increment you specify in the EXTTSK option, rounded up to the next
32-word boundary. This option extends only the D-space of an 1- and D-space
task.
This option extends only the D-space of and 1- and D-space task.
Syntax

EXTTSK=length
where:
length

is a decimal number in the range O<n<32,736 specifying the increase in
task memory allocation (in words).

Default

The program is extended to the next multiple of lK words .
Example
RUN $TKB
TKB> PROG=OBJl,OBJ2,LB:F4POTS/LB
TKB> /
ENTER OPTIONS:
TKB> EXTTSK=4096
TKB> //

NOTE
1. You should not use the EXTTSK option to extend a task containing memory-resident overlays because the system does not map the
extended area.
2. Be careful when extending an 1- and D-space task that is linked to
a library containing both data and instructions. Normally, libraries
are mapped in both 1- and D-space, allowing data and instructions to
be intermixed. The extension length must not extend into the area
mapped for the library or the library will be mapped in I-space only.

Task Builder Options

12-13

12.11

FMTBUF-Format Buffer Size
The FMTBUF option declares the length of the internal working storage that
you want the Task Builder to allocate within your program for the compilation of
format specifications at run time. 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 source of
formatting information within a FORTRAN 1/0 statement. The program section
that the Task Builder extends has the reserved name $$OBFl.
Syntax

FMTBUF=n
where:
n

is a decimal integer, larger than the default (132), that specifies the number of
characters in the longest format specification.

Default

FMTBUF=132
Example
RUN $TKB
TKB > PROG= OBJ1, OBJ2, LB :F4POTS/LB
TKB> /
ENTER OPTIONS:
TKB> FMTBUF= 140
TKB> / /

12-14 Task Builder Options

12.12 GBLDEF-Define a Global Symbol
The GBLDEF option defines a global symbol and its value. The Task Builder
considers this symbol definition to be absolute. It overrides any definition in your
object program files.
Syntax

GBLDEF=symbol-name:symbol-value
where:
symbol-name

is the one- to six-character name assigned to the global symbol.

symbol-value

is an octal number in the range of 0 through 177777 assigned to the
defined symbol.

Default

None
Example
RUN $TKB
TKB> PROG=OBJ1,OBJ2,F4POTS/LB
TKB> I
ENTER OPTIONS:
TKB> GBLDEF=LITVAL=1357
TKB> II

Task Builder Options

12-15

12.13 GBLlNC-lnclude Global in .SlB File
The GBLINC option includes a global symbol in the .STB file that would not
otherwise be there. This option is used in Digital-supplied resident libraries that
may need to call routines in other resident libraries in a cluster. It is also useful
if you are building your own clusterable resident libraries.
Syntax

GBLINC=symbol
where:
symbol

is the global symbol name to be included in the symbol table file being built
for the resident library.

Default

None
Example
RUN $TKB
TKB> PROG, PROG, PROG=OVERLY/MP
TKB> /

Enter Options:
TKB > GBLINC=. FCSJT
TKB > GBLINC=USER
TKB> / /

The GBLINC option includes the symbols named (.FCSJT and USER) in the
symbol table file (PROG).

12-16 Task Builder Options

12.14 GBLPAT-Global Relative Patch
The GBLPAT option declares a series of object-level patch values starting at an
offset relative to a global symbol. You can specify up to eight patch values.
Note that all patches must be within the segment address limits or the Task
Builder will generate a fatal error.
Syntax

GBLPAT=seg-name:sym-name[ +I-offset] :vall :vaI2: ... :val8
where:
seg-name

is the one- to six-character name of the segment.

sym-name

is the one- to six-character name specifying the global symbol.

offset

is an octal number specifying the offset from the global symbol.

vall

is an octal number in the range of 0 through 177777 to be stored at the
address of the global symbol plus or minus the offset.

val2

is an octal number in the range of 0 through 177777 to be stored at the
address of the global symbol, plus or minus the offset, plus 2.

val8

is an octal number in the range of 0 through 177777 to be stored at the
address of the global symbol, plus or minus the offset, plus 14.

Default

None
Example
RUN $TKB
TKB> PROG, PROG=OVERLY/MP
TKB> /
ENTER OPTIONS :
TKB> GBLPAT=IN1 : MRTN+4 : 10001
TKB> / /

The GBLPAT option sets the word at location MRTN+4 in segment IN1 to 010001.

Task Builder Options

12-17

12.15 GBLREF-Global Symbol Reference
The GBLREF option declares a global symbol reference. The reference originates
in the root segment of the executable program.
Syntax

GBLREF=symbol-name
where:
symbol-name

is the one- to six-character name of a global symbol.

Default

None
Example
RUN $TKB
TKB> PROG,PROG=OVERLY/MP
ENTER OPTIONS:
TKB> GBLREF=MRTN
TKB> / /

12-18 Task Builder Options

12.16 GBLXCL-Exclude Global from .STB File
The GBLXCL option excludes a global symbol from the .STB file that would
otherwise be there. This option is used in Digital-supplied resident libraries that
may need to call routines in other resident libraries in a cluster. It is also useful
if you are building your own clusterable resident libraries.
Syntax

GBLXCL=symbol
where:
symbol

is the global symbol name to be excluded from the symbol table file being
built for the resident library.

Default

None
Example
RUN $TKB
TKB> PROG, PROG, PROG=OVERLY/MP
TKB> /

Enter Options:
TKB> GBLXCL= . FCSJT
TKB> GBLXCL=USER
TKB> 1/

The GBLXCL option excludes the symbols named (.FCSJT and USER) from the
symbol table file (PROG).

Task Builder Options

12-19

12.17 HISEG-Oefine High Segment
The HISEG option associates an executable program with a user-written high
segment, or run-time system. If there are global definitions within the high
segment that resolve references in the input files you specify, the Task Builder
links them correctly. The symbol-table file (.STB file) for the named run-time
system must be in the account specified by the system logical name LB:. If the
HISEG option is not specified:
1. The run-time system associated with the executable program is the same as

that associated with the Task Builder itself.
2.

No global references to symbols in that high segment are resolved.

Note that the HISEG option is sometimes used when you build a multiuser
program with the IMU switch. (See Section 11.16.)
Syntax
HISEG=high-segment-name
where:
high-segment-name

is a one- to six-character name specifYing the run-time
system.

Default
If no high segment is specified, the run-time system associated with the Task
Builder is assumed.

Example
RUN $TKB
TKB> PROG=OBJl, OBJ2
TKB> /
ENTER OPTIONS:
TKB> HISEG=USRTS
TKB > / /

12-20 Task Builder Options

12.18 LlBR-Access System-Owned Resident Library
The LIBR option declares that your program intends to access a system-owned
resident library.
Syntax

LIBR=name:access-code[:apr[:mask]]
where:
name

is the one- to six-character name specifying the library. The Task
Builder expects to find a symbol table file and task image file of the
same name (name.STB and name.TSK) on the device and under the
account specified by the system logical name LB: .
The easiest way to find out if the files exist on LB: is to do a directory:
OIR LB:RMSRES . STB
Name Typ Size
Prot
RMSRES.STB
4 < 40>
OIR LB:RMSRES.TSK
Name Typ Size
Prot
RMSRES.TSK
16 < 40>

OR3: [1,11]

OR3: [ 1,11]

(If the files do not exist on LB:, you must use the RESLIB option,

Section 12.23.)
access-code

is the code RW (for read/write) or RO (for read-only), indicating the
type of access required by your program.

mask

can be an explicit D-APR usage mask for the library. The value given
here will override what was defined for the mask when you built the
library, and will be acceptable to all other APR masks associated with
this task. See Section 7.7 for more details.

apr

is an integer in the range of 1 to 7 that specifies the first Active Page
Register (APR) reserved for the library.
It is not really necessary to understand Active Page Registers to use
this modifier. Think of your 32K-word user job area as divided into 8
parts of 4K words each, numbered from 0 through 7. Your program
occupies one or more of the lowest-numbered segments.
You can "map" a resident library into the area between the top of the
task and the top of the virtual address space. The map must begin on a
4K-word boundary. For example, if the program takes 6K words, there
are six APRs available (24K words) for resident library mapping. You
can map up to 20K words of resident library into your job, beginning
with APR 2, as illustrated in the following diagram:

Task Builder Options

12-21

APR

0
1-

YOUR PROGRAM

I-

SPACE AVAILABLE
FOR LIBRARY

S67
MK--{)1047--{)O

Default

None
Example
RUN $TKB
TKB> PROG, PROG=OVERLY/MP
ENTER OPTIONS:
TKB> LIBR=RMSRES :RO: 5
TKB> / /

This example causes the RMSRES library in LB: to be mapped through APRs 5
and 6. The run-time system is to be mapped through APRs 4 through 7.

12-22 Task Builder Options

12.19 MAXBUF-Maximum Record Buffer Size
The MAXBUF option declares the maximum record buffer size required for any
file used by the program. If your program requires a maximum record size that
exceeds the default buffer length (133 bytes), you must use this option to extend
the buffer.
You must also include a language library (object time system, or OTS), such as
FORTRAN's F4POTS, in your executable program for the extension to take place.
The program section that is extended has the reserved name $$IOBl.
Syntax

MAXBUF=n
where:
n

is a decimal integer, larger than 133, that specifies the maximum record size in
bytes.

Default

MAXBUF=133
Example
RUN $TKB
TKB> PROG=OBJl , OBJ2 , LB : F4POTS / LB
TKB> /
ENTER OPTIONS:
TKB> MAXBUF=166
TKB> / /

Task Builder Options

12-23

12.20 ODTV-ODT SST Vector
The ODTV option declares that a global symbol is the address of the ODT
Synchronous System Trap vector table. You must define the global symbol in the
main root segment of your program.
The vector address list contained at the global symbol will automatically be
installed as the task is loaded at execution time. Also, the vectors are active on
the execution of the first instruction when the task is started. This means that
there is no window where the traps could be missed, and the program will not
waste code space making explicit or SVTK$ or SVDB$ calls.
Syntax

ODTV=symbol-name:vector-length
where:
symbol-name

is a one- to six-character name of a global symbol.

vector-length

is a decimal integer in the range of 1 through 32, specifying the length of
the SST vector in words.

Default

None
Example
RUN $TKB
TKB> PROG/DA=OBJ1, OBJ2
TKB> /
ENTER OPTIONS:
TKB> ODTV= TRPVEC:8
TKB> //

For related information, refer to the RSTS / E System Directives Manual for the
SVDB$ (Set SST Vector Table for Debugging Aid) macro.

12-24 Task Builder Options

12.21

PAR-Partition for Resident Area
The PAR option is used when building a resident area. The option identifies
a "partition" for the resident area: the amount of space the resident area will
occupy when linked into user programs in the user job area (and its location, if
the resident library is to occupy absolute addresses).
Syntax

PAR=pname[:base:length]
where:
pname

is the name of the partition. This name must be the same as the file name
portion of the executable and symbol table files in the command line. For
example:
RUN $TKB
TKB> LIBRES/-HD"LIBRES/PI=LIBRES
TKB> /
ENTER OPTIONS :
TKB> PAR=LIBRES
TKB> / /

baae

is the octal byte address that defines the start of the partition. If the
library is position-independent (see Section 7.3.1), the base address is
zero. If the library is absolute, the base address must be on a 4K word
boundary. For example, if the library is always to be positioned beginning
at APR 6, you would specify an octal address of 140000.

length

is the octal number of bytes contained in the partition. If the length is
omitted or is zero, it is the size of the executable file .
If length is nonzero, and greater than the size of the executable file that
the build produced, the Task Builder automatically extends the size of the
resident area to make up the difference.
If the executable file size is greater than the length specified, the Task
Builder issues the following error message:
%TKB--*DIAG* - TASK HAS ILLEGAL MEMORY LIMITS

Default

PAR=GEN
Example

See parameter description, above.

Task Builder Options

12-25

12.22 RESCOM-Access Resident Common Block
The RESCOM option indicates a resident area that should contain only data. The
format of the RESCOM option is the same as the RESLIB option (Section 12.23).
Syntax

RESCOM=file-speclaccess-code[:apr[:mask]]

12-26 Task Builder Options

12.23 RESLlB-Access Resident Library
The RESLIB option declares that your program intends to access a resident
library.
Syntax

RESLIB=filespeclaccess-code[:apr[:mask]]
where:
filespec

is the file specification identifying the library. The Task Builder
expects to find a symbol table file and task image file with the same
filename (filename.STB and filename.TSK) on the device and account
specified. You must omit the file type from the file specification.

access-code

is the code RW (for read/write) or RO (for read-only), indicating the
type of access required by your program.

mask

apr

is an integer in the range of 1 to 7 that specifies the first Active Page
Register (APR) reserved for the library.
It is not really necessary to understand Active Page Registers to use
this modifier. Think of your 32K-word user job area as divided into 8
parts of 4K words each, numbered from 0 through 7. Your program
occupies one or more of the lowest-numbered segments.
You can "map" a resident library into the area between the top of
the task and the top of the virtual address space. The map must
begin on a 4K-word boundary. For example, if the program takes 6K
words, there are six APRs available (24K words) for resident library
mapping. You can map up to 20K words of resident library into your
job, beginning with APR 2, as illustrated in the following diagram:

APR

O--r---------------------rYOUR PROGRAM
2--r---------------------~

SPACE AVAILABLE
FOR LIBRARY

4
5
6

MK-O 1052-00

Task Builder Options

12-27

Default

None
Example
RUN $TKB
TKB>PROG=OBJ1,OBJ2
TKB>/
ENTER OPTIONS:
TKB>RESLIB=DR2:MYLIB/RO:5:200
TKB>//

This example causes the library MYLIB on DR2: in the user's account to be
mapped read-only beginning at APR 5. The user informs the Task Builder that
this library has D-space usage in APR 7.

12-28 Task Builder Options

12.24 RESSUP-Resident Supervisor-Mode Library
The RESSUP option declares 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 in any directory that you
choose. You can specify the directory along with the other portions of the file
specification. Do not place comments on the line with RESSUP.
Syntax

RESSUP=filespecl[-]access-code[:apr]
where:
filespec

is the specification identifying the supervisor mode library. The Task
Builder expects to find a symbol table file and a task image file with
the same file name (filename.8TB and filename.TSK) on the device and
account specified. You must omit the file type from the specification.
indicates whether TKB includes mode switching vectors within the user
task. If you specify ISV orlSW, TKB includes a 4-word mode switching vector within the address space of the user task for each call to a
supervisor-mode library subroutine. If you specify I-SV or I-SW, you must
provide your own mode switching vectors. This is useful if your library
contains threaded code. Digital recommends, however, using system
supplied vectors whenever possible.

access-code

is the code SV (for read-only) or SW (for read/write), indicating the type of
access required by your program.

apr

is an integer in the range 0 to 7 that specifies the first supervisor Active
Page Register (APR) that you want TKB to reserve for this supervisormode library. For position-independent libraries only, you can specify
that the default is the lowest available supervisor APR. One supervisormode library is required to be at virtual 0 (that is, ISV:O) and must have
the CSM (change supervisor mode) dispatcher present together with the
completion routines as described in Chapter 9. Most uses would be ISV:O.

Task Builder Options

12-29

12.25 RNDSEG-Round Segment
The RNDSEG option rounds the size of a named segment up to the nearest APR
boundary while building a resident library.
Syntax

RNDSEG=seg-name
where:
seg-name

is the 1- to 6-character Radix-50 name of the segment

Default

None
NOTE

The RNDSEG option operates only during a library build. Attempting
to use the option while building any other form of task will result in
the following diagnostic error message:
TKB -- *DIAG* - Library build not requested - ignoring option

If you attempt to specify a nonexistent name, the following diagnostic

error will be generated and the build will continue:
TKB -- *DIAG* - Segment not found to address round

12-30

Task Builder Options

12.26 STACK-Declare Stack Size
The STACK option declares the maximum size of the "stack" required by the
executable program.
The stack is an area of memory used for temporary storage, subroutine calls,
and other system functions. The stack is referenced by hardware register 6 (the
stack pointer). The default stack size is 25610 words, or 10008 bytes. The Task
Builder allocates space for the stack immediately following the low 10008 bytes
of memory used by the RSTSIE monitor, your program, and the run-time system.
(That is why, if you look at the Task Builder memory map file, the first location
of your program begins at address 2000, unless you specify a different stack size
with this option.)
CAUTION

Decreasing the size of the stack to less than the default size can cause
unpredictable results for programs written in certain higher-level
languages.
Syntax

STACK=n
where:
n

is a decimal integer specifying the number of words required for the stack.

Default

STACK=256
Example
RUN $TKB
TKB> PROG=OBJ1,OBJ2,OBJ3
TKB> /
ENTER OPTIONS:
TKB> STACK=512
TKB / /

Task Builder Options

12-31

12.27 SUPUB-Resident Supervisor-Mode library
The SUPLIB option declares that your task intends to access a systemwide
supervisor-mode library. The term "systemwide" means that the Task Builder
expects to find the supervisor-mode library and the symbol definition file
associated with it in the system library account (LB:).

Syntax
SUPLIB=name:[-]access-code[:apr]
where:
name

is the 1- to 6-character name specifying the supervisor mode library. The
Task Builder expects to find a symbol table file and a task image file of the
same name (name.STB and name.TSK) on the system device and under
the account specified by the system logical LB:. If the files do not exist on
LB:, you must use the RESSUP option.
indicates whether TKB includes mode switching vectors vl'ithin the user
task. If you specify :SV or :SW, TKB includes a 4-word mode switching vector Vlrithin the address space of the user task for each call to a
supervisor-mode library subroutine. If you specify :-SV or :-SW, you must
provide your own mode sVlritching vectors. Providing your own mode
sVlritching vectors is useful if your library contains threaded code. Digital
recommends, however, using system supplied vectors whenever possible.

access-code

is the code SV (for read-only) or SW (for readJwrlte), indicating the type of
access required by your program.

apr

is an integer in the range 0 to 7 that specifies the first supervisor Active
Page Register (APR) that you want TKB to reserve for this supervisormode library. You can specifY an APR only for position-independent
supervisor mode libraries. The default is the lowest available APR. One
supervisor-mode library is required to be at virtual 0 (for example, :SV:O)
and must have the CSM (change supervisor mode) dispatcher present
together Vlrith the completion routines as described in Chapter 9. Most
uses would be :SV:O.

12-32 Task Builder Options

12.28 TASK-Program Name for SYSTAT
The TASK option lets you specify the name of the program being built. This
name is displayed by the SYSTAT program. You can use this option if you want
to give a name to a program other than the name of the executable program file.
Syntax

TASK=program-name
where:
program-name

is the one- to six-character name to identify the program in SYSTAT.
The characters within the name must be letters (A to Z), numbers
(0 to 9), periods (.), or dollar signs ($).

Default

TASK=executable file name
Example
RUN $TKB
TKB> PROG, PROG=OVERLY/MP
ENTER OPTIONS :
TKB> TASK=USER
TKB> II

Task Builder Options

12-33

12.29 TSKV-Task SST Vector
The TSKV option declares that a global symbol is the address of the program
Synchronous System Trap (SST) vector table. You must define the global symbol
in the main root segment of your program.
The vector address list contained at the global symbol will automatically be
installed as the task is loaded at execution time. Also, the vectors are active on
the execution of the first instruction when the task is started. This means that
there is no window where the traps could be missed, and the program will not
waste code space making explicit or SVTK$ or SVDB$ calls.
Syntax

TSKV =symbol-name:vector-length
where:
symbol-name

is a one- to six-character name of a global symbol.

vector-length

is a decimal integer in the range of 1 through 32 specifying the length of
the SST vector in words.

Default

None
Example
RUN $TKB
TKB> PROG=OBJ1, OBJ2
TKB> /
ENTER OPTIONS :
TKB> TSKV=VECNAM: 8
TKB> / /

For related information, refer to the RSTS / E System Directives Manual for the
SVTK$ (Set SST Vector Table for Task) macro.

12-34 Task Builder Options

12.30 UNITS-Maximum Number of Units or Channels
The UNITS option declares the maximum number oflogical units (often called
channels in RSTS/E documentation) that are used by the program. The default
number is 6.
NOTE

If you want to use more than 6 channels, specify the UNITS option
before the ASG option (Section 12.4) that defines the devices for the
units.
Syntax

UNITS=max-units
where:
max-units

is a decimal number from 0 to 14 specifying the maximum number of
logical units. (The Task Builder allows you to specify more than 15
channels, but RSTSIE will give an error when the program is RUN.)

Default

UNITS=6
Example
RUN $TKB
TKB>PROG=OBJ1,OBJ2,LB:F4POTS/LB
TKB>/
ENTER OPTIONS:
TKB>UNITS=4
TKB>ASG=SY:O : l,LPO:3,TI:4
TKB> //

Task Builder Options

12-35

12.31 VARRAY - Virtual Array Specification and Usage
A virtual array in FORTRAN is a defined area outside of the virtual address
space of a task, but within the task's logical address space. The TKB assigns
the name $VIRT to the virtual array and automatically provides code to create
a dynamic region in memory. Refer to Section 7.7 for more dtails on the use of
virtual arrays. The VARRAY=OVR option specifies an overlaid virtual array so
that it may be used similarly to the way a FORTRAN COMMON is used. This
means that each segment of an overlaid task that uses it defines the array in
the same way as it is defined in the root segment. Thereafter, the segment may
access the array directly without passing arguments, as is necessary when the
array has the concatenated attribute (the default, VARRAY=CON).

To use the VARRAY option with the OVR attribute as VARRAY=OVR, you must
first define the array (for example, VIRTUAL DATA(lO», in the root segment of
the task. Then, you must define the array in the same way in each segment of
an overlaid task using the virtual array. Example 12-1 illustrates how a virtual
array may be directly accessed by segments in a task. The example also shows
the TKB command line and overlay description file for building the task.
Using the VARRAY option with the CON attribute as VARRAY=CON (the default
operation) results in a virtual array subject to the restrictions and uses that are
described in the reference manual for the specific kind of FORTRAN that you are
using.
Syntax
VARRAY=option
where:
is either OVR or CON.

option

Default

VARRAY==CON
Example 12-1:

A Task Using a Virtual Array with the OVR Attribute

Program to test the Task Builder option VARRAY

PROGRAM MAIN
IMPLICIT INTEGER *2 (A-Z)
VIRTUAL DATA(lO)
CALL INPUT
CALL CALC
CALL OUTPUT
CALL EXIT
END

(continued on next page)

12-36

Task Builder Options

Example 12-1 (Cant.):

10
20
30

A Task Using a Virtual Array with the OVR Attribute

SUBROUTINE INPUT
IMPLICIT INTEGER *2 (A-Z)
VIRTUAL DATA (10)
TYPE 10
FORMAT (lX,'INPUT I '$)
ACCEPT 20,DATA(1)
FORMAT (12)
TYPE 30
FORMAT (lX, 'INPUT J '$)
ACCEPT 20,DATA(2)
RETURN
END
SUBROUTINE CALC
IMPLICIT INTEGER *2 (A-Z)
VIRTUAL DATA (10)
DATA(3)
DATA(l) + DATA(2)
DATA(4)
DATA(l) - DATA(2)
DATA(5)
DATA(l) * DATA (2)
DATA(6)
DATA(l) I DATA(2)
RETURN
END

!I + J
!I - J
!I * J
!I I J

SUBROUTINE OUTPUT
IMPLICIT INTEGER *2 (A-Z)
VIRTUAL DATA(10)
TYPE 10.DATA(3),DATA(4),DATA(5),DATA(6)
FORMAT (lX, 'I + J =',I6,I,lX,'I - J =',16,1
1,lX'I * J=' ,I6,I,lX.'I I J =' ,16)
RETURN
END
Command file MAINFT.CMD to build MAINFT.TSK

,
MAINFT/FP,MAINFT/MA/-WI=MAINFT/MP
VARRAY=OVR

II
;Overlay description file MAINFT.ODL for MAINFT.TSK
. ROOT
$MAIN-*($INPT,$CALC,$OUTP)
MAIN-LB:[l,1]F770TS/LB
$MAIN: .FCTR
INPUT-LB: [l,1]F770TS/LB
$INPT: .FCTR
CALC-LB: [l,1]F770TS/LB
$ CALC .FCTR
.FCTR
OUTPUT-LB:[l,1]F770TS/LB
$OUTP
.END

Task Builder Options

12-37

12.32 VSECT-Virtual Program Section
Use the VSECT option to specify the virtual base address, virtual length, and,
optionally, the physical memory allocated to the named program section. It is
possible to have multiple VSECT lines in a task build; however, the sum total
of the phsyical lengths cannot exceed 255K words. The VSECT option does the
following two things during task build:
•

It adds the physical length to the offset value in the header so that the
RSTS/E monitor will know at run-time how large a dynamic region the task
will need.

•

It places the given PSECT name at the specified absolute address (usually an
APR boundary like 140000 octal) so that the program can relate the base of
the window that will be mapped to the code. To do this in MACRO-H, declare
the PSECT directly; in FORTRAN-77, use a COMMON statement of the form:
COMMON MARRAY!IARRAY

where:
MARRAY

is the PSECT name

IARRAY

is declared as an array

If the task being built is lID and one or more APRs are being used of I-only
library code (such as RMSRES), it is useful to use the D-APRs of that code with
the VSECT option as it is D-only mapping.

Refer to Section 7.6 for more information on virtual program sections.
Syntax

VSECT=p-sect-name:[base:window][physical-length]
where:
p-sect-name

is a 1- to 6-character program section name.

base

is an octal value representing the virtual base address of the
program section in the range of 0 to 177777. If you use the
mapping directives, the value you specify must be a multiple of

4K
window

is an octal value specifying the amount of virtual address space
in bytes allocated to the program section. Base plus window
must not exceed 177777. This is the maximum window size
that can be created with the CRAW$ function.

physical-length

is an octal value specifying the minimum amount of physical
memory to be allocated to the section in units of 64-byte
blocks. TKB rounds this value up to the next 256-word limit.
This value, when added to the task image size of any previous
allocation, must not exceed 255K words on RSTSIE (maximum
17740 octal). If you do not specify a length, TKB assumes a
value ofO.

Default

Physical length defaults to O.

12-38 Task Builder Options

12.33 WNDWS-Number of Address Windows
The WNDWS option declares the number of address windows required by the
program in addition to those needed to map the program and any declared (with
CLSTR, RESLIB, LIBR, SUPLIB, RESCOM, RESSUp, or COMMON) resident
area. In other words, you use this option to tell the Task Builder what windows
your program will access directly using the .PLAS mapping directives (see
the RSTS / E System Directives Manual). The number specified is equal to the
number of such simultaneously mapped regions the program will use.
Syntax

WNDWS=n
where:
n

is an integer in the range 0 to 23.

Default

WNDWS=O
Example
RUN $TKB
TKB> PROG=OBJ1,OBJ2
TKB> I
ENTER OPTIONS :
TKB> WNDWS=2
TKB> II

Task Builder Options

12-39

Chapter 13

Overlay Description Language (ODL)

The Task Builder provides a language, called the Overlay Description Language
(ODL), that allows you to describe the overlay structure of a program. You
construct a text file containing a series of ODL commands, one command per line.
You then refer to this file in a Task Builder command line, with an IMP switch,
as described in Chapter 3. For example:
RUN $TKB
TKB> OUT,MAP=OVERLY/MP

The ODL command file is named OVERLY.ODL (.ODL is the default file type).

13.1

OOL Command Line
An ODL line takes the form:

label: directive argument-list ;comment
A label is required only for the .FCTR command (see Section 13.3).
The ODL commands are listed below and are described in alphabetical order in
Sections 13.2 through 13.6.
.ROOT

specifies the entire overlay structure in tenns of (1) your separately
compiled or assembled program and subprogram files, (2) library files, (3)
program sections, and (4) names defined in .NAME or .FCTR commands.
These elements are connected by operators, which show the way the
elements are to be linked. Operators include the symbols:

-,* ()!
.FCTR

defines a "substructure" within the entire overlay structure. As with
.ROOT, the substructure is specified in tenns of object files, library
files, program sections, and names defined in .NAME or other .FCTR
commands. These elements are connected by the same operators used in
the .ROOT command.

.PSECT

allows you to directly specify the placement of a global program section
in an overlay structure. Thus, you can indicate the segment to which the
program section will be allocated.

.NAME

allows you to define a name and attributes for an overlay segment. An
overlay segment is a piece of the overlay structure that is stored on disk
such that it is loaded with one disk access.

.END

is used to end the overlay description.

Overlay Description Language (ODL)

13-1

13.2 The .END Command
Use the .END command as the last line in the ODL file. The .END command
tells the Task Builder where the input ends. The format of the .END command
is:
.END

13.3 The .FCTR Command
The .FCTR command lets you build large, complex overlay structures and
represent them clearly. The format of the .FCTR command is:
label: .FCTR structure
where:
label

at the beginning of the line is used as a part of the structure of a .ROOT
or another .FCTR command. The label must be unique with respect to file
names and other labels. The structure portion of the .FCTR command can be
made up of the same components as the structure of a .ROOT command.

The .FCTR command lets you extend the overlay tree description beyond the one
line possible in a .ROOT command. For example:
AFCTR:
BFCTR:
B2FCTR:
LIB:

.ROOT
.FCTR
. FCTR
.FCTR
.FCTR

AFCTR,BFCTR
A-LIB-(AI-LIB,A2-LIB)
B-LIB-(BI-LIB,B2FCTR)
B2-LIB(B21-LIB,B22-LIB,B23-LIB)
LB:F4POTS/LB

.END

In the example above, the AFCTR and BFCTR items in the .ROOT command
are expanded in following .FCTR commands. Likewise, B2FCTR and LIB are
defined in the third and fourth .FCTR commands. The B2FCTR item is defined
in a "nested" .FCTR command; that is, the B2FCTR item is defined by a .FCTR
command nested within the BFCTR item's defining .FCTR command. The .FCTR
command can be nested in this manner to 16 levels.

13.4 The .NAME Command
The .NAME command lets you give a name to a segment and then assign
attributes to a segment. As described in Chapter 3, a segment is a piece of your
overlay structure that can be loaded in one disk access.
The name you assign must be unique; that is, it must be different than file
names, program section names, .FCTR labels, and other segment names used in
the overlay description.
The chief purpose of the command is to assign a name to a null co-tree root
(Section 4.2), and to make a data segment autoloadable (Section 6.5 ).

13-2

Overlay Description Language (ODL)

The format of the .NAME command is:
.NAME segment-nameLattr][,attr]
where:
segment-name

is a one- to six-character name consisting of the characters A-Z,
0-9, and $. The name applies to the segment defined immediately
following the name when it is used in a .ROOT or .FCTR command.
A segment is formed by pieces connected by a dash (-) without
intervening parentheses. (Pieces connected by a comma are overlaid
and are stored as separate segments.)

attr

is one of the following:
GBL
Defines the segment-name as a global symbol. As
such, it can be referred to in transfer-of-control
statements from other pieces of the overlay structure.
When such a transfer of control is executed, the
segment is loaded, and control is returned to the
statement or instruction immediately following
the call. Used chiefly in making data segments
autoloadable (see Section 6.5).
NOGBL

Does not define the segment-name as a global symbol.
Hence, the name cannot be referred to in transfer-of
control statements from other pieces of the overlay
structure. If the GBL attribute is not specified,
NOGBL is assumed. You would use this attribute
when using .NAME to define a null segment as a
co-tree root (see Section 4.2).

NODSK

No disk space is allocated to the named segment in
the executable file. If a data overlay segment has no
initial values but will be generated by the running
program, there is no need to reserve space for it. If
you request this option, and the code in your program
assigns initial data values to the segment, the Task
Builder terminates the build with a fatal error:
LOAD ADDR OUT OF RANGE IN MODULE
file-name

DSK

Disk space is allocated to the named segment in the
executable file. If you do not specify NODSK, DSK is
assumed.

If more than one name is applied to a segment, the attributes of the last name
given take effect.

13.5 The .PSECT Command
You use the .PSECT command to define the name and attributes of a program
section that you want to place in the structure of a .ROOT or .FCTR command.
In other words, you can directly specify the placement of a program section
named in a .PSECT command.
The general form of the .PSECT command is:
.PSECT p-name[,attrl][,attr2]. .. [,attr4]
where:
p-name

is the name of the program section (a one- to six-character name consisting
of the character A-Z, 0-9, or $).

Overlay Description Language (ODL)

13-3

attr[i]

The attr parameters can be any of the following:
GBL
A global program section, or
LCL

A local program section.

A read/write program section, or

A read-only program section.

REL

A relocatable program section, or

ABS

An absolute program section.

OVR

An overlaid program section, or

CON

A concatenated program section.

SAY

A program section with the save attribute.

A program section contains data.

A program section contains instructions and/or data.

For example, suppose a program consists of the file CNTRL as a root, with
overlays A, B, and C. Suppose that CNTRL calls A, B, C, and A again, and that A
contains a common block named DATA3. The first execution of A stores data in
DATA3, and the second execution of A needs this data. The common block DATA3
must be moved to the root segment, where it will not be overlaid with the old
values when A is read in from disk for its second execution. This is accomplished
by the following ODL file:

LIB:

.PSECT DATA3,RW,GBL,REL,OVR
.ROOT CNTRL-DATA3-LIB-*(A-LIB,B-LIB,C-LIB)
.FCTR LB:F4POTS/LB
.END

See the PDP-ll MACRO-ll Language Reference Manual for more information
about .PSECTs.

13.6 The .ROOT Command
Each overlay description must have one, and only one .ROOT command. The
.ROOT command defines the overlay structure. The general format of the
command is:
.ROOT structure
where:
structure

is a series of file specifications for your separately compiled object programs, library files, program section names, or names defined in .FCTR
or .NAME commands.

These items are connected by the following operators:
1. The hyphen (-) operator indicates the concatenation of two items. For

example, X-Y means that sufficient virtual address space will be allocated to
contain the items X and Y simultaneously. The Task Builder allocates X and
Y in sequence.
2. The comma (,) operator, appearing within parentheses, indicates the
overlaying of virtual address space. For example, (Y,Z) means that the virtual
address space can contain either Y or Z; they overlay each other. Parentheses
can be nested to 16 levels.
The comma operator outside of parentheses is used to define multiple tree
structures.

13-4 Overlay Description Language (ODL)

3. The exclamation point (!) operator indicates memory-resident overlays in a
resident area (see Chapter 7).
4.

The asterisk operator (*) indicates that autoload vectors are to be generated
for the following piece or pieces of the overlay structure. Unless you want to
save space by carefully applying autoload indicators (Chapter 5), the simplest
way to use the asterisk is immediately before the outermost left parenthesis
in your ODL file. And, for co-trees, put additional asterisks before a non-null
co-tree root segment and any co-tree's outermost left parenthesis.

For example:
.ROOT X-*(Y,Z(Zl,Z2))
.END

The .ROOT command in this ODL file describes the following overlay tree.

x
I
y
Z

Z2
MK-01053-00

The units Y and Z overlay each other, as do Zl and Z2.

13.7 Indirect Command Files
The ODL processor can accept ODL text specified in an indirect command file.
If an at sign (@) appears as the first character in a line, the processor reads text

from the file specified immediately after the at sign character.
For example, suppose you create a file, called BIND.ODL, that contains the text:
B:

.FCTR Bl-(B2,B3)

This text can be inserted by a line beginning with @BIND in another ODL file:

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

@BIND
.END

This has the same effect as an ODL file with the following commands:

c:
B:

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

The Task Builder allows two levels of indirection. That is, you can place a
reference to an indirect command file in an indirect command file. (However,
note that excessive use of indirect command files will degrade Task Builder
performance.)

Overlay Description Language (ODL)

13-5

Appendixes

Appendix A

Error Messages

This appendix lists the error messages produced by the Task Builder. Error
messages are printed in two forms:
•

%TKB-*DIAG*-error-message

•

?TKB-*FATAL*-error-message

When you give commands to the Task Builder from a terminal (rather than from
a command file), you can correct some errors as you go along. These errors are
noted with the *DIAG* heading. Correct the error and the build will proceed.
Indeed, some of the errors merely tell you about an unusual condition. If you can
live with the condition, or consider it to be normal to your program, you can go
ahead with the build and run the executable file produced.
The errors headed by *FATAL* abort the build; you have to start over.
Messages and their explanations are listed below. If the explanation refers to a
system error, or says that the error should not occur on RSTSIE systems, please
send a Software Performance Report (SPR) to Digital.
ALLOCATION FAILURE ON FILE filename

The Task Builder could not find enough disk space to store the executable program file or did not have write access to the account or disk that was to contain
the file.
BLANK P-SECTION NAME IS ILLEGAL odl-line

The overlay description line printed contains a .PSECT command that does not
have a program section name.
CLUSTER LIBRARY ELEMENT, element-name, IS NOT RESIDENT OVERLAID

The listed cluster element was built without memory-resident overlays. This kind
of element cannot be used as a cluster library element. Cluster libraries 2-6 must
be memory-resident and overlaid.
COMMAND 1/0 ERROR

An 110 error occurred for an input file in a Task Builder command. The device
may not be on line, or there may be a hardware error.
COMMAND SYNTAX ERROR command-line

The command line given is specified incorrectly. See Part IV for the correct syntax
for the command.

Error Messages A-1

COMPLEX RELOCATION ERROR - DIVIDE BY ZERO: MODULE filename

A zero divisor was detected in a complex expression. The result of the division
was set to zero. (A probable cause is division by a global symbol whose value is
undefined. You can set a value for a global symbol with the GBLDEF option to
correct this.)
FILE filename ATTEMPTED TO STORE DATA IN VIRTUAL SECTION

You should not get this error running the Task Builder on RSTSIE systems. It
diagnoses an error for a capability not used on RSTSIE.
FILE filename HAS ILLEGAL FORMAT

The file named is in an invalid format. This can occur if you try to build a
text file, such as a source file. Input files must be compiled or assembled object
program files or library files containing compiled or assembled object routines.
ILLEGAL APR RESERVATION

An APR parameter specified in a COMMON, LIBR, SUPLIB, RESCOM, RESSUp,
or RESLIB option is outside the range 0-7.
ILLEGAL DEFAULT PRIORITY SPECIFIED

Note that this error relates to the PRI option, which is ignored on RSTSIE
systems. The error is returned if you specify an illegal value in the use of the PRI
option.
ILLEGAL ERROR-SEVERITY CODE octal-list

System error (no recovery). Please send Digital a Software Performance Report
(SPR) with a copy of the message containing the octal-list as printed.
ILLEGAL FILENAME invalid-line

The invalid line printed contains a wildcard (*) in a file specification. You cannot
use wildcards in file specifications for the Task Builder.
ILLEGAL GET COMMAND LINE ERROR CODE

System error (no recovery). Please send an SPR to Digital.
ILLEGAL LOGICAL UNIT NUMBER invalid-line

You tried to assign a device (ASG option) to a logical unit number larger than the
available number of logical units (UNITS option or the default of 6 if the UNITS
option is not specified).
ILLEGAL MULTIPLE PARAMETER SETS invalid-line

You tried to specify more parameters for an option than the option format calls
for. See Chapter 12 for the correct format for options.
ILLEGAL NUMBER OF LOGICAL UNITS invalid-line

You cannot specify a logical unit number greater than 14.
ILLEGAL ODT OR TASK VECTOR SIZE

You should not get this error on RSTSIE systems; it diagnoses an error for an
option not processed by RSTSIE.

A-2

Error Messages

ILLEGAL OVERLAY DESCRIPTION OPERATOR invalid-line

The invalid line printed is an ODL line that contains an operator that the Task
Builder does not recognize. This error occurs if the first character in a program
section or segment name is a period (.).
ILLEGAL OVERLAY DIRECTIVE invalid-line

The invalid line printed contains an unrecognizable overlay command.
ILLEGAL PARTITION/COMMON BLOCK SPECIFIED

You tried to specify a partition option (PAR) or resident area access option
(COMMON, LIBR, RESCOM, RESLIB, RESSUp, OR SUPLIB) defining a resident
area as starting not on a 32-word boundary.
ILLEGAL P-SECTION/SEGMENT ATTRIBUTE

You tried to define an attribute for a program section or segment that is not
recognizable to the Task Builder. See the description of the .PSECT command or
.NAME command in Chapter 13.
ILLEGAL REFERENCE TO LIBRARY P-SECTION psect-name

Your program attempts to refer to a program section name that exists in a runtime system or resident area but has not named the run-time system or area in a
COMMON, HISEG, LIBR, RESCOM, RESLIB, RESSUP, SUPLIB or option.
ILLEGAL SWITCH file-specification

The file specification printed contains an illegal switch or switch value.
INCOMPATIBLE OTS MODULE

TKB did not find the Overlay Run-Time System (OTS) module. The OTS modules
are part of the system library. This error occurs if you are using an incompatible
version of the system library (SYSLIB.OLB).
INCOMPATIBLE REFERENCE TO LIBRARY P-SECTION psect-name

Your program attempts to refer to more storage in a run-time system or resident
library than exists in the run-time system or resident library definition.
INCORRECT LIBRARY MODULE SPECIFICATION invalid-line

The invalid line printed names a library routine name with an invalid character.
Valid characters are A-Z, 0-9, space, dollar sign ($), or period (.).
INDIRECT COMMAND SYNTAX ERROR invalid-line

The invalid line printed is a command from an indired file. You must correct the
syntax of the command in the indirect file.
INDIRECT FILE OPEN FAILURE invalid-line

The invalid line printed refers to a command input file that could not be located.
INSUFFICIENT PARAMETERS invalid-line

The invalid line printed contains too few parameters. See Part IV for the correct
format for command lines, switches, and options.

Error Messages

A-3

INVALID APR RESERVATION invalid-line

You specified an APR on an option dealing with an absolute resident area. An
absolute resident area is built to occupy the same virtual address space each time
it is used; you do not specify an APR in this case.
INVALID KEYWORD IDENTIFIER invalid-line

The invalid line printed contains an unrecognizable option.
INVALID PARTITION/COMMON BLOCK SPECIFIED

The base address of a partition defined in a PAR option is not on a 4K boundary
or is not 0, or the memory bounds for the partition overlap a run-time system or
other resident area.
INVALID REFERENCE TO MAPPED ARRAY BY MODULE filename

The module has attempted to initialize the mapped array with data. An SPR
should be submitted if Digtial-supplied software caused this problem.
INVALID WINDOW BLOCK SPECIFICATION

The number of extra address windows requested with the WNDWS option cannot
exceed 23.
1/0 ERROR LIBRARY IMAGE FILE

An 1/0 error occurred during an attempt to open or read the symbol table file
(.STB file type) for a run-time system or resident area.
1/0 ERROR ON INPUT FILE filename

An I/O error occurred during an attempt to open or read an input file in the Task
Builder command line. This error message can also occur if your command line is
too long (greater than 80 characters).
1/0 ERROR ON OUTPUT FILE filename

An I/O error occurred during an attempt to open or write to an output file in the
Task Builder command line.
LABEL OR NAME IS MULTIPLY DEFINED invalid-line

The invalid line printed defines a name that has already appeared in 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. (The specified library has no routines.)
LIBRARY REFERENCES OVERLAID LIBRARY invalid-line

An attempt was made to link the resident library being built to a resident area
that has memory-resident overlays.
LOAD ADDR OUT OF RANGE IN MODULE filename

An attempt has been made to store data in the executable file outside the address
limits of the segment. This problem is usually caused by one of the following:
..

A-4

An attempt to initialize a program section contained in a run-time system or
resident area.

Error Messages

An attempt to initialize an absolute location outside the limits of the segment
or in the header.

A patch outside the limits of the segment it applies to.

An attempt to initialize a segment having the NODSK attribute.

LOOKUP FAILURE ON FILE filename invalid-line

The invalid line printed contains a file name that cannot be located.
LOOKUP FAILURE ON SYSTEM LIBRARY FILE

The Task Builder cannot find the system library file to resolve undefined symbols.
The system library is LB:SYSLIB.OLB unless defined otherwise with a IDL
switch.
LOOKUP FAILURE RESIDENT LIBRARY FILE invalid-line

No symbol table (.STB) file or executable file (.TSK) can be found for the run-time
system or resident area.
MAXIMUM INDIRECT FILE DEPTH EXCEEDED invalid-line

The invalid line printed gives the file reference that exceeded the permissible
indirect file depth (2).
MODULE filename AMBIGUOUSLY DEFINES P-SECTION psect-name

The program section named has been defined in two pieces of the overlay structure that are not on a common path and is referred to by a segment that is
common to both paths.
MODULE filename AMBIGUOUSLY DEFINES SYMBOL sym-name

The file named refers to or defines a symbol. The symbol definition exists on two
different paths but is referenced by a segment common to both paths.
MODULE filename ILLEGALLY DEFINES XFR ADDRESS psect-name addr

This error is caused by one of the following:
1.

The start address printed is odd (it must be even).

2. The file containing the start address is in an overlay segment. The start
address must be in the root segment of the main tree.
3. The address is in a program section that has not yet been defined. Please
send an SPR to Digital if this is caused by Digital-supplied software.
MODULE filename MULTIPLY DEFINES P-SECTION psect-name

The program section named has been defined more than once in the same segment with different attributes.
Or, a global program section has been defined more than once with different
attributes in more than one segment along a common path.
MODULE filename MULTIPLY DEFINES SYMBOL sym-name

Two definition for the relocatable symbol sym-name have occurred on a common
path.
Or, two definitions for an absolute symbol with the same name but two different
values have occurred.

Error Messages

A-5

MODULE filename MULTIPLY DEFINES XFR ADDR IN SEG segment-name

More than one file making up the root has a start address.
MODULE routine-name NOT IN LIBRARY

The Task Builder could not find the routine named on the ILB switch in the
library specified.
NO DYNAMIC STORAGE AVAILABLE

The Task Builder needs additional storage for a symbol table and cannot find it.
Refer to Appendix E for ways to optimize Task Builder performance.
NO MEMORY AVAILABLE FOR LIBRARY library-name

The Task Builder could not find enough free virtual memory to map the specified
run-time system or resident area. Refer to Appendix E for ways to optimize Task
Builder p~rformance.
NO ROOT SEGMENT SPECIFIED

You must specify one .ROOT command in the overlay description file.
NO VIRTUAL MEMORY STOR~GE AVAILABLE

The maximum allowable size of the Task Builder work file was exceeded. See
Section 7.5.6 for suggestions on reducing the size of the work file.
ONLY ONE HISEG MAY BE SPECIFIED

You attempted to specify more than one high segment. The command that
generated this error is ignored.
OPEN FAILURE ON FILE filename

An 110 error occurred while the Task Builder was attempting to open the specified
file. Try the build again. If you get the same error, see your system manager and
report the 1/0 error.
OPTION SYNTAX ERROR invalid-line

The invalid line printed contains an option that the Task Builder cannot process
because it is specified incorrectly. See Chapter 12 for the correct syntax for
options.
OVERLAY DIRECTIVE HAS NO OPERANDS

All overlay commands except .END require operands.
OVERLAY DIRECTIVE SYNTAX ERROR invalid-line

The invalid line printed contains a syntax error or refers to a line that contains
an error.
PARTITION par-name HAS ILLEGAL MEMORY LIMITS

The partition named is longer than the available address space.
PASS CONTROL OVERFLOW AT SEGMENT segment-name

System error. Please send an SPR to Digital with a copy of the ODL file associated with the error.

A-6

Error Messages

PIC LIBRARIES MAY NOT REFERENCE OTHER LIBRARIES

You have tried to build a position-independent resident area that refers to another
resident area.
P-SECTION psect-name HAS OVERFLOWED

You have tried to create a program section larger than (32K-32) words.
REQUIRED INPUT FILE MISSING

At least one input file is required for a build.
REQUIRED PARTITION NOT SPECIFIED

You should not get this error on RSTSIE systems. It diagnoses an error for a
capability not used on RSTSIE.
RESIDENT LIBRARY HAS INCORRECT ADDRESS ALIGNMENT invalid-line

The invalid line printed specifies a resident area that has one of the following
problems:

1. The library refers to another library with invalid address bounds (that is, not
on 4K word boundary).
2. The library has invalid address bounds.
RESIDENT LIBRARY MAPPED ARRAY ALLOCATION TOO LARGE invalid-line

The invalid-line displayed contains a reference to a shared region that has
allocated too much memory in the task's mapped array area. The total allocation
exceeds the system limit; the maximum usable size on RSTSIE is 255K words.
RESIDENT LIBRARY MEMORY ALLOCATION CONFLICT option

One of the following problems has occurred. You tried to specify:
•

More than 7 resident areas.

•

The same resident area more than once.

•

Absolute resident areas whose memory allocations overlay.

ROOT SEGMENT IS MULTIPLY DEFINED invalid-line

The invalid line printed contains the second .ROOT command encountered in an
ODL file. Only one .ROOT command is allowed.
SEGMENT seg-name HAS ADDR OVERFLOW: ALLOCATION DELETED

Within a segment, the program attempted to allocate more than (32K-32) words.
A map file is produced if it was specified, but no executable file is produced.
TASK HAS ILLEGAL MEMORY LIMITS

You have tried to build a program whose size exceeds the allowable memory
size. (This may be the size defined in a PAR option.) If an executable file was
produced, delete it.
TASK HAS ILLEGAL PHYSICAL MEMORY LIMITS
mapped-array executable-program program extension

The sum of the values displayed-mapped array size, executable program size,
and program extension size-exceeds 2.2 million bytes. The quantities are shown
as octal numbers in units of 64-byte blocks. Delete any resulting executable
program file.
Error Messages A-7

TASK IMAGE FILE filename IS NON-CONTIGUOUS

This error will only occur if your disk is so fun that RSTSIE cannot find contiguous space for your program. The file is therefore created noncontiguous; you can
otherwise ignore the error message.
TASK REQUIRES TOO MANY WINDOW BLOCKS

The number of address windows required by the program and any resident areas
is more than 16. Only 16 are available.
TASK-BUILD ABORTED VIA REQUEST option-line

The option-line printed contains your request to abort the build. You can now
retype commands to rerun the Task Builder.
TOO MANY NESTED .ROOT/.FCTR DIRECTIVES invalid-line

The invalid line printed contains a .FCTR command that exceeds the maximum
of 16 nested .FCTR commands.
TOO MANY PARAMETERS invalid-line

The invalid line printed contains an option with more parameters than required.
TOO MANY PARENTHESES LEVELS invalid-line

The invalid line printed contains nested parentheses that exceed the maximum of
16 nested parentheses.
TRUNCATION ERROR IN MODULE filename

You tried to load a global value greater than +127 or less than -128 into a byte.
Only the low-order eight bits are loaded.
UNABLE TO OPEN WORK FILE

This error can result from several conditions. For example, the device is full, or
the work file is assigned to a private pack where you do not have an account, or
the work file device is either not mounted or is mounted read-only.
UNBALANCED PARENTHESES invalid-line

The invalid line printed contains unbalanced parentheses. The number of left
parentheses must equal the number of right parentheses.
n UNDEFINED SYMBOLS SEGMENT seg-name

The segment named contains n undefined symbols. If you did not request a
memory map file, the symbols are also printed at your terminal.
VIRTUAL SECTION HAS ILLEGAL ADDRESS LIMITS option

This error means that the virtual section was declared larger than the limit on
RSTSIE.
WORK FILE i/O ERROR

An 1/0 error occurred during an attempt to refer to data stored by the Task
Builder in its work file.

A-a Error Messages

Appendix B

Task Builder Input Data Formats
A compiled or assembled program (.OBJ file), called an object module, consists of
variable-length record information. Six record (or block) types are included in the
object language. These records guide the Task Builder in the translation of the
object language into a task image.
The six record types are:
..

Type 1 - Declare Global Symbol Directory (GSD)

Type 2 - End of Global Symbol Directory

Type 3 - Text Information (TXT)

Type 4 - Relocation Directory (RLD)

•

Type 5 - Internal Symbol Directory (ISD)

Type 6 - End of Module

Each object module must consist of at least five of the record types. The
only record type that is not mandatory is the internal symbol directory. The
appearance of the various record types in an object module follows a defined
format. See Figure B-l.

An object module must begin with a GSD record and end with an end-of-module
record. Additional GSD records can occur anywhere in the file but must appear
before an end-of-GSD record. An end-of-GSD record must appear before the
end-of-module record, and at least one relocation directory record (RLD) must
appear before the first text information record (TXT). Additional RLDs and TXTs
can appear anywhere in the file. The internal symbol directory records (ISDs) can
appear anywhere in the file between the initial GSD and end-of-module records.
Object module records are of 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.

Task Builder Input Data Formats

B-1

Figure 8-1:

r----...... -

General Object Module Format

GSD

INITIAL GSD

RLD

INITIAL RELOCATION DIRECTORY

GSD

ADDITIONAL GSD

TXT

TEXT INFORMATION

TXT

TEXT INFORMATION

RLD

RELOCATION DIRECTORY

~
GSD
END GSD

ADDITIONAL GSD
END GSD

ISD

INTERNAL SYMBOL DIRECTORY

ISD

INTERNAL SYMBOL DIRECTORY

TXT

TEXT INFORMATION

TXT

TEXT INFORMATION

TXT

TEXT INFORMATION

END MODULE

END OF MODULE
MK-Q105&-OO

B-2

Task Builder Input Data Formats

B.1

Global Symbol Directory
Global symbol directory (GSD) records contain all the information necessary to
assign addresses to global symbols and to allocate the memory required by a task.
GSD records are the only records processed in the first pass. You can save a
significant amount of time if you put all GSD records at the beginning of a
module, because less of the file must be read on the first pass.
GSD records contain the nine types of entries listed in Table B-l.
Table 8-1:

GSD Entry Types

Type (Octal)

Entry

Module Name

Control Section Name

Internal Symbol Name

Transfer Address

Global Symbol Name

Program Section Name

Program Version Identification

Mapped Array Declaration

Completion Routine Name

Task Builder Input Data Formats

8-3

There are four words in the GSD record for each entry type. The first two words
contain six Radix-50 characters. The third word contains a flag byte and the
entry type identification. The fourth word contains additional infonnation about
the entry. See Figure B-2.

Figure 8-2:

GSD Record and Entry Format

a
RADIX-50
NAME
ENTRY TYPE

FLAGS
VALUE

RADIX-50
NAME
ENTRY TYPE

FLAGS
VALUE

RADIX-50
NAME
ENTRY TYPE

FLAGS
VALUE
RADIX-50
NAME

ENTRY TYPE

FLAGS
VALUE
MK-01057-00

8-4 Task Builder Input Data Formats

8.1.1

Module Name
The module name entry, as illustrated in Figure B-3, declares the name of the
object module. The name need not be unique with respect to other object modules
because modules are identified by file, not module name. Only one module name
entry can occur in any given object module.
Figure 8-3:

Module Name Entry Format

MODULE
NAME

MK-01058-00

8.1.2

Control Section Name
Control sections, which include ASECTs, blank CSECTs, and named CSECTs,
are supplanted by PSECTs. For compatibility with other systems, Task Builder
processes ASECTs and both forms of CSECTs. Section B.1.6 details the entry
generated for a PSECT statement. In terms of the PSECT directive, ASECT and
CSECT statements can be defined as follows:
•

For a blank CSECT, the PSECT definition is:
.PSECT ,LCL,REL,CON,RW,I,LOW

•

For a named CSECT, the PSECT definition is:
.PSECT name, GBL,REL,OVR,RW, I,LOW

•

For an ASECT, the PSECT definition is:
.PSECT . ABS.,GBL,ABS,I,OVR,RW,LOW

ASECTs and CSECTs are processed by the Task Builder as PSECTs with the
fixed attributes defined above. The entry generated for a control section is shown
in Figure B-4.

Task Builder Input Data Formats

8-5

Figure 8-4:

Control Section Name Entry Format

CONTROL SECTION
NAME

(Ignored)

MAXIMUM LENGTH

MK-01058-01

8.1.3

Internal Symbol Name
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,
so the detailed format of this entry is not defined (Figure B-5). Any internal
symbol entry encountered while the Task Builder reads the GSD is ignored.
Figure 8-5:

Internal Symbol Name Entry Format

SYMBOL
NAME

UNDEFINED

M K-O 1059-00

8.1.4

Transfer Address
The transfer address entry, as illustrated in Figure B-6, declares the transfer
address of a module relative to a PSECT. The first two words of the entry define
the name of the PSBCT, and the fourth word defines the relative offset from
the beginning of that PSECT. If no transfer address is declared in a module,
a transfer address entry either must not be included in the GSD or a transfer
address 000001 relative to the default absolute PSECT (.ABS.) must be specified.

B-6

Task Builder Input Data Formats

Figure B-6:

Transfer Address Entry Format

PSECT
NAME
3

I
OFFSET

MK-01059-01

NOTE
If the PSECT is absolute and OFFSET is not 000001, then OFFSET is

the actual transfer address.

8.1.5

Global Symbol Name
The global symbol name entry, as illustrated in Figure B-7, declares either a
global reference or a definition. All definition entries must appear after the
declaration of the PSECT they are defined in and before the declaration of
another PSECT. Global references can appear anywhere within the GSD.
Figure B-7:

Global Symbol Name Entry Format

SYMBOL
NAME
4

FLAGS

VALUE

MK-O 1059-02

The first two words of the entry define the name of the global symbol. The flag
byte declares the attributes of the symbol, and the fourth word declares the value
of the symbol relative to the PSECT it is defined in.

Task Builder Input Data Formats

B-7

The flag byte of the symbol declaration entry has the following bit assignments:
Bit 0 - Weak Qualifier

o =

Symbol is a strong definition or reference and is resolved in the normal
manner.

Symbol is a weak definition or reference. A weak reference (Bit 3 =0)
is ignored. A weak definition (Bit 3 = 1) is ignored unless a previous
reference has been made.

Bit 1 - Not used
Bit 2 - Definition Type

o
1

=
=

Normal Definition of 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.

Bit 3 - Reference or Definition

o =
1

Global symbol reference.

= Global symbol definition.

Bit 4 - Not used
Bit 5 - Relocation

o =

Absolute symbol value.

Relative symbol value.

Bit 6-7 - Not used

8.1.6

PSECT Name
The PSECT name entry, as illustrated in Figure B-8, declares the name of a
PSECT and its maximum length in the module. It also declares the attributes of
the PSECT in the flag byte.
Figure 8-8:

PSECT Name Entry Format

PSECT
NAME
5

FLAGS

MAX LENGTH

MK-01060-00

8-8 Task Builder Input Data Formats

GSD records must be constructed such that, once a PSECT name has been
declared, all global symbol definitions pertaining to it must appear before another
PSECT name is declared. Global symbols are declared in symbol declaration
entries. Thus, the normal format is a series of PSECT names each followed by
optional symbol declarations.
The flag byte of the PSECT entry has the following bit assignments:
Bit 0 - SAY PSECT

o
1

=
=

N onnal PSECT.
PSECT is forced into the root of the task.

Bit 1 - Library PSECT

N onnal PSECT.

Relocatable PSECT that references a resident library or common block.

Bit 2 - Allocation

PSECT references are to be concatenated with other references to the
same PSECT to fonn the total memory allocated to the PSECT.

PSECT references are to be overlaid. The total memory allocated to the
PSECT is the largest request made by individual references to the same
PSECT.

Bit 3 - Reserved for the Task Builder
Bit 4 - Access

PSECT has readJwrite access.

PSECT has read-only access.

Bit 5 - Relocation

PSECT is absolute and requires no relocation.

PSECT is relocatable, and references to the control PSECT must have a
relocation bias added before they become absolute.

Bit 6 - Scope

The scope of the PSECT is local. References to the PSECT are collected
only within the segment in which the PSECT is defined.

The scope of the PSECT is global. References to the PSECT are collected
across segment boundaries. The segment in which a global PSECT is
allocated storage is detennined either by the first module that defines the
PSECT on a path or by direct placement of a PSECT in a segment by the
.PSECT directive.

The PSECT contains instruction (I) references.

The PSECT contains data (D) references.

Bit 7 - Type

NOTE

The length of all absolute PSECTs is zero.

Task Builder Input Data Formats

8-9

8.1.7

Program Version Identification
The program version identification entry, as illustrated in Figure B-9, declares
the version of the module. The Task Builder saves the version identification
of the first module that defines a nonblank version. This identification is then
included on the memory allocation map and is written 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 8-9:

Program Version Identification Entry Format

VERSION
IDENTIFICATION
6

MK-01060-01

8.1.8

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 location. 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 O.

8-10

Task Builder Input Data Formats

One additional window block is allocated whenever a mapped array is declared.
Figure B-IO illustrates the mapped array declaration entry format.

Figure 8-10:

Mapped Array Declaration Entry Format

MAPPED ARRAY
NAME
ENTRY = 7
TYPE

FLAGS

LENGTH (NUMBER OF 64-BYTE BLOCKS)

8.1.9

Completion Routine Definition (Type 10)
The completion routine defintion declares the entry point for completion routine
of a supervisor-mode library. The data structure is created by the Task Builder
and appears only in symbol definition files of supervisor mode libraries.
As shown in figure B-ll, 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.

Figure 8-11:

Completion Routine Entry Format

COMPLETION ROUTINE
NAME
ENTRY
= 10
TYPE

0
VALUE

Task Builder Input Data Formats

8-11

B.2 End of Global Symbol Directory
The end-of-global-symbol-directory record, as illustrated in Figure B-12, declares
that no other GSD records are contained farther on in the module. Exactly one
end-of-GSD record must appear in an object module. Its length is one word.
Figure 8-12:

End-of-GSD Record Format

MK-01060-02

B.3 Text Information
The text information record, as illustrated in Figure B-13, 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.
Text records can contain words or bytes or a combination of both of information
whose final contents have not been determined yet. This information will be
bound by a record (see Section B.4). If the test record does not need modification,
then no relocation directory record is needed. Thus, multiple text records can
appear in sequence before a relocation directory record.
The load address of the text record is specified as an offset from the current
PSECT base. At least one relocation directory record must precede the first text
record. This directory must declare the current PSECT.

8-12

Task Builder Input Data Formats

Figure 8-13:

Text Information Record Format

3
LOAD ADDRESS

TEXT

TEXT
MK-Q1061-QO

The Task Builder writes a text record directly into the task image file and
computes the value of the load address minus four. This value is stored in
anticipation of a subsequent relocation directory that modifies words and bytes
that are contained in the test record. When added to a relocation directory
displacement byte, this value yields the address of the word and byte to be
modified in the task image.

Task Builder Input Data Formats

8-13

8.4 Relocation Directory
Relocation directory records (see Figure B-14) contain the information necessary
to relocate and link the preceding text information record. Every module
must have at least one relocation directory record that precedes the first text
information record. The first record does not modify a preceding text record but
rather defines the current PSECT and location. Relocation directory records
contain 15 types of entries. These entries are classified as relocation or location
modification entries. Table 7-2 lists the defined types.
Table B-2: Types of Entries for Relocation Directory Records
Type 8

Definition

Internal Relocation

Global Relocation

Internal Displaced Relocation

Global Displaced Relocation

Global Additive Relocation

Global Additive Displaced Relocation

Location Counter Definition

Location Counter Modification

Program Limits

PSECT Relocation

Not used

PSECT Displaced Relocation

PSECT Additive Relocation

PSECT Additive Displaced Relocation

Complex Relocation

Additive Relocation

Each type of entry is represented by a command byte (specifies type of entry
and 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 text
information record (see Section B.3), yields the virtual address in the image
that is to be modified. The command byte of each entry has the following bit
assignments:
Bit 0 - 6
Specify the type of entry. Potentially, the 128 command types can be specified,
although only 1510 are implemented.
Bit 7 - Modification

o =
1

The command modifies an entire word.

= The command modifies only one byte. The Task Builder checks for truncation errors in byte modification commands. If truncation is detected,
that is, if the modification value has a magnitude greater than 255, an
error occurs.

8-14 Task Builder Input Data Formats

Figure 8-14:

Relocation Directory Record Format

OISP

CMO

INFO

~~
CMO

INFO

OISP

INFO

OISP

CMO

INFO

INFO
MK-01062-00

8.4.1

Internal Relocation
The internal relocation entry illustrated in Figure B-15 relocates a direct pointer
to an address within a module. The current PSECT base address is added to
a specified constant, and the result is written 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.)

Task Builder Input Data Formats

8-15

For example:
A:

MOV

#A,RO

or
. WORD

Figure 8-15:

Internal Relocation Entry Format

OISP
CONSTANT

MK-01063-00

8.4.2

Global Relocation
The global relocation entry in Figure B-16 relocates a direct pointer to a global
symbol. The definition of the global symbol is obtained and the result is written
into the task image file at the calculated address.
For example:
MOV

#GLOBAL,RO

or
GLOBAL

. WORD

Figure 8-16:

OISP

Global Relocation Entry Format

IB I

SYMBOL
NAME

MK-O i 063-01

B.4.3

Internal Displaced Relocation
The internal displaced relocation entry in Figure B-17 relocates a relative
reference to an absolute address from within a relocatable control section. The
address plus 2 that the relocated value is to be written into is subtracted from
the specified constant. The result is then written into the task image file at the
calculated address.

8-16

Task Builder Input Data Formats

For example:
177550

CLR

or
MOV

Figure 8-17:

177550,RO

Internal Displaced Relocation Entry Format

OISP

CONSTANT

MK-01063-02

B.4.4

Global Displaced Relocation
The global displaced relocation entry in Figure B-18 relocates a relative reference
to a global symbol. The definition of the global symbol is obtained, and the
address plus 2 that the relocated value is to be written into is subtracted from
the definition value. The result is then written into the task image file at the
calculated address.
For example:
CLR

GLOBAL

or
GLOBAL,RO

MOV

Figure 8-18:

OISP

Global Displaced Relocation Entry Format

IB I

SYMBOL
NAME

MK-01063-03

Task Builder Input Data Formats

B-17

8.4.5

Global Additive Relocation
The global additive relocation entry in Figure B-19 relocates a direct pointer to
a global symbol with an additive constant. The definition of the global symbol is
obtained, the specified constant is added, and the resultant value is then written
into the task image file at the calculated address.
For example:
4tGLOBAL+2,RO

MOV

or
. WORD

Figure 8-19:

GLOBAL-4

Global Additive Relocation Entry Format

OISP

SYMBOL
NAME

CONSTANT
MK-01064-00

8.4.6

Global Additive Displaced Relocation
The global additive displaced relocation entry in Figure B-20 relocates a relative
reference to a global symbol with an additive constant. The definition of the
global symbol is obtained, and the specified constant is added to the definition
value. The address plus 2 that the relocated value is to be written into is
subtracted from the resultant additive value. The result is then written into the
task image file at the calculated address.
For example:
CLR

GLOBAL+2

or
MOV

8-18 Task Builder Input Data Formats

GLOBAL-5,RO

Figure 8-20:

Global Additive Displaced Relocation Entry Format

OISP

SYMBOL
NAME

CONSTANT
MK-01064-01

8.4.7

Location Counter Definition
The location counter definition in Figure B-2! declares a current PSECT and
location counter value. The control base is stored as the current control section,
and the current control section base is added to the specified constant and stored
as the current location counter value.
Figure 8-21:

Location Counter Definition

PSECT
NAME

CONSTANT
MK-01064-02

Task Builder Input Data Formats

8-19

8.4.8

Location Counter Modification
The location counter modification entry in Figure B-22 modifies the current
location counter. The current PSECT base is added to the specified constant and
the result is stored as the current location counter.
For example:
.=.+N

or
.BLKB

Figure 8-22:

Location Counter Modification

CONSTANT

MK-01065-00

8.4.9

Program Limits
The program limits entry in Figure B-23 is generated by the .LIMIT assembler
directive. The first address above the header (normally the beginning of the
stack) and the highest address allocated to the task are obtained and written into
the task image file at the calculated address and at the calculated address plus 2
respectively.
For example:
.LIMIT

Figure 8-23:

Program Limits Entry Format

DISP

MK-01065-01

8-20 Task Builder Input Data Formats

8.4.10

PSECT Relocation
The PSECT relocation entry in Figure B-24 relocates a direct pointer to the
beginning address of another PSECT (other than the PSECT in which the
reference is made) within a module. The current base address of the specified
PSECT is obtained and written into the task image file at the calculated address.
For example:
.PSECT

.PSECT
MOV

C
#B,RO

or
. WORD

Figure 8-24:

PSECT Relocation Entry Format

DISP

PSECT
NAME

MK-01065-02

8.4.11

PSECT Displaced Relocation
The PSECT displaced relocation entry in Figure B-25 relocates a relative
reference to the beginning address of another PSECT within a module. The
current base address of the specified PSECT is obtained and the address plus 2
that the relocated value is to be written into is subtracted from the base value.
The result is then written into the task image file at the calculated address.
For example:
.PSECT

.PSECT
MOV

C
B,RO

Task Builder Input Data Formats

8-21

Figure 8-25:

PSECT Displaced Relocation Entry Format

DISP

PSECT
NAME

MK-01066-00

8.4.12

PSECT Additive Relocation
The PSECT additive relocation entry in Figure B-26 relocates a direct pointer to
an address in another PSECT within a module. The current base address of the
specified PSECT is obtained and added to the specified constant. The result is
written into the task image file at the calculated address.
For example:
.PSECT

.PSECT
MOV
MOV

#B+I0,RO
#C,RO

or
. WORD
. WORD

8-22

Task Builder Input Data Formats

B+IO
C

Figure 8-26:

PSECT Additive Relocation Entry Format

IB I

DISP

PSECT
NAME

CONSTANT
MK-01066-01

8.4.13

PSECT Additive Displaced Relocation
The PSECT additive displaced relocation entry in Figure B-27 relocates a relative
reference to an address in another PSECT within a module. The current base
address of the specified PSECT is obtained and added to the specified constant.
The address plus 2 that the relocated value is to be written into is subtracted
from the resultant additive value. The result is then written into the task image
file at the calculated address.
For example:
.PSECT

.PSECT

MOV
MOV

B+I0,RO
C,RO

Task Builder Input Data Formats

8-23

Figure 8-27:

DISP

PSECT Additive Displaced Relocation Entry Format

PSECT
NAME

CONSTANT
MK-01066-02

8.4.14

Complex Relocation
The complex relocation entry in Figure B-28 resolves a complex relocation
expression. In such an expression, any of the MACRO-ll binary or unary
operations are permitted. Any type of argument is permitted, regardless of
whether the argument is unresolved global, relocatable to any PSECT base,
absolute, or a complex relocatable subexpression.
The RLD command word is followed by a string of numerically-specified operation
codes and arguments. Each operation code occupies one byte. The entire RLD
command must fit in a single record. Table B-3 lists the defined operation codes.
Table 8-3:

Defined Operation Codes for the RLD Command Word

No operation.

Addition (+).

Subtraction (-).

Multiplication (*).

Division (/).

Logical AND (&).

Logical inclusive OR (!).

Negation (-).

Complement AC.

Store result (command termination).

Store result with displaced relocation (command termination).

Fetch global symbol. It is followed by four bytes containing the symbol name in
Radix-50 representation.

Fetch relocatable value. It is followed by one byte containing the sector number
and two bytes containing the offset within the sector.

Fetch constant. It is followed by two bytes containing the constant.

(continued on next page)

8-24 Task Builder Input Data Formats

Table 8-3 (Cont.):
21

Defined Operation Codes for the RLD Command Word

Fetch resident library base address. 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.

The STORE commands indicate that the value is to be written into the task
image file at the calculated address.
All operands are evaluated as 16-bit signed quantities using two's complement arithmetic. The results are equivalent to expressions that are evaluated
internally by the assembler. Note the following rules:
1. An attempt to divide by zero yields a zero result. The Task Builder issues a

nonfatal diagnostic message.
2. All results are truncated from the left in order to fit into 16 bits. No diagnostic message is issued if the number was too large. If the result modifies a byte, the Task Builder checks for truncation errors as described in
Section B.4.
3. All operations are performed on relocated (additive) or absolute 16-bit
quantities. PC displacement is applied to the result only.
For example:
.PSECT ALPHA
A:

.PSECT BETA
B:

MOV

Figure 8-28:

#A+B -<Gl/G2&AC<177120!G3»,Rl

Complex Relocation Entry Format

DISP
COMPLEX

STRING

12 or 13
MK-{)1067-{)O

Task Builder Input Data Formats

8-25

8.4.15

Additive Relocation
The shared run-time system (SRTS) additive relocation entry in Figure B-29
relocates a direct pointer to an address within an SRTS.
If the current file is a symbol table file (STB), the base address of the SRTS is

obtained and added to the specified constant. The result is written into the task
image file at the calculated address. If the file is not associated with an SRTS,
the task base address is used.
Figure 8-29:

Additive Relocation Entry Format

DISP

CONSTANT
MK-01067-01

8.5 Internal Symbol Directory Record
The Internal Symbol Directory (ISD) record declares definitions of all symbols
that are defined in the module. In addition to looking for global symbol definitions
in the input object modules, TKB must look for ISD records. Some of these
require no relocation and TKB can copy them directly into the .STB file. Others
will require modification; after being modified, ISD records can be written to the
.STB file. In addition, TKB may need to generate some ISD records of its own in
the .STB file.
Except for autoloadable library entry points, TKB puts ISD records into the .STB
file only if the IDA switch is used in the TKB command line. When TKB outputs
the .STB file, it writes one of three major types of ISD records:
•

Type 1 records, where TKB generates ISDs in language-independent form.

•

Type 3 records, written for any type 2 records in an input object module.
TKB does this after adding data and then changing the ISD record type to
language-dependent and independent sections. Language processors generate
these records and TKB modifies them. They contain information that can be
used to find the absolute task image address of source program entities (for
example, variables, program statements, and so on).

•

Type 4 records, written to the .STB file without modification. Type 4 records
are literal records that contain language-dependent information. Apart from
the first few bytes, TKB ignores the rest of the record.

The following sections describe the record formats.

8-26 Task Builder Input Data Formats

8.5.1

Overall Record Format
ISD records have the same basic structure as all object language records. Because
of the variety of different types, the skeleton structure must inc1ude additional
fields that are common to all ISD record types. The general format of all ISD
records is shown in Figure B-30.
Figure 8-30:

General Format of All ISD Records

MUST BE 0

RECORD TYPE = 5

RESERVED (0)

ISD RECORD TYPE

RECORD TYPE DEPENDENT

MK-01068-00

ISD record types fall into these general categories:

Illegal.

TKB-generated.

Compiler-generated relocatable.

Relocated (type 2 after TKB processing).

4-127

Not defined, reserved for future use.

128-255

Literal records. (The type code identifies the generating language processor, and thus, the internal structure.)

Task Builder Input Data Formats

8-27

B.5.2

TKB-Generated Records (Type 1)
The content of this record type is a string of individual items, each with its
own format. The items are either start-of-segment items, task identification
items, or autoloadable entry point items. The TKB-generated record is similar
to the structure of an RLD or GSD record. The general format is shown in
Figure B-31.
Figure B-31:

General Format of a TKB-Generated Record

LENGTH (BYTES)

ITEM TYPE

CONTENT DEPENDS ON ITEM TYPE

MK-O 1069-00

B.5.2.1

Start-of-Segment Item (Type 1)

The format of the start-of-segment item type is shown in Figure B-32.
Figure B-32:

Format of TKB-Generated Start-of-Segment Item (1)

LENGTH = 8

ITEM TYPE = 1

SEGMENT NAME

SEGMENT DESCRIPTOR ADDRESS
MK-01070-00

8-28 Task Builder Input Data Formats

B.5.2.2

Task Identification Item (Type 2)

The task identification item type ensures that an .STB file and the task image
being debugged were generated at the same time. Otherwise, symbols that are
found may not correspond to the actual task.
The task identification item type exists to make the correlation between the
.STB file and its related task possible. The contents of this item type correspond
exactly to the first ten words of an area in a task image file, which is in the
TKB-created PSECT called $$DBTS.
The format of the task identification item type is shown in Figure B-33.
Figure B-33:

Format of TKB-Generated Task Identification Item (2)

LENGTH = 22

ITEM TYPE = 2

EIGHT-WORD TIME STAMP (1)

TWO-WORD NUMBER (2)

(1) Its form is that which is returned by RSX
directive GTM$.

(2) TKB generates this number as an additional
check on correspondence. Currently always
zero.
MK-01071-00

Task Builder Input Data Formats

8-29

B.5.2.3

Autoloadable Library Entry Point Item (Type 3)

TKB outputs the autoloadable library entry point item into an .8TB file when
building overlaid resident libraries. The I8D record contains the information
needed by TKB to dynamically generate autoload vectors for entry points in the
library. Autoload vectors appear for only those entry points that are referenced
by the task. Unlike the other items, the autoloadable library entry point item is
not for use by debuggers.
The format of the autoloadable entry point item is shown in Figure B-34.
Figure 8-34:

Format of an Autoloadable library Entry Point Item (3)

LENGTH = 12

ITEM TYPE = 3

SYMBOL
NAME

FLAGS BYTE

ENTRY POINT OFFSET FROM LIBRARY BASE

SEGMENT DESCRIPTOR OFFSET IN $$SGD1

MK-01072-00

8.5.3

Relocatable/Relocated Records (Type 2)
These records are the central part of TKB's involvement in debugger communication. Every item type in these records must be standardized, and only standard
items can appear. The general format is the same as that shown in Figure B-30.
A language processor outputs these record types as type 2. When TKB processes
them, it changes the type to type 3. It also fills in or modifies some fields. In
the following descriptions, fields that are filled in by TKB are marked with an
asterisk (*). They should be left as zero in language processor output.

8-30

Task Builder Input Data Formats

8.5.3.1

Module Name Item (Type 1)

A module name item should be the first ISD entry of each object module. A
debugger can assume that all following ISD information up to the next module
name item relates to this module.
The language code is included so that a debugger for a specific language can
determine whether to ignore a module if it is written for another language. The
language code has the same range of values as that of a language-dependent ISD
record (128-255) and has the same meanings.
The format of the module name item type is shown in Figure B-35.
Figure 8-35:

Format of a Module Name Item (Type 1)

LENGTH

ITEM TYPE: 1

MUST BE 0

LANGUAGE CODE

MODULE NAME (1)

(1) A counted ASCII string of the required
length. (A counted ASCII string is a byte
in which the first byte indicates the
number of bytes to follow.)
MK-01073-00

Task Builder Input Data Formats

8-31

B.5.3.2

Global Symbol item (Type 2)

One type 2 item should appear for each global symbol definition that the language
processor wants the debugger to understand. It need not, for example, include
definitions generated for the language processor run-time system.
The format of the global symbol item type is shown in Figure B-36.
Figure 8-36:

Format of a Global Symbol Item (Type 2)

LENGTH

ITEM TYPE = 2

SYMBOL NAME
(RADIX-50)
VALUE*
DESCRIPTOR ADDRESS FOR CONTAINING
OVERLAY SEGMENT*
MUST BE ZERO

FLAGS

FULL SYMBOL NAME (1)

(1) Counted ASCII string of the required length.
(A counted ASCII string is a byte string in
which the first byte indicates the number of
bytes to follow.)

MK-01074-00

8.5.3.3

PSECT Item (Type 3)

A concatenated PSECT has two base addresses: one for the whole PSECT, and
the other for the part of it that belongs to this module. It is the base address for
the part that belongs to this module that may be used by a debugger to convert
local symbol values to absolute addresses.
The segment descriptor address is necessary because a PSECT may move to
segments other than the one in which it is placed. This address is relevant to
languages that provide semi-automatic overlay generation, like COBOL-H. This
word may be zero if the PSECT has not moved to another segment.
The flag word is a copy of the flag word built by TKB. It allows for identification
ofVSECTs.
Some languages may need the full PSECT name.

8-32

Task Builder Input Data Formats

The fonnat of a PSECT item type is shown in Figure B-37.
Figure 8-37:

Format of a PSECT Item (Type 3)

LENGTH

ITEM TYPE = 3

PSECT NAME

BASE ADDRESS OF PSECT IN THIS SEGMENT'
BASE ADDRESS OF PSECT FOR THIS MODULE'
LENGTH OF PSECT FOR THIS MODULE'
DESCRIPTOR ADDRESS FOR CONTAINING SEGMENT'
FLAG WORD'
FULL PSECT NAME (1)

(1) Counted ASCII string of the required length.
(A counted ASCII string is a byte string in
which the first byte indicates the number of
bytes to follow.)
MK-01075-00

Task Builder Input Data Formats

8-33

B.5.3.4

Line-number or PC Correlation Item (Type 4)

This item provides the information needed to translate a source line-number into
a task image address, or a task image address into a source line-number.
The format of a line-number of PC correlation item type is shown in Figure B-38.

Figure B-38:

Format of a Line-Number or PC Correlation Item (Type 4)

LENGTH

ITEM TYPE = 4

PSECT
NAME
START PC (1)
DESCRIPTOR ADDRESS OF CONTAINING OVERLAY
SEGMENT'
START PAGE NUMBER
START LINE NUMBER
STRING OF ONE-BYTE ITEMS

(1) Offset into PSECT in type 2 records;
absolute address in type 3 records.
MK-01076-00

B.5.3.5

Internal Symbol Name Item (Type 5)
It is necessary to allow for the fact that a name may have more than one associated address. For example, a COBOL variable may have three associated
addresses: the address of the area that actually contains the data, the address of
a CIS descriptor, and the address of a picture string.

8-34 Task Builder Input Data Formats

The internal symbol name item, which meets these requirements, is shown in
Figure B-39.
Figure 8-39:

Format of an Internal Symbol Name Item (Type 5)

LENGTH

ITEM TYPE = 5

OFFSET TO NAME

OFFSET TO DATA

MUST BE ZERO

NUMBER OF ADDRESSES

ADDRESS 1:
PSECT
NAME
TASK IMAGE ADDRESS/OFFSET (1)
SEGMENT DESCRIPTOR ADDRESS·
ADDRESS 2:
PSECT
NAME
TASK IMAGE ADDRESS/OFFSET (1)
SEGMENT DESCRIPTOR ADDRESS·
ADDRESS n:.

LANGUAGE-DEPENDENT DATA
SYMBOL NAME (2)

(1) Modified by TKB.
(2) A counted ASCII string of the required length.
(A counted ASCII string is a byte string in
which the first byte indicates the number of
bytes to follow.

MK-01077-00

Task Builder Input Data Formats

8-35

8.5.4

Literal Records (Type 4)
Literal records may take any form except for the two-byte header shown in
Figure B-40.
Figure 8-40:

Format of a Literal Record Type

RESERVED (0)

ISO RECORD TYPE 4

MK-O 1078-00

B.6 End of Module
The end-of-module record in Figure B-41 declares the end of an object module.
Exactly orie end-of-module record must appear in each object module. It is one
word in length.
Figure 8-41:

End-of-Module Record Format

MK-O 1067 -02

B-36

Task Builder Input Data Formats

Appendix C

Executable File Structure
This appendix describes the elements of an executable file.
The executable file as it is recorded on the disk appears in Figure C-1.
Figure C-1:

Task Image on Disk

AUTOLOAD VECTORS
CO-TREE OVERLAY
BLOCK
AUTOLOAD VECTORS
CO-TREE ROOT
BLOCK
AUTOLOAD VECTORS
MAIN TREE
OVERLAY
BLOCK
AUTOLOAD VECTORS
SEGMENT TABLES
ROOT SEGMENT
CODE & DATA
STACK FP/EA
SAVE AREA HEADER
BLOCK
CHECKPOINT AREA
BLOCK
LABEL
(Block 0 of the file)

MK-01079-00

Executable File Structure

C-1

C.1

Label Block Group
The label block group shown in Figure C-2 precedes the task on the disk and
contains data that need not be resident during task execution. This group is
composed of two elements:

C-2

•

Task and resident library data (Label Block 0)

•

Table of LUN assignments (Label Block 1) which contains the name and
logical unit number of each device assigned

Executable File Structure

Figure C-2:

Label

Label Block Group

Non-I&D TasksilD Tasks

Offset *

L$BTSK

L$BPAR

2
4
6
10
12
14
16
20
22
24

L$BSA
L$BHGV
L$BMXV
L$BLDZ
L$BMXZ
L$BOFF
L$BWND/L$BSYS
L$BSEG
L$BFLG
L$BDAT

26
30
32

L$BLlB

34
36
40
42
44
46
50
52
54
56
60
62
64
66
70

Task
Name
Task
Partition
Base address of task
Highest window 0 virtual address
Highest virtual address in task
Load size in 64-byte blocks
Maximum size in 64-byte blocks
Task offset into partition
System 10 I Number of window blocks'
Size of overiay segment descriptors
Task flag word
Task creation date -Year
-Month
-Day
Library/common

Name
Base address of library
Highest address In first library window
Highest address In library
Library load size (64-byte blocks)
Library maximum size (64-byte blocks)
Library offset into region
Number of library window blocks
Size of library segment descriptors
Library flag word
Library creation date - Year
-Month

L$BPRI
L$BXFR
L$BEXT
L$BSGL
L$BHRB
L$BBLK
L$BLUN
L$BROB
L$BROL
L$BRDL
L$BHDB
L$BDHV
L$BDMV
L$BDLZ
L$BDMZ
L$BAPR
L$DAPR
L$BFLZ
L$BLRL

344/704
346/706
350/710
3521712
354/714
356/716
360/720
3621722
364/724
366/726
370/730
3721732
374/734
376/736
400/740
4021742
404/744
404/772
404n74

404/776

R$LNAM
R$LSA
R$LHGV
R$LMXV
R$LLDZ
R$MXZ
R$LOFF
R$LWND
R$LSEG
R$LFLG
R$LDAT

Library
Request
(maximum
of 7 or 15
14-word
entries)

- Day

0
Task priority
Task transfer address
Task extension (64-byte blocks)
Block number of segment load list
Block number of header
Number of blocks in label
Number of logical units
Relative block of R-O image
RIO load size
RIO data size In 32-word blocks
Relative block number of data header
High virtual address of data window 1
High virtual address of data
Load size of data
Mazimum size of data
APR mask word
Second task flag word
Label block revision number
AME (must be 0)

• Less library window blocks.

* If the Image is a SIL (output of MAKSIL program), add 1000 (octal) to these values. Also, location 776 (no 1000 added)=SIL in Radix-50.

Executable File Structure

C-3

Task and resident library data are described in Table C-l.
Table C-1:

Task and Resident Library Data

L$BTSK

Task name consisting of two wcrds in Radix-50 format. This parameter is
set by the TASK keyword.

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. This value is set to L$BHGV.

L$BLDZ

Task load size in units of 64-byte blocks. This value represents the size of
the root segment.

L$BNIXZ

Task minimum 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$BOFF

Task offset into partition in units of 64-byte blocks.

L$BWND

Number of task windows (less windows of declared libraries (SRTS»- Low
byte.

L$BSYS

System I.D.- High byte
1 = RSX-llM.
4 = RSX-llM-PLUS.

L$BSEG

Size of overlay segment descriptors (in bytes).

L$BFLG

Task flags word. The following flags are defined:
Bit
Flag
Meaning When Bit = 1

L$BDAT

TS$PIC

Task contains position-independent code (PIC).

TS$NHD

Task has no header.

TS$PMD

Task generates Postmortem Dump.

TS$CMP

Task is built in compatibility mode.

TS$CHK

Task is not check-pointable (not supported on
RSTSIE).

TS$RES

Task has memory-resident overlays.

TS$SUP

Image linked as supervisor-mode library.

TS$NEW

New header format L$BFL2 and after are valid.

Three words containing the task creation date as two-digit integer values:
Year (since 1900)
Month of year
Day of month

L$BLIB

Resident library entries.

L$BPRI

Task priority set by the PRI keyword. Ignored by RSTSIE.

L$BXFR

Task transfer address. (Not used by RSTSIE.)

L$BEXT

Task extension size in units of 64-byte blocks. This parameter is set by the
EXTTSK keyword.

L$BSGL

Relative block number of segment load list. Set to zero if no list is
allocated.

(continued on next page)

C-4

Executable File Structure

Table C-1 (Cont.):

Task and Resident Library Data

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 RIO image.

L$BROL

RIO load size in 32-word blocks.

L$BRDL

Size of RIO data in 32-word blocks.

L$BHDB

Relative block number of data header.

L$BDHV

High virtual address of data window 1 of D-space task.

L$BDMV

High virtual address of data.

L$BDLZ

Load size of data.

L$BDMZ

Maximum size of data.

L$BAPR

The APR mask word.

L$BFL2

Second task flag word. The following flags are defined:
Bit
Flag
Meaning When Bit =1
1

TZ$FMP

Task uses fast map facility.

L$BLRL

Label block revision level.

L$AME

Always 0 for AME compatibility.

Executable File Structure

C-5

The contents of the SRTS/common name block are listed in Table C-2. This block
is constructed by referencing the disk image of the SRTS/common block. The
format is identical to words 3 through 16 of the label block.
Table C-2:

Contents of SRTS/Common Name Block

R$LNAM

Library/command name consisting of two words in Radix-50 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

Library/common block load size in 64-byte blocks.

R$LMXZ

Library maximum size in units of 64-byte blocks.

R$LOFF

Size of mapped array allocated by the resident library.

R$LWND

Number of window blocks required by library.

R$LSEG

Size of library overlay segment descriptors in bytes.

R$LFLG

Library flags word. The following flags are defined:
Bit
Meaning

R$LDAT

LD$ACC - Access intent (l=readiwrite, O=read-only)

LD$RSV - APR was reserved

LD$CLS - Library is part of a cluster

Default member of cluster (or HISEG).

LD$RES-library has memory resident overlays.

LD$SUP - Supervisor-mode library (l=yes)

LD$REL - Position-independent code (PIC) flag (I=PIC)

LD$TYP-shared region type (l=common, O=library).

Three words containing the library/common block creation date in the
following format:
WORD 0:
Year since 1900
WORD 1:

Month of year

WORD 2:

Day of month

C.2 Header
The task header starts on a block boundary and is immediately followed by
the task image. The task is read into memory starting at the base of the root
segment. Because the root segment is a set of contiguous disk blocks, it is loaded
with a single disk access.
The header is divided into two parts: a fixed part, as shown in Figure C-3, and a
variable part, as shown in Figure C-4.

C-6

Executable File Structure

Figure C-3:

Task Header Fixed Part

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 UIC

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 language impure storage

H.OVLY

Address of overlay impure storage

H.vEXT

Address of impure vectors

H.SPRI
H.NML

60
61

Swapping priority
Mailbox LUN

H.RRVA

Receive by reference AST control block

Reserved

H.GARD

Header guard word painter

H.NLUN

Number of LUNs

MK-{)1081-{)O

Executable File Structure

C-7

Figure C-4:

H.LUN

Task Header Variable Part

LUN Table (2 words/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

First PDR Address

W.BFPD

Number of PDRs to Map

W.BNPD

Contents of Last PDR

W.BLPD

Current PS
Current PC

INITIAL VALUES

Current R5

relative block
number of header

Current R4

indent word #2

Current R3

indent word #1

Current R2

task name word #2

Current R1

task name word #1

Current RO

program transfer
address

Header Guard Word
MK4Jl0824JO

C-8

Executable File Structure

The variable part of the header contains window blocks that describe the following:
•

The task's virtual-to-physical mapping

•

Logical unit data

•

Task context

The task header is used by RSTSIE mainly for setting the initial conditions of the
task. Only locations 46 through 56 have identical meanings as in RSX.
NOTE

To save the identification, the initial value set by the Task Builder
should be moved to local storage. When the program is fixed in memory and being restarted without reloading, the reserved progfam
words must be tested for their initial values to determine whether the
contents of R3 and R4 should be saved.
The contents of RO, Rl, and R2 are set only when a debugging aid is
present in the task image.

C.2.1

low Core Context
The low core context for a task consists of the Directive Status Word and the
Impure Area vectors. The Task Builder recognizes the following global names:
. FSRPI'

File Control Services work area and buffer pool vector

$OTSV

Language OTS work area vector

N.OVPI'

Overlay Runtime System work area vector

$VEXT

Vector extension area pointer

The only proper reference to these pointers is by symbolic name.
The Impure Area pointers contain the addresses of storage used by the reentrant
library routines described above.
The address contained in the vector extension pointer locates an area of memory
that can contain additional impure area pointers.
The format of the vector extension area is shown in Figure C-5. Each location within this region contains the address of an impure storage area that is
referenced by subroutines that must be reentrant. Addresses below $VEXTA, referenced by negative offsets, are reserved for Digital applications. Addresses above
this symbol, referenced by positive offsets, are allocated for user applications .
.PSECTs $$VEXO and $$VEXl have the attributes D, GBL, RW, REL, and OVR.

Executable File Structure

C-9

Figure C-S:

Vector Extension Area Format

,PSECT
IMPURE:

$VEXT

,PSECT $$VEXO

$VEXTA

,PSECT $$VEX1

]
]

Reserved for
DIGITAL use

Reserved for
user applications

MK-O 1083-00

The .PSECT attribute OVR facilitates the definition of the offset to the vector and
the initialization of the vector location at link time, as shown by the following
example:
$VEXTA

.PSECT

$$VEX1,D,GBL,RO,REL,OVR
; POINT TO BASE OF POINTER TABLE

BEG=.

LABEL:

.BLKW

OFFSET TO CORRECT LOCATION
IN VECTOR AREA

• WORD

IMPURE

SET IMPURE AREA ADDRESS
DEFINE OFFSET

OFFSET==LABEL-BEG
.PSECT
IMPURE:

C-10

Executable File Structure

;MAKE SURE VECTOR AR A IS LINKED

.GLOBL

C.3 Overlay Data Structure
Figure C-6 illustrates the structure and principal components of the task-resident
overlay data base.
Figure C-6:

Task-Resident Overlay Data Base

----------------,
AUTOLOAD
VECTOR

SEGMENT
DESCRIPTOR

AUTOLOAD
VECTOR

SEGMENT
DESCRIPTOR

AUTOLOAD
VECTOR

SEGMENT
DESCRIPTOR

WINDOW
DESCRIPTOR

0
WINDOW
DESCRIPTOR

REGION
DESCRIPTOR

~----------------

Window descriptors are necessary for the
windows that the overlay run-time
system uses to map memory resident
overlays. The overlay run-time system
also needs window descriptors to map
disk-resident overlays that are up-tree
from memory-resident overlay segments.
The overlay run-time system uses
region descriptors to map overlaid
libraries.

Executable File Structure

C-11

Figure C-7 illustrates the task-resident overlay database for an 1- and D-space
overlaid task.
Figure C-7:

Task·Resident Overlay Database for and 1- and O-Space Overlaid
Task

AUTOLOAD
VECTOR
D-SPACE PART

o,--------------I

SEGMENT
DESCRIPTOR

I
I

WINDOW
DESCRIPTOR
FOR I-SPACE

EXTENSION

WINDOW
DESCRIPTOR
FORD-SPACE
AUTOLOAD
VECTOR

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

D-SPACE PART ~

SEGMENT
DESCRIPTOR

-_ .... _--------

H-t

EXTENSION

:li

WINDOW
DESCRIPTOR
FOR I-SPACE

WINDOW
DESCRIPTOR
FOR D-SPACE

AUTOLOAD
VECTOR
D-SPACE PART

l®
: ,----------------j
I

SEGMENT
DESCRIPTOR

WINDOW
DESCRIPTOR

I :

REGION
DESCRIPTOR

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 referencing
segment.

Executable File Structure

I _______________ l :
_______________ JI L

The overlay run-time system uses
region descriptors to map overlaid
libraries.

C-12

One segment descriptor is generated for each overlay segment in the task or
shared region. The segment descriptor contains infonnation on the size, virtual
address, and location ofthe segment within the task image file. In addition, it
contains a set of link words that point to other segments. The overlay structure
detennines the link word contents.
The following sections describe the composition of each element.

C.3.1

Autoload Vectors for Conventional Tasks
The autoload vector table consists of one entry per autoload entry point in the
form shown in Figure C-8.
Figure C-8:

Autoload Vector Entry

JSR @PC+2
Offset to pointer to autoload code
Segment descriptor address
Entry point address

MK-01055-00

The autoload vector contains a JSR to the autoload processor, $AUTO, followed
by a pointer to the descriptor for the segment to be loaded and the real address of
the entry point.

Executable File Structure

C-13

C.3.2

Segment Descriptor
The segment descriptor is composed of a six-word fixed-length portion. Segment
descriptor contents are shown in Figure C-9.

Figure C-9:

Segment Descriptor

TASK-RESIDENT SEGMENT DESCRIPTOR OFFSETS
15

12 11

I RELATIVE DiSK BLOCK ADDRESS

FLAGS

VIRTUAL LOAD ADDRESS OF SEGMENT

BYTE

LENGTH OF SEGMENT IN BYTES

LINKUP

LINK DOWN

LINK NEXT

SEGMENT NAME (2-WORD RADIX-50)

WINDOW DESCRIPTOR ADDRESS

FLAGS: 15-TASK RESIDENT FLAG (ALWAYS 1)
14-SEGMENT HAS DISK ALLOCATION (1 =NO)
13-SEGMENT IS LOADED FROM DISK (1=YES)
12-SEGMENT IS LOADED AND MAPPED (O=YES)
F: a-SEGMENT FOR 1- AND D-SPACE TASK (1=YES)

TASK-RESIDENT SEGMENT DESCRIPTOR EXTENSION
OFFSETS FOR I-AND D-SPACE TASKS ONLY

12 11

15
UNUSED

D-SPACE DISK BLOCK ADDRESS

D-SPACE VIRTUAL LOAD ADDRESS

D-SPACE SEGMENT LENGTH IN BYTES*

D-SPACE WINDOW DESCRIPTOR ADDRESS

*0 IF ONLY I-SPACE SEGMENT

C-14

Executable File Structure

Word 0 contains the relative disk address in bits 0-11 and the segment status in
bits 12-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.
.
The segment flags are defined as follows:
Bit 15

Always set to 1.

Bit 14

o =Segment loaded and mapped.

Bit 13

o =Segment has disk allocation.

Bit 12

o = Segment not loaded from disk.

1 =Segment is either not loaded or not mapped.
1 =Segment does not have disk allocation.

1 =Segment loaded from disk.

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.
The next three words point to the following segment descriptor:
Link Up

Points to the next segment away from the root. Link Up equals 0 of
you are already at the leaf.

Link Down

Points to the next segment toward the root. Link Down equals 0 if you
are already at the root.

Link Next

Points to the adjoining segment. Link Next equals the address of the
current segment if there are no others on the same level with the same
Link Down. Link Next links all· segments on the same level that have
the same Link Down in a circular fashion. Thus, in Figure C-10, Link
Next in A3 points to AI, but Link Next in All points to All itself and
Link Next in AO points to AO itself.

The segment descriptor for an 1- and D-space task consists of a fixed part that 'is
nine words long and an optional part that is four words long. The optional part
is always present for task segments and never present for library segments. The
bottom half of Figure C-9 illustrates the contents of the segment descriptor for land D-space tasks.
When a segment is loaded, the overlay run-time system follows the links to
determine which segments are being overlaid and should therefore be marked out
of memory.

Executable File Structure

C-1·5

Using the tree in Figure C-10 as an example:
Figure C-10:

Sample Tree

A21

A22

A11

AO (ROOT)
MK-O 1088-00

The segment descriptors are linked as in Figure C-ll.
If there is a co-tree, the Link Next for the root segment descriptor points to the

co-tree root segment descriptor.
Words 6 and 7 contain the segment name in Radix-50 format.
Word 8 points to the window descriptor used to map the segment (0 = none).
Figure C-11:

A11

Segment Linkage Directives

A21

A22

~----j
A2

______ L ____ j .
~'
AD
LINK UP

A11

A21

A22

j ~!r

~[j

(-;;'1
I
I
I
I
I
I

A21
I

•

I
I

A22
iI
I

'-------T------ J
I

)0
I - I
I
I
I
I
I1- ______ , _______ I1_ _ _ _ _ _ _ I1

Cal

LINK DOWN

LINK NEXT

MK--{)1089-00

C-16

Executable File Structure

C.3.2.1

Autoload Vectors for 1- and D-Space Tasks
The autoload vector table consists of two entries (put into the task image for each
autoload entry point) in the form shown in Figure C-12.
The I-space part of the autoload vector contains a move (MOV) instruction that
places the address of the D-space part of the vector on the stack. The vector then
executes an indirect jump (JMP) to $AUTO through .NAUTO. The D-space part
of the vector contains the segment descriptor address of the requir.ed routine.
Figure C-12:

Autoload Vector Entry for 1- and D-Space Tasks

MOV (PC) +, - (SP)
ADDRESS OF PACKET (D-SPACE)
JMP@.NAUTO
PC RELATIVE OFFSET TO .NAUTO
I-SPACE PORTION

ADDRESS OF SEGMENT DESCRIPTOR
ENTRY POINT ADDRESS
D-SPACE PORTION

Executable File Structure

C-17

C.3.3

Window Descriptor
TKB allocates the window descriptors only if you define a structure containing
memory-resident overlays. Figure G-13 illustrates the format of a window
descriptor.

Figure C-13:

Window Descriptor

o
Base Active Page Register

Window 10

Virtual base address

2
Window size in 64-byte blocks

3
Region 10
4

Offset in partition

5
Length to map
6

Status word
7
Send/receive buffer address (always 0)

8
Flags word
9

Address of region descriptor

MK-01087-00

Words 0 through 7 constitute a window descriptor in the format required by
the mapping directives (the Program Logical Address Space (.PLAS) Mapping
Directives - see the RSTS / E System Directives Manual for more information),
The overlay loading routine fills in the region ID at run time.
Words 8 and 9 contain additional data that the overlay routines refer to. 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.

C-18

Executable File Structure

C.3.4

Region Descriptor
FigW'e C-14 illustrates the format of a region descriptor.
Figure C-14:

Region Descriptor

o
Region 10
Size of region

2
Region
3

Name
4

Region

5
Partition
6

Region status
7

Partition codes (always 0)

8
Flags

MK-01086-00

Words 0 through 7 constitute a region descriptor in the format required by the
mapping directives. Word 8, 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.

C.4 Root Segment
The root segment is written as a contiguous group of blocks. The root segment is
the first segment loaded and remains in memory for the entire life of the program
execution.

C.s Overlay Segments
Each overlay segment begins on a block boundary. 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 nonroot segment is 28K words. The maximum size for
the root segment is 32K words.

Executable File Structure

C-19

Appendix D

Reserved Symbols
All symbols and PSECTt names containing a period (.) or dollar sign ($) are
reserved for Digital-supplied software. Several global symbols and PSECTt
names are reserved for use by the Task Builder. Special handling occurs when a
definition of one of these names is encountered in a task image.
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.
Table D-1 shows global symbols reserved by the Task Builder.
Table D-1:

Task Builder Reserved Global Symbols

Global
Symbol

Modification Value

$ALERR

OTS address of overlay load eroor handler.

$AUTO

OTS address of autoload routine.

$DBTS

Debugger time stamp.

. FSRPT

Address of file storage region work area (.FSRCB) .

$FSTIN

OTS address of fast map overlay routine.

$MARKS

OTS address of MARK segment routine.

. MBLUN

Mailbox logical unit number.

. MOLUN

Error message output device .

. NALER

OTS entry point to overlay load error handler.

. NAUTO

OTS entry point to $AUTO or $LOAD .

. NDTDS

OTS highest displaced segment .

. NFAST

OTS AST supression control flags .

.NFMAP

OTS entry point to Fast Map initialization routine .

. NIOST

OTS common I/O status doubleword .

.NLUNS

The number of logical units used by the task, not including the message
output and overlay units .

. NMARKS

OTS entry point to MARK segments.

(continued on next page)

t PSECTS are created by .ASECT, .CSECT, or .PSECT directives. The .PSECT directive eliminates the need for either
the .ASECT or .CSECT directive, both of which are retained only for compatibility with other systems. In this
document all sections are referred to as PSECTS unless the specific characteristics of .ASECT or .CSECT apply.

Reserved Symbols

D-1

Table D-1 (Cont.):

Task Builder Reserved Global Symbols

Global
Symbol

Modification Value

.NOVLY

The overlay logical unit number.

N.OVPT

Address of overlay run-time system work area (.NOVLY).

. NRDSG

OTS entry point to READ segments .

. NSTBL

The address of the segment description tables. This location is modified only
when the number of segments is greater than one.

. NSZSG

OTS size of resident segment descriptors .

.ODTLI

Logical unit number for the ODT terminal device TI:.

. ODTL2

Logical unit number for the ODT line printer device CL: .

$OTSV

Address of Object Time System work area ($OTSVA).

. PTLUN

Logical unit number for plotter/graphics software .

$RDSEG

OTS address of READ segment routine.

. SUMLI

P/OS standard utility module LUN .

.TRLUN

The trace subroutine output logical unit number.

.USLUI

Logical unit number for special purpose user software.

.USLU2

Logical unit number for special purpose user software .

$VEXT

Address of vector extension area ($VEXTA).

The following global symbols are reserved by TKB for tasks using disk-resident
overlays:
Global
Symbol

Modification Value

$MARDS

OTS entry point to IID MARK segment routine.

$MAFKS

OTS entry point to optimized MARK segment routine.

$MAFDS

OTS entry point to optimized lID MARK segment routine.

The following global symbols are reserved by TKB for tasks using memoryresident overlays:
Global
Symbol

Modification Value

$MARKR

OTS entry point to MARK segment routine.

$MARDR

OTS entry point to IID MARK segment routine.

$$MAFKR

OTS entry point to optimized MARK segment routine.

$MAFDR

OTS entry point to opitmized lID MARK segment routine.

The following global symbols are reserved by TKB for tasks using cluster
libraries:

D-2

Global
Symbol

Modification Value

$MARKC

OTS entry point to MARK segment routine.

$MARDC

OTS entry point to IID MARK segment routine.

Reserved Symbols

Global
Symbol

Modification Value

$MAFKC

OTS entry point to optimized MARK segment routine.

$MAFDC

OTS entry point ot optimized lID MARK segment routine.

The PSECT names in Table 0-2 are reserved by the Task Builder. In some
cases, the definition of a reserved PSECT causes the PSECT to be extended if the
appropriate option is specified.
Table 0-2:

PSECT Names Reserved by the Task Builder

Source
Location

Section Name

Description

TKB

$$ALER

Contains code to process or trap Overlay Run-time
system segment load errors. Provides named areas
in the task for the FORTRAN Object Time System
and the RSX Overlay Run-time System.

TKB

$$ALVC

Contains the segment autoload vectors for tasks
without 1- and D-space.

TKB

$$ALVD

Contains the D-space portions of the segment
autoload vectors in an 1- and D-space task.

TKB

$$ALVI

Contains the I-space portions of the segment
autoload vectors in an 1- and D-space task.

TKB

$$AUTO

Contains code to determine if a called subroutine in
an overlay segment is already in memory or if that
overlay segment should be read into memory before
control is passed to the subroutine that is called.

Input Module

$$DBTS

This symbol should appear in the debugger input
module with the symbol $DBTS as follows:
.PSECT

$$DBTS

.$DBTS::
.PSECT
The task builder extends $$DBTS and fills it with
time stamp information followed by the filename
information of the .STB file.
SYSLIB

$$DEVT

The extension length (in bytes) is calculated from
the formula:
EXT =(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.

SYSLIB

$$FSRI

The extension of this section is specified by the
ACTFIL option.

SYSLIB

$$FTSM

Contains the code to map memory-resident overlays
using the fast map facility instead of the standard
executive mapping directive CRAW$.

SYSLIB

$$IOBI

The extension of this section is specified by the
MAXBUF option.

(continued on next page)

Reserved Symbols

0-3

Table 0-2 (Cont.):

PSECT Names Reserved by the Task Builder

Source
Location

Section Name

Description

TKB

$$IOB2

A zero length .PSECT containing a label, IOBFND,
that is stored in the work area offset, W.BEND,
representing the upper bound of the I/O buffer,
$$IOBl. TKB uses $$IOB2 as a boundary value to
detennine whether the I/O buffer has overflowed.

TKB

$$LOAD

Overlay manual load routine.

TKB

$$MRKS

Contains code to properly mark those segments that
are not needed any longer or have been overlaid
by another segment as being out of memory. This
ensures that a fresh copy of the overlay segment
will be read in the next time the overlay segment is
needed.

SYSLIB

$$OBFl

FORTRAN OTS uses this area to parse array type
fonnat specifications. This section can be extended
by the FMTBUF keyword.

TKB

$$OBF2

A zero length .PSECT containing a label, OBFH,
that is stored in the work area offset, W.OBFH,
which represents the upper bound of the runtime fonnat buffer, $$OBFl. TKB uses $$OBF2
to detennine if the run-time fonnat buffer has
overflowed.

TKB

$$OVDT

The Overlay Run-time System impure data area.
The symbol N.OVPT in low memory points to this
area. This area defines the operational parameters
with which the Overlay Run-time system operates
on disk-resident and memory-resident overlay
structures.

TKB

$$OVRS

The .ABS. program section that redefines the
Overlay Run-time System impure data area with
different symbols, defined as offsets and relative
to zer6. These offsets are necessary for proper
linkages between the subroutines in the Overlay
Run-time System. This program section is never
included in the memory allocation of the task
because of its absolute program section attribute.

TKB

$$PDLS

Cluster library service routine.

TKB

$$RDSG

Contains the code that reads into memory the
overlay segment selected by the code contained in
the programs section $$AUTO.

TKB

$$RGDS

Contains the region descriptors for resident libraries referred to by the task.

TKB

$$RTQ

Defines the PSECT used for selective enabling of
AST recognition in the Overlay Run-time System.
$$RTQ is 0 in length if $AUTOT is not included.

TKB

$$RTR

Defines the PSECT used for selective disabling of
AST recognition in the Overlay Run-time System.
$$RTR is 0 in length if $AUTOT is not included.

TKB

$$RTS

Contains the return instruction.

(continued on next page)

0-4

Reserved Symbols

Table 0-2 (Cont.):

PSECT Names Reserved by the Task Builder

Source
Location

Section Name

Description

TKB

$$SLVC

Supervisor-mode library transfer vectors (RSX-llMPLUS only).

TKB

$$SGDO

Contains the program section adjoining the task
segment descriptors.

TKB

$$SGDI

Contains the task segment descriptors.

TKB

$$SGD2

Contains a .WORD 0 following the task segment
descriptors.

FORTRAN-77

$$TSKP

TKB fills in the following words in the PSECT (note
that the word values are filled into the Section in
order):
•
•
•
•
•
•
•
•

APR bit map in word $APRMP
Task offset into region in word $LBOFF
Maximum physical read/write memory needed
for task in word $:MXLGH
Maximum physical read-only memory needed
for task in word $:MXLGH+2
Task extension in 32-word blocks in word
BOK$LBEXT
Total contribution of FORTRAN virtual arrays
Maximum physical read-only D-space memory
needed for task in word $:MXLGH+4
Maximum physical read/write D-space memory
needed for task in word $:MXLGH+6

MACRO-ll

$$TSKP

TKB fills in the first work of the PSECT called
TSKP$. Refer to the System Directives Manualfor
more details.

TKB

$$WNDS

Contains task window descriptors.

Reserved Symbols

0-5

Appendix E

Improving Task Builder Performance

This appendix contains procedures and suggestions to help you maximize Task
Builder performance. Procedures are given for:

E.1

•

Evaluating and improving Task Builder throughput

•

Modifying command switch defaults to provide a more efficient user interface

Evaluating and Improving Task Builder Performance
Task Builder throughput is determined by these factors:
•

The amount of memory available for table storage

•

The amount of disk latency due to input file processing

The discussion in the following paragraphs outlines methods for improving
throughput in each case. The methods approach their goals through judicious use
of system resources and Task Builder features.

E.1.1

The Task Builder Work File
The largest factor affecting Task Builder performance is the amount of memory
available for table storage. To reduce memory requirements, the Task Builder
uses a work file to store symbol definitions and other tables. If the total size of
these tables is within the limits of available memory, the work file is kept in core
and not shunted to a disk. If the tables exceed the amount of memory available,
some information must be moved to the disk, which degrades performance.

Improving Task Builder Performance

E-1

Work file performance can be gauged by consulting the statistics portion of the
Task Builder map. The following parameters are displayed:
Number of work file references:
Total number of times that work file data was referenced.
Work file reads:
Number of work file references that resulted in disk accesses to read work file
data.

NOTE
If work file reads and writes equal zero and the

number of work file references is greater than
zero, you can be sure that the work file remained
in memory.
Work file writes:
Number of work file references that resulted in disk accesses to write work file
data.
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
words.)
Size of Work File:
Amount of work file storage in words. If this value is less than the core 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 produce the map. This value
excludes ODL processing, option processing, and the time required to produce the
global cross-reference.

The overhead for accessing the work file can be reduced 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, such as the
virtual disk (DV:)

•

By decreasing system overhead required to access the file

•

By reducing the number of work file references

The Task Builder automatically increases its size up to the maximum job size,
which may be as large as 32K words. See the RSTS / E System Manager's Guide
for information on how to change the maximum job size.
The size of the work file can be reduced by:

E-2

•

Linking your task to a core-resident run-time system containing commonly
used routines (for example, BASIC-PLUS-2 object time 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 file of concatenated object modules if many modules
are to be linked

Improving Task Builder Performance

In the last two cases, system overhead is also significantly reduced because fewer
files must be opened to process the same number of modules.
The number of work file references can be reduced by eliminating unneeded
output files and cross-reference processing or by obtaining the short map. In
addition, selected files, such as the default system object module library, can
usually be excluded from the map. In this case, a full map can be obtained at less
frequent intervals and retained.

Try the following procedures to improve work file performance:
•

Install 1- and D version ofTKB.

•

Decrease work file size by using resident run-time systems, concatenated
object files, and object libraries.

•

Decrease work file size by moving common modules into the root segment of
an overlaid task.

•

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.

<II

Place the work file on the fastest possible device. If the system manager
installs a system-wide logical "device:OV", the Task Builder uses a device
other than SY: as the work file device.
If the device is a private pack, aU accounts of any user wishing to use the
Task Builder must be entered on the private pack while the system-wide
logical is in effect. Otherwise, a protection violation error occurs for those
users without accounts when the Task Builder tries to create its work file.

Again, make sure the device is mounted so users without access privileges
will not obtain fatal errors when the Task Builder tries to create its work file.
•

E.1.2

Use the CCLlSI:## to increase size to maximum immediately. This may
reduce swapping when TKB must increase in size.

Input File Processing
The suggestions 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 three times when building the task:
1.

To build the symbol table

To produce the task image

To produce the long map

Files that are excluded from the long map are read only twice. The third pass
is completely eliminated for all modules when a short map is requested. So, if
you do not need the long map, use the ISH switch (described in Section 11.23) to
eliminate the third pass.

Improving Task Builder Performance

E-3

Index
A
ABORT option, 12-3
ABS attribute, 13-4
Absolute Patch (ABSPAT), 12-4
Absolute Patch for D-Space(DSPPAT), 12-11
Absolute resident area, 7-2, 7-3
ABSPAT option, 12-4
Access code (resident library), 2-11
Access code in CLSTR option, 12-8
Access code in cluster libraries, 2-14
Access Resident Common Block (RESCOM), 12-26
Access Resident Library (RESLlB), 12-27
Access System Common Block (COMMON), 12-10
Access System-Owned Resident Library (LlBR),
12-21
ACTFIL option, 12-5
Active files, 12-5
Active Page Register, 2-11, 12-8, 12-21
Additive relocation, 8-26
Addresses
absolute, 7-2
relative, 7-2
Address space, 2-2 to 2-3
$$ALVC, 6-7
Ambiguously defined symbols
in a simple overlay, 3-12
in co-trees, 4-6
APR, 2-2,2-11,12-8,12-21
with cluster libraries, 2-14
with 1- and D-space tasks, 8-1
Area, memory-resident, 7-1 to 7-7, 12-25
ASECT, 8-5
ASG option, 12-6
example, 2-15
Assembler (MAC), 2-9
used with TKB, 1-1
Assembly language and cluster libraries, 7-9
Assign Devices (ASG), 12-6
Asterisk (*)
before .FCTR names, 5--5
before .NAME names, 5--5
before file names, 5--4
before items in parentheses, 5--5
before program sections, 5--4
easiest use of, 4-3, 5--1, 13-5
errors in using, 5--6
for co-trees, 4-3
for simple overlays, 3-4
not for null co-tree roots, 4-5
ODL operator, 13-5
Attributes, 6-1 to 6-4, 13-3 to 13-4

Attributes (Cont.)
CON, 12-12
OVR, 12-12
$AUTO, 5--2, 7-9
$$AUTO, 6-7
Au!oloadable library entry point item type, 8-30
Autoload indicator, 5--1 to 5--6, 13-5
for co-trees, 4-3
for simple overlays, 3-4
not for null co-tree roots, 4-5
Autoloading a data PSECT, 6-5
Autoload processor, 5--2
Autoload routines ($AUTO), 7-9
Autoload vector, 3-4,13-5,8-30, C-13
definition, 5--1
how to request specific, 5--4
specific examples, 5--6
where needed, 5-3

8
.B2S file, 4-8
BASIC Object Time System, 2-7
BASIC-PLUS-2, 1-1
disk libraries for, 2-4t
example build, 2-15
libraries in a cluster, 12-7
resident libraries for, 2-7
run-time system for, 2-2
Blank common area, 6-7
BLDODL utility, 3-2
.BLK, 6-7
BP20TS.OLB, 2-41, 2-7
BP2RES library, 2-7,2-12, 12-7
BP2SML library, 2-7,2-12, 12-7
Branch (overlay structure), 3-10
Buffer
format, 12-14
record, 12-23
Build a Common Block Shared Region (/CO), 11-4
Build a Library Shared Region (Ill), 11-16

c
C81CIS.OLB, 2-5t
C81CIS library, 2-12,12-7
C81L1B.OLB, 2-5t
C81L1B library, 2-12,12-7
Calls
between cluster libraries, 7-10
cross-tree, 4-3

Index-1

Calls (Cont.)
logical independence of, 3-2,3-8,3-10
Call structure, 3-2, 4-1
with co-trees, 4-7
CCl command, 2-7
ICC switch, 11-3
Characters within the SYSTAT program name, 12-33
CIS option, 2-51
ClSTR option, 2-11, 12-8
format, 2-13
Cluster libraries, 2-121
and assembly language, 7-9
and calls between libraries, 7-10
and memory-resident overlays, 7-8
and the ClSTR option, 2-11, 12-8
Building, 7-8
GBUNC option, 12-16
GBlXCloption, 12-19
limitations of use, 2-14
revectoring, 7-10
trapping or asynchronous entry, 7-9
Cluster Libraries (ClSTR), 12-8
.CMD files, 10-4
CMPRT option, 12-9
COBLlB.OlB, 2-41
COBOL (PDP-11), 1-1
disk libraries for, 2-41
example build, 2-16
run-lime system for, 2-2
COBOl-a1, 1-1
disk libraries for, 2-5t
example build, 2-16
libraries in a cluster, 12-7
run-time system for, 2-2
symbolic debugger, 2-8
COBOVR.OlB, 2-5t
Code
sharable, 2-7
Comma
ODl operator, 3-4, 13-4
ODl operator (co-trees), 4-3
Command
CCl, 2-7
multiline, 2-9, 10-3
Command line
ending TKB, 10-3
ODl, 13-1
TKB, 2-8, 10-1
Comments, 10--6
Commercial instruction set option, 2-5t
Common area
allocating space for, 6--2
blank, 6--7
definition, 6--2
resident, 7-1, 12-26
COMMON option, 12-10
Comparison of disk and resident libraries, 2-7
Compilers, used with TKB, 1-1
Compiling (BASIC-PLUS-2 sample), 4-8
Completion Routine (CMPRT), 12-9
Complex relocation, 8-24
CON attribute, 6-4, 12-12, 13-4
Concatenated programs and subprograms (ICC), 11-3
Concatenation, 3-4,3-13, 13-4
Concurrent libraries, 6-4
Context, low core, C-9
Control section, 8-5

Index-2

Core common, 11-12
ICO switch, 11-4
Co-trees, 4-1 to 4-17, 11-11
and high-level languages, 4-8 to 4-17
fine-tuning, 4--13
how loaded during execution, 4--3, 4--3f
most space-saving, 4--5 to 4-8
sample program, 4-6
structure, 4-1
Cross-tree calls, 4--3
CSECT, 8-5

D
DAPRES library, 2-12
Dash
See Hyphen
IDA switch, 11-5, 8-26
Data PSECT, 6--5
Data space
See /- and O-space tasks

o attribute, 6--4, 6--5, 13-4
DBlLlB.OlB, 2-4t
DBRUB.OlB, 2-4t
DBRRES, 2-4t
$$DBTS, B-29
DCl (LINK command), 1-4
Debugger, 8-31
Debugger (COBOL-81), 2-8
Debugging Aid (IDA), 11-5, B-26
Declare Stack Size (STACK), 12-31
Default library, 3-15,11-8,11-11,11-17
how searched for co-trees, 4-3
in ClSTR option, 2-13, 12-8
using co-tree techniques on, 4--17
Default Library (lDL), 11-8
Define a Global Symbol (GBlDEF), 12-15
Define High Segment (HISEG), 12-20
Device
assigning, 12-8
Device designators, specifying, 2-9
Diagnostic
errors, A-1
messages, omitting, 11-20
run, 10-2
DIBOL, 1-1
disk libraries for, 2-4t
example build, 2-16
resident libraries for, 2-41
run-time system for, 2-2
DIBOl library, 2-12,12-7
DIBOl Management System, 2-4t
Directive emulation code for RSX, 2-11
Directory, internal symbol, 8-26
Disappearing RSX run-time system, 2-11
Disk access time, reducing, 3-9 to 3-10
Disk and resident libraries, comparison of, 2-7
Disk libraries, 2-4 to 2-5, 2-5f, 2-8,11-14
IDl switch, 11-8
OMS, 2-41
Double slash (II), to end TKB, 10--3
DSK attribute, 13-3
DSPPAT option, 12-11
Dump, 11-22

E
IEL switch, 11-7
.END command, 3-3 to 3-5,13-2
End-ol-module record, B-36
Enter Options prompt, 10-3
Error messages, A-I to A-8
diagnostic, A-I
fatal, A-1
Exclamation point (I), 7-5, 11-23
ODL operator, 13-4
Exclude Global from .STB File (GBLXCL), 12-19
Executable program
extending size of, 12-13
file, 2-8
file format, C-1f
patching, 12-4
Executable program file, 7-2
Exit on Error (/XT) , 11-38
Extend Library, 11-7
Extend Program Section (EXTSCT), 12-12
Extend Task Memory (EXTISK), 12-13
EXTSCT option, 12-12
EXTISK option, 12-13
example, 2-15

F
F4PCLS library, 2-12,12-7
F4POTS.OLB, 2-51
F4PRMS.OLB, 2-5t
Fast Map, 11-8
Fast Map overlay (/FO) , 11-9
Fast-mapping code, 7-29
Fast-Mapping Facility, 7-28 to 7-31
Fatal errors, A-I
FCS, 11-33
.FCTR command, 3-3 to 3-5, 13-2
nesting limit, 3-5
FDVDBG.OLB, 2-5t
FDVLlB.OLB, 2-5t
FDVRDB library, 2-12,12-7
FDVRES library, 2-12,12-7
File
Control System, 11-33
declaring maximum open, 12-5
executable, 2-8, 7-2, C-1
indirect command, 10-4 to 10-5
input to TKB, 10-2
library, 11-14
map, 2-8,10-1
memory map, 11-17
object, 2-4, 2-8
specifications, 10-6
symbol table, 2-8,7-2,10-1,12-20
task, 2--8,7-2, 10-1
FIRQB, 11-12
Floating-point processor, 11-10
FMS
disk libraries for, 2-5t
libraries in a cluster, 12-7
IFM switch, 11--8
FMTBUF option, 12-14
Format Buffer Size (FMTBUF), 12-14
FORTRAN-77, 1-1
disk libraries for, 2-5t
example build, 2-17

FORTRAN-77 (Cont.)
resident library for, 2-12, 12-7
run-time system for, 2-2
FORTRAN virtual arrays, 7-13
IFO switch, 11-9
IFP switch, 11-10
.FSRPT, C-9
IFU switch, 4-17,11-11
full search, 11-11

G
GBL attribute, 6-5, 13-4
segment name, 13-3
GBLDEF option, 12-15
GBLlNC option, 7-12,12-16
in cluster library example, 7-12
GBLPAT option, 12-17
GBLREF option, 7-6, 12-18
GBLXCL option, 7-12,12-19
Global additive displaced relocation, B-18
Global additive relocation, B-18
Global displaced relocation, B-17
Global Relative Patch (GBLPAT), 12-17
Global relocation, B-16
Global symbol item type, 8-32
Global Symbol Reference (GBLREF), 12-18
Global symbols
ambiguously defined, 3-12,4-6
autoload vectors for, 5-2
defining, 12-15
definition, 3-11
excluding from .STB file, 12-19
forcing reference in root, 7--8
general discussion, 1-3
including in .STB file, 12-16
in internal file, 11-34
multiply defined, 3-12, ~
name entry, B-7
reference from root, 12-18
reserved, 0--1
undefined, 3-12,4-6
GSD, B-1 to B-4, B--8, B-9, B-12

H
IHD switch, 11-12
Header, 11-12, C-6 to C-9
High segment, 1-3, 12-20
HISEG option, 12-20
Hyphen, 3-13
in .ROOT and .FCTR commands, 3-4 to 3-5
ODL operator, 3-4, 13-4
with library files, 3-5

I-and D-Space (liD), 11-13
1- and D-space tasks, 8-1 to 8-4
I attribute, 6-4, 13-4
liD switch, 11-13
Impure area, C-9
Include Global in .STB File (GBLlNC), 12-16
Indirect command files
ODL, 13-5
TKB, 10-4 to 10-5
Input files, 10-2

Index-3

Instruction space
See 1- and D-space tasks
Internal
displaced relocation, B-16
relocation, 8-15
symbol directory, 8-26
symbol name, 8-6
Internal symbol name item type, 8-34
$$IOB1, 12-23
ISD record, 8-1
description, 8-26
general format, 8-27
types, 8-26

J
Job area, 2-2 to 2-3
JSR PC instruction, 7-9
Jump table, 7-10

L
L$BBLK, C-5
L$BDAT, C-4
L$BDHV, C-5
L$BDLZ, C-5
L$BDMV, C-5
L$BDMZ, C-5
L$BEXT, C-4
L$BFL2, C-5
L$BFLG, C-4
L$BHDB, C-5
L$BHGV, C-4
L$BHRB, C-5
L$BLDZ, C-4
L$BLlB, C-4
L$BLUN, C-5
L$BMXV, C-4
L$BMXZ, C-4
L$BOFF, C-4
L$BPAR, C-4
L$BPRI, C-4
L$BRDL, C-5
L$BROB, C-5
L$BROL, C-5
L$BSA, C-4
L$BSEG, C-4
L$BSGL, C-4
L$BSYS, C-4
L$BTSK, C-4
L$BWND, C-4
L$BXFR, C-4
Label block group, C-2 to C-4
Languages, used with TKB, 1-1
LB:, 2-10 to 2-11
LBR utility, 11-36
ILB switch, 2-S, 3-5, 11-14
naming specific routines, 3-15,4-16,11-14
LCL attribute, 13-4
LD$ACC, C-6
LD$CLS, C-6
LD$REL, C-6
LD$RSV, C-6
LD$SUP, C-6
Libraries, 1-2,2-1 to 2-17
BP2RES, 2-12,12-7

Index-4

Libr aries (Cont.)
BP2SML, 2-12,12-7
CS1CIS, 2-12,12-7
CS1L1B, 2-12,12-7
clustering resident, 2-11, 2-12f
DAPRES, 2-12
default, 3-15
default in CLSTR option, 12-6
DIBOLR, 2-12,12-7
disk, 2-4 to 2-5, 2-5f, 2-8
F4PCLS, 2-12,12-7
FDVRDB, 2-12,12-7
FDVRES, 2-12, 12-7
indicating in ODL files, 3-13
object, 2-4
resident, 2-5 to 2-7, 2-10, 7-1,12-21,12-27
RMSRES, 2-12, 12-7
routines inserted in co-trees, 4-6
routines inserted in overlays, 3-13
rules for building cluster, 7-S
SMRES, 2-12,12-7
Library account (LB:), 2-10
Library File (/LB) , 11-14
LlBRoption, 2-10 to 2-11, 12-21
example, 2-17
.LlMIT (MACRO directive), B-20
Line-number or PC correlation item type, 8-34
LINK command, 1-4
Linking, general discussion, 1-2 to 1-3
III switch, 11-16
Literal record type, 8-36
Local symbols, 3-11
Location counter, 8-19 to 8-20
Logical independence, 3-2,3-8,3-10
Logical units
assigning, 12-6
declaring maximum number of, 12-35
Low core context, C-9

M
MAC assembler, 1-1,2-9
MACRO programs, 2-17
run-time system for, 2-2
with 1- and D-space tasks, 8-1 to 8-4
MAKSIL, 7-1,11-19
Map, ~
132 columns, 11-37
SO columns, 11-37
detailed description, 11-26 to 11-31
file, 3-6,6--6, 10-1, 11-17
first 1000 bytes in, 6--7
long, 11-26
overlay description, 3-7e
sample, 4-ge,6--9 to 6--15
sample with co-trees, 4-11e, 4-16
short, 11-26
spooling, 11-32
Map Contents of File (1M A) , 11-17
.MAP file, 2-8
Mapping, 2-5,2-11
Map Supervisor D-Space, 9-22 to 9-24
IMA switch, 4-17,6--6, 11-17
MAXBUF option, 12-23
Maximum Number of Units or Channels (UNITS),
12-35
Maximum Record Buffer Size (MAXBUF), 12-23

Maximum size, 2-2
Memory map, 3-6, 6--6
132 columns, 11-37
80 columns, 11-37
detailed description, 11-26 to 11-31
file, 10-1,11-17
long, 11-26
overlay description, 3-7e
sample listing, 6-9 to 6-15
short, 11-26
spooling, 11-32
Memory-resident overlays, 7-4 to 7-7, 11-23
Memory-resident overlays in cluster libraries, 7-8
Mode-Switching Vectors, ~1
Module, B-1
end-of-module record, B-36
general discussion, 1-2 to 1-3
general format, B-1f
name, B-5
Module name item type, B-31
IMP switch, 3-6,10-2,11-18
MRG utility, 3-2
MSDS$ call, ~23
Multiline command, 2-9, 10-3
Multiple builds in one run, 10-4
Multiply defined symbols
in a simple overlay, 3-12
in co-trees, 4-6
Multiuser Program (/MU) , 11-19
IMU switch, 11-19

N
N.OVPT, C-9
.NAME
for null co-tree root, 4-4
to make data PSECT autoloadable, 6-5
.NAME command, 13-2
Nested .FCTR commands, 3-5, 13-2
Nested parentheses, 3-9, 13-5
INM switch, 11-20
No Diagnostic Messages (/NM), 11-20
NODSK attribute, 13-3
NOGBL attribute, 13-3
Null root for co-tree, 4-4
Number of Active Files (ACTFIL), 12-5
Number of Address Windows (WNDWS), 12-39

o
$$OBF1, 12-14
Object files, 2-8
Object library file type, 2-4
.OBJ file, 2-8, 10-2, B-1
general format, B-1f
ODL, 13-1 to 13-5
command line, 13-1
ODL file, 3-1 to 3-6,10-2, 13-1
ODL operators, 3-4, 4-3, 4-5, 5-4 to 5-6, 13-4
ODT, 11-5,12-24
ODT SST Vector (ODTV), 12-24
ODTV option, 12-24
.OLB file, 2-4,2-8, 10-2
Option
ABORT, 12-3
ABSPAT, 12-4
ACTFIL, 12-5

Option (Cont.)
ASG, 12-6
CLSTR, 2-11,12-6
CMPRT, 12-9
COMMON, 12-10
DSPPAT, 12-11
EXTSCT, 12-12
EXTTSK, 12-13
FMTBUF, 12-14
GBLDEF, 12-15
GBLlNC, 7-12,12-16
GBLPAT, 12-17
GBLREF, 12-18
GBLXCL, 7-12,12-19
HISEG, 12-20
LlBR, 12-21
MAXBUF, 12-23
ODTV, 12-24
PAR, 12-25
RESCOM, 12-26
RESLlB, 12-27
RESSUP, 12-29
RNDSEG, 12-30
STACK, 12-31
(SUPLlB), 12-32
SVDB$, 12-24
SVTK$, 12-34
TASK, 12-33
TSKV, 12-34
UNITS, 12-35
VSECT, 7-14, 12-38
WNDWS, 12-39
Options, 2-10,10-3,12-1 to 12-39
summary, 12-1 to 12-2
Ordering program sections, 11-25
$OTSV, C-9
OUTS PC instruction, 7-9
Overlay Description Language, 3-1,3-3 to 3-6, 13-1
to 13-5
Overlay Map (IMP), 11-18
Overlays
brief discussion, 1-3
co-trees, 4-1 to 4-17
data structure, C-11
definition, 3-2
description of memory map, 3-7e
designing, 3-7
for COBOL programs, 3-2
memory-resident, 7-4 to 7-7, 11-23
memory-resident, in cluster libraries, 7-8
ODL file, 11-18
simple, 3-1 to 3-15
using the IMP switch, 11-18
Overlay tree, 3-10
OVR attribute, 6-4,6-5,12-12,13-4

p
Parentheses
nesting, 3-9
ODL operators, 3-4, 13-4
PAR option, 7-3 to 7-4, 12-25
Partition, 7-3 to 7-4
Partition for Resident Area (PAR), 12-25
Patching, 12-4
offset from global, 12-17
Path (overlay structure), 3-10 to 3-13

Index-5

PDP-11 C, 1-1
run-time system for, 2-2
PDP-l1 COBOL, 1-1
disk libraries for, 2-4t
example build, 2-16
run-time system for, 2-2
Performance, improving TK8, E-1 to E-3
Physical memory, 2-2
PIC
See Position independent code
IPI switch, 7-3, 11-21
PMDUMP, 11-22
IPM switch, 11-22
Position-independent (/PI), 11-21
Position independent code, 7-2 to 7-3
and cluster libraries, 7-8
Post-mortem Dump (/PM), 11-22
Programmer Control Regions, 7-26 to 7-28
Program Name for SYSTAT (TASK), 12-33
Program sections, 6-1 to 6-15
absolute, 13-4
allocating space for global, 6-2
appearing in map, 6-6
attributes, 6-1 to 6-4,13-3
changing order of, 11-33
concatenated, 6-4, 13-4
data, 6-4
definition, 6-1
extending size of, 12-12
global, 6-2, 13-4
in default library, 4-17
instruction, 6-4
in SYSLlB.OLB, 3-15
local, 13-4
overlaid, 6-4, 13-4
placing with .PSECT, 6-5
read/write, 6-2 to 6-4,11-19,11-33,13-4
read-only, 6-2 to 6-4,11-19,11-33,13-4
relocatable, 13-4
Program size, 2-2,3-1
Program status word, 11-36
Program version 10, 8-10
Project-programmer numbers, specifying, 2-9
.PSECT, 6-5, 13-3
PSECT, 8-5 to B-9
additive displaced relocation, 8-23
additive relocation, 8-22
displaced relocation, 8-21
item type, 8-32
relocation, 8-21
reserved names, 0-3 to 0-5
with 1- and D-space tasks, 8-1 to 8-4
.PSECT directive (MACRO), 6-1
PSW, 11-36

R
R$LDAT, C-6
R$LFLG, C-6
R$LHGV, C-6
R$LLDZ, C-6
R$LMXV, C-6
R$LMXZ, C-6
R$LNAM, C-6
R$LOFF, C-6
R$LSA, C-6
R$LSEG, C-8

Index-6

R$LWND, C-6
Read/write resident library, 2-11
Read-only resident library, 2-11
Record Management Services, 2-4t, 2-8
Region descriptor, C-19
Relative addressing, 1-3, 7-2
REL attribute, 6-5, 13-4
Relocatable/Relocated records, 8-30
Relocation
additive, 8-26
complex, 8-24
directory format, 8-141
entry, 8-15
global, 8-16
global additive, 8-18
global additive displaced, 8-18
global displaced, 8-17
internal, 8-15
internal displaced, 8-16
PSECT, 8-21
PSECT additive, 8-22
PSECT additive displaced, 8-23
PSECT displaced, 8-21
Relocation directory, 8-14
RESCOM option, 12-26
Reserved symbols, 0-1 to 0-3
Resident area, 7-1 to 7-7,11-21,12-10,12-25
absolute, 7-2, 7-3
position independent, 7-2 to 7-3
Resident common, 12-10, 12-26
building your own, 7-1
definition, 7-1
Resident libraries, 2-5 to 2-7,12-21,12-27
building your own, 7-1
clustering, 2-11
definition, 7-1
limit in a cluster, 12-7
maximum number, 2-7, 2-10
read/write, 2-11
read-only, 2-11
system-owned, 2-10
user-owned, 2-11
Resident Overlay (/RO), 11-23
Resident Supervisor-Mode Library, 12-29
RESLIB option, 2-10 to 2-11, 12-27
example, 2-17
RESSUP option, 12-29
Revectoring cluster libraries, 7-10
RLD record, 8-1
RMS, 2-4t
RMS-11 libraries in a cluster, 12-7
RMSDAP.OL8, 2-4t
RMSLlB.OL8, 2-4t
RMS resident libraries, 2-6
RMSRES library, 2-12,12-7
RNDSEG Option, 12-30
RO attribute, 2-11,6-4,13-4
in CLSTR option, 12-8
in cI uster libraries, 2-14
Root, 3-2, 3-8
co-tree structure, 4-1
null for co-tree, 4-4
putting libraries at end of, 3-13
simple overlay structure, 3-10
.ROOT, 13-4
.ROOT command, 3-3 to 3-5
IRO switch, 11-23

Round Segment (RNOSEG), 12-30
Routines
library (in co-trees), 4-6
library (in simple overlays), 3-13
RSX run-time system, 2-11
$$RTS, 6--7
Run, diagnostic, 10-2
Running the Task Builder, 2-7, 10-1 to 10~
Run-time system, 2-2 to 2-3
RSX, 2-11
RWattribute, 2-11,6--4,6--5, 13-4
in CLSTR option, 12-8
in cluster libraries, 2-14

s
Sample program
first build, 4-9
second build, 4-10
third build, 4-15
using co-trees, 4-6
SAVattribute, 13-4
ISB switch, 11-24
Segment
as described in map, ~
definition, 3-10,5-4
descriptor, 0-14
linkage, C-15
overlay format, 0-19
putting libraries at end of, 3-13
root, 3-8
root format, 0-19
Segmentation facility, 3-2
Segregate Program Sections (/SG) , 11-25
Selective Search (ISS), 11-34
Sequential (ISO), 11-33
Set SST Vector Table for Oebugging Aid (SVOB$),
12-24
Set SST Vector Table for Task (SVTK$), 12-34
ISG switch, 11-25
Sharable code, 2-7
Short Map (ISH), 11-26
ISH switch, ~, 11-26
Single slash (I), to end command line, 10-3
Slow build, 11-24
SMRES library, 2-12, 12-7
Spool Map Output (/SP), 11-32
ISP switch, 11-32
ISO switch, 11-33
ISS switch, 11-34
SST vector, 12-24, 12-34
Stack, 12-31
changing size, 6--7
definition, 6--7
for memory-resident areas, 7-2
STACK option, 7-2, 12-31
Start-of-segment item type, B-28
.STB file, 2-8,2-11,7-2,12-20, B-26, B-29
Supervisor-Mode Library, 9-1 to 9-22, 12-32
SUPLIB Option, 12-32
SVOB$ option, 12-24
SVTK$ option, 12-34
Switch
ICC, 11-3
ICO, 11-4
lOA, 11-5
10L, 11-6

Switch (Cont.)
IEL, 11-7
IFM, 11-8
IFO, 11-9
IFP, 11-10
IFU, 11-11
IHO, 11-12
110, 11-13
ILB, 11-14
Ill, 11-16
IMA, 11-17
IMP, 11-18
IMU, 11-19
INM, 11-20
IPI, 11-21
IPM, 11-22
IRO, 11-23
ISB, 11-24
ISG, 11-25
ISH, 11-26
ISP, 11-32
ISO, 11-33
ISS, 11-34
ITR, 11-36
!WI, 11-37
IXT, 11-38
Switches, 11-1 to 11-38
overview, 11-1 to 11-2
Symbolic debugger, 2-8
Symbols
ambiguously defined, 3-12,4-6
global, 3-11
local, 3-11
multiply defined, 3-12, 4-6
reserved, 0-1 to 0-3
undefined, 3-12,4-6,4-17
Symbol table, Task Builder's internal, 11-34
Symbol table file, 2-8,7-2,10-1, 12-20
Synchronous system trap, 12-34
SYSLlB.OLB, 2-4t, 3-15,11-6,11-17,11-33,11-36
SYSTAT, 12-33
System Common Block (COMMON), 12-10
System default library, 3-15, 11~, 11-11, 11-17
how searched for co-trees, 4-3
using co-tree techniques on, 4-17
System-owned resident library, 2-10

T
Table
jump, 7-10
vector, 7-10
Task, extending memory for, 12-13
Task Builder
aborting run, 12-3
command line, 2-8,10-1
data formats, B-1
exit on error, 11-38
improving performance, E-1 to E-3
options, 12-1 to 12-39
running, 10-1 to 10-6
switches, 11-1 to 11-38
work file, E-1
Task file, 2-8, 7-2, 10-1
Task identification item type, B-29
TASK option, 12-33
Task SST Vector (TSKV), 12-34

Index-7

T-bit, 11-36
Text information record format, B--12f
Time, reducing disk access, 3-9 to 3--10
TKB-generated record, B--28
Trace, 11-36
TRACE.OBJ, 11-36
Traceable Program (ITR) , 11-36
Transfer address, B--6
Trap, synchronous, 12-34
Tree
co-tree structure, 4--1
simple overlays, 3-10
ITR switch, 11-36
.TSK file, 2-8,2-11,7-2
TSKVoption, 12-34
TXT record, B-1

v
Vector
autoload indicator, 3-4
definition of autoload, 5-1
extension area, C--9, C--10f
revectoring cluster libraries, 7-10
SST, 12-24,12-34
table, 7-10
table code sample, 7-12
$VEXT, C--9
Virtual address space, 2-2
Virtual Program Section (VSECT), 12-38
Virtual Program Sections, 7-14 to 7-26
VSECT option, 7-14, 12-38

Undefined symbols, 4--17
in a simple overlay, 3-12
in co-trees, 4--6
UNITS option, 12-35
example, 2--15
User-owned resident library, 2-11
UTILITY, 7-1, 11-19

Wide Listing Format (!WI), 11-37
Window descriptor, C--18
Windows, declaring maximum number of, 12-39
!WI switch, 6--6, 11-37
WNDWS option, 12-39
Work file, E-1

x
XRB, 11-12

IXT switch, 11-38

Index-8

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing
your electronic, telephone, or direct mail order.

Electronic Orders
To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud
modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

800-DIGITAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

Puerto Rico

809-754-7575

Local Digital subsidiary

Canada

800-267-6215

Digital Equipment of Canada
Attn: DECdirect Operations KA02/2
P.O. Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6

International
Internal!

Local Digital subsidiary or
approved distributor
USASSB Order Processing - WMOlE15
or

U.S. Area Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 01473

IFor internal orders, you must submit an Internal Software Order Form (EN-01740-07).

Reader's Comments

RSTS/E Task Builder Reference Manual
AA-5072D-TC

Please use this postage-paid form to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your
comments on an SPR form.
Thank you for your assistance.

I rate this manual's:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

0
0
0
0
0
0
0
0

I would like to see morelless

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version _ _ _ of the software this manual describes.

Name!I'itle

Dept.

Company

Date

Mailing Address
Phone

Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - ,
NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

~DmDDmaTM

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

DIGITAL EQUIPMENT CORPORATION
CORPORATE USER PUBLICATIONS
CONTINENTAL BOULEVARD MK01-2/E12
PO BOX 9501
MERRIMACK NH 03054-9982

11111. 1111. 1111 •• 1.1 •• I•• 11.1111.1 •• I. .1. I. 11111 •I
II

_ _ _ _ _ _ _ _

Do Not Tear - Fold Here _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ --jI

Reader's Comments

RSTS/E Task Builder Reference Manual
AA-50720-TC

Excellent

QQod

Fair

Poor

0
0
0
0
0
0
0
0

I would like to see morelless

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version _ _ _ of the software this manual describes.

Nametritle

Dept.

Company

Date

Mailing Address
Phone

Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - - ,

momooma

™

NO POSTAGE

NI~;~~i~Y

UNITED STATES

I
I

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

DIGITAL EQUIPMENT CORPORATION
CORPORATE USER PUBLICATIONS
CONTINENTAL BOULEVARD MK01-2/E12
PO BOX 9501
MERRIMACK NH 03054-9982

11111 ••• 11.11 •••• 1.1 •• 1•• 11.1 •• 1.1 •• 1•• 1••• 1.111 ••• 1
_ _ _ _ _ _ _ _

Do Not Tear - Fold Here _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ I

()

...c:

Printed in U.S.A.