Digital PDFs

AA-FD14A-TC

July 1985

310 pages

Original

13MB

Document:	RSX-11M/M-PLUS and Micro/RSX I/O Operations Reference Manual
Order Number:	AA-FD14A-TC
Revision:	0
Pages:	310
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_plus/RSX11Mplus_V3.0_Jul85/AA-FD14A-TC_RSX-11M-PLUS_V3.0_IO_Operations_Reference_Manual_Jul85.pdf

OCR Text

RSX-11 M/M-PLUS
and Micro/RSX
I/O Operations Reference Manual
Order No. AA-FD14A-TC

RSX-11 M Version 4.2
RSX-11 M-PLUS Version 3.0
Micro/RSX Version 3.0

digital equipment corporation · maynard, massachusetts

First Printing, December 1975
Revised, December 1976
Revised, December 1977
Revised, June 1979
Revised, November 1981
Revised, July 1985
The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may be used or copied only in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by Digital Equipment Corporation or its
affiliated companies.
Copyright @ 1975, 1976, 1977, 1979, 1981, 1985
by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future
documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-lO
DECSYSTEM-20
DECUS
DECWriter

DIBOL
EduSystem
lAS
MASSBUS
MicroPDP-ll
Micro/RSTS
Micro/RSX
PDP

PDT
RSTS
RSX
UNIBUS
VAX
VMS
VT

~D~DD~D

HOW TO ORDER ADDITIONAL DOCUMENTATION
In Continental USA and Puerto Rico call

800-258-1710

In New Hampshire, Alaska, and Hawaii call
In Canada call

603-884-6660

613-234-7726 (Ottawa-Hull)
800-267-6215 (all other Canadian)

DIRECT MAIL ORDERS (USA & PUERTO RICO)*
Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

DIRECT MAIL ORDERS (CANADA)
Digital Equipment of Canada Ltd.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

DIRECT MAIL ORDERS (INTERNATIONAL)
Digital Equipment Corporation
PSG Business Manager
c/o Digital's local subsidiary or
approved distributor

"Any prepaid order from Puerto Rico must be placed
with the local Digital subsidiary (809-754-7575)

internal orders should be placed through the Software Distribution Center (SDC), Digital Equipment
Corporation, Northboro, Massachusetts 01532

ZK2565

CONTENTS

Page

PREFACE

SUMMARY OF TECHNICAL CHANGES
CHAPTER 1

xiii

FILE CONTROL SERVICES

1.1
KEY TERMS USED THROUGHOUT THIS MANUAL • • • • • • 1-2
1.2
IMPORTANT FCS CHARACTERISTICS • • • •
• • 1-3
1.3
FCS DATA STRUCTURES • • • • • • • • • • • • • • • 1-4
1.3.1
File Descriptor Block (FOB)
••••
• 1-5
1.3.2
Dataset Descriptor and Default Filename Block • 1-5
1.3.3
File Storage Region (FSR)
• • ••
• • • 1-5
1.4
FILE ACCESS METHODS • • • • • • • • • •
• • 1-6
1.5
DATA FORMATS FOR FILE-STRUCTURED DEVICES.
•• 1-6
1.5.1
Data Formats for ANSI Magnetic Tape • • • • • • 1-7
1.6
BLOCK I/O OPERATIONS. • • • • • • • • • •
1-7
1.7
RECORD I/O OPERATIONS
• • • • • • • •
• 1-8
1.7.1
Record I/O Data-Transfer Modes.
• 1-9
1.7.1.1
Move Mode
• • • •
• • • • • 1-9
1.7.1.2
Locate Mode • • • • •
• • • •
1-10
1.7.2
Multiple Buffering for Record I/O
• • •• 1-10
1.7.2.1
Multiple Buffering Performance.
1-10
1.7.3
Big Buffering for Record I/O •
• • • • • • 1-11
1.8
SHARED ACCESS TO FILES. •
• • • • • • •• 1-12
1.9
FILE SPECIFICATION SYNTAX
• • • •
1-13
1.9.1
Device...
1-14
1.9.2
Directory..........
• • • •
1-14
1.9.3
Name..
1-15
1.9.4
Type............
• • •• 1-15
1.9.5
Version.................
1-16
1.10
ANSI MAGNETIC TAPE FILE SPECIFICATION SYNTAX.. 1-16
1.10.1
Device.....
• • • • • 1-16
1.10.2
Directory
• • • • • • •
1-17
1.10.3
Quoted String • • • • • • • • • • • • • •
1-17
1.10.4
Version
• • • • • • • • • • • • • •
1-17
1.10.4.1
Example Magnetic Tape File Specification
1-17
1.11
GENERATION OF A FULL FILE SPECIFICATION • • • • 1-17
1.12
LOGICAL NAMES
• • • • • • • • • • • •
1-18
1.12.1
Using Logical Names for Program Input and
1-19
Output • • • • • • • • • • •
1.12.1.1
Logical Name Tables
1-19
1-19
1.12.1.2
Specifying Logical Names
1.13
ROUTINES INCLUDED IN FCSRES
1-20
CHAPTER 2

PREPARING FOR I/O

2.1
2.2

PREPARING FOR I/O -- GENERAL INFORMATION • •
.MCALL DIRECTIVE - LISTING NAMES OF REQUIRED MACRO
DEFINITIONS • • • • • • • • • • • • • • • •
FILE DESCRIPTOR BLOCK (FOB)
••••••••
2.3
2.3.1
Assembly-Time FOB Initialization Macros •
FDBDF$ - Allocate File Descriptor Block (FOB)
2.3.1.1
FDAT$A - Initialize File Attribute Section
2.3.1.2
of
FOB...................

iii

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

CONTENTS
2.3.1.3

FDRC$A - Initialize Record Access Section of

2.3.1.4

FDBK$A -

Initialize Block Access Section of

FOB

•

2.3.1.5
2.3.1.6

FDOP$A - Initialize File-Open Section of FDB
FDBF$A - Initialize Block Buffer Section of

2.3.2
2.3.2.1
2.3.2.2

Run-Time FDB Initialization Macros.
Run-Time FDB Macro Exceptions
• • • • •
Specifying the FDB Address
in Run-Time
Macros • • • • • • • • • • • •
GLOBAL VERSUS LOCAL DEFINITIONS FOR FDB OFFSETS
Specifying Global Symbols in the Source Code •
Defining FDB Offsets and Bit Values Locally
CREATING FILE SPECIFICATIONS WITHIN YOUR PROGRAM
Dataset Descriptor • • • • • • • • • • • •
Default Filename Block - NMBLK$ Macro • • • •
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 • • • •
• • • •
Block Locking
•••••
• • • •
Error Codes Related to Shared Files and Block
Locking
•• • • • • • • • • • • • • • • • • •

FOB

2.4
2.4.1
2.4.2
2.5
2.5.1
2. 5. 2
2.5.3
2.6
2.6.1
2.6.2
2.7
2.7.1
2.7.2
2.8
2.8.1
2.8.2
2.9
2.9.1
2.9.2
2.9.3
2.9.4
2.9.5

CHAPTER 3

•
•

•

•
•

•

•
•

•

•
•

•

•
•

•

•
•

•

•
•

•

•
•

•

•
•

•

•
•

•

•
•

•

•
•

•

2-10
2-12
2-14
2-18
2-21
2-22
2-24
2-25
2-26
2-27
2-27
2-28
2-31
2-34
2-34
2-35
2-36
2-37
2-37
2-40
2-41
2-41
2-42
2-42
2-43
2-44
2-45
2-46
2-48

FILE-PROCESSING MACROS

3.1
3.1.1
3.1.2
3.2
3.3
3.4

OPEN$X - GENERALIZED OPEN MACRO
• • • • • • • • • 3-2
Format of Generalized OPEN$x Macro • • • • • • • 3-5
FDB Requirements for Generalized OPEN$x Macro
• 3-7
OPNS$X - OPEN FILE FOR SHARED ACCESS • • • • • •
3-12
OPNT$W - CREATE AND OPEN TEMPORARY FILE
• • • •
3-12
OPNT$D - CREATE AND OPEN TEMPORARY FILE AND MARK
FOR DELETION • • • • • • • • • • • • • • • • • •
3-13
3.5
OFID$X - OPEN FILE BY FILE ID
• . • • • • • • •
3-13
3.6
OFNB$X OPEN FILE BY FILENAME BLOCK • • • • • • •
3-14
3.6.1
Dataset Descriptor or Default Filename Block •
3-15
3.6.2
Default Filename Block Only • • • ~ •
3-15
OPEN$ - GENERALIZED OPEN FOR SPECIFYING FILE
3.7
ACCESS • • • • • • • • • • • • • • • • • •
3-16
3.8
CLOSE$ - CLOSE SPECIFIED FILE
• • • • •
3-18
3.8.1
Format of CLOSE$ Macro
3-18
3.9
GET$ - READ LOGICAL RECORD • • • • • • •
3-19
3.9.1
Format of GET$ Macro • • • • • • • • • •
3-19
3-21
3.9.2
The FDB Relevant to GET$ Operations
3.9.2.1
GET$ Operations in Move Mode • • •
3-21
3-21
3.9.2.2
GET$ Operations in Locate Mode • • • •
3.10
GET$R - READ LOGICAL RECORD IN RANDOM MODE.
3-22
3.11
GET$S - READ LOGICAL RECORD IN SEQUENTIAL MODE.
3-24
3.12
PUT$ - WRITE LOGICAL RECORD • • • • • • •
3-24
3-24
3.12.1
Format of PUT$ Macro • • • • • • • • •
3.12.2
The FDB Relevant to PUT$ Operations
3-25
3.12.2.1
PUT$ Operations in Move Mode • • •
3-26
3.12.2.2
PUT$ Operations in Locate Mode • • •
3-27
3.13
PUT$R - WRITE LOGICAL RECORD IN RANDOM MODE
3-28
iv

CONTENTS
3.14
3.15
3.15.1
3.15.2
3.16
3.16.1
3.16.2
3.17
3.17.1
3.18
3.18.1
CHAPTER 4
4.1
4.2
4.2.1
4.2.2
4.3
4.3.1
4.3.2
4.4
4.4.1

PUT$S - WRITE LOGICAL RECORD IN SEQUENTIAL MODE
READ$ - READ VIRTUAL BLOCK • • • • • • •
Format of READ$ Macro
• • • • •
The FOB Relevant to READ$ Operations • • •
WRITE$ - WRITE VIRTUAL BLOCK • • • • • • • •
Format of WRITE$ Macro • • • • • • • •
The FOB Relevant to WRITE$ Operations • • • •
WAIT$ - WAIT FOR BLOCK I/O COMPLETION
Format of WAIT$ Macro • • • • • • • • • • • •
DELET$ - DELETE SPECIFIED FILE •
Format of DELET$ Macro • • • •

3-30
3-30
3-31
3-33
3-34
3-34
3-36
3-37
3-37
3-39
3-39

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

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

• • • • • • • • • • • • • • • • •
• 4-5
.WDFFP - Write New $$FSR2 Default File
Protection Word
• • • • • • • • • • •
• 4-5
4.5
FILE OWNER WORD ROUTINES • • • • • • • •
• 4-5
.RFOWN - Read $$FSR2 File Owner Word •
4.5.1
• 4-6
4.5.2
.WFOWN - Write New $$FSR2 File Owner Word • • • 4-6
ASCII/BINARY UIC CONVERSION ROUTINES •
4.6
• 4-6
4.6.1
.ASCPP - Convert ASCII Directory String to
Equivalent Binary UIC • • • • • • • • • • • • • 4-7
4.6.2
.PPASC - Convert UIC to ASCII Directory String. 4-7
FILENAME BLOCK ROUTINES
• • • 4-7
4.7
4.7.1
Logical Name Translation • • • • • • • • •
• 4-8
Iterative Translation
• • • • • • • • • 4-8
4.7.1.1
4.7.1.2
Logical Translation Process • • • • • • • • • 4-9
.PARSE - Fill in All File Name Information
4-10
4.7.2
4.7.2.1
Device'" and Uni t Information • • • • •
4-11
Directory Identification Information • •
4-12
4.7.2.2
4.7.2.3
File Name, File Type, and File Version
4-13
Information • • • • • • • • • • • • • •
Using the FOB Extension for Logical Names
4.7.2.4
4-14
Other Filename Block Information • • • • • • 4-14
4.7.2.5
4.7.2.6
4-14
.EXPLG Module (Expand Logical) • • • • • • •
.PRSDV - Fill in Device and unit Information
4.7.3
Only . . . . . . . . . . . . . . . . . . .
4-15
• PRSDI - Fill in Directory Identification
4.7.4
Information Only • • • • • • • •
4-15
.PRSFN - Fill in File Name, File Type, and File
4.7.5
Version Only • • • • • • • • • • • • • • • • • 4-15
4-15
.ASLUN - Assign Logical Unit Number
4.7.6
4.8
DIRECTORY ENTRY ROUTINES • • • • • •
4-16
4-16
4.8.1
.FIND - Locate Directory Entry • •
4.8.2
.ENTER - Insert Directory Entry
4-18
4-19
.REMOV - Delete Directory Entry
4.8.3
4.9
FILENAME BLOCK ROUTINES • • • • • •
4-19
.GTDIR - Insert Directory Information in
4.9.1
Filename Block • • • • • • • • • • • • • • • •
4-19
4.9.2
.GTDID - Insert Default Directory Information
in Filename Block
••••••••••
4-20
4.10
FILE POINTER ROUTINES • • • • • • • • • • •
4-20
4.10.1
• POINT - Position File to Specified Byte.
4-21
4.10.2
.POSRC - Position File to Specified Record
4-21

4.4.2

CONTENTS
4.10.3
4.10.4
4.11
4.12
4.13
4.14
4.15
4.15.1
4.15.2
4.16
4.17
4.17.1
4.17.2
4.17.3
4.17.4
CHAPTER 5

.MARK - Save Position Information Context of
File . . . . . . . . . . . . . . . . . . .
.POSIT - Return Specified Record position
Information • • • • • • • • • • • • • • •
QUEUE I/O FUNCTION ROUTINE (.XQIO) • • • •
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) • •
BUFFER FLUSH ROUTINE (.FLUSH)
•••••
Purpose of the .FLUSH Routine
• • ••••••
When .FLUSH Should Be Used
Performance Considerations Using .FLUSH
Using the .FLUSH Routine •

4-22
4-23
4-23
4-24
4-25
4-25
4-25
4-26
4-27
4-28
4-28
4-28
4-28
4-29

FILE STRUCTURES

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

4-22

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

5-9

COMMAND LINE PROCESSING

6.1
6.1.1

GET COMMAND LINE (GCML) ROUTINE • • • • • • • • • 6-2
GCMLB$ - Allocate and Initialize GCML Control
Block • • • • • • • • • • •
•• • ••
• 6-3
GCMLD$ - Define GCML Control Block Offsets and
6.1.2
Bit Values • • • • • • • • • • • •
• 6-5
GCML Routine Run-Time Macros • • • • • • • • • • 6-9
6.1.3
6.1.3.1
GCML$ - Get Command Line Macro • • • • • • • • 6-9
RCML$ - Reset Indirect Command File Scan
6.1.3.2
Macro • • • • • • • • • • • •
6-12
6-12
CCML$ - Close Current Command File Macro
6.1.3.3
6.1.4
GCML Usage Considerations • • • • • • • • • • 6-13
COMMAND STRING INTERPRETER (CSI) ROUTINE • •
6-14
6.2
6.2.1
CSI$ - Define CSI Control Block Offsets and Bit
Values Macro • • •
• • • • • • • • • ••
6-14
6.2.2
CSI$ Macro Control Block Offset and Bit Value
Definitions • • • • • • • • • • •
6-15
6.2.3
CSI Run-Time Macros
• • • • • • • •
6-19
6-19
CSI$l - Command Syntax Analyzer • • • •
6.2.3.1
6.2.3.2
CSI$2 - Command Semantic Parser Macro
6-20
6-22
CSI$4 - Command Semantic Parser Macro
6.2.3.3
CSI Switch Definition Macros • • • • • •
6-23
6.2.4

CONTENTS
6.2.4.1
6.2.4.2
6.2.4.3
CHAPTER 7

CSI$SW - Create Switch Descriptor Table Entry
Macro
• • • • • • • • • • • • • • • • • ••
6-24
CSI$SV - Create Switch Value Descriptor Table
Entry Macro
• • • • • • • • • • • • • •
6-28
CSI$ND - Define End of Descriptor Table
6-31
THE TABLE-DRIVEN PARSER (TPARS)

7.1
CODING TPARS SOURCE PROGRAMS • • • • • • • • • • • 7-1
TPARS Macros: ISTAT$, STATE$, and TRAN$
• 7-1
7.1.1
7.1.1.1
ISTAT$ Macro - Initialize the State Table
• • 7-2
STATE$ Macro - Defining a Syntax Element
• 7-2
7.1.1.2
7.1.1.3
TRAN$ Macro - Defining a Transition • • • • • 7-3
Action Routines and Built-In Variables.
• • 7-5
7.1.2
7.1.2.1
TPARS Built-In Variables. • • • •
• • 7-5
Calling Action Routines
• • • • •
• 7-6
7.1.2.2
7.1.2.3
Using Action Routines to Reject a
Transition • • • • • •
••••
• 7-6
7.1.2.4
Optional Debug Routine for RSX-ll Users
• 7-6
TPARS Subexpressions • • • • • • • • • •
• 7-7
7.1.3
7.2
GENERAL CODING CONSIDERATIONS
• • • • • •
• 7-7
Suggested Arrangement of Syntax Types in a State
7.2.1
Table . . . . . . . . . . . . • . . . • . . . . 7-7
Ignoring Blanks and Tabs in a Command Line
• 7-8
7.2.2
7.2.3
Entering Special Characters
• • • • • • •
• 7-8
Recognition of Keywords
• • • • • • • • •
• 7-9
7.2.4
7.3
PROGRAM SECTIONS GENERATED BY TPARS MACROS •
7-10
7.4
INVOKING TPARS • • • • • • • • • • • • • •
7-11
7.4.1
Register Usage and Calling Conventions • •
7-11
Using the Options Word • • • •
7-11
7.4.2
7.5
HOW TO GENERATE A PARSER PROGRAM USING TPARS
7-12
PROGRAMMING EXAMPLES • • • • • •
• • • •
7-14
7.6
7.6.1
Parsing a UFO Command Line • • • • • • • • • •
7-14
Using Subexpressions and Rejecting Transitions 7-18
7.6.2
7.6.3
Using Subexpressions to Parse Complex Command
Lines . . . . . . . • . . . . . . . . . . . .
7-19
CHAPTER 8
8.1
8.2
8.2.1
8.2.2
8.3

SPOOLING
PRINT$ MACRO • • • • • •
.PRINT SUBROUTINE
Opening a File on Disk and Using the PRINT
Command
• • • •
Opening a File on LP:
ERROR HANDLING •

APPENDIX A

FILE DESCRIPTOR BLOCK

APPENDIX B

FILENAME BLOCK

APPENDIX C

SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES

APPENDIX 0

SAMPLE PROGRAMS

APPENDIX E

INDEX FILE FORMAT

E.l
E.2
E.3
E.4

BOOTSTRAP BLOCK
HOME BLOCK
.
INDEX FILE BIT MAP •
PREDEFINED FILE HEADER BLOCKS
vii

.
.

• 8-1
• • 8-1
• • 8-2
• 8-2
• • 8-2

.
.

.
.
•
•

E-l
E-l
E-2
E-2

CONTENTS
APPENDIX F
F.l
F.2
F.3
APPENDIX G

FILE HEADER BLOCK FORMAT
HEADER AREA • • • •
IDENTIFICATION AREA
MAP AREA • • •

• • F-3
• • F-4
.

. F-S

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

G.l
VOLUME AND FILE LABELS •
G.l.l
Volume Label Format • • • • • • •
G.l.l.l
Contents of Owner Identification Field
G.l.2
User Volume Labels • • • • •
G.l.3
File Header Labels • • • • •
File Identifier Processing by Files-II
G.l.3.l
G.l.4
End-of-Volume Labels •
G.l.5
File Trailer Labels
G.l.6
User File Labels • • • • •
G.2
FILE STRUCTURES • • • • • •
G.2.l
Single File Single Volume
G.2.2
Single File Multivolume
G.2.3
Multifile Single Volume
G.2.4
Multifile Multivolume
G.3
END-OF-TAPE HANDLING • • • •
• • •
G.4
ANSI MAGNETIC TAPE FILE HEADER BLOCK (FCS
COMPATIBLE)
••••••••••
THE MAGNETIC TAPE CONTROL TASK •
G.5
G.5.l
MAG Command Example
G.5.2
MAG Command Error Messages • •
• • • • •
G.6
UNLABELED TAPE • • • • • • • • • • • •
G.6.l
Block Size on Tapes Mounted /NOLABEL • • • •
G.6.2
Tape Positioning • • • • • • • • • •
G.6.3
Specifying File Attributes • • • • • • • • •
G.6.4
Tape Translation • • • • • • • • • •
Example of EBCDIC Translation Tables • • • •
G.6.5
G.7
EXAMPLE USING AN INDIRECT COMMAND FILE TO READ
TAPE • •

•

• • •

•

• • • •

APPENDIX H

STATISTICS BLOCK

APPENDIX I

ERROR CODES

APPENDIX J

FIELD SIZE SYMBOLS

APPENDIX K

RSX-llM/M-PLUS FCS LIBRARY SYSGEN OPTIONS

•

•
•
•

•

•
•
•
•
A
•

• G-l
G-l
G-2
• G-3
• G-3
• G-7
• G-B
• G-9
• G-9
• G-9
• G-9
• G-9
G-IO
G-IO
G-IO
G-IO
G-ll
G-14
G-15
G-16
G-16
G-17
G-17
G-17
G-IB
G-19

K.l
K.2

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

K-l
• • K-l

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

File Access Operation • • • • • • • • • •
• 1-2
Record I/O Operations • • • • • • • • • • •
• 1-9
Single Buffering Versus Multiple Buffering •
1-10
Directory Structure for Single-User Volumes • • • 5-3
Directory Structure for Multiuser Volumes • • • • 5-3
Data Flow During Command Line Processing • •
• 6-2
Format of Switch Descriptor Table Entry
6-2B
Format of Switch Value Descriptor Table Entry
6-30
Processing Steps Required to Generate a Parser
Program Using TPARS • • • • • • • • • • • • • •
7-13

FIGURES

viii

CONTENTS
7-2
A-I
B-1
B-2
G-l
H-l

Flow of Control When TPARS Is Called From An
7-14
Executing User Program • • • •
File Descriptor Block Format •
• •••
A-2
• B-2
Filename Block Format • • • •
• • • •
• • • • • • B-4
ANSI Filename Block Format • • • •
ANSI Magnetic Tape File Header Block (FCS
Compatible)
• • • •
G-ll
• • H-l
Statistics Block Format

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

Shared File Access • • • • • • • • • • • • •
1-13
Macro Calls Generating FOB Information • • •
• 2-2
File Access Privileges Resulting from OPEN$x Macro 3-3
R2 Control Bits for .EXTND Routine
4-26
FOB Offset Definitions • • • • • • •
• A-3
Filename Block Offset Definitions
• B-1
Filename Block Sta tus Word (N. STAT)
••••
• B-3
Filename Block Offset Definitions for ANSI
Magnetic Tape • • • • • • • • • • • • •
• B-4
Summary of I/O-Related System Directives
• C-l
Home Block Format • • • • •
••• • •
E-3
File Header Block
• • • •
• • • • • • F-l
Volume Label Format • • • •
• • • • • ••
G-l
File Header Label (HDRl)
• • • •
• G-4
File Header Label (HDR2)
• • • • • • • • G-S
File Header Label (HDR3)
•••• • •
• G-6
FCS Library Descriptions •
• K-l
.FCTYP Values • • • • • • •
• • K-2

PREFACE

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

INTENDED AUDIENCE
Because the File Control Services described in this manual pertain to
both M,ACRO-II and FORTRAN programs, the reader is assumed to be
familiar with these languages.
Also, because the development of
programs in an RSX-IIM/M-PLUS and Micro/RSX environment requires the
use of the Task Builder, the reader is also assumed to be familiar
with the contents of the RSX-IIM/M-PLUS and Micro/RSX Task Builder
Manual.

STRUCTURE OF THIS MANUAL
Chapter I describes the FCS features available for RSX-IIM/M-PLUS and
Micro/RSX users, and defines some of the terminology used throughout
the manual. This chapter is vital to understanding the balance of the
manual.
Chapter 2 describes the actions you must take at assembly time to
prepare adequately for all intended file I/O processing through FCS.
This chapter describes the data structures and working storage areas
that you must define within a particular program to use any of the
File Control Services. Until you are thoroughly familiar with this
chapter, you are advised to postpone reading subsequent chapters.
Chapter 3 describes the run-time macro calls
manipulate files and to perform I/O operations.

that

allow

you

Chapter 4 describes a set of run-time routines that perform I/O
functions on files, such as reading and writing directory entries, and
renaming or extending files.
Chapter 5 describes the structure of files for disk, DECtapes and
magnetic tapes supported by the RSX-IIM/M-PLUS and Micro/RSX systems.
Chapter 6 describes two collections of object library routines.
The
Get Command Line
(GCML)
routine and the Command String Interpreter
(CSI) routine may be linked with the user task to perform operations
that request command line input.
Such input consists of file
specifications that identify and control the files to be processed by
your program.

PREFACE
Chapter 7 describes the table-driven parser
(TPARS), which provides
you with the means to define and parse command lines in a unique
user-designed syntax.
Chapter 8 describes queuing files for printing.
You can
for printing at both the MACRO and subroutine levels.

queue

files

Finally, the appendixes provide detailed information to help you
better understand I/O operations. Appendix A and Appendix B outline
the File Descriptor Block (FOB) and the filename block,
respectively.
Appendix C summarizes a number of I/O-related system directives that
form a part of the total resource management capabilities of the
RSX-IIM/M-PLUS
Executive.
Through
simplified sample programs,
Appendix 0 illustrates the use of the macro calls that create and
initialize the FOB.
These sample programs also include some of the
macro calls used for processing files.
Appendix E illustrates the
structure of the index file of a Files-II volume.
The format and
content of the file header block, magnetic tape labels, and the
statistics
block
are
described
in Appendixes F, G,
and H,
respectively.
The error codes returned by the system are listed in
A~pendix
I.
Field-size symbols are listed in Appendix J. Appendix K
llsts RSX-IIM/M-PLUS FCS library system generation options
and
provides a brief description of each.

ASSOCIATED MANUALS
The following manuals may be useful:
•

RSX-IIM/M-PLUS Information Directory and Master Index

•

RSX-IIM/M-PLUS and Micro/RSX Executive Reference Manual

•

RSX-IIM/M-PLUS and Micro/RSX Task Builder Manual

•

PDP-II MACRO-II Language Reference Manual

In addition, documentation
languages may be helpful.

for

programming

any

the

PDP-II

CONVENTIONS USED IN THIS MANUAL
Unless otherwise noted, the term "RSX-II" refers
RSX-IIM-PLUS, and Micro/RSX operating systems.

xii

the

RSX-IIM,

SUMMARY OF TECHNI1AL CHANGES

This reVlSlon of the RSX-llM/M-PLUS and Micro/RSX I/O Operations
Reference Manual reflects the following-sQftware technical changes and
additions:
•

Support for logical names, which affects information in this
manual on file and ANSI magnetic tape specification syntax,
and filename block routines

•

Support for logical name parsing

•

Support for the CSI$4 command semantic parser

•

Changes in parameters
macros

•

New information on block locking

•

A new file control routine, .FLUSH (buffer flush)

•

Changes to the C.EXPS user task expansion buffer size offset
and to the C.CMLD command line descriptor offset in the CSI
control block

•

Changes to offsets within the File Descriptor Block

•

New volume label offsets

•

New file header format

for

the

FDAT$A,

FDOP$A,

and

OPEN$x

In addition to these changes, the manual has been reorganized to make
the information more easily accessible to the reader. Appendix C has
also been revised to include all I/O-related system
Executive
directives.

xiii

CHAPTER 1
FILE CONTROL SERVICES

This chapter describes the File Control Services
(FCS)
features
availabJLe for RSX-ll/M-PLUS and Micro/RSX users.
It defines some of
the ter~ninology used throughout the manual.
FCS enables you to
perform record-oriented and block-oriented I/O operations, as well as
additional operations required for file control. Open, close, wait,
and delete are some of these additional operations. The term FCS as
used in this manual is a substitute for FCSRES, a memory-resident
library.. This memory-resident library contains commonly used routines
that arE~ linked with your task at task-build time.
These routines may
also be linked with your task from a system object module library
(SYSLIB .. OLB). There are three kinds of FCS:
•

ANSI - supports ANSI format magnetic tape and big buffers

•

Non-ANSI - does not support ANSI tape or big buffers

•

Multibuffered - supports ANSI tape, big buffers, and
buffers

multiple

When your task uses commonly requested functions such as OPEN$, which
opens a file,
and CLOSE$, which closes a file, the Task Builder
resolves the address of these routines in FCSRES, thereby eliminating
these r()utines from your task image. Thus, commonly used FCS routines
do not significantly increase the size of your task image.
If you do
not link your task with FCSRES at task-build time, the routines must
come from SYSLIB and are included in your task image,
increasing its
size.
These routines, consisting of pure, position-independent code,
provide an interface to the file system, enabling you to read and
write files on file-structured devices and to process files by using
logical records.
Your pr()gram regards logical records as data units that are structured
in accordance with application requirements, rather than as physical
blocks of data on a particular storage medium.
To meet
the
application's requirements, FCS allows a collection of data--distinct
logical records--to be written to a file in a way that enables you to
retrieve the data from the file without having to know the exact
format in which it was written to the file.
FCS, therefore,
is
transparent to your task: records can be read or written in logical
units that are consistent with particular application requirements.
To invoke FCS functions from your task or application, your task
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 that you request (see Figure 1-1).

1-1

FILE CONTROL SERVICES

USER-ISSUED MACRO CALL

FILE CONTROL SERVICES

FILE CONTROL PRIMITIVES

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

ZK-290-81

Figure 1-1

1.1

File Access Operation

KEY TERMS USED THROUGHOUT THIS MANUAL

Listed next are terms used throughout this manual, which
definitions in the context of FCS operations.

have

unique

File Descriptor Block (FDB)
The data structure that provides FCS with information needed to
perform I/O operations on a file.
The space for this data
structure is allocated in your program by issuing the FDBDF$
macro call
(see section 2.3.1.1).
Each file to be opened
simultaneously by your program must have an associated FOB.
Portions of the FOB, which may be defined by you or the system,
are maintained by FCS. Assembly-time or run-time macro calls are
provided for you to initialize 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 (see the File Specification entry in this
section) that FCS uses.
Initially, as a file is opened, FCS
fills in the filename block with information that you specify and
that is taken from the dataset descriptor or the default filename
block
(see the next entry). Section 2.4 describes how FCS fills
in the filename block from a file specification; the format and
content of the filename block are described in Appendix B.
DefauLt Filename Block
An area allocated within your program by issuing the NMBLK$ macro
call
(see Section 2.5.2) that contains the various elements of a
file specification.
You create the default filename block,
whereas the filename block within the FOB is maintained by FCS.
You create the default
filename
block
to
supply
file
specifications to FCS that are not otherwise available through
the dataset descriptor (see the next entry).
FCS takes these
file specifications and creates a parallel structure in the FOB
that contains information that FCS requires during execution time
in opening and operating on files.

1-2

FILE CONTROL SERVICES
Thus, the terms "default filename block" and "filename block"
refer
to
separate
and
distinct data structures.
These
distinctions should be kept in mind whenever these terms appear
in this manual. These areas are structurally identical, but they
are created and used differently, and may contain different
information at different times.
Dataset Descriptor
A 6-word block in your program that contains the sizes and the
addresses of ASCII data strings that together constitute a file
specification (see Section 1.9). This 6-word block, which you
also create, is described in detail in Section 2.4.1. Unless the
filename block in the FOB has been initialized, you must provide
FCS with dataset-descriptor or default filename block information
before the specified file can be opened.
Dataset Descriptor Pointer
An address value that points to the 6-word dataset descriptor
within your program.
This address value is stored in the FOB,
allowing FCS to access a file specification that you created in
the dataset descriptor.
File Specification
The unique file identification that names a file, specifies the
location, and allows it to be explicitly referenced by any task.
The operating system, or your task, must refer to files by using
a file specification. The file specification contains specific
information that must be made available to FCS before that file
can be opened.
See Section 1.9 for a description of a file
spE~cification.

File Storage Region (FSR)
An area of memory that you reserve for use in I/O operations (see
Section 1.7.3). You can allocate this area by issuing the FSRSZ$
macro call in your program (see Section 2.7).

1.2

IMPORTANT FCS CHARACTERISTICS

You should be aware of the following FCS
its I/O facilities:

characteristics

when

using

I/O operations initiated by READ$ and WRITE$ macros are
• asynchronous;
you are responsible for coordinating all block
I/O activity.
•

I/O operations initiated by GET$ and PUT$
macros
are
synchronized entirely by FCS; control is not returned to your
program until the requested GET$ or PUT$ operation
is
complete.

•

FCS macro calls save and
following exceptions:

restore

registers,

with

the

The file-processing macro calls (see Chapter 3)
File Descriptor Block (FOB) address in RO.

place

the

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

1-3

all

return

FILE CONTROL SERVICES
•

The macro that defines and allocates the space for the File
Descriptor Block
(FOB)
is the FDBDF$ macro
(see Section
2.3.1.1). Once the FOB is allocated, necessary information
can be placed in this data construct through any logical
combination of assembly-time or run-time macro calls
(see
Sections 2.3.1 and 2.3.2, respectively). Certain information
must be present in the FOB before FCS can open and operate on
a specified file.

•

For each assembly-time FOB initialization macro call, a
corresponding run-time macro call is provided that supplies
identical information. Although both sets of macro calls (see
Table 2-1 in Section 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 Carry bit in the Processor Status Word is
set, and an error indicator is returned to FOB offset location
F.ERR.
NOTE
When you use the READ$ or WRITE$ macros to execute
system I/O,
the 10SB parameter must be specified for
F.ERR and the Carry bit to be properly returned
(see
Section 3.15).

If the address of a user-defined error-handling routine is specified
as a parameter in any of the file-processing macro calls, a JSR PC
instruction to that error-handling routine is generated. The routine
is then executed if the Carry bit in the Processor Status Word is set.

1.3

FCS DATA STRUCTURES

In addition to generating calls to FCS subroutines, FCS macros issued
by your task create and maintain certain data structures that file I/O
operations require.
These required data structures include the
following:
•

A File Descriptor Block
(FOB)
that
necessary for processing the file.

•

A dataset descriptor that FCS accesses to obtain ASCII
name information required to open a specified file.

•

A default filename block that FCS accesses to obtain default
file name information to open a specified file. FCS accesses
the default filename block when complete file information is
not specified in the dataset descriptor.

•

A file storage region (FSR) that FCS uses for working storage.
The FSR is described in Section 1.3.3.

1-4

contains

information
file

PILE CONTROL SERVICES
1.3.1

F'ile Descriptor Block (PDB)

The File Descriptor Block (FOB) contains information that FCS uses to
open and process files.
One FOB is required for each file that your
program opens simultaneously. You initialize some portions of the FOB
with assembly-time or run-time macro calls, and FCS maintains other
portions. Each FOB has five sections that contain information that
your task or the system defines:
•

File attribute section

•

Record or block access section

•

File open section

•

Block buffer section

•

Filename block portion

The information stored in the FOB depends upon the characteristics of
the file to be processed.
The FOB and the macro calls that cause
values to be stored in this structure are described in detail
in
Section 2.3.
Appendix A describes the format and the content of the
FOB.

1.3.2

Dataset Descriptor and Default Filename Block

You must specify either a dataset descriptor or a default filename
block for each file that you intend to open. These data structures
provide FCS with the file specifications required for opening a
file.
Although either the dataset descriptor or the default filename block
is usually specified, you may also specify both for the same file.
The dataset descriptor and the default filename block are further
described in detail in Sections 2.5.1 and 2.5.2.
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.6 describes this
process in detail.

1.3.3

File Storage Region (PSR)

The filE! storage region (FSR) is an area allocated in your program as
working storage for record I/O operations (see Section 1.7). The FSR
consists of two program sections that are always contiguous.
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.
You
determine the size of this area at assembly time by
issuing the FSRSZ$ macro call (see Section 2.7).
The
number of block buffers and associated headers is based
on
the number of files that you intend to open
simultaneously for record I/O operations.

1-5

FILE CONTROL SERVICES
$$FSR2 - This area of the FSR contains impure data that FCS uses
and maintains when performing both record and block I/O
operations.
Portions of this area are initialized at
task-build time,
and other portions are maintained by
FCS.
The size of the FSR can be changed, if desired,
Section 2.8 shows you how to do this.

1.4

task-build

time.

FILE ACCESS METHODS

RSX-IIM/M-PLUS and Micro/RSX systems support both sequential and
random access to data in files on sequential access devices (such as
magnetic tapes and card readers) and random access devices
(such as
disks).
The sequential access method is device independent; that is,
sequential access is usable on both record-oriented and random access
devices
(for example, card reader and disk).
You can use the random
access method only for random access devices.

1.5

DATA FORMATS FOR FILE-STRUCTURED DEVICES

Data is transferred between peripheral devices and memory in blocks.
A data file consists of virtual blocks, each of which may contain one
or more logical records created by your program.
In FCS terms,
a
virtual block in a file consists of 512(decimal) bytes for random
access devices.
The size of the logical records in the virtual blacks
is under the control of the program that originally wrote the records.
When creating a new file, your program can specify that the records in
the
file
will
differ
in size.
Such records are known as
variable-length records. Conversely, if your program indicates that
all records in the new file will be equal in size, the records are
known as fixed length.
There are two types of variable-length records:
sequenced and
nonsequenced.
Both must be word aligned. Sequenced variable-length
records are preceded by a 2-word record header.
The first word
contains the length of the record, and the second word contains the
value of the sequence number:

L..-B_y_t_e_c_o_u_n_t--L..s_e_q_u_e_n_c_e_N_u_m_b_e_r_-L-_n_-_2_b_y_t...",ef of da ta
Nonsequenced variable-length records are preceded
record header containing the length of the record:

I
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
simply ignored.
(The extra byte is not necessarily a 0 byte.)

1-6

FILE CONTROL SERVICES
virtual blocks and logical records within a file are numbered
sequentially, each starting at 1. A virtual block number is a file
relative value, whereas a logical block number is a volume relative
value.
Ordinarily, records may cross block boundaries. Crossing
block boundaries 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.5.1

Data Formats for ANSI Magnetic Tape

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

tape;

On magnetic tape, 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 from 8 through 2048 bytes (14 through 2048 bytes for a
write function) with the use of the FDBF$ macro (see Section 2.3.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 word boundary immediately following the last
record that will fit in the block buffer.
Variable-length records are preceded by a 4-byte count
field,
expressed in decimal in ASCII characters. The count includes the
length of the record and the 4-byte count field.
After the last
record in a block (if there is any space left in the block), a caret
character ("~", ASCII code 136) appears where the next byte count
should be, signaling the end of data in that block.

1. 6

BI~OCK

I/O OPERATIONS

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

1-7

FILE CONTROL SERVICES
1.7

RECORD I/O OPERATIONS

Sequential access mode I/O operations can be performed for both
fixed- and variable-length records.
Random access mode I/O operations
can be performed only for fixed-length records.
Your program accesses
records
randomly
by specifying a record number.
This number
represents the position of the desired record within the file (viewing
the file as an array of fixed-sized records, with the number 1
representing the first record physically present in the file,
and n
the last).
The GET$ and PUT$ macro calls
(see Sections
3.9
and
3.12,
respectively) are provided for processing individual records in files.
Using the FSR block buffers (see Section 1.3.3), the GET$ and PUT$
routines perform the necessary blocking and deblocking of records
within the virtual blocks of the file, allowing your program to access
logical records. Successive GET$ or PUT$ operations in random access
mode can access records anywhere within the file.
To do so, your
program need only modify the record number specified as part of the
random record operation.
After each such random operation, FCS
increases by one the record number used in the operation.
If your
program does not again modify this number prior to issuing another
record operation, the record actually accessed is the next sequential
record in the file.
In contrast to block I/O operations, all record I/O operations are
synchronous;
that is, control is returned to your program only after
the requested I/O operation is completed.
Because GET$ or PUT$ operations process logical records within a
virtual block, only a limited number of GET$ or PUT$ operations result
in an actual I/O transfer (for example, when the end of a data block
is reached).
Therefore, all GET$ or PUT$ I/O requests do not
necessarily involve an actual physical transfer of data.
The data flow during record I/O operations is shown 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 occurs in the FSR block buffer, and
the blocking of records occurs in the FSR block buffer during output.
Note also that FCS serves as your task's interface to the FSR block
buffer pool. All record I/O operations, which are initiated through
GET$
and
PUT$
macro
calls, are synchronized by Fes unless
multibuffering is in use.

1-8

FILE CONTROL SERVICES

BLOCK
BUFFER
POOL

r~-------~'-------,

FCS

DEVICE

USER
RECORD
BUFFER

$$FSR2
IMPURE DATA

ZK-291-81

Figure 1-2

1.7.1

Record I/O Operations

Record I/O Data-Transfer Modes

By using record I/O, a program can gain access to a record in either
of the two following ways after the virtual block has been transferred
into the FSR from a file:
•

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

•

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

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

1-9

FILE CONTROL SERVICES
1.7.1.2 Locate Mode - Locate mode enables your task to access records
directly in the FSR block buffer. Consequently, there is normally no
need to transfer data from the FSR block buffer to your task's record
buffer.
To access records directly in the FSR block buffer, refer to
locations in the File Descriptor Block (see Section 1.3.1 and Appendix
A)
that contain values defining the length and the address of the
desired record within the FSR block buffer. These values are present
in the FOB as a result of FCS macro calls that you issued.
Program overhead is reduced in locate mode because records can be
processed directly within the FSR block buffer. Moving data to your
task's record buffer in locate mode is required only when the last
record of a virtual block crosses block boundaries.

1.7.2

Multiple Buffering for Record I/O

By supporting multiple buffers for record I/O, FCS provides the
ability in multibuffered FCS
(see Appendix K)
to read data into
buffers in anticipation of user program requirements, and to write the
contents of buffers while your program is building records for output.
You can thus overlap the internal processing of data with file I/O
operations, as illustrated in Figure 1-3.
When your task uses read-ahead multiple buffering, the file must be
sequentially accessed to derive full benefit from multiple buffering.
For write-behind multiple buffering, you can use any file access
method with full benefit.
When your task uses multiple buffering, you must allocate sufficient
space in the FSR for the total number of block buffers in use at any
given time. The FSRSZ$ macro call (see Section 2.6.1) allocates space
for FSR block buffers.
Time

Single
Buffer

process record

write record

process record

write record

Multiple
Buffer

process record

write record
process record

process record
write record

write record
process record

ZK-292-81

Figure 1-3

Single Buffering Versus Multiple Buffering

1.7.2.1 Multiple Buffering Performance - Multiple
buffering
can
improve performance for I/O-bound tasks under certain circumstances.
However, multibuffer processing in random mode is not very efficient.
When using multibuffering in random mode, a user record buffer is
always required.
If one is not supplied, the task's low memory may be
overwritten and the task may abort.

1-10

FILE CONTROL SERVICES
For example, consider an I/O-bound task running as the dedicated or
highest priority application on a system. For such a task, multiple
buffering can decrease execution time by enabling overlap of I/O and
task execution.
However,> if other tasks run at the same priority as that of the
application task described previously, then an overlap of I/O and task
execution is already achieved among these tasks without multiple
buffering.
In this case, multiple buffering would use up address
space and pool without improving execution speed.
If virtual and
physical address space is available, big buffering would improve
performance (see Section 1.7.3). However, big buffer processing in
random mode is not very efficient.

1.7.3

Big Buffering for Record I/O

If the task uses large records or operates on clusters of records, big
buffering is advantageous. The use of big buffering assumes that it
is reasonable to use more task address space and physical memory for
increased buffer space, and more pool for the increased number of
outstanding I/O packets.
Big buffering reduces the number of disk accesses by allowing
multiblock input and output. Normally, the disk accesses for GET$ or
PUTS operations are performed one sector at a time.
Using FCS big
buffers allows you to read or write a specified number of sectors in a
single operation.
When using big buffering in random mode, a user record buffer is
always required.
If one is not supplied, the task's low memory may be
overwritten and the task may abort. Using big buffering with random
GET$ and PUTS can cause data to be lost from the end of a file.
In
this case, a directory of the file would indicate more blocks in use
than it had allocated.
To prevent this condition from happening,
follow these steps:
•

Preallocate enough
unnecessary.

space

make

writing

extension

•

Execute a FLUSH operation after the highest-numbered record is
written by a PUTS macro.

•

After a PUTS macro, arrange not to execute any GET$ macro that
could cause the file to extend.

To use big buffers, you must select the buffer size and specify that
buffer size in the parameter lists for each occurrence of both the
FSRSZ$ macro and the FDBDF$ macro in your program.
You should choose a buffer size that is a multiple of 5l2(decimal)
bytes, the size of one disk block.
Because the default amount
allocated by a file extend is five blocks and disks often contain many
5-block files or parts of files,
a buffer size of five blocks is
generally a good choice. Larger amounts may increase performance, but
note that you are trading large amounts of memory for speed.
You must reserve the buffer space in your program and you must specify
the buffer size to the FDB. The FSRSZ$ macro allows you to specify
the total buffer space needed. Specify 5l2(decimal) bytes for each
normal disk file, plus the buffer size that you have selected for each

1-11

FILE CONTROL SERVICES
big buffered file.
For example, assume that a program has three
files:
one normal file (5l2-byte buffer); one file with a big buffer
size of three blocks; and one file with a big buffer size of five
blocks.
The following call to the FSRSZ$ macro reserves the space
properly:
FSRSZ$

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

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

,<5*512.>

On RSX-llM-PLUS and Micro/RSX systems, the SYSLIB provided as the
default library contains all the proper ~CS modules for big buffer
support. RSX-11M user tasks must link to ANSLIB for these modules.

1.8

SHARED ACCESS TO FILES

The Files-II disk architecture permits shared access to
files
according to established conventions. You can issue one of two macro
calls, among several available in FCS for opening files,
to invoke
these
conventions.
The
OPNS$x macro call
(see Section 3.2)
specifically opens 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 subsequently issued.
Both macro calls take an
alphabetic suffix that specifies the type of operation being requested
for the file, as follows:
R - Read existing file
W - Write (create) a new file
M - Modify existing file without extending its length
U - Update existing file and extend its length, if necessary
A - Append data to end of existing file
The suffix R applies to the reading of a file, whereas the suffixes W,
M, U, and A all apply to the writing of a file. You can use the
OPNS$x and OPEN$x macro calls as follows for shared access to files:
1.

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

While FCS allows concurrent write-access requests through the
use
of the OPNS$W, OPNS$M, OPNS$U, and OPNS$A macro,
synchronizing
access
to
the
file
is
your
task's

1-12

FILE CONTROL SERVICES
of
responsibility.
To avoid the retrieval or storage
inconsistent data, each task must implement and use some
mechanism, which you define, ensuring that the file is
serially accessed.
3.

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 previous text that readers of a shared file should be
aware that the file may yield inconsistent data from request to
request if that file is also being written.
Shared access during reading does not necessarily mean that the access
requests are all from separate tasks. A file could also be shared by
a single task that has opened the file on several different logical
unit numbers.
Table 1··1 shows the circumstances under which Fi les-11 permi ts
second file access when the file is opened for shared access.

Table 1-1
Shared File Access
First Access
Read

Shared read

Write

Shared write

Read

Yes

Shared
Reiad

Yes

Write

Yes

Sh,ared
Write

Yes

Second Access

1.9

FILE SPECIFICATION SYNTAX

A full file specification has the following
listed:

elements,

device
directory
name
type
version
A file specification has the following format:
device: [directory]filename.filetype;version
An example of a full file specification follows:
LB: [l,*]SUPLIB.OLB;O is a full file specification.

1-13

the

order

FILE CONTROL SERVICES
1.9.1

Device

The device element of the file specification names the device on which
the file resides. For unit-record devices, such as terminals and line
printers,
this
is the only significant element
in
the
file
specification.
Except for logical names, the device specification consists of two
alphabetic characters specifying the device name, followed by 0- to
3-character octal numeric string specifying the device unit number,
followed by a colon (:). FCS converts lowercase alphabetic characters
to uppercase befQre passing them to the operating system. The device
unit number must not exceed 377 octal; if no unit number is given, FCS
assumes unit O.
For example:
db2: and DB02: are equivalent device specifications.
SY: and syOO: are equivalent device specifications.
login: and LOGIN: are equivalent logical device specifications.

1.9.2

directory

the

FILENAME STRING DESCRIPTOR
Word 5 -

Contains the length
filename string.

(in

bytes)

ASCII

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

2-29

PREPARING FOR I/O
separated by a period (.), and the file version
number
must be preceded by a semicolon.
A
filename string may be created as shown following:
FILNM: .ASCII

/PROGI.OBJ;7/

For Files-II, only the characters A through Z and
o through 9 may be used in composing an ASCII
filename string. An ANSI magnetic tape filename
string may contain, in addition, the following
special characters:
SP !

" % &

(

)

* + , - . /

; <=> ?

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

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

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

;7
NOTE

The semicolon is a legal character in the
name string. To delimit a version number,
the semicolon must be outside the quoted
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 your program.
For example,
the
following code creates a dataset descriptor containing only a 2-word
ASCII filename string descriptor:
FDBOUT: FDBDF$
FDAT$A
FDRC$A
FDOP$A

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

OFDSPT:

.WORD
• WORD
.WORD

0,0
0,0
ONAMSZ,ONAM

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

ONAM:
• ASC I I
ONAMSZ=.-ONAM

/OUTPUT.DAT/

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

2-30

PREPARING FOR I/O
Note first that an FOB labeled FDBOUT is created.
Observe further
that the FDOP$A macro call takes as its second parameter the symbol
OFDSPT. This symbol represents the address value stored in FOB offset
location F.DSPT.
This value enables the .PARSE routine (see Section
4.7.2) to access the fields of the dataset descriptor in building the
filename! block.
The symbol OFDSPT also appears in the label field of the first
.WORD
directive, defining the address of the dataset descriptor for the
.PARSE routine. The .WORD directives each allocate two words of
storage for the device name descriptor, the file directory descriptor,
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 two 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 to the dataset descriptor. For each such ASCII
string lreferenced in the dataset descriptor, however, corresponding
statements must appear elsewhere in the source program to define the
appropriate ASCII data string(s).
A dataset descriptor for each of several files to be accessed by
program may be defined in this manner.

2.5.2

your

Default Filename Block - NMBLK$ Macro

As noted earlier, you may also define a default filename block in the
program as a means of providing required file information to FCS. For
this purpose, you can issue the NMBLK$ macro call in connection with
each FOB for which a default filename block is to be defined. When
this macro call is issued, space is allocated within your program for
the default filename block, and the appropriate locations within this
data structure are initialized according to the parameters supplied in
the call.
Note in the parameter descriptions in the following text 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.
Format
label:

NMBLK$ fnam,ftyp,fver,dvnm,unit

Parameter
label
A symbol, which you define, 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.

2-31

PREPARING FOR I/O

fnam
The default file name. This parameter may consist of up to nine
ASCII characters. The character string is stored as six bytes in
Radix-50 format, starting at offset location N.FNAM of the
default filename block.
ftyp
The default file type. This parameter may consist of up to three
ASCII characters. The character string is stored as two bytes in
Radix-50 format in offset location N.FTYP of the default filename
block.
fver
The default file version number {binary}. When specified, this
binary value identifies a particular version of a file.
This
value is stored in offset location N.FVER of the default filename
block.
dvnm
The default name of the device upon which the volume containing
the desired file is mounted.
This parameter consists of two
ASCII characters that are stored in offset location N.DVNM of the
default filename block.
unit
A binary value identifying which unit {among several like units}
is to be used in processing the file.
If specified, this numeric
value is stored in offset location N.UNIT of the default filename
block.
Only the alphanumeric characters A through Z and 0 through 9 may be
used
in composing the filename and filetype strings discussed
previously. Although the file version number and the unit number
discussed previously are binary values, these numbers are normally
represented in octal form when printed, when input by a command
string, or when supplied through a dataset descriptor string.
As evident from the foregoing, all the default information supplied in
the NMBLK$ macro call is stored in the default filename block at
offset locations that correspond to identical fields in the filename
block within the 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:
•

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.2}, which is invoked as a result of
issuing any version of the generalized OPEN$x macro call.

•

A dataset descriptor has not been created in your program.

•

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

2-32

PREPARING FOR I/O
The following code illustrates the general method
NMBLK$ macro call:
FDBOUT: FDBDF$
FDAT$A
FDRC$A
FDOP$A
FDBIN:

~~M:

IFNAM:

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

specifying

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 FILE NAME AND FILE TYPE.
INPUT,DAT"DT,1 iESTABLISHES FILE NAME, FILE TYPE,
iDEVICE NAME, AND UNIT NUMBER.

The first NMBLK$ macro call in the previous coding sequence 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 your program.
Note that this symbol is specified as the dfnb parameter in the FDOP$A
macro call associated with this default filename block to initialize
the file open section of the corresponding FOB.
The accompanying
parametE!rS in the first NMBLK$ macro call define the file name 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 thH latest version of the file is desired. All other parameter
fields contain explicit declarations defining default information for
the applicable FOB.
You can define the offsets for a filename
program by issuing the following macro call:

block

locally

your

NBOF$L
This macro call does not generate any code.
Its function is merely to
define the filename block offsets locally, presumably to conserve
symbol table space at task-build time. The NBOF$L macro call need not
be issued if the FDOF$L macro call has been inVOked, because the
filenamE~ block offsets are defined locally as a result of issuing
the
FDOF$L macro call.
If you want, you may initialize fields in the default filename block
directly with appropriate values.
You can do this by placing 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

2-33

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

2.5.3

Dynamic Processing of File Specifications

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

2.6

OPTIMIZING FILE ACCESS

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

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

•

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

•

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

2-34

PREPARING FOR I/O
These three fields are written into the filename block in one of three
ways:
•

By issuing any version of the generalized OPEN$x
for a file associated with the FOB in question.

•

By initializing the filename block manually by using the
• PARSE routine (see Section 4.7.1) and the .FINO routine (see
Section 4.8.1).

•

By moving the necessary values into the filename block.

Opening an existing file by file 10 is a
3. 5) •

2.6.1

special

case

macro

(see

call

Section

Initializing the Filename Block as a Function of OPEN$x

To understand how to effect the process of opening a file by file 10,
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.2). The .PARSE routine is linked into your program,
along with the code for OPEN$x.
This routine first zeros the filename
block and then fills
it in with information taken from the dataset
descriptor and the default filename block, or both.
Thus, issuing the generalized OPEN$x macro call
invokes 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 your task's memory space and later
restored to the FOB at the desired point in program flow for use in
reopening that same file.
Your task can reopen files in this manner because FCS is sensitive to
the presence of any nonzero value in the first word of the file
identification field of the filename block. When your task
invokes
the OPEN$x function, FCS first examines offset location N.FIO 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 10.
To ensure that an undesired value does not remain in the first word of
the N.FID field from a previous OPEN$x or CLOSE$ sequence, the first
word of this field is zeroed as the file is closed.
In opening files by file 10, you need only ensure that manual saving
and r~~storing of the filename block are accomplished with in-line MOV
instructions that are consistent with the desired sequence
of
processing files.
This process should proceed as follows:
1.

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

Save the filename block by copying it into your task's memory
space with appropriate MOV instructions.
The filename block
begins at offset location F.FNB in the file descriptor block
(FOB) •
2-35

PREPARING FOR I/O
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.5.2) may be invoked in your program
to define these symbols locally. These symbolic values may
be used in appropriate MOV instructions to accomplish the
saving and restoring of the filename block.
Moreover, you
must reserve sufficient space in the program for saving the
filename block.
3.

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

the

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

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

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

2.6.2

Manually Initializing the Filename Block

In addition to saving and restoring the filename block in anticipation
of reopening a file by file 10, you can also initialize the filename
block manually.
If you choose to do so, the .PARSE and .FINO routines
(see Sections 4.7.2 and 4.8.1,
respectively)
may be invoked at
appropriate points to build the required fields of the filename block.
After the • PARSE and .FINO 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 10.
Occasionally,
instances arise that make such manual
operations
desirable, especially if your program is operating in an overlaid
environment.
In this case, it is highly desirable that the code for
opening a file be broken into small segments in the interest of
conserving memory space. Because 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 OFIO$
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 OFIO$ or the OFNB$ code on one branch of the overlay and
the .PARSE and .FINO code on another branch. Then, if you want your
task to open a file by file 10, the .PARSE and .FINO routines can be
invoked at will to insert required information in the filename block
before opening the file.
2-36

PREPARING FOR I/O
The OFID$ macro call can be issued only in connection with an existing
file.
The OFNB$ macro call, on the other hand, may be used for
opening either an existing file or for creating and opening a new
file.
In addition, the OFNB$ macro call requires only the manual
invocation of the .PARSE routine to build the filename block before
opening the file.
If conservation of memory is an objective, and if your program will be
opening both new and existing files, it is recommended that only the
OFNB$ routine be included in one branch of the overlay; including the
OFID$ routine would needlessly consume memory space.
In all cases, however, it is important to note that all the macro
calls for opening existing files are sensitive to the presence of any
nonzero value in the first word (N.FID) of the filename block.
If
this
field
contains
any
value
other than 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) puts zeros in 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 your task later intends to open a file by
file 1D 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.7

INITIALIZING THE FILE STORAGE REGION

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

2.7.1

initialization

the

FSR

are

FSRSZ$ - Initialize FSR at Assembly Time

The MACRO-II programmer establishes the size of the FSR at assembly
time by issuing an FSRSZ$ macro call.
This macro call does not
generate any executable code.
It merely allocates space for a
block-·buffer pool in a program section named $$FSRI. The amount of
space allocated depends on information provided by you, or defaulted,
during the macro call.

2-37

PREPARING FOR I/O
NOTE
The FSRSZ$ macro allocates the Fes impure area that is
pointed to by a fixed location in your task's 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.
Format
FSRSZ$

fbufs,bufsiz,psect

Parameter
fbufs
A numeric value that you establish as follows:
•

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

No other parameters need be specified unless the
the psect parameter is required.
•

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,
you might want to access simultaneously three files for block
I/O and two files for record I/O.
You would specify the
following FSRSZ$ macro call:
FSRSZ$

Additional
parameters,
bufsiz
and
psect
subsequently) could also be specified as required.
•

function

(described

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

This macro call indicates that a maximum of seven buffers will
be in use simultaneously.,
This total is calculated as
follows:
one buffer for the single-buffered file and two
buffers
for
each
of the three double-buffered files.
Additional parameters, bufsiz and psect
(described next),
could also be specified as required.

2-38

PREPARING FOR I/O
bufsiz
A numeric value defining the total block buffer pool space
(in
bytes)
needed to support the maximum number of files that can be
open simultaneously for record I/O.
If this parameter is
omitted, FCS obtains a total block buffer pool requirement by
multiplying the value specified in the fbufs parameter with a
default buffer size of 512 bytes.
If, for example, a maximum of
two single-buffered disk files will be open simultaneously for
record I/O, either of the following FSRSZ$ macro calls could be
issued:
FSRSZ$

FSRSZ$

2,1024.

If you want your task to explicitly specify block buffer
requirements, the following formula must be applied:

pool

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

Section

2.3.1.6)

The total value expressed by the bufsiz parameters must
always represent the worst case buffer pool requirements
among all combinations of simultaneously open record I/O
files.
The number of files (or buffers) representing the
worst case is expressed as the first parameter of the macro
call.
NOTE
If you use RSX-IID, you must not allocate an FSR
block buffer less than 512(decimal) bytes in length
for spooled output to a record-oriented device (such
as a line printer).
psect
The name of the program section (PSECT) to which control returns
after FSRSZ$ completes processing.
If no name is specified,
control returns to the blank PSECT.

2-39

PREPARING FOR I/O
2.7.2

FINIT$ - Initialize FSR at Run Time

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

FINIT$

Parameter
label
An optional symbol, which you specify, 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.
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 shown in the third
paragraph following.
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
;AND OPENS THE FILE.

#FDBIN

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

FINIT$
OPEN$R

#FDBIN

;EXPLICITLY INITIALIZES THE FSR AND
;OPENS THE FILE.

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

2-40

PREPARING FOR I/O
2.8

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 Sections 2.8.1 and 2.8.2.

2.8.1

FSR Extension Procedures for MACRO-II Programs

Increase the size of the FSR
either of these procedures:

for

MACRO-II

program

following

•

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, specify the command in the following form:
EXTSCT

= $$FSRl:length

Parameter
$$FSRI
The symbolic name of the program section within the FSR
that is reserved as the block buffer pool length. A
numeric value defining the total required size of the
buffer pool in bytes.
The size of the FSR cannot be reduced at task-build time.
In calculating the total length of the FSR, you can use either of
formulas:
•
•

the

= (S.BFHD*fbufs)+bufsiz
Length = fbufs*(S.BFHD+S12.)

Length

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

DEF$L

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

2-41

PREPARING FOR I/O
bufsiz
A numeric value defining the total block buffer pool
space
(in bytes) needed to support the maximum number of
files that can be open simultaneously for record I/O.
Refer to the description of this parameter in the FSRSZ$
macro call in Section 2.7.1.
512.
The standard default buffer size.
The EXTSCT option is described in detail
Micro/RSX Task Builder Manual.

2.8.2

the

RSX-llM/M-PLUS

and

FSR Extension Procedures for FORTRAN Programs

For a FORTRAN program, if an explicit ACTFIL option is not issued to
the Task Builder, an ACTFIL statement with a default value of 4 is
generated during task build. You may extend the size of the FSR at
task-build time by issuing the command:
ACTFIL = files
where files is a decimal value defining the maximum number
that may be open simultaneously for record I/O processing.

files

This command, like the EXTSCT command described previously, 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 previously, 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 option is described in detail in
Builder Reference Manual.

2.9

the

RSX-llM/M-PLUS

Task

COORDINATING I/O OPERATIONS

Your programs perform all I/O operations by issuing GET$ or PUT$ and
READ$ or WRITE$ macro calls.
(See Chapter 3 for a complete discussion
of these file-processing macro calls.) 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 macro called Queue I/O
(QI0$, QIO$C, or QIO$S) 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 RSX-ll systems. Although transparent to your
task, the QUEUE I/O directive is used for all FCS file access
operations.
When invoked, the QIO$ macro 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.

2-42

PREPARING FOR I/O

As implied previously, two separate and distinct
involved in accomplishing a specified I/O transfer:

processes

are

The successful queuing of the GET$ or PUT$ or READ$ or WRITE$
I/O request

The successful completion
operation

the

requested

data

transfer

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

2.9.1

Event Flags

I/O opelrations 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. The system executes operations that manipulate,
test, and wait for these indicators of internal task activity.
The completion of an I/O transfer, for example, is recognized by the
system as a significant event.
If you have specified a particular
event flag to be used by the task in coordinating I/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 (decimal) may be defined for local use by the task.
If you have not
specified an event flag, FCS uses event flag 32(decimal) by default to
signal the completion of I/O transfers.
Specific FOB-initialization and I/O-initiating macro calls in FCS
enable you to specify event flags, if desired, that are unique to a
particular task and that are set and reset only as a result of that
task's operation.
For record I/O operations, such an event flag may be defined through
the efn parameter of the FDBF$A or the FDBF$R macro call (see Section
2.3.1.6 or 2.3.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.3.1.4 or 2.3.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).
In both record and block I/O operations, the event flag is cleared
when the I/O request is queued and set when the I/O operation is
completed.
In the case of record I/O operations, only FCS manipulates
the event flag. Additionally, the event flag's state is transparent
to YOUl: task, which must not issue a WAITFOR system directive
predicated on the event flag used for coordinating record I/O
operations. A record I/O operation, for example, may not even involve
an I/O transfer; rather, it may only involve the blocking or
deblocking of a record within the FSR block buffer.
On the other
hand, the event flag defined for synchronizing block I/O operations is
totally under your control.
2-43

PREPARING FOR I/O
Also, a code indicating the success or failure of the QIO$ macro
request resulting from the READ$ or WRITE$ macro call is returned to
the Directive Status Word ($DSW).
If desired, symbolic location $DSW
may be tested to determine the status of the I/O request.
The
success/failure codes for the QIO$ macros are listed
in
the
RSX-IIM/M-PLUS I/O Drivers Reference Manual and the Micro/RSX I/O
DrIvers Reference Manual.
Event flag directives are described in the RSX-IIM/M-PLUS
and
Micro/RSX Executive Reference Manual.
The relationshIp of event flags
to specIfic devIces IS described in the RSX-IIM/M-PLUS I/O Drivers
Reference Manual and the Micro/RSX I/O Drivers Reference Manual.

2.9.2

I/O Status Block

Because of the comparative complexity of block
I/O operations,
an
optional parameter is provided in the FDBK$A and the FDBK$R macro
calls, as well as in the READ$ and WRITE$ macro calls,
that enables
the system to return status information to your task for block I/O
operations.
The I/O status block is not applicable to record
I/O
(GET$ or PUT$) operations.
This optional parameter, called the I/O status block address, is made
available to FCS through any of the macro calls identified previously.
When this parameter is supplied, the system returns status information
to a 2-word block reserved in your program.
Although the I/O status
block is used principally as a QIO$ macro housekeeping mechanism for
containing
certain device-dependent information,
this area also
contains information of particular interest to you.
Specifically, the second word of the I/O status block is filled
in
with the number of bytes transferred during a READ$ or WRITE$
operation. When you are performing READ$ operations,
it is good
practice to use the value returned to the second word of the I/O
status block as the number of bytes actually read,
rather than to
assume that the requested number of bytes was transferred.
Employing
this technique allows the program to properly read virtual blocks of
varying length from a device such as a magnetic tape unit, provided
that the requested byte count is at least as large as the largest
virtual block.
For WRITE$ operations, the specified number of bytes
is always transferred~ otherwise, an error condition exists.
Also, the low-order byte of the first word of the I/O status block
contains a code that reflects the final status of the READ$ or WRITE$
operation. The codes returned to this byte may be tested to determine
the status of any given block I/O transfer.
The binary values of
these status codes always have the following significance:
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
RSX-llM/M-PLUS I/O Drivers Reference Manual or the Micro/RSX I/O
DrIvers Reference-Manual.

2-44

PREPARING FOR I/O
If the ciddress of the I/O status block is not made available to FCS
(and hence to the QIO$ macro) through any of the macro calls noted
previously, no status information is returned to the I/O status block.
In this case,
the fact that an error condition may have occurred
during a READ$ or WRITE$ operation is simply lost.
Thus, supplying
the address of the I/O status block to the associated FOB is highly
desirable and makes normal error reporting easier.
An I/O status block may be defined in your task at assembly time
through any storage directive logically equivalent to the following:
IOSTAT:

• BLKW

where IOSTAT is a symbol, which you define, naming the I/O status
block and defining ~ts address.
This symbolic value is specified as
the bkst parameter 1n the FDBK$A or the FDBK$R macro call to
initialize FOB 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 FOB is an integral part of issuing the
desired I/O request.

2.9.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 intel~rupted and control to be transferred to another instruction
sequencE~
elsewhere in the program.
If desired, you may specify the
address of an AST service routine that is to be entered upon
completion of a block I/O transfer. Because an AST is a trap action,
it constitutes an 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.3.1.4 or 2.3.2, respectively): this parameter may also be specified
in the READ$ or the WRITE$ macro call, initializing the FOB 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 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
continuE~s •
The main purpose of an AST service routine is to inform your task that
a block I/O operation has been completed, thus enabling the program to
continuE~ immediately with some other desired
(and perhaps logically
dependent) operation (for example, another I/O transfer).
If an AST service routine is not provided by you, 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, you 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.

2-45

PREPARING FOR I/O
Implementing an AST service routine in your program is application
dependent
and must be coded specifically to meet your task's
particular I/O-processing requirements.
A detailed discussion of
asynchronous system traps is beyond the scope of this document.
Refer
to the RSX-llM/M-PLUS and Micro/RSX Executive Reference Manual for
discussions of trap-associated system directives.
CAUTION
Do not execute any FCS routines while in an AST
service routine.
FCS maintains an impure data
area that it uses as a Directive Parameter Block
and as a scratch area for directives. An AST
could interrupt an FCS operation that is altering
this impure area. Executing an FCS routine in AST
state could alter the impure area and cause
unpredictable results when task execution resumes.

2.9.4

Block Locking

Block locking selectively controls access to blocks within a file
while that file is being read from or written to by one or more users.
Block locking can be used from FCS or RMS-ll,
or by issuing QIO$
macros.
You can enable block locking only when the file is opened. Once block
locking is enabled, you can establish "locks," which are structures
allocated from system dynamic storage that control access to specific
blocks in the file.
When your task reads or writes a block, the Executive creates a lock
that subsequently restricts other users from writing to or reading
from that block. When your task has a file open on a LUN with block
locking enabled and locks are created, your locks do not restrict your
task from reading or writing blocks if you use the same LUN.
Locks
may be selectively eliminated by issuing a QIO$ macro with the IO.ULK
(unlock) function code. You can only eliminate those blocks that you
have created. When your task closes the file, all your locks on that
file are released to system dynamic storage.
Block locking operates in the following ways when using FCS:
1.

Opening the File:
To enable block locking when opening a file from FCS, you
must change two fields
in the File Descriptor Block. The
value FA.SHR in byte F.FACC must be set to allow shared write
access to the file.
Additionally, the values FA.LKL, FA.EXL,
and FA.ENB must be set in word F.ACTL. Setting FA.SHR causes
FCS to clear AC.LCK in the DPB. For example:
FDOP$R
OPEN$R

#FDB",,#FA.SHR,#FA.LKL!FA.EXL!FA.ENB
RO""""ERRSUB
iOPEN SHARED FOR READ WITH LOCKS

Writing or Reading Blocks:
A one-block read or write operation locks a block for
exclusive access. A write or read operation of more than one
block similarly locks all blocks operated on in this QIO$
macro.
A file open for block mode may invoke READ$ and
WRITE$ macros in the usual manner.

2-46

PREPARING FOR I/O

Note that, in general, FCS operates as follows on
read access:

sequential

OPEN$R positions the file to record 1

GET$ returns record 1 and positions the file to record 2

GET$ returns record 2 and positions the file to record 3

GET$ returns record 3 and positions the file to record 4

Be aware that successive GET$ macros
sequentially.

scan

across

However, if you have files open for record mode
the following special considerations may exist:

the

file

operations,

•

A number of tasks are updating records in a single file

•

One of these tasks is reading records sequentially

For example, if the GET$ macro for record 2 in the task that
reads blocks sequentially fails because record 2 is contained
in a block previously locked by another task, FCS loses its
position in the file.
The next GET$ macro yields undefined
results; it obtains neither record 2 nor record 3.
After this kind of error occurs, FCS must reposition its
pointer to the records in the file. This can happen in one
of the following ways:

•

Operating in random mode on fixed-length records, FCS
repositions its record pointer to the first record for
each GET$ or PUT$ operation.

•

FCS repositions the
FCS
pointer
in
a
file
of
variable-length records by calling the FCS .POINT routine.
You can reposition the pointer either to a location noted
by a previous .MARK call, or to the beginning of the file.

•

FCS closes and reopens the file to reposition the
to the beginning.

pointer

Unlocking Blocks:
To unlock blocks without closing the file, you must execute a
QIO$ macro with the function code IO.ULK.
You can use IO.ULK
to unlock one block, a series of blocks, or all the blocks in
an open file.
To unlock one or more blocks in a series, specify the block
count in device-dependent parameter Word 2, specify the high
8 bits of the starting VBN in the low byte of parameter Word
4, and specify the low 16 bits of the starting VBN in
parameter Word 5. For example, to unlock previously locked
VBNs 5, 6, and 7, use the following code:
MOV
MOV
QIOW$S

#3,RO
;UNLOCK 3 BLOCKS
#5,Rl
;STARTING AT VBN 5
#IO.ULK,#MYLUN,#l"#IOSB,,(,RO,,,Rl>

2-47

PREPARING FOR I/O
To unlock all blocks you have locked on this LUN,
issue the
QIO$ macro with no parameters beyond the device-independent
part of the DPB, as follows:
QIOW$S

#IO.ULK,#MYLUN,#l,,#IOSB

iUNLOCK ALL BLOCKS

Also, you can use FCS to execute the QIO$ macros for
calling the .XIOU routine.

you

To use the .XIOU routine to unlock all blocks that you have
locked on this LUN and file, call
.XQIO with no option
parameters, that is, with R2=O as follows:
MOV
MOV
CLR
CALL
BCS

iGET FOB ADDRESS
iUNLOCK BLOCK FUNCTION
iUNLOCK ALL BLOCKS

#FDB,RO
#IO.ULK
R2
.XQIO
ERROUT

iEXECUTE QI0
iIF CS ERROR IS IN F.ERR(RO)

To use .XIOU to unlock one or more blocks in a series, you
must set up a 5-word parameter block.
Specify the count of
blocks in Word 2, specify the high 8 bits of the starting VBN
in the low byte of parameter Word 4, and specify the low 16
bits of the starting VBN in parameter Word 5.
For example,
to unlock the previously locked VBNs 5, 6, and 7, use the
following code:
PRMBK:

.WORD
.WORD
.WORD
.WORD
.WORD
MOV
MOV
MOV
MOV
MOV
MOV
CALL
BCS

0
0
0
0
0
#FDB,RO
#IO.ULK
#5,R2
#PRMBK,R3
#3,2(R3)
#5,8. (R3)
.XQIO
ERROUT

iPARAMETER BLOCK FOR UNLOCK QIO
iCOUNT OF BLOCKS TO UNLOCK
iHIGH 8 BITS OF START VBN
iLOW 16 BITS OF START VBN
iGET FOB ADDRESS
iUNLOCK BLOCK FUNCTION
iFIVE PARAMETERS
iADDRESS OF PARAMETER BLOCK
iUNLOCK 3 BLOCKS
iSTARTING AT VBN 5
iEXECUTE QIO
iIF CS ERROR IS IN F.ERR(RO)

Closing the Files
Closing the file in the ordinary manner
blocks that have been established on
specific task and LUN.

2.9.5

will
that

release all
file for the

Error Codes Related to Shared Files and Block Locking

Error codes relating to file sharing and block locking may be returned
in the following circumstances:
1.

Opening the File
IE.WAC
Indicates that you have requested that other users be
denied write access
(no FCS FA.SHR or AC.LCK=l), but
someone else has already opened the file to write to it.

2-48

PREPARING POR I/O
Solution: Do not attempt to open the file
others writing to the file have closed it.

until

all

IE.LCK
Indicates that one of the following conditions is true:
•

You want to write to the file and have allowed shared
write access
(set FCS FA.SHR or AC.LCK=O), but
someone else has already opened the file denying
others write access.
Solution: Do not attempt to open the file until all
accessors without shared write access have closed the
file.

•

You want to write to the file and have allowed shared
write access
(set FCS FA.SHR or AC.LCK=O) without
enabling block locking but someone else has already
opened the file with block locking enabled.
Solution:

•

Open the file with block locking enabled.

FllACP cannot perform a directory operation
the directory is locked or being written to.

because

you
Solution:
The solution
depends
on
what
anticipate as normal activity on your system.
If it
is legitimate for a task to access a directory, then
consider attempting the operation again.
IE.ULK
Indicates that the Executive does not support block
locking.
This error can only be returned on an RSX-llM
system that has been generated without block locking
support.
Solution:
2.

Open the file without enabling block locking.

Writing or Reading Blocks:
IE.ULK
Returned by the Executive when any read or write error
occurs that relates to block locking. It generally
means that another task has locked the block.
Solution: The solution depends on the application.
Wait and retry the operation or report the error and
stop processing.

Unlocking Blocks:
IE.IPC
Returned when
locking.

the

Executive

does

not

support

Solution: Do not attempt to unlock blocks on
that does not support block locking.
IE.LCK

2-49

block
system

PREPARING FOR I/O
Returned upon the occurrence of any other error.
For
example, IE.LCK is returned if another task has locked
the blocks.
Solution:
Unlock only those blocks
previously locked for that file.
4.

that

you

have

Closing the File:
No block locking error can occur when closing a file.

2-50

CHAPTER 3
FILE-PROCESSING MACROS

You can manipulate files through a set of file-processing macro calls.
The assembler invokes and expands these macros at assembly time and
the operating system executes the resulting code at run time.
This
chapter describes these run-time macro calls, which allow you to
manipulate files and to perform the following I/O operations:
OPEN$

- Opens and prepares a file for processing

OP'NS$

- Opens and prepares a file for processing and to allow
shared access to that file (depending on the mode of
access)

OPNT$

- Creates and opens a temporary file for processing

OE'ID$

- Opens an existing file using file
information in the filename block
- Opens a file
filename block

CLOSE$

using

file

name

identification

information

the

Terminates file processing in an orderly manner

GET$

- Reads logical data records from a file

GET$R

- Reads fixed-length records from a file in random mode

Gl~T$S

- Reads records from a file in sequential mode

PUT$

- Writes logical data records to a file

PUT$R

- Writes fixed-length records to a file in random mode

PUT$S

- Writes records to a file in sequential mode

READ$

- Reads virtual data blocks from a file

WRITE$

- Writes virtual data blocks to a file

DELET$

volume
- Removes a named file from the associated
directory and deal locates the space occupied by the
file

WAIT$

- Suspends program execution until a requested block
operation is completed

I/O

Most of the parameters associated with the file-processing macro calls
supply
information
to the File Descriptor Block
(FOB).
Such
parame'ters cause MOV or MOVB instructions to be generated in the
object code,
resulting in the initialization of specific locations
withiI1l the FOB.

3-1

FILE-PROCESSING MACROS
The final parameter in all file-processing macros is the symbolic
address of an optional, user-defined 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
WORD.
JSR
nn$:

nn$

;TESTS CARRY BIT IN PROCESSOR STATUS

PC,ERRLOC

;INITIATES ERROR-HANDLING ROUTINE
;AT "ERRLOC" ADDRESS.
;CONTINUES NORMAL PROGRAM EXECUTION.

where nn$ represents a generated local symbol.
If the operation is
completed successfully, the Carry bit in the Processor Status Word is
not set, and FOB 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 Carry bit in the Processor Status Word is
set, FOB offset location F.ERR contains a negative value
(indicating
an error condition), and the branch to the local symbol nn$ does not
occur. Instead, the JSR instruction is executed, loading the PC with
the symbolic address
(ERRLOC)
of the error-handling routine and
initiating its execution.
If this optional parameter is not specified, the error-processing
routine is not called, and you must explicitly test the Carry bit in
the Processor Status Word to ascertain the status of the requested
operation.
Note that executing the FCS file-processing routines causes all your
task's general registers to be saved except RO. FCS uses RO by
convention to contain the address of the FOB associated with the file
being processed.

3.1

OPEN$X - GENERALIZED OPEN MACRO

Before any file can be processed by your task or system program,
it
must first be opened.
An alphabetic suffix accompanying the macro
name indicates to FCS the action you intend to perform on a file.
For
example, in issuing the following generaLized macro:
OPEN$x
x represents anyone of the following alphabetic
which denotes a specific type of file processing:
R

suffixes,

each

- Read an existing file

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

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

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

3-2

FILE-PROCESSING MACROS
NOTE
You can issue the generalized OPEN$x macro without an
alphabetic suffix.
In this case, the action to be
performed on the file is indicated to FCS through an
additional parameter in the macro. This value, called
the file access
(facc)
parameter, causes
offset
location
F.FACC
in
the
associated FOB to be
initialized. Section 3.7 describes this macro 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
here:
1.

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

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

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

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

The program that issues the OPEN$x macro must have appropriate access
privilE!ges for the specified action. Table 3-1 summarizes the access
privileges for the various forms of the OPEN$x macro. 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
Maclt:o

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

When your task issues any form of the OPEN$x macro, FCS first fills in
the filename block with file name information retrieved from the
datasE!t descriptor (see Section 2.4.1). FCS gains access to this data
structure through the address value stored in FOB offset location
F. DSP'1~.

3-3

FILE-PROCESSING MACROS
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 file name
information specified in your task,
is created in the program by
issuing the NMBLK$ macro (see Section 2.4.2).
FCS gains access to
this structure through the address value stored in FDB offset location
F.DFNB.
The address values in offset locations F.DSPT and F.DFNB can
supplied to FCS through the FDOP$A macro, the FDOP$R macro call,
the OPEN$x macro. FCS requires access to the Dataset Descriptor
the default filename block in retrieving file name information used
opening files.
If a new file is to be created, the OPEN$W macro is issued.
performs the following operations:

FCS

be
or
or
in

then

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

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

Places an entry for the file in the User File Directory
(UFD).
If, however,
an entry for a file having the same
name, type, and version number already exists in the UFD, the
old file is deleted.
If your task explicitly issues a
particular type of macro that specifies that the file not be
superseded,
the old file is not deleted and an error code is
returned. This type of OPENS 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$ or PUTS) operations are processing
the file.

If an existing file is to be opened, anyone of the
may be issued:
OPEN$R, OPEN$M, OPEN$U, or OPEN$A.
the following operations:

(LUN)

with

the

following macros
FCS then performs

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

Associates the assigned logical unit number
file.

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

(LUN)

with

the

FILE-PROCESSING MACROS
4.

Allocates a buffer for the file from the FSR block buffer
pool
if record I/O (GET$ or PUT$) operations are processing
the file.
NOTE
As described in Section 2.6, you allocate buffers
through the FSRSZ$ macro.
The number of buffers
allocated is dependent upon the number of files that
you intend to open simultaneously for
record I/O
operations.

If your task uses block I/O operations, FOB offset location F.RACC
must bE~ initialized with the FO.RWM parameter by the FORC$A, the
FORC$R, or the generalized OPEN$x macro. This parameter inhibits the
allocation of a buffer when the file is opened.

3.1.1

li!'ormat of Generalized OPEN$x Macro

The OPEN$x macro takes the following general form:
Format
OPEN$x

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

Paramebers
x

The alphabetic suffix specified as part of the macro name,
indicating the desired type of operation to be performed on the
file.
The possible values for this parameter are: R, W, M,
U,
or A (see Section 3.1).
fdb
A symbolic value of the address of the associated FOB.
lun
The logical unit number (LUN) associated with the desired file.
This
parameter identifies the device on which the volume
containing the desired file is mounted.
Normally,
the logical
unit number associated with the file is specified through the
corresponding parameter of the FOOP$A or the FOOP$R macro.
If so
specified,
the lun parameter need not be present in the OPEN$x
malcro. Each FOB must have a unique LUN.
dspt
The symbolic address of the dataset descriptor.
Normally,
this
address value is specified through the corresponding parameter of
the FOOP$A or the FOOP$R macro.
If so specified, this parameter
need not be present in the OPEN$x macro.
This parameter specifies the address of the manually created
dataset descriptor
(see Section 2.4.1).
If the Command String
Interpreter (CSI)
interprets command lines dynamically,
this
pcirameter specifies the address of the dataset descriptor within
the CSI control block (see offset location C.OSOS in Section
6 .. 2.2).

3-5

FILE-PROCESSING MACROS

racc
The record access byte. One or more symbolic values may be
specified in this field to initialize the record access byte
(F.RACC) in the associated FDB. You can specify any combination
of the following parameters by separating them with exclamation
points:
•

FD.RWM - Requests that block I/O (READ$ or WRITE$) operations
are to process the file.
If you do not specify this
parameter, FCS assumes by default that record I/O (GET$ or
PUT$) operations are to process the file.

•

FD.RAN - Requests random access to the file for record I/O
(GET$ or PUT$) operations. The file is opened and the first
record is pointed to. With this parameter, a PUT$ operation
in the file, without exception, does not truncate the file.
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 - Requests locate mode (see Section 1.6.2) for record
I/O
(GET$ or PUT$)
operations.
If this parameter is not
specified, FCS uses mov~ mode-(see Section 1.6.1) by default.

•

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

Specifying this parameter allows a data record in the body of the
file to be overwritten.
Care must be exercised, however, to
ensure that the record being written is the same length as that
of the record being replaced.
If the record access byte in the FDB has already been initialized
through the corresponding parameters of the FDRC$A or the FDRC$R
macro, the racc parameters need not be present in the OPEN$x
macro.
urba
The symbolic address of your task's record buffer.
parameter initializes FDB offset location F.URBD+2.

This

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

3-6

FILE-PROCESSING MACROS
err
The symbolic address of
routine.

optional

user-coded

Specific FOB requirements for record I/O operations
macros) are detailed in Sections 3.9.2 and 3.12.2.

error-handling
(GET$

and

PUTS

might

take

The following examples show sample uses of the OPEN$x macro.
A macro to open and modify an existing file, for example,
the following form:
OPEN$M

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

Note in this macro that the FOB address is assumed to be present in
RO.
The third parameter, that is, the dataset descriptor pointer, is
not specified; this null specification (indicated by the extra comma)
assumes that FOB 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$ or PUTS operations.
The following macro might be issued to update an existing file:
OPEN$U

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

This macro also assumes that the FOB 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 FOB and that the record access byte (F.RACC) has also been
previously initialized. Finally, the last two parameters establish
the address and the size, respectively, of your task's record buffer.
This last example shows a macro that might be issued to allow data
be appended to the end of a file:
OPEN$A

#OUTFDB

This macro specifies the address of an FOB 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
FOB through the appropriate assembly-time or run-time macro.
Note in all three preceding examples that the error parameter is not
specified, requiring that you explicitly test the Carry bit in the
Processor Status Word to ascertain the success of the specified
operation.
NOTE
You can use RO only to pass the FOB address parameter.
Any other use of RO when you issue the OPEN$A macro
will fail.

3.1.2

FOB Requirements for Generalized OPEN$x Macro

The information required for opening a file may be supplied to the FOB
through the following macros:
•

The assembly-time macros described in Section 2.2.1

•

The NMBLK$ macro described in Section 2.4.2
3-7

FILE-PROCESSING MACROS
•

The run-time macros described in Section 2.2.2

•

The various macros described in this chapter for opening files

Using any particular combination of macros to define and initialize
the FOB is a matter of choice, as indicated previously. Of far
greater significance is the fact that certain information must be
present in the FOB before you can open the associated file.
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,
the
following information must first be supplied to the FOB.
You
can specify this information through the FOAT$A macro
(see
Section 2.2.1.2) or the FOAT$R macro (see Section 2.2.2):
•

The record
operations.

type

must

established

for

record

I/O

The record type cannot be supplied to the FOB through any
of the various macros used to create or open files (for
example, OPEN$W, OPEN$R, and so forth).
Furthermore, this
information is required when opening an existing file,
because FCS obtains such information from the first 14
bytes of your task's file attribute section of the file
header block (see Appendix F).
To establish the record type, you must initialize byte
offset location F.RTYP with the following symbolic values:
R.FIX - Requests that fixed-length records
written into the file.

are

R.VAR - Requests that variable-length records are to be
written into the file.
R.SEQ - Requests that
written into the file.
•

sequenced

records

are

The desired record attributes must be specified for record
I/O operations.
The record attributes cannot be supplied to the FOB
through any of the various macros used to create or open
files
(for example, OPEN$W, OPEN$R, and so
forth) •
Furthermore, the record attributes are required when
opening an existing file, because FCS obtains
such
information from the first 14 bytes of your task's file
attribute section of the file header block
(see Appendix
F) •

The record attributes are defined by initializing byte
offset location F.RATT with the appropriate value(s), as
follows:
FO.FTN - Requests that the first byte of each
contain a FORTRAN carriage-control character.

record

FO.CR - Requests that a line-feed
«LF»
character
precede each record and that a carriage-return «CR»
character follow the record when that record is output

3-8

FILE-PROCESSING MACROS
to a device requiring carriage control information (for
example, to a terminal). The <LF) and <CR) characters
are not actually embedded within the record.
Their
presence is merely implied through the file attribute
FD.CR.
FD.BLK - Requests that records
crossing block boundaries.

prevented

from

FD.PRN - Requests that the record be preceded by a word
containing carriage-control information.
Files with
this attribute must also be sequenced files;
that is,
files with the bit R.SEQ set in the byte F.RTYP in the
FDB. For more information about FD.PRN as a
record
attribute, see Chapter 2, Section 2.2.1.2.
•

If fixed-length records are to be written to the file, you
must specify the record size (in bytes) for record I/O
operations to appropriately initialize FDB offset location
F.RSIZ.
The record size cannot be supplied to the FDB through any
of the various macros used to create and open files, or
both
(for example, OPEN$W, OPEN$R,
and
so
forth) •
Furthermore, the record size is required when opening an
existing file, because FCS obtains such information from
the first 14 bytes of your task's file attribute section
of the file header block (see Appendix F).

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

The record access byte must be initialized for record or
block I/O operations. The symbolic values following may
be specified in the FDRC$A macro
(see Section 2.2.l.3),
the
FDRC$R macro call
(see Section 2.2.2), or the
generalized OPEN$x macro to initialize FDB offset location
F.RACC:
FD.RWM - Requests that READ$ or WRITE$
(block I/O)
operations process the file.
If this parameter is not
specified, GET$ or PUT$ (record I/O) operations result
by default.
FD.RAN - Requests that random access mode (GET$ or PUT$
record I/O)
process the file.
The file is opened and
the first record pointed to.
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 - Requests that locate mode (GET$ or PUT$ record
I/O)
process the file.
If this parameter is not
specified, move mode results by default.
FD.INS - Requests that a PUT$ operation in sequential
mode in the body of a file shall not truncate the file.
If this parameter is not specified, a PUT$ operation
truncates the file.
In this case, the logical end of
the file is reset to a point just beyond the inserted
record, but no deallocation of file blocks occurs.

3-9

FILE-PROCESSING MACROS
•

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

•

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

•

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

•

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

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

The override block size (ovbs parameter) must be specified
in either the FDBF$A or the FDBF$R macro to initialize FOB
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
or
if
the
big-buffering or multiple-buffering versions of FCS are in
use. The override block size is specified to improve I/O
system
performance
with
record
I/O,
and
with
record-oriented devices
(such as line printers)
and
sequential devices
(such as magnetic tape units).
(See
Section 2.2.1.6.)

•

The multiple buffer count
(mbct parameter) must
be
specified in either the FDBF$A or the FDBF$R macro to
initialize
FOB
offset
location
F.MBCT.
If
multiple-buffered record I/O operations are to be used,
this parameter must be greater than 1, and it must agree
with the desired number of buffers to be used. This
parameter is neither overlaid nor zeroed when the file is
closed.
3-10

FILE-PROCESSING MACROS
If the multiple buffer count is not established as
described previously, 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 .M~FCT 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 your task uses multiple buffering, you
must specify the appropriate control flag as the mbfg
parameter in either the FOBF$A or the FOBF$R macro to
appropriately
initialize FOB offset location F.MBFG.
Either of two symbolic values may be specified for this
purpose, as follows:
FO.RAH - Requests that
process the file.

read-ahead

operations

are

FO.WBH - Requests that write-behind operations
process the file.

are

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 when that file is being used basically for
sequential read operations, but scattered updating is also
being performed.
•

To allocate required file space at the time a file is
created, the cntg parameter must be specified in either
the FOAT$A or the
FOAT$R
macro.
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 your program
must be moved manually into FOB offset location F.STBK.
This address value specifies an area in your task to which
FCS returns certain statistical information about a file
when it is opened.
If this parameter is not specified, no
return of such information occurs.
The format and content of the statistics block are
presented in Appendix H. You can define such an area in a
program with coding logically equivalent to
STBLK:

.BLKW

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

manually

initialized,

#STBLK,FOBAOR+F STBK

where STBLK is the symbolic address of the statistics
block, which you define, and the destination operand of
this instruction defines the appropriate offset location
within the desired FOB.

3-11

FILE-PROCESSING MACROS
3.2

OPNS$X - OPEN FILE FOR SHARED ACCESS

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

3.3

OPNT$W - CREATE AND OPEN TEMPORARY FILE

The OPNT$W macro creates and opens 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 described in the
following section.
The OPNT$W macro creates a file but does not enter
that file into any associated user directory file.

file

name

for

In using the OPNT$W macro, you bear the responsibility for marking the
temporary file for deletion, as described in the procedure in the
following text. 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 takes the same format and parameters as
those of the generalized OPEN$x macro, the former executes faster
because no directory entries are made for a temporary file.
Creating a temporary file is usually done when a program requires a
file only for the duration of its execution (for example, for use as a
work file).
The general sequence of operations in such instances
proceeds as follows:
1.

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

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

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

In anticipation of reopening the temporary file, restore
filename block to the FOB by reversing step 2.

Reopen the file by issuing any of the FCS macros 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 .MRKOL
routine, as shown following, to mark the file for deletion:
CALL

.MRKOL

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

Close the file by issuing the CLOSE$ macro.

3-12

the

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

3.4

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

The OPN1r$D macro creates and opens a temporary file.
This macro is a
convenient way to perform the previously shown steps 1 and 6. A file
marked for deletion cannot be opened by another program. Furthermore,
when the file is closed, it is deleted from the volume, returning its
space to the pool of available storage on the volume for reallocation.
The presumption in issuing the OPNT$D macro is that the file thus
created is to be used only once. This is a particularly desirable way
to open a temporary file, because the file will be deleted even if the
program terminates abnormally without closing the file.
The OPNT$D macro takes the same format and parameters as those of
generalized OPEN$x macro.

the

NOTE
If the OPNT$D macro is used for a temporary file
containing sensitive information, it is recommended
that you zero the file before closing it, or reformat
the
disk
to destroy the sensitive information.
(Although a temporary file is deleted after use, the
information physically remains on the volume until
written over with another file and could be analyzed
by unauthorized users.)

3.5

OFID$X - OPEN FILE BY FILE ID

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

either

one

two

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. Saving
and restoring the filename block are discussed in detail in
Section 2.5.1.

3-13

FILE-PROCESSING MACROS
•

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
can be issued.

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

applies,

requiring

that

the

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

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

Issue the OFID$x macro.

The advantage in using the .PARSE and .FIND routines with the OFID$x
macro is that you can overlay the program, placing .PARSE and .FIND on
one branch, and the code for OFID$x on another branch.
This overlay
structure reduces the program's overall memory requirements.
Unlike the other FCS macros for opening files,
the OFID$x macro
requires a nonzero value in the first word of the file identification
field (N.FID) 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 10.
Opening an existing file by file 10 for write
case.
Because it is intended to rewrite
following occur:

access is a special
the existing file, the

•

Any initial allocation (F.CNTG) is ignored.

•

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

•

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

•

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

The OFID$W macro is equivalent to the OFID$U macro.
Invoking either
OFID$W or OFID$U opens an existing file by file 10 number for update
and extension.

3.6

OFNB$X OPEN FILE BY FILENAME BLOCK

The OFNB$x macro either opens an existing file or creates and opens a
new file using file name information in the filename block. Like the
OFID$x macro previously described, the OFNB$x call is for use with

3-14

FILE-PROCESSING MACROS
overlaid programs. However, the OFNB$x macro differs in two important
respects:
it can be issued to create a new file, and it can be issued
to open a file by filename block.
The OFNB$x call has the same format and takes the same parameters as
those of the generalized OPEN$x macro (as described in Section 3.1.1):
OFNB$x fdb,lun,dspt,racc,urba,urbs,err
The OFNB$x macro also uses the same suffixes that are available to the
OPEN$x macro:
OFNB$R, OFNB$W, OFNB$M, OFNB$U, OFNB$A. The suffixes
have the same meaning as they do for OPEN$x (see Table 3-1).
In describing the functions of the OFNB$x macro, the same assumptions
outlined for OFIO$x apply, namely, that the filename block has been
saved and restored in anticipation of issuing the OFNB$x macro, or
that the file
is being opened for the first time. Because the
procedures for saving and restoring the filename block ate 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 FOB must be initialized, as described in the following text.
To open a file by filename block, the following
information
present in the filename block of the associated FOB:

The file name (offset location N.FNAM)

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

The file version number (offset location N.FVER)

The directory 10 (offset location N.OIO)

The device name (offset location N.OVNM)

The unit number (offset location N.UNIT)

must

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

3.6.1

Dataset Descriptor or Default Filename Block

If the dataset descriptor contains all the required information listed
previously, follow these procedures:
1.

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

Issue the OFNB$x macro.

3.6.2

Default Filename Block Only

If a default filename block is to be used in
information to FCS, follow these procedures:
1.

providing

the

required

Issue the NMBLK$ macro (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.

3-15

FILE-PROCESSING MACROS
2.

To provide the directory ID, call
routines:

either

the

following

Call the .GTDIR routine (see Section 4.9.1)
to retrieve
the directory ID from the specified dataset descriptor and
to store the directory ID in the default filename block.
Call the .GTDID routine (see Section 4.9.2)
to retrieve
the default UIC from $$FSR2 and to store the directory ID
in the default filename block.
3.

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

Issue the OFNB$x macro.

the

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

3.7

OPEN$ - GENERALIZED OPEN FOR SPECIFYING FILE ACCESS

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

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

3-16

FILE-PROCESSING MACROS

Parameter
facc
Anyone or an appropriate combination of the following symbolic
values indicating how the specified file is to be accessed:
•

FO.RO - Requests that an existing file is
reading only.

•

FO.WRT - Requests that a new file is to be created and
for writing.

•

FO.APO - Requests that an existing file is to
appended.

opened

and

•

FO.MFY - Requests that an existing file is to
modified.

opened

and

•

FO.UPO - Requests that an existing file
updated, and, if necessary, extended.

opened

for

opened

opened,

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

FA.TMP - Requests, in combination with FO.WRT, that
is to be a temporary file.

•

FA.SHR - Requests that the file is to
access.

opened

the
for

file
shared

dfnb
The symbolic address of the default filename block.
This
parameter is the same as that described in connection with the
FDOP$A/FOOP$R macro.
The previously described parameters initialize
F.FACC and F.OFNB with appropriate values.

FOB

offset

locations

Any logically consistent combination of the previously described file
access symbols is permissible. The particular combination required to
create and write a new file without superseding an existing file
follows:
OPENS

#OUTFOB,#FO.WRT!FA.NSP

The following macro creates a temporary file for shared access:
OPENS

#OUTFOB,#FO.WRT!FA.TMP!FA.SHR
NOTE

You can use RO only to pass the FOB address parameter.
Any other use of RO when you issue the OPENS macro
will fail.

3-17

FILE-PROCESSING MACROS
3.8

CLOSES - CLOSE SPECIFIED FILE

When the processing of a file is completed, you must close it by
issuing the CLOSES macro. The CLOSES 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)

By default, truncates the file being closed

Deaccesses the file

Releases the FSR block
(record I/O only)

Prepares the FOB for subsequent use by
FOB offset locations

clearing

Calls
an
optional
usei-coded
error-handling routine if an error
during the CLOSES operation

and
user-specified
condition is detected

buffer(s)

allocated

for

the

file

appropriate

Note that I/O does occur in items 1 and 2.
Therefore, your program
should include error processing for CLOSES calls as it would for calls
to PUTS.
Issuing a CLOSES when a file is already closed results in a success
status code. Closing a file that is already closed is not an error.

3.8.1

Format of CLOSES Macro

Format
CLOSES

fdb,err

Parameter
fdb
A symbolic value of the address of the associated FOB.
err
The symbolic address of
routine.

user-coded,

optional

error-handling

The following examples illustrate the use of the CLOSES macro:
CLOSES

#FDBIN,CLSERR

CLOSES

,CLSERR

CLOSES

The first example shows an explicit declaration for the relevant FOB,
and the symbolic address of a user-coded error-handling routine to be
entered if the CLOSES operation is not completed successfully.
The
last two examples assume that RO currently contains the address of the
appropriate FOB.
3-18

FILE-PROCESSING MACROS
3.9

GET$ - READ LOGICAL RECORD

The GET$ macro reads logical records from a file.
After a GETS
operation, the next record buffer descriptors in the FOB always
identify the record just read;
that is, offset location F.NRBO+2
contains the address of the record just read, and offset location
F.NRBO contains the size of that record (in bytes). This is true of
GETS operations in both move and locate mode.
In move mode, a GETS operation moves a record to your task's record
buffer
(as defined by the current contents of F.URBO+2 and F.URBO),
and the address and size of that record are then returned to the next
record buffer descriptors in the FOB (F.NRBO+2 and F.NRBO).
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.NRBO+2 and F.NRBO).
If, on the other hand, the entire record does not reside within the
FSR block buffer, then that record is moved piecemeal into your task's
record buffer, and the address of your task's record buffer and the
size of the record are returned to offset locations F.NRBO+2 and
F.NRBO, respectively.
After returning from a GETS operation in locate mode, regardless of
whether moving the record was necessary, F.NRBO+2 always contains the
address of the record just read, and F.NRBO always contains the size
of that. record.
If the record read was a sequenced record, the sequence number is
stored in F.SEQN regardless of whether the GETS was in move mode or
locate mode.
GETS operations are fully synchronous; that is, record I/O
are completed before control is returned to your program.

operations

Specific FOB requirements for GET$ operations are presented in Section
3.9.2.

3.9.1

Format of GET$ Macro

Format
GgTS

fdb,urba,urbs,err

Parame~ter

fdb
A symbolic value of the address of the associated FOB.
urba
The symbolic address of your task's record buffer that is to be
used for record I/O operations in move or locate mode. When
specified, this parameter initializes FOB
offset
location
F. URBO+2.

3-19

FILE-PROCESSING MACROS
urbs
A numeric value defining the size
(in bytes)
of your task's
record buffer.
This parameter determines the largest record that
can be placed in your task's record buffer
in move or locate
mode. When specified, this parameter initializes offset location
F.URBD in the associated FDB.
err
The symbolic address of an optional error-handling routine, which
you coded.
If neither the urba nor the urbs parameter is specified in the GET$
macro, FCS assumes that these requisite values have been supplied
previously through the FDRC$A, the FDRC$R, or the generalized OPEN$x
macro.
Any resulting nonzero values in offset locations F.URBD+2 and
F.URBD are used as the address and the length, respectively,
of your
task's 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:
•

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

specified

•

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

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

may

used

RO",ERROR

In this example, the address of the desired FDB is assumed to be
present in RO.
Note that the next two parameters, that is, your
task's record buffer address (urba) and your task's 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. The final parameter in the string is the
symbolic address of a user-coded error-handling routine.
GET$

,#RECBUF,#25.,ERROR

This example also assumes that RO contains the address of the desired
FDB.
Explicit parameters then define the address and the size,
respectively, of your task's record buffer and an error handler, which
you coded.
GET$

#INFDB

This example shows a GET$ macro in which only the address of
is specified.
NOTE
You can use RO only to pass the FDB address.
Any
other use of RO when you issue the GET$ macro will
fail.
3-20

the

FDB

FILE-PROCESSING MACROS
3.9.2

The FOB 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 following text focuses mainly on whether your task's record buffer
is required under certain conditions.
In this regard, you should
recall that your task's record buffer descriptors, that is, the urba
and the urbs parameters, may be specified in the FDRC$A, the FORC$R,
or the generalized OPEN$x macro, as well as the I/O-initiating GET$
macro.
These parameters must be present in the GET$ macro (to
appropriately initialize the FOB) only if they were not previously
supplied through other available means.
If operating in random access mode, ~he 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 your task alters the values in locations F.RCNM and
F.RCNM+2 before each issuance of the GET$ or GET$R macro call, the
next record in sequence is read. Your specified record buffer size
(that is, the urbs parameter) always determines the largest record
that can be read during a GET$ operation.

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

3.9.2.2 GET$ Operations in
Locate
Mode - In
performing
GET$
operations in locate mode (refer to Section 1.7.1.2 for information on
locate mode), you should take into account the following:
NOTE
In the following text, reference is made to the FSR
block buffer. By default, the blocksize that FCS uses
is equivalent to the buffer size of the device on
which the file is opened.
If big buffering is enabled
(that is, an ovbs parameter value is specified in the
FOBF$x macro as described in Section 2.2.1.6), the FSR
block buffer will be more than one block long.
As a
result,
it may not be necessary to move a record even
though it crosses block boundaries, because both
blocks are currently within the FSR block buffer
space. Thus, moves are only necessary when the record
crosses a buffer boundary, which is not necessarily
the same as a block boundary in a big-buffered file.

3-21

FILE-PROCESSING MACROS
•

If fixed-length records are to be processed, and if they fit
evenly within the FSR block buffer, your task's 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, your task's 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 (FO.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 FO.BLK prior to
the time the file is created, the records in the resulting
file are not allowed to cross buffer boundaries.
For an existing file, the file attribute section of the file
header block is read when the file
is opened; thus, all
attributes of that file are made known to FCS,
including
whether records within that file are allowed to cross block
boundaries.
The design of FCS requires you to use your task's record
buffer only in the event that records
(either fixed or
variable in length) cross buffer boundaries.

•

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

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

3.10

GET$R - READ LOGICAL RECORD IN RANDOM MODE

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

parameters

3-22

addition

those

FILE-PROCESSING MACROS

Format
GET$R

fdb,urba,urbs,lrcnm,hrcnm,err

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

offset

location

F.RCNM

If you use F.RCNM to specify a desired record number for any
given GET$R operation, this cell must be cleared before issuing a
subsequent GET$R macro 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 n\acro, the next sequential record is read because the record
number i.n offset locations F.RCNM+2 and F.RCNM is increased by one
with each GET$ operation.
In the case of the first GET$R, after
opening the file, record number 1 is read because the record number
has been initialized to 0 by the OPEN.
If a record other than the
next sequential record is to be read, you must explicitly specify the
number of the desired record.
The following statements represent the use of the GET$R macro:
GE'J.1$R

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

In this example the number of the desired record to be read, that is,
1040(decimal),
is expressed through the first of two available fields
for this purpose; the second field is not required and is therefore
reflected as a null specification.
GE~?$R

#FOBAOR,#RECBUF,#160.,R3

This 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.
NOTE
RO can be used only to pass the FOB address parameter.
Any other use of RO when issuing the GET$R macro will
fail.
3-23

FILE-PROCESSING MACROS
3.11

GET$S - READ LOGICAL RECORD IN SEQUENTIAL MODE

The GET$S macro reads logical records from a file in sequential mode.
Although the routine invoked by the GET$S macro 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 is 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 usage over GET$ and PUT$ can be realized only if
GET$S and PUT$S are placed on different branches of the overlay
structure.

3.12

PUT$ - WRITE LOGICAL RECORD

The PUT$ macro writes 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 increases this value by one after each PUT$ or
PUT$R operation to point to the next sequential record position.
Thus, unless your program alters this value before issuing another
PUT$ or PUT$R operation, the next record in sequence is written.
For PUT$ operations, offset locations F.NRBD+2 and F.NRBD in the
associated FOB must contain the address and the size, respectively, of
the record to be written.
The distinction between move mode and
locate mode for PUT$ operations relates to the building or the
assembling of the data into a record. Specifically, in move mode the
record is built in a buffer of your choice. This buffer is not
necessarily your task's record buffer previously described in the
context of record I/O operations.
In other words, you can build
records in an area of a program apart from that normally defined by
your task's record buffer descriptors in the FOB
(F.URBD+2 and
F.URBD).
In this case, you specify the address of the record buffer
so used and the size of the record in the PUT$ macro, and the record
thus built is then moved into the FSR block buffer.
In locate mode, however, the record is built at the address specified
by the contents of offset location F.NRBD+2, and only the record size
need be specified in the PUT$ macro. Then, if the record so built is
not already in the FSR block buffer, it is moved there as the PUT$
operation is performed.
If the records in the file are sequenced records, the field F.SEQN
the FOB contains the sequence value, which you can modify.

PUT$ operations are fully synchronous; that is, record 1/0 operations
are completed before control is returned to your task's program.
A random PUT$ operation in locate mode requires the use of the .POSRC
routine.
This operation is described in detail in Section 4.9.2.
Specific FOB requirements for PUT$ operations are presented in Section
3.12.2.

3.12.1

Format of PUT$ Macro

Format
PUT$

fdb,nrba,nrbs,err

3-24

FILE-PROCESSING MACROS
Parameter
~b

A symbolic value of the address of the associated FOB.
nrba
The symbolic address of the next record buffer, that is,
the
address of the record to be PUT$. This parameter initializes FOB
offset location F.NRBD+2.
nrbs
A numeric value specifying the size of the next record buffer,
that is, the length of the record to be PUT$. This parameter
initializes FOB offset location F.NRBD.
err
The symbolic address of an optional error-handling routine, which
you coded.
The following examples show how the
program:
PUT$

PUT$

macro

may

used

#FDBADR",ERRRT

In this example the next record buffer address
(nrba parameter)
and
the next record buffer size (nrbs parameter) are null. These null
specifications imply that the current values in offset locations
F.NRBD+2 and F.NRBD of the associated FOB are suitable to the current
operation. Note also that fixed-length records could also be written
in locate mode by issuing this macro.
PUT$

,,#160.,ERRRT

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

This example specifies only
parameter fields are null.

the

address

the

FOB:

all

other

NOTE
RO can only be used to pass the FOB address parameter
as shown in the previous example: it cannot be used to
pass any other parameter in the PUT$ macro.

3.12.2

The FOB Relevant to PUT$ Operations

This subsection highlights aspects of PUT$ operations
locate mode that have a bearing on the associated FOB.

move

and

The conditions under which your task's record buffer is or is not used
are summarized.
As is the case for GET$ operations, if your task's
record buffer is required for PUT$ operations, the buffer descriptors

3-25

FILE-PROCESSING MACROS
(that is, the urba and urbs parameters) may be supplied to the
associated FDB through the FDRC$A, the FDRC$R, or the generalized
OPEN$x macro.
In any case, offset locations F.URBD+2 and F.URBD must
be
appropriately
initialized
if
PUT$ operations require the
utilization of your task's record buffer. Note, however, that PUT$
operations in move mode never require a record buffer.
If your task's record buffer is required, the specified size of that
buffer (that is, the urbs pa~ameter) always determines the size of the
largest record that can be written to the specified file.
Whether in move or locate mode, a PUT$ operation uses the information
in offset locations F.NRBD+2 and F.NRBD, that is, the next record
buffer descriptors, to determine whether the record must be moved into
the FSR block buffer. In the event that the record does have to be
moved, and the size of that record is such that it cannot fit in the
space remaining in the FSR block buffer, one of two possible
operations is performed:
•

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

•

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

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

Your task's 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. The values so specified dynamically
update offset locations F.NRBD+2 and F.NRBD in the associated
FDB.

•

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

•

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

3-26

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

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

•

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

•

If a variable-length record is being PUT$, the potential
task's record buffer descriptors must be present in offset
exists for crossing block boundaries.
In this case, your
task's record buffer descriptors must be present in offset
locations F.URBD+2 and F.URBD of
the
associated
FOB.
Moreover, the size of each variable-length record must be
specified as the nrbs parameter in each PUT$ macro.
Determining if Fes points offset location F.NRBD+2 to the FSR
block buffer for the PUT$ operation or to your task's record
buffer is based on whether there is potentially enough room in
the FSR block buffer to accommodate the record.

3-27

FILE-PROCESSING MACROS
Because the records are variable in length, it must be assumed
that the largest possible record is PUTS, as defined by the
size of your task's record (F.URBD). Thus,
if a record of
this defined size cannot fit in the space remaining in the FSR
block buffer, FCS sets offset location F.NRBD+2 to point to
your task's record buffer.
Each PUTS operation in locate mode sets up the FDB for the next PUTS.
In other words,
the specified record size is used by FCS as the
worst-case condition in determining whether sufficient space exists in
the FSR to build the next record.
If variable-length records are being processed that are shorter than
the largest defined record size, FCS may move records unnecessarily
from your task's record buffer to the FSR block buffer. For example,
assume that your task 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 your
task's record buffer for PUTS operations, even if you continue to PUTS
short
(10- or 20-byte) records.
Thus, some unavoidable movement of
records takes place in locate mode.
If the largest record that you intend to PUTS 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 record buffer in your task,
PUTS operations in locate mode are more efficient if this precaution
is observed.
Exercising care in this regard reduces the tendency to
move records from your task's 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 writes fixed-length records to a file in random mode.
As noted in Section 3.10 in discussing the GET$R macro, operations in
random access mode require you to be very familiar with the contents
of such files.
The PUT$R macro also relies entirely on you to specify
the number of the record before a specified PUTS operation can be
performed.
Because the usual purpose of a PUT$R operation is to
update known records in a file, it is assumed that you also know the
number of such records within the file.
The PUTS and PUT$R macros 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 PUTS 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 macros, then neither
PUTS nor PUT$R will write the desired record.
The PUT$R macro takes two more
specified in the PUTS macro.

parameters

Format
PUT$R

fdb,nrba,nrbs,lrcnm,hrcnm,err

3-28

addition

those

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

offset

location

F.RCNM

If F.RCNM is used in expressing a desired record number for any
given PUT$R operation, you must clear this cell before issuing a
subsequent PUT$R macro 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 FOB.
If these values are
not specified in a subsequent PUT$R macro, the next sequential record
is written, because FCS increases the record number by one in these
cells after each PUT$ operation.
In the case of the first PUT$R after
opening the file, record number 1 is written. Note that this is true
even if the file has been opened for an append (OPEN$A).
If a record
other than the next sequential record is to be written, you must
explicitly specify the number of the desired record.
NOTE
A random mode PUT$R operation executed in locate mode
must be preceded by a call to .POSRC. Because locate
mode allows you to store data directly into the block
buffer, the file must be positioned so that the
desired record position is in fact in the block
buffer. See Section 4.10.2 for further details.
Examples of how the PUT$R macro may be used in a program follow:
PUT$R

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

In the first example, the presence of RECBUF as the next record buffer
address
(nrba) parameter merely indicates that you are specifying the
address of the record. Although specifying this address repeatedly is
unnecessary,
it is not invalid.
Normally, a buffer address is
specified dynamically, because 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. Note also that the
next record buffer size (nrbs)
parameter is null, because 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.
PUT$R

#FDBADR,#RECBUF"R4

PUT$R

#FDBADR,#RECBUF"LRN
3-29

FILE-PROCESSING MACROS
Note in the second and third examples that R4 and a memory location
(LRN) are used to specify the logical record number.
Such a
specification assumes that you have preset the desired record number
in the referenced location.
NOTE
You can use RO only to pass the FOB address.
Any
other use of RO when you issue the PUT$R macro will
fail.

3.14

PUT$S - WRITE LOGICAL RECORD IN SEQUENTIAL MODE

The PUT$S macro writes logical records to a file in sequential mode.
Although the routine invoked by the PUT$S macro 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 is 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 reads a virtual block of data from a block-oriented
device (for example, a magnetic tape, a disk, or DECtape).
In
addition, if certain optional parameters are specified in the READ$
macro, status information is returned to the I/O status block (see
Section 2.8.2), or the program traps to an AST service routine, which
you coded, at the completion of block I/O operations (see Section
2.8.3).
In issuing the READ$
(or WRITE$) macro, you are responsible for
synchronizing all block I/O operations. For this reason, the WAIT$
macro is provided (see Section 3.17), allowing you to suspend program
execution until a specified READ$ or WRITE$ operation has been
completed. It is important, howeve~, that you test the contents of
F.ERR in the FOB for error codes immediately after issuing the READ$
or WRITE$ call as well as on return from the WAIT$ call. When errors
occur during multiple-block transfers, the second word of the I/O
status block will contain the number of bytes transferred before the
error occurred. The READ$ or WRITE operations can return error codes
distinct from those that can be present on completing a WAIT$
operation.
For example, IE.EOF will be returned upon completing the
READ$ operation, but not upon completing WAIT$.
When your task issues the WAIT$ macro with a READ$ (or WRITE$) macro,
you must ensure that the event flag number and the I/O status block
address specified in both macro calls are the same.
When the WTSE$ macro waits for I/O completion, the issuing task must
check I/O errors by examining the I/O status block (defined by the
task).
(The I/O status block is described in Section 2.8.2.) When
WTSE$ is used, FCS will not return a completion code to offset F.ERR
in the FOB.

3-30

FILE-PROCESSING MACROS
3.15.1

Format of READ$ Macro

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

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

Parameter

A symbolic value of the address of the associated FOB.
bkda
The symbolic address of the block I/O buffer in your program.
This parameter need not be specified if offset location F.BKDS+2
has been previously initialized through either the FDBK$A or the
FDBK$R macro.
bkds
A numeric value specifying the size (in bytes)
of the virtual
block to be read. This parameter need not be specified if offset
location F.BKDS has been previously initialized through either
the FDBK$A or the FDBK$R macro.
In any case, the maximum block
size that may be specified for file-structured devices is 32256
bytes.
bkvb
The symbolic address of a 2-word block in your program containing
the number of the virtual block to be read. This parameter
causes offset locations F.BKVB and F.BKVB+2 to be initialized
with the virtual block number; F.BKVB+2 contains the low-order 16
bits of the virtual block number, and F.BKVB contains the
high-order 15 bits.
As noted in connection with the FDBK$A macro described in Section
2.2.1.4, assembly-time initialization of the virtual block number
in the FOB is ineffective, because the generalized OPEN$x
macro
sets the virtual block number in the FOB to 1.
The virtual block number can be made available to FCS only
through the FDBK$R macro or the I/O-initiating READ$ (or WRITE$)
macro after the file has been opened. The virtual block number
is created as described in item 4 of Section 2.2.2.1.
The~

READ$ function checks the specified virtual block number to
ensure that it does not reference a nonexistent block, that is, a
block beyond the end of the file.
If the virtual block number
references
nonexistent data, an end-of-file
(IE.EOF)
error
indication is returned to offset location F.ERR of the associated
FOB; otherwise, the READ$ operation proceeds normally.
If the
total number of bytes goes beyond the end of the file,
then as

3-31

FILE-PROCESSING MACROS
many blocks as exist a~e read and the byte count of the shortened
transfer is returned in I/O STATUS+2. No error condition occurs,
so you must check the count on each READ.
An end-of-file
indication is returned only if no blocks can be read.
If the virtual block number is not specified through any of the
available means identified already, sequential operation results
by default, beginning with virtual block number 1.
The virtual
block number is incremented by the number of blocks read after
each READ$ ope~ation is performed.
bkef
A numeric value specifying the event flag number to be used for
synchronizing block I/O operations. This event flag number is
used by FeS 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, initializes FDB offset
location F.BKEF;
if so specified, this parameter need not be
included in the READ$ (or WRITE$) macro.
If this optional parameter is not specified through any available
means, event flag 32(decimal) is used by default. The function
of an event flag is discussed in further detail in Section 2.8.1.
bkst
The symbolic address of the I/O status block in your task
(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 or 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.
If the address of this
2-word structure is not supplied to Fes through any of the
available means, status information cannot be returned to your
program. Regardless, the event flag specified through the bkef
parameter is set to indicate block I/O completion, but, without
an I/O status block, your program must assume that the operation
(for example, READ$ or WRITE$) was successful.
bkdn
The symbolic entry point address of an AST service routine
(see
Section 2.8.3).
If this parameter is specified, a trap occurs
upon completion of the specified READ$
(or WRITE$) operation.
This pa~ameter, which is optional, initializes offset location
F.BKDN. This address value may also be made available to Fes
through either the FDBK$A or the FDBK$R macro, and, if so
specified, need not be present in the READ$
(or WRITE$) macro
call.
If the address of an AST service routine is not specified through
any available means, no AST trap occurs at the completion of
block I/O operations.
err
The symbolic address of an optional error-handling routine, which
you coded.
The following examples represent READ$ macros that may
accomplish a variety of operations:
READ$

RO
3-32

issued

FILE-PROCESSING MACROS
This example assumes that RO contains the address of the associated
FOB.
Also,
all
other
required FOB initialization has been
accomplished through either the FDBK$A or the FDBK$R macro call.
READ$

#INFDB""",ERRLOC

This example shows an explicit declaration of the associate FOB and
includes the symbolic address of an error-handling routine, which you
coded.
RO,#INBUF,#BUFSIZ,,#22.,#IOSADR,#ASTADR,ERRLOC
In this example RO again contains the address of the associated FOB.
The block buffer address and the size of the block are specified next
in symbolic form.
The address of the 2-word block in your program
containing 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.
RE1~D$

#INFDB,#INBUF,#BUFSIZ,#VBNADR

This example reflects, as the last parameter in the string, the
symbolic address of the 2-word block in your program containing the
virtual block number.
NOTE
You can use RO only to pass the FOB address.
Any
other use of RO when you issue the READ$ macro will
fail.

3.15.2

The FOB Relevant to READ$ Operations

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

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

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

The virtual block number (in offset
F .BKVB)

locations

F.BKVB+2

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

3-33

and

FILE-PROCESSING MACROS
3.16

WRITE$ - WRITE VIRTUAL BLOCK

The WRITE$ macro is issued to wrii te a virtual block of data to a
block-oriented device
(for exa~ple, magnetic tape, disk, DECtape, or
DECtape II). Like the READ$ mac~o, if certain optional parameters are
specified in the WRITE$ macro, status information is returned to the
I/O status block (see Section 2.i8. 2), and, at the completion of the
I/O transfer,
the program t~aps to an AST service routine that is
supplied to coordinate asynchronpus block I/O operations (see Section
2.8.3).
Whether or not you supply the address of an AST service routine and an
event flag number, or both, you! are responsible for synchronizing all
block I/O processing. The WAIT$! macro can be issued with the WRITE$
macro to suspend program exe~ution until a program-dependent I/O
transfer has been completed. Wh~n the WAIT$ macro is used for this
purpose, the event flag numb~r and the I/O status block address in
both macros must be the same. A~ain, as with READ$ operations, you
should check for an error code ~mmediately following the WRITE$ macro
as well as on return from the WA~T$ macro.

3.16.1

Format of WRITE$ Macro

The WRITE$ macro takes the same parameters as the READ$ macro.
The
bkvb parameter represents the: symbolic address of a 2-word block
containing the number of the virtual block to be written. The virtual
block number is incremented afte~ each WRITE$ operation is performed.
Format
WRITE$

fdb,bkda,bkds,bkvb,~kef,bkst,bkdn,err

Parameter
fdb
A symbolic value of the addfess of the associated FDB.
bkda
The symbolic address of the!block I/O buffer in your program.
This parameter need not be! specified if offset location F.BKDS+2
has been previously initialized through either the FDBK$A or the
FDBK$R macro.
bkds
A numeric value specifying ~he size (in bytes)
of the virtual
block to be read. This par~meter need not be specified if offset
location F.BKDS has been pr~viously initialized through either
the FDBK$A or the FDBK$R *acro.
In any case, the maximum block
size that may be specified tor file-structuzed devices is 32256
bytes.
bkvb
The symbolic address of a 2iword block in your program containing
the number of the virtu~l block to be read. This parameter
causes offset locations F.B VB and F.BKVB+2 to be initialized
with the virtual block numb ri F.BKVB+2 contains the low-order 16
bits of the virtual blocij number, and F.BKVB contains the
high-order 15 bits.

3-34

FILE-PROCESSING MACROS
As noted in connection with the FDBK$A macro described in Section
2.2.1.4, assembly-time initialization of the virtual block number
in the FOB is ineffective, because the generalized OPEN$x
macro
sets the virtual block number in the FOB to 1.
The virtual block number can be made available to FCS only
through the FDBK$R macro or the I/O-initiating READ$ (or WRITE$)
macro after the file has been opened. The virtual block number
is created as described in item 4 of Section 2.2.2.1.
The WRITE$ function checks the specified virtual block number to
ensure that it does not reference a nonexistent block, that is, a
block beyond the end of the file.
If the virtual block number
references
nonexistent data, an end-of-file
(IE.EOF) error
indication is returned to offset location F.ERR of the associated
FDB; otherwise, the WRITE$ operation proceeds normally.
If the
total number of bytes goes beyond the end of the file,
then as
many blocks as exist are read and the byte count of the shortened
transfer is returned in I/O STATUS+2. No error condition occurs,
so you must check the count on each WRITE. 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 already, sequential operation results
by default, beginning with virtual block number 1.
The virtual
block number is incremented by the number of blocks read after
each WRITE$ operation is performed.
bkef
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, initializes FOB offset
location F.BKEF; if so specified, this parameter need not be
included in the WRITE$ macro.
I:E this optional parameter is not specified through any available
means, event flag 32(decimal) is used by default. The function
of an event flag is discussed in further detail in Section 2.8.1.
bkst
The symbolic address of the I/O status block in your task
(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 or 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.
If the address of this
2-word structure is not supplied to FCS through any of the
available means, status information cannot be returned to your
program. Regardless, the event flag specified through the bkef
parameter is set to indicate block I/O completion, but, without
an I/O status block, your program must assume that the WRITE$
operation was successful.
bkdn
The symbolic entry point address of an AST service routine
(see
Section 2.8.3).
If this parameter is specified, a trap occurs
upon completion of the specified WRITE$
operation.
This
parameter, which is optional, initializes offset location F.BKDN.

3-35

FILE-PROCESSING MACROS
This address value may also be made available to FCS through
either the FDBK$A or the FDBK$R macro, and, if so specified, need
not be present in the WRITE$ macro call.
If the address of an AST service routine is not specified through
any available means,
no AST trap occurs at the completion of
block I/O operations.
err
The symbolic address of an optional error-handling routine, which
you coded.
When this macro is issued, the virtual block number (that is, the bkvb
parameter)
is checked to ensure that it references a block within the
file's allocated space; if it does, the block is written.
If the
specified block is not within the file's allocated space, FCS attempts
to extend the file.
If this attempt is successful, the block is
written;
if not, an error code indicating the reason for the failure
of the extend operation is returned to the I/O status block and to
offset location F.ERR of the associated FOB.
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.
The following examples show how the WRITE$ macro
program:
WRITE$

may

used

This example specifies only the FOB address and assumes that all other
required values are present in the FOB.
WRITE$

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

This example reflects explicit declarations for the FOB,
the block
buffer address,
the block buffer size, the virtual block number
address, and the event flag number for signalling
block
I/O
completion.
WRITE$

RO",,#22.,#IOSADR,#ASTADR,ERRLOC

This 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, it
specifies the address of an error-handling routine, which you coded.
NOTE
You can use RO only to pass the FOB address.
Any
other use o£ RO when you issue the WRITE$ macro will
fail.

3.16.2

The FOB Relevant to WRITE$ Operations

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

3-36

the

FILE-PROCESSING MACROS
3.17

WAIT$ - WAIT FOR BLOCK I/O COMPLETION

The WArr$ macro, which is issued only with READ$ and
WRITE$
operations, suspends program execution until the requested block I/O
transfer is completed. This macro 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, you can
specify an event flag number through the bkef parameter. This event
flag number is used during READ$ (or WRITE$) operations to indicate
the completion of the requested transfer.
If desired, you can issue a
WAIT$ macro (specifying the same event flag number and I/O status
block address) following the READ$ (or WRITE$) macro.
In this case, the READ$ (or WRITE$) operation is initiated in the
usual manner, but the Executive 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 or failure of the operation.
Fes then
moves the I/O status block success or failure indicator into offset
location F.ERR of the associated FOB, and returns with the carry
condition code 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.
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

Format
WAIT$

fdb,bkef,bkst,err

ParametE:!r
fdb
A symbolic value of the address of the associated FOB.
bkef
A numeric value specifying the event flag number to be used for
synchronizing block I/O operations. The WAIT$ macro causes task
execution to be suspended by invoking the .WAITFOR
system
directive.
This parameter must agree with the corresponding
(bkef) parameter in the associated READ$ or WRITE$ macro.
If this parameter is not specified, either in the WAIT$ macro
call or the associated READ$ or WRITE macro, FOB offset location
F.BKEF is assumed to contain the desired event flag number, as
previously initialized through the bkef parameter of the FDBK$A
or the FDBK$R macro.

3-37

FILE-PROCESSING MACROS
bkst
The symbolic address of the I/O status block in your program (see
Section 2.8.2).
Although this parameter is optional, if it is
specified, it must agree with the corresponding (bkst)
parameter
in the associated REAO$ or WRITE$ macro.
If this parameter is not specified, either in the WAIT$ macro
call or the associated REAO$ or WRITE$ macro, FOB offset location
F.BKST is assumed to contain the address of the I/O status block,
as previously initialized through the bkst parameter of the
FOBK$A or the FOBK$R macro.
If F.BKST has not been initialized,
no information is returned to the I/O status block.
err
The symbolic address of an optional error-handling routine, which
you coded.
The following examples show how the WAIT$
program.
WAIT$

WAIT$

#INFOB,#25.

WAIT$

RO,#25.,#IOSTAT

WAIT$

RO,,#IOSTAT,ERRLOC

macro

may

used

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

Issue the desired REAO$ or WRITE$ macro.

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

Issue the WAIT$ macro.

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

3-38

the

FILE-PROCESSING MACROS
When pelrforming several asynchronous transfers in the same general
sequenc~~ as described previously, a separate buffer, I/O status block,
and event flag must be maintained for each operation.
If you intend
to wait for the completion of a given transfer, the appropriate event
flag number and I/O status block address must be specified in the
associated WAIT$ macro.
NOTE
You can use RO only to pass the FOB address.
Any
other use of RO when you issue the WAIT$ macro will
fail.

3.18

DELET$ - DELETE SPECIFIED FILE

The DELET$ macro causes the directory information for the file
associated with the specified FOB to be deleted from the appropriate
UFO. The space occupied by the file is then deallocated and returned
for reallocation to the pool of available storage on the volume.
This macro 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
(including 0
and -1).
NOTE
If the DELET$ macro is issued for use with a file
containing sensitive information, it is recommended
that you zero the file before closing it, or reformat
the
disk
to destroy the sensitive information.
(Although DELET$ logically removes a
file,
the
information physically remains on the volume until
written over with another file, and could be analyzed
by unauthorized user tasks.)

3.18.1

Format of DELET$ Macro

Format
DELET$

fdb,err

Parameter
fdb
A symbolic value of the address of the associated FOB.
err
The symbolic address of an optional error-handling routine, which
you coded.

3-39

FILE-PROCESSING MACROS

The following examples show how the DELET$ macro
program.
DELET$

DELET$

#OUTFDB,ERRLOC

DELET$

RO,ERRLOC

3-40

may

used

CHAPTER 4
FILE CONTROL ROUTINES

This chapter describes a set of file control routines that you
invoke in MACRO-II programs to perform the following functions:

4.1

can

•

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

•

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

•

Read or write the default
section $$FSR2.

•

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

•

Convert a directory string from ASCII to binary, or binary
ASCII.

•

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

file

protection

from

program

dataset

•

Find, insert, or delete a directory entry.

•

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

record

•

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

•

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

•

Rename a file.

•

Extend a file.

•

Truncate a file.

•

Mark a

•

Delete a file by filename block.

•

Perform device-specific control functions.

t~mporary

block

word

program

file for deletion.

CALLING FILE CONTROL ROUTINES

The CALL macro invokes file control routines (JSR PC, dst). The Task
Builder includes these routines from the system object library
([l,l]SYSLIB.OLB) at task-build time and incorporates them into your
task. Your task calls the following file control routines:
CALL

.RDFOR

CALL

.EXTND
4-1

FILE CONTROL ROUTINES
Before your task issues the CALL macro, certain file control routines
require that specific registers be preset with requisite information.
The descriptions of
the
respective
routines
identify
these
requirements.
Upon return to your task, all task registers are
preserved except for those that have been explicitly specified as
changed.
If a file control routine detects an error,
it sets the Carry bit
indication to FDB offset location F.ERR.
However, certain file
control routines do not return error indications even if one is
present.
The following file control routines are listed according to
whether they return error indications.
Normal Error Return
(Carry bit and F.ERR)

No Error Return
.RDFDR
.WDFDR
.RDFUI
.WDFUI
.RDFFP
.WDFFP
.RFOWN
.WFOWN
.PPASC
.MARK

.ASCPP
• PARSE
.PRSDV
.PRSDI
.PRSDV
.ASLUN
.FIND
.ENTER
.REMOV
.GTDIR
.GTDID
.POINT
.POSRC
.POSIT
.XQIO
.RENAM
.EXTND
.TRNCL
.MRKDL
.DLFNB
.CTRL

Appendix I lists the error codes that the routines listed
opening of Chapter 4 return in FDB offset location F.ERR.

4.2

the

DEFAULT DIRECTORY STRING ROUTINES

The .RDFDR and
descriptors.

4.2.1

.WDFDR

routines

read

and

write

directory

string

.RDFDR - Read $$FSR2 Default Directory String Descriptor

Your task calls the .RDFDR routine to read default directory string
descriptor words previously written by the .WDFDR routine into program
section $$FSR2 of the FSR. These descriptor words define the address
and the length of an ASCII string that contains the default directory
string. This directory string is the default directory that FCS uses
when one is not specified in a dataset descriptor.
If you have not established default directory string descriptor words
in program section $$FSR2 by using the .WDFDR routine described in the
following text, the descriptor words in program section $$FSR2 are
null.
FCS uses a default directory (when one is not specified in a
dataset descriptor) corresponding to the User Identification Code
(UIC) under which the task is running.

4-2

FILE CONTROL ROUTINES
When called, the
register!; :

.RDFDR

routine

returns

values

the

following

contains the size (in bytes) of the default directory
"in program section $$FSR2.

contains the address of the default directory string in
program section $$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

Your task calls the .WDFDR routine to create default directory string
descriptor words in program section $$FSR2. For example, if your
program is to operate on files in the directory [220,220], regardless
of the UIC under which the program runs, you can establish default
directory string descriptor cells in program section $$FSR2 to point
to this alternate directory string [220,220] created elsewhere in the
program. To do this, first create the desired directory string
through an .ASCII directive. Then, by calling the .WDFDR routine, you
can initialize the default directory string descriptor cells in
program section $$FSR2 to point to the new directory string.
Assume that the task is currently running under default UIC [200,200].
You define a new directory string by issuing the following MACRO-II
directivle:
NEWDDS:

.ASCII /[220,220]/

By calling the .WDFDR routine, you initialize string descriptor
in program section $$FSR2 to point to the new directory string.

cells

The following registers must
routine:

.WDFDR

preset

before

calling

the

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 program section $$FSR2 does not change the default
UIC in program section
$$FSR2
or
the
task's
privileges.

4.3

DEFAULT UIC ROUTINES

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

8 7

GROUP

MEMBER

4-3

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

4.3.1

.RDFUI - Read Default UIC

Your task calls the .RDFUI
follows:
Rl

4.3.2

routine

return

contains the binary encoded default
program section $$FSR2.

the
UIC

default
as

UIC

maintained

.WDFUI - Write Default UIC

Your task calls the .WDFUI routine to create
program section $$FSR2.
The following register
routine:
Rl

must

preset

before

new

default

calling

the

UIC

.WDFUI

must contain the binary representation of a UIC.
NOTE
The .WDFUI routine
overrides
any
default
descriptor
in
program
section $$FSR2 that
previously created by the .WDFDR routine.

4.4

UIC
was

DEFAULT FILE PROTECTION WORD ROUTINES

The .RDFFP and .WDFFP routines described in the following text read
and write the default file protection word in a location in program
section $$FSR2 of the file storage region (FSR). FCS uses this word
only when a file is created (for example, by the OPEN$W macro call) to
establish the default file protection values for the new file.
Unless
altered, this value constitutes the default file protection word for
that file.
If the value is -1, it indicates that the volume default
file protection value is to be used for the new file.
The default file protection word has four file protection categories:
world, group, owner, and system.
It has the following format:
Bit 15
I

12 11
WORLD

8 7

GROUP

4-4

4 3
OWNER

SYSTEM

FILE CONTROL ROUTINES
Each of these four file protection categories has four bits; each bit
represents the kind of access allowed to a file, as shown in the
following example:
Bit

IDELETE I EXTEND I WRITE I READ I
A bit value of 0 indicates that the corresponding file access is to be
allowed~ a bit value of 1 indicates that the access is to be denied.

4.4.1

.RDFFP - Read $$FSR2 Default File Protection Word

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

4.4.2

contains the default
section $$FSR2.

file

protection

word

from

program

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

You use the .WDFFP routine to write a new default file protection word
into program section $$FSR2.
The following register
routine::
Rl

4. 5

must

preset

before

calling

the

.WDFFP

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

FI1LE OWNER WORD ROUTINES

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

corresponds

the

•

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

•

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

For privileged users, the owner Ule is always the same as the
the task creating the file.

Ule

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

4-5

FILE CONTROL ROUTINES
A specific UIC value can be stored in the file owner word by the
.WFOWN routine
(see Section 4.5.2). All new files then created and
closed by your task will contain the specified UIC value.
The format of the file owner word is shown next:
Bit 15

8 7

MEMBER

GROUP

The routines for reading and writing the file owner word are described
in Section 4.5.1.
NOTE
The UIC and the file protection word for the file (see
Section 4.4) must not be set such that the UIC under
which the task is running does not have access to the
file.
This
condition
results
in a privilege
violation.
When a file is created, the owner UIC is always set to either the UIC
of the task creating the file or the task's login UIC, as previously
described. However, when closing the file, you can change the owner
UIC by using the .WFOWN routine.
If_ the file is not closed properly,
the owner UIC will not change.

4.5.1

.RFOWN - Read $$FSR2 File Owner Word

You use the .RFOWN routine to read the contents of the file owner word
in program section $$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

You use the .WFOWN routine
program section $$FSR2.

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

Your task calls the .ASCPP and .PPASC routines to convert a
string from ASCII to binary, or binary to ASCII.

4-6

directory

FILE CONTROL ROUTINES
4.6.1

.ASCPP - Convert ASCII Directory String
UIC

Your task calls the .ASCPP routine to
string to its corresponding binary UIC.

convert

Equivalent
an

ASCII

Binary

directory

-The following registers must be preset before call ing this routine:
R2

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

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

4.6.2

.PPASC - Convert UIC to

ASCI~

Directory String

Your task calls the .PPASC routine to convert
corresponding ASCII directory string.

binary

UIC

its

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

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

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

must contain a control code.
indicate the following:

Bits 0 and 1 of

this

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

4. 7

FI1C,ENAME BLOCK ROUTINES

FCS pro 17ides the .PARSE, .PRSDV, .PRSDI, .PRSFN, and .ASLUN routines,
which perform functions related to a specified filename block. These
routines are described in the following sections.
FCS provides the
main support for logical name translation in these routines.
1

4-7

FILE CONTROL ROUTINES
4.7.1

Logical Name Translation

When Fes obtains a device name or a file specification, it examines
the leftmost component to check for the presence of a logical name.
It does this by checking whether the leftmost character string, which
may consist only of alphanumeric characters, dollar signs ($), or
underscores ( ), ends in either a colon (:) or a space
().
If it
does, Fes recognizes the character string as a logical name and makes
an attempt to translate the entire character string. If Fes finds an
equivalence name,
the original information that the logical name
represents, the equivalence name is merged with the file specification
without the logical name.
If the leftmost character string ends in
any character other than a space or colon, Fes uses the string as a
file specification.
In the following example, the first line shows how to specify a file
specification.
The second line shows the use of a logical name to
specify the location of a file.
$ TYPE ALPHA
$ TYPE DISK:ALPHA
In the first line, Fes obtains the file specification ALPHA and checks
to see if ALPHA is a logical name because ALPHA is the leftmost (and
in this example, the only) component of the file specification.
In
the second line, Fes checks to see if DISK, the leftmost component, is
a logical name. Fes does not check ALPHA.
The system stores logical names in four logical name tables. When Fes
translates logical names, it searches first the task table, then the
session table, then the group table, and finally the system table, and
uses the first match it finds.

4.7.1.1 Iterative Translation - When Fes translates logical names in
file specifications, the logical name translation can be iterative.
That is, after Fes translates a logical
name
in
the
file
specification,
it continues to translate and repeats the process of
translating the file specification if it finds
the presence of a
logical name.
NOTE
Use the ASSIGN command for all file-specification
arguments.
ASSIGN performs several checks to insure
that the logical names are syntactically correct.
As an example of iterative translation, consider
entries made with ASSIGN commands as follows:

logical

name

table

$ ASSIGN OBI:

DISK
$ ASSIGN REPORT DISK: [HUMIDO]WEATHER.SUM

The first ASSIGN command equates the logical name DISK to the device
OBI:.
The second ASSIGN command equates the logical name REPORT to
the file specification DISK: [HUMIDO]WEATHER.SUM.
In
subsequent
commands, or in programs you execute, you can refer to the logical
name REPORT.
For example,
$ TYPE REPORT

4-8

FILE CONTROL ROUTINES
When FCS attempts to translate the logical name REPORT, it checks the
logical
name
tables
and
finds
the
equivalence
name
DISK: [HUMIDO]WEATHER.SUM.
It then checks the file specification for
the presence of a
logical name; if it finds a match in one of the
logical name tables (DISK in this example), it translates that logical
name also.
When the logical name translation is complete, the
following translated file specification results:
OBI: [HUMIDO]WEATHER.SUM
If you define a
FCS limits logical name translation to ten levels.
logical name to more than ten levels or create a circular definition,
an error occurs when you use the logical name.
If a device name or file specification is preceded by an underscore
(_), the logical translation process stops.
In the example,
TYPE

REPORT

FCS would look for the file REPORT. in your default device and
directory.
Note also that if an extension or version are included
with the file name, it is not considered for logical translation.
In
the example,
TYPE REPORT.TXT
Fes would look for the file REPORT.TXT
d i rectc)ry.

your

default

device

4.7.1.2 Logical Translation Process - The following three
operations occur during the logical translation process:

and

basic

Parsing the file specification - Fes determines the location
and
length of the various parts of the primary file
specification. It sets flags indicating which parts were
present and which parts contain wild cards. The length and
location of the string following the file specification is
also determined.

Expanding the string - Fes takes the first portion of the
string and attempts to translate it.
The first portion could
be a logical name. A logical name can be a device name or a
file name.
If there is a logical name string to equivalent
string translation, Fes uses the equivalent string as the
secondary string in a merge.
The primary string for this
merge is the original file specification less the logical
name.
This operation is reiterative until one of the
following occurs:
There is no logical name to translate.
The translation fails.
The result of the translation is not a file specification.
The recursion limit of more than ten levels of translation
has occurred.
The first character is an underscore ( ).

Merging the specifications - Fes generates a merged string
from the primary and the default string. The merged string
consists of the primary string with any missing components
filled in from the default string.
4-9

FILE CONTROL ROUTINES
4.7.2

.PARSE - Fill in All File Name Information

FCS includes the main support for logical name translation in the FCS
• PARSE directive.
When the • PARSE routine receives a string, the
.PARSE routine performs any necessary logical expansion and parses the
resultant string.
If you use logical name parsing, logical translation is performed
first.
If you have not requested logical name translation (as when it
has already been done by CSI$4), the FL.AEX bit should be set in the
F.FLG byte in the FOB.
Setting this bit disables logical name
translation.
When called, the .PARSE routine first zeros the filename block pointed
to by Rl and then stores the following information in the filename
block:

• The ASCII device name (N.OVNM)
• The binary unit number (N.UNIT)
• The directory 10 (N.OIO)

• The Radix-50 file name (N .FNAM)
• The Radix-50 file type or extension (N .FTYP)
• The binary file version number (N.FVER)
For ANSI magnetic tape file names, the following information is stored
in the filename block:
•

The ASCII device name (N.OVNM)

•

The binary unit number (N.UNIT)

•

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

•

The binary file version number (N.FVER)

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

preset

before

calling

the

• PARSE

must contain the address of the desired FOB.

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

4-10

FILE CONTROL ROUTINES
R2

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

must contain the address of the desired default filename
block for the • PARSE routine to access a default filename
block in filling in the ~pecified filename block.
This
default filename block is usually, but not necessarily, the
same as the one associated with the FOB specified in RO (that
is, the default filename block pointed to by the address
value in F.DFNB).
If R3 contains 0, a default filename block has not been
defined;
therefore,
the default filename block logic of the
.PARSE routine is bypassed.

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

order

4.7.2.1 Device and Unit Information - The .PARSE routine first tries
to fill in the filename block with device (N.DVNM) and unit (N.UNIT)
information.
The following operations are performed until
the
requirE!d information is obtained from the specified data structures:
1.

If the address of a dataset descriptor is specified in R2 and
the dataset descriptor contains a device string, the .PARSE
routine moves the device and unit information from the
dataset descriptor into the specified filename block.

If step 1 fails, and if the address of a default filename
block is specified in R3, and the default filename block
contains a nonzero value in the device name field, the .PARSE
routine moves the device and unit information from the device
name field into the specified filename block.

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

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

4-11

FILE CONTROL ROUTINES
The .PARSE routine first determines the device and unit, assigns the
logical unit number, and then invokes the GLUN$ directive to obtain
necessary device information. The required information obtained by
GLUN$ is placed by the .PARSE routine into the following offsets in
the filename block pointed to by Rl:
N.DVNM

- Device Name Field, which contains the redirected device
name.

N.UNIT

- Unit Number Field, which contains the
number.

redirected

Additionally, the .PARSE routine places the information returned
GLUN$ into the following offsets in the FOB, which RO points to:

unit
by

F.RCTL

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

F.VBSZ

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

The GLUN$ directive is described in detail in the
Micro/RSX Executive Reference Manual.

RSX-llM/M-PLUS

and

4.7.2.2 Directory Identification Information - The N.DID field in the
filename block contains the following information:
Word

Meaning

File 10

File Sequence Number

Reserved

The .PARSE routine moves these three words from the Master File
Directory (MFD) to the N.DID field in the filename block. The file 10
is the header number of the header (in the index file) for a User File
Directory.
The .FIND routine uses the file 10 to locate and search a
UFO and fill in the N.FID field in the filename block. The N.FID has
the same format as the N.DID field except that it identifies the
header number of the header for a user data file.
The file sequence
number is incremented each time a file header is reused for a new
file.
Following the operations described in the preceding section,
• PARSE
attempts to fill in the filename block with directory identification
(N.DID) information. The methods for obtaining this information are
as follows:
1.

If your task specifies the address of a dataset descriptor in
R2 and the dataset descriptor contains a directory string,
FCS uses that directory string to find the associated UFO in
the MFD.
The resulting file 10 is then moved into the
directory-ID field of the specified filename block.
4-12

FILE CONTROL ROUTINES
2.

If step 1 fails, and your task specifies the address of a
default filename block in R3, and the default filename block
contains a nonzero directory ID, the contents of the default
filename block are moved into the specified filename block.
Because none of the parameters of the NMBLK$ macro call
(see
Section 2.4.2) initialize the three words starting at offset
location N.DID in the default filename block, your task must
initialize these cells manually. Or your task can call the
.GTDIR routine (see Section 4.9.1) or the .GTDID routine (see
Section 4.9.2). Note that these routines can also initialize
a specified filename block directly with required directory
information.

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

If steps 1 through 3 fail to produce directory information,
FCS uses the binary value stored in the default UIC word in
program section $$FSR2 as the directory identifier.
Unless
changed by you through the .WDFUI routine, this word contains
the UIC under which the task is running.
NOTE
The .PARSE routine does not accept UICs that contain
wildcards.
Additionally, the .PARSE routine does not
set filename block status word (N.STAT) bits NB.SDI or
NB.SD2
(group and owner wildcard specifications,
respectively) •

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

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

If your task specifies the address of a default filename
block in R3, and one or more of the file name, file type, and
file version number fields of the dataset descriptor that you
specified in R2 are null, the corresponding fields of the
default filename block fill in the specified· filename block.

If neither step 1 nor step 2 yields the requisite file name
information, any specific fields not available from either
source remain null.
NOTE
If a period (.) appears in the filename string without
an accompanying file type designation (for example,
TEST. or TEST.;3), FCS interprets the file type as
being explicitly null.
In this case, the default file
type is not used.
4-13

FILE CONTROL ROUTINES
Similarly, if a semicolon (i) appears in the filename
string without an accompanying file version number
(for example, TEST.DATi), FCS also interprets the file
version number as being nulli again, the default file
version number is not
used.
This
information
concerning semicolons in filename strings does not
apply to the l7-byte ASCII filename strings supported
for ANSI magnetic tape.

4.7.2.4 Using the FOB Extension for Logical Names - FCS uses the FOB
extension to obtain the correct directory string. The extension has
the following format:
.BYTE
.BYTE
.BYTE
.BYTE
.WORD

Extension length
Unused
Length of the directory string buffer
Length of the directory string (filled in by .PRSDI)
Address of the directory string buffer

The FOB extension block and the directory string buffer are allocated
in your task's address space. You fill in the address, the length of
the buffer, and the length of the 'extension into the appropriate
locations in the FOB extension block. You then place the address of
the extension block in the offset F.EXT in the FOB.
When the
directory parsing code detects that F.EXT has a value, it uses the
value as an address and moves the directory string into the buffer.
It also puts the length of the actual directory string into the
appropriate byte of the extension. This directory string is always
filled in unless FCS obtains the directory from the default name
block, because the default name block does not contain the directory
string.
If FCS obtains the directory from the default name block, FCS
sets the directory length to zero.

4.7.2.5 Other Filename Block Information - After performing all the
previously described operations, the .PARSE routine also fills in the
status word (offset location N.STAT) of the filename block specified
in Rl.
The bit definitions for this word are presented in Table B-2.
Note
that in this table the directory, device, file name, file type, or
file version number specification pertains to ASCII data supplied
through the dataset descriptor pointed to by R2.
In addition, the .PARSE routine zeros offset location N.NEXT in the
filename block pointed to by Rl. This action has implications for
wildcard operations, as described in Section 4.8.1.

4.7.2.6 .EXPLG Module (Expand Logical) - The .EXPLG module expands a
logical name and returns a pointer to the task that points to the
expanded string. The module has the following inputs and outputs:
INPUTS:

R2 - Pointer to the dataset descriptor of the string to
be expanded.

OUTPUTS:

R2 - Pointer to the dataset descriptor of the
string. All other registers are preserved.

4-14

expanded

FILE CONTROL ROUTINES
This routine expands the string into the same buffer that the • PARSE
routine and CSI$4 use for input files; therefore, caution is advised
if you use this method. In addition, the call only accepts logical
names that expand into a correct FCS file specification.
The
inclusion of a node specifier or other non-FCS characters results in
an error being returned.

4.7.3

.,PRSDV - Fill in Device and Unit Information Only

The .PRSDV routine is identical to the .PARSE routine, except that it
performs only those operations associated with requisite device and
unit information (see Section 4.7.1.1). The .PRSDV routine zeros the
filename block pointed to by Rl, calls the .PARSE routine to operate
on the device and unit fields in the specified dataset descriptor or
default filename block, and assigns the logical unit number contained
in offset location F.LUN of t~e specified FOB.
After the logical device translation is performed,
.PRSDV fills the
filename block with the required device and unit information.
If the
device is LB:, the actual physical device name and unit are placed in
the filename block.
If the logical device expands to contain anything
other than a device specification, for example, a directory or a
filenam'~,
the remainder is ignored.
Setting the FL.AEX bit (see
Chapter 6) disables logical expansion for the device and unit
information.

4.7.4

.PRSDI - Fill in Directory Identification Information Only

The .PRSDI routine is identical to the .PARSE routine, except that it
performs only those operations associated with requisite directory
identification information (see Section 4.7.1.2). The .PRSDI routine
performs
a
• PARSE
operation
on the directory identification
information (N.DID) field in the specified dataset descriptor or
default filename block.
The .PRSDI routine does not perform any
logical name expansion.

4.7.5

.PRSFN - Fill in File Name, File Type, and File Version Only

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

4.7.6

.ASLUN - Assign Logical Unit Number

The .ASLUN routine assigns a logical unit number to a specified device
and unit and returns the device information to a specified FOB and
filename block.

4-15

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

must contain the address of the desired FOB.

must contain the address of the filename block where the
desired device and unit information are located.
This
filename block is usually, but not necessarily, within the
FOB specified by the address in RO.

If the device name field (offset location N.DVNM)
of the filename
block pointed to by Rl contains a nonzero value, the specified device
and unit are assigned to the logical unit number contained in offset
location F.LUN in the FOB pointed to by RD.
If offset location N.DVNM in the filename block contains 0, then the
device and unit currently assigned to the specified logical unit
number are returned to the appropriate fields of the filename block.
Finally, if the specified logical unit number is not assigned to a
specific device,
the .ASLUN routine assigns it to the system device
(SYO:) by default.
The information returned to the specified filename block and the
specified FOB is identical to that returned by the device and unit
logic of the .PARSE routine (see Section 4.7.1.1).

4.8

DIRECTORY ENTRY ROUTINES

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

4.8.1

.FIND - Locate Directory Entry

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

must contain the address of the desired FOB.

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

filename
the FOB

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

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

(largest)

version

number

•

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

number

If either of these special versions is specified in the filename
block, the matching version number is returned to the filename block.
In this way, the actual version number is made available to the
program.
4-16

FILE CONTROL ROUTINES
Certain ,~ildcard operations require the use of the .FIND routine.
Three bits in the filename block status word (see N.STAT in Table B-2)
indicate whether a wildcard (*) was specified for a file name, a file
type, or a file version number field.
If the wildcard bit in N.STAT
is set for a given field,
any directory entry
matches
that
corresponding field.
Thus, if the file name and file version number
fields contain wildcard specifications (*), and the file type field is
specified as
.OBJ
(that is,
*.OBJ;*), the first directory entry
encountered that contains .OBJ in the file type field matches.
When a wildcard match is found, the complete file name, file type, and
file velrsion number fields of the matching entry are returned to the
filename block, along with the file-ID field
(N.FID).
Thus,
the
program can determine the actual name of the file just found. Offset
location N.NEXT in the filename block is also set to indicate where
that directory entry was found in the directory file. FCS uses this
information in subsequent .FIND operations to locate the next matching
entry in the directory file.
For example, the .FIND routine often opens
wildcard specifications are used.
The
typical:

a series
following

of files when
operations are

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

Check for wildcard bits set by the • PARSE routine in the
filename block status word
(see N.STAT in Table B-2). An
instruction sequence such as that shown in the following text
tests for the setting of wildcard bits in N.STAT:

BIT

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

BEQ

NOWILD

;BRANCH IF NOT SET.

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

.FIND

BCS

DONE

;ERROR CODE IE. NSF INDICATES
;NORMAL TERMINATION.

OPEN$ RO
Wildcard .FIND operations update offset location N.NEXT in
the filename block.
In essence, the contents of this cell
provide the necessary information
for
continuing
the
directory file search for a matching entry.
4.

Perform the desired operations on the file.
NOTE
This procedure applies only to the following types
wildcard file specifications:
TEST.DAT;*
TEST.*;*
*.DAT;*
TEST.*;5
*.DAT;3

4-17

FILE CONTROL ROUTINES
This procedure does not work for the
of wildcard file specifications:

following

types

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

names

the

following

formats

•

Up to nine Radix-50 characters followed by spaces

•

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

can

followed

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

4.8.2

.ENTER - Insert Directory Entry

You use the .ENTER routine to insert an entry
directory.

file

name

into

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

must contain the address of the desired FOB.

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

4-18

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

4.8.3

connection

.REMOV - Delete Directory Entry

You use the .REMOV routine to delete an entry from a directory by file
name.
This routine only deletes a specified directory entry; it does
not delete the associated file.
The following registers must be preset before calling this routine:
RO

must contain the address of the desired FOB.

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

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

4.9

FIL,ENAME BLOCK ROUTINES

The .GTDIR and .GTDID routines insert directory
specified filename block.
Sections 4.9.1 and
describe the use and operation of these routines.

4.9.1

information in a
4.9.2, following,

.GTDIR - Insert Directory Information in Filename Block

You call the .GTDIR routine to insert directory information
directory string descriptor into a specified filename block.

from

Before calling this routine, the following registers must be preset:
RO

must contain the address of the desired FOB.

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

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

4-19

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

4.9.2

macro call
(see
into a specified

.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, this routine uses the binary value found in the default UIC
word maintained in program section $$FSR2 as the desired UFD.
Before calling the .GTDID
registers:

routine,

you

must

preset

the

following

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, within the FDB specified by
the address in RO.

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

4.10

177777,177777,0

for

nondirectory

FILE POINTER ROUTINES

The .POINT, .POSRC, .MARK, and .POSIT routines point to a byte or a
record within a specified file.
Sections 4.10.1 through 4.10.3,
following, briefly describe the use of these routines and their
operation.

4-20

FILE CONTROL ROUTINES
4.10.1

.POINT - position File to Specified Byte

You call the .POINT routine to position a file pointer 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 FOB in preparation for a
PUT$ operation in locate mode.
The following registers must be preset before calling this routine:
RO

must contain the address of the desired FOB.

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

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

must contain the desired byte
virtual block.

number

within

the

specified

For a description of virtual block numbers and how these 2-word values
are formed, refer to item 4 in Section 2.2.2.1.
NOTE
Use of the .POINT routine is restricted to files
accessed with GET$ or PUT$ macros. For files accessed
with READ$ or WRITE$ macros, use the FDBK$R macro to
initialize the block access section of the FOB.
The .POINT routine is used often with the .MARK routine and achieves a
limited degree of random access with variable-length records.
The
.MARK routine saves the positional information of a file, permitting
you to temporarily close that file and reopen it later at the same
position; this procedure is outlined in the following steps:
1.

Call the .MARK routine to save the current positional context
of the file.

Close the file.

Reopen the file when desired.

Load the information returned by the .MARK routine
R2, and R3.

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

Resume processing of the file.

4.10.2

into

Rl,

.POSRC - position File to Specified Record

The .POSRC routine sets up the position information for 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.

4-21

FILE CONTROL ROUTINES
Before calling this routine, you 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.
The register RO must be preset before calling the .POSRC routine:
RO

must contain the address of the associated FOB.

You use the .POSRC routine when performing random access PUT$
operations in locate mode.
Normally, PUT$ operations in locate mode
are sequential; however, when you use random access mode, you must
follow the next procedure 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.NRBO+2 of the associated FOB.

Perform the PUT$ operation.

4.10.3

the

associated

.MARK - Save position Information Context of File

The .MARK routine allows you to save the current position information
of a file for later use; you can save the current position information
of a file, close that file, and later reopen it to the same position.
The .MARK routine also allows you to alter records within a file; you
can save the file position, retrieve information elsewhere in that
file, and return to the saved position of the file to alter the
desired record. This sequence may be repeated to update any number of
desired records in the file.
The following register must be preset
before calling the .MARK routine:
RO

must contain the address of the associated FOB before calling
this routine.

When called, the .MARK routine returns information
registers:

the

following

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

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

contains the number of
block.

the

byte

within

the

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 Specified Record position Information

The .POSIT routine calculates the virtual block number
number locating the beginning of a specified record.

and

the

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

must contain the address of the associated FOB.

4-22

byte

FILE CONTROL ROUTINES
In addition, offset locations F.RCNM and F.RCNM+2
FOB must contain the desired record number.

the

associated

Unlike the .POSRC routine, which sets up the position information of
the file to the specified record, .POSIT calculates the positional
information of a s~ecified record so that a .POINT operation can be
later performed to position to the desired record.
The .POSIT routine returns register values
described pr~viously for the .MARK routine.

4.11

identical

those

QUEUE I/O FUNCTION ROUTINE (.XQIO)

The Queue I/O Function Routine
(.XQIO)
function and waits for its completion.

executes

specified

QIO$

The following registers must be preset before calling this routine:

4.12

must contain the address of the desired FOB.

must contain the desired QIO$ macro function code. Refer to
the RSX-llM/M-PLUS I/O Drivers Reference Manual or Micro/RSX
I/O Drivers Reference--Manuar--for the deslred QIO$ macro
function codes.

must contain the number of optional parameters, if any, to be
included in the QIO$ directive.

must contain the beginning address of the list of optional
QIO$ directive parameters, if R2 contains a nonzero value.
Refer to the RSX-llM/M-PLUS I/O Drivers Reference Manual or
Micro/RSX Drivers Reference Manual for the parameter llst.

RENAME FILE ROUTINE (.RENAM)

The .RENAM routine is called to change the name of a file in its
associated directory. To rename a file, you must specify the address
of an FOB containing file name information, a LUN, and an event flag
number.
If the file to be renamed is open when the call to .RENAM is issued,
that file is closed before the renaming operation is attempted.
The following registers must be preset before calling this routine:
RO

must contain the address of the FOB associated with the
with the original name.

file

must contain the address of the FOB containing the desired
file name information, LUN assignment, and event flag.

If the renaming operation is successful, a new directory entry is
created and the original entry is deleted.
If the operation is
unsucce·ssful, the file is closed under its or igi nal name, and the
associated directory is not affected.
The .RENAM routine uses the absence of a value
in
location
F.FNB + N.FID to indicate that .PARSE must be called to parse a file
specification (an open file always has
a
nonzero
value
in
F.FNB + N.FID).
If neither a dataset descriptor nor a default

4-23

FILE CONTROL ROUTINES
filename block is present, .PARSE returns a null file name.
The
rename operation then produces a new file name of version ".;1".
If a
wildcard (*)
is part of the
input file specification, wildcard
processing
like
that described for the
.FIND routine occurs.
Wildcards are not allowed in an output file specification.
NOTE
The renaming process is merely a directory operation
that replaces an old entry with a new entry.
The file
name stored in the file header block is not altered.

4.13

FILE EXTENSION ROUTINE (.EXTND)

The .EXTND routine extends either contiguous or noncontiguous files.
The file to be extended can be either open or closed. A call to the
.EXTND routine disables file truncation.
You must explicitly call
.TRNCL to truncate a file after you call .EXTND.
The following registers must be
routine:

preset

before

calling

the

.EXTEND

must contain the address of the associated FOB.

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

blocks

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

FCS uses the contents of Rl and the high-order
byte of R2
(Bits 8 through 15) to perform the
specified .EXTND operation.
Thus,
24 bits of
magnitude are available for specifying the number
of blocks by which the file is to be extended.

If a file previously had space allocated to it, a
contiguous file extension by the .EXTND routine
cannot be done.
You can create a contiguous file
by opening a new file with a zero allocation and
calling .EXTND to allocate the desired number of
blocks.

When writing a new file using QIO$ macros,
the
task
must
explicitly issue .EXTND calls as
necessary to reserve enough blocks for
the file,
or
the file must be initially created with
sufficient blocks.
In addition, the task must put
an
appropriate
value
in
the FOB for the
end-of-file block number (F.EFBK)
before closing
the file or rewinding and reading it.

If R2 contains
a
zero,
noncontiguous allocation.
4-24

FCS

defaults

FILE CONTROL ROUTINES
In general, when FCS implicitly extends a file,
it activates file
truncation.
See Section 4.14 for information on how to turn off file
truncation. When your program explicitly allocates space to a file,
either with an OPENS or .EXTND, FCS turns off truncation. To turn off
file truncation and close the file, call the following routines:
1.

Call the .EXTND routine.

Issue the CLOSES macro.

4.14

Set both Rl and R2 to O.

FILE TRUNCATION ROUTINE (.TRNCL)

The .TRNCL routine truncates a file to the logical end of the
deal locates any space beyond this point, and closes the file.

file,

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.
FCS turns on truncation when it extends a file.
However, when your
progr~m explicitly calls the .EXTND routine, FCS turns off truncation.

4.15

FILE DELETION ROUTINES

FCS provides the .MRKDL and .DLFNB routines for deleting files.
NOTE
If you use the .MRKDL or .DLFNB routine to delete a
file containing sensitive information, you should
clear the file before closing it or reformat the disk
to destroy the sensitive information.
(Although the
file is marked
for
deletion,
the
information
physically remains on the volume until written over
with another file,
and
could
be
analyzed
by
unauthorized users.)

4.15.1

.MRKDL - Mark Temporary File for Deletion

You use the .MRKDL routine to mark a temporary file for deletion: that
is, a. file created through the OPNT$W macro call (see Section 3.3).
Such a file has no associated directory entry.
A call to the .MRKDL routine is issued prior to closing a temporary
file.
The file so marked is then deleted when the file is closed.

4-25

FILE CONTROL ROUTINES
Table 4-1
R2 Control Bits for .EXTND Routine
Value in Low-Order
Byte of R2

Meaning

Indicates that the
noncontiguous.

200

Indicates that the file extent is to be
noncontiguous.
This clears the contiguous
file attribute.

201

Indicates that the contiguous area is to be
added
to
the
file.
This clears the
contiguous file attribute.

203

Indicates
that
the
largest
available
contiguous area is to be added to the file
if the desired file extent space is not
available.
This clears the contiguous file
attribute.

205

Indicates that this is the initial extent of
the file.
The file is to be contiguous.

207

Indicates that the largest contiguous area
up to the specified extend size is to be
added to the file.
The file is to be
contiguous.

210

Indicates that the file is to be extended by
the def~ult extend size for the volume.
The
extend is to be noncontiguous.

211

Indicates that the file is to be extended by
the default extend size for the volume. The
extend is to be contiguous, whereas the file
is to be noncontiguous.

Before calling the .MRKDL
register:
RO

routine,

you

file

must

extent

preset

the

following

must contain the address of the associated FOB. This FOB is
assumed to contain the file identification, device name, and
unit information of the file to be deleted.

If the .MRKDL routine is invoked while the temporary file is open,
as
is normally done,
the file
is deleted unconditionally when it is
closed.
This occurs even if the calling task terminates abnormally
without closing the file.

4.15.2

.DLFNB - Delete File by Filename Block

You use this routine to delete a file by filename block.
The .DLFNB
routine assumes that the filename block is completely filled; 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 FOB.
4-26

FILE CONTROL ROUTINES
The .DLFNB routine operates in the same manner as the DELET$ macro
call (see Section 3.18), but .DLFNB does not require any of the .PARSE
logic and thus requires less memory than the normal DELET$ function.
Like the DELET$ operation, however, the .DLFNB operation fails if the
file to be deleted is not open, and if an explicit file version number
is missing from offset location N.FVER of the associated filename
block.

4.16

DEVICE CONTROL ROUTINE (.CTRL)

control
You call the .CTRL routine to perform device-specific
functions.
The following are examples of .CTRL device-specific
functions:
•

Rewind a magnetic tape volume set.

•

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

•

Close the current magnetic tape
operations on the next volume.

•

Space forward or backward n blocks on a magnetic tape.

•

Rewind a file
on
a
(record-oriented device).

•

Clear the terminal end-of-file.

magnetic

volume

tape

and

continue

file

terminal

The following registers must be preset before calling this routine to
perform the first three bulleted items listed previously in this
section.
RO

must contain the address of the associated FOB.

must contain one of the following function codes:
•

FF.RWD to rewind a magnetic tape volume set.

•

FF.POE to position to the logical end· of a magnetic
volume set.

•

FF.NV to close the current volume and continue file
operations on the next volume of a magnetic tape volume
set.

tape

must be set to

must be set to O.

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

that

must contain the address of the associated FOB.

must contain the value FF.SPC.

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

R~
~

must contain

4-27

FILE CONTROL ROUTINES
When using .CTRL to rewind a file, you must ensure that register
contains the value FF.RWF and that registers R2 and R3 contain o.

See Chapter 5 for an explanation of using .CTRL to accomplish magnetic
tape device-specific functions.

4.17

BUFFER FLUSH ROUTINE (.FLUSH)

The buffer flush routine (.FLUSH) writes the block buffer to the file
being written in record mode.
The .FLUSH routine also writes file
attributes
(including F.EFBK and F.HIBK,
the
end-of-file
and
high-allocation block numbers) each time the routine is called.
Closing the file guarantees that the block buffer is flushed and that
the file attributes will be written back to the file header.
However,
closing and opening a file frequently, solely to write the block
buffer, causes high system overhead and unnecessary disk accesses.

4.17.1

Purpose of the .FLUSH Routine

When FCS executes a PUT$ macro to a disk file, the PUT$ macro puts a
record into the block buffer. When the block buffer is full, or the
file is closed, FCS writes the block buffer to the file.
You cannot
predict when FCS will actually write the block buffer to the file.
Some applications may require that a record be written to a file
immediately.
As an example, a task that handles a laboratory device
may write small amounts of data to a file every few minutes.
If the
system crashes,
the contents of the block buffer may not have been
written to the file.
This data may be lost unless a PUT$ is
immediately followed by a call to the .FLUSH routine. As another
example, the .FLUSH routine should be called by an originating task to
write data immediately if another task must then read data written by
that originating task.
In these examples, the tasks need not close
the file to ensure that the data is written to the file.

4.17.2

When .FLUSH Should Be Used

Your task should call
written to a file.

.FLUSH

whenever

data

should

immediately

You need not call the .FLUSH routine for block mode (WRITE$) or record
mode
(PUT$)
write operations to a record-oriented device; the block
buffer is always written in these cases. Nothing happens if you call
.FLUSH when a file is open under these circumstances except the return
of a cleared Carry bit and status +1 (success) in FOB byte F.ERR.

4.17.3

Performance Considerations Using .FLUSH

Calling the .FLUSH routine after every PUT$ macro can greatly increase
I/O activity compared to using solely the PUT$ macro. One alternative
is to call the .FLUSH routine after certain intervals have passed or
after a certain number of calls to PUT$.

4-28

FILE CONTROL ROUTINES
4.17.4

Using the .FLUSH Routine

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

must contain the address of the associated FOB.

During output, all registers are preserved, the C-bit is clear or set
to indicate success or failure, and the FOB F.ERR byte contains the
success or failure code.

4-29

CHAPTER 5
FILE STRUCTURES

This chapter describes the structure of files supported by the RSX-llM
systems.. It specifically covers the identical file structure on disk,
DECtape" and DECtape II and the ANSI file structure on magnetic tape
supported by the Micro/RSX and RSX-llM/M-PLUS systems.
The disk, DECtape, and DECtape II file structure is
the magnetic tape file structure is ANSI standard.

called

Files-II;

The Fi143S-11 structure is a file-organization system, which primarily
determines the way that files and their associated control files are
arranged on a disk or DECtape. Associated with the Files-II structure
is a system of data structures in memory, the most important of which
include the Volume Control Block, the File Control Block, and the
Device Control Block.
Files-II structure includes not only the
physical file and its associated control files,
but the necessary
information in these files that determines the file's size, location,
content, and various attributes.
The ANSI standard describes a way of organIzIng sequential files on a
magnetic tape that allows the tape to be used on any computer system.
The standard includes file structure,
labeling,
and
physical
characteristics such as end-of-tape length.

5.1

DISK AND DECTAPE FILE STRUCTURE (FILES-ll)

Disk and DECtape volumes (defined by and associated with a Volume
Control Block)
contain both user files and system files. Disks and
DECtapes initialized through the DCL command INITIALIZE or MCR command
INITVOLUME have the standard Files-II structure built for them. The
standard system files created by these commands include:

• Index file

• Storage allocation file
• Bad block file
• Master File Directory (MFD)
• Checkpoint file
Each Files-II volume has all of these files. A volume may have more
than one directory file; the system uses these files, created by the
MCR UFD command or the DCL CREATE/DIRECTORY command for RSX-llM/M-PLUS
and Mic:ro/RSX systems, to locate user files on the volume.

5-1

FILE STRUCTURES
5.1.1

User File Structure

Data files on disk and DECtape consist of ordered sets of virtual
blocks; these blocks constitute the virtual structure of the data
files as they appear to you. Virtual blocks can be read and written
directly by issuing READ$ and WRITE$ macro calls (see Sections 3.15
and 3.16, respectively). The first block in the file is virtual block
1; subsequent virtual blocks are numbered in ascending order.
The virtual blocks of a file are stored on the volume as logical
blocks.
Because virtual blocks and logical blocks are equal in size,
and the logical block size of all "volumes is 256 words, each virtual
block is also 256 words. When access to a virtual block is requested,
the virtual block number is mapped into a logical block number.
The
logical block number is then mapped to the physical address on the
associated volume.

5.1.2

Directory Files

A directory file contains directory entries. Each entry consists of a
file name and its associated file number and file sequence number.
The number of required directory files depends on the number of users
of the volume.
For single-user volumes, only a Master File Directory
(MFD) is needed; for multiuser volumes, an MFD is required, and one
User File Directory (UFD) is required for each user of the volume.
The MFD contains a list of all the UFDs on the volume, and each UFD
contains a list of all that user's files.
UFDs are identified by User
Identification Codes
(UICs).
An MCR UFD
command
or
a
DCL
CREATE/DIRECTORY command creates the User File Directory. These
commands are described in detail in the RSX-IIM/M-PLUS MCR Operations
Manual and the RSX-IIM/M-PLUS Command Language Manual.
Figures 5-1 and 5-2 illustrate the directory structure for single-user
and multiuser volumes, respectively.

5.1.3

Index File

You create the index file for the operating system to use when you
initialize a volume. During initialization, the information requir~
by the system to manage the file is placed in the index file.
The
index file contains volume information and user file header blocks,
which the system file control primitives (FCP) use to manage the file.
The file header blocks
(see Section 5.1.4) are stored in the index
file so that they can be located quickly. Furthermore, because a file
header block is 256 words in length, it can be read into memory with a
single access. Appendix E contains a detailed description of the
format and content of an index file.

5-2

FILE STRUCTURES

MFO

FILE A

FILE B

FILE C

ZK-293-81

Figure 5-1

Directory Structure for Single-User Volumes

MFO

UFO
100,100

UFO
200,200

FIL~

FILE B

FILE A

I
I

FILE B

FILE C
ZK-294-81

Figure 5-2

5.1.4

Directory Structure for Multiuser Volumes

File Header Block

Each file has a file header block that contains a description of the
file.
File header blocks are stored in the index file.
Each file
header block is 256 words long and contains 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 identifi~d by a file 10 consisting of two words. Fes
uses the first word of the file 10
(that is,
the file number)
to
calculate the virtual block number (VBN) of that file's header block
in the index file.
(This calculation is done as follows:
the VBN is
the file number + 2 + the number of index file bit map blocks.) The
operating system uses the second word
(that is,
the file sequence
number)
to verify that the header block is really the header for the
desired file.
When you request file access, both the file number and the file
sequence number are specified.
The system denies a request for access
if the file sequence number does not match the corresponding field
in
the file header block that is associated with the specified file
number.

5-3

FILE STRUCTURES
When you delete a file, its file header block space becomes available
for storing a newly created file's sequence number.
If you attempt to
access a file that has been deleted (for example, by referencing an
obsolete directory entry), this updated file sequence numbe~ ensures
the rejection of the request for access, even if the same file header
block is reused for a different file.
The identification area specifies the file's creation name and
identifies the file owner's UIC.
This area also specifies the
creation date and time, the revision number, the date and time of the
last revision, and the expiration date.
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

RSX-IIM/M-PLUS and Micro/RSX systems support the standard
ANSI
magnetic tape structure as described in "Magnetic Tape Labels and File
Structure for Information Interchange," ANSI X3.27-1978. Any of the
following file/volume combinations can be used:
•

Single file on a single volume

•

Single file on more than one volume

•

Multiple files on a single volume

•

Multiple files on more than one volume

The second and fourth file and volume combinations constitute a volume
set.
The record format on magnetic tape differs from that on disk. When a
file containing variable-length records or fixed-length records that
cross block boundaries is copied to magnetic tape,
it occupies more
blocks on the magnetic tape than it did on the disk.
This is so
because magnetic tape record counts are larger disk record counts, and
there is unused space at the end of the blocks.
In addition, a bit is
set in the file's FOB that indicates the file cannot cross block
boundaries.
Appendix G defines the sequence in which volume and
used and the format of each label type.

file

labels

NOTE
The ANSI file header label contains no place for the
creation
time
or
the
length
of
the
file.
Consequently, the creation time of a
file on ANSI
magnetic tape is listed as O.
If a contiguous file is
copied to ANSI magnetic tape and then transferred back
to disk,
the resulting disk file is not marked as
contiguous even if you use the /CO switch, because the
system cannot know how much space to allocate for the
output file when it reads from magnetic tape.

5-4

are

FILE STRUCTURES
5.2.1

Access to Magnetic Tape Volumes

MagnetiC' tape is a sequential access, single-directory storage medium.
Only one user can have access to a given volume set at a time. Only
one file~ in a volume set can be open at a time. The system protects
access by volume set rather than by file.
On volumes produced by
DIGITAL systems,
the contents of the owner identification file
determine user access rights as described in Section G.l.l.l. Volumes
produced by non-DIGITAL systems are restricted to read-only access
unless the access is overridden explicitly at MOUNT time.

5.2.2

Rewinding Volume Sets

You can rewind a magnetic tape volume set by usin9 either the FDOP$R
macro before an OPEN$ or CLOSE$ macro or by using the .CTRL file
control routine. Regardless of the method you use, FCS performs these
procedul:es:

5.2.3

All mounted volumes
(BOT) •

are

rewound

the

beginning-of-tape

If the first volume in the set is not
device-unit to be used is placed off line.

If the volume is not already mounted and if the rewind was
requested with an OPEN$ macro or by a .CTRL routine call, a
request to mount the first volume appears on the operator's
console.

If the rewind was requested with a CLOSE$ macro,
message is issued until the next volume is needed.

mounted,

the

mount

Positioning to the Next File position

The standard procedure for writing a new file onto a magnetic tape is
to begin writing the file following the end of the volume set's last
file.
However, you can use the FDOP$R macro to indicate that the new
file is to be written immediately after the labels at the end of the
most recently closed file.
NOTE
The 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
itself at the logical end of the volume set to create the file.
When you use the default, the file system makes no check 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.
5-5

FILE STRUCTURES

Directory device file processors ignore the next file position option.
However, programs written mainly for directory devices can specify the
next file position option in open commands for output and,
therefore,
override a process of positioning the file system to the logical end
of file normally used with ANSI magnetic tape.

5.2.4

Single-File Operations

You perform single-file operations by specifying the rewind option
with the FDOP$R macro before the open and before the close. Using
this approach, you can perform operations on temporary tapes or work
tapes (scratch tapes) as follows:
1.

Open the first file with the rewind option specified.

Write the data records and close the file with rewind.

Open the first file again for input (rewinding is optional).

Read and process the data.

Close the file with rewind.

Open the second file with rewind specified.

Write the data records.

Close the file
processing.

5.2.5

with

rewind

and

perform

any

additional

Multiple-File Operations

You create a multiple-file volume by first opening, writing, and then
closing a series of files without specifying the rewind option.
You
can process files sequentially on the volume by closing without rewind
and opening the next file without rewind.
Opening a file for extend with the OPEN$A macro is legal only for
last file on the volume set.

the

Perform the following tape operations to create a
volume:

tape

multiple-file

Open a file for output with the rewind option.

Write data records and close the file.

Open the next file without rewinding.

Write the data records and close the file.

Repeat for as many files as desired.

You can open files on tape in a nonsequential order, but doing so
increases processing and tape-positioning time.
Nonsequential access
of files in a multivolume set is not recommended.

5-6

FILE STRUCTURES
5.2.6

Using .CTRL

You can call the .CTRL file control routine to override normal
defaults for magnetic tape. This routine might be used to:
•

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

•

Position to the logical end-of-volume set.

•

Rewind a volume at other times than when
the file.

•

Space forward or backward any number of records.

•

Rewind a file.

When FCS uses
next volume,
File sections
The po:rtion
section. For
occurs:

opening

FCS
set

closing

the .CTRL routine to continue processing a file on the
the first file section on the next volume is opened.
occur when a file is written on more than one volume.
of the file on each of these volumes constitutes a file
input files,
the following .CTRL routine processing

If the current volume is the last volume in the set (that is,
there is no next volume), the end-of-file is reported to you.

If another file section exists, the current volume is rewound
and the next volume is mounted. A request to mount the next
volume appears on the operator's console.

The header label (HDRl) of the next file section is read
checked.

If all required fields check, the operation continues.

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

mount

and

the

For output files, the following .CTRL routine 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 a write operation. 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
on the next file section.

are

written

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

5-7

FILE STRUCTURES
5.2.7

Examples of Magnetic Tape Processing

The following sections contain examples of FCS statements that process
magnetic tape. Macro parameters not related to magnetic tape handling
are omitted from these statements.

5.2.7.1 Examples of OPEN$W Macro-II Statements to Create a New File All routines expect RO to contain the FOB address.
OPRWDO:
OPEN WITH REWIND
FDOP$R
BR

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

;SET REWIND AND ENABLE USE
;OF F.ACTL

OPNXTO:
OPEN FOR NEXT FILE POSITION
FDOP$R
BR

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

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

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

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

;DISABLE USE OF F.ACTL

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

OPOURO:
BIS
OPNOUT: FDBF$R
OPEN$W
RETURN

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

;ENABLE USE OF F.ACTL
;OVERRIDE BLOCK SIZE FOR TAPE

5.2.7.2 Examples of OPEN$R Macro-II Statements to Read
routines expect RO to contain the FOB address.

File - All

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

5-8

;DISABLE USE OF F.ACTL

FILE STRUCTURES

OPEN USING USER ACCESS CONTROL
i
OPDFLI: BIS
#FA.ENB,F.ACTL(RO)
OPNIN:
FDBF$R RO, ,#2048.
OPEN$R RO
RETURN

iENABLE USE OF F.ACTL
iOVERRIDE BLOCK SIZE FOR TAPE

5.2.7.3 Examples of CLOSE$ Macro-II Statements - All routines
RO to contain the FOB address.

expect

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

CLSRWD:
CLOSE REWINDING THE VOLUME
FDOP$R
BR

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

CLOSE WITH USER ACCESS CONTROL BITS
i
CLSDFL: BIS
#FA.ENB,F.ACTL(RO)
CLOSE: CLOSE$ RO
RETURN

iSET REWIND AND ENABLE USE OF
iF.ACTL

iENABLE USE OF F.ACTL

5.2.7.4 Combined Bxamples of OPBN$ and CLOSE$ Macro-II StatementsThe following examples call routines shown in previous examples in
Section 5.2.7.1. By combining various magnetic tape operations,
you
can process tape volumes in the following ways:
i SCRATCH TAPE OPERATIONS--SINGLE FILE VOLUME-i
SCROUT: MOV
#FDBOUT,RO
iSELECT FOB AND OPEN
CALL
OPRWDO
iOUTPUT FILE WITH REWIND
RETURN
SCRIN: MOV
#FDBIN,RO
iSELECT FOB AND OPEN FOR
iINPUT WITH REWIND
CALL
OPRWDI
RETURN
CLSCRO: MOV
#FDBOUT,RO
iCLOSE SCRATCH FILE
BR
CLSVOL
iREWINDING VOLUME
C['SCRI: MOV
FDBIN,RO
CLSRWD
Cr.SVOL: CALL
RETURN
i
i 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 FOB
iOPEN FILE

5-9

FILE STRUCTURES

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

#FDBIN,RO
OPRWDI

iSELECT FOB

MULTI-FILE OUTPUT OPERATIONS
OPNINT:
START NEW VOLUME DESTROYING ALL PAST FILES ON IT
MOV
CALL
RETURN

#FDBOUT,RO
OPRWDO

iSELECT OUTPUT FOB
iOPEN WITH REWIND

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 FOB

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

#FDBOUT,RO
OPROVK

iSELECT OUTPUT FOB

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

#FDBOUT,RO
OPROVO

iSELECT OUTPUT FOB

NOT LAST FILE IN FILE SET CLOSE ROUTINE
CLSFLO: MOV
BR
CLSFLI: MOV
CLSXX: CALL
RETURN
5

iSELECT OUTPUT FOB

#FDBOUT,RO
CLSXX
#FDBIN,RO
CLSCUR

iSELECT INPUT FOB

TO APPEND TO LAST FILE
OPEN$A

#FDBOUT

5-10

CHAPTER 6
COMMAND LINE PROCESSING

This chapter describes two object library routines that are available
from the system object library, [l,l]SYSLIB.OLB. These routines may
be linked with your task to provide the logical capabilities necessary
to process terminal command line input as follows:
•

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 you of the burden of
manually coding command line input operations.

•

Command String Interpreter
(CSI)
Normally, this routine
takes command lines from the GCML command line input buffer
and parses them into the appropriate dataset descriptors that
FCS requires for opening files.

The Task Builder links these routines with your program when the task
is being built.
GCML and CSI are often used together in system or
appliccltion programs as a standardized interface for obtaining and
interpreting dynamic command line input. Figure 6-1 shows the flow of
data during command line processing.
Although this chapter assumes the joint use of these routines to
process command line input, GCML and CSI may be used independently.
Using one without the other, however, requires that you manually code
the functions normally performed by the missing component.
Invoking GCML and CSI functions requires that certain initialization
be done when you write the source code. 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
approplriate macro calls that invoke GCML and CSI execution-time
functions must be included in the source code at appropriate logical
points to effect the dynamic processing of command lines.
GCML and CSI macro calls observe the same register conventions as FCS.
All r4~gisters except RO are preserved exactly as those in FCS macro
calls. RO contains the address of the GCML control block or the CSI
control block, as appropriate.
As with all FCS macro calls, the GCML and CSI macro calls must be
listed as an argument in an .MCALL directive (see Section 2.1) before
you insert them in your program.

6-1

COMMAND LINE PROCESSING
ASCII DATA

GCML

CSI

DEFAULT
FILENAME
BLOCK

DATASET
DESCRIPTOR

FCS
(.PARSE)

FILENAME
BLOCK

ZK-295-81

Figure 6-1

6.1

Data Flow During Command Line Processing

GET COMMAND LINE (GCML) ROUTINE

The Get Command Line
(GCML)
routine contains all the
logical
capabilities necessary to enter command lines dynamically during
program execution. GCML accepts input from a terminal or an indirect
command file that contains predefined command lines.
If your program
allocates sufficient buffer space in the file storage region
(see
Section 2.6), GCML accepts commands that are longer than one line of
terminal input.
The appearance of a hyphen as the last printing
character of a command line permits the continuation of commands from
one line to the next.
All GCML functions require you to create and initialize a GCML control
block.
See Section 6.1.1 for a description of this macro call. The
GCML run-time macro calls that your task may issue dynamically are
described in Section 6.1.3.

6-2

COMMAND LINE PROCESSING
6.1.1

GCMLB$ - Allocate and Initialize GCML Control Block

This section describes the GCMLB$ macro. This macro is a necessary
part of the code needed to dynamically obtain and execute command
lines. During the assembly of your program the GCMLB$ macro:
•

Reserves storage for and
within your program.

initializes

GCML

control

block

•

Creates and initializes an FOB for the indirect
in the first part of the GCML control block.

command

file

•

Creates and initializes a default filename
GCML control block.

within

the

•

Defines the symbolic offsets for the GCML control block and
initializes certain offsets to required values by invoking the
GCMLD$ macro.
These offsets are described in detail in
Section 6.1.2.

block

FCS uses the FOB to open an indirect command file. Your program may
open and read a command file, which can use a terminal or a
file-structured device such as a disk. GMCL and FCS initialize and
maintain this FOB.
FCS uses the default filename block for an indirect command file.
If
you do not specify an explicit filename string for an indirect command
file, the values CMI for the file name and .CMD for the file type are
assumed by default.
There is no default designation for the device
name.
The GCM1['B$ macro has the following forma t:
Format
label:

GCMLB$

maxd,prmpt,ubuf,lun,pdl,size

Parameters
label
A symbol that names the GCML control block and defines its
address.
This label permits the GCML control block to be
referenced directly by all the GCML run-time routines that
require access to this structure (see Section 6.1.3).
maxd
A numeric value that specifies the maximum nesting
depth
permitted for indirect command files.
This parameter determines
the number of nested indirect command files that GCML can access
in obtaining command line input.
An indirect command file, which often resides on disk, contains
W€'ll-def i ned, nonvary i ng command sequences, wh ich may be read
directly by GCML to control such highly repetitive operations as
Task Builder activities.
If you do not specify this parameter, the default nesting level
de!pth is 0, which effectively eliminates an indirect command file
as a source of command line input.

6-3

COMMAND LINE PROCESSING
prmpt
A 3-character ASCII prompting sequence that you specify.
The
GCML routine displays this default prompt string at your terminal
to solicit command line input.
Construct the ASCII prompting sequence as
string:

the

•

A carriage return «CR»

•

The three ASCII characters that you specify

•

A right angle bracket (»

following

6-byte

and a line-feed «LF»

The ASCII prompting sequence initializes
offset location G.DPRM (see Section 6.1.2).

GCML

control

block

If you do not specify this parameter, GCML uses the right angle
bracket
(», preceded by three blanks, as the default prompting
sequence.
ubuf
The address of a buffer that the GCML routine uses for temporary
storage of command line input.
If you do not specify this
parameter, a buffer is reserved in the GCML control block for
command line input. The size parameter determines the length of
the buffer.
If you specify neither this parameter nor the size
parameter, a 41-word buffer is reserved by default in the GCML
control block.
lun
A logical unit number. The GCML routine uses the device assigned
to this logical unit number as the command input device.
If you
do not specify this parameter, GMCL uses a logical unit number of
1 by default.
pdl
The address of an area reserved in your program as a push-down
list.
Indirect command file processing uses this area for
working storage. Normally, you do not specify the pdl parameter
unless you want to increase the storage for the push-down list.
Statements logically
push-down list:

equivalent

the

following

create

the

• EVEN

label:

• BLKB

G.LPDL

The label that you supply 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.
You can increase the
storage
in
the control block for the push-down list by
calculating the value according to the following algorithm:
1.

Add 1 to the maximum nesting level depth
maxd parameter described previously.

6-4

declared

with

the

COMMAND LINE PROCESSING
2.

Multiply the sum of step 1 by l6(decimal) to find the number
of bytes that must be reserved for the push-down list.

For example,
if you specify 4 as the maxd parameter,
determine the length of the push-down list as follows:
(4+1)*16.

= 80.

you

bytes

From the previous mathematical statement, note that 16 (decimal)
bytes of storage are required for each indirect command file (4),
plus another 16 (decimal) bytes as general overhead.
size
The size, in bytes, of the buffer reserved for command line
input.
The size must always include two extra bytes that are
used internally by GCML. The default size value is 82 (that is,
80 bytes for command line input and 2 bytes GCML overhead).
If you want GCML to accept continuation lines, the specified
value for the size parameter must be greater than 82. When the
size is greater than 82, the bit value GE.CON is set in the
status and mode control byte (offset G.MODE) of the GCML command
block. This value indicates that the continuation mechanism is
in effect.
Examples of how a GCMLB$ macro call may be used in a program follow:
GCLBLK: GCMLB$
GCLBLK: GCMLB$
GCLBLK: GCMLB$

6.1.2

4. ,GCM,BUFADR, 1.
"BUFADR
DEPTH,GCM,BUFADR,CMILUN,PDLIST,BUFSIZ

GCMLD$ - Define GCML Control Block Offsets and Bit Values

The GCMLD$ macro, which the GCMLB$ macro call invokes, locally defines
the GCML control block offsets and bit values within the current
module. A description of these offsets and their bit values follows:
Symbolic
Offset
Name
G.ERR

Description
Error Return Code Byte
This field initially contains o.
If any error
conditions that GCML recognizes occur during the
processing of a command line, an appropriate error
code is returned to offset location G.ERR in the
control block. Descriptions of these error bits
follow:
GE.IOR - I/O error occurred during the input of
a command line.
GE.OPR - GCML unable to
specified command file.

open

reopen

GE.BIF - Syntax error detected in the
the indirect command file.

name

the
of

GE.MDE - Attempt made to exceed the maximum
permissible nesting-level depth for an indirect
command file (see the description of the maxd
parameter in Section 6.1.1).
6-5

COMMAND LINE PROCESSING
Symbolic
Offset
Name

Description
GE.RBG - 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 - End-of-file
(EOF)
command file detected.

the

top-level

NOTE
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.
The error code is set along with command file
input.
When the first call is issued for input,
GCML attempts to retrieve an MCR command line.
Command
level 0 is set for the first line
obtained, whether it is an MCR command or a
terminal command.
If the name of an indirect
command file is then entered, the command input
level is increased to 1. Each indirect file name
entry thereafter increments the command input
level.
When the end-of-file (EOF) is encountered
on any given indirect file,
the command input
level is decremented by 1, restoring the count to
the previous level and reopening the associated
command file.
The next command line from that
file is then read.
If an MCR command has already been read at level
0, entering another MCR command when level 0 is
again reached causes the error code GE.EOF to be
returned to offset location F.ERR of the GCML
control block. Hence, only one MCR command line
can be read at level O.
If input thus fails at
MCR level 0, then GCML continues to prompt for
input until you type CTRL/Z to indicate terminal
end-of-file (EOF).
In summary, the first line of input is always read
at level O.
This initial input may be an MCR
command; if the MCR command fails or is null,
the
command input file (normally a terminal) is then
opened at level o. Multiple inputs at level 0 are
permissible only in the latter case, that is, from
the command input file.
G.MODE

Status and Mode Control Byte
This field is initialized at assembly time with
bit definitions to specify certain default actions
for GCML during the retrieval of a command line.

6-6

COMMAND LINE PROCESSING
Symbolic
Offset
Name

Description
At run time, you can reset default status and mode
control bits by issuing a Bit Clear Byte (BICB)
instruction that takes the symbolic name of the
bit to be cleared as the source operand.
In the
case of the GE.LC value (see the following text),
the BISB instructio~ can override the default
action.
Descriptions of the symbolic names
defined in the status and mode
follow:

of the
control

bits
byte

GE.IND - (Default) A command line that begins
with a leading at sign
(@)
is an explicit
indirect command file specification.
If you
reset the GE.IND bit to 0, a command line
beginning with an at sign (@)
is returned to
the calling program.
GE.CLO - (Default) The command file currently
being read is closed after each GCML$ macro
call is issued. If you reset the GE.CLO bit to
0, GCML keeps the current command file open
between calls for input.
In this case,
the
File Storage Region (FSR) described in Section
2.6.1
must
include
one
additional
512(decimal)-byte
buffer
for command line
input. This requirement adds to the total FSR
block buffer space normally reserved for the
maximum number of files that may be open
simultaneously for record I/O processing.
Clearing the GE.CLO bit in the status and mode
control byte renders 512 (decimal) bytes of FSR
block buffer space unavailable
for
other
purposes, because the command file remains open
between calls for command line input.
GE.COM - (Default) A command line that begins
with a leading semicolon
(;)
is a comment.
Such lines are not returned to the calling
program.
If you reset this bit to 0, a command
line beginning with a leading semicolon (;)
is
returned to the calling program.
GE.CON If the value of the size parameter of
the GCMLB$ macro is greater than 82,
the
continuation mechanism is in effect by default.
You must not attempt to set this bit in the
mode byte without providing a buffer larger
than 82 bytes.
GE.LC If this bit is set to 1 in the GCML
control block at run time, lowercase characters
in the command line are passed unaltered to
your
program.
If this bit is not set,
lowercase characters are changed to upppercase
before being passed to your program.

6-7

COMMAND LINE PROCESSING
Symbolic
Offset
Name

Description

G.PSDS

Prompt String Descriptor
This 2-word field is initialized at assembly time
to 0 by issuing the GCMLB$ macro call (see Section
6.1.1).
When you issue the GCML$ macro call to request
command line input
(see Section 6.1.3.1), the
address and the length of a prompting sequence are
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
to
solicit
command
line
input.
(See the
description of G.DPRM in the following text.)
If you want to define an alternate prompt string
elsewhere in the program, you may do so through
the .ASCII directive. The address and length of
this alternate prompt string may then be specified
as the adpr and lnpr parameters in subsequent
GCML$ macro calls.
(See the description of these
parameters and how they affect alternate prompt
strings in the following text.) 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.
GCML then types out the alternate prompt string to
solicit command line input, thereby overriding the
default
prompt
string previously established
through the GCMLB$ macro call.
If you do not specify the adpr and lnpr parameters
in a subsequent GCML$ macro call, offset location
G.PSDS in the control block is 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
GCML
initializes
this
2-word
field
after
retrieving a command line. The address of this
command line 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
specifications 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

6-8

COMMAND LINE PROCESSING
Symbolic
Offset
Name

Description
for pointers, flags, counters, and so forth, along
with input from an indirect command file.
In
normal usage, you need not be concerned with this
symbol.
The space between the FDB and the default prompt
string
(see G. DPRM in ,the following text) is the
impure area of the GCML control block. The value
of the symbol S.FDB defines the size of the FDB.
Thus, the size of the impure area is equal to
G.DPRM minus S.FDB (G.DPRM-S.FDB).

G.J)PRM

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
Inpr parameters in the GCML$ macro call
(see
Section 6.1.3.1), GMCL types out this default
prompt string to solicit terminal input.

You can reference the GCML control block offsets and bit values in
another module by establishing the appropriate symbolic definitions
within that module through one of the following statements:
GCI'1LD$

iDEFAULT LOCAL DEFINITION

GCI'1LD$

DEF$L

iLOCAL DEFINITION

GCiMLD$

DEF$G

iGLOBAL DEFINITION

6.1.3

GCML Routine Run-Time Macros

GCML provides the following three
specific functions:

run-time

macro

GCML$

- Retrieves a command line

RCML$

- Resets the indirect command file
(unnested) level

CCML$

- Closes the current command file

calls

scan

the

perform

first

These routines are described in the following sections.

6.1.3.1 GCML$
interface for
command file.
the program to

- Get Command Line Macro - GCML$ serves as your program
retrieving command lines from a terminal or an indirect
You can issue this macro call at any logical point in
solicit command line input.

This macro call has the following format:
Format
GCML$

gclblk,adpr,lnpr

6-9

COMMAND LINE PROCESSING
Parameters
gclblk
The address of the GCML control block. This symbol must be the
same as that specified at assembly time in the label field of the
GCMLB$ macro call (see Section 6.1.1). If you do not specify
this parameter, RO is assumed to contain the address of the GCML
control block.
adpr
The address of your program location containing an alternate
prompt string.
When this optional parameter and the lnpr
parameter following are present in the GCML$ macro call, the
alternate prompt string appears on your terminal to solicit
command line input.
The normal default prompt string, as
contained in offset location G.DPRM of the GCML control block
(see Section 6.1.2), is thereby overridden.
lnpr
The length (in bytes) of the optional, alternate prompt string.
If you do not specify this parameter, offset location G.PSDS in
the GCML control block (see Section 6.1.2) is cleared.
If you specify this parameter, but do not specify the adpr
parameter described previously, 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 you specify this parameter, as well
as the adpr parameter, the default prompt string is used.
If you do not specify the adpr and lnpr parameters in a subsequent
GCML$ macro call, offset location G.PSDS in the GCML control block is
reset to O. Consequently, GCML reverts to using the default prompt
string contained in offset location G.DPRM (see Section 6.1.2).
When you issue the GCML$ macro call, the following occurs:
1.

RO is loaded with the address of the GCML control block.
If
you do not specify the gclblk parameter, RO is assumed to
contain the address of the GCML control block.
If it does
not contain that address, you must first manually initialize
RO with the address of the control block before you issue the
GCML$ macro call.

The address and the length of the alternate prompt string, if
specified, are stored in control block offset locations
G.PSDS+2 and G.PSDS,
respectively.
These
two
words
constitute the alternate prompt string descriptor.

Code is generated that calls GCML to transfer a command line
to the command line input buffer.
If the last character of
an input line is a hyphen, and if the value GE.CON is present
in the status and mode control byte, GCML transfers commands
that are longer than one line.
The continuation lines
obtained are concatenated in the input buffer with the
continuation hyphen(s) removed.

6-10

COMMAND LINE PROCESSING
When your task first issues the GCML$ macro call, GCML$ tries to
retrievle an MCR command line.
If this attempt fails, or if the MCR
command line is null, GCML uses the FOB within the GCML control block
to open a file for command line input.
If the command input device is
a terminal, a prompt string appears on your terminal to solicit input.
Any
appropriate
command
input may then be entered.
If the
continuation mechanism is in effect, the prompt string reappears to
solicit subsequent portions of the continued command line.
If appropriate, you may enter an at sign (@) as the first character in
the command line,
followed by the name of an indirect command file.
This file name identifies an explicit indirect command file from which
input is to be read.
GCML then opens this file and retrieves the
first command line. On successive GCML calls, this file is read until
one of the following occurs:
•

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 reduced by 1, and the previous
command file is reopened.
If the command input level count is
already 0 when EOF is detected, the error code GE.EOF is
returned to offset location G.ERR of the GCML control block
(see Section 6.1.2).

•

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

•

An RCML$ macro call is issued in the program (see Section
6.1.3.2).
In this case, the current indirect command file is
closed, and the command input count reverts to level Oi
that
is, the top-level command file is again used for input.

You may also enter a semicolon (i)
as the first character in the
command line.
If GE.COM is set, such a line is treated as a comment
and is not returned to the calling program.
If GE.COM is clear,
the
line is returned to the calling program.
Whether a command line is entered manually or retrieved from an
indirect command file, the address and the length of the command line
are returned to GCML control block offset locations G.CMLD+2 and
G.CMLD, respectively.
Together,
these two words constitute the
command line descriptors. These descriptors may be specified as the
buff and len parameters in the CSI$l macro (see Section 6.2.3.1).
Successful retrieval of a command line causes the Carry bit in the
Processor Status Word to be cleared. Any error condition that occurs
during the retrieval of a command line, however, causes the Carry 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.
Examples of how you may use the GCML$ macro in a program follow:
GGML$

#GCLBLK

GGML$
GC.ML$

#GCLBLK,#ADPR,#LNPR

6-11

COMMAND LINE PROCESSING
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 employ the
default prompt string contained in offset location G.DPRM of the
control block to solicit command line input.
The last example
specifies the address and the length of an alternate prompt string
that you have defined within the program. GCML uses this alternate
prompt string to prompt for terminal input, rather than using the
default prompt string contained in the GCML control block.

6.1.3.2 RCML$ - Reset Indirect Command File Scan Macro - If you must
close the current indirect command file and return to the top-level
file, that is, to the top-level (unnested) file,
you may do so by
issuing the RCML$ macro.
You specify the RCML$ macro in the following format:
Format
RCML$

gclblk

Parameter
gclblk
The address of the GCML control block.
If you do not specify
this parameter, RO is assumed to contain the address of the GCML
control block.
When you issue this macro, the current indirect command file is
closed, returning control to the top-level
(unnested)
file.
A
subsequent GCML$ macro then retrieves the next command line from the
O-level command file.
Note, however, that a second MCR command at
level 0 cannot be read (see GE.EOF error code in offset location G.ERR
of GCML control block, Section 6.1.2).
Examples of how you may use the RCML$ macro in a program 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 Macro - You may want to
close the current command file between calls for input to free FSR
block buffer space for some other use.
FCS normally closes the
command file after the retrieval of a command line, provided that the
GE.CLO bit in the status and mode control byte remains appropriately
initialized
(see Section 6.1.2).
This bit is set to 1 at assembly
time. If you reset this bit to 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, because keeping the file open between
calls for input reduces total file access time. However, should you
want to close such a file to free FSR block buffer space, you may do
so by issuing the CCML$ macro call.

6-12

COMMAND LINE PROCESSING
The CCML$ macro call has the following format:
Format
CCML$

gclblk

Parameter
gclblk
The address of the GCML control block. If you do not specify
this parameter, RO is assumed to contain the address of the GCML
control block.
Issuing this statement closes the current command file, effectively
releasing 512 (decimal) bytes of FSR block buffer space for some other
use between calls for input.
If the command file is already closed
when your task issues the CCML$ macro call, control is returned to
your task. 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 how the CCML$ macro may be used in a program follow:
CCML$

#GCLBLK

CCML$

As in the RCML$ macro call described previously, this macro call takes
a single parameter, specifically, the address of the GCML control
block.

6.1.4

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 ordinarily you need
not manipulate this FOB (because it is under GCML and FCS control),
you can perform the following operations on this FOB:
1.

In an unrecoverable error situation, you can issue a CLOSE$
macro call
(see Section 3.8) with the address of this FOB
before issuing the system EXIT$ macro call.

You can test the FO.TTY bit in the device characteristics
byte (offset location F.RCTL) of the FOB to determine whether
the command line just obtained was retrieved from a terminal.

In the event that error code GE.IOR or GE.OPR is returned to
control block offset location G.ERR (indicating that an I/O
error has occurred during the retrieval of a command line),
you can test offset location F.ERR of the associated FOB for
a more complete error analysis. This FOB cell 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)
option
should be issued to assign the appropriate physical device unit to the
desired logical unit number. For example, to assign the logical unit
number (lun parameter) in the GCMLB$ macro call (see Section 6.1.1) to
a terminal, the following Task Builder option should be issued:
ASG

= TI:l

6-13

COMMAND LINE PROCESSING
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 option is described in further detail
and Micro/RSX Task Builder Reference Manual.

the

RSX-11M/M-PLUS

As covezed in the Section 2.6.1 discussion on FSRSZ$, at any given
time there must be an FSR block buffer available for each file
currently open for record I/O operations.
You must consider the
buffer requirements of the command file when issuing the FSRSZ$ macro
(FSRSZ$ must be issued with a nonzero first parameter) •

6.2

COMMAND STRING INTERPRETER (CSI) ROUTINE

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

dev:[g,m]outputfilespec/switch
More than one file specification
separating them with commas •

•

can

specified

dev: [g,m]outputfilespec/switch, ••• = dev: [g,m]
inputfilespec/switch, •••

A file specification may be either of the following:
filename.type;version
or
"ANSI name string";version
CSI maintains a dataset descriptor within the csr control block
(see
Section 6.2.1), which FCS may use in opening files. The run-time
routines that analyze and parse command lines for your calling program
are described in Section 6.2.3.
Using CSI requires that the CSl control block offsets and bit values
be defined and that a control block be allocated within the program.
The macro described in the following section accomplishes these
requisite actions.

6.2.1

CSIS - Define CSI Control Block Offsets and Bit Values Macro

Following is the
assembly time:

only

initialization

csr$
.EVEN
CSIBLK: .BLKB

c.srZE

coding

required

for

csr

;DEFlNES CSI CONTROL BLOCK OFFSETS
;AND BIT VALUES LOCALLY
;WORD ALIGNS csr CONTROL BLOCK
;NAMES CSI CONTROL BLOCK AND
;ALLOCATES REQUIRED STORAGE

6-14

COMMAND LINE PROCESSING
The CSI$ macro does not generate any executable code. The CSI control
block resulting from the .BLKB directive allows communication between
CSI and the calling program. The symbol C.SIZE specifies the length
of the control block. C.SIZE is defined during the expansion of the
CSI$ macro. Expanding this macro also causes a local definition of
the symbolic offsets and bit values within the CSI control block.
You can cause the control block offsets to be defined globally within
the current module. This is done by specifying DEF$G as an argument
in the CSI$ initialization macro call, as follows:
CSI$

6.2.2

DEF$G

ICSI$ Macro Control Block Offset and Bit Value Definitions

The CSI$ macro locally defines the following symbolic offsets and
values within the CSI control block:
Symbolic
Offset
Name
C.TYPR

bit

Description
Command String Request Type
This byte field indicates which type of file
specification is being requested. Depending on
whether an input or output file specification is
being requested (see the io parameter in the CSI$2
macro call described in Section 6.2.3.2), the
corresponding bit' in this byte is set. The bit
definitions for this byte are as follows:

C.STAT

CS.INP - Indicates
that
an
input
specification is being requested.

file

CS.OUT - Indicates
that
an
output
specification is being requested.

file

Command String Request Status
This byte field reflects the status of the current
command line request. The bits in this field are
initialized according to
the
following
bit
definitions:
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 specifications. Once
CS.EQU is set, CSII and
CSI2
processing
preserve the value of CS.EQU.
CS.NMF - Indicates that
the
current
file
specification
contains
a filename string.
Accordingly, control block offset locations
C.FILD+2 and C.FILD (see the entry for C.FILD)
are initialized with the address and the length

6-15

COMMAND LINE PROCESSING
Symbolic
Offset
Name

Description
(in bytes), respectively, of the command line
segment that contains the filename string.
If no
filename string is pres~nt, this bit is not set,
and the filename string descriptors in the control
block are cleared.
CS.DIF - Indicates
that
the
current
file
specification contains a directory string. Thus,
control block offset locations C.DIRD+2 and C.DIRD
(see the description following for C.DIRD) are
initialized with the address and the length
(in
bytes), respectively, of the command line segment
that contains the directory string.
If
no
directory string is present, this bit is not set.
In this case, any residual nonzero values in the
directory string descriptor cells that pertain to
a previous command string request of similar type
are used by default
(see the description of
C.TYPR). Thus, FCS uses the last directory string
encountered in a file specification.
CS.DVF - Indicates
that
the
current
file
specification
contains a device name string.
Similarly, control block offset locations C.DEVD+2
and C.DEVD
(see the description of C.DEVD) 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.
Like
CS.DIF
(see
the previous
description of CS.DIF), any residual
nonzero
values in the device name descriptor cells that
pertain to a previous command ·string request of
similar type are used by default. Thus, the last
device name string
encountered
in
a
file
specification is used.
CS.WLD - Indicates
that
the
current
file
specification contains an asterisk (*), signaling
the presence of a wildcard specification.
CS.MOR - Indicates
that
the
current
file
specification is terminated by a comma (,), which
indicates that more file specifications are to
follow.
If this bit is not set, it signifies that
the end of the input or output file specification
has been reached.

C.CMLD

Command Line Descriptor
This 2-word field is initialized with the length
(in bytes)
and the address, respectively, of the
compressed command line.
In other words,
the
values returned to these cells are the CSI output
after it scans a file specification and removes
all nonsignificant characters from the string
(that is, nulls, unquoted blanks and tabs, and
RUBOUTs) .

6-16

COMMAND LINE PROCESSING
Symbolic
Offset
Name

Description
CSI uses the values contained in these cells as
the descriptors of the compressed command line to
be parsed
(see CSI$2 macro call in
Section
6.2.3.2).

C.DSDS

Dataset Descriptor Pointer
This pointer defines the address of the 6-word
dataset descriptor in the CSI control block. This
structure is functionally
identical
to
the
manually created dataset descriptor detailed in
Section 2.4.1.
You can use this symbol to initialize offset
location F.OSPT in the FOB associated with the
file to be processed.
Thus, FCS is able to
retrieve the ASCII information from this structure
that it needs to open files.
Assembly-time initialization of F.OSPT in the
associated FOB may be accomplished as follows:
FOOP$A

1,CSIBLK+C.OSOS

where CSIBLK is the address of the CSI control
block, and C.OSOS represents the beginning address
of the descriptor strings in the CSI control block
(see the following entries for offset names)
ASCII
filename
identifying
the
requisite
information.
Run-time
initialization
of
F.OSPT
in
the
associated FOB may also be accomplished by using
the dspt parameter of the FOOP$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.OEVO+2)
and the length in bytes
(C.OEVD)
of the most
recent device name string (of those with the same
request type) encountered in a file specification.
Note that the colon that follows the device name
is not included in the device name string.

C.O:[RO

Directory String Descriptor
This 2-word field contains the address
(C.DIRD+2)
and the length in bytes
(C.DIRO) of the most
recent directory string (of those with the same
request type) encountered in a file specification.

C.FILD

Filename String Descriptor
This 2-word field contains the address
(C.FILO+2)
and the length in bytes (C.FILO) of the filename
string in the current file specification.

6-17

COMMAND LINE PROCESSING
Symbolic
Offset
Name

Description
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), 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
switches
present in the cu~rent file specification after
each invocation of the CSI$2 macro call.
The
switch mask for each of the defined switches
encountered in' a file
specification
between
delimiting commas is inserted into this location
by a logical OR operation.
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 specification for which a
defined mask exists, the corresponding bits in
C.MKWI are set.. By testing C.MKWl, you can
determine the particular combination of defined
switches
present
in
the
current
file
specification.

C.MKW2

CSI Mask Word 2
This word provides
switch polarity.

you

with

indication

When a switch is present in a file specification
and you do not negate that switch, the defined
mask for that switch is inserted into C.MKW2 by a
logical
OR operation in the same manner as
described previously for C.MKWI. Conversely, when
a switch is present in a file specifier and you do
negate that switch, the corresponding bits in
C.MKW2 are cleared.
Thus, you can check the
polarity of each switch that C.MKWI indicates is
present by examining the corresponding bits in
C.MKW2.
C.SIZE

Control Block Size Indicator
This symbol, which is defined during the expansion
of the CSI$ macro, represents the size in bytes of
the CSI control block.

C.EXPS

User Task Expansion Buffer Size
This symbol is the constant for your task's
expansion
buffer
size
(for
logical
name
expansion).
It is currently set to 4S(decimal).
See the description of the CSI$4 routine in
Section 6.2.3.3 for more information.
6-lS

COMMAND LINE PROCESSING
6.2.3

CSI Run-Time Macros

Three run-time macro calls in CSI invoke
following functions:

routines

that

perform

the

CSI$l

- Initializes the CSI cont~ol 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
also initializes 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 specification 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.
In
addition, certain cells in the CSI control block are
initialized with the appropriate string descriptors for
subsequent use by FCS in opening the specified file.

CSI$4

- Expands a file specification and returns a dataset
descriptor and flag word that refer to this expanded
file specification. The file specification string is
not expanded into the original buffer but into a
separate buffer in the file storage region. The use of
CSI$4
is
recommended
when
parsing logical file
specification strings.

6.2.3.1 CSI$l - Command Syntax Analyzer - The CSI$l macro invokes 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 correct syntax. In addition, it compresses
the file specifications in the command line by
removing
all
nonsignificant characters
(that is, null, RUBOUT, and unquoted tabs
and blanks). Finally, the command syntax analyzer initializes offset
locations C.CMLD+2 and C.CMLD in the CSI control block (see Section
6.2.2) with the address and the length (in bytes), respectively, of
the validated and compressed command line. Each file specification in
the cOlmrnand line is then parsed into its component device name,
directory, and filename strings during each successive time the CSI$2
macro call is issued (see Section 6.2.3.2).
The CSI$l macro call has the following format:
Format
CSI$l

csiblk,buff,len

Parameters
csiblk
The address of the CSI control block. If you do not specify this
parameter, RO is assumed to contain the address of the CSI
control block.
buff
The address of a command line input buffer.
This parameter
initializes CSI control block offset location C.CMLD+2, enabling
CSI to retrieve the current command line from a command line
input buffer.

6-19

COMMAND LINE PROCESSING
If you do not specify this parameter, you must
manually
initialize CSI control block offset location C.CMLD+2 with the
address of a command line input buffer before issuing the CSI$l
macro call.
The following statement shows one way to manually
initialize this location:
MOV GCLBLK+G.CMLD+2,CSIBLK+C.CMLD+2
len
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 described previously, if you do not
specify this parameter, you must manually initialize CSI control
block offset location C.CMLD with the length of the command line
input buffer before issuing the CSI$1 macro call. The following
statement shows one way to manually initialize this location:
MOV GCLBLK+G.CMLD,CSIBLK+C.CMLD
The combination of the buff and len parameters described previously
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 syntactical error is detected during the validation of the
command line,
the Carry 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 how the CSI$l macro call may be used in a program follow:
CSI$l

#CSIBLK,#BUFF,#LEN

CSI$1

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

CSI$l

#CSIBLK

The first example shows symbols that represent the address and the
length of a command line to be analyzed (not necessarily the line
contained in the GCML command line input buffer) •
The second example assumes that RO has been preset with the address of
the CSI control block; the next two parameters are direct references
to the command line descriptor words in the GCML control block.
The third example assumes that the required descriptor values are
already present in offset locations C.CMLD+2 and C.CMLD of the control
block (CSIBLK) as the result of prior action.

6.2.3.2 CSI$2 - Command Semantic Parser Macro - The CSI$2
macro
invokes 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
routine then parses the referenced line into its component device
name, directory, and filename strings.
The equal sign (=) in the
command line indicates that the string that follows is an input file
specification.
In addition, 2-word descriptors for these strings are

6-20

COMMAND LINE PROCESSING
stored in a 6-word dataset descriptor in the CSl control block,
beginning at offset location C.DSDS (see Section 6.2.2). This field
is functionally equivalent to the dataset descriptor created manually
in your program (see Section 2.4.1).
The parser also decodes any switches and associated switch values
present in a file specification, provided that the address of the
appropriate switch descriptor table has been specified in the CSl$2
macro call (see the following text). The CSI switch definition macro
calls are described in detail in Section 6.2.4.
The CSl$2 macro call has the following format:
Format
CSl$2

csiblk,io,swtab

Paramet,ers
csiblk
The address of the CSI control block. If you do not specify this
parameter, RO is assumed to contain the address of the CSl
control block.
io
A symbol that identifies the type of file specification to be
parsed.
You may specify either of the following two symbolic
arguments in this parameter field:
INPUT - The next input file specification in the command
is to be parsed.
OUTPUT - The next output file
line is to be parsed.

specification

the

line

command

You must initialize offset location C.TYPR in the CSl control
block
(see Section 6.2.2), either manually or through the CSl$2
macro call, with the type of file specification being requested.
If arguments other than the symbolic arguments defined previously
are specified in the CSI$2 macro call, an .ERROR directive is
generated during assembly that causes the error message INCORRECT
REQUEST TO .CSI2 to be printed in the assembly listing.
This
diagnostic message alerts you to the presence of an invalid io
parameter in the CSI$2 macro call.
swtab
The address of the associated switch descriptor table.
You
specify this optional parameter only if you suspect that the file
specification contains a switch to be decoded.
For you to
specify this parameter, the program must already contain a switch
descriptor table, which you created with the CSI$SW macro
(see
Section 6.2.4.1).
In addition, if the switch to be decoded has
any associated switch values, the program must already contain an
associated switch value descriptor table, which you create with
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 you do not specify this
parameter, FCS uses any residual nonzero value in this cell by
default as the switch descriptor table address.

6-21

COMMAND LINE PROCESSING
You can also initialize offset location C.SWAD manually prior to
issuing
the CSI$2 macro call, as shown in the following
statement:
MOV #SWTAB,CSIBLK+C.SWAD
where SWTAB is the symbolic address of the associated switch
descriptor table.
(The switch table must be aligned on an even
address.)
If an error condition occurs during the parsing of the
file
specification,
the Carry bit in the Processor Status Word is set, and
control is returned to the calling program.
The possible error
conditions that may occur during command line parsing include the
following:
•

The request type is invalid; that is, offset location C.TYPR
in the CSI control block (see Section 6.2.2) is incorrectly
initialized.

•

The file specification contains a switch, but the address of
the switch descriptor table is not specified in the CSI$2
macro call, or the switch descriptor table does not contain a
corresponding entry for the switch.

•

The file specification contains an invalid switch value.

•

The number of values accompanying a given switch in the file
specification are greater than the number of corresponding
entries in the switch value descriptor table for decoding
those values.

•

The file specification contains a negative switch, but the
corresponding entry in the switch descriptor table prevents
you from negating the switch (see the nflag parameter of the
CSI$SW macro call in Section 6.2.3.3).

Examples of how the CSI$2 macro may be used in a program follow:
CSI$2

#CSIBLK,INPUT,#SWTBL

CSI$2

RO,OUTPUT,#SWTBL

CSI$2

#CSIBLK,INPUT

The first example shows a request to
parse
an
input
file
specification, 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 specification, which also may
include a switch. The last example is a request to parse an input
file specification and to disallow any accompanying switches.

6.2.3.3 CSI$4 - Command Semantic Parser Macro - Use CSI$4 in the same
way that you use CSI$2. However, CSI$4 is the preferred method of
parsing logical names. Using CSI$4 causes the same function as CSI$2
except that CSI$4 allows all tasks to use logical names correctly,
except under the following two conditions:
1.

The task saves the dataset descriptor for one call to CSI$2
and then calls CSI$2 again, expecting to be able to use the
first dataset descriptor at a later time.

The task assumes that the dataset descriptor points into
original string.
6-22

the

COMMAND LINE PROCESSING
CSI$4 cannot be called repeatedly using the
previous
Dataset
Descriptor.
The reason is that whenever a parse is done, whether by
the .PARSE routine (see Section 4.7.1), or the CSI$4 macro, or the
.EXPLG routine, the expanded string is always put into the FSR area of
the task.
If your task repeatedly calls CSI$4, each call overwrites
the previous call.
CSI$4 uses this common buffer for input file
specifications, but uses a separate expansion buffer for output file
specifications.
This permits CSI$4 to process input and output file
specifications simultaneously.
To allow multiple calls to CSI$4, another parameter is
CSI macro, so that:
CSI$2

added

the

tCSIBLK,INPUT,fCSISWT

is chanqed to:
CSI$4

tCSIBLK,INPUT,fCSISWT,fDSCBLK

The DSCBLK parameter is a pointer to a 2-word descriptor block that
specifies the expanded command line buffer. The descriptor block
contains the following two words:
WORD 0:

Contains the size of the expanded command line buffer

WORD 1:

Contains the address of the expanded command line buffer

The desc:::riptor block and the command line expansion buffer are
allocated in your task's address space. The size of the expansion
buffer should be as large as any possible single file specification.
Therefore, C.EXPS, currently set to 48 (decimal) , should be used.
If
the buf:fer is too small, an error is returned.
If either value in the
descriptor block is 0, the expansion area in the FSR is used.
Logical name expansion requires a relatively large amount of system
overhead.
These steps should be followed to reduce the overhead
demand:
1.

Do not change CSI$2 macros to CSI$4 macros when you want your
task to only scan the line for switches or files without
opening any files found.
In this case, changing CSI$2 to
CSI$4 only adds to the extra translation required.

Include the following line before any call to .PARSE:
BISB

tFL.AEX,F.FLG(RO)

;RO is the FOB address

This code line informs .PARSE that the string has already
been expanded and .PARSE need not repeat the expansion.

6.2.4

CSI Switch Definition Macros

The following macro calls create the requisite switch descriptor
tables in your program for processing switches that appear in a file
specification:
CSI$SW - Creates an entry in the switch descriptor table for a
particular switch that you expect to encounter in a file
specification.
CSI$SV - Creates a matching entry in the switch value descriptor
table for the switch defined through the CSI$SW macro.

6-23

COMMAND LINE PROCESSING
CSI$ND - Terminates a switch descriptor table or a switch value
descriptor table created through the CSI$SW or the
CSI$SV macro call, respectively.
These macro calls are described in the following sections.

6.2.4.1 CSI$SW - Create Switch Descriptor Table Entry Macro - You
must define a matching entry in the switch descriptor table for each
switch that you expect youz task to encounter in a file specification.
If no switch descriptor table is specified or no corresponding entry
exists, the presence of a switch in the command line causes an error.
When your task issues a CSI$2 macro (see Section 6.2.3.2) and the
address of a switch descriptor table is specified, the following
processing occurs:
1.

For each switch encountered in a file specification, CSI
searches the switch descriptor table for a matching entry.
If either the switch descriptor table address is
not
specified, or a matching switch entry is not found in the
table, that switch is considered invalid. As a result,
the
Carry bit in the Processor Status Word is set, any remaining
switches in the file specification 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 you do
not negate the switch, 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 you negate the switch but
negation is not allowed, the switch is considered invalid.
In this case, the error sequence described in step 1 would
occur.
However, if you negate the switch, and negation is
allowed, the corresponding bits in C.MKW2 are cleared.
The negation flag for a switch is established through
nflag parameter of the CSI$SW macro
(described in
following text}.

the
the

If the optional mask word address is not present in the
corresponding switch descziptor table entry, that is, if you
did not specify the mkw parameter in the associated CSI$SW
macro, switch processing continues with step 7.
If, however,
you did specify the optional mask word address,
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,
you
negate
the
switch,
the
corresponding bits in the optional mask word are cleared.
You specify the clear/set flag as the csflg parameter in
CSI$SW macro.

the

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 you negate the switch, the
corresponding bits in the optional mask word are set.

6-24

COMMAND LINE PROCESSING
7.

If a switch value accompanies a
switch
in
a
file
specification,
FCS
uses
the
associated switch value
descriptor table created through the CSI$SV macro call
(see
Section 6.2.4.2) 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
specification.
If the switch value descriptor table is
incomplete, or an invalid switch value is encountered, or the
address of the switch value descriptor table is not present
in the associated switch descriptor table, the switch is
invalid, and the error sequence described in step 1 would
occur.
You specify the address of the switch value "descriptor
as the vtab parameter in the CSI$SW macro call.

table

The CSI$SW macro call has the following format:
Format
label:

CSI$SW

sw,mk,mkw,csf1g,nf1g,vtab,compf1g

Parameters
label
An optional symbol that names the resulting switch descriptor
table entry and defines its address. To establish the address of
a switch descriptor table, the first CSI$SW macro call issued in
the program must include a label. This label allows the table to
be referenced by other instructions in the program.
sw
The switch name to be stored as an entry in the switch descriptor
table.
This
name may comprise any number of alphabetic
characters. CSI compares the name entered on the command line
with this switch name as entered in the switch descriptor table.
This is a required parameter; if you omit it, the Assembler
generates an .ERROR directive during assembly that Causes the
error message MISSING SWITCH NAME to be printed in the assembly
listing.
mk
A mask that you define for the switch specified through the sw
parameter.
To enable CSI to indicate the presence of a given
switch in a file specification, you must define a mask value for
the switch, as follows:
ASMSK
NUMSK

VWMSK
XYMSK

40000
100000

where the octal value that you assign to each symbol defines a
unique bit configuration. This configuration is to be set in CSI
mask word 1 (C.MKW1) of the control block when a defined switch
is encountered in a file specification.

6-25

COMMAND LINE PROCESSING
When you specify the appropriate symbol as the mk parameter in
the CSI$SW macro call, the corresponding mask value is stored in
the resulting switch descriptor table entry. Thus, a mechanism
is established through which you can determine the particular
combination of switches present in a file specification.
For
every matching entry found in the switch descriptor table, the
corresponding bits are set in C.MKWI.
mkw
The address in your 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 your program. You set the
SET and CLEAR functions using the csflg parameter.
Such an optional word may be reserved
logically equivalent to the following:
MASKX:

.WORD

through

statement

csflg
A symbolic argument that specifies the clear/set flag for a given
switch.
This parameter is optional; if you do not specify it,
SET is assumed. You may specify either one of two symbolic
arguments for this parameter, as follows:
CLEAR - Indicates that the bits in the optional mask word
corresponding to the switch mask are to be cleared, provided
that you did not negate the switch.
(If you negate the
switch, the bits are set.)
SET - Indicates, conversely, that the bits in the optional
mask word in your task corresponding to the switch mask are to
be set, provided that you did not negate the switch.
(If you
negate the switch, the bits are cleared.)
If you specify other than SET or CLEAR, the Assembler generates
an .ERROR directive that causes the error message INVALID
SET/CLEAR SPEC to be printed in the assembly listing.
nflg
Specifies an optional negation flag for the
specify this parameter,
it indicates that
negated, for example, /-LI or /NOLI.

switch.
If you
the switch can be

If you specify this parameter as other than NEG, the Assembler
generates an .ERROR directive that causes the error message
INVALID NEGATE SPEC to be printed in the assembly listing.
If
you do not specify this parameter, the assumption is that switch
negation is not allowed.
vtab
The address of the switch value descriptor table associated with
this switch.
If you specify this optional parameter, it allows
CSI to decode any switch values accompanying the switch, provided
that you have defined an associated switch descriptor table entry
for that switch. The CSI$SV macro defines the switch value
descriptor table.
(If you specify the vtab parameter in the
CSI$SV macro, you need not specify it in the CSI$SW macro call.)

6-26

COMMAND LINE PROCESSING
compflg
Defines the method CSI uses to compare the switch name entered on
the command line with the value entered in the switch descriptor
table by the sw parameter.
Either LONG or EXACT may be
specified.
The default value is entered if you do not specify a
value.
De£'ault - If you do not code the parameter, only the first two
characters of the switch name (specified by sw) are entered into
the switch descriptor table and only these two characters are
compared when the command line is parsed. 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
chaLracters in either the command line or the table are treated as
an error.
The switch table must be aligned on an even address.
The format of
the switch descriptor table entry created by the CSI$SW macro is shown
in Figure 6-2.
The switch name characters precede the control information in the
table. The sign bit of each word indicates whether the following word
contains more switch name characters. A sign bit set to 1 indicates
that the next word contains more switch name characters, whereas a
sign bit set to 0 indicates that this is the last word containing
switch name characters.
If the number of characters in the switch name is odd, the
byte of the last word contains zeros, and CSI ignores it.

high-order

The sign bit of the first byte of the last word of the switch name is
the EXACT match bit. If this bit is set to 1, additional characters
in the switch name on the command line are treated as an error by CSI;
if this bit is set to 0, additional characters are ignored.
The switch name characters are followed by entry control information
consisting of the CSI mask word, the address of the area task of a
mask word corresponding to the CSI mask word, and the address of the
switch value table.
A bit setting of 1 in the low-order bit of the address of your mask
word indicates the CLEAR function; a bit setting of 0 indicates the
SET function.
The last word of the switch descriptor table entry contains the
address of the switch value table.
A bit setting of 1 in the
low-order bit of this word indicates that the switch may be negated.

6-27

COMMAND LINE PROCESSING

15
char2

char1

char4

char3

lastchar

EX nextlast

Mask Word for this Switch
Address of Optional User Mask Word
Address of Switch Descriptor Table
ZK-296-81

Figure 6-2

Format of Switch Descriptor Table Entry

The following example shows a 2-entry switch descriptor table
through successive CSI$SW macro calls:
ASSWT:

CSI$SW

AS,ASMSK,MASKX,SET"ASVTBL

CSI$SW

NU,NUMSK,MASKX,CLEAR,NEG,NUVTBL

CSI$ND

created

iEND OF SWITCH DESCRIPTOR TABLE.

The first parameter in the first statement creates 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 (MASKX) is the address of an optional mask word in your task
(see the description of the mkw parameter).
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 creates a switch descriptor table entry for the
switch jNU.
In contrast to the first statement, the fourth parameter
(CLEAR) indicates that the bits in the optional mask word
(MASKX)
in
your task 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 switch value descriptor table
associated with this switch.
Note that the switch descriptor table entry macros are terminated with
the CSI$ND macro (see Section 6.2.4.3).

6.2.4.2 CSI$SV - Create Switch Value Descriptor Table Entry MacroCSI$SV defines a switch value descriptor table entry. For every
switch value that you expect your task to find with a given switch in
a file specification, a corresponding switch value descriptor table
entry must be defined in your program so that the switch value can be
decoded.
This macro creates a 2-word entry in the switch value
descriptor table. The format of this table is shown in Figure 6-3.
The CSI$SV macro call has the following format:
Format
CSI$SV type,adr,len

6-28

COMMAND LINE PROCESSING
Parameters
type
A parameter that specifies the conversion type for the switch
value.
Anyone of four symbolic values may be specified. The
possible conversion types include the following:
ASCII - Indicates that the switch value is to be treated as an
ASCII string.
If you quote the string, the quotes are
returned in the buffer as part of the string.
If a quote
appears anywhere in the switch value, all characters following
it, up to the end of the line or another quote, are included
in the string.
NUMERIC - Indicates a numeric switch value is to be converted
to binary using octal as a default conversion radix.
OCTAL - Indicates a numeric switch value is to be converted to
binary using octal as a default conversion radix.
DECIMAL - Indicates a numeric switch value is to be converted
to binary using decimal as a default conversion radix.
If any parameter is specified other than these, an .ERROR
directive is generated during assembly that causes the error
message INVALID CONVERSION TYPE to be printed in the assembly
listing.
If you do not specify any of the previously described
parameters, ASCII is assumed by default.
adr
The address of your program location that is to receive the
resultant switch value at the conclusion of switch processing.
This parameter is required: if not specified, an .ERROR directive
is generated during assembly that causes the error message VALUE
ADDRESS MISSING to be printed in the assembly listing.
len
A numeric value that defines the length (in bytes)
of the area
that is to receive the switch value that results 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.
The format of a switch value descriptor
CSI$SV macro is shown in Figure 6-3.

table

entry

created

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 I if ASCII is specified:
it is
set to 2 if NUMERIC or OCTAL is specified, and is set to 3 if DECIMAL
is specified. The high-order byte of this word indicates the maximum
allowable length (in bytes) of the switch value.
If the conversion type is ASCII,
the len parameter reflects the
maximum number of ASCII characters that can be deposited in the area
defined through the adr parameter. The high-order byte of the first
word in the switch value table then reflects the maximum length of the
ASCII string.
If the number of characters in the switch value exceeds
the specified length, the extra characters are 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 padded with nulls.
6-29

COMMAND LINE PROCESSING
If the conversion type is numeric, the length of the resulting binary
value is either two bytes or four bytes.
If the size field is less
than 4, 2 bytes are stored.
If the size field is greater than 4, 4
bytes are stored. You must align the buffer on a word boundary.
If you specify the default conversion type for a switch value on
numeric conversions, you can override it with a pound sign (#) or a
period (.).
Preceding a numeric value by a pound sign
(for example,
#10)
forces the conversion type to octal; a numeric value followed by
a period (for example, 10.) forces the conversion type to decimal.
Note also that you may precede a numeric switch value with a plus sign
(+) or a minus sign (-). The plus sign is the default assumption.
If
you specify an explicit octal switch value by using the pound sign
(#), the arithmetic sign indicator (+ or -), if included, must precede
the pound sign (for example, -#10).
If the conversion type is decimal, the switch value is evaluated as a
single number; an overflow into the high-order bit (bit 15) causes an
error condition. However, if the conversion type is octal, a full
l6-bit value may be specified.
16

Switch Value Length

Conversion Type

Address of Location Receiving Switch Result
ZK-297-81

Figure 6-3

Format of Switch Value Descriptor Table Entry

Examples of how the CSI$SV macro call may appear in a program follow:
ASVTBL: CSI$SV
CSI$SV

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

CSI$ND
NUVTBL: CSI$SV
CSI$SV

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

CSI$ND

;END OF SWITCH VALUE TABLE

In these examples, the first parameter in the CSI$SV macro defines the
conversion type.
The next two parameters, in all cases, define the
address and the length of the program location that is to receive the
resultant switch value.
You may reserve the required storage for the first switch value
ASVTBL: as follows:
ASVAL:

.BLKW

;ASCII VALUE STORAGE

You can similarly reserve the required storage for the
value table NUVAL:
through the following statement:
NUVAL:

.BLKW

table

second

switch

;NUMERIC VALUE STORAGE

Note again that switch value tables are
macro call.

6-30

terminated

with

the

CSI$ND

COMMAND LINE PROCESSING
6.2.4.3 CSI$ND - Define End of Descriptor Table - CSI$ND terminates
descriptor tables with a l-word entry. Switch descriptor tables and
switch value descriptor tables must be terminated with a l-word
end-of-table entry. You can create this word, which contains 0, with
the CSI$ND macro call.
This macro call takes no arguments. The examples near the ends of
Sections 6.2.4.1 and 6.2.4.2 illustrate the use of this macro call.

6-31

CHAPTER 7
THE TABLE-DRIVEN PARSER (TPARS)

This chapter describes the table-driven parser (TPARS), which parses
command lines. TPARS permits you to define and parse command lines in
a unique syntax using TPARS-supplied macros, built-in variables, and
your own code.
TPARS parses command lines according to syntax and semantics or
meanin9.
The command line is made up of syntax elements. TPARS
evaluat:es each syntax element of the command line based on a
predefined arrangement of those elements. TPARS parses command lines
using Cl table that you define. You can build a state table, which
contains states and transitions, 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 contains instructions
for further parsing at another state. TPARS uses subexpressions to
resolvE~ complex syntax elements.
On the semantic level, TPARS also
resolves the semantics or meaning of each element based on definitions
supplied within action routines of your program.
These action
routines use TPARS macros, built-in variables, and your code to permit
you to define and parse command lines.
The parser routine that you write is included in your programs that
parse command lines.
TPARS is invoked from within an executing
program by means of a CALL instruction. The CALL invokes the parser
routine as well as the TPARS processor. For further information on
the interrelationships among 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.1

TPARS Macros:

ISTAT$, STATE$, and TRAN$

TPARS provides macros that allow you to write a state table for
parsing a unique command line. The ISTAT$ macro initializes a state
table, the STATE$ macro defines a-state (a particular syntax element)
in your state table, and the TRAN$ macro defines the conditions for
transition to another state.

7-1

THE TABLE-DRIVEN PARSER (TPARS)
7.1.1.1 ISTAT$
Macro - Initialize
the
State
Table - ISTAT$
initializes the state table.
The state table is built using two
macros, STATE$ and TRAN$, which are described in Sections 7.1.1.2 and
7.1.1.3, respectively.
This state table is built into a program
section. Keyword strings that you define for parsing command lines
are also accumulated in a program section. A third program section is
also provided for a keyword pointer table used to enter the list of
keyword strings. The ISTAT$ macro initializes these program sections.
A blank STATE$ macro must follow the TPARS state table.
Format
ISTAT$ statetable,keytable,$DEBUG
Parameters
statetable
The label that you assign to the state table.
this label as the start of the state table.

TPARS

recognizes

key table
The label that you assign to the keyword table.
this label as the start of the keyword table.

TPARS recognizes

$DEBUG
Directs the Assembler to list addresses of the state transition
table in the assembly listing. These addresses are useful for
tracing TPARS operation using a debug routine that you supply
(see Section 7.1.3.4).
When you do not include $DEBUG, state
transition table addresses are not listed.
The state table is built in a program section named $STATE, the
keyword strings are accumulated in a program section named $KSTR, and
the keyword pointer table is built in a program section named $KTAB.
If you define the symbol $RONLY, each of these program sections is
generated as read-only.
You generate a read-only state table by
specifying the symbol $RONLY before the ISTAT$ macro in the form:
$RONLY = 1
ISTAT$ statetable,keytable,$DEBUG

STATE$

7.1.1.2 STATE$ Macro - Defining a Syntax Element - STATE$ declares
the beginning of a state. This macro delimits one command line syntax
element from another. A blank STATE$ macro must follow the TPARS
state table.

7-2

THE TABLE-DRIVEN PARSER (TPARS)
Format
ST.ATE$ [label]
Parameter
label
An alphanumeric symbol that defines the address of the state.
Each state defined by a
transitions defined by
syntax element.

STATE$ macro consists of any number of
The TRAN$ macros parse each
TRAN$ macros.

7.1.1.3 TRAN$ Macro - Defining a Transition - The TRAN$ macro allows
you to match each syntax element in a command line to a given type,
supply a symbolic address to the next TRAN$ macro, supply an address
of an action routine that may be required to further process the
syntax element, and supply a mask that you may use as a flag in the
parsing process.
Format
T~:AN$

type [,label] [,action] [,mask] [,maskaddr]
[,$EXIT]

Parameters
type
The type of command line syntax element being parsed.
You code
the type parameter using one of the following types of command
li.ne elements:
Element Type

Description

$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 any number. A number consists of a string
of
digits; a concluding period is optional.
Numbers not followed by a period are 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 Ononnumeric 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.

7-3

THE TABLE-DRIVEN PARSER (TPARS)
Element Type

Description
character

string.

The

$STRNG

Matches any alphanumeric
string will not be null.

$RAD50

Matches any legal Radix-50 string, that is, any
string containing alphanumeric characters, or the
period (.), or dollar sign ($) characters.
If you
require Radix-50 conversion, the action routine in
your code must convert this number.

$BLANK

Matches a string of blank and/or tab characters.

$EOS

Indicates the position of the end of an input
string.
Once TPARS has reached the end of the
input string,
$EOS is the equivalent of that
position as many times as $EOS is encountered in
the state table.

char

Matches a single character in the syntax element
whose ASCII code corresponds to the value of char.
The value of char must be a 7-bit ASCII code; that
is, the value must be in the range 0-177 (octal).
Specify a single quote (I) before char, such as IA
or IX.

nkeyword n

Matches a specified keyword. Keywords can be any
length, can contain only alphanumeric characters,
must be in uppercase, and are terminated by the
first nonalphanumeric character encountered in
parsing the keyword.
The maximum number
of
keywords allowed in a state table is 64.

!label

Matches the string processed by passing control to
and executing the state table section that starts
with a STATE$ macro that has the label parameter
specified here as !label.
In effect, this type
parameter passes control to a
STATE$
macro
subroutine or subexpression. For information on
TPARS subexpressions, see Section 7.1.4.

[label]
[$EXIT]
The label associated with a STATE$ macro to which execution
control will pass after the code for this TRAN$ transition is
executed.
If the label parameter is omitted, execution control
passes on to the next sequential STATE$ macro. A null label
parameter is allowed only for the last transition in a state; a
TRAN$ macro with a null label field must follow a TRAN$ macro.
Specifying $EXIT in the label field terminates eTPARS execution
and
returns
control to the calling program.
$EXIT also
terminates a TPARS subexpression.
action
The label of an action routine that you include in the parser
routine of your code. This routine can include TPARS built-in
variables, described in Section 7.1.3 below.

7-4

THE TABLE-DRIVEN PARSER (TPARS)
mask
A maskword to be stored in a location pointed to by the maskword
address whenever the TRAN$ macro is executed.
If you specify
mask, you must specify the maskaddr parameter as well
(see the
following parameter).
This maskword is ORed into maskaddr
(described below) when the transition is taken (after the action
routine is called).
maskaddr
The label for an address into which TPARS stores the value
specified by the mask parameter. You must specify the maskaddr
parameter if you specify mask.
The mask and maskaddr parameters provide a convenient
flagging the execution of a particular transition.

7.1.2

means

for

Action Routines and Built-In Variables

Action routines process command line elements at the semantic level.
That is, a given syntax element can have more than one meaning.
Action routines determine and validate the meaning of the syntax
element:s.
You write action routines in your parsing program
functions related to your program's requirements.

7.1.2.1 TPARS Built-In Variables - TPARS
built-in variables for action routines:

provides

perform

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.
Returns the high-order binary value of the number
returned
by a $NUMBR or $DNUMB syntax type
specification.

.PNUMB

Returns the low-order binary value of the number
returned
by a $NUMBR or $DNUMB syntax type
specification.

.PCHAR

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

.PFLAG

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

• TPDEB

Contains the entry address of the
routine that you write.

7-5

optional

debug

THE TABLE-DRIVEN PARSER (TPARS)
R3

Returns the byte count of the remainder of the
input string. When the action routine is called,
the string does not include the characters matched
by the current transition.

Returns the address of the remainder of the input
string.
When the action routine is called, the
string does not include the characters matched by
the current transition.

7.1.2.2 Calling Action Routines - Acti~n routines are called by a JSR
PC instruction. Action routines may modify registers RO, Rl, and R2;
all other registers must be preserved.

7.1.2.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 extending the syntax types
beyond the set provided by TPARS.
When an action routine rejects a transition, that transition has no
effect. TPARS continues to attempt to match the remaining transitions
in the state.

7.1.2.4 Optional Debug Routine for RSX-ll Users - A debug routine
that you supply can be called by TPARS at each state transition
allowing TPARS operation to be traced. For example, the routine can
be written to display the contents of RS each time the routine is
called; RS contains the current transition table address.
By
comparing the addresses displayed with the TPARS assembly listing
showing the state transition table addresses, TPARS operation can be
monitored.
If a debug routine that you supply is to be called by TPARS, your task
must first specify the entry point address for the debug routine in
TPARS location .TPDEB, as follows:
MOV

#DENTER,.TPDEB

Then, invoke TPARS with the .TPARD entry point
(rather
.TPARS). TPARS is invoked as described in Section 7.4.

than

with

Upon entry to the debug program, CPU registers contain the following:
R3

Length of remainder of input string

Address of remainder of input string

Current address of transition table

The debug routine must
returning to TPARS.

save

and

restore

all

registers

prior

For addresses displayed by the debug routine to be useful, you must
obtain an assembly listing showing the addresses of the state
transition tables. These addresses are listed by the assembler if the
optional $DEBUG parameter is provided in the ISTAT$ macro call (see
Section 7.1.1.1).

7-6

THE TABLE-DRIVEN PARSER (TPARS)
7.1.3

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.
You follow this macro by the states and transitions
that comprise the body of the subexpression.
To terminate the
subexpression, specify a TRAN$ macro with the $EXIT keyword specified
in the label field.
The general form of a subexpression is shown in
the example below.
In this example, control is directed to the subexpression by a TRAN$
macro that specifies a !label syntax element as the type parameter:
TRAN$ lUIC,NEXT
TPARS then directs control to the STATE$ macro with the label UIC:
STATE$
TRAN$ I [

UIC

STATE$
TRAN$ $NUMBR"SETGN
STATE$
TRAN$ <I,)
STATE$
TRAN$ $NUMBR"SETPN
ST;~TE$

TRAN$ I] ,$EXIT
When thle UIC subexpression completes processing, control passes to the
state labeled NEXT.

7.2

GENERAL CODING CONSIDERATIONS

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

7.2.1

Suggested Arrangement of Syntax Types in a State Table

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

7-7

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

7.2.2

Ignoring Blanks and Tabs in a Command Line

Bit zero of the low byte of Register 1 (Rl) controls processing of
blanks and tab characters. If this bit is I 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 0, blanks and tab
characters are interpreted as terminator characters; they are ignored
as syntax elements. In neither case does TPARS modify the command
line.
When blanks are being ignored, the $BLANK syntax type never matches an
element on the command line. Also, when this option is in effect,
values returned to the !label syntax type by .PSTCN or .PSTPT may
contain blanks or tabs, even though none were requested. The examples
below show how TPARS parses the string:
ABC DEF
with and without the blank-suppress option.
In the first example, an extra state is required to parse the blank:
STATE$
TRAN$

$STRNG

STATE$
TRAN$

$BLANK

STATE$
TRAN$

$STRNG

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

7.2.3

STATE$
TRAN$

$STRNG

STATE$
TRAN$

$STRNG

the

same

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.

7-8

THE TABLE-DRIVEN PARSER (TPARS)
To include a comma or a semicolon in a char syntax element string, use
angle brackets:
TRAN$

<I,>

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

7.2.4

Recognition of Keywords

When TPARS encounters a transition table entry that specifies a
keyword,
it first scans from the current point in the input string in
search of a delimiter
(nonalphanumeric)
character.
The characters
between the current input point and the next delimiter are then
assumed to be a possible keyword and are matched against the entries
in the keyword table. For this reason, the following example will not
work as expected:
STATE$
TRAN$
TRAN$

"NO",STATEl,SETNEG
$LAMDA"SETPOS

STATE$
TRAN$
TRAN$

STATEl
"AA", •••
"BB", •••

When TPARS encounters the keyword NO, it scans and attempts to match
the string "NOAA" or "NOBB".
If exact matching is requested, neither
the "NO" transition nor the "AA" transition will match.
In addition,
if keyword matching is limited to two characters, the "NO" transition
will match but TPARS will skip past "NOAA" so that the "AA" transition
can be taken.
You can use the following example to achieve the
desired operation:
STATE$
TRAN$
TRAN$

!NONO,STATEl,SETNEG
$LAMDA, , SETPOS

STATE$
TRAN$
TRAN$

STATE
"AA", •••
"BB", •••

STATE$
TRAN$

NONO
'N

STATE$
TRAN$

'O,$EXIT

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

7-9

THE TABLE-DRIVEN PARSER (TPARS)
7.3

PROGRAM SECTIONS GENERATED BY TPARS MACROS

TPARS macros generate three program sections.
Data for the STATE$
macro are stored in the program section $STATE, whereas data for the
TRAN$ macro are stored in program sections $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 you specify them. 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 Extenlion
Action Return Address
Ma.kword
Ma.kword Address
Target State Label
ZK-31."1

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
= 312
= 314

Used in the !label type.

316
= 320
= 322
= 324
= ASCII code for the specified character
= 200+n (See explanation below.)

The value of keyword is 200+n, where n is an index into the keyword
table.
The keyword table is an array of pointers to keyword strings,
which are stored in the program section $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-10

THE TABLE-DRIVEN PARSER (TPARS)
7.4

INVOKING TPARS

You control execution of TPARS using the calling conventions and
options described in this section. You invoke TPARS from within an
executing program by the instruction
CALL

.TPARS

When a debug routine that you specify traces a TPARS operation
Section 7.1.3.4), a special entry point is called, as follows:
CALL

(see

• TPARD

When your task calls TPARS in this manner, TPARS calls the debug
routine at each state transition.
If your task invokes TPARS by the
.TPARS E!ntry point, the debug routine entry point address in .TPDEB is
cleared and the debug routine is not called.

7.4.1

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

contain

= Options word
Pointer to the keyword table
= Length of the string to be parsed
Address of the string to be parsed
Label of the starting state in the state table

On return from
information:
R3
R4

must

TPARS

processing,

registers

contain

the

following

= Length of the unscanned portion of the string
= Address of the unscanned portion of the string

The values of all other registers are preserved.
The Carry bit in the Processor Status Word returns 0 for a successful
parse; the Carry bit is set when TPARS finds a syntax error.
For an E:!xample 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.
The high byte of the options word controls abbreviation of keywords.
If the high byte is set to 0, 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.

7-11

THE TABLE-DRIVEN PARSER (TPARS)
If a syntax error occurs, TPARS sets the Carry bit
Status Word and terminates.

the

Processor

A syntax error occurs when there are no syntax elements in the current
state that match the portion of the string being scanned.
Illegal
type codes and errors in the state table can also cause a syntax
error.
TPARS processing requires that the addresses in the
the keyword tables be reliable; bad addresses
termination.

state table and
may cause program

The only syntax types that can match the end of the
and $LAMDA.

string

7.5

are

$EOS

HOW TO GENERATE A PARSER PROGRAM USING TPARS

Three processing steps generate a parser program using TPARS, as shown
in Figure 7-1. The source program must contain .MCALL statements for
three macros:
ISTAT$, STATE$, and TRAN$.
These three
• MCALL
statements must precede the statements that comprise the state table
and action routines.
Assembling the source module produces an object module composed of
three program sections.
The assembly listing showing the code
produced by the state table macros is not straightforward. The binary
output of the macros is delayed by one statement. Thus, if you enable
the listing of macro-generated binary code during assembly of the
code, the binary code appearing after a macro call is, in fact, the
result of the preceding macro call. Error messages generated by macro
calls are similarly delayed. This is the reason an additional STATE$
macro is required to terminate the state table.
When the parser program is linked and is in task image form, it can be
invoked from within your executing task, as shown in Figure 7-2.

7-12

THE TABLE-DRIVEN PARSER (TPARS)

PARSER.SRC

1.
-----~

Write a source program that
includes the required MCALL
statements.

-:>

MCALL ISTAT$
MCALL STATE$
MCALL TRAN$
STATE$

··

STATE$

PARSER.OBJ

[

MAC RO-ll

2.
PARSER.SRC

Assemble the source program to
produce an object module.

-:>

IPARSER.OBJ

MYFILE.TSK

3.
MYFILE.OBJ

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

-:>

UPDATE.OBJ

ZK-298-81

Figure 7-1

Processing Steps Required to Generate a Parser
Program Using TPARS

7-13

THE TABLE-DRIVEN PARSER (TPARS)
Figure 7-2 shows the CALL .TPARS statement that invokes the parser
program and the TPARS processor. As the parser executes the state
table, it calls action routines.
These action routines access code in
the TPARS processor to perform such functions as returning the values
of the built-in variables. When the state table completes execution,
TPARS receives control and passes control back to the calling program.

Executing
User Program

User-defined
Parser Program

-..

r---.

STATE$

*
*
*

~-,

STATE$

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

TPARS
Processor

Action
Routines

I
I

I
I
I

I
I
I
I
.... _ .J

I
I
I
..... ___ .J

ZK-299-81

Figure 7-2

7.6

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

PROGRAMMING EXAMPLES

This section includes three programming examples of how TPARS can be
used in your program. The first example shows the code required to
parse a UFO command line for RSX-ll. The second example shows the use
of subexpressions and how to reject transitions. The third example
shows how to use subexpressions to parse complex command lines.

7.6.1

Parsing a UFD Command Line

This example shows the code required to parse a UFO command line.
It
includes a state table and action routines. The general form of the
UFO command line is as follows:
UFO OKO:LABEL[20l,202]/ALLOC=lOO./PRO=[RWEO,RWEO,RWE,R]
The action routines
values:
$UOEV
$UUNIT
$UVNML
$UVNAM
$UUIC
$UALL
$UPRO
$FLAGS

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 UFO
Flags word containing the following bits:
UF.ALL Set if allocation was specified
UF.PRO Set if protection was specified

7-14

following

THE TABLE-DRIVEN PARSER (TPARS)
The label and the IALLOC and IPRO switches are optional.
sequence for this routine is as follows:
CL1R

MOV
MOV
MOV
MOV
CALL
BCS

The

calling

Rl
#UFDKTB,R2
COUNT,R3
ADDR,R4
#START,R5
• TPARS
ERROR

The following is an example of the parser routine that you write:
.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
!UIC

READ UIC

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

OPTS
$EOS,$EXIT

'I
"ALLOC",ALC"UF.ALL,$FLAGS
"PRO",PRO~,UF.PRO,$FLAGS

7-15

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

; VOLUME LABEL

7-16

THE TABLE-DRIVEN PARSER (TPARS)
SETLAB: : MOV

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

; PPN - GROUP NUMBER
SETGN: :

MOVB
BR

• PNUMB,$UUIC+1
TSTPPN

; PPN - PROGRAMMER NUMBER
SETPN: :
TSTPPN:

MOVB
TST
BNE
TSTB
BEQ
ADD
RETURN

10$:
20$:

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

CHECK FOR

o HIGH ORDER

CHECK FOR BYTE VALUE
SAD VALUE - REJECT TRANSITION

; NUMBER OF ENTRIES TO ALLOCATE
• PNUMB,$UALL
RETURN

SETALC: : MOV
; SET PERMISSIONS
; INITIALIZE
IGROUP: :MOV

#4,GRCNT

; MOVE TO NEXT PERMISSIONS CATEGORY
NXGRP: :

SEC
ROR
ASR
ASR
ASR
DEC
BGE
ADD
RETURN

BADGRP:
30$:

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

SIC
RETURN

#FP.RDV*10000,$UPRO

BIC
RETURN

#FP.WRV*10000,$UPRO

; SET WRITE PERMIT

SETWP: ::
; SET

I~XTEND

SETEP: ::

PERMIT
BIC
RETURN

#FP.EXT*10000,$UPRO

; SET DELETE PERMIT

SETDP: :

SIC
RETURN

#FP.DEL*10000,$UPRO

; END OF PROTECTION SPEC

7-17

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

7.6.2

GRCNT
BNE
RETURN

; CHECK THE GROUP COUNT
BADGRP
; MUST HAVE 4

• END

UFO

Using Subexpressions and Rejecting Transitions

The following example is an excerpt from a state table that parses a
string in which the first character is interpreted as a quote
character. This typical construction occurs in many editors and
programming languages. The action routines associated with the state
table return the byte count and address of the string in the locations
QSTC and QSTP.
The quoting character is returned in location QCHAR.
MAIN LEVEL STATE TABLE
PICK UP THE QUOTE CHARACTER
STATE$
TRAN$

STRING
$ANY, ,SETQ

ACCEPT THE QUOTED STRING
STATE$
TRAN$

!QSTRG"SETST

GOBBLE UP THE TRAILING QUOTE CHARACTER
STATE$
TRAN$

$ANY,NEXT,RESET

SUBEXPRESSION TO SCAN THE QUOTED STRING
THE FIRST TRANSITION WILL MATCH UNTIL IT IS REJECTED
BY THE ACTION ROUTINE
STATE$
TRAN$
TRAN$
STATE$

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)

; STORE THE STRING DESCRIPTOR
SETST:

MOV
MOV
RETURN

.PSTPT,QSTP
.PSTCN,QSTC

7-18

REJECT TRANSITION ON MATCH

THE TABLE-DRIVEN PARSER (TPARS)
; RESET THE SPACE FLUSH FLAG
DECB
RETURN

RESET:

7.6.3

.PFLAG

Using Subexpressions to Parse Complex Command Lines

The following excerpt from a state table shows how subexpressions
used to parse complex command lines.

are

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

STATE$
TRAN$
STATE$

"DECIMAL",$EXIT

; ACTION ROUTINE TO STORE THE NUMBER
SE:TNUM:

MOV
MOV
RETURN

.PNUMB,NUMBER
.PNUMH,NUMBER+2

The contents of .PNUMB and .PNUMH remain undisturbed
transitions except the $NUMBR and $DNUMB types.

all

state

Because of the way in which sUbexpressions are processed, calls to
action routines from within subexpressions must be handled with care.

7-19

THE TABLE-DRIVEN PARSER (TPARS)
When a subexpression is encountered in a transition, TPARS saves its
current context and calls itself, using the label of the subexpression
as the starting state. If the subexpression parses successfully and
returns by means of $EXIT, the transition is taken and control passes
to the next state. If the subexpression encounters a syntax error,
TPARS restores the saved context and tries to take the next transition
in the state.
However, TPARS provides no means for resetting original values changed
by action routines that were called by subexpressions. Therefore,
action routines called from subexpressions should store results in an
intermediate area.
Data in this intermediate area can then be
accessed by an action routine called from the primary level of the
state table.

7-20

CHAPTER 8
SPOOLING

FCS provides facilities at both the macro and subroutine level to
queue files for subsequent printing; thus, your task can queue a print
Job. There are several ways for your task to spool output for
printing but you cannot control the printing from within your task as
you can with the PRINT command. You can, however, use the DCL SET
QUEUE command to alter the att~ibutes of the print job once the job
appears in the queue.

8.1

PRINT$ MACRO

A task issues the PRINT$ macro 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.
The
If the device is not
file is placed in the default queue PRINT.
specified, LP: is used.
The file to be spooled must be open when the PRINT$ macro is issued.
Once the file is queued, PRINT$ closes the file.
Error returns differ
from normal FCS conventions, and are described in Section 8.3.
The PRINT$ macro call has the following format:
Format
PRINT$ fdb,err"dev,unit,pri,forms,copies,presrv
Parameters
Mb

The address of the associated FOB. This parameter need not be
present if the address of the associated FOB is already in RO.
err
The address of an optional, error-handling routine that you code.
See Section 8.3.
The following parameters are not applicable to
Micro/RSX: dev, unit, pri, forms, copies, presrv

8.2

RSX-11M/M-PLUS

and

.PRINT SUBROUTINE

Your task can open a file on disk, send output to the disk, and close
the file either by using the PRINT$ macro call or by calling the
.PRINT subroutine to spool the output.
The .PRINT subroutine is
called to queue a file for printing. RO must contain the address of
8-1

SPOOLING
the associated FOB. The file must be open when .PRINT is called. The
file is placed in the default queue PRINT and then the .PRINT routine
closes the file. One copy of the file is printed on the LP:
device.
In your task,
it may be preferable to call the .PRINT subroutine if
the routine resides in FCSRES. Using the PRINT$ macro causes all the
code of .PRINT to appear in your task each time it is used.
Section 8.3 describes error
routine.

8.2.1

handling

for

the

.PRINT

file

control

Opening a File on Disk and Using the PRINT Command

As stated in the opening of this section, your task can open a file on
disk, send output to that disk, and close the file. When the task
exits, the PRINT command can print the file.
This is the only method
that gives you access to the PRINT command qualifier. Other than
using the qualifier, your task can use PRINT$ or .PRINT; you then wait
until the job is in the queue and alter its attributes with the SET
QUEUE command.
If you run your task from an indirect command file or batch job that
includes a PRINT command after the task exits, the difference between
spooling from within a task or from outside it is negligible.
You can use the SPWN$ directive in the task to issue the PRINT
command.
(Re fer to the RSX-llM/M-PLUS and Micro/RSX Executive
Reference Manual.)

8.2.2

Opening a File on LP:

Your task can use the OPEN$ macro to name the output device.
FCS
opens the file on pseudo device SPO:. The file is placed in the
device-specific queue for the device you named. When your task has
finished writing to this file, close it with a CLOSE$ macro. The file
is deleted after it is printed. This file does not remain in any
directory but is identified by a file-ID number labeled FlO in the
SHOW QUEUE display.

8.3

ERROR HANDLING

The error returns provided with PRINT$ and .PRINT differ from the
standard FCS error returns.
Unlike FCS error returns, PRINT$ and
.PRINT 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 (for example, the PRINT$ macro cannot
close the file),
the Carry bit is set and F.ERR contains the error
code.
If the failure is related to the SEND/REQUEST directive that
queues the file,
the Carry bit is set and the directive status word
contains an error code. Directive status word error codes are listed
in the RSX-llM/M-PLUS and Micro/RSX Executive Reference Manual.
Normally, once you determine that the C-bit is set, any error routine
that you code should first test F.ERR and then test the directive
status word error code.

8-2

APPENDIX A
FILE DESCRIPTOR BLOCK

A File [~scriptor Block (FOB) contains file information that is used
by FilE! Control Services (FCS) and the file control primitives. The
layout of an FOB is illustrated in Figure A-I. Table A-I defines the
offset locations within the FOB.
The offset names in the File Descriptor Block may
locally or globally, as shown below:
FDOF$L

defined

;DEFINE OFFSETS LOCALLY.

FDOFF$

DEF$L

;DEFINE OFFSETS LOCALLY.

FDOFF$

DEF$G

;DEFINE OFFSETS GLOBALLY.
NOTE

When you refer to FOB locations, it is essential
to use the symbolic offset names, rather than the
actual address of such locations.
The position
of information within the FOB may be subject to
change from release to release, whereas the
offset names remain constant.

A-I

either

FILE DESCRIPTOR BLOCK
File Attribute Section
F.RATT

Record attributes

Record type

o F.RTYP

Record size

2 F.RSIZ

Highest virtual block number allocated

4 F.HIBK

End of file block number

10 F.EFBK

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

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

Record- or Block-Access Section
14 F.FFBY

First free byte in last block
F.RCTL

Record control

Record access

20 F.BKDS

User's record buffer descriptor

20 F.URBD

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

16 F.RACC

Block I/O buffer descriptor

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

Next record buffer descriptor
------ -------------

-----

24 F.NRBD

Block I/O status block address

24 F.BKST

Block I/O done AST address

26 F.BKDN

Override block buffer size

30 F.OVBS

Next record address in block buffer

30 F.NREC

End of block buffer

32 F.EOBB

Record number for random records

34 F.RCNM

- - - - - - - - - - - - - - - - - - - ----Size in blocks of contiguous file

34 F.CNTG

Address to read in statistics block

36 F.STBK

ZK-3010/1-84

Figure A-I

File Descriptor Block Format

A-2

FILE DESCRIPTOR BLOCK
File-Open Section

F.FACC

Amount of space allocated when needed

40 F.ALOC

42 F.LUN

File access

Logical unit number

File descriptor pointer

44 F.DSPT

Default file name block address

46 F.DFNB

Block-Buffer Section
51

Bookkeeping bits

010 event flag

2nd byte error return code

1st byte error return code

52 F.ERR

F.MBC1

Number of buffers in use

Number of buffers desired

54 F. MBCT

F.BGBC

Big buffer block count (blks)

Multiple buffer control flags

56 F. MBFG

F.BKP1

Virtual block size (bytes)

60 F.VBSZ

Block buffer size

62 F.BBFS

Block 1/0 virtual block number

64 F.BKVB

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

Virtual block number

64 F.VBN

Block buffer descriptor block

70 F.BDB

FOB extension address

72 F.EXT

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

F.CHR

50 F.EFN or F.BKEF

ACP volume character byte

Flag byte

74 F.FLG

Access control word

76 F.ACTL

Sequence number for sequenced files

100 F.SEON

Beginning of file name block

102 F.FNB
ZK-3010/2-84

Figure A-I (Cont.)

File Descriptor Block Format

Table A-I
FOB Offset Definitions
Symbolic
Offset
Name

Size
(in bytes)

Contents

F.RTYP

Record-type byte.
This byte is set,
as
follows, to indicate the type of records for
the file:
F.RTYP = 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.RTYP = 4 to indicate
stream
ASCII
records (R. STM) •
{Continued on next page}

A-3

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

Size
(in bytes)

Contents

F.RATT

Record attribute byte. Bits 0 through 3 are
set
to
indicate record attributes,
as
follows:
Bit 0 = 1 to indicate that the first byte
of a
record is to contain a FORTRAN
carriage control
character
{FD.FTN)i
otherwise, it is o.
Bit 1 = 1 to indicate for a carriage
control device that a line feed is to be
performed before the line is printed and
a carriage return is to be performed
after the line is
printed
{FD.CR)i
otherwise, it is o.
Bit 2 = 1 to indicate the "print file
format"
(FD.PRN).
FCS
allows this
attribute but does not interpret the
format word.
Bit 3 = 1 to indicate that records cannot
cross
block
boundaries
{FD.BLK)i
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 virtual
allocated.

F.EFBK

Contains the end-of-file block number.

block

number

The format of the block number is high-order
word followed by low-order word.
F.FFBY

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

F.RACC

Record access byte. Bits 0 through 3 of
this byte define the record access modes, as
follows:
Bit 0 = 1 to indicate READ$/WRITE$ mode
(FD.RWM); otherwise, it is 0 to indicate
GET$/PUT$ mode.
(Continued on next page)

A-4

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

Contents

Size
(in bytes)

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
1 to indicate locate
mode
(FD.PLC)
for
GET$/PUT$
record I/O;
otherwise, it is 0 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.
F • RCT'L

Device characteristics byte. Bits 0 through
5 define the characteristics of the device
associated with the file, as follows:
Bit 0 = I to indicate a record-oriented
devi ce
(FD. REC) ,
for
example,
a
teletypewriter or line printer; a value
of 0 indicates a block-oriented device,
for example, a disk or DECtape.
Bit I = I to indicate a carriage control
device (FD.CCL); otherwise, it is o.
Bit 2 = I to
indicate
a
teleprinter
device (FD.TTY); otherwise, it is o.
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
UFOs are present.
Bit 5 = I to indicate a block-oriented
device that is inherently sequential in
nature (FD.SQD), such as magnetic tape.
A record-oriented device is assumed to be
sequential in nature; therefore, this bit
is not set for such devices.
Bit 6 = I
(FD. ISP) •

indicate

input

spooling

Bit 7 = I to
(FD.OSP) •

indicate

output

spooling

(Continued on next page)

A-5

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

Size
(in bytes)

Contents

Bit 8

1 for DIGITAL use (FD.PSE) •

Bit 9

1 for DIGITAL use (FD.COM) •

Bit 10

1 for DIGITAL use (FD. F 11) •

Bit 11

1 for DIGITAL use (FD.MNT) •

F .BKDS
or
F.URBD

F.NRBD

Contains the next record buffer descriptor.
The record buffer descriptor contains the
size of the buffer in the first word and the
address of the buffer in the second word.

or
F .BKST
and

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.

F.RCNM
or

Contains the number of the record for random
access operations. The format of the record
number
is the high-order word followed by
the low-order word.

F.CNTG
and

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

F.STBK

Contains the address of the statistics block
in your program.

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

the

AST

service

record

end-of-block

(Continued on next page)

A-6

FILE DESCRIPTOR BLOCK
Table A-1 (Cont.)
FOB Offset Definitions
Symbolic
Offset
Name

Size
(in bytes)

Contents

F.ALOC

blocks
to
be
Contains the number of
allocated when the file must be extended. A
contiguous
pos i t i ve
( + ) value indicates
extend, and a negative (-) value indicates
noncontiguous extend.

F.LUN

Contains the logical unit number
with the FOB.

F.FACC

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

associated

Bit 0 = 1 if the file
reading only (FA.RD).

accessed

for

Bit 1 = 1 if the file
writing (FA. WRT) •

accessed

for

Bit 2 = 1 if the file
extending (FA.EXT) •

accessed

for

Bit 3 = 1 if a new file is being created
(FA.CRE); otherwise, it is 0 to indicate
an existing file.
Bit 4 = 1 if the file is a temporary file
(FA.TMP).
Bit 5 = 1 if the file
shared access (FA.SHR).

opened

for

If Bit 3 above is 0:
Bit 6 = 1 if an existing file is being
appended (FA.APD).
If Bit 3 above is 1:
Bit 6 = 1 if not
file at
existing
(FA. NSP) •

an
superseding
file-create time

F.DSPT

Contains the Dataset Descriptor pointer.

F.DFNB

Contains the default filename block pointer.

F.BKEF

Contains the block I/O event flag.

clr

F.EFN

Contains the record I/O event flag.
(Continued on next page)

A-7

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

Contents

Size
(in bytes)

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:

FCS

internal
value

F.ERR+I = 0 to indicate that error code
is an I/O error code (see 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 number of
buffers
currently
in use if the multibuffering
version of FCS is in use.

F.MBFG

Multibuffering flag word.
Contains either
one of the multibuffering flags, as follows:
Bit 0 =
(FD.RAH) •

Bit l I t o
(FD.WBH) •
F.BGBC

indicate
indicate

used

read-ahead
write-behind

Big-buffer block count in number of blocks
if the big-buffer version of FCS is in use.
Buffer offset for reading ANSI magnetic tape
in record mode.

F.VBSZ

Device buffer size word.
Contains
virtual block size (in bytes).

F.BBFS

Indicates the block buffer size.

F.BKVB
or

Contains the virtual block
user program for block I/O.

F.VBN

the

number in the

Contains the virtual block number.
The
format of the virtual block number is the
high-order word followed by the low-order
word.
(Continued on next page)

A-a

FILE DESCRIPTOR BLOCK

Table A-I (Cont.)
FOB Offset Definitions
Size
(in bytes)

Contents

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

Address of FOB extension.

F.FLG

Flag byte.

F.CHR

Volume characteristics byte.

Symbolic
Offset
Name

Bit 0 = 1 to indicate
formats 0 or F.
F. AC'I'L

ANSI

magnetic

tape

The low-order byte of this word indicates
the number of retrieval pointers to be used
for the file.
The control bits are in the high-order
and are defined as follows.
Bit 15 = 1 to
information is
(FA.ENB) •

byte

specify
that
control
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).
Bit 11 = 1 to
volume set to
close (FA.RWD).

cause a magnetic tape
be rewound upon open or

Bit 9 = 1 to cause a file not to be
locked if it is not properly closed when
accessed for write (FA.DLK).
F.SEQN
F.FNB

Contains the sequence number
records.

for

sequenced

The symbolic offset of the beginning of
filename block portion of the FOB.

A-9

the

APPENDIX 8
FILENAME BLOCK

The format of a filename block is illustrated in Figure 8-1.
offsets within the filename block are described in Table B-1.

The

The offset names in a filename block may be defined either locally
globally, as shown below:

N1BOF$L

;DEFINE OFFSETS LOCALLY.

N:BOFF$

DEF$L

;DEFINE OFFSETS LOCALLY.

N:BOFF$

DEF$G

;DEFINE OFFSETS GLOBALLY.
NOTE

When you refer 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 change from release to
release,
whereas
the
offset
names remain
constant.
Table B-1
Filename Block Offset Definitions
Symbolic
Offset
Name

Contents

Size
(in bytes)

N.FID

File identification field

N.FNAM

File name
characters
format

as
nine
field;
specified
that are stored in Radix-50

N. F'I'YP

File type
characters
format

field; specified
that are stored

N.FVER

File version number field (binary)

N.S'I'AT

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

as
three
in Radix-50

(See

bit

(Continued on next page)

B-1

FILENAME BLOCK
Table B-1 (Cont.)
Filename Block Offset Definitions
Symbolic
Offset
Name

Size
(in bytes)

N.NEXT

Context for next .FIND operation

N.DID

Directory identification field

N.DVNM

ASCII device name field

N.UNIT

Unit number field (binary)

Contents

The bit definitions of the filename block status word (N.STAT) in the
File Descriptor Block
(FOB) and their significance are described in
Table B-2.

0
2

N.FID

4
6
N.FNAM

10
12

N.FTYP

N.FVER

N.STAT

CUMULATIVE
LENGTH IN
BYTES (OCTAL)

20
N.NEXT

22
24
N.DID

26
30
N.DVNM
N.UNIT

32
34
ZK-301-81

Figure B-1

Filename Block Format

B-2

FILENAME BLOCK

Table B-2
Filename Block Status Word (N.STAT)
Symb()lic
OffsE!t
Name

Value
(in octal)

Meaning

NB.VgR 1

Set if explicit
specified

NB.TYP 1

Set if explicit file type is specified

NB.NAM 1

Set if explicit file name is specified

NB.SVR

Set if wildcard
specified

NB.STP

Set if wildcard file type is specified

NB.SNM

Set if wildcard file name is specified

NB.DIR 1

100

Set if explicit directory string (UIC)
specified

NB.DlE:V 1

200

Set if explicit
specified

NB.SDI 2

400

Set if group portion
wildcard specification

UIC

contains

NB.SlD2 2

1000

Set if owner portion
wildcard specification

UIC

contains

NB.ANS

2000

Set if file name is in ANSI format.

NB.WCH

4000

Set if wild
required.

file

version

number

version

device

character

number

name

string

processing

NOTE
Other bits are set as required by
and PIP for processing.
1. Indicates bits that are set if the associated
supplied through an ASCII dataset descriptor.
2. Although NB.SDI and NB.SD2 are defined, they
nor supported by FCS.

B-3

FCS

information
are

neither

is
set

FILENAME BLOCK

The filename block format for ANSI magnetic tape file names
in Figure B-2.

shown

o
N.FIO

2
N.ANM1
14
N.FVER
16

N.STAT

20
N.NEXT
22
N.ANM2
30
N.OVNM
N.UNIT

34
ZK-302-81

Figure B-2

ANSI Filename Block Format

The filename block offset definitions for ANSI magnetic tape are shown
in Table B-3.
Table B-3
Filename Block Offset Definitions for ANSI Magnetic Tape
Symbolic
Offset
Name

Size
(in bytes)

Definition

N.FID

File identification field

N.ANMl

First 12 bytes of ANSI filename string

N.FVER

File version number field

(binary)

N.STAT

Filename
block
status
definitions in Table B-2.)

word

N.NEXT

Context for next .FIND operation

N.ANM2

Remainder of the ANSI filename string

N.DVNM

ASCII device name field

N.UNIT

Unit number field (binary)

B-4

(See

bit

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 t~at 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 ~SX-IIM/M-PLUS and Micro/RSX Executive Reference Manual.
Table C-I
Summary of I/O-Related System Directives
Function and Parameters

Directive
ALUN$

Assign Logical unit Number -number to a physical device.

Assigns

logical

unit

Syntax
ALUN$
lun

= Logical unit number

dev
unt
GLUN$

lun,dev,unt

Physical device name (two ASCII characters)

= Physical device unit number

Get Logical Unit Number Information -- Fills a 6-word
buffer with information about a physical unit to which
the LUN is assigned.
Syntax
GLUN$

lun,buf

lun

Logical unit number

buf

= Address of a 6-word buffer in which

the

LUN

information is to be stored
GMCR$

Get MCR Command Line -- Transfers an 80-byte MeR command
line to the task issuing GMCR$.
No parameters are
required in this Directive.

QIO$

Queue I/O Request -- Places an I/O request in the device
queue associated with the specified logical unit number.
(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

Syntax
QIO$ fnc,lun,efn,pri,isb,ast,prl

= I/O function code
lun = Logical unit number

fnc

efn

Event flag number

pri

Priority of the request (ignored but must
present)

isb = Address of the I/O status block
ast
prl
QIOW$

Entry-point
routine

address

the

AST

service

= Parameter list in the form <Pl, ••• ,P6>

Queue I/O Request and wait -- Places an I/O request in
the device queue associated with the specified logical
unit number. The Executive suspends the task until the
specified event flag is set.
Syntax
QIOW$ fnc,lun,efn,pri,isb,ast,prl
fnc

= I/O function code

lun

Logical unit number

efn

Event flag number

pri

Priority of the request (ignored but must
present)

isb

Address of the I/O status block

ast

= Entry-point

address

the

AST

service

routine

prl
RCST$

= Parameter list in the form <Pl, ••• ,P6>

Receive Data or Stop -- Instructs the system to dequeue
a 13-word data block for the task issuing RCST$; the
data block was queued for the task with a Send Data
directive (SDAT$) or a Send, Request, and Connect
directive (SDRC$).
(Continued on next page)

C-2

SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES
Table C-l (Cant.)
Summary of I/O-Related System Directives
Function and Parameters

Dire'cti ve
Syntax

RCST$ tname,buf
tname

= Name of the sending task (if not specified,
data may be received from any task)

buf

RCVD$

Address of a IS-word buffer to receive
sender task name and data

the

Receive Data -- Receives a l3-word data block that has
been queued
(FIFO) by a Send Data directive (see SDAT$
and SDRC$ which follow).
Syntax
RCVD$ tsk,buf

= Name of the sending task
buf = Address of the IS-word data
tsk

buffer
(2-word
sending task name and l3-word data block)

RCVX$

Receive Data or Exit -- Receives a l3-word data block if
queued by a Send Data directive (see SDAT$ and SDRC$
following), or the task exits if no data is queued •
. Syntax
RCVX$ tsk,buf

SDAT:$

tsk

= Name of the sending task (if

buf

= Address of the IS-word

not specified,
data may be received from any task)
data buffer
(2-word
sending task name and l3-word data block)

Send Data -- Queues (FIFO) a l3-word block of data for a
task to receive, and declares a significant event.
Syntax
SDAT$ tsk,buf,efn
tsk

SDRC$

= Name of the receiving task

buf

Address of the l3-word data buffer

efn

Event flag number

Send, Request, and Connect
Executes a Send Data
directive to the specified task, requests the Executive
to activate the task if it is not already active, and
then connects to the task.
(Continued on next page)

C-3

SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES
Table C-l (Cont.)
Summary of I/O-Related System Directives
Function and Parameters

Directive
Syntax

SDRC$ tname,buf,efn,east
tname

Target task name of the offspring
be connected

buf

= Address of a 13-word send buffer

efn

= The event flag to be
and set when
emits status

east
SDRP$

task

cleared on issuance
the offspring task exits or

Address of an AST routine to be called when
the offspring task exits or emits status

Send Data Request and Pass Offspring Control Block
Sends a data packet for the specified task, chains to
the requested task; and requests it if it is not already
active.
Syntax
SDRP$ task,bufadr,buflen,efn,flag
task

Name of the task to be chained to

bufadr

Address of the buffer to be given
requested task

the

buflen

Length of the buffer to be
requested task

the

efn

Event flag

flag

Flags byte controlling the execution of
this directive. The flag bits are defined
as follows:
SO. REX

given

= 128.

Force this task to exit
upon successful completion of
this directive

Pass all connections to
1.
the requested task (defaul t is
If you specify
pass none).
this flag, do not specify the
parent task name.

SD.RAL

NOTE
The target task may not
be a CLI task.

(Continued on next page)

C-4

SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES
Table C-1 (Cont.)
Summary of I/O-Related System Directives
Function and Parameters

Directive

SD.RNX

SMSG~~

= 2.

Pass the first connection
in the queue, if there is one,
to the requested task.
If you
specify
this
flag, do not
specify the parent task name.

Send Message
Creates and sends
a
formatted data packet to a system-defined target task.
The only valid target for the Send Message directive is
the Error Logger.
The task that issues the SMSG$
directive must be privileged.
Syntax
SMSG$ tgt,buf,len,<pri, ••• ,prn>
tgt

Target identifier

buf

Address of optional data buffer

len

= Length

bytes

optional

data

buffer
<pri, ••• ,prn>

VRCD$

= Target-specified parameter list

Variable Receive Data
Instructs the
system to dequeue a variable-length data block for the
task issuing VRCD$.
The block was queued by the
Variable Send Data directive.
If you specify the
sending task, only data sent by that task is received.
Syntax
VRCD$ task,bufadr,buf1en

VRCS$

task

= Sender task name

bufadr

Buffer address

buf1en

Buffer size
in
words
(256.
words
maximum). The default is 13. words. The
first two words are the sender task name.
The data block follows.

Variable Receive Data or Stop -- Instructs
the system to dequeue a variable-length data block for
the task issuing VRCS$.
The block was queued by a
Variable Send Data directive.
If there is no packet,
the task issuing VRCS$ is stopped. The sending task is
expected to issue an Unstop directive after sending the
data. When you specify a sender task, only data sent by
that task is received.
Syntax
VRCS$ task,bufadr,buf1en
task

= Sender task name

(Continued on next page)

C-5

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

Function and Parameters
bufadr
buflen

VRCX$

Buffer address

= Buffer

size
in
words
(256.
words
maximum).
The default is 13. words. The
first two words are the sender task name.
The data block follows.

Variable Receive Data or Exit -- Instructs
the sys~em to dequeue a variable-Length data block for
the issulng task. The data block was queued for the
task by a Variable Send Data directive.
If you specify
a sender task, only data sent by that task is received.
If no data has been sent to the task issuing VRCX$, the
task exits.
Syntax
VRCX$ task,bufadr,buflen
task

The name of the sending task

bufadr

The buffer address

buflen

VSDA$

= The

buffer length
(a maximum of 256.
words) •
The default is a mlnlmum of 13.
words.
The first two words are the sender
task name.

Variable Send Data -- Instructs the system
to queue a variable-length data block for the specified
task to receive.
If you specify an event flag,
a
significant
event
is declared when the directive
executes successfully.
Syntax
VSDA$ task,bufadr,buflen

VSRC$

task

Receiving task name

bufadr

Buffer address

buflen

Buffer size in words (a maximum of
words).
The default is 13. words.

256.

variable Send, Request,
and Connect
Performs a Variable Send Data to the specified task,
requests the task if it is not already active, and then
connects to the task.
Syntax
VSRC$ tname,buf,buflen,efn,east,esb
tname

Target task name of the offspring task
be connected

(Continued on next page)
C-6

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

Function and Parameters
buf

= Address of send buffer

buf1en = Length of the buffer (a maximum of
words). The default is 13. words.
efn

= The event flag cleared when the

east

= Address of an AST

directive
is issued and set when the offspring task
exits or emits status

when the
status
esb

256.

routine
offspring task

to be called
exits or emits

= Address of an 8-word status
written when
emits status:

block to be
the offspring task exits or

Word 0

Offspring task exit status

Word 1

TKTN abort code

Words 2-7

Reserved

C-7

APPENDIX 0
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 FOB.
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$
iAssign CR or file device
INLUN=3
iAssign to output device
OUTLUN=4
FSRSZ$ 2
iAllocate space for output FOB
FDBOUT: FDBDF$
iInit file attributes
FDAT$A R.VAR,FD.CR
FDRC$A ,RECBUF,80.
iInit record attributes
iInit file open section
FDOP$A OUTLUN"OFNAM
iAllocate space for input FOB
FDBIN: FDBDF$
iInit record attributes
FDRC$A ,RECBUF,80.
iInit file open section
FDOP$A INLUN"IFNAM
iRecord buffer
RECBUF: .BLKB
80.
OFNAM: NMBLK$ OUTPUT,DAT
iOutput filename
iInput filename
NMBLK$ INPUT,DAT
IFNAM:
START: FINIT$
iInit file storage region
iOpen the input file
OPEN$R tFDBIN
BCS
ERROR
iBranch if error
iOpen the output file
OPEN$W tFDBOUT
BCS
ERROR
iBranch if error
iNote - URBD is all set up
#FDBIN
GTREC: GET$
BCS
CKEOF
iError should be EOF indication
iRl=size of record read
MOV
F.NRBD(RO) ,Rl
#RECBUF,R2
MOV
ADD
Rl,R2
iR2=address of last byte+l
iStrip trailing blanks
1()$:
CMPB
#40,- (R2)
BNE
PTREC
Rl,lO$
SOB
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:
ERROR:

PUT$
BCC
NOP

iRl is needed to specify
ithe record size.
iError code goes here

#FDBOUT"R1
GTREC

0-1

SAMPLE PROGRAMS
CKEOF:

FDBOUT:

FDBIN:
RECBUF:
CFDSPT:
IFDSPT:
ONAM:
INAM:
START:

GTREC:

10$:

CMPB
BNE
CLOSE$
BCS
CLOSE$
BCS
EXIT$S
.END

#IE.EOF,F.ERR (RO) ;End of file?
ERROR
;Branch if other error
RO
;Close the input file
ERROR
#FDBOUT
;Close the output file
ERROR
;Issue exit directive
START

.TITLE CRCOPA
;Card reader copy routine
• MCALL FDBDF$,FDAT$A,FDRC$A,FDOP$A,NMBLK$,FSRSZ$
.MCALL OPEN$R,OPENSW,GET$,PUT$,CLOSE$,EXIT$S
.MCALL FINIT$
INLUN=3
;Assign CR or file device
;Assign to output device
OUTLUN=4
FSRSZ$ 2
FDBDF$
FDAT$A R.VAR,FD.CR
FDRC$A ,RECBUF,80.
FDOP$A OUTLUN,OFDSPT
FDBDF$
FDRC$A ,RECBUF,80.
FDOP$A INLUN,IFDSPT
.BLKB
80.
.WORD
0,0
;Device descriptor
;Directory descriptor
.WORD
0,0
.WORD
ONAM$Z,ONAM
;Filename descriptor
;Device descriptor
.WORD
0,0
.WORD
0,0
;Directory descriptor
;Filename descriptor
.WORD
INAMSZ,INAM
.ASCII /OUTPUT.DAT/
ONAMSZ=.-ONAM
.EVEN
.ASCII /INPUT.DAT/
INAMSZ=.-INAM
• EVEN
FINIT$
;Init file storage region
;Open the input file
OPEN$R #FDBIN
BCS
ERROR
;Branch if error
;Open the output file
OPEN$W #FDBOUT
BCS
ERROR
;Branch if error
;Note - URBD is all set up
GET$
#FDBIN
BCS
CKEOF
;Error should be EOF indication
;Rl=size of record read
F.NRBD(RO),Rl
MOV
MOV
#RECBUF,R2
ADD
Rl,R2
;R2=address of last byte+l
;Strip trailing blanks
CMPB
#40,-(R2)
BNE
PTREC
Rl,lO$
SOB

;At this point, Rl contains the stripped size of the
;record to be written.
If the card is blank,
ia zero-length record is written.
PTREC:
ERROR:
CKEOF:

PUT$
BCC
NOP
CMPB
BNE
CLOSE$

#FDBOUT"Rl
GTREC

;Rl is needed to specify
;the record size.
;Error code goes here
#IE.EOF,F.ERR(RO) ;End of file?
ERROR
;Branch if other error
RO
;Close the input file

0-2

SAMPLE" PROGRAMS
BCS
CLOSE$
BCS
EXIT$S
.END

FDBOUT:
FDBIN:
RECBUF:
CE~DSPT :
IEmSPT:
ONAM:
INAM:
S~~ART :

mrREC:

10$:

ERROR
#FDBOUT
ERROR

iClose the output file
ilssue exit directive

START

.TITLE CRCOPB
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$,FDAT$R
INLUN=3
iAssign CR or file device
iAssign to output device
OUTLUN=4
FSRSZ$ 2
FDBDF$
FDBDF$
• BLKB
80.
.WORD
0,0
;Device descriptor
.WORD
0,0
iDirectory descriptor
.WORD
ONAM$Z,ONAM
iFilename descriptor
• WORD
0,0
iDevice descriptor
.WORD
0,0
iDirectory descriptor
.WORD
INAMSZ,INAM
iFilename descriptor
.ASCII /OUTPUT.DAT/
ONAMSZ=.-ONAM
• EVEN
.ASCII /INPUT.DAT/
INAMSZ=.-INAM
• EVEN
FINIT$
ilnit file storage region
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
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
CMPB
iStrip trailing blanks
#40,-(R2)
BNE
PTREC
SOB
Rl,lO$

iAt this point, Rl contains the stripped size of the
irecord to be written.
If the card is blank,
i8 zero-length record is written.
prrREC:
EHROR:
CKEOF:

PUT$
BCC
NOP
CMPB
BNE
CLOSE$
BCS
CLOSE$
BCS
EXIT$S
.END

#FDBOUT"Rl
GTREC

iRl is needed to specify
ithe record size.
iError code goes here
#IE.EOF,F.ERR(RO) iEnd of file?
ERROR
iBranch if other error
RO
iClose the input file
ERROR
#FDBOUT
iClose the output file
ERROR
ilssue exit directive
START

0-3

APPENDIX E
INDEX FILE FORMAT

The index file ([O,O]INDEXF.SYS) of a Files-ll volume consists of
virtual blocks, starting with virtual block 1, the bootstrap block.
Virtual block 2 is the home block. The structure of an index file is
shown below.
Virtual Block Number

Index File Element

Bootstrap block

Home block

Index file bit map (n blocks);
the value of n is in the home
block

3+n

Index file header

3+n+l

Storage map header

3+n+2

Bad block file header

3+n+3

Master File Directory header

3+n+4

Checkpoint file header

3+n+5

User file header 1

3+n+6

User file header 2

User file header n.

E.l

BOOTSTRAP BLOCK

A disk that is structured for Files-ll has a 256-word block, starting
at physical block O. This block contains either a bootstrap routine
or a message to the operator stating that the volume does not contain
a bootstrappable system.
The bootstrap routine brings a core image
into memory from a predefined location on the disk.

E.2

HOME BLOCK

The home block contains volume identification information that is
formatted as shown in Table E-l. This block is located either in
logical block 1 or at any even multiple of 256 blocks.
E-l

INDEX FILE FORMAT
The offset names in the home block may be defined
globally, as shown below.

E.3

either

HMBOF$

DEF$L

;DEFINES OFFSETS LOCALLY.

HMBOF$

DEF$G

;DEFINES OFFSETS GLOBALLY.

locally

INDEX FILE BIT MAP

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

o - Indicates that the file header block is available.

The
control primitives can use this block to create a file.

file

This

block

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

E.4

PREDEFINED FILE HEADER BLOCKS

The first five file header blocks are described below.
Significance

File Header Block
Index File Header

This is the standard
with the index file.

Storage Map File
Header

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

Bad Block File
Header

The bad block file is
consists
of
unusable
sectors) on the disk.

Master File Directory
Header

This header block is associated with the
Master File Directory for the disk.
This directory contains entries for the
index file, the storage map file,
the
bad
block
file,
the
Master File
Directory (MFD),
the checkpoint file,
and all User File Directories (UFOs).

Checkpoint File Header

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

header

associated

a file
blocks

that
(bad

The remainder of the index file consists of file header blocks for
user files, as shown in the list at the beginning of this section.

E-2

INDEX FILE FORMAT
Table E-l
Home Block Format
Size
(in bytes)

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

12.

Volume name (12 ASCII
characters)

H.VNAM

Reserved

Volume owner's UIC

H.VOWN

Volume protection code

H.VPRO

Volume characteristics

H.VCHA

Default file protection
word

H.DFPR

Reserved

Default number of
retrieval pointers
in a window

H.WISZ

Default number of
blocks to extend files

H.FIEX

Number of entries in
directory LRU

H.LRUC

11.

Available space

Checksum of words 0-28

H.CHKl

14.

Creation date and time

H.VDAT

100.

Volume header label (not
used)

82.

System-specific information (not used)

254.

Relative volume table
(not used)

Checksum of home block
(Words 0 through 255)

E-3

H.CHK2

APPENDIX F
FILE HEADER BLOCK FORMAT

Table F-l shows the format of the file header block.
The various
areas within the file header block are described in detail in the
following sections. The offset names. in the file header block may be
defined either locally or globally, as shown in the following
statements:
FHDOF$

DEF$L

;DEFINE OFFSETS LOCALLY.

FHDOF$

DEF$G

;DEFINE OFFSETS GLOBALLY.
Table F-l
File Header Block

Area

Header Area

Size
(in bytes)

Content

Offset

Identification area offset
in words

H.IDOF

Map area offset in words

H.MPOF

File number

H.FNUM

File sequence number

H.FSEQ

Structure level and system
number

H.FLEV

Offset to file owner
information, consisting of
member number and group
number

H.FOWN

Member number

H.PROG

Group number

H.PROJ

File protection code

H.FPRO

User-controlled file
characteristics

H.UCHA

(Continued on next page)

F-l

FILE HEADER BLOCK FORMAT
Table F-I (Cont.)
File Header Block
Area

Identification
Area

Map Area

Content

Size
(in bytes)

Offset

System-controlled file
characteristics

H.SCHA

32.

User file attributes

H.UFAT

Size in bytes of header
area of file header block

S.HDHD

File name (Radix-50)

I.FNAM

File type (Radix-50)

I.FTYP

File version number
(binary)

I.FVER

Revision number

I.RVNO

Revision date

I.RVDT

Revision time

I.RVTI

Creation date

I.CRDT

Creation time

I.CRTI

Expiration date

I.EXDT

To round up to word
boundary
Size (in bytes) of
identification area of
file header block

S.IDHD

Extenaion 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 I is used

M.CTSZ

Size (in bytes) of the
logical block number field
of a retrieval pointer (2,
3, or 4); only 3 is used

M.LBSZ

(Continued on next page)

F-2

FILE HEADER BLOCK FORMAT
Table F-l (Cont.)
File Header Block
Area

Content

Offset

Words of retrieval pointers
in use in the map area

M.USE

Maximum number of words
of retrieval pointers
availab~e in the map area

M.MAX

Start of retrieval pointers

M.RTRV

Size in bytes of map area
of file header block

S.MPHD

Checksum of words 0 through
255

H.CKSM

Size
(in bytes)

Checksum Word

NOTE
The checksum word is the last word of the file header
block.
Retrieval pointers occupy the space from the
end of the map area to the checksum word.

F.l

HEADER AREA

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

block

consists

Identification area
offset

Word 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; for
example, the index file is number 1, the
storage bit map is file number.2, and so forth.

File sequence number

The file number and the file sequence number
constitute the file identification number used
by the system. This number is different each
time a header is reused.

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.

File owner
information

This word contains the group number and owner
number constituting the User Identification
F-3

FILE HEADER BLOCK FORMAT
Code (UIC) for the file.
Legal UICs are within
the range
[1,1]
to
[377,377]. UIC [1,1] is
reserved for the system.
File protection code

This word specifies the manner in which the
file can be used and who can use it. When
creating the file, you specify the extent of
protection desired for the file.

File characteristics

This word, consisting of two bytes, defines the
status of the file.
Byte 0 defines the user-controlled characteristics, as follows:
UC.CON = 200 - Logically contiguous
file.
When the file is extended (for example, by a
WRITE$ or PUT$ macro), bit UC.CON is cleared
whether
or
not the extension requests
contiguous blocks.
UC.DLK

100 - File improperly closed.

Byte
1
defines
characteristics, as follows:

= 200
SC.BAD = 100
SC.MDL

User file
attributes

F.2

system-controlled

File marked for delete
Bad data block in file

This area consists of 16 words. The first
seven words of this area are a direct image of
the first seven words of the FDB when the file
is opened. The other nine words of the record
I/O control area are not used by FCS, although
RMS does use them.

IDENTIFICATION AREA

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

file

header

block

File name

The file's creator specifies a file name of up
to nine Radix-50 characters in length. This
name is placed in the name field.
The unused
portion of the field (if any) is zero-filled.

File type

This word contains the file
format.

File version number

This word contains the file version number,
in
binary, as specified by the creator of the
file.

Revision number

This word is initialized to 0 when the file is
created;
it is incremented each time a file is
closed after being updated or modified.

Revision date

Seven bytes are used to maintain the date on
which the file was last revised. The revision
date is kept in ASCII form in the format day,
month, year
(two bytes, three bytes, and two
bytes, respectively). This date is meaningful
only if the revision number is a nonzero value.
F-4

type

Radix-50

FILE HEADER BLOCK FORMAT
Revision time

Six bytes are used to record the time at which
the file was last revised. This information is
recorded in ASCII form in the format hour,
minute, and second (two bytes each).

Creation date

The date on which the file was created is kept
in a 7-byte field having the same format as
that of the revision date (see above).

Creation time

The time of the file's creation is maintained
in a 6-byte field having the same format as
that of the revision time (see above).

Expiration date

The date on which the file becomes eligible to
be deleted is kept in a 7-byte field having the
same format as that of the revision date
(see
above). Use of .expiration-is not implemented.

F.3

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 retI'ieval pointer format used in the Files-II
shown bedow:

file

o
COUNT-1

structure

are
is

HIGH LBN

LOW

LBN
ZK-303-81

NOTE
The remaining paragraphs in this appendix apply to
RSX-llM/M-PLUS and Micro/RSX systems that support the
multiheader version of FllACP.
The map area normally has space for 102 retrieval pointers.
It can
map up to 102 discontiguous segments or up to 26112 blocks if the file
is contiguous.
If more retrieval pointers are required because the
file is too large or consists of too many discontiguous segments,
extension headers are allocated to hold additional retrieval pointers.
Extension headers are allocated within the index file. They are
identified by a file number and a file sequence as are other file
headers; however, extension file headers do not appear in any
directory.

F-5

FILE HEADER BLOCK FORMAT
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 numbers 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 ffrst
extension was created. Extension headers are not updated when the
first header of the file is modified.
Extension headers are created and handled by the
primitives as needed; their use is transparent to you.

F-6

file

control

APPENDIX G
SUPPORT OF ANSI MAGNETIC TAPE STANDARD

This appendix defines the ANSI magnetic tape labeling standard, which
is a level three implementation of the ANSI standard Magnetic Tape
Labels and File Structure for Information Interchange (X3.27-l978).
The exceptions are that ANSI does not support spanned records and that
DIGITAL's tape system does not
support
user-supplied
labels.
User-supplied
labels may appear on a tape~ however, they are
accessible to application programs through the unlabeled tape feature
only.

G.l

VO.LUME AND FILE LABELS

Tables G-l, G-2, G-3, and G-4 present the format of volume labels
file header labels.

G.l.l

and

'Volume Label Format
Table G-l
Volume Label Format

Field Name

Length
(in bytes)

1-3

Label identifier

VOL

Label number

5-10

Volume identifier

Volume label. Any ANSI "a"
character.
An "a" character
is defined
by
the
ANSI
standard
as
any
of the
uppercase letters A through
Z, the digits 0 through 9,
and the following
special
characters: space! "% & '
() * + , - • / : ~ <=) ?

Accessibility

Any ANSI "a" character.
A
space
indicates
no
restriction.
You can specify
the "a" character with the

Character
Position

Contents

(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
/VOLUME ACCESSABILITY:"c"
qualifier
in
the
DCL
INITIALIZE
commands.
A~y
ANSI
"a"
character
IS
allowed.
The
default
character
is a space.
Refer
to the RSX-llM/M-PLUS
MCR
Operations
Manual
or
RSX-llM/M-PLUS
Command
Language
Manual
for more
information on INITIALIZE.

12-37

Reserved

Spaces

38-51

Owner
ide n t i f ic at ion

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
Fie~d - 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)

A numeric 1 (position 51)

The system
sequence:

identification

consists

the

following

character

D%x
x

The machine code, which can be one of the following:
8 A B F -

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

The D%x characters provide an identification method so that the
remaining data
in the owner identification field can be interpreted.
The /OWNER switch to the MCR INI command allows you to overwrite these
characters.
The /OWNER="owner" qualifier to the DCL INITIALIZE
command allows you to overwrite these characters.
(Refer to the

G-2

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
RSX-llM/M-PLUS MCR Operations Manual and the RSX-llM/M-PLUS Command
Language Manual for more information.) In the case of tapes produced
on POP-Il systems, the default system identification is O%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

Class

41
42
43
44

System (UIC no greater than [7,255])
Owner (group and member numbers match)
Group (group number matches)
World (any user not i~ one of the above)

One of the following access codes can be specified for each
position:
Code

character

Privilege
No access
Read access only
Extend (append) access
Read/extend access
Total access

The UIC is specified in character positions 45 through 50. The first
three characters are the group code in decimal. The next three are
the user code in decimal.
The last character in the owner identification field is a numeric 1.
The following is an example of the owner identification field.
Owner identifier - 0%B14l0063l46l
1.

The file was created on a POP-ll.

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

The UIC is [063,146].

G.l.2

User Volume Labels

User volume labels are never
present, they are skipped.

passed

back

you.

The following information should be kept in mind
header labels:

when

creating

file

G.l.3

written

File Header Labels

•

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

•

One character in the file identifier, the period (.), is fixed
by Files-ll.

G-3

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
•

A maximum of 13 of the 17 bytes in
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 non-DIGITAL systems,
the conventions listed above should be followed.
If they are
not, refer to Section G.l.3.1.

Tables G-2, G-3, and G-4 describe the HDRl,
respectively.

the

file

HDR2,

identifier

and

HDR3

are

labels,

Table G-2
File Header Label (HDRl)
Character
Position

Field Name

Length
(in bytes)

1-3

Label identifier

HDR

Label number

5-21

File identifier

Any ANSI "a" character.
Table G-l.

22-27

File set
identifier

Volume
identifier
first volume in the
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 fi Ie.

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

48-53

Expiration date

Same format
date.

Accessibility

Space.

55-60

Block count

000000

Contents

See

of the
set of

indicates space)
or
00000 if no date.
as

creation

(Continued on next page)

G-4

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
Table G-2 (Cont.)
File Header Label (HDRl)
Character
Position
61-73

Length
(in bytes)

Field Name
System code

Contents

The
three
letters
DEC,
followed by the name of the
system that produced
the
volume.
See
Section
G.l.l.l.
Examples:

DECFILEllA
DECSYSTEMlO

Pad name with spaces.
74-80

Reserved

Spaces.

Table G-3
File Header Label (HDR2)
Character
Position

Field Name

Length
(in bytes)

1-3

Label identifier

HDR

Label number

Record format

F D S U -

6-10

Block length

Numeric characters.

11-15

Record length

Numeric characters.

16-50

System-dependent
information

Positions 16 through 36 are
spaces.

Contents

Fixed length
Variable length
Spanned
Undefined

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.
(Continued on next page)

G-5

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
Table G-3 (Cont.)
File Header Label (HDR2)
Character
Position

Field Name

Length
(in bytes)

Contents
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.
Supported only on input to
Files-II.

53-80

Reserved

Spaces.

Table G-4
File Header Label (HDR3)
Character
Position

Field Name

Length
(in bytes)

1-3

Label identifier

HDR

Label number

5-68

System-dependent

Contents

File attributes specified at
creation time.
Each of the
" 32 bytes of user file
attributes is expanded into
two hexadecimal characters.
The first seven words of this
area are a direct image of
the first seven words of the
FOB when the file is opened.
These are the same words in
the file attribute section of
the
File Descriptor Block
given in Appendix A.
The
other nine words are not used
by FCS though they are used
by RMS.
The following list translates
the user file attribute bytes
to
the
corresponding
hexadecimal character pair.
(Continued on next page)

G-6

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
Table G-4 (Cont.)
File Header Label (HDR3)
Character
Position

Field Name

Length
(in bytes)

Contents
Byte

Pair

2
3

3
2

1
8

5
6

7
8
9
10
11
12
13
14
15
16

7
6
5
12
11
10
9
16
15
14
13

Byte
17
18
19
20
21
22

Pair
20
19
18
17
24

22
21
28
27
26
25

24
25
26
27
28
29
30
31
32

31
30
29

Using the list,
the eighth
hexadecimal character pair 1S
the expansion of the fifth
user file attribute byte, and
the
fourth
user
file
attribute byte is expanded
into the first hexadecimal
character
pair.
The
hexadecimal
pair
is
the
normal representation of the
contents of the byte;
that
is,
if the byte contains a
15.,
the
hexadecimal
representation of it is OF.
69-80

Reserved

Spaces.

G.1.3.1 File Identifier Processing by Files-ll - The magnetic tape
ACP processes Fi1es-11 type file identifiers as described below.
However, if the file name is enclosed in quotes, it is processed as an
ANSI file name, all "a" characters are legal, all 17 positions may be
used, and the only conversion that takes place is making all lowercase
characters into uppercase characters and converting all characters
that are not "a" characters to question marks.
At file input, the file identifier is handled as follows:
1.

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

G-7

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
2.

If the period is encountered, the next three characters after
the period are converted and treated as the file type.
If a
failure occurs or all nine characters are converted, the next
character is examined for a period.
If it is a period, it is
skipped and the next three characters are converted and
treated as the file type.

The version number is derived from the generation number
the generation version number as follows:

and

(generation number - 1)*100 + generation version + 1
If an invalid version number is computed, it will be
to 1.

changed

At file output, the file identifier is handled as follows:
1.

The file name is placed in the first positions in the file
identifier field.
It can occupy up to nine positions and is
followed by a period.

The file type of up to three characters is placed after
period.
The remaining positions are padded with spaces.

the

The version number is then placed in the generation
generation
version number fields,
as described in
following formulas:

and
the

Generation number =(version # - 1)+ 1

100

Generation version • =(verSion i

- 1)MOdU10 100

NOTE
In both calculations, remainders
are ignored.
The following are examples.
Files-II Version No.

Generation No.

1
50

1
1
2

49
99

100
101
1010

G.l.4

Generation version No.

End-of-Volume Labels

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

the

Character positions 1 through 3 contain EOV instead of HDR.

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

G-8

the

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
G.l.5

File Trailer Labels

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

identical

Columns 1 through 3 contain EOF instead of HDR.

The block count contains the number of
file.

G.l.6

data

blocks

file

the

User File Labels

User file labels are never written or passed back to you.
they are skipped.

G.2

with

If present,

FILE STRUCTURES

The file structures illustrated below are the types of file and volume
combinations that the file processor produces. The file processor can
read and process additional sequences.
The minimum block size and fixed-length record size is 18 bytes.
The
maximum block size is 8192 bytes.
FCS adapts to input files of
varying block size.
If HDR2 is not present, the data type is assumed to be fixed (F), and
the blclck size and record size are assumed to be the default value for
the file processor. 512 decimal bytes is the default for both block
and record size. You can override these block and record sizes with
the MAG command (see Section G.5), and MOUNT command. The MAG command
controls block and record size on unlabeled tapes and on ANSI level 1
and 2 tapes.
The meaning of the symbols used in the file structure illustrations is
as follows:

G.2.l

The asterisk (*) indicates a tape mark. As defined by ANSI,
a tape mark is a special control block recorded on magnetic
tape to serve as a separator between files and file labels.

BOT indicates beginning of tape.

EOT indicates end of tape.

The comma (,) indicates the physical record delimiter.

Single File Single Volume
BOT,VOLl,HDRl,HDR2,HDR3*---DATA---*EOFl,EOF2,EOF3**

G.2.2

Single File Multivolume
BOT,VOLl,HDRl,HDR2,HDR3*---DATA---*EOVl,EOV2,EOV3**
BOT,VOLI,HDRl,HDR2,HDR3*---DATA---*EOFl,EOF2,EOF3**

G-9

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

G.2.3

Multifile Single Volume
BOT,VOLl,HDRl,HDR2,HDR3*---DATA---*EOFl,EOF2,EOF3*HDRl,HDR2,HDR3*---DATA
--*EOFl,EOF2,EOF3**

G.2.4

Multifile Multivolume
BOT,VOLl,HDRl,HDR2,HDR3*--DATA--*EOFl,EOF2,EOF3*HDRl,HDR2,HDR3*--DATA--*
EOVl,EOV2**
BOT,VOLl,HDRl,HDR2,HDR3*--DATA--*EOFl,EOF2,EOF3*HDRl,HDR2,HDR3*--DATA--*
EOFl,EOF2,EOF3**

G.3

END-OF-TAPE HANDLING

End-of-tape is handled 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 (FCB 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-lO

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

H.MPOF

,.,

MAP OFFSET

IDENT OFFSET

FILE SEQUENCE NUMBER

H.FNUM

FILE SECTION NUMBER

H.FSEQ

STRUCTURE LEVEL = 401(8)

H.FLEV

UIC (FOR VOLUME)
HEADER AREA

H.IDOF

H.FOWN=H.PROG

PROTECTION CODE (FOR VOLUME)

H.FPRO

H.UFAT

RECORD ATTRIBUTES

RECORD TYPE CODE

RECORD SIZE IN BYTES

N WORDS OF ZERO'S

....

IDENTIFICA·
TION AREA

MAP AREA

(

FI LE NAME RAD50

X+I.FNAM
(lDENT OFFSET "2)-X

FILE 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)
ZK-315-81

Figure G-l

G.S

ANSI Magnetic Tape File Header Block (FCS Compatible)

THE MAGNETIC TAPE CONTROL TASK

The Magnetic Tape Control Task
(MAG)
allows you to specify file
attributes for unlabeled tapes, provides positioning functions for
both unlabeled and ANSI tapes, and allows you to respond to requests
for new tapes or volumes without mounting a new tape.
This command can only be used on mounted tapes.
The keywords
valid for both unlabeled and ANSI tapes, unless otherwise noted.
The fo:r:mat of the MAG command is as follows:
>l~AG

SET mmnn :/keyword [/keyword [s]]

G-ll

are

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
mmnn:
Magnetic tape unit on which the operation is to be performed.
Keywords:
/BS=number-of-bytes
/CC=NONE
LIST
FORTRAN
/EOF
/EOT
/EOV
/INITIALIZE="vo1ume id"
/POS=number-of-fi1es
/RS=number-of-characters
/REWIND
Keyword definitions:
BS

/BS=number-of-bytes. Number of
per block on a mounted tape.
number of characters in either
To specify a decimal number,
period. The default is octal.

characters
(bytes)
You can specify the
decimal or octal.
terminate it with a

This block size becomes the default for the tape.
FCS uses this value on output when there is no HDR2
label present on an ANSI magnetic tape, and when no
other value was specified on creation of the file.
FCS reads the file attributes to obtain the block
size when opening an existing file on ANSI magnetic
tape.
The value specified for block size must be greater
than 14 (decimal) bytes. There is no maximum block
size. FCS pads a block on ANSI magnetic tape to an
even length to permit PUT$ operations with odd
fixed-length records.
CC

/CC=type of
/CC=NONE.

carriage

control.

The

default

Valid types of carriage control are as follows:
NONE
LIST
FORTRAN

G-12

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
When reading from an
carriage control if:

ANSI

FCS

•

No HDR2 label is present.

•

The HDR2 label contains a system
other than DEC or OS.

If a HDR2
information
keyword.

uses

this

identification

label is present,
FCS
uses
the
in the HDR2 label and ignores the ICC

This keyword is the only way
control for unlabeled tapes.
EOH'

tape,

specify

carriage

/EOF. Causes the ACP to return the I/O status code
IE.EOF to the requesting task. You can use this
keyword to terminate a request for another tape in
a volume set.
This keyword is only valid for ANSI tapes.

Eo~r

/EOT. Causes the ACP to return the I/O status code
IE.EOT to the requesting task. You can use this
keyword to terminate a request for another tape in
a volume set.
This keyword is only valid for ANSI tapes.

EOV

/EOV. Causes the ACP to return the I/O status code
IE.EOV to the requesting task. You can use this
keyword to terminate a request for another tape in
a volume set.
This keyword is only valid for ANSI tapes.

INITIALIZE

/INITIALIZE=tlvolume id tl • The volume label to which
the tape will be initialized. This keyword allows
you to create a new volume to satisfy a request
from the ACP for a new output volume for an ANSI
tape. The format of the volume identifier is
identical to the format of the volume identifier
specified for the MOUNT command.
Refer to the
INITIALIZE command in the RSX-llM/M-PLUS Command
Langua~e
Manual
or
the
RSX-IIM/M-PLUS
MeR
OperatIons Manual for details.
This keyword is only valid for ANSI tapes.

POS

/POS=number-of-files. The number of files
(tape
marks)
to be spaced over from the current tape
position. For example, /POS=O means access the
current file;
/POS=l means space.forward one file
from the current position. The number of files may
be specified in either decimal or octal.
To
specify a decimal number, terminate the number with
a period. The default is octal.
The number of files specified must be between 0 and
234l7{octal).

G-l3

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
This keyword is only valid for mounted unlabeled
tapes.
This keyword is not necessary for labeled
tapes, because files can be accessed by name.
If a tape containing ANSI or IBM labels is mounted
as unlabeled, the formula to calculate the position
of a data file is:
N= (N-l)*3+1
where N is the number of the desired file.
/RS=number-of-characters. The number of characters
per record for fixed-length records on tape.

Maximum record size is the block size.
When reading files from an ANSI tape, FCS uses this
value for record size when no HDR2 label is
present.
This keyword is the only way to specify record size
for unlabeled tapes.
REWIND

G.S.l

/REWIND. Specifies that the tape is to be rewound
to BOT.
For ANSI tapes, this keyword rewinds to
the beginning of the volume set.

MAG Command Example
>MOU MMO:/NOLABEL/TR=EBCDIC
>MAG SET MMO:/BS=80./RS=80./CC=LIST/REWIND
>1 Read the first "file" on the tape to determine the actual tape format
>PIP TI:=MMO:X
VOL1X234870
HDR1DEC2.KP72132
X2348700010001
HDR2F008000008030DEC2K009/DEC2U009
>1
>1
>1
>1
>1

NASHUA
80256 802860000000IBM OS/VS 370
60337

This information shows that the tape in fact has labels that
resemble ANSI labels (this tape is in the format of
another computer manufacturer). The actual block size and record size
can be determined from the labels.
Use the MAG SET command to set the actual block and record size.

>MAG SET MMO:/BS=800./RS=80.
>1
>1
>1
>1
>1

Use the MAG SET /POS command to position to the next file on the tape.
You could also position to the file by specifying
a position to PIP as follows: PIP TI:=MMO:"POS=R1"
where R indicates REWIND and 1 is the number of tape
marks to space over.

>MAG SET MMO:/REWIND/POS=l
>1 Read the data file. Note that PIP requires a dummy file name, even
>1 though the tape is already positioned at the correct file.
>PIP TI:=MMO:X
001
321
002
456
003
789
004
124
005
345

03054
03060
02165
01845
64801

MERRIMACK
NASHUA
NEWTON
NORTH ANDOVER
JOPLIN

G-14

603
603
617
617
714

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
G.S.2

MAG Command Error Messages

MAG

Device not mounted or mounted foreign
Explanation: Specified device must be either a mounted ANSI tape
or a mounted unlabeled tape.
A foreign tape that is mounted
foreign is not known to the magnetic tape ACP and is therefore
the same as an unmounted tape. The MAG command only supports
mounted tapes.
User Action: Mount the device with the INOLASEL qualifier if it
is an unlabeled tape. Do not use the MAG command with tapes that
are mounted foreign.

MAG -- Get command line failure
Explanation: An illegal indirect command file name was specified
or MAG could not find the specified indirect command file.
User Action: Check the specification for
file and reenter the command line.

the

indirect

command

that

required

both

MAG -- Illegal combination of keywords
Explanation: Keywords were specified
unlabeled tape and an ANSI tape.

User Action: Refer to the keyword descriptions in this chapter
to determine which switches require ANSI tapes and which require
unlabeled tapes.
MAG -- Illegal file attributes combination
Explanation: A record size was specified that was not less
or equal to the block size.

than

User Action:
block size.

the

retype

the

Specify a record size less than

equal

MAG -- Illegal switch value
Explanation:

One of the following:

•

IpOS value was greater than 9999.

•

ISS value was less than 14.

•

IRS value was less than 14.

User Action: Determine which value was illegal
command line.

and

MAG -- Invalid device or unit
Explanation: Specified
magnetic tape.

device

does

not

exist

not

User Action: Determine the correct device or unit and retype the
command line.
MAG -- Operation is only valid for mounted ANSI tapes
Explanation: An operation that is only valid for
tape was attempted on an unlabeled tape.
User Action:

Use only valid commands.
G-lS

ANSI

magnetic

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
MAG -- Operation is only valid for unlabeled tapes
Explanation: An operation that is only valid for unlabeled tapes
was attempted on an ANSI tape.
User Action:

Use only valid commands.

MAG -- Privilege violation
Explanation: On systems with multiuser protection, only the
terminal to which the tape drive is allocated may change the tape
characteristics.
User Action:
tape drive.

Reenter the command from the terminal that owns the

MAG -- Requested operation inconsistent with tape state
Explanation: The user specified /EOF,
magnetic tape ACP rejected it.

/EOV,

/EOT

and

the

type

only

this

or
The user specified /INITIALIZE' and the ACP rejected it.
User Action: Determine the state of the tape and
commands that can be performed in the current state.
MAG -- Syntax error
Explanation:

The command was specified incorrectly.

User Action: Check the correct syntax as
chapter, and then reenter the command line.

G.6

described

UNLABELED TAPE

A tape that contains no labeling information is called an unlabeled
tape.
An unlabeled tape contains either blocked or unblocked
fixed-length records. When a tape is mounted with the /NOLABEL
qualifier on the MOUNT command, FCS and RMS can access records on the
tape using standard read and write operations. This is different from
mounting a tape foreign (MOU/FOREIGN). When a tape is mounted foreign
(or not mounted at all on RSX-IIM systems), records on the tape must
be accessed directly using the QIO$ operations that are defined for
the magnetic tape driver.

G.6.1

Block Size on Tapes Mounted /NOLABEL

Under certain conditions, if a file is written to a tape, its block
size will be even and one more than the value specified in the MOUNT
command. The conditions where this occurs are as follows:
•

The tape is mounted /NOLABEL.

•

The mount command specifies an odd record size.

•

The mount command specifies an odd block size.

G-16

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
FCS adds the padding character, an octal 136 circumflex
(A), to
odd-sized byte blocks because of a hardware restriction; some tape
drives will not allow an odd number of bytes to be transferred to or
from tape.
Therefore, blocks of data are padded with the circumflex
character so that even blocks of data can be written to tape on any
tape drive.

G.6.2

Tape Positioning

Any tape motion before the first read operation
requested in one of the following ways:

must

explicitly

•

The FA.ENB!FA.RWD bit may be set in F.ACTL to request a rewind
of the volume set prior to create or find-file operations.

•

The MAG SET /POS command may be specified to space
specified number of files from 0 to 9999.

forward

•

The MAG SET /REWIND command may be
tape to BOT.

rewind

•

The file may be referenced by the name "POS=[R] [nnnn]" where R
indicates that the tape is to be rewound, and nnnn is the
number of files (tape marks) to space forward.
For example,
to read the second file on a tape:

specified

a
the

)PIP TI:=MM:"POS=OOOl"
Each tape mark delimits a file.
All positioning operations are in
terms of tape marks.
If any type of label is present on the tape, it
will be treated as a file.
When a file
consistent.

G.6.3

deaccessed,

position

within

the

file

always

Specifying File Attributes

You can specify the attributes for files to be read from tape in three
ways:

G.6.4

The MOUNT command
(see the- RSX-llM/M-PLUS MCR Operations
Manual or the RSX-llM/M-PLUS Command Language Manual).

Any create operation request.
You can issue the create
request from within your program by creating a file and
closing it without writing any data, or by using the RMS
DEFINE utility.
The FCS Create routine returns the error
code IE.BTP (bad record type) if an attempt is made to set
the record type to anything other than fixed length.

The MAG SET command (see Section G.5).

Tape Translation

You can request translation for a tape when you mount it with the
MOUNT command
(see the RSX-llM/M-PLUS MCR o¥erations Manual or the
RSX-llM/M-PLUS Command Language Manual)-.-- I
you have requested
translation, your data buffer
(the FCS or RMS block buffer) is
translated within your task. Therefore, on a write operation,
the
data in your task is destroyed.
G-17

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
You can add up to three installation-dependent translation routines to
the magnetic tape ACP by adding routines with the following format:
USERn:: MOV #TBLPTR,RO
;n is 1, 2, or 3.
RETURN
TBLPTR: .WORD INTRAN
.WORD OUTRAN
INTRAN: (A 256 byte table for input translation>
OUTRAN: (A 256 byte table for output translation>
An example of the EBCDIC translabion tables
your system is shown in Section G.6.5.

that

are

provided

with

You must include these translation' routines in the Overlay Description
Language
(ODL)
for the magnetic tape ACP when the MTAACP task is
built. Comments within the files MTABLD.ODL and MTABLD.CMD indicate
where these routines may be added.

G.6.5

Example of EBCDIC Translation Tables
EBCDIC::

MOV
RETURN

TBLPTR: .WORD
.WORD

EBCASC
ASCEBC

#TBLPTR,RO

.NLIST BEX
;

EBCASC:

ASCEBC:

.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
• BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
• BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE

041,044,052,051,073,136,055,057,040,040
040,040,040,040,040,040,174,054,045,137
076,077,137,040,040,040,040,040,040,040
040,140,072,043,100,047,075,042,040,141
142,143,144,145,146,147,150,151,040,040
040,040,040,040,040,152,153,154,155,156
157,160,161,162,040,040,040,040,040,040
040,176,163,164,165,166,167,170,171,172
040,040,040,040,040,040,040,040,040,040
040,040,040,040,040,040,040,040,040,040
040,040,173,101,102,103,104,105,106,107
110,111,040,040,040,040,040,040,175,112
113,114,115,116,117,120,121,122,040,040
040,040,040,040,134,040,123,124,125,126
127,130,131,132,040,040,040,040,040,040
060,061,062,063,064,065,066,067,070,071
040,040,040,040,040,040

.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE

000,001,002,003,040,011,040,177,040,040
040,013,014,015,016,017,020,021,022,023
040,040,010,040,030,031,040,040,040,035
040,037,040,040,034,040,040,012,027,033
040,040,040,040,040,005,006,007,040,040
026,040,040,036,040,004,040,040,040,040
024,025,040,032,040,040,040,040,040,040
040,040,040,040,133,056,074,050,053,135

50.

046,040,040,040,040,040,04~,040,040,040

G-1S

100 •

150.

200 •

250.

SUPPORT OF ANSI MAGNETIC TAPE STANDARD

G.7

.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE

370,371,172,136,114,176,156,157
174,301,302,303,304,305,306,307
310,311,321,322,323,324,325,326
327,330,331,342,343,344,345,346
347,350,351,112,340,117,137,155
171,201,202,203,204,205,206,207
210,211,221,222,223,224,225,226
227,230,231,242,243,244,245,246
247,250,251,300,152,320,241,007

.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
.BYTE

000,001,002,003,067,055,056,057
026,005,045,013,014,015,016,017
020,021,022,023,074,075,062,046
030,031,077,047,042,035,065,037
100,132,177,173,133,154,120,175
115,135,134,116,153,140,113,141
360,361,362,363,364,365,366,367
370,371,172,136,114,176,156,157
174,301,302,303,304,305,306,307
310,311,321,322,323,324,325,326
327,330,331,342,343,344,345,346
347,350,351,112,340,117,137,155
171,201,202,203,204,205,206,207
210,211,221,222,223,224,225,226
227,230,231,242,243,244,245,246
247,250,251,300,152,320,241,007

100

140

200

240

300

EXAMPLE USING AN INDIRECT COMMAND FILE TO READ A TAPE
• E:NABLE QU I ET
.ENABLE SUBSTITUTION
., This command file is invoked with the command

@MTA outspec=Mx:infile
·.,, and searches
a tape mounted unlabeled (which has an ANSI-like structure)
., for the file "infile" and copies it to outspec.
·.,, Parse the command line; OUTSPC gets outspec,
.,
.,

DEV
gets Mx,
INFILE gets the file name to find on tape •

• PARSE COMMAN " " OUTSPC COMMAN
.PARSE COMMAN "=" OUTSPC INSPEC
.PARSE INSPEC ":" DEV INFILE
.IF INFILE EQ "" .GOTO NOTMT
.SETS INFILE INFILE+"
.SETS INFILE INFILE[l:l7.]
.SETS JUNK DEV[l:l]
.IF JUNK NE "M" .GOTO NOTMT

·.;, Make a name for the temp file.
·,
.'I'ESTFILE TI:
.PARSE <FILSPC> ":" TMP JUNK
.SETS TMP TMP+".TMP"

·,

.; Always start at the beginning of the tape.

G-19

SUPPORT OF ANSI MAGNETIC TAPE STANDARD
HAG SET 'DEV':/REWIND
• i

.i Labels have a block and record size of 80.

HAG SET 'DEV':/BS:80./RS:80 •
• LOOK:

·.i, Put the labels in a temp file so Indirect can look at them
PIP 'THP'='DEV':DUMHY.NAH
.OPENR 'TMP'
.READLB:
.READ LABEL
.IFT <EOF> .GOTO NOSUCH
.SETS LABELT LABEL[l:3]
•i

.i Skip any Volume header labels

.IF LABELT = "VOL" .GOTO READLB
.IF LABELT NE "HDR" .GOTO ILLFHT
.SETS LABELT LABEL[4:4]
.IF LABELT NE "1" .GOTO ILLFHT
.SETS LABELT LABEL[S:2l.]
•i

.i If the names do not match, go get the next set of labels •

• IF LABELT NE INFILE .GOTO TRYNXT
•i

.i We have found the file, see if there is a HDR2 with size info •

• READ LABEL
.IFT <EOF> .GOTO READFL
.SETS LABELT LABEL[1:4]
.IF LABELT NE "HDR2" .GOTO READFL
•i

., Yes, we have a HDR2 label •

• SETS LABELT LABEL[37.:37.]
.SETS CC "LI"
.IF LABELT = "A" .SETS CC "FO"
.IF LABELT = "H" .SETS CC "NO"
.SETS BS LABEL[6:l0.]
.SETS RS LABEL[ll.:lS.]
•i
.i Set up the block size, record size, and carriage control
.i based on what was in HDR2.

MAG SET 'DEV' :/BS: 'BS' ./RS: 'RS' ./CC: ICC'
.SETS LABELT LABEL[S:S]
.IF LABELT EQ "F" .GOTO READFL
.DISABLE QUIET
IMTA - Warning, Record Format is 'LABELT'; only F Format is fully supported •
• ENABLE QUIET
.READFL:
.CLOSE

G-20

SUPPORT OF ANSI MAGNETIC TAPS S~ANDARD

..,, Transfer the file.
PI P 'OUTSPC'·' DEV' : "POS-l"
.GOTO ENDIT
.TRYNXT:
.CLOSE
MAG SET 'DEV':/POS=3
.GOTO LOOK
.ILLFMT:
.DISABLE QUIET
.DISABLE MCR
MTA - Tape is not in a format that I understand •
• GOTO ENDIT
.NOTMT:
.DISABLE QUIET
.DISABLE MCR
MTA - Input file spec must specify a magnetic tape device and a file name •
• EXIT
.NOSUCH:
.DISABLE QUIET
.DISABLE MCR
MTA - No such file -- 'INSPEC'
.ENDIT:
.ENABLE MCR
.ENABLE QUIET
PIP 'TMP'; /DE/NM
.EXIT
-

G-21

APPENDIX H
STATISTICS BLOCK

The format of the statistics block is shown in Figure H-1 below.
The
statistics block is allocated manually in your program as described in
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

SIZE (high)

Word 3

Word 4

SIZE (low)

LOCK COUNT

ACCESS COUNT
ZK-304-81

Figure H-1

Statistics Block Format

H-1

APPENDIX I
ERROR CODES

This appendix includes the code for:
•

I/O ~rror codes

•

Directive Status Word error codes

•

I/O function codes
.TITLE

QIOMAC - QIOSYM MACRO DEFINITION

DATE OF LAST MODIFICATION:
John R. Covert

16-Nov-1984

***** ALWAYS UPDATE THE FOLLOWING TWO LINES TOGETHER
.IDENT
QI.VER=0375

/0375/

COPYRIGHT (C) 1983, 1984
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A
SING!LE COMPUTER SYSTEM AND MAY BE COPIED
ONLY WITH THE
INCLOSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE
MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN
IN DEC.
THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC.
PETER H. LIPMAN 1-0CT-73
i

MACRO TO DEFINE STANDARD QUEUE I/O DIRECTIVE FUNCTION VALUES
AND IOSB RETURN VALUES. TO INVOKE AT ASSEMBLY TIME (WITH LOCAL
DEFINITION) USE:
QIOSY$

iDEFINE SYMBOLS

I-I

ERROR CODES
TO OBTAIN GLOBAL DEFINITION OF THESE SYMBOLS USE:
QIOSY$ DEF$G

;SYMBOLS DEFINED GLOBALLY

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

;.MACRO QIOSY$ $$$GBL,$$$MSG
.IIF
IDN,<$$$GBL>,<DEF$G>, • GLOBL Qr. VER
.IF
IDN,<$$$MSG>,<DEF$S>
$$$MAX=O
$$MSG=l
.IFF
$$MSG=O
.ENDC
.MCALL
IOERR$
IOERR$
;1/0 ERROR CODES FROM HANDLERS, FCP, FCS
$$$GBL
DRERR$
.MCALL
DRERR$
;DIRECTIVE STATUS WORD ERROR CODES
$$$GBL
DIF,<$$$MSG>,<DEF$S>
.IF
.MCALL
FILIO$
FILIO$
;DEFINE GENERAL I/O FUNCTION CODES
$$$GBL
SPCIO$
.MCALL
SPCIO$
$$$GBL
;DEVICE-DEPENDENT I/O FUNCTION CODES
ARG,ARG1,ARG2
;RECLAIM MACRO STORAGE
.MACRO
QIOSY$
.ENDM
QIOSY$
.ENDC
.ENDM
QIOSY$
DEFINE THE ERROR CODES RETURNED BY DEVICE HANDLER AND FILE PRIMITIVES
IN THE FIRST WORD OF THE I/O STATUS BLOCK
THESE CODES ARE ALSO RETURNED BY FILE CONTROL SERVICES (FCS) IN THE
BYTE F.ERR IN THE FILE DESCRIPTOR BLOCK (FOB)
THE BYTE F.ERR+l IS 0 IF F.ERR CONTAINS A HANDLER OR FCP ERROR CODE.
.ENABL
. MACRO
.MCALL
.IF
••• GBL=l
.IFF
.•• GBL=O
.ENDC
.lIF

LC
IOERR$
$$$GBL .IOER.,DEFIN$
IDN,<$$$GBL>,<DEF$G>

NDF,$$MSG,$$MSG=O

SYSTEM STANDARD CODES, USED BY EXECUTIVE AND DRIVERS
.lOER.
.lOER.
.lOER.
.IOER.
.lOER.
.lOER.
.lOER.
.lOER.
.lOER.
.lOER.
.IOER.

lE.BAD,-Ol.,<Bad parameters>
lE.lFC,-02.,<lnvalid function code>
lE.DNR,-03.,<Device not ready>
lE.VER,-04.,<parity error on device>
lE.ONP,-OS.,<Hardware option not present>
lE.SPC,-06.,<lllegal user buffer>
lE.DNA,-07.,<Device not attached>
lE.DAA,-08.,<Device already attached>
lE.DUN,-09.,<Device not attachable>
lE.EOF,-lO.,<End of file detected>
IE.EOV,-ll.,<End of volume detected>

I-2

ERROR CODES
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.

IE.WLK,-12.,<Write attempted to locked unit>
IE.DAO,-13.,<Data overrun>
IE.SRE,-14.,<Send/receive failure>
IE.ABO,-lS.,<Request terminated>
IE.PRI,-16.,<Privilege violation>
IE.RSU,-17.,<Shareable resource in use>
IE.OVR,-18.,<111egal overlay request>
IE.BYT,-19.,<Odd byte count (or virtual address»
IE.BLK,-20.,<Logical block number too large>
IE.MOD,-2l.,<lnvalid UpC module #>
IE.CON,-22.,<UDC connect error>
IE.BBE,-S6.,<Bad bloc~ on device>
IE.STK,-S8.,<Not enough stack space (FCS or FCP»
IE.FHE,-S9.,<Fatal hardware error on device>
IE.EOT,-62.,<End of tape detected>
IE.OFL,-6S.,<Device off line>
IE.BCC,-66.,<Block check, CRC, or framing error>
IE.NFW,-69.,<Path lost to partner> iTHIS CODE MUST BE ODD
IE.DIS,-69.,<Path lost to partner> iDISCONNECTED (SAME AS NFW)
IE.PNT,-7l.,<Partition/Region not in system>
IE.NDR,-72.,<No dynamic space available> i SEE ALSO IE.UPN
IE.TMO,-9S.,<Timeout on request>
see also IS.TMO
IE.CNR,-96.,<Connection rejected>
IE.MII,-99.,<Media inserted incorrectly>
IE.SPI,-lOO.,<Spindown ignored>

FILE PRIMITIVE CODES
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IO&R.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.

IE.NOD,-23.,<Caller's nodes exhausted>
IE.DFU,-24.,<Device full>
IE.IFU,-2S.,<lndex file full>
IE.NSF,-26.,<No such file>
IE.LCK,-27.,<Locked from read/write access>
IE.HFU,-28.,<File header full>
IE.WAC,-29.,<Accessed for write>
IE.CKS,-30.,<File header checksum failure>
IE.WAT,-3l.,<Attribute control list format error>
IE.RER,-32.,<File processor device read error>
IE.WER,-33.,<File processor device write error>
IE.ALN,-34.,<File already accessed on LUN>
IE.SNC,-3S.,<File ID, file number check>
IE.SQC,-36.,<File ID, sequence number check>
IE.NLN,-37.,<No file accessed on LUN>
IE.CLO,-38.,<File was not properly closed>
IE.DUP,-S7.,<ENTER - duplicate entry in directory>
IE.BVR,-63.,<Bad version number>
IE.BHD,-64.,<Bad file header>
IE.EXP,-7S.,<File expiration date not reached>
IE.BTF,-76.,<Bad tape format>
IE.ALC,-84.,<Allocation failure>
IE.ULK,-8S.,<Unlock error>
IE.WCK,-86.,<Write check failure>
IE.DSQ,-90.,<Disk quota exceeded>

FILE CONTROL SERVICES CODES
.IOER.
.IOER.
.IOER.
.IOER.

IE.NBF,-39.,<OPEN - no buffer space available for file>
IE.RBG,-40.,<111egal record size>
IE.NBK,-4l.,<File exceeds space allocated, no blocks>
IE.ILL,-42.,<111egal operation on file descriptor block>

1-3

ERROR CODES

.IOER •
• IOER.
.IOER •
• IOER.
.IOER •
• IOER.
.IOER •
• IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.

IE.BTP,-43.,<Bad record type>
IE.RAC,-44.,<Illegal record access bits set>
IE.RAT,-45.,<Illegal record attributes bits set>
IE.RCN,-46.,<Illegal record number - too large>
IE.2DV,-48.,<Rename - 2 different devices>
IE.FEX,-49.,<Rename - new file name already in use>
IE.BDR,-50.,<Bad directory file>
IE.RNM,-51.,<Can't rename old file system>
IE.BDI,-52.,<Bad directory syntax>
IE.FOP,-53.,<File already open>
IE.BNM,-54.,<Bad file name>
IE.BDV,-55.,<Bad device name>
IE.NFI,-60.,<File ID was not specified>
IE.ISQ,-61.,<Illegal sequential operation>
IE.NNC,-77.,<Not ANSI 'D' format byte count>

NETWORK ACP, PSI, AND DECDATAWAY CODES
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.
.IOER.

IE.NNN,-68.,<No such node>
IE.BLB,-70.,<Bad logical buffer>
IE.URJ,-73.,<Connection rejected by user>
IE.NRJ,-74.,<Connection rejected by network>
IE.NDA,-78.,<No data available>
IE.IQU,-91.,<Inconsistent qualifier usage>
IE.RES,-92.,<Circuit reset during operation>
IE.TML,-93.,<Too many links to task>
IE.NNT,-94.,<Not a network task>
IE.UKN,-97.,<Unknown name>

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

IE.NLK,-79.,<Task not linked to specified ICS/ICR interrupts>
IE.NST,-80.,<Specified task not installed>
IE.FLN,-8l.,<Device offline when offline request was issued>

TTY ERROR CODES
.IOER.
.IOER.

IE.IES,-82.,<Invalid escape sequence>
IE.PES,-83.,<Partial escape sequence>

RECONFIGURATION CODES
.IOER.
.IOER.
.IOER.

IE.ICE,-47.,<Internal consistancy error>
IE.ONL,-67.,<Device online>
IE.SZE,-98.,<Unable to size device>

PCL ERROR CODES
.IOER.
.IOER.
.IOER.

IE.NTR,-87.,<Task not triggered>
IE.REJ,-88.,<Transfer rejected by receiving CPU)
IE.FLG,-89.,<Event flag already specified)

I-4

ERROR CODES

SUCCESSFUL RETURN CODES--DEFIN$
DEFIN$
DEFIN$

IS.PND,+OO.
IS. SUC, +01.
IS.RDD,+02.

DEFIN$

IS.TNC,+02.

D1E:FIN$

IS.CHW,+04.

D1E:FIN$

IS.BV,+OS.

D:E:FIN$

IS.DAO,+02.

;OPERATION PENDING
;OPERATION COMPLETE, SUCCESS
;FLOPPY DISK SUCCESSFUL COMPLETION
;OF A READ PHYSICAL, AND DELETED
;DATA MARK WAS SEEN IN SECTOR HEADER
; (PCL) SUCCESSFUL TRANSFER BUT MESSAGE
;TRUNCATED (RECEIVE BUFFER TOO SMALL).
; "(IBM COMM) DATA READ WAS RESULT OF
;IBM HOST CHAINED WRITE OPERATION
; (AID READ) AT LEAST ONE BAD VALUE
;WAS READ (REMAINDER MAY BE GOOD).
;BAD CHANNEL IS INDICATED BY A
;NEGATIVE VALUE IN THE BUFFER.
;SUCCESSFUL BUT WITH DATA OVERRUN
; (NOT TO BE CONFUSED WITH IE.DAO)

TTY SUCCESS CODES
D:EFIN$
DEFIN$
DEFIN$
DEFIN$
DEFIN$
DEFIN$
DEFIN$
DEFIN$
DEFIN$
DEFIN$

IS.CR,<lS*400+l>
IS.ESC,<33*400+l>
IS.CC,<3*400+l>
IS.ESQ,<233*400+l>
IS.PES,<200*400+l>
IS.EOT,<4*400+l>
IS.TAB,<11*400+l>
IS.TMO,+2.
IS.OOB,+3.
IS.TMM,+4.

;CARRIAGE RETURN WAS TERMINATOR
;ESCAPE (ALTMODE) WAS TERMINATOR
;CONTROL-C WAS TERMINATOR
;ESCAPE SEQUENCE WAS TERMINATOR
;PARTIAL ESCAPE SEQUENCE WAS TERMINATOR
;EOT WAS TERMINATOR (BLOCK MODE INPUT)
;TAB WAS TERMINATOR (FORMS MODE INPUT)
;REQUEST TIMED OUT
;OUT OF BAND TERMINATOR (TERM IN HIGH BYTE)
;READ COMPLETED, MANAGEMENT MODE SEQ RCVD

Professional Bisync Success Codes
DEFIN$
DEFIN$
DEFIN$

IS.RVI,+2.
IS .CNV ,+3.
IS.XPT,+S.

DATA SUCC. XMITTED; HOST ACKED WIRVI
DATA SUCC. XMITTED; HOST ACKED W/CONVERSATION
DATA SUCC. RECVD IN TRANSPARENT MODE

Professional Bisync Abort Codes
These codes are returned in the high byte of the first word of the IOSB
when the low byte contains IE.ABO.
DEFIN$
DEFIN$
DEFIN$
DEFIN$
DEFIN$
DEFIN$
DEFIN$

SB.KIL,-1.
SB .ACK, -2.
SB. NAK, -3.
SB.ENQ,-4.
SB.BOF,-S.
SB.TMO,-6.
SB.DIS,-7.

ABORTED BY IO.KIL
ABORTED BECAUSE TOO MANY ACKS RECD OUT OF SEQ
ABORTED BECAUSE NAK THRESHOLD EXCEEDED
ABORTED BECAUSE ENQ THRESHOLD EXCEEDED
ABORTED BECAUSE OF IO.RLB BUFFER OVERFLOW
ABORTED BECAUSE OF TIMEOUT
ABORTED BECAUSE HOST DISCONNECTED WI OLE, EOT

******
THE NEXT AVAILABLE ERROR NUMBER IS: -101.
*****
• IF
.MACRO
.ENDM
.ENDC
.ENDM

EQ,$$MSG
IOERR$ A
IOERR$
IOERR$

I-5

ERROR CODES

DEFINE THE DIRECTIVE ERROR CODES RETURNED IN THE DIRECTIVE STATUS WORD
FILE CONTROL SERVICES (FCS) RETURNS THESE CODES IN THE BYTE F.ERR
OF THE FILE DESCRIPTOR BLOCK (FOB). TO DISTINGUISH THEM FROM THE
OVERLAPPING CODES FROM HANDLER AND FILE PRIMITIVES, THE BYTE
F.ERR+l IN THE FOB WILL BE NEGATIVE FOR A DIRECTIVE ERROR CODE.
.MACRO
.MCALL
.IF
••• GBL=l
.IFF
••• GBL=O
.ENDC
.IIF

DRERR$
$$$GBL
.QIOE.,DEFIN$
IDN,<$$$GBL>,<DEF$G>

NDF,$$MSG,$$MSG=O

STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE STATUS WORD
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.

IE.UPN,-Ol.,<Insufficient dynamic storage> ; SEE ALSO IE.NDR
IE.INS,-02.,<Specified task not installed>
IE.PTS,-03.,<Partition too small for task>
IE.UNS,-04.,<Insufficient dynamic storage for send>
IE.ULN,-05.,<Un-assigned LUN>
IE.HWR,-06.,<Device handler not resident>
IE.ACT,-07.,<Task not active>
IE.ITS,-08.,<Directive inconsistent with task state>
IE.FIX,-09.,<Task already fixed/unfixed>
IE.CKP,-lO.,<Issuing task not checkpointable>
IE.TCH,-ll.,<Task is checkpointable>
IE.RBS,-15.,<Receive buffer is too small>
IE.PRI,-16.,<Privilege violation>
IE.RSU,-17.,<Resource in use>
IE.NSW,-18.,<No swap space available>
IE.ILV,-19.,<Illegal vector specified>
IE.ITN,-20.,<Invalid table number>
IE.LNF,-2l.,<Logical name not found>

.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.
.QIOE.

IE.AST,-80.,<Directive issued/not issued from AST>
IE.MAP,-8l.,<Illegal mapping specified>
IE.IOP,-83.,<Window has I/O in progress>
IE.ALG,-84.,<Alignment error>
IE.WOV,-85.,<Address window allocation overflow>
IE.NVR,-86.,<Invalid region 10>
IE.NVW,-87.,<Invalid address window 10>
IE.ITP,-88.,<Invalid TI parameter>
IE.IBS,-89.,<Invalid send buffer size
.GT. 255.»
IE.LNL,-90.,<LUN locked in use>
IE.IUI,-91.,<Invalid UIC>
IE.IDU,-92.,<Invalid device or unit>
IE.ITI,-93.,<Invalid time parameters>
IE.PNS,-94.,<Partition/region not in system>
IE.IPR,-95.,<Invalid priority ( .GT. 250.»
IE.ILU,-96.,<Invalid LUN>
IE.IEF,-97.,<Invalid event flag ( .GT. 64.»
IE.ADP,-98.,<Part of DPB out of user's space>
IE.SDP,-99.,<DIC or DPB size invalid>

SUCCESS CODES FROM DIRECTIVES - PLACED IN THE DIRECTIVE STATUS WORD
DEFIN$

IS.CLR,O

;EVENT FLAG WAS CLEAR
iFROM CLEAR EVENT FLAG DIRECTIVE

1-6

ERROR CODES
DEFIN$

IS.SET,2

DEFIN$

IS.SPD,2

DEFIN$

IS.SUP,3

iEVENT FLAG WAS SET
iFROM SET EVENT FLAG DIRECTIVE
iTASK WAS SUSPENDED
iLOGICAL NAME SUPERSEDED
i

DEFIN$

IS.WAT,4

.IF
• MACRO
.ENDM
.ENDC
.ENDM

EQ,$$MSG
DRERR$ A
DRERR$

iOPERATION INITIATED, WAIT FOR COMPLETION
iFROM "VAX-II RSX" RMS-2I ELEP$ DIRECTIVE

DRERR$

DEFINE THE GENERAL I/O FUNCTION CODES - DEVICE INDEPENDENT
• MACRO
FILIO$ $$$GBL
• MCALL
.WORD.,DEFIN$
.IF
IDN,<$$$GBL),<DEF$G)
.IFF
••• GBL=O
.ENDC
GENERAL I/O QUALIFIER BYTE DEFINITIONS
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IQ.X,OOI,OOO
IQ.Q,002,000
IQ.S,004,000
IQ.UMD,004,000
IQ.LCK,200,000

iNO ERROR RECOVERY
iQUEUE REQUEST IN EXPRESS QUEUE
iSYNONYM FOR IQ.UMD
iUSER MODE DIAGNOSTIC STATUS REQUIRED
iMODIFY IMPLIED LOCK FUNCTION

EXPRESS QUEUE COMMANDS
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.KIL,012,000
IO.RDN,022,000
IO.UNL,042,000
IO.LTK,050,000
IO.RTK,060,000
IO.SET,030,000

iKILL CURRENT REQUEST
i I/O RUNDOWN
iUNLOAD I/O HANDLER TASK
iLOAD A TASK IMAGE FILE
iRECORD A TASK IMAGE FILE
iSET CHARACTERISTICS FUNCTION

GENERAL DEVICE DRIVER CODES
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.WLB,OOO,OOI
IO.RLB,000,002
IO.LOV,010,002
IO.LDO,110,002
IO.ATT,000,003
IO.DET,000,004

iWRITE LOGICAL BLOCK
iREAD LOGICAL BLOCK
iLOAD OVERLAY (DISK DRIVER)
iLOAD D-SPACE OVERLAY (DISK)
iATTACH A DEVICE TO A TASK
iDETACH A DEVICE FROM A TASK

DIRECTORY PRIMITIVE CODES
.WORD.
.WORD.
.WORD.

IO.FNA,OOO,OII
IO.RNA,000,013
IO.ENA,000,014

iFIND FILE NAME IN DIRECTORY
iREMOVE FILE NAME FROM DIRECTORY
iENTER FILE NAME IN DIRECTORY

FILE PRIMITIVE CODES
.WORD.
.WORD.
.WORD.
.WORD.

IO.CLN,000,007
IO.ULK,000,012
IO.ACR,000,015
IO.ACW,000,016

iCLOSE OUT LUN
i UNLOCK BLOCK
iACCESS FOR READ
iACCESS FOR WRITE

1-7

ERROR CODES
.WORD •
• WORD.
.WORD •
• WORD.
.WORD •
• WORD.
.WORD •
• WORD.
.WORD •
• WORD.
.WORD.

IO.ACE,OOO,OI7
IO.DAC,OOO,020
IO.RVB,OOO,02I
IO.WVB,OOO,022
IO.EXT,OOO,023
IO.CRE,OOO,024
IO.DEL,OOO,02S
IO.RAT,OOO,026
IO.WAT,OOO,027
IO.APV,OIO,030
IO.APC,OOO,030

.MACRO
.ENDM
.ENDM

FILIO$
FILIO$
FILIO$

iACCESS FOR EXTEND
iDE-ACCESS FILE
iR~AD VIRITUAL BLOCK
iWRITE VIRITUAL BLOCK
iEXTEND FILE
iCREATE FILE
iDELETE FILE
iREAD FILE ATTRIBUTES
iWRITE FILE ATTRIBUTES
iPRIVILEGED ACP CONTROL
iACP CONTROL

DEFINE THE I/O FUNCTION CODES THAT ARE SPECIFIC TO INDIVIDUAL DEVICES
.MACRO
SPCIO$ $$$GBL
.WORD.,DEFIN$
• MCALL
.IF
IDN,<$$$GBL>,<DEF$G>
••• GBL=I
.IFF
••• GBL=O
.ENDC
I/O FUNCTION CODES FOR SPECIFIC DEVICE-DEPENDENT FUNCTIONS
.WORD.
.WORD •
• WORD.
.WORD •
• WORD.
.WORD •
• WORD.
.WORD •
• WORD.
.WORD •
• WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD •
• WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD •
• WORD.
.WORD.
.WORD.
.WORD •
• WORD.
.WORD.
.WORD.
.WORD •
• WORD.
.WORD.

IO.WLV,IOO,OOI
IO.WLS,OIO,OOI
IO.WNS,020,OOI
IO.WAL,OIO,OOI
IO.WMS,020,OOI
IO.CCO,040,OOI
IO.WBT,IOO,OOI
IO.WLT,OIO,OOI
IO.WLC,020,OOI
IO.WPB,040,OOI
IO.WDD,140,OOI
IO.RSN,140,002
IO.RLV,IOO,002
IO.RST,OOl,002
IO.RAL,OIO,002
IO.RNE,020,002
IO.RNC,040,002
IO.RTM,200,002
IO.RDB,200,002
IO.SCF,200,002
IO.RHD,OIO,002
IO.RNS,020,002
IO.CRC,040,002
IO.RPB,040,002
IO.RDF,240,002
IO.RLC,020,002
IO.ATA,OIO,003
IO.GTS,OOO,OOS
10 • RIC, 000 , 005
10.INL,OOO,OOS
10.TRM,OIO,OOS
10.RWD,OOO,OOS
10.SPB,020,OOS
10.RPL,020,OOS
10.SPF,040,OOS
10.STC,IOO,OOS

i (DECTAPE)

WRITE LOGICAL REVERSE

i (COMM.) WRITE PRECEDED BY SYNC TRAIN
i (COMM.) WRITE, NO SYNC TRAIN
i (TTY) WRITE PASSING ALL CHARACTERS
i (TTY) WRITE SUPPRESSIBLE MESSAGE

i (TTY) WRITE WITH CANCEL CONTROL-O
i (TTY)

WRITE WITH BREAKTHROUGH
; (DISK) WRITE LAST TRACK
i (DISK) WRITE LOGICAL W/ WRITECHECK
i (DISK) WRITE PHYSICAL BLOCK
i (FLOPPY DISK) WRITE PHYSICAL W/ DELETED DATA
i (MSCP DISK) READ VOLUME SERIAL NUMBER
i (MAGTAPE,DECTAPE) READ REVERSE
i (TTY) READ WITH SPECIAL TERMINATOR
i (TTY) READ PASSING ALL CHARACTERS
i (TTY) READ WITHOUT ECHO
i (TTY) READ - NO LOWERCASE CONVERT
; (TTY) READ WITH TIME-OUT
i (CARD READER) READ BINARY MODE
i (DISK) SHADOW COPY FUNCTION
i (COMM.) READ, STRIP SYNC
i (COMM.) READ, DON'T STRIP SYNC
i (COMM.) READ, DON'T CLEAR CRC
i (DISK) READ PHYSICAL BLOCK
i (DISK) READ DISK FORMAT
i (DISK,MAGTAPE) READ LOGICAL W/ READCHECK
; (TTY) ATTACH WITH ASTS
; (TTY) GET TERMINAL SUPPORT CHARACTERISTICS
i (AFC,ADOI,UDC) READ SINGLE CHANNEL
i (COMM.) INITIALIZATION FUNCTION
; (COMM.) TERMINATION FUNCTION
; (MAGTAPE,DECTAPE) REWIND
i (MAGTAPE) SPACE "N" BLOCKS
i (DISK) REPLACE LOGICAL BLOCK (RESECTOR)
; (MAGTAPE) SPACE "N" EOF MARKS
iSET CHARACTERISTIC

1-8

ERROR CODES
.WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.. WORD.
.• WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.SMD,110,005
IO.SEC,120,005
IO.RWU,140,005
IO.SMO,160,005
IO.HNG,000,006
IO.HLD,100,006
IO.BRK,200,006
IO.RBC,000,006
IO.MOD,000,006
IO.HDX,010,006
IO.FDX,020,006
IO.SYN,040,006
IO.EOF,000,006
IO.ERS,020,006
IO.DSE,040,006
IO.RTC,000,007
IO.SAO,OOO,OlO
IO.SSO,OOO,Oll
IO.RPR,OOO,Oll
IO.MSO,000,012
IO.RTT,001,012
IO.SLO,000,013
IO.MLO,000,014
IO.LED,000,024
IO.SDO,000,025
IO.SDI,000,026
IO.SCS,000,026
IO.REL,000,027
IO.MCS,000,027
IO.ADS,000,030
IO.CCI,000,030
IO.LOD,000,030
IO.MDI,000,031
IO.DCI,000,031
IO.PAD,000,031
HT.RPP,OlO,OOO
IO.XMT,000,031
IO.XNA,010,031
IO.INI,000,031
IO.HIS,000,032
IO.RCI,000,032
IO.RCV,000,032
IO.CLK,000,032
IO.CSR,000,032
IO.MDO,000,033
IO.CTI,000,033
IO.CON,000,033

.WORD.
.WORD.
.WORD.

IO.ORG,010,033
IO.ANS,020,033
IO.STA,000,033

.WORD.
.WORD.

IO.DTI,000,034
IO.DIS,000,034

.WORD.
• WORD.
.WORD.
.WORD.

IO.MDA,000,034
IO.DPT,010,034
IO.RTI,000,035
IO.CTL,000,035

i (FLOPPY DISK) SET MEDIA DENSITY
iSENSE CHARACTERISTIC
i(MAGTAPE,DECTAPE) REWIND AND UNLOAD
i (MAGTAPE) MOUNT & SET CHARACTERISTICS
i (TTY) HANGUP DIAL-UP LINE
i (TMS) HANGUP BUT LEAVE LINE ON HOLD
i (PRO/TTY) SEND SHORT OR LONG BREAK
iREAD MULTICHANNELS (BUFFER DEFINES CHANNELS)
i (COMM.) SETMODE FUNCTION FAMILY
i tCOMM'.) SET UNIT HALF DUPLEX
i (COMM.) SET UNIT FULL DUPLEX
i (COMM.) SPECIFY SYNC CHARACTER
i (MAGTAPE) WRITE EOF
i (MAGTAPE) ERASE TAPE
i (MAGTAPE) DATA SECURITY ERASE
iREAD CHANNEL - TIME BASED
i (UDC) SINGLE CHANNEL ANALOG OUTPUT
i (UDC) SINGLE SHOT, SINGLE POINT
i (TTY) READ WITH PROMPT
i (UDC) SINGLE SHOT, MULTI-POINT
; (TTY) READ WITH TERMINATOR TABLE
i (UDC) LATCHING, SINGLE POINT
; (UDC) LATCHING, MULTI-POINT
i (LPS11) WRITE LED DISPLAY LIGHTS
; (LPS11) WRITE DIGITAL OUTPUT REGISTER
i (LPS11) READ DIGITAL INPUT REGISTER
i (UDC) CONTACT SENSE, SINGLE POINT
; (LPS11) WRITE RELAY
; (UDC) CONTACT SENSE, MULTI-POINT
i (LPS11) SYNCHRONOUS A/D SAMPLING
i (UDC) CONTACT INT - CONNECT
i (LPA11) LOAD MICROCODE
i (LPS11) SYNCHRONOUS DIGITAL INPUT
i (UDC) CONTACT INT - DISCONNECT
i (PSI) DIRECT CONTROL OF X.29 PAD
; (PSI) RESET PAD PARAMETERS SUBFUNCTION
; (COMM.) TRANSMIT SPECIFIED BLOCK WITH ACK
; (COMM.) TRANSMIT WITHOUT ACK
i (LPA11) INITIALIZE
i (LPS11) SYNCHRONOUS HISTOGRAM SAMPLING
; (UDC) CONTACT INT - READ
; (COMM.) RECEIVE DATA IN BUFFER SPECIFIED
; (LPA11) START CLOCK
i (BUS SWITCH) READ CSR REGISTER
i (LPS11) SYNCHRONOUS DIGITAL OUTPUT
i (UDC) TIMER - CONNECT
; (COMM.) CONNECT FUNCTION
; (VT11) - CONNECT TASK TO DISPLAY PROCESSOR
i (BUS SWITCH) CONNECT TO SPECIFIED BUS
; (COMM./PRO) DIAL TELEPHONE AND ORIGINATE
i (COMM.) INITIATE CONNECTION IN ORIGINATE MODE
; (COMM.) INITIATE CONNECTION IN ANSWER MODE
i (LPA11) START DATA TRANSFER
; (XJDRV) - SHOW STATE
; (UDC) TIMER - DISCONNECT
i (COMM.) DISCONNECT FUNCTION
i (VT11) - DISCONNECT TASK FROM DISPLAY PROCESSOR
; (BUS SWITCH) SWITCHED BUS DISCONNECT
; (LPS11) SYNCHRONOUS D/A OUTPUT
i (BUS SWITCH) DISCONNECT TO SPECIF PORT NO •
; (UDC) TIMER - READ
; (COMM.) NETWORK CONTROL FUNCTION

1-9

ERROR CODES
.WORD.

IO.STP,000,035

.WORD.
.WORD.

IO.SWI,000,035
IO.CNT,000,036

.WORD.

IO.ITI,000,036

; (LPS11,LPA11) STOP IN PROGRESS FUNCTION
; (VT11) - STOP DISPLAY PROCESSOR
; (BUS SWITCH) SWITCH BUSSES
; (VT11) - CONTINUE DISPLAY PROCESSOR
; (XJDRV) - SHOW COUNTERS
; (UDC) TIMER - INITIALIZE

EXTENDED I/O FUNCTION
.WORD.

IO.EIO,000,037

; (TTY) TSA EXTENDED I/O

PRO 300 SERIES BITMAP FUNCTIONS
NOTE: THESE FUNCTIONS ARE FOR DEC USE ONLY AND ARE SUBJECT TO CHANGE
.WORD.
.WORD.
DEFIN$
DEFIN$

IO.RSD,030,014
IO.WSD,010,013
SD.TXT,O
SD.GDS,l

READ SPECIAL DATA
WRITE SPECIAL DATA
TEXT DATA TYPE FOR SPECIAL DATA
GIDIS DATA TYPE FOR SPECIAL DATA

PROFESSIONAL 300 BISYNC DRIVER (XJDRV) FUNCTIONS
.WORD.
.WORD •
• WORD.
.WORD.

SB.PRT,020,003
SB.CLR,010,036
SB.RDY,010,033
SB.NRD,020,033

ATTACH AS A PRINTER
CLEAR COUNTERS (IO.CNT SUBFUNCTION)
SET DEVICE STATE READY (IO.STA SUBFUNC)
SET DEVICE STATE NOT READY

.WORD.

IO.LBK,000,035

PERFORM LOOPBACK TEST

.WORD.
.WORD.

SB.CBL,010,035
SB.CLK,020,035

PERFORM CABLE LOOPBACK TEST
DEVICE PERFORMS LINE CLOCKING

COMMUNICATIONS FUNCTIONS
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD •
• WORD.
.WORD.
.WORD.
.WORD •
• WORD.
.WORD.
.WORD.

IO.CPR,010,033
IO.CAS,020,033
IO.CRJ,040,033
IO.CBO,110,033
IO.CTR,210,033
IO.GNI,010,035
IO.GLI,020,035
IO.GLC,030,035
IO.GRI,040,035
IO.GRC,050,035
IO.GRN,060,035
IO.CSM,070,035
IO.CIN,100,035
IO.SPW,110,035
IO.CPW,120,035
IO.NLB,130,035
IO.DLB,140,035

;CONNECT NO TIME-OUTS
;CONNECT WITH AST
;CONNECT REJECT
;BOOT CONNECT
;TRANSPARENT CONNECT
;GET NODE INFORMATION
;GET LINK INFORMATION
;GET LINK INFO CLEAR COUNTERS
;GET REMOTE NODE INFORMATION
;GET REMOTE NODE ERROR COUNTS
;GET REMOTE NODE NAME
;CHANGE SOLO MODE
;CHANGE CONNECTION INHIBIT
;SPECIFY NETWORK PASSWORD
;CHECK NETWORK PASSWORD
;NSP LOOPBACK
;DDCMP LOOPBACK

ICS/ICR I/O FUNCTIONS
.WORD.
.WORD •
• WORD.
.WORD.
.WORD.
.WORD.

IO.CTY,000,007
IO.DTY,000,015
IO.LDI,000,016
IO.UDI,010,023
IO.LTI,000,017
IO.UTI,020,023

;CONNECT TO TERMINAL INTERRUPTS
;DISCONNECT FROM TERMINAL INTERRUPTS
;LINK TO DIGITAL INTERRUPTS
;UNLINK FROM DIGITAL INTERRUPTS
;LINK TO COUNTER MODULE INTERRUPTS
;UNLINK FROM COUNTER MODULE INTERRUPTS

1-10

ERROR CODES
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

10.LTY,000,020
10.UTY,030,023
10.LKE,000,024
10.UER,040,023
10.NLK,000,023
10.ONL,000,037
10.FLN,000,025
10.RAD,OOO,021

iLINK TO REMOTE TERMINAL INTERRUPTS
iUNLINK FROM REMOTE TERMINAL INTERRUPTS
iLINK TO ERROR INTERRUPTS
iUNLINK FROM ERROR INTERRUPTS
iUNLINK FROM ALL INTERRUPTS
iUNIT ONLINE
iUNIT OFFLINE
iREAD ACTIVATING DATA

IPII I/O FUNCTIONS
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

10.MAO,010,007
IO.LEI,010,017
10.RDD,010,020
IO.RMT,020,020
10.LSI,000,022
IO.UEI,050,023
10.USI,060,023
IO.CSI,000,026
10.DSI,000,027
IO.RAM,000,032
10.RLK,000,013
10.EBT,000,011

iMULTIPLE ANALOG OUTPUTS
iLINK EVENT FLAGS TO INTERRUPT
iREAD DIGITAL DATA
iREAD MAPPING TABLE
iLINK TO DSI INTERRUPTS
iUNLINK EVENT FLAGS
;UNLINK FROM DSI INTERRUPTS
iCONNECT TO DSI INTERRUPTS
iDISCONNECT FROM DSI INTERRUPTS
;READ ANALOG MAPPING TABLES
iREAD RESOURCE LINKAGES
iCHECK EBIT STATUS

PCLl1 I/O FUNCTIONS
.WORD.
.WORD.
.WORD.
.WORD •
• WORD.

10.ATX,000,001
10.ATF,000,002
10.CRX,000,031
10.DRX,000,032
10.RTF,000,033

• MACRO
.ENDM
.ENDM

SPCIO$
SPCIO$
SPCIO$

iATTEMPT TRANSMISSION
iACCEPT TRANSFER
;CONNECT FOR RECEPTION
iDISCONNECT FROM RECEPTION
iREJECT TRANSFER

DEFINE THE I/O CODES FOR USER-MODE DIAGNOSTICS. ALL DIAGNOSTIC
FUNCTIONS ARE IMPLEMENTED AS A SUBFUNCTION OF I/O CODE 10 (OCTAL).
• MACRO
.MCALL
.IF ION
••• GBL=1
.IFF
••• GBL=O
.ENDC

UMDIO$
$$$GBL
.WORD.,DEFIN$
<$$$GBL),<DEF$G)

DEFINE THE GENERAL USER-MODE I/O QUALIFIER BIT.
.WORD.

IQ.UMD,004,000

iUSER-MODE DIAGNOSTIC REQUEST

DEFINE USER-MODE DIAGNOSTIC FUNCTIONS.
.WORD.
.WORD.
.WORD.

10.HMS,000,010
IO.BLS,010,010
10.OFF,020,010

i (DISK) HOME SEEK OR RECALIBRATE
; (DISK) BLOCK SEEK
i (DISK) OFFSET POSITION

I-II

ERROR CODES
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.
.WORD.

IO.RDH,030,OlO
IO.WDH,040,OlO
IO.WCK,050,OlO
IO.RNF,060,OlO
IO.RNR,070,OlO
IO.LPC,lOO,OlO
IO.RTD,120,OlO
IO.WTD,130,OlO
IO.TDD,140,OlO
IO.DGN,150,OlO
IO.WPD,160,OlO
IO.RPD,170,OlO
IO.CER,200,OlO
IO.CEW,210,OlO

; (DISK) READ DISK HEADER
; (DISK) WRITE DISK HEADER
; (DISK) WRITECHECK (NONTRANSFER)
; (DECTAPE) READ BLOCK NUMBER FORWARD
; (DECTAPE) READ BLOCK NUMBER REVERSE
;(MAGTAPE) READ LONGITUDINAL PARITY CHAR
; (DISK) READ TRACK DESCRIPTOR
; (DISK) WRITE TRACK DESCRIPTOR
; (DISK) WRITE TRACK DESCRIPTOR DISPLACED
;DIAGNOSE MICRO PROCESSOR FIRMWARE
; (DISK) WRITE PHYSICAL BLOCK
; (DISK) READ PHYSICAL BLOCK
; (DISK) READ CE BLOCK
; (DISK) WRITE CE BLOCK

MACRO REDEFINITION TO NULL
• MACRO
.ENDM

UMDIO$

.ENDM

UMDIO$

HANDLER ERROR CODES RETURNED IN I/O STATUS BLOCK ARE DEFINED THROUGH THIS
MACRO, WHICH THEN CONDITIONALLY INVOKES THE MESSAGE-GENERATING MACRO
FOR THE QIOSYM.MSG FILE
.MACRO
DEFIN$
.IF
• MCALL
.IOMG.
.ENDC
.ENDM

.IOER. SYM,LO,MSG
SYM,LO
GT,$$MSG
• IOMG •
SYM,LO,<MSG>
.IOER.

I/O ERROR CODES ARE DEFINED THROUGH THIS MACRO, WHICH THEN INVOKES THE
ERROR MESSAGE-GENERATING MACRO; ERROR CODES -129 THROUGH -256
ARE USED IN THE QIOSYM.MSG FILE
.MACRO
DEFIN$
.IF
• MCALL
.IOMG •
• ENDC
.ENDM

.QIOE.
SYM,LO,MSG
SYM,LO
GT,$$MSG
.IOMG •
SYM,<LO-128.>,<MSG>
.QIOE.

CONDITIONALLY GENERATE DATA FOR WRITING A MESSAGE FILE
.MACRO
.WORD
.ENABL
.ASCIZ
.DSABL
.EVEN
.IIF
• ENDM

• IOMG.
-AO<LO>
LC
AMSG A
LC

SYM,LO,MSG

LT,AO<$$$MAX+<LO»,$$$MAX=-AO<LO>
.IOMG •

1-12

ERROR CODES

DEFINE THE SYMBOL SYM WHERE LO IS THE LOW-ORDER BYTE, HI IS THE HIGH BYTE
.MACRO
DEFIN$
• ENDM

.WORD. SYM,LO,HI
SYM,<HI*400+LO>
.WORD •

.DSABL

1-13

APPENDIX J
FIELD SIZE SYMBOLS

Definitions for these symbols are contained in the System Library.
S.BFHD - Size of FSR block buffer header in bytes
S.FATT - Size of FOB file attribute area in bytes
S.FDB

- Size of FOB in bytes (including name block)

S.FNAM - Size of file name in bytes (stored in Radix-50)
S.FNB

- Size of filename block in bytes

S.FNBW - Size of filename block in words
S.FNTY - Size of file name and file
Radix-50)

type

words

(stored

S.FSR2 - Size of FSR2 (basic impure area)
S.FTYP - Size of file type in bytes (in Radix-50)
S.NFEN - Size of a complete file'name in bytes -- file 10,
type, and version

J-l

name,

APPENDIX K
RSX-IIM/M-PLUS FCS LIBRARY SYSGEN OPTIONS

K.l

FCS LIBRARY OPTIONS

The system manager has the option of selecting one of several FCS
libraries as the default FCS library.
You can replace the default
library in SYSLIB with one of the other libraries shown in Table K-l
by
using
the /RP switch to the LBR utility.
Refer to the
RSX-IIM/M-PLUS Utilities Manual for more information.
Table K-l
contains the FCS libraries that are available with each RSX-IIM,
RSX-IIM-PLUS, and Micro/RSX system, and a brief description of each.
Table K-I
FCS Library Descriptions
FCS Library Support

K.2

Description

[1,I]FCS.OBJ

Standard FCS routines. Distributed and
included in SYSLIB.OLB as the default FCS
library routines for RSX-IIM.

[1,l]FCSMTA.OBJ

Includes standard FCS routines, plus ANSI
magnetic tape support and "big buffering"
(see Section 2.2.1.6 for block buffer size
override specification). Distributed and
included as the default FCS library
routines for RSX-IIM-PLUS and Micro/RSX.

[1,I]FCSMBF.OBJ

Provides multiple buffering support, big
buffering support, and ANSI magnetic tape
support in addition to the standard FCS
routines.

• FCTYP

The FCS routine .FCTYP returns a description of the FCS
assembly parameters that were set when FCS was built.

conditional

The format of the call is:
CALL

.FCTYP

There are no input parameters.
The information is returned in RI.
The bits set in the mask word
returned in RI correspond to the conditional assembly parameters as
shown in Table K-2.

K-I

RSX-IIM/M-PLUS FCS LIBRARY SYSGEN OPTIONS
Table K-2
.FCTYP Values
Conditional
Assembly Symbol

Rl Bit Mask Symbol

Meaning

R$$ANI

FT.ANI

ANSI magnetic tape support

R$$BBF

FT.BBF

Big buffer support

R$$MBF

FT.MBF

Multibuffer support

K-2

INDEX

Access
shared, 2-15
read, 1-13
write, 1-12
Action routine, 7-5
calling, 7-6
using, 7-6
ALUN$ directive summary, C-l
ANSI tape standard, G-l
Append
file open, 2-15
.ASCPP routine, convert UIC to
binary, 4-7
.ASLUN routine, assign LUN, 4-10,
4-1.5
ASSIGN command
in logical name translation,
~1:-8

AST service routine, 2-45, 2-46
Bad block file header, E-2
Binary to ASCII conversion
UIC, 4-7
Bit map
inde~: file, E-2
Blank
igno:ring in command line, 7-8
Block
access
initialization, 2-12
READ$ macro, 2-12
WRITE$ macro, 2-12
boundary, 2-6

Block I/O (Cont.)
operation, 1-7
operation, FD.RWM parameter,
3-6
request, record attribute, 3-9
Block size
override, 3-10
Bootstrap block, E-l
Buffer
FSR block
locate mode, 3-21
space allocation, 2-20
multiple, 2-19
count, 3-10
type, 2-19
pool space, FSR, 2-39
specifying number, 2-20
task record, 3-21
locate mode, 3-27
PUT$ macro, 3-26
Buffer boundary, locate mode,
3-22
Buffer count
default, 2-20
multiple, 2-19
Buffer descriptor, task, 3-10
Buffer flush routine, 4-28
Buffering
big, 1-11
multiple
performance, 1-10
record I/O, 1-10

buffE~r

initialize FOB, 2-18
pool space, FSR, 2-39
locking, 2-17, 2-46
enable, 2-16
logical, 5-2
size
block I/O, 2--12
reset, CLOSE$ macro, 2-19
statistics
address, 3-11
tape
override size, 2-18
unlocking, 2-47
virtual, 5-2
Block boundary
crossing, record attribute, 3-9
fixed-length record
PUT$ macro, 3-27
FSR block buffer, 3-26
variable-length record
PUT$ macro, 3-27
Block I/O, 2-10
block size, 2-12
buff~~r, 2-12
completion event flag, 2-13
I/O status block, 2-13

Carriage control, 2-6, 2-7
Carriage-control
record attribute, 3-8
word, record attribute, 3-9
CCML$ macro, 6-12
Checkpoint file header, E-2
Checksum value, 5-4
CLOSE$ example, 5-9
CLOSE$ macro, 3-1
block size reset, 2-19
file processing, 3-18
file processing completion, 2-8
format, file processing, 3-18
COBOL carriage control, 2-6
Coding TPARS, 7-1
Command file
close, 6-12
reset scan macro, 6-12
Command line
ignoring blanks and tabs, 7-8
parsing, 7-1
processing, 6-1
Command String Interpreter
See CSI
Control task
tape, G-ll

Index-I

INDEX
Conversion
UIC, ASCII/binary, 4-6, 4-7
Convert UIC
binary to ASCII, 4-7
CSI, 6-1
control block bit values
definition, 6-14
control block offsets
definition, 6-14
expand file specification, 6-19
initialize control block, 6-19
parse file specification, 6-19
routine, 6-14
run time macros, 6-19
CSI macro, switch definition,
6-23
CSI$ macro, 6-14, 6-15
CSI$l macro, command syntax
analyzer, 6-19
CSI$2 macro
command semantic parser, 6-20
initialize control block, 6-19
parse file specification, 6-19
CSI$4 macro
command semantic parser, 6-22
expand file specification, 6-19
CSI$ND macro, 6-24
define end of descriptor table,
6-31
CSI$SV macro, 6-23
create switch value descriptor
table entry, 6-28
CSI$SW macro, 6-23
create switch descriptor table
entry, 6-24
.CTRL routine, control device,
4-27
.CTRL routine, tape, 5-7
Data format
ANSI tape, 1-7
file device, 1-6
Dataset descriptor, 2-28
address, initialization, 2-14
as data structure, 1-4
definition, 1-3
general description, 1-5
OFNB$x macro, 3-15
pointer
definition, 1-3
file-open, 2-14
initialization, 2-14
specifying, 2-28
$DEBUG, 7-2
Debug routine, 7-6
DECtape file structure, 5-1
Default Filename Block
See DFNB
DELET$ macro, 3-1, 3-39
format
file operations, 3-39
Device control routine, 4-27
Device information
.PRSDV routine, 4-15

Device name field, 2-34
Device name string descriptor,
2-29
DFNB, 2-31, 3-15
as data structure, 1-4
definition, 1-2
FNBLK$ macro, 2-31
OFNB$x macro, 3-15
specifying, 2-28
Directive summary
I/O related, C-l
Directory
file, 5-2
identification information
.PARSE routine, 4-12
.PRSDI routine, 4-15
structure, 5-3
Directory entry
delete
.REMOV routine, 4-19
insert
.ENTER routine, 4-18
locate
.FIND routine, 4-16
routine, 4-16
Directory string
default
read, 4-2
write, 4-3
descriptor, 2-29
routine
default, 4-2
Disk file structure, 5-1
.DLFNB routine, delete file by
filename block, 4-26
End-of-file
label (tape), G-9
READ$ macro, 3-33
End-of-tape handling, G-10
End-of-volume label (tape), G-8
.ENTER routine, insert directory
entry, 4-18
Error code
block locking, 2-48
file operations, 1-1
shared file, 2-48
Error return
GCMLD$ macro, 6-5
IE. I FC , 2 - 4 9
IE. LC K, 2 - 4 9
IE.ULK, 2-49
IE.WAC, 2-48
Error routine
file macro, 3-2
Event flag
I/O coordination, 2-43
I/O synchronization, 3-10
.EXPLG module
logical name expansion, 4-14
Extension
default, 2-20
.EXTND routine, extend file, 4-24

Index-2

INDEX
F.ACTL field, number of retrieval
pointers, A-9
F.ALOC field, number of blocks
allocated for extend, A-7
F. BBFS field, block buffer s i ze-,
A-a
F.BDB field, block buffer
descriptor block address, A-9
F.BGBC field, big-buffer block
count, A-8
F.BKDN field, AST service routine
address, A-6
F.BKDS field, block I/O buffer
descriptor, A-6
F.BKEF field, block I/O event
flag, A-7
F.BKPI field, FCS internal
control bits, A-8
F.BKST field, I/O status block
address, A-6
F.BKVD field, user virtual block
number, A-8
F.CHR field, volume
characteristics byte, A-9
F.CNTG field, number of blocks to
be allocated, A-6
F.DFNB field, default filename
block pointer, A-7
F.DSPT field, dataset descriptor
pointer, A-7
F.EFBK field, end-of-file block
number, A-4
F.EFN field, record I/O event
fLag, A-7
F.EOBB field, end-of-block buffer,
A-6
F.ERR field, error return code
byte, A-8
F.ERRI field, F.ERR extension,
A-8
F.EXT field, FDB extension
address, A-9
F.FACC field, file access byte,
A-7
F.FFBK field, first free byte in
last block, A-4
F.FLG field, flag byte, A-9
F.FNB field, filename block
offset, A-9
F.HIBK field, highest allocated
virtual block number, A-4
F.LUN field
FDB, 4-16
F.LUN field, LUN for FDB, A-7
F.MBCl field, number of buffers
in use, A-8
F.MBC'II field, number of multiple
buffers, A-a
F.MBFG field, multibuffer flag
word, A-8
F.NRBD field, next record buffer
dE~scr iptor, A-6
F.NREC field, adress of next
record in block, A-6

F.OVBS field, override block
buffer size, A-6
F.RACC field, record access byte,
A-4
F.RATT field, record attribute
byte, A-4
F.RCNM field, random access
record number, A-6
F.RCTL field, device
characteristics byte, A-5
F.RCTL, device characteristic
byte
.PARSE routine, 4-12
F.RSIZ field, reocrd-size word,
A-4
F.RTYP field, record-type byte,
A-3
F.SEQN field, sequence number,
A-9
F.STBK field, statistics block
address, A-6
F.URBD field, user record buffer
descriptor, A-6
F.VBN field, virtual block number,
A-8
F.VBSZ field, device buffer size
word, A-8
F.VBSZ, device buffer size word
.PARSE routine, 4-12
FA.DLK value, not lock file, 2-16
FA.EXL value, block locking, 2-17
FA.LKL value, block locking, 2-17
FA.NSP value, open file no
supersede, 3-17
FA.POS value, file position on
close, 2-16
FA.RWD value, rewind on close or
open, 2-16
FA.SHR value, open file shared
access, 3-17
FA.TMP value, open temporary file,
3-17
FCS, 1-1
data structure
general, 1-4
file access method, 1-6
I/O macro, 2-1
important characteristic, 1-3
impure area, 2-38
library options, K-l
macro
FDB information, 2-2
.MCALL directive, 2-2
term definition, 1-2
with Task Builder, 1-1
FCS.OBJ FCS library, K-l
FCSMBF.OBJ FCS library, K-l
FCSMTA.OBJ FCS library, K-l
FCSRES routines, 1-20
.FCTYP routine, assembly
parameters, K-l
FD.BLK parameter
record attribute, 2-6
block boundary crossing, 3-9

Index-3

INDEX
FD.CR parameter
record attribute, 2-6
line-feed character, 3-8
FD.FTN parameter, 3-8
FD.INS parameter
sequential file, 2-10
sequential mode, 3-6, 3-9
FD.PLC parameter
locate mode, 2-10, 3-6, 3-9
move mode, 2-10
FD.PRN parameter
record attribute, 2-6
carriage-control word, 3-9
FD.RAH parameter, read-ahead
operation, 3-11
FD.RAH value, read-ahead, 2-19
FD.RAN parameter
random access, 2-10, 3-9
random record I/O, 3-6
FD.RTN, record attribute, 2-6
FD.RWM parameter
block I/O operation, 3-6
record access, 2-10
record attribute
process with block I/O, 3-9
FD.WBH parameter, write-behind
operation, 3-11
FD.WBH value, write behind, 2-19
FDAT$A macro, 2-5
FDAT$R macro, 2-21
FOB, 2-3
address, run-time macro, 2-24
allocate file block, 2-8
as data structure, 1-4
block I/O, 2-10
block locking, 2-17
block size reset, 2-19
carriage control, 2-7
definition, 1-2
description, 1-5
extension, logical name
translation, 4-14
F.LUN field, 4-16
F.xxxx field, A-3
file identification, 3-10
GET$ macro, 3-21
initial values, 2-1
initialization, 2-3
initialize block access, 2-21
initialize block buffer, 2-18,
2-22
initialize block buffer size,
2-18
initialize file attribute, 2-5,
2-21
initialize file-open section,
2-14, 2-22
initialize record access, 2-10,
2-21
largest record size, 2-8
lun specification, 3-10
macro
global symbol, 2-26
local symbol, 2-27

FOB
macro (Cont.)
run-time exceptions, 2-22
run-time initialization, 2-21
multiple buffering, 2-19
type, 2-19
offset, global/local, 2-25
OPEN$x macro requirement, 3-7
PUT$ macro operation, 3-25
record I/O, 2-10
record size, 3-9
sequence number field, 2-7
space allocation, 2-5
WRITE$ macro, 3-36
FDBDF$ macro, FOB space
allocation, 2-5
FDBF$A macro, 2-18
example, 2-21
FDBF$R macro, 2-22
FDBK$A macro
block access initialization,
2-12
example, 2-13
record access, block I/O, 2-12
FDBK$R macro, initialize block
access, 2-21
FDOP$A macro, 2-14
example, 2-17
FDOP$R macro, initialize
file-open section, 2-22
FDRC$A macro, 2-10
example, 2-10
FDRC$R macro, initialize record
access, 2-21
Field size symbols, file
operation, J-l
File
access
method, FCS, 1-6
optimizing, 2-34
close current command, 6-12
close indirect command, 6-12
closing, 3-18
closing temporary, 3-12
creating
FO.WRT value, 3-17
creating temporary, 3-12
mark for deletion, 3-13
delete routine, 4-25, 4-26
deleting, 3-39
deleting routine, 4-25
device
data format, 1-6
directory, 5-2
extend, routine, 4-24
extending
WRITE$ macro, 3-36
index, 5-2, E-1
locked, 2-16
mark for delete, 3-13
multiple, operation, 5-6
no lock on close, 2-16
open by filename block, 3-14
open by 10, 3-13

Index-4

INDEX

File (Cont.)
open for append
FO.APD value, 3-17
open for modify, 3-17
open for read, 3-17
open for shared access
FA.SHR value, 3-17
open for update and extend,
3-17
open for write
FO.WRT value, 3-17
open on LP: for printing, 8-2
open processing, 3-3
open temporary
FA.TMP value, 3-17
opening temporary, 3-12
mark for deletion, 3-13
position on close, 2-16
record access intialization,
2-21
rename, 4-23
sequemced, 2- 6
reading, 2-7
wri ting, 2-7
shared access, 1-12
single, operation, 5-6
truncate routine, 4-25
truncation, 2-11
File attribute
initialize, 2-5
run-time, 2-21
specifying tape, G-17
File block
access initialization, 2-12
run time, 2-21
allocation, 2-8
buffer initialization, 2-18
run time, 2-22
locking, 2-17
File characteristic
system-controlled
SC.BAD, bad data block, F-4
SC.MDL, file marked for
delete, F-4
user-controlled
UC.CON, contiguous file, F-4
UC.DLK, file improperly
closed, F-4
File control routine, 4-1
File Control Services
See FCS
File Descriptor Block
See FOB
File extension
default, 2-20
default size, 2-9
size, 2-8
virtual block, 2-9
File header block, 5-3, E-2
format, F-l
H.XXXX field, F-l
header area
file characteristics, F-4
file owner information, F-3

File header block
header area (Cont.)
file protection code, F-4
'identification area, F-4
creation date, F-5
creation time, F-5
expiration date, F-5
file version number, F-4
filename, F-4
filetype, F-4
revision date, F-4
revision number, F-4
revision time, F-5
map area, F-5
tape, G-I0
user file, E-2
File header block, H.XXXX field,
F-2
File header block, I.XXXX field,
F-2
File header block, M.XXXX field,
F-2, F-3
File header label
ANSI, 5-4
tape, G-3
HDR1, G-4
HDR2, G-5
HDR3, G-6
File I/O
coordination, 2-42
status block, 2-44
File identification, 5-3
FOB, 3-10
field, 2-34
File identifier
processing by Files-ll (tape),
G-7
File label
tape, G-l
File macro, 3-1
access privileges, 3-3
error routine, 3-2
File name
.PARSE routine, 4-13
.PRSFN routine, 4-15
tape
Radix-50 conversion, 4-18
File number, 5-3
File open
append, 2-15
by 10, 2-34
for file access, 3-16
lock on close, 2-16
modify, 2-15
no supersede, 2-15, 3-16, 3-17
read access, 2-15
shared access, 2-15
tape position, 2-16
temporary, 2-15
update, 2-15
write access, 2-15
File operation, error codes, 1-1
File owner word, 4-5
read, 4-6

Index-5

'INDEX
File owner word (Cont.)
write, 4-6
File pointer routine, 4-20
File position
by byte, 2-11
save, 4-22
to byte
.POINT routine, 4-21
to record
.POSRC routine, 4-21
File processing completion
CLOSE$ macro, 2-8
File protection word, 4-4, 4-5
File random I/O, 2-20
File read-ahead
FD.RAH parameter, 3-11
File record
attribute, 2-6
File rename routine, 4-23
File sequence number, 2-7, 5-3
File space preallocation, 2-20
File specification
definition, 1-3
device, 1-14
.PRSDV routine, 4-15
directory, 1-14
.PRSDI routine, 4-15
dynamic processing
SYSLIB, 2-34
generation, 1-17
logical name expanding, 4-9
logical name merging, 4-9
logical name parsing, 4-9
magnetic tape, 1-16, 1-17
name, 1-15
syntax description, 1-13
type, 1-15
unit
.PRSDV routine, 4-15
version, 1-16
within program, 2-27
File Storage Region
See FSR
File structure, 5-1
tape, G-9
user, 5-2
virtual blocks, 5-2
File trailer label (tape), G-9
File type
.PARSE routine, 4-13
.PRSFN routine, 4-15
File version
.PARSE routine, 4-13
.PRSFN routine, 4-15
File window pointer
number, 2-16
Filename block
See also FNB
default, 2-31, 3-15
file-open, 2-14
initialization, 2-15
OFNB$x macro, 3-15
specifying, 2-28
default directory information

Filename block
default directory information
(Cont. )
.GTDID routine, 4-20
delete file, 4-26
directory information
.GTDIR routine, 4-19
initializing, 2-35
local offset definition, 2-33
manually initializing, 2-36
N.DID field
.PARSE routine, 4-12
N.DVNM field, 4-16
N.NEXT
.PARSE routine, 4-14
N.STAT word
.PARSE routine, 4-14
NBOF$L macro, 2-33
NMBLK$ macro, 2-31
open file by, 3-14
OPEN$x macro, 2-35
.PARSE routine
disk, 4-10
N.DID field, 4-12
N.FID field, 4-12
tape, 4-10
Filename block routine, 4-7, 4-19
Filename string descriptor, 2-29
Files-II structure, 5-1
.FIND routine, find directory
entry, 4-16
.FINIT routine, initialize before
.PARSE routine, 4-10
FINIT$ macro
FSR initialization
run-time, 2-40
Fixed-length record
PUT$ macro
block boundary, 3-27
block buffer, 3-27
Flush buffer routine, 4-28
.FLUSH routine, flush buffer,
4-28
FNB
definition, 1-2
N.XXXX field, B-1
FO.APD value, open file for
append, 3-17
FO.MFY value, open file for
modify, 3-17
FO.RD value, open file for read,
3-17
FO.UPD value, open file for
update and extend, 3-17
FO.WRT value
open file for write and create,
3-17
FORTRAN carriage-control
record attribute, 3-8
FSR
as data structure, 1-4
definition, 1-3
general description, 1-5

Index-6

INDEX
FSR
incre!asing size
FORTRAN, 2-42
MACRO-II, 2-41
initalization
FINIT$ macro, 2-40
initialization
FSRSZ$ macro, 2-37
record I/O, 2-38
multiple buffering, 2-38
fsr
INITIALIZATION, 2-37
FSR block buffer
block boundary, 3-26
locate mode, 3-21, 3-27
pool space, 2-39
space allocation, 2-20
$$FSRl, 1-5
$$FSR2
default UIC, 4-4
file owner w6rd, 4-5
file protection word, 4-4
general description, 1-6
FSRSZ$ macro, FSR initialization,
2-37
GCML, 6-1, 6-2
control block
allocate, 6-3
define bit values, 6-5
define offsets, 6-5
initialize, 6-3
routine, run-time error, 6-9
usage, 6-13
GCML$ macro, 6-9
GCMLB$ macro, 6-3
GCMLO$ macro, 6-5
Get command line
See also GCML
Get command line macro, 6-9
GET$ macro, 1-8, 3-1
example, 3-20
FO.RWM parameter, record I/O,
2-10
FOB,. file processing, 3-21
file processing, 3-19
locate mode, 3-21
move mode, 3-21
format, file processing, 3-19
GET$R macro, 3-1
filE:! process i ng
read logical record, random
mode, 3-22
GET$S macro, 3-1
fi149 processing
read logical record,
sequential mode, 3-24
Global symbol, FOB macro, 2-26
GLUN$ directive summary, C-l
GMCR$ directive summary, C-l
.GTOIO routine, 4-19
.GTOIO routine, default directory
information, 4-20
.GTOIR routine, 4-19

.GTOIR routine, insert directory
information, 4-19
H.CKSM, checksum word, F-3
H.FLEV, structure level, F-l
H.FNUM, file number, F-l
H.FOWN, offset to file owner, F-l
H.FPRO, file protection code, F-l
H.FSEQ, file sequence number, F-l
H.IOOF, header area, F-l
H.MPOF, map area offset, F-l
H.PROG, member number, F-l
. H.PROJ, group number, F-l
H.SCHA, system-controlled file
characteristics, F-2
H.UCHA, user-controlled file
characteristics, F-l
R.UFAT, user file attributes, F-2
Header area, 5-3
file header block, F-3
file characteristics, F-4
file number, F-3
file owner information, F-3
file protection code, F-4
file sequence number, F-3
identification area, F-3
map area offset, F-3
structure level, F-3
user file attributes
file characteristics, F-4
Header block
file, 5-3
Home block, E-l
I.CROT, creation date, F-2
I.CRTI, creation time, F-2
I.EXOT, expiration date, F-2
I.FNAM, identification area, F-2
I.FTYP, file type, F-2
I.FVER, file version number, F-2
I.RVDT, revision date, F-2
I.RVNO, revision number, F-2
I.RVTI, revision time, F-2
I/O
block operation, 1-7
coordination
event flag, 2-43
file operation, 2-42
data-transfer mode, 1-9
directive summary, C-l
locate mode, 1-9, 1-10
move mode, 1-9
preparation, FCS macro, 2-1
record
big buffering, 1-11
multiple buffering, 1-10
record operation, 1-8
synchronization, 1-7
event flag, 2-18, 3-10
wait for completion
block I/O, 3-37
I/O macro
AST service routine, 2-45, 2-46
FCS, 2-1

Index-7

INDEX
I/O macro (Cont.)
FOB, 2-2
I/O program example, 0-1
I/O status block
block I/O, 2-13
defined in task, 2-45
file I/O, 2-44
Identification area, 5-4
file header block, F-4
creation date, F-5
creation time, F-5
expiration date, F-5
file version number, F-4
filename, F-4
filetype, F-4
revision date, F-4
revision number, F-4
revision time, F-5
Index file, 5-2
bit map, E-2
format, E-l
header, E-2
ISTAT$ macro, 7-1, 7-2
Keyword recognition, transition
table, 7-9
Library option, FCS, K-l
Line-feed character
record attribute, 3-8
Local symbol
FOB macro, 2-27
Locate mode, 1-9, 1-10, 2-10
file processing, 3-27
FSR block buffer, 3-27
GET$ macro, 3-19, 3-21
PUT$ macro, 3-24, 3-28
record attribute, 3-9
task record buffer, 3-27
Logical block, 5-2
file device, 1-7
Logical name, 1-18
specifying, 1-19
using, 1-19
Logical name translation, 4-8
ASSIGN command, 4-8
expanding file specification
string, 4-9
FOB extension, 4-14
i tera ti ve, 4-8
merging file specification, 4-9
name expansion
.EXPLG module, 4-14
parse file specification, 4-9
.PARSE routine
device and unit, 4-11
process, 4-9
.PRSDV routine, 4-15
LUN, assign with .ASLUN routine,
4-15
M.CTSZ, retrieval pointer block
count field size, F-2

M.EFNU, extension file number,
F-2
M.EFSQ, extension file sequence
number, F-2
M.ERVN, extension relative volume
number, F-2
M.ESQN, map area, F-2
M.LBSZ, retrieval pointer logical
block number field size, F-2
M.MAX, available retrieval
_
pointer words, F-3
M.RTRV, retrieval pointer start,
F-3
M.USE, retrieval pointer word
count, F-3
Macro
global symbol, 2-26
local symbol, 2-27
run-time
exceptions, 2-22
FOB address, 2-24
initialization, 2-21
MAG, G-ll
MAG task error messages, G-15
Map area, 5-4
file header block, F-5
Mark file for delete, 4-25
.MARK routine, save file position,
4-22
Master File Directory, 5-2
.MCALL directive, 2-2
MFD, 5-2
MFD header, E-2
Move mode, 1-9
GET$ macro, 3-19, 3-21
PUT$ macro, 3-24, 3-26
.MRKDL routine, mark temporary
file for delete, 4-25
Mutiple file operation, 5-6
N.ANMI field, ANSI filename
string, B-4
N.ANM2 field, remainder of ANSI
filename string, B-4
N.DID field, .PARSE routine, 4-12
N.DID field, directory
identification, B-2
N.DVNM field, 4-16
N.DVNM field, ASCII device name,
B-2
N.DVNM field, ASCII tape device
name, B-4
N.FID field
.FIND routine, 4-16
.PARSE routine, 4-12
N.FID field, file identification,
B-1, B-4
N.FNAM field, file name, B-1
N.FTYP field, file type, B-1
N.FVER field, file version number,
B-1
N.FVER field, tape file version
number, B-4

Index-8

INDEX
N.NEXT field, context for next
.FIND, B-2
N.NEXT field, tape context for
nex.t • FIND, B-4
N.STAT field, filename block
status word, B-1
N.STAT field, tape filename block
status word, B-4
N.UNIT field
FNB (tape), B-4
N.UNIT field, unit number field,
B-~~

NBOF$L macro, 2-33
NMBLK$ macro
default filename block, 2-31
example, 2-33
OFID$ macro, 3-1
OFID$x macro, file processing,
3-13
OFNB$ macro, 3-1
OFNB$x macro
dataset descriptor, 3-15
default filename block, 3-15
file processing, 3-14
Open file
by filename block, 3-14
by ID, 2-34, 3-13
existing, 3-9
for access, 3-16
for modify, 3-17
for read, 3-17
for update and extend, 3-17
new, 3-9
no supersede, 3-16, 3-17
processing, 3-3
OPEN$
example, 5-9
macro, 3-1
macro, file processing, 3-16
OPEN$R
example, 5-8
macro, shared access, 1-13
OPEN$x macro
file processing, 3-2 , 3-7
format, file operations, 3-5
OPNS$ macro, 3-1
OPNS$R macro, shared access, 1-12
OPNS$x macro, file processing,
3-12
OPNT$ macro, 3-1
OPNT$D macro, 3-13
OPNTSW macro, file processing,
3-12
Owner 10 field
tape, G-2
.PARSE routine
device and unit translation,
4-11
logical name translation, 4-10
Parser program
TPARS, 7-12

Parser program
TPARS (Cont.)
processing steps, 7-14
Parsing
command line, 7-1
complex command lines, 7-19
UFO, 7-14
.POINT routine
file byte position, 2-11
position file to byte, 4-21
.POSIT routine, return record
position, 4-22
Position to next file
tape, 5-5
.POSRC routine, position file to
record, 4-21
.PPASC routine, convert UIC to
ASCII, 4-7
PRINT command, 8-2
.PRINT routine, error handling,
8-2
.PRINT subroutine, 8-1
PRINT$ macro, 8-1
error handling, 8-2
Print, open file on LP:, 8-2
Program example I/O, 0-1
Program section
TPARS, 7-10
.PRSDI routine, fill in directory
information, 4-15
.PRSDV routine, fill in
device/unit information, 4-15
.PRSFN routine, fill in file
name, type, version, 4-15
PUT$ macro, 1-8, 3-1, 3-26
FO.RWM parameter
record I/O, 2-10
FOB, file processing, 3-25
file processing
locate mode, 3-27
write logical record, 3-24
file truncate, 2-11
fixed-length record, 3-26
block boundary, 3-27
block buffer, 3-27
format, 3-24
locate mode, 3-24, 3-28
move mode, 3-24, 3-26
no truncate, 2-10
sequenced record, 3-24
task record buffer, 3-26
variable-length record, 3-26
block boundary, 3-27
PUT$R macro, 3-1
example, 3-29
file processing
write logical record, random
mode, 3-28
random mode
locate mode execution, 3-29
PUT$S macro, 3-1
file processing
write logical record,
sequential mode, 3-30

Index-9

INDEX
QIO execution routine, 4-23
QIO$ directive summary, C-l
QIOMAC.MAC error codes, 1-1
QIOW$ directive summary, C-2
R.FIX
file attribute, 2-5
parameter, fixed-length records,
3-8
R.SEQ
file attribute, 2-6
parameter, sequenced records,
3-8
R. VAR
file attribute, 2-6
parameter, variable-length
records, 3-8
Random access, 2-10
Random access mode, 3-21
Random access mode, record
attribute, 3-9
Random I/O, 2-20
Random mode
PUT$R macro
locate mode execution, 3-29
write logical record, 3-28
RCML$ macro, 6-12
RCST$ directive summary, C-2
RCVD$ directive summary, C-3
RCVX$ directive summary, C-3
.RDFDR routine, read $$FSR2
default directory string, 4-2
.RDFPP routine, read $$FSR2
default file protection word,
4-5
.RDFUI routine, read default UIC,
4-3, 4-4
Read $$FSR2, default directory
string, 4-2
Read access
file open, 2-15
shared, 1-13
Read default UIC, 4-4
Read file owner word, 4-6
Read file protection word
default, 4-5
Read logical record
file processing, 3-19
random mode
file processing, 3-22
sequential mode, 3-24
Read virtual block
file processing, 3-30
READ$ macro, 1-7, 3-1
block access, 2-12
end-of-file, 3-33
example, 3-32
FD.RWM parameter
block I/O, 2-10
FDB, file operation, 3-33
file processing
read virtual block, 3-30
format
file processing, 3-31

READ$ macro (Cont.)
virtual block number, 3-31
Read-ahead file processing, 2-19
Record
fixed-length
PUT$ macro, 3-26
R.FIX parameter, 3-8
sequenced
PUT$ macro, 3-24
R.SEQ parameter, 3-8
. var iable-length, 1-6
PUT$ macro, 3-26
R.VAR parameter, 3-8
Record access initialization,
2-10
Record attribute, 2-6, 3-8
FD.BLK parameter
block boundary crossing, 3-9
FD.CR, 2-6
FD.CR parameter
line-feed character, 3-8
FD.FTN parameter
FORTRAN carriage-control, 3-8
FD.RAN parameter
random access mode, 3-9
FD.RPN parameter
carriage-control word, 3-9
locate mode, 3-9
sequential mode, 3-9
FD.RTN, 2-6
FD.RWM parameter
process with block I/O, 3-9
Record buffer
task
locate mode, 3-27
Record format
tape, 5-4
Record I/O, 2-10
FSR, 2-38
FSRZ
multiple buffering, 2-38
locate mode, FD.PLC parameter,
3-6
macro, 2-10
mode, 1-9
multiple buffering, 1-10
operation, 1-8
random, FD.RAN parameter, 3-6
synchronization, event flag,
2-18
Record size
FDB, 3-9
fixed length, 2-8
largest, 2-8
.REMOVE routine, delete directory
entry, 4-19
.RENAME routine, rename file,
4-23
Rewind
on close or open, 2-16
volume, 5-5
.RFOWN routine, read $$FSR2 file
owner word, 4-6

Index-10

INDEX
$RONLY

Storage map, file header, E-2
Subexpression, parsing complex
command lines, 7-19
Syntax
element, defining, 7-2
state table, 7-7

state~

table, 7-2
Run-time initialization
FSR
FINIT$ macro, 2-40
S.BFHD, FSR block buffer header
siz,e, J-1
S.FATT, FOB file attribute area
siz:e, J-1
S.FDB, FOB size, J-1
S.FNAM, file name size, J-1
S.FNB, filename block size in
bytes, J-1
S.FNBW, filename block size in
words, J-1
S.FNTY, file name and type size,
J-l
S.FSR2, FSR2 (impure area) size,
J-l
S.FTYP, file type size, J-1
S.HDHD, header area size, F-2
S.IDHD, identification area size,
F-~~

S.MPHD, map area size, F-3
S.NFEN, complete file name size,
J-l
SC.MDL, bad data b1bck
user-controlled file
characteristic, F-4
SC.MDL, file marked for delete
user-controlled file
characteristic, F-4
SDAT$ directive summary, C-3
SDRC$ directive summary, C-3
SDRP$ directive summary, C-4
Security information
DELET$ macro, 3-39
Sequenced mode
GET$I, 3-19
Sequential file, 2-10
Sequential mode
FD.INS parameter, 3-6
record attribute, 3-9
write logical record, 3-30
Shared access
file, 1-12
file open, 2-15, 3-12
Single file operation, 5-6
SMSG$ directive summary, C-5
Special character
stab~ table, 7-8
Spooling, 8-1
.PRINT subroutine, 8-1
$STATE program section, 7-2
State table, 7-1
arrangement of syntax types,
7-7
initializing, 7-2
rejecting transitions, 7-18
special character, 7-8
using subexpressions, 7-18
STATE$ macro, 7-1, 7-2
Statistics block, H-1

Tab
ignoring in command line, 7-8
Table Driven Parse
See TPARS
Tape
ANSI file structure, 5-1
control task, G-11
data format, 1-7
end-of-file label, G-9
end-of-vo1ume label, G-8
file processing, 5-4
fixed length records, 1-7
owner 10 field, G-2
position to next file, 5-5
position, file open, 2-16
positioning, G-17
processing example, 5-8
read, indirect command file,
G-19
record format, 5-4
translation, G-17
unlabeled, G-16
block size, G-16
user file label, G-9
user volume label, G-3
variable length record, 1-7
volume access, 5-5
volume label, G-1
Tape file
attributes, specifying, G-17
header block, G-10
header label, G-3
header label (HDR1), G-4
header label (HDR2), G-5
header label (HDR3), G-6
identifier processing, G-7
label, G-1
structure, G-9
Tape handling
end-of-tape, G-10
Tape standard, ANSI, G-1
Task
spooling print job, 8-1
Task buffer descriptor, 3-10
Task record buffer, 3-21
TPARS
built-in variable, 7-5
coding, 7-1, 7-7
command line parsing, 7-1
creating parser program, 7-12
invoking, 7-11
macro, 7-1
options word, 7-11
program section, 7-10
programming examples, 7-14
register usage, 7-11
state table, 7-1

Index-11

INDEX
TPARS (Cont.)
subexpression, 7-7
transition, 7-1
TRAN$ macro, 7-1, 7-3
Transition table
recognition of keyword, 7-9
.TRNCL routine, truncate file,
4-25
UC.CON, contiguous file
user-controlled file
characteristic, F-4
UC.DLK, file improperly closed
user-controlled file
characteristic, F-4
UFO, 5-2
UIC, 5-2
ASCII-binary conversion, 4-6,
4-7
read/write defaults, 4-3, 4-4
Unit information
.PRSDV routine, 4-15
Unit number field, 2-34
Unlabeled tape, G-16
Unlabeled tape block size, G-16
User file attributes
header area
file characteristics, F-4
User File Directory, 5-2
User file label (tape), G-9
User Identification Code
See UIC
User volume label
tape, G-3
Variable-length record
block boundary
PUT$ macro, 3-27
Virtual block
file device, 1-7
file extension, 2-9
Virtual block number
READ$ macro, 3-31
WRITE$ macro, 3-35
Volume
default extend size, 2-9
Volume label
tape, G-l
user, G-3
Volume rewind, 5-5
VRCD$ directive summary, C-5
VRCS$ directive summary, C-5
VRCX$ directive summary, C-6
VSDA$ directive summary, C-6
VSRC$ directive summary, C-6

WAIT$ macro
file processing, 3-1
block I/O completion, 3-37
format
file operations, 3-37
with READ$ and WRITE$, 3-37
with READ$ or WRITE$, 3-30
.WDFPP routine, write $$FSR2
default file protection word,
4-5
.WDFR routine, write $$FSR2
default directory string, 4-3
.WDFUI routine, write default UIC,
4-3, 4-4
.WFOWN routine, write $$FSR2 file
owner word, 4-6
Wild card
file name, 4-18
file type, 4-18
Window pointer
number, 2-16
Write
file owner word, 4-6
Write $$FSR2
default directory string, 4-3
Write access
file open, 2-15
shared, 1-12
Write default UIC, 4-4
Write file protection word
default, 4-5
Write logical record
file processing, 3-24
random mode, 3-28
sequential mode, 3-30
write virtual block
file processing, 3-34
WRITE$ macro, 1-7, 3-1
block access, 2-12
example, 3-36
extending file, 3-36
FD.RWM parameter
block I/O, 2-10
FOB, 3-36
file processing, 3-34
write virtual block, 3-34
format, 3-34
virtual block number, 3-35
Write-behind file processing,
2-19
Write-behind operation, FD.WBH
parameter, 3-11
.XQIO routine, execute QIO, 4-23

Index-12

RSX-llM/M-PLUS and Micro/RSX
I/O Operations Reference Manual
AA-FD14A-TC
READER'S COMMENTS
NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the
company's discretion. If you require a written reply and are eligible to receive one under Software
Performance Report (SPR) service, submit your comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make suggestions for improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent.

[J
LJ
[J
lJ
[]
[J

Name

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify)
____________________________________________ Date _________________________________

Organization
Street
City

State __________ Zip Code
or Country

Do Not Tear - Fold Here and Tape -

IIIII

No Postage
Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

SSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03062-2698

DoNotTear-FoldHere