Digital PDFs

EY-0061E-SG-0201

May 1982

310 pages

Original

9.3MB

Document:	Programming RSX-11M in Fortran Volume II
Order Number:	EY-0061E-SG-0201
Revision:	0
Pages:	310
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/Programming_RSX-11M_Self-Paced_Training/EY-0061E-SG-0201_Programming_RSX-11M_in_Fortran_Vol_2_1982.pdf

OCR Text

EY -0061 E- SG- 020 1

Programming
RSX-llM
in FORTRAN
Volume II

EY -0061 E-SG-020 1

Programming
RSX-llM
in FORTRAN
Student Workbook
Volume II

Prepared by Educational Services
of
Digital Equipment Corporation

Copyright © 1982, Digital Equipment Corporation.
All Rights Reserved.
The reproduction of this material, in part or whole, is
strictly prohibited. For copy information, contact the
Educational Services Department, Digital Equipment
Corporation, Bedford, Massachusetts 01730.

Printed in U.S.A.

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 not be used or copied except
in accordance with the terms of such license.
Digital Equipment Corporation assumes no responsibility
for the use or reliability of its software on equipment
that is not supplied by Digital.

The following are trademarks of Digital Equipment Corporation,
Maynard, Massachusetts:
DIGITAL
DEC
PDP
DECUS
UNIBUS

DECsystem-l0
DECSYSTEM-20
DIBOL
EDUSYSTEM
VAX
VMS

MASSBUS
OMNIBUS
OS/8
. RSTS
RSX
lAS

CONTENTS
Volume I

SG STUDENT GUIDE
INTRODUCTION
• • • • • • • • • • • • •
PREREQUISITES. • • • • • • • • • •
•
COURSE GOALS AND NONGOALS. • • • •
COURSE ORGANIZATION. • •
• ••••••••••
COURSE MAP DESCRIPTION • • • •
COURSE MAP • • • • • • •
• • • • • • • • • • •
•• • • • • •
COURSE RESOURCES • • • •
Required References • • • • •
• • • • •
Optional References • • • • • • •
• • • • • •
HOW TO TAKE THE COURSE • •
• ••
PERSONAL PROGRESS PLOTTER. • • • •

....

• 3
• ·4
• 4
•'5

• 5
• 6

• 7
• 7
7

• 8
13

USING SYSTEM SERVICES
INTRODUCTION •
OBJECTIVES • • •
• • • • • • • • • • • • •
RESOURCES..
••• • •
• •••••••••••
WHAT IS A SYSTEM SERVICE?
••••••
WHY SHOULD YOU USE SYSTEM SERVICES?
•••••••••
To Extend the Features of Your programming
Language • • • • • • • • • • • • • • • • •
To Ease programming and Maintenance • • • • • • • •
To Increase Performance. • • • • • • •
• •••
WHAT SERVICES ARE PROVIDED?
•••••••••••••
System and Task Information • • • • • • • • • • • •
Task Control • • • • • • • • • • • • • • • • • • •
Task Communication and Coord ination. • • • • • • •
I/O to Peripheral Devices.
• •••••••••
Mern 0 r y Us e

•

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

OTHER SERVICES AVAILABLE • •
HOW SERVICES ARE PROVIDED.
Executive Directives • • • •
Code Inserted into Your Task
AVAILABLE FILE AND RECORD ACCESS
SYSTEM LIBRARIES • • • • • • • •

iii

• • • • • • • • •
Image • • • • • • • •
SYSTEMS • • • • • • •
• • • • •

17
17
17
19
19
19
19
20
20
20
21
21
21
22
22
23
23
26
28
28

DIRECTIVES
INTRODUCTION • • • •
• • • • • • • • • • •
•• • • • • •
•
OBJECTIVES ••
RESOURCES. • • • • • • • • • • •
•
, INVOKING EXECUTIVE DIRECTIVES FROM A USER TASK
Directive processing • • • • • • • • • • •
Functions Available Through Executive
Directives • • • • • • • • • • • • • • • •
The Directive Status Word (DSW). • • • • •
Sample Program • • • • • • • • • • • • • •
Example using Other Directives • ••
•
Run Time Conversion Routines • • • • • • •
NOTIFYING A TASK WHEN AN EVENT OCCURS. • • • •
Event Flag s . . . . . . . . . . . . . . .
Using Event Flags for Synchronization ••
Examples of the Use of Event Flags
for Synchronization • • • • •
ASYNCHRONOUS SYSTEM TRAPS (ASTs) • • • •

• •
• •
••
••

33
33
33
35
35

• •
• •

••
• •
••

36
39
42
46
47
47
48

49
53

USING THE QIO DIRECTIVE
INTRODUCTION • • • •
• • • • • • • • • • •
OBJECTIVES • • • • •
• • • •
• • •
RESOURCES. • • • ••
• • • • • • • • • • • • •
OVERVIEW OF QIO DIRECTIVES •
• • • • •
PERFORMING I/O • • • • • •
• ••
•• •
USING QIO DIRECTIVES IN FORTRAN. • • • • • ••
I/O FUNCTIONS. • • • • • • •
• • • • • • •
LOG ICAL UNIT NUMBERS (LUNs). • • • • • • • • • • •
SYNCHRONOUS AND ASYNCHRONOUS I/O • • • •
• • •
MAKING THE I/O REQUEST • • • • •
• • •
THE I/O PARAMETER LIST IN FORTRAN. • • •
•••
ERROR CHECKING AND THE I/O STATUS BLOCK. • • • • •
THE QIO DIRECTIVES • • • • • • • • • • • • • • • •
Synchronous I/O. • • • • • • • • • • • • • • •
Asynchronous I/O • • • • • • • • • • • • •
Synchronization With Asynchronous I/O.
TERMINAL I/O • • • • • • • • • • • • • • • • •
Device Specific Functions • • • • • • • • • • •
I/O Status Block and Terminating Characters • •
Read After Prompt. ••
• •••••••••
Read No Echo • • • • • • • • • • • • •
Read Wi th Timeout. • • • • • • •
Term inal- Independent Cursor Control. • • •

63
63
63
65
65
66
66
68
68
74
76
76
77
77
82
82

86
86
87

89
91
93

USING DIRECTIVES FOR INTERTASK COMMUNICATION
INTRODUCTION • • • • • • • • • • • • • • • • • • • • • 103
OBJECTIVES • • • • • • • • • • • • • • • • • • • • • • 103
RESOURCE • ,. • • • • • • • • • • • • • • • • • • • • • 103
USING TASK CONTROL DIRECTIVES AND EVENT FLAGS. • • • • 105
Directives • • • • • • • • • • •
• • • • • • • 106
SEND/RECEIVE DIRECTIVES. • • • • • • • • • • • • • • • 116
General Concepts • • • • • • • •
• • • • • • • 116
Directives • • • • • • • • • • • • •
• • • • • 116
Synchroni zing Send Requests Wi th
Receive Requests • • • • • • •
• 117
using Send/Receive Directives
for Synchronization. • • • • • • • • •
• • • • 132
Slaving the Receiving Task • • • • • • • • • • • • 132
PARENT/OFFSPRING TASKING • • • • • • • •
• • • • • 133
Directives Issued by a Parent Task • • • • • • • • 136
Directives Issued by an Offspring Task • • • • • • 145
Chaining of Parent/Offspring Relationships •
• 146
Other Parent/Offspring Considerations • • • • • • • 153
Retriev ing Command Lines in Spawned Tasks. • • 153
Spawning a Utility or Other MCR
Spawnable Task • •
• • • • • • • • •
• 153
Task Abort Status.
• ••••••••
• 157
Summary of Various Methods of Data Transfer
Between Tasks. • • • • • • • • • • I . • •
• 158
Comparison of Methods of Data Transfer •
• 158
Other Methods of Transferring or Sharing Data
Between Tasks • • • • • • • • • • • • • • • • • • • 159

.....

MEMORY MANAGEMENT CONCEPTS
INTRODUCTION • • • • • • •
• • • • • •
OBJECTIVES • • • • • • • • •
•
• •
RESOURCES. • • • • • • • • • • • •
GOALS OF MEMORY MANAGEMENT • • • •
• • • •
HARDWARE CONC EPTS. • • • . ' . • • • • • • • • •
Mapped Versus Unmapped Systems
• • • •
Virtual and Physical Addresses •
• • •
The KT-l1 Memory Management Uni t • •
•
Mode Bits • • • • • • • • • •
• • •
Active Page Registers (APRs) ....
•
Converting Virtual Addresses to Physical
Addresses. • • • • • • • • • •
• •••
SOFTWARE CONCEPTS. • • • • • • • •
Virtual Address Windows • •
Reg ions. • • • • • • • • •

•

163

• • • • 163
• • • • 163
• • • • 165
• • 165
•

•

• 165

• • • • 170
• • •

• 17~

•
••

• 173
173
• 176
• 178
• 178
• 179

Volume II

OVERLAYING TECHNIQUES
INTRODUCTION • • • • • • • • • • • • • • • • • • • • • 185
OBJECTIVES • • • • • • • • • • • • • •
• • • • • • 185
RESOURCE • • • • • • • • • • • • • • •
• • • • 185
CONCEPTS • • • • • •
••• • • • •
• • • • 187
OVERLAY STRUCTURE. • • • • • • • •
• • • • • • 188
STEPS IN PROGRAM DEVELOPMENT USING OVERLAYS.
• 191
THE OVERLAY DESCRIPTOR LANGUAGE (ODL). • • • •
• • 191
ODL Command Line Format.
••
•• •
•• 191
, TYPES OF OVERLAYS. • • • ••
• • • • • • • • • • • 195
Disk-Resident. ••
•• • •
• • • • 195
Memory-Resident. • • • • • • • • •
• •
•• 197
LOADING METHODS. • • • • • • • • • • • • • • • • • • • 201
Autoload • • • ••
• • • • • •
• • • • • • 201
Manual Load. • ••
• • • •
• • • • • • 203
Com pa r i so n 0 f a Ta s k Wi th No Over 1 a ys ,
With Disk-Resident Overlays, and
With Memory-Resident OVerlays • • • • •
• • 204
LIBRARIES. • • • • • • • • • • •
• • • .' 211
GLOBAL SYMBOLS IN OVERLAID TASKS •
• • 217
Data References in Overlays ••
• 219
CO-TREES • • • • • • • • • • • •
• • • • • • 225

STATIC REGIONS
INTRODUCTION • • • • • • •
• • 233
OBJECTIVES • • • • • • •
• • • • 233
RESOURCE • • • • • • • • •
• • • • 233
. • . • • . . . . . . . 235
TYPES OF STATIC REGIONS. •
. • • • . • . . . 236
MEMORY ALLOCATION • • • •
• • • • • • 237
MAPPING. • • • • • • • • • • • • • • •
REFERENCES TO A SHARED REGION.
• • • • 240
PROCEDURE FOR CREATING SHARED REGIONS
AND REFERENCING TASKS. • • • • • • • • • • • • • • • • 241
Creating a Resident Common. • • • ••
• • • • 241
Crea t ing a Re fer enc ing Task. • • • • • • • • • • • 249
Accessing a Reg ion for Read-Only or Read/Wri te •• 251
CREATING AND REFERENC INGA SHARED LIBRARY. • • • • • • 252
Task-Building the Shared Library
and the Re fer enc ing Task • • • •
• • • • 254
• • 257
DEVICE COMMONS • • • • • • • • • • • •

.....

DYNAMIC REGIONS
INTRODUCTION • • • •
• • • • • • • • • • • • • 261
OBJ ECTIVES ,. • • • • • • • • • • •
• • 261
RESOURCE • • • • • •
• • • • • • • • • • • • • 261
SYSTEM FACILITIES. •
• • • • • • • • • • • • • • • 263
REQUIRED DATA STRUCTURES • • • • • • • • • • •
• • 265
Region Definition Block (RDB).
• • 265
Creating an RDB in FORTRAN • • •
•••
• • 269
Window Definition Block (WDB).
••••
• • 270
Creating a WOB in FORTRAN. • • •
• • • • • • • 273
CREATING AND ACCESSING A REGION. • • • •
• 275
Creat ing a Reg ion. • • • •
•• • • ••
• • 276
Attaching to a Region. • • • • •
•••••
279
Creating a Virtual Address Window. • • • • • • • • 280
Mapping to a Region. • • •
• • • • • • • • • • 281
SEND- AND RECEIVE-BY-REFERENCE • • • • • • • • • • • • 289
THE MAPPED ARRAY AREA. • • • •
• • •
• • • • • 297

FILE I/O
INTRODUCTION • • • •
• • • • • •
OBJECTIVES •
• • • • • • •
RESOURCES. • • • • • • •
• • • • ••
OVER VI EW • • • •
•• • • • • • • • • •
TYPES OF DEVICES • • • •
•• • • • • •
Record-Oriented Devices • • • • • • • •
Fil e-Structured Dev ices. • • • • • • •
Types of File-Structured Devices •
COMMON CONCEPTS OF FILE I/O. • • •
Common Operations..
• •••••
steps of File I/O. • • • • • •
FILES-II • • • • • • • • • • • • • • • • •
FILES-II Structure • • • •
Directories • • • • • • •
Five Basic System Files.
•
Functions of the ACP • • • • • • • •
OVERVIEW AND COMPARISON OF FCS AND RMS • •
Common Functions • • • • • • • •
FCS FEATURES • • • • • • • • • • • • • • •
File Organizations • • •
Suppo rted Record Types • • • •
• •
Reco rd Access Modes. • • • • • • • • •
File Sharing • • • • • • • • •
• •

...

vii

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

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

• •
• •
• •

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

•
•
•
•

• •
• •
• •

•
•
•
•

• 305
• 305
• 305
• 307
• 307
• 307
• 307
• 308
• 310
• 310
• 310
• 311
• 311
• 316
• 319
• 320
• 323
• 323
325
• 325
• 325
• 329
• 331

RMS FEATURES • • • • • • • • • • • • • • • • •
• •
File Organizations • • • • • • • • • • • • • • • •
Record Formats • • • • • • • • • • • • • • • •
Record Access Modes • • • • • • • • • • • • • • • •
File-Sharing Features • • • • • • • • • • • • • • •
Summary. • • • • • • • • • • • • • •
• ••••

332
332
334
334
336
337

FILE CONTROL SERVICES
INTRODUCTION • • • • • • • • • • • •
OBJECTIVES • • • • • • • • • • • • • • • •
RESOURCE • • • • • • • • • • • • • • • • •
FILE ORGANIZATION VS. RECORD ACCESS. • • •
READ AND WRITE ACCESS TO A FILE..
••
TYPES OF RECORDS IN A FILE • • • • • • • •
FORMATTED AND UNFORMATTED RECORDS. •
DECLARING THE SIZE OF A RECORD • • • • • •
SUMMARY OF KEYWORDS IN THE OPEN STATEMENT.

•
•
•
•
•

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

•
•
•
•
•
•
•
•
•

341
341
341
343
344
344
345
345
346

AP APPENDICES
APPENDIX A
APPENDIX B
APPENDIX C
APPENDIX D
APPENDIX E
APPENDIX F
APPENDIX G
APPENDIX H

367
. . . . . · · · · · · · · · · 373
·········
· 375
·
·
·
·
·
.·····
· · · ·· ·· 377
379
·
·
383
397
· · · · · · ·· ··· ··· ··. ··· ··· 399

GLOSSARY
CONVERSION TABLES.
FORTRAN/MACRO-II INTERFACE
PRIVILEGED TASKS
TASK BUILDER USE OF PSECT ATTRIBUTES
ADDITIONAL SHARED REGION TOPICS.
ADDITIONAL EXAMPLE
LEARNING ACTIVITY ANSWER SHEET

viii

FIGURES

1-3

Using Executive Directives to Service a Task • • •
using Exe~utive Directives to Receive Services
From Other Tasks • • • • • • • • • •
Code Inserted into Your Task Image. • • • • •

2-1

AST Sequence.

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

Execution
Events in
Execution
Events in

4-1
4-2

parent/Offspring Communication Facilities.
Spawning Versus Chaining (Request and
Offspr ing Information). • • • • • • •

1-1
1-2

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

24
25
27

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

of a Synchronous I/O Request • • • •
Synchronous I/O • • • • • • •
of an Asynchronous I/O Request • • • • •
Asynchronous I/O. • • • • • • • • • • •

70
70
73
73
134
147

Physical Address Space in an Unmapped System.
Physical Address Space in an 18-Bit Mapped System
Physical Address Space in a 22-Bit Mapped System.
Virtual Addresses Versus Physical Addresses
on an Unmapped System • • • • • • • • • • • •
Virtual Addresses Versus Physical Addresses
on a Mapped System • • • ~ • • • • ~ • • • • •
••
Page Address Registers Used in Mapping a Task • • • •
A Task wi th Three Windows to Three Reg ions. • • • • •
Task in Figure 5-7 After Attaching to and Mapping
to a Fo urth Reg ion. • • • •
• • • • • ••

167
168
169

A Memory Allocation Diagram •
• •••••••
An Overlay Tree • • • • • •
• • • • • • • • •
An Example of Disk-Resident OVerlays. • • • •
An Example of Memory-Resident Overlays.
•
Task With Two Overlay Segments. • • • • • • • • •
Resolution of Global Symbols. • • •
• ••
Task Without Co-Trees • • • • •
• ••••••••
Use of Co-Trees • • • • • • •
••••••
••

190
190
196
199
213
218
227
228

171
172
175
181
182

7-1
7-2
7-3

Tasks Using a position Independent Shared Region • • • 238
Tasks Us ing an Absol ute Shared Reg ion • • • •
•• 239
Program Development for Shared Regions • • • • • • • • 243

8-1
8-2
8-3

The Region Definition Block •
The Window Definition Block ••
The Mapped Array Area • • • • • • •

9-1

Example of Virtual Block to Log ical Block,
to Physical Location Mapping. • • • • • • • • •
• 313
How the Operating System Converts Between
Virtual, Log ical, and Physical Blocks ••
• 314
FILES-II Structures Used to Support
Virtual-to-Log ical Block Mapping. • • • • • • •
• 315
Directory and File Organi zation on a Vol ume ••
• 317
Locating a File on a FILES-II Volume..
• • • • • 318
Flow of Control During the processing
of an I/O Request • • • • • • • • • • ••
•• • • 322
Move Mode and Locate Mode • • • • •
•• •
•• 324
Sequential Files • • • • • • • • • • • • • • • • • • • 325
RMS File Organizations • • • • • • • • • • • • • • • • 333

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

F-l
F-2
F-3
F-4
F-5
F-6

F-7

267
. . . . . . • •• •• 272
• • • • 298
..

A Shared Reg ion Wi th Memory-Resident OVerlays •
• 384
Referencing Two Resident Libraries. • • • • • ••
386
Referenc ing Combined Li brar ies. • •
• • • • • 388
Building One Library, Then Building
a Referencing Library • • • • • • • • • • • • • • • • 390
Revectoring • • • • • • • • • ••
• • • ••
• 391
Using Revectoring When Referenced Library
Has Overlays. • • • •
•• • • • • ••
• • • • 393
Cluster Libraries • • • • • • • • • • • • • • • • • • 395

TABLES

. . . 12

SG-l

Typical Co urse Sched ules. •

1-1
1-2

Standard Libraries ••
Resident Libraries ••

29
30

2-1

Types of Directives •

3-1
3-2
3-3

Common (Standard) I/O Functions • • • • • • • •
I/O Parameter List for Standard I/O Functions •
Some Special Terminal Function Codes • • • • • •

4-1
4-2
4-3
4-4
4-5
4-6
4-7
4-8
4-9
4-10
4-11
4-12

Task Control Directives and Their Use
for Synchronizing Tasks • • • • • • • • • • • • • • • 107
Stopping Compared to Suspend ing or Wai ting..
• • 108
Event Flag Directives and Their Use
for Synchronizing Tasks • • • • • • • • • • • • • • • 109
The Send/Receive Data Directive • • • • • • • • • • • 117
Methods of Synchronizing a Receiving Task (RECEIV)
With a Sending Task (SEND) • • • • • • • • •
• 118
Standard Exit Status Codes • • • • • • • •
• 135
Comparison of Parent Directives • • • • •
• 136
Directives Used by a Task to Establish138
a parent/Offspr ing Relationship • • • • • •
• • • 138
Directives Which Return Status to a parent Task
• 145
Directives Which Pass Parent/Offspring Connections
148
to Other Tasks • • • • • • • • • • • • • •
Task Abort Status Codes • • • • • • • • •
• 157
Comparison of Methods of Data Transfer
Between Tasks • • • • • • • • • • • • • • • • •
• 158
•

•

5-1
5-2

Mapped Versus Unmapped Systems. • • • • •
• • 166
APR and Virtual Address Correspondence • • • • • • • • 174

6-1

Comparison of Overlaying Methods.

7-1
7-2

Types of Static Regions Available on RSX-11M.
Required Switches and Options for Building
a Sh a r ed Reg ion • • • • • • •
• • • • • •

• • 210
• 236
• • 244

• • • • • • 264
• • • • • • 268
• • • • • • 274

8-1
8-2
8-3

Memory Management Directives.
Reg ion S ta t us Wo rd. • • •
Window Status Word. • • • • •

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

Compar ison of Physical, Log ical and Virtual Blocks • •
Examples of Use of F11ACP Functions • • • • • • • • •
Comparison of FCS Record Types.
• • •
• •
Comparison of Sequential Access I/O and
Random Access I/O • • • • • • • • • • • • • • • • • •
File Organization, Record Formats, and Access Modes.
Comparison of FCS and RMS • • • • • • • • • • • • • •

B-1
B-2

Decimal/Octal, Word/Byte/Block Conversions • • • • • • 373
APR/Virtual Addresses/Words Conversions..
• • • 373

312
321
328
330
335
338

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

Requesting a Task From Another Task
Using Some Miscellaneous Directives
Wai ting for- an Event Flag • • • • •
Setting an Event Flag • • • • • • •
Using a Requested Exit AST. • • • •

3-1
3-2

Synchronous I/O • • • • • • • • • •
Asynchronous I/O Using Event Flags
for Synchronization • • • •
Prom pt i ng fo r Input • • • •
Read No Echo • • • • • • • •
Read With Timeout • • • • •
Terminal-Independent Cursor Control

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

4-9

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

41
44
50
52
57

. . . . . . . . . 80
84
90
92

94
.......
. . . . . . . . . 98

Synchroni zing Tasks Using Suspend and Resume..
•
Synchronizing Tasks Using Event Flags • • • • • • • •
Synchronizing a Receiving Task Using Event Flags • • •
A Receiving Task Which Can be Run Before or After
the Sender. • • • • • • • • • • • • • • •
• •
Synchroni zing a Receiv ing Task Using RCDS • • • • • •
A Task Which Spawns PIP • • • • • • • • • • • • • • •
A Generalized Spawning Task • • • • • • • • • • • • •
An Offspring Task Which Chains Its parent/Offspring
Connection to PIP • • • • • • • • • • • • • • • • • •
A Spawned Task Which Retrieves a Command Line • • • •

III

114
120

124
129
140
143
150
155

6-5
6-6

Description of An Overlaid Task • • • • • • •
••
Map File of Example 6-1 Without Overlays • • • • • • •
Map File of Example 6-1 with Disk-Resident
Overlays • • • • • •
• •
Map File of Example 6-1 with Memory-Resident
Overlays. •
• ••••••••••••••
A Task Wi th Two Overlay Segments. • • • • • • • • • •
Complex Example Using Overlays • • • '. • • • • •
•

7-1
7-2

Resident Common Referenced with FORTRAN COMMON • • • • 247
Shared Library • • • • • • • • • • • • • • • • • • • • 255

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

xii

189
205

207
209
216
221

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

Creating a Region • • • • • • • • • • • • • • • • • •
Creating a Region and Placing Data in It • • • • • • •
Attaching to an Existing Reg ion and Reading Data
From It • • • • • • • • • • •
•
Send-by-Reference • • • • • •
•
Rece ive- by-Re ference. • • • •
•
Use of the Mapped Array Area.
•

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

10-5
10-6
10-7
10-8
10-9

Creating a Sequential File with Variable
Length Records • • • • • • • • • • • • • • • • • • • •
MACRO Equivalent of Example 10-1 • • • • • • • • • • •
P r og r am to Re ad a F i I e Crea ted in 10 -1 • • • • • • • •
Creating a File with Sequential, Fixed
Length Records. • • • • • • • • • • • • •
• •
Reading a Fixed Length Record • • • • • • • • •
•
Creating a Direct Access File • • • • • • • • • • • •
Creating an Unformatted, Direct Access File
•
Creating a Segmented File • • •
••••••
•
Creating a File using Block I/O. • • • • • • • •

G-1

Reading the Event Flags (for Exercise 1-1) • •

10-2
10 - 3
10-4

xiii

278
284
287
292
295
300
348
349
3 51
353
355
357
359
361
362

• • 397

OVERLAYING TECHNIQUES

INTRODUCTION
Overlays are used to allow a task to be developed and run if the
amount of memory available or virtual address space for a task is
insufficient. This module explains the various overlay techniques
which are available and how to use them.

OBJECTIVES
1.

To determine whether
to
use
a
disk-resident
memory-resident overlay in a given situation

To construct overlay
descriptor language

To write tasks using overlays.

structures

using

the

overlay

RESOURCE
•

RSX-IIM/M-PLUS Task Builder Manual, Chapters 3 and 4

185

OVERLAYING TECHNIQUES

CONCEPTS
A task may be too large to fit in the available memory.
This may
happen because it is larger than the total amount of memory on the
system. More likely,
it is because it is larger than the
partition it is to run in, or the available space within the
partition. The partition is probably used at the same time by
other tasks, hence, the available space may be considerably less
than the full partition.
For example, a 20K word task may have to fit
in 15K words of
memory.
The task can use overlays and load only portions of the
code at a time and just use 15K words of memory.
Typically,
the
pieces which overlay each other contain subroutines.
As an example, consider a task with main code and two subroutines,
G and H, which overlay each other. The main code calls subroutine
G first, causing GiS code to be read into memory.
Later, the main
code calls subroutine H, causing His code to be read into the same
memory locations, overlaying subroutine G.
If the main code later
calls G, GiS code overlays subroutine H. As the task executes,
overlaying is performed whenever necessary.
You can choose to
have all loading of overlay segments done automatically or you can
load them manually with specific calls to a loading routine.
In addition to physical memory limitations,
tasks on PDP-II
systems have virtual memory limitations. As we learned in the
last module, a task can use a maximum of 32K words of virtual
addresses at a time.
A task may require, say, 40K of virtual
memory,
thereby exceeding the 32K virtual addressing limit.
Overlays loaded from disk would permit this task to run in 32K
words or less of physical memory, and allow all of the code loaded
at any given time to be addressed. Therefore, 32K words, or less,
of code are loaded and addressed at anyone time, satisfying the
virtual address limit. Or, using a special kind of overlay, all
40K words of code can be loaded into memory, but the task maps
only 32K words of code at a time. This means that the task stays
within the virtual addressing limits even though it uses 40K of
physical memory.
These special kinds of overlays are called
memory-resident
overlays. They overlay by remapping rather than by reloading code
into memory.

187

OVERLAYING TECHNIQUES

An overlaid task can have several program segments.
A program
segment consists of part or all of one or more object modules.
Each of the object modules consists in turn of one or more program
sections
(Psects).
There is always a single resident root
segment. This segment is loaded when the task is first loaded and
remains· loaded and mapped at all times.
In addition, there are
overlay segments which either:
reside on disk unless needed
space and physical memory.

and

virtual

address

stay in memory once needed and share virtual address space
only.
There is one restriction on subroutines in an overlay segment.
They cannot call subroutines which are located in a segment which
overlays itself. The code for only one segment or the other is
available at anyone time, and never both. We say that the
segments must be logically independent.
There are some drawbacks to using overlays.
Additional code is
required to handle the overlay structure and the loading and/or
mapping of the overlay segments. Also, some execution time is
required to load and/or map the overlay segments.

OVERLAY STRUCTURE
Example 6-1 lists the subroutines
(corresponding to overlay
segments) which each segment calls during the execution of a task.
In addition, the sizes of the various modules are listed.
If the
task is built without overlays, it is 17K words in size.
We can reduce the amount of memory needed to 8K words by using
overlays.
Figure 6-1 shows a likely overlay structure, using a
memory allocation diagram. This picture represents the overlaying
or sharing of virtual and/or physical address space in the task.
Figure 6-2 shows another method for showing the same overlay
structure, an overlay tree.
It is easier to draw but doesn't
allow you to estimate the size of the task.
As the calculation
below Figure 6-1 shows,
the largest pieces which will ever be
needed at anyone time are PROG, the root,
and overlay segments
SUBI and B.
These total 8K words, so this task can run in 8K
words of physical memory.

188

OVERLAYING TECHNIQUES

Main Segment:
PROG
SUBI
SUB2
SUB3

calls:
calls:
calls:
calls:

PROG
SUBl, SUB2, SUB3
A, B
none
C, D, E

Segment

Size

PROG
SUBI
SUB2
SUB3
A
B
C
D
E

4K words
2K words
3K words
lK words
lK words
2K words
lK words
2K words
lK words

TOTAL

17K words

Example 6-1

Description of An Overlaid Task

189

OVERLAYING TECHNIQUES

!"'--

SUB2

SUBl

SUB3

PROG

TK-7764

Figure 6-1

A Memory Allocation Diagram

Overlaid Task Size = Size of Root + Sum of lengths of segments
using, the most overlay
area at anyone time
= Size of PROG + Size of SUB1 + Size of B
=
4K
+
2K
+
2K
= 8K

SUB1

I
I

SUB2

SUB3

PROG
TK-7765

Figure 6-2

An Overlay Tree

190

OVERLAYING TECHNIQUES

STEPS IN PROGRAM DEVELOPMENT USING OVERLAYS
Use the following steps in developing a task which uses overlays:
1.

Compile each module, producing a .OBJ file for each.

Use the editor to create an overlay descriptor file
(defines the overlay structure for the Task Builder).

Task-build using the overlay descriptor file as
input file.

the

only

THE OVERLAY DESCRIPTOR LANGUAGE (ODL)
The overlay descriptor language (ODL) is a fairly simple language
which is used to define the overlay structure for the Task
Builder. Statements are placed in a text file which has a file
type
• 0 DL •
(e •g • ,
EXAM P LE • OD L) •
It i sid en t i fie d to th eTa s k
Builder as a special file by using the 10VERLAY DESCRIPTION input
file qualifier (IMP in MCR) in the task-build command line.

ODL Command Line Format
The ODL command lines use the following format:
label:

directive

argument-list

;comment

where:
label - a one to six character symbolic, required only on a
.FCTR directive.
directive - one of the following
indicates the start of the overlay tree
indicates the end of input
allows naming of subtrees
allows naming a segment and assigning
attributes
.PSECT - allows special placement of a global
program section (Psect) - typically
used only in special cases in MACRO-II.

.ROOT
.END
.FCTR
• NAME

191

OVERLAYING TECHNIQUES

argument list - a list of .OBJ files and/or object
libraries, separated by hyphens or
commas, and grouped together with
parentheses.
comment - a comment to annotate the line
The separators have the following meaning:
•

Parentheses' ()'
enclose the segments to be overlaid

•

The hyphen

I_I

indicates the concatenation of virtual address space
•

The comma

',I

separates the segments to be overlaid

192

OVERLAYING TECHNIQUES

Examples of ODL:
1.

X, the root of a task, calls subroutines Y and Z.
Y

x
.ROOT
.END
Explanation:

X-(Y,Z)

X is the root segment, Y and Z are each
overlay segments. Virtual addresses are
assigned to X first. Starting after that,
Y and Z begin at the same virtual address.
Either Y or Z (never both) is loaded and
mapped using those virtual addresses.

Using the information from Example 1, Y
and V.

calls

subroutines

Z
X

.ROOT
.END
Explanation:

X-(Y-(U,V) ,Z)

Add to Example 1. U and V are overlay
segments which overlay each other. After
the last address for Y, virtual addresses
begin for U and V.

193

OVERLAYING TECHNIQUES

Using Example 1 again, add subroutine A to the root segment.
y

Z
A

X
.ROOT
.END
Explanation:

X and A together make up the root segment.
Virtual addresses are assigned first to X and.
then to A. After that, Y and Z are assigned
virtual addresses.

Using ODL to describe Example 6-1 (Figures 6-1 and 6-2):
.ROOT
.END
Explanation:

X-A-(Y,Z)

PROG-(SUBl-(A,B) ,SUB2,SUB3-(C,D,E»

PROG is the root segment. SUBl, SUB2, and
SUB3 overlay each other, beginning at the
same virtual address. A and B overlay each
other, beginning after SUBI. C, D, and E
overlay each other, beginning after SUB3.

Using the .FCTR directive to describe Example 6-1:
PARTl:
PART2:

.ROOT
.FCTR
.FCTR
.END

Explanation:

PROG-(PARTl,SUB2,PART2)
SUBl-(A,B)
SUB3-(C,D,E)

Substitute SUBl-(A,B) for PARTI in the first
line. Substitute SUB3-(C,D,E) for PART2 in
the first line.

194

OVERLAYING TECHNIQUES

TYPES OF OVERLAYS
There are two types of overlays available, disk-resident overlays
and memory-resident overlays.
In fact, both are loaded from disk.
The distinction is that disk-resident overlays are always loaded
from disk every time they are needed, while memory-resident
overlays are loaded from disk only the first time they are needed.
After that, they remain in memory and remapping is used to overlay
segments as needed.

Disk-Resident
Disk-resident overlays are available on all RSX-IIM systems.
See
Figure 6-3 for an example of a task with a root segment and three
disk-resident overlays.
On initial load, only the
root segment
MAIN is loaded.
Overlay segments are loaded from disk whenever
required.
This typically occurs when a subroutine in the overlay
segment is called.
So if the root overlay segment MAIN contains .a
call for subroutine A, for example, segment A is loaded from disk
prior to the transfer of control to A.
If, after the subroutine
returns control to MAIN, a call is made to subroutine B, segment B
is loaded into memory right over segment A.
If a call is later
made to subroutine C, segment C is loaded right over segment B.
This loading of overlay segments is performed whenever necessary.
The subroutines may be called in any order and each subroutine may
be called any number of times in the course of task execution.
The same starting virtual address is assigned to all three overlay
segments, A, B, and C, beginning at the next 32(10) word boundary
after the code for MAIN.
So A, B, and C use the same virtual
addresses and are loaded starting at the same physical address.
One virtual address window maps the entire task, just the code in
memory is changed when an overlay is loaded.
This technique is useful when the entire task is too large to fit
into the space allowed for it.
In the example in Figure 6-3, a
Disk-resident
22K word .task runs in 15K words of physical memory.
overlays are the default overlay type.
The examples in the
previous section all produce disk-resident overlays.

195

OVERLAYING TECHNIQUES

PHYSICAL
MEMORY

VIRTUAL
MEMORY
160000 APR7
140000 APR6
120000 APR5

100000 APR4
60000 APR3

TIME1
LOADED
AS NEEDED

•

TIME2

TIME3
C

t - - - - " - " - - - ' - - L . . . . - -.................... .

WINDOW

40000 APR2

o
20000 APR1

15K WORDS
INITIAL
LOAD

AND MAP
o APRO '"-_ _ _ _ _ _...._ _ _ _

M~IN

(ROOT SEGMENT)
~------

HEADER AND STACK

TK-7766

Figure 6-3

An Example of Disk-Resident Overlays

196

OVERLAYING TECHNIQUES

Memory-Resident
Memory-resident overlays are available only on mapped systems
which support the memory management directives.
See Figure 6-4
for the same task as in Figure 6-3, this time with memory-resident
overlays.
On initial load, again only the root segment MAIN is
loaded. The first time an overlay seg~ent is needed it is loaded
from disk.
However, once a segment is loaded it remains in memory
and is not reloaded from disk.
If subroutine A is called first, overlay segment A is loaded and
virtual address window I is mapped to A.
If, after the subroutine
returns control to MAIN, a call is made to subroutine B,
then
segment B is loaded,
but not directly over A.
Instead, it is
loaded into another area of memory, and then virtual address
window 1 is mapped to B.
If a call is later made to subroutine C,
segment C is loaded into another area of memory, and virtual
address window 1 is mapped to C.
The real gain in run-time efficiency is made when an overlay is
needed again.
If another call is mape to A, overlay segment A
does not have to be loaded again from disk.
It is already
memory-resident.
Therefore, virtual address window 1 is simply
remapped from segment C to segment A. Any additional overlaying
is performed by remapping, with no further loading of overlay
segments necessary. Again, the subroutines may be called in any
ord~r and each subroutine may be called ~ny number of times.
The advantage of this approach is that after the first load, it is
much faster
than disk-resident overlays.
However, there is no
savings in the use of physical memory.
In fact, a bit more memory
is required than with a non-overlaid task.
So its main use is for
overcoming the 32K word virtual address limit when execution time
efficiency is important. A 44K word task can use memory-resident
overlays if there is enough memory. available and the time
necessary
for
loading
disk-resident
overlay
segments is
unacceptable.
The root segment uses one window and each overlay area requires a
separate window.
This means that virtual addresses for each
overlay segment begin at the starting virtual address for the next
highest APR, corresponding to a 4K word boundary.
Because the
root segment is 9K(10), APRs 0, 1, and 2 must be used to map the
root segment.
Notice that A, B, and C all begin at virtual
address 60000, for APR 3~

197

OVERLAYING TECHNIQUES

This means that virtual addresses 44000-57777 cannot be used by
this t"ask.
If in fact MAIN were extended, then these virtual
addresses would be used. Remember, this doesn't mean that any
physical memory is wasted;
but it does mean that careful
allocation of sizes to the various segments is necessary to avoid
wasting virtual address space. Note that the maximum number of
overlay areas with memory-resident overlay is seven since the root
segment requires one virtual address window and each overlay level
requires another virtual address window.
To indicate that you want memory-resident overlays, place an
exclamation point (1) before an overlay specification. The'l'
applies only to the first level;
the next level may have
disk-resident overlays or memory-resident overlays again. The
only restriction on mixing of types is that once a level has
disk-resident overlays, no higher level may have memory-resident
overlays.

198

OVERLAYING TECHNIQUES

PHYSICAL
MEMORY

VIRTUAL
MEMORY

160000 APR7

140000 APR6

---~

120000 APR5

---

100000 APR4
WINDOW

{

60000 APR3

40000 APR2

~I N DOW

20000 AP R1
{

MAIN
(ROOT SEGMENT)
(9K WORDS)

MAIN
INITIAL LOAD

(ROOT SEGMENT)

•

AND MAP
o APRO '--_ _ _ _ _ _ _-'-________
_

-HEADER
----AND STACK

TK·1767

Figure 6-4

An Example of Memory-Resident Overlays

199

OVERLAYING TECHNIQUES

Examples of .ODL files for memory-resident overlays:
1.

X, the root of a task, calls subroutines Y and Z.

x
• ROOT
.END
The!

X-! (Y , Z)

makes the overlays memory-resident.

Using the information from Example 1, Y
and V.

calls

subroutines

some

disk-resident

J V
Z

Y
X

All memory-resident overlays:
.ROOT
.END

Some
memory-resident
overlays:
.ROOT
.END

X-I (Y-! (U, V) , Z)

overlays,

X-I (Y-(U,V) ,Z)

Illegal mixture:
.ROOT
.END

x-(Y-! (U,V) ,Z)

Explanation of c.:
This mixture is illegal because the first
level
(Y and Z)
is disk-resident.
The next higher level
cannot have memory-resident overlays.
Therefore, U and V
cannot be memory-resident.

200

OVERLAYING TECHNIQUES

LOADING METHODS
There are two loading methods, autoload and manual load.
With
autoload, any necessary loading and/or remapping (in the case of
memory-resident overlays) is done automatically and is transparent
to the program. With manual load, the overlay segments are loaded
by specific user calls to a loading routine. Autoload and manual
load cannot be mixed in the same task.

Autoload
When a call is made to a subroutine in an overlay segment, an
autoload
routine takes control before the transfer to the
subroutine is made.
It checks to find out whether the required
segment is already loaded or loaded and mapped.
It performs any
necessary loading and/or remapping.
Following that, the transfer
to the called subroutine is made.
Autoload is path loading, meaning that all segments along the path
to the
required overlay segment are loaded.
For example, in
example 2 in the previous section, involving X, Y, U, V, and Z, if
a call from segment X is made to subroutine U, both Y and U are
loaded.
(However, the auto-load routine checks to see if either Y
or U is already in memory and if so, the segments are not loaded.)
Autoload is indicated by an asterisk
(*)
before an overlay
specification in an ODL line.
An asterisk outside a set of
parentheses applies to all levels inside the parentheses.
The advantages of autoload are that it is easy to use and that it
does not require changes in the source code.
For instance, you
could make changes in the ODL commands for the task but you would
not have to make any cbanges in the source code. One disadvantage
to autoload is that it increases the size of the segments,
since
the autoload code plus its data structures must be included in the
task. Another disadvantage is that it executes slower than manual
load, since the autoload code has to check for whether the
required segment is available or not each time an autoloadable
segment is called.
In addition, autoload must be performed
synchronously.
See
Section
4.1
(on
Autoload)
i,n
the
RSX-llM/M-PLUS Task Builder Manual
for more
information about
autoload.

201

OVERLAYING TECHNIQUES

Examples of autoload:
1.

X, the root of a task, calls subroutines Y and Z.

x
With disk-resident overlays:
• ROOT,
.END

X-*(Y,Z)

With memory-resident overlays:
.ROOT
.END

X-*!(Y,Z)

Using the information from Example 1, Y
and V.
U

calls

subroutines

I V
Y

Z
X

With disk-resident overlays:
.ROOT
.END

X-*(Y-(U,V) ,Z)

With memory-resident overlays:
.ROOT
.END

X-*! (y-! (U,V) ,Z)

With some memory resident and some disk resident overlays:
• ROOT
.END

X-*! (Y-(U,V) ,Z)

202

OVERLAYING TECHNIQUES

Manual Load
With manual load, you must call the subroutine MNLOAD in the main
program or any subroutines to load and/or map any required overlay
segment
before
calling
a
subroutine
in
that
segment.
Additionally,
you must keep track of which segments are currently
available to avoid a transfer of control to an incorrect segment,
and to avoid unnecessary calls to the loading subroutine. Manual
load is not path loading.
In example 2 of the previous section,
if X calls U, it can load just segment U, without loading segment
Y, unless that is desired.
See Section 4.2 (on Manual Load)
in
the RSX-IIM/M-PLUS Task Builder Manual for more
information on
manual load.
Manual load is the default loading' method. Anytime that a segment
is not preceeded by an asterisk (*) in the ODL file, manual load
is used.
The advantages of manual load are that smaller overlay segments
result,
it is usually more run time efficient, and loading of
overlay segments can be performed either
synchronously
or
asynchronously.
The disadvantages are that the user must keep
track of things and that it requires special coding in the source
program.

203

OVERLAYING TECHNIQUES

Comparison of a Task With No Overlays, With Disk-Resident Overlays, and
With Memory-Resident Overlays
Example 6-1, shown earlier in the module, and repeated below for
convenience, shows a main program which calls a subroutine, which
in turn calls another subroutine, etc. Note that the sizes shown
for the various parts of the task are only approximate.
Main Segment:

PROG

PROG calls:
SUBl calls:
SUB2 calls:
SUB3 calls:

SUBl, SUB2, SUB3
A, B
none
C, D, E

Segment

Size (in words)

PROG
SUBl
SUB2
SUB3
A
B
C
D
E

4K
2K
3K
lK
lK
2K
lK
2K
lK

Total

17K

Example 6-1

Description of an Overlaid Task

Example 6-2 shows part of the task-build map for the
Example 6-1 when the task is built with no overlays.

task

Example 6-3 shows the map when
disk-resident overlays.

Example

6-1

built

with

all

Example 6-4 shows the map when
memory-:-resident overlays.

Example

6-1

built

with

all

Example 6-2 does not use overlays;
therefore no .ODL file is
required.
Examples 6-3 and 6-4 use overlays; therefore they
require a .ODL file. These files are shown along with the map.

204

OVERLAYING TECHNIQUES

Example 6-2 has a root segment but does not have any overlay
segments.
Note that a single virtual address window maps the
entire task.
The virtual address limits of the task are 000000(8)
and 105357(8), meaning that these virtual addresses are used to
reference the task code when it is loaded into memory.
The task
image is 17792(10) words long; hence 17792(10) words of physical
memory are required to load and run the task.
Task-build command:
LINK/MAP PROG,SUBl,A,B,SUB2,SUB3,C,D,E,LB:[l,l]FOROTS/LIBRARY

Partition name : GEN
Identification : 01
Task UIC
: [305,301]
Stack
limits: 000254 001253 001000 00512.
PRG xfr address: 021254
Total address windows: 1.
Task imaSe size
17792. words
Task address limits: 000000 105357
R-W disk blk limits: 000002 000107 000106 00070.

*** ROOT SEGMENT: PROG
R/W mem limits: 000000 105357 105360 35568.
Disk blk limits: 000002 000107 000106 00070.

Example 6-2

Map File of Example 6-1 Without Overlays

205

OVERLAYING TECHNIQUES

Example 6-3 with disk-resident overlays, has a root segment, PROG,
and eight overlay segments. Note that a single virtual address
window maps the entire task when just disk overlays are used;
i.e., when no memory resident overlays are used.
The overlay
description shows the virtual addresses and sizes of the segments.
On the right side, the segments are listed, lined up by overlay
level. Segments SUBl, SUB2, and SUB3 overlay each other.
They
all begin at virtual address 022200(8),
right after the root
segment PROG. At various times, virtual addresses starting at
022200(8)
reference the memory code of the overlay segment which
is actually loaded in memory at that time.
Segments A and B overlay each other, beginning with virtual
address 032234(8),
right after SUBI.
In a similar way, segments
C, D, and E begin at viitual addresses 026250(8),
right after
SUB3.
With
disk-resident overlays, only virtual addresses
000000(8) to 042237(8) are used to reference the task
in memory,
compared to 0000000(8) to 105357(8) without overlays.
This task
requires only 8800(10) words of memory, compared to 17792(10)
words with no overlays.

206

OVERLAYING TECHNIQUES

PROG.ODL file:
L:

.ROOT PROG-L-*(SUBI-L-(A-L,B-L) ,SUB2-L,SUB3-L-(C-L,D-L,E-L))
•. FACTR LB: [1,1] FOROTS/LIBRARY
.END

Task-build command:
LINK/MAP PROG/OVERLAY_DESCRIPTION
Note that LB:[l,l]FOROTS/LIBRARY must be concatenated with each
segment in the ODL file.
In the remaining examples of ODL files,
the concatenation of the library to each segment will not be shown
in order to simplify the appearance of the ODL file.

Partition name : GEN
Identification : 01
Task UIC
[305y301J
Stack
limits: 000260 001257 001000 00512.
PRG xfr address! 021260
Total address windows: 1.
Task ima~e size
8800. words
Task address limits: 000000 042237
R-W disk blk limits: 000002 000120 000117 00079.

EX63.TSK

Overla~

Base

Top

000000
022200
()32234

022177
032233
036237
042237
036203
026247
032253
03c!)253
032253

O:322~54
022:~00

022200
()26250
()262~50

()26250

Example 6-3

description:
Len~th

-_ .... _-022200
010034
004004
010004
014004
004050
004004
010004
004004

09344.
04124.
02052.
04100.
06148.
02088.
02052.
04100.
02052.

F'ROG
SUBl
A

B
SUB2
SUB3
C
D
E

Map File of Example 6-1 With Disk-Resident Overlays

207

OVERLAYING TECHNIQUES

Example 6-4, with memory-resident overlays, also has a root
segment,
PROG, and eight overlay segments. Notice -that three
virtual address windows are required for this task, one for the
root segment and one for each other overlay level.
PROG uses
virtual addresses 000000(8) to 023077(8), slightly more than with
Example 6-3.
However, segments SUB1, SUB2, and SUB3 begin at
virtual address 40000(8) corresponding to the next available APR,
APR 2, and not right after PROG. This is necessary because the
virtual address window must begin with the next APR.
Segments A
and B begin at 60000(8), since the next virtual address window
begins with APR3.
Segments C, D and E also begin at 60000(8)
for
the same reason. With memory-resident overlays, virtual addresses
000000(8) to 077777(8) are used and the task requires 18464(10)
words in memory.
The memory-resident overlay version of the task
requires the most virtual memory and also the most physical memory
of the three examples.

208

OVERLAYING TECHNIQUES

PROG.ODL file:
.ROOT PROG-*1 (8UB1-l (A,B) ,SUB2,8UB3-1 (C,D,E))
.END
Task-build command:
LINK/MAP PROG/OVERLAY_DESCRIPTION

Partition name
BEN
Identification
01
Task UIC
[305,301]
Stack
limits: 000320 001317 001000 00512.
PRG xfr address: 021320
Total address windows: 3.
Task imase size
18464. words
Task address limits: 000000 077777
R-W disk blk limits: 000003 000122 000120 00080.

EXDOVR.TSK Overlay description:
Base

Top

000000
040000
060000

023077
050077
064077
0700T7

O(SOOOO

040000
040000
060000
060000
060000

Example 6-4

O~j4077

044077
064077
070077
064077

Lensth

-----023100
010100
004100
010100
014100
004100
004100
010100
004100

09792.
04160.
02112.
04160.
06208.
02112.
02112.
04160.
02112.

PROG
SUBl
A

B
SUB2
SUB3
C
D
E

Map File of Example 6-1 With Memory-Resident Overlays

209

OVERLAYING TECHNIQUES

Table 6-1 refers to Examples 6-2, 6-3, and 6-4.
Table 6-1

Comparison of Overlaying Methods

Method

Task Size

Non-Overlaid

17792(10) Words
of Memory

Windows

Advantages
Smallest task size on
disk
Fastest execution
Simplest to develop

Disadvantages
Maximum task size 32K
words
Task smaller than 32K
words but tod large
for partition or for
available space in
partition

70(10) Blocks
on Disk
105360(8)
Virtual
Addresses Used

Disk-Resident

8800(10) Words
of Memory

Advantages and
Disadvantages

Advantages
Uses the smallest
amount of physical
memory
Uses the least amount
of virtual address
space

79(10) Blocks
on Disk

Disadvantages
Slowest execution
time; overlay segments
loaded from disk when
needed

42238(8)
Virtual
Addresses Used

Memory-Resident 18464(10) Words
of Memory

80(10) Blocks
on Disk

Advantages
Faster execution than
disk-resident overlays
Task resident in
memory at one time
Disadvantages
Uses the most memory
and disk space
May waste virtual
address space
Requires space in
memory to hold the
entire task

100000(8)
Virtual
Addresses Used

2l~

OVERLAYING TECHNIQUES

Table 6-1 gives a comparison of the three overlaying methods.
In
addition to the various sizes, it also lists the advantages and
disadvantages of each approach.
It is also possible to build this
task with memory-resident overlays for the first level (SUBl,SUB2
and SUB3) and disk-resident overlays for one or both of the second
levels (A and B; or C, D and E).

LIBRARIES
Object libraries, when used, must be specified in the
.ODL file.
The
one
exception
is
the
default
system
library
LB:[l,l]SYSLIB.OLB, which is searched automatically for
the root
and each overlay segment.
To allow inclusion of any needed
libraries, just specify the library with the /LB qualifier (as in
MCR format for TKB).
To force ,the inclusion of a specific module
from a library, use the /LB:module form of the /LB qualifier.
Examples:

1.
CPART:
LIB:

.ROOT
.FCTR
.FCTR
.END

Explanation:

MAINPG-MYLIBl/LB-LIB-(SUBA,SUBB,CPART)
SUBCl-(SUBC2,SUBC3)
MYLIB2/LB

Include all needed modules from MYLIBl.OLB
and from MYLIB2.0LB that are referenced in
the root segment MAINPG.

2.
.ROOT
.END
Explanation:

MAIN-MYLIB1/LB:MOD4-MYLIB1/LB-(A,B)

Include the module MOD4 from MYLIB1.OLB.
In addition, the second MYLIB1/LB with no
modules listed, causes the inclusion of
any other modules from MYLIB1.OLB that
are referenced in the root segment MAIN.

Note that if you reference additional library routines
from other segments, they will not get resolved properly
unless you specify the library again in each referencing
overlay segment.

211

OVERLAYING TECHNIQUES

Including the FORTRAN OTS Library:
LIBRA:

• ROOT
.FCTR
.END

MAIN-LIBRA-(A-LIBRA,B-LIBRA)
LB:[l,l]FOROTS/LB
or F4POTS/LB

Include needed modules from FOROTS.OLB (or F4POTS.OLB) in the root
segment,
in segment A, and in segment B. Notice that you should
specify the library in each segment which might need
it.
Otherwise,
if segment A needs a module not already included for
the root segment, the library is not searched again for module A
unless it is specified again in overlay segment A.
Note that in an installation which makes heavy use of FORTRAN, the
appropriate FORTRAN OTS library may have been included in SYSLIB
making it unnecessary to include the OTS library in the TKB
command. Check with your system manager to see if the OTS library
is included in SYSLIB.
Example of Duplicate Code in Overlays
In the above example with a root and two overlay segments, A and
B,
it is possible that duplicate code will be forced into the two
segments.
If A and B both need module X from' the 1 ibrary, and the
root does not need X, then a copy of X would be placed in both
segment A and in segment B. This adds to the size of segments A
and B but keeps the size of the root smaller.
If the size of the
root is critical, you may be willing to have the duplicate code
appear in A and B.
If the size of the root is not critical, force
X to be in the root by the following ODL statement:
LIB:

.ROOT MAIN-LB:[l,l]FOROTS/LB:X-LIB-(A-LIB,B-LIB)
.FCTR LB:[l,l]FOROTS/LB
.END

In general, it is good practice to include a library reference
in
each segment of the task.
If you are concerned with the
possibility of duplicate code, you can use the trial and error
approach wherein you specify the library only in the root and then
note the unresolved symbols that occur. Once you determine from
the TKB map which modules are needed in which segments, you can
then determine if you want to place certain modules in the root or
if you are willing to have duplicate code in various segments.

212

OVERLAYING TECHNIQUES

Duplicate code can also be included from SYSLIB,
the default
library.
If you wish to use the trial and error method on modules
from SYSLIB, use the /LONG qualifier in the LINK command
(/MA in
TKB format).
This qualifier causes the Task Builder to list
modules included from SYSLIB in the map file.
Note that in the previous example, if X had been required
in the
root,
duplicate code
in the overlay segments would not be
generated;
all references to X would be resolved via the root.
An Overlay Example
Example 6-5 is a simple task with a
root segment ROOT and
2
overlay segments, P and Q.
During the execution of the task, the
following calling sequence is used:
ROOT calls P
ROOT calls Q
Figure 6-5 shows an overlay tree and a memory
for this task.

allocation

diagram

The code for
Example 6-5 is separated
into three different
modules,
one for" each segment.
The source file for the root
segment ROOT contains the startup code and controls the overlay
loading by calls to
the subroutines. The source file for each
overlay segment, P and Q, contains the subroutine code.

OVERLAY TREE
MEMORY ALLOCATION DIAGRAM

ROOT

TK-7755

Figure 6-5

Task with Two Overlay Segments

213

OVERLAYING. TECHNIQUES

Steps in program Development for Example 6-5
1.

Compile each module.
>FORTRAN/LIST ROOT
)FORTRAN/LIST P
)FORTRAN/LIST Q

Use the editor to create the overlay
FEXDOVR.ODL for disk-resident overlays •
LIB:

descriptor

• ROOT ROOT-LIB-*(P-LIB,Q-LIB)
• FCTR LB: [1,1] FOROTS/LB
.END

Task-build using the .ODL file as the input file.
)LINK/MAP EXDOVR/OVERLAY_DESCRIPTION

LEARNING ACTIVITY
1.

To
build
the
above
memory-resident overlays,
modify the .OOL file?

To build the above task without overlays,
what task-build command would you use?

214

task
with
how would you

file

OVERLAYING TECHNIQUES

The following notes are keyed to Example 6-5.

o On initial load only the root segment ROOT is loaded.
autoload the call to subroutine P causes the autoload
o With
routine to load overlay segment P from disk and then
transfer control to the subroutine.

Subroutine P displays a message and returns.

call to subroutine Q causes the autoload routine to
o The
load overlay segment Q from disk over segment P and then
transfer control to the subroutine.

o Subroutine Q displays a message and returns.
If another call were added to subroutine Q, the autoload routine
would check and see that overlay segment Q is already loaded and
would then just transfer control to Q.
If another call were added
to subroutine P, the autoload routine would check and see that
overlay segment P is hot loaded. Hence, it would load segment P
over segmentr Q and then transfer control.

215

OVERLAYING TECHNIQUES

PI:::OGRAM ROOT
f'

C FILE ROOT.FTN
G

C This task calls each of the subroutines P AND Q

C Task-build instructions: Use FEXDOVR.ODL as the input
C' file.
C;

l~50

WRITE (5,50)
! Displaw messa~e
FORMAT (' THE ROOT SEGMENT IS NOW RUNNING AND
l.WIL.L CAL.L. P.')
CAL.L. F'
WRITE (5,150)
! Displaw messa~e
FORMAT (' THE ROOT SEGMENT WIL.L NOW CALL. a.')
CALL Q
WRITE (5,250)
! Displaw messa.e
FORMAT (' THE ROOT SEGMENT WILL. NOW EXIT.')
CALL EXIT
! EHit
END
SUBliOUT I NE P

C FILE P.FTN
C

C This subroutine displaws a messa.e and then returns
C

WRITE(5,50)
! Displaw messa~e
FORMAT (' SEGMENT P IS NOW LOADED. SUBROUTINE P
lIS EXECUTING.')
RETURN
! Return
END
SUBliOUT I NE Q

C FIl.E (1.FTN
C
C Thi~.; subroutine
C

displa~~s

a ITleSSaSe and then returns

WRITE(S,SO)
! Displaw messase
FORMAT (' SEGMENT Q IS NOW l.OADED. SUBROUTINE a
lIS EXECUTING.')
RETURN
! Return
END

>RUN EXDOVR
THE MAIN SEGMENT IS RUNNING AND WILL CALL P.
SEGMENT P IS NOW LOADED. SUBROUTINE P IS EXECUTING.
THE MAIN SEGMENT WILL NOW CALL a.
m~GMENT a IS NOW LOADED. SUBROUTINE a IS EXECUTING.
niE MAIN SEGMENT WILL NOW EXIT.

Example 6-5

A Task with Two Overlay Segments
216

OVERLAYING TECHNIQUES
Changing Example 6-5 to Manual Load
To change the previous example to manual load, the source code in
ROOT must be modified to include the calls to subroutine MNLOAD
which will cause the loading of the segments. The ODL file must
also be modified to remove the autoload indicator (*). The files
MLROOT.FTN and MLEXDOVR.ODL on the tape provided with this course
are modifications of ROOT.FTN and EXDOVR.ODL. Check UFD [202,3]
for these files.
See your course administrator if you have
difficulty finding these files.

GLOBAL SYMBOLS IN OVERLAID TASKS
When the Task Builder builds a task, 'each reference to a
subroutine is an unresolved symbol reference which must ultimately
be resolved by finding a corresponding subroutine or by finding an
entry in the system library.
(Each subroutine generates a global
symbol definition which can be used to resolve an unresolved
global
reference symbol.)
If no such subroutine or entry in the
system library is found, the global symbol is unresolved.
The scope of a global symbol
is controlled by the overlay
structure.
A module can only refer to a global symbol defined on
a path which passes through it.
Thus,
in Figure 6-6,
the
reference to global symbol R (global symbol and subroutine are
used synonymously in this discussion) in segment Al is undefined
because R is not defined' in either A0 or CNTRL. A0 and CNTRL form
the only path passing through AI.
The definition in A2 can't be
used because Al and A2 overlay one another.
In a single segment task with no overlays the same global symbol
cannot be defined more than once, or it is multiply defined. With
the rules governing global symbols in overlays, however, the same
name can be used for two different global symbols as long as they
follow these two restrictions:
1.

They must be defined on separate paths.
Each reference is
resolved to the definition on its own path.
Only if the
same symbol is defined more than once on the same path, is
it multiply defined.

The two symbols must not be referenced from a segment
closer to the root which has paths through both segments.
An example is a root segment which references a subroutine
N.
If the root segment has two overlay segments U and V
and each one defines the subroutine N,
the Task Builder
can't tell which subroutine N to use.
Therefore, the
reference is ambiguous, since there are several possible
ways to resolve the reference.

217

OVERLAYING TECHNIQUES

Figure 6-6 shows an example overlay tree with a number of global
resolved as
The various references are
symbol definitions.
follows:
Q is defined in A0 and B0

Reference in A22 resolved in A0
Reference in Al resolved in A0
Reference in Bl resolved in B0

R is defined in A2

Reference in A22 resolved to A2
Reference in Al undefined
Reference in CNTRL resolved to A2
(i f autoload, through an autoload
vector)

S is defined in A0 and B0

Reference
Reference
Reference
Reference
Reference
Reference

T is defined in A0 and A2l

Symbol multiply defined

A21

A22

T(DEF)
S(REF)

R(REF)
O(REF)
S(REF)

I
M
O(REF)
R(REF)
S(REF)

in
in
in
in
in
in

Al resolved to A0
A2l resolved to A0
A22 resolved to A0
Bl resolved to B0
B2 resolved to 80
CNTRL ambiguous

.!ll

R(DEF)

O(REF)
S(REF)

S(REF)

O(DEF)
S(DEF)
T(DEF)

O(DEF)
S(DEF)

I
£rill!.!:
S(REF)
R(REF)

TK-7756

Figure 6-6

Resolution of Global Symbols

218

OVERLAYING TECHNIQUES

Data References in Overlays
Data loca~ to an overlay segment is only available while the
segment 1S loaded.
When the segment is overlaid by another
segment, any updating of local data that had been made while the
segment was loaded will be lost.
The next time the same segment
is loaded from the disk, the original data values will be brought
into memory.
For this reason it is strongly recommended that data
required by more than one segment be placed in the root.
If you wish to share data between overlay segments, you must use
FORTRAN COMMON or pass arguments in the CALL (discussed below).
Note that if you want to share data between overlay segments A and
B,
and
if updating of the data can be done by either segment, it
is not sufficient to simply place the COMMON in A and B;
it must
also be placed in the root segment.
By placing the same COMMON in the root, you are assured that A and
B will always be referring to the same data in the COMMON since
the root segment is always loaded.
In FORTRAN-77 another way to
place a COMMON in the root is to use the FORTRAN SAVE common-name
statement in one of the segments.
This
will
force
the
task-builder
to place the named common in the root.
The .PSECT
ODL statement can also be used to force the placement of a common
in the root segmant.
Another way of sharing small amounts of data between two overlays
is to have the data passed from the root to each overlay as an
argument to the CALL.
If the segment changes one of the data
values passed as an argument, it will then be changed in the root
segment.
The changed value can then be passed to the next
overlay, etc.
Example 6-6 is a more complex example of the use of overlays.
program calling sequence is as follows:
MAIN calls A
A calls JOBI or JOB2 (in module JOBXX)
MAIN calls B
Loop through three time
MAIN calls A
A calls JOBI or JOB2
End of loop
MAIN calls TOTAL (in the root segment)

219

The

OVERLAYING TECHNIQUES

The following notes are keyed to Example 6-6.

ct Task-build instructions.
«t COMMON OTHER is defined in the root segment MAIN,

and is
referred to in overlay A and in overlays JOBI and JOBXX.
The entire allocation of space for OTHER is in MAIN;
no
space is reserved for OTHER in the overlays.
The use of the COMMON OTHER by the MAIN segemnt and the
the overlay segments allows the overlays to access data
provided by MAIN and to pass a result back to MAIN via the
This argument is called
fourth
argument in OTHER.
variously ANS in MAIN, ARG(4) in overlay A, SUM in overlay
JOBI and ANS in JOBXX.

TOTCOM is also defined in MAIN and is referenced in
o COMMON
overlays JOBI and JOBXX.
Allocation for TOTCOM is in
MAIN. Subroutine TOTAL displays the grand total, which
has been accumulated in TOTCOM in variable TOT, but the
subroutine does not refer to COMMON TOTCOM.
Since MAIN
passes
the
argument
TOT to subroutine TOTAL,
the
subroutine does not have to use TOTCOM. This illustrates
how shared data may be passed between overlay segments via
the argument list.

Note that subroutine A calls JOB2, which is the name of
the subroutine, and that the OOL file uses JOBXX which is
the file name.
File names are always used in OOL;
not
subroutine names.
In general, file names and subroutine
names should be the same simply to avoid confusion.

that neither COMMON OTHER or COMMON TOTCOM appear
in
o Note
segment B since the segment does not refer to any
variables in either COMMON.
()

Argument TOT is is COMMON TOTCOM.
Since the
passed
to subroutine TOTAL, TOTAL does
reference to COMMON TOTCOM.

220

argument is
not need a

OVERLAYING TECHNIQUES

PROGRAM MAIN

C FIl.E MAIN.FTN
C
C This pro~ram prints a

messa~e and then calls subroutine
Subroutine A asks whether to perform Job 1 or Job 2.P
C It then calls either subroutine JOBI or JOB2 which
("'
., performs the operation and displ~~s the results. MAIN
C then calls subroutine B which displa~s a messaSe. MAIN
f' then calls subroutine A 3 more times, keepinS a srand
C total of the operations. Finall~, it displaws the
C srand total and exits.

C A.

("'

Task-build instructions: Use FMRMAIN.ODL as the input
0 cc file.
C

COMPLEX DUMMYCI024)

! Leave space to make
!
seSment larSer

o COMMON
IOTHER/OP1,OP,OP2,ANS
INTEGER OP1,OP,OP2,ANS

DATA OP1,OP2/5,21

e COMMON
ITOTCOM/TOT
INTEGER TOT
e
("'

:lO

! Total

TYPE *,'THE MAIN SEGMENT IS RUNNING AND WILL
lCALL A'
CALL A
! Call subroutine A
TYPE *,'THE MAIN SEGMENT WILl. NOW CALL B'
CALL B
! Call subroutine B
DO 10, 1=1,3
TYPE *,'THE MAIN SEGMENT WILL NOW CALl. A'
ANS = 0
Clear answer in case
of no operation
CALL A
Call subroutine A
TYPE *, ' THE MAIN SEGMENT WILL CALL TOTAL'
! Call routine to
CALL TOTALCTOT)
displa~ srand total
TYPE *,'THE MAIN SEGMENT WILL NOW EXIT'
! EXIT
CALL EXIT
END

Example 6-6

Complex Example Using Overlays
(Sheet 1 of 4)

221

OVERLAYING TECHNIQUES

SUBROUTINE A

C FILE A.FTN
C

C This sub~outine displaws a messa~e and then asks which
C of two Jobs to do. It calls the app~opriate subroutine
C to do the Job, displaws the results, and then returns
C to the main pro~ram
C

o
f'

:1.0

1000
:1.001
2000

COMMON 10THER/ARG
INTEGER ARG(4)
INTEGER BUFF
TYPE 1
FORMAT (T8,'SEGMENT A IS NOW LOADED. SUBROUTINE
1 A IS EXECUTING.')
TYPE 2
FORMAT ('$',TS,'DO YOU WANT TO DO JOB 1 OR JOB 2
11 ')
ACCEPT 3,BUFF
FORMAT (16)
IF (BUFF.NE.l) GOTO 10
Is it Job 11
CALL JOBl
Call subr to do Job 1
GOTO 20
Branch to displaw code
IF (BUFF.NE.2) GO TO 1000! Is it Job 21
CALL JOB2
Call subr to do Job 2
TYPE 21,ARG
FORMAT (TS,I2,lX,A2,I2,' = ',13/)
GOTO 2000
TYPE 1001
FORMAT (TS,'NO SUCH JOB. SORRY.')
RETURN
! Return
END

Example 6-6

Complex Example Using Overlays
(Sheet 2 of 4)

222

OVERLAYING TECHNIQUES

SUBROUTINE JOB1
("

C FILE ..JOB1.FTN
C
C This subroutine performs an addition operation. The
C operands, operator, and sum are held in one common
C' block, and the total in another.
C

/OTHER/NUM1,OPRATR,NUM2,SUM
o COMMON
INTEGER NUM1,OPRATR,NUM2,SUM
/TOTCOM/TOT
e COMMON
INTEGER TOT

Leave space to make
module larger

INTEGER DUMMYCI024)

TYPE 1
Display message
FORMAT CT16,'SEGMENT JOB1 IS NOW LOADED.',
1/,T16'SUBROUTINE JOB1 IS EXECUTING.')
SUM :::: NUM1 t NUM2
Calculate sum
TOT = TOT t SUM
Add to grand total
OPRATR :::: 't'
Move operand for
output display
RETURN
END

SUB/i:OUTINE .JOB2

C FILE ..JOBXX.FTN
c
C This subroutine performs a multiplicat{on operation.
C The operands, operator, and product are held in one
r common block, the running total in another.
C

/OTHER/OP1,OPRATR,OP2,ANS
o COMMON
INTEGER OP1,OPRATR,OP2,ANS
/TOTCOM/TOT
e COMMON
I
TOT
NTEGE/;~

Leave space to make
module larger
TYPE 1
! Displaw message
FORMAT CT16,'SEGMENT JOBXX IS NOW LOADEri.',
1/,T16,'SUBROUTINE ..JOB2 IS EXECUTING.')
Calculate product
ANS :::: OP 1
OP2
Add this to grand total
TOT :::: TOT tANS
Move operand for
OP/i:ATR = '
output displaw
RETURN
END
REAL DUMMYCI024)

*
*'

Example 6-6

Complex Example Using Overlays
(Sheet 3 of 4)

223

OVERLAYING TECHNIQUES

Ct 'SUBROUTINE B

C FILE B.FTN
C
C This subroutine displaws a

messa~e

and returns

TYPE 1
FORMAT (Ta,'SEGMENT B IS NOW LOADED. SUBROUTINE
1B IS EXECUTING.')
RETURN
END

SUBROUTINE TOTAL (TOT)

C FILE TOTAL.FTN

c
r Subroutine to displaw ~rand total. The ~rand total
r location is passed as a subroutine ar~ument
C

INTEGER TOT
TYPE 1,TOT
FORMAT (' THE GRAND TOTAL IS ',13,'.'/)
RETURN
END

Run Session

>RUN MRMAIN
THE MAIN SEGMENT IS RUNNING AND WILL CALL A
SEGMENT A IS NOW LOADED. SUBROUTINE A IS EXECUTING.
DO YOU WANT TO DO JOB 1 OR JOB 21 1
SEGMENT JOBI IS NOW LOADED.
SUBROUTINE JOBI IS EXECUTING.
5

+ 2 =-

THE MAIN SEGMENT WILL NOW CALL B
SEGMENT B IS NOW LOADED. SUBROUTINE B IS EXECUTING.
l~E MAIN SEGMENT WILL NOW CALL A
SEGMENT A IS NOW LOADED. SUBROUTINE A IS EXECUTING.
DO YOU WANT TO DO JOB 1 OR JOB 21 2
SEGMENT JOBXX IS NOW LOADED.
SUBROUTINE JOB2 IS EXECUTING.
5

* 2 = 10

THE MAIN SEGMENT WILL NOW CALL A
SEGMENT A IS NOW LOADED. SUBROUTINE A IS EXECUTING.
DO YOU WANT TO DO JOB 1 OR JOB 21 2
SEGMENT JOBXX IS NOW LOADED.
SUBROUTINE JOB2 IS EXECUTING.
5

* 2 =- 10

THE MAIN SEGMENT WILL NOW CALL A
SEGMENT A IS NOW LOADED. SUBROUTINE A IS:EXECUTING.
DO YOU WANT TO DO JOB I OR JOB 21 1
SEGMENT JOBI IS NOW LOADED.
SUBROUTINE JOBI IS EXECUTING.
5

+2 -

THE MAIN SEGMENT WILL CALL TOTAL
THE GRAND TOTAL IS 34.
THE MAIN SEGMENT WILL NOW EXIT

Example 6-6

Complex Example Using Overlays
(Sheet 4 of 4)
224

OVERLAYING TECHNIQUES

LEARNING ACTIVITY (Using Example 6-6)
1.

Draw an overlay tree
or
a
memory
allocation diagram. Since the questions
below
assume
a
particular
overlay
structure, check your answer before doing
questions 2 through 4.

What .ODL file would you use for autoload
and all disk-resident overlays?

What .ODL file would you use for autoload
and all memory-resident overlays?

What .ODL file would you use for autoload
and A and B memory-resident and JOBI and
JOBXX disk-resident?

CO-TREES
Sometimes there are subroutines which must be callable from
several or all different overlay segments in a task.
One solution
is to place the subroutines in the root. Since they are always
loaded,
they are then available from the root and all overlay
segments.
If this causes the task to become too large and the
subroutines are logically independent
(don't call each other),
another solution is available.
You can set up a separate overlay
area and place the subroutines in it so that they overlay each
other.
For example, Figure 6-7 shows an overlaid task with subroutines X
and Y in the
root.
They are placed there so that the root and
every other segment can call them.
If this makes the task too
large, set up a separate overlay area and place X and Y in it 50
they overlay each other (Figure 6-8). X and Yare in a separate
overlay area, therefore, they can overlay each other and still be
called from the root and every other segment in the task.

225

OVERLAYING TECHNIQUES

The two overlay areas, the main one and the separate one for
the
extra subroutines, are defined by a multiple tree structure.
The
tree for the main code is called the main tree and the other one
is called a co-tree.
The co-tree root may contain code but it
does not have to.
In the example in Figure 6-8, the root of the
co-tree is null (or is a dummy root) and contains no code. A root
is needed to set up the overlay structure. Only the root of the
main tree is loaded on initial load. The co-tree roots are loaded
when they are first needed and remain loaded after that.
Other
than
that,
loading of overlay segments works
just like a
single-tree overlay structure.
The .ODL files are listed above the files
for
the task without
co-trees and with co-trees.
The co-trees are separated in the
.ODL file by a comma. with autoload, an asterisk
(*)
should be
specified on the co-tree roots as well as in the normal places.
This is necessary because the co-tree roots are loaded like
overlay segments the first time they are needed.
Also, note that
the .NAME directive is used to specify that CNTRL2 is just a name
for the null root segment of the co-tree.
For additional information on co-trees and an example, see Section
3.5
(on Multiple-Tree Structures)
in the RSX-llM/M-PLUS Task
Builder Manual.
In particular, note the use of the /NOFU or /FU
switch used with TKB.

226

OVERLAYING TECHNIQUES

.ODL File with no co-trees:
.ROOT
.END

CNTRL-X-Y-*{A0,{Al,A2) ,80-{81,82))

I
I
CNTRl
X

AO
Y

CNTRl

TK-8635

Figure 6-7

~ask

Without Co-Trees

227

OVERLAYING TECHNIQUES

.ODL File with Co-Trees
.NAME CNTRL2
.ROOT CNTRL-*(A0-(Al,A2) ,B0-(8l,82)), *CNTRL2- *(X,Y)
.END
The segment CNTRL2 is a dummy root used for loading purposes only.

A1
I

I
I

81
I

A2
I

I
I

82
I

CNTRL

CNTRL2

NULL ROOT CNTRL2
81

82
80

AO
CNTRL

TK-7768

Figure 6-8

Use of Co-Trees

228

OVERLAYING TECHNIQUES

Now do the tests/exercises for this module in the Tests/Exercises
book.
,They are all lab problems.
Check your answers against the
solutions provided, either in that book or in on-line files.
If you think that you have mastered the material, ask your course
administrator to
record your progress in your Personal Progress
plotter. You will then'be ready to begin a new module.
If you think that you have not yet mastered the
to this module for further study.

229

material,

return

STATIC REGIONS

INTRODUCTION
Logical address space in a task is composed of regions.
There are
three basic types of regions:
task regions, static regions, and
dynamic regions.
Task regions, into which tasks are loaded, are
created using information set up by the Task Builder. Static and
dynamic regions are generally used to share code or data among
several tasks.
Static regions are created using the Task Builder;
dynamic regions are created during task execution using executive
directives.
This module discusses static regions.
regions to:

You can

use

these

static

•

Create memory areas containing code which is shared
tasks

among

•

Create memory-resident data areas which can be used for
communication between tasks or successive invocations of
the same task.

OBJECTIVES
1.

To create and use a resident common region

To create and use a resident library

To determine whether a position independent or an absolute
shared region should be used in a given situation.

RESOURCE
•

RSX-IIM/M-PLUS Task Builder Manual, Chapter 5

•

233

STATIC REGIONS

TYPES OF STATIC REGIONS
Static regions, also called shared regions, are areas of memory
which are shared among tasks.
They allow tasks to share data or
code with very little overhead.
Unlike send
and
receive
directives, no executive directives are needed and the area's size
is limited only by virtual address and possibly physical memory
limitations.
The virtual addressing limit must be met for both
the region itself and for any tasks which use the region.
For a
task using the region, the virtual addressing limit applies to the
total of all regions used plus the task's code.
Static regions also offer very quick access,
since the area is
loaded before the tasks which use it are run.
Once loaded, it is
available directly in memory.
Therefore, it offers much faster
access than disk-resident data.
Table 7-1 summarizes the types of shared regions available on an
RSX-IIM system. A resident common contains data.
The data can be
accessed by several different tasks, each with read only access or
with read/write access.
A resident library contains reentrant subroutines, which can be
called by several different tasks.
A single copy of each
subroutine can be shared,
thus reducing the
total
memory
requirements of the tasks.
The term resident is used because the
shared region is task-built, installed,
and I loaded into memory
separately from the tasks which access it.
A third type of shared region is a device common, a special type
of resident common.
It occupies physical addresses on the I/O
page, which correspond to I/O device registers instead of physical
memory.
Therefore, this kind of common allows a task to reference
an I/O device directly.
Unlike other resident commons,
a device
common has no true contents because it has no physical memory
associated with it.

235

STATIC REGIONS

Table 7-1 Types of Static Regions
Available on RSX-llM
Type of Region

Contents

Advantages

Resident Common

Data accessed
by two or more
tasks

Serves as communications link
Serves as memoryresident data base

Resident Library

Reentrant routines,
used by two or more
tasks (must be writen in MACRO-II but
can be used in a
FORTRAN CALL)

One copy of common
routines shared in
memory

Device Common

No true "contents"
Region is a range
of physical addresses
within I/O page

Nonprivileged task
can directly access
an I/O device without being mapped
to the Executive

MEMORY ALLOCATION
Memory is allocated independently to the shared region and to the
individual tasks which use it. We will call the tasks which use
the region referencing tasks.
On an RSX-IIM system,
the shared
region must reside in a dedicated common type partition. The name
of the partition must be the same as the name of the region.
The
partition can be created at SYSGEN time or later by the system
manager or by a privileged user.
Once the region is installed and
loaded into the partition, it cannot be checkpointed.

236

STATIC REGIONS

MAPPING
Shared regions can be written and task-built as either position
independent regions or as absolute regions.
On a mapped system,
position independent regions can be placed anywhere
In
a
referencing task's virtual address space. This means that the
virtual addresses used to map to the region can correspond to any
available APR.
Figure 7-1 shows a position independent region POSIND and three
referencing tasks.
The region is loaded into memory into the
partition POSINDi
the partition name must be the same as the name
of the region. Recall that a virtual address window for mapping
must begin with a base address for an APR on a 4K word boundary.
Because the region is 5K words in length and each APR can only map
at most 4K words, two APRs are needed to map the region.
TASK A maps the shared region using APRs 6 and 7, starting at
virtual address 140000{8).
It could in fact use APRs 5 and 6,
beginning at virtual address l20000{8);
or APRs 4 and 5,
beginning at virtual address l00000{8).
TASK B maps the shared region at the first available APR above the
task code, using APRs 2 and 3, beginning at virtual address
40000{8).
It could use APRs 3 and 4, 4 and 5, 5 and 6, or 6 and 7
as well.
Task C maps the shared region using APRs 6 and 7, starting with
virtual address 140000{8).
There is no other possible way for
task C to map the shared region because APR 6 is the first
available APR.
When you task-build a referencing task, you can specify which APR
to use in mapping the region.
If you do not specify an APR, the
Task Builder selects the highest set of available APRs. When task
A and task C were built, either the user did not specify an APR,
or APR 6 was specified. When task B was built, the user specified
APR 2.
An absolute shared region has its virtual addresses fixed when it
is task-built.
All tasks which reference it must use those
virtual addresses, and the corresponding APRs, to map to the
region.
Figure 7-2 shows another region, ABSOLU,
and three
referencing tasks A, Band C. The shared region ABSOLU was built
to use virtual addresses 120000 (8) through 147777 (8) (6K words)
with APRs 5 and 6. All referencing tasks must map to the region
using these APRs.
Therefore, task A and task B can both map to
the region, since APRs 5 and 6 are available.
Task C, on the
other hand, cannot reference ABSOLU, since APR 5 is already used
by its task code.
237

STATIC REGIONS

VIRTUAL
MEMORY

PHYSICAL
MEMORY

TASK A
160000 APR7
140000 APR6
120000 APR5
100000 APR4
60000 APR3
TASK
WINDOW
(16K WORDS)

40000 APR2
20000 APR1

o APRO

TASK
REGION
(TASK A)

160000 APR7
140000 APR6
120000 APR5

100000 APR4
60000 APR3
40000 APR2
20000 APR1

o APRO

160000 APR7

I I

~-......:...;..--....;.....-------..---rt--

TASK
REGION
(TASK B)

II __ ------

------~1T

FJ')'J'J,;~~~~~~".J/
/
~~~~~~~/

///
,/'/

140000 APR6

TASK
REGION
(TASK C)

120000 APR5
100000 APR4
60000

APR3

TASK
WINDOW

40000

APR2

(24K WORDS)

20000 APR1

o APRO
TK-7774

Figure 7-1

Tasks Using a position Independent Shared Region

238

STATIC REGIONS

VIRTUAL

PHYSICAL·

MEMORY

TASK A
160000 APR7

----

140000 APR6
120000 APR5

ABSOLU
(ABSOLUTE REGION)

100000 APR4
60000 APR3
TASK

40000 APR2

WINDOW

20000 APR1

(16K WORDS)

APRO
TASK

REGION
(TASK A)

160000 APR7
140000 APR6
120000 APR5
100000 APR4
60000 APR3
40000 APR2
20000 APR1

o APRO

------

TASK

REGION

(TASK B)

TASK

WINDOW

(8K WORDS)

--------------------

_-----

---

TASK C
160000 APR7

140000 APR6
120000 APR5

100000 APR4

TASK

60000 APR3

WINDOW

40000 APR2 ~

(24K WORDS)

20000 APR1 ~
o APRO .......___________

CAN'T
REFERENCE
ABSOLU

TK-7769

Figure 7-2

Tasks Using an Absolute Shared Region

239

STATIC REGIONS

Because of the added flexibility of a position independent region,
i.e., any APR can be used to map the region, it might seem that
there is no reason to ever use an absolute region with
its
attendant
APR
restrictions.
However,
there
are
coding
restrictions for position independent regions which require the
use of highly specialized coding techniques.
Because of these
restrictions, the decision to create a position independent or an
absolute region is usually based on these coding restrictions
rather than on flexibilty alone.
In general,
resident commons,
containing data, are
created
position independent and resident libraries, containing code, are
created absolute.
Figure 7-3 shows the program development process for creating a
shared region and a
referencing task.
Specific steps for each
process are discussed later
in this module.
Compile
and
task-build the shared region separate from the referencing task,
and before task-building the referencing task.
Since it is not an executable task,
certain task-build switches
are used to create a task image with no header and no stack. An
additional file, called a symbol definition file, is also created
at task-build time.
This file contains information about the
symbols defined in the region which the Task Builder will use when
it builds the
referencing
task to set up the linkage to the
region.
After task-building the shared region, task-build the
referencing
task.
It can be written and compiled earlier, if desired.
The
name of the region is specified to the Task Builder so that it can
access the symbol definition file and set up the linkage to the
shared region.
The shared region must be installed (causing it to
be loaded into memory as well) before any referencing task is run.

REFERENCES TO A SHARED REGION
The following kinds of references are made to a shared region by a
referencing task:
•

The task retrieves data from or stores data in a
resident
common.
FORTRAN COMMON is used for this purpose.

•

Subroutine call
region.

subroutine

240

defined

shared

STATIC REGIONS

PROCEDURE FOR CREATING SHARED REGIONS AND REFERENCING TASKS
Creating a Resident Common
Typically consists of a COMMON
statements which allow you to

Code the shared region.
statement
and
DATA
initialize the COMMON.

Choose position independent for a resident common.

Compile the shared region.

If not already done, create the common type partition.
•

Name must be the same as the name of the region.

•

Best done when the system is SYSGENed.

•

Use the SET PARTITION (SET/MAIN
create a partition.

•

Use the SET NOPARTITION (SET/NOMAIN in MCR) command to
eliminate a partition.

•

Examples:

MCR)

command

)SET PARTITION:MYCOM/BASE:7114/SIZE:200/COMMON
Creates the common type partition MYCOM with base
physical address 711400(8) and size 20000(8) bytes.
no other partition may use this space at the same
time.
)SET NOPARTITION:MYCOM
Eliminates the partition MYCOM.
NOTE
Before you create or eliminate any partitions on
your system, check with your system manager to
find out what area of memory you may use.

241

STATIC REGIONS

Task-build the shared region.
•

Symbol definition file

(.STB)

required.

•

Build position independent and
/SHAREABLE:COMMON.
This causes the Task Builder to include the COMMON
names in the .STB file so that references to them in
the referencing task are properly resolved.
The
/SHAREABLE:LIBRARY switch
used
in
task-building
resident libraries causes the COMMON (Psect for MACRO)
names to be omitted from the .STB file.
This avoids
task-builder errors in the case of unintentional
duplication of Psect names.

•

Use required switches and options (see Table 7-2).

Install the shared region in the common
before running any referencing task.

type

•

Not required
tasks.

task-building

the

referencing

•

Use the INSTALL (INS in MCR) command
region.

install

before

partition

the

This command also loads the region into memory.
This is unlike an executable task, which is
usually loaded into memory only when it
is
activated.
•

There is no command to remove a region.
It is removed
by either installing another region or eliminating the
partition.

242

STATIC REGIONS

LIBRARY
FILE{S)

SHARED
REGION

TASK REFERENCING
SHARED REGION

CREATE
SOURCE CODE

ASSEMBLE
OR COMPILE

SYMBOL
DEF'N
FILE

TASK
BUILD

INSTALL
SHARED
REGION

TASK
BUILD

RUN
TASK

TK-7770

Figure 7-3

Program Development for Shared Regions

243

STATIC REGIONS

The required switches and options in Table 7-2 are needed for
various reasons. No header or stack is needed because this is not
an executable task.
The referencing tasks each have their own
header and stack.
The symbol table definition file is needed to
allow the Task Builder to link referencing tasks to the region.
The partition name specifies the partition into which the region
will be loaded.
For an absolute region you must specify a base address.
If you
specify a nonzero length,
that value is used as a maximum, for
length checking. A task-builder error results if the length of
the region is longer than the length specified.
If you specify a
length of 0, the region is set up with the size needed for
the
code,
so long as it doesn't exceed the normal 32K word virtual
addressing limit.
Table 7-2

Required Switches and Options for Building
a Shared Region

Switch/Option
in DCL (MCR)

Effect

Defaults

/NOHEADER
(/-HD)

No task
header

/HEADER

/SYMBOL TABLE
(Specify third
output file)

Create a
.STB file

No .STB
file

STACK=0

No space
for stack
in .TSK file

STACK=256 (10)
words

PAR=
par [: base: len]

Specify
partition
name (set
base virtual
address required if
absolute; must
also specify
length, 0 or
maximum)

PAR=GEN
If base and
length not
specified,
information
taken from
partition on
the system

244

Notes,

Needed for
task-building
referencing task

Partition name
must be same as
name of the .TSK
and .STB files
For PI regions,
if specifying
base and len, use
base=0, length=0
or max

STATIC REGIONS

Example 7-1 has the source code for a resident common COMWP and a
referencing task COMGP. The following procedure is used to create
the resident common:
1.

Code the shared region.
See COMWP.FTN in Example 7-1.
to the example:

The following note is keyed

ctcreate the FORTRAN named COMMON, MYDATA, and put
into the array I.
2.

data

Compile the shared region.
)FORTRAN/LIST COMWP

If necessary, create the common type partition.
We will make a partition COMWP, eight blocks = 1000(8)
bytes long.
If the partition TSTPAR already exists on
your system, you may be able to eliminate it and then set
up your partition.
Be sure to check with your system
manager before doing this and also be sure to put TSTPAR
back when you are finished.
Check current partitions on the system
>SHOW PARTITIONS
Record base address and length of TSTPAR and the type
of partition. Convert the values to blocks by
dropping the last 2 zeroes.
(For example, base
address 123400(8)=1234 blocks,
length=20000(8) bytes = 200(8) blocks)
Eliminate the partition TSTPAR
)SET NOPARTITION:TSTPAR
Create the partition COMWP
)SET PARTITION:COMWP/BASE:1234/SIZE:10/COMMON
Check to see if this worked correctly
)SHOW PARTITIONS
Later, to eliminate the partition and to
use these commands:

replace

)SET NOPARTITION:COMWP
)SET PARTITION:TSTPAR/BASE:1234/SIZE:200/TASK

245

TSTPAR,

STATIC REGIONS

Task-build the

sh~red

region.

To build position independent:
)LINK/OPTIONS/MAP/SHAREABLE:COMMON/NOHEADER -)/SYMBOL TABLE/CODE:PIC COMWP,LB:[l,l]FOROTS/LIB
Option? STACK=0
.
Option? PAR=COMWP
Option? <RET)
The /OPTIONS switch allows you to enter options.
/MAP
indicates that you want a map file.
/SHAREABLE:COMMON
indicates that Psect names are to be placed in the
.STB
file
(required
to
reference with FORTRAN COMMON).
/NOHEADER indicates that no task header be included in the
task
image
since this is not an executable task.
/SYMBOL TABLE indicates that a
.STB file be created.
(COMWP.STB).
/CODE:PIC indicates a position independent
region.
STACK=0 indicates no stack space is needed since
this
is not an executable task.
PAR=COMWP indicates the
partition is COMWP. The Task Builder gets the length (for
a maximum check) from the partition on the system.
5.

Install the region.
)INSTALL COMWP
Installs the region and also loads it into memory.
Note that this is different from an executable task,
which usually isn't loaded until it is requested.

246

STATIC REGIONS

BLOCK DATA COMWF'
C

C File COMWP.FTN
C

C Pro~ram to create and initialize a resident common
C

C Task-build instructions: Must include /SHAREABLE:COMMON
C and /NOHEADER switches; STACK=O and PAR=COMWP options.
C Must create .STB file. Maw be /CODE:PIC or absolute
C (the default). OTS librarw NOT reGuired.
C

rCOMMON /MYDATA/ I (256)
O ~ATA
I /128*5,128*10/
END

PROGRAM COMGP
C

C File COMGF'.FTN
C
C Task to read data from a static re~ion and print it
C out at TI:. It uses a COMMON to reference the data.
C
C Task-build instructions:
C
LINK/MAP/OPTION COMGP,LB:r1,1JFOROTS/LIBRARY
C
Option? RESCOM=COMWF'/RO
C

C
C

Option? <RET>

! Common to reference
!
shared re~ion
C Loop throu~h to displaw re~ion, 8 numbers on a line
DO 50 J = 1,249,8
WRITE (5,10) (L(K),K::::J,J+7) ! Write vall.Jes
FORMAT (' ',12,718)
10
CONTINUE
50
CALL EXIT
END

Example 7-1

COMMON /MYDATA/ L(256)

Resident Common Referenced with FORTRAN COMMON
(Sheet 1 of 2)

247

STATIC

REGI~ONS

3
3

3
6
()

3
6
6

R'Jn Sest:;:i,on

>J:NS COMWP
>RUN COMGP
~~

:'5

Example 7-1

Resident Common Referenced with FORTRAN COMMON
(Sheet 2 of 2)

248

STATIC REGIONS

Creating a Referencing Task
1.

Code the task, using the FORTRAN COMMON used
the region.

Compile the task.

Task-build the task.
•

Specify shared regions by using one of
options:

creating

the

following

RESCOM=common name - for a user resident common.
The .STB and .TSK files may be on any device and
in any UFD, using normal defaults.
Append /RO or /RW for read-only or read-write
access.
COMMON=common name - for a system resident common.
The .STB and .TSK files must be in LB:[l,l].
Append :RO or :RW for read-only or read/write
access.
(Note that a colon (:) is used for COMMON and
a slash (/) is used for RESCOM when appending the
RO or RW switches.)
4.

After installing the shared region, install and/or run the
task.

If the shared region is to be a system shared region, the .STB
file and the .TSK file should be placed in LB:[l,l]. Otherwise,
they can reside on any device under any UFO, as long as both files
are in the same UFO on the same device.
Read-only or read/write access affects the way the access bits in
the page descriptor registers (PORs) in the APRs are set up. A
memory protect violation occurs if a task attempts to write to a
region when it has read-only access.

249

STATIC REGIONS

COMGP.FTN in Example 7-1 contains the source code for a task' to
reference the shared region COMWP.
Use the following procedure to
cre~te the task:
1.

Code the task.
See COMGP.FTN in Example 7-1.
to the example:

The following note is keyed

same FORTRAN named COMMON, MY DATA , is used here as
o The
in COMWP.FTN to set up referencing.
2.

Compile the task

Task-build the task
>LINK/OPTION/MAP COMGP
Option? RESCOM=COMWP/RO
Option? <RET>
Link task to resident common COMWP.
COMWP.TSK and
CONWP.STB are in the current UFD on SY:.
Set up
read-only access.
Use the highest available APR, APR
7, if the region was built position independent.

After installing the shared region, install and/or run the
task.
To do a temporary install, run, remove:
>RUN COMGP
To install and then run:
>INSTALL COMGP
>RUN COMGP

250

STATIC REGIONS

Accessing a Region for Read-Only or Read/Write
Whether read-only or read/write access
is required
is
straightforward.
If a task moves data into the region or
a value in the region, read-write access is required.
If
moves data out of the region or just reads values in the
read-only access is required.

usually
changes
a
task
region,

However, when QIOs are issued and the buffer
is in the shared
region,
the situation is more involved.
Obviously, to do a read
(e.g., from a terminal)
into a buffer
in the shared region
requires write access.
A write
(e.g.,
to a terminal) from a
buffer in the region should only require read access.
However,
because the
Executive is designed
for very fast,
real-time
applications, it does not check the function code for a
QIO
directive to see whether
it is a read or a write.
Instead it
assumes the worst case - that all QIOs involving a buffer
in a
shareo
region are reads (from a peripheral device) into a buffer
in the region, and that therefore all QIOs require
read/write
access.
This condition causes an
I/O error
(IO.SPR)
for
illegal user
buffer.
This condition does not cause errors in the example
because FORTRAN WRITEs create the output string in a buffer within
the
referencing
task area and the QIOs do the writes from the
referencing task area.
However, if you issue QIOs directly,
the
above problem can exist.
One solution is to get read/write access to the shared
region.
Another solution is to move the data from the shared region to a
buffer in the referencing task area and then use that buffer for
the QIOs.
A third solution is to build the task as a privileged
task.
Privileged tasks,
similar to privileged terminals,
are
granted certain extra access to the system which nonprivileged
tasks don't have.
Some privileged tasks
just gain these extra
access rights, others map to the Executive as well. Normally, the
Task Builder builds a
task as a nonprivilege~
task.
For a
discussion of privileged tasks and how to task-build them, see
Appendix D.

251

STATIC REGIONS

CREATING AND REFERENCING A SHARED LIBRARY
Example 7-2 contains a shared library, LIB.MAC, and a
referencing
task USELIB.FTN.
The program LIB.MAC and the associated comments
ar,e included to illustrate how a MACRO program can be called from
a FORTRAN program.
Some knowledge of MACRO-II is required to have
a full understanding of the example.
The FORTRAN user need only
know the order of the arguments in the CALL in order to use these
subroutines.
The shared library contains four
simple arithmetic routines to
add,
subtract, multiply,
and divide two numbers.
They are all
written to be reentrant and, in addition, they are written so that
they can be called from a FORTRAN program with a standard FORTRAN
subroutine call.
INTEGER OPI,OP2,ANS
CALL AADD(OPI,OP2,ANS)
The argument list is set up as follows:

*******************************
R5
*
COUNT=3
*
*
*******************************

address of OPI

address of OP2

address of ANS

word, word

longword

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

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

Note that subroutines written in FORTRAN cannot be included
in a
resident library because the code generated by FORTRAN is not
reentrant.
For additional
information on the FORTRAN/MACRO-II
interface, see Appendix C.

252

STATIC REGIONS

Each subroutine saves and restores all of the registers, using the
system library routine $SAVAL.
The referencing task, USELIB,
calls each of the subroutines once, using the operands 8(10)
and
2(10), and displays just the answers for the four operations. The
following notes are keyed to Example 7-2.

Each subroutine entry
symbol.

point

defined

with

global

Each subroutine is in a Psect of the same name as the
o subroutine.
In fact,
the Psects are optional since the
library is built /SHAREABLE:LIBRARY. The specified
names are not placed in the .STB file.

Psect

AADD and SUBS, move the first operand to R0,
perform
e For
the operation in R0,
then move the answer to the third
operand for return to the caller.
MULL, use R1 instead of R0, so that the product is
o For
limited to just R1 (16 bits).
If R0 were used instead, a
32-bit product is returned
high-order 16 bits in R0).

(low-order

bits

R1,

For DIVV, a 32-bit dividend is assumed in Rn and Rn+l,
so
e here
it is R2 and R3 (low-order 16 bits in R3, high-order
16 bits in R2).
Therefore, the 16-bit operand
in R3 and the high-order word is cleared.
quotient, returned in R2, is then moved into
operand for return to the caller.

is placed
The 16-bit
the third

instructions needed to tie the task to the
o Task-build
library.

253

STATIC REGIONS

Task-Building the Shared Library and the Referencing Task
The instructions for task-building the library and the referencing
task are
included
in Example 7-2; however one point should be
emphasized.
When
Task
Building
the
library,
you
must
use
the
/SHAREABLE:LIBRARY
switch to avoid task-builder errors when
building the referencing task. Whether the library is to be a
system resident library or a user resident library is determined
strictly by where the .STB and the
.TSK file for
the library
reside.
If they are in LB:[l,l], the library is a system resident
library.
If the .STB and .TSK files exist in other than LB:[l,l],
the library is a user resident library.
When task building a referencing task,
the option
(not switch)
RESLIB=library name or LIBR=library name must be used.
If the
option LIBR is used, the search for the library will be done only
in UFD LB:[l,l].
If the option RESLIB is used, the search for the
library will be done on the default device and UFD, or on the
device and UFD specified with the library name;
for example:
)LINK/OPTIONS/MAP COMPG
Option? RESLIB=DB2:[200,S]LIBAl/RO
The above comments also apply to the creation and referencing of a
The only difference is that when the common is
common region.
task-built, the /SHAREABLE:COMMON switch is gener,ally used and
when the common is referenced, the option COMMON=name is used for
a system resident common, and RESCOM=name is used for a user
resident library.

254

STATIC REGIONS

.TITLE
.IDENT
.ENABL

LIB
lOll
L.C

Enable lower case

y+
File LIB.MAC
This file contains the FORTRAN callable subroutines
y AADD, SUBB, MUL.L, and DIVV, which perform the
y appropriate inte~er operation.
y

;

Callin~

convention: CALL sub (opl,op2,ans)

Task-build instructions: Must include ISHAREA8LE:LIBRARY
y and INOHEADER switches; STACK=O and PAR=LIB options.

; Must create .ST8 file. Ma~ be ICODE:PIC or absolute
y (default). Usin~ ISHAREA8LE:LIBRARY avoids Psect
conflicts.

;--0

.PSECT AADD,RO,I,GBL,REL,CON
SSAVAL
Save all resisters
o AADn:: CALL
@2(RS),RO
Move 1st operand
rov
@4(R5),RO
Add 2nd operand
ADD
e MOV RO,@6(RS)
store result

0 BUBB: :

RETURN

Restore

.PSECT
CALL

SUBB,RO,I,GBL,REl,CON
SSAVAL
Save all resisters
@2(RS),RO
Move ls~ operand
@4(RS),RO
Subtract 2nd operand
RO,@6(R5)
Store result
Restore re~s and return

[MOV
SUB
MOV
RETURN

MULL::

.PSECT
CALL

rOV
MUL

MOV
RETURN

0
0 rHVV: :
0

.PSECT
CALL

rOV
CLR
DIV
MOV
RETURN
.END

re~s

and return

MULL,RO,I,GBL,REL,CON
SSAVAL
Save all re~isters
@2(RS),R1
Move 1st operand
MIJJ.t:i.pl~:I (answer 'in
,just Rl)
R1,@6(R5)
sto re resu 1 t,
Restore re~s and return
DIVV,RO,I,GBL,REL,CON
SSAVAL
Save all re~isters
@2(RS),R3
Move 1st operand
R2
Clear hiSh order 16 bits
@4(R5),R2
Divide

Example 7-2

Restore reSs and return

Shared Library (Sheet 1 of 2)

255

STATIC REGIONS

PROGRAM USELIB

C File USELIB.FTN
C

C FORTRAN task to use resident librarw LIB
C
C
C
C

Task-build instructions:

C
C
C
C

c
C

C
C

>LINK/CODE:FPP/MAP/OPTION USELIB,LB:C1,lJFOR-)OTS/LIBRARY
RESLIB~LIB/RO
[ Option?
Op·tion? <RET>
INTEGER ANS,OP1,OP2
DATA OP1,OP2 18,21
CALL AADD(OP1,OP2,ANS)
TYPE 100, ANS

Add operands
Print results

CALL SUBB(OP1,OP2,ANS)
TYPE 100, ANS

Subtract operands
Print reslJl ts

CALL MULL(OP1,OP2,ANS)
TYPE 100, ANS

Multipl~ of,erands
Print results

CALL DIVV(OP1,OP2,ANS)
TYPE 100, ANS

Divide operands
Print reslJlts

CALL EXIT

100

'~un

FORMAT
END

(

, THE ANSWER .- ',I2,'.')

Sess i on

>INS l.IB
>RUN USELIB
THE ANSWER IS 10.
THE ANSWER IS 6.
'THE ANSWE'~ IS 16.
THE ANSWER IS 4.

Figure 7-2

Shared Library (Sheet 2 of 2)

256

STATIC REGIONS

DEVICE COMMONS
A device common is a special type of common that occupies physical
addresses on the I/O page.
The I/O page does not contain physical
memory, but peripheral device
registers
instead.
Therefore,
a
device common does not contain data the way a regular resident
common does.
It is really just a way of setting up addressing
to
allow a
task
to manipulate the device registers directly.
This
might be useful in checking out
the proper commands needed
to
control a device or to check what control status registers (CSRs)
are in use on your system.
Obviously, extreme care must be used
if you manipulate a device which is also referenced by any system
routines (e.g., a system device driver).
privileged tasks which map to the Executive can also automatically
map the I/O page.
However, privileged tasks must be written very
carefully to avoid causing additional problems for
the
running
system.
Device Commons allow nonprivileged tasks to manipulate
device registers.
by its
While a device common region can be created
in FORTRAN,
For an example see
nature, referencing must be done via MACRO-II.
the RSX-IIM/M PLUS Task Builder Manual.
Appendix F contains information about more advanced shared
topics.
It includes a discussion of the following topics:
•

Overlaid shared regions

•

Referencing several shared regions, from
task

•

Handling interlibrary calls

•

Cluster libraries

one

region

referencing

Most of the techniques discussed
are more appropriate for
the
MACRO-II programmer who is running into virtual address limitation
problems.
Cluster libraries are designed to save virtual
address
space
in tasks
which
use DIGITAL layered
products,
such as
FORTRAN, FMS (Forms Management Services), and
FCS
(File Control
Services).
If you write
FORTRAN programs which
use
these
products, you may find it useful to just read the last few pages,
which
cover
the
procedure for
task-building
a
task which
references two or more DIGITAL supplied resident
libraries as a
set of cluster libraries.

257

STATIC REGIONS

Now do the Tests/Exercises for
this module in the Tests and
Exercises Book.
They are all lab problems. Check your answers
against the solutions provided, either the on-line file (under UFO
[202,2]) or the hard copy in the Tests and Exercises Book.
If you feel that you have mastered the material, have your course
administrator record your progress on your progress plotter. You
will then be ready to begin a new module.
If you feel that you have not yet mastered the material, return to
the module for further study.

258

DYNAMIC REGIONS

INTRODUCTION
The last module discussed how to use the Task Builder to create
and access static regions.
It is also possible to create and
access regions while a task is executing. Such regions are called
dynamic regions.
The memory management directives allow a task to
create and access dynamic regions and access existing static
regions.
In addition, they offer a facility for creating private
regions and for allowing other tasks to access these regions.

OBJECTIVES
1.

To write tasks which create a dynamic
dynamic and/or static regions

region

and

access

To write tasks which dynamically control their mapping

To write tasks which create a private dynamic region
allow one or more other tasks to access the region.

and

RESOURCE
•

RSX-IIM/M-PLUS Executive Reference Manual, Chapter 3
specific directives in Chapter 5

261

plus

DYNAMIC REGIONS

SYSTEM FACILITIES
Sometimes a task's needs for memory and for shared regions aren't
known until
run time, or the needs may change at run time.
Examples are:
1.

A task, e.g.
an editor, needs a temporary work buffer for
only part of the time the task is active.

A task needs a shared region or work buffer, but its size
depends upon the needs of the user running the task (e.g.,
the size of an input file).

A task creates a shared region and wants to control access
to it by other tasks.

A task wants to create a shared region in a system
controlled partition (e.g., GEN) instead of in a dedicated
common type partition. Then when the shared region isn't
needed,
the space automatically is available for other
system needs (tasks, etc.).

A task needs to map to two different shared regions at
different times, but has only one 4K word virtual address
window available.

Special directives,
called memory management
available on mapped systems to allow tasks
following functions:

directives,
to perform

are
the

•

Create regions in system controlled partitions

•

Attach/detach from a region

•

Create/eliminate virtual address windows

•

Map/unmap a virtual address window to an attached region

•

Obtain information about its mapping from the system

The memory management directives are a SYSGEN option.
Therefore,
if users on a system plan to use them, they must be included in
the Executive at SYSGEN time. Check with your system manager to
find out if they have been included on your system.

263

DYNAMIC REGIONS

Table 8-1 lists the memory management
available on an RSX-IIM system.
Table 8-1

directives

Memory Management Directives

Function

FORTRAN Calls

Attach region

ATRG

Create address window

CRAW

Create region

CRRG

Detach region

DTRG

Eliminate address window

ELAW

Get mapping context

GMCX

Map address window

MAP

Receive-by-reference

RREF

Send-by-reference

SREF

Unmap address window

UNMAP

264

which

are

DYNAMIC REGIONS

REQUIRED DATA STRUCTURES
Each memory management directive requires that you set up one of
two data structures within your task; namely a region definition
block (RDB) or a window definition block (WDB). The RDB and the
WDB are the
interface between the user task and the Executive.
Their contents change dynamically as regions are created and
accessed.
In general, once the WDB and/or the RDB are set up, the
actual memory management directive FORTRAN calls are
quite
straightforward. Their format is either:
CALL XXXX(wdb,idsw)
or
CALL XXX(rdb,idsw)
where wdb is the name of an 8 word integer array
for the Window Descriptor Block
rdb is the name of an 8 word integer array
for the Region Descriptor Block
Examples:
INTEGER WDB(8),RDB(8)
CALL CRAW(WDB,IDSW)
CALL CRRG(RDB,IDSW)

Region Definition Block (ROB)
An RDB contains information needed to create a region
attach to a region in a system controlled partition.
used by the following directives:
•

Attach Region (ATRG)

•

Create Region (CRRG)

•

Detach Region

(DTRG)

265

and/or to
The RDB is

DYNAMIC REGIONS

Figure 8-1 shows the arguments for the various RDB elements.
meaning of the elements is as follows:

The

Region ID - a unique number assigned to a region when your
task attaches to a region.
The number associates the task
with the region.
It is ~eturned by the Executive after
your task attaches to a region.
Size of Region - the size of a region to be created,
in
32-word blocks. Also used to return a size when attaching
an existing region.
Name of Region
up to six characters in Radix-50.
Assigned when a region is created and used when attaching
to a region.
Region's Main Partition Name - up to six characters in
Radix-50.
The name of the system controlled partition.
Region Status Word
used by the user task to send
information to the Executive when creating or attaching to
a region. Also used by the Executive to return status to
the task after a memory management directive is executed.
Table 8-1 lists the various bits and their meanings.
Region Protection Word - Analogous to the file protection
word, controlling access to regions. As shown below, it
is set up with the same format
(RWED for Read, Write,
Extend, Delete)
within each category:
System, Owner,
Group, and World:
World
DEWR
1110

Group
DEWR
1110

Owner
DEWR
0000

System
DEWR
0000

= 167000(8)

A 1 means access is denied, a 0.means access is permitted.
The example means world and group have read access; owner
and system have all access.

266

DYNAMIC REGIONS

ARRAY
ELEMENT

BLOCK FORMAT

ARGUMENTS

irdb (1)

irdb (2)

REGION 10

siz

SIZE OF REGION (32W BLOCKS)

nam

NAME OF REGION (RAD50)

par

REGION'S MAIN PARTITION NAME (RAD50)-

irdb (7)

sts

REGION STATUS WORD

irdb (8)

pro

REGION PROTECTION WORD

irdb (3)

irdb (4)

irdb (5)
irdb (6)

TK-9385

Figure 8-1

The Region Definition Block

267

DYNAMIC REGIONS

Table 8-2

Region Status Word

Symbol

Octal
Value

Set By

Definition

RS.CRR

100000

System

Region successfully created

RS.UNM

40000

System

At least one window unmapped .on a
detach

RS.MDL

200

User

Mark region for deletion on last
detach

RS.NDL

100

User

Created region not deleted on last
detach

RS.ATT

User

Attach to created region

RS.NEX

User

Created region not extendable

RS.DEL

User

Delete access

RS.EXT

User

Extend access desired on attach

RS.WRT

User

Write access desired on attach

RS.RED

User

Read access desired on

de~ired

on attach

atta~h

Just as in other modules, the symbols shown are those used in the
documentation and by MACRO programmers.
The symbols can be
converted to FORTRAN acceptable variable names by dropping the
period in the symbol. Values may be assigned by using the DATA
statement.

268

DYNAMIC REGIONS

Creating an ROB in FORTRAN
Example:
Create an RDB for a region with the following specifications:
Size in 32(10) word blocks = 2

= MYREG
'Partition name = GEN
Region name

Region to be attached on create
Region to be marked for delete on last detach
write access desired on attach
Owner to have all privileges and group to have read privileges
DIMENSION IRDB(8)

DATA IRDB/0,2,3RMYR,3REG ,3RGEN,3R

,"242,"177017/

In the above, the region status word (word 7 = 242(8», is the sum
of 200(8) + 40(8) +2(8).
See table 8-2 for meanings.
The region protection word is
follows:
World
DEWR
1111

Group
DEWR
1110

177017(8),
Owner
DEWR
0000

269

which

System
DEWR
1111

breaks

down

DYNAMIC REGIONS

Example:
Create an RDB for a region with the following specifications:
Size in 32(10) word blocks = 1000(8)
Region name = XXXX
Partition name =

sam~

as task is installed in

Region status = do not delete, desired access to be filled
before attaching

World to have no privileges, all others to have all privileges
DIMENSION IRDB(8)

DATA IRDB/0,"1000,3RXXX,3RX

,0,0,"100,"170000/

Note that any value the Region Descriptor Block could be· changed
dynamically at run time by using input values to change various
parts of the RDB.

Window Definition Block (WDB)
A WDB contains information needed to create a virtual address
region and to map a virtual address window to an attached region.
The WDB is required for the following directives:
•

Create Address Window (CRAW)

•

Eliminate Address Window (ELAW)

•

Map Address Window (MAP)

•

Unmap Address Window (UNMAP)

•

Send-by-Reference (SREF)

•

Receive-by-Reference (RREF)

270

DYNAMIC REGIONS

Figure 8-2 shows the layout of the WDB.
The meaning of the elements is as follows:
Window ID - A number which identifies the window block, in
the task header which describes the window.
Window 0 is
used fO,r the task window. Windows 1 through 7 are used
for additional windows set up by the Task Builder for
overlays and static regions and for windows created
dynamically.
The window ID is returned by the Executive
after a Create Address Window directive.
The Task Builder
option WINDWS=n must be used to specify the number of
additional window blocks needed for dynamic windows.
Base APR - The base APR to be used in mapping the
which sets the base virtual address.

window,

Base Virtual Address -- The base virtual address in octal;
returned by the Executive after a Create Address Window
directive.
Region ID - The region ID, used to identify the region
when mapping a virtual address window to a
region;
returned by the Executive in the RDB after an Attach
Region directive.
You must move the value returned from
the RDB to the WDB before mapping to the region.
Offset in Region (32 word blocks) - The offset within the
region at which mapping is to begin. Allows a task to map
to different portions of a region.
Length to Map (32-word block)
The length within the
region to be mapped.
Defaults to the shorter of the space
remaining in the region and the size of the window.
Window Status Word
Used by the user task to -send
information' to the
Executive when creating and mapping
windows. Also used by the Executive to return status to
the user task after a directive is executed.
Table 8-3
lists the various bits and their meanings.
Send/receive buffer address - The address of an eight-word
buffer for sending or recelvlng data as part of the
Send-by-Reference and Receive-by-Reference directives.

271

DYNAMIC REGIONS

ARRAY
ELEMENT

BLOCK FORMAT

ARGUMENTS

BASE APR

iwdb (1)

WINDOW 10

apr
VIRTUAL BASE ADDRESS (BYTES)

iwdb (2)

iwdb (3)

siz

WINDOW SIZE (32W BLOCKS)

iwdb (4)

rid

REGION 10

iwdb (5)

off

OFFSET IN REGION (32W BLOCKS)

iwdb (6)

len

LENGTH TO MAP (32W BLOCKS)

iwdb (7)

sts

WINDOW STATUS WORD

iwdb (8)

srb

SEND/RECEIVE BUFFER ADDRESS

TK-9386

Figure 8-2

The Window Definition Block

272

DYNAMIC REGIONS

Creating a WOB in FORTRAN
Example:
Create a WDS to describe a window with the following:
APR = 7
Size in 32(10) word blocks = 100(10)
Region to be mapped in a CALL CRAW or CALL RREF directive
Map with read access
Map 100(10) blocks
DIMENSION IWDB(8)
DATA IWDB/"3400,0,100,0,0,100,"201,0/
Note that the APR number (7 in the example) must be placed in the
high byte of the first word in the WDB. This can be done by
putting 3400(8) into IWDB(1).
3400(8)
is 00000111 OOOOOOOO(2)
which puts a 7 in the high byte for the base APR. This can also
be done by setting IDWB(1)=7*256.
Word 7 (201(8»
is the window status word.
definitions of the bits in this word.

See Table 8-3 for

Create a WDB to describe a window with the following:
APR = 5
Size in 32(10) word blocks = 200(8)
Map starting at offset of 5 blocks in region and map
10(10) blocks
Send with delete! and write access
DIMENSION IWDB(8)

DATA IWDB/"2400,0,200,0,5,10,"412,0/

273

the

DYNAMIC REGIONS

Table 8-3

Window Status Word

Symbol

Octal
Value

Set By

Definition

WS.CRW

100000

System

Address window successfully
created

WS.UNM

40000

System

At least one window unmapped by
a CRAW, MAP or UMAP directive

WS.ELW

20000

System

At least one window eliminated
in a CRAW or ELAW directive

WS.RRF

10000

System

Reference successfully received

WS.64B

400

User

Defines permitted alignment for
offset start within the region
o for 256-word alignment (8 blocks)
1 for 32-word alignment (1 block)

WS.MAP

200

User

Window to be mapped in a CRAW or
RREF directive

WS.RCX

100

User

Exit if no references

WS.DEL

User

Send with delete access

WS.EXT

User

Send with extend access

WS.WRT

User

Send or map with write access

WS.RED

User

Send with read access (map is
with read access by default)

274

DYNAMIC REGIONS

CREATING AND ACCESSING A REGION
Use the following procedure to create and access a region:
1.

Create the region (Create Region directive)

Attach to the region (Attach Region directive)

Move the region ID from the RDB to the WDB

Create a virtual address
directive)

Address

Window

Map the virtual address window to the region (Map
Window directive)

Address

Use the region

Detach from the region (Detach Region directive or task
exit).
It is recommended that a task always issue the
Detach Region directive rather than depend on the EXIT
processing code to issue the Detach. The reason for this
is that if a task is fixed and EXITs, then no detach is
done.
If you run the fixed task over and over, you could
run out of pool.

window

(Create

Steps I and 2 and also steps 4 and 5 can each be combined in a
single directive call.
Step 4 can be performed earlier, if
desired. To access an existing region, begin with step 2.
If you don't remember what windows and regions are and also what
attaching and mapping mean, look over the sections on Windows and
Regions in the last few pages of Module 5, the Memory Management
module.
The use of each directive in the procedure above is detailed on
the following pages. The discussion includes:
the purpose of the
directive, important input and output parameters, plus notes about
its use. For a complete discussion of each directive, see Chapter
5
of
the
RSX-IIM/M-PLUS Executive Reference Manual.
For
additional information on the memory management directives, see
Chapter 3 of the same manual.

275

DYNAMIC REGIONS

Creating a Region
When you create a region, the Executive allocates space for it in
a system controlled partition. Use the Create Region directive
(CRRG) with the following RDB input parameters:
1.

Size of region (in 32(10) word blocks)

Name of region (becomes a private region if no name)

Name of partition (defaults to partition of task)

Region Status Word - mark for
(default is mark for delete)

Region protection word - determines permissible access
region

delete

not

delete
,to

In the following discussion, the MACRO symbols are used for the
various Window Status Word bits. See Table 8-3 (Window Status
Word) for definitions and values.
The only RDB output parameter is the 'RS.CRR bit in the region
status word.
It is set if the region is successfully created, and
cleared if not. Normal Executive directive status is returned as
well
(carry set for error, clear for success; DSW contains
directive status word).
If the region already exists, success
status is returned.
Therefore, RS.CRR can be used to tell whether
the region was in fact created or whether it already existed. The
following code segment illustrates how to examine RS.CPR to see if
the the region was successfully created.
INTEGER RSCPR,RDB(8)
DATA RSCPR/"100000/
I=RDB(7) .AND."100000
Now test I.
was.

If I is 0, the region was not created;' otherwise

276

DYNAMIC REGIONS

Any task which passes the protection test can attach to a named
region.
For unnamed
(private)
regions, only tasks which are
specifically attached by the creator of the region may attach to
it.
Therefore, for a private region,
the creator completely
controls which tasks attach to it, and their access rights as
well.
By default, or if RS.MDL is set in the region status word,
the
region is deleted when the last attached task detaches from the
region. Named regions are left in existence after the last detach
if RS.NDL is set in the region status word when the region is
created. Unnamed (private) regions are always marked for delete
(deleted on last detach).
There is no explicit Delete Region
directive.
If the RS.ATT bit is set in the region status word, the Executive
also attempts to attach the task to the region.
In this case,
additional RDB input parameters are required and additional output
parameters are returned. Attaching to a region is discussed after
Example 8-1.
Example 8-1 shows how to create a named region which is left in
existence on the last detach.
The following notes are keyed to
the example.
up the RDB.
RS.NDL{100(8»
o Set
(RDB(7»
specifies that the

in the region status word
region is to be left in

existence.

Region Protection Word =

World
DEWR
1111

Group
DEWR
0000

System
DEWR
0000(2)

Owner
DEWR
0000

l70000(8)
Bit set means access denied
~

Issue directive to create region, specifying
address and the DSW as the only arguments.

Check for directive error.

C»

Display message and exit.

277

the

RDB

DYNAMIC REGIONS

PROGRAM CRERG

C File CRERG.FTN
C

C CRERG creates a named
C re~ion in existence.
C
C

re~ion

and exits,

RDB = Re~ion Definition Block for

C followinS properties:

Size
Name
Pa'rti tion
Protection

C
C
C
C

re~ion

leayin~

the

with the

= 100 (32. word blocks)
= MYREG
= GEN
= WO:None,SY:RWED

OW:RWED,GR:RWED
Do not mark for delete on last detach

C
C
C

INTEGER RDB(S)
C Initialize the RDB
_. IIATA RDS/O, 8100, 3RMYR, 3REG , 3RGEN, 3R
1 000100,8170000/
C Create re~ion
CALL CRRG (RDB 51 IDS)
C Branch on error
IF(IDS.LT.O)GOTO 800
C Write success messa~e
WRITE (5,15)
15
FORMAT (~ CRERG SUCCESSFULLY CREATED MYREG ~ )
C Go to common exit
GOTO 1000
C Write create error messa~e
800
WRITE(5,850)IDS
850
FORMAT(~ ERROR IN CREATING REGION, DSW = ~,I4)
1000
CALL EXIT
END
8

1:::'.Jn Sestsion
>RUN CRERG
CRERG SUCCESSFULLY CREATED MYREG

:::.

Example 8-1

Creating a Region

278

DYNAMIC REGIONS

Attaching to a Region
When you attach your task to a region, the Executive creates a
logical connection between the two. The region can be either a
dynamic region or a static region.
Use the Attach Region
directive (ATRG) with the following RDB input parameters:
Region name
Region Status Word

(indicating R,W,E,D access)

The following RDB output parameters are returned:
Region ID
Region size
The region ID is needed later in order to map a virtual address
window to the region.
The region size is of interest when
attaching to an already existing region whose size may not be
known.
Attaching can also be done as part of the Create Region directive
(CRRG),
if the RS.ATT bit in the region status word is set when
the Create Region directive is issued.
In fact,
for
an unnamed
region, attaching must be done as part of the Create Region
directive, since there is no region name to be used in a separate
Attach Region directive.
A task can detach from a region by using an explicit Detach Region
directive
(DTRG) or by exiting (the Executive detaches the task).
If a task is changing a region from "do not delete" to "mark for
delete", an explicit detach is required with RS.MDL set in the
region status word.
If a task exits without issuing an explicit
detach, and the task is not fixed, the Executive detaches the task
but does not mark the region for delete.
Once a region is marked
for delete,
it is deleted when the last attached task detaches
from it. Once it is marked for delete it cannot be changed to "do
not delete".
If a fixed task exits without
issued by the Executive.

issuing

279

detach,

detach

DYNAMIC REGIONS

Creating a Virtual Address Window
When you create a virtual address window for a task, the Executive
initializes a window block in the task header.
It also checks to
ensure that this is the only window that uses the specified range
of virtual addresses,
unmapping and eliminating any window that
overlaps that range.
Use the Create Address Window directive
(CRAW) with the following WDB input parameters:
Base APR number
Window size (in 32 (10) word blocks)
The following WDB output parameters are returned:
Window ID assigned by the system (1-7)
Base virtual address
The space for the additional window blocks in the task header must
be reserved at task-build time using the WNDWS=n option. N is the
number of additional windows needed for windows created at run
time.
If extra space is not allocated, an address window
allocation overflow error (IE.WaV= -85.) results when you attempt
to create a virtual address window.
The window is also mapped to a region if bit WS.MAP is set in the
window status word when the Create Address Window directive is
issued.
In that case, additional
i~put
parameters are needed.
See the following section on Mapping to a region.
The Eliminate Address Window
(ELAW)
directive can be used to
explicitly eliminate a virtual address window.
In general, it is
not used because creating a new window automatically eliminates
any overlapping window.

280

DYNAMIC REGIONS

Mapping to a Region
When you map a virtual address window to a region,
the Executive
creates a logical connection between the virtual address window
and the region. Any attached region can be mapped.
In the
process,
the memory management registers are loaded so that
references to virtual addresses in the window access the region.
This assumes,
of course, that the task keeps control of the cpu.
The APRs are reloaded every time a new ta~k takes control of the
CPU.
Use the Map Address Window directive (MAP) to map a
region, with the following WDB input parameters:
Region ID - Returned to RDB by Attach (move
WDB) •

window
from

RDB

Offset into Region - in 32-word blocks,
used to start
mapping at an offset from the start of the region.
This
must be a multiple of 8(10) unless WS.64B is set in the
window status word.
If WS.64B is set, any whole number
may be specified.
Length to Map - If specified, must be less than or equal
to shorter of length of window and length remaining in
region.
If defaulted, is set to the shorter of the two.
Window status word - actual access desired (read-only, or
read/write).
Read access is always requested by default
so a request for write access actually requests read/write
access, and a request for no access actually requests read
access.
The only WDB output parameter generally used is the length
actually mapped.
If the window is already mapped, it is first
unmapped by the Executive. You can also use the Unmap Address
Window directive to explicitly unmap a window. Mapping can also
be done as part of the Create Address Window directive (CRAW).
The access desired is used here in addition to that declared when
attaching because several windows
in the task may map the same
region.
Some of the windows may need read-only access, others may
need read/write access.
In that case, you must attach with
read/write access, and then you may map each window with either
read-only access or read/write access.

281

DYNAMIC REGIONS

Example 8-2 shows how to create a region and place data
into
it,
leaving it in existence on exit.
Example 8-3 shows how to
attach to that region, read and display the data, and finally
detach and mark it for delete.
One run session covers both
examples.
The following notes are keyed to Example 8-2.
with the WNDWS=l option causes the Task
o Task-building
Builder to allocate space in the task header for one
additional window block.
You must also use the VSECT
option to create a virtual section starting at 160000(8)
for an extent of 20000(8). APR 7 must be used to map the
section
because
the section's beginning address
is
160000(8). The name of the virtual section is DATA.
This
ties the FORTRAN named COMMON DATA to the virtual section.
for region. Note that RDB(7), the region status word,
o RDB
is 152(8). This is the combination of the following:
RS.NDL
RS.ATT
RS.DEL
RS.WRT

= 100(8)
= 40(8)
= 10(8)
2(8)
=
------

152(8)
See Table 8-1 for the above definitions.
WDB for virtual address window.
The third argument is for
the region ID, which will be filled in at run time after
the task attaches to the region.
In the window status
word, WS.MAP (200(8»
means that the Create Address Window
directive will both create the window and map it to the
region.
WS.RED
(1(8»
is automatic, even though not
specified. WS.WRT (2(8»
indicates to map with write
access.
The sum of the two needed octal codes is 202(8).

o Create region and attach.
ct

Move region ID, returned
WDB(4) for mapping.

Create a virtual address window and map it to the
region.
The virtual address window begins with APR 7, so the base
address in the window is 160000(8), corresponding to the
base address in the region.

282

RDB(l)

after

attach,

into

DYNAMIC REGIONS

a byte count, 400(10), in the first word
in the
o Place
region.
This
just one way to communicate this
1S

information to other tasks which access the. reg ion.
The
length of the region is returned when a task attaches to
the region. You could use this as an alternate way to
pass the information about the amount of data.
Move 100(10) words of ASCII "AB" and 100(10)
words of
ASCII "12"
into the region.
This gives us 200(10) words
or 400(10) bytes of data.
Display a successful creation and
at the terminal.

initialization

Detach from the reg ion and then exi t, leaving
in existence.

283

the

message
reg ion

DYNAMIC REGIONS

P/:;:OG/:;:AM C/:;:EURG
c
C File CREURG.FTN
C'

C CREURG creates a named resion (attached on creation),
C'

creates a virtual address window (mapped on creation),

C' places ASCII data in the resion, detaches from the
("

reSion and exits, leavinS the resion in existence.

C It places a count word in the first word of the
C resion, tellins how man~ b~tes of data follow.
C
C Task-build instructions:
C
>LINK/MAP/OPTIONS/CODE:FPP CREURG,LB:[l,lJFOROTSC
("
_. > IL I BRARY
Option? VSECT=DATA:160000:20000
C
("

WNDWS::::1
i on? <RET>

(h-:,tion'~
())~t

C
C

C RDB ::: ReSion Definition Block for resion with the
(" followinS properties:
- 100(S) (32. word blocks)
r'
Size
N,:Jme
.- MYREG
C
..
(.,
Parti ticm
.- GEN
P rCJtect i on
C
- WO:None,SY:RWED
OW:RWED,GR:RWED
C
Do not mark for delete on last detach
C
Attach with write and delete access
C

C WDS ::: Window Definition Block for window with the
C fC)l.IOW~~~!~ properties:
__ 7

C
C
C
C
C
C

Size
- 1000ctal (32. word blocks)
Offs.et in region _. 0 (32. wc)rd blc)cks)
Length in reSion - 1000ctal (32. word blocks)
Map on create with write access

INTEGER RDB(S),WDB(S)
COMMON /DATAI IDATA(201)
C Initialize the RDB
'
DATA RDB/O,"100,3RMYR,3REG ,3RGEN,,3R
C' Initialize the WDB
A DATA WDB/"3400,0,"100,0,O,"100,"202,OI
C C~l routine to create and attach resion
CALL CR/:;:G (F<DB" IDS)
C Check for error
IF(IDS.LT.O)GOTO 800
C Create address window and map to reSion
WDB(4)=RDR( 1)
CALL CRAW (WDB" IPS)

Example 8-2 Creating a Region and Placing
Data in It (Sheet 1 of 2)
284

DYNAMIC REGIONS

C Check for error

IF(IDS.LT.O)GOTO 810
C Place data in re~ion ~ 1st word is a byte count
IDATA (1) =-400
DO 10 J=2,101
lO
IDATA(.J)='AB'
. [ DO 20 K==102,201
20
IDATA(K)='12'
C Detach from re~iori
C!) CAL.L DTr~G (RDB" IDS)
C Check for error
IF(IDS.LT.O)GOTO 820

C Write

mf:?~;Sage

TYPE *" 'CRELJRG HAS CREATED AND INITIALIZED THE
1REGION'

C Branch to common exit
GOTO 1000
C Write create error message
800
WRITE(5,805)IDS
805
FORMAT(' ERROR IN CREATING REGION, DSW - ',14)
C Go to common exit
GO TO 1000
C Write attach error message
810
WRITE(5,815)IDS
815
FORMAT(' ERROR IN CREATING WINDOW AND MAPPING,
lDSW = ',,14)
GO TO 1000
C Write detach error messa~e
820
WRITE(S,825)IDS
825
FORMAT(' ERROR IN DETACHING FROM REGION, DSW ==
1,,14)
C Common exit

1000

CAL.L EXIT

END

Rttrl

Sess:i em

>RUN CRELJI~G
CRELJRGHAS CREATED AND INITIAL.IZED THE REGION
>RUN ATTLJRG
ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB
ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB
ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB
ABABABAB12121212121212121212121212121212121212121212121212121212
1212121212121212121212121212121212121212121212121212121212121212
1212121212121212121212121212121212121212121212121212121212121212
1212121212121212

Example 8-2 Creating a Region and Placing
Data in It (Sheet 2 of 2)
285

DYNAMIC REGIONS

The following notes are keyed to Example 8-3.
task-build with the WNDWS=l option so the Task
o Again,
Builder allocates space for the window block in the task
header and with the VSECT option.
RDB for attaching to the region.
The only required
o The
information is the region name and the region status word.
The partition name and the size, although included, are
not required. RS.MDL (200(8»
(set) marks the region for
delete when we do an explicit detach.
We need delete
access to mark the region for delete (RS.DEL=10(8».
In
addition, attach with read
(RS.RED=1(8»
and
write
(RS.WRT=2(8»
access so we can map with read/write access.
The sum of the region status codes above is 213(8).
The WDB for the virtual address window. We map the entire
region (length = 100 (8) 32-word blocks) starting from the
beginning (offset = 0). WS.MAP means create the address
window and map. Map with read (WS.RED) and write (WS.WRT)
access.
The sum of the window status codes is 203(8).

C» Attach to the region.
C)

Move the region ID to the WDB and create
address window and map it to the region.

the

virtual

o count.
First word in the region contains a character or byte
Convert it to a word count.
the contents of the region,
64(10)
characters per
o Print
line.
This technique
is used to demonstrate how to
control the width of the 'output and to make the run
session fit on an 8 1/2 by 11 inch page with margins.
If
the full terminal buffer width
(typically 80(10)
or
132(10»
is acceptable, the FORMAT could be 39A2 or 6SA2.
from the region.
Explicit deta¢h required to mark
o Detach
the region for delete.

286

DYNAMIC REGIONS

PROGRAM

ATTUF~G

C File ATTURG.FTN
C

C FORTRAN pro~ram to attach the existin~ re~ion MYREG,
C create a virtual address window (mapped on creation),
C read ASCII data out of the re~ion, detach from the
C reSion, and exit. The reSion is marked for delete
C and will be deleted on last detach.
("' The first word in the reSion contains a count of how
C man~ bwtes of data are in the re~ion.
C
C Task-build with these options:
C
rVSECT=REG I ON: 160000: 20000

C.,

~NDWS=l

(.,

INTEGER RDB(S),WDB(S)
INTEGER IDATA(2048)

! Arraw for

addressin~

C
!
reSion (Full 4KW)
C This common block will alisn with the address window

COMMON IREGION/IDATA
c; RDB = Resion definition block with the followin~ properties:
Size
0 (32.-word blocks) - returned
r'.,
c
when attached
("'
.,
Name
MYREG
c
Partition
GEN
Mark for delete on last detach
c
c;
Attach with delete, read and write access
("' Initialize the RDB
,800021.3
DATA RDB 10,0,3RMYR,3REG ,3RGEN,3R
1,01
C
C WDB == Window definition block with the
C
APR
7

c:;

followin~

properties:

200 octal (32.-word blocks)
0 (32.-word blocks)
c;
0 octal (32.-word blocks) defaults to shortest
r'.,
c
available len~th
Map on create with read and write access
G
C Initialize the WDB
DATA WDB 1 8 3400,0,8200,0,0,0,'203,01

Size
Offset in reSion
Lensth of window

Example 8-3 Attaching to an Existing Region
and Reading Data From It (Sheet 1 of 2)

287

DYNAMIC REGIONS

C Attach resion

CALL ATr~G (RIIB!' IIIS)

C Check for error on attach

IF (IIIS .LT. 0) GOTO 100

r Move resion id to WDB
WIIB(4)=RIIB(1)

C Create and mar-" window

CALL CRAW (WIIB,IIIS)

[

C Check for error

IF (IIIS .LT. 0) GOTO 200

Get bwte count and convert to word count

NWORII::::('I[iATA( 1 )+1 )/2
C Print contents of resion

WrnTE
(IIIATA( I), I=2,NWORn)
0[:1.0:1.1
FORMAT (' ',32A2)
from resion and delete it
o CC Detach
CAL.L DTRG (RnB,InS)
Check for error
(5, :1.1)

IF (InS .LT. 0) GOTO 300

C And Jump to exit

GOTO 500

C ET'ror messases

100
:1.01
200
201
300
301

WRITE (5,101) InS
FORMAT (' ERROR ATTACHING TO REGION, DSW ::::',14)
GOTO 500
WRITE (5,201) IIIS
FORMAT (' ERROR IN CREATING WINnow, nsw =',14)
GOTO 500
WRITE (5,301) Ins
FORMAT (' ERROR DETACHING FROM REGION, nSW::::',I4)

500

CALL EXIT
ENn

Example 8-3 Attaching to an Existing Region
and Reading Data From It (Sheet 2 of 2)

288

DYNAMIC REGIONS

SEND- AND RECEIVE-BY-REFERENCE
If you create a private
(unnamed)
region,
you have complete
control over whether other tasks can have access to it.
You
specifically attach other tasks to the region by sending a packet
containing a
reference to the region. When you do that, you can
also specify what access they have to the region.
At the
time,
you must be attached with at least that much access yourself.
Named regions, on the other hand, can be attached by any task that
knows the name and has the appropriate access privileges to pass
the protection check.
Use the Send-by-Reference directive (SREF) to send
reference, with the following input parameters:

region

Receiver task name
WDB - Region ID
offset into region - sent unchecked to receiver
length to map - sent unchecked to receiver
window status word - determines how receiving
task is attached
address of buffer - 8(10) word buffer which is
sent to the receiver
Event flag - if specified, set when the reference
is received, not when it is queued up
(in the receive-by-reference queue)
The receiver task is attached to the region when the reference
is
queued.
This avoids
the problem of the region being deleted if
the sender exits before the
receiver
receives
the
region.
Remember
that private regions are always marked for delete on the
last detach.
If you are using an event flag for synchronization, note that the
flag
should be used
to notify the sender when the receiver
receives the region by reference.
It is not the same as the Send
and Receive Data directives,
where the flag
is set when the
reference is queued.
That flag
should be used
to notify the
receiver.

289

DYNAMIC REGIONS

The receiver follows a somewhat modified procedure to
region, as follows:

access

the

Create window

After reference is queued, Receive-by-Reference (fills
region ID in WDS)

Map to region

Use region

Detach from region

Use the Receive-by-Reference directive
(RREF)
to receive
reference to a region, with the following WDS input parameters:
Window Status Word -

WS.MAP (200(8)) for receive and map
WS.RCX (100(8)) for receive data or exit

Suffer Address - 10(10) word buffer for sender task
name (in Radix-50 format) and data
The following WDS output parameters are returned, all
the sender:
Region
Offset
Length
Window

set

ID
into region
to map
status word - describes how attached

If the WS.MAP bit is set, the Executive maps the window to the
region, using the offset, length, and window status word access as
sent.
If a separate Map directive is used, the receiver can first
check and/or modify those parameters before mapping to the region.
WS.RCX set tells the Executive that the task is to EXIT if there
are no packets in the Receive-by-Reference queue.

290

DYNAMIC REGIONS

Examples 8-4 and 8-5 show how to create a pair of tasks, a sender
task and a receiver task.
The sender, Example 8-4, creates a
private region, initializes it, and sends a reference to it to the
receiver.
The receiver,
Example 8-5,
in turn receives the
reference, displays the data, and then exits.
One run session is
included for both examples.
The following notes are keyed to
Example 8-4.
The RDB for the region.
The name is defaulted to create a
o private
region.'
The WDB for
the virtual address window.
The length
o actually
mapped will be returned after mapping.
Read
access is automatic for map,
access.

WS.WRT

gets

read/write

Create and attach to region, create virtual address window
and map it to the region.

o Fill the region with ASCII M's.
Send-by-Reference to RCVREF (Example 8-4).
Event flag
o will
be
set
when
RCVREF
actually
does
a

Receive-by-Reference.
()

Display message saying region created and sent.
for event flag 1 to be set.

Display message saying RCVREF received region.

Exit. The Executive will detach us from the region.
Note
that even if SNDREF exits before REVREF received, the
region will not be deleted because RCVREF is attached when
the reference is queued.
The region is deleted only after
.both SNDREF and RCVREF detach.

291

Then wait

DYNAMIC REGIONS

F'r';:OGRAM SNDREF

C File SNDREF.FTN

C This pro~ram creates a 64~word unnamed re~ion and
C fills it with ASCII characters. It then sends it bw
C reference to task RCVREF, and waits for RCVREF to
C receive the re~ion.(This is s1.nalled bw event fla~
C tl.) SNDREF then prints a messaSe and exits. Since
C the area is unnamed, it is automatical1w deleted when
C the last attached task exits.
("'

C Task-build instructions:
C;

>LINK/MAP/CODE:FPP/OPTIONS SNDREF,LB:(l,lJFOROTSMH)/J...IBI=i:ARY
O}":Ition? WNDWS::::1
Option? VSECT=DATA:160000:200
Or-,tion? <F~ET>

r'
c

c
c

C Install and run instructions: RCVREF must be installed.
C Run SNDREF first, then run RCVREF.
C

RDB = Re~ion definition block with the followin~
properties:
2 32-word blc)cks
Size
Name
none
Parti ticm
GEN
WO:none,SY:RWED,OW:RWED,
Prot(~ction
GR :nor,e
Attach on creation
Read and write access desired on attach

C
C
C

·c

c
("'

c
c

WDB = Window definition block with the followins
rt :i. es:
APR
7
Size
2 32-word blocks
Offset in re~ion 0 32-word blocks
Len~th of re.ion
2 32-word blocks
Map on create with write access

c
c

f~ T'C)f·'('~

c
c
c
c
c

INTEGER RDB(S),WDB(S),RCV(2)
C This common block will ali.n with the address window
COMMON /DATA/IDATA(64)
C Initialize the RDB
DATA F~DB/O, - 2,0,0, 31:;:GEN, 3~~
, u 43, -1700171
C Initialize the WDB
DATA WDB/ u 34001'01' u2,0,0, u2, -202,01
C Name of receiver task
DATA RCV/3RRCV,3RREFI

o
o

Example 8-4

Send-by-Reference (Sheet 1 of 2)

292

DYNAMIC REGIONS

CCld(~

CALL CRRGCRDB,IDS)
! Creat~~ region
IF (ID8 .LT. 0) GOTO 100 ! Check for error
! Move region id to WDB
[ WDB(4)=RDB(1)
CALL CRAWCWDB,IDS)
! Create window
IF (IDS .LT. 0) GO TO 200 ! Check for error
C Fill region with data
[DO :1.0 1:::1,,64
10
IDATACI)='MM'
r Send-b~-reference to receiver task, set event flag 1
C when T'ec(~i ved
CALL SREF(RCV,l,WDB,,,IDS)
IF (IDS .LT. 0) GO TO 400 ! Check for error
TYPE *,,' SN.DREF HAS CREATED THE REGION AND HAS
1 8ENT I T TO RCVF~EF.'
! Di SF' I a~ message
[ CALL WAITFR(l,IDS)
! Now wait for reception
IF (IDS .IT. 0) GOTO 500 ! Check for error
fYPE *,' RCV~~EF HAS RECEIVED IT. SNDREF IS NOW
lEXITING.'
! Write message
GO TO 600
! And go exit
C Error handling code
100
WRITE (5,,110)IDS
110
FOF~MAT (' ERROf~ CREATING REGION, DSW ._. ' ,14)
GO TO 600
200
WRITE (5,,2:1.0)IDS
210
FORMAT (' ERROR CREATING WINDOW, DSW - ',14)
GOTO 600
400
WRITE (5,410)ID8
410
FORMAT (' ERROR IN SEND-BY-REFERENCE, DSW - ',,14)
GO TO 600
500
WRITE (5,510)ID8
510
FORMAT (' ERROR ON WAIT" DSW - ',14)

o
o

O [

(SOO

CALL EXIT
END

Example 8-4

Send-by-Reference (Sheet 2 of 2)

293

DYNAMIC REGIONS

The following notes are keyed to Example 8-5.
for virtual address window.
The size is 200(8)
o WDB
32-word blocks, a full
4K words.
The offset into the
region, the length to map, and the access will be filled
in on receive.
Since the length to map sent by SNDREF is
two blocks, 2 will be used in mapping.
Note that the
window can be more than two blocks lohg. WS.MAP must be
left clear until after the window is created.
Otherwise,
the Executive will try to map the window to the region,
causing an error. See the discussion which follows.

o Create the virtual address window.
(200(8»
must be set in the Window Status Word
e WS.MAP
(word 7) of the Window Definition Block, so that the task
will map as part of the Receive-by-Reference.

o Receive-by-reference and map.
length actually mapped (two blocks, same as length of
o Get
region)
and convert from blocks to bytes •. Just display
that many characters.

o Display all characters with one WRITE.
Exit. The Executive will detach the task from the region.
o When
both tasks have detached, the region will be deleted.
The receiver may map after the receive-by-reference or as part of
the receive-by-reference.
If the receive-by-reference and the map
are combined in one directive,
issue the Receive by Reference
directive with the WS.MAP bit set.
In that case, the WS.MAP bit
must be clear when the window is created since you can't map until
you receive.
This is necessary because even though the receiver
is attached to the region when the reference
is queued up,
the
region ID isn't filled in the WDB until the receiver executes the
Receive-by-Reference directive.
So if you receive and map in one
call,
issue the Create Address Window directive with the W8.MAP
bit clear, and then set it before issuing the Receive-by-Reference
directive.
If you use a separate Map directive, the W8.MAP bit
can be left clear.

294

DYNAMIC REGIONS

PROGr-i:AM

RCVF~EF

C File RCVREF.FTN
C

C ProSram to receive~b~-reference a resion from SNDREF,
C map to the resionv read ASCII data from the resion,
r detach from the reSion~ and exit. The resion will be
C deleted on last detach.
C

C Task-build instructions: Include these options
WNDWS::::1
VSECT=DATA:160000:20000

c
c
c

C Install and run instructions: RCVREF must be installed.

r Run SNDREF firstv then run RCVREF.
C

C WDe - Window definition block with:
C
APR
7
200(8) 32-word blocks
C
Allow for full APR use
r'
These are filled in on receivev as set bw sender:
C
Offset in resion 0 32-word blocks
C
Lensth of reSion 0 32-word blocks
C
reset after mappins
C
Access
o
C
C NOTE: Must m~p after receivinS Cor as part of receive)
INTEGER WDBCS)
DATA WDB/a3400,0,·200~0,0,0,O~OI
r This common block will alisn with the address window
COMMON IDATA/IDATAC R10000)
r Create address window--do not map at this time
CALL CRAWCWDBv IDS)
r Check for error on create
IF CIDS .LT. 0) GOTO 200
r Now set WDB status for mappins--will be done bw receive-bw-reference
WDB(7)=WDBC7)+R200
C Receive-bw-reference and map
CALL RREF (WDBv ,IDS)
C Check for error
IF CIDS .LT. 0) GO TO 100

e
o

Example 8-5

Receive-by~Reference

295

(Sheet 1 of 2)

DYNAMIC REGIONS

C Calculate number of words of data - lensth in blocks

C returned at WDB(6)
NCHAR :::: ~32*WnB (6)
rWRITE(S,10) (ItIATA(I) ,I::::1,NCHAFO
10
~ORMAT (' ',32A2)

C Go eHit

GOTO 300

Error messases

100
110

WRITE(S,110)IDS
FORMAT (' ERROR ON RECEIVE-BY-REFERENCE, DSW =',I4)
GO TO 300
WJ::::rTE (5,210) IDS
FORMAT (' ERROR CREATING WINDOW, DSW ::::',14)
CALL EXIT
END

2()0
~.~10

~300

Run Session

:>:r NS F~CVJ:::EF
>J~UN

SNDI~EF

SNDREF HAS CREATED THE REGION AND HAS SENT IT TO RCVREF.
RUN J~CVJi:EF
RCVREF HAS RECEIVED IT. SNDREF IS NOW EXITING.
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM

Example 8-5

Receive-by-Reference (Sheet 2 of 2)

296

DYNAMIC REGIONS

THE MAPPED ARRAY AREA
A large core resident data area may be set up by using the FORTRAN
VIRTUAL statement.
The VIRTUAL statement provides the Task
Builder with the information required to create a mapped array
area.
The VIRTUAL statement is very similar to the DIMENSION
statement except that all space reserved for a VIRTUAL array is in
a separate area within the task region.
Figure 8-3 shows a task using a mapped array area.
The Task
Builder sets things up so that when the task is initially loaded,
the task region is larger than normal, with the mapped array area
set aside
in memory jmmediately below the task header.
The task
is automatically attached to the region since it is part of the
task region.
The area may be any size as long as the task image and the mapped
array area fit
into the partition. This means that it may be
larger than 32K words.
However, due to the subscript limitation
of 32767 in FORTRAN, a single array cannot have more than 32767
elements. Typically, the virtual address window maps only a
portion of the region at a time using a single APR.
Once you have
referenced an element in a virtual array, the APR is set up to map
to the nearest 4K boundary in the array.
Hence, assuming an
integer array IARRAY, if your first
reference
is to IARRAY(I) ,
then any element in the virtual array between IARRAY(I) and
IARRAY(4096) can be maped with the current setting of the APR.
However, if a reference is made to an element with a subscript
higher than 4096, the APR used for the 4K window must be remapped.
Hence,
consecutive
references
to
IARRAY(I) ,
IARRAY(5000) ,
IARRAY(2),
IARRAY(5001),
etc., will cause a remapping on each
reference, thereby inducing some additional overhead.
Note that
all mapping is transparent to the user; however, knowledge of how
mapping is performed, and when, can aid you in designing your
programs to reduce the overhead required by remapping.
Since the area isn't set aside until
the task
is loaded
into
memory,
any initialization of the area must be performed at run
time.

297

DYNAMIC REGIONS

PHYSICAL
MEMORY

VIRTUAL
MEMORY
WINDOW
(4K WORDS)

160000 APR 7 ~------~-

APR 6 I-

APR 5 I-

APR 4

I"-

TASK
IMAGE
(28K WORDS)

TASK
IMAGE

APR 3 I -

'\\
\\

APR 2 I-

APR 1 I-

APR 0 ...
-_-_H_EA_D_E_R_&_S_T_A_CK_-_-_______

---------~ __\ \ ___ _ - -HEADER
& STACK

\ \

CD INITIAL LOAD AND MAP

TOTAL SPACE INITIALLY
ALLOCATED. 4K WORD
AREAS MAPPED AS
NEEDED.

\ \

MAPPED
ARRAY
AREA
(32K WORDS)

TK-7739

Figure 8-3

The Mapped Array Area

298

DYNAMIC REGIONS

Example 8-6 shows how to create and use a mapped array area.
following notes are keyed to the example:

The

o Create the virtual array IDATA with 32000 elements.
o Data to be placed into various parts of the virtual array.
Put 'AI' into IDATA(I) and 'G7' into IDATA(2). After the
e first
reference, the mapping is set up to allow reference
to any element up to IDATA(4096) without remapping.
data into elements IDATA(4097) and IDATA(4098).
Note
o Put
that the window had to be remapped to access the second 4K
of the mapped array.

This is transparent to the user.

C»

Put data into the third 4K block.

Remapping needed.

Put data into the fourth 4K block.

Remapping needed.

«» Retrieve
data from each of the four 4K blocks.
Remapping
required for
each reference.
The mapping order for
displaying the data is different just to show that the
order need not match the original order for placing the
data into the region.

299

DYNAMIC REGIONS

PROGRAM VIRTAR

C File VIRTAR.FTN

C VIRTAR makes use of the mapped arra~ area b~ usinS a
C FORTAN virtual arra~. It places data in 4 different
C 4K word blocks of the area and then displa~s the
C data at the terminal.
C

C Set UP the virtual arra~ in the mapped arra~ area
VIRTUAL.. IIIATA(32000)
C Define data values to be placed in the arra~
rD ATAD AT A, DATB, DA TC / 1 Al' , 1 B2 1 '. 1 C3 1 /
~ATA DATD,DATG /ID4 / ,/G7 ' /
C Place data in 1st 4KW block/ IDATA(l) - IDATA(4096)
- [IDATA (1) ::::DATA
IItATA (~!) ::::DATG
C-Place data in 2nd 4KW block/ IDATA(4097) - IDATA(8192)
A
[IDATA (4097) ::::DATB
~
IDATA(4098)::::DATG
C Place data in 3rd 4KW block/ IDATA(8193) - IDATA(12288)
[IDATA(8j,93)::::DATC
IDATA(8194)::::DATG
C Place data in 4th 4KW block/ IDATA(12289) -IDATA(16384)
•
[IDATA (12289) ::::DATD
~
IDATA(12290)::::DATG
C Write data from 1st 4KW block
WRITE
(5,100) IDATA(1),IDATA(2)
(" Write data from 2nd 4KW block
WRITE
(5,100) IDATA(4097),IDATA(4098)
Write data from 4th 4KW block
WRITE
(5,100) IDATA(12289),IDATA(12290)
Write data from 3rd 4KW block
WRITE
(5,100) IDATA(8193),IDATA(8194)
FORMAT (' I,A2,A2)
:1.00
CALL EXIT
END

Ole

>F~LJN

VIRTA~\:

A1G'7
B2G'7

D4G7
C:~G'7

Example 8-6

Use of the Mapped Array Area

300

DYNAMIC REGIONS

Now do the tests/exercises for this module in the Tests/Exercises
book.
They are all lab problems. Check your answers against the
solutions provided, either in that book or in on-line files.
If you think that you have mastered the material, ask your course
administrator to record your progress in your Personal Progress
Plotter. You will then be ready to begin a new module.
If you think that you have not yet mastered the
to this module for further study.

301

material,

return

FILE I/O

INTRODUCTION
The RSX-IIM file system is composed of three parts.
•

File structures - the organization and data structures
maintained on the mass storage volumes themselves

•

Ancillary Control Processors (ACPs) - tasks which maintain
the file structures and provide access to them

•

File access routines - provide user-written tasks with an
interface to ACPs, which provide and maintain organization
within files.

This module reviews some basic information about file storage, and
provides general
information about the RSX-IIM primary file
structure called FILES-II, and its ACP. This module also presents
an overview and comparison of the two supplied file access
subsystems, File Control Services
(FCS)
and Record Management
Services
(RMS).
The following module provides details on
programming using FCS, which is the more widely used subsystem.

OBJECTIVES
1.

To describe the steps involved in file I/O

To describe the FILES-II structure and
maintains that structure during file I/O

To identify the advantages of using either FCS or RMS
file access.

how

the

FIIACP
for

RESOURCES
1.

IAS/RSX-ll I/O Operations Reference Manual, Chapters 1 and
5

RMS-ll User's Guide

305

FILE I/O

OVERVIEW
Quite often in an application you need to store data on a
peripheral device
(disk, magtape, etc.) for later retrieval.
To
write such an application, you must know something about the
different devices which are on your system.
In addition, you must
understand the file structure and its support systems.
Once you
know that, you can learn the procedure for actually performing I/O
operations.

TYPES OF DEVICES
Record-Oriented Devices
Record-oriented devices have the following characteristics.
•
•

Data is handled a record at a time.
There is no file structure.

Terminals, line printers, and card readers are all record-oriented
devices.
They are not designed for storage and fast retrieval of
data, but are designed instead to support interactive sessions or
provide hard copies of reports and other data.

File-Structured Devices
File-structured
characteristics.

devices
have
the
The data they contain:

following

general

•

Can be handled in files

•

Can be stored and retrieved quickly

•

Is typically stored on a storage medium which can be moved
from one device to another.

Hard disks,
floppy disks,
and
magtape
are
examples
of
file-structured devices.
The following definitions should prove
helpful in our discussion.
a file - a collection of related
logical unit of maSs storage.

307

data;

therefore,

FILE I/O

volume - a physical unit of mass storage consisting of a
recording medium and its packaging. Examples are a disk
pack, a reel of tape, a diskette, and a DECtape II
cartridge.

Types

of File-Structured Devices
There are two types of
file-structures devices,
sequential and random-access. The type
is determined by the kind of access to data on it.

Sequential devices have the following characteristics.
•

Data is retrieved in the same order as written

•

New data is always appended at the
tape, after the last data written

•

data cannot be written in the middle of the volume without
losing the data past that point.

logical

end

the

Magtape and cassettes are examples of sequential devices.
In
essence, data is stored in order as written.
To access any data,
all data before it on the tape must be read first.
Under RSX-lIM, the magtape ancillary
supports the ANSI file structure.

control

processor

(MTAACP)

The MTAACP supports the following file setups:'
•
•
•
•

A single
A single
Multiple
Multiple

file on a single volume
file on multiple volumes
files on a single volume
files on multiple volumes

Random-access devices, also
block-replaceable devices,
They can:

called block-structured devices or
have the following characteristics.

•

Store and retrieve data in units called blocks

•

Write or read blocks in any order

•

Rewrite blocks without interfering with other blocks.

Hard disks (RL0l/02, RP06, RM02/03), diskettes (RXll,
DECtape II are examples of random-access devices.

308

RX2ll)

and

FILE I/O

The FILES-II file structure, the standard RSX file ~ structure,
is
supported by the FILES-II ancillary control processor (FIIACP).
FIIACP supports multiple files on a volume, but a file may not
extend across volumes.
The COpy command (PIP in MCR) maintains
the FILES-II structure during transfers of files within a given
device and between FILES-II devices on a system.
The ANSI file structure is useful for transfers of files between
different
(possibly non-DIGITAL)
systems.
FILES-II is useful
between DIGITAL systems under RSX-IIM, RSX-IIM-PLUS, lAS and VMS
if the two systems have a device in common (e.g., both systems
have RL02s).
The FLX utility is provided to facilitate transfers
between
RSX and other DIGITAL systems which don't support
FILES-II, or between systems which support FILES-II (even, between
two RSX-IIM systems) which do not have a common FILES-II device.
In that case, the FLX transfer is typically made on magtape, using
DOS or RT-II format.

309

FILE I/O

COMMON CONCEPTS OF FILE 1/0
Common Operations
File I/O is often used to perform the following operations.
•

Creating a file

•

Deleting a file

•

Modifying existing data within a file

•

Appending new data to a file (or extending the file).

Steps of File 1/0
Use the following three basic steps to do file I/O.
1.

Open the file.
Specify a LUN and the file. The ACP connects a task
LUN to the file. Specify the access rights desired.
The ACP checks against the file protection code.
If
you
are creating a new file, specify the file
characteristics (e.g., format and initial length).

Perform the I/O operations.
Use macros to invoke subroutines to store data in
file and/or retrieve data from the file.

the

Close the file.
Notify the system that the file operations
are
completed, so that appropriate cleanup work can be
performed.

31~

FILE I/O

FILES-11
In order to use FILES-II, you need to understand its structure and
how to interact with it.

FILES-11 Structure
A block is the smallest unit of storage which is read from,
or
written to, a FILES-II device. Typically, the blocks are 256(10)
words or 512(10) bytes long.
Some devices divide or format their
volumes into pieces whith are 256(10) words long, and others do
not. Therefore, the FILES-II structure does some converting or
mapping so 'that you work with logical blocks which are all
standard size.
When the volume is formatted,
logical block
numbers are assigned to each 256(10)
word area on the disk,
starting with logical block 0. Generally, the position of data on
a FILES-II volume can be described in three alternate ways, by:
•
•
•

Physical location
Logical block number
Virtual block number

,Table 9-1 compares the three ways.
Figure 9-1 shows an example of
the mapping among the different methods. Typically, you will
reference data only within files.
The files are referenced by
virtual block numbers within the file, starting with 1.
Logical
block numbers are assigned to the entire disk, starting from 0.
The system converts virtual block number references to logical
block number references.
For example, if you request a read of
virtual block 5, the system looks at the mapping and finds that
this corresponds to logical block 1622(8). This logical block, in
turn, is mapped to one or more specific sectors on the disk, which
are read from the disk.

311

FILE I/O

Table 9-1

Comparison of Physical, Logical and Virtual Blocks

Type of Block
Designation

Size

How Designated

Physical

Depends on
device

On multi-platter disks,
designated by cylinder, track
and sector

Logical

256(10)
words

Numbered in increments relative
to the beginning of the volume,
starting with 0

Virtual

256(10)
words

Numbered in increments relative
to the beginning ofa file,
starting with 1

Typically, data is accessed as records, units which are not
exactly one block or 512(10) bytes long. A record is a unit of
user specified size, corresponding, for example, to. a single bank
account or a single line of text at a terminal.
Figure 9-2 shows how the operating system handles a request to
read a record using FCS. The first row shows a FORTRAN READ. The
FORTRAN READ instruction is converted by the compiler to a GET$
call to the File Control Services (FCS) to fead that record. In
MACRO, you will issue the GET$ call yourself. FCS checks to find
out which virtual block within the file contains that record and
issues the QlO directive for you.
The Executive converts the
virtual block number to its corresponding logical block number and
issues a read logical block QlO. The driver then converts the
logical block number to the appropriate physical locations, and
reads a block of data into memory. The record itself will then be
located within the block of data.
The second row shows a BASlC-PLUS-2 READ under the Record
Management Services (RMS). The BASlC-PLUS-2 compiler converts the
READ to aRMS $GET call. RMS converts this to a QlO, to read the
corresponding virtual block.
From that point on, the steps are
just like those in the FORTRAN example.

312

FILE I/O

FILE
VIRTUAL
BLOCK #'S
(IN THE
FILE)

1 2 1 3

SAMPLE.TXT;1

1 5 1 6 1 7 1 10

PHYSICAL
LOCATIONS
(ON THE
VOLUME)

NOTE: BLOCK NUMBERS ARE IN OCTAL
TK-7738

Figure 9-1

Example of Virtual Block to Logical Block,
to Physical Location Mapping

313

FILE I/O

MACRO-11
ENTERS HERE

FORTRAN

···
··
·

READ (5,10)
1DATA

COMPILER

FORTRAN RECORD

··.
···

GET$

FCS RECORD

READ DATA

BASIC-PLUS-2
RECORD

OIOIO.RLB

VIRTUAL
BLOCK #

LOGICAL
BLOCK #

EXEC
OIOIO.RVB. F11ACP

··•
···

~
~

.......

DRIVER

TRANSFER
FROM PHYSICA L
LOCATIONS ON
DISK

RMS

BASIC-PLUS-2

···
···

··
·
···

COMPILER

··
·
···

$GET

RMS RECORD
TK-7743

Figure 9-2 How the Operating System Converts Between
Virtual, Logical, and Physical BlocksFigure 9-3 shows the FILES-II structures which are used to support
virtua1-to-10gica1 block mapping.
Every FILES-II volume has a
number of system files on it, one of which is the Index File
(INDEXF.SYS).
The Index File contains certain blocks which are
for system use, plus a file header block for each file on the
volume.
Each file header block contains file retrieval pointers which are
used in mapping virtual blocks to logical blocks.
Each file
retrieval pointer locates a range of contiguous logical blocks.
The first byte tells how many contiguous blocks are in the group,
and the next three bytes specify the logical block number of the
first block in the group. Therefore, in the figure, there are
five contiguous blocks, starting with logical block 336851(10).
Virtual block 1 = logical block 336851(10), vb 2 = 1b 336852(10),
vb 3 = 1b 336853(10), vb4 = 1b 336854(10), and vb 5 = lb
336855(10). The next group of blocks, starting with virtual block
6 has 51(10) blocks and begins at logical block 336900(10)
up
through logical block 336950(10). The last 17(10) virtual blocks
(v i r t ua 1 b 1 0 c k s
57 ( 10 )
to 73 ( 10) ) beg i n a t
log i cal
b 10 c k .
337006(10)
up through logical block 337022(10).
These file
retrieval pointers are updated each time a change in block
allocation occurs as a result of a file I/O operation.
314

FILE I/O

VOLUME

~~~---f-INDEX FILE

,/'

./'

" "-

~
I ~ILE IFILE I FILE IFILE I· .. ~
. HDR . HDR . HDR . HDR _

VBN

6 /

/
/

\
\

FILE HEADER
FILE 3
~VA4""i-- RETRIEVAL POINTERS

SIZE J
1ST LBN

'----...-----'
SIZE

1ST LBN

H:005

L:021723 = 336851.

51.

H:005

L:022004 = 336900.

17.

H:005

L:022156 = 337006.
TK-7741

Figure 9-3 FILES-II Structures Used to Support
Virtual-to-Logical Block Mapping

315

FILE I/O

Directories
The operating system identifies files by file IDs, which are used
to calculate the location of the file header within the index
file. When you need to locate a file, it is difficult to remember
where it is on the disk, or even what its file ID is. Instead,
you use a file specification, a more English-like way
of
identifying a file.
An example of a file specification is:
DRI:[5,6]SAMPLE.TXT;I. Tasks you write also usually identify
files with a file specification. Directories are structures set
up on a FILES-II volume that are used to group files together, and
to convert file specifications to file IDs.
A directory is a list of files belonging to a single user, or
grouped together for other organizational purposes. An example of
files grouped together for organization is the libraries in User
File Directory (UFD)
[1,1] on the system device. On a FILES-II
volume, a directory is a special file containing a list of the
files belonging to that user or group. For each file, the list
has:
•
•

The file specification:
The file ID

name, type, and version number

The file ID consists of a file number and a sequence number.
The
file number identifies the offset within the index file to the
virtual block containing the file's file he~der.
The sequence
number is used to distinguish this file from previously deleted
files which used the same file header. There are two levels of
directories on a volume, as follows.
•
•

One Master File Directory (MFD) which is directory [0,0]
One or more User File Directories (UFDS)

Figure 9-4 shows the relationship between the two levels and the
files. The MFD contains a list of the system file, plus one entry
for each UFD on the volume. Each UFD file has a name of the form
gggmmm.DIR, where [ggg,mmm] is the user identification code (UIC)
of the owner. Each UFD cont~ins a list of the files in that
directory.

316

FILE I/O

MFO
[0,0]

- - - __ -r-\_ _

-----1..I_ _ _ -- -__

UFO
[200,1]

/
-

- -

UFO
[303,5]

---r

- , . - - - -- - L . . . - - - - - - '

HIYA.MAC;l

FLY.TXT;l

------/r--------+-------. ----I

IZZY.TXT;l

OZY.TXT;l

TK-3965

Figure 9-4

Directory and File Organization on a Volume

Figure 9-5 shows the steps used in locating and accessing ,the
blocks of the file DR2:[5,6]SAMPLE.TXTil. The device name, DR1:
tells which device or volume to look on.
The operating system
reads the MFD file header to find the retrieval pointers for the
MFD file itself.
It converts the virtual blocks to logical blocks
and reads the blocks of the MFD file.
It searches through the
dlrectory list for the UFD [5,6], namely the file 005006.DIR.
When it finds that name in the list, it uses the file ID to locate
the UFD file header.
It reads the retrieval pointers there,
converts the virtual blocks to logical blocks,
and reads the
blocks of directory [5,6].
It looks for an entry SAMPLE.TXTil.
When it finds that entry, it uses the file
ID to locate the
SAMPLE.TXTs file header.
It then reads the retrieval pointers in
the file header, converts the virtual blocks to logical blocks,
and reads the blocks of the file itself.
If this sounds like a lot of work, it is.
Later, you will learn
about a way to go directly to the file header using the file ID if
a file is opened a second time during a task's execution.

317

FILE I/O

DR 1:[5,6]SAMPLE. TXT; 1

MFD
HEADER

•
•
•

RETRIEVAL.
POINTERS

OOSOOS.OIR
OOS006.DIR

•

UFD
HEADER

FILE 10
FILE ID

MFO

•
•

RETRIEVAL
POINTERS

SAMPLE.TXT;1

FILE ID

UFO

[S,6]

•

THIS IS A SAMPLE FILE
FILE
HEADER

•
•
•

RETRIEVAL
POINTERS

FILE
SAMPLE.TXT;1

TK-7735

Figure 9-5

Locating a File on a FILES-II Volume

318

FILE I/O

Five Basic System Files
There are five basic system files found on all FILES-II volumes.
They are all created when the volume is initialized and are all
entered in the MFD. Two of these, the Index File and the Master
File Directory, have been mentioned previously. The five files
and their purposes are as follows.
•

The Index File:

INDEXF.SYS.

Boot block - used when a system volume is bootstrapped
Home block - contains volume identification and
information

other

Index file bitmap - a record of which header blocks
are in use;
used by FIIACP when allocating header
blocks to files
File header blocks for all files on the volume
•

The Storage Map:

BITMAP.SYS.

A record of which blocks on the volume are in use
Used by FIIACP when allocating blocks to files
•

The Bad Block File:

BADBLK.SYS.

A list of blocks on the volume known to be bad
•

The Master File Directory:

000000.DIR.

Entries for the five system files
An entry for each UFD file
•

The System Checkpoint File:

CORIMG.SYS.

Space used for checkpointing
allocates space in it.

319

the

system

manager

FILE I/O

Functions of the ACP
The FIIACP maintains the FILES-II structure on a volume during its
use.
The most elementary functions performed by the ACP are as follows.
•

Maintaining the File Header

Bloc~s.

This includes:

Allocating and initializing a file header when a
is created
Recovering a file header for
deleted

reuse

Maintaining file attributes such as
length, etc.

when

file

protection

code,

Maintaining the file retrieval pointers
•

Maintaining directories.

This includes:

Creating directory entries when a file or UFO is
created, or when a file synonym is created (e.g., by
the PIP /EN switch)
Removing entries from directories when a file is
deleted or a file synonym is removed (e.g., by the PIP
/RM switch)
•

Maintaining block allocation.

This includes:

Allocating blocks to files when a file is
extended

•

created

Recovering blocks for reuse when a file is deleted
truncated

Controlling and facilitating task access to
includes:

files.

This

Checking protection codes to determine access rights
Connecting a task's LUN to a
block I/O

file

Controlling shared access to files.

320

allow

virtual

FILE I/O

Table 9-2 shows the FIIACP functions performed
some typical file I/O operations.
Table 9-2

when

you

request

Examples of Use of FllACP Functions

Operation Requested

FUnctions Performed by FIIACP

Create a new, permanent file
and write data to the file.

1. Allocate a header for the file.
2. Allocate blocks to the file,
when it is opened and/or when
data written requires that extensions be added.
3. Create a directory entry for
the file.
4. Assign a LUN to the file.
5. When the file is closed, write
the updated file attributes to
the file header, deassign the
LUN

Read data from an existing
file.

1. Assign a LUN to the file.

Delete a file.

1. Remove the directory entry for
the file.
2. Deallocate the blocks of the
file.
3. Deallocate the header for the
file.

Append data to a file.

1. Assign a LUN to the file.
2. Allocate extra blocks to the
file.

Create a temporary (scratch)
file.

1. When file is opened, allocate
a header, allocate blocks, and
assign a LUN.
(No directory
entry is created.)
2. When file is closed, deallocate blocks, deallocate
header, and deassign LUN.
321

FILE I/O

Figure 9-6 shows the flow of control during the processing of an
I/O request.
This figure parallels Figure 9-2, which sho'ws how
the operating system converts virtual blocks to logical blocks to
physical locations.
The user task issues a read record request which is converted by
an FCS routine in the user task to a QIO, to read a virtual ,block.
The Executive converts the virtual block number to a logical block
number, using file retrieval pointers in pool. These retrieval
pointers are built by FIIACP from the retrieval pointers in the
file header. The Executive issues a read logical block request to
the driver. The driver converts the logical block number to the
actual physical locations and copies the block into the user
buffer.
For additional information on the FILES-II structure, see
5 of the IAS/RSX-il I/O Operations Reference Manual.

USER TASK

[

~EAD~ECDRD

Chapter

POOL
RETRIEVAL POINTERS

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

I
I

FCS OR RMS
EXEC

FILE HEADER

DRIVER

QIO IO.RVB

BUFFER
FILE BODY
F11ACP

TK·7737

Figure 9-6

Flow of Control During the Processing of an
I/O Request

322

FILE I/O

OVERVIEW AND COMPARISON OF FCS AND RMS

Common Functions
The File Control Services (FCS) and the Record Management Services
(RMS)
both offer easy methods for performing file I/O.
The
operator or programmer need not be concerned with all
the
nitty-gritty details, but can instead let FCS or RMS take care of
them.
Both perform the following functions:
•

Serve as an interface to the ACPs

•

Allow I/O to the virtual blocks
block-by-block basis (Block I/O)

file

•

Divide files
into logical
records and allow
individual records within a file (Record I/O)

I/O

•

Allow the programmer to process records using one
following buffers (Figure 9-7)

the

A buffer reserved by the programmer with another
buffer transparently used by FCS or RMS (move mode)
Directly in the buffer used
mode)

FCS

RMS

(locate

•

Allow device independent I/O - the routines are written to
work correctly with terminals, disks, etc.

•

Provide mechanisms for controlling shared access to files.

Beyond that,
FCS and RMS each offer a
organizations,
record
types,
and access
described in the following sections.

323

variety
modes.

of
file
These are

FILE I/O

MOVE MODE
~

TASK
_ _~(I.N MEMORY)

rA;;B;;C~.~.~.:----""--!- USER RECORD

DISK

BUFFER

MOVE RECORD
TO USER
RECORD BUFFER

.----...,.-+----.

...._ _t--INTERNAL
1----,.-'----.--1......1
BU FFER

LOCATE MODE
TASK
_-_-.:(IN MEMORY)

DISK

POINTER
/
/
/

POINT
POINTER
TO RECORD

MOVE BLOCK
TO INTERNAL
BUFFER
(I F NECESSARY)

1+-----1- INTERNAL
I----,.-L-...;;...;..-..,....-I.,.......I

BU FFER

TK-7742

Figure 9-7

Move Mode and Locate Mode

324

FILE I/O

FCS FEATURES
File Organizations
Essentially, all FCS supported £iles are 'sequential, meaning that
new records are added at the end of the file, and records are
stored in the order they are written. Figure 9-8 shows a file
with sequential organization.

CE LL NO.

r-~---m~m-~~~
RECORD

RECORD

... 1RECORD I
' n

TK-7748

Figure 9-8

Sequential Files

Supported Record Types
FCS supports two record
types,
fixed-length
records
and
variable-length records. Variable-length records may be sequenced
or nonsequenced. An example of each type of file is shown below
with the following three records:
12345
123 1234
AAAA BBBB CC D
The examples are in DMP format;
the six-digit number on the left
is the byte count in octal of the first byte in that row. Then
16(10) = 20(8) bytes follow in order in octal. Below each byte in
octal is its equivalent in ASCII. An underscore ( ) stands for an
ASCII blank. Consult the examples as you read the-description of
each record type which follows.

325

FILE I/O

Examples:
Fixed-Length Records (record length = 17(10»
000 061 062 063 064 065 040 040 040 040 040 040 040 040 040 040 040
3
4
5
1
2
020 040 xxx 061 062 063 040 061 062 063 064 040 040 040 040 040 040
pad 1
1
2
3
4
2
3
040 040 040 040 xxx 101 I i I 101 101 040 102 10'2 10'2 10'2 040 10'3 10'3

pad

060 040 1'04 040 040 040 xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx

pad

Variable-Length Records
000 005 000 061 062 063 064 065 xxx 010 000 061 062 063 040 061 062
2
3
1
2
1
5 pad
2
3
4
1
040
103
103
102
040
102
102
101
101
101
102
000
101
020 063 064 016
B
B
B
B
A
A
A
A
C
C
4
3
040 040 104 xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx
D

Sequenced Variable-Length Records
000 007 000 001 000 061 062 063 064 065 xxx 012 000 002 000 061 062
1
2
3
4
1
2
5 pad
020 063 040 061 062 063 064 020 000 003 000 101 101 101 101 040 102
A
A
A
A
B
3
1
2
3
4
040 102 102 102 040 103 103 040 104 xxx xxx xxx xxx xxx xxx xxx xxx
B

326

FILE I/O

Fixed-length records all contain the same number of bytes.
Therefore, the location of the beginning of any record within the
file can be computed from its record number.
With all
record
types, each record begins on an even word boundary. This means
that in files with fixed-length records, if each record contains
an even number of bytes, the next record begins immediately after
it.
If, on the other hand, each record contains an odd number of
bytes, one byte is unused after each record, and the next record
begins at the next word boundary. This unused byte is called a
pad byte.
Variable-length records may each have different lengths.
For all
files with variable-length records, the first word of each record
contains a byte count, telling how many bytes are in that record.
For variable-length nonsequenced records,
this count word is
followed by the data itself.
Following this, at the next word boundary, is the byte count for
the next record and then its data. To locate a given record
within the file, you must first read the byte count for the first
record in the file.
You can then use the byte count to locate the
second record. You then continue reading byte counts and locating
successive records until you reach the desired record.
Variable-length sequenced records contain a byte count, a user
specified sequence word, and then the data itself. The sequence
word can contain the record number or any other user specified
value.
Variable-length sequenced records are not used much under
FCS.
They are supported to allow compatibil~ty
with
RMS
variable-with-fixed-control records.

327

FILE I/O

Table 9-3 compares the different Fes record types.
Table 9-3
Record
Type
Fixed-Length

Comparison of FCS Record Types

Characteristics
Record length
set when file
created

Overhead
in File

Common
Applications

None

Files with
similar data
in each record
Bank account
information,
bad credit
card lists,
etc.

Records all
same length
(shorter
records padded)
Variable~Length

(nonsequenced)

Records may be
of different
lengths

One word per
record (holding record
length)

First word of
each record is
a byte count
Variable-length
(sequenced)

Variable length
records, with
an additional
word for a user
specified sequence number

328

Files with
varying contents among
records
Files to be
printed
Source and
list files

Two words per
record (one
for record
length, for
sequence
field)

Infrequently
used, except
for compatibility with
RMS.

FILE I/O

Record Access Modes
Fes offers two record access modes, sequential access and random
access.
Table 9-4 compares the two access modes. The major
difference is that with random access,
the user can process
records in any order (e.g., record 12, then record 4, then record
29). This is possible with fixed length records only, because Fes
can calculate the position of each record within the file from the
record number and the record size.
with variable-length records, on the other hand, Fes can't locate
record 12 unless it reads records 1 through 11 first, using the
record length in the first word of each record to calculate the
starting position of the next record. Therefore, you must use
sequential access with variable length records.
You may choose
either of the two access modes for fixed length records, depending
on how your application processes the records.

329

FILE I/O

Table 9-4

Comparison of Sequential Access I/O and
Random Access I/O

Characteristics

Sequential

Random Access

Devices supporting
this type of access

All devices

Block-structured
devices only

Record types using
this type of I/O

All record types

Fixed-length
records only

Sequence of records
in th.e file

Determined by the
order in which they
are written to the
file

Usually determined'
by the order in
which they are
written to the file

Order of processing
records

Usually the same
order as in the
file (one after
another)

In any order, as
specified by the
user (using the
record number)

Overhead if records
are processed in
same order as they
are stored in the
file

Low

Low, but not as
low as sequential

Overhead involved
if records are
processed in
order different
from how they are
stored in the file

Much higher than
random access I/O

Much lower than
sequential I/O

NOTE
With sequential
access,
special
system
subroutines allow the user to save pointers
to a record for much faster
subsequent
access.

330

FILE I/O

File Sharing
A task which opens a file may choose one of the following options:
•

That no other accessor change any data in the file
it has access ("shared" read, ~exclusive" write).

while

If this task desires read access, other accessors may
have simultaneous read access, but no other accessor
may have simultaneous write access.
If this task desires write access, no other
may have simultaneous read or write access.

accessor

Any access request causing a conflict is rejected.
•

That other accessors may change the
access ("shared" read/write access).

data

while

has

If this task requests read or write access, other
accessors may have simultaneous read or write access.
Use extreme care - Any precautions against corrupted
data are the responsibility of the accessors.
That no other accessor changes any block within the file
• which
has already been accessed (block locking). Shared
access to the file is allowed, but:
Each block which is written to is locked for exclusive
write access.
Each block which is read is
access.

locked

for

shared

read

It is not recommended if accessing a large numbers of
blocks, because each block lock uses four words of
pool.
Any attempt to access a block which causes a conflict,
returns an error.

331

FILE I/O

RMS FEATURES
File Organizations
RMS supports three file organizations, sequential,
relative and
indexed. See Figure 9-9. Sequential files under RMS are the same
as sequential files under FCS. A relative file is composed of a
series of cells of uniform size. The cell size is greater than or
equal to the largest record to be placed in the file.
A single
record may be written to a cell, or the cell can be empty.
The
cells may contain variable-length
records.
Variable-length
records within relative files can be accessed randomly because
each record is contained within a fixed-length cell.
Also, when
you read successive records in a relative file, empty records are
automatically skipped.
An indexed file is composed of records, plus one or more indexes
,which are used to access those records.
Each index is used to
retrieve records according to the contents of a particular field,
or key, within the record.
The data records themselves are
ordered according to a primary key which you declare when you
create the file.
Figure 9-9 shows an indexed file with a single key,
namely last
name.
In the example,
the data records are in the bottom row,
ordered alphabetically by last name.
The index for this file
contains two other levels, levelland level 2 (the root level).
A search for a record begins at the root level. For example, to
find the record with key value FRANCIS, search through the root
level, checking for the first value which is greater than or equal
to FRANCIS.
The first such value is SMITH. Go to the next level
and again search for the first value greater than or equal to
FRANCIS;
it is GROSS, the first value. Now go to the next level
and search again;
this time the value FRANCIS is found.
Since
this is level 0, we have found the record.
As new records are added to the file, they are inserted in order
at level 0 of the primary index. The primary index structure is
adjusted for the new entry at the same time.
In addition, any
alternate index structures for other keys are adjusted as well.
There is always one primary key, and there may be as many as
254(10) alternate keys.

332

FILE I/O

SEQUENTIAL FILE ORGANIZATION

RELATIVE FILE ORGANIZATION

LEVEL 2
(ROOT)

LEVEL 1

LEVEL 0

INDEXED FILE ORGANIZATION

Figure 9-9

RMS File Organizations

Level 0 of the alternate keys contains pointers to the original
location of the data
record
itself.
If a data record· is ever
moved in order to maintain the
index structure, a pointer is
created and maintained
in the record's original location, which
points to the data record's new location.
One specific advantage of an indexed file over a relative file
is
that an indexed file allows you to search for records using
several different key fields, while only the cell number can be
used with relative files.
Even with a single key, indexed files
offer keys consisting of any ASCII characters, in contrast to just
a cell number for relative files.
There is, of course, more space overhead required in the file for
the
index structures.
In addition, more execution time is
required to insert new records, because the index structures must
be updated as well. We are keeping things rather simple in the
the
discussion
here.
For
additional
information,
see
RMS-II User's Guide.
333

FILE I/O

Record Formats
RMS supports three record
formats;
fixed-length
records,
variable-length records,
and variable-length records with fixed
control.
Fixed-length records and variable-length records are the
same as fixed-length
records and nonsequenced variable-length
records respectively, under FCS.
They are both supported under
all three file organizations.
Variable-length records with fixed-control
(VFC)
contain
a
fixed-length portion,
for control, followed by a variable-length
portion. The fixed control portion may be up to 255(10)
bytes
long. A sequenced variable-length record under FCS is the same as
a VFC record with a 2-byte (one word) fixed control portion.
An example of the use of VFC records is a bank account file, where
some accounts have both savings and checking, and others have just
one or the other. The fixed control portion could contain the
account number plus an indication of the kinds of accounts
contained in it.
The variable portion contains the account
information for those accounts.
The length of this portion
varies, depending on how many accounts the person has.
VFC
records
are
supported
under sequential and
relative file
organizations only.

Record Access Modes
RMS supports three record access modes:
sequential access, random
access,
and access by Record File Address (RFA).
Sequential
access and random access are similar to the FCS access modes,
except that they are applied differently for indexed files.
For sequential access on an indexed file, the "next" record is the
record with the next highest key value using the specified key,
not the next record added to the file.
For random access,
a key
value for a certain key is specified, and that record is located
and accessed. To access a record by record file address,
save
pointers to the record
,(called its record file address or RFA)
from one access, then use the pointers to subsequently access the
record again.
Table 9-5 describes the various access modes supported for each
file organization and how they work.
For additional information,
see the RMS-ll User's Guide.

334

FILE I/O

Table 9-5

File Organization, Record Formats, and Access,Modes
I

sequential
Files

Relative
Files

Indexed
Files

Record
Formats
Supported

Fixed
Variable
VFC

Fixed
Variable

Access Modes
Supported

Sequential
RFA*

Sequential
Random
RFA*

Sequential
Access
Techniques

writes and
reads subsequent,records

Writes to
subsequent
cells
Reads from subsequent cells,
skipping empty
ones

Accesses cells
in ascending
order according to user
specified key

Random
Access
Techniques

Not allowed

User specifies
cell number of
record to be
accessed

User specifies
key and key
value to be
used in
accessing
records

Record File
Address
Techniques

Task can
store RFA* of
a record for
later return

Same as sequential files

Same as
sequential
files

* Not available in FORTRAN.

335

FILE I/O

File Sharing Features
RMS offers more sophisticated file-sharing options than FCS.
Sequential files can be shared for read access only. Relative and
indexed files can be shared for read and write access.
When
opening a relative or indexed file, a task indicates one of the
following options.
•

No other accessor can change data in the file while it has
access ("shared" read, exclusive "write").

•

Other accessors can change data, but subsets of
are protected at a time, while in use.

the

file

Relative and indexed files are divided into units called buckets
(of user specified size, each I to 32(10) blocks long).
In fact,
all actual I/O tranfers are performed on full buckets only.
In
implementing protection of subsets of the file at a time,
protection is on a bucket-by-bucket basis (bucket-locking).
A bucket is locked from the time any task with write access
accesses a record in a bucket, until that task begins operations
on another bucket, or closes the file.
This means that ~ecords
within a given bucket can't be accessed by other tasks while
another task with write access is using the bucket.
But other
tasks may access other buckets in the file during that time.

336

FILE I/O

Summary
Table 9-6 summarizes our comparison of FCS and RMS.
The
module discusses the details of how to use FCS in a program.

Table 9-6

Comparison of FCS and RMS

Characteristics

FCS

RMS

supporting
utilities

Standard RSX
utilities

Special RMS utilities
to define, convert,
etc.

supporting
languages

MACRO-II
FORTRAN IV, IV-PLUS,
-77, BASIC-II

MACRO-II
FORTRAN IV-PLUS,
-77, BASIC-PLUS-2
COBOL

Ease of
file design

Relatively simple

Relatively complex

Ease of
programming

Relatively simple in
high-level languages

Relatively simple in
high-level languages,
issues of efficiency
complex

Moderate in MACRO-II

Relatively difficult
in MACRO-II

Virtual block I/O

Sequential record
access

Random access by
record number with
fixed-length records

Random access by
cell number in a
relative file

Type of data.
access supported

Random access by
key field within
reco rd, in an
indexed file
Access by record
position pointers,
saved from previous
access of record

337

Access by record
file address,
saved from previous
access of record

FILE I/O

Table 9-6
Characteristics

Comparison of FCS and RMS (Cont)
FCS

RMS

Overhead in file Minimal
needed to support
record ~tructure

Minimal for sequential files
Moderate for
relative files
High for indexed
files
Low for sequential
and relative files

Execution time
overhead to
support record
access

Low

Shared access
coordination

System protection on
a per-file basis or
on an all blocks
accessed basis

Moderate to high
for indexed files,
depending on file
and program design,
and 'file growth
System protection
on per-file or
per-bucket basis
within a file

Now do the tests/exercises for this module in the Tests/Exercises
book.
They are all written problems. Check your answers against
the provided solutions 'in the Tests/Exercises book.
If you think that you have mastered the material, ask your course
administrator to record your progress on your Personal Progress
Plotter. You will then be ready to begin a new module.
If you think that you have not yet mastered the
to this module for further study.

338,

material,

return

FILE CONTROL SERVICES

INTRODUCTION
The File Control Services
(FCS)
subsystem provides the means
through which tasks perform I/O.
In FORTRAN, calls to the FCS
routines are made indirectly through the FORTRAN Object Time
System (OTS).
While the FORTRAN programmer need not know how the the data
structures or the various calls to the FCS subroutines are used,
this module is presented as a brief introduction to FCS.
The first example, illustrating how a FORTRAN program creates a
file,
also shows the MACRO code needed to perform the same
function.
Further examples illustrate how some of the FCS features can be
incorporated
by
using the FORTRAN OPEN statement and the
appropriate forms of the READ and WRITE statements.
The major portion of this module contains a brief summary, with
examples, of the FORTRAN READ, WRITE and OPEN statements and the
various file and record types used in writing a FORTRAN program.
The FORTRAN programmer should be aware that each of the above,
READ, WRITE, and OPEN, are translated into FCS data structures at
compile time, and CALLs to FCS routines at e~ecution time.

OBJECTIVES
1.

To choose file characteristics for a specific
and create files with those characteristics

application

To write tasks which read or write data using record I/O.

RESOURCES
1.

FORTRAN IV User's Guide

FORTRAN IV-Plus User's Guide

FORTRAN-77 User's Guide

341

FILE CONTROL SERVICES

FILE ORGANIZATION VS. RECORD ACCESS
A clear distinction must be made between
file and the record access to a file •

the

organization

. A file's organization refers to how the file was created
keyword ORGANIZATION in the OPEN.

via

a
the

The two possibilities are:
ORGANIZATION=' SEQUENTIAL'
ORGANIZATION=' RELATIVE ,
'INDEXED' is a third ORGANIZATION, but will not be discussed here.
Once established, the file ORGANIZATION cannot
default is 'SEQUENTIAL'.

changed.

The

The record access to a file determines how a particular program
wants to access a file, again via the OPEN. The choices are:
ACCESS='SEQUENTIAL'
ACCESS='DIRECT'
ACCESS='APPEND'
(ACCESS='INDEXED' will not be discussed.)
Figure 10-1 shows the possible combinations
ACCESS.
ORGANIZATION
SEQUENTIAL

"
"
RELATIVE

"
Figure 10-1

ORGANIZATION

ACCESS
SEQUENTIAL
APPEND
DIRECT (if fixed
length records)
DIRECT
SEQUENTIAL

possible Combinations of ORGANIZATION and ACCESS

343

and

FILE CONTROL SERVICES

READ AND WRITE ACCESS TO A FILE
When a file is opened via the OPEN statement, the default is that
the file
is opened for read and write access. The OPEN keyword
READONLY is used to restrict a program from write access.
If you
are the
'WORLD'
to a file (i.e., not SYSTEM, OWNER, or GROUP)
which has 'WORLD' protection set to R (read), and you attempt to
open that file without using the READONLY keyword in the OPEN, the
open will fail.

TYPES OF RECORDS IN A FILE
(Sometimes Referred to as 'Record Format')
There are three types of records (record formats)
file via the OPEN keyword RECORDTYPE:

possible

RECORDTYPE= 'VARIABLE ,
RECORDTYPE='FIXED'
RECORDTYPE='SEGMENTED'
Type VARIABLE consists of variable length records where the record
length is kept in the first two bytes of each record.
Type FIXED consists of records all of the same length as specified
in the RECORDSIZE keyword in the OPEN. Since the size is fixed,
it is not kept as an extra two bytes in the record;
it is kept in
the header of the file and is available when the file ~s opened.
Type SEGMENTED consists of records which contain a single logical
record having one or more variable length records (segments). The
length of a segmented record is arbitrary; however, the length of
each segment is determined by the value of the RECORDSIZE keyword.
The default size is 133.
The segmented record is unique to
FORTRAN and can be used only with unformatted sequential files
under sequential access.
Because there is no set limit on the size of a segmented record,
each segment contains control information to indicate that the
segment is one of the following:
•
•
•
•

The first segment in the segmented record (control word=l)
The last segment in the segmented record (control word=2)
The only segment in the segmented record (contol word=3)
None of the above:
i.e., a continuation record
(control
word=0)

344

FILE CONTROL SERVICES

The control word is kept as the first two bytes in the segment if
the record is FIXED and in the third and fourth bytes if the
record is VARIABLE.
When you wish to access an unformatted sequential file that
contains fixed length or variable length records, which was not
created by FORTRAN, you must specify RECORDTYPE='FIXED'
or
RECORDTYPE='VARIABLE'
when you open the file.
If you do not
specify a RECORDTYPE,
the default OPEN of the file will be
RECORDTYPE='SEGMENTED' and the first word (if FIXED) or the second
word (if VARIABLE) will be treated as a .control word causing
almost certain errors in the data.

FORMATTED AND UNFORMATTED RECORDS
A READ or WRITE statement can be formatted or unformatted.
The
main difference in the two is that a formatted READ or WRITE uses
ASCII data while an unformatted READ or WRITE uses untranslated
binary data.
The FORM='FORMATTED' or FORM=' UNFORMATTED' is used as appropriate.
The
default
is FORMATTED for ORGANIZATION='SEQUENTIAL'
and
UNFORMATTED for ORGANIZATION='RELATIVE'.

DECLARING THE SIZE OF A RECORD
The keyword RECORDSIZE is used to declare a specific
record. The defaults are as follows:
FORMATTED
UNFORMATTED (fixed)
UNFORMATTED (variable)

size

for

133 bytes
128 bytes
126 bytes

Note that you must specify the TKB option MAXBUF=n if you e~,~ed a
record size of 133, where n is the size in bytes of the record.

345

FILE CONTROL SERVICES

SUMMARY OF KEYWORDS IN THE OPEN STATEMENT
ORGANIZATION

=
=

'SEQUENTIAL'
'RELATIVE'

ACCESS

=
=
=

'SEQUENTIAL'
'DIRECT'
'APPEND' (sequential only)
to disallow WRITEs

READONLY
RECORDTYPE

=
=
=

'FIXED'
'VARIABLE'
'SEGMENTED'

FORM

=
=

'FORMATTED'
'UNFORMATTED'

RECORDSIZE

The remainder of this module is a series of examples illustrating
the various types of files and how they are OPENed and ACCESSed.

346

FILE CONTROL SERVICES

Example 10-1, CRESEQ, creates a file, VARI.ASC, of variable length
records. Since the records are variable in length, the byte count
for each record is kept in the first two bytes of the record
itself.
As can be seen from the run session, the first record contains a
single character, 1.
Therefore bytes 0 and 1 are 001 and 000.
The next byte is 61, which is ASCII for 1 followed by a byte of
000.
Since the record has an odd number of bytes, the record is
padded with a 000 byte.
The next record contains an even
record need not be padded.

number

bytes

(2),

the

Although the examples use several defaults, in order to illustrate
the various defaults, it is recommended that no defaults be used
when creating a file with an OPEN statement.
Hence,
in Example
10-2, the complete OPEN is as follows:
OPEN(UNIT=l,NAME='VARI.ASC',CARRIAGECONTROL='LIST' ,
ORGANIZATION='SEQUENTIAL',ACCESS='SEQUENTIAL',
1
2
TYPE='NEW' ,FORM='FORMATTED')
While it may seem a bit tedious to include all options in the
OPEN,
it aids greatly ln the readability of the program and
relieves any question as to what was meant in the OPEN.

347

FILE CONTROL SERVICES

PROGRAM CRESEQ

!CREATE FILE SEQUENTIALLY

c
C FILE CRESEQ.FTN

C This task creates a file VARI.ASC of variable-len.th
C records usin~ seauential record access. The records
C are input from the terminal and written to the file.
C The process stops when the operator twpes CTRL/Z at
C the terminal.
C
BYTE BUFF(80)
INTEGER LEN
C OPEN FILE - Default access is seauential, default form
C is formatted 1/0 with seauential access
OPEN
(UNIT=l,NAME='VARI.ASC',TYPE='NEW',
1
CARRIAGECONTROL='LIST')
C Loop
READ (5,11,END=100) LEN,BUFF
Read record
10
FORMAT (Q,80Al)
11
WRITE (1,12) (BUFF(I),I=l,LEN)
Write record
FORMAT (80Al)
to file
12
GO TO 10
C Close file and exit
100
CLOSE
(UNIT=l)
CALL EXIT
END
Run Session
>RUN CRESEQ
1

22
333
4444
Now is the time for all .ood.
Dump of DR2:C305,301JVARI.ASC;6 - File ID 40554,5,0
. Virtual block 0,000001 - Size 512. b~tes
000000
000020
000040
000060

001 000 061
064 064 064
040 164 151
157 144 056

Example 10-1

000 002 000
064 035 000
155 145 040
000 000 000

062 062 003 000 063
116 157 167 040 151
146 157 162 040 141
000 000 000 000 000

063 063 000
163 040 164
154 154 040
000 000 000

004 000
150 145
147 157
000 000

Creating a Sequential File with Variable Length Records

348

FILE CONTROL SERVICES

Example 10-2 shows the equivalent MACRO code to produce
file as Example 10-1.

the

same

Example 10-3, SEQFOR, reads the first five records from
VARI.ASC and displays them on the terminal.

the

file

.TITLE

CRESEQ

.IDENT
.ENABL

1011
LC

Enable lower case

File CRESEQ.MAC
CRESEQ creates a file VARI.ASC of variable-Iensth
records usin~ seQuential access~ It reads records from
; TI:, and places them in the file. A -Z terminates
input and closes the file.
Assemble and task-build instructions:
MACRO/LIST LB:Cl,lJPROGMACS/LIBRARY,dev:CufdJ-)CRESEQ
LINK/MAP CRESEQ,LB:[l~lJPROGSUBS/LIBRARY
.MCALL
.MCALL
.MCALL
.MCALL

EXSTSC,QIOWSC~QIOWS,DIRS ~ S~stem macros
FSRSZS,FDBDFS,FDATSA,FDRCSA,FDOPSA ; S~stem
NMBLKS,OPENSW,PUTS,CLOSES; FCS macros
DIRERR,IOERR,FCSERR ; SUPplied macros

FSRSZS 1
; 1 file for record 1/0
; Define file descriptor block for VARI.ASC
FDB:
FDBDFS
Allocate the FDB
FDATSA R.VAR,FD.CR
Variable lensth records,
Listins - implied
(CR),(LF)
FDRCSA ,BUFF
SeQuential access and
record 110 bhl
default, BUFF is
user record buffer
Use LUN 1, file spec
FDOPSA 1"FNAME
at FNAME
FNAME: NMBLKS VARI,ASC
"VARI.ASC"
User Record Buffer
BUFF:
.BLKB
80.
110 status block
lOST:
.~LKW
2
.EVEN
Enable local swmbol
.ENABL LSB
block

Example 10-2

MACRO Equivalent of Example 10-1 (Sheet 1 of 2)

349

FILE CONTROL SERVICES

; Open file for write, call ERRl if open fails
START: OPENSW tFDB"""ERRl
; Get record from terminal, put to file.
lOS:
QIOWSC IO.RVB,5,1"IOST,,(BUFF,80.>
BCS
ERR2D
Branch on directive
error
TSTB
lOST
Check for lID error
ELT
ERR21
Branch on lID error

EXIT:

MOV
PUTS
BCS
DR

IOST+2,Rl
iFDB"R1
ERR3
lOS

CLOSES
EXSTSC

iFDB,ERR4
EX$SUC

Number of b~tes input
Put record to file
Branch on FCS error
Get next record

Close file
Exit with success
9 status
; Error code - Close file if necessary, display error
9 messaSe and exit
8~Rl:
FCSERR tFDB,(ERROR OPENING FILE>
ERR2D: DIRERR (DIRECTIVE ERROR ON READ>·
ERR2I: CMPB
$IE.EOF,IOST
Is it MZ?
BEQ
EXIT
9 If eGual, close file
9 and exit
tIOST,(ERROR ON READ> 9 Display error
IOERR
messa~e and exit
ERRJ:
CLOSES tFDB,ERR4
; Close file
FCSERR iFDB,(ERROR WRITING RECORD>
ERR4:
FCSERR tFDB,(ERROR CLOSING FILE>
.END
START
Run Session
>RUN CRESEQ
1
22

333
4444
Now is the time for all Sood.
Dump of DR2:C305,301JVARI.ASC96 - File ID 40554,5,0
Virtual block 0,000001
Size 512. bytes

000000
000020
000040
000060

001 000 061 000 002 O()O 062 062 003 000 063 063 063 000
064 064 064 064 035 000 116 157 167 040 151 163 040 164
040 164 151 1~~ 145 040 146 157 162 040 141 154 154 040
157 144 056 000 000 000 000 000 000 000 000 000 000 000

Example 10-2

.~~

004 000
150 145
147 157
000 000

MACRO Equivalent of Example 10-1 (Sheet 2 of 2)
350

FILE CONTROL SERVICES

PROGI~AM

SE(~FOI:~

C File SEQFOR.FTN
C;

C This task reads the first 5 records from the file
VARI.ASC usinS se~uential access and formatted reads.
C It displaws the records at TI:.

INTEGER REC(40)
("'.#

Of~en

file

OPEN (UNIT=l,NAME='VARI.ASC',TYPE='OLD')
I~f a 1..1 1 ts

C
f'

access,
formatted reach;
se~uential

DO :1.00 I::::l,5
C Read record from file

READ (1,10) N,REC
FORMAT (Q,40A2)

C Write record at terminal

20
:1.00

WRITE (5,20) (RECCK),K=1,(Nfl)/2)
FORMAT (' ',40A2)
CONTINUE

C Close file and exit

CLOSE (UNIT:::l)
CALL. EXIT
END
Run Session

>RUN SEQFOR
1

22
~:S:33

4444
Now is the time for all

Example 10-3

~ood+

Program to Read File Created in 10-1

351

FILE CONTROL SERVICES

Example 10-4, CRESEQFIX, creates a file,
fixed length records of 16 bytes each.
In
records, the size of each record is kept in
rather than in the first two bytes of the
file dump you will see that the first input
1, creates a record consisting of 61
(40(8». The next record is 62, 62, and 14

FIXED.ASC,
containing
a file of fixed length
the header of the file
record itself.
In the
record, containing a
(ASCII)
and 15 blanks
blanks, etc.

One advantage of a file of fixed length records is that the file
may be accessed in 'DIRECT
(or random) mode for both READ and
WRITE.
The disadvantage of a fixed
length record
is that,
assuming a l6-byte record, a
record containing one byte and a
record containing 16 bytes occupies the same space on the disk.
(Direct access is not available on a tape or cassette.) If you
have a wide disparity in record sizes, say 10 and 80, it may not
be practical to use fixed length records. However, where disk
space is not a problem, using direct access to a sequential file
might be very useful.

352

FILE CONTROL SERVICES

PROGRAM CRESEQFIX

!CREATE FILE SEQUENTIALLY

C FILE CRESEQFIX.FTN
C

C This task c~eates a file FIXED.ASC of fixed-IenSth
C records usins seGuential record access. The records
C are input from the terminal and written to the file.
C The process stops when the operator twpes CTRL/Z at
C the terminal.

BYTE BLJFF(SO)
INTEGEli LEN
C OPEN FILE - Default access is seGuential, default rorm
C
is formatted lID with seauential access.

0,
(
.1

OPEN
(UNIT~l,NAME~'FIXED.ASC',TYPE='NEW',
1 RECORDTYPE='FIXED',RECORDSIZE=16)

C Loop
READ (5,11,END=100) LEN,BUFF
FORMAT (Ch SOA1)
WRITE (1,12) (BUFF(I),I=l,LEN)
FORMAT (SOA1)
:1.2
GO TO 10
C Close file and exit
100
CLOSE
(UNIT=l)
CALL EXIT
END
10

I:;:ead raco rd

Write record
tC) file

RIJn Session
1

22
333
4444
Now is the time for all sood.
- File III 40573,6,0
Virtual bl()clt.:. 0,,000001 - Size 512. b~:rt,es

DumF' of

DR2:[305,301JFIXED.ASC~3

000000
()00020
()00040
000060
()00100

061 040
062 062
063 063
064 064
122 157

040 040 040 040 040 040
040 040 040 040 040 040
06~5 040 040 040 040 040
064 064 040 040 040 040
163 145 163 040 1.41 1.62

Example 10-4

040
040
040
040
145

040
040
040
040
040

040 040
040 040
040 040
040 040
162 145

040
040
040
040
1.44

040
040
040
040
056

Creating a File With Sequential,
Fixed Length Records

353

040
040
040
04()
04()

040
04()
040
040
040

FILE CONTROL SERVICES

Example 10-5, READFIXED, prompts you for the record number of the
record you want from the file FIXED.ASC, displays the record and
then allows you to replace the record if you wish. Note that the
file was created as a sequential file with fixed length records
and is being accessed as DIRECT. Since the record size is in the
header of the file,
it is not necessary to describe the record
size in the OPEN. Note that both the READ and the WRITE to unit 1
use the formatted, direct form, i.e.:
READ (1'NO,10)
and
WRITE (1'NO,10)
One precaution here is that if you attempt to replace a record
with a longer record (in this case 16 bytes) than the original,
the new record will be truncated on the right.
As you can see from the run session in CRESEQFIX, the third record
originally contained 333.
This was replaced with "Now is the
Time", as is shown by running READFIXED a second time and
displaying record 3 again.

354

FILE CONTROL SERVICES

PROGRAM READFIXED

C File READFIXED.FTN

C This task asks YOU which record YOU want from FIXED.ASC~
C and displays the record on the terminal. It then asks if
C ~OIJ wi1!>h to replace the recC"Jrd c:~nd j.f so asks 1"or the new
C record.
CHARACTER*16 REC,NEW
C Open file
OPEN (UNIT=l,NAME='FIXED.ASC',TYPE='OLD',ACCESS='DIRECT',
1 FORM='FORMATTED')
C Read record from file
TYPE *, 'Enter record number ~ou want.'
READ *,NO
READ (1'NO,10)REC !Get record number NO
10
FORMAT (A16)
C Write record at terminal
WI~ITE (5,20) REC
TYPE *, 'Do YOU want to replace the record? Y or N '
READ(5,10)ANS
IF (ANS.EQ.'N'.OR+ANS~EQ.'n') GO TO 100
TYPE *, 'Enter new record.'
READ(5,10)NEW
20
FORMAT (' ',A16)
WRITE(1'NO~10)NEW

CONT INLJE
C Close file and exit
CLOSE (UNIT=1)
CALI... EXIT
END
:1.00

Run Session
>I~UN READF I XED
Enter record number

YOU

want.

~'5

333

Do YOU want to replace the record? Y or N
y

Enter new record.
Now is the time.
>RUN READFIXED
Enter record number wou want.
~'5

Now is the time.

Example 10-5

Reading a Fixed Length Record

355

FILE CONTROL SERVICES

Example 10-6, DIRFOR, illustrates the creation of a file via
direct access. The example creates record 1 through record 5, in
order. It is not necessary to create the records in order, nor
must there be a record n-l if record n exists. Hence you may have
a sparse file, containing only those records whose record numbers
are specifically used in a WRITE.
Note that the RECORDSIZE = 10 is used in the OPEN. Since this is
a formatted record,
the recordsize of 10 means that each record
will be 10 bytes. Hence the first record, containing 1,1,1,1,1,
is filled with five blanks (40,40,40,40,40). The fifth record,
which contains just a 5, is filled with nine blanks. The rest of
the file is filled with zeros.

356

FILE CONTROL SERVICES

PROGRAM DIRFOR

C File DIRFOR.FTN

C This task creates a file DIRFOR.DAT
C access formatt~d writes.

usin~

direct

C
C Direct access formatted writes are available in

r FORTRAN IV-PLUS and FORTRAN-77 onlw
(J

INTEGER REC(10)

C Open file
OPEN (UNIT=2,NAME='DIRFOR.DAT',ACCESS='DIRECT't
1 TYPE='NEW',FORM='FORMATTED',RECORDSIZE=10)
DO 100 1=1,5
C Prompt ~or input
WRITE (5,25)
25
FORMAT ('$ INPUT UP'TO 10 DIGITS: ')
C Read record from terminal
READ (5,50)N,REC
SO
FORMAT (Q,10Il)
C Write record to disk
WRITE (2'1,80) (REC(K),K=l,N)
80
FORMAT (1011)
100
CONTINUE
CLOSE (UNIT=2)
CALL EXIT

END
Run Session
>RUN DIRFOR
INPUT UP TO
INPUT UP TO
INPUT UP TO
INPUT UP TO
INPUT UP TO

10 DIGITS:
10 DIGITS:
10 DIGITS:
10 DIGITS:
10 DIGITS:

11111
2222
3333333333
444
5

Dump of DR2:[305,301JDIRFOR.DATP17 - File ID 40653,10,0
Virtual block 0,000001 - Size 512. b~tes
000000
000020
000040
000060

061 061
040 040
064 040
040 040

061 061
040 040
040 ~O
000 000

Example 10-6

061 040 040
063 063 063
040 040 040
000 000 000

040 040 040
063 063 063
040 065 040
000 000 000

062
063
040
000

062 062 062 040 040
063 063 063 064 064
040 040 040 040 040
000 000 000 000 000

Creating a Direct Access File

357

FILE CONTROL SERVICES

Example l~-7, DIRUNF, creates a file with unformatted, direct
access records. Since the file is unformatted, the record size of
5 does not refer to five bytes but rather to five storage units
where a storage unit is defined as four bytes. Hence each record
is 2~ bytes long. Note that the file dump shows words rather than
bytes.
This is because the data type is INTEGER which has two
bytes for each value. The first record contains five words of
~~~~l
padded with five words of ~~~~~ to pad out the 2~-byte
record.

358

FILE CONTROL SERVICES

PROGRAM II I RUNF

C File DIRUNF.FTN
C

C This task creates a file DIRUNF.DAT
C access unformatted writes.

usin~

direct

I NTEGER
C Open

F~EC ( 10)

fil.€~

OPEN (UNIT=4,N~ME=/DIRUNF.DAT',ACCESS='DIRECT/,
1 TYPE='NEW/,RECORDSIZE=5)
! Itefaults to
! 1.lnformatted

C Promp~ fpr input
WRITE (55125)
FORMAT (' INPUT UP TO 10 DIGITS:')
C Read record from terminal
READ (55110) N,REC
10
FORMAT (Q,10Il)
C Write record to disk
WRITE (4'1) (REC(K),K=l,N)
:1.00
CONTINUE
CALL EXIT
END
25

RI..trJ Sess i on
>RUN IIIRUNF
INPUT UP TO
INPUT UP TO
INOUT UP TO
INPUT UP TO
INPUT UP TO
:::.

10 DIGITS:
10 DIGITS:
10 DIGITS:
10 DIGITS:
10 DIGITS:

11111
2222
3333333333
444
5

Dump of DR2:C305,301JDIRUNF.DAT;13 - File ID 40661,5,0
Virtual block 0,000001 - Size 512. bwtes
000000
000020
()00()40
()00060
()00100
()00120
()00140

000001 000001 000001 000001 OOOOO:!. 000000
000000 000000 000002 ()00002 000002 000002
000000 000000 000000 000000 000003 000003
000003 000003 000003 000003 000003 00O()03
000004 000000 000000 000000 000000 000000
000005 000000 000000 000000 000000 000000
000000 000000 000000 000000 000000 000000

Example 10-7

000000 OOOO()()
000000 000000
OOOOO:~ 000003
000004 O()OOO4
000000 OOO()OO
000000 ()()()OOO
000000 O()()OOO

Creating an Unformatted, Direct Access File

359

FILE CONTROL SERVICES

Example 10-8, SEQUNF, illustrates the SEGMENTED record type, even
though the OPEN does not contain RECORDTYPE = 'SEGMENTED'. This
is because SEGMENTED is the default record
type
for
an
UNFORMATTED, SEQUENTIAL file.
This is the default file type
created by an unformatted WRITE in FORTRAN. Hence, if there had
been no OPEN statement, and the write statement was as shown:
WRITE(l) (REC(K) ,K=l,N)
the file created would default to FOR001.DAT (001 because 1 was
used in the WRITE) and the record type would be SEGMENTED. The
advantage of a file with segmented records is that there . is no
limit to its size, i.e., a single record could be many physical
blocks on a disk. The disadvantage of a file with segmented
records is that it cannot be read by any other high level
languages.

360

FILE CONTROL SERVICES

PI=i:OGI=i:AM SEQUNF

C This task creates a file SEQUNF.DAT usinS seGuentisl

C unformatted writes

BYTE REC(10)

c
c: e)F-en fil.e~

OPEN

(UNIT~l,NAME='SEQUNF.DAT',TYPE~'NEW',

1 FORM='UNFORMATTED',ACCESS='SEQUENTIAL')

C Loop for 5 records
DO 100 1::::1,5

C Prompt for input

WRITE (5,25)
FORMAT ('$ INPUT UP TO 10 DIGITS: ')
C Read record from terminal
READ (5,50) N,REC
50
FORMAT (Q,10Il)
C Write record to disk
WRITE (1) CRECCK),K::::l,N)
:1.00
CONTINUE
CLOSE (UNIT::::l.)
CALL EXIT
C Error routine
900
WRITE (5,950)
950
FORMAT (' THERE WAS A FILE OPEN ERROR')
CALL EXIT
END
25

RIJn Session
>RUN SEQUNF
INPUT UP TO
INPUT UP TO
INPUT UP TO
INPUT UP TO
INPUT UP TO

10 DIGITS:
10 DIGITS:
10 DIGITS:
10 DIGITS:
10 DIGITS:

11111
2222
3333333333
444
5

Dump of DR2:C305,301JSEQUNF.DAT;16 ~ File ID 40675,3,0
Virtual block 0,000001 - Size 512. bytes
000000
000020
000040
000060
000100

000014
000003
000003
000003
000005

000003 000001
000002 000002
000003 000003
000010 000003
000000 000000

Example 10-8

000001
000002
000003
000004
000000

000001
000026
000003
000004
000600

000001
000003
000003
000004
000000

Creating a Segmented File

361

000012
000003
000003
000003
000000

FILE CONTROL SERVICES

Example 10-9, FWRITE, illustrates how a Block I/O routine written
in MACRO can be called by a FORTRAN program. Block I/O is not
directly available in FORTRAN •
• TITLE
.IDENT
.ENABL

FWRITE
lOll
LC

; Enable lower case

; FWRITE is a FORTRAN-callable block lID subroutine.
Subroutine call:

where

IOSB:

ilun
ibuf
isiz
ivb
iefn
iosb
ierr

lo~i~al

unit number

is block buffer ~ddress
is block buffer size (in bwtes)

address of 2-word v.b. number
event fla~
lID status block
a status code
Success
=
-1
SFCHNL ERROR
CANNOT CHANGE RECORD ACCESS
-2 =
WRITES REJECTED
-4
is
is
is
is
+1

.MCALL
.BLKW

WRITES,FDRCSR

MOV
MOV

@2(R5),R2
@iSOTSV,R3

Swstem FCS macros

FWRITE::

CALL
BCS
ADD
FDRCSR
BCS
WRITES
Bes
MOV
RETURN
ERROR1: MOV

Lun
Address of FORTRAN
work area
Get FORTRAN FDB
SFCHNL
Branch on error
ERRORl
Point to FCS FDB
i14,RO
Chan~e record access
,iFD.RWM
to block 1/0
ERROR2
; Branch on error
,4(R5),@6(R5),10(R5),@12(R5),14(R5),iO
Issue write
Branch on error
ERROR3
Return success code
tl,@16(R5)
i-l,@16(R5)

Return FCHNL failure
code

RETURN
ERROR2: MOV

t-2,@16(R5)

Return couldn't
access code

RETURN
ERROR3: MOV

t-4,@16(R5)

Return write rejected
code

chan~e

RETURN
.END

Example 10-9

Creating a File Using Block I/O (Sheet 1 of 3)
362

FILE CONTROL SERVICES

F'ROGRAM BLOCK1

C File BLOCK1.FTN
C

C BLOCK1 creates a file BLOCK.ASC usinS FWRITE, a
C FORTRAN callable subroutine Mritten in MACRO-11.

C Subroutine call:

CALL FWRITE(ilun,ibuff,isize,ivbn,iefn,iosb,ierr)

where

c
c
c

c
c
c
c
c

iltln
ibtlff
isize
ivbn
iefn
iosb
ierr

is the lc)!:.fical unit nl.JlTlbe~ r
is the arra~:l to b(~ written
is ttl(~ ~:d:.:~e of th(-? buffer' (b~ltes )
is a 2 .... integer vbn Chigh,lnw)
is an event flas nl.JlTlbC:-1r
is a 2-irlteser 1/0 statlJ~; block
is an status cod€~ ,
SUCCESS
+1 ::::
-1 $FCHNL ERROR
-2 CANNOT CHANGE RECDF~D ACCESS
WRITE$ RE,JECTED
""
""4

C Task-btlild instructions:

C
C

)LINK/MAP/CODE:FPP BLOCK1,FWRITE,LB:Cl,lJF4POTS-)/LIBRARY

INTEGER WDBUFF(256),IVBN(2)
INTEGER ISIZE,IEFN,IOSB(2),IERR
BYTE IOST(2),CHAR,CHBUFF(512)

c
EQUIVALENCE (IOSB,IOST) ! For accessing liD status
EQUIVALENCE (WDBUFF,CHBUFF) ! For accessing data
DATA ILUN,ISIZE,IEFN 11,512,21
C Get virtual block. :JI:
TYPE 5
FORMAT ('$VIRTUAL BLOCK NUMBER (LOW ONLY) : ' )
5
ACCEPT 6,IVBN(2)
I.)
FORMAT (16)
IVBN(l) .... 0
High VBN " .. 0
C Get character to irlseT't
TYPE 7
7
FORMAT ("$CHARACTER: ' )
ACCEPT 8,CHAR
FORMAT (lAl)
EJ
C Fill buffer with character
DO 9"I=1"ISIZE
CHBUFF(I) .. CHAR
9
"

Example 10-9

Creating a File Using Block I/O (Sheet 2 of 3)

363

FILE CONTROL SERVICES
C Open file
OPEN (UNIT=ILUN,NAME='BLOCK.ASC',TYPE='NEW')
C Call subroutine to write block of data
CALL FWRITE (ILUN,WDBUFF,ISIZE,IVBN,IEFN,IOSB,
lIERR)
IF (IERR .LT. 0) GO TO 200
TYPE 20
20
FORMAT (' 1 BLOCK BEING WRITTEN TO FILE')
C Wait for write to complete
CALL WAITFR(IEFN,IDSW)
IF (IDSW .LT. 0) GOTO 40 ! Check for dir error
IF (IOST(l) .LT. 0) GO TO 100 ! Cheek for lID
C
error on write
WRITE (5,30)IOSB(2)
30
FORMAT (' WRITE COMPLETED,',I6,' BYTES WRITTEN
ITO FILE')
GOTO 300

C
40
45

c
100
110

c
200
210

TYPE 45,IDSW
FORMAT (' DIRECTIVE ERROR. IDSW GOTO 300
WRITE (5,110) IOST(l)
FORMAT (' lID ERROR. lID STATUS
GOTO 300
TYPE
210,IERR
FORMAT (' FCS ERROR, CODE -

',16)

= ',16)

',16)

C
300

CLOSE (UNIT=ILUN)
CALL EXIT
END

Run Session
>RUN BLOCK1
VIRTUAL BLOCK NUMBER (LOW ONLY) : 2
CHARACTER e
1 BLOCK BEING WRITTEN TO FILE
WRITE COMPLETED,
512 BYTES WRITTEN TO FILE
Dump of

- File ID 40701,2,0
Virtual block 0,000001 - Size 512. bwtes

DR2:[305,301]BLOCK.ASC~14

Contains whatever was

previousl~

in that block on the disk

Dump of DR2:[305,301JBLOCK.ASC;14
File ID 40701,2,0
Virtual block 0,000002 - Size 512. b~tes
000000
000020
000040

145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145
145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145
145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145

000760

145 145 145 145 145 145 145 145 145 145 145 145 145 145 145 145

Example 10-9

Creating a File Using Block I/O (Sheet 3 of 3)
364

APPENDICES

APPENDIX A
GLOSSARY
ASYNCHRONOUS SYSTEM TRAP (AST) - A system condition which occurs
as a result of a specified event such as completion of an I/O
request.
On occurrence of the event, control passes to an AST service
routine, and the AST is added to an Executive first-in first-out
queue for the task in which the service routine appears.
ATTACH - Device: Dedicate a physical device
use by the task that requested attachment.

unit

for

exclusive

A task attaches a given device by issuing a QIO directive, or
and WAIT directive, specifying the I/O function IO.ATT.
Region:

QIO

Include a region in a task's logical address space.

A task attaches a region by issuing an Attach Region directive or
by being the target of another task's Send-By-Reference directive.
CLUSTER LIBRARIES - A special setup with shared resident libraries
which permits a task to use the same virtual address window to map
several difficult libraries.
For example, the resident FORTRAN
Object Time System and the resident FCS libr~ry could use the same
virtual addresses.
The run-time routines map and remap the
regions as they are needed, somewhat similar to what happens with
regular memory-resident overlays.
DATASET DESCRIPTOR - A six-word area in the user task containing
sizes and addresses of ASCII data strings, which FeS consults in
order to obtain a run-time file specification.
A dataset descriptor for a given file
is a user-created
structure which contains a file specification for that file.

data

When the filename block associated with a given file does not
contain sufficient information to enable FCS to do run-time file
processing on that file, FCS tries to get the needed information
from the file's dataset descriptor, if specified. Otherwise, Fes
consults the file's default filename block, if specified, in order
to get the desired information.
DEFAULT FILENAME BLOCK - An area in the user task that supplies
FCS with those default values that are needed to build a routine
file specification.

367

When the filename block associated with a given file does not
contain sufficient information to allow FCS to process the file,
and when a dataset descriptor does not contain the needed
information,
then
FCS consults the default filename block
associated with the file to obtain the missing information.
A default filename block may be used to supply a default name,
extension, and/or version for the file.
The MACRO programmer uses
the NMBLK$ macro to create this block at assembly time.
DETACH - Device: Free an attached physical device unit for use by
tasks other than the one that attached it.
A physical device unit can only be detached by means of an IO.DET
I/O function
issued by the task that attached it, or by the
Executive, if the task is terminated with the device still
attached.
Region:

Remove a region from a task's logical address space.

A task detaches a region by issuing 'a Detach Region
by exiting.

directive

DIRECTIVE STATUS WORD - A word in the user task header into which
the Executive returns status information about the most recently
called directive.
After processing a directive, the Executive passes the status of
that directive to the issuing task by putting a success or error
code into the task's Directive Status Word, which is assigned the
global label $DSW.
If $DSW is negative, the Executive rejected
the directive;
if $DSW is +1, the directive was successful.
EVENT FLAG - A software flag which can be specified in a program
r-equest to indicate to the issuing task which of several specified
events has occurred.
There are 96(10) event flags.
Event flags

1 - 32(10) are local
33(10) - 64(10) are system global flags
65(10) - 96(10) are group global flags

Local flags are used for intra-task synchronization, while group
global
and
system
global
flags are used for
inter-task
synchronization and communication.
EXECUTIVE DIRECTIVE - A program request for Executive services.

368

An Executive directive is issued from a FORTRAN program by calling
a subroutine in the system object library.
It is issued from a
MACRO-II program by invoking a macro in the system macro library.
FILE DESCRIPTOR BLOCK (FOB) - The tabular data structure which
provides FCS with information needed to perform I/O operations on
a file.
A task must allocate,
through calls to the FDBDF$
dynamically through the use of run-time macros.

macro,

FILE STORAGE REGION (FSR) - The area in user task which FCS uses
to buffer all virtual blocks read or written during record.
processing.
FCS requires one FSR block buffer for each file to be opened at
the same time for
record I/O. When the task requests a record
that is not in the FSR buffer, FCS reads a virtual block from the
file
into the task's file storage region.
On the other hand, FCS
writes virtual blocks in the file storage region to the file when
a record must be put to the file.
The user task allocates this area by issuing an FSRSZ$ macro.
FILENAME BLOCK - The part of a file's File Descriptor Block which
FCS uses for building, and later using, a file specification.
The filename block contains the file's UFO,
name,
extension,
version number, device name, and unit. When a file is initially
opened, FCS fills
in the filename block from user-supplied
information in the dataset descriptor and/or default filename
block.
I/O STATUS BLOCK - A two-integer array which receives success or
error codes on completion of an I/O request.
If an I/O status
block has been specified in an I/O request, the Executive clears
both words when the I/O operation is queued.
On completion, the
low byte of the first word contains +1 if the I/O was successful,
and a negative error code otherwise.
If the I/O function involved a transfer, the second word contains,
on completion, the number of bytes transferred.
LOGICAL ADDRESS SPACE - The set of all physical addresses to which
a task has access rights.
If a task is running on a mapped system that includes support for
the memory management directives, it may issue directives in order
to manipulate its logical address space at run time.

369

LOGICAL BLOCK - A 512(10) byte (256(10) word) block of data
block addressable volume.

To achieve device independence, each block addressable volume is
organized into logical blocks, numbered 0 to n-l, where n is the
number of logical blocks on the volume.
The mapping of logical blocks to physical blocks is handled by the
driver.
LOGICAL UNIT NUMBER (LUN) - A number associated
device unit during a task's I/O operations.

with

physical

The association of a LUN in a task with a given physical device
may be done by the Task Builder, by the operator using the
REASSIGN command, or at run time by the task, by issuing an Assign
LUN directive.
RANDOM ACCESS - A method of I/O to disk files in which records (or
virtual blocks) are specified by record (or virtual block) number.
Under IFCS, a file must be organized into fixed length
order for a task to do random acc~ss to the file.

records

FCS supports the use of block I/O, in which virtual blocks are
read from, or written to,
the file without regard for the
structure of those blocks. The FORTRAN language does not support
block I/O.
READ/WRITE MODE - An FCS file access method in which the user task
uses the READ$ and WRITE$ macros to do block-structured I/O to a
file.
REGION - An area consisting of one
blocks of physical memory.

contiguous

32.-word

A region may be named or unnamed, but is always assigned a unique
region ID.
A region has an associated protection word which
specifies the access rights a task may have with respect to that
region.
Any task that satisfies the region protection word may
attach a named region, but no task can attach an unnamed region
unless the task has the region ID.
RESIDENT COMMON - A shared region which contains data.
RESIDENT LIBRARY - A shared region containing
functions.

subroutines

and/or

SEQUENTIAL ACCESS - A mode of record access in which the n+lth
record in the file is processed after the nth record in the file.
370

Each record is assigned a record number, and each successive
or PUT causes the record number to be incremented.
SYNCHRONOUS SYSTEM TRAP (SST)
typically occurs as a result
executing task.

GET

A "software interrupt"
which
of an error or fault within the

On recognition of an SST, the Executive aborts the task,
unless
there is an SST vector table to an SST routine in the task.
VIRTUAL ADDRESS - A l6-bit address which may be directly specified
using one of the general purpose registers.
A task specifies a virtual address whenever it uses one of the
addressing modes in executing an instruction. Up to 32K virtual
word addresses may be specified by a task.
On a mapped system, the memory management hardware
maps virtual addresses to real physical addresses.
VIRTUAL ADDRESS WINDOW - A contiguous chunk of
address space.

dynamically

task's

virtual

Each virtual address window in a task begins on a 4K word boundary
and consists of one or more 32(10) word blocks of virtual address
space. Each window has a unique number assigned to it by the
Executive.
Window 0 always maps the task's header, stack, and
code. A task may divide its virtual address, space into eight
windows.
VIRTUAL BLOCK - One of the logical blocks belonging to a file.
Each file consists of one or more logical blocks.
The logical
blocks belonging to a file are called virtual blocks 1, 2, 3, etc.
The mapping of virtual blocks in a file to logical blocks on disk
is performed by the file system.
WINDOW DESCRIPTOR BLOCK (WOB) - A data structure used in a task in
order to represent a dynamically created window.

371

APPENDIX B
CONVERSION TABLES
Table 8-1

Decimal/Octal, Word/Byte/Block Conversions

Words (lS)/Words (8)

Bytes (lS)/Bytes (8)

1/1

2/2

32/40

64/100

1/1

=1024/2000

2048/4000

32/40

=2048/4000

4096/10000

64/100

=4096/10000

8192/20000

128/200

=8192/20000

16384/40000

256/400

16K =16384/40000

32768/100000

512/1000

32K =32768/100000

65536/200000

1024/2000

64K =65536/200000

131072/400000

2048/4000

128K=131072/400000

262144/1000000

4096/10000

Table B-2

Blocks(10)/Blocks{8)

APR/Virtual Addresses/Words Conversions
Words

APR

Virtual Addresses

000000-017776

0-4K

020000-037776

4-8K

040000-0.57776

8-12k

060000-077776

12-16K

100000-117776

16-20K

120000-137776

20-24K

140000-157776

24-28K

160000-177776

28-32K

373

APPENDIX C

FORTRAN/MACRO-11 INTERFACE
CALLING A MACRO-11 SUBROUTINE FROM A FORTRAN PROGRAM

FORTRAN Program Call:
CALL SUBNAM (I,J,K)
MACRO translation:
1.

Set up table of arguments.
RS ----)

Icount=3
Address of I
Address of J
Address of K

Issue subroutine call.
JSR PC,SUBNAM
or
CALL SUBNAM
The FORTRAN Callable MACRO-II Subroutine
; Access i ng :
Argument count = (RS)
;
Argl = @2(RS)
;
Arg2 = @4(RS)
;
;
Arg3 = @6(RS)
SUBNAM: :

RTS PC

; or RETURN

375

CALLING A FORTRAN SUBROUTINE FROM A MACRO-11 PROGRAM
In the MACRO program:
LINK:

A:
B:
C:

.BYTE
• WORD
• WORD
• WORD
.WORD
.WORD
.WORD

3,O
A
B
C

MOV
JSR

iLINK,R5
PC,SUB

3
((}

In the FORTRAN program:
SUBROUTINE SUB (L,M,N)
N=L+M
RETURN
END
NOTE
This method is also used to call a FORTRAN
callable subroutine (written in MACRO-II).
Example 7-3 in the Static Regions module shows a shareable library
LIB.MAC, which contains FORTRAN callable subroutines. USELIB.MAC,
also in Example 7-3, shows a referencing task which calls
subroutines in the library.

376

APPENDIX D
PRIVILEGED TASKS
RSX-IIM systems have two classes of tasks, privileged
and
nonprivileged. The basic difference is that privileged tasks have
certain system-access capabilities that nonprivileged tasks do not
have. These privileges include one or more of the following:
•

Access to Executive routines and data structures

•

Automatic mapping to the I/O page

•

Bypass of system security features.
NOTE
privileged tasks may be hazardous to
ning system.

Use one of the
privileged task.
1.

following

qualifiers

run-

(switches)

build

/PRIVILEGE:0 qualifier (MCR /PR:0)
This task is built in the same way as a nonprivileged task
and does not map to the Executive or the I/O page.
It
can, however, do the following:
•

Bypass file protection

•

Issue directives which require privileges (e.g., Alter
Priority, QIO for Write Logical Break-through)

•

Issue QIOs to write logical blocks to a mounted
volume, regardless of who issued the MOUNT or ALLOCATE
command.

377

/PRIVILEGE:4 or /PRIVILEGE:5 (MCR /PR:4 or /PR:5)
This task has the privileges of a /PRIVILEGE:0 task, plus
it maps to the Executive and the I/O page. The user task
code is mapped beginning at APR 4 or 5, as specified. The
APRs below the one specified are used to map to the
Executi ve, and APR 7 is 'used to map the I/O page.
Use
/PRIVILEGE:4 if the Executive is 16K words or less; use
/PRIVILEGE:5 if the Executive is between 16K and 29K
words.
If the task code extends beyond the end of the
addresses mapped by APR 6, then APR 7 is used to map the
excess code, and the task does not map to the I/O page.

Privileged tasks are discussed in detail in the RSX-llM Internals
Course.
See
also
Chapter 6 on Privileged Tasks in the
RSX-llM/M-PLUS Task Builder Manual.

378

APPENDIX E
TASK BUILDER USE OF PSECT ATTRIBUTES
The Task Builder collects scattered occurrences of
progr~m
sections of the same name and combines them in a single area In
your task image.
The program section attributes control how the
Task Builder collects and places each program section.
See, Chapter 2 of the RSX-llM/M-PLUS Task Builder Manual
complete discussion of program section attributes.
Example of allocation code attributes:
CON (concatenate) versus OVR (overlay)
1.

A.OBJ has Psect Q,CON - length 100(10) words
B.OBJ has Psect Q,CON - length 50(10) words
When task-built:
LINK A,B
Yields 150(10) words in Psect Q
(first A's 100(10) words, then B1 s 50(10) words).

A.OBJ has Psect Q,OVR - length 100(10) words
B.OBJ has Psect Q,OVR - length 50(10) words
When task-built:
LINK A,B
Yields 100(10) words in Psect Q
(A's 100(10) words.
B's 50(10) words are the
same as A's first 50(10) words).

379

for

Example of scope code attributes:
LCL (local) versus GBL (global)
Overlay Tree

B.ODL file:

.ROOT B-*I(B1,B2-B3)
.END

B
Task-build command (for all):
1.

LINK B/OVERLAY__DESCRIPTION

B.OBJ has Psect Q,LCL,CON - length 100(10) words
Bl.0BJhas Psect Q,LCL,CON - length 50(10) words
When task-built:
Yields 100(10) words in Psect Q in root segment B
Yields 50(10) words in Psect Q in overlay segment Bl

B.OBJ has Psect Q,GBL,CON - length 100(10) words
Bl.0BJ has Psect Q,GBL,CON - length 50(10) words
When task-built:
yields 150(10) words in Psect Q in root segment B (in the
segment closest to the root); B's 100(10) words, then
Bl's 50(10) words.
If GBL,OVR instead, yields 100(10) words in Psect Q in the
root segment.
B's 100 words, with Bl's 50(10) words the
same as B's first 50(10) words.

380

B2.0BJ has Psect Q (LCL or GBL) - length l00i10) words
B3.0BJ has Psect Q (LCL or GBL) - length 50(10) words
When task-built:
If CON, yields 150(10) words in Psect Q in overlay segment
B2
(allocation collected, since it is all in the same
overlay segment).
If OVR instead,
100(10) words in Psect Q in overlay
segment B2. B3's 50(10) words are the same as B2's first
50(10) words.

LCL and GBL are used only for overlaid tasks.
In a non-overlaid
task or within an overlay segment in an overlaid task, allocations
are collected when either LCL or GBL is specified, as in Example
3.
Example of FORTRAN COMMONs at Psects:
Psect attributes are always:

RW,D,GBL,OVR,REL

COMMON /RDATA/ I(100)
Macro translation:
.PSECT RDATA,RW,D,GBL,OVR,REL

381

APPENDIX F
ADDITIONAL SH,ARED REGION TOPICS
SHARED REGIONS WITH OVERLAYS

•

Can be referenced using a smaller
task

window

referencing

•

Reuse virtual addresses in the referencing task

•

Must be memory-~esident overlays

•

Have overlay structures which are placed in the .STB file
and later placed in root segment of referencing task.

BUILDING A RESIDENT LIBRARY WITH OVERLAYS

Code and assemble library modules.

Write regular .ODL file to define overlay structure.
•

Typical structure has a null root.

Task-build as a shared region.
•

Only symbols defined or referenced
included in the .STB file.

the

•

Force inclusion of global references into
necessary, usi~g GLBREF option.

root

are

root,

when

Example .ODL file OVRLIB.ODL (Figure F-l):
• NAME
• ROOT
.END

OVRLIB
OVRLIB-*! (H,I-J)

Example task-build command:
)LINK/NOHEADER/MAP/SYMBOL TABLE/OPTIONS OVRLIB/OVERLAY-) DESCRIPTION
Option? STACK=f2J
Option? PAR=OVRLIB:14f2Jf2Jf2Jf2J:4f2Jf2Jf2Jf2J
Option? GBLREF=H,I,J
Option? <RET)

383

Referencing task is created using regular procedure
library OVRLIB.

reference

See section 5.1.4
(on Shared Regions
with
Memory-Resident
Overlays) in the RSX-llM/M PLUS Task Builder Manual for additional
information.

PHYSICAL
MEMORY

VIRTUAL
MEMORY

----~
-- -----

---160000 APR7

__ - - -::.. TIME 1

140000 APR6

~.,."..,~ _

120000 APR5

---

(MAP)"

J
I

-- ---

100000 APR4

60000 APR3
40000 APR2

1'\~~ '}.

INITIAL
LOAD

(.16K WORDS)
G

20000 APR 1

o APRO '--_ _ _ _ _ _ _........_

-- --TK-7773

Figure F-l

A Shared Region With Memory-Resident Overlays
384

REFERENCING MULTIPLE REGIONS IN A TASK
•

Use the usual procedure if:
The number of available APRs in the
is sufficient

referencing

Shared regions are logically independent (one
does not call the other library)
•

If shared regions are built absolute,
addresses) cannot overlap.

Example task-build for
F-2):

logically

independent

APRs

task

library

(and

virtual

libraries

(Figure

Libraries: ARES built absolute at V.A. 160000(8); length 4K
words
BRES built absolute at V.A. 120000(8); length 6K
words
Referencing task: REF
>LINK/MAP/OPTIONS REF
Option? RESLIB=ARES/RO
Option? RESLIB=BRES/RO
Option? <RET>

385

PHYSICAL

MEMORY

VIRTUAL

MEMORY

• •~~m.f-/-J.. _____ _

ARES

140000 APR6

120000 APR5

BRES

II I
---1...-/ __
I
J--160000 APR7

~~~~~~~wJI

100000 APR4 ~~~~~~~~l
60000 APR3
REF

40000 APR2

(16K WORDS)
REF

20000 APR1

o APRO

_ _ _ _ _ _ _'-

----------TK-7772

Figure F-2

Referencing Two Resident Libraries
386

INTERLIBRARY CALLS
One library can call another library
FORRES calls FCSRES
To build libraries with
techniques.

interlibrary

calls,

use

any

these

•

Build as a single combined library, then build referencing
task (Figure F-3).

•

If referenced library does not
F-4):

contain

overlays

(Figure

Build referenced library.
Build referencing library,
library to resolve calls.
Build referencing task,
library.
•

~pecifying

specifying

referenced

only

referencing

If referenced library has overlays (Figures F-5 and F-6):
You must revector interlibrary calls to allow access
to overlay structure and autoload vectors (always in
root of referencing task).
Once revectoring is included, build shared regions and
referencing
task
as
if
regions are logically
independent.

Example task-build commands for each technique follow.
Example task-build command for combined libraries (Figure F-3):
>LINK/MAP/NOHEADER/SHAREABLE:LIBRARY/SYMBOL TABLE->/OPTIONS F4PRES,LB:[1,1]F4POTS/LIBRARY
Option? STACK=0
Option? PAR=F4PRES:120000:60000
Option? <RET)
Referencing task is created using normal
the library F4PRES.

387

procedure

reference

PHYSICAL
MEMORY

.,.,
/.,/

VIRTUAL
MEMORY

.,......., .........
F4PRES

/.,/

----------------~"
160000 APR7

F4PRES

.,.,

(FCSRES)
140000 APR6

(FCSRES)

12K WORDS

120000 APR5

100000 APR4

60000 APR3

USER

40000 APR2

20000 APR1

...

USER
(12K WORDS)

o APRO

TK-7776

Figure F-3

Referencing Combined Libraries

388

Example task~build commands for building one library,
building the second (referencing) library (Figure F-4):

then

>LINK/MAP/NOHEADER/SHAREABLE:LIBRARY/SYMBOL TABLE->/OPTIONS/CODE:PIC FCSRES
Option? STACK=0
Option? PAR=FCSRES:0:20000
Option? <RET>

>LINK/MAP/NOHEADER/SHAREABLE:LIBRARY/SYMBOL TABLE->/OPTIONS F4PRES,LB:[1,l]F4POTS/LIBRARY
Option?
Option?
Option?
Option?

STACK=0
LIBR=FCSRES:RO
PAR=F4PRES:140000:40000
<RET>

Referencing task is created using normal procedure to reference
just the library F4PRES.
F4PRES must be mapped using APRs 6 and 7
because it is built absolute.
FCSRES is mapped at the next
available APR, namely APR 5, because it is built position
independent.

389

PHYSICAL
MEMORY

----------------~-

~--------------~c

.-----------

F4PRES

....
---------

-- -----

FCSRES

------

USER

------------

--TK-7771

Figure F-4

Building One Library, Then Building
a Referencing Library

390

FCS1

FCS2

USER

F4PCLS

.FSRPT::~

.OPEN::

.GET::

CALL .OPEN

,OPEN::j
DISPAT:

JMPTBL::

··
···

.OPEN~

.PUT
.GET
AUTOLOAD ROUTINE, MAPS TO
FCS1, THEN TRANSFERS CONTROL

TK-7777

Figure F-5

Revectoring

See Section 5.2.1.3 (on User Task Vectors Indirectly Resolve all
Interlibrary References) in the RSX-IIM/M-PLUS Task Builder Manual
for additional information on revectoring.
See also Section 5.2.3
on
Examples for commented task-build commands for building
libraries with revectoring.

391

Example task-build commands when revectoring is used
(Figure F-6):
>LINK/MAP/NOHEADER/SHAREABLE:LIBRARY/SYMBOL TABLE->/OPTIONS/CODE:PIC FCSRES/OVERLAY DESCRIPTION
Option? STACK=0
Option? PAR=FCSRES:0:20000
Option? GBLREF=.CLOSE
Option? GBLREF=.CSIl
Option? GBLREF=.CSI2

Option? GBLREF=.WAIT
Option? <RET>
>LINK/MAP/NOHEADER/SHAREABLE:LIBRARY/SYMBOL TABLE:->F4PCLS/TASK:F4PCLS/OPTIONS F4PRES,LB:[l,lTF4POTS->/LIBRARY,LB:[l,l]SYSLIB/INCLUDE:FCSVEC
Option? STACK=0
Option? PAR=F4PCLS:140000:40000
Option? GBLINC=.FCSJT
Option? GBLXCL=.CLOSE
Option? GBLXCL=.CSIl
Option? GBLXCL=.CSI2

Option? GBLXCL=.WAIT
Option? <RET>
Referencing task is created using normal
libraries FCSRES and F4PCLS.

392

procedure

reference

PHYSICAL
MEMORY

VIRTUAL
MEMORY
F4PCLS
(8K WORDS)

160000 APR7

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

.,...,

,........ ~

-~-- --.....
-- ---

F4PCLS

. ,/'

.,/'

.--.,/'

~
140000 APR6 I-----~---__+_e:::::_=:::
FCSl
FCS2
120000 APR5 (4K WORDS) (4K WORDS)

_ ,,\\AE 2

100000 APR4

FCS1

----

60000 APR3

40000 APR2
USER
(12K WORDS)

20000 APR1

o APRO

FCS2

_ _ _ _ _ _ _........._

INITIAL
_LOAD AND MAP

..
--- --

USER

TK·7775

Figure F-6

Using Revectoring When Referenced Library Has Overlays

393

CLUSTER LIBRARIES
•

Allow shared libraries to overlay each other (Figure F-7).
Can use one window for several ,libraries.
Only enough virtual
largest library.

•

address

space

needed

for

initially

mapped

(no

One library can call another.
Generally moving in one direction only.
First library
autoload).

cluster

When a call is made to another library in cluster:

•

Autoload routines save mapping
called library for a call.

context

Original library
subroutine.

for

Revectoring is necessary for
F-5).
Special coding
libraries.

must

be
be

remapped

and

map

return

from

interlibrary

calls

(Figure

included

the

resident

•

Some special rules must
resident libraries.

followed

•

Are useful for FORTRAN tasks using
time system
(FORRES,
F4PRES, or
products.

in
when

building

the resident object
F77RES), plus layered

See Section 5.2 on Cluster Libraries in the
Task Builder Manual for additional information.

RSX-IIM/M-PLUS

Example of task-build command:
>LINK/MAP/OPTIONS/CODE:FPP CLSDEM,LB:[I,I]HLLFOR,->LB:[1,1]F4POTS/LB,LB:[1,1]FDVLIB/LB
Option? CLSTR~F4PCLS,FMSCLS,FCSRES:RO
Option? <RET>

394

the

PHYSICAL
MEMORY

PHYSICAL
MEMORY
I

,,- .,/
.,/

VIRTUAL
MEMORY

"AnI"

160000

APR7

.,/

F4PCLS

VIRTUAL
MEMORY

~~,,~/

1.,,,£'1" ..WhUI

.,/
./

140000- APR6

160000

APR7

140000

APR6

120000

APR5

100000

APR4

LAM, .. L"M']

./
FMSCLS

120000

APR5

W
\.0
U'1

TASK
60000

APR3l

40000

APR2

20000

APR1

FCS2

60000 AP.+

(22K WORDS)

.....

FMSCLS

<:> -<f'(

~..o(O

""
"

(22K WORDS)

40000

APR2

20000

APR1

FCS2

FCS1

"9~;,'-?-

<:> :?(

~..o(o

o APRO

:1<::)

o APRO

"\
TASK

FCS1

-<f'~;,'-?-

-----~
---"\

APR4

'\
100000

F4PCLS

:1<::)

'\
'\

TASK

""
""

TASK

TK-7815

Figure F-7

Cluster Libraries (Sheet 1 of 2)

PHYSICAL
MEMORY

.PHYSICAl
MEMORY

F4PCLS

VIRTUAL
MEMORY

160000 APR7

L_u. _L.h. _~

F4PCLS

VIRTUAL
MEMORY
160000 APR7

140000 APR6

" "~

FMSCLS

W
\.0
0'\

120000 APR5

100000 APR4

«'all >-.

TASK
60000 APR3l

TASK

FCS2
60000 APR3

(22K WORDS)

40000 APR2

20000 APR1

o APRO

'"1?-<{~","

'- ....

(22K WORDS)

"'",
'\
'\

FCS1
40000 APR2

FMSCLS

l/-%"~

FCS2

....
FCS1

"'\

"'"~.)..

~
<>~ (

"'Y'1-,

"'Y',.¢ 0"'Y'<:>

'\
TASK

TASK

'\
'\

"
\

TK-7778

Figure F-7

Cluster Libraries (Sheet 2 of 2)

APPEND,IX G
ADDITIONAL EXAMPLE
The following example REAOF.FTN, should be available on-line,
probably under UFO [202,1].
It is needed for the Tests/Exercises.
Therefore, it is listed here in case it is not available on-line
at your site.

PF~OGRAM

REAIIF

C File READF.FTN
C

C This task sets event fla~ 1 and then reads
C fla~s 1 to 16 and displa~s them. The displa~ is
C a series of 16 di~its, correspondin~ to fla~
C 16 on the left throu~h flaS 1 on the ri~ht.
CAl indicates that the fla~ is set, a 0
C indicates that the fla~ is clear.

IEVF(16),IDSW
C Set event flas 1.
CALL SETEF (l,IDSW)
C Branch on directive error
IF (IDSW .LT. 0) GO TO 1000
C Read the event fla~s into the arra~ ievf. Note
C that in FORTAN, we can onl~ read 1 fla~ at a time
DO 20 1=1,16
CALL READEF (I,IIISW)
C Branch on directive error
IF (IDSW .LT. 0) GO TO 1100
C Check IDSW value, 2 means set, 0 means clear
C Set the ievf value accordin~l~ (1 means set, 0
C Jflf~anS clear)
IF (IIISW .EQ. 2) GOTO 10
IEVF(I):::IDSW
GOTO 20
10
IEVF(I)=1
20
CONTINUE
C Write out fla~ settin.s, startin~ with fla~ 16.
WRITE (5,30)
30
FORMAT (' EVENT FLAGS 16. TO 1. ARE:')
WRITE (5,40) (IEVF(J), J:::16,1,~1)
40
FORMAT (' ',1612)
CALL EXIT
C Come here on directive errors
WRITE (5,1010) IIISW
:1.000
FORMAT (' ERROR SETTING FLAG. ERROR COIlE::: ',15)
:LOI0
CALL EXIT
WRITE (5,1110) IIISW
:l100
FORMAT (' ERROR REAIIING FLAG. ERROR COIlE::: ',15)
:1.110
CALL EXIT
END

Example G-l'

Reading the Event Flags (For Exercise 1-1)

397

APPENDIX H
LEARNING ACTIVITY ANSWER SHEET
Learning Activity 2-1 (Directives)
1.

Either:
a) Do some work, then check the flag by using the
CALL CLREF
(35,IDSW)
directive. Check the DSW.
IS.SET
(=+2) means the flag was set;
IS.CLR (=0) means the flag
was clear, or b) read flags 4 through 64 using RDAF$ and
then test bit 2 of the third word in the buffer to read
flag
35.
In either case, keep doing more specific work
and periodically chec)~' the flag.

The Executive would only set event flag 1 for Task A.
It
would not set Task B's event flag 1;
therefore, Task B
wouldn't realize that the data had been sent.

Local flags are accessible only to the task itself.
They
are specifically provided for synchronization between the
Executive and a task.

Learning Activity 6-1 (Overlays)
(Using Example 6-5)

1.
LIB:

.ROOT-LIB-*! (P-LIB,Q-LIB)
.FACTR LB:[l,l]FOROTS/LB
.END

2.
LINK/MAP ROOT,P,Q,LB:[l,l]FOROTS/LB

399

Learning Activity 6-2
(Using Example 6-6)
1. Overlay tree.
JOBI

JOBXX

I
I
A

I
TOTAL

I
MAIN

2.
LIB:

.ROOT MAIN-TOTAL-LIB-*(A-LIB-(JOBI-LIB,JOBXX-LIB) ,B-LIB)
.FACTR LB:[l,l]FOROTS/LIB
.END

LIB:

.ROOT .MAIN-TOTAL-LIB-*!(A-LIB-! (JOBI-LIB,JOBXX-LIB,B-LIB)
.FACTR LB:[l,l]FOROTS/LIB
.END

LIB:

.ROOT MAIN-TOTAL-LIB-*(A-LIB-(JOBI-LIB,JOBXX-LIB),B-LIB)
.FACTR LB:[l,l]FOROTS/LB
.END

400

EY-006 1E-TP-OOO 1

Programming
RSX-llM
in FORTRAN
Tests /Exercises

Prepared by Educational Services
of
Digital Equipment Corporation

CONTENTS
1

USING SYSTEM SERVICES
Test/Exercise • • • •
Sol ut ion.
••• •

DIRECTIVES
Test/Exercise •
Sol ut ion. • •

5
7

USING THE QIO DIRECTIVE
Test/Exercise • • • •
Solution • • • • • • •

• 21
• 23

USING DIRECTIVES FOR INTERTASK COMMUNICATION
Test/Exercise • • • • • • • • • • • • • • • • • • • • • 35
Solution. • • • • • • • • • • • • • • • • • • • •
• 37

MEMORY MANAGEMENT CONCEPTS.
Test/Exercise • • • • •
Solution • • • • • • •

OVERLAYING TECHNIQUES
Test/Exercise
Solution • • • • •

• 59

• 61

•

••

• • • • • 63

• • • . . • . • • • • . • • • 65

STATIC REGIONS
Test/Exercise •
Sol ut ion. • •

• • • 81
• • • • 83

DYNAMIC REGIONS
Test/Exercise
Sol ut ion. • '.

.....,
iii

•

• • • • 93
• • • • 95

INTRODUCTION
This book contains tests/exercises for two different courses,
Programming RSX-IIM in MACRO and Programming RSX-IIM in FORTRAN.
Most of the questions apply to both courses.
If a question begins
with "In MACRO" or "In FORTRAN", that question applies only to the
specified course.
Solutions are provided for all tests/exercises.
Where it is appropriate, separate solutions are provided for MACRO
and FORTRAN.
Solutions which involve programs should also be
available on-line.
Check the Student Guide in the Student Workbook for
course for information on how to use the tests/exercises.

your

Using System Services
TEST /EXERCISE
1.

Match the function with the type of
perform it.
Function

system

service

used

Type of System Service

a. The tasks send data
back and forth to
each other

1. System and task information

b. The tasks read data
from a file on disk

3. Task communication/coordination

c. The tasks get input
from an operator
at a terminal

4. I/O to peripheral devices

2. Task control

5. File and record access

6. Memory use

Draw a figure to illustrate a method
service through the Executive.

providing

system

Using System Services
SOLUTION
1.

Match the function with the type of
perform it.
Function
3

5
4

system

service

used

Type of System Service

a. The tasks send data
back and forth to
each other

1. System and task information

b. The tasks read data
from a file on disk

3. Task communication/coordin-

c. The tasks get input
from an operator
at a terminal

4. I/O to peripheral devices

2. Task control

ation

5. File and record access

6. Memory use

Draw a figure to illustrate a method
service through the Executive.

See Figure I-lor 1-2

providing

system

Directives
TEST IEXERCISE
1.

In MACRO-II
a.

Modify the task READF to use the $C form of the Read Event
Flags directive.

Modify the task READF to use the $S form of the Read Event
Flags directive.

In FORTRAN, modify the task READF
numbered flags from 1 to 15(10).

Modify WFLAG and SFLAG to use a global event flag instead of a
group global event flag.
Omit any unnecessary code in the
tasks. Check with your instructor to find out which event
flag to use.

Write a task which does some work and periodically checks a
group global event flag.
Have it display a message and exit
when the flag has been set. Write another task, or modify
SFLAG to set the flag.

Add a requested exit AST routine to WFLAG.

In MACRO-II, add an odd address trap SST routine to the task
SST.
Include an instruction which causes the trap to occur.

set

all

the

odd

Directives
SOLUTION
l.a

.TITLE
.IDENT
.ENABL

2
3
4

1='

F:i.le

}

6
"7
B
(1

F~EADF

lOll
LC

Enable lower case

LEX2:I.A. MAC

Modified to use the $C form of the Read All Event ;;EX
Fla~.:j~5 directive

This task starts up, sets event flas Iv reads the
event flaSs, moves them into reSisters RO-R3 and then
exits~ It uses the $ form of the directive calls.

:1.1
:1.2

Th€-~

of:l. a~.~s

are

:J. ~5
:I.e>

:1.7

:I.B
19
2()
'?l

; ....

'2:~

follow~):

r(~tl.Jl"'ned

a~;;

word
wor'd
word
word

event flags 1-:1.6

0
1

.".
"

.. event fl,3ss :1.7-32

2 .- event flags ~53""48
ev(:'nt flags 49-64
3

.MCALL

RDAFSC,SETFS,EXITSSvDIR$; Swstem macros

.BLKW

; ; EX

2~5

BUFF:

Buffer for event flas
vall.Je~;)

'11:"
•.
_ ,J

26
2:7

SETF:

SElFS

rtF'B for Set Evel-It, Flag
di rf~ctive

STAF~T :

3~5

F~[lAF$C

R4
ISETF
ERR1
BUFF

Clear errrJr' counter

:32

CLR
DIR$
BeS

2fJ

29
3()

Sf.~t

34
~5~3

BeB

EI~R2

:36

MOV
MOV
MOV
MOV
lOT

BUFF"RO
BUFF+2,R1
BUFF+4,R2
BUFF+6,R3

37
313
3(7

; Come here on directive

INC
INC

R4
R4

MOV
lOT

$DSW"RO

413

.END

START

4c~

.. I

46
47
4(J

:
ERR1:
EF~R2

1'1,39 1

r€~9isters

TraF' and displaw
resisters

4':>
43
414

eVf.~nt

Branch 0 .... dir errOl'
Read th€-~ event, fla9s;;EX
( 1 - 64) •
Branch on dir er r'or
Move the event, flas
values into the

error~)

R4=2 for ,'ead err'or
R4=1 for set event
fla9 error
Error code into RO
Trap r:md displaw the
register's

Directives
SOLUTION
2.

:J.

.'")
A..

3
4
5
6
l
8
9
10
:1.1
12

13
:L4

1 ~)
:L6
17
:I.B
19
20

21..

,") ")
4_ .,~.

23
24
'")c·
A·•• ,J

2(~)

27
28
2.9

30
3:1.

32
33

34
:·55
36

37
38
J9

40
41
4")
..:.
43
44

READF.FTN

C File lEX22.FTN
C
C Modified for exercises. Set odd numbered
C

fla~s.

! !EX

C This task sets event fla~ 1 and then reads
fla~s 1 to 16 and displa~s them

C
C

IEVF(:L6)"IDSW
! !EX
C Set odd event fla~s+
DO 5 J(~-::1,,1!5,.2
! !EX
CALL SETEF (K,IDSW)
! !EX
C Branch on directive error
IF (IDSW .LT. 0) GOTO 1000
! !EX
5
CONTINUE
r Read the event fla~s into the arraw ievf. Note
C that in FORTAN" we can onl~ read 1 fla~ at a time
DO 20 1=1,16
CAll READEF (I"IDSW)
C Branch on directive error
IF (IDSW .IT. 0) GOTO 1100
C Check IDSW value" 2 means set, 0 means clear
C Set the ievf value accordin~l~ (1 means set, 0
C means cl€~ar)
IF (IDSW .EQ. 2) GOTO 10
IEVF( I )::::IDSW
GOlD 20
10
IEVF(I)=l
20
CONTINUE
C Write out fla~ settin~s" startin~ with fla~ 16.
WRITE (5,,30)
30
FORMAT (' EVENT FLAGS 16. TO 1. ARE:')
WRITE (5,,40) (IEVF(J)~ J=16,,1,-1)
40
FORMAT (' ~,16I2)
CALI... EXIT
C Come here on directive errors
1000
WRITE (5,,1010) IDSW
1010
FORMAT (' ERROR SETTING FLAG. ERROR CODE - ',15)
CALL EXIT
1100
WRITE (S"il10) IDSW
1110
FORMAT (' ERROR READING FLAG. ERROR CODE = '"IS)
CALI... EXIT
END

Directives
SOLUTION

PF~()GF~AM

WFLAG

("'

3
4
5

6
7
8
9

10
1.1
12

1 ~~
14

:L ~s
16
17
18
19

C FILE LEX23A.FTN
C
C Modified to use event fla~ 35(10)
" EX
C
C This task creates the Sroup slobal event flass, and

C then clears event fla~ 65. and waits for it to be set.
C When the fiaS is set~ it writes a message and exits
C
C Install and run instructions:
C
C
Run WFLAGy then run SFLAG. At least one of the
C
tasks must be installed, or else the RUN command
C
will tr~ to install both tasks under the same
nalTlf-:.' (TTnn)
C
C
WRITE (:7;,:20)

FORMAT (' CLEAR AND WAIT FOR EF 35. TO BE SET')! !EX
CALL CLREF (35yIDSW)
, !EX
IF (IDSW .LT. 0) GOTO 1100
CALL WAITFR (35,IDSW)
, 'EX
IF (IDSW .LT. 0) GOTO 1200
WRITE (~;,30)
30
FORMAT (' EF 35. HAS BEEN SET. FWAIT WILL NOW EXIT')
, !EX
r'
CALL EXIT
C Error processins

30
31

1100
1110

20
21
22
2:~

24
~~~ ~:j

26
27

32
~33

:1.200
12:J.O

37
38

1
3
4
.::'
,.J

6
7
8
9
10

11
12
13
14
:1.5

WRITE (5~1110) IDSW
FORMAT (' DIRECTIVE ERROR CLEARING EVENT FLAG 35.
1 DSW :::: " IS)
, 'EX
CALL EXIT
WRITE (5,1210) IDSW
FORMAT (' DIRECTIVE ERROR WAITING FOR EVENT FLAG
1 35. DSW :::: ',IS)
CALL EXIT
END
.TITLE
.IDENT
.ENABL

SFLAG
1011
Enable lower case

L.C

FILE LEX2:3B. MAC
Modified to use event flas 35.
This task sets event flas 65.
It assumes that the
Sroup slobal event flass have alreadw been created.
Assemble and task-build instructions:
MACROILIST LB:[:L,:LJPROGMACS/LIBRARY,dev:CufdJSFLAG
LINKIMAP SFLAG,LB:C1,lJPROGSUBS/LIBRARY

Directives
SOLUTION

.TITLE
.IDENT
.ENABL

1
'")
A..

4
5
6

LEX24

lOll
LC

Enable lower case

FILE LEX24 + M(~C

7
8
9
10
11

This pro~ram creates the ~roup ~lo&al event fla~s,
clears event fla~ 65., does some work and periodicallw
cehcks event fla~ 65+ When the fla~ is set it writes a
messa~e and exits.

12
13
14

Assemble and task-build instructions:
MACRO/LIST/OBJEcr:WFLAG LB:C:I.,lJPROGMACS/LIB-,;EX
RARY,dev:CufdJLEX24
;;EX
LINKIMAP WFLAG,LB:[1,1JPROGSUBS/LIBRARY

1. ~5
:1.6

17
Install and Run instructions:

1.8
19
20

21
,.),.)

A*- ....

2~3

; --

Run WFLAG, then run SFLAG. At least one of the
tasks must be installed, or else the RUN command
will trw to install both tasks under the same
name, TT .... n.
.MCALL

:~5

26
27

EXITSS,WTSESC,CLEFSC,CRGFSC;

S~stem

;

.MCALL

TYPE

CLR

I~O

ITlc~C T'OS

SuPp lied mac T'O

28
::.~ <?

31
32
33
3~l

36
37
38
39

40
41
4':>
43
44
45
46

47
48
4(7

~)TAF~T :

RO used to identif~
the er'ror
TYPE
<LEX24 IS CREATING THE GROUP GLOBAL EVENT FLAGS>
Create ~roup ~lobal
CRGFSC
€·~vent f I (!~9S
, Branch on directive ok
BCC
OK
If ~roup ~lobal event fla~s alread~ exist,
Just displa~ messa~e and continue
CMP
SDSW,*IE.RSU
Check for efa alread~
in e~d.5tence
ERRl
Branch on an~ other
BNE
;
di r error'
TYPE
<GROUP GLOBAL EVENT FLAGS ALREADY EXIST>
<CLEAR EF 65. WORK UNTIL IT IS SET>
0/\ :
TYPE
Clear event fla~ 65.
CLEFSC 65.
Branch on directive
BCS
E/~/~2
p

e r rcn"'

AGAIN:
CLR
; Loop 2**16
LOOP:
INC
BNE

1:;:1
tilTle~:;,

Clear counter
then check

r~ 1-

LOOP

;,EX
;;[X
Increment counter ;;EX
Not ~et c~cled, loop;;EX
a~ain
;;EX

fla~

Directives
SOLUTION

(',
1.Il::'
19

:1.0
C

2:1.

~JRITE

'')'')

A'- A..
")':1'
""._ \.0 ••

24
26
27
28
29
30
31
32
33
34

35
36
37
39
40

41
42

WI~:ITE C:=;,10)
FORMAT (' LEX24 IS CREATING THE GROUP GLOBAL EVENT FLAGS')
! !EX
CALL CRGF (,IDSW)
IF (IDSW .L1. 0) GOTO 900
(~:;,20)

FORMAT (' CLEAR EF 65. WORK UNTIL IT IS SET')
CALL CLREF (65,IDSW)
IF (InSW .L1. 0) GO TO 1100
22
DO 25 K=1,65535
EX
25
CONTINUE
EX
WRITE (5,28)
EX
28
FORMAT (' COUNTER HAS CYCLED')
EX
CALL READEF (65,IDSW)
EX
IF (IDSW .L1. 0) GOTO 1200
EX
IF (IDSW .NE. 2) GOTO 22
EX
WRITE (5,30)
30
FORMAT (' EF 65. HAS BEEN SET. LEX24 WILL NOW EXIT')
CALL EXIT
C Error processinS
C

C Check for code of -:1.7, meaninS fla~s alreadhl exist
IF (IDSW .NE. -:1.7) GOTO 1000
C In that case, Just disla~ a messaSe and continue.
WRITE <:5,9:1.0)
9:1.0
FORMAT (' GROUP GLOBAL EVENT FLAGS ALREADY EXIST')

900

44
4~:5

C Here for fatal errors, di5pla~ messaSe and exit
:I.()OO
WRITE (5,:1.010) IDSW
FORMAT C' DIRECTIVE ERROR CREATING GROUP GLOBAL
t010
lEF/"n. D~:)W :::: I,I~:5)
Ci~1...1... EXIT
WRITE (5,1:1.10) IDSW
:1.:1.00
FORMAT (' DIRECTIVE ERROR CLEARING EVENT FLAG 65.
:1.:1.10
:L DSW :::: I, I~7;)
Ct.LL EXIT
WRITE (5,:1.210) IDSW
:1,200
1:::,:::1.0
FORMAT (' DIRECTIVE ERROR READING EVENT FLAG
:J. 6:~; + DSW :::: " I ~D
! ! EX
CALI... EXIT
END

Directives
SOLUTION
WTSE$C

52
BCS

5:5

54
55
56
57

65.

Wait for event fla~ 65
to be set
ERR3
Branch on directive
error
(EF 65. HAS BEEN 8ET. WFLAG WILL NOW EXIT>

TYPE
EXIT$S
; AST Service routine
REXAST: TYPE
<WHY ME? NOT THIS TIME!!> ;

59
60
61

ERR3:

ASTX$S
INC

ERR2:

INC

ERR1. :

INC

ERRO:

MOV

;;EX
message
;;EX
AST exit to return ;;EX
RO = 3 if error on
wait for dir
RO = 2 if error on
clear flas dir
RO = 1 if error on
create Sroup fla~s dir
Place DSW in Rl, leave
RO=O for specif~ ;;EX
reauested exit AST err
Trap and dump reSisters

63
64
6~5

66
67

68
69
70

71
1

2
3
4
5

6
7
8
9
10
11

12
13
14

15
16
17
l8
19

20
21

23
24
26
27
28

29
30
31

lOT
.END

T~pe

STAr~T

PROGRAM WFLAG
C
C FILE LEX25.FTN
C
C Modified to include a Reauested Exit AST
! !EX
C
C This task creates the group global event flags, and
C then clears event flag 65. and waits for it to be set.
C When the flas is set, it writes a message and exits
C
C Install and run instructions:
C
r
Run WFLAG, then run SFLAG. At least one of the
C
tasks lTIust be in~,;t,alled, or else t,fle F,LJN command
C
will tr~ to install both tasks under the same
C
name (TTnn)
C
EXTERNAL REXAST
! !EX
C Set UP Reauested Exit AST
! !EX
CALL SREA (REXAST~ID8W)
! !EX
IF (I DSW .1... T. 0) GOTO 950
! ! EX
WrnTE (5"lO)
10
FORMAT (' WFLAG IS CREATING THE GROUP GLOBAL EVENT FLAGS')
CALL CRGF (,IDSW)
IF (ID8W .LT. 0) GOTO 900
WI:;;ITE (5,20)
15
20
FORMAT (' CLEAR AND WAIT FOR EF 65. TO BE 8ET')
CALL CLREF (65yIDSW)
IF (ID8W .LT. 0) GO TO 1100
CALL WAITFR (65~IDSW)
IF (IDSW .LT. 0) GOTO 1200
WRITE (5,30)

Directives
SOLUTION
6.

.TITLE
.IDENT
.ENABL

1
'')

.:0.

SST
lOll
LC

Enable lower case

4
5

FIl.E LEX26.MAC

6
?
8

Modified to include an odd address trap

This task sets UP an SST vector table to handle SST's
for BPTy lOT, and odd address traps. It then executes
instructions to cause these traps to occur. In each
SST routiney a messa~e is displa~ed and then the task
continues. Finall~, a TRAP instruction is executed.
Since no user SST routine is specified for TRAP, the
Executive aborts the task.

:to
1,1
12
:t3
14
:L5,
16
1,7
1.8
1.9

Assemble and task-build instructions:
MACRO/LIST LB:rl,lJPROGMACS/LIBRARY,dev:[ufdJLEX26
LINK/MAP LEX26yLB:rl,:t.JPROGSUBS/LIBRARY

20
21

.MCALL
.MCALL

'')'')
.\••• .A...

23
24
25

STAr.:T:

SVTK$C
BPT
TST

29
~50
~5 :t.
~~2
3~~

CLR

34
35
~56

37
38

SVTK$C,EXIT$S
TYPE

External s~stem macros
External supplied macro

;

VTABLE: • WORD

26
27
28

;;EX

NEW:

lOT
EXIT$S
TRAP

ODDTRP,MPTVIO,BPT,IOT ; SST vector table
; ;EX
VTABLE,4
Have E~·~ecuti ve set
SST table
BPT instruction
1
Test location 1, ; ;EX
; ;EX
causin~ an odd
; ; EX
addr trap
120000
Clear l()cation 120000,
caus:in~.:t a JTlemOT'~
protect violaticm
lOT instruction
J.JJ~

E~·dt

TRAP instruction

~5(~

Using the QIO Directive
TEST IEXERCISE
1.

Modify SYNCHQ or ASYNCQ to write prompting text
SOME TEXT:
") before issuing the read.

In MACRO-II, modify NUMER, replacing the error handling code
with
code which writes out an error message plus the
appropriate status code.
Refer to SYNQER for
sample error
messages.

Modify NOECHO to use one QIO directive to both write
the
prompt and read the input.
Also, have the read timeout if no
key is struck for 20(10) seconds, in which case,
display a
timeout 'message and ex it.

Write a task which prints a message on every terminal
in the
system.
The task should break through any pending I/O at the
terminal.
(Note:
as
This task must be task-built
a
privileged task,
using
the IPRIVILE~ED:0 qualifier in the
task-build command;
/PR:0 in MCR)

(e.g.,

"TYPE

Using the QIO Directive
SOLUTION
1.

.TITlE
.IDENT
.ENABL

2
3
4

5
6
7
8
9
10
11
12

13
14
15
16
17
18
19
2()

SYNCHQ
lOll
lC

Enable lower case

FILE LEX31.MAC
Modified to displaw promptins text
This task reads a line of text from the terminal,
converts all upper case characters to lower casey and
prints the converted messaSe back at the terminal. It
uses s~nchronous Qla directives.
.MCALL

QIOWSC,QIOWSSvEXITSS

EwteT'nal
macros

s~~)t(:'m

IOSB:
BUFF:
F'RMf'T:
LPRMF'T

.BtKW
2
110 status Block
.BlKB
80.
; Text buffer
.ASCII ITYf'E SOME TEXT: I ; Prompt
=.-F'RMPT
Len~th of prompt
.EVEN

START:

CLR
ClR

R5
R4

QIOWSC

IO.WVB,5,1,~IOSB,,<F'RMPT,lF'RMPT,40>

; ; EX
; H·:X
; ; EX

22
23
24

Error Count
Error indicator - 0
means directive error
(DSW in R3), ne~
means liD error
(liD status in R3)

25
26
27

28
2(1
30
31
32
33

34
35
36
37
38
39

40
41
42
43
44
45
46
47
48
49
50
51

Displa~ prompt
j;EX
ERR3
Branch on dir error;;EX
10SB
Check for liD error;;EX
ERR3A
; Branch on 1/0 error;;EX
IO.RVB,5,1,vIOSB,,<BUFF,80.> ; Issue
read
BCS
ERR1
Branch on dir error
TSTB
rOSB
Check for liD error
BlT
ERR1A
Branch on liD error
IOSB+2,RO
MOV
Get count of characters
t~ped in
ClR
R1
Offset into buffer to
character
lOOP:
CMPB
BUFF(Rl),t'A
Check for upper case
ASCII character
BLT
NEXT
Branch if below ran~e
CMPB
BUFF(Rl),t'Z
BGT
NEXT
Branch if above ran~e
Here if upper case, move to re~ister R2 and convert
MOVB
BUFF(Rl),R2
Move to register
ADD
t32.,R2
Convert to lower case
MOVB
R2,BUF~(R1)
Replace in messaSe

BCS
T8TB
BlT
QIOWSC

Using the 010 Directive
SOLUTION
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

25
26
27
28
29
30
31,

32
33

34
35
36
37
38
~~9

40
41
42

43
44
45
46
47
48
49
50

PROGRAM ASYNCQ
C
C FILE LEX31.FTN
C
C Modified to displa~ promptin~ text
! !EX
C
C This pro~ram reads a line of text from the terminal,
C converts an~ upper case characters to lower case and
C prints the converted message back at the terminal.
C It uses asynchronous aIDs and an event flas for
C synchronization.
C'
BYTE IOSB(4),IBUF(80)
DIMENSION IPAR(6),K(10)
EQUIVALENCE (NUM,IOSB(3»
REAL PRMPT(4)
! !EX
DATA PRMPT I'TYPE',' SOM',,'E TE','XT: '/!!EX
DATA IOWVB/ 110001
DATA IORVB/ R I04001
DATA IVFC/·401
C Set UP values for the ala
IUNIT=5
! !EX
C Set UP for oro to issue prompt
CALL GETADR(IPAR(l),PRMPT(l»
! !EX
! ! EX
IF'AR(2):::16
IPAR(3):::·40
! !EX
! !EX
C Issue as~nchronous write
! !EX
CALL aIO(IOWVB~IUNIT,5"IOSB,IPAR,IDS)
! !EX
IF (IDS .LT. 0) GOTO 780
! !EX
CALL WAITFR(S,IDS)
! !EX
IF (IDS .LT. 0) GO TO 785
! !EX
IF (IOSB(l) .LT. 0) GOTO 790
! !EX
C Set UP for read
IPAR(3):::0
! !EX
IPAR(2):=80
C Get the address of the liD buffer
CALL GETADR(IPAR(I),IBUF(l»
C Issue the 010
CALL QIO(IORVB,IUNIT,5~,IOSB,IPAR,IDS)
C Check the directive status
IF (IDS .LT. 0) GO TO 800
C Do some work while 1/0 operation is being performed
DO 50 1=1,10
K(I)=64*1
50
CONTINUE
C
Wait for I/O to complete
CALL WAITFR(S,IDS)
C
Check directive status
IF (IDS .LT. 0) GO TO 805
C Check the liD status
IF (IOSB(l) .IT. 0) GO TO 810
8

Using the 010 Directive
SOLUTION
2.

.TITLE
.IDENT
.ENABL

2
3

4
5
6
7

Modified to include error messa~e code
This task does a simple addition and outputs the
results. It demonstrates the use of $EDMSG for
formattin~ messa~es with numeric data

10
11

14
15

.MCALL
.MCALL
.NLIST

Q10W$,EXITSS,DIRS ; S~:lS tem mac T'OS
; S~stem macros ;;EX
QIOWSS
BEX
Do not list binar~
eNtensions

16
17

; Data

.WORIt

19
20
21

.WORIt
.BLKW

22
23

OUT:

QIOW$

10SB:

.BLKW

24
25
26
27

;

BUF:
FMES:

39
40
41
42
43
44
45
46
47
48
49

output messaSe

; liD status block

; Set UP for SEDMSG

~~9

37
38

;

31
32
33
34
35
:36

1st addend and start
of ar~ument block
2nd adder,d
Location for SIJm
;

'28

~50

Enable lower case

FILE LEX32.MAC

8
9

12
13

NUMER
lOll

.BLKB
.ASCIZ

Output buffer

80.

IXD. WAS ADDED TO %D., GIVING XIt.1

FoY'mat stT'in~
; Set UP for error messa~es usinS SEDMSG
; ;EX
.EVEN
ARG:
• Bl.KW
1
Ar~ument block;;EX
FMT1It:
.ASCIZ IDIRECTIVE ERROR ON WRITE, DSW = XDI ;;EX
FMT1I:
.ASCIZ '1/0 ERROR ON WRITE, liD STATUS = XD';;EX
; ; EX
.EVEN

START:

.LIST
.EVEN
MOV

A,C

ADD

B,C

List binar~ e}·,tens ions
Move to word bO'.Jnda r~1
Move 1st addend to Sl..l",
word
Add 2nd addend to form
sum

BEX

Set UP for call to $EDMSG
MOV
IBUF,RO
IFMES,R1
MOV
tA,R2
MOV
CALL
SEDMSG

Addr of output buffer
Addr (Jf format strins
Addr of ar~ument block
Make call, ctlaracter
count returned in R1

Using the 010 Directive
SOLUTION

1
2
3
4
5
6
7
8
9
10
1.1
1 ~!
13
14
15
16
17
18
19
20
21

.TITLE
.IDENT
.E:NABL

NO ECHO
/01/
LC

Enable lower

ca~e

FILE l.EX33.MAC
Modified to combine aIOs and include timeout

;;EX

This task writes a prompt and then issues a aIO to read
from the terminal without echo.
It then displaws the
word which was entered.
Assemble and task-build

instr~ctions:

MACRO/LIST LB:[1,lJPROGMACS/l.IBRARY,dev:CuicJLEX33
LINK/MAP LEX33,PROGSUBS/LIBRARY
.MCALL
.MCALL

EXIT$S,aIOW$C,aIOWSS; S~stem macros
DIRERR,IOERR
; SUPplied macros

.NLIST

BEX

Data

::~:~

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
4C"
.. I
46
47
48
49
50

Don't list of binar~
e~·{tens i otlf:>
.ASCII /SECRET WORD: /
ProlTlPt messese
MES:
Len!:jth of PT'omF,t
LEN
.-MES
=
BUFF:
.ASCII <15>/NO LONGER A SECRET WORD: /
; Prf:~cedins T'emark
; Len~th of Remark
.BLEN
.-BUFF
; Input buffer
• BLKB
80 •
BUF:
.ASCII /READ TIMED OUT/ ; Timeout message ; ;E:X
TMOMS:
; ;EX
LTMOMS ==. --TMOMS
.E:VEN
Word align for IOSB
10SB:
0
.WORD
IOSB is b,'c)ken i.nto
LENT:
.WORD
0
two pc3rts for
convenience.
; Define functions locall~ to allow us of an assignment
; statement to shorten directive statement
IO.RPR =004400
Define functions
TF.RNE =20
TF • TMO ==200
IO.FNC =<IO.RPR!TF.RNE!TF.TMO>
aIO function code
.LIST BEX
List binar~ extensions
!

Code
;
START:

aIOW$C

Bes

;

IO.FNC,5,1"IOSB,,<BUF,80.,2,MES,LEN,44>
Issue read after ;;EX
prompt
;;EX
DERR:I.
Branch on dir error

Using the QIO Directive
SOLUTION
PROGRAM NOECHO

2
3

4
:5
6

?
8
9

10
11
12
13
14
15
16
17
:L8

19
20
21
22
23
24
25
26
27

28
29

30
31
32
33
34
35
36
37

38
39

40
41
42
43
44
45
46
47
48
49
50
51
~j2

C File LEX33.FTN
C Modified to use read after prompt and to timeout I lEX

C This task prompts for input, reads it without echo and
C then skiPS to the next line 'and displa~s the input
C text and exits.
C

BYTE
BUFF(80),IOSB(4),CR(1)
INTEGER PARM(6)
REAL
PROMPT(4)

, 'EX

C
DATA

IOFNe

Q I O ! 'EX
function! 'EX
,code
, 'EX
C
DATA
ISTMO 121
Timeout "EX
s tatl.Js I! EX
C
CR IU151
CarriaSe return character
DATA
DATA
PROMPT I'SECR','ET W','ORD:','
'I
, Text
, ! EX
C
C Set UP the lID parameter list
CALL GETADR (PARM(1),BUFF(1»
buffer address
PARM(2) - 80
Buffer lensth
PARM(3) = 2
Timeout = 2
EX
C
10 sec
EX
CALL GETADR (PARM(4),PROMPT(1»
Prompt addr
EX
PARM(5) = 13
Prompt lensth !EX
PARM(6) = 844
Vertical
'EX
C
, format contr 'EX
C Issue read no echo, read after prompt, with timeout
EX
CALL WTQIO (IOFNC~5,1"IOSB~PARMvIDS)
IF (IDS .LT. 0) GO TO 100
Dir error?
IF (IOSB(l) +LT. 0) GO TO 110
1/0 error?
C Check for timeout
IF (IOSB(l) .NE. ISTMO) GOTO 1
Branch if no I ! EX
c
tilTleolJt
, 'EX
Displa~
, 'EX
TYPE *,'READ TIMED OUT'
C
messaS€~
, 'EX
CALL EXIT
and exit
, 'EX
WRITE (5,2) CI:;:,(BUFF(I),I=1,IOSB(3»
, Echo input
1
FORMAT (' ',A1,'NO LONGER A SECRET WORD: ',80Al)
CALL EXIT
I· 46201

C Error conditions
C

lOO
110

TYPE *, 'DIRECTIVE ERROR ON READ. STATUS = ',IDS
CALL EXIT
TYPE *, 'I/O ERROR ON READ. CODE = ',IOSB(l)
CALL EXIT
END

Using the QIO Directive
SOLUTION
1
2
3

PROGRAM LEX34
C+
C FILE LEX34.FTN

C Solution to Module 3, Lab Exercise 4

C Task does a write breakthrou~h to all terminals.
C
C Task-build with IPRIVILEGED:O aualifier
CINTEGER TTUNIT,DSW
DATA TTUNIT/OI
! First output to TTO:
INTEGER PARAM(6),lOSB(2)
BYTE 6UCCOD(2)
. ! 110 sticcess codes
EQUIVALENCE (SUCCOD,IOSB) ! First bytes of 10SB
INTEGER IEIDU
! Mnemonic for Mlilesal
Device or Unit- DSW code
DATA IEIDU/-·991
1/0 function code
INTEGER lOFCOD
mnemonic
C
Write lo~ical block,
DATA lOFCOD/-5011
write breakthrou_h,
C
and restore cursor
C

8
9
10
11
12
13

14
15
1,6
:L 7
18

19
20
21
'")'")
A"- AO_

23
24

25
26
27

28
29
30
31
~52
~~~5
:~4

36
37
38
39
40
41
42
43
44

45
46

47
48

49
50
51

c
C Load parameter list
CALL GETADR(PARAM(l),'HELLO THERE')
PARAM(2) ::: 11
! Len~th of strin~
PARAM(3) ::: -40
! Blank for carr. ctrl.
CALL ASNLUN(4,'TT',TTUNIT,DSW)
Assi~n LUN 4 to
10
c
TTrd
IF (DSW.LT.O) GOTO 900
CALL WTQIO(IOFCOD,4,1,,10SB,PARAM,DSW)
IF (DSW.LT.O) GOTO 910
! Directive error
IF (SUCCOD(1).NE.1) GOTO 920
! 1/0 error
TTUNIT = TTUNIT+1
GOTO to
C
r Error from ASNLUN. If ASNLUN failed because of ille~al
C unit number, must have passed the last terminal.
Exit.
900
IF (DSW.Ea.IEIDU) CALL EXIT
TYPE 905,DSW
! Other error
905
FORMAT (' ERROR ON ASNLUN. DSW ::: ',16)
CALL EXIT
910
TYPE 915,TTUNIT,DSW
915
FORMAT (' DIRECTIVE ERROR ON aIO TO TT',02,':'1
1 ' DSW ::: ',16)
CALL.. EXIT
TYPE 925,TTUNIT,SUCCOD(2),SUCCOD(1),IOSB(2)
920
FORMAT (' liD ERROR ON aIO TO TT',02,':'1
925
1 ' liD STATUS BLOCK::: ',14,' ,',14,' 1',16)
CALL EXIT
END

Using Directives for Intertask Communication
TEST IEXERCISE
1.

Modify RECVl and SENDl to synchronize using Suspend and Resume
directives instead of event flags.

Modify RECV2 so that the display includes
sending task in addition to the data.

Write another sender task to send data to RECV2.
Modify the
receiver so that
it receives data from ydur task only, not
from SEND2.

Modify SPAWN so that
it spawns CLI ••• ,
MCR ••• ,
or
••• DCL
several different times and sends a different MeR or DCL
command line each time.
Display the exit status after each
command- executes.

Write a parent task and an offspring task.
Have the parent
spawn the offspring.
Have the offspring emit status to the
Have
parent every five seconds for 30 seconds and then exit.
the parent display each status value.
Optional:
Use an AST
routine in the parent for synchronization.

the

name

the

Using Directives for Intertask Communication
SOLUTION
1.

.TITL.E
.IIIENT
.ENABl

1
2
3
4
5

SEND1
lOll
LC

Enable lower case

FILE L..EX41A.MAC

6
7

Modified to use Suspend and Resume directives for;;EX
swnchronization
;;EX

8
9

10
11
1"

This task prompts at TI: for a line of text and sends
the data to RECVl for processinS. SYnchronization is
handled throu~h a common event fla~.

13
1.4

Assemble and task-build instructions:

15
lb
17

>MACRO/LIST/OBJECT:SENII1 lB:[l,lJPROGMACS/LI-;;EX
-)BRARY,dev:[ufdJlEX41A
)LINK/MAP SEND1,LB:[1,lJPROGSUBS/LIBRARY

18
19

Install and run instructions: RECV1 must be install~d
and run prior to runnins SEND1. RECVl continues to run
until it receives 3 data packets.

21
,,"),a)
A! ......

23
24

; ....

'')c"

A: • ..J

26
27

;

BUFFER:

29
30
31
32
:~3

.MCAlL
.MCALl

SDAT$C,EXIT$S,RSUM$C; Swstem macros;;EX
TYPE,INPUT,DIRERR; SUPplied macros

tBlKB

26.

Data buffer to be sent

.ENABL.

lSB

Enable local symbol
blocks

;
START:: TYPE

INPUT
SDAT$C
BCC
DIRERR

~55

36
37
38
~59

4()
41
4'')
.:..
43
44

1$:
5$:

RSUM$C
BCC
DIRERR
EXITSS
tEND

<TYPE A LINE OF TEXT, 2b CHARACTERS OR LESS)
Type prompt
tBUFFER,. f.26.
; Get teHt to send
RECV1,BUFFER
; Send data to RECV1 ;;EX
1$
; Branch on directvie ok
<UNABLE TO QUEUE DATA TO RECV1) ; Displaw
error messa~e and exit
RECV1
Resume RECVl
;;EX
5$
Branch on directive ok;;EX
<UNABLE TO RESUME RECV1>
;;EX
Exit
;;EX
START

Using Directives for Intertask Communication
SOLUTION
.TITLE
.IDENT
.ENABL

1
:~

4
5
6
7
8
9
10
11
12

RECV1
lOll
l..C

Enable lower case

FILE LEX41B.MAC
Modified to use Suspend and Resume for synchronization;;EX
This task and receives data from any sender task
(e.S., SEN(1).It prints the data on TI:. Then it
waits for another data packet. It does this until it
has received 3 messaSes and then exits.

1.3

14
15
16
17

This task synchronizes with its sender throuSh an
event flas.
Assemble and task-build instructions:

19
20
21
22
23
24
25

>MACRO/LIST/OBJECr:RECV1 LB:[1,IJPROGMACS/LIB-;;EX
->RARY,dev:CufdJRECVl
;;EX
LINKIMAP RECV1,LB:r!,lJPROGSUBS/LIBRARY

; .-

Install and run instructions: RECV1 must be installed
and run before runninS SEND!.

.MCALL
.MCALL

RCVD$C,EXIT$S,SPND$S; System macros ;;EX
TYPE,DIRERR
; SUPplied macros

• BLKW

15 •

Rece i ve buff En'

.ENABL

LSB

Enable local symbol
blocks

MOV

t3,R5

29
30

;
RBUFF:

31
32
33
~54

35
:36
~57

38
:~9

40
4:L

42
43
44
45
46
47
48
49

START:

Initialize messaSe
counter
Suspend self until;;EX
AGAIN: Sf'ND$S
messaSe arrives
3$
BCC
; Branch on directive ok
DIRERR <SUSPEND DIRECTIVE FAILED> ; Display ~;EX
; error messaSe and exit
; We set here when resumed by SENDI
;;EX
3$:
RCVD$C
,RBUFF
; Receive from anyone
BCC
5$
; Branch on directive ok
DIRERR <RECEIVE DIRECTIVE FAILED IN -RECVI->
Display error messaSe
and e~·dt,
; Successful receipt
Displa~
5$:
TYPE
<DATA RECEIVED BY -RECUI-:>
data

Using Directives for Intertask Communication
SOLUTION
2.

.TITLE
.IrIENT
.ENABL

1
2

RECV2
lOll
LC

Enable lower case

5
6
7
8
9
10
11
1 .:'")

13
14
1 ~)
16
17
18
19
20
21
22
23
24
2!:i

26
27
28
29
30
31
32
33

FILE LEX42.MAC
Modified to displaw the sender task name in addition ;;EX
to the data
;;EX
This task receives data from another task. It prints
the data, alon~ with a header, on TI:.
Then it waits
for another data packet, continuin~ this until it has
received 3 messaSes.
This task swnchronizes with its sender usin~ RCSTS.
Because of this swnchronization, the tasks can be run
in an~ order, with an~ relative priorities.
Assemble and task build instructions:
>MACRO/LIST/OBJECT:RECV2 LS:[1,1JPROGMACS/LIB-;;EX
->RARY,dev:[ufdJLEX42A
;;EX
>LINK/MAP RECV2,LB:[1,lJPROGSUBS/LIBRARY
Install and run instructions: RECV2 ffiust be installed.

RBUFF:
TASKNM:

.MCALL
.MCALL

RCSTSC,RCVDSC,EXITSS; S~stem macros
TYPE,DIRERR
SUPplied macros

BLKW
BLKW

.ENABL

LSB

+
+

Rec€~ i ve

bufte r
Buffer for task name;;EX

15.

Enable local
blocks

s~mbol

:~5

37
~58

39
40
41
42
43
44
41:"...1
46
47
48
49
~jO

t3,R5
Set UP message counter
,RBUFF
Receive from anyone
5S
Branch on directive ok
<RECEIVE DIRECTIVE FAILED IN PRECV2 P >
Displaw error message
;
and e~"~i t
Successful receipt or unstopped bw another task. First
check for unstopped after being stopped, in which case
we have to receive the data
5$:
CMP
SDSW,tIS.SET
Were we stopped due to
no data
ENE
6$
If not, we have a data
packet
RCVD$C ,RBUFF
Now ~et the packet
BCC
6$
Branch on directive ok
START: MOV
RECEIV: RCSTSC
BCC
DIRERR

Using Directives for Intertask Communication
SOLUTION
20

23
24
:?5
26
27

~50

31
32
33
:36

Buffer for ASCII form! !EX
of task name
! !EX
DSW code mnemonic

IIATA ISSET/21

DO 100, 1=1,3
CALL RCST(,RBUFF,DSW)
Receive from an~one
IF (DSW.GE.O) GO TO 50
u
T~pe *,/RECEIVE DIRECTIVE FAILED IN -RECV2 •
1 DSW ::: /,DSW
Displaw error messa~e
GOTO
1000
and e~·d t

Receive buffer

C
C

INTEGER RBUFF(15)
INTEGER DSW,ISSET
INTEGER TASKNM(3)

C
C Successful receipt or unstopped bw another task. First
C check for unstopped after bein~ stopped, in which case

~58

C we have to receive the data
50
IF (DSW.NE.ISSET) GO TO 60

39
40
41

C
C
C

4')

C Stopped due to no data:

CALL RECEIV(,RBUFF"DSW)
Now ~et the packet
IF (DSW.EQ.l) GOTO 60
TYPE *,/RECEIVE DIRECTIVE FAILED AFTER nRECV2lUNSTOPPED. DSW ::: /,DSW
Displa~l E~rr()r
GOTO 1000
messa~e and exit

44
45
46
47
48
49
50
51

C Displaw data

60
7::=;

CALL R50ASC (6,RBUFF,TASKNM)
! !EX
TYPE 75,TASKNM~(RBUFF(J),J=3,15)
! !EX
FORMAT (/ DATA RECEIVED BY BRECV2 A ://1X,3 ! !EX
lA2,1X,13A2)
! !EX
CONTINUE

100

C Have received 3

55
56
~.i7

Were we stopped due
to no data? If not
(NE), we hav€~ a
data F,acket

1000

messa~es

TYPE *,/BRECV2· HAS RECEIVED 3 MESSAGES AND WILL
1 NOW EXIT'
CALL EXIT
! Exit
END

Using Directives for Intertask Communication
SOLUTION
PROGRAM LEX43A

2
3
4
5

C FILE LEX43A.FTN

! !EX

C A second sender task to send data to RECV2

I lEX

7
8
9

C This task prompts at TI: for a line of text and sends
C the data to RECV2 for processin~.
The receiver will
C continue to run until it receives 3 messages.
C S~nchronization is handled throush RECV2's stop bit.
C RECV2 and LEX43A ma~ be run in an~ order.

10
11
12
13

14
15
16
17
18

C Install and run instructions: LEX43B must be
C installed under the name RECV2.
C

20
21
22
23

FOf~MAT

2b
27

~3 :L
~'52

:~3

34
:35

C
C
C

:36

37
38
39
40
41
42

BYTE BUFFER(26)
INTEGER nsw
REAL RECV2
DATA RECV2/SRRECV21
INTEGER IEITS,IEACT
DATA IEITS,IEACT/-8,-71

Sf.~nd

buff€~ r

Receiving task name
ErT'or mnemonics

TYPE *,'TYPE A LINE OF TEXT, 26 CHARACTERS OR LESS'
READ (5,5) BUFFER

24
25
28
29
30

! 'EX
'!EX

C.~~6A1)

CALL SEND(RECV2,BUFFER"DSW) , Send data to RECV2
IF (DSW.EO.l) GOTO 10
TYPE *,'UNABLE TO QUEUE DATA TO aRECV2 u • DSW = '
l..,DSW
CALL USTP(RECV2,DSW)
Unstop RECV2
IF (DSW.EQ.l) GOTO 20
! Branch on directive ok
IF (DSW.EQ.IEITS) GOTO 20 ! Isn't he stopped?
That's ok., he'll pick
UP data when he
e~·{ecl.Jt.es Ii:CDS$
IF (DSW.EQ.IEACT) GOTO 20 ! Is he not. active? If
! not, he'll pick UP
data when activated
TYPE *,'UNABLE TO UNSTOP aRECV2 a • DSW = ',DSW
! An~ other error is bad
CALL EX I T ' E~·d. t
END

Using Directives for Intertask Communication
SOLUTION
47
48

49
50
51
52
53
54
55

56
57
58

59
60
61
62
63
64
6~5

66
67

68
69
70
71
72
7~5

1
2

3
4
5
6
7
8

9
10
11
12

13
14
15

16
17

18
19

20
21,

; Successful receipt or unstopped by another task. First
check for unstopped after bein~ stopped, in which case
; we have to receive the data
5$:
CMP
$DSW,tIS.SET
Were we stopped due to
no data
BNE
6$
If not, we have a data
packet
RCVD$C LEX43A,RBUFF
Now get the packet
BCC
6$
; Branch on directive ok
DIRERR (RECEIVE DIR FAILED AFTER "RECV2" UNSTOPPED>
Display error message
; and e~·d t
Displa~
TYPE
(DATA RECEIVED BY "RECV2":>
te~·~t and
TYPE
tRBUFFt4,t26.
; data sent
R~j,RECEIV
SOB
pecrement messa~e
counter. Receive a~ain
if haven't received 3
yet
R5
;;EX
DEC
BE(~
DONE
;;EX
RECEIV
;;EX
JMP
DONE:
TYPE
("RECV2 HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT>
TYF'e eHi t
meSSfjge
EXIT$S
.END
START
;

PROGRAM RECV2
C
C FILE LEX43B.FTN
C

! !EX

! !EX
C Modified to receive only from LEX43A
C NOTE: TASK WILL EXIT WITH A NO DATA QUEUED ERROR IF! !EX
! !EX
C SEND2 SENDS DATA. MORE COMPLICATED CODE IS NEEDED
C TO CHECK FOR SEND2 SENDING DATA AND UNSTOPPING RECV2! !EX
C
C This task receives data from another task

(e.~. SEN(2).
Then
C It prints the data, alon~ with a header, on TI:.
C it waits for another data packet, continuin~ this
C until it has received 3 messages.C
C This task synchronizes with its sender using RCST.
C Because of this sYnchronization, the tasks can be run
C in any order, with any relative priorities.
C
! !EX
C Install and run instructions: LEX43B must be
C installed under the name RECV2.
! !EX
C

Using Directives for Intertask Communication
SOLUTION
4.

+TITLE
+IDENT
+ENABL

3
4
c·
~

6
7

8
9

10
11
12
13
14
15
1.6
17
18
19
20
21
~~ ~~

23
24
25
26
27
28
29
30

31
:32
33
~~4

:35
36
37
38
39

40
41
42
43
44
45
46
47
48

SPAWN

/02/

Enable lower case

File LEX44.MAC
This pro~ram spawns MCR ••• , passes it a series of ;;EX
command lines, waits for each to exit, and
;;EX
displa~s each command's exit status.
;;EX
Assemble and task-build instructions:
MACRO/LIST LS:[1,1JPROGMACS/LIBRARY,dev:(ufdJLEX44
LINK/MAP LEX44,LB:[1,lJPROGSUBS/LIBRARY
.MCALL
.MCALL
.NLIST

SPWN$,EXITSS,WTSE$C,QIOW$S,QIOW$C
S~stelTl macros
DIRERR,IOERR
SUF-P lied mac ros
Inhibit listin~ of
BEX
binar~ extensions

CMD1:
.ASCII -PIP *.MAC/LILEN1
=.-CMD1
CMD2:
• ASCI I /ACT /
LEN2 :::: +···CMD2
CMD3:
.ASCII /TIM/
LEN3 ~..: +-CMD3

Command line
of command

Len~th

.ASCII /SPAWN IS STARTING AND WILL SPAWNI
Startup messa~e
+ASCII / MCR COMMANDSI
::::+-SMES
Len~th of messaSe
LSMES
.EVEN
I/O status block
lOSB:
.BLKW
2
Exit status block
EXSTAT: .BLKW
8.

SMES:

CMDTBL: .WORD
.WORD
.WORD
.WORD
SPAWN:

CMD1,LEN:I.
CMD2,LEN2
CMD3,LEN3

Table inde}·dns
MCR command!5

End

of tctble

; ;EX
; ; EX
; ;EX
; H::X
; ;EX
;;EX
; ;EX

; a::x

; ;EX
; ;EX
; ; EX
; ;EX

SPWN$

; Output messa~e buffer
.BI... KB
80.
BUFF:
; Format strin~:
FMT:
.ASCII /XNSPAWN REPORTING: COMMAND I
;;EX
.ASCIZ I COMPLETED. EXIT STATUS WAS XD.ZNI
;;EX
.EVEN
START: QIOW$C IO.WVB,5,1"IOSB~,<SMES,LSMES,40>
BCS
ERR1D
Branch on dir error
49
TSTB
IOSB
Check for liD error
50 r
BlT
ERR11
Branch on I/O error
~51

Using' Directives for Intertask Communication
SOLUTION
1
2
3
4
5
6
7
8
("l

10
11

12
13
14
15

16
17

PROGRAM SPWN
C
C File lEX44.FTN
C
C This proSram spawns ••• DCL, passes it a series of
C command lines, waits for each to exit, and
C displaws each command's exit status.
C
C Data
INTEGER EXSTAT(8),PLIST(6),DSW
BYTE BUFF(80)
C Commands to be spawned:
C
C
C
C
C

:1.8

19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
~jO

!!EX
! !EX
, 'EX

, !EX

DIR *.MAC
SHOW TASKS/ACTIVE
SHOW TIME

! 'EX
, 'EX
! !EX

REAL CMD(5,3)
DATA CMD/'DIR ','*.MA','C'
, 0
,0,
1
'SHOW',' TAS','KS/A','CTIV','E',
2
'SHOW',' TIM/,'E'
,0
, 0/
INTEGER lEN ( :-S)
DATA LEN/9,17,9/

, !EX
! !EX

C
REAL DCl
DATA DCl/6R ••• DCl/
C
C Code

WRITE (5,15)
, Write messa~e
FORMAT (' SPAWN IS STARTING AND WILL SPAWN "
1 ' DCl COMMANDS')
! ! EX
DO 30,1=1,3
CALL SPAWN (DCL , ,',1, , EXSTAT, , CMD ( 1 , I ) , LEN ( I )
1 " , DSW)
, ! EX
Spawn DCl
IF (DSW.lT.O) GOTO 900
Branch on dir error
CAll WAITFR(I,DSW)
Wait for task to exit
IF (DSW.lT.O) GO TO 910
Branch on dir error
WRITE (5,25) EXSTAT(I).AND. a 377 , Displaw low
, bwte of exit status
25
FORMAT (' SPAWN REPORTING: COMMAND COMPLETED.',
1 ' EXIT STATUS WAS ',II,'.')
30
CONTINUE
CALL EXIT
, Exit
C Error handling code
900
TYPE *,'ERROR SPAWNING DCl. DSW = ',DSW
GOTO 1000
910
TYPE *,~ERROR WAITING FOR EVENT FLAG. DSW - ',DSW
1000
CALL EXIT
END
15

Using Directives for Intertask Communication
SOLUTION
51

52
53
~7i4

55
56

57
58

3$:

QIOW$ to TI:

DIR$
BCS
TST
BGE
[lIR$
BCS
BR
EXIT$S

R4
ERR4
R5
3$
t:CLEF
ERR5
1$

DIRERR
DIRERR

{lid offspring e~·dt'?
Yes
No. Clear EF 1 again
Wait
Once offsprins e~·d ts,
so should parent

~:)9

60
61
62
63
64
65
66

;

ERR1:
ERR2:
ERR3:
ERR4:
ERR5:

DH~ERR

DIRERR
DIRERR

AST routine, entered when offsprins emits status
(negative status value) or exits (positive status

1.,9

v (!~ 11.JE:~ )

f.,7

70
71
72
73
74
75
76

ASTRTN: SETF$C
BCS
eMP
BEQ·
TST
BGE

78
CNCT$C
BCS
TST
ASTX$S

80
81
82
83
84
85

Awaken main code

ERR6
$[lSW,t:IS.SET

If set, main code is
not read!:l !:let
We've been overrun
OVRRUN
Has offsprins exited?
STATUS
4$
If so, don't tr!:l to
reconnect
LEX45B"ASTRTN,STATUS
ERR7
(SP>+
Clean UP stack from AST
Let main code run

If a new status comes in before we're done with the old
one, somethins is wrons. Stop everwthins.

;

OVRNMS: .ASCII /STATUS RECEIVED BEFORE READY. /
.ASCII / ABORTING BOTH TASKS./
OVRNML = .-OVRNMS
.EVEN

89
90
91

;

92
93

fJVRRUN: QIOW$C
ABRT$C
BCS
EXIT$S

IO.WVB,5,3",,<OVRNMS,OVRNML,40>
LEX45B
Abort offspring
ERR8
E~·dt this task

{lIRERR
DIRERR
DIRERR
.EN{I

<ERROR FROM SETF$ IN AST ROUTINE)
<ERROR CONNECTING TO OFFSPRING>
<ERROR ABORTING OFFSPRING>
START

(~4

95
96
97
98

ERR6:
ERR7:

E:RI~8 :

100

Using Directives for Intertask Communication
SOLUTION
.TITLE
.IItENT
.ENABL

1
,.)
A.,

4
5

LEX45B
lOll
LC

Enable lower case

File L.EX45B.MAC

Solution to Module 4, Lab Exercise 5 - Part B,
offspring task

8
9
10

This task is spawned bv lEX45A. It emits a negative
status every 5 seconds, then exits after 30 seconds
(6 emits¥ then an exit).

12
1.3

14
15

If an emit status fails because this task was not
connected to the parent, another emit status will be
tried 5 seconds later. Two consecutive failures cause
this task to exit with an error messa~e.

16
17
:1.8

19
20
21

This task must be installed under task name LEX45B.
; ....

.MCAL.l
+ MCAL.L.

EMSTSS,QIOWSC,WTSESC,MRKTSC,EXITSS
DI F~ERR

2~}

26
.',)'7
..:.. ...
:?B

.ASCII ILEX45B NOT CONNECTED TO ANY PARENTI
"BYTE
15,:1.2
.ASCII /WILL TRY AGAIN IN 5 SECONDSI
NCNCTI... ::: + .... NCNCT
.EVEN

29
30

STAF(r:

24
'')1::'

,1t:.....J

NCNCT:

3:1.

CL.F~

RO
Rl

MO'v'

:fI:611R3

DEC
BMI
MRKTSC
BCS
DEC

1:;:3

EMSTSS
BeS
CLR
BR
eMF'

lIRO
1S

BNE

ERR2

CL.F~

RO = exit status
Rl = 0 means last
atte~pt to emit status
suceeded. RO < 0 means
it failed because we
were not connected
R3 ,- number of emits
yet to be issued
Set timer (again)'r
Nc) , ,just exit
Set, timer for 5 seconds

34
35

36
37
38
:39
40

EMST:

4:1.
42

EXIT
1,,5,2
ERI~:I.

Use status .::: 0 when
emitting
Emit to parent
Failed. Why?
N(:)te success
Wait for o::J sees to pass
Failed because not
connected?
Any other reason, CHJit

F~O

44
4~)

47
48

1~;:

WAIT
S[lSw,tIE.ITS

s:.~

Using Directives for Intertask Communication
SOLUTION

:1,9

INTEGER DSW,IEITS
DATA IEITS/ .... 81
LOGICAL*1 ERLAST

20
21
22
2~5

24
25

C
C

DATA ERLAST/.FALSE./

28
29
~50
:~1

32
:3:'5

34
35
36

37
38

20
C
C

39
40
41

44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

Error mnemonic
Flas if last EMST
failed because we were
not connected

25
C

30
50

DO 50~I:::1,6
Issue 6 EMSTs
CALL MARK (1,5,2,DSW)
Set timer for 5 seconds
IF (DSW.LT.O) GOTO 900
CALL EMST(,(-I),DSW)
Emit to parent
IF (DSW.LT.O) GOTO 20
Failed. Why?
ERLAST ::: .FALSE.
Note success
GOTO 30
! Wait for 5 sees to pass
IF (DSW.NE.IEITS) GOTO 910 ! Failed for reason
othe T' than not
! connected
IF (ERLAST) GOTO 910
Failed last time too?
Then sive up.
ERLAST ::: .TRUE.
Else note we failed
this time
And announce the
PT'oblem:
TYPE 25
FORMAT ('LEX45B NOT CONNECTED TO ANY PARENT'/
1 'WILL TRY AGAIN IN 5 SECONDS')
And try asain in 5 secs
CALL WAITFR(l,DSW)
! Wait for 5 sees to pass
IF (DSW.LT.O) GOTO 920
CONTINUE
CALL EXIT
Exit (with success)

C
C Directive errors
C
900
TYPE *,'ERROR ON MRKT. DSW::: ',DSW
GO TO 1000
910
TYPE *,'ERROR EMITTING TO PARENT. DSW GOTO 1000
920
TYPE *,'ERROR ON WAITFR. DSW = ',DSW
1000
CALL EXIT
END

',DSW

Memory Management Concepts
TEST / EXERCISE
1.

Write 'M' if the statement applies to mapped systems,
lUI
if
it applies to
unmapped systems, or 'M,U' if it applies to
both.
a.

Physical addresses up to 32K words accessible with
16-bit addressing.

Physical addresses up to l28K words accessible with
l8-bit addressing.

Program relocation possible without having to program
or task-build again.

Detection of memory protection violations.

Program executes only at physical addresses that match
the virtual addresses created by the task builder.

Virtual address limit of 32K words.

Fill in the headings and the missing values in Figure 1.

Memory Management Concepts
SOLUTION
1.

Write 'M' if the statement applies to mapped systems,
'u' if
it applies to
unmapped systems, or 'M,U' if it applies to
both.
U

Physical addresses up to 32K words accessible with
l6-bit addressing.
(M is also acceptable since 32K
words is the limit of l6-bit addressing even on a
mapped system.)

Physical addresses up to l28K words accessible with
l8-bit addressing.

Program relocation possible without having to program
or task-build again.

Detection of memory protection violations.

Program executes only at physical addresses that match
the virtual addresses created by the task builder.

M,U f •
2.

Virtual address limit of 32K words.

Fill in the headings and the missing values in Figure 1.

Overlaying Techniques
TEST IEXERCISE
The following is an output display from a task.
MAIN CALLING SUBROUTINE G
G CALLING SUBROUTINE GI
Gl RUNNING
MAIN CALLING SUBROUTINE HI
HI RUNNING
MAIN CALLING SUBROUTINE H
H CALLING SUBROUTINE HI
HI RUNNING
H CALLING SUBROUTINE H2
H2 RUNNING
MAIN EXITING
The calling sequence parallels the output display.
1.

Draw an overlay tree diagram or a memory allocation
for a possible overlay structure for the task.

Write the modules MAIN, G, Gl, H, HI,
compile each one.

Task-build and run the task without overlays.

Task-build and run the task with all
Obtain a map.

Task-build and run the task with all memory-resident overlays.
Obtain a map.

and

H2.

diagram

Assemble

Obtain a map.

disk-resident

overlays.

Overlaying Techniques
SOLUTION
The following is an output display from a task.
MAIN CALLING SUBROUTINE G
G CALLING SUBROUTINE GI
Gl RUNNING
MAIN CALLING SUBROUTINE HI
HI RUNNING
MAIN CALLING SUBROUTINE H
H CALLING SUBROUTINE HI
HI RUNNING
H CALLING SUBROUTINE H2
H2 RUNNING
MAIN EXITING
The calling sequence parallels the output display.
1.

Draw an overlay tree diagram or a memory allocation
for a possible overlay structure for the task.

MEMORY ALLOCATION
DIAGRAM

OVERLAY TREE
G1

MAIN

TK-7744

diagram

Overlaying Techniques
SOLUTION

PROGRAM MAIN

C File lEX6A.FTN

4
5
7
8

C
C Mainline routine for Module 6, Lab Exercises 1-6.
C Illustrate different overlays and their effects.
C
C For each routine, type messaSe then call routine

TYF'E *, ~ MAIN CAl.l.ING SUBROUTINE G~
CAl.L
G
TYPE *"~MAIN CALLING SUBROUTINE H1~
CAll
H1
TYPE *,~MAIN CAl.LING SUBROUTINE H~
CALL
H
TYPE *,~MAIN EXITING~
CALL EXIT
END

10
11
12
13
14
15
1.6

1?
18

.TITLE

2
3

+IDENT

101/

.ENABL

Enable lower case

File LEX6B.MAC

7
8

Subroutine for Module 6, Lab Exercises 1-6.
Illustrate different overla~s and their effects.

9
:1.0
11
12
13

.GLOBl
.GLOBL
.MCALL

Gl
IOFAIL
QIOW$C

Subroutine called
Error T'outine

14
:1.5
:1.6
17
:LB
:1.9

20
21

;
CG1MS:

.ASCII IG CALLING SUBROUTINE G11
CG1ML _. .-CG1MS
.EVEN
Type messaSe then call routine

(,' . +

2~5

26
27

ERROR:

CHDW$C
BCS
CALL
RETURN
..JMP
.END

IO.WVB,5,1",,(CG1MS,CG1ML,40>
E I:;: I:;: OR

G1
IOFAIL

Overlaying Techniques
SOLUTION
SUBJ~OLJT I NE

1
.~)

c Fi l€~ LEX6C. FTN

-4

,.1

r Subroutine for Module 6, Lab Exercises 1-6.

6
l
8
9

C
C

I~'

C Illustrate different overlaws and their effects.
T~pe

messa~e

then return

TYPE *,'G1 RUNNING'

I:~ETURN

1.2

END

1
2
3
4

.TrTLE
.IDENT
.ENABL

lOll

Enable lower case

File LEX6D.MAC

5
6

7
8

Subroutine for Module 6, Lab Exercises 1-6.
Illustrate different overla~s and their effects.

tGLOBL
tGL.OBL.
.MCALL

10
:L 1
12
13

Hl,H2
IOFAIL
QIOW$C

Subroutines called
Error' routine

14
15

;

16
17

CHIMS:
CH1ML =
CH2MS:
CH2ML -

18
19
20
21

22
23

T~pe

26
27

28
29
3':)

messaSe then call routine

QIOW$C
BCS
CALL..
QIOW$C
BCS
CALL

30
31

.ASCII IH CALL.ING SUBROUTINE Hil
.-CH1MS
.ASCII IH CALLING SUBROUTINE H21
.-CH2MS
.EVEN

IO.WVB,5,1",,<CH1MS,CH1ML,40>
ERROR
H1
IO.WVB,5,l",,<CH2MS,CH2ML,40>
ERROR
H2

I~ETURN

ERROR:

JMF'

IOFAIL

.END

Overlaying Techniques
SOLUTION
1
2
3

4
5
6
7
8

9
10
11
1:2

SUBROUTINE Hi
C
C File LEX6E.FTN
C
C Subroutine for Module 6, la~ Exercises 1-6.
C Illustrate different overlays and their effects.
C
C T~pe messa~e then return
C
TYPE *,'Hl RUNNING'
RETURN
END

.TITlE
.I[tENT
.ENABL.

:2
3

H2
lOll
Enable lower case

I... C

4
cd

6
7
8
9
10
11

File L.EX6F.MAC
Subroutine for Module 6, lab Exercises 1-6.
Illustrate different overlays and their effects.
.GLOBI...
MCALL

; Error routine

IOFAIl
CHOW$C

12
13
14
l ~)

lb
:1.7
18
19
20

'.,,.)

H2RUN:
.ASCII IH2 RUNNINGI
H:2FUJNL.. :::: • ~"H2RUN
.EVEN
T~pe

messa~e

then return

H2::

QIOW$C
BCS
RETURN

IO.WVB,5,1",,<H2RUN,H2RUNL,40>
ERROR

ERROR:

JMP

IOFAIL

".O.h

.END

1
:2

3
4
5
6
7
8
9
10
11
12

SUBROUTINE H2
C
C File LEX6F.FTN
C
C Subroutine for Module 6, Lab Exercises 1-6.
C Illustrate different overlays and their effects.
C
C T~pe messa~e then return
C
TYPE *,'H2 RUNNING'
RETURN
END

Overlaying Techniques
SOLUTION
4.

Module 6, Lab Exercise 4
.ODL file for buildin~ MACRO-11 with all disk resident
ove r 1 a~:,~;;
.R()()T
LEX6A-PROGSUBS/LB-*(LEX6B-LEX6C,OVRH)
LEX6D-(LEX6E,LEX6F)
.FCTR
OVFUH
l.EX6A ..~ MAIN
LEXt)B
G
G1
1... EX6C
LEX6D
H
LEX6E - H1
LEX6F
H2
M ••

.END
Module 6y Lab Exercise 4
.ODL file for buildins FORTRAN with all disk-resident
overla~s

HSEGS:
Fl.IB:

.ROOT
• FCTF~
.FCTR

LEX6A-FI...IB-*(I...EX6B-l.EX6C-FLIB,HSEGS)
LEX6D-FLIB-(I...EX6E-FLIB,LEX6F-FLIB)
LB:[I,lJF4POTS/LB

LEX6A .- MAIN
LEX6B .- G
LEX6C - Ot
LEX6D -- H
I...EX6E
H:I.
LEX~)F ..
H2
.END
M

Module 6, Lab Exercise 5
.ODL file for MACRO-11 with all

memor~-resident

OVf:? r 1 ('=l!:I~:;
+ F.:()OT

OVRH:

.FCTR

LEX6A-PROGSUBS/LB-*!(LEX6B-LEX6C,OVRH)
LEX6D-!(LEX6E,LEX6F)

L.EX6A .... MAIN
LEX6B .... G
LEX6C
81
•• M

I...Ex(~)rr

EX6E
LEX6F

1•••

.END

Overlaying Techniques
SOLUTION
7.

Use the map to fill in the following table:
Type of
Overlay

Starting Virtual
Address of G

Starting Virtual
Address of HI

No Overlays
All
Disk-Resident
Overlays

Answers will vary depending on
students' particular solution.

All
Memory-Resident
Overlays
Disk-Resident
and MemoryResident
Overlays

Module 6, Lab Exercise 8
.ODL file in MACRO-I! to place TOTAL in an overlaw
All overlaws are disk-resident
.ROOT
MAIN-*eA-eJOB1,JOBXX),B,TOTAL)
.END

Module 6v Lab Exercise 8
.ODL file in FORTRAN to place TOTAL in an overlaw
•
All overlays are disk-resident
.ROOT
MAIN-FLIB-*(OVRAyB-FLIB,TOTAL-FLIB)
DVRA:
.FCTR
A-FLIB-eJOB1-FLIBvJOBXX-FLIB)
FLIB:
.FCTR
LB:[!,lJF4POTS/LB
.END
sf~~ment

Overlaying Techniques
SOLUTION
51
~52
~:;:~

54
56
57
:58

59
60
61
62
b:~

64
b~5

66
67

68
69
70
7:1.
72
73

1
2

QIOW$C
CAl.L
CALL

IO.WVB,5,1",,{MES1,LMES1,40> ;Write MES1
A
Call subroutine A
; ; EX
RTOTAL
Call routine to
; ; EX
d i sp I a~ runrd rig
; ; EX
;
total
QIOW$C IO.WVB,5,1",,{MES2,LMES2,40> ;Write MES2
CALL
B
Call subroutine B
; Set UP for loop
MOV
i3,R4
;'Counter
QIOW$C IO.WVB,5,1",,{MES3,LMES3,40>; Write MES3
LOOP:
CLR
ANS
Clear answer in case
of no operation
CALL
A
Call subroutine A
CALL
RTOTAl.
Call routine to
displa~ running
;;EX
total
;;EX
SOB
R4,LOOP
Decrement counter and
;
loop back until done
QIOW$C IO.WVB,5,:I.",,{MES4,LMES4,40>; Write MES4
CALl.
TOTAL
.; Ca 11 rout i ne to
;
display grand total
QIOW$C IO.WVB,5,1",,{MES5,LMES5,40>; Write MES5
EXITSS
; Exit
.END START
START:

PROGRAM MAIN

C
C FILE LEXb9A.FTN

1:."

6
7
8
~:>

:1.0
1t
12
13
14
1. .JC~
16

! !EX

r Modified to call RTOTAL to display the running
f'

after each call to A

! !EX
! !EX

C
C This program prints a messaSe and then calls subroutine

C A. Subroutine A asks whether to perform Job :I. or Job 2.P
C It then calls either subroutine JOBl or JOB2 which
C performs the operation and displaws the results. MAIN
C then calls subroutine B which displaws a message. MAIN
C then calls subroutine A 3 more times, keeping a grand
C total of the operations. Finally, it displays the
C grand total and exits.
C
C Task-build instructions: Use LEX69A.ODL as the input! !EX

1.7
18
19

C input file for RTOTAL in the best overlay seSment

C file for RTOTAL in the root. Use LEX69B.ODL as the

! !EX
! !EX

Overlaying Techniques
SOLUTION

.TITLE
.IDENT
.ENABL

1
2
3
4

RTOTAL
lOll
LC

Enable lower case

FILE LEX69B.MAC

Subroutine to print the running total

7
8
9

.MCALL
.NLIST

11
12
13
1.4
15

RTOFMT: • ASell
RTOTBF: • BU"B
.EVEN
.NLIST

RTOTAL::MOV
MOV
MOV
CALL
QIOWSS

lB
19
20
21
22
23

QIOW$S
BEX

External s~stem macros
Do not list binar~
e~·~t,ens:i. ons
ITHE TOTAL SO FAR IS %D.I ;Format string
100.
Output buffer
BEX

List binar~ extensions

tRTOTBF,RO
Set UP for SEDMSG
#RTOFMT,Rl
ITOT,R2
SEDMSG
; Edit messaSe
tIO.WVB,iSvily"y(#RTOTBF,Rly#40>
y P l' i nt it

RETURN
.END

SUBROUTINE RTOTAL
C

C FILE LEX69B.FTN
C

C Subroutine to print the running total
6
7
8
9
1.0
11
12

COMMON ITOTCOM/TOT
INTEGEF~ TOT
TYPE 5,TOT
FORMAT(' THE TOTAL SO FAR IS', 14,'.')
RETURN
END

Module 6, Lab Exercise 9
.ODL file in MACRO-ll, placinS RTOTAL in the root
segment for testins
; All overla~s are ffiemor~-resident
.ROOT
LEX69A-LEX69B-*!CA-!(JOB1,JOBXX),B,TOTAL)
LEX69A = MAIN modified to call RTOTAL
LEX69B :::: RfOTAL
• ENl)

Static Regions
TEST / EXERCISE
1.

Create an initialized resident common (size:
32(10) blocks =
1024(10)
words, contents:
25(10) in each word).
Check with
your course administrator to find out where to place the
common type partition. Write two tasks, one that modifies all
values in the common, and one that reads the values and
displays them.

Create a resident library using the supplied FORTRAN callable
subroutines AADD, SUBB, MULL and DIVV (all in LIB.MAC). Write
a task that calls one or more of the routines.
For example,
write a
task that asks for four numbers (A, B, C, and D) and
then computes' and displays (A * B) + (C * D) = answer.

Static Regions
SOLUTION
1.

:I.
2
3

.TITLE LEX71A

I::"

.IDENT

lOll

.ENABL

Enable- lower case

File LEX71A.MAC

....'

ProSram which creates and initializes a common region
which will be referenced using overlaid Psects.

B
9

Size 1024. words, contents all 25's

10
11
1 ')

Task-build instructions: Must include ISHAREABLE:COMMON
and INOHEADER switches; STACK=O and PAR=COMWP options.
Must create .STB file. Ma~ be ICODE:PIC or absolute
(default).

1:3
14
:I. ~5
11.>
:1.:7

; The code is placed in a Psect named MYDATA
; ....

:1.9

• r~EPT

• WOr';:D
.ENDR
.END

r)",)
4°• • •0. .

2~3

BLOCK DATA LEX7:1.A

1
,.)
A"••

34
5
6

ReF,eat count
Word of 25(10)
End repeat range

1024.
25.

C
C
C

C Pro~ram to create and initialize a resident common
C

9
:1.0
11
:I. ')

C Size is 1024 words, initialized with all 25's
C
C Task-build instructions: Must include ISHAREABLE:COMMON
C and INOHEADER switches; STACK=O and PAR=COMWP options.
C Must create .STB file. Ma8 be ICODE:PIC or absolute
C (the default). OTS librarw NOT reGuired.

1.4
:L ~j
16

COMMON IMYDATA/·I(:l.024)
DATI~ I 11024*25/
END

Static Regions
SOLUTION

EF~ROI:;:l

: MOVB
MOV

c:- r )

,J.:..

~j~J

~54

SETUP:

~:55

MOV
MOV
MDV
CALL.
CnOW$S

Extend si~n on I/O
status and place in
ar~j block
tFERR2,Rl
Addr of format strins
tBUFF,RO
Addr of output buffer
tARG,R2
Addr of ar~ument block
$EDMSG
Edit messaSe
iID~WVB,t5~il"y~<tBUFF,Rl,#40> ; Write
RO~ARG

:5B

EXIT$S
.END

1
r)

.:..

3
4
0::.

...1

6
7
B
<l

10
11
:1.2
13
14
1 ~:j
16

l7
18

F'ROCH-;;AM L.EX71B
C
C
C
C Task to decrement each word in the static common
C reSion L.EX71A. It uses a COMMON to reference
C the data.
C
C Task-build instructions:
C

C
C

C
f'
C

21
I")r)

Il. .....

23
2·4
'")c:"

.(..J

COMMON /MYDATA/ L(1024)! Common to reference
shared re~ion
DE.'crement values
DO 5 K::::1, 1024
L (K ):::L (K) -··1

LINK/MAP/OPTION L.EX71B~LB:[1,1]FOROTS/LIBRARY
Option? RESCOM=LEX71A/RW
Opti on'r <RET>

CONTINUE
WRITE (5,10)
! Displa~ done messa~e
FORMAT (' LEX71B HAS MODIFIED THE VALUES IN THE
1 COMMON LEX71A/)
CALL EXIT
END

Static Regions
SOLUTION
; E T' rc:) r

CCH:if?

Em~(H;::

MDV
MDV
BI~

ERI~C)f;:

1: MDVB
MDV

SETUP:

MOV
MDV
MOV
CALI...
CHOW$S

SDSW,ARG

Move DSW to ar~ block
Addr of format strinS
SETUP
Branch to SEDMSG code
I OSB, 1:;;0
Extend siSn on I/O
I:~O y ARG
status and ~lace in
ar'~j block
tFEI:~R2!1 F~:I.
Addr of format strins
:I=BlJFF y RO
Addr of output buffer
#ARGyR2
Addr of ar~ument block
SEDMSG
Edit messaSe
IIO.WVBlIIS,#1",,<tBUFF,R:I.,i40) ; Write
:IJ:FEI~I:;::I. ,1:;::1.

IT! f..~ ~:; !:; a ~:j (.:.~

EXITSS
.END

;

E:·dt

START

PROGRAM LEX71C

1
")

h..

3
4

C File LEX71C.FTN

I::'

C Task to read data from the static common region LEX71A
C and print it out at TI:. It uses a COMMON to reference
C the data.

6
'7
8

r Task-build instructions:

CLINK/MAP/OPTION LEX71C,LB:[1,lJFOROTS/LIBRARY
C
Option? RESCOM=LEX71A/RO
Option? <RET)
C

1 ':)

13
14
15
16

17
18
19

20
21
22
23

COMMON /MYDATA/ L(1024)! Common to reference
shared region
C Loop through to display regiony 8 numbers on a line
DO 50 J :::: 1,1024,8
WRITE (5,10) (L(K),K::::J,J+7) ! Write values
10
FORMAT (' '~I2Y7I8)
50
CONTINUE
CALL EXIT
END

Static Regions
SOLUTION

51
52

53
54
!7i6

58
59
60
61

6?
63

64
6~5

66
6°?'

68
6<"1

70
71
72
73
74

75
76

77
78
79

80
81

ADDARG: .WORD
.WORD
.WORD
.WORD

For ADD
First MUL result
Second result
Grand total

3
MURESl
MULRES
GRTOT

ASCII buffer table. Irti tiall~ each entr~ in this table
consists of the address of a prompt strins followed b~
the address of the buffer to store the input. After a
string is input, however, the prompt strinS address is
replaced b~ the length of the input string. This
table, with the addition of the final value GRTOTv then
; serves as the SEDMSG argument block.
EDMAI:;:G:
APRMTl'ASCA
~ WOF:D
AnTElL.:
BF'RMT,ASCB
.WOHD
CF'RMT,ASCC
~ ~JORD
CDTBL.:
DPRMT,ASCD
.WOHD
Grand total (numeric
v WOr~D
GPTOT!
value is inserted
directl~ into SEDMSG
block)
Other
M1:
M2:
MUHES 1:
MULRES:

numeric values
.WOt,D
.WORD
. WORD
• WORD

RDF'RMT: QIOWS
IOSB!
.BL.KW

First MUL ar~ument
Second MUL argument
First MUL result
MUL result

fJ2

B3
84
85
B6

87
88
89
<"10

91
92
9~5

94
9~5

96
(rl

98
99

100

Code
,
START:

QIOWSC
MOV
MDV
MOV
CAL.L
CAL.L
MOV
CALL
MOl,,'
MOV
MOV
MOV

IO.WVB,5,1'l',,{HDRMS,HDRML,40>; Identif~
R5 => location to store
binar~ input values
R4 => -read with
tRDPRMTvR4
p romF,t· Df'B
R3 => ASCII buffer table
tABTBL, f~3
Gf?t A
GETINF'
Get B
GETINF'
R5 => MUL ar~ block
tMUl.ARG,R5
Do first multipl~
MULL
Save reslJI t
MULRES,MURESl
IM1 , F.:5
Reset re~isters
(FORTRAN calling
IRDF'RMT,R4
convention does not
tCDTBL,R3
~uarantee the~ are
p rese rved. )

Static Regions
SOLUTION

1
2

PROGRAM LEX72
C+

r File LEX72.FTN

5
6

C Solution to Module 7, Lab Exercise 2
C
C Task computes sum of products usin~ resident library
C routines.

10
11

1?
13
14
15

16
17
18
:1.9

20
21

'")'"')

.~.:

24
25
26
27

28
29
30

32
33
34
35
:36
~57

38
39
40

r Task build instructions:

CLINK/MAP/OPTIONS LEX72,LB:C1,1JF4POTS/LIB
C
Option? RESLIB=LIB/RO
c·~·

INTEGER A,B,C,D,MURES1,MURES2,GRTOT
C ASCII bytes to make promptins code cleaner
BYTE ASCA,ASCB,ASCC,ASCD
C

TYPE ~)
FORMAT (' TASK WILL COMPUTE (A*B)+(C*D)'/
1 ' ENTER NUMBERS IN DECIMAL.')
C FORMAT statements used repeatedly below:
15
FORMAT ('SENTER ',Al,': ')
25
FORMAT (16)
TYPE 15,ASCA
ProlTJPt for
and input A
ACCEPT 25,A
P rOITJF,t fa r
TYPE 15,ASCB
and input B
ACCEPT 25,B
CALL MULL(A,B,MURES1)
MURESl ::: A*B
TYPE 15,ASCC
ProlTJPt fOT'
ACCEPT 25,C
and inF'ut C
P rCHT,pt fo r
TYPE 15,ASCD
ACCEPT 25,D
and input D
CALL MULL(C,D,MURES2)
MURES2 = C*D
CALL AADD(MURES1,MURES2,GRTOT)
! GRTOT :::
TYPE 35, A,B,C,D,GRTOT
FORMAT (' (',16,' * ',16,') + (',16,' *
35
CALL EXIT
END
5

SUITJ

Dynamic Regions
TEST IEXERCISE
1.

Referring to Exercise 1 of Module 7 (Static Regions), modify
the
tasks that reference the common so that they both map to
the common dynamically using the memory management directives.

Write a task that creates a dynamic region two blocks long,
fills it with a character typed in at the terminal, and leaves
it in existence on exit~ Write a second
task
that modifies
one value
in the region, then displays all the values in the
reg i-on a t the terminal, and fi nally deletes the reg ion.

Modify SNDREF so that it sends the region by reference to a
second receiver task, in addition to RCVREF.
Write the second
receiver task, which should modify values in the
region and
then display the values in the region at the terminal.

Dynamic Regions
SOLUTION
1.

.TITLE
.IDENT
.ENABL

3
4

LEX81B
lOll
LC

c·

;;J

File LEX81B.MAC

6
7
8

LEX71B modified to use

11
1 ':>
1:-5

:1.4

Assemble and

1
• c·
..J
:1.1.)
.:LB
19

20
21
::!::!

RDB:

'")1::•.
_ ,J

26
27
28
29
30

;

31
32
33
34

WIN:

WDB:

:35

directives

task~build

instructions:

.MCALL. EXITSS,RDBBKS,WDBBKS,ATRGSC ; S~stem
.MCALL CRAW$"DTRGSS"DII~$,(HOWSS
;. macros
.MCALL DIRERR,IOERR
; SUPplied macros
RDBBK$ 32.,LEX71A,LEX71A,<RS.WRT!RS.RED>
Define T'esicm with:
Size
::: 32. (32. word blocks)
Name
::: LEX71A
Partition
- LEX71A
Attach with read and write access
CRAWS
WDB
;DPB for create address window
WDBBKS 7,32.,0,0,32.,<WS.MAP!WS.RED!WS.WRT>
Define window with:
APR
7
Size
32. (32. word blocks)
Offset in re~ion :::
(32. word blocks)
Len~th in re~ion ::: 32. (32. word blocks)
Map on create with read and write access

~S6

37
38

;

IOSB:
W

DONE:

4~5

44
4 ..cJ'
46
47
48
49
50

mana~ement

>MACRO/LIST LB:[1,lJPROGMACS/LIBRARY,dev:[ufdJLEX81B
>LINK/MAP/OPTION LEX81B~LB:[1,1]PROGSUBS/LIBRARY
>Option? WNDWS==1
>Option? <RET>

39
40
41
42

memor~

Pro~ram to attach to the existins re~ion LEX71A, create
a virtual address window (mapped on creation), decrement
all values in the resion b~ 1, detach from the reSion
and e~d t +

9
:to

23
24

Enable lower case

LDONE
START:

.BLKW
=1024.
.ASCII
.ABCII
==. ·-DONE
ATRGSC
BCS
MDV
DIF,$

BeS

; lID status block
of words in re~ion
ILEXBIB HAS MODIFIED THE VALUESI ; Done
I IN LEX71AI
.
mes~aSe
; t

RDB
; Attach to re~ion
ERR1
; Check for error
RDBtR.GID,WDBtW.NRID ; Move re~ion ID
; into WDB
tWIN
Create window
ERR2
Check for error

Dynamic Regions
SOLUTION

29
30
31
32
33
34
35
36
37
38
39

40
41
42
4:3

44
45
46
47
48

49
50
~51
5~~

54
55

56
57
~)8

~59

60
61
62
63
64

C WDB - Window definition block with the followin~ properties:
C
APR
7
C
Size
32 (10) (32.-word blocks)
C
Offset in reSion 0 (32.-word blocks)
.
r
Lensth of window 32 (10) (32.-word blocks)
C
Map on create with read and write access
C Initialize the WDB
DATA WDB /-3400,0,32,0,0,32,-203,0/
C

C Attach resion
CALL ATRG (RDByIDS)
C Cht~ck for error' on attach
IF (IDS .LT. 0) GOTO 100
C Move resion id to.WDB
WDB(4)=RDB(1)
C Cr(=ate and llIap window
CALI... CRAW (WDB,IDS)
C Chf~ck for eT'ror
IF (IDS .LT. 0) GOTO 200
C Dec r'r.~ment values
DO 50 K=I,1024
IDATA(K)=IDATA(K)-1
50
CONTINUE
C Detach frolll reSion and delete it
CALL DTRG (RDB,IDS)
C Check for error
IF (IDS .LT. 0) GOTO 300
C And Jump to exit
WRITE (5,60)
60
FORMAT (' LEX81B HAS MODIFIED THE VALUES IN
1 THE COMMON LEX71A')
GOTO 500
C

C
100
101

6~~

66
67
68

200
201

6("}

300
301

70
71
".72
·73

Error messaSes
WRITE (5,101) IDS
FORMAT (' ERROR ATTACHING TO REGION, DSW =',14)
GOTO 500
WRITE (5,201) IDS
FORMAT (' ERROR IN CREATING WINDOW, DSW =',14)
GOTO ~:;OO
WRITE (5,301) IDS
FORMAT (' ERROR DETACHING FROM REGION, DSW =',14)

500

CALL EXIT
END

Dynamic Regions
SOLUTION

52
53
54
55

LOOP:

56
57
58

BCS
MOV
MOV
MOV
MOV
CALL
QIDW$S

{,1

62
63
64

DONE:

6~)

66
67
68
69
70
71
7~?

; Error
ERR1:
ERR2:
ERR3D:
ERR3I:
ERR4:

7:1

BCS
TSTB
BLT
SOB
DTRG$S
BCS.
EXIT$S

ERR2
Check for error
Set base addr in re~ion
t160000"R2
tN,R5
Loop count
tBUFF,RO
Set UP for $EDMSG
tFMT,R1
$EDMSG
; Edit data
tIO.WVB,t5,t1"tIOSB,,(tBUFF,R1,t40)
Write data
ERR3D
Check for dir error
Check for 1/0 error
IOSB
EI:;:R3I
Branch on error
Print the line
R5"LOOP
Detach from re~ion
:fI:RDB
ERR4
Check for error

~END

code
(ERROR ATTACHING TO REGION)
(ERROR CREATING WINDOW AND MAPPING)
(ERROR WRITING DATA)
tIOSB,(ERROR WRITING DATA)
(ERROR DETACHING FROM REGION)
START

PI~OGRAM

LEX81C

handlin~

DIRERR
DIRERR
DIRERR
IOERR
DIRERR

C File LEX81C.FTN

C
C
f'
C
C
C

5
6
7
B

9
1. ()
11
1.2

13
14
1~i

17
:L8
19
20

23
24
25
'1£

11-\••'

LEX71C modified to use

memor~

mana~ement

directives

Prosram to attach resion LEX71A in partition LEX71A
create a window and map it to the region upon creation,
read data out of the reSiony and detach from it

C
C Task-build with these options:
VSECT=DATA:160000:20000
C
WNDWS=::1
C
C

INTEGER RDB(8),WDB(8)
C This common block will aliSn with the address window
COMMON IDATA/IDATA(1024)
C RDB = ReSion definition block with the followin~
C proF'ertie~:;:
32 (10) (32.-word blocks)
C
SL--=e
C
Name
LEX71A
LEX71A
C
Partition
Protection
WO:none,SV:RWED,OW:RWED,GR:RWED
C
Attach with read access
C
C Initialize the RDB
DATA RDB 10,32,3RLEX,3R71A,3RLEX,3R71A,·000001,
:1. • 1700001

Dynamic Regions
SOLUTION

.TITlE
.IDENT
.ENABl

1
2

;-5

lEX82A
lOll
lC

Enable lower case

4
~5

File LEX82A.MAC

6
7
8
9
:J.O

Pro~ram to
creation),
creation),
the re~ion

create an named re~ion (attached on
create a virtual address window (mapped on
place ASCII data in to resion, detach from
and exit¥ leavins th~ re~ion in existence.

11
1 ':>

Task-build instructions:

:1.3
Include WNDWS=l option

14
15

.MCALL
.MCALl

16
17
18
19

20
21
....
23
24
25
26
27
28
29
30
3:L
32
33
34

REG:

'·)/·)
~:-

;
RDB:
;
WIN:

CRRG$
;DPB for create resion
RDB
Define resion with:
= 2 (32. word blocks)
Si::-~e
Name
- MYREG
Parti tic>n
GEN
= WO:None,SY:RWED,
Protection
OW:RWED,GR:RWED
Do not mark for delete on last detach
Attach with write and delete access
RDBBK$ 2,MYREG,GEN,(RS.NDl!RS.DEl!RS.WRT!RS.ATT),170000
; DPB for create address window
CRAWS
WDB
Define window with:
APR
= 7
Size
- 2 (32. word blocks)
Offset in re~ion
(32. word blocks)
Lensth in resion
2 (32. word blocks)
Map on create with write access
WDBBK$ 7,2,O,O,2,(WS.MAP!WS.WRT)

,31:.~
,J

36
37

EXITSS,RDBBKS,WDBBKS,CRRG$,CRAW$
DTRGS,DIRS¥QIOWSS,QIOW$C

;
WDB:

:~8

40
4:L
42
43
44
41::"
,J
46
47
48
49
~:;O

DET:
IOSB:
BUFF:
ME!:):
LEN
DNMES:
LDNMES
; Error
FCRRER:
FCRWER:
FDETER:

DTRG$
.BLKW
.BlKB
.ASCII

DPB for detach ins reSion
lID status block
80.
Input/Output buffer
IENTER ASCII CHARACTER: I
• -~-MES
(15)/lEX82A HAS CREATED AND INITIALIZEDI
I THE REGIONI
RDB

.ASCII
.ASCII
:::: + ---DNMES
format strin~s
.ASCIZ IERROR CREATING REGION. DSW = %D.I
.ASCIZ IERROR CREATING WINDOW. DSW = %D.I
.ASCIZ IERROR DETACHING FROM REGION. DSW = %D.I

101

Dynamic Regions
SOLUTION

101
102
103
104
10!)
106
107
108
109
110
111
112

1
'")

..:~

4,
c:·

..1

7
8
9
:to
:I.:t

12
:I. ~5

14
1 ~)

16
II

lB
1.9
20
21
22
23
24
25
26
27
28
29
30
31
~52
3:~

34
35
~:S6

MOV
BR
MOV

ERR5:

SHOERR: MDV
MOV
CALl..
CHOW$S

:f.FaI2IE,R:L
SHOERR
tFDETEF.:" R:L

aIO write err messa~e
Branch to common code
Detach reSion messaSe

tBUFF,RO
Set UP for $EDMSG
:t$DSW,R2
$EDMSG
; Edit messaSe
tIO.WVB,t5,tl",,<tBUFF,Rl,t40>
; Displaw message

EXIT$S
.END

;

E~·d

START

PROGRAM l..EX82A
C
C F :i.l e LEX82A. FTN
C
C LEX82A creates a named region (attached on creation),
C creates a virtual address window (mapped on creation),

C places an ASCII character input at TI: at all locations
C in the resion, detaches from the region and exits,
C leavins the region in existence.
C
C Task-build instructions:
C
>LINK/MAP/OPTIONS/CODE:FPP LEX82A,LB:rl,lJFOROTSC
.M.:> IL I BRAr':Y
C
Option? VSECT=DATA:160000:20000
C
Option? WNDWS::::1
C
Option? <RET>
C
C
Region Definition Block for reSion with the
C RDB
C following properties:
:: 2 (32. word blocks)
Si:<::e
C
:: MVREG
C
Name
:: GEN
C
Partition
Protection
WO:None,SV:RWED
C

OW:RWED,GR:RWED
Do not mark for delete on last detach
Attach with write and delete access

C
C
C

C
C WDB
Window Definition Block for wir,dow with the
C following properties:
_. 7
APR
C
..M 2 (32 • word blocks)
Size
C
C
Offset in resion :: 0 (32. word blocks)
Length in region ..M 2 (32 • word blocks)
C
Map on create with write access
C
C
M~

103

Dynamic Regions
SOLUTION

.TITLE

LEX8~~B

.IDENT

/01/

.ENABL

Enable lower case

File LEX82B.MAC

ProSram to attach to an existin~ reSionv create a
vi T'tua I add T'es-:;; 1;..1 :i. nciDw (mapped on c rE~atj. c)n) v mod :i. f~~
the first b~te of the re~iDn, read ASCII data from the
resion, detach from the re~ion and mark it for deletev
and finall~ exit. The resion will be deleted on last
detach.

7
8

9
10
11

12
:L ~~
14

Assemble and task-build instructions:

:1. !7.i

>MACRO/LIST LB:[1,1JPROGMACS/LIBRARY,dev:CufdJ->LEX82B
>LINK/MAP/OPTION LEX82B,LB:[1,1JPROGSUBS/LIBRARY
>Option? WNDWS=:L
>Option? (RET>

18
19

:~5

RnB:

26
27

28
29
30

32
33
:34
3~j

;

+MCALL EXITSS,RDBBK$,WDBBK$,ATRGSC ; S~stem
; macros
.MCALL CRAWS,DTRG$S,DIR$,QIOW$S
; SUPplied macros
.MCALL DIRERR,IOERR
RDBBK$ O,MYREG,GENv(RS+WRT!RS+RED!RS+MDL!RS.DEL>
Define resion with:
- 0 (32. word blocks)
ret~rned after attach
.... MYREG
Nam€·~
.- GEN
Parti t:i.on
Mark for delete on last detach
Attach with ready write and delete access

WIN:
WDB:

CRAWS
WDB
;DPB for create address window
WDBBK$ },200,O,O,O,(WS.MAP!WS.RED!WS+WRT>
Define window with:
API:~
=7
Size
200 (32. word blocks)
Off~:;(-?t il". re~:HDn - 0 (32. word blocks)
l..en~:jth in T'f:~~.~~ion
o (32. word blocks)
returned when mapped
Map on CT'eate with read and wT'ite access

IOSB:

.BLKW
=128.

ATRGSC

RDB
ERRl

:'56
37
:'58
3~~

40
41
42

43
44
4!5

46
47
48
49
50

I~SIZ

STAI:n' :

BC~)

MOV
DIRt

liD status block
size in b~tes

R~Sion

Attach to reSion
; Check for error
RDB+R~GID,WDB+W.NRID ; Move reSion ID
, into WDB
tWIN
; CT'eate window

105

Dynamic Regions
SOLUTION

:1. ~j

INTEGER RDB(8),WDB(S)
BYTE IDATA(1.2S)
C This common block will align with the address'window
COMMON IDATA/IDATA
r RDB = Resion definition block with the followins
C p r(),Pf~ rt :i. (·?S :
C
Si ~.:,:\:?
o (32.-word blocks)
C
filled in when attached
MYI:~EG
Name
C

17
18
19

20
21
22
23

24
2~i

26
27
2B
2(1

30
3:1.

32
33

r WDB = Window definition block with the followins

C
("'
C
C

37
38
39

40
41
4':>
4:"5

44
45
46
47
48
49
~jO

5:1.
5:~

54
55
!:i6
!:;7

58
59

60
61
b2
63

GEN

Protection
WO:none,SY:RWED,OW:RWED,GR:RWED
Mark for delete on last detach
C
Attach with delete, write and read access
C Initialize the RDB
DATA RDB IO,O,3RMYR,3REG v3RGEN~3R
1.1:L700001

3~:;

31.)

Part.:i.1',:i.on

C
C
C

F' roP€'~ T'1', :i. e~;; :

APR
Size
Offset in reSion
Lensth of window

200(S) (32.-word blocks)
o (32.-word blocks)
o (32.-word blocks)
filled in when mapped
C
C
Map on create with read access
C Initialize the WDB
DATA WDB 1·3400,O,·200,O,O,O~1203,OI

c
C At tach

rf.·~~:.H on
CALL ATRG (RDB,IDS)
C Check for error on attach
IF (IDS .LT. 0) GOTO 100
C Move reSion id to WDB
WDB (4) :=;RDB ( 1. )
C Create and map windoW
CALL CRAW (WDB,IDS)
C Check for error
IF (IDS .LT. 0) GOTO 200
C Place ASCII Z in first b~te
IDATA(1.)~-::/Z/

C Print contents of resion
10
WRITE (5,11) IDATA
11
FORMAT (/ /,64A1)
C Detach from ~esion and delete it
CALL DTRG (RDB,IDS)
C Check for error
IF (IDS .LT. 0) GOTO 300
C And Jump to exit
GOTO !500

107

Dynamic Regions
SOLUTION
3.

.TITLE
.IIrENT
.ENABL

1
,")

.:..

SNDREF
lOll
LC

; Enable lower case

4
..,'

File LEX83A.MAC

b
7
B
9

Modified to send to a 2nd receiver RCVRF2 in
addition to RCVREF

I::"

;;EX
;;EX

LEX83A creates a 64-word (2 block) unnamed reSion and
fills it with ASCII characters. It then sends the
reSion to RCVREF, and then waits for RCVREF to receive
the reSion. (This is sisnalled by event fla~ t1.) It
then prints a messaSe and exits. Since the area is
unnamed, it is autDmaticall~ deleted when the last
attached task exits.

1.7
lB

Assemble and task-build instructions:

1.0
11
12

14
1!5

1,9

>MACRO/LIST LB:C1.,1.JPROGMACS/LIBRARY,dev:[ufdJ-;;EX
-- >LEXB:'5A
>LINK/MAP/OPTION LEX83A,LB:[1,1.JPROGSUBS/LIBRARY
Option? WNDWS=1

21
2:~~
2~5

Install and run instructions: RCVREF must be installed.
LEX83B must be installed as RCVRF2. Run LEX83A first,
then run RCVREF and RCVRF2 (either one first)

:~~ ~j

26
27
2B
2<1

,..

~MCALI...

• MCALI...
.MCALL.

]()

:31

~MCAI...I...

3:3

"NI...IST

QIOWtC,QIOWSS,RQSTSC ; S~stem macros
WTSESC,EXITSS,RDBBKS,WDBBKS
CRRGSS,CRAWSSvSREFSC
DIRERR
; SUPplied macro
BEX ,
; SUPPRESS DATA

34
:!;S

Define region with:

Siz(;~

:'57
:H?

Nam€~

Partj, tion
Protection

39
40
41

32--WORD BLOCKS
none
00- GEN
- WO:none,GR:RWED
OW: I~WED, SY: none

Attach on cl"eate
Read and write ac~ess desired on attach

42
43
44
45

,- 2

Rpr~()

F~STAT

.... 170()17
= RS.ATT!RS.RED!RS.WRT

46
47

109

Dynamic Regions
SOLUTION
QIOW$C

99
100
101
102
103
104
105

1$:

DIREFH~

2$:

106

:3$:

DJr';:ERR
DIRERR

107
lOB
109
:L10

111
112
l
~

.(..

4
c·
J

7
8

9
10
11
12
13
14
1'~'
....
}

1,6

4$:

It IF~EI:~R

DIRERR
DIRERR

8!1; :

DIRE~:R

DH~EF~R

+END

;

Dif:)pla~

me!:.;~;age

BT'anch on dir e T' T'O T'
E:d.t

ON CREATE OR ATTACH I~EGION>
ON CREATE OR MAP WINDOW>
<ERI=i:OR ON SEND BY I:;:EFERENCE>
<EI:;:I:;:OR ON lST W~-;:ITE>
<EI:;:/:;:OR ON WAIT FOR>
<ERROR ON 2ND WRITE>
<ERROR ON 2ND SEND BY REFERENCE>
<ERROR ON 2ND WAIT FOR>
START
<EI~RCJF~

<EI~F:()I~

;; EX
;; EX

PROGRAM SNDREF·
C
C Fil€~ l.EX83A.FTN
C
f' Modified to send the region b~ reference to RCVRF2
C in addition to RCVREF
C
C This program creates a 64-word unnamed region and

! !EX
! !EX

C fills it with ASCII characters. It then sends it bw
C reference to task RCVREF, and waits for RCVREF to
C receive the region+(This is signalled bw event flag
SNDREF then prints a message and exits. Since
C 41.)
r the area is unnamed, it is automaticallw deleted when
C the last attached task exits+
C
C Task-build instructions:

Bes
EXIT$S
ET'r(:)r code

5'* :
6$:
?~; :

C
C
C
C

IO.WVB,5,2",,~MES2,LMES2,40>

>LINK/MAP/CODE:FPP/OPTIONS LEX83A,LB:[1,lJFO-! !EX
->ROTS/LIBRARY
! !EX
Option'? WNDWS=l
Option? VSECT=DATA:l60000:200
Option"~ <RET}

2:3

24
25
26
27

f' Install and run instructions: RCVREF must be installed.
! !EX
C LEX83B must be installed under the name RCVRF2.
C

C Run LEX83A first, then run RCVREF and RCVRF2 (in
e:ith(.~r order)

2E1

29
30
31
32

~53

C
C

! !EX

RDB = Resion definition block with the followin~
propeT'ties:
2 32-word blocks
Si ~·~e
none
Name
GEN
Partiticm
WO:none,SY:RWED,OW:RWED,
Protection
GR:none
Attach on creation
Read and write access desired on attach

III

Dynamic Regions
SOLUTION
85
86
87

88
89
90
91
'7'2

93
94
95
96
97

98
99

100
101
102
103
104
105
106

C ErT'or h<~ndling code
WRITE (5,110)IDS
100
110
FORMAT (' ERROR CREATING REGION, DSW - ',14)
GOTD 600
2()()
WRITE (5,210)ID9
210
FORMAT (' ERROR CREATING WINDOW, DaW
',14)
GO TO 600
WRITE (5,410)ID8
400
FORMAT (I' Ef,ROR IN SEND-BY'-REFERENCE, DSW ::: /,14)
410
GOTO 600
45()
WRITE (5,460)IDS
460
FORMAT (' ERROR IN 2ND SEND-BY-REFERENCE, DSW
1 == ',14)
! !EX
GOTO 600
! !EX
500
WRITE (5,510)IDS
',14)
510
FORMAT (' ERROR ON WAIT, DSW
GOTD 600
! !EX
~=j~50
WRITE (5,560)IDS
! !EX
FORMAT (I' ERROR ON 2ND WAIT, DSW - ',14)
560
! !EX

600

CAll EXIT
END

.TITlE
.IDENT
.ENABL.

1
2
3

L.EX8~5B

101/

Enable lower case

File

LE~83B.MAC

7
8
9
10
1~

12
13
14
15
16
.17

Second reciever for SNDREF (modifed to LEX83A).
Program to receive-bY-reference (mapped on creation),
modify the first data byte in the region,
read ASCII data from the region, detach from the
region and exit. The region will be deleted on last
detach.
The first word in the region contains the count of the
number of bytes of data in the resion.
Assemble and task build instructions:

:1.8

19
20
21
22

>MACRO/LIST LB:[l,lJPROGMACS/LIBRARY,dev:[ufdJ
->LEX83B
LINK/MAP/OPTIONS LEX83B,LB:C1,lJPROGSUBS/LIBRARY
option? WNDWS=l

113

Dynamic Regions
SOLUTION

PROGRAM LEX83B

C File LEX83B.FTN

6
7
8

9
10
11
12

13
14
15
16

C LEX83B receives bw reference a re~ion from the task
It maps to the re~ion, modifies the ~irst
C b~te, prints out the contents, and exits. The re~ion
C is deleted on last detach.
C
C Task-build instructions: Include these options
C
WNDWS=l
C
VSECT=DATA:160000:20000

r LEX83A.

r Install and run instructions: LEX83B must be installed.
C as RCVRF2. RCVREF must be installed. Run LEX83A first,
C then run LEX83B and RCVREF (in either order).

:L7

18
19
20
21
22
23
24

C WDe
C
C
C

= Window definition block with:

27
28
29
30

7
200(8) 32-word blocks
Allow for full APR
r
Offset in re~ion 0 32-word blocks
C
Len~th of region
0 32-word blocks (to be filled
C
in on receive)
r
Read and write access
INTEGER WDB(8)
DATA WDB/-3400,0,-2,0,0,·0,·3,O/
BYTE DATA(128)
C This common block will ali~n with the address window
COMMON /DATA/DATA

3:1.

C Create address window--do not map at this time
CALL CRAW(WDB,IDS)
C Check for error on create
IF (IDS .LT. 0) GOTO 200
C Now set WDB status for mappin~--will be done bw
r r(·:~cf.~' i. ve--b~- refe renee
WDB(7)=WDB(7)+-200
C Receive data and map
CALL RREF(WDB"IDS)
C Check for error
IF (IDS .LT. 0) GOTO 100
C Modify first value
DATA(1)='9'
C Calculate number of bwtes of data - length in blocks
C returned at WDB(6)
NCHAR = 64*WDB(6)
WRITE(S,10) (DATA(I),I=l,NCHAR)
10
FORMAT (' ',64Al)
C Go e :.~ i t
GOTO 300

33
34
35

36
37
38
39

40
41
42
43

44
45
46
47
48
49
~j 0

APR
Size

115

File I/O
TEST /EXERCISE
1.

Next to each activity, write 0 for open, I for I/O operation,
or C for close,
to
identify which step of file I/O is
involved.

Records are read from the file.

Access rights to the file are checked.

Existing file is located on disk.

Internal buffers are placed in a pool for re-use.

Records are written to a file.

Describe three functions performed by the Files-II ancillary
control processor
(FllACP)
when a
task creates a new file
containing seven blocks~

117

File I/O
TEST /EXERCISE
b.

A company uses COBOL for
its applications.
It has a
payroll file which is processed in order every two weeks.

119

File I/O
SOLUTION
1•

Next to each activity, write 0 for open, I for I/O operation,
or C for
close,
to
identify which step of file I/O is
involved.
I

Records are read from the file.

Access rights to the file are checked.

Existing file is located on disk.

Internal buffers are placed in a pool for re-use.

Records are written to a file.

Describe three functions performed by the Files-II ancillary
control processor
(FllACP)
when a
task creates a new file
containing seven blocks.
Any three of the following:
Allocate a file header
Initialize the file header
Set up file retrieval pointers
Create a directory entry
Allocate blocks to the file
Connect a task's LUN to the file

121

File 1/0
SOLUTION
b.

A company has a file of customer
records.
Each record
contains the company name,
the address,
the contact
person, and the equipment bought.
At different times, the
records are accessed using company name, city, or contact
person.
Best answer
is RMS only since an
indexed file with
multiple
keys
is needed for fastest access.
FCS can be
used, but access by key value is
impossible.
You would
have to
step through the file, checking all records, to
locate the one you want.

A company uses COBOL for
its applications.
It has a
payroll file which is processed in order every two weeks.
RMS only;
FeS.

COBOL is supported under

123

RMS,

but

not

under

File Control Services
TEST / EXERCISE
1.

Modify CRESEQ so that each record in the
file contains
text input from the terminal preceded by "AAAA".

the

Write a task that appends records to a file you have created
(using one of the FCS example programs or the editor).

In MACRO-II, modify the task CREFXA so
that
input
from
terminal uses FCS routines instead of QIO directives.

Write a task that requests input from a terminal of the form:

the

n, text
Use the input to update the nth record of FIXED.ASC, which has
fixed
length
records.
Use random access and do not truncate
the file.
5.

In MACRO-II, modify the task BLOCKI or BLOCK2
writes or displays two virtual blocks ata time.

(Optional) In MACRO-II,
modify the task CSI so
that
the
subroutines DISPLY and DELETE actually display and delete the
file.
Caution:
DELET$ delete the highest version of a
file
if no version number
is specified.
(See Chapter 6 of the
IAS/RSX I/O Operations Reference Manual for information about
the routines GCML and CSI.)

125

that

File Control Services
SOLUTION
1.

.TITLE
.IDENT
.ENABL

1
,.)
.:.0

CI:;:ESEO
/()l/

L.C

5
6

File LEX:l.Ol.MAC

7
8
9
10

Modified to preced each record with AAAA
CRESEO creates a file VARI.ASC. It reads
records from TI:, and places them in the file.
A -Z terminates input and closes the file.

:L2
13
14
15
16
17
18
19
2()
21
22

Assemble and task-build instructions:
MACRO/LIST LB:[1,1]PROGMACS/LIBRARY,dev:CufdJ.... >CRESE[~
LINK/MAP CRESEQ,LB:[1,1]PROGSUBS/LIBRARY
;-

2~5

• MCAL..L
.MCALL
.MCALL
.MCALL.

EXSTSC,QIOWSC,QIOWS,DIRS ; S~stem macros
FSRSZS,FDBDFS,FDATSA,FDRCSA,FDOPSA ;
NMBLKS,OPENSW,PUTS,CL.OSES ;
DIRERR,IOERR,FCSERR ; SUPplied macros

FSRSZS

24
1")1::'

A-<t..'

;

1 file for record I/O

....

,.)
.:.0/

28
29
:'50

Define file descriptor block for VARI.ASC
Al1ocat(,:~ the FDB
Variable lensth records,
Listins - implied
carria~e return, line
feed
Seauential access and
reco T'd I /0 b~
default, BUFF is
user record buffer
Use LUN 1, file spec
at FNAME
·VARI.ASC a

FDBDFS
FDATSA

R.VAR,FD.CR

FDRCSA

,BUFF

FIIOF'SA

1"FNAME

FNAME:

NMBLKS

VARI,ASC

; Local
BUFF:
INBUF:
lOST:

Data
.ASCII
.BLKB
.BL.KW

/AAAA/
SO.

USER RECORD BUFFER

I/O STATUS BLOCK

47
48
49

.LI9T
.EVEN

BEX

.ENABI...

LSB

FDB:

:'51

3'')
33
34
~

3~5

3b
37
38
39
40
41
4':)

43
44
4~;

;;EX
; H::X

127

File Control Services·
SOLUTION

PROGRAM CRESEQ

C FILE LEXI01.FTN

!CREATE FILE SEQUENTIALLY

C Modified to precede each record with AAAA·

7
8
10
11
12
13
14
15
16
17
18

C This task creates a file of VARI.ASC of
C variable-Ien~th records usin~ seauential record access.
C The records are input from the terminal and copied to
C the file.
The process stops when the operator twpes
C CTRL/Z at the terminal.
C
BYTE BUFF(84),INBUF(80)
! !EX
E(~UIVI~LENCE (BUFF(5)"INBUF(1»
'!EX
INTEGER LEN
DATA BUFF(1)"BUFF(2),BUFF(3),BUFF(4)
l/'A','A','A','A'1
C

20
21
22
23
24
25
26
27
28

C OPEN FILE
C
C Default access is seauential
C Default is formatted liD for seauential files

C
OPEN
:t.

TYPE
*,'TYPE IN TEXT, TERMINATE EACH RECORD
1 WITH A CARRIAGE RETURN'
*,'TERMINATE INPUT WITH A CTRL/Z'
TYPE

C Loop
10
11

32
35
36
37
38
39
40
41
42
43

(UNIT=l,NAME='VARI.ASC',TYPE='NEW',
CARRIAGECONTROL='LIST')

29
30
31

! !EX

READ (5,11,END=100) LEN"INBUF
FORMAT (Q,80A1)

Read reco T'd' 'EX

LEN ::: LEN+4

Add 4 fOT' A's
, 'EX
Write record
to file

WRITE (1,12) (BUFF(I),I=1,LEN)
FORMAT (BOA1)
GO TO 10
C Close file and exit
100
CLOSE
(UNIT=1)
CALL EXIT
END
12

129

File Control Services
SOLUTION
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
71::,J
76
77
78
79
80
81
82
83
84
85

CHOW$C

OKlO:

MOV
PUT$
BR

IO.RVB,5,1"IOST,,(BUFF,80.); Read a
line from TI:
ItIROK
Branch on [Ii T'ective ok
tEF'ICHO,Rl
Set IJP for $EItMSG
t.IISW,R2
SHOERR
Branch to show €:'T'ro r
and e~·dt
lOST
Check for 1/0 errOl'
OKlO
BT'anch if 1/0 ok
Check for EOF
tIE.EOF"IOST
EXIT
If EO, close and e~·~ it
10ST,RO
1/0 status is sign
e~·ctended and F,laced
in argument block
RO,ARG
for $EDMSG call
tARG,R2
Set '.J? for $EDMSG call
tEFDCHO"Rl
SHOERR
Branch to show error
and e~·dt
Length of l'ecord to FU
IOST+2,Rl
tFDB"Rl,ERR2
Write neNt record
10$
Get ne~·~t record

EXIT:

CLOSE$
BeS
EXST$C

tFDB
EI:':R3
EX$SUC

Bec
MOV
MOV
BR
DIROK:

MOV
MOV
MOV
BR

9:~

94
91::,J
96
97
9EJ
99

Close file
BT'anch on FCS En' 1'0 r
E~·dt with status of :I.

; Error Processing
ERR1:
ERR2:
F.ERR+l(RO)
ERI:':3:
TSTB

BEQ
MOV

87
88
89
90
91
92

TSTB
BGT
CMF'B
BEO
MOVB

10:

BR
MOV

FINSET: MOVB
MOV
MOV
SHOERR: MOV
CALL
MOV
DIR$
CLOSE$
EXST$C
.END

Iii rf.~ct, i ve error or 110
error
Branch on 1/0 errOl'
10
tEFCDIR,R1
Set UP for $EDMSG,
directive error
Branch to finish setup
FINSET
Set UP for $EDMSG" lID
tEFCSIO"Rl
error
F.ERR(RO),RO
FCS error code
RO, Ar~G
is sign e~·~tended and
placed in ars block
tARG,R2
$EDMSG argument block.
tOBUFF,RO
OutPIJt buffer
$EDMSG
Format err'or messasE'
R1,PRINT+Q.IOPL+2 ; Size of message
tPRINT
Print erT'OT' ITleSSage
Close file
tFDB
EX$ERR
E~·d t, with statu~; of
START
'")
A..

131

File Control Services
SOLUTION
3.

1
2
3
4

5
6
7
8

9
10
11
12
13
14
1 ...}
16
17
18
19
20
21

.TITLE
.IDENT
.ENABL

;+
~':'ile

Enable lower case

LEXI03.MAC
~et

;;EX
;;EX

CREFXA opens FIXED.ASC for write, inputs records
from TI: and puts them seGuentiallw to the file.
A ~z terminates input and closes the file.
.MCALL

EXSTSC,aIOWSC,QIOWS,DIR$

.MCALL
.MCALL
.MCALL
.MCALL

FSRSZS,FDBDFS,NMBLKS

RSIZ
lOST:
PRINT:
BUFF:
OBUFF:

.NLIST
30.
• BLI<W
QIOWS
.BLKB
.BLKB

ARG:

.BLKW

~54
~55

Modified to use FCS instead of aID's to
input from TI:

23
24
25
26
27
28
29
3()
31
32
33

CREFXA
/01/

::::

EFDaIO: .ASCIZ
EFlaIO: .ASCIZ
EFCDIR: .ASCIZ
EFCSIO: .ASCIZ

FDRCSA,FDATSA~FDOP$A

OPENSW,GETS,PUTS,CLOSES
OPENSR
; SUPF"ress ASCI I
; Record size (bwtes)
; aIO status block
2
IO.WVB,5,1",,{OBUFF,O,40>
RSIZ
User record buffer
80.
Output buffer for
error messages;
1
Ar~ument block for
SEDMSG
IDIRECTIVE ERROR ON QIO. ERROR CODE :::: %D.I
1110 ERROR ON QIO. ERROR CODE:::: %D.?
IFCS DIRECTIVE ERROR. ERROR CODE:::: %D.I
?FCS liD ERROR CODE. ERROR CODE:::: %D.?
BEX

.EVEN
.LIST

BEX

Show offsets

38
39

FSRSZS

2 files for record liD

:36

4()

41
42
43
44
45
46
47

; H~X

FDB:

FILE:

FDBDFS
FDRCSA
FDATSA
FDOPSA
NMBLKS

; File descriptor block
,BUFF,RSIZ
; User buffer and size
R.FIX,FD.CR,RSIZ; Fixed len~th records,
implied <CR><LF>
l.Jse LUN 1
1"FILE
FIXED,ASC
FIXED.ASC

133

File Control Services
SOLUTION
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

; Error Processing
ERR1:
ERR2:
ERR3:
ERR4:
F.ERRtl(RO)
TSrB

BEQ
I1IRERR: MOV
10:

BR
MOV

FINSEr: MOVB
MOV
MOV
SHOERR: MOV
CALL
MOV
I1IR$
CLOSE$
CLOSE$
EXST$C
.END

Directive error or lID
error
10
Branch 01"1 lID error
; ;EX
tEFCDIR,Rl
Set U? for $EDMSG,
di rectiv(-? eT'rOT'
FINSEr
Branch to finish setup
Set UP for $EDMSG, 110
tEFCSIO"Rl
error
F.ERR(RO),RO
FCS error code
RO,ARG
is sign e~·,tend€~d and
placed in aT'g block
tARG,R2
$EDMSG argument block
Output buffc-?T'
tOBUFF,RO
$EDMSG
Format error messcs!,je
Rl,PRINTtQ.IOPLt2 ; Size of lTIeSSc~gf:~
tP~~INr
PT'int eT'T'C)r ITlessa~ie
iFDB
Close file
iFDBI
Close -file- at T1: ~ ; EX
E~·:i t, with status of 2
EX$ERR
START

135

File Control Services
SOLUTION
50
51
52
53
54
~;5

57
58
59
60
61

.ENABL

START:

LSB

Allow local symbols
to cross Psect
bOI.Jndaries

OF'EN$U

Open file for update
;
(includes extend)
; Clear buffer tC) all blanks each time
:J:~-;:SIZ,Rl
lOS:
MOV
Record size
R2 =) buffer
MOV
tBUFF"R2
i ~ , (R2) t
20$:
MOVB
Move in a blank.
Rl,20$
SOB
Continue until done

62
63
64
65
66

68
69
'70

71
72
73

74
75
76

77
78
79

80
81
B2

84
85

86
87
88
89
90
91

QIOWSC

IO.RPR,5,1"IOST"(BUFF,RSIZ,,INPT,LINPT,'S)
Prompt and ~et input
CMPB
tIE.EOF,IOST
Check for ~Z
BEQ
EXIT
If -Z, exit
MOV
tBUFF,RO
Set UP to convert
CALL
SCDTB
;
record t to binar~
Check for ~ood conversion, character after t is
returned in R2 (it should be a M,M)
CMPB
t'"R2
; Is it a comma
BEQ
GOOD
; Branch on ~ood
conveT'sion
QIOWSC IO.WVB,5,1",,(CNVER,LCNVER,40)
Display error messaSe
BCS
ERR4
Branch on directive
error
BR
lOS
Get next input
GOOD:
PUTSR
tFDB",Rl"ERR2
Write record to output
file
BR
lOS
; Get next input
; Close file, display message, and exit
EXIT:
CLOSES tFDB,ERR3
; Close file
QIOWSC IO.WVB,5,1",,(BUFF1,LEN1,40> ;Write
; messaSe to operator
BCS
ERR4
; Branch on error
EXITSS
ERr~ 1 :

ERR2:
ERR3:

(12

CLOSES
MOVB
MOV

tFDB,ERR3
F • ERR (RO) , r~o

RO,IOST

(14
95
96
(17
98
99
lOO
l01

IOERR:

MOV
T8TB
BEQ
MOV

tIOST,R2
F.ERRtl(RO)

BR
MOV

COMME
tEMESI,R1

10ERR

tEMESD,R1

137

Close t'ile
Move FCS error code
to arSument block
for SEDMSG
Set UP for SEDMSG
1/0 or directive error
Branch on 1/0 error
Set UP for dir error
ITlessase
Branch to common code
Set UP fdr 1/0 error
message

File Control Services
SOLUTION
5.

1
2
3
4

.TITLE
.IDENT
.ENABL

BLOCK2
lOll

Enable lower case

File LEX105.MAC

; ;EX

7
8
9
10
11
12
l3
14
15

Modified to work on 2 virtual blocks at a time ;;EX
**-BLOCK2 prompts at TI: for a virtual block number
and then reads and displa~s that block of -BLOCK.ASC·
;-

.MCAl.L
.MCALl.
.MCALL

QIOWS,DIRS,QIOWSS,EXSTSS
FDBDFS,FDRCSA,FDBKSA,FDOPSA,NMBLKS
FSRSZS,OPENSR,READS,WAITS,CLOSES

:16

17
18
19
20
21
.'......
23
24
25
26
'")1")

2B
,29
30
31
3'".:..
33
34

CR
LF
MESl. :
LENl
MES2:
;

LEN2
MES3I:
MES:3D:
MES4I:
MES4D:
MES5I:
MES5D:
BUFF:

3 ...c1

36
37

38
39
40
41
42
43
44
45
46
47
48
49
50

.SBTTl. MESSAGES
.NLIST BEX
:::: 15
:::: 12
.ASCII IFIRST VIRTUAL BLOCK: I
:::: • - MESl
.ASCII <CR><LF>/HERE ARE THE BLOCKS

FDB:

I<CR><LF>
; ; EX

:::: • - MES2
.ASCIZ /1/0 ERROR FROM OPENSR, CODE:::: XD./
.ASCIZ IDIRECTIVE ERROR FROM OPENSR, CODE:::: XD.I
.ASCIZ /1/0 ERROR FROM READS, CODE:::: XD.'
.ASCIZ IDIRECTIVE ERROR FROM READS, CODE - XD.I
.ASCIZ /1/0 ERROR FROM WAITS, CODE:::: %D.'
.ASCIZ IDIRECTIVE ERROR FROM WAITS, CODE = XD.I
; STORE RESPONSE HERE
.BLKB
80 •
.LIST
.EVEN
.SBTTL

LOCAL STORAGE

FSRSZS

FDBDFS
FDRCSA
FDBKSA

FDB FOR INPUT FILE
FD.RWM
; READ/WRITE MODE
BLOCK,1024.,,1,IOSB ; EF 1, BUFFER ADR,;;EX
SIZE
1"FILE
LUN 1, DFNB
BLOCK,ASC
NAME IS BLOCK.ASC

FIl.E:

FDOPSA
NMBLKS

VBN:
BLOCK:
IOSB:

• WORD
• BLKW
.BLKW

BEX

NO FSR BUFFER NEEDED
FOR BLOCK 1/0

0,1
512.

DEFAULT VBN
BLOCK BUFFER

139

File Control Services
SOLUTION
101
102
103
104
l()S
1()6
107
108
1()9
110
111
112
113
114
115
116
117
118
119
120
121
122
123

tMES4I,Rl
FCSERR

=:> I/O error messar.je 4
Branch to common codf-?

F.ERR+l(RO)
IOERR3
tMES5IhR1
FCSERR
tMES5I,Rl

1/0 or di r~~ct,ive errC)f'
Efrarlch on I/C) errOT'
=:;:. Di T' error messagf.~ 5
Brcmch to common code
:::::> I/O error lTte~;~;age ,.1
FALL INTO COMMON CODE

MOVB
MOV
MOV

F.ERR(RO),R2
R2,IOSB
tEX$ERf\,R5

Sign eNtend error code
and lTtove into lOSB
E~·dt status in R5

MOV
MOV
CALl.
aIOW$S

tIOSB,R2
tBUFF,RO
$EDMSG

Set, UP for $EDMSG

IOERR2: MOV
BR
ERR3:
TSTB
BEC~

MOV
BR
IOERR3: MOV

I::-

FCSERR:

FORMAT:

tIO.WVB,t5~tl",,<tBUFF,Rl,t40>
lTtessa~:.~e

EXIT:
CLOSE$
EXST$S
.END

tFDB
R5
START

Close the file
with status

E~·dt

141

Di!:;pla~

File Control Services
SOLUTION
51
52
53

CBLK:

CSI$
.BLKB
.EVEN

Define CSI offsets
allocate CSI storase

C.SIZE

~)4

55
56
57

[tEMSK _. 1
[lIMSK = 2
SWTBL:
CSI$SW
CSI$SW

58
59

DE,DEMSK
DI,DIMSK""NUM

60
61
62
63
64

65
66
67

68
69
70

CSI$ND

Delete mask
Displa~ mask
Switch descriptor table
Delete switch - DE
Displa~ switch = DI,
also allow DI:N
End of switch table

OCTAL,COPY,2,NUM; Value N for IDI:N is
in octal and will
be stored in COpy
CSI$ND
End of switch value
table
;GET COMMAND LINE BLOCK DEFINITIONS
CSI$SV

FSRSZ$

GCML uses record I/O;;EX

GBLK:

GCMLB$

,CSI,,5

FItB:

FDBItF$

Prompt with 'eSI' on
LUN 5
FDB for file to delete
or display.
URB AT TBUFF, lensth
132.
LUN 1, dataset
descriptor from csr

72
73

74
75
76

FDRC$A

,TBUFF,132.

FItOP$A

1,CBLKtC.DSDS

77
78

79
80
81

; NOTE: Need a 2nd FItB for display

82
83

FItBO:

FDBDF$
FDAT$A

R.VAR,FD.CR

FDRC$A

,TBUFF,132.

FDOP$A

2,DSPTO

FDB for output to TI:;;EX
Var len~th records, ;;EX
list format
;;EX
URB at TBUFF, lensth;;EX
132.
;;EX
LUN 2, dataset
;;EX
descriptor at DSPTO ;;EX
Dataset descriptor
;;EX
for TI:. No Ule or ;;EX
name needed.
;;EX
;; EX
;; EX

86
87

89
90

DSPTO:

91
(72

93
94
95
96
97
98
99
100

DEV:

.WORIt
LDEV,DEV
.WORD
0,0
.WORD
0,0
.ASCII ITI:I
LDEV=.-DEV

.EVEN
JMPTBL: • WORD
COpy:

.WORD

NONE,DELETE,DISPLY ; Jump table for
subroutines dependin~
; on switches
; Value for N in IDI:N
1

143

File Control Services
SOLUTION
151
152

CALL

1~)3

RETURN

OUTMS

Call OUTMS, as a
subroutine
Return

;; EX
; ; EX
; ; EX

154

155
156
157
158
159
160
161
162
163

Common displa~ messa~e code - a subroutine since it ;;EX
is not a common return point
;;EX
OUTMS:

MOV
MOV
MOV
CALL
QIOWSS
RETURN

iBUFF, I~()

Set UP for SEDMSG

tFMT,I~j,

tDATA,R2
SEDMSG
~ Edit message
tIO.WVB,t5,tl",,<tBUFF,Rl,t40>
; Return

164
165
166
167
168
169

Subroutine DELETE
***WARNING - THE HIGHEST VERSION NUMBER OF THE FILE ***
***WILL BE DELETED IF NO VERSION NUMBER IS SPECIFIED ***

170

DELETE: MOV

171
172

CALL

tDELTXT,DATA

Set UP for Dutput of

OUTMS

Call

/Tlessa~e

173
174
175
176
177

178
179
180
181

DELETS tFDB,ERRD
RETURN
; Delete err'or code
F.ERR(RO),R5
ERRD:
MOVB
R5,DATA+2
MOV
tDELTXT,DATA
MOV
COMME:

TSTB

182
183
184
185

BEa
MOV
BR

186
187
188
189
190
191

192
193
194
195

IOERR: MOV
DISf'ER: MOV
MOV
CALL
MOV
DIRS
EXITSS

displa~

subroutine
Delete file
Return

Extend sign on error;;EX
and move to ars block;;EX
Move pointer to delete;;EX
text
;;EX
Check for directive ;;EX
F.ERR+1(RO)
error or I/O error ;;EX
Branch on I/O error ;;EX
IOERR
Get format string
;;EX
tFMTERD,R1
Branch to common
;;EX
DISf'ER
error displa~ code ;;EX
Get format strin~
;;EX
tFMTERI,R:L
Set UP for SEDMSG
;;EX
tBUFF, I~O
; ;EX
tDATA,R2
; Edit messaSe
;;EX
SEDMSG
;;EX
R1,TYPE4+a.IOf'L+2 ; Size of messase
Displa~ messa~e
;;EX
tTYF'E4
Exit
;;EX

Subroutine DISPLY - Just displa~ a messa~e

196
197
198

DISF'LY: CALL
MOV

Save all reSisters
Set UP for output of
message
Branch to common
displa~ code

SSAVAL
tDITXT,DATA

199
200
201

CALL

;;EX
;;EX
;;EX

OUTMS

145