Digital PDFs

AA-M176A-TC

November 1981

270 pages

Original

11MB

Document:	IAS/RSX-11 I/0 Operations Reference Manual
Order Number:	AA-M176A-TC
Revision:	0
Pages:	270
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V4.1_Apr83/4_ProgramDevelopment/AA-M176A-TC_ioOper_198111.pdf

OCR Text

IAS/RSX-11
1/0 Operations Reference Manual
Oidei No. AA-M176A-TC

RSX-11 M Version 4.0
RSX-11 M-PLUS Version 2.0
IAS Version 3.1

digital equipment corporation . maynard, massachusetts

First Printing, December
Revised, December
Revised, December
Revised, June
Revised, November

1975
1976
1977
1979
1981

The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may be used or copied only in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by Digital Equipment Corporation or its
-~~~,~-~-~
dJ.J.J..1.J.dl..t::U

------:--

1,.;v111pa11.1.t::o::i.

Copy r i g ht @ 1 9 7 5 , 19 7 6 , 1977 , 197 9 , 1981
by Digital Equipment Corporation
All Rights Reserved.

Printed in U.S.A.

The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future
documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DECnet
DECsystem-IO
DECSYSTEM-20
DEC US
DECwriter
DIBOL

EduSystem
IAS
MASS BUS
PDP
PDT
RSTS

RSX
UNIBUS
VAX
VMS

ZK2058

CONTENTS

Page
PREFACE

SUMMARY OF TECHNICAL CHANGES
CHAPTER 1
1.1
l. 2
1. 3
1. 3 .1
1. 4
1. 5
1. 6
1. 6.1
, ,.. '"'
.1. • 0 • L

1. 7
1.8
1. 9
1.10
1.11
1.12
CHAPTER 2

xiii

FILE CONTROL SERVICES
FILE ACCESS METHODS
FILE STORAGE REGION (FSR)
DATA FORMATS FOR FILE-STRUCTURED DEVICES •
Data Formats for ANSI Magtape
BLOCK I/O OPERATIONS • • • • • • • • •
RECORD I/O OPERATIONS
• • •
DATA-TRANSFER MODES
Move Mode
Locate Mode
• • • •
MULTIPLE BUFFERING FOR RECORD I/O
SHARED ACCESS TO FILES • • • •
FILE DESCRIPTOR BLOCK (FDB)
••••
DATASET DESCRIPTOR AND DEFAULT FILENAME BLOCK
KEY TERMS USED THROUGHOUT THIS MANUAL
SYSTEM CHARACTERISTICS • • • • • • • • • • • •

•
•
•

•

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

PREPARING FOR I/O

.MCALL DIRECTIVE - LISTING NAMES OF REQUIRED MACRO
DEFINITIONS
• • • • • • • • • • • • • • • • 2-2
2.2
FI LE DESCRIPTOR BLOCK {FDB)
• • • • • • • •
2-3
2.2.1
Assembly-Time FDB Initialization Macros
• • • • 2-3
2.2.1.1
FDBDF$ - Allocate File Descriptor Block (FDB)
2-5
2.2.1.2
FDAT$A - Initialize File Attribute Section
of
FDB • • • • • • • • • • • • • • • • • • • 2-5
2.2.1.3
FDRC$A - Initialize Record Access Section of
• 2-8
FDB
• • • • • • • • •
• • • •
2.2.1.4
FDBK$A - Initialize Block Access Section of
FDB
• • • • • • • • • • • • • • • • • •
2-10
2.2.1.5
FDOP$A - Initialize File-Open Section of FDB 2-13
2.2.i.6
FDBF$A - Initialize Block Buffer Section of
FDB
• • • • • • • • • • • • • • • • • • • •
2-1 7
2.2.2
Run-Time FDB Initialization Macros •
2-21
2.2.2.1
Run-Time FDB Macro-Call Exceptions
2-21
2.2.2.2
Specifying the FDB Address
in Run-Time
2-24
Macro Calls
• • • • • • • • • • • • • • • •
2.3
GLOBAL VERSUS LOCAL DEFINITIONS FOR FDB OFFSETS
2-25
2.3.1
Specifying Global Symbols in the Source Coding 2-25
2.3.2
Defining FDB Offsets and Bit Values Locally
2-26
2.4
CREATING FILE SPECIFICATIONS WITHIN THE USER
2-26
PROGRAM
• • • • • • • • • • •
2.4.1
Dataset Descriptor
2-28
2.1

iii

CONTENTS

Page
2.4.2
2.4.3
2.5
2.5.1
2.5.2
2.6
2.6.1
2.6.2
2.7
2.7.1
2.7.2
2.8
2.8.1
2.8.2
2.8.3
CHAPTER 3

. . 2-30
2-33
. . . . . . . . . . . . . 2-33
2-34
............
.
2-35
2-36
....
.
2-37

Default Filename Block - NMBLK$ Macro Call
Dynamic Processing of File Specifications
OPTIMIZING FILE ACCESS
Initializing the Filename Block As a Function
of OPEN$x
Manually Initializing the Filename Block
INITIALIZING THE FILE STORAGE REGION
FSRSZ$ - Initialize FSR at Assembly Time
FIN IT$ - Initialize FSR at Run Time
INCREASING THE SIZE OF THE FILE STORAGE REGION
FSR-Extension Procedures for MACR0-11 Programs
FSR-Extension Procedures for FORTRAN Programs
COORDINATING I/O OPERATIONS
Event Flags
I/O Status Block
AST Service Routine

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

2-40
2-41
2-41
2-42
2-43
2-44

FILE-PROCESSING MACRO CALLS

. . . . . . . 3-2
. 3-5
3-8
. . . . . . . . . . . . . . . .. .. .. .. .. .. .3-12
. . . . 3-12
. . . . . . . . . . . . . . . . . . 3-13
3-14
.....
3-15
.....
3-16
. . . . . . . . . . . .. .. .. .. .. .. ..
3-16
. . . . 3-17
.........
3-18
. .. . .
3-i9
.
.
.
.
..
3-19
.....
. . . . . . . . . . 3-20
3-21
......
3-22
3-22
.....

OPEN$X - GENERALIZED OPEN MACRO CALL
Format of Generalized OPEN$x Macro Call
FOB Requirements for Generalized OPEN$x Macro
Call
OPNS$X - OPEN FILE FOR SHARED ACCESS
3.2
3.3
OPNT$W - CREATE AND OPEN TEMPORARY FILE
3.4
OPNT$D - CREATE AND OPEN TEMPORARY FILE AND MARK
FOR DELETION
OFID$X - OPEN FILE BY FILE ID
3.5
OFNB$X OPEN FILE BY FILENAME BLOCK
3.6
Dataset Descriptor and/or Default Filename
3.6.1
Block
3.6.2
Default filename Block Only
OPEN$ - GENERALIZED OPEN FOR SPECIFYING FILE
3.7
ACCESS
CLOSE$ - CLOSE SPECIFIED FILE
3.8
3.8.1
Format of CLOSE$ Macro Call
GET$ - READ LOGICAL RECORD
3.9
3.9.1
Format of GET$ Macro Call
FOB Mechanics Relevant to GETS Operations
3.9.2
GET$ Operations in Move Mode
3.9.2.1
3.9.2.2
GET$ Operations in Locate Mode
3.10
GET$R - READ LOGICAL RECORD IN RANDOM MODE
3 .11
GET$S - READ LOGICAL RECORD IN SEQUENTIAL MODE
3.12
PUT$ - WRITE LOGICAL RECORD
3.12.1
Format of PUT$ Macro Call
3.12.2
FOB Mechanics Relevant to PUT$ Operations
3.12.2.1
PUT$ Operations in Move Mode
3.12.2.2
PUT$ Operations in Locate Mode
3 .13
PUT$R - WRITE LOGICAL RECORD IN RANDOM MODE
3.14
PUT$S - WRITE LOGICAL RECORD IN SEQUENTIAL MODE
3.15
READ$ - READ VIRTUAL BLOCK
3.15.1
Format of READ$ Macro Call
3.15.2
FOB Requirements for READ$ Macro Call
3.16
WRITE$ - WRITE VIRTUAL BLOCK
3.16.1
Format of WRITE$ Macro Call
3 .. 16 .. 2
FDB Requirements for WRITE$ Macro Call
3.17
WAIT$ - WAIT FOR BLOCK I/O COMPLETION
3.17.1
Format of WAIT$ Macro Call
3.18
DE LET$ - DELETE SPECIFIED FILE
3.18.1
Format of DELET$ Macro Call

3.1
3 .1.1
3.1. 2

2-39

. 2-40

. . 3-23
3-25
.. .. .. .. .. ..
3-25
3-26
3-27
. .. .. .. .. ..
3-27
3-28
3-29

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

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

3-31
3-31
3-32
3-35
3-35
3-35
3-36
3-36
3-37
3-39
3-39

CONTENTS
Page
CHAPTER 4
4.1
4.2
4.2.1
4.2.2
4.3
4.3.1
4.3.2
4.4
4.4.1

FILE CONTROL ROUTINES
CALLING FILE CONTROL ROUTINES • • • • •
DEFAULT DIRECTORY-STRING ROUTINES
.RDFDR - Read $$FSR2 Default Directory String
Descriptor • • • • • • • • • • • • • •
.WDFDR - Write New $$FSR2 Default
Directory-String Descriptor • • • •
•
DEFAULT UIC ROUTINES • • • • •
•
• RDFUI - Read Default UIC • • • •
. . . .
•
.WDFUI - Write Default UIC • • • • • •
DEFAULT FILE-PROTECTION WORD ROUTINES
.RDFFP - Read $$FSR2 Default File Protection

• 4-1
• 4-2
• 4-2
•
•
.
•
•

4-3
4-4
4-4
4-4
4-4

• 4-5
• • • • • • • • • • • • • • • •
.WDFFP - Write New $$FSR2 Default
File-Protection Word • • • • • • • • • • • • • • 4-5
4.5
FILE OWNER WORD ROUTINES • • • • • •
• • 4-5
~RFOWN - Read $$FSR2 File Owner Word •
• • 4-6
4.5.1
.WFOWN - Write New $$FSR2 File Owner Word • • • 4-6
4.5.2
ASCII/BINARY UIC CONVERSION ROUTINES • • • • • • • 4-7
4.6
4.6.1
.ASCPP - Convert ASCII Directory String to
Equivalent Binary UIC • • • • • • • • • • • • • 4-7
4.6.2
.PPASC - Convert UIC to ASCII Directory String • 4-7
4.7
FILENAME BLOCK ROUTINES • • • • • • • • • •
4-7
.PARSE - Fill in All Filename Information • • • 4-8
4.7.1
Device and Unit Information • • • • •
• 4-9
4.7.1.1
4.7.1.2
Directory Identification Information •
4-10
File Name, File Type or Extension, and File
4.7.1.3
4-11
Version Information • • • • • • • • •
4.7.1.4
Other Filename Block Information • • •
4-11
4.7.2
.PRSDV - Fill in Device and Unit Information
On 1 y • • • • • • • • • • • • • • • • • • .. .. .. 4 -1 2
4.7.3
.PRSDI - Fill in Directory Identification
Information Only • • • • • • • • • • • • •
4-12
.PRSFN - Fill in File name, File Type or
4.7.4
Extension, and File Version Only • • •
4-12
.ASLUN - Assign Logical Unit Number
4-12
4.7.5
4-13
DIRECTORY ENTRY ROUTINES • • • • • •
4.8
4-13
.FIND - Locate Directory Entry ••
4.8.1
4-15
4.8.2
.ENTER - Insert Directory Entry
4-16
.REMOV - Delete Directory Entry
4.8.3
4.9
FILENAME BLOCK ROUTINES • • • • • • • • • • • • 4-16
4.9.1
.GTDIR - Insert Directory Information in
Filename Block • • • • • • • • • • • • • •
4-16
4.9.2
.GTDID - Insert Default Directory Information
in Filename Block
• • • • • • • • • •
4-17
4.10
FILE POINTER ROUTINES • • • • • • • • • • •
4-17
4.10.1
.POINT - Position File to Specified Byte •
4-18
.POSRC - Position File to Specified Record
4-19
4.10.2
.MARK - Save Positional Context of File
4-19
4.10.3
.. POSIT - Return Positional Information for
4 .. 10 .. 4
Specified Record • • • • • • • •
4-20
QUEUE I/O FUNCTION ROUTINE (.XQIO) • • • • •
4-20
4.11
RENAME FILE ROUTINE (.RENAM) • • • • • • • •
4-20
4.12
FILE EXTENSION ROUTINE (.EXTND)
4-21
4 .13
FILE TRUNCATION ROUTINE (.TRNCL)
4-22
4.14
4.15
FILE DELETION ROUTINES • • • • • •
4-22
.MRKDL - Mark Temporary File for Deletion
4-23
4.15.1
.DLFNB - Delete File by Filename Block
4-24
4.15.2
4.16
DEVICE CONTROL ROUTINE (.CTRL) • • • • • • •
4-25
Word

4.4.2

CONTENTS
Page
CHAPTER 5

FILE STRUCTURES

5.1
DISK AND DECTAPE FILE STRUCTURE (FILES-11)
•
User File Structure
••••••••••••
5.1.1
5.1. 2
Directory Files
• • • • • • • •
• ••••
5.1.3
Index File • • • • •
• • • • • • • • • •
5.1. 4
File Header Block
••
5.2
MAGNETIC TAPE FILE PROCESSING
• • • • •
5.2.1
Access to Magnetic Tape Volumes
• •
5.2.2
Rewinding Volume Sets
••••••••
5.2.3
Positioning to the Next File Position
••
5.2.4
Single-File Operations • • •
• • • •
• ••
5.2.5
Multiple-File Operations • • • • • • • •
• •
5.2.6
Using .CTRL • • • • • • • • • • • • • • • • • •
5.2.7
Examples of Magnetic Tape Processing •
•
5.2.7.1
Examples of OPEN$W to Create a New File • • •
5.2.7.2
Examples of OPEN$R to Read a File
•••
5.2.7.3
Examples of CLOSE$ •
• • • • • •
5.2.7.4
Combined Examples of OPEN$ and CLOSE$ for
Magnetic Tape
. • • • • • • •
CHAPTER 6

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

COMMAND LINE PROCESSING

6.1
6.1. l

GET COMMAND LINE (GCML)
• • • • • • • • • • • • • 6-2
GCMLB$ - Allocate and Initialize GCML Control
Block
. . . . . . . . . . .
. . . . .
• 6-3
6.1. 2
GCMLD$ - Define GCML Control Block Off sets and
Bit Values • • • • • • • •
• •••
• 6-6
6.1. 3
GCML Run-Time Macro Calls
• • • • •
• 6-9
6.1.3.1
GCML$ - Get Command Line
• • • • • • • 6-10
6.1.3.2
RCML$ - Reset Indirect Command File Scan
6-12
6.1.3.3
CCML$ - Close Current Command File • • • • •
6-12
6.1. 4
6-13
GCML Usage Considerations
• • • • • • • •
6.2
COMMAND STRING INTERPRETER (CS!) • • • . • • • • 6-14
6.2.1
CSI$ - Define CS! Control Block Offsets and Bit
TT-,

a"" -

vaiu~~

6.2.2
6.2.3
6.2.3.1
6.2.3.2
6.2.4
6.2.4.1
6.2.4.2
6.2.4.3
CHAPTER 7

•••••••••

•

CSI Control Block Offset and Bit Value
Definitions
• • • • • •
CSI Run-Time Macro Calls
CSI$1 - Command Syntax Analyzer
• • • •
CSI$2 - Command Semantic Parser
CS! Switch Definition Macro Calls
CSI$SW - Create Switch Descriptor Table Entry
CSI$SV - Create Switch Value Descriptor Table
Entry • • • • • • • • • • • • • • • • •
CSI$ND - Define End of Descriptor Table

t: _, c
v -~_,

6-15
6-19
6-19
6-20
6-22
6-23
6-28
6-30

THE TABLE-DRIVEN PARSER (TPARS)

7.1
CODING TPARS SOURCE PROGRAMS • • • • • • • •
7 .1.1
TPARS Macros: !STAT$, STATE$, and TRAN$ • • • •
7.1.1.1
Initializing the State Table: the !STAT$ Macro
7.1.1.2
Defining a Syntax Element: the STATE$ Macro
•
7.1.1.3
Defining a Transition: the $TRAN Macro •
•
7 .1. 2
Types of Command Line Syntax Elements
7 .. 1 .. 3
Action Routines and Built-in Variables
•
7.1.3.1
TPARS Built-in Variables • • • • • •
7.1.3.2
Calling Action Routines
• • • • • •
• ••
Using Action Routines to Reject a
7.1.3.3
Transition • • • • • •
• • • • •
• •
7.1.3.4
Optional Debug Routine for RSX-11 Users
•

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

CONTENTS
Page
7 .1. 4

7.2
7.2.1
7.2.2
7.2.3
7.2.4
7.3
7.4
7.4.1
7.4.2
7.5

7.6
7.n.l
7.6.2
7.6.3
CHAPTER 8
8.1
8.2
8.3

TPARS Subexpressions • • • • • • • • • • •
7-7
GENERAL CODING CONSIDERATIONS • • • • • • •
7-8
Suggested Arrangement of Syntax Types in a State
Table • • • • • • • • • • • • • • • • • • • • • 7-8
Ignoring Blanks and Tabs in a Command Line • • • 7-8
Entering Special Characters • • • • •
• 7-9
Recognition of Keywords • • • • • • •
• • 7-9
PSECTS GENERATED BY TPARS MACROS • • • • • • • • 7-10
INVOKING TPARS • • • • • • • • • • • • •
7-11
Register Usage and Calling Conventions •
7-12
Using the Options Word • • • • • • • • • • • • 7-12
HOW TO GENERATE A PARSER PROGRAM USING TPARS • • 7-14
PROGRAMMING EXAMPLES • • • • • •
7-15
Parsing a UFD Command Line • •
• • • • • 7-15
How to Use Subexpressions and Reject
Transitions • • • • • • • • • • • • • • • • • 7-18
Using Subexpressions to Parse Complex Grammars 7-19
SPOOLING
• 8-1
• 8-2
• 8-2

PRINT$ MACRO CALL • • • • • • •
.PRINT SUBROUTINE
ERROR HANDLING • • •

APPENDIX A

FILE DESCRIPTOR BLOCK

APPENDIX B

FILENAME BLOCK

APPENDIX C

SUMMARY OF I/0-RELATED SYSTEM DIRECTIVES

APPENDIX D

SAMPLE PROGRAMS

APPENDIX E

INDEX FILE FORMAT

E.l
E.2
E.3
E.4
APPENDIX F

BOOTSTRAP BLOCK • • • • • • • • • • • • • • • • • E-1
HOME BLOCK
• • • • • • • • • E-2
INDEX FILE BIT MAP •
• • • • • • • • • •
E-2
PREDEFINED FILE HEADER BLOCKS
• E-2
FILE HEADER BLOCK FORMAT

F.l
F.2

HEADER AREA • • • •
IDENTIFICATION AREA

F:3

MAP ARE.A "

APPENDIX G

• • • • • • • F-3

• • • • • • • F-4
F-5

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

VOLUME AND FILE LABELS • • • • • • • •
• G-1
Volume Label Format • • • • • • • •
• • • • G-1
Contents of Owner Identification Field •
• G-2
G.1.1.1
User Volume Labels • • • • •
• • • • • • • G-3
G. l. 2
File Header Labels • • • • •
• • • • G-3
G.1.3
File Identifier Processing by Files-11 •
• G-6
G.1.3.1
End-of-Volume Labels • • • • • • • • • • • • • • G-7
G. l. 4
File Trailer Labels • • • • • • • • • • • • • • G-7
G. l. 5
G.l

G.1.1

vii

Page
G. l. 6

G.2
G.2.1
G.2.2
G.2.3
G.2.4
G.3
G.4
G.5
G.6
G.6.1
G.6.2
G.6.3
G.6.4
G.7

User File Labels • • • • • • • • • • •
• • G-8
FILE STRUCTURES
• • • •
• • • • •
• • G-8
Single File Single Volume
• • • •
• • G-8
Single File Multivolume
• • • • • • • • • G-8
Multifile Single Volume
• • • • •
• • G-8
Multifile Multivolume
• • • • • • • • • • G-8
END-OF-TAPE HANDLING • • • • • • • •
• • • • G-9
ANSI MAGNETIC TAPE FILE HEADER BLOCK (FCS
• • G-9
COMPATIBLE)
• • • • • • • • •
G-10
THE MAGNETIC TAPE CONTROL TASK •
UNLABELED TAPE • • • • • • •
• • • • • • • • G-14
G-15
Tape Positioning • • • • • • • • • • •
Specifying File Attributes • • • • • • • • • • G-15
Translation • • • • • • • • •
• • • • • • G-15
G-16
Example of EBCDIC Translation Tables •
EXAMPLE USING AN INDIRECT COMMAND FILE TO READ A
G-17
TAPE • • • • • • • • • • • • • • • • •

APPENDIX H

STATISTICS BLOCK

APPENDIX I

ERROR CODES

APPENDIX J

FIELD SIZE SYMBOLS

APPENDIX K

RSX-llM/M-PLUS FCS LIBRARY SYSGEN OPTIONS

K.l
K.2

FCS LIBRARY OPTIONS
.FCTYP • • • • • • •

• K-1
• K-1
Index-I

INDEX

FIGURES
FIGURE

1-1
1-2
1-3
5-1
5-2
6-1
6-2
6-3
7-1
7-2
A-1
B-1
B-2
G-1
H-1

File-Access Operation • • • • • • • • • •
1-1
Record I/O Operations • • • • • • • • • • •
1-3
Single Buffering Versus Multiple Buffering • • • • 1-7
Directory Structure for Single-User Volumes • • • 5-2
Directory Structure for Multiuser Volumes
• • 5-3
Data Flow During Command Line Processing ••
• 6-2
Format of Switch Descriptor Table Entry
6-27
Format of Switch Value Descriptor Table Entry
6-29
Processing Steps Required to Generate a Parser
Program Using TPARS
• • • • • • • • •
7-13
Flow of Control When TPARS Is Called from an
Executing User Program • • • • • • • • • • •
7-14
File Descriptor Block Format • • • • • • • • • • • A-2
Filename Block Format • • • • • •
• • B-3
ANSI Filename Block Format • •
• • • • • B-5
ANSI Magnetic Tape File Header Block (FCS
Compatible)
• • • •
• • • •
• • G-9
Statistics Block Format
• • • •
• H-1

viii

CONTENTS
Page
TABLES
TABLE

1-1

2-1
3-1
4-1
A-1
B-1
B-2
B-3
C-1
E-1
F-1
G-1
G-2
G-3
G-4
K-1
K-2

Shared File Access • • • • • • • • • • • • • •
1-9
Macro Calls Generating FDB Information • • •
• 2-2
File Access Privileges Resulting from OPEN$x
Macro Call • • • • • •
• • • •
• • 3-3
R2 Control Bits for .EXTND Routine •
4-23
FDB Offset Definitions • • • • • • • •
• A-3
Filename Block Offset Definitions
• B-2
Filename Block Status Word (N.STAT)
• • • • • • • B-3
Filename Block Offset Definitions for ANSI
Magnetic Tape • • • • • • • • • • • • •
• • B-4
Summary of I/0-Related System Directives •
• C-1
Home Block Format
• • • • • • • • • • • E-3
Fi le Header Block
• • F-1
Volume Label Format • • • •
• G-1
File Header Label {HDRl)
G-4
File Header Format (HDR2)
• G-5
File-Header Label (HDR3) • • • •
• • • • • • • G-6
FCS Library Descriptions •
• • • • •
• • • K-1
.FCTYP Values • • • • •
• • • • •
• • K-2

PREFACE

MANUAL OBJECTIVES
The purpose of this manual is to familiarize the users of an RSX-llM,
RSX-llM-PLUS, or IAS operating system with the File Control Services
(FCS) facility provided with the system.

INTENDED AUDIENCE
Since the file control services described herein pertain to both
MACR0-11 and FORTRAN programs, the reader is assumed to be familiar
with the manuals describing these oroaram development tools.
Also,
since the development of programs in an RSX-11 or IAS environment
necessarily involves the use of the Task Builder, the reader is also
assumed to be familiar with this system program.

STRUCTURE OF THE DOCUMENT
Chapter 1 briefly describes the FCS features available for IAS/RSX-11
users and defines some of the terminology that is pertinent to
discussions throughout the manual.
This chapter is
vital
to
understanding the balance of the manual.
Chapter 2, perhaps the most important in the manual, describes the
actions you must take at assembly time to prepare adequately for all
intended file I/O processing through FCS. This chapter describes the
data structures and working storage areas that you must define within
a particular program in order to use any of the file control services
provided by the system. Unless you are thoroughly familiar with the
content of this chapter, you are advised to defer a reading of
subsequent chapters, since all that follows is dependent upon a
complete working understanding of the material in Chapter 2.
Chapter 3 describes the run-time macro calls
manipulate files and to perform I/O operations.

that

allow

you

Chapter 4 describes a set of run-time routines used to perform
functions related to controlling files, such as reading and writing
directory entries, renaming or extending files, and so forth.
Chapter 5 describes the structure of files supported by the IAS and
RSX-11 systems.
In this context, the structure of files for disks,
DECtapes, and magnetic tapes are covered.
Chapter 6 describes two collections of object library routines called
the Get Command Line (GCML) routine and the Command String Interpreter
(CSI). These routines may be linked with the user task to perform
operations associated with the dynamic input of command lines. Such
input consists of file specifications that identify and control the
files to be processed by the user program.
Chapter 7 describes the Table-Driven Parser
xi

(TPARS),

which

provides

PREFACE
you with the means
user-designed syntax.

define

and parse command lines in a unique

Chapter 8 describes the queuing of files for printing.
is available at both the MACRO and subroutine levels.

This

facility

Finally, a number of appendixes are provided that supply detailed
information of further interest. Appendix A and Appendix B outline in
detail the File Descriptor Block (FDB) and the filename block,
respectively, two structures forming a significant part of the
descriptive material in Chapter 2. Appendix C summarizes a number of
I/0-related system directives that form a part of the total resource
management capabilities of the RSX-11 or the IAS Executive.
Through
simplified sample programs, Appendix D illustrates the use of the
macro calls that create and initialize the FDB. These sample programs
also include some of the macro calls that are used for processing
files.
Appendix E illustrates the structure of the index file of a Files-11
volume, while Appendix F describes in detail the format and content of
a file header block. The format and content of magnetic tape labels
are similarly described in Appendix G. The format and content of the
statistics block are described in Appendix H.
The error codes returned by the system are listed in Appendix
field-size symbols are listed in Appendix J.
Appendix K lists RSX-llM/M-PLUS FCS library SYSGEN options,
a brief description of each.

and

including

ASSOCIATED DOCUMENTS
Other manuals closely allied to the purposes of this document are
described briefly in either the RSX-llM or RSX-llM-PLUS Information
Directory and Index. The information directories define the intended
readership--Of each manual in the appropriate set and provide a brief
synopsis of each manual's contents.

CONVENTIONS USED IN THIS DOCUMENT
Unless otherwise noted, the term "RSX-11" refers to both
RSX-llM-PLUS.

xii

RSX-llM

and

SUMMARY OF TECHNICAL CHANGES

This rev1s1on of the !AS/RSX I/O Operations Reference Manual
changes and additions relative to the following:
1.

contains

New FCS functions:
•

CLOSE$ - Truncates the file by default

REWIND -

•

PUT$ - Magtape enhancement

.POINT and .CTRL clear EOF condition

ANSI magtape level 3 compliance (See Appendix G):
•

The magnetic tape ACP now supports the ANSI header labels.

•

The magnetic tape ACP now supports 17-character file names
that include ANSI "a" characters.

An overlayed FCS resident library (FCSRES).

Support for unlabeled tape (See Appendix G).

The following changes to CSil and CSI2 (See Chapter 6):
•

The file name and extension may be replaced
string.

•

The device name may be logical queue name (PRINT:, BATCH:,
etc.) •

•

The file name may contain
(A*B%C*.T*).

•

Quotes may not be used as switch
them.

•

The version number is not completely validated.

•

The directory specification is validated by rules
to those used in VMS.

•

Longword number conversion f~ now supported, resulting
in
two words of number stored when two words are requested.

any

Big buffer support (See Chapter 1).

Multibuffering (See Chapter 1).

xiii

combination
values

quoted

wildcards

without

quoting

similar

CHAPTER 1
FILE CONTROL SERVICES

IAS and RSX-11 File Control Services
(FCS)
enable you to perform
record-oriented and block-oriented I/O operations, and to perform
additional functions required for file control, such as open, close,
wait, and delete operations.
To invoke FCS functions, you issue macro
calls to specify desired file control operations. The FCS macros are
called at assembly time to generate code for specified functions and
operations.
The macro calls provide the system-level, file control
primitives with the necessary parameters to perform the file access
operations that you request (see Figure 1-1).
FCS is basically a set of routines that are linked with the user
program at task-build time from a system global area (IAS) or resident
system library (RSX-11), or a system object module library.
These
routines, consisting of pure, position-independent code, provide an
interface to the file system, enabling you to read and write files on
file-structured devices and to process files
in terms of logical
records.
Logical records are regarded by your program as data units that are
structured in accordance with application requirements, rather than as
physical blocks of data on a particular storage medium.
FCS provides the capability to write a collection of data
(consisting
of distinct logical records) to a file in a way that enables the data
to be retrieved at will.
You can retrieve data from the file without
having to know the exact format in which it was written to the file.
FCS, therefore, is transparent to the user, so that records can be
read or written in logical units that are consistent with particular
application requirements.

USER-ISSUED MACRO CALL

FILE CONTROL SERVICES

FILE CONTROL PRIMITIVES

PERIPHERAL DEVICE HARDWARE
(e.g., disk, VT05)

ZK-290-81

Figure 1-1

File-Access Operation
1-1

FCS provides an extensive set of macros to simplify your interface to
the system's I/O facilities. In addition to generating calls to FCS
subroutines, these macros create and maintain certain data structures
that are required when performing any file I/O operations. The
required data structures include the following:
1.

A File Descriptor Block {FDB)
that contains information
necessary at execution time for processing the file.

A dataset descriptor that is accessed by FCS to obtain ASCII
file name information required when opening a specified file.

A default filename block that is accessed by FCS to obtain
default
file name information required when opening a
specified file.
This data structure is accessed
when
complete file information is not specified in the dataset
descriptor.

A file storage region {FSR) that is used by FCS
storage.

for

working

The FDB is described in detail in Appendix A and Appendix B.
The
dataset descriptor and the default filename block are described in
detail in Section 2.4. The FSR is described in Section 1.2.

1.1

FILE ACCESS METHODS

IAS and RSX-11 support both sequential and random access to data in
files on sequential access devices (such as magnetic tapes and card
readers) and random access devices {such as disks) •
The sequential
access method is device independent; that is, sequential access can
be used for both record-oriented and random access devices (for
example, card reader and disk, respectively). You can use the random
access method only for random access devices.

1.2

FILE STORAGE REGION (FSR)

The file storage region (FSR) is an area allocated in your program as
working storage for performing record I/O operations (see Section
1.5). The FSR consists of two program sections that are always
contiguous to each other.
These program sections exist for the
following purposes:
$$FSR1 - This area of the FSR contains the block buffers and the
block buffer headers for record I/O processing. You
determine the size of this area at assembly time by
issuing the FSRSZ$ macro call (see Section 2.6.1). The
number of block buffers and associated headers is based
on
the number of files that you intend to open
simultaneously for record I/O operations.
$$FSR2 - This area of the FSR contains impure data that is used
and maintained by FCS when performing both record and
block I/O operations.
Portions of this area
are
initialized at task-build time, whereas other portions
are maintained by FCS.

1-2

FILE CONTROL SERVICES
The size of the FSR can be changed, if desired, at task-build time.
Section 2.7 presents the procedures that provide you with this
flexibility.
The data flow during record I/O operations is depicted in Figure 1-2.
Note that blocks of data are transferred directly between the FSR
block buffer and the device containing the desired file.
The
deblocking of records during input is accomplished in the FSR block
buffer, and the blocking of records is similarly accomplished in the
FSR block buffer during output. Note also that FCS serves as your
interface to the FSR-block-buffer pool. All record I/O operations,
which are initiated through GET$ and PUT$ macro calls, are totally
synchronized by FCS unless multibuffering is in use.
Record I/O operations are described in detail in Section 1.5.

BLOCK
BUFFER
POOL

FCS

DEVICE

USER
RECORD
BUFFER

LJ
$$FSR2
IMPURE DATA

ZK-291-81

Figure 1-2

1.3

Record I/O Operations

DATA FORMATS FOR FILE-STRUCTURED DEVICES

Data is transferred between peripheral devices and memory in blocks.
A data file consists of virtual blocks, each of which may contain one
or more logical records created by your program.
In FCS terms, a
virtual block in a file consists of 512(decimal) bytes for random
access devices. The size of the logical records in the virtual blocks
is under the control of the user program that originally wrote the
records.
When creating a new file, your program can specify that the records in
the file need not all be the same size. Such records are known as

1-3

PILE CONTROL SERVICES
variable-length records. Conversely, if your program indicates that
all records in the new file will be equal in size, the records are
known as fixed length.
There are two types of variable-length records:
sequenced and
nonsequenced.
Both must be word aligned. Sequenced variable-length
records are preceded by a 2-word record header.
The first word
contains the length of the record, and the second word contains the
value of the sequence number:
16

Byte Count

Sequence Number

\ n-2

Nonsequenced variable-length records are preceded
record header containing the length of the record:

byte;~
by

single-word

'---B_y_t_e~c_o_u_n~t~~~~~...__~-n~b_y_t_e--is;~
Both fixed- and variable-length records are aligned on a word
boundary.
Any extra byte that results from an odd-length record is
simply ignored.
(The extra byte is not necessarily a 0 byte.)
Virtual blocks and logical records within a file are numbered
sequentially, each starting at 1. A virtual block number is a file
relative value, whereas a logical block number is a volume relative
value.
Ordinarily, records may cross block boundaries. This means
that the beginning of a record can fill out the end of a block, while
the rest of the record occupies the beginning of the next block.

1.3.1

Data Formats for ANSI Magtape

You can use both fixed- and variable-length records on magtape;
format conforms to the ANSI standard.

their

On mag:tape., a virtual bl~alt co:rrespo1nds ·ta::'.:"~ ···my~ical ;~d .. 41• The
default length of a block is 512 bytes. Its length can be changed to
any value greater than 8 bytes (14 bytes for a write function) and up
to 2J2A..8 bytes with the use of the FDBF$ macro (see Section 2.2.1.6).
Records are not a1lowed1 to cross block bounda:ries.
e.

Fixed-length records are packed into a block with no
control
information and no padding for alignment. The blpe,Jt ;i$h~tea•so
that it ends at the word boundary following the end of the last record
that will fit in the block buffer.
recoi:dl), are preceded by a 4'.-byte c9unt_
fi:e1d~11t'
expressed in decimal in ASCII characters. The count includes the
length of the record and the 4-byte count field.
After the last
record in a block (if there is any space left in the block), a caret
character ("A", ASCII code 136), which appears where the next byte
count should be, signals the end of data in that block.
Va~iable.1'!'leng.th.

1-4

FILE CONTROL SERVICES
1.4

BLOCK I/O OPERATIONS

The READ$ and WRITE$ macro calls
(see Sections 3.15 and 3.16,
respectively)
allow the user to read and write virtual blocks of data
from and to a file without regard to logical records within the file.
Block I/O operations provide an efficient means of processing file
data, since such operations do not involve the blocking and deblocking
of records within the file.
Also, in block I/O operations, you can
read or write files in an asynchronous manner; that is, control may
be returned to your program before the requested I/O operation is
completed.
When block I/O is used, the number of the virtual block to be
processed is specified as a parameter in the appropriate READ$/WRITE$
macro call; the virtual blocks so specified are processed directly in
a reserved buffer in user memory space. READ$ and WRITE$ can be used
only on block-structured devices.
As implied above, you are responsible for synchronizing all block I/O
operations.
Such asynchronous operations can be coordinated through
an event flag (see Section 2.8.1) specified in the READ$/WRITE$ macro
call.
The system uses the event flag to signal the completion of a
specified block I/O transfer, enabling you to coordinate those block
I/O operations that are dependent on each other.

1.5

RECORD I/O OPERATIONS

The GET$ and PUT$ macro calls
(see Sections
3.9
and
3.12,
respectively)
are provided for processing individual user records in
files.
Using the FSR block buffers (see Section 1.2), the GET$ and
PUT$ routines perform the necessary blocking and deblocking of records
within the virtual blocks of the file: allowing your program to access
logical records.
Sequential access mode I/O operations can be performed for both fixedand variable-length records. Random access mode I/O operations can be
performed only for fixed-length records.
Your program accesses
records
randomly
by specifying a record number.
This number
represents the position
of
the
desired
record
within
the
file -- viewing the file as an array of fixed-sized records, with the
number 1 representing the first record physically present in the file
and n the last. Successive GET$ or PUT$ operations in random access
mode can access records anywhere within the file.
To do so, your
program need only modify the record number specified as part of the
random record operation.
After each such random operation, FCS
increments the record number used in the operation.
If your program
does not again modify this number prior to issuing another record
operation, the record actually accessed is the next sequential record
in the file.
In contrast to block I/O operations, all record I/O operations are
synchronous;
that is, control is returned to your program only after
the requested I/O operation is completed.
Because GET$/PUT$ operations process logical records within a virtual
block, only a limited number of GET$ or PUT$ operations result in an

1-5

FILE CONTROL SERVICES
actual I/O transfer (for example, when the end of a data block is
encountered).
Therefore,
all
GET$/PUT$
I/O requests do not
necessarily involve an actual physical transfer of data.

1.6

DATA-TRANSFER MODES

When record I/O is used, a program can gain access to a record in
either of two ways after the virtual block has been transferred into
the FSR from a file:
1.

In move mode, by specifying that individual records are to be
moved from the FSR block buffer to a user-defined record
buffer (see Figure 1-2)

In locate mode, by referencing a location in the File
Descriptor Block (see Section 1.9) that contains a pointer to
the desired record within the FSR block buffer

1.6.1

Move Mode

Move mode requires that data be moved between the FSR block buffer and
a user-defined record buffer. For input, data is first read into the
FSR block buffer from a peripheral device and then moved to your
record buffer for processing. For output, your program first builds a
record in the user record buffer; FCS then moves the record to the
FSR block buffer, from which it is written to a peripheral device when
the entire block is filled.
Move mode simulates the reading of a record directly into your record
buffer,
thereby making the blocking and deblocking of records
transparent to you.

1.6.2

Locate Mode

Locate mode enables your to access records directly in the FSR block
buffer. Consequently, there is normally no need to transfer data from
the FSR block buffer to your record buffer.
To access records
directly in the FSR block buffer, you refer to locations in the File
Descriptor Block (see Section 1.9) that contain values defining the
length and the address of the desired record within the FSR block
buffer. These values are present in the FDB as a result of FCS macro
calls that you issued.
Program overhead is reduced in locate mode, since records can be
processed directly within the FSR block buffer. Moving data to the
user record buffer in locate mode is required only when the last
record of a virtual block crosses block boundaries.

1.7

MULTIPLE BUFFERING FOR RECORD I/O

By supporting multiple buffers for record I/O, FCS provides the
capability for users who select multibuffered FCS (see Appendix K) to
read data into buffers in anticipation of user program requirements,

1-6

FILE CONTROL SERVICES
and to write the contents of buffers while the user program is
building records for output.
You can thus overlap the internal
processing of data with file I/O operations, as illustrated in Figure
1-3.
When read-ahead multiple buffering is used, the file must
be
sequentially accessed to derive full benefit from multiple buffering.
For write-behind multiple buffering, you can use any file access
method with full benefit.
When multiple buffering is used, you must allocate sufficient space in
the FSR for the total number of block buffers in use at any given
time. The FSRSZ$ macro call (see Section 2.6.1) is used to accomplish
the allocation of space for FSR block buffers.
Time

Single

process record

Buffer

write record

process record

write record

J
Multiple
Buffer

process record

I
I

write record
process record

l
Figure 1-3

process record
write record

I
I
I

write record
process record

J
ZK-292-81

Single Buffering Versus Multiple Buffering

Multiple buffering can improve performance for I/0-bound
certain circumstances.

tasks

under

For example, consider an I/O bound task running as the dedicated or
highest priority application on a system. For such a task, multiple
buffering can decrease execution time by enabling overlap of I/O and
task execution.
If the task uses large records or operates on
clusters of records, big buffering is also advantageous. This assumes
that it is reasonable to use more task address space and physical
memory for increased buffer space, and more pool for the increased
number of outstanding I/O packets.
However, if other tasks run at the same priority as that of the
application task described above, then an overlap of I/O and task
execution is already achieved among these tasks without multiple
buffering.
In this case, multiple buffering would use up address
space and pool without improving execution speed.
If virtual and
physical address space is available, big buffering would improve
performance.
Big buffering reduces the number of disk accesses by allowing
multiblock input and output. Normally, the disk accesses for GET$ or
PUT$ operations are performed one sector at a time.
Using FCS big
buffers allows you to read or write a specified number of sectors in a
single operation.

1-7

FILE CONTROL SERVICES
To use big buffers, you must select the buffer size and specify that
buffer size in the parameter lists for each occurrence of both the
FSRSZ$ macro and the FDBDF$ macro in your program.
You should choose a buffer size that is a multiple of 512(decimal)
bytes, the size of one disk block. Since the default amount allocated
by a file extend is five blocks and disks often contain many 5-block
files or parts of files, a buffer size of five blocks is generally a
good choice.
Larger amounts may increase performance, but note that
you are trading large amounts of memory for speed.
You must reserve the buffer space in your program and you must make
the buffer size known to the FDB. The FSRSZ$ macro allows you to
specify the total buffer space needed.
Specify 512(decimal) bytes for
each normal disk file, plus the buffer size that you have selected for
each big buffered file.
For example, assume that a program has three
files: one normal file (512-byte buffer); one file with a big buffer
size of three blocks; and one file with a big buffer size of five
blocks.
The following call to the FSRSZ$ macro reserves the space
properly:
FSRSZ$

3,<<1+1+5>*512.>

In the FDB of each file that has a big buffer, you must override the
default buffer size, using either the FDBF$A macro or the FDBF$R
macro. For a file with five blocks as a big buffer, the assembly-time
macro call is:
FDBF$A

<5*512.>

On RSX-llM-PLUS systems, the SYSLIB provided as the default
contains all the proper FCS modules for big buffer support.
users must link to ANSLIB for these modules.

1.8

library
RSX-llM

SHARED ACCESS TO FILES

Files-11 permits shared access to files according to established
conventions.
You can issue two macro calls, among several available
in FCS for opening files, to invoke these conventions.
The OPNS$x
macro call
(see Section 3.2) is used specifically to open a file for
shared access. The OPEN$x macro call (see Section 3.1), on the other
hand,
invokes generalized open functions that have shared-access
implications only in relation to other I/O requests then issued. Both
macro calls take an alphabetic suffix that specifies the type of
operation being requested for the file, as follows:
R - Read existing file.
W - Write (create) a new file.
M - Modify existing file without extending its length.
U - Update existing file and extend its length, if necessary.
A - Append data to end of existing file.
The suffix R applies to the reading of a file, whereas the suffixes W,
M, U, and A all apply to the writing of a file. These macro calls and
the shared access conditions that they invoke are summarized below.

1-8

FILE CONTROL SERVICES
You can use the OPNS$x and OPEN$x macro calls as
access to files:

follows

for

shared

When the OPNS$R macro call is issued, read access to the file
is granted unconditionally, regardless of the presence of one
or more concurrent write access requests to the file.
(The
OPNS$R macro call permits concurrent write accesses to the
file while it is being read.)
Subsequent write access
requests for this same file are honored. Thus, several
active read access requests and one or more write access
requests may be present for the same file.
However, multiple
tasks simultaneously accessing the file for write operations
are subject to certain restrictions, as detailed in point 2.

While FCS allows concurrent write access requests through the
use
of the OPNS$W, OPNS$M, OPNS$U, and OPNS$A macro,
synchronizing access to the file is the responsibility of the
user tasks themselves.
To avoid the retrieval or storage of
inconsistent data, each such task must implement and use some
user-defined mechanism that ensures that the file is accessed
in a serial fashion.

When the OPEN$R macro call is issued, read access to the file
is granted, provided that no write access requests for that
file are active.
(The OPEN$R macro call does not permit
concurrent write access to the file while it is being read.)

Note from the above that readers of a shared file should be aware that

the

file

may yield inconsistent data from request to request if that

file is also being written.
Shared access during reading does not necessarily mean that the access
requests are all from separate tasks. A file could also be shared by
a single task that has opened the file on several different logical
unit numbers.
Table 1-1 shows the circumstances under which Files-11 permits
second file access when the file is opened for shared access.

Table 1-1
Shared File Access
First Access
Second Access
Read

Read

Shared read

Write

Shared write

Yes

Shared
Read
Write
Shared
Write

I
I

1-9

FILE CONTROL SERVICES
1.9

FILE DESCRIPTOR BLOCK (FOB)

The File Descriptor Block (FDB) contains information used by FCS in
opening and processing files.
One FOB is required for each file that
is to be opened simultaneously by your program. You initialize some
portions of the FDB with assembly-time or run-time macro calls, and
FCS maintains other portions.
Each FOB has five sections that contain
user- or system-initialized information:
• File attribute section
• Record or block access section
• File open section
• Block Buffer Section
• Filename block portion of the FOB
The information stored in the FOB depends upon the characteristics of
the file to be processed.
The FOB and the macro calls that cause
values to be stored in this structure are described
in detail
in
Section 2.2.
Appendix A describes in detail the format and the
content of the FDB.

1.10

DATASET DESCRIPTOR AND DEFAULT FILENAME BLOCK

Normally, either a dataset descriptor or a default filename block is
specified for each file that you intend to open.
These data
structures provide FCS with the file specifications required for
opening a file~ Although either one or the other is usually defined~
both can be specified for the same file.
The dataset descriptor and
the default filename block are summarized below and described in
detail in Sections 2.4.1 and 2.4.2, respectively.
When a file is being opened using information already present in the
filename block, neither the dataset descriptor nor the default
filename block is accessed by FCS for required file information. This
method of file access, which is termed "opening a file by file ID," is
an efficient means of opening files.
Section 2.5 describes this
process in detail.

1.11

KEY TERMS USED THROUGHOUT THIS MANUAL

Listed below are terms used throughout this manual that have
meanings in the context of FCS operations.

specific

FILE DESCRIPTOR BLOCK {FOB)
The tabular data structure that provides FCS with information
needed to perform I/O operations on a file.
The space for this
data structure is allocated in your program by issuing the FDBDF$
macro call
(see Section 2.2.1.1).
Each file to be opened
simultaneously by your program must have an associated FDB.
Portions of the FDB are user defined and others are maintained by
FCS. Assembly-time or run-time macro calls are provided for you
in order to initialize the FDB.
The format and content of the
FDB are detailed in Appendix A.

1-10

FILE CONTROL SERVICES
FILENAME BLOCK
The portion of the FDB that contains the various elements of a
file specification (that is, directory, file name, file type,
file version number, device, and unit) for use by the FCS
file-processing routines.
Initially, as a file is opened, FCS
fills in the filename block with user-specified information taken
from the dataset descriptor and/or the default filename block
(see below). The methods of creating file specifications for
initializing the filename block are described in detail in
Section 2.4; the format and content of the filename block itself
are described in Appendix B.
DEFAULT FILENAME BLOCK
The default filename block, an area allocated within your program
by issuing the NMBLK$ macro call (see Section 2.4.2), contains
the various elements of a file specification.
The default
filename block is a user-created structure, whereas the filename
block within the FDB is maintained by FCS.
You create the
default filename block to supply file specifications to FCS that
are not otherwise available through the dataset descriptor (see
below).
In other words, from information defined in the default
filename block, FCS creates a parallel structure in the FDB that
serves as the execution time repository for information that FCS
requires in opening and operating on files.
Thus, the terms "default filename block" and "filename block"
refer
to
separate
and
distinct data structures.
These
distinctions should be kept clearly in mind whenever these terms
appear in the manual. Though created and used differently, these
areas are structurally identical.
DATASET DESCRIPTOR
The dataset descriptor is a 6-word block in your program
containing the sizes and the addresses of ASCII data strings that
together constitute a file specification (see below). This data
structure, which you also create, is des~ribed in detail in
Section 2.4.1. Unless the filename block in the FDB has been
initialized, dataset-descriptor and/or default filename block
information must be provided to FCS before the specified file can
be opened.
DATASET-DESCRIPTOR POINTER
An address value that points to the 6-word dataset descriptor
within your program.
This address value is stored in the FDB,
allowing FCS to access a user-created file specification in the
dataset descriptor.
FILE SPECIFICATION
Any system or user program having a requirement to refer to files
does so through a file specification. Such information names a
file and allows it to be explicitly referenced by any task.
A
file
specification, whether for input or output, contains
specific information that must be made available to FCS before
that file can be opened. The term "file specifier" is sometimes
used as a synonym for "file specification."
FILE STORAGE REGION (FSR)
The file storage region (see Section 1.2) is an area of memory
that you reserve for use in I/O operations. You can allocate
this area by issuing the FSRSZ$ macro call in your program (see
Section 2.6.1).

1-11

FILE CONTROL SERVICES
SYSTEM CHARACTERISTICS

1.12

Listed below are the important characteristics
important in using its I/O facilities:

FCS

that

are

•

REAO$/WRITE$ operations are asynchronous; you are responsible
for
coordinating all block I/O activity.
In contrast,
GET$/PUT$ operations are synchronized entirely
by
FCS;
control is not returned to your program until the requested
GET$/PUT$ operation is completed.

•

FCS macro calls save and
following exceptions:

restore

all

registers,

with

the

The file-processing macro calls (see Chapter 3} place
FOB address in RO.

the

Many of the file control routines (see Chapter 4)
requested information in the general registers.

return

The FOBOF$ macro call (see Section 2.2.1.1) is issued to
• allocate
space for an FOB.
Once the FOB is allocated,
necessary information can be placed in this data construct
through
any logical combination of assembly-time and/or
run-time macro calls (see
Sections
2.2.1
and
2.2.2,
respectively). Certain information must be present in the FOB
before FCS can open and operate on a specified file.
For each assembly-time FOB initalization macro call,
a
• corresponding
run-time macro call is provided that supplies
identical information. Although both sets of macro calls (see
Table 2-1) place the same information in the FOB, each set
does so in a different way. The assembly-time calls generate
.BYTE or .WORD directives that create specific data, while the
run-time calls generate MOV or MOVB instructions that place
desired information in the FOB during program execution.

-...

If an error condition is detected during cul.:r
of
the
file-processing operations described in Chapter 3, or during
the execution of several of the file control routines (see
Section
4 .1) ,
the C-bi t
(carry condition code)
in the
Processor Status Word is set, and an error indicator is
returned to FOB offset location F.ERR.

NOTE
When I/O is being done using the REAO$/WRITE macros,
the IOSB parameter must be specified for F.ERR and the
C-bit to be properly returned (see Section 3.15).
If the address of a user-coded, error-handling routine is specified as
a parameter in any of the file-processing macro calls, a JSR PC
instruction to the error-handling routine is generated.
The routine
is then executed if the C-bit in the Processor Status Word is set.

1-12

CHAPTER 2
PREPARING FOR I/O

The MACR0-11 programmer must establish the proper data base and
working storage areas within the particular program in order to
perform input/output operations.
The following actions must be
performed:
•

Define a File Descriptor Block {FDB) for each file that is to
be opened simultaneously by your program {see Section 2.2).

•

Define a dataset descriptor and/or a default filename block
{see Sections 2.4.1 or 2.4.2, respectively) if you intend to
access
these
structures
to
provide
required
file
specifications to FCS.

•

Establish a file storage region (FSR) within the program {see
Section 2.6).
(The initialization procedures for FORTRAN
tasks are described in detail in the FORTRAN-IV User's Guide
and the FORTRAN-IV-PLUS User's Guide.)

This chapter describes the macro calls that must be invoked to provide
the
necessary
file-processing
information for the FDB.
Such
information is placed in the FDB in one of three ways:
1.

By the assembly-time
Section 2.2.1)

FDB

initialization

macro

calls

By the run-time FDB initialization macro calls
2.2.2)

By the file-processing macro calls (see Chapter 3)

(see

{see

Section

Data supplied during the assembly of the source program establishes
the initial values in the FDB. Data supplied at run time can either
initialize additional portions of the FDB or change values established
at
assembly
time.
Similarly, the data supplied through the
file-processing macro calls can either initialize portions of the FDB
or change previously initialized values.
Table 2-1 lists the macro calls that generate FDB information.

2-1

Table 2-1
Macro Calls Generating FOB Information

2.1

Assembly Time FDB
Macro Calls

Run-Time FOB
Macro Calls

File-Processing
Macro Calls

FDBDF$ (Required)
FDAT$A
FDRC$A
FDBK$A
FDOP$A
FDBF$A

FDAT$R
FDRC$R
FDBK$R
FDOP$R
FDBF$R

OPEN$ (all variations)
CLOSE$
GET$ (all variations)
PUT$ (all variations)
READ$
WRITE$
DE LET$
WAIT$

.MCALL DIRECTIVE - LISTING NAMES OF REQUIRED MACRO DEFINITIONS

All the assembly-time, run-time, and file-processing macro calls (see
Table 2-1 above) that you intend to issue in a program must first be
listed as arguments in an .MCALL directive.
Doing so allows the
required macro definitions to be read in from the system macro library
during assembly.
The .MCALL directive and associated arguments must appear in the
program prior to the issuance of any macro call in the execution code
of the program. If the list of macro names is lengthy, several .MCALL
directives, each appearing on a separate source line, must be
specified to accommodate the entire list of macro names.
The number
of such names that may appear in any given .MCALL statement is limited
only by the availability of space within that 80-byte source line.
The .MCALL directive takes the following general form:
.MCALL

argl,arg2, ••• ,argn

argl,arg2, ••• ,argn
A list of symbolic names identifying the macro definitions
required in the assembly of your program. If more than one
source line is required to list the names of all desired macros,
each additional line so required must begin with an .MCALL
directive.
For clarity of functional use, the assembly-time, run-time, and
file-processing macro names may be listed in each of three
separate .MCALL statements. The macro names may also be listed
alphabetically for readability, or they may be intermixed,
regardless of functional use. All these options are matters of
preference and have no effect whatever on retrieving macro
definitions from the system macro library.
For those users planning to invoke the command line processing
capabilities of the Get Command Line (GCML) routine and the
Command String Interpreter (CSI), all the names of the associated
macros must also be listed as arguments in an .MCALL directive.
GCML and CSI, ordinarily employed in system or application
programs
for
convenience
in
dynamically processing file
specifications, are described in detail in Chapter 6.

2-2

PREPARING FOR I/O
The .MCALL directive is described in detail in the PDP-11 MACR0-11
Language Reference Manual.
The sample programs in Appendix D also
illustrate the use of the .MCALL directive.
Note that
these
directives appear as the first statements in the preparatory coding of
these programs.
The object routines described in Chapter 4 should not be confused with
the macro definitions available from the system macro library. The
file control routines, constituting a body of object modules, are
linked into your program at task-build time from the system object
library ([l,l]SYSLIB.OLB). You should consult Section 4.1 for a
description of these routines.
The following statements are representative of the use of
directive:
.MCALL
.MCALL

the

.MCALL

FDBDF$,FDAT$A,FDRC$A,FDOP$A,NMBLK$,FSRSZ$,FINIT$
OPEN$R,OPEN$W,GET$,PUT$,CLOSE$
NOTE
You can use the macro FCSMC$ to declare
in the .MCALL format the most commonly
used FCS macros, as follows:
.MCALL
FCSMC$

FCSMC$

FCS macros declared in this
manner
include: OPEN$x, OPNS$x, CLOSE$, READ$,
WRITE$, WAIT$, GET$,
PUT$,
DELET$,
FINIT$, FSRSZ$, FDBDF$, FDAT$x, FDRC$x,
FCOP$x, FDBF$x, FDBK$x, and NMBLK$.
If
other
macros are required, explicit
.MCALLs must be issued. A disadvantage
of using this method to declare .MCALL
macros is that unused macros may take up
possibly critical assembler symbol table
space, thus slowing down the assembly
process.

2.2

FILE DESCRIPTOR BLOCK (FDB)

The File Descriptor Block (FDB) is the data structure that provides
the information needed by FCS for all file I/O operations. Two sets
of macro calls are available for FDB initialization: one set is used
for assembly-time initialization (see next section), and the other set
is used for run-time initialization (see Section 2.2.2).
Run-time
macros are used to supplement and/or override information specified
during assembly. Appendixes A and B illustrate all the sections of
the FDB in detail.

2.2.1

Assembly-Time FDB Initialization Macros

Assembly-time initialization requires that the FDBDF$ macro call be
issued (see Section 2.2.1.1) to allocate space for and to define the
beginning address of the FDB. Additional macro calls can then be
issued to establish other required information in this structure.

2-3

PREP1~RING

FOR I/O

The assembly-time macros that accomplish these functions are described
in the following sections. These macro calls take the general form
shown below:
mcnam$A

pl,p2, ••• ,pn

mcnam$A
The symbolic name of the macro.
pl,p2, ••• ,pn
The string of initialization parameters associated with the
specified macro.
A parameter may be omitted from the string by
leaving its field between delimiting commas null.
Assume, for
example, that a macro call may take the following parameters:
FDOP$A 2,DSPT,DFNB
Assume further that the second parameter field is to be coded as
a null specification.
In this case, the statement is coded as
follows:
FDOP$A 2,,DFNB
Also, a trailing comma need not be inserted to reflect the
omission of a parameter beyond the last explicit specification.
For example, the macro call
FDOP$A

2,DSPT,DFNB

need not be specified as
FDOP$A

2,DSPT,

if the last parameter (DFNB) is omitted.
call is specified as follows:
FDOP$A

Rather,

such

macro

2,DSPT

If any parameter is not specified, that is, if any field in the macro
call contains a null specification, the corresponding cell in the FDB
is not initialized and thus remains O.
Multiple values may be specified in a parameter field of certain macro
calls.
Such values are indicated by placing an exclamation point (!)
between the values, indicating a logical OR operation to the MACR0-11
assembler.
Using multiple values in this manner is pointed out in
this manual where such specifications apply.
Throughout the descriptions of the assembly-time macros in the
following sections and elsewhere in this manual, symbols of the form
F.xxx or F.xxxx are referenced (for example, F.RTYP).
These symbols
are defined as offsets from the beginning address of the FDB, allowing
specific locations within the FDB to be referenced.
Thus, you can
reference or modify information within the FDB without having to
calculate word or byte offsets to specific locations.
Using such symbols in system/user software has the
additional
advantage of permitting the relative position of cells within the FDB
to be changed (in a subsequent release, for example) without affecting
your current programs or the coding style employed in developing new
programs.

2-4

PREPARING FOR I/O
2.2.1.1 FDBDF$ - Allocate File Descriptor Block (FOB) - The
FDBDF$
macro call is specified in a MACR0-11 program to allocate space within
the program for an FOB. This macro call must be specified in the
source program once for each input or output file to be opened
simultaneously by your program in the course of execution.
Any
associated assembly-time macro calls
(see Sections 2.2.1.2 through
2.2.1.6) must then be specified immediately following the FDBDF$ macro
if you desire to accomplish the initialization of certain portions of
this FDB during assembly.
The FDB allocation macro takes the following form:
label:

FDBDF$

label
A user-specified symbol that names this particular FDB and
defines
its beginning address.
This label has particular
significance in all I/O operations that require access to the
data structure allocated through this macro call. FCS accesses
the fields within the FDB relative to the address represented by
this symbol.
The following examples are representative of
they might appear in a source program:

FDBDF$

macro

calls

FDBOUT: FDBDF$

;ALLOCATES SPACE FOR AN FDB NAMED
;"FDBOUT" AND ESTABLISHES THE
;BEGINNING ADDRESS OF THE FDB.

FDBIN:

;ALLOCATES SPACE FOR AN FDB NAMED
;"FDBIN" AND ESTABLISHES THE
;BEGINNING ADDRESS OF THE FDB.

FDBDF$

As noted earlier, the source program must embody one FDBDF$ macro call
logically similar to those above for each file to be accessed
simultaneously by your program. FDBs can be reused for many different
files,
as long as the file currently using the FDB is closed before
the next file is opened. The only requirement is that an FDB must be
defined for every file to be opened simultaneously.

2.2.1.2 FDAT$A - Initialize File Attribute Section of
FOB - The
FDAT$A macro call is used to initialize the file attribute section of
the FDB when a new output file is to be created.
If the file to be
processed already exists, the first four parameters of the FDAT$A
initialization macro are not required, since FCS obtains the necessary
information from the first 14 bytes of the user file attribute section
of the specified file's header block (see Appendix F).
This macro
call has the following format:
FDAT$A

rtyp,ratt,rsiz,cntg,aloc

rtyp
A symbolic value that defines the type of records to be built as
the new file is created. One of three values must be specified,
as follows:
1.

R.FIX - Indicates that fixed-length
written in creating the file

2-5

records

are

PREPARING FOR I/O
2.

R.VAR - Indicates that variable-length records are
written in creating the file

R.SEQ - Indicates variable-length sequenced records are to
be written in creating the file

This parameter initializes FOB offset location F.RTYP. Since the
symbols R.FIX, R.VAR, and R.SEQ initialize the same location in
the FOB, these values are mutually exclusive.
ratt
Symbolic values that may be specified to define the attributes of
the records as the new file is created. The following symbolic
values may be specified, as appropriate, to define the desired
record attributes:
•

FD.FTN - Indicates that the first byte in each record
contain a FORTRAN carriage-control character

•

FD.CR - Indicates that the record is to be preceded by a
<LF> character and followed by a <CR> character when the
record is written to a carriage control device {for
example, a line printer or a terminal)

•

FD.BLK - Indicates that records are not
block boundaries

•

FD.PRN - Indicates that the record is preceded
containing carriage control information

allowed

to
by

will

cross
a

word

These parameters initialize the record attribute byte (offset
location F.RATT) in the FOB. The values FD.FTN and FD.CR are
mutually exclusive and must not be specified together.
Apart
from this restriction, the combination (logical OR) of multiple
parameters specified in this field must be separated by an
exclamation point {for example, FD.CR!FD.BLK).
rsiz
A numeric value that defines the size (in bytes) of fixed-length
records to be written to the file. This value, which initializes
FDB offset location F.RSIZ, need not be specified if R.VAR has
been
specified
as
the record type parameter above (for
variable-length records). If R.VAR or R.SEQ is specified, FCS
maintains a value in FOB offset location F.RSIZ that defines the
size (in bytes) of the largest record currently written to the
file. Thus, whenever an existing file containing variable-length
records is opened, the value in F.RSIZ defines the size of the
largest record within that file. By examining the value in this
cell, a program can dynamically allocate record buffers for its
open files.
cntg
A signed numeric value that defines the number of blocks that are
allocated for the file as it is created. The signed values have
the following significance:
•

Positive Value - Indicates that the specified number of
blocks is to be allocated contiguously at file-create time,
and further that the file is to be contiguous

2-6

PREPARING FOR I/O
•

Negative Value - Indicates that the two's complement of the
specified
number
of
blocks is to be allocated at
file-create time, not necessarily contiguously, and further
that the file is to be noncontiguous

This parameter, which has 15 bits of magnitude (plus a sign bit),
initializes FDB offset location F.CNTG.
(You can specify an allocation of up to
.EXTND routine.)

bits

using

the

If you have a firm idea as to the desired length of the file, it
is more eIIlcient to allocate the required number of blocks at
file-create time through this parameter, rather than requiring
FCS to extend the file, if necessary, during the writing of the
file (see aloe parameter below).
If this parameter is not specified, then the file is created as
an empty file; that is, no space is allocated within the file as
it is created.
Issuing the
CLOSE$
macro
call
at
the
completion
of
file-processing resets the value in F.CNTG to O. Thus, the usual
procedure is to initialize this location at run time just before
opening the file.
Reinitialization is necessary if the FDB is
reused.
aloe
A signed numeric value that defines the number of blocks by which
the file is extended, if FCS determines that file extension is
necessary during the writing of the file.
When the end of
allocated space in the file is reached during writing, the signed
value provided through this parameter causes file extension to
occur, as follows:

•

Positive Value - Indicates that the specified number of
blocks is to be allocated contiguously as additional space
within the file, and further that the file is to be
contiguous.
NOTE
Once a file has had blocks allocated,
all future file extensions cause the
file to become noncontiguous, even when
aloe is a positive value.

•

Negative Value - Indicates that the two's complement of the
specified
number
of
blocks
is
to
be
allocated
noncontiguously as additional space within the file, and
further that the file is to be noncontiguous.

This parameter, which also has 15 bits of magnitude (plus a sign
bit), initializes FDB offset location F.ALOC. If this optional
parameter is not specified, file extension occurs as follows:
•

If the number of virtual blocks yet to be written is
greater than 1, the file is extended by the exact number of
blocks required to complete the writing of the file.

2-7

PREPARING FOR I/O
•

If only one additional block is required to complete the
writing of the file,
the file is extended in accordance
with the volume's default extend value.

The volume default extend size is established through the INITIALIZE,
INITVOLUME, or MOUNT command, respectively.
The volume default extend
size cannot be established at the FCS level;
this value must be
established when the volume is initially mounted.
The following statement is representative of an FDAT$A macro call.
This statement initializes the FDB in preparation for creating a new
file containing fixed-length, 80-byte records that will be allowed to
cross block boundaries.
FDAT$A

R.FIX,,80.

In the above example, the record attribute (ratt) parameter has been
omitted, as indicated by the second comma (,) in the parameter string.
Also, the cntg and aloe parameters have been omitted. Their omission,
however, occurs following the last explicit specification, and their
absence need not be indicated by trailing commas in the parameter
string. Since the aloe parameter has been omitted, file extension (if
it becomes necessary) is accomplished in accordance with the current
default extend size in effect for the associated volume.
If moro than one record attribute is specifi~d in thP- ratt parameter
field,
such specifications must be separated by an exclamation point
(!), as shown below:
FDAT$A

R.VAR,FD.FTN!FD.BLK

The above macro call enables a file of variable-length records to be
created.
The
records will contain FORTRAN vertical-formatting
information for carriage control devices;
the records will not be
allowed to cross block boundaries.

2.2.1.3 FDRC$A - Initialize Record Access Section of FDB - The FDRC$A
macro call is used to initialize the record access section of the FDB,
and to indicate whether record or block I/O operations are to be used
in processing the associated file.
If record I/O operations (GET$ and PUT$ macro calls) are to be used,
the FDRC$A or the FDRC$R macro call (see Section 2.2.2) establishes
the FDB information necessary for record-oriented I/O.
If block I/O
operatior1s (READ$ and WRITE$ macro calls) are to be used, however, the
FDBK$A macro call (see Section 2.2.1.4) or the FDBK$R macro call
(see
Section 2.2.2)
must also be specified in order to establish other
values in the FDB required for block I/O.
In this case, portions of
the record access section of the FDB are physically overlaid with
parameters from the FDBK$A/FDBK$R macro call.
You must appropriately initialize the FDB to indicate whether record
or block I/O operations are to be used in processing the associated
file, prior to
issuing the OPEN$ macro call to
initialize file
operations.
The FDRC$A macro call takes the following format:
FDRC$A

racc,urba,urbs

2-8

PREPARING FOR I/O
race
Specifies which variation of block or record I/O is to be used to
process the fileo
This parameter initializes the record access
byte (offset location F.RACC) in the FDB.
The first value below
applies only for block I/O
(READ$/WRITE$)
operations;
all
rema1n1ng values are specific to
record
I/O
(GET$/PUT$)
operations:
•

FD.RWM - Indicates that READ$/WRITE$ {block I/O) operations
are to be used in processing the file.
If this value is
not specified, GET$/PUT$ {record I/O) operations are used
by default.
Specifying FD.RWM necessitates issuing an FDBK$A or an
FDBK$R macro call
in the program to
initialize other
offsets in the block access section of the FDB. Note also
that the READ$ or WRITE$ macro call allows the complete
specification of all the parameters required for block I/O
operations.

•

FD.RAN - Indicates that random access mode is to be used in
processing the file.
If this value is not specified,
sequential access mode is used by default.
Refer to
Section 1.5 for a description of random access mode.

•

FD.PLC - Indicates that locate mode is to be used
in
processing the file.
If this value is not specified, move
mode is used by default.

•

FD.INS - This value, which applies only for sequential
files
(and therefore cannot be specified jointly with the
FD.RAN parameter above), indicates that a PUT$ operation
performed within the body of the file shall not truncate
the file.
Should you wish to perform a PUT$ operation within the body
of a file, the .POINT routine described in Section 4.10.l
may be called.
This routine, which permits a limited
degree of random access to a file, positions the file to a
user-specified byte within a virtual block in preparation
for the PUT$ operation.
If FD.INS is not specified, a PUT$ operation within the
file truncates the file at the point of insertion; that
is, the PUT$ operation moves the logical end-of-file
(EOF)
to a point just beyond the inserted record.
However, no
deallocation of blocks within the file occurs.
Regardless of the setting of the FD.INS bit, a
PUT$
operation that is in fact beyond the current logical end of
the file resets the logical end of the file to a point just
beyond the inserted record.

urba
The symbolic address of a user record buffer to be used for GET$
operations in move and locate modes, and for PUT$ operations in
locate mode.
This parameter initializes FDB offset location
F.URBD+2, and is specified only for record I/O operations.

2-9

PREPARING FOR I/O
urbs
A numeric value that defines the size {in bytes) of the user
record buffer to be employed for GET$ operations in move and
locate modes, and for PUT$ operations in locate mode.
This
parameter
initializes
FDB offset location F.URBD, and is
specified only for record I/O operations.
You allocate and label a record buffer in a program by issuing a .BLKB
or .BLKW directive.
The address and the size of this area is then
passed to FCS as the urba and the urbs parameters above. For example,
a user record buffer may be defined through a statement that is
logically equivalent to that shown below:
RECBUF:

.BLKB

82.

RECBUF
Is the address of the buffer and
bytes} •

82(decimal)

its

size

(in

Beginning user record buffers on a word boundary can
improve
performance by allowing FCS to move the data with MOV instructions
rather than MOVB instructions.
Under certain conditions, you need not allocate a record buffer or
specify the buffer descriptors {urba and urbs) for GET$ or PUT$
operations. These conditions are described in detail in Sections
3.9.2 and 3.12.2, respectively.
The following statement is representative of an FDRC$A macro call that
is issued for a file that may be accessed in random mode:
FDRC$A

FD.RAN,BUFl,160.

The address of the user record buffer is specified through the symbol
BUFl, and the size of the user record buffer (in bytes) is defined by
the numeric value i60(decimal).
If more than one value is specified in the record access (race) field,
an exclamation point (!) must separate the multiple values, as shown
b~low:

FDRC$A

FD.RAN!FD.PLC,BUFl,160.

In addition to the functions described for the first example, this
example specifies that locate mode is to be used in processing the
associated file. Note that the multiple parameters specified in the
first field are separated by an exclamation point (!).

2.2.1.4 FDBK$A - Initialize Block Access Section of FDB - The FDBK$A
macro call is used to initialize the block access section of the FDB
when block I/O operations (READ$ and WRITE$ macro calls) are to be
used for file processing. Initializing the FDB with this macro call
allows you to read or write virtual blocks of data within a file.

Use of the FDBK$A macro call implies that the FDRC$A macro call has
also been specified, since the FD,RWM parameter of the FDRC$A macro
call does initial declaration of block I/O operations.
Thus, for

2-10

PREPARING FOR I/O
block I/O operations, the FDRC$A macro call must be spec1r1ed, as well
as any one of the following macro calls, to appropriately initialize
the block access section of the FDB:
FDBK$A, FDBK$R, READ$, or
WRITE$.
Issuing the FDBK$A macro call causes certain portions of the record
access section of the FDB to be overlaid with parameters necessary for
block I/O operations. Thus, the terms "record access section" and
"block access section" refer to a shared physical area of the FDB that
is functional for either record or block I/O operations.
The block I/O and record I/O FOB-initialization macros use the same
area of the FDB for different data.
Therefore, if record I/O
operations are to be employed, neither the FDBK$A nor the FDBK$R macro
call must be issued.
The FDBK$A macro call is specified in the following format:
FDBK$A

bkda,bkds,bkvb,bkef ,bkst,bkdn

bkda
The symbolic address of an area in user memory space to be
employed as a buffer for block I/O operations. This parameter
initializes FDB offset location F.BKDS+2.
bkds
A numeric value that specifies the size {in bytes) of the block
to be read or written when a block I/O request (READ$ or WRITE$
macro call) is issued. This parameter initializes FDB offset
location F.BKDS.
The size specified must be an even, positive
(sign bit must not be set) value; thus, the maximum number of
bytes that can be specified is 32766. If an integral number of
blocks are to be specified, the practical maximum number of bytes
that can be specified is equal to 63 virtual blocks, or
32256(decimal) bytes.
bk vb
A dummy parameter for compatibility with the FDBK$R macro call.
The bkvb parameter is not specified in the FDBK$A macro call for
the reasons stated in item 4 of Section 2.2.2.1.
In short,
assembly-time initialization of FDB offset locations F.BKVB+2 and
F.BKVB with the virtual block number is meaningless, since any
version of the generalized OPEN$x macro call resets the virtual
block number in these cells to 1 as the file is opened.
Therefore, these cells can be initialized only at run time
through either the FDBK$R macro call (see Section 2.2.2) or the
I/0-initiating READ$ and WRITE$ macro calls (see Sections 3.15
and 3.16, respectively).
This dummy parameter should be reflected as a null specification
(with a comma) in the parameter string only in the event that an
explicit parameter follows. This null specification is required
in order to maintain the proper position of any remaining
field(s) in the parameter string.

2-11

PREPARING FOR I/O
bkef
A numeric value that specifies an event flag to be used during
READ$/WRITE$ operations to indicate the completion of a b1'ock I/O
transfer. This parameter initializes FOB offset location F.BKEF;
if not specified, event flag 32(decimal) is used by default.
The function of an event flag is described in further
Section 2. 8 .1.

detail

bkst
The symbolic address of a 2-word I/O status block in your
program.
If specified, this optional parameter initializes FOB
offset location F.BKST.
The I/O status block, if it is to be used, must be defined and
appropriately labeled at assembly time.
Then, if the bkst
parameter is specified, information is returned by the system to
the I/O status block at the completion of the block I/O transfer.
This information reflects the status of the requested operation.
If this parameter is not specified, no information is returned to
the I/O status block.
NOTE
If an error occurs during a READ$ or
WRITE$ operation that would normally be
reported as a negative value in the
first byte of the I/O status block, the
error is not reported unless an I/O
status
block
address is specified.
Thus, you are advised to specify this
parameter to allow the return of block
I/O status information and to facilitate
normal error reporting.
The creation and function of the I/O status block
in detail in Section 2.8.2.

are

described

bkdn
The symbolic address of an optional user-coded AST service
routine.
If present, this parameter causes the AST service
routine to be initiated at the specified address upon completion
of block I/O;
if not specified, no AST trap occurs. This
parameter initializes FOB offset location F.BKDN.
Considerations relevant to the use of an AST service routine
presented in Section 2.8.3.

are

The following example shows an FDBK$A macro call that utilizes all
available parameter fields for initializing the block access section
of the FOB:
FDBK$A

BKBUF,240.,,20.,ISTAT,ASTADR

In this macro call, the symbol BKBUF identifies a block I/O buffer
reserved in the user program that will accommodate a 240{decimal)-byte
block. The virtual block number is null (for the reasons stated above

2-12

PREPARING FOR I/O
in the description of this parameter) , and the event flag to be set
upon block I/O completion is 20(decimal). Finally, the symbol ISTAT
specifies the address of the I/O status block, and the symbol ASTADR
specifies the entry point address of the AST service routine.

2.2.1.s FDOP$A - Initialize File-Open Section of FDB - The
FDOP$A
macro call is used to initialize the file-open section of the FDB. In
addition to a logical unit number, either a dataset descriptor pointer
and/or a default filename block address is normally specified for each
file that is to be opened. The latter two parameters provide FCS with
the linkage necessary to retrieve file specifications from these
user-created data structures in the program.
Although both a dataset descriptor pointer (dspt) and the address of a
default filename block (dfnb) may be specified for a given file, one
or the other must be present in the FDB before that file can be
opened.
If, however, certain information is already present in the
filename block as the result of prior program action, neither the
dataset descriptor nor the default filename block is accessed by FCS,
and_ the file is opened through a process called "opening a file by
file ID." This process, which is an efficient method of opening a
file, is described in detail in Section 2.5.
The dspt and dfnb parameters represent address values which point to
user-defined data structures in the program. These data structures,
which are described in detail in Section
2.4,
provide
file
specifications to the FCS file-processing routines.
The FDOP$A macro call takes the following form:
FDOP$A

lun,dspt,dfnb,facc,actl

lun
A numeric value that specifies a logical unit number.
This
parameter
initializes FDB offset location F.LUN.
All I/O
operations performed in conjunction with this FDB are done
through the specified logical unit number (LUN). Every active
FDB must have a unique LUN.
The logical unit number specified through this parameter may be
any value from 1 through the largest value specified to the Task
Builder through the UNITS option.
This option specifies the
number of logical units to be used by the task (see the Task
Builder Reference Manual of the host operating system).
dspt
The symbolic address of a 6-word block in the user program
containing
the dataset descriptor~
This user-defined data
structure consists of a 2-word device descriptor, a 2-word
directory descriptor, and a 2-word file name descriptor, as
outlined in Section 2.4.1.
The dspt parameter initializes FDB offset location F.DSPT.
This
address value, called the dataset descriptor pointer, is the
linkage address through which FCS accesses the fields in the
dataset descriptor.

2-13

When the Command String Interpreter
{CS!}
is used to process
command string input, a file specification is returned to the
calling program in a format identical to that of the manually
created dataset descriptor.
The use of CS! as a dynamic command
line processor is described in detail in Section 6.2.
dfnb
The symbolic address of the default filename block.
This
structure is allocated within the user program through the NMBLK$
macro call
{see Section 2.4.2).
When specified, the dfnb
parameter initializes FDB offset location F.DFNB, allowing FCS to
access the fields of the default filename block in building the
filename block in the FDB.
Specifying the dfnb parameter in the FDOP$A {or the FDOP$R} macro
call assumes that the NMBLK$ macro call has been issued in the
program. Furthermore, the symbol specified as the dfnb parameter
in the FDOP$A (or the FDOP$R) macro call must correspond exactly
to the symbol specified in the label field of the NMBLK$ macro
call.
f acc

Any one, or any appropriate combination, of
symbolic values indicating how the specified
accessed:
•

FO.RD - Indicates that an existing file is to be opened for
reading only.

FO.WRT - Indicates that a new file is
• opened
for writing.

FO.APD - Indicates that an existing file is
• for
append.

•

the following
file is to be

FO.MFY - Indicates

LL -L

--·:.L;:,
_.....l...Lll'::j
:
an t::A

s:.;, -

created
to

.i-L.V

FO.UPD - Indicates that an existing file is
• for
update and, if necessary, extended.

l..lJQ l..

.L.L.,t.C

and

opened

...........

,...,.Y"'\.0'1""110,=I

opened

A.IC

V.t"''Wl&~U

for modification.

•

FA.NSP - Indicates, in combination with FO.WRT above, that
an old file having the same file specification is not to be
superseded by the new file.
Rather, an error code is to be
returned if a file of the same file name, type, and version
exists.

•

FA.TMP - Indicates, in combination with FO.WRT above,
the created file is to be a temporary file.

•

FA.SHR - Indicates that the file is to be opened for shared
access.

that

The face parameter initializes FDB offset location F.FACC.
The symbolic values FO.xxx, described above, represent the
logical OR of bits in FDB location F.FACC.
The information specified by this parameter
can
be
overridden by an OPEN$ macro call, as described in Section
3.7.
It is overridden by an OPEN$x macro call.

2-14

PREPARING FOR I/O
actl
A symbolic value that is used to specify
information in FDB location F.ACTL:

the

following

control

Magnetic tape position

Whether a disk file that is opened for write is to be
locked if it is not properly closed; for example, the
task terminates abnormally

Number of retrieval pointers to allocate for a
window

Enable block locking

disk

file

Normallly, FCS supplies default values for F.ACTL.
However, if
FA.ENB is specified in combination with any of the symbolic
values described below, FCS uses the information in F.ACTL.
FAENB must be specified with the desired values to override the
defaults. The following are the defaults for location F.ACTL:
•

For file creation, magnetic tapes are positioned to the end
of the volume set.

•

At file open and close, tapes are not rewound.

•

A disk file that is opened for write is locked if it is not
properly closede

•

The volume default is used for the file window.

The values listed below can be used in conjunction with FA.ENB:
•

FA.POS - Is meaningful only for output files and
is
specified to cause a magnetic tape to be positioned just
after the most recently closed file for creating a new
file.
Any files that exist after that point are lost. If
rewind is specified, it takes precedence over FA.POS, thus
causing the tape to be positioned just after the VOLl label
for file creation. See Section 5.2.3.

•

FA.RWD - Is specified to cause a magnetic
rewound when the file is opened or closed.

tape

Examples of using FA.ENB
provided in Section 5.2.8.

FA.RWD

are

•

with

FA.POS

and

FA.DLK - Is specified to cause a disk file not to be locked
if it is not properly closed.
The number of retrieval pointers for a file window can be
specified in the low-order byte of F.ACTL. The default
number of retrieval pointers is the file-~indow mapping
pointer count parameter (/WIN) included in the Initialize
Volume or Mount Volume MCR commands; the default value for
this parameter is 7. Retrieval pointers are used to point
to contiguous blocks of the file on disk.
Access to
fragmented files may be optimized by increasing the number
of retrieval pointers, that is, by increasing the size of
the window.
Similarly, since retrieval pointers use up
pool space, additional memory can be freed by reducing the
number
of
pointers
for
files
with little or no
fragmentation, for example, contiguous files.
2-15

PREPARING FOR
•

T
/f"\
~1 v

FA.LKL!FA.EXL - Is specified to lock all blocks that are
accessed.
See the RSX-llM/M-PLUS I/O Drivers Reference
Manual for further information on bloci<Tocking.

As noted, if neither the dspt nor the dfnb parameter is specified,
corresponding offset locations F.DSPT and F.DFNB contain O.
In this
case, no file is currently associated with this FDB. Any attempt to
open a file with this FDB results in an open failure.
Either offset
location F.DSPT or F.DFNB must be initialized with an appropriate
address value before a file can be opened using this FDB. Normally,
these cells are initialized at assembly time through the FDOP$A macro
call; but they may also be initialized at run time through the FDOP$R
or the generalized OPEN$x macro call (see Section 3.1).
The following examples represent the FDOP$A macro
appear in a source program:
FDOP$A

l,,DFNB

FDOP$A

2,0FDSPT

FDOP$A

2,0FDSPT,DFNB

FDOP$A

l,CSIBLK+C.DSDS

FDOP$A

l,,DFNB,,FA.ENB!l6.

call

might

Note in the first example that the dataset descriptor pointer
(dspt)
is null, requiring that FCS rely on the run-time specification of the
dataset descriptor pointer for the FDB or the use of the default
filename block for required file information.
In the second example, a dataset descriptor pointer (OFDSPT) has been
specified, allowing FCS to access the fields in the dataset descriptor
for required file information.
The third example specifies both a dataset descriptor

default

filename

o~ocK

pointer

and

address, causing FDB offset locations F.DSPT

and F.DFNB, respectively, to be initialized with the appropriate
values.
In this case, FCS can access the dataset descriptor and/or
the default filename block for required file information.
By
convention,
FCS
first
seeks such information in the dataset
descriptor; if all the required information is not present in this
data structure, FCS attempts to obtain the missing information from
the default filename block.
The fourth example shows a macro call that takes as its second
parameter a symbolic value that causes FDB offset location F.DSPT to
be initialized with the address of the CS! dataset descriptor.
This
structure is creat~d in the CS! control block through invoking the
CS!$ macro call. All considerations relevant to the use of CS! as a
dynamic command line processor are presented in Section 6.2.
The last example illustrates the use of the parameter actl to increase
the number of retrieval pointers in the file window to 16. FA.ENB is
specified to cause the contents of F.ACTL, rather than the defaults,
to be used.
In all the examples above, the value specified as the first parameter
supplies the logical unit number to be used for all I/O operations
involving the associated file.

2-16

PREPARING FOR I/O
2.2.1.6 FDBF$A - Initialize Block Buffer Section of FDB - The FDBF$A
macro call is used to initialize the block buffer section of the FDB
when record I/O operations (GET$ and PUT$ macro calls) are to be used
for file processing. Initializing the FDB with this macro call allows
FCS to control the necessary blocking and deblocking of individual
records within a virtual block as an integral function of processing
the file.
The FDBF$A macro call takes the following format:
FDBF$A

efn,ovbs,mbct,mbfg

efn
A numeric value that specifies the event flag to be used by FCS
in synchronizing record I/O operations.
This numeric value
initializes FDB offset location F.EFN. This event flag is used
internally by FCS; it must not be set, cleared, or tested by the
user.
If this parameter is not specified, event flag 32(decimal) is
used by default. A null specification in this field is indicated
by inserting a leading comma in the parameter string.
ovbs
A numeric value that specifies an FSR block buffer size, in
bytes, which overrides the standard block size for the particular
device associated with the file. This parameter initializes FDB
offset location F.OVBS to the specified block-buffer size.
When ovbs is used in RSX-11 systems to specify an FSR block
buffer size for disks, the desired number of bytes is specified
in integral multiples of 512(decimal), overriding the standard
512(decimal)
{one sector) block buffer size. Block buffer sizes
up to 63 sectors (32256(decimal) bytes) can be specified for
disks.
Increasing the block buffer size in this manner greatly
reduces average disk access time, since several contiguous
sectors are generally read or written during a typical disk
access operation. An override block size of 2048{decimal) bytes
(4 sectors) or 2560(decimal) bytes (5 sectors) is recommended,
since 2048{decimal) bytes also provides ANSI magtape buffer
capability, and 2560(decimal) bytes is the Files-11 default
extend size. Note that once the file has been opened, FCS uses
the ovbs field for other purposes. Thus, if the FDB is to be
used for additional disk I/O operations, the ovbs parameter must
be issued in an FDBF$R macro prior to accessing the disk.
NOTE

When block buffer sizes greater than l
sector
(512 (decimal)
bytes)
are
specified, $$FSR1 size must be increased
accordingly. This is done by specifying
an appropriate value for the bufsiz
parameter in the FSRSZ$ macro call (see
Section 2.6.1).

In IAS systems, an override block size is allowed only for
record-oriented devices (such as line printers) and sequential
devices (such as magnetic tape units);
if specified for a
block-oriented device, the override block size is ignored. For
2-17

PREPARING FOR
spooled output to a record-oriented device, do not allocate
(512(decimal) bytes).

bu~fer less than a single sector

Routines that will read ANSI-standard magnetic tape without prior
knowledge of the format of the files that will be read must
specify an override block size of 2048(decimal)
bytes.
This
value is sufficient for the largest ANSI-standard tape blocks.
Issuing the CLOSE$ macro call (see Section 3.8)
resets offset
location F.OVBS in the associated FDB to O. Therefore, this
location should typically be initialized at run time, just before
opening the file, particularly if an OPEN$x/CLOSE$ sequence for
the file is performed more than once.
On certain devices, such as line printers and terminals, the
block size should not exceed the device's line width. The task
can obtain the proper block size for these devices by issuing the
Get LUN Information system directive for each device.
(See the
description for the Get LUN Information directive in
the
Executive Reference Manual for the operating system in use.) The
standard block size for ea~h device is established at SYSGEN
time, or by the MCR SET/BUF command.
mbct
A numeric value that specifies the multiple buffer count, that
is, the number of buffers to be used by FCS in processing the
associated file.
This parameter initializes FDB offset location
F.MBCT.
If this value is greater than 1, multiple buffering is
effectively declared for file processing.
In this case, FCS
employs either read-ahead or write-behind operations, depending
on which of two symbolic values is specified as the mbfg
parameter (see below).
If the mbct parameter is specified as null or 0,
FCS uses the
default buffer count contained in symbolic location .MBFCT in
$$FSR2 (the program section in the FSR containing impure data).
This cell normally contains a aerault buffer count of l.
1r
desired, this value can be modified, as noted in the discussion
following the mbfg parameter below.
If, in specifying the FSRSZ$ macro call
(see Section 2.6.1),
sufficient memory space has not been allocated to accommodate the
number of buffers established by the mbct parameter,
FCS
allocates as many buffers as can fit in the available space.
Insufficient space for at least one buffer causes FCS to return
an error code to FDB offset location F.ERR.
The user can initialize the buffer count in F.MBCT through either
the FDBF$A or the FDBF$R macro call.
The buffer count so
established is not altered by FCS and, once set, need not be of
further concern to the user.
When input is from record devices (for example, a
F.MBCT should not be greater than 2.

card

reader),

mbf g
A symbolic value that specifies the type of multiple buffering to
be employed in processing the file.
Either of two values may be
specified to initialize FDB offset location F.MBFG:
•

FD.RAH - Indicates that read-ahead
used in processing the file
2-18

operations

are

PREPARING FOR I/O
•

FD.WBH - Indicates that write-behind operations are
used in processing the file

These parameters are mutually exclusive;
other, but not both, may be specified.

that

is,

one

the

Specifying this parameter assumes that
the
buffer
count
established in the mbct parameter above is greater than 1.
If
multiple buffering has thus been declared, omitting the mbfg
parameter causes FCS to use read-ahead operations by default for
all files opened using the OPEN$R macro call;
similarly,
write-behind operations are used by default for all files opened
using other forms of the OPEN$x macro call.
If these default buffering conventions are not desired, you can
alter the value in the F.MBFG dynamically at run time.
This is
done by issuing the FDBF$R macro call, which takes as the mbfg
parameter the appropriate control flag (FD.RAH or FD.WBH).
This
action must be taken, however, before opening the file.
Offset location F.MBFG in the FDB is reset to
associated file is closed.
NOTE
When using
write-behind
multibuffering, there is no gain in
efficiency if the size of the file
must be increased in order to make
room for the data to be written.
If a file is being written at the
end, using default extension, there
will be one extend operation for
each five write operations;
thus,
only
80%
of
the write-behind
operations
will
actually
be
overlapped with processing. This
percentage can be increased
as
follows:
1.

Space for the file can be completely
preallocated, either by using the "cntg"
parameter in the FDOP$x macro, or by
using the .EXTND subroutine.

The default extension amount can be
increased from five blocks by using the
"aloe" parameter of the FDAT$x macro
call.
For
example,
if an "aloe"
parameter of lO(decimal)
is specified,
the number of write-behind operations
that will be overlapped will increase to
90%.

The file can be accessed using random
I/O.
Since issuing PUT$R macros to
access random preexisting locations in
the file does not require extends, the
percentage of overlapped operations is
increased.

2-19

each

time

the

PREPARING FOR IiO
You can change the default buffer count, if desired, by modifying a
location in $$FSR2, the second of two program sections comprising the
FSR. A location defined as .MBFCT in $$FSR2 normally contains a
default buffer count of 1.
This default value may be changed, as
follows:
1.

Apply a global patch to .MBFCT at task-build time to
the desired number of buffers.

specify

For MACR0-11 programs, use the EXTSCT Task Builder directive
(see Section 2.7.1) to allocate more space for the FSR block
buffers; for FORTRAN programs, use the ACTFIL Task Builder
directive
(see Section 2.7.2) to allocate more space for the
FSR block buffers.

Because the above prpcedure alters the default buffer count for all
files to be processed by your program, it may be desirable to force
single buffering for any specific file(s) that would not benefit from
multiple buffering.
In such a case, you can set the buffer count in
F.MBCT for a specific file to 1 by issuing the following macro call
for the applicable FOB:
FOBF$A

,,1

The value 1 specifies the buffer count (mbct) for the desired file and
is entered into offset location F.MBCT in the applicable FOB. Note in
the example above that the event flag (efn)
and the override block
buffer size
(ovbs)
parameters are null; these null values are used
for illustrative purposes only and should not be interpreted as
conditional
specifications
for
establishing
single-buffered
operations.
The following examples are representative of the FOBF$A macro call
it might appear in a program:
FOBF$A

25.,,1

FOBF$A

25.,,2,FO.RAH

FOBF$A

,,2,FO.WBH

The first example specifies that event flag 25(decimal) is to be used
in synchronizing record I/O operations and that single buffering is to
be used in processing the file.
The second example also specifies event flag
25(decimal)
for
synchronizing record I/O operations, and in addition establishes 2 as
the multiple buffer count. The buffers so specified are to be used
for read-ahead operations, as indicated by the final parameter.
The last example allows event flag 32(decimal) to be used by default
for synchrotiizing record I/O operations, and the two buffers specified
in this case are to be used for write-behind operations.
Note in all three examples that the second parameter, that is, the
override block size parameter
(ovbs), is null; thus, the standard
block size in effect for the device in question will be used for all
file I/O operations.

2-20

PREPARING FOR I/O
2.2.2

Run-Time FDB Initialization Macros

Although the FDB is allocated and can be initialized during program
assembly, the contents of specific sections of the FDB can also be
initialized or changed at run time by issuing any of the following
macro calls:

•

FDAT$R

- Initializes or alters the file

attribute

sectioh

of the FDB.

• FDRC$R

- Initializes or alters the record access section of
the FDB.

• FDBK$R

- Initializes or alters the block access section

• FDOP$R

- Initializes or alters the file-open section of the

• FDBF$R

- Initializes or alters the block buf fec section

the FDB (see item 4 below) •
FDB.
of

the FDB.

There are no default values for run-time FDB macros
(except for the
FDB address).
At run time, the values currently in the FDB are used
unless they are explicitly overridden. For example, values stored in
the FDB at assembly time are used at run time unless they are
overridden.

2.2.2.1 Run-Time FDB Macro-Call Exceptions - The
format
and
the
parameters of the run-time FDB initialization macros are identical to
the assembly-time macros described earlier, except as noted below:
•

An R rather than an A must appear as the last character in the
run-time symbolic macro name.

•

The first parameter in all run-time macro calls must be the
address of the FDB associated with the file to be processed.
All other parameters in the run-time macro calls are identical
to those described in Sections 2.2.1.2 through 2.2.1.6 for the
assembly-time macro calls, except as noted in items 3 and 4
below.

•

The parameters in the run-time macro calls must be valid
MACR0-11 source operand expressions. These parameters may be
address values or literal values; they may also represent the
contents of registers or memory locations.
In short, any
value that is a valid source operand in a MOV or MOVB
instruction may be specified in a run-time macro call. In
this regard, the following conventions apply:
If the parameter is an address value or a literal value
that is to be placed in the FDB; that is, if the
parameter itself is to be taken as an argument, it must
be preceded by the number sign (f). This symbol is the
immediate expression indicator for MACR0-11 programs,
causing the associated argument to be taken literally in
initializing the appropriate cell in the FDB.
Such
literal values may be specified as follows:
FDOP$R #FDBADR,#1,#DSPT,#DFNB

2-21

rru::r1rnrnc Pon. ....J../,,..v
If the parameter is the address of a location containing
an argument that is to be placed in the FOB, the
parameter must be preceded by the number sign {#). Such
a parameter may be specified as follows:
ONE:

.WORD

FDOP$R

#FDBADR,ONE,#DSPT,#DFNB

where ONE represents the symbolic address of a
containing the desired initializing value.

location

But, if the parameter is a
register specifier
(for
example, R4), the parameter must not be preceded by the
number sign
(#).
Register specifiers are
defined
MACR0-11 symbols and are valid expressions in any
context.
NOTE
RO can only be specified in the first parameter
(FOB address).
Any other use of RO will fail.
(See Section 2.2.2.2, items 1 and 2.)
Thus, in contrast, parameters specified in assembly-time macro
calls are used as arguments in generating data in .WORD or
.BYTE directives, while parameters specified in run-time macro
calls
are
used as arguments in MOV and MOVB machine
instructions.
•

As noted in the description of the FDBK$A macro call
in
Section 2.2.1.4, assembly-time initialization of the FOB with
the virtual block number is meaningless, since issuing the
OPEN$x
rna~LU
~aii
LO
piepare a ~11e for processing
automatically resets the virtual block number in the FOB to 1.
For this reason, the virtual block number can be specified
only at run time after the file has been opened. This may be
accomplished by issuing either the FDBK$R macro call or the
I/0-initiating READ$/WRITE$ macro call.
In all three cases,
the relevant field for defining the virtual block number is
the bkvb parameter. The READ$ and WRITE$ macro calls are
described in detail in Sections 3.15 and 3.16, respectively.
At assembly time, you must reserve and label a 2-word block in
the program that is to be used for temporarily storing the
virtual-block number appropriate for
intended block
I/O
operations.
Since you are free to manipulate the contents of
these two locations at will, any virtual block
number
consistent with intended block I/O operations may be defined.
By specifying the symbolic address {that is, the label)
of
this field as the bkvb parameter in the selected run-time
macro call, you can make the virtual block number available to
FCS.
In preparing for block I/O operations, you
following general procedures:

At assembly time, reserve a
through a statement that
following:
2-22

2-word block
is logically

must

perform

the

in your program
equivalent to the

PREPARING FOR I/O
VBNADR: .BLKW

The label VBNADR names this 2-word block and defines its
address.
This symbol is used subsequently as the bkvb
parameter in the
selected
run-time
macro
caii
for
initializing the FDB.
2.

At run time, load this field with the desired virtual block
number.
This
operation
may
be accomplished through
statements logically equivalent to those shown below:
CLR
MOV

VBNADR
#10400,VBNADR+2

Note that the first word of the block is cleared~
The MOV
instruction then loads the second (low-order) word of the
block with a numeric value. This value constitutes the 16
least significant bits of the virtual block number.
If the desired virtual block number cannot be completely
expressed within 16 bits, the rema1n1ng portion of the
virtual block number must be stored in the first (high-order)
word
of the block.
This may be accomplished through
statements logically equivalent to the following:
MOV
MOV

#1,VBNADR
#10400,VBNADR+2

As a result of these two instructions, 31 bits of value are
defined in this 2-word block. The first word contains the 15
most significant bits of the virtual block number, and the
second word contains the 16 least significant bits. Thus,
the virtual block number is an unsigned value having 31 bits
of magnitude.
You must ensure that the sign bit in the
high-order word is not set.
3.

Open the desired file for processing by
issuing
the
appropriate version of the generalized OPEN$x macro call (see
Section 3.1).

Issue either the FDBK$R macro call or the READ$/WRITE$ macro
call, as appropriate, to initialize the relevant FDB with the
desired virtual block number.
If the FDBK$R macro call
representative example:
FDBK$R

elected,

the

following

#FDBIN,,,#VBNADR

Regardless of the particular macro call used to supply the
virtual block number, the two words at VBNADR are loaded into
F.BKVB and F.BKVB+2. The first of these words (F.BKVB) is 0
if 16 bits are sufficient to express the desired virtual
block number. The I/O-initiating READ$/WRITE$ macro call may
then be issued.
Should you choose, however, to initialize the FDB directly
through either the READ$ or WRITE$ macro call, the virtual
block number may be made available to FCS through a statement
such as that shown below:
READ$

#FDBIN,JINBUF,JBUFSIZ,#VBNADR

2-23

PREPARING FOR I,/O

The symbol VBNADR represents the address of the 2-word
in your program containing the virtual block number.

block

2.2.2.2 Specifying the FDB Address in Run-Time Macro Calls - In
relation to item 2 of the exceptions noted above, the address of the
FDB associated with the file to be processed corresponds to the
address value of the user-defined symbol appearing in the label field
of the FDBDF$ macro call (see Section 2.2.1.1).
For example, the
statement
FDBOUT: FDBDF$
in addition to allocating space for an FDB at assembly time, binds the
label FDBOUT to the beginning address of the FDB associated with this
file. The address value so established can then be specified as the
initial parameter in a run-time macro call in any one of three ways:
1.

The address of the appropriate FDB may be specified as an
explicit parameter in a run-time macro call, as indicated in
the following statement:
FDAT$R

#FDBOUT,#R.VAR,#FD.CR

The argument FDBOUT is taKen literally by FCS as the
-.t:

V.L

g11

l:'T'\D .&..",_,....,,

,4!,. • .,...a-h-. ..... -.-. .... -.

.1..u.a..\...1.1,,_..a..u1v.&..-.;;;;-1

~)......;,,..

\..&&•~

~...:i.,:i.,..,....,...,,..

u.uu.a....,.;>~

~,"!"lt.1

... -.

vu•u~r

1-i...,.
uz

address

,..,,,,...""' .. '"'""',._.; - -

vv11v,;;;;-11'-.£.v,ur

is stored in general register zero (RO).
Whenever this
method of specifying the FDB address is employed, the
previous contents of RO are overwritten (and thus destroyed).
Therefore, you must exercise care in issuing subsequent
run-time macro calls to ensure that the present value of RO
is suitable to current purposes.
2.

A general register specifier may be used as the initial
parameter in a run-time macro call. When a register other
than RO is used, the contents of the specified register are
moved to ROe
The previous contents of RO are overwritten
(and thus destroyed).
The following statement reflects the
register to specify the FDB address:
FDAT$R

use

general

RO,#R.VAR,#FD.CR

In this case, the current contents of RO are taken by FCS as
the address of the appropriate FDB. This method assumes that
the address of the FDB has been previously loaded into RO
through some overt action. Note, when using this method to
specify the FDB address, that the immediate expression
indicator (#) must not precede the register specifier (RO).
3.

A null specification may be used as the initial parameter
a run-time macro call, as shown below:
FDAT$R

,#R.VAR,#FD.CR

In this case, the current contents of RO are taken by default
as the address of the associated FDB. As in method 2 above,
RO is assumed to contain the address of the desired FDB.
Although the comma in this instance constitutes a valid
specification, you are advised to employ methods 1 and 2 for
consistency and clarity of purpose.

2-24

PREPARING FOR I/O
These three methods of specifying the FDB address also apply
the FCS file-processing macro calls described in Chapter 3.

2.3

all

GLOBAL VERSUS LOCAL DEFINITIONS FOR FDB OFFSETS

Although the FDB offsets can be defined either locally or globally,
the design of FCS does not require that you be concerned with the
definition of FDB offsets locally.
To some extent, this design
consideration is based on the manner in which MACR0-11 handles
symbols.
Whenever a symbol appears
in
the
source
program,
MACR0-11
automatically assumes that it is a global symbol unless it is
presently defined within the current assembly. Such a symbol must be
defined further on in the program; otherwise, it will be treated by
MACR0-11 as,a default global reference, requiring that it be resolved
by the Task Builder.
Thus, the question of global versus local symbols may simply be a
matter of the programmer's not defining the FDB offsets and bit values
locally in coding the program. Such undefined symbols thus become
global references, which are reduced to absolute definitions at
task-build time.
It should be noted that global symbols may be used as operands and/or
macro-call parameters anywhere in the source program coding, as
described in the following section.

2.3.1

Specifying Global Symbols in the Source Coding

Throughout the descriptions of the assembly-time macros (see Sections
2.2.1.2 through 2.2.1.6), global symbols are specified as parameters
in the macro calls. As noted earlier, such symbols are treated by
MACR0-11 as default global references.
For example, the global symbol FD.RAN may be specified as the initial
parameter in the FDRC$A macro call (see Section 2.2.1.3).
At
task-build time, this parameter is reduced to an absolute symbol
definition, causing a prescribed bit to be set in the record access
byte (offset location F.RACC) of the FDB.
Global symbols may also be used as operands in user
program
instructions to accomplish operations associated with FDB offset
locations. For example, global offsets such as F.RACC, F.RSIZ, and
F.RTYP may be specified as operands in the source coding. Assume, for
example, that an FDBDF$ macro call (see Section 2.2.1.1) has been
issued in the source program to allocate space for an FDB, as follows:
FDBIN:

FDBDF$

The coding sequence shown below may then appear in the source program,
illustrating the use of the global offset F.RACC:
MOV
MOVB

#FDBIN,RO
#FD.RAN,F.RACC(RO)

2-25

PREPARING FOR !/O
Note that the beginning address of the FDB is first moved into general
register zero {RO). However, if the desired value already exists in
RO as the result of previous action in the program, you need issue
only the second MOV instruction (which appropriately references RO).
As a consequence of this instruction, the value FD.RAN initializes FDB
offset location F.RACC.
An equivalent instruction is the following:
MOVB

#FD.RAN,FDBIN+F.RACC

which similarly initializes offset location F.RACC in the FDB with the
value of FD.RAN. Global symbols may be used anywhere in the program
in this manner to effect the dynamic storage of values within the FDB.

2.3.2

Defining FDB Offsets and Bit Values Locally

If you wish to declare explicitly that all FDB offsets and bit values
are to be defined locally, you can do so by invoking two macro calls
in the source program. The first of these, FDOF$L, causes the offsets
for FDBs to be defined within your program. Similarly, bit values for
all FDB parameters may be defined locally by invoking the FCSBT$ macro
call. You can invoke these macro calls anywhere in your program.
Vvben issued, the FDOF$L and FCSBT$ macro calls

define

syrflbols

manner roughly equivalent to:
F.RTYP
F.RACC
F.RSIZ

xx xx
xx xx
xx xx

where xxxx represents the value assigned to the corresponding symbol.
In other words, the macros for defining FDB offsets and bit values
locally do not generate any code. Their function is simply to create
absolute symbol definitions within the program at assembly time.
The
symbols so defined, however, appear in the MACR0-11 symbol table,
rather than in the source program listing.
Such local symbol
definitions are thereby made available to MACR0-11 during assembly,
rather than forcing them to be resolved by the Task Builder.
Whether the FDOF$L and FCSBT$ macro calls are invoked should not in
any way affect the coding style or the manner in which the FDB offsets
and bit values are used.
Note, however, if the FDOF$L macro call is issued, the NBOF$L macro
call for the local definition of the filename block need not be issued
{see Section 2.4.2). The FDOF$L macro call automatically defines all
FDB offsets locally, including those for the filename block.
If any of the above named macro calls is to be issued in your program,
it must first be listed as an argument in an .MCALL directive (see
Section 2.1).

2.4

CREATING FILE SPECIFICATIONS WITHIN THE USER PROGRAM

Certain information describing the file must be present in the FDB
before the file can be opened.
The file is located using a file
specification that contains the following:

2-26

PREPARING FOR I/O
1.

A device name and unit number.

A directory string consisting of a group number and a member
number that specify the User File Directory {UFD) to be used
for the file.
The term "UFD" is synonymous with the term
"file directory string" appearing throughout this manual.

A file name.

A file type (RSX-11} or file extension (IAS).

A file version number.

The term "file specifier" is sometimes used as
specification."

synonym

for

A file specification describing
the file
to be
processed
communicated to FCS through two user-created data structures:

"file
is

This tabular structure may be
The dataset descriptor.
initialized manually through the use of .WORD
created and
Section 2.4.1 describes this data structure in
directives.
detail.

The default filename block.
In contrast to the manually
created dataset descriptor,
the default filename block is
created by issuing the NMBLK$ macro call.
This macro call
allocates a block of storage in your program at assembly time
and initializes this structure with parameters supplied
in
the call.
This structure is described in detail in Section
2.4.2.

As noted in Section 2.2.1.5, the FDOP$A or the FDOP$R macro call
is
issued to
initialize the FDB with the addresses of these data
structures.
These address values are supplied to FCS through the dspt
and dfnb parameters of the selected macro call.
FCS uses these
addresses to access the fields of the dataset descriptor and/or the
default filename block for the file specification required in opening
a specified file.
By convention, a required file specification is first sought by FCS in
the dataset descriptor.
Any nonnull data contained therein
is
translated from ASCII to Radix-50 form and stored in the appropriate
offsets of the filename block.
This area of the FDB then serves as
the execution time repository for the information describing the file
to be opened and processed.
If the dataset descriptor does not
contain the required information, FCS attempts to obtain the missing
information from the default filename block.
If neither of these
structures contains the required information, an open failure occurs.
Note, however, that the device name and the unit number need not be
specified in either the dataset descriptor or the default filename
block, since these values are defaulted to
the device and
unit
assigned to the LUN at task-build time if not explicitly specified.
The FCS file-processing macro calls used
in opening files are
described
in Chapter 3, beginning with the generalized OPEN$x macro
call in Section 3.1.
For a detailed description of the format and content of
block, the reader should refer to Appendix B.

2-27

the

filename

PRF.PARTN~

2.4.1

FOR I/O

Dataset Descriptor

The dataset descriptor is often oriented toward the use of -a fixed
{built-in} file name in your program. A given application program,
for example, may require access only to a limited and nonvariable
number of files throughout its execution. By defining the names of
these files at assembly time through the dataset descriptor mechanism,
such a program, once initiated, executes to completion without
requiring additional file specifications.
This structure, a 6-word block of storage that you can create manually
within your program by using .WORD directives, contains information
describing a file that you intend to open during the course of program
execution.
In creating this structure, you can define any one or all
of three possible string descriptors for a particular file, as
follows:
1.

A 2-word descriptor for an ASCII device name string

A 2-word descriptor for an ASCII file direqtory string

A 2-word descriptor for an ASCII file name string

This data structure is allocated in
format:

Word 1 -

your

program

the

following

Contains the length (in bytes) of the ASCII device
name string.
This string consists of a 2-character alphabetic
device name, followed by an optional octal unit
number and an optional colon.
You can create
these strings by issuing statements such as those
below:

Word 2 -

DEVNM: ;ASCII

/DKO:/

DEVNM: .ASCII

/TTlO:/

Contains the address
string.

ASCII

device

name

Contains the length (in bytes) of the
directory string.

ASCII

file

the

DIRECTORY STRING DESCRIPTOR
Word 3 -

This string consists of a group number and a
member number, separated by a comma {,). The
entire string is enclosed in brackets.
For
example, [200,200] is a directory string. You can
create a directory string by issuing statements
such as those that follow:
DIRNM: .ASCII

/[200,200]/

DIRNM: .ASCII

/[40,100]/

If you wish to specify an explicit file directory
different
from the UIC under which you are
currently
running,
the
dataset
descriptor
mechanism permits that flexibility.
2-28

PREPARING FOR I/O
Word 4 -

Contains the address of the ASCII
string.

file

directory

FILENAME STRING DESCRIPTOR
Word 5 -

Contains the length (in bytes) of the
name string.

ASCII

file

This string consists of a file name up to 9
characters in length, an optional 3-character file
type designator, and an optional file version
number.
The file name and file type must be
separated by a dot (.), and the file version
number must be preceded by a semicolon. A file
name string may be created as shown below:
FILNM: .ASCII

/PROGl.OBJ;7/

For Files-11, only the characters A through z and
0 through 9 may be used in composing an ASCII file
name string.
An

ANSI

magnetic

tape

file

name

string

may

contain, in addition to the above, the following
special characters:
SP !

" % &

(

)

* +

< = > ?

A name that contains any of these characters must
be enclosed in quotation marks. If a quotation
mark is part of the name, the string must contain
two quotation marks. An ANSI file name string may
be created as shown below:
FILNM:

.ASCII /"PROG""2"";%&,";7/

The file name created in the above example is:
PROG"2";%&;

NOTE
Semicolon is a legal character
name
string.
To delimit a
number, the semicolon must be
the quoted string.
Word 6 -

Contains
string.

the

address

in the
version
outside

the

ASCII

file

name

A length specification of 0 in Word 1, 3, or 5 of the dataset
descriptor indicates that the corresponding device name, directory, or
file name string is not present in your program.
For example, the
coding below creates a dataset descriptor containing only a 2-word
ASCII file name string descriptor:
FDBOUT: FDBDF$
FDAT$A
FDRC$A
FDOP$A

;CREATES FDB.
R.VAR,FD.CR
;INITIALIZES FILE-ATTRIBUTE SECTION.
,RECBUF,80.
;INITIALIZES RECORD-ACCESS SECTION.
OUTLUN,OFDSPT ;INITIALIZES FILE-OPEN SECTION.

2-29

PRF.PARTNG FOR T/O

OFDSPT: .WORD
.WORD
.WORD

0,0
0,0
ONAMSZ,ONAM

;NULL DEVICE-NAME DESCRIPTOR.
;NULL DIRECTORY DESCRIPTOR.
;FILENAME DESCRIPTOR.

ONAM :
• ASCII
ONAMSZ=.-ONAM

/OUTPUT.DAT/

;DEFINES FILENAME STRING.
;DEFINES LENGTH OF FILENAME STRING.

Note first that an FDB labeled FDBOUT is created.
Observe further
that the FDOP$A macro call takes as its second parameter the symbol
OFDSPT. This symbol represents the address value stored in FOB offset
location F.DSPT.
This value enables the .PARSE routine (see Section
4.7.1) to access the fields of the dataset descriptor in building the
filename block.
The symbol OFDSPT also appears in the label field of the first
.WORD
directive, defining the address of the dataset descriptor for the
.PARSE routine. The .WORD directives each allocate two words of
storage for the device name descriptor, the file directory descriptor,
anu..

• '- -

LU~

r ~ , .L.LJ.~

-- - -- -

Ildill~

.!I -

~ - ._ - -.. -- .Lf:Jl..UL.,

u~::H :L

.I-. .: - - -

- •

Lt::~pt:1,,,;l...LVt::.L.Y.

In the example above, however, note that the first two descriptor
fields are filled with zeros, indicating null specifications. The
last .WORD directive allocates two words that contain the size and the
address of the file name string, respectively. The file name string
itself is explicitly defined in the .ASCII directive that follows.
Note that the statements defining the file name string need not be
physically contiguous with the dataset descriptor. For each such
ASCII string referenced in
the
dataset
descriptor,
however,

corresponding statements must appear elsewhere in the source program
to define the appropriate ASCII data string(s).
A dataset descriptor for each of several files to be accessed by
program may be defined in this manner.

2.4.2

your

Default Filename Block - NMBLK$ Macro Call

As noted earlier, you may also define a default filename block in the
program as a means of providing required file information to FCS. For
this purpose, you can issue the NMBLK$ macro call in connection with
each FDB for which a default filename block is to be defined. When
this macro call is issued, space is allocated within your program for
the default filename block, and the appropriate locations within this
data structure are initialized according to the parameters supplied in
the call.
Note in the parameter descriptions below that symbols of the form
N.xxxx are used to represent the offset locations within the filename
block. These symbols are differentiated from those that apply to the
other sections of the FOB by the beginning character N. All versions
of the generalized OPEN$x macro call
(see Section 3.1)
use these
~ymbols
to identify offsets in storing file information in the
filename block.

2-30

PREPARING FOR I/O
The NMBLK$ macro call is specified in the following format:
label:

NMBLK$ fnam,ftyp,fver,dvnm,unit

label
A user-defined symbol that names the default filename block and
defines its address.
This label is the symbolic value normally
specified as the dfnb parameter when the FDOP$A or the FDOP$R
macro call is issued.
This causes FDB offset location F.DFNB to
be initialized with the address of the default filename block.
f nam

The default file name.
This parameter may consist of up to nine
ASCII characters.
The character string is stored as six bytes in
Radix-50 format,
starting at offset location N.FNAM of the
default filename block.
f typ

The default file type.
This parameter may consist of up to three
characters.
Tne character string is stored as two bytes in
Radix-50 format in offset location N.FTYP of the default filename
block.

Ab~11

fver
The default file version number {binary). When specified,
this
binary value identifies a
particular version of a file.
This
value is stored in offset location N.FVER of the default filename
block.
dvnm
The default name of the device upon which the volume containing
the desired file
is mounted.
This parameter consists of two
ASCII characters that are stored in offset location N.DVNM of the
default filename block.
unit
A binary value identifying which unit {among several like units)
is to be used in processing the file.
If specified, this numeric
value is stored in offset location N.UNIT of the default filename
block.
Only the characters A through Z and 0 through 9 may be used
in
composing the file name and file type strings discussed above.
Although the file version number and the unit number discussed above
are binary values,
these numbers are normally represented in octal
form when printed, when input by a command string, or when supplied
through a dataset descriptor string.
As evident from the foregoing, all the default information supplied in
the NMBLK$ macro call
is stored
in the default filename block at
offset locations that correspond to identical fields in the filename
block within the FDB.
This default information is moved into the
corresponding offsets of the filename block when any version of the
generalized OPEN$x macro call
is issued under any of the following
conditions:
•

All the file information required by FCS to open the file
is
not present in the dataset descriptor. Missing information is
2-31

PREPARING FOR I/O
then sought in the default filename block by the .PARSE
routine (see Section 4.7.1), which is automatically invoked as
a result of issuing any version of the generalized OPEN$x
macro call.
•

A dataset descriptor has not been created in your program.

•

A dataset descriptor is present in your program, but the
address of this structure has not been made available to FCS
through any of the assembly-time or run-time macro calls that
initialize FDB offset location F.DSPT.

Th~ following coding illustrates the general method of specifying
NMBLK$ macro call:

the

FDBOUT: FDBDF$
FDAT$A
FDRC$A
FDOP$A

R.VAR,FD.CR
,RECBUF,80.
OUTLUN,,OFNAM

;ALLOCATES SPACE FOR AN FDB.
;INITIALIZES FILE-ATTRIBUTE SECTION.
;INITIALIZES RECORD-ACCESS SECTION.
;INITIALIZES FILE-OPEN SECTION.

FDBDF$
FDRC$A
FDOP$A

,RECBUF,80.
INLUN,, IFNAM

;ALLOCATES SPACE FOR AN FDB.
;INITIALIZES RECORD-ATTRIBUTE SECTION.
;INITIALIZES FILE-OPEN SECTION.

NMBLK$
NMBLK$

OUTPUT,DAT
;ESTABLISHES FILENAME AND FILE TYPE.
INPUT,DAT,,DT,l ;ESTABLISHES FILENAME, FILE TYPE,

FDBIN:

OFNAM:
IFNAM:

eT\li'UT("'li'
......
.....

,....,~

11.T'.aMli'
.lo'l.l..&.1..1 ..... ,

'.al\11"\

.. .a..&.'I~

flf\TT'l'
V.&.'l..a.. ...

11.lflMQli'D
.&.'IV& ...
e
..._.,.._.~,._

The first NMBLK$ macro call in the coding sequence above creates a
default filename block to establish default information for the FDB,
named FDBOUT. The label OFNAM in this macro defines the beginning
address of the default filename block allocated witttin your program.
Note that this symbol is specified as the dfnb parameter in the FDOP$A

macro

call

associated with this default filename block to initialize

the file open section of the corresponding FDB.
The accompanying
parameters in the first NMBLK$ macro call define the file name and the
file type, respectively, of the file to be opened;
all remaining
parameter fields in this call are null~
The second NMBLK$ macro call accomplishes essentially the same
operations in connection with the FDB, named FDBIN. Note in this
macro call that the third parameter (the file version number) is null,
as reflected by the extra comma. This null specification indicates
that the latest version of the file is desired. All other parameter
fields contain explicit declarations defining default information for
the applicable FDB.
You can define the offsets for a filename block locally
program, if desired, by issuing the following macro call:

your

NBOF$L
This macro call does not generate any code.
Its function is merely to
define the filename block offsets locally, presumably to conserve
symbol table space at task-build time. The NBOF$L macro call need not
be issued if the FDOF$L macro call has been invoked, since the
filename block offsets are defined locally as an automatic result of
issuing the FDOF$L macro call.
If desired, you may initialize fields in the default filename block
directly with appropriate values.
This may be accomplished with
in-line statements in the program. For example, a specific offset in
the default filename block may be initialized through coding that is
logically equivalent to the following:
2-32

PREPARING FOR I/O

DFNB:

NMBLK$

RSXLIB,OBJ

NUTYP:

.RAD50

/DAT/

MOV

NUTYP,DFNB+N.FTYP

where the symbol NUTYP in the MOV instruction represents the address
of the newly defined Radix-50 file type DAT, which is to be moved into
destination offset N.FTYP of the default filename block labeled DFNB.
You can manually initialize any of the offsets within the default
filename block in this manner to establish desired values or to
override previously initialized values.
NOTE
The NMBLK$ macro cannot be used to
create
a
file
name
containing
non-Radix-50 characters or a file name
that is not in the normal FILNAME.TYP
format. A program that uses the file
name format permitted for ANSI magnetic
tape must set up the file name in a
dataset descriptor.

2.4.3

Dynamic Processing of File Specifications

If you wish to make use of routines available from the system object
library
([l,l]SYSLIB.OLB)
for
processing
command
line input
dynamically, you should consult Chapter 6. Chapter 6 describes the
Get Command Line
(GCML)
routine and the Command String Interpreter
(CSI), both of which may be linked with your program to provide all
the logical capabilities required in processing dynamic terminal input
or indirect command file input.

2.5

OPTIMIZING FILE ACCESS

When certain information is present in the filename block of an FOB, a
file can be opened in a manner referred to throughout this manual as
"opening a file by file ID." This type of open requires a minimum of
system overhead, resulting in a significant increase in the speed of
preparing a file for access by your program.
If files are frequently
opened and closed during program execution, opening files by file ID
accomplishes substantial savings in overall execution time.
To open a file by file ID, the m1n1mum information that must be
present in the filename block of the associated FOB consists of the
following:
1.

File Identification Field. This 3-word field, beginning at
filename block offset location N.FID, contains a file number
in the first word and a file sequence number in the second
word;
the third word is reserved. The file identification
field is maintained by the system and ordinarily need not be
of concern to you.

2-33

PREPARING FOR IiO
2.

Device Name Field.
This 1-word field at filename block
offset location N.DVNM contains the 2-character ASCII name of
the device on which the volume containing the desired file is
mounted.

Unit Number Field.
This 1-word field at filename block
offset location N.UNIT contains a binary value identifying
the particular unit (among several like units) on which the
volume containing the desired file is mounted.

These three fields are written into the filename block in one of three
ways:
1.

As a function of issuing any version of the generalized
OPEN$x macro call for a file associated with the FDB in
question.

As a result of initializing the filename block manually by
using the .PARSE routine (see Section 4.7.1) and the .FIND
routine (see Section 4.8.1).

You manually move the
block.

necessary

values

into

the

filename

Opening an existing file by file ID is a

special

case

(see

Section

3. 5) •

2.5.1

Initializing the Filename Block As a Function of OPEN$x

To understand how to effect the process of opening a file by file ID,
note that the initial issuance of the aeneralized OPEN$x macro call
(see Section 3.1) for a given file first invokes the .PARSE routine
(see Section 4.7.1). The .PARSE routine is automatically linked into
your program, along with the code for OPEN$x.
This routine first
zeros the filename block and then fills it in with information taken
from the dataset descriptor and/or the default filename block.
Thus, issuing the generalized OPEN$x macro call results in the
invocation of the .PARSE routine each time a file is opened. The
.PARSE function, however, can be bypassed altogether in subsequent
OPEN$x calls by saving and restoring the filename block before
attempting to reopen that same file.
This is made possiqle because of the logic of the OPEN$x macro call.
Specifically, after the initial OPEN$x for a file has been completed,
the necessary context for reopening that file exists within the
filename block.
Therefore, before closing that file, the entire
filename block can be copied into user memory space and later restored
to the FDB at the desired point in program flow for use in reopening
that same file.
The option to reopen files in this manner stems from the fact that FCS
is sensitive to the presence of any nonzero value in the first word of
the file identification field of the filename block. When the OPEN$x
function is invoked, FCS first examines offset location N.FID of the
filename block. If the first word of this field contains a value
other than O, FCS logically assumes that the remaining context
necessary for opening that file is present in the filename block, and
therefore unconditionally opens that file by file ID.

2-34

PREPARING FOR I/O
To ensure that an undesired value does not remain in the first word of
the N.FID field from a previous OPEN$x/CLOSE$ sequence, the first word
of this field is zeroed as the file is closed.
In opening files by file ID, you need only ensure that manual saving
and restoring of the filename block are accomplished with in-line MOV
instructions that are consistent with the desired sequence
of
processing files.
This process should, in general, proceed as
outlined below:
1.

Open the file in the usual manner by issuing the OPEN$x macro
call.

Save the filename block by copying it into user memory space
with appropriate MOV instructions. The filename block begins
at offset location F.FNB.
The value of the symbol S.FNB is the size of the filename
block in bytes, and the value of the symbol SaFNBW is the
size of the filename block in words. If desired, the NBOF$L
macro call (see Section 2.4.2) may be invoked in your program
to define these symbols locally. These symbolic values may
be used in appropriate MOV instructions to accomplish the
saving and restoring of the filename block.
Moreover, you
must reserve sufficient space in the program for saving the
filename block.

At the end of current file operations, close the file in
usual manner by issuing the CLOSE$ macro call.

the

When, in the normal flow of program logic, that same file is
about to be reopened, restore the filename block to the FDB
by doing the reverse of step 2.

Reopen the file by issuing any one of the macro calls
available in FCS for opening an existing file. Since the
first word of offset location N.FID of the filename block now
contains a nonzero value, FCS unconditionally opens the file
by file ID, regardless of the specific type of open macro
call issued.

Although it is necessary to save only the file identification, device
name, and unit number fields of the filename block in anticipation of
reopening a file by file ID, you are advised to save the entire
filename
block.
The file name, file type, file version, and
directory-ID fields, and so forth, may also be relevant. For example,
an OPEN$x, save, CLOSE$, restore, OPEN$x, and DELET$ sequence would
require saving and restoring the entire filename block.
Though you
may be logically finished with file processing and may want to delete
the file, the delete operation will not work properly unless the
entire filename block has been saved and restored.

2.5.2

Manually Initializing the Filename Block

In addition to saving and restoring the filename block in anticipation
of reopening a file by file ID, the filename block can also be
initialized manually. If you choose to do so, the .PARSE and .FIND
routines (see Sections 4.7.1 and 4.8.1, respectively} may be invoked
at appropriate points to build the required fields of the filename
block.
After the .PARSE and .FIND logic is completed, all the
information required for opening the file exists within the filename
block.
When any one of the available FCS macro calls that open
2-35

PREPARING FOR I/O
existing files is then issued, FCS unconditionally opens that file
file ID.

Occasionally, instances arise that make such manual
operations
desirable, especially if your program is operating in an overlaid
environment. In this case, it is highly desirable that the code for
opening a file be broken into small segments in the interest of
conserving memory space. Since the body of code for the OPEN$x and
.PARSE functions is sizable, two other types of macro calls for
opening files are provided for use with overlaid programs. The OFID$
and OFNB$ macro calls (see Sections 3.5 and 3.6, respectively) are
specifically designed for this purpose.
The structure recommended for an overlaid environment is to have
either the OFID$ or the OFNB$ code on one branch of the overlay and
the .PARSE and .FIND code on another branch. Then, if you wish to
open a file by file ID, the .PARSE and .FIND routines can be invoked
at will to insert required information in the filename block before
opening the file.
The OFID$ macro call can be issued only in connection with an existing
file.
The OFNB$ macro call, on the other hand, may be used for
opening either an existing file or for creating and opening a new
file.
In addition, the OFNB$ macro call requires only the manual
invocation of the .PARSE routine to build the filename block before
opening the file.
If conservation of memory is an objective, and if your program will be
opening both new and existing files, it is recommended that only the
OFNB$ routine be included in one branch of the overlay; including the
OFID$ routine would needlessly consume memory space.
In all cases, however, it is important to note that all the macro
calls for opening existing files are sensitive to the presence of any
nonzero value in the first word (N.FID) of the filename block.
If
this
field
contains
any
value
other than O, the file is
unconditionally opened by file ID. This does not imply, however, that
uu~y
the file identification field (N.FID) is required to open the
file in this manner. The device name field (N.DVNM) and the unit
number field (N.UNIT) must also be appropriately initialized. The
logic of the FCS macro calls for opening existing files assumes that
these other required fields are present in the filename block if the
file identification field contains a nonzero value.
Because many programs continually reuse FDBs, the CLOSE$ function (see
Section 3.8) zeros the file identification field (N.FID) of the
filename block. This action prevents the field (which pertains to a
previous operation) from being used mistakenly to open a file for a
current operation. Thus, if a user later intends to open a file by
file ID using information presently in the filename block, the entire
filename block (not just N.FID) must be saved before closing the file.
Then, at the appropriate point in program flow, the filename block may
be restored to open the desired file by file ID.

2.6

INITIALIZING THE FILE STORAGE REGION

The file storage region (FSR) is an area allocated in your program as
a buffer pool to accommodate the program's block buffer requirements
in performing record I/O (GET$ and PUT$) operations. Although the FSR
is not applicable to block I/O (READ$ and WRITE$) operations, you must
issue the FSRSZ$ macro once in every program that uses FCS, regardless
of the type of I/O to be performed.
2-36

PREPARING FOR I/O
The macro calls associated with the
described below.

2.6.1

initialization

the

FSR

are

FSRSZ$ - Initialize FSR at Assembly Time

The MACR0-11 programmer establishes the size of the FSR at assembly
time by issuing an FSRSZ$ macro call.
This macro call does not
generate any executable code.
It merely allocates space for a
block-buffer pool in a program section named $$FSR1.
The amount of
space allocated depends on information provided by you, or defaulted,
during the macro call.
NOTE
The FSRSZ$ macro allocates the
FCS
impure area that is pointed to by a
fixed location in user virtual memory.
This
pointer
is
not altered when
overlays are loaded;
therefore, the
FSRSZ$ macro must be invoked in the root
segment of
a
task.
Unpredictable
results may occur if the FSRSZ$ macro is
invoked in more than
one
parallel
overlay.
The format of the FSRSZ$ macro is:
FSRSZ$

fbufs,bufsiz,psect

fbuf s
A numeric value that you establish as follows:
1.

If no record I/O processing is to be done, fbufs equals o.
A value of 0 indicates that an unspecified number of files
may be open simultaneously for block I/O processing.
For
example, if you intend to access three files for block I/O
operations and no files for record I/O operations, the
FSRSZ$ macro call takes 0 as an argument, as shown below:
FSRSZ$

No other parameters need be specified unless the function
of the psect parameter (described below) is required.
2.

If record I/O, using a single buffer for each file, is to
be done, fbufs represents the maximum number of files that
can be open simultaneously for record I/O processing. For
example,
an
RSX-llM
user
might
want
to access
simultaneously three files for block I/O and two files for
record I/O. This user would specify the following FSRSZ$
macro call:
FSRSZ$

Additional parameters, bufsiz and psect (described below),
could also be specified as required.
3.

If record I/O with multiple buffering is to be done, fbufs
represents the maximum number of buffers ever in use
2-37

nn~n•nT~~

.,~..., ... ~ .. ~ ...

~"n

4 V£\

Tl"
... ,

simultaneously among all files open concurrently for
record I/O.
Assume, for example, that your program will
simultaneously access four disk files for record I/O
operations. Assume further that you want double-buffering
for three of the disk files and have, therefore, specified
a multiple buffer count of 2 in the FDBF$A macro calls
(refer to Section 2.2.1.6) for the associated files.
You
would then issue the following FSRSZ$ macro call:
FSRSZ$

This macro call indicates that a maximum of seven buffers
will be in use simultaneously. This total is calculated
as follows: one buffer for the single-buffered file and
two buffers for each of the three double-buffered files.
Additional parameters, bufsiz and psect (described below),
could also be specified as required.
bufsiz
A numeric value defining the total block buffer pool space (in
bytes) needed to support the maximum number of files that can be
open simultaneously for record I/O.
If this parameter is
omitted, FCS obtains a total block buffer pool requirement by
multiplying the value specified in the fbufs parameter with a
default buffer size of 512 bytes. If, for example, a maximum of
two single-buffered disk files will be open simultaneously for
record I/O, either of the following FSRSZ$ macro calls could be
issued:
FSRSZ$

FSRSZ$

2,1024.

If you wish to explicitly specify block buffer pool requirements,
the following formula must be applied:
bufsiz={bsizel*mbcl) [+(bsize2*mbc2) ••• +{bsizen*mbcn)]
bsizel,bsize2, ••• ,bsizen
The sizes, in bytes, of the buffers to support each file. The
size of a buffer for a particular file depends on the device
supporting the file if the standard block buffer size is used.
Standard block sizes for devices are established at system
generation time.
The override block buffer size (ovbs)
parameter can be used in the FDBF$x macro call to increase
buffer size, as described in Section 2.2.1.6; these increases
must be considered when you explicitly specify block buffer
pool requirements.
mbcl,mbc2, ••• ,mbcn
The multiple buffer counts (refer
specified for the respective files.

Section

2.2.1.6)

The total value expressed by the bufsiz parameters must always
represent the worst case buffer pool requirements among all
combinations of simultaneously open record I/O files.
The
number of files (or buffers) representing the worst case is
expressed as the first parameter of the macro call.

2-38

PREPARING FOR I/O
NOTE
An IAS or RSX-llD user must not allocate
an
FSR
block
buffer
less
than
512(decimal) bytes in length for spooled
output to a record-oriented device (such
as a line printer).
psect
The name of the program section (PSECT) to which control returns
ar~er
FSRSZ$ completes processing.
If no name is specified,
control returns to the blank PSECT.

2.6.2

FINIT$ - Initialize FSR at Run Time

In addition to the FSRSZ$ macro call described in the preceding
section, the FINIT$ macro call must also be issued in a MACR0-11
program to call initialization coding to set up the FSR.
This macro
call takes the following format:
label:

FINIT$

label
An optional user-specified symbol that allows control to be
transferred to this location during program execution. Other
instructions in the program may reference this label, as in the
case of a program that has been written so that it can be
restarted. Considerations relative to the FINIT$ macro call in
such a restartable program are presented below.
The FINIT$ macro call should be issued in the program's initialization
code.
The first FCS call issued for opening a file performs the FSR
initialization implicitly (if it has not already been accomplished
through an explicit invocation of the FINIT$ macro call). However, it
is necessary, in the case of a program that is written so that it can
be restarted, to issue the FINIT$ macro call in the program's
initialization code, as shown in the second example below.
This
requirement derives from the fact that such a program performs all its
initialization at run time, rather than at assembly time.
For example, a program that is not written so that it can be restarted
might accomplish the initialization of the FSR implicitly through the
following macro call:
START:

OPEN$R

#FDBIN

;IMPLICITLY INITIALIZES THE FSR
;AND OPENS THE FILE.

In this case, although transparent to you, the OPEN$R macro call
automatically invokes the FINIT$ operation. The label START is the
transfer address of the program.
In contrast, a program that embodies the capability to be restarted
must issue the FINIT$ macro call explicitly at program initialization
in the manner shown below:
START:

FINIT$
OPEN$R

#FDBIN

;EXPLICITLY INITIALIZES THE FSR AND
;OPENS THE FILE.

2-39

PREPARING FOR I/O
In this case, the FINIT$ macro call cannot be invoked arbitrarily
elsewhere
in
the
program;
it
must
be issued at program
initialization. Doing so forces the appropriate reinitialization of
the FSR, whether or not it has been done in a previous execution of
the program through an OPEN$x macro call.
Also important in the above context is the fact that calling any of
the file control routines described in Chapter 4, such as .PARSE,
first requires the initialization of the FSR.
However, the FINIT$
operation must be performed only once each program execution. Note
also that FORTRAN programs issue a FINIT$ macro call at the beginning
of the program execution; therefore, MACR0-11 routines used with the
FORTRAN object time system must not issue a FINIT$ macro call.

2.7

INCREASING THE SIZE OF THE FILE STORAGE REGION

Procedures for increasing the size of the FSR for either MACR0-11
FORTRAN programs are presented in the following sections.

2.7.1

FSR-Extension Procedures for MACR0-11 Programs

To increase the size of the FSR for a MACR0-11 program, you
options:

have

two

Modify the parameters in the FSRSZ$ macro call to redefine
the buffer pool requirement of files open simultaneously for
record I/O processing. Reassemble the program.

Use the EXTSCT (extend program section) command at task-build
time to define the new size of the FSR. To invoke this
option, the command is specified in the following form:
EXTSCT = $$FSRl:length

$$FSR1
The symbolic name of the program section within the FSR that is
reserved for use as the block buffer pool length. A·numeric
value defining the total required size of the buffer pool in
bytes.
The size of the FSR cannot be reduced at

ta~k-build

time.

In calculating the total length of the FSR, you can use either of
formulas below:
1.

Length

(S.BFHD*fbufs)+bufsiz

Length

fbufs*(S.BFHD+512.)

the

S.BFHD
A symbol that defines the number of bytes required for each block
buffer header.
If desired, you can define this symbol locally in
your program by issuing the following macro call:
BDOFF$

DEF$L

2-40

PREPARING FOR I/O

fbuf s
A numeric value representing either the maximum number of files
open simultaneously for record I/O (when single buffering only is
used) or the maximum number of buffers ever in use simultaneously
among all files open concurrently for record I/O (when multiple
buffering is used).
Refer also to the description of this
parameter in the FSRSZ$ macro call in Section 2.6.1.
bufsiz
A numeric value defining the total block buffer pool space
(in
bytes)
needed to support the maximum number of files that can be
open simultaneously for record I/O.
Refer to the description of
this parameter in the FSRSZ$ macro call in Section 2.6.1.
512.
The standard default buffer size.
The EXTSCT command is described in detail
Reference Manual of the host operating system.

2.7.2

the

Task

Builder

FSR-Extension Procedures for FORTRAN Programs

For a FORTRAN program, if an explicit ACTFIL statement is not issued
in the optional keyword input to the Task Builder, an ACTFIL statement
with a default value of 4 is generated automatically during Lask
build.
To extend the size of the FSR at task-build time, you can
issue the following command:
ACTFIL = files
files
A decimal value defining the maximum number of files that may
open simultaneously for record I/O processing.

This command, similar to the EXTSCT command above, causes program
section $$FSR1 to be extended by an amount sufficient to accommodate
the number of active files anticipated for simultaneous use by the
program.
The size of the FSR for a FORTRAN program can also be decreased at
task-build time.
As noted above,
for either IAS or RSX-11, the
default value for the ACTFIL command is ~.
Thus, if O, 1, 2, or 3 is
specified as the "files" parameter, the size of $$FSR1 (the FSR block
buffer pool) is reduced accordingly.
The ACTFIL command is described in detail
Reference Manual of the host operating system.

2.8

the

Task

Builder

COORDINATING I/O OPERATIONS

In the IAS/RSX-11 environment, user programs perform
all
I/O
operations by issuing GET$/PUT$ and READ$/WRITE$ macro calls (see
Chapter 3). These calls do not access the physical devices in the
system directly.
Rather, when any one of these calls is issued, an
I/O-related system directive called QUEUE I/O is invoked as the
interface between the FCS file-processing routines at the user level
2-41

PREPARING FOR IiO
and the system I/O drivers at the device level.
Device drivers are
included for all the standard I/O devices supported by IAS and RSX-11
systems. Although transparent to the user, the QUEUE I/O directive is
used for all FCS file access operations.
When invoked, the QUEUE I/O directive instructs the system to place an
I/O request for the associated physical device unit into a queue of
priority-ordered requests for that unit.
This request is placed
according to the priority of the issuing task. As required system
resources become available, the requested I/O transfer takes place.
As implied above, two separate and distinct processes are involved
accomplishing a specified I/O transfer:
1.

The successful queuing of the GET$/PUT$ or
request

The successful completion
operation.

the

READ$/WRITE$

requested

data

in
I/O

transfer

These processes, both of which yield success/failure indications that
may be tested by your program, must be performed successfully in order
for the specified I/O operation to have been completed.
It is
important to note that FCS totally synchronizes record I/O operations
for you, even in the case of multiple-buffered operations.
In the
case of block I/O operations, the flexibility of FCS allows you to
synchronize all block I/O activities, thus enabling you to satisfy
logical processing dependencies within the program.

2.8.1

Event Flags

I/O operations proceed concurrently with other system activity. After
an I/O request has been queued, the system does not force an implied
wait for the issuing task until the requested operation is completed.
Rather, the operation proceeds in parallel with the execution of the
issuing task, and it is the taskis responsibility to synchronize the
execution of I/O requests.
Tasks use event flags in synchronizing
these activities. With respect to event flags,
the system merely
executes primitive operations that manipulate, test, and/or wait for
these indicators of internal task activity.
The completion of an I/O transfer, for example, is recognized by the
system as a significant event.
If you have specified a particular
event flag to be used by the task in coordinating I/0-completion
processing, that event flag is set, causing the system to evaluate the
eligibility of other tasks to run. Any event flag from 1 through
32(decimal) may be defined for local use by the task.
If you have not
specified an event flag, FCS uses event flag 32(decimal) by default to
signal the completion of I/O transfers.
Specific FOB-initialization and I/O-initiating macro calls in FCS
enable you to specify event flags, if desired, that are unique to a
particular task and that are set and reset only as a result of that
task's operation.
For record I/O operations, such an event flag may be defined through
the efn parameter of the FDBF$A or the FDBF$R macro call (see Section
2.2.1.6 or 2.2.2, respectively).
For block I/O operations, an event flag may be declared through the
bkef parameter of the FDBK$A or the FDBK$R macro call (see Section
2.2.1.4 or 2.2.2, respectively); alternatively, a block event flag
2-42

PREPARING FOR I/O
may
be
declared
through
the corresponding parameter of the
I/0-initiating READ$ or WRITE$ macro call (see Section 3.15 or 3.16,
respectively).
In both record and block I/O operations, the event flag is cleared
when the I/O request is queued and set when the I/O operation is
completed. In the case of record I/O operations, only FCS manipulates
the event flag. Additionally, the event flag's state is transparent
to the user, who must not issue a WAITFOR system directive predicated
on the event flag used for coordinating record I/O operations. A
record I/O operation, for example, may not even involve an I/O
transfer; rather, it may only involve the blocking or deblocking of a
record within the FSR block buffer. On the other hand, the event flag
defined for synchronizing block I/O operations is totally under your
control.
Also, a code indicating the success or failure of the QUEUE I/O
request resulting from the READ$/WRITE$ macro call is returned to the
Directive Status Word ($DSW). If desired, symbolic location $DSW may
be
tested
to determine the status of the I/O request.
The
success/failure codes for the QUEUE I/O directive are listed in the
manuals referenced above.
Event flag directives are described in the RSX-llM/M-PLUS Executive
Reference Manual. The relationship of event flags to specific devices
is described in the RSX-llM/M-PLUS I/O Drivers Reference Manual.

2.8.2

I/O Status Block

Because of the comparative complexity of block I/O operations, an
optional parameter is provided in the FDBK$A and the FDBK$R macro
calls, as well as in the READ$ and WRITE$ macro calls, that enables
the system to return status information to your task for block I/O
operations. The I/O status block is not applicable to record I/O
(GET$ or PUT$) operations.
This optional parameter, called the I/O status block address, is made
available to FCS through any of the macro calls identified above.
When this parameter is supplied, the system returns status information
to a 2-word block reserved in your program. Although the I/O status
block is used principally as a QUEUE I/O housekeeping mechanism for
containing
certain device-dependent information, this area also
contains information of particular interest to you.
Specifically, the second word of the I/O status block is filled in
with the number of bytes transferred during a READ$ or WRITE$
operation. When you are performing READ$ operations, it is good
practice always to use the value returned to the second word of the
I/O status block as the number of bytes actually read, rather than to
assume that the requested number of bytes was transferred. Employing
this technique allows the program to properly read virtual blocks of
varying length from a device such as a magnetic tape unit, provided
that the requested byte count is at least as large as the largest
virtual block.
For WRITE$ operations, the specified number of bytes
are always transferred; otherwise, an error condition exists.

2-43

PREPARING FOR 1/0
Also, the low-order byte of the first word of the I/O status block
contains a code that reflects the final status of the READ$/WRITE$
operation. The codes returned to this byte may be tested to determine
the status of any given block I/O transfer. The binary values of
these status codes always have the following significance:
Meaning

Code Value

I/O transfer completed.

I/O transfer still pending.
I/O error condition exists.

The format of the I/O status block and the error codes returned to the
low-order byte of its first word are described in detail in the !AS
Device Handlers Reference Manual or the RSX-llM/M-PLUS I/O Drivers
Reference Manual.
If the address of the I/O status block is not made available to FCS
(and hence to the QUEUE I/O directive) through any of the macro calls
noted above, no status information is returned to the I/O status
block.
In this case, the fact that an error condition may have
occurred during a READ$ or WRITE$ operation is simply lost.
Thus,
supplying the address of the I/O status block to the associated FDB is
highly desirable in order to facilitate normal error reporting.
An I/O status block may be defined in the user program at assembly
time through any storage directive logically equivalent to the
following:
IOSTAT: .BLKW

I OS TAT
A user-defined symbol naming the I/O status block and defining
its address.
This symbolic value is specified as the bkst
parameter in the FDBK$A or the FDBK$R macro call to initialize
FDB offset location F.BKST;
it may also be specified as the
corresponding parameter in the READ$ or the WRITE$ macro call.
Initializing this cell in the FDB is an integral part of issuing
the desired I/O request.

2.8.3

AST Service Routine

An asynchronous system trap (AST) is a software-generated interrupt
that causes the sequence of instructions currently being executed to
be interrupted and control to be transferred to another instruction
sequence elsewhere in the program. If desired, you may specify the
address of an AST service routine that is to be entered upon
completion of a block I/O transfer. Since an AST is a trap action, it
constitutes an automatic indication of block I/O completion.
The address of an AST service routine may be specified as an optional
parameter (bkdn)
in the FDBK$A or the FDBK$R macro call (see Section
2.2.1.4 or 2.2.2, respectively); this parameter may also be specified
in the READ$ or the WRITE$ macro call, initializing the FDB at the
time the I/O request is issued (see Section
3.15
or
3.16,
respectively).

2-44

PREPARING FOR I/O
Usually, an AST address is specified to enable a running task to be
interrupted in order to execute special code upon completion of a
block I/O request.
If the address of an AST service routine is not
specified, the transfer of control does not occur, and normal task
execution continues9
The main purpose of an AST service routine is to inform the user
program that a block I/O operation has been completed, thus enabling
the program to continue immediately with some other desired
{and
perhaps logically dependent)
operation
(for example, another I/O
transfer) •
If an AST service routine is not provided by tne user, some other
mechanism, such as event flags or the I/O status block, must be used
as a means of determining block I/O completion.
In the absence of
such a routine, for example, the user may test the low-order byte of
the first word in the I/O status block to determine if the block I/O
transfer has been completed. A WAIT$ macro call (see Section 3.17)
may also be issued in connection with a READ$ or WRITE$ operation to
suspend task execution until a specified event flag is set to indicate
the completion of block I/O.
Implementing an AST service routine in the user program is application
dependent and must be coded specifically to meet particular user
I/O~processing requirements.
A detailed discussion of asynchronous
system traps is beyond the scope of this document.
Refer to the
Executive Reference Manual of the host
operating
system
for
discussions of trap-associated system directives.
WARNING
Do not execute any FCS routines while in
an AST service routinee
FCS maintains
an impure data area that it uses as a
Directive
Parameter Block and as a
scratch area for directives.
An AST
could interrupt an FCS operation that is
altering this impure area.
Executing an
FCS routine in AST state could alter the
impure area and cause
unpredictable
results when task execution resumes.

2-45

CHAPTER 3
FILE-PROCESSING MACRO CALLS

You manipulate files through a set of file-processing macro calls.
These macro calls are invoked and expanded at assembly time. The
resulting code is then executed at run time to perform the operations
listed below:
OPEN$

- To open and prepare a file for processing

OPNS$

- To open and prepare a file for processing and to allow
shared access to that file (depending on the mode of
access)

OPNT$

- To create and open a temporary file for processing

OFID$

- To open an existing file using
information in the filename block

OFNB$

To open a file
filename block

using

file

name

file

identification

information

the

CLOSE$

- To terminate file processing in an orderly manner

GET$

- To read logical data records from a file

GET$R

- To read fixed-length records from a file in random mode

GET$S

- To read records from a file in sequential mode

PUT$

- To write logical data records to a file

PUT$R

- To write fixed-length records to a file in random mode

PUT$S

- To write records to a file in sequential mode

READ$

- To read virtual data blocks from a file

WRITE$

- To write virtual data blocks to a file

DE LET$

- To remove a named file from the associated volume
directory and to deallocate the space occupied by the
file

WAIT$

- To suspend program execution until
I/O operation is completed

requested

block

Most of the parameters associated with the file-processing macro calls
supply information to the FDB.
Such parameters cause MOV or MOVB
instructions to be generated in the object code, resulting in the
initialization of specific locations within the FDB.

3-1

FILE-PROCESSING MACRO CALLS
The final parameter in all file-processing macro calls is the symbolic
address of a user-coded, error-handling routine. This routine is
entered upon
detection
of
an
error
condition
during
the
file-processing operation. When this optional parameter is specified,
the following code is generated:
Code for macro

BCC
JSR

nn$
PC,ERRLOC

nn$:

;TESTS C-BIT IN PROCESSOR STATUS WORD.
;INITIATES ERROR-HANDLING ROUTINE
;AT "ERRLOC" ADDRESS.
;CONTINUES NORMAL PROGRAM EXECUTION.

where nn$ represents an automatically generated local symbol. If the
operation is completed successfully, the C-bit (carry condition code)
in the Processor Status Word is not set, and FDB offset location F.ERR
contains a positive value.
The BCC instruction then results in a
branch to the local symbol nn$ and the continuation of normal program
execution.
However, if an error condition is detected during the execution of the
file-processing routine, the C-bit in the Processor Status Word is
set, FDB offset location F.ERR contains a negative value (indicating
an error condition), and the branch to the local symbol nn$ does not
occur. Instead, the JSR instruction is executed, loading the PC with
the symbolic address (ERRLOC) of the error-handling routine and
initiating its execution.
If this optional .parameter is not specified, the error-processing
routine is not called, and you must explicitly test the C-bit in the
Processor Status Word to ascertain the status of thP- requested
operation.
Note that executing the FCS file-processing routines causes all
user-program general registers to be saved except RO, which by
convention is used by FCS to contain the address of the FDB associated
with the file being processed.

3.1

OPEN$X - GENERALIZED OPEN MACRO CALL

Before any file can be processed by your (or system) program, it must
first be opened. The type of action that you intend to perform on a
file is indicated to FCS by an alphabetic suffix accompanying the
macro name. For example, in issuing the generalized macro call
OPEN$x
x represents any one of the following alphabetic suffixes, each of
which denotes a specific type of processing anticipated for the file:
R

- Read an existing file

W - Write (create) a new file
M - Modify an existing file without changing its length
U

- Update an existing file and extend its length, if necessary

- Append (add) data to the end of an existing file

3-2

FILE-PROCESSING MACRO CALLS
NOTE
You can issue the generalized OPEN$x
macro call without an alphabetic suffix.
In this case, the type of action to be
performed on the file is indicated to
FCS through an additional parameter in
the macro call. This value, called the
file access (face) parameter, causes
offset location F.FACC in the associated
FDB to be initialized.
Section 3.7
describes this macro call in detail.
Depending on the alphabetic suffix supplied in the OPEN$x macro call,
certain other types of operations may or may not be allowed, as noted
below:
1.

If R is specified (for reading an existing file), that file
cannot also be written; that is, a PUT$ or WRITE$ operation
cannot be performed on that file.

If M or U is specified (for modifying or updating an existing
file), that file can be both read and written; that is,
concurrent GET$/PUT$ or READ$/WRITE$ operations can
be
performed on that file.

If M is specified (for modifying an existing file), that file
cannot be extended.

If W or A is specified (for creating a new file or appending
data to an existing file), that file can be read, written,
and/or extended.

The program that is issuing the OPEN$x macro call must
have
appropriate access privileges for the specified action. Table 3-1
summari~es the access privileges for the various forms of
the OPEN$x
macro call. This table also shows where the next record or block will
be read or written in the file after it is opened.
Table 3-1
File Access Privileges Resulting from OPEN$x ~aero Call
MACRO

ACCESS PRIVILEGES

POSITION OF FILE AFTER OPEN$x

OPEN$R

Read

First record of existing file

OPEN$W

Read, write, extend

First record of new file

OPEN$M

Read, write

.L".J..LW\...

OPEN$U

Read, write, extend

First record of existing file

OPEN$A

Read, write, extend

End of existing file (For
special PUT$R considerations,
see Section 3.13.)

t:'.; ..... '-"" ....

record of

ov
i C! +- i nrr
'-rllo ....... """' ... &&"::1

file

When any form of the OPEN$x macro call is issued, FCS first fills in
the filename block with file name information retrieved from the
dataset descriptor (see Section 2.4.1). FCS gains access to this data
structure through the address value stored in FDB offset location
F.DSPT.
3-3

FILE-PROCESSING MACRO CALLS
If any required data has been omitted from the dataset descriptor, FCS
attempts to obtain the missing information from the default filename
block. This data structure, which may also contain user-specified
file name information, is created in the program by issuing the NMBLK$
macro call (see Section 2.4.2). FCS gains access to this structure
through the address value stored in FDB offset location F.DFNB.
The address values in offset locations F.DSPT and F.DFNB can be
supplied to FCS through the FDOP$A macro call, the FDOP$R macro call,
or the OPEN$x macro call.
FCS requires access to the dataset
descriptor and/or the default filename block in retrieving file name
information used in opening files.
If a new file is to be created, the OPEN$W macro call is issued.
then performs the following operations:

FCS

Creates a new file
and
obtains
file
identification
information
for
the
file.
FCS
maintains the file
identification information in offset location N.FID of the
filename block.
The filename block in the FDB begins at
offset location F.FNB.

Initializes the file attribute section of the file header
block.
The file header block is a file system structure
maintained on the volume containing the file. Each file on a
volume has an associated file header block that describes the
attributes of that file. FCS obtains attribute information
for a new file from the FDB associated with the file. The
format and content of a file header block are presented in
detail in Appendix F.

Places an entry for the file in the User File Directory
(UFD).
Ifr howeverf an entry for a file having the same
name, type, and version number already exists in the UFD, the
old file is deleted. If a particular type of macro call is
issued explicitly specifying that the file not be superseded,
the old file is not deleted and an error code is returned.
This type of OPEN$ operation is described in Section 3.7.

Associates the assigned logical unit number
file to be created.

Allocates a buffer for the file from the FSR block buffer
pool if record I/O (GET$/PUT$) operations are to be used in
processing the file.

(LUN)

with

the

If an existing file is to be opened, any one of the following macro
calls may be issued:
OPEN$R, OPEN$M, OPEN$U, or OPEN$A. FCS then
performs the following operations:
1.

If file identification information is not present in the file
name
block,
FCS
constructs
the filename block from
information taken from the dataset descriptor and/or the
default filename block.
FCS then searches the UFD by file
name to obtain the required file identification information.
When found, this information is stored in the filename block,
beginning at offset location N.FID.

Associates the assigned logical unit number
file.

Reads the file header block and initializes the
file
attribute section of the FDB associated with the file being
opened.
3-4

(LUN)

with

the

FILE-PROCESSING MACRO CALLS
4.

Allocates a buffer for the file from the FSR block buffer
pool if record I/O (GET$/PUT$) operations are to be used in
processing the file.
NOTE
As described in
Section
2.6,
you
allocate
buffers through the FSRSZ$
macro call.
The number of
buffers
allocated is dependent upon the number
of files that you intend
to
open
simultaneously
for
record
I/O
operations.
If block I/O operations are to be used,
FOB
offset location F.RACC must be
initialized with the FO.RWM parameter by
the
FORC$A,
the
FORC$R,
or
the
generalized OPEN$x macro call.
This
parameter inhibits the allocation of a
buffer when the file is opened.

3.1.1

Format of Generalized OPEN$x Macro Call

The generalized macro call for opening files takes the following form:
OPEN$x

fdb,lun,dspt,racc,urba,urbs,err

x
The alphabetic suffix specified as part of the macro name,
indicating the desired type of operation to be performed on the
file.
The possible values for this parameter are:
R, W, M,
U,
or A (see Section 3.1).
f db

A symbolic value of the address of the associated FOB.
lun
The logical unit number (LUN) associated with the desired file.
This
parameter identifies the device on which the volume
containing the desired file is mounted.
Normally,
the logical
unit number associated with the file is specified through the
corresponding parameter of the FOOP$A or the FOOP$R macro call.
If so specified, the lun parameter need not be present in the
OPEN$x macro call. Each FOB must have a unique LUN.
dspt
The symbolic address of the dataset descriptor.
Normally, this
address value is specified through the corresponding parameter of
the FOOP$A or the FOOP$R macro call.
If so specified, this
parameter need not be present in the OPEN$x macro call.

3-5

FILE-PROCESSING MACRO CALLS
This parameter specifies the address of the manually created
dataset descriptor (see Section 2.4.1). If the Command String
Interpreter (CSI)
is being used to interpret command lines
dynamically, this parameter is used to specify the address of the
dataset descriptor within the CSI control block (see offset
location C.DSDS in Section 6.2.2).
race
The record access byte. One or more symbolic values may be
specified in this field to initialize the record access byte
(F.RACC) in the associated FDB. You can specify any combination
of the following parameters by separating them with exclamation
points:
e

FD.RWM - Indicates that block I/O (READ$/WRITE$) operations
are to be used in processing the file. If this parameter
is not specified, FCS assumes by default that record I/O
(GET$/PUT$) operations are to be used in processing the
file.

•

FD.RAN - Indicates that random access to the file is to be
used for record I/O (GET$/PUT$) operations.
If this
parameter is not specified, FCS uses sequential access by
default.
Refer to Section 1.5 for a description of random
access mode.

•

FD.PLC - Indicates that locate mode {see Section 1.6.2) is
to be used for record I/O (GET$/PUT$} operations. If this
parameter is not specified, FCS uses move mode (see Section
1.6.1) by default.

- Indicates that a PUT$ operation in sequential mode
in the body of a file shall not truncate the file.
Effectively, this parameter prevents the logical end of the
file from being reset to a point just beyond the inserted
record.
If this parameter is not specified, a PUT$
operation in sequential mode truncates the file to a point
just beyond the inserted record, but no deallocation of
file blocks occurs.
FD~INS

Specifying this parameter allows a data record in the body of the
file to be overwritten.
Care must be exercised, however, to
ensure that the record being written is the same length as that
of the record being replaced.
If the FD.RAN parameter above is specified, the file is accessed
in random mode.
In this case, a PUT$ operation in the file,
without exception, does not truncate the file.
If the record access byte in the FDB has already been initialized
through the corresponding parameters of the FDRC$A or the FDRC$R
macro call, the race parameters need not be present in the OPEN$x
macro call.
urba
The symbolic address of the user record buffer.
initializes FDB offset location F.URBD+2.

This

parameter

If the user record buffer address has already been supplied to
the FDB through the corresponding parameter of the FDRC$A or the
FDRC$R macro call, this parameter need not be present in the
OPEN$x macro call.
3-6

FILE-PROCESSING MACRO CALLS
urbs
A numeric value defining the size of the user record buffer
(in
bytes). This parameter initializes FDB offset location F.URBD.
If the size of your record buffer has already been supplied to
the FDB through the corresponding parameter of the FDRC$A or the
FDRC$R macro call, this parameter need not be present in the
OPEN$x macro call.

err
The symbolic address of an
routine.

optional

user=coded,

error-handling

Specific FDB requirements for record I/O operations
(GET$
macro calls) are detailed in Sections 3.9.2 and 3.12.2.

and

PUT$

The following examples depict representative uses of the OPEN$x
call.

macro

A macro call to open and modify an existing file, for
take the following form:

might

OPEN$M

example,

RO,#INLUN,,#FD.RAN!FD.PLC

Note in this macro call that the FDB address is assumed to be present
in RO. The third parameter, that is, the dataset descriptor pointer,
is not specified;
this null specification {indicated by the extra
comma)
assumes that FDB offset location F.DSPT {if required) has
already been initialized.
The last parameter, consisting of two
values separated by an exclamation point, establishes random access
and locate modes for GET$/PUT$ operations.
The following macro call might be issued to update an existing file:
OPEN$U

RO,#INLUN,,,#RECBUF,#80.

This macro call also assumes that the FDB address is in RO.
Note also
that the dspt and race parameter fields are null, based on the premise
that the dataset descriptor pointer
(F.DSPT)
has been provided
previously to the FDB and that the record access byte {F.RACC) has
also been previously initialized. Finally, the last two parameters
establish the address and the size, respectively, of the user record
buffer.
This last example shows a macro call that might
data to be appended to the end of a file:
OPEN$A

issued

allow

#OUTFDB

Thi~

macro call specifies the address of an FDB as the only parameter.
In this case, it is assumed that all other parameters required by FCS
in opening and operating on the file have been previously supplied to
the FDB through the appropriate assembly-time or run-time macro calls.

Note in all three examples above that the error
specified, requ1r1ng that you explicitly test
Processor Status Word to ascertain the success
operation.

3-7

parameter is not
the C-bit in the
of the specified

FILE-PROCESSING MACRO CALLS
NOTE
You can use RO only to pass the FDB
address parameter. Any other use of RO
when you issue the OPEN$A macro call
will fail.

FDB Requirements for Generalized OPEN$x Macro Call

3.1.2

The information required for opening a file may be supplied to the FDB
through the following macro calls:
•

The assembly-time macro calls described in Section 2.2.1

•

The NMBLK$ macro call described in Section 2.4.2

•

The run-time macro calls described in Section 2.2.2

•

The various macro calls described in this chapter for
files

opening

The particular combination of macro calls used to define
and
initialize the FDB is a matter of choice, as indicated above. Of far
greater significance is the fact that certain information must be
present in the FDB before the associated file can be opened. In this
regard, the following rules apply for creating and opening new files,
for opening existing files, and for specifying desired file options:
1.

To Create a New File. If a new file is to be created through
the OPEN$W macro call, the following information must first
be supplied to the FDB. You can specify this information
through the FDAT$A macro call (see Section 2.2.1.2) or the
FDAT$R macro call (see Section 2.2.2):
a.

The record type must be established for record I/O
operations. To accomplish ~n1s, you must initiaiize byte
offset location F.RTYP with the following
symbolic
values:
•

R.FIX - Indicates that fixed-length records are
be written into the file

•

R.VAR - Indicates that variable-length records
to be written into the file

are

•

R.SEQ - Indicates that sequenced records are to
written into the file

The desired record attributes must be specified for
record I/O operations. The record attributes are defined
by initializing byte offset location F.RATT with the
appropriate value(s), as follows:
- Indicates that the first byte- of each
• FD.FTN
record is to contain a FORTRAN carriage control
character.

3-8

FILE-PROCESSING MACRO CALLS

•

FD.CR - Indicates that a line-feed (<LF>) character
is to precede each record and that a carriage
return (<CR>) character is to follow the record
when that record is output to a device requiring
carriage control information (for example, to a
terminal).
The <LF> and <CR> characters are not
actually embedded within
the
record.
Their
presence
is
merely implied through the file
attribute FD.CR.

•

FD.BLK - Indicates that records are not allowed
cross block boundaries.

•

FD.PRN - Indicates that the record is preceded by a
word containing carriage control information.

If fixed-length records are to be written to the file,
you must specify the record size (in bytes) for record
I/O operations to appropriately initialize FOB offset
location F.RSIZ.

Items a. through c. above cannot be supplied to the FOB
through any of the various macros used to create and/or open
files (for example, OPEN$W,
OPEN$R,
and
so
forth).
Furthermore, none of the above information is required when
opening an existing file, since FCS obtains such information
from the first 14 bytes of the user file attribute section of
the file header block (see Appendix F).
2.

To Open Either a New File or an Existing File. Regardless of
whether the file being opened is yet to be created or already
exists, the following information must be present in the FOB
before that file can be opened:
a.

The record access byte
must
be
initialized
for
record/block I/O operations. The symbolic values below
may be specified in the FDRC$A macro call (see Section
2.2.1.3), the FDRC$R macro call (see Section 2.2.2), or
the generalized OPEN$x macro call to initialize FOB
offset location F.RACC:
e

FD.RWM - Indicates that READ$/WRITE$ (block I/0)
operations are to be used in processing the file.
If this parameter is not specified, GET$/PUT$
(record I/O) operations result by default.

•

FD.RAN - Indicates
that
random
access
mode
(GET$/PUT$ record I/O) is to be used in processing
the file. If this parameter is not specified,
sequential access mode results by default. Refer
to Section 1.5 for a description of random access
mode.

•

FD.PLC - Indicates that locate mode
(GET$/PUT$
record I/O)
is to be used in processing the file.
If this parameter is not specified, move mode
results by default.

3-9

FILE-PROCESSING MACRO CALLS
•

FD.INS - Indicates that a
PUT$
operation
in
sequential mode in the body of a file shall not
truncate the file.
If this parameter is not
specified, such an operation truncates the file.
In this case, the logical end of the file is reset
to a point just beyond the inserted record, but no
deallocation of file blocks occurs.

Your record buffer descriptors, (that is, the urba and
urbs parameters), must be specified for record I/O
operations. To accomplish this, the FDRC$A, the FDRC$R,
or the generalized OPEN$x macro call may be used. The
selected macro call defines the address and the size of
the area reserved in the program for use as a buffer
during record I/O operations.
The urba
and
urbs
parameters initialize FDB offset locations F.URBD+2 and
F.URBD, respectively.
FDB requirements specific to GET$ and PUT$ operations in
move and locate mode are presented in detail in Sections
3.9.2 and 3.12.2, respectively.

You must specify the logical unit number to initialize
FDB offset location F.LUN. Initializing this cell can be
accomplished with the lun parameter of the FDOP$A, the
FDOP$R, or the generalized OPEN$x macro call. Each FDB
must have a unique iogicai unit number.

If file identification information is not already present
in
the FDB, either the dataset descriptor pointer
(F.DSPT) or the default filename block address (F.DFNB)
must be specified to enable FCS to obtain required file
name information for use in opening the file.
These
address values may be specified in either the FDOPSA
macro call (see Section 2.1.1.5) or the FDOP$R macro call
(see Section 2.2.2). The generalized OPEN$x macro call
(see Section 3.1) may also be used to specify the dataset
descriptor pointer.

If desired, an event flag number for synchronizing record
I/O operations must be specified to initialize FDB offset
location F.EFN. This optional parameter may be specified
in either the FDBF$A macro call (see Section 2.2.1.6) or
the FDBF$R macro call (see Section 2.2.2).
If not
specified, FCS uses event flag number 32(decimal) by
default in synchronizing all record I/O activity.

Specifying Desired File Options.
If certain options are
desired for a given file, they must be specified before that
file is opened. Since this information is needed only in
opening the file, it is zeroed when the file is closed, thus
ensuring that the FDB is
properly
reinitialized
for
subsequent use.
The options that may be specified for a
given file are described below:
a.

The override block size (ovbs parameter)
must
be
specified in either the FDBF$A or the FDBF$R macro call
to initialize FDB offset location F.OVBS. This parameter
need be specified only if the standard default block size

3-10

FILE-PROCESSING MACRO CALLS
in effect for the associated device is to be overridden
or if the big-buffering or multiple-buffering versions of
FCS are in use. The override block size is specified to
improve I/O system throughput with record I/O, and with
record-oriented devices (such as line printers) and
sequential devices (such as magnetic tape units).
(See
Section 2.2.1.6.)
b.

The multiple buffer count (mbct parameter) must be
specified in either the FDBF$A or the FDBF$R macro call
to
initialize
FDB
offset
location
F.MBCT.
If
multiple-buffered record I/O operations are to be used,
this parameter must be greater than 1, and it must agree
with the desired number of buffers to be used. This
parameter is not overlaid, nor is it zeroed when the file
is closed.
If the multiple buffer count is not established as
described above, multiple-buffered operations can still
be invoked by changing the default buffer count in the
FSR.
A default buffer count of 1 is stored in symbolic
location .MBFCT of $$FSR2. This default value can be
altered to reflect the number of buffers intended for use
during record I/O operations.
The
procedure
for
modifying this cell in $$FSR2 is described at the end of
Section 2.2.1.6.
In addition, if multiple buffering is to be employed, the
appropriate control flaq must be specified as the mbfq
parameter in either the FDBF$A or the-FDBF$R macro call
to appropriately initialize FDB offset location F.MBFG.
Either of two symbolic values may be specified for this
purpose, as follows:
•

FD.RAH - Indicates that read-ahead
to be used in processing the file.

operations

are

•

FD.WBH - Indicates that write-behind operations are
to be used in processing the file.

Offset location F.MBFG need be initialized only if the
standard default buffering assumptions are inappropriate.
When a file is opened for reading (OPEN$R), read-ahead
operations are assumed by default; for all other forms
of OPEN$x, write-behind operations are assumed.
It may
be useful, for example, to override the write-behind
default assumption for a file opened through the OPEN$M
or the OPEN$U macro call when that file is being used
basically for sequential read operations, but scattered
updating is also being performed.
c.

To allocate required file space at the time a file is
created, the cntg parameter must be specified in either
the FDAT$A or the FDAT$R macro call.
This parameter
initializes FDB offset location F.CNTG. A positive value
so specified results in the allocation of a contiguous
file having the specified number of blocks; a negative
value, on the other hand, results in the allocation of a
noncontiguous file having the specified number of blocks.

3-11

The address of the 5-word statistics block in your
program must be moved manually into FOB offset location
F.STBK. This address value specifies an area in the user
program
to
which
FCS returns certain statistical
information about a file when it is opened.
If this
parameter is not specified, no return of such information
occurs.
The format and content of the statistics block are
presented in Appendix H. You can define such an area in
a program with coding logically equivalent to that shown
below:
STBLK:

.BLKW

Offset location F.STBK may then be manually
as follows:
MOV

initialized,

#STBLK,FDBADR+F.STBK

where STBLK is the user-defined symbolic address of the
statistics block, and the destination operand of this
instruction defines the appropriate offset
location
within the desired FDB.

3.2

OPNS$X - OPEN FILE FOR SHARED ACCESS

The OPNS$x macro call is issued to open a file for shared access.
This macro call has the same format, that is, takes the same
alphabetic suffixes and run-time parameters, as the generalized OPEN$x
macro call. The shared access conditions that result from the use of
this macro call are summarized in Section 1.8.

3.3

OPNT$W - CREATE AND OPEN TEMPORARY FILE

The OPNT$W macro call is issued to create and open a temporary file
for some special purpose of limited duration.
If a temporary file is
to be used only once, it is best created through the OPNT$D macro call
described in the following section.
The OPNT$W macro call creates a file but does not enter
for that file into any associated user directory file.

file

name

In using the OPNT$W macro call, you bear the responsibility for
marking the temporary file for deletion, as described in the procedure
below. Then, after all operations associated with that file are
completed, closing the file results in its deallocation. All space
formerly occupied by the file is then returned for reallocation to the
pool of available storage on the volume.
Although the OPNT$W macro call takes the same parameters as those of
the generalized OPEN$x macro call, the former executes faster because
no directory entries are made for a temporary file.
Creating a temporary file is usually done when a program requires a
file only for the duration of its execution (for example, for use as a
work file).
The general sequence of operations in such instances
proceeds as follows:

3-12

FILE-PROCESSING MACRO CALLS
1.

Open a temporary file by issuing the OPNT$W macro call.
Perform any desired operations on that file.
If the file is
to be used only for a single OPNT$W/CLOSE$ sequence, go to
step 6; otherwise, continue with step 2.

Before closing the file for processing, save the filename
block in the associated FDB.
The general procedure for
saving (and restoring) the filename block is discussed in
Section 2.5.1.

Close the file by issuing the CLOSE$ macro call (see Section
3.8). Continue other processing in the program, as desired.

In anticipation of reopening the temporary file, restore the
filename block to the FDB by accomplishing the reverse of
step 2 above.

Reopen the file by issuing any of the FCS macro calls that
open existing files.
Resume operations on the file;
repeat
the save, CLOSE$, restore, open sequence any desired number
of times.

Before closing the file the last time, call the .MRKDL
routine, as shown below, to mark the file for deletion:
CALL

.MRKDL

The .MRKDL routine is described in Section 4.13.1.

Close the file by issuing the CLOSE$ macro call.

If the filename block is not saved, the file identification field
therein is destroyed, since this field is reset to 0 when the file is
closed.
Thus, not saving the filename block before closing a temporary file
results in a "lost" file,
since no directory entry is made for a
temporary file.
The usual procedure of listing the volume's directory
is therefore inapplicable. The only way such a file can be recovered
is to use the File Structure Verification Utility program
(VFY)
to
search the volume's index file.
The VFY program has the capability to
compare the files listed in all the directories on the volume with
those listed in the index file.
If a file appears in the index file,
but not in a directory, VFY identifies that file for you.
This
program is described in detail in the IAS System Management Guide and
RSX-11 Utilities Manual.

3.4

OPNT$D - CREATE AND OPEN TEMPORARY FILE AND MARK FOR DELETION

The OPNT$D macro call is issued to create and open a temporary file:
This macro call is simply a convenient way to perform steps 1 and 6
above. A file marked for deletion cannot be opened by another
program.
Furthermore, when the file is closed, it is automatically
deleted from the volume, returning its space to the pool of available
storage on the volume for reallocation.
The presumption in issuing the OPNT$D macro call is that the file thus
created is to be used only once. This is a particularly desirable way
to open a temporary file, since the file will be deleted even if the
program terminates abnormally without closing the file.

3-13

The OPNT$D macro call takes the same format and parameters as those of
the generalized OPEN$x macro call.
NOTE
If the OPNT$D macro call is issued for
use with a temporary file containing
sensitive information, it is recommended
that you zero the file before closing
it, or reformat the disk to destroy the
sensitive
information.
{Although a
temporary file is deleted after use, the
information physically remains on the
volume until written over with another
file
and
could
be
analyzed
by
unauthorized users.)

3.5

OFID$X - OPEN FILE BY FILE ID

The OFID$x macro call is issued to open an existing file using
information stored in the file identification field (offset location
N.FID) of the filename block in the FDB (not in your default filename
block).
Thus,
issuing this macro call invokes an FCS routine that
opens a file only by file ID (see Section 2.5).
The OFID$x call,
which has the same format and takes the same parameters as those of
the generalized OPEN$x macro call (see Section 3.1), is designed for
use with overlaid programs.
In describing the functions of the OFID$x macro call,
two assumptions may apply, as follows:

either

one

That the necessary context for opening the file has been
saved from a previous OPEN$x operation and restored to the
filename block in anticipation of opening that file by file
iu.
Saving and restoring the filename block are discussed in
detail in Section 2.5.1.

That the desired file is to be opened for the first time.
In
that case, the necessary context for opening the file must
first be stored in the file name block before the OFID$ macro
call can be issued.

In most cases, the latter assumption
following procedures be performed:

applies,

requiring

that

the

Call the .PARSE routine {see Section 4.7.1).
This routine
takes information from a specified dataset descriptor and/or
default filename block, and initializes and fills in the
specified filename block.

Call the .FIND routine {see Section 4.8.1).
This routine
locates an appropriate directory entry for the file (by file
name) and stores the file identification information found
there in the 6-byte file identification field of the filename
block, starting at offset location N.FID.
As a result of
steps 1 and 2, the necessary context then exists in the
associated filename block for opening the file by file ID.

Issue the OFID$x macro call.

3-14

FILE-PROCESSING MACRO CALLS
The advantage in using the .PARSE and .FIND routines in conjunction
with the OFID$x macro call is that you can overlay the program,
placing .PARSE and .FIND on one branch, and the code for OFID$x on
another branch. This overlay structure reduces the program's overall
memory requirements.
Unlike the other FCS macro calls for opening files, the OFID$x macro
call requires a nonzero value in the first word of the file
identification field (N.FID) in order to work properly.
When this
field contains a nonzero value, FCS assumes that the remaining context
necessary for opening that file is present and, accordingly, opens the
file by file ID.
Opening an existing file by file ID for write
case.
Because it is intended to rewrite
following occur:

3.6

access is a special
the existing file, the

•

Any initial allocation (F.CNTG) is ignored.

•

File access byte (F.FACC) value NA.NSP (do not supersede file)
is ignored.

•

File access byte (F.FACC) value FA.CRE (create new file)
is
set even though the file is being rewritten rather than
created.

•

This operation may not be performed on ANSI magnetic tape.
The data in the file header labels is not changed when the
file is written.
See Section 5.2 for
information
on
positioning file on tape to rewrite a file in a particular
position.

OFNB$X OPEN FILE BY FILENAME BLOCK

The OFNB$x macro call is issued to open either an existing file or to
create and open a new file using file name information in the filename
block. Similar to the OFID$x macro call above, the OFNB$x call is
designed for use with overlaid programs. However, the OFNB$x macro
call differs in two important respects: it can be issued to create a
new file, and it can be issued to open a file by filename block.
The OFNB$x call has the same format and takes the same parameters as
those of the generalized OPEN$x macro call (as described in Section
3.1.1, as follows,
OFNB$x fdb,lun,dspt,racc,urba,urbs,err
The OFNB$x macro also uses the same suffixes that are available to the
OPEN$x macro:
OFNB$R, OFNB$W, OFNB$M, OFNB$U, OFNB$A. The suffixes
have the same meaning as they do for OPEN$x (see Table 3-1).
In describing the functions of the OFNB$x macro call, the same
assumptions outlined above for OFID$x apply, namely, that the filename
block has been saved and restored in anticipation of issuing the
OFNB$x macro call, or that the file is being opened for the first
time. Since the procedures for saving and restoring the filename
block are detailed in Section 2.5.1, the following discussion assumes
that the desired file is being opened for the first time.
In this
case, the filename block in the FDB must be initialized, as described
below.

3-15

FILE-PROCESSING MACRO CALLS
To open a file by filename block, the following
information
present in the filename block of the associated FDB:
1.

The file name (offset location N.FNAM}

The file type or extension {offset location N.FTYP)

The file version number {offset location N.FVER)

The directory ID (offset location N.DID)

The device name (offset location N. DVNM)

The unit number {offset location N.UNIT)

must

In providing the information above to the filename block, you can use
either of two general procedures, as described in the following
sections.

3.6.1

Dataset Descriptor and/or Default Filename Block

If the dataset descriptor contains all the required information listed
above, perform the following procedures:

,
.l..

1---

.L.'L.--··.a...:-- \.::>CC ....
C"--~.:-A-, 1 \
Thi::; routine
\..Q.l..l.
1..Uit::
.rn.nv.i:.o .L.VU'-.1.UC
C\,,'-.1.Vll
"S•
takes information from a specified dataset descriptor and/or
default filename block and fills in the appropriate offsets
of a specified filename block.
,,_,,

n1'nt""'t:t

..... ,

•

Issue the OFNB$x macro call.

Default filename Block Only

3.6.2

If a default filename block is to be used in providing
information to FCS, perform the following procedures:

the

required

Issue the NMBLK$ macro call {see Section 2.4.2) to create and
initialize a default filename block. With the exception of
the directory ID, this structure provides all the requisite
information to FCS.

To provide the directory ID, call
routines:

either

the

following

Call the .GTDIR routine {see Section 4.9.1)
to retrieve
the directory ID from the specified dataset descriptor
and to store the directory ID in the default file name
block

Call the .GTDID routine (see Section 4.9.2)
to retrieve
the default UIC from $$FSR2 and to store the directory ID
in the default file name block.

Move the entire default filename block manually into
filename block associated with the file being opened.

Issue the OFNB$x macro call.

3-16

the

FILE-PROCESSING MACRO CALLS
Note that the coding for OFNB$x operations normally resides in an
overlay apart from that containing the other FCS routines identified
above.
Issuing the OFNB$x macro call is usually done under the premise that
the filename block contains the requisite information, as described
above. However, if the file identification field
(offset location
N.FID) in the filename block contains a nonzero value when the call to
OFNB$x is issued, the file is unconditionally opened by file ID.
If you expect to open both new and existing files, and memory
conservation is an objective, the OFNB$x macro call is most suitable
for opening such files. The OFID$x coding should not be included in
the same overlay with OFNB$x, since OFID$x overlaps the function of
OFNB$x and, therefore, needlessly consumes memory space.

3.7

OPEN$ - GENERALIZED OPEN FOR SPECIFYING FILE ACCESS

Usually, when you wish to create a file, the file name and the file
type are specified, and FCS is allowed to assign the next higher file
version number. However, if the OPEN$W macro call is issued for a
file having an explicit file name, file type, and file version number,
and a file of that description already exists in the specified UFD,
the old file is superseded.
By issuing the OPEN$ macro call without an alphabetic suffix, and by
specifying two additional parameters, you can inhibit the automatic
superseding of a file when a duplicate file specification
is
encountered in the UFD. Rather than deleting the old version of the
file, an error indication (IE.DUP)
is returned to offset location
F.ERR of the applicable FDB.
All parameters of this macro call are identical to those specified for
the generalized OPEN$x macro call (see Section 3.1), with the
exception of the face parameter and the dfnb parameter.
These
additional parameters are described below. To open a file without
superseding an existing file having an identical file specification, a
macro call of the following form is used:
OPEN$

fdb,facc,lun,dspt,dfnb,racc,urba,urbs,err

f acc

Any one or an appropriate combination of the following symbolic
values indicating how the specified file is to be accessed:
•

FO.RD - Indicates that an existing file is to be opened for
reading only

•

FO.WRT - Indicates that a new file is
opened for writing

•

FO.APD - Indicates that an existing file is
and appended

opened

•

FO.MFY - Indicates that an existing file is
and modified

opened

•

FO.UPD - Indicates that an existing file is to
updated, and, if necessary, extended

opened,

3-17

created

and

FTLE-PROCESSTNG MACRO CALLS

•

FA.NSP - Indicates, in combination with FO.WRT above, that
the old file having the same file specification is not to
be superseded by the new file

•

FA.TMP - Indicates, in combination with FO.WRT above,
the file is to be a temporary file

•

FA.SHR - Indicates that the file is to be opened for shared
access

that

dfnb
The symbolic address of the default filename block.
This
parameter is the same as that described in connection with the
FDOP$A/FDOP$R macro call.
The above parameters initialize FOB offset locations F.FACC and F.DFNB
with appropriate values.
Any logically consistent combination of the above file access symbols
is permissible.
The particular combination required to create and
write a new file without superseding an existing file is shown below:
OPEN$

#OUTFDB,iFO.WRT!FA.NSP

The following macro call creates a temporary file for shared access:
OPEN$

iOUTFDB,iFO.WRT!FA.TMP!FA.SHR
NOTE
You can use RO

address

only

parameter.

pass

the

FDB

Any other use of RO

when you issue the OPEN$ macro call will
fail.

3.8

CLOSE$ - CLOSE SPECIFIED FILE

When the processing of a file is completed, you must close it by
issuing the CLOSE$ macro call.
The CLOSE$ operation performs the
following housekeeping functions:
1.

Waits for all I/O operations in progress for the file
completed {multiple-buffered record I/O only)

Ensures that the FSR block buffer, which contains data for an
output file, is completely written if it is partially filled
{record I/O only)

Deaccesses the file

Releases the FSR block
{record I/O only)

Prepares the FDB for subsequent use by
FDB off set locations

Calls an optional user-coded, error-handling routine if
error condition is detected during the CLOSE$ operation

buffer(s)

3-18

allocated

for

clearing

the

file

appropriate
an

FILE-PROCESSING MACRO CALLS
Note that I/O does occur in items 1 and 2 above.
Therefore, your
program should include error processing for CLOSE$ calls as it would
for calls to PUT$.
Issuing a CLOSE$ when a file is already closed resuits in a success
status code. Closing a file that is already closed is not an error.

3.8.1

Format of CLOSE$ Macro Call

The CLOSE$ macro call takes the following format:
CLOSE$

fdb,err

f db

A symbolic value of the address of the associated FDB.
err
The symbolic address of an
routine.

optional

user-coded,

error-handling

The following examples illustrate the use of the CLOSE$ macro call:
CLOSE$

#FDBIN,CLSERR

CLOSE$

,CLSERR

CLOSE$

The first example shows an explicit declaration for the relevant FDB,
and the symbolic address of an error-handling routine to be entered if
the CLOSE$ operation is not completed successfully.
The last two
examples assume that RO currently contains the address of the
appropriate FDB.

3.9

GET$ - READ LOGICAL RECORD

The GET$ macro call is used to read logical records from a file.
After a GET$ operation, the next record buffer descriptors in the FDB
always identify the record just read;
that is, offset location
F.NRBD+2 contains the address of the record just read, and offset
location F.NRBD contains the size of that record (in bytes). This is
true of GET$ operations in both move and locate mode.
In move mode, a GET$ operation moves a record to your record buffer
(as defined by the current contents of F.URBD+2 and F.URBD), and the
address and size of that record are then returned to the next record
buffer descriptors in the FDB (F.NRBD+2 and F.NRBD).
In locate mode, if the entire record resides within the FSR block
buffer, then the address and the size of the record just read are
returned to the next record buffer descriptors (F.NRBD+2 and F.NRBD).
If, on the other hand, the entire record does not reside within the
FSR block buffer, then that record is moved piecemeal into your record
buffer, and the address of your record buffer and the size of the
record are returned to offset locations F.NRBD+2
and
F.NRBD,
respectively.

3-19

FTT.F.-PROCF.88TN(; MACRO CALLS

After returning from a GET$ operation in locate mode, regardless of
whether moving the record was necessary, F.NRB0+2 always contains the
address of the record just read, and F.NRBO always contains the size
of that record.
If the record read was a sequenced record, the sequence number is
stored in F.SEQN regardless of whether the GET$ was in move mode or
locate mode.
GET$ operations are fully synchronous; that is, record I/O operations
are completed before control is returned to your program.
Specific FOB requirements for GET$ operations are presented in Section
3.9.2 below.

3.9.l

Format of GET$ Macro Call

To read a logical record, the GET$ macro
following format:
GET$

call

specified

the

fdb,urba,urbs,err

f db

A symbolic value Ul.
-

.LL -

l..Ut:::

- &:
UL

-----.:-~-A
Cl;;);;)U\....LCll..CU

'C'T'\D
.L:uue

urba
The symbolic address of your record buffer to be used for record
I/O operations in move or locate mode. When specified, this
parameter initializes FOB offset location F.URB0+2.
urbs
A numeric value defining the

size
(in bytes)
of your record
buffer. This parameter determines the largest record that can be
placed in your record buffer in move or locate mode.
When
specified, this parameter initializes offset location F.URBD in
the associated FOB.

err
The symbolic address of an
routine.

optional

user-coded,

error-handling

If neither the urba nor the urbs parameter is specified in the GET$
macro call, FCS assumes that these requisite values have been supplied
previously through the FORC$A, the FORC$R, or the generalized OPEN$x
macro call. Any resulting nonzero values in offset locations F.URB0+2
and F.URBO are used as the address and the length,
respectively, of
your record buffer.
If either of the following conditions occurs during record I/O
operations, FCS returns an error indication
(IE.RBG)
to offset
location F.ERR of the FOB, indicating an illegal record size:
1.

In move mode, the record size exceeds the limit specified
offset location F.URBO.

3-20

FILE-PROCESSING MACRO CALLS
2.

In locate mode, the record size exceeds the limit specified
in offset location F.URBD, and the record must be moved
because it crosses block boundaries.

In both move and locate mode, only data up to the amount specified in
F.URBD is placed in your buffer. The next GET$ begins reading at the
beginning of the next record.
The following statements represent the use of the GET$ macro call:
GET$

RO,,,ERROR

GET$

,#RECBUF,#25.,ERROR

GET$

#INFDB

In the first example, the address of the desired FDB is assumed to be
present in RO.
Note that the next two parameters, that is, your
record buffer address (urba) and your record buffer size (urbs), are
null.
In this case, FCS assumes that the appropriate values for FDB
offset locations F.URBD+2 and F.URBD, respectively,
have
been
specified previously in the FDRC$A, the FDRC$R, or the generalized
OPEN$x macro call. The final parameter in the string is the symbolic
address of a user-coded, error-handling routine.
The second example also assumes that RO contains the address of the
desired FDB.
Explicit parameters then define the address and the
size, respectively, of your record buffer and a user-coded error
handler.
The last example shows a GET$ macro call in which only the address
the FDB is specified.

NOTE
You can use RO only to pass the FDB
address.
Any other use of RO when you
issue the GET$ macro will fail.

3.9.2

FDB Mechanics Relevant to GET$ Operations

The following sections summarize the essential aspects of GET$
operations in move and locate mode with respect to the associated FDB.
The discussions below focus mainly on whether your record buffer is
required under certain conditions. In this regard, you should recall
that your record buffer descriptors, that is, the urba and the urbs
parameters, may be specified in the FDRC$A, the FDRC$R, or the
generalized OPEN$x macro call, as well as the I/0-initiating GET$
macro call.
These parameters need be present in the GET$ macro call
(to appropriately initialize the FDB) only if not previously supplied
through some other available means.
If operating in random access mode, the number of the record to be
read is maintained by FCS in offset locations F.RCNM and F.RCNM+2 of
the associated FDB. FCS increments this value after each GET$ or
GET$R operation to point to the next record in the FSR block buffer.

3-21

F!LE-PROCESSINC MACRO CALLS
Thus, unless your program alters the values in locations F.RCNM and
F.RCNM+2 before each issuance of the GET$ or GET$R macro call, the
next record in sequence is read. Your specified record buffer size
(that is, the urbs parameter) always determines the largest record
that can be read during a GET$ operation.

3.9.2.1 GET$ Operations in Move Mode - With
respect
to
GET$
operations in move mode (refer to Section 2.2 for information on move
mode), the following generalization applies. If records are always
moved to the same user record buffer, the urba and urbs parameters
need be specified only in the initial GET$ macro call. Alternatively,
these values may be specified beforehand through any available means
identified above for initializing the user record buffer descriptor
cells in the FDB. In any case, offset locations F.URBD+2 and F.URBD
remain appropriately initialized for all subsequent GET$ operations in
move mode that involve the same user record buffer.

3.9.2.2 GET$ Operations in Locate Mode - In
performing
GET$
Operations in locate (refer to Section 2.2 for information on locate
mode) mode, you should take into account the following:
NOT~

In the following discussion, reference
is made to the FSR block buffer. By
default, the blocksize that FCS uses is
equivalent to the buffer size of the
device on which the file is opened.
If
big buffering is enabled (that is, an
ovbs parameter value is specified in the
FDBF$x
macro
call as described in
Section 2.2.1.6), the FSR block buffer
will be more than one block long. As a
result, it may not be necessary to move
a record even though it crosses block
boundaries, since
both
blocks
are
currently within the FSR block buffer
space. Thus, moves are only necessary
when
the
record
crosses a buffer
boundary, which is not necessarily the
same
as
a
block
boundary
in a
big-buffered file.
•

If fixed-length records are to be processed, and if they fit
evenly within the FSR block buffer, your record buffer
descriptors need not be present in the associated FDB.

•

If fixed-length records that do not fit evenly within the FSR
block buffer are to be processed, or if variable-length
records are to be processed, your record buffer descriptors
need not be present in the FDB, provided that the file being
processed exhibits the attribute of records not being allowed
to cross block boundaries {FD.BLK).

3-22

FILE-PROCESSING MACRO CALLS
The property of records not crossing block boundaries is
established as the file is created. Specifically, if offset
location F.RATT in the FDB is initialized with FD.BLK prior to
file-create time, then the records in the resulting file are
not allowed to cross buffer boundaries.
For an existing file, your file attribute section of the file
header block is read when the file is opened; thus, all
attributes of that file are made known to FCS, including
whether records within that file are allowed to cross block
boundaries.
The design of FCS requires you to utilize your record buffer
only in the event that records (either fixed or variable in
length) cross buffer boundaries.
•

If a GET$ operation is performed in locate mode, and the
record is contained entirely within the FSR block buffer, the
address of the record within the FSR block buffer and the size
of that record are returned to offset locations F.NRBD+2 and
F.NRBD, respectively, in the associated FDB. However, if that
record crosses buffer boundaries, it is moved to your record
buffer.
In this case, the address of your record buffer and
the size of the record are returned to offset locations
F.NRBD+2 and F.NRBD, respectively.

In summary, if the potential exists for crossing buffer boundaries
during GET$ operations in locate mode, then the your record buffer
descriptors must be supplied through any
available
means
to
appropriately initialize offset locations F.URBD+2 and F.URBD in the
associated FDB.

3.10

GET$R - READ LOGICAL RECORD IN RANDOM MODE

The GET$R macro call is used to read fixed-length records from a file
in random mode. Thus, by definition, issuing this macro call requires
that you be intimately familiar with the structure of the file to be
read and, furthermore, that you be able to specify precisely the
number of the record to be read.
The GET$ and GET$R macro calls are identical, except that the
parameter list of GET$R includes the specification of the desired
record number.
If the desired record number is already present in the
FDB {at offset locations F.RCNM and F.RCNM+2), then GET$ may be used.
If, however, the record access byte in the FDB (offset location
F.RACC)
has not been initialized for random access operations with
FD.RAN in the FDRC$A, the FDRC$R, or the generalized OPEN$x macro
call, then neither GET$ nor GET$R will read the desired record.
The GET$R macro call takes two more parameters in
specified in the GET$ macro call, as shown below:
GET$R

fdb,urba,urbs,lrcnm,hrcnm,err

3-23

addition

those

PILE
lrcnm
A numeric value specifying the low-order 16 bits of the number of
the record to be read. This value, which must be specified, is
stored in offset location F.RCNM+2 in the FDB. The GET$R macro
call seldom requires more than 16 bits to express the record
number. A logical record number up to 65,536(decimal) may be
specified through this parameter.
If this parameter is not
sufficient to completely express the magnitude of the record
number, the following parameter must also be specified.
hrcnm
A numeric value specifying the high-order 15 bits of the number
of the record to be read. This value is stored in FDB offset
location F.RCNM. If specified, the combination of this parameter
and the lrcnm parameter above determines the number of the
desired record. Thus, an unsigned value having a total of 31
bits of magnitude may be used in defining the record number.
If this parameter is not specified,
retains its initialized value of O.

offset

location

F.RCNM

If F.RCNM is used to express a desired record number for any
given GET$R operation, this cell must be cleared before issuing a
subsequent GET$R macro call that requires 16 bits or less to
express the desired record number; otherwise, any residual value
in F.RCNM yields an incorrect record number.
If the lrcnm and hrcnm parameters are not specified in a subsequent
GET$R macro call, the next sequential record is read since the record
number in offset locations F.RCNM+2 and F.RCNM is automatically
incremented with each GET$ operation. In the case of the first GET$R
after opening the file, record number 1 is read, because the record
number has been initialized to 0 by the OPEN. If a record other than
the next sequential record is to be read, you must explicitly specify
the number of the desired record.
The following statements represent the use of the GET$R macro call:
GET$R

#INFDB,#RECBUF,#160.,#1040.,,ERROR

GET$R

#FDBADR,#RECBUF,#160.,R3

•

Note in the first example that the number of the desired record to be
read, that is, 1040(decimal), is expressed through the first of two
available fields for this purpose; the second field is not required
and is therefore reflected as a null specification.
The second example reflects the use of general register 3 in
specifying the logical record number. This register, or any other
location so used, must be preset with the desired record number before
issuing the GET$R macro call.
NOTE
RO can only be used to pass the FDB
address parameter. Any other use of RO
when issuing the GET$R macro call will
fail.

3-24

FILE-PROCESSING MACRO CALLS
3.11

GET$S - READ LOGICAL RECORD IN SEQUENTIAL MODE

The GET$S macro call is used to read logical records from a file in
sequential mode. Although the routine invoked by the GET$S macro call
requires less memory than that invoked by GET$ (see Section 3.9),
GET$S has the same format and takes the same parameters. The GET$S
macro call is designed specifically for use in an overlaid environment
in which the amount of memory available to the program is limited and
files are to be read in strictly sequential mode.
If both GET$S and PUT$S are to be used by the program, note that the
savings in memory utilization over GET$ and PUT$ can be realized only
if GET$S and PUT$S are placed on different branches of the overlay
structure.

3.12

PUT$ - WRITE LOGICAL RECORD

The PUT$ macro call is used to write logical records to a file.
If
operating in random access mode, the number of the record to be
written is maintained by FCS in offset locations F.RCNM and F.RCNM+2
of ~ne associated FDB. FCS increments this value after each PUT$ or
PUT$R operation to point to the next sequential record position.
Thus, unless your program alters this value before issuing another
PUT$ or PUT$R operation, the next record in sequence is written.
For PUT$ operations, offset locations F.NRBD+2 and F.NRBD in the
associated FDB must contain the address and the size, respectively, of
the record to be written.
The distinction between move mode and
locate mode for PUT$ operations relates to the building or the
assembling of the data into a record. Specifically, in move mode the
record is built in a buffer of your choice. This buffer is not
necessarily your record buffer previously described in the context of
record I/O operations.
In other words, you ~an build records in an
aif'ea of a program apart from that normally defined by your record
buffer descriptors in the FDB (F.URBD+2 and F.URBD). In this case,
the address of the record buffer so used and the size of the record
are specified in the PUT$ macro call, and the record thus built is
then moved into the FSR block buffer.
In locate mode, however, the record is built at the address specified
by the contents of offset location F.NRBD+2, and only the record size
need be specified in the PUT$ macro call.
Then, if the record so
built is not already in the FSR block buffer, it is moved there as the
PUT$ operation is performed.
If the records in the file are sequenced records, the field F.SEQN
the FDB contains the sequence value, which you can modify.

PUT$ operations are fully synchronous; that is, record I/O operations
are completed before control is returned to the user program.
A random PUT$ operation in locate mode requires the use of the .POSRC
routine.
This operation is described in detail in Section 4.9.2.
Specific FDB requirements for PUT$ operations are presented in Section
3.12.2 below.

3-25

FttE-PROCESS!NG MACRO CALLS
3.12.1

Format of PUT$ Macro Call

The PUT$ macro call takes the following format:
PUT$

fdb,nrba,nrbs,err

f db

A symbolic value of the address of the associated FDB.
nrba
The symbolic address of the next record buffer, that is, the
address of the record to be PUT$. This parameter initializes FDB
offset location F.NRBD+2.
nrbs
A numeric value specifying the size of the next record buffer,
that is, the length of the record to be PUT$. This parameter
initializes FDB offset location F.NRBD.
err
The symbolic address of an
routine.

optional

user-coded,

error-handling

The following examples represent the uses of the PUT$ macro call:
PUT$

#FDBADR,,,ERRRT

PUT$

,,#160.,ERRRT

PUT$

In the first example, note that the next record buffer address (nrba
parameter) and the next record buffer size (nrbs parameter) are null.
These null specifications imply that the current values in offset
locations F.NRBD+2 and F.NRBD of the associated FDB are suitable to
the current operation. Note also that fixed-length records could also
be written in locate mode by issuing this macro call.
The second example contains null specifications in the first two
fields, assuming that RO currently contains the address of
the assoc~ated FDB and that variable-length records are to be written
to the file.

paramet~~

The last example specifies only the address of
parameter fields are null.

the

FDB;

NOTE
RO can only be used to pass the FDB
address parameter as shown in the above
example; it cannot be used to pass any
other parameter in the PUT$ macro call.

3-26

all

other

FILE-PROCESSING MACRO CALLS
3.12Q2

FDB Mechanics Relevant to PUT$ Operations

The discussions below highlight aspects of PUT$ operations in move and
locate mode that have a bearing on the associated FDB.
The conditions under which your record buffer is or is not used are
summarized. As is the case for GET$ operations, if your record buffer
is required for PUT$ operations, the buffer descriptors (that is, the
urba and urbs parameters) may be supplied to the associated FDB
through the FDRC$A, the FDRC$R, or the generalized OPEN$x macro call.
In
any
case,
offset
locations F.URBD+2 and F.URBD must be
appropriately initialized if PUT$ operations require the utilization
of your record buffer. Note, however, that PUT$ operations in move
mode never require a record buffer.
If your record buffer is required, the specified size of that buffer
(that is, the urbs parameter) always determines the size of the
largest record that can be written to the specified file.
Whether in move or locate mode, a PUT$ operation uses the information
in offset locations F.NRBD+2 and F.NRBD, that is, the next record
buffer descriptors, to determine whether the record must be moved into
the FSR block buffer. In the event that the record does have to be
moved, and the size of that record is such that it cannot fit in the
space rema1n1ng in the FSR block buffer, one of two possible
operations is performed:
1.

If records are allowed to cross block boundaries, then the
first part of the record is moved into the FSR block buffer,
thereby completing a virtual block.
That block buffer is
then written out to the volume, and the remaining portion of
the record is moved into the beginning of the next FSR block
buffer.

If records are not allowed to cross block boundaries (because
of the file attribute FD.BLK specified in the associated
FDB), then the FSR block buffer is written out to the volume
as is, and the entire record is moved into the beginning of
the next FSR block buffer.

3.12.2.1 PUT$ Operations in Move Mode - A PUT$ operation in move mode
(see Section 2.2) is basically driven by specifying in each PUT$ macro
call the address and the size of the record to be written.
Then, as
the PUT$ operation is performed, FCS moves the record into the
appropriate area of the FSR block buffer.
In summary, the following generalizations apply for PUT$ operations in
move mode:
l.

Your record buffer descriptors need not be present in the FDB
because the programmer is dynamically specifying the address
and the length of the record to be written at each issuance
of a PUT$ macro call. The values so specified dynamically
update offset locations F.NRBD+2 and F.NRBD in the associated
FDB.

If the file consists of fixed-length records, then the
generalized OPEN$x macro call (see Section 3.1) initializes
offset location F.NRBD with the appropriate record size, as
defined by the contents of offset location F.RSIZ. Thus, the
size of the record need not be specified as the nrbs
parameter in any PUT$ macro call involving this file.
3-27

FILE-PROCESSING MACRO CALLS
3.

If variable-length records are being PUT$, the size of each
record must be specified as the nrbs parameter in each PUT$
macro call involving this file, thus setting offset location
F.NRBD to the appropriate record size.

3.12.2.2 PUT$ Operations in Locate Mode - Basically,
your
record
buffer is required for PUT$ operations in locate mode (see Section
2.2) only when the potential exists for records to cross buffer
boundaries. In other words, ~f there is insufficient space in the FSR
block buffer to accommodate the building of the next record, you must
provide a buffer in your memory space in order to build that record.
When a file is initially opened for PUT$ operations in locate mode,
FCS sets up offset location F.NRBD+2 to point to the area in the FSR
block buffer where the next record is to be built.
Then, each PUT$
operation thereafter in locate mode updates the address value in this
cell to point to the area in the FSR block buffer where the next
record is to be built.
Thus, after each PUT$ operation in locate
mode, F.NRBD+2 points to the area where the next record is to be
built.
This logic dictates whether your record buffer is required in
locate mode.
In this regard, the following generalizations apply:
NOTE
In the following discussion, reference
is made to the FSR block buffer. By
default, the block size that FCS uses is
equivalent to the buffer size of the
device on which the file is opened.
If
big buffering is enabled (that is, an
ovbs parameter value is specified in the
FDBF$x
macro call, as described in
Section 2.2.1.6) the FSR block buffer
will be more than one block long. As a
result, it may not be necessary to move
a record even though it crosses block
boundaries, since
both
blocks
are
currently within the FSR block buffer
space. Thus, moves are only necessary
when
the
record
crosses a buffer
boundary, which is not necessarily the
same
as
a
block
boundary
in a
big-buffered file.
1.

If fixed-length records are being PUT$ and they fit evenly
within the FSR block buffer, your record buffer is not
required.

If a fixed-length record crosses block boundaries, your
record buffer descriptors must be present in offset locations
F.URBD+2 and F.URBD of the associated FDB.
In this case,
after determining that the record cannot fit in the FSR block
buffer, FCS sets offset location F.NRBD+2 to point to your
record buffer.
Then, when the record is PUT$, it is moved
from your record buffer to the FSR block buffer.

If a variable-length record is being PUT$, the potential
exists for crossing block boundaries. In this case, your
3-28

FILE-PROCESSING MACRO CALLS
record buffer descriptors must be present in offset locations
F.URBD+2 and F.URBD of the associated FOB. Moreover, the
size of each variable-length record must be specified as the
nrbs parameter in each PUT$ macro call.
Determining if FCS points offset location F.NRBD+2 to the FSR
block buff er for the PUT$ operation or to your record buff er
is based on whether there is potentially enough room in the
FSR block buffer to accommodate the record.
Because the records are variable in length,
it must be
assumed that the largest possible record is PUT$, as defined
by the size of your record buffer
(F.URBD).
Thus,
if a
record of this defined size cannot fit in the space remaining
in the FSR block buffer, FCS sets offset location F.NRBD+2 to
point to your record buffer.
Each PUT$ operation in locate mode sets up the FOB for the next PUT$.
In other words,
the specified record size is used by FCS as the
worst-case condition in determining whether sufficient space exists in
the FSR to build the next record.
If variable-length records are being processed that are shorter than
the largest defined record size, FCS may move records unnecessarily
from your record buffer to the FSR block buffer. For example, assume
that you have allocated a 132-byte record buffer. Assume further that
the available remaining space in the FSR block buffer is less than 132
bytes.
In this case, FCS continues to point to your record buffer for
PUT$ operations, even if you continue to PUT$ short (10- or 20-byte}
records.
Thus, some unavoidable movement of records takes place in
locate mode.
If the largest record that you intend to PUT$ is 80 bytes, for
example, then the largest defined record size should not be specified
as 132 bytes (or any length larger than that intended to be PUT$).
Aside from having to allocate a smaller user record buffer, PUT$
operations in locate mode are more efficient if this precaution is
observed.
Exercising care in this regard reduces the tendency to move
records from your record buff er to the FSR block buff er when they
might otherwise be built directly in the FSR block buffer.

3.13

PUT$R - WRITE LOGICAL RECORD IN RANDOM MODE

The PUT$R macro call is used to write fixed-length records to a file
in random mode. As noted in Section 3.10 in connection with the GET$R
macro call, operations in random access mode require you to be
intimately familiar with the contents of such files.
The PUT$R macro
call also relies entirely on you to specify the number of the record
before a specified PUT$ operation can be performed. Since the usual
purpose of a PUT$R operation is to update known records in a file,
it
is assumed that you also know the number of such records within the
file.
The PUT$ and PUT$R macro calls are identical, except that PUT$R allows
the specification of the desired record number.
If the desired record
number is already present in the FOB (at offset locations F.RCNM and
F.RCNM+2), then PUT$ and PUT$R may be used interchangeably. However,
if the record access byte in the FOB (offset location F.RACC) has not
been initialized for random access operations with FD.RAN in the
FDRC$A, the FDRC$R, or the generalized OPEN$x macro call, then neither
PUT$ nor PUT$R will write the desired record.

3-29

FILE-PROCESSING MACRO CALLS
The PUT$R macro call takes two more parameters in
specified in the PUT$ macro call, as shown below:
PUT$R

addition

those

fdb,nrba,nrbs,lrcnm,hrcnm,err

lrcnm
A numeric value specifying the low-order 16 bits of the number of
the record to be processed.
This parameter serves the same
purpose as the corresponding parameter in the GET$R macro call
(see Section 3.10), except that it identifies the record to be
written.
hrcnm
A numeric value specifying the high-order 15 bits of the number
of the record to be processed. This parameter serves the same
purpose as the corresponding parameter in the GET$R macro call,
except that it identifies the record to be written.
If this parameter is not specified,
retains its initialized value of O.

offset

location

F.RCNM

If F.RCNM is used in expressing a desired record number for any
given PUT$R operation, you must clear this cell before issuing a
suhseq~ent PUTSR macro call that requires
16 bits or .L t:::::>::i J. !l
expressing the desired record number; otherwise, any residual
value in F.RCNM results in an incorrect record number.
,

.! --

The lrcnm and hrcnm parameters initialize offset locations F.RCNM+2
and F.RCNM, respectively, in the associated FDB. If these values are
not specified in a subsequent PUT$R macro call, the next sequential
record lS written, s1nce FCS automatically increments the record
number in these cells after each PUT$ operation. In the case of the
first PUT$R after opening the file, record number 1 is written. Note
that this is true even if the file has been opened for an append
(OPEN$A).
If a record other than the next sequential record is to be
written, you must explicitly specify the number of the desired record.
NOTE
A random mode PUT$ operation executed in
locate mode must be preceded by a call
to .POSRC, Since locate mode allows you
to store data directly into the block
buffer, the file must be positioned so
that the desired record position is in
fact in the block buffer.
See Section
4.10.2 for further details.
Examples of the use of the PUT$R macro call follow:
PUT$R

#OUTFDB,#RECBUF,,#12040.,,ERRLOC

PUT$R

#FDBADR,iRECBUF,,R4

PUT$R

iFDBADR,iRECBUF,,LRN

In the first example, the presence of RECBUF as the next record buffer
address (nrba) parameter merely indicates that you are specifying the
address of the record. Although specifying this address repeatedly is
unnecessary, it is not invalid.
Normally, a buffer address is
3-30

FILE-PROCESSING MACRO CALLS
specified dynamically, since other PUT$ macro calls may be referencing
different areas in memory; thus, the address of the record must be
explicitly specified in each PUT$ macro call. Note also that the next
record buffer size (nrbs) parameter is null, since this parameter is
required only in the case of writing variable-length records.
Also,
the second of the two available parameters for defining the record
number is null.
Note in the second and third examples that R4 and a memory location
Such a
(LRN)
are used to specify the logical record number.
specification assumes that you have preset the desired record number
in the referenced location.
NOTE
You can use RO only to pass the FOB
address.
Any other use of RO when you
issue the PUT$R macro call will fail.

3.14

PUT$S - WRITE LOGICAL RECORD IN SEQUENTIAL MODE

The PUT$S macro call is used to write logical records to a file in
sequential mode. Although the routine invoked by the PUT$S macro call
requires less memory than that invoked by PUT$
(see Section 3.12),
PUT$S has the same format and takes the same parameters. The PUT$S
macro call is designed specifically for use in an overlaid environment
in which the amount of memory available to the program is limited and
files are to be written in strictly sequential mode.
If both GET$S and PUT$S are to be used by the program, the savings in
memory utilization over GET$ and PUT$ are realized only if GET$S and
PUT$S are placed on different branches of the overlay structure.

3.15

READ$ - READ VIRTUAL BLOCK

The READ$ macro call is issued to read a virtual block of data from a
block-oriented device
(for example, a magtape, a disk, or DECtape).
In addition, if certain optional parameters are specified in the READ$
macro call, status information is returned to the I/O status block
(see Section 2.8.2), and/or the program traps to a user-coded AST
service routine at the completion of block I/O operations (see Section
2.8.3).
In issuing the READ$ (or WRITE$) macro call, you are responsible for
synchronizing all block I/O operations. For this reason, the WAIT$
macro call is provided (see Section 3.17), allowing you to suspend
program execution nnt.il
a specified READ$/WRITE$ operation has been
completed.
It is important, however, that you test the contents of
F.ERR in the FOB for error codes immediately after issuing the
READ$/WRITE$ call as well as on return from the WAIT$ call.
When
errors occur during multiple-block transfers, the second word of the
I/O status block will contain the number of bytes transferred before
the error occurred. The READ$/WRITE operations can return error codes
distinct from those that can be present on completing a WAIT$
operation.
For example, IE.EOF will be returned upon completing the
READ$ operation, but not upon completing WAIT$.

3-31

FILE-PROCESSING MACRO CALLS
When the WAIT$ macro call is issued in conjunction with a READ$
(or
WRITE$) macro call, you must ensure that the event flag number and the
I/O status block address specified in both macro calls are the same.
When the WTSE$ macro call is issued to wait for
I/O completion, the
issuing task must check I/O errors by examining the I/O status block
(defined by the task).
(The I/O status block is described in Section
2.8.2.)
When WTSE$ is used, FCS will not return a completion code to
offset F.ERR in the FDB.

3.15.1

Format of READ$ Macro Call

From the format below, note that the parameters of the READ$ macro
call are identical to those of the FDBK$A or the FDBK$R macro call,
with the exception of the fdb and err parameters.
Certain FDB
parameters may be set at assembly time (FDBK$A), initialized at run
time (FDBK$R), or set dynamically by the READ$ macro call.
In any
case, certain information must be present in the FDB before the
specified READ$
(or WRITE$)
operation can be performed.
These
requirements are noted in Section 3.15.2 below.
The READ$ macro call takes the following format:
READ$

fdb,bkda,bkds,bkvb,bkef ,bkst,bkdn,err

fdb
A symbolic value of the address of the associated FDB.
bkda
The symbolic address of the block IiO burrer in your program.
This parameter need not be specified if offset location F.BKDS+2
has been previously initialized through either the FDBK$A or the
FDBK$R macro call.
bkds
A numeric value specifying the size (in bytes)
of the virtual
block to be read. This parameter need not be specified if offset
location F.BKDS has been previously initialized through either
the FDBK$A or the FDBK$R macro call.
In any case, the maximum
block size that may be specified for file-structured devices is
32256 bytes.
bk vb
The symbolic address of a 2-word block in your program containing
the number of the virtual block to be read. This parameter
causes offset locations F.BKVB and F.BKVB+2 to be initialized
with the virtual block number; F.BKVB+2 contains the low-order
16 bits of the virtual block number, and F.BKVB contains the
high-order 15 bits.
As noted in connection with the FDBK$A macro call described in
Section 2.2.1.4, assembly-time initialization of the virtual
block number in the FDB is ineffective, since the generalized
OPEN$x macro call sets the virtual block number in the FDB to 1.

3-32

FILE-PROCESSING MACRO CALLS

The virtual block number can be made available to FCS only
through the FDBK$R macro call or the I/0-initiating READ$ (or
WRITE$) macro call after the file has been opened.
The virtual
block number is created as described
in item 4 of Section
2.2.2.1.
The READ$ function checks the specified virtual block number to
ensure that it does not reference a nonexistent block, that is, a
block beyond the end of the file.
If the virtual block number
references
nonexistent data, an end-of-file
(IE.EOF)
error
indication is returned to offset location F.ERR of the associated
FDB;
otherwise, the READ$ operation proceeds normally.
If the
total number of bytes goes beyond the end of the file,
then as
many blocks as exist are read and the byte count of the shortened
transfer is returned in I/O STATUS+2.
No error condition occurs,
so you must check the count on each READ.
An end-of-file
indication is returned only if no blocks can be read.
If the virtual block number is not specified through any of the
available means identified above, automatic sequential operation
results by default, beginning with virtual block number 1.
The
virtual block number is automatically incremented by the number
of blocks read after each READ$ operation is performed.

bkef
A numeri~ value specifying the event flag number to be used for
synchronizing block I/O operations. This event flag number is
used by FCS to signal the completion of the specified block I/O
operation.
The event flag number, which may also be specified
in either the FDBK$A or the FDBK$R macro call,
initializes FDB
offset location F.BKEF;
if so specified, this parameter need not
be included in the READ$ (or WRITE$) macro call.
If this optional parameter is not specified through any available
means, event flag 32(decimal) is used by default. The function
of an event flag is discussed in further detail in Section 2.8.1.

bk st
The symbolic address of the I/O status block in the user program
(see Section 2.8.2).
This parameter, which initializes offset
location F.BKST, is optional. The I/O status block is filled
in
by the system when the requested block I/O transfer is completed,
indicating the success/failure of the requested operation.
The address of the I/O status block may also be specified
in
either the FDBK$A or the FDBK$R macro call.
If the address of
this 2-word structure is not supplied to FCS through any of the
available means, status information cannot be returned to your
program. Regardless, the event flag specified through the bkef
parameter above is set to indicate block I/O completion 1 but;
without an I/O status block, your program must assume that the
operation (for example, READ$ or WRITE$) was successful.

bkdn
The symbolic entry point address of an AST service routine
(see
Section 2.8.3).
If this parameter is specified, a trap occurs
upon completion of the specified READ$
(or WRITE$)
operation.

3-33

FILE-PROCESSING MACRO CALLS
This parameter, which is optional,
initializes offset location
F.BKDN.
This address value may also be made available to FCS
through either the FDBK$A or the FDBK$R macro call, and,
if so
specified, need not be present in the READ$ (or WRITE$) macro
call.
If the address of an AST service routine is not specified through
any available means, no AST trap occurs at the completion of
block I/O operations.
err
The symbolic address of an
routine.

optional

user-coded,

error-handling

The following examples represent READ$ macro calls that may be
to accomplish a variety of operations:
READ$

READ$

#INFDB,,,,,,,ERRLOC

READ$

RO,#INBUF,#BUFSIZ,,#22.,#IOSADR,#ASTADR,ERRLOC

READ$

#INFDB,JINBUF,#BUFSIZ,#VBNADR

issued

The first example assumes that RU contains the address of the
associated FDB. Also, all other required FDB initialization has been
accomplished through either the FDBK$A or the FDBK$R macro call.
The second example shows an explicit declaration of the associate FDB
and includes the symbolic address of a user-coded, error-handling
routine.
In the third example, RO again contains the address of the associated
FDB. The block buffer address and the size of the block are specified
next in symbolic form.
The address of the 2-word block in your

program

containing

~ne

virtual

block

number

is not specified, as

indicated by the additional comma in the parameter string. The event
flag number, the address of the I/O status block, and the address of
the AST service routine then follow in order.
Finally, the symbolic
address of an optional error routine is specified.
The fourth example reflects, as the last parameter in the string, the
symbolic address of the 2-word block in your program containing the
virtual block number.
NOTE
You can use RO only to pass the FDB
address.
Any other use of RO when you
issue the READ$ macro call will fail.

3-34

FILE-PROCESSING MACRO CALLS
3.15.2

FDB Requirements for READ$ Macro Call

The READ$ macro call requires that the associated FDB be initialized
with certain values before it can be issued. You can specify these
values through either the FDBK$A or the FDBK$R macro call, or they may
be made available to the FDB through the various parameters of the
READ$ macro call. In any case, the following values must be present
in the FDB to enable READ$ operations to be performed:
1.

The block buffer address (in offset location F.BKDS+2)

The block byte count (in offset location F.BKDS)

The virtual block number (in offset
F.BKVB)

locations

F.BKVB+2

and

NOTE
When either READ$ or WRITE$ operations
are
performed,
FCS
maintains
the
end-of-file block number field
(F.EFBK}
and clears the first free byte in the
last block field F.FFBY in the FDB.
During a READ$ operation, end-of-file is
determined by the end-of-file
block
number field in F.EFBK.
If desired, you
can modify F.FFBY before closing the
file by using the CLOSE$ macro call.

3.16

WRITE$ - WRITE VIRTUAL BLOCK

The WRITE$ macro call is issued to write a virtual block of data to a
block-oriented device (for example, magtape, disk, DECtape, or DECtape
II). Like the READ$ macro call, if certain optional parameters are
specified in the WRITE$ macro call, status information is returned to
the I/O status block (see Section 2.8.2), and, at the completion of
the I/O transfer, the program traps to an AST service routine that is
supplied to coordinate asynchronous block I/O operations (see Section
2.8.3).
Whether or not the address of an AST service routine and/or an event
flag number is supplied, you are responsible for synchronizing all
block I/O processing.
The WAIT$ macro call can be issued in
conjunction with the WRITE$ macro call to suspend program execution
until a program-dependent I/O transfer has been completed.
When the
WAIT$ macro call is used for this purpose, the event flag number and
the I/O status block address in both macro calls must be the same.
Again, as with READ$ operations, you should check for an error code
immediately following the WRITE$ macro call as well as on return from
the WAIT$ macro call.

3.16.1

Format of WRITE$ Macro Call

The WRITE$ macro call takes the same parameters as the READ$ macro
call, as shown below.
The bkvb parameter represents the symbolic
address of a 2-word block containing the number of the virtual block
to be written. The virtual block number is incremented automatically
after each WRITE$ operation is performed.

3-35

FILE-PROCESSING MACRO CALLS
The WRITE$ macro call has the following format:
WRITE$

fdb,bkda,bkds,bkvb,bkef ,bkst,bkdn,err

When this macro call is issued, the virtual block number (that is, the
bkvb parameter) is checked to ensure that it references a block within
the file's allocated space;
if it does, the block is written.
If the
specified block is not within the file's allocated space, FCS attempts
to extend the file.
If this attempt is successful, the block is
written;
if not, an error code indicating the reason for the failure
of the extend operation is returned to the I/O status block and to
offset location F.ERR of the associated FDB.
If FCS determines that the file must be extended, the actual extend
operation is performed synchronously. After the extend operation has
been successfully completed, the WRITE$ operation is queued, and only
then is control returned to the instruction immediately following the
WRITE$ macro call.
The following examples illustrate WRITE$ macro calls:
WRITE$

WRITE$

#OUTFDB,#OUTBUF,#BUFSIZ,#VBNADR,#22.

1.rnTm'C'C:-

nn
.II.")")
nv r r r r 1t.£..£. •

... ~ ... .1. ... .,,

.11.'llC"m'llnn
1:1nnTn,..
r .11.Tf"\C"'llT'\n
1t.LVun.un. 1 ttnu .1.n.un. 1 un.n..1...1v""

The first example specifies only the FDB address and assumes that all
other required values are present in the FDB. The second example
reflects explicit declarations for the FDB, the block buffer address,
the block buffer size, the virtual block number address, and the event
flag number for signalling block I/O completion.
The third example
shows null specifications for three parameter fields, then continues
with the event flag number, the address of the I/O status block, and
the address of the AST service routine. Finally, the address of a
user-coded, error-handling routine is specified.
NOTE
You can use RO only to pass the FDB
address.
Any other use of RO when you
issue the WRITE$ macro call will fail.

3.16.2

FDB Requirements for WRITE$ Macro Call

WRITE$ operations require the presence of the same information in
FDB as READ$ operations (see Section 3.15.2).

3.17

the

WAIT$ - WAIT FOR BLOCK I/O COMPLETION

The WAIT$ macro call, which is issued only in connection with READ$
and WRITE$ operations, causes program execution to be suspended until
the requested block I/O transfer is completed. This macro call may be
used to synchronize a block I/O operation that depends on the
successful completion of a previous block I/O transfer.

3-36

FILE-PROCESSING MACRO CALLS
As noted in Section 3.15 in connection with the READ$ macro call, you
can specify an event flag number through the bkef parameter. This
event flag number is used during READ$ (or WRITE$) operations to
indicate the completion of the requested transfer. If desired, you
can issue a WAIT$ macro call (specifying the same event flag number
and I/O status block address) following the READ$ (or WRITE$) macro
call.
In this case, the READ$ (or WRITE$) operation is initiated in the
usual manner, but the Executive of the host operating system suspends
program execution until the specified event flag is set, indicating
that the I/O transfer has been completed. The system then returns
information to the I/O status block, indicating the success/failure of
the operation.
FCS then moves the I/O status block success/failure
indicator into offset location F.ERR of the associated FDB, and
returns with the C-bit in the Processor Status Word cleared if the
operation is successful, or set if the operation is not successful.
Task
execution then continues with the instruction immediately
following the WAIT$ macro call.
The system returns the final status of the I/O operation to the I/O
block (see Section 2.8.2)
upon completion of the requested
operation. A positive value (+) indicates successful completion, and
a negative value (-) indicates unsuccessful completion.
status

Event flags are discussed in further detail in Section 2.8.1.

3.17.1

Format of WAIT$ Macro Call

The WAIT$ macro call is specified in the following format:
WAIT$

fdb,bkef ,bkst,err

f db

A symbolic value of the address of the associated FDB.
bkef
A numeric value specifying the event flag number to be used for
synchronizing block I/O operations. The WAIT$ macro causes task
execution to be suspended by invoking the WAITFOR
system
directive.
This parameter must agree with the corresponding
(bkef) parameter in the associated READ$/WRITE$ macro call.
If this parameter is not specified, either in the WAIT$ macro
call or the associated READ$/WRITE macro call, FDB offset
location F.BKEF is assumed to contain the desired event flag
number, as previously initialized through the bkef parameter of
the FDBK$A or the FDBK$R macro call.
bkst
The symbolic address of the I/O status block in your program (see
Section 2.8.2).
Although this parameter is optional, if it is
specified, it must agree with the corresponding (bkst) parameter
in the associated READ$/WRITE$ macro call.

3-37

FILE-PROCESSING MACRO CALLS
If this parameter is not specified, either in the WAIT$ macro
call or the associated READ$/WRITE$ macro call, FOB offset
location F.BKST is assumed to contain the address of the I/O
status
block,
as previously initialized through the bkst
parameter of the FDBK$A or the FDBK$R macro call. If F.BKST has
not been initialized, no return of information to the I/O status
block occurs.
err
The symbolic address of an
routine.

optional

user-coded,

error-handling

The following statements represent WAIT$ macro calls:
WAIT$

WAIT$

#INFDB,#25.

WAIT$

R0,#25.,#IOSTAT

WAIT$

RO,,#IOSTAT,ERRLOC

The first example assumes that RO contains the address of the
associated FDB;
furthermore, since the event flag number (bkef
parameter) is not specified~ offset location F.BKEF is assumed to
contain the desired event flag number.
If this cell in the FOB
contains O, event flag number 32(decimal) is used by default.
The second example shows an explicit specification of the FOB address
and also specifies 25(decimal) as the event flag number. Again, in
this example, the FOB is assumed to contain the address of the I/O
status block.
In contrast; the third example shows an explicit
specification for the address of the I/O status block.
The fourth example contains a null specification for the event flag
number, and, in addition, specifies the address of a user-coded,
error-handling routine.
It should be noted that the WAIT$ macro call associated with a given
READ$ or WRITE$ operation need not be issued immediately following the
macro call to which it applies. For example, the following sequence
is typical:
1.

Issue the desired READ$ or WRITE$ macro call.

Perform other processing that is not dependent
completion of the requested block I/O transfer.

Issue the WAIT$ macro call9

Perform the processing that is dependent on the completion of
the requested block I/O transfer.

the

When performing several asynchronous transfers in the same general
sequence as above, a separate buffer, I/O status block, and event flag
must be maintained for each operation. If you intend to wait for the
completion of a given transfer, the appropriate event flag number and
I/O status block address must be specified in the associated WAIT$
macro call.

3-38

FILE-PROCESSING MACRO CALLS
NOTE
You can use RO only to pass the FDB
address.
Any other use of RO when you
issue the WAIT$ macro call will fail.

3.18

DELET$ - DELETE SPECIFIED FILE

The DELET$ macro call causes the directo~y information for the file
associated with the specified FDB to be deleted from the appropriate
UFD. The space occupied by the file is then deallocated and returned
for reallocation to the pool of available storage on the volume.
This macro call can be issued for a file that is either open or
closed.
If issued for an open file, that file is then closed and
deleted;
if issued for a closed file, that file is deleted only if
the file name string specified in the associated dataset descriptor or
default filename block contains an explicit file version number
(including 0 and -1).
NOTE
If the DELET$ macro call is issued for
use with a file containing sensitive
information, it is recommended that you
zero the file before closing it, or
reformat the disk
to
destroy
the
sensitive information.
(Although DELET$
logically
removes
a
file,
the
information physically remains on the
volume until written over with another
file,
and
could
be
analyzed
by
unauthorized users.)

3.18.1

Format of DELET$ Macro Call

The DELET$ macro call takes the following format:
DELET$

fdb,err

f db

A symbolic value of the address of the
FDB.

associated

The symbolic address of
error-handling routine.

user-coded,

err
an

optional

The following statements illustrate DELET$ macro calls:
DELET$

DELET$

iOUTFDB,ERRLOC

DELET$

RO,ERRLOC

3-39

CHAPTER 4
FILE CONTROL ROUTINES

You can invoke file control routines in MACR0-11 programs
the following functions:

4.1

perform

•

Read or write default directory string descriptors in $$FSR2.

•

Read or write the default UIC word in $$FSR2.

•

Read or write the default file protection word in $$FSR2.

•

Read or write the file owner word in $$FSR2.

•

Convert a directory string
versa.

•

Fill in all or part of a filename block
descriptor and/or default filename block.

from

ASCII

binary,
from

vice

dataset

•

Find, insert, or delete a directory entry.

•

Set a pointer to a byte within a virtual block or to a
within a file.

record

•

Mark a place in a file for a subsequent OPEN$x operation.

•

Issue an I/O command and wait for its completion.

•

Rename a file.

•

Extend a file.

•

Truncate a file.

•

Mark a temporary file for deletion.

•

Delete a file by filename block.

•

Perform device-specific control functions.

CALLING FILE CONTROL ROUTINES

The CALL opcode/macro is used to invoke file control routines (JSR PC,
dst).
These routines are included from the system object library
([l,l]SYSLIB.OLB) at task-build time and incorporated into the user
task. The file control routines are called as shown below:
CALL

.RDFD~

CALL

.EXTND

4-1

FILE CONTROL ROUTINES
Before the CALL is issued, certain file control routines require that
specific registers be preset with requisite information.
These
requirements are identified in the descriptions of the respective
routines.
Upon return, all registers are preserved, except those
explicitly specified as changed.
If an error is detected by a file control routine, the C-bit
(carry
condition code)
in the Processor Status Word is set, and an error
indication is returned to FDB offset location F.ERR. However, certain
file control routines do not return error indications. The following
file control routines are listed according to whether they return
error indications.
Normal Error Return
(C-bit and F.ERR)
.ASCPP
.PARSE
.PRSDV
.PRSDI
.PRSDV
.ASLUN
.FIND
.ENTER
.REMOV
.GTDIR
.GTDID
.POINT
.POSRC
.POSIT
.XQIO
.RENAM
.EXTND
.TRNCL
.MRKDL
.DLFNB
.CTRL

No Error Return
.RDFDR
.WDFDR
.RDFUI
.WDFUI
.RDFFP
.WDFFP
.RFOW~

.WFOWN
.PPASC
.MARK

Appendix I lists the error codes that the
return in FDB offset location F.ERR.

4.2

routines

above

DEFAULT DIRECTORY-STRING ROUTINES

The .RDFDR and .WDFDR routines are used to read
string descriptors.

4.2.1

identified

and

write

directory

.RDFDR - Read $$FSR2 Default Directory String Descriptor

You call the .RDFDR routine to read default directory
string
descriptor words previously written by the .WDFDR routine into program
section $$FSR2 of the FSR. These descriptor words define the address
and the length of an ASCII string that contains the default directory
string. This directory string constitutes the default directory that
is to be used by FCS when one is not explicitly specified in a dataset
descriptor.

4-2

FILE CONTROL ROUTINES
If you have not established default directory string descriptor words
in $$FSR2 through the .WDFDR routine described below, the descriptor
words in $$FSR2 are null and FCS uses a default directory (when one is
not specified in a dataset descriptor) corresponding to the UIC under
which the task is running.
When called, the
registers:

.RDFDR

routine

returns

values

the

following

Contains the size (in bytes) of the default directory
in $$FSR2.

Contains the address of the default directory string
in
$$FSR2.
If no default directory string descriptor words have
been written by .WDFDR, R2 equals O.

4.2.2

string

.WDFDR - Write New $$FSR2 Default Directory-String Descriptor

The ~WDFDR routine is called to create default directory string
descriptor words in $$FSR2.
For example,
if your program is to
ooerate on files in the directorv r220.2201.
reaardless of the UIC
under which the program runs, then-you.can-establish default directory
string descriptor cells in $$FSR2 to point to the alternate directory
string
(220,220]
created elsewhere in the program. To do this, the
desired directory string is first created through an .ASCII directive.
Then, by calling the .WDFDR routine, you can initialize the default
directory string descriptor cells in $$FSR2 to point to the new

directory string.
Assume that the task is currently running under default UIC (200,200].
By issuing a MACR0-11 directive similar to the following:
NEWDDS:

.ASCII /[220,220]/

you define a new directory string.
Then, by calling the
.WDFDR
routine, you can initialize string descriptor cells in $$FSR2 to point
to the new directory string.
The following registers must
routine:

preset

before

calling

the

.WDFDR

Must contain the size (in bytes) of the new directory string.

Must contain the address of the new directory string.
NOTE
Establishing default directory string
descriptor words in $$FSR2 does not
change the default UIC in $$FSR2 or the
task's privileges.

4-3

FILE CONTROL ROUTINES
4.3

DEFAULT UIC ROUTINES

The .RDFUI and .WDFUI routines are used to read and write the default
UIC maintained in program section $$FSR2 of the file storage region
(FSR). Unlike the default directory string descriptor that describes
an ASCII string, the default UIC is maintained as a binary value with
the following format:
Bit

8 7

MEMBER

GROUP

The default UIC in
$$FSR2
provides
directory
identification
information for a file being accessed. FCS uses it only when all
other sources of such information have failed to specify a directory
(refer to Section 4.7.1.2).
It is never used to establish file
ownership or file access privileges.
Unless you explicitly change the default UIC through the .WDFUI
routine described below, the default UIC in $$FSR2 always corresponds
to the UIC under which the task is running.

4.3.1

.RDFUI - Read Default UIC

When called, the .RDFUI routine returns the default UIC as follows:
Rl

4.3.2

Contains the binary encoded defauit
program section $$FSR2.

UIC

maintained

.WDFUI - Write Default UIC

The .WDFUI routine is called to create a new default UIC in $$FSR2.
The following register
routine:
Rl

must

preset

before

calling

the

.WDFUI

Must contain the binary representation (as shown above) of a
UIC.
NOTE
The .WDFUI routine overrides any default
UIC descriptor previously created by
.WDFDR in $$FSR2.

4.4

DEFAULT FILE-PROTECTION WORD ROUTINES

The .RDFFP and .WDFFP routines described below are used to read and
write the default file protection word in a location in program
section $$FSR2 of the file storage region (FSR). This word is used
only at file creation time (for example, by the OPEN$W macro call) to
establish the default file protection values for the new file. Unless
altered, this value constitutes the default file protection word for
that file. If the value is -1, it indicates that the volume default
file protection value is to be used for the new file.

4-4

FILE CONTROL ROUTINES
The default file protection word has the following format:
Bit 15

12 11
WORLD

8 7

GROUP

4 3

OWNER

SYSTEM

Each of the four categories above has four bits;
following meaning with respect to file access:
Bit

DELETE,EXTEND

WRITE

READ

each

bit

has

the

bit value of 0 indicates that the respective type of access to the
file is to be allowed; a bit value of 1 indicates that the respective
type of access to the file is to be denied.

4.4.l

.RDFFP - Read $$FSR2 Default File Protection Word

You call the .RDFFP routine to read the default file protection word
in program section $$FSR2 of the FSR. No registers need be set before
calling this routine.
When called, the .RDFFP routine returns the following information:
Rl

4.4.2

Contains the default file protection word from $$FSR2.

.WDFFP - Write New $$FSR2 Default File-Protection Word

The .WDFFP routine is used to write a new default file protection word
into $$FSR2.
The following register must be preset before calling this routine:
Rl

4.5

Must contain the new default file protection word to be
written into $$FSR2.
If this register is set to -1, the
default file protection values established through
the
appropriate operating system command will be used in creating
all subsequent new files.

FILE OWNER WORD ROUTINES

The file owner word, like the default file protection word above, is.a
location in program section $$FSR2 of the FSR. Its contents are
specified by the current program through the .WFOWN routine.
If not
so specified, the file owner word contains O.
For nonprivileged users, the owner of a new file
default UIC specification, as follows:

corresponds

the

•

If the volume on which the new file is created is private
(allocated) , the owning UIC is the same as the UIC of the task
creating the file.

•

If the volume on which the new file is created is a system
volume, the owning UIC is the same as the task's login UIC.

4-5

FILE CONTROL ROUTINES
For privileged users, the owning UIC is always the same as the UIC
the task creating the file.

Note that for files created by privileged or nonprivileged tasks that
are started by a time-scheduled request, the owning UIC is set to the
UIC specified at task-build time.
A specific UIC value can be stored in the file owner word by the
.WFOWN routine
(see Section 4.5.2). All new files then created and
closed by your task will contain the specified UIC value.
The format of the file owner word is shown below:
Bit 15

8 7

GROUP

MEMBER

The routines for reading and writing the file owner word are described
below.
NOTES

4.5.1

The UIC and the file protection word
for
the file (see Section 4.4) must
not be set such that the UIC under
which the task is running does not
have access to the file.
This
condition results in a
privilege
violation.

When a file is created,
its owning
UIC is always set to either the UIC
of the task creating the file or the
task's
login UIC;
as previously
described.
However, when closing
the file, you can change the owning
UIC by using the .WFOWN routine.
If
the file is not closed properly, the
owning UIC will not change.

.RFOWN - Read $$FSR2 File Owner Word

The .RFOWN routine is used to read the contents of the file owner word
in $$~SR2.
No registers need be preset before calling this routinee
When called, the .RFOWN routine returns the following information:
Rl

4.5.2

Contains the file owner word (UIC) •
If the current program
has not previously established the contents of the file
owner word through the .WFOWN routine, Rl contains O.

.WFOWN - Write New $$FSR2 File Owner Word

The .WFOWN routine is used
$$FSR2.

initialize

the

file

owner

word

The following register must be preset before calling this routine:
Rl

Must contain a file owner word to be written into $$FSR2.

4-6

FILE CONTROL ROUTINES
4.6

ASCII/BINARY UIC CONVERSION ROUTINES

The .ASCPP and .PPASC routines are called
string from ASCII to binary, or vice versa~

4.6.l

convert

directory

.ASCPP - Convert ASCII Directory String to Equivalent Binary UIC

The .ASCPP routine is called to convert an ASCII directory
its corresponding binary UIC.

string

The following registers must be preset before calling this routine:
R2

Must contain the address of the directory string descriptor
in your program (see Section 2.4.1) for the string to be
converted.

Must contain the address of a word location in your program
to which the binary UIC is to be returned. The member
number is stored in the low-order byte of the word, and the
group number is stored in the high-order byte.

4.6.2

.PPASC - Convert UIC to ASCII Directory String

The .PPASC routine is called to convert
corresponding ASCII directory string.

binary

UIC

its

The following registers must be preset before calling this routine:
R2

Must contain the address of a storage area within your
program into which the ASCII string is to be placed. The
resultant string can be up to nine bytes in length, for
example, [200,200].

Must contain the binary UIC value to be converted.
The
low-order byte of the register contains the member number,
and the high-order byte of the register contains the group
number.

Must contain a control code.
indicate the following:

Bits 0 and 1 of

this

Bit 0 is set to 0 to suppress leading zeros (for example, 001
is returned as 1). Bit 0 is set to 1 to indicate that
leading zeros are not to be suppressed.
Bit 1 is set to 0 to place separators (square brackets and
commas) in the directory string (for example, [10,20]).
Bit 1 is set to 1 to suppress separators (for example,
1020).
The .PPA8C routine increments the conten~s of R2 to point to the byte
immediately following the last byte in the converted directory string.

4.7

FILENAME BLOCK ROUTINES

The .PARSE, .PRSDV, .PRSDI, .PRSFN, and .ASLUN routines are available
for performing functions related to a specified filename block. These
routines are described in the following sections.

4-7

FILE CONTROL ROUTINES
4.7.1

.PARSE - Fill in All Filename Information

When called, the .PARSE routine first zeros the filename block pointed
to by Rl and then stores the following information in the filename
block:
1.

The ASCII device name (N.DVNM)

The binary unit number (N.UNIT)

The directory ID (N.DID)

The Radix-50 file name (N.FNAM)

The Radix-50 file type or extension (N.FTYP)

The binary file version number (N.FVER).

For ANSI magnetic tape file names, the following information is stored
in the filename block:
1.

The ASCII device name (N.DVNM)

The binary unit number {N.UNIT)

The file name as 17 ASCII bytes (N.ANMl and N.ANM2)

The binary file version number

(N.FVER)

In addition, .PARSE calls .ASLUN to assign the LUN associated with the
FDB to the device and unit currently specified in the filename block.
Both formats for filename blocks are shown in detail in Appendix B.
Before the .PARSE routine can be called, the FINIT$ macro call
(see
Section 2.6) must be invoked explicitly in your program, or iL must be
invoked implicitly through a prior OPEN$x macro call. Note, however,
that the FINIT$ call must be issued only once in the initialization
section of the program;
that is,
the FINIT$ operation must be
performed only once per task execution.
Furthermorer FORTRAN programs
issue a FINIT$ call at the beginning of task execution;
therefore,
MACR0-11 routines used with the FORTRAN object time system must not
issue a FINIT$ macro call.
The following registers must
routine:

preset

before

calling

the

.PARSE

Must contain the address of the desired FDB.

Must contain the address of the filename block to be filled
in.
This filename block is usually, but not necessarily, the
filename block within the FDB specified in RO (that is, RO +
F.FNB).

Must contain the address of the desired dataset descriptor if
.PARSE is to access a dataset descriptor in building the
specified filename block.
This structure is usually, but not
necessarily, the same as that associated with the FDB
specified in RO (that is, the dataset descriptor pointed to
by the address value in F.DSPT).
If R2 contains O,
this value
implies that a
dataset
descriptor has not been defined;
therefore, the dataset
descriptor logic of .PARSE is bypassed.

4-8

FILE CONTROL ROUTINES
R3

Must contain the address of the desired default filename
block if .PARSE is to access a default filename block in
building the specified filename block.
This structure is
usually, but not necessarily, the same as that associated
with the FOB specified in RO (that is, the default filename
block pointed to by the address value in F.DFNB).
If R3 contains zero (0), this value implies that a default
filename block has not been defined; therefore, the default
filename block logic of .PARSE is bypassed.

Thus, RO and Rl each must contain the address of the appropriate data
structure, while either R2 or R3 must contain the address of the
desired filename information. Both R2 and R3, however, may contain
address values if the referenced structures both contain information
required in building the specified filename block.
The .PARSE routine fills in the specified filename block in the
described in the following sections.

order

4.7.1.1 Device and Unit Information - The
.PARSE
routine
first
attempts to fill in the filename block with device (N.DVNM) and unit
{N.UNIT) information.
The following operations are performed in
sequence until the required information is obtained from the specified
data structures:
1.

If the address of a dataset descriptor is specified in R2 and
this structure contains a device string, the device and unit
information therein is moved into the specified filename
block.

If step 1 fails, and if the address of a default filename
block is specified in R3, and this structure contains a
nonzero value in the device name field, the device and unit
information therein is moved into the specified filename
block.

If step 2 fails, .PARSE uses the device and unit currently
assigned to the logical unit number in offset location F.LUN
of the specified FOB in building the filename block.
This feature allows a program to use preassigned logical
units that are assigned through either the device assignment
(ASG) option of the Task Builder or one of the following
commands: ASSIGN (under !AS) or REASSIGN (under RSX-11). In
this case, you simply avoid specifying the device string in
the dataset descriptor and the device name in the default
filename block.

If the logical unit number in F.LUN is currently unassigned,
.PARSE assigns this number to the system device (SYO:).

Once the device and unit are determined and the logical unit number is
assigned, .PARSE invokes the GLUN$ directive to obtain necessary
device information.
Requisite information is returned
to
the
following offsets in the filename block pointed to by Rl:
N.DVNM

- Device Name
name.

Field.

Contains

the

redirected

device

N.UNIT

- Unit Number
number.

Field.

Contains

the

redirected

unit

4-9

FILE CONTROL ROUTINES
In addition, requisite information
offsets in the FDB pointed to by RO:

returned

the

following

F.RCTL

- Device Characteristics Byte.
This
cell
contains
device-dependent informat.ion from the first byte of the
third word returned by the GLUN$ directive.
The bit
definitions pertaining to the device characteristics
byte are described in detail in Table A-1. If desired,
you can examine this cell in the FDB to determine the
characteristics of the device associated with the
assigned LUN.

F.VBSZ

- Device Buffer Size Word. This location contains the
information from the sixth word returned by the GLUN$
directive. The value in this cell defines the device
buffer
size (in bytes) pertaining to the device
associated with the assigned LUN.

The GLUN$ directive is described in detail in the Executive
Manual of the host operating system.

Reference

4.7.1.2 Directory Identification Information - Following the operations described in the preceding section, .PARSE attempts to fill in
the filename block with directory identification information (N.DID).
The precedence rules for establishing this information are as follows:
l.

If the address of a dataset descriptor is specified in R2 and
this structure contains a directory string, that directory
string is used to find the associated UFD in the MFD.
The
resulting file ID is then moved into the directory-ID field
of the specified filename block.

If step 1 fails, and if the address of a default filename
block is specified in R3, and this structure contains a
nonzero directory ID, it is moved into the specified filename
block.
macro call
Since none
Section 2.4.2) initialize the three words starting at offset
location N.DID in the default filename block, these cells
must be initialized manually, or by issuing a call to either
the .GTDIR routine (see Section 4.9.1) or the .GTDID routine
(see Section 4.9.2).
Note that these routines can also be
used to initialize a specified filename block directly with
required directory information.

If neither step 1 nor step 2 yields the required directory
string, .PARSE examines the default directory string words in
$$FSR2. If your program has previously initialized these
words through use of the .WDFDR routine, FCS uses the string
described as the default directory.

If steps 1 through 3 fail to produce directory information,
FCS uses the binary value stored in the default UIC word in
$$FSR2 as the directory identifier. Unless changed by you
through the .WDFUI routine, this word contains the UIC under
which the task is running.

4-10

FILE CONTROL ROUTINES
NOTE
Wildcard UICs are not acceptable to
.PARSE.
In addition,
.PARSE will not
set either filename block status word
(N.STAT)
bits NB.SDI or NB.SD2 (group
and
owner
wildcard
specifications,
respectively).

4.7.1.3 File Name, File Type or Extension, and File Version Information
- Following the operations described in the preceding section, .PARSE
attempts to obtain file name information (N.FNAM, N.FTYP, and N.FVER),
as follows:
1.

If the address of a dataset descriptor is specified in R2 and
this structure contains a filename string, the file name
information therein is moved into the specified filename
block.

If the address of a default filename block is specified in
R3, and one or more of the file name, file type or extension,
and file version number fields of the dataset descriptor
specified in R2 are null, then the corresponding fields of
the default filename block are used to fill in the specified
filename block.

If neither step 1 nor step 2 yields the requisite file name
information, any specific fields not available from either
source remain null.
NOTE
If a dot (.) appears in the file name
string without an accompanying file type
designation
(for example, TEST.
or
TEST.;3), the file type is interpreted
as being explicitly null.
In this case,
the default file type is not used.
Similarly, if a semicolon (;) appears in
the
file
name
string
without an
accompanying file version number
(for
example, TEST.DAT;), the file version
number is also interpreted as being
explicitly null;
again, the default
file version number is not used in this
case. This note (except for the version
number) does not apply to the 17-byte
ASCII file name strings supported for
ANSI magnetic tape.

4.7.1.4 Other Filename Block Information - Finally, after performing
all the operations above, the .PARSE routine also fills in the
filename block status word (offset location N.STAT) of the file name
block specified in Rl.
The bit definitions for this word are presented in Table B-2. Note in
this table that an nexplicitn directory, device, file name, file type,
or file version number specification pertains to ASCII data supplied
through the dataset descriptor pointed to by R2.

4-11

FILE CONTROL ROUTINES
In addition, .PARSE explicitly zeros offset location N.NEXT in the
filename block pointed to by Rl. This action has implications for
wildcard operations, as described in Section 4.8.1 below.

4.7.2

.PRSDV - Fill in Device and Unit Information Only

The .PRSDV routine is identical to the .PARSE routine above, except
that it performs only those operations associated with requisite
device and unit information (see Section 4.7.1.1). This routine zeros
the filename block pointed to by Rl, performs a .PARSE operation on
the device and unit fields in the specified dataset descriptor and/or
default filename block, and assigns the logical unit number contained
in offset location F.LUN of the specified FDB.

4.7.3

.PRSDI - Fill in Directory Identification Information Only

The .PRSDI routine is identical to the .PARSE routine above, except
that it performs only those operations associated with requisite
directory identification information {see Section 4.7.1.2).
This
routine performs a
.PARSE operation on the directory identification
information (N.DID) field in the specified dataset descriptor and/or
default filename block.

4.7.4

.PRSFN - Fill in File name, File Type or Extension, and File Version Only

The .PRSFN routine is identical to the .PARSE routine above, except
that it performs only those operations associated with requisite file
name, file type or extension, and file version information
(see
Section 4.7.1.3).
This routine performs a .PARSE operation on the
file name, file type or extension, and file version information fields
(N.FNAM, N.FTYP, N.FVER)
in the specified dataset descriptor and/or
default filename block.

4.7.5

.ASLUN - Assign Logical Unit Number

The .ASLUN routine is called to assign a logical unit number to a
specified device and unit and to return the device information to a
specified FDB and filename block.
The following registers must be preset before calling this routine:
RO

Must contain the address of the desired FDB.

Must contain the address of the filename block containing the
desired device and unit. This filename block is usually, but
not necessarily, the filename block within the FDB specified
in RO.

If the device name field (offset location N.DVNM)
of the filename
block pointed to by Rl contains a nonzero value, the specified device
and unit are assigned to the logical unit number contained in offset
location F.LUN in the FDB pointed to by RO.
If N.DVNM in the filename block contains O, then the device and unit
currently assigned to the specified logical unit number are returned
to the appropriate fields of the filename block.

4-12

FILE CONTROL ROUTINES
Finally, if the specified logical unit number is not assigned to a
device, the .ASLUN routine assigns it to the system device (SYO:) by
defaulto
The information returned to the specified filename block and to the
specified FDB is identical to that returned by the device and unit
logic of the .PARSE routine (see Section 4.7.1.1).

4.8

DIRECTORY ENTRY ROUTINES

The .FIND, .ENTER, and .REMOV routines are used to find, insert, and
delete directory entries.
The term "directory entry" encompasses
entries in both the Master File Directory (MFD) and the User File
Directory (UFD).

4.8.1

.FIND - Locate Directory Entry

The .FIND routine is called to locate a directory entry by file name
and to fill in the file identification field (N.FID) of a specified
filename block.
The following registers must be preset before calling this routine:
RO

Must contain the address of the desired FDB.

Must contain the address of a filename block. This filename
block is usually, but not necessarily, the filename block
within the FDB specified in RO.

When invoked, the .FIND routine searches the directory file specified
by the directory-ID field of the filename block.
This file is
searched for an entry that matches the specified file name, file type,
and file version number. In this regard, two special file versions
are defined:
•

Version O is matched by the latest
encountered in the directory file.

(largest)

version

number

•

Version -1 is matched by the oldest (smallest) version
encountered in the directory file.

number

If either of these special versions is specified in the filename
block, the matching version number is returned to the filename block.
In this way, the actual version number is made available to the
program.
Certain wildcard operations require the use of the .FIND routine.
Three bits in the filename block status word (see N.STAT in Table B-2)
indicate whether a wildcard (*) was specified for a file name, a file
type, or a file version number fielda If the wildcard bit in N.STAT
is set for a given field, any directory entry matches in that
corresponding field.
Thus, if the file name and file version number
fields contain wildcard specifications (*), and the file type field is
specified as .OBJ (that is, *.OBJ;*), the first directory entry
encountered that contains .OBJ in the file type field matches,
regardless of the values present in the other two fields.

4-13

FILE CONTROL ROUTINES
When a wildcard match is found, the complete file name, file type, and
file version number fields of the matching entry are returned to the
filename block, along with the file-ID field
(N.DID).
Thus, the
program can determine the actual name of the file just found.
Offset
location N.NEXT in the filename block is also set to indicate where
that
directory
entry was found in the directory file.
This
information is used in subsequent .FIND operations to locate the next
matching entry in the directory file.
For example, the .FIND routine is often used to open a series of files
when wildcard specifications are used. The following operations are
typical:
1.

Call the .PARSE routine. This routine zeros offset location
N.NEXT in the filename block in preparation for the iterative
.FIND operations described in step 3 below.

Check for wildcard bits set by the
.PARSE routine in the
filename block status word
(see N.STAT in Table B-2). An
instruction sequence such as that shown below may be used to
test for the setting of wildcard bits in N.STAT:

BIT

#NB.SVR!NB.STP!NB.SNM,N.STAT(Rl)

BEQ

NOWILD

;BRANCH IF NOT SET.

If wildcard specifications are present in the filename block
status word, repeat the following sequence until all the
desired wildcard files have been processed:
CALL

.FIND

BCS

DONE

;ERROR CODE IE.NSF INDICATES
;NORMAL TERMINATION.

OPEN$ RO
Wildcard .FIND operations update offset location N.NEXT in
the filename block.
In essence, the contents of this cell
---··.:~1:-' 1. v v ..1. u c

"-""'1..11 c

- - - - - - - - .. ,.
\.. c ;;::i ;;::i a 1. y

11 c

.;_& ____ ,,_.; __
..1. 11..1.. v 1. iu a '- ..1. v 11

C-..1.. v 1.

~--.,_.;_, • .;__

v v 11 '- ..1. 11 u ..1. 11 ':;j

of the directory file for a matching entry.
4.

Perform the desired operations on the file.
NOTE
The above procedure applies only for the
following
types
of
wildcard
file
specifications:
TEST.DAT;*
TEST.*;*
*.DAT;*
TEST.*;5
*.DAT;3
The procedure does not work for the
following
types
of
wildcard
file
specifications:
*.DAT
TEST.*

4-14

.a-\...1..11 c

-----\...
ca 1. vu

;;::i

FILE CONTROL ROUTINES
In
summary,
if
a
wildcard
file
specification is present in either the
file name field or the file type field,
the file version number field must also
contain either an explicit
wildcard
specification
(*) or a specific file
version number (for example, 2,
3, and
so forth).
In the latter case, however,
the version number cannot be O, for the
latest version of the file, or -1, for
the oldest version of the file.
When your task sets NB.ANS, the .FIND operation compares the file name
against the full 17-character ANSI file name string that is stored in
the filename block (see Appendix B). When NB.ANS is clear, the file
name is converted to Radix-50, as described in Appendix G.
ANSI magnetic tape file
converted to Radix-50:

names

the

following

formats

can

•

Up to nine Radix-50 characters followed by spaces

•

Up to nine Radix-SO characters followed by a dot, followed
spaces or by a 3-character file type

Note that unless NB.ANS is set before the call to
.FIND, some file
names may be incorrectly matched. For example, the names "ABC" and
"ABC." are considered the same when compared with the name ABC in
Radix-SO.
When a wildcard operation is performed, the name returned in the
filename block is normally converted to Radix-50.
However, if NB.ANS
is set, the ANSI file name string is returned as up to 17 ASCiI bytes.
The first twelve bytes are returned at offset N.ANMl in the ANSI
filename block. The remainder are returned at offset NeANM2.
It is illegal to set NB.ANS before a wildcard .FIND operation unless
both file name and file type are wild, or both filename and file type
are not wild.
To delete a file whose file descriptor entry in the FDB contains
wildcards, you must save the values in the fields N.STAT and N.NEXT in
the FDB, then zero those fields in the FDB. A DELETE call then uses
the information returned from the last .FIND to delete the file.
Once
the file is deleted, the saved values of N.STAT and N.NEXT must be
restored in the FDB.

4.8.2

.ENTER - Insert Directory Entry

The .ENTER routine is used to insert an entry
directory.

file

name

into

The following registers must be preset before calling this routine:
RO

Must contain the address of the desired FDB.

Must contain the address of a filename block. This filename
block is usually, but not necessarily, the filename block
within the FDB specified in RO.

4-15

FILE CONTROL ROUTINES
If the file version number field of the filename block contains 0,
indicating a default version number, the .ENTER routine scans the
entire directory file to determine the current highest version number
for the file. If a version number for the file is found, this entry
is incremented to the next higher version number;
otherwise, it is
set to 1.
The resulting version number is returned to the filename
block, making this number known to the program.
NOTE
Wildcard specifications cannot be used
in connection with .ENTER operations.

4.8.3

.REMOV - Delete Directory Entry

The .REMOV routine is called to delete an entry from a directory
file name. This routine only deletes a specified directory entry;
does not delete the associated file.

by
it

The following registers must be preset before calling this routine:
RO

Must contain the address of the desired FDB.

Must contain the address of a filename block. This filename
block is usually, but not necessarily, the filename block
within the FDB specified in RO.

Wildcard specifications operate in the same manner as for the .FIND
routine described in Section 4.8.1 above. The file version number for
.REMOV operations must be explicit (including 0 and -1) or wildcard.
Each .REMOV operation deletes the next directory entry having the
specified file name; file type; and file version number,

4.9

FILENAME BLOCK ROUTINES

The .GTDIR and .GTDID routines are used
information in a specified filename block.

4.9.1

insert

directory

.GTDIR - Insert Directory Information in Filename Block

The .GTDIR routine is called to insert directory information taken
from a directory string descriptor into a specified filename block.
Before calling this routine, the following registers must be preset:
RO

Must contain the address of the desired FDB.

Must contain the address of a filename block in which the
directory information is to be placed. This filename block
is usually, but not necessarily, the filename block within
the FDB specified in RO.

Must contain the address of the 2-word directory string
descriptor in your program. This string descriptor defines
the size and the address of the desired directory string.

4-16

FILE CONTROL ROUTINES
This routine performs a .FIND operation for the specified UFD in the
MFD and returns the resulting directory ID to the three words of the
specified filename block, starting at offset location N.DID.
The
.GTDIR routine preserves the information in offset locations N.FNAM,
N.FYTP, N.FVER, N.DVNM, and N.UNIT of the filename block, but zeros
(clears) the rest of the filename block.
The .GTDIR routine can also be used in conjunction with the NMBLK$
macro call (see Section 2.4.2) to insert directory information into a
specified default filename block.

4.9.2

.GTDID - Insert Default Directory Information in Filename Block

The
.GTDID routine provides an alternative means for
inserting
directory information into a specified filename block.
Instead of
allowing the specification of the directory string, as does the .GTDIR
routine above, this routine uses the binary value found in the default
UIC word maintained in $$FSR2 as the desired UFD.
Before calling this routine, the following registers must be preset:
RO

Must contain the address of the desired FDB.

Must contain the address of a filename block in which the
directory information is to be placed.
This filename block
is usually, but not necessarily, the filename block within
the FDB specified in RO.

When called, the .GTDID routine takes the default UIC from its 1-word
location in $$FSR2 and performs a .FIND operation for the associated
UFD in the MFD.
The resulting directory ID is returned to the three
words of the specified filename block, starting at offset location
N.DID.
As does the .GTDIR routine, .GTDID preserves offset locations
N.FNAM, N.FTYP, N.FVER, N.DVNM, and N.UNIT in the filename block, but
zeros the rest of the filendme block.
The .GTDID routine embodies considerably less code than the
.GTDIR
routine.
Its input is the binary representation of a UIC rather than
an ASCII string descriptor. Therefore, it does not invoke the
.PARSE
logic;
furthermore,
.GTDID is intended specifically for use in
programs that open files by the OFNB$ macro call
(see Section 3.6).
Such a program does not invoke the .PARSE logic because all required
file name information is provided to the program in filename block
format.
As is true of the .GTDIR routine described
in Section 4.9.1 above,
.GTDID can be used in conjunction with the NMBLK$ macro call (see
Section 2.4.2)
to insert directory information
(N.DID)
into
a
specified default filename block.
You also have the option to
initialize offset location N.DID manually with required directory
information.

4.10

FILE POINTER ROUTINES

The .POINT, .POSRC, .MARK, and .POSIT routines are used to point to
byte or a record within a specified file.

4-17

FILE CONTROL ROUTINES
4.10.1

.POINT - Position File to Specified Byte

The .POINT routine is called to position a file to a specified byte in
a specified virtual block. If locate mode is in effect for record I/O
operations, the .POINT routine also updates the value in offset
location F.NRBD+2 in the associated FDB in preparation for a PUT$
operation in locate mode.
The following registers must be preset before calling this routine:
RO

Must contain the address of the desired FDB.

Must contain the high-order bits of the virtual block number.

Must contain the low-order bits of the virtual block number.

Must contain the desired byte
virtual block.

number

within

the

specified

For a description of virtual block numbers and how these 2-word values
are formed, refer to item 4 in Section 2.2.2.1.
NOTE
Using the .POINT routine is restricted
to files accessed with GET$ or PUT$
macros. For files accessed with READ$
or WRITE$ macros, use the FDBK$R macro
to initialize the block access section
of the FDB.
The .POINT routine is often used in coniunction with the .MARK routine
to achieve a limited degree of random access with variable-length
records. The .MARK routine saves the positional context of a file in
anticipation of temporarily closing that file and then reopening it
later at the same position.
For such purposes, the following
procedure applies:
1.

Call the .MARK routine (see Section 4.10.3 below) to save the
current positional context of the file.

Close the file.

When desired, reopen the file.

Load the information returned by the .MARK routine into Rl,
R2, and R3, as required above, before calling the .POINT
routine.

Call the .POINT routine.
The .POINT routine may be called to rewind a file on disk or
ANSI magtape to its start. For this case, Rl and R3 must be
O, and R2 must be 1.
The .POINT routine may be called to rewind a file that is
open on a terminal. Doing so clears the terminal end-of-file
condition.

Resume processing of the file.

4-18

FILE CONTROL ROUTINES
4.10.2

.POSRC - Position File to Specified Record

The .POSRC routine is called to position a file to a specified
fixed-length record within a file.
If locate mode is in effect for
record I/O operations, the .POSRC routine also updates the value in
offset location F.NRBD+2 in the associated FDB in preparation for a
PUT$ operation in locate mode.
Before calling this routine, you must set offset locations F.RCNM+2
and F.RCNM in the FDB to the desired record number and ensure that the
correct record size is reflected in offset location F.RSIZ of the FDB.
Also, the register below must be
routine:
RO

preset

before

calling

the

.POSRC

Must contain the address of the associated FDB.

The
.POSRC routine is used when performing random access PUT$
operations in locate mode. Normally, PUT$ operations in locate mode
are sequential;
however, when random access mode is used,
the
following procedure must be performed to ensure that the record is
built at the desired location:
1.

Set offset locations F.RCNM+2 and F.RCNM
FDB to the desired record number.

Call the .POSRC routine.

Build the new record at the address returned (by the
.POSRC
call) in offset location F.NRBD+2 of the associated FDB.

Perform the PUT$ operation.

4.10.3

the

associated

.MARK - Save Positional Context of File

The .MARK routine allows you to record the current positional context
of a file for later use.
For example, you can mark the current
position of the file, close that file, and later reopen the file and
return to the same position within it.
The .MARK routine is also
useful in altering records within a file.
After determining the
record to be altered, you can save your position in the file and
retrieve information elsewhere in the file for use in updating the
desired record.
Then, by returning to the saved position of the file,
you can alter the desired record.
This iterative sequence may be
repeated any number of times to update desired records in the file.
RO must contain the address of the associated FDB before calling
routine.
When called, the .MARK routine returns information
registers:

the

following

Contains the high-order bits of the virtual block number.

Contains the low-order bits of the virtual block number.

Contains the number of
block.

the

byte

within

the

this

virtual

R3 points to the next byte in the block.
For example,
if four GET$
operations are performed, followed by a call to the .MARK routine, R3
points to the first byte in the fifth record in the file.

4-19

FILE CONTROL ROUTINES
4.10.4

.POSIT - Return Positional Information for Specified Record

The .POSIT routine calculates the virtual block number and
number pertaining to the beginning of a specified record.

the

byte

The following register must be preset before calling this routine:
RO

Must contain the address of the associated FDB.

In addition, offset locations F.RCNM and F.RCNM+2
FDB must contain the desired record number.

the

associated

Unlike the .POSRC routine above, which positions the file to the
specified record, .POSIT simply calculates the positional information
for a specified record so that a .POINT operation can be later
performed to position to the desired record.
The register values returned by the .POSIT routine
those described above for the .MARK routine.

4.11

are

identical

QUEUE I/O FUNCTION ROUTINE (.XQIO)

The .XQIO routine is called to execute a specified Queue I/O
and to wait for its completion.

function

The following registers must be preset before calling this routine:

4.12

Must contain the address of the desired FDB.

Must contain the desired Queue I/O function code.
Refer to
the
!AS
Device
Handlers
Reference
Manual
or
the
RSX-llM/M-PLUS I/O Drivers Reference Manual for the desired
Queue I/O directive function codes.

Must contain the number of optional parameters, if any, to be
included in the Queue I/O directive.

Must contain the beginning address of the list of optional
Queue I/O directive parameters, if R2 contains a nonzero
value. Refer to the RSX-llM/M-PLUS I/O Drivers Reference
Manual for the parameter list.
~-

RENAME FILE ROUTINE (.RENAM)

The .RENAM routine is called to change the name of a file in its
associated directory. To rename a file, you must specify the address
of an FDB containing file name information, a LUN, and an event flag
number to be used in connection with renaming the file.
If the file to be renamed is open when the call to .RENAM is issued,
that file is closed before the renaming operation is attempted.
The following registers must be preset before calling this routine:
RO

Must contain the address
originally named file.

Must contain the address of the FDB containing the desired
file name information, LUN assignment, and event flag to be
associated with renaming the file.

4-20

the

FDB

associated

with

the

FILE CONTROL ROUTINES
If the renaming operation is successful, a new directory entry is
created, and the original entry is deleted. If the operation is not
successful, the file is closed under its original name, and the
associated directory is not affected.
The .RENAM routine uses the absence of a value in location F.FNB+N.FID
to indicate that ePARSE must be called to parse a file specification
(an open file always has a nonzero value in F.FNB + N.FID).
If
neither a dataset descriptor nor a default filename block is present,
.PARSE returns a null file name. The rename operation then results in
a new file name of ".;l".
NOTE
The renaming process
is
merely
a
directory operation that replaces an old
entry with a new entry. The file name
stored in the file header block is not
altered.

4.13

FILE EXTENSION ROUTINE (.EXTND)

The .EXTND routine is called to extend either
contiguous
or
noncontiguous files.
The file to be extended can be either open or
closed.
A call to the .EXTND routine disables automatic file
truncation.

The following registers must be preset before calling this routine:
RO

Must contain the address of the associated FDB.

Must contain a numeric value specifying the number of
to be added to the file.

Must contain the extension control bits, as appropriate. The
possible
bit configurations for controlling file-extend
operations are detailed in Table 4-1. This table defines the
bits in the low-order byte of R2. The high-order 8 bits of
R2 (Bits 8 through 15) are used in conjunction with the 16
bits of Rl to define the number of blocks to be added to the
file (see NOTE 1 below).
NOTES
1.

The contents of Rl and the high-order
byte of R2 (Bits 8 through 15) are used
by FCS in accomplishing the specified
.EXTND operation.
Thus, 24 bits of
magnitude are available for specifying
the number of blocks by which the file
is to be extended.

If a file previously had space allocated
to it, a contiguous .EXTND cannot be
done. You can create a contiguous file
by opening a new file with a zero
allocation and then calling .EXTND to
allocate the desired number of blocks.

4-21

blocks

FILE CONTROL ROUTINES
3.

When writing a new file using Queue I/O
directives, the task must explicitly
issue
.EXTND calls as necessary
to
reserve enough blocks for the file, or
the file must be initially created with
enough blocks allocated for the file.
In addition,
the task must put
an
appropriate value in the FDB for the
end-of-file block number {F.EFBK) before
closing
the
file or rewinding and
reading it.

If R2 contains a zero, FCS
noncontiguous allocation.

defaults

To turn off automatic file truncation and close
following routines:
•

.EXTND with Rl and R2 both containing 0

CLOSE$

the

file,

call

the

The above procedure is the opposite of a call to .TRNCL.

4.14

FILE TRUNCATION ROUTINE (.TRNCL)

Tne .TkNCL routine truncates a file to its logical end-of-file
deallocates any space beyond this point, and closes the file.

point,

The following register must be preset before calling this routine:
RO

Must contain the address of the associated FDB.

The file must have been opened with both write
privileges. Otherwise, the truncation will fail.

and

extend

access

The close operation will be attempted even if the truncation operation
Ldii~.
i~
errors occur in both operations, the error code from the
close operation will be returned.
A call to .TRNCL turns on automatic file truncation.
If automatic
truncation is on, the file
is truncated to end-of-file when it is
closed.
If automatic truncation is off, the file is not truncated.
FCS turns on automatic truncation when it extends a file.
the .EXTND routine turns off automatic truncation.

4.15

call

FILE DELETION ROUTINES

The .MRKDL and .DLFNB routines are provided for deleting files.

4-22

FILE CONTROL ROUTINES
NOTE
If the .MRKDL or .DLFNB routine is used
to delete a file containing sensitive
information, it is recommended that you
zero the file before closing it, or
reformat the disk
to
destroy
the
sensitive information.
(Although the
file is marked
for
deletion,
the
information physically remains on the
volume until written over with another
file,
and
could
be
analyzed
by
unauthorized users.)

4.15.1

.MRKDL - Mark Temporary File for Deletion

The .MRKDL routine is used in conjunction with a temporary file, that
is, a file created through the OPNT$W macro call (see Section 3.3).
Such a file has no associated directory entry.
A call to the .MRKDL routine is issued prior to closing a temporary
file.
The file so marked is then deleted automatically when the file
is closed.
Table 4-1
R2 Control Bits for .EXTND Routine
Value in Low-Order
Byte of R2

Meaning

Indicates that
noncontiguous.

the

extend

200

Indicates that
noncontiguous.
file attribute.

the
This

extend
is
to
be
clears the contiguous

201

Indicates that the contiguous area is to be
added
to
the
file.
This clears the
contiguous file attribute.

203

Indicates
that
the
largest
available
contiguous area is to be added to the file
if the desired
extend
space
is
not
available.
This clears the contiguous file
attribute.

205

Indicates that this is the initial
The file is to be contiguous.

207

Indicates that the largest contiguous area
up to the specified extend size is to be
added to the file.
The file is to be
contiguous.

extend.

(continued on next page)

4-23

FILE CONTROL ROUTINES
Table 4-1 (cont.)
R2 Control Bits for .EXTND Routine
Value in Low-Order
Byte of R2

Meaning

210

Indicates that the file is to be extended by
the default extend size for the volume. The
extend is to be noncontiguous.

211

Indicates that the file is to be extended by
the default extend size for the volume. The
extend is to be contiguous, whereas the file
is to be noncontiguous.

Before calling the .MRKDL
register:
RO

routine,

you

must

preset

the

following

Must contain the address of the associated FDB. This FDB is
assumed to contain the file identification, device name, and
unit information pertaining to the file to be deleted.

If the .MRKDL routine is invoked while the temporary file is open, as
is normally done, then the file is deleted unconditionally when it is
closed. This occurs even if the calling task terminates abnormally
without closing the file.

4.15.2

.DLFNB - Delete File by Filename Block

This routine is used to delete a file by filename block.
The .DLFNB
routine assumes that the filename block is completely filled in; when
called, it closes the file, if necess-ary, and then deletes the file.
Before calling this routine, the following register must be preset:
RO

Must contain the address of the associated FDB.

The .DLFNB routine operates in the same manner as that of the routine
invoked by the DELET$ macro call (see Section 3.18), but .DLFNB does
not require any of the .PARSE logic and is thus considerably smaller
(in terms of memory requirements) than the normal DELET$ function.
Like the DELET$ operation, however, if the file to be deleted is not
currently open, and if an explicit file version number is not present
in offset location N.FVER of the associated filename block, then the
.DLFNB operation fails.

4-24

FILE CONTROL ROUTINES
4.16

DEVICE CONTROL ROUTINE (.CTRL)

The .CTRL
functions.
functions:

routine is called to perform device-specific control
The following are examples of .CTRL device-specific

Rewind a magnetic tape volume set.

Position to the logical end of a magnetic tape volume set.

Close the current magnetic tape
operations on the next volume.

Space forward or backward n blocks on a magnetic tape.

Rewind a file on
a
magnetic
(record-oriented device).

Clear terminal

volume

tape

and

continue

file

terminal

end~of-file.

The following registers must be preset before calling this routine for
items 1 to 3 above:
RO

Must contain the address of the associated FDB.

Must contain one of the following function codes:
•

FF.RWD to rewind a magnetic tape volume set

•

FF.POE to position to the logical end of
tape volume set

•

FF.NV to close the current volume and continue file
operations on the next volume of a magnetic tape
volume set.

magnetic

R2 and R3 must each contain O.
When using .CTRL to space forward or backward, you must ensure
registers RO, Rl, R2, and R3 contain the following values:

that

Must contain the address of the associated FDB.

Must contain the value FF.SPC.

Must contain the number of blocks to space forward or
backward. A positive number means space forward; a negative
number means space backward.

Must contain O.

When using .CTRL to rewind a file, you must ensure that register
contains the value FF.RWF and that registers R2 and R3 contain O.
See Chapter 5 for an explanation of using .CTRL to accomplish
tape device-specific functions.

4-25

CHAPTER 5
FILE STRUCTURES

IAS and RSX-11 support an identical file structure on disk, DECtape,
and DECtape II.
They also support ANSI file structure on magnetic
tape.
The disk, DECtape, and DECtape II file structure is
the magnetic tape file structure is ANSI standard.

5.1

called

FILES-11;

DISK AND DECTAPE FILE STRUCTURE (FILES-11)

Volumes contain both user files and system files.
Disks and DECtapes
initialized through the INITIALIZE (IAS) or INITVOLUME (RSX) command
have the standard FILES-11 structure built for them automatically.
The standard system files created through these commands include the

following:
1.

Index file

Storage allocation file

Bad block file

Master File Directory (MFD)

Checkpoint file

Each FILES-11 volume has a file of each type. A volume may have more
than one directory file;
such files, created by the CREATE/DIRECTORY
command in IAS, and the UFD command in RSX-11 systems, are used by the
system to locate user files on the volume.

5.1.1

User File Structure

Your data files on disk and DECtape consist of ordered sets of virtual
blocks that constitute the virtual structure of the files as they
appear to you. Virtual blocks can be read and written directly by
your issuing READ$ and WRITE$ macro calls (see Sections 3.15 and 3.16,
respectively). Virtual blocks are numbered in ascending sequence
relative to the first block in the file (which is virtual block 1).

5-1

FILE STRUCTURES
The virtual blocks of a file are stored on the volume as logical
blocks.
The logical block size of all volumes is 256 words; thus,
each virtual block is also 256 words. When access to a virtual block
is requested, the virtual block number is mapped into a logical block
number. The logical block number is then mapped to the physical
address on the associated volume.

5.1.2

Directory Files

A directory file contains directory entries. Each entry consists of a
file name and its associated file number and file sequence number.
The number of required directory files depends on the number of users
of the volume. For single-user volumes, only a Master File Directory
(MFD) is needed; for multiuser volumes, an MFD is required, and one
User File Directory (UFD) is required for each user of the volume.
The MFD contains a list of all the UFDs on the volume, and each UFO
contains a list of all that user's files. UFDs are identified by User
Identification Codes (UICs). A User File Directory is created by the
UFD command in RSX-11 systems, and by the CREATE/DIRECTORY command in
IAS. These commands are described in detail in the RSX-llM/M-PLUS MCR
Operations Manual and the IAS System Management Guide.
Figures 5-1 and 5-2 illustrate the directory structure for single-user
and multiuser volumes, respectively.

5.le3

Index File

The index file contains volume information and user file header
blocks, which are used by the file control primitives (FCP). Because
the file header blocks (see below) are stored in the index file, they
can be located quickly. Furthermore, since a file header block is 256
words in length, it can be read into memory with a single access.
The index file is created when a volume is initialized for use by the
host
operating
system.
During initialization, the information
required by the system is placed in the index file.
Appendix E
contains a detailed description of the format and content of an index
file.

MFD

l
I

FILE A

FILE B

FILE C

ZK-293-81

Figure 5-1

Directory Structure for Single-User Volumes

5-2

FILE STRUCTURES

MFD

UFO
100, 100

UFO
200,200

FILE A

l
FILE B

FILE A

FILE B

FILE C

ZK-294-81

Figure 5-2

5.1.4

Directory Structure for Multiuser Volumes

File Header Block

Associated with each file is a file header block that contains
information describing the file. File header blocks are stored in the
index file. Each file header block is ?~~ words in length and
contains three areas: the header area, the identification area, and
the map area.
The header area identifies the block as a file header block.
Each
file is uniquely identified by a file ID consisting of two wordse The
first word of the file ID (that is, the file number)
is used to
calculate the virtual block number (VBN) of that file's header block
in the index file.
(This calculation is done as follows:
VBN = the
file number + 2 + the number of index file bit map blocks.) The second
word (that is, the file sequence number) is used to verify that the
header block is in fact the header for the desired file.
When a request to access a file is issued, both the file number and
the file sequence number are specified. The access request is denied
if the file sequence number does not match the corresponding field in
the file header block associated with the specified file number.
When a file is deleted, its file header block is made available for
subsequently creating a new file, and when the new file is created, a
different file sequence number is stored in the file header block. If
you attempt to access a file that has been deleted (for example, by
referencing an obsolete directory entry), this updated file sequence
number ensures the failure of the access request, even if the same
file header block is reused for a different file.
The identification area specifies the creation name of the file and
identifies the file owner's UIC.
This area also specifies the
creation date and time, the revision number, the date and time of the
last revision (that is, the time and date on which the last
modification to the file occurred), and the expiration date.
The map area provides the information needed by
virtual block numbers to logical block numbers.

5-3

the

system

map

FILE STRUCTURES
A checksum value is computed each time the file header block is read
from or written to the volume, thus ensuring that the file header
block is transferred correctly.
Appendix F contains a detailed
description of the format and content of the file header block.

5.2

MAGNETIC TAPE FILE PROCESSING

!AS and RSX-11 support the standard ANSI magnetic tape structure as
described
in "Magnetic Tape Labels and File Structure for Information
Interchange," ANSI X3.27-1978.
Any of the following file/volume
combinations can be used:

• Single file on a single volume
• Single file on more than one volume
• Multiple files on a single volume
• Multiple files on more than one volume
Items 2 and 4 above constitute a volume set.
The record format on magtape is different from that on disk.
When a
file that contains variable-length records or fixed-length records
that cross block boundaries is copied to magtape,
it occupies more
blocks on the magtape than it did on the disk. This is so because on
magtape the record counts are larger than on disk, and there is unused
space at the end of the blocks.
In addition, the cannot-crossblock-boundaries bit is set in the file's FDB.
The sequence in which volume and file labels are used and
of each label type is defined in Appendix G.

the

format

NOTE
There is no place for the creation time
the length oL the file in an ANSI
file header label.
Consequently, the
creation time of a file on ANSI magtape
is listed as O.
If a contiguous file is
copied
to
ANSI
magtape
and then
transferred back to disk, the resulting
disk file is not marked contiguous even
if the /CO switch is used, because the
system cannot know how much space to
allocate for the output file when it
reads from magtape.
uL

5.2.1

Access to Magnetic Tape Volumes

Magnetic tape is a sequential access, single-directory storage medium.
Only one user can have access to a given volume set at a time. No
more than one file in a volume set can be open at a time.
Access
protection is performed on a volume set basis. On volumes produced by
DIGITAL systems, user access rights are determined by the contents of
the owner identification field as described in Section G.1.1.1.
Volumes produced by non-DIGITAL systems are restricted to read-only
access unless explicitly overridden at MOUNT time.

5-4

FILE STRUCTURES
5.2.2

Rewinding Volume Sets

You can rewind a magnetic tape volume set either by using the FDOP$R
macro call before an OPEN$ or CLOSE$ or by using the .CTRL file
control subroutine. Regardless of the method used to rewind the
volume set, the following procedures are performed by the file control
system:
1.

All mounted volumes are rewound to BOT.

If the first volume in the set is not mounted, the unit to be
used is placed off line.

If the volume is not already mounted and if the rewind was
requested by an OPEN$ macro call or by a .CTRL call, a
request to mount the first volume is printed on
the
operator's console.

If the rewind was requested on a CLOSE$ macro call, no
message is issued until the next volume is needed.

5.2.3

mount

Positioning to the Next File Position

The normal procedure for writing a new file onto a magnetic tape is to
begin writing the file following the end of the last file currently in
the volume set. However, the FDOP$R macro call can be used to
indicate that the new file is to be written immediately after the
end-of-file labels of the most recently closed file. This next file
position option causes the loss of any files physically following this
most recently closed file in the volume set.
If, in addition to the next file position option, the rewind option
also is specified, the fil~ is created after the VOLl label on the
first volume of the set. All files previously contained in the entire
volume set are lost.
To create a file in the next file position, FA.POS must be set in FDB
location F.ACTL.
The default value for this FDB position is O (not
FA.POS). The default indicates that the file system is to position at
the logical end of the volume set to create the file.
When the default is used, no check is made for the existence of a file
with the same name in the volume set. Therefore, a program written to
use magnetic tape normally should specify FA.POS.
The next file position option is ignored by directory device file
processors.
However, programs written mainly for directory devices
can specify the next file position option in open commands for output
and, therefore, override the position-to-end process normally used
automatically when used with ANSI magtape.

5.2.4

Single-File Operations

Single-file operations are performed by specifying the rewind option
before the open and before the close. Using this approach, you can
perform scratch tape operations as follows:
1.

Open the first file with rewind specified.

Write the data records and close the file with rewind.

Open the first file again for input (rewind is optional).
5-5

FILE STRUCTURES
4.

Read and process the data.

Close the file with rewind.

Open the second file with rewind specified.

Write the data records.

Close the file
processing.

5.2.5

with

rewind

and

perform

any

additional

Multiple-File Operations

A multiple-file volume is created by opening, writing, and then
closing a series of files without specifying a rewind. The sequential
processing of files on the volume can be accomplished by closing
without rewind and then opening the next file without rewind.
Opening a file for extend (OPEN$A) is legal only for the last file
the volume set.
The following tape operations are performed to create a
tape volume:
1.

Open a file for output with rewind.

Write data records and close the file.

Open the next file with no rewind.

Write the data records and close the file.

Repeat for as many files as desired.

multiple-file

Files on tape can be opened in a nonsequential order, but increased
processing and tape-positioning time is required.
Nonsequential
access of files in a multivolume set is not recommended.

5.2.6

Using .CTRL

The .CTRL file control routine can be called to override
defaults for magnetic tape. Examples of its uses are:

normal

Continuing processing a file on the next volume of a
set before the end of the current volume is reached.

Positioning to the logical end-of-volume set.

Rewinding a volume at other than file open or close.

Spacing forward or backward n records.

Rewinding a file.

FCS

volume

When .CTRL is used to continue processing a file on the next volume,
the first file section on the next volume is opened. File sections
occur when a file is written on more than one volume. The portion of
the file on each of the volumes constitutes a file section. For input
files, the following .CTRL processing occurs:
1.

If the current volume is the last volume in the set (that is,
there is no next volume), end-of-file is reported to you.
5-6

FILE STRUCTURES
2.

If another file section exists, the current volume is rewound
and the next volume is mounted.
A request to the operator is
printed, if necessary.

The header label {HDRl) of the next file section is read
checked.

If all required fields check, the operation continues.

If any check fails, the operator is requested
correct volume.

mount

and

the

For output files, the following processing occurs:

The current file section is closed with EOVl and EOV2
and the volume is rewound.

The next volume is mounted.

A file with the same name and the next higher section number
is opened for write.
The file set identifier is identical
with the volume identifier of the first volume in the volume
set.

labels

NOTE
I/O buffers that are currently in memory are
on the next file section.

written

When .CTRL is used to position to the logical end-of-volume set,
the
file system positions between the two tape marks at the logical end of
the last volume in the set.
When .CTRL is used to space forward or backward across blocks
magnetic tape, spacing crosses volumes for multivolume files.

5.2.7

Examples of Magnetic Tape Processing

The following pages contain examples of FCS statements used to process
magnetic tape.
Macro parameters not related to magnetic tape handling
have been omitted from the statements so that you need consider only
those matters directly related to magnetic tape.

5.2.7.1 Examples of OPEN$W to Create a New File - All routines expect
RO to contain the FDB aadress.
OPRWDO:
OPEN WITH REWIND
FDOP$R
BR

RO,,,,,#FA.ENB!FA.RWD
OPNOUT

;SET REWIND AND ENABLE USE
;OF F.ACTL

OPNXTO:
OPEN FOR NEXT FILE POSITION
FDOP$R
BR

RO,,,,,#FA.ENB!FA.POS
OPNOUT

OPROYK:

5-7

;SET POSITION TO NEXT
;AND ENABLE USE OF F.ACTL

FILE STRUCTURES
OPEN FILE AT END OF VOLUME KEEPING CURRENT USER
ACCESS CONTROL BITS
BIC
BR

#FA.ENB,F.ACTL(RO)
OPNOUT

;DISABLE USE OF F.ACTL

OPROVO:
OPEN FILE AT END OF VOLUME - SELECT SYSTEM DEFAULT FOR
USER ACCESS CONTROL BITS
;DISABLE USE OF AND RESET
FDOP$R R0,,,,,#0
BR
OPNOUT
;F.ACTL TO ZERO
OPEN FILE WITH CURRENT USER ACCESS CONTROL
;

OPOURO:
BIS
OPNOUT: FDBF$R
OPEN$W
RETURN

#FA.ENB,F.ACTL(RO)
R0,,#2048.
RO

;ENABLE USE OF F.ACTL
;OVERRIDE BLOCK SIZE FOR TAPE

5.2.7.2 Examples of OPEN$R to Read a File - All routines expect RO to
contain the FDB address.
OPRWDI:
OPEN WITH REWIND
FDOP$R
BR

RO,,,,,#FA.ENB!FA.RWD
OPNIN

OPCURI:
OPEN STARTING SEARCH AT CURRENT TAPE POSITION KEEPING USER
ACCESS CONTROL BITS
BIC
BR

#FA.ENB,F.ACTL(RO)
OPNIN

;DISABLE USE OF F.ACTL

OPEN USING USER ACCESS CONTROL
;

OPDFLI: BIS
OPNIN:
FDBF$R
OPEN$R
RETURN

#FA.ENB,F.ACTL(RO)
R0,,#2048.
RO

;ENABLE USE OF F.ACTL
;OVERRIDE BLOCK SIZE FOR TAPE

5.2.7.3 Examples of CLOSE$ - All routines expect RO
FDB address.

contain

the

CLSCUR:
CLOSE LEAVING TAPE AT CURRENT POSITION AND KEEPING
USER ACCESS CONTROL BITS
BIC
BR

#FA.ENB,F.ACTL(RO)
CLOSE

;DISABLE USE OF F.ACTL
;DEFAULT IS LEAVING AT CURRENT
;POSITION

CLSRWD:
CLOSE REWINDING THE VOLUME
FDOP$R
BR

RO,,,,,#FA.ENB!FA.RWD
CLOSE

5-8

;SET REWIND AND ENABLE USE OF
;F.ACTL

FILE STRUCTURES

; CLOSE WITH USER ACCESS CONTROL BITS
;

CLSDFL: BIS
CLOSE: CLOSE$
RETURN

#FA.ENB,F.ACTL(RO)
RO

;ENABLE USE OF F.ACTL

5.2.7.4 Combined Examples of OPEN$ and CLOSE$ for Magnetic Tape - The
following examples call routines in previous examples. By combining
various magnetic tape operations, you can process tape volumes in the
following ways.
;

; SCRATCH TAPE OPERATIONS--SINGLE FILE VOLUME-;

SCROUT: MOV
CALL
RETURN
SCRIN: MOV
CALL
RETURN
CLSCRO: MOV
BR
CLSCRI: MOV
CLSVOL: CALL
RETURN

#FDBOUT,RO
OPRWDO

;SELECT FDB AND OPEN
;OUTPUT FILE WITH REWIND

#FDBIN, RO
OPRWDI

;SELECT FDB AND OPEN FOR
;INPUT WITH REWIND

#FDBOUT,RO
CLSVOL
FDBIN,RO
CLSRWD

;CLOSE SCRATCH FILE
;REWINDING VOLUME

MULTI-FILE VOLUME OPERATIONS
;

OPNXTI:
OPEN FILE FOR READING WHEN FILE IS NEXT OR FURTHER UP THE VOLUME
MOV
CALL
RETURN

#FDBIN,RO
OPCURI

;SELECT FDB
;OPEN FILE

OPENIN:
OPEN FILE FOR READ ING WHEN POSITIONED PAST IT
MOV
CALL
RETURN

;SELECT FDB

#FDBIN I RO
OPRWDI

MULTI-FILE OUTPUT OPERATIONS
;

OPNINT:
START NEW VOLUME DESTROYING ALL PAST FILES ON IT
MOV
CALL
RETURN

;SELECT OUTPUT FDB
;OPEN WITH REWIND

#FDBOUT, RO
OPRWDO

OPNEXT:
OPEN OUTPUT FILE AT NEXT FILE POSITION DESTROYING ANY FILE
THAT MAY BE AT OR PAST THAT POSITION
MOV
CALL
RETURN

#FDBOUT,RO
OPNXTO

;SELECT OUTPUT FDB

OPENDT:

5-9

FILE STRUCTURES
OPEN OUTPUT FILE AT CURRENT END OF VOLUME SET KEEPING USER
ACCESS CONTROL BITS
MOV
CALL
RETURN

#FDBOUT,RO
OPROVK

;SELECT OUTPUT FDB

OPNEOV:
OPEN OUTPUT FILE AT CURRENT END OF VOLUME AND MAKE THAT THE USER
ACCESS CONTROL
MOV
CALL
RETURN

#FDBOUT,RO
OPROVO

;SELECT OUTPUT FDB

NOT LAST FILE IN FILE SET CLOSE ROUTINE
;

CLSFLO: MOV
BR
CLSFLI: MOV
CLSXX:
CALL
RETURN

#FDBOUT,RO
CLSXX
#FDBIN, RO
CLSCUR

;SELECT OUTPUT FDB
;SELECT INPUT FDB

TO APPEND TO LAST FILE
OPEN$A

#FDBOUT

5-10

CHAPTER 6
COMMAND LINE PROCESSING

As noted in Section 2.4.3, a collection of routines available from the
system object library ([l,l]SYSLIB.OLB) may be linked with your
program to provide all the logical capabilites required to process
command lines dynamically.
These system facilities include the
following routines:
1.

Get Command Line (GCML). This routine accomplishes all the
logical functions associated with the entry of command lines
from a terminal, an indirect command file, or an on-line
storage mea1um.
using ~~ML relieves you of the burden of
manually coding command line input operations.

Command String Interpreter (CSI).
Normally, this routine
takes command lines from the GCML command line input buffer
and parses them into the appropriate dataset descriptors
required by FCS for opening files.

This body of routines is linked with your program at task-build time.
GCML and CSI are often jointly incorporated in system or application
programs as a standardized interface for obtaining and interpreting
dynamic command line input.
The flow of data during command line
processing is shown in Figure 6-1.
Although these routines are presented in the context of ·being used
together
for processing command line input, each may be used
independently of the other. Doing so, however, means that you must
manually code the functions otherwise performed by the missing
component. The joint use of these routines is assumed throughout this
chapter to be the "normal" situation.
Invoking GCML and CSI functions requires that certain initialization
operations be accomplished at assembly time. This initialization sets
up the GCML command line input buffer, defines and initializes control
blocks for both GCML and CSI, and establishes the necessary working
storage and communication areas for these routines.
Also, the
appropriate macro calls that invoke GCML and CSI execution-time
functions must be included in the source coding at desired logical
points to effect the dynamic processing of command lines.
GCML and CSI macro calls observe the same register conventions
applicable to FCS. All registers except RO are preserved exactly as
in all FCS macro calls. RO is used to contain the address of the GCML
control block or the CSI control block, as appropriate.
As with all FCS macro calls, the GCML and CSI macro calls must also be
listed as an argument in an .MCALL directive (see Section 2.1) before
being issued in your program.

6-1

COMMAND LINE PROCESSING

ASCII DATA

GCML

CSI

DEFAULT
FILENAME
BLOCK

DATASET
DESCRIPTOR

FCS
(.PARSE)

FILENAME!
BLOCK

ZK-295-81

Figure 6-1

6.1

Data Flow During Command Line Processing

GET COMMAND LINE (GCML)

The Get Command Line
(GCML)
routine embodies all the
logical
capabilities required to enter command lines dynamically during
program execution. GCML accepts input from a terminal or an indirect
command file that contains predefined command lines.
If your program
allocates sufficient buffer space in the file storage region
(see
Section 2.6), GCML accepts commands that are longer than one line of
terminal input. The continuation of commands from one line to the
next is effected when a hyphen appears as the last printing character
of a command line.

6-2

COMMAND LINE PROCESSING
All GCML functions require you to create and initialize a GCML control
block. The macro call that accomplishes this function is described in
detail in the following section. The GCML run-time macro calls that
may be issued dynamically are described in Section 6.1.3.

6.1.l

GCMLB$ - Allocate and Initialize GCML Control Block

Issuing the GCMLB$ macro call accomplishes the following assembly-time
functions:
•

Reserves storage for, and initializes
within, your program.

GCML

control

block

•

Creates and initializes an FDB in the first part of the GCML
control block. This FDB is used to open a command file. Such
a file, which may employ a terminal or a file-structured
device such as a disk, is opened and read by your program in
the same manner as any other file.
Initializing
and
maintaining this FDB, however, is under GCML and FCS control
and need not be of concern to you.

•

Creates and initializes a default filename block within the
GCML control block. This default filename block pertains to
an indirect command file. If you do not specify an explicit
file name string for an indirect command file, the values CMI
for the file name and .CMD for the file type are assumed by
default. There is no default designation for the device name.

•

Defines the symbolic offsets for the GCML control block and
initializes certain offsets to required values. These offsets
are described in detail in Section 6.1.2.

The GCMLB$ macro call is specified in the following format:
label:

GCMLB$

maxd,prmpt,ubuf ,lun,pdl,size

label
A symbol that names the GCML control block and defines its
address.
This label permits the GCML control block to be
referenced directly by all the GCML run-time routines that
require access to this structure (see Section 6.1.3).
maxd
A numeric value that specifies the maximum nesting
depth
permitted for indirect command files. This parameter determines
the number of nested indirect command files that GCML will be
allowed to access in obtaining command line input.
An indirect command file, which often resides on disk, contains
well-defined, nonvarying command sequences, which may be read
directly by GCML to control operations that are highly repetitive
(such as Task Builder activities). Significant advantages in
terms of convenience and faster execution result from using an
indirect command file.

6-3

COMMAND LINE PROCESSING
If this parameter is not specified, a nesting level depth of 0 is
defined by default, effectively eliminating an indirect command
file as a source of command line input.
prmpt
A user-specified, 3-character ASCII prompting sequence.
This
parameter constitutes a default prompt string that is typed out
by GCML to your terminal to solicit command line input.
The ASCII prompting sequence is
6-byte string:

formulated

into

the

A carriage return (<CR>) and a line-feed (<LF>)

The three ASCII characters that you specify

A right angle bracket (>)

The above string initializes GCML control block
G.DPRM (see Section 6.1.2).

offset

following

location

If this parameter is not specified, the right angle bracket (>),
preceded by three blanks, is defined by default for use by GCML
as the default prompting sequence.
ubuf
The address of a buffer to be used by GCML for temporary storage
of command line input.
If this parameter is not specified, a
buffer, whose length is determined by the size parameter, is
reserved in the GCML control block for command line input. If
neither this pnrnmeter nor the size parameter is specified, a
41-word buffer is reserved by default in the GCML control block.
lun
A logical unit number. The device assigned to this logical unit
number is used by GCML as the command input device. If this
parameter is not specified, a logical unit number of 1 is used by
default.
pdl
The address of an area reserved in your program for use as a
push-down list. This area is reserved as working storage for use
in connection with indirect command files.
Normally, the pdl parameter is not specified;
in this case,
sufficient storage for the push-down list is added to the control
block by default in accordance with the algorithm described
below.

6-4

COMMAND LINE PROCESSING
The push-down list is created
equivalent to the following:
label:

.EVEN
.BLKB

through

statements

logically

G.LPDL

The user-supplied label specifies the push-down list and defines
its address;
G.LPDL, which is defined by the GCMLB$ macro, is
the length {in bytes) of the push-down list.
The length of the push-down list is a function of the maximum
number of nested indirect command files that may be accessed by
GCML in obtaining command line input. The value of G.LPDL is
calculated according to the following algorithm:
1.

Add 1 to the maximum nesting level depth
maxd parameter {see above).

declared

with

Multiply the sum of step 1 by 16{decimal), the appropriate
number of bytes that must be reserved for the push-down list.

For example, if the maxd parameter is specified as 4, the
of the push-down list is determined as follows:
{4+1)*16. = 80.

the

length

bytes

From the above, note that 16(decimal)
bytes of
required for each indirect command file, plus
16{decimal) bytes for use as general overhead.

storage are
a total of

size
The size, in bytes, of the buffer reserved for command line
inputo
The specified size must always include two extra bytes
that are used internally by GCML.
The default value for size is
82
(that is, 80 bytes for command line input and 2 bytes GCML
overhead).
If you want GCML to accept continuation lines, the specified
value for the size parameter must be greater than 82. When the
size is greater than 82, the bit value GE.CON is set in the
status and mode control byte {offset G.MODE) of the GCML command
block. This value indicates that the continuation mechanism is
in effect.
The following examples represent a
appear in your program:
GCLBLK: GCMLB$
GCLBLK: GCMLB$
GCLBLK: GCMLB$

GCMLB$

macro

call

4.,GCM,BUFADR,l.
,,BUFADR
DEPTH,GCM,BUFADR,CMILUN,PDLIST,BUFSIZ

6-5

might

COMMAND LINE PROCESSING
6.1.2

GCMLD$ - Define GCML Control Block Offsets and Bit Values

The GCMLD$ macro, which is invoked automatically by the GCMLB$
macro call, locally defines the GCML control block offsets and
bit values within the current module.
These offsets
and
associated bit values are listed and described below.
Off set
Name
G.ERR

Functional Significance
Error Return Code Byte.
This field
initially
contains O.
If any one of the error conditions
recognized by GCML occurs during the processing of
a command line, an appropriate error code is
returned to offset location G.ERR in the control
block.
These error codes are described below:
GE.IORl Indicates that an I/O error occurred
during the input of a command line.
GE.OPRl Indicates that GCML was unable
open or reopen the specified command file.
GE.BIF detected
file.

Indicates that a syntax error was
in the name of the indirect command

Indicates that an attempt was made to
GE.MOE exceed the maximum permissible nesting-level
depth for an indirect command file
(see the
maxd parameter in the GCMLB$ macro call above) •
GE.RBG Indicates that the command line input
buffer was too small for the total command.
This condition can occur when multiple lines
have
been
entered using the continuation
mechanism.
The input buffer contains as much
of the command as possible.
GE.EOF - Indicates that the
on
the first
(unnested)
detected.

end-of-file
(EOF)
command file was

This code is set in connection with command file
input.
When the first call is issued for input,
GCML attempts to retrieve an MCR/PDS command line.
The first line obtained, whether it is an MCR/PDS
command or a terminal command, is accomplished at
command level O.
If the name of an indirect
command file is then entered, the command input
level
is incremented to 1.
Each indirect file
name entry thereafter increments the command input
level.
When the end-of-file (EOF) is encountered
on any given indirect file,
the command input
level
is decremented by 1, restoring the count to
the previous level and reopening the associated
command file.
The next command line from that
file is then read.

1. For GE.IOR and GE.QPR, additional information concerning the error
is available by examining the FCS error code at offset F.ERR from the
start of the GCML block.
6-6

COMMAND LINE PROCESSING

Off set
Name

Functional Significance
If an MCR/PDS command has already been read at
level O, entering another MCR/PDS command when
level 0 is again reached causes the error code
GE.EOF to be returned to offset location F.ERR of
the GCML control block. Hence, only one MCR/PDS
command line can be read at level O. If input
thus fails at MCR/PDS level O, then GCML continues
to prompt for input until you type CTRL/Z to
indicate terminal end-of-file (EOF).
In summary, the first line of input is always read
at level O. This initial input may be an MCR/PDS
command; if the MCR/PDS command fails or is null,
the command input file (normally a terminal) is
then opened at level 0. Multiple inputs at level
O are permissible only in the latter case, that
is, from the command input file.

G~MODE

Status and Mode Control Byte.
This field is
initialized at assembly time with bit definitions
to specify certain default actions for GCML durinq
the retrieval of a command line. At run time, yo~
can reset default status and mode control bits, if
desired, by issuing a Bit Clear Byte (BICB)
instruction that takes as the source operand the
symbolic name of the bit to be cleared. In the
case of the GE.LC value (see below), the BISB
instruction can be used to override the default
action.
The symbolic names of the bits defined in
status and mode control byte are as follows:

the

GE.IND - (Default)
Indicates that a command
line containing a leading at sign (@) is to be
treated as an explicit indirect command file
specifier.
If, for any reason, you reset this
bit to O, a command line containing a leading
at sign (@) is returned to the calling program.
GE.CLO - (Default) Indicates that the command
file currently being read is to be closed after
each issuance of the GCML$ macro call. If you
reset this bit to 0 for any reason, GCML keeps
the current command file open between calls for
input.
In this case, the FSR (see Section
2.6.1)
must
include
one
additional
512(decimal)-byte
buffer
for command line
input. This requirement adds to the total FSR
block buffer space normally reserved for the
maximum number of files that may be open
simultaneously for record I/O processing.
Clearing the GE.CLO bit in the status and mode
control byte effectively renders 512(decimal)
bytes of FSR block buffer space unavailable for
other purposes, since the command file remains
open between calls for command line input.

6-7

COMMAND LINE PROCESSING
Off set
Name

Functional Significance
GE.COM - (Default) Indicates that a command line
having a leading semicolon (;) is to be treated as
a comment. Such lines are not returned to the
calling program.
If, for any reason, you reset
this bit to O, a command line containing a leading
semicolon (;) is returned to the calling program.
GE.CON - Indicates
that
the
continuation
mechanism is in effect. This is the default if
the value of the size parameter of the GCMLB$
macro is greater than 82. You must not attempt to
set this value in the mode byte without providing
a buffer larger than 82 bytes.
GE.LC - Indicates that lowercase characters in
the command line are to be passed to your program
without mapping. Unless you explicitly set this
value in the GCML control block at run time, the
default action will be to map lower- and uppercase
characters to uppercase before transmission to
your program.

G.PSDS

Prompt String Descriptor. This 2-word field is
initialized to 0 at assembly time through the
GCMLB$ macro call (see Section 6.1.1).
When the GCML$ macro call is issued to request
command line input (see Section 6.1.3.1), the
address and the length of a prompting sequence is
usually not specified. In this case, the prompt
string descriptor words in the GCML control block
are cleared, causing GCML to type out the default
prompt string contained in offset location G.DPRM
(see below) to solicit command line input.
If you wish to define an alternate prompt string
elsewhere in the program, you may do so through
the .ASCII directive. The address and length of
this alternate prompt string may then be specified
as the adpr and lnpr parameters in subsequent
GCML$ macro calls. These parameters cause offset
locations G.PSDS+2 and G.PSDS to be initialized
with the address and the length, respectively, of
the alternate prompt string. The alternate prompt
string is then typed out by GCML to solicit
command line input, thereby overriding the default
prompt string previously established through the
GCMLB$ macro call (see G.DPRM below).
If the adpr and lnpr parameters are not specified
in a subsequent GCML$ macro call, offset location
G.PSDS in the control block is automatically reset
to O, causing GCML to revert to the use of the
default prompt string contained in offset location
G.DPRM.

G.CMLD

Command Line Descriptor.
This 2-word field is
initialized by GCML after retrieving a command
line. The address of the line just obtained is
returned to offset location G.CMLD+2, and the
length (in bytes) of the command line is returned
to offset location G.CMLD.

6-8

COMMAND LINE PROCESSING
Off set
Name

Functional Significance
The contents of these word locations in the GCML
control block may be passed to CS! as the "buff"
and "len" parameters in the CSI$1 macro call (see
Section
6.2.3.1).
The combination of these
parameters
constitutes
the
command
line
descriptors that enable CSI to retrieve file
specifiers from the GCML command line
input
buffer.
Impure Area Size Indicator.
This symbol
is
defined at assembly time, indicating the size of
an impure area within the GCML control block to be
used as working storage for pointers, flags,
counters, and so forth, in connection with input
from an indirect command file.
In normal usage,
you need not be concerned with this symbol.

G.ISIZ

The space between the FDB and the default prompt
string (see G.DPRM below) constitutes the impure
area of the GCML control block. The size of the
FDB is defined by the value of the symbol S.FDB.
Thus, the size of the impure area is equal to
G.DPRM-S.FDB.
Default Prompt String.
This 6-byte field is
initialized at assembly time with the default
prompt string created through the prmpt parameter
of the GCMLB$ macro call (see Section 6.1.1). In
the absence of the adpr and lnpr parameters in the
GCML$ macro call (see Section 6.1.3.1), this
default prompt string is typed out by GCML to
solicit terminal input.

G.DPRM

You can reference the GCML control block offsets and bit values in
another module by establishing the appropriate symbolic definitions
within that module through one of the following statements:
;DEFAULT LOCAL DEFINITION.

GCMLD$

6.1.3

GCMLD$

DEF$L

;LOCAL DEFINITION.

GCMLD$

DEF$G

;GLOBAL DEFINITION.

GCML Run-Time Macro Calls

Three run-time macro calls are provided in GCML
functions, as described below:

perform

GCML$

- Tc retrieve a command line

RCML$

- To reset the indirect command file scan to
(unnested) level

CCML$

- To close the current command file

specific

the

first

These routines are described separately in the following sections.

6-9

COMMAND LINE PROCESSING
6.1.3.1 GCML$ - Get Command Line - The GCML$ macro call serves as
your program interface for retrieving command lines from a terminal or
an indirect command file.
This macro call can be issued at any
logical point in the program to solicit command line input.
This macro call takes the following format:
GCML$

gclblk,adpr,inpr

gclblk
The address of the GCML control block.
This symbol must be the
same as that specified at assembly time in the label field of the
GCMLB$ macro call (see Section 6.1.1).
If this parameter is not
specified, RO is assumed to contain the address of the GCML
control block.
ad pr
The address of your program location containing an alternate
prompt string.
When this optional parameter and the inpr
parameter below are present in the GCML$ macro call, the
alternate prompt string is typed out on your terminal to solicit
command line input.
The normal default prompt string, as
contained in offset location G.DPRM of the GCML control block
(see Section 6.1.2), is thereby overridden.
lnpr
The length (in bytes)
of the alternate prompt string.
This
parameter is also optional;
if not specified, offset location
G.PSDS in the GCML control block (see Section 6.1.2) is cleared.
If this parameter is specified but the adpr parameter above is
not, an .ERROR directive is generated during assembly that causes
the error message PROMPT STRING MISSING to be printed in the
assembly listing.
This message is a diagnostic announcement of
an incomplete prompt string descriptor in the GCML$ macro call.
If this parameter is not given but the adpr parameter above is
given, the default prompt string is used.
If the adpr and lnpr parameters are not specified in a subsequent
GCML$ macro call, offset location G.PSDS in the GCML control block is
automatically reset to 0, causing GCML to revert to using the default
prompt string contained in offset location G.DPRM (see Section 6.1.2
above) •
When the GCML$ macro call is issued, the following actions occur:
1.

RO is loaded with the address of the GCML control block.
If
the gclblk parameter is not specified, as described above, RO
is assumed to contain the address of the GCML control block.
If it does not, RO must first be initialized manually with
the address of the control block before the GCML$ macro call
is issued.

The address and the length of the alternate prompt string, if
specified, are stored in control block offset locations
G.PSDS+2 and G.PSDS,
respectively.
These
two
words
constitute the alternate prompt string descriptor.

6-10

COMMAND LINE PROCESSING
3.

Code is generated that calls GCML to transfer a command line
to the command line input buffer.
If the last character of
an input line is a hyphen, and if the value GE.CON is present
in the status and mode control byte, GCML will automatically
transfer commands that run to more than one line.
The
continuation lines obtained are concatenated in the input
buffer with the continuation hyphen(s) removed.

At the initial issuance of the GCML$ macro call, an attempt is made to
retrieve an MCR/PDS command line.
If this attempt fails, or if the
MCR/PDS command line is null, the FDB within the GCML control block is
used to open a file for command line input.
If the command input
device is a terminal, a prompt string is typed out to solicit input.
Any desired command input may then be entered.
If the continuation
mechanism is being used, the prompt string is similarly typed to
solicit subsequent portions of a continued command line.
If appropriate, you may enter an at sign (@) as the first character in
the command line, followed by the name of an indirect command file.
This file name identifies an explicit indirect command file from which
input is to be read.
GCML then opens this file and retrieves the
first command line therein.
On successive GCML calls, this file
is
read until one of the following occurs:
1.

The end-of-file (EOF) is detected on ~ne current indirect
file.
In this case, the current indirect file is closed, the
command input level count is decremented by 1, and the
previous command file
is reopened.
If the command input
level count is already 0 when EOF is detected, the error code
GE.EOF is returned to offset location G.ERR of the GCML
control block (see Section 6.1.2).

An indirect file specifier is encountered in a command line.
In this case, the current indirect command file is closed (if
not already closed), and the new indirect file
is opened.
The first command line therein is then read.

An RCML$ macro call is issued in the program
(see Section
6.1.3.2 below).
In this case, the current indirect command
file is closed, and the command input count reverts to level
O;
that is, the top level command file is again used for
input.

You may also enter a semicolon (;)
as the first character in the
command line.
If GE.COM is set, such a line is treated as a comment
and is not returned to the calling program.
If GE.COM is clear, the
line is returned to the calling program.
Whether a command line is entered manually or retrieved from an
indirect command file, the address and the length of the command line
thus obtained are returned to GCML control block offset locations
G.CMLD+2
and
G.CMLD,
respectively.
Together, these two words
constitute the command line descriptors.
These descriptors may be
specified as the "buff" and "len" parameters in the CSI$1 macro call
(see Section 6.2.3.1).
Successful retrieval of a command line causes the C-bit in the
Processor Status Word to be cleared. Any error condition that occurs
during the retrieval of a command line, however, causes the C-bit to
be set.
In addition, a negative error code is returned to offset
location G.ERR of the GCML control block.
These error codes are
described in detail in Section 6.1.2 above.

6-11

COMMAND LINE PROCESSING
Examples of the GCML$ macro call follow:
GCML$

#GCLBLK

GCML$
GCML$

#GCLBLK,#ADPR,#LNPR

The first example specifies the symbolic address of the GCML control
block. The second example assumes that RO contains the address of the
GCML control block.
Both these forms of the GCML$ macro call employ
the default prompt string contained in offset location G.DPRM of the
control block to solicit command line input.
The last example
specifies the address and the length of an alternate prompt string
that you have defined within the program.
This alternate prompt
string is used by GCML to prompt for terminal input, rather than the
default prompt string contained in the GCML control block.

6.1.3.2 RCML$ - Reset Indirect Command File Scan - If you must close
the current indirect command file and return to the top-level file,
that is, to the first (unnested) file, he or she may do so by issuing
the RCML$ macro call.
The RCML$ macro call is specified in the following format:
RCML$

gclblk

gclblk
The address of the GCML control block.
If this parameter is not
specified, RO is assumed to contain the address of the GCML
control block.
When this macro call is issued, the current indirect command file
is
closed,
returning control to the top-level
(unnested)
file.
A
subsequent GCML$ macro call then retrieves the next command line from
~ne
0-level command r11e.
Note, however, that a second MCR/PDS
command at level 0 cannot be read (see GE.EOF error code in offset
location G.ERR of GCML control block, Section 6.1.2).
Examples of the RCML$ macro call follow:
RCML$

#GCLBLK

RCML$

This macro call requires only the address of the GCML control block.

6.1.3.3 CCML$ - Close Current Command File - It is often desirable to
close the current command file between calls for input in order to
free FSR block buffer space for some other use.
The command file is
closed automatically after the retrieval of a command line, provided
that the GE.CLO bit in the status and mode control byte remains
appropriately initialized
(see Section 6.1.2). This bit is set to 1
at assembly time.
If you reset this bit to O,
the current command
file remains open between calls for input.

6-12

COMMAND LINE PROCESSING
For a program that frequently reads command files, this may be a
desirable operational mode, since keeping the file open between. calls
for input reduces total file access time.
However, should it be
desirable to close such a file to free FSR block buffer space, you may
do so by issuing the CCML$ macro call.
The CCML$ macro call takes the following format;
CCML$

gclblk

gclblk
The address of the GCML control block. If this parameter is not
specified, RO is assumed to contain the address of the GCML
control block.
Issuing this statement closes the current command file, effectively
releasing 512(decimal) bytes of FSR block buffer space for some other
use between calls for input. If the command file is already closed
when the CCML$ macro call is issued, control is merely returned to the
calling program. A subsequent GCML$ macro call then causes the
command file to be reopened and the next command line in the file to
be returned to the calling program.
Examples of this macro call are shown below:
CCML$

#GCLBLK

CCML$

As in the RCML$ macro call above, this macro call takes
parameter, namely, the address of the GCML control block.

6.1.4

single

GCML Usage Considerations

As noted in Sectton 6.1.1, the GCMLB$ macro call creates an FDB in the
first part of the GCML control block. Although ordinarily you need
not manipulate this FDB (since it is under GCML and FCS control), you
can perform the following operations on this FDB:
1.

In an irrecoverable error situation, you can issue a CLOSE$
macro call (see Section 3.8)
in connection with this FDB
before issuing the system EXIT$ macro call.

You can test the FD.TTY bit in the device characteristics
byte (offset location F.RCTL) of the FDB to determine if the
command line just obtained was retrieved from a terminal.

In the event that error code GE.IOR or GE.QPR is returned to
control block offset location G.ERR (indicating that an I/O
error has occurred during the retrieval of a command line),
you can test offset location F.ERR of the associated FDB for
more complete error analysis. This cell in the FDB also
contains an error code that may be helpful in determining the
nature of the error condition.

6-13

COMMAND LINE PROCESSING
At task-build time, the Task Builder device assignment (ASG) directive
should be issued to assign the appropriate physical device unit to the
desired logical unit number.
For example, to assign the logical unit
number (lun parameter) in the GCMLB$ macro call (see Section 6.1.1) to
a terminal, the following Task Builder directive should be issued:
ASG = TI:l
The designation TI:
is a pseudo-device name that is redirected to the
command input device. Note that the numeric value following the colon
(:) must agree with the numeric value specified as the lun parameter
in the GCMLB$ macro call.
The ASG directive is described in further detail in the
Reference Manual of the host operating system.

Task

Builder

As discussed in Section 2.6.1 on FSRSZ$, at any given time there must
be an FSR block buffer available for each file currently open for
record I/O operations. You must consider the buffer requirements of
the command file when issuing the FSRSZ$ macro (FSRSZ$ must be issued
with a nonzero first parameter).

6.2

COMMAND STRING INTERPRETER (CS!)

The Command String Interpreter (CSI) analyzes command lines and parses
them into their component device name, directory, and file name
-.L..--~----

;:,1...L .llll::J;:,•

'°"-··
-'--- .. ,..:1
l.VU ;:,uvuJ.u

L-

ut:::

- ... · - - - -

awa.Lt:::

.a...L-.a...

1..ua1..

n~T

\....:>J.

---------

J::l.LU\...t:::o:>o:>t:::o:>

------~

\...U11m1a11u

,,: ___

J...1.11co::>

,:_

..1.11

.a...\...-

\..uc

following formats only:
•

dev:[g,m]outputfilespecification/switch
More than one such file specification
separating them with commas.

•

can

specified

dev:[g,m]outputfilespecification/switch, ••• = dev:[g,m]
inputfilespecification/switch, •••

A file specification is either of the following:
f ilename.type;version
or
"ANSI name string";version
In addition,
block
(see
The run-time
calling user

CSI maintains a dataset descriptor within the CS! control
next section) which may be used by FCS in opening files.
routines that analyze and parse command lines for a
program are described in Section 6.2.3.

Using CSI requires that the CS! control block offsets and bit values
be defined and that a control block be allocated within the program.
The macro described
in the following section accomplishes these
requisite actions.

6-14

COMMAND LINE PROCESSING
6.2.1

CSI$ - Define CS! Control Block Offsets and Bit Values

The only initialization coding required for CSI at
that shown below:
CSI$
• EVEN
CSIBLK: .BLKB

C.SIZE

assembly

time

;DEFINES CSI CONTROL BLOCK OFFSETS
;AND BIT VALUES LOCALLY.
;WORD ALIGNS CSI CONTROL BLOCK •
;NAMES CSI CONTROL BLOCK AND
;ALLOCATES REQUIRED STORAGE.

The CSI$ macro is strictly definitional in nature and does not
generate any executable code. The CSI control block resulting from
the .BLKB directive serves as a means of communication between CSI and
the calling program. The length of the control block is specified by
the symbol C.SIZE, which is defined during the expansion of the CSI$
macro.
Expanding this macro also results in the local definition of
the symbolic offsets and bit values within the CSI control block.
If desired, you can cause the control block offsets to be defined
globally within the current module. This is done by specifying DEF$G
as an argument in the CSI$ initialization macro call, as shown below:
CSI$

6.2.2

DEF$G

CS! Control Block Offset and Bit Value Definitions

The CSI$ macro call causes the following symbolic offsets
values within the CSI control block to be defined locally:
Off set
Name
C.TYPR

and

bit

Functional Significance
Command String Request Type.
This byte field
indicates
the
type of file specifier being
requested.
Depending on whether an input or
output file specifier is being requested (see the
io parameter in the CSI$2 macro call, Section
6.2.3.2), the corresponding bit in this byte is
set. The bit definitions for this byte are as
follows:
CS.INP - Indicates that an input file specifier
is being requested
CS.OUT - Indicates
that
an
specifier is being requested

C.STAT

output

file

Command String Request Status.
This byte field
reflects the status of the current command line
request. The bits in this field are initialized
in accordance with the bit definitions listed
below:
CS.EQU - Indicates that an equal sign (=} has
been detected in the current command line,
signifying that the command line contains both
output and input file specifiers. Once set,
the value of CS.EQU is
preserved
during
processing by both CSil and CSI2.

6-15

COMMAND LINE PROCESSING
Offset
Name

Functional Significance
CS.NMF - Indicates that
the
current
file
specifier
contains
a
file
name string.
Accordingly, control block offset locations
C.FILD+2 and C.FILD (see below) are initialized
with the address and the length
(in bytes),
respectively,
of the command line segment
containing the file name string.
If no file
name string is present, this bit is not set,
and the file name string descriptors in the
control block are cleared.
CS.DIF - Indicates that
the
current
file
specifier contains a directory string.
Thus,
control block offset locations C.DIRD+2 and
C.DIRD
(see below)
are initialized with the
address
and
the
length
(in
bytes),
respectively,
of the command line segment
containing the directory
string.
If
no
directory string is present, this bit is not
set.
In this case, any residual nonzero values
in the directory string descriptor cells that
pertain to a previous command string request of
similar type
(see C.TYPR above) are used. by
default.
Thus,
the last directory
string
encountered in a file specifier is used.
CS.DVF - Indicates that
the
current
file
specifier
contains
a device name stringe
Similarly, control block
offset
locations
C.DEVD+2 and C.DEVD (see below) are initialized
with the address and the length
(in bytes),
respectively~ of the device name string.
If no
device name string is present, this bit is not
set.
Again, similar to CS.DIF above, any
residual nonzero values in the device name
descriptor cells that pertain to a previous
command string request of similar type are used
by default.
Thus, the last device name string
encountered in a file specifier is used.
CS.WLD - Indicates that
the
current
file
specifier contains an asterisk (*), signalling
the presence of a wildcard specification.
CS.MOR - Indicates that
the
current
file
specifier is terminated by a comma (,). The
comma indicates that more file specifiers are
to
follow.
If this bit is not set,
it
signifies that the end of the input or output
file specifiers has been reached.

6-16

COMMAND LINE PROCESSING

Off set
Name
C.CMLD

Functional Significance
Command Line Descriptor.
This 2-word field is
initialized with the address and the length (in
bytes), respectively, of the compressed command
line.
In other words, ~ne values returned to
these cells constitute the output of CSI after
scanning
a
file specifier and removing all
nonsignif icant characters from the string (that
is, nulls, blanks, tabs, and RUBOUTs).
The values contained in these cells are used by
CSI as the descriptors of the compressed command
line to be parsed (see CSI$2 macro call in Section
6.2.3.2).

C.DSDS

Dataset Descriptor Pointer. This offset defines
the address of the 6-word dataset descriptor in
the CSI control block.
This
structure
is
functionally identical to the manually created
dataset descriptor detailed in Section 2.4.1.
You can use this symbol to initialize offset
location F.DSPT in the FDB associated with the
file to be processed.
Thus, FCS is able to
retrieve requisite ASCII information from this
structure for use in opening files.
-Assembly-time initialization of F.DSPT in the
associated FOB may be accomplished as follows:
FDOP$A

l,CSIBLK+C.DSDS

where CSIBLK is the address of the CSI control
block, and C.DSDS represents the beginning address
of the descriptor strings in the CSI control block
(see C.DEVD, C.DIRD, and C.FILD below) identifying
the requisite ASCII file name information.
Run-time
initialization
of
F.DSPT
in
the
associated FDB may also be accomplished through
the dspt parameter of the FDOP$R macro call (see
Section 2.2.2) or the generalized OPEN$x macro
call (see Section 3.1).
C.DEVD

Device Name String Descriptor. This 2-word field
contains the address (C.DEVD+2) and the length in
bytes (C.DEVD) of the most recent device name
string (of like request type) encountered in a
file specifier. Note that the colon that follows
the device name is not included in the device name
string.

C.DIRD

Directory String Descriptor.
This 2-word field
contains the address (C.DIRD+2) and the length in
bytes (C.DIRD) of the most recent directory string
{of like request type)
encountered in a file
specifier.

6-17

COMMAND LINE PROCESSING
Off set
Name
C.FILD

Functional Significance
File Name String Descriptor.
This 2-word field
contains the address (C.FILD+2) and the length in
bytes (C.FILD) of the file name string in the
current file specifier.
If an error condition is detected by the command
syntax analyzer during the syntactical analysis of
a command line (see Section 6.2.3.1 below) , a
segment descriptor is returned to this field,
defining the address and the length of the command
line segment in error.

C.SWAD

Current Switch Table Address. This word location
contains the address of the switch descriptor
table specified in the current CSI$2 macro call
(see Section 6.2.3.2).

C.MKWl

CSI Mask Word 1.
This word
indicates
the
particular switch(es) present in the current file
specifier after each invocation of the CSI$2 macro
call.
The switch mask for each of the defined
switches encountered in a file specifier between
delimiting commas is inserted into this location
by a logical OR operation into this location.
The mask tor a switch is specitied in the csr$sw
macro call (see Section 6.2.4.1). When a switch
is encountered in a file specifier for which a
defined mask exists, the corresponding bits in
C.MKWl are set.
By testing C.MKWl, you can
determine the particular combination of defined
switches present in the current file specifier.

C.MKW2

CSI Mask Word 2. This word provides you
indication of switch polarity.

with

When a switch is present in a file specifer and
that switch is not negated, the defined mask for
that switch is inserted into C.MKW2 by a logical
OR operation in the same manner as described above
for C.MKWl. Conversely, when a switch is present
in a file specifer and that switch is negated, the
corresponding bits in C.MKW2 are cleared.
Thus,
for each switch indicated as being present by
C.MKWl, you can check the polarity of that switch
by examining the corresponding bits in C.MKW2.
C.SIZE

Control Block Size Indicator. This symbol, which
is defined during the expansion of the CSI$ macro,
represents the size in bytes of the CSI control
block.

6-18

COMMAND LINE PROCESSING
6.2.3

CS! Run-Time Macro Calls

Two run-time macro calls are provided in CSI to invoke
perform the following functions:

routines

that

CSI$1

- Initializes the CSI control block, analyzes the command
line (normally contained in the GCML command line input
buffer), removes nonsignif icant characters from the
line, and checks it for syntactic validity. This macro
call also results in the initialization of certain cells
in the CSI control block with the address and the
length, respectively, of the validated and compressed
command line.

CSI$2

- Parses a file specifier in the validated and

compressed
command line into its component device name, directory,
and file name strings, and processes any associated
switches and accompanying switch values. Also, certain
cells in the CSI control block are initialized with the
appropriate string descriptors for subsequent use by FCS
in opening the specified file.

6.2.3.1 CSI$1 - Command Syntax Analyzer - The
CSI$1
macro
call
results in the invocation of a routine called the command syntax
analyzer. This routine analyzes a command line (which is normally
read into the GCML command line input buffer) and checks it for
syntactic validity. In addition, it compresses the file specifiers in
the command line by removing all nonsignificant characters (that is,
nulls: RUBOUTs, and unquoted tabs and blanks). Finally, the command
syntax analyzer initializes offset locations C.CMLD+2 and C.CMLD in
the CSI control block (see Section 6.2.2) with the address and the
length (in bytes), respectively, of the validated and compressed
command line. Each file specifier in the command line is then parsed
into its component device name, directory, and file name strings
during successive issuances of the CSI$2 macro call (see next
section).
The CSI$1 macro call is issued in the following format:
CSI$1

csiblk,buff ,len

csiblk
The address of the CSI control block. If this parameter is not
specified, RO is assumed to contain the address of the CSI
control block.
buff
The address of a command line input buffer.
This parameter
initializes CSI control block offset location C.CMLD+2, enabling
CSI to retrieve the current command line from a command line
input buffer.
If this parameter is not specified, you must manually initialize
CSI control block offset location C.CMLD+2 with the address of a
command line input buffer before issuing the CSI$1 macro call.
This may be accomplished through a statement similar to the
following:
MOV GCLBLK+G.CMLD+2,CSIBLK+C.CMLD+2

6-19

COMMAND LINE PROCESSING
len
The length of the command line input buffer.
parameter initializes CS! control block offset
thus completing the 2-word descriptor that
retrieve the current command line from the input

Similarly, this
location C.CMLD,
enables CS! to
buffer.

As with the buff parameter above,
if this parameter is not
specified, you must manually initialize CSI control block offset
location C.CMLD with the length of the command line, input buffer
before issuing the CSI$1 macro call. This may be accomplished as
follows:
MOV GCLBLK+G.CMLD,CSIBLK+C.CMLD
The combination of the buff and len parameters above enables CS! to
analyze the current command line.
Following the analysis of the
command line, CS! updates offset location C.CMLD with the length of
the validated and compressed command line.
If a syntactical error is detected during the validation of the
command line, the C-bit in the Processor Status Word is set, and
offset locations C.FILD+2 and C.FILD in the CS! control block
(see
Section 6.2.2)
are set to values that define the address and the
length, respectively, of the command line segment in error.
Examples of the CSI$1 macro call follow:
CSI$1

#CSIBLK,#BUFF,#LEN

CSI$1

RO,GCLBLK+G.CMLD+2,GCLBLK+G.CMLD

CSI$1

#CSIBLK

The first example shows symbols that represent the address and the
length of a command line to be analyzed (not necessarily the line
contained in the GCML command line input buffer).
The second example assumes that RO has been preset with the address of
the CS! control block; the next two parameters are direct references
to the command line descriptor words in the GCML control block.
The third example assumes that the required descriptor values are
already present in offset locations C.CMLD+2 and C.CMLD of the control
block (CSIBLK) as the result of prior action.

6.2.3.2 CSI$2 - Command Semantic Parser - The
CSI$2
macro
call
results in the invocation of the command semantic parser. This
routine uses the values in CS! control block offset locations C.CMLD+2
and C.CMLD as the address and the length, respectively, of the command
line to be parsed. The referenced line is then parsed into its
component device name, directory, and file name strings. The equal
sign (=) in the command line indicates that the following string is an
input file specification.
In addition, 2-word descriptors for these
strings are stored in a 6-word dataset descriptor in the CS! control
block, beginning at offset location C.DSDS (see Section 6.2.2). This
field is functionally equivalent to the dataset descriptor created
manually in your program (see Section 2.4.1).

6-20

COMMAND LINE PROCESSING
The command semantic parser also decodes any switches and associated
switch values present in a file specifier.
If yo,u expect to encounter
switches in the current file specifier, the command semantic parser
decodes them, provided that the address of the appropriate switch
descriptor table h~s been specified in the CSI$2 macro call
(see
below). The CS! switch definition macro calls are described in detail
in Section 6.2.4.
The CSI$2 macro call is specified in the following format:
CSI$2

csiblk,io,swtab

csiblk
The address of the CS! control block.
If this parameter is nob
specified, RO is assumed to contain the address of the CS!
control block.
io
A symbol that explicitly identifies the type of file specifier to
be parsed. Either of two symbolic arguments may be specified in
this parameter field, as follows:
INPUT - Indicates that the next input file
command line is to be parsed

specifier

the

OUTPUT - Indicates that the next output file specifier in
command line is to be parsed

the

Offset location C.TYPR in the CS! control block
(see Section
6.2.2)
must be initialized, either manually or through the CSI$2
macro call, with the type of file specifier being requestede
If
arguments other than the symbolic arguments defined above are
specified in the CSI$2 macro call, an .ERROR directive is
generated during assembly that causes the error message INCORRECT
REQUEST TO .CSI2 to be printed in the assembly listing.
This
diagnostic message alerts you to the presence of an invalid io
parameter in the CSI$2 macro call.
swtab
The address of the associated switch descriptor table for this
particular issuance of the CSI$2 macro call. This optional
parameter need be specified only when you anticipate the presence
of a switch in the file specifier that is to be decoded.
Specifying this parameter presumes that you previously created a
corresponding switch descriptor table in the program through the
CSI$SW macro call (see Section 6.2.4.1).
In addition,
if the
switch to be decoded has any associated switch values, you must
also have created an associated switch value descriptor table in
the program through the CSI$SV macro call (see Section 6.2.4.2).
This parameter initializes offset location
control block
(see Section 6.2.2);
if
residual nonzero value in this cell is used
address of the switch descriptor table.

6-21

C.SWAD in the
not specified,
by default as

CS!
any
the

COMMAND LINE PROCESSING
You can also initialize offset location C.SWAD manually prior to
issuing
the CSI$2 macro call, as shown in the following
statement:
MOV #SWTAB,CSIBLK+C.SWAD
where SWTAB is the symbolic
descriptor table.

address

the

associated

switch

The switch table must be aligned on an even address.
If an error condition occurs during the parsing of the file specifier,
the C-bit in the Processor Status Word is set, and control is returned
to the calling program.
The possible error conditions that may occur
during command line parsing include the following:
•

The request type was invalid;
that is, offset location C.TYPR
in the CSI control block (see Section 6.2.2) was incorrectly
initialized.

•

A switch was present in a file specifier, but the address of
the switch descriptor table was not specified in the CSI$2
macro call, or the switch descriptor table did not contain a
corresponding entry for the switch.

•

An invalid switch value was present in the file specifier.

•

More values accompanied a given switch in the file specifier
than there were corresponding entries in the switch value
descriptor table for decoding those values.

•

A negative switch was present in the file specifier, but the
corresponding entry in the switch descriptor table did not
allow the switch to be negated (see the nflag parameter of the
CSI$SW macro call in the next section) •

Examples of the CSI$2 macro call are shown below:
CSI$2

#CSIBLK,INPUT,#SWTBL

CSI$2

RO,OUTPUT,#SWTBL

CSI$2

#CSIBLK,INPUT

The first example shows a request to parse an input file specifier,
which may include an associated switch.
The second example, which
assumes that RO presently contains the address of the CSI control
block, parses an output file specifier that also may include a switch.
The last example is a request to parse an input file specifier and to
disallow any accompanying switches.

6.2.4

CS! Switch Definition Macro Calls

You must issue the following macro calls at assembly time to create
the requisite switch descriptor tables in the program for processing
switches that appear in a file specifier:
CSI$SW - Creates an entry in the switch descriptor table for a
particular switch that you expect to encounter in a file
specifier
CSI$SV - Creates a matching entry in the switch value descriptor
table for the switch defined through the CSI$SW macro
call above
6-22

COMMAND LINE PROCESSING
CSI$ND - Terminates a switch descriptor table or a switch value
descriptor table created through the CSI$SW or the
CSI$SV macro call, respectively
These macro calls are described separately in the following sections.

6.2.4.1 CSI$SW - Create Switch Descriptor Table Entry - To
process
each switch that you expect to encounter
in a file specifier, a
matching entry in the switch descriptor table must be defined.
If no
switch descriptor table is specified, the presence of any switch in
the command line causes an error to occur.
When the address of a
switch descriptor table is specified in any particular issuance of the
CSI$2 macro call
(see Section 6.2.3.2),
the following processing
occurs:
1.

For each switch encountered in a file specifier, CSI searches
the switch descriptor table for a matching entry.
If the
switch descriptor table address
is not specified, or a
matching entry is not found in the table for the switch, that
switch is considered to be invalid.
As a result,
the C-bit
in the Processor Status Word is set, any remaining switches
in the file specifier are bypassed, and control
is returned
to the calling program.

If a matching entry is found in the switch descriptor
table,
mask word 1 in the CSI control block is set according to the
defined mask for that switch (see C.MKWl, Section 6.2.2).

The negation status of the switch is determined.
If the
switch is not negated, the corresponding bits in mask word 2
(C.MKW2) in the CSI control block are set according to
the
defined mask for that switch.
If the switch is negated, and
negation is not allowed, then the switch is considered to be
invalid~
In this case, the error sequence described in step
1 above applies.
However, if the switch is negated,
and
negation is allowed,
then the corresponding bits in C.MKW2
are cleared.
The negation flag for a switch is established through
nflag parameter of the CSI$SW macro call (see below).

the

If the address of the optional user mask word is not present
in the corresponding switch descriptor table entry, that is,
if the mkw parameter has not been specified in the associated
CSI$SW macro call
(see below), switch processing continues
with step 7.
If, however, the address of the optional mask
word is specified, switch processing continues with step 5.

If SET has been specified as the clear/set flag
in the
corresponding switch descriptor table entry, and the switch
is not negated, then the corresponding bits in the optional
mask word nre set according to the defined mask for that
switch.
If,
however,
the
switch
is
negated,
the
corresponding bits in the optional mask word are cleared.
The clear/set flag is specified as the csflg parameter in the
CSI$SW macro call (see below).

If CLEAR has been specified as the clear/set flag
in the
corresponding switch descriptor table entry, and the switch
is not negated, the corresponding bits in the optional mask
word are cleared.
Conversely, if the switch is negated, the
corresponding bits in the optional mask word are set.

6-23

COMMAND LINE PROCESSING
7.

If a switch value accompanies a switch in a file specifier,
the associated switch value descriptor table created through
the CSI$SV macro call (see next section) is used to decode
the value.
There must be at least as many entries in the
switch value descriptor table as there are such values
accompanying the switch in the file specifier. If the switch
value descriptor table is incomplete, if an invalid switch
value is encountered, or if the address of the switch value
descriptor table is not present in the associated switch
descriptor table, then the switch is considered to be
invalid, and the error sequence described in step 1 again
applies.
The address of the switch value descriptor table is specified
as the vtab parameter in the CSI$SW macro call (see below).

The CSI$SW macro call is specified in the following format:
label:

CSI$SW

sw,mk,mkw,csflg,nflg,vtab,compflg

label
An optional symbol that names the resulting switch descriptor
table entry and defines its address. In order to establish the
address of a switch descriptor table, the first CSI$SW macro call
issued in the program must include a label. This label allows
the table to be referenced by other instructions in the program.
SW

The alphabetic switch name to be stored in the switch descriptor
table.
This name may comprise any number of characters. CSI
compares the name entered on the command line with this switch
name, as entered in the switch descriptor table. The method CS!
uses to compare their names is described below.
This parameter
is required. If omitted, an .ERROR directive is generated during
assembly that causes the error message MISSING SWITCH NAME to be
printed in the assembly listing.
mk
A user-defined mask for the switch specified through the sw
parameter above.
To enable CSI to indicate the presence of a
given switch in a file specifie~, a mask value for the switch
must be defined, as shown below:
ASM SK = 1
NUMSK
2

VWMSK
XYMSK

40000
100000

where the (octal) value that you assign to each symbol defines a
unique bit configuration that is to be set in CS! mask word 1
(C.MKWl) of the control block when a defined
switch
is
encountered in a file specifier.

6-24

COMMAND LINE PROCESSING
When you specify the appropriate symbol as the mk parameter in
the CSI$SW macro call, the corresponding mask value is stored in
the resulting switch descriptor table entry. Thus, a mechanism
is established through which you can determine the particular
combination of switches present in a file specifier.
For every
matching
entry found in the switch descriptor table, the
corresponding bits are set in C.MKWl.
mkw
The address in your program storage of a mask word that CSI
changes each time it changes C.MKWl. CS! stores the same value
into this mask word that it stores into C.MKWl. This mask word
can be manipulated (that is, changed or tested) by the SET and
CLEAR functions or by instructions in your program. You set the
SET and CLEAR functions using the csflg parameter described
below.
Such an optional 'Word may be reserved
logically equivalent to that shown below:
MASKX:

.WORD

through

statement

csf lg
A symbolic argument that specifies the clear/set flag for a given
switch.
This parameter is optional; if not specified, SET is
assumed (see below). Either one of two symbolic arguments may be
specified for this parameter, as follows:
CLEAR - Indicates that the bits in the optional user mask word
corresponding to the switch mask are to be cleared, provided
that the switch is not negated.
(If the switch is negated,
the bits are set.)
SET - Indicates, conversely, that the bits in the optional
user mask word corresponding to the switch mask are to be set
provided that the switch is not negated.
(If the switch is
negated, the bits are cleared.)
If other than one of the above arguments is specified, an .ERROR
directive is generated during assembly that causes the error
message INVALID SET/CLEAR SPEC to be printed in the assembly
listing.
nf lg
A symbolic argument that specifies an optional negation flag for
the switch.
If this parameter is specified, it indicates that
the switch is allowed to be negated, for example, /-LI or /NOLI.
If this parameter is specified as other than NEG, an .ERROR
directive is generated during assembly that causes the error
message INVALID NEGATE SPEC to be printed in the assembly
listing.
If this parameter is not specified, the default
assumption is that switch negation is not allowed.

6-25

COMMAND LINE PROCESSING
vtab
The address of the switch descriptor table associated with this
switch.
This optional parameter,
if specified, allows CSI to
decode any switch values accompanying the switch, provided that
an associated switch descriptor table entry has been defined for
that switch.
The switch value descriptor table is defined
through the CSI$SV macro call, as described in the next section.
(If the vtab parameter is specified in the CSI$SV macro call,
there is no need to specify it in the CSI$SW macro call.)
compflg
The method CSI uses to compare the switch name entered on the
command line with the value entered in the switch descriptor
table by the sw parameter.
Either LONG or EXACT may be
specified. The default value is entered if a value is not coded.
Default - If the parameter is not coded, only the first two
characters of the switch name (specified by sw) are entered into
the switch descriptor table and only these two characters are
___ ,
compared when the command line is parsed. M.UU.1.1...1.VJJQ.J. -""----"---in the command line switch name are ignored.
l\~...:J.;.a...;

\..JJQJ. Q\.. l..CJ. ;::>

LONG - All characters specified by the sw parameter are entered
in the switch descriptor table. During compare processing, the
first characters of the switch name on the command line must
exactly match the value for the switch in the switch descriptor
table. Additional characters in the command line switch name are
ignored.
EXACT - All characters specified by the sw parameter are entered
in the switch descriptor table. During compare processing, all
the characters of the switch name on the command line must
exactly match the value in the switch descriptor table.
Extra
characters are treated as an error.
The switch table must be aligned on an even address.
The format of the switch descriptor table entry that results from a
call to the CSI$SW macro is shown in Figure 6-2 below.
One such
switch entry must be defined for each switch appearing in the file
specifier that you intend to recognize.
Entries in the switch
descriptor table consist of control information and switch name
characters stored two characters per word.
The switch name characters precede the control information in the
table. The sign bit of each word indicates whether the following word
contains more switch name characters. A sign bit set to 1 indicates
that the next word contains more switch name characters, whereas sign
bit set to 0 indicates the last word containing switch
name
characters.
If the number of characters in the switch name is odd, the high-order
byte of the last word contains zeros and is ignored by CSI.
The sign bit of the first byte of the last word of the switch name is
the EXACT match bit.
If this bit is set to 1, additional characters
in the switch name on the command line are treated as an error by CSI.
Otherwise, they are ignored.

6-26

COMMAND LINE PROCESSING
The switch name characters are followed by entry control information
consisting of the CSI mask word, the address in user program storage
of a mask word corresponding to the CSI mask word, and the address of
the switch value table.
A bit setting of 1 in the low-order bit of the address of your mask
word indicates the CLEAR function;
a bit setting of 0 indicates the
SET function.
The last word of the switch descriptor table entry contains the
address of the switch value table.
A bit setting of 1 in the
low-order bit of this word indicates that the switch may be negated.

15
char2

char1

char4

char3

lastchar

nextlast

Mask Word for this Switch
Address of Optional User Mask Word
Address of Switch Descriptor Table
ZK-296-81

Figure 6-2

Format of Switch Descriptor Table Entry

The following example shows a 2-entry switch descriptor table
through successive CSI$SW macro calls:
ASSWT:

CSI$SW

AS,ASMSK,MASKX,SET,,ASVTBL

CSI$SW

NU,NUMSK,MASKX,CLEAR,NEG,NUVTBL

CSI$ND

created

;END OF SWITCH DESCRIPTOR TABLE.

The first statement results in the creation of an entry in the switch
descriptor table for the switch /AS.
The second parameter is an
equated symbol that defines the switch mask, and the third parameter
(MASKX)
is the address of an optional user mask word (see the mkw
parameter above).
The fourth parameter indicates that the bits in
MASKX that correspond to the switch mask are to be set. The fifth
parameter (the negation flag) is null.
The last parameter is the
address of the associated switch value descriptor table.
The second statement results in the creation of a switch descriptor
table entry for the switch /NU.
In contrast to the first statement,
the fourth parameter (CLEAR) indicates that the bits in the optional
user mask word
(MASKX) that correspond to the switch mask are to be
cleared. The fifth parameter (NEG) allows the switch to be negated,
and the last parameter is the address of the value table associated
with this switch.
Note that the switch descriptor macros are terminated with the
macro call (see Section 6.2.4.3).

6-27

CSI$ND

COMMAND LINE PROCESSING
6.2.4.2 CSI$SV - Create Switch Value Descriptor Table Entry - For every switch value that you expect to encounter in connection with a
given switch in a file specifier, a corresponding switch value
descriptor table entry must be defined in your program in order to
allow the switch value(s) to be decoded. The CSI$SV macro call is
provided for this purpose. When issued, this macro call results in
the creation of a 2-word entry in the switch value descriptor table.
The format of this table is shown in Figure 6-3 below.
The CSI$SV macro call is specified in the following format:
CSI$SV type,adr,len
type
A symbolic argument that specifies the conversion type for the
switch value.
Any one of four symbolic values may be specified
in this parameter field to indicate the conversion type for the
accompanying
switch
value.
The
possible conversion-type
arguments include the following:
ASCII - Indicates that the switch value is to be treated as an
ASCII string.
If the string is quoted, the quotes are
returned in the buffer as part of the string.
If a quote
appears anywhere in the switch value, all characters following
it, up to end-of-line or another quote are included in the
string.
NUMERIC - Indicates that a numeric switch value is to be
converted to binary using octal as a default conversion radix.
OCTAL - Indicates that a numeric switch value is to be
converted to binary using octal as a default conversion radix.
DECIMAL - Indicates that a numeric switch value is to be
converted to binary using decimal as a default conversion
radix.
If any value other than those defined above is specifiedf an
.ERROR directive is generated during assembly that causes the
error message INVALID CONVERSION TYPE to be printed in the
assembly listing. If none of the above parameters is specified,
ASCII is assumed by default.
adr
The address of your program location that is to receive the
resultant switch value at the conclusion of switch processing.
This parameter is required;
if not specified, an
.ERROR
directive is generated during assembly that causes the error
message VALUE ADDRESS MISSING to be printed in the assembly
listing.
len
A numeric value that defines the length (in bytes) of the area
that is to receive the switch value resulting from switch
processing. This parameter is also required; if not specified,
an .ERROR directive is generated during assembly that causes the
error message LENGTH MISSING to be printed in the assembly
listing.

6-28

COMMAND LINE PROCESSING
The format of a switch value descriptor table entry that results
the CSI$SV macro call is shown in Figure 6-3 below.

from

The low-order byte of the first word in the switch value descriptor
table indicates whether the conversion type is ASCII or numeric.
The
low-order byte of this word is set to 1 if ASCII is specified;
it is
set to 2 if NUMERIC or OCTAL is specified, and is set to 3 if DECIMAL
is specified. The high-order byte of this word indicates the maximum
allowable length (in bytes) of the switch value.
If the conversion type is ASCII,
the len parameter reflects the
maximum number of ASCII characters that can be deposited in the area
defined through the adr parameter.
The high-order byte of the first
word in the switch value table then reflects the maximum length of the
ASCII string.
If the number of characters in the switch value exceeds
the specified length, the extra characters are simply ignored.
If,
however, the actual number of ASCII characters present in the switch
value falls short of the specified length, the remaining portion of
the area receiving the resultant value is null padded.
If the conversion type is numeric, the length of the resulting binary
value is either two bytes or four bytes.
If the size field is less
than 4, 2 bytes are stored.
If the size field is greater than 4,
4
bytes are stored. The buffer must be aligned on a word-bounoary.
On numeric conversions, the default conversion type specified for a
switch value can be overridden by means of a pound sign (#) or a dot
(.). A numeric value preceded by a pound sign
(for example,
#10)
forces the conversion type to octal;
a numeric value followed by a
dot (for example, 10.) forces the conversion type to decimal.
Note
also that a numeric switch value may be preceded by a plus sign (+) or
a minus sign (-). The plus sign is the default assumption.
If an
explicit octal switch value is specified using the pound sign (#), as
described above, the arithmetic sign indicator (+ or -) , if included,
must precede the pound sign {for example, -#10).
If the conversion type is decimal, the switch value is evaluated as a
single number;
an overflow into the high-order bit (bit 15) results
in an error condition.
However, if the conversion type is octal, a
full 16-bit value may be specified.
16

0
Switch Value Length

Conversion Type

Address of Location Receiving Switch Result
ZK-297-81

Figure 6-3

Format of Switch Value Descriptor Table Entry

6-29

COMMAND LINE PROCESSING
Representative CSI$SV macro calls are shown below:
ASVTBL: CSI$SV
CSI$SV

ASCII,ASVAL,3
ASCII,ASVAL+4,3

CSI$ND
NUVTBL: CSI$SV
CSI$SV

;END OF SWITCH VALUE TABLE.
OCTAL,NUVAL,2
DECIMAL,NUVAL+2,2

CSI$ND

;END OF SWITCH VALUE TABLE.

In all cases above, the first parameter in the CSI$SV macro call
defines the conversion type. The next two parameters, in all cases,
define the address and the length of your program location that is to
receive the resultant switch value.
The required storage for the first switch value
reserved as follows:
AS VAL

.BLKW

table

.BLKW

may

;ASCII VALUE STORAGE.

The required storage for the second switch value
similarly reserved through the following statement:
NUVAL:

above

table

;NUMERIC VALUE STORAGE.

Note again that switch value tables are
macro call.

terminated

with

the

CSI$ND

6.2.4.3 CSI$ND - Define End of Descriptor Table - Switch
descriptor
tables and switch value descriptor tables must be terminated with a
1-word end-of-table entry.
This word, which contains O, may be
created through the CSI$ND macro call.
This macro caii takes no arguments, as shown below:
CSI$ND
The examples near the end of the preceding section illustrate the
of this macro call.

6-30

use

CHAPTER 7
THE TABLE-DRIVEN PARSER (TPARS)

TPARS is a table-driven parser designed to parse command lines. TPARS
provides the means to define a unique syntax and, using TPARS-supplied
macros, built-in variables, and your own code,
recognize a command
line written in that syntax.
For TPARS, parsing is breaking down a command line into syntax
elements and resolving the form, function, and interrelationship of
these elements.
TPARS parses command
lines
at
two
levels:
syntactical and semantic. At the syntactical level, TPARS evaluates
each syntax element on the command line based on a predefined
arrangement of command line elements. This arrangement of command
line elements is defined by TPARS macros in a state table that
consists of states and transitions.
Also at the syntactical level,
TPARS provides for
resolving complex syntax types by means of
subexpressions.
On the semantic level, TPARS resolves the meaning of
each element based on definitions supplied in action routines. Action
routines make use of TPARS built-in variables and user-supplied code
to fit the needs of a user parsing routine.
TPARS parses command lines using a user-defined table. You can build
a state table using the TPARS STATE$ and TRAN$ macros. A state
delimits and represents a single syntax element on a command line.
A
transition is a statement that defines the processing required for
parsing a given syntax element and provides direction for further
parsing at another state.
The user-written parser routine is included in user programs that
parse command lines.
TPARS is invoked from within an executing
program by means of a CALL instruction.
The CALL invokes the
user-defined parser routine as well as the TPARS processor itself.
For further information on the interrelationships between the calling
program, the user-defined parser routine, and the TPARS processor,
refer to Section 7.5.

7.1

CODING TPARS SOURCE PROGRAMS

This section describes the three TPARS macros required to
initialize
and define the state table.
Also
included in this section is
information describing action routines, TPARS built-in variables, and
TPARS subexpressions.

7-1

THE TABLE-DRIVEN PARSER (TPARS)
7.1.1

TPARS Macros: !STAT$, STATE$, and TRAN$

TPARS provides macros that allow you to write a state table for
parsing a unique command line syntax.
The ISTAT$ macro initializes a
state table, the STATE$ macro defines a state in your state table, and
the TRAN$ macro defines the conditions for transition to another
state.

7.1.1.1 Initializing the State Table: the !STAT$ Macro - The
ISTAT$
macro initializes the state table.
The state table is built using two
macros, STATE$ and TRAN$, which are described below.
This state table
is built into a program section.
User-defined keyword strings, for
use in parsing command lines, are also accumulated in a program
section.
A program section is also provided for a keyword pointer
table to index into the list of keyword strings.
The ISTAT$ macro
initializes these program sections.
The format for coding the ISTAT$
macro is:
ISTAT$ statetable,keytable,$DEBUG
statetable
The label that you assign to the state table.
label to the start of the state table.

TPARS equates this

keytable
The label that you assign to the keyword table.
this label to the start of the keyword table.

TPARS

equates

$DEBUG
Directs the assembler to list addresses of the state transition
table in the assembly listing.
These addresses are useful for
tracing TPARS operation using a user-supplied debug routine
{see
Section 7.1.3.4). When $DEBUG is not included, state transition
table addresses are not listed.
The state table is built in a program section named $STATE;
keyword strings are accumulated in a program section named $KSTR;
keyword pointer table is built in a program section named $KTAB.

the
the

If you define the symbol $RONLY, each of these program sections is
generated as read-only.
You generate a
read-only state table by
specifying the symbol $RONLY preceding the ISTAT$ macro in the form:
$RONLY = 1
ISTAT$ statetable,keytable,$DEBUG

7-2

THE TABLE-DRIVEN PARSER (TPARS}
7.1.1.2 Defining a Syntax Element: the STATE$ Macro - The
STATE$
macro declares the beginning of a state. Syntactically, this macro
delimits one command line element from anothero The STATE$ macro is
coded in the following form:
STATE$ [label]
label
An alphanumeric symbol that is equated
state.

the

address

the

Each state is comprised of any number of transitions, which define the
conditions under which control can be passed to another state.

7.1.1.3 Defining a Transition: the $TRAN Macro - The
provides:

TRAN$

•

The means for matching a given type of syntax element

•

Direction to the next state to be processed

•

The address of the
syntax element

•

A maskword and maskword address

action

routine

process

the

macro

current

The TRAN$ macro is coded in the following form:
TRAN$ type [,label] [,action] [,mask] [ ,maskaddr]
[,$EXIT]

type
The syntactical type of the command line element being parsed.
The type parameter is coded using one of the types of command
line elements described in the Section, "Types of Command Line
Syntax Elements," below.
[label]
[$EXIT]
The label associated with the state to which control is directed
after the code for this transition is executed.
If label is
omitted, control drops through to the next sequential STATE$
macro.
A null label parameter is allowed only for the last
transition in a state; the statement following a TRAN$ macro
with a null label field must be a STATE$ macro.

$EXIT specified in the label field terminates TPARS execution and
returns control to the calling program.
$EXIT is also used to
terminate a TPARS subexpression.
action
The label of an action routine the user includes in the parser
routine.
This routine can include TPARS built-in variables,
described in Section 7.1.3 below.

7-3

THE TABLE-DRIVEN PARSER (TPARS)
mask
A maskword to be stored into a maskword address whenever the
transition is executed.
If mask is specified, maskaddr, below,
must be specified.
This maskword is ORed
into
maskaddr
(described below) when the transition is taken (after the action
routine is called).
maskaddr
The label for an address into which TPARS stores the value
specified by the mask parameter.
The maskaddr parameter must be
specified if mask is specified.
The mask and maskaddr parameters provide a convenient
flagging the execution of a particular transition.

7.1.2

means

for

Types of Command Line Syntax Elements

The type parameter of the TRAN$ macro requires the entry of one of the
following types of syntax elements:
$ANY

Matches any single character.

$ALPHA

Matches any single alphabetic character (A-Z}.

$DIGIT

Matches any single digit (0-9}.

$LAMDA

Matches an empty string.
This transition is
always successful.
LAMDA txansitions are useful
for getting action routines called without passing
any of the input string.

$NUMBR

Matches a number. A number consists of a string
of digits, followed optionally by a period.
If
the number is not followed by a period,
it is
interpreted as octal.
Numbers followed by a
period are interpreted as decimal and the decimal
point is included in the matching string. A
number is terminated by any nonnumeric character.
Values through 2**32-1 are converted to 32-bit
unsigned integers.

$DNUMB

Matches a decimal number.
The string of digits is
interpreted as decimal. With the exception that
the matched string does not include the trailing
decimal point, TPARS treats $DNUMB the same way it
treats $NUMBR.

$STRNG

Matches
any
alphanumeric
character
(0-9,A-Z). The string will not be null.

$RADSO

Matches any legal RADIX-SO string, that is, any
string containing alphanumeric characters and/or
the period (.) and dollar sign
($}
characters.
Conversion
to
RADIX-SO
format
is
the
responsibility of the action routine.

7-4

string

THE TABLE-DRIVEN PARSER (TPARS)

7.1.3

$BLANK

Matches a string of blank and/or tab characters.

$EOS

Matches the end of the input string.
Once TPARS
has reached the end of the input string, $EOS
matches as many times as it is encountered in the
state table.

char

Matches a single character whose ASCII
code
corresponds to the value of the expression char.
The value of the expression must be a 7-bit ASCII
code;
that is, the value must be in the range
0-177 (octal). Constructions such as 'X are valid
and, in fact, recommended.

"keyword"

Matches a specified keyword. Keywords may be any
length, may contain only alphanumeric characters,
and are terminated by the first nonalphanumeric
character encountered.
The maximum number of
keywords allowed in a state table is 64.

!label

Matches the string processed by executing the
state table section that starts with the state
specified as label. This syntax type is used to
pass control to a subexpression. For information
on TPARS subexpressions, refer to Section 7.1.4.

Action Routines and Built-in Variables

Action routines provide the means for processing command line elements
at the semantic level. That is, a given syntax element can have more
than one meaning. Action routines provide a mechanism for determining
and validating the meaning of the syntax elements.
Write action routines to perform functions
requirements of your parsing program.

7.1.3.1 TPARS Built-in Variables - TPARS
provides
built-in variables for use in action routines:

the

unique

following

.PSTCN

Returns the character count of the portion of the
input string matched by this transition. This
character count is valid for all syntax types
recognized by TPARS, including subexpressions.

.PSTPT

Returns the address of the portion of the input
string matched by this transition. This address
is valid for all syntactical types recognized by
TPARS, including subexpressions.

.PNUMH

Returns the high-order binary value of the number
returned
by a $NUMBR or $DNUMB syntax type
specification.

.PNUMB

Returns the low-order binary value of the number
returned
by a $NUMBR or $DNUMB syntax type
specification.

7-5

THE TABLE-DRIVEN PARSER (TPARS)
.PCHAR

Returns the character found by the $ANY, $ALPHA,
$DIGIT, or char syntax type specifications.

.PFLAG

Returns the value of the flag word passed to TPARS
by register 1 {Rl). Action routines can modify
this word to change options dynamically.

.TPDEB

Contains the entry address of
{user-supplied) debug routine.

Returns the byte count bf the remainder of the
input string. When the action routine is called,
the string does not include the characters matched
by the current transition.

Returns the address of the remainder of the input
string.
When the action routine is called, the
string does not include the characters matched by
the current transition.

the

optional

7.1.3.2 Calling Action Routines - Action routines are called by a JSR
PC instruction. Action routines may modify registers RO, Rl, and R2;
all other registers must be preserved.

7.1.3.3 Using Action Routines to Reject a Transition - Acc1on routines can reject a transition by returning to CALL+4 rather than to
CALL+2. That is, the action routine performs the same function as an
ADD #2,(SP)
before returning to the caller. This technique allows
additional processing of syntax types and extending the syntax types
beyond the set provided by TPARS.
When an action routine rejects a transition, that transition has no
effect. TPARS continues to attempt to match the remaining transitions
in the state.

7.1.3.4 Optional Debug Routine for RSX-11 Users - A
user-supplied
debug routine can be called by TPARS at each state transition allowing
TPARS operation to be traced. For example, the routine can be written
to display the contents of RS each time the routine is called; RS
contains the current transition table address.
By comparing the
addresses displayed with the TPARS assembly listing showing the state
transition table addresses, TPARS operation can be monitored.
If a user-supplied debug routine is to be called by TPARS, the user
task must first specify the entry point address for the debug routine
in TPARS location .TPDEB, as follows:
MOV

#DENTER,.TPDEB

Then, invoke TPARS with the .TPARD entry point (rather
.TPARS). TPARS is invoked as described in Section 7.4.

7-6

than

with

THE TABLE-DRIVEN PARSER (TPARS)
Upon entry to the debug program, CPU registers contain the following:
R3

Length of remainder of input string

Address of remainder of input string

Current address of transition table

The debug routine must
returning to TPARS.

save

and

restore

all

registers

prior

In order for addresses displayed by the debug routine to be useful, it
is necessary to obtain an assembly listing showing the addresses of
the state transition tables.
These addresses are listed by the
assembler ir the optional $DEBUG parameter is provided in the !STAT$
macro call (see Section 7.1.1.1).

7.1.4

TPARS Subexpressions

A TPARS subexpression is a series of states and transitions analogous
to a subroutine. In general, such a series of states and transitions
is used more than once during the parsing process.
Subexpressions begin with a STATE$ macro specifying the label of the
subexpression.
This macro is followed by the states and transitions
that comprise the body of the subexpression.
To terminate the
subexpression, specify a TRAN$ macro with the $EXIT keyword specified
in the label field. The general form of a subexpression is shown in
the example below.
In this example, control is directed to the subexpression by a TRAN$
macro that specifies a !label syntax element as the type parameter:
TRAN$ !UIC 1 NEXT
TPARS then directs control to the STATE$ macro with the label UIC:
STATE$
TRAN$ I [

UIC

STATE$
TRAN$ $NUMBR,,SETGN
STATE$
TRAN$ ',>
STATE$
TRAN$ $NUMBR,,SETPN
STATE$
TRAN$ '],$EXIT
When the UIC subexpression completes processing, control passes to the
state labeled NEXT.

7-7

THE TABLE-DRIVEN PARSER (TPARS)
7.2

GENERAL CODING CONSIDERATIONS

This section contains information on how to arrange syntax types in a
state table and how to direct TPARS to ignore blanks and table
characters in a command line, and rules for entering
special
characters (commas and angle brackets).

7.2.1

Suggested Arrangement of Syntax Types in a State Table

The transitions in a state may represent several syntax types;
a
portion of a string being scanned often matches more than one syntax
type. Therefore, the order in which the types are entered in the
state table is critical. Transitions are always scanned in the order
in which they are entered, and the first transition matching a string
being scanned is the transition taken. Therefore, the following order
is recommended for states containing more than one syntax type:
char
keyword
$EOS
$ALPHA
$DIGIT
$BLANK
$NUMBR
$DNUMB
$STRNG
$RAD50
$ANY
$LAMDA
Placement of !label transitions in a state depends on the types and
positions of other syntax types in the state as well as on the syntax
types in the starting state of the subexpression,

7.2.2

Ignoring Blanks and Tabs in a Command Line

Bit zero of the low byte of Register l
(Rl) controls processing of
blanks and tab characters. If this bit is 1 when TPARS is invoked,
blanks and tab characters are processed in the same way any other
ASCII character is processed;
they are treated as syntax elements
that require validation by TPARS. If this bit is set to O, blanks and
tab characters are interpreted as terminator characters; they are
ignored as syntax elements. In neither case does TPARS modify the
command line.
When blanks are being ignored, the $BLANK syntax type never matches an
element on the command line. Also, when this option is in effect,
values returned to the !label syntax type by .PSTCN or .PSTPT may
contain blanks or tabs, even though none were requested. The examples
below show how TPARS parses the string:
ABC DEF
with and without the blank-suppress option.

7-8

THE TABLE-DRIVEN PARSER (TPARS)
In the first example, an extra state is required to parse the blank:
STATE$
TRAN$

$STRNG

STATE$
TRAN$

$BLANK

STATE$
TRAN$

$STRNG

When TPARS is directed to ignore blanks and tab characters,
string can be parsed using only two states:

7.2.3

STATE$
TRAN$

$STRNG

STATE$
TRAN$

$STRNG

the

same

Entering Special Characters

In ticharti syntax elements, MACR0-11 interprets commas (,), semicolons
(;), and angle brackets (< >) as special characters. The comma is
interpreted as an argument separator and angle brackets are used to
parenthesize special characters.
To include a comma or a semicolon in a "char" syntax
use angle brackets:

element

string,

TRAN$ <' ,>
Angle brackets cannot be passed as string elements in macro arguments.
If
required
in
a "char" expression, they must be expressed
symbolically, for example:
LA = '<
TRAN$ LA

7.2.4

Recognition of Keywords

When TPARS encounters a transition table entry that specifies a
keyword, it first scans from the current point in the input string in
search of a delimiter (nonalphanumeric) character.
The characters
between the current input point and the next delimiter are then
assumed to be a possible keyword and are matched against the entries
in the keyword table. For this reason, the following example will not
work as expected:
STATE$
TRAN$
TRAN$
STATE$
TRAN$
TRAN$

"NO",STATEl,SETNEG
$LAMDA,,SETPOS
STATE!
11

AA" I • • •

"BB", •••

7-9

THE TABLE-DRIVEN PARSER (TPARS)
When TPARS encounters the keyword NO, it will scan and attempt to
match the string "NOAA" or "NOBB".
If exact matching is requested,
neither the "NO" transition nor the "AA" transition will match.
In
addition,
if keyword matching is limited to two characters, the "NO"
transition will match but TPARS will skip past "NOAA" so that the "AA"
transition can be taken. You can use the following example to achieve
the desired operation:
STATE$
TRAN$
TRAN$
STATE$
TRAN$
TRAN$

!NONO,STATEl,SETNEG
$LAMDA,,SETPOS
STATE

"AA", •••
"BB", •••

STATE$
TRAN$

NONO
'N

STATE$
TRAN$

'O,$EXIT

In this example, TPARS attempts to match the subexpression NONO to the
"NO" prefix one character at a time.
This bypasses the keyword
scanning of TPARS, allowing the input pointer to be left pointing at
"AA" or "BB".
If NONO fails, the input pointer will not be changed
and the scan can continue by looking for "AA" or "BB".

7.3

PSECTS GENERATED BY TPARS MACROS

TPARS macros generate three PSECTs. Data associated with the STATE$
macro is stored in the PSECT $STATE, whereas data associated with the
TRAN$ macro is stored in PSECTs $KSTR and $KTAB.
$KTAB contains
addresses for each of the entries of the keyword syntax type.
$KSTR
contains the keyword entries separated by character code 377 (octal).
Each state consists of its transition entries concatenated in the
order in which they are specified. The state label, if specified, is
equated to the address of the first transition in the state.
Each
transition consists of from one to six words, as follows:

Flags

Type

Type Extension
Action Return Address
Maskword
Maskword Address
Target State Label
ZK-314-81

7-10

THE TABLE-DRIVEN PARSER (TPARS)
The type byte of the first word may contain the following values:
$LAMDA
$NUMBR
$STRNG
$BLANK
$SUBXP
$EOS
$DNUMB
$RAD50
$ANY
$ALPHA
$DIGIT
char
keyword

300
302
304
306
Used in the !label type.
310
312
314
316
320
322
324
ASCII code for the specified character
200+n (See explanation below.)

The value of keyword is 200+n, where n is an index into the keyword
t~ble.
The keyword table is an array of pointers to keyword strings,
w~ich are stored in the PSECT $KSTR.
Keyword strings in $KSTR are
separated from each other by 377 (octal).
Bits in the flags byte indicate whether parameters for the TRAN$ macro
are specified:

7o4

Bit

Meaning

O
1
2
3
4
7

Type extension is specified.
Action routine label is specified.
Target state label is specified.
Maskword is specified.
Maskword address is specified.
Indicates last transition in the current state.

INVOKING TPARS

You control execution of TPARS using the calling conventions and
options described in this section. TPARS is invoked from within an
executing program on an IAS or RSX-llM system by means of the
instruction
CALL

.TPARS

When a user-supplied debug routine is used for tracing a TPARS
operation (see Section 7.1.3.4), a special entry point is called, as
follows:
CALL

.TPARD

When TPARS is called in this manner, TPARS calls the debug routine at
each state transition.
If TPARS is invoked by means of the .TPARS
entry point, the debug routine entry point address in .TPDEB is
cleared and the debug routine is not called.

7-11

THE TABLE-DRIVEN PARSER (TPARS}
7.4.1

When TPARS is invoked, registers in the calling program
the following information:
Rl
R2
R3
R4
RS

Th~

contain

Options word
Pointer to the keyword table
Length of the string to be parsed
Address of the string to be parsed
Label of the starting state in the state table

On return from
information:
R3
R4

must

TPARS

processing,

registers

contain

the

following

Length of the unscanned portion of the string
Address of the unscanned portion of the string

values of all other registers are preserved.

The carry bit in the Processor Status Word returns O for a successful
parse; the carry bit is set when TPARS finds a syntax error.
For an example of a calling
7.6.1.

7.4.2

sequence

for

TPARS,

refer

Section

Using the Options Word

The low byte of the options word contains flag bits.
The only flag
bit defined is bit zero, which controls processing of blanks.
If bit
zero is set to 1, blanks are interpreted as syntax elements.
If bit
zero is set to O, blanks are ignored as syntax elements.
The high byte of the options word controls abbreviation of keywords.
If the high byte is set to O, keywords being parsed must exactly matcn
their corresponding entries in the state table.
If the high byte is
set to a number, keywords being parsed may be abbreviated to that
number of characters. Keywords in the string that are longer than the
number specified must be spelled correctly up to the length specified
by the number.
TPARS clears the carry bit in the Processor Status Word when it
completes processing successfully. This occurs when a transition is
made to $EXIT that is not within a subexpression.
If a syntax error occurs, TPARS sets the carry bit
Status Word and terminates.

the

Processor

A syntax error occurs when there are no syntax elements in the current
state that match the portion of the string being scanned.
Illegal
type codes and errors in the state table can also cause a syntax
error.
TPARS processing requires that the addresses in the state table and
the keyword tables be reliable;
bad addresses may cause program
termination.
The only syntax types that can match the end of the
and $LAMDA.

7-12

string

are

$EOS

THE TABLE-DRIVEN PARSER (TPARS}
PARSER.SAC

[]-------

Write a source program that
includes the required MCALL
statements.

-->'

MCALL ISTAT$
MCALL ST ATE$
MCALL TRAN$
STATE$
STATE$

PARSER.OBJ
MACR0-11

PARSER.SAC

I~ 2.

Assemble the source program to
produce an object module.

TKB

PARSER.OBJ

MYFILE.TSK

3.
MY FILE.OBJ

Execute the Task Builder to
produce a task image including
the parser.

UPDATE.OBJ

~
Figure 7-1

ZK-298-81

Processing Steps Required to Generate a Parser
Program Using TPARS

7-13

THE TABLE-DRIVEN PARSER (TPARS)
7.5

HOW TO GENERATE A PARSER PROGRAM USING TPARS

There are three processes involved in generating a parser program
using TPARS, as shown in Figure 7-1.
The source program must contain
MCALL statements for three macros:
ISTAT$, STATE$, and TRAN$.
These
three MCALL statements must precede the statements that comprise the
state table and action routines.
Assembling the source module produces an object module comprised of
three PSECTs:
$STATE,
$KTAB, and $KSTR.
When the Task Builder
executes, the task image produced is placed on an appropriate volume
for future use.
The assembly listing produced by the state table macros is not
straightforward.
The source language macros are designed for clarity
and convenience in writing state tables;
the object code is designed
for
compactness and processing convenience.
As a result, the
mechanism used to translate the source code to object code is not a
simple one.
The binary output of the macros is delayed by one statement. Thus, if
the listing of macro-generated binary code is enabled, the binary code
appearing after a macro call is, in fact, the result of the preceding
macro call.
Error messages generated by macro calls are similarly
delayed.
This is the reason an additional STATE$ macro is required to
terminate the state table.
When the parser program is linked and is in task imaqe form, it can be
invoked from within an executing user program, as shown in Figure 7-2.
Executing
User Program

User-defined
Parser Program

TPARS
Processor

r---~

STATE$
*

*
*
STATE$

1-1

- - - - - - - - - -1

I
CALL .TPARS

Action
Routines

I
I

~-_J

I
I
I

I
I
I
I
I
I
I

1-4----J

ZK-299-81

Figure 7-2

Flow of Control When TPARS Is Called from an Executing
User Program

Figure 7-2 shows the CALL .TPARS statement that invokes the parser
program and the TPARS processor. As the parser executes the state
table, it calls action routines. These action routines access code in
the TPARS processor to perform such functions as returning the values
of the built-in variables. When the state table completes execution,
TPARS receives control and passes control back to the calling program.

7-14

THE TABLE-DRIVEN PARSER (TPARS)
7.6

PROGRAMMING EXAMPLES

This section includes three programmed examples of how to use TPARS.
The first example shows the code required to parse a UFD command line
for RSX-11. The second example shows the use of subexpressions and
how to reject transitions.
The third example shows how to use
subexpressions to parse indeterminate grammars.

7.6.1

Parsing a UFO Command Line

This example shows the code required to parse a UFD command line.
It
includes a state table and action routines. The general form of the
UFD command line is as follows:
UFD DKO:LABEL[201,202]/ALLOC=l00./PRO=[RWED,RWED,RWE,R]
The action routines
values:
$UDEV
$UUNIT
$UVNML
<'-TT'T71'1'71 M

~UV.L'll"'l.l'l

$UUIC
$UALL
$UPRO
$FLAGS
UF.ALL
UF.PRO

this

parser

program

return

following

Device name (2 ASCII characters)
Unit number {binary)
Byte count of the volume label string
Address of the volume label string
Binary UIC for which to create a directory
Number of directory entries to preallocate
Binary protection word for UFD
Flags word containing the following bits:
Set if allocation was specified.
Set if protection was specified.

The label and the /ALLOC and /PRO switches are optional.
sequence for this routine is as follows:
CLR
MOV
MOV
MOV
MOV
CALL
BCS

the

The

Rl
#UFDKTB,R2
COUNT,R3
ADDR,R4
#START,R5
.TPARS
ERROR

The following is the user-written parser routine:
.TITLE

STATE TABLE FOR UFO COMMAND LINE

.MCALL

ISTAT$,STATE$,TRAN$

TO BE USED WITH BLANK SUPPRESS OPTION
!STAT$

UFDSTB,UFDKTB

READ OVER COMMAND NAME
.GLOBL

START

STATE$
TRAN$

START
"UFO"

7-15

calling

THE TABLE-DRIVEN PARSER (TPARS)
READ DEVICE AND UNIT NUMBER
STATE$
TRAN$

$ALPHA,,SETDV1

STATE$
TRAN$

$ALPHA,,SETDV2

STATE$
TRAN$
TRAN$

$NUMBR,DEV1,SETUNT
$LAMDA

STATE$
TRAN$

DEVl
I :

READ VOLUME LABEL
STATE$
TRAN$
TRAN$

$STRNG,RUIC,SETLAB
$LAMDA

STATE$
TRAN$

RUIC
!UIC

READ UIC

SCAN FOR OPTIONS AND END OF LINE
STATF.$

OPTS

TRAN$
TRAN$

$EOS,$EXIT

STATE$
TRAN$
TRAN$

SET

'/
"ALLOC",ALC,,UF.ALL,$FLAGS
"PRO",PRO,,UF.PRO,$FLAGS

7\ TT f"lf"'7\ ITITf"ll\T

£""i..&...l..L...IV\,,,,Cl.J...LV.L'41

STATE$
TRAN$
STATE$
TRAN$

ALC

'=
$NUMBR,OPTS,SETALC

PROTECTION
STATE$
TRAN$

PRO

STATE$
TRAN$

STATE$
TRAN$
TRAN$
TRAN$
TRAN$
TRAN$
TRAN$

SPRO
'] ,OPTS,ENDGRP
<' ,>,SPRO,NXGRP
'R,SPRO,SETRP
'W,SPRO,SETWP
'E,SPRO,SETEP
'D,SPRO,SETDP

[,,!GROUP

7-16

THE TABLE-DRIVEN PARSER {TPARS)
SUBEXPRESSION TO READ AND STORE UIC
STATE$
TRAN$

UIC

STATE$
TRAN$

$NUMBR,, SETGN

STATE$
TRAN$

$NUMBR,,SETPN

STATE$
TRAN$

'],$EXIT

[

STATE$
STATE TABLE SIZE: 60 WORDS
KEYWORD TABLE SIZE:
8 WORDS
KEYWORD POINTER SPACE: 3 WORDS
.SBTTL

ACTION ROUTINES FOR THE COMMAND LINE PARSER

; DEVICE NAME CHAR 1
SETDVl::MOVB

.PCHAR,$UDEV
RETURN

; DEVICE NAME CHAR 2
SETDV2::MOVB

.PCHAR,$UDEV+l
RETURN

; UNIT NUMBER
SETUNT: :MOV

.PNUMB,$UUNIT
RETURN

; VOLUME LABEL
SETLAB: :MOV

.PSTCN,$UVNML
MOV
.PSTPT,$UVNAM
RETURN

; PPN - GROUP NUMBER
SETGN: :

MOVB
BR

.PNUMB,$UUIC+l
TSTPPN

; PPN - PROGRAMMER NUMBER
SETPN: :
TSTPPN:

10$:
20$:

MOVB
TST
BNE
TSTB
BEQ
ADD
RETURN

.PNUMB,$UUIC
.PNUMH
10$
.PNUMB+l
20$
#2, (SP)

7-17

CHECK FOR ZERO HIGH

nnnr."ln

Vr\LJC.r\

CHECK FOR BYTE VALUE
BAD VALUE - REJECT TRANSITION

THE TABLE-DRIVEN PARSER (TPARS)
; NUMBER OF ENTRIES TO ALLOCATE
.PNUMB,$UALL
RETURN

SE TALC: : MOV
SET PERMISSIONS
INITIALIZE

#4 ,GRCNT

!GROUP: : MOV

; MOVE TO NEXT PERMISSIONS CATEGORY
NXGRP::

BADGRP:
30$:

SEC
ROR
ASR
ASR
ASR
DEC
BGE
ADD
RETURN

FORCE ONES
$UPRO
$UPRO
$UPRO
$UPRO
GRCNT
30$
#2, (SP)

SHIFT TO NEXT GROUP
COUNT GROUPS
TOO MANY IS AN ERROR
IF SO, REJECT TRANSITION

; SET READ PERMIT
SETRP: :

BIC
RETURN

#FP.RDV*l0000,$UPRO

BIC
RETURN

#FP.WRV*l0000,$UPRO

: SET WRITE PERMIT
SETWP::

; SET EXTEND PERMIT
SETEP::

BIC

#FP.EXT*l0000,$UPRO

RETURN
; SET DELETE PERMIT
BIC
RETURN
; END OF PROTECTION SPEC

SETDP::

ENDGRP::TST

7.6.2

#FP.DEL*l0000,$UPRO

GRCNT
BNE
RETURN

; CHECK THE GROUP COUNT
BADGRP
; MUST HAVE 4

.END

UFD

How to Use Subexpressions and Reject Transitions

This example is an excerpt of a state table that parses a string
quoted by an arbitrary character.
That is, the first character is
interpreted as a quote character.
This typical construction occurs in
many
editors
and
programming languages.
The action routines
associated with the state table return the byte count and address of
the string in the locations QSTC and QSTP.
The quoting character is
returned in location QCHAR.

7-18

THE TABLE-DRIVEN PARSER (TPARS)
MAIN LEVEL STATE TABLE
;

PICK UP THE QUOTE CHARACTER
STATE$
TRAN$

STRING
$ANY,,SETQ

ACCEPT THE QUOTED STRING
STATE$
TRAN$

!QSTRG,,SETST

GOBBLE UP THE TRAILING QUOTE CHARACTER
STATE$
TRAN$

$ANY,NEXT,RESET

SUBEXPRESSION TO SCAN THE QUOTED STRING
THE FIRST TRANSITION WILL MATCH UNTIL IT IS REJECTED
BY THE ACTION ROUTINE
STATE$
TRAN$
TRAN$

QSTRG
$ANY,QSTRG,TESTQ
$LAMDA,$EXIT

ACTION ROUTINES
STORE THE QUOTING CHARACTER
SETQ:

MOVB
INCB
RETURN

.PCHAR,QCHAR
• PF LAG

TURN OFF SPACE FLUSH

; TEST FOR QUOTING CHARACTER IN THE STRING
TESTQ:

CMPB
.PCHAR,QCHAR
BNE
10$
ADD
#2, (SP)
10$:
RETURN
; STORE THE STRING DESCRIPTOR

SETST:

MOV
MOV
RETURN

REJECT TRANSITION ON MATCH

.PSTPT,QSTP
.PSTCN,QSTC

; RESET THE SPACE FLUSH FLAG
RESET:

7.6.3

DECB
RETURN

.PFLAG

Using Subexpressions to Parse Complex Grammars

This example is an excerpt from a state table
subexpressions are used to parse complex grammars.

that

shows

how

The state table accepts a number followed by a keyword qualifier.
Depending on the keyword, the number is interpreted as either octal or
decimal.

7-19

THE TABLE-DRIVEN PARSER {TPARS)
The binary value of the number is returned in the tagged NUMBER.
following types of strings are accepted:

The

10/0CTAL
359/DECIMAL
77777 /0CTAL
MAIN STATE TABLE ENTRY - ACCEPT THE EXPRESSION AND
STORE ITS VALUE
STATE$
TRAN$
TRAN$

!ONUMB,NEXT,SETNUM
!DNUMB,NEXT,SETNUM

SUBEXPRESSION TO ACCEPT OCTAL NUMBER
STATE$
TRAN$

ONUMB
$NUMBR

STATE$
TRAN$

"OCTAL",$EXIT

SUBEXPRESSION TO ACCEPT DECIMAL NUMBER
STATE$
TRAN$

DNUMB
$DNUMB

STATE$
TRAN$

"DECIMAL",$EXIT

; ACTION ROUTINE TO STORE THE NUMBER
SETNUM:

MOV
MOV
RETURN

.PNUMB,NUMBER
.PNUMH,NUMBER+2

The contents of .PNUMB and .PNUMH remain undisturbed
transitions except the $NUMBR and $DNUMB types.

all

state

Because of the way in which subexpressions are processed, calls to
action routines from within subexpressions must be handled with care.
When a subexpression is encountered in a transition, TPARS saves its
current context and calls itself, using the label of the subexpression
as the starting state.
If the subexpression parses successfully and
returns by means of $EXIT, the transition is taken and control passes
to the next state.
If the subexpression encounters a syntax error, TPARS restores
saved context and tries to take the next transition in the state.

the

However, TPARS provides no means for resetting original values changed
by action routines called by subexpressions.
Therefore, action
routines called from subexpressions should store results in an
intermediate area.
Data in this intermediate area can then be
accessed by an action routine called from the primary level of the
_state table.

7-20

CHAPTER 8
SPOOLING

FCS provides facilities at both the macro
queue files for subsequent printing.

8.1

and

subroutine

level

PRINT$ MACRO CALL

A task issues the PRINT$ macro call to queue a file for printing on a
specified device.
The specified device must be a unit record,
carriage-controlled device such as a line printer or terminal. If the
device is not specified, LP: is used.
The file to be spooled must be open when the PRINT$ macro
PRINT$ closes the file.
Error returns differ from
conventions and are described in Section 8.3.

is issued.
normal FCS

The PRINT$ macro call has the following format:
PRINT$ fdb,err,,dev,unit,pri,forms,copies,presrv
f db

The address of the associated FDB.
err
The address of an optional,
See Section 8.3.

user-coded

error-handling

routine.

The following parameters are not applicable to RSX-llM/M-PLUS.
A blank parameter is present between err and dev,
additional comma.

thus

requiring

dev
The 2-character device mnemonic of the device on which the file
is to be printed.
If dev is not specified, LP: is used by
default.

8-1

SPOOLING

unit
The unit number of the device on which the file is to be printed.
If unit is not specified, unit 0 is used by default.
pri
A number in the range 1 through 250 to indicate the priority of
the request.
The priority is used to determine the order in
which spooled files are dequeued for printing.
If pri is
omitted, the task's priority is used by default.
forms
The specific form-type on which the file is to be printed, as
indicated by a number in the range 0 through 6. This parameter
must be specified as a single integer without a preceding number
sign {#).
The numbers 0 through 6 are associated with the
various forms for an installation by the system manager.
If
forms is omitted, form-type 0 is used by default.
copies
A number in the range 1 through 32(decimal) to indicate the
number of copies of the file to be produced. The number of
copies must be specified as a 1- er 2-digit integer without a
preceding number sign (#).
If copies is omitted, one copy is
printed. If copies is specified as a decimal number, a trailing
decimal point should be included in the parameter.
presrv
Should be specified if the file is not to be deleted after it is
printed.
Any parameter value results in the file's being
preserved after printing.

8.2

.PRINT SUBROUTINE

The .PRINT subroutine is called to queue a file for printing.
The
file must be open when .PRINT is called, and then the .PRINT routine
closes the file. RO must contain the address of the associated FDB.
One copy of the file is printed on LP:.
Section 8.3 describes error
routine.

8.3

handling

for

the

.PRINT

file

control

ERROR HANDLING

The error returns provided in conjunction with PRINT$ and .PRINT
differ from the standard FCS error returns in that error codes are
placed in F.ERR or in the directive status word, depending on when the
failure occurred.

8-2

SPOOLING

If the failure is FCS related (for example, the PRINT$ macro cannot
close the file), the C-bit is set and F.ERR contains the error code.
If the failure is related to the SEND/REQUEST directive that queues
the file,
the C-bit is set and the directive status word contains an
error code. Directive status word· error codes are provided in the
Executive Reference Manual of the host operating system.
Normally, user-coded error routines, upon determining that the C-bit
is set, should test F.ERR first and then test the directive status
word.

8-3

APPENDIX A
FILE DESCRIPTOR BLOCK

A File Descriptor Block {FDB) contains file information that is used
by FCS and the file control primitives.
The layout of an FDB is
illustrated in Figure A-1.
Table A-1 defines the offset locations
within the FDB.
The offset names in the file descriptor block may
locally or globally, as shown below:
FDOF$L

;DEFINE OFFSETS LOCALLY.

FDOFF$

DEF$L

;DEFINE OFFSETS LOCALLY.

FDOFF$

DEF$G

;DEFINE OFFSETS GLOBALLY.
NOTE

When you refer to FDB locations,
it is
essential to use the symbolic offset
names, rather than the actual address of
such
locations.
The
position
of
information within the FDB
may
be
subject
to
change from release to
release, whereas the offset names remain
constant.

A-1

defined

either

FILE DESCRIPTOR BLOCK

F.RTYP

F.RATT
F.RSIZ
File-Attribute Section
F.HIBK
F.EFBK
F.FFBY
F.RCTL

F.RACC

F.BKDS or F.URBD
F.NRBD or
Record- or Block-Access
Section

F.BKST and F.BKDN
F.OVBS or F.NREC
F.EOBB
F.RCNM or
F.CNTG and F.STBK
F.ALOC
F.FACC

File-Open Section

F.LUN

F.DSPT

}
I

F.DFNB
F.BKP1

F.EFN or F.BKEF

F.ERR+I

F.ERR

F.MBC1

F.MBCT

F,BGBC

F.MBFG
F.VBSZ
F.BBFS

Block-Buffer Section

F.BKVB or F.VBN
F.BDB
F.SPDV
F.CHR

F.SPUN

F.ACTL
F.SEON
F.FNB
ZK-300-81

Figure A-1

File Descriptor Block Format

A-2

FILE DESCRIPTOR BLOCK
Table A-1
FOB Offset Definitions
Offset

Size
(in bytes)

Contents

F.RTYP

Record-type byte.
This byte is set, as
follows, to indicate the type of records for
the file:
F.RTYP = 1
to
indicate
fixed-length
records (R.FIX).
F.RTYP = 2 to indicate variable-length
records {R. VAR).
F.RTYP = 3 to indicate sequenced records
(R.SEQ).

F.RATT

Record attribute byte. Bits 0 through 3 are
set
to
indicate record attributes, as
follows:
Bit 0 = 1 to indicate that the first byte
of a record is to contain a FORTRAN
carriage control
character
(FD.FTN);
otherwise, it is 0.
Bit 1 = 1 to indicate for a carriage
control device that a line feed is to be
performed before the line is printed and
a carriage return is to be performed
after the line is
printed
(FD.CR);
otherwise, it is 0.
Bit 2 is not used.
Bit 3 = 1 to indicate that records cannot
cross
block
boundaries
(FD.ELK);
otherwise, it is 0.

F.RSIZ

Record-size word.
This location contains
the
size
of
fixed-length
records or
indicates the size of the largest record
that
currently
exists
in
a file of
variable-length records.

F. HIBK

Indicates the highest virtual
allocated.

F.EFBK

Contains the end-of-file block number.

block

number

The format of the block number is high-order
word followed by low-order word.
F.FFBY

Indicates the first
free byte in the last
block,
or
the maximum block size for
magnetic tape.
(continued on next page)

A-3

FILE DESCRIPTOR BLOCK
Table A-1
(Cont.)
FOB Offset Definitions
Offset

Size
(in bytes)

Contents

F.RACC

Record access byte. Bits 0 through 3 of
this byte define the record access modes, as
follows:
Bit 0 = 1 to indicate READ$/WRITE$ mode
(FD.RWM);
otherwise,
it
is 0
to
indicate GET$/PUT$ mode.
Bit 1 = 1 to indicate random access mode
GET$/PUT$
(FD.RAN)
for
record I/O;
otherwise, it is 0 to indicate sequential
access mode.
Bit 2 = 1 to indicate locate
mode
(FD.PLC)
for
GET$/PUT$
record I/O;
otherwise, it is 0 to indicate move mode.
Bit 3 = 1 to indicate that PUT$ operation
in sequential mode does not truncate the
file fFD.INS\!
othe:rwise , it is 0 to
indicate
that
PUT$
operation
in
sequential mode truncates the file.

F.RCTL

Device characteristics byte. Bits O through
5 define the characteristics of the device
associated with the file, as follows:
Bit 0 = 1 to indicate a record-oriented
device
(FD.REC), for example, a Teletype
or line printer; a value of O indicates
a block-oriented device: for example: a
disk or DECtape.
Bit 1 = 1 to indicate a carriage control
device (FD.CCL};
otherwise, it is O.
Bit 2
1 to
indicate a
teleprinter
device (FD.TTY};
otherwise, it is O.
Bit 3 = 1 to indicate a directory
(FD.DIR); otherwise, it is O.

device

Bit 4 = 1 to indicate a single directory
device
(FD.SDI).
An MFD is used, but no
UFDs are present.
Bit 5 = 1 to
indicate a block-oriented
device that is inherently sequential in
nature (FD.SQD), such as magnetic tape.
A record-oriented device is assumed to be
sequential in nature;
therefore, this
bit is not set for such devices.
(continued on next page)

A-4

FILE DESCRIPTOR BLOCK
Table A-1
(Cont.)
FOB Offset Definitions
Off set

Contents

Size
(in bytes)
I

F.BKDS
or
F.URBD

F.NRBD
or
F.BKST
and
F.BKDN

,.,,

""'!
.t'. OVts::;

Contains the block I/O buffer descriptor.
Contains the user record buffer descriptor.

Contains the next record buff er descriptor.,

Contains the address of the I/O status block
for block I/O.

Contains the address of
routine for block I/O.

the

AST

service

,
•• .c .c
.:
mi...:
.c.:
...
"
uverr.ide
hJ.OCK buLLer S.1..Zc.
.LU.LS .L..Le.J.u
has
meaning only before the file is opened.
.!

,.;i

F.NREC

Contains the address of the next
the block.

F.EOBB

Contains a value defining
buffer.

F.RCNM
or

Contains the number of the record for random
access operations.

F.CNTG

Contains a numeric value defining the number
of blocks to be allocated in creating a new
file. This cell has meaning only before the
file is opened.
A value of 0 means leave
the file empty;
a positive value means
allocate the specified number of blocks as a
contiguous
area
and
make
the
file
contiguous; a negative value means allocate
the specified number of
blocks
as
a
noncontiguous
area
and
make the file
noncontiguous.

F.STBK

Contains the address of the statistics block
in your program.

F.ALOC

Contains the number of
blocks
to
be
allocated when the file must be extended. A
positive (+) value indicates
contiguous
extend, and a negative (-) value indicates
noncontiguous extend.

F.LUN

Contains the logical unit number
with the FDB.

the

record

end-of-block

associated

(continued on next page)

A-5

I
I

FILE DESCRIPTOR BLOCK

Table A-1
(Cont.)
FDB Offset Definitions
Off set

Size
(in bytes)

Contents

F.FACC

File access byte. This byte indicates the
access privileges for a file, as summarized
below:
Bit 0 = 1 i f the file
read only (FA.RD).

accessed

for

Bit 1 = 1 if the file
writing (FA.WRT).

accessed

for

Bit 2 = 1 i f the file
extending (FA.EXT).

accessed

for

Bit 3 = 1 if a new file is being created
(FA.CRE); otherwise, it is 0 to indicate
an existing file.
Bit 4 = 1 if the file is a temporary file
{FA.TMP).
if the file
Bit 5 = l
shared access (FA.SHR).

"T"\01""\0~

for

""J:"""'-&.&"'-'-A

II
I

I f Bit 3 above is 0:

Bit 6 = 1 if an existing file is being
appended (FA.APD).

I f Bit 3 above is one

Bit 6 = 1 i f not
existing
file at
(FA.NSP).

( 1) :

superseding
an
file-create time

F .DSPT

Contains the dataset-descriptor pointer.

F.DFNB

Contains the default filename block pointer.

F.BKEF
or
F.EFN

Contains the block I/O event flag.

F.BKPl

Contains bookkeeping bits for
control.

F.ERR

A negative
Error return code byte.
indicates an error condition.

Contains the record I/O event flag.
FCS

internal

value

(continued on next page)

A-6

FILE DESCRIPTOR BLOCK
Table A-1
(Cont.)
FDB Offset Definitions
Off set

Size
(in bytes)

Contents

F.ERR+l

Used in conjunction with F.ERR above.
If
F.ERR is negative, the following applies:
F.ERR+l = 0 to indicate that error code
is an I/O error code (see IOERR$ error
codes in Appendix I).
F.ERR+l = negative value to indicate that
error code is a Directive Status Word
error code (see DRERR$ error codes in
Appendix I).

F.MBCT

Indicates the number of buffers to
for multiple buffering.

F.MBCl

Indicates the actual number of
buffers
currently
in use if the multibuffering
version of FCS is in use.

F.MBFG

Multibuffering flag word.
Contains either
one of the multibuffering flags, as follows:

F.BGBC

Bit 0
(FD.RAH).

Bit 1
(FD.WBH).

indicate

used

read-ahead
write-behind

indicate

Big buffer block count in number of blocks
if the big-buffer version of FCS is in use.
Buffer offset for reading ANSI magnetic tape
in record mode.

F. VBSZ

Device buffer size word.
Contains
virtual block size (in bytes).

F.BBFS

Indicates the block buffer size.

F.BKVB
or

Contains the virtual block
user program for block I/O.

number in the

Contains the virtual block number.

F. VBN

F.BDB

the

Contains the address of the block buffer
descriptor
block.
This location always
contains a nonzero value if the file is open
and 0 if the file is closed.
(continued on next page)

A-7

FILE DESCRIPTOR BLOCK
Table A-1
(Cont.)
FDB Offset Definitions
Offset

Size
(in bytes)

Contents

F.SPDV

Reserved for future use.

F.SPUN

Reserved for future use.

F.CHR

Volume characteristics byte.
Bit 0 = 1 to indicate
formats D or F.

ANSI

magnetic

tape

F.ACTL

The low-order byte of this word indicates
the number of retrieval pointers to be used
for the file.

F.ACTL

The control bits are in the high-order
and are defined as follows.
n.: ~

U.L\,..

, c
..L..J

information
(FA. ENB) •

....

,_......,.1""11.,,....; -1=~ T
..;Jt'CV..Li...J'

....

"'"" ....

byte

,.."
..... ~,....",
'-''-''.l.'-.1.V..L.

be taken from F.ACTL

Bit 12 = 0 to cause positioning to the
end of a magnetic tape volume set upon
open or close.
Bit 12 = 1 to cause positioning of a
magnetic tape volume set to just past the
most recently closed file when the next
file is opened (FA:POS)=
Bit 11 = 1 to cause a magnetic tape volume
set
to be rewound upon open or close
(FA.RWD).
Bit 9 = 1 to cause a file not to be locked
if it is not properly closed when accessed
for write (FA.DLK).
F.SEQN

F.FNB

Contains the sequence number
records.

for

Defines the beginning
address
filename block portion of the FDB.

A-8

sequenced

the

APPENDIX B

FILENAME BLOCK

The format of a filename block is illustrated in Figure B-1.
offsets within the filename block are described in Table B-1.

The

The offset names in a filename block may be defined either locally
globally, as shown below:

;DEFINE OFFSETS LOCALLY.

NBOF$L
NBOFF$

DEF$L

;DEFINE OFFSETS LOCALLY.

NBOFF$

DEF$G

;DEFINE OFFSETS GLOBALLY.
NOTE

When you are referring to filename block
locations,
it is essential to use the
symbolic offset names, rather than the
actual addresses of such locations.
The
position of information
within
the
filename block may be subject to change
from release to release, whereas the
offset names remain constant.

B-1

FILENAME BLOCK
Table B-1
Filename Block Offset Definitions

Off set

Size
(in Bytes)

N.FID

File identification field

N.FNAM

File name
characters
format

field;
specified
nine
as
that are stored in Radix-50

N.FTYP

File type
characters
format

specified as
three
field;
that are stored in Radix-50

N.FVER

File version number field (binary)

N.STAT

Filename block status word
definitions in Table B-2.)

N.NEXT

Context for next .FIND operation

N.DID

Directory identification field

N.DVNM

ASCII device name field

I N. UNIT

Unit number field (binary)

Contents

(See

The bit definitions of the filename block status word (N.STAT) in
FDB and their significance are described in Table B-2.

bit

the

Symbols marked with an asterisk (*) in Table B-2 indicate bits that
are set if the associated information is supplied through an ASCII
dataset descriptor.

B-2

FILENAME BLOCK
0

N.FID

4
6

N.FNAM

10
12

N.FTYP

N.FVER

N.STAT

CUMULATIVE
LENGTH IN
BYTES (OCTAL)

20
N.NEXT

22
24

N.DID

--------11I::
.,32u

N.DVNM
N.UNIT

,___~~~~~~~~~~---

34
ZK-301-81

Figure B-1

Filename Block Format

Table B-2
Filename Block Status Word {N.STAT)

Symbol

Value
(in Octal)

Meaning

NB.VER*

Set if explicit
specified

NB.TYP*

Set if explicit file type is specified

NB.NAM*

Set if explicit file name is specified

NB.SVR

Set if wildcard
specified

NB.STP

Set if wildcard file type is specified

NB.SNM

Set

~ r::
.LI:

file

version

number

wildcard file name is specified

(continued on next page}

B-3

FILENAME BLOCK
Table B-2 (Cont.)
Filename Block Status Word (N.STAT)

Symbol

Value
(in Octal)

NB.DIR*

100

Set if explicit directory string {UIC)
specified

NB.DEV*

200

Set if explicit
specified

NB.SDl

400

Set if group portion
wildcard specification!

UIC

contains

NB.SD2

1000

Set if owner portion
wildcard specification!

UIC

contains

NB.ANS

2000

Set if file name is in ANSI format.

1. Although NB.SDl
supported by FCS.

and

Meaning

NB.SD2

are

device

name

defined, they

are

string

not

set

Table B-3
Filename Block Offset Definitions for ANSI Magnetic Tape

Off set . {inSize
Bytes)
N.FID

N.ANMl

Definition
File identification field
First 12 bytes of ANSI file name string

I File version number field

I N.FVER

N.STAT

Filename block status word (See bit
in Table B-2.)

N.NEXT

Context for next .FIND operation

N.ANM2

Remainder of the ANSI file name string

N.DVNM

ASCII device name field

N.UNIT

Unit number field (binary)

The bit definitions of the filename block
shown in Table B-2.

(binary)

status

word

definitions

(N.STAT)

The filename block format for ANSI magnetic tape file names
in Figure B-2.

B-4

are
shown

FILENAME BLOCK
0
N.FID

2
N.ANM1

I 14
N.FVER

16
N.STAT

20
N.NEXT
22
N.ANM2
30
N.DVNM
N.UNIT

34
ZK-302-81

Figure B-2

ANSI Filename Block Format

B-5

APPENDIX C
SUMMARY OF I/0-RELATED SYSTEM DIRECTIVES

Table C-1 contains a summary of the I/0-related system directives in
alphabetical order for ready reference. The parameters that may be
specified with a directive are also described in the order of their
appearance in the directive. These directives are described in detail
in the Executive Reference Manual of the host operating system.
Table C-1
Summary of I/0-Related System Directives
Function and Parameters

Directive
ALUN$

Assigns a logical unit number to a physical device:
lun = Logical unit number

GLUN$

dev

= Physical device name

unt

= Physical device unit number

Fills a 6-word
physical unit:
lun

buff er

with

ASCII characters)

information

about

= Logical unit number

buf = Address of a 6-word buff er in which the
information is to be stored
GMCR$

LUN

Transfers an 80-byte MCR/PDS command line to the
issuing task.
No parameters are required in this
directive.
(continued on next page)

C-1

SUMMARY OF I/0-RELATED SYSTEM DIRECTIVES
Table C-1 (Cont.)
Summary of I/0-Related System Directives
Directive
QIO$

RCVD$

RCVS$

Function and Parameters
Places an I/O request in the device queue
with the specified logical unit number:

associated

fnc

I/O function code

lun

Logical unit number

efn

Event flag number

pri

Priority of the request (IAS only)

isb

Address of the I/O status block

ast

Entry-point address of the AST service
routine

prl

Parameter list in the form< Pl, ••• ,P6>

Receives a 13-word data block that has been queued
(FIFO)
by a send data directive (see SDAT$ and SDRQ$
below) :
tsk

Name of the sending task.
This field is
ignored by RSX-11.
The tsk parameter is
specified as a null value (,) in RSX-11 for
compatibility with IAS (see the description
of the RCVD$ directive in the RSX-llM/M-PLUS
Executive Reference Manual).

buf

Address of the 15-word data buffer
(2-word
sending task name and 13-word data block).

Receives a 13-word data block if queued by
a
send-data directive
(see SDAT$ AND SDRQ$ below), or
suspends task if no data is queued:
tsk

Name of the sending task

buf

Address of the 15-word data buffer
(2-word
sending task name and 13-word data block)

This directive is not supported in RSX-11.
(continued on next page)

C-2

SUMMARY OF I/0-RELATED SYSTEM DIRECTIVES
Table C-1 (Cont.)
Summary of I/0-Related System Directives
Function and Parameters

Directive
RCVX$

Receives a 13-word data block if queued by a send
data directive (see SDAT$ and SDRQ$ below), or exits
if data is not queued for the task:
tsk

buf

SDRQ$

= Name of the sending

task.
This field
is
ignored by RSX-11.
The tsk parameter is
specified as a null value (,) in RSX-11 for
compatibility with IAS (see the description
of the RCVX$ directive in the RSX-llM/M-PLUS
Executive Reference Manual)
Address of the 15-word data buffer
(2-word
sending task name and 13-word data block) •
SDAT$ Queues {FIFO) a 13-word block of data
for a task to receive:
tsk

Name of the receiving task

buf

Address of the 13-word data buff er

efn

Event flag number

Queues (FIFO) a 13-word block of data for a task to
receive;
also requests or resumes the execution of
the receiving task:
tsk

Name of the receiving task

par

Partition name of the receiving task

pri

Priority of the request

ugc

UIC group code

upc

UIC owner code

buf

Address of the 13-word data buffer

efn

Event flag number

This directive is not supported in RSX-11.

C-3

APPENDIX D
SAMPLE PROGRAMS

The sample programs that follow read records from an input device,
strip off any blanks to the right of the data portion of the record,
and write the data record on an output device. While the programs are
intended primarily for card reader input and printer output, device
independence is maintained.
The main program is CRCOPY; CRCOPA and CRCOPB are variations. CRCOPA
uses a dataset descriptor instead of the default filename block used
in CRCOPY. CRCOPB uses run-time initialization of the FDB.
;CARD READER COPY ROUTINE
.TITLE CRCOPY
.MCALL FDBDF$,FDAT$A,FDRC$A,FDOP$A,NMBLK$,FSRSZ$
.MCALL OPEN$R,OPEN$W,GET$,PUT$,CLOSE$,EXIT$S
.MCALL FIN IT$
;ASSIGN CR OR FILE DEVICE
INLUN=3
;ASSIGN TO OUTPUT DEVICE
OUTLUN=4
FSRSZ$ 2
FDBOUT: FDBDF$
;ALLOCATE SPACE FOR OUTPUT FDB
FDAT$A R.VAR,FD.CR
;INIT FILE ATTRIBUTES
FDRC$A ,RECBUF,80.
;INIT RECORD ATTRIBUTES
FDOP$A OUTLUNiiOFNAM
;INIT FILE OPEN SECTION
FDBIN: FDBDF$
;ALLOCATE SPACE FOR INPUT FDB
FDRC$A ,RECBUF,80.
;INIT RECORD ATTRIBUTES
FDOP$A INLUN, , IFNAM
;INIT FILE OPEN SECTION
RECBUF: .BLKB
;RECORD BUFFER
80.
OFNAM: NMBLK$ OUTPUT,DAT
;OUTPUT FILENAME
IFNAM: NMBLK$ INPUT,DAT
; INPUT FILENAME
START: FINIT$
;INIT FILE STORAGE REGION
OPEN$R #FDBIN
;OPEN THE INPUT FILE
BCS
ERROR
;BRANCH IF ERROR
OPEN$W #FDBOUT ;OPEN THE OUTPUT FILE
BCS
ERROR
;BRANCH IF ERROR
GTREC: GET$
#FDBIN
;NOTE - URBD IS ALL SET UP
BCS
CKE6F
;ERROR SHOULD BE EOF INDICATION
MOV
F.NRBD(RO),Rl
;Rl=SIZE OF RECORD READ
MOV
#RECBUF,R2
ADD
Rl,R2
;R2=ADDRESS OF LAST BYTE+l
10$:
CMPB
;STRIP TRAILING BLANKS
#40,-(R2)
SOB
Rl,10$
;AT THIS POINT, Rl CONTAINS THE STRIPPED SIZE OF THE
;RECORD TO BE WRITTEN.
IF THE CARD rs BLANK,
;A ZERO-LENGTH RECORD IS WRITTEN.
PTREC: PUT$
#FDBOUT,,Rl
;Rl IS NEEDED TO SPECIFY
BCC
GTREC
;THE RECORD SIZE.
ERROR: NOP
;ERROR CODE GOES HERE

D-1

SAMPLE PROGRAMS
CKEOF:

CMPB
BNE
CLOSE$
BCS
CLOSE$
BCS
EXIT$S
.END

#IE.EOF,F.ERR(RO) ; END OF FILE?
ERROR
;BRANCH IF OTHER ERROR
RO
;CLOSE THE INPUT FILE
ERROR
#FDBOUT
;CLOSE THE OUTPUT FILE
ERROR
; ISSUE EXIT DIRECTIVE
START

;CARD READER COPY ROUTINE
• TITLE CRCOPA
.MCALL FDBDF$,FDAT$A,FDRC$A,FDOP$A,NMBLK$,FSRSZ$
.MCALL OPEN$R,OPEN$W,GET$,PUT$,CLOSE$,EXIT$S
.MCALL FIN IT$
;ASSIGN CR OR FILE DEVICE
INLUN=3
;ASSIGN TO OUTPUT DEVICE
OUTLUN=4
FSRSZ$ 2
FDBOUT: FDBDF$
FDAT$A R.VAR,FD.CR
FDRC$A ,RECBUF,80.
FDOP$A OUTLUN,OFDSPT
FDBIN: FDBDF$
FDRC$A ,RECBUF,80.
FDOP$A INLUN,IFDSPT
RECBUF: .BLKB
80.
;DEVICE DESCRIPTOR
CFDSPT: .WORD
0,0
;DIRECTORY DESCRIPTOR
.WORD
O,O
.WORD
ONAM$Z,ONAM
;FILENAME DESCRIPTOR
IFDSPT: .WORD
0,0
;DEVICE DESCRIPTOR
.WORD
0,0
;DIRECTORY DESCRIPTOR
.WORD
INAMSZ,INAM
;FILENAME DESCRIPTOR
ONAM:
.ASCII /OUTPUT.DAT/
ONAMSZ=.-ONAM
.EVEN
.ASCII /INPUT.DAT/
INAM:
INAMSZ=.-INAM
.EVEN
;INIT FILE STORAGE REGION
START: FIN IT$
OPEN$R #FDBIN
;OPEN THE INPUT FILE
;BRANCH IF ERROR
BCS
ERROR
OPEN$W #FDBOUT ;OPEN THE OUTPUT FILE
;BRANCH IF ERROR
BCS
ERROR
GTREC: GET$
#FDBIN
;NOTE - URBD IS ALL SET UP
;ERROR SHOULD BE EOF INDICATION
BCS
CKE OF
;Rl=SIZE OF RECORD READ
MOV
F.NRBD(RO) ,Rl
MOV
#RECBUF,R2
;R2=ADDRESS OF LAST BYTE+l
ADD
Rl,R2
;STRIP TRAILING BLANKS
CMPB
#40,-(R2)
10$:
BNE
PT REC
SOB
Rl,10$
;AT THIS POINT, Rl CONTAINS THE STRIPPED SIZE OF THE
;RECORD TO BE WRITTEN.
IF THE CARD IS BLANK,
;A ZERO-LENGTH RECORD IS WRITTEN.
PTREC:
PUT$
#FDBOUT,,Rl
;Rl IS NEEDED TO SPECIFY
BCC
GTREC
;THE RECORD SIZE.
ERROR: NOP
;ERROR CODE GOES HERE
CKEOF: CMPB
#IE.EOF,F.ERR(RO) ;END OF FILE?
BNE
ERROR
;BRANCH IF OTHER ERROR
CLOSE$ RO
;CLOSE THE INPUT FILE
BCS
ERROR
;CLOSE THE OUTPUT FILE
CLOSE$ #FDBOUT
BCS
ERROR
;ISSUE EXIT DIRECTIVE
EXIT$S
START
.END

D-2

SAMPLE PROGRAMS
.TITLE CRCOPB
;CARD READER COPY ROUTINE
.MCALL FDBDF$,FDAT$A,FDRC$A,FDOP$A,NMBLK$,FSRSZ$
.MCALL OPEN$R,OPEN$W,GET$,PUT$,CLOSE$,EXIT$S
.MCALL FINIT$, FDAT$R
INLUN=3
;ASSIGN CR OR FILE DEVICE
OUTLUN=4
;ASSIGN TO OUTPUT DEVICE
FSRSZ$ 2
FDBOUT~ FDBDF$
FDBIN: FDBDF$
RECBUF: .BLKB
80.
;DEVICE DESCRIPTOR
CFDSPT: .WORD
0,0
;DIRECTORY DESCRIPTOR
.WORD
0,0
.WORD
ONAM$Z,ONAM
;FILENAME DESCRIPTOR
IFDSPT: .WORD
0,0
;DEVICE DESCRIPTOR
;DIRECTORY DESCRIPTOR
.WORD
0,0
.WORD
INAMSZ,INAM
;FILENAME DESCRIPTOR
ONAM:
.ASCII /OUTPUT.DAT/
ONAMSZ=.-ONAM
.EVEN
!NAM:
.ASCII /INPUT.DAT/
INAMSZ=.-INAM
wEVEN
FINIT$
;INIT FILE STORAGE REGION
START:
OPEN$R #FDBIN,#INLUN,#IFDSPT,,#RECBUF,#80.
;RUNTIME INITIALIZATION
BCS
ERROR
;BRANCH IF ERROR
FDAT$R #FDBOUT,#R.VAR,#FD.CR
;RUNTIME INITIALIZATION
OPEN$W RO,#OUTLUN,#OFDSPT,,#RECBUF,#80.
BCS
ERROR
;BRANCH IF ERROR
GTREC: GET$
#FDBIN
;NOTE - URBD IS ALL SET UP
BCS
CKEOF
;ERROR SHOULD BE EOF INDICATION
MOV
F.NRBD(RO) ,RJ
;Rl=SIZE OF RECORD READ
MOV
#RECBUF,R2
ADD
Rl,R2
;R2=ADDRESS OF LAST BYTE+l
10$:
CMPB
#40,-(R2)
;STRIP TRAILING BLANKS
BNE
PT REC
SOB
Rl,10$
;AT THIS POINT, Rl CONTAINS THE STRIPPED SIZE OF THE
;RECORD TO BE WRITTEN.
IF THE CARD IS BLANK,
;A ZERO-LENGTH RECORD IS WRITTEN.
PTREC: PUT$
#FDBOUT,,Rl
;Rl IS NEEDED TO SPECIFY
BCC
GTREC
;THE RECORD SIZE.
ERROR: NOP
;ERROR CODE GOES HERE
CKEOF: CMPB
#IE.EOF,F.ERR(RO) ;END OF FILE?
BNE
ERROR
;BRANCH IF OTHER ERROR
CLOSE$ RO
;CLOSE THE INPUT FILE
BCS
ERROR
CLOSE$ #FDBOUT
;CLOSE THE OUTPUT FILE
BCS
ERROR
EXIT$S
;ISSUE EXIT DIRECTIVE
• END
START

D-3

APPENDIX E
INDEX FILE FORMAT

The index file ([O,O]INDEXF.SYS) of a
FILES-11 volume consists of
virtual blocks, starting with Virtual Block 1, the bootstrap block.
Virtual Block 2 is the home block.
The structure of an index file
is
shown below.
Virtual Block Number

Index File Element

Bootstrap block.

Home block.

Index file bit map (n blocks);
the value of n is in the home
block.

3+n

Index file header.

3+n+l

Storage-map header.

3+n+2

Bad-block file header.

3+n+3

Master File Directory header.

3+n+4

Checkpoint file header

3+n+5

User file header 1.

3+n+6

User file header 2.

User file header n.

E.l

BOOTSTRAP BLOCK

A disk that is structured for FILES-11 has a 256-word block, startinq
at physical block O.
This block contains either a bootstrap routine
or a message to the operator stating that the volume does not contain
a bootstrappable system.
The bootstrap routine brings a core image
into memory from a predefined location on the disk.
In IAS, the core
image is pointed to by a file header block in the index file.

E-1

INDEX FILE FORMAT
E.2

HOME BLOCK

The home block contains volume identification information that is
formatted as shown in Table E-1. This block is located either in
Logical Block 1 or at any even multiple of 256 blocks.
The offset names in the home block may be defined
globally, as shown below.

E.3

either

HMBOF$

DEF$L

;DEFINES OFFSETS LOCALLY.

HMBOF$

DEF$G

;DEFINES OFFSETS GLOBALLY.

locally

INDEX FILE BIT MAP

The index file bit map controls the use of file header blocks in the
index file.
The bit map contains a bit for each file header block
contained in the index file. The bit for a file header block is
located by means of the file number of the file with which it is
associated. The values of the bit map are as follows:

O - Indicates that the file header block is available. The
control primitives can use this block to create a file.

file

This

block

1 - Indicates that the file header block is in use.
has already been used to create a file.

E.4

PREDEFINED FILE HEADER BLOCKS

The first five file header blocks are described below.
Significance

File Header Block
Index File Header

This is the standard
with the index file.

header

associated

Storage Map File
Header

The storage map is a file that is used'
to control the assignment of disk blocks
to files.

Bad Block File
Header

The bad block file is
consists
of
unusable
sectors) on the disk.

Master File Directory
Header

This header block is associated with the
Master File Directory for the disk.
This directory contains entries for the
index file, the storage map file, the
bad
block
file,
the
Master File
Directory (MFD), the checkpoint file,
and all User File Directories (UFDs).

Checkpoint File Header

This block identifies the file that is
used for the checkpoint areas for all
checkpointable tasks. In RSX-11, a task
can also have checkpoint space in the
task image itself.

a file
blocks

that
(bad

The remainder of the index file consists of file header blocks for
user files, as shown in the illustration at the beginning of this
section.

E-2

INDEX FILE FORMAT

Table E-1
Home Block Format

(

. Size
bytes)

Content

\1n

Offset

Index bit map size

H. IBSZ

Location of index bit
map

H. IBLB

Maximum files allowed

H.FMAX

Storage bit map cluster
factor

H.SBCL

Disk device type

H.DVTY

Structure level

H.VLEV

12.

Volume name (12 ASCII
characters)

H.VNAM

Reserved

Volume owner's UIC

H.VOWN

Volume protection code

H.VPRO

Volume characteristics

H.VCHA

Default file protection
word

H.DFPR

Reserved

Default number of
retrieval pointers
in a window

H. WISZ

Default number of
blocks to extend files

H.FIEX

Number of entries in
directory LRU

H.LRUC

11.

Available space

Checksum of words 0-28

H.CHKl

14.

Creation date and time

H.VDAT

1 OO•

Vo 1 um e head e r 1 ab el ( no t
used)

82.

System specific information (not used)

254.

Relative volume table
(not used)

Checksum of home block
(Words O through 255)
E-3

H.CHK2

APPENDIX F
FILE HEADER BLOCK FORMAT

Table F-1 shows the format of the file header block.
The various
areas within the file header block are described in detail in the
following sections. The offset names in the file header block may be
defined either locally or globally, as shown in the following
statements:
FHDOF$

DEF$L

;DEFINE OFFSETS LOCALLY.

FHDOF$

DEF$G

;DEFINE OFFSETS GLOBALLY.
Table F-1
File Header Block

Area

Header Area

Size
(in Bytes)

Content

Offset

Identification area offset
in words

H. IDOF

Map area off set in words

H.MPOF-'-

File number

H.FNUM

File sequence number

H.FSEQ

Structure level and system
number

H.FLEV

Offset to file owner
information, consisting of
member number and group
number

H.FOWN

Member number

H.PROG

Group number

H.PROJ

File protection code

H.FPRO

User-controlled file
characteristics

H.UCHA

(continued on next page)

F-1

FILE HEADER BLOCK FORMAT
Table F-1 (Cont.)
File Header Block
Area

Identification
Area

Size
(in Bytes)

Offset

System-controlled file
characteristics

H.SCHA

32.

User file attributes

H.UFAT

Size in bytes of header
area of file header block

S.HDHD

File name (Radix-50)

I.FNAM

File type (Radix-50)

I.FTYP

File version number
(binary)

I.FVER

Revision number

I. RVNO

Revision date

I.RVDT

Revision time

I. RVTI

Creation date

I.CRDT

Creation time

I.CRT!

I Expiration date

Map Area

Content

.L. •

'C'VT"\m

.LIA.U .L

To round up to word
boundary
Size (1n bytes) of
identification area of
file header block

S. IDHD

Extension segment number

M.ESQN

Extension relative volume
number (not implemented)

M.ERVN

Extension file number

M.EFNU

Extension file sequence
number

M.EFSQ

Size (in bytes) of the
block count field of a
retrieval pointer (1 or 2) ;
only 1 is used

M.CTSZ

(continued on next page)

F-2

FILE HEADER BLOCK FORMAT
Table F-1 (Cont.)
File Header Block
Size
(in Bytes)

Area

Content

Offset

Size (in bytes) of the
logical block number field
of a retrieval pointer (2,
3, or 4); only 3 is used

M.LBSZ

Words of retrieval pointers
in use in the map area

M.USE

Maximum number of words
of retrieval pointers
available in the map area

M.MAX

Start of retrieval pointers

M.RTRV

Size in bytes of map area
of file header block

S.MPHD

Checksum of words 0 through
255

H.CKSM

Checksum Word

NOTE
The checksum word is the last word of
the
file
header
block.
Retrieval
pointers occupy the space from the end
of the map area to the checksum word.

F.l

HEADER AREA

The information in the header area of the file header
of the following:

block

consists

Identification area
off set

- Word O, Bits 0-7. This byte locates the start
of the identification area relative to the
start of the file header block. This offset
contains the number of words from the start of
the header to the identification area.

Map area off set

- Word O, Bits 8-15. This byte locates the start
of the map area relative to the start of the
file header block. This offset contains the
number of words from the start of the header
area to the map area.

File number

- The file number defines the position this file
header block occupies in the index file; for
example, the index file is number 1, the
storage bit map is file number 2, and so forth.

File sequence number - The file number and the file sequence number
constitute the file identification number used
by the system. This number is different each
time a header is reused.

F-3

FILE HEADER BLOCK FORMAT
Structure level

- This word identifies the system that created
the file and indicates the file structure. A
value of [1,1] is associated with all current
FILES-11 volumes.

File owner
information

- This word contains the group number and owner
number constituting the User Identification
Code (UIC) for the file.
Legal UICs are within
the range [1,1] to [377,377].
UIC [1,1]
is
reserved for the system.

File protection code - This word specifies the manner in which the
file can be used and who can use it. When
creating the file, you specify the extent of
protection desired for the file.
File characteristics - This word, consisting of two bytes, defines the
status of the file.
Byte 0 defines the user-controlled characteristics, as follows:
UC.CON = 200 - Logically contiguous
file.
When the file is extended (for example, by a
WRITE or PUT), bit UC.CON is cleared whether
or not the extension requests contiguous
blocks.
UC.DLK = 100 - File improperly closed.
Byte 1 defines system-controlled
tics, as follows:

characteris-

SC.MDL

200 - File marked for delete

SC.BAD

100 - Bad data block in file

User file
attributes

- This area consists of 16 words. The first
seven words of this area are a direct image of
the first seven words of the FDB when the file
is opened. The other nine words of the record
I/O control area are not used by FCS, although
RMS does use them.

F.2

AREA

IDENTIFICA~ION

The information in the identification area of the
consists of the following:
File name

file

header

block

- The file's creator specifies a file name of up
to nine Radix-SO characters in length. This
name is placed in the name field.
The unused
portion of the field (if any) is zero-filled.

File type

This word contains the file
format.

File version number

This word contains the file version number, in
binary, as specified by the creator of the
file.

F-4

type

Radix-50

FILE HEADER BLOCK FORMAT
Revision number

This word is initialized to 0 when the file
is
created;
it is incremented each time a file is
closed after being updated or modified.

Revision date

- Seven bytes are used to maintain the date on
which the file was last revised.
The revision
date is kept in ASCII form in the format day,
month, year
(two bytes, three bytes, and two
bytes, respectively).
This date is meaningful
only if the revision number is a nonzero value.

Revision time

- Six bytes are used to record the time at which
the file was last revised.
This information is
recorded in ASCII form in the format hour,
minute, and second (two bytes each).

Creation date

The date on which the file was created is kept
in a 7-byte field having the same format as
that of the revision date (see above).

Creation time

- The time of the file's creation is maintained
in a
6-byte field having the same format as
that of the revision time (see above) •

Expiration date

- The date on which the file becomes eligible to
be deleted is kept in a 7-byte field having the
same format as that of the rev1s1on date
(see
above).
Use of expiration is not implemented.

F.3

MAP AREA

The map area contains the information necessary to map virtual Qlock
numbers to logical block numbers.
This is done by means of pointers,
each of which points to an area of contiguous blocks.
A pointer
consists of a count field and a number field.
The count field defines
the number of blocks contained in the contiguous area pointed to, and
the logical block number (LBN) field defines the block number of the
first logical block in the area.
A value of n in the count field (see below) means that n+l blocks
allocated, starting at the specified block number.
The retrieval pointer format used in the FILES-11
shown below:
15

file
0

COUNT-1

HIGH LBN

LOW

LBN
ZK-303-81

F-5

structure

are
is

FILE HEADER BLOCK FORMAT
NOTE
in
this
The
remaining
paragraphs
appendix
apply
to !AS, and RSX-11
systems that support the multiheader
version of FllACP.
The map area normally has space for 102 retrieval pointers.
It can
map up to 102 discontiguous segments or up to 26112 blocks if the file
is contiguous.
If more retrieval pointers are required because the
file is too large or consists of too many discontiguous segments,
extension headers are allocated to hold additional retrieval pointers.
Extension headers are allocated within the
index file.
They are
identified by a file number and a file sequence as are other file
headers;
however, extension file headers do not appear in any
directory.
A nonzero value in the extension file number field of the map area
indicates that an extension header exists. The extension header is
identified by the extension file number and the extension file
sequence number.
The extension segment number is used to number the
headers of the file sequentially, starting with a 0 for the first.
Extension headers of a file contain a header area and identification
area that are a copy of the first header as it appeared when the first
extension was created.
Extension headers are not updated when the
first header of the file is modified.
Extension headers are created and handled by the
primitives as needed;
their use is transparent to you.

F-6

file

control

APPENDIX G
SUPPORT OF ANSI MAGNETIC TAPE STANDARD

This appendix defines the ANSI magnetic tape labeling standard, which
is a level three implementation of the ANSI standard Magnetic Tape
Labels and File Structure for
Information Interchange
(X3.27-1978).
The only exception is that ANSI does not support spanned records.

G.l

VOLUME AND FILE LABELS

Tables G-1, G-2, and G-3 present the format of volume labels and
header labels.

G.1.1

file

Volume Label Format
Table G-1
Volume Label Format

Character
Position

Field Name

Length
(in Bytes)

1-3

Label identifier

VOL

Label number

5-10

Volume identifier

Volume label. Any ANSI "a"
character. An "a" character
is defined by
the
ANSI
standard
as
any of the
uppercase letters A through
Z, the digits 0 through 9,
and the following special
characters:
space !
" % &
I
()
* + , - • I : ; <=> ?

Accessibility

Any ANSI "a" character.
A
space
indicates
no
restriction. The /ACCESS =
character switch to the IN!
command
allows
you
to
specify a character to be
placed in this
position.
Any ANSI "a" character is
permitted.
The
default
character is a space. Refer
to the RSX-llM/M-PLUS MCR
Operations Manual for more
information on INI.

Contents

(continued on next page)
G-1

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

Table G-1 (Cont.)
Volume Label Format
Character
Position

Field Name

Length
(in Bytes)

Contents

12-37

Reserved

Spaces.

38-51

Owner
identification

The contents of this field
are system dependent and are
used for volume protection
Section
purposes.
See
G.1.1.1 below.

52-79

Reserved

Spaces.

Label standard
version

1Z,
J

G.1.1.1 Contents of Owner Identification Field - The owner identification field is divided into the following three subfields and a
single pad character:
1.

System identification (positions 38 through 40)

Volume protection code (positions 41 through 44)

UIC (positions 45 through 50)

Pad character of one space (position 51)

The system
sequence:

identification

consists

the

following

character

D%x

x
The machine code, which can be one of the following:
8 A B F -

PDP-8
DECsystem-lo
PDP-11
PDP-15

The D%x characters provide an identification method so that the
remaining data in the owner identification field can be interpreted.
The /OWNER - switch to the IN! command allows you to overwrite these
characters.
(Refer to the RSX-llM/M-PLUS MCR Operations Manual for
more information.) In the case of tapes produced on PDP-11 systems,
the default system identification is D%B and the volume protection
code and UIC are interpreted as described below.

G-2

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
The volume protection code in positions 41 through 44 defines access
protection for the volume for four classes of users.
Each class of
user has access privileges specified in one of the four columns, as
follows:
Position

Class

41
42
43
44

System (UIC no greater than [7,255])
Owner (group and member numbers match)
Group (group number matches)
World (any user not in one of the above)

One of the following access codes can be specified for each
position:
Code

Privilege

No access
Read only
Extend (append) access
Read/extend access
Total access

1
2
3
4

character

The UIC is specified in character positions 45 through 50.
The first
three characters are the group code in decimal.
The next three are
the user code in decimal.
The last character in the owner identification field is a space.

The following is an example of the owner identification
Owner identifier - D%Bl410051102
1.

The file was created on a PDP=ll.

System and group have read access.
Owner has total access.
All others are denied access.

The UIC is [051,102].

G.1.2

indicates space)

User Volume Labels
passed

back

you.

The following information should be kept in mind
header labels.

when

creating

file

User volume labels are never
present, they are skipped.

G.1.3

written

File Header Labels

•

The Files-11 naming convention uses a subset (Radix-50) of the
available ANSI character set for file identifiers.

•

One character in the file identifier, the period (.), is fixed
by Files-11.

•

A maximum of 13 of the 17 bytes in
processed by Files-11.

G-3

the

file

identifier

are

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
•

It is strongly recommended that all file identifiers be
limited to the Radix-SO PDP-11 character set, and that no
character other than the period {.) be used in the file type
delimiter position for data interchange between PDP-11 and
DECsystem-10 systems.

•

For data interchange between DIGITAL and non-DIGITAL systems,
the conventions listed above should be followed.
If they are
not, refer to Section G.1.3.1.

Tables G-2 and G-3 describe the HDRl and HDR2 labels, respectively.
Table G-2
File Header Label (HDRl)
Field Name

Length
(in Bytes)

1-3

Label identifier

HDR

Label number

5-21

File identifier

Any ANSI "a" character.
Table G-1.

22-27

File set
identifier

Volume
identifier
first volume in the
volumes.

Character
Position

Contents

I 28-31
I
I
I

File section
number

II Numeric

See

of the
set of

This I
is I
by 1 for each I
volume used by

characters.

I field starts at 0001 and

I increased

additional
I the file.

I
I

32-35

File sequence
number

36-39

IGeneration number

File
number
within
the
volume set for this file.
This number starts at 0001.
I

I
I

Numeric characters.

40-41

Generation version

Numeric characters.

42-47

Creation date

48-53

Expiration date

Same format
date.

Accessibility

Space.

55-60

Block count

000000

61-73

System code

The
three
letters
DEC,
followed by the name of the
system that produced
the
volume.
See
Section
G.1.1.1.

I
I
I

yyddd (

indicates space)
or
00000 if no date.
-

Examples:

creation

DECFILEllA
DECSYSTEMlO

Pad name with spaces.
74

!Reserved

G-4

Spaces.

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
Table G-3
File Header Format (HDR2)

r Character
Position

Length
(in Bytes)

Field Name
l

Contents
l

IHDR

Label number

Record format

F D s u -

1-3

Label identifier

Fixed length
Variable length
Spanned
Undefined

6-10

Block length

Numeric characters.

11-15

Record length

Numeric characters.

16-50

System-dependent
information

Positions 16 through 36 are

lspa~e~.

Pos1t1on 37 defines carriage
control and can contain one
of the following:
A

- First
byte
of
contains
record
FORTRAN
control
characters.

space - line
feed/carriage
return is to be
inserted between
records.

- the
record
contains all form
control
information.

If DEC appears in positions
61
through
63 of HDRl,
position 37 must
as
be
specified above.

Positions 38
through
contain spaces.

51-52

Buffer offset

Numeric characters.
00 on
tapes produced by Files-11.
Supported only on input to
Files-11.

53-80

Reserved

Spaces.

G-5

I
I

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
Table G-4
File-Header Label {HDR3)
Character
Position

Field Name

Length
{in Bytes)

1-3

Label identifier

HOR

Label number

5-68

System-dependent

File attributes specified
at creation time. Each
of the 32 bytes of user
file attributes is
expanded into two
hexadecimal characters.

69-80

Reserved

Spaces.

Contents

G.1.3.1 File Identifier Processing by Files-11 - The magnetic
tape
ACP processes Files-11 type file identifiers as described below.
However, if the file name is enclosed in quotes, it is processed as an
ANSI file name, all "a" characters are legal, all 17 positions may be
used, and the only conversion that takes place is the upcasing of all
lowercase characters and the convetsion of all characters that are not
"a" characters to question marks.
At file input, the file identifier is handled as follows:
1.

The first nine characters at a maximum are processed by an
ASCII to Radix-SO converter. The conversion continues until
one of the following occurs:
a. A conversion failure.
b. Nine characters are converted.
c. A period (.)

is encountered.

If the period is encountered, the next three characters after
the period are converted and treated as the file type. If a
failure occurs or all nine characters are converted, the next
character is examined for a period. If it is a period, it is
skipped and the next three characters are converted and
treated as the file type.

The version number is derived from the generation number
the generation version number as follows:

and

(generation number - 1)*100 +generation version+ 1
If an invalid version number is computed, it will be
to 1.

G-6

changed

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
At file output, the file identifier is handled as follows:
1.

The file name is placed in the first positions in the file
identifier field.
It can occupy up to nine positions and is
followed by a period.

The file type of up to three characters is placed after
period. The remaining spaces are padded with spaces.

the

The version number is then placed in the generation
generation
version number fields, as described in
following formulas:

and
the

Generation number ={version# \
100

i)+ 1
I

Generation version# =(version# - ~Modulo 100

NOTE
In both
ignored.

calculations,

remainders

are

The following are examples.
FILES-11 Version No.

G.1.4

Generation No.

Generation Version No.

50
100
101

1
1

49
99

1010

End-of-Volume Labels

End-of-volume labels are identical to the file header labels with
following exceptions:

the

Character positions 1 through 4 contain EOVl and EOV2 instead
of HDRl and HDR2, respectively.

The block count field contains the number of records
last file section on the volume.

G.1.5

the

with

file

File Trailer Labels

End-of-file labels (file trailer labels)
are
header labels, with the following exceptions:

identical

Columns 1 through 4 contain EOFl and EOF2 instead of HDRl and
HDR2, respectively.

The block count contains the number of
file.

G-7

data

blocks

the

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
G.l.~

User File Labels

User file labels are never written or passed back to you.
they are skipped.

G.2

If present,

FILE STRUCTURES

The file structures illustrated below are the types of file and volume
combinations that the file processor produces. The file processor can
read and process additional sequences.
The minimum block size and fixed-length record size is 18 bytes.
maximum block size is 8192 bytes.

The

If HDR2 is not present, the data type is assumed to be fixed {F), and
the block size and record size are assumed to be the default value for
the file processor.
512 decimal bytes is the default for both block
and record size. You can override these defaults with the MAG command
{see Section G.5).
The meaning of graphics used in the file structure illustrations is as
follows:

G.2.1

The asterisk {*) indicates a tape mark. As defined by ANSI,
a tape mark is a special control block recorded on magnetic
tape to serve as a separator between files and file labels.

BOT indicates beginning of tape.

EOT indicates end of tape.

The comma {,)

indicates the physical record delimiter.

Single File Single Volume
BOT,VOL1,HDR1,HDR2,HDR3*---DATA---*EOF1,EOF2**

G.2.2

Single File Multivolume
BOT,VOL1,HDR1,HDR2,HDR3*---DATA---*EOV1,EOV2**
BOT,VOL1,HDR1,HDR2,HDR3*---DATA---*EOF1,EOF2**

G.2.3

Multifile Single Volume
BOT,VOL1,HDR1,HDR2,HDR3*---DATA---*EOF1,EOF2*HDR1,HDR2,HDR3*---DATA
--*EOF1,EOF2**

G.2.4

Multifile Multivolume
BOT,VOLl,HDRl,HDR2,HDR3*--DATA--*EOFl,EOF2*HDRl,HDR2,HDR3*--DATA--*
EOV1,EOV2**
BOT,VOL1,HDR1,HDR2,HDR3*--DATA--*EOF1,EOF2*HDR1,HDR2,HDR3*--DATA--*
EOF1,EOF2**

G-8

G.3

END-OF-TAPE HANDLING

End-of-tape is handled automatically by the magnetic tape file
processor.
Files are continued on the next volume provided that the
volume is already mounted or mounted upon request. A request for the
next volume is printed on CO:
(console output pseudo-device).

G.4

ANSI MAGNETIC TAPE FILE HEADER BLOCK (FCS COMPATIBLE)

Figure G-1 illustrates the format of a file header block that is
returned by the file header READ ATTRIBUTE command for ANSI magnetic
tape.
The header block is constructed by the magnetic tape primitive
from data within the tape labels.

H.MPOF

r~-----F-1

MAP OFFSET

IDENT OFFSET

L_E_S_E_o_u_E_N_C_E_N_U_M_B_E_R_ _ _ _ _---i

I l~I-----~-~-:-.~-:-:-.~-:-:-'~-:-"-:-~-M-~-:-~-,0-1---------1
;::>1 nUvl u n c LCVCL = ... Ul\01

UIC (FOR VOLUME)

HEADER AREA

l
i

H.FNUM
H.FSEQ

H.FLEV
H.FOWN=H.PROG

PROTECTION CODE (FOR VOLUME)

H.FPRO

H.UFAT

RECORD ATTRIBUTES

H.IDOF

RECORD TYPE CODE

RECORD SIZE IN BYTES

l
I
I

N WORDS OF ZERO'S

IDENTIFICATION AREA

Fl LE NAME RADSO

X+l.FNAM
(IDENT OFFSET *2)=X

Fl LE TYPE RADSO

1.FTYP

FILE VERSION NUMBER

X+l.FVER

ZERO'S (REVISION DATE & TIME)

X+l.RVNO

CREATION DATE & TIME (000000)

X+l.CRDT

EXPIRATION DATE

X+l.EXDT

PAD BYTE OF 0

X+47.

COPY OF THE
HDR1 LABEL

X+SO.

COPY OF THE HDR2 LABEL
(if byte 1 of label = 0,
label is not present)

X+130.

>------------------------

MAP AREA

lr _
l·

------N-U-LL_·_M_A_P_._1.E_._._zE_R_o_·_s
_ _ _ _ _____,
(10 BYTES LONG)

X+210.=
(MAP OF OFFSET 2)
ZK-315-81

Figure G-1

ANSI Magnetic Tape File Header Block (FCS Compatible)

G-9

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
G.5

THE MAGNETIC TAPE CONTROL TASK

The Magnetic Tape Control Task
(MAG}
allows you to specify file
attributes for unlabeled tapes, provides positioning functions for
both unlabeled and ANSI tapes, and allows you to respond to requests
for new tapes or volumes without mounting a new tape.
This command can only be used on mounted tapes.
The keywords
valid for both unlabeled and ANSI tapes, unless otherwise noted.

are

The format of the MAG command is as follows:
>MAG SET mmnn:/keyword[/keyword[s]]
Keywords:
/BS=number-of-characters
/CC=NONE
LIST
FORTRAN
/EOF
/EQT
/EOV
/INITIALIZE="volume id"
/POS=number-of-files
/RS=number-of-characters
/REWIND
mmnn:
Magnetic tape unit on which the operation is to be performed.
Keyword definitions:
BS

/BS=number-of-bytes. Number of
per block on a mounted tape.
number of characters in either
To specify a decimal number,
period. The default is octal.

characters
(bytes}
You can specify the
decimal or octal.
terminate it with a

This block size becomes.the default for the tape.
This value is used on output when there is no HDR2
label present on an ANSI magnetic tape, and is used
on output when no other value was specified on
creation of the file.
The value specified for block size must be greater
than 14 {decimal} bytes. There is no maximum block
size.
See Section 1.3 for magnetic tape buffer sizes.

G-10

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

/CC=type of carriage control. The default type of
carriage control for the tape.
Valid types of
carriage control are as follows:
NONE
LIST
FORTRAN
When reading from an
control is used if:

ANSI

tape,

this

carriage

•

No HDR2 label is present.

•

The
HDR2
label
contains
a
identification other than DEC or OS.

system

If a HDR2 label is present, the information in the
HDR2 label is used and the /CC keyword is ignored.
This keyword is the only way
control for unlabeled tapes.
EOF

specify

carriage

/EOF. Causes the ACP to return the I/O status code
IE.EOF to the requesting task. This keyword can be
used to terminate a request for another tape in a
volume set.
This keyword is only valid for ANSI tapes.

EQT

/EOT. Causes the ACP to return the I/O status code
IE.EQT to the requestina task. This keyword can be
used to terminate a request f~r another tape in a
volume set.
This keyword is only valid for ANSI tapes.

EOV

/EOV. Causes the ACP to return the I/O status code
IE.EOV to the requesting task. This keyword can be
used to terminate a request for another tape in a
volume set.
This keyword is only valid for ANSI tapes.

INITIALIZE

/INITIALIZE="volume id". The volume label to which
the tape will be initialized. This keyword allows
you to create a new volume to satisfy a request
from the ACP for a new output volume for an ANSI
tape. The format of the volume identifier is
identical to the format of the volume identifier
specified for the Mount command.
Refer to the
RSX-llM/M-PLUS
MCR
Operations
Manual or the
RSX-llM/M-PLUS Command Language Reference Manual
for details.
This keyword is only valid for ANSI tapes.

POS

/POS=number of files. The number of files (tape
marks) to be spaced over from the current tape
position. For example, /POS=O means access the
current file; /POS=l means space forward one file
from the current position. The number of files may
be specified in either decimal or octal.
To
specify a decimal number, terminate the number with
a period. The default is octal.

G-11

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
The number of files specified must be between 0 and
23417(octal).
This keyword is only valid for mounted unlabeled
tapes.
This keyword is not necessary for labeled
tapes, since files can be accessed by name.
If a tape containing ANSI or IBM labels is mounted
as unlabeled, the formula to calculate the position
of a data file is:
N= (N-1)*3+1
where N is the number of the desired file.
RS

/RS=number of characters. The number of characters
per record for fixed-length records on tape.
Maximum record size is the block size.
When reading files from an ANSI tape, this value is
used for record size when no HDR2 label is present.
This keyword is the only way to specify record size
for unlabeled tapes.

REWIND

Specifies that the tape is to be rewound
/REWIND.
to BOT.
For ANSI tapes, this keyword rewinds to
the beginning of the volume set.

Example:

>MOU MMO:/NOLABEL/TR=EBCDIC
>MAG SET MMO:/BS=80./RS=80./CC=LIST/REWIND
>! Read the first "file" on the tape to determine the actual tape format
>PIP TI:=MMO:X
VOL1X234870
NASHUA
HDR1DEC2.KP72132
X2348700010001
80256 802860000000IBM OS/VS 370
HDR2F008000008030DEC2K009/DEC2U009
B
60337
>! This information shows that the tape in fact has labels that
>! resemble ANSI labels (this tape is in the format of
>! another computer manufacturer). The actual block size and record size
>! can be determined from the labels.
>! Use the MAG SET command to set the actual block and record size.
>MAG SET MMO:/BS=800./RS=80.
>! Use the MAG SET /POS command to positon to the next file on the tape
>! You could also position to the file by specifying
>! a position to PIP as follows: PIP TI:=MMO:"POS=Rl"
>! where R indicates Rewind and 1 is the number of tape
>! marks to space over.
>MAG SET MMO:/REWIND/POS=l
>! Read the data file. Note that PIP requires a dummy file name, even
>! though the tape is already positioned at the correct file.
>PIP TI:=MMO:X
MERRIMACK
603
001
321
03054
NASHUA
603
002
456
03060
NEWTON
617
003
789
02165
NORTH ANDOVER
617
004
124
01845
714
JOPLIN
005
345
64801

G-12

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
Command Error Messages:
MAG -- Device not mounted or mounted foreign
Explanation: Specified device must be either a mounted ANSI tape
or a mounted unlabeled tape.
A foreign tape that is mounted
foreign is not known to the magnetic tape ACP and is therefore
the same as an unmounted tape.
The MAG command only supports
mounted tapes.
User Action: Mount the device with the /NOLABEL qualifier if it
is an unlabeled tape. Do not use the MAG command with tapes that
are mounted foreign.
MAG -- Get command line failure
Explanation: An illegal indirect command file name was specified
or MAG could not find the specified indirect command file.
User Action: Check the specification for
file and reenter the command line.

the

indirect

command

that

required

both

MAG -- Illegal combination of keywords
Explanation: Keywords were specified
unlabeled tape and an ANSI tape.

User Action: Refer to the keyword descriptions in this chapter
to determine which switches require ANSI tapes and which require
unlabeled tapes.
MAG -- Illegal file attributes combination
Explanation: A record size was specified that was not less
or equal to the block size.

than

User Action:
block size.

the

retype

the

Specify a record size less than

equal

MAG -- Illegal switch value
Explanation:

One of the following:

•

/POS value was greater than 9999.

•

/BS value was less than 14.

•

/RS value was less than 14.

User Action: Determine which value was illegal
command line.

and

MAG -- Invalid device or unit
Explanation: Specified
magnetic tape.

device

does

not

exist

not

User Action: Determine the correct device or unit and retype the
command line.

G-13

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
MAG -- Operation is only valid for mounted ANSI tapes
Explanation: An operation that is only valid for
tape was attempted on an unlabeled tape.
User Action:

ANSI

magnetic

Use only valid commands.

MAG -- Operation is only valid for unlabeled tapes
Explanation: An operation that is only valid for unlabeled tapes
was attempted on an ANSI tape.
User Action:

Use only valid commands.

MAG -- Privilege violation
Explanation: On systems with multiuser protection, only the
terminal to which the tape drive is allocated may change the tape
characteristics.
User Action:
tape drive.

Reenter the command from the terminal that owns the

MAG -- Requested operation inconsistent with tape state
Explanation~
The user specifi~a /EOF,
magnetic tape ACP rejected it.

/EOV,

iEOT

and

the

type

only

this

or
The user specified /INITIALIZE and the ACP rejected it.
User Action: Determine the state of the tape and
commands that can be performed in the current state.

MAG -- Syntax error
Explanation:

The command was specified incorrectly.

User Action: Check the correct syntax as
chapter, and then reenter the command line.

G.6

described

UNLABELED TAPE

A tape that contains no labeling information is called an unlabeled
tape.
An unlabeled tape contains either blocked or unblocked
fixed-length records. When a tape is mounted with the /NOLABEL
qualifier on the MOUnt command, FCS and RMS can access records on the
tape using standard read and write operations. This is different from
mounting a tape foreign (MOU/FOREIGN). When a tape is mounted foreign
(or not mounted at all on RSX-llM systems) , records on the tape must
be accessed directly using the QIO operations that are defined for the
magnetic tape driver.

G-14

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
G.6.1

Tape Positioning

Any tape motion before the first read operation
requested in one of the following ways:

must

explicitly

•

The FA.ENB!FA.RWD bit may be set in F.ACTL to request a rewind
of the volume set prior to create or find-file operations.

•

The MAG SET /POS command may be specified to space
specified number of files from 0 to 9999.

forward

•

The MAG SET /REWIND command may be
tape to BOT.

rewind

•

The file mav be referenced by the name "POS=[R] [nnnn]" where R
indicates that the tape is to be rewound, and nnnn is the
number of files (tape marks) to space forward.
For example,
to read the second file on a tape:

specified

a
the

>PIP TI:=MM:"POS=OOOl"
Each tape mark delimits a file.
All positioning operations are in
terms of tape marks.
If any type of label is present on the tape, it
will be treated as a file.
When a file
consistent.

G.6.2

deaccessed,

position

within

the

file

always

Specifying File Attributes

You can specify the attributes for files to be read from tape in three
ways:

G.6.3

The MOUnt command
(see the RSX-llM/M-PLUS MCR Operations
Reference Manual or the RSX-llM/M-PLUS CoITiiliand Language
Reference Manual) •

Any create operation request.
You can issue the create
request from within your program by creating a file and
closing it without writing any data, or by using the RMS
DEFINE utility.
The FCS create routine returns the error
code IE.BTP (bad record type} if an attempt is made to set
the record type to anything other than fixed length.

The MAG SET command (see Section G.5).

Translation

You can request translation for a tape at the time it is mounted
(see
the
RSX-llM/M-PLUS
MCR
Operations
Reference
Manual
or the
RSX-llM/M-PLUS Command-r:anguage Reference Manual).
if you have
requested translation, your data buffer (the FCS or RMS block buffer)
is translated within your task.
Therefore, on a write operation, the
data in your task is destroyed.

G-15

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
You can add up to three installation-dependent translation routines to
the magnetic tape ACP by adding routines with the following format:
USERn:: MOV #TBLPTR,RO
;n is 1, 2, or 3.
RETURN
TBLPTR: .WORD INTRAN
.WORD OUTRAN
INTRAN: <A 256 byte table for input translation>
OUTRAN: <A 256 byte table for output translation>
For example, the EBCDIC translation tables that are provided with your
system are shown in section G.6.4.
You must include these translation routines in the Overlay Description
Language
(ODL)
for the magnetic tape ACP when the MTAACP task is
built. Comments within the files MTABLD.ODL and MTABLD.CMD indicate
where these routines may be added.

G.6.4

Example of EBCDIC Translation Tables
EBCDIC::

MOV
RETURN

TBLPTR: .WORD
.WORD

EBCASC
ASCEBC

#TBLPTR,RO

.NLIST BEX
;

EBCASC: .BYTE
.BYTE
.BYTE
.BYTE
.BYTE
• BYTE
.BYTE
.BYTE
.BYTE
.BYTE
• BYTE
.BYTE
.BYTE
.BYTE
.BYTE
• BYTE
.BYTE
.BYTE
.BYTE
.BYTE
• BYTE
.BYTE
.BYTE
.BYTE
.BYTE
• BYTE

000,001,002,003,040,0ll,040,177,040,040
040,013,014,015,016,017,020,021,022,023
040,040,010,040,030,031,040,040,040,035
040,037,040,040,034,040,040,0l2,027,033
040,040,040,040,040,005,006,007,040,040
026,040,040,036,040,004,040,040,040,040
024,025,040,032,040,040,040,040,040,040
040,040,040,040,133,056,074,050,053,135
046,040,040,040,040,040,040,040,040,040
041,044,052,051,073,136,055,057,040,040
040,040,040,040,040,040,174,054,045,137
076,077,137,040,040,040,040,040,040,040
040,140,072,043,100,047,075,042,040,141
142,143,144,145,146,147,150,151,040,040
040,040,040,040,040,152,153,154,155,156
157,160,161,162,040,040,040,040,040,040
040,176,163,164,165,166,167,170,171,172
040,040,040,040,040,040,040,040,040,040
040,040,040,040,040,040,040,040,040,040
040,040,173,101,102,103,104,105,106,107
110,lll,040,040,040,040,040,040,175,112
113,114,115,116,117,120,121,122,040,040
040,040,040,040,134,040,123,124,125,126
127,130,131,132,040,040,040,040,040,040
060,061,062,063,064,065,066,067,070,071
040,040,040,040,040,040

G-16

50 •

100 •

150 •

200 •

250 •

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

ASCEBC: .BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE

;.7

000,001,002,003,067,055,056,057
026,005,045,013,014,015,016,017
020,021,022,023,074,075,062,046
030,031,077,047,042,035,065,037
100,132,177,173,133,154,120,175
115,135,134,116,153,140,113,141
360,361,362,363,364,365,366,367
370,371,172,136,114,176,156,157
174,301,302,303,304,305,306,307
310,311,321,322,323,324,325,326
327,330,331,342,343,344,345,346
347,350,351,112,340,117,137,155
171,201,202,203,204,205,206,207
210,211,221,222,223,224,225,226
227,230,231,242,243,244,245,246
247,250,251,300,152,320,241,377

100

140

EXAMPLE USING AN INDIRECT COMMAND FILE TO READ A TAPE
.ENABLE QUIET
.ENABLE SUBSTITUTION
., This command file is invoked with the command
@MTA outspec=Mx:infile
'
., and searches a tape mounted unlabeled (which has an ANSI-like structure)
., for the file "infile" and copies it to outspec •

.
..,' Parse the command line; OUTSPC gets outspec,
.;

DEV

gets Mx,

.,
INFILE gets the file name to find on tape •
• PARSE COMMAN " " OUTSPC COMMAN
.PARSE COMMAN "=" OUTSPC INSPEC
.PARSE INSPEC ":" DEV INFILE
.IF INFILE EQ "" .GOTO NOTMT
.SETS INFILE INFILE+"
.SETS INFILE INFILE[l:l7.]
.SETS JUNK DEV[l:l]
.IF JUNK NE "M" .GOTO NOTMT

..;' Make a name for the temp file
..TESTFILE
'
TI:
.PARSE <FILSPC> ":" TMP JUNK
.SETS TMP TMP+".TMP"

..;' Always start at the beginning of the tape:

MAG SET 'DEV':/REWIND
•

.; Labels have a block and record size of 80.
MAG SET 'DEV':/BS:80./RS:80 •
• LOOK:

..;' Put the labels in a temp file so INDirect can look at them

PIP 'TMP'='DEV':DUMMY.NAM
.OPENR 'TMP'
.READLB:
.READ LABEL
.IFT <EOF> .GOTO NOSUCH
.SETS LABELT LABEL[l:3]

G-17

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

..,, Skip any VOLume header labels
.IF LABELT = "VOL" .GOTO READLB
.IF LABELT NE "HDR" .GOTO ILLFMT
.SETS LABELT LABEL[4:4]
.IF LABELT NE "l" .GOTO ILLFMT
.SETS LABELT LABEL[5:21.]

.,
.; If the names do not match, go get the next set of labels •
.• IF, LABELT NE INFILE .GOTO TRYNXT

.; We have found the file, see if there is a HDR2 with size info •
• READ LABEL
.!FT <EOF> .GOTO READFL
.SETS LABELT LABEL[l:4]
.IF LABELT NE "HDR2" .GOTO READFL

..;, Yes, we have a HDR2 label •

• SETS LABELT LABEL[37.:37.]
.SETS CC "LI"
.IF LABELT = "A" .SETS CC "FO"
.IF LABELT = "M" .SETS CC "NO"
.SETS BS LABEL[6:10.]
.SETS RS LABEL[ll.:15.]

..;, Set up the Block Size, Record Size, and Carriage Control

.; Based on what was in HDR2.
MAG SET 'DEV':/BS:'BS'./RS:'RS'./CC:'CC'
.SETS LABELT LABEL[S:S]
.IF LABELT EQ "F" .GOTO READFL
• DISABLE QUIET
!MTA - Warriing, Record Format is :LABELT;; only r' r'ormat is fully supported •
• ENABLE QUIET
• READFL:
.CLOSE

..;, Transfer the file.

PIP 'OUTSPC'='DEV' :"POS=l"
.GOTO ENDIT
.TRYNXT:
.CLOSE
MAG SET 'DEV':/POS=3
.GOTO LOOK
.ILLFMT:
.DISABLE QUIET
.DISABLE MCR
MTA - Tape is not in a format that I understand •
• GOTO ENDIT
.NOTMT:
• DISABLE QUIET
• DISABLE MCR
MTA - Input file spec must specify a Magtape device and a file name •
• EXIT
.NOSUCH:
.DISABLE QUIET
.DISABLE MCR
MTA - No such file -- 'INSPEC'
.ENDIT:
.ENABLE MCR
• ENABLE QUIET
PIP 'TMP'; /DE/NM
.EXIT
-

G-18

APPENDIX H
STATISTICS BLOCK

The format of the statistics block is shown in Figure H-1 below.
The
statistics block is allocated manually in your program as described in
item 3.d of Section 3.1.2.

Word 0

I Word 1

HIGH LOGICAL BLOCK NUMBER
(0 if file is noncontiguous)
LOW LOGICAL BLOCK NUMBER
(0 if file is noncontiguous)

Word 2

SIZE (high)

Word 3

SIZE (low)

Word4
LOCK COUNT

ACCESS COUNT
ZK-304-81

Figure H-1

Statistics Block Format

H-1

APPENDIX I

ERROR CODES

This appendix lists:
•

I/O error codes

•

Directive Status Word error codes

•

I/O function codes
.TITLE

QIOMAC - QIOSYM MACRO DEFINITION

DATE OF LAST MODIFICATION:
John R. Covert

29-Jul-81

***** ALWAYS UPDATE THE FOLLOWING TWO LINES TOGETHER
.!DENT /0351/
QI.VER=0351
COPYRIGHT (C) 1980
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A
SINGLE COMPUTER SYSTEM AND MAY BE COPIED
ONLY WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE.
THIS SOFTWARE,
OR
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE
MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE WHO AGREES ~O THESE LICENSE TERMS. TITLE
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN
IN DEC.
THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC.
PETER H. LIPMAN l-OCT-73

I-1

ERROR CODES
;

;+
MACRO TO DEFINE STANDARD QUEUE I/O DIRECTIVE FUNCTION VALUES
AND IOSB RETURN VALUES. TO INVOKE AT ASSEMBLY TIME (WITH LOCAL
DEFINITION} USE:
; DEFINE SYMBOLS

QIOSY$

TO OBTAIN GLOBAL DEFINITION OF THESE SYMBOLS USE:
QIOSY$ DEF$G

;SYMBOLS DEFINED GLOBALLY

THE MACRO CAN BE CALLED ONCE ONLY AND THEN
REDEFINES ITSELF AS NULL.
;-

.MACRO QIOSY$ $$$GBL,$$$MSG
.GLOBL QI.VER
.IIF
IDN,<$$$GBL>,<DEF$G>,
.IF
IDN,<$$$MSG>,<DEF$S>
$$$MAX=O
$$MSG=l
.IFF
$$MSG=O
.ENDC
.MCALL IO ERR$
IO ERR$ $$$GBL
;I/O ERROR CODES FROM HANDLERS, FCP, FCS
.MCALL DRERR$
DRERR$ $$$GBL
;DIRECTIVE STATUS WORD ERROR CODES
.IF
DIF,<$$$MSG>,<DEF$S>
.MCALL FI LIO$
FI LIO$ $$$GBL
;DEFINE GENERAL I/O FUNCTION CODES
.MCALL
SPCIO$ $$$GBL
;DEVICE DEPENDENT I/O FUNCTION CODES
.MACRO QIOSY$ ARG,ARG1,ARG2
;RECLAIM MACRO STORAGE
.ENDM
QIOSY$
• ENDC
QIOSY$
.ENDM
DEFINE THE ERROR CODES RETURNED BY DEVICE HANDLER AND FILE PRIMITIVES
IN THE FIRST WORD OF THE I/O STATUS BLOCK
THESE CODES ARE ALSO RETURNED BY FILE CONTROL SERVICES (FCS) IN THE
BYTE F.ERR IN THE FILE DESCRIPTOR BLOCK (FDB)
THE BYTE F.ERR+l IS 0 IF F.ERR CONTAINS A HANDLER OR FCP ERROR CODE •
• ENABL

.MACRO IOERR$ $$$GBL
.MCALL .IOER.,DEFIN$
.IF
IDN,<$$$GBL>,<DEF$G>
••• GBL=l
.IFF
e • • GBL=O
• ENDC
.!IF
NDF,$$MSG,$$MSG=O

I-2

ERROR CODES
SYSTEM STANDARD CODES, USED BY EXECUTIVE AND DRIVERS
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.

• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
.IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.

• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.

IE.BAD,-01.,<Bad parameters>
IE.IFC,-02.,<Invalid function code>
IE.DNR,-03.,<Device not ready>
IE.VER,-04.,<Parity error on device>
IE.ONP,-05.,<Hardware option not present>
IE.SPC,-06.,<Illegal user buffer>
IE.DNA,-07.,<Device not attached>
IE.DAA,-08.,<Device already attached>
IE.DUN,-09.,<Device not attachable>
IE.EOF,-10.,<End of file detected>
IE.EOV,-11.,<End of volume detected>
IE.WLK,-12.,<Write attempted to locked unit>
IE.DA0,-13.,<Data overrun>
IE.SRE,-14.,<Send/receive failure>
IE.AB0,-15.,<Request terminated>
IE.PRI,-16.,<Privilege violation>
IE.RSU,-17.,<Sharable resource in use>
IE.OVR,-18.,<Illegal overlay request>
IE.BYT,-19.,<0dd byte count (or virtual address)>
IE.BLK,-20.,<Logical block number too large>
IE.MOD,-21.,<Invalid UDC module#>
IE.CON,-22.,<UDC connect error>
IE.BBE,-56.,<Bad block on device>
IE.STK:-58.,<Not enough stack space (FCS or FCP)>
IE.FHE,-59.,<Fatal hardware error on device>
IE.EOT,-62.,<End of tape detected>
IE.OFL,-65.,<Device off line>
IE.BCC,-66.,<Block check, CRC, or framing error>
IE.NFW,-69.,<Path lost to partner> ;THIS CODE MUST BE ODD
IE.NDR,-72.,<No dynamic space available> ; SEE ALSO IE.UPN
IE.TM0,-95.,<Timeout on request>
IE.CNR,-96.,<Connection rejected>

FILE PRIMITIVE CODES
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
• IOER.
.IOER.
• IOER.
. IOER.
• IOER.
• IOER.
• IOER.

IE.NOD,-23.,<Caller's nodes exhausted>
IE.DFU,-24.,<Device full>
IE.IFU,-25.,<Index file full>
IE.NSF,-26.,<No such file>
IE.LCK,-27.,<Locked from read/write access>
IE.HFU,-28.,<File header full>
IE.WAC,-29.,<Accessed for write>
IE.CKS,-30.,<File header checksum failure>
IE.WAT,-31.,<Attribute control list format error>
IE.RER,-32.,<File processor device read error>
IE.WER,-33.,<File processor device write error>
IE.ALN,-34.,<File already accessed on LUN>
IE.SNC,-35.,<File ID, file number check>
IE.SQC,-36.,<File ID, sequence number check>
IE.NLN,-37.,<No file accessed on LUN>
IE.CL0,-38.,<File was not properly closed>
IE.DUP,-57.,<ENTER - duplicate entry in directory>
IE.BVR,-63.,<Bad version number>
IE.BHD,-64.,<Bad file header>

I-3

ERROR CODES
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.

IE.EXP,-75.,<File expiration date not reached>
IE.BTF,-76.,<Bad tape format>
IE.ALC,-84.,<Allocation failure>
IE.ULK,-85.,<Unlock error>
IE.WCK,-86.,<Write check failure>
IE.DSQ,-90.,<Disk ~uota exceeded>

FILE CONTROL SERVICES CODES
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.

IE.NBF,-39.,<0PEN - no buffer space available for file>
IE.RBG,-40.,<Illegal record size>
IE.NBK,-41.,<File exceeds space allocated, no blocks>
IE.ILL,-42.,<Illegal operation on file descriptor block>
IE.BTP,-43.,<Bad record type>
IE.RAC,-44.,<Illegal record access bits set>
IE.RAT,-45.,<Illegal record attributes bits set>
IE.RCN,-46.,<Illegal record number - too large>
IE.2DV,-48.,<Rename - 2 different devices>
IE.FEX,-49.,<Rename - new file name already in use>
IE.BDR,-50.,<Bad directory file>
IE.RNM,-51.,<Can't rename old file system>
IE.BDI,-52.,<Bad directory syntax>
IE.FOP,-53.,<File already open>
IE.BNM,-54.,<Bad file name>
IE.BDV,-55.,<Bad device name>
IE.NFI,-60.,<File ID was not specified>
IE.ISQ,-61.,<Illegal sequential operation>
IE.NNC,-77.,<Not ANSI 'D' format byte count>

NETWORK ACP, PSI, AND DECDATAWAY CODES
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.

IE.NNN,-68.,<No such node>
IE.BLB,-70.,<Bad logical buffer>
IE.URJ,-73.,<Connection rejected by user>
IE.NRJ.-74.~<Connection rejer.ted by network>
IE.NDA,-78.,<No data available>
IE.IQU,-91.,<Inconsistent qualifier usage>
IE.RES,-92.,<Circuit reset during operation>
IE.TML,-93.,<Too many links to task>
IE.NNT~-94.!<Not a network task>
IE.UKN,-97.,<Unknown name>

ICS/ICR ERROR CODES
.IOER.
.IOER.
.IOER.

IE.NLK,-79.,<Task not linked to specified ICS/ICR interrupts>
IE.NST,-80.,<Specified task not installed>
IE.FLN,-81.,<Device offline when offline request was issued>

TTY ERROR CODES
.IOER.
.IOER.

IE.IES,-82.,<Invalid escape sequence>
IE.PES,-83.,<Partial escape sequence>

I-4

ERROR CODES
RECONFIGURATION CODES
.IOER.
.IOER.

IE.ICE,-47.,<Internal consistancy error>
IE.ONL,-67.,<Device online>

PCL ERROR CODES
• IOER.
• IOER.
• IOER.

IE.NTR,-87.,<Task not triggered>
IE.REJ,-88.,<Transfer rejected by rece1v1ng CPU>
IE.FLG,-89.,<Event flag already specified>

SUCCESSFUL RETURN CODES--DEF IN$
DEF IN$
DEF IN$

IS.PND,+00.
IS.SUC,+01.
IS.RDD,+02.

DEF IN$

IS.TNC,+02.

DEF IN$

IS.DA0,+02.

;OPERATION PENDING
;OPERATION COMPLETE, SUCCESS
;FLOPPY DISK SUCCESSFUL COMPLETION
;OF A READ PHYSICAL, AND DELETED
;DATA MARK WAS SEEN IN SECTOR HEADER
; (PCL) SUCCESSFUL TRANSFER BUT MESSAGE
;TRUNCATED {RECEIVE BUFFER TOO SMALL).
;(A/DREAD) AT LEAST ONE BAD VALUE
;WAS READ {REMAINDER MAY BE GOOD) •
;BAD CHANNEL IS INDICATED BY A
;NEGATIVE VALUE IN THE BUFFER.
;SUCCESSFUL BUT WITH DATA OVERRUN
;{NOT TO BE CONFUSED WITH IE.DAO)

TTY SUCCESS CODES
DEF IN$
DEF IN$
DEF IN$
DEF IN$
DEF IN$
DEF IN$
DEF IN$
DEF IN$

IS.CR,<15*400+1> ;CARRIAGE RETURN WAS TERMINATOR
IS.ESCi<33*400+1> ;ESCAPE (ALTMODE) WAS TERMINATOR
IS.CC,<3*400+1> ;CONTROL-C WAS TERMINATOR
IS.ESQ,<233*400+1> ;ESCAPE SEQUENCE WAS TERMINATOR
IS.PES,<200*400+1> ;PARTIAL ESCAPE SEQUENCE TERMINATOR
IS.EOT,<4*400+1> ;EOT WAS TERMINATOR {BLOCK MODE INPUT)
IS.TAB,<11*400+1> ;TAB WAS TERMINATOR (FORMS MODE INPUT)
IS.TM0,+2.
;REQUEST TIMED OUT

******
THE NEXT AVAILABLE ERROR NUMBER IS: -98.
NUMBER -71. IS AVAILABLE AND MAY BE REASSIGNED AT
A LATER DATE
*****
.IF
.MACRO
.ENDM
• ENDC
o-..Tni..•

• C.l'llLJl'I

EQ,$$MSG
IOERR$ A
IO ERR$
IO ERR$

I-5

ERROR CODES
DEFINE THE DIRECTIVE ERROR CODES RETURNED IN THE DIRECTIVE STATUS WORD
FILE CONTROL SERVICES (FCS) RETURNS THESE CODES IN THE BYTE F.ERR
OF THE FILE DESCRIPTOR BLOCK (FDB). TO DISTINGUISH THEM FROM THE
OVERLAPPING CODES FROM HANDLER AND FILE PRIMITIVES, THE BYTE
F.ERR+l IN THE FDB WILL BE NEGATIVE FOR A DIRECTIVE ERROR CODE •
• MACRO DRERR$ $$$GBL
.MCALL .QIOE.,DEFIN$
.IF
IDN,<$$$GBL>,<DEF$G>
••• GBL=l
.!FF
••• GBL=O
.ENDC
.IIF
NDF,$$MSG,$$MSG=O
STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE STATUS WORD
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.

IE.UPN,-01.,<Insufficient dynamic storage> ; SEE ALSO IE.NOR
IE.INS,-02.,<Specified task not installed>
IE.PTS,-03.,<Partition too small for task>
IE.UNS,-04.,<Insufficient dynamic storage for send>
IE.ULN,-05.,<Un-assigned LUN>
IE.HWR,-06.,<Device handler not resident>
IE.ACT,-07.,<Task not active>
IE.ITS,-08.,<Directive inconsistent with task state>
IE.FIX,-09.,<Task already fixed/unfixed>
IE.CKP,-10.,<Issuing task not checkpointable>
IE.TCH,-11.,<Task is checkpointable>
IE.RBS,-15.,<Receive buffer is too small>
IE.PRI,-16.,<Privileqe violation>
IE.RSU,-17.,<Resource in use>
IE.NSW,-18.,<No swap space available>
IE.ILV,-19.,<Illegal vector specified>

.QIOE.

IE.AST,-80.,<Directive issued/not issued from AST>
IE.MAP,-81.,<Illegal mapping specified>
IE.IOP,-83.,<Window has I/O in progress>
IE.ALG,-84.,<Alignment error>
IE.WOV,-85.,<Address window allocation overflow>
IE.NVR,-86.,<Invalid region ID>
IE.NVW,~87.,<Invalid address window ID>
IE.ITP,-88.,<Invalid TI parameter>
IE.IBS,-89.,<Invalid send buffer size ( .GT. 255.)>
IE.LNL,-90.,<LUN locked in use>
IE.IUI,-91.,<Invalid UIC>
IE.IDU,-92.,<Invalid device or unit>
IE.ITI,-93.,<Invalid time parameters>
IE.PNS,-94.,<Partition/region not in system>
IE.IPR,-95.,<Invalid priority ( .GT. 250.)>
IE.ILU,-96.,<Invalid LUN>
IE.IEF,-97.,<Invalid event flag ( .GT. 64.)>
IE.ADP,-98.,<Part of DPB out of user's space>
IE.SDP,-99.,<DIC or DPB size invalid>

.Q!OE.

.QIOE.
.QIOE.
.QIOE.
.QIOE.
nTn~

·~~v~•

.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.

SUCCESS CODES FROM DIRECTIVES - PLACED IN THE DIRECTIVE STATUS WORD

I-6

ERROR CODES
DEFIN$

IS.CLR,O

DEFIN$

IS.SET,2

DEFIN$

IS.SPD,2

.IF
.MACRO
.ENDM
.ENDC
.ENDM

EQ,$$MSG
DRERR$ A
DRERR$

;EVENT FLAG WAS CLEAR
;FROM CLEAR EVENT FLAG DIRECTIVE
;EVENT FLAG WAS SET
;FROM SET EVENT FLAG DIRECTIVE
;TASK WAS SUSPENDED

DRERR$

DEFINE THE GENERAL I/O FUNCTION CODES - DEVICE INDEPENDENT
.MACRO FILIO$ $$$GBL
.MCALL .WORD.,DEFIN$
.IF
IDN,<$$$GBL>,<DEF$G>
••• GBL=l
.IFF
••• GBL=O
.ENDC
GENERAL I/0 QUALIFIER BYTE DEFINITIONS
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IQ.X,001,000
IQ.Q,002,000
IQ.S,004,000
IQ.UMD,004,000
IQ.LCK,200,000

;NO ERROR RECOVERY
;QUEUE REQUEST IN EXPRESS QUEUE
;SYNONYM FOR IQ.UMD
;USER MODE DIAGNOSTIC STATUS REQUIRED
;MODIFY IMPLIED LOCK FUNCTION

EXPRESS QUEUE COMMANDS
.WORD.
.WORD.
.WORDe
.WORD.
.WORD.
.WORD.

IO.KIL,012,000

IO.RDN,022,000
IO.UNL,042,000
IO.LTK,050,000
IO.RTK,060,000
IO.SET 1 030,000

;KILL CURRENT REQUEST
;I/O RUNDOWN
;UNLOAD I/O HANDLER TASK
;LOAD A TASK IMAGE FILE
;RECORD A TASK IMAGE FILE
;SET CHARACTERISTICS FUNCTION

GENERAL DEVICE HANDLER CODES
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.WLB,000,001
IO.RLB,000,002
IO.LOV,010,002
IO.ATT,000,003
IO.DET,000,004

;WRITE LOGICAL BLOCK
;READ LOGICAL BLOCK
;LOAD OVERLAY (DISK DRIVER)
;ATTACH A DEVICE TO A TASK
;DETACH A DEVICE FROM A TASK

DIRECTORY PRIMITIVE CODES
.WORD.
.WORD.
.WORD.

IO. FNA, 000, Oll
IO.RNA,000,013
IO.ENA,000,014

;FIND FILE NAME IN DIRECTORY
;REMOVE FILE NAME FROM DIRECTORY
;ENTER FILE NAME IN DIRECTORY

I-7

ERROR CODES
FILE PRIMITIVE CODES
.WORD.
.WORD •
• WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
• WORD.
.WORD.

IO.CLN,000,007
IO.ULK,000,012
IO.ACR,000,015
IO.ACW,000,016
IO.ACE,000,017
IO.DAC,000,020
IO.RVB,000,021
IO.WVB,000,022
IO.EXT,000,023
IO.CRE,000,024
IO.DEL,000,025
IO.RAT,000,026
IO.WAT,000,027
IO.APV,010,030
IO.APC,000,030

.MACRO
.ENDM
.ENDM

FI LIO$
FI LIO$
FI LIO$

;CLOSE OUT LUN
;UNLOCK BLOCK
;ACCESS FOR READ
;ACCESS FOR WRITE
;ACCESS FOR EXTEND
;DE-ACCESS FILE
;READ VIRITUAL BLOCK
;WRITE VIRITUAL BLOCK
;EXTEND FILE
;CREATE FILE
;DELETE FILE
;READ FILE ATTRIBUTES
;WRITE FILE ATTRIBUTES
;PRIVILEGED ACP CONTROL
;ACP CONTROL

DEFINE THE I/O FUNCTION CODES THAT ARE SPECIFIC TO INDIVIDUAL DEVICES
.MACRO SPCIO$ $$$GBL
.MCALL .WORD.,DEFIN$
.IF
IDN,<$$$GBL>,<DEF$G>
••• GBL=l
.IFF
••• GBL=O
.ENDC

I/O FUNCTION CODES FOR SPECIFIC DEVICE DEPENDENT FUNCTIONS
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
• WORD.
.WORD.
.WORD.
• WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.WLV,100,001
IO.WLS,010,001
IO.WNS,020,001
IO.WAL,010,001
IO.WMS,020,001
IO.CC0,040,001
IO.WBT,100,001
IO.WLT,010,001
IO.WLC:020:001
IO.WPB,040,001
IO.WDD,140,001
IO.RLV,100,002
IO.RST,001,002
IO.RAL,010,002
IO.RNE,020,002
IO.RNC,040,002
IO.RTM,200,002
IO.RDB,200,002
IO.SCF,200,002
IO.RHD,010,002
IO.RNS,020,002
IO.CRC,040,002
IO.RPB,040,002
IO.RLC,020,002
IO.ATA,010,003
IO.GTS,000,005

; (DECTAPE) WRITE LOGICAL REVERSE
; (COMM.) WRITE PRECEDED BY SYNC TRAIN
; (COMM.) WRITE, NO SYNC TRAIN
;(TTY) WRITE PASSING ALL CHARACTERS
; (TTY} WRITE SUPPRESSIBLE MESSAGE
; (TTY) WRITE WITH CANCEL CONTROL-0
; (TTY} WRITE WITH BREAKTHROUGH
; (DISK) WRITE LAST TRACK
; (DISK) WRITE LOGICAL W/ WR!TECHECK
; (DISK) WRITE PHYSICAL BLOCK
; (FLOPPY DISK) WRITE PHYSICAL W/ DELETED DATA
; (MAGTAPE,DECTAPE) READ REVERSE
; (TTY) READ WITH SPECIAL TERMINATOR
; (TTY) READ PASSING ALL CHARACTERS
; (TTY) READ WITHOUT ECHO
; (TTY) READ - NO LOWER CASE CONVERT
i (TTY) READ WITH TIME OUT
; (CARD READER) READ BINARY MODE
; (DISK) SHADOW COPY FUNCTION
; (COMM.) READ, STRIP SYNC
; (COMM.) READ, DON'T STRIP SYNC
; (COMM.) READ, DON'T CLEAR CRC
; (DISK) READ PHYSICAL BLOCK
; (DISK,MAGTAPE) READ LOGICAL W/ READCHECK
; (TTY) ATTACH WITH AST'S
; (TTY) GET TERMINAL SUPPORT CHARACTERISTICS

I-8

ERROR CODES
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.RlC,000,005
IO.INL,000,005
IO.TRM,010,005
IO.RWD,000,005
IO.SPB,020,005
IO.RPL,020,005
IO.SPF,040,005
IO.STC,100,005
I 0. SMD, 110 , 0 0 5
IO.SEC,120,005
IO.RWU,140,005
IO.SM0,160,005
IO.HNG,000,006
IO.RBC,000,006
IO.MOD,000,006
IO.HDX,010,006
IO.FDX,020,006
IO.SYN,040,006
IO.EOF,000,006
IO.ERS,020,006
·rn.DSE,040,006
IO.RTC,000,007
IO.SA0,000,010
IO.SS0,000,011
IO.RPR,000,011
IO.MS0,000,012
IO.RTT,001,012
IO.SL0,000,013
IO.ML0,000,014
IO.LED,000,024
IO.SD0,000,025
IO.SDI,000,026
IO.SCS,000,026
IO.REL,000,027
IO.MCS,000,027
IO.ADS,000,030
IO.CCI,000,030
IO.LOD,000,030
IO.MDI,000,031

.WORD.
.WORD.
.WORD.

IO.STA,000,033
IO.DTI,000,034
IO.DIS,000,034

.WORD.
• WORD.

IO.MDA,000,034
IO.DPT,010,034

IO.DCiiOOOi03l
IO.PAD,000,031
IO.XMT,000,031
IO.XNA,010,031
IO.INI,000,031
IO.HIS,000,032
IO.RCI,000,032
IO.RCV,000,032
IO.CLK,000,032
IO.CSR,000,032
IO.MD0,000,033
IO.CTI,000,033
IO.CON,000,033

; (AFC,ADOl,UDC) READ SINGLE CHANNEL
; (COMM.) INITIALIZAtION FUNCTION
; (COMM.) TERMINATION FUNCTION
; (MAGTAPE,DECTAPE) REWIND
; {MAGTAPE) SPACE "N" BLOCKS
; (DISK) REPLACE LOGICAL BLOCK (RESECTOR)
; (MAGTAPE} SPACE "N" EOF MARKS
;SET CHARACTERISTIC
; (FLOPPY DISK) SET MEDIA DENSITY
;SENSE CHARACTERISTIC
; (MAGTAPE,DECTAPE) REWIND AND UNLOAD
; (MAGTAPE) MOUNT & SET CHARACTERISTICS
; (TTY) HANGUP DIAL-UP LINE
;READ MULTICHANNELS {BUFFER DEFINES CHANNELS)
; (COMM.) SETMODE FUNCTION FAMILY
; (COMM.) SET UNIT HALF DUPLEX
; (COMM.) SET UNIT FULL DUPLEX
; (COMM.) SPECIFY SYNC CHARACTER
; (MAGTAPE) WRITE EOF
; (MAGTAPE) ERASE TAPE
; {MAGTAPE) DATA SECURITY ERASE
;READ CHANNEL - TIME BASED
; (UDC) SINGLE CHANNEL ANALOG OUTPUT
; (UDC) SINGLE SHOT, SINGLE POINT
; (TTY) READ WITH PROMPT
;(UDC) SINGLE SHOT, MULTI-POINT

; (TTY) READ WITH TERMINATOR TABLE
;(UDC) LATCHING, SINGLE POINT
; (UDC) LATCHING, MULTI-POINT
;(LPSll) WRITE LED DISPLAY LIGHTS
; (LPSll) WRITE DIGITAL OUTPUT REGISTER
; (LPSll) READ DIGITAL INPUT REGISTER
; (UDC) CONTACT SENSE, SINGLE POINT
; (LPSll) WRITE RELAY
; (UDC) CONTACT SENSE, MULTI-POINT
; (LPSll) SYNCHRONOUS A/D SAMPLING
;{UDC) CONTACT INT - CONNECT
; (LPAll} LOAD MICROCODE
; (LPSll) SYNCHRONOUS DIGITAL INPUT
; (UDC) CONTACT INT - DISCONNECT
; (PSI) DIRECT CONTROL OF X.29 PAD
; (COMM.) TRANSMIT SPECIFIED BLOCK WITH ACK
; (COMM.) TRANSMIT WITHOUT ACK
; (LPAll) ~NITIALIZE
; (LPSll) SYNCHRONOUS HISTOGRAM SAMPLING
; {UDC) CONTACT INT - READ
; (COMM.) RECEIVE DATA IN BUFFER SPECIFIED
; (LPAll) START CLOCK
; {BUS SWITCH) READ CSR REGISTE~
; {LP~ll) SYNCHRONOUS DIGITAL OUTPUT
; (UDC) TIMER - CONNECT
; {COMM.) CONNECT FUNCTION
;{VTll) - CONNECT TASK TO DISPLAY PROCESSOR
;(BUS SWITCH) CONNECT TO SPECIFIED BUS
; (LPAll) START DATA TRANSFER
; (UDC) TIMER - DISCONNECT
; (COMM.) DISCONNECT FUNCTION
; (VTll) - DISCONNECT TASK FROM DISPLAY PROCESSOR
; (BUS SWITCH) SWITCHED BUS DISCONNECT
; (LPSll) SYNCHRONOUS D/A OUTPUT
; (BUS SWITCH) DISCONNECT TO SPECIF PORT NO •

I-9

ERROR CODES
.WORD.
.WORD.
.WORD.

IO.RTI,000,035
IO.CTL,000,035
IO.STP,000,035

.WORD.
.WORD.
.WORD.

IO.SWI,000,035
IO.CNT,000,036
IO.ITI,000,036

; (UDC) TIMER - READ
; (COMM.) NETWORK CONTROL FUNCTION
; (LPSll,LPAll) STOP IN PROGRESS FUNCTION
; {VTll) - STOP DISPLAY PROCESSOR
; {BUS SWITCH) SWITCH SUSSES
; {VTll) - CONTINUE DISPLAY PROCESSOR
; (UDC) TIMER - INITIALIZE

COMMUNICATIONS FUNCTIONS
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.CPR,010,033
IO.CAS,020,033
IO.CRJ,040,033
IO. CBO, llO, 033
IO.CTR,210,033
IO.GNI,010,035
IO.GLI,020,035
IO.GLC,030,035
IO.GRI,040,035
IO.GRC,050,035
IO.GRN,060,035
IO.CSM,070,035
IO. CIN, 100, 035
IO. SPW, llO, 035
IO.CPW,120,035
IO.NLB,130,035
IO.DLB,140,035

;CONNECT NO TIMEOUTS
;CONNECT WITH AST
;CONNECT REJECT
;BOOT CONNECT
;TRANSPARENT CONNECT
;GET NODE INFORMATION
;GET LINK INFORMATION
;GET LINK INFO CLEAR COUNTERS
;GET REMOTE NODE INFORMATION
;GET REMOTE NODE ERROR COUNTS
;GET REMOTE NODE NAME
;CHANGE SOLO MODE
;CHANGE CONNECTION INHIBIT
;SPECIFY NETWORK PASSWORD
;CHECK NETWORK PASSWORD.
;NSP LOOPBACK
;DDCMP LOOPBACK

ICS/ICR I/O FUNCTIONS
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.CTY,000,007
IO.DTY,000,015
IO.LDI,000,016
IO.UDI,010,023
IO.LTI,000,017
IO.UTI,020,023
IO.LTY,000,020
IO.UTY,030,023
IO.LKE,000,024
IO.UER,040,023
IO.NLK,000,023
IO.ONL,000,037
IO.FLN,000,025
IO.RAD,000,021

;CONNECT TO TERMINAL INTERRUPTS
;DISCONNECT FROM TERMINAL INTERRUPTS
;LINK TO DIGITAL INTERRUPTS
;UNLINK FROM DIGITAL INTERRUPTS
;LINK TO COUNTER MODULE INTERRUPTS
;UNLINK FROM COUNTER MODULE INTERRUPTS
;LINK TO REMOTE TERMINAL INTERRUPTS
;UNLINK FROM REMOTE TERMINAL INTERRUPTS
;LINK TO ERROR INTERRUPTS
;UNLINK FROM ERROR INTERRUPTS
;UNLINK FROM ALL INTERRUPTS
;UNIT ONLINE
;UNIT OFFLINE
;READ ACTIVATING DATA

IPll I/O FUNCTIONS
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.MA0,010,007
IO.LEI,010,017
IO.RDD,010,020
IO.RMT,020,020
IO.LSI,000,022
IO.UEI,050,023
IO.USI,060,023
IO.CSI,000,026
IO.DSI,000,027

;MULTIPLE ANALOG OUTPUTS
;LINK EVENT FLAGS TO INTERRUPT
;READ DIGITAL DATA
;READ MAPPING TABLE
;LINK TO DSI INTERRUPTS
;UNLINK EVENT FLAGS
;UNLINK FROM DSI INTERRUPTS
;CONNECT TO DSI INTERRUPTS
;DISCONNECT FROM DSI INTERRUPTS

I-10

ERROR CODES
PCLll I/O FUNCTIONS

.WORD.
.WORD.
.WORD.
.WORD.

IO.ATX,000,001
IO.ATF,000,002
IO.CRX,000,031
IO.DRX,000,032
IO.RTF,000,033

.MACRO
.ENDM
.ENDM

SPCIO$
SPCIO$
SPCI0$

.WORD~

;ATTEMPT TRANSMISSION
;ACCEPT TRANSFER
;CONNECT FOR RECEPTION
;DISCONNECT FROM RECEPTION
;REJECT TRANSFER

DEFINE THE I/O CODES FOR USER-MODE DIAGNOSITCS. ALL DIAGNOSTIC
FUNCTION ARE IMPLEMENTED AS A SUBFUNCTION OF I/O CODE 10 (OCTAL) •
.MACRO UMDI0$ $$$GBL
.MCALL • WORD., DEF IN$
• IF IDN <$$$GBL>,<DEF$G>
••• GBL=l
.IFF
••• GBL=O
.ENDC
DEFINE THE GENERAL USER-MODE
.WORD.

IQ.UMD,004,000

;USER MODE DIAGNOSTIC REQUEST

DEFINE USER-MODE DIAGNOSTIC FUNCTIONS.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.HMS,000,010
IO.BLS,010,010
IO.OFF,020,010
IO.RDH,030,010
IO.WDH,040,010
IO.WCK,050,010
IO.RNF,060,010
IO.RNR,070,010
IO.LPC,100,010
IO.RTD,120,010
IO.WTD,130,010
IO.TDD,140,010
IO.DGN,150,010
IO. WPD, 16 0 , 010
IO.RPD,170,010
IO.CER,200,010
IO.CEW,210,010

; (DISK) HOME SEEK OR RECALIBRATE
; (DISK) BLOCK SEEK
; (DISK) OFFSET POSITION
; (DISK) READ DISK HEADER
; (DISK) WRITE DISK HEADER
; (DISK} WRITECHECK (NON-TRANSFER)
; (DECTAPE) READ BLOCK NUMBER FORWARD
; (DECTAPE) READ BLOCK NUMBER REVERSE
; (MAGTAPE) READ LONGITUDINAL PARITY CHAR
; (DISK) READ TRACK DESCRIPTOR
; (DISK) WRITE TRACK DESCRIPTOR
; (DISK) WRITE TRACK DESCRIPTOR DISPLACED
;DIAGNOSE MICRO PROCESSOR FIRMWARE
; (DISK) WRITE PHYSICAL BLOCK
; (DISK) READ PHYSICAL BLOCK
; (DISK) READ CE BLOCK
; (DISK) WRITE CE BLOCK

MACRO REDEFINITION TO NULL
.MACRO
• ENDM

UMDIO$

.ENDM

UMDIO$

I-11

ERROR CODES
HANDLER ERROR CODES RETURNED IN I/O STATUS BLOCK ARE DEFINED THROUGH THIS
MACRO WHICH THEN CONDITIONALLY INVOKES THE MESSAGE GENERATING MACRO
FOR THE QIOSYM.MSG FILE
.MACRO
DEFIN$
.IF
• MCALL
• IOMG •
• ENDC
• ENDM

.IOER.
SYM,LO,MSG
SYM,LO
GT,$$MSG
• IOMG •
SYM,LO,<MSG>
• IOER •

I/O ERROR CODES ARE DEFINED THOUGH THIS MACRO WHICH THEN INVOKES THE
ERROR MESSAGE GENERATING MACRO, ERROR CODES -129 THROUGH -256
ARE USED IN THE QIOSYM.MSG FILE
.MACRO
DEF IN$
.IF
.MCALL
• IOMG •
• ENDC
• ENDM

.QIOE.
SYM,LO,MSG
SYM,LO
GT,$$MSG
• IOMG.
SYM,<L0-128.>,<MSG>
• QIOE •

CONDITIONALLY GENERATE DATA FOR WRITING A MESSAGE FILE
.MACRO
.WORD
.ENABL
.ASCIZ
.DSABL

.IOMG.
SYM,LO,MSG
-""O<LO>
LC
"'MSG""
LC

•!IF

LT,""O<$$$MAX+<LO>>,$$$MAX=-""O<LO>
• IOMG •

• ENDM

DEFINE THE SYMBOL SYM WHERE LO IS IS THE LOW ORDER BYTE, HI IS THE HIGH BYTE
.MACRO
DEF IN$
• ENDM

.WORD. SYM,LO,HI
SYM,<HI*400+LO>
.WORD •

.DSABL

I-12

APPENDIX J
FIELD SIZE SYMBOLS

Definitions for these symbols are contained in the System Library.
S.BFHD - Size of FSR block buffer header in bytes
S.FATT - Size of FDB file attribute area in bytes
S.FDB

- Size of FDB in bytes (including name block)

S.FNAM - Size of file name in bytes (stored in RAD-50)
S.FNB

- Size of filename b'lock in bytes

S.FNBW - Size of filename block in words
S.FNTY

Size of file name and file
RAD-50)

type

words

(stored

S.FSR2 - Size of FSR2 (basic impure area)
S.FTYP - Size of file type in bytes (in RAD-50)
S.NFEN - Size of a complete file name in bytes -- file ID,
type, and version

J-1

name,

APPENDIX K
RSX-llM/M-PLUS FCS LIBRARY SYSGEN OPTIONS

K.l

FCS LIBRARY OPTIONS

The system manager has the option of selecting one of several FCS
libraries as the default FCS library. You can replace the default
library in SYSLIB with one of the other libraries shown in Table K-1
by
using
the /RP switch to the LBR utility.
Refer to the
RSX-llM/M-PLUS Utilities Manual for more information.
The following
list contains the FCS libraries that are available with each RSX-llM
or RSX-llM-PLUS system, and a brief description of each.
Table K-1
FCS Library Descriptions
FCS Library Support

K.2

Description

[l,l]FCS.OBJ

Standard FCS routines. Distributed and
included in SYSLIB.OLB as the default FCS
library routines for RSX-llM.

[l,l]FCSMTA.OBJ

Includes standard FCS routines, plus ANSI
magtape support and "big buffering" (see
Section 2.2.1.6 for block buffer size
override specification). Distributed and
included as the default FCS library
routines for RSX-llM-PLUS.

[l,l]FCSMBF.OBJ

Provides multiple buffering support, big
buffering support, and ANSI magtape support
in addition to the standard FCS routines.

.FCTYP

The FCS routine, .FCTYP, returns a description of the FCS
assembly parameters that were set when FCS was built.
The format of the call is:
CALL

.FCTYP

There are no input parameters.

K-1

conditional

RSX-llM/M-PLUS FCS LIBRARY SYSGEN OPTIONS
The information is returned in Rl. The bits set in the mask word
returned in Rl correspond to the conditional assembly parameters as
shown in Table K-2.
Table K-2
.FCTYP Values
Conditional
Assembly Symbol

Rl Bit Mask Symbol

Meaning

R$$ANI

FT.ANI

ANSI magnetic tape support

R$$BBF

FT.BBF

Big buffer support

R$$MBF

FT.MBF

Multibuffer support

...:.

K-2

INDEX

ACTFIL command, 2-41
Action routines, 7-6
ANSI filename block format,
B-5
ANSI magnetic tape, 5-4, G-1,
G-10
creating volume, G-11
end-of-tape, G-9
end-of-volume label, G-7
file header block, G-9
file header format,
G-5 to G-6
file header labels,
G-3 to G-4
file name conversion, G-6
file structure, G-8
file trailer labels, G-7
FNB offset defintions, B-4
opening file by file ID,
3-14
override block size, 2-18
rewinding file, 4-18
set default block size, G-10
user file labels, G-8
user volume labels, G-3
volume label format,
G-1 to G-4
ANSI magtape file name, 6-13
conversion to RADIX-50, 4-15
dataset descriptor, 2-29
.FIND operation on, 4-15
.PARSE, 4-8
restriction on NMBLK$, 2-33
.ASCPP, 4-7
ASG directive,
task builder, 6-13
• ASLUN I 4-12
Assign Logical Unit Number,
4-12
AST,
block I/O completion, 2-44
AST service routine,
restrictions, 2-45
specifying address, L-44
Asynchronous transfer, 3-37
Automatic file truncation,
4-22
disabling, 4-22
enabling, 4-22

Bad Block File Header, E-2
Big buffering, 1-7, 3-21, 3-27
Big buffers,
choosing size for, 1-8
Index-1

Big buffers (Cont.)
using, 1-8
Block buffer size, 3-21, 3-27
Block I/O, 3-30, 3-35
Block I/O completion, 3-35
Block locking,
enabling, 2-15
Block size,
parameter to FDBK$A, 2-11
Boostrap block, E-1
Buffer address,
parameter to FDBK$A, 2-11
Built-in variables, 7-5

Calculating length of the FSR,
2-40
CALL macro, 4-1
Carriage control,
specifying, for unlabeled
tape, G-11
CCML$, 6-9, 6-12
Checkpoint File Header, E-2
Choosing buffer size, 1-8
Clearing terminal end of file,
4-25
CLOSE$,
automatic file truncation,
4-22
effect of on F.CNTG, 2-7
CLOSE$ macro call,
format, 3-18
Closing a file, 3-17
Closing magtape volume, 4-25
Command line,
ignoring blanks and tabs,
7-8
Command line parsing,
errors, 6-21
Command line processing, 6-1
data flow during, 6-2
Command Semantic Parser,
6_-i 9 to 6-20
Command String Syntax
Analyzer, 6-18 to 6-19
Continuation lines, 6-5
Control bits for .EXTND,
4-23 to 4-24
Control information,
parameter to FDOP$A, 2-15
Creating a new file, 3-4, 3-7
CSI, 6-1, 6-13 to 6-14, 6-18,
6-20 to 6-27, 6-29
numeric conversion, 6-28
CSI$, 6-14

INDEX

CS! Control block,
6-14 to 6-17
CS! Run-time macro calls, 6-18
CSI$1, 6-18 to 6-19
CSI$2, ~-18 to 6-21
.CTRL, 4-25, 5-6

Dataset descriptor, 1-10,
2-27 to 2-28, 3-15
definition of, 1-11
parameter to FDOP$A, 2-13
Dataset-descriptor pointer,
definition of, 1-11
Debug routine, 7-6 to 7-7,

Directory entry (Cont.)
deleting wildcard, 4-16
inserting, 4-15
locating, 4-13
Directory files, 5-2
Directory Identification,
parsing, 4-10
Directory information,
inserting, 4-16
parsing, 4-12
Directory string,
reading, 4-2
writing, 4-2 to 4-3
Directory Structure,
multiuser volume, 5-3
single-user volume, 5-2

7-11

Declaring FCS macros, 2-3
Default buffer count,
changing, 2-20
Default buffer size, 1-8, 2-41
Default directory,
inserting, 4-17
Default extend size, 2-19
establishing, 2-8
volume, 2-8
Default file name,
parameter to NMBLK$, 2-31
Default file name block! 1-10!
2-27, 2-30, 3-4, 3-15
definition of, 1-11
initializing directly, 2-32
parameter to FDOP$A, 2-14
Default file name block label,
parameter to NMBLK$, 2-31
Default file protection,
4-4 to 4-5
reading, 4-5
word format, 4-5
writing, 4-5
Default file type,
parameter to NMBLK$, 2-31
Default file version number,
parameter to NMBLKS, 2-31
Default name of device,
parameter to NMBLK$, 2-31
Default UIC, 4-4
reading, 4-4
writing, 4-4
DELET$, 3-38
format, 3-38
parameters, 3-38
Delete Directory Entry, 4-16
Device and unit,
parsing, 4-9, 4-12
Directive status codes,
I-1 to I-12
Directory entry,
deleting, 4-16

Index-2

EBCDIC, G-17
Enabling block locking, 2-15
.ENTER, 4-15
Error handling,
• PRINT, 8-2
PRINT$, 8-2
Event flag,
parameter to FDBF$A, 2-17
parameter to FDBK$A, 2-12
using for I/O operations!
2-42
Executive directives,
summary, C-1 to C-3
Existing file,
opening by file ID, 3-14
Extend size,
default, 2-8
volume default, 2-8
Extending a file, 4-21
Extension headers, F-6
.EXTND, 4-21
control bits for,
4-23 to 4-24
effect of on F.CNTG, 2-7
EXTSCT Task-build command,
to extend FSR size, 2-40

FllACP, F-6
F.ALOC,
See Extend size
F.CNTG, 2-6 to 2-7
FCS, 4-1
characteristics of, 1-12
conditional assembly
parameters, K-1 to K-2
FCS impure area,
allocating, 2-37
FCS library descriptions, K-1

INDEX

FCS library options, K-1
FCS macros,
declaring, 2-3
FCS routines,
error return, 4-2
list of, 4-2
FCSMC$, 2-3
.FCTYP values, K-2
FDB, 1-10
block access section, 2-10
block buffer section, A-2
file attribute section, A-2
file open section, A-2
format, A-2
GET$, 3-20
offset definitions,
A-3 to A-4, A-6 to A-8
offset defintions, A-5
PUT$, 3-26
READS, 3-34
record access section, 2-8
record or block access
section, A-2
WRITE$, 3-35
FDB information, 2-2
macro calls, 2-2
FDB macros,
initializing, 2-3
FDBDF$, 2-5
FDBF$A,
using with big buffers, 1-8
FDBF$A macro call,
format, 2-17
FDBF$R,
using with big buffers, 1-8
FDBK$A, 2-10
format, 2-11
parameters, 2-11
FDBKSR,
compatability with FDBK$A,
2-11
FD.BLK,
See Record attributes
FD.CR,
See Record attributes
F.DFNB, 2-14
FD.FTN,
See Record attributes
FD.PRN,
See Record attributes
FDRC$A,
format, 2-8
F.DSPT, 2-13
F.FACC, 2-14
Field size symbols, J-1
File,
closing, 3-17
creating, 3-4, 3-7
deleting, 3-38, 4-23

Index-3

File (Cont.)
deleting by Filename block,
4-24
deleting wildcard, 4-15
extending, 4-21
opening an existing, 3-4,
3-8
opening by filename block,
3-14
positioning, 4-18 to 4-19
renaming, 4-20
rewinding, 4-18
File access, 3-16
parameter to FDOP$A, 2-14
file access privileges, 3-3
File Control Services {FCS),
4-1
File Descriptor Block, 1-10,
A-1
definition of, 1-10
format, A-1 to A-2
offset definitions,
A-3 to A-8
offsets, A-1
File extension,
See File type
File header area,
characteristics, F-4
file number, F-3
file owner, F-4
file protection, F-4
file sequence number, F-3
identification area, F-3
map area offset, F-3
structure level, F-4
user file attributes, F-4
File header block, 5-3
file header area, F-3
format, F-2
identification area, F-4
map area, F-5
predefined, E-2
file header block,
format, F-1
File ID,
opening file by, 2-33, 3-13
File identifier,
processing by Files-11, G-6
File locking, 2-15
File owner,
nonprivileged user, 4-5
privileged user, 4-6
File owner word, 4-5
format, 4-6
reading, 4-6
writing, 4-6
File processing,
magnetic tape, 5-4

INDEX

File specification, 2-27
definition of, 1-11
File specifier,
See File specification
File Storage Region,
definition of, 1-11
initializing, 2-36
File structure, 5-1
ANSI magtape, G-8
user, 5-1
File truncation,
automatic, 4-22
PUTS, 2-9
File type,
parsing, 4-11 to 4-12
File version,
0, 4-16
default, 4-16
parsing, 4-11 to 4-12
special versions, 4-13
wildcard, 4-16
Filename,
parsing, 4-8, 4-11 to 4-12
Filename block,
ANSI format, B-5
default directory, 4-17
definition of, 1-11
deleting by, 4-24
directory information, 4-16
format, B-1, B-3
initializing, 2-35
offset definitions, B-2
offsets, B-1
offsets for ANSI magtape,
B-4
status word, 4-11,
B-3 to B-4
File-processing macro calls,
3-1
error handling, 3-2
Files-11, 5-1, E-1, F-5, G-3,
G-6
file identifier processing,
G-6
naming convention, G-3
.FIND, 4-13 to 4-14
effects of NB.ANS, 4-15
wildcard operations, 4-13
FINIT$ macro, 2-39
format, 2-39
Fixed length record, 1-4
mag tape, 1-4
F.MBCT, 2-18
FORTRAN programs,
increasing FSR size, 2-41
F.RACC,
See FDB
F.RATT, 2-6

Index-4

FSR,
calculating length, 2-40
changing the size of, 1-3
initializing, 2-36, 2-39
number of block buff er
headers, 1-2
number of block buffers, 1-2
FSR size,
for command file, 6-13
$$FSR1, 1-2
FSR program section, 2-40
$$FSR2, 1-2, 4-2, 4-4 to 4-5
FSRSZ$, 2-37
FSRSZ$ macro, 2-36
format, 2-37
parameters, 2-37

GCML, 6-1 to 6-13
run-time calls, 6-9
usage considerations, 6-13
GCMLS; ~-9 to 6-11
GCML control block, n-3
offsets, 6-6 to 6-9
GCML control block offsets,
referencing, 6-9
GCMLB$, 6-4 to 6-5
GCMLD$, 6-6 to 6-9

Generating a parser program,
7-14
GET$,
FDB, 3-20
locate mode, 3-18
move mode, 3-18, 3-21
GET$ macro call,
format, 3-19
parameters, 3-19
GET$R, 3-22
GET$R macro call,
format, 3-22
parameters, 3-23
GET$S, 3-24
.GTDID, 3-15, 4-17
.GTDIR, 3-15, 4-16

Home block, E-2
format, E-3

IBM magnetic tape,
reading, G-18 to G-19
Increasing FSR size,
FORTRAN programs, 2-41
MACR0-11 programs, 2-40

INDEX

Index file, 5-2, E-1
bit map, E-2
format, E-1
header, E-2
Indirect command files, 6-3,
6-11 to 6-12
maximum nesting depth,
6-3 to 6-4
Insert Directory Entry, 4-15
I/O Error Codes, I-1 to I-12
I/O Function codes,
I-1 to I-12
I/O operations,
event flag use, 2-42
I/O related directives,
summary, C-2 to C-3
I/O status block, 2-43
parameter to FDBK$A, 2-12
READ$ operations, 2-43
second word, 2-43
status codes, 2-44
I/0-related directives,
summary, C-1
IOSTAT, 2-44
ISTAT$, 7-2, 7-7

MAG SET (Cont.)
/EOF, G-11
/POS, G-16
/REWIND, G-12, G-16
/RS, G-12
MAG SET command, G-10, G-16
error messages, G-13 to G-15
example, G-12
MAG SET /EOT, G-11
MAG SET /EOV, G-11
MAG SET /INITIALIZE, G-11
MAG SET /POS, G-11
Magnetic tape, 5-4
closing a file, 5-8
closing volume, 4-25
examples, 5-9 to 5-10
multiple-file operations,
5-6
overriding FCS defaults,
5-6 to 5-7
position to EOT, 4-25
positioning, 5-5, G-11
processing examples, 5-7
reading a file, 5-8
reading IBM, G-18 to G-19
rewinding, 4-25
rewinding file on, 4-25
single-file operations, 5-S
translation, G-16
Magnetic Tape Control Task,
G-10
Magnetic tape position, 2-15
Magnetic tape volume,
access, 5-4
creating multiple file, 5-6
rewinding, 5-5
Magnetic tape volume set,
rewinding, 5-5
.MARK, 4-18 to 4-19
Master File Directory, 5-2
Master File Directory Header,
E-2
Move mode, 1-6
GET$, 3-18
GET$ operations, 3-21
PUT$, 3-26
.MRKDL, 4-23
Mnltiole buffer count.
---p~~~~~t~r to FDBF$A~ 2-18
parameter to FSRSZ$, 2-38
Multiple buffering, 1-6, 3-10
effect on FSRSZ$, 2-37
read-ahead, 1-7, 2-18
type of, 2-18
versus single buffering, 1-7
write-behind, 2-19
Multiple-buffered record I/O,
3-10

Keyword,
abbreviation, 7-12
recognition, 7-9
Keyword table, 7-2

Locate Directory Entry, 4-13
Locate mode, 1-6
GET$, 3-18
GET$ operations, 3-21
PUT$, 3-27
Logical unit number,
assigning, 4-12
parameter to FDOP$A, 2-13

Macro calls, 2-2
assembly time, 2-2
file-processing, 2-2
run-time, 2-2
MACR0-11 programs,
increasing FSR size, 2-40
MAG, G-10
MAG command,
format, G-10
MAG SET,
/BS, G-10
/CC, G-11

Index-5

INDEX

NB.ANS,
bit in N.STAT, 4-15
NMBLK$,
general method of
specifying, 2-32
macro call, 2-30
parameters, 2-31
NMBLK$ macro, 3-15
N.STAT, 4-11, B-3 to B-4
wildcard .FIND operations,
4-13

OFNB$X macro call,
format, 3-14
OPENS macro call,
format, 3-17
Opening a file, 3-2
Opening a new file, 3-8
Opening an existing file, 3-4,
3-8
by file ID, 3-i4
Opening by file ID,
2-33 to 2-34, 3-13
Opening filename block, 3-14
OPEN$x,
restrictions, 3-3
suffixes for, 3-2
OPEN$x macro call,
file access privileges, 3-3
format, 3-5
Override block size,
ANSI magtape, 2-18
parameter to FDBF$A, 2-17
Overriding default buffer
size, 1-8
Overriding FCS defaults for
mag tape, 5-7

.PRINT subroutine, 8-2
Program section,
generated by TPARS, 7-10
Prompt,
user-specified, 6-4, 6-10
PSECT, 7-10
PUT$, 3-24
FDB, 3-26
locate mode, 3-24, 3-27
move mode, 3-24, 3-26
random mode, 3-24
PUT$ macro call,
format, 3-25
parameters, 3-25
PUT$R, 3-28
PUT$R macro call,
format, 3-29
parameters, 3-29
PUT$S, 3-30
PUT$S format,
See PUT$

• PARSE, 4-8
Parser program,
generating, 7-14
.POINT, 2-9, 4-18
restrictions, 4-18
.POSIT, 4-20
Positioning to end of tape,
4-25
.POSRC, 3-24, 3-29, 4-19
.PPASC, 4-7
.PRINT,
error handling, 8-2
PRINT$,
error handling, 8-2
error returns, 8-1
macro, 8-1
Print Spooling, 8-1

Index-6

QIO$ directive, 2-41 to 2-42
QIO function,
executing, 4-20

Random mode, 3-22
RCML$, 6-9, 6-12
• RDFDR, 4-2
• RDFFP, 4-5

.RDFUI, 4-4
READ$, 3-30
FDB, 3-34
Read logical record,
locate mode, 3-18
move mode, 3-18
random mode, 3-24
READ$ macro call,
format, 3-31
parameters, 3-31 to 3-33
Read virtual block, 3-30
Read-ahead multiple buffering,
1-7, 2-18
Record access byte,
initializing, 2-9
Record access section of FDB,
2-8
Record attribute byte, 2-6
Record attributes, 2-6
Record I/O,
contrast to block I/O, 1~5
data flow during, 1-3
multiple buffered, 3-10
multiple buffering, 1-6
random access mode, 1-5

INDEX

Record I/O (Cont.)
sequential access mode, 1-5
Record I/O operations, 3-24
Record size, 2-6
Record type,
R.FIX, 2-5
R.SEQ, 2-6
R.VAR, 2-6
• REMOV, 4-16
• RENAM, 4-2 0
Request for next tape,
terminating, G-11
Retrieval pointer format, F-5
Retrieval pointers,
allocating, 2-15
Rewinding,
file on ANSI magtape, 4-18
file open on terminal, 4-18
Rewinding magtape, 4-25
Rewinding magtape volume, 4-25

Sample programs, D-1
Shared file access,
OPEN$R, 1-9
OPNS$A, 1-9
OPNS$R, 1-9
OPNS$U, 1-9
OPNS$W, 1-9
Permitted second access, 1-9
Single buffering,
versus multiple buffering,
1-7
Special characters,
entering, 7-9
Spooling, 8-1
State table, 7-2, 7-8
initializing, 7-2
Statistics block, 3-11
format, H-1
Storage Map File header, E-2
Subexpression,
using, 7-19
Subexpressions,
TPARS, 7-7
Switch Definition,
C

"')1

u-L.J.

..__

1..v

"')C

System directives,
summary, C-1 to C-3

Table Driven Parser, 7-1
Tape mark, G-16
Task builder, 2-41
ASG directive, 6-13
Temporary file,
creating, 3-11
deleting, 4-23
marking, for deletion, 3-12
opening, 3-11
Termin.al,
rewinding file open on, 4-18
TPARS, 7-1 to 7-11, 7-14
calling conventions, 7-12
options word, 7-12
programming examples,
7-15 to 7-18
register usage, 7-12
subexpressions, 7-19
TRAN$ macro, 7-4
Transition,
defining, 7-3
rejecting, 7-6, 7-18
Translation,
EBCDIC, G-17 to G-18
installation=dependent
routines, G-17
magnetic tape, G-17
Translation table,
EBCDIC, G-17 to G-18
• TRNCL, 4-22
Truncation of file,
PUT$, 2-9

UIC,
default, 4-4
UIC conversion,
ASCII to binary, 4-7
binary to ASCII, 4-7
Unit number,
parameter to NMBLK$, 2-31
Unlabeled tape, G-15

u-Lu

Switch Descriptor Table,
fi-22 to 6-26
end, 6-29
format of entry, 6-26
Switch Value Descriptor Table,
6-27
end, 6-29
entry format, 6-28
Syntax element,
defining, 7-3
types, 7-4 to 7-5, 7-8

Index-7

example, G-12
file attributes, G-16
positioning, G-11, G-16
specifying block size, G-10
specifying carriage control,
G-11
specifying record size, G-12
User File Directory, 5-2
User record buffer,
parameter for FDRC$A, 2-9
size, 2-10

INDEX

User record buffer size,
parameter for FDRC$A, 2-10
User volume lables,
ANSI magtape, G-3
User-specified prompt, 6-4,
6-10
Using big buffers, 1-8

Variable-length record,
magtape, 1-4
nonsequenced, 1-4
sequenced, 1-4
VFY, 3-12
Virtual block,
definition of, 1-3
Virtual block on magtape, 1-4

WAIT$ macro call (Cont.)
parameters, 3-36 to 3-37
.WDFDR, 4-3
.WDFFP, 4-5
.WDFUI, 4-4
Wildcard operations, 4-14
effects of N.STAT, 4-13
.FIND, 4-13
WRITE$, 3-34
FOB, 3-35
Write logical record,
random mode, 3-28
sequential mode, 3-30
WRITE$ macro call,
format, 3-34 to 3-35
parameters, 3-35
Write virtual block, 3-34
Write-behind multiple
buffering, 2-19

WAIT$, 3-35 to 3-36
WAIT$ macro call,
format, 3-36

• XQIO, 4-20

Index-8

IAS/RSX-11
I/O Operations
Reference Manual
AA-M176A-TC

READER'S COMMENTS
NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the
company's discretion. If you require a written reply and are eligible to receive one under Software
Performance Report (SPR) service, submit your comments on an SPR form.

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

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent.

D
D
D
D
D
D

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with iittle programming experience
Student programmer
Other (please specify)

Organization
Street
State _ _ _ _ _ _ Zip Code _ _ _ _ __
or Country

DoNotTear-FoldHereandTape -

~nmnomn

No Postage
Necessary
if Mailed in the
United States

111111

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS ZK1-3/ J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03061

Do Not Tear - Fold Here