Digital PDFs

AA-2515D-TC

June 1979

262 pages

Original

12MB

Document:	IAS/RSX-11 I/0 Operations Reference Manual
Order Number:	AA-2515D-TC
Revision:	0
Pages:	262
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V3.2_Jun79/5A_FileMgmt_IO/AA-2515D-TC_RSX-11M_V3.2_IO_Operations_Ref_Man_197906.pdf

OCR Text

IAS/RSX-11
1/0 Operations
Reference Manual
Order No. AA-25150-TC

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

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

digital equipment corporation · maynard, mass~chusetts

First Printing, December 1975
Revised:
December 1976
December 1977
June 1979
The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corpo1:ation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may only be used or copied in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.

@) 1975, 1976, 1977, 1979 by Digital Equipment Corporation

The postage-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
""

DIGITAL
DEC
PDP
DEC US
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-11
VAX
DECnet
DATATRIEVE

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

4/B0-14

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

~
I

CONTENTS
Page
SUMMARY OE' TECHNICAL CHANGES

PREFACE

xiii

CHAPTER

FILE CONTROL SERVICES

1-1

l. l
l. 2
l. 3
l. 3.1
l. 4
l. 5
l. 6
l. 6 .1

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 (IAS ONLY)
SHARED ACCESS TO FILES
FILE DESCRIPTOR BLOCK (FOB)
DATASET DESCRIPTOR AND DEFAULT FILENAME BLOCK
KEY TERMS USED THROUGHOUT THIS MANUAL
SYSTEM CHARACTERISTICS

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

1.. 6. 2
1.. 7

1.. 8
1.. 9

1..10
1..11
1..12
CHAPTER

"--''

PREPARING FOR I/O
.MCALL DIRECTIVE - LISTING NAMES OF REQUIRED
MACRO DEFINITIONS
FILE DESCRIPTOR BLOCK (FDB)
2.2
2.2.1
Assembly-Time FOB Initialization Macros
FDBDF$ - Allocate File Descriptor Block
2.2.1.1
(FOB)
2.2.1.2
FDAT$A - Initialize File Attribute Section
of FDB
2.2.1.3
FDRC$A - Initialize Record-Access Section
of FDB
2.2.1.4
FDBK$A - Initialize Block-Access Section
of FOB
2.2.1.5
FDOP$A - Initialize File-Open Section of FOB
2.2.1.6
FDBF$A - Initialize Block-Buffer Section
of FOB
2.2.2
Run-Time FOB Initialization Macros
2.2.2.1
Run-Time FDB Macro-Call Exceptions
2.2.2 •.2
Specifying the FOB Address in Run-Time
Macro Calls
GLOBAL VERSUS LOCAL DEFINITIONS FOR FOB
2.3
OFFSETS
Specifying Global Symbols in the Source
2.3.l
Coding
Defining FOB Offsets and Bit Values Locally
2.3.2
CREATING FILE SPECIFICATIONS WITHIN THE USER
2.4
PROGRAM
2.4.l
Dataset Descriptor
Default Filename Block - NMBLK$ Macro Call
2.4.2
Dynamic Processing of File Specifications
2.4.3
OPTIMIZING FILE ACCESS
2.5
2.5.1
Initializing the Filename Block as a Function
of OPEN$x
2
2.1

i:Li

2-1
2-2
2-3
2-3
2-5
2-5
2-8
2-11
2-13
2-17
2-21
2-22
2-24
2-25
2-26
2-27
2-27
2-28
2-31
2-33
2-33
2-34

CONTENTS
Page
2-36
2-37
2-37
2-39
2-40

2.7.2
2.8
2.8.1
2.8.2
2.8.3

Manually Initializing the Filename Block
INITIALIZING THE 1~ILE STORAGE REGION
FSRSZ$ - Initialize FSR at Assembly-Time
FINIT$ - 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

FILE-PROCESSING MACRO CALLS

3-1

2.5.2
2.6
2.6.l
2.6.2
2.7
2.7.1

CHAPTER

3.1

OPEN$x - GENERALIZED OPEN MACRO CALL
Format of Generalized OPEN$x Macro Call
FOB Requirements for Generalized OPEN$x
Macro Call
3.2
OPNS$x - OPEN FILE FOR SHARED ACCESS
3.3
OPNT$W - CREATE AND OPEN TEMPORARY FILE
3.4
OPNT$D - CREATE AND OPEN TEMPORARY FILE AND
MARK FOR DELETION
3.5
OFID$x - OPEN FILE BY FILE ID
3.6
OFNB$x OPEN FILE BY FILENAME BLOCK
3.6.1
Dataset Descriptor and/or Default Filename
Block
3.6.2
Default Filename Block Only
3.7
OPEN$ - GENERALIZED OPEN FOR SPECIFYING FILE
ACCESS
3.8
CLOSE$ - CLOSE SPECIFIED FILE
3.8.1
Format of CLOSE$ Macro Call
3.9
GET$ - READ LOGICAL RECORD
3.9.1
Format of GET$ Macro Call
3.9.2
FDB Mechanics Relevant to GET$ Operations
3.9.2.1
GET$ Operations in Move Mode
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
FDB Requirements for READ$ Macro Call
3.16
WRITE$ - WRITE VIRTUAL BLOCK
3.16.l
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
DELET$ - DELETE SPECIFIED FILE
3.18.l
Format of DELET$ Macro Call
3 .1.1
3 .1. 2

2-40
2-41
2-42
2-42
2-44
2-45

3-2
3-5
3-8
3-12
3-12
3-13

3-14
3-14
3-15
3-16
3-16
3-18
3-18
3-18
3-19
3-20
3-21
3-21
3-22
3-23
3-24
3-24
3-25
3-26
3-26
3-28
3-30
3-30
3-31
3-33
3-34
3-34
3-35
3-35
3-36
3-38
3-38

. . . . . . .
..,.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
1
.

CONTENTS
Page
CHAPTER

FILE CONTROL ROUTINES

4.1
4.2
4.2.1

4-1

CALLING FILE CONTROL ROUTINES
4-1
DEFAULT DIRECTORY-·STRING ROUTINES
4-2
.RDFDR - Read $$FSR2 Default Directory
String Descriptor
4-2
4.2.2
.WDFDR - Write New $$FSR2 Default DirectoryString Descriptor
4-3
4.3
DEFAULT UIC ROUTINES
4-3
4.3.1
.RDFUI - Read Default UIC
4-4
4.3.2
.WDFUI - Write Default UIC
4-4
4.4
DEFAULT FILE-PROTECTION WORD ROUTINES
4-4
4.4.1
.RDFFP - Read $$FSR2 Default File Protection
Word
4-5
4.4.2
.WDFFP - Write New $$FSR2 Default
File-Protection Word
4-5
4.5
FILE OWNER WORD ROUTINES
4-5
4.5.1
.RFOWN - Read $$FSR2 File-Owner Word
4-6
4.5.2
.WFOWN - Write New $$FSR2 File-Owner Word
4-6
4.6
ASCII/BINARY UIC CONVERSION ROUTINES
4-7
4.6.l
.ASCPP - Convert ASCII Directory String to
Equivalent Binary UIC
4-7
4.6.2
.PPASC - Convert UIC to ASCII Directory
String
4-7
FILENAME BLOCK ROUTINES
4.7
4-7
4.7.1
.PARSE - Fill in All Filename Information
4-8
4.7.1.1
Device and Unit Information
4-9
4.7.1.2
Directory-Identification Information
4-10
4.7.1.3
Filename, File-Type or Extension, and File
Version Information
4-10
4-11
4.7.1.4
Other Filename Block Information
.PRSDV - Fill in Device and Unit Information
4.7.2
4-11
Only
4.7.3
.PRSDI - Fill in Directory-Identification
Information Only
4-12
.PRSFN - Fill in Filename, File-Type or
4.7.4
Extension, and File Version Only
4-12
.ASLUN - Assign Lbgical Unit Number
4.7.5
4-12
DIRECTORY ENTRY ROUTINES
4.8
4-13
.FIND - Locate Directory Entry
4.8.1
4-13
.ENTER - Insert Directory Entry
4.8.2
4-15
4.8.3
.REMOV - Delete Directory Entry
4-15
FILENAME BLOCK ROUTINES
4.9
4-16
4.9.1
.GTDIR - Insert Directory Information in
Filename Block
4-16
.GTDID - Insert Default Directory Information
4.9.2
in Filename Block
4-16
FILE POINTER ROUTINES
4.10
4-17
.POINT - Position File to Specified Byte
4-17
4.10.1
.POSRC - Position File to Specified Record
4-18
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-19
QUEUE I/O FUNCTION ROUTINE (.XQIO)
4-19
4 .11
RENAME FILE ROUTINE (.RENAM)
4-20
4.12
4-20
FILE EXTENSION ROUTINE (.EXTND)
4 .13
4-21
FILE TRUNCATION ROUTINE (.TRNCL)
4.14

CONTEN'l'S
Page

CHAPTER

4.15
4.15.1
4.15.2
4.16

FILE DELETION ROUTINES
.MRKDL - Mark Temporary File for Deletion
.DLFNB - Delete File by Filename Block
DEVICE CONTROL ROU'I1INE (. CTRL)

4-21
4-22
4-23
4-24

FILE STRUCTURES

5-1

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

COMMAND-LINE PROCESSING

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

GET COMMAND LINE (GCML)
6-2
GCMLB$ - Allocate and Initialize GCML
Control Block
6-3
GCMLD$ - Define GCML Control Block Off sets
6 .1. 2
and Bit Values
6-5
GCML Run-Time Macro Calls
6-9
6 .1. 3
GCML$ - Get Command Line
6-9
6.1.3.1
RCML$ - Reset Indirect Command File Scan
6-11
6.1.3.2
6-12
CCML$ - Close Current Command File
6.1.3.3
GCML Usage Considerations
6-12
6 .1. 4
COMMAND STRING INTERPRETER (CSI)
6-13
6.2
CSI$ - Define CSI Control-Block Off sets
6.2.1
6-14
and Bit Values
CSI Control-Block Offset and Bit-Value
6.2.2
Definitions
6-14
CSI Run-Time Macro Calls
6-17
6.2.3
CSI$1 - Command Syntax Analyzer
6-18
6.2.3.1
CSI$2 - Command Semantic Parser
6-19
6.2.3.2
CSI Switch Definition Macro Calls
6-21
6.2.4
CSI$SW - Create Switch Descriptor Table Entry 6-21
6.2.4.1
CSI$SV - Create Switch-Value Descriptor
6.2.4.2
Table Entry
6-26
CSI$ND - Define End of Descriptor Table
6-29
6.2.4.3
6.1
6.1.1

CHAPTER

THE TABLE-DRIVEN PARSER (TPARS)

CODING TPARS SOURCE PROGRAMS
7.1
TPARS Macros: !STAT$, STATE$, and TRAN$
7 .1.1
Initializing the State Table: the ISTAT$
7.1.1.1
Macro

·~j

7-1
7-1
7-2
7-2

....._. .__. . ,.............................. .............................................I.

--~--_,.

CONTENTS
Page

7,.1.1.2
7,.1.1.3
7~1. 2
7,,1.3
7.1.3.1
7,.1.3.2

Defining a Syntax Element: the STATE$ Macro
Defining a Transition: the $TRAN Macro
Types of Command Line Syntax Elements
Action Routines and Built-in Variables
TPARS Built-in Variables
Calling Action Routines
7,.1.3~3
Using Action Routines to Reject a Transition
7.1.3.4
Optional Debug Routine for RSX-11 Users
7 ,, l . 4
TPARS Subexpressions
7.2
GENERAL CODING CONSIDERATIONS
7.2.1
Suggested Arrangement of Syntax Types in a
State Table
7.2.2
Entering Special Characters
7.2.3
Ignoring Blanks and Tabs in a Command Line
7.2.4
Recognition of Keywords
PSECTs GENERATED BY TPARS MACROS
7.3
7.4
INVOKING TPARS
Register Usage and Calling Conventions
7.4.1
7.4.2
Using the Options Word
HOW TO GENERATE A PARSER PROGRAM USING TPARS
7.5
7.6
PROGRAMMING EXAMPLES
Parsing a UFO Command Line
7.6.1
How to Use Subexpressions and Reject
7.6.2
Transitions
7.6.3
Using Subexpressions to Parse Complex
Grammars

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

SPOOLING

8-1

8.1
8.2
8.3

PRINT$ MACRO CALL
.PRINT SUBROUTINE
ERROR HANDLING

8-1
8-2
8-2

APPENDIX A

FILE DESCRIPTOR BLOCK

A-1

APPENDIX B

FILENAME BLOCK

B-1

APPENDIX C

SUMMARY OF I/0-RELATED SYSTEM DIRECTIVES

C-1

APPENDIX D

SAMPLE PROGRAMS

D-1

APPENDIX E

INDEX FILE FORMAT

E-1

BOOTSTRAP BLOCK
HOME BLOCK
INDEX-FILE BIT MAP
PREDEFINED FILE-HEADER BLOCKS

E-1
E-2
E-2
E-2

FILE-HEADER BLOCK FORMAT

F-1

HEADER AREA
IDENTIFICATION AREA
MAP AREA

F-3
F-4
F-5

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

G-1

VOLUME AND FILE LABELS
Volume Label Format

G-1
G-1

CHAPTER

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

vii

7-7
7-8
7-8
7-9
7-9
7-10
7-11
7-11
7-12
7-14
7-14
7-18
7-19

CONTENTS
Page
Contents of Owner Identification Field
User Volume Labels
File-Header Labels
File Identifier Processing by Files-11
End-of-Volume Labels
File-Trailer Labels
User File Labels
FILE STRUCTURES
Single File Single Volume
Single File Multivolume
Multifile Single Volume
Multifile Multivolume
END-OF-TAPE HANDLING
ANSI MAGNETIC TAPE FILE HEADER BLOCK (FCS
COMPATIBLE)

G-2
G-3
G-3
G-5
G-7
G-7
G-7
G-7
G-8
G-8
G-8
G-8
G-8

APPENDIX H

STATISTICS BLOCK

H-1

APPENDIX I

ERROR CODES

I-1

APPENDIX J

FIELD SIZE SYMBOLS

J-1

APPENDIX K

RSX-llM/M-PLUS FCS LIBRARY SYSGEN OPTIONS

K-1

G.1.1.l
G. l . 2
G. l. 3
G.1.3.1
G. l . 4
G. l . 5
G. l. 6

G.2
G.2.1
G.2.2
G.2.3
G.2.4
G.3
G.4

INDEX

G-8

Index-1
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
G-1
H-1

File-Access Operation
Record I/O Operations
Single Buffering Versus Multiple Buffering
Directory Structure for Single-User Volumes
1)irectory Structure for Multiuser Volumes
Data Flow During Command Line Processing
Format of Switch Descriptor Table Entry
Format of Switch-Value Descriptor Table Entry
Processing Steps Required to Generate a
Parser Program Using TPARS
Flow of Control When TPARS is Called from an
Executing User Program
File Descriptor Block Format
Filename-Block Format
ANSI Magnetic Tape File-Header Block
(FCS Compatible)
Statistics Block Format

1-2
1-3
1-7
5-2
5-3
6-2
6-26
6-28

7-13
7-14
A-2
B-2

G-9
H-1

TABLES
TABLE

2-1
3-1
4-1
A-1
B-1
B-2
C-1

Macro Calls Generating FDB Information
File Access Privileges Resulting from OPEN$x
Macro Call
R2 Control Bits for .EXTND Routine
FDB Off set Definitions
Filename-Block Offset Definitions
Filename-Block Status Word (N.STAT)
Summary of I/0-RelatE~d System Directives

2-2

3-3
4-22
A-3
B-1
B-2
C-1

viii

•t•a•...

............,............................................................~.•1111.........................•1. .

111111111. . .~•~f'.,.

CONTENTS
TABLES {Cont.)
Page
TABLE

E·-1

F-1
G-1
G·-2
G·-3

Home-Block Format
File Header Block
Volume Label Format
File-Header Label {HDRl)
File-Header Format {HDR2)

E-3

F-1
G-1
G-4
G-5

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

--9..--,·----~

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

-.~

SUMMARY OF TECHNICAL CHANGES

This rev1s1on of the I/O Operations Reference Manual contains
and additions relative to the items listed as follows:

changes

File control services described in this manual
in RSX-llM-PLUS systems.

"Big buffer" support is provided, allowing block-buffer sizes
in excess of 1 disk block to be specified in the File
Descriptor Block for record
I/O operations.
(See Section
2.2.1.6.)
By using
this technique,
generally fewer disk
operations are required, and
file
access time
is
reduced
accordingly.

The Table-Driven Parser (TPARS) has a new entry point added
allowing
the
use of a user-supplied debug routine.
The use
of a debug routine will allow monitoring TPARS operation by
automatically entering
the debug
routine at each state
transition.

4 .•

Appendix K is added,
listing RSX-llM/M-PLUS FCS library
SYSGEN options.
A brief description of each option is
provided.

are

included

·~-::
!

~·

. I

. I4

Ti•

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 program-developmerit 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
likewise 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 the user 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 the user must
define within a particular program in order to use any of the
file
control
services provided by the system.
Unless the user
is
thoroughly familiar with the content of this chapter, he is 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 that allow
manipulate files and to perform I/O operations.

the

user

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, etc.
ChaptE~r

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.

xiii

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 lineso 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 (TPARS) which provides the
user with the means to define and parse command lines in a unique
user-designed syntax.
Chapter 8 describes the queuing of files for printing. This
is available at both the MACRO level and subroutine level.

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 (FOB) 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/O-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 file descriptor block.
These sample programs also include some of the macro calls that are
used for processing files.

·~I.
'I

Appendix E illustrates the structure of the index file of a Files-11
volume, while Appendix F describes tn 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 the appropriate IAS and RSX-11 Documentation
Directories.
The Documentation Directories define the
intended
readership of each manual in the ctppropriate set and provide a brief
synopsis of each manual's contents.

~
I

CONVENTIONS USED IN THIS DOCUMENT

Unless otherwise noted, the term RSX-11 refers
RSX-llM-PLUS.

both

RSX-llM

and

~·

xiv

Ji Ji¥

CHAPTER l
FILE CONTROL SERVICES

