Digital PDFs

EY-0060E-SG-0201

May 1982

281 pages

Original

11MB

Document:	Programming RSX-11M in Macro A Self-Paced Course Volume II
Order Number:	EY-0060E-SG-0201
Revision:	0
Pages:	281
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/Programming_RSX-11M_Self-Paced_Training/EY-0060E-SG-0201_Programming_RSX-11M_in_Macro_Vol_2_1982.pdf

OCR Text

EY -0060E-SG-020 1

Programming
RSX-llM in MACRO
A Self-Paced Course
Volume II

EY-0060E-SG-020 1

Programming
R5X- 11 M in MACRO
A Self-Paced Course
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-10
DECSYSTEM-20
DIBOL
EDUSYSTEM
VAX
VMS

9/82/14

MASSBUS
OMNIBUS
OS/8
RSTS
RSX
lAS

CONTENTS
VOLUME I

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. •
• • • • • ••
• • • • • 17
OBJECTIVES. • • • • • • • • • • • •
• • • • • • • • 17
RESOURCES • • • . . • • • • • • • • • • . • • . • • • • • 17
WHAT IS A SYSTEM SERVICE?
• •
. • . . • • • . • 19
WHY SHOULD YOU USE SYSTEM SERVICES?
• • • . • • • • • • 19
To Extend the Features of Your Programming
Language. • • • • • • • • • • • • • •
• • • • • 19
To Ease Programming and Maintenance • • • • • • • • • 19
To Increase Performance. • •
• • • • • • • • • • 20
WHAT SERVICES ARE PROVIDED?
• • • • • • • • • • • • • • 20
System and Task Information. • • • •
. • • • • • 20
Task Control • • • • • • • • • • • • • • • • • • • • 21
Task Communication and Coordination..
• • • • • 21
I/O Peripheral Devices. • • • • • • •
• • • • • 21
File and Record Access. • • • • • • •
• • • • • 21
File and Record Access Systems • • • • • • • • • • • 22
Memory Use. • • • • • •
• • • • • • • • • • 22
OTHER SERVICES AVAILABLE. • • •
••••••
• .23
HOW SERVICES ARE PROVIDED. • • • • •
• • • • • • 25
Executive Directives. • • • • • • • •
• • • • • 25
Code Inserted into Your Task Image • • • • • • • • • 28
SYSTEM LIBRARIES • • • • • • • • • • • • • • • • • • • • 30

DIRECTIVES
INTRODUCTION
••••
• • ••
• • • • • • • • 35
OBJECTIVES. • • • • • • • • • • • • • • •
• • • • • 35
RESOURCES. • • • • • • • • • • • • • • • •
• • • • • 35
INVOKING EXECUTIVE DIRECTIVES FROM A USER TASK.
• .37
Directive Processing • • • • • • • • • • • • • • • • 37
iii

Functions Available Through Executive
Directives • • • • • • • • • • • • • • • • • • • • • 39
The Directive Parameter Block (DPB). • • • •
• .41
The Directive Status Word (DSW) • • • • • • • • • • • 42
Sample Program
•••••••••••••
• .43
DIFFERENT FORMS OF THE DIRECTIVE CALLS •
. • • • 46
The $ Form.
• • • •
•••• • •
. • • • 46
The $C Form..
• • • • • • • • • • • • • • • • • 49
The $S Form..
• • • • • • • • • • • ••
• .51
Repeated Use of a Directive with Different
Arguments • • • • • • • • • • • • • • • •
• .58
ADDITIONAL DIRECTIVE CONSIDERATIONS • • • • • • •
• .62
An Alternative Method for Error Checking • •
• .62
Run Time Conversion Routines • • • • • •
• .68
Notifying a Task When an Event Occurs • •
• .69
Event Flags • • • • • • • • • • • • • • •
• .69
Using Event Flags for Synchronization • •
• .70
Asynchronous System Traps (ASTs) • • • •
• .75
Synchronous System Traps (SSTs) • • • • • • •
• .82

USING THE QIO DIRECTIVE
INTRODUCTION • • • •
• • • • • • •
• • • • • 91
OBJECTIVES • • • • • • • • •
•• • • • •
• .91
RESOURCES. • • • • •
•••••••
• • • • • 91
OVERVIEW OF QIO DIRECTIVES • • • •
• • • • • • • • • 93
PERFORMING I/O . • • • • • • • • .
• • • • • • • 93
I/O FUNCTIONS. • • • • • • •
• • • • • • • • • • • ~94
Logical Unit Numbers (LUN) • • • •
• • • • • 95
Synchronous and Asynchronous I/O • • • •
• .95
MAKING THE I/O REQUEST
• • • • • • • • • • • • 101
Error Checking and the I/O Status Block. • • • • • 103
THE QIO DIRECTIVES • •
• • • • • •
• • • • 105
Synchronous I/O. •
• • • • • • • • • • • • 105
Asynchronous I/O • • •
• • • • • • • • • • • • III
Synchronization With Asynchronous I/O • • • • • • • 112
TERMINAL I/O • • • • • • • • • • • • • • • • • • • • • 120
Device Specific Functions • • • • • • • • • • • • • 120
I/O Status Block and Terminating Characters • • • • 120
Read After Prompt..
•••
• • • • • • • • 123
Read No Echo • • • • • • • • • • • • • • • • • • • 126
Read with Timeout. • • • • • • •
•• •
• • 128
Terminal-Independent Cursor Control • • • • • • • • 131
Formatting Output Data •
• • • • • • • • • • • 135
Formatting ASCII Data • • • • • • • • • • • • • • • 145

USING DIRECTIVES FOR INTERTASK COMMUNICATION
INTRODUCTION • • • • • • • • • • • • • • • • • • • • •
OBJECTIVES • • • • • • • • • • • • • • • • • • • • • •
RESOURCE • • • • • • • • • • • • • • • • • • • • • • •
USING TASK CONTROL DIRECTIVES AND EVENT FLAGS • • • • •
Directives • • • • • •
• • •
•
SEND/RECEIVE DIRECTIVES. • • • • • •
• • • ••
General Concepts • • • • • • • • • • • • • • • • •
Directives • • • • • • • • • • •
• ••
Synchronizing Send Requests With
Receive Requests • • • • • • •
•
Using Send/Receive Directives
for Synchronization • • • • • • • • • • • • • • • •
Slaving the Receiving Task • • • • • • • • • • • •
PARENT/OFFSPRING TASKING • • • • • • • • • • • • • • •
Directives Issued by a Parent Task •
• • • ••
Directives Issued by an Offspring Task • • • • • •
Chaining of Parent/Offspring Relationships •
•
Other Parent/Offspring Considerations • • • • • • •
Task Abort Status • • • • • • • • • • • • • • • • •
Summary of Various Methods of Data Transfer
Between Tasks • • • • • • • • • • • • • •
• • •
Other Methods of Transferring or Sharing Data
Between Tasks • • • • • • • • • • • • • • • • • • •

151
151
151
153
154
163
163
163
164
181
181
182
184
194
195
201
206
208
209

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

213
213
213
215
215
215
220
223
223
223
226
228
228
229

OVERLAYS
INTRODUCTION • • • • • • • •
• • • • • • • • • • • 235
OBJECTIVES •
• • • • • • • • • • • -'235
RESOURCE • •
•••• • • • •
• • • • • • • 235
CONCEPTS • •
• • •
• • • • • • • • 237
OVERLAY STRUCTURE..
• • • • •
• • • • • • • • 238
STEPS IN PROGRAM DEVELOPMENT USING OVERLAYS • • • • • • 241
THE OVERLAY DESCRIPTOR LANGUAGE (ODL). • • •
• • • 241
ODL Command Line Format.
• • • • • • • • • • • 241
TYPES OF OVERLAYS. • • • • • •
• • • • • • • • 245
Disk-Resident. • •
• • • • • • • • 245
Memory-Resident..
• • • • • • • • • • • • • • 247
LOADING METHODS. • • • • • •
•• •
• • • • • • 251
Autoload • • • • •
• • • • • • • •
• • 251
Manual Load. • • •
• •
• • • • • • 253
Comparison of a Task With No Overlays,
to One With Disk-Resident Overlays, and
One With Memory-Resident Overlays. •
• • • 253
Overlaying Techniques. • • • •
• • • • • • • • 254
LIBRARIES. • • • • • • • • • • • • • • • • • • •
• 262
GLOBAL SYMBOLS IN OVERLAID TASKS •
• • • • • • • • 268
Resolution of Global Symbols •
• • • • • • 268
Subroutine Calls • • • •
• • • • • • • • • • • 271
Data References. • • • •
• • • • • • • • • • • 271
Placing Data in the Root and Referencing It. • • • 272
CO-TREES • • •
••• • • • • • • • • • •
• • • 282
VOLUME II

ST ATIC REGIONS
INTRODUCTION • • • • • •
•••
• • • • •
•
OBJECTIVES • • • • • • • • •
•••• • • • • • • •
RESOURCE • • • • • • • • •
••••••• • • • • •
TYPES OF STATIC REGIONS. • • • • • • • • • • • • • • •
MEMORY ALLOCATION. • • • • • • • • • • • • •
•
MAPPING. • • • • • • • •
• • • ••
••••
REFERENCES TO A SHARED REGION. • • • •
• •
Techniques of Referencing.
• •••••••
Using Overlaid Psects (Data Only) • • • • • • • • •
Using Global Symbols (Data or Subroutines) • • • •
Using Virtual Addresses (Data Only)..
• •••
PROCEDURE FOR CREATING SHARED REGIONS
AND REFERENCING TASKS. • • • • • • • • • •
••••
Creating a Resident Common or Resident Library • •
Creating a Referencing Task • • • • • • • • • • • •
DEVICE COMMONS • • • • • • • • • • • • • • • • • • • •

289
289
289
291
293
293
299
301
301
302
303
307
307
315
326

DYNAMIC REGIONS
INTRODUCTION • • • • • • • • •
• • • • • • • •
OBJECTIVES • • • • • • • • • •
• • •
•
RESOURCE • • • • • • • • • • • • • • • • • • • •
•
SYSTEM FACILITIES. • • • • • • • •
•••• •
•
REQUIRED DATA STRUCTURES • • • • • • • • • • • •
•
Region Definition Block (RDB).
• •••••••
Creating an RDB in MACRO-II. • •
• ••••••
Window Definition Block (WDB).
• •••••••
Creating a WDS in MACRO-II • • • • • • • • •
•
CREATING AND ACCESSING A REGION. • • •
•• •
•
Creating a Region. • • • • • • • • • • • • •
•
Attaching to a Region. • •
• •••••••••
Creating a virtual Address Window.
• • • • • •
Mapping to a Region. • • •
• •••••
SEND- AND RECEIVE-BY-REFERENCE • • • •
• • • •
The Mapped Array Area. • •
• • • • ••

337
337
337
339
341
341
345
347
349
351
352
355
356
356
365
373

FILE 1/0
INTRODUCTION • • • • • • • • • • •
• • • • • •
OBJECTIVES • • • • •
• • •
••••••••
RESOURCES. • • • • •
• • •
• •••••
OVERVIEW • • • • • •
• • • • • • • • • • • • • • •
TYPES OF DEVICES • • • • • • • • • • • • • • • •
•
Record-Oriented Devices. • • • • • • • • • •
•
File-Structured Devices. • • • • • • •
•• ••
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 ..• •
• •••••
Supported Record Types • • • • •
• ••••••
Record Access Modes.
• ••••••••••••
File Sharing • • • • • • • • • •
• ••••••
RMS FEATURES • • • • • • •
• • • • • • • • • • • •
File Organizations •
•• • • • • • • • • • • •
Record Formats • • •
•• • ••
••••••
Record Access Modes. • • • • • • • • •
• •••
File Sharing Features.
• •••••••
Summary. • • • • • • •
• • • • • • • • • • • •
vi i

383
383
383
385
385
385
385
386
388
388
388
389
389
394
397
398
401
401
403
403
403
407
409
410
410
412
412
414
415

FILE CONTROL SERVICES
INTRODUCTION •
• • •
• • • • • • • • • 419
OBJECTIVES • •
• • •
• • • • • • • • • 419
RESOURCE • • • • • • • • • • • •
• • • • • • • • • 419
REVIEW OF FILE I/O • • • • • • • • • • • • • • • • • • 421
INTRODUCTORY EXAMPLE • • • • • •
••• •
• • • 422
USING FCS
• ~ • • • • • • • • • • • • • • •
• 427
Preparing to Open a File • • • • • • • • • • • • • 427
Initialization of the FSR. • • • • • • • • •
~ 429
The File Descriptor Block (FDB). •
• • • • 431
Functions of the FDB • • • • • • • • • • • • • 431
Allocating Space for FDBs. • •
• • • • • • 432
Initializing an FDB • • • • • • • • • • • • • • 432
Specifying New File Characteristics. •
• • 433
Selecting Data Access Methods. • • • •
• • • • 435
Specifying Data Access Methods • • • • • • •
• 437
Additional Initialization of the FDB
for Record I/O • • • • • • • • • • • • • • • • • • 438
Additional Initialization for Block I/O • • • • • • 439
Initializing the File-Open Section of FDB. •
• 440
Setting Up a File Specification in the FDB • • 440
Setting Up the Dataset Descriptor. • •
• • • • 441
Setting Up the Default Filename Block.
• • • • 442
Initializing the File-Open Section
Prior to Opening the File. •
• 443
Opening a File • • • • • • • • • • • • • • • • • • 450
ERROR CHECKING • • • • • • • • • • • • • • • • •
• 453
PERFORMING RECORD I/O. • • • • • • • • • • • • •
• 456
Different Forms of PUTS and GET$ • • • • • •
• 456
Sequential Access.
• • • • • • • • • • • • 457
Random Access. • • • • •
• • • • • • • 459
Closing the File •
• • . • • • • •
• • 460
PERFORMING BLOCK I/O •
• • • • • • • • • • • • 477
READ$ and WRITE$ Calls •
• • • • • •
• 477
Synchronization and Error Checking • • • • •
• 478
ADDITIONAL TOPICS. • • • •
•••
• • • • • • • 487
Deleting a File • • • • • • • • • • • • • • • • • • 487
File Control Routines. • • • • • • • • • •
• • 487
Command Line Processing.
• • • • • • • • • • • 488

APPENDICES
APPENDIX A
APPENDIX B
APPENDIX C
APPENDIX D
APPENDIX E

.········
· · 491
· · · · · · · · . . . · · 513
· 515
. · · · · ·· ·· ·· ··
· · 517
.
· · 519

SUPPLIED MACROS.
CONVERSION TABLES.
FORTRAN/MACRO-II INTERFACE
PRIVILEGED TASKS
TASK BUILDER USE OF PSECT ATTRIBUTES

viii

APPENDIX F
APPENDIX G
APPENDIX H

ADDITIONAL SHARED REGION TOPICS • • • • • • • • 523
ADDITIONAL EXAMPLES • • • • • • • •
• • • • 537
LEARNING ACTIVITY ANSWER SHEET • • • • • • • • 541

GLOSSARY

FIGURES
1-1
1-2
1-3

Using Executive Di~ectives to Service a Task. • •
.26
Using Executive Directives to Receive Services
from Other Tasks. • • • • • • • • • •
• • • • • • • 27
Code Inserted into Your Task Image. •
••• •
.29

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

Directive Implementation. • • • • •
• • • • • • • • 39
The Directive Parameter Block. • • •
• • • • • • • 41
The $ Form. • • • • • •
•• •
••••• •
.47
The $C Form • • • • • • • • • • • • • • • • • • • • • • 50
The $S Form.
••• •
.52
AST Mechanics • • • • • • • • • • • • • • • • • • • • • 76
Stack as Set Up by the Executive for ASTs •
• • • • 78
SST Sequence. • • • • • • • • • • • • • • • • • •
.84
Execution of a Synchronous I/O Request. • • • • •
.97
Events in Synchronous I/O • • • • • • • • • • • • • • • 97
Execution of an Asynchronous I/O Request.
• • 100
Event~ in Asynchronous I/O. • • • • • • • • • • • • • 100

4-1
4-2

Parent/Offspring Communication Facilities • • • • • •
Spawning Versus Chaining (Request and Pass
Offspring Information). • • • • • • • • • • • • • • •
Physical Address Space in an Unmapped System. • • • •
Physical Address Space in an l8-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 with Three Windows to Three Regions • • • • • •
Task in Figure 5-7 After Attaching to and Mapping
to a Fourth Region. • • • • •
•••
• ••••

183

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 • • • • • • • • • • • • •

240
240
246
249
263
270

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

195
217
218
219
221
222
225
231
232

...

. . . • 283
. . . • • • 284

6-7
6-8

Use of Co-Trees • • • •
Task With Co-Trees • • •

7-1
7-2
7-3
8-1
8-2
8-3

Tasks Using a Position Independent Shared Region • • •
Tasks Using an Absolute Shared Region • •
• •••
Program Development for Shared Regions • • • • • • • •
The Region Definition Block. • •
••• • •
•
The Window Definition Block • • • • • • • • • • • • •
The Mapped Array Area • • • • • • -.
• ••••

9-1

9-7
9-8
9-9

Example of Virtual Block to Logical Block,
to Physical Location Mapping • • • • • • • • • • • • • 391
How the Operating System Converts Between
virtual, Logical, and Physical Blocks • • • • • • • • 392
FILES-II Structures Used to Support Virtual-to-Logical
Block Mapping • • • • • • • • • • • • • • • • • • • • 393
Directory and File Organization on a Volume • •
• 395
Locating a File on a FILES-ll Volume.
•• •
• 396
Flow of Control During the Processing
of an I/O Request • • • • • • • • • •
•• • • • • 400
Move Mode and Locate Mode •
• • • • • • • 402
Sequential Files • • • • • • • • • • • • • • • • • • • 403
RMS File Organizations.
• • • ••
• • • • • • 411

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

The File Storage Region ••
••••••••
Move Mode Versus Locate Mode for Record I/O • • • •
Block I/O Operations. • • • • • • • • •
• •
The File Descriptor Block • • • • • ••
• •

•
•
•
•

F-l

A Shared Region With Memory-Resident Overlays.
Referencing Two Resident Libraries..
• ••
Referencing Combined Libraries • • • • • • • • •
Building One Library, Then Building
a Referencing Library • • • • • • ••
•••
Revectoring • • • • • • • • • • • • • • • • • •
Using Revectoring When Referencing Library
Has Overlays • • • • • • ~ • • • •
• ••••
Cluster Libraries • • • • • • • • • • • • • • •

• 524
• 526
• 528

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

F-2

F-3
F-4
F-5
F-6
F-7

....

295
297
300
342
348
375

426
428
429
431

• 530
• 531

·.

• 533
• 535

TABLES
.12

SG-l

Typical Course Schedules • • • • •

1-1
1-2
1-3

Examples of Use of Other Services • • • • • • •
Standard Libraries • • • • • • • • • • • • • • •
Resident Libraries.
• •••••••••••

2-1

Types of Directives
••••••••
Summary of Directive Forms.
• ••••

2-2

· . . .24
.30
.32

. . . . . .40
• 61

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

Common (Standard) I/O Function Codes • • • • • • • • • • 94
I/O Parameter List for Standard I/O Functions • • •• 102
Some Special Terminal Function Codes • • • • • • • • • 122
Sample Editing Directives for $EDMSG • • • • • • • • • 137

4-1

Task Control Directives and Their Use
for Synchronizing Tasks • • • • • • • • • • • • • • • 155
Stopping Compared to Suspending or Waiting • • • • • • 156
Event Flag Directives and Their Use
for Synchronizing Tasks • • • • • • • • • • • • • • • 156
The Send/Receive Data Directive • • • • • • • • • • • 164
Methods of Synchronizing a Receiving Task (RECEIV)
with a Sending Task (SEND) • • • • • • • • • • • • • • 165
Standard Exit Status Codes • • • • • • • • • • • • • • 184
Comparison of Parent Directives • • • • • • • • • •• 185
Directives Used by a Task to Establish
a Parent/Offspring Relationship • • • • • • • • • •• 186
Directives Which Return Status to a Parent Task •
194
Directives Which Pass Parent/Offspring Connections
to Other Tasks. • • • • • • • • • • • ••
• • • • 196
Task Abort Status Codes • • • • • • • • •
• • • • 207
Comparison of Methods of Data Transfer
Between Tasks • • • • • • • • • • • • • • • • • • • • 208

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

Mapped Versus Unmapped Systems • • • • • •
APR and Virtual Address Correspondence ••

6-1
6-2

Comparison of Overlaying Methods ••
How Global Symbols Are Resolved ••

7-1
7-2
7-3

Types of Static Regions Available on RSX-11M • • • • •
Techniques of Referencing a Shared Region • • • • • •
Effect of /CODE:PIC, /SHAREABLE:COMMON, and
/SHAREABLE:LIBRARY on a Shared Region's STB • • • • •
Required Switches and Options for Building
a Shared Region • • • • • ••
••
• •

7-4

...

• • 216
• • • • 224
• • • 260
• • • 269
292
305
306
309

• 340
• ••
• • • • 344
• • 349

8-1
8-2
8-3

Memory Management Directives.
Region Status Word • • • • • •
Window Status Word • • • • • •

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

Comparison of Physical, Logical and Virtual Blocks •• 390
Examples of Use of F11ACP Functions • • • • • • • • • 399
Comparison of FCS Record Types • • • • • • • • • • • • 406
Comparison of Sequential Access I/O and
Random Access I/O • • • • • • • ••
•• • • • • • 408
File Organization, Record Formats, and Access Modes. 413
Comparison of FCS and RMS • • • • • • • • • • • • • • 415

9-5
9-6

10-1
10-2

When the User Record Buffer Is Needed • • •
Types of Access • • • • • • • • • • • •

436
• • 445

8-1
8-2

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

513
• 513

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

Requesting a Task • • • • • • • • •
• • • .45
Using thec $ Form of the Directives •
• • ••
.54
Using the $C Form of the Directives • . . .
....56
.Using the $S Form of the Directives • . . . . . . . . .57
Using Several Directives • • • • • • •
• • • • • • .66
Waiting for an Event Flag • • • • •
• • •
.72
Setting an Event Flag in a Task • • •
.74
Using a Requested Exit AST. • • • • • •
• ••
.79
Using an AST in the Mark Time Directive • • • • • • • • 81
Using SSTs. • • • • • • • •
• ••••••••
.86

3-1
3-2

Synchronous I/O • • • • • • • • • • • • • • • •
•
Asynchronous I/O Using Event Flags
for Synchronization • • •
• • • ••
•••
Asynchronous I/O Using an AST for Synchronization • •
Prompting for Input • • •
••••
••••••
Read No Echo. • • • • • • • • • • • • •
• ••••
Read With Timeout. • • • • • • • • • •
• ••
Terminal Independent Cursor Control • • • • • • • • •
Formatting Numeric Data • • • • • • • • • • • • • • •
Formatting Directive and I/O Error Messages •
••
Formatting ASCII Data • • • • • •
• • •
•

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

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

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

Synchronizing 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 • • • • • • • • • • • • • • • • • • • • • •
Synchronizing a Receiving 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 • • • •
c

Description
Map File of
Map File of
Overlays. •

109
114
118
124
127
129
133
140
143
146
158
161
168
173
178
188
191
198
203

of An Overlaid Task • • • • • • • • • • • 239
Example 6-1 Without Overlays • • • • • • • 255
Example 6-1 With Disk-Resident
• • • •
• • • • • • • • • • • • • 257
xii

6-5
6-6

Map File of Example 6-1 With Memory-Resident
Overlays..
• • • • • • • • • • • • • • • • • • • 259
A Task With Two Overlay Segments. • • • • • • •
• 266
Complex Example Using Overlays. • • • • • • • •
• 276

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

Resident Common Referenced With Overlaid Psects • • •
Resident Common Referenced with Global Symbols • • • •
Shared Library. • • • • • •
• • ••
•
Creating and Using a Device Common. • •
• ••••

313
320
324
331

8-1
8-2
8-3

Creating a Named Region • • • • • • • • • • • • • • •
Creating a Region and Placing Data in It • • • • • • •
Attaching to an Existing Region and Reading Data
From It • • • • • • • • • • • • • •
• • •
Send-by-Reference • • • • • •
. • . . . . • .
Receive-by-Reference • • • • • . . • • • . . • . . . .
Use of the Mapped Array Area.
• • • • • . . . . •

354
359

424

10-4
10-5
10-6
10-7

Creating a File in MACRO-ll •
••••••••••
Creating a File of Fixed Length Records, Initializing
FDB at Assembly Time • • • • • • • • • • • • • • • • •
Creating a File of Fixed Length Records, Initializing
FDB at Run Time
•••••••••••••••••
Accessing a File in Locate Mode • • • • • • • • • • •
Accessing a File in Random Mode •
••••••••
Creating a File With Block I/O • • • • • • • • • • • •
Reading a File With Block I/O •
• ••••••

G-1
G-2

Reading the Event Flags (for Exercise 1-1) • • • • • • 537
Using the Routines GCML and CSI (for Exercise 10-6) • 538

6-4

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

xiii

363
368
371
378

463
467
470
474
480
484

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
static regions to:

regions.

Yo u

can

use

these

•

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

•

Communicate directly with a peripheral device through
I/O page.

the

OBJECTIVES
1.

To create and use a resident common region

To create and use a resident library

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

To create and use a device common.

RESOURCE
•

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

289

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 any tasks which use the region.
For a
task which uses the region, the total applies to all regions used
plus the task's code.
Static regions 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 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.

291

STATIC REGIONS

Table 7-1

Types of Static Regions Available on RSX-IIM

292

STATIC REGIONS

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 a
privileged
user.
Once
the
region
is
installed
and
loaded
into
the
partition,
it cannot be
checkpointed.

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 reg ion is loaded into memory into
the partition POSIND;
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
reg ion.
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 120000(8) or APRS 4 and 5,
beginning
at virtual address 100000(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.

293

STATIC REGIONS

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, the user either did not specify an
APR, or specified APR 6.
When task B was built, the user
specified APR 2.

294

STATIC REGIONS

VIRTUAL
MEMORY

PHYSICAL
MEMORY

160000 APR7
140000 APR6
120000 APR5
100000 APR4
60000

APR3

40000 APR2
20000 APR1

TASK
WINDOW
(16K WORDS)

o APRO
TASK
REGION
(TASK A)
160000 APR7
140000 APR6
120000 APR5
100000 APR4
60000

APR3

40000

APR2

20000

APR1

o APRO
TASK
REGION
(TASK C)

160000 APR7
140000 APR6
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

295

STATIC REGIONS

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 120008(8)-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.
You may think that there is no reason to ever limit yourself
by making a region absolute. However, there are code restrictions
for position independent regions due to the fact that a shared
region is task-built separately from any of its referencing tasks.
When the region is task-built, all code within it is set.
The code has to be written using special position independent
coding techniques to allow it to be placed at possibly different
virtual addresses in the various referencing tasks. This is only
a problem for data if the data is not position independent;
for
example, a jump table.
The starting virtual address of each routine, defined by its
label, is assigned when the referencing task is task-built. This
address may vary depending on which base APR is used to map the
region.
The address of a given routine may vary from one
referencing task to another. But the address placed in the table
itself was already fixed when the region was task-built, and does
not change for each referencing task. Further, that address may
not match any of the addresses assigned in referencing tasks. For
example, consider the following jump table and routines W, X, and
Y:
JMPTAB:

.WORD W
.WORD X
.WORD Y

296

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
0 APRO

TASK
REGION

TASK B
160000 APR7
140000 APR6
120000 APR5
100000 APR4
60000 APR3
40000 APR2
20000 APR1
o APRO

ABSOLU
(ABSOLUTE REGION)

........

.TASK
WINDOW
---(8K WORDS)
_----'---------~-

(TASK A)

TASK
REGION
(TASK B)

TASK C
160000 APR7
140000 APR6
120000 APR5
100000 APR4
60000 APR3
40000 APR2
20000 APR1
o APRO

TASK
WINDOW
(24K WORDS)

CAN'T
REFERENCE
ABSOLU

TK-7769

Figure 7-2

Tasks Using an Absolute Shared Region

297

STATIC REGIONS

The addresses resulting from the .WORD directives are fixed
wh e n th e reg ion is ta s k - b u i It; e • g ., at W = 15 0 0 (8), X = 15 4 0 (B) ,
and y = 1626(8).
If the referencing task places the actual
addresses W, X and Y at those virtual addresses, everything will
work fine. But if it starts mapping at APR 4 (virtual address
120000) ,
the
labels themselves will be assigned addresses
120000 (8) + 1500 (8) = 121500 (8), 120000 (8) + 1540 (8) =
121540 (8) ,
and 120000(8) + 1626(8) = 121626(8).
However, the values in the table are already set at 1500(8),
and 1626 (8), and they no longer address the correct
locations. A jump or call by way of the table to routine W will
result in a transfer to location 1500(8) in the referencing task,
and definitely not to routine W.
To avoid this problem, jump
tables should be included in the referencing task code instead of
in the shared region.

1540 (8),

Instructions in shared regions are even trickier to program.
All references which are relative to the current PC, for example,
eight bytes from here, work fine. But a reference to an actual
virtual address, for example, virtual address 4260(8) or @#A, only
works if 4260(8) or A remains set at that virtual address. For a
discussion of position independent code and how to write it, see
Appendix H of the IAS/RSX-ll MACRO-II Reference Manual.
All of this means that in general, the decision about whether
to create a position independent or an absolute shared region is
based on the code restrictions, rather than the flexibility.
In
general, resident commons, containing data, are created position
independent; and resident libraries, containing code, are created
absol ute.
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.
Assemble
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 linkage to
the reg ion.

298

STATIC REGIONS

After
task-building
the shared
region,
task-build
the
referencing ~ask.
It can be written and assembled 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
resident common.

data

from,

•

The task calls
library.

jumps

routine

299

stores
in

data

in,

resident

STATIC REGIONS

LIBRARY
FI LE(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

300

STATIC REGIONS

Techniques of Referencing
When you write the code for the shared region and
referencing task, you must pick a technique to resolve
references to the shared region. Some of the techniques are
same as the ones we used in Chapter 6 for referencing data in
\ root from an overlay segment.

the
the
the
the

Using Overlaid Psects (Data Only)
This technique is similar to the one for overlays.
An
example appears below.
This time the Overlaid (OVR) psect is
defined in the shared region, then the same psect is sp~cified in
the referencing tasks. The Task Builder, as usual, combines the
different occurrences of each psect. Because the shared region is
built first,
the psect MYDATA is placed there. Later, when the
referencing task is built, the new occurrence of MYDATA is
combined with the one in the shared region. The OVR attribute
tells the Task Builder to start the allocation at the same
location as the allocation already there, causing the addresses to
be overlaid. This, in effect, just sets up the addressing so that
M references the first word of the region, the 3.
Shared region:
• PSECT
.WORD
• END

MYDATA D,GBL,OVR

Defaults: REL,RW

3. ,4. ,5 •

Referencing task:

• PSECT

MYDATA D,GBL,OVR ; PSECT in shared
reg ion
Addr of start of region
Back to blank psect

CMP
BGT

M,#5
FIFTY

• PSECT
M=.

START:

Check value
Branch if greater

301

STATIC REGIONS

Using Global Symbols (Data or Subroutines)
This technique is also the same as the one used in overlays.
An example for data and for a subroutine appear below. In both
cases, the label or labels are defined as global symbols.
The
referencing task uses the same global symbols to ~ccess the data
or to call the subroutine. The possibly needed Psect name will be
discussed later in the module.
For Da ta
Shared reg ion:
; Po ss ibl y needed psec t name
.PSECT ZZZ
M· •
• WORD
3 • ,4.
N: :
• WORD
5•
• END

Define data and symbols

Referencing task:
CMP
BGT

M,#5

FIFTY

Check val ue
Branch if greater

For Subroutine Names
Shared reg ion:
Subro utine
AADD: :
Return

RETURN
Referencing task:
Set up arg umen ts

CALL

AADD

Call subro utine

302

STATIC REGIONS

Using Virtual Addresses (Data Only)
This technique is not available with overlays.
If the shared
region
is built absolute,
the
starting virtual address of the
region is fixed when the region is task-built.
In
the example
below,
it
is assumed
that the region is task-built absolute to
begin at virtual address 160000(8).
The referencing
task can
access the data by using the actual virtual address where the data
is mapped.
If the region is built position independent, it can be mapped
at a
specific base virtual address (or base APR) by specifying a
base APR in the task-build command for the referencing
task.
In
this example, specifying APR 7 would set the base virtual address
for the region at 160000(8).
Sha r ed reg ion:
; possibly needed psect name
.PSECT ZZZ
.WORD
3.,4.,5 •
• END
Referencing task:
; Shared region must be task-built either:
absolute starting at V.A. 160000
position independent and referencing task is
task-built to force region to start at
V.A. 160000
M = 160000
CMP
BGT

M, #5

FIFTY

Addr of start of region
Chec k val ue
Branch if greater

303

STATIC REGIONS

Table 7-2 summarizes the techniques for referencing a shared
region.
When you task-build the shared region, you can specify
whether or not you want the psect names placed in the symbol
defini tion file
(.STB file). They must be there if you use the
technique of overlaid Psects to reference the region.
Use the
/SHAREABLE:COMMON qualifier
(/CO in MCR)
to include the psect
names.
If global symbols or virtual addresses are used, it is best
to
exclude
the
Psect names in the .STB file.
Use the
/SHAREABLE:LIBRARY qualifier (/LI in MCR) to exclude psect names.
This avoids possible task-build errors due to psect conflicts.
If psect names are kept in the .STB file, each psect defined
in the region, including the default blank (. BLK.) psect is
there. The Task Builder tries to collect allocations together if
a matching psect name appears in the referencing task. However,
it can't add to the allocation in the region, since the region is
already built.
Therefore, if the psect results in additional
allocation to the psect (always true if the psect has the
concatenate
(CON) attribute), then a task-build error .. LOAD
ADDRESS OUT OF BOUNDS"
results.
This is because the
new
allocation can't be added to the already built shared region.
Therefore, if psect names are placed in the .STB file, the
psect names in the referencing task must not match any in the
shared reg ion, incl ud ing the defaul t blank psect.
Avojd ing this
is especially difficult if the shared region is a system resident
library like FCSRES or FORRES, which was written by DIGITAL.
In
this case, you may not know what psect names were used in the
original source code.
As a general rule, place psect names in the .STB file only if
you use overlaid Psects to reference the region. Table 7-3 shows
the interaction of three task-builder switches or qualifiers.
They
are:
/CODE:PIC,
for
position
independent or not;
/SHAREABLE:COMMON, for placing Psect names in the .STB file;
and
/SHAREABLE:LIBRARY, for not placing psect names in the .STB file.
The name COMMON is used for keeping psect names because
overlaid Psects can only be used for data references, therefore
they are generally used in resident commons. The name LIBRARY is
used for not keeping psect names because global symbols are
generally used to reference subroutines in a resident library. In
fact,
if a resident common is referenced using global symbols or
virtual addresses, it is also built /SHAREABLE:LIBRARY to avoid
Psect conflicts.

304

STATIC REGIONS

Table 7-2

Techniques of Referencing a Shared Region

305

STATIC REGIONS

Table 7-3 Effect of /CODE:PIC, /SHAREABLE:COMMON, and
/SHAREABLE:LIBRARY on a Shared Region's STB

306

STATIC REGIONS

PROCEDURE FOR CREATING SHARED REGIONS AND REFERENCING TASKS
Creating a Resident Common or Resident Library
1.

Code yo ur sha red reg ion.
•

Set up for an appropriate referencing technique.
Choose either overlaid psects, global symbols,
virtual addresses for a resident common.

Use global symbols for a resident library.
•

Choose position independent or absolute.
The decision
is
techniques used.

based

mainly

the

coding

is position
independent,
build
If
the code
po si tion
independent
(typical
for
resident
common) •
If the code is not position
independent,
absolute (typical for resident library).
space,

plus

build

you

•

Resident common
reserve
initialize locations.

•

Resident library - code must be
reentrant.
See the
section on Reentrancy in Chapter 5 of the PDP-II
Processor Handbook
for
more
information
about
reentrant code.

Assemble the shared region.

If not already done, create the common type partition.

may

•

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.

307

MCR)

command

STATIC REGIONS

•

Examples:
>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.

Task-build the shared reg ion.
•

Symbol definition file

(.STB)

•

Build position
7-3) •

