AA 2515C TC RSX 11M 3.1 IO Operations Reference Manual Dec77

AA-2515C-TC_RSX-11M_3.1_IO_Operations_Reference_Manual_Dec77 AA-2515C-TC_RSX-11M_3.1_IO_Operations_Reference_Manual_Dec77

User Manual: manual pdf -FilePursuit

Open the PDF directly: View PDF .
Page Count: 259

Download
Open PDF In Browser	View PDF

IAS/RSX-11
I/O Operations
Reference Manual
Order No. AA-2515C-TC

lAS Version 2.0
RSX-11 M Version 3. 1
RSX-11 D Version 6.2

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment'Corporation, Maynard, Massachusetts 01754

digital equipment corporation · maynard, massachusetts

First Printing, December 1975
Revised:
December 1976
December 1977

The information in this document is ~ubject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may be used or copied only in accordance with the terms of such
license.
Digital Equipment Corporation assumes no responsibility for the use
or reliability of its software on equipment that is not supplied by
DIGITAL.

1975, 1976, 1977 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 p~e
paring future documentation.
The following are trademarks of Digital Equipment Corporation:

DIGITAL
DEC
PDP
DECUS
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM

DECsystem-lO
DEC tape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20

12/77-14

MASSBUS
OMNIBUS
OS/8
PHA

RSTS
RSX
TYPESET-8
TYPESET-IO
TYPESET-II

CONTENTS

Page
PREFACE
CHAPTER

CHAPTER

xi
1

FILE CONTROL SERVICES

1-1

1.1
1.2
1.3
1.3.1
1.4
1.5
1.6
1.6.1
1.6.2
1.7

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

1.8
1.9
1.10
1.11
1.12

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

PREPARING FOR I/O

2-1

2.1

.MCALL DIRECTIVE - LISTING NAMES OF REQUIRED
MACRO DEFINITIONS
FILE DESCRIPTOR BLOCK (FDB)
Assembly-Time FDB Initialization Macros
FDBDF$ - Allocate File Descriptor Block
(FDB)
FDAT$A - Initialize File Attribute Section
of FDB
FDRC$A - Initialize Record-Access Section
of FDB
FDBK$A - Initialize Block-Access Section
of FDB
FDOP$A - Initialize File-Open Section
of FDB
FDBF$A - Ini tia1ize B1ock-Bt~ffer Section
of FDB
Run-l'ime FDB Initialization Macros
Run-Time FDB Macro-Call Exceptions
Specifying the FDB Address in Run-Time
Macro Calls
GLOBAL VERSUS LOCAL DEFINITIONS FOR FDB
OFFSETS
Specifying Global Symbols in the Source
Coding
Defining FDB Offsets and Bit Values Locally
CREATING FILE SPECIFICATIONS WITHIN THE USER
PROGRAM
Data~et Descriptor

2.2
2.2.1
2.2.1.1
2.2.1.2
2.2.1.3
2.2.1.4
2.2.1.5
2.2.1.6
2.2.2
2.2.2.1
2.2.2.2
2.3
2.3.1
2.3.2
2.4
2.4.1

iii

1-8
1-8
1-9
1-10
1-10
1-11

2-2
2-3
2-3
2-4
2-5
2-8
2-10
2-12
2-16
2-19
2-20
2-22
2-23
2-24
2-24
2-25
2-26

CONTENTS (Cont.)

Page

2.8
2.8.1
2.8.2
2.8.3

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

2-39
2-39
2-40
2-41
2-42

FILE-PROCESSING MACRO CALLS

3-1

2.4.2
2.4.3
2.5

.,
~

•

."", •

..&.

2.5.2
2.6
2.6.1
2.6.2
2.7
2.7.1
2.7.2

CHAPTER

OPEN$x - GENERALIZED OPEN MACRO CALL
Format of Generalized OPEN$x Macro Call
FDB 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
OFNB$x OPEN FILE BY FILENAME BLOCK
3.6
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 RECO~D IN RANDOM MODE
3.11
GET$S - READ LOGICAL RECORD IN SEQUENTI~ MODE
3.12
PQT$ - WRITE LOGICAL RECORD
3.12.1
Format of PUT$ Macro Call
3.12.2
FDB 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
READ$ ... READ VIRTUAL BLOCK
3.15
3.15.1
Format of READ$ Macro Call
3.15.2
FDB Requirements for READ$ Macro Call
3.16
WRITE$ - WRITE VIRTUAL BLOCK
3.1
3.1.1
3.1.2

2-28
2-31
2-31
2-32
2-33
2-34
2-35
2 ... 37
2-38
2-38

3-2
3-5
3-8
3-11
3-12
3-13
3-13
3-14
3-15
3-15
3-16
3-17
3-17
3-18
3-18
3-20
3-20
3-20
3-21
3-22
3-23
3-23
3.,..24
3-25
3-25
3-26
3-28
3-28
3-29

3-31
3-31

CONTENTS (Cont.)

Page

CHAPTER

3.16.1
3.16.2
3.17
3.17.1
3.18
3.18.1

Format of WRITE$ Macro Call
FDB Requirements for WRITE$ Macro Call
WAIT$ - WAIT FOR BLOCK I/O COMPLETION
Format of WAIT$ Macro Call
DELET$ - DELETE SPECIFIED FILE
Format of DELET$ Macro Call

3.... 32
3-32
3-33
3-33
3-35
3-35

FILE CONTROL ROUTINES

4-1

4.1
4.2
4.2.1

CALLING FILE CONTROL ROUTINES
DEFAULT DIRECTORY-STRING ROUTINES
.RDFDR - Read $$FSR2 Default Directory
String Descriptor
.WDFDR - Write New $$FSR2 Default DirectoryString Descriptor
DEFAULT UIC ROUTINES
.RDFUI - Read Default UIC
.WDFUI - Write Default UIC
DEFAULT FILE-PROTECTION WORD ROUTINES
.RDFFP - Read $$FSR2 Default File Protedtion
Word
.WDFFP - Write New $$FSR2 Default FileProtection Word
FILE OWNER WORD ROUTINES
.RFOWN - Read $$FSR2 File-Owner Word
.WFOWN - Write New $$FSR2 File-Owner Word
ASCII/BINARY UIC CONVERSION ROUTINES
.ASCPP - Convert ASCII Directory String to
Equivalent Binary UIC
.PPASC - Convert UIC to ASCII Directory
String
FILENAME BLOCK ROUTINES
.PARSE - Fill in All Filename Information
Device and Unit Information
Directory-Identification Information
Filename, File-Type or Extension, and File
Version Information
Other Filename Block Information
.PRSDV - Fill in Device and Unit Information
Only
.ASLUN - Assign Logical Unit Number
DIRECTORY ENTRY ROUTINES
.FIND - Locate Directory Entry
.ENTER - Insert qirectory Entry
.REMOV - Delete Directory Entry
FILENAME BLOCK ROUTINES
.GTDIR - Insert Directory Information in
Filename Block
.GTDID - Insert Default Directory Information
in Filename Block
FILE POINTER ROUTINES
.POINT - Position File to Specified Byte
.POSRC - Position File to Specified Record
.MARK - Save Positional Context of File
.POSIT - Return positional Information for
Specified Record
QUEUE I/O FUNCTION ROUTINE (.XQIO)

4-1
4-2

4.2.2
4.3
4.3.1
4.3.2
4.4
4.4.1
4.4.2
4.5
4.5.1
4.5.2
4.6
4.6.1
4.6.2
4.7
4.7.1
4.7.1.1
4.7 .. 1.2
4.7 .. 1 .. 3
4.7.1.4
4.7.2
4.7.3
4.8
4.8.1
4.8.2
4.8.3
4.9
4.9.1

4.9.2
4.10
4.10•• 1
4.10.:2
4.10.3
4.10.4
4.11

4-2
4-3
4-3
4-4
4 .... 4
4 ... 4

4-5
4-5
4-5
4-6
4-6
4-6
4-6
4-6
4-7
4 .... 7
4 .... 8

4-9
4 .... 10
4-11

4-11
4-11
4-12
4-12
4 .... 14
4-14
4-14
4"",15
4 .... 15
4 .... 16
4 .... 16
4 .... 17
4-17

4-18
4-18

CONTENT S (Con t. )

Page
4.12
4.13
4.14

4-19
4-19
4-20

4.15.1
4.15.2
4.16

RENAME FILE ROUTINE (.RENAM)
FILE EXTENSION ROUTINE (.EXTND)
FILE TRUNCATION ROUTINE (.TRNCL)
FILE DELETION ROUTINES
.MRKDL - Mark Temporary File for Deletion
.DLFNB - Delete File by Filename Block
DEVICE CONTROL ROUTINE (.CTRL)

FILE STRUCTURES

5-1

4.15

CHAPTER

4-20

4-20
4-21
4-22

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

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

COMMAND-LINE PROCESSING

6-1

6.1
6.1.1

GET COMMAND LINE (GCML)
GCMLB$ - Allocate and Initialize GCML
Control Block
GCMLD$ - Define GCML Control Block Offsets
and Bit Values
GCML Run-Time Macro Calls
GCML$ - Get Command Line
RCML$ - Reset Indirect Command File Scan
CCML$ - Close Current Command File
GCML Usage Considerations
COMMAND STRING INTERPRETER (CSI)
CSI$ - Define CSI Control-Block Offsets
and Bit Values
CSI Control-Block Offset and Bit-Value
Definitions
CSI Run-Time Macro Calls
CSI$l - Command Syntax Analyzer
CSI$2 - Command Semantic Parser
CSI Switch Definition Macro Calls
CSI$SW - Create Switch Descriptor Table
Entry
CSI$SV - Create Switch-Value Descriptor
Table Entry
CSI$ND - Define End of Descriptor Table

6-2

6.1.2
6.1.3
6.1.3.1
6.1.3.2
6.1.3.3
6.1.4
6.2
6.2.1
6.2.2
6.2.3
6.2.3.1
6.2.3.2
6.2.4
6.2.4.1
6.2.4.2
6.2.4.3

5-8
5-8

5-9

6-3
6-5
6-9
6-9
6-11
6-12
6-12
6-13
6-14
6-14
6-17
6-17
6-19
6-21
6-21
6-26
6-28

CONTENTS (Cont.)

Page
CHAPTER

THE TABLE-DRIVEN PARSER (TPARS)

7-1

7.1

CODING TPARS SOURCE PROGRAMS
TPARS Macros: ISTAT$, STATE $ , and TRAN$
Initializing the State Table: the ISTAT$
Macro
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
Using Action Routines to Reject a Transition
TPARS SUbexpressions
GENERAL CODING CONSIDERATIONS
Suggested Arrangement of Syntax Types in a
State Table
Entering Special Charact'ers
Ignoring Blanks and Tabs in a Command Line
PSECTs GENERATED BY TPARS MACROS
INVOKING TPARS
Register Usage and Calling Conventions
Using the Options Word
Storage Requirements
HOW TO GENERATE A PARSER PROGRAM USING TPARS
PROGRAMMING EXAMPLES
Parsing a UFD Command Line
How to Use Subexpressions and Reject
Transitions
Using Subexpressions to Parse Complex
Grammars

7-1

7.1.1
7.1.1.1
7.1.1.2
7.1.1.3
7.1.2
7.1.3
7.1.3.1
7.1.3.2
7.1.3.3
7.1.4
7.2
7.2.1
7.2.2
7.2.3
7.3
7.4
7.4.1
7.4.2
7.4.3
7.5
7.6
7.6.1
7.6.2
7.6.3
CHAPTER

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

7-9
7-9
7-9
7-10
7-10
7-12
7-12
7-16
7-17

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

F-3

E.1
E.2
E.3

E.4
APPENDIX F
F.1

vii

CONTENTS (Cent.)

Page
IDENTIFICATION AREA
MAP AREA

F-4
F .... 5

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

G-l

VOLUME AND FILE LABELS
Volume Label Format
Contents of Owner Identification Field
User Volume Labels
File-Header Labels
File Identifier Processing by Files-II
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-l
G-l
G.... 2
G-3
G-3
G-5
G-6
G-7
G-7
G-7
G-7
G-7
G-8
G-8
G-8

APPENDIX H

STATISTICS BLOCK

H-l

APPENDIX I

ERROR CODES

I-I

APPENDIX J

FIELD SIZE SYMBOLS

J-l

F.2
F.3
APPENDIX G
G.l
G.l.l
G.l.l.l
G.l.2
G.l.3
G.l.3.l
G.l.4
G.l.5
G.l.6
G.2
G.2.l
G.2.2
G.2.3
G.2.4
G.3
G.4

G-8

Index-l

INDEX

FIGURES
FIGURE

1-1
1-2
1-3
5-1
5-2
6-1
6-2
6-3

7-1
7-2
B-1
G-l
H-l

File-Access Operations
Record I/O Operations
Single Buffering Versus Multiple Buffering
Directory Structure for Single-User Volumes
Directory 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 Centro 1 When TPARS Is Called from an
Executing User Program
Filename-Block Format
ANSI Magnetic Tape File-Header Block (FCS
Compatible)
Statistics Block Format

viii

1--2
1-4
1-8
5-2
5-3
6-2
6-25
6-28
7-11

7-12
B-2
G-9
H-l

CONTENTS (Cont.)

Page
TABLES
TABLE

2-1
3-1

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

Macro Calls Generating FDB Information
File Access Privileges Resulting from OPEN$x
Macro Call
R2 Control Bits for .EXTND Routine
FDB Offset Definitions
Filename-Block Offset Definitions
Filename-Block Status Word (N.STAT)
Summary of I/O-Related System Directives
Home-Block Format
File Header Block
Volume Label Format
File-Header Label (HDR1)
File Header Format (HDR2)

2-2

3-3
4-20
A-2
B-1
B-2
C-l
E-3
F-l
G-l
G-4
G-5

PREFACE

0.1

MANUAL OBJECTIVES AND READER ASSUMPTIONS

The purpose of this manual is to familiarize the users of an RSX-llD,
RSX-llM, or lAS operating system with the file control services (FCS)
facility provided with the system. Since the file control services
described herein pertain to both MACRO-II and FORTRAN programs, the
reader is assumed to be familiar with the manuals describing these
program-development tools. Also, since the development of programs in
an RSX-ll or lAS environment necessarily involves the use of the Task
Builder, the reader is likewise assumed to be familiar with this
system program. Unless otherwise noted, the term RSX-ll refers to
both RSX-llD and RSX-llM.

0.2

STRUCTURE OF THE DOCUMENT

Chapter 1 briefly describes the FCS features available for IAS/RSX-ll
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.
Chapter 5 describes the structure of files supported by the lAS and
RSX-ll systems.
In this context, the structure of files for disks,
DECtapes, and magnetic tapes are covered.

Chapter 6 describes two collections of object library routines called
the Get Command Line (GCML) routine and the Command String Interpreter
(CSI). These routines may be linked with the user task to perform
operations associated with the dynamic input of command lines. Such
input consists of file specifications that identify and control the
files to be processed by the user program.
Chapter 7 describes the 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
(FDB)
and the filename block,
respectively, two structures forming a significant part of the
descriptive material in Chapter 2. Appendix C summarizes a number of
I/O-related
system
directives that form a part of the total
resource-management capabilities of the RSX-II or the lAs Executive.
Through simplified sample pr~grams, 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.
Appendix E illustrates the structure of the index file of a Files-II
volume, while Appendix F describes in detail the format and content of
a file-header block. The format and content of magnetic tape labels
are similarly described in Appendix G. The format and content of the
statistics block are described in Appendix H.
The error codes returned by the system are listed in Appendix
field-size symbols are listed in Appendix J.

0.3

and

ASSOCIATED DOCUMENTS

Other manuals closely allied to the purposes of this document are
described
briefly
in
the
lAS,
RSX-IID, and RSX-IIM/RSX-IIS
Documentation Directories. The Documentation Directories define the
intended readership of each manual in the appropriate set and provide
a brief synopsis of each manual's contents.

xii

CHAPTER 1

FILE CONTROL SERVICES

lAS and RSX-ll 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 (lAS and RSX-IID)
or resident system library
(RSX-IIM);
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 logical 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

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

Figure 1-1

File-Access Operation

FCS provides an extensive set of macros to simplify the user's
interface to the system's I/O facilities.
These macros create and
maintain certain data structures that are required in performing all
file-I/O operations.
The required structures include the following:
1.

A file descriptor block (FOB)
that contains execution-time
information necessary for the processing of a file.

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

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

ASCII

The FOB is described in detail in Appendix A and Appendix B.
The
dataset descriptor and the default filename block are treated in
detail in Section 2.4.

1.1

FILE ACCESS METHODS

lAS and RSX-ll support both sequential and random access to data in
files.
The sequential-access method is device-independent, i.e.,
sequential acc~ss 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.

1-2

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:
$$FSRI - 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.1).
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
Fes in performing record I/O
operations.
Portions of this area are initialized at
task-build time,
and other portions are maintained by
Fes.
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 Fes serves as the user
interface to the FSR-block-buffer pool. All record I/O operations,
which are initiated through GET$ and PUT$ macro calls, are totally
synchronized by Fes.
Record I/O operations are described in detail in Section 1.5.

1-3

BLOCK
BUFFER
POOL