IJ\S and RSX-11 file control services (FCS) enable the user 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, the user issues
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 requested by the user (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 a
user interface to the file system, enabling the user to read and write
files on file-structured devices and to process files in terms of
l1::>g ical records~
Logical records are regarded by the user 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. Data can be retrieved from the file without
the user's having to know the exact format in which it was written to
the file.
FCS thus is virtually transparent to the user so that records can be
read or written in logical units that are consistent with particular
application requirements.

1-1

FILE CONTROL SERVICES

USER-ISSUED MACRO CALL

FILE CONTROL SERVICES

FILE CONTROL PRIMITIVES

HAR~

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

Figure 1-1

___J

File-Access Operation

FCS provides an extensive set of macros to simplify the user's
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
ASCII
filename
information required when
specified file

A default filename block that is accessed by FCS to obtain
default filename
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
working storage.

(FSR)

that

used

to obtain
opening a

FCS

for

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

!AS and RSX-11 support both sequential and random access to data
in
files.
The sequential-access method is device-independent, i.e~,
sequential access can be used
for
both
record-oriented
and
block-addressable devices (e.g., card reader and disk, respectively).
The random-access method can be used only for block-addressable
devices.
~.
····"'ff.

!"'''

1-2

o .a

FILE CONTROL SERVICES
1. 2

FILE STORAGE REGION (FSR)

The file storage region (FSR) is an area allocated in the user 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.
The
user determines the size of this area at assembly-time
by issuing the FSRSZ$ macro call (see Section 2.6.l).
The number of block buffers and associated headers is
based on the number of files that the user intends 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;
other portions are
maintained by FCS.
The size of the FSR can be changed, if desired,
at task-build time.
Section 2.7 presents the procedures that provide this flexibility to
the programmer.
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 likewise accomplished
in the
FSR block buffer during output. Note also that FCS serves as the user
interface to the FSR-block-buffer pool.
All
record I/0 operations,
which are initiated through GET$ and PUT$ macro calls, are totally
synchronized by FCS.
Record I/O operations are described in detail in Section 1.5.

BLOCK
BUFFER
POOL

r---------..

DEVICE

FCS

$$FSR2
IMPURE DATA

Figure 1-2

Record I/O Operations

1-3

USER
RECORD
BUFFER

FILE CONTROL SERVICES
1.3

DATA FORMATS FOR FILE-STRUCTURED DEVICES

Data are 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 a user program. In FCS terms, a
virtual block in a file consists of 512(10) bytes. The size of the
logical records in the virtual blocks is under the control of the user
program that originally writes the records.
When creating a new file, a user program can specify that the records
in the file need not all be the same size. Such records are known as
variable-length records. Conversely, if the user 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 two-word record header.
The first word
contains the length of the record and the second word contains the
value of the sequence number:
16

.____s_v_te_c_o_u_n_t_ ___.__s_e_q_ue_n_c_e_N_u__
m_be_r_

_.___n_-_2_b....,,yte~

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

Byte Count

single-word

nbyte~o8

,___----~--____,,(

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, while 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

Both fixed- and variable-length records may be used on magtape;
format conforms to the ANSI standard.

their

On magtape, a virtual block corresponds to a physical record.
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 2048 bytes with the use of the FDBF$ macro (see Section 2.2.1.6).
Records are not allowed ~o cross block boundaries.
Fixed-length records are packed into a block with no
control
information and no padding for alignment. The block is truncated so
that it ends at the end of the last record that will fit in the block
buffer.

101111

FILE CONTROL SERVICES
Variable-length records are preceded by a 4-byte count
field,
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 ("~",ASCII code 136), which appears where the next byte
count should be, signals the end of data in that block.

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
ds1ta, since such operations do not involve the blocking and deblocking
of records within the file. Also, in block I/O operations, the user
may read or write files in an asynchronous manner, i.e., control may
be returned to the user program before the requested I/O operation is
cc>mpl eted.
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, the user is responsible for synchronizing all block
I/O operations.
Such asynchronous operations may be coordinated
through an event flag
(see Section 2.8.1)
specified
in
the
READ$/WRITE$ macro call.
The event flag is used by the system to
signal the completion of a specified block I/O transfer, enabling the
user to coordinate those block I/O operations that are dependent on
ec:tch other ..

luS

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 the user 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. The user 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
mc>de can access records anywhere within the file. To do so, the user
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 the user
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.

1-5

FILE CONTROL SERVICES
In contrast to block I/O operations, all
record I/O operations are
synchronous,
i.e., control is returned to the user 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
actual
I/O transfer
(e.g., 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.

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

Move Mode

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

1.6.2

Locate Mode

Locate mode enables the user to access records directly in the FSR
block buffer.
Consequently,
there
is normally no need to transfer
data from the FSR block buffer to the user record buffer.
To access
records directly in the FSR block buffer, the user refers 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 file descriptor
block as a result of FCS macro calls issued by the user.
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-6

•

FILE CONTROL SERVICES
1.7

'-"'

MULTIPLE BUFFERING FOR RECORD I/O (IAS ONLY)

By supporting multiple buffers for record I/O, FCS provides the
capability for IAS users to read data into buffers in anticipation of
user program requirements and to write the contents of buffers while
the user program is building records for output. The user 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, any file-access method can be
used with full benefit.
When multiple buffering is used, sufficient space in the FSR must be
allocated 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
Buffer

pro cess record

write record

process record

write record

Multiple
Buffer

proc.ess record

write record
process record

process record
write record

write record
process record

Figure 1-3

1.8

Single Buffering Versus Multiple Buffering

SHARED ACCESS TO FILES

Files-11 permits shared access to files according to established
conventions.
Two macro calls, among several available in FCS for
opening files, may be issued 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.

1-7

FILE CONTROL SERVICES
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.
The OPNS$x and OPEN$x macro calls may be used as
access to files:

follows

for

~:,'
t--- -1f

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, the
synchronization of 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 assures 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 activa. {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 imply the presence
of read requests from several separate tasks. The same task, for
example, may open the same file using different logical unit numbers.

1.9

FILE DESCRIPTOR BLOCK (FDB)

The file descriptor block {FOB) contains information used by FCS in
opening and processing files. One FDB is required for each file that
is to be opened simultaneously by the user program.
The user
initializes some portions of the FDB with assembly-time or run-time
macro calls, and FCS maintains other portions.
Each FDB has five
sections that contain user or system-initialized information:

~,!

• File-Attribute Section;
• Record- or Block-Access Section;
• File-Open Section;
• Block-Buff er Section; and the
• 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 FOB.

~'I

1-8

,...........,.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19111&•0. . . . . . . . . . .~,~·-

FILE CONTROL SERVICES
1.10

DATASET DESCRIPTOR AND DEFAULT FILENAME BLOCK

Normally, either a dataset descriptor or a default filename block is
specified for each file the user intends 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 the user program by issuing the
FDBDF$ macro call (see Section 2.2.1.1). Each file to be opened
simultaneously by the user 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 user
initialization of the FDB. The format and content of the FDB are
detailed in Appendix A.
FJ:LENAME Bf.. OCK
The portion of the FDB that contains the various elements of a
file specification (i.e., 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 the user
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.
The user
creates 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.
1-9

FILE CONTROL SERVICES
DATASET DESCRIPTOR
The dataset descriptor is a 6-word block in the user program
containing the sizes and the addresses of ASCII data strings that
together constitute a file specification (see below). This data
structure, which is also created by the user, is described in
detail in Section 2.4.1. Unless the filename block
in the FOB
has
been
initialized,
data
set-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 the user program.
This address value is stored in the
FDB, allowing FCS to access a user-c:reated 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
reserved by the user
for use in I/O operations. This area is
allocated by issuing the FSRSZ$ macro call in the user program
(see Section 2.6.1).

1.12

SYSTEM CHARACTERISTICS

Listed below are the important characteristics of FCS that
borne in mind in using its I/O facilities:

should

READ$/WRITE$ operations . are asynchronous;
the user
is
responsible for coordinating all block I/O activity.
In
contrast, GET$/PUT$ operations are synchronized entirely by
FCS;
control
is not returned to the user 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 the
FDB address in RO.

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

return

The FDBDF$ macro call (see Section 2.2.1.1)
is issued to
allocate space for
an FDB.
Once the FDB 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.l
and
2.2.2,
respectively).
Certain information must be present in the
FDB before FCS can open and operate on a specified file.

1-10

,.._~._.......!111111. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

FILE CONTROL SERVICES
4.

For each assembly-time FDB initalization macro call, a
corFesponding
run-time macro call is provided that supplies
identical information. Although both sets of macro calls
(se~
Table 2-1) place the same information in the FDB, 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 FDB during program
execution ..

If an error condition is detected during any 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-bit
(carry condition code)
in the
Processor Status Word is set,
and an error indicator
is
returned to FDB offset location F.ERR.
NOTE
When I/O is being done
using
the
READ$/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-11

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 the user program (see Section 2.2).
• Define a dataset descriptor and/or a default filename block
(see Section 2.4.1 or 2.4.2, respectively) if the user intends
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

Section

Data supplied during the assembly of the source program establish 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.
Likewise,
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

PREPARING FOR I/O
Table 2-1
Macro Calls Generating FDB Information

2.1

Assembly-Time FDB
Macro Calls

Run-Time FDB
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
the
user intends to issue in a program must
first be listed as arguments in an .MCALL directive.
So doing allows
the
required macro definitions to be read in from the system macro
library during assembly.

·~.
11;

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

argl,arg2, ••• ,argn

argl,
etc.

represents a list of symbolic names identifying
the macro definitions required in the assembly of
the user 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,
irrespective of functional use.
All
these options are matters of preference and have
no effect whatever on the
retrieval of 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 {CS!), all the names of the associated
macros must also be listed as arguments
in an
.MCALL
directive.
GCML and CS!,
ordinarily
employed in system or application programs for
convenience
in
dynamically
processing
file
specifications, are described in detail in Chapter
6.
2-2

n-.--r--...ii,_.._._......llllllllllllll. . . . . .J$•-•L•.B._£. ..i.•&. . . .~. . . . . . .,_.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.

PREPARING FOR I/O
The .MCALL directive is described in detail in the IAS/RSX-11 MACR0-11
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 preparato(y, 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 the user program at task-build time from the system object
library ([l,l]SYSLIB.OLB). The reader 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$ 1 FINIT$
OPEN$R,OPEN$W,GET$,PUT$,CLOSE$
NOTE
The macro FCSMC$ can be used to
.MCALL
the most commonly used FCS macros, as
follows:
.MCALL
FCSMC$

FCSMC$

FCS macros
.MCALLed 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 .MCALL macros is
that
unused
macros
may
take
up
possibly-critical assembler symbol table
space,
slowing
down
the
assembly
process.

2.2

FILE DESCRIPTOR BLOCK (FOB)

The file descriptor block (FOB) 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 FOB 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 FOB 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

2-3

PREPARING FOR I/O
issued to establish other required information in this structure. 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
where:

~J
,J ..

pl,p2, ••• ,pn

mcnam$A

represents the symbolic name of the macro.

pl,p2,

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

••• ,pn

FOOP$A

2,0SPT,OFNB

Assume further that the second parameter field is
to be coded as a null specification. In this
case, the statement is coded as follows:
FOOP$A

~~, ,OFNB

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
FOOP$A

2,0SPT,OFNB

need not be specified as
FOOP$A

2,0SPT,

if the last parameter (OFNB) is omitted.
Rather,
such a macro call is specified as follows:
FOOP$A

2,0SPT

If any parameter is not specified, i~e., if any field in the macro
call contains a null specification, the corresponding cell in the FOB
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 (1)
between the values, indicating a logical OR operation to the MACR0-11
assembler.
The use of 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 (e.g~, F.RTYP).
These symbols are
defined as offsets from the beginning address of the FOB, allowing
specific locations within the FOB to be referenced.
Thus, the
programmer can reference or modify inf~rmation within the FOB 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 FOB
to be changed (in a subsequent release, for example) without affecting
the user's current programs or the coding style employed in developing
new programs.

2-4

...,i..~~...............4•1•t•£111111. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .,J.............4llll•l•¥. . . .llll!l. . . . . . . . . . . . . .SS!
.•.N.t•
. . ll!lllJ";IPIP

~,r._

PREPARING FOR I/O

'--1'

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 a file descriptor block (FDB). This macro call must
be specified in the source program once for each input or output file
to be opened simultaneously by the user 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 the user desires to accomplish the initialization
of certain portions of this FDB during assembly.
The FDB allocation macro takes the following form:
1 ab el :

F'DBDF$

where:

label

represents 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 FpB 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$

must embody one FDBDF$ macro call
for
each file
to be accessed
FDB's can be reused
for many
currently using the FDB is closed
only requirement is that an FDB
opened simultaneously.

As noted earlier, the source program
logically similar
to
those above
simultaneously by the user program.
different files, as long as the file
before the next file is opened. The
must be defined for every file to be

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,~loc
/

where:

r.typ

represents 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:
R.FIX - Indicates that fixed-length records are to
be written in creating the file.
R.VAR - Indicates that variable-length records are
to be written in creating the file.

2-5

PREPARING FOR I/O
R.SEQ - Indicates
variable-length
sequenced
records are to be written in creating the file.
This parameter
initializes FDB offset location
F.RTYP.
Since the symbols R.FIX, R.VAR, and R.SEQ
initialize the same location in the FDB,
these
values are mutually exclusive.
ratt

represents 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 will 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, e.g., a line printer or a
terminal.
FD.BLK - Indicates that records are not allowed to
cross block boundaries.
These parameters initialize
the record-attribute
byte
(offset location F.RATT)
in the FDB.
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
(e.g.,
FD.CR!FD.BLK).

rsiz

represents 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 FDB 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

represents 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

aa "'"'

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, anq,,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.
If the user has a firm idea as to the desired
length of the file,
it is more efficient to
of
blocks
at
allocate the required number
file-create time through this parameter, rather
file,
if
than requiring FCS to extend the
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, i.~., 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.
This action is especially necessary if the FDB is
to be re-used.
aloe=

represents 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 non-contiguous, even when aloe is a
positive value.
Negative
Value - Indicates
that
the
complement of the specified number of blocks
be allocated noncontiguously as additional
within the file, and further that the file
be noncontiguous.

two's
is to
space
is to

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

2-7

PREPARING FOR I/O
1.

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.

If only 1 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 estc1blished 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 the creation of
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 more than one record attribute is specified in the ratt parameter
field, such specifications must be separated by an exclamation point
(1), as shown below:
FDAT$A

R.VAR,FD.FTNIFD.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
operations (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.
Prior to issuing the OPEN$x macro call to initiate file operations,
the FDB must be appropriately initialized to indicate whether record
or block I/O operations are to be used in processing the associated
file.

2-8

PREPARING FOR I/O

The FDRC$A macro call takes the following format:
FDRC$A
whe!re:

racc,urba,urbs

race

specifies which variation of block or record I/O
is to be used t~ process the file. This parameter
byte
{offset
initializes
the
record-access
location F.RACC)
in the FOB.
The first value
below applies only for block I/O {READ$/WRITE$)
operations;
all remaining 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 FOB. 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 the user wish to perform a PUT$ operation
within the body of a file, the .POINT routine
described in Section 4.10.1 may be calied.
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.

2-·9

PREPARING FOR I/O
If FD.INS
is not specified,
a PUT$ operation
within the file truncates the.file at the point of
insertion, i.e.,
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

represents 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. This parameter
is specified
only for record I/O operations.

urbs

represents 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.
This parameter
is specified only for
record I/O operations.

The user allocates and labels a record buffer
a
.BLKB or .BLKW directive.
The address and
then passed to FCS as the urba and the urbs
example,
a user record buffer may be defined
is logically equivalent to that shown below:
RECBUF:

• BLKB

in a program by
issuing
the size of this area is
parameters above.
For
through a statement that

82 •

where RECBUF is the address of the buffer and 82(10)
bytes) •

is its

size

(in

Under certain conditions, the user 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 160(10).
If more than one value is specified in the record-access (race) field,
multiple values must be separated by an exclamation point (!), as
shown below:
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-10

.....,..."'1...........................................................................11!111!!1111. . . . . .,. . . . . . . . . . . . .11111!11. . . . . .f.lllfilc

PREPARING FOR I/O
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 the user to read or write virtual blocks of data within a file.
As noted in the preceding section,
issuing the FDBK$A macro call
implies that the FDRC$A macro call has also been specified, since it
is through the FD.RWM parameter of the FDRC$A macro call that the
initial declaration of block I/O operations is accomplished. Thus,
for block I/O operations, the FDRC$A macro call must be specified, 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.
When block I/O operations are desired,
the FDB must be properly
initialized through the FDBK$A or the FDBK$R macro call prior to
issuing a generalized OPEN$x macro call that references the FDB.
If
record I/O operations are to be employed, the FDBK$A or the FDBK$R
macro call must not be issued.
The FDBK$A macro call is specified in the following format:
FDBK$A
where:

bkda,bkds,bkvb,bkef ,bkst,bkdn

bkda

represents 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

represents 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(10) bytes.

bk vb

represents 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/a-initiating READ$ and WRITE$ macro calls
(see
Sections 3.15 and 3.16, respectively).

2-11

PREPARING P'OR I/O

This dummy parameter need be reflected as a null
specification (wi.th 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
positionality of any remaining field(s) in the
parameter string.
bkef

represents a numeric value that specifies an event
flag to be used during REAO$/WRITE$ operations to
indicate the completion of a block I/O transfer.
This parameter initializes FOB offset location
F.BKEF; if not specified, event flag 32(10) is
used by default.
The function of an event flag is
further detail in Section 2.8.1.

bk st

~
I.

described

represents the symbolic address of a 2-word I/O
status block in the user 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, the user is
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
are described in detail in Section 2.8.2.

bkdn

block

represents 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 FDB offset
location F.BKON.
Considerations relevant to the use of an AST
service routine are presented in Section 2.8.3.

2-12

SSU.

!¥

;:a•

PREPARING FOR I/O
The following example shows an FDBK$A macro call that utilizes all
available parameter fields for initializing the block-access section
of the FDB:
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(10)-byte
block. The virtual-block number is null (for the reasons stated above
in the description of this parameter), and the event flag to be set
upon block I/O completion is 20(10).
Finally,
the symbol !STAT
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 FOB The FDOP$A
macro call is used to initialize the file-open section of the FOB.
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 FOB 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."
'fhis 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

·represents a numeric value that specifies
a
logical unit number.
This parameter initializes
FOB 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

represents 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
filename
descriptor, as outlined in Section 2.4.1.

2-13

PREPARING FOR I/O

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.
When the Command String Interpreter (CSI) 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 CSI
as a
dynamic command-line processor
is described in
detail in Section 6.2.
dfnb

represents 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

one,
or
any
appropriate
represents
any
combination,
of
the
following
symbolic values
indicating how the specified
file
is
to
be
accessed:
FO.RD - Indicates that an existing file is
opened for reading only.

FO.WRT - Indicates that a
new
created and opened for writing.

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

FO .MF'Y - Indicates that an existing file is to
opened for modifica1tion.

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

file

FA.NSP - Indicates,
in combination with FO.WRT
above,
that an old
file
having
the same file
specification is not be to 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,
that the created file is to be a temporary
file.

2-14

. .,.

l~-..--~-------- ----------------··---------------1--.-----~

PREPARING FOR I/O
FA.SHR - Indicates that the file is to
for shared access.

opened

The face parameter initializes FOB offset location
F.FACC.
The symbolic values FO.xxx, described
above, represent the logical OR of bits in FOB
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.
actl

represents a symbolic value that is used to
specify the following control information in FOB
location F.ACTL:
l.

Magnetic tape position.

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

Number of retrieval pointers to allocate for a
disk file window.

Normallly, FCS supplies default values for F.ACTL.
However,
if FA.ENS is specified in combination
with any of the symbolic values described below,
FCS uses the information in F.ACTL.
FA.ENS.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
positioned to the end of the volume set.

are

At file open and close, tapes are not rewound.
A disk file that is opened for write is locked
if it is not properly closed.
The volume
window.

default

used

for

the

file

The values listed below can be used in conjunction
with FA.ENS.
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 the creation of 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.RWO - Is specified to cause a magnetic tape
be rewound when the file is opened or closed.

Examples of the use of FA.ENS with
FA.RWO are provided in Section 5.2.8.

and

2-15

FA.POS

PREPARING FOR I/O
FA.OLK - Is specified to cause a disk file not
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-window 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
incr~asing the number of retrieval pointers, i.e.,
by increasing the size of the window.
Likewise,
additional memory can be freed by reducing the
number of pointers for files with little or no
fragmentation, e.g., contiguous files.
As noted, if neither the dspt nor the dfnb parameter is specified,
corresponding offset locBtions 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 ~his FDB. Normally,
these cells are initialized at assembly-time through the FDOP$A macro
call;
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 datas~t-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 pointer and a
default filename block 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 CSI dataset descriptor.
This
structure is created in the CSI control block through the invocation
of the CSI$ macro call. All considerations relevant to the use of CSI
as a dynamic command line processor are presented in Section 6.2.
2-16

ii I st

'' .:r••

PREPARING FOR I/O
The last example illustrates the use of the parameter actl to increase
the number of retrieval pointers ~n the file window to 16.
FA.ENB is
specified to cause the contents of F.ACTL, rather than the defaults,
to be usedo
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.2.1.6 FDBF$A - Initialize Block-Buffer Section of FOB - 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
where:

efn,ovbs,mbct,mbfg

efn

represents 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(10)
is used by default.
A null specification
in this field is indicated by inserting a
leading
comma in the parameter string.

ovbs

represents 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(10), overriding the standard 512(10) (one
sector) block-buffer size.
Block-buffer sizes up
to 63 sectors (32256(10) 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(10)
bytes
(4 sectors) or 2560(10) bytes (5
sectors) is recommended since 2048(10) bytes also
provides
ANSI magtape buffer capability, and
2560(10) 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.

2-17

PREPARING FOR I/O
NOTE
When block-buffer sizes greater
than l
sector
(512(10))
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 !AS 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
spooled output to a record-oriented device, do not
allocate a buffer less than a
single sector
(512(10) bytes).
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(10)
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 each device is established
at SYSGEN time, or via the MCR SET/BUF command.
mbct

represents a numeric value that specifies the
multiple buffer count, i.e., 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
O,
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 default buffer count of
1.
If desired,
this value can be modified, as
noted
in the discussion following
the
mbfg
parameter below.

2-18

.,......,l.... ...-...,.11111. . . .
~t•

a•4•.·•azs•.•-•-. . . .""'. . . . . . . . . . . . . . . . . . . . . . . . .,. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .....

PREPARING FOR I/O
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
card reader), F.MBCT should not be greater than 2.
mb:fg

represents 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 operations
to be used in processing the file.
FD.WBH - Indicates that write-behind
are to be used in processing the file.

are

operations

These parameters are mutually exclusive, i.e., one
or the other, but not both, may be specified.
Specifying this parameter assumes that the buffer
count established in the mbct parameter above is
greater than l.
If multiple buffering has thus
been declared, the omission of 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,
the user 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
each time the associated file is closed.

2-19

PREPARING roR I/O
NOTE
When using write-behind multi-buffering,
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 operations1 thus, only 80%
of the write-behind operations
will
actually be overlapped with processing.
This percentage can be increased as
follows a
1.

Space for the file can be completely
pre-allocated, either by use of the
"cntg" parameter in
the
FDOP$x
macro,
or
by using the .EXTND
subroutine.

The default extension amount can be
increased from 5 blocks by use of
the "aloe" parameter of the FDAT$x
macro call.
For example, if an
"aloe" parameter
of
10(10)
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 pre-existing
locations
in the file does not
require extends, the percentage of
overlapped operations is increased.

For IAS, the default buffer count can be changed, 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 S&ction 2.7.2) to allocate more space for the
FSR block buffers.

Because the above procedure alters the default buffer count for all
files to be processed by the user 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, the buffer count in F.MBCT
for a specific file may be set to 1 by issuing the following ma~ro
call for the applicable FOB:
FDBF$A

, ,1

2-20

PREPARING roR I/O

"--".·

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 fiag (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
ti

The following examples are representative of the FOBF$A macro call
it might appear in a program:
FOBF$A

25.,, l

FOBF$A

25.,,2,FO.RAH

FOBF$A

,,2,FO.WBH

The first example specifies that event flag 25(10) 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(10) for synchronizing
record I/O operations, and in addition establishes 2 as the multiple
buffer countti 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(10) to be used by default for
synchronizing 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, i.e., 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.2o2

Run-Time FOB Initialization Macros

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

- Initializes or alters the file-attribute
the FOB.

section

FORC$R

- Initializes or alters the
the FOB.

section

FOBK$R

- Initializes or alters the block-access section of the
FOB (see Item 4 below).

FOOP$R

- Initializes or alters the file-open
FOB.

FOBF$R

- Initializes or alters the block-buffer section of the
.E'OB.

record-access

section

the

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

2-21

PREPARING FOR I/O
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
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:
a.

#FDBADR,#1,#DSPT,#DFNB

If the parameter is the address of a location containing
an argument that is to be placed
in the FDB, the
parameter must not 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
containing the desired initializing value.
c.

character

If the parameter is an address value or a literal value
that is to be placed in the FDB, i.e., if the parameter
itself is to be taken as an argument, it must be preceded
by the number sign
{#). 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

last

location

Also, if the parameter is a
register specifier
{e.g.,
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
{FDB address).
Any other use
of RO will fail.
{See Section 2.2.2.2,
items 1 and 2.)

·~.
I

2-22

PREPARING FOR I/O
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 a~yuments in MOV and MOVB machine
instructions.
4.

As noted in the description of the FDBK$A macro call
in
Section 2.2.1.4, assembly-time initialization of the FDB with
the virtual-block number is meaningless,
since issuing the
OPEN$x
macro
call
to prepare a file for processing
automatically resets the virtual-block number in the FDB 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/O-ini t i a ting 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, the user must reserve and label a
2-word
block in the program which is to be used for temporarily
storing the virtual-block number appropriate for
intended
block I/O operations.
Since the user is 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 (i.e., the label) of this field as the bkvb parameter
in the selected run-time macro call, the virtual-block number
is made available to FCS.
In preparing for block I/O operations, the following
procedures must be performed:
a.

general

At assembly-time, reserve a 2-word block in the user
program through a statement that is logically equivalent
to the following:
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 call
for
initializing the FDB.

At run-time,
load
this
field
with
the
desired
virtual-block number. ~rhis 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.

2-23

PREPARING JrOR I/O
If the desired virtual-block number cannot be completely
expressed within 16 bits, the remaining 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

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.
The
user must ensure that the sign bit in the high-order word
is not set.
c.

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
FOB with the desired virtual-block number.
If the FDBK$R macro call is elected, the following
representative example:
FDBK$R

#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 O 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 the user, however, choose 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,#INBUF,#BUFSIZ,#VBNADR

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

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
FOB 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$

2-24

'--r-~r-·-----llllP'----.,.----------·1:•t••·--·-----------------i
1

PREPARING FOR I/O

in addition to allocating space for an FOB at assembly time, binds the
label FOBOUT to the beginning addxess of the FOB 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,
as follows:
1.

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

#FOBOUT,#R.VAR,#FO.CR

The argument FOBOUT is taken literally by FCS as the address
of an FOB; furthermore, this address value, by convention,
is stored in general register zero (RO).
Whenever this
method of specifying the FOB address is employed, the
previous contents of RO are overwritten (and thus destroyed).
Therefore, the user must exercise care in issuing subsequent
run-time macro call~ 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 RO.
The previous contents of RO are overwritten
(and thus destroyed).
The following statement reflects the
register to specify the FOB address:
FOAT$R

use

general

RO,#R.VAR,#FO.CR

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

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

initial

,#R.VAR,#FO.CR

In this instance, the current contents of RO are taken by
default as the address of the associated FOB. As in method 2
above, RO is assumed to contain the address of the desired
FOB. Although the comma in this instance constitutes a valid
specification, the user is advised to employ methods l and 2
for consistency and clarity of purpose.
In relation to the foregoing, it should be understood that these three
methods of specifying the FOB address also apply to all the FCS
file-processing macro calls described in Chapter 3.

2.3

GLOBAL VERSUS LOCAL DEFINITIONS FOR FOB OFFSETS

Although the FOB offsets can be defined either locally or globally,
the design of FCS does not require that the user be concerned with the
definition of FOB offsets locally.
To some extent, this design
consideration is based on the manner in which MACR0-11 handles
symbols.

2-25

PREPARING FOR I/O
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.l

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)

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,
the user 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 likewise 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-26

PREPARING FOR I/O

Defining FDB Offsets and Bit Values Locally

2.3.2

The user who wisht~s to declare explicitly that all FOB offsets and bit
values are to be defined locally may do so by invoking two macro calls
in the source program. The first of these, FOOF$L, causes the offsets
for FOB's to be defined within the user program. Similarly, bit
values for all FOB parameters may be defined locally by invoking the
FCSBT$ macro call. These macro calls may be invoked anywhere in the
user program.
When issued, the FOOF$L and FCSBT$ macro calls
manner roughly equivalent to:
F.RTYP
F.RACC
F.RSIZ

define

symbols

xx xx
xx xx
xx xx

where xxxx represents the value assigned to the corresponding symbol.
In other words, the macros for defining FOB 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 or not the FOOF$L and FCSBT$ macro calls are
invoked should
not in any way affect the coding style or the manner in which the FOB
offsets and bit values are used.
Note, however, if the FOOF$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 FOOF$L macro call aut~matically defines all
FOB offsets locally, including those for the filename block.
If any of the above named macro calls is to be issued in the user
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 FOB
before the file can be opened.
The file is located using a file
specification that contains the following:
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 (UFO) to be used
for the file.
The term "UFD" is synonymous with the term
"file directory string" appearing throughout this manual.

3•

A f i l en am e ;

A file type (RSX-11) or file extension (IAS);

A file version number.

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

2-27

synonym

for

"file

PREPARING FC)R I/O

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

The dataset descriptor.
This tabular structure may be
created and
initialized manually through the use of .WORD
directives.
Section 2.4.l describes this data structure in
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 the user 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.s, 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 non-null data contained therein is
translated from ASCII to Radix-SO form and stored in the appropriate
offsets of the
fil~name 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 specifiedQ
The FCS file-processing macro calls used
in opening file~ 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.4.l

the

filename

Dataset Descriptor

The dataset descriptor is often oriented toward the use of a fixed
{built-in) filename in the user 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 may be created manually
within the user program through the use of .WORD directives, contains
information describing a file that the user intends to open during the

2-28

SW.

.~·

PREPARING FOR I/O
course of program execution.
In creating this structure, any one or
all of three possible string descriptors may be defined for
a
particular file, as follows:
1.

A 2-word descriptor for an ASCII device name string;

A 2-word descriptor
and/or

A 2-word descriptor for an ASCII filename string.

for

ASCII

file

directory

This data structure is allocated in the user program in the
format:

string;

following

DEVICE-NAME STRING DESCRIPTOR
Word 1 -

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 1- or 2-digit
octal unit number. These strings may be created
by issuing statements such as those below:

Word 2 -

DEVNM:

.ASCII

/DKO:/

DEVNM:

.ASCII

/TTlO:/

Contains the address
string.

the

ASCII

device

name

the

ASCII

DIRECTORY STRING DESCRIPTOR
Word 3 -

Contains the length
file-directory string.

{in

bytes)

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.
A
directory string can be created
by
issuing
statements such as those that follow:
DIRNM:

.ASCII

/(200,200]/

DIRNM:

.ASC:II

/(40,100]/

If the user wishes to specify an explicit file
directory different from the UIC under which he is
currently
running,
the
dataset-descriptor
mechanism permits that flexibility.
Word 4 -

Contains the address of the
string.

ASCII

file-directory

bytes)

FILENAME STRING DESCRIPTOR
Word 5 -

Contains the length
filename string.

(in

the

ASCII

This string consists of a
filename up to 9
characters in length, an optional 3-character file
type designator,
and an optional
file version
number.
The filename and file
type must be

2-29

PREPARING FOR I/O
separated by a dot
(.),
and the file version
number
must be preceded by a semic-0lon.
A
filename string may be created as shown below:
FILNM:

.ASCII

/PR0Gl.OBJ;7/

Only the characters A through z and 0 through 9
may be used in composing an ASCII filename string.
Word 6 -

Contains the address of the ASCII filename string.

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

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

;CREATES FOB.
;INITIALIZES FILE-ATTRIBUTE SECTION.
;INITIALIZES RECORD-ACCESS SECTION.
;INITIALIZES FILE-OPEN SECTION.

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

OFDSPT:

Note first that an FDB labelled 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 FDB 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
f i1 ename 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 2 words of storage
for the device-name descriptor, the file-directory descriptor, and the
filename descriptor, respectively.
In the example above, however, note that the first
two descriptor
fields are filled
with zeros, indicating null specifications.
The
last .WORD directive allocates 2 words that contain the size and the
address of the
filename
string, respectively.
The filename string
itself is explicitly defined in the .ASCII directive that follows.
Note that the statements defining the filename 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
user program may be defined in this manner.

2-30

the

..~

PREPARING FOR I/O
2o4.2

Default Filename Block - NMBLK$ Macro Call

As noted earlier, the user may also define a default filename block in
the program as a means of providing required file information to FCS.
For this purpose, the NMBLK$ macro call may be issued 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 the user
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
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 FDB by the beginning character N. All versions
of the generalized OPEN$x macro call
(see Section 3.1)
use these
symbols to
identify offsets in storing file
information in the
f Uename block.
N~xxxx

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

'"-"'

label:

NMBLK$

fnam,ftyp,fver,dvnm,unit

where:

label

represents 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

represents the default filename.
This parameter
may consist of up to 9 ASCII characters.
The
character string is stored as 6 bytes in Radix-SO
format,
starting at offset location N.FNAM of the
default filename block.

f typ

represents the default file type.
This parameter
may consist of up to
3 ASCII characters.
The
character string is stored as 2 bytes in Radix-SO
format
in offset location N.FTYP of the default
filename block.

fver

represents
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

represents the default name of the device upon
which the volume containing the desired file is
mounted.
This parameter consists of 2 ASCII
characters that are stored
in offset location
N.DVNM Qf the default filename block.

unit

represents 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
composing the filename and file type strings discussed above.

2-31

PREPARING FOR I/O
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 via a command string, or when supplied
through a dataset-descript~r 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 FOB.
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:
1.

All the file information required by FCS to open the file is
not present in the dataset descriptor. Missing information
is 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
program.

A dataset descriptor is present in the user 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 FOB offset location F.DSPT.

descriptor

has

not

been

created

the

The following coding illustrates the general method of specifying
NMBLK$ macro call:
FDBOUT: FDBDF$
FDAT$A
FDRC$A
FDOP$A
FDBIN:

OFNAM:
IFNAM:

user

the

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,
;DEVICE NAME, AND UNIT NUMBER.

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 within the user
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
filename 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 FOB named FDBIN. Note in this macro
call that the third paramater (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.

2-32

PREPARING FOR I/O

The offsets for a filename block can be defined locally in
program, if desired, by issuing the following macro call:

the

user

NBOF$L
This macro call does not generate any code. Its function is merely to
define the ~ilename-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, the user 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:

DFNB:

NMBLK$

RSXLIB,OBJ

NUTYP:

.RADSO

/DAT/

MOV

NUTYP,DFNB+N.FTYP

where the symbol NUTYP in the MOV instruction represents the address
of the newly defined Radix-SO file type DAT, which is to be moved into
destination offset N.FTYP of the default filename block labeled DFNB.
Any of the offsets within the default filename block may be manually
initialized in this manner to establish desired values or to override
previously initialized values.

2.4.3

Dynamic Processing of File Specifications

Users who wish to make use of routines available from the system
object library ([l,l]SYSLIB.OLB) for processing command-line input
dynamically 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 the user 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 FDB, a
file can be opened in a manner referred to throughout this manual as
"op1ening 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 the user program.
If files are
frequently opened and closed during program execution, opening files
by file ID accomplishes substantial savings in overall execution time.

2-33

PREPARING .E'OR I/O
To open a file by file ID,
the minimum 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,
beqinning 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 the user.

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
offset iocation N.UNIT contains
the particular unit (among several
volume containing the desired file

field
at filename block
a binary value identifying
like units) on which the
is mounted.

These three fields are written into the filename block
two ways:

either

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

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

These two methods of setting up the filename block in anticipation of
opening a
file by file ID are described in detail in the following
sections.

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 generalized 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
the user 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 possible 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 FOB at the desired point in program flow for use in reopening
that same file.

2-34

4 II

&L$

••

PREPARING FOR I/O
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.
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, the user 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 S.FNBW 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 the user
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.
It is the user's responsibility to 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, the user
is advised to
save
the
entire
filename
block.
The
filename,
file-type,
file-version, and directory-ID fields, etc., 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 the user 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-35

PREPARING FOR I/O
2.s.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 the user chooses to do so,
the
.PARSE and
.FIND routines
(see Sections 4.7.l and 4.8.l, 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 existing files is then issued,
FCS unconditionally opens that
file by file ID.
Occasionally,
instances arise that make such manual
operations
desirable, especially if the user 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 the user wishes
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.

~rt

If conservation of memory is an objective, and
if the user 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
only 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-identif.ication 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-36

,._...

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

,...ml1~

I. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. , .. . . . . . . . . .~-

PREPARING FOR I/O
2.6

INITIALIZING THE FILE STORAGE REGION

The file storage region (FSR) is an area allocated in the user program
as
a
buffer
pool
to accommodate the program's block-buffer
requirements in performing record 1/0 (GET$ and PUT$) operations.
Although the FSR is not applicable to block I/O (READ$ and WRITE$)
operations, the FSRSZ$ macro must be issued once in every program that
uses FCS, regardless of the type of I/O to be performed.
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 the user, 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$
where:

fbufs,bufsiz,psect

fbuf s

represents a numeric value that is established
the user as follows:
1.

If no record I/O processing is to be done,
fbufs equals O. A value of O indicates that
an unspecified number of files may be open
simultaneously for block I/O processing. For
example, if the user intends to access three
files for block I/O operations and no files
for record I/O operations, the FSRSZ$ macro
call takes O 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-37

PREPARING FOR I/O
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.
Since RSX-llM
provides single buffering only for record I/O,
and since block I/O does not require pool
space
in the FSR, this user would specify the
following FSRSZ$ macro call:
FSRSZ$
Additional
(described
required.

parameters,
bufsiz
and
psect
below), could also be specified as

If record I/O with multiple buffering is to be
done,
fbufs
represents the maximum number of
buffers ever in use simultaneously among all
files
open
concurrently for
record
I/O.
Assume, for example, that an RSX-llD or !AS
user's program will simultaneously access four
disk files for record I/O operations.
Assume
further
that the user wants double-buffering
for
three of the disk
files
and
has,
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.
This user 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

represents a numeric value defining the
to~al
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 2 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.

2-38

....,..llml..................................................................................................

PREPARING FOR I/O
If the user
wishes
to
explicitly
specify
block-buffer-pool
requirements,
the following
formula must be applied:
bufsiz=(bsizel*mbcl) [+(bsize2*mbc2) ••• +(bsizen*mbcn)]
where:

bsizel,
bsize2,
etc.

are 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 the user explicitly specifies
block-buffer-pool requirements.

mbcl,
mbc2,
etc.

are the multiple buffer counts (refer to Section
2.2.1.6)
specified for the respective files.
For
the purposes of this formula, RSX-llM users must
use multiple buffer counts equal to 1.
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.
NOTE
An !AS or RSX-llD user must not allocate
an FSR block buffer less than 512(10)
bytes in length for spooled output to a
record-oriented device
(such as a line
printer).

psect

2.6.2

specifies the name of the program section
(PSECT)
to which control
returns after FSRSZ$ completes
processing.
If no name
is specified,
control
returns to the blank PSECT.

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

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

2-39

.PREPARING FtOR I/O

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 the user, 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.

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.

.~,
i

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 per 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.
·~!i

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

FSR-Extension Procedures for MACR0-11 Programs

To increase the size of the FSR for a MACR0-11 program, the
two options:
1.

user

has

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.

2-40

PREPARING FOR I/O
2.

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
where $$FSR1 is the symbolic name of the program section
within the FSR that is reserved for use as the block-buffer
pool, and "length" represents a numeric value defining the
total required size of the buffer pool in bytes.
The size of the FSR cannot be reduced at task-build time.

In calculating the total length of the FSR,
below may be used:
1.

length

where:

S.BFHD

either

the

formulas

(S.BFHD*fbufs)+bufsiz

= fbufs*(S.BFHD+512.)
is a symbol that defines the number of bytes
required
for
each
block-buffer header.
If
desired, this symbol may be defined locally in the
user program by issuing the following macro call:
BDOFF$

DEF$L

fbuf s

is 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.l.

bufsiz

represents 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.l.

512.

is the standard default buffer size.

The EXTSCT command is described in detail
Reference Manual of the host operating system.

the

Task

Builder

FSH-Extension Procedures for FORTRAN Programs

2.7.2

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
task-build.
To extend the size of the FSR at task-build time, the
user may issue the following command:
ACTFIL = files
whe·re:

files

represents a decimal value defining · the maximum
number of files that may be open simultaneously
for record I/O processing.

2-41

PREPARING FOR I/O
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 4. 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
and th& 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;
and

The successful
operation.

completion

the

READ$/WRITE$

requested

in
I/O

data-transfer

These processes, both of which yield success/failure indications that
may be tested by the user 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 the user, even in the case of multiple-buffered operations.
In
the case of block I/O operations, the flexibility of FCS allows the
user to synchronize all block I/O activities, thus enabling the user
to satisfy logical processing dependencies within the program.

2.8.l

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 task's responsibility to synchronize the
execution of I/O requests.
Tasks use event flags in synchronizing

2-42

~. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ., . . . . . . . . . . . ." " '. . . . . . . . . . . . . . . . . . . . . . . .llllm.........lllllllllllll'•i-

l. . . . . . . . .

PREPARING FOR I/O
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 the user has specified a particular
event flag to be used by the task in coordinating I/O-completion
processing, that event flag is set, causing the system to evaluate the
eligibility of other tasks to run. Any event flag
from l
through
32(10) may be defined for local use by the task.
If the user has not
specified an event flag, FCS uses event flag
32(10)
by default to
signal the completion of I/O transfers.
Specific FOB-initialization and I/O-initiating macro calls in FCS
enable the user 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
may
be
declared
through
the corresponding parameter of the
I/O-initiating READ$ or WRITE$ macro call (see Section 3.15 or 3.16,
respective 1 y) •
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 user is unaware of the event flag's
state and has no need to know.
Furthermore, the user 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 the user's control.
Th~ough

event-associated system directives, the user can clear event
flags, set event flags, test whether a specified event flag is set, or
cause a task to be suspended until a specified event flag
is set.
These event-associated directives are described
in detail in the
Executive Reference Manual of the host operating system. The setting
and checking of event flags allow tasks in a real-time system to
communicate with each other and thereby synchronize their execution.
Event flags and related device-dependencies are described in detail in
the IAS Device Handlers Reference Manual and the RSX-llM/M-PLUS I/O
Drivers Reference Manual.
Also, a code indicating the success or failure of the QUEUE
request resulting from the READ$/WRITE$ macro call is returned to
Directive Status Word ($DSW).
If desired, symbolic location $DSW
be
tested
to determine the status of the I/O request.
success/failure codes for the QUEUE I/O directive are listed in
manuals referenced above.

2-43

I/O
the
may
The
the

PREPARING F'OR I/O

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 the user 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 the user 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 the user.
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 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 magnetic tape units, almost all virtual blocks
are 512(10) bytes or less
in length.)
For WRITE$ operations,
the
specified number of bytes are always transferred;
otherwise an error
condition exists.
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.

·~
:1

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 IAS
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 FOB is
highly desirable in order to facilitate normal error reporting.
An I/O status block
assembly-time
through
the following:
IOSTAT:

.BLKW

may
any

be defined
in the user
program
at
storage directive logically equivalent to

2-44

L.11 SL

LUJ

ca. as au ;u: s:•~

PREPARING FOR I/O

where the label IOSTAT is 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 tequest.

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, the user 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).
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 continues.
·~·

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 (e.g., another I/0 transfer).
If an AST service routine is not provided by the 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 WA.IT$ 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.
The implementation of 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.
The
reader is therefore referred to the Executive Reference Manual of the
host operating system for discussions of various trap-associated
system directives.

2-45

.......................................................................................1.

--~--

CHAPTER 3
FILE-PROCESSING MACRO CALLS

The user manipulates 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;

file-identification

OFNB$

- To open a file
filename block;

information

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

DELET$

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

WAIT$

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

using

filename

from

file

requested

the

random

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 the user must explicitly test the c-bit in
the Processor Status Word to ascertain the status of the
requested
operation.
Note that the execution of 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 the user (or system)
program,
it
must
first
be opened.
The type of action that the user intends 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;

- Write (create) a new file;

- Modify an existing file without changing its length;

~
I

3-2

FILE-PROCESSING MACRO CALLS
U

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

'--"

or
A

- Append (add) data to the end of an existing file.
NOTE:
The generalized OPEN$x macro call can be
issued 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, i.e., 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,
i.e.,
concurrent GET$/PUT$ or READ$/WRITE$ operations may
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 may be read, written,
and/or extended.

The program that is issuing the OPEN$x macro call must
have
appropriate access p~ivileges for the specified action. Table 3-1
summarizes 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 Macro 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

First record of existing file.

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.)
3-3

FILE-PROCESSING MACRO CALLS
When any form of the OPEN$x macro call is issued, FCS first
fills
in
the
filename
block with filename
information retrieved
from the
dataset descriptor (see Section 2.4.1).
FCS gains access to this data
structure through
the address value stored in FOB offset location
ft'. OSPT.

~
1 ·

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
filename
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 FOB offset location F.OFNB.
The address values in offset locations F.OSPT and
F.OFNB may be
supplied
to FCS through the FOOP$A macro call, the FOOP$R macro call,
or the OPEN$x macro call.
FCS requires access to
the dataset
descriptor and/or
the default filename block in retrieving filename
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.
File-identification information is
maintained by FCS in offset location N.FIO of the
filename
block.
The
filename
block
in the
FOB 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 FOB 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
(UFO).
If,
however,
an entry for a file having the same
name, type, and version number already exists in the UFO, 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
filename
block,
FCS constructs the
filename
block
from
information taken from
the dataset descriptor
and/or
the
default
filename
block.
FCS then searches the user file
directory
(UFO)
by filename
to
obtain
the
required
file-identification
information.
When
found,
this
information is stored in the
filename
block,
beginning at
offset location N.FIO.

3-4

JLJSij[J

,. I

:::•

FILE-PROCESSING MACRO CALLS
2.

Associates the assigned logical unit number
file.

(LUN)

with

the

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

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,
the
user
allocates buffers through
the FSRSZ$
macro call.
The number of
buffers
allocated
is dependent upon the number
of files that the user intends to open
simultaneously
for
record
I/O
operations.
If block I/O operations are to be used,
FDB
offset location F.RACC must be
initialized with the
FD.RWM parameter
via
the
FDRC$A,
the FDRC$R,
or the
generalized OPEN$x macro call.
This
parameter
inhibits the allocation of a
buffer when the file is opened.

3.1.l

Format of Generalized OPEN$x Macro Call

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

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

represents 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).

fdb

represents a symbolic value of the address of
associated FDB.

lun

represents
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 FDOP$A or the FDOP$R macro call.
If so
specified,
the lun parameter need not be present
in the OPEN$x macro call.
Each FDB must have a
unique LUN.

dspt

represents the symbolic address of the dataset
descriptor.
Normally,
this address value
is
specified through the corresponding
parameter of
the FDOP$A or
the FDOP$R macro call.
If so
specified, this parameter need not be present
in
the OPEN$x macro call.

3-5

the

FILE-PROCESSING MACRO CALLS

This _parameter specifies the address of
the
manually created dataset descriptor (see Section
2.4.1).
If the Cqmmand 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).
represents 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. Any combination of the following
parameters may be specified by separating them
with exclamation points:

race

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.
FD.INS - 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.
The specification of 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 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 FOB 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

represents the symbolic address of the user record
buffer.
This parameter
initializes FOB offset
location F.URBD+2.
3-6

aIA

~.
rt

FILE-PROCESSING MACRO CALLS
If the user-record-buffer address has already been
supplied to
the FOB through the corresponding
parameter of the FDRC$A or the FORC$R macro call,
this parameter need not be present in the OPEN$x
macro call.
urbs

represents 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 the user 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

represents the symbolic address of
user-coded error-handling routine.

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

'-"'

optional
and

PUT$

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

macro

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

might

OPEN$M

for

example,

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

Note in this macro call that the FDB address is assumed to be present
in RO.
The third parameter, i.e., 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.OSPT)
has been
provided
previously to
the
FOB and that the record-access byte (F.RACC) has
also been previously initialized.
Finally, the last
two parameters
establish the address and
the size of the user
record buffer,
re!spect i vel y.
This last example shows a macro call that might
data to be appended to the end of a file:
OPEN$A

issued

allow

#OUTFDB

This 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 parameter
is not
specified,
requiring
that the user explicitly test the C-bit in the
Processor Status Word
to ascertain the success of the specified
operation.

3-7

FILE-PROCESSING MACRO CALLS
NOTE

RO can only be used to pass the FDB
address parameter.
Any other use of RO
will fail when issuing the OPEN$A macro
call.

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

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 opening
files.

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.
This information may be specified
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 this,
byte offset location
F.RTYP must be initialized with the
following
symbolic
values:
R.FIX - Indicates that fixed-length
written into the file.

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

R.SEQ - Indicates that
written into the file.

sequenced

records

are

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:
FD.FTN - Indicates that the first byte of each record
to contain a FORTRAN carriage-control character.

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
(e.g., 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.

3-8

~
ti

FILE-PROCESSING MACRO CALLS

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

cross

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

Items a.
through c.
above cannot be supplied to the FDB
through any of the various macros used to create and/or open
files (e.g., OPEN$W, OPEN$R, etc.).
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 FDB
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 FDB
offset location F.RACC:
FD.RWM - Indicates
that
READ$/WRITE$
(block
I/O)
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.
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.

'--"'

The user-record-buffer descriptors, i.e.,
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.

3-9

FILE-PROCESSING MACRO CALLS

The logical unit number must be specified to
initialize
FOB offset location F.LUN. The initialization of this
cell can be a~complished through the lun parameter of the
FDOP$A, the FDOP$R, or th. e ,generalized OPEN$x macro call.
Each FOB must have a unique logical unit number.

If file identification information is not already present
in
the
FOB,
either the dataset-descriptor pointer
(F.DSPT) or the default filename-block address
(FoDFNB)
must be specified to enable FCS to obtain required
filename information for use in opening the file.
These
address values may be specified
in either the FDOP$A
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 FOB 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(10) by default
in synchronizing all record I/O activity.

~t,

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 FOB
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
in effect for the associated device is to be overridden.
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.)
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.
(The mbct
parameter
is not applicable to RSX-llM/M-PLUS.)
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.

3-10

FILE-PROCESSING MACRO CALLS
In addition, if multiple buffering is to be employed, the
appropriate control flag must be specified as the mbfg
parameter in either the FDBF$A or the FDBF$R macro call
to appropriately initialize FOB offset location F.MBFG.
Either of two symbolic values may be specified for this
purpose, as follows:
FD.RAH - Indicates that read-ahead operations are
used in processing the file.

FD.WBH - Indicates that write-behind operations are to bs
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 FOB 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.

The address of the 5-word statistics block
in the user
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. The user who elects to define
such an area in a program may do so 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 FOB.

3-11

FILE-PROCESSING MACRO CALLS
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, i.e., 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·ar~ 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 a filename for
that file
into any associated user directory file.
This macro call
simply enters appropriate
file-identification
information into the
volume's
index
file
and,
in
addition,
maintains
the
file-identification field (offset location N.FID)
in the associated
filename block.
The
index file consists of file-header blocks for
user files (see Appendix E).
In using the OPNT$W macro call, the user bears 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 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 (e.g., for use as a work
file).
The general sequence of operations in such instances proceeds
as follows:
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.

3-12

~
.
'!

FILE-PROCESSING MACRO CALLS
6.

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 the
user.
This
program
is described in detail in the !AS 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
and
in addition to mark the file for deletion.
File identification
information for such a file is entered into the volume's
index
file
and
the
filename
block
in the associated FDB
(but not
in any
associated volume directory).
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.
The OPNT$D macro call takes the same
generalized OPEN$x macro call.

format

and

parameters

NOTE
If the OPNT$D macro call is
issued
for
use with a
temporary file containing
sensitive information, it is recommended
that the
user
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-13

the

FILE-PROCESSING MACRO CALLS
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 the
user's default
filename block).
Thus, issuing this macro call invokes an F'CS routine
that opens a file only bv file ID (see Section 2.5).
The OFID$x call,
which has the
same
format
and
takes the
same parameters as 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
ID.
The saving and
restoring of
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 filename 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
filename)
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.

The advantage in using the .PARSE and .. FIND routines
in conjunction
with the OFID$x macro call is that the user 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.

3.6

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 filename information in the filename
block.
Similar to the OFID$x macro call above,
the OFNB$x call
is

3-14

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

11111111111. . .. .

FILE-PROCESSING MACRO CALLS
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
the generalized OPEN$x macro call as described in Section 3.1.l;
i.e .. ,
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;
i.e.,
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, viz., 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.
To open a file by filename block, the following
information
present in the filename block of the associated FDB:
1.

The filename

The file type or extension (offset location N. FTYP);

The file version number

The directory ID (offset location N.DID);

The device name (offset location N.DVNM);

'I'he unit number

must

(offset location N.FNAM);

(of :Eset location N.FVER);

and

(offset location N. UNIT) •

In providing the information above to the filename block,
either of
two general
procedures may be used, 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:
1.

Call the .PARSE routine (see Section 4.7.1).
This routine
takes
information from a specified dataset descriptor and/or
default filename block and fills in the appropriate offsets
of a specified filename block.

Issue the OFNB$x macro call.

3-15

FILE-PROCESSING MACRO CALLS
3.6.2

Default Filename Block Only

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 ?.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 filename
block;
or

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 filename block.

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

Issue the OFNB$x macro call.

the

Note that the coding for OFNB$x operations normally resides
in an
overlay apart from that containing the other FCS routines identified
above.
The issuance of 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 the user expects 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 the user wishes to create a file, the filename
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 filename, 'tile type, and file version
number, and a file of that description already exists in the specified
user file directory (UFD), the old file is superseded.
By issuing the OPEN$ macro call without an alphabetic suffix,
and
by
specifying two additional
parameters,
the
user 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 offs~t 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.

3-16

~
I

FILE-PROCESSING MACRO CALLS
To open a
file without superseding
an existing
file having an
identical
file specification,
a macro call of the following form is
used:
OPEN$
where:

f acc

fdb,facc,lun,dspt,dfnb,racc,urba,urbs,err
represents 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
opened for reading only.

FO.WRT - Indicates that a
new
created and opened for writing.

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

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

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

file

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, that the file is to be a temporary file.
FA.SHR - Indicates that the file is to
for shared access.
dfnb

opened

represents 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 FDB 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,#FO.WRT!FA.NSP

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

#OUTFDB,#FO.WRT!FA.TMP!FA.SHR
NOTE
RO can only be used
to pass the FDB
address parameter.
Any other use of RO
when issuing the OPEN$ macro call will
fail.

3-17

FILE-PROCESSING MACRO CALLS
3.8

CLOSE$ - CLOSE SPECIFIED FILE

When the processing of a file is completed,
it must be closed by
issuing the CLOSE$ macro call.
T~~ CLOSE$ operation performs the
following housekeeping functions:
1.

Waits for all I/O operation~ 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 offset locations.

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

3.8.1

buffer{s)

allocated

for

clearing

the

file

appropriate
an

Format of CLOSE$ Macro Call

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

f'db,err

fdb

represents a symbolic value of the address of
associated FDB.

err

represents the symbolic address of
user-coded error-handling routine.

the

optional

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, i.e., 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.

3-18

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

FILE-PROCESSING MACRO CALLS
In move mode, a GET$ operation moves a
record to the user
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 FOB (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 the user
record buffer, and the address of the user record buffer and the size
of the record are returned to offset locations F.NRBD+2 and F.NRBD,
respectively ..
After returning from a GET$ operation in locate mode, whether or not
moving
the record was necessary, F.NRBD+2 always contains the address
of the record just read, and F.NRBD 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, i.e., record I/O operations are
completed before control is returned to the user program.
Specific FDB requirements for GET$ operations are presented in Section
3.9 .. 2 below.

3.9.1

Format of GET$ Macro Call

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

the

fdb

represents a symbolic value of the address of
associated FDB.

the

urba

represents the symbolic address of a
user
record
buffer
to be used for record I/O operations in
move or locate mode.
When
specified,
this
parameter
initializes
FDB
offset
location
F.URBD+2.

urbs

represents a numeric value defining the size
(in
bytes)
of the user record buffer.
This parameter
determines the largest record that can be placed
in the user record buffer in move or locate mode.
When specified, this parameter initializes offset
lncation F.URBD in the associated FDB.

err

represents the symbolic address of
user-coded error-handling routine.

GET$
where:

call

specified

fdb,urba,urbs,err

optional

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 FDRC$A, the FDRC$R, or the generalized OPEN$x
macro call.
Any nonzero values in offset locations F.URBD+2 and
F.URBD resulting therefrom are used as the address and the length,
respectively, of the user record buffer.

3-19

FILE-PROCESSING MACRO CALLS
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 FDB, indicating an illegal record size:
1.

In move mode, the record size exceeds the limit specified
offset location F.URBD;
or

In locate mode, the record size exceeds the limit specified
in offset location F.URBDv
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 the user's buffer.
The next GET$ begins reading
at the beginning of the next record.
The following statements are representative 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, i.e., the user
record-buffer address (urba) and the user-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 HO contains the address of the
desired
FDB.
Explicit parameters then define the address and the
size, respectively, of the user 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
RO can only be used
to pass the FDB
address.
Any other use of RO when
issuing 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 or not a
user
record
buffer
is required
under certain conditions.
In this regard, the
reader should recall that the user-record-buffer descriptors,
i.e.,
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/O
initiating GET$ macro call.
These parameters need be present in the
GET$ macro cail (to appropriately initialize
the FDB)
only
if not
previously supplied through some other available means.

3-20

.-.,
i

FILE-PROCESSING MACRO CALLS
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.
·rhus, unless the user 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.
The specified user-record-buffer
size
(i.e.,
the urbs parameter) always determines the largest record
that can be read duting a GET$ operation.

3.9.2.1 GET$ Operations in Move Mode - With
respect
to
GET$
operations
in 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
Operations in locate mode,
following::

Mode - In
performing
GET$
Locate
the user should take into account the

NOTE
"--"'

In the following
discussion,
reference
is made
to
the FSR block buffer.
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 P.Ven 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.

'•••f
1.

If fixed-length records are to be processed, and if they fit
evenly within
the FSR block buffer, the user 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,
the
user-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).
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.

3-21

FILE-PROCESSING MACRO CALLS
For an existing file, the user-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 or not records within, t~hat file are allowed to cross
block boundaries.
The design of FCS requires the utili~ation of a user
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 FOB.
However, if
that record crosses buffer boundaries, it is moved to the
user record buffer.
In this case, the address of the user
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 user-record-buffer
descriptors must be supplied through any
available
means
to
appropriately initialize offset locations F.URBD+2 and F.URBD in the
associated FOB.

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 the user be intimately familiar with the structure of the file to
be read and, furthermore, that the user 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
FOB
(at offset locations F.RCNM and F.RCNM+2), then GET$ may be used.
If, however, 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 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
where:

lrcnm

addition

those

fdb,urba,urbs,lrcnm,hrcnm,err
represents 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 n··mber up to 65,536(10)
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.

3-22

FILE-PROCESSING MACRO CALLS
hrcnm

represents a
numeric
value
specifying
the
high-order 15 bits of the number of the record to
be read.
This value
is stored
in FOB 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 41 bits
of magnitude may be used in defining the record
number.
parameter
is not
specified,
offset
I f this
location F.RCNM retains its initialized value of
zero (0).
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 numberX
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 O by the OPEN.
If other than the next
sequential record is to be read, the user must explicitly specify the
number of the desired record.
The following statements are representative of the use
maciro call:
GET$R

#INFOB,#RECBUF,#160.,#1040.,,ERROR

GET$R

#FOBAOR,#RECBUF,#160.,R3

the

GET$R

Note in the first example that the number of the desired record to be
read,
i.e., 1040(10), 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 FOB
address parameter.
Any other use of RO
when issuing the GET$R macro call will
fa:il.

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

3-23

FILE-PROCESSING MACRO CALLS
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 the associated FDB.
FCS increments this value after each PUT$ or
PUT$R operation to point to the next sequential
record position.
Thus, unless the user 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 the user's choice.
This buffer is not
necessarily the user record buffer previously described in the context
of record I/O operations.
In other words, the user may build records
in an area of a program apart from that normally defined by the
user
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 in
the FDB contains the sequence value, which can be modified by the
user.
PUT$ operations are fully synchronous, i.e., record I/O operation~ 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.12.1

Format of PUT$ Macro Call

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

fdb

fdb,nrba,nrbs,err
represents a symbolic value of the address of
associated FDB.

3-24

the

~.I

FILE-PROCESSING MACRO CALLS
nrba

represents the symbolic address of the next record
buffer,
i.e.,
the address of the record to be
PUT$.
This parameter
initializes FDB
offset
location F.NRBD+2.

nrbs

represents a numeric value specifying the size of
the next record buffer, i.e., the length of the
record to be PUT$.
This parameter initializes FDB
offset location F.NRBD.

err

represents the symbolic address of
user-coded error-handling routine.

optional

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

#FDBADR,,,ERRRT

PU'I'$

,,#160.,ERRRT

PU'I'$

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
parameter
fields,
assuming that RO currently contains the address of
the associated FOB and that variable-length records are to be written
to the file.
The last example specifies only the address of
parameter fields are null.

the

FDB;

all

other

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

FOB 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 a user record buffer is or is not used are
summarized.
As
is the case for GET$ operations, if a user record
buffer is required for PUT$ operations, the buffer descriptors
(i.e.,
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
a user record buffer.
Note, however, that PUT$ operations in move
mode never require a user record buffer.
If the user record buffer is required,
the specified size of that
buffer
(i.e.,
the
urbs parameter) always determines the size of the
largest record that can be written to the specified file.

3-25

FILE-PROCESSING MACRO CALLS

Whether in move or locate mode, a PUT$ operation uses the
information
in offset locations F.NRBD+2 and F.NRBD, i.e., the next record-buffer
desc~iptors, 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
remaining
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 th~ 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
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:
1.

The user-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 the 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 urbs
parameter in any PUT$ macro call involving this file.

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

""·
'I

3.12.2.2 PUT$ Operations in Locate Mode - Basically,
a
user
record
buffer
is required
for PUT$ operations in locate mode only when the
potential exists for records to cross buffer boundaries.
In other
words,
if there is insufficient space
in the FSR block buffer to
accommodate the building of the next record, the user must provide a
buffer in user 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$

3-26
---,i....,.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~. . . . . . . .i..-. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...,.l!P

FILE-PROCESSING MACRO CALLS
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 ~o 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 the user 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.
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 l 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,
a user record buffer is not
required
6

If a fixed-length record crosses block boundaries,
the user
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 the
user record buffer.
Then,
when the record is PUT$, it is
moved from the user 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, the user
record-buffer descriptors must be present in offset locations
F.URBD+2 and F.URBD of the associated FDB.
Moreover, the
size of each variable-length record must be specified as the
nrbs parameter in each PUT$ macro call.
The determination as to whether FCS points offset location
F.NRBD+2 to the FSR block buffer for the PUT$ operation or to
the user
record
buffer
is based on whether
there
is
potentially
enough
room
in the FSR block buff er
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 the user 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 the user record buffer.

3-27

FILE-PROCESSING MACRO CALLS
Each PUT$ operation in locate mode sets up the FDB 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.

~:
1-·
!

If variable-length records are being processed that are shorter than
the largest defined
record size, FCS may move records unnecessarily
from the user record buffer to the FSR block buffer.
For example,
assume
that the user has 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 the
user's record buffer for PUT$ operations, even if the user continues
to PUT$ short
(10- or
20-byte)
records.
Thus, some unavoidable
movement of records takes place in locate mode.
If the largest record that the user intends 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 the user record buffer to the FSR block buffer 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 the user
to be
intimately familiar with the contents of such files.
The PUT$R macro
call likewise relies entirely on the user for the specification of 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 the user also knows 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 FDB (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 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
PUT$ nor PUT$R will write the desired record.
The PUT$R macro call takes two more parameters in
specified in the PUT$ macro call, as shown below:
PUT$R
where:

lrcnm

addition

those

fdb,nrba,nrbs,lrcnm,hrcnm,err
represents 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.

~·i

3-28

U .4fPlllll'

FILE-PROCESSING MACRO CALLS
hrcnm

represents 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,
offset
location F.RCNM retains its initialized value of
zero (O).

If F.RCNM is used in expressing a desired
record
number
for
any given PUT$R operation, the user
must clear this cell before issuing a
subsequent
PUT$R macro call that requires 16 bits or less in
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
is written,
since 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, the user 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 the
user
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,#RECBUF,,R4

PUT$R

#FDBADR,#RECBUF,,LRN

In the first example, the presence of RECBUF as the next record buffer
address
(nrba) parameter merely indicates that the user is specifying
the address of the record.
Although specifying
this
address
repeatedly is unnecessary,
it is not invalid.
Normally, a buffer
address is 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.

3-29

FILE-PROCESSING MACRO CALLS
Note in the second and third examples that R4 and a memory location
Such a
(LRN)
are used
to specify the logical
record
number.
record
specification assumes that the user has preset the desired
number in the referenced location.

.,-,

NOTE
RO can only be used to pass the
FDB
address.
Any other
use of RO when
issuing 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.

~,l

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
(e.g.,
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 Sect ion
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, the user
is responsible
for
synchronizing all
block
I/O operations.
For this reason, the
WAIT$ macro call is provided (see Section 3.17), allowing the user
to
suspend program execution until a specified READ$/WRITE$ operation has
been completed.
It is important, however,
that
the
user
test
the
contents of F.ERR in the FDB 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 completion of a WAIT$
operation.
For example,
IE.EOF will be returned upon completion of
the READ$ operation, but not upon completing of WAIT$.
When the WAIT$ macro call is issued in conjunction with a
READ$
(or
WRITE$)
macro call,
the user 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-30

.................................................................................................I_

FILE-PROCESSING MACRO CALLS

NOTE
The READ$ macro call cannot be used when
accessing ANSI magtapes.

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 FOB
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$
where:

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

fdb

represents a symbolic value of the address of
associated FDB.

the

bkda

represents the symbolic address of the block I/O
buffer
in the user 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

represents 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

represents the symbolic address of a 2-word block
in the user 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
FOB
is
ineffective, since the generalized OPEN$x
macro call sets the virtual-block number
in the
FOB to
1.
The virtual-block number can be made
available to FCS only through the FDBK$R macro
call or the I/O-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.

3-31

FILE-PROCESSING MACRO CALLS
The READ$ function checks the specified virtual
block number to ensure that it does not reference
a nonexistent block, i.e., 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 the user 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

represents a numeric 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 FOB 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(10) is
used by default.
The function of an event flag is
discussed in further detail in Section 2.8.1.
bk st

represents the symbolic address of the I/0 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 ~upplied
to FCS through any of the available
means, status information is not returned
to
the
I/O
status
block.
However,
the event flag
specified through the bkef parameter above is set
to
indicate block I/O completion, but the user
program must assume
that the
operation
was
successful.
An
error
indication cannot be
returned to the user program without an I/O status
block address.

-~-

3-32

$ '

41••

FILE-PROCESSING MACRO CALLS
bkdn

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

represents the symbolic address of
user-coded error-handling routine.

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,#INBUF,#BUFSIZ,#VBNADR

optional
issued

The first example assumes that RO 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 associated 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 the user
program containing the 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 the user program containing
the virtual block number.
NOTE
RO can only be used to pass the FDB
address.
Any other use of RO when
issuing the READ$ macro call will fail.

3.15.2

FOB Requirements for READ$ Macro Call

The READ$ macro call requires that the associated FDB be
initialized
with certain values before
it can be issued.
These values may be
specified through either the FDBK$A or the FDBK$R macro call, or they

3-33

FILE-PROCESSING MACRO CALLS

may be made available to the FOB through the various parameters of the
READ$ macro call. In any case, the following values must be present
in the FOB 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

and

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
la~t block
field F.FFBY in the FOB.
During a READ$ operation, end-of-file is
determined by the end-of-file
block
number field in F.EFBK.
If desired,
F.FFBY may be modified before closing
the file 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 (e.g., 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, the user is responsible for synchronizing all
block I/O processing.
The WAIT$ macro call can be issued in
conjunction with the WRITE$ macro cc1ll 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, the user should check for an error
code immediately following the WRITE$ macro call as well as on return
from the WAIT$ macro call.
NOTE
The WRITE$ macro call cannot
when accessing ANSI magtapes.

3.16.1

used

Format of WRITE$ Macro Call

The WRITE$ macro call takes the same parameters as the READ$ macro
call, as shown below.
However, the bkvb parameter in this case
represents the number of the virtual block to be written.
The
virtual-block number is incremented automatically after each WRITE$
operation is performed.

3-34
~

I. . .. , .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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
(i.e.,
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$

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

WRITE$

R0,,,,#22.,#IOSADR,#ASTADR,ERRLOC

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
RO can only be used to pass the FDB
address.
Any other use of RO when
issuing 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.
As noted in Section 3.15 in connection with the READ$ macro call, the
user may specify an event flag number through the bkef parameter.
This event flag number is used during READ$ (or WRITE$) operations to

3-35

FILE-PROCESSING MACRO CALLS
indicate the completion of the requested transfer.
If desired, the
user may issue a WAIT$ macro call
(specifying the same event flag
number and I/O status block address) following the READ$ (or WRITE$)
macro call.

~
I

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 FOB,
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
status 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.
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$
where:

fdb,bkef ,bkst,err

fdb

represents a symbolic value of the address 6f
associated FOB.

bkef

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

the

If this parameter is not specified, either in the
WAIT$ macro call or the associated READ$/WRITE
macro call, FOB 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.
bk st

·~.

represents the symbolic address of the I/O status
block
in the user 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-36

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

represents the symbolic address of
user-coded error-handling routine.

optional

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
fla~
number (bkef
parameter) is not specified, offset location F.BKEF is assumed
to
contain the desired event flag
number.
If this cell in the FDB
contains o, event flag number 32(10) is used by default.
The second example shows an explicit specification of the FDB address
and also specifies 25(10) as the event flag number.
Again, in this
example, the FDB 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 event flag
The fourth example contains a null specification for
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 call.

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 the user
intends 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-37

FILE-PROCESSING MACRO CALLS
NOTE

~\
1-

RO can only be used
to pass the
FOB
address.
Any other
use of RO when
issuing the WAIT$ macro call will fail.

3.18

DELET$ - DELETE SPECIFIED FILE

The OELET$ macro call causes the directory information for
the
file
associated with the specified FOB to be deleted from the appropriate
user file directory (UFO).
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
filename string specified in the associated dataset descriptor or
default filename block contains an explicit file version number.
Thus, if the file is not open,
and
the file version number
is 0
(indicating
the latest version), or if the file version number is -1
(indicating the oldest version), then the OELET$ operation fails.
NOTE:
If the OELET$ macro call is
issued
for
use with a
file
containing sensitive
information, it is recommended that
the
user zero the file before closing it, or
reformat
the disk
to
destroy
the
sensitive information.
(Although OELET$
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 OELET$
macro
following format:

call

takes

the

fdb

represents a symbolic value of
address of the associated FOB.

the

err

represents the symbolic address of
an
optional
user-coded
error-handling routine.

OELET$ fdb,err
where:

The following statements illustrate OELET$ macro calls:
OELET$

OELET$

#OUTFOB,ERRLOC

OELET$

RO,ERRLOC

3-38

CHAPTER 4

FILE CONTROL ROUTINES

File control routines can be invoked in MACR0-11 programs
the following functions:

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 f il e-owrier word in $$FSR2.
• Convert a directory string from ASCII to binary, or vice versa.
•

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

from

dataset

• Find, insert, or delete a directory entry.
• Set a pointer to a byte within a virtual block or to
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.

4.1

CALLING FILE CONTROL ROUTINES

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

.RDFDR

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 respective descriptions of the
routines.
Upon return,
all
registers are preserved, except those
explicitly specified as changed.
As a general rule, 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
because of the specific nature of their functions.
The following file
control
routines are listed according to whether or not they return
error indications.
Normal Error Return
(C-bit and F.ERR)

No Error Return

.ASCPP
.PARSE
.PRSDV
.PRSDI
.PRSDV
.ASLUN
.FIND
.ENTER
.REMOV
.GTDIR
.GTDID
.POINT
.POSRC
.POSIT

.RDFDR
.WDFDR
.RDFUI
.WDFUI
.RDFFP
.WDFFP
.RFOWN
.WFOWN
.PPASC
.MARK

.XQIO

.RENAM
.EXTND
.TRNCL
.MRKDL
• DLFNB
.CTRL
Appendix I lists the error indicators that are placed
location F.ERR by the routines identified above.

4.2

FDB

offset

and

write

DEFAULT DIRECTORY-STRING ROUTINES

The
.RDFDR and
.WDFDR routines
directory-string descriptors.

4.2.1

are

used

read

.RDFDR - Read $$FSR2 Default Directory String Descriptor

The user calls 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

...,...""1....................................................................,.1.,.....................................,.JP•llP

FILE CONTROL ROUTINES
If the user has 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 a user program is to
operate on files in the directory [220,220], regardless of the UIC the
program
runs
under,
then
the
user
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,
the default
directory-string descriptor cells in $$FSR2 are initialized 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]/

a new directory string
is defined.
Then,
by calling the
.WDFDR
routine,
the user 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

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 which describes

4-3

FILE CONTROL ROUTINES
an ASCII string, the default UIC is maintained as a binary value with
the following format:
Bit

GROUP

MEMBER

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 the user explicitly changes 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.l

.RDFUI - Read Default UIC

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

4.3.2

Contains the binary encoded default
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
routine
overrides
any
The
.WDFUI
previous
.WDFDR
routine - created
default UIC
descriptor
present
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
(e.g.,
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.
The default file-protection word has the following format:
Bit

15
WORLD

GROUP

4
OWNER

4-4

SYSTEM

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

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

DELETE

EXTEND

each

bit

has

the

0
WRITE

READ

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

.RDFFP - Read $$FSR2 Default File Protection Word

The user calls 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.·~.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 specific~tion, as follows:

corresponds

the

If the volume on which the new file
is created
is private
(allocated),
the owner's 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 owner's UIC is the same as the task's login UIC.

Note that for files created by privileged or nonprivileged tasks that
are started by a time-scheduled request, the owner's UIC is set to the
UIC specified at task build time.

4·-5

FILE CONTROL ROUTINES
A specific UIC value can be stored in the file owner word via the
.WFOWN routine
{see section 4.5.2).
All new files then created and
closed by the user task will contain the specified UIC value.
The format of the file-owner word is shown below:
Bit

GROUP

0
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.
If this
condition
prevails,
a privilege
violation results.

When a file is created, the owner's
UIC is always set to either the task
UIC creating the file or the task's
login UIC, as previously described.
However, when closing the file,
the
owner's UIC can be changed using the
.WFOWN routine.
If the file is not
closed properly,
the owner's 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 $$FSR2. No registers need be preset before calling this routine.
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
$$FSR2.

used

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

'l~he

.ASCPP and .PPASC routines are· called
string from ASCII to binary, 6r vice versa.

convert

oASCPP - Convert ASCII Directory String

4:.6.1

directory

.GTDIR - Insert Directory Information in Filename Block

4.9.1

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 the user program.
This string descriptor
defines the size and the address of the desired directory
string.

This routine performs a .FIND operation for the specified user
file
directory
(UFD)
in the master file directory (MFD) and returns the
resulting directory ID to the 3 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.

.GTDID - Insert Default Directory Information in Filename Block

4.9.2

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
user
file directory
( UFD) •
Before calling this routine, the following registers must be preset:
RO

Must contain the address of the desired FDB.

When called, the
.GTDID routine takes the default UIC from
its
one-word
location
in $$FSR2 and performs a .FIND operation for the
associated user file directory (UFD)
in the master
file directory
(MFD)~
The
resulting directory ID is returned to the 3 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,

4-16

,. . . . . . . . . . . . . . . . . . . . . .lll!ml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .~. . . . . . . . . . . . . . . . . . . . . . . . . .

FILE CONTROL ROUTINES
N.FVER, N.DVNM, and N.UNIT in the filename block, but zeros
of the filename block.

the

rest

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 via the OFNB$ macro call (see Section 3.6).
Such a program does not invoke the .PARSE logic because all required
filename 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.
The user also has 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.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 FQNRBD+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
The use of 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 conjunction 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

4-17

FILE CONTROL ROUTINES
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)
current positional context of the file.

to save the

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, RO and R3 must be
O, and R2 must be 1.

4.10.2

Resume processing of the file.

.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,
the user 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 mod~.
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:

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

the

associated

FILE CONTROL ROUTINES
4.10.3

.MARK - Save Positional Context of File

The .MARK routine allows the user to
record
the current positional
context of a file for later use.
For example, the user may mark the
current position of the file, close that file, and
later
reopen the
file and
return to the same position within the file.
The .MARK
routine is aiso useful in altering
records within a
file.
After
determining the record to be altered, the user may .MARK 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,
the desired record may be altered.
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

the

this

following

registers~

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

the

within

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

Must contain the address of the desired FDB.

4-19

FILE CONTROL ROUTINES

4.12

Must contain the desired Queue I/O function code.
Refer
to
the
IAS
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 to be included
in the Queue I/O directive, if any.

Must contain the beginning address of the list of optional
Queue I/O directive parameters,
if R2 contains a nonzero
value.

RENAME FILE ROUTINE (.RENAM)

The .RENAM routine is called to changE~ the name of a
file
in its
associated directory.
To
rename a file, the user must specify the
address of an FDB containing filename 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.

the

FDB

associated

with

the

Must contain the address of the FDB containing the desired
filename
information,
LUN assignment, and event flag to be
associated with renaming the file.

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
as an
indication that
.PARSE must be called to parse a
file
specification.
If neither a dataset descriptor nor a default filename
block
is present,
.PARSE returns a null
filename.
The
rename
operation then results in a new filename of ".;l".
NOTE
The
renaming process
is
merely
a
directory operation that replaces an old
entry with a new entry.
The
filename
stored
in the file-header block is not
altered.

4.13

FILE EXTENSION ROUTINE (.EXTND)

The
.EXTND routine
noncontiguous files.
closed.

called to extend either
contiguous
or
The file to be extended can be either open or

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

Must contain the address of the associated FDB.

4-20

...,....,.............""'........,................................................................ ..

FILE CONTROL ROUTINES
Rl

Must contain a numeric value specifying the number of
to be added to the file.

blocks

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 below).
NOTES

4.14

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
(Bit
EX.ACl=l) cannot be done.

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.

FILE TRUNCATION ROUTINE (.TRNCL)

The .TRNCL 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
fails.
If errors occur in both operations, the error code from the
close operation will be returned.

4.15

FILE DELETION ROUTINES

The .MRKDL and .DLFNB routines are provided for deleting files.

4-21

FILE CONTROL ROUTINES
NOTE:
If the .MRKDL or .DLFNB routine is used
to delete a
file containing sensitive
information, it is recommended that the
user 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, i • e • I
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
BIT SETTINGS Low-Order Byte of R2
7

BIT DEFINITIONS AND MEANING!

EX.ENA - Bit 7

= 0

indicates
EX.ACl - BIT 0 = O;
extend is to be noncontiguous.

·x

indicates that
BIT 0 = 1;
EX.ACl
extend
is to be contiguous and that
file is to be contiguous.

that

EX.ENA

- Bit 7 = 1

EX.ACl - Bit 0 = O;
nonconti9uous area
the file.

EX.ACl - Bit 0 = l;
indicates that
contiguous area is to be added to the
file.

indicates that
is to be added to

1 Bit settings must be defined by the user program.

(continued on next page)

4-22

.Ji&¥

$L9i

FILE CONTROL ROUTINES
Table 4-1 (Cont.)
R2 Control Bits for .EXTND Routine
~

BIT SETTINGS
Low-Order Byte of R2

BIT DEFINITIONS AND MEANINGl

EX.AC2 - Bit 1 = l;
indicates that
the largest available contiguous area
is to be added to the file if desired
extend space
This
is not available.
is
bit is set only if bit 0 in EX.ACl
set to 1.

indicates
EX.FCO - Bit 2 = O;
the file is to be noncontiguous.

that

:x:

indicates
EX.FCO - Bit 2 = 1 i
the file is to be cont ig uo us.

that

EX.ADF - Bit 3 = O;
indicates that
the
the
user
intends to allocate
and
number of blocks specified by Rl
the high-order bits of R2 (see Note
above) •

EX.ADF - Bit 3 = l;
indicates that
file
extension is to occur according
to the volume default extend value, as
established
INITIALIZE,
by
the
INITVOLUME, or MOUNT command.

'-''

1 Bit settings must be defined by the user program.
Before calling the .MRKDL routine,
preset:
RO

the

following

must

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, 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 necessary, 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 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

4-23

FILE CONTROL ROUTINES

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

DEVICE CONTROL ROUTINE (.CTRL)

The
.CTRL
functions.
functions:

to perform device-specific control
routine
is called
.CTRL device-specific
The
following
are examples of

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

Rewind a file.

volume

and

continue

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
volume set;
FF.NV

to close the
operations on
volume set.

end

current volume and
the ne~t volume of

magnetic

tape

continue
file
a magnetic tape

R2 and R3 must each contain O.
When using .CTRL to space forward or backward, registers RO,
and R3 must contain the following values:
RO

Must contain the address of the associated FDB.

Must contain the value FF.SPC.

Must contain the number of records to space
backward.
A positive number means space forward;
number means space backward.

Must contain

Rl,

forward
or
a negative

When using .CTRL to rewind a file, register Rl must contain the
FF.RWF and registers R2 and R3 must contain O.
See Chapter 5 for an explanation of the use
magnetic tape device-specific functions.

.... ..,..
~

R2,

.CTRL

value

accomplish

4-24

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

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:

Indf~X

Storage-allocation file

Bad·-block file

Master file directory (MFD)

Checkpoint. file

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

User 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 the user.
Virtual blocks can be read and written directly
by
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).
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

FILE STRUCTURES
5.1.2

Directory Files

A directory file contains directory entries.
Each entry consists of a
filename 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, a master file directory (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 UFD
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.1.3

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
host
operating
system.
During
initialization,
the
required by the system is placed
in the
index file.
contains a detailed description of the format and content
file.

MFD

FILE A

FILE B

Figure 5-1

J
J

use by the
information
Appendix E
of an index

~·

l
FILE C

Directory Structure for Single-User Volumes

5-2

FILE STRUCTURES

''-"'
MFD

[_1~0~1°00

FIL~-] [

Figure 5-2

5.1.4

1
UFD
200,200

J
FILE A

I
I

FILE B

FILE C

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 256 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 2 words.
The
first word of the file ID, i.e., 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, i.e., 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
the
subsequent creation of a
new file,
and when the new file is
created, a different file sequence number is stored in the file-header
block.
If a
user attmpts to access a file that has been deleted
(e.g., 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 (i.e., 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

IAS and RSX-11 support the standard ANSI magnetic
tape structure as
described
in the June 19, 1974 proposed revision to "Magnetic Tape
Labels and File Structure for
Information
Interchange,"
ANSI
X3.27-1969.
Any of the
following
file/volume combinations can be
used:
1.

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
or
the
length of 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.

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 nonDIGITAL systems are
restricted
to
read-only
access unless explicitly overridden at MOUNT time.

5-4

FILE STRUCTURES
5.2.2

Rewinding Volume Sets

A magnetic tape volume set can be rewound 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 offline;

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 file 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.PCS must be set in FDB
location F.ACTL.
The default value for this FDB position is 0 (not
FA.PCS).
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.PCS.
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,
cause the position to end process to be 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, scratch
tape operations can be performed as follows:
1.

Open the first file with rewind specified.

Write the data records and close the file with rewind.

5-5

FILE STRUCT'URES
3.

Open the first file again for input {rewind is optional).

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
Nonsequent.ial
processing and tape-positioning time is required.
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

FCS

Continue processing a file on the next volume of a volume set
before the end of the current volume is reached.

Position to the logical end-of-volume set.

Rewind a volume at other than file open or close.

Space forward or backward n records.

Rewind a file.

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.
5-6

FILE STRUCTURES
1.

If the current volume is the last volume in the set,
i •e • I
there is no next volume, end-of-file is reported to the user.

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

If all required fields check, the operation continues.

If any check fails, the operator is requested
correct volume.

(HDRl) of the next file section is read

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 moun~ed.

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 followinq 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 the user 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 address.
OPRWDO:
OPEN WITH REWIND
FDOP$R
BR

RO,,,,#FA.ENB!FA.RWD
OPNOUT

OPNXTO:
; OPEN FOR NEXT FILE POSITION

5-7

;SET REWIND AND ENABLE USE
;OF F.ACTL

FILE STRUCTURES

FDOP$R
BR

RO,,,,#FA.ENBiFA.POS
OPNOUT

;SET POSITION TO NEXT
;AND ENABLE USE OF F.ACTL

OPROYK:
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
FDOP$R R0,,,,#0
;DISABLE USE OF AND RESET
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

5-8

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

----~

FILE STRUCTURES
CLS:RWD:
CLOSE REWINDING THE VOLUME
FDOP$R
BR

RO,,,,#FA.ENB!FA.RWD
CLOSE

;SET REWIND AND ENABLE USE OF
;F.ACTL

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, the user can process tape volumes in
the following ways.
~

;
;
;

SCRATCH TAPE OPERATIONS--SINGLE FILE VOLUME--

SCROUT: MOV
CALL

#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

Rr~TURN

SCR.IN:

"-"''

MOV
CALL
RETURN
CL SCRO: MOV
BH
CLSCRI: MOV
CLSVOL: CALL
RETURN
;

; MULTI-FILE VOLUME OPERATIONS
OPNXTI:
OPEN FILE FOR READING WHEN FILE IS NEXT OR FURTHER UP THE VOLUME
MOV
CALL
RETURN

;SELECT FDB
;OPEN FILE

#FDBIN,RO
OPCURI

OPE:NIN:
OPEN FILE FOR READING WHEN POSITIONED PAST IT
MOV
CALL
RETURN

#FDBIN,RO
OPRWDI

;SELECT FDB

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

5-9

FILE STRUCTURES
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:
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 FI LE 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

......'--..,. .llml. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. , .. . . . . . . . . . . . . .. .

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 the user
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 medium.
Using GCML relieves the user of the burden
of manually coding command-line-input operations.

Command String Interpreter
(CS!).
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 the user
program at task-build
time.
GCML and CS! 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 the
user
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.
The invocation of GCML and CS!
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 CS!, and establishes the
necessary working storage and communication areas for these
routines.
Also,
the
appropriate
macro calls that
invoke GCML and CS!
execution-time functions must be included
in the source coding
at
desired
logical
points to
effect the dynamic processing of command
line!s.
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 CS! control block, as appropriate.
As with all FCS macro calls, the GCML and CS! macro calls must also be
listed as an argument in an .MCALL directive (see Section 2.1) before
being issued in the user program.

6-1

COMMAND-LINE PFtOCESSING

ASCII DATJ\

PDS/MCR

GCML

DEFAULT
FILENAME
BLOCK

DATASET
DESCRIPTOR

FCS
(.PARSE)

Fl LENAME
BLOCK

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 the user
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.
All GCML functions require the creation and initialization of 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.

~
I

6-2
!11111. . .. , .. . .~. . . . . . . . . . . . . . . . . . . . . . . . . .. ,. . . . . . . . . . . . . . . . . . . . . . .,. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .,. . . . . . . . . . . . . . . . . . . .,......

COMMAND-LINE PROCESSING
GCMLB$ - Allocate and Initialize GCML Control Block

6.1.l

Issuing the GCMLB$ macro call accomplishes the following assembly-time
functions:
l.

Reserves storage for, and initializes a
within, the user 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 the user program
in the same manner as any other file.
The initialization and
maintenance of this FDB,
however,
is under GCML and FCS
control and need not be of concern to the user.

Creates and initializes a default filename block within the
GCML control block. This default filename block pertains to
an indirect command file.
If an explicit filename string
is
not specified by the user for an indirect command file, the
values CM! for the filename 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

where:

label

represents 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

represents 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 the use of an indirect
command file.
If this parameter
is not specified, a nesting
level
depth
of
O
is defined by default,
effectively eliminating an indirect command file
as a source of command-line input.

prmpt

represents a
usef-Specified,
3-character ASCII
prompting sequence. This parameter constitutes a
default prompt string that is typed out by GCML to
the user terminal to solicit command line input.

6-3

COMMAND-LINE PHOCESSING
The ASCII prompting sequence
the following 6-byte string:

A carriage
(<LF>);

The 3 ASCII characters specified by the
and

A right angle bracket (>).

rE~turn

(<CR>)

formulated
and

into

line-feed

The above string initializes GCML control
offset location G.DPRM (see Section 6.1.2).

user;

block

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

represents the address of a buffer to be used by
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 parameter nor
the size parameter is specified, a 41-word buffer
is reserved by default in the GCML control block.

GCML

lun

pdl

The. device
represents a logical unit number.
assigned to this logical unit number is used by
this
If
GCML as the command-input device.
parameter is not specified, a logical unit number
of 1 is used by default.

represents the address of an area reserved in the
user 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.
The push-down list is created through
logically equivalent to the following:
label:

.EVEN
'.BLKB

statements

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
declared with the maxd parameter (see above).

~
'I

6-4

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

COMMAND-LINE PROCESSING
2.

Multiply the sum of Step 1 by 16(10),
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 length of the push-down list is determined
as follows:
(4+1)*16.

BO.

bytes

From the above, note that 16(10) bytes of storage
are
required for each indirect command file, plus
a
total
of 16(10)
bytes for
use as general
overhead.
size

represents the size,
in bytes,
of the buffer
reserved
for
command-line
input.
The specified
size must always include 2 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 the user wants GCML to accept continuation
lines,
the specified value for the size parameter
must be greater than 82.
When 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 a user program:
GCLBLK: GCMLJ3$
GCLBLK: GCMLJ3$
GCLBLK: GCMLB$

6.1.2

GCMLB$

macro

call

might

4.,GCM,BUFADR,l.
, , BUFADR
DEPTH,GCM,BUFADR,CMILUN,PDLIST,BUFSIZ

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.
OFFSET
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
during the input of a command line.

occurred

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

COMMAND-LINE PFlOCESSING
GE.QPR 1 - Indicates that GCML was unable
or reopen the specified command file.

open

·~.

GE.BIF - Indicates that a
syntax
error
was
detected in the name of the indirect command file.
GE.MOE - Indicates that an attempt was made to
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.EQF - Indicates that the end-of-file
(EQF)
on
the first (unnested) command file was detected.
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 filename
entry thereafter
increments the
command-input
level.
When the end-of-file (EQF) is encountered
on any given
indirect file,
the command
input
level
is decremented by 1, restoring the count to
the previous level and re-opening
the associated
command
file.
The next command line from that
file is then read.
If an MCR/PDS command has already been read at
level
O, entering another MCR/PDS command when
level O is again reached causes the error code
GE.EQF 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 CTRL/Z is typed by the
user to indicate terminal end-of-file (EQF).
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 O.
Multiple inputs at level
0 are permissible only in the latter case, i.e.,
from the command-input file.
G.MQDE

Status and Mode Control Byte.
initialized at assembly-time with
to specify certain default actions
the
retrieval of a command line.

This field
is
bit definitions
for GCML during
At runtime, the

1 For GE.IQR 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
user 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 symboric 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, the user resets this bit to
zero (0), 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 the user
resets this bit to O 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(10)-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(10) bytes of
FSR-block-buffer space unavailable
for
other
purposes,
since the command file remains open
between calls for command-line input.
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, the user
resets 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.
The user must not
attempt to set this value in the mode byte without
providing a buffer larger than 82 bytes.
GE.LC Indicates that lower-case characters in
the command line are to be passed to the user
program without
mapping.
Unless
the
user
explicitly sets this value
in the GCML control
block at runtime, the default action will be to
map lower-upper case characters to upper-case
before transmission to the user program.
G.PSDS

Prompt-String Descriptor. This 2-word field
is
initialized to O at assembly-time through the
GCMLB$ macro call (see Section 6.1.1).

6-7

COMMAND-LINE PlROCESSING

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.
The user who wishes to define an alternate prompt
string elsewhere in the program 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 inputu 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.
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
descript~rs
that enable CS! to
retrieve file
specifiers from the GCML
command-line
input
buffer.

G.ISIZ

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,
count~rs, etc., in connection with input
from an
indirect command file.
In normal
usage, this
symbol need not be of concern to the user.
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.

G.DPRM

Default Prompt String.
This 6-byte field
is
initialized at assembly-time with the default
prompt string created through the prmpt parameter

6-8

,._. ..,.. ..,.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .,. . . . . . . . . . . . . . . . ."". . . . .
a•.1111. .~•. . •a•.-.111111-.. .11111. .11111.-111"";;111!111

COMMAND-LINE PROCESSING
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.
The user who wants to reference the GCML control-block offsets and bit
vaues in another module may establish the appropriate symbolic
definitions within that module through one
of
the
following
statements, as desired:
GCMLD$

;DEFAULT LOCAL DEFINITION.

GCMLD$

DEF$L

;LOCAL DEFINITION.

GCMLD$

DEF$G

;GLOBAL DEFINITION.

GCML Run-Time Macro Calls

6.1.3

Three run-time macro calls are provided in GCML
functions, as described below:

perform

GCML$

- To 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.1.3.1 GCML$ - Get Command Line - The GCML$ macro call serves as the
user 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$
where:

gclblk,adpr,inpr

gclblk

represents 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

represents the address of the
user
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
the
user
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

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

6-9

COMMAND-LINE PRC>CESSING
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
GCML$ macro call, offset location G.PSDS
automatically reset to O, causing GCML to
default prompt string contained in offset
6. 1. 2 above) •

specified
in a
subsequent
in the GCML control block is
revert to
the use of the
location G.DPRM (see Section

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 2 words constitute
the alternate prompt string descriptor.

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 FOB 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, the user may enter an at sign
(@)
as the
first
character
in the command
line, followed by the name of an indirect
command file.
This filename 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 the 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 re-opened.
If the command input
level count is already O 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).

6-10

.....----------------......------------~I-

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

COMMAND-LINE .PROCESSING

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
~, i.e., the top level command file is again used for input.

The user 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 2 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.
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 the user has 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 the user must
close the current indirect command file and return to the top-level
file, i.e., 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
represents 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.

6-11

COMMAND-LINE PROCESSING
When this macro call is issued, the current indirect command file
is
closed,
returning control
to the top-level
(unnested)
fileo
A
subsequent GCML$ macro call then retrieves the next command line from
the 0-level command file.
Note,
however,
that a second MCR/POS
command at level O 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 the user resets this bit to O,
the current
command file remains open between calls for input.
For a program that frequently reads command
files,
this may be a
desirable operational mode, since kee!ping 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, the
user may do so by issuing the CCML$ macro call.
The CCML$ macro call takes the following format:
CCML$
where:

gclblk

represents 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(10)
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, viz., the address of the GCML control block.

6.1.4

single

GCML Usage Considerations

As noted in Section 6.1.1, the GCMLB$ macro call creates an FOB in the
first
part of the GCML control block.
Although this FOB ordinarily
need not be manipulated by the user (since it is under GCML and FCS
control), the following operations may be performed on this FDB:

6-12

COMMAND-LINE PROCESSING
1.

In an irrecoverable error situation, the
user may
issue
a
CLOSE$ macro call (see Section 3.8) in connection with this
FDB before issuing the system EXIT$ macro call.

The
user
may
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),
the user may 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.

At task-build time, the Task Builder device-assignment (ASG) directive
sho~ld 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

= Tid

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.
The block-buffer requirements of the command
file must be considered when issuing the FSRSZ$ macro (FSRSZ$ must be
issued with a nonzero first parameter).

6.2

COMMAND STRING INTERPRETER (CSI)

The Command String Interpreter (CSI) analyzes command lines and parses
them
into
their component device name,
directory,
and
filename
strings.
The user should be aware that CSI processes command lines in
the following formats only:
1.

dev: [g,m]outputfilename.type;version/switch
More than one such file specification
separating them with commas.

can

specified

dev: [g,m]outputfilename.type;version/switch, ••• = dev: [g,m]
input filena~e.type;version/switch, •••

In addition,
block
(see
The run-time
calling user

CSI maintains a dataset descriptor within the CSI 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.

6-13

COMMAND-LINE PIWCESSING
The use of CSI requires that the CSI 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.2.l

CSI$ - Define CSI Control-Block Offsets and Bit Values

The only initialization coding required for CSI
that shown below:
CSI$
CSIBLK:

• EVEN
.BLKB

C.SIZE

assembly-time

;DEFINES CSI CONTROL BLOCK OFFSETS
;AND BIT VALUES LOCALLY.
;WORD ALIGNS CSI CONTROL BLOCK •
;NAMES CS! CONTROL BLOCK AND
1ALLOCATES REQUIRED STORAGE.

The CS!$ macro
is strictly definitional
in nature and does not
generate any executable code. The CS! control block resulting from
the .BLKB directive serves as a means of communication between CS! 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.
The expansion of this macro also results in the local
definition of the symbolic offsets and bit values within the CS!
control block.
If desired, the user may 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:
CS!$

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 CS! control block to be defined locally:
OFFSET
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 output
is being requested.

6-14

file

specifier

COMMAND-LINE PROCESSING
C.STAT

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.
CS.NMF - Indicates that the current file specifier
contains
a
filename
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 filename
string.
If no filename string
is present,
this
bit
is
not
set,
and the filename 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 like 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
string.
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 like 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 c~mma 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.

C.CMLD

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,
the values returned to

6-15

COMMAND-LINE PROCESSING
these cells constitute the output of CS! after
removing all
scanning
a
file
specifier and
(i.e.,
nonsignificant characters from the string
nulls, blanks, tabs, and RUBOUT's).
The values contained in these cells are used by
CS! as the descriptors of the compressed command
line to be parsed (see CSI$2 macro call in Section
6.2.3.2).
This offset defines
Dataset Descriptor Pointer.
the address of the 6-word dataset descriptor in
This
structure
is
the CS! control block.
functionally identical
to the manually created
dataset descriptor detailed in Section 2.4.1.

C.DSDS

This symbol may be used
to
initialize offset
location F.DSPT in the FOB 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 CS! control
block, and C.DSDS represents the beginning address
of the descriptor strings in the CS! control block
(see C.DEVD, C.DIRD, and C.FILD below) identifying
the requisite ASCII filename information.
Run-time
initialization
of
F.DSPT
in
the
associated FOB 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.

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.

C.FILD

Filename String Descriptor.
This 2-word
field
contains the address (C.FILD+2) and the length in
bytes (C.FILD)
of the filename
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.

6-16

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

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

~~--

COMMAND-LINE PROCESSING
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 OR'ed into this location.
The mask for a switch is specified in the CSI$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, the
user can
determine the particular combination of defined
switches present in the current file specifier.

C.MKW2

CSI Mask Word 2. This word provides the
indication of switch polarity.

user

When a switch is present in a
file specifer and
that switch is not negated, the defined mask for
that switch is OR'ed
into C.MKW2
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, the user can
check the polarity of that switch by examining the
corresponding bits in C.MKW2.
C.SIZE

6.2.3

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.

CSI 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 nonsignificant 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
filename
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-17

COMMAND-LINE PROCESSING
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 lin~ (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 (i.e.,
nulls, tabs, blanks, and RUBOUTs).
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, di rectory, and filename 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
where:

csiblk,buff ,len

csiblk

represents 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

represents the address of a command-line input
initializes
CSI
buffer.
This
parameter
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, the user 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

len

GCLBLK+G.CMLD+2,CSIBLK+C.CMLD+2

represents the length of the command-line input
buffer. SimilBrly, this parameter initializes CSI
control-block
offset
location
C.CMLD,
thus
completing the 2-word descriptor that enables CSI
to retrieve the current command line from the
input buffer.
As with the "buff" parameter above,
if this
parameter is not specified, the user 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 CSI to
analyze the current command line.
Following the analysis of the
command line, CSI updates offset location C.CMLD with the length of
the validated and compressed command line.
If a syntactic 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.

6-18

COMMAND-LINE PROCESSING
Examples of the CSI$1 macro call follow:
I

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 CSI 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 CSI 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 filename 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 CSI 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 the user program (see Section 2~4.1).
The command semantic parser also decodes any switches and associated
switch values present
in a file specifier.
If the user expects to
encounter switches in the current file specifier, the command semantic
parser decodes them,
provided that the address of the appropriate
switch descriptor table has been specified in the CSI$2 macro call
(see below).
The CSI 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
whe!re:

csiblk,io,swtab

csiblk

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

represents 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:
file
input
next
INPUT - Indicates that the
specifier in the command line is to be parsed.
file
OUTPUT - Indicates that the next output
specifier in the command line is to be parsed.

6-19

COMMAND-LINE PROCESSING
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 requested.
If 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 the user
to
the presence of an
invalid io parameter in the CSI$2 macro call.
swtab

represents the address of the associated switch
table for this particular issuance of
the CSI$2 macro call.
This optional parameter
need
be specified only when the user anticipates
the presence of a switch in the file specifier
that is to be decoded.
Specifying this parameter
presumes that the user 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, the user
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).
descript~r

This parameter initializes offset location C.SWAD
in the CS! control block (see Section 6.2.2);
if
not specified, any residual nonzero value in this
cell
is used by default as the address of the
switch descriptor table.
Offset location C.SWAD may also be
initialized
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 address
associated switch descriptor table.

the

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, i.e., 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.

6-20

...

.................................................. ..........................................."""
~

COMMAND-LINE PROCESSING
5.

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 CS! control
block,
parses an output file specifier that likewise may include a
switch.
The last example
is a
request to parse an
input
file
specifier and to disallow any accompanying switch{es).

6.2.4

CSI Switch Definition Macro Calls

The following macro calls must be issued 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 the user expects 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.
CSI$ND - Terminates a switch descriptor table or a switch-value
descriptor
table created through the CSI$SW or the
CSI$SV macro call, respective!~.
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 the user expects 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:

For each switch encountered in a file specifier, CS! 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.

6-21

COMMAND-LINE PROCESSING
2.

If a matching entry is found in the switch descriptor table,
mask word l in the CSI control block is set according to the
defined mask for that switch (see C.MKWl, Section 6.2.2).

'~
'I'

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, i.e., 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 are 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.

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.

~'.ll

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

where:

label

sw,mk,mkw,csflg,nflg,vtab,compflg
represents 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

6-22

.. ..

.,.. ,.. .,.........................,...................................""'.....................................""'-

COMMAND-LINE PROCESSING
CSI$SW macro call
include a label.
be
referenced by
program.

issued
in the program must
This label allows the table to
other
instructions
in
the

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

represents a
user-defined mask for
the switch
specified through the sw parameter above.
To
enable CS! to indicate the presence of a given
switch in a file specifier, a mask value for the
switch must be defined, as shown below:
ASMSK
NUMSK

1
2

VWMSK
XYMSK

40000
100000

where the (octal) value assigned by the user
to
each symbol defines a
unique bit configuration
that is to be set in CSI mask word 1
(C.MKWl)
of
the
control block when a defined switch is
encountered in a file specifier.
By specifying 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 the user
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

represents the address in user program storage of
a mask word that CS! changes each time it changes
C.MKWl.
CSI 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
the user's program.
The SET and CLEAR functions
are set using the csflg parameter described below.
through a
Such an optional word may be reserved
statement
logically equivalent to
that shown
below:
MASKX:

.WORD

6-23

COMMAND-LINE E1ROCESSING

csflg

represents 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 which causes the error message INVALID
SET/CLEAR SPEC to be printed in the assembly
listing.

nflg

represents 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, e.g., /-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.

vtab

represents the address of the switch descriptor
table associated with this switch. This optional
parameter, if specified, allows CS! 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

spec if ies the method CS! uses to compare the
switch name ente?red on the command line with the
value entered in the switch descriptor table via
the SW parameter.
Either LONG or EXACT may be
specified. The de?fault value is entered if a
value is not coded.
Default - If the parameter is not coded, only the
first 2 characters of the switch name (specified
via sw) are entered into the switch descriptor
table and only these 2 characters are compared
when the command line is parsed.
Additional
characters in the command-line switch name are
ignored.

6-24

•..

..........................................................", .....................................................

·~

COMMAND-LINE PROCESSING
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 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 the user intends to recognize. Entries in the switch
descriptor table consist of control information and switch-name
characters stored 2 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 l
indicates
that the next word contains more switch name characters. A sign bit
set to O 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.
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 l in the low-order bit of the address of the user
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.

6-2!)

COMMAND-LINE PROCESSING
0

char2

char1

char4

char3
EX

lastchar

nextlast

Mask Word for this Switch
Address of Optional User Mask Word
Address of Switch Descriptor Table

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

CSI$ND

6.2.4.2 CSI$SV - Create Switch-Value Descriptor Table Entry - For
every switch value that the user expects to encounter in connection
with a given switch in a file specifier, a corresponding switch-value
descriptor table entry must be defined in the user 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.

6-26

.......................................................................................................1-

COMMAND-LINE PROCESSING
The CSI$SV macro call is specified in the following format:
"'-"'

CSI$SV
wheire:

type

type,adr,len,vtab
represents 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
treated as an ASCII string.

NUMERIC - Indicates that a numeric switch value 1s
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
specified, 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

represents the address of the
user
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.
represents 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.
NOTE
The len oarameter is ignored for all types
except ASCII.

vtab

represents a symbol that names the switch-value
descriptor table and defines its address.
This
parameter is optional.
The vtab parameter may
also be specified
in the CSI$SW macro call {see
Section 6.2.4.1) when the user anticipates the
presence of a switch value in a file specifier
that is to be decoded.
{If the vtab parameter
is
specified in the CSI$SW macro call, there is no
need to specifv it in the CSI$SV macro call.)

6-27

COMMAND-LINE P:ROCESSING

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 l if ASCII is specified;
it is
set to 2 if NUMERIC or OCTAL is specified;
it 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 resultant binary value
is
assumed to be 2 bytes in length, and the area receiving the value is
assumed to be word-aligned.
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 (e.g., #10) forces the
conversion type to octal;
a numeric value followed by a dot (e.g.,
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 (e.g., -#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.

0
Switch Value Length

Conversion Type

Address of Location Receiving Switch Result

Figure 6-3

Format of Switch-Value Descriptor Table Entry

6-28

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111111. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ."". . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .

COMMAND-LINE PROCESSING
Representative CSI$SV macro calls
ASVTBL: CSI$SV
CSI$SV

CSI$SV

shown below:

ASCII,ASVAL,3
ASCII,ASVAL+4,3

CSI$ND
NUVTBL: CSI$SV

arE~

;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 the user program location to
receive the resultant switch value.
The required storage for the first switch value
reserved as follows:
ASVAL

• BLKW

table

.BLKW

may

table

may

;ASCII VALUE STORAGE •

The required storage
for
the second switch-value
similarly reserved through the following statement:
NUVAL:

above

;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 0, may be
created through the CSI$ND macro call.
This macro call takes no arguments, as shown below:
CSI$ND
The examples near the end of the preceding section illustrate the
of this macro call.

6-29

use

~\
j

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 va·riables, and the~ user's 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,
a
syntactical level and a semantic level.
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 syntactic 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 user parsing routine.
TPARS parses command lines using a user-defined table consisting of
states and
transitions.
This table is referred to as a state table
and is built 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-·l

THE TABLE-DRIVEN PAHSER (TPARS)
7.1.1

TPARS Macros: ISTAT$, 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 the user's state
table,
and the TRAN$ macro defines the conditions for transition to
another.·

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
where:
statetable is the label the user assigns to the state
equates this label to the start of the state table.

table.

TPARS

keytable is the label the user assigns to the keyword
equates this label to the start of the keyword table.

table.

TPARS

$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 the user defines the symbol $RONLY, each of these program sections
is generated as read-only. A read-only state table is generated by
specifying the symbol $RONLY preceding the ISTAT$ macro in the form~
$RONLY = 1
!STAT$ statetable,keytable,$DEBUG

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 another.
The STATE$ macro
is
coded in the following form:
STATE$ [label]
where label is an alphameric symbol that is equated to the address
the state.

Each state is comprised of any number of transitions, which define the
conditions under which control can be passed to another state.

7-2

'~
..
".
:~
I

THE TABLE-DRIVEN PARSER (TPARS)
7.1.1.3 Defining a Transition:
provides:

the

$TRAN

Macro - The

TRAN$

•

The means for matching a given type of syntax element.

•

Direction to the next state to be processed.

•

The address of the action
syntax element.

•

A maskword and maskword address.

routine

process

the

macro

current

The TRAN$ macro is coded in the following form:
TRAN$ type [,label] [,action] [,mask] [ ,maskaddr]
[.$EXIT]
where:
type

specifies 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]

specifies 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

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

mask

specifies 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

specifies 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
means for
flagging
the execution of
transition.

7-3

a
a

convenient
particular

THE TABLE-DRIVEN PARSER (TPARS)
7.1.2

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:
ch~racter.

$ANY

Matches any single

$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 transitions 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 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 alphameric character string (0-9,A-Z).
string will not be null.

$RAD50

Matches any legal RADIX-50 string, that is, any string
containing alphameric characters and/or the period (.)
and dollar sign ($) characters.
Conversion to RADIX-50
format is the responsibility of the action routine.

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

The

keyword"

Matches a specified keyword.
Keywords may be any
length, may contain only alphameric characters, and are
terminated by the
first
nonalphameric
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.

7-4

I Pl.

w••

THE TABLE-DRIVEN PARSER (TPARS)
7.1.3

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 the user's 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
returned
by
a
$NUMBR
or
specification.

value of the number
syntax type
$DNUMB

.PNUMB

returns the low-order binary
returned
by
a
$NUMBR
or
specification.

value of the number
syntax type
$DNUMB

.PCHAR

returns the character found by the $ANY,
$DIGIT, or char syntax type specifications.

• PE'LAG

returns the value of the flag word passed to TPARS via
register 1 (Rl).
Action routines can modify this word
to change options dynamically.

.TPDEB

contains
the
entry
address
(user-supplied) ·debug routine.

returns the byte count 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.

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

$ALPHA,

optional

7.1.3.2 Calling Action Routines - Action routines are called via a
JSR PC instruction. Action routines may modify registers RO, Rl, and
R2t
all other registers must be preserved.

7.1.3.3 Using Action Routines to Reject
a
Transition - Action
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

7-5

THE TABLE-DRIVEN PA:RSER (TPARS)

ADD #2,(SP)
before returning to the caller. This technique allows
additional processing of syntax types and allows extension of 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 i~ 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 via the
.TPARD entry point
(rather
.TPARS). TPARS is invoked as described in Section 7.4.

than

via

tipon 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
if the optional $DEBUG parameter is provided in the !STAT$
macro call (see Section 7.1.1.1).
i\

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 •.
Suhexpressions 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 via a TRAN$
macro that specifies a !label syntax element as the type parameter:
TRAN$ !UIC,NEXT

7-6

__ kQ. I.

fit•

THE TABLE-DRIVEN PARSER (TPARS)
TPARS then directs control to the STATE$ macro with the label UIC:
STATE$
TRAN$ ' [

UIC

STATE$
TRAN$ $NUMBR,,SETGN
STAn$
TRAN$ <', >
STATE$
TRAN$ $NUMBR,,SETPN
STATE$
TRAN$ '],$EXIT
When the UIC subexpression completes processing, control passes to the
state labeled NEXT.

7.2

GENERAL CODING CONSIDERATIONS

This section contains information describing how to arrange syntax
types in a state table, rules for entering special characters (commas
and angle brackets), and how to direct TPARS to ignore blanks and tab
characters in a command line.

7.2.l

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

THE TABLE-DRIVEN PARSER (TPARS)
7.2.2

Entering Special Characters

In "char" 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 wchar" syntax
use angle brackets:

element

~
I

string,

TRAN$ <I I>
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.3

1·

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 one 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 zero, 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.
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:
STATE$
TRAN$

$STRNG

STATE$
TRAN$

$STRNG

the

same

7-8

...

,._ ,..............................................................,.....................................

THE TABLE-DRIVEN PARSER (TPARS)
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 (non-alphanumeric)
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:

'-''

"NO",STATEl,SETNEG
$ LAMD.A,, SETPOS

STATE$
TRAN$
TRAN$

STATEl
II AA" ' •••
"BB", •••

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.
The following example can be used to achieve
the desired operation:

'-'.·

STATE$
TRAN$
TRAN$

!NONO,STATEl,SETNE"G
$LAMDA, ,SETPOS

STATE$
TRAN$
TRAN$

STATE
"AA II ' • • •
"BB", •••

STATE$
TRAN$

NONO
'N

STATE$
TRAN$

'O,$EXIT

In this example, TPARS attempts to match the subexpression NONO to the
prefix one character at a
time.
This bypasses the keyword
scanning of TPARS, allowing the input pointer to be left pointing at
"AAw
or "BB".
If NONO fails, the input pointer will not be changed
and the scan can continue by looking for "AA" or "BB".

"Now

7.3

PSECTs GENERATED BY TPARS MACROS

TPARS macros generate three PSECT's.
Data associated with the STATE$
macro
is stored in the PSECT $STATE.
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:

7-9

THE TABLE-DRIVEN P'ARSER (TPARS)

Flags

11ype

Type Extension
Action Return Address
Mask word
Maskword Address
Target State Label

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
310
Used in the !label type.
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
table.
The keyword table is an array of pointers to keyword strings.
The keyword strings 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:
Bit

Meaning ·

0
1
2
3
4

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.

7.4

INVOKING TPARS

The user controls execution of TPARS using the calling conventions and
options described
in this section. TPARS is invoked from within an
executing program on an !AS or RSX-llM system by means of the
instruction:
CALL

.TPARS

When a user-supplied debug routine is used for tracing TPARS operation
{see Section 7.1.3.4), a special entry point is called, as follows:
CALL

.TPARD

7-10

,, j .Jill.Ji

.. LIUlJl\

U:Ut. .Q IL

ii'_.

THE TABLE-DRIVEN PARSER (TPARS)
When TPARS is called in this manner, TPAES calls the debug routine at
each state transition.
If TPARS is
invoked via the .TPARS entry
point, the debug routine entry point address in .TPDEB is cleared, and
the debug routine is not called.

7.4.1

When TPARS is invoked, registers in the calling program
the following information:
Rl
R2
R3
R4
RS

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

The values of all other registers are preserved.
The carry bit in the Processor Status Word
returns zero
for
a
successful parse;
the carry bit is set when TPARS finds a syntax
error.
For an example of a calling

sequence

for

TPARS,

refer

Section

7.6.1.

7.4.2

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 zero, keywords being parsed must exactly
match 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.

7-11

THE TABLE-DRIVEN PARSER (TPARS)
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.5

string

are

$EOS

HOW TO GENERATE A PARSER PROGRAM USING TPARS

There are three processes involved
in
using TPARS, as shown in Figure 7-1.

generating

parser

program

As shown
in Figure 7-1,
the source program must contain MCALL
statements for
three macros, !STAT$, STATE$, and TRAN$.
These three
MCALL statements must precede the statements that comprise the state
table and action routines.
Assembly of the source module produces an object module comprised of
three PSECT's,
$STATE,
$KTAB,
and $KSTR.
When the Task Builder
executes, the task image produced is placed on ~n appropriate volume
for future use.

~1::

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.

7-12

,..-r-..,_..-..........................................."91. . . . . . . . . . . . . . . . . . . . . ..,..

THE TABLE-DRIVEN PARSER (TPARS)

PARSER.SAC

..., _____ _.,..

EDI

Write a source program that
includes the required MCALL
statements.

MCALL ISTAT$
MCALL STATE$
MCALL TRAN$
STATE$

STATE$

'-".

'-"

t:hl
EYf
[:J=
LYJ

PARSER.OBJ

$STATE

Assemble the source program to
produce an object module.

$KTAB
$KSTR

PARSER.OBJ

'-'

MYFILEOBJ

L:J==
L:J==

MYFILE.TSK

Execute the Task Builder to
produce a task image including
the parser.

UPDATE.OBJ

~·

Figure 7-1

..
Processing Steps Required to Generate a Parser
Program Using TPARS

7-13

THE TABLE-DRIVEN PJrnSER (TPARS)

When the parser program is linked and is in task image form, it can be
invoked from within an executing user program, as shown in Figure 7-2.

Executing
User Program

User-defined
Parser Program

·-··-

r·---•

STATE$
*
*
*
STATE$

-----------CALL .TPARS

Action
Routines

Figure 7-2

TPARS
Processor

f-1--,

I
I

14-- _J

I
I

f-4----_J

...-

Flow of Control When TPARS Is Called from an Executing
User Program

Figure 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 th~ built-in variables. When the state table completes execution,
TPARS receives control and passes control back to the calling program.

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 UFD 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
$UVNAM
$UUIC
$UALL
$UPRO
$FLAGS
UF.ALL
UF.PRO

this

parser

program

return

the

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.

7-14

following

THE TABLE-DRIVEN PARSER (TPARS)
The label and the /ALLOC and /PRO switches are optional.
sequence for this routine is as follows:
CLR
MOV
MOV
MOV
MOV
CALL
BCS

Rl
#UFDKTB,R2
COUNT,R3
ADDR,R4
#START,RS
.TPARS
ERROR

The following is the user-written parser routine:
.TITLE

STATE TABLE FOR UFD COMMAND LINE

.MCALL

ISTAT$,STATE$,TRAN$

TO BE USED WITH BLANK SUPPRESS OPTION
ISTAT$

UFDSTB,UFDKTB

READ OVER COMMAND NAME
.GLOBL

START

STATE$
TRAN$

START
"UFD"

READ DEVICE AND UNIT NUMBER
STATE$
TRAN$

$ALPHA,,SETDV1

STATE$
TRAN$

$ALPHA,,SETDV2

STATE$
TRAN$
TRAN$

$NUMBR,DEV1,SETUNT
$LAMDA

STATE$
TRAN$

DEVl
':

READ VOLUME LABEL
STATE$
TRAN$
TRAN$

$STRNG,RUIC,SETLAB
$LAMDA

STATE$
TRAN$

RUIC
! UIC

READ UIC

SCAN FOR OPTIONS AND END OF LINE
STATE$
TRAN$
TRAN$
STATE$
TRAN$
TRAN$

OPTS
$EOS,$EXIT

'/
"ALLOC",ALC,,UF.ALL,$FLAGS
"PRO",PRO,,UF.PRO,$FLAGS

7-15

The

calling

THE TABLE-DRIVEN PARSER (TPARS)
SET ALLOCATION
STATE$
TRAN$
STATE$
TRAN$

ALC

'=
$NUMBR,OPTS,SETALC

PROTECTION
STATE$
TRAN$

PRO
I=

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

[,,IGROUP

·~.

SUBEXPRESSION TO READ AND STORE UIC
STATE$
TRAN$

UIC
I

[

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 'rHE 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

7-16

.....................................,..................................llmll. . . . . . . .111111. . . . . . . . . . . . . . . . . . . . . . . . . . . . .,.-

THE TABLE-DRIVEN PARSER (TPARS)
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)

CHECK FOR ZERO HIGH ORDER
CHECK FOR BYTE VALUE
BAD VALUE - REJECT TRANSITION

; NUMBER OF ENTRIES TO ALLOCATE
S ET.~LC : : MOV

.PNUMB,$UALL
RETURN

SET PERMISSIONS
INITIALIZE
IGROUP::MOV

#4,GRCNT

; MOVE TO NEXT PERMISSIONS CATEGORY
NXGRP::

BADGRP:
30$:
;
·~

#FP.RDV*l0000,$UPRO

BIC
RETURN

#FP.WRV*l0000,$UPRO

SHIFT TO NEXT GROUP
COUNT GROUPS
TOO MANY IS AN ERROR
IF SO, REJECT TRANSITION

SET EXTEND PERMIT

SETEP: :
;

BIC
RETURN

FORCE ONES

SET WRITE PERMIT

SETWP::
;

$UPRO
$UPRO
$UPRO
$UPRO
GRCNT
30$
# 2, (SP)

SET READ PERMIT

SETRP: :
;

SEC
ROR
ASR
ASR
ASR
DEC
BGE
ADD
RETURN

BIC
RETURN

#FP.EXT*l0000,$UPRO

SET DELETE PERMIT

SETDP: :

BIC
RETURN
; END OF PROTECTION SPEC

#FP.DEL*l0000,$UPRO

'"-'
7-17

THE TABLE-DRIVEN PARSER (TPARS)
ENDGRP: : TST

7.6.2

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

TURN OFF SPACE FLUSH

; TEST FOR QUOTING CHARACTER IN THE STRING
TESTQ:
10$:

CMPB
BNE
ADD
RETURN

.PCHAR,QCHAR
10$
#2, (SP)

7-18

REJECT TRANSITLON ON MATCH

THE TABLE-DRIVEN PARSER (TPARS)
; STORE THE STRING DESCRIPTOR
S:E:TST:

MOV
MOV
RETURN

.PSTPT,QSTP
.PSTCN,QSTC

; RESET THE SPACE FLUSH FLAG
DECB
RETURN

7.6.3

.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
di~c imal.
The binary value of the number is returned in the tagged NUMBER.
following types of strings are accepted:
10/0CTAL
359/DECIMAL
77777 /OCTAL
MAIN STATE TABLE ENTRY - ACCEPT THE EXPRESSION AND
STORE ITS VALUE
STATE$
'fRAN$
'rRAN$

!ONUMB,NEXT,SETNUM
JDNUMB,NEXT,SETNUM

SUBEXPRESSION TO ACCEPT OCTAL NUMBER
STATE$
'fRAN$

ONUMB
$NUMBR

STATE$
'rRAN$

STATE$
TRAN$

"OCTAL",$EXIT

SUBEXPRESSION TO ACCEPT DECIMAL NUMBER

;

STATE$
'rRAN$

DNUMB
$DNUMB

STATE$
'fRAN$

STATE$
'.rRAN$

"DECIMAL",$EXIT

ACTION ROUTINE TO STORE THE NUMBER

SETNUM:

MOV
MOV
HE TURN

.PNUMB,NUMBER
.PNUMH,NUMBER+2

7-19

The

THE TABLE-DRIVEN PARSER (TPARS)

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 subexptession 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 via $EXIT, the transition is taken and control passes to the
next state.
If the subexpression encounters a synta>c 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
action
by action routines called by subexpressions.
Therefore,
in an
routines called from subexpressions should store results
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
fdb

represents the address of the associated FDB.

err

represents the address of an optional user-coded
handling routine. See Section 8.3.

error

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

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

unit

represents 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

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

8-1

SPOOLIHG

8.2

forms

represents the specific form-type on which the file
is
to be printed as indicated by a number in the range O
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 O is used by default.

copies

represents a number in the range l
through 32(10)
to
indicate the number of copies of the file
to be
produced. The number of copies must be specified as a
1- or
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.

.PRINT SUBROUTINE

The .PRINT subroutine is called to queue a file for
printing.
The
file must be open when .PRINT is called. 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.
If the failure is FCS related, e.g., 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-2

¥-··

APPENDIX A

FILE DESCRIPTOR BLOCK

A file descriptor block (FOB) contains file information that is used
by FCS and the file control primitives.
The layout of an FOB 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

defined

either

;DEFINE OFFSETS LOCALLY.

FDOFF$

DEF$L

;DEFINE OFFSETS LOCALLY.

FDOFF$

DEF$G

;DEFINE OFFSETS GLOBALLY.
NOTE

When referring to FOB 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

FILE DESCRIPTOR BLOCK
F.RATT

F.RTYP
F.RSIZ

File-Attribute Section
F.HIBK
F.EFBK
F.FFBY

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

F.LUN

File-Open Section
F.DSPT
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

Figure A-1

File Descriptor Block Format

A-2

Stu

FILE DESCRIPTOR BLOCK
Table A-1
FOB Offset Definitions
OFFSET

SIZE
(in bytes)

CONTENTS

F. R~~yp

Record-type byte.
This byte is set, as
follows, to indicate the type of records for
the file:
F.RTYP = l 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. RJ~TT

Record-attribute byte. Bits O through 3 are
set
to
indicate record attributes, as
follows:
Bit 0 = l to indicate that the first byte of
a
record
is
to
contain
a
FORTRAN
carriage-control
character
(FD.FTN);
otherwise, it is o.
Bit l = l 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 O.
Bit 2 is not used.
Bit 3 = l to indicate that records cannot
cross block boundaries (FD.BLK); otherwise,
it is o.

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

F. Elf!'BK

Contains the end-of-file block number.

F. F.FBY

2 .

Indicates the first
free byte in the last
block,
or
the maximum block size for
magnetic tape.

virtual-block

number

(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 O 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$ moqe.
Bit 1 = 1 to
indicate random-access mode
(FD.RAN)
for
GET$/PUT$
record
I/O;
otherwise, it. is O to
indicate sequential
access mode.

F.RACC

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
(FD.INS);
otherwise, it is Oto
indicate
that
PUT$ operation in sequential mode
truncates the file.

F.RCTL

Device-characteristics byte.
Bits 0 through
5 define the characteristics of the device
associated with the file, as follows:
Bit 0 = 1 to
indicate
device
(FD.REC),
e.g.,
printer;
a value
of
block-oriented
device,
DECtape.

a
record-oriented
a Teletype or line
O
indicates
a
e.g.,
a disk or

Bit 1 = 1 to
indicate a carriage-control
device (FD.CCL);
otherwise, it is O.
Bit 2 = 1 to indicate a teleprinter
(FD.TTY);
otherwise, it is O.

device

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
UFD's are present.
(continued on next page)

A-4

SJJJ4jlllft

FILE DESCRIPTOR BLOCK
Table A-1 (Cont~)
FDB Offset Definitions
OFFSET

SIZE
(in bytes)

Bit 5 = 1 to
indicate a
block-oriented
device that is inherently sequential
in
nature
(FD.SQD).
A record-oriented device
is assumed to be sequential
in nature;
therefore,
this bit is not set for such
devices.

F.RCTL
(Cont.)

'-'

'-"

CONTENTS

F.BK DS
0 r
F.UR BD

F .NR BD
0 r
F.BK ST
an d

Contains the next record-buffer descriptor.

Contains the address of the I/O status block
for block I/O.

F.BK DN

Contains the address of
routine for block I/O.

F.OVBS
or

Override block-buffer size.
This field has
meaning only before the file is opened.

F.NREC

Contains the address of the next
the block.

.F.EO BB

Contains a value defining
buffer.

.F .RC NM
0 r

Contains the number of the record for random
access operations.

F.CN 'TG

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 O 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 the user 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.

Contains the block-I/0-buffer descriptor.
Contains the user-record-buffer descriptor.

the

AST

service

record

end-of-block

(continued on next page)
A-5

FILE DESCRIPTOR BLOCK

Table A-1 (Cont.)
FDB Offset Definitions
OFFSET

SIZE
(in bytes)

F.LUN

Contains the logical unit number
with the FDB.

F.FACC

File-access byte.
This byte
indicates the
access privileges for a file, as summarized
below:

CONTENTS

associated

Bit 0 = 1 if the file is accessed
only (FA.RD).

F.ACC

for

read

Bit 1 = 1
if the
writing (FA.WRT).

file

accessed

for

Bit 2 = 1 if the
extending (FA.EXT).

file

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
(FA.TMP).

temporary

Bit 5 = 1 if the file is opened
access (FA.SHR).

file

for

shared

being

If Bit 3 above is 0:
Bit 6 = 1 if an existing
appended (FA.APO).

file

If Bit 3 above is one (1):
Bit 6 = 1 if not superseding an
file at file-create time (FA.NSP).

existing

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 the record I/O event flag.
Contains bookkeeping bits for
control.

FCS

internal

(continued on next page)

A-6

FILE DESCRIPTOR BLOCK
Table A-1 (Cont.)
FDB Offset Definitions
OFFSET

SIZE
(in bytes)

F.ERR

Error return code byte.
A negative
indicates an error condition.

F.ERR+l

Used in conjunction with F.ERR above.
If
F.ERR is negative, the following applies:

CONTENTS

value

F.ERR+l = 0 to indicate that error code
is
an I/O error code (see IOERR$ error codes in
Append ix I Ji •
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
currently in use.

buffers

F .MBFG

Multiple-buffering
flag
word.
Contains
either one of the multiple buffering flags,
as follows:
Bit 0

number

used

= 1 to indicate read-ahead (FD.RAH).

Bit 1 = 1 to indicate write-behind

(FD.WBH).

F. BGBC

Big-buffer-block count in number of blocks
(not implemented).

F.VBSZ

Device-buffer-size
word.
Contains
virtual-block size (in bytes).

F.BBFS

Indicates the block-buffer size.

F.BIKVB
or

Contains the virtual-block
user program for block I/O.

F. VBN
F.BlDB

the

number in the

Contains the virtual-block number.
2

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)

F.SPDV

Spooler
only) •

F.SPUN

Spooler output unit designation (IAS only).

F.CHR

Reserved for system use.

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.

CONTENTS

output

Bit 15 = 1
information
(FA.ENB).

device

designation

(IAS

byte

to specify that control
is to be taken from F.ACTL

Bit 12 - O 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.OLK).
F.SEQN

F.FNB

Contains the sequence number
records.

for

Defines the beginning
address
filename-block portion of the FDB.

sequenced

the

A-8

. . . ., . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ., . .. . . . . . . . . . . . . . . . . . . . . .l. .1!1111111. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .,,~.

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:

NBOF$L

;DEFINE OFFSETS LOCALLY.

NBOFF$

DEF$L

;DEFINE OFFSETS LOCALLY.

NBOFF$

DEF$G

;DEFINE OFFSETS GLOBALLY.
NOTE

When
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.
Table B-1
Filename-Block Offset Definitions
OFF'SET

SIZE
(in bytes)

N.F'ID

File-identification field.

N.F'NAM

Filename field;
specified as 9 characters
that are stored in Radix-50 format.

N.F'TYP

File-type field;
spec i f ied as 3 characters
that are stored in Radix-50 format.

N.FVER

File version number field

N.S TAT

Filename-block
status
word
definitions in Table B-2) •

N.N EXT

Context for next • FIND operation.

N.D ID

Directory-identification field.

N.D,VNM

ASCII device-name field.

N.U NIT

Unit-number field

CONTENTS

B-1

(binary) •

(binary).

(see

bit

FILENAME Bl'..OCK
The bit definitions of the filename-block status word (N.STAT)
FDB and their significance are described in Table B-2.

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.

a
2

N.FID

4
6
N.FNAM

10
12

N.FTYP

N.FVER

CUMULATIVE
LENGTH IN
BYTES (OCTAL)

N.STAT

20
N.NEXT

22
24

N.DID

...,.\

30
N.DVNM
N.UNIT

32
34

Figure B-1

Filename-Block Format

Table B-.2
Filename-Block Status Word
SYMBOL

VALUE
(in octal)

. if·
·~.··~

(N.STAT)

MEANING

number

NB.VER*

Set if explicit file version
specified.

NB.TYP*

Set if explicit file type is specified.

NB .NAM*

Set if explicit filename is specified.

(continued on next page)

B-2

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .

FILENAME BLOCK
Table B-2 (Cont.)
Filename-Block Status Word (N.STAT)
SYMBOL

VALUE
(in octal)

MEANING

NB.SVR

Set if wild card file version
specified.

NB.STP

Set if wildcard file type is specified.

NB.SNM

Set if wildcard filename is specified.

NB.DIR*

100

Set if explicit directory
is specified.

NB.DEV*

200

Set if explicit
specified.

NB.SDl

400

Set if group portion of
wildcard specification.l

UIC

contains

NB.SD2

1000

Set if owner portion of
wildcard specification.l

UIC

contains

set

1 Although NB.SDl and NB.SD2 are defined, they
supported by FCS.

B-3

number

string

device-name

are

not

(UIC)

string

APPENDIX C
SUMMARY OF I/0-RELATED SYSTEM DIRECTIVES

Table C-1 contains a summary of the I/O-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
DIHECTIVE
ALUN$

GLUN$

FUNCTION AND PARAMETERS
Assigns a logical unit number to a physical device:
lun

= Logical unit number.

dev

= Physical device name

unt

= Physical device-unit number.

(2 ASCII characters).

Fills a 6-word buffer with information about a physical
unit:
lun

= Logical unit number.

buf

= Address of a

6-word buffer
information is to be stored.

which

GMCR$

Transfers an 80-byte MCR/PDS
issuing task.
No pa.rameters
directive.

QIO$

Places an I/O request in the device queue
with the specified logical unit number:
f nc

= I/O function code.

lun

= Logical unit number.

efn

= Event flag number.

pri

= Priority of the request

the

command line
are required

LUN

to
the
in this

associated

(!AS only).
(continued on next page)

C-1

SUMMARY OF I/0-RELATED SYSTEM DIRECTIVES
Table C-1 (Cont.)
Summary of I/O-Related System Directives
DIRECTIVE
QIO$
(Cont.)

FUNCTION AND PARAMETERS
isb
ast

= Address of the I/O status block.

= Entry-point address of the AST service routine.

prl = Parameter list in the form <Pl, ••• ,P6>.
RCVD$

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
!AS
(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).
RCVS$

Receives a 13-word data block, if queued by a send-data
di"rective (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.
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

= Name of the sending task.

buf

This field is ignored
by RSX-11.
The tsk parameter is specified as a
null value (,) in RSX-11 for compatibility with
!AS
(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:

= Name of the receiving task.
buf = Address of the 13-word data buffer.
tsk

efn

= Event flag number.
(continued on next page)

C-2

SUMMARY OF I/0-RELATED SYSTEM DIRECTIVES
Table C-1 (Cont.)
Summary of I/0-Related System Directives
DIRECTIVE
SDRQ$

FUNCTION AND PARAMETERS
Queues (FIFO) a 13-word bloc~ 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

pri

= Priority of the request.

ugc

= UIC group code.

upc

= UIC owner C Od E~ •

buf

= Address of the 13-word data buffer.

efn

= Event flag number.

namE~

of the receiving task.

'I'his 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 proqram 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
OUTLUN=4
;ASSIGN TO OUTPUT DEVICE
FSRSZ$
2
FDBOUT: FDBDF$
;ALLOCATE SPACE FOR OUTPUT FDB
FDAT$A R.VAR,FD.CR
;!NIT FILE ATTRIBUTES
FDRC$A ,RECBUF,80.
;!NIT RECORD ATTRIBUTES
FDOP$A OUTLUN,,OFNAM
;!NIT FILE OPEN S~CTION
FDBIN:
FDBDF$
;ALLOCATE SPACE FOR INPUT FDB
FDRC$A ,RECBUF,80.
;!NIT RECORD ATTRIBUTES
;!NIT FILE OPEN SECTION
FDOP$A INLUN,, IFNAM
RECBUF: .BLKB
;RECORD BUFFER
80.
;OUTPUT FILENAME
OFNAM: NMBLK$ OUTPUT,DAT
I FNJ\M: NMBLK$
INPUT,DAT
; INPUT FILENAME
;!NIT FILE STORAGE REGION
STAHT:
FIN IT$
OPEN$R #FDBIN
;OPEN THE INPUT FILE
BCS
ERROR
;BRANCH IF ERROR
OPEN$W #FDBOUT ;OPEN THE OUTPUT 'FI LE
BCS
ERROR
;BRANCH IF ERROR
GTREC: GET$
#FDBIN
;NOTE - URBD IS ALL SET UP
BCS
CKE OF
;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
#40,-(R2)
;STRIP TRAILING BLANKS
BNE
PTREC
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

D-1

SAMPLE PROGRAMS
BCS
CLOSE$
BCS
EXIT$S
.END

ERROR
#FDBOUT
ERROR

;CLOSE THE OUTPUT FILE

~
I

;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$,CLOS~$,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
0,0
;FILENAME DESCRIPTOR
.WORD
ONAM$Z,ONAM
;DEVICE DESCRIPTOR
I FD SP T : • WO RD
0,0
;DIRECTORY DESCRIPTOR
.WORD
0,0
;FILENAME DESCRIPTOR
.WORD
INAMSZ,INAM
.ASCII /OUTPUT.DAT/
ONAM:
ONAMSZ=.-ONAM
.EVEN
.ASCII /INPUT.DAT/
!NAM:
INAMSZ= .-!NAM
.EVEN
;!NIT FILE STORAGE REGION
START:
FINIT$
;OPEN THE INPUT FILE
OPEN$R #FDBIN
;BRANCH IF ERROR
BCS
ERROR
OPEN$W #FDBOUT ;OPEN THE OUTPUT FILE
;BRANCH IF ERROR
BCS
ERROR
;NOTE - URBD IS ALL SET UP
GTREC: GET$
#FDBIN
;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+!
ADD
Rl,R2
;STRIP TRAILING BLANKS
CMPB
#40,-(R2}
10$:
BNE
PTREC
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
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$
FDBJCN:
FDBDF$
RECBUF: .BLKB
80.
CFDSPT: .WORD
0,0
;DEVICE DESCRIPTOR
.WORD
0,0
;DIRECTORY DESCRIPTOR
.WORD
ONAM$Z,ONAM
;FILENAME DESCRIPTOR
IFDSPT: .WORD
0,0
;DEVICE DESCRIPTOR
.WORD
0,0
;DIRECTORY DESCRIPTOR
.WORD
INAMSZ,INAM
;FILENAME DESCRIPTOR
ONAIM:
.ASCII /OUTPUT.DAT/
ONAMSZ=.-ONAM
.EVEN
INAM:
.ASCII /INPUT.DAT/
INAMSZ=. -INAM
.EVEN
START:
FIN IT$
;INIT FILE STORAGE REGION
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) ,Rl
;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
PTREC
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
EXI'r$s
;ISSUE EXIT DIRECTIVE
.END
START
.M~ALL

'-"'

D·-3

APPENDIX E

INDEX FILE FORMAT

The index file ([O,O]INDEXF.SYS) of Cl 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 l.

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,
starting
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 !AS, 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
n~mber 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
file-control primitives can use this block to create a file.

1 -

E.4

Indicates that the file-header block is in
has already been used to create a file.

use.

This

block

with

PREDEFINED FILE-HEADER BLOCKS

The first five file-header blocks are described below.

SIGNIFICANCE

FILE-HEADER BLOCK
Index-File Header

This is the standard header
the index file.

associated

S to rage-Map-File
Header

The storage map is a file
control the assignment of
files.

that is used to
disk blocks to

Bad-Block-File
Header

The bad-block file is a file that consists of
unusable blocks (bad 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
ch~ckpoint
file,
and
all
user
file
directories (UFOs).

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.

E-2

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

INDEX FILE FORMAT
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.
Table g-1
Home-Block Format

E-3

INDEX FILE FORMAT
Table E-1 (Cont.)
Home-Block .f.i'ormat

SIZE
(in bytes)

CONTENT

OFFSET

100.

Volume-header label (not
used) •

82.

System-specific information (not used) •

254.

Relative volume table
(not used) •

Checksum of home block
(Words 0 through 255) •

H.CHK2

~
I

E-4

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

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 A.REA

SIZE
{in bytes)

CONTENT

OFFSET

Identification-area offset
in words.

H. IDOF

Map-area offset 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

HEADER AREA
(Cont.)

IDENTIFICATION
AREA

MAP AREA

SIZE
(in bytes)

CONTENT

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

Filename (Radix-SO).

I. FNAM

File type (Radix-SO).

I. FTYP

File version number
(binary).

I.FVER

Revision number.

I. RVNO

Revision date.

I.RVDT

Revision time.

I.RVTI

Creation date.

I .CRD'I'

Creation time.

I.CRT!

Expiration date.

I. EXD'l'

·To round up to word
boundary.
Size (in bytes) of
identification area of
file-header block.

S. IDHD

Extension segment number.

M.ESQN

Extension relative volume
number (not impl~mented).

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
AREA

SIZE
(in bytes)

Ml.. P AREA
(Cont.)

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 O 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
OFFSET

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

- 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,
e.g., the index file is number 1,
the storage
bit map is file number 2, etc.

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
UIC's 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
When
file can be used and who can use it.
creating the file,
the
user
specifies the
extent of protection desired for the file.
FILE CHARACTERISTICS -

This word, consisting of 2 bytes,
status of the file.

defines

the

Byte O 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.OLK = 100 - File improperly closed.
Byte 1 defines system-controlled
tics, as follows:

USER FILE
ATTRIBUTES

F.2

characteris-

SC.MDL

200

SC.BAD

100 - Bad data block in file.

~\
rr1

-- -

File marked for delete.

- This area consists of 16 words. The first
7 words of this area are a direct image of the
first
7
words of the FOB when the file is
opened.
The other 9 words of the
record
I/O
control
area are not used by FCS, although RMS
does use them.

IDENTIFICATION AREA

The information in the identification area of the
consists of the following:
FILENAME

file

header

block

- The file's creator specifies a filename of up
to 9 Radix-50 characters in length.
This name
is placed
in the name
field.
The
unused
portion of the field (if any) is a-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.

type

Radix-50

F-4

.) =

u 1114 .;; ..

FILE-HEADER BLOCK FORMAT
REVISION NUMBER

This word is initialized to O 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
(2 bytes,
3 bytes, and 2 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 (2 bytes each).

CREA.TION DATE

- The date on which the file was created is kept
in a 7-byte field having the same format as 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 the
revision time (see above).

EXPIRATION DATE .

F.3

The date on which the file becomes eligible to
be deleted is kept in a 7-byte field having the
same format as the revision date
(see above).
Use of expiration is not implemented.

MAP AREA

The map area contains the information necessary to map virtual-block
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:

file

COUNT-1

HIGH LBN

LOW

LBN

F-5

structure

are
is

FI LE-HEADER BLOCJC FORMAT

NOTE
The
remaining
paragraphs
in
. this
appendix
apply
to IAS,
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 O 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
file-control
primitives as needed;
their use is transparent to the user.

F-6

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 June 19, 1974 Proposed Revision
to the ANSI standard Magnetic Tape Labels and File Structure for
Information Interchange (X3.27-1969).
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
file-header labels.

G.Ll

the

format

volume

labels

and

Volume Label Format
Table G-1
Volume Label Format

r-·

CHAHACTER
POSITION

LENGTH
CONTENTS

FIELD NAME

IN BYTES

1-3

Label identifier

VOL

Label number

5-10

Volume identifier

Any
label.
Volume
special
alphanumeric
or
character in the center four
columns
of· the ASCII code
table.

Accessibility

Any alphanumeric or special
character
in the center four
code
columns of the ASCII
table.
A space indicates no
volumes
restriction.
All
produced by IAS or RSX-11 have
a space in this position.

12-·37

Reserved

Spaces

I-·

(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

38-51

Owner
identification

The contents of this field are
system-dependent and are used
protection
for
volume
purposes.
See Section G. L 1.1
below.

52-79

Reserved

Spaces.

Label standard
version

CONTENTS

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

is the machine code and can be one of the following.
8 - PDP-8
A - DECsystem-10
B - PDP-11
F - PDP-15

The D%x characters provide an
identification method so that the
remaining data
in the owner identification field can be interpreted.
In the case of tapes produced on PDP-11 systems,
the
system
identification is D%B and the volume protection code and UIC are
interpreted as described below.
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
41
42
43
44

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

G-2

Z- , ... L . ~...L

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

One of the following access codes can be specified for each
position.
Code
0
1
2

3
4

character

Privilege
No access
Read only
Extend (append) access
Read/extend access
Total access

The UIC is specified in character positions 45 through 50.
The
first
3 characters are the group code in decimal.
The next 3 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 field.
indicates space)

Owner identifier - D%Bl410051102
1.

The file was created on a PDP-11.

System and group have read access.
Owner has total access.
All others are denied access.

The UIC is [051,102].

User Volume Labels

G.1.2

User volume labels are never written or passed back to the
present, they are skipped.

user.

File-Header Labels

G.1.3

The following
information
file-header labels.

should

kept

mind

when

creating

•

The Files-11 naming convention uses a
subset
(Radix-SO)
the available ANSI character set for file identifiers.

•

One character in the file
fixed by Files-11.

identifier,

the

(.),

•

A maximum of 13 of the 17 bytes in the
processed by Files-11.

file

identifier

are

•

It is strongly recommended
that all
file
identifiers be
limited
to
the Radix-50 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 nonDIGITAL systems,
the conventions listed above should be followed.
If they are
not, refer to Section G.1.3.1.

G-3

period

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

Tables G-2 and G-3 describe the HDRl and HDR2 labels respectively.
Table G-2
File-Header Label
CHARACTER
POSITION

FIELD NAME

(HDRl)

LENGTH
I
IN BYTES;

CONTENT

1-3

Label identifier

HDR

Label number

5-21

File

Any alphanumeric or
special
character
in the center four
columns of the ASCII
code
table.

22-27

File set
identifier

Volume identifier of the first
volume in the set of volumes.

28-31

File section
number

'l'h is
Numeric
characters.
is
field starts at 0001
and
each
increased
by
1
for
additional volume used by the
file.

32-35

File sequence
number

File number within the volume
set for
this
file.
This
number starts at 0001.

36-39

Generation number

Numeric characters.

40-41

Generation version

Numeric characters.

42.;...47

Creation date

_yyddd

48-53

Expiration date

Same format as creation date.

Accessibility

Space.

55-60

Block count

000000

61-73

System code

The three letters DEC followed
by name of
the system that
produced
the
volume.
see
Section G.1.1.1.

identifi~r

(_ indicates space)
or
t
00000 if no date.

Examples:

DECFILEllA
DECSYSTEMlO

Pad name with spaces.
74

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

Reserved

Spaces.

G-4

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

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
Table G-3
File Header Format (HDR2)
CHARl\CTER
POSITION FIELD NAME

LENGTH
IN BYTES

CONTENT

1-3

Label identifier

HDR

Label number

Record fe>rmat

F - fixed length
D - variable length
S - spanned
U - undefined

6-10

Block length

Numeric characters.

11-15

Record length

Numeric characters.

16-50

System-dependent
information

Positions 16 through 36 are
spaces.
Position 37 defines carriage
control and can contain one of
the following:
A -

first byte of record
contains FORTRAN control characters,

space - line feed/carriage return is to be inserted
between records,
M -

the record contains
all form-control information.

If DEC appears in positions 61
through 63 of HDRl, position
37 must be as specified above.
Positions
38
contain spaces.

53-BO

G.1~3.1

through

Buffer offset

00
on
Numeric characters.
tapes produced by Files-11.
input
to
Not supported on
Files-11.

Reserved

Spaces.

File Identifier Processing by Files-11 - The following
describe the processing of a file identifier by Files-11.

steps

SUPPORT OF ANSI MAGNEUC TAPE STANDARD
1.

The first 9 characters at a maximum are processed by an ASCII
'bo Radix-50 converter.
The conversion continues until one of
the following occurs:
A conversion failure,
9 characters are converted,
A period {.) is encountered.

If the period is encountered, the next 3 characters after the
period are converted and treated as the file type.
If a
failure occurs or all 9 characters are converted,
the next
character is examined for a period.
If it is a period, it is
skipped and the next 3 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.

changed

At file output, the file identifier is handled as follows.
1.

The filename is placed in the first
positions in the file
It is
identifier field.
It can occupy up to 9 positions.
followed by a period.

The file type of up to 3 characters is placed after
period.
The remaining spaces are padded with spaces.

the

The version number is
generation
version
following formulas.

and
the

then placed
in the generation
number fields
as described
in

generation number =(version # - 1 +
100

generation version # =(version # - 1)
Modulo 100
NOTE
In both calculations, remainders are ignored.

The following are examples.
FILES-11 VERSION #

GENERATION #

GENERATION VER #

50
100
101
1010

49
99

0
9

G-6

. ; an : sssa us: a

ma;:••

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

End-of-Volume Labels

G.1~4

End-of-volume labels are identical to the file-header labels with
following exceptions:
1.

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

File-Trailer Labels

End-of-file labels
(file-trailer
labels)
are
file-header labels, with the following exceptions:

with

identical

Columns J. through 4 contain EOFl and EOF2 instead of HDRl and
HDR2, respectively.

The block count contains the number of
file.

G.1.6

data

blocks

the

user.

User File Labels

User file labels are never written or passed back
present, they are skipped.

G.2

the

FILE STRUCTURES

The file structures illustrated below are the types of file and volume
combinations that the file processor produces.
Additional sequences
can be read and processed by the file processor.
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.
The meaning of graphics used in the file structure illustrations is as
follows.
1.

* indicates a tape mark,

BOT indicates beginning of tape,

EOT indicates end of tape,

, indicates the physical record delimiter.

G--7

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
G.2.1

Single File Single Volume

~l
I'
!

BOT,VOL1,HDR1,HDR2*---DATA---*EOF1,EOF2**

G.2.2

Single File Multivolume

BOT,VOL1,HDR1,HDR2*---DATA---*EOV1,EOV2**
BOT,VOL1,HDR1,HDR2*---DATA---*EOF1,EOF2**

G.2.3

Multifile Single Volume

BOT,VOL1,HDR1,HDR2*---DATA---*EOF1,EOF2*HDR1,HDR2*----DATA--*EOF1,EOF2**

G.2.4

Multifile Multivolume

BOT,VOLl,HDRl,HDR2*--DATA--*EOFl,EOF2*HDRl,HDR2*--DATA--*EOVl,EOV2**
BOT,VOL1,HDR1,HDR2*--DATA--*EOF1,EOF2*HDR1,HDR2*--DATA--*EOF1,EOF2**

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.

G-8

: : a o:••

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

H.MPOF

,,...

MAP OFFSET

IDENT OFFSET

Fl LE SEQUENCE NUMBER

H.FNUM

Fl LE SECTION NUMBER

H.FSEQ

STRUCTURE LEVEL= 401 (8)

H.FLEV

UIC (FOR VOLUME)
HEADER AREA

H.IDOF

H.FOWN=H.PROG

PROTECTION CODE (FOi~ VOLUME)

H.FPRO

H.UFAT

RECORD ATTRIBUTES

RECORD TYPE CODE

RECORD SIZE IN BYTES

N WORDS OF ZERO'S

IDENTIFICACATION AREA

MAP AREA

Figure G--1

(

Fl LE NAME RA.050

X+l.FNAM
(IDENT OFFSET *2)=X

Fl LE TYPE RAD50

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+50.

COPY OF THE HDR2 LABEL
(if byte 1 of label = 0,
label is not present)

X+130.

NULL MAP, I.E., ZERO'S
(10 BYTES LONG)

X+210.=
(MAP OF OFFSET 2)

ANSI Magnetic Tape File-Header Block (FCS Compatible}

G-9

SJ .

xu : a .

£&

aaaaau Lt:'"'

APPENDIX H

STATISTICS BLOCK

The format of the statistics block is shown in Figure H-1 below.
The
statistics block
is allocated manually in the user program as
described in Item 3.d of Section 3.1.2.

Word 0

HIGH LOGllCAL BLOCK NUMBER
(0 if file is noncontiguous)

Word 1

LOW LOGICAL BLOCK NUMBER
(O if file is noncontiguous)

Word 2

Word 3

Word 4

Figure H-1

SIZE (high)

SIZE (low)

LOCK COUNT

ACCESS COUNT

Statistics Block Format

H-1

APPENDIX I
ERROR CODES

This appendix lists the Directive Status Word error codes and the
error codes returned by the system.

·'-'.

I-1

I/O

ERROR CODES
.TITLE

QIOMAC • QIOSYM MACRO DEFINITIWN

DATE OF LAST MODIFICATIONS
C,A, D"t:LIA

***** ALWAYS UPDATE THE FOLLOwING TwO LINES TOGETHER
•I OE NT
/k1335/
QI.VER•0335

J
J
J

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A
SINGLE COMPUTER SYSTEM ANO MAY BE COPIED
ONLY WITH THE
J INCLUSION OF THE ABOVE COPYRIGHT NOTICE,
THIS SOFTWARE, OR
J ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDEO
OR OTHERWISE
J MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT ~OR USE ON SUCH
J SYSTEM ANO TO ONE WHO AGREES TO THESE LICENS~
TERMS, TITLE
J TO ANO OWNERSHIP OF THE SOFTWARE SHALL AT ALL
TIME$ REMAIN
J IN DEC.
J
I

,
, THE INFORMATION IN THIS DOCUMENT Is SUBJEc·r TO CHANGE WITHOUT
NOTICE ANO SHOULD NOT BE CONSTRUED AS A COMMITMENT
DIGITAL
, EWUIPMENT CORPORATION,
DEC ASSUMES NO REsPON5JBILITY FOR THE USE OR RELIABILITY OF
,, ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC,

J
J

PETER H, LIPMAN l•OCT•7l

' MACRO TO DEFINE STANDARD QUEUE I/O DIRECTIVE FUNCTION VALUES
ANO IOSB RETUHN VALUES, TO INVOKE AT ASSEMBLY TIME (WITH LOCAL
DEFINITION) USEa
,
J+

J
J
J

QlOSYS

JDEFINE SYMBOLS

, TU OBTAIN GLOBAL DEFINITION OF THESE SYMBOLS USEI
'
QIOsYS DEFSG
JSYMBOLs DEFINED GLOBALLY
THE MACRO CAN BE CALLEO ONCE ONLY AND THEN
' REDEFINES
ITSELF AS NULL,
,.

J
1

,MACRO
,IIF
,IF

QIOSYS SSSGBL 1 $SSMSG
IDN,cSSSGBL>,cDEFSG>,
ION,cSSSMSG>,cDEFSS>

,GLOBL

SSSMAX•0
SSMSG• 1
,IFF
SSMSG•0
.ENDC
,MCALL IOERRS
IOERRS SSSGBL
rI/O ERROR CODES FROM HANDLERS, FCP, FCS
,MCALL OR ERRS
DRERR$ SSSGBL
1DIRECTIVE STATUS WORD ERROR CODES
,IF
DIF,cSS!MSG>,<DEFSS>
FILIOS
1 MCALL
FILI OS USGBL
JDEFINE GENERAL I/0 'UNCTION CODES
,MCALL SPCIOS
SPCIOS SSSGBL
1DEVICE DEPENO~NT I/O FUNCTION CODES
.MACRO QIOSYS ARG,ARG1 1 ARG2
;RECLAIM MACRO STORAGE
,ENOM
QI OS VS
.ENDC
,ENOM
QI OS Y$

I-2

2 Si I I :S: :•

ERROR CODES
DtFINE THt ERROR CODES RETURNED BY DEVICE HANDL~R AND FILE PRIMITlV~S
IN THE FIRST WORD OF THE I/O STATUS BLOCK
THESE coo~s AHE ALSO RETURNED BY FILE CONTROL SERVICES CFCS) IN THE
BYTE F.ERR IN THE FILE DESCRIPTOR BLOCK (FOB)
THf BYTE F.ERR+l IS 0 IF F.ERR CONTAINS A HANDLE.R OR FCP ERROR CODE,
.MACRO
.MCALL

.IF
• I.

IOERR$ $$$GBL
,IOER,,DEFIN$
IDN,c$$$GBL>,<DEF$G>

CiiBL:a: 1

• I FF

,,.GBL::0
.ENOC

.IIF

NOF,$$MSG,$$MSG:v.

SYSTEM STANDARD CODES, USED BY EXECUTIVE AND DRIVERS

~·

.IOER,
.IOER,
,IOER,
,lOE.R,
.IOER,
.IOER,
.IOER,
.IOE.R.
.IOER,
1 IOER 1
,IOER,
IOER,
1

~IOER,

.IOER,
.IOER,
,IOER,
,IOER,
IOER,
.IOE.R,
.IDER,
,IOER.
.IOER,
,IDER,
.IOER,
.IDER,
,IOER,
.IOER,
,IOER,
1

IE.,BAD,•01.,<BAD PARAMETERS)
IE,IFC,•02,,<INVALID FUNCTION CODE>
IE,DNR,·~3,,<DEVICE NOT READY>
IE,VER 1 •H4,,<PARITY ERROR ON DtVICE>
IE,ONP,-~s.,cHARDWARE OPTION NOT PRESENT>
IE,SPC,•06,,<ILLEGAL USER BUFF~R>
IE,DNA,·~7.,<DEVICE NOT ATTACHtD>
IE,DAA,-~8.,cDEVICE ALREADY ATTACHED>
IE,OUN,-~q,,cDEVICE NOT ATTACHABLE>
IE,EOF,•10,,<END OF FILE DETECTED>
IE 1 EOV,•11,,cEND OF VOLUME DETtCTED>
IE,WLK,•12.,<WRITE ATTEMPTED TU LOCKED UNIT>
IE,OA0,•13,,cDATA OVERRUN>
IE,SRE,·1~.,<SENO/RECEIVE FAILURE>
IE,AB0,•1S,,<REQUEST TERMlNATEU>
IE,PR1 1 •1ba 1 <PRIVILEGE VIOLATIUN>
IE,RSU 1 •17, 1 <SHARABLE RESOURCE IN USE>
IE,OVR,•18,,<lLLEGAL OVERLAY R~QUEST>
IE 1 6YT,•1q,,cODD BYTE COUNT (OR VIRTUAL ADDRESS)>
IE,BLK,•20,,cLOGICAL BLOCK NUMBER TOO LARGE>
IE,MOD 1 •2t,,clNVALID UDC MODUL~ #>
IE,CON,•22, 1 <UDC CONNECT ERROR>
IE,BBE,•Sb.,<BAD BLOCK ON DEVICe>
IE,STK,-sa,,cNOT ENOUGH STACK SPACE CFCS OR FCP)>
IE,FHE. 1 •59,,<FATAL HARDWARE ERROR ON DEVICE>
IE,EOT,•02,,<END OF TAPE DETECTED>
IE,OFL,•bS,,<DEVICE OFF LINE>
IE,BCC 1 •6o,,c8LOCK CHECK, CRC, OR FRAMING ERROR>

I-3

ERROR CODES
FILE PRI~ITIVE. CODES
.IOER,
,IOER,
,IOER,
,IOER,
,IOER,
,IOER,
,IOER,
,IOER,
,IOER,
,IOER,
,IOER,
,IOER,
,IOE.R,
,IOER,
,IOER,
,IOER,
,IOER,
,IOER,
.IOER,
,IOER,
,IOER,
,IOE.R,
, IOER,
• IOER,

IE,N00,•23,,<CALLER'S NODES EXHAUSTED>
IE,OFU,•24,,cDEVICE FULL>
IE,IFU,•25,,<INDEX FILE FULL>
IE,NSF 1 •2b,,<N0 SUCH FILE>
IE,LCK 1 •27,,<LOCKEO FROM READ/~RITE ACCESS>
IE,HFU,•28,,<FlLE HEADER FULL~
IE,wAC,•29,,<ACCESSED FOR WRITE>
IE,CKS 1 ·3~.,cFILE HEADER CHECKSUM FAILURE>
IE,WAT 1 •31, 1 <ATTRIBUTE CONTROL LIST FORMAT ERROR>
IE,RER 1 •32, 1 <FILE PROCESSOR DEVICE READ ERROR>
IE,WER,•33,~<FILE PROCESSOR DEVICE WRITE ERROR>
IE,ALN,.34,,cFILE ALREADY ACCESSED ON LUN>
IE,SNC 1 •35, 1 <FILE IO, FILE NUM~ER CHECK>
IE,SQC,•J&,,cFILE IO, SEQUENCE NUMBER CHECK>
IE,NLN,•37,,cNO FILE ACCESSED UN LUN>
IE,CL0 1 •J8,,<~ILE WAS NOT PROP~RLY CLOSED>
IE,DUP 1 •57,,cENTER • DUPLICATE ENTRY IN DIRECTORY>
IE,BVR,•&3,,<BAO VERSION NUMBE~>
IE,BHD 1 •64 11 cBAD FILE HEADER>
IE,EXP 1 •75, 1 <FILE EXPIRATION DATE NOT REACHED>
IE,BTF,•7&.,<BAD TAPE FORMAT>
IE.ALC,-Aa,,cALLOCATION FAILURt>
IE,ULK 1 •65, 1 <UNLOCK ERROR>
IE,WCK 1 •8c, 1 <WRITE CHECK FAILURE>

FILE CONTROL SERVICES CODES
.IOE.R,
.IDER.
,lOER,
.IOER,
,IOER.
.IOER,
,IOER,
,IOER.
,IOE.R,

IE,NBF,.3~ 1 ,cOPEN • NO BUFFER SPACE
IE,RBG,·a~ 1 ,<ILLEGAL RECORD SIZE>

AVAILABLE FOR FILE>

.IOER.
,IOER,
.IOE.R,
,IOER,
,IDER,
.IOER,
,lOER,
.IOER,
,IOER,

IE,NBK,-a1,,cFILE EXCEEDS SPACE ALLOCATED, NO BLOCKS>
IE,ILL,-a2.,cILLEGAL OPERATION ON FILE DESCRIPTOR BLOCK>
IE,BTP 1•43,,<BAD RECORD TYPE>
IE,RAC,•44,,<ILLEGAL RECORD AC~ESS BITS SET>
IE,RAT,-as.,<ILLEGAL RECORD ATTRIBUTES BITS SET>
IE,RCN,-ac,,<ILLEGAL RECORD NU~BER • TOO LARGE>
IE,2Dv,-ae,,<RENAME • 2 DIFFERENT DEVICES>
IE,FEX,•49,,<RENAME • NEW FILE NAME ALREADY IN USE>
IE,BDR 1 •5~ 1 ,<BAD DIRECTORY FILt>
IE,RNM 1 •51, 1 <CAN'T RENAME OLD FILE SYSTEM>
IE,BDI,•52,,<BAD DIRECTORY SYNTAX>
IE,FOP,•53,,<FILE ALREADY OPEN>
IE,BNM,-sa,,<BAO FILE NAME>
IE,BOV,•SS,,<BAD DEVICE NAME>
IE,NFir•b0,,<FILE ID WAS NOT SPECIFIED>
IE~l5Q 1 •&1 1 ,clLLEGAL SEQUENTIAL OPERATION>
IE,NNC,-77,,cNOT ANSI •o• FORMAT BYTE COUNT>

,lOER.
.IOE.R,
,IOE.R,
,IOER,
,IOER,
.IOE.R,
,lOER,
,IOER,
,IOER,

IE,AST1•80,,<NO AST SPECIFIED l~ CONNtCT>
IE,NNN1•b8,,<NO SUCH NOOE>
lt,NFw,-bq,,cPATH LOST TO PART~ER> ,T~Is CODE MUST BE ODD
I~.BLB,•70,,<BAD LOGICAL BUFFE~>
IE,TM~,-11.,croo MANY OUTSTANDlNG MESSAGtS>
IE.NDR,•72.,<NO DYNAMIC SPACE AVAILABLE>
IE,CNR,•73,,<CONNECTION REJECTtD>
IE,T~0,•74,,<TI~EOUT ON REQUEST>
IE,NNL,•78,,<NOT A NETwORK LUN>

, I OE. R,

-· ~
.~

-~p

ICS/lCR ERROR CODES
,IOER,
.I OER •
,IOER.

IE,NLK,-7q,,crAsK NOT LI~KED TU sPECIFIED ICs/ICR INTERRUPTS>
IE,NST,•80,,<SPECIFIED TASK ~OT INSTALLED>
IE,FLN,•81,,<DEVICE OFFLINE wHtN OFFLINE REQUEST WAS ISSUED>

I-4

a a

ERROR CODES

nv ERROR coots
.IDER.
,IDER,

IE,IES,•82.,<INVALID ESCAPE SEQUENCE>
IE,PES,•83.,cPARTIAL ESCAPE SEQUENCE>

RECONFIGURATION CODES
,IOER,
.IOER,
F1 CL

IE,XCE,•47.,cINTERNAL CONSISTA~CY ERROR>
IE,ONL,•b7.,cDEVICE ONLINE>

ERROR CODES
.IOER,
,IOER,
.IOER.

IE,NTR 1 •87,,cTASK NOT TRIGGEREU>
IE,REJ,•88,,cTRANSFER REJECTED BY RECEIVING CPU>
IE.FLG,•89,,cEVENT FLAG ALREADY SPECIFIED>

SUCCESSFUL RETURN CODES•••
OE FINS
DE.FINS
DEF INS

IS 1 PN0,+01t1.
1s,suc,+~1.

IS,ROD,H12.

DEF IN$

IS,ElV,+05,

JOPERATION PEN~ING
JOPERATlON COMPLETE, SUCCESS
1CRX11) FL.OPPY DISK SUCCESSFUL COMPLETION
JOF A READ PHYSICAL, AND DELETED
JDATA MARK WAS SEEN IN SECTOR HEADER
J L.AST SECTOR,
J(PCL) SUCCESS~UL TRANSFER BUT MESSAGE
1TRUNCATED (RECEIVE BUFFER TOO SMALL.>.
J(A/D READ) AT LEAST ONE BAD VALUE
J~AS READ (REMAINDER MAY BE GOOD),
sBAO CHANNEL IS INDICATED BY A
JNEGATIVE VALU~ IN TH~ BUFFER,

TTY SUCCESS CODES
DEF IN$
DEF IN$
DEF IN!
DEFit><!
DEF IN$
DE FIN$
DEFIN$
OEFIN$

IS,CR,<15•400t1> JCA~RIAGE RETURN WAS TERMINATOR
IS.ESC,<33•400+1> JESCAPE CALTMoOE) WAS TERMINATOR
Is.cc,c3i1r400t1> JCONTROL•C wAS TERMINATOR
IS,ESQ 1 c233i1r400+1> JESCAPE SE~UENCE WAS TER~INATOR
IS.PES,<200i1r400+1> JPARTIAL ESCAPE SEQUENCE TERMINATOR
lS,EOT,<4*40~+1>
'EDT ~AS TERMINATOR (BLOCK MOOE INPUT)
IS,TAB1<11•4~~t1> JTAB ~AS tERMINATOR (FORMS MOOE INPUT)
IS.TM0,+2.
:REQUEST TIMED OUT

******
THE NEXT AVAILABLE ERROR NUMBER 151
AL~ LOWER NUMBERS ARE IN USE 11
*****

.IF

,MACRI)

,E.NDM
,ENDC
.ENDM

•Q0,

EQ,UMSG
IOERRS A
IOERRS

IOERRS

"'-"'
I-5

ERROR

DtFINE

TH~

CODJ~S

DIRECTIVE ERROR CODES RETURhED

THE DIRECTIVE STATUS WORD

FILE CONTROL SERVICES CFCs> RETURNS THtsE CODts IN THE 6YTE F,ERR
DESCRIPTOR BLOCK (FOB), TO DISTINGUISH THEM FROM THE
CODES FROM HANDLER AND FILE PRIMITIVES, THE BYTE
F,ERRtt IN THE FOB wILL BE NEGATIVE FOR A DI~ECTIVE ERROR CODE,
O~ THE FILE
O~ERLAPPING

,MACRO DRERR$ $$SGRL
,MCALL ,Ql0f,,DEFlN$
,IF
IDN,c$$$GBL>,<DEF$G>
,,,GBL.•1
,IFF
,,,GBL•0
,ENDC
,IIF
NDF,SSMSG,SSMSG•0
STANOARD ERROR CODES RETURNED BY DIRECTIVES lN THE DIRECTIVE STATUS WORD
,CllIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIDE,
,QIOE,

• Cil I DE,
,CllJOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,
,QIOE,

,QioE,
,CilIOE,
,CilIOE,

,QIOE,
,CilIOE,

,GIIOE,
,GIIOE,
,QIOE,

,QIOE,
,QIOE,

,GIIOE,
,QIOE,

DYNA~IC STORAGE>
TASK NOT INSTALLED>
IE,PTS,•H3,,cPARTITION TOO SMALL FOR TASK>
IE,UNS 1 ·~~.,cINSUFFICIENT DYNA~IC STORAGE FOR SEND>
IE,UPN,•~1,,<INSUFFICIENT

IE.INS,-~2.,csPECIFIED

IE,ULN,-~s.,cUN•ASSIGNED LU~)
IE.MWR,-~o,,cDEVICE HANDLER NOT

RESIDENT>
IE,ACT,•07,,cTASK NOT ACTIVE> .
IE.ITS,-~e.,cDIRECTIVE IhCONSISTENT WITH TASK STATE>
IE,Fix,-0q,,cTASK ALREADY FIXED/UNFIXED>
IE,CKP,·t~,,cISSUING TASK NOT CHECKPOINTABLE>
IE,TCH,•11 1 ,cTASK IS CMECKPUINTABLE>
IE,RBS,•15 1 ,cRECEIVE BUFFER IS TOO SMALL>
IE,PRI,•to,,cPRIVILEGE VIOLATION>
IE,RSU,•17,,cRESOURCE IN USE>
IE,NSW,•18 1 ,cNO SWAP SPACE AVAILABLE>
IE,ILV,•19,,<ILLEGAL VECTOR SPtCIFIED>

IE1AST1•80,,<DIRECTivE IssuED/NOT IssuED FROM Asr>
rE,MAP,•8l,,<ILLEGAL MAPPING SPECIFIED>
IE,IOP,•83,,<WINDOW MAS I/O IN PROGRESS>
IE,ALG,•84,,<ALIGNMENT ERROR>
IE,WOV,•85,,cADDRESS WINDOW AL~OCATION OVERFLO~>
IE,NVR 1•8o,,clNVALID REGION ID>
IE,NVW,•87,,cINVALID ADDRESS WINDOW ID>
IE,ITP 1•88,,<INVALlD TI PARAMETER>
IE,IBS,•89,,<INVALID SEND BUFFER SIZE
,GT, 255,)>
IE 1 LNL,.q0,,cLUN LOCKED IN USE>
IE,IUI,•q1,,<INVALID UIC>
IE,IOU,.q2 1 ,cINVALID DEVICE OR UNIT>
IE,ITI,•q3,,cINVALID TIME PARA~~TERS>
IE,PNS 1 ·q~ 1 ,cPARTITION/REGION ~OT IN SYSTEM>
IE,IPR,.qs.,cINVALID PRIORITY ( ,GT, zs~.)>
IE.ILU,•qo,,cINVALID LUN>
IE,IEF,-q7,,cINVALID EVENT FLA~ ( ,GT, o4,)>
IE.ADP,.qa.,cPART OF DPB OUT OF USER'S SPACE>
IE,SOP 1 •99,,<DIC OR DPB SIZE INVALID>

SUCCESS CODES FROM DIRECTIVES • PLACED IN
DEF INS

IS1CLR10

DEF IN$

IS,SET,2

DEF INS

IS,SPD,2

.IF
,MACRO
,ENOM
,ENOC

EQ,UMSG
ORE RFU A
DRE RR$

,END~

T~i~

~·.

DIRECTIVE STATUS WORD

:EVENT FLAG ~HIS CLEAR
JFROM CLEAR EV~NT FLAG DIRECTIVE
:EVENT FLAG WAS SET
JFRO~ SET EVENl
FLAG IJIRECTIVE
sTASK ~AS SUSPtNDED

OR ERRS

I-6

.,.I.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..,.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111111. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

ERROR CODES
D~FINE

THE GENERAL I/O FUNCTION CODES • DEVICE INDEPENDENT
.MACRO FIL.IO$ $$$GBL
.MCALL ,WORD,,0EFIN$
,IF
ION,<$$$GBL> 1 <0EF$G>
.,,GRL:st
• IFF
.,,GBL:r0

,E.NDC
GENERAL IIO QUALIFIER BYTE DEFINITIONS
,WORD,
,WORD,
,WORD,
,ViORO,

IQ,x,"1,iH,~J0'1

JQ,Q 1 002, ~HHI
JQ,5,l{J01J,00DI
IQ,UM0,1()~4,~04.'I

J~O ERROR RECOVERY
7QUEUE REQUEST IN EXPRESS QUEUE
JSYNONYM FOR IQ,U~D
JUSER MODE DIA~NOSTIC STATUS REQUIRED

EXPRESS QUEUE COMMANDS
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,

I01KIL.1012,~01l!

Io.RON, 022, (ihrn
IO,UNL.,042,0~0

IO,l.TK,050,00ei
IO,RTK,(21b0 1 000
IO,SET,030,~lirn

JKILl. CURRENT ~EQUEST
Jl/O RUNDOWN
;UNLOAD l/O HANDLER TASK
:LOAD A TASK IMAGE FILE
sRECORD A TASK IMAGE FILE
1SET CHARACTERISTICS FUNCTION

GENERAL DEVICE HANDLER CODES
,WORD,
,WORD,
,WORD,
,WORO,
,WORD,
,WORD,

.wORDt
,WORD,
,WORD,
FI~E

IO,wLB,0':10,01211
JO,Rl.8, 12100 1 1.rn2
10,Lov,010,002
10.sci:,0~H,01.rn

IO,ATT,01r10,0vi:5
IO,DET,000,004

IO,FNA,01l!0,0ll
ro,RNA,ri'J~0,013

IO,ENA,000 1 1314

JWRITE LOGICAL BLOCK
JRfAO LOGICAi. BLOCK
JLOAD OVERLAY CDISK DRIVER)
JSHAOOw COPY FUNCTION (DISKS ONLY)
;ATTACH A DEVICE TO A TASK
7DETACH A DEVICE FROM A TASK

JFIND FILE NAMt IN DIRECTORY
;REMOVE FILE NAME FROM DIRECTORY
1ENTER FILE NAME IN DIRECTORY

PRIMITIVE CODES
,WORD,
,WQRD,
,WORD,
,WORO,
,WORD,
,WORD,

• wo~w.

IO,CLN,000,007
I01ULl(10V110,012

IO,ACR,li:Hli.11015
IO,ACl~,ftHrn,01a
IO,ACE,~1,rn,011

IO,DAC,00t-"l,020
IO,RVB,000,1~21

,WORD,
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,

IO,WVB,i.?lvi0,'122

,MACRO
,ENDM
,ENDM

F"ILIO$
FILIOSi
FI LIO$

IO,EXT,0~1J,023

IO, CRE, liH10, 024

IO,DEL.,000,025
IO,RAT,000 1 026
IO,WAT,000,027
IO,APV,010,03~

IO,APC,0V!i,11,030

JCl.OSE OUT LUN
JUNL.OCK Bt,.OC.K
1ACCESS FOR READ
;ACCESS FOR WRITE
JACCESS FOR EXTEND
1DE•ACCESS FILt.
JREAD VIRITUAL 61.0CK
;WRITE VIRITUAL BLOCK
1EXTEND FILE
1CREATE FILE
JDELETE FILE
1READ FILE ATT~IBUTES
;WRITE FILE ATTRIBUTES
7PRIVILEGED ACP CONTROL
;ACP CONTROL.

DEFINE THE I/O FUNCTION CODES THAT ARE SPECIFIC TO INDIVIDUAL. DEVICES
.MACRO $PCIO$ $$$GBL
,MCALL ,WORD.,DEFIN$
.IF
IDN,c$$$GBL>,<DEF$G>
11 ,GBL.•1

.IFF

, , • GBL::a!l1

.ENDC

I-7

ERROR CODES
I/O F~NCTION CODES FOR SPECIFIC DEVICE DEPENDtNT FUNCTIONS

.woRD,

.WORD,

IO,wLv, lfll~,,~01
IO,WLS,01li 1 001

,WORD,
,WORD,
,WORD,
.woRD,
,WORD,
,WORD,

IO,WAL,01vl 1 0'11
10, w~s, 02,1, 1rn1
Io,cco,01.10,k1'111

.woRn,
wORD,
WQRD 1
• iri ORD,
.woRD.
1

IO,wNS,02t1,~'°"1

IO,wRT,1~""'001

IO.wLT,"10 1 0"'1
ID.wLC,i2!2V" 1 0'H
IO,WPB 1 0t.iltl 1 0M1
10,wDD, 1'lr;i,iJ111
I 0 • RL V, 1 v.1 ~J , I-' QI 2

JO I Rs T , 11 (1 1 ' ~ 0 2

.wo~o.

IO,RAL,01l-i 1 0Vl2

,wo~rn.

10,RNE,02i..~,0~2
0Ll~J, IJ02

,WORD,
,wORD,
.WORD,
,WORD,
,wORO,
,WORD,
.~ORD,

, WORD,
WORD,
,WORD,
,WORD,
.WORD,
,WORD,
,WORD,
1

.~OR0 1

WORD,
,WORD,
1 WORD 1
1 WORD,
1 WORD 1
.WORD,
•WORD,
,WORD,
,WORD,
,WORD,
1 WORD,
,WORD,
.WORD,
,WORD,
WORD,
,WORD,
1

.woRo,

IO, RNC,
IO,RTf'i 1 2vH1 1 iJ02
10,RDB, 2r;i0, ~02
IO,RMD,0111 1 "'02

IO,RNS,02t1,~02

IO,CRC,01.11.1,002
IO,RPB, 040 1 002
IO, RLC, 02"'' !.:Hl.12
I0 1 ATA,0rn,003
IO,GTS 1 000 1 iJ0S
IO • R 1C I 0 0 0 , 0 0 5
IO, INL, 00~, ~ms
IO, TRM, 01~, "'0S
IO,RWD,ei~~,005

ID,SPB, 020 1 005
IO,SPF,0t.IVl,005
IO,STC, 101t1 1 005
IO,St-40, 110, 11105
IO, SEC, 12vl, (!j05
IO,RWU,140 1 005
JO,SM0,1&0,005
I0 1 HNG,000,0r;,b
10,RBC, llH/10, 00b
IO,MOD,0171~,i1"'b

IO,HOX,ttH0 1 00b
IO,Fox,020,~~b

I0 1 SYN,0t.10,00b
IO,EOF,0~0,00&

IO,ERS,020 1 00&
ID,DSE,0t.10,"10b
IO,RTC,01!!0 1 007
10,SA0,0~\1,~10

,WORD,
,WORD,
• wQRD •
.WORD,

IO,SS0,01(1Yi 1 011
IO,RPR,00fc1,011

,WORD,
,WORD,
,WORD,
1 WORD,
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,
WORD,
1 WOR0 1
,WORD,
,WORD,
,WORD,
,WORD,
,WORD,

I0 1 Ml,.0,01-1V.J,01t.I
I0, 1..ED, 1110~, 024

.woRD.

I 0, t-45 0, N~IJ, 012

IO,RTT,"-'01 1 012
JO,SLO,~~n,013

IO,soo,1.inrn,02s
IO,SOI,00~,020

IO,SCS,kH"1 1 02b
IO,REL,~'1l0,027

IO,MCS,!cH11i:l 1 027
IO,ADS,000 1 030
10.ccr,0v.i0,ril30

JO,LOD,0e11,0:rn
IO,MDl,~l'lvJ,031

IO,DCl,01llk1 1 Ql31
IO, XMT, 0Vl0, 031
IO,XNA,01~ 1 031
IO,INI,~0111,031

I 0 , HI S , 0 It l1 , 0 3 2

IO,RCI 1 0L-JIJ1032
IO,RCV,0vH1 1 032
!O,CLK,0vrn,032

ID,CSR,00'1 1 [(!32

JCDECTAPE) WRITE L.OGICAL REVERSE
J(COMM 1 ) WRITE PRECEDED BY SYNC TRAIN
J(COMM,) WRITE, NO SYNC TRAIN
1CTTY) WRITE PASSING ALL CHARACTERS
rCTTV) WRITE SUPPRESSIBLE MESSAGE
J(TTY) ~RIT~ WITH CANCEL CONTROL•O
J(TTY) ~RITE WlTH BREAKTHROUGH
JCDISK) WRITE LAST TRACK
JCDISK) WRITE LOGICAL W/ wRITECHECK
sCDISK) WRITE PHYSICAL BLOCK
J(RXl1 DISK) WWITE PHYSICAL w/ DELETED DATA
J(MAGTAPE,OECTAPE) READ REVERSE
J(TTY) READ WITH SPECIAL TERM]NATOR
;(TTY) READ PASSING ALL CHARACTERS
rCTTY) READ WITHOUT ECHO
1CTTY) READ• NQ 1..0WE~ CASE CONVERT
1CTTY) READ WITH TIME OUT
;(CARD READER) READ BINARY MODE
J(COMM,) READ, STRIP SVNC
J(COMM,) READ, DON•T ST~IP SYNC
sCCOMM.) READ, DON•T CLtAR CRC
J(DISK) READ PHYSICAL BLOCK
J(DISK,MAGTAPE> READ LOGICAL W/ REAOCHECK
sCTTY) ATTACH ~ITH AST•s
J(TTY) GET TERMINAi.. SUPPORT CHARACTERISTICS
J(AFC,AD01 1 UDC) READ SINGLE CHANNEL
J(COMM,) INITIALIZATION FUNCTION
J(COMM,) TERMINATION ~UNCTIO~
J(MAGTAPE,DECTAPE) REWIND
J(MAGTAPE) SPACE "N" BLOCKS
J(MAGTAPE) SPACE "N" EO~ MARKS
JSET CHARACTERISTIC
J(FLOPPY DISK) SET MEDIA DENSITY
JSENSE CHARACT~RISTIC
J(MAGTAPE,DECTAPE) REWIND AND UNLOAD
J(MAGTAPE) MOUNT & SET CHARACTERISTICS
sCTTY) HANGUP OIAL•UP LlNE
sREAD MULTICHANNELS (SUFFER DEFINES CHANNELS)
J(COMM,) SETMOOE FUNCTION FAMILY
sCCOMM,) SET UNIT HALF DUPLEX
rCCOMM,) SET UNIT FULL DUPLEX
J(COMM,) SPECIFY SYNC CHARACTER
J(MAGTAPE) W~JTE EOF
J(MAGTAPE) E~ASE TAPE
rCMAGTAPE) DATA SECURITY ERASE
sREAD CHANNEL • TIME SASED
J(UOC) SINGLE CHANNEL. ANALOG OUTPUT
sCUDC) SINGLE SHOT, SlNGl..E POINT
rCTTY) READ WITH PROMPT
rCUDC) SINGLE SHOT, MULTI•POINT
rCTTY) READ WITH TERMINATOR TABLE
J(UOC) LATCHIN~, SINGLE POINT
J(UDC) l..ATCHING, MULTl•POINT
;CLPS11) WRITE 1..~D DISPLAY LIGHTS
sCLPS11) WRITE DIGITAL OUTPUT REGlSTER
J(LPS11) READ UIGITAL INPUT REGISTER
J(UDC) CONTACT SENSE, SINGLE POINT
J(LPS11) WRITE RELAY
J(UDC) CO~TACT SENSE, M~LTI•POINT
J(LPS11) SYNCHHONOUS AID SAMPLING
rCUOC) CONTACT INT• CONNECT
sCLPA11) LOAD MICROCODE
rCLPS11) SYNCHNONOUS DIGITAL INPUT
J(UDC) CONTACT INT • DISCONNECT
J(COMM,) TRANSMIT SPECIFIED BLOCK WITH ACK
J(COMM,) TRANS~IT WITHOUT ACK
1CLPA11) INITIALIZE
J(LPS11) SYNCHRONOUS HISTOGRAM SAMPLING
J(UDC) CONTACT INT •READ
;(COMM,) RECEIVE DATA IN BUFFER SPECIFIED
:(LPA11) START CLOCK
J(~US S~lTCH) ~EAD CSR REGISTER

I-8

....----~I~

·--,---r------------..---------·----~--------

ERROR CODES

"'-"

• WORID,
.wORID,
.wORID,

IO,M00,00'1 1 Vl3:5
IO,C'TI,000,0:n
IO,CON,kll00 1 033

.wORID,
.WORD,
.WORD,

IO,STA 1 i/11-;:t1,;:1,.n5
IO,DTI 1 01H3 1 L2l3'1

.WORD,
.wORD,

IO,MOA 1 !2!V.li..1,~3LI

IO,DIS,-0~H1dH4

,WORD,
.wORD,

IO,OPT 1 01I0 1 03LI
ID,RTI1l1HHJ1!.135
IO,CTL,001.1,035
IO,STP 1 01.1i.1 1 03S

.~ORD,

10,sw1,001&,03s

.~oRD,

Io,CNT1121"10 1 03b
IO,ITI,000,030

.~ORO,

.wORD,

J(LPS11) SYNCHMONOUS DIGITAL OUTPUT
J(UDC) TIMER •CONNECT
;CCOMM,) CONNECT fUNCTION
;CVT11) • CONNtCT TASK TO DISPLAY PROCESSOR
;(BUS SWITCH) CONNECT TO SPECIFIED ~us
J(LPA11) START DATA TMANSFER
;(UOC) TIMER • DISCONNECT
;(COM~,) DISCONNECT FUNCTION
;CVT11) •DISCONNECT TAS~ FROM DISPLAY PROCESSOR
;(BUS SWITCH) SwITCHED eus DISCONNECT
;CLPS1t) SYNCHkONOUS DIA OUTPUT
;(BUS SWITCH) UlSCONNtCT TO SPECIF PORT NO,
;CUDC) TIMER • READ
J(COMM,) NETwO~K CONTROL FUNCTION
;(LPS11 1 LPA11) STOP IN PROGRESS FUNCTION
;CVT11) • STOP DISPLAY PROCESSOR
J(BUS SWITCH) SwITCH ~USSES
tCVT11) • CoNTlNUE DISPLAY PRoCESSoR
J(UOC) TIMER • INITIALIZ~

CUMMUNICATION5 FUNCTIONS
.wORD,
.WORD,
.WORD.
.WORD,
.WORD,
.wORO,
.WORD,
,wORD,
,WORD,
,WORD,

.woRo,

,WORD,
,WORD,
,WORD,
.WORD,
• l>'IORD,
.WORD,

IO,CPR,010 1 033
IO,CAS,020,0H
IO,CRJ,040 1 033

10,ceo,110,ein
IO,CTR,210,033

IO,GNI,010,035
IO,GLI,020 1 035
l0,Gl.C,031ll,035

IO,GRI,0'1k1d'135
IO,GRC 1 0Slil,035
IO, GRN, li!lb0, 035
IO,CSM,070,035
IO,CIN, 100 1 12l3S
IO,SPW,110 1 035
IO,CPw,120,035
IO,Nl.B, 130 1 035
IO,OLB,140 1 035

1CONNECT NO TirEOUTS
1CONNECT WITH AST
;CONNECT REJECT
;BOOT CONNECT
sTRANSPARENT CUNNECT
1GET NODE INFORMATION
JGET LINK INFORMATION
1GET LINK INFO CLEAR COUNTERS
1GET REMOTE NODE INFORMATION
JGET REMOTE NOUE ERROR COUNTS
1GET REMOTE NODE NAME
;CHANGE SOLO MODE
JCHANGE CONNECTION INHIBIT
;SPECIFY NETWORK PASSWORD
rCHECK NETWORK PASSWORD,
,NSP L.OOPBACK
,OOCMP LOOPBACK

ItSIICR l/0 FUNCTIONS
,WORD,
.WORD,
,WORD,
.WORD,
1 WORD,
,WORD,
,WORD,
,WOF'10 1

,WORO,
•WORD,
.WORD,
,WORD,
,WORD,
,WORD,

IO,CTY,000 1 007
IO,DTY,000 1 015
IO,LOI,000,010
IO,UDI, 010, i/J23
IO,L.TI,000,1H7
IO,UTI,02121,023
IO,LTY,000,0UJ
IO,UTY,030 1 023
IO,l.KE,000 1 024
IO,UER,040 1 023
IO,NLK,000 1 023
IO,ONL,000,037
IO,Fl.N,000 1 025
IO,RAD 1 000 1 1d21

rCONNECT TO TERMINAL INTERRUPTS
JDISCONNECT FROM TERMINAL INTERRUPTS
JLINK TO DIGITAL INTERRUPTS
JUNLINK FROM DIGITAL INTERRUPTS
JLINK TO COUNTtR MODULE INTERRUPTS
JUNLINK FROM COUNTER MODULE INTERRUPTS
t~INK TO REMOT~ TERMINAL INTERRUPTS
JUNLINK FROM RtMOTE TERMINAL INTERRUPTS
JLINK TO ERROR INTERRUPTS
JUNLINK FROM ERROR INTERRUPTS
;UNLINK FROM ALL INTERRUPTS
JUNIT ONLIN!:
JUNIT OFFLINE
JREAD ACTIVATI~G DATA

IP11 I/0 FUNCTIONS
,WORD,
.WORD,
,WORD,
• WOIW,

,WORD,

.woRo,

• WQl~O,
.WORD,
.WORD,

IO,MA0,010,l~Hn

IOeLEI101~,1iH7

IO,RD0,12110,020
IO,RMT,020 1 020
IO,LSI 1 001il 1 i022
IO,UEI 1 050 1 i023
Io,USI,0&0 1 023
IO, CSI, 000, 02b
IO,os1,0~rn,~21

JMULTIPLE ANALOG OUTPUTS
JLINK EVENT FLAGS TO INTERRUPT
;READ DIGITAL DATA
;READ MAPPING TABLE
rLINK TO OSI I~TERRUPTS
JUNLINK EVENT fLAGS
JUNLINK FROM OSI INTERRUPTS
JCONNECT TO OSI INTERRUPTS
rDISCONNECT FROM OSI lNTERRUPTS

I-9

ERROR CODES
PCL11 I/O FUNCTIONS
.wORD,
.wOR0 1
.wORD,
.WORD,
.WORD,

, "'ACRO
• ENDM
• ENDt-1

IO,ATX,000 1 001

JO, ATF, 01iH:l 1 ~02
IO,CRX 1 0~HJ,031

IO,DRX,1210fl1 1 032
IO,RTF,00'1 1 033
SPCIOS
SPCIOS
SPCIOS

rATTEMPT TRANSMISSION
JACCEPT TRANSFtR
JCONNECT FOR RtCEPTlON
7DlSCONNECT FROM RECEPTION
sREJECT TRANSFER

DEFINE THE I/O CODfS FOR USER•MODf DIAGNOsirCs, ALL DIAGNOSTIC
FUNCTION ARE IMPLEMENTED AS A SUBFUNCTION OF-IIO co~E 10 (OCTAL),

.MACRO UMOIOS SUGBL
.MCALL ,WORD., DEF INS
.IF ION <SSSGBL>,<OEFSG>

,,,GBL•l
, •• C1BL•0

.IFF
.ENDC

DEFINE THE GENERAL USER•MODE I/0 QUALIFIER Blf,
.wORD,

IQ,UMD,0~u,000

rUSER MOOE DIAGNOSTIC REQUEST

OtFINE USER•MUDE DIAGNOSTIC FUNCTIONS,
.wORD,
.wORD,
,1tiORD,

.wmw,

.WORD,

,WORD,
.i.tiORO,

.wORD,
,WORD,
,WORD,
,WORD,
,WORD,
,wORD,

IO,HMS,000 1 010
IO,BLS,"'tv1,010
IO,OFF,020,01"1
IO,RDH,030 1 010
IO,wDH,040 1 010
IO,wCK 1 05H 1 ~10

JO,Rr>iF,060,1110
IO,RNR,070 1 11llll
IO,LPC,10~ 1 010

IO,RTD, 120 1 1H0
IO,WTD,130 1 010
IO, TDD, 1u0, 010
J0 1 DGN,150,lil10

,MACRO
.ENDM

UMOIOS

.END~

UMDIOS

;(DISK) HOME StEK OR RECALIBRATE
rCDISK) BLOCK SE~K
rCDISK) OFFSET POSITION
J(OISK) READ OlSK HEADER
J(DISK) WRITE DISK HEADER
J(DlSK) WRITEC~ECK (NON•TRANSFER)
J(DECTAPE) READ BLOCK NU~BER FORWARD
7(DECTAP~) READ BLOCK NUMBER REVERSE
J(MAGTAPE) READ LONGITUDINAL PARITY CHAR
J(DISK) READ T~ACK DESCRIPTOR
;CDISK) WRITE TRACK DtSCRIPTOR
J(DISK) WRITE TRACK DtSCRIPTOR DISPLACED
rDIAGNOSE MICRO PROCESSOR FIRMWARE

I-10

ERROR CODES
HANDLER ERROR CODfS RETURNED IN I/O STAl'US BLOCK ARE DEFINED THROUGH THIS
MACRO WHICH THEN CONDITIONAL~Y INVOKES THE MESSAGE GENERATING MACRO
FOR THE QIOSYM,MSG FILE
,MACRO

DEF INS

.IF
,MCALL
,IOMG,
,ENDC
.ENDM

,IOER, SYM,LO,MSG
SYM,LO
GT, UMSG
,IOMG,
SYM,l.O,cMSG>

110 ERROR CODES ARE DEFINED THOUGH THIS MACRU WHICH THEN INVOKES THE
EHROR MESSAGE GENERATING MACRO, ERROR CODES •129 THROUGH •25~
~RE USED IN THE QlOSYM,MSG FILE
,MACRO
DEF INS
,IF
,MCALL
,IOMG,
,!NOC
,ENDM

,QIOE,

SYM,l.0,MSG

SYM~LO

GT, UMSG
,IOMG,
SYMpcL0•128,> 1 cMSG>
,QIOE,

CONDITIONALLY GENERATE DATA FOR WRITING A MESSAGE FILE
,MACRO
,WORD
, ASC: IZ
,EVEN
, I IF

,ENDM

,IOMG, SYM,l.0,MSG
··O.cLO>
•MsG•

LT,•OcSSSMAX+cLO>>,SSSMAX•··OcLO>
,IOMG,

DEFINE THE SYMBOL svM WHERE LO Is Is THE LOW ORDER
,MACRO

DEF INS

,ENOM

,WORD,

SYM,LO,Hl

SYM,<HI*~00+l.0>

,WORD,

I-11

~YTE1

HI Is THE HIGH BYTE

~I
!

""'I
''I

APPENDIX J

FIELD SIZE SYMBOLS

Definitions for these symbols are contained in the System Library.

S. FA~rT

- size of FSR block-buff er header in bytes.
- size of FDB file-attribute area in bytes.

S.FDB

- size of FDB in bytes (including name block) •

S.FNAM

- size of filename in bytes (stored in RAD-50).

S.FNB

- size of filename block in bytes.

S.BFHD

S.FNBW - size of filename block in words.
S.FNTY

- size of filename and

file

type

words

(stored

RAD-50).

·'-".

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 filename in bytes -- file
type, and version.

J-1.

ID,

name,

. . . . .lllmll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .,. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..

APPENDIX K
RSX-llM/M-PLUS FCS LIBRARY SYSGEN OPTIONS

The system manager has the option of selecting one of several
FCS
libraries as the default FCS library. 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:
FCS Library Support

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 buffer" (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
buffer" support, and ANSI magtape support
in addition to the standard FCS routines

K-1

INDEX
Access methods, file, 1-2
ACTFIL command, task builder, 2-41
Allocation, file, 2-7, 2-8, 3-11
ANSI magtape data formats, 1-4, G-1
Append access, 2-14, 3-3, 3-17
ASCII/binary UIC conversion
routines,
.ASCPP, 4-7
.PPASC, 4-7
.ASCPP routine, 4-7
.ASLUN routine, 4-12
.Assembly-time FOB initialization
macros, 1-10, 2-3 to 2-21
AST service routine, 2-12, 2-45,
3-34
Asynchronous block I/O, 1-6,
1-11, 2-42, 3-34
Attribute section of FOB, file,
2-5 to 2-8

'-''

Big buff er (override block buffer
size) , 2-17, 2·-21, 2-39
Block access section of FDB, 2-1
to 2-3
Block buffer pool, 1-3, 2-38,
2-39
Block buffer section of FOB,
2-17 to 2-21
Block buffer size, override,
2-17, 2-21, 2-39
Block I/O operations, 1-6, 2-11,
2-23, 2-24, 3-6, 3-9, 3-30
to 3-38
Block number,
logical, 1-5, 5-1
virtual, 1-5, 1-6, 2-23, 2-24,
3-32, 4-19, 5-1
Block sizev non-standard, 2-17,
2-18
Bootstrap block, E-1
Buffer count, 2-18, 2-19
Buffer for block I/O, 2-11, 3-31

Command string interpreter
(CSI), 2-2, 6-1, 6-13 to
6-29
Contiguous file allocation, 2-6,
2-7
Continuation mechanism, 6-2, 6-7
Conversion routines, ASCII/
binary UIC,
. ASCPP, 4-6
.PPASC, 4-6
Count field, 1-6
Creating a new file, 3-4, 3-8
to 3-9
CSI, 2-2, 6-1, 6-13 to 6-29
CSI control block,
allocating, 6-14
bit values, 6-14
offsets, 6-14
CSI$ macro call, 6-14 to 6-17
CSI$1 macro call, 6-17 to 6-19
CSI$2 macro call, 6-19 to 6-21
CSI$ND macro call, 6-29
CSI$SV macro call, 6-26 to 6-29
CSI$SW macro call, 6-21 to 6-26
.CTRL routine, 4-24, 5-6 to 5-7

CALL macro, 4-1, 4-2
Calling file control routines,
4-1 to 4--2
Caret character, 1-6
CCML$ macro call, 6-12
Characteristics byte, device, 4-9
CLOSE$ macro call, 3-18
Closing a file, 3-18
Coding TPARS source programs, 7-1
Command line processing, 6-1

Index-1

Data formats, 1-5, 1-6
Data transfer modes, 1-6
Dataset descriptor, 1-9, 1-10,
2-14, 2-28 to 2-30, 3-4,
3-5, 3-15, 4-8 to 4-11
DECtape file structure, 5-1
Default buffer count, 2-20, 2-21
Default directory string routines,
. RDFDR, 4-2
.WDFDR, 4-3
Default file protection word
format, 4-4
Default file protection word
routines,
.RDFFP, 4-5
.WDFFP, 4-5
Default filename block, 1-10,
2-14, 2-28, 2-31 to 2-33,
3-4, 3-16, 4-8 to 4-11
Default UIC routines,
.RDFUI routine, 4-4
.WDFUI routine, 4-4
DELET$ macro call, 3-38
Deletion routines, file,
.DLFNB, 4-23 to 4-24
.MRKDL, 4-22, 4-23
Device buffer size word, 4-10
Device characteristics byte, 4-9
Device control routine, 4-24

.-...

INDEX

Device name field, 2-34, 4-8
Directive status word, 2-41, I-1
Directory entries, 5-2
Directory entry routines,
.ENTER, 4-15
.FIND, 4-13 to 4-15
.REMOV, 4-15
Directory files, 5-2
Directory identification
information, 4-10, 4-16
Directory string routines,
default,
. RDFDR, 4-2
.WDFDR, 4-3
Disk file structure, 5-1
$DSW, 2-43, I-1

.ENTER routine, 4-15
Error codes, I-1
Error conditions, 1-12
Error handling routines, 1-12,
3-2, 3-19, 3-23, 3-31
Event flags, 2-12, 2-17, 2-42,
2-43, 3-30
Extension, file, 2-7, 3-32, 4-20
.EXTND routine, 4-20
EXTSCT command, task builder, 2-41

FCS, 1-1
FCS library SYSGEN options, K-1
FCSBT$ macro call, 2-27
FDAT$A macro call, 2-5 to 2-8
FDB, 1-2, 1-9, 1-10, 2-3 to 2-33,
A-1
FDB bit values, 2-26, 2-27
FDB offsets, 2-26, 2-27, A-2
FDBDF$ macro call, 1-12, 2-4,
2-5, 2-17 to 2-21, 2-26
FDBK$A macro call, 2-11 to 2-13
FDOF$L macro call, 2-26, 2-27
FDOP$A macro call, 2-13 to 2-17
FDRC$A macro call, 2-8 to 2-10
Field size symbols, J-1
File access methods, 1-2
File allocation, 2-6, 2-7, 3-11
File attribute section of FDB,
2-5 to 2-8
File control routines, 4-1
File deletion routines,
.DLFNB, 4-23 to 4-24
.MRKDL, 4-22, 4-23
File descriptor block, 1-2, 1-9,
1-10, 2-3 to 2-33, A-1
File extension, 2-7, 3-35, 4-21
File header block, 3-4, 5-3 to
5-4, F-1

File identification field, 2-34,
3-4, 4-9, 4-12
File number, 5-2, 5-3
File open section of FDB,
2-13 to 2-17
File owner word format, 4-5
File owner word routines,
.RFOWN I 4-6
. WFOWN, 4-6
File pointer routines,
.MARK, 4-18, 4-17 to 4-18
~POINT, 2-9, 4-17 to 4-18
.POSIT, 4-19
.POSRC, 3-29, 4-18
File protection word format,
default, 4-4
File sequence number, 5-2, 5-3
File specification, 1-11
File specification in user
program, 2-27 to 2-33
File storage region, 1-3, 1-11,
2-18, 2-37 to 2-43
File structures, 5-1, G-6
File truncation, 2-10, 3-6, 3-9,
4-21
File truncation routine, 4-21
File type information, 4-10
File version number, 3-38, 4-10,
4-12, 4-14
File window, 2-15, 2-16
Filename block, 1-10, 2-34 to
2-36, 3-4, 3-14 to 3-16,
4-7 to 4-11, 4-15 to 4-17,
B-1
Filename block offset definitions,
B-1
Filename block routines,
.ASLUN, 4-11
.GTDID, 4-16
.GTDIR, 4-16
.PARSE, 2-32, 2-34, 2-35, 3-14,
3-15, 4-7 to 4-11, 4-10
. PRSDV, 4-11
.PRSDI, 4-12
.PRSFN, 4-12
Filename block size, 2-35, J-1
Filename block status word,
4-11, 4-13, B-2
Filename information, 4-10
FILES-11, 5-1
.FIND routine, 2-36, 4-13 to
4-16
FINIT$ macro call, 2-39 to 2-40,
4-7
Fixed length records, 1-5, 1-6,
2-5, 3-8, 3-27, 4-18
FSR, 1-3, 1-10, 2-17, 2-37 to
2-42
FSRSZ$ macro call, 2-37 to 2-40,
3-5

~
I

Index·-2

. . . . . . . ....,. .111111. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..

INDEX

GCML, 2-2, 6-1, 6-2 to 6-13
GCML control block,
allocating, 6-3
bit values, 6-5
offsets, 6-5
GCML$ macro call, 6-9 to 6-11
GCMLB$ macro call, 6-3 to 6-5
GCMLD$ macro call, 6-5 to 6-9
Get command line routine,
2-2, 6-1, 6-2 to 6-13
Get LUN Information system
directive, 2-18
GET$ macro call, 3-19 to 3-24
GET$R macro call, 3-22 to 3-23
GET$S macro call, 3-24
Global definitions for FDB
offsets, 2-25 to 2-26
GLUN$ directive, 4-9, C-1
.GTDID routine, 4-16, 4-17
.GTDIR routine, 4-16

Magnetic tapes,
accessing, 5-4
ANSI standard, G-1
examples of processing, 5-7
to 5-10
multiple file operations, 5-6
positioning, 2-14, 4-24, 5-5
processing, 5-4
rewinding, 4-24, 5-5
single-file operations, 5-5
Marking a file for deletion,
3-13
Master File Directory, 5-2
.MCALL directive, 2-2
MFD, 5-2
Modify access, 2-14, 3-3, 3-15
Move mode,
defined, 1-7
GET$ operations in, 3-18 to
3-20
PUT$ operations in, 3-24 to
3-27
specifying, 2-10, 3-6
.MRKDL routine, 3-12
Multiple buffer count, 2-18,
2-38, 2-39, 3-10
Multiple buffering, 1-8, 2-17,
2-38, 2-39, 3-10

Home block, E-2, E-3
Hyphen , 6--2

Index file, 5-2, E-1
Index file bit map, E-2
I/O-related system directives, C-1
I/O status block, 2~12, 2-44
to 2-45, 3-32, 3-33

Library, FCS SYSGEN option, K-1
Local definitions for FDB offsets,
2-25 to 2-26
Locate mode,
defined, 1-7
GET$ operations in, 3-19 to 3-22
.POINT routine and, 4-17
PUT$ operations in, 3-24 to
3-27, 4-18
specifying, 2-10, 3-6
Locked file, 2-15, 2-16
Logical block number, 1-5, 5-1
Logical record number, 1-5,
3-22, 3-28
Logical records, 1-1, 1-5,
3-18 to 3-28
Logical unit number, 2-13, 3-4,
3-5, 3-9
LUN, 2-13, 3-4, 3-5, 3-9

Index-3

New file, creating a, 3-4, 3-8
to 3-9
NMBLK$ macro call, 2-31 to 2-33,
3-16, 4-10, 4-17
Noncontiguous file allocation,
2-7
Non-sequenced variable length
records, 1-5
Nonstandard block size, 2-17 to
2-19

Offsets, symbolic, 2-4
OFID$x macro call, 2-36, 3-14
OFNB$ macro call, 2-36, 3-14
to 3-15, 4-17
OPEN$ macro call, 3-16, 3-17
OPEN$A macro call, 3-4
OPEN$M macro call, 3-4
OPEN$R macro call, 3-4
OPEN$U macro call, 3-4
OPEN$W macro call, 3-4
OPEN$x macro call, 1-7, 1-8,
2-34, 2-35, 3-2 to 3-11

INDEX
Opening a file, 3-2 to 3-11
Opening a file by file ID,
2-13, 2-33 to 2-35, 3-13
to 3-14_
Opening a file by filename
block, 3-14 to 3-16
OPNS$x macro call, 1-8, 3-12
OPNT$D macro call, 3-13
OPNT$W macro call, 3-12, 4-22
Optimizing file access, 2-33
to 2-36
Override block size, 2-17, 2-18,
3-10
Owner word format, file, 4-5

.PARSE routine, 2-32, 2-34, 2-36,
3-15, 4-8 to 4-11, 4-20
Physical record, 1-4
.POINT routine, 2-9, 4-17 to
4-18
.POSIT routine, 4-19
.POSRC routine, 3-29, 4-18
.PPASC routine, 4-7
.PRINT subroutine, 8-2
PRINT$ macro call, 8-1
Programs, sample, D-1
.PRSDV routine, 4-11
.PRSDI routine, 4-12
.PRSFN routine, 4-12
PSECTs generated by TPARS, 7-9
PUT$ ~aero call, 2-9~ 3-6, 3-9,
3-26 to 3-28
PUT$R macro call, 3-28 to 3-30
PUT$S macro call, 3-30

QIO, 2-42 to 2-44, 4-19
Queue I/O, 2-42 to 2-44, 4-19
Queue I/O function routine
(.XQIO), 4-19

Random access mode, 1-2, 1-5, 2-9,
3-6, 3-9, 3-22 to
3-23, 3-28 to 3-30, 4-17
RCML$ macro call, 6-11
.RDFDR routine, 4-2
.RDFFP routine, 4-5
.RDFUI routine, 4-4
Read access, 2-14, 3-3, 3-16
READ$ macro call, 1-5, 3-30 to
3-33
Read-ahead multiple buffering,
1-7, 2-19, 3-10
Reading a logical record, 3-20
to 3-24

Index-4

Reading a virtual block, 3-30
to 3-33
Record access section of FDB,
2-8 to 2-10
Record attributes, defining,
2-5 I 2-6 I 3-8
Record I/O operations, 1-5,
1-6, 2-8 to 2-10
Record number, logical, 1-5,
3-21, 3-27
Record size, defining, 2-6
Record types, defining, 2-5
Register usage, 1-10, 2-23
.REMOV routine, 4-15
.RENAM routine, 4-20
Rename file routine, 4-20
Retrieval pointers, 2-15, 2-16
Rewinding magnetic tape, 2-15
.RFOWN routine, 4-6
Run-time FDB initialization
macros, 2-21 to 2-25
Run-time macro calls, 1-10, 1-11

Sample programs, D-1
Sequence number, file, 5-2,
5-3
Sequenced variable length
records, 1-4, 2-5, 3-8
Sequential access mode, 1-2,
1-5, 2-9, 3-6, 3-9, 3-23,
3-24, 3-30
Shared file access, 1-7, 2-15,
3-11, 3-17
Spooling, 8-1
Spooling error handling, 8-2
Standard block size, 2-17,
2-18
State table initialization,
7-2
Statistics block, 3-11
Status word, directive, 2-42,
I-1
Status word, filename block,
4-11, 4-13, 4-15
Subexpressions for TPARS,
7-6
Symbols, field size, J-1
Synchronous record operations,
1-6, 1-10, 2-42 to 2-45
Syntax element definition, 7-2
SYSGEN options, FCS library, K-1

Table driven parser (TPARS), 7-1
Temporary file, 2-14, 3-12, 3-13,
3-17, 4-22
.TPARD, 7-6, 7-10

INDEX
TPl\RS, 7-1
built-in variables, 7-5
coding, 7·-1
command line syntax, 7-4
debug routine, 7-2, 7-6
examples, 7-12
generating a parser using, 7-10
invocation of, 7-10
subexpressions, 7-6, 7-7
TR.ll~N$ macro call, 7-3
Transition definition, 7-3
.TRNCL routine, 4-21
Truncation, file, 2-9, 3-6, 4-21

''-'

Version number, file, 3-38, 4-11,
4-13 I 4-15
Virtual block number, 1-4, 1-5,
2-23, 3-31, 3-34
4-19, 5-1
Virtual blocks, 1-4, 3-30 to
3-37·, 5-1

UFD I 3-4 I 5-·2
UIC conversion routines,
ASCII/binary,
.ASCPP, 4-7
.PPASC, 4-7
Unit number field, 2-32, 4-9
UNITS option, task builder, 2-13
Update access, 2-14, 3-3, 3-1
User File Directory, 3-4, 5-2
User file structure, 5-1
User record buffer, 2-10, 3-6 to
3-7, 3-9, 3-19~ 3-20, 3-25

Variable length records, 1-4, 1-5,
2-5, 3-8, 3-27, 3-28, 4-17
Variables, built-in for TP~RS,
7-5

Index-5

WAIT$ macro call, 3-30, 3-35
to 3-37
WAITFOR system directive, 3-34,
3-35
.WDFDR routine, 4-3
.WDFFP routine, 4-5
.WDFUI routine, 4-4
.WFOWN routine, 4-6
Wildcards, 4-13, 4-14, 4-15
Window, file, 2-15, 2-16
Write access, 2-14, 3-3, 3-16
WRITE$ macro call, 1-5, 3-34
to 3-35
Write-behind multiple buffering,
1-7 I 2-19 t 3-11
Writing a logical record, 3-24
to 3-30
Writing a virtual block, 3-34
to 3-35

.XQIO routine, 4-19

IAS/RSX-11
I/O Operations
Reference Manual
AA-25l5D-TC

READER'$ 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 •

c:
0

Did you find errors in this manual?
page number.

If so, specify the error and the

Please indicate the type of reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)

r=:J User with little programming experience
[] Student programmer
[] Other (please specify>~~~~~~~~~~~~~~~~~~~

Name
Organization
Street
City

--~~------------~----State _____________ Zip

Code __~---------

-1

Do Not Tear - Fold Here and Tape
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

RT/C SOFTWARE PUBLICATIONS TW/A14
DIGITAL EQUIPMENT CORPORATION
1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS

Do Not Tear - Fold Here

01876

I
I