•

Keep or do not keep psect names (see Table 7-3).

•

Use required switches and options (see Table 7-4) •

independent

required.
or

absolute

(see

Table

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.

308

STATIC REGIONS

•

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

The required switches and options in Table 7-4 are needed for
different 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, the specified value is used as a
maximum length. A task-builder error results if the length of the
region is longer than the length specified. If you specify a
length of zero, the region is set up with the size needed for the
cod~, as long as it doesn't exceed the 32K word virtual addressing
limit.
Table 7-4

Required Switches and Options for Building
a Shared Region

309

STATIC REGIONS

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

Code the shared region.
See COMWP.MAC in Example 7-1.
keyed to the example.

The

following

notes

are

The code is placed in an OVR psect named MYDATA.
This
o same
psect is used in the referencing task.
This series of assembler directives is equivalent to
o 128(10)
.WORD 3 assembler directives.
It initializes
the first 128(10) words in the region to 3.
This series of assembler directives
initializes
next 128(10) words in the region to 6.
2.

the

Assemble the shared region.
>MACRO/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 two 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

310

STATIC REGIONS

Later, to eliminate the partition and to
use the commands:

replace

TSTPAR,

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

Task-build the shared region.
To build position independent:
)LINK/OPTIONS/MAP/SHAREABLE:COMMON/NOHEADER -)/SYMBOL TABLE/CODE:PIC COMWP
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 the shared region using
overlaid psects). /NOHEADER means do not include a
task
header in the task image because this is not an executable
task. /SYMBOL TABLE means make a .STB file
(COMWP.STB).
/CODE:PIC means position independent code for a position
independent region.
STACK = 0 means no stack space
is
needed because this is not an executable task.
PAR =
COMWP means the partition is COMWP.
The Task Builder gets
the length (for a maximum check) from the partition on the
system.
To build absolute:
)LINK/OPTIONS/MAP/SHAREABLE:COMMON/NOHEADER -)/SYMBOL TABLE COMWP
Option? STACK=0
Option? PAR=COMWP:160000:20000
Option? <RET)
Only changes:
1.

Omit /CODE:PIC.