t"i
tz:I
(')

.......

DEVICE

FCS

USER
BECORD
BUFFER

~
~

t"i

,j:::.

til
tz:I

:g
H
(')

tz:I
til

$$FSR2
IMPURE DATA

Figure 1-2

Record I/O Operations

FILE CONTROL SERVICES
1.3

DATA FORMATS FOR FILE-STRUCTURED DEVICES

Data are transferred between peripheral devices and memory in blocks.
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

16
Byte Count

Sequence Number

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

single-word

16
Byte Count

Both fixed- and variable-length records are aligned on a word
boundary.
Any extra byte that results from an odd-length record is
(The extra byte is not necessarily a 0 byte.)
simply ignored.
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 to 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.

1-5

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 ("ft", 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
data, 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
completed.
When block I/O is used,
the number of the virtual block to be
processed is specified as a parameter in the appropriate READ$/WRITE$
macro call;
the virtual blocks so specified are processed directly in
a reserved buffer in user memory space. READ$ and WRITE$ can be used
only on block-structured devices.
As implied above, the user is responsible for synchronizing all block
I/O operations.
Such asynchronous operations may be coordinated
through an event ~lag
(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
each other.

1.5

RECORD I/O OPERATIONS

The GET$ and PUT$ macro calls
(see Sections
3.9
and
3.12,
respectively)
are provided for processing individual user records in
files.
Using the FSR block buffers (see Section 1.2), the GET$ and
PUT$ routines perform the necessary blocking and deblocking of records
within the virtual blocks of the file, allowing 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
mode 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-6

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

FILE CONTROL SERVICES
1.7

MULTIPLE BUFFERING FOR RECORD I/O (lAS AND RSX-IID ONLY)

By supporting multiple buffers for record I/O, FCS provides the
capability for lAS and RSX-IID 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

process record

write record

process record

write record

process record

write record
process record

process record
write record

write record
process record

I
i

Multiple
Buffer

Figure 1-3

1.S

Single Buffering Versus Multiple Buffering

SHARED ACCESS TO FILES

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

write (create) a new file.

M - Modify existing file without extending its length.
U - Update existing file and extend its length, if necessary.
A - Append data to end of existing file.
The suffix R applies to the reading of a file, whereas the suffixes W,
M, U, and A all apply to the writing of a file. These macro calls and
the shared-access conditions that they invoke are summarized below.
l-S

FILE CONTROL SERVICES
The OPNS$x and OPEN$x macro calls may be used as
access to files:

follows

for

shared

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

While FCS allows concurrent write-access requests through the
use of the OPNS$W, OPNS$M, OPNS$U, and OPNS$A macro, 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 active.
(The OPEN$R macro call does not permit
concurrent write access to the file while it is being read.)

Note from the above that readers of a shared file should be aware that
the file may yield inconsistent data from request to request if that
file is also being written.
Shared access during reading does not necessarily 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 (FOB)

The file descriptor block (FDB) 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-Buffer Section; and the
• Filename Block Portion of the FDB.
The information stored in the FDB depends upon the characteristics of
the file to be processed.
The FDB and the macro calls that cause
values to be stored in this structure are described in detail
in
Section 2.2.
Appendix A describes in detail the format and the
content of the FDB.

1-9

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 pes 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 10," 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 FOB.
Portions of the FOB are
user-defined and others are maintained by FCS. Assembly-time or
run-time macro calls are provided for user initialization o~ the
FOB.
The format and content of the FOB are detailed in Appendix
A.
FILENAME BLOCK -- The portion of the FOB that contains the various
elements of a file specification (i.e., directory, filename, 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
FOB
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 FOB 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-10

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 FDB has been saved, dataset-descriptor and/or
default-filename-block information must be provided to FCS before
the specified file can be opened.
DATASET-DESCRIPTOR POINTER -- An address value that points to the
6-word dataset descriptor within the user program. This address
value is stored in the FDB, allowing FCS to access a user-created
file specification in the dataset descriptor.
FILE SPECIFICATION -- Any system or user program having a requirement
to refer to files does so through a file specification. Such
information names a file and allows it to be
explicitly
referenced by any task. A file specification, whether for input
or output, contains specific information that must be made
available to FCS before that file can be opened. The term "file
specifier"
is sometimes
used
as
a
synonym
for
"file
specification."
FILE STORAGE REGION (FSR) -- The file storage region (see Section 1.2)
is an area of memory reserved by the user for use in record 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 RD.

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

1-11

return

FILE CONTROL SERVICES
3.

The FDBDF$ macro call (see Section 2.2.1.1)
is issued to
allocate space for an FOB.
Once the FOB is allocated,
necessary information can be placed in this data construct
through any logical combination of assembly-time and/or
run-time macro calls
(see Sections
2.2.1
and
2.2.2,
respectively) .
Certain information must be present in the
FOB before FCS can open and operate on a specified file.

For each assembly-time FDB initalization macro call,
a
corresponding run-time macro call is provided that supplies
identical information. Although both sets of macro calls
(see Table 2-1) place the same information in the FOB, each
set does so in a different way.
The assembly-time calls
generate .BYTE or .WORD directives that create specific data,
while the run-time calls generate MOV or MOVB instructions
that place desired information in the FOB during program
execution.

If an error condition is detected during 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 FOB offset location F.ERR.
If the address of a user-coded error-handling routine
is
specified as a parameter in any of the file-processing macro
calls, a JSR PC instruction to the error-handling routine is
generated.
The routine is then executed if the C-bit in the
Processor Status Word is set.

1-12

CHAPTER 2

PREPARING FOR I/O

The MACRO-II 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 if the
user
intends to employ record
I/O in processing files (see
Section 2.6).
(The initialization procedures for
FORTRAN
programs are described
in detail
in the FORTRAN-IV 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

OPENS (All Variations)
CLOSES
GET$ (All Variations)
PUT$ (All Variations)
READ$
WRITE$
DELET$
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.
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 (CSI), all the names of the associated
macros must also be listed as arguments in an
.MCALL
directive.
GCML and CSI, ordinarily
employed in system or application programs for
convenience
in
dynamically
processing
file
specifications, are described in detail in Chapter
6.
2-2

PREPARING FOR I/O
The .MCALL directive is described in detail in the IAS/RSX-ll MACRO-II
Reference Manual.
The sample programs in Appendix D also illustrate
the use of the .MCALL directive.
Note that these directives appear as
the first statements in the preparatory coding of these programs.
The object routines described in Chapter 4 should not be confused with
the macro definitions available from the system macro library.
The
file-control routines, constituting a body of object modules,
are
linked into 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

2.2

the

.MCALL

FDBDF$,FDAT$A,FDRC$A,FDOP$A,NMBLK$,FSRSZ$,FINIT$
OPEN$R,OPEN$W,GET$,PUT$,CLOSE$

FILE DESCRIPTOR BLOCK (FOB)

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

2.2.1

Assembly-Time 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 FOB.
Additional macro calls can then be
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:

pl,p2, ... ,pn

mcnam$A

represents the symbolic name of the macro.

pl,p2,
•.. ,pn

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:
FDOP$A

2,DSPT,DFNB

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

2"DFNB

2-3

PREPARING FOR I/O
Also, a trailing comma need not be inserted to
reflect the omission of a parameter beyond the
last explicit specification.
For example, the
macro call
FDOP$A

2,DSPT,DFNB

need not be specified as
FDOP$A

2,DSPT,

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

2,DSPT

If any parameter is not specified, i.e., if any field
in the macro
call contains a null specification, the corresponding cell in the FDB
is not initialized and thus remains O.
Multiple values may be specified in a parameter field of certain macro
calls.
Such values are indicated by placing an exclamation point (1)
between the values, indicating a logical OR operation to the MACRO-II
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 FDB, allowing
specific locations within the FDB to be referenced.
Thus,
the
programmer can reference or modify information within the FDB without
having to calculate word or byte offsets to specific locations.
Using such symbols in system/user software has the
additional
advantage of permitting the relative position of cells within the FDB
to be changed (in a subsequent release, for example) without affecting
the user's current programs or the coding style employed in developing
new programs.

2.2.1.1 FDBDF$ - Allocate File Descriptor Block
(FOB) The FDBDF$
macro call is specified in a MACRO-II 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:
label:
where:

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

2-4

PREPARING FOR I/O
The following examples are representative of
they might appear in a source program:

FDBDF$

macro

calls

FDBOUT: FDBDF$

iALLOCATES SPACE FOR AN FDB NAMED
i"FDBOUT II AND ESTABLISHES THE
iBEGINNING ADDRESS OF THE FDB.

FDBIN:

iALLOCATES SPACE FOR AN FDB NAMED
i"FDBIN" AND ESTABLISHES THE
iBEGINNING ADDRESS OF THE FDB.

FDBDF$

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

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.

2.2.1.2 FDAT$A - Initialize File Attribute Section of FDB 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 FDAT$A initialization macro is 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
where:

rtyp

rtyp,ratt,rsiz,cntg,aloc
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.
R.SEQ - Indicates sequenced records
written in creating the file.

are

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 character and followed by a
character when the record is written to a
carriage-control device, e.g., a line printer or a
terminal.

2-5

PREPARING FOR I/O
FO.BLK - Indicates that records are not allowed to
cross block boundaries.
These parameters initialize the record-attribute
byte
(offset location F.RATT)
in the FOB.
The
values FO.FTN and FO.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.,
FO.CR!FO.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 FOB
offset location F.RSIZ, need not be specified if
R.VAR has been specified as the record type
parameter above (for variable-length records).
If
R.VAR or R.SEQ is specified, FCS maintains a value
in FOB offset location F.RSIZ that defines the
size (in bytes) of the largest record currently
written to the file.
Thus, whenever an existing
file containing variable-length records is opened,
the value in F.RSIZ defines the size of the
largest record within that file.
By examining the
value in this cell,
a program can dynamically
allocate record buffers for its open files.

cntg

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.
Negative
Value - Indicates
that
the
two's
complement of the specified number of blocks is to
be allocated at file-create time, not necessarily
contiguously, and, further, that the file is to be
noncontiguous.
This parameter, which has 15 bits of magnitude
(plus a sign bit), initializes FOB offset location
F.CNTG.
If the user has a firm idea as to the desired
length of the file,
it is more efficient to
allocate the required number
of
blocks
at
file-create
time through this parameter, rather
than requiring FCS to extend the
file,
if
necessary,
during the writing of the file (see
aloc parameter below).
If this parameter is not specified, then the file
is created as an empty file, i.e., no space is
allocated within the file as it is created.

2-6

PREPARING FOR I/O
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 FOB is
to be re-used.
aloc

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

This parameter, which also has 15
bits
of
magnitude
(plus a sign bit),
initializes FOB
offset location
F.ALOC.
If
this
optional
parameter is not specified, file extension occurs
as follows:
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.

In lAS, RSX-llD, and RSX-llM,
the volume default extend size is
established through the INITIALIZE,
INITVOLUME, or MOUNT command
respectively. The volume default extend size cannot be established at
the FCS level;
this value must be established when the volume is
initially mounted.
The following statement is representative of an FDAT$A macro call.
This statement initializes the FOB 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 param€~ter string.
Also, the cntg and aloc 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 aloc 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.

2-7

PREPARING FOR I/O
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.FTN1FD.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 PUTS macro calls) are LO 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.
The FDRC$A macro call takes the following format:
FDRC$A
where:

racc,urba,urbs

racc

record I/O
specifies which variation of block or
is to be used to process the file.
This parameter
byte
(offset
initializes
the
record-access
location F.RACC)
in the FDB.
The first value
(READ$/WRITE$)
below applies only for block I/O
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 FDB.
Note also that the READ$ or
WRITE$
macro
call
allows
the
complete
specification of all the parameters required for
block I/O operations.
FD.RAN - Indicates that random-access mode
is to
be used in processing the file.
If this value is
not specified, sequential-access mode is used by
default.
Refer
to Section 1.5 for a description
of random-access mode.

2-8

PREPARING FOR I/O
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 called.
This
routine, which permits a limited degree of random
access to a file,
positions the file to
a
user-specified byte within a virtual block in
preparation for the PUT$ operation.
If FD.INS is not specified,
a PUT$ operation
within the file truncates the file at the point of
insertion, 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.

2-9

PREPARING FOR I/O
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 (racc) field,
multiple values must be separated by an exclamation point (1), 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.2.1.4 FDBK$A - Initialize Block-Access Section of FOB - 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 anyone 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 maximum block size that can
be specified through this parameter is equal to 64
virtual blocks, i.e., 32767(10) bytes.
2-10

PREPARING FOR I/O
bkvb

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/O-initiating READ$ and WRITE$ macro calls
(see
Sections 3.15 and 3.16, respectively).
This dummy parameter need be reflected as a null
specification
(with a comma)
in the parameter
string only in the event that
an
explicit
parameter follows.
This null specification is
required in order
to
maintain
the
proper
pO$itionality of any remaining field(s) in the
parameter string.

bkef

represents a numeric value that specifies an event
flag to be used during READ$/WRITE$ operations to
indicate the completion of a block I/O transfer.
This parameter initializes FDB 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.

bkst

described

represents the symbolic address of a 2-word I/O
status block in the user program.
If specified,
this optional parameter initializes FDB 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.
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.

2-11

block

PREPARING FOR I/O
bkdn

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

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

BKBUF,240.,,20.,ISTAT,ASTAOR

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 ISTAT
specifies the address of the I/O status block, and the symbol ASTAOR
specifies the entry-point address of the AST service routine.
2.2.1.5 FOOP$A - Initialize File-Open Section of FOB The FOOP$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 10." This process, which is an efficient method of opening a
file, is described in detail in Section 2.5.
The dspt and dfnb parameters represent address values which point to
user-defined data structures in the program. These data structures,
which are described in detail
in Section
2.4,
provide
file
specifications to the FCS file-processing routines.
The FOOP$A macro call takes the following form:
FOOP$A
where:

lun

lun,dspt,dfnb,facc,actl
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 FOB are done
through the specified logical unit number
(LUN).
Every active FOB must have a unique LUN.

2-12

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

facc

represents
any
one,
or
any
appropriate
combination, of the following symbolic values
be
indicating how the specified file is to
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.MFY - Indicates that an existing file is to
opened for modification.

2-13

file

PREPARING FOR I/O
FO.UPD - Indicates that an existing file is to
opened for update and, if necessary, extertded.

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.
FA.TMP - Indicates,
in combination with FO.WRT
above,
that the created file is to be a temporary
~~,

L~i~.

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

opened

The facc parameter initializes FDB offset location
F.FACC.
The symbolic values FO.xxx, described
above, represent the logical OR of bits in FDB
location F.FACC.
The information specified by this parameter can be
overridden by an OPENS 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 FDB
location F.ACTL:
1.

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.ENB is specified in combination
with any of the symbolic values described below,
FCS uses the information in F.ACTL.
FA.ENB 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.ENB.
FA. pas - 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

2-14

PREPARING FOR I/O
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 VOLI label for file creation. See Section
5.2.3.
FA.RWD - Is specified to cause a magnetic tape
be rewound when the file is opened or closed.
Examples of the use of FA.ENB with
FA.RWD are provided in Section 5.2.8.

FA.POS

to
and

FA.DLK - 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 system normally provides 7 retrieval pointers
automatically.
Retrieval pointers are used to
point to contiguous blocks of the file on disk.
Access to fragmented files may be optimized by
increasing the number of retrieval pointers, 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 locations F.DSPT and F.DFNB contain O.
In this
case, no file is currently associated with this FDB. Any attempt to
open a file with this FDB results in an open failure.
Either offset
location F.DSPT or F.DFNB must be initialized with an appropriate
address value before a file can be opened using this FDB. Normally,
these cells are initialized at assembly-time through the FDOP$A macro
call;
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

1"DFNB

FDOP$A

2,OFDSPT

FDOP$A

2,OFDSPT,DFNB

FDOP$A

1,CSIBLK+C.DSDS

FDOP$A

1"DFNB"FA.ENB!16.

call

might

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

2-15

PREPARING FOR I/O
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 FOB 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.
The last example illustrates the use of the parameter actl to increase
the number of retrieval pointers in the file window to 16. FA.ENB is
specified to cause the contents of F.ACTL, rather than the defaults,
to be used.
In all the examples above, the value specified as the first parameter
supplies the logical unit number to be used for all I/O operations
involving the associated file.

2.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 FOB
when record I/O operations (GET$ and PUTS macro calls) are to be used
for file processing. Initializing the FOB 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 FOB 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 is
specified only when a nonstandard block size is
desired.
The
numeric
value
so
specified
initializes FOB offset location F.OVBS.
An override block size is allowed only
for
record-oriented devices
(such as line printers)
and sequential devices
(such as magnetic tape
units) •
For block-oriented devices, the override
block size is ignored.
In lAS and RSX-IID,
for
spooled output to a record-oriented device, a
buffer less than 512(10) bytes in length must not
be allocated.

2-16

PREPARING FOR I/O
Issuing the CLOSES macro call
(see section 3.8)
resets offset location F.OVBS in the associated
FOB 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.
The standard block size in effect for a particular
device may be obtained through an I/O-related
system directive called Get
Lun
Information
(GLUN$). This directive is described in detail in
the Executive Reference Manual of
the
host
operating system.
The standard block size for a
device is established at system-generation time.
NOTE
For RSX-IIM, FCS uses single buffering and
simply
ignores
the multiple-buffering
parameters
(mbct
and
mbfg)
in
the
FOBK$A/FOBK$R macro call.
For lAS and
RSX-IIO,
resident
and
nonresident
libraries
support
the
multibuffered
version of FCS.
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 FOB offset
location F.MBCT.
If this value is greater than 1,
mUltiple buffering is effectively declared for
file processing.
In this case, FCS employs either
read-ahead or write-behind operations, depending
on which of two symbolic values is specified as
the mbfg parameter (see below) .
If the mbct parameter is specified as null or 0,
FCS uses the default buffer count contained in
symbolic location .MBFCT in $$FSR2
(the program
section in the FSR containing impure data). This
cell normally contains a default buffer count of
1.
If desired,
this value can be modified, as
noted in the discussion following
the
mbfg
parameter below.
If, in specifying the FSRSZ$ macro call
(see
Section 2.6.1),
sufficient memory space has not
been allocated to accommodate the number
of
buffers established by the mbct parameter, FCS
allocates as many buffers as can fit in the
available space.
Insufficient space for at least
one buffer causes FCS to return an error code to
FOB offset location F.ERR.
The user can initialize the buffer count in F.MBCT
through either the FOBF$A or the FOBF$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.

2-17

PREPARING FOR I/O
mbfg

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

For lAS and RSX-IlD, 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 .MBFeT 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 MACRO-II programs, use the EXTSCT Task Builder directive
(see Section 2.7.1) to allocate more space for the FSR block
buffers; for FORTRAN programs, use the ACTFIL Task Builder
directive
(see Section 2.7.2) to allocate more space for the
FSR block buffers.

Because the above 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 macro
call for the applicable FDB:
FDBF$A

,,1

2-18

PREPARING FOR 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 flag (efn)
and the override block
buffer size
(ovbs)
parameters are null;
these null values are used
for illustrative purposes only and should not be interpreted as
conditional
specifications
for
establishing
single-buffered
operations.
The following examples are representative of the FDBF$A macro call
it might appear in a program:
FDBF$A

25.,,1

FDBF$A

25.,,2,FD.RAH

FDBF$A

,,2,FD.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 count. The buffers so specified are to be used for read-ahead
operations, as indicated by the final parameter.
The last example allows event flag 32(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.2.2

Run-Time FDB 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:
FDAT$R

- Initializes or alters the file-attribute
the FOB.

section

FDRC$R

- Initializes or alters the
the FOB.

section

FDBK$R

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

FDOP$R

- Initializes or alters the file-open
FOB.

FDBF$R

- Initializes or alters the block-buffer section of the
FOB.

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

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

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 tnose 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
MACRO-II 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.

character

#FDBADR,#l,#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.

If the parameter is an address value or a literal value
that is to be placed in tqe 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 MACRO-II 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.,
RO), the parameter must not be preceded by the number
sign
(#).
Register specifiers are defined MACRO-II
symbols and are valid expressions in any context.

Thus, in contrast, parameters specified in assembly-time
macro calls are used as arguments in generating data in .WORD
or .BYTE directives f while parameters specified in run-time
macro calls are used as arguments 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.
2-20

PREPARING FOR I/O
This may be accomplished by issuing either the FDBK$R macro
call or the I/O-initiating READ$/WRITE$ macro call.
In all
three cases, the relevant field for defining the virtual
block number is the bkvb parameter. The READ$ and WRITE$
macro calls are described in detail in Sections 3.15 and
3.16, respectively.
At assembly-time, 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.
b.

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

VBNADR
#10400,VBNADR+2

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

#l,VBNADR
#10400,VBNADR+2

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

2-21

PREPARING FOR I/O
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
FDB 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 0 if 16 bits are sufficient to express
the desired virtual-block number.
The I/O-initiating
READ$/WRITE$ macro call may then be issued.
Should 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 FOB Address in Run-Time Macro Calls In
relation to Item 2 of the exceptions noted above, the address of the
FDB associated with the file to be processed corresponds to the
address value of the user-defined symbol appearing in the label field
of the FDBDF$ macro call (see Section 2.2.1.1).
For example, the
statement
FDBOUT: FDBDF$
in addition to allocating space for an FDB at assembly time, binds the
label FDBOUT to the beginning address of the FDB associated with this
file.
The address value so established can then be specified as the
initial parameter in a run-time macro call in anyone of three ways,
as follows:
1.

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

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

The argument FDBOUT is taken literally by FCS as the 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).
Therefor$, the user must exercise care in issuing subsequent
run-time macro calls to ensure that the present value of RO
is suitable to current purposes.

2-22

PREPARING FOR I/O
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:
FDAT$R

use

general

RO,#R.VAR,#FD.CR

In this case, the current contents of RO are taken by FCS as
the address of the appropriate 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:
FDAT$R

initial

,#R.VAR,#FD.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 I 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 MACRO-II handles
symbols.
Whenever a symbol appears
in
the
source
program,
MACRO-II
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
MACRO-II 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 FOB 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-23

PREPARING FOR I/O
2.3.1

Specifying Global Symbols in the Source Coding

Throughout the descriptions of the assembly-time macros (see Sections
2.2.1.2 through 2.2.1.6), global symbols are specified as parameters
in the macro calls. As noted earlier, such symbols ~re treated by
MACRO-II 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.3.2

Defining FDB Offsets and Bit Values Locally

The user who wishes to declare explicitly that all FDB 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, FDOF$L, causes the offsets
for FDBls to be defined within the user program. Similarly, bit
values for all FDB 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 FDOF$L and FCSBT$ macro calls
manner roughly equivalent to:

define

symbols

F.RTYP = xxxx
F.RACC = xxxx
F.RSIZ
xxxx
where xxxx represents the value assigned to the corresponding symbol.

2-24

PREPARING FOR I/O
In other
locally
absolute
symbols

words, the macros for defining FOB offsets and bit values
do not generate any code. Their function is simply to create
symbol definitions within the program at assembly-time.
The
so defined, however, appear in the MACRO-II symbol table,
~ather
than in the source-program listing.
Such local
symbol
definitions are thereby made available to MACRO-II during assembly,
rather than forcing them to be resolved by the Task Builder.
Whether or not the FDOF$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 FDOF$L macro call is issued, the NBOF$L macro
call for the local definition of the filename block need not be issued
(see Section 2.4.2). The FDOF$L macro call automatically defines all
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 ~he 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 "UFO" is synonymous with the term
"file directory string" appearing throughout this manual.

A filename;

A file type (RSX-l1) or file extension (lAS);

A file version number.

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

synonym

for

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

"file
is

The dataset descriptor.
This tabular structure may be
created and initialized manually through the use of .WORD
directives. 'Section 2.4.1 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.

2-25

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

2.4.1

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
course of program execution.
In creating this structure, anyone 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
apd/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:
DEVICE-NAME STRING DESCRIPTOR

2-26

string~

following

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

DIRECTORY STRING DESCRIPTOR
Word 3 -

Contains the length
file-directory string.

(in

bytes)

the

ASCII

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

/[200,200]/

DIRNM: .ASCII

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

FILENAME STRING DESCRIPTOR
Word 5 -

Contains the length
filename string.

(in

bytes)

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
separated by a dot (.), and the file version
number
must be preceded by a semicolon.
A
filename string may be created as shown below:
FILNM: .ASCII

/PROGl.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 0 in Word 1, 3, or 5 of the dataset
descriptor indicates that the corresponding device-name, directory, or
filename string is not present in the user program. For example, the
coding below creates a dataset descriptor containing only a 2-word
ASCII filename string descriptor:

2-27

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

OFDSPT: .WORD
• WORD
. WORD

0,0
0,0
ONAMSZ,ONAM

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

ONAM:
.ASCII
ONAMSZ=.-ONAM

/OUTPUT.DAT/

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

Note first that an FOB 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 FOB offset
location F.DSPT.
This value enables the .PARSE routine (see Section
4.7.1) to access the fields of the dataset descriptor in building the
filename block.
The symbol OFDSPT also appears in the label field of the first . WORD
directive, defining the address of the dataset descriptor for the
.PARSE routine. The .WORD directives each allocate 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.4.2

the

Default Filename Bloak - 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 NMSLK$ macro call may be issued in connection
with each FOB 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.

2-28

PREPARING FOR I/O
Note in the parameter descriptions below that symbols of the form
N.xxxx are used to represent the offset locations within the filename
block. These symbols are differentiated from those that apply to the
other sections of the FOB by the beginning character N. All versions
of the generalized OPEN$x macro call (see Section 3.1) use these
symbols to identify offsets in storing file information in the
filename block.
The NMBLK$ macro call is specified in the following format:
label:
where:

NMBLK$

fnam,ftyp,fver,dvnm,unit

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 FOB
offset location F.DFNB to be initialized with the
address of the default filename block.

fnam

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

ftyp

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-50
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 of 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 filena~e block.

Only the characters A through Z and a through 9 may be used
composing the filename and file type strings discussed above.

Although the file version number and the unit number discussed above
are binary values, these numbers are normally represented in octal
form when printed, when input via a command string, or when supplied
through a dataset-descriptor string.
As evident from the foregoing, all the default information supplied in
the NMBLK$ macro call is stored in the default filename block at
offset locations that correspond to identical fields in the filename
block within the 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:
2-29

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

FDBDF$
FDRC$A
FDOP$A
NMBLK$
NMBLK$

user

the

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

iALLOCATES SPACE FOR AN FOB.
iINITIALIZES FILE-ATTRIBUTE SECTION.
iINITIALIZES RECORD-ACCESS SECTION.
iINITIALIZES FILE-OPEN SECTION.

,RECBUF,80.
INLUN"IFNAM

iALLOCATES SPACE FOR AN FOB.
iINITIALIZES RECORD-ATTRIBUTE SECTION.
iINITIALIZES FILE-OPEN SECTION.

OUTPUT ,OAT
iESTABLISHES FILENAME AND FILE TYPE.
INPUT,DAT"DT,l iESTABLISHES FILENAME, FILE TYPE,
iDEVICE 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 FOB
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 FOB.
The
accompanying parameters in the first NMBLK$ macro call define the
filename and the file type, respectively, of the file to be openedi
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 parameter (the file version number)
is null, as
reflected by the extra comma. This null specification indicates that
the latest version of the file is desired. All other parameter fields
contain explicit declarations defining default information for the
applicable FOB.
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 filename-block offsets locally, presumably to conserve
symbol-table space at task-build time. The NBOF$L macro call need not
be issued if the FDOF$L macro call has been invoked, since the
filename block offsets are defined locally as an automatic result of
issuing the FDOF$L macro call.

2-30

PREPARING FOR I/O
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-50 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
"opening a file by file ID". This type of open requires a minimum of
system overhead, resulting in a significant increase in the speed of
preparing a file for access by 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.
To open a file by file ID, the mlnlmum information that must· be
present in the filename block of the associated FDB consists of ' the
following:
1.

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

Device-Name Field.
This I-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.

2-31

PREPARING FOR I/O
3.

Unit-Number Field.
This I-word
offset location 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 FDB 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 FDB at the desired point in program flow for use in reopening
that same file.
The option to reopen files in this manner stems from the fact that FCS
is sensitive to the presence of any nonzero value in the first word of
the file identification field of the filename block. When the OPEN$x
function is invoked, FCS first examines offset location N.FID of the
filename block. If the first word of this field contains a value
other than 0, 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 proces~ should, in general, proceed as
outlined below:

2-32

PREPARING FOR I/O
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 CLOSES 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 anyone 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, CLOSES, 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.5.2

Manually Initializing the Filename Block

In addition to saving and restoring the filename block in anticipation
of reopening a file by file ID, the filenam~ block can also be
initialized manually. If the user chooses to do so, the • PARSE and
.FIND routines (see Sections 4.7.1 and 4.8.1, respectively) may be
invoked at appropriate points to build the required fields of the
filename block.
After the .PARSE and .FIND logic is completed, all
the information required for opening the file exists within the
filename block.
When anyone 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

2-33

PREPARING FOR I/O
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.
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 0, 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-identification field
(N.FID)
of the
filename block.
This action prevents the field (which pertains to a
previous operation)
from being used mistakenly to open a file for a
current operation. Thus, if a user later intends to open a file by
file ID using information presently in the filename block, the entire
filename block (not just N.FID) must be saved before closing the file.
Then, at the appropriate point in program flow, the filename block may
be restored to open the desired file by file ID.

2.6

INITIALIZING THE FILE STORAGE REGION

The file storage region (FSR) is an area allocated in the user program
as
a
buffer
pool
to accommodate the program's block-buffer
requirements in performing record I/O
(GET$ and PUT$)
operations.
Although the FSR is not applicable to block I/O (READ$ and WRITE$)
operations, 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-34

initialization

the

FSR

are

PREPARING FOR I/O
2.6.1

FSRSZ$ - Initialize FSR at Assembly-Time

The MACRO-II programmer establishes the size of
the
FSR
at
assembly-time by lssulng 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 $$FSRI. 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

fbufs

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 0 indicates that
an unspecified number of files may be open
simultaneously for block I/O process{ng.
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 0 as an argument, as shown below:
FSRSZ$

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

If record I/O, using a single buffer for each
file,
is to be done, fbufs represents the
maximum number of files that can be open
simultaneously for record I/O processing. For
example, an RSX-llM user might want to access
simultaneously three files for block I/O and
two files for record I/O.
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

2-35

PREPARING FOR I/O
3.

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-IID or lAS
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 total
block-buffer-pool
space (in bytes) needed to
support the maximum number of files that can be
open simultaneously for record I/O.
If this
parameter is omitted, Fes
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.

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.
Standard block sizes for devices are established
at system-generation time.

mbcl,
rnbc2,
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-IIM users must
use multiple buffer counts equal to 1.

2-36

PREPARING FOR I/O
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 lAS 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
pr inter) .
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 MACRO-II
program to call initialization coding to set up the FSR.
This macro
call takes the following format:
label:
where:

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.

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

;IMPLICITLY INITIALIZES THE FSR
iAND OPENS THE FILE.

#FDBIN

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.

2-37

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

iEXPLICITLY INITIALIZES THE FSR AND
iOPENS THE FILE.

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

2.7

INCREASING THE SIZE OF THE FILE STORAGE REGION

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

2.7.1

FSR-Extension Procedures for MACRO-II Programs

To increase the size of the FSR for a MACRO-II program, the
two options:

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.

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

(S.BFHD*fbufs)+bufsiz

length

fbufs*(S.BFHD+SI2.)

where:

S.BFHD

either

the

formulas

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

PREPARING FOR I/O
fbufs

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

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

512.

is the standard default buffer size.

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

2.7.2

the

Task

Builder

FSR-Extension Procedures for FORTRAN Programs

For a FORTRAN program, if an explicit ACTFIL statement is not issued
in the optional keyword input to the Task Builder, an ACTFIL statement
with a default value of 4 is generated
automatically
during
task-build.
To extend the size of the FSR at task-build time, the
user may issue the following command:
ACTFIL = files
where:

files

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

This command, similar to the EXTSCT command above, causes program
section $$FSRI 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 lAS or RSX-ll, the
default value for the ACTFIL command is 4. Thus, if 0, 1, 2, or 3 is
specified
as
the "files" parameter, the size of $$FSRI
(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-ll 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 anyone 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 the system I/O drivers at the device level.
Device drivers are
included for all the standard I/O devices supported by lAS and RSX-ll
systems. Although transparent to the user, the QUEUE I/O directive is
used for all FCSfile-access operations.
2-39

PREPARING FOR I/O
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 Fes 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 Fes allows the
user to synchronize all block I/O activities, thus enabling the user
to satisfy logical processing dependencies within the program.

2.8.1

Event Flags

I/O operations proceed concurrently with other system activity. After
an I/O request has been queued, the system does not force an implied
wait for the issuing task until the requested operation is completed.
Rather, the operation proceeds in parallel with the execution of the
issuing task, and it is the task's responsibility to synchronize the
execution of I/O requests.
Tasks use event flags in synchronizing
these activities. with respect to event flags, the system merely
executes primitive operations that manipulate, test, and/or wait for
these indicators of internal task activity.
The completion of an I/O transfer, for example, is recognized by the
system as a significant event. If 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 1 through
32(10) may be defined for local use by the task. If the user has not
specified an event flag; Fes 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 Fes
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,
respectively) •

2-40

PREPARING FOR I/O
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.
Through 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/RSX-llD Device Handlers Reference Manual and the RSX-llM 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.8.2

I/O
the
may
The
the

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 ~ord 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 actu~lly 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.

2-41

PREPARING FOR I/O
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 d~termine
the status of any given block I/O transfer. The binary values of
these status codes always have the following significance:
Code Value

Meaning

I/O transfer completed.

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

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

may
any

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

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 as an integral function of issuing
the desired I/O request.

2.8.3

AST Service Routine

An asynchronous system trap (AST) is a software-generated interrupt
that causes the sequence of instructions currently being executed to
be interrupted and control to be transferred to another instruction
sequence elsewhere in the program.
If desired, 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.
2-42

PREPARING FOR I/O
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/O 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 WAIT$ macro call (see Section 3.17)
may also be issued in connection with a READ$ or WRITE$ operation to
suspend task execution until a specified event flag is set to indicate
the completion of block I/O.
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-43

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

- To open and prepare a file for processing;

OPNS$

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

OPNT$

- To create and open a temporary file for processing;

OFID$

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

OFNB$

- To open a file
filename block;

CLOSES

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

PUTS

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

file

requested

the

random

block

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

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 anyone of the following alphabetic suffixes, each of
which denotes a specific type of processing anticipated for the file:
R

- Read an existing file;

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

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

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

3-2

FILE-PROCESSING MACRO CALLS
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
(facc)
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 mayor 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 privileges 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
F.OSPT.
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. 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, anyone 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

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 FOB 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,
FOB
offset location F.RACC must be
initialized with the FO.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.1

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 Command String Interpreter
(CSI)
is
being
used
to
interpret command lines
dynamically, this parameter is used to specify the
address of the dataset descriptor within the CSI
control block
(see offset location C.DSDS in
Section 6.2.2).
racc

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:
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 -~e 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 PUTS
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 PUTS
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
PUTS operation in the file, without exception,
does not truncate the file.
If the record-access byte in the FDB has already
been
initialized
through
the
corresponding
parameters of the FDRC$A or the FDRC$R macro call,
the racc parameters need not be present in the
OPEN$x macro call.

urba

represents the symbolic address of the user record
buffer.
This parameter initializes FDB offset
location F.URBD+2.

3-6

FILE-PROCESSING MACRO CALLS
If the user-record-buffer address has already been
supplied to the FDB through the corresponding
parameter of the FDRC$A or the FDRC$R macro call,
this parameter need not be present in the OPEN$x
macro call.
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
call.

macro

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

might

OPEN$M

example,

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

Note in this macro call that the FDB address is assumed to be present
in RO.
The third parameter, i.e., the dataset-descriptor pointer, is
not specified;
this null specification (indicated by the extra comma)
assumes that FbB 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 racc parameter fields are null, based on the premise
that the dataset-descriptor pointer
(F.DSPT)
has been
provided
previously to the FDB and that the record-access byte (F.RACC) has
also been previously initialized.
Finally, the last two parameters
establish the address and the size of the user record buffer,
respectively.
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,
requir~ng
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
3.1.2

FDB Requirements for Generalized OPEN$x Macro Call

The information required for opening a file may be supplied to the FOB
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 FOB is a matter of choice, as indicated above.
Of far
greater significance is the fact that certain information must be
present in the FOB 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 FOB.
This information may be specified
through the FOAT$A macro call (see Section 2.2.1.2) or the
FOAT$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.
b.

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

FO.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 and characters are
not actually embedded within the record. Their presence
is merely implied through the file attribute FO.CR.
FO.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 FOB offset
location F.RSIZ.

3-8

FILE-PROCESSING MACRO CALLS
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 deal location 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 j~itialize 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.

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

3-9

FILE-PROCESSING MACRO CALLS

If file identification information is not already present
in
the
FDB, either the dataset-descriptor pointer
(F.DSPT) or the default filename-block address
(F.DFNB)
must be specified to enable FCS to obtain required
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 FDB offset
location F.EFN. This optional parameter may be specified
in either the FDBF$A macro call (see Section 2.2.1.6) or
the FDBF$R macro call
(see Section 2.2.2).
If not
specified, FCS uses event flag number 32(10) by default
in synchronizing all record I/O activity.

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

The override block size
(ovbs parameter)
must
be
specified in either the FDBF$A or the FDBF$R macro call
to initialize FDB offset location F.OVBS. This parameter
need be specified only if the standard default block size
in effect for the associated device is to be overridden.
The override block size is specified only in connection
with record-oriented devices (such as line printers)
and
sequential devices (such as magnetic tape units).

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

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

To allocate required file space at the time a file is
created,
the cntg parameter must be specified in either
the FDAT$A or the FDAT$R macro call.
This parameter
initializes 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.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 are summarized in section 1.8.

3-11

FILE-PROCESSING MACRO CALLS
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 s~AngE(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 CLOSES macro call (see Section
3.8). Continue other processing in the program, as desired.

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

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

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

.MRKDL

The .MRKDL routine is described in Section 4.13.1.
7.

Close the file by issuing the CLOSES macro call.

3-12

FILE-PROCESSING MACRO CALLS
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 lAS System Management Guide,
RSX-llD Utility Programs Procedures Manual,
and RSX-ll Utilities
Procedures 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.
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.

3.5

format

and

parameters

the

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. Thus, issuing this macro call invokes
an Fes routine that opens a file only by file ID (see Section 2.5).
The OFID$x call, which has the same format and takes the same
parameters as 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.

3-13

FILE-PROCESSING MACRO CALLS
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
therefrom 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
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.1;
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.

3-14

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

The filename

2'.

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

The file version number

The directory 10 (offset location N.OIO);

The device name (offset location N. DVNM) ;

The unit number

must

(offset location N.FNAM);

(offset 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 Oefault 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 speci£ied 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.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 2.4.2) to create and
initialize a default filename block. With the exception of
the directory 10, this structure provides all the requisite
information to FCS.

To provide the directory 10, call
routines:

either

the

following

Call the .GTOIR routine (see Section 4.9.1)
to retrieve
the directory ID from the specified dataset descriptor
and to store the directory 10 in the default filename
block; or

Call the .GTOIO 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.

FILE-PROCESSING MACRO CALLS
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.FIO)
in the filename block contains a nonzero value when
the call to OFNB$x is issued, the file is unconditionally opened by
file 10.
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 OFIO$x coding should not be included in
the same overlay with OFNB$x, since OFIO$x overlaps the function of
OFNB$x and, therefore, needlessly consumes memory space.

3.7

OPENS - 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,
file type, and file version
number, and a file of that description already exists in the specified
user file directory (UFO), 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 UFO.
Rather than deleting the old version of the
file, an error indication (IE.OUP)
is returned to offset location
F.ERR of the applicable FOB.
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 facc parameter and the dfnb parameter.
These
additional parameters are described below.
To open a file without superseding an existing file having an
identical file specification,
a macro call ~f the following form is
used:
OPENS
where:

facc

fdb,facc,lun,dspt,dfnb,racc,urba,urbs,err
represents anyone or an appropriate combination
of the following symbolic values indicating how
the specified file is to be accessed:
FO.RO - 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 modif~ed.

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

FILE-PROCESSING MACRO CALLS
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$

3.8

#OUTFDB,#FO.WRT!FA.TMP!FA.SHR

CLOSES - CLOSE SPECIFIED FILE

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

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

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

Deaccesses the file.

Releases the FSR block
(record I/O only) .

Prepares the FDB for subsequent use by
FDB 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 CLOSES Macro Call

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

fdb,err

fdb

represents a symbolic value of the address of
associated FDB.

err

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

3-17

the

optional

FILE-PROCESSING MACRO CALLS
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.
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 FDB (F.NRBD+2 and F.NRBD).
In locate mode, if the entire record resides within the FSR block
buffer,
then the address and the size of the record just read are
returned to the next record-buffer descriptors (F.NRBD+2 and F.NRBD).
If, on the other hand, the entire record does not reside within the
FSR block buffer, then that record is moved piecemeal into 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:
GET$

fdb,urba,urbs,err

3-18

call

specified

the

FILE-PROCESSING MACRO CALLS
where:

fdb

represents a symbolic value of the address of
associated FDB.

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
location F.URBD in the associated FDB.

err

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

the

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.
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.URBDi
or

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

In both move and locate mode, only data up to the amount specified in
F.URBD is placed in 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 routipe.
The second exampl~ also assumes that RO contains the address of the
desired FDB.
Explicit parameters then define the address and the
size, respectively, of the user record buffer.
The last example shows a GET$ macro call in which only the address
the FDB is specified.

3-19

FILE-PROCESSING MACRO CALLS
3.9.2

FOB 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 FOB.
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, l.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 call (to appropriately initialize the FOB) only if not
previously supplied through some other available means.
If operating in random-access mode, the number of the record to be
read is maintained by FCS in offset locations F.RCNM and F.RCNM+2 of
the associated FOB. FCS increments this value after each GET$ or
GET$R operation to point to the next record in the FSR block buffer.
Thus, 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 during 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 FOB. 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:

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

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

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 FOB, 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 FOB is initialized with FD.BLK prior
to file create-time, then the records in the reSUlting file
are not allowed to cross block boundaries.

3-20

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 that file are allowed to cross
block boundaries.
The design of FCS requires the utilization of a user
record
buffer only in the event that records
(either fixed or
variable in length) cross block boundaries.
3.

If a GET$ operation is performed in locate mode, and the
record is contained entirely within the FSR block buffer, the
address of the record within the FSR block buffer and the
size of that record are returned to offset locations F.NRBD+2
and F.NRBD, respectively, in the associated FDB.
However, if
that record crosses block 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 block 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 FDB.

3.10

GET$R - READ LOGICAL RECORD IN RANDOM MODE

The GET$R macro call is used to read fixed-length records from a file
in random mode. Thus, by definition, issuing this macro call requires
that 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
FDB
(at offset locations F.RCNM and F.RCNM+2), then GET$ may be used.
If, however, the record-access byte in the FDB
(offset location
F.RACC)
has not been initialized for random-access operations with
FD.RAN in the FDRC$A, the FDRC$R, or the generalized OPEN$x macro
call, then neither GET$ nor GET$R will read the desired record.
The GET$R macro call takes two more parameters in
specified in the GET$ macro call, as shown below:
GET$R
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 number 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-21

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 FDB offset
location F.RCNM.
If specified, the combination of
this parameter and the lrcnm parameter above
determines the number of the desired record.
Thus, an unsigned value having a total of 31 bits
of magnitude may be used in defining the record
number.
If this parameter is not
specified,
offset
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 number; otherwise, any
residual value in F.RCNM yields an incorrect
record number.

If the lrcnm and hrcnm parameters are not specified in a subsequent
GET$R macro call, the next sequential record is read since the record
number in offset locations F.RCNM+2 and F.RCNM is automatically
incremented with each GET$ operation.
In the case of the first GET$R
after opening the file, record number 1 is read, because the record
number has been initialized to 0 by the OPEN.
If 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
macro call:
GET$R

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

GET$R

#FDBADR,#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.

3.11

GET$S - READ LOGICAL RECORD IN SEQUENTIAL MODE

The GET$S macro call is used to read logical records from a file
in
sequential mode. Although the routine invoked by the GET$S macro call
requires less memory than that invoked by GET$
(see Section 3.9),
GET$S has the same format and takes the same parameters. The GET$S
macro call is de~igned 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 PUTS can be realized only
if GET$S and PUT$S are placed on different branches of the overlay
structure.

3-22

FILE-PROCESSING MACRO CALLS
3.12

PUTS - WRITE LOGICAL RECORD

The PUTS 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 FOB.
FCS increments this value after each PUTS or
PUT$R operation to point to the next sequential record position.
Thus, unless the user program alters this value before issuing another
PUTS or PUT$R operation, the next record in sequence is written.
For PUTS operations, offset locations F.NRBD+2 and F.NRBD in the
associated FOB must contain the address and the size, respectively, of
the record to be written.
The distinction between move mode and
locate mode for
PUTS 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 FOB (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 PUTS 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 PUTS macro call.
Then,
if the record so
built is not already in the FSR block buffer, it is moved there as the
PUTS operation is performed.
If the records in the file are sequenced records, the field F.SEQN in
the FOB contains the sequence value, which can be modified by the
user.
PUTS operations are fully synchronous, i.e., record I/O operations are
completed before control is returned to the user program.
A random PUTS operation in locate mode requires the use of the
.POSRC
routine.
This operation is described in detail in Section 4.9.2.
Specific FOB requirements for PUTS operations are presented in Section
3.l2~2 below.

3.12.1

Format of PUTS Macro Call

The PUTS macro call takes the following format:
PUTS
where:

fdb,nrba,nrbs,err

fdb

represents a symbolic value of the address of
associated FOB.

nrba

represents the symbolic address of the next record
buffer,
i.e.,
the address of the record to be
PUTS.
This parameter initializes FOB
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 PUTS. This parameter initializes FOB
offset location F.NRBD.

err

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

the

optional

FILE-PROCESSING MACRO CALLS
The following examples represent the uses of the PUTS macro call:
PUTS

#FDBADR",ERRRT

PUTS

,,#160.,ERRRT

PUTS

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

3.12.2

the

FDB;

all

other

FDB Mechanics Relevant to PUT$ Operations

The discussions below highlight aspects of PUTS 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 PUTS 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 PUTS operations require the utilization
of a user record buffer. Note, however, that PUTS 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.
Whether in move or locate mode, a PUTS operation uses the information
in offset locations F.NRBD+2 and F.NRBD, i.e., the next record-buffer
descriptors, to determine whether the record must be moved into -the
FSR block buffer. In the event that the record does have to be moved,
and the size of that record is such that it cannot fit in the space
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 the associated
FDB) , then the FSR block buffer is written out to the volume
as is, and the entire record is moved into the beginning of
the next FSR block buffer.

3-24

FILE-PROCESSING MACRO CALLS
3.12.2.1 PUT$ Operations in Move Mode - A
is basically driven by specifying in each
and the size of the record to be written.
is performed, FCS moves the record into
FSR block buffer.

PUT$ operation in move mode
PUT$ macro call the address
Then, as the PUT$ operation
the appropriate area of the

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.

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 block 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$
operation thereafter in locate mode updates the address value in this
cell to point to the area in the FSR block buffer where the next
record is to be built.
Thus, after each PUT$ operation in locate
mode, F.NRBD+2 points to the area where the next record is to be
built. This logic dictates whether the user record buffer is required
in locate mode.
In this regard, the following generalizations apply:
1.

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

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.

3-25

FILE-PROCESSING MACRO CALLS
3.

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 buffer to
accommodate the record.
Because the records are variable in length,
it must be
assumed that the largest possible record is PUT$, as defined
by the size of 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.

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.
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
userls 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 en~irely 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 m~cro 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.
3-26

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

addition

those

fdb,nrba,nrbs,lrcnm,hrcnm,err

lrcnm

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.

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 (0).
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 PUTS 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 PUTS 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

3-27

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

3.14

PUT$S - WRITE LOGICAL RECORD IN SEQUENTIAL MODE

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

3.15

READ$ - READ VIRTUAL BLOCK

The READ$ macro call is issued to read a virtual block of data from a
block-oriented device
(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 Section
2.8.2), and/or the program traps to a user-coded AST service routine
at the completion of block I/O operations (see Section 2.8.3).
In issuing the READ$ (or WRITE$) macro call, 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 tor
error codes immediately after issuing the READ$/WRITE$ call as well as
on return from the WAIT$ call. The READ$/WRITE operations can return
error codes distinct from those that can be present on completion of a
WAIT$ operation.
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.

3-28

FILE-PROCESSING MACRO CALLS
3.15.1

Format of READ$ Macro Call

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

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

fdb

represents a symbolic value of the address of
associated FDB.

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

bkvb

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.

the

As noted in connection with the FDBK$A macro call
described
in
Section
2.2.1.4, assembly-time
initialization of the virtual-block number in the
FDB is ineffective, since the generalized OPEN$x
macro call sets the virtual-block number
in the
FDB to 1.
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.
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 the I/O
status block (see bkst parameter below)
and 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

3-29

FILE-PROCESSING MACRO CALLS

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 incremented by 1
automatically
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 FDB offset location
F.BKEFi
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.

bkst

represents the symbolic address of the I/O status
block in the user program (see Section 2.8.2).
This parameter, which initializes offset location
F.BKST, is optional.
The I/O status block is
filled in by the system when the requested block
I/O
transfer
is
completed,
indicating the
success/failure of the requested operation.
The address of the I/O status block may also be
specified in either the FDBK$A or the FDBK$R macro
call. If the address of this 2-word structure is
not supplied to FCS through any of the available
means, status information 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.

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

FILE-PROCESSING MACRO CALLS
err

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

optional

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

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.

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

3.16

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

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

The virtual-block number
F. B,KVB) .

(in offset

locations

and

F.BKVB+2

and

WRITE$ - WRITE VIRTUAL BLOCK

The WRITE$ macro call is issued to write a virtual block of data to a
block-oriented device (e.g., a disk or DECtape). 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).

3-31

FILE-PROCESSING MACRO CALLS
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 call to suspend program execution
until a program-dependent I/O transfer has been completed.
When the
WAIT$ macro call is used for this purpose, the event flag number and
the I/O status block address in both macro calls must be the same.
Again, as with READ$ operations, the user should check for an error
code immediately following the WRITE$ macro call as well as on return
from the WAIT$ macro call.

3.16.1

Format of WRITE$ Macro Call

The WRITE$ macro call takes the same parameters as the READ$ macro
call, as shown below.
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.
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$

WRITE$

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

WRITE$

RO",,#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.

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

the

FILE-PROCESSING MACRO CALLS
3.17

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$ operations to 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.
In this case, the READ$ operation is initiated in the usual manner,
but the Executive of the host operating system suspends program
execution until the specified event flag is set, indicating that the
I/O transfer has been completed. The system then returns information
to the I/O status block,
indicating the success/failure of the
operation.
FCS then moves the I/O status block success/failure
indicator into offset location F.ERR of the associated FDB,
and
returns with the C-bit in the Processor Status Word cleared if the
operation is successful, or set if the operation is not successful.
Task
execution then continues with the instruction immediately
following the WAIT$ macro call.
The system returns the final status of the I/O operation to the I/O
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 of
associated FDB.

the

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.
If this parameter is not specified, either in the
WAIT$ macro call or the associated READ$/WRITE
macro call, FDB offset location F.BKEF is assumed
to contain the desired event flag number, as
previously initialized through the bkef parameter
of the FDBK$A or the FDBK$R macro call.

3-33

FILE-PROCESSING MACRO CALLS

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.

bkst

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

RO,#25.,#IOSTAT

WAIT$

RO,,#IOSTAT,ERRLOC

The first example assumes that RO contains the address of the
associated FDBi
furthermore,
since the event flag number (bkef
parameter) is not specified, offset location F.BKEF is assumed to
contain the desired event flag number.
If this cell in the FDB
contains 0, 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.

3-34

the

FILE-PROCESSING MACRO CALLS
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 t6 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.18

DELET$ - DELETE SPECIFIED FILE

The DELET$ macro call causes the directory information for
the file
associated with the specified FDB to be deleted from the appropriate
user file directory (UFD). The space occupied by the file is then
deallocated and returned for
reallocation to the pool of available
storage on the volume.
This macro call can be issued for a file that is either open or
closed.
If issued for
an open file, that file is then closed and
deleted;
if issued for a closed file, that file is deleted only if
the 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 DELET$ operation fails.

3.18.1

Format of DELET$ Macro Call

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

fdb,err

fdb

represents a symbolic value of the address of
associated FDB.

err

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

The following statements illustrate DELET$ macro calls:
DELET$

DELET$

#OUTFDB,ERRLOC

DELET$

RO,ERRLOC

3-35

the

optional

CHAPTER 4
FILE CONTROL ROUTINES

File control routines can be invoked in MACRO-II 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 file-owner word in $$FSR2.
• Convert a directory string from ASCII to binary, or vice versa.
• 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.
• Place directory information in a default filename
filename block.

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
([l,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 CALL is issued, certain
specific registers be preset
requirements are identified in
routines.
Upon return, all
explicitly specified as changed.

file control routines require that
with requisite information.
These
the respective descriptions of the
registers are preserved, except those

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
.ASLUN
.FIND
.ENTER
.REMOV
.GTDIR
.GTDID
.POINT
.POSRC
.POSIT
.XQIO
.RENAM
• EXTND
.TRNCL
.MRKDL
.DLFNB
.CTRL

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

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

4-2

FILE CONTROL ROUTINES
(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 MACRO-II 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
an ASCII string, the default UIC is maintained as a binary value with
the following format:
Bit

7
MEMBER

GROUP

4-3

FILE CONTROL ROUTINES
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
.WOFUI
routine described below, the default UIC in $$FSR2 always corresponds
to the UIC under which the task is running.

4.3.1

.RDFUI - Read Default UIC

When called, the .ROFUI 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 .WOFUI routine is called to create a new default UIC in $$FSR2.
The following register
routine:
Rl

4.4

must

preset

before

calling

the

.WOFUI

Must contain the binary representation (as shown above) of a
UIC.

DEFAULT FILE-PROTECTION WORD ROUTINES

The .RDFFP and .WOFFP 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

11
GROUP

WORLD

SYSTEM

OWNER

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

each

bit

has

the

DELETE

EXTEND

WR ITE

READ

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

4-4

FILE CONTROL ROUTINES
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.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 -I, 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.
Normally, the owner of a new file corresponds to the default UIC under
which the task creating the file is running.
However, through the
.WFOWN routine (see section 4.5.2 below), a UIC value can be stored in
the file owner word so that any new files then created and closed by
the user program can have the desired UIC.
The format of the file-owner word is shown below:
Bit

7
MEMBER

GROUP

The routines for reading and writing the file-owner word are described
below.
NOTE
The UIC and the file-protection word for
the file
(see Section 4.4) must not be
set such that the Ule under which the
task is running does not have access to
the file.
If this condition prevails, a
privilege violation results.

4-5

FILE CONTROL ROUTINES
.RFOWN - Read $$FSR2 File-Owner Word

4.5.1

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

4.6

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

ASCII/BINARY UIC CONVERSION ROUTINES

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

convert

.ASCPP - Convert ASCII Directory String

4.6.1
UIC

directory

FILE CONTROL ROUTINES
4.9.1

.GTDIR - Insert Directory Information in Filename Block

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

Must contain the address of the desired FDB.

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

Must contain the address of the 2-word directory-string
descriptor in 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.

4.9.2

.GTDID - Insert Default Directory Information in Filename Block

The
.GTDID routine provides an alternative means for
inserting
directory information into a specified filename block.
Instead of
allowing the specification of the directory string, as does the .GTDIR
routine above, this routine uses the binary value found in the default
Ule 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 Ule 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,
N.FVER, N.DVNM, and N.UNIT in the filename block, but zeros the rest
of the filename block.
The .GTDID routine embodies considerably less code than
routine.
Its input is the binary representation of a Ule
an ASCII string descriptor. Therefore, it does not invoke
logic;
furthermore,
.GTDID is intended specifically

4-15

the
.GTDIR
rather than
the
. PARSE
for use in

FILE CONTROL ROUTINES
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 F.NRBD+2 in the associated FDB in preparation for a PUTS
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.
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
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)
cqrrent positional context of the file.

Close the file.

When desired, reopen the file.

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

4-16

to save the

FILE CONTROL ROUTINES
5.

Call the .POINT routine.
The .POINT routine may be called to rewind a file on ANSI
magtape to its start.
For this case, RO and R3 must be 0,
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 FOB 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 FOB to the desired record number and ensure
that the correct record size is reflected in offset location F.RSIZ of
the FOB.
Also, the register below must be
routine:
RO

preset

before

calling

the

.POSRC

Must contain the address of the associated FOB.

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

Set offset locations F.RCNM+2 and F.RCNM
FOB 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 FOB.

Perform the PUT$ operation.

4.10.3

the

associated

.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 also 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 FOB before calling
routine.

4-17

this

FILE CONTROL ROUTINES
When called, the .MARK routine returns information
registers:

the

following

Contains the high-order bits of the virtual-block number.

Contains the low-order bits of the virtual-block number.

Contains the number of
block.

the

byte

within

the

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

In addition, offset locations F.RCNM and F.RCNM+2
FOB 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 FOB.

Must contain the desired QUEUE I/O function code.
Refer to
the IAS/RSX-llD Device Handlers Reference Manual or the
RSX-llM 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.

4-18

FILE CONTROL ROUTINES
4.12

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 FOB 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 under its new name, provided that the renaming
operation is successful.
The following registers must be preset before calling this routine:
RO

Must contain the address
originally named file.

the

FOB

associated

with

the

Must contain the address of the FOB 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 ".;1
11

•

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

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

Must contain the extension control bits, as appropriate.
The
possible bit configurations for controlling file extend
operations are detailed in Table 4-1. This table defines the
bits in the low-order byte of R2. The high-order 8 bits of
R2 (Bits 8 through 15) are used in conjunction with the 16
bits of Rl to define the number of blocks to be added to the
file (see Note below).

4-19

blocks

FILE CONTROL ROUTINES
NOTE
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.

4.14

FILE TRUNCATION ROUTINE (.TRNCL)

The .TRNCL routine truncates a file to its logical end-of-file
deal locates 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.15.1

.MRKDL - Mark Temporary File for Deletion

The .MRKDL routine is used in conjunction with a temporary file, i . e • ,
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

that

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

EX.ACI - BIT 0 = 1 ;
indicates that
extend is to be contiguous and that
file is to be contiguous.
(continued on next page)
4-20

FILE CONTROL ROUTINES
Table 4-1
(Cont.)
R2 Control Bits for .EXTND Routine
BIT SETTINGS Low-Order Byte of R2

BIT DEFINITIONS AND MEANING
EX.ENA - Bit 7

= 1

EX.ACI - Bit 0 = 0;
indicates that
noncontiguous area is to be added to
the file.

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

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

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

that

EX.FCO - Bit 2 = 1 ;
indicates
the file is to be contiguous.

that

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

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

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.
4-21

FILE CONTROL ROUTINES
The .OLFNB 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
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:

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

Rewind a magnetic tape volume set.

Position to the logical end of a magnetic tape volume set.

Close the current magnetic tape
operations on the next volume.

Space forward or backward n 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 FOB.

Must contain one of the following function codes:
FF.RWO 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.

R2 and R3 must each contain

end

current volume and
the next volume of

magnetic

tape

continue
file
a magnetic tape

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

Rl,

R2,

Must contain the address of the associated FDB.

Must contain the value FF.SPC.

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

Must contain

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.

4-22

.CTRL

value

accomplish

CHAPTER 5
FILE STRUCTURES

lAS, RSX-llD, and RSX-llM support an identical file structure on disk
and DECtape. They also support ANSI file structure on magnetic tape.
The disk and DECtape file structure is called FILES-II;
tape file structure is ANSI standard.

5.1

the

magnetic

DISK AND DECTAPE FILE STRUCTURE (FILES-II)

Volumes contain both user files and system files.
Disks and DEC tapes
initialized through the INITIALIZE (lAS) or INITVOLUME (RSX) command
have the standard FILES-II structure built for them automatically.
The standard system files created through these commands include the
following:
1.

Index file

Storage-allocation file

Bad-block file

Master file directory (MFD)

Checkpoint file

Each FILES-II 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 lAS, and the UFD command in RSX-ll 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-ll systems, and by the CREATE/DIRECTORY command in
lAS.
These commands are described in detail
in the RSX-IID User's
Guide,
the RSX-IIM Operator's Procedures Manual, and the lAS System
Management GUlde.
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.

use by the
information
Appendix E
of an index

MFD

I
1

I
FILE A

Figure 5-1

FILE 8

1
FILE C

Directory Structure for Single-User Volumes

5-2

FILE STRUCTURES

MFO

UFO
100,100

UFO
200,200

FILEA

Figure 5-2

5.1.4

I
FILE B

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 + 3 + 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 DIC.
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.
However, lAS uses
magtapes with standard ANSI labels.
There is no place for the
creation time or the length of the file in the ANSI file-header
labels.
Consequently, the creation time is listed as O. If a

5-3

FILE STRUCTURES
contiguous file is copied to magtape 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.
The map area provides the information needed by
virtual-block numbers to logical-block numbers.

the

system

map

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

lAS and RSX 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 FOB.
The sequence in which volume and file labels are used and
of each label type is defined in Appendix G.

5.2.1

the

format

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.I.I.I.
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 FOOP$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 FOOP$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 VOLI label on the
first volume of the set. All files previously contained in the entire
volume set are lost.
To create a file in the next file position, FA.POS must be set in FOB
location F.ACTL.
The default value for this FOB position is 0 (not
FA.POS).
The default indicates that the file system is to position at
the logical end of the volume set to create the file.
When the default is used, no check is made for the existence of a file
with the same name in the volume set.
Therefore, a program written to
use magnetic tape normally should specify FA.POS.
The next file-position option is ignored by directory-device file
processors.
However, programs written mainly for directory devices
cannot specify the next file-position option in open commands for
output and,
therefore,
cause the position to end process to be used
automatically.

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.

Open the first file again for input (rewind is optional).
5-5

FILE STRUCTURES
4.

Read and process the data.

Close the file with rewind.

Open the second file with rewind specified.

Write the data records.

Close the file
processing.

5.2.5

with

rewind

and

perform

any

additional

Multiple-File Operations

A multiple-file volume is created by opening, writing,
and then
closing a series of files without specifying a rewind. The sequential
processing of files on the volume can be accomplished by closing
without rewind and then opening the next file without rewind.
Opening a file for extend (OPEN$)
the volume set.

is legal only for the last

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.

file

multiple-file

Files on tape can be opened in a nonsequential order, but increased
processing and tape-positioning time is required.
Nonsequential
access of files in a multivolume set is not recommended.

5.2.6

Using .CTRL

The .CTRL file control routine can be called to override
defaults for magnetic tape.
Examples of its uses are:

normal

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.,
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 first file section is read and

mount

the

For output files, the following processing occurs.
1.

The current file section is closed with EOVI and EOV2
and the volume is rewound.

labels

The next volume is mounted.

A file with the same name and the next higher section number
is opened for write.
The file-set identifier is identical
with the volume identifier of the first volume in the volume
set.
NOTE
I/O buffers that are currently in memory are
on the next file section.

written

When .CTRL is used to position to the logical end-of-volume set,
the
file system positions between the two tape marks at the logical end of
the last volume in the set.
When .CTRL is used to space forward or backward across blocks
magnetic tape, spacing crosses volumes for multivolume files.

5.2.7

Examples of Magnetic Tape Processing

The following pages contain examples of FCS statements used to process
magnetic tape.
Macro parameters not related to magnetic tape handling
have been omitted from the statements so that 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

5-7

iSET REWIND AND ENABLE USE
iOF F.ACTL

FILE STRUCTURES
OPNXTO:
OPEN FOR NEXT FILE POSITION
FDOP$R
BR

RO",,#FA.ENB!FA.POS
OPNOUT

iSET POSITION TO NEXT
iAND ENABLE USE OF F.ACTL

OPROYK:
OPEN FILE AT END OF VOLUME KEEPING CURRENT USER
ACCESS CONTROL BITS
BIC
BR

iDISABLE USE OF F.ACTL

#FA.ENB,F.ACTL(RO)
OPNOUT

OPROVO:
OPEN FILE AT END OF VOLUME - SELECT SYSTEM DEFAULT FOR
USER ACCESS CONTROL BITS
iDISABLE USE OF AND RESET
FDOP$R RO",,#O
BR
OPNOUT
iF.ACTL TO ZERO

OPEN FILE WITH CURRENT USER ACCESS CONTROL

OPOURO:
BIS
OPNOUT: OPEN$W
RETURN

#FA.ENB,F.ACTL(RO)
RO

iENABLE USE OF F.ACTL
iOPEN FILE

5.2.7.2 Examples of OPEN$ 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

iDISABLE USE OF F.ACTL

OPEN USING USER ACCESS CONTROL
i

OPDFLI: BIS
OPNIN: OPEN$R
RETURN

#FA.ENB,F.ACTL(RO)
RO

iENABLE USE OF F.ACTL

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

iDISABLE USE OF F.ACTL
iDEFAULT IS LEAVING AT CURRENT

iPOSITION
5-8

FILE STRUCTURES
CLSRWD:
CLOSE REWINDING THE VOLUME
FDOP$R
BR

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

iSET REWIND AND ENABLE USE OF
iF.ACTL

CLOSE WITH USER ACCESS CONTROL BITS
CLSDFL: BIS
CLOSE: CLOSE$
RETURN

#FA.ENB,F.ACTL(RO)
RO

iENABLE 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.
i
i

SCRATCH TAPE OPERATIONS--SINGLE FILE VOLUME--

SCROUT: MOV
CALL
RETURN
SCRIN: MOV
CALL
RETURN
CLSCRO: MOV
BR
CLSCRI: MOV
CLSVOL: CALL
RETURN

# FDBOU'I' ,RO
OPRWDO

iSELECT FDB AND OPEN
iOUTPUT FILE WITH REWIND

#FDBIN,RO
OPRWDI

iSELECT FDB AND OPEN FOR
iINPUT WITH REWIND

#FDBOUT,RO
CLSVOL
FDBIN,RO
CLSRWD

iCLOSE SCRATCH FILE
iREWINDING VOLUME

MULTI-FILE VOLUME OPERATIONS
i

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

#FDBIN,RO
OPCURI

iSELECT FDB
iOPEN FILE

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

iSELECT FDB

#FDBIN,RO
OPRWDI

MULTI-FILE OUTPUT OPERATIONS
i

OPNINT:
START NEW VOLUME DESTROYING ALL PAST FILES ON IT
MOV
CALL
RETURN

iSELECT OUTPUT FDB
iOPEN 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

iSELECT OUTPUT FDB

OPENDT:
OPEN OUTPUT FILE AT CURRENT END OF VOLUME SET KEEPING USER
ACCESS CONTROL BITS
MOV
CALL
RETURN

#FDBOUT,RO
OPROVK

iSELECT OUTPUT FDB

OPNEOV:
OPEN OUTPUT FILE AT CURRENT END OF VOLUME AND MAKE THAT THE USER
ACCESS CONTROL
MOV
CALL
RETURN

#FDBOUT,RO
OPROVO

iSELECT OUTPUT FDB

NOT LAST FILE IN FILE SET CLOSE ROUTINE
i

CLSFLO: MOV
BR
CLSFLI: MOV
CLSXX:
CALL
RETURN

#FDBOUT,RO
CLSXX
#FDBIN,RO
CLSCUR

iSELECT OUTPUT FDB
iSELECT INPUT FDB

TO APPEND TO LAST FILE
OPEN$A

#FDBOUT

5-10

CHAPTER 6
COMMAND-LINE PROCESSING

As noted in Section 2.4.3, a collection of routines available from the
system object library
([l,l]SYSLIB.OLB) may be linked with 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
(CSI).
Normally,
this routine
takes command lines from the GCML command-line-input buffer
and parses them into the appropriate dataset descriptors
required by FCS for opening files.

This body of routines is linked with the'user program at task-build
time.
GCML and CSI are often jointly incorporated in system or
application programs as a standardized interface for obtaining and
interpreting dynamic command-line input.
The flow of data during
command-line processing is shown in Figure 6-1.
Although these routines are presented in the context of being used
together
for
processing command-line input, each may be used
independently of the other. Doing so, however, means that 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 CSI functions requires that certain
initialization operations be accomplished at assembly time. This
initialization sets up the GCML command-line-input buffer, defines and
initializes control blocks for both GCML and CSI, and establishes the
necessary working storage and communication areas for these routines.
Also,
the
appropriate
macro calls that invoke GCML and CSI
execution-time functions must be included in the source coding at
desired logical points to effect the dynamic processing of command
lines.
GCML and CSI macro calls observe the same register conventions
applicable to FCS. All registers, except RO, are preserved exactly as
in all FCS macro calls.
RO is used to contain the address of the GCML
control block or the CSI control block, as appropriate.
As with all FeS macro calls, the GCML and CSI macro calls must also be
listed as an argument in an .MCALL directive (see Section 2.1) before
being issued in the user program.

6-1

COMMAND-LINE PROCESSING

ASCII DATA

PDS/MCR

ON-LINE
STORAGE

(

GCML

CSI
~

DEFAULT
FILENAME
BLOCK

DATASET
DESCRIPTOR

-'"

FCS
(.PARSE)

FILENAME
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, GCML accepts commands that
run to more than one line. This continuation mechanism takes effect
automatically 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.

6-2

COMMAND-LINE PROCESSING
6.1.1

GCMLB$ - Allocate and Initialize GCML Control Block

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

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 CMI 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 offset,s 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:
where:

GCMLB$

maxd,prmpt,ubuf,lun,pdl,size

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
0
is defined by default,
effectively eliminating an indirect command file
as a source of command-line input.

prmpt

represents a user-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 PROCESSING
The ASCII prompting sequence
the following 6-byte string:
return

«CR»

formulated

A carriage
«LF»;

and

2•

The 3 ASCII characters specified by the
and

3•

A right angle bracket ( » .

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
GCML for temporary storage of command-line input.
If this parameter is not specified, a buffer,
whose length is determined by the size parameter,
is reserved in the GCML control
block
for
command-line input. If neither this parameter nor
the size parameter is specified, a 41-word buffer
is reserved by default in the GCML control block.

lun

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

pdl

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

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:

= 80.

(4+1)*16.

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: GCMLB$
GCLBLK: GCMLB$
GCLBLK: GCMLB$

6.1.2

GCMLB$

macro

call

might

4.,GCM,BUFADR,1.
"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 anyone of the error conditions
recognized by GCML occurs during the processing of
an appropriate error code is
a command line,
returned to offset location G.ERR in the control
block. These error codes are described below:
GE.IOR* - Indicates that an I/O error
during the input of a command line.

occurred

GE.OPR* - Indicates that GCML was unable
or reopen the specified command file.

open

* For GE.IOR and GE.OPR, 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 PROCESSING
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.EOF - Indicates that the end-of-file
(EOF)
on
the first (unnested) command file was detected.
This bit is set in connection with command-file
input.
When the first call is issued for input,
GCML attempts to retrieve an MCR/POS command line.
The first line obtained, whether it is an MCR/POS
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 (EOF) 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/POS command has already been read at
level 0, entering another MCR/POS command when
level a is again reached causes the error code
GE.EOF to be returned to offset location F.ERR of
the GCML control block.
Hence, only one MCR/POS
command line can be read at level O.
If input
thus fails at MCR/PDS level 0, then GCML continues
to prompt for input until CTRL/Z is typed by the
user to indicate terminal end-of-file (EOF).
In summary, the first line of input is always read
at level O. This initial input may be an MCR/POS
command;
if the MCR/POS command fails or is null,
the command-input file
(normally a terminal) is
then opened at level O. Multiple inputs at level
o are permissible only in the latter case, i.e.,
from the command-input file.
G.MOOE

Status and Mode Control Byte.
This field
is
initialized at assembly-time with bit definitions
to specify certain default actions for GCML during
the retrieval of a command line. At runtime, the
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 symbolic name of the bit to be
cleared.
In the case of the GE.LC value
(see
below),
the BISB instruction can be used to
override the default action.

6-6

COMMAND-LINE PROCESSING
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 0 for any reason, GCML keeps
the current command file open between calls for
input.
In this case, the FSR (see Section 2.6.1)
must include one additional 5l2(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 (i) 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 0, a command line containing a
leading semicolon
(i) 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 0 at assembly-time through the
GCMLB$ macro call (see Section 6.1.1).
When the GCML$ macro call is issued to request
command-line input
(see Section 6.1.3.1),
the
address and the length of a prompting sequence is
usually
not
specified.
In this case,
the
prompt-string descriptor words in the GCML control
block are cleared, causing GCML to type out the
default prompt string contained in offset location
G.DPRM (see below) to solicit command-line input.

6-7

COMMAND-LINE PROCESSING

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 input, thereby overriding the default
prompt string previously established through the
GCMLB$ macro call (see G.DPRM below).
If the adpr and lnpr parameters are not specified
in a subsequent GCML$ macro call, offset location
G.PSDS in the control block is automatically reset
to 0,
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 CSI as the "buff"
and "len" parameters in the CSI$l macro call
(see
Section
6.2.3.1).
The combination of these
parameters
constitutes
the
command-line
descriptors that enable CSI to retrieve file
specifiers from the GCML
command-line
input
buffer.

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,
counters, etc., in connection with input from an
indirect command file.
In usage terms,
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
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.

6-8

COMMAND-LINE PROCESSING
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$

6.1.3

iDEFAULT LOCAL DEFINITION.

GCMLD$

DEF$L

iLOCAL DEFINITION.

GCMLD$

DEF$G

iGLOBAL DEFINITION.

GCML Run-Time Macro Calls

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.

adpr

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.

Inpr

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 PROCESSING
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 the adpr and Inpr parameters are not
GCML$ macro call, offset location G.PSDS
automatically reset to 0, 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 ~o 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 hypen(s) removed.

At the initial issuance of the GCML$ macro call, an attempt is made to
retrieve an MCR/PDS command line. If this attempt fails, or if the
MCR/PDS command line is null, the FDB within the GCML control block is
used to open a file for command-line input. If the command-input
device is a terminal, a prompt string is typed out to solicit input.
Any desired command input may then be entered. If the continuation
mechanism is being used, the prompt string is similarly typed to
solicit subsequent portions of a continued command line.
If appropriate, 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. 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 0 when EOF is detected, the error code
GE.EOF is returned to offset location G.ERR of the GCML
control block (see Section 6.1.2).

An indirect~file specifier is encountered in a command line.
In this case, the current indirect command file is closed (if
not already closed), and the new indirect file is opened.
The first command line therein is then read.

6-10

COMMAND-LINE PROCESSING
3.

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

The user may also enter a semicolon (i) as the first character in the
command line. Such a line is treated as a comment and is not 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 andG.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$l 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$
where:

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.

When this macro call is issued, the current indirect command file is
closed,
returning control to the top-level
(unnested)
file.
A
subsequent GCML$ macro call then retrieves the next command line from
the O-level command file.
Note, however, that a second MCR/PDS
command at level 0 cannot be read (see GE.EOF error code in offset
location G.ERR of GCML control block, Section 6.1.2).

6--11

COMMAND-LINE PROCESSING
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 0,
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 keeping the file open between calls
for input reduces total file-access time.
However,
should it be
desirable to close such a file to free FSR-block-buffer space, 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 ~se
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 FOB:
1.

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

6-12

COMMAND-LINE PROCESSING
2.

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 is returned to controlblock 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
should be issued to assign the appropriate physical device-unit to the
desired logical unit number.
For example, to assign the logical unit
number (lun parameter) in the GCMLB$ macro call (see Section 6.l.l) to
a terminal, the following Task Builder directive should be issued:
ASG

= TI:l

The designation TI:
is a pseudo-device name that is redirected to the
command-input device. Note that the numeric value following the colon
(:) must agree with the numeric value specified as the lun parameter
in the GCMLB$ macro call.
The ASG directive is described in further detail in the
Reference Manual of the host operating system.

Task

Builder

As discussed in Section 2.6.1 on FSRSZ$, at any given time there must
be an FSR block buffer available for each file currently open for
record I/O operations. The block-buffer requirements of the command
file must be considered when issuing the FSRSZ$ macro.

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

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

COMMAND-LINE PROCESSING
6.2.1

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

iDEFINES CSI CONTROL BLOCK OFFSETS
iAND BIT VALUES LOCALLY.
iWORD ALIGNS CSI CONTROL BLOCK •
iNAMES CSI CONTROL BLOCK AND
iALLOCATES REQUIRED STORAGE.

The CSI$ macro is strictly definitional
in nature and does not
generate any executable code. The CSI control block resulting from
the .BLKB directive serves as a means of communication between CSI and
the calling program. The length of the control block is specified by
the symbol C.SIZE, which is defined during the expansion of the CSI$
macro.
The expansion of this macro also results in the local
definition of the symbolic offsets and bit values within the CSI
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:
CSI$

6.2.2

DEF$G

CSI Control-Block Offset and Bit-Value Definitions

The CSI$ macro call causes the following symbolic offsets
values within the CSI control block to be defined locally:
OFFSET
NAME
C.TYPR

and

bit

FUNCTIONAL SIGNIFICANCE
This byte field
Command String Request Type.
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.

C.STAT

file

specifier

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 CSII
and CSI2.
6-14

COMMAND-LINE PROCESSING

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 comma indicates
that more file specifiers are to follow.
If this
bit is not set, it signifies that the end of the
input or output file specifiers has been reached.
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
these cells constitute the output of CSI after
scanning
a
file specifier and removing all
nonsignificant characters from the string
(i.e.,
nulls, blanks, tabs, and RUBOUT's).
The values contained in these cells are used by
CSI as the descriptors of the compressed command
line to be parsed (see CSI$2 macro call in Section
6.2.3.2).

6-15

COMMAND-LINE PROCESSING

C.DSDS

Dataset Descriptor Pointer. This offset defines
the address of the 6-wo~d dataset descriptor in
the CSI control block.
This
structure
is
functionally identical to the manually created
dataset descriptor detailed in Section 2.4.1.
This symbol may be used to initialize offset
location F.DSPT in the FDB associated with the
file to be processed.
Thus, FCS is able to
retrieve requisite ASCII
information from this
structure for use in opening files.
Assembly-time initialization of F.DSPT in the
associated FDB may be accomplished as follows:
FDOP$A

1,CSIBLK+C.DSDS

where CSIBLK is the address of the CSI control
block, and C.DSDS represents the beginning address
of the descriptor strings in the CSI control block
(see C.DEVD, C.DIRD, and C.FILD below) identifying
the requisite ASCII filename information.
Run-time
initialization
of
F.DSPT
in
the
associated FDB may also be accomplished through
the dspt parameter of the FDOP$R macro call
(see
Section 2.2.2)
or the generalized OPEN$x macro
call (see Section 3.1).
C.DEVD

Device-Name String Descriptor. This 2-word field
contains the address (C.DEVD+2) and the length in
bytes (C.DEVD)
of the most recent device-name
string
(of like request type) encountered in a
file specifier.

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.

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

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 ORled into this location.

6-16

COMMAND-LINE PROCESSING
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.MKWI 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 ORled into C.MKW2 in the same
manner as described above for C.MKWI.
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$l

- 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.2.3.1 CSI$1 - Command Syntax Analyzer - The CSI$l
macro
call
results in the invocation of a routine called the command syntax
analyzer. This routine analyzes a command line
(which is normally
read into the GCML command-line input buffer)
and checks it for
syntactic validity.
In addition, it compresses the file specifiers in
the command line by removing all nonsignificant characters (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, directory, and filename strings during
successive issuances of the CSI$2 macro call (see next section).
6-17

COMMAND-LINE PROCESSING

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
buffer.
This
parameter
initializes
CSI
control-block offset location C.CMLD+2, enabling
CSI to retrieve the current command line from a
command-line input buffer.
If this parameter is not specified, 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.
Similarly, 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 CSI control block
(see Section
6.2.2)
are set to values that define the address and the length,
respectively, of the command-line segment in error.
Examples of the CSI$1 macro call follow:
CSI$1

#CSIBLK,#BUFF,#LEN

CSI$1

RO,GCLBLK+G.CMLD+2,GCLBLK+G.CMLD

CSI$1

#CSIBLK

The first example shows symbols that represent the address and the
length of a command line to be analyzed (not necessarily the line
contained in the GCML command-line input buffer).

6-18

COMMAND-LINE PROCESSING
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 t~e 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
where:

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:
INPUT - Indicates that the
file
next
input
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.
Offset location C.TYPR in the CSI 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.

6-19

COMMAND-LINE PROCESSING
swtab

represents the address of the associated switch
descriptor table for this particular issuance of
the CSI$2 macro call.
This optional parameter
need oe 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).
This parameter initializes offset location C.SWAD
in the CSI 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:
1.

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.

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

6-20

COMMAND-LINE PROCESSING
The first example shows a request to parse an input file specifier,
which may include an associated switch. The second example, which
assumes that RO presently contains the address of the CSI control
block, parses an output file specifier that 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, respectively.
These macro calls are described separately in the following sections.

6.2.4.1 CSI$SW - Create Switch Descriptor Table Entry - To process
each switch that the user expects to encounter in a file specifier, a
matching entry in the switch descriptor table must be defined.
When
the address of a switch descriptor table is specified in any
particular issuance of the CSI$2 macro call (see Section 6.2.3.2), the
following processing occurs:
1.

For each switch encountered in a file specifier, CSI searches
the switch descriptor table for a matching entry.
If the
switch descriptor table address is not specified, or a
matching entry is not found in the table for the switch, that
switch is considered to be invalid. As a result,
the C-bit
in the Processor Status Word is set, any remaining switches
in the file specifier are bypassed, and control is returned
to the calling program.

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

The negation status of the switch is determined.
If the
switch is not negated, the corresponding bits in mask word 2
(C.MKW2) in the CSI control block are set according to the
defined mask for that switch.
If the switch is negated, and
negation is not allowed, then the switch is considered to be
invalid.
In this case, the error sequence described in Step
1 above applies.
However, if the switch is negated,
and
negation is allowed,
then the corresponding bits in C.MKW2
are cleared.
The negation flag for a switch is established through
nflag parameter of the CSI$SW macro call (see below).

6-21

the

COMMAND-LINE PROCESSING
4.

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 I again applies.
The address of the switch-value descriptor table is specified
as the vtab parameter in the CSI$SW macro call (see below).

The CSI$SW macro call is specified in the following format:
label:
where:

CSI$SW

sw,mk,mkw,csflg,nflg,vtab,compflg

label

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
CSI$SW macro call issued in the program must
include a label. This label allows the table to
be referenced by other instructions
in
the
program.

represents the alphabetic switch name to be stored
in the switch descriptor table. This name may
comprise any number of characters.
(For RSX-IID,
this name may comprise only two characters.) CSI
compares the name entered on the command line with
this
switch name, as entered in the switch
descriptor table. The method CSI 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.

6-22

COMMAND-LINE PROCESSING

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

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.MKWI.
mkw

represents the address in user program storage of
a mask word that CSI changes each time it changes
C.MKWI.
CSI stores the same value into this mask
word that it stores into C.MKWI. 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.
Such an optional word may be reserved through a
statement
logically equivalent to that shown
below:
MASKX:

csflg

.WORD

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

6-23

COMMAND-LINE PROCESSING
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 CSI to decode any
switch values accompanying the switch, provided
that an associated switch descriptor table entry
has
been
defined
for
that
switch.
The
switch-value descriptor table is defined through
the CSI$SV macro call, as described in the next
section.

compflg

specifies the method CSI uses to compare the
switch name entered on the command line with the
value entered in the switch descriptor table via
the
sw
parameter.
(This parameter is not
supported for RSX-IID.) Either LONG or EXACT may
be specified.
The default value is entered if a
value is not coded.
Default - If the parameter is not coded, only the
first 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.
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

6-24

COMMAND-LINE PROCESSING

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 1 indicates
that the next word contains more switch name characters. A sign bit
set to 0 indicates the last word containing switch-name characters.
If the number of characters in the switch name is odd, the high-order
byte of the last word contains zeros and is ignored by CSI.
The sign bit of the first bite 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 1 in the low-order bit of the user mask word
a bit setting of 0 indicates the SET
indicates the CLEAR function:
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.

0
char2

char1

char4

char3

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

iEND OF SWITCH DESCRIPTOR TABLE.

The first statement results in the creation of an entry in the switch
descriptor table for
the switch JAS.
The second parameter is an
equated symbol that defines the switch mask, and the third parameter

6-25

COMMAND-LINE PROCESSING
(MASKX) is the ~ddress 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.
The CSI$SV macro call is specified in the following format:
CSI$SV
where:

type

type,adr,len,vtab
represents a symbolic argument that specifies the
conversion type for the switch value. Anyone 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 is
to be converted to binary using octal as a default
conversion radix.
OCTAL - Indicates that a numeric switch value is
to be converted to binary using octal as a default
conversion radix.
DECIMAL - Indicates that a numeric switch value is
to be converted to binary using decimal as a
default conversion radix.
If any value other than those defined above is
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.

6-26

COMMAND-LINE PROCESSING
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.

len

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.

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.

The format of a switch-value descriptor table entry that results
the CSI$SV macro call is shown in Figure 6-3 below.

from

The low-order byte of the first word in the switch-value descriptor
table indicates whether the conversion type is ASCII or numeric. The
low-order byte of this word is set to 1 if ASCII is specified;
it is
set to 2 if NUMERIC or OCTAL is specified;
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.
A numeric switch value is always
evaluated as a signed number;
an overflow into the high-order bit
(Bit 16) results in an error condition.
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).

6-27

COMMAND-LINE PROCESSING

Switch Value Length

Conversion Type

Address of Location Receiving Switch Result

Figure 6-3

Format of Switch-Value Descriptor Table Entry

Representative CSI$SV macro calls are shown below:
ASVTBL: CSI$SV
CSI$SV

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

CSI$ND
NUVTBL: CSI$SV
CSI$SV

;END OF SWITCH VALUE TABLE.
OCTAL,NUVAL,2
DECIMAL,NUVAL+2,2
iEND OF SWITCH VALUE TABLE.

CSI$ND

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

iASCII VALUE STORAGE.

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

above

iNUMERIC 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
I-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-28

use

CHAPTER 7
THE TABLE-DRIVEN PARSER (TPARS)

TPARS is a table-driven parser designed to parse command lines. TPARS
provides the means to define a unique syntax and, using TPARS-supplied
macros, built-in variables, and 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-1

THE TABLE-DRIVEN PARSER (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 ISTAT$ 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 pro ram
s a so provl e
or 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
where:
statetable is the label the user assigns to the state
equates this label to the start of the state table.

table.

TPARS

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

table.

TPARS

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
ISTAT$ statetable,keytable

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

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:
$ANY

Matches any single character.

$ALPHA

Matches any single alphabetic character (A-Z).

$DIGIT

Matches any single digit (0-9).

$LAMDA

Matches an empty string.
This transition is always
successful.
LAMDA 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
IX are valid and,
in fact,
recommended.

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 ~ontrol to a
subexpression.
For
information
on
TPARS
subexpressions, refer to Section 7.1.4.

7-4

The

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 userls 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
$DNUMB
syntax type

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

.PFLAG

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

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 striQg
does not include the characters matched by the current
transition.

$ALPHA,

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

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

7-5

THE TABLE-DRIVEN PARSER (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.4

TPARS Subexpressions

A TPARS subexpression is a series of states and transitions analogous
to a subroutine. In general, such a series of states and transitions
is used more than once during the parsing process.
Subexpressions begin with a STATE$ macro specifying the label of the
subexpression.
This macro is followed by the states and transitions
that comprise the body of the subexpression.
To terminate the
subexpression, specify a 'fRAN$ 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
TPARS then directs control to the STATE$ macro with the label UIC:
STATE$
TRAN$ '[

DIC

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

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

Suggested Arrangement of Syntax Types in a State Table

The transitions in a state may represent several syntax types;
a
portion of a string being scanned often matches more than one syntax
type. Therefore, the order in which the types are entered in the
state table is critical. Transitions are always scanned in the order
in which they are entered and the first transition matching a string
being scanned is the transition taken. Therefore, the following order
is recommended for states containing more than one syntax type:

7-6

THE TABLE-DRIVEN PARSER (TPARS)
char
keyword
$EOS
$ALPHA
$DIGIT
$BLANK
$NUMBR
$DNUMB
$STRNG
$RAD50
$ANY
$LAMDA
Placement of !label transitions in a state depends on the types and
positions of other syntax types in the state as well as on the syntax
types in the starting state of the subexpression.

7.2.2

Entering Special Characters

In "char" syntax elements, MACRO-II interprets commas (,),
semicolons
(;), and angle brackets
«
>) as special characters. The comma is
interpreted as an argument separator and angle brackets are used to
parenthesize special characters.
To include a comma or a semicolon in a "char" syntax
use angle brackets:

element

string,

TRAN$ <',>
Angle brackets cannot be passed as string elements in macro arguments.
If
required
in
a
"char" expression,
they must be expressed
symbolically, for example:
LA = '<
TRAN$ LA

7.2.3

Ignoring Blanks and Tabs in a Command Line

Bit zero of the low byte of Register I
(RI)
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.

7-7

THE TABLE-DRIVEN PARSER (TPARS)
In the first example, an extra state is required to parse the blank:
STATE$
TRAN$

$STRNG

STATE$
TRAN$

$BLANK

STATE$
TRAN$

$STRNG

When TPARS is directed to ignore blanks and tab characters,
string can be parsed using only two states:

the

same

STATE$

7.3

'l'RAN$

$STRNG

STATE$
TRAN$

$STRNG

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:

Flags

Type

Type Extension
Action Return Address
Maskword
Maskword Address
Target State Label

The type byte of the first word may contain the following values:
$LAMDA
$NUMBR
$STRNG
$BLANK
$SUBXP
$EOS
$DNUMB
$RADSO
$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)
7-8

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

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.

1
2
3
4
7

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 by means of the instruction:
CALL .TPARS

7.4.1

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

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 un scanned 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
7.6.1.

7.4.2

sequence

for

TPARS,

refer

Section

Using the Options Word

The low byte of the options word contains flag bits.
The only flag
bit defined is bit zero, which controls processing of blanks.
If bit
zero is set to 1, blanks are interpreted as syntax elements.
If bit
zero is set to 0, blanks are ignored as syntax elements.

7-9

THE TABLE-DRIVEN PARSER (TPARS)
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 ale no syntax elements in the current
state that match the portion of the string being scanned.
Illegal
type codes and errors in the state table can also cause a syntax
error.
TPARS processing requires that the addresses in the state table and
the keyword tables be reliable;
bad addresses may cause program
termination.
The only syntax types that can match the end of the
and $LAMDA.

7.4.3

string

are

$EOS

Storage Requirements

The routine .TPARS is 253 words long.
In addition,
. TPARS calls
routines
.OD2CT and
.DD2CT, which use an additional 68 words of
storage.

7.5

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, ISTAT$, 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 an appropriate volume
for future use.
The assembly listing produced by the state table macros is not
straightforward.
The source language macros are designed for clarity
and convenience in writing state tables;
the object code is designed
for
compactness and processing convenience.
As a result,
the
mechanism used to translate the source code to object code is not a
simple one.
The binary output of the macros is delayed by one statement. Thus, if
the listing of macro-generated binary code is enabled, the binary code
appearing after a macro call is, in fact, the result of the preceding
macro call.
Error messages generated by macro calls are similarly
delayed. This is the reason an additional STATE$ macro is required to
terminate the state table.
7-10

THE TABLE-DRIVEN PARSER (TPARS)
PARSER.SRC

EOI

1.
-----~

Write a source program that
includes the required MCALL
statements.

-:>

MCALL ISTAT$
MCALL STATE$
MCALL TRAN$
STATE$

STATE$

PARSER.OBJ
MACRO-11

2.
PARSER.SRC

Assemble the source program to
produce an object module.

TKB

PARSER.OBJ

MYFILE.TSK
3.
MYFILE.OBJ

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

UPOATE.OBJ

Figure 7-1

Processing Steps Required to Generate a Parser
Program Using TPARS

7-11

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

TPARS
Processor

User-defined
Parser Program

r---.

STATE$
*
*
*

r--,

I
I

I
I
I
.J

STATE$

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

Figure 7-2

Action
Routines

r-~

I
I
.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 the 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-IIM.
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=lOO./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-12

following

THE TABLE-DRIVEN PARSER (TPARS)

The label and the IALLOC and IPRO switches are optional.
sequence for this routine is as follows:
CLR
MOV
MOV
MOV
MOV
CALL
BCS

Rl
#UFDUTB,R2
COUNT,R3
ADDR,R4
#START,R5
. 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, , SETDVl

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
IUIC

READ Ule

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

OPTS
$EOS,$EXIT

'I
II

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

7-13

The

calling

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

ALC

'=
$NUMBR,OPTS,SETALC

PROTECTION
STATE$
TRAN$

PRO

STATE$
TRAN$

, [ , ,IGROUP

STATE$
TRAN$
TRAN$
TRAN$
TRAN$
TRAN$
TRAN$

SPRO
'] ,OPTS,ENDGRP
<' ,>,SPRO,NXGRP
'R,SPRO,SETRP
'W,SPRO,SETWP
'E,SPRO,SETEP
'D,SPRO,SETDP

SUBEXPRESSION TO READ AND STORE UIC
STATE$
TRAN$

UIC

STATE$
TRAN$

$NUMBR"SETGN

STATE$
TRAN$

< >

STATE$
TRAN$

$NUMBR"SETPN

STATE$
TRAN$

'],$EXIT

STATE$
STATE TABLE SIZE: 60 WORDS
KEYWORD TABLE SIZE:
8 WORDS
KEYWORD POINTER SPACE:
3 WORDS
.SBTTL

ACTION ROUTINES FOR THE COMMAND LINE PARSER

; DEVICE NAME CHAR 1
SETDV1::MOVB

.PCHAR,$UDEV
RETURN

; DEVICE NAME CHAR 2
SETDV2: : MOVB

.PCHAR,$UDEV+1
RETURN

; UNIT NUMBER
SETUNT: : MOV

.PNUMB,$UUNIT
RETURN

7 ... 14

THE TABLE-DRIVEN PARSER (TPARS)

; VOLUME LABEL
SETLAB: : MOV

• PSTCN, $UVNML
MOV
.PSTPT,$UVNAM
RETURN

; PPN - GROUP NUMBER
SETGN: :

MOVB
BR

.PNUMB,$UUIC+1
TSTPPN

; PPN - PROGRAMMER NUMBER
SETPN: :
TSTPPN:

10$:
20$:

MOVB
TST
BNE
TSTB
BEQ
ADD
RETURN

.PNUMB,$UUIC
.PNUMH
10$
.PNUMB+1
20$
#2, (SP)

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

; NUMBER OF ENTRIES TO ALLOCATE
SETALC: : MOV

.PNUMB,$UALL
RETURN

SET PERMISSIONS
INITIALIZE
#4,GRCNT

IGROUP::MOV

; MOVE TO NEXT PERMISSIONS CATEGORY
NXGRP: :

BADGRP:
30$:

SEC
ROR
ASR
ASR
ASR
DEC
BGE
ADD
RETURN

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

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

; SET READ PERMIT
SETRP: :

BIC
RETURN

#FP.RDV*10000,$UPRO

BIC
RETURN

#FP.WRV*10000,$UPRO

; SET WRITE PERMIT
SETWP: :

; SET EXTEND PERMIT
SETEP::

BIC
RETURN

#FP.EXT*10000,$UPRO

; SET DELETE PERMIT
SETDP: :

BIC
RETURN

#FP.DEL*10000,$UPRO

7-15

THE TABLE-DRIVEN PARSER (TPARS)
; END OF PROTECTION SPEC
ENDGRP::TST

7.6.2

GRCNT
BNE
RETURN

; CHECK THE GROUP COUNT
BADGRP
; MUST HAVE 4

.END

UFD

Bow 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
programmlng 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-16

REJECT TRANSITION ON MATCH

THE TABLE-DRIVEN PARSER (TPARS)
; STORE THE STRING DESCRIPTOR
SETST:

MOV
MOV
RETURN

.PSTPT,QSTP
.PSTCN,QSTC

; RESET THE SPACE FLUSH FLAG
DECB
RETURN

RESET:

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

!ONUMB,NEXT,SETNUM
!DNUMB,NEXT,SETNUM

SUBEXPRESSION TO ACCEPT OCTAL NUMBER
STATE$
TRAN$

ONUMB
$NUMBR

STATE$
TRAN$

"OCTAL",$EXIT

SUBEXPRESSION TO ACCEPT DECIMAL NUMBER

;

STATE$
TRAN$

DNUMB
$DNUMB

STATE$
TRAN$

"DECIMAL",$EXIT

ACTION ROUTINE TO STORE THE NUMBER

SETNUM:

MOV
MOV
RETURN

.PNUMB,NUMBER
.PNUMH,NUMBER+2

7-17

The

TBETABLE-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 subexpression is encountered in a transition, TPARS saves its
current context and calls itself, using the label of the subexpression
as the starting state. If the subexpression parses successfully and
returns via $EXIT, the transition is taken and control passes to the
next state.
If the subexpression encounters a syntax error, TPARS restores
saved context and tries to take the next transition in the state.

the

However, TPARS provides no means for resetting orlglnal values changed
by action routines called by subexpressions.
Therefore, action
routines called from subexpressions should store results in an
intermediate area.
Data in this intermediate area can then be
accessed by an action routine called from the primary level of the
state table.

7-18

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 FeS

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-I1M.
dev

represents the 2-character device mnemonic of the
device on which the file is to be printed.
If dey 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
o is used by default.

The following parameters are used only by the lAS and RSX-llD multiple
device despoolers. See the discussion below.
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.

forms

represents the specific form-type on which the file
is
to be printed as indicated by a number in the range 0
through 6. This parameter must be specified as a
single integer without a preceding number sign (#).
The numbers 0 through 6 are associated with the various
forms for an installation by the system manager.
If
forms is omitted, form-type 0 is used by default.
8-1

SPOOLING
copies

represents a number in the range 1 through 32 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.

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.

The following points do not apply to RSX-IIM.
1.

A blank parameter is present between err and dev,
thus
requiring an additional comma.
This parameter exists to
provide compatibility between RSX-IID Version 4 and RSX-IID
Versjon 6.

The number of parameters that are meaningful for RSX-IID is
determined by whether the single-device despooler or the
multiple-device despooler is available in the system.
The
difference between the two despoolers is described in the
RSX-IID User's Guide and the RSX-IID System Manager's Guide.
In lAS, only the multiple-device despooler is supported.
This is described in the lAS System Management Guide.
The
following
parameters
are
used by the multiple-device
despooler and ignored by the single-device despooler.
pri
forms
copies
presrv

8.2

.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.
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 1S 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 (FDB) contains file information that is used
by FCS and the file control primitives. The layout of an FDB is
illustrated on the following page;
Table A-I 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 FDB locations, it is essential to
use the symbolic offset names, rather than the actual
address of
such
locations.
The
position
of
information within the FDB may be subject to change
from release to release, whereas the offset names
remain constant.
File-Attribute Section

F.RATT

F.RTYP

F.RSIZ
F.HIBK
F.EFBR
F.FFBY

Record- or Block-Access
Section

F.RCTL

F.RACC

F.BRDS or F.URBD
F.NRBD or

F.BRST and F.BRDN
F.OVBS or F.NREC
F.EOBB
F.RCNM or
F.CNTG and F.STBR

A-I

FILE DESCRIPTOR BLOCK
File-Open Section

F.ALOC
F.LUN

F.FACC
F.DSPT
F.DFNB
Block-Buffer Section

F.EFN or F.BKEF

F.BKPI
FERR+I

F.ERR

F.MBCI

F.MBCT

F.BGBC

F.MBFG

F.VBSZ
F.BBFS
F.BKVB or F.VBN
F.BDB
F.SPDV
F.SPUN

F.CHR
F.ACTL
F.SEQN
F.FNB
Table A-I
FDB Offset Definitions
OFFSET

F.RTYP

SIZE
(in bytes)
I

CONTENTS

Record-type byte.
This byte is set, as
follows, to indicate the type of records for
the file:
F.RTYP = I to indicate fixed-length records
(R.FIX) •
F.RTYP = 2
to
indicate
variable-length
records (R.VAR).
F.RTYP = 3 to indicate sequenced records
(R.SEQ) •

F.RATT

Record-attribute byte. Bits 0 through 3 are
set
to
indicate record attributes, as
follows:
Bit 0 = I to indicate that the first byte of
a
record
is
to
contain
a
FORTRAN
carriage-control
character
(FD.FTN)i
otherwise, it is O.
(continued on next page)
A-2

FILE DESCRIPTOR BLOCK
Table A-I
(Cont.)
FDB Offset Definitions
OFFSET

SIZE
(in bytes)

CONTENTS

Bit I = I 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 = I 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.EFBK

Contains the end-of-file block number.

F.FFBY

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

F.RACC

Record access byte.
Bits 0 through 3 of
this byte define the record-access modes, as
follows:

virtual-block

number

Bit 0 = I to
indicate READ$/WRITE$
mode
(FD.RWM);
otherwise,
it
is 0 to indicate
GET$/PUT$ mode.
Bit I = I
to
indicate random-access mode
(FD.RAN)
for
GET$/PUT$
record
I/O:
otherwise, it is 0 to
indicate sequential
access mode.
Bit 2 = I to indicate locate mode
(FD.PLC)
for
GET$/PUT$ record I/O;
otherwise, it is
o to indicate move mode.
Bit 3 = I to indicate that PUT$ operation in
sequential mode does not truncate the file
(FD.INS);
otherwise, it is
0 to
indicate
that
PUT$ operation in sequential mode
truncates the file.
(continued on next page)

A-3

FILE DESCRIPTOR BLOCK
Table A-I
(Cont.)
FDB Offset Definitions
OFFSET

F.RCTL

SIZE
(in bytes)
I

CONTENTS

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

a record-oriented
a Teletype or line

; nd i ~;:d-AC::

e.g.,

disk

::.

Bit I = I to indicate a carriage-control
device (FD.CCL);
otherwise, it is O.
Bit 2 = I to indicate a teleprinter
(FD.TTY); otherwise, it is o.

device

Bit 3 = I to indicate a directory
(FD.DIR); otherwise, it is o.

device

Bit 4 = I
to indicate a single-directory
device
(FD.SDI).
An MFD is used, but no
UFD's are present.
Bit 5 = I 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.BKDS
or
F.URBD

F.NRBD
or
F.BKST
and

Contains the next record-buffer descriptor.

Contains the address of the I/O status block
for block I/O.

F.BKDN

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

Contains a value defining
buffer.

Contains the block-I/O-buffer descriptor.
Contains the user-record-buffer descriptor.

the

AST

service

record

end-af-block

(continued on next page)

A-4

FILE DESCRIPTOR BLOCK
Table A-I
(Cont.)
FOB Offset Definitions
OFFSET

SIZE
(in bytes)

F.RCNM
or

Contains the number of the record for random
access operations.

F.CNTG

Contains a numeric value defining the number
of blocks to be allocated in creating a new
file. This cell has meaning only before the
file is opened. A value of 0 means leave
the file empty;
a positive value means
allocate the specified number of blocks as a
contiguous
area
and
make
the
file
contiguous;
a negative value means allocate
the specified number of
blocks
as
a
noncontiguous
area
and
make the file
noncontiguous.

F.STBK

Contains the address of the statistics block
in the user program.

F.ALOC

Contains the number of
blocks
allocated when the file must be
This cell has meaning only before
is opened.
A positive (+) value
contiguous extend, and a negative
indicates noncontiguous extend.

to
be
extended.
the file
indicates
(-)
value

F.LUN

Contains the logical unit number
with the FOB.

associated

F.FACC

File-access byte. This byte indicates the
access privileges for a file, as summarized
below:

CONTENTS

Bit 0 = I if the file is accessed
only (FA.RD).

for

read

Bit I = I
if the
writing (FA.WRT).

file

accessed

for

Bit 2 = I
if the
extending (FA. EXT) .

file

accessed

for

Bit 3 = I if a new file
is being created
(FA.CRE); otherwise, it is 0 to indicate an
existing file.
Bit 4 = I if the file is
(FA.TMP) .

temporary

Bit 5 = I if the file is opened
access (FA.SHR).

for

file
shared

If Bit 3 above is 0:
(continued on next page)
A-5

FILE DESCRIPTOR BLOCK

Table A-I
(Cont.)
FOB Offset Definitions
OFFSET

SIZE
(in bytes)

CONTENTS

Bit 6 = I
if an existing
appended (FA.APD).

file

being

If Bit 3 ,above is one (I):
Bit 6 = I 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.BKPI

Contains bookkeeping bits for
control.

F.ERR

Error return code byte.
A negative
indicates an error condition.

F.ERR+I

Used in conjunction with F.ERR above.
If
F.ERR is negative, the following applies:

Contains the record I/O event flag.
FCS

internal

value

F.ERR+I = 0 to indicate that error code is
an I/O error code (see IOERR$ error codes in
Appendix I).
F.ERR+I = 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.MBCI

Indicates the actual
currently in use.

F.MBFG

Multiple-buffering flag
word.
Contains
either one of the multiple buffering flags,
as follows:

number

used

buffers

Bit 0 = I to indicate read-ahead (FD.RAH).
Bit I

I to indicate write-behind (FD.WBH).
(continued on next page)
A-6

FILE DESCRIPTOR BLOCK

Table A-I
(Cont.)
FDB Offset Definitions
OFFSET

SIZE
(in bytes)

CONTENTS

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.BKVB
or

Contains the address of the virtual-block
number in the user program for block I/O.

F.VBN

the

Contains the virtual-block number.

F.BDB

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.

F.SPDV

Spooler output device designation
RSX-IID only) .

(lAS

and

F.SPUN

Spooler output
RSX-IID only) .

(lAS

and

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.

unit

designation

The control bits are in the high-order
and are defined as follows.
Bit 15 = 1
information
(FA. ENB) .

byte

to specify that control
is to be taken from F.ACTL

Bit 12 = 0 to cause positioning to the
end of a magnetic tape volume set upon
open or close.
Bit 12 = 1 to cause positioning of a
magnetic tape volume set to just past
the most recently closed file when the
next file is opened (FA.POS).
(continued on next page)

A-7

FILE DESCRIPTOR BLOCK
Table A-I
(Cont.)
FDB Offset Definitions
OFFSET

SIZE
(in bytes)

CONTENTS

Bit 11 = 1 to cause a magnetic tape volume
set
to be rewound upon open or close
(FA.RWD) .
Bit 9 = 1 to cause a file not to be locked
if it is not properly closed when accessed
for write (FA. DLK) .
F.SEQN

Contains the sequence number
records.

F.FNB

Defines the beginning
address
filename-block portion of the FDB.

A-8

for

sequenced

the

APPENDIX B

FILENAME BLOCK

The format of a filename block is illustrated in Figure B-1.
offsets within the filename block are described in Table B-1.
The offset names in a filename block may be defined either locally
globally, as shown below:
NBOF$L

The
or

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

SIZE
(in bytes)

CONTENTS

N.FID

File-identification field.

N.FNAM

Filename field:
specified as 9 characters
that are stored in Radix-50 format.

N.FTYP

File-type field:
specified as 3 characters
that are stored in Radix-50 format.

N.FVER

File version number field

N.STAT

Filename-block
status
word
definitions in Table B-2).

N.NEXT

Context for next .FIND operation.

N.DID

Directory-identification field.

N.DVNM

ASCII device-name field.

N.UNIT

Unit-number field (binary).
B-1

(binary).
(see

bit

FILENAME BLOCK

The bit definitions of the filename-block status word (N.STAT) in
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.

0
N.FID

2
4
6

N.FNAM

10
12

N.FTYP
N.FVER

14
16

N.STAT

CUMULATIVE
LENGTH IN
BYTES (OCTAL)

20
N.NEXT

N.DID

22
24
26
30·

N.DVNM
N.UNIT

32
34

Figure B-1

Filename-Block Format

Table B-2
Filename-Block Status Word (N.STAT)
SYMBOL

VALUE
(in octal)

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.

NB.SVR

Set if wildcard file version
specified.

number

(continued on next page)

B-2

FILENAME BLOCK
Table B-2
(Cont.)
Filename-Block Status Word (N.STAT)
SYMBOL

VALUE
(in octal)

MEANING

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.

UIC

contains

NB.SD2

1000

Set if owner portion of
wildcard specification.

UIC

contains

B-3

string

device-name

(UIC)

string

APPENDIX C
SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES

Table C-l 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-l
Summary of I/O-Related System Directives
DIRECTIVE
ALUN$

FUNCTION AND PARAMETERS
Assigns a logical unit number to a physical device:
lun

= Logical unit number.

dev = Physical device name (2 ASCII characters).
unt
GLUN$

Physical device-unit number.

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 aO-byte MCR/PDS
issuing task.
No parameters
directive.

QIO$

Places an I/O request in the device queue
with the specified logical unit number:
fnc

= I/O function code.

lun

= Logical unit number.

efn

= Event flag number.

the

command line
are required

LUN

to the
in this

associated

pri = Priority of the request (lAS and RSX-llD only).
(continued on next page)

C-l

SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES

Table C-l
(Cont.)
Summary of I/O-Related System Directives
DIRECTIVE

FUNCTION AND PARAMETERS

ast

= Address of the I/O status block.
= Entry-point address of the AST service

prl

= Parameter list in the form .

isb

RCVD$

Receives a 13-word data
~~7

(PTP()'

::;c. •• d -dQ'-Cl

routine.

block that has been aueupn
d.ireCl:IVe -(see SDAT$ and SDRQ$

below) .
tsk = Name of the sending task. This field is ignored
by RSX-IIM. The tsk parameter is specified as a
null value (,) i~ RSX-IIM for compatibility with
lAS and RSX-llD (see the description of the RCVD$
directive in the RSX-IlM Executive Reference
Manual) .
buf

RCVS$

Address of the IS-word data buffer
(2-word
sending task name and 13-word data block).

Receives a 13-word data block, if queued by a send-data
directive (see SDAT$ AND SDRQ$ below), or suspends task
if no data is queued:
tsk = Name of the sending task.
buf

= Address

of the IS-word data buffer
(2-word
sending task name and 13-word data block).

This directive is not supported in RSX-IIM.
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

buf

= Address

of the sending task.
This field is ignored
by RSX-IIM. The tsk parameter is specified as a
null value (,) in RSX-IIM for compatibility with
lAS and RSX-IID (see the description of the RCVX$
directive in the RSX-IIM Executive Reference
Manual) .
of the IS-word data buffer
(2-word
sending task name and 13-word data block).
SDAT$ Queues (FIFO) a 13-word block of data for a
task to receive:
tsk

= Name

of the receiving task.

buf = Address of the 13-word data buffer.
efn = Event flag number.
(continued on next page)
C-2

SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES
Table C-I (Cont.)
Summary of I/O-Related System Directives
DIRECTIVE
SDRQ$

FUNCTION AND PARAMETERS
Queues (FIFO) a 13-word block of data for a task to
receive; also requests or resumes the execution of the
receiving task:

pri

= Name of the receiving task.
= Partition name of the receiving
= Priority of the request.

ugc

tsk
par

task.

UIC group code.

upc = UIC owner code.
buf

= Address

of the 13-word data buffer.

efn = Event flag number.
This directive is not supported in RSX-IIM.

C-3

APPENDIX D

SAMPLE PROGRAMS

The sample programs that follow read records from an input device,
strip off any blanks to the right of the data portion of the record,
and write the data record on an output device. While the programs are
intended primarily for card reader input and printer output, device
independence is maintained.
The main program is CRCOPYi 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.
iCARD 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 FINIT$
INLUN=3
iASSIGN CR OR FILE DEVICE
OUTLUN=4
iASSIGN TO OUTPUT DEVICE
FSRSZ$ 2
FDBOUT: FDBDF$
iALLOCATE SPACE FOR OUTPUT FDB
FDAT$A R.VAR,FD.CR
iINIT FILE ATTRIBUTES
FDRC$A ,RECBUF,80.
iINIT RECORD ATTRIBUTES
iINIT FILE OPEN SECTION
FDOP$A OUTLUN"OFNAM
iALLOCATE SPACE FOR INPUT FDB
FDBIN:
FDBDF$
iINIT RECORD ATTRIBUTES
FDRC$A ,RECBUF,80.
FDOP$A INLUN, ,IFNAM
iINIT FILE OPEN SECTION
iRECORD BUFFER
80 •
RECBUF: . BLKB
iOUTPUT FILENAME
OFNAM: NMBLK$ OUTPUT,DAT
iINPUT FILENAME
IFNAM: NMBLK$ INPUT,DAT
START: FINIT$
iINIT FILE STORAGE REGION
OPEN$R #FDBIN
iOPEN THE INPUT FILE
BCS
ERROR
iBRANCH IF ERROR
OPEN$W #FDBOUT iOPEN THE OUTPUT FILE
BCS
ERROR
iBRANCH IF ERROR
GTREC: GET$
#FDBIN
iNOTE - URBD IS ALL SET UP
iERROR SHOULD BE EOF INDICATION
BCS
CKEOF
MOV
F.NRBD{RO) ,Rl
iRl=SIZE OF RECORD READ
MOV
#RECBUF,R2
ADD
Rl,R2
iR2=ADDRESS OF LAST BYTE+l
CMPB
#40,-{R2)
iSTRIP TRAILING BLANKS
10$:
BNE
PTREC
SOB
Rl,lO$
iAT THIS POINT, Rl CONTAINS THE STRIPPED SIZE OF THE
iRECORD TO BE WRITTEN.
IF THE CARD IS BLANK,
iA ZERO-LENGTH RECORD IS WRITTEN.
PUT$
#FDBOUT"Rl
iRl IS NEEDED TO SPECIFY
PTREC:
BCC
GTREC
iTHE RECORD SIZE.
ERROR: NOP
iERROR CODE GOES HERE
CKEOF: CMPB
#IE.EOF,F.ERR{RO) iEND OF FILE?
BNE
ERROR
iBRANCH IF OTHER ERROR
CLOSE$ RO
iCLOSE THE INPUT FILE

D-1

SAMPLE PROGRAMS
BCS
CLOSES
BCS
EXIT$S
.END

ERROR
#FDBOUT
ERROR

iCLOSE THE OUTPUT FILE
iISSUE EXIT DIRECTIVE

START

.TITLE CRCOPA
iCARD READER COpy ROUTINE
• MCALL FDBDF$,FDAT$A,FDRC$A,FDOP$A,NMBLK$,FSRSZ$
.MCALL OPEN$R,OPEN$W,GET$,PUT$,CLOSE$,EXIT$S
• MCALL FINIT$
INLUN=3
iASSIGN CR OR FILE DEVICE
OUTLUN=4
iASSIGN TO OUTPUT DEVICE
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.
CFDSPT: .WORD
0,0
iDEVICE DESCRIPTOR
. WORD
0,0
iDIRECTORY DESCRIPTOR
. WORD
ONAM$Z,ONAM
iFILENAME DESCRIPTOR
IFDSPT: .WORD
0,0
iDRVICE DESCRIPTOR
. WORD
0,0
iDIRECTORY DESCRIPTOR
. WORD
INAMSZ,INAM
iFILENAME DESCRIPTOR
ONAM:
.ASCII /OUTPUT.DAT/
ONAMSZ=.-ONAM
.EVEN
INAM:
.ASCII /INPUT.DAT/
INAMSZ=.-INAM
.EVEN
START:
FINIT$
iINIT FILE STORAGE REGION
OPEN$R #FDBIN
iOPEN THE INPUT FILE
BCS
ERROR
;BRANCH IF ERROR
OPEN$W #FDBOUT iOPEN THE OUTPUT FILE
BCS
ERROR
;BRANCH IF ERROR
GTREC: GET$
#FDBIN
iNOTE - URBD IS ALL SET UP
BCS
CKEOF
;ERROR SHOULD BE EOF INDICATIO~
MOV
F.NRBD(RO} ,Rl
iRl=SIZE OF RECORD READ
MOV
#RECBUF,R2
ADD
Rl,R2
;R2=ADDRESS OF LAST BYTE+l
10$:
CMPB
#40,-(R2}
iSTRIP TRAILING BLANKS
BNE
PTREC
SOB
Rl,lO$
iAT THIS POINT, Rl CONTAINS THE STRIPPED SIZE OF THE
iRECORD TO BE WRITTEN.
IF THE CARD IS BLANK,
iA ZERO-LENGTH RECORD IS WRITTEN.
PTREC: PUTS
#FDBOUT"Rl
iRl IS NEEDED TO SPECIFY
BCC
GTREC
iTHE RECORD SIZE.
ERROR: NOP
iERROR CODE GOES HERE
CKEOF: CMPB
#IE.EOF,F.ERR(RO} iEND OF FILE?
BNE
ERROR
iBRANCH IF OTHER ERROR
CLOSES RO
iCLOSE THE INPUT FILE
BCS
ERROR
;CLOSE THE OUTPUT FILE
CLOSES #FDBOUT
BCS
ERROR
iISSUE EXIT DIRECTIVE
EXIT$S
START
.END

D-2

SAMPLE PROGRAMS
iCARD READER COPY ROUTINE
.TITLE CRCOPB
• MCALL FDBDF$,FDAT$A,FDRC$A,FDOP$A,NMBLK$,FSRSZ$
.MCALL OPEN$R,OPEN$W,GET$,PUT$,CLOSE$,EXIT$S
. MCALL FINIT$,FDAT$R
iASSIGN CR OR FILE DEVICE
INLUN=3
iASSIGN TO OUTPUT DEVICE
OUTLUN=4
FSRSZ$ 2
FDBOUT: FDBDF$
FDBIN: FDBDF$
80.
RECBUF: .BLKB
iDEVICE DESCRIPTOR
0,0
CFDSPT: • WORD
iDIRECTORY DESCRIPTOR
. WORD
0,0
iFILENAME DESCRIPTOR
. WORD
ONAM$Z,ONAM
iDEVICE DESCRIPTOR
0,0
IFDSPT: • WORD
iDIRECTORY DESCRIPTOR
. WORD
0,0
. WORD
INAMSZ,INAM
iFILENAME DESCRIPTOR
.ASCII /OUTPUT.DAT/
ONAM:
ONAMSZ=.-ONAM
.EVEN
.ASCII /INPUT.DAT/
INAM:
INAMSZ=.-INAM
. EVEN
iINIT FILE STORAGE REGION
START: FINIT$
OPEN$R #FDBIN,#INLUN,#IFDSPT,,#RECBUF,#80.
iRUNTIME INITIALIZATION
BCS
ERROR
iBRANCH IF ERROR
FDAT$R #FDBOUT,#R.VAR,#FD.CR
iRUNTIME INITIALIZATION
OPEN$W RO,#OUTLUN,#OFDSPT,,#RECBUF,#80.
BCS
ERROR
iBRANCH IF ERROR
GTREC: GET$
#FDBIN
iNOTE - URBD IS ALL SET UP
BCS
CKEOF
iERROR SHOULD BE EOF INDICATION
MOV
F.NRBD(RO) ,Rl
iRl=SIZE OF RECORD READ
MOV
#RECBUF,R2
ADD
Rl,R2
iR2=ADDRESS OF LAST BYTE+l
iSTRIP TRAILING BLANKS
CMPB
#40,-(R2)
10$:
BNE
PTREC
SOB
Rl,lO$
iAT THIS POINT, Rl CONTAINS THE STRIPPED SIZE OF THE
iRECORD TO BE WRITTEN.
IF THE CARD IS BLANK,
iA ZERO-LENGTH RECORD IS WRITTEN.
PTREC: PUTS
#FDBOUT"Rl
iRl IS NEEDED TO SPECIFY
BCC
GTREC
iTHE RECORD SIZE.
ERROR: NOP
iERROR CODE GOES HERE
CKEOF: CMPB
#IE.EOF,F.ERR(RO) iEND OF FILE?
BNE
ERROR
iBRANCH IF OTHER ERROR
CLOSES RO
iCLOSE THE INPUT FILE
BCS
ERROR
CLOSES #FDBOUT
iCLOSE THE OUTPUT FILE
BCS
ERROR
iISSUE EXIT DIRECTIVE
EXIT$S
.END
START

D-3

APPENDIX E
INDEX FILE FORMAT

The index file ([O,O]INDEXF.SYS) of a FILES-II 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 (not used by
RSX-IIM).

3+n+5

User file header 1.

3+n+6

User file header 2.

User file header n.

E.l

BOOTSTRAP BLOCK

A disk that is structured for FILES-II has a 256-word block, starting
at physical block 0. 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 lAS and
RSX-IID,
the core image is pointed to by a file header block in the
index file.

E-l

INDEX FILE FORMAT
E.2

HOME BLOCK

The home block contains volume identification information that is
formatted as shown in Table E-I. This block is located either in
Logical Block I or at any even multiple of 256 blocks.
The offset names in the home block may be defined
globally, as shown below:

E.3

either

HMBOF$

DEF$L

~DEFINES

OFFSETS LOCALLY.

HMBOF$

DEF$G

~DEFINES

OFFSETS GLOBALLY.

locally

INDEX-FILE BIT MAP

The index-file bit map controls the use of file-header blocks in the
index file.
The bit map contains a bit for each file-header block
contained in the index file. The bit for a file-header block is
located by means of the file number of the file with which it is
associated. The values of the bit map are as follows:

Indicates that the file-header block is available.
The
file-control primitives can use this block to create a file.

I - Indicates that the file-header block is in
has already been used to create a file.

E.4

use.

This

block

PREDEFINED FILE-HEADER BLOCKS

The first five file-header blocks are described below.

FILE-HEADER BLOCK

SIGNIFICANCE

Index-File Header

This is the
standard
with the index file.

Storage-Map-File
Header

The storage map is a file that is used to
control the assignment of disk blocks to
files.

Bad-Block-File
Header

The bad-block file is 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), th~
checkpoint
file,
and
all
user
file
directories (UFD's).

Checkpoint-File Header

This block identifies the file that is used
for
the
checkpoint
areas
for
all
checkpointable tasks. In RSX-IIM, a task can
also have checkpoint space in the task image
itself.

E-2

header

associated

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 E-l
Home-Block Format
CONTENT

OFFSET

Index-bit-map size.

H.IBSZ

Location of index bit
map.

H.IBLB

Maximum files allowed.

H.FMAX

Storage-bit-map cluster
factor.

H.SBCL

Disk-device type.

H.DVTY

Structure level.

H.VLEV

Volume name (12 ASCII
characters) .

H.VNAM

SIZE
(in bytes)

12.
4

Reserved.

Volume owner's UIC.

H.VOWN

Volume-protection code.

H.VPRO

Volume characteristics.

H.VCHA

Default-file protection
word.

H.DFPR

Reserved

Default number of
retrieval pointers
in a window.

H.WISZ

Default number of
blocks to extend files.

H.FIEX

Number of entries in
directory LRU.

H.LRUC

11.

Available space.

Checksum of words 0-28.

H.CHKl

14.

Creation date and time.

H.VDAT

100.

Volume-header label (not
used) .
(continued on next page)

E-3

INDEX FILE FORMAT
Table E-I
(Cont.)
Home-Block Format
SIZE
(in bytes)
82.
254.
2

CONTENT

OFFSET

System-specific information (not used).

Relative volume table
(not used).

Checksum of home block
lworas u tnrough 255).

E-4

H.CHK2

APPENDIX F

FILE-HEADER BLOCK FORMAT

Table F-I 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

iDEFINE OFFSETS LOCALLY.

FHDOF$

DEF$G

iDEFINE OFFSETS GLOBALLY.
Table F-I
File Header Block

AREA

HEADER AREA

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

SIZE
(in bytes)

(continued on next page)

F-l

FILE~HEADER

BLOCK FORMAT

Table F-l
(Cont.)
File Header Block
AREA

SIZE
(in bytes)

H.SCHA

User file attributes.

H.UFAT

Size in bytes of header
area of file-header block.

S.HDHD

Filename (Radix-50).

I.FNAM

File type (Radix-50).

I.FTYP

File version number
(binary) .

I.FVER

Revision number.

I.RVNO

Revision date.

I.RVDT

Revision time.

I.RVTI

Creation date.

I.CRDT

Creation time.

I.CRTI

Expiration date.

I.EXDT

To round up to word
boundary.

32.

MAP AREA

OFFSET

System-controlled file
characteristics.

IDENTIFICATION
AREA

CONTENT

Size (in bytes) of
identification area of
file-header block.

S. IDHD

Extension segment number.

M.ESQN

Extension relative volume
number (not implemented).

M.ERVN

Extension file number.

M.EFNU

Extension file sequence
number.

M.EFSQ

Size (in bytes) of the
block-count field of a
retrieval pointer (lor 2);
only 1 is used.

M.CTSZ

Size (in bytes) of the
logical-block-numper field
of a retr ieval pointer (2,
3, or 4);
only 3 is used.

M.LBSZ

(continued on next page)

F-2

FILE-HEADER BLOCK FORMAT

Table F-l
(Cant.)
File Header Block
AREA

SIZE
(in bytes)

CHECKSUM WORD

CONTENT

OFFSET

Words of retrieval pointers
in use in the map area.

M.USE

Maximum number of words
of retrieval pointers
available in the map area.

M.MAX

Start of retrieval pointers.

M.RTRV

Size in bytes of map area
of file-header block.

S.MPHD

Checksum of words 0 through

H.CKSM

255.

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

HEADER AREA

The information in the header area of the file-header
of the following:

block

consists

IDENTIFICATION AREA
OFFSET

- Word 0, 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 0, 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.
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-II volumes.

F-3

FILE-HEADER BLOCK FORMAT
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
file can be used and who can use it. When
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 0 defines the user-controlled characteristics, as follows:
UC.CON = 200 - Logically contiguous file.
When
the file is extended (for example, by a WRITE
or PUT), bit UC.CON is cleared whether or not
the extension requests contiguous blocks.
UC.DLK

= 100

- File improperly closed.

Byte 1 defines system-controlled
tics, as follows:
SC.MDL

characteris-

200 - File marked for delete.

SC.BAD = 100 - Bad data block in file.
USER FILE
ATTRIBUTES

F.2

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

IDENTIFICATION AREA

The information in the identification area of the
consists of the following:
FILENAME

FILE TYPE
FILE VERSION NUMBER

REVISION NUMBER

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 O-filled.
This word contains the file
format.

type

Radix-50

- This word contains the file version number,
in
binary, as specified by the creator of the
file.
This word is initialized to 0 when the file is
created;
it is incremented each time a file is
closed after being updated or modified.

F-4

FILE-HEADER BLOCK FORMAT

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

CREATION 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-II
shown below:

file

15
COUNT-1

HIGH LBN

LOW

LBN

NOTE
The
remaining
paragraphs
in
this
appendix apply to lAS, RSX-IID, and
RSX-IIM
systems
that
support
the
multiheader version of FIIACP.

F-5

structure

are
is

FILE-HEADER BLOCK FORMAT

The map area normally has space for 102 retrieval pointers.
It can
map up to 102 discontiguous segments or up to 26112 blocks if the file
is contiguous. If more retrieval pointers are required because the
file is too large or consists of too many discontiguous segments,
extension headers are allocated to hold additional retrieval pointers.
Extension headers are allocated within the index file. They are
identified by a file number and a file sequence as are other file
headers;
however, extension file headers do not appear in any
directory.
A nonzero value in the extension file number field of the map area
indicates that an extension header exists. The extension header is
identified by the extension file number and the extension file
sequence number.
The extension segment number is used to number the
headers of the file sequentially, starting with a 0 for the first.
Extension headers of a file contain a header area and identification
area that are a copy of the first header as it appeared when the first
extension was created. Extension headers are not updated when the
first header of the file is modified.
Extension headers are created and handled by the
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 Jun~ 19, 1974 Proposed Revision
to the ANSI standard Magnetic Tape Labels and File Structure for
Information Interchange (X3.27-l969). The only exception is that ANSI
does not support spanned records.

G.l

VOLUME AND FILE LABELS

Tables G-l, G-2, and G-3 present
file-header labels.

G.l.l

the

format

volume

labels

and

Volume Label Format
Table G-l
Volume Label Format

CHARACTER
POSITION FIELD NAME

LENGTH
IN BYTES

CONTENTS

1-3

Label identifier

VOL

Label number

5-10

Volume identifier

Volume
label.
Any
special
alphanumeric
or
character in the center four
of the ASCII code
columns
table.

Accessibility

Any alphanumeric or special
character
in the center four
columns of the ASCII
code
table.
A space indicates no
restriction.
All
volumes
produced by lAS or RSX-ll have
a space in this position.

12-37

Reserved

Spaces
(continued on next page)

G-l

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
Table G-l
(Cont.)
Volume Label Format
CHARACTER
POSITION FIELD NAME

LENGTH
IN BYTES

CONTENTS

38-51

Owner
identification

The contents of this field are
system-dependent and are used
for
volume
protection
purposes. See Section G.l.l.l
below.

52-79

Reserved

Spaces.

Label standard
version

G.l.l.l 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
A
B
F

PDP-8
DECsystem-lO
PDP-II
PDP-IS

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

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
One of the following access codes can be specified for each
position.
Code

o
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%B1410051102
1.

The file was created on a PDP-II.

System and group have read access.
Owner has total access.
All others are denied access.

The UIC is [051,102].

G.l.2

User Volume Labels

User volume labels are never written or passed back to the
present, they are skipped.

G.l.3

user.

File-Header Labels

The following
information
file-header labels.

should

kept

mind

when

creating

•

The Files-II naming convention uses a subset
(Radix-50)
the available ANSI character set for file identifiers.

•

One character in the file
fixed by Files-II.

•

A maximum of 13 of the 17 bytes in the
processed by Files-II.

•

It is strongly recommended that all file identifiers be
limited to the Radix-50 PDP-II character set and that no
character other than the period (.) be used in the file
type
delimiter position for data interchange between PDP-II and
DECsystem-lO systems.

•

For data interchange between DIGITAL and nonDIGITAL systems,
the conventions listed above should be followed.
If they are
not, refer to Section G.l.3.1.

identifier,

G-3

the
file

period

(.),

identifier

are

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

Tables G-2 and G-3 describe the HDRI and HDR2 labels respectively.
Table G-2
File-Header Label (HDR1)
CHARACTER
POSITION FIELD NAME

LENGTH
IN BYTES

CONTENT

1-3

Label identifier

HDR

Label number

5-21

File idpntifiAr

1 i

£'l.u.1

22-27

File set
identifier

Volume identifier of the first
volume in the set of volumes.

28-31

File section
number

Numeric
characters.
This
field starts at 0001 and is
increased
by
1
for each
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 (_ indicates space)
or
00000 if no date.

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

a.LJ: IR
l~L IC
or speCIa 1
character in the center four
columns of the ASCII
code
table.
7\

•

Examples:

DECFILEllA
DECSYSTEMIO

Pad name with spaces.
74

Reserved

Spaces.

G-4

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
Table G-3
File Header Format (HDR2)
CHARACTER
POSITION FIELD NAME

LENGTH
IN BYTES

CONTENT

1-3

Label identifier

HDR

Label number

Record format

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.

through

51-52

Buffer offset

Numeric characters.
00
on
tapes produced by Files-II.
Not supported on input
to
Files-II.

53-80

Reserved

Spaces.

G.l.3.1 File Identifier Processing by Files-II - The following
describe the processing of a file identifier by Files-II.
1.

steps

The first 9 characters at a maximum are processed by an ASCII
to Radix-50 converter. The conversion continues until one of
the following occurs:
A conversion failure,
9 characters are converted,
A period (.) is encountered.
G-5

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
2.

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
At file output, the file identifier is handled as follows.
1.

The filename is placed in the first positions in the file
identifier field
It can occupy up to 9 positions.
It IS
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
version # - 1 + 1
100

generation number

generation version # = version # - 1
Modulo 100
NOTE
In both calculations, remainders are ignored.

The following are examples.
FILES-II VERSION #

GENERATION #

50
100
101
1010

G.l.4

GENERATION VER #

1
1
1

49
99

2
11

End-ot-Volume Labels

End-of-volume labels are identical to the file-header labels with
following exceptions:

the

Character positions 1 through 4 contain EOVI and EOV2 instead
of HDRI and HDR2, respectively.

The block-count field contains the number of records
last file section on the volume.

G-6

the

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
G.l.5

File-Trailer Labels

End-of-file labels
(file-trailer
labels)
are
file-header labels, with the following exceptions:

with

Columns 1 through 4 contain EOFI and EOF2 instead of HDRI and
HDR2, respectively.

The block count contains the number of
file.

G.l.6

data

blocks

the

user.

User File Labels

User file labels are never written or passed back
present, they are skipped.

G.2

identical

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.

G.2.1

* indicates a tape mark,

BOT indicates beginning of tape,

EOT indicates end of tape,

, indicates the physical record delimiter.

Single' File Single Volume

BOT,VOLl,HDRl,HDR2*---DATA---*EOFl,EOF2**

G.2.2

Single File Multivolume

BOT,VOLl,HDRl,HDR2*---DATA---*EOVl,EOV2**
BOT,VOLl,HDRl,HDR2*---DATA---*EOFl,EOF2**

G-7

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

G.2.3

Multifile Single Volume

BOT,VOLl,HDRl,HDR2*---DATA---*EOFl,EOF2*HDRl,HDR2*---DATA--*EOFl,EOF2**

G.2.4

Multifile Multivolume

BOT,VOLl,HDRl,HDR2*--DATA--*EOFl,EOF2*HDRl,HDR2*--DATA--*EOVl,EOV2**
BOT,VOLl,HDRl,HDR2*--DATA--*EOFl,EOF2*HDRl,HDR2*--DATA--*EOFl,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-l 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

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

H.MPOF

,..

MAP OFFSET

IDENT OFFSET

FILE SEQUENCE NUMBER

H.FNUM

FI LE SECTION NUMBER

H.FSEQ

STRUCTURE LEVEL = 401(8)

H.FLEV

UIC (FOR VOLUME)
HEADER AREA

H.IDOF

PROTECTION CODE (FOR VOLUME)
RECORD ATTRIBUTES

RECORD TYPE CODE

H.FOWN=H.PROG
H.FPRO
H.UFAT

RECORD SIZE IN BYTES

N WORDS OF ZERO'S
\",

IDENTI FICA·
CATION AREA

MAP AREA

Figure G-I

(

FILE NAME RAD50

X+I.FNAM
(IDENT OFFSET *2)=X

FI LE TYPE RAD50

I.FTYP

FILE VERSION NUMBER

X+I.FVER

ZERO'S (REVISION DATE & TIME)

X+I.RVNO

CREATION DATE & TIME (000000)

X+I.CRDT

EXPIRATION DATE

X+I,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

APPENDIX 8
STATISTICS BLOCK

The format of the statistics block is shown in Figure 8-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 LOGICAL BLOCK NUMBER
(0 if file is noncontiguous)

Word 1

LOW LOGICAL BLOCK NUMBER
(0 if file is noncontiguous)

Word 2

Word 3

SIZE (high)

SIZE (low)

Word 4
LOCK COUNT

Figure 8-1

ACCESS COUNT

Statistics Block Format

H-l

APPENDIX I
ERROR CODES

This appendix lists the Directive Status Word error codes and the
error codes returned by the system.

I-I

I/O

QIOMAC • QIOSYM MACRO DEFINITIO MACRO Mll1217

1212-NOV-77 1,.37
.TITL!

1
2
3
4
5

C••• D'ELIA

*****

8
9

12
13
14

I
N

15
16
17
18
19
2121
21
22

23
24

25
26

27
28
29

30
31

33
34

35
36

37
38
39

40
41
42

43
44

QIOMAC - QIOSYM MACRO DEFINITION

DATE OF LAST MODIFICATION,

6
7

PAGE 1

01210327

1212-NOV-77

ALWAYS UPDATE THE FOLLOWING TWO LINES
.IDENT 11213211
QI.VERae321

TO~ETH!R

, COPYRIGHT (C) 1'73,1'77
, DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.

,, THIS SOFTWARE IS FURNISHED UNDER • LICENSE FOR S! ONLY ON A
,, SINGLE
COMPUTER SYSTEM AND MAY BE COPIED
ON V WITH TH!
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS OFTWARE, OR
,, MADE
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED
R OTHERWISE
AVAIlABLE TO ANV OTHER PERSON
EXCEPT FOR USE ON SUCH
,, SYSTEM
AND TO ONE WHO AGREES TO THESE LICENSE
TITLE
TO AND OWNERSHIP 0' THE SOFTWARE SHALL AT ALL
IM!S REMAIN
,, IN DEC.
,, THE
INFORMATION IN THIS DOCUMENT IS SUBJECT TO
WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED 4S A COMMITM¢NT BY DIGITAL
,
E~MS.

~HANGE

EQUIP~ENT

CORPOR~TION.

, DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RE4IABILITY OF
, ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIEDIBY DEC.

,,, PETER H.
,

LIPMAN 1-0CT-13

'+, MACRO

TO DEFINE STANDARD QUEUE 1/0 DIRECTIVE FUNCTION VALUES
, AND IOSB RETURN VALUES. TO INVOKE AT ASSEMBLY ~IME (WITH LOCAL
, DEFINITION) USE,

,,
QIOSYS
,DEFINE SYMBOLS
,, TO OBTAIN
GLOBAL DEFINITION OF THESE SYMBOLS
,,
QIOSVS DEFSG
,SYMBOLS DEFINED GLOBALLY
,

US~I

t:zl

!:tI

!:tI
()

tzl
til

4tl

47
A8

49
50
51
52
53

, THE MACRO CAN BE CALLED ONCE ONLY AND THEN
, REDEFINES ITSELF AS NULL.

.MACRO QIOSYS SSSGBL,SSSMSG
.11'
IDN,cSSSGBL.,cDEFSG.,
.IF
IDN,cSSSMSG.,cDE'SS.
SSSMAX.0
SSMSG-l
.IFF
SSMSG-e
.ENDC

55
5tl

57
QIOMAC - QIOSVM MACRO DEFINITIO MACRO M1107

.MCALL
IOERRS
.MCALL
DRERRS
• IF
.MCALL
FILIOI
.MCALL.
SPCIOS
.MACRO
,ENDM
.ENDC
.ENDM

I
LV

59
be
bl
b2
b3
b4
b5
bb
b7
be
&9
70

QIOMAC • QIOSYM MACRO DEFINITIO MACRO Mlle?
72
73
74
'75

1&
17
78

79
80
81
82

02-NOV-11 19137

.GLOBL

QI.VER

PAGE 1-1

IOERRS
,1/0 ERROR CODES FROM HANDLERS, FCP, FCS
SSIGBL
DRERRS
,DIRECTIVE STATUS WORD ERROR CODES
SSSGeL
DIF,cSSSMSG>,cDEFSS •
FILIOI
,DEFINE GENERAL 1/0 FUNCTION CODES
SSSGeL
SPCIOS
,DEVICE DEPENDENT 1/0 FUNCTION CODES
SSIGBL
,RECLAI~'MACRO STORAGE
QIOSVS .ARG, ARG1, ARG2
QIOSYS
QIOSVS

02-NOV.77 19.37

PAGE 2

DEFINE THE ERROR CODES RETURNED BY DEVICE HANDLER AND FIL.E PRIMITIVES
IN THE FIRST wORD OF THE 110 STATUS BLOCK
THESE CODES ARE ALSO RETURNED BY FIL.E CONTROL SERVICES (FCS) IN THE
BYTE F.ERR IN THE 'ILE DESCRIPTOR BLOCK (FOB)
THE BYTE F,ERR+1 IS 0 IF F,ERR CONTAINS A HANDLER OR FCP ERROR CODE.
.MACRO
.HCALL
.IF

IOERRS SSIGBL
.IOER.,DEFINS
IDN,cSSSGBL>,cDEFIG>

til

~
o

!:II:'

o
c
til

til

84
85
86
87
ee
e9
9'"
91
92
93
94
95
96
97
9a
99
10et

I
~

101
102
103
104
105
106
107
108

U!!9
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

••• GeLal
.IFF
••• GBLa'"
.ENOC
NDF,SSMSG,SSMSGa0
.IIF
SYSTEM STANDARD CODES, USED BY EXECUTIVE AND OR_V£RS
.IOER.

IE.BAD,-01.,~BAO

.IOE~.

IE.IFC,-02.,
IE.D~R,-03.,coEVICE NOT READY>
IE.VE~,-04.,
IE.ONP~-05.,cHARDWARE OPTlnN NOT
RESENT>
IE.SPC,-06.,
IE.ONA,-07.,cOEVICE NOT ATTACHED>
IE.DAA,-~a.,
IE.oUN,-"9.,cDEVICE NorATTACHABL >
IE,EOF,-10.,
IE,wL~,-12"cWRITE ATTEMPTED TO L CKED UNIT>
IE.OlO,-13.,cOATA OVERRUN>
IE.SRE,-14.,cSEND/REtEIVE FAILURE
IE.ABO,-15.,
IE.P~I,-16.~
IE.RSU,-17.,cSHARABLE RESOURCE IN USE>
IE.OVR,-18.,
IE.6YT,-19.,
IE.MOD,-21.,
IE.8BE,-56.,<8Ao BLOCt< ON OEVICE>

• I OER.
.IOER.
.IOER.
.IOER •
• IOER.
.IOER.
.IOER.
.IOER,
.IOER.
.IDER.
.IDER.
.IOER.
.IOER.
.ICER.
.ICER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.

PARAMET~RS>

IE,sn,-58"cNOT E~OUGH SUCK SPAJE (FCS OR FCPl'

IE.FHE,-59.,cFATAL HARDWARE ERROR ON DEVICE>
IE.EOT,-62.,
IE.OFL,-65.,cDEVICE OFF LINE>
IE.BCC,-6~.,cBLOCI( CHECK, CRC, OR ~RAMING ERROR>

, FILE PRIMITIVE COOES
.IOER •
• IOER.
.ICER.
.IOER.

IE.NOO,-23.,
IE.DFU,-24"cDEVICE FULL>
IE.IFU,-25"cINOEX FILE FULL>
IE.NSF,-26"cNO SUCH FILE>

tzl

l:t1

0
l:t1

n
0

tzl
til

QIOMAC - QIOSYM MACRO DEFINITIO MACRO M1107
12q

130
111
132
133
13".
135
13&
137
138
13q
1".0

141
14£2
14£3
1"'"
1"5
1£&&
1".7
148
H

I
U1

1£&q

150
151
152
1153
15".
155
15&
157
158
159
1~0

1&1
1&2
1&3
164
1&5
1&&
1&7
1&8
l&q

170
171
172

02-NOV-71 19137
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER,
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.

PAGE 2-1
FROM READ/WRITE

IE.~CK,.27.,cLOCKED
IE.~FU,-2e.,cFI~E ~EADER

ACCESS~

FULL~

IE.WAC,-29.,CACCESSEO FOR WRITEIE.CKS,-30.,cFILE HEADER CHECKSUM FAI~URE~
IE.WAT,-31.,CATTRIBUTE CONT~OL LIST FORMAT ERROR~
IE.RER,-32.,cFI~E PROCESSOR DEVICE READ ERROR~
IE.WER,-33.,CFILE PROCESSOR DEVICE WqITE ERR~R~
IE.A~N,·3~'JcFI~E ALR£ADY ACCESSED ON LUN~
IE.SNC,-35.,cFILE 10, FILE NUMBER C"ECK~
IE,SQC,-3&"cFILE 10, SEQUENCE NUMBER CHECK~
IE.NLN,-]1.,cNO FILE ACCESSED ON LUN~
IE.CLO,-3e.,cFILE WAS NOT PROPERLY CLOSED~
IE.DUP,-S7.,cENlER - DUPLICATE ENTRY IN DIRECTORY~
IE.BVR,-&3.,cBAD VERSION NUMBER~
IE.BHD,-&"..,cBAD FILE HEADERIE.EXP,-75.,cFILE EXPIRATION DATE NOT REACHED~
IE.BTF,-7&"cB~D TAPE FORMAf~
IE.ALC,-e"..,cALLOCATION FAILURE~
IE,ULK,-e5.,cUNLOCK ERROR>
IE.wCK,-S&.,cWRITE CHECK FAILURE-

tzl

n
0

FILE CONTROL SERVICES CODES

tzl
til

.IOER,
.IOER.
.IOER.
.IOER,
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER,
.IOER,
.IOER.
.IOER.

IE.N8F,-19"cO~EN • ~O BUFFER SPACE AVAILABLE FOR FILE>
IE,RBG,-40"cILLEGAL RECORD SIZE~
IE,NBK,-41"cFILE EXCEEDS SPACE ALLOCATED, NO BLOCKS>
IE,ILL,-42.,clLLEGAL OPERATION ON FILE DESCRIPTOR B~OCK~
IE.8TP,-43.,CSAO ~ECORD TYPE~
lE.RAC,.44.,cI~LEGAL RECORD ACCESS 8ITS SET~
lE.RAT,-4S.,cI~~EGAL RECORD ATTRIBUTES BITS SET~
IE.RCN,-46.,cILLEGAL RECORD NUMBER • TOO LARGE~
IE.20V,-48.,cRENAME - 2 DIFFERENT DEVICES~
IE.FEX,-49"cRENAME - NEW FILE ~AME ALREADY IN USEIE,8D~,-50"cBAD DIRECTORY FILE~
IE.RNM,-51.,cCAN'T RENAME O~D FILE SYSTE~~
IE.BOI,-52.,c8AO DIRECTORY SYNTAX~
IE.FOP,-51.,cFILE ALREADY OPEN~
IE.8~M,-54"c8AO

FI~E

NAME~

IE,BDV,-55.,cBAO DEVICE NAME_
IE,NFI,-&0.,cFILE 10 WAS NOT SPECIFIEO~
IE.lSQ,-61.,cILLEGA~

SEQUENTIA~

OPERATION~
COUNT~

If.NNC,-77.,CNOT ANSI '0' FORMAT BYTE

113
114
175
176
177
178
179
180
181
182
183
184
185
QIOMAC -

I
0"1

186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215

NETWORK ACP CODES
.IOER.
.IOER.
.IOER.
.IOER.
.IOER,
,IOER,
,IOER,
.IOER,
.IOER.

QIOSY~

MACRO DEFINITIO MACRO M1107

IE.AST,-80.,C~0 AST SPECIFIED IN CONNECT>
IE,NNN,-68"CNO SUCH NODE>
IE.NFW,-69.,CPATH ~OST TO PARTNER> ,THIS CODE MUST BE ODD
IE,8l8,-70.,c8AD LOGICA~ BUFFER>
IE.TMM,-71.,cTOO ~ANY OUTSTANDING MESSAGES>
IE,NDR,-12"CNO DVNA~IC SPACE AVAILABLE>
IE,CNR,·73"cCO~NECTION REJECTED>
IE,TMO,-74"cTIMEOUT ON REQUEST>
IE,NNl,-78"CNOT A NETWORK lUN>

02-NOV-77 19137

PAGE 2-2

ICS/ICR ERROR CODES
,IOER,
,IOER,
,IOER.

tzl

IE,NlK,-79.,cTASK NOT lINKED TO S ECIFIED ICS/ICR INTERRUPTS>
IE,NST,-80.,cSPECIFIED TASK NOT I STAt.~ED>
IE,FlN,-81"cDEVICE OFFLINE WHEN FFlI~E REQUEST WAS ISSUED>

~
~

n
0

tzl
til

TTY ERROR CODES
,IOER,
,IOER,

IE,IES,-82"CINVA~ID

ESCAPE SEQUE~CE>
IE,PES,-83"cPARTIAl ESCAPE SEQUE CE>

, SUCCESSFUL RETURN CODES--·
DEFINS
DEFINS
OEFINS

IS,PND,+00,
IS,SUC,+01,
IS,ROO,+02,

OEFINS

IS,8V,+05.

,OPERATION PENDIN
,OPERATION COMP~EiE' SUCCESS
,(RX11) FLOPPY 01 K SUCCESSFUL COMPLETION
,OF A READ PHYSIC L, ANO OELETED
,DATA MARK WAS SE N IN SECTOR ~EADER
, LAST SECTOR,
,(AID READ) AT ~E~ST ONE BAD VA~UE
,WAS READ (REMAIN ER MAV BE GOOO),
,BAD CHANNE~ IS r OrCATED BY A
,NEGATIVE VALUE I THE BUFFER,

21&
217
218

21q
220
221
222
223
224
225
22&
227
228

TTY SUCCESS CODES
OEFINS
DEFINS
DEFINS
DEFINS
OEFINS
OEFINS
DEFINS
DEFINS

22q

230
231
232
233
234
235
23&
231
238
23q

240

I5.TMO,+2,

tzl
~

~
~

*****

.IF

.MACRO
.ENDM

QIOMAC • QIOSYM MACRO DEFINITIO MACRO M1le?

EQ,SSMSG
IOERR! A
10ERRS

a2-NOV-?7 lql3?
.ENDC
.ENDM

243
244

24q

,ESCAPE SEQUENCE WAS TERMINATOR
,PARTIAL ESCAPE SEQUENCE TERMINATOR
,EOT WAS TERMINATOR (BLOCK MODE INPUT)
,TAB WAS TERMINATOR (FORMS MODE INPUT)
,REQUEST TIMED OUT

IS.ESQ,C233*400+1~
IS.PES,C200*400+1~
I5.EOT,c4*400+1~
IS,TAB,Cl1*400+1~

TME NEXT AVAILABLE ERROR NUMBER lSI -87,
A~L (BUT TWO) ~OWER NUMBERS ARE IN USE"
NOTE. ERROR CODES -41. AND -&1, MAV! BEEN RETIRED AND CAN
BE ASSIGNED AT A LATER DATE,

QIOMAC - QIOSYM MACRO OEFINITIO MACRO M110?

250
251
252
253

TER~INATOR

IS.ESC,c33*400+1~ ,ESCAPE (A~TMODE) WAS TERMINATOR
IS.CC,C3*40~+1~ ,CONTRO~-C WAS TERMINATOR

.**.**

241
242

24&
241
248

,CARRIAGE AETURN WAS

IS.CR,C15*400+1~

PAGE 2-3

IOERRS

02-NOV-?7 lql37

PAGE 3

DEFINE THE DIRECTIVE ERROR CODES RETURNED IN THE DIRECTIVE STATUS WORD
FILE CONTROL SERVICES C'CS) RETURNS THESE CODES IN THE BYTE F,ERR
OF THE FILE DESCRIPTOR BLOCK (FOB), TO DISTINGUISH TMEM FROM TME
OVERLAPPING CODES FROM HANDLER AND FILE PRIMITIVES, THE BYTE
F,ERR+1 IN THE FOB WI~L BE NEGATIVE FOR A DIRECTIVE ERROR CODE.

n
o

tzl

til

I
(Xl

254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
27q

280
281

,"4ACRO ORERRS SSSGBL
,MCALL ,QIOE"OEFINS
.IF
IDN,,
",GBL-l
,IFF
, •• GBL-"
.ENDC
,IIF
NDF,SSMSG,SSMSG.0

STANDARD ERROR CODES RETURNED 8Y DIRECTIVES IN fHE DIRECTIVE STATUS WORD
,QIOE,
.QIOE,
,QIOE,
,GlIOE,
,GlIOE.
,GlIOE.
,QIOE.
,GlIOE.
.QIOE,
,GlIOE.
.tHOE.
.GlIOE.
,GlIOE,
.QIOE.
,GlIOE,
,GlIOE,

IE.UPN,-01.,
IE.HwR,-06.,
IE.ITS,-08"cDIRECTIVE INCONSISTE
IE.FIX,-"9.,
IE.RSU,-17.,cRESOURCE IN USE>
IE,NSW,-18"cNO SWAP SPACE AVAILA
IE.ILV,-19"cILLEGAL VECTOR SPECI

,GlIDE,
,GlIOE,
,GlIOE.
.GlIOE.
,GlIDE,
,GlIDE.
,GlIDE,
.GlIOE,
.GlIOE,
,GlIDE,
.GlIOE,
,QIOE.
• GlIOE,
• GlIOE.
,GlIOE,
.GlIOE,
.GlIOE.
.(IlIOE.
,GlIDE,

IE.AST.-S0 •• cDIRECTIVE ISSUEO/NOTiISSUED ~ROM AST.
IE,MAP,-el.,cILLEGAL MAPPING SPEC FlED>
IE.IOP,·83.,CWI~DOW HAS 1/0 IN PR GRESS>
IE,ALG,-84.,CALIGNMENT ERROR>
IE.WOV,-85.,
IE.NVR,-86"CINVALID REGION 10>
IE.NVW,-87.,
IE.IUI,-91.,CINVALID UIC>
IE.IDU,-92.,
IE,I!F,-Q1.,cINVALIO EVENT FLAG ( .GT. 64,»
IE,ADP,-9a,,
IE,SOP,-QQ.,cDIC OR 01'8 SIZE !NVA 10>

STORAGE>
STALLED>
OR TASK>
STORAGE FOR SEND>

T WITH TASK STATE>
FIXED>
KPOINTABLE>
E>
SMALL>

2q3

294
295
296
297
2q8

299
300

301
302

~
(')

LE>
lEO>

282

283
284
285
286
287
288
2e9
290
291
292

trl

~
~

0
c::;,
trl

QIOMAC • QIOSYM MACRO DEFINITIO
303
304
305
306
307
308
309
310
311
312
313
314
315
31&
317

M~CRO

M1107

I
\.D

319
320
321
322
323
324
325
32b

327
328
329
330
331
332
333
334
335

PAGE 3-1

SUCCESS CODES FROM DIRECTIVES - PLACED IN THE DIRECTIVE STATUS WORD

QIOMAC • QIOSYM MACRO OEFINITIO MACRO Mll01
H

02-NOV-77 19137

DEFINS

IS.CLR,e

DEFINS

IS.SET,2

DEFINS

IS.SPD,2

.IF
• MACRO
,ENOM
,ENDC
,ENOM

EQ,SSMSG
DRERRS A
DRERRS

,EVENT FLAG WAS CLEAR
,FROM CLEAR EVENT FLAG DIRECTIVE
,EVENT FLAG WAS SfT
,FRO~ SET EVENT FLAG DIRECTIVE
,TASK WAS SUSPENDED

DRERRS

02-NOV-11 19131

tEl

PAGE 4

DEFINE THE GENERAL 1/0 FUNCTION CODES • DEVICE INDEPENDENT
.MACRO FILIOS SSIGBL
.MCALL .WORD.,DEFINS
.IF
IDN,CSSSGBL>,cDEFSG>
••• GBL-l
.IFF
.,.GBL-0
,ENDC
GENERAL 1/0 QUALIFIER ByTE DEFINITIONS
.WORD.
,WORD.
.wORD.
.WORD.

IQ.X,QHH,000
IQ.Q,002,000
IQ.S,004,000
IQ.UMD,004,000

,NO ERROR RECOVERy
,QUEUE REQUEST IN EXPRESS QUEUE
,SYNONYM FOR IQ.UMD
,USER MODE DIAGNOSTIC STATUS REQUIRED

33b

337
338
339
340
341
342

EXPRESS QUEUE COMMANDS
.WORD.
.WORD.
.WORD.

IO.KIL,012,000
10.RDN,022,000
IO.UNL,042,000

,KILL CURRENT REQUEST

,1/0 RUNDOWN

,UNLOAD 110 HANDLER TASK

tI:I

.WORD.
.WORD.
.WORD.

31J3

344
345

IO.LTI(,05e,000
IO.RTI(,060,000
IO.SET,030,000

,L040 A TASK

IMA~E

FILE

,RECORD A TASK I~AGE FILE
.SET CHARACTER IS ICS FU~CTION

31J~

347
3IJS

GENERAL DEVICE HANDLER CODES
.WORD.
.WORD.
,wORD.
,IIIORD.
,WORD.

3IJq

350
351
352
353
354
355

IO,WLB,000,001
IO.RLB, QlI2II2I, 12102
IO.LOV,12I1121,002
IO.4TT,eI2l0,01213
IO.DET,000,001J

,wRITE LOGICAL BtOCK
,READ LOGICAL BL
,LOAD OVERLAY (0
,ATTACH A DEVICE
,DETACH A DEVICE

CK
SK DRIVER)
TO A TASK
FROM A TASK

, DIRECTORy PRIMITIVE CODES

35~

.wORD.
.WORD.

357
358
35fi

.~ORD.

IO.FNA,000,011
IO.RNA,000,013
IO.ENA,000,12I14

,FIND FILE NAME

AA 2515C TC RSX 11M 3.1 IO Operations Reference Manual Dec77

AA-2515C-TC_RSX-11M_3.1_IO_Operations_Reference_Manual_Dec77 AA-2515C-TC_RSX-11M_3.1_IO_Operations_Reference_Manual_Dec77

AA-2515C-TC_RSX-11M_3.1_IO_Operations_Reference_Manual_Dec77 AA-2515C-TC_RSX-11M_3.1_IO_Operations_Reference_Manual_Dec77

Navigation menu

Versions of this User Manual:

Views

Navigation