Specify a base virtual address and a maximum
length.
The base virtual address must correspond
to a base virtual address for an APR
(e.g.,
2,
20000(8),
40000(8),
60000(8),
100000(8),
120000(8), 140000(8), or 160000(8».
The APRs
used must be available in all referencing tasks.

311

STATIC REGIONS

Install the reg ion.
)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.

312

STATIC REGIONS

1
2
3
4

.TITLE COMWF'
.IDENT lOll
.ENABL LC

Enable lower case

File COMWF'.MAC

5
6

7
8

Pro~ram which creates and initializes a common re~ion
which will be referenced usin. overlaid Psects.

Task-build instructions: Must include ISHAREABLE:COMMON
and INOHEADER switches; STACK=O and PAR=COMWP options.
Must create .STB file. Ma~ be ICODE:PIC Dr absolute
(default).

10
11
12
13

15
1t>
17

The code is placed in a Psect named MYDATA
;-

.PSECT
.REPT
• WORD
.ENDR
.REPT
• WORD
• ENDR
.END

_[:LB

_[21

22
23

24
1
2
3
4
5
6

128.
6•

.TITLE COMGF'
.IDENT lOll
.ENABL LC

Enable lower case

FILE COMGF'.MAC

7
B
9

This task ~ets the values from the static common
re~ion COMWP. It uses the techniGue of overlaid Psects
to reference the re~ion.

10
11

Task-build instructions:

12
13

>LINK/MAP/OPTION COMGP
Option1 RESCOM=COMWP/RO
Option1 <RET>

14
15
16

.MCALL
.PSECT

:1.7

0[18
:1.9

Rf~F'eat count
Word vallJ(~ of 3 •
End reF'eat rar.:;.!e
Repeat count
Word value of t> •
End reF'eat ran~e

128.

M=.

IOSB:
ARG:

.PSECT
.BLKW
.BLKW

A[;~
V
27

BUFF:
FMT:

• BLKB
.ASCIZ

FERRi:

• ASC.IZ

FERR2:

• ASCIZ

2:1.

22
23

29
30

Example 7-1

QIOWSS,EXITSS
~ S~stem macros
MYDATA D,GBL,OVR ~ Psect used in COMWP
1 c:)(~a 1. s~:lmbol ft11' staT't
of resion
Back to blank Psect
2
liD status block
Ar~ument block for
1
; error code
Output buffe T'
:1.00 •
1%8DI
Format stT'in:;j fOT'
output of data
IDIR ERROR ON cno. DSW .- %DI ; Di T'ective
;
errt")r mes~;a~e
! liD ERROR ON aIO • CODE .- %D! ; 110 c-:~rror
messa.e

Resident Common Referenced \ATith OVerlaid Psects
(Sheet 1 of 3)

313

STATIC REGIONS

e
0

32
33
34
35
36
37

Lao? cOI.Jnt .- :~2 ..
8 :JJ:s }""er 1 inE~

N=32 ..

.EVEN

;

START:

MOV

tM,R2

Startirls addT' of data
in the resion
Le)o? cOI.Jnt
Out?IJt buffer
Format stT'irls
; Edit meSSC:~f..jf~

~58

39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

lines~

MOV
:fI:N,R5
:fI:BUFF,RO
MDV
MOV
tFMT" r';:1
CALL
$EDMSG
QIOW$S :JJ:IO .. WVB,#5":fI:l,~:JJ:IOSB,,,,<#BUFF,Rl,:JJ:40>
Chf.~ck fe)r i.:f:i. r err'or
BCS
ERROR
Check foy' I/O EH'ror
TSTB
IOSB
Branch on I/O er'ror'
BLT
ERF~OR1
Sta~ here for sood write
R5,LOOP
SOB
Decremerlt cOI.JnteT' , loo?
back if not ~Iet done
EXIT$S
E~·dt
; Error code
$DSW,ARG
ERROR: MOV
Move DSW to c~rS block
MOV
:JI:FERR1, R:I.
Acldr of format strin!~
BR
Branch to $EDMSG code
SETUP
10SB,RO
E~·,tend sisn em lID
ERROR1: MOVB
RO,ARG
status cmd F,lace in
MDV
ars block
MOV
Addr of format stT'ins
tFERR2"F~1
:fI:BUFF,RO
Addr of OIJt?I.Jt buffer
SETUP: MOV
tARG,R2
Addr of arslJlTtent block
MOV
; Edit ITlessaSe
CALL
$EDMSG
QIOW$S iIO .. WVB"#5~.1,,,,<:JJ:BUFF,Rl,t40> ; Wr j, tf?
LOOP:

Example 7-1

EXIT$S
.. END

;
Jrlf?~5SaSe
; EHit

START

Resident Common Referenced With Overlaid Psects
(Sheet 2 of 3)

314

STATIC REGIONS

Session

I~tln

>INS COMWP
>r~UN
~~

COMGF'

:·5

Example 7 -1

3
3

6
6

3
6
6

/.)

3
3

3
6
6

3
6

Resident Common Re fe renced Wi th Overl a id Psects
(Sheet 3 of 3)

Creating a Referencing Task
1.

Code the
task,
technique.
•

using

referencing

corresponding

If psect names are kept in the
.STB file
referencing task, avoid psect conflicts.

Assemble the task.

Task-build the task.
•

the

Specify shared regions
options:

using

one

the

following

COMMON=common name for a
system resident
(.STB and .TSK files must be in LB: [1,1]).

common

LIBR=common name for a
system resident library
(.STB and .TSK files must be in LB: [1,1]).

315

STATIC REGIONS

RESCOM=common name for
(.STB and .TSK files
using normal defaul ts) •

a user resident common
in any device and any UFD

RESLIB=common name for a user resident library
(any device and any UFD using normal defaults) •

•

Append :RO if read-only access is desired.
:RW if read-write access is desired.
Use "I" instead of ":" for RESCOM and RESLIB.

•

Only if the shared region is position independent, can
you specify the base APR to be used to map the region.
If not specified, the highest available APR or set of
APRs is used, as needed.

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 UFD, as long as
both files are in the same UFD on the same device.
Read-only or read/write access affects the way the access
bits in the page descriptor reg isters (PDRs) 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.

316

STATIC REGIONS

COMGP.MAC in Example 7-1 contains the source code for a task
to reference the shared reg ion COMWP.
Use the, following procedure
to create the task.
1.

Code the task.
See COMGP.MAC in Example 7-1.
keyed to the example.

o
o

The

following

notes

are

The same Psect, MYDATA, is used here as in COMWP.MAC
to set up referenc ing • M mar ks the beg inn ing 0 f the
region.
No
initialization of the Psect can
be
performed in the referencing task.
The main code is in the blank (. BLK.) psect.

e Move the starting address of the region to R2.
o

We use $EDMSG to set up each line of the display.
loop
through
once
for
each line, editing
displaying the values.

We
and

o words
The format string for $EDMSG.
%8D means convert eight
to signed decimal, with a tab between values.
2.

Assemble the' task.

Task-bui ld the ta sk.
>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, i~ 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

317

STATIC REGIONS

Deciding whether read-only or read/write access to a
region
is required is usually straightforward.
If a task moves data into
the region or changes a value in the region, read-write access
is
required.
If a
task mqves data out of the region or just reads
values in the region, just read-only access is required.
However, when QIOs are issued and the buffer is in the shared
region,
things get a
little
tricky.
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
shared
region are reads (from a peripheral device) into a buffer
in the region, and that therefore, all
QIOs
requlre
read/write
access.
This condition causes an I/O error (IE.SPR) for illegal
user buffer.
This condition does not affect Example 7-1
because
$EDMSG
creates
the output string
in a
buffer within the
referencing task area, and
the QIOs do the writes from the
referencing task area.
In an example in a later module, you will
see this problem
come up.
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 nonprivileged task.
For a
discussion of privileged
tasks and how to task-build them, see
Appendix D.

318

STATIC REGIONS

Example 7-2 shows a shared region
(COMNP.MAC)
and
a
referencing task
(COMGGS.MAC)
using global symbols to reference
the shared region.
Other than the difference in referencing
technique,
Example 7-2 is the same as Example 7-1. The following
notes are keyed to the example.

C»

Because the region is built with the /SHAREABLE:LIBRARY
switch, any Psect names used in the file are not placed in
the .STB file.
Therefore, the code for
the---referencing
task can be placed in the default blank (.
BLK.) Psect or
any other Psect.
If the library were instead built
/SHAREABLE:COMMON,
the Psect names used in the shared
region would all be placed in the
.STB file.
In that
case, using any Psect in the referencing task which is
also used in the shared region would cause a
Psect
conflict,
causing
a
LOAD
ADDRESS
OUT OF BOUNDS
task-builder error.

«» The
global symbol K marks the beginning of the shared
region.
t)

The rest of the code is the same as COMWP.MAC
7-1.

C»

Just use the global symbol K to reference the start of the
shared region.
The Task Builder sets up the linkage to K,
as it is defined in the shared region COMNP. The rest of
the code is the same as that in COMGP.MAC in Example 7-1.

Example

The tape supplied with this course also contains an example
using virtual addresses as a referencing technique.
The shared
region is still COMNP, the same one as in Example 7-2.
The
referencing task code is in the file COMGVA.MAC.
It should be in
UFD [202,3] on your system. Check with your course administrator
if you need help locating this example.

319

STATIC REGIONS

.TITLE
.IDENT
.ENABL

1
2

3
4
5

Prosram which creates and initializes a common resion
which will be referenced usins slobal swmbols or
actual virtual addresses.

10
11
12
13
14
:1.5

Task-build instuctions: Must include ISHAREABLE:LIBRARY
and INOHEADER switches, STACK=O and PAR=COMNP options.
Must create a .STB file. Maw be ICODE:PIC or absolute
(the default).

[16
o is

This proSram places the code in the default blank
(. BLK.) Psect. It could be in anw Psect. Psect
conflicts are avoided bw usins the ISHAREABLE:LIBRARY
switch on the task builder.

'L7

26
27
28

;; Define K, a Slobal symbol
K: :
• REPT
1 :~8.
• WDRD
3.
.ENDR
.REPT
128.
• WORD
6.
.ENDR
.END

.TITLE COMGGS
.IDENT /0:1./
.ENABl. LC

1
2
3

4
5
6
7
S
9
:1.0
11
12
:1.3
14
15
16
17

Enable lower case

File COMNP.MAC

6
7
8
9

19
20
21
22
23
24
25

COMNP
1011
LC

Repeat cOIJnt
Word val'Je of 3 •
End repeat T'an~H?
ReF,eat cO'.Jnt
Word value 0·(·' 6 •
End reF,eat rfJn~te

Enable lower case

FILE COMGGS.MAC
This task sets the values from the static common
reSion COMNP. It uses a slobal swmbol to reference
the resion.
Task-build notes:

Example 7-2

LINK/MAP/OPTION COMGGS
Option? RESCOM=COMNP/RO
Option? <RET>
.MCALL

QIOW$S,EXIT$S

External swstem macros

Resident Common Referenced With Global Symbols
(Sheet 1 of 3)

320

STATIC REGIONS

:L8

;

10SB:
ARG:

.BlKW
.BLKW

BUFF:
FMT:

.BlKB
.ASCIZ

FERR1:

.ASCIZ

FERR2:

.ASCIZ

20
21
22
23
24
26
27

28
29

N=32.

3()

3l.
32
33

34
35
36
37

:-ss

39
4()

41
42
43
44
45
46

47
48
49
~5()

51
52
53
54
55
56
57

58
59
60

I/O status block
block for
err'or code
100.
Output buffer
/X8D/
Format strins for
output of da-ta
/DIR ERROR ON aro. DSW - XD/ ; Directive
error messaSe
!I/O ERROR ON aro. CODE = XD! ; I/O
e l' 1'0 l' messa9E~
loop count - 32. lines,
8 :fI:s per line
2

Ar~ument

.EVEN
MOV

Startins addrress of
data in the resion
tN,R5
Loop count
MOV
:fI:BUFF,RO
Output buffer
lOOP:
MOV
:fI:FMT,R:L
Format strinS
MOV
$EDMSG
Edit messase
CAll
aIOW$S :fI:IO.WVB,:fI:5,:fI:l,,:fI:IOSB,,(tBUFF,Rl,:fI:40>
ERROR
Check for dir error
BCS
IOSB
Check for I/O error
TSTB
ERRORl
Branch on I/O error
BlT
Sta~ here for good write
Decrement counter, loop
SOB
R5,lOOP
back if not wet done
E~·dt
EXIT$S
; Error code
Move DSW to arg block
$DSW,Ar~G
ERROR: MOV
Addr of format strins
tFERR1,Rl.
MOV
Branch to $EDMSG code
SETUP
BR
Extend sign on I/O
IOSB,RO
ERROr~ 1: MOVB
status and place in
RO,ARG
MOV
arg block
tFERR2,Rl
Addr of format string
MOV
tBUFF,RO
Addr of output buffer
SETUP: MOV
:fI:ARG,R2
Addr of argument block
MOV
$EDMSG
Edit message
CAll
aIOW$S tIO.WVB,t5,tl",,(tBUFF,Rl,t40> ; Write
error message
EXIT$S
.END
START
START:

Example 7-2

Resident Common Referenced With Global Symbols
(Sheet' 2 of 3)

321

STATIC REGIONS

J~lJn

Sessicm

>INS COMNF'
>RUN COMGGS
~~

3
3

3
6
6

3
6

3
6
6

Example 7-2

Resident Common Referenced With Global Symbols
(Sheet 3 of 3)

Example 7-3 contains a shared library, LIB.MAC, and a
referencing task, USELIB.MAC.
The shared library contains four
simple arithmetic routines to add, subtract, multiply, and divide
two numbers. They are all written to be reentrant, plus they can
be called from a FORTRAN program with a standard
FORTRAN
subroutine
call.
Basically, this means that on entry the
arguments are assumed to be set up as follows:
R5 --.

I count=3
address of OPI
address of OP2
address of answer

322

STATIC REGIONS

For additional information on the FORTRAN/MACRO-II interface,
see Appendix
C.
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 fo ur operations.
The following notes are keyed to Example

7-3.

o symbol.
Each subroutine entry point
is defined
wi th a 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 .8TB file.

Psect

For AADD and SUBB, move the first operand to
R0,
perform
the operation
in R0,
then move the answer to the third
operand for return to the caller.

For MULL, use Rl instead of R0, so
that the product
is
limited
to just Rl (16 bits).
If R0 were used instead, a
32-bit product is
returned
(low-order 16
bits
in Rl,
high-order 16 bits in R0).

For DIVV, a 32-bit dividend is assumed in Rn and Rn+l,
so
o 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.

o
o
C)

The two operands.
Space allocated for return of the 'result.
FORTRAN type argument block is buil t
reverse order, so
that SP points
block.

on the stack,
in
to the start of the

The address in SP is moved to R5,
start of the argument block.

Call each of the routines.
disturbed
between calls,
used for all four calls.

is placed
The 16-bit
the third

points

the

Since R5 and the stack are not
the same argument block can be

Call the subroutine PRINT to edit the output
display it for all operations.

323

message

and

STATIC REGIONS

.TITLE
.IDENT
.ENABL

1
2
~:s

4
5
6
7
8
9
10
11

LIB
lOll
LC

Enable lower case

File LIB.MAC
This file contains the FORTRAN callable subroutines
AADD, SUBB, MULL, and DIVV, which perform the
appropriate inte~er operation.
Callin~

convention: CALL sub (op1,op2,ans)

12
:I. ~:s
:L4

15
:L6

0 ..

:1.8
:1.9

. . 20

; _.

Task-build instructions: Must include ISHAREABLE:LIBRARY
and INOHEADER switches; STACK=O and PAR=LIB options.
Must create .STB file. Maw be ICODE:PIC or absolute
(default). Usin~ ISHAREABLE:LIBRARY avoids Psect
conflicts.

AADD: :

'")1
A
~'")
V,.·
.. ,:..
[
23

24
25
26
27

°0
e [~~

SUBB: :

30
~51

o 3;

t~ETURN

AADD,RO,I,GBL,REL,CON
SSAVAL
Save all re~isters
@2(RS),RO
Move 1st operand
@4(R5),RO
Add 2nd operand
RO,@6(R5)
Store result
Restore reSs and return

.PSECT
CALL
MOV
SUB
MOV
RETURN

SUBB,RO,I,GBL,REL,CON
SSAVAL
Save all re~isters
@2(RS),RO
Move 1st operand
@4(RS),RO
Subtract 2nd operand
RO,@6(RS)
Store result
Restore reSs and return

.PSECT
CALL
MOV
MUL

MULL,RO,I,GBL,REL,CON
SSAVAL
Save all re~isters
@2(RS),R1
Move 1st operand
@4(R5),R1
Multiplw (answer in
Just Rl)
R1,@6(RS)
Store result
Restore reSs and return

.F'SECT
CALL
MOV
ADD
MOV

MULL: :

O [ ~~
~57

MOV
RETURN

39
40

o04241

o [!~46
47
48

DIVV: :

.PSECT
CALL
MOV
CLR
DIV
MOV
RETURN
.END

Example 7-3

DIVV,RO,I,GBL,REL,CON
SSAVAL
Save all re~isters
@2(RS),R3
Move 1st operand
R2
Clear hiSh order 16 bits
@4(RS),R2
Divide
R2,@6(RS)
Store result
Restore re~s and return

Shared Library (Sheet 1 of 2)

324

STATIC REGIONS

1
2
3
4

.TITLE
.IDENT
.ENABL

USELIB
lOll

Enable lower case

File USELIB.MAC

5
6

MACRO-11 task to use the resident

8
9

Task-build instructions:

10
11
12
13
14
15

librar~

LIB

>LINK/MAP/OPTION USELIB
Option? RESLIB=LIB/RO
Option? <RET>
;.MCALL

arOWSS,EXITSS

.WORD
.WORD
.BLKW

2
l

S~:~stem

macros

1.6

O[i~

20
21
22
23

o 26

[ 27
28

CD0 30
31
29

32
:{3

0- 34
35
:36
0- 37

:39
40

41
42
43
44
45
46
47
48

OP1:
OP2:
ANS:

Or-'e T'and 1
Operand 2
Result

100.
; Output buffer
OUT:
• BLKW
FORMAT: • ASCI Z ITHE ANSWER = %D.I ; Format strin~
.EVEN
; Build ar~ument block for subroutine on the stack
For result
START: MOV
tANS,-(SP)
Operand 2
MOV
tOP2,-(SP)
Or-'e r"and 1
MOV
tOP1,-(SP)
Number of arsuments
MOV
t3,-(SP)
R5=> arS block
MOV
SP,R5
Add operands
CALL
AADD
Prirlt resul ts
CALL.
PRINT
Subtract operands
CALL
SUBB
Print results
CALL
PRINT
Multipl~ operands
CALL
MULL
Print results
CALL
pr~INT
Divide operands
CALL
DrVV
Print results
CALL
PRINT
E~·dt
EXITSS

;** PRINT - Prints the results of the operation
tOUT,RO
Set UP for $EDMSG
PRINT: MOV
iFORMAT,Rl
MOV
tANS,R2
MOV
$EDMSG
; Edit messaSe
CALL
Wr'i te
CHOWSS trO.WVB,#5,tl",,<iOUT,R1,i40>
; messaSe
RETURN
; Return
.END
START

I;:un Sess i on
>INS LIB
>RUN USEL.IB
THE ANSWER IS 10.
THE ANSWER IS 6.
THE ANSWER IS 16.
THE ANSWER IS 4.

Example 7-3

Shared Library (Sheet 2 of 2)
325

STATIC REGIONS

DEVICE COMMONS
A device common is a special type of common that occupies
physical addresses on the I/O page. Instead of physical memory,
the I/O page contains peripheral device registers.
Therefore, a
device common does not contain data the way a regular resident
common does.
A device common 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 (Example 7-4). 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.
Use the procedure outlined below to create a device common
and a referencing task. The outline includes the specific steps
for Example 7-4.
It has a device common, DEVICE.MAC, which covers
the entire I/O page. The referencing task, CSR.MAC, checks each
address on the I/O page to find out which CSRs are in use.
If a
nonexistent CSR is found, a nonexistent memory error synchronous
system trap (SST) results. Use the following steps to create the
device common.
1.

Create a device common partition
desired device register addresses.

which

includes

the

•

Identify the addresses of the needed device registers,
using the PDP-II peripherals Handbook or information
available from your hardware installation.

•

Determine the base address of the partition at
100(8) boundary below the first identified address.

Mapping always begins at a 32-word block boundary.
Example 7-4 covers all of the I/O page. On a PDP-ll/70 or
other PDP-II with 22-bit addressing, it starts at physical
address 17760000(8). On a system with 18-bit addressing,
it
starts
at 760000(8).
On a system with 16-bit
addressing, it starts at 160000 (8) •

326

STATIC REGIONS

For a 22-bit system the command is:
SET PARTITION:DEVICE/BASE:177600/SIZE:200/DEVICE
For a 16-bit or IS-bit system, use
address in 32-word blocks.

the

appropriate

base

Note
that you don't need to eliminate an
existing
partition the way you did for
resident commons and
resident libraries.
This is because there isn't any real
partition already on the system, because the I/O page does
not correspond to physical memory.
You also don't need to create the partition until
after
you create the shared
region.
However, you do have to
know its base address before you write the code for
the
device common, so that you can set up the offsets to the
locations you plan to reference.
2.

Code the shared region.
•

Do not initialize any locations,
physical memory.

since

•

Set up for an appropriate referencing
address the desired registers.

there

technique

Use .=.+n or .BLKB n to get to the first address.
Use .BLKB or
.BLKW statements
needed space (or addresses) •

reserve

the

The following note is keyed to DEVICE.MAC in Example 7-4.

ct
3.

Because you access the entire I/O page, mark the start
of the region with the global symbol FCSR.
The .BLKW
4096.
directive reserves a full 4K words of addresses
for the entire I/O page.

Assemble the device common.
)MACRO/LIST DEVICE

327

STATIC REGIONS

Task-build the device common.
)LINK/OPTION/MAP/NOHEADER/SHAREABLE:LIBRARY-)SYMBOL TABLE DEVICE
option? -STACK=0
option? PAR=DEVICE:160000:20000
option? <RET)
This command task-builds the region absolute.
also task-build it position independent.

Yo u

can

Install the device common before you run the referencing
task.
Unlike a
resident common, a device common is not
loaded into memory because it has no real contents.

328

STATIC REGIONS

Use the following steps to create the referencing task.

task
using
the
corresponding
Code the referencing
See the notes which are keyed to
referencing
technique.
the example below.

Assemble the task.
)MACRO/LIST CSR

Task-build the task to reference the device common.
)LINK/MAP/OPTION CSR
)option? RESCOM=CSR/RO
)option? <RET)

After installing the device common, install and/or run the
referencing task.

The following notes are keyed to CSR.MAC in Example 7-4.

ct
~

Use the global symbol FCSR to reference the start
device common.

the

SST vector table with one entry for nonexistent memory.
NONE is the address of the SST routine.
(See Example 2
for an SST example.)

The
range of good CSR addresses.
for a
to
page
the
(0
(8
)
offsets
into
are
I/O
initially with 0;
LAST is
17777(8)) •
FIRST is set
updated on each read of a CSR.
If you ever trap due to
set
nonexistent memory, print the range of addresses,
the first add ress
in the next range, and
FIRST for
continue.

C»

Set up for SST, using just one table entry.

Count of good addresses in a range.
This is used to avoid
printing a message if a number of consecutive addresses
are not in use.

Two words
addresses

329

STATIC REGIONS

C»

Set first range to start with offset 0 into I/O page.

Test (or read) the word and increment R4.
Control
to
the next instruction
if the CSR is in use;
results if it is not in use.

C»

Increment count of good addresses.

Check to see if you are
Branch back if not.

CD
CD

the

end

passes
an SST

the

I/O

page.

When at the end of the I/O page, display
and ex it.

the

last

range

SST routine, entered fo r nonex istent memory trap on the
TST(R4)+
instruction.
Check for some good addresses in
this range.
If none, do not print a message.
Calculate offset to the last good CSR.
The last one
tested was bad, plus autoincrement incremented R4 by two.
Therefore, the current contents of R4 are
four
bytes
higher than the last good CSR.
Also, convert the virtual
address to an offset from the beginning of the
I/O page.
Move the last good CSR address to LAST.
Edit the range message, and convert
the
last good addresses to unsigned octal.
message.

first good and
Then display the

Set up for the next range and return from the
trap.
The
return picks
up at
line 49 (INC R5).
We want R5 to be
zero after it is incremented, so place a -1 in R5.
Set up
the first good CSR address in FIRST as the offset into the
I/O page corresponding to the current address in R4.
R4
has already been incremented past the CSR which is not in
use.
Return from trap at line 49, and continue check of
CSRs,
unless
you have already reached the end of the I/O
page.
On the Run Session - This command has probably been issued
already to create
the device partition.
It is included
here for documentation purposes, and in case
it has not
been issued previously.

330

STATIC REGIONS

:I.
2
3
4
5
6
7
8
9

.TITL..E

DEVICE

~IDENT

/011
I...C

.ENABL.

Enable lower case

File IIEVICE.MAC
This proSram sets

a device common for the liD paSe

Task-build instructions: Must include ISHAREABLE:lIBRARY
and INOHEADER switches, STACK=O, PAR=DEVICE options.
Must create .STB file. Ma~ be ICODE:PIC or absolute
(the default).

10
11
12
13
14

Install and run instructions: DEVICE must be installed
before runninS an~ referencins task.

1~)

16
The code is placed in the default blank Psect. Psect
conflicts are avoided b~ usins the ISHAREABlE:lIBRARY
task-builder switch.

17
18
:L 9

20
0'21
22

1
2
3

;
FCSR: :

• r~u\w
.END

4096.

.TITlE
.IDENT

CSR

Set

area 4K words IonS

/011

File CSR.MAC

6
7
8

This task displa~s the CSR addresses that are in use
on ~our s~stem. The addresses are listed as offsets
into the 1/0 paSe

10
11
12
13
14

Task-build instructions:
lINK/MAP/OPTION CSR
Option? RESCOM=DEVICE/RO
Option? <RET>

Install and run instructions: The d~vice common DEVICE
must be installed before runnins CSR.

16
17
:1.8

19
20
21

QIOWSS,EXITSS,SVTKSC
; S~stem macros
BEX
Do not list binar~
extensions
; SST vector table
VEe:
• WORD
NONE
Nonexistent memor~

Example 7-4

.MCAll
.NlIST

Creating and Using a Device Common (Sheet 1 of 3)

331

STATIC REGIONS

e[;~
27
28
29
30
3:L
32

FIF~ST:

LAST:
HDR:

MES:

.BLI(W
• £H.. I(W
.ASCII
.ASCII
.ASCII
LHDR
.ASCIZ

3~5

34
35
36
37

o :~B
o
Q

BUFF:

START:

39
40
41
42

1
1

; First ~ood CSR address
• Last CSR address
;
before trappinS
I
**CSR'S IN USE ON SYSTEM:**1(15)
(12)' (ADDRS ARE OFFSETS INTO liD PAGE)'
<15><12><12>
Header text
=.-HDR
Len~th of header text
ICSR'S %P THROUGH %P ARE IN USEI ; Text
for each ~ood CSR ranSe
Output messa~e buffer
100.

.BLKB
.EVEN
.ENABL

L.SB

SVTK$C

VEC,l

QIOW$S
MOV

• Set UP SST vector to
; handle trap
tIO.WVB,i5,#:L",,<tHDR,#LHDR,t40>
Displaw header text
tFCSR,R4
Set base address in

liD pa~e

4~5

44
45
46
47

fa . 48
49

o~~1

c-O

e[~~

57
58
59

Count of addrs found
Offset to first CSR
CLF~
; addr in use
; Test address, causins trap if not in use
IS:
TST
(R4)+
; Is this a sood addr1
INC
R5
; Yes, increment count
CMP
t<FCSR+17776),R4 ; At end of liD paSe1
BHIS
1$
; Branch back if not ~et
DisF/la~ last Sood ran~e and exit
t17776,LAST
Put last CSR in LAST
MOV
tBUFF,RO
Set UP for $EDMSG
MOV
tMES,Rl
MOV
MOV
tFIRST"R2
SEDMSG
; Edit ran~e messa~e
CALL
CHOW$S tIO.WVB,t5,tl",,<tBUFF,R1,t40)
; Displaw ran~e messaSe
EXITSS
CLR

R5
FIRST

C):L

62
63

CD[:;

; SST routine for non-existent memorw (or CSR not in use)
NONE:

CD[~i
CD

70
71

Example 7-4

!=Jood addresses in
this ran~f~1
None, nothins t(J print
Calculate offset to
last ~O(Jd CSR

TST

r~~j

BEQ
MOV

OUT
R4,R3

SUB
MOV
MOV

t<FCSR+4>,R3
R3,LAST
tBUFF,RO

An~1

P'Jt last CSR in LAST
Set '.JP for $EDMSG

Creating and Using a Device Common (Sheet 2 of 3)

332

STATIC REGIONS

[

~~
CD ~;
76
77
78

79
80

CD 81

82
83
84

:fI:MES,R1
tFIRST,R2
SEDMSG
; Edit ran~e messa~e
cnowls :fI:IO.WVB9:f1:5,:fI:1",,<$BUFF,R1,:fI:40>
; Displaw range message
; Set addresses and counters for continued search
OUT:
MOV
:f/:-1,R5
Initialize count to -1
since RTT returns to
INC R5 instruction
R4,R3
MOV
Set UP first ~ood CSR
in FIRST
SUB
tFCSR"R3
R3,FIRST
MOV
Retu. rn from trap
RTT
.END
START
MOV
MOV
CALL

PARTITION:DEVICE/BASE:177600/SIZE:200/DEVICE
CD >SET
>INS DEVICE
>RUN CSF:
**CSR'S IN USE ON SYSTEM:**
(ADDRS ARE OFFSETS INTO I/O PAGE)
CSR'S 000020 THROUGH 000106 ARE
CSR'S 004200 THROUGH 004236 ARE
CSR'S ·005000 THROUGH 005776 ARE
CSR'S 010200 THROUGH 010376 ARE
CSR'S 010500 THROUGH 010526 ARE
CSR'S 012200 THROUGH 012376 ARE
CSR'S 012440 THROUGH 012476 ARE
CSR'S 012516 THROUGH 012516 ARE
CSR'S 013000 THROUGH 013776 ARE
CSR'S 016300 THROUGH 016352 ARE
CSR'S 016400 THROLIGH 016452 ARE
CSR'S 016500 THROUGH 016506 (IRE
CSR'S 016700 THROUGH 016752 ARE
CSR'S 017170 THROUGH 017176 ARE
CSR'S 017340 THROUGH 017356 ARE
CSR'S 017400 THROUGH 0171416 ARE
CSR'S 017440 THROUGH 017476 ARE
CSR'S 017514 THROUGH 017526 ARE
CSR'S 017546 THROUGH 017546 ARE
CSR'S 017560 THROUGH 017676 ARE
CSR'S 017740 THROUGH 017752 ARE
CSR'S 017760 THROUGH 01?776 ARE

Example 7-4

IN USE
IN IJSE
IN LISE
IN USE
IN USE
IN USE:
IN USE
IN IJSE
IN USE
IN USE
IN USE
IN USE
IN USE
IN USE:
IN USE
IN USE
IN USE
IN IJSE
IN LISE
IN USE:
IN USE
IN USE

Creating and Using a Device Common (Sheet 3 of 3)

333

STATIC REGIONS

Appendix F contains information about several more
shared region topics. It includes a discussion of:
•

OVerlaid shared regions

•

Referencing several shared regions
task

•

Handling interlibrary calls

•

Cluster libraries

from

one

advanced

referencing

Most of the techniques discussed are more appropriate for the
advanced 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, Forms Management Services (FMS), and File Control
Services
(FeS).
If you write FORTRAN programs which use these
products, you may find it useful to read just the last few pages.
These
cover
the procedure for task-building a task which
references two or more DIGITAL supplied resident libraries as a
set of cluster libraries.
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 the on-line files
(should be under UFD [202,2]) or the printed copies 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
return to this module for further study.

334

mastered

the

material,

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 to access existing
static or dynamic 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

2•

To wr i t e ta s k s wh i c h d yn am i calI y co n t r 0 1 th e irma p pin g

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

337

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.
Ex am pIe s 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 on
the needs of the user running the task (e.g.,
the si ze 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
is automatically 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 directives,
available on mapped
systems to
allow tasks
to
perform
following functions.

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.

339

DYNAMIC REGIONS

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

Table 8-1

directives

Memory Management Directives

340

which

are

DYNAMIC REGIONS

REQUIRED DATA STRUCTURES
Each memory management directive requires that you set up one
of
two
data
structures within your task - 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 macro
calls are completely
straightforward.
Their format is either:
xxxx$x wdb
or
xxxx$x rdb
where
wdb rdb -

the label or address of the WDB
the label or address of the RDB

Examples:
CRAW$C
CRRG$S

WDB
#RDBI

As with other executive directives, the $, $C! or $8 form of
directive may be used.

each

Region Definition Block (ROB)
An RDB contains information needed to create a region and/or
The RDB
to
attach to a region in a system controlled partition.
is used by the following directives.
1.

Attach Region (ATRG$)

Create Region (CRRG$)

Detach Reg ion (DTRG$)

341

DYNAMIC REGIONS

ARRAY
ELEMENT

RDBBK$
ARGUMENT

SYMBOLIC
OFFSET

BLOCK FORMAT

R.GID

REGION ID

R.GSIZ

SIZE OF REGION (32W BLOCKS)

BYTE
OFFSET

o
irdb (1)

2
irdb (2)

siz

4
irdb (3)
nam

R.GNAM

NAME OF REGION (RAD50)

irdb (4)
10
irdb (5)
par

R.GPAR

irdb (7)

sts

R.GSTS

REGION STATUS WORD

irdb (8)

pro

R.GPRO

REGION PROTECTION WORD

REGION'S MAIN PARTITION NAME (RAD50)- 12

irdb (6)
14

TK-7733

Figure 8-1

The Region Definition Block

342

DYNAMIC REGIONS

Figure 8-1 shows the layout of the RDB along with the
symbolic offsets.
Use the RDBBK$ macro to create and initialize
an RDB.
Figure 8-1 also shows the RDBBK$ arguments for
the
various RDB elements.
The meaning of the elements is as follows.
•

Region ID - a unique number assigned to a region when your
task attaches to a region. The number associates the task
with the region and is returned by the Executive after
your task attaches to a region.

•

Size of Region - the size ofa region to be created,
in
32-word blocks.
It is also returned by the Executive when
attaching to an existing region.

Name of Region - up to six characters.
It is assigned
• when
a region is created and used when attaching to a
region.
•

Region's Main Partition Name controlled partition.

the

name

•

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.
See Table 8-2 for a list of 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; or: system, owner,
group, and world.
World
DEWR

Group
DEWR

Owner
DEWR

System
DEWR

1110

0000

the

system

= 167000(8)

A 'I' means access is denied, a
'0' means access is
permitted.
So the example means that world and group have
just read access, and owner and system have all accesses.

343

DYNAMIC REGIONS

Table 8-2

Region Status Word

344

DYNAMIC REGIONS

Creating an ROB in MACRO-11
The format for the RDBBK$ macro call is:
RDBBK$

siz,nam,par,sts,pro

No argument is provided for
the
region
ID because
it is
always
returned
by the
Executive and is never specified by the
bits,
user.
See Table 8-2 for a list of the region status word
including
their
symbols and meanings.
We will discuss these
Any
further
when we discuss
the
individual
directives.
information not filled in at assembly time using the RDBBK$ macro
can be filled in using direct MOVS at run time.
Examples:
To create an RDB for use in creating a region with:
Size in 32(10) word blocks = 2
Region name = MYREG
Partition name = GEN
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
pr i v i leg e s •
RDBBK$

2,MYREG,GEN,<RS.ATT!RS.MDL!RS.WRT),177017

Expansion:
.WORD
.WORD
• RAD50
.RAD50
.WORD
.WORD

0
; Reg ion ID
Reg ion si ze
2
/MYREG/
; Reg ion name
/GEN
; partition name
/
<RS.ATT!RS.MDL!RS.WRT) ; 000242 (8) Region status
; word
177017
; Reg ion protection word

345

DYNAMIC REGIONS

The example below shows the use of a MOV instruction
the region size at run time.

set

To create an RDB for use in creating a region with:
Size in 32(10) word blocks = 1000(8)
Region name = XXXX
partition name = same as task is installed in
Region status = do not delete, desired access to be filled in
before attaching
World to have no privileges, all others to have all privileges
RDBBK$

0,XXXX"RS.NDL,170000

Expansion:

o
o

Reg ion ID
Reg ion si ze
; Reg ion name
parti tion name
100(8), Region status word
; Region protection word

.WORD
.WORD
.RADS0
.WORD
.WORD
.WORD

/XXXX /
0,0
RS.NDL
170000

MOV

#1000,RDB+R.GSIZ

346

Set region size at run time

DYNAMIC REGIONS

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.
1.

Create Address Window (CRAW$)

Eliminate Address Window (ELAW$)

Map Address Window (MAP$)

Unmap Address Window (UMAP$)

Send by Reference

Receive by Reference

(SREF$)
(RREF$).

Figure 8-2 shows the
layout of the WDB along
with the
symbolic offsets.
Use the WDBBK$ macro to create and initialize a
WDB.
Figure 8-2 also shows the WDBBK$ arguments.
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 for the
task window.
Windows
1-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.

•

Base APR - The base APR to be used in mapping the
which sets the base virtual address.

•

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.
It is
returned by the Executive
in the
RDB after
an Attach
Region directive.
You 'must move the value returned from
the RDB to the WDS before mapping to the region.
NOTE
The Task Builder option WNDWS=n must be
used
to
specify the additional number of window
blocks needed for dynamic windows.

347

window,

DYNAMIC REGIONS

ARRAY
ELEMENT

WDBBK$
ARGUMENT

SYMBOLIC
OFFSET

BLOCK FORMAT

W.NID
W.NAPR

W.NBAS

VI RTUAL BASE ADDRESS (BYTES)

BASE APR

iwdb (1)
apr
iwdb (2)

BYTE
OFFSET

WINDOW ID
2

4
iwdb (3)

siz

W.NSIZ

WINDOW SIZE (32W BLOCKS)

iwdb (4)

rid

W.NRID

REGION ID

iwdb (5)

off

W.NOFF

OFFSET IN REGION (32W BLOCKS)

iwdb (6)

len

W.NLEN

LENGTH TO MAP (32W BLOCKS)

iwdb (7)

sts

W.NSTS

WINDOW STATUS WORD

iwdb (8)

srb

W.NSRB

SEND/RECEIVE BUFFER ADDRESS

6
10
12

14
16

TK-7736

Figure 8 -2

The Window De fin i t ion Block

•

Offset in Region (32-word blocks) - The offset within the
region at which mapping is to begin.
It 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.
It 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.
It is 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 8-word
buffer
for
sending or receiving data as part of the Send
by Reference and Receive by Reference directives.

348

DYNAMIC REGIONS

Creating a WOB in MACRO-11
The format of the WDBBK$ macro is:
WDBBK$

apr,siz,rid,off,len,sts,srb

Note that no argument is provided for either the window ID or
the base virtual address,
because these
elements are always
returned by the Executive.
Table 8-3 shows a list of the window
status word
bits, including their symbols and meanings. We will
discuss these further when we discuss the individual directives.
Table 8-3

Window status Word

349

DYNAMIC REGIONS

Examples:
To create a WDB to describe a window with the following:
APR = 7
Size in 32(10) word blocks = 100(10)
Region is to be mapped in a CRAWS or RREF$ directive
Map with read access.
WDBBK$

7,100.,0,0,100.,<WS.MAP!WS.RED)

Expansion:
.BYTE
.WORD
.WORD
.WORD
.WORD
• WORD
.WORD
.WORD

0,7

o
100.

o
o

100 •
WS. MAP! WS. RED

Window ID, APR
Base virtual address
Leng th
Reg ion ID
Offset in region
Leng th in reg ion
000201(8), window status word
; Send/Receive buffer address

To create a WDB to describe a window with the following
characteristics:
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.
WDBBK$

5,200,0,5,10.,<WS.64B!WS.WRT!WS.DEL)

Expansion:
.BYTE
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD

0,5

Window ID, APR
Base virtual address
200
; Window length
o
; Region ID
Offset in region
5
10.
; Length in region
WS.64B!WS.WRT!WS.DEL ; 000412(8), Window status
; word
o
; Send/Receive buffer address

350

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) •

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

Use the reg ion.

Detach from the region (Detach Region
ex it) •

window

(Create

Address
(Map

directive

Window
Address

task

Steps 1 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,
or what
attaching
and mapping mean, look over the sections on Windows and
Regions in the last few pages of Module 5 on Memory Management.
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,
and
notes
about
its
use.
For a complete discussion of each directive, see
Chapter 5 of the
RSX-I1M/M-PLUS Executive Reference Manual.
For
additional
information on
the memory management directives, see
Chapter 3 of the same manual.

351

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.

•
•
•
•
•

Size of region (in 32(10) word blocks)
Name of region (becomes a private reg ion if no name)
Name of partition (defaults to partition of task)
Reg ion status word - mark for
(default is mark for delete)

delete

not

delete

Region protection word - determines permissible access
region.

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
direct i ve sta tus wo rd).
If th e
reg ion al read y ex i sts ,
success
status is returned.
Therefore, RS.CRR can be used to tell whether
the region was in fact created, or whether it already existed.
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)
reg ions 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.

352

DYNAMIC REGIONS

Example 8-1 shows how to create a named region which is left
in existence on last detach.
The following notes are keyed to the
example.

set up the RDB.
RS.NDL set specifies that the
to be left in existence.

Region protection word =

region

World
DEWR

Group
DEWR

Owner
DEWR

System
DEWR

1111

0000

(2)

1 7

(8 )

- Bit set means access is to be denied.

Issue the directive to create the region,
specifying
the
RDB address as the only argument.
Here we use the $C form
of the directive.
Any form is allowed.

Check for a directive error.

Display message and exit.

353

DYNAMIC REGIONS

.TITL£
.IDENT
.ENABL

2
3
4

Enable lower case

File CRERG.MAC

;

; CRERG creates a named re~ion, and exits,
; leavin~ the re.ion in existence.

:7
:to
11

CRERG
lOll

12
:L3
14
1,5
16
17
18
19
20
21
22
23
24
'")C"

fa ;~

RDB:

3:~

34
35
36
37

tem ITIc~C 1"'('lS

with:
- 100 (32. word blocks)

MYREG
"" GEN
- WO:None,SY:RWED
OW: RWED" Gf~: F~WED
Do not mark for delete on last detach
ICRERG SUCCESSFUL.LY CREATED MYREGI

;

SMES:
L.SMES
BUFF:
EFMT:
;

START:

.ASCII
::::. ""SMES
• BL./(B
80.
; SEDMSG buffer
.ASCIZ IERROR IN CREATING REGION. DSW :::: %D.I
.EVEN
CRRGSC
BCS
QIOWSC

EXITSS
; Error code
ERR:
MOV
MOV
MOV
CALL.
QIOWSS
EXITSS
.END

~58

>f~UN

re~ion

S~~;

Name
Parti t:ion
Protection

[ ?8

30
31
:32

EXITSS,RDBBKS,CRRGSC
QIOW$C, (~IOW$S
Sizf~

827

o 29

.MCALL
.MCALL
RDBBI(S
Define

RDB
; Create re~ion
ERR
; Branch on dir error
IO.WVB,5,1",,(SMES,L.SMES,40) ; Write
success mef:)S(:1g€~
E}"dt

:JI:EFMT,R:L
Set UP for SEDMSG
:/I:SDSW,R2
:ft:BUFF,RO
SEDMSG
; Edit error messa~e
tIO.WVB,:JI:5,:lf:l",,(:JI:BUFF,Rl,t40) ; Write
; message
; ENit
START

CF:EI:::O

CRERG SUCCESSFULLY CREATED MYREG

Example 8-1

Creating a Named Region

354

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:
•
•

Reg ion name
Region status word

(indicating R,W,E,D access)

The following RDB output parameters are returned:
•
•

Reg ion ID
Reg ion si ze

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 chang ing a reg ion from do not delete to mark
for
delete, an explicit detach is required with RS.MDL set in the
region status word.
If the task exits without issuing an explicit
detach,
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 issuing an explicit detach, no detach is
performed by the Executive.

355

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.WOV = -85.) results.
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, addition input parameters are needed.
See
Mapping to a Region in the following section.
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.

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
is assuming,
of course, that the task keeps control of the
CPU.
The APRs are reloaded every time a new task takes control of
the CPU.

356

DYNAMIC REGIONS

Use the Map Address Window directive (MAP$) to map
to a region, with the following WDB input parameters.
from

window

•

Region ID - Returned to RDB by Attach (move
WDB) •

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
win dow s tat us wo rd.
If WS. 64 B i s s e t, an 'y wh ole n urn be r
may be specified.

•

Length to Map - If specified, must be less than, or equal
to,
either the
length of the window or
the length
remaining
in the
region,
whichever
is shorter.
If
defaulted, it is set to the shorter of the two.

•

Window status word - actual access desired (read-only, or
read/write).
Read-only is always requested by default.

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 type of access desired is used here in addition to when
you attach to the region, because several different 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 or read/write access.

357

DYNAMIC REGIONS

Example 8-2 shows how to create a region and place data
into
it,
leaving
it in existence upon exit.
Example 8-3 shows how to
attach to that region, read and display the data, and then detach
and mark it for delete.
One run session covers both examples.
The following notes are keyed to Example 8-2.

Task-build with the WNDWS=l option, allocates space in the
task header for one additional window block.

o
e

We use the $ form of the memory management directives.

WDB for virtual address window.
The third argument is for
the
region ID, which will be filled in at r un tim e, aft e r
the task attaches to the region.
In the window status
word,
WS.MAP
means
that the Create Address Window
the
directive will both create the window and map it to
not
specified.
region.
WS.RED is automatic, even though

Create region and attach.
Use DIR$ since
the $ form of the directive.

RDB for region.
RS.ATT set means Create Region
will both create the region and attach to it.

you

directive

are

using

Move region ID, returned in RDB after attach, into WDB for
mapping.

o
o

Create a virtual address window and map it to the region.
The virtual address window begins with APR 7;
therefore,
the base address in the window is 160000(8), corresponding
to the base address in the region.
place a byte count, 400(10), in the
first
word
in the
reg ion.
This
is
just one way to communicate this
information to other tasks which access the
region.
The
length of the region is returned when a task attaches to
the region.
You could use this as an alternate way to
pass information-about the amount of data.
and 100(10)
words of
Move 100(10) words of ASCII "AB"
This gives you 200(10) words
ASCII "12" into the region.
or 400(10) bytes of data.

ct
CD

Display a successful creation and
at the terminal.

initialization

Detach from the reg ion and then ex it, leaving
in existence.

358

the

message
reg ion

DYNAMIC REGIONS

.TITl!::
.IDENT
.ENABL.

2
3
4

CREURG
lOll

Enable lower case

File CREURG.MAC

6
7
8
9

ProSram to create a named resion (attached on creation),
create a virtual address window (mapped on creation),
place ASCII data in to the re~ion, detach from the
reSion and exit, leavins the resion in existence.

:LO

11
Task-build instructions:

12
13

>LINK/OPTION/MAP CREURG
Option? WNDWS=l
OPTION? <RET>

:1.4

15
16
17
18
19
20
2:1.

A
V

24
25
21.>
27

• MCALL.
.MCAlL
REG:

29
30
31

o :~:3

~52

WSW
RDB:
;

WIN:

34
35

o 36

37
38
39

WDB:

41
42

DET:

EXITSS,RDBBKS,WDBBKS,CRRGS,CRAWS
DTRGS,DIRS,QIOWSS,QIOWSC

CI=<RG$
;DPB for create reSion
RIIB
Define reSion with:
Si~::e
= 100 (32. word blocks)
Name
MYREG
Partition
- GEN
Protection
= WO:None,SY:RWED,
OW:RWED"GR:RWED
Do not mark for delete on last detach
Attach with read, write and delete access
- <RS.NDL!RS.DEl!RS.RED!RS.WRT!RS.ATT>
RDBBK$ 100,MYREG"GEN,WSW,170000
; I1PB for create address window
CRAWS
WDB
Define window with:
APR
7
Size
- 100 (32. word blocks)
Offset in reSion ::: 0 (32. word blocks)
lensth in reSion = 100 (32. word blocks)
Map on create with readlwrite access
WDBBKS 7,100,,0,0,,100,<WS.MAP!WS.WRT>

;

DTRG$

DPB for detachins
from reSion
2
1/0 status block
ICREURG HAS CREATED AND INITIALIZED THEI
I REGIONI

48
4'"1
50
~5 :L
!52
!53

.BLKW
.ASCII
.ASCII
LDNMES ::::. -DNMES
; Error fOT'mat strinss
FeRRER: .ASCIZ IERROR CREATING REGION. DSW = %D.I
FCRWEI:;:: .ASCIZ IERROR CREATING WINDOW. DSW = %D.I
FCHODE: .ASCIZ IDIRECTIVE ERROR ON QIO. DSW ::: %D.I
FCHOIE: .ASCIZ !I/O ERROR ON QIO. CODE = %D.!
FDETER: .ASCIZ IERROR DETACHING FROM REGION. DSW = %D.I

54
55

BUFF:

44
45
46

IOSB:
DNMES:

RDB

.BLKB

Output btlffer

80.

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

359

DYNAMIC REGIONS

0
0

CD
CD

56
57
58
59
60
61
62
63

START:

DIR$
BCS
MOV
MOV

65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
8l

.EVEN
DIR$
BCS
MOV

LOOf':

MOV
MOV
SOB

MOV
MOV
SOB
(HOW$C
BCS
TSTB
BLT
DIR$
BCS
EXIT$S
; Error code
ERR1:
MOV
LOOf'B:

8:~

83
84
85
86
87
88
89
9()

91
92
93
94
95
96
97
98
99

BR
MOV
BR
ERR3D: MOV
BR
ERR3I: MOV
MOV
MOV
BR
ERR4:
MOV
SHOERI~ : MOV
MOV
CALL
aIOW$S
ERR2:

EXIT$S
.END

; Create region and attach
tREG
; Check f()r error
ERR1
RDB+R.GID,WDB+W.NRID ; Move region III
into WDB
Create window and lTIa?
tWIN
Check fOT' error
ERR2
Set base addr in region
t160000,R5
t400.,(R5)+
Move b~te count to 1st
word in regiorl
t100.,RO
t of words of 'AB' data
t·AB,(RS)+
Move chars to region
RO,LOOF'
Decrement counter and
loop until done
t of words of '12' data
t100.lIRO
t·12,(RS)+
Move chars "to region
RO,LOOF'B
Loo? 1..lrIt i 1. done
IO.WVB,S,1"IOSB,,(DNMES,LDNMES,40>
Branch on dir error
ERR3D
Check for I/O error
IOSB
Branch on I/O error
ERI~31
Detach from region
tDET
Check for error
ERR4

tFCRRER,R1

Create region error
message
Brarlch to common code
Create window message
Branch to common code
aIO directive message
Branch to common code
EHtend sign on statlJs
and move t,o arg block
aIO I/O error
Branch to COlTIlllOn code
Detach resi(:m message
Set U? for $EDMSG

SHOERR
tFCRWER,R1
SHOERR
tFCHODE,Rl
SHOERR
IOSB,RO
RO,$DSW
tFaIOIE,Rl
SHOERR
:J:FDETEI~, R1
tBUFF,RO
t$DSW,R2
; Edit message
$EDMSG
tIO.WVB,t5,t1",,(tBUFF,R1,i40>
; Dis?la~ message
; EHit
START

HIJn Session
>RUN CREURG
CREURG HAS CREATED AND INITIALIZED THE REGION
>RUN ATTURG
ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB
ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB
ABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABABAB
ABABABAB12121212121212121212121212121212121212121212121212121212
1212121212121212121212121212121212121212121212121212121212121212
1212121212121212121212121212121212121212121212121212121212121212
:1.212121212121212

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

DYNAMIC REGIONS

Example 8-3 attaches to the region created by Example 8-2,
reads and displays the data, and then detaches from the region and
marks it for delete.
The following notes are keyed
to
Example
8-3.

o Builder
Again, task-build wi th the WNDWS=l option so that the Task
allocates space for the window block in the task
header.

This example uses all three forms of the
illustration purposes.

directives,

for

The RDB for attaching to the region.
In fact,
the only
required
information
is the
region name and the region
status word.
The parti tion name and si ze, al tho ugh
included here, are not needed.
RS.MDL set marks the
region for delete when we do an explicit detach.
You need
delete access to mark the region for delete (RS.DEL).
Also, attach with read (RS.RED) and write (RS.WRT)
access
so tha t yo u can map wi th read/wr i te access.
WDB for the virtual address window. We map the entire
o The
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.

o Attach to the reg ion.
ct

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

set base address in region - again 160000(8), because
base APR is APR 7.

the

The first word in the region contains a character or
count.

byte

Number of characters to print on each line,
except
last line (if it has less than 64 (10) characters).

the

ct
C)

361

DYNAMIC REGIONS

Loop through region, printing 64(10) characters per line.
This technique
is used to demonstrate how to control the
width of the output and make the run session fit on an
8-1/2" by 11" page with margins.
If the full terminal
buffer width (typically 80(10) or 132(10)) is accept~ble,
one
QIO
directive, with the total
character count
specified for number of characters, would be enough to
write the entire region.
In that case, the terminal
driver will automatically wrap to the next line after a
full line is displayed.
Detach from the region. An explicit detach is required to
mark the region for delete.
NOTE
In Chapter 7, we discussed the fact that a
task needs read/write access to a region to
issue QIOs to write directly from a
region.
This also applies to dynamic regions. ATTURG
issues QIOs directly from MYREG.
Therefore,
although it appears that ATTURG only needs
read access,
it actually needs read/write
access.
See the discussion following Example
7-1 in Chapter 7 for additonal information.

362

DYNAMIC REGIONS

.TITLE
.IDENT
.ENABL

1
2
3

4
5

ATTURG
/011

Enable lower case

L..C

File ATTURG.MAC

Prosram to attach to an existinS resion, create a
virtual address window (mapped on creation)y read
ASCII data from the resion, detach from the reSion
and exit.
The reSion will be deleted on last detach.
The first word in the reSion contains a count of how
manw b~tes of data are in the re~ion

7
B
9
10
11
1'">
.:..
:L3

14
15
lc.t,
17
1B
19
20

Assemble and task-build instructions:
>MACRO/L..IST LB:[lylJPROGMACS/LIBRARY,dev:[ufdJATTURG
>LINK/MAP/OPTION ATTURGyLB:[lylJPROGSUBS/LIBRARY
}Option1 WNDWS=l
}Option1 <RET)

0[ 23
21

2~!

A[~~

27
28
29

RDB:
; .

32
33

;
WIN:
WDB:

35
36
O 37

39
40
4:1.
42
4:~

0[:;
46

;
IOSB:
START:

.MCALL EXIT$S,RDBBK$,WDBBK$,ATRG$C ; Swstem
macros
.MCALL CRAWS,DTRG$S,DIRS,QIOWSS
; SUPplied macros
.MCALL DIRERR,IOERR
RDBBK$ 100,MYREG,GENy<RS.MDL!RS.DEL!RS.RED!RS.WRT>
Define reSion with:
- 100 (32. word blocks)
Si::~e
Name
"" MYREG
Partition
"" GEN
Mark for delete on last detach
Attach with read, write and delete access
CRAWS
WDB
;DPB for create address window
WDBBK$ 7,100,OyOyl00,<WS.MAP!WS.RED!WS.WRT>
Define window with:
APR
- 7
Size
- 100 (32. word blocks)
Offset in resion = 0 (32. word blocks)
Lensth in reSion - :1.00 (32. word blocks)
Map on create with read and write access
.BLKW
ATRGSC
BCS
MOV
DIRS

IIO status block
RDB
Attach to reSion
ERRl
Check for error
RDB+R.GID,WDB+W.NRID ; Move resion ID
; i rd:,<'1 WDB
tWIN
; Create window

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

363

DYNAMIC REGIONS

47
48
49

o 5150

lOOP:

BCS
MOV
MOV
MOV
QIOW$S

BCS
TSTB
BLT
SUB
BLE
ADD
CMF'

S:-S
54
5~:;

56
57
~j8

59
60
61
62

BlE
MOV

6:~

64
65
66

67
1.)8

69
70
71
72
73
74

ERR2
Check. for e r r() r
t160000,R5
Set base addT' in re~H (")n
(RS)+,R4
Get character count
; Chars per 1 irH?
:8:64. ,1:;:3
tIO.WVB,t5,ll"tIOSB,,(R5,R3,140>
Write datc~
ERR3D
Check for dir error'
IOSB
Check for liD €~ Y' ro Y'
Branch on error
ERR31
R3,R4
COITIPIJte chars left
Branch if done
DONE
R3,R5
Point to neNt char
f"~3, R4
Check for .::: 64. chaT's
left to print
). or ::::, print ne~·~t line
LOOP
<, print onl~ that lTIan~
R4,R3
chars
Print the line
LOOP
Detach from reg i or.
tRDB
E/:;;R4
Check for e T' r(") T'

BR
DTRG$S
BCS
EXIT$S
; Error handling code
ERFU:
DIRER/:;; <E/:;;ROF< ATTACHING TO REGION>
DI/~ER/:;;
<ER/:;:OR CREATING WINDOW AND MAPPING)
ERR2:
ERR3D: DIRERR <ERROR W/:;:ITING DATA>
tIOSB,(ERROR WRITING DATA>
ERR~5 I:
IOERR
ERR4:
DIRERI:': <ERROR DETACHING Ff"~OM REGION>
.END
START
DONE:

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

364

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 access privileges needed to pass the
protection check.
Use the Send-by-Reference directive (SREF$) to send a
by reference, with the following input parameters.

region

Receiver task name
WDB - Reg ion 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
receiveby-reference queue).
The receiver
task
is attached
to
the
region when the
reference
is queued
up.
This avoids the problem of the region
being deleted if the sender exits before th~ receiver receives the
region.
Remember
that private
regions are always marked for
delete on last detach.
If you are using the event
flag
for
synchronization,
note
that the
flag should be used to notify the sender as to when the
receiver receives the region by reference.
It is not the same as
Send and
Receive Data directives, where the flag is set when the
reference is queued.
That flag
should
be
used
to notify the
receiver.

365

DYNAMIC REGIONS

The receiver follows a somewhat modified procedure to
the region, as follows.
1.

Crea te wi ndow.

After reference is queued, receive by reference
region ID in WDB)

Map to reg ion.

Use region.

Detach from region.

access

(fills

Use the Receive-bY-Reference directive (RREF$) to
receive
reference to a region, with the following WDB input parameters.

Window Status Word - WS.MAP for receive and map;
receive data or exit.

WS.RCX

for

10(10) word buffer for sender task name
and data.

(in

The following WDB output parameters are returned, all as
by the sende r :

set

Buffer Address Radix-50 format)

Reg ion
Offset
Leng th
Window

ID
into region
to map
status word -

describes how attached

If the WS.MAP bit is set, the Executive maps
the window to
the
reg ion,
us i ng
the 0 ff set,
length, and window sta tus 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 to exit the
task
if
there are no packets in the receive-by-reference queue.
Although there are 'some similarities, Send Data and
Receive
Data
are
completely independent from
Send-by-Reference and
Receive-bY-Reference.
The receive (data) queue is separ~te
from
the receive-by-reference queue.
If you want to use' ASTs for synchronization, use the
Specify
Receive-by-Reference AST directive
(SRRA$).
This causes the
Executive to transfer control to the specified AST routine when a
packet
is placed
in the receive-by-reference queue.
Generally,
issue this directive when the task starts up.

366

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.

ct
__

This program uses the supplied macro DIRERR to generate
directive error messages.
Therefore, PROGMACS.MLB must be
specified
when
assembling,
and
PROGSUBS.OLB
when
task-building.
The RDB for the region.
private region.

The name is defaulted to create a

The WDB for
the virtual
address window.
The length
actually mapped will be returned after mapping.
Read
access is automatic for map, so WS.WRT gets read/write
access.

Create and attach to region, create virtual address window
and,map it to the region.
Use the base virtual address in the window (returned
in
the WDB) to set the base address of the region.
Since APR
7 is the base APR, this address is 160000(8).

o Fill the region with ASCII Ms.
Send-by-reference to RCVREF (Example 8-4).
Event flag
o will
does
a
be
set
when
RCVREF
actually
I

receive-by-reference.

Display message that a region was created and sent.
wait for event flag I to be set.

Then

Display message saying RCVREF received
exit.

then

region,

and

Exit.
The Executive will detach you from
the region.
Note
that even if SNDREF exits before REVREF receives the
region by reference,
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.

367

DYNAMIC REGIONS

.TITLE
.InENT
.ENABL

2
3

SNDREF
lOll
LC

Enable lower case

File SNnREF.MAC

6
7
B
('I
10
1.1

SNDREF creates a 64-word (2 block) unnamed re~ion and
fills it with ASCII characters. It then sends the
resion to RCVREF, and then waits for RCVREF to receive
the ~esion. (This is sisnalled b~ event flas tl.) It
then prints a messaSe and exits. Since the area is
unnamed, it is automatica1l~ deleted when the last
attached task exits.

1."")

1. :~
14

Assemble and task-build instructions:

:1.5

.p~
19

>MACRO/LIST LB!Cl,lJPROGMACS/LIBRARY,dev:CufdJSNDREF
>LINK/MAP/OPTION SNDREF,LB:[1,1.JPROGSUBS/LIBRARY
Or--t:i.on? WNDWS==l.

20
21.

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

22
23
24

.MCALL
.MCALL
.MCALL
• MCALL..
.NLIST

:~5

26
27
2B
29
30
31
:32
33
34
31::"
,.:}
36
37
38
~59

40
41.
42
43
44
45
46
47
4B
49
50
51
52

Define

RPRO
RSTAT

QIOWSC,QIOWSS,RQSTSC ; S~stem macros
WTSESC,EXITSS,RDBBKS,WDBBKS
CRRGSS,CRAWSS,SREFSC
DIRERR
; Supr--lied macro
BEX
; SUPPRESS DATA

re~ion with:
Size
Name
Partition
Protection

== 2
32-WORD BLOCKS
.- nc)ne
.- GEN
= WO:none,GR:RWED
OW:RWED,SV:none

Attach on create
Read and write access desired on attach
1. 70017
== RS.ATTJRS.RED!RS.WRT
••M

Define window with:
APR
Size
Offset in re~ion
Lensth to map
;
WSTAT

- 7
== 2
== 0
- 0

32-word blocks
32-word blocks
32-word blocks (defaults
to smaller of re~ion
size and window len~th)
Map on create with read and write access
:: WS. MAP! WS. WRT

Example 8-4

Send-by-Reference (Sheet 1 of 2)

368

DYNAMIC REGIONS

54
5~)

56
~57
~i8

60
61
62
63
64

[

O 68

69
70
71

o[;~
74

75
76
77

o 7880
79

81
8')

o 8483
[

8~)

86
87

e[:~
90
CD 92
91.

94
95
96
97

98
99
F~l.Jn

;

.ASCII I SNDREF HAS CREATED THE REGION AND HASI
.ASCII I SENT IT TO RCVREF.I
L.MES j.
:::. --MESl
MES2:
.ASCII I RCVREF HAS RECEIYED IT. SNDREF IS NOWI
.ASCII I EXITING.I
LMES2 ::: • - MES~~~
.LIST
BEX
Show binar~ extensions
.EVEN
.ENABL LSB
Enable local s~mbol
blocks
Create and attach to
START: CRRG$S tRDB
MES1:

re~ion

1$
Branch on dir error
RDBtR.GID,WDBtW.NRID ; COpy re~ion ID
; into WDB
Create and map window
CRAW$S tWDB
Branch on dir error
BCS
2$
base V.A. of re~ion
MOV
WDBtW.NBAS,RO
; Fill re~ion with all M'S
count of words to move
MOV
:l:64.,R3
MOV
.KMM,(RO)+
Move in an ASCII M
SOB
R3,20$
Loop throu~h re~ion
Send the re~ion to RCVREF. EF 1 will be set when
RCVREF recieves it
SREFSC RCVREF,WDB,l
Send b~ reference to
RCVV<EF
BCS
3$
; Branch on dir error
OIOW$C IO.WVB,5,2",,(MES1,LMES1,40>; Displaw
; messa~e
BCS
4$
; Branch on dir error
; Wait for RCVREF to ~et
WTSE$C 1
; the re~ion
BCS
5$
; Branch on dir error
OIOW$C IO.WVB,5,2",,(MES2,LMES2,40>; Displaw
; messa~e
; Branch on dir error
BCS
6$
EXIT$S
; E~·d t
; Error code
1 $:
DIREr';:R (ERROR ON CREATE OR ATTACH REGION>
2$:
DIRERR (ERROR ON CREATE OR MAP WINDOW>
3$:
DIRERR (ERROR ON SEND BY REFERENCE>
4$:
DIRERR (ERROR ON 1ST WRITE>
5$:
DIF~ERR
(ERROR ON WAIT FOR>
(ERROR ON 2ND WRITE>
6>$:
Dn~ERR
START
.END
BCS
MOV

Session

>INS RCVREF
>SET TERMINAL/WIDTH:64.
>RUN SNDF:EF
SNDREF HAS CREATED THE REGION AND HAS SENT IT TO RCVREF.
I~UN RCVREF
RCVREF HAS RECEIVED IT. SNDREF IS NOW EXITING.
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM
>SET TERMINAL/WIDTH:80.

Example 8-4

Send-by-Reference (Sheet 2 of 2)
369

DYNAMIC REGIONS
The receiver, Example 8-5, receives a reference, displays the
data, then exits.
The following notes are keyed to the example.
This program uses the supplied macros DIRERR and IOERR to
o display
directive and I/O error messages.

«t

e
o
e

WDB for
virtual
address window.
The size
is
200(8)
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 long.
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.
Create the virtual address window.
Set WS.MAP so that the
receive-by-reference.

task

will

map

part

the

Receive-by-reference and map.

Set base address in region, using base virtual address for
o APR
7 (160000 (8» •

Get length actually mapped (two blocks, the same as length
of region) and convert from blocks to bytes. Just display
that many characters.
Display all characters with one QIO directive.
Note on
the
run session that we set the terminal buffer to 64(10)
to allow for margins on an 8-1/2" by 11" page.
Exit.
The Executive will detach the task from the region.
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.
Therefore,
if you receive and map in one call, issue the Create
Address Window directive with the WS.MAP bit clear;
then set it
before
issuing
the Receive-by-Reference directive.
If you use a
separate Map directive, the WS.MAP bit can be left clear.

370

DYNAMIC REGIONS

.TITLE
.IDENT
.ENABL

3
4

;+
Filf.~

!5
6
7
8

RCVREF
lOll
Enable lower case

I... C

RCVREF.MAC

Prosram to receive-bY-reference a region from SNDREF,
map to the re~ion, read ASCII data from the reSion,
detach from the region and exit. The region will be
deleted on last detach.

to
11

Assemble and task-build instructions:

t :5

o [14

MACRO/LIST LB:C1,lJPROGMACS/LIBRARY,dev:[ufdJRCVREF
LINK/MAP/OPTIONS RCVREF,LB:[l,lJPROGSUBS/LIBRARY
Opt :i. on? WNDWS:::::I.
Opticm'P <RET>

15
16
1'7
18

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

19
20

EXITSS,WDBBKS,RREFS ; External system
QIOWSS,CRAWS,DIR$
; macros
DIRERR,IOERR
External supplied
macros
Define window with:
.MCALL
.MCALL
.MCALL.

22
'")-v

A·_':)

24
2!5

26
2'7
:~8

32
~5~5
~54

3!:i
31.>

e
0

- 200 (32. word blDcks)
Allow for full APR
These are filled in on receive, as set by sender:
Offset in reSion - 0 (32. word blocks)
Len~th in reSion - 0 (32. word blocks)
reset when mapped
Access
- 0
; Note: Must map after receivins (or as part of receive)
WDB:
WDBBK$ '7,200

3'7

:38
39

REC:
WIN:
IOSB:

CRAWS
.BLKW

START:

DIRS

:JI:WIN

40
4:1
4'">
.:..

RF~EFS

4~3

45
46

.... 7

API:~

BCS
BIS

Example 8-5

WDB
WDB

Set UP DPB for RREF$
; Set UP DPB for CRAWS
I/O ~;tc~tu~; block

Create virtual address
window
ERR1
; Branch on error
:JI:WS.MAP,WDB+W.NSTS ; Set WDB to map on
; T'eceive

Receive-by-Reference

371

(Sheet 1 of 2)

DYNAMIC REGIONS

e 4847
0

DIH$
BCS
MOV

49
~5()

~5:L

MDV
MUL
CnOW$S

0[52
5~5

o 55~54

BCS

56
57
~58

60
61
b2

63
64
65
66

tREC

Receive bw reference
and lTIa?
ERR2
Branch on error
t160000,R5
Set base address in
T'e~~ii on
WDB+W.NLEN,R3
Size of re~ion to R3
t64.,R3
; Convert blocks to bwtes
tIO.WVB,t5vil"tIOSB,,(R5,R3,t40) ; Write
; data
ERR3
Branch on directive
e r rC)f'

TST8
BLT
EXIT$S
; Err'oT' code
EHH1:
DI REF~F.~
EF~I~2 :
DIRERR
EF~I~3 :
DIREF~H
ERR4:
I ()EI~F~
.END

Example 8-5

IOSB
ERR4

Check for 1/0 error
Branch on errc)r

(ERROR CREATING VIRTUAL ADDRESS WINDOW)
<ERROR ON RECEIVE AND MAP)
<ERROH ON WRITE aIO)
iIOSB,<ERROR ON WRITE aID)
START

Receive-by-Reference (Sheet 2 of 2)

372

DYNAMIC REGIONS

The Mapped Array Area
If you want to automatically set up a. large core resident
data area, without using a create region directive, you may use
special techniques to set up an area called a mapped array area.
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 immediately below the task header.
The task is automatically attached to the region, since it is
part of the task region.
Therefore, all you have to do is to
create a virtual address window and map it to the 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.
Typically, the virtual address window maps only a portion of
the region at a time. In Figure 8-3, the virtual address window
maps 4K words at a time.
This technique is used to implement virtual arrays in
FORTRAN.
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.
Use the following procedure to create a task which
mapped array area.

uses

the

Set up a separate Psect in the source code and reserve
space for the virtual address window (using .BLKB or .BLKW
statements).
Also set up symbols for reference, if
des ire d • Do no tin i t i ali ze any 10 cat ion s •

In the code, create a virtual address window.

Map the window to a portion of the region.

Later, map to other portions of the region by modifying
the offset within the region and reissuing the map
directive.

373

DYNAMIC REGIONS

Task-build with the WNDWS and the VSECT options.
WNDWS=n allocates space in the
extra window block

task

header

for

the

VSECT=psect-name:base:window-length:physical- length
where
psect-name = the name of the psect to be used
the virtual address window

for

base = the base virtual address for the window
window-length = the length of the window in bytes
physical-length = the length of the
area in 32-word blocks.

mapped

array

This option sets up virtual addressing for the
region
and specifies the amount of space to be set aside for
the mapped array area.

374

DYNAMIC REGIONS

PHYSICAL
MEMORY

TASK
IMAGE
APR 3 -

'\\
\ \

APR 2 -

APR 1 APR 0

-----------HEADER & STACK

HEADER
&_
STACK
_
__
_ _I _ _ _ _ _ _ - - - \\ - " , - -

\ \
\ \

\ \

CD INITIAL LOAD AND MAP
(3) TOTAL SPACE INITIALLY
ALLOCATED. 4K WORD
AREAS MAPPED AS
NEEDED.

\ \

MAPPED
ARRAY
AREA
(32K WORDS)

TK-7739

Figure 8-3

The Mapped Array Area

375

DYNAMIC REGIONS

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

area.

o This program uses the supplied macro DIRERR.
o block.
WNDWS = 1 is needed to reserve space for the extra window
The VSECT option sets up addressing for psect VV,
beginning at virtual address 160000(8), for
a
length of
20000(8)
bytes or 4K words.
The last argument sets up a
mapped array area 2000 32-word blocks = 200000(8)
bytes
long = 32K words.
Set up psect VV, which is used
for mapping
the mapped
array area.
Symbol A marks the beginning of the window at
virtual address 160000(8). The number of bytes
reserved
must be at least as long as the window si ze (4K words) •

e
o
e
o
tt
t»

Data to be placed in the mapped array area.
WDS for the window.
The reg ion ID is left '0' because the
region is the task region, which always has region ID 0.
Create the virtual address window and
offset 0, to the first 4K word area.

map

starting

Move "AIG7" into the first two words of the area.
Modify the offset in the region
in the WDS
(at offset
W.. NOFF)
to 200'(8)
blocks, so that mapping will begin at
that offset within the region.
Map to the second 4K word area.
Move "B2G7" into the first two words of the second 4K word
area.
Similarly, map and move "C3G7" to the third 4K word
and "D4G7" to the fourth 4K word area.

CD
CD

area,

Map back to the fi rst4K word area.
Di spla y the fi r st fo ur bytes.
Map to the second 4K word area and display the first
bytes.

376

four

DYNAMIC REGIONS

Map to the fourth 4K word area and display the first
bytes.

four

Map to the third 4K word area and display the
bytes.

four

first

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.
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 the on-line
files
(which should be under UFD [202,2]) or the printed copies 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
return to this module for further study.

377

mastered

the

material,

DYNAMIC REGIONS

(.TITLE

.IDENT
+ ENABL

VH3
/Oll
I... C

; Enable lower case

c·

This proSram uses the mapped arra~ area. It places
data in the first 2 words of each of the first four
4K word blocks. It then retrieves the data and prints
it at the terminal.

...J

6
7
8
9
1.0

Assemble and task-build instructions:

11
0[12
13

o [ 1416
:Lt")

.1
1 ·..,

; ....

2()

A
V

[ 23

MACRO/LIST LB:[1,1]PROGMACS/LIBRARY~dev:[ufdJVS3
LINK/MAP/OPTIONS VS3~PROGSUBS/LIBRARY
Opt:icm? WNDWS::::1.
Option? VSECT=VV:160000:20000:2000
Opt i on'~ <F~ET>
.MCALL

QIOW$S~EXIT$SvWDBBKS,CRAWSS~MAPSS

• MCALI...
.PSECT

DI I~EF;~F~
VV CONvGBI...

• BU(B

200(}O

S~~~> t€·~m

:1.9

"'L

:;~

[

e 2~~
29

30
31
T')

033

34
3:5

O[~~
39
O[:~

o 43
42

e[:~

/TI(:~C po~;

SI.JPP I :i. f.~\d

ll'Ia(:~ T'()

Psect for mapped arra~
is r€~a
Used to reference the
vi rttlisl (:1r~:~(:~
Back to blank Psect

.PSECT
DATA:
.ASCII /Al/
DATB:
.ASCII /82/
DATC:
.ASCII /C~3/
DATD:
.ASCII /D4/
DATG:
.ASCII /G7/
; Define window definition block.
WDB:
WDBBKS 7,200vOvOv200,<WS.MAP!WS.WRT>,0
START: CRAWSS tWDB
; Create window and /TIap
; to 1st 4KW block
BCC
Ai
; Branch on dir ok
DIRERR <ERROR CREATING WINDOW OR ON FIRST MAP)
Ai:
MOV
DATA,A
Move data to 1st word
:fJ:2,R5
MOV
DATGlIA(f~~)
MOV
Move data to 2nd word
4~WDB, RO
MOV
:fJ:200,W.NOFF(RO)
MOV
Set UP next 4KW block
MAPSS
:fI:WDB
Map 2nd 4KW block
BCC
A4
Branch on dir ok
DI F~EJ:~F~ <ERROR ON lST MAP TO 2ND 4KW BLOCK)
MOV
DATB"A
DATG,A(I:;::5)
MOV

Example 8-6

Use of the Mapped Array Area

378

(Sheet 1 of 2)

DYNAMIC REGIONS

47
48
49
50
51

A7:

53
54
5~:;
~:;6

~57

A8:

!58

8[59
60
61
62
63

MAP~;S

BCe
DIF~ERR

All:

.[:~

67
68

[ 69
70

A:J.l:

.[~~

A:l.2:

80
Hun

QIOW$S
MOV
MAF'$S
Bee
DIF~EF~R

(.1:1. 0 :

CD 71
72
73

MOV
MAP$S
BCC
DIF~ERI:::
MOV
MOV
MOV
MAP$S
Bce
DII:::ERI:::
MOV
MOV
MOV

:fI:400 ~ W. NOFF (F~O) 1I Sf.~t !..IF' 3rr..f 4K block
:JI:WDB
A7
<ERI:~(}I:~ ON :J.ST MAP TO 31:~D 4KW BLOCK>
J)ATC~A

DATG~A(R~5)
·:B=600~W+N()FF(H(»

; Set

Ufo"

4th 4K bl(Jcl.:.

:B=WDB
A8
<Ef~I~OF~

:LST

MAP TO 4TH 4Kl4 BLOCK>

DATDlIA
DATGlIA(~(~)

Go back tC) :J.f.;t 4K bl(Jcl.:.
:lJ:O"W.NOFF(I:::O)
:lJ:WDB
Branch on cf:i. T' ('1k
A9
<EFa~OF~ ON 2ND MAP TO :J.ST 41,W BI... OCI(>
:lJ:IO.WVB":fI:5,:fI:1,, " " ,,<:lJ:A,,:lJ:411:IJ:40>
GC) to 2nd 41( block
:1J:2() 0 "W +NOFF (F~O)
:lJ:WDB
A:J.O
v Branch orl d:i.r c)k
<EI:n(OF~ ON 2ND Mr.1P TO 2ND 4KW BLOCI,>

QIOW$~)

:fI:IO+WVB,:fI:5,,:fI::J.~"1I,,<:fI:A,,:fI:411:IJ:4(»

MOV
MAP$S
Bee
DIRERR
QIOW$S
MOV
MAP$S
Bee
DIRERI:::
QIOW$S
EXIT$S
.END

:JJ:600" W• NOFF (1:::0) v Go to 4th 41"< blocl.-:.
~I:WDB

A:J.:J.
v Branch on ci:i. r ok
<ERROR ON 2ND MAP TO 4TH 4KW BLOCK>
:lJ:IO.WVB":fI:5":fI::J.,,,,,,<:fI:A,,:fI:4,,:fI:40>
:lJ:400, W. NOFF (1:::0) ; Go to 3rd 41-( bl(Jck
:lJ:WDB
At:?
v Brcmch on d:i.l"' ok
<ERI~Cm ON 2ND MI~P TO :~FUI 4KW BLOCK>
:fI:IO.WVB,:JI:5,,:fI::J.,,~,~<:fI:A,,:fI:4,,:JI:40>

v I::.~·{l. t
STAr~T

Session

>RUN VS3
A:J.G7
:82G7
D4G7
C:5G?

Example 8-6

Use of the Mapped Array Area

379

(Sheet 2 of 2)

· FILE 1/0

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

383

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
devices
have
the
characteristics.
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.

and magtape are examples of
.
Ha r d dis ks ,
flo PP Y qisks,
file-structured
devices.
The following definitions should prove
helpful in our discussion.
a file - a collection of related
logical unit of mass storage.

385

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
Types of File-structured
Devices
There are
two
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 se~uential 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-IIM,
the magtape ancillary
(MTAACP) supports the ANSI file structure.

control

processor

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 called block-st~uctured devices
or
block-replaceable devices, have the following characteristics.
They can:
•

Store and retrieve data in units called blocks

•

Write or read blocks in any order

•

Rewrite blocks without interfering with other blocks.

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

386

RX211)

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 ~f 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.

387

FILE I/O

COMMON CONCEPTS OF FILE I/O
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 I/O
Use the following three basic steps to do file I/O.
1•

ope n th e f i 1 e •
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).

2•

Pe r for m th e I/O

0 pe rat ion s •

Use macros to invoke subroutines to store data in
file and/or retrieve data from the file.
3.

the

Close the file.
Notify the
system
completed,
so
tha t
performed.

388

that the
file
operations
are
appropriate cleanup work can be

FILE I/O

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

need

understand

its

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 (1 0 ) wo r d s 0 r 5 12 (1 Qj ) _ b yt e s
long •
So me d ev ice s d i v ide 0 r
format their volumes into pieces which 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.

389

FILE I/O

Table 9-1

Comparison of physical, Logical and Virtual Blocks

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 read 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 QIO directive for you.
The Executive converts the
virtual block number to its corresponding logical block number and
issues a read logical blockQIO.
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 BASIC-PLUS-2 READ under
the Record
Management Services (RMS)~
The BASIC-PLUS-2 compiler converts the
READ to aRMS $GET call. r RMS converts this to a QIO, to read
the
corresponding virtual
block.
From that point on, the steps are
just like those in the FORTRAN example.

390

FILE I/O

FILE
VIRTUAL
BLOCK #'S
(IN THE
FILE)

SAMPLE. TXT; 1

I I I I I I I I
1

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

391

FILE I/O

FORTRAN

MACRO-11
ENTERS HERE

··
·
··
·

···
···

READ (5,10)
1DATA

COMPILER

FORTRAN RECORD

GET$

READ DATA

BASIC-PLUS-2
RECORD

VIRTUAL
BLOCK #

LOGICAL
BLOCK #

I FCS. OIOIO.RVB.

FCS RECORD

EXEC
F11ACP

OIOIO.RLB

"r--....

...........

.......

...,....,

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 Blocks

Figure 9-3 shows the FILES-II structures which are
used
to
support virtual-to-logical
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
vol ume.
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 = log ical block 336851 (10), vb 2 = lb 336852 (10) ,
vb 3 = Ib 336853 (10), vb4 = lb 336854 (10), and vb 5 = Ib
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
(virtual
blocks 57 (10)
to 73 (10»
beg in at
log ical
block
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.
392

FILE I/O

VOLUME

~~~--f-INDEX FILE

"'-

"" "-

"'" ".........

I I
FILE

VBN

"'-

FILE

HDR

6 /

/
/

1HDR
FILE 1FILE I· · · ~
HDR
~
7

\
\

FILE HEADER
FILE 3
~~~-RETRIEVAL POINTERS

SIZE

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 ~apping

393

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:
DRl:[5,6]SAMPLE.TXTil.
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
(UFO)
[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 header.
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,O]
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 gggmrnm.DIR,
where [ggg ,mmm] is the user identification code
(UIC) of the owner.
Each UFD contains a list of the files in that
directory.

394

FILE I/O

MFD
[0,0]

- - - - _-,-----_ _-"--1_ _------, ____ _

I
UFD
[303,5]

UFD
[200,1]

-----1"--------'-----.1-----1

HIYA.MAC;1

------1

~--------~-----------'I-----

IZZY.TXT;1

FLY.TXT;1

OZY.TXT;1

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, DRl:
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
directory 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 th is so und s 1 i ke a 10 t 0 f wo r k, it is.
La te r ,
yo u wi 11
learn about a way to go directly to the file header using the file
ID if it is opened a second time during a task's execution.

395

FILE I/O

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

MFD
HEADER
RETRIEVAL
POINTERS

005005.DIR
005006.DIR

•

FILE ID
FILE ID

MFD

UFD
HEADER
RETRIEVAL
POINTERS

SAMPLE.TXT;1

FILE ID

UFD

[5,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

396

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 Fil e:

INDEXF. SYS.

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

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 Bloc k Fil e:

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.

397

the

system

manager

FILE I/O

Functions of the ACP
The FIIACP maintains
d ur i ng its use.

the

FILES-II

structure

The most elementary functions performed by
follows.
•

Maintaining the File Header Blocks.

the

volume

ACP

are

This includes:

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

reuse

Maintaining file attributes such as
leng th, etc.

when

file

protection

code,

Maintaining the file retrieval pointers
•

Maintaining directories.

This includes:

Creating directory entries when a
file or
UFD 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 swi tch)
•

Maintaining block allocation.

This includes:

Allocating blocks to files when a file is
ex tended

•

created

Recovering blocks for reuse when a file is deleted
truncated

Controlling and facilitating task access to
incl ud es:

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.

398

allow

virtual

FILE 1/0

Table 9-

shows

the

FllACP

functions

performed

request some 2typical file 1/0 operations.
Table 9-2

EXamples of use of FllACP Functions

399

when

yoU

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 shows 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 Fes 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 FIlACP 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,
Chapter 5 of the IAS/RSX-Il I/O Operations Reference Manual.

USER TASK

[

~EAD~ECORD

POOL
RETRI-EVAL POINTERS~ -

FI LE HEADER

I
I

FILE BODY

FCS OR RMS
EXEC

DRIVER

OIOIO.RVB

BUFFER

I
I

F11ACP

I
I
I
L _________________________

TK-7737

Figure 9-6

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

400

see

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 pe r fo rm the fo llowing funct ions:
•

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
organizations,
record
types) and
described in the following sections.

401

offer a variety of file
access modes.
These are

FILE I/O

MOVE MODE
TASK
_ _ _~(I.N MEMORY)

----1+---4- USER
RECORD
BUFFER

rA~B;;;C~.:-:-.:-.

DISK

MOVE RECORD
TO USER
RECORD BUFFER

....._ _I--INTERNAL
BUFFER

MOVE BLOCK
TO INTERNAL
BUFFER
(I F NECESSARY)

~~~---r-L~

LOCATE MODE
TASK
(IN MEMORY)
~---

DISK

POINTER
/
/
/

POINT
POINTER
TO RECORD

/
MOVE BLOCK
TO INTERNAL
BUFFER
(IF NECESSARY)

i + - - - - f - INTERNAL

I-----.--L._ _--.-.......L.-I

BU F FER

TK-7742

Figure 9-7

Move Mode and Locate Mode

402

FILE I/O

FCS FEATURES
File Organizations
Essentially, all FCS supported files 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.

END OF FILE

,
RECORD RECORD

RECORD
3

RECORD

SEQUENTIAL FILE ORGANIZATION

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.

403

FILE I/O

Examples:
Fixed- Leng th Records (record leng th = 17(10))
000000 061 062 063 064 065 040 040 040 040 040 040 040 040 040 040 040
1
2
3
4
5
000020 040 xxx 061 062 063 040 061 062 063 064 040 040 040 040 040 040
pad 1
2
2
3
4
1
3
000040 040 040 040 xxx 101 1"01 101 101 040 102 102 102 102 040 103 103

pad

000060 040 f04 040 040 040 xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx xxx

pad

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

Sequenced variable-Length Record s
000000 007 000 001 000 061 062 063 064 065
4
1
2
3
5
000020 063 040 061 062 063 064 020 000 003
3
1
2
4
3
000040 102 102 102 040 103 103 040 104 xxx
B

404

xxx 012 000 002 000 061 062
pad
1
2
000 101 101 101 101 040 102
A

xxx xxx xxx xxx xxx xxx xxx

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 compatibility with
RMS variable-with-fixed-control records.

405

FILE I/O

Table 9-3 compares the different FeB record types.

Table 9-3

Comparison of FCS Record Types

406

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.

407

FILE I/O

Table 9-4

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

408

FILE I/O

File Sharing
A task which opens a file may choose
options:
•

one

the

following

Tha t no other accesso r chang e an y data in the f i I e
it has access ("shared" read, "exclusive" write).

wh i Ie

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.

409

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.

410

FILE I/O

L--_.....L.._ _' - _ - - '

...

I~E::::r

FILE

SEQUENTIAL FILE ORGANIZATION

CELL

NO.r~-,---=____~~~=4~~~5~

.. ·I~ECORDI

RELATIVE FILE ORGANIZATION

LEVEL 2
(ROOT)

LEVEL 1

LEVEL 0

INDEXED FILE ORGANIZATION
TK-1748

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 records original location, which
points 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 th e in d ex s t r uc t u res •
I n ad d i t ion, m0 r e ex e cut ion tim e is
required to insert new records, because the index structures must
be updated as well. We are keeping things rather simple in the
discussion
here.
For
additional
information,
see
the
RMS-ll user's Guide.
411

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.
fo r
Table 9-5 describes the various access modes suppo rted
For additional
each
file organization and how they work.
information, see the RMS-ll User's Guide.

412

FILE I/O

Table 9-5

File organization, Record Formats, and Access Modes

413

FILE I/O

File Sharing Features
Fes.
RMS 0 ffers more sophisticated file-sharing options than
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 si ze, each 1 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 records
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.

414

FILE I/O

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

Comparison of Fes and RMS

415

FILE I/O

Table 9-6

Comparison of FCB and RMB (Cont)

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 mater ial, 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
return to this module for further study.

416

mastered

the

material,

FILE CONTROL SERVICES

INTRODUCTION
The File Control Services (FCS) subsystem provides the means
through which most tasks perform file
I/O.
You make calls
directly to the FCS routines.
This module introduces you
services
it offers, and the
services.

to the structure of FCS,
the
ways in which you can use those

OBJECTIVES
1.

To choose file characteristics for a specific application,
then create a file with those characteristics

To write tasks which read or write data using
or block I/O (MACRO onl y)

To identify and implement methods of optimizing file I/O.

record

I/O

RESOURCE
•

IAS/RSX-ll I/O OPERATIONS MANUAL, ,Chapters
(Additional reading - Chapters 4 and 6)

419

and

FILE CONTROL SERVICES

REVIEW OF FILE I/O
Use the following basic steps to perform file I/O.
I•

Ope n th e f i Ie.
•

Ask ACP to connect LUN to file.

•

Specify access rights desired

•

Specify type of access.

(RWED).

Block I/O or record I/O
For record I/O only
Random or sequential access
Move or locate mode
•

If new file, specify file characteristics.
Record type
Record attributes
File initial size and extend size

perform the actual I/O operations.

Close the file.
•

Perform any needed clean-up work.

421

FILE CONTROL SERVICES

INTRODUCTORY EXAMPLE
The purpose
We begin our discussion of FCS with an example.
is to give you a feeling for how to perform the basic steps of
file I/O.
After
that,
we will examine the data structures
involved,
and
the specific steps for setting them up and using
them to perform file I/O.
Example 10-1 creates a
file with variable-length records
using sequential access.
The records are input from TI:
and then
placed in the file.
The following notes are keyed to the example.

o The interface with FCS is through system macros.
o

FCSERR is an error message macro supplied with this
course.
Its source and documentation concerning its use
are in Appendix A.
It is used here
to avoid having to
worry about the details of the code.
The FSRSZ$ macro reserves space in the
user
task for
a
general
FCS data area which is called the file storage
region (FSR).
This macro must be issued in every program
that uses FCS.

file descriptor block (FOB) contains data structures for
o aA file
opened by FCS.
A separate FOB is required for each
file which is open at the same time.
The FDB and
its
related data structures can be filled in at assembly time
or at run time.
In this example, they are set up mostly
at assembly time, which is more run time efficient.
open the new file VARI.ASC.
Notice that the
run-time
macro
references the label of the FOB.
This is necessary
in the case of multiple FOBs, for multiple files opened by
a single program.

Get input record from TI:.
Write (PUT$) the record to the file.
For variable-length
records, specify the record length in bytes.
Branch on any FCS error.

422

FILE CONTROL SERVICES

C»

Get next record.

On the Dump - A file dump is included for each example in
this module which creates a new file.
The dumps were
created using the DMP utility, and are in octal byte
format.
Because this file has variable-length records,
the first word in each record is a byte count for the
record.
See the section on FCS File Organizations in the
File I/O module for additional information on the dump.

On a

~Z,

423

close the file and exit.

FILE CONTROL SERVICES

3
4

.TITLE
.IDENT
.ENABL

CRESE(~

lOll
LC

Enable lower case

File CRESEQ.MAC
6
7
8

9
:LO

CRESEQ creates a file VARI.ASC of variable-Ien~th
records usinS seGuential 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:[l,l]PROGMACS/LIBRARY~dev:[ufdJ
"")CRESEQ
LINK/MAP CRESEQ,LB:[l,lJPROGSUBS/LIBRARY

1. ~)
16
17

.MCALL
.MCALL
.MCALL
.MCALL

O[~9
..:.0

o
e ;~
21

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

'')'')

26
=~7

28
29

30
31
32
33
~54

35
36
:~7

:1EJ
39
4()

_[41.

-[:;
43

46
47

FSRSZS 1
; 1 file for record liD
; Define file descriptor block for VARI.ASC
FDB:
FDBDFS
Allocate the FDB
FDATSA R.VAR,FD.CR
Variable lensth records,
Listins - implied
<CR>,<L.F>
Seauential access and
FDRCSA "BUFF
reeD rd I 10 b~1
default, BUFF is
user record buffer
FDOPSA 1"FNAME
Use LUN 1, file spec
at FNAME
FNAME: NMBl.I(S VAl:': I "ASC
aVARI.ASC·
BUFF:
.BL.KB
80.
User Record Buffer
lOST:
.BLKW
2
1/0 status block
.EVEN
.ENABL LSB
Enable local symbol
block.
; Open file for write, call ERRl if open fails
START: OPENSW #FDB"""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 1/0 error
BLT
ERR21
Branch on 110 error

Example 10-1

Creating a File in MACRO-II

424

(Sheet 1 of 2)

FILE CONTROL SERVICES

fa [;6

852

53
54

EXIT:

MOV
PUTS
BCS
BR

IOST+2,Rl
:fI:FDB, , R:L
ERR3
lOS

CLOSES
EXSTSC

tFDB,ERR4
EXSSUC

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

Close file
with success
status
; Error code - Close f:i.le if necessar~, displa~1 err'or
; messa~e and exit
ERR1:
FCSERR tFDB,(ERROR OPENING FILE)
ERR2D: DIRERR (DIRECTIVE ERROR ON READ)
ERR2I: CMPB
iIE.EOF,IOST
; Is it -z?
BEQ
EXIT
; If eaual, close file
; and exit
IOERR
tIOST,(ERROR ON READ) ; Displa~ error
; messa~e and exit
ERR3:
CLOSES #FDB,ERR4
; Close file
FCSERR tFDB,(ERROR WRITING RECORD)
ERR4:
FCSERR tFDB,(ERROR CLOSING FILE)
.END
START

56
~57

58
59
60
61
62
63
64
65
66
67
68
69

;
;

E~·dt

>RUN CRESEQ
1:1.:1.:1.
~~3~!'

JAZZ Jazz JAZZ Jazz
HcJVf:~

f.)6

~~()I..J

/.i6

t:,'VE.' r
66 1.)1.)

~;;(~en

the sun?

"'Z

D'Jmp of DB1:[305,30:l.JVARI.ASC;27 .- File ID 34772,6,0
Virtual block O,OOOOOl. - Size 512. b~tes

000000
000020
000040
OOO()6()
000100
OOO:L20

004 000 061
003 000 063
172 040 112
166 145 040
040 164 150
066 040 066

Example 10-1

061 061 06:1. 0:1.0 000 062 062 062 062 062 040 06:~ 062
063 063 000 023 000 112 101 .132 132 040 112 14:L 172
101 132 132 040 112 141 172 172 000 033 000 110 141
171 157 165 040 145 166 145 162 040 163 145 145 156
145 040 :1.6:3 :1.65 :1.56 077 000 013 000 066 066 040 066
066 040 066 066 000 000 000 000 000 000 000 000 000

Creating a File in MACRO-II (Sheet 2 of 2)

425

FILE CONTROL SERVICES

BLOCK BUFFER

BLOCK BUFFER
$$FSR1
(BLOCK
BUFFER
POOL)

BLOCK BUFFER

$$FSR2

IMPURE DATA

TK·7734

Figure 10-1

The File Storage Region

426

FILE CONTROL SERVICES

USING FCS
In this course, we cover many of the options supported by
FCS.
However, we cannot cover all of the options in detail.
Therefore,
it is very important that you read the
reading
references mentioned
in the IAS/RSX-ll I/O Operations Reference
Manual for further information.
This is especially important if
you are going to use an option which is not discussed in detail in
this course.
For a general discussion of FCS and
its use,
read
Chapter 1 of that manual.

Preparing to Open a File
The File storage Region (FSR) -- The FSR is an area allocated
in your
task as working storage for FCS operations.
The FSR
consists of two program sections which are always contiguous to
each other.
Figure 10-1 shows the layout of the FSR.
The program
sections and their purposes are as follows.
$$FSRI -- contains space for
block buffers and the block
buffer headers for record I/O operations.
You determine the
size of this area at assembly time with the
FSRSZ$ macro.
Block buffers and headers are allocated from this area when a
file is opened for record I/O operations.
Enough space must
be allocated
for
the greatest need of your task at anyone
time.
$$FSR2 -- contains impure data which is used and maintained by
FCS when performing both record I/O and block I/O operations.
The area is set aside at assembly time.
portions of it are
initialized at task-build time; other portions are maintained
by FCS at run time.
The data flow during record I/O operations for
locate mode
and move mode is shown in Figure 10-2.
Note that blocks of data
are transferred directly between the device and
the FSR block
buffer.
In locate mode, you usually access the data directly in
the FSR block buffer.
In move mode, an additional
transfer
is
made of the specified record between the FSR block buffer and a
user specified buffer.
The data flow during block I/O operations is different, as
show in Figure 10-3.
Blocks of data are transferred directly
between the device and a user specified buffer.
No
FSR block
buffer is needed.

427

FILE CONTROL SERVICES

MOVE MODE
TASK
_ - -__
(IN MEMORY)

rA;-;B;;C:-:.~.~.:----l.---L USE R R ECOR D

DISK

BUFFER
MOVE
RECORD

......_ _"-- FSR BLOCK
BU F FER

~---r--L.:..":'="='-.--.L.....j

LOCATE MODE
TASK
(IN MEMORY)

------

r--- - --- - !+-_ _-I--USER RECORD
a..---------J
BUFFER
..........

DISK

MOVE
BLOCK
(IF NECESSARY)

FSR BLOCK
BUFFER

TK·7729

Figure 10-2

Move Mode Versus Locate Mode for Record I/O

428

FILE CONTROL SERVICES

TASK
(IN MEMORY)

-------

DISK

MOVE
BLOCK
ABC ...

TK-8636

Figure 10-3

Block I/O Operations

Initialization of the FSR
Use the FSRSZ$ macro to establish the size of the FSR at
assembly time.
This macro must be used in any program using FCS,
whether fO,r block I/O or record I/O.
The format of the FSRSZ$
macro is as follows.
FSRSZ$ fbufs,bufsize,psect
fbufs

for block I/O only, specify 0

for record I/O or record and block I/O,
number of buffers needed for record I/O

bufsize - total space needed for block
Defaults to fbuf*5l2(10)
psect

buffers

- return Psect if other than default.

429

(in

maximum
bytes).

FILE CONTROL SERVICES

Examples:
FSRSZ$ 0
using FCS for block I/O only.
data only ($$FSR2).

Allocate FSR space for

impure

FRSRSZ$ 2
using FCS, allocate FSR space for impure data
($$FSR2), and
for
record I/O block buffers ($$FSRl).
Total allocation for
block buffers in $$FSRI is two headers plus
2*512(10)
=
10 2 4 (1 0 ) b yt e s •
FSRSZ$ 3,2048
using FCS, allocate FSR space for impure data
($$FSR2), and
for
record I/O block- buffers ($$FSR1).
Total allocation for
block buffers is three headers plus
2048(10)
bytes.
For
example, two are 512(10) bytes long and the third is 1024(10)
bytes long.
The buffer size usually corresponds to a disk block (512(10»
for disks, or the buffer width for terminals.
If all record I/O
operations use single buffering with the default buffer size of 1
disk block
(512 (10», then fbufs should be the max imum number of
files open at the same time for
record
I/O.
Bufsize can be
defaul ted to that number, times 512 (10) •
If double buffering is used for some record
I/O operations,
or larger block buffers are desired (to reduce the number of I/O
transfers) , speci fy val ues for fbufs and/or bufsi ze.
This allows
for
your maximum need for files open at the same time for record
I/O.
See section 2.6.1 on FSRSZ$
in the
IAS/RSX-ll Operations
Reference Manual for a discussion on how to calculate bufsize.

430

FILE CONTROL SERVICES

The File Descriptor Block (FOB)
Functions of the FOB - The FOB contains information used by FCS in
opening
and processing a file.
One FOB is required for each file
that is open at the same time by your program.
An
FOB may be
reused once the
file
associated with it is closed.
The FOB is
used by:
•

The task, to pass information to FCS

•

FCS, to return information to the task

•

FCS, for internal bookkeeping for the file.

You must allocate space for each FOB and initialize specific
portions, before opening a file.
You may use either assembly-time
or run-time macro calls.
Figure 10-4 shows an FOB and
its
different parts.

FILE DESCRIPTOR BLOCK
FILE ATTRIBUTE
SECTION

RECORD TYPE AND SIZE
FILE TYP,E AND SIZE

BUFFER DESCRIPTORS AND
POINTERS - ACCESS MODE

RECORD OR BLOCK
ACCESS SECTION

FI LE OPEN SECTION

BLOCK BUFFER
SECTION

ASSOCIATED LUN

MULTI-BUFFERING DESCRIPTOR
BUFFER SIZE

FILE NAME
BLOCK SECTION

FILE SPECIFICATION
FI LE ID

FDAT$A

FDRC$A AND
FOR BLOCK FDBK$A

FDOP$A

FDBF$A
POINTERS IN FDOP$A
(BUI L T AT OPEN FROM
DSPT OR NAME BLOCK
PLUS INFO. FROM FILE)
TK-7740

Figure 10-4

The File Descriptor Block

431

FILE CONTROL SERVICES

Allocating Space for FOBs - Use the FDBDF$ macro to allocate space
for one FOB. The format of the call is:
1 abel:

FOB DF$

FOB IN:

FDBDF$

The label is used later to refer to a specific FOB.
Initializing an FOB - You can initialize an FOB either at assembly
time or at run time. Whenever possible, use the assembly-time
macros because they do not need to be executed at run-time.
Therefore, your task will be more run-time efficient. With the
assembly-time macros, use parameters which are valid source
arguments for
.WORD or .BYTE assembler directives. Many values
have symbolic equivalents which can be used instead of the actual
numer ic val ues.
With the run-time macros, use parameters which are valid
source arguments for MOV or MOVB instructions. This is similar to
the convention for the $ form versus the $S form of the executive
directives.
At assembly time, use FCS macros which end with $A;
at run time, use FCS macros which end with $R. The assembly-time
macros must immediately follow the FDBDF$ macro which reserves
space for the FOB. The run-time macros have an additional initial
argument to specify which FOB they refer to.
Run-time initialization macros override any previous FOB
settings.
In addition, you can also override the settings in the
file open operation or in an I/O operation.
As an aid in referencing a given FOB at run time, all
run-time initialization and file-processing macros return the
address in R0.
If no FDB pointer is specified in subsequent
macro calls, it defaults to R0. The other registers are saved
restored by all FCS run-time macros.

FCS
FOB
FCS
and

For additional information on the use of parameters in the
different forms of the FCS macro calls, see section 2.2.1 on
Assembly-Time FOB Initialization Macros, and section 2.2.2.1 on
Run-Time
FOB
Macro-Call
Exceptions
in the IAS/RSX-ll I/O
Operations Reference Manual •
The following sections describe how to use the different
FOB initialization macros to initialize an FOB.

432

FCS

FILE CONTROL SERVICES

Specifying New File Characteristics
Use either the FDAT$A macro, at assembly time, or the
FDAT$R
macro,
at
run
time, to specify new file characteristics.
These
macros are only required where you create a new file.
FCS uses
the established characteristics for existing files.
The format of
the FDAT$A,macro is:
FDAT$A rtyp,ratt,rsiz,cntg,aloc
rtyp -

record type
R.FIX = fixed length
R.VAR = variable length
R.SEQ = sequenced

ratt -

record attributes
carriage control
FD.FTN = FORTRAN type
FD.CR = list type
default = no implied carriage control
spanning of blocks
FD.BLK = spanning blocks not allowed
default = spanning blocks is allowed

rsiz -

record size

cntg -

initial number of blocks for file

aloc -

extend size for file.

Examples:
1.

FDA T$A R. VAR
File will have variable-length
records.
Defaults:
no
implied carriage control, may span block boundaries,
initial size of zero blocks, default extend size, on
disk, generally five blocks.

FDAT$A R. FIX, FD. CR, 64.
File will have fixed-length
records,
list
carriage
control, and 64(10) byte records.
Defaults:
records may
span block boundaries,
initial
size of zero blocks
default extend size.

433

FILE CONTROL SERVICES

FDAT$A R.FIX,RD.FTN!FD.BLK,100.,-15.
File to have fixed-length records, FORTRAN type carriage
control;
records may not span block boundaries;
100(10)
byte records, initial file size of 15(10)
blocks, not
necessarily contiguous.
Default: default extend size.

FDAT$R #FBDl,#R.FIX,#FD.FTN!FD.BLK,#100.,#15.
The same as the previous example, but using the
form.

run-time

Note the difference in the format of the parameters in the $A
(for assembly-time)
and the $R (for run-time) forms.
For the $A
form, the parameters are symbolic or numeric values, all valid
source arguments for .WORD or .BYTE assembler directives.
For the
$R form, on the other hand, the parameters are all valid
source
arguments for MOV or MOVB instructions.
If records are allowed
to span block boundaries,
then a
record at the end of a block, which doesn't fit completely within
the block, is continued in the next block.
If records are not
allowed
to
span block boundaries, a
record which doesn't fit
completely is started at the beginning of the next block.
The
space
remaining
in the current block is unused.
This technique
uses more file space, but permits quicker I/O operations in locate
mode.
Specify one of three possible types of carriage control
in
the
ratt parameter.
FD.FTN indicates that the first data byte of
each record contains a FORTRAN carriage-control character
(e.g.,
space for single space, 0 for double space).
FD.CR indicates that
when the record is written to a line printer or a
terminal, each
record
is to be preceded by an <LF) character and followed by a
<CR) character.
This causes single spacing between records in the
printout.
If you specify neither FD.FTN nor FD.CR, no carriage
control is implied.
Any carriage control characters must be
imbedded
in the data.
List
(.LST)
files are set up with no
implied carriage control.
See section 2.2.1.2 on FDAT$A
in
Operations Reference Manual
for additional
FDAT$A parameters.

434

the
IAS/RSX-ll I/O
information on the

FILE CONTROL SERVICES

Selecting Data Access Methods
First decide whether
to
use block I/O or
record
I/O.
Normally use block
I/O for files with no record structure, and
record I/O for record structured files.
However,
block
I/O is
faster
than record
I/O,
because no blocking or deblocking of
records is required, and transfers are made directly between the
device and the user buffer.
Therefore, if your operation does not
require accessing individual records within the file, e.g., a file
copy operation, use block I/O because it is more efficient.
After you select block I/O or record
I/O,
there are some
other considerations.
For block I/O,
no
FSR block buffer is
needed.
Instead, you must specify a user buffer.
Block I/O
is
asynchronous; set up an event flag or an AST for synchronization.
Also, you must use
the additional
FDBK$A or FDBK$R macro
to
specify the user buffer and the synchronization techniques.
For record I/O, choose either sequential access or random
access mode.
Sequential access can be performed on files with
either
variable-length
records
or
fixed-length
records.
Successive PUTS or GET$ operations in sequential access mode
access successive records in the file.
This is useful if you need
to
process all
records in the file in order.
It is required if
the file has variable-length records.
Random access can be performed
only
in
files' with
fixed-length records.
With random access, your program can access
records randomly by specifying a record number
in each PUTS or
GET$ call.
Random access
is desirable
if you want to access
records in an order which is different from
their order
in the
file.
with sequential access, you can use
FCS routine to save
pointers to an accessed record, and later return to that record.
This offers you a limited ability to access records
in a
random
order, or at least an ability to back up to a certain point in the
file and continue
from
there.
The actual subroutines
are
discussed later in this module under performing I/O.
For record I/O, an FSR block buffer is used for
the actual
I/O transfers.
Blocking and deblocking of records is done
transparently for you by FCS. When FCS blocks a record on output,
it places it into one -or more virtual blocks as needed. When FCS
deblocks a record on input, it takes one or more virtual blocks
and constructs a
logical record.
Because GET$/PUT$ operations,
used for record
I/O,
process records which are contained in
virtual
blocks, not all
I/O operations cause an actual I/O
transfer. Generally, an I/O transfer is needed only when the end
of a block is reached.
435

FILE CONTROL SERVICES

You may choose either move mode or locate mode.
Figure 10-2
compares the two.
In move mode, you always access records in a
user specified buffer, sometimes called a
user record buffer.
Move mode is simple to program, but every PUTS or GET$ operation
requires an extra transfer of the record between the user record
buffer and
the FSR block buffer.
A user record buffer is
required.
In locate mode, as long as complete records are located
totally within an FSR block buffer, you access the record directly
in the FSR block buffer.
FCS returns information in the FDB about
the location and the size of the record.
If records are allowed
to span block boundaries and the last record in a block does span
the block boundary, then" the full record cannot be accessed until
the next virtual block is read (in the case of a GET$ operation),
or until
the current virtual block is written (in the case of a
PUTS operation).
In that special case, the record is accessed
in
a
user specified buffer.
Therefore, a
user record buffer is
required in locate mode only if one or more records actually span
block boundaries.
Table 10-1 summarizes the situations when a
user record buffer is needed.
Record I/O operations are synchronous.
All synchronization
is handled
for
you by FCS.
Control is returned to your program
only after the requested PUTS or GET$ operation is completed.
Table 10-1

When the User Record Buffer Is Needed

436

FILE CONTROL SERVICES

Specifying Data Access Methods
Use the FDRC$A or the FDRC$R macro to
methods.

specify

data

access

FDRC$A racc,urba,urbs
racc -

type of access
methods
FD.RWM = block mode
FD.RAN = record mode, random I/O
default = record mode, sequential I/O

f i 1 e t r un cat ion
FD.INS = PUTS in middle of file does not truncate
file
defaul t = does tr uncate file
move or locate
FD.PLC = locate mode
defaul t = move mode
urba -

user record buffer address (Table 10-1)

urbs - user record buffer si ze (in bytes).
Examples:
1.

FDRC$A ,BUFF,80.
Defaults to record I/O, sequential access in
User record buffer at BUFF, 80.
bytes long.

mode.

FDRC$A FD.RWM
Block I/O.
buffer is specified in
open, READ$, or WRITE$ macros.

move

FDBK$A

macro

FDRC$R #FDB4,#FD.RAN!FD.PLC,#BUFF,#100.
Record I/O, random access in locate mode.
User
record
buffer at BUFF,
100.
bytes long.
This is a run-time
macro which initializes the FDB at FDB4.

437

FILE CONTROL SERVICES

If FD.INS is not specified, a PUTS in the middle of the
file
places
the
log ical
end-of-file
right after that record, which
truncates the file.
If FD.INS is specified, a PUTS in the middle
of the file does not change the logical end-of-file.
See section
2.2.1.3 on FDRC$A in the
IAS/RSX-ll I/O Operations Manual
for
additional information.

Additional Initialization of the FOB for Record I/O
Normally, no further initialization is needed for record I/O.
However,
if you wish to override one or more of the defaults, use
the FDBF$A or the FDBF$R macro.
The defaults are included in the
list of parameters below.
The format of the FDBF$A call is:
FDBF$A efn,ovbs,mbct,mbfg
efn

event flag used internally for synchronization
(default is 32(10))

ovbs -

overr ide FSR block buffer si ze
(in
is standard block size for device)

mbct -

multiple buffer count (default generally 1, or
single buffering)

mbfg -

multiple buffering type (only for multiple buffering)

bytes)

(default

FD.RAH = read ahead operations
FD.WRB = write behind operations
(default - FD.RAH if file opened for read only,
FD.WRB if file opened for a write operation)
Examples:
1.

FDB F$A

, ,2

Use double buffering.
Defaults:
event flag 32(10),
FSR
block buffer size standard
for
device (e.g., 512(10)
bytes for disk).
Multiple buffering type - read ahead if
file
is opened
for
read only,
write behind if it is
opened for a write operation.
2.

FDBF$A

12.,2048.

Use event flag 12(10) and an FSR block buffer size of
2048(10)
bytes.
This
is the standard
size for ANSI
magtape.
It can also be used for disks to cut down on
the number of I/O transfers.
Default:
single buffering.

438

FILE CONTROL SERVICES

In the second example, you must reserve enough space
in the
FSR using
the FSRZ$ macro.
See section 2.2.1.6 on FDBF$A in the
IAS/RSX-11 I/O Operations Reference Manual
for
further
information.

Additional Initialization for Block I/O
For block I/O, you only specify the access method
in the
FDRC$A or FDRC$R macro.
You must use the FDBK$A or FDBK$R macro
to set up the user buffer and your synchronization methods.
The
format of the FDBK$A macro is as follows.
FDBK$A bkda ,bkds ,bkvb ,bkef ,bkst ,bkdn
bkda

user buffer address

bkds

user buffer size (in bytes)

bkvb

address of two-word virtual block number

bkef

event flag for synchronization (default =
32(10))

bkst

I/O status block address (must be specified
for FCS to return I/O status)

bkdn

AST service routine address
NOTE
Bkvb must be specified after
the file
is
opened
us i ng
the $R form, or in a READ$ or
WRITE$ call.

Example:
FDBK$A MYBUF,1024.,,20.,IOST
User buffer at MYBUF, size is 1024(10) bytes.
Use event flag
20(10), the I/O status block is at lOST.
No AST routine.
Bkvb is the address of a two-word data block containing
the
first virtual
block number for a block I/O operation.
This data
block is copied into the FDB and then used to locate the starting
block for the I/O operation.

439

FILE CONTROL SERVICES

However, the virtual
block number
in the
FDB
is always
initialized
to
'I' when a file is opened.
Therefore, this
parameter must be specified after the file is opened if you wish
to
start
I/O operations with a block other than virtual block 1.
Do this using either a FDBK$R, a READ$, or a WRITE$ call.
The parameter should be left null if you use the $A form.
It
is present in the $A form only for compatibility with the $R form.
Bkst is the address of an I/O status block.
Unlike
record
I/O,
where
FCS sets up its own internal I/O status block, block
I/O requires that you specify an IOSB in order to get
I/O status
reports.
FCS issues QIOS for you.
With record I/O, FCS reports
both directive errors and I/O errors automatically.
With block
I/O,
I/O errors are reported only if you specify an IOSB address
in a FDRK$A or FDBK$R call.

Initializing the File-Open Section of the FOB
You must also initialize the file-open
section of the
FDB
before opening a file.
It contains information about the file to
be opened.
You must set up data structures so that FCS can build
a
file specification for the file.
In addition, you must specify
the LUN to be ass ig ned to the fi Ie and the' ki nd of access
rights
yo u nee d ( rea d, wr i t e, ex tend 0 r del e t e).
Yo u can do all 0 f t his
with an assembly or run-time macro, or in the actual open macro
call.
Setting Up the File Specification in the FDB -- At run
time,
FCS
constructs a standard file specification in the filename block in
the FDB using the following, in order:
1.
2.
3.

The dataset descriptor
The default filename block
Other defaults of the task or system

FCS first uses any information which is set up in the dataset
descriptor.
Any non-null data
is translated
from ASCII
to
Radix-50 format, and stored in the appropriate offsets
in the
filename
block.
If any pieces of the file specification are not
specified in the dataset descriptor, FCS next checks the default
filename
block for any of the missing pieces.
Any missing pieces
which are found there are filled in next.

440

FILE CONTROL SERVICES

If the device or the UFD is still not filled in, normal
system defaults are used. The device defaults to the current LUN
assignment of the LUN to be used to access the file.
The UFD
defaults to the default UIC of the task, which is typically the
default UIC of the user who runs the task.
If the file name or
the file type are still not filled in, a file open failure occurs.
If only a dataset descriptor or a default filename block is
specified, and not both, the missing structure is skipped.
Typically, the dataset descriptor is used for building file
specifications at run time. Several routines (get command line
(GCML), command string interpreter (CSI), etc.) are available for
prompting for input, getting a command line, and then filling in a
dataset descriptor. Typically, the default filename block is used
to default any fields not specified in the dataset descriptor, or
to completely set up a file specification at assembly time.
However, one or both structures may be set up at assembly time, if
desired.
If you want to have FCS perform I/O to a terminal, just build
a file spec with the device TTnn: or TI:. If the specified
device is a terminal, FCS just issues QIOs to the terminal.
The
advantage of this technique over issuing QIOs yourself is that the
same I/O routines work correctly with file-oriented devices and
terminals.
You do not have to rewrite the I/O code to change
between device types. The system utility PIP uses FCS calls for
all of its I/O operations.

Setting Up the Dataset Descriptor
The dataset descriptor is a six-word data area in your
program containing the sizes and the addresses of the ASCII data
strings that together make up a file specification. The format of
the data area and the ASCII strings is:
label:

.WORD
.WORD
.WORD

Idev,adrdev
1 ufd ,ad r ufd
Inam,adrnam

adrdev:
Idev
adrufd:
lufd
adrnam
Inam

.ASCII
/dev/
=.-adrdev
• ASCI I
/ufd/
=. -adr ufd
.ASCII
/full name/
=.-adrnam

441

FILE CONTROL SERVICES

Example for file DBl:[202,1]SAMPLE.MAC:
DSPT:
DEV:
LDEV
UFD
LUFD
NAM:
LNAM

.WORD LDEV, DEV
.WORD LUFD, UFD
.WORD LNAIV1, NAM
.ASCII /DBI :/
=.-DEV
._ASCII /[202,1]/
=.-UFD
.ASCII/SAMPLE.MAC/
=.-LNAM

This example sets up the dataset descriptor and all of its
file specification pieces at assembly 'time.
This can also be done
at
run
time.
As shown above,
FCS builds the
file
spec
DBl:[202,1]SAMPLE.MAC.
If no default filename block is specified,
the version number takes the normal
system default,
the latest
version for
an existing file, and the latest version, plus one,
for a new file.
See section 2.4.1 on the Dataset Descriptor of
the
IAS/RSX-ll I/O Operations Reference Manual
for
additional
information.

Setting Up the Default Filename Block
The default filename block is an area within your program
containing
the various elements of a file specification.
Use the
NMBLK$ macro call to both reserve space for
this area, and
to
initialize it at assembly time.
The format of the NMBLK$ call is:
label:

NMBLK$ fnam,ftyp,fver,dvnm,unit

Example for file DBl:SAMPLE.MAC:
NMBLK$ SAMPLE,MAC, DB ~l
Notice that you divide the file specification into pieces in
the macro call.
Also. note that you cannot specify a UFD in the
default filename block.
It can be specified
using a dataset
descriptor.
otherwisei it is usually taken from the default UIC
of the task.
See section 2.4.2 (on Default Filename Block NMBLK$ Macro
Call)
for
additional
information on the default filename block.
It also explains how to manually define or override data
in the
default filename block.

442

FILE CONTROL SERVICES

Initializing the File-Open Section Prior to Opening the File
Use the FDOP$A or the FDOP$R macro call.
FDOP$A call is as follows.

The format

the

FDOP$A lun,dspt,dfnb,facc,actl
lun

- LUN for I/O requests

dspt - pointer to dataset descriptor
dfnb - pointer to default name block
facc - type of file access

(Table 10-2)

actl - access control
The type of file access indicates the kind of activity that
you will perform on the file.
Table 10-2 lists these types.
Note
that you do not specify read, write, extend, or delete;
but
instead write,
read, append, modify, or update.
Each implies a
request for a particular set of access rights.
The meanings of
the types are:
write

- Write

read

- Read an existing file.

append - Append

(create) a new file.

(add) data to the end of an existing file.

modify - Modify an existing file without changing its length.
update - Update an existing file, extending its length if
necessary.
In all cases, the file can also be read.

443

FILE CONTROL SERVICES

The actl parameter is used to override
certain FDB control information, namely:

the

defaults
on

for

•

Initial magnetic tape position - default depends
operation.

•

is not
Locking of a disk file opened
for write
if it
properly closed, e.g~, if the task is aborted.
Default is
that the file is locked.

•

The number of retrieval pointers in pool for a
window.
Default is volume default.

•

Enable or disable block locking.
locking.

disk

file

Default is disable block

See section 2.2.1.5 on FDOP$A
in
the
IAS/RSX-ll I/O
Operation Reference Manual for an explanation of the defaults, and
the arguments to override them.
This section also
covers
additional information on the FDOP$A and the FDOP$R macros.
If desired, you can specify all of the
FDOP$A or FDOP$R
parameters,
except actl,
in the open macro call instead.
The
following examples show the
use of the
FDOP$A call, dataset
descriptors, and default filename blocks.

444

FILE CONTROL SERVICES

Table 10-2

Types of Access

445

FILE CONTROL SERVICES

Examples:

1.
FDOP$A

DFNB:

NM B LK $

1, , DFNB

MYF I LE , DA T , , DB , 0

Use LUN 1, build the file spec in the FDB with the default
filename block
(since there is no dataset descr iptor).
The
file spec will be DB0:MYFILE.DAT.
The UFD will be taken from
the default UIC of the task;
the version number takes the
normal default.

2.
FDOP$A

2, DS PT

.WORD'
0,0
.WORD
LUFD,ADRUFD
.WORD
LNAM,ADRNAM
ADRUFD: .ASCII /[15,12]/
LUFD
=. -ADRUFD
ADRNAM: .ASCII /MYFILE.FFF;3/
LNAM
=.-ADRNAM
DSPT:

Use LUN 2, build the file spec first with the dataset
descriptor,
then go to task and system defaults (since there
is no default filename block).
The File spec will be
[lS,12]MYFILE.FFF;3.
The device will be defaulted to the
currentLUN assignment and to SY:
if not currently assigned.
3.

FDOP$A

DFNB 1:
DSPT 1:
DEV:
LDEV
DNAM:
LNAM

1,DSPT1,DFNB1,FO.WRT

NMBLK$ ANY,FIL
.WORD
LDEV,DEV
.WORD
0,0
.WORD
LNAM,'NAM
.ASCII /DK2:/
=.-DEV
.ASCII /MINE/
=.-NAM

446

FILE CONTROL SERVICES

Use LUN 1; open the file for
write
(create a new file).
Build the
file spec first from the dataset descriptor, then
fill in any missing information from
the default filename
block.
The
resulting
file spec will be DK2:MINE.FIL.
The
UFD and version number
take normal
system defaults.
The
filename
is MINE because the dataset descriptor is used
first.
Since the name
is then filled
in,
the default
filename block is not checked for a name.
Examples of Setting up an FDB
The following examples show the complete process of setting
up and
initializing FDBs at assembly time before opening a file.
Two examples are included for creating a new file,
plus two
for
accessing
an
existing
file.
The line comments offer an
explanation of the examples.
Creating a New File:
1.

FDBl:

DFNB:

FSRSZ$

; 1 file will be open for
; record I/O

FDBDF$
FDAT$A

R.VAR,RD.CR

FDRC$A

,BUFF,80.

FDOP $A

2, , DFNB

NMBLK$

VARIABLE,ASC

; variable length records,
"list" carriage control
URB at BUFF, length 80.
bytes. Defaults: sequential
access, move mode
Use LUN 2, file spec from
Default Name Block
File Spec VARIABLE.ASC

447

FILE CONTROL SERVICES

FSRSZ$

FDBl:

FDBDF$
FDAT$A

R.FIX,FD.FTN,80,
;
;

DSPT:
NAM:
LNAM

FDRC$A

RD.RAN,BUFF,80.

FDOP$A

1 , DS PT , , F0 • WR T

.WORD
0,0
.WORD
0,0
.WORD
LNAM, NAM
.ASCII . / MIN E • F I L ; 2/
=.-NAM

;
;
;

;
;

Fixed length records,
FORTRAN carriage control,
80. byte records
Random access, URB at BUFF,
length is 80. bytes
Use LUN 1, build file spec
from dataset descriptor,
open a new file for write
Use default device
Use default UFD
pointer to file spec
File name
Leng th of file name

Accessing an Existing File:
1•

FSRSZ$

FDBl:

FDBDF$
FDRC$A

,URB,25.

FDOP$A

3, , DFNB

; UR Bat UR B, 1 eng th = 25.
bytes. Defaults: sequential
; access, move mode
Use LUN 3, build file spec
; f rom De fa ul t Name Bloc k

448

FILE CONTROL SERVICES

2.
FSRSZ$

FDBl:

; Only block I/O

FDBDF$
FDRC$A
FDBK$A

FD.RWM
BUFF,512.

FDOP$A

2"DFNB

; Block I/O, no URB needed
; For block I/O - sets up
; buffer at BUFF, length =
; 512. bytes
; Use LUN 2, build file spec
; from Default Name Block

LEARNING ACTIVITY 10-1
The example below shows two FDBs.
The second
FDB is filled
in to display a file at a
terminal.
Fill in the first FDB for
a
file
YOURS.MAC, with variable length records which
will be read and displayed.
Use sequential
access in locate mode.
FSRSZ$

; 2 "Files" open for record I/O

FDBI:
FDBO:

FDBDF$
FDAT$A

R.VAR,RD.CR

FDRC$A

,BUFF,80.

;

To be filled in by the student

;
;
;

Variable length records,
implied carriage return,
line feed
Sequential I/O, move mode,
URB at BUFF, length = 80.
bytes
Use LUN 2, override LUN
assignment. Build file spec
using dataset descriptor
pointers to ASCII data

;

Device is TI:

;
;

FDOP$A
DSPTO:
DEV:
LDEV

.WORD
.WORD
.WORD
.ASCII
=.-DEV

2,DSPTO
LDEV,DEV
0,0
0,0
/TI :/

449

FILE CONTROL SERVICES

Opening a File
Whether or not you set the
file access parameter with an
FDOP$A or
FDOP$R macro call, you can use the general OPENS macro
call to open the file.
If the access parameter
is not already
specified, specify it in the
OPENS call.
You can also use a
number of other open macro calls, which have a
single letter
suffix
to specify the
file access.
See Table 10-2 for the
suffixes and their meanings.
with file open macros,
you can
choose:
•

Whether shared access is allowed

•

Whether a file is permanent
closed)

•

Which FCS object modules are used to open the file.

temporary

(deleted

when

The following list shows all of the possible open macros.
OPENS

fdb,facc,lun,dspt,dfnb,racc,urba,urbs,err
Gene ral fo rm
File access specified in facc or previously using
FDOP$A or FDOP$R

OPEN$x*

fdb,lun,dspt,racc,urba,urbs,err
used for most applications
Requests exclusive write access, shared read access

OPNS$x

fdb,lun,dspt,racc,urba,urbs,err
Allows shared access

OPNT$D

fdb,lun,dspt,racc,urba,urbs,err
Opens temporary file, deletes when closed

OFID$x

fdb,lun,dspt,racc,urba,urbs,err
Opens file by file ID

OFNB$x

fdb,lun,dspt,racc,urba,urbs,err
specifies file by file name block.

* The "x" in the macro name represents one of the suffixes
in Table 10-2.

450

listed

FILE CONTROL SERVICES

Examples:
OPENS

#FDBI,#FO.WRT""",ERRI

open the file using the FDB at FDBI for write access
(create
a
new file).
Call ERRI on an error. All other information
is already in the FDB.
OPEN$W

# F DB 1 , , , , , , ERR 1

The same as the last example, only using the
the call.
OPNT$D

form

#FDB3"", ,ERR2

Open a new file as a temporary file using the
Call ERR2 on an error.
OPNS$U

other

FDB

FDB3.

R0,#3"",ERR5

Open the file for update using the FDB whose address
is in
R0.
Allow shared access.
Use LUN 3.
Call ERR3 on an error.
OPENS

R0,#FO.UPD!FA.SHR,#3"""ERR5

The same as the last example, using theOPEN$
call.

form

the

OPENS
Open the
file
using
the FDB pointed to by R0.
All
information is already in the FDB.
The user should check the
carry flag for an error.
There is no difference in functionality between the
OPENS
macro with the facc argument filled in, and the OPEN$x, OPNS$x, or
OPNT$D forms.
Use the form which is most convenient.
OFNB$x uses information already in the filename block of the
FDB to open the file.
When this occurs, Fes does not build a file
spec prior to the open call.
This is more efficient if the
filename block is still
intact, or has been restored after a
previous open and close of the file.
However,
the OFNB$X call
causes the Task Builder to include different object modules in
your task, thus increasing your task's size.
These will be
additional modules unless OFNB$x is already used in your program.
The same run-time savings can be achieved if you first fill in the
filename block and then use an OPENS, OPEN$x, or OPNS$x call, with
no additional object modules added.

451

FILE CONTROL SERVICES

OPFNB$x is useful only in overlay situations, or when OFNB$X
is already included.
Note that the Get Command Line routine
(GCML) uses OFNB$X.
As shown in the last module, accessing a file-by-file
specification involves a minimum of six disk reads (see Figure
9-5). If you know the file ID of ' a file, opening the file-by-file
ID reduces the number of file accesses to two. This is possible
if you reopen a file for a second time or use other Fes routines
to obtain the file ID. This is because the file ID allows direct
access to the file header of the file~
Any time the file ID field in the FDB is filled in, any open
macro call automatically opens the file-by-file ID. .The OFID$x
call performs the same function, but like the OFNB$x call, it
causes the Task Builder to include different object modules in
your task, thus increasing its size. Therefore, fill in the file
ID and use the regular open macros to open a file-by-file ID.
only use the OFID$x call in an overlay situation, or if OFID$x has
already been included in your task.

452

FILE CONTROL SERVICES

ERROR CHECKING
If an error condition is detected during any of the file
processing operations,
the FCS routines set the carry bit in the
processo r sta tus word (PSW) , and return the error cod e and
the
type of error to FDB offset locations F.ERR and F.ERR+l.
The run-time FDB initialization macros are an exception to
this convention.
They do not return any error indications because
they involve only
moves
into
FDB
locations.
The
FCS
file-processing routines issue appropriate QIOs for you.
As with regular QIOs you issue yourself, directive errors or
I/O errors can occur.
For record I/O, FCS returns the error codes
to the offset F.ERR of the FDB for you so that you don't have to
check the
I/O status block and the directive status word (DSW)
directly yourself.
The error codes are always
returned
as byte
values.
Since some of the error code values for directive and I/O
errors overlap, another byte, offset location F.ERR+I in the
FDB,
contains an indicator, whether the error was a directive or an I/O
error.
A val ue of ''''
in F. ERR+I
ind icates an
I/O error, a
negative value indicates a directive error.
Therefore, to check for errors, check the carry bit on return
from
each file-processing FCS macro call.
If there is an error,
use a TSTB to check offset location F.ERR+I to distinguish whether
it
is an I/O error or a directive error.
Then, check and display
the error code value.
The following
section of code shows a
technique for doing this.

453

FILE CONTROL SERVICES

Example of Error Checking and Processing
BUFF:
ARG:
EDIR:
EIO:

.BLKB
.BLKW
• ASCIZ
• ASCIZ
.EVEN

80
; output buffer
1
; Argument block for $EDMSG
/FCS DIRECTIVE ERROR • ERROR CODE = %D./
?FCC I/O ERROR • ERROR CODE = %D.?

OPEN$W
BCS

#FDB
ERRI

Open file
Branch on FCS error

; Er ror Processing
TSTB
F.ERR+l(R0)
ERRl:

10:
FNSET:

Directive error or I/O
error?
Branch on I/O error
BEQ
10
MOV
#EDIR,Rl
Addr of directive error text
string for $EDMSG
BR
FINSET
Branch to common code
MOV
Addr of I/O error text string
#EIO,Rl
for $EDMSG signs
Sign extend FCS error
MOVB
F.ERR(R0),R0
code and place
MOV
R0,ARG
in arg block
MOV
#ARG,R2
Output
MOV
#BUFF,R0
buffer
CALL
Edit error message
$EDMSG
QIOW$S #IO.WVB,#5,#1",,<#BUFF,Rl,#40> ; Display message
BCS
ERRQIO
; Branch on directive error
EXIT$S
; Exit
;
;
;
;
;
;
;
;
;
;
;
;
;

ERRQIO:
; Directive error code

using the READ$ and WRITE$ macros, directive errors
returned normally by FCS.
Unlike record I/O, with block I/O
does not set up an internal IOSB for you.
Therefore, you will
get I/O success or failure indications if you do not set up
specify an IOSB.

454

are
FCS
not
and

FILE CONTROL SERVICES

The error code is sign extended because $EDMSG works only on
word values,
not on byte values.
The error codes and their
meanings are
listed
in Appendix
I
of
the
IAS/RSX-II I/O
Operations Reference Manual.
They are also in the RSX-IIM Mini
Reference. Just the directive error codes are in Appendix
B of
the
Executive Reference Manual, and just the I/O error codes are
in Appendix B of the RSX-IIM/M-PLUS I/O Driver's Reference Manual.
You can also specify the address of your own error-handling
routine,
and
specify it as the last macro call parameter.
A JSR
PC instruction to the specified user routine is generated.
This
takes
the
place
of the
BCS,
and causes a call
to
the
error-handling subroutine in the case of an FCS error.
Note
that
it
is a JSR PC which places the return address on the stack.
You
must clear off the stack for a nonfatal error if you do not use a
return at the end of the error routine.

455

FILE CONTROL SERVICES

PERFORMING RECORD I/O
Different Forms of PUTS and GETS
Th~

•

three different forms of the PUTS and GET$ macros are:
GET$ and PUTS
used for sequential access
Can also be used for random access if either:
Records are actually accessed in sequence
Program manually changes record
the FDB

•

number

field

GET$S and PUT$S
Used for sequential access only
Takes less space than GET$ and PUTS
Used only to optimize space in an overlaid task

•

GET$R and PUT$R
Used for random access only.

The formats of the macro calls are:
GET$

fdb,urba,urbs,err

GET$S

fdb,urba,urbs,err

GET$R

fdb,urba,urbs,lrcnm,hrcnm,err
urba and urbs override any previous URB setups
lrcnm and hrcnm - the low word and high word of
the record number (random I/O only)

PUTS

fdb,nrba,~rbs,err

PUT$S

fdb,nrba,nrbs,err

PUT$R

fdb,nrba,nrbs,lrcnm,hrcnm,err
nrba and nrbs override the previous settings
for the next record buffer (NRB)

456

FILE CONTROL SERVICES

Examples:
PUTS iFDBI",ERR
Write the record pointed to by the next record buffer pointer
into the file at the current location.
Use the FOB at FDBI.
GET$R ,iMYBUF,i64.,i93.
Read record 93(10) into the buffer MYBUF.
is 64(10).
R0 contains the FOB address.

The buffer

length

Sequential Access
For sequential access, use PUTS and GET$, or PUT$S and GET$S.
FCS uses internal pointers to identify the record to be operated
on next.
The initial pointer location is at the beginning of the
file
unless the file
is opened for Append.
In that case, the
original pointer location is at the end of the file.
Each PUTS or
GET$ operation sets the pointers to the record after the record
just accessed.
This means that a series of PUT$s or a series of
GET$s work on successive reCords.
To update a record in place, you cannot use a GET$,
then
update the record, and then use a PUTS. With that seqeunce, the
GET$ updates the record after the one you read.
Instead, use two
special
file control routines, .MARK and .POINT, which allow you
to save and reset the internal pointers.
Use a .MARK before you
do
the GET$, and save the returned pointers to the record.
Then
do a GET$ and update the record.
Use a
.POINT to reset the
internal
pointers.
Finally,
issue a PUTS to update the record.
See sections 4.10.1 on
.POINT, and 4.10.3 on
.MARK,
in the
IAS/RSX-II I/O Operations Reference Manual
for details on how to
use these routines.
After all GET$ operations, the next record buffer
(NRB)
descriptors identify the address and length of the record just
read.
The address is located at offset F.NRBD+2 in the FOB, and
the length is at offset F.NRBD.
For all PUTS operations, the NRB descriptors identify the
'record to be written.
Depending on whether you use move or locate
mode, as described in the following paragraphs, you mayor may not
need to use the NRB descriptors.

457

FILE CONTROL SERVICES

In move mode (Figure 10-2), GET$ operations always move the
record read to the user specified record buffer. Therefore, in
general, specify the URB address and size once
(in a
FDRC$A,
FDRC$R, or a file open call).
Once these are set up, do not
specify them again unless you want to use a different buffer.
After each GET$, access the record directly in the URB, which has
a known address.
If you specify a different URB in a GET$ call,
that becomes the URB for later GET$ calls, unless another URB is
specified.
PUTS operations in move mode (Figure 10-2) assume that the
record has been built at the location set up in the NRB
descriptor.
This defaults to the URB.
Therefore, the easiest
method is to specify the URB once, and then build all records in
the URB.
Then issue PUT$s without specifying an NRB.
If you want to build your records in a different buffer, you
must specify an NRB in the first PUTS call. After that, for
successive PUT$s, build all records in the NRB so that you won't
have to respecify an NRB.
If however, you mix GET$s and PUT$s,
you must specify your NRB in each PUTS call, because each GET$
call updates the NRB descriptors to point to the record just read
(specifically the NRB pointer points to the URB).
In locate mode (Figure 10-2), you generally access records
directly in the FSR block buffer. The only time a user record is
needed is if a record spans block boundaries.
Set up a
URB only
if this is a possibility.
For GET$ operations, the NRB descriptors identify the record
just
read.
Access the record at the NRB address
(offset
F.NRBD+2). This pointer points directly into the FSR block buffer
if the record does not span block buffer boundaries.
For records which span block buffer boundaries, FCS moves the
record to the URB and the NRB pointer points to the URB instead of
a location within the FSR block buffer. Do not specify a new URB
unless you want to use a different URB for records that span block
boundaries.
For PUTS operations in locate mode (Figure 10-2), build the
record at the NRB address.
This assumes that the NRB descriptors
have already been updated to point to the record to be built,
either by the file open macro, or the previous PUTS or GET$.
Once
the record is built, use a PUTS to allow FCS to do some internal
bookkeeping
and update its internal pointers for
the next
operation.

458

FILE CONTROL SERVICES

In locate mode, be very careful when you write
to a
file,
because you are working directly in the FSR block buffer.
If you
build a record in the wrong location by mistake, you cannot easily
recover any record which gets overwritten.
In move mode, on the
other hand, since you work in a separate
URB buffer, a mistake
discovered before
issuing a
PUTS does not update the FSR block
buffer.
For both move and locate modes, you can also use the
.POINT
routine
to
return to the beginning of a file, or the .MARK and
.POINT routines to save and later return to a
record previously
accessed.
This allows a very limited form of random access.

Random Access
For random access, use PUTS and GET$ or
PUT$R and GET$R.
PUT$R and GET$R are easier to use because you can specify the
record number in the macro call.
For random operations, on each
PUTS or GET$
call,
the record number field in the FDB (offsets
F.RCNM, high-order word, and F.RCNM+2, low-order word) is used to
calculate the position of the record to be operated on.
When the file
is opened,
the
record number
is always
initialized
to '1', even if the file is opened for Append.
After
each PUTS or GET$ operation, the record number is set to one more
than the last record accessed.
You can override this default by
specifying a record number
in a
PUT$R or GET$R call, or by
manually placing the record number directly into the FDB before a
PUTS or GET$ call.
For move mode, the URB and NRB mechanics are exactly the same
as
for
sequential access.
For locate mode, GET$ operations are
the same as for sequential access.
PUTS operations are very similar.
For
PUTS operations in
locate mode, build the record directly at the NRB address.
After
each PUTS operation, the NRB pointer is updated to point to
the
record after the record written.
Therefore, if you are updating a
record other than the next record, use either a dummy GET$R call
or
the
.POSRC routine to set the NRB pointer to the record to be
built.
See section 4.10.2 on
.POSRC
in
the
IAS/RSX-ll
I/O operation Reference Manual
for details on how to use that
routine.

459

FILE CONTROL SERVICES

For all types of access, as you do PUT$s
transparently extends the file as necessary.

file,

FCS

NOTE
FCS
updates
the
logical
end-of-file
information in the FDB, but not in the file
header. Close the file using the CLOSES
macro to write the end-of-file information
out to the file header.
See the
next
section, on closing the file, for additional
info rmat ion.
See sections 3.9 (on GET$) through 3.14 (on PUTS)
in the
IAS/RSx-ll I/O Operation Reference Manual for additional informatlon on performing record I/O.

Closing the File
Use the CLOSES macro to explicitly close a file, specifying
the address of the FDB. CLOSES performs appropriate cleanup work
which involves I/O transfers to the file.
•

Waiting for I/O in progress to complete (multiple buffered
record I/O onl y)

•

performing any needed
(record I/O only)

FSR

block

buffer

•

Updating the file header (high block, end of
fir s t f r e e b yt e) •

file

block,

write

'the

Since CLOSES performs I/O transfers to the file, always check
for
errors
on
return to ensure that the transfers were
successfully performed. If a CLOSES is not issued before a task
exits, the Executive closes the file.
If the file was opened with
write access (write, modify, append, or update), the Executive
locks the file unless you specify "no lock of files" in the FDOP$A
or FDOP$R call.

460

FILE CONTROL SERVICES

Examples of Record I/O
This section contains several examples which show how to
use
the various
FCS services discussed previously for record I/O.
Also, look back at Example 10-1, our
introductory example.
It
shows how to create a
file with variable-length records using
sequential I/O.
Examples 10-2 and 10-3 show how to create a
file
with fixed-length records using sequential I/O.
Example 10-2 uses
the assembly-time FOB initialization macros, and Example 10-3 uses
the run-time FOB initialization macros.
Examples 10-1 to 10-3 all
use move mode.
Example 10-4 shows how to
read
records from an
existing
file
using locate mode.
Example 10-5 shows how to read
records from an existing file using random access in move mode.
Example 10-2 creates the file FIXED.ASC.
It takes
records
input at TI:
and places them in the file, terminating input and
closing the file when a ~z is typed.
The following
notes are
keyed to Example 10-2.
Symbol for record size.
reco rd si ze •

Allows easy modification

the

The user record buffer (URB).
Input from
TI:
is read
into this buffer and then written to the file using PUT$s.
Output buffer, argument block,
and
format strings for
generating error messages using $EDMSG.
This is for both
QIO errors and FCS errors.

o
o

Allocate FSR space; one FSR block buffer for record
The default size is 512(10) bytes.

I/O.

Assembly-time initialization of FDB.

Open file for write.
All FOB parameters are already set.
o The
extra
ERR1 argument causes a call to the subroutine
ERR1 in the case of an open error.

Fill the URB with blanks before each read to avoid garbage
from
a
previous
read,
because you will be reusing the
buffer.
Issue read.
Check for directive and I/O errors.
Display
an error message and exit on either type of error using
common code at SHOERR, except for a
~Z.
In that case,
branch to a common exit routine which closes the file and
exits.

461

FILE CONTROL SERVICES

Use PUTS to write the record to the file.
FCS takes
the
record at NRB (in th i s case the same as URB by defaul t) ,
writes it to the file and updates
its
internal
pointers
for
the next PUTS.
Call the subroutine ERR2 in the case
of an error.

Branch back, clear the URB and read the next input.

After a AZ, close the file, check for
errors and exit.
Use BCS here instead of an additional CLOSES argument, to
show that this technique is also possible.
The two
forms
are similar.
The only difference is that BCS does not
affect the stack, while the additional argument form uses
a JSR PC, which pushes the return address onto the stack.
Error processing, as discussed in the section on Error
Checking.
This code always issues an explicit CLOSE so
that the file is unlocked.
No
error occurs if a
file
which is not yet - opened, is closed.
This code does not
distinguish whether the error was caused by the OPEN$R,
a
PUTS, or the CLOSES call.
Additional code can be added to
tell which call caused the error.

462

FILE CONTROL SERVICES

.TITLE
.IDENT
.ENABL

2
:3
4
5
6
7

CREFXA opens FIXED.ASC for write, inputs records
from TI: and puts them seGuentiall~ to the file.
A ~z terminates input and closes the file.
;-

.MCALL
.MCALL
.MCALL
.MCALL
.NLIST

11
12
13

15
16
17
18
19

20
21
22
23

26
27
28
29

;50
31
32

Enable lower case

File CREFXA.MAC

9
10

CREFXA
lOll

RSIl
lOST:
PRINT:
BUFF:
OBUFF:

:::: 30.

ARG:

.BLKW

EFDQIO:
EFIQIO:
EFCDIR:
EFCSIO:

• ASCIl
.ASCIl
• ASeIl
• ASCIl
.EVEN
.LIST

.BLKW
QIOWS
• BLI\B
.BLKB

FSRSlS
FDBDFS
FDRCSA

EXSTSC,QIOWSC,QIOWS,DIRS ; S~stem macros
FSRSZS,FDBDFS,NMBLKS
S~stem FCB
FDRCSA,FDATSA,FDOPSA
macros
OPENSW,GETS,PUTS,CLOSES ;
BEX
; Suppress ASCII
; Record size (b~tes)
2
; QIO status block
IO.WVB,5,1",,<OBUFF,0,40>
RSIZ
; User record buffer
Output buffer for
80.
; error messa~es
1
Ar~ument block for
SEDMSG
IDIRECTIVE ERROR ON GIO. ERROR CODE - %D.I
1110 ERROR ON QIO. ERROR CODE - %D.1
IFCS DIRECTIVE ERROR. ERROR CODE - %D.I
1FCS 110 ERROR. ERROR CODE - %D.1
Show offsets

BEX
1

FILE:

FDOPSA
NMBLKS

1 file for record 110
File descriptor block
,BUFF,RSIl
User buffer and size,
default is record 110
with seGuential access
R.FIX,FD.CR,RSIZ ; Fixed len~th records,
implied <CR><LF>
1"FILE
use LUN 1
FIXED,ASC
FIXED.ASC

o 4042

START:

OPENSW

:fI:FDB"", ,ERr~1

FDB:

33
34

O 35
36

FDATSA

:37
38

e[:;
46

CLRBUF: MOV
MOV
LOOP:
MOVB
SOB

:fI:RSIl"Rl
:JI:BUFF"R2
:fI:" , (1~2) +
R1,100p

OPEN; if open fails,
CALL EI~Rl
Size of URB
Addr of URB
Blank fill record
so no ~arba~e fill

Example 10-2 Creat ing a Fi Ie 0 f Fixed Leng th Records,
Initializing FDB at Assembly Time (Sheet 1 of 3)

463

FILE CONTROL SERVICES

47
48
49
50
5:L
52

QIOW$C

IO.RVB,5,1"IOST,,<BUFF,RSIZ>~

£{CC
MOV
MOV
BR

IIIROK
tEFItQIO,Rl
t$IISW,R2
SHOERR

TSTB
BGT
CMPB
BEQ
MOVB

lOST
OKlO
f.IE.EOF,IOST
EXIT
IOST,RO

MOV
MOV
MOV
BR

RO,ARG
:JI:ARG,R2
tEFICHO,R1
SHOERR

OKlO:

PUT$
BR

tFIIB, , , ERI~2
CLRBUF

EXIT:

CLOSE$
BeS
EXST$C

ERR:~

5:~

54
55
56
57
58

ItIROK:

~59

60
61
62
63
64
65
66
1)67
68

CD[~~

72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

Read a
line from TI:
Branch on Iii rectiv(-? ok
Set IJP for $EItMSG

Branch to show error
and e~·dt
Check for 1/0 error
Branch if 110 ok
Check for EOF
If-EQ, close and e~dt
liD status is sign
eHtended and plc.=Jced
in argument block
for $EDMSG call
Set UP for $EIIMSG call
Branch to show error
and e~·dt
Write neHt rec.'ord
Get neHt record
Close file
Branch on FCS eT'ror
E~·dt with status of 1

tFDB
EX$SUC

Processing
~ Error
ERR1:
ERR2:
F + ERR+ 1 ( F~O )
ERR:3 :
TSTB
BEQ
MOV
10:

BR
MDV

FINSET: MOVB
MOV
MOV
SHOERR: MOV
CALL
MOV
IIIR$
CLOSE$
EXST$C
.ENIt

Directive error Dr liD
error'
Branch (In liD E~ T' T'O T'
10
tEFCDIR,R1
Set IJP for $EDMSG,
directive error
Brcmch to finish S€~tup
FINSET
Set UP for $EDMSG, 110
tEFCSIO" R:I.
error
F.ERR(RO),RO
FCS error code
RO,ARG
is sign e~·,tended and
placed in arg block
tARG,R2
$EIIMSG argument block
tOBUFF,RO
OUtF'IJt buffeT'
; Fc.1rmat error message
$EDMSG
R1,PRINT+Q.IOPL+2 ; Size of message
Print erT'or message
tPRINT
Close file
tFItB
EHit with status of 2
EX$EI~R
START

Example 10-2 Creating a File of Fixed Length Records,
Initializing FDB at Assembly Time (Sheet 2 of 3)

464

FILE CONTROL SERVICES

F:ur.

f:)e~;;~.; :i.

>r~UN

on:

Cf~EFXA

1:1.1:1.1

2222
3;33;3:~3

Where d:i.d

\:~Ol..l

~.:fC) 'i)

cS6b6 66
r-.Z

- File ID 23746,13,0
V:i.rtual. block 0,,0()()()O1 .- Size 512. b~tes

{Jump of

DB1:[305~301]FIXED.ASC~4

000000
000020
000040
000060
000100
000120
000140
000160
000200
000220
000240
000260
000300

061 061
040 040
062 062
040 040
063 063
040 040
040 040
040 040
144 040
040 040
040 040
040 040
000 000

061 061 061 040 040 040 040 040 040 040 040 040 040 040
040 040 040 040 040 040 040 040 040 040 040 040 062 062
040 040 040 040 040 040 040 040 040 040 040 ()40 040 040
040 040 040 040 040 040 040 040 040 040 063 063 063 063
()40 040 040 040 040 040 040 04() 040 040 040 040 040 040
040 040 040 040 040 040 040 040 064 064 040 040 040 040
040 040 040 040 040 040 040 040 040 040 040 040 040 040
040 040 040 040 040 040 1.27 150 145 162 145 040 144 151
:1.71 157 165 040 147 157 077 040 040 ()40 040 ()40 040 040
040 040 040 040 066 066 066 066 040 066 066 040 040 040
040 040 040 040 040 040 040 040 040 040 040 040 040 040
040 040 000 000 000 000 000 000 000 000 000 000 000 000
000 000 000 000 000 000 000 000 000 000 000 000 000 000

Example 10-2 Creating a File of Fixed Length Records,
Initializing FDB at Assembly Time (Sheet 3 of 3)

465

FILE CONTROL SERVICES

Example 10-3 performs the same function as Example 10-2, but
it uses the run-time FDB initialization macros.
The following
notes are keyed to Example 10-3.

Include the run-time ($R) macros.

assembly time, simply allocate space for
the
FDB and
o Atinitialize
the default filename block.
Issue the run-time FDB initialization macros, specifying
the FDB address in the first call.
The first call returns
the FDB address in R0.
The subsequent calls default the
FDB address to R0.

466

FILE CONTROL SERVICES

.TITLE
.IDENT
.ENABL

2
~~

4
5
6

CI~EFXR

10:1.1

Enable lower case

File CREFXR.MAC
CREFXR opens FIXED.ASC for write, inputs records
from TI: and puts them seGuentiall~ to the file.
A -Z terminates input and closes the file.

7
8

9
l.()

1,1.
:L2
:1.3

This proSram uses the SR macros at run time to
initializ~ the FDB

1,4
15
16

17
:L8

19
2()

21
22
:'~3

24
25
26
27
28
29
3()

.MCALL
.MCALl.
• MCALL.MCALL
.NLIST
30.
• Bl.KW
QIOWS
• BLt<B
.Bl.KB

RSIZ
lOST:
PRINT:
BUFF:
OBUFF:

ARG:

• Bl.KW

EFDQIO:
EFIQIO:
EFCDIR:
EFCSIO:

.ASCIZ
.ASCIZ
.ASCIZ
.ASCIZ
.EVEN
.l.IST

31
32

EXSTSC,QIOWSC,QIDWS,DIRS ; S~stem macros
FSRSZS,FDBDFS,NMBLKS
S~stem FCS
macros
FDRCSR,FDATSR,FDDPSR
OPENSW,GETS,PUTS,CLOSES
BEX
P Suppress ASCII
; Record size (b~tes)
2
; QIO status block
IO.WVB,5,1",,{OBUFF,0,40}
RSIZ
User Reco~d Buffer
SO.
Output buffer for
error 1TI€~ssage~;
1
Argument block for
SEDMSG
IDIRECTIVE ERROR ON QID. ERROR CODE = %D.I
1110 ERROR ON QID. ERROR CODE = %D.1
IFCS DIRECTIVE ERROR. ERROR CODE = %D.I
1FCS 1/0 ERROR. ERROR CODE = %D.1
BEX

Show offsets
1 file for record 1/0
Allocate space for FDB
Default Name Block,
for 'FIXED.ASC"

3:~

FSRSZS
FDBDFS
NMBLKS

FDB:
DFILE:
START:

FDATSR

tFDB,tR.FIX,tFD.CR,tRSIZ ; Fixed length
recordsv implied {CR}
{LF}
User buffer addr and
size, move mode and
seGuential access b~
default
Use LUN 1, Default
Name Block

o [~55

36
37
38
39

40
4:L

42
43
44
45
46

Example 10-3 Creating a File of Fixed Length Records,
Initializing FDB at Run Time (Sheet 1 of 3)

467

FILE CONTROL SERVICES

4B
49

OPEN$W

~5()

CLRBUF: MOV
MOV
LOOP:
MOVB
SOB
QIOW$C

51
52
5~5

54
55
56

Bee
MOV
MOV
BR

~57
~5B

59
60
61
62
63
64
/.)5
66
67

DIROK:

MOV
MOV
MOV
BR

69
70
71
72
73
74
75
76
77
78
79
80
8l
82
8:3
84

OKlO:

PUT$
BR

iFDB,,,,ERR2
Cl.RBUF

Write neNt record
Get neNt recoT'd

EXIT:

Cl.OSE$
BCS
EXST$C

:JI:FDB
ERR3
EX$SUC

Close fi If.:'
Branch on FCS error
EN:J.t with stc~tus of 1

; Error Processing
ERR:I.:
ERR2:
F.ERR+l(RO)
ERR3:
TSTB

85
86
87
8B
89

90
91
92
9:~

94
95

TSTB
BGT
CMPB
BEQ
MOVB

OPEN - if open fails,
CALL ERR1
Size of URB
:fI:RSIZ"Rl
:fI:BUFF,R2
Addr of URB
Blank fill T'ecord
:1:' ,(R2)+
;
Rl,l.OOP
so no garbag~~ fill
10.RVB"5,,1,,,IOST,,(BUFF,,30.) ; Read a
line from TI:
DIROK
Branch on Directive ok
Set UP for $EDMSG
:fI:EFDQ:J:O" 1~1
:J$[JSW,R2
Branch to show error
SHOERI~
and e}·d t
Check for 1/0 error
lOST
Branch if liD c)k
010: 0
:JI::J:E.EOF,IOST
Check for EOF
If EQ, close and e}·dt
EXIT
liD s tatlJ~; is sign
lOST" F.:O
e}·,tended and placed
in argument blc)ck
ROl'ARG
for $EDMSG call
Sc-?t UP for $EDMSG call
:J:ARG"R2
:JEFICHO" 1~1
SHOERR
Branch to show error
and eNit
, , , , , , EI:;:R 1

10:

BEC~

MOV

iEFCDIR,Rl

BR
MOV

FINSET
iEFCSIOl'R1

FINSET: MOVB
MOV
MOV

F.ERR(RO),RO
RO"AI:W
:l:ARG,R2

Directive errc)r CH' liD
e r T'CH'
BT'anch on liD err'or
Set UP fc)r $EDMSG,
directive erT'or
Branch to finish set,l.Jp
Set UP for $EDMSG, IIO
error
FCS error code
is s;isn eHtended and
placed in ars block
frJr ~~E[JMSG

Example 10-3 Creating a File of Fixed Length Records,
Initializing FDB at Run Time (Sheet 2 of 3)

468

FILE CONTROL SERVICES

96
97

SHOERR: MOV
CALL
MOV

(f8
(f9

DII~$

100
101
102

f~un

CLOSE$
EXST$C
+END

:l:OBUFF,RO
$EDMSG
Rl,PRINT+Q.IOPL+2
:fI:PRINT
tFDB
EX$ER~~

Output buffer
Format error mest:;ase
; Size of message
Print error message
Close file
E~dt with statIJ~') of ~~

START

Session

>RUN CREFXR
11111
3;3~S33;3

44
Where did
61.>6[;. 66

~ou

go?

···z

DIJITIP of DB1:[305,301JFIXED.ASC95 -

File ID 24564,6,0
Virtual block 0,000001 _. Size 512. b~tes

000000
000020
000040
000060
000100
OOO:L20
000],40
OOO:L60
000200
000220
000240
000260
000:300

061 061 061 061 040 040 040· 040 040 040 040
040 040 040 040 040 040 040 040 040 040 040
062 040 040 040 040 040 040 040 040 040 040
040 040 040 040 040 040 04() 040 040 040 040
0t')3 063 040 040 040 040 040 040 040 040 040 040
040 040 040 040 040 040 040 040 040 040 064 064
040 040 040 040 040 040 040 040 040 040 040 040
040 040 040 040 ()40 040 040 040 127 150 ],45 162
144 040 171 157 165 040 147 157 077 040 040 040
040 040 040 040 040 040 066 066 066 066 040 066
040 040 040 040 040 040 040 040 040 040 040 040
040 040 040 040 000 000 000 000 000 000 000 000
000 000 000 000 000 000 000 000 000 000 000 000
061
040
062
040

040 040 040 040
040 040 062 062
040 040 040 040
06:~ 063 063 063
040 040 040 040
040 040 040 040
040 040 040 040
145 040 144 151
040 040 040 040
066 040 040 040
040 040 040 040
000 000 000 000
000 000 000 000

Example 10-3 Creating a File of Fixed Length Records,
Initializing FDB at Run Time (Sheet 3 of 3)

469

FILE CONTROL SERVICES

Example 10-4
reads the
first
five
records of the
file
VAR1.ASC
(which
is created using Example 10-1) and displays them
at TI:.
It uses sequential I/O in locate mode.
The
following
notes are keyed to Example 10-4.

FDB allocation and initialization.
Specify locate mode;
default is sequential access.
No FDAT$A or FDAT$R macro
is needed because the file already exists.
No user record
buffer
is needed
because none of the first five records
spans block boundaries.
None
span block
boundaries
because
the maximum
input
record
for
Example 10-1 is
80(10) bytes.
specify a URB if
records can span block
bo un dar i e s •

Set up loop counter to read five records.
GET$ a record.
The FDB pointer is returned
the OPEN$R call.

after

Write the record at TI:.
The pointer to the record is at
o offset
F.NRBD+2 in FDB;
size is at offset F.NRBD in FDB.

No '#' is used because we want
those locations as arguments.

Decrement the counter and
loop
done, close the file and exit •

back

• TITLE I~EADLC
.IDENT /0:1..1
• ENABL. I... C

3
4

5
6
?
8
9
10
1:L
12
1.3
14

[

the
until

contents
done.

of
When

Enable lower case

F i]. ~~ READLC. MAC
This task reads the first 5 records from the file
VARI.ASC and displa~s them at the terminal. It uses

FDB:

.MCALL
.MCALL

OPENSRvGETSvQIOWSSvNMBLKS,FDOPSA
CLOSES,EXITSSvFDBDFS,FDRCSA,FSRSZS

FSF~SZ$

DFNB:

Example 10-4

:I.

FSR block buffer

FDBDFS
FDOPSA

FD. PLC
1" "DFNB

NMBL..K$

VAFU "ASC

FD~~C$A

Ct :L7
18
19
20

use

Locat€." modf:~
L.UN ly default file
name block
File FIXED.ASC

Acces$ing a File in Locate Mode (Sheet 1 of 2)

470

FILE CONTROL SERVICES

22
2~5

24
2~5

26
27

o 2B
8 30

A
V

3~5

3':>
[ 34

:35

36
:3"i'

38
39

40
41
42
43
44

45
46

47
48
49
~:50

DBUFF:
ARG:
EFCDIFn
EFCSIO:

• BU,W
• BU,W
.ASCIZ
.ASCIZ
.EVEN
STf~RT:
OPENSI:;:
BCS
MOV
LOOP:
GETS
BCS
CHOW$S
SOB
CLOSES
BCS
EXIT$S
V Error code
ERI:;:C:
ERHF~ :
ERF~():
TSTB

80.
; Error messa~e buffer
1
; SEDMSG arsument block
/FCS DIRECTIVE ERROR. ERROR CODE = %D./
'FeS I/O ERROR. ERROR CODE = %D.'
Open file for read
Branch on FCS error
L.oop countf.~ T'
Gf.~t r'f.·~co rd
; Branch on error

=lJ:FDB
E~-;;F~O
:JI:~) , F~2

ERRR

IIO.WVB~:JI:5,*1",,<FDB+F.NRBD+2,FDB+F.NRBD,.40>

R2,L.OOP

Decrement loop counter
fi :I,(;:~
Branch on f.·~rT'C)T'
Clo~a~

ERF,C

E~·dt

F.ERR+1(RO)

Directive error or I/O
€~rrc)r?

CLOSE~;

EXITSS
.END

START

MOV
BR
IOERR: MOV
FINSET: MOVB
MOV
MOV
MOV
CALL
QIOW$S

51
5~5

IOEI:;:F,

Branch on I/O error
=lJ:EFCDH-;;IIF;~:I.
Set UP for $EDMSG
FINSET
Branch to displas code
:IJ:EFCS I 0" I:~:I.
Set UP for SEDMSG
F • ERF, ( RO ) , RO
SiSn extend FCS error
RO~ARG
code and place in
IARG,R2
arSument block
=lJ:OBUFF~RO
Output buffer
SEDMSG
~ Format error messaSe
=lJ:IO.WVB,=lJ:5,I:I.",,<#OBUFF,Rl,#40> v Write
messa!-:tco:'
#FDB
Clo~:;e fil€~

BE(~

E~·dt

>RUN READLC
1111
333
JAZZ Jazz JAZZ Jazz

Have sou ever seen the sun?

Example 10-4

Accessing a File in Locate Mode (Sheet 2 of 2)

471

FILE CONTROL SERVICES

Example 10-5 uses random
FIXED.ASC,
which is created
10-3.
It prompts at TI:
for
record at TI:.
The following

access to read records from the file
using either Example 10-2 or Example
a record number and displays that
notes are keyed to Example 10-5.

FCSMC$ is a macro containing .MCALLs for most of the FCS
o macros.
using
it can avoid having to specify all of the
FCS macros in .MCALL statements.
Note that GET$R is
included in FCSMC$, so it is specified separately.

not

Using the $ form of all QIOs. With the exception of the
o QIO
at
PRINT,
all
parameters are set at assembly time.
Therefore, any of the three forms ($, $C, or $8)
can be
used for the QIOs at ECHO, PROMPT, and WARN.
Either the $
or the $S can be used for the QIO setup at PRINT.

o
o
e

The record number is input in ASCII
FDB for file.

(up to two dig its) •

Use random access I/O.

Open file for read.

prompt for and read record number.

On a directive error, use the supplied macro
DIRERR to
o display
an error message and the DSW, and then exit.
for I/O error.
If the error was a
branch to
Z,
o Check
EXIT to close the file and exit.
If any other error
A

occurred, use the supplied macro IOERR to display an error
message and the IOSB, and then exit.
Set up and call .DD2CT to convert the record number from
o ASCII
to double-precision binary.
During setup, make sure
that at least one digit was input.
If none were
input,
prompt again.
Double precision is used only to show how
to take advantage of the full range of record numbers
(up
to 3 1 bit sin two wo r d s) •
Move the low-order 16 bits of the record number to R2, and
o use
GET$R to read the record.
Call the subroutine ERR2 on
any FCS error.
Only the low-order 16 bits are needed,
because we know the record number is less than or equal to
99 (10) •
Display the record and prompt for the next record number.
Always display 30(10)
characters, because the file has
fixed-length records.

472

FILE CONTROL SERVICES,

On FC S err 0 r s, fir s t c he c k for end - 0 f - f i Ie.
If it i s not,
branch to common FCS error code at ERR3.
If the error is
read past end-of- fil e ,
d ispl ay a
warning messag e and
prompt
for
the next
input.
Because
this
routine is
entered with a JSR PC
instruction,
you must clear
the
-return
address
off
the
stack before
using
a
BR
ins t r uc t ion.
Notice that the suppl ied macros DIRERR and IOERR are, used for
QIO errors,
but not for FCS errors.
This is because FCS returns
error status to the FDB.
In fact,
DIRERR would work correctly
because
the
DSW
is returned by the Executive, and FCS moves the
DSW value into the FDB.
IOERR however, does not work correctly
because
FCS sets up
its own internal I/O status block, and its
address is not available to the user
task.
The supplied macro
FCSERR is set up to handle both types of FCS errors.

473

FILE CONTROL SERVICES

.TITLE
.IDENT
.ENABL

F?I~NnOM

lOll

Enable lower case

5
6
7
8

9
:1- ()

11
12
1 ~S
14

RANDOM uses direct access to a file, FIXED.ASC, which
contains fixed length records. This task prompts at
TI: for a record number, and displa~s it at TI:
It exits when a control Z is input
Assemble and task-build instructions:
>MACRO/LIST LB:[l,l]PROGMACS/LIBRARY,dev:CufdJ-

:L ~j

--~}RANDOM

>LINK/MAP RANDOM,LB:[l,lJPROGSUBS/LIBRARY

:1.7

0
0

.MCALL
.MCALL

19
20

21
:~:~

o [~~

.MCALL
FCSMCS
.NLIST
; LOCAL.. DATA
/:;:SIZ
ECHO:
cnows
PRMPT: CHOWS
QIOW$
WAI:;:N:
PRINT: CHOWS

QIOWS,DIRS,EXITSS,GETSR; S~stem macros
FCSMCS
Macro to get most
s~stem FCS macros
DIRERR,IOERR
SUF'P 1 i ed mac ros
Get most FCS macros
BEX
SuP T'(-?f.>S ABC I I
=30.
; Record size
IO.WVB,5vl",,(BUFF,30.,40>
IO.RPR,5,1"IOST"(AREC,2,,MES1,SIZ1,'S}
IO.WVB,5,1",,(MES3,BIZ3,40>
IO.WVB,5,1",,(OUT,0,40>

30
:~H
~'S2

A[3:~
V

~'S4

:35
36
:37
:~8

41
42
43
44

BUFF:
lOST:
AREC:
I:;:EC:
OUT:

.BLKB
• BU,W
.BLKW
.BLKW
• BLKB

RSIZ
:I.
:L 00 •

MES1:

.ASCII
SIZl -MES2:
.ASCIZ
MES:3 :
.ASCII
SIZ3
EFCDIR: .ASCIZ
EFCSIO: .ASCIZ
.EVEN

Example 10-5

User record buffer
IIO status block
Record number in ASCII
Record number in binar~
SEDMSG output buffer

'-)
A.•

-~-

Ir';:ECORD NUMBER'~ I
+ ~~ME~a

IFCS ERROR. ERROR CODE = %D.I
I***PAST END OF FILE***I
.-MEB3
IFCS DIRECTIVE ERROR. CODE = %D.I
'FCB 1/0 ERROR. CODE = %D.'

Accessing a File in Random Mode
(Sheet 1 of 3)

474

FILE CONTROL SERVICES

FSI:;:SZS

START:

OPENSR

IFDBvvvl'vvERRl

lOS:

DIR$

IPRMPT

o[ ~~

FDB:

!51

52
5~5

FILE:

!54

':~'7
,.,

58
r::'0
..17

cd.
62,

6:3

o [~~

66
67
68
69

"70
71
72

1 file opened for
T'ecord I/O
; File descriptor block
FDBDF$
FDI:;:CSA FD.RAN~BUFF~RSIZ ; Random access, URB
addT' and si:;i!('?
Use LUN 1, default
FDOP$A lvvFILE
name block at FILE
Default name
FIXEDl'ASC
FIXED.ASC
.ENABL I...SB

BCC
DIRERR
DIROK: TSTB
BLT
ConveT't ASCII
MOV
BE(~

MOV

73
74

MOV

75
:76

CALI...

O[;~

MOV

~ [79
W
80
81
82
B3

DIR$

o !:J;~
[

B,.)

A
..

87
88
89
90
~~1

(12

Open file foT' read
CALI... ERRl on open
Y (·?rrOT'
Prompt foT' record

GET~~I~

BF~

numb(~r

DIROK
Branch on dir ok
<ERROR ON QIO)
lOST
Check for I/O error
ERR1I
; Branch on error
record number to double-worded decimal
IOST+2,R4
I of characteT's to
Y convert
; If no charactersl'
10$
prompt asain
y Address of ASCII
; cha racte 1'S
; Buffer to store
:Jf:REC,R3
converted number
Convert ASCII to
.DD2CT
; decimal
; Move low order 16 bits
REC+2,R2
:U:FDB, , , R2, ";::RR2 ; Get specified record
Print it on TI:
:JI:ECHO
10~;
Prompt for next input

; F.::!=~I~~OR ROUTINES
ERR1I: CMPB
:U:IE.EOFl' lOST
; ~Z?
BEQ
EXIT
; If wesl' branch to EXIT
IOERR
IIOSTl'<ERROR ON QIO)
; HeT'e for errors on GET$
ERR2:
CMPB
IIE.EOFl'F.ERRCRO); Was the error an EOF?
BNE
ERR1
No, it is another
; error. bT'anch to ERR!
Just displa~ a warnins for end of file
DIR$
IWARN
Displa~ EOF mess ass
TST
CSP)+
Clean off return addr
f rrJIT. s tc1Cv..

9~:~

(14

Prompt for next input

10$

Example 10-5

Accessing a File in Random Mode
(Sheet 2 of 3)

475

FILE CONTROL SERVICES

9~')

ERt:;:3:
E!=~Rl :

F • ERR ( RO ) , r~~5
R~i, 108T
:IH OST" R2
F + ERI:;:+ :1, ( F~O )

CLOSE~~

~:;ign cm e T' rc))"
and move into
arg'Jment blc)ck
I/O c)r dir€~ctive eT' r()T"~
Bra,..,(~h on I/O c:~rT'or
IOEI:;:I:~
Di T'ectiv€,~ c:~rroT' message
:Jl:EFCD I I:;: "R:l
Bl"anch to d:i,spla~ code
DSPERR
:JJ:EFCSIO y 1:;::1.
I/O error me~:;sc~g€:'
Output bu'rf(~~ r
:IHHJT, RO
$EDMSG
v Edit OlJf:"Jt lTJessag€~
Rl"PRINT+Q.IOPL+2 ; Length of er rC)T'
;
message
P T' :i, r'lt error me~~~~cH:je
:JI:PRINT
:IJ:FDB
Close file
EXIT
:JI:FDB y ERR:3
Clo~:;e file

EXIT$S
.END

START

MOVB
MOV
MOV
TSTB
BEQ
MOV
BR
IOEI:;:I:;: :
MOl.,'
DSPEI:;:R: MOV
CALL
MOV

97
9B

99
lOO

101
102
10:3

1()4
10~5

10c!)
107

lOB

DIF~$

lO9
:U,O

CLOSE~~

EXIT~~S

o [1:l1
113

EXIT:

:1,1.2

Run

Bf'~ss:j,()n:

>I:;:UN

F~AND()M

EHtend
c()df.~

E~,dt

I;:ECORD NUMBEF~'l)l
:1,:1.:1. :1. :I.
r':':ECOI:;:n NUMBER'i):3

33:'53:'5:'3
1:~ECc)F~D

NUMBE!=~?9

***PAST END OF FILE***
r~EC()I:~D

NUMBEI:~?5

Where did

~DU

so?

Example 10-5

Accessing a File in Random Mode
(Sheet 3 of 3)

476

FILE CONTROL SERVICES

PERFORMING BLOCK 1/0
READ$ and WRITE$ Calls
The formats of the READ$ and WRITE$ calls are:
READ$
WRITE$

fdb, bkd a ,bkd s,b kvb, bke f ,bks t ,bkdn ,er r
fdb ,bkda ,bkds ,bkvb ,bkef ,bkst ,bkdn ,err

All parameters except fdb and err override any previous FDB
settings.
Always use a user specified buffer, which can be
specified in a FDBK$A, or FDBK$R call, an open call, or in a READ$
or WRITE$ call.
The length of the transfer is controlled by the bkds
parameter.
The starting virtual block number in the FDB is
initially set to 1, unless the file is opened for Append.
FCS
updates the block number after each operation to point to the
block after the last one accessed. To override the default block
number, set up a two-word data block for the virtual block number
and specify the address of the block in a FDBK$R macro call (after
the file is opened), or in a READ$ or WRITE$ macro call.
The following piece of skeletal code shows how to
5, then block 12 (10), and finally block 13 (10) •

use

0,5

; Starting block number

OPEN$R
BCS

#FDB
ERRl

; open file

READ$

# F DB , , , # B LC KN M, , , ERR 2

MOV
READ$

# 12., BLCKNM+2 ; Update bloc k #
#FDB",#BLCKNM",ERR3 ; Read virtual
; block 12 (10)

READ$

#FDB"""ERR4

BLCKNM: .WORD

477

block

Read block 5

; Read next virtual block

FILE CONTROL SERVICES

Unlike record I/O, for block I/O each READ$ or WRITE$
an I/O transfer between the user buffer and the file.

causes

Synchronization and Error Checking
For block I/O, FCS issues asynchronous QIO directives.
You
must p~ovide synchronization and check for both directive and I/O
errors.
Use an event flag or an AST routine for
synchronization.
Check for
errors on return from the READ$ or WRITE$ call (after
the QIO directive is issued).
Also check for I/O errors after the I/O operation completes.
To get
I/O error indications, you must set up and specify an I/O
status block.
Otherwise. no I/O status conditions are
returned,
and success must be assumed.
If you use an AST routine for synchronization, check the IOSB
directly
for
I/O errors.
If you use an event flag
for
synchronization, use a WAIT$ call to wait for the flag to be set,
rather
than a wait for Single Event Flag (WTSE$) directive. with
WAIT$, FCS returns its standard error indications. This means the
carry bit is clear
for
success and set for an I/O error.
In
addition, for errors, the I/O error code. is returned at offset
F.ERR in the FDB.
If you use the wait for Single Event Flag
directive (WTSE$)
instead,
standard FCS error codes are not
returned.
In that case,
you must check the
IOSB directly
yo ur sel f.
Se e sec t ion s 3. 15 ( 0 n REA D$), 3. 16
for
additional
information
WAIT$)
synchronization, and error checking.

( 0 n WR IT E$), an d 3. 1 7
(0 n
about block
I/O calls,

Examples 10-6 and 10-7 show how to use block I/O.
Example
10-6 creates a file BLOCK.ASC using block I/O.
Example 10-7 reads
a virtual block from the file BLOCK.ASC and displays
it at TI:.
The following notes are keyed to Example 10-6.

o noYou FSR
still need an FSRSZ$ statement to set up an FCS,
but
block buffers are needed.
o I/O.
FDB setup.
FDAT$A and FDOP$A are the same as for
record
The
only difference here is that a dataset
descriptor is used instead of a default filename block.
This is done just to show the use of a dataset descriptor.
FDRC$A specifies read/write mode
(block I/O).
FDBK$A
specifies the address and size of the user buffer, the
event flag for
synchronization, and
the
IOSB address.
Don't specify the address of the block number until after
opening the file.
478

FILE CONTROL SERVICES

Other data structures: A two-word block for the virtual
block number, initially set to virtual block 1; the user
buffer, and the I/O status block.

prompt for and read virtual block number.
"Low onl y"
means only a one-word virtual block number, rather than a
two-word val ue •

place a terminating null character at the end of the ASCII
virtual block number to set up for a call to $CDTB. Use
$CDTB to convert ASCII decimal to binary.
There is no
error check included, but it can be added.
Move the converted virtual block
block number block.

number

the

virtual

prompt for and get a character to place in the block.

Fill the user buffer with the character.

Ope n (c rea t e)

th e f il e •

start the I/O transfer.
specify the address of the
virtual block now, since the "open" call initializes the
block number to 1.
Display the message and wait for the I/O transfer to
complete.
Using WAIT$, FCS returns its standard error
indications. Call subroutine ERR3 in the case of an
error.
Close the fi Ie.
Set up to display the number of characters transferred,
branch to common code to edit and display the message, and
then exit. The code is common to the" error message code.

CD
CD

Common error code. Set up for an I/O or directive
message. Set up to exit with error status.

error

Common code for displaying a message, closing the file,
and ex i ting •
In the case 0 f a successful wr i te, yo u end
up calling CLOSES twice. There is no error for closing
the file after it is already closed. Use of the common
code saves space in the task.

479

FILE CONTROL SERVICES

1
2
3
4
5
6

8
9
10

.TITLE
.IDENT
.ENABL

BLOCKl

lOll

Enable lower case

File BLOCK1.MAC
BLOCKl creates a file BLOCK.ASC and fills the specified
virtual block of the file with the specified character.
It uses block 110.

+MCALL

~MCALL

:13

+MCALL

QIOW$,DIR$,QIOW$S,EXST$S ; S~stem macros
FDBDF$,FDRCSA,FDBK$A,FDOP$A,NMBLK$
FDAT$A,FSRSZ$,OPEN$W,WRITE$,WAIT$,CLOSE.

15
:1.6

:L'1
18
:L 9

20
:~1

MES:L:
LENl
MES2:
LEN2:::
MES3:
LEN3
MES4:

2~5

24
2~5

MESD:
MESI:

.NLIST BEX
+ASCII IVIRTUAL BLOCK NUMBER (LOW ONLY>: I
::: + .- MESl
.ASCII ICHARACTER: I
• - MES2
.ASCII /1 BLOCK BEING WRITTEN TO FILEI
:::: + -- MES3
.ASCII IWRITE COMPLETED, %D BYTES WRITTEN TO I
.ASCIZ IFILEI
.ASCIZ IFCS DIRECTIVE ERROR, CODE::: %D.I
.ASCIZ 'FCS liD ERROR, CODE::: %D.'

26
2'1

28
29

CHAR:
BUFF:

:3:1.

.BLKB
.BLKB
.LIST
.EVEN
FSRSZ$

:~2
~33

FDB:

~34
3~5

~56

o :~8

FDBDF$
FDAT$A
FDRCSA
FDBKSA

~37

~59

108B:

FDOP$A
.WORII
.WORII
.WORD
+ASCII
:: .-NAM
.EVEN
.WDRD
+BLKW
.BLKW

TYPE1:
TYPE2:
TYPE:~ :

QIOW$
CHOWS
CHOWS

DSPT:

40
41

42
43
44

.[:~
47
4B
49
~50

NAM:
LNAM
VBN:
BLOC/( :

Example 10-6

1
lOO.
BEX

Character to write
Buffer for $EDMSG

No FSR block buffers
needed for block 1/0
Reserve FIIB space
R.VAR,FD.FTN
File characteristics
FD.RWM
; Readlwrite mode
BLOCK,512.,,1,IOSB ; Adr, size of buffer,
ef 1, IOSB addr
1,DSPT
LUN 1, DSPT
0,0
Len~th and addr of device
0,0
Len~th and addr of UIC
LNAM,NAM
Len~th and addr of name
IBLOCK.ASCI
File name and t~pe
Default VBN
Use r buffe T'
liD status block

256.
2

IO.RPR,5,1"IOSB"(BUFF,6,,MES1,LEN1,'$)
IO.RPR,5,1""(CHAR,1,,MES2,LEN2,'$)
IO.WVB,5,2",,(MES3,LEN3,40)

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

480

FILE CONTROL SERVICES

!53

54
~5~5

O [ ;;

58
59

o[ ~~

63
64

66
OA
W67

CD [ ~~

G
A
W

70
71
72
7~5

[ 74

7~5

76
7"7
"78

80
81.

82
8~S

84
85

86
87

89
90
ell

92
93
94
95
96

97
98

; Code
START:

DIRS
iTYPE1
; Prompt and ~et VBN
MOV
IOSB+2,RO
; Len~th in RO
CLRB
BUFF(RO)
Put null b~te at end
MOV
iBUFF,RO
RO =) ASCII di~its
CALL
SCDTB
; Convert to binar~
MOV
R1,VBN+2
; Store as low VBN
DIRS
iTYPE2
; Input character
Fill user buffer with character
MOV
tBLOCK,RO
; Get address
MOV
i512.,R1
; and size of user buffer
lOS:
MOVB
CHAR,(RO)+
Move character
SOB
R1,10S
Loop back until done
; Open file to receive characters, write virtual block
OPENSW iFDB"""ERRl
Open, ERR1 if no ~ood
WRITES J"iVBN""ERR2 ; Start transfer
iTYPE3
, Sa~ transfer started
DIR.
, , ,ERF~3
Wait until it's done
WAITS
Close file
CLOSES ,ERR4
Adr of completion
:ft:MES4,R1.
MOV
; messag(~
; Exi t, statl.JS
tEXSSUC,R5
MOV
Branch to common code
FORMAT
BR
; for message display
and e~·d t
ERR1:
ERR2:
Er~R3 :
Directive or 1/0 error?
F.ERR+l(RO)
EF~R4 :
T8TB
Branch on 110 error
BE(~
IOEI:;:R
=) 110 error messa~e
:JI:MESD,R1
MDV
; Branch to common code
BR
FCSSET
=) Dir error messa~e
:JI:MESI,R1.
IOERR: MDV
Sisn extend error code
F.ERRCRO),R4
FCSSET: MOVB
Use 110 status block
R4,IOSB+2
MDV
for arg block
MOV
iEXSERR,R5
; Exit status to R5
; Print messaSe, exit with status in R5
FORMAT:
iIOSB+2,R2
; R2 =) 110 status
MOV
:JI:BUFF,RO
; RO =) SEDMSG buffer
MOV
SEDMSG
; Format the text
CALL.
CHOWSS iIO.WVB,:JI:5,:JI:2",,<iBUFF,R1.,:JI:40); And
write it out to TI:
; Close file and
CLOSES tFDB
; Exit with status
EXSltS R5
START
.END

Example 10-6

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

481

FILE CONTROL SERVICES

BI... OCK:I.
VIRTUAL BLOCK NUMBER (LOW ONLY): 2
CHAF<I~CTEI:~: \ C:~
1 BLOCK BEING WRITTEN TO FILE
WRITE COMP~ETED,
512 BYTES WRITTEN TO FILE
>F~UN

Virtual block 0,000001- Size 512.
Contains whatever was
DumF'

previousl~

of DR2:C305,301JBLOCK.ASC;10

b~tes

in that block on the disk

.... F:i.lc·? If.!

:3?3~5:5,

2y 0

ViT'tU(!Jl block OyOOOO02 .... S:i. ~~f? 512.

b~~te~;

:1.4:5 14:7; :I. 4~7;

14~5

:1.4:5

:1.4~5

:I.4~5

:1.4::5 14!:5 :I.4!5 145

14~5

14:7; 145 :1.4:7; 145 14:5 :1.45 :1.45

:1.4~:;

:I.4~)

14~)

:l.4~5

:1.4~5

:l.4~)

:l.4~5

14~5

000040

:1.4:5

14~5

14:7i 14::5 14:5 :1.4::5 :1.4:5 :1.45

:l.4~:;

:1.45 14::5 1. 4~5

:J.4~5

:1.4::i 145

:J.4~:i

000740

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

000760

145 :1.45 145 145 :1.45 145 145 :1.45 145 145 :1.45 :1.45 145 145 145 145

000000

145 :1.45

000020

14~:;

145

:J.4~:;

*** EOF ***
Example 10-6

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

482

FILE CONTROL SERVICES

Example 10-7 prompts at TI:
for a virtual block number,
and
then
reads and displays that block of BLOCK.ASC.
The following
notes are keyed to the example.

o
o
e

This example displays, in addition
to
the error codes,
text error messages which tell the user which FCS call
caused the error.
No FSR block buffers are needed for block I/O.
This is the FDB setup.
Use read/write mode.
Use FDBK$A
to
specify the
user buffer address and size, the event
flag, and the IOSB address.

o number.
open the file for read and prompt for
the virtual
block
o $CDTB.
place a null byte at the end of block number for a call to
Use $CDTB to convert the block number from ASCII
decimal to binary.
Store the resul t, returned in Rl by $CDTB, in the low byte
of the virtual block number block.

o
o
o
CD

Issue a READ$ to read the specified block, and
use WAIT$
to
wait for
the
I/O operation to complete.
READ$' and
WAIT$ return standard FCS status and error returns.
Display a heading and the virtual block.
Close the file and ex it.
Error code to display the
text message,
error code for each type of error.

483

including

the

FILE CONTROL SERVICES

.TITl.E
.IDENT
.ENABl.

2
3
4
5

H ..

;

?
8

BLOCK2

lOll

Enable lower case

File BLOCK2.MAC
; BLOCK2 prompts at TI: for a virtual block number
; and then reads and displa~s that block of nBLOCK.ASC·

10
11
12
1. :~
:1.4

15
:1.6

17
18
1,9

20
2:l
:~2

23
24
',)1::'

..~.,J

26
27

28
29

CR
LF
MESl:
LENl
MES2:
LEN2
MES3I:
MES~~D :
MES4I:
MES4D:
MES5I:
MES5D:
MES6I:
MESf.>D:
BUFF:

• MCAI...L
.MCALL
.MCALL

QIOWS,DIRS,QIOWSS,EXSTSS,EXITSS
FDBDFS,FDRCSA,FDBKSA,FDOPSA,NMBLKS
FSRSZS,OPENSR,READS,WAITS,CLOSES

.NLIST
::: 15

BEX

:::: :1.2

.ASCII IVIRTUAL BLOCK NUMBER: I
:::: • - MESl
.ASCII <CR><LF>/HERE IS THE BLOCK : I<CR><LF>
:::: • - MES2
.ASCIZ 'IIO ERROR ON OPENSR, CODE::: %D.'
.ASCIZ IDIRECTIVE ERROR ON OPENSR, CODE::: XD.I
.ASCIZ '110 ERROR ON READS, CODE:::: %D.'
.ASCIZ IDIRECTIVE ERROR ON READS, CODE - XD.I
.ASCIZ 'IIO ERROR AFTER WAITS, CODE:::: XD.'
.ASCIZ IDIRECTIVE ERROR AFTER WAIT', CODE:::: XD.I
.ASCIZ ,. IIO EIi:ROR ON CLOSES, CODE::: %D.'
.ASCIZ /DIRECTIVE ERROR ON CLOSES, CODE::: XD./
; SEDMSG output buffer
80 •
• BLKB

3()

.LIST
.EVEN
FSRSZS

o [~1!

a[H
V

FDB:

FDBDFS
FDRCSA
FDBKSA

FILE:

FDOPSA
NMBLKS

VBN:
BLOCK:
lOSS: -

.WORD
• BLKW
.BLKW

45
46

PROMPT: QIOWS

~'59

41
42
43

47
48
49

DONE:

QIOWS

~50

DUMP:

QIOW$

Example 10-7

BEX

No FSR block buffer
needed for block I/O
FDB for input file
FD.RWM
; Read/write. mode
BLOCK,512.,,1,IOSB ; Buffer adr, size,
ef 1, iosb adJ'
1"FILE
; LUN 1, DFNB
BLOCK,ASC
; Name i~ BLOCK.ASC
; . DefalJI t VBN
; User buffer
; 10SB

256.
2

; Prompt and ~et VB t
; Done
; messa~e
IO.WVB,5,1",,<0,64.,40> ; Displa~ of VB
IO.WVB,5,1,,~,<MES2,LEN2,40>

Reading a File With Block I/O (Sheet 1 of 3)

484

FILE CONTROL SERVICES

!51

o [ ;~

O [ !57
;~

!5B
~5(";

60
O [ 61

62
6~5

64
65
6c)

67
6B
6(,
70

o[ 71

'.72
73

74
75
76
77
7B
79

CC.H:ie

START:
ClPENSR

iFDB"""ERR1
Open file
iPROMPT
Ask for a VBN
IOSBt2,RO
Put null at end
MOV
BUFF(RO)
of digit string
CLI~B
tBUFF,RO
RO =) VBN
MDV
SCDTB
Convert to binar~
CALL
R1,VBN+2
; Store as low VBN
MOV
tFDB",tVBN""ERR2 ; Read in the block
READS
; Wait until done
, , "ERR~5
WAIT~.
; Tell them lID is done
Drr~s
tDONE
Now dump 8 lines of 64. characters each
MOV
iBLOCK,RO
RO =) 1st line to dump
MDV
t8.,Rl
i of lines to dump
1$:
MOV
RO"DUMPtQ.IOPL
Addr of current line
DIRS
tDUMP
Dump it
ADD
t64.,RO
Point at next line
SOB
R1,1$
Dump all 8. lines
CLOSES iFDB,ERR4
Close file
EXIT$S
Exit
; Error code
ERR1:
F • ERR+ 1 ( I~O )
lID or directive error?
TSTB
BE(~
Branch on lID error
IOERR1
=) Dir error messa~e 3
MOV
tMES3D"R1
Branch to common code
FCSERR
BR
=) lID error message 3
tMES3I,R1
IDEF~Rl: MOV
Branch to common code
BR
FCSERR
DIr~~~

BO
F.ERRtl(RO)
IOERR2
tMES4D,R1
FCSERR
iMES4I,Rl
FCSERR

lID or directive error?
Branch on lID error
=) Dir e~ror message 4
Branch to common code
=) liD error message 4
Branch to common code
lID or
Branch
=) Dir
Branch

B/=<

F.ERR+l(RO)
IOERR3
tMES5D,R:J.
FCSERR
tMES5I"/:;:1
FCSERR

TSTB
BEQ
MOV
BR
MOV

F.ERRtl(RO)
IOERR4
tMES6D"Rl
FCSERR
tMES6I,Rl

lID or directive error?
Branch on lID error
=) Dir error message 6
Branch to common code
=) 1/0 error message 6,
fall into common code

8:1.

TSTB

BE(~

B:~

B4
B5
B6

87
88
89
90
9:1.
92
93
94

MOV
BR
IOERR2: MDV
BR
ERR3:
TSTB
BE(~

I OER/~3:
EF~R4 :

95
9c)

98
99
100

MOV
BR
MOV

directive error?
on 1/0 error
error message 5
to common code
=> liD error message 5
Branch to common code

I(]EF~R4:

Example 10-7

Reading a File With Block I/O (Sheet 2 of 3)

485

FILE CONTROL SERVICES

101
102
103
104
105
106
107
108
109
110

FCSERR:

MOVB
MOV
MOV

F.ERR(RO),R2
R2,IOSB
tEXSERR,R5

MOV

MOV
CALL
QIOWSS

iIOSB,R2
Set UP for SEDMSG
tBUFF,RO
SEDMSG
iIO.WVB,i5,tl",,<iBUFF,Rl,t40>
Displaw

CLOSES
EXSTSS
.END

iF DB
R5
START

extend error code
and move into 10SB
Exit status in R5
Si~n

FORMAT:

111

112
113

messa~e

Close the file
Exit with status

Run Session

>RUN BLOCK2
VIRTUAL BLOCK: 2
HERE IS THE BLOCK:
eeeeeeeeeeeeeeeeeeeee~eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee eeeeeeeeee

eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

Example 10-7

Reading a File With Block I/O (Sheet 3 of 3)

486

FILE CONTROL SERVICES

ADDITIONAL TOPICS
Deleting a File
Use the DELET$ macro to delete a file.
If the file is open,
DELET$ closes the file and
then deletes
it.
If the file is
closed, DELET$ just deletes the file.
The format of the DELET$
call is:
DELET$ fdb,err
DELET$

FDB 3
NOTE
Unlike the DCL DELETE command, if no version
is specified, the latest version of the file
is deleted.

File Control Routines
You can use a number of internal FCS routines in
Some of the available functions include:

your

task.

•

Filling in an FDB filename block from a dataset descriptor
or default filename block.

•

Finding, inserting, or deleting a directory entry.

•

Marking a place in a file for later return.

•

Setting a pointer to a byte within a virtual block, or
the start of a record in a file.

•

Renaming, extending or truncating a file.

•

Marking a temporary file for deletion, or deleting a
by FDB filename block.

file

We have already discussed the use of the routines
.MARK and
.POINT for marking a place in a file so that you can later return
to it, and .POSRC for locating a
record with random access
in
locate mode.
See Chapter 4 of the IAS/RSX-II I/O Operations
Reference Manual for a description of each of the
file control
routines, plus information on how to use them.

487

FILE CONTROL SERVICES

Command Line Processing
You can use two other collections of routines to facilitate
input and processing of command lines, which are useful in general
or utility tasks. The routines and their functions are:
•

Get Command Line (GCML)
performs command line
prompts, gets input)

•

input

operations

(issues

Command String Interpreter (CSI)
parses the file specification in a command line
GCML into a dataset descriptor, for use by FCS

from

Parses and processes any switches and switch values in
the command line.
See Chapter 6
on
Command
Line
processing
in
the
IAS/RSX-ll Operations Reference Manual for a description of the
command line processing routines. The program CSI.MAC should be
available on-line
(under UFD [202,1]).
It is also listed in
Appendix G, and contains an example of the use of GCML and CSI.
This example is needed to do optional exercise 6 for this module.
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 files
(should
be under UFD [202,2]) or the printed copies 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 finished- with this course.
If you think that you have not yet
return to this module for further study.

488

mastered

the

material,

APPENDICES
•

APPENDIX A
SUPPLIED MACROS
The supplied macros are designed for simple invocation.
They
are
intended for use early in the course (before QIOs are taught)
to provide easy ways of doing I/O t~ TI:,
and
in labs to make
writing programs easier for the student.
They are also used in
some example programs to allow brevity of code and
to establish
consistency in error checking.
These macros are contained in the macro library PROGMACS.MLB
and can be assembled by using the
following assembler and
task-builder calls:
MACRO/LIST LB:[l,l]PROGMACS/LIBRARY,dev:[ufd]SAMPLE
(in MCR, MAC SAMPLE,SAMPLE=LB:[l,l]PROGMACS/ML,dev: [ufd]SAMPLE)
LINK/MAP SAMPLE,LB:[l,l]PROGSUBS/LIBRARY

Needed to include
the internal
subroutines
(in MCR, TKB SAMPLE,SAMPLE=SAMPLE,LB:[I,l]PROGSUBS/LB)
NOTE
If you make copies of PROGMACS.MLB
and
PROGSUBS.OLB
in
your
UFD
(or enter a
synonym), then the LB:[l,l] and the dev:[ufd]
can be omitted.

This appendix includes directions for
using the
macros,
the MACRO-II source code for
the macros,
internally-called subroutines.

491

supplied
and any

SIMPLE MESSAGE OUTPUT
Invocations:

TYPE
TYPE
TYPE

Description:

In the first two forms, supply the text of
the message; the macro will generate the
storage. Use 'the second form if you are programming in a Psect other than the default;
supply the name of the Psect in which you are
writing.

<message>
<message>"psect
message-address,message-length

In the third form, provide the message address
and length using standard addressing modes.
The message can be ASCII or ASCIZ.
If it is
ASCIZ, supply a value of 0 for the message
length; if it is ASCII, supply the length in
bytes.
Examples:

MS G1 :

• AS C I Z
.ASCII
MSG2:
MSG2LN=.-MSG2

TYPE
TYPE
TYPE
Outputs:

ITHIS IS MESSAGE ill
ITHIS IS MESSAGE i21

iMSG1,i0
iMSG2,iMSG2LN
<THIS IS MESSAGE i3>

All registers are preserved.
C-bit is set for error;
clear for no error.

Note:

Event flag 24(10) is used for synchronization.
Avoid using this flag for other purposes in
your task.

Task-Building:

This macro requires subroutine modules TYPOUT
and LENGTH from PROGSUBS.OLB~

492

SIMPLE MESSAGE INPUT
Invocations:

INPUT

buffer,length

Description:

Accepts input data from TI:, into specified
buffer.
Length is in bytes. Use standard
addressing modes for all arguments.

Outputs:

R0 points to the input buffer.
R1 contains the byte count from the I/O status
block if there is no error.
C-bit is set for error;
clear for no error.
For directive errors, RI is clear; $DSW
contains directive error code.
For I/O errors, R1 contains error code
from the I/O status block.

Note:

Event flag 24(10) is used for synchronization. Avoid using this flag for other
purposes in your task.

Task-Building:

This macro requires subroutine module TYPIN
from PROGSUBS.OLB.

•

493

ERROR MESSAGE MACROS
Error message macros generate error messages appropriate
Executive directives, I/O operations, and FeS calls.

•

All macros have message, length, and Psect arguments whose
interpretations are identical to those for the TYPE macro.
These are used to specify the user-defined section of the
error message.

•

The calling program must check for acceptable errors
before calling the error message macro, because the error
routine aborts the task.

•

All macros exit unconditionally with "severe error" status
after the error message is printed.

•

All macros require the subroutine modules EREXIT,
and LENGTH from PROGSUBS.OLB.

TYPOUT,

EXECUTIVE DIRECTIVE ERRORS
Invocations:

DIRERR
DIRERR
DIRERR

<message>
<message>"psect
message-address,message-Iength

Notes:

User should check C-bit and dismiss acceptable
errors before calling DIRERR.

Format of
Message:

DIRECTIVE ERROR
<user-defined message>
DSW = <value> •

•

494

I/O ERRORS
Invocations:

IOERR
IOERR
IOERR

Notes:

iosb is a pointer to the I/O status block.

iosb,<message>
iosb,<message>"psect
iosb,message-address,message-length

User should check the low-order byte of the
first word of the I/O status block, and dismiss
acceptable errors before calling IOERR.
Format of
Message:

I/O ERROR
<user-defined message>
I/O STATUS BLOCK = <hb>,<lb>/<2nd word>
hb is the high byte of the first word.
lb is the low byte of the first word.

FCSERRORS
Invocations:

FCSERR
FCSERR
FCSERR

Notes:

fbd is a pointer to the file descriptor block
for the operation which caused the error.

fdb,<message>
fdb,<message>"psect
fdb,message-address,message-length

User should check the C-bit and/or check F.ERR
in the FDB, and dismiss acceptable errors before
calling FCSERR.
Format of
Message:

FCS ERROR
<user-defined message>
DSW = <value>
or
FCS ERROR
<user-defined message>
I/O ERROR CODE = <value>.

495

MACRO-11 CODE FOR SUPPUED MACROS
.MACRO
.NLIST

2
3
4

TYPE

MESSG,LEN,PSCT

Macro to invoke the -TYPOUT- routine to
TI:.

6
7
8
9
10

t~pe

a line on

Invoke usinS one of two forms:
TYPE

11
12
13
14
15
16
17
18
19
20
21

<messa~e)

or
TYPE
In the first form ~ou specif~ the text of the message.
The macro reserves storage for the string.
WARNING: The character
is used as the delimiter in a
.ASCII directive when wou invoke the first form, so
~bu maw not use this character in ~our message.
In the second form ~ou must use addressing modes to
specifw the address and length of a string which ~ou
have reserved in ~our proSram. The first arSument is
the address of an ASCII or ASCIZ strins.
The second
arSument should have a value of 0 if the string is
ASCIZ, else should be the lensth of ·the ASCII string.
addressins modes using the stack pointer are not
allowed.

22
23

24
25
26
27
28

30
If wou use the first form and are programming in other
than the blank Psect, ~ou must explicitl~ provide a
null -LEN· arSument, and specif~ a third argument
(psect). This arSument must be the name of the Psect
in which ~ou are programmins.

32
33

34
35
36
37
38
39
40
41

Needed subroutine modules: TYPOUT and LENGTH
s~mbols

SAV.Rn

= -1 if Rn is not saved on the
stack
)= 0 indicates Rn is stored on
the stack at SAV.Rn(SP).

42
43

45
46
47
48
49
50
51

;.LIST
.GLOBL

TYPOUT

Subroutine to issue GIO
directive
Assume no need to save
RO
Assume no need to save
R1
Assume no need to save
R2

SAV.RO = -1
SAV.R1 = -1
SAV.R2 = -1

52
53

496

54
55

.IF B

56
57

.PSECT MSGTXT
$$$MES=.
• ASCI I
'MESSG'
$$$LEN=. ""$$$MES
.PSECT PSCT
MDV
RO,-(SP)
MOV
t$$$MES,RO
MOV
Rl,-(SP)
MOV
t$$$LEN,Rl
SAV + RO "" 2
SAV.Rl ::: 0

58
59

60
61
f.,::!

63
64

65
66
67
C)S
69

70
71
72

LEN

Second form of
;
invocation
If arSuments are not already in the correct resisters,
save them temporarilw on the stack
ADM.Al,MESSG

'76

.IF
MOV

NE,ADM.Al
MESSG,-(SP)

77
78

SAV.RO == 0

74
75

80
81
f.J2
83
84

86
87
88
89
90
91
92

Back to oriSinal Psect
Save old RO
RO ::::> messaSe
S(~ve old Rl
Rl == messaSe lensth
Note RO saved on stack
Note Rl saved on stack

.IFF

.NTYPE

Blank LEN arS means
fi rst, form
Set UP text in Psect
MSGTXT

SAV.R2 == 0
.ENDC

Addressins mode of
MESSG
If anwthins but BRO·
Save arSument on the
stack
RO will be saved here
later
We'll need to save R2

AddressinS mode of LEN
If anwthins but BRIB
Save arSument on the
stack
Rl will be saved here
SAV.Rl == 0
;
later
.IIF GE,SAV.RO, SAV.RO==SAV.RO+2 ; Increase
; offset of RO
SAV.R2 ::: 0
; We'll need to save R2
.ENDC

.NTYPE
.IF
MOV

ADM.A2,LEN
NE,ADM.A2-1
LEN,-(SP)

94
9~':;

96
97
98
99
100
101
102

Swap the reSisters with their arSument values which we
stored on the stack.
.IF
EQ,SAV.R2
; If we need to save R2
MOV
R2,-(SP)
; Save R2
.IIF GE,SAV.RO, SAV.RO=SAV.RO+2 ; Increase
offset of RO
.IIF GE,SAV.Rl, SAV.RI=SAV.Rl+2 ; Increase
offset of Rl
.ENDC

l03

497

104
105
106
107
lOB
109
110
111
112
113
114
115
116
117
:1.18
119
:1.20

121
122
12~5

:1.24
12~5

.IF

GE,SAV.RO

MOV
MOV
MOV
.ENIIC

RO,R2
SAV • 1:;:0 ( SP ) , RO
R2"SAV.RO(SP)

.IF

GE"SAV.Rl

MOV
MOV
MOV
.ENDC

R:I. ,R2
SAV.R1(SP),R1
R2,SAV.R1(SP)

It' RO's en'g was put on

stack,
swap RO with its
argument vallJe

It' R1's arg was F,ut on

stack,
Swap R1 with its
argument value

Forms at' invocation

.ENDC
CAL.L..
TYPOUT
Restore resisters
.IIF GE,SAV.R2" MOV
.IIF GE"SAV.R1, MOV
.IIF GE"SAV.RO" MOV
.ENIIM
TYPE

498

(SP)+,R2
(SP)+,R1
(SP)+"RO

Restore old R2
Restore old 1~1
Restore old RO

.MACRO

INPUT

2
3

4
5
6

Macro to invoke the "TYPIN u routine to input data from
TI:.

7
8

Invoke using:

10
11

INPUT

12
13
14
15
16

where address and length are the address and
lensth of the input buffer.

OUTPUTS:
;

=> buffer

C-bit is set for error, clear for no
error (for directive or I/O errors)

20
21
22
23
24
25
28
29
30
31
32
33
34
35

Data is input swnchronouslw from LUN 5
RO

18
19

26
27

address,lensth

If no error, Rl contains bwte count from
I/O status block.
If a directive error is encountered, R1
is clear, $DSW contains error code

;

If an I/O error is encountered, Rl
contains error code from I/O status block
Needed subroutine module: TYPIN
WARNINGS:

1. ROUTINE USES EVENT FLAG .24 FOR
SYNCHRONIZATION
2. RO AND R1 ARE DESTROYED

37
38
39
40

.GLOBL

.IF

46
47

Subroutine to issue aIO
; directive
.NTYPE ADRMOD,BUFFER; Check addressing mode
NE,ADRMOD
Buffer pointer alreadw in R01
MOV
BUFFER,RO ; No, move it there

.ENDC

.NTYPE ADRMOD,LEN; Check addressing mode
NE,ADRMOD-l
Lensth alreadw in Rl?
MOV
LEN,Rl
No, move it there

.ENDC
CALL

TYPIN

Call subroutine to issue aIO
directive

.ENDM

499

.TITLE

2
3

TYPOUT

Subroutine to output to TI:

5
6
7

TYPOUT provides a simple wa~ for MACRO-11 routines to
t~pe out a messaSe on TI:.

8
9
10
11
12
13

CALL:

JSR

INPUTS:

RO
Rl

24
25
26
27

ASCII or ASCIZ messaSe

o if strins is ASCIZ

LUN 5 is assumed to be assisned to TI:
OUTPUTS:

MessaSe is output

s~nchronousl~

to LUN 5

All resisters preserved

19
20
21
22
23

n>O for ASCII strinS of lensth n

14
15
16
17
18

PC,TYPOUT

C-bit is set for error, clear for no
error
WARNING:

Routine uses event flas 124 for
s~nchronization

The macro "TYPER can be used to invoke this routine
in a fairlw transparent manner.

29
30

.GLOBL

LENGTH

31
32

.MCALL

QIOW$S

33
34
35
36
37
38
39
40
41
42
43

44
45

TYPOUT:: TST
BNE

Subroutine to determine
lensth of strins
S~stem macro

ASCII input or ASCIZ?
Branch if ASCII. R1
alread~ has lensth
CALL
LENGTH
Find lensth of strinS
(returned in Rl)
1$:
MOV
R2,-(SP)
Save R2 on stack
SUB
t4,SP
Reserve space for IOSB
MOV
SP,R2
; R2=>IOSB
Do a Sarden varietw output to TI:
QIOW$S tIO.WVB,t5,t24.,yR2y,(RO,Rl,t40>
BCC
2$
Branch on directive OK

ADD

Directive error. PurSe
10SB from stack

500

Exit (with C-bit set)

49
50

Directive succeeded. Record anw liD errors, recbrd
bwte count~ pur~e stack

2$:

CMPB

Irs.suc,(SP)+
4$

3$:

BEQ
SEC
BR
CLC

4$:

TST

(SP)+

54
55
56

57
58

rio error?
Branch if no error
Set C-bit to indicate
error
Branch to ~et liD count
Clear C-bit to indicate
no error
Clean UP stack

61
62
63
64
65

; COMMON EXIT
6$:

MOV

(SP)+,R2

Restore R2
Return

RETURN
.END

501

.TITLE

:I.
2

TYPIN

Subroutine to input from TI:

5
6
7
B
9
10
11
1 ':>

TYPIN provides a simple wa~ for MACRO-11 routines to
input data from TI:.
CALL..:

..JSR

INPUTS:

:1. :3

14
15
:1.6

F~O

=:>

R1.

Inf'ut buffer
LenSth of buffer in b~tes

LUN 5 is assumed to be assi~ned to TI:
OUTPUTS:

Data is input

:1.7
:LB
:1.9

(~q'

s~nchronousl~

from LUN 5

unch<:~n~.~(~':!r..i

C-bit is set for errorv clear for no
r C) r ( f.o r d :i. r f~ c t i V (.? 0 T' I/O €.~ r rOT's)

2:L

If no errorv R1 contains b~te count from
I/O status block.
25
26
27

If a directive error is encountered v R1
is clearv $DSW contains error code

If an I/O error is encountered, R1
contains error code from I/O status
block

29
30

:':H

ROUTINE USES EVENT FLAG #24 FOR
SYNCHRONIZATION

:'~2
~;S:·~

34
35
~56

37
38
39

40
4:L

42
4~~

44
4~5

4B
49
~50

The macro "INPUT R can be used to invoke this routine
in a fairl~ transparent manner.
• MCALI...

Q I OWlS

S~-lS

telTl ITI(!~C ro

TYPIN:: MOV
R2,-(SP)
Save R2
SUB
t4,SP
Reserve space for IOSB
MOV
SP,R2
; R2~>IOSB
Do a ~arden variet~ input from TI:
QIOWSS #IO.RVB,tSvi24."R2,,(RO,R1>
BCC
2$
Branch on directive OK
ADD
t4,SP
Directive error. Pur~e
10SB from stack
CLR
R1
Note directive error
SEC
6~.
BR

502

Directive succeeded. Check for I/O errors, record
count, purSe stack

b~te

2$:

57
58

MOV
CMPB
BEQ
TST

Get success/error code
1/0 error?
Brnch if no error
Error. For~et about
1/0 count
Just return with C-bit
set and I/O status in
R1
Branch to common exit
Clear carry bit
Return 1/0 count in R1

(SP)+,R1
tIS.SUC,R1
4$

(SP)+

59
60
61
62
63
64

SEC

4$:

65
66
67
68
69
70
71

BR
CLC
MOV

(SP)+,R1

COMMON EXIT
(SP)+,R2

Restore R2
Return

RETURN
.END

.TITLE

LENGTH

2
3

len~th

5
6

LENGTH finds the

CALL:

CALL

8
9
10

INPUT:

OUTPUT:

RO preserved
Rl Len~th of

11
12
13
14
15
16
17
18
19
20
21

22
23
24

25
26
27

of an ASCIZ

strin~

LENGTH

ASCIZ

strin~

terminatin~

(not

includin~

null)

;
LENGTH:: CLR
MOV

Rl
RO,-(SP)

1$:

TSTB

(RO)+

Clear counter
Save pointer to
be~innin~ of strin~
Real character or null

BEQ

Null means end of

INC
BR
MOV

Rl
1$
(SP)t,RO

Count real character
And look at next b~te
Restore original
pointer
Return

b~te?
strin~

RETURN
.END

503

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

20
21
22
23
24
25
26
27

.MACRO

DIRERR

MESSAG,LEN,PSCT

COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION
Macro to ~enerate a Bdirective error l messa~e and
print out the value of the DSW, plus a user-defined
message. The task is forced to exit after the messa~e
is printed.
The form of the resultant error

messa~e

is:

DIRECTIVE ERROR
<USER-DEFINED MESSAGE>
DSW = <VALUE>
It is su.~ested that the user-defined messa~e identifw
the operation which returned the error.
It is the caller's responsibilitw to check the c-bit
prior to invokin~ DIRERR. This convention allows the
user to accept certain twpes of errors, then invoke
DIRERR for anw other kinds of errors.
Invoke

usin~

one of two forms:

DIRERR

<messa~e>

DIRERR

ADDRESS,LENGTH

30
31
32
33
34

36
37
38

39
40
41

42
43

In the first form wou specifw the text of the
The macro reserves stora~e for the strin~.

messa~e.

In the second form wou must use addressin~ modes to
specifw the address and len~th of a strin~ which wou
have reserved in wour pro~ram. The first ar~ument is
the address of an ASCII or ASCIZ strin~.
The second
ar~ument should have a value of 0 if the strin~ is
ASCIZ, else should be the len~th of the ASCII strin~.
If wou use the first form and are pro~rammin~ in other
than the blank Psect, wou must explicitlw provide a
null BIen' ar~ument, and supplw as the third ar~ument
the name of the Psect to return to.

504

45
46
47
48
49
~50

51
5;!
5~5

.GLOBL
.GLOBL

EREXIT
DIRERI

.GLOBL ERARGS·
Offsets into arg'Jment block:
.GLOBL E.RUMA
.GLOBL E.RUML
.GLOBL E.RDSW

COlTlmon routine
-DIRECTIVE ERROR u
in?'Jt string for
$EDMSG
$EIIMSG argument block
User-message address
User-message lensth
rrsw 'v'al'Je

~54

55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
7:~

73
74
7~5

.IF B

MOV
LEN

tERARGSl'R2

.F'SECT

MSGTXT

R2=>$EDMSG aI's block
Blank len arg means
first form

$$$MES=.
.ASCII IMESSAGI
$$$LEN=. ·-$$$MES
.F'SECT F'SCT
t$$$MES,E.RUMA(R2)
MOV
t$$$LEN,E.RUML(R2)
MOV

.IFF

MOV
MOV

MESSAG,E.RUMA(R2)
LEN,E.RUML(R2)

MOV
MOV
,JMF'

$DSWl'E.RDSW(R2)
tDIRERI,R3
EREXIT

.ENDC

.ENDM

505

; Load message addr
;
and ITlessage length
;
ir.to arg bloc"~
;
;

Load message addr
ar.d message length
into arg block

Load DSW into arg block
R3=}$EDMSG inPIJt string
JIJm? to common error
eHit routine

+MACRO

2
3
4
5
6
7
8

IOERR

;+
COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION
Macro to ~enerate an HI/O error A messa~~ and print out
the value of the 1/0 status block, plus a user-defined
messaSe+
The task is forced to exit after the messaSe
is printed+

10
11

The form of the resultant error

messa~e

is:

1/0 ERROR
(user-defined messa~e>
1/0 STATUS BLOCK = <hb>,(lb>/(2nd word>

12
13

14
15
16
17
18

where Ahb H and AlbA are the hi~h bwte and low byte of
the first word of the liD status block+

It is su~~ested that the user-defined messa~e identify
the operation which returned the error.

20
21
22

It is the caller's responsibility to check the first
word of the 1/0 status block prior to invokin~ IOERR,
to see whether the operation has been a success or a
failure+ This convention allows the user to accept
certain twpes of errors, then invoke IOERR for any
other kinds of errors.

23
24
25
26

27
28

29
30

Invoke

usin~

one of two forms:

IOERR

32
33
34
35
36

or
IOERR
In either form uiosb u is the address of the 1/0 status
block, in any addressin~ mode+

38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

In the first form YOU specifw the text of the
The macro reserves stora~e for the strin~+

messa~e+

In the second form wou must use addressin~ modes to
specifw the address and len~th of a strinS which YOU
have reserved in your pro~ram+ The second arSument is
the address of an ASCII or ASCIZ strin~.
The third
ar~ument should have a value of 0 if the strinS is
ASCIZ, else should be the len~th of the ASCII strinS+
If wou use the first form and are pro~ramminS in other
than the blank Psect, YOU must explicitly provide a
null -LEN" ar~ument, and supply as the fourth ar~ument
the name of the Psect to return tOt

506

53
54
55

.GLOBL
.GLOBL

.GLOBL
Offsets into
.GLOBL
.GLOBL
.GLOBL

57
58
59

60
61
62
63
64

Common routine
'I/O ERROR- input
strin~ for SEDMSG
SEDMSG ar~ument block

EREXIT
IOERIN
ERARGS
ar~ument

block:

E.RUMA
E.RUML
E.RIOS

.PSECT

MSGTXT

SSSMES=.
.ASCII /MESSG/
$$$LEN=.-S$$MES
.PSECT PSCT
t$SSMES~E.RUMA(R2)
MOV
t$$$LEN,E.RUML(R2)
MOV

79
80

81
82

84
85
86

Load messa~e addr
and messa~e len~th
into ar~ block

.IFF
MOV
MOV

75
76

77
78

len~th

R2=)$EDMSG ar~ block
Blank LEN arS means
first form

66
67
68
69
70
71
72

address

First word of I/O
status block

MOV
LEN

.IF B

User-messa~e
User~messaSe

~ENDC
Cop~

;

MESSG,E.RUMA(R2)
LEN,E.RUML(R2)

Load messa~e addr
and messa~e len~th
into ar~ block

I/O status block into SEDMSG arS block
MOV
IOSB,Rl
Rl =) I/O status block
MOVB
1(Rl),R3
Get hi b~te of first
word (and si~n-extend
it)
R3,E.RIOS(R2)
Cop~ into ar~ block
MOV
(Rl),R3
Get 10 b~te and
MOVB
si~n-extend

87
88

MOV
MOV

89
90
91

MOV

R3,E.RIOS+2(R2)
Cop~ into ar~ block
2(Rl),E.RIOS+4(R2); Cop~ 2nd word of
10SB
tIOERIN,R3
R3 =) SEDMSG input

JMP

EREXIT

93
94

.ENDM

strin~

Jump to common error
exit routine

507

2
3

ec) 1981 BY DIGITAL EQUIPMENT CORPORATION

5
6
7
8

Macro to ~enerate an -FCS ERROR- messa~e and print out
the error code plus a user-defined messa~e. The task
is forced to exit after the messa~e is printed.

9
10

The form of the resultant error

messa~e

is:

FeS ERROR
(USER-DEFINED MESSAGE>
DSW = (VALUE>

12
13
14
15
16
17
18
19

or
FCB ERROR
(USER-DEFINED MESSAGE>
I/O ERROR CODE = <VALUE>

20
21

22
23
24
25
26
27

28
29

It is su~~ested that the user-defined messa~e
the operation which returned the error.

identif~

It is the caller's responsibilit~ to check F.ERR in
the FDB prior to invokin~ FCSERR, to see whether the
operation has been a success or a failure. This
convention allows the user to accept certain t~pes of
errors, then invoke FCSERR for an~ other kinds of
errors.

30
31

Invoke usinS one of two forms:

32
33
34
35

36
37
38
39
40
41

42
43
44
45
46
47
48
49
50
51
52
53
54

FCSERR

fdb,(messa~e>

FCSERR

fdb,address,len~th

or
In either form, ·fdb- is the address of the file
descriptor block for the FCS operation which has
~enerated the error.
In the first form ~ou specif~ the text of the
The macro reserves stora~e for the strin~.

messa~e.

In the second form ~ou must use addressin~ modes to
the address and len~th of a strin~ which ~ou
have reserved in ~our pro~ram. The second ar~ument is
the address of an ASCII or ASCIZ strin~. The third
ar~ument should have a value of 0 if the strin~ is
ASCIZ, else should be the len~th of the ASCII strin~.
specif~

If ~ou use the first form and are pro~rammin~ in other
than the blank Psect, ~ou must explicitl~ provide a
null BIen- arsument, and suppl~ as the fourth ar~ument
the name of the Psect to return to.

508

57
58
59

60
61
62

.GLOBl. EREXIT
• Gl.OBL FCStrIR,FCSIO
.GLOBL ERARGS
Offsets into arsument block:
.GLOBL E.RUMA
.GLOBL E.RUML
.GLOBL E.RCOD

63
64
b5

.MCALL
FDOF$L

FDOF$L

MOV
LEN

tERARGS,R2

.f'SECT

MSGTXT

Common rOIJt i ne
$EDMSG input strinss
$EDMSG arsument block
User-messase address
User-messase lensth
Error code (DSW value
or I/O error)
Define FtrB offsets

R2=)$EDMSG ars block
Blank len ars means
first form

69
70
71

.IF 13

$$$MES=.

.ASCII /MESSG/
$$$LEN=.-$$$MES
.f'SECT f'SCT
t$$$MES,E.RUMA(R2)
MOV
t$$$LEN,E.RUML(R2)
MOV

74
75
76

77
78

80
81
82
83
84

.IFF
MOV
MOV

MESSG,E.RUMA(R2)
LEN 1I E. J~UML (R2)

MOV

86
87
88

MOVB

F.ERR(R1),RO

MOV
TSTB

RO,E.RCOtr(R2)
F.ERRt1(Rl)

BEQ
10
Directive error:
MOV
tFCSDIR,R3
JMf'

9~5

96
97

Load messase addr
and messase lensth
into ars bloct<.

.ENDC

89
90
91
92
93
94

Load messase addr
and messase lensth
into ars block

10:

R3=) HFCS DIRECTIVE
ERROR H $EDMSG strins
Jump to common error
e~d t
routine
R3=)HFCS I/O ERROR'
$EDMSG strins
Jump to common error
exit routine

EREXIT

MOV

98
99
100

JMf'

101

.ENDM

Rl=) file descriptor
block
Get error code
(sisn-extend) and
store into ars block
Directive error or I/O
err'or?
Branch on I/O error

EREXIT

509

1
2

.TITLE

EREXIT

ERROR EXIT ROUTINE

This is a common exit routine called bw the
error-processin~ macros DIRERR, IOERR, and FCSERR.
It
twpes out an error messa~e and for6es the task to exit
with status ·severe error-.

7
8
9
10
:Ll.
12

Cc-Jll :

JMP

Inp'Jts:

EREXIT
:::::>

1.3
1.4

ERARGS ($EDMSG ar~'Jment block,
defir.ed irl this routir.e)
The aT'~UIT.ent block has alreadw
been filled in with the
user-messa~e descriptor,
and the
s~Jstem error code (DSW value or
IOSB poir.ter) • A 'Jse r-messa~e
:: 0 means that the
len~th
user lTIessa~e is ir. ASCIZ form.

15
16
17

18
:t (~
2()

2:t

2~5

::::).

One of the $EIIMSG input strin~s
defined in this routine

25
26
27

28
29
3()

.GLOBL
.GLOBl.

$EIIMSG
LENGTH

.MCALL
.MCALL

EXST$C
TYPE

Comp'Jtes len~th of
ASCIZ strin~
Swstem macro
S'JPpl ied macro

Error exit stat'Js

EX$SEV

:'~2

M ..

:33
34

$EIIMSG input strings:

;

DIRERI:: .ASCII IXNIIIRECTIVE ERRORI
.ASCII IZNXVAI
.ASCIZ IXNDSW:: XDI

37
38

;

40
4l.

FCSDIR:: .ASCII I%NFCS ERRORI
.ASGII IXNZVAI
.ASCIZ IXNDSW:: XDI

42
43
44
45
46
47
48
49
50
51

;

IOERIN:: .ASCII @XNI/O ERROR@
.ASCII I%NXVAI
.ASCIZ @XNI/O STATUS BLOCK:: XD, XD I XD@
FeSIO:: .ASCII
.ASCII
.ASCIZ

@%NFCS ERROR@
/XNXVAI
@%NI/O ERROR COIlE - XD@

510

OUTBUF: • BLKB
200.
.EVEN
; $EDMSG arSument block
ERARGS::
E. RUML:::::: + -ERARGS
.WORD
E.RUMA::::::::.-ERARGS
.WORD
; Error codes
E.RDSW::::::::.-ERARGS
E. RIOS:::::: + -ERARGS
E • Ii: CO [I:::::::: • '-ERARGS
.WORD
.WORD
.WO/i:D

68
69

EREXIT::

54
55
56
57
58

59
60
61
62

63
64
65
66

$EDMSG output buffer

User-messaSe lensth
User-messaSe address
DSW for DIRERR
rOSB for IOERR
FCS code for FCSERR

;

70
71
72
73

TST

E.RUML(R2)

User messaSe ASCII or

BNE

74
75

MOV
CALL.
MOV

E.RUMA(R2),RO
LENGTH

MOV

:l:OUTBUF,RO

MDV

R3,R:L

83
84
85

CALL
TYPE

$EDMSG
tOUTBlJF, Rl

EXST$C
.END

EX$SEV

ASCII
If ASCIZ, find lensth
RO ::::) user messaSe
(ret'..tr'ned irl Rl)
Set lensth field in
arsument block
Output buffer for
$EIIMSG
Put input strins
pointer into proper
resister for $EDMSG
(returns lensth in Rl)
T~pe out formatted
messaSe
Exit/severe error

ASCIZ"~

;

78
7(J
80
81

1.$:

Rl,E.RUML(F'~2)

511

APPENDIX B
CONVERSION TABLES
Table B-1

Decimal/Octal, Word/Byte/Block Conversions

Words(10)/Words(8)

Bytes(10)/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

APR

Virtual Addresses

000000-017776

0-4K

020000-037776

4-8K

040000-057776

8-12k

060000-077776

12-16K

100000-117776

16-20K

120000-137776

20-24K

140000-157776

24-28K

1-60000-177776

28-32K

513

Words

,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.
R5 ----)

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
Accessing:
Argument count
Argl = @2(R5)
Arg2 = @4(R5)
;
Arg3 = @6(R5)
SUBNAM: :
RTS PC

= (R5)

; or RETURN

515

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

A:
B:
C:

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

3,0
A
B
C

MOV
JSR

#LINK,R5
PC,SUB

3
0

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.

516

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 following qualifiers
privileged task.
1.

/PRIVILEGE:0 qualifier

run-

(switches)

build

(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.

/PRIVILEGE:4 or /PRIVILEGE:5 (MeR /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
Executive, 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 20K
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.

517

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

518

APPENDIX E
TASK BUILDER USE OF PSECT ATTRIBUTES
The Task Builder collects scattered occurrences of program
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 for a
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 B'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).

519

Example of scope code attributes:
LCL (local) versus GBL (global)
B.ODL file:

Overlay Tree
B3

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

B2
I

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

LINK B/OVERLAY__DESCRIPTION

B.OBJ has Psect Q,LCL,CON - length 100(10) words
B1.0BJ has 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 B1

B.OBJ has Psect Q,GBL,CON - length 100(10) words
B1.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
B1's 50(10) words.
If GBL,OVR instead, yields 100(10) words in Psect Q in the
root segment.
B's 100 words, with B1's 50(10) words the
same as B's first 50(10) words.

520

B2.0BJ has Psect Q (LCL or GBL) - length 100(10) 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.

overlaid tasks.
In a
LCL and GBL are
used only for
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/ 1(100)
Macro translation:
.PSECT RDATA,RW,D,GBL,OVR,REL

521

APPENDIX F
ADDITIONAL SHARED 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-resident 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
1.

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, using GLBREF option.

root
root,

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=0
Option? PAR=OVRLIB:140000:40000
Option? GBLREF=H,I,J
Option? <RET)

523

are
when

Referencing task
is
reference library OVRLIB.

created

using

regular

procedure

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

PHYSICAL
MEMORY

VIRTUAL
MEMORY

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

-\\t-J\~ ~
~~~~-------,~- ~
160000 APR7

__ - - -:.. TIME 1

140000 APR6

120000 APR5

-- --

(MAP) ...

-- ---

100000 APR4

60000 APR3

INITIAL
LOAD

G
(16K WORDS)

40000 APR2

20000 APR 1

o APRO

_ _ _ _ _ _ _ __

--- -TK-7773

Figure F-l

A Shared Region With Memory-Resident Overlays

524

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)

525

PHYSICAL
MEMORY

II
VIRTUAL
MEMORY

----1-__ /

ARES

7-- __

160000 APR7

--1-'---140000 APR6

120000 APR5

I -'

TASK REF

BRES

ARES

100000 APR4

60000 APR3
40000 APR2

REF
(16K WORDS)
REF

20000 APRl

o APRO

--------TK-7772

Figure F-2

Referencing Two Resident Libraries

526

INTERLIBRARY CALLS
One library can call another library
FORRES calls FCSRES
To build libraries with interlibrary calls, use any of
techniques.

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.
•

specifying

only

referenced
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:[I,I]F4POTS/LIBRARY
Option? STACK=0
Option? PAR=F4PRES:120000:60000
Option? <RET>
Referencing task
is created
reference the library F4PRES.

527

using

normal

procedure

PHYSICAL

MEMORY

VIRTUAL

MEMORY

/,....-

,.,."""

,....-/'

,.,."'"
F4PRES
- (FCSRES)

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

F4PRES
, (FCSRES)

140000 APR6

"'"

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

528

Example task-build commands for building one library, then
building the second (referencing) library (Figure F-4):
>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,1]F4POTS/LIBRARY
Option? STACK=0
Option? LIBR=FCSRES:RO
Option? PAR=F4PRES:140000:40000
Option? <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.

529

PHYSICAL
MEMORY

VIRTUAL
MEMORY
160000

APR 7

F4PRES

....

(8K WORDS)
140000

APR 6
FCSRES

120000

APR 5

100000

APR 4

60000

APR 3

40000

APR 2

20000

APR 1

APR 0

(4K WORDS)

------

--------

FCSRES

-----USER
(12K WORDS)

USER

------TK-7771

Figure F-4

Building One Library, Then Building
a Referencing Library

530

...

FCSl

FCS2

.OPEN::

.GET::

USER

F4PCLS

.FSRPT::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
RSX-llM/M-PLUS Task
all
Interlibrary
References)
in
the
See
Builder Manual for a9ditional
information on revectoring.
task-build
commands
also Section 5.2.3 on Examples for commented
for building libraries with revectoring.

531

Example task-build commands when revectoring are 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=.CSII
Option? GBLREF=.CSI2

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

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

532

normal

procedure

PHYSICAL
MEMORY

VIRTUAL
MEMORY

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

,...- ,...-

...-

-~-- ----==--TiME~
----

F4PCLS

160000 APR7

140000 APR6

F4PCLS
(8K WORDS)

~
1-----_-----+lE::::::'":::::
_1'ME 2

120000 APR5

100000 APR4

....

FCS2

FCS1

----

60000 APR3

40000 APR2

20000 APRl

.-~

USER
(12K WORDS)

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

INITIAL
_LOAD AND MAP

...

USER

--- --

TK-7775

Figure F-6

Using Revectoring When Referencing Library Has Overlays

533

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>

534

the

PHYSICAL
MEMORY

F4PCLS

VIRTUAL
MEMORY

./
160000

APR7

140000

APR6

F4PCLS FMSCLS
f- (8K)
(8K)

~UNUSED~
FCS11 FCS2
(4K) (4K)

APR5 f-

100000

APR4 f-

I\.

APR3

40000

APR2

20000

APR1

APRO

140000

APR6

120000

APR5

100000

APR4

60000

APR3

40000

APR2

20000

APR1

F4PCLS FMSCL
(8K)
(8K)

--- --FMSCLS

TASK

FCS2

TASK
60000

APR7

FMSCLS

UNUSED~

120000

160000

F4PCLS

(22K WORDS)

FCS2

(22K WORDS)
FCS1

FCS1

'\ ,

o APRO
'\

TASK

\
\

TK-781S

Figure F-7

Cluster Libraries (Sheet 1 of 2)

535

PHYSICAL
MEMORY

F4PCLS

VIRTUAL
MEMORY

F4PCLS

VIRTUAL
MEMORY

aaUNUSED :?di
160000 APR7

£4PCLS FMSCLS
(8K)
(BK)

140000 APR6

FCSl
(4K)

160000 APR7

FCS2 '\
(4K)
FMSCLS

FMSCLS

UNUSED~

120000 APR5

....

100000 APR4

100000 APR4
TASK

60000 APR3 f-

120000 APR5

(22K WORDS)

40000 APR2 f-

20000 APRl

TASK

FCS2
60000 APR3
FCSl

FCS2

(22K WORDS)

FCSl

40000 APR2

20000 APRl

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

o APRO

'\
TASK

TASK

\
\

Figure F-7

Cluster Libraries (Sheet 2 of 2)

536

APPENDIX G
ADDITIONAL EXAMPLES
The f~llowing examples should be available on-line, probably
under UFD
[202,1].
They are needed for the Tests/Exercises.
Therefore, they are listed here in case --they are not available
on-line at your site.
.TITLE
.IDENT
.ENABL

:I.
·7
.....

4
5

F<EADF
/0:1./

Enable lower case

File READF.MAC

This task starts up, sets event fla~ 1, reads the
event fla~s, moves them into re~isters RO-R3 and then
exits. It uses the' form of the directive calls.

7
8
9
:1.0
l.:t.
12
:1.3
14
:1.5
:L6

Tht~~

f 1. iSSS; are

event flass 1-16
worr..i 0
word 1 .. event fla!~s :I. 7~-32
'")
._. event fla~s 3:3·-48
wCH'd .:-.
word :~ _.. eVf:nt flass 4 (j>-f.) 4
bit set m€~ans) fla£~ is s~~t ,
bit c 1 E~~H' ITleans f I c~~j :i.s clf.~ar
.~.

:I.?

18
:L ~}
20
2:1.

as follows:

T'C:.~turned

!I .•~

.MCALL

RDAF.,SETF.,EXIT.S,DIR.;

BUFF:

.BLKW

Buffer for event flaS

READ:

fUtAF$

BUFF

DPB for Read All Event
FlaSs di rectivf?

SETF:

SETF.

STAf~T:

CL.J:~

DIF~!~

:JI:SETF

BCS
DIR.

ERR:t.
tREAD

BCS
MOV
MOV
MOV
MOV
lOT

BUFF,RO
BUFF+2,R1
BUFF+4,R2
BUFF+6,R3

S~stem

macros

val,-,(.~s

26
2?
2B

DPB for Set Event Flas
directive

29
~5()

:H
32
3:~

34
35
36
37
:~8

39
40
41
42

E~~1~2

Clear error counter
Set event flag 1
Branch on dir error
Read the event flass
(1 - 64).
Branch on dir error
Move the event flag
vallJes into the
registf.~rs

Trap and displaw
registers

4~5

44
45

46
47
48

; Come here on directive errors
ERR2:
INC
R4
ERR1:
INC
R4

MOV

$[tSW"RO

rOT

50
51

Example G-l

.END

R4=2 for read error
R4=1 for set event
flag error'
Error code into RO
Trap and displa~ the
reSisters

START

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

.TITLE
.IDENT
+ENABL

2
3
4

csr
lOti

; Enable lower case

I...C

6
7

CSI illustrates the use of the command strins
interpreter. This task accepts a command line from the
terminal in the form:

B
9

dev:Cx,wJfilename.filetwpe;version/switch

where switch can be:

12
13
14

DE - Delete file
DI:N - Displaw N copies of file
+MCALL
+MCALL
.MCALL
+MCALL
+MCALL

GCMI...BS,GCMLS,CSIS,CSrS1,CSIS2
CSISSV,CSISSW,CSISND
FSRSZS,FDBDFS,FDRCSA,FDOPSA,FINITS
QIOWSS,QIOWS,DIRS,EXITSS
DELETS,OPENSR,OPENSW,GETS,PUTS,CLOSE$

.NLIST

BEX

22
23
24

LOCAL DATA

15
16

17
1B
:1.9

TYPE1:
TYPE2:
TYPE:~ :
TYPE4:
ERR1:

30
31

ERR2:

27
2B

~52
3~:S

34
35
:~6
~37

38
39

40
41
42
4~5

44
45
46

IO.WVB,5,1",,<ERR1,SIZ1,40)
IO+WVB,5,1",,<ERR2,SIZ2,40)
IO.WVB,5,l",,<ERR3,SIZ3,40)
IO.WVB,5,1",,<ERR4,SIZ4,40)
IGET COMMAND LINE ERROR/

SIZ1:::.··-EJ~F~1

.ASCII ICSI ERROR. ILLEGAL COMMANDI
SIZ2::::. ··.. EliR::!
+ASCII ICaI ERROR. FILE SPEC ERRORI
S I Z3::: + "-ERF~~3
ERR4:
.ASCII IERROR PERFORMING TASKI
SIZ4~"::. --ERli4
BUFF:
• BLKB
100 +
()ut~":.out t€-~xt buff~~ r
TBUFF:
+BLKB
132.
; Transfer buffer
FMT:
.ASCrZ IYOU HAVE REQUESTED A %7A JOBI
+EVEN
DATA:
.WORD 0
; Arsument block
DELTXT: +ASCII IDELETE/<O)
; ASCII text
TYTXT: .ASCII ITYPE/<O)<O)<O)
NOTXT: • ASC I I INOTH I NGI
+EVEN

48
49

arows
aIOW$
aIOWS
aIOW$
+ASCII

CBLK:

CSIS
+BLKB
.EVEN

C.SIZE

Define CSI offsets
allocate CSI storase

!:50

DEMSK ..- 1
DIMSK :::: 2

Delete IT,a~~k
Di SF' I iS~~

mi:~~;k

Example G-2

Using the Routines GCML and CSI (for Exercise 10-6)
(Sheet 1 of 3)

538

SWTBl:
CSI'SW
CSI'SW

55
56

DE,DEMSK
DI,DIMSK""NUM

CSI'ND

58
59
60
61

CSI'SV

63
64
65
66

CSI.ND

Switch descriptor table
Delete switch = DE
Display 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
End of switch value
table

;GET COMMAND lINE BLOCK DEFINITIONS

FSRSZ'

GCML uses record 1/0

GBLK:

GCMlB'

,CSI,,5

FDB:

FDBDF$

Prompt with 'CSI' on
LUN 5
FDB for file to delete
or display~
URB AT TBUFF, len~th
132.
LUN 1, dataset
descriptor from CSI

68
69
70
71
72
73

74
75
FDOP.A

76
77

1,CBlKtC.DSDS

78
NOTE: Need a 2nd FDB for displaw

80
81
82
83
84

.EVEN
JMPTBl: .WORD

NONE,DElETE,DISPlY

86
87
88
89
90

COpy:

.WORD
0
.ENABLE LSB

Value for N in IDI:N

START:

FINIT'

Initialize FCS, this
is normall~ done with
an OPEN statement.
For delete we do net
need an open statement.
Prompt and set command
Branch if command OK

92
93
94
95

96
97

98
99
100
101
102
103
104
105
106
107

~ Jump table for
subroutines dependin~
on switches

GCML'
BCC
; Check for ~Z.
CMPB
BNE
EXITSS
REALER: DIR'
EXIT'S
~

Parse input for illeSal characters

10$:

108
109
110

Example G-2

#GBLK
10'
If ~z, exit.
iGE.EOF,GBLKtG.ERR; Is it -Z1
REALER
Branch on other error
EXIt
tTYPEl
Display error text for
set command line error
Exit

CSI'l

tCBLK,GBLKfG.CMLDf2,GBLK+G.CMLD ; Format
is CSI addr, addr of
command, lensth of
command

Using the Routines GCML and CSI (for Exercise 10-6)
(Sheet 2 of 3)

539

:I. :I. :1.

Bce

:1.12

D:r I:~~~

LI. 3
LI.4

.EXIT$S

20$
:If:TYF'E2

Branch on OK command
Displa~ error text ~or
ill e!=.i«31. cOlTlmand
E~·dt

:1.15
116
:L 17
:1. :l. fJ
:1.1.9

Create a dataset descriptor
20$:

the

~rom

C81$2

ICBLKvOUTPUTvlSWTBL
30$
:U:TYPE3

:l.20

BCC

1.2:1.

DIF~~;

1 ':>':>
:L2:3

EX1T$~)

~ile

specification

~ Expect output file
; s}~'f.·~c
Branch on file spec OK
Displa~ text for file

:1.24
:l.2~)

; Call the appropriate subroutine

126
:1.27
128
1.29
130

MOV

:Jl:FDB,I/=i:O

Adf.".i T'(::~S~:; c)f f :i.l (:~
d f:~~:; C T' if':' t (J T'

MOV

CBI... K+C + MI\W:1. v I:~:I.

ASL

CALI...
BR

@JMPTBL(R:I.)
NEXT

Mask value = 0, 1, or 2
Double for word offset
i ntc) ,jUITIP tab 1. (:~
Call the subroutine
Get next comlTland line

:1.31

132
:1.:33
:I.~54
:L3~::i

Subroutine NONE, entered if no switches specified

:1.:36

:1.37

NONE!

MOV

S(·:~t

:Jl:NOTXT v D(.rrl~

1.:38
1.3(Y

I..tP fo T'

out}~ut

ITIE~~:;sa~~~f.~

Common

140
1.41

142
:1.43
:1.44

CH.JTM:

displa~

MOV
MOl,,'
MOl,,'
CALI...

14~5

(~I ()W~;~)

1.46
1.4'1

messsSe cDde
:II:BUFF, I:~O
:U:Ft1T, H:I.
:If:DATA!I F~2

Set UP for $EDMSG

$EDMSG

Edit messaSe

IIO.WVB,IS,I:I.",,<IBUFF,Rl,140>

I:;:ETUF~N

:1.48
:1.49

Subroutine DELETE - Just

displa~

a messaSe

:/. ~i()

:I. ~7j :I.

DELETE: MOl"l

:If:DELTXT!I DI~TI~

:I.~::;2

:L ~)~5

Br~

OUTM

:1.54
:I.~5b

; Subroutine DISF'LY - Just

:L ~5'1
:l.5B

DIBPI... Y: MOV

159
:r. f.)()

displa~

ITYTXTvDATA

Set UP for output of

OUTM

Branch to common
d :i. ~:;p 1. a~~ cc)cf(~~

tEND

STAr~T

mE) !:; ~5 a ~:.{ (~)

:1.6:1.
:l.b2

Example G-2

Set UP for output of
IT! C-? ~; ~:; a ~.t f:')
BT'«3nch tC) CC)ITIITIOn
d:i ~:;P 1 a~:~ cod(·:~

Using the Routines GCML and CSI (for Exercise 10-6)
(Sheet 3 of 3)

540

APPENDIX H
LEARNING ACTIVITY ANSWER SHEET
Learning Activity 2-1 (Directives)
1.

Either: a) Do some work, then check the flag by using the
CLEF$ 35. 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 check 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.

541

Learning Activity 6-1 (Overlays)
1.

• ROOT-* ! (P, Q)
.END

LINK/MAP ROOT,P,Q

Learning Activity 6-2
1.

Di ag ram

JOB1
I

JOBXX
I
I
A

I
I
TOTAL
I
MAIN

2 • • ROOT MAIN-TOTAL-*(A-(JOB1,JOBXX) ,B)
.END
3 • • ROOT MAIN-TOTAL-*! (A-! (JOB1,JOBXX) ,B)
.END

4 • • ROOT MAIN-TOTAL-*! (A-(JOB1,JOBXX) ,B)
.END

542

Learning Activity 10-1 (File Control Services)
Wi thout a User Record buffer (no spanning of blocks):
FDBDF$
FDRC$A
FDOP$A
DFNB: NMBLK$

FD. PLC
I,DFNB
YOURS,MAC

;
;

Use locate mode
Use LUN 1, default name block
File Spec

With a User Record Buffer
FDBDF$
FDRC$A

FDOP$A
DFNB: NMBLK$

FD.PLC,URB,80.; 80.= maximum record size,
Record size can be checked after
; the file is opened as well.
I,DFNB
YOURS.MAC

You can use a dataset descriptor as well.
If you use a default name block to specify TI:, use:
NMBLK$ ",TI,0

543

GLOSSARY

GLOSSARY
ASYNCHRONOUS SYSTEM TRAP (AST) - A system condition which occurs
as a
result of a
speclfled 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 library 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 FCS 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, FCS
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.
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.

547

GLOSSARY
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
Executjve, 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 ex i ting •

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, ~he 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
request to ind icate to the issuing task wh ich 0 f several spec if ied
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.
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.

548

GLOSSARY
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 Blo~k which
FCS uses for building, and later using, a file specification.
The filename block contains
the
file's
UFD,
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
bloc k.
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 b yt e 0 f the fir st wo r d con t a ins + 1 i f th e I/O wa s
s u c c e s sf u 1 ,
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.
LOGICAL BLOCK - A 512(10) byte (256(10) word)
block addressable volume.

block of data

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.

549

GLOSSARY
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
vlrtual blocks) are specified by record (or virtual block) number.
Under FCS, a file must be organized into fixed length
order for a task to do random access 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 r:gion may be name~ or unnamed, but is always assigned a unique
reglon ID.
A reglon 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.
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 " so ftware inter r upt"
whi ch
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 th~ task.

550

GLOSSARY
VIRTUAL ADDRESS - A 16-bit address which may be directly specified
uSIng one of the general purpose registers.
uses one of the
A task specifies a virtual address whenever it
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 (WDB) - A data structure used in a task in
order to represent a dynamIcally created window.